JavaScript API

bursar for TypeScript/JavaScript is published as @zonastery/bursar on npm. Requires Node.js 18+.

Installation

npm install @zonastery/bursar

# PostgreSQL store (optional)
npm install pg

# YAML pricing loading (optional)
npm install js-yaml

Core Classes

Class / Type	Exported from	Description
PricingEngine	@zonastery/bursar	Pure calculation layer — no DB dependency
CreditManager	@zonastery/bursar	Orchestrates credit lifecycle
HttpxSupabaseStore	@zonastery/bursar	Supabase-backed store (native fetch, no extra deps)
PostgresStore	@zonastery/bursar	Direct PostgreSQL via pg
MemoryStore	@zonastery/bursar/node	In-memory store for testing (Node.js only)
CreditEventEmitter	@zonastery/bursar	Typed pub/sub for credit lifecycle events
UsageMetrics	@zonastery/bursar	Input interface for calculate() / deduct()
CostBreakdown	@zonastery/bursar	Structured cost breakdown (all fields Decimal)
CreditManagerOptions	@zonastery/bursar	Constructor options (policy, thresholds, TTL, …)
PricingConfigData	@zonastery/bursar	Schema for a pricing config dict
DeductionResult	@zonastery/bursar	Return type of deduct() / settle()
LeaseResult	@zonastery/bursar	Return type of reserve() / renew()
BalanceResult	@zonastery/bursar	Return type of getBalance()
CanAffordResult	@zonastery/bursar	Return type of canAfford() — includes .spendable (effective spending power)
TierBalancesResult	@zonastery/bursar	Return type of getCreditTiers() — per-tier balance breakdown
TierDefinition	@zonastery/bursar	Credit tier definition (priority, expiry, default/overdraft flags)
LowBalanceConfig	@zonastery/bursar	CreditManagerOptions.lowBalance shape: { thresholds, onTrigger }
CapabilityNotSupportedError	@zonastery/bursar	Thrown by a store's default implementation of an optional capability (analytics, transaction listing, teams) that wasn't overridden

All money values (balances, amounts, costs) are Decimal from decimal.js, never binary number.

Quick Example

import { CreditManager, PostgresStore } from "@zonastery/bursar";
// For tests / local dev, use MemoryStore from the Node subpath:
import { MemoryStore } from "@zonastery/bursar/node";

const store = new MemoryStore();
const manager = new CreditManager(store);

await manager.publishPricingFromDict({
  models: { "gpt-4": "input_tokens * (0.01 / 1000) + output_tokens * (0.03 / 1000)" },
});

await manager.addCredits("user_abc", 1000);
const result = await manager.deduct(
  "user_abc",
  { model: "gpt-4", inputTokens: 500, outputTokens: 200 },
  "idempotency-key-123",
);
// result.amount is a Decimal — use .toString() or .toNumber()
console.log(`Deducted ${result.amount.toString()} credits`);