# PHP SDK платформы лояльности

`loyal/sdk` — клиент Runtime API (кассы, сайты, приложения), Management API (партнёры и мерчанты) и API участника
(виджеты участника на сайте мерчанта), проверка подписей вебхуков и помощники для тестов. Поведение SDK — контракт [sdk/README.md](../README.md), закреплённый
эталонными векторами [sdk/conformance](../conformance/README.md); TypeScript SDK ведёт себя так же.

- PHP 8.2 и новее, `ext-curl`, `ext-json`; никаких пакетов Composer во время выполнения.
- Методы — по одному на операцию спецификации, с именем `operationId` и аргументами с именами её параметров:
  `registerReceipt(body: …)`, `confirmReceipt(receipt: …, body: …)`, `getPointsHistoryAll(member: …, limit: 100)`.
- Тела и ответы — ассоциативные массивы; их формы описаны для PHPStan и IDE в `Loyal\Sdk\Generated\RuntimeTypes`,
  `ManagementTypes` и `MemberTypes` (`@phpstan-import-type Receipt from RuntimeTypes`).
- Деньги, баллы и количества — целые в минимальных единицах (копейки, тысячные доли); дробных чисел SDK не создаёт.

## Установка

Пакет пока не опубликован: имя, лицензия и реестр выбираются перед пилотом. До этого — репозиторий-зеркало
каталога `sdk/php` или путь:

```json
{
    "repositories": [{"type": "path", "url": "../loyal/sdk/php"}],
    "require": {"loyal/sdk": "*"}
}
```

Необязательные пакеты: `psr/http-client` и `psr/http-factory` — для `Psr18Transport`, `psr/simple-cache` — для
`Psr16TokenStore`.

## Касса: Runtime API

```php
use Loyal\Sdk\ClientOptions;
use Loyal\Sdk\RequestOptions;
use Loyal\Sdk\RuntimeClient;

$till = RuntimeClient::create(getenv('LOYAL_TERMINAL_KEY'), new ClientOptions(
    baseUrl: 'https://api.example.com',
    appInfo: 'MyPOS/2.1',                     // попадёт в User-Agent
));
// или RuntimeClient::fromEnv(): LOYAL_BASE_URL и LOYAL_TERMINAL_KEY

$input = [
    'purchased_at' => '2026-10-11T14:59:58+03:00',
    'member' => ['phone' => '+79000000001'],
    'lines' => [['id' => '1', 'sku' => 'LATTE-M', 'quantity' => 1000, 'amount' => 25000]], // 1 шт., 250,00 ₽
    'redeem_maximum' => true,
];
$calculation = $till->calculateReceipt(body: $input);   // ничего не меняет, можно звать сколько угодно

$receipt = $till->registerReceipt(
    body: ['number' => '1042', 'business_date' => '2026-10-11'] + $input,
    options: new RequestOptions(idempotencyKey: 'receipt:till-7:2026-10-11:1042'),
);
$till->confirmReceipt(receipt: $receipt['id'], body: ['fiscal' => ['drive' => '…', 'document' => '1042', 'sign' => '…']]);

foreach ($till->getPointsHistoryAll(member: $memberId, limit: 100) as $entry) {
    // все записи всех страниц по одной
}
```

Ключ кассы — `lk_…` (`lk_test_…` в песочнице). Формат проверяется сразу: ключ с пробелом, переводом строки или
чужого типа — `ConfigurationException` до любого запроса.

## Партнёр и мерчант: Management API

```php
use Loyal\Sdk\Auth\Psr16TokenStore;
use Loyal\Sdk\Exception\ConflictException;
use Loyal\Sdk\Generated\ProblemCode;
use Loyal\Sdk\ManagementClient;

$partner = ManagementClient::forPartner(
    getenv('LOYAL_CLIENT_ID'),                // lc_…
    getenv('LOYAL_CLIENT_SECRET'),            // lcs_…
    new ClientOptions(baseUrl: 'https://api.example.com'),
    scopes: null,                             // null — все скоупы клиента; иначе ['merchants', 'programs']
    tokenStore: new Psr16TokenStore($cache),  // под PHP-FPM; по умолчанию — память процесса
);

try {
    $merchant = $partner->createMerchant(body: ['name' => 'Кофейня «Зерно»', 'external_id' => 'crm-1']);
    $merchantId = $merchant['id'];
} catch (ConflictException $e) {
    if (! $e->is(ProblemCode::MERCHANT_EXISTS)) {
        throw $e;
    }
    $merchantId = $e->extension('merchant_id');
}

$m = $partner->forMerchant($merchantId);      // новый клиент; $partner не меняется
$program = $m->createProgram(body: ['name' => 'Зерно+', 'timezone' => 'Europe/Moscow', 'currency' => 'RUB']);

// lm_…: ключ мерчанта уже выбирает мерчанта, forMerchant() ему не нужен
$own = ManagementClient::forMerchantKey(getenv('LOYAL_MERCHANT_KEY'), new ClientOptions(baseUrl: 'https://api.example.com'));
```

