MineFlow Client SDK
Платформо-агностичный SDK для работы с backend MineFlow из React (web) и React Native (mobile). Бизнес-логика — запросы, идемпотентность, ошибки, async-саги, FSM, RBAC, realtime, offline-запись — пишется один раз и переиспользуется обеими платформами. UI на каждой платформе свой («share logic, not pixels»).
Архитектурное обоснование — ADR-0042.
Поставь пакеты → оберни приложение в <MineflowProvider> → дёргай хуки
(useAssets, useApproveShiftReport, useNotificationFeed, …) и валидируй
формы Zod-схемами (zCreateAssetDto). Всё типобезопасно из OpenAPI и не
дрейфует от бэка (CI-гейт). → Быстрый старт
Что внутри этого сайта
| Раздел | Что | Источник |
|---|---|---|
| Обзор (эта страница) | архитектура, слои, anti-drift | рукописный |
| Быстрый старт | установка → провайдер → первый экран | рукописный |
| Пакеты | нарративный гайд по каждому из 9 пакетов с примерами | рукописный |
| Рецепты | ошибки, саги, SSE, offline, RBAC, FSM, формы, RN | рукописный |
| API-референс (из кода) | сигнатуры/типы/экспорты, извлечённые TypeDoc'ом | генерится из packages/<pkg>/src |
Два вида документации намеренно дополняют друг друга: нарративные гайды объясняют «как и зачем» с примерами, а API-референс даёт точные сигнатуры прямо из исходников и пересобирается на каждом билде, поэтому никогда не расходится с кодом.
Архитектура (слои)
| Сл ой | Пакет | Что | Гайд |
|---|---|---|---|
| L0 | @mineflow/api-client | TS-типы REST (codegen из OpenAPI, zero-runtime) | ↗ |
| L0 | @mineflow/api-zod | Zod-схемы форм (codegen из OpenAPI) | ↗ |
| L0 | @mineflow/api-schemas | FSM-машины (xstate) + status-энумы | ↗ |
| L1 | @mineflow/client-core | fetch + Idempotency-Key + ошибки + саги + пагинация + SSE + JWT | ↗ |
| L2 | @mineflow/client-react | провайдер + хуки (data/mutation/saga/notifications/RBAC/FSM) | ↗ |
| L3 | @mineflow/auth-web | KeycloakTokenProvider (web) | ↗ |
| L3 | @mineflow/auth-native | ReactNativeTokenProvider (RN) | ↗ |
| — | @mineflow/contracts | типы/схемы доменных событий (для realtime/интеграций) | ↗ |
| — | @mineflow/shared-validation | ИИН/БИН/IBAN-проверки (frontend-safe) | ↗ |
В 95% случаев фронтенд работает только с client-react + api-zod +
auth-web. client-core — низкоуровневое ядро (используется через про вайдер),
api-schemas — для FSM-кнопок.
Anti-drift — почему SDK не разойдётся с бэком
Один источник истины на бэке → в SDK попадает codegen'ом или re-export'ом, никогда копией → CI-гейт валит тот же PR.
- Типы (
api-client) — codegen из live-OpenAPI. - Zod-схемы форм (
api-zod) — codegen из live-OpenAPI. - FSM-машины и энумы (
api-schemas) — re-export спецификации бэка. - Роли — единый словарь Keycloak→canonical в ядре.
- Read-хуки (list/detail) — генерятся из OpenAPI (
pnpm gen:hooks), падают fail-loud при переименовании эндпоинта.
Подробно — ADR-0042 § Anti-drift contract.
Ключевые правила
baseUrl— это origin (https://api.mineflow.local), без пути: пути из api-client уже содержат/api/v1.- Idempotency-Key проставляется автоматически на все write.
- Async-саги: некоторые POST возвращают
202 + sagaId; saga-хуки сами поллят статус до терминала. - Ошибки —
MineflowApiErrorсо стабильнымerror.code; гейти UI поcode, не по тексту. - Object-scope / multi-tenancy делает сервер по JWT —
org_idв URL не передаётся. - FSM: показывай кнопки по
useAvailableActions(machine, status); бэк всё равно валидирует переход (409). - Offline-first: write-операции рапорта паузятся офлайн и доигрываются при реконнекте.
→ Дальше: Быстрый старт