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

Какой API использовать, зависит от того, где выполняется ваш код.

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

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

Передайте идентификатор, который объявляет ваша интеграция, и тип-параметр для типизированных настроек. Например:

providers/payment-my/services/my-payment.ts
1import { resolveIntegrationOptions } from "@gorgo/medusa-integration"
2import type { MyOptions } from "../../integration-my/services/my-integration"
3
4// внутри любого метода провайдера
5const options = await resolveIntegrationOptions<MyOptions>({
6  identifier: "my"
7})

Возвращённый options типизирован как MyOptions, уже расшифрован и проверен.

Для провайдера, который поддерживает несколько инстансов, передайте instance_id. Обычно это собственный id регистрации вашего провайдера. Опустите его или передайте null для инстанса по умолчанию:

providers/payment-my/services/my-payment.ts
1import { resolveIntegrationOptions } from "@gorgo/medusa-integration"
2import type { MyOptions } from "../../integration-my/services/my-integration"
3
4// внутри любого метода провайдера
5const options = await resolveIntegrationOptions<MyOptions>({
6  identifier: "my",
7  instance_id: this.instanceId_,
8})

this.instanceId_ подходит сюда, потому что базовый класс провайдера сохраняет id своей регистрации ещё в конструкторе; провайдеру без нескольких инстансов instance_id можно вообще не передавать.

По умолчанию хелпер бросает MedusaError, если интеграция не настроена, выключена или не заполнена:

1// бросит исключение, если интеграцией ещё нельзя пользоваться
2const options = await resolveIntegrationOptions<MyOptions>({
3  identifier: "my"
4})

Передайте { optional: true }, чтобы вместо этого получить null и обработать отсутствие настройки самостоятельно:

1const options = await resolveIntegrationOptions<MyOptions>(
2  { identifier: "my" },
3  { optional: true }
4)
5
6if (!options) {
7  // ещё не настроена: пропустите, используйте запасной вариант или верните понятную ошибку
8}

С { optional: true } не настроенная, выключенная или незаполненная интеграция даёт здесь null вместо исключения. Именно от этого случая защищает проверка if (!options) выше.

Когда у вашего кода уже есть контейнер, получите модуль из контейнера и вызовите getResolvedOptions напрямую. Это подходит для API-роутов, подписчиков, запланированных задач и лоадеров, и никакой воркфлоу не задействуется. Например, в API-роуте:

api/admin/my-payment/route.ts
1import { INTEGRATION_MODULE, IntegrationModuleService } from "@gorgo/medusa-integration"
2import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
3
4export async function GET(req: MedusaRequest, res: MedusaResponse) {
5  const integration: IntegrationModuleService = req.scope.resolve(INTEGRATION_MODULE)
6
7  const resolved = await integration.getResolvedOptions("my")
8  if (!resolved) {
9    return res.status(503).send("My is not configured")
10  }
11
12  const options = resolved.options as MyOptions
13  const { provider_id, category, is_enabled } = resolved.meta
14}

getResolvedOptions(identifier, instanceId?) возвращает ResolvedOptions | null. Значение представляет собой { options, meta }, где meta содержит provider_id, category и is_enabled. Результат null означает, что интеграция не настроена, выключена или не заполнена.

Когда вы собираете собственный воркфлоу, используйте экспортируемый шаг вместо хелпера:

workflows/create-my.ts
1import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
2import { getResolvedIntegrationOptionsStep } from "@gorgo/medusa-integration"
3
4export const createMyWorkflow = createWorkflow("create-my", () => {
5  const resolved = getResolvedIntegrationOptionsStep({
6    identifier: "my"
7  })
8  return new WorkflowResponse(resolved)
9})

Также экспортируется getResolvedIntegrationOptionsWorkflow. Именно его хелпер запускает внутри себя.

Итоговые параметры не совпадают с сырыми хранимыми значениями. При каждом их получении модуль делает три вещи:

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

Если интеграция не настроена, выключена или не заполнена, она даёт null. В этом случае хелпер бросает исключение или возвращает null при { optional: true }. Частичные черновики никогда не доходят до работающего приложения.

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