Billingrails Node.js SDK

Official Node.js SDK for Billingrails - Flexible, composable, and intuitive API-first commerce platform.

Installation

pnpm add @billingrails/node

Or with npm:

npm install @billingrails/node

Or with yarn:

yarn add @billingrails/node

Quick Start

import { Billingrails } from '@billingrails/node';

// Initialize the client
const client = new Billingrails({
  apiKey: 'your-api-key',
});

// List accounts
const accounts = await client.accounts.list();

// Create an account
const account = await client.accounts.create({
  name: 'John Doe',
  email: 'john@example.com',
  country: 'US',
  default_currency: 'USD',
});

// Retrieve an account
const retrievedAccount = await client.accounts.retrieve('acc_123');

// Update an account
const updatedAccount = await client.accounts.update('acc_123', {
  name: 'Jane Doe',
});

// Get account balances
const balances = await client.accounts.getBalances('acc_123');

// Debit an account
const debitResult = await client.accounts.debit('acc_123', {
  amount: 1000, // Amount in cents
  currency: 'USD',
});

Configuration

Basic Configuration

const client = new Billingrails({
  apiKey: 'your-api-key',
});

Advanced Configuration

const client = new Billingrails({
  apiKey: 'your-api-key',
  baseURL: 'https://api.billingrails.com/v1', // Production URL
  timeout: 30000, // Request timeout in milliseconds
  maxRetries: 3, // Maximum number of retries for failed requests
});

API Reference

Accounts

List Accounts

const accounts = await client.accounts.list({
  page: 1,
  page_size: 20,
});

Create Account

const account = await client.accounts.create({
  name: 'John Doe',
  email: 'john@example.com',
  type: 'individual',
  country: 'US',
  default_currency: 'USD',
  timezone: 'UTC',
  billing_address: {
    line1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94105',
    country: 'US',
  },
});

Retrieve Account

const account = await client.accounts.retrieve('acc_123');

Update Account

const account = await client.accounts.update('acc_123', {
  name: 'Jane Doe',
  email: 'jane@example.com',
});

Get Account Balances

const balances = await client.accounts.getBalances('acc_123');

// Filter by currency
const usdBalance = await client.accounts.getBalances('acc_123', {
  currency: 'USD',
});

Debit Account

const result = await client.accounts.debit('acc_123', {
  amount: 1000, // Amount in cents
  currency: 'USD',
  reference_id: 'ref_123',
});

Error Handling

The SDK throws BillingrailsError for API errors:

import { Billingrails, BillingrailsError } from 'billingrails';

try {
  const account = await client.accounts.retrieve('invalid_id');
} catch (error) {
  if (error instanceof BillingrailsError) {
    console.error('API Error:', error.message);
    console.error('Error Code:', error.code);
    console.error('Status Code:', error.statusCode);
    console.error('Details:', error.details);
  }
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import type { Account, AccountCreate, AccountUpdate } from 'billingrails';

const accountData: AccountCreate = {
  name: 'John Doe',
  email: 'john@example.com',
};

const account: Account = await client.accounts.create(accountData);

Development

# Install dependencies
pnpm install

# Build the SDK
pnpm build

# Run linter
pnpm lint

# Fix linting issues
pnpm lint:fix

# Type check
pnpm typecheck

Requirements

Node.js >= 18.0.0
TypeScript >= 5.0.0 (for TypeScript projects)

License

MIT

Support

For support, please contact support@billingrails.com or visit our documentation.