Node.js SDK

Типизированный клиент для счетов, денег, ошибок и проверки вебхуков.

@plateshka/sdk работает в Node.js 20 и новее. Сейчас высокоуровневый клиент покрывает счета; подписки и возвраты описаны в HTTP API и не притворяются готовыми методами SDK.

Установка

pnpm add @plateshka/sdk

Минимальный клиент

import { PlateshkaClient } from '@plateshka/sdk';

const plateshka = new PlateshkaClient({
  apiKey: process.env.PLATESHKA_API_KEY!,
  timeoutMs: 15_000,
});

const invoice = await plateshka.invoices.create(
  {
    amount: { amount: 49_900n, currency: 'RUB' },
    description: 'Тариф «Про»',
    metadata: { orderId: '4815162342' },
  },
  { idempotencyKey: 'order-4815162342' },
);

SDK создаст ключ сам, если его не передать, и сохранит его между внутренними retry одного вызова. Для очереди, повторного запуска процесса или двойного клика нужен ваш стабильный ключ.

Вебхуки

import { parseWebhookEvent } from '@plateshka/sdk';

const event = parseWebhookEvent(rawBody, signature, webhookSecret);

if (event.type === 'invoice.success') {
  await markOrderPaidOnce(event.id, event.data.invoice.metadata.orderId);
}

parseWebhookEvent одновременно проверяет подпись, окно времени и форму события. При ошибке он выбрасывает WebhookVerificationError.

Деньги без потери точности

import { formatMoney, money } from '@plateshka/sdk';

const total = money(149_900n, 'RUB');
formatMoney(total); // «1 499,00 ₽»

В SDK сумма на входе — bigint или строка, в HTTP — строка минорных единиц. Не переводите деньги в number.

Обработка ошибок

import { PlateshkaApiError } from '@plateshka/sdk';

try {
  await plateshka.invoices.get(invoiceId);
} catch (error) {
  if (error instanceof PlateshkaApiError) {
    logger.warn({ code: error.code, status: error.status, requestId: error.requestId });
  }
  throw error;
}

Следующий шаг

Сверьте поведение retry в разделе ошибок и используйте API для операций, которых ещё нет в высокоуровневом клиенте.