@ryuzaki13/react-foundation-api 1.1.16 → 1.1.17

package/src/foundationApi.mdx

@@ -0,0 +1,123 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation API/Обзор" />
+
+# `@ryuzaki13/react-foundation-api`
+
+Пакет соединяет приложение с внешними API. Он содержит transport, интеграцию с TanStack Query, SAP/OData V2 infrastructure и небольшие orchestration helpers. Документ рассчитан на разработчика, который видит только опубликованный пакет и его типы.
+
+## Подключение
+
+```bash
+npm install @ryuzaki13/react-foundation-api @ryuzaki13/react-foundation-lib
+```
+
+Корневого импорта нет. Всегда указывайте точный subpath:
+
+```ts
+import { httpFetchPayload } from "@ryuzaki13/react-foundation-api/http";
+import { useResourceQuery } from "@ryuzaki13/react-foundation-api/resource";
+import { useODataMetadataQuery } from "@ryuzaki13/react-foundation-api/odata";
+```
+
+## Где находится пакет в архитектуре
+
+```text
+host application: entities / features / widgets / pages
+                           │
+                           ▼
+          @ryuzaki13/react-foundation-api
+           transport + query orchestration
+                           │
+                           ▼
+          @ryuzaki13/react-foundation-lib
+       pure helpers + metadata + query policies
+```
+
+`foundation-api` не должен знать конкретную бизнес-сущность, экран или UI-компонент. DTO/domain mapping конкретного проекта остаётся у host-приложения. UI primitives находятся в `@ryuzaki13/react-foundation-ui`.
+
+## Как выбрать entrypoint
+
+| Нужно сделать | Entrypoint | Важная граница |
+| --- | --- | --- |
+| Вызвать обычный JSON REST endpoint | `http` | Нет SAP/SSO/X-CSRF политики |
+| Вызвать SAP Gateway/OData V2 | `odata` | Metadata, envelope, SSO и X-CSRF принадлежат этому слою |
+| Описать произвольные queries/mutations | `resource` | Transport передаётся операциями |
+| Описать сохранённые records с фиксированными capability | `persisted` | Только list/latest/history/save/create/delete |
+| Подключить функцию вида `fn({ data })` | `server-fn` | Это adapter операции, не сервер и не security boundary |
+| Выполнить пакет независимых задач | `async` | Выберите all-at-once или bounded concurrency |
+| Прочитать ADT transport XML | `adt` | Endpoint `/sap/bc/adt`, XML |
+| Прочитать UI2 workbench/customizing requests | `transport` | Это SAP transport requests, а не generic HTTP transport |
+| Отправить error-report draft | `error-report` | Сбор/хранение draft принадлежит `foundation-lib` |
+
+## Самая частая ошибка: одинаковые слова, разные уровни
+
+### `http` и `odata`
+
+`http` подходит для нейтрального REST. Он не получает CSRF token, не распознаёт SAML form и не снимает OData V2 envelope. Для SAP Gateway используйте `odata`, даже если технически запрос тоже выполняется через `fetch`.
+
+### `resource` и `persisted`
+
+`resource` позволяет задавать любые имена операций: например `search`, `details`, `archive`. `persisted` — специализированный facade для сохранённых записей с именами `list`, `latest`, `history`, `save`, `create`, `delete`.
+
+### `adt` и `transport`
+
+Оба entrypoint читают SAP transports, но из разных API:
+
+| Entrypoint | Endpoint/format | Результат |
+| --- | --- | --- |
+| `adt` | `/sap/bc/adt/cts/transports`, XML | Общий `UserTransport` из ADT header |
+| `transport` | UI2 OData endpoints, JSON | Нормализованные workbench/customizing requests |
+
+## TanStack Query: кто чем владеет
+
+`resource`, `persisted` и часть `odata` работают внутри `QueryClientProvider`. Query key определяет identity кеша; `staleTime` — свежесть; `gcTime` — время хранения неиспользуемого query; `AbortSignal` позволяет отменять чтение. Mutation не обновляет все связанные query автоматически: это делает явно выбранная cache strategy.
+
+```tsx
+import { QueryClientProvider } from "@tanstack/react-query";
+import { createQueryClient } from "@ryuzaki13/react-foundation-lib/query-client";
+
+const queryClient = createQueryClient();
+
+export function App() {
+	return <QueryClientProvider client={queryClient}>{/* приложение */}</QueryClientProvider>;
+}
+```
+
+Не создавайте новый `QueryClient` при каждом render.
+
+## Runtime
+
+| API | Browser | Server runtime |
+| --- | :---: | :---: |
+| `async` и pure normalization | Да | Да |
+| `http` | Да | Да, если доступны Web Fetch API |
+| pure `resource` factories | Да | Да |
+| React hooks | Да | Только в поддерживаемом React runtime/provider |
+| OData SSO recovery | Да | Нет: использует `window`, `document`, iframe |
+| SAP transport fetchers | Да | Только при корректном fetch/proxy/cookie окружении |
+
+OData transport использует compile-time constants и проектный adapter. Host-сборка должна предоставлять ожидаемую конфигурацию; подробности приведены на странице OData.
+
+## Service Worker cache
+
+Некоторые query factories передают строку политики через header `x-sw-cache`. Сам header ничего не кеширует: Service Worker host-приложения должен понимать тот же protocol.
+
+```text
+off
+ttl=24h
+ttl=10m;max=200;name=ui
+bust=24h;name=ref
+```
+
+`bust` означает принудительное обновление сетевого snapshot в соответствующей cache policy. Не используйте SW cache для персональных/секретных payload без отдельной модели изоляции.
+
+## Каталог страниц
+
+| Область | Документы |
+| --- | --- |
+| Transport | [HTTP](./http/README.mdx), [OData](./odata/README.mdx), [ADT](./adt/README.mdx), [SAP Transport Requests](./transport/README.mdx) |
+| Query infrastructure | [Resource](./resource/README.mdx), [Persisted](./persisted/README.mdx), [Server Function](./server-fn/README.mdx) |
+| Orchestration и diagnostics | [Async](./async/README.mdx), [Error Report](./error-report/README.mdx) |
+
+Каждая страница содержит точный import, пошаговый guide, runtime/lifecycle, ошибки и таблицу публичных exports. Не импортируйте файл глубоким путём, если его символ не опубликован соответствующим entrypoint.

