index
@mineflow/client-core
@mineflow/client-core
Classes
| Class | Description |
|---|---|
| CopilotStreamError | Ошибка открытия потока Copilot (не-2xx ответ до начала стрима). |
| MineflowApiError | Типизированная ошибка REST-вызова. Бросается из unwrap/normalizeError, когда ответ не-OK. Наследует Error, поэтому ловится обычным try/catch и распознаётся через instanceof MineflowApiError. |
| SagaTimeoutError | Бросается pollSaga, когда сага не достигла терминала за timeoutMs. Несёт sagaId зависшей саги и лимит — для логирования/ретраев на стороне UI. |
Interfaces
| Interface | Description |
|---|---|
| AuthFetchOptions | Опции конструктора makeAuthenticatedFetch. |
| CopilotChartSeries | Серия графика: поле-значение в каждой строке data + опц. подпись/цве т. |
| CopilotChartSpec | Резолвленная спека графика — то, что едет в SSE-чанке chart и рендерится во фронте (ADR-0096). КЛЮЧЕВОЕ: data наполняет agent-host из захваченного результата read-инструмента (подход 2b), модель значения НЕ сочиняет — она лишь выбирает kind, x и series (поля). client-core — SoT этого провода; agent-host импортирует тип отсюда, web рендерит по нему. |
| 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, а тесты могут подсунуть мок. |
| SignatureEnvelope | Транспортная обёртка одной ЭЦП (BL-58 / ADR-0105). CMS-контейнер (CAdES) в base64 (DER). Структурно совпадает с signatureEnvelopeSchema из @mineflow/contracts (бэк валидирует ту же форму) — здесь дублируется как локальный тип, т.к. фронт-пакеты не импортируют runtime-barrel контрактов (ADR-0042 / dep-cruiser). |
| SignatureProvider | Поставщик ЭЦП (BL-58 / ADR-0105). Зовётся makeAuthenticatedFetch на КАЖДЫЙ write-запрос — тем же слоем, что навешивает Idempotency-Key. Если вернул непустой массив конвертов, fetch-слой вкладывает их в JSON-тело зарезервированным полем _signature (одна) / _signatures (несколько), которое SignatureGuard снимает на сервере. |
| SignatureRequestContext | Контекст исходящего write-запроса, по которому рез олвится подпись. |
| StreamCopilotOptions | Опции streamCopilot. |
| TokenProvider | Поставщик access-token'а. web: keycloak-js; RN: react-native-app-auth. |
| TokenStorage | Хранилище токена/состояния. web: localStorage; RN: expo-secure-store. |
Type Aliases
| Type Alias | Description |
|---|---|
| AgentStreamChunk | Фрагмент потока ответа Copilot. Дискриминируется по type. ЗЕРКАЛИТ AgentStreamChunk из apps/agent-host — это сетевой контракт между ними. |
| CopilotChartKind | Виды визуализации Copilot (ADR-0096). Намеренно узкий whitelist — декларативная спека маппится в фиксированный набор Mantine-компонентов на фронте, никакого исполняемого кода от модели. area исключён: recharts AreaChart нестабилен под React 19 (см. web-заметку), используем line. |
| CopilotChartRow | Одна строка данных графика. Значения — скаляры (агрегаты/проекции сервера). |
| 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 — 11 системны х ролей в 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) молча отбрасываются — фронт оперирует только 11 системными ролями. Сравнение регистронезависимо (role.toLowerCase()). |
| normalizeError | Превращает (HTTP-статус, тело ответа) в типизированную MineflowApiError. |
| orgIdFromToken | Достаёт organization_id владельца сессии из токена (клейм org_id, ADR-0020). Нужен только для UI (показать организацию) — авторизацию и scope делает бэк по JWT, в URL org_id не передаётся. |
| parseSseFrame | Разбирает один SSE-кадр (текст между \n\n) в { event, data }. Чистая функция (легко тестируется). Возвращает null для кадров без data: (комментарии-keepalive : ..., пустые кадры). |
| pollSaga | Опрашивает статус async-саги до терминального состояния и возвращает финальный снимок. Бэк выполняет некоторые POST асинхронно (возвращая 202 + sagaId), SSE для саг нет — поэтому статус тянется поллингом. |
| realmRolesFromToken | Достаёт realm-роли из токена (lowercase-алиасы Keycloak, напр. ['foreman']). Маппинг в канонический SystemRole (PascalCase) делает mapKeycloakRoles, а не ядро. |
| streamCopilot | Открывает SSE-поток на один ход диалога и проигрывает фрагменты в обработчики. |
| unwrap | Извлекает данные из openapi-fetch-совместимого результата { data, error, response }, либо бросает MineflowApiError, если ответ не-OK или присутствует error. |