В этом руководстве вы узнаете, как создать провайдер Medusa для управления своими настройками через Модуль интеграций.

При разработке своего провайдера Модуля интеграций бывает полезно посмотреть, как устроен готовый провайдер.

Если вам нужен пример реальной реализации, посмотрите провайдер платежей YooKassa в репозитории Medusa Integrations.

Начните с создания новой директории для вашего провайдера Модуля интеграций. Для плагина она размещается в src/providers, например src/providers/integration-my.

Создайте файл src/providers/integration-my/services/my-integration.ts, который объявляет дескриптор интеграции и сам сервис.

providers/integration-my/services/my-integration.ts
1import {
2  AbstractIntegrationProvider
3} from "@gorgo/medusa-integration"
4
5class MyIntegrationProvider extends AbstractIntegrationProvider {
6  // TODO add methods
7}
8
9export default MyIntegrationProvider

Родительский класс, который вы расширяете здесь, AbstractIntegrationProvider, абстрактный, поэтому подкласс обязан реализовать его свойство descriptor (объявленное через get). Классу также нужен static identifier: на него рассчитывает загрузчик.

Каждый провайдер Модуля интеграций имеет уникальный идентификатор. По нему администратор настраивает провайдер, а потребитель получает его параметры.

providers/integration-my/services/my-integration.ts
1class MyIntegrationProvider extends AbstractIntegrationProvider {
2  static identifier = "my"
3  // ...
4}

Загрузчик читает это статическое поле, чтобы собрать ключ, под которым регистрируется ваш инстанс: int_<identifier>_<id>, либо int_<identifier> без ID.

Класс провайдера обязан реализовать свойство descriptor. Дескриптор содержит единое описание параметров, их группировку в секции настроек и метод проверки соединения (опционально). Создайте его через defineIntegration.

providers/integration-my/services/my-integration.ts
1import {
2  AbstractIntegrationProvider,
3  defineIntegration,
4  z
5} from "@gorgo/medusa-integration"
6
7const descriptor = defineIntegration({
8  category: "payment",
9  displayName: "my.name",
10  options: {
11    apiKey: {
12      type: "string",
13      control: "secret",
14      secret: true,
15      required: true,
16      label: "my.apiKey"
17    },
18    sandbox: {
19      type: "boolean",
20      control: "switch",
21      default: false,
22      label: "my.sandbox"
23    },
24  },
25  sections: [
26    {
27      id: "credentials",
28      title: "my.credentials",
29      options: ["apiKey", "sandbox"]
30    },
31  ],
32})
33
34export type MyOptions = z.infer<typeof descriptor.optionsSchema>
35
36export class MyIntegrationProvider extends AbstractIntegrationProvider {
37  // ...
38  get descriptor() {
39    return descriptor
40  }
41}
42
43export default MyIntegrationProvider

MyOptions описывает итоговый набор параметров: defineIntegration собирает optionsSchema из объекта options, и поскольку у apiKey указан required, а у sandbox задан default, оба поля в MyOptions становятся обязательными.

Как и другие провайдеры Medusa, провайдер Модуля интеграций может объявить статический validateOptions, чтобы проверить свою конфигурацию из medusa-config.ts уже при загрузке приложения.

providers/integration-my/services/my-integration.ts
1class MyIntegrationProvider extends AbstractIntegrationProvider {
2  // ...
3  static validateOptions(options: Record<string, unknown>) {
4    // необязательная fail-fast проверка options.providers[].options
5  }
6}

Собственный validateOptions базового класса ничего не делает ((): void | never {}), поэтому переопределять его не обязательно. Тип возврата void | never показывает, что метод либо ничего не возвращает, либо выбрасывает исключение, чтобы прервать загрузку.

В отличие от validateOptions, который проверяет конфигурацию провайдера в medusa-config.ts, testConnection проверяет сами параметры интеграции (например, API-ключ), обращаясь к стороннему сервису. Администратор запускает эту проверку из Admin, а запланированная задача ежедневно перепроверяет настроенные интеграции. Объявите её прямо в дескрипторе.

providers/integration-my/services/my-integration.ts
1const descriptor = defineIntegration({
2  // ...
3  testConnection: async ({ options }) => {
4    const res = await fetch("https://api.my.com/ping", {
5      headers: { Authorization: `Bearer ${options.apiKey}` },
6    })
7
8    return res.ok
9      ? { status: "passed" }
10      : { status: "failed", message: `My responded with ${res.status}` }
11  },
12})

status принимает одно из значений "passed" | "failed" | "skipped". Возврат { status: "failed", message } считается обычным результатом, а не ошибкой. Если провайдер выбросит исключение, ежедневная задача учтёт его отдельно, как status: "errored".

Создайте файл src/providers/integration-my/index.ts со следующим содержимым:

providers/integration-my/index.ts
1import { ModuleProvider } from "@medusajs/framework/utils"
2import { INTEGRATION_MODULE } from "@gorgo/medusa-integration"
3import MyIntegrationProvider from "./services/my-integration"
4
5export default ModuleProvider(INTEGRATION_MODULE, {
6  services: [MyIntegrationProvider],
7})

Это экспортирует определение провайдера, указывая, что MyIntegrationProvider является его сервисом.

Чтобы использовать провайдер Модуля интеграций, добавьте его в массив providers модуля интеграций в medusa-config.ts:

medusa-config.ts
1module.exports = defineConfig({
2  // ...
3  plugins: [
4    {
5      resolve: "@gorgo/medusa-integration",
6      options: {
7        encryptionKey: process.env.INTEGRATION_ENCRYPTION_KEY,
8        providers: [
9          {
10            resolve: "./src/providers/integration-my",
11            id: "my-1",
12            options: {},
13          },
14        ],
15      },
16    },
17    // ...
18  ],
19})

По этой записи загрузчик создаёт инстанс MyIntegrationProvider.

Далее добавьте секретный ключ шифрования в переменные окружения. Модуль интеграций использует его, чтобы зашифровать секреты перед сохранением в базу данных:

.env
INTEGRATION_ENCRYPTION_KEY=supersecret

Подходит любое непустое значение. Модуль преобразует его через SHA-256 в 32-байтовый ключ AES-256-GCM, поэтому используйте значение с высокой энтропией, например openssl rand -hex 32.

Запустите сервер и откройте Настройки → Интеграции в Medusa Admin. Интеграция появится в списке. Заполните параметры и нажмите Проверить соединение, чтобы вызвать testConnection.

Чтобы прочитать сохранённые параметры, используйте resolveIntegrationOptions, передав тот же identifier, который объявляет ваш класс провайдера:

providers/payment-my/services/my-payment.ts
1import { resolveIntegrationOptions } from "@gorgo/medusa-integration"
2import type { MyOptions } from "../../integration-my/services/my-integration"
3
4const options = await resolveIntegrationOptions<MyOptions>({
5  identifier: "my",
6})

Возвращённые options типизированы как MyOptions, уже расшифрованные и проверенные. По умолчанию вызов выбрасывает MedusaError, если интеграция не настроена, выключена или не заполнена.