TypeScript SDK

@orbytelabs/credit provides the Credit SDK and the orbyte catalog CLI. It requires Node.js 24+ and ESM.

pnpm add @orbytelabs/credit

Follow the quickstart to create a key and deploy your first catalog.

Keep the SDK on your server. Set ORBYTE_API_KEY in your environment. The SDK uses https://api.orbytelabs.com automatically; you do not need to set an API URL. See authentication for keys and permissions.

Use the direct functions

Use check, track, topup, and getWallet for day-to-day billing.

import { check, credit, getWallet, topup, track } from "@orbytelabs/credit";

const identity = "customer_123";
const credits = credit("credits");

// Run once for a confirmed purchase or grant.
await topup(identity, credits(100), {
  idempotencyKey: "purchase_123",
});

const access = await check("api-call", identity, { quantity: 2 });
if (!access.allowed) throw new Error("Usage is not allowed.");

// Perform the work, then record its completed usage.
await track("api-call", identity, {
  id: "request_batch_123",
  quantity: 2,
});

const wallet = await getWallet(identity);
console.log(wallet?.balances);

This example uses the credits credit type and api-call feature from the quickstart. Choose IDs from your own purchase and usage records. Keep the same ID when retrying the same operation.

The wallet argument accepts an identity string or an object containing identity, including a wallet returned by getWallet. Amounts in responses are integer nanocredit strings. One credit equals 1_000_000_000 nanocredits.

When a plan allowance applies, check can also return limit with limit, used, remaining, periodStart, periodEnd, and overage. The optional reason describes a denial, such as feature_limit_exceeded or subscription_inactive. Always branch on allowed; a denied check does not necessarily mean the wallet needs a top-up.

Check and track options

For a fixed price, pass its typed name directly, such as check("api-call", identity). The generated _orbyte.ts registers the valid names with the SDK. No runtime import of the config or generated enums is required. Generated Features enum values and feature objects from your config remain supported.

Callback prices require the feature object so the SDK can evaluate your function on your server. Generated types reject callback names in string-based calls. See pricing.

topup accepts an idempotencyKey; it generates a UUID when omitted. See wallets and top-ups for funding after payments and handling duplicate requests.

Subscriptions and payments

These functions are also exported from @orbytelabs/credit. See subscriptions and payments for Stripe setup, required options, and complete examples.

Connection options

All functions above accept these options in their final argument. Explicit values override the environment.

The defaults work for both Development and Production; your API key selects the application. For a custom API server, the optional url option or ORBYTE_API_URL environment variable can override the address. Use an origin with no API path, credentials, query, or fragment. HTTPS is required except for loopback development addresses. A custom fetch implementation receives your key and request data.

import { check } from "@orbytelabs/credit";

const access = await check("api-call", "customer_123", {
  apiKey: process.env.ORBYTE_API_KEY,
});
console.log(access.allowed);

The direct functions read the process environment. They do not load .env.local themselves; your server or process launcher must load it. The CLI loads .env.local next to the config file.

Use a client for administration

Create an OrbyteClient when you need catalog administration, deposit history, or wallet billing periods. It accepts the same connection options.

import { OrbyteClient } from "@orbytelabs/credit";

const client = new OrbyteClient();
const application = await client.application();
const features = await client.listFeatures();
const deposits = await client.listDeposits({ identity: "customer_123" });

console.log(application.name, features.length, deposits.length);

List methods collect all pages into an array. See the API reference for request fields and permission requirements.

Pass { config } to the constructor to use callback prices through client.check and client.ingest. The client then requires features from that config and infers their data types.

Plan reads require plans:read; plan creation and updates require plans:write. PlanInput and PlanRecord describe the request and response. A plan includes amountCents, currency, a monthly or yearly interval, and featureLimits. Optional creditGrants deposits credits after confirmed creation, renewal, or full-period migration invoices, topupsEnabled controls paid top-up checkout, and featureMultipliers applies per-plan rates in basis points. Use the same raw { creditKey, amountNanocredits } grant entries as the REST API. See plans and allowances for configuration, included quantities, and overage behavior.

Deploy your catalog

Use the orbyte CLI to deploy credits, features, and plans from orbyte.config.ts.

pnpm exec orbyte deploy --dry-run
pnpm exec orbyte deploy

The CLI generates _orbyte.ts to type feature names in SDK calls. See deployment for catalog updates and Production deployment, watch mode for local development, and generated types for TypeScript setup.

Handle failures

HTTP errors throw OrbyteApiError with status, code, and message. Network failures and interrupted response reads throw OrbyteTransportError. Invalid configuration and response data can fail local validation.

Requests time out after 20 seconds per attempt. The SDK makes up to two retries for supported transient failures. It retries reads, updates, checks, event ingestion, and deposits; catalog creation is not retried after an ambiguous transport failure. A recognized rate_limited response can be retried for any request.

Automatic event and deposit retries retain the same IDs. If your application starts a fresh SDK call after a failure, pass the original event ID or deposit idempotency key again. See checking and tracking and errors.