@mineflow/contracts

@mineflow/contracts — единый источник правды (SSoT) для доменных событий MineFlow: Zod-схемы payload каждого события, реестр всех событий (eventCatalog) и схема общего конверта (eventEnvelopeSchema). Тот же пакет, из которого backend публикует события в outbox/Redis Streams, фронтенд использует для типизации event-нагрузок (интеграционные/backend-консьюмеры).

В слоистой архитектуре SDK (ADR-0042) это shared-пакет уровня контракта: он не делает запросов и не рендерит UI — он описывает форму данных, которые ходят по событийной шине. Для REST-формы данных есть отдельный слой L0 (@mineflow/api-client / @mineflow/api-zod); contracts отвечает строго за события, не за HTTP-ответы.

SSoT — Zod, AsyncAPI — производное

Источник истины — именно Zod-схемы в этом пакете. Документ AsyncAPI 3.1.0 (docs/asyncapi.json) генерируется из eventCatalog + eventEnvelopeSchema через z.toJSONSchema() — это машинно-читаемая проекция контракта, а не параллельный источник. См. функцию buildAsyncApiDocument и ADR-0013.

Установка

pnpm add @mineflow/contracts
# peer-зависимость (используется как обычный import { z } из схем):
pnpm add zod

В монорепо MineFlow пакет резолвится как workspace:*. Рантайм-зависимость у пакета одна — zod.

Импортируй типы, а не рантайм

Схемы (eventCatalog, *Schema) — это runtime-значения Zod. Если фронту нужна только типизация event-нагрузки, импортируй type-символы (EventName, EventDataByName, ShiftReportApproved, …) — это zero-runtime и ничего не тянет в бандл. Полноценные схемы держи на серверной стороне (валидация при publish/consume).

Конверт события (envelope)

Все события MineFlow едут в одном конверте — eventEnvelopeSchema (ADR-0013). Полезная нагрузка лежит в поле data, метаданные — снаружи:

import type { EventEnvelope } from '@mineflow/contracts';

// EventEnvelope:
// {
//   id: string;             // UUID события
//   type: string;           // "<context>.<entity>.<verb-past>", напр. "eam.asset.transferred"
//   version: string;        // "major.minor" схемы data, напр. "1.0"
//   occurredAt: string;     // ISO 8601
//   producedBy: string;     // имя продюсера
//   correlationId?: string; // UUID, опционально
//   causationId?: string;   // UUID, опционально
//   organizationId: string; // владелец события (ADR-0020 multi-tenancy)
//   data: unknown;          // payload — типизируется по type через eventCatalog
// }

data в самом конверте типизирован как unknown намеренно: конкретная форма зависит от type. Сузить её до конкретного события помогает eventCatalog (см. ниже).

organizationId уже на сервере

Поле organizationId есть в каждом событии (ADR-0020), но фронт его не задаёт и не фильтрует руками — multi-tenancy изоляцию делает backend по JWT. На клиенте конверт приходит уже отскоупленным под организацию пользователя.

Каталог событий

eventCatalog — это as const-реестр всех известных событий: ключ — имя события (<context>.<entity>.<verb-past>), значение — { version, schema }. Из него выводятся два полезных типа:

• EventName — объединение всех имён событий ('eam.asset.transferred' | 'prd.shift-report.approved' | …);
• EventDataByName<N> — тип data для конкретного имени (через z.infer его схемы).

import type { EventName, EventDataByName } from '@mineflow/contracts';

type AssetTransferred = EventDataByName<'eam.asset.transferred'>;
// { assetId: string; fromObjectId: string; toObjectId: string; performedBy: string; reason?: string }

type ApprovedData = EventDataByName<'prd.shift-report.approved'>;
// { reportId; organizationId; productionObjectId; shiftDate; shiftType; approvedBy;
//   approvedAt; approveSagaId; actorId; summary: { drilledMeters; blastedBlocks; … } }

type IamProvisioningRequested =
  EventDataByName<'hr.user-account.iam-provisioning-requested'>;
// { userAccountId; personnelId; login; actorId }

Конвенция имён жёсткая: <context>.<entity>.<verb-past> — eam.asset.created, prd.shift-report.rejected-after-approve, scm.fuel.* и т.д. Полный перечень имён — в API-референсе (тип EventName) либо прямо в eventCatalog.

Использование на фронтенде: типизация event-нагрузок

Контракты дают форму data каждого доменного события без догадок — сузив EventEnvelope по type, получаешь точный тип полей:

import type { EventEnvelope, EventName, EventDataByName } from '@mineflow/contracts';

// Узкоспециализированный конверт под конкретное имя события
type TypedEnvelope<N extends EventName> = Omit<EventEnvelope, 'type' | 'data'> & {
  type: N;
  data: EventDataByName<N>;
};

function handle(evt: EventEnvelope): void {
  if (evt.type === 'prd.shift-report.approved') {
    const data = evt.data as EventDataByName<'prd.shift-report.approved'>;
    console.log('утверждён рапорт', data.reportId, data.summary.drilledMeters);
  }
}

Это пригодится, когда фронт/BFF/edge принимает доменные события из интеграционного канала (см. раздел ниже) — форма та же, что у backend-консьюмеров.

Пользовательские уведомления — это не сырые события

