@bmc-soft/super-app-contracts

Общие контракты (типы, Zod-схемы) между хостом super-app и его мини-приложениями.

Установка

npm install @bmc-soft/super-app-contracts zod

zod >=3.22.0 — обязательная peer-зависимость.

Использование

Валидация модуля мини-приложения

Когда хост загружает бандл мини-приложения (через Module Federation или динамический import), он получает объект с экспортами. Перед использованием нужно проверить, что в модуле есть все обязательные экспорты (SuperAppEntry, контексты, CONTRACT_VERSION и т.д.) и они корректного типа.

import { MiniAppModuleSchemaV1, HOST_CONTRACT_VERSION } from '@bmc-soft/super-app-contracts';

const result = MiniAppModuleSchemaV1.safeParse(loadedModule);

if (!result.success) {
  console.error('Invalid mini-app module:', result.error.issues);
}

Валидация дескриптора мини-приложения (из API)

Дескриптор — это JSON с описанием мини-приложения (id, bundleId, version, name, icon, bundleUrl и т.д.), который приходит с бэкенда. Схема проверяет структуру и типы полей. При успехе возвращается типизированный объект, при ошибке — исключение.

import { MiniAppDescriptorSchemaV1 } from '@bmc-soft/super-app-contracts';

const descriptor = MiniAppDescriptorSchemaV1.parse(apiResponse);
// descriptor полностью типизирован как MiniAppDescriptorV1

Типизация событий между хостом и мини-приложением

import type {
  MiniAppToHostEventMap,
  HostToMiniAppEventMap,
  MiniAppToHostEventType,
  HostToMiniAppEventType,
} from '@bmc-soft/super-app-contracts';

// Отправка типизированного события из мини-приложения в хост
function emitToHost<T extends MiniAppToHostEventType>(
  type: T,
  payload: MiniAppToHostEventMap[T],
) {
  // ...
}

emitToHost('badge_count_changed', { count: 3 });
emitToHost('navigation_requested', { route: '/dashboard' });

Справочник API

Константы

| Имя | Значение | Описание | |-----|----------|----------| | HOST_CONTRACT_VERSION | '1.0' | Текущая версия контракта хоста |

Схемы (Zod)

| Имя | Описание | |-----|----------| | MiniAppDescriptorSchemaV1 | Валидирует дескриптор инстанса мини-приложения, полученный с бэкенда | | MiniAppIconSchemaV1 | Валидирует определение иконки (iconName, svg или svgXml) | | MiniAppModuleSchemaV1 | Валидирует экспорты загруженного бандла мини-приложения |

Типы

| Имя | Описание | |-----|----------| | MiniAppDescriptorV1 | Тип, выведенный из MiniAppDescriptorSchemaV1 | | MiniAppIconV1 | Тип, выведенный из MiniAppIconSchemaV1 | | MiniAppModuleV1 | Тип, выведенный из MiniAppModuleSchemaV1 | | MiniAppToHostEventMap | Карта событий от мини-приложения к хосту | | HostToMiniAppEventMap | Карта событий от хоста к мини-приложениям | | MiniAppToHostEventType | Объединение ключей из MiniAppToHostEventMap | | HostToMiniAppEventType | Объединение ключей из HostToMiniAppEventMap | | MiniAppToHostEventPayload<T> | Тип payload для события мини-приложение → хост | | HostToMiniAppEventPayload<T> | Тип payload для события хост → мини-приложение |

Структура MiniAppDescriptorV1

{
  id: string;              // уникальный ID инстанса, напр. 'wiskey', 'ucrm'
  bundleId: string;        // имя бандла Module Federation
  version: string;         // semver-версия бандла
  name: string;            // отображаемое название
  icon: MiniAppIconV1 | null;
  background?: string;     // цвет фона карточки (hex/rgb)
  textColor?: string;      // цвет текста на карточке (hex/rgb)
  config: Record<string, unknown>;
  bundleUrl: string;       // URL бандла (S3/CDN или localhost в dev)
  forceUpdate?: boolean;
  multiInstance?: {
    enabled: true;
    brandbookKey: string;
  };
}

Обязательные экспорты MiniAppModuleV1

Бандл мини-приложения должен экспортировать следующее для прохождения валидации MiniAppModuleSchemaV1:

| Экспорт | Тип | Обязательный | |---------|-----|--------------| | SuperAppEntry | function | Да | | SuperAppAuthContext | any | Да | | SuperAppConfigContext | any | Да | | SuperAppNavigationRefContext | any | Да | | SuperAppHostContext | any | Нет | | applyBrandbook | function | Нет | | CONTRACT_VERSION | '1.0' | Да | | MIN_HOST_VERSION | string (напр. '1.0') | Нет | | SUPPORTS_MULTI_INSTANCE | boolean | Нет |

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

Пакет следует Semantic Versioning. Несовместимые изменения в типах контрактов приводят к увеличению major версии.

Лицензия

MIT