@billkit-eu/sdk 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -95,9 +95,15 @@ type QueryValue = string | number | boolean | null | undefined;
 interface RequestOptions {
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
     path: string;
-    query?: {
-        readonly [key: string]: QueryValue;
-    };
+    /**
+     * Query parameters, as a plain object. Typed this way rather than with
+     * an index signature because TypeScript only gives an implicit index
+     * signature to type aliases, so a closed `*ListParams` interface would
+     * need a cast at every call site. {@link buildUrl} does the pruning:
+     * `undefined` and `null` are dropped, an array is joined with commas
+     * (the API's `expand=a,b` shape), everything else is stringified.
+     */
+    query?: object;
     body?: Record<string, unknown> | undefined;
     idempotencyKey?: string | undefined;
     extraHeaders?: Record<string, string>;
@@ -217,15 +223,23 @@ declare function paginate<T>(listFn: ListFn<T>, options?: PaginateOptions): Asyn
 /**
  * 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.
+ * Closed on purpose: there is no index signature, so a misspelled filter
+ * (`provisonal`) is a compile error instead of a query parameter the
+ * server ignores. The Transport takes `query` as a plain `object` and
+ * prunes/stringifies it, which is what lets these interfaces through
+ * without a cast.
  */
 interface BaseListParams {
     limit?: number;
     starting_after?: string;
-    readonly [key: string]: QueryValue;
+}
+/**
+ * `?expand=` on a single-object GET. The relations a route accepts differ
+ * per resource and are listed on each `retrieve()`; an unknown one is a
+ * `400` naming the ones that work.
+ */
+interface ExpandOptions {
+    expand?: string[];
 }
 /**
  * `prices.list` params. Adds the server-side `product_id` filter on top of
@@ -236,6 +250,40 @@ interface BaseListParams {
 interface PricesListParams extends BaseListParams {
     product_id?: string;
 }
+/**
+ * `payments.list` params. `customer_id` narrows to one customer's
+ * charges. Mandate verifications are never listed, so every row is a
+ * real purchase attempt; check `status` before treating one as revenue.
+ */
+interface PaymentsListParams extends BaseListParams {
+    customer_id?: string;
+    /** Expandable here: `customer`, `subscription`. */
+    expand?: string[];
+}
+/**
+ * `invoices.list` params. The three id filters each narrow to one row's
+ * worth of invoices: `payment_id` answers "which invoice did this charge
+ * produce".
+ */
+interface InvoicesListParams extends BaseListParams {
+    customer_id?: string;
+    subscription_id?: string;
+    payment_id?: string;
+    /** One of `draft`, `open`, `paid`, `void`, `uncollectible`. */
+    status?: string;
+    /** Expandable here: `customer`. */
+    expand?: string[];
+}
+/**
+ * `disputes.list` params. `status` takes a comma-separated list of `open`
+ * / `won`. There is no `lost`, because the provider gives no signal for
+ * one. `payment_id` matches subscription payments only, not one-off
+ * charges.
+ */
+interface DisputesListParams extends BaseListParams {
+    status?: string;
+    payment_id?: string;
+}
 /**
  * `subscriptions.list` params. Both filters take a comma-separated
  * list (`"active,past_due"`); an unrecognised value is rejected with
@@ -255,6 +303,8 @@ interface SubscriptionsListParams extends BaseListParams {
     status?: string;
     /** `auto_renew` | `paused` | `canceling` | `stopped`, CSV. */
     renewal_state?: string;
+    /** Expandable here: `customer`, `price`, `refund_eligibility`. */
+    expand?: string[];
 }
 /** Optional idempotency knob carried by every mutating call. */
 interface IdempotencyOptions {
@@ -264,9 +314,12 @@ interface IdempotencyOptions {
      *  process to converge on the same server-side result. */
     idempotencyKey?: string;
 }
-type ListParams = BaseListParams & {
-    readonly [key: string]: QueryValue;
-};
+/**
+ * @deprecated Alias of {@link BaseListParams}, kept for callers that
+ * imported the older name. Reach for the resource-specific `*ListParams`
+ * (e.g. `EventsListParams`) instead.
+ */
+type ListParams = BaseListParams;
 interface CreateCustomerParams extends IdempotencyOptions {
     email?: string;
     name?: string;
@@ -286,14 +339,25 @@ interface CustomerListParams extends BaseListParams {
      * omitted for both.
      */
     provisional?: boolean;
+    /** Expandable here: `stats`. Sent as `expand=a,b`. */
+    expand?: string[];
+}
+/** Query parameters accepted by `GET /v1/products`. */
+interface ProductsListParams extends BaseListParams {
+    /** Expandable here: `prices`, `stats`. */
+    expand?: 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.
+ *
+ * `vat_number: null` **clears** the registration, and is sent as an
+ * explicit null rather than pruned: only `undefined` is dropped.
  */
 interface SetCustomerVatNumberParams extends IdempotencyOptions {
-    vat_number: string;
+    vat_number: string | null;
+    /** VIES needs a country; send it when the customer has none yet. */
     country_code?: string;
 }
 /**
@@ -336,13 +400,34 @@ interface UpdateProductParams extends IdempotencyOptions {
     allow_promotion_codes?: boolean;
 }
 /**
- * Body for `POST /v1/prices/{id}`. `active` is the only field a price
- * accepts, and it moves both ways: `false` withdraws the price from sale,
- * `true` puts it back. The amount, currency and interval are fixed at
- * creation, so neither direction changes what anyone was charged.
+ * Body for `POST /v1/prices/{id}`. Every field is optional; omitted ones
+ * are left alone.
+ *
+ * The dividing line is what a field decides. `amount_cents`, `currency`,
+ * `interval` and `usage_type` decide **what a past charge was**, so they
+ * are fixed at creation and absent here, because subscriptions renew
+ * against a price by id and editing one would re-price live customers.
+ * Everything
+ * below decides **what happens next**, which is why it is editable:
+ * setting `refund_on_cancel` covers the customers already on the price.
+ *
+ * `tax_behavior` is the exception and moves one way. It can be set while
+ * the price is still `"unspecified"` and never changed again, because
+ * flipping it would restate whether tax was inside or on top of an amount
+ * somebody has already paid.
  */
 interface UpdatePriceParams extends IdempotencyOptions {
-    active: boolean;
+    /** `false` withdraws the price from sale, `true` puts it back. */
+    active?: boolean;
+    metadata?: Record<string, string>;
+    /** Settable once, while the price is still `"unspecified"`. */
+    tax_behavior?: "inclusive" | "exclusive";
+    /** Read when a checkout opens. At least one entry. */
+    payment_methods?: Array<"creditcard" | "directdebit" | "ideal" | "eps" | "applepay" | "paypal" | (string & {})>;
+    refund_on_cancel?: "none" | "full" | "prorated";
+    /** `0` disables refunds for that charge type; `N > 0` is an N-day window. */
+    refund_window_initial_days?: number;
+    refund_window_renewal_days?: number;
 }
 /**
  * One band of a tiered price.
@@ -420,7 +505,7 @@ interface CreatePriceParams extends IdempotencyOptions {
     metadata?: Record<string, string>;
     trial_days?: number;
     trial_verification_cents?: number;
-    payment_methods?: Array<"creditcard" | "directdebit" | "ideal" | "applepay" | (string & {})>;
+    payment_methods?: Array<"creditcard" | "directdebit" | "ideal" | "eps" | "applepay" | "paypal" | (string & {})>;
     /**
      * What a cancellation refunds without being asked. `"none"` (the default)
      * nothing; `"full"` the whole last charge; `"prorated"` the unused part
@@ -527,12 +612,26 @@ interface CreateCheckoutSessionParams extends IdempotencyOptions {
     price_id: string;
     success_url: string;
     cancel_url: string;
+    /**
+     * The buyer's ISO-3166-1 alpha-2 country, when you already know it.
+     * Stored on the customer if they do not have one yet, which is what
+     * lets VAT apply to the very first charge. On the hosted flow the buyer
+     * only reaches a country-collecting page after the charge exists.
+     * Never overwrites a country the customer already has.
+     */
+    country?: 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.
+     *
+     * Subscription-starting only, so this is deliberately NARROWER than the
+     * one-shot union: `bancontact` and `banktransfer` are absent because
+     * neither can mint the mandate a renewal needs. Mollie refuses the
+     * latter outright with "The payment method does not support sequence
+     * type".
      */
-    method?: "creditcard" | "directdebit" | "ideal" | "applepay" | (string & {});
+    method?: "creditcard" | "directdebit" | "ideal" | "eps" | "applepay" | "paypal" | (string & {});
     /** Optional coupon code applied at checkout; atomically claimed. */
     coupon_code?: string;
     /**
@@ -588,8 +687,12 @@ interface CreateOneShotPaymentParams extends IdempotencyOptions {
     /**
      * 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.
+     * `currency`; one-off methods like `bancontact` and `banktransfer` are
+     * allowed here even though they can't back a subscription.
+     *
+     * `banktransfer` settles in DAYS, not seconds: the payer is handed bank
+     * details and Mollie holds the payment `open` for about a fortnight. Expect
+     * `one_shot_payment.paid` long after the call returns.
      *
      * `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
@@ -597,7 +700,7 @@ interface CreateOneShotPaymentParams extends IdempotencyOptions {
      * *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" | "applepay" | (string & {});
+    method: "creditcard" | "directdebit" | "ideal" | "bancontact" | "eps" | "applepay" | "paypal" | "banktransfer" | (string & {});
     /** Where Mollie returns the payer after the hosted checkout. */
     success_url: string;
     /** Optional page for an abandoned/cancelled payment. */
@@ -639,6 +742,8 @@ interface UpdateWebhookEndpointParams extends IdempotencyOptions {
 interface EventsListParams extends BaseListParams {
     /** Server-side filter, e.g. `customer.created`. */
     type?: string;
+    /** Expandable here: `customer`. `events.retrieve` accepts none. */
+    expand?: string[];
 }
 interface SetPortalBrandingParams extends IdempotencyOptions {
     business_name?: string;
@@ -657,7 +762,12 @@ interface RotateProviderCredentialParams extends IdempotencyOptions {
 }
 interface CreateCouponParams extends IdempotencyOptions {
     code: string;
-    discount_type: "percentage" | "amount" | (string & {});
+    /**
+     * `"percent"` reads `discount_value` as whole percent; `"fixed_cents"`
+     * reads it as minor units off the charge. Those are the only two the
+     * API accepts (`schemas/coupon.py`); anything else is a `422`.
+     */
+    discount_type: "percent" | "fixed_cents" | (string & {});
     discount_value: number;
     duration: "once" | "repeating" | "forever" | (string & {});
     duration_in_months?: number;
@@ -700,9 +810,18 @@ interface UpdateTaxRateParams extends IdempotencyOptions {
     inclusive?: boolean;
     active?: boolean;
 }
+/**
+ * `auditLogs.list` params. All four filters match exactly and combine.
+ *
+ * `resource_type` narrows to a kind (`"customer"`, `"price"`);
+ * `resource_id` narrows to one row, which is the "everything that ever
+ * happened to this customer" question an audit log mostly exists for.
+ * Pair them or use `resource_id` alone — ids are already unique.
+ */
 interface AuditLogsListParams extends BaseListParams {
     action?: string;
     resource_type?: string;
+    resource_id?: string;
     actor_id?: string;
 }
 /**
@@ -716,6 +835,40 @@ interface CreditNotesListParams extends BaseListParams {
     invoice_id?: string;
     customer_id?: string;
 }
+/**
+ * Body for `POST /v1/tenant/billing_profile`: the seller identity that
+ * VAT is decided against and that an invoice prints.
+ *
+ * `country_code` is required on every call: there is nothing to leave
+ * alone about a jurisdiction. Every other field is partial-update: omit
+ * it to leave the stored value alone, or pass an explicit `null` to
+ * clear it, because ceasing to be VAT registered (or moving office) is a
+ * real event.
+ */
+interface SetTenantBillingProfileParams extends IdempotencyOptions {
+    /** ISO-3166-1 alpha-2, e.g. `"NL"`. */
+    country_code: string;
+    /** Your own EU VAT registration, or `null` to clear it. */
+    vat_id?: string | null;
+    address_line1?: string | null;
+    address_line2?: string | null;
+    postal_code?: string | null;
+    city?: string | null;
+    registration_number?: string | null;
+}
+/**
+ * Body for `POST /v1/api_keys`. The full key is returned **once**, on the
+ * create response, and is never retrievable again.
+ */
+interface CreateApiKeyParams extends IdempotencyOptions {
+    /** Human label, so a key can be identified before it is revoked. */
+    label?: string;
+    /**
+     * Narrow what the key may do. Omit to inherit the calling key's own
+     * scopes; a key can never grant more than it holds.
+     */
+    scopes?: string[];
+}
 /** `invoices.void` params. `reason` is recorded on the audit row only. */
 interface VoidInvoiceParams extends IdempotencyOptions {
     reason?: string;
@@ -723,6 +876,12 @@ interface VoidInvoiceParams extends IdempotencyOptions {
 interface CreateBillingPortalSessionParams extends IdempotencyOptions {
     subscription_id: string;
     return_url: string;
+    /**
+     * Also email the portal link to the subscription's customer, at the
+     * address on their record, as a tenant-branded message. Defaults to
+     * `false`: without it you distribute the returned `url` yourself.
+     */
+    deliver_email?: boolean;
 }
 /**
  * Shared transport wrapper. Resources subclass this so each method
@@ -733,7 +892,13 @@ interface CreateBillingPortalSessionParams extends IdempotencyOptions {
 declare abstract class BaseResource {
     protected readonly t: Transport;
     constructor(t: Transport);
-    protected get<T>(path: string, query?: BaseListParams & Record<string, QueryValue>): Promise<T>;
+    /**
+     * `query` is a plain object rather than an index-signature type: TypeScript
+     * only gives an implicit index signature to type *aliases*, so a closed
+     * `*ListParams` interface would otherwise need a cast at every call site.
+     * The transport prunes `undefined`/`null` and joins arrays with commas.
+     */
+    protected get<T>(path: string, query?: object): 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>;
@@ -793,7 +958,8 @@ declare class Customers extends BaseResource {
 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>;
+    /** Expandable: `prices` (every price on the product), `stats`. */
+    retrieve<T = unknown>(id: string, options?: ExpandOptions): Promise<T>;
     /**
      * Patch mutable Product fields, or archive it with `active: false`.
      *
@@ -804,7 +970,7 @@ declare class Products extends BaseResource {
      * `active: true` un-archives.
      */
     update<T = unknown>(id: string, params: UpdateProductParams): Promise<T>;
-    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    list<T = unknown>(params?: ProductsListParams): Promise<ListResponseEnvelope<T>>;
     iter<T = unknown>(options?: {
         pageSize?: number;
     }): AsyncIterableIterator<T>;
@@ -868,7 +1034,8 @@ declare class OneShotPayments extends BaseResource {
     retrieve<T = unknown>(id: string): Promise<T>;
 }
 declare class Subscriptions extends BaseResource {
-    retrieve<T = unknown>(id: string): Promise<T>;
+    /** Expandable: `customer`, `price`, `refund_eligibility`. */
+    retrieve<T = unknown>(id: string, options?: ExpandOptions): Promise<T>;
     /**
      * List subscriptions, newest first, optionally filtered.
      *
@@ -977,12 +1144,22 @@ declare class Refunds extends BaseResource {
  */
 declare class Disputes extends BaseResource {
     retrieve<T = unknown>(id: string): Promise<T>;
-    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    list<T = unknown>(params?: DisputesListParams): Promise<ListResponseEnvelope<T>>;
     iter<T = unknown>(options?: {
         pageSize?: number;
+        status?: string;
+        payment_id?: string;
     }): AsyncIterableIterator<T>;
 }
 declare class WebhookEndpoints extends BaseResource {
+    /**
+     * Every event type this deployment can deliver, plus the wildcard.
+     *
+     * `enabled_events` rejects anything not on this list, so read it rather
+     * than hard-coding a set: a name that is not on it fails at
+     * registration and leaves you with an endpoint that never fires.
+     */
+    listEventTypes<T = unknown>(): Promise<T>;
     create<T = unknown>(params: CreateWebhookEndpointParams): Promise<T>;
     retrieve<T = unknown>(id: string): Promise<T>;
     /**
@@ -1066,6 +1243,40 @@ declare class Events extends BaseResource {
 declare class Tenant extends BaseResource {
     /** Cached Mollie profile shape (enabled methods, country, currency). */
     capabilities<T = unknown>(): Promise<T>;
+    /**
+     * Your registered country and VAT number: what your customers' VAT is
+     * decided against.
+     *
+     * `country_code` is what you have stored and can be `null`;
+     * `effective_country_code` is what the next charge will really use.
+     * The two differ only when you have stored nothing, which is exactly
+     * the case worth spotting before a first live payment.
+     */
+    billingProfile<T = unknown>(): Promise<T>;
+    /**
+     * Set the seller identity. `country_code` is required on every call;
+     * every other field is partial-update, with an explicit `null` to
+     * clear. Changes take effect on the next charge only. Tax is written
+     * onto a payment and its invoice before money moves, and nothing goes
+     * back and recalculates it.
+     */
+    setBillingProfile<T = unknown>(params: SetTenantBillingProfileParams): Promise<T>;
+    /**
+     * Download everything in the account as one JSON document, as raw bytes.
+     *
+     * ```ts
+     * await writeFile("export.json", Buffer.from(await client.tenant.export()));
+     * ```
+     *
+     * The GDPR Article 20 portability route, and the way to take a backup.
+     * It is `application/json` streamed inline, with no redirect, and each
+     * record has the same shape its `GET` route returns, with
+     * `billkit_export_version` naming the shape. It can be large, so write
+     * it to a file rather than holding it in memory. Test and live data
+     * export separately: you get whichever mode the key belongs to. The
+     * access is recorded in your audit log.
+     */
+    export(): Promise<ArrayBuffer>;
     /** Current portal branding row (business name, theme, capability flags). */
     portalBranding<T = unknown>(): Promise<T>;
     /**
@@ -1134,7 +1345,8 @@ declare class TaxRates extends BaseResource {
  * {@link Invoices.retrievePdf}.
  */
 declare class Invoices extends BaseResource {
-    retrieve<T = unknown>(id: string): Promise<T>;
+    /** Expandable: `customer`. */
+    retrieve<T = unknown>(id: string, options?: ExpandOptions): Promise<T>;
     /**
      * Download the rendered invoice PDF as raw bytes.
      *
@@ -1154,9 +1366,24 @@ declare class Invoices extends BaseResource {
      * structured invoice for tenants who render their own.
      */
     retrievePdf(id: string): Promise<ArrayBuffer>;
-    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    /**
+     * Send the customer their invoice again.
+     *
+     * The same tenant-branded "your invoice is ready" email, with a fresh
+     * portal link, because the one in the original may have expired. It
+     * goes to the address captured **on the invoice**, not the customer's
+     * current one: this is a copy of a document that was issued to
+     * somebody. An invoice with no address on file is a
+     * `InvalidRequestError` rather than a send that did not happen.
+     */
+    sendEmail<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    list<T = unknown>(params?: InvoicesListParams): Promise<ListResponseEnvelope<T>>;
     iter<T = unknown>(options?: {
         pageSize?: number;
+        customer_id?: string;
+        subscription_id?: string;
+        payment_id?: string;
+        status?: string;
     }): AsyncIterableIterator<T>;
     /**
      * Void an invoice: state that the sale was never owed.
@@ -1214,6 +1441,7 @@ declare class AuditLogs extends BaseResource {
         pageSize?: number;
         action?: string;
         resource_type?: string;
+        resource_id?: string;
         actor_id?: string;
     }): AsyncIterableIterator<T>;
 }
@@ -1225,10 +1453,23 @@ declare class AuditLogs extends BaseResource {
  * 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>>;
+    /** Expandable: `customer`, `subscription`. */
+    retrieve<T = unknown>(id: string, options?: ExpandOptions): Promise<T>;
+    /**
+     * Fetch the provider's own record of this charge, live.
+     *
+     * Reads Mollie at request time rather than a stored copy, so it carries
+     * what BillKit deliberately does not keep: the card BIN, the iDEAL
+     * bank, the provider's own status string. Reading live means it can
+     * fail: a provider outage or a charge old enough to have aged out
+     * answers `200` with `available: false` and a short reason, so render
+     * the rest of the page regardless.
+     */
+    retrieveProvider<T = unknown>(id: string): Promise<T>;
+    list<T = unknown>(params?: PaymentsListParams): Promise<ListResponseEnvelope<T>>;
     iter<T = unknown>(options?: {
         pageSize?: number;
+        customer_id?: string;
     }): AsyncIterableIterator<T>;
 }
 /**
@@ -1244,6 +1485,38 @@ declare class BillingPortalSessions extends BaseResource {
     /** Kill an in-the-wild portal session. Idempotent. */
     revoke<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
 }
+/**
+ * Issue, inspect and revoke API keys.
+ *
+ * A key is issued in the same mode as the key that created it, so a test
+ * key can only mint test keys, and it can never grant scopes it does not
+ * hold itself. The secret is returned **once**, on
+ * {@link ApiKeys.create}; every later read carries only the prefix.
+ */
+declare class ApiKeys extends BaseResource {
+    /**
+     * Issue a new key. The response's `secret` is the only time the full
+     * key exists outside the caller's own storage, so record it now.
+     */
+    create<T = unknown>(params?: CreateApiKeyParams): Promise<T>;
+    /**
+     * One key's metadata: prefix, label, scopes, `revoked_at`, and
+     * `last_used_at`, which is the field to read before revoking one.
+     */
+    retrieve<T = unknown>(id: string): Promise<T>;
+    /**
+     * Revoke a key so it stops working. Immediate and irreversible; issue a
+     * new key instead. Revoking an already-revoked key returns it
+     * unchanged, so a retry is safe, and a key may revoke itself, which is
+     * what you want when the leaked key is the one you are calling with.
+     */
+    revoke<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
+    /** List keys, newest first. Revoked ones are included; check `revoked_at`. */
+    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+    }): AsyncIterableIterator<T>;
+}
 
 /**
  * Top-level BillKit client.
@@ -1259,6 +1532,7 @@ interface BillKitOptions extends Omit<TransportConfig, "apiKey"> {
     apiKey?: string;
 }
 declare class BillKit {
+    readonly apiKeys: ApiKeys;
     readonly customers: Customers;
     readonly products: Products;
     readonly prices: Prices;
@@ -1287,6 +1561,12 @@ interface BillKitErrorOptions {
     statusCode?: number | undefined;
     requestId?: string | undefined;
     rawBody?: unknown;
+    /**
+     * The underlying error, forwarded to `Error`'s own `cause`. Set on
+     * `APIConnectionError` so the runtime's reason for a failed fetch
+     * (`ECONNREFUSED`, a TLS failure, an abort) survives the mapping.
+     */
+    cause?: unknown;
 }
 declare class BillKitError extends Error {
     name: string;
@@ -1330,7 +1610,7 @@ declare class RateLimitError extends BillKitError {
     });
 }
 
-declare const VERSION = "0.5.0";
+declare const VERSION = "0.7.0";
 
 /**
  * Verify `BillKit-Signature: t=<unix>,v1=<hex>` headers.
@@ -1362,4 +1642,4 @@ interface VerifyWebhookOptions {
 }
 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 CreateUsageRecordParams, type CreateWebhookEndpointParams, type CreditNotesListParams, type CustomerListParams, DEFAULT_RETRY_POLICY, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, type EventsListParams, type IdempotencyOptions, InvalidRequestError, type ListParams, type ListResponseEnvelope, type LogContext, NOOP_LOGGER, type PaginateOptions, PermissionError, type PriceTier, type PricesListParams, RateLimitError, ResourceMissingError, type RetryPolicy, type RotateProviderCredentialParams, ServerError, type SetPortalBrandingParams, type SubscriptionsListParams, type UpdateCouponParams, type UpdateCustomerParams, type UpdateProductParams, type UpdateTaxRateParams, type UpdateWebhookEndpointParams, type UsageRecordsListParams, VERSION, type ValidateCouponParams, type VerifyWebhookOptions, type VoidInvoiceParams, WebhookVerificationError, paginate, verifyWebhookSignature };
+export { APIConnectionError, APIError, type AuditLogsListParams, AuthenticationError, type BaseListParams, BillKit, BillKitError, type BillKitLogger, type BillKitOptions, ConflictError, type CreateApiKeyParams, type CreateBillingPortalSessionParams, type CreateCheckoutSessionParams, type CreateCouponParams, type CreateCustomerParams, type CreateOneShotPaymentParams, type CreatePriceParams, type CreateProductParams, type CreateRefundParams, type CreateTaxRateParams, type CreateUsageRecordParams, type CreateWebhookEndpointParams, type CreditNotesListParams, type CustomerListParams, DEFAULT_RETRY_POLICY, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, type DisputesListParams, type EventsListParams, type ExpandOptions, type IdempotencyOptions, InvalidRequestError, type InvoicesListParams, type ListParams, type ListResponseEnvelope, type LogContext, NOOP_LOGGER, type PaginateOptions, type PaymentsListParams, PermissionError, type PriceTier, type PricesListParams, type ProductsListParams, RateLimitError, ResourceMissingError, type RetryPolicy, type RotateProviderCredentialParams, ServerError, type SetCustomerVatNumberParams, type SetPortalBrandingParams, type SetTenantBillingProfileParams, type SubscriptionsListParams, type UpdateCouponParams, type UpdateCustomerParams, type UpdatePriceParams, type UpdateProductParams, type UpdateTaxRateParams, type UpdateWebhookEndpointParams, type UsageRecordsListParams, VERSION, type ValidateCouponParams, type VerifyWebhookOptions, type VoidInvoiceParams, WebhookVerificationError, paginate, verifyWebhookSignature };