- Токен партнёра запрашивается при первом вызове (RFC 6749, client credentials, HTTP Basic) и переиспользуется,
  пока до истечения больше 60 секунд. Ключ кэша — `sha256(baseUrl|client_id|скоупы по алфавиту)`: клиенты одного
  партнёра делят токен, `forMerchant()` — тоже.
- Под PHP-FPM каждый процесс начинает с пустой памятью, а выдача токенов ограничена 60 запросами в минуту с адреса:
  используйте `Psr16TokenStore` (APCu, Redis, Memcached). В кэше лежат только токен и срок.
- Сбой хранилища токенов не роняет вызовы — ни `InMemoryTokenStore`, ни `Psr16TokenStore` (исключение PSR-16 или
  самого хранилища, например `RedisException`), ни вашей реализации `TokenStore`, что бы она ни бросила: исключение
  `get` — промах (вызов запрашивает токен сам и считает его своим), исключения `put` и `forget` игнорируются (токен
  всё равно используется, а отвергнутый 401 токен вызов не берёт снова). Пока общее хранилище недоступно, каждый
  вызов запрашивает токен сам и может упереться в ограничение выдачи (429).
- Запрос токена принадлежит клиенту, а не вызову: он повторяется со своим счётчиком по `maxRetries` и
  `maxRetryAfter` из `ClientOptions` и уходит с тайм-аутами клиента. `RequestOptions` вызова (`maxRetries`,
  `timeout`, `headers`) на него не действуют: вызов с `maxRetries: 0` получает токен с повторами клиента. Попытки
  самой операции, в том числе повтор после обновления токена, идут по настройкам вызова.
- Запрос токена — не попытка операции. Если токен получить не удалось (точка выдачи не ответила), ошибка
  `TransportException` несёт флаг всего вызова: `mayHaveBeenProcessed() === false`, если запрос операции так и не
  ушёл, и `true`, если более ранняя попытка того же вызова могла быть обработана (оборвалась после отправки или
  получила любой ответ, кроме 401 и 429).
- 401 на токене из кэша (его получил более ранний вызов или другой процесс): SDK забывает токен, получает новый и
  один раз повторяет запрос с тем же ключом идемпотентности, без паузы и не расходуя повторы.
- 401 на токене, который получил этот же вызов (в этой или более ранней попытке, в том числе после обновления), —
  окончательная `AuthenticationException` без второго запроса токена: только что выданный токен отвергнут, значит,
  неверны учётные данные или окружение. Обновление токена — не больше одного раза за вызов.
- `Loyal-Merchant` уходит только у операций, которые его объявляют; операциям партнёра вне мерчантов
  (`listMerchants`, `listEventTypes`) он не отправляется.

## Участник: API участника

Бэкенд сайта, где участник вошёл, открывает ему сеанс (скоуп `widgets`; код для кассы — ещё и `members`) и отдаёт
токен странице: виджеты говорят с API участника сами (ADR-0018). Сам PHP-клиент участника нужен серверу, который
говорит от имени участника, — например, странице, которую сервер рисует сам.

