@billkit-eu/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -65,9 +65,12 @@ 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.
+ * 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.
  */
 interface RetryPolicy {
     readonly maxAttempts: number;
@@ -98,6 +101,14 @@ interface RequestOptions {
     body?: Record<string, unknown> | undefined;
     idempotencyKey?: string | undefined;
     extraHeaders?: Record<string, string>;
+    /**
+     * How to read a **successful** response body. `"json"` (the default)
+     * parses it; `"binary"` hands back the raw `ArrayBuffer`, for
+     * endpoints that serve a document rather than a resource (the invoice
+     * PDF). Error responses are always read as JSON either way, so the
+     * typed error hierarchy behaves identically on both paths.
+     */
+    responseType?: "json" | "binary";
 }
 interface TransportConfig {
     apiKey: string;
@@ -122,6 +133,17 @@ declare class Transport {
     private readonly fetchFn;
     private readonly logger;
     constructor(config: TransportConfig);
+    /**
+     * Fetch a binary document (currently only the invoice PDF).
+     *
+     * Same retry policy, same timeout, same typed errors as
+     * {@link Transport.request}; only the success-path decoding differs.
+     * `fetch` follows the storage adapter's `302` to the signed URL by
+     * itself, and the WHATWG spec drops the `Authorization` header on that
+     * cross-origin hop — which is correct, since a presigned URL carries
+     * its own credential and must not be handed BillKit's API key.
+     */
+    requestBinary(options: Omit<RequestOptions, "responseType">): Promise<ArrayBuffer>;
     request<T = unknown>(options: RequestOptions): Promise<T>;
 }
 
@@ -203,7 +225,6 @@ declare function paginate<T>(listFn: ListFn<T>, options?: PaginateOptions): Asyn
 interface BaseListParams {
     limit?: number;
     starting_after?: string;
-    ending_before?: string;
     readonly [key: string]: QueryValue;
 }
 /**
@@ -215,6 +236,26 @@ interface BaseListParams {
 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.
+ */
+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. */
 interface IdempotencyOptions {
     /** Coalesces retries across process restarts. The SDK generates
@@ -274,6 +315,15 @@ interface UpdateProductParams extends IdempotencyOptions {
     /** Set false to stop selling a product without deleting history. */
     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.
+ */
+interface UpdatePriceParams extends IdempotencyOptions {
+    active: boolean;
+}
 interface CreatePriceParams extends IdempotencyOptions {
     /** Existing Product id returned from `client.products.create`. */
     product_id: string;
@@ -302,6 +352,42 @@ 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`.
+ */
+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.
+ */
+interface UsageRecordsListParams extends BaseListParams {
+    invoice_id?: "pending" | (string & {});
 }
 interface CreateCheckoutSessionParams extends IdempotencyOptions {
     /**
@@ -339,6 +425,19 @@ 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>;
 }
 interface CreateRefundParams extends IdempotencyOptions {
     payment_id?: string;
@@ -518,6 +617,16 @@ declare class Customers extends BaseResource {
     create<T = unknown>(params?: CreateCustomerParams): Promise<T>;
     retrieve<T = unknown>(id: string): Promise<T>;
     update<T = unknown>(id: string, params?: UpdateCustomerParams): Promise<T>;
+    /**
+     * 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>;
     list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
     /** Walk every page of `list()` and yield each customer. */
@@ -544,10 +653,16 @@ 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. */
+    /**
+     * 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>;
-    /** 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;
@@ -557,6 +672,27 @@ 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>;
+    /**
+     * 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>;
     list<T = unknown>(params?: PricesListParams): Promise<ListResponseEnvelope<T>>;
     iter<T = unknown>(options?: {
         pageSize?: number;
@@ -583,9 +719,23 @@ declare class OneShotPayments extends BaseResource {
 }
 declare class Subscriptions extends BaseResource {
     retrieve<T = unknown>(id: string): Promise<T>;
-    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>>;
+    /**
+     * 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>;
     cancel<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
     pause<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
@@ -608,6 +758,33 @@ declare class Subscriptions extends BaseResource {
     reauthorizePaymentMethod<T = unknown>(id: string, params: {
         return_url: string;
     } & IdempotencyOptions): Promise<T>;
+    /**
+     * 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>;
+    /**
+     * 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>>;
+    /** Walk every page of `listUsageRecords()` for one subscription. */
+    iterUsageRecords<T = unknown>(id: string, options?: {
+        pageSize?: number;
+        invoice_id?: string;
+    }): AsyncIterableIterator<T>;
 }
 declare class Refunds extends BaseResource {
     create<T = unknown>(params: CreateRefundParams): Promise<T>;
@@ -636,7 +813,26 @@ declare class Disputes extends BaseResource {
 declare class WebhookEndpoints extends BaseResource {
     create<T = unknown>(params: CreateWebhookEndpointParams): Promise<T>;
     retrieve<T = unknown>(id: string): Promise<T>;
+    /**
+     * 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>;
+    /**
+     * 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>;
     /** Rotate the signing secret. The new `whsec_...` is returned once. */
     rotateSecret<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
@@ -708,8 +904,15 @@ declare class Tenant extends BaseResource {
 declare class Coupons extends BaseResource {
     create<T = unknown>(params: CreateCouponParams): Promise<T>;
     retrieve<T = unknown>(id: string): Promise<T>;
+    /**
+     * 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>;
-    delete<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
     /**
      * Server-side dry-run of a coupon redemption.
      *
@@ -725,8 +928,15 @@ declare class Coupons extends BaseResource {
 declare class TaxRates extends BaseResource {
     create<T = unknown>(params: CreateTaxRateParams): Promise<T>;
     retrieve<T = unknown>(id: string): Promise<T>;
+    /**
+     * 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>;
-    delete<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
     list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
     iter<T = unknown>(options?: {
         pageSize?: number;
@@ -736,12 +946,30 @@ declare 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}.
  */
 declare class Invoices extends BaseResource {
     retrieve<T = unknown>(id: string): Promise<T>;
+    /**
+     * 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>;
     list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
     iter<T = unknown>(options?: {
         pageSize?: number;
@@ -876,7 +1104,7 @@ declare class RateLimitError extends BillKitError {
     });
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.2.0";
 
 /**
  * Verify `BillKit-Signature: t=<unix>,v1=<hex>` headers.
@@ -908,4 +1136,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 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 };
+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, 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 SubscriptionsListParams, type UpdateCouponParams, type UpdateCustomerParams, type UpdateProductParams, type UpdateTaxRateParams, type UpdateWebhookEndpointParams, type UsageRecordsListParams, VERSION, type ValidateCouponParams, type VerifyWebhookOptions, WebhookVerificationError, paginate, verifyWebhookSignature };