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

Создайте дескриптор через defineIntegration. Он собирает из каталога options схему optionsSchema, которая используется для z.infer, значений по умолчанию и полной валидации.

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. defineIntegration сразу выбрасывает ошибку при загрузке в двух случаях: если секция ссылается на id параметра, которого нет в options, и если values параметра типа enum смешивает строки и числа.

Каждый параметр в options представляет собой объект вида { type, ... }. Поле type определяет доступные значения и остальные поля, общие для всех типов:

У некоторых типов есть свои поля сверх общих:

• string: minLength, maxLength, pattern
• url: protocols
• number: min, max, int, positive, nonnegative, multipleOf
• enum: values, valueLabels

Модуль генерирует CRUD API из дескриптора и валидирует каждую запись. Валидация покрывает правила на уровне отдельного параметра (типы, диапазоны, паттерны) вместе с правилами между секциями, охватывающими всю конфигурацию. Ничего писать под каждую интеграцию не нужно.

Правила между секциями объявляются через validate дескриптора. В отличие от validate отдельного параметра, он получает всю собранную конфигурацию и может пометить проблемой любое поле:

providers/integration-my/services/my-integration.ts
1const descriptor = defineIntegration({
2  // ...
3  validate: (full, { addIssue }) => {
4    if (full.mode === "webhook" && !full.webhookSecret) {
5      addIssue({ path: ["webhookSecret"], message: "Required when mode is \"webhook\"" })
6    }
7  },
8})

В отличие от required или validate конкретного параметра, это правило запускается только при полной валидации (проверке готовности интеграции к включению), а не при сохранении отдельной секции.

Параметры становятся активными, только когда интеграция и включена, и заполнена, то есть проходит полную валидацию. Незавершённый черновик или выключенная интеграция никогда не отдают параметры, поэтому недоделанная конфигурация не может попасть в работающее приложение.

Параметры с пометкой secret шифруются при хранении алгоритмом AES-256-GCM и никогда не попадают в браузер. CRUD API маскирует их и сообщает лишь, задано значение или нет. Сохранение секрета пустым оставляет прежнее хранимое значение, а не стирает его.

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

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

Добавьте testConnection в дескриптор. Он получает уже итоговые (расшифрованные) параметры и возвращает статус:

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    if (!res.ok) {
9      return { status: "failed", message: `My responded with ${res.status}` }
10    }
11
12    return { status: "passed" }
13  },
14})

status принимает одно из значений: passed, failed или skipped; необязательное message отображается в Admin рядом с результатом проверки.

Потребители читают типизированные, проверенные и расшифрованные параметры с применёнными значениями по умолчанию из дескриптора. Незаполненная или выключенная интеграция возвращает пустой результат, а не частичные данные. Итоговые параметры кэшируются ненадолго и обновляются при каждом изменении конфигурации.