@billium/node 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,483 @@
+declare class BilliumError extends Error {
+    constructor(message: string);
+}
+declare class BilliumWebhookSignatureError extends BilliumError {
+    constructor(message: string);
+}
+declare class BilliumWebhookTimestampError extends BilliumError {
+    constructor(message: string);
+}
+declare class BilliumApiError extends BilliumError {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+
+/**
+ * Single source of truth for the SDK version reported in the User-Agent
+ * header. **Keep this in sync with `package.json#version`** when bumping.
+ *
+ * Hardcoded rather than imported from package.json so that the build does
+ * not bundle the entire package.json blob (with dev/test config) into the
+ * production output.
+ */
+declare const SDK_VERSION = "1.0.0";
+
+interface HttpClientOptions {
+    /**
+     * Maximum number of retry attempts after the initial request fails.
+     * Total HTTP calls = maxRetries + 1. Set to 0 to disable retries entirely.
+     * @default 2
+     */
+    maxRetries?: number;
+    /**
+     * Initial backoff delay in milliseconds. Subsequent retries use
+     * exponential backoff with full jitter, capped at `maxDelayMs`.
+     * @default 500
+     */
+    baseDelayMs?: number;
+    /**
+     * Upper bound for the backoff delay between retries.
+     * @default 30000
+     */
+    maxDelayMs?: number;
+}
+/**
+ * Acceptable shape for query string params: any object whose values are
+ * primitives the URL spec can serialize. `undefined` and `null` values are
+ * dropped at serialization time (so callers can spread optional fields
+ * without filtering them first), and non-primitive values are skipped.
+ *
+ * Typed as `Readonly<Record<string, unknown>>` rather than a stricter union
+ * so user-defined interfaces with optional properties (e.g.
+ * `{ page?: number; limit?: number }`) can be passed directly without an
+ * `as Record<…>` cast — TypeScript's "weak type detection" otherwise
+ * refuses to widen interfaces with all-optional properties into a stricter
+ * value union.
+ */
+type QueryParams = Readonly<Record<string, unknown>>;
+interface RequestOptions {
+    body?: unknown;
+    params?: QueryParams;
+    headers?: Record<string, string>;
+}
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly isPublicKey;
+    private readonly maxRetries;
+    private readonly baseDelayMs;
+    private readonly maxDelayMs;
+    constructor(baseUrl: string, apiKey: string, options?: HttpClientOptions);
+    /**
+     * Throws a `BilliumError` if the configured key is a public key (`pk_*`).
+     *
+     * Used by methods that the backend won't accept a public key for —
+     * webhook management, invoice cancellation, anything that mutates state
+     * beyond invoice creation. Surfacing the error in the SDK rather than
+     * letting it round-trip to the backend gives developers a clear,
+     * actionable message instead of a generic `403 Insufficient permissions`.
+     *
+     * @param method - Dotted method name for the error message ("webhooks.create", etc.)
+     */
+    assertSecretKey(method: string): void;
+    get<T>(path: string, params?: object): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    private request;
+    private headers;
+    private buildUrl;
+    private parse;
+    /**
+     * Returns the number of milliseconds to wait before the next retry.
+     *
+     * Honors a `Retry-After` header on the response when present (parsed as
+     * either a delta-seconds integer or an HTTP date). Otherwise falls back
+     * to exponential backoff with full jitter — randomizing across the entire
+     * `[0, exponentialCeiling]` range to avoid retry storms when many
+     * clients fail simultaneously.
+     */
+    private computeDelay;
+    private sleep;
+}
+
+type WebhookEventType = 'invoice.*' | 'invoice.created' | 'invoice.updated' | 'invoice.paid' | 'invoice.underpaid' | 'invoice.overpaid' | 'invoice.expired' | 'invoice.cancelled' | 'payment.*' | 'payment.created' | 'payment.updated' | 'payment.detected' | 'payment.confirmed' | 'payment.paid' | 'payment.underpaid' | 'payment.overpaid' | 'payment.expired';
+interface WebhookSecret {
+    id: string;
+    webhookId: string;
+    secretKeyPreview: string;
+    isActive: boolean;
+    expiresAt?: string;
+}
+interface Webhook {
+    id: string;
+    merchantId: string;
+    url: string;
+    events: WebhookEventType[];
+    isActive: boolean;
+    description?: string;
+    /** Number of retry attempts on failure (0–10). */
+    retryCount: number;
+    /** Request timeout in milliseconds (1000–30000). */
+    timeout: number;
+    webhookSecrets: WebhookSecret[];
+}
+interface CreateWebhookParams {
+    /** The HTTPS URL Billium will POST events to. */
+    url: string;
+    /** List of event types to subscribe to. Use `'invoice.*'` or `'payment.*'` to subscribe to all events in a category. */
+    events: WebhookEventType[];
+    /** Optional description for this endpoint. */
+    description?: string;
+    /** Whether the webhook is active on creation. Defaults to `true`. */
+    isActive?: boolean;
+    /** Number of retry attempts on delivery failure (0–10). Defaults to `3`. */
+    retryCount?: number;
+    /** Request timeout in milliseconds (1000–30000). Defaults to `30000`. */
+    timeout?: number;
+}
+type UpdateWebhookParams = Partial<CreateWebhookParams>;
+interface WebhookEvent {
+    event: string;
+    id: string;
+    data: unknown;
+    timestamp: string;
+}
+interface VerifyOptions {
+    /**
+     * Maximum allowed age of the webhook timestamp in seconds.
+     * Set to 0 to disable the check.
+     * @default 300
+     */
+    tolerance?: number;
+}
+declare class WebhooksClient {
+    private readonly defaultSecret?;
+    private readonly http?;
+    private readonly basePath;
+    constructor(defaultSecret?: string | undefined, http?: HttpClient | undefined, merchantId?: string);
+    /**
+     * Parses and verifies an incoming Billium webhook request.
+     *
+     * Signature header format:  x-signature: t={unix_seconds},v1={hmac_sha256_hex}
+     * Signed string:            "{unix_seconds}.{raw_body}"
+     * Algorithm:                HMAC-SHA256
+     *
+     * If `webhookSecret` was passed to the `Billium` constructor, you can omit
+     * the `secret` argument here. Pass it explicitly to override.
+     *
+     * @param rawBody   Raw request body as Buffer or string — must not be parsed
+     * @param signature Value of the `x-signature` header
+     * @param secret    Webhook secret — can be omitted if set in the constructor
+     * @param options   Optional config (tolerance window)
+     *
+     * @throws {BilliumError}                  No secret available
+     * @throws {BilliumWebhookSignatureError}  Header malformed or HMAC mismatch
+     * @throws {BilliumWebhookTimestampError}  Timestamp outside tolerance window
+     */
+    verify(rawBody: Buffer | string, signature: string, secret?: string, options?: VerifyOptions): WebhookEvent;
+    /**
+     * Creates a new webhook endpoint for the merchant.
+     *
+     * Requires `apiKey` and `merchantId` in the constructor, and the `apiKey`
+     * must be a **secret key** (`sk_*`) — public keys do not have webhook
+     * management scope.
+     */
+    create(params: CreateWebhookParams): Promise<Webhook>;
+    /**
+     * Lists all webhook endpoints for the merchant.
+     *
+     * Requires `apiKey` and `merchantId` in the constructor, and the `apiKey`
+     * must be a secret key (`sk_*`).
+     */
+    list(): Promise<Webhook[]>;
+    /**
+     * Updates a webhook endpoint.
+     *
+     * Requires `apiKey` and `merchantId` in the constructor, and the `apiKey`
+     * must be a secret key (`sk_*`).
+     */
+    update(webhookId: string, params: UpdateWebhookParams): Promise<Webhook>;
+    /**
+     * Deletes a webhook endpoint.
+     *
+     * Requires `apiKey` and `merchantId` in the constructor, and the `apiKey`
+     * must be a secret key (`sk_*`).
+     */
+    delete(webhookId: string): Promise<void>;
+    /**
+     * Sends a test ping to a webhook endpoint to verify it is reachable.
+     *
+     * Requires `apiKey` and `merchantId` in the constructor, and the `apiKey`
+     * must be a secret key (`sk_*`).
+     */
+    ping(webhookId: string): Promise<void>;
+    private managementHttp;
+    private managementPath;
+    private verifyInternal;
+    private parseSignatureHeader;
+    private timingSafeCompare;
+}
+
+type InvoiceStatus = 'AWAITING_PAYMENT' | 'PENDING_CONFIRMATION' | 'PAID' | 'UNDERPAID' | 'OVERPAID' | 'EXPIRED' | 'CANCELLED';
+/**
+ * Customer attached to an invoice. Returned as a nested relation, not as
+ * flat `customerEmail` / `customerName` fields, because that mirrors the
+ * underlying data model: a customer is a separate entity that can be linked
+ * to multiple invoices.
+ */
+interface InvoiceCustomer {
+    id: string;
+    merchantId: string;
+    email: string;
+    name: string | null;
+    address: string | null;
+    phoneNumber: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Product an invoice was generated from, when applicable. Only set for
+ * invoices created via the public product checkout endpoint.
+ */
+interface InvoiceProduct {
+    id: string;
+    name: string;
+    description: string | null;
+    price: string;
+    currency: string;
+    image: string | null;
+}
+/**
+ * A single transition in an invoice's status history. Useful for rendering
+ * a timeline in a merchant dashboard.
+ */
+interface InvoiceTimelineEntry {
+    id: string;
+    invoiceId: string;
+    paymentStatus: InvoiceStatus;
+    time: string;
+}
+/**
+ * On-chain payment received against an invoice. An invoice can have zero
+ * payments (still awaiting), one (typical), or many (split payments,
+ * overpayments, etc.).
+ */
+interface InvoicePayment {
+    id: string;
+    invoiceId: string;
+    chainId: number | null;
+    /** Symbol of the chain's native coin (e.g. 'BTC', 'ETH'). */
+    network: string | null;
+    txHash: string | null;
+    fromAddress: string | null;
+    toAddress: string | null;
+    amount: string;
+    currency: string;
+    status: string;
+    receivedTxAt: string | null;
+    confirmedTxAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * An invoice as returned by the Billium merchant API.
+ *
+ * **Note on numeric fields:** `rawAmount` and `endAmount` are strings, not
+ * numbers, because 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`) for arithmetic.
+ *
+ * **Note on relations:** `customer`, `product`, `payments`, and
+ * `invoiceTimeline` are always present on responses from `create()`,
+ * `get()`, `list()`, and `cancel()`. They will be `null` / `[]` when
+ * empty, never `undefined`.
+ */
+interface Invoice {
+    id: string;
+    merchantId: string;
+    customerId: string | null;
+    productId: string | null;
+    name: string;
+    description: string | null;
+    redirectUrl: string | null;
+    /** Decimal serialized as string. The amount the merchant set on the invoice. */
+    rawAmount: string;
+    /** Decimal serialized as string. The amount the customer actually pays (rawAmount + fees, when applicable). */
+    endAmount: string;
+    currency: string;
+    status: InvoiceStatus;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    customer: InvoiceCustomer | null;
+    product: InvoiceProduct | null;
+    payments: InvoicePayment[];
+    invoiceTimeline: InvoiceTimelineEntry[];
+}
+interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    limit: number;
+}
+interface CreateInvoiceParams {
+    /** Invoice display name. */
+    name: string;
+    /** Amount in the specified currency. */
+    rawAmount: number;
+    /** Currency code (e.g. 'USD'). Defaults to 'USD'. */
+    currency?: string;
+    /** Customer email address. */
+    customerEmail?: string;
+    /** Customer full name. */
+    customerName?: string;
+    /** Customer billing address. */
+    customerAddress?: string;
+    /** Customer phone number. */
+    customerPhoneNumber?: string;
+    /** Optional description shown on the invoice. */
+    description?: string;
+    /** URL to redirect the customer after payment. */
+    redirectUrl?: string;
+}
+interface ListInvoicesParams {
+    /** Page number (1-based). Defaults to 1. */
+    page?: number;
+    /** Number of results per page (max 100). Defaults to 10. */
+    limit?: number;
+    /** Search by invoice name, description, or ID. */
+    search?: string;
+}
+/**
+ * Per-call options accepted by `invoices.create()`.
+ */
+interface CreateInvoiceOptions {
+    /**
+     * A unique key (≤ 255 chars, scoped to your merchant) that the server uses
+     * to deduplicate retried requests. If you call `create()` twice with the
+     * same key and same body within 24 hours, the second call returns the
+     * exact response from the first — no duplicate invoice is created.
+     *
+     * **You should set this on every `create()` call** in production. The SDK
+     * also requires it for transparent retries on POST: without this header,
+     * the SDK will not retry a failed `create()` call (even on `503`),
+     * because it cannot prove the server didn't already accept the first
+     * attempt.
+     *
+     * Generate a fresh key per logical operation (e.g. one per checkout
+     * session, one per cart submission). A UUID v4 is a good default:
+     *
+     * ```typescript
+     * import { randomUUID } from 'crypto';
+     *
+     * const invoice = await billium.invoices.create(
+     *   { name: 'Order #1234', rawAmount: 99.99 },
+     *   { idempotencyKey: randomUUID() },
+     * );
+     * ```
+     *
+     * If the server sees the same key with a *different* body, it returns
+     * `409 Conflict` — that's a programming bug, not a transient error.
+     */
+    idempotencyKey?: string;
+}
+declare class InvoicesClient {
+    private readonly http;
+    private readonly basePath;
+    constructor(http: HttpClient, merchantId: string);
+    /**
+     * Creates a new invoice for the merchant.
+     *
+     * Pass `options.idempotencyKey` for safe retries — see
+     * {@link CreateInvoiceOptions.idempotencyKey} for the full rationale.
+     */
+    create(params: CreateInvoiceParams, options?: CreateInvoiceOptions): Promise<Invoice>;
+    /**
+     * Retrieves a single invoice by ID.
+     */
+    get(invoiceId: string): Promise<Invoice>;
+    /**
+     * Lists invoices for the merchant with optional pagination and search.
+     */
+    list(params?: ListInvoicesParams): Promise<PaginatedResult<Invoice>>;
+    /**
+     * Cancels an invoice. Only invoices in non-terminal states can be cancelled.
+     * Terminal states: PAID, UNDERPAID, OVERPAID, EXPIRED, CANCELLED.
+     *
+     * **Requires a secret key (`sk_*`).** Public keys (`pk_*`) cannot mutate
+     * existing invoices.
+     */
+    cancel(invoiceId: string): Promise<Invoice>;
+}
+
+interface BilliumOptions {
+    /**
+     * Your Billium **secret** API key (`sk_*`). Required to use
+     * `billium.invoices` and `billium.webhooks` management methods.
+     *
+     * Generate a key in the Billium dashboard under Settings → Developer →
+     * API keys. The dashboard issues two key types — public (`pk_*`) and
+     * secret (`sk_*`) — but the Node SDK only consumes secret keys, since
+     * every method it exposes mutates state or accesses webhook management
+     * endpoints that public keys aren't authorized for. Public keys are
+     * reserved for browser-side SDKs (vanilla JS, React, etc.) which will
+     * ship as separate packages.
+     *
+     * Passing a `pk_*` key here is allowed, but methods like
+     * `webhooks.create()` and `invoices.cancel()` will throw a
+     * `BilliumError` immediately rather than round-tripping a 403.
+     */
+    apiKey?: string;
+    /**
+     * Your merchant ID (mer_...).
+     * Required to use `billium.invoices`.
+     */
+    merchantId?: string;
+    /**
+     * Your webhook secret (whsec_...).
+     * When set, you can call `billium.webhooks.verify(body, signature)` without
+     * passing the secret as a third argument on every call.
+     */
+    webhookSecret?: string;
+    /**
+     * Override the API base URL. Useful for self-hosted deployments or testing.
+     * @default 'https://api.billium.to'
+     */
+    baseUrl?: string;
+    /**
+     * Maximum number of retry attempts for failed requests.
+     * Total HTTP calls = `maxRetries + 1`. Set to 0 to disable retries.
+     *
+     * Retries fire on network errors, 5xx responses, and 429 (rate limited).
+     * `Retry-After` headers from the server are honored when present.
+     *
+     * `GET`, `PUT`, `PATCH`, and `DELETE` are always retried when
+     * `maxRetries > 0`. `POST` is retried only when an `Idempotency-Key`
+     * header is set on the request — otherwise retrying could create
+     * duplicate resources.
+     *
+     * @default 2
+     */
+    maxRetries?: number;
+    /**
+     * Initial backoff delay in milliseconds. Retries use exponential backoff
+     * with full jitter, capped at `maxDelayMs`.
+     * @default 500
+     */
+    baseDelayMs?: number;
+    /**
+     * Upper bound for the backoff delay between retries.
+     * @default 30000
+     */
+    maxDelayMs?: number;
+}
+declare class Billium {
+    readonly webhooks: WebhooksClient;
+    readonly invoices: InvoicesClient;
+    constructor(options?: BilliumOptions);
+}
+
+export { Billium, BilliumApiError, BilliumError, type BilliumOptions, BilliumWebhookSignatureError, BilliumWebhookTimestampError, type CreateInvoiceOptions, type CreateInvoiceParams, type CreateWebhookParams, type Invoice, type InvoiceCustomer, type InvoicePayment, type InvoiceProduct, type InvoiceStatus, type InvoiceTimelineEntry, type ListInvoicesParams, type PaginatedResult, SDK_VERSION, type UpdateWebhookParams, type VerifyOptions, type Webhook, type WebhookEvent, type WebhookEventType, type WebhookSecret };