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

Модуль интеграций можно применять в самых разных сценариях. Он не зависит от типа провайдера, и ему всё равно, для чего нужны параметры.

• Любой тип провайдера: Платежи, доставка, уведомления, аналитика, авторизация и другие.
• Плагины: Добавляйте плагину настраиваемые параметры, не разрабатывая UI и слой данных.
• Собственные модули и расширения: Любой модуль Medusa, которому нужны настраиваемые параметры в Admin, например API-ключи, режимы или feature-флаги.

Если администратор магазина должен уметь управлять настройкой, её можно сделать через Модуль интеграций.

В интеграции участвуют две роли разработчика, а между ними находится администратор магазина.

• Провайдер интеграций: Объявляет интеграцию. Описывает параметры, их группировку и валидацию, а также необязательную проверку соединения. Провайдером интеграций может быть любой плагин, провайдер или собственный модуль, и всё это он объявляет в одном дескрипторе.
• Администратор магазина: Настраивает в Admin эти параметры, например учётные данные, режимы или вебхуки.
• Потребитель: Читает параметры инстанса интеграции во время выполнения.

Провайдер и потребитель обычно живут в одном пакете. Платёжный плагин объявляет свои учётные данные, затем считывает их обратно в своей платёжной логике. Потребителем может быть и посторонний код, например API-роут, подписчик или запланированная задача, которым нужны параметры настроенной интеграции.

Дескриптор представляет собой единое объявление метаданных интеграции, её параметров, секций настроек, валидации и необязательной проверки соединения. Создаётся он через defineIntegration.

Вот дескриптор платёжного провайдера с двумя параметрами и одной секцией:

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

Дескриптор служит единым источником истины для интеграции: в этом примере он объявляет apiKey и sandbox, сгруппированные в одну секцию credentials. По нему модуль генерирует CRUD API, валидирует запись, отрисовывает UI настроек и определяет, что потребители получают во время выполнения. Вам не нужно писать ни модели данных, ни API-роуты, ни UI-формы.

Полный справочник по каждому полю параметра, по типу, а также по валидации, секретам и проверке соединения смотрите в разделе Дескриптор провайдера интеграций.

Инстанс представляет собой отдельную регистрацию провайдера интеграций с собственной конфигурацией. Один и тот же провайдер можно зарегистрировать несколько раз, и каждая регистрация даёт самостоятельный инстанс со своими настройками в Admin.

Каждый инстанс интеграции адресуется по provider_id вида:

int_<identifier>[_<instanceId>]

В <identifier> подставляется static identifier провайдера, общий для всех его инстансов. <instanceId> берётся из id конкретной регистрации и присутствует только у именованных инстансов.

У каждой интеграции есть стабильный идентификатор, например my, заданный как static identifier в провайдере:

providers/integration-my/services/my-integration.ts
1import { defineIntegration, AbstractIntegrationProvider } from "@gorgo/medusa-integration"
2
3// ...
4
5export class MyIntegration extends AbstractIntegrationProvider {
6  static identifier = "my"
7
8  // ...
9}

Все инстансы провайдера используют общий static identifier. Он всегда my. Различает инстансы только instanceId в provider_id.

Это вариант по умолчанию. У него нет ID инстанса (instanceId), поэтому его provider_id выглядит, например, как int_my.

Зарегистрируйте его без id:

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

Без id в записи регистрации провайдер получает единственный, безымянный инстанс с ключом int_my.

Зарегистрируйте один и тот же провайдер несколько раз, каждый со своим id. Каждый инстанс настраивается независимо, например для поддержки нескольких аккаунтов интегрируемого сервиса.

Например, две независимые регистрации одного и того же провайдера:

medusa-config.ts
1module.exports = defineConfig({
2  // ...
3  plugins: [
4    {
5      resolve: "@gorgo/medusa-integration",
6      options: {
7        // ...
8        providers: [
9          {
10            resolve: "@gorgo/medusa-payment-my/providers/integration-my",
11            id: "eu",
12            options: {},
13          },
14          {
15            resolve: "@gorgo/medusa-payment-my/providers/integration-my",
16            id: "us",
17            options: {},
18          },
19        ],
20      },
21    },
22  ],
23})

Это даст int_my_eu и int_my_us соответственно. id задаётся на верхнем уровне записи. Если случайно поместить его внутрь options, провайдер зарегистрируется под инстансом по умолчанию (безымянным) без предупреждения.

Потребитель получает параметры по идентификатору и инстансу, поэтому один и тот же код может обращаться к нужному.

Параметры интеграции движутся по предсказуемому пути. Автор объявляет их в дескрипторе, администратор настраивает, модуль валидирует, они становятся активными, как только интеграция включена и заполнена, а потребитель получает их во время выполнения. По пути проверка соединения может сверить их со сторонним сервисом.

Полный справочник по каждому полю параметра, по типу, а также по валидации, секретам и проверке соединения смотрите в разделе Дескриптор провайдера интеграций.

Модуль генерирует UI интеграции из её дескриптора, поэтому строить страницы не нужно.

Параметры группируются в секции настроек и отрисовываются через LayoutComposer Medusa в виде карточек с изменяемым порядком, в одну или две колонки.

Когда сгенерированного UI недостаточно, вы можете построить для своих параметров любой интерфейс на собственных admin-виджетах. Это обычные admin-виджеты Medusa на том же механизме defineWidgetConfig и зон внедрения, что вы уже используете в других местах, так что учить ничего нового не придётся. Модуль предоставляет зоны внедрения на странице каждой интеграции (например, gorgo.integration.<identifier>.main.after), и виджет, нацеленный на такую зону, получает готовый providerId и напрямую читает и пишет параметры интеграции.

Метки, подсказки и заголовки в дескрипторе задаются как i18n-ключи. Поставляйте переводы вместе со своей интеграцией, и UI настроек локализуется автоматически.

Всё это построено на стандартном i18n Medusa, так что учить ничего нового не нужно. Регистрируйте переводы привычным способом, и ключи подставляются по активному языку Admin с откатом на английский, если ключ отсутствует. Собственные виджеты локализуются так же, используя тот же каталог сообщений, что и сгенерированная форма.