@openaisdk/billing-sdk 1.0.0

package/.env.example

@@ -0,0 +1,8 @@
+# Те же имена, что у packages/billing-catalog-mcp (base URL без завершающего /)
+BILLING_API_URL=http://127.0.0.1:4001
+
+BILLING_API_KEY=
+
+BILLING_PROJECT_ID=
+
+BILLING_HTTP_X_TENANT_ID=

package/README.md

@@ -0,0 +1,117 @@
+# @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` пакета.

package/dist/config.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Конфигурация SDK для Billing API.
+ *
+ * Auth model (ADR-010): project-scoped integration keys.
+ * Tenant и project резолвятся из API key автоматически на стороне API.
+ * Часть методов OpenAPI всё равно принимает `xTenantId` в сигнатуре — используйте
+ * `BILLING_HTTP_X_TENANT_ID` (или `getOptionalTenantIdFromEnv()` + `getApiHeaders()`).
+ *
+ * **Переменные окружения** (договор с `packages/billing-catalog-mcp`):
+ * `BILLING_API_URL`, `BILLING_API_KEY`, `BILLING_PROJECT_ID`, `BILLING_HTTP_X_TENANT_ID`.
+ *
+ * Предпочтительный способ аутентификации: Authorization: Bearer <key>.
+ */
+export interface SdkConfig {
+    baseURL: string;
+    /** Project-scoped integration key (bsk_live_... / bsk_test_...). */
+    apiKey?: string;
+    timeout?: number;
+}
+/**
+ * Устанавливает глобальную конфигурацию SDK
+ */
+export declare function setSdkConfig(config: Partial<SdkConfig>): void;
+/**
+ * Получает текущую конфигурацию SDK
+ */
+export declare function getSdkConfig(): SdkConfig;
+/**
+ * Создаёт headers для Billing API.
+ * Использует Authorization: Bearer как предпочтительный метод (ADR-010).
+ */
+export declare function getApiHeaders(): Record<string, string>;
+/** UUID tenant из env (для аргументов сгенерированных методов). */
+export declare function getOptionalTenantIdFromEnv(): string | undefined;
+/** UUID project из env (если прокидываете projectId из конфига). */
+export declare function getOptionalProjectIdFromEnv(): string | undefined;
+/**
+ * Подставляет в глобальный конфиг `baseURL` и `apiKey` из process.env
+ * (`BILLING_API_URL`, `BILLING_API_KEY`). Без побочных эффектов для остальных полей.
+ */
+export declare function applyBillingSdkEnv(): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAOD;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,CAE7D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAExC;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUtD;AAED,mEAAmE;AACnE,wBAAgB,0BAA0B,IAAI,MAAM,GAAG,SAAS,CAG/D;AAED,oEAAoE;AACpE,wBAAgB,2BAA2B,IAAI,MAAM,GAAG,SAAS,CAGhE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAazC"}

