subos-sdk

TypeScript ESM SDK to consume SubOS backend APIs (plans, coupons, subscriptions, customers, checkout helpers).

• ESM-only build (type: module), NodeNext resolution
• Zero runtime deps (uses native fetch); pass a custom fetchImpl if needed
• Typed endpoints for Plans, Coupons, Subscriptions, and Customers

Install (in monorepo)

Using pnpm workspaces, from repo root:

pnpm -w install
pnpm -w -F subos-sdk build

This produces packages/subos-sdk/dist/* and the package is publishable (only dist is included).

Usage

import { createClient, type Interval, type Plan } from 'subos-sdk';

const client = createClient({
  baseUrl: 'https://api.example.com',
  projectId: '<PROJECT_ID>',
  // fetchImpl: customFetch, // optional
});

// List plans (optionally filter by interval or link an external customer)
const plans: Plan[] = await client.plans.list({ interval: 'MONTHLY' satisfies Interval });

// Get a specific plan
const plan = await client.plans.get('plan-uuid');

// Buy a plan
await client.plans.buy({
  idOrCode: 'BASIC',
  externalCustomerId: 'cust_123',
  paymentMethodId: 'pm_abc',
  couponCode: 'SUMMER10',
});

// Apply coupon
const result = await client.coupons.apply({
  couponCode: 'SUMMER10',
  externalId: 'cust_123',
  planCode: 'BASIC',
});

### Subscriptions

```ts
// Get active subscription for a customer (by externalId)
const sub = await client.subscriptions.getActive('cust_123');

// Get customer usage/billable metrics
const metrics = await client.subscriptions.getMetrics('cust_123');

// Update payment method associated to active subscription
await client.subscriptions.updatePaymentMethod({
  externalId: 'cust_123',
  paymentMethodId: 'pm_abc',
});

// Cancel active subscription
await client.subscriptions.cancel('cust_123');

Customers and Payment Methods

// Basic CRUD
const customers = await client.customers.list();
const created = await client.customers.create({ externalId: 'cust_123', email: '[email protected]' });
const updated = await client.customers.update('cust_123', { name: 'John Doe' });
await client.customers.delete('cust_123');

// Payment methods
await client.customers.setPaymentMethod('cust_123', 'pm_abc');
await client.customers.confirmPaymentIntent('cust_123', 'seti_123');
const methods = await client.customers.listPaymentMethods('cust_123');
await client.customers.deletePaymentMethod('cust_123', 'pm_abc');

Client factory

const client = createClient({ baseUrl, projectId });
// available modules
client.http; // raw HTTP client
client.plans;
client.coupons;
client.subscriptions;
client.customers;

Environment

• Node 18+ (native fetch). For Node <18 or custom environments, pass fetchImpl in createClient.
• Backend requires projectId header – provide via SDKConfig.projectId.

Development

pnpm -w -F subos-sdk dev

Publish (optional)

# from packages/subos-sdk
npm publish --access public

Ensure the package name and version meet your publishing strategy.