@openaisdk/billing-sdk-node 1.3.0

package/README.md

@@ -0,0 +1,619 @@
+# @openaisdk/billing-sdk-node
+
+Ручной публичный Node.js SDK для Mega-Billing consumer API.
+
+## За что отвечает
+
+- Узкий контракт для backend вашего SaaS: клиенты, checkout, доступ, подписки, usage, чтение счетов, проверка подписи вебхуков.
+- Аутентификация только `Authorization: Bearer <integration key>`. Tenant и project из ключа, не из заголовков.
+- Типы и ошибки, которые видит интегратор. Поведение совпадает с `GET /api/public-json`.
+
+## За что не отвечает
+
+- Полный admin/internal OpenAPI (ключи, провайдер, void счёта) — сгенерированный [`billing-sdk`](../billing-sdk/README.md) или Admin UI.
+- MCP для агентов — [`billing-catalog-mcp`](../billing-catalog-mcp/README.md).
+- Доменные пакеты платформы (`*-domain`): SDK только HTTP-клиент.
+- Хранение секретов, ретраи провайдера, фискализация.
+
+Пакет намеренно открывает узкую consumer-facing поверхность:
+
+| Ресурс              | Методы                                       |
+| ------------------- | -------------------------------------------- |
+| `customers`         | `create`, `retrieve`, `list`, `update`       |
+| `subscriptions`     | `retrieve`, `list`, `cancel`                 |
+| `checkout.sessions` | `create`                                     |
+| `access`            | `retrieve`                                   |
+| `meterEvents`       | `create`, `summary`                          |
+| `invoices`          | `retrieve`, `listCreditNotes`                |
+| `webhooks`          | `constructEvent`, `generateTestHeaderString` |
+
+Wave 1 (`customers.create`, `checkout.sessions.create`, `access.retrieve`) — реализованный golden path. Customer & Subscription Lifecycle (`customers.retrieve/list/update`, `subscriptions.*`), thin Invoice Read (`invoices.retrieve`, `invoices.listCreditNotes`) и Wave 4 Usage (`meterEvents.create`, `meterEvents.summary`) следуют зафиксированному public contract: customer, invoice и meter остаются публичными идентификаторами, а replay usage-события задаётся body-полем `identifier`, а не внутренними UUID. Void / credit note create остаются admin-only.
+
+Аутентификация только через `Authorization: Bearer <integration key>`. В опциях клиента и сигнатурах методов нет `x-tenant-id`, `xTenantId` или `projectId` — tenant и project определяются самим ключом.
+
+Требования: Node.js ≥ 20.
+
+## Установка
+
+```bash
+pnpm add @openaisdk/billing-sdk-node
+```
+
+## Инициализация
+
+Для hosted-окружения достаточно integration key вида `bsk_test_...` или `bsk_live_...`. Для local / self-hosted задайте `BILLING_API_URL` в окружении или передайте `baseUrl` явно.
+
+```ts
+import { BillingError, MegaBilling } from '@openaisdk/billing-sdk-node';
+
+const billing = new MegaBilling({
+  apiKey: process.env.BILLING_API_KEY!,
+  // baseUrl: 'http://127.0.0.1:4001', // опционально для local/self-hosted
+  // timeoutMs: 30_000, // опционально, по умолчанию 30s
+});
+```
+
+## Sandbox / live contract
+
+Wave 5 Sandbox не требует второго consumer deploy и не вводит дополнительных env headers:
+
+- один и тот же `baseUrl` обслуживает и test, и live;
+- режим задаётся самим Bearer key: `bsk_test_...` для sandbox/test и `bsk_live_...` для live;
+- consumer не передаёт `x-tenant-id`, `x-project-id`, `x-env` или аналогичный mode header;
+- все consumer-facing resource responses и outbound webhook events несут `livemode: boolean`, чтобы приложение могло явно различать test и live данные.
+
+Практический migration path: для перехода из sandbox в live достаточно подставить live key и повторить smoke flow на связанном live project.
+
+## Golden path
+
+Типичный сценарий consumer-backend: создать customer → открыть checkout → прочитать access state.
+
+```ts
+import { BillingError, MegaBilling } from '@openaisdk/billing-sdk-node';
+
+const billing = new MegaBilling({
+  apiKey: process.env.BILLING_API_KEY!,
+});
+
+const workspace = {
+  id: 'ws_123',
+  name: 'MegaRetro Workspace',
+  ownerEmail: 'owner@example.com',
+};
+
+async function main() {
+  const customer = await billing.customers.create(
+    {
+      externalType: 'workspace',
+      externalId: workspace.id,
+      email: workspace.ownerEmail,
+      name: workspace.name,
+    },
+    {
+      idempotencyKey: `customer:${workspace.id}`,
+    }
+  );
+
+  const checkout = await billing.checkout.sessions.create(
+    {
+      customer: customer.id,
+      price: 'price_pro_monthly',
+      successUrl: 'https://app.example.com/billing/success',
+      cancelUrl: 'https://app.example.com/billing',
+    },
+    {
+      idempotencyKey: `checkout:${workspace.id}:price_pro_monthly:v1`,
+    }
+  );
+
+  const access = await billing.access.retrieve(customer.id);
+
+  console.log(customer.requestId, checkout.requestId, access.requestId);
+  console.log(customer.livemode, checkout.livemode, access.livemode);
+  console.log(checkout.confirmationUrl);
+  console.log(access.status, access.features, access.limits);
+}
+
+main().catch((error) => {
+  if (error instanceof BillingError) {
+    console.error(error.code, error.status, error.requestId, error.param);
+    return;
+  }
+
+  throw error;
+});
+```
+
+Запускаемый пример из репозитория:
+
+```bash
+BILLING_API_KEY=bsk_test_... \
+BILLING_API_URL=http://127.0.0.1:4001 \
+BILLING_PRICE_ID=price_pro_monthly \
+pnpm --filter @openaisdk/billing-sdk-node run quickstart
+```
+
+## Lifecycle-сценарий
+
+Типичный экран «Биллинг» в consumer-продукте: показать текущую подписку и дать отменить её в конце периода.
+
+```ts
+const customer = await billing.customers.retrieve('cus_123');
+const subscriptions = await billing.subscriptions.list({
+  customer: customer.id,
+  status: 'active',
+});
+
+const [current] = subscriptions.data;
+
+if (current) {
+  await billing.subscriptions.cancel(
+    current.id,
+    { atPeriodEnd: true },
+    { idempotencyKey: `subscription-cancel:${current.id}:v1` }
+  );
+}
+
+const access = await billing.access.retrieve(customer.id);
+```
+
+Отмена в конце периода не снимает доступ немедленно: до `currentPeriodEnd` `billing.access.retrieve(...)` продолжит возвращать активный доступ.
+
+## Usage-based billing
+
+Типичный metered-flow в consumer backend: отправить usage по публичному customer и затем прочитать usage summary по публичному meter.
+
+```ts
+const acceptedEvent = await billing.meterEvents.create({
+  eventName: 'ai_tokens',
+  customer: 'cus_123',
+  value: 1250,
+  identifier: 'generation_gen_987',
+  timestamp: '2026-08-10T00:00:00.000Z',
+  dimensions: { model: 'gpt-5' },
+});
+
+const summary = await billing.meterEvents.summary('ai_tokens', {
+  customer: 'cus_123',
+  startTime: '2026-08-10T00:00:00.000Z',
+  endTime: '2026-08-10T01:00:00.000Z',
+  valueGroupingWindow: 'hour',
+});
+
+console.log(acceptedEvent.id, acceptedEvent.status, acceptedEvent.requestId);
+console.log(summary.data[0]?.aggregatedValue, summary.requestId);
+```
+
+Правила:
+
+- `eventName` и аргумент `meterId` в `summary(...)` используют публичный meter code, а не внутренний UUID;
+- `identifier` обязателен и задаёт replay/dedup contract для create: повтор с тем же `identifier` и тем же нормализованным payload (customer, meter, value, dimensions и — только если он был передан явно — `timestamp`) возвращает тот же event, а другой payload — `idempotency_key_conflict`;
+- явный `timestamp` — часть payload fingerprint, поэтому его отсутствие в исходном запросе не мешает retry-safe повтору без `timestamp`: сервер каждый раз подставляет текущее время, но это поле в такой повтор не входит, поэтому ложного конфликта не возникает;
+- открытые события (без `subscriptionId` — SDK его и не принимает) попадают в расчёт нужной подписки по `project + customer + meter` в момент выставления счёта, а не по значению, переданному клиентом;
+- `value` можно передать числом или строкой с неотрицательным целым значением;
+- `valueGroupingWindow` поддерживает `hour` и `day`; для группировки окно должно быть выровнено по UTC-границам;
+- сервер может принять событие асинхронно, поэтому `create(...)` возвращает `status: 'accepted'`.
+
+## Webhooks
+
+Wave 3 добавляет consumer-facing helper для проверки webhook signature поверх уже существующей endpoint/delivery/replay infrastructure.
+
+Поддерживаемый signature format:
+
+```txt
+x-billing-signature: t=1760000000,v1=<hex-hmac>
+```
+
+- подпись считается по строке `"<timestamp>.<rawBody>"`;
+- по умолчанию SDK использует tolerance window `300` секунд;
+- проверять нужно именно raw body до `JSON.parse(...)`;
+- event envelope содержит `livemode`, совпадающий с mode проекта-источника;
+- дедупликация consumer-side handler должна идти по `event.id`;
+- test event использует тот же `v1` scheme, что и production deliveries.
+
+Поддерживаемые event types: `billing.test`, `subscription.*`, `invoice.*`, `payment.failed`, `payment.refunded`, `entitlement.updated`, `entitlement.granted`, `entitlement.revoked`.
+
+### `billing.webhooks.constructEvent(rawBody, signature, secret, options?)`
+
+```ts
+import { BillingWebhookVerificationError, MegaBilling } from '@openaisdk/billing-sdk-node';
+
+const billing = new MegaBilling({
+  apiKey: process.env.BILLING_API_KEY!,
+});
+
+const rawBody = request.rawBody.toString('utf8');
+const signature = request.headers['x-billing-signature'];
+
+try {
+  const event = billing.webhooks.constructEvent(
+    rawBody,
+    Array.isArray(signature) ? signature[0] : signature,
+    process.env.MEGABILLING_WEBHOOK_SECRET!
+  );
+
+  console.log(event.livemode ? 'live webhook' : 'test webhook');
+
+  if (event.type === 'entitlement.updated') {
+    const access = await billing.access.retrieve(event.data.customer!);
+    console.log(access.status, access.features, access.limits);
+  }
+} catch (error) {
+  if (error instanceof BillingWebhookVerificationError) {
+    console.error(error.code, error.message);
+  }
+}
+```
+
+`options`:
+
+| Поле               | По умолчанию | Назначение                                    |
+| ------------------ | ------------ | --------------------------------------------- |
+| `toleranceSeconds` | `300`        | Максимальное допустимое расхождение timestamp |
+| `receivedAt`       | `Date.now()` | Позволяет стабильно тестировать верификацию   |
+
+### `billing.webhooks.generateTestHeaderString(rawBody, secret, timestamp?)`
+
+Helper для локальных тестов и unit/integration specs. Генерирует header в формате `t=...,v1=...`, совместимый с `constructEvent(...)`.
+
+## API
+
+### `billing.customers.create(params, options?)`
+
+`POST /v1/customers`
+
+Создаёт (или идемпотентно возвращает) customer, связанный с сущностью consumer-а через `externalType` + `externalId`.
+
+```ts
+const customer = await billing.customers.create(
+  {
+    externalType: 'workspace',
+    externalId: 'ws_123',
+    email: 'owner@example.com',
+    name: 'MegaRetro Workspace',
+    phone: '+79990000000',
+  },
+  { idempotencyKey: 'customer:ws_123' }
+);
+```
+
+`externalType`: `'workspace' | 'tenant' | 'company' | 'org'`. Поля `email`, `name` и `phone` опциональны. Ответ содержит `livemode`, чтобы consumer мог не смешивать sandbox/live customers в собственных логах и диагностике.
+
+### `billing.customers.retrieve(customerId, options?)`
+
+`GET /v1/customers/{customerId}`
+
+Читает текущее состояние customer по публичному `cus_...` идентификатору.
+
+```ts
+const customer = await billing.customers.retrieve('cus_123');
+```
+
+### `billing.customers.list(params?, options?)`
+
+`GET /v1/customers`
+
+Возвращает страницу customers проекта, определяемого integration key.
+
+```ts
+const customers = await billing.customers.list({
+  limit: 20,
+  startingAfter: 'cus_100',
+  externalType: 'workspace',
+  // externalId: 'ws_123',
+});
+
+for (const customer of customers.data) {
+  console.log(customer.id, customer.externalId);
+}
+
+console.log(customers.hasMore);
+```
+
+Ответ — list envelope: `{ object: 'list', data: Customer[], hasMore: boolean }` плюс `requestId`. Все параметры опциональны; `undefined` в query не отправляется.
+
+### `billing.customers.update(customerId, payload, options?)`
+
+`PATCH /v1/customers/{customerId}`
+
+Обновляет изменяемые контактные поля customer. `externalType` и `externalId` — иммутабельная связка с сущностью consumer-а и через update не меняются. `null` очищает контактное поле, отсутствие поля оставляет текущее значение без изменений.
+
+```ts
+const customer = await billing.customers.update(
+  'cus_123',
+  {
+    name: 'MegaRetro Workspace (renamed)',
+    email: 'billing@example.com',
+    phone: null,
+  },
+  { idempotencyKey: 'customer-update:ws_123:v2' }
+);
+```
+
+### `billing.subscriptions.retrieve(subscriptionId, options?)`
+
+`GET /v1/subscriptions/{subscriptionId}`
+
+Возвращает подписку по публичному `sub_...` идентификатору: `livemode`, `status`, `product`, `price`, границы периода, trial/grace поля и timestamps отмены/завершения.
+
+```ts
+const subscription = await billing.subscriptions.retrieve('sub_123');
+```
+
+`status`: `'pending' | 'trialing' | 'active' | 'past_due' | 'paused' | 'canceled'`.
+
+Подписка описывает биллинговый lifecycle, а не право доступа. Для gate фич в продукте по-прежнему используйте `billing.access.retrieve(...)`.
+
+### `billing.subscriptions.list(params, options?)`
+
+`GET /v1/subscriptions?customer=...`
+
+Возвращает подписки одного customer. Параметр `customer` обязателен: SDK не открывает project-wide перебор подписок.
+
+```ts
+const subscriptions = await billing.subscriptions.list({
+  customer: 'cus_123',
+  status: 'active',
+  limit: 10,
+});
+```
+
+### `billing.subscriptions.cancel(subscriptionId, payload?, options?)`
+
+`POST /v1/subscriptions/{subscriptionId}/cancel`
+
+Отменяет подписку. `atPeriodEnd: true` планирует отмену на конец оплаченного периода, `false` (или отсутствие поля) отменяет немедленно.
+
+```ts
+const subscription = await billing.subscriptions.cancel(
+  'sub_123',
+  { atPeriodEnd: true },
+  { idempotencyKey: 'subscription-cancel:sub_123:v1' }
+);
+
+console.log(subscription.status, subscription.cancelAtPeriodEnd);
+```
+
+Отмена — mutating операция, поэтому она использует `POST` с action-суффиксом, а не `DELETE`: отмена не удаляет ресурс и должна возвращать обновлённое состояние подписки.
+
+### `billing.checkout.sessions.create(params, options?)`
+
+`POST /v1/checkout/sessions`
+
+Создаёт checkout session и возвращает `confirmationUrl` вместе со связанными публичными идентификаторами (`subscription`, `invoice`, `payment`). Redirect сам по себе не подтверждает оплату — источник истины о доступе: `billing.access.retrieve(...)`.
+
+```ts
+const checkout = await billing.checkout.sessions.create(
+  {
+    customer: 'cus_123',
+    price: 'price_pro_monthly',
+    successUrl: 'https://app.example.com/billing/success',
+    cancelUrl: 'https://app.example.com/billing',
+    // promoCode: 'PROMO', // опционально
+  },
+  { idempotencyKey: 'checkout:ws_123:pro-monthly:v1' }
+);
+```
+
+### `billing.access.retrieve(customerId, options?)`
+
+`GET /v1/customers/{customerId}/access`
+
+Возвращает materialized access state: `livemode`, `status`, `features`, `limits`, `currentPeriodEnd`, `graceUntil`.
+
+```ts
+const access = await billing.access.retrieve('cus_123');
+```
+
+Все успешные ответы дополняются полем `requestId` из заголовка `MegaBilling-Request-Id`, если сервер его вернул. Этот header для SDK является единственным authoritative источником correlation ID; возможный `requestId` в JSON body рассматривается только как server echo и не повышается до authoritative client-side значения.
+
+### `billing.meterEvents.create(params, options?)`
+
+`POST /v1/billing/meter-events`
+
+Принимает usage event по публичному `eventName` и публичному `customer`, не раскрывая внутренние `meterId`, `customerAccountId` или `subscriptionId`.
+
+```ts
+const event = await billing.meterEvents.create({
+  eventName: 'ai_tokens',
+  customer: 'cus_123',
+  value: 1250,
+  identifier: 'generation_gen_987',
+  timestamp: '2026-08-10T00:00:00.000Z',
+  dimensions: { model: 'gpt-5' },
+});
+```
+
+Ответ: `billing.meter_event` с полями `id`, `livemode`, `status`, `eventName`, `customer`, `value`, `identifier`, `timestamp`, `dimensions` и `requestId`.
+
+Для безопасного replay повторяйте тот же нормализованный payload с тем же `identifier`. Если исходный запрос не передавал `timestamp`, сервер подставляет текущее время при каждом вызове (включая retry), но само значение `timestamp` не входит в payload fingerprint, когда клиент его не задавал явно — поэтому такой повтор не считается другим payload и не завершается `idempotency_key_conflict`. Если `timestamp` был передан явно в исходном запросе, он становится частью fingerprint, и retry обязан повторить то же самое значение. Public usage contract опирается именно на `identifier`; даже если transport-level `Idempotency-Key` передан вручную, он не заменяет это поле.
+
+Событие не привязывается к конкретной подписке клиентом: биллинг сам находит нужную подписку по `project + customer + meter` в момент расчёта счёта.
+
+### `billing.meterEvents.summary(meterId, params, options?)`
+
+`GET /v1/billing/meters/{meterId}/event-summaries`
+
+Возвращает usage summary по публичному meter code и публичному customer в рамках project, определённого integration key.
+
+```ts
+const summary = await billing.meterEvents.summary('ai_tokens', {
+  customer: 'cus_123',
+  startTime: '2026-08-10T00:00:00.000Z',
+  endTime: '2026-08-10T01:00:00.000Z',
+  valueGroupingWindow: 'hour',
+});
+
+for (const item of summary.data) {
+  console.log(item.meter, item.aggregatedValue, item.startTime, item.endTime);
+}
+```
+
+`meterId` здесь означает публичный meter code. Ответ — list envelope: `{ object: 'list', data: MeterEventSummary[], hasMore: false }` плюс `requestId`.
+
+## Ошибки
+
+SDK бросает `BillingError` для ошибок API и транспортных сбоев (включая timeout и network errors).
+
+```ts
+try {
+  await billing.checkout.sessions.create(
+    {
+      customer: 'cus_123',
+      price: 'price_pro_monthly',
+      successUrl: 'https://app.example.com/billing/success',
+      cancelUrl: 'https://app.example.com/billing',
+    },
+    { idempotencyKey: 'checkout:ws_123:pro-monthly:v1' }
+  );
+} catch (error) {
+  if (error instanceof BillingError) {
+    console.error(error.code);
+    console.error(error.message);
+    console.error(error.status);
+    console.error(error.requestId);
+    console.error(error.param);
+  }
+}
+```
+
+Для HTTP error-path `BillingError.requestId` читается строго из ответного header `MegaBilling-Request-Id`. Если header отсутствует, `requestId === null` даже если body содержит поле `error.requestId`.
+
+Для локальной верификации webhook SDK бросает отдельный `BillingWebhookVerificationError` с кодами:
+
+| Код                         | Когда возникает                                          |
+| --------------------------- | -------------------------------------------------------- |
+| `webhook_header_invalid`    | header отсутствует или не содержит валидный `t=` / `v1=` |
+| `webhook_signature_invalid` | payload или secret не совпали с подписью                 |
+| `webhook_timestamp_expired` | timestamp вышел за tolerance window                      |
+| `webhook_payload_invalid`   | payload не является валидным JSON event envelope         |
+
+Поля `BillingError`:
+
+| Поле        | Назначение                                                                                        |
+| ----------- | ------------------------------------------------------------------------------------------------- |
+| `code`      | Стабильный код ошибки API или транспортный (`request_timeout`, `network_error`, `http_<status>`)  |
+| `status`    | HTTP status; `408` для timeout; `0` для network failure                                           |
+| `requestId` | Корреляционный ID только из `MegaBilling-Request-Id`; при отсутствии header SDK возвращает `null` |
+| `param`     | Параметр, связанный с ошибкой валидации (если API его вернул)                                     |
+
+### Transport / network errors
+
+Для `network_error` SDK намеренно не прокидывает сырой `fetch`/runtime message наружу. Вместо этого возвращается безопасное сообщение:
+
+```txt
+Network request failed. Check connectivity or BILLING_API_URL and retry.
+```
+
+Это поведение защищает consumer logs и UI от случайной утечки низкоуровневых деталей рантайма (`ECONNREFUSED`, DNS internals, stack fragments) и оставляет диагностику в предсказуемом typed error contract.
+
+## Идемпотентность
+
+Для mutating-операций передавайте стабильный `idempotencyKey` в `options`. SDK пробрасывает его в заголовок `Idempotency-Key` без изменений.
+
+- Повтор с тем же ключом и тем же payload возвращает сохранённый результат.
+- Тот же ключ с другим payload приводит к конфликту на стороне API.
+- Для `meterEvents.create(...)` replay задаётся не header-ом, а обязательным body-полем `identifier`: тот же `identifier` с тем же нормализованным payload возвращает тот же event, а с другим payload приводит к `idempotency_key_conflict`. `timestamp` входит в payload fingerprint только если он был передан явно — retry без `timestamp` не создаёт ложный конфликт.
+- Для read-методов (`customers.retrieve`, `customers.list`, `subscriptions.retrieve`, `subscriptions.list`, `invoices.retrieve`, `invoices.listCreditNotes`, `access.retrieve`) ключ не используется — это GET.
+
+| Метод                      | Идемпотентность                   |
+| -------------------------- | --------------------------------- |
+| `customers.create`         | ключ обязателен на стороне API    |
+| `customers.update`         | ключ опционален, но рекомендуется |
+| `subscriptions.cancel`     | ключ опционален, но рекомендуется |
+| `checkout.sessions.create` | ключ обязателен на стороне API    |
+| `meterEvents.create`       | replay через `identifier` в body  |
+
+Рекомендуемый паттерн ключей: привязка к бизнес-сущности consumer-а, например `customer:{externalId}`, `checkout:{externalId}:{price}:v1`, `customer-update:{externalId}:v2`, `subscription-cancel:{subscriptionId}:v1`. Для usage `identifier` тоже стоит привязывать к бизнес-событию consumer-а, например `generation:{generationId}` или `workspace:{workspaceId}:usage:{sequence}`.
+
+Подробнее: [`docs/api/idempotency-rules.md`](../../docs/api/idempotency-rules.md).
+
+## Переменные окружения
+
+| Переменная                                          | Обязательность            | Назначение                                                                                       |
+| --------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------ |
+| `BILLING_API_KEY`                                   | да (для реальных вызовов) | Project-scoped integration key (`bsk_test_...` или `bsk_live_...`) → `Authorization: Bearer ...` |
+| `BILLING_API_URL`                                   | нет                       | Base URL API; если не задан и не передан `baseUrl`, используется значение по умолчанию пакета    |
+| `BILLING_PRICE_ID`                                  | нет                       | Только для `pnpm run quickstart` (пример)                                                        |
+| `APP_URL`                                           | нет                       | Только для quickstart: базовый URL success/cancel redirect                                       |
+| `WORKSPACE_ID`, `WORKSPACE_EMAIL`, `WORKSPACE_NAME` | нет                       | Только для quickstart: демо-данные customer                                                      |
+
+В публичном клиенте Wave 1 **не** используются `BILLING_PROJECT_ID` и `BILLING_HTTP_X_TENANT_ID`: scope задаётся integration key.
+
+## Отличие от `@openaisdk/billing-sdk`
+
+|                    | `@openaisdk/billing-sdk-node`                                                  | `@openaisdk/billing-sdk`                                            |
+| ------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| Роль               | Канонический handwritten SDK для consumer Public API                           | Generated OpenAPI/axios compatibility-слой                          |
+| Поверхность        | `customers` / `subscriptions` / `checkout.sessions` / `access` / `meterEvents` | Шире: generated client поверх полного Billing API                   |
+| Auth / headers     | Только Bearer integration key                                                  | Может опираться на legacy env (`BILLING_PROJECT_ID`, `x-tenant-id`) |
+| Источник контракта | Public API Wave 1 (`/api/public-json`)                                         | Не источник истины для Wave 1 public contract                       |
+
+Для новой consumer-интеграции предпочитайте `@openaisdk/billing-sdk-node`. Пакет `@openaisdk/billing-sdk` допустим как временный compatibility-слой до Wave 2, но не должен диктовать public naming или onboarding.
+
+## Документация Public API
+
+- Обзор публичной границы: [`docs/api/public-api-v1.md`](../../docs/api/public-api-v1.md)
+- Сопоставление со Stripe: [`docs/integration/stripe-mapping.md`](../../docs/integration/stripe-mapping.md)
+- Правила идемпотентности: [`docs/api/idempotency-rules.md`](../../docs/api/idempotency-rules.md)
+- Машиночитаемый контракт runtime: `GET /api/public-json` (Swagger UI: `GET /api/public`)
+
+## DX vs Stripe Node SDK
+
+Сходства:
+
+- resource-oriented форма: `customers.create`, `customers.retrieve`, `subscriptions.list`, `checkout.sessions.create`
+- явная поддержка `Idempotency-Key` на mutating-операциях
+- usage передаётся product-level методом `meterEvents.create` по публичным `eventName` + `customer`
+- типизированные ошибки через `instanceof` и стабильные коды
+- list-ответ как envelope со списком в `data` и признаком продолжения
+
+Осознанные отличия:
+
+- Mega-Billing использует project-scoped integration key вместо account-wide Stripe secret
+- `externalType` и `externalId` — first-class поля маппинга customer, а не опциональный metadata
+- доступ к продукту читается через `billing.access.retrieve(...)`, а не собирается из subscriptions / invoices / payments
+- для meter events dedup/replay задаётся обязательным `identifier` в body, а не отдельным `Idempotency-Key` header
+
+### Customer & Subscription Lifecycle: сравнение со Stripe
+
+| Сценарий            | Stripe Node SDK                                                                                                 | `@openaisdk/billing-sdk-node`                                                | Почему отличается                                                                                               |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Чтение customer     | `stripe.customers.retrieve(id)`                                                                                 | `billing.customers.retrieve(id)`                                             | Совпадает по форме; возвращается публичный `cus_...` без внутренних UUID                                        |
+| Список customers    | `stripe.customers.list({ limit, starting_after })`                                                              | `billing.customers.list({ limit, startingAfter, externalType, externalId })` | camelCase вместо snake_case; фильтр по `externalType`/`externalId` вместо поиска по свободному metadata         |
+| Обновление customer | `stripe.customers.update(id, params)`                                                                           | `billing.customers.update(id, payload, options)`                             | Обновляются только контактные поля; связка `externalType`/`externalId` иммутабельна                             |
+| Список подписок     | `stripe.subscriptions.list({ customer })`, `customer` опционален                                                | `billing.subscriptions.list({ customer })`, `customer` обязателен            | Consumer работает в контексте своей сущности; project-wide перебор подписок не является consumer-сценарием      |
+| Отмена подписки     | `stripe.subscriptions.cancel(id)` для немедленной и `update(id, { cancel_at_period_end: true })` для отложенной | `billing.subscriptions.cancel(id, { atPeriodEnd })`                          | Один метод вместо двух разных операций: намерение «отменить» выражается одним вызовом, а момент отмены — флагом |
+| Форма списка        | `{ object: 'list', data, has_more }`                                                                            | `{ object: 'list', data, hasMore }`                                          | Та же mental model, camelCase по конвенции остальной части API                                                  |
+| Право доступа       | Собирается из subscription status / entitlements                                                                | `billing.access.retrieve(customerId)`                                        | Subscription остаётся биллинговым lifecycle; gate фич даёт materialized access state                            |
+
+## Scope
+
+Wave 1 golden path, Customer & Subscription Lifecycle, Wave 3 webhook verification helper и Wave 4 public meter events. Пакет не открывает invoices, payments, refunds, admin API и внутренние заголовки.
+
+## Troubleshooting
+
+### `requestId` в ошибке равен `null`
+
+Это ожидаемо, если сервер не вернул `MegaBilling-Request-Id` в ответном header. SDK не доверяет `error.requestId` из body как authoritative источнику correlation ID.
+
+### `BillingError` с `code === 'network_error'`
+
+Проверьте:
+
+- доступность `BILLING_API_URL`;
+- локальную сеть / VPN / proxy;
+- что backend действительно слушает ожидаемый host и port.
+
+Низкоуровневая строка `fetch failed ...` специально не попадает в `BillingError.message`; для глубокой диагностики смотрите server logs и локальный runtime output.
+
+### Scoped локальная пересборка пакета
+
+Для локальной проверки используйте узкие команды из корня monorepo:
+
+```bash
+pnpm --filter @openaisdk/billing-sdk-node build
+pnpm --filter @openaisdk/billing-sdk-node test
+```
+
+Если `node_modules/.pnpm` локально оказался частично повреждён и сборка падает на `ENOENT`, сначала повторите именно scoped-команды выше. Только если проблема воспроизводится стабильно, переходите к минимальному восстановлению lockfile-based install, а не к полному destructive reinstall всего workspace.