0
# Medusa Interfaces
1

2
Medusa Interfaces provides core interface definitions for the Medusa e-commerce framework. These abstract base classes define the contract for implementing custom services within the Medusa ecosystem, including payment processing, fulfillment operations, file handling, notifications, search functionality, and OAuth authentication.
3

4
**Note**: All interfaces in this package are deprecated in favor of newer abstract classes from @medusajs/medusa and @medusajs/utils. They remain available for backward compatibility.
5

6
## Package Information
7

8
- **Package Name**: medusa-interfaces
9
- **Package Type**: npm
10
- **Language**: JavaScript (ES6)
11
- **Installation**: `npm install medusa-interfaces`
12

13
## Core Imports
14

15
```javascript
16
import { 
17
  BaseService, 
18
  PaymentService, 
19
  FulfillmentService, 
20
  FileService, 
21
  NotificationService, 
22
  OauthService, 
23
  SearchService 
24
} from "medusa-interfaces";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const { 
31
  BaseService, 
32
  PaymentService, 
33
  FulfillmentService 
34
} = require("medusa-interfaces");
35
```
36

37
Individual imports:
38

39
```javascript
40
import BaseService from "medusa-interfaces/dist/base-service";
41
import PaymentService from "medusa-interfaces/dist/payment-service";
42
```
43

44
## Basic Usage
45

46
```javascript
47
import { PaymentService } from "medusa-interfaces";
48

49
// Extend the PaymentService interface
50
class StripePaymentService extends PaymentService {
51
  static identifier = "stripe";
52

53
  async createPayment(cart) {
54
    // Implementation for creating a payment
55
    return { id: "payment_123", status: "pending" };
56
  }
57

58
  async authorizePayment(paymentData) {
59
    // Implementation for authorizing payment
60
    return { status: "authorized", transaction_id: "txn_456" };
61
  }
62

63
  // ... implement other required methods
64
}
65
```
66

67
## Architecture
68

69
Medusa Interfaces follows a consistent inheritance pattern:
70

71
- **BaseService**: Foundation class providing transaction management, query building, validation utilities, and decorator pattern support
72
- **Service Interfaces**: Abstract classes extending BaseService that define specific service contracts
73
- **Static Identifiers**: Each service interface includes static methods for type checking and identification
74
- **Decorator Pattern**: Built-in support for adding decorators to extend service functionality
75

76
## Capabilities  
77

78
### Base Service Foundation
79

80
Core service functionality providing transaction management, query building, validation, and decorator pattern support. All other service interfaces extend this base class.
81

82
```javascript { .api }
83
class BaseService {
84
  constructor();
85
  withTransaction(): this;
86
  buildQuery_(selector: object, config?: object): object;
87
  validateId_(rawId: string, config?: object): string;
88
  atomicPhase_(work: function, isolationOrErrorHandler?: string|function, maybeErrorHandlerOrDontFail?: function|boolean): Promise<any>;
89
  setMetadata_(obj: object, metadata: object): Promise<object>;
90
  addDecorator(fn: function): void;
91
  runDecorators_(obj: object, fields?: array, expandFields?: array): Promise<object>;
92
  shouldRetryTransaction(err: object): boolean;
93
}
94
```
95

96
[Base Service](./base-service.md)
97

98
### Payment Processing
99

100
Interface for payment service implementations, providing methods for creating, authorizing, capturing, and refunding payments through various payment gateways.
101

102
```javascript { .api }
103
class PaymentService extends BaseService {
104
  static isPaymentService(obj: object): boolean;
105
  getIdentifier(): string;
106
  createPayment(cart: object): Promise<object>;
107
  retrievePayment(cart: object): Promise<object>;
108
  updatePayment(cart: object): Promise<object>;
109
  getStatus(): any;
110
  authorizePayment(): any;
111
  capturePayment(): any;
112
  refundPayment(): any;
113
  deletePayment(): any;
114
  retrieveSavedMethods(customer: object): Promise<array>;
115
}
116
```
117

