SDK интеграций

Пакет @easymb/sdk — единственная поверхность, через которую пишется интеграция. Импортировать внутренние пакеты платформы, код ядра или браузерные глобалы запрещено, и это не соглашение, а правило линтера: такой импорт не пройдёт сборку.

Ограничение осмысленное. Интеграция, залезшая во внутренности, ломается на первом же рефакторинге ядра. SDK — стабильный контракт, который платформа обязуется поддерживать.

Точки входа

Точка входа интеграции

Единственный допустимый экспорт по умолчанию — результат defineIntegration:

import { defineIntegration } from '@easymb/sdk';

export default defineIntegration({
  meta: { alias: 'my-integration' },
  setup(sdk) {
    sdk.ui.registerMenuAction('catalog.products', {
      key: 'my-integration.example',
      label: sdk.i18n.t('menu.example'),
      action: { type: 'modal', modal: 'my-integration.example' },
    });
    sdk.ui.registerModal(
      'my-integration.example',
      () => import('./modals/ExampleModal'),
    );
  },
});

defineIntegration — не просто обёртка для типов. Она проверяет контракт до того, как платформа попытается вызвать setup: алиас должен быть в kebab-case, setup — функцией. Ошибка конвенции всплывает сразу, а не в рантайме у клиента.

В setup не должно быть бизнес-логики. Только регистрация: страницы, модалки, пункты меню, обработчики.

SDK воркера

Фоновый исполнитель получает свой набор:

• commands.register — обработчики команд, которые дёргает платформа;
• storage — key-value хранилище в своём пространстве имён, чужое недоступно;
• api — доменное API ядра через прокси хоста, в пределах объявленных областей;
• proxy — запросы к внешним хостам;
• logger — журналирование.

Прямого доступа к сети и к базе у воркера нет. Всё идёт по протоколу host↔worker, а хост сверяется с манифестом.

Структура интеграции

Интеграция живёт отдельным пакетом в каталоге integrations/:

integrations/my-integration/
  index.ts          точка входа с defineIntegration
  manifest.json     паспорт и границы возможностей
  package.json      зависимость только на @easymb/sdk
  pages/            свои страницы
  modals/           модалки
  workers/          фоновые исполнители
  reports/          формы и показатели для отчётов
  assets/           иконка и картинки

Готовый скелет лежит в integrations/_template/ — новая интеграция начинается с копирования этого каталога и замены алиаса.

Команды

Из корня монорепозитория:

pnpm gen:integrations       # собрать манифесты
pnpm validate:integrations  # проверить все интеграции

Внутри пакета интеграции — pnpm typecheck и pnpm lint.

Версионирование

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

Что дальше

Как устроены возможности, области доступа и установка — в разделе Платформа интеграций.