@ryuzaki13/react-foundation-api 1.1.15 → 1.1.17

package/src/adt/README.mdx

@@ -0,0 +1,164 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation API/SAP/ADT Transports" />
+
+# SAP ADT transports через `@ryuzaki13/react-foundation-api/adt`
+
+Модуль получает transport requests текущего пользователя из SAP ADT endpoint и преобразует XML в простой массив объектов.
+
+## Содержание
+
+- [Когда использовать](#когда-использовать)
+- [Установка и импорт](#установка-и-импорт)
+- [Быстрый старт](#быстрый-старт)
+- [`fetchUserTransports`](#fetchusertransports)
+- [`parseUserTransportsXml`](#parseusertransportsxml)
+- [Формат результата](#формат-результата)
+- [Ошибки и ограничения](#ошибки-и-ограничения)
+- [Полный API](#полный-api)
+
+## Когда использовать
+
+Используйте `adt`, если backend доступен по `/sap/bc/adt/cts/transports` и возвращает ADT XML. Если нужны отдельные UI2 списки workbench/customizing в JSON, используйте [`@ryuzaki13/react-foundation-api/transport`](../transport/README.mdx).
+
+```text
+SAP ADT XML
+    │
+    ▼
+parseUserTransportsXml
+    │
+    ▼
+UserTransport[]
+```
+
+## Установка и импорт
+
+```bash
+npm install @ryuzaki13/react-foundation-api @ryuzaki13/react-foundation-lib fast-xml-parser
+```
+
+```ts
+import { fetchUserTransports, parseUserTransportsXml } from "@ryuzaki13/react-foundation-api/adt";
+
+import type { UserTransport } from "@ryuzaki13/react-foundation-api/adt";
+```
+
+## Быстрый старт
+
+```ts
+async function loadTransports() {
+	try {
+		const transports = await fetchUserTransports();
+		return transports;
+	} catch (error) {
+		console.error("Не удалось получить transports", error);
+		return [];
+	}
+}
+```
+
+`fetchUserTransports` возвращает Promise. Пока он выполняется, данных ещё нет; ошибку нужно обработать через `try/catch`, TanStack Query или error boundary владельца сценария.
+
+## `fetchUserTransports`
+
+Функция выполняет GET:
+
+```text
+/sap/bc/adt/cts/transports?_action=FIND&trfunction=K
+```
+
+Запрос отправляется через SAP/OData transport пакета с:
+
+- `Accept: application/xml, text/xml, */*`;
+- cookies через `credentials: include`;
+- SAP language/client и SSO policy общего OData transport;
+- пустым base URL, потому что ADT endpoint уже содержит `/sap/...`.
+
+Ответ читается как text и передаётся `parseUserTransportsXml`.
+
+Если сервер вместо XML вернул HTML login/error page, функция выбросит ошибку. Это защищает UI от ситуации, когда HTML ошибочно принимается за пустой список transports.
+
+## `parseUserTransportsXml`
+
+Parser можно использовать отдельно, например в тесте или при получении XML другим transport:
+
+```ts
+const xml = `
+<root>
+	<CTS_REQ_HEADER>
+		<TRKORR>DEVK900001</TRKORR>
+		<AS4TEXT>Исправление отчёта</AS4TEXT>
+		<AS4USER>IVANOV</AS4USER>
+		<TARSYSTEM>QAS</TARSYSTEM>
+		<TRFUNCTION>K</TRFUNCTION>
+		<TRSTATUS>D</TRSTATUS>
+	</CTS_REQ_HEADER>
+</root>`;
+
+const transports = parseUserTransportsXml(xml);
+```
+
+Алгоритм:
+
+1. Пустая или состоящая из пробелов строка превращается в `[]`.
+2. XML разбирается `fast-xml-parser`.
+3. Во вложенной структуре рекурсивно ищутся узлы `CTS_REQ_HEADER`.
+4. Поля преобразуются в `UserTransport`.
+5. Записи без непустого `TRKORR` отбрасываются.
+6. Дубликаты `transportNo` удаляются; сохраняется первая запись.
+7. Если header-узлы не найдены, parser ищет вложенные `TRKORR` и создаёт минимальные записи.
+
+Parser делает `trim` строковых полей, но не декодирует бизнес-значения статуса/function и не проверяет их по справочнику SAP.
+
+Некорректный XML может привести к исключению parser-а. Функция не заменяет его пустым массивом: повреждённый ответ должен быть виден как ошибка.
+
+## Формат результата
+
+```ts
+interface UserTransport {
+	transportNo: string;
+	description?: string;
+	owner?: string;
+	targetSystem?: string;
+	function?: string;
+	status?: string;
+	parentTransportNo?: string;
+}
+```
+
+Соответствие XML:
+
+| XML | Поле | Значение |
+| --- | --- | --- |
+| `TRKORR` | `transportNo` | Обязательный номер transport |
+| `AS4TEXT` | `description` | Описание |
+| `AS4USER` | `owner` | Владелец |
+| `TARSYSTEM` | `targetSystem` | Целевая система |
+| `TRFUNCTION` | `function` | SAP transport function |
+| `TRSTATUS` | `status` | SAP status |
+| `STRKORR` | `parentTransportNo` | Родительский request/task |
+
+Optional-поле может быть `undefined`. Проверяйте его перед отображением:
+
+```ts
+const label = transport.description
+	? `${transport.transportNo} — ${transport.description}`
+	: transport.transportNo;
+```
+
+## Ошибки и ограничения
+
+- `fast-xml-parser` должен быть установлен в host, использующем этот entrypoint.
+- Это не generic ADT client: endpoint и query parameters зафиксированы.
+- Функция не создаёт/не освобождает transport и не проверяет authorization.
+- SSO/cookies требуют browser/proxy окружения SAP. На server runtime поведение зависит от переданного глобального `fetch` и cookie boundary.
+- HTML-response, HTTP error и XML parse error не превращаются в `[]`.
+- Дедупликация выполняется только по `transportNo` и сохраняет первую найденную запись.
+
+## Полный API
+
+| Export | Назначение |
+| --- | --- |
+| `fetchUserTransports` | Загружает и разбирает ADT XML |
+| `parseUserTransportsXml` | Преобразует XML string в массив |
+| `UserTransport` | Контракт результата |

package/src/async/README.mdx

@@ -0,0 +1,253 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation API/Orchestration/Async Tasks" />
+
+# Асинхронные задачи через `@ryuzaki13/react-foundation-api/async`
+
+Модуль запускает независимые Promise-задачи, сохраняет связь результата с исходным элементом и формирует удобную сводку для UI/логов.
+
+## Какой runner выбрать
+
+| Сценарий | Функция |
+| --- | --- |
+| Задач немного, можно начать все одновременно, любая ошибка должна завершить batch исключением | `runAsyncTasks` |
+| Нужно ограничить число одновременных запросов, показать progress или поддержать abort | `runConcurrentTasks` |
+
+Обе функции выполняют задачи параллельно. Они не создают web workers и не ускоряют CPU-bound JavaScript: Promise-concurrency полезна прежде всего для I/O — HTTP, чтения storage и других async операций.
+
+## Импорт
+
+```ts
+import {
+	AsyncTasksError,
+	ConcurrencyPartialError,
+	runAsyncTasks,
+	runConcurrentTasks
+} from "@ryuzaki13/react-foundation-api/async";
+
+import type {
+	AsyncTask,
+	RunAsyncTasksResult,
+	RunConcurrentTasksOptions,
+	RunConcurrentTasksResult
+} from "@ryuzaki13/react-foundation-api/async";
+```
+
+Модуль не требует React или TanStack Query.
+
+## База: `async`, `Promise` и `await`
+
+`async`-функция всегда возвращает `Promise`. `await` приостанавливает только текущую async-функцию, а не весь browser thread:
+
+```ts
+async function loadName() {
+	const response = await fetch("/api/me");
+	return response.text();
+}
+
+const namePromise = loadName(); // Promise<string>.
+const name = await namePromise; // string.
+```
+
+Ошибку Promise обрабатывают через `try/catch` вокруг `await`.
+
+## `runAsyncTasks`
+
+### Быстрый старт
+
+```ts
+const result = await runAsyncTasks([
+	{ name: "profile", run: () => fetchProfile() },
+	{ name: "settings", run: () => fetchSettings() }
+]);
+
+console.log(result.summary);
+// { total: 2, succeeded: 2, failed: 0 }
+```
+
+Все `run` запускаются сразу через `Promise.all`. Важное отличие от обычного `Promise.all`: ошибка одной задачи перехватывается внутри runner-а, поэтому остальные задачи успевают завершиться. После завершения всего batch функция либо возвращает полный результат, либо бросает `AsyncTasksError` с тем же полным результатом.
+
+### Обработка частичного успеха
+
+```ts
+try {
+	const result = await runAsyncTasks(tasks, {
+		errorMessage: "Не все стартовые данные загрузились"
+	});
+	useData(result.successes);
+} catch (error) {
+	if (error instanceof AsyncTasksError) {
+		usePartialData(error.result.successes);
+		showErrors(error.result.errors);
+		return;
+	}
+
+	throw error;
+}
+```
+
+`AsyncTasksError.result` содержит:
+
+```ts
+type RunAsyncTasksResult<TResult> = {
+	settled: readonly AsyncTaskSettled<TResult>[];
+	successes: readonly AsyncTaskSuccess<TResult>[];
+	errors: readonly AsyncTaskFailure[];
+	summary: {
+		total: number;
+		succeeded: number;
+		failed: number;
+	};
+};
+```
+
+Элементы `settled`, `successes` и `errors` сохраняют порядок исходного массива. Каждый элемент содержит `index` и `name`.
+
+```ts
+if (item.status === "fulfilled") {
+	console.log(item.data);
+} else {
+	console.error(item.error);
+}
+```
+
+TypeScript сужает union по `status`.
+
+Пустой список возвращает успешный пустой результат. `runAsyncTasks` не имеет встроенного concurrency limit и AbortSignal.
+
+## `runConcurrentTasks`
+
+### Ограничение одновременных запросов
+
+```ts
+const result = await runConcurrentTasks(
+	userIds,
+	async (userId, { signal }) => {
+		const response = await fetch(`/api/users/${userId}`, { signal });
+		if (!response.ok) throw new Error(`HTTP ${response.status}`);
+		return response.json();
+	},
+	{ concurrency: 4 }
+);
+```
+
+Не более четырёх задач будут находиться в работе одновременно. Значение по умолчанию — `4`. Если элементов меньше, workers создаются только по числу элементов.
+
+`concurrency` обязан быть целым числом не меньше `1`:
+
+| Значение | Результат |
+| --- | --- |
+| `4` | Работает |
+| `1` | Последовательное выполнение |
+| `0`, `-1` | `RangeError` |
+| `1.5`, `NaN` | `TypeError` |
+
+### Ошибки отдельных элементов
+
+Runner не бросает ошибки отдельных задач. Он помещает их в `result.errors` и продолжает обработку:
+
+```ts
+const result = await runConcurrentTasks(inputs, task);
+
+if (result.errors.length > 0) {
+	for (const failure of result.errors) {
+		console.error(failure.index, failure.input, failure.error);
+	}
+}
+```
+
+Исключение самой функции возможно при невалидном `concurrency` или если callback `onProgress`/`onItemSuccess`/`onItemError` сам бросил ошибку. Callbacks должны быть безопасными и быстрыми.
+
+### Progress
+
+```ts
+await runConcurrentTasks(files, uploadFile, {
+	concurrency: 3,
+	onProgress(progress) {
+		setProgress(progress.percentage);
+	},
+	onItemSuccess(item) {
+		console.log("Загружен", item.input.name);
+	},
+	onItemError(item) {
+		console.error("Ошибка", item.input.name, item.error);
+	}
+});
+```
+
+`onProgress` вызывается после каждой завершённой задачи. В первом вызове процент уже больше нуля; отдельного начального события `0%` нет.
+
+```ts
+type ConcurrentTaskProgress<TInput, TResult> = {
+	total: number;
+	completed: number;
+	succeeded: number;
+	failed: number;
+	running: number;
+	pending: number;
+	percentage: number;
+	aborted: boolean;
+	lastSettled?: ConcurrentTaskSettled<TInput, TResult>;
+};
+```
+
+`percentage` округляется через `Math.round`.
+
+### Abort
+
+```ts
+const controller = new AbortController();
+
+const promise = runConcurrentTasks(urls, async (url, { signal }) => {
+	const response = await fetch(url, { signal });
+	return response.text();
+}, {
+	concurrency: 2,
+	signal: controller.signal
+});
+
+controller.abort();
+const result = await promise;
+```
+
+После abort новые задачи не стартуют. Уже начатая операция прервётся только если сама использует переданный `signal`. Runner ждёт завершения начатых tasks и возвращает:
+
+- `aborted: true`;
+- обработанные элементы в `settled`;
+- не начатые элементы в `unprocessed`.
+
+Abort не является ошибкой runner-а и сам по себе не приводит к `throw`.
+
+### Порядок результата
+
+Tasks могут завершаться в любом порядке, callbacks идут в порядке фактического завершения. Итоговые `settled`, `successes`, `errors` и `unprocessed` собираются по исходным индексам, поэтому результат детерминирован относительно input.
+
+## `ConcurrencyPartialError`
+
+`runConcurrentTasks` сам не создаёт этот error. Класс нужен, если слой приложения хочет преобразовать частичный результат в исключение:
+
+```ts
+const result = await runConcurrentTasks(inputs, task);
+
+if (result.errors.length > 0 || result.aborted) {
+	throw new ConcurrencyPartialError("Batch выполнен частично", result);
+}
+```
+
+Не путайте его с `AsyncTasksError`: первый создаёт consumer по своей policy, второй автоматически бросает `runAsyncTasks`.
+
+## Практические рекомендации
+
+- Не ставьте слишком большой concurrency: browser, proxy и backend имеют свои лимиты.
+- Для write-операций продумайте идемпотентность: retry может повторить уже выполненное действие.
+- Не меняйте input objects внутри task, если те же значения использует UI.
+- Обрабатывайте `unknown` error через безопасный normalizer.
+- Не используйте runner вместо TanStack Query cache для одного и того же resource.
+- Если задача зависит от результата предыдущей, это не независимый batch: выполните зависимые шаги последовательно.
+
+## Полный API
+
+| Группа | Exports |
+| --- | --- |
+| All-at-once | `runAsyncTasks`, `AsyncTasksError`, `AsyncTask`, `AsyncTaskSuccess`, `AsyncTaskFailure`, `AsyncTaskSettled`, `RunAsyncTasksResult`, `RunAsyncTasksOptions` |
+| Bounded concurrency | `runConcurrentTasks`, `ConcurrencyPartialError`, `ConcurrentTaskContext`, `ConcurrentTaskFn`, `ConcurrentTaskSuccess`, `ConcurrentTaskError`, `ConcurrentTaskSettled`, `ConcurrentTaskUnprocessed`, `ConcurrentTaskProgress`, `RunConcurrentTasksOptions`, `RunConcurrentTasksResult` |

package/src/error-report/README.mdx

@@ -0,0 +1,148 @@
+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`.
+
+## `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`.
+
+## 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-а.
+
+## Повторная отправка и concurrency
+
+После `failed` функцию можно вызвать повторно. Проверка `sending` защищает от обычного повторного нажатия, но это не распределённая блокировка: два практически одновременных вызова могут успеть прочитать старый статус до его обновления. Backend желательно сделать идемпотентным по `reportId`.
+
+## Ошибки и безопасность
+
+- Ошибка adapter-а не поглощается: вызывающий код обязан её обработать.
+- Не добавляйте secrets в draft. Delivery layer не выполняет дополнительную redaction всего payload.
+- `queryClient` передаётся adapter-у, но модуль сам не инвалидирует queries.
+- Функция управляет локальным draft store; не вызывайте её в среде без подходящего storage/runtime, если draft store там недоступен.
+- Статус `sent` означает успешное завершение adapter-а, а не обязательное подтверждение бизнес-обработки backend-ом.
+
+## Полный API
+
+| Export | Назначение |
+| --- | --- |
+| `createErrorReportDeliveryBody` | Строит сериализуемый backend body |
+| `sendErrorReport` | Управляет status и вызывает adapter |
+| `ErrorReportDeliveryBody` | Поля delivery payload |
+| `ErrorReportDeliveryContext` | `draft` и `queryClient` для adapter-а |
+| `ErrorReportDeliveryAdapter` | Контракт функции доставки |
+| `SendErrorReportOptions` | `adapter` и `queryClient` |