# 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 перед пилотом; публикация — после выбора имён
  пакетов, лицензии и реестров.