Package Exports

@velobaseai/billing

Readme

@velobaseai/billing

Official Velobase Billing SDK for JavaScript and TypeScript.

Zero runtime dependencies — uses native fetch
Works with Node.js 18+, Deno, Bun, and Cloudflare Workers
ESM and CommonJS dual build with full TypeScript declarations
Automatic retries with exponential backoff

Installation

npm install @velobaseai/billing
# or
pnpm add @velobaseai/billing
# or
yarn add @velobaseai/billing

Quick Start

import Velobase from '@velobaseai/billing';

const vb = new Velobase({ apiKey: 'vb_live_xxx' });

// 1. Deposit credits to a customer (creates the customer if new)
const deposit = await vb.customers.deposit({
  customerId: 'user_123',
  amount: 1000,
});

// 2. Check balance
const customer = await vb.customers.get('user_123');
console.log(customer.balance.available); // 1000

// 3. Freeze credits before doing work
const freeze = await vb.billing.freeze({
  customerId: 'user_123',
  amount: 50,
  businessId: 'job_abc',
});

// 4a. Job succeeded — consume (supports partial)
const consume = await vb.billing.consume({
  businessId: 'job_abc',
  actualAmount: 32, // only charge 32, return 18
});

// 4b. Or if the job failed — unfreeze to return all
const unfreeze = await vb.billing.unfreeze({
  businessId: 'job_abc',
});

How It Works

Velobase Billing uses a freeze-then-consume pattern to safely manage credits:

deposit → freeze → consume   (normal flow)
                 → unfreeze  (failure/cancellation)

Deposit — Add credits to a customer's account. Creates the customer automatically on first deposit.
Freeze — Pre-authorize an amount before performing work. The frozen credits are deducted from available but not yet used. Each freeze is identified by a unique businessId you provide.
Consume — After the work is done, settle the frozen amount. You can pass actualAmount to charge less than what was frozen; the difference is automatically returned.
Unfreeze — If the work fails or is cancelled, release the full frozen amount back to the customer.

All write operations are idempotent — repeating the same businessId (freeze/consume/unfreeze) or idempotencyKey (deposit) returns the original result without double-charging.

Configuration

const vb = new Velobase({
  apiKey: 'vb_live_xxx',             // Required. Your Velobase API key.
  baseUrl: 'https://api.velobase.io', // Optional. Override the API endpoint.
  timeout: 30000,                     // Optional. Request timeout in ms (default: 30s).
  maxRetries: 2,                      // Optional. Retry count on 5xx/network errors (default: 2).
});

Usage Examples

Deposit with idempotency

// Safe to retry — the second call returns the same result without double-charging
const result = await vb.customers.deposit({
  customerId: 'user_123',
  amount: 500,
  idempotencyKey: 'order_abc_payment',
  description: 'Purchase of 500 credits',
});

console.log(result.addedAmount);        // 500
console.log(result.isIdempotentReplay); // false on first call, true on retries

Deposit with customer metadata

const result = await vb.customers.deposit({
  customerId: 'user_123',
  amount: 1000,
  name: 'Alice',
  email: 'alice@example.com',
  metadata: { plan: 'pro', source: 'stripe' },
});

Full billing flow

const CUSTOMER = 'user_123';
const JOB_ID = 'video_gen_001';

// Check balance before starting
const before = await vb.customers.get(CUSTOMER);
console.log('Available:', before.balance.available);

// Freeze the estimated cost
await vb.billing.freeze({
  customerId: CUSTOMER,
  amount: 100,
  businessId: JOB_ID,
  businessType: 'video_generation',
  description: '1080p video, ~60s',
});

// ... do the work ...

// Settle with the actual cost (partial consumption)
const result = await vb.billing.consume({
  businessId: JOB_ID,
  actualAmount: 73,
});
console.log('Charged:', result.consumedAmount);  // 73
console.log('Returned:', result.returnedAmount); // 27

// Verify final balance
const after = await vb.customers.get(CUSTOMER);
console.log('Available:', after.balance.available);

Customer balance structure

const customer = await vb.customers.get('user_123');

