@billkit-eu/sdk 0.1.0 → 0.2.1

package/src/errors.ts

@@ -5,8 +5,11 @@
  *
  *   { "error": { "type": "...", "code": "...", "message": "...", "param": "..." } }
  *
- * Each `type` maps to one error class so callers can `catch` on the
- * subclass they care about rather than branching on HTTP status codes.
+ * The HTTP **status** picks the class so callers can `catch` on the
+ * subclass they care about rather than branching on status codes; the
+ * envelope's `type`/`code`/`param` ride along on the thrown object.
+ * See {@link classForStatus} for why the status, not `type`, is the
+ * authority.
  */
 
 export interface ErrorEnvelope {
@@ -96,21 +99,6 @@ export class RateLimitError extends BillKitError {
   }
 }
 
-const TYPE_TO_CLASS: Record<string, new (msg: string, opts: BillKitErrorOptions) => BillKitError> =
-  {
-    api_connection_error: APIConnectionError,
-    // ``api_error`` is the Stripe-convention type for 5xx, so surface it as
-    // ServerError (a subclass of APIError) so `catch (e instanceof
-    // ServerError)` works without false negatives.
-    api_error: ServerError,
-    authentication_error: AuthenticationError,
-    permission_error: PermissionError,
-    invalid_request_error: InvalidRequestError,
-    idempotency_error: ConflictError,
-    conflict: ConflictError,
-    rate_limit_error: RateLimitError,
-  };
-
 function fallbackType(status: number): string {
   if (status === 401) return "authentication_error";
   if (status === 403) return "permission_error";
@@ -121,15 +109,35 @@ function fallbackType(status: number): string {
   return "invalid_request_error";
 }
 
-function fallbackClass(
+/**
+ * Pick the exception class from the HTTP **status**, not the envelope
+ * `type`.
+ *
+ * The status is the field the API cannot get wrong. The `type` is
+ * accurate for errors BillKit raises itself, but a request that never
+ * reaches a route handler — an unmatched path, a method the route does
+ * not allow — is serialised by the framework-level handler as
+ * `{"type": "api_error", "code": "unhandled"}` *with a 4xx status*.
+ * Trusting `type` there mapped a plain `404 Not Found` (a typo in a
+ * resource id, or an SDK/API version skew) onto `ServerError`, telling
+ * the caller BillKit had broken when their own request was at fault —
+ * and `ServerError` is the class retry/alerting policies key on.
+ *
+ * The envelope `type` is still preserved verbatim on
+ * {@link BillKitError.type} for callers that want it; only the class is
+ * status-driven.
+ */
+function classForStatus(
   status: number,
 ): new (msg: string, opts: BillKitErrorOptions) => BillKitError {
+  if (status >= 500) return ServerError;
   if (status === 401) return AuthenticationError;
   if (status === 403) return PermissionError;
   if (status === 404) return ResourceMissingError;
   if (status === 409) return ConflictError;
   if (status === 429) return RateLimitError;
-  if (status >= 500) return ServerError;
+  // Everything else below 500 (400, 405, 422, 451 …) is a request the
+  // caller has to change.
   return InvalidRequestError;
 }
 
@@ -149,9 +157,7 @@ export function errorFromResponse(args: {
   const message =
     envelope.message ?? `BillKit API returned HTTP ${status} with no error body.`;
 
-  let cls = TYPE_TO_CLASS[type] ?? fallbackClass(status);
-  if (status === 404 && cls === InvalidRequestError) cls = ResourceMissingError;
-  if (status === 409 && cls === InvalidRequestError) cls = ConflictError;
+  const cls = classForStatus(status);
 
   const options: BillKitErrorOptions & { retryAfter?: number | undefined } = {
     type,

package/src/index.ts

@@ -6,7 +6,7 @@
  * ```ts
  * import { BillKit } from "@billkit-eu/sdk";
  *
- * const client = new BillKit({ apiKey: "sk_test_..." });
+ * const client = new BillKit({ apiKey: "bk_test_..." });
  * const customer = await client.customers.create<{ id: string }>({
  *   email: "ada@example.com",
  * });
@@ -45,7 +45,7 @@
  * a logger to opt in:
  *
  * ```ts
- * const client = new BillKit({ apiKey: "sk_test_...", logger: console });
+ * const client = new BillKit({ apiKey: "bk_test_...", logger: console });
  * ```
  *
  * See {@link BillKitLogger} for what is logged and what is withheld
@@ -79,6 +79,7 @@ export type {
   CreateProductParams,
   CreateRefundParams,
   CreateTaxRateParams,
+  CreateUsageRecordParams,
   CreateWebhookEndpointParams,
   EventsListParams,
   IdempotencyOptions,
@@ -86,11 +87,13 @@ export type {
   PricesListParams,
   RotateProviderCredentialParams,
   SetPortalBrandingParams,
+  SubscriptionsListParams,
   UpdateCouponParams,
   UpdateCustomerParams,
   UpdateProductParams,
   UpdateTaxRateParams,
   UpdateWebhookEndpointParams,
+  UsageRecordsListParams,
   ValidateCouponParams,
 } from "./resources.js";
 export { DEFAULT_RETRY_POLICY, type RetryPolicy } from "./retry.js";

package/src/resources.ts

@@ -34,7 +34,10 @@ import type { QueryValue, Transport } from "./transport.js";
 export interface BaseListParams {
   limit?: number;
   starting_after?: string;
-  ending_before?: string;
+  // Deliberately no `ending_before`: BillKit's cursor pagination binds
+  // `limit` + `starting_after` only (see `api/billkit/api/pagination.py`).
+  // Advertising a backwards cursor the server ignores is worse than not
+  // having one — the request succeeds and silently re-serves page 1.
   readonly [key: string]: QueryValue;
 }
 
@@ -48,6 +51,27 @@ export interface PricesListParams extends BaseListParams {
   product_id?: string;
 }
 
+/**
+ * `subscriptions.list` params. Both filters take a comma-separated
+ * list (`"active,past_due"`); an unrecognised value is rejected with
+ * `400 parameter_invalid` rather than silently ignored.
+ *
+ * The two answer different questions, and mixing them up is the most
+ * common mistake against this route. `status` is where the subscription
+ * stands with its payments. `renewal_state` is what happens at the end
+ * of the current period. A paused subscription keeps `status: "active"`,
+ * because the customer has paid for the period they are in, so
+ * `renewal_state: "paused"` is the only way to find paused ones —
+ * `status: "paused"` is not an accepted value and is rejected.
+ */
+export interface SubscriptionsListParams extends BaseListParams {
+  customer_id?: string;
+  /** `incomplete` | `trialing` | `active` | `past_due` | `canceled`, CSV. */
+  status?: string;
+  /** `auto_renew` | `paused` | `canceling` | `stopped`, CSV. */
+  renewal_state?: string;
+}
+
 /** Optional idempotency knob carried by every mutating call. */
 export interface IdempotencyOptions {
   /** Coalesces retries across process restarts. The SDK generates
@@ -125,6 +149,16 @@ export interface UpdateProductParams extends IdempotencyOptions {
   active?: 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.
+ */
+export interface UpdatePriceParams extends IdempotencyOptions {
+  active: boolean;
+}
+
 export interface CreatePriceParams extends IdempotencyOptions {
   /** Existing Product id returned from `client.products.create`. */
   product_id: string;
@@ -153,6 +187,44 @@ export interface CreatePriceParams extends IdempotencyOptions {
    * regardless of what tax rates exist now or later.
    */
   tax_behavior?: "inclusive" | "exclusive" | "unspecified";
+  /**
+   * `"licensed"` (the default when omitted) bills `amount_cents` per
+   * period regardless of consumption. `"metered"` bills
+   * `amount_cents` **per reported unit**: post consumption with
+   * `subscriptions.createUsageRecord` and the renewal invoice charges
+   * `amount_cents × sum(quantity)` for the period. Metered prices
+   * must be `interval: "month"`, carry `amount_cents > 0`, and cannot
+   * have `trial_days`.
+   */
+  usage_type?: "licensed" | "metered";
+}
+
+/**
+ * Body for `POST /v1/subscriptions/{id}/usage_records`. Only valid
+ * against a subscription whose price is `usage_type: "metered"`; the
+ * server rejects a licensed subscription with `400 parameter_invalid`.
+ */
+export interface CreateUsageRecordParams extends IdempotencyOptions {
+  /** Units consumed, `1..1_000_000`. Post multiple records to accumulate. */
+  quantity: number;
+  /**
+   * Epoch seconds when the consumption happened. Omit to let the
+   * server stamp receipt time. Useful when reporting is batched and
+   * the record must land in the period the usage occurred.
+   */
+  occurred_at?: number;
+  /** Small string metadata map echoed back on the record. */
+  metadata?: Record<string, string>;
+}
+
+/**
+ * `subscriptions.listUsageRecords` params. `invoice_id` filters by
+ * billing state: `"pending"` selects records not yet rolled into an
+ * invoice, and a concrete `inv_...` id selects the records that
+ * invoice billed. Omit it to list everything.
+ */
+export interface UsageRecordsListParams extends BaseListParams {
+  invoice_id?: "pending" | (string & {});
 }
 
 export interface CreateCheckoutSessionParams extends IdempotencyOptions {
@@ -191,6 +263,19 @@ export interface CreateCheckoutSessionParams extends IdempotencyOptions {
    * `0` disables a trial that the price would otherwise grant.
    */
   trial_days_override?: number;
+  /**
+   * `"hosted"` (the default) returns a `url` you redirect the buyer to.
+   * `"embedded"` returns a `client_secret` instead, for
+   * `mountCheckoutElement()` / `<CheckoutElement/>` from
+   * `@billkit-eu/js` — the card fields then render in a cross-origin
+   * iframe on your own page.
+   */
+  ui_mode?: "hosted" | "embedded";
+  /**
+   * Small string map carried onto the session. Up to 50 keys, key ≤ 40
+   * chars, value ≤ 500 chars.
+   */
+  metadata?: Record<string, string>;
 }
 
 export interface CreateRefundParams extends IdempotencyOptions {
@@ -451,6 +536,16 @@ export class Customers extends BaseResource {
     return this.post<T, UpdateCustomerParams>(`/v1/customers/${id}`, params);
   }
 
+  /**
+   * Delete a customer. Resolves to `{ id, object: "customer", deleted:
+   * true }`, not the customer.
+   *
+   * The customer leaves the API: `retrieve()` 404s and they drop out of
+   * `list()`. Their payments, invoices and refunds are untouched, and so
+   * is their personal data — use {@link Customers.purge} for a GDPR
+   * erasure. Refused while they hold a subscription that can still
+   * charge them.
+   */
   delete<T = unknown>(id: string, params: IdempotencyOptions = {}): Promise<T> {
     return this.del<T>(`/v1/customers/${id}`, params);
   }
@@ -497,16 +592,19 @@ export class Products extends BaseResource {
     return this.get<T>(`/v1/products/${id}`);
   }
 
-  /** Patch mutable Product fields. */
+  /**
+   * Patch mutable Product fields, or archive it with `active: false`.
+   *
+   * Archiving is how you stop offering something. The product keeps its
+   * id and still comes back from `retrieve()` and `list()`, because what
+   * was sold under it has to stay readable, so there is no `delete()`.
+   * A checkout against any of its prices is refused from then on, and
+   * `active: true` un-archives.
+   */
   update<T = unknown>(id: string, params: UpdateProductParams): Promise<T> {
     return this.post<T, UpdateProductParams>(`/v1/products/${id}`, params);
   }
 
-  /** Archive a Product. */
-  delete<T = unknown>(id: string, params: IdempotencyOptions = {}): Promise<T> {
-    return this.del<T>(`/v1/products/${id}`, params);
-  }
-
   list<T = unknown>(params: BaseListParams = {}): Promise<ListResponseEnvelope<T>> {
     return this.get<ListResponseEnvelope<T>>("/v1/products", params);
   }
@@ -526,6 +624,30 @@ export class Prices extends BaseResource {
     return this.get<T>(`/v1/prices/${id}`);
   }
 
+  /**
+   * Archive a Price so it stops selling, or put it back on sale.
+   *
+   * `update(id, { active: false })` archives. The price keeps its id and
+   * is still returned by `retrieve()` and by `list()`, because
+   * subscriptions renew against it by id and what they are charged has to
+   * stay readable. Subscriptions already on it keep renewing at it. What
+   * stops is new business: a checkout session against the price is
+   * refused and it is no longer offered as a plan change.
+   *
+   * `{ active: true }` undoes that. `active` is the only field because
+   * `amount_cents`, `currency` and `interval` are fixed at creation, and
+   * since none of them move here neither direction can change what a past
+   * charge was made under. To charge something different, create a new
+   * price.
+   *
+   * Sending the value a price already has returns it unchanged and emits
+   * no second event, so a retry is safe. Archiving emits
+   * `price.archived`; putting one back emits `price.updated`.
+   */
+  update<T = unknown>(id: string, params: UpdatePriceParams): Promise<T> {
+    return this.post<T, UpdatePriceParams>(`/v1/prices/${id}`, params);
+  }
+
   list<T = unknown>(params: PricesListParams = {}): Promise<ListResponseEnvelope<T>> {
     return this.get<ListResponseEnvelope<T>>("/v1/prices", params);
   }
@@ -575,12 +697,33 @@ export class Subscriptions extends BaseResource {
     return this.get<T>(`/v1/subscriptions/${id}`);
   }
 
-  list<T = unknown>(params: BaseListParams = {}): Promise<ListResponseEnvelope<T>> {
+  /**
+   * List subscriptions, newest first, optionally filtered.
+   *
+   * Reach for `renewal_state: "paused"` rather than `status: "paused"`
+   * to find paused subscriptions; see `SubscriptionsListParams`.
+   */
+  list<T = unknown>(params: SubscriptionsListParams = {}): Promise<ListResponseEnvelope<T>> {
     return this.get<ListResponseEnvelope<T>>("/v1/subscriptions", params);
   }
 
-  iter<T = unknown>(options: { pageSize?: number } = {}): AsyncIterableIterator<T> {
-    return paginate<T>((p) => this.get("/v1/subscriptions", p), { pageSize: options.pageSize });
+  /**
+   * Walk every page of `list()`. Filters are carried onto each page
+   * request, so a filtered walk narrows server-side instead of paging
+   * the whole history and discarding rows client-side.
+   */
+  iter<T = unknown>(
+    options: {
+      pageSize?: number;
+      customer_id?: string;
+      status?: string;
+      renewal_state?: string;
+    } = {},
+  ): AsyncIterableIterator<T> {
+    // `undefined` query values are pruned by the transport, so the
+    // filter can be spread as-is without a conditional per key.
+    const { pageSize, ...filter } = options;
+    return paginate<T>((p) => this.get("/v1/subscriptions", { ...filter, ...p }), { pageSize });
   }
 
   cancel<T = unknown>(id: string, params: IdempotencyOptions = {}): Promise<T> {
@@ -634,6 +777,48 @@ export class Subscriptions extends BaseResource {
       { idempotencyKey: params.idempotencyKey },
     );
   }
+
+  /**
+   * Report consumption against a metered subscription.
+   *
+   * Only valid when the subscription's price is `usage_type:
+   * "metered"`; a licensed subscription is rejected with `400
+   * parameter_invalid`. Records accumulate until the renewal invoice
+   * rolls them up (`amount_cents × sum(quantity)`); the record's
+   * `invoice_id` stays `null` until then.
+   *
+   * Supports `Idempotency-Key` replay: retrying with the same key
+   * returns the same record instead of double-counting the usage,
+   * which is what makes at-least-once reporting pipelines safe.
+   */
+  createUsageRecord<T = unknown>(id: string, params: CreateUsageRecordParams): Promise<T> {
+    return this.post<T, CreateUsageRecordParams>(`/v1/subscriptions/${id}/usage_records`, params);
+  }
+
+  /**
+   * List usage records for one subscription.
+   *
+   * Pass `invoice_id: "pending"` to reconcile what has been reported
+   * but not yet billed, or a concrete invoice id to see what that
+   * invoice charged for.
+   */
+  listUsageRecords<T = unknown>(
+    id: string,
+    params: UsageRecordsListParams = {},
+  ): Promise<ListResponseEnvelope<T>> {
+    return this.get<ListResponseEnvelope<T>>(`/v1/subscriptions/${id}/usage_records`, params);
+  }
+
+  /** Walk every page of `listUsageRecords()` for one subscription. */
+  iterUsageRecords<T = unknown>(
+    id: string,
+    options: { pageSize?: number; invoice_id?: string } = {},
+  ): AsyncIterableIterator<T> {
+    return paginate<T>((p) => this.get(`/v1/subscriptions/${id}/usage_records`, p), {
+      pageSize: options.pageSize,
+      filters: { invoice_id: options.invoice_id },
+    });
+  }
 }
 
 export class Refunds extends BaseResource {
@@ -686,15 +871,34 @@ export class WebhookEndpoints extends BaseResource {
     return this.get<T>(`/v1/webhook_endpoints/${id}`);
   }
 
+  /**
+   * Update an endpoint, or stop delivery with `status: "disabled"`.
+   *
+   * Disabling keeps the endpoint, its signing secret and its delivery
+   * history, and `status: "enabled"` resumes. Use {@link
+   * WebhookEndpoints.delete} when the endpoint should not exist at all:
+   * disabling is reversible and deleting is not.
+   */
   update<T = unknown>(id: string, params: UpdateWebhookEndpointParams): Promise<T> {
     return this.post<T, UpdateWebhookEndpointParams>(`/v1/webhook_endpoints/${id}`, params);
   }
 
+  /**
+   * Delete an endpoint. Resolves to `{ id, object: "webhook_endpoint",
+   * deleted: true }`, not the endpoint.
+   *
+   * A URL registered by mistake should not be a permanent fixture of the
+   * account, so this removes it: `retrieve()` 404s afterwards and it is
+   * gone from `list()`. Its delivery attempts go with it, because they
+   * are readable only through the endpoint that owns them. The events
+   * themselves are untouched and still in `client.events`, so what you
+   * were sent stays on record.
+   */
   delete<T = unknown>(id: string, params: IdempotencyOptions = {}): Promise<T> {
     return this.del<T>(`/v1/webhook_endpoints/${id}`, params);
   }
 
-  /** Rotate the signing secret. The new `whsec_...` is returned once. */
+  /** Rotate the signing secret. The new `bkwhsec_...` is returned once. */
   rotateSecret<T = unknown>(id: string, params: IdempotencyOptions = {}): Promise<T> {
     return this.postEmpty<T>(`/v1/webhook_endpoints/${id}/rotate_secret`, params);
   }
@@ -834,14 +1038,18 @@ export class Coupons extends BaseResource {
     return this.get<T>(`/v1/coupons/${id}`);
   }
 
+  /**
+   * Update a coupon's limits, or withdraw it with `active: false`.
+   *
+   * A withdrawn code is refused at checkout while the coupon stays
+   * readable and discounts already applied keep working out, so there is
+   * no `delete()`: a coupon that has been redeemed is part of what a
+   * customer was charged. `active: true` brings the campaign back.
+   */
   update<T = unknown>(id: string, params: UpdateCouponParams): Promise<T> {
     return this.post<T, UpdateCouponParams>(`/v1/coupons/${id}`, params);
   }
 
-  delete<T = unknown>(id: string, params: IdempotencyOptions = {}): Promise<T> {
-    return this.del<T>(`/v1/coupons/${id}`, params);
-  }
-
   /**
    * Server-side dry-run of a coupon redemption.
    *
@@ -876,14 +1084,18 @@ export class TaxRates extends BaseResource {
     return this.get<T>(`/v1/tax_rates/${id}`);
   }
 
+  /**
+   * Correct a rate, retire it with `active: false`, or bring one back.
+   *
+   * Retiring is how you stop charging VAT in a country. The rate stays
+   * readable, because an invoice records the percentage it charged and
+   * you have to be able to point at the rate that produced it, so there
+   * is no `delete()`.
+   */
   update<T = unknown>(id: string, params: UpdateTaxRateParams): Promise<T> {
     return this.post<T, UpdateTaxRateParams>(`/v1/tax_rates/${id}`, params);
   }
 
-  delete<T = unknown>(id: string, params: IdempotencyOptions = {}): Promise<T> {
-    return this.del<T>(`/v1/tax_rates/${id}`, params);
-  }
-
   list<T = unknown>(params: BaseListParams = {}): Promise<ListResponseEnvelope<T>> {
     return this.get<ListResponseEnvelope<T>>("/v1/tax_rates", params);
   }
@@ -897,15 +1109,36 @@ export class TaxRates extends BaseResource {
  * 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.
+ * them directly. Fetch the rendered document with
+ * {@link Invoices.retrievePdf}.
  */
 export class Invoices extends BaseResource {
   retrieve<T = unknown>(id: string): Promise<T> {
     return this.get<T>(`/v1/invoices/${id}`);
   }
 
+  /**
+   * Download the rendered invoice PDF as raw bytes.
+   *
+   * ```ts
+   * const pdf = await client.invoices.retrievePdf("inv_123");
+   * await writeFile("invoice.pdf", Buffer.from(pdf));
+   * ```
+   *
+   * Blob-backed deployments stream the bytes inline; S3-backed ones
+   * answer `302` to a presigned URL, which `fetch` follows for us under
+   * the SDK's own timeout and retry policy — so both storage adapters
+   * look identical from here.
+   *
+   * Deployments with `INVOICE_PDF_ENABLED=false` never render one and
+   * answer `501 rendering_pending`, which surfaces as a `ServerError`
+   * whose `code` is `"rendering_pending"`; `retrieve()` still returns the
+   * structured invoice for tenants who render their own.
+   */
+  retrievePdf(id: string): Promise<ArrayBuffer> {
+    return this.t.requestBinary({ method: "GET", path: `/v1/invoices/${id}/pdf` });
+  }
+
   list<T = unknown>(params: BaseListParams = {}): Promise<ListResponseEnvelope<T>> {
     return this.get<ListResponseEnvelope<T>>("/v1/invoices", params);
   }

package/src/retry.ts

@@ -2,9 +2,12 @@
  * 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.
+ * 4xx are caller-fault and never retried, with one deliberate
+ * exception: `409 idempotency_in_progress`. See
+ * {@link IN_PROGRESS_CODE}.
+ *
+ * The SDK auto-generates an `Idempotency-Key` for every mutating call
+ * and reuses it across attempts, so retrying never double-charges.
  */
 
 export interface RetryPolicy {
@@ -37,14 +40,39 @@ export function backoffForMs(attempt: number, policy: RetryPolicy): number {
   return Math.max(0, jittered);
 }
 
+/**
+ * The one 409 error code that is transient rather than caller-fault.
+ *
+ * The server returns it when a request carrying the *same*
+ * `Idempotency-Key` is still in flight ("Retry after a short delay",
+ * `Retry-After: 1`). It is the only 4xx where doing nothing is the
+ * dangerous option: the call may well have charged the customer, the
+ * caller cannot see the outcome, and the obvious workaround — retry
+ * with a *fresh* key — is precisely what turns one charge into two.
+ *
+ * Retrying is safe because the transport reuses the original
+ * `Idempotency-Key` on every attempt, so the retry either loses the
+ * race again or replays the first call's recorded response.
+ */
+export const IN_PROGRESS_CODE = "idempotency_in_progress";
+
 export function shouldRetry(
   status: number | null,
   attempt: number,
   policy: RetryPolicy,
   retryAfterMs?: number,
+  /**
+   * `error.code` from the parsed response envelope, when there was one.
+   * Only consulted for 409s; every other decision is status-driven.
+   */
+  errorCode?: string,
 ): boolean {
   if (attempt >= policy.maxAttempts) return false;
   if (status === null) return true; // network error
+  // A 409 from a *different* code (`idempotency_key_in_use`, a
+  // conflicting subscription state) is a genuine caller-fault conflict
+  // that retrying can only repeat, so it still fails fast.
+  if (status === 409) return errorCode === IN_PROGRESS_CODE;
   if (status === 429) {
     // 429 is retried only when the server supplies a short, parseable
     // Retry-After value; otherwise we surface the exception so the