```php
use Loyal\Sdk\ClientOptions;
use Loyal\Sdk\MemberClient;

$site = $partner->forMerchant($merchantId);
$body = [
    'program_id' => $programId,
    'external_id' => $userId,                                // или member_id
    'origin' => 'https://shop.example.com',                  // сайт виджетов
    'scopes' => ['profile', 'history', 'presentation_code'], // по умолчанию — profile и history; код для кассы
];                                                           // требует у ключа ещё и скоуп members
$session = $site->issueMemberSession(body: $body);

$member = MemberClient::create(
    $session['token'],                         // lms_… (в песочнице lms_test_…), живёт минуты
    'https://shop.example.com',                // уходит заголовком Origin: сеанс работает только со своего сайта
    new ClientOptions(baseUrl: 'https://api.example.com'),
    sessionProvider: fn (): string => $site->issueMemberSession(body: $body)['token'],
);

$profile = $member->getProfile();              // баллы, уровень, штампы
$code = $member->issuePresentationCode();      // код и QR-картинка для кассы
// Скоупы consents и details: участник сам даёт или отзывает согласие на рекламу и меняет имя.
$member->changeConsent(kind: 'marketing_sms', body: ['granted' => true, 'version' => 3]); // версия, которую он видел
$member->changeDetails(body: ['first_name' => 'Анна']);
// E-mail (скоуп details): письмо с кодом через почту мерчанта, код из письма — адрес подтверждён.
$letter = $member->startEmailConfirmation(body: ['email' => 'anna@example.com']);
$member->confirmEmail(body: ['confirmation_id' => $letter['confirmation_id'], 'code' => $codeFromLetter]);
$member->endSession();                         // участник вышел
```

- Поставщик сеансов необязателен: клиент зовёт его, когда сеанса у него нет, — сервер отверг прежний (истёк, закрыт,
  отозван ключ сайта) или участник вышел. Сеанс, с которым клиент создан или который поставщик дал раньше, на 401
  заменяется один раз и запрос повторяется; 401 на только что полученном сеансе — `AuthenticationException`.
  Исключение поставщика доходит до вызова как есть. Без поставщика клиент после 401 или `endSession()` сеанса не
  имеет: следующий вызов — `ConfigurationException`.
- `endSession()` закрывает сеанс клиента и никогда не зовёт поставщика; уже закрытый сеанс (401) — тоже успех.
- `origin` — сайт так, как его пишет браузер: `https://хост[:порт]` в нижнем регистре, без пути и без порта 443
  (`http://` — только для `localhost`, `127.0.0.1` и `[::1]`).

## Ошибки

Каждая ошибка SDK реализует `Loyal\Sdk\Exception\LoyalException`. Класс определяется статусом ответа, а не телом:

| Исключение | Когда |
|---|---|
| `BadRequestException` | 400 (например, `merchant_required`) |
| `AuthenticationException` | 401 (неверный, отозванный ключ или ключ другого окружения — `environment_mismatch`) |
| `PermissionDeniedException` | 403 (`scope_missing`) |
| `NotFoundException` | 404 |
| `ConflictException` | 409 (`receipt_exists`, `merchant_exists`, `insufficient_points`) |
| `ValidationException` | 422 (`validation_failed` с `errors()`, `invalid_basket`, `idempotency_key_reused`) |
| `RateLimitException` | 429; `retryAfter()` — секунды ожидания |
| `ServerException` | 500–599 |
| `ApiException` | базовый класс всех выше; сам по себе — другой статус 4xx (410 `verification_expired`) |
| `OAuthException` | точка выдачи токенов отказала (400/401 RFC 6749): `error()`, `errorDescription()` |
| `TransportException` | ответа нет: `mayHaveBeenProcessed()` — могла ли быть обработана хотя бы одна попытка вызова (обрыв после отправки или любой ответ, кроме 401 и 429) |
| `UnexpectedResponseException` | ответ не от API: 2xx без JSON, перенаправление, повторённый курсор страниц |
| `ConfigurationException` | неверные настройки или аргументы — до отправки запроса |
| `WebhookVerificationException` | вебхук не прошёл проверку: `reason()` |

У ошибок ответа API: `status()`, `problemCode()` (константы — `Loyal\Sdk\Generated\ProblemCode`), `is($code)`,
`title()`, `detail()`, `errors()`, `extension('available')`, `requestId()` (назовите его поддержке),
`idempotencyKey()` и `problem()` — тело problem+json целиком. Сообщение — `<статус> <код>: <title>`. Ни сообщение,
ни поля ошибки не содержат ключей, токенов, адресов с параметрами, заголовков и тел запросов; SDK ничего не пишет в
логи. Учётные данные не попадают и в трассировку стека (`#[SensitiveParameter]`, маскирование в дампах), а аргументы
ваших вызовов (тело запроса) попадают в неё, как в любом PHP-коде, пока не включён `zend.exception_ignore_args`.

## Повторы и идемпотентность

