# ADR-0011. SDK из спецификаций OpenAPI

- Статус: принято, реализуется на этапе 5 (5.6)
- Дата: 2026-10-01

## Контекст

Интеграторы (кассы, CRM, собственные продукты компании) должны встраиваться за день, без ручной работы с
идемпотентностью, повторами, токенами и подписями вебхуков. SDK нужны на PHP и TypeScript. Спецификации
OpenAPI — источник истины (ADR-0006): SDK не должен расходиться ни с ними, ни с поведением API.

## Решение

- **Свой генератор** в `sdk/generator` (PHP), без сторонних генераторов: openapi-generator требует Java и
  даёт громоздкий код, генераторы из npm и Composer тянут зависимости и небезопасный для удаления типов
  TypeScript. Наши спецификации используют узкое подмножество JSON Schema, генератор работает в **закрытом
  мире**: незнакомая конструкция останавливает генерацию с JSON-указателем (`sdk/generator/README.md`).
- **Сгенерированный код коммитится** и проходит ревью вместе с изменением спецификации; тест сравнивает его
  со свежей генерацией и падает при расхождении. Генерация детерминирована: порядок спецификации, без дат и
  хешей.
- **Имена из спецификации без переименований:** метод — `operationId`, аргументы и ключи — имена параметров и
  свойств, типы — имена схем. PHP SDK отдаёт массивы с формами PHPStan, а не DTO: совместимо вперёд, без
  расхождений гидрации, микросекунды времени не теряются.
- **Сгенерированное и ручное разделены:** генератор пишет типы, методы операций и метаданные операций; ручное
  ядро (`ClientBase`) отправляет запросы, отвечает за аутентификацию, идемпотентность, повторы, ошибки и
  пагинацию, одинаково в обоих SDK. Поведение закреплено общими эталонными векторами `sdk/conformance`.
- **Каталог ошибок** (`x-problem-codes`, ADR-0006) даёт константы кодов; `x-safe-to-retry` — повтор POST без
  ключа идемпотентности.
- **PHP SDK** — `loyal/sdk`, PHP 8.2+, без зависимостей во время выполнения (curl; адаптер PSR-18 по желанию).
  **TypeScript SDK** — ESM, Node 22+, Deno, Bun, без зависимостей во время выполнения; `typescript` — единственная
  зависимость разработки (проверка типов и сборка `.d.ts`).

## Последствия

- Изменение спецификации требует `composer sdk:generate`; новая конструкция схемы — сначала расширения
  генератора с тестами.
- Одна версия у обоих SDK (`sdk/VERSION`), 0.x до заморозки API перед пилотом; публикация — после выбора имён
  пакетов, лицензии и реестров.

## Третий API: клиент участника (этап 6j-2)

- Генератор читает и API участника (`docs/api/member-v1.yaml`, ADR-0018): `MemberOperations`, `MemberSpec`,
  `MemberTypes` в PHP, `member-operations.ts` и `member-types.ts` в TS. Расширять генератор не пришлось.
- `MemberClient` в обоих SDK: сеанс участника `lms_…` и необязательный поставщик сеансов, который заменяет
  отвергнутый сеанс один раз за вызов, как обновление токена партнёра; `endSession` закрывает сеанс без обновления, и
  401 на нём — успех. Сайт сеанса уходит заголовком `Origin`, который SDK ставит сам вне браузера; в браузере его ставит
  браузер. Клиент участника разрешён в браузере.
- `DELETE` безопасен для повтора, как `GET`. Правила — в контракте `sdk/README.md` («Клиент участника»), векторы
  23–27 закрепляют их для обоих SDK.
