# Node.js server SDK

Typed resources, automatic transient retries, cursor pagination, idempotency, and webhook verification for Node.js 18+.

> **Note — Release status**
>
> npm currently serves `billerapi@0.1.0`. The reviewed next release intent is `2.0.0`; use the registry version until an exact-SHA publication receipt is attached.

## Install and initialize

**npm**

```bash
npm install billerapi
```

**TypeScript**

```javascript
import { BillerApi } from 'billerapi';

const billerapi = new BillerApi(process.env.BILLERAPI_API_KEY!, {
  maxRetries: 2,
  timeout: 30_000,
});

const page = await billerapi.bills.list({ account_link_id: 'link_123' });
console.log(page.data);
```

## Resource map

| Accessor | Use it for |
| --- | --- |
| billerapi.billers | Catalog search and retrieval |
| billerapi.links | Link tokens, status, exchange, and link retrieval |
| billerapi.bills | List, detail, statements, create, and sync |
| billerapi.billImports | Upload, review, confirm, and cancel |
| billerapi.accountLinks | Sync and refresh status |
| billerapi.webhookEndpoints | Endpoint lifecycle and secret rotation |
| billerapi.pay | Pay tokens, payment methods, and payment attempts |
| billerapi.feedback | Structured integration feedback |
| billerapi.webhooks | Signature verification and event construction |

> **Tip — Let the SDK own transport behavior**
>
> The SDK retries network errors, 429s, and retryable 5xx responses. Mutation helpers preserve idempotency keys across transparent retries. Branch on typed errors and keep the request ID for support.

Prefer raw HTTP? Every SDK call maps directly to the [API reference](/docs/api).

## Migrating from 0.1.0 to 2.0.0

The tables below are generated from the one SDK deprecation record, so this page, its markdown and the standalone migration guide cannot disagree with each other.

Every entry describes the SDK artifact `billerapi`, not the REST API. The REST API keeps accepting and emitting the legacy money and date fields under its own published compatibility window; only the SDK's TypeScript surface performs the hard cutover.

There is exactly one upgrade to make: `1.0.0` and `1.1.0` were reviewed but never published, so the `deprecated in` column is history rather than a window you can pin to.

Full narrative, a before/after example for every entry and a dry-run codemod fixture live in the repository at `docs/api/sdk-migration-0.1-to-2.0.md`.

<!-- BEGIN GENERATED sdk-deprecations -->

<!-- Generated from config/sdk-deprecations.json. Do not edit inside this block; run `node scripts/ci/generate-sdk-deprecations.mjs`. -->

### Compatibility matrix

| SDK version | On npm | REST audience plane | Bill money and dates | `billers.list` pagination | Webhook signature header |
| --- | --- | --- | --- | --- | --- |
| `0.1.0` | yes | pre-/v1 bare and legacy IAM route shapes | legacy amount / currency / due_date only | page-based (page / page_size) | BillerAPI-Signature or legacy BillButler-Signature |
| `1.0.0` | no | /v1 audience plane, no aliases | legacy amount / currency / due_date only | page-based (page / page_size) | BillerAPI-Signature or legacy BillButler-Signature |
| `1.1.0` | no | /v1 audience plane, no aliases | canonical total_amount / due_date_iso added; legacy fields kept and marked @deprecated | page-based (page / page_size) | BillerAPI-Signature or legacy BillButler-Signature |
| `2.0.0` | no | /v1 audience plane, no aliases | canonical total_amount / due_date_iso only on request and response types | cursor-only (limit / cursor) | BillerAPI-Signature only |

- `0.1.0` — The only version npm serves today. Everything below is unpublished release intent.
- `1.0.0` — The 0.x to 1.x contract boundary: retired route shapes are not aliased.
- `1.1.0` — Superseded by 2.0.0 and never published; listed so the deprecated_in column resolves.
- `2.0.0` — Reviewed release intent. The REST API still accepts and returns the legacy fields; the removal is SDK-side.

> **Scope.** Every entry describes the SDK artifact `billerapi`, not the REST API. The REST API keeps accepting and emitting the legacy money and date fields under its own published compatibility window; only the SDK's TypeScript surface performs the hard cutover.

### What changed

Each row's narrative section, with a before/after example, is in `docs/api/sdk-migration-0.1-to-2.0.md`.

| Removed symbol or behavior | Deprecated in | Removed in | Replacement | Section |
| --- | --- | --- | --- | --- |
| `Bill.amount`, `Bill.currency`, `Bill.due_date` | `1.1.0` | `2.0.0` | `Bill.total_amount.value, Bill.total_amount.currency, Bill.due_date_iso` | Bill legacy money and date fields |
| `SyncedBill.amount`, `SyncedBill.currency`, `SyncedBill.due_date` | `1.1.0` | `2.0.0` | `SyncedBill.total_amount.value, SyncedBill.total_amount.currency, SyncedBill.due_date_iso` | SyncedBill legacy money and date fields |
| `CreateClientBillParams.amount_due`, `CreateClientBillParams.currency`, `CreateClientBillParams.due_date` | `1.1.0` | `2.0.0` | `CreateClientBillParams.total_amount, CreateClientBillParams.due_date_iso` | bills.create legacy money and date params |
| `BillImportReviewChanges.amount_due`, `BillImportReviewChanges.currency`, `BillImportReviewChanges.due_date` | `1.1.0` | `2.0.0` | `BillImportReviewChanges.total_amount, BillImportReviewChanges.due_date_iso` | Bill-import review changes legacy money and date operations |
| `BillerListParams.page`, `BillerListParams.page_size` | `1.1.0` | `2.0.0` | `BillerListParams.limit, BillerListParams.cursor` | billers.list page-based pagination |
| `webhooks.constructEvent` | `1.0.0` | `2.0.0` | `BillerAPI-Signature` | Legacy BillButler-Signature webhook header |
| `BillerApi.request` | `0.1.0` | `1.0.0` | `/v1 audience-plane paths` | Pre-/v1 bare and legacy IAM route shapes |
| `webhookEndpoints.create`, `webhookEndpoints.list`, `webhookEndpoints.update` | `0.1.0` | `1.0.0` | `/v1/webhook-endpoints` | Underscored /v1/webhook_endpoints path |

<!-- END GENERATED sdk-deprecations -->