package/src/http/README.mdx

@@ -0,0 +1,221 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation API/Transport/HTTP" />
+
+# Обычный HTTP через `@ryuzaki13/react-foundation-api/http`
+
+Модуль выполняет нейтральные HTTP/REST запросы и создаёт функции, совместимые с TanStack Query. Внешний payload остаётся `unknown`, пока consumer явно не проверит его через `parse`.
+
+## Содержание
+
+- [Когда использовать](#когда-использовать)
+- [Импорт](#импорт)
+- [`httpFetch`](#httpfetch)
+- [`httpFetchPayload`](#httpfetchpayload)
+- [`httpJsonQueryFn`](#httpjsonqueryfn)
+- [`httpJsonMutationFn`](#httpjsonmutationfn)
+- [`RouteError`](#routeerror)
+- [Ошибки, runtime и безопасность](#ошибки-runtime-и-безопасность)
+- [Полный API](#полный-api)
+
+## Когда использовать
+
+```text
+обычный REST/HTTP ──► /http
+SAP Gateway/OData ──► /odata
+```
+
+`http` не добавляет SAP headers, `credentials: include`, X-CSRF token, SSO recovery, OData V2 headers и не снимает envelope `{ d: { results } }`. Для SAP/OData используйте [`/odata`](../odata/README.mdx).
+
+## Импорт
+
+```ts
+import {
+	httpFetch,
+	httpFetchPayload,
+	httpJsonMutationFn,
+	httpJsonQueryFn,
+	RouteError
+} from "@ryuzaki13/react-foundation-api/http";
+
+import type {
+	HttpMutationFnOptions,
+	HttpQueryFnOptions,
+	HttpRequestOptions
+} from "@ryuzaki13/react-foundation-api/http";
+```
+
+Нужны глобальные Web Fetch API: `fetch`, `Request`, `Response`, `Headers`, `URL`.
+
+## `httpFetch`
+
+```ts
+const response = await httpFetch("/health", {
+	baseUrl: "https://api.example.com",
+	init: {
+		method: "GET",
+		headers: { Accept: "text/plain" }
+	}
+});
+
+console.log(await response.text());
+```
+
+Функция возвращает исходный `Response`, если `response.ok === true`. Body ещё не прочитан.
+
+Для string input URL строится простой конкатенацией:
+
+```text
+baseUrl + input
+```
+
+Helper не исправляет slash:
+
+```ts
+// Правильно.
+{ baseUrl: "https://api.example.com", input: "/users" }
+
+// Получится https://api.example.comusers — неверно.
+{ baseUrl: "https://api.example.com", input: "users" }
+```
+
+Если input является `Request` или `URL`, `baseUrl` игнорируется. Это не proxy/url resolver.
+
+## `httpFetchPayload`
+
+```ts
+const payload: unknown = await httpFetchPayload("/api/profile");
+```
+
+Правила parser-а:
+
+| Response | Результат |
+| --- | --- |
+| status `204` или `205` | `null` |
+| `Content-Type` содержит `application/json` | `response.json()` |
+| любой другой content type | `response.text()` |
+
+Результат намеренно `unknown`. Generic type не может проверить данные, пришедшие по сети:
+
+```ts
+function parseProfile(value: unknown): Profile {
+	if (!isProfile(value)) throw new Error("Некорректный Profile payload");
+	return value;
+}
+
+const profile = parseProfile(await httpFetchPayload("/api/profile"));
+```
+
+Если сервер отдаёт JSON без корректного `Content-Type`, модуль вернёт JSON как string. Исправьте backend или разберите string на своей boundary.
+
+## `httpJsonQueryFn`
+
+Factory возвращает async-функцию с формой TanStack Query `queryFn`:
+
+```ts
+const loadProfile = httpJsonQueryFn("/api/profile", {
+	baseUrl: "https://api.example.com",
+	parse: parseProfile,
+	swCache: "ttl=10m;name=profile"
+});
+
+const profile = await loadProfile({ signal });
+```
+
+С React Query:
+
+```tsx
+const profileQuery = useQuery({
+	queryKey: ["profile", userId],
+	queryFn: httpJsonQueryFn(`/api/users/${userId}`, {
+		parse: parseProfile
+	})
+});
+```
+
+Factory:
+
+- использует `init.signal`, если он задан явно;
+- иначе подставляет signal, переданный TanStack Query;
+- добавляет `x-sw-cache`, только если `swCache` truthy;
+- вызывает обязательный `parse(payload)` после успешного запроса.
+
+Header `x-sw-cache` — только protocol с Service Worker. Без соответствующего SW он не создаёт cache.
+
+`parse` может вернуть преобразованную domain model, но обычно лучше ограничиться runtime validation и вынести бизнес-mapping владельцу entity.
+
+## `httpJsonMutationFn`
+
+```ts
+type CreateUserInput = { name: string };
+
+const createUser = httpJsonMutationFn<CreateUserInput, User>("/api/users", {
+	method: "POST",
+	mapBody: (input) => ({ displayName: input.name }),
+	parse: parseUser
+});
+
+const user = await createUser({ name: "Анна" });
+```
+
+С `useMutation`:
+
+```tsx
+const mutation = useMutation({ mutationFn: createUser });
+mutation.mutate({ name: "Анна" });
+```
+
+Поведение:
+
+1. Вычисляет body через `mapBody(input)` или использует input.
+2. Сериализует body через `JSON.stringify`.
+3. Использует method `POST` по умолчанию; поддерживаются `POST`, `PUT`, `PATCH`, `DELETE`.
+4. Добавляет `Content-Type: application/json`, только если header ещё не задан.
+5. Выполняет запрос и передаёт payload в обязательный `parse`.
+
+Сигнатура mutation function также допускает второй `AbortSignal` при ручном вызове. Стандартный `useMutation` TanStack Query не передаёт signal автоматически. Если `options.init.signal` уже задан, второй signal не заменит его.
+
+`JSON.stringify` может бросить ошибку для `BigInt`/циклического объекта. `undefined` body сериализуется в `undefined`; убедитесь, что это соответствует endpoint.
+
+## HTTP errors
+
+Для `response.ok === false` обе низкоуровневые функции бросают обычный `Error`:
+
+```text
+HTTP error: <message>
+```
+
+Если error body — непустой text, он становится message. Для JSON error object поля `message`, `error` и `details` не извлекаются; fallback — `<status> <statusText>`.
+
+Network error/CORS/abort от глобального `fetch` пробрасывается без обёртки.
+
+## `RouteError`
+
+```ts
+throw new RouteError(404);
+```
+
+Это маленький `Error` с числовым полем `status` и пустым message. `httpFetch` сам его не создаёт. Класс нужен для routing/error-boundary policy приложения, если оно договорилось понимать такой error.
+
+## Ошибки, runtime и безопасность
+
+- TypeScript generic не валидирует сеть; используйте `parse`/schema guard.
+- `baseUrl` и path не нормализуются и не кодируются.
+- Authorization, cookies, CORS и retry задаёт consumer через `init` или внешний слой.
+- Модуль не делает timeout. Для него используйте `AbortController`.
+- Не помещайте token/secret в query string и cache key.
+- `x-sw-cache` для персональных данных требует изолированной cache policy.
+- На SSR абсолютный/относительный URL и cookies должны быть настроены server runtime-ом.
+
+## Полный API
+
+| Export | Результат |
+| --- | --- |
+| `httpFetch` | Успешный `Response` |
+| `httpFetchPayload` | JSON/text/`null` как `unknown` |
+| `httpJsonQueryFn` | Query-compatible async function |
+| `httpJsonMutationFn` | Mutation-compatible async function |
+| `RouteError` | Error с `status` |
+| `HttpRequestOptions` | `baseUrl` и `init` |
+| `HttpQueryFnOptions` | Request options + `swCache` + `parse` |
+| `HttpMutationFnOptions` | Request options + method/body mapper/parse |