index
@mineflow/client-core
@mineflow/client-core
Classes
| Class | Description |
|---|---|
| MineflowApiError | Типизированная ошибка REST-вызова. Бросается из unwrap/normalizeError, когда ответ не-OK. Наследует Error, поэтому ловится обычным try/catch и распознаётся через instanceof MineflowApiError. |
| SagaTimeoutError | Бросается pollSaga, когда сага не достигла терминала за timeoutMs. Несёт sagaId зависшей саги и лимит — для логирования/ретраев на стороне UI. |
Interfaces
| Interface | Description |
|---|---|
| AuthFetchOptions | Опции конструктора makeAuthenticatedFetch. |
| CursorPage | Одна страница курсорного списка. |
| GetTokenOptions | Опции getToken. |
| JwtClaims | Подмножество клеймов access-token'а Keycloak, которые читает фронт. Открытый индекс [claim: string] оставляет доступ к остальным клеймам (sub, name, exp…). |
| MineflowClientOptions | Опции all-in-one конструктора createMineflowClient. |
| PollSagaOptions | Опции опроса саги pollSaga. |
| ProblemDetails | Форма тела ошибки бэкенда по RFC 7807 (Problem Details). |
| SagaStatusClient | Минимальный структурный контракт openapi-fetch-клиента для saga-status. pollSaga принимает любой объект с таким GET, поэтому реальный MineflowClient подходит as-is, а тесты могут подсунуть мок. |
| TokenProvider | Поставщик access-token'а. web: keycloak-js; RN: react-native-app-auth. |
| TokenStorage | Хранилище токена/состояния. web: localStorage; RN: expo-secure-store. |
Type Aliases
| Type Alias | Description |
|---|---|
| IdGenerator | Генератор Idempotency-Key (ADR-0012). web: crypto.randomUUID; RN: react-native-get-random-values + uuid. Должен возвращать свежий UUID на каждый вызов. |
| MineflowClient | Тип типобезопасного REST-клиента MineFlow — openapi-fetch Client, параметризованный сгенерированными из OpenAPI paths. Даёт методы .GET/.POST/.PATCH/.PUT/.DELETE с автодополнением путей, query- и body-типов. |
| SagaStatus | Снимок состояния саги из GET /api/v1/sagas/{sagaId}/status. Содержит append-only массив steps (см. шапку файла) — сырой saga_log, который latestStatusByStep сворачивает в последний статус по каждому шагу. |
| SagaStepStatus | Одна строка saga_log: имя шага и его статус на момент записи. Поле status — настоящий union канонического enum (не string), протёкший из бэка через OpenAPI (anti-drift, ADR-0042). |
| SystemRole | Канонический RBAC-контракт MineFlow — 7 системных ролей в PascalCase. |
Variables
| Variable | Description |
|---|---|
| KEYCLOAK_ROLE_ALIASES | Keycloak realm-role aliases (lowercase) → канонический MineFlow SystemRole. Платформо-агностично: используется и web (auth-web), и RN (auth-native) адаптерами — живёт в ядре, чтобы не было RN→web зависимости и второй копии. |
Functions
| Function | Description |
|---|---|
| collectAllPages | Стягивает все страницы курсорного списка в один массив, последовательно передавая nextCursor следующему запросу, пока он не станет null. |
| createMineflowClient | All-in-one конструктор: за один вызов строит аутентифицированный fetch (Bearer + авто Idempotency-Key + retry-once на 401) и openapi-fetch-клиент поверх него. Подходит для не-React кода: скриптов, CLI, фоновых задач. |
| createRestClient | Низкоуровневый конструктор: openapi-fetch клиент поверх ГОТОВОГО fetch. |
| decodeJwt | Декодирует payload (вторую часть) JWT в объект клеймов. Подпись НЕ проверяется — это работа сервера; фронт читает клеймы только для UI/scope. |
| defaultIsSettled | Дефолтный предикат завершённости саги: - любой шаг в финальном последнем статусе failed/compensated → терминал; - иначе settled, когда последний статус КАЖДОГО шага = completed. |
| hasTerminalFailure | Есть ли шаг в терминальном провале (failed/compensated). Такой статус окончателен независимо от будущих шагов, поэтому pollSaga возвращает его сразу, БЕЗ стабилизации (в отличие от success-пути). |
| latestStatusByStep | Сворачивает append-only строки saga_log в последний статус по каждому шагу. Строки упорядочены по времени (at asc), поэтому поздняя перетирает раннюю. |
| makeAuthenticatedFetch | Собирает fetch-декоратор, который перед каждой отправкой добавляет Authorization: Bearer <token>, на write-методы (POST/PUT/PATCH/DELETE) ставит Idempotency-Key (ADR-0012), а на ответ 401 ровно один раз форсит refresh токена и повторяет запрос. |
| mapKeycloakRoles | Маппит realm-роли Keycloak (lowercase-алиасы) в канонические SystemRole (PascalCase), дедуплицируя результат. Неизвестные роли (не из KEYCLOAK_ROLE_ALIASES) молча отбрасываются — фронт оперирует только 7 системными ролями. Сравнение регистронезависимо (role.toLowerCase()). |
| normalizeError | Превращает (HTTP-статус, тело ответа) в типизированную MineflowApiError. |
| orgIdFromToken | Достаёт organization_id владельца сессии из токена (клейм org_id, ADR-0020). Нужен только для UI (показать организацию) — авторизацию и scope делает бэк по JWT, в URL org_id не передаётся. |
| pollSaga | Опрашивает статус async-саги до терминального состояния и возвращает финальный снимок. Бэк выполняет некоторые POST асинхронно (возвращая 202 + sagaId), SSE для саг нет — поэтому статус тянется поллингом. |
| realmRolesFromToken | Достаёт realm-роли из токена (lowercase-алиасы Keycloak, напр. ['foreman']). Маппинг в канонический SystemRole (PascalCase) делает mapKeycloakRoles, а не ядро. |
| unwrap | Извлекает данные из openapi-fetch-совместимого результата { data, error, response }, либо бросает MineflowApiError, если ответ не-OK или присутствует error. |