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

Модуль проверяет параметры в два момента, и каждый раз в разном объёме:

• При сохранении. Когда администратор магазина сохраняет секцию или ваш код отправляет значения параметров, модуль проверяет только отправленные параметры. Их правила он применяет к сохранённой конфигурации, поверх которой наложены отправленные значения, без значений по умолчанию из дескриптора. Поэтому правило может читать параметры из других секций. Если правило не проходит, сохранение отклоняется и ничего не записывается.
• Полная валидация. Модуль проверяет всю собранную конфигурацию с подставленными значениями по умолчанию: все правила каждого параметра и общее правило дескриптора. От результата зависит, считается ли интеграция полностью настроенной. Полная валидация выполняется каждый раз, когда потребитель получает параметры и когда Admin показывает статус интеграции. Сохранение она никогда не блокирует.

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

Схема показывает оба прохода рядом и то, где рядом с ними стоит проверка соединения:

При сохранении каждый отправленный параметр проходит встроенное правило, а затем собственный validate, и любая проблема отклоняет сохранение с ошибкой 400. Полная валидация разбирает всю конфигурацию целиком и решает, завершена ли интеграция, но сохранение она не блокирует. Проверка соединения не относится ни к одному из проходов. Администратор магазина запускает её отдельным действием, и она вызывает testConnection дескриптора только с параметрами, которые удалось получить, то есть для включённой и полностью настроенной интеграции. Как её написать, читайте в руководстве Как создать провайдер Модуля интеграций.

---

У каждого типа параметра (type) есть свои правила, например формат URL для url или допустимые значения values для enum. Поля конкретного типа добавляют новые, например minLength и pattern для string или min, max и int для number. Все они перечислены в разделе Дополнительные поля по типу параметра.

required: true отклоняет параметр без значения. Для всех типов, кроме string и json, значением не считается пустая строка, а для всех типов ещё и null. Параметр с default никогда не нарушает required, потому что пропуск заполняет значение по умолчанию.

Форма в Admin тоже отмечает обязательные поля и не отправляет их пустыми. Исключение составляет секрет, у которого уже есть сохранённое значение: пустое поле оставляет его как есть.

Для параметра типа string правило про пустую строку не действует, потому что пустая строка для него значение. На сервере одного required: true достаточно, чтобы принять "", и интеграция считается полностью настроенной с пустым полем. Форма в Admin не даст отправить пустое обязательное поле, а запрос к API Admin или виджет даст. Добавьте обязательному параметру string значение minLength: 1, чтобы отклонять такие значения, как это делает провайдер ЮKassa для своих shopId и secretKey.

---

Если встроенных правил параметра недостаточно, добавьте ему функцию validate. Она получает значение параметра и контекст с двумя полями:

• options – конфигурация, по которой проверяется правило, с соседними параметрами из всех секций. При сохранении это сохранённые значения с наложенными поверх отправленными, без значений по умолчанию из дескриптора. При полной валидации это вся конфигурация после подстановки значений по умолчанию;
• addIssue({ message, path? }) – сообщает о проблеме. Без path проблема относится к самому параметру.

Например, код ставки НДС обязателен, только пока включены чеки:

providers/integration-my/services/my-integration.ts
1import { defineIntegration } from "@gorgo/medusa-integration"
2import type { OptionValidateContext } from "@gorgo/medusa-integration"
3
4const requiredWhenReceipt = (value: number | undefined, ctx: OptionValidateContext) => {
5  if (ctx.options.useReceipt && value == null) {
6    ctx.addIssue({ message: "Required when receipts are enabled" })
7  }
8}
9
10const descriptor = defineIntegration({
11  category: "payment",
12  displayName: "my.name",
13  options: {
14    apiKey: {
15      type: "string",
16      control: "secret",
17      secret: true,
18      required: true,
19      minLength: 1,
20      label: "my.apiKey"
21    },
22    useReceipt: {
23      type: "boolean",
24      default: false,
25      label: "my.useReceipt"
26    },
27    vatCode: {
28      type: "enum",
29      values: [1, 2, 3, 4, 5, 6],
30      label: "my.vatCode",
31      visibleWhen: { field: "useReceipt", equals: true },
32      validate: requiredWhenReceipt,
33    },
34  },
35  sections: [
36    {
37      id: "credentials",
38      title: "my.credentials",
39      options: ["apiKey"]
40    },
41    {
42      id: "receipts",
43      title: "my.receipts",
44      options: ["useReceipt", "vatCode"]
45    },
46  ],
47})

vatCode не помечен required, поэтому магазину, который не отправляет чеки, заполнять его не нужно. visibleWhen только прячет поле в Admin, пока useReceipt выключен, а обязательным его делает requiredWhenReceipt. Правило читает useReceipt из ctx.options. Это конфигурация с наложенными отправленными значениями, поэтому правило видит переключатель независимо от того, сохраняется ли он вместе с vatCode.

Условное поле проверяйте в validate и не сочетайте required: true с visibleWhen. Поле, скрытое через visibleWhen, всё равно отправляется и проверяется, потому что форма в Admin подставляет и отправляет все поля своей секции. Скрытый параметр типа number, enum, url, email или uuid без default уходит пустым, не проходит required, и модуль отклоняет сохранение, пока поле скрыто.

---

Правило, которое сравнивает несколько параметров и не относится ни к одному из них, задаётся в собственном validate дескриптора. Оно получает всю собранную конфигурацию и addIssue, который через path может указать на любой параметр:

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})

Это правило выполняется только при полной валидации. Секция с mode сохранится в любом случае, а интеграция останется в статусе Не завершено, пока правило сообщает о проблеме. Если правило на самом деле касается одного параметра, задайте его в validate этого параметра, чтобы администратор магазина узнал о проблеме при сохранении.

---

Сохранение, которое не прошло валидацию, возвращает ошибку 400, и Admin показывает её сообщение в уведомлении. В сообщении каждая проблема записана как <идентификатор параметра>: <сообщение>, например vatCode: Required when receipts are enabled.

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

---

@gorgo/medusa-integration экспортирует полную валидацию самого модуля, поэтому unit-тест может проверить дескриптор без запущенного приложения Medusa:

• collectValidationIssues(descriptor, config) возвращает все проблемы в виде { path, message } и пустой массив для полной конфигурации;
• isDescriptorComplete(descriptor, config) возвращает true, если проблем нет.

Например, тест для дескриптора выше:

providers/integration-my/__tests__/descriptor.unit.spec.ts
1import { collectValidationIssues } from "@gorgo/medusa-integration"
2import MyIntegrationProvider from "../services/my-integration"
3
4const descriptor = new MyIntegrationProvider().descriptor
5
6describe("my integration descriptor", () => {
7  it("requires a VAT code once receipts are on", () => {
8    expect(
9      collectValidationIssues(descriptor, { apiKey: "key", useReceipt: true })
10    ).toEqual([
11      { path: "vatCode", message: "Required when receipts are enabled" },
12    ])
13  })
14})

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