@billkit-eu/sdk 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -26,6 +26,9 @@ async function* paginate(listFn, options = {}) {
 }
 
 // src/resources.ts
+function p(id) {
+  return encodeURIComponent(id);
+}
 function dropUndefined(obj) {
   const out = {};
   for (const [k, v] of Object.entries(obj)) {
@@ -58,6 +61,12 @@ var BaseResource = class {
     this.t = t;
   }
   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.
+   */
   get(path, query) {
     return this.t.request({ method: "GET", path, query });
   }
@@ -98,10 +107,10 @@ var Customers = class extends BaseResource {
     return this.post("/v1/customers", params);
   }
   retrieve(id) {
-    return this.get(`/v1/customers/${id}`);
+    return this.get(`/v1/customers/${p(id)}`);
   }
   update(id, params = {}) {
-    return this.post(`/v1/customers/${id}`, params);
+    return this.post(`/v1/customers/${p(id)}`, params);
   }
   /**
    * Delete a customer. Resolves to `{ id, object: "customer", deleted:
@@ -114,7 +123,7 @@ var Customers = class extends BaseResource {
    * charge them.
    */
   delete(id, params = {}) {
-    return this.del(`/v1/customers/${id}`, params);
+    return this.del(`/v1/customers/${p(id)}`, params);
   }
   /**
    * List customers, newest first.
@@ -131,7 +140,7 @@ var Customers = class extends BaseResource {
   }
   /** Walk every page of `list()` and yield each customer. */
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/customers", p), { pageSize: options.pageSize });
+    return paginate((page) => this.get("/v1/customers", page), { pageSize: options.pageSize });
   }
   /**
    * Attach or replace the customer's VAT number; triggers server-side
@@ -139,7 +148,7 @@ var Customers = class extends BaseResource {
    * reflecting whether VIES confirmed the number.
    */
   setVatNumber(id, params) {
-    return this.post(`/v1/customers/${id}/vat_number`, params);
+    return this.post(`/v1/customers/${p(id)}/vat_number`, params);
   }
   /**
    * Hard-purge a customer's PII for GDPR erasure. Distinct from
@@ -151,7 +160,7 @@ var Customers = class extends BaseResource {
    */
   purge(id, params = {}) {
     const { confirmed = true, idempotencyKey } = params;
-    return this.postFixed(`/v1/customers/${id}/purge`, { confirmed }, { idempotencyKey });
+    return this.postFixed(`/v1/customers/${p(id)}/purge`, { confirmed }, { idempotencyKey });
   }
 };
 var Products = class extends BaseResource {
@@ -159,8 +168,9 @@ var Products = class extends BaseResource {
   create(params) {
     return this.post("/v1/products", params);
   }
-  retrieve(id) {
-    return this.get(`/v1/products/${id}`);
+  /** Expandable: `prices` (every price on the product), `stats`. */
+  retrieve(id, options = {}) {
+    return this.get(`/v1/products/${p(id)}`, options);
   }
   /**
    * Patch mutable Product fields, or archive it with `active: false`.
@@ -172,13 +182,13 @@ var Products = class extends BaseResource {
    * `active: true` un-archives.
    */
   update(id, params) {
-    return this.post(`/v1/products/${id}`, params);
+    return this.post(`/v1/products/${p(id)}`, params);
   }
   list(params = {}) {
     return this.get("/v1/products", params);
   }
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/products", p), { pageSize: options.pageSize });
+    return paginate((page) => this.get("/v1/products", page), { pageSize: options.pageSize });
   }
 };
 var Prices = class extends BaseResource {
@@ -201,7 +211,7 @@ var Prices = class extends BaseResource {
     return this.post("/v1/prices", assertPriceRatesAreStrings(params));
   }
   retrieve(id) {
-    return this.get(`/v1/prices/${id}`);
+    return this.get(`/v1/prices/${p(id)}`);
   }
   /**
    * Archive a Price so it stops selling, or put it back on sale.
@@ -224,14 +234,14 @@ var Prices = class extends BaseResource {
    * `price.archived`; putting one back emits `price.updated`.
    */
   update(id, params) {
-    return this.post(`/v1/prices/${id}`, params);
+    return this.post(`/v1/prices/${p(id)}`, params);
   }
   list(params = {}) {
     return this.get("/v1/prices", params);
   }
   iter(options = {}) {
     const filter = options.product_id === void 0 ? {} : { product_id: options.product_id };
-    return paginate((p) => this.get("/v1/prices", { ...filter, ...p }), {
+    return paginate((page) => this.get("/v1/prices", { ...filter, ...page }), {
       pageSize: options.pageSize
     });
   }
@@ -241,7 +251,7 @@ var CheckoutSessions = class extends BaseResource {
     return this.post("/v1/checkout/sessions", params);
   }
   retrieve(id) {
-    return this.get(`/v1/checkout/sessions/${id}`);
+    return this.get(`/v1/checkout/sessions/${p(id)}`);
   }
 };
 var OneShotPayments = class extends BaseResource {
@@ -250,12 +260,13 @@ var OneShotPayments = class extends BaseResource {
     return this.post("/v1/checkout/one_shot", params);
   }
   retrieve(id) {
-    return this.get(`/v1/checkout/one_shot/${id}`);
+    return this.get(`/v1/checkout/one_shot/${p(id)}`);
   }
 };
 var Subscriptions = class extends BaseResource {
-  retrieve(id) {
-    return this.get(`/v1/subscriptions/${id}`);
+  /** Expandable: `customer`, `price`, `refund_eligibility`. */
+  retrieve(id, options = {}) {
+    return this.get(`/v1/subscriptions/${p(id)}`, options);
   }
   /**
    * List subscriptions, newest first, optionally filtered.
@@ -273,16 +284,16 @@ var Subscriptions = class extends BaseResource {
    */
   iter(options = {}) {
     const { pageSize, ...filter } = options;
-    return paginate((p) => this.get("/v1/subscriptions", { ...filter, ...p }), { pageSize });
+    return paginate((page) => this.get("/v1/subscriptions", { ...filter, ...page }), { pageSize });
   }
   cancel(id, params = {}) {
-    return this.postEmpty(`/v1/subscriptions/${id}/cancel`, params);
+    return this.postEmpty(`/v1/subscriptions/${p(id)}/cancel`, params);
   }
   pause(id, params = {}) {
-    return this.postEmpty(`/v1/subscriptions/${id}/pause`, params);
+    return this.postEmpty(`/v1/subscriptions/${p(id)}/pause`, params);
   }
   resume(id, params = {}) {
-    return this.postEmpty(`/v1/subscriptions/${id}/resume`, params);
+    return this.postEmpty(`/v1/subscriptions/${p(id)}/resume`, params);
   }
   /**
    * Reactivate a canceled-but-still-in-period subscription.
@@ -293,23 +304,23 @@ var Subscriptions = class extends BaseResource {
    * Returns `409` if the period has already elapsed.
    */
   reactivate(id, params = {}) {
-    return this.postEmpty(`/v1/subscriptions/${id}/reactivate`, params);
+    return this.postEmpty(`/v1/subscriptions/${p(id)}/reactivate`, params);
   }
   previewUpdate(id, params) {
-    return this.postFixed(`/v1/subscriptions/${id}/preview_update`, {
+    return this.postFixed(`/v1/subscriptions/${p(id)}/preview_update`, {
       target_price_id: params.target_price_id
     });
   }
   update(id, params) {
     return this.postFixed(
-      `/v1/subscriptions/${id}/update`,
+      `/v1/subscriptions/${p(id)}/update`,
       { target_price_id: params.target_price_id },
       { idempotencyKey: params.idempotencyKey }
     );
   }
   reauthorizePaymentMethod(id, params) {
     return this.postFixed(
-      `/v1/subscriptions/${id}/reauthorize_payment_method`,
+      `/v1/subscriptions/${p(id)}/reauthorize_payment_method`,
       { return_url: params.return_url },
       { idempotencyKey: params.idempotencyKey }
     );
@@ -331,7 +342,7 @@ var Subscriptions = class extends BaseResource {
    * See {@link CreateUsageRecordParams.identifier}.
    */
   createUsageRecord(id, params) {
-    return this.post(`/v1/subscriptions/${id}/usage_records`, params);
+    return this.post(`/v1/subscriptions/${p(id)}/usage_records`, params);
   }
   /**
    * List usage records for one subscription.
@@ -341,11 +352,11 @@ var Subscriptions = class extends BaseResource {
    * invoice charged for.
    */
   listUsageRecords(id, params = {}) {
-    return this.get(`/v1/subscriptions/${id}/usage_records`, params);
+    return this.get(`/v1/subscriptions/${p(id)}/usage_records`, params);
   }
   /** Walk every page of `listUsageRecords()` for one subscription. */
   iterUsageRecords(id, options = {}) {
-    return paginate((p) => this.get(`/v1/subscriptions/${id}/usage_records`, p), {
+    return paginate((page) => this.get(`/v1/subscriptions/${p(id)}/usage_records`, page), {
       pageSize: options.pageSize,
       filters: { invoice_id: options.invoice_id }
     });
@@ -369,7 +380,7 @@ var Subscriptions = class extends BaseResource {
    * unsettled; while one is open, this period cannot be charged.
    */
   retrieveUsageSummary(id) {
-    return this.get(`/v1/subscriptions/${id}/usage_summary`);
+    return this.get(`/v1/subscriptions/${p(id)}/usage_summary`);
   }
 };
 var Refunds = class extends BaseResource {
@@ -377,32 +388,45 @@ var Refunds = class extends BaseResource {
     return this.post("/v1/refunds", params);
   }
   retrieve(id) {
-    return this.get(`/v1/refunds/${id}`);
+    return this.get(`/v1/refunds/${p(id)}`);
   }
   list(params = {}) {
     return this.get("/v1/refunds", params);
   }
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/refunds", p), { pageSize: options.pageSize });
+    return paginate((page) => this.get("/v1/refunds", page), { pageSize: options.pageSize });
   }
 };
 var Disputes = class extends BaseResource {
   retrieve(id) {
-    return this.get(`/v1/disputes/${id}`);
+    return this.get(`/v1/disputes/${p(id)}`);
   }
   list(params = {}) {
     return this.get("/v1/disputes", params);
   }
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/disputes", p), { pageSize: options.pageSize });
+    return paginate((page) => this.get("/v1/disputes", page), {
+      pageSize: options.pageSize,
+      filters: { status: options.status, payment_id: options.payment_id }
+    });
   }
 };
 var WebhookEndpoints = class 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() {
+    return this.get("/v1/webhook_endpoints/event_types");
+  }
   create(params) {
     return this.post("/v1/webhook_endpoints", params);
   }
   retrieve(id) {
-    return this.get(`/v1/webhook_endpoints/${id}`);
+    return this.get(`/v1/webhook_endpoints/${p(id)}`);
   }
   /**
    * Update an endpoint, or stop delivery with `status: "disabled"`.
@@ -413,7 +437,7 @@ var WebhookEndpoints = class extends BaseResource {
    * disabling is reversible and deleting is not.
    */
   update(id, params) {
-    return this.post(`/v1/webhook_endpoints/${id}`, params);
+    return this.post(`/v1/webhook_endpoints/${p(id)}`, params);
   }
   /**
    * Delete an endpoint. Resolves to `{ id, object: "webhook_endpoint",
@@ -427,17 +451,17 @@ var WebhookEndpoints = class extends BaseResource {
    * were sent stays on record.
    */
   delete(id, params = {}) {
-    return this.del(`/v1/webhook_endpoints/${id}`, params);
+    return this.del(`/v1/webhook_endpoints/${p(id)}`, params);
   }
   /** Rotate the signing secret. The new `bkwhsec_...` is returned once. */
   rotateSecret(id, params = {}) {
-    return this.postEmpty(`/v1/webhook_endpoints/${id}/rotate_secret`, params);
+    return this.postEmpty(`/v1/webhook_endpoints/${p(id)}/rotate_secret`, params);
   }
   list(params = {}) {
     return this.get("/v1/webhook_endpoints", params);
   }
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/webhook_endpoints", p), {
+    return paginate((page) => this.get("/v1/webhook_endpoints", page), {
       pageSize: options.pageSize
     });
   }
@@ -450,20 +474,20 @@ var WebhookEndpoints = class extends BaseResource {
    */
   listDeliveries(endpointId, params = {}) {
     return this.get(
-      `/v1/webhook_endpoints/${endpointId}/deliveries`,
+      `/v1/webhook_endpoints/${p(endpointId)}/deliveries`,
       params
     );
   }
   /** Walk every page of `listDeliveries()` for one endpoint. */
   iterDeliveries(endpointId, options = {}) {
     return paginate(
-      (p) => this.get(`/v1/webhook_endpoints/${endpointId}/deliveries`, p),
+      (page) => this.get(`/v1/webhook_endpoints/${p(endpointId)}/deliveries`, page),
       { pageSize: options.pageSize }
     );
   }
   /** Fetch one delivery row for inspection before deciding to redeliver. */
   retrieveDelivery(endpointId, deliveryId) {
-    return this.get(`/v1/webhook_endpoints/${endpointId}/deliveries/${deliveryId}`);
+    return this.get(`/v1/webhook_endpoints/${p(endpointId)}/deliveries/${p(deliveryId)}`);
   }
   /**
    * @deprecated Renamed to {@link WebhookEndpoints.retrieveDelivery}.
@@ -488,21 +512,21 @@ var WebhookEndpoints = class extends BaseResource {
    */
   redeliver(endpointId, deliveryId, params = {}) {
     return this.postEmpty(
-      `/v1/webhook_endpoints/${endpointId}/deliveries/${deliveryId}/redeliver`,
+      `/v1/webhook_endpoints/${p(endpointId)}/deliveries/${p(deliveryId)}/redeliver`,
       params
     );
   }
 };
 var Events = class extends BaseResource {
   retrieve(id) {
-    return this.get(`/v1/events/${id}`);
+    return this.get(`/v1/events/${p(id)}`);
   }
   list(params = {}) {
     return this.get("/v1/events", params);
   }
   /** Walk every page of `list()`. Pass `type` to filter at the server. */
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/events", p), {
+    return paginate((page) => this.get("/v1/events", page), {
       pageSize: options.pageSize,
       filters: { type: options.type }
     });
@@ -513,6 +537,46 @@ var Tenant = class extends BaseResource {
   capabilities() {
     return this.get("/v1/tenant/capabilities");
   }
+  /**
+   * 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() {
+    return this.get("/v1/tenant/billing_profile");
+  }
+  /**
+   * 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(params) {
+    return this.post("/v1/tenant/billing_profile", params);
+  }
+  /**
+   * 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() {
+    return this.t.requestBinary({ method: "GET", path: "/v1/tenant/export" });
+  }
   /** Current portal branding row (business name, theme, capability flags). */
   portalBranding() {
     return this.get("/v1/tenant/portal_branding");
@@ -546,7 +610,7 @@ var Coupons = class extends BaseResource {
     return this.post("/v1/coupons", params);
   }
   retrieve(id) {
-    return this.get(`/v1/coupons/${id}`);
+    return this.get(`/v1/coupons/${p(id)}`);
   }
   /**
    * Update a coupon's limits, or withdraw it with `active: false`.
@@ -557,7 +621,7 @@ var Coupons = class extends BaseResource {
    * customer was charged. `active: true` brings the campaign back.
    */
   update(id, params) {
-    return this.post(`/v1/coupons/${id}`, params);
+    return this.post(`/v1/coupons/${p(id)}`, params);
   }
   /**
    * Server-side dry-run of a coupon redemption.
@@ -575,7 +639,7 @@ var Coupons = class extends BaseResource {
     return this.get("/v1/coupons", params);
   }
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/coupons", p), { pageSize: options.pageSize });
+    return paginate((page) => this.get("/v1/coupons", page), { pageSize: options.pageSize });
   }
 };
 var TaxRates = class extends BaseResource {
@@ -583,7 +647,7 @@ var TaxRates = class extends BaseResource {
     return this.post("/v1/tax_rates", params);
   }
   retrieve(id) {
-    return this.get(`/v1/tax_rates/${id}`);
+    return this.get(`/v1/tax_rates/${p(id)}`);
   }
   /**
    * Correct a rate, retire it with `active: false`, or bring one back.
@@ -594,18 +658,19 @@ var TaxRates = class extends BaseResource {
    * is no `delete()`.
    */
   update(id, params) {
-    return this.post(`/v1/tax_rates/${id}`, params);
+    return this.post(`/v1/tax_rates/${p(id)}`, params);
   }
   list(params = {}) {
     return this.get("/v1/tax_rates", params);
   }
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/tax_rates", p), { pageSize: options.pageSize });
+    return paginate((page) => this.get("/v1/tax_rates", page), { pageSize: options.pageSize });
   }
 };
 var Invoices = class extends BaseResource {
-  retrieve(id) {
-    return this.get(`/v1/invoices/${id}`);
+  /** Expandable: `customer`. */
+  retrieve(id, options = {}) {
+    return this.get(`/v1/invoices/${p(id)}`, options);
   }
   /**
    * Download the rendered invoice PDF as raw bytes.
@@ -626,13 +691,27 @@ var Invoices = class extends BaseResource {
    * structured invoice for tenants who render their own.
    */
   retrievePdf(id) {
-    return this.t.requestBinary({ method: "GET", path: `/v1/invoices/${id}/pdf` });
+    return this.t.requestBinary({ method: "GET", path: `/v1/invoices/${p(id)}/pdf` });
+  }
+  /**
+   * 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(id, params = {}) {
+    return this.postEmpty(`/v1/invoices/${p(id)}/email`, params);
   }
   list(params = {}) {
     return this.get("/v1/invoices", params);
   }
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/invoices", p), { pageSize: options.pageSize });
+    const { pageSize, ...filters } = options;
+    return paginate((page) => this.get("/v1/invoices", page), { pageSize, filters });
   }
   /**
    * Void an invoice: state that the sale was never owed.
@@ -650,12 +729,12 @@ var Invoices = class extends BaseResource {
    * Idempotent: re-voiding an already-void invoice returns it unchanged.
    */
   void(id, params = {}) {
-    return this.post(`/v1/invoices/${id}/void`, params);
+    return this.post(`/v1/invoices/${p(id)}/void`, params);
   }
 };
 var CreditNotes = class extends BaseResource {
   retrieve(id) {
-    return this.get(`/v1/credit_notes/${id}`);
+    return this.get(`/v1/credit_notes/${p(id)}`);
   }
   /**
    * Download the rendered credit note PDF as raw bytes. Same storage
@@ -663,13 +742,13 @@ var CreditNotes = class extends BaseResource {
    * `302`, and `501 rendering_pending` on a deployment with no renderer.
    */
   retrievePdf(id) {
-    return this.t.requestBinary({ method: "GET", path: `/v1/credit_notes/${id}/pdf` });
+    return this.t.requestBinary({ method: "GET", path: `/v1/credit_notes/${p(id)}/pdf` });
   }
   list(params = {}) {
     return this.get("/v1/credit_notes", params);
   }
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/credit_notes", p), {
+    return paginate((page) => this.get("/v1/credit_notes", page), {
       pageSize: options.pageSize,
       filters: { invoice_id: options.invoice_id, customer_id: options.customer_id }
     });
@@ -677,47 +756,90 @@ var CreditNotes = class extends BaseResource {
 };
 var AuditLogs = class extends BaseResource {
   retrieve(id) {
-    return this.get(`/v1/audit_logs/${id}`);
+    return this.get(`/v1/audit_logs/${p(id)}`);
   }
   list(params = {}) {
     return this.get("/v1/audit_logs", params);
   }
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/audit_logs", p), {
+    return paginate((page) => this.get("/v1/audit_logs", page), {
       pageSize: options.pageSize,
       filters: {
         action: options.action,
         resource_type: options.resource_type,
+        resource_id: options.resource_id,
         actor_id: options.actor_id
       }
     });
   }
 };
 var Payments = class extends BaseResource {
-  retrieve(id) {
-    return this.get(`/v1/payments/${id}`);
+  /** Expandable: `customer`, `subscription`. */
+  retrieve(id, options = {}) {
+    return this.get(`/v1/payments/${p(id)}`, options);
+  }
+  /**
+   * 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(id) {
+    return this.get(`/v1/payments/${p(id)}/provider`);
   }
   list(params = {}) {
     return this.get("/v1/payments", params);
   }
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/payments", p), { pageSize: options.pageSize });
+    return paginate((page) => this.get("/v1/payments", page), {
+      pageSize: options.pageSize,
+      filters: { customer_id: options.customer_id }
+    });
   }
 };
 var BillingPortalSessions = class extends BaseResource {
   create(params) {
-    return this.postFixed(
-      "/v1/billing_portal/sessions",
-      {
-        subscription_id: params.subscription_id,
-        return_url: params.return_url
-      },
-      { idempotencyKey: params.idempotencyKey }
-    );
+    return this.post("/v1/billing_portal/sessions", params);
   }
   /** Kill an in-the-wild portal session. Idempotent. */
   revoke(id, params = {}) {
-    return this.postEmpty(`/v1/billing_portal/sessions/${id}/revoke`, params);
+    return this.postEmpty(`/v1/billing_portal/sessions/${p(id)}/revoke`, params);
+  }
+};
+var ApiKeys = class 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(params = {}) {
+    return this.post("/v1/api_keys", params);
+  }
+  /**
+   * One key's metadata: prefix, label, scopes, `revoked_at`, and
+   * `last_used_at`, which is the field to read before revoking one.
+   */
+  retrieve(id) {
+    return this.get(`/v1/api_keys/${p(id)}`);
+  }
+  /**
+   * 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(id, params = {}) {
+    return this.postEmpty(`/v1/api_keys/${p(id)}/revoke`, params);
+  }
+  /** List keys, newest first. Revoked ones are included; check `revoked_at`. */
+  list(params = {}) {
+    return this.get("/v1/api_keys", params);
+  }
+  iter(options = {}) {
+    return paginate((page) => this.get("/v1/api_keys", page), { pageSize: options.pageSize });
   }
 };
 
@@ -731,7 +853,7 @@ var BillKitError = class extends Error {
   requestId;
   rawBody;
   constructor(message, options = {}) {
-    super(message);
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
     this.type = options.type;
     this.code = options.code;
     this.param = options.param;
@@ -851,7 +973,7 @@ function sleep(ms) {
 }
 
 // src/version.ts
-var VERSION = "0.5.0";
+var VERSION = "0.7.0";
 
 // src/transport.ts
 var DEFAULT_BASE_URL = "https://api.billkit.eu";
@@ -879,9 +1001,8 @@ function buildUrl(baseUrl, path, query) {
   const url = new URL(baseUrl.replace(/\/$/, "") + normalised);
   if (query) {
     for (const [k, v] of Object.entries(query)) {
-      if (v !== null && v !== void 0) {
-        url.searchParams.set(k, String(v));
-      }
+      if (v === null || v === void 0) continue;
+      url.searchParams.set(k, Array.isArray(v) ? v.join(",") : String(v));
     }
   }
   return url.toString();
@@ -935,9 +1056,11 @@ function retryDelayMs(status, attempt, policy, retryAfterMs) {
 function connectionError(err, timeoutMs) {
   const e = err;
   if (e?.name === "TimeoutError" || e?.name === "AbortError") {
-    return new APIConnectionError(`BillKit request timed out after ${timeoutMs}ms.`);
+    return new APIConnectionError(`BillKit request timed out after ${timeoutMs}ms.`, {
+      cause: err
+    });
   }
-  return new APIConnectionError(e?.message ?? "Network request failed.");
+  return new APIConnectionError(e?.message ?? "Network request failed.", { cause: err });
 }
 var Transport = class {
   apiKey;
@@ -1071,6 +1194,7 @@ function resolveApiKey(supplied) {
   );
 }
 var BillKit = class {
+  apiKeys;
   customers;
   products;
   prices;
@@ -1094,6 +1218,7 @@ var BillKit = class {
       ...options,
       apiKey: resolveApiKey(options.apiKey)
     });
+    this.apiKeys = new ApiKeys(transport);
     this.customers = new Customers(transport);
     this.products = new Products(transport);
     this.prices = new Prices(transport);