@ryuzaki13/react-foundation-api 1.1.16 → 1.1.18

package/src/error-report/README.mdx

@@ -0,0 +1,471 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation API/Errors/Error Report Delivery" />
+
+# Доставка error reports через `@ryuzaki13/react-foundation-api/error-report`
+
+Модуль превращает сохранённый черновик отчёта из `foundation-lib` в delivery body, вызывает adapter приложения и обновляет статус черновика.
+
+## Граница ответственности
+
+```text
+foundation-lib/error-report        foundation-api/error-report       host backend adapter
+collect + sanitize + draft store ──► lifecycle + delivery body ─────► HTTP/OData/serverFn
+```
+
+Модуль не собирает browser diagnostics, не выбирает endpoint и не отправляет запрос самостоятельно. Transport явно передаёт приложение через `adapter`.
+
+## Установка и импорт
+
+```ts
+import {
+	createErrorReportDeliveryBody,
+	sendErrorReport
+} from "@ryuzaki13/react-foundation-api/error-report";
+
+import type {
+	ErrorReportDeliveryAdapter,
+	ErrorReportDeliveryBody,
+	ErrorReportDeliveryContext,
+	SendErrorReportOptions
+} from "@ryuzaki13/react-foundation-api/error-report";
+```
+
+Нужны `@ryuzaki13/react-foundation-lib` и `@tanstack/react-query`.
+
+## Полный сценарий
+
+Сначала другой слой создаёт и сохраняет draft средствами `@ryuzaki13/react-foundation-lib/error-report`. Затем API-слой получает только его `reportId`:
+
+```ts
+import { httpFetchPayload } from "@ryuzaki13/react-foundation-api/http";
+import { sendErrorReport } from "@ryuzaki13/react-foundation-api/error-report";
+import type { ErrorReportDeliveryAdapter } from "@ryuzaki13/react-foundation-api/error-report";
+
+const deliveryAdapter: ErrorReportDeliveryAdapter = async (body) => {
+	await httpFetchPayload("/api/error-reports", {
+		init: {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body)
+		}
+	});
+};
+
+await sendErrorReport(reportId, {
+	adapter: deliveryAdapter,
+	queryClient
+});
+```
+
+## `createErrorReportDeliveryBody`
+
+```ts
+const body = createErrorReportDeliveryBody(draft);
+```
+
+Результат:
+
+```ts
+type ErrorReportDeliveryBody = {
+	reportId: string;
+	sessionId: string;
+	createdUtc: string;
+	category: ErrorReportCategory;
+	errorClass: string;
+	errorMessage: string;
+	stackTrace?: string;
+	payload: string;
+};
+```
+
+`payload` — JSON string всего payload черновика, а не вложенный object. Это важно для backend contract.
+
+Если `draft.payload.error.message` пуст, обязательные `errorMessage` и message внутри сериализованного payload получают значение `"Неизвестная ошибка"`. Остальной draft не нормализуется.
+
+`JSON.stringify` может выбросить ошибку при циклических или неподдерживаемых данных. Draft должен соответствовать сериализуемому контракту `foundation-lib`.
+
+### Что такое draft и delivery body
+
+Для начинающего разработчика важно не смешивать две формы:
+
+```text
+ErrorReportDraft
+├── локальный lifecycle status
+├── retry information
+├── collected/sanitized payload
+└── identifiers
+
+ErrorReportDeliveryBody
+├── плоские обязательные backend fields
+└── payload: JSON string
+```
+
+Draft принадлежит локальному хранилищу `foundation-lib`. Delivery body — одноразовый snapshot для transport adapter-а.
+
+Нельзя отправлять draft целиком только потому, что он уже похож на body: backend contract намеренно отделён от local store contract.
+
+### Соответствие полей
+
+| Delivery field | Источник |
+| --- | --- |
+| `reportId` | `draft.reportId` |
+| `sessionId` | `draft.sessionId` |
+| `createdUtc` | `draft.createdUtc` |
+| `category` | `draft.category` |
+| `errorClass` | `draft.payload.error.name` |
+| `errorMessage` | `draft.payload.error.message` или fallback |
+| `stackTrace` | `draft.payload.error.stackTrace` |
+| `payload` | `JSON.stringify(normalized payload)` |
+
+Если message содержит непустой текст с пробелами по краям, проверка считает его валидным, но в delivery сохраняется исходная строка. Функция не выполняет общий trim draft-а.
+
+```ts
+draft.payload.error.message = "  Ошибка сохранения  ";
+
+const body = createErrorReportDeliveryBody(draft);
+body.errorMessage;
+// "  Ошибка сохранения  "
+```
+
+Если message пустой или whitespace-only:
+
+```ts
+draft.payload.error.message = "   ";
+
+const body = createErrorReportDeliveryBody(draft);
+body.errorMessage;
+// "Неизвестная ошибка"
+
+JSON.parse(body.payload).error.message;
+// "Неизвестная ошибка"
+```
+
+Функция создаёт новые wrapper objects и не записывает fallback обратно в draft.
+
+## `sendErrorReport`
+
+Lifecycle:
+
+```text
+draft отсутствует ─────────► undefined
+status sent/sending ───────► текущий draft, adapter не вызывается
+остальной draft ───────────► sending
+                               │
+                    adapter success / error
+                       │              │
+                       ▼              ▼
+                     sent           failed + failedReason
+```
+
+Пошагово функция:
+
+1. Ищет draft по `reportId` в store из `foundation-lib`.
+2. Возвращает `undefined`, если draft не найден.
+3. Не отправляет повторно draft со статусом `sent` или `sending`.
+4. Устанавливает `status: "sending"` и очищает `failedReason`.
+5. Создаёт delivery body.
+6. Вызывает `adapter(body, { draft, queryClient })`.
+7. При успехе устанавливает `status: "sent"` и `sentUtc`.
+8. При ошибке устанавливает `status: "failed"`, сохраняет нормализованное сообщение и повторно бросает исходную ошибку.
+
+Adapter получает исходный snapshot `draft`, прочитанный до перевода store в `sending`. Используйте `body` как delivery payload, а context — для query invalidation или transport, которому нужен `QueryClient`.
+
+### Status table
+
+| Status draft до вызова | Вызывается adapter | Результат |
+| --- | --- | --- |
+| draft отсутствует | нет | `undefined` |
+| `sent` | нет | текущий draft |
+| `sending` | нет | текущий draft |
+| `pending` или эквивалентный начальный | да | `sent` либо exception + `failed` |
+| `failed` | да | повторная попытка |
+
+Функция не создаёт draft. Если `reportId` ошибочный, это не exception: result равен `undefined`.
+
+### Время отправки
+
+`sentUtc` создаётся на client после успешного завершения adapter-а:
+
+```ts
+new Date().toISOString()
+```
+
+Это client timestamp, а не server acknowledgement time. Для аудита используйте server time из backend record.
+
+### Ошибка построения body
+
+`createErrorReportDeliveryBody` вызывается внутри `try`. Если `JSON.stringify` выбросил error:
+
+- adapter не вызывается;
+- draft становится `failed`;
+- `failedReason` формируется через `createErrorInfo`;
+- исходный error снова выбрасывается caller-у.
+
+### UI flow
+
+```tsx
+import { useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { sendErrorReport } from "@ryuzaki13/react-foundation-api/error-report";
+
+function SendReportButton({ reportId }: { reportId: string }) {
+	const queryClient = useQueryClient();
+	const [isSending, setIsSending] = useState(false);
+	const [errorMessage, setErrorMessage] = useState<string>();
+
+	const handleSend = async () => {
+		setIsSending(true);
+		setErrorMessage(undefined);
+
+		try {
+			const result = await sendErrorReport(reportId, {
+				adapter: deliveryAdapter,
+				queryClient
+			});
+
+			if (!result) {
+				setErrorMessage("Черновик отчёта не найден");
+			}
+		} catch (error) {
+			setErrorMessage(
+				error instanceof Error ? error.message : "Не удалось отправить отчёт"
+			);
+		} finally {
+			setIsSending(false);
+		}
+	};
+
+	return (
+		<>
+			<button type="button" disabled={isSending} onClick={handleSend}>
+				{isSending ? "Отправка…" : "Отправить отчёт"}
+			</button>
+			{errorMessage ? <p role="alert">{errorMessage}</p> : null}
+		</>
+	);
+}
+```
+
+Local `isSending` нужен UI для немедленной блокировки повторного click. Draft status остаётся источником долгоживущего lifecycle, но component может не быть подписан на store.
+
+## Варианты delivery adapter-а
+
+### Обычный HTTP
+
+```ts
+import { httpFetchPayload } from "@ryuzaki13/react-foundation-api/http";
+import type { ErrorReportDeliveryAdapter } from "@ryuzaki13/react-foundation-api/error-report";
+
+export const deliveryAdapter: ErrorReportDeliveryAdapter = async (body) => {
+	await httpFetchPayload("/api/error-reports", {
+		init: {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body)
+		}
+	});
+};
+```
+
+### OData FunctionImport
+
+Если backend contract опубликован как FunctionImport, operation определяется metadata:
+
+```ts
+import { odataFunctionImportFn } from "@ryuzaki13/react-foundation-api/odata";
+import { wrapODataParams } from "@ryuzaki13/react-foundation-lib/odata-service";
+
+const deliveryAdapter: ErrorReportDeliveryAdapter = async (body, { queryClient }) => {
+	await odataFunctionImportFn({
+		odata: {
+			service: "ZERROR_REPORT_SRV",
+			target: "SendErrorReport"
+		},
+		params: wrapODataParams({
+			ReportId: body.reportId,
+			Payload: body.payload
+		})
+	})({ client: queryClient });
+};
+```
+
+Это только пример mapping: точные parameter names должны соответствовать metadata вашего сервиса.
+
+### Server function
+
+Adapter может вызвать client-safe serverFn operation. Модуль error-report не знает о transport и не ограничивает его, пока adapter возвращает `Promise<void>`.
+
+### Почему adapter ничего не возвращает
+
+`sendErrorReport` управляет local draft lifecycle, а не server entity. Если backend вернул receipt, adapter может обработать его внутри: сохранить в отдельный Query cache, telemetry или domain store. Public delivery contract считает успехом fulfilled promise.
+
+## Adapter с cache invalidation
+
+```ts
+const adapter: ErrorReportDeliveryAdapter = async (body, { queryClient }) => {
+	await postReport(body);
+	await queryClient.invalidateQueries({ queryKey: ["error-reports"] });
+};
+```
+
+Если invalidation бросит ошибку, вся доставка считается неуспешной и draft станет `failed`, даже если backend уже принял отчёт. Для non-critical cache update обработайте ошибку внутри adapter-а.
+
+Безопасный вариант для необязательного refresh:
+
+```ts
+const adapter: ErrorReportDeliveryAdapter = async (body, { queryClient }) => {
+	await postReport(body);
+
+	try {
+		await queryClient.invalidateQueries({ queryKey: ["error-reports"] });
+	} catch (error) {
+		console.warn("Отчёт отправлен, но cache не обновлён", error);
+	}
+};
+```
+
+Решение зависит от contract: если fresh cache является частью успешной операции, не поглощайте ошибку.
+
+## Повторная отправка и concurrency
+
+После `failed` функцию можно вызвать повторно. Проверка `sending` защищает от обычного повторного нажатия, но это не распределённая блокировка: два практически одновременных вызова могут успеть прочитать старый статус до его обновления. Backend желательно сделать идемпотентным по `reportId`.
+
+### Idempotency backend-а
+
+Рекомендуемый server contract:
+
+```text
+UNIQUE(reportId)
+```
+
+Повтор с тем же `reportId` должен либо вернуть прежний успешный result, либо завершиться предсказуемым «already accepted», которое adapter считает успехом.
+
+Это защищает сценарий:
+
+1. Backend принял report.
+2. Network response потерялся.
+3. Client пометил draft как `failed`.
+4. Пользователь повторил отправку.
+
+Без idempotency server создаст duplicate.
+
+### Несколько tabs
+
+Status `sending` в local store не является cross-tab distributed lock, если storage implementation явно не гарантирует это. Idempotency по `reportId` остаётся обязательной защитой.
+
+## Тестирование
+
+### Body builder
+
+```ts
+import { expect, it } from "vitest";
+
+it("подставляет fallback message в оба места", () => {
+	const body = createErrorReportDeliveryBody({
+		...draftFixture,
+		payload: {
+			...draftFixture.payload,
+			error: {
+				...draftFixture.payload.error,
+				message: " "
+			}
+		}
+	});
+
+	expect(body.errorMessage).toBe("Неизвестная ошибка");
+	expect(JSON.parse(body.payload).error.message).toBe("Неизвестная ошибка");
+});
+```
+
+### Delivery lifecycle
+
+В package/feature test проверяйте:
+
+- отсутствующий id не вызывает adapter;
+- `sent` не отправляется повторно;
+- `sending` не отправляется повторно;
+- success переводит status в `sent` и задаёт ISO `sentUtc`;
+- adapter error переводит status в `failed`;
+- исходный error сохраняет identity и выбрасывается повторно;
+- retry после `failed` снова вызывает adapter.
+
+Adapter удобно делать mock-функцией:
+
+```ts
+const adapter = vi.fn<ErrorReportDeliveryAdapter>().mockResolvedValue(undefined);
+```
+
+Не помещайте реальные stack traces, cookies, tokens или пользовательские данные в test snapshots.
+
+## Частые ошибки
+
+### Передавать draft вместо body
+
+Adapter contract уже получает подготовленный `body`. Не сериализуйте `context.draft` вместо него.
+
+### Дважды сериализовать `payload`
+
+`body.payload` уже string:
+
+```ts
+JSON.stringify(body)
+```
+
+правильно сериализует outer HTTP body. Не делайте `body.payload = JSON.stringify(body.payload)`.
+
+### Считать `sending` надёжной блокировкой
+
+Это local lifecycle guard. Server idempotency всё равно нужна.
+
+### Поглощать adapter error в UI
+
+Функция намеренно rethrow-ит error. Покажите feedback и оставьте возможность retry.
+
+### Добавлять transport в shared delivery module
+
+Endpoint и auth policy специфичны проекту. Они должны оставаться adapter-ом host application.
+
+## Ошибки и безопасность
+
+- Ошибка adapter-а не поглощается: вызывающий код обязан её обработать.
+- Не добавляйте secrets в draft. Delivery layer не выполняет дополнительную redaction всего payload.
+- `queryClient` передаётся adapter-у, но модуль сам не инвалидирует queries.
+- Функция управляет локальным draft store; не вызывайте её в среде без подходящего storage/runtime, если draft store там недоступен.
+- Статус `sent` означает успешное завершение adapter-а, а не обязательное подтверждение бизнес-обработки backend-ом.
+- Delivery body содержит stack trace и diagnostic payload: передавайте его только по защищённому каналу авторизованному endpoint.
+- Не логируйте `body.payload` целиком в production.
+- Redaction должна происходить при сборе draft в `foundation-lib`; delivery boundary не может безопасно угадать все domain secrets.
+
+## FAQ
+
+### Почему функции нужен `QueryClient`, даже если adapter его не использует?
+
+Это единый adapter context. Он позволяет OData operations и cache synchronization без глобального QueryClient.
+
+### Можно ли отправить report, которого нет в store?
+
+Нет. `sendErrorReport` принимает id существующего draft и вернёт `undefined`.
+
+### Можно ли изменить body перед отправкой?
+
+Да, внутри project adapter можно построить backend-specific envelope. Не мутируйте входной body; создайте новый object.
+
+### Когда разрешён retry?
+
+После status `failed`. `sent` и `sending` являются no-op states.
+
+### Кто отвечает за offline queue?
+
+Не этот модуль. Он хранит lifecycle одного draft и вызывает adapter. Background sync/retry scheduler должен быть отдельной явно спроектированной инфраструктурой.
+
+## Полный API
+
+| Export | Назначение |
+| --- | --- |
+| `createErrorReportDeliveryBody` | Строит сериализуемый backend body |
+| `sendErrorReport` | Управляет status и вызывает adapter |
+| `ErrorReportDeliveryBody` | Поля delivery payload |
+| `ErrorReportDeliveryContext` | `draft` и `queryClient` для adapter-а |
+| `ErrorReportDeliveryAdapter` | Контракт функции доставки |
+| `SendErrorReportOptions` | `adapter` и `queryClient` |

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.