TypeScript

The official TypeScript server SDK for the Bias API. It ships with fully typed resources and parameters, type-safe expansion generics, cursor pagination, async-iterator event streaming, and idiomatic error handling. The package is generated from the Bias OpenAPI specification.

Installation

npm install @biaspay/sdk

Requires a JavaScript runtime with a global fetch implementation — Node.js 18+, Bun, Deno, or any modern browser.

Usage

Construct a client with your API key and call resource methods directly. Models are returned as fully typed objects.

import { Bias } from "@biaspay/sdk";

const bias = new Bias(process.env.BIAS_API_KEY!);

const customer = await bias.customers.create({
    name: "Acme, Inc.",
    email: "billing@acme.example",
});

console.log(customer.id, customer.email);

Pagination

List methods return a page object with object: "list", an items array, and a has_more boolean. Pass starting_after (the last item’s id) to fetch the next page.

let page = await bias.customers.list({ limit: 100 });
if (page.object === "error") throw new Error(page.error.message);

for (const customer of page.items) {
    console.log(customer.id);
}

To walk every page transparently, pass the list method to iterateListPages. It yields each page in turn, following the cursor until has_more is false.

import { iterateListPages } from "@biaspay/sdk";

for await (const page of iterateListPages(bias.customers.list, { limit: 100 })) {
    if (page.object === "error") throw new Error(page.error.message);
    console.log(page.items.length, page.has_more);
}

If you want every item collected into a single list, use fetchListPages. Pass maxItems to limit the total length.

import { fetchListPages } from "@biaspay/sdk";

const all = await fetchListPages(bias.customers.list, { limit: 100 }, { maxItems: 500 });
if (all.object === "error") throw new Error(all.error.message);

console.log(all.items.length, all.has_more);

Expanding related objects

Pass an expand parameter to inline related objects instead of receiving bare IDs. The object shape mirrors the resource tree, and the return type is narrowed to the expanded form automatically — no casts required. See expansion for the full list of expandable fields.

const payment = await bias.payments.get("pay_123", {
    expand: { customer: true },
});

if (payment.object !== "error") {
    payment.customer; // a Customer object, not just a string id
}

Nested expansions are typed too — pass an object instead of true to expand deeper.

const payment = await bias.payments.get("pay_123", {
    expand: { payment_method: { customer: true } },
});

If a field was not expanded, assertExpanded narrows it at runtime and throws a BiasError if it is still an id string. Use getId to accept either an id or an object holding an id.

import { assertExpanded } from "@biaspay/sdk";

const customer = assertExpanded(payment.customer);

Streaming events

The events resource can return a long-lived stream of events instead of a single page. Set stream: true and treat the result as an async iterator; heartbeats sent to keep the connection alive are skipped automatically.

const stream = await bias.events.list({
    stream: true,
    filters: { type: "customer.created" },
});

if ("object" in stream && stream.object === "error") throw new Error(stream.error.message);

for await (const event of stream) {
    const customer = event.state; // typed as the event's payload
    console.log(`New customer: ${customer.name}`);
}

See the event streaming guide for more.

Error handling

API errors are returned, not thrown — they are part of every method’s return type as a discriminated union with object: "error". Narrow on object before reading the result.

const payment = await bias.payments.create({ amount: -1 });

if (payment.object === "error") {
    console.log(payment.error.type, payment.error.message, payment.error.param);
} else {
    console.log(payment.id);
}

Every error object exposes error.type, error.message, error.param, and error.code. The error.type discriminates the category:

Client-side failures — no API key, no fetch implementation, or an unexpected request parameter — throw a BiasError. Network and timeout failures throw the underlying fetch error (or an AbortError when the request exceeds the timeout). Wrap calls in try/catch to handle these.

import { BiasError } from "@biaspay/sdk";

try {
    await bias.customers.create({ name: "Acme" });
} catch (err) {
    if (err instanceof BiasError) {
        console.error(err.message);
    }
}

Idempotency

Every POST and PATCH request automatically sends an idempotency-key header, generated as a UUID. To reuse a key across retries, pass idempotencyKey in the request config.

await bias.payments.create({ amount: 1000, currency: "usd" }, { idempotencyKey: "my-stable-key" });

See idempotency for details.

Configuration

Pass a Config object as the second argument to the constructor to override defaults.

const bias = new Bias(process.env.BIAS_API_KEY!, {
    baseURL: "https://api.biaspay.com",
    timeout: 30_000, // milliseconds, default 30_000
    networkRetries: 1, // retries on 429 / 5xx, default 1
    headers: { "x-app": "my-app" },
});

To customize transport, inject your own fetch implementation:

const bias = new Bias(process.env.BIAS_API_KEY!, {
    fetch: (input, init) => myInstrumentedFetch(input, init),
});

Resources

The client exposes every API resource as a typed namespace. Each method maps to an API reference endpoint.