// Aggregate balance across all accounts
customer.balance.total;     // total deposited
customer.balance.used;      // total consumed
customer.balance.frozen;    // currently frozen (pending)
customer.balance.available; // total - used - frozen

// Individual accounts (e.g., different credit types/expiry)
for (const account of customer.accounts) {
  console.log(account.accountType);    // 'CREDIT'
  console.log(account.subAccountType); // 'DEFAULT'
  console.log(account.available);
  console.log(account.expiresAt);      // null or ISO date string
}

API Reference

`vb.customers.deposit(params): Promise<DepositResponse>`

Deposit credits. Creates the customer if they don't exist.

Parameter	Type	Required	Description
`customerId`	`string`	Yes	Your unique customer identifier
`amount`	`number`	Yes	Amount to deposit (must be > 0)
`idempotencyKey`	`string`	No	Prevents duplicate deposits on retry
`name`	`string \| null`	No	Customer display name
`email`	`string \| null`	No	Customer email
`metadata`	`object`	No	Arbitrary key-value metadata
`description`	`string`	No	Description for the deposit

Returns: { customerId, accountId, totalAmount, addedAmount, recordId, isIdempotentReplay }

`vb.customers.get(customerId): Promise<CustomerResponse>`

Retrieve a customer's balance and account details.

Returns: { id, name, email, metadata, balance, accounts, createdAt }

`vb.billing.freeze(params): Promise<FreezeResponse>`

Freeze credits before performing work.

Parameter	Type	Required	Description
`customerId`	`string`	Yes	Customer identifier
`amount`	`number`	Yes	Amount to freeze (must be > 0)
`businessId`	`string`	Yes	Your unique ID for this operation (idempotency key)
`businessType`	`string`	No	Category label (e.g., `'video_generation'`)
`description`	`string`	No	Human-readable description

Returns: { businessId, frozenAmount, freezeDetails, isIdempotentReplay }

`vb.billing.consume(params): Promise<ConsumeResponse>`

Settle a frozen amount. Supports partial consumption.

Parameter	Type	Required	Description
`businessId`	`string`	Yes	The `businessId` from the freeze
`actualAmount`	`number`	No	Actual amount to charge. Defaults to full frozen amount.

Returns: { businessId, consumedAmount, returnedAmount, consumeDetails, consumedAt, isIdempotentReplay }

`vb.billing.unfreeze(params): Promise<UnfreezeResponse>`

Release a frozen amount back to the customer.

Parameter	Type	Required	Description
`businessId`	`string`	Yes	The `businessId` from the freeze

Returns: { businessId, unfrozenAmount, unfreezeDetails, unfrozenAt, isIdempotentReplay }

Error Handling

All API errors throw typed exceptions that extend VelobaseError:

import {
  VelobaseError,
  VelobaseAuthenticationError,
  VelobaseValidationError,
  VelobaseNotFoundError,
} from '@velobaseai/billing';

try {
  await vb.billing.freeze({
    customerId: 'user_123',
    amount: 999999,
    businessId: 'job_xyz',
  });
} catch (err) {
  if (err instanceof VelobaseValidationError) {
    // 400 — bad request or insufficient balance
    console.error(err.message); // "insufficient balance"
  } else if (err instanceof VelobaseAuthenticationError) {
    // 401 — invalid or missing API key
  } else if (err instanceof VelobaseNotFoundError) {
    // 404 — customer not found
  } else if (err instanceof VelobaseError) {
    // catch-all for other API errors
    console.error(err.status, err.type, err.message);
  }
}

Error Class	HTTP Status	When
`VelobaseAuthenticationError`	401	Invalid or missing API key
`VelobaseValidationError`	400	Bad params, insufficient balance
`VelobaseNotFoundError`	404	Customer or resource not found
`VelobaseConflictError`	409	Conflicting operation
`VelobaseInternalError`	500	Server-side error (auto-retried)

Retries

The SDK automatically retries on 5xx errors and network failures with exponential backoff (500ms, 1s, 2s..., capped at 5s). Retries are safe because all Velobase write operations are idempotent.

4xx errors (validation, auth, not found) are never retried.

CommonJS

const { Velobase } = require('@velobaseai/billing');

const vb = new Velobase({ apiKey: 'vb_live_xxx' });

License

MIT