@billkit-eu/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,911 @@
+/**
+ * Opt-in logging for the BillKit SDK.
+ *
+ * A library has no business deciding where its host application's logs
+ * go, so this SDK ships no logger, no transport, and no destination. It
+ * accepts one from you and writes to a no-op until you do:
+ *
+ * ```ts
+ * const client = new BillKit({ logger: console });
+ * ```
+ *
+ * `console` satisfies {@link BillKitLogger} structurally, so that line
+ * works with no adapter. So does a pino/winston/bunyan child logger:
+ * their `debug(msg, ctx)` / `warn(msg, ctx)` signatures line up. If yours
+ * takes its arguments the other way round, wrap it:
+ *
+ * ```ts
+ * const logger = {
+ *   debug: (m, c) => myLogger.debug(c, m),
+ *   warn: (m, c) => myLogger.warn(c, m),
+ * };
+ * ```
+ *
+ * ## What gets logged
+ *
+ * - **debug**: one call per HTTP attempt and one per response, with
+ *   `method`, `url`, `attempt`, `status`, `durationMs`, and `requestId`
+ *   (quote that id to BillKit support).
+ * - **warn**: one call per retry, naming the reason and the delay before
+ *   the next attempt. A retry is a real anomaly worth surfacing without
+ *   being an error.
+ *
+ * ## What is deliberately never logged
+ *
+ * - The `Authorization` header or the API key, in any form.
+ * - Request and response **bodies**. They carry customer PII (emails,
+ *   names, addresses) and billing detail; a payments SDK that quietly
+ *   copies those into its user's log sink has manufactured a compliance
+ *   problem on their behalf.
+ * - The **query string**. List filters routinely carry values like
+ *   `email=ada@example.com`, so only the path is logged.
+ * - The **final failure**. Every exhausted call throws a typed
+ *   `BillKitError` carrying the status, request id and retry-after;
+ *   logging it here as well would produce a duplicate the caller never
+ *   asked for and cannot suppress from their own sink.
+ */
+/** Structured context attached to a log line. Never contains secrets. */
+type LogContext = Record<string, unknown>;
+/**
+ * The minimum a logger must do for the SDK to use it. Deliberately two
+ * methods: the SDK has exactly two things to say, and a narrow interface
+ * is one almost every logger already satisfies without an adapter.
+ */
+interface BillKitLogger {
+    debug(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+}
+/**
+ * The default. Discards everything, so the SDK is silent until a logger
+ * is supplied, and costs nothing when it isn't.
+ */
+declare const NOOP_LOGGER: BillKitLogger;
+
+/**
+ * Retry policy for transient failures.
+ *
+ * Retries 5xx + network errors with jittered exponential backoff.
+ * 4xx (including 409 Idempotency-Key conflicts) are caller-fault and
+ * never retried. The SDK auto-generates an `Idempotency-Key` for every
+ * mutating call so retrying a 5xx never double-charges.
+ */
+interface RetryPolicy {
+    readonly maxAttempts: number;
+    readonly initialBackoffMs: number;
+    readonly backoffMultiplier: number;
+    readonly maxBackoffMs: number;
+    readonly maxRetryAfterMs?: number;
+    readonly jitter: number;
+}
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+
+/**
+ * Fetch-backed transport with retry + error mapping.
+ *
+ * Uses the runtime's native `fetch` (Node 20+, Bun, Deno, Cloudflare
+ * Workers, browsers). The transport is the only place that touches HTTP;
+ * everything else in the SDK speaks to a `Transport` interface so a
+ * caller can inject a mock or replay layer for testing.
+ */
+
+type QueryValue = string | number | boolean | null | undefined;
+interface RequestOptions {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    query?: {
+        readonly [key: string]: QueryValue;
+    };
+    body?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    extraHeaders?: Record<string, string>;
+}
+interface TransportConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    retryPolicy?: RetryPolicy;
+    fetch?: typeof fetch;
+    /**
+     * Where to send the SDK's request/retry lifecycle. Omitted (the
+     * default) means a no-op: the SDK stays silent and never picks a
+     * destination for you. `console` works as-is; see
+     * {@link BillKitLogger}. Secrets, bodies and query strings are never
+     * passed to it.
+     */
+    logger?: BillKitLogger;
+}
+declare class Transport {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly retryPolicy;
+    private readonly fetchFn;
+    private readonly logger;
+    constructor(config: TransportConfig);
+    request<T = unknown>(options: RequestOptions): Promise<T>;
+}
+
+/**
+ * Auto-pagination helper for list endpoints.
+ *
+ * The BillKit API returns Stripe-shape envelopes:
+ *
+ *     { "object": "list", "data": [...], "has_more": bool }
+ *
+ * Cursor pagination is forward-only via the last item's `id` as
+ * `starting_after`. `paginate` walks every page and yields each row.
+ * Callers consume it via `for await`:
+ *
+ *     for await (const customer of client.customers.iter()) {
+ *       ...
+ *     }
+ */
+
+interface ListResponseEnvelope<T = unknown> {
+    readonly data?: readonly T[];
+    readonly has_more?: boolean;
+}
+interface PaginateOptions {
+    /** Maps to the API's `limit` parameter. `undefined` lets the
+     *  server pick its default (10 today). */
+    pageSize?: number | undefined;
+    /** Extra filters forwarded on every page (e.g. `type` on events,
+     *  `action` on audit logs). Values are pruned of `undefined` so
+     *  callers can spread their full options object in. */
+    filters?: Readonly<Record<string, QueryValue>>;
+}
+type ListFn<T> = (params: {
+    limit?: number | undefined;
+    starting_after?: string | undefined;
+    [key: string]: QueryValue;
+}) => Promise<ListResponseEnvelope<T>>;
+/**
+ * Walk every page of `listFn` and yield each row.
+ *
+ * Three terminators, in priority order:
+ *   1. `has_more=false`: the server's authoritative signal (common case).
+ *   2. Empty `data` with `has_more=true`: shouldn't happen per the API
+ *      contract, but if a future server bug or proxy misbehaviour
+ *      produced it the iterator would loop forever. Belt-and-suspenders.
+ *   3. The last row has no `id`, so there is no cursor to advance with. The schema
+ *      doesn't allow it today, but same defensive reasoning.
+ */
+declare function paginate<T>(listFn: ListFn<T>, options?: PaginateOptions): AsyncIterableIterator<T>;
+
+/**
+ * Resource accessors mirroring the BillKit API surface.
+ *
+ * Each resource exposes the public verbs from `/v1/<resource>`. The
+ * return type defaults to `unknown`; the SDK doesn't ship runtime
+ * schemas (zod / valibot) because the API is Stripe-shape and tenants
+ * typically forward the JSON through their own data layer unchanged.
+ * Callers who want strong types parameterise each call with their
+ * own generic:
+ *
+ *     interface Customer { id: string; email: string }
+ *     const c = await client.customers.create<Customer>({ email: "..." });
+ *
+ * Every list-returning resource also exposes an `iter()` method that
+ * walks every page via the Stripe-shape `has_more` + `starting_after`
+ * cursor protocol. Iterate with `for await`:
+ *
+ *     for await (const customer of client.customers.iter()) { ... }
+ */
+
+/**
+ * Cursor-pagination knobs shared by every `list()` method.
+ *
+ * The index signature is what lets a resource-specific extension
+ * (e.g. `EventsListParams` adds `type?: string`) flow through the
+ * Transport's `query` shape without a cast. Excess fields are
+ * tolerated; `undefined` values are pruned before serialisation.
+ */
+interface BaseListParams {
+    limit?: number;
+    starting_after?: string;
+    ending_before?: string;
+    readonly [key: string]: QueryValue;
+}
+/**
+ * `prices.list` params. Adds the server-side `product_id` filter on top of
+ * the usual cursor knobs. `GET /v1/prices?product_id=...` narrows to one
+ * product's prices, which beats listing everything and filtering client-side
+ * once a tenant has more than a page of prices.
+ */
+interface PricesListParams extends BaseListParams {
+    product_id?: string;
+}
+/** Optional idempotency knob carried by every mutating call. */
+interface IdempotencyOptions {
+    /** Coalesces retries across process restarts. The SDK generates
+     *  a random `sdk-<uuid>` key for every mutating call if you don't
+     *  supply one. Pass your own when you want retries from a different
+     *  process to converge on the same server-side result. */
+    idempotencyKey?: string;
+}
+type ListParams = BaseListParams & {
+    readonly [key: string]: QueryValue;
+};
+interface CreateCustomerParams extends IdempotencyOptions {
+    email?: string;
+    name?: string;
+    country_code?: string;
+    metadata?: Record<string, string>;
+}
+interface UpdateCustomerParams extends IdempotencyOptions {
+    email?: string;
+    name?: string;
+    country_code?: string;
+    metadata?: Record<string, string>;
+}
+/**
+ * Body for `POST /v1/customers/{id}/vat_number`. The VAT number is
+ * sent through VIES server-side; the response carries
+ * `vat_number_validated` reflecting the outcome.
+ */
+interface SetCustomerVatNumberParams extends IdempotencyOptions {
+    vat_number: string;
+    country_code?: string;
+}
+/**
+ * Body for `POST /v1/customers/{id}/purge`. The server requires
+ * `confirmed: true` as a fat-finger guard against accidental purges
+ * fired from a DELETE that meant to soft-delete. The SDK defaults
+ * `confirmed` to `true` so the caller doesn't have to opt in twice.
+ */
+interface PurgeCustomerParams extends IdempotencyOptions {
+    confirmed?: boolean;
+}
+interface CreateProductParams extends IdempotencyOptions {
+    /** Customer-facing name, for example "Pro" or "Enterprise". */
+    name: string;
+    /** Optional long-form description shown in your own catalog UI. */
+    description?: string;
+    /** Ordered bullets suitable for pricing tables and checkout pages. */
+    marketing_features?: string[];
+    /** Small string metadata map echoed back on the Product object. */
+    metadata?: Record<string, string>;
+}
+interface UpdateProductParams extends IdempotencyOptions {
+    name?: string;
+    description?: string;
+    marketing_features?: string[];
+    metadata?: Record<string, string>;
+    /** Set false to stop selling a product without deleting history. */
+    active?: boolean;
+}
+interface CreatePriceParams extends IdempotencyOptions {
+    /** Existing Product id returned from `client.products.create`. */
+    product_id: string;
+    amount_cents: number;
+    currency: string;
+    interval: "month" | "year" | (string & {});
+    metadata?: Record<string, string>;
+    trial_days?: number;
+    trial_verification_cents?: number;
+    payment_methods?: Array<"creditcard" | "directdebit" | (string & {})>;
+    /**
+     * Per-Price refund-window override (`POST /v1/prices`). `undefined`
+     * inherits the default policy table (7d / 30d initial, 3d renewal);
+     * `0` disables refunds for that charge type; `N > 0` is an N-day
+     * window (capped server-side at 365). Useful for "Pro Bundle has a
+     * 14-day money back" or "Lifetime: no refunds" product decisions.
+     */
+    refund_window_initial_days?: number;
+    refund_window_renewal_days?: number;
+    /**
+     * Whether `amount_cents` is quoted gross (`"inclusive"`, VAT is
+     * backed out of it) or net (`"exclusive"`, VAT is added on top at
+     * charge time). `undefined` inherits `"unspecified"`, which defers to
+     * the tax rate configured for the buyer's country. Set it explicitly
+     * when the amount you advertise has to be the amount charged,
+     * regardless of what tax rates exist now or later.
+     */
+    tax_behavior?: "inclusive" | "exclusive" | "unspecified";
+}
+interface CreateCheckoutSessionParams extends IdempotencyOptions {
+    /**
+     * Existing Customer to attach the session to. Mutually exclusive
+     * with `customer_email`; exactly one of the two must be set.
+     */
+    customer_id?: string;
+    /**
+     * Stripe-compatible shortcut: BillKit creates a fresh Customer row
+     * in the same transaction as the checkout. Never dedupes by email
+     * (emails are not unique identifiers in BillKit). Mutually exclusive
+     * with `customer_id`.
+     */
+    customer_email?: string;
+    /**
+     * Optional friendly name carried onto the auto-created Customer when
+     * using `customer_email`. Rejected with `422` if supplied alongside
+     * `customer_id` (rename existing customers via `customers.update`).
+     */
+    customer_name?: string;
+    price_id: string;
+    success_url: string;
+    cancel_url: string;
+    /**
+     * Pin the Mollie payment method. `undefined` lets Mollie pick from
+     * the customer's available methods; when set, must be in the price's
+     * `payment_methods` allowlist.
+     */
+    method?: "creditcard" | "directdebit" | (string & {});
+    /** Optional coupon code applied at checkout; atomically claimed. */
+    coupon_code?: string;
+    /**
+     * Per-session trial override. Replaces the price's `trial_days`
+     * for this checkout. Capped server-side at `2 × max(price.trial_days, 14)`.
+     * `0` disables a trial that the price would otherwise grant.
+     */
+    trial_days_override?: number;
+}
+interface CreateRefundParams extends IdempotencyOptions {
+    payment_id?: string;
+    subscription_id?: string;
+    /**
+     * Refund a mandate-less one-shot payment (`oneShotPayments.create`).
+     * Mutually exclusive with `payment_id` / `subscription_id`; pass
+     * exactly one target or the server rejects with `400`.
+     */
+    one_shot_payment_id?: string;
+    /**
+     * Partial-refund amount in minor units. Omit to refund the whole remaining
+     * balance (the full charge when nothing has been refunded yet). A payment
+     * may carry several partial refunds up to the charged amount; the one that
+     * brings the cumulative total to the full charge cancels the bound
+     * subscription (or flips a one-shot to `refunded`).
+     */
+    amount_cents?: number;
+    reason?: string;
+}
+/**
+ * Body for `POST /v1/checkout/one_shot`, a single mandate-less charge
+ * (the Stripe PaymentIntent shape, mapped onto Mollie). No subscription,
+ * no mandate, no renewals: it settles once against your `success_url`.
+ */
+interface CreateOneShotPaymentParams extends IdempotencyOptions {
+    /** Existing Customer to charge. */
+    customer_id: string;
+    amount_cents: number;
+    /** ISO-4217, e.g. `"EUR"`. Validated against the tenant allowlist. */
+    currency: string;
+    /**
+     * Concrete Mollie method to charge with. Required, because a one-shot commits
+     * up front). Validated against the tenant's capability allowlist for
+     * `currency`; one-off methods like `bancontact`/`eps` are allowed here
+     * even though they can't back a subscription.
+     *
+     * `giropay` was removed: the scheme shut down at the end of 2024 and the
+     * server now 422s it. The `(string & {})` tail keeps this open on
+     * purpose: unlike the console's read-side `PaymentMethodKind`, this is a
+     * *request* type the server validates, so an SDK that lags a newly-added
+     * method should not be the thing that blocks the call.
+     */
+    method: "creditcard" | "directdebit" | "ideal" | "bancontact" | "eps" | (string & {});
+    /** Where Mollie returns the payer after the hosted checkout. */
+    success_url: string;
+    /** Optional page for an abandoned/cancelled payment. */
+    cancel_url?: string;
+    /** Shown on the Mollie page + the payer's bank statement. */
+    description?: string;
+    /**
+     * Per-payment refund-window override in days. `undefined` inherits the
+     * one-shot default (30 days); `0` disables refunds for this payment;
+     * `N > 0` is an N-day window (capped server-side at 365).
+     */
+    refund_window_days?: number;
+    /**
+     * Whether `amount_cents` is quoted gross or net.
+     *
+     * `"inclusive"` (the default when omitted) charges `amount_cents` and
+     * backs the VAT out of it. `"exclusive"` reads it as a net figure and
+     * charges the payer `amount_cents + tax`, so the response's
+     * `amount_cents` comes back *larger* than the one you sent, because it
+     * is always what was actually charged. Reconcile against `net_cents` /
+     * `tax_cents` on the response.
+     *
+     * Omit to inherit the country default from your configured tax rate.
+     */
+    tax_behavior?: "inclusive" | "exclusive";
+    metadata?: Record<string, string>;
+}
+interface CreateWebhookEndpointParams extends IdempotencyOptions {
+    url: string;
+    enabled_events?: string[];
+    description?: string;
+}
+interface UpdateWebhookEndpointParams extends IdempotencyOptions {
+    url?: string;
+    enabled_events?: string[];
+    description?: string;
+    status?: string;
+}
+interface EventsListParams extends BaseListParams {
+    /** Server-side filter, e.g. `customer.created`. */
+    type?: string;
+}
+interface SetPortalBrandingParams extends IdempotencyOptions {
+    business_name?: string;
+    support_email?: string;
+    logo_url?: string;
+    theme?: Record<string, unknown>;
+    capabilities?: Record<string, unknown>;
+}
+interface RotateProviderCredentialParams extends IdempotencyOptions {
+    /** New raw provider API key. Encrypted server-side; never logged. */
+    api_key: string;
+    /** Defaults to the calling key's mode. */
+    mode?: "test" | "live" | (string & {});
+    /** Currently only `"mollie"`. */
+    provider?: "mollie" | (string & {});
+}
+interface CreateCouponParams extends IdempotencyOptions {
+    code: string;
+    discount_type: "percentage" | "amount" | (string & {});
+    discount_value: number;
+    duration: "once" | "repeating" | "forever" | (string & {});
+    duration_in_months?: number;
+    max_redemptions?: number;
+    redeem_by?: number;
+    applies_to_price_ids?: string[];
+    min_amount_cents?: number;
+}
+interface UpdateCouponParams extends IdempotencyOptions {
+    active?: boolean;
+    max_redemptions?: number;
+    redeem_by?: number;
+    applies_to_price_ids?: string[];
+    min_amount_cents?: number;
+}
+interface ValidateCouponParams {
+    code: string;
+    /**
+     * Scope the dry-run to one price. Optional: omit to validate the code
+     * on its own (existence, active, not exhausted, not expired). Supply it
+     * to also check the coupon's `applies_to_price_ids` restriction.
+     */
+    price_id?: string;
+    /**
+     * Base amount the discount is computed against, in minor units.
+     * Optional: omit to skip the discount math and the `min_amount_cents`
+     * check. `POST /v1/coupons/validate` treats both fields as nullable.
+     */
+    amount_cents?: number;
+}
+interface CreateTaxRateParams extends IdempotencyOptions {
+    country_code: string;
+    rate_basis_points: number;
+    display_name?: string;
+    inclusive?: boolean;
+}
+interface UpdateTaxRateParams extends IdempotencyOptions {
+    rate_basis_points?: number;
+    display_name?: string;
+    inclusive?: boolean;
+    active?: boolean;
+}
+interface AuditLogsListParams extends BaseListParams {
+    action?: string;
+    resource_type?: string;
+    actor_id?: string;
+}
+interface CreateBillingPortalSessionParams extends IdempotencyOptions {
+    subscription_id: string;
+    return_url: string;
+}
+/**
+ * Shared transport wrapper. Resources subclass this so each method
+ * reads as a single line, "verb to path with params", instead of
+ * the four-line `this.t.request({ ... })` boilerplate the previous
+ * draft repeated everywhere.
+ */
+declare abstract class BaseResource {
+    protected readonly t: Transport;
+    constructor(t: Transport);
+    protected get<T>(path: string, query?: BaseListParams & Record<string, QueryValue>): Promise<T>;
+    protected post<T, P extends IdempotencyOptions>(path: string, params: P): Promise<T>;
+    /** POST with no body, used by lifecycle verbs (cancel, resume, revoke ...). */
+    protected postEmpty<T>(path: string, params?: IdempotencyOptions): Promise<T>;
+    /** POST with a fixed body and no idempotency stripping (used by
+     *  endpoints whose body is fully specified by the caller's args
+     *  and not optional, e.g. `preview_update`). */
+    protected postFixed<T>(path: string, body: Record<string, unknown>, params?: IdempotencyOptions): Promise<T>;
+    protected del<T>(path: string, params?: IdempotencyOptions): Promise<T>;
+}
+declare class Customers extends BaseResource {
+    /** Create a tenant-scoped buyer record. */
+    create<T = unknown>(params?: CreateCustomerParams): Promise<T>;
+    retrieve<T = unknown>(id: string): Promise<T>;
+    update<T = unknown>(id: string, params?: UpdateCustomerParams): Promise<T>;
+    delete<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    /** Walk every page of `list()` and yield each customer. */
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+    /**
+     * Attach or replace the customer's VAT number; triggers server-side
+     * VIES validation. The response carries `vat_number_validated`
+     * reflecting whether VIES confirmed the number.
+     */
+    setVatNumber<T = unknown>(id: string, params: SetCustomerVatNumberParams): Promise<T>;
+    /**
+     * Hard-purge a customer's PII for GDPR erasure. Distinct from
+     * `delete()` (soft delete): purge nulls email/name/country/VAT/
+     * metadata, sets `purged_at`, and is irreversible.
+     *
+     * The server requires `confirmed: true` as a fat-finger guard; the
+     * SDK defaults it to `true` so callers don't have to opt in twice.
+     */
+    purge<T = unknown>(id: string, params?: PurgeCustomerParams): Promise<T>;
+}
+declare class Products extends BaseResource {
+    /** Create a catalog Product, then attach one or more Prices to it. */
+    create<T = unknown>(params: CreateProductParams): Promise<T>;
+    retrieve<T = unknown>(id: string): Promise<T>;
+    /** Patch mutable Product fields. */
+    update<T = unknown>(id: string, params: UpdateProductParams): Promise<T>;
+    /** Archive a Product. */
+    delete<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+}
+declare class Prices extends BaseResource {
+    /** Create immutable billing terms for an existing Product. */
+    create<T = unknown>(params: CreatePriceParams): Promise<T>;
+    retrieve<T = unknown>(id: string): Promise<T>;
+    list<T = unknown>(params?: PricesListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+        product_id?: string;
+    }): AsyncIterableIterator<T>;
+}
+declare class CheckoutSessions extends BaseResource {
+    create<T = unknown>(params: CreateCheckoutSessionParams): Promise<T>;
+    retrieve<T = unknown>(id: string): Promise<T>;
+}
+/**
+ * Mandate-less one-shot payments (`/v1/checkout/one_shot`).
+ *
+ * A one-shot is the Stripe PaymentIntent shape mapped onto Mollie: a
+ * single `sequenceType=oneoff` charge that provisions nothing: no
+ * subscription, no mandate, no renewals. Drive terminal state via the
+ * `one_shot_payment.succeeded` / `.failed` webhook events; refund one
+ * with `client.refunds.create({ one_shot_payment_id })`.
+ */
+declare class OneShotPayments extends BaseResource {
+    /** Create a one-off charge; returns the object with a `redirect_url`. */
+    create<T = unknown>(params: CreateOneShotPaymentParams): Promise<T>;
+    retrieve<T = unknown>(id: string): Promise<T>;
+}
+declare class Subscriptions extends BaseResource {
+    retrieve<T = unknown>(id: string): Promise<T>;
+    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+    cancel<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    pause<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    resume<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    /**
+     * Reactivate a canceled-but-still-in-period subscription.
+     *
+     * Distinct from `resume()` (paused → active): `reactivate()` flips
+     * `canceled` back to `active` for the remainder of the current
+     * period, so the customer keeps service without a new checkout.
+     * Returns `409` if the period has already elapsed.
+     */
+    reactivate<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    previewUpdate<T = unknown>(id: string, params: {
+        target_price_id: string;
+    }): Promise<T>;
+    update<T = unknown>(id: string, params: {
+        target_price_id: string;
+    } & IdempotencyOptions): Promise<T>;
+    reauthorizePaymentMethod<T = unknown>(id: string, params: {
+        return_url: string;
+    } & IdempotencyOptions): Promise<T>;
+}
+declare class Refunds extends BaseResource {
+    create<T = unknown>(params: CreateRefundParams): Promise<T>;
+    retrieve<T = unknown>(id: string): Promise<T>;
+    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+}
+/**
+ * Chargebacks / disputes (`/v1/disputes`).
+ *
+ * Read-only. Disputes are provider-originated (opened by the cardholder's
+ * bank) and surfaced via the `dispute.created` / `dispute.closed` webhook
+ * events. There is no create/update. A dispute's `status` is `open` or `won`
+ * (chargeback reversed); Mollie exposes no "lost" signal, so an upheld
+ * chargeback stays `open` (treat any non-`won` dispute as unresolved).
+ */
+declare class Disputes extends BaseResource {
+    retrieve<T = unknown>(id: string): Promise<T>;
+    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+}
+declare class WebhookEndpoints extends BaseResource {
+    create<T = unknown>(params: CreateWebhookEndpointParams): Promise<T>;
+    retrieve<T = unknown>(id: string): Promise<T>;
+    update<T = unknown>(id: string, params: UpdateWebhookEndpointParams): Promise<T>;
+    delete<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    /** Rotate the signing secret. The new `whsec_...` is returned once. */
+    rotateSecret<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+    /**
+     * List per-attempt delivery records for one endpoint.
+     *
+     * Useful when a tenant's receiver is failing. Surfaces the status
+     * code, response body excerpt, error, and next-attempt timestamp
+     * for each event × endpoint pair.
+     */
+    listDeliveries<T = unknown>(endpointId: string, params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    /** Walk every page of `listDeliveries()` for one endpoint. */
+    iterDeliveries<T = unknown>(endpointId: string, options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+    /** Fetch one delivery row for inspection before deciding to redeliver. */
+    getDelivery<T = unknown>(endpointId: string, deliveryId: string): Promise<T>;
+    /**
+     * Re-enqueue a delivery row for the dispatcher.
+     *
+     * Idempotent: a row already in `delivered` returns unchanged. A
+     * `pending` / `failed` row flips to `pending` with
+     * `next_attempt_at = now()`; `attempt_count` is preserved.
+     */
+    redeliver<T = unknown>(endpointId: string, deliveryId: string, params?: IdempotencyOptions): Promise<T>;
+}
+declare class Events extends BaseResource {
+    retrieve<T = unknown>(id: string): Promise<T>;
+    list<T = unknown>(params?: EventsListParams): Promise<ListResponseEnvelope<T>>;
+    /** Walk every page of `list()`. Pass `type` to filter at the server. */
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+        type?: string;
+    }): AsyncIterableIterator<T>;
+}
+/**
+ * Read + mutate tenant-level configuration.
+ *
+ * Exposes the Mollie capability cache, the portal-branding row, and
+ * the encrypted Mollie API key. None of these are per-resource;
+ * they're tenant-wide knobs.
+ */
+declare class Tenant extends BaseResource {
+    /** Cached Mollie profile shape (enabled methods, country, currency). */
+    capabilities<T = unknown>(): Promise<T>;
+    /** Current portal branding row (business name, theme, capability flags). */
+    portalBranding<T = unknown>(): Promise<T>;
+    /**
+     * Partial-update the portal branding row.
+     *
+     * Only fields you set are sent. Pass `undefined` to leave a field
+     * untouched; sending an empty string explicitly clears it.
+     */
+    setPortalBranding<T = unknown>(params?: SetPortalBrandingParams): Promise<T>;
+    /**
+     * Rotate the encrypted provider credential for this tenant.
+     *
+     * The new `api_key` is encrypted server-side; nothing is logged.
+     * `mode` defaults to the calling key's mode; prefix-mismatch
+     * (`test_...` under live, `live_...` under test) is rejected at the
+     * API boundary.
+     */
+    rotateProviderCredential<T = unknown>(params: RotateProviderCredentialParams): Promise<T>;
+}
+declare class Coupons extends BaseResource {
+    create<T = unknown>(params: CreateCouponParams): Promise<T>;
+    retrieve<T = unknown>(id: string): Promise<T>;
+    update<T = unknown>(id: string, params: UpdateCouponParams): Promise<T>;
+    delete<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    /**
+     * Server-side dry-run of a coupon redemption.
+     *
+     * Returns the discount math without atomically claiming the coupon,
+     * which is useful for "preview before checkout" UX.
+     */
+    validate<T = unknown>(params: ValidateCouponParams): Promise<T>;
+    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+}
+declare class TaxRates extends BaseResource {
+    create<T = unknown>(params: CreateTaxRateParams): Promise<T>;
+    retrieve<T = unknown>(id: string): Promise<T>;
+    update<T = unknown>(id: string, params: UpdateTaxRateParams): Promise<T>;
+    delete<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+}
+/**
+ * Read-only access to generated invoices.
+ *
+ * Invoices are produced by the billing pipeline; tenants don't create
+ * them directly. PDF retrieval returns a 302 redirect to the storage
+ * adapter's signed URL. Follow it transparently with the runtime's
+ * fetch settings.
+ */
+declare class Invoices extends BaseResource {
+    retrieve<T = unknown>(id: string): Promise<T>;
+    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+}
+/**
+ * Read-only access to the per-tenant audit log.
+ *
+ * Supports server-side filters: `action`, `resource_type`, `actor_id`.
+ * The filters are forwarded through to `iter()` so an audit walk can
+ * scope to a single actor or action without client-side filtering.
+ */
+declare class AuditLogs extends BaseResource {
+    retrieve<T = unknown>(id: string): Promise<T>;
+    list<T = unknown>(params?: AuditLogsListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+        action?: string;
+        resource_type?: string;
+        actor_id?: string;
+    }): AsyncIterableIterator<T>;
+}
+/**
+ * Read-only access to the payment ledger.
+ *
+ * Payments are written by the billing pipeline (checkout, renewal,
+ * reauthorize). Inspect attempts and their Mollie-side metadata here;
+ * refunds and disputes are separate flows.
+ */
+declare class Payments extends BaseResource {
+    retrieve<T = unknown>(id: string): Promise<T>;
+    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+}
+/**
+ * Mint and revoke customer-facing billing-portal sessions.
+ *
+ * Each session token is scoped to a single subscription with a
+ * sliding 30-minute idle window and a 2-hour hard cap. The raw token
+ * is returned **once** on mint; the response also includes the URL
+ * the tenant embeds in their app.
+ */
+declare class BillingPortalSessions extends BaseResource {
+    create<T = unknown>(params: CreateBillingPortalSessionParams): Promise<T>;
+    /** Kill an in-the-wild portal session. Idempotent. */
+    revoke<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+}
+
+/**
+ * Top-level BillKit client.
+ *
+ * Wraps a single Transport and exposes every resource family as a
+ * field. The Transport is configured once at construction; every
+ * resource reuses it, so a runtime-injected `fetch` impl (Cloudflare
+ * Workers, MSW for tests, a debug proxy) flows through automatically.
+ */
+
+interface BillKitOptions extends Omit<TransportConfig, "apiKey"> {
+    /** Falls back to `process.env.BILLKIT_API_KEY` when omitted. */
+    apiKey?: string;
+}
+declare class BillKit {
+    readonly customers: Customers;
+    readonly products: Products;
+    readonly prices: Prices;
+    readonly checkoutSessions: CheckoutSessions;
+    readonly oneShotPayments: OneShotPayments;
+    readonly subscriptions: Subscriptions;
+    readonly refunds: Refunds;
+    readonly disputes: Disputes;
+    readonly webhookEndpoints: WebhookEndpoints;
+    readonly events: Events;
+    readonly tenant: Tenant;
+    readonly coupons: Coupons;
+    readonly taxRates: TaxRates;
+    readonly invoices: Invoices;
+    readonly auditLogs: AuditLogs;
+    readonly payments: Payments;
+    readonly billingPortalSessions: BillingPortalSessions;
+    constructor(options?: BillKitOptions);
+}
+
+interface BillKitErrorOptions {
+    type?: string | undefined;
+    code?: string | undefined;
+    param?: string | undefined;
+    statusCode?: number | undefined;
+    requestId?: string | undefined;
+    rawBody?: unknown;
+}
+declare class BillKitError extends Error {
+    name: string;
+    readonly type: string | undefined;
+    readonly code: string | undefined;
+    readonly param: string | undefined;
+    readonly statusCode: number | undefined;
+    readonly requestId: string | undefined;
+    readonly rawBody: unknown;
+    constructor(message: string, options?: BillKitErrorOptions);
+}
+declare class APIConnectionError extends BillKitError {
+    name: string;
+}
+declare class APIError extends BillKitError {
+    name: string;
+}
+declare class ServerError extends APIError {
+    name: string;
+}
+declare class AuthenticationError extends BillKitError {
+    name: string;
+}
+declare class PermissionError extends BillKitError {
+    name: string;
+}
+declare class ResourceMissingError extends BillKitError {
+    name: string;
+}
+declare class InvalidRequestError extends BillKitError {
+    name: string;
+}
+declare class ConflictError extends BillKitError {
+    name: string;
+}
+declare class RateLimitError extends BillKitError {
+    name: string;
+    readonly retryAfter: number | undefined;
+    constructor(message: string, options?: BillKitErrorOptions & {
+        retryAfter?: number | undefined;
+    });
+}
+
+declare const VERSION = "0.1.0";
+
+/**
+ * Verify `BillKit-Signature: t=<unix>,v1=<hex>` headers.
+ *
+ * Works in Node 20+, Bun, Deno, Cloudflare Workers and the browser:
+ * we use the Web Crypto API (`globalThis.crypto.subtle`) which is
+ * available in all modern runtimes. The verifier:
+ *
+ * 1. Parses the header (rejects malformed shapes). A header may carry
+ *    more than one `v1=` value, because the server emits both the old and new
+ *    signature during a signing-secret rotation, and verification passes
+ *    if any of them matches.
+ * 2. Confirms the timestamp is within `toleranceSeconds` of now
+ *    (replay protection).
+ * 3. Computes the expected HMAC and compares against each candidate in
+ *    constant time.
+ */
+declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+declare class WebhookVerificationError extends Error {
+    name: string;
+    constructor(message: string);
+}
+interface VerifyWebhookOptions {
+    payload: string | Uint8Array;
+    signatureHeader: string | null | undefined;
+    secret: string;
+    toleranceSeconds?: number;
+    nowMs?: number;
+}
+declare function verifyWebhookSignature<T = unknown>(options: VerifyWebhookOptions): Promise<T>;
+
+export { APIConnectionError, APIError, type AuditLogsListParams, AuthenticationError, type BaseListParams, BillKit, BillKitError, type BillKitLogger, type BillKitOptions, ConflictError, type CreateBillingPortalSessionParams, type CreateCheckoutSessionParams, type CreateCouponParams, type CreateCustomerParams, type CreateOneShotPaymentParams, type CreatePriceParams, type CreateProductParams, type CreateRefundParams, type CreateTaxRateParams, type CreateWebhookEndpointParams, DEFAULT_RETRY_POLICY, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, type EventsListParams, type IdempotencyOptions, InvalidRequestError, type ListParams, type ListResponseEnvelope, type LogContext, NOOP_LOGGER, type PaginateOptions, PermissionError, type PricesListParams, RateLimitError, ResourceMissingError, type RetryPolicy, type RotateProviderCredentialParams, ServerError, type SetPortalBrandingParams, type UpdateCouponParams, type UpdateCustomerParams, type UpdateProductParams, type UpdateTaxRateParams, type UpdateWebhookEndpointParams, VERSION, type ValidateCouponParams, type VerifyWebhookOptions, WebhookVerificationError, paginate, verifyWebhookSignature };