118
[Payment Service](./payment-service.md)
119

120
### Fulfillment Operations  
121

122
Interface for fulfillment service implementations, managing shipping options, fulfillment processing, returns, and document generation for logistics operations.
123

124
```javascript { .api }
125
class FulfillmentService extends BaseService {
126
  static isFulfillmentService(obj: object): boolean;
127
  getIdentifier(): string;
128
  getFulfillmentOptions(): any;
129
  validateFulfillmentData(optionData: object, data: object, cart?: object): object;
130
  validateOption(data: object): any;
131
  canCalculate(data: object): any;
132
  calculatePrice(optionData: object, data: object, cart: object): any;
133
  createFulfillment(data: object, items: array, order: object, fulfillment: object): any;
134
  cancelFulfillment(fulfillment: object): any;
135
  createReturn(fromData: object): any;
136
  getFulfillmentDocuments(data: object): array;
137
  getReturnDocuments(data: object): array;
138
  getShipmentDocuments(data: object): array;
139
  retrieveDocuments(fulfillmentData: object, documentType: string): any;
140
}
141
```
142

143
[Fulfillment Service](./fulfillment-service.md)
144

145
### File Storage
146

147
Interface for file storage service implementations, providing upload and delete operations for handling file assets across different storage providers.
148

149
```javascript { .api }
150
class FileService extends BaseService {
151
  static isFileService(obj: object): boolean;
152
  upload(): any;
153
  delete(): any;
154
}
155
```
156

157
[File Service](./file-service.md)
158

159
### Notification Services
160

161
Interface for notification service implementations, enabling sending and resending notifications through various channels like email, SMS, or push notifications.
162

163
```javascript { .api }
164
class NotificationService extends BaseService {
165
  static isNotificationService(obj: object): boolean;
166
  getIdentifier(): string;
167
  sendNotification(event: string, data: object): any;
168
  resendNotification(notification: object, config?: object): any;
169
}
170
```
171

172
[Notification Service](./notification-service.md)
173

174
### OAuth Authentication
175

176
Interface for OAuth service implementations, providing token generation, refresh, and destruction operations for OAuth-based authentication flows.
177

178
```javascript { .api }
179
class OauthService extends BaseService {
180
  static isOauthService(obj: object): boolean;
181
  generateToken(): any;
182
  refreshToken(): any;
183
  destroyToken(): any;
184
}
185
```
186

187
[OAuth Service](./oauth-service.md)
188

189
### Search Operations
190

191
Interface for search service implementations, providing full-text search capabilities including index management, document operations, and search queries across different search engines.
192

193
```javascript { .api }
194
class SearchService extends BaseService {
195
  static isSearchService(obj: object): boolean;
196
  get options(): object;
197
  createIndex(indexName: string, options?: object): Promise<object>;
198
  getIndex(indexName: string): Promise<object>;
199
  addDocuments(indexName: string, documents: array, type: string): Promise<object>;
200
  replaceDocuments(indexName: string, documents: array, type: string): Promise<object>;
201
  deleteDocument(indexName: string, document_id: string): Promise<object>;
202
  deleteAllDocuments(indexName: string): Promise<object>;
203
  search(indexName: string, query: string, options?: object): Promise<object>;
204
  updateSettings(indexName: string, settings: object): Promise<object>;
205
}
206
```
207

208
[Search Service](./search-service.md)
209

210
## Migration Notes
211

212
All interfaces are deprecated. Use these replacements instead:
213

214
- `BaseService` → `TransactionBaseService` from @medusajs/medusa  
215
- `PaymentService` → `AbstractPaymentProcessor` from @medusajs/medusa
216
- `FulfillmentService` → `AbstractFulfillmentService` from @medusajs/medusa
217
- `FileService` → `AbstractFileService` from @medusajs/medusa
218
- `NotificationService` → `AbstractNotificationService` from @medusajs/medusa
219
- `SearchService` → `AbstractSearchService` from @medusajs/utils