@allowancejs/api-client

Typed HTTP client for the AllowanceJS API.

Types are the single source of truth shared across the SDK, dashboards, and admin surfaces — kept aligned with the proto definitions in /proto/allowancejs/v1.

Install

npm install @allowancejs/api-client

Usage

import { AllowanceClient } from "@allowancejs/api-client";

const client = new AllowanceClient({
  baseUrl: "https://api.example.com",
  getToken: async () => getSessionToken(),
});

// Fetch the current balance (read tier)
const balance = await client.getBalance({ userId: "user_xyz" });
console.log(balance.remainingUnits, balance.allowanceUnits, balance.outOfAllowance);

// Preflight a governed action (kill switch / per-feature cap / total budget)
const decision = await client.checkAllowance({
  userId: "user_xyz",
  featureKey: "summarize",
  estimateUnits: 1500,
});

This client is the read + governance surface. Usage events are not submitted here — metering metadata is pushed to the ingest service (or its gateway/OTel adapters), never through @allowancejs/api-client. To report usage from your backend, use the per-language ingest SDKs under clients/ — see the server-side reference.

Error handling

import { RpcError } from "@allowancejs/api-client";

try {
  await client.getBalance({ userId: "user_xyz" });
} catch (err) {
  if (err instanceof RpcError) {
    console.error(err.code, err.httpStatus, err.message);
  }
}

Format utilities

import { toDisplay, formatUsage } from "@allowancejs/api-client";

// Convert raw units to a display string (positional args: units, metric, locale?)
const label = formatUsage(1_500_000, "usd"); // "$1.50"

Key exports

AllowanceClient, RpcError, toDisplay, unitsFromDisplay, formatUsage, compactUsage — plus the complete domain type inventory (Period, UsageMetric, BudgetScope, request/response interfaces, etc.). See src/types.ts for the full list.