or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

base-service.mdfile-service.mdfulfillment-service.mdindex.mdnotification-service.mdoauth-service.mdpayment-service.mdsearch-service.md
tile.json

tessl/npm-medusa-interfaces

Core interfaces for Medusa e-commerce framework service implementations

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/medusa-interfaces@1.3.x

To install, run

npx @tessl/cli install tessl/npm-medusa-interfaces@1.3.0

index.mddocs/

Medusa Interfaces

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.

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.

Package Information

  • Package Name: medusa-interfaces
  • Package Type: npm
  • Language: JavaScript (ES6)
  • Installation: npm install medusa-interfaces

Core Imports

import { 
  BaseService, 
  PaymentService, 
  FulfillmentService, 
  FileService, 
  NotificationService, 
  OauthService, 
  SearchService 
} from "medusa-interfaces";

For CommonJS:

const { 
  BaseService, 
  PaymentService, 
  FulfillmentService 
} = require("medusa-interfaces");

Individual imports:

import BaseService from "medusa-interfaces/dist/base-service";
import PaymentService from "medusa-interfaces/dist/payment-service";

Basic Usage

import { PaymentService } from "medusa-interfaces";

// Extend the PaymentService interface
class StripePaymentService extends PaymentService {
  static identifier = "stripe";

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

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

  // ... implement other required methods
}

Architecture

Medusa Interfaces follows a consistent inheritance pattern:

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

Capabilities

Base Service Foundation

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

class BaseService {
  constructor();
  withTransaction(): this;
  buildQuery_(selector: object, config?: object): object;
  validateId_(rawId: string, config?: object): string;
  atomicPhase_(work: function, isolationOrErrorHandler?: string|function, maybeErrorHandlerOrDontFail?: function|boolean): Promise<any>;
  setMetadata_(obj: object, metadata: object): Promise<object>;
  addDecorator(fn: function): void;
  runDecorators_(obj: object, fields?: array, expandFields?: array): Promise<object>;
  shouldRetryTransaction(err: object): boolean;
}

Base Service

Payment Processing

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

class PaymentService extends BaseService {
  static isPaymentService(obj: object): boolean;
  getIdentifier(): string;
  createPayment(cart: object): Promise<object>;
  retrievePayment(cart: object): Promise<object>;
  updatePayment(cart: object): Promise<object>;
  getStatus(): any;
  authorizePayment(): any;
  capturePayment(): any;
  refundPayment(): any;
  deletePayment(): any;
  retrieveSavedMethods(customer: object): Promise<array>;
}

Payment Service

Fulfillment Operations

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

class FulfillmentService extends BaseService {
  static isFulfillmentService(obj: object): boolean;
  getIdentifier(): string;
  getFulfillmentOptions(): any;
  validateFulfillmentData(optionData: object, data: object, cart?: object): object;
  validateOption(data: object): any;
  canCalculate(data: object): any;
  calculatePrice(optionData: object, data: object, cart: object): any;
  createFulfillment(data: object, items: array, order: object, fulfillment: object): any;
  cancelFulfillment(fulfillment: object): any;
  createReturn(fromData: object): any;
  getFulfillmentDocuments(data: object): array;
  getReturnDocuments(data: object): array;
  getShipmentDocuments(data: object): array;
  retrieveDocuments(fulfillmentData: object, documentType: string): any;
}

Fulfillment Service

File Storage

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

class FileService extends BaseService {
  static isFileService(obj: object): boolean;
  upload(): any;
  delete(): any;
}

File Service

Notification Services

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

class NotificationService extends BaseService {
  static isNotificationService(obj: object): boolean;
  getIdentifier(): string;
  sendNotification(event: string, data: object): any;
  resendNotification(notification: object, config?: object): any;
}

Notification Service

OAuth Authentication

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

class OauthService extends BaseService {
  static isOauthService(obj: object): boolean;
  generateToken(): any;
  refreshToken(): any;
  destroyToken(): any;
}

OAuth Service

Search Operations

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

class SearchService extends BaseService {
  static isSearchService(obj: object): boolean;
  get options(): object;
  createIndex(indexName: string, options?: object): Promise<object>;
  getIndex(indexName: string): Promise<object>;
  addDocuments(indexName: string, documents: array, type: string): Promise<object>;
  replaceDocuments(indexName: string, documents: array, type: string): Promise<object>;
  deleteDocument(indexName: string, document_id: string): Promise<object>;
  deleteAllDocuments(indexName: string): Promise<object>;
  search(indexName: string, query: string, options?: object): Promise<object>;
  updateSettings(indexName: string, settings: object): Promise<object>;
}

Search Service

Migration Notes

All interfaces are deprecated. Use these replacements instead:

  • BaseService → TransactionBaseService from @medusajs/medusa
  • PaymentService → AbstractPaymentProcessor from @medusajs/medusa
  • FulfillmentService → AbstractFulfillmentService from @medusajs/medusa
  • FileService → AbstractFileService from @medusajs/medusa
  • NotificationService → AbstractNotificationService from @medusajs/medusa
  • SearchService → AbstractSearchService from @medusajs/utils