Повторы — по контракту ([sdk/README.md](../README.md#повторы)), по умолчанию 2 (`ClientOptions::$maxRetries`, у
вызова — `RequestOptions::$maxRetries`; запрос токена партнёра — всегда по настройкам клиента):

- соединение не установлено — повторяется любой запрос;
- таймаут или обрыв после отправки, 502, 503, 504 — только безопасные для повтора: `GET`, запросы с
  `Idempotency-Key` и операции `calculateReceipt`, `lookupMember`;
- 429 — любой запрос, если `Retry-After` не больше `maxRetryAfter` (60 с); иначе `RateLimitException`;
- 400, 401, 403, 404, 409, 422, 500 — никогда.

Пауза — `Retry-After` или случайная от 0 до `min(8 с, 0,5 с × 2^n)`.

**Идемпотентность.** У операций с `Idempotency-Key` (все записи Runtime API и `adjustMemberPoints`) SDK отправляет
ваш ключ или создаёт UUIDv4 — один на вызов, одинаковый во всех повторах. Ключ есть у каждой ошибки вызова:

```php
try {
    $till->registerReceipt(body: $receipt, options: new RequestOptions(idempotencyKey: $key));
} catch (TransportException|ServerException|UnexpectedResponseException $e) {
    // сервер мог провести чек: сохраните $e->idempotencyKey() и повторите вызов позже с тем же ключом
}
```

`mayHaveBeenProcessed()` относится ко всему вызову, а не к последней попытке: первая попытка оборвалась после
отправки, а оба повтора не смогли соединиться — `true`; 429, а затем два сбоя соединения — `false`.

Лучше детерминированные ключи: `receipt:{касса}:{бизнес-дата}:{номер}` — касса повторит их и после перезапуска.
Ключ — от 1 до 255 видимых символов ASCII (Management API принимает до 200). Ключ у операции без
`Idempotency-Key` (`verifyCode`) — `ConfigurationException`.

Записи Management API без ключа (`createMerchant`, `createLocation`…) после возможной отправки не повторяются:
`TransportException` с `mayHaveBeenProcessed() === true` или `ServerException`. Перед повтором проверьте состояние —
например, мерчанта по `external_id` (повторный `createMerchant` ответит `merchant_exists` с `merchant_id`).

## Вебхуки

```php
use Loyal\Sdk\Exception\WebhookVerificationException;
use Loyal\Sdk\Webhooks\WebhookVerifier;

$verifier = new WebhookVerifier(secrets: [getenv('LOYAL_WEBHOOK_SECRET'), getenv('LOYAL_WEBHOOK_SECRET_PREVIOUS')]);

try {
    $event = $verifier->verify(file_get_contents('php://input'), WebhookVerifier::headersFromServer($_SERVER));
} catch (WebhookVerificationException $e) {
    http_response_code(400);
    exit;
}

// $event->id — одинаков у всех попыток доставки: отсекайте по нему повторы
match ($event->type) {
    'receipt.confirmed' => handleReceipt($event->data),
    default => null,
};
```

- Тело — сырое, до разбора JSON. Заголовки — из `$_SERVER`, PSR-7 (`$request->getHeaders()`) или массива; имена в
  любом регистре.
- Допуск времени — 300 с в обе стороны (`toleranceSeconds`); подписи сравниваются за постоянное время.
- После ротации секрета платформа сутки подписывает новым и прежним: передайте оба.

## Ответы и метаданные

`ClientOptions::$onResponse` получает `Loyal\Sdk\ResponseMeta` на каждый HTTP-ответ, включая промежуточные ответы
повторов и выдачу токена: операция, метод, шаблон пути, статус, длительность, `requestId`, `idempotentReplayed`
(сервер ответил сохранённым ответом на повтор), `rateLimitRemaining` и `environment` (`Loyal-Environment`: покажите
«ТЕСТОВЫЙ РЕЖИМ» на кассе). Адресов, значений параметров, тел и заголовков там нет — можно в метрики и логи.

## Транспорт

- `CurlTransport` (по умолчанию): только https (http — только для `localhost`, `127.0.0.1`, `[::1]`),
  перенаправления не выполняются, сертификат и имя хоста проверяются всегда, TLS 1.2+, соединения
  переиспользуются; можно указать свой набор корневых сертификатов: `new CurlTransport(caBundle: '/path/ca.pem')`.
- `Psr18Transport($client, $factory)`: ваш PSR-18-клиент (прокси, middleware). Таймауты — его собственные.
  - **Перенаправления выключите в самом клиенте.** PSR-18 не запрещает клиенту следовать им (HttpClient Symfony
    по умолчанию следует до 20 перенаправлений — передайте `Psr18Client` клиент с `max_redirects: 0`; `sendRequest()`
    Guzzle им не следует), а перенаправление, выполненное клиентом, SDK не видит и отвергнуть не может. Вернувшийся
    3xx SDK отвергает.
  - Любой сбой клиента считается возможно дошедшим до сервера: PSR-18 не говорит надёжно, ушёл ли запрос (Guzzle
    сообщает обрыв соединения и непрочитанное тело ответа как `RequestExceptionInterface`). Поэтому записи без
    ключа (`createMerchant`, `createLocation`…) через `Psr18Transport` после сбоя не повторяются.
  - Исключение клиента к ошибке не прикладывается: оно несёт запрос PSR-7 с заголовком `Authorization`, а его
    сообщение — адрес. `TransportException` называет только класс исключения.
- Таймауты `ClientOptions`: попытка — 10 с в Runtime API и 30 с в Management API, соединение — 3 с.

## Единицы

```php
use Loyal\Sdk\Support\Units;

Units::money('250.50');              // 25050
Units::quantity('1.5');              // 1500
Units::points('12.5', precision: 1); // 125
Units::toDecimal(25050, 2);          // '250.50'
```

Строковая арифметика без `float`; лишние знаки после запятой — `ConfigurationException`, а не округление.

## Тесты интегратора

```php
use Loyal\Sdk\Testing\MockTransport;
use Loyal\Sdk\Testing\WebhookSigner;

$transport = new MockTransport(
    MockTransport::json(201, ['id' => 'r-1', 'status' => 'reserved']),
    MockTransport::problem(409, 'receipt_exists', 'Чек уже зарегистрирован', ['receipt_id' => 'r-1']),
);
$till = RuntimeClient::create($key, new ClientOptions(baseUrl: 'https://api.example.com', transport: $transport));
// … код кассы …
$transport->assertSent(fn ($request) => $request->header('Idempotency-Key') === 'receipt:7:2026-10-11:1042');

$headers = WebhookSigner::headers('whsec_…', 'evt-1', $body);   // подпись как у платформы
```

- `MockTransport` отдаёт ответы по очереди и записывает запросы (`requests()`, `lastRequest()`, `assertSent()`);
  сбой без ответа — `TransportException::beforeSend()` / `afterSend()` в очереди.
- `ClientOptions(sleeper: …, random: …)` заменяют ожидание перед повтором и случайную паузу — тесты повторов
  не ждут.

## Песочница

Песочница — отдельное развёртывание с теми же API и кодом (ADR-0012). Учётные данные песочницы несут `test_`:
`lk_test_…`, `lm_test_…`, `lc_test_…`, `lcs_test_…`, `lms_test_…`. По ним `$client->environment()` возвращает
`Environment::Sandbox`; сервер отвергает учётные данные другого окружения (401 `environment_mismatch`, у выдачи
токена — `invalid_client`).

```php
use Loyal\Sdk\Testing\Sandbox;

$member = $till->registerMember(body: ['phone' => Sandbox::phone(1), 'consents' => ['program_rules', 'personal_data']]);
// SMS в песочнице не отправляются; код подтверждения тестового телефона — всегда Sandbox::CODE ('000000')
$till->verifyCode(verification: $verificationId, body: ['code' => Sandbox::CODE]);
```

В песочнице — только тестовые телефоны `+7 900 000-00-00 … +7 900 000-99-99` (`Sandbox::phone(0…9999)`) и адреса
`example.com`, `*.test`; другие — 422 `sandbox_test_data_required`.

## Разработка SDK

```powershell
vendor\bin\pest sdk/php/tests                                                  # модульные тесты и векторы
vendor\bin\phpstan analyse -c sdk/php/phpstan.neon --memory-limit=1G --no-progress
vendor\bin\pint --config=sdk/php/pint.json sdk/php                             # стиль (без mb_* — их нет в 8.2)
php sdk/php/tests/smoke.php                                                    # векторы без Composer, на PHP 8.2
```

- `src/Generated` создаёт генератор (`composer sdk:generate`) — руками не правится.
- Код SDK — PHP 8.2: без типизированных констант, `#[\Override]`, `json_validate`, `mb_trim` и других функций
  8.3+; PHPStan проверяет с `phpVersion: 80200`, CI запускает `smoke.php` на PHP 8.2.
- SDK не использует Laravel, Symfony и код приложения; интерфейсы PSR — только в `Psr18Transport` и
  `Psr16TokenStore`.
- Изменение поведения начинается с вектора в `sdk/conformance`, затем меняются оба SDK.
