@openaisdk/billing-sdk

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

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

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

Установка

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-приложения.

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

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 пакета.