Для live-уведомлений в UI не нужно работать с EventEnvelope вручную: их доставляет Centrifugo, а @mineflow/client-react даёт готовые хуки (useRealtimeNotifications / useOnNotification / usePresence) с уже типизированным Notification. Сырые контракты событий нужны для другого — типизации backend/интеграционных консьюмеров доменных событий. Подробности realtime — рецепт «Realtime».

HR local onboarding

hr.user-account.iam-provisioning-requested публикуется retry endpoint-ом POST /hr/user-accounts/{id}/iam-provisioning/retry. Его consumer в IAM worker идемпотентно создаёт или переиспользует local Keycloak user, синхронизирует MineFlow realm roles и пишет JWT-attributes. Фронтенд обычно работает с этим через useRetryIamProvisioning; contracts нужны интеграционным consumer-ам и тестам событий.

Использование: типизация интеграций

Если фронт (или BFF/edge-функция) принимает события из внешнего интеграционного канала, contracts даёт ровно тот же контракт, что и у backend-консьюмеров — без дублирования форм руками. Сузив EventEnvelope по type, можно строить дискриминируемые обработчики:

import type { EventEnvelope, EventDataByName } from '@mineflow/contracts';

function handle(evt: EventEnvelope): void {
  switch (evt.type) {
    case 'eam.asset.created':
      onAssetCreated(evt.data as EventDataByName<'eam.asset.created'>);
      break;
    case 'prd.shift-report.rejected':
      onReportRejected(evt.data as EventDataByName<'prd.shift-report.rejected'>);
      break;
    default:
      // неизвестное/неинтересное событие — игнор
      break;
  }
}

Ключевые экспорты

Экспорт	Тип	Назначение
eventEnvelopeSchema	Zod-схема	Схема конверта всех событий (валидация на сервере)
EventEnvelope	тип	z.infer конверта — форма любого события
makeEnvelope(input)	функция	Сборка конверта (продюсер-сторона; поддерживает детерминированный id через deterministicId → UUIDv5)
eventCatalog	as const объект	Реестр всех событий: { [name]: { version, schema } }
EventName	тип	Объединение всех имён событий
EventDataByName<N>	тип	Тип data для конкретного имени события
defineEvent(entry)	функция	Хелпер-объявление записи каталога с проверкой типов миграций
EventCatalogEntry<T>	тип	Форма одной записи каталога (version / schema / migrations)
migrateEventEnvelope(envelope)	функция	Up-миграция data старого конверта к текущей версии схемы
EventVersionMismatchError	класс	Бросается, когда для старой version нет зарегистрированной миграции (→ DLQ)
buildAsyncApiDocument(options)	функция	Генерация AsyncAPI 3.1.0 из каталога (build-tooling, не для фронта)
AsyncApiDocument	тип	Форма генерируемого AsyncAPI-документа
uuidSchema	Zod-схема	Общий UUID (с .meta) — переиспользуется в payload-схемах
isoDateSchema	Zod-схема	ISO 8601 дата-время
moneyAmountSchema	Zod-схема	{ amount, currency } (минимальные единицы)
paginationSchema / Pagination	Zod-схема / тип	{ limit, cursor }
dateRangeSchema / DateRange	Zod-схема / тип	{ from, to } с from <= to
*Schema / типы payload	Zod-схемы / типы	Per-event схемы и их z.infer-типы (ShiftReportApproved, AssetTransferred, …)

Для фронта релевантна верхушка

makeEnvelope, migrateEventEnvelope, defineEvent, buildAsyncApiDocument — продюсер/инфра/build-инструменты backend. Фронту обычно нужны только EventEnvelope, EventName, EventDataByName и при необходимости per-event типы. Полный список — в API-референсе.

Подводные камни и важные правила

warning

data в конверте — unknown

EventEnvelope.data намеренно unknown. Без сужения по evt.type TypeScript не знает форму — всегда дискриминируй по type и приводи через EventDataByName<'...'>. Не доверяй форме «на глаз».

warning

Версионирование схем (version)

У каждого события есть version (major.minor). Конверты живут в outbox/DLQ долго и могут прийти со старой версией. На backend migrateEventEnvelope поднимает data до текущей схемы; если миграции нет — летит EventVersionMismatchError (→ DLQ). На фронте просто учитывай, что breaking-change схемы — это bump version, а не «тихая» правка поля.

Конвенция имён событий неизменна

Имя <context>.<entity>.<verb-past> — часть контракта. Подписки/маршрутизация завязаны на строку имени; глагол всегда в прошедшем времени (created, transferred, approved).

Anti-drift

Контракт событий не копируется во фронт руками — он импортируется из @mineflow/contracts. Тот же пакет публикует backend, тот же документ AsyncAPI проверяется breaking-diff'ом в CI. Поэтому форма event-нагрузки на клиенте гарантированно совпадает с тем, что реально шлёт сервер.

React Native

Пакет платформо-агностичен — это чистые типы/схемы Zod без платформенных API, работает в RN без оговорок. Сами типы из contracts одинаковы на всех платформах; live-доставка уведомлений (если нужна в UI) — через Centrifugo в @mineflow/client-react, без платформенной возни с транспортом.

Ссылки

• Полный API-референс из кода → /api/contracts/
• REST-референс (OpenAPI / Redoc) → /rest/
• Связанные гайды: @mineflow/client-react (useRealtimeNotifications — live-уведомления), @mineflow/api-zod (Zod-схемы REST-форм)
• Рецепты: Realtime, React Native