npm package: @openaisdk/billing-sdk
Description: TypeScript SDK для Billing API — customer account, checkout, access
Author: Anatoliy Tukov
Latest version: 1.0.0

# @openaisdk/billing-sdk

TypeScript-клиент для **Billing API**: подписки, checkout, customer accounts, каталог, webhooks и админские операции. Сгенерирован из OpenAPI (**axios**).

**Аудитория:** backend вашего SaaS (Node.js), который вызывает Billing Platform по сети.

Исходники и issues: монорепозиторий [MegaRetroHQ/saas-billing](https://github.com/MegaRetroHQ/saas-billing) (каталог `packages/billing-sdk`).

## Установка

```bash
npm install @openaisdk/billing-sdk
# или
pnpm add @openaisdk/billing-sdk
```

Пакет тянет **`axios`** как зависимость; отдельно ставить его не обязательно.

## Требования

- **Node.js** ≥ 20 (как у платформы; для других LTS обычно тоже ок).
- **TypeScript** рекомендуется: в комплекте типы (`dist/*.d.ts`).

## Аутентификация (M2M)

Используйте **project-scoped integration key**, выданный в Admin UI платформы (раздел «Интеграция»). Передавайте ключ как **`Authorization: Bearer <ключ>`**.

Tenant и project для ключа определяются **на стороне API**. Часть сгенерированных методов всё равно принимает **`xTenantId`** в сигнатуре (как в OpenAPI) — передавайте UUID tenant из настроек проекта / сниппета интеграции, даже при Bearer-ключе.

**Не коммитьте** ключи и не вшивайте их в клиентский фронтенд — только сервер consumer-приложения.

## Быстрый старт

```typescript
import {
  Configuration,
  CustomerAccountsApi,
  AccessApi,
} from '@openaisdk/billing-sdk';

const billing = new Configuration({
  basePath: process.env.BILLING_API_URL, // без завершающего /
  baseOptions: {
    headers: {
      Authorization: `Bearer ${process.env.BILLING_API_KEY}`,
    },
  },
});

const customers = new CustomerAccountsApi(billing);
const access = new AccessApi(billing);

// Пример: список customer accounts (сигнатуры сгенерированы из OpenAPI — часто первым идёт x-tenant-id)
const tenantId = process.env.BILLING_HTTP_X_TENANT_ID; // UUID tenant
const projectId = process.env.BILLING_PROJECT_ID;
if (!tenantId || !projectId) throw new Error('Задайте BILLING_HTTP_X_TENANT_ID и BILLING_PROJECT_ID');
const list = await customers.customerAccountsControllerList(tenantId, projectId);
```

Точные аргументы методов смотрите в **типах** пакета: генератор отражает пути и заголовки спецификации.

## Переменные окружения (типичный backend)

Имена ниже — распространённый договор; точный `.env`-сниппет часто копируют из Admin UI после создания ключа.

| Переменная | Назначение |
|------------|------------|
| `BILLING_API_URL` | Base URL Billing API **без** завершающего `/` |
| `BILLING_API_KEY` | Сырой integration key (Bearer) |
| `BILLING_PROJECT_ID` | UUID проекта — для параметров `projectId` |
| `BILLING_HTTP_X_TENANT_ID` | UUID tenant — для параметров `xTenantId` в сгенерированных методах (имя из OpenAPI) |

Те же четыре имени использует MCP **`@openaisdk/billing-mcp`** (`packages/billing-catalog-mcp`): см. README пакета. Для глобального конфига SDK: `applyBillingSdkEnv()`, `getOptionalProjectIdFromEnv()`, `getOptionalTenantIdFromEnv()` в `config.ts`.

Дополнительные переменные и сценарии (включая feature-flag интеграции у consumer) — в гайде интеграции у поставщика платформы.

## Основные классы API

Клиент разбит на группы методов (OpenAPI tags):

| Класс | Назначение (кратко) |
|-------|---------------------|
| `AccessApi` | Состояние доступа (entitlements) для customer account |
| `CheckoutApi` | Checkout-сессии |
| `CustomerAccountsApi` | Учётные записи плательщиков в проекте |
| `SubscriptionsApi` | Подписки |
| `CatalogApi` | Планы и цены (каталог) |
| `WebhooksApi` | Webhook-подписки consumer |
| `IntegrationKeysApi` | Ключи интеграции (часто только из доверенного admin-кода) |
| `PlatformApi` | Платформенные/tenant-операции (по правам) |
| `AdminApi` | Админские операции |
| `ProviderAccountsApi` | Платёжные провайдеры |
| `AuthApi` | Auth (human flow; для M2M обычно не нужен) |
| `HealthApi` | Health / readiness |
| `MetricsApi` | Метрики |
| `DevProductionApi` | Dev-only эндпоинты (если включены на стенде) |

Полный список методов и DTO — в типах пакета и в OpenAPI-спецификации вашего стенда (`GET /api-json`).

## Idempotency

Для **POST**-операций создания (customer account, checkout и т.д.) рекомендуется передавать заголовок **`Idempotency-Key`** (уникальный ключ на логическую операцию), чтобы повторы запроса не создавали дубликаты.

Через axios это делается через `baseOptions`, опции конкретного вызова или перехватчик — в зависимости от того, как вы оборачиваете клиент.

## Дополнительно: `setSdkConfig` / `getApiHeaders`

В пакете есть вспомогательный модуль **`config.ts`**: `setSdkConfig`, `getSdkConfig`, `getApiHeaders` — для простой глобальной базы URL и ключа. Сгенерированные `*Api` по умолчанию используют **`Configuration`**, переданный в конструктор; глобальный конфиг нужен только если вы сами строите запросы поверх `getApiHeaders()`.

## Документация и контракт

- Контракт API и описание сценариев — у **поставщика Billing Platform** (часто документ **Consumer Integration Guide** и OpenAPI).
- Версия npm-пакета следует за релизами SDK; при breaking changes в API растёт мажорная версия SDK.

## Лицензия

**MIT** — см. поле `license` в `package.json` пакета.