@unitpay/sdk

The official UnitPay Node.js/TypeScript SDK. Provides a Stripe-like client for the UnitPay billing API.

Installation

npm install @unitpay/sdk
# or
bun add @unitpay/sdk

Quick Start

import { UnitPay } from '@unitpay/sdk';

const unitpay = new UnitPay({ apiKey: 'upay_sk_...' });

// Customers
const customer = await unitpay.customers.create({
  name: 'Acme Corp',
  email: '[email protected]',
});

// Subscriptions
const subscription = await unitpay.subscriptions.create({
  customer_id: customer.id,
  plan_id: 'pln_...',
});

// List with auto-pagination
for await (const invoice of unitpay.invoices.list({ customer_id: customer.id })) {
  console.log(invoice.id, invoice.status);
}

Resources

| Resource | Methods | |----------|---------| | customers | create, get, update, list, archive | | subscriptions | create, get, update, list, cancel | | invoices | get, list, pay, void | | plans | create, get, update, list | | products | create, get, update, list | | paymentMethods | attach, detach, list, setDefault | | credits | grant, deduct, balance, ledger | | billableMetrics | create, get, update, list | | planChanges | preview, apply, get | | webhooks | verifyWebhook (requires svix peer dep) |

Error Handling

import { UnitPay, NotFoundError, RateLimitError } from '@unitpay/sdk';

try {
  await unitpay.customers.get('cus_nonexistent');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Customer not found');
  } else if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.headers?.['retry-after']}s`);
  }
}

Auto-Pagination

All .list() methods return a PagePromise that supports both await (single page) and for await (all pages):

// Single page
const page = await unitpay.customers.list({ limit: 20 });
console.log(page.data, page.hasMore);

// All pages (auto-paginating)
for await (const customer of unitpay.customers.list()) {
  console.log(customer.id);
}

Configuration

const unitpay = new UnitPay({
  apiKey: 'upay_sk_...',
  baseUrl: 'https://api.unitpay.dev/v1',  // default
  timeout: 30_000,                          // 30s default
  maxRetries: 2,                            // retries on 5xx/network errors
});

Webhook Verification

Requires svix as a peer dependency:

npm install svix

const event = unitpay.webhooks.verifyWebhook({
  body: rawBody,
  headers: request.headers,
  secret: 'whsec_...',
});

License

MIT