package/dist/config.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Конфигурация SDK для Billing API.
+ *
+ * Auth model (ADR-010): project-scoped integration keys.
+ * Tenant и project резолвятся из API key автоматически на стороне API.
+ * Часть методов OpenAPI всё равно принимает `xTenantId` в сигнатуре — используйте
+ * `BILLING_HTTP_X_TENANT_ID` (или `getOptionalTenantIdFromEnv()` + `getApiHeaders()`).
+ *
+ * **Переменные окружения** (договор с `packages/billing-catalog-mcp`):
+ * `BILLING_API_URL`, `BILLING_API_KEY`, `BILLING_PROJECT_ID`, `BILLING_HTTP_X_TENANT_ID`.
+ *
+ * Предпочтительный способ аутентификации: Authorization: Bearer <key>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setSdkConfig = setSdkConfig;
+exports.getSdkConfig = getSdkConfig;
+exports.getApiHeaders = getApiHeaders;
+exports.getOptionalTenantIdFromEnv = getOptionalTenantIdFromEnv;
+exports.getOptionalProjectIdFromEnv = getOptionalProjectIdFromEnv;
+exports.applyBillingSdkEnv = applyBillingSdkEnv;
+let globalConfig = {
+    baseURL: 'http://localhost:4001',
+    timeout: 10000,
+};
+/**
+ * Устанавливает глобальную конфигурацию SDK
+ */
+function setSdkConfig(config) {
+    globalConfig = { ...globalConfig, ...config };
+}
+/**
+ * Получает текущую конфигурацию SDK
+ */
+function getSdkConfig() {
+    return { ...globalConfig };
+}
+/**
+ * Создаёт headers для Billing API.
+ * Использует Authorization: Bearer как предпочтительный метод (ADR-010).
+ */
+function getApiHeaders() {
+    const headers = {};
+    if (globalConfig.apiKey) {
+        headers['Authorization'] = `Bearer ${globalConfig.apiKey}`;
+    }
+    const tenantFromEnv = process.env.BILLING_HTTP_X_TENANT_ID?.trim();
+    if (tenantFromEnv) {
+        headers['x-tenant-id'] = tenantFromEnv;
+    }
+    return headers;
+}
+/** UUID tenant из env (для аргументов сгенерированных методов). */
+function getOptionalTenantIdFromEnv() {
+    const v = process.env.BILLING_HTTP_X_TENANT_ID?.trim();
+    return v || undefined;
+}
+/** UUID project из env (если прокидываете projectId из конфига). */
+function getOptionalProjectIdFromEnv() {
+    const v = process.env.BILLING_PROJECT_ID?.trim();
+    return v || undefined;
+}
+/**
+ * Подставляет в глобальный конфиг `baseURL` и `apiKey` из process.env
+ * (`BILLING_API_URL`, `BILLING_API_KEY`). Без побочных эффектов для остальных полей.
+ */
+function applyBillingSdkEnv() {
+    const base = process.env.BILLING_API_URL?.trim() || process.env.BILLING_API_BASE_URL?.trim();
+    const key = process.env.BILLING_API_KEY?.trim();
+    const patch = {};
+    if (base) {
+        patch.baseURL = base.replace(/\/$/, '');
+    }
+    if (key) {
+        patch.apiKey = key;
+    }
+    if (Object.keys(patch).length > 0) {
+        setSdkConfig(patch);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAiBH,oCAEC;AAKD,oCAEC;AAMD,sCAUC;AAGD,gEAGC;AAGD,kEAGC;AAMD,gDAaC;AAhED,IAAI,YAAY,GAAc;IAC5B,OAAO,EAAE,uBAAuB;IAChC,OAAO,EAAE,KAAK;CACf,CAAC;AAEF;;GAEG;AACH,SAAgB,YAAY,CAAC,MAA0B;IACrD,YAAY,GAAG,EAAE,GAAG,YAAY,EAAE,GAAG,MAAM,EAAE,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY;IAC1B,OAAO,EAAE,GAAG,YAAY,EAAE,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa;IAC3B,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,IAAI,YAAY,CAAC,MAAM,EAAE,CAAC;QACxB,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,YAAY,CAAC,MAAM,EAAE,CAAC;IAC7D,CAAC;IACD,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,IAAI,EAAE,CAAC;IACnE,IAAI,aAAa,EAAE,CAAC;QAClB,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAAC;IACzC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,mEAAmE;AACnE,SAAgB,0BAA0B;IACxC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,IAAI,EAAE,CAAC;IACvD,OAAO,CAAC,IAAI,SAAS,CAAC;AACxB,CAAC;AAED,oEAAoE;AACpE,SAAgB,2BAA2B;IACzC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE,CAAC;IACjD,OAAO,CAAC,IAAI,SAAS,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,SAAgB,kBAAkB;IAChC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,IAAI,EAAE,CAAC;IAC7F,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC;IAChD,MAAM,KAAK,GAAuB,EAAE,CAAC;IACrC,IAAI,IAAI,EAAE,CAAC;QACT,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,GAAG,EAAE,CAAC;QACR,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC;IACrB,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}