В этом руководстве вы узнаете, как добавить на страницу интеграции в Medusa Admin собственную секцию на виджете.

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

Собственная секция строится как обычный admin-виджет Medusa на defineWidgetConfig. Модуль отрисовывает его на странице интеграции рядом со сгенерированными секциями, и администратор магазина может перемещать его, как любую другую секцию.

Схема показывает, как страница, LayoutComposer из Medusa, ваш виджет и API Admin участвуют в работе, от загрузки страницы до сохранения параметра виджета:

Страница загружает интеграцию, затем отрисовывает composer с префиксом зоны gorgo.integration.<identifier> и данными своих секций. Composer ставит ваш виджет в зону, для которой он зарегистрирован, и передаёт ему data. Когда виджет сохраняет параметр, он отправляет { values } в тот же API-роут Admin, из которого читает страница, а модуль проверяет значения и записывает изменение с автором запроса. В шагах ниже вы построите каждую часть этой схемы.

---

Провайдер доставки ApiShip хранит подключения служб доставки в параметре типа json и редактирует их в собственном виджете src/admin/widgets/apiship-integration-main.tsx. В шагах ниже вы построите такой же виджет, только проще, со списком адресов вебхуков.

---

Объявите в дескрипторе параметр, которым управляет виджет, и не включайте его в sections, чтобы его не показывала ни одна сгенерированная секция:

providers/integration-my/services/my-integration.ts
1const descriptor = defineIntegration({
2  // ...
3  options: {
4    // ...
5    webhooks: {
6      type: "json",
7      default: [],
8      label: "my.webhooks.title",
9      validate: (value, { addIssue }) => {
10        if (!Array.isArray(value) || !value.every((url) => typeof url === "string")) {
11          addIssue({ message: "Expected a list of URLs" })
12        }
13      },
14    },
15  },
16})

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

---

На странице интеграции модуль предоставляет две зоны внедрения, названные по static identifier провайдера:

• gorgo.integration.<identifier> – основная колонка;
• gorgo.integration.<identifier>.side – боковая колонка, которая отрисовывается, только если дескриптор задаёт preferredLayoutId: "core:two-column".

Medusa собирает виджет и в собственной зоне, но типы defineWidgetConfig знают только её зоны. Объявите свои, дополнив InjectionZoneRegistry в файле index.d.ts в корне плагина:

index.d.ts
1export {}
2
3declare module "@medusajs/admin-shared" {
4  interface InjectionZoneRegistry {
5    "gorgo.integration.my": true,
6    "gorgo.integration.my.side": true
7  }
8}

Затем опубликуйте этот файл вместе с плагином и укажите его как типы плагина в package.json:

package.json
1{
2  "files": [
3    ".medusa/server",
4    "index.d.ts"
5  ],
6  "exports": {
7    ".": {
8      "types": "./index.d.ts"
9    }
10  }
11}

Остальные записи exports оставьте как есть. Так объявление попадёт в проекты, которые установят ваш плагин. TypeScript-проект самой Admin по умолчанию включает только src/admin, поэтому файл в корне плагина он пока не видит. Добавьте объявление в его include в файле src/admin/tsconfig.json:

src/admin/tsconfig.json
1{
2  "include": [".", "../../index.d.ts"]
3}

Остальную часть файла, например compilerOptions, оставьте как есть. После этого defineWidgetConfig примет "gorgo.integration.my", а проект, который установит ваш плагин, увидит те же зоны. Полный список зон смотрите в справочнике Зоны виджетов в Admin.

---

Создайте виджет в директории src/admin/widgets плагина. Он читает и записывает параметр через API-роуты Admin самого модуля:

src/admin/widgets/my-integration-webhooks.tsx
1import { defineWidgetConfig } from "@medusajs/admin-sdk"
2import { Button, Container, Heading, Input, Text, toast } from "@medusajs/ui"
3import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
4import { useState } from "react"
5import { useTranslation } from "react-i18next"
6import type { IntegrationSectionData } from "@gorgo/medusa-integration"
7import { sdk } from "../lib/sdk"
8
9type IntegrationResponse = { integration: { values: Record<string, unknown> } | null }
10
11const MyWebhooksWidget = ({ data }: { data: IntegrationSectionData }) => {
12  const { t } = useTranslation()
13  const queryClient = useQueryClient()
14  const queryKey = ["my-webhooks", data.providerId]
15  const [url, setUrl] = useState("")
16
17  const { data: stored } = useQuery({
18    queryKey,
19    queryFn: () => sdk.client.fetch<IntegrationResponse>(`/admin/integrations/${data.providerId}`),
20  })
21  const webhooks = (stored?.integration?.values.webhooks as string[] | undefined) ?? []
22
23  const save = useMutation({
24    mutationFn: (next: string[]) =>
25      sdk.client.fetch(`/admin/integrations/${data.providerId}`, {
26        method: "POST",
27        body: { values: { webhooks: next } },
28      }),
29    onSuccess: () => {
30      queryClient.invalidateQueries({ queryKey })
31      setUrl("")
32    },
33    onError: (error: Error) => toast.error(error.message),
34  })
35
36  return (
37    <Container className="divide-y p-0">
38      <div className="px-6 py-4">
39        <Heading level="h2">{t("my.webhooks.title")}</Heading>
40      </div>
41      {webhooks.map((webhook) => (
42        <Text key={webhook} size="small" className="px-6 py-4">
43          {webhook}
44        </Text>
45      ))}
46      <div className="flex gap-x-2 px-6 py-4">
47        <Input value={url} onChange={(event) => setUrl(event.target.value)} />
48        <Button size="small" variant="secondary" onClick={() => save.mutate([...webhooks, url])}>
49          {t("my.webhooks.add")}
50        </Button>
51      </div>
52    </Container>
53  )
54}
55
56export const config = defineWidgetConfig({
57  zone: "gorgo.integration.my",
58})
59
60export default MyWebhooksWidget

Виджет получает от страницы data типа IntegrationSectionData:

• providerId – ключ инстанса, например int_my или int_my_eu. Одна зона обслуживает все инстансы провайдера, поэтому передавайте providerId в каждый запрос.
• identifier – static identifier провайдера.
• values – сохранённые параметры инстанса без секретов.
• isComplete – проходит ли сохранённая конфигурация полную валидацию. Используйте его, чтобы блокировать действия, которым нужны рабочие настройки.

data.values приходит из собственного запроса страницы и не обновляется после сохранения в виджете. То же относится к остальным данным страницы, например к data.isComplete, значку статуса и разделу История изменений. Они показывают состояние до сохранения, пока страница не запросит их снова, потому что сохранение в виджете не сбрасывает запросы страницы. Поэтому виджет хранит свою копию интеграции под своим ключом запроса и обновляет её после каждого сохранения. GET /admin/integrations/:provider_id возвращает актуальный is_complete рядом со значениями, поэтому, если виджету нужна полнота настройки после сохранения, берите её из этой копии.

В запросе POST нет section_id, поэтому модуль записывает ровно те отправленные параметры, которые объявлены в дескрипторе, и отбрасывает остальные ключи. Он проверяет значения, шифрует секреты, отправляет событие integration.updated, которое сбрасывает кэш параметров, и записывает изменение в историю с текущим пользователем Admin в качестве автора.

sdk здесь клиент JS SDK из src/admin/lib/sdk.ts, настроенный так же, как в руководствах Medusa по кастомизации панели администратора.

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