| assertSagaSucceeded | Превращает терминально-отказную сагу (failed/compensated) в брошенную SagaFailedError; успешную возвращает как есть. Вынесено отдельной чистой функцией, чтобы поведение покрывалось unit-тестом без рендера хука. |
| useApiMutation | Дженерик-write без авто-инвалидации кэша — когда кэшем управляешь сам (optimistic-апдейты, ручной setQueryData). Авто-Idempotency-Key всё равно проставит fetch-слой по generateId. Для автоинвалидации раздела бери useDomainMutation. |
| useApiQuery | Типобезопасный дженерик-хук чтения под любой endpoint, которого ещё нет в concrete-наборе. Конкретный запрос вызывает caller через замыкание fn(client) и типизирует его против @mineflow/api-client — SDK даёт лишь механику (кэш TanStack Query + REST-клиент из контекста), не хардкодит формы DTO. |
| useApiQueryAll | Как useApiQuery, но стягивает ВСЕ страницы курсорной пагинации в один массив (collectAllPages). Нужен там, где UI обязан видеть полный набор, а серверный предел страницы (limit ≤ 200, libs/common) молча обрезал бы одностраничный запрос — напр. пикеры персонала/техники на участке с >200 единицами. |
| useDomainMutation | Единая доменная write-мутация: вызывает fn(client, vars) и на успехе инвалидирует invalidateKey (префикс списков/деталей раздела). Заменяет раздублированные per-area хелперы (useAssetMutation/useShiftReportMutation): раздел задаётся invalidateKey, offline-механика — опциями. На дженерике построен ы все concrete write-хуки SDK. |
| useSagaMutation | Хук async-саги: start инициирует операцию (POST 202 → { sagaId }), затем хук поллит /sagas/{id}/status до терминального состояния и резолвится финальным SagaStatus. Терминальный откат (failed/compensated) бросается как SagaFailedError → срабатывает onError, а не onSuccess. |