JavaScript SDK

npm install @velobaseai/billing@^1.2.0

import { Velobase } from "@velobaseai/billing";

const vb = new Velobase({ apiKey: "vb_live_your_project_key" });
// baseUrl defaults to https://api.velobase.io, override for self-hosted / dev:
// const vb = new Velobase({ apiKey: "...", baseUrl: "https://api.velobase.io" });

await vb.customers.deposit({ customerId: "user_123", amount: 5_000_000 }); // $5.00

await vb.customers.deposit({
  customerId: "user_123",
  amount: 5_000_000,
  idempotencyKey: "stripe_evt_1a2b3c",
});

const cust = await vb.customers.get("user_123");
const wallet = cust.wallets["credits"];
console.log(wallet.available, "available");
wallet.sources.forEach((s) => console.log(s.source, s.available));

const page = await vb.customers.ledger("user_123", { limit: 20 });
for (const entry of page.items) {
  console.log(entry.operationType, entry.amount, entry.transactionId);
}
if (page.hasMore) {
  const next = await vb.customers.ledger("user_123", { cursor: page.nextCursor });
}

// Known cost up front: 200,000 credits = $0.20
await vb.billing.deduct({ customerId: "user_123", transactionId: "img_001", amount: 200_000 });

// Unknown cost: reserve a budget, then settle the actual amount.
await vb.billing.freeze({ customerId: "user_123", transactionId: "job_001", amount: 1_000_000 });
await vb.billing.consume({ transactionId: "job_001", actualAmount: 730_000 }); // releases the rest
// await vb.billing.unfreeze({ transactionId: "job_001" }); // cancel, release everything

const usage = await vb.usage.list({ customerId: "user_123", limit: 20 });

const receipt = await vb.receipts.get("txn_abc123"); // transaction id from a call

import { GATEWAY_HEADERS, parseGatewayInsufficientBalance } from "@velobaseai/billing";

// on a 402 error from the gateway:
const details = parseGatewayInsufficientBalance(errorBody);
if (details) {
  // show your paywall with the required / available credit amounts
}