@wilix/billbill-client-js

Официальный клиент BillBill для JavaScript и TypeScript на базе fetch. Поддерживаются API мерчанта (MerchantApi), пользовательского портала (UserApi) и системные вызовы (SystemApi).

Установка

npm install @wilix/billbill-client-js
# или
yarn add @wilix/billbill-client-js

Требуется среда с глобальным fetch (Node.js 18+, современные браузеры).

Запуск готовых примеров (5-10 минут)

1. Из корня пакета соберите клиент:

yarn build

2. Подготовьте переменные окружения:

cp ./examples/.env.example ./examples/.env

3. Заполните ./examples/.env:

   • BILLBILL_MERCHANT_API_KEY для примера мерчанта,
   • BILLBILL_USER_JWT для примера пользовательского API,
   • при необходимости BILLBILL_BASE_URL и BILLBILL_USER_AGENT.

4. Запустите нужный сценарий:

yarn example:merchant
# или
yarn example:user

Дополнительные примеры для MerchantApi (каждый сценарий — отдельная папка в examples/, см. русские комментарии в коде):

| Команда | Назначение | |--------|------------| | yarn example:merchant:user-subscribe | Создать плательщика и оформить подписку | | yarn example:merchant:user-subscribe-metric | То же + отправка metered / usage (metricEventNew) | | yarn example:merchant:payment-method-card | То же + привязка метода (карта / YooKassa и др. через ваш gateway) | | yarn example:merchant:payment-method-wire | То же + банковский перевод (wire transfer gateway) | | yarn example:merchant:subscription-cancel | Отмена подписки | | yarn example:merchant:quotas | Квоты: definitions, overrides, resolve | | yarn example:merchant:public-plans | Список опубликованных планов по продукту |

Переменные окружения для этих сценариев — в examples/.env.example.

Ожидаемый результат: скрипт выводит краткую сводку (Merchant profile loaded / User profile loaded) либо печатает структурированную ошибку BillBillError с code, message, requestId, redirect.

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

Базовый URL по умолчанию — https://api.billbill.ru. Его можно не указывать, если вы работаете с продакшеном.

import { MerchantApi, BillBillError } from '@wilix/billbill-client-js';

const merchant = new MerchantApi({
  apiKey: process.env.BILLBILL_MERCHANT_API_KEY!, // OpenAPI-ключ или JWT портала
  // baseUrl: 'https://api.billbill.ru', // опционально
  // userAgent: 'MyApp OpenAPI/1.0',  // для серверных вызовов по API-ключу см. ниже
});

try {
  const profile = await merchant.get();
  console.log(profile.merchant?.name);
} catch (e) {
  if (BillBillError.isBillBillError(e)) {
    console.error(e.code, e.message, e.requestId);
  } else {
    throw e;
  }
}

User-Agent и OpenAPI

Часть логики на сервере зависит от того, классифицируется ли запрос как OpenAPI (например, по подстроке OpenAPI в User-Agent). Для интеграций с ключом мерчанта задайте userAgent так, чтобы в нём была подстрока OpenAPI, если это требует ваш сценарий (см. документацию BillBill и вашу конфигурацию).

const merchant = new MerchantApi({
  apiKey: 'bb_live_xxx',
  userAgent: 'MyService OpenAPI/1.0',
});

Поведение методов

• Успешный JSON-ответ BillBill имеет вид { code: 0, message, data, ... }. Методы клиента возвращают только data (типизировано), после проверки code === 0.
• При ошибке (HTTP, code !== 0, сеть) выбрасывается BillBillError с полями code, message, при необходимости requestId, redirect (например, при истечении сессии портала).
• Ответы не JSON (файлы, текст), если они описаны в OpenAPI с соответствующим Content-Type, обрабатываются через callArrayBuffer / callText в базовом классе; такие методы возвращают ArrayBuffer или string без проверки JSON-обёртки.

Типовые сценарии

1. Серверная интеграция (API-ключ мерчанта)

Последовательность: клиент с ключом → чтение профиля → работа со счетами/подписками (по необходимости).

import { MerchantApi } from '@wilix/billbill-client-js';

const api = new MerchantApi({
  apiKey: 'bb_live_xxx',
  userAgent: 'Billing OpenAPI/1.0',
});

const me = await api.get();
const invoices = await api.invoiceList({
  page: 0,
  count: 20,
  // остальные поля — см. тип InvoiceListReq и JSDoc в IDE
});

2. Пользовательский портал (JWT пользователя)

Используйте UserApi с токеном, выданным после авторизации пользователя (/user/auth/...). Паттерн тот же: new UserApi({ apiKey: '<user_jwt>' }).

import { UserApi } from '@wilix/billbill-client-js';

const userApi = new UserApi({ apiKey: userJwt });
const profile = await userApi.get();

3. Обработка ошибок и редиректа

Если в ответе бизнес-ошибка или истекла сессия, сервер может вернуть code !== 0 и поле redirect. Их можно прочитать с BillBillError.

import { BillBillError } from '@wilix/billbill-client-js';

try {
  await merchant.get();
} catch (e) {
  if (BillBillError.isBillBillError(e) && e.redirect) {
    window.location.href = e.redirect; // пример для браузера
  }
}

4. Policy-квоты (consumer-side enforcement)

Для policy-квот используйте snapshot-подход:

1. читать definition/list и override/list для админских настроек;
2. получать resolve snapshot для конкретного productId + planId;
3. кэшировать snapshot в вашем сервисе и проверять квоты локально.

const snapshot = await merchant.getQuotaResolve({
  productId: 1001,
  planId: 2001
});

console.log(snapshot.snapshot?.etag, snapshot.snapshot?.version);
// локальная проверка в вашем коде, без отправки metric events

Другой хост (staging)

const api = new MerchantApi({
  apiKey: '...',
  baseUrl: 'https://staging-api.example.com',
});

Адрес без завершающего слэша; клиент сам нормализует URL.

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

• Живая спецификация: https://api.billbill.ru/api.json
• Swagger UI: https://api.billbill.ru/swagger (путь может отличаться на вашем стенде)

Подмодули пакета

| Импорт | Назначение | |--------|------------| | @wilix/billbill-client-js | MerchantApi, UserApi, SystemApi, ApiClient, BillBillError, типы | | @wilix/billbill-client-js/merchant | только MerchantApi | | @wilix/billbill-client-js/user | только UserApi | | @wilix/billbill-client-js/system | только SystemApi | | @wilix/billbill-client-js/apiClient | базовый ApiClient, DEFAULT_BASE_URL, ApiClientOptions | | @wilix/billbill-client-js/errors | BillBillError, типы ошибок |

Миграция с 0.x

Версия 1.x — ломающее изменение:

• Конструктор только в виде { apiKey, baseUrl?, userAgent? }, база по умолчанию https://api.billbill.ru.
• Методы возвращают Promise<данные из data>, а не StdResponse.
• Ошибки — через BillBillError, а не через поля ответа с HTTP-ошибкой.

Разработка и генерация клиента

Из корня пакета:

yarn generate   # OpenAPI → src/types/*.ts, src/merchant.ts, ...
yarn build

Подробности для контрибьюторов — в AGENTS.md.

Также доступны smoke-тесты runtime-контракта:

yarn test

Лицензия

MIT