@billium/node 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to `@billium/node` are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0]
+
+Initial public release. The API surface is covered by the SemVer guarantee from this point on — breaking changes will only ship in major releases.
+
+### Added
+
+- **Invoices client.** `billium.invoices.create / get / list / cancel`. The `Invoice` response shape mirrors the backend exactly: customer information is nested under `invoice.customer` (as `InvoiceCustomer | null`), and `rawAmount` / `endAmount` are returned as **strings** (Prisma `Decimal(15,6)` serialized) rather than numbers — use a decimal library like `decimal.js` for arithmetic.
+- **Webhook signature verification.** `billium.webhooks.verify(rawBody, signatureHeader)` performs HMAC-SHA256 with timing-safe comparison and a configurable tolerance window. Drop-in for Express, Fastify, Hono, Next.js Route Handlers — anywhere you can get the raw request body.
+- **Webhook management.** `billium.webhooks.create / list / update / delete / ping` for managing webhook endpoints from server code. Requires a secret key.
+- **Idempotency-Key support** on `invoices.create()` via `{ idempotencyKey }` option. The server deduplicates retries within a 24 h window so a network blip can't create duplicate invoices. Generate a UUID v4 per logical operation.
+- **Automatic retries** for transient failures (`5xx`, `429`, network errors) with exponential backoff and full jitter. Honors `Retry-After` headers when present. Configurable via `maxRetries`, `baseDelayMs`, `maxDelayMs` on the `Billium` constructor (defaults: 2 retries, 500 ms base, 30 s cap). `POST` is only retried when an `Idempotency-Key` header is set — without one, the SDK refuses to retry POSTs to avoid creating duplicates.
+- **Public-key safety guard.** Billium issues two API key types: `pk_*` (public, scope-limited) and `sk_*` (secret, full access). The SDK detects the `pk_*` prefix at construct time and throws a `BilliumError` immediately when a method that requires secret scope (`webhooks.create / list / update / delete / ping`, `invoices.cancel`) is called — no round-tripping a generic `403` from the backend to find out you used the wrong key. Public keys are reserved for future browser-side SDKs.
+- **Prefixed resource IDs.** Every entity returned by the API has a typed prefix: `mer_` (merchant), `inv_` (invoice), `pay_` (payment), `cus_` (customer), `prd_` (product), `wh_` (webhook endpoint), `wal_` (wallet), `tle_` (invoice timeline entry), `evt_` (webhook event). Format: `{prefix}_{32 hex chars}`. The SDK treats IDs as opaque strings — pass them through verbatim. See the README's "About resource IDs" section.
+- **Webhook event types.** The full `WebhookEventType` union covers every event the backend emits: `invoice.created/updated/paid/underpaid/overpaid/expired/cancelled`, `payment.created/updated/detected/confirmed/paid/underpaid/overpaid/expired`, plus the `invoice.*` and `payment.*` wildcards.
+- **Per-event delivery guarantees** documented in the README. Terminal-state events (`invoice.paid`, `payment.confirmed`, etc.) flow through a transactional outbox with at-least-once delivery and crash recovery. Best-effort events (`invoice.updated`, `payment.updated`, `payment.created`) are emitted in-process for sub-second UI sync — use them as UI hints, not for critical business logic.
+- **`User-Agent` header** (`billium-node/<version> (node/<process.version>)`) on every request, so backend operators can segment traffic by SDK version.
+- **Dual ESM / CJS build** with TypeScript declarations for both module formats. `Billium` is exposed as a named export only — `import { Billium } from '@billium/node'` (ESM) or `const { Billium } = require('@billium/node')` (CJS) — to keep CJS consumers free of `.default` foot-guns and to tree-shake cleanly in modern bundlers.
+- **Zero runtime dependencies.** The SDK uses only native Node.js APIs: `crypto` for HMAC verification, `fetch` for HTTP. Total install footprint ≈ 47 KB packed.
+- **Public TypeScript surface** re-exports `Invoice`, `InvoiceStatus`, `InvoiceCustomer`, `InvoiceProduct`, `InvoicePayment`, `InvoiceTimelineEntry`, `CreateInvoiceParams`, `CreateInvoiceOptions`, `ListInvoicesParams`, `PaginatedResult`, `Webhook`, `WebhookEvent`, `WebhookEventType`, `WebhookSecret`, `CreateWebhookParams`, `UpdateWebhookParams`, `VerifyOptions`, `BilliumError`, `BilliumApiError`, `BilliumWebhookSignatureError`, `BilliumWebhookTimestampError`, and `SDK_VERSION`.
+- **Test suite typecheck.** `npm run lint` typechecks both `src/` and `tests/` (via a separate `tsconfig.test.json`), so type drift in fixtures fails CI alongside source code.
+- **npm provenance.** Releases are published from GitHub Actions via OIDC, so every published version carries a verifiable cryptographic attestation tying the tarball to its source commit. Verify with `npm audit signatures @billium/node`.
+
+### Server-side prerequisites
+
+These backend behaviors are required for `@billium/node 1.0.0` to work end-to-end. They shipped alongside the SDK as part of the same launch:
+
+- `POST /merchants/merchant/:merchantId/invoices` returns the full invoice DTO with relations (the same shape as `GET /invoices/:id`).
+- `POST /merchants/merchant/:merchantId/invoices/:invoiceId/cancel` returns the same full shape.
+- `invoice.cancelled` webhook event is emitted via the outbox when a merchant cancels an invoice, with at-least-once delivery semantics.
+- `Idempotency-Key` header is honored on `POST /invoices` with a 24 h TTL, body-hash mismatch detection, and an in-flight processing lock.
+- A global response interceptor (`IdSerializerInterceptor`) prefixes resource IDs on every API response (`mer_`, `inv_`, etc.), and a global request middleware (`StripIdPrefixMiddleware`) strips the prefix on the way back in. Prisma still stores bare UUIDs at the database layer — the prefix lives only on the wire.
+- Two-tier rate limiting: a global IP-based throttler (50 req / 60 s) and a per-API-key throttler (300 req / 60 s, keyed off the `x-api-key` prefix). Both expose `X-RateLimit-Limit / Remaining / Reset` and `Retry-After` headers, which the SDK's retry loop honors automatically.
+
+[1.0.0]: https://github.com/BilliumHQ/billium-node/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Billium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,300 @@
+# @billium/node
+
+Official Node.js SDK for [Billium](https://billium.to) — non-custodial crypto payments.
+
+## Installation
+
+```bash
+npm install @billium/node
+```
+
+## Quick start
+
+```typescript
+import { Billium } from '@billium/node';
+
+const billium = new Billium({
+  apiKey: process.env.BILLIUM_API_KEY,           // sk_... (secret key)
+  merchantId: process.env.BILLIUM_MERCHANT_ID,   // mer_...
+  webhookSecret: process.env.BILLIUM_WEBHOOK_SECRET, // whsec_... (optional)
+});
+```
+
+### About API keys
+
+Billium issues two key types from the dashboard (Settings → Developer → API keys):
+
+| Type | Prefix | Scope | Where to use |
+|---|---|---|---|
+| **Secret** | `sk_*` | Full server-side access — invoices, webhook management, customers, products | **This SDK.** Server code only — never ship a secret key to a browser. |
+| **Public** | `pk_*` | Limited to `invoice.create`, `invoice.view`, `product.view` | Future browser-side SDKs (vanilla JS, React, Vue, Next.js client components) — not consumed by `@billium/node`. |
+
+`@billium/node` is built for server environments and consumes **secret keys** (`sk_*`). If you pass a public key by mistake, methods that require secret scope (`webhooks.create()`, `invoices.cancel()`, etc.) will throw a `BilliumError` immediately with a clear message — they won't round-trip a generic `403` from the backend.
+
+If you need to call Billium from a browser, route your requests through your own backend (running `@billium/node`) instead of calling Billium directly from client code. A browser-targeted SDK is on the roadmap, but its exact form — vanilla JS, React components, Vue, framework-agnostic — hasn't been decided yet, so there's no specific package name to wait on.
+
+### About resource IDs
+
+Every Billium resource ID is prefixed with a short tag indicating its type, followed by 32 hexadecimal characters. The prefix is for human and log-debuggability — when you see one of these in an error message, you instantly know what kind of resource it points at, without having to chase down which field it came from.
+
+| Resource | Prefix | Example |
+|---|---|---|
+| Merchant | `mer_` | `mer_550e8400e29b41d4a716446655440000` |
+| Invoice | `inv_` | `inv_7d9b8e2c1a4f4e3d9c2b8f7a6d5e3b1c` |
+| Payment | `pay_` | `pay_3a1b9c8d7e6f5a4b3c2d1e0f9a8b7c6d` |
+| Customer | `cus_` | `cus_a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7` |
+| Product | `prd_` | `prd_b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8` |
+| Webhook endpoint | `wh_` | `wh_c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9` |
+| Wallet | `wal_` | `wal_d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0` |
+| Invoice timeline entry | `tle_` | `tle_e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1` |
+| Webhook event | `evt_` | `evt_f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2` |
+
+The SDK treats IDs as opaque strings. You don't need to parse or construct them yourself — pass them through verbatim. The backend accepts both prefixed and bare UUID forms during the transition window, but you should always use the prefixed form returned by the API in production code.
+
+## Invoices
+
+### Create an invoice
+
+```typescript
+import { randomUUID } from 'crypto';
+
+const invoice = await billium.invoices.create(
+  {
+    name: 'Order #1234',
+    rawAmount: 99.99,
+    currency: 'USD',
+    customerEmail: 'customer@example.com',
+    redirectUrl: 'https://yoursite.com/thank-you',
+  },
+  { idempotencyKey: randomUUID() },
+);
+
+console.log(invoice.id); // inv_...
+```
+
+#### Idempotency keys
+
+Pass `idempotencyKey` whenever you call `create()` from anywhere a retry might happen — webhook handlers, queue workers, mobile-initiated checkouts, anything subject to timeouts or duplicate clicks.
+
+The server stores the response keyed by `(merchantId, idempotencyKey)` for **24 hours**. If the same key arrives again with the same body, you get back the original invoice — no duplicate is created. If the key arrives with a *different* body, the server returns `409 Conflict` (it's almost always a programmer bug to reuse a key for two different requests).
+
+The key also unlocks **automatic retries** on `create()`: without it, the SDK refuses to retry a failed `POST` because it can't prove the original didn't already succeed server-side. With it, the SDK will retry on transient errors (`5xx`, `429`, network failures) using exponential backoff with jitter.
+
+```typescript
+// One key per logical operation. UUID v4 is a good default.
+await billium.invoices.create(params, { idempotencyKey: randomUUID() });
+
+// Or, scope by your own business identifier — anything stable per attempt.
+await billium.invoices.create(params, { idempotencyKey: `cart-${cartId}` });
+```
+
+### Get an invoice
+
+```typescript
+const invoice = await billium.invoices.get('inv_...');
+
+invoice.id;                  // 'inv_...'
+invoice.status;              // 'AWAITING_PAYMENT' | 'PAID' | ...
+invoice.rawAmount;           // string — Decimal(15,6) serialized, use a decimal lib for math
+invoice.customer?.email;     // string | undefined
+invoice.payments;            // InvoicePayment[] — on-chain payments received against this invoice
+invoice.invoiceTimeline;     // InvoiceTimelineEntry[] — status transition history
+```
+
+> **Note on amounts:** `rawAmount` and `endAmount` are returned as **strings**, not numbers. They're stored as `Decimal(15, 6)` in the database and serialized as strings to preserve precision. Use a decimal library (e.g. [`decimal.js`](https://github.com/MikeMcl/decimal.js/)) if you need to do arithmetic on them.
+
+### List invoices
+
+```typescript
+const result = await billium.invoices.list({
+  page: 1,
+  limit: 20,
+  search: 'Order',
+});
+
+console.log(result.data);  // Invoice[]
+console.log(result.total); // total count
+```
+
+### Cancel an invoice
+
+```typescript
+await billium.invoices.cancel('inv_...');
+```
+
+## Webhooks
+
+### Verify a webhook signature
+
+Use `billium.webhooks.verify()` inside your webhook handler to validate that the request came from Billium.
+
+```typescript
+import express from 'express';
+
+const app = express();
+
+app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
+  try {
+    const event = billium.webhooks.verify(
+      req.body,                      // raw body (Buffer or string)
+      req.headers['x-signature'],    // signature header
+    );
+
+    switch (event.event) {
+      case 'invoice.paid':
+        // handle payment
+        break;
+      case 'invoice.expired':
+        // handle expiration
+        break;
+    }
+
+    res.sendStatus(200);
+  } catch (err) {
+    console.error('Webhook verification failed:', err);
+    res.sendStatus(400);
+  }
+});
+```
+
+You can also pass the secret explicitly per call:
+
+```typescript
+const event = billium.webhooks.verify(body, signature, 'whsec_...');
+```
+
+### Manage webhook endpoints
+
+```typescript
+// Create
+const webhook = await billium.webhooks.create({
+  url: 'https://yoursite.com/webhooks',
+  events: ['invoice.paid', 'invoice.expired'],
+  description: 'Production webhook',
+});
+
+// List
+const webhooks = await billium.webhooks.list();
+
+// Update
+await billium.webhooks.update(webhook.id, {
+  events: ['invoice.*'],
+});
+
+// Ping (send a test event)
+await billium.webhooks.ping(webhook.id);
+
+// Delete
+await billium.webhooks.delete(webhook.id);
+```
+
+### Webhook event types
+
+| Event | Delivery | Description |
+|-------|----------|-------------|
+| `invoice.*` | — | All invoice events (subscribe wildcard) |
+| `invoice.created` | durable | Invoice was created |
+| `invoice.updated` | best-effort | Invoice fields changed (status, expiry, etc.) |
+| `invoice.paid` | **durable** | Invoice fully paid |
+| `invoice.underpaid` | **durable** | Payment received but insufficient |
+| `invoice.overpaid` | **durable** | Payment exceeds invoice amount |
+| `invoice.expired` | **durable** | Invoice expired without payment |
+| `invoice.cancelled` | **durable** | Invoice was cancelled by the merchant |
+| `payment.*` | — | All payment events (subscribe wildcard) |
+| `payment.created` | best-effort | Payment was created (customer initiated checkout) |
+| `payment.updated` | best-effort | Payment fields changed (e.g. confirmation count) |
+| `payment.detected` | **durable** | On-chain payment detected |
+| `payment.confirmed` | **durable** | Payment confirmed on-chain |
+| `payment.paid` | **durable** | Payment completed |
+| `payment.underpaid` | **durable** | Underpayment detected |
+| `payment.overpaid` | **durable** | Overpayment detected |
+| `payment.expired` | **durable** | Payment expired |
+
+#### Delivery guarantees
+
+Billium emits webhooks via two paths depending on the event criticality:
+
+- **Durable events** are written to a transactional outbox in the same database transaction as the underlying state change. A background processor picks them up every 10 seconds and delivers them — **even if the Billium backend crashes between the state change and the delivery attempt**, the event is replayed once the process recovers. These events have **at-least-once** delivery semantics: design your handler to be idempotent (e.g. dedupe on the `event.id` field).
+
+- **Best-effort events** (`invoice.updated`, `payment.updated`, `payment.created`) are emitted in-process from the same request that triggered them, optimized for real-time UI sync (sub-second latency). These events have **at-most-once** semantics: a backend crash between the state change and HTTP delivery may drop them. Use them to keep your dashboards fresh, **not** to drive critical business logic — for that, listen to the matching durable event (e.g. use `payment.detected` / `payment.confirmed` instead of `payment.updated`).
+
+In practice: **subscribe to terminal-state events for anything that touches money or fulfillment**, and treat `*.updated` and `payment.created` as nice-to-have UI hints.
+
+## Configuration
+
+```typescript
+const billium = new Billium({
+  apiKey: '...',         // Required for invoices and webhook management
+  merchantId: '...',     // Required for invoices and webhook management
+  webhookSecret: '...',  // Optional — default secret for webhook verification
+  baseUrl: '...',        // Optional — defaults to https://api.billium.to
+
+  // Retry configuration (all optional)
+  maxRetries: 2,         // Total HTTP calls = maxRetries + 1. Default: 2
+  baseDelayMs: 500,      // Initial backoff delay. Default: 500ms
+  maxDelayMs: 30_000,    // Cap on backoff. Default: 30s
+});
+```
+
+### Retries
+
+The SDK automatically retries failed requests on:
+
+- **Network errors** (DNS failure, connection reset, TLS handshake)
+- **5xx responses** (500, 502, 503, 504)
+- **429 Too Many Requests** — honoring the `Retry-After` header when present
+
+Backoff is exponential with full jitter, so a fleet of clients failing simultaneously won't all retry at the same instant.
+
+**Retry safety on POST**: `GET`, `PUT`, `PATCH`, and `DELETE` are always retried because they're idempotent by HTTP convention. `POST` is **only** retried when an `Idempotency-Key` is set on the request — otherwise a retry could create a duplicate resource if the original POST reached the server but the response was lost in transit. See the next section for how to set an idempotency key.
+
+You can create a client with only `webhookSecret` if you only need to verify webhooks:
+
+```typescript
+const billium = new Billium({
+  webhookSecret: process.env.BILLIUM_WEBHOOK_SECRET,
+});
+
+// This works:
+const event = billium.webhooks.verify(body, signature);
+
+// This throws — apiKey and merchantId are required:
+await billium.invoices.list();
+```
+
+## Error handling
+
+```typescript
+import {
+  BilliumError,
+  BilliumApiError,
+  BilliumWebhookSignatureError,
+  BilliumWebhookTimestampError,
+} from '@billium/node';
+
+try {
+  await billium.invoices.create({ name: 'Test', rawAmount: 10 });
+} catch (err) {
+  if (err instanceof BilliumApiError) {
+    console.log(err.status);  // HTTP status code
+    console.log(err.code);    // API error code
+    console.log(err.message); // Error message
+  }
+}
+```
+
+| Error class | When |
+|-------------|------|
+| `BilliumError` | Base error — missing configuration |
+| `BilliumApiError` | API returned a non-2xx response |
+| `BilliumWebhookSignatureError` | Webhook signature mismatch or malformed header |
+| `BilliumWebhookTimestampError` | Webhook timestamp outside tolerance window |
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Zero production dependencies
+
+## License
+
+MIT