SDK

The official Orbiill TypeScript SDK provides a type-safe, zero-dependency client for the Public API. It uses native fetch and includes full TypeScript types.

Installation

npmshell

npm install @orbiill/sdk

pnpmshell

pnpm add @orbiill/sdk

yarnshell

yarn add @orbiill/sdk

Setup

Initialize the client with your API key. The baseUrl defaults to https://api.orbiill.com.

Initializationtypescript

import { OrbiillClient } from '@orbiill/sdk';

const orbiill = new OrbiillClient({
  apiKey: 'orb_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
  baseUrl: 'https://api.orbiill.com', // optional, this is the default
});

Tip: Store your API key in an environment variable (e.g., ORBIILL_API_KEY) and never commit it to source control.

Resources

Plans

typescript

// List all plans
const plans = await orbiill.plans.list();
// plans: Plan[]

// Get a single plan
const plan = await orbiill.plans.get('bp_abc123');
// plan: Plan

Billing Configs

typescript

// List all billing configs
const configs = await orbiill.billingConfigs.list();

// Get a specific config
const config = await orbiill.billingConfigs.get('bc_abc123');

Subscriptions

typescript

// List subscriptions with pagination
const result = await orbiill.subscriptions.list({ limit: 10 });
// result.data: Subscription[]
// result.meta.hasMore: boolean
// result.meta.nextCursor: string | null

// Cancel a subscription (at period end)
await orbiill.subscriptions.cancel('sub_1N0abc...');

// Cancel immediately
await orbiill.subscriptions.cancel('sub_1N0abc...', { immediate: true });

// Report usage for a metered subscription item
await orbiill.subscriptions.reportUsage('si_abc123', { quantity: 100 });

Webhook Verification

The SDK includes a verifyWebhook helper to validate incoming webhook signatures. Use it in your Express.js middleware:

Express.js middlewaretypescript

import { verifyWebhook } from '@orbiill/sdk';

app.post('/webhooks/orbiill', (req, res) => {
  const event = verifyWebhook(
    req.body,                             // raw string body
    req.headers['x-orbiill-signature'],   // signature header
    process.env.ORBIILL_WEBHOOK_SECRET    // your endpoint secret
  );

  switch (event.type) {
    case 'subscription.created':
      // Grant access to the user
      break;
    case 'subscription.deleted':
      // Revoke access
      break;
    case 'invoice.payment_failed':
      // Notify the customer
      break;
  }

  res.json({ received: true });
});

The function throws an error if the signature is invalid, so wrap it in a try/catch if you want to handle verification failures gracefully.

Error Handling

The SDK exports two error classes for typed error handling:

`OrbiillAPIError`

Thrown for any non-2xx API response. Properties:

statusCode — HTTP status code
message — Human-readable error message
error — Error type string (e.g., "Bad Request")

`RateLimitError`

Extends OrbiillAPIError. Thrown when the API returns 429. Additional property:

retryAfter — Seconds to wait before retrying

Error handling exampletypescript

import { OrbiillAPIError, RateLimitError } from '@orbiill/sdk';

try {
  await orbiill.subscriptions.cancel('sub_invalid');
} catch (error) {
  if (error instanceof RateLimitError) {
    // error.retryAfter contains seconds to wait
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof OrbiillAPIError) {
    // error.statusCode, error.message, error.error
    console.error(error.statusCode, error.message);
  }
}