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

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

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

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

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

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

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

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

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

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

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

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

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

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

api/admin/acme-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("acme")
8  if (!resolved) {
9    return res.status(503).send("Acme is not configured")
10  }
11
12  const options = resolved.options as AcmeOptions
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-acme.ts
1import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
2import { getResolvedIntegrationOptionsStep } from "@gorgo/medusa-integration"
3
4export const createAcmeWorkflow = createWorkflow("create-acme", () => {
5  const resolved = getResolvedIntegrationOptionsStep({
6    identifier: "acme"
7  })
8  return new WorkflowResponse(resolved)
9})

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

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

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

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

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

• Основные концепции
• Перенос провайдера на модуль интеграций