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 listResponse = await client.accounts.list();
console.log(listResponse.accounts);

// Create an account
const createResponse = await client.accounts.create({
  name: 'John Doe',
  email: '[email protected]',
  country: 'US',
  default_currency: 'USD',
});
console.log(createResponse.account);

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

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

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

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

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
});

Error Handling

The SDK throws BillingrailsError for API errors:

import { Billingrails, BillingrailsError } from 'billingrails';

try {
  const retrieveResponse = 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: '[email protected]',
};

const createResponse = 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 [email protected] or visit our documentation.