@usebillow/sdk 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @usebillow/sdk
 
+## 0.10.0
+
+### Minor Changes
+
+- 935c12d: Included credits now follow plan changes and early endings. A plan upgrade inside the period raises its current and later Included Credit Windows to the new plan's rule (a high-water mark, never lowered), and the difference is issued at once as an `included` grant with ledger reason `subscription_upgrade`; `CreditIncludedWindow` gains `raisedAt`, when an upgrade last raised the window. An immediate cancellation, or a lost chargeback of the payment for the period, ends the period's unspent included credits and its later refills: the window reads `ended` with its `endedAt` and `endCause` (`canceled` or `charged_back`), and the grant's unheld credits expire with ledger reason `subscription_canceled` or `subscription_charged_back`. The `credit_grant.expired` webhook data's `reason` is now `grant_expired`, `subscription_canceled` or `subscription_charged_back`.
+- a41c39f: `BillowApiError.retryAfterSeconds` says how many seconds to wait before trying again, read from the response's `Retry-After` header: whole seconds, or an HTTP date (`Sun, 06 Nov 1994 08:49:37 GMT`) counted from now, at most an hour. billow sends it with a `429 rate_limited`; it is undefined when the response did not say, or said something that is neither. With `maxRetries` set, the SDK already waited between attempts (now at most an hour, however long the header asks); a caller that does not retry can now tell its user when to try again.
+
+### Patch Changes
+
+- a41c39f: Usage line descriptions count their units in words: `Usage - 1 unit over allowance` or `Usage - 7 units over allowance` (and `Usage - api: 7 units over allowance (2026-03-01 - 2026-04-01)` for a reset window) instead of `unit(s)`. This is the text of an invoice's usage `lineItems` from `invoices.get`, and of an invoice's `reason` (its first line) from `invoices.list` and the portal's `invoices.list` and `invoices.get` when that line is a usage line. Invoices issued before keep the descriptions they were issued with. No SDK code changed.
+
+## 0.9.0
+
+### Minor Changes
+
+- 598ec24: Included credits are now issued: each period Billow grants a subscription on a Price with an Included Credit Rule records its Included Credit Windows and issues them as `included` grants. New `credits.includedWindows.list` reads them - for one or more subscriptions (`subscription`, an id or a list) or a customer (`customer`), newest first, auto-paginating by cursor, with `current: true` for each subscription's latest started window - each with its bounds and its billing period's, `nextRefillAt`, `entitled`, `issued` and a `state` (`scheduled`, `pending`, `blocked` with its `blockedCause`, `issued`, `suspended`, `lapsed`, `ended` or `account_closed`). `CreditBalance` gains `includedPeriods` (each subscription's current window, with `periodStart`, `periodEnd` and `nextRefillAt`), and its `currentPeriod` now describes the current windows (its `end` is always set). `CreditLedgerEntry` gains `subscriptionId`. The `credit_grant.created` webhook data gains `subscriptionId`, `periodStart` and `periodEnd`, and `credit_grant.expired` gains `reason`. The data export's credits gain `includedWindows`. New types: `CreditIncludedWindow`, `CreditIncludedWindowListParams`, `CreditWindowState`, `IncludedCredits` and `IncludedPeriod`.
+
+### Patch Changes
+
+- 8d2c420: Invoice lines and a product's prices and entitlements always come back in a stable order. `invoices.get` lists an invoice's `lineItems` in the order the invoice lists them (as its PDF and receipt email do), and a product's `prices` and `entitlements` come back in the order they were given to `products.create` or last to `products.update`; an invoice's usage lines follow the price order too. The customer data export lists each invoice's lines in order and carries each line's `position`.
+- 2b175c1: Document `subscriptions.pause` and `subscriptions.resume`. Paused time is never billed: usage recorded while a subscription is paused is never invoiced. A subscription resumed before its paid period ends carries on and renews at `currentPeriodEnd`; one resumed after it ended starts a fresh full period at the moment of resume and is charged for it at once, like a renewal, together with the ended period's usage (a declined charge returns it `past_due`). A paused trial resumes `trialing`. Resuming an already active or trialing subscription changes nothing; resuming one that is `past_due` or `unpaid` is refused. Pause, resume, plan, item and coupon changes are refused while one of the subscription's invoices is still being collected.
+
 ## 0.8.0
 
 ### Minor Changes

package/dist/{billing-B-VyZCXV.d.cts → billing-8ug1Gw05.d.cts}

@@ -1,5 +1,5 @@
-import { A as ActivatedSubscriptionResponse, C as CreateSubscriptionResponse, P as PendingSubscriptionCheckoutResponse, a as ProductResponse, b as ProductEntitlementResponse, c as ProductPriceResponse, S as SubscriptionResponse, d as SubscriptionDetailResponse, e as SubscriptionItemResponse } from './index.d-CKQAhQfJ.cjs';
-import { C as ChargeStatus } from './billing-status-BZQN_gm7.cjs';
+import { A as ActivatedSubscriptionResponse, C as CreateSubscriptionResponse, P as PendingSubscriptionCheckoutResponse, a as ProductResponse, b as ProductEntitlementResponse, c as ProductPriceResponse, S as SubscriptionResponse, d as SubscriptionDetailResponse, e as SubscriptionItemResponse } from './index.d-DSEYhV2c.cjs';
+import { C as ChargeStatus } from './billing-status-DZkB0VPK.cjs';
 
 /** Public SDK types for this domain. Re-exported by ../types.ts. */
 interface BillowOptions {
@@ -16,14 +16,14 @@ interface BillowOptions {
      */
     timeoutMs?: number;
     /**
-     * How many times to retry a transient failure. Retries are **opt-in** — the default is
+     * How many times to retry a transient failure. Retries are **opt-in** - the default is
      * `0`. Only requests that are safe to repeat are retried: every `GET`, plus **any** method
      * on a `429` (a rate-limited request never executed). A write (`POST`/`PATCH`/`DELETE`) is
      * never retried on a `5xx`/network error, since it may have already applied.
      */
     maxRetries?: number;
     /**
-     * Base backoff in milliseconds between retries — exponential (`base × 2^attempt`), and a
+     * Base backoff in milliseconds between retries - exponential (`base × 2^attempt`), and a
      * `Retry-After` response header takes precedence when present. Defaults to 500.
      */
     retryBackoffMs?: number;
@@ -32,7 +32,7 @@ interface BillowOptions {
  * Per-call overrides passed as the last argument to a resource method.
  * - `signal` cancels the request (a caller abort is surfaced immediately and never retried).
  * - `timeoutMs` overrides the client's default timeout for this call (applied per attempt).
- * - `idempotencyKey` sends an `Idempotency-Key` and makes the write **safe to retry** — reused
+ * - `idempotencyKey` sends an `Idempotency-Key` and makes the write **safe to retry** - reused
  *   verbatim on every attempt. Only exposed on writes the server replays (create/attach/track/refund).
  */
 interface RequestOptions {
@@ -44,7 +44,7 @@ interface RequestOptions {
 type IdempotentRequestOptions = RequestOptions & {
     idempotencyKey: string;
 };
-/** Per-call overrides for reads and non-replayable writes — cancellation + timeout, no idempotency key. */
+/** Per-call overrides for reads and non-replayable writes - cancellation + timeout, no idempotency key. */
 type CallOptions = Omit<RequestOptions, "idempotencyKey">;
 interface Customer {
     id: string;
@@ -77,7 +77,7 @@ interface MeterFilter {
     key: string;
     values: string[];
 }
-/** A meter's measurement config (ADR-0011) — how a metered feature's usage aggregates. */
+/** A meter's measurement config (ADR-0011) - how a metered feature's usage aggregates. */
 interface MeterConfig {
     aggregation: MeterAggregation;
     eventProperty?: string | null;
@@ -142,7 +142,9 @@ interface CreateProductInput {
     isAddOn?: boolean;
     /** Free-form string map that round-trips on the product + on subscription.* webhooks. */
     metadata?: Record<string, string>;
+    /** In the order the product lists them: every read of it, and an invoice's usage lines, keep it. */
     prices: PriceInput[];
+    /** In the order the product lists them: every read of it keeps it. */
     entitlements?: EntitlementInput[];
 }
 /** A price in a product edit: carry `id` to update that row in place, omit it to add. */
@@ -169,7 +171,9 @@ interface UpdateProductInput {
     archived?: boolean;
     /** Replace the product's metadata map. */
     metadata?: Record<string, string>;
+    /** The product's whole price list, in the order it lists them from now on. */
     prices?: UpdatePriceInput[];
+    /** The product's whole entitlement list, in the order it lists them from now on. */
     entitlements?: EntitlementInput[];
 }
 interface Feature {
@@ -182,7 +186,7 @@ interface Feature {
 }
 /**
  * An in-place edit to a feature. `name` is always allowed; `meter` re-configures a
- * metered feature's aggregation — but the server refuses a meter change once usage has
+ * metered feature's aggregation - but the server refuses a meter change once usage has
  * been recorded (it would rewrite billed history). At least one field must be present.
  */
 interface UpdateFeatureInput {
@@ -217,7 +221,7 @@ interface CreateUsageAlertInput {
 }
 interface TrackResult {
     ok: true;
-    /** True when the idempotency key was already seen — the call was a no-op. */
+    /** True when the idempotency key was already seen - the call was a no-op. */
     deduplicated: boolean;
     /** Remaining balance for the feature; `null` if unlimited. */
     balance: number | null;
@@ -234,7 +238,7 @@ type Product = ProductResponse;
 type Subscription = SubscriptionResponse;
 /** A single fetched subscription (`subscriptions.get`) - {@link Subscription} plus the stable `customerExternalId` + `productSlug`. */
 type SubscriptionDetail = SubscriptionDetailResponse;
-/** A subscription line item — the base plan or an attached add-on (Phase D2). */
+/** A subscription line item - the base plan or an attached add-on (Phase D2). */
 type SubscriptionItem = SubscriptionItemResponse;
 interface CreateSubscriptionInput {
     customerId: string;

package/dist/{billing-CgjcWmvb.d.ts → billing-Bs10EcjR.d.ts}

@@ -1,5 +1,5 @@
-import { A as ActivatedSubscriptionResponse, C as CreateSubscriptionResponse, P as PendingSubscriptionCheckoutResponse, a as ProductResponse, b as ProductEntitlementResponse, c as ProductPriceResponse, S as SubscriptionResponse, d as SubscriptionDetailResponse, e as SubscriptionItemResponse } from './index.d-CKQAhQfJ.js';
-import { C as ChargeStatus } from './billing-status-BZQN_gm7.js';
+import { A as ActivatedSubscriptionResponse, C as CreateSubscriptionResponse, P as PendingSubscriptionCheckoutResponse, a as ProductResponse, b as ProductEntitlementResponse, c as ProductPriceResponse, S as SubscriptionResponse, d as SubscriptionDetailResponse, e as SubscriptionItemResponse } from './index.d-DSEYhV2c.js';
+import { C as ChargeStatus } from './billing-status-DZkB0VPK.js';
 
 /** Public SDK types for this domain. Re-exported by ../types.ts. */
 interface BillowOptions {
@@ -16,14 +16,14 @@ interface BillowOptions {
      */
     timeoutMs?: number;
     /**
-     * How many times to retry a transient failure. Retries are **opt-in** — the default is
+     * How many times to retry a transient failure. Retries are **opt-in** - the default is
      * `0`. Only requests that are safe to repeat are retried: every `GET`, plus **any** method
      * on a `429` (a rate-limited request never executed). A write (`POST`/`PATCH`/`DELETE`) is
      * never retried on a `5xx`/network error, since it may have already applied.
      */
     maxRetries?: number;
     /**
-     * Base backoff in milliseconds between retries — exponential (`base × 2^attempt`), and a
+     * Base backoff in milliseconds between retries - exponential (`base × 2^attempt`), and a
      * `Retry-After` response header takes precedence when present. Defaults to 500.
      */
     retryBackoffMs?: number;
@@ -32,7 +32,7 @@ interface BillowOptions {
  * Per-call overrides passed as the last argument to a resource method.
  * - `signal` cancels the request (a caller abort is surfaced immediately and never retried).
  * - `timeoutMs` overrides the client's default timeout for this call (applied per attempt).
- * - `idempotencyKey` sends an `Idempotency-Key` and makes the write **safe to retry** — reused
+ * - `idempotencyKey` sends an `Idempotency-Key` and makes the write **safe to retry** - reused
  *   verbatim on every attempt. Only exposed on writes the server replays (create/attach/track/refund).
  */
 interface RequestOptions {
@@ -44,7 +44,7 @@ interface RequestOptions {
 type IdempotentRequestOptions = RequestOptions & {
     idempotencyKey: string;
 };
-/** Per-call overrides for reads and non-replayable writes — cancellation + timeout, no idempotency key. */
+/** Per-call overrides for reads and non-replayable writes - cancellation + timeout, no idempotency key. */
 type CallOptions = Omit<RequestOptions, "idempotencyKey">;
 interface Customer {
     id: string;
@@ -77,7 +77,7 @@ interface MeterFilter {
     key: string;
     values: string[];
 }
-/** A meter's measurement config (ADR-0011) — how a metered feature's usage aggregates. */
+/** A meter's measurement config (ADR-0011) - how a metered feature's usage aggregates. */
 interface MeterConfig {
     aggregation: MeterAggregation;
     eventProperty?: string | null;
@@ -142,7 +142,9 @@ interface CreateProductInput {
     isAddOn?: boolean;
     /** Free-form string map that round-trips on the product + on subscription.* webhooks. */
     metadata?: Record<string, string>;
+    /** In the order the product lists them: every read of it, and an invoice's usage lines, keep it. */
     prices: PriceInput[];
+    /** In the order the product lists them: every read of it keeps it. */
     entitlements?: EntitlementInput[];
 }
 /** A price in a product edit: carry `id` to update that row in place, omit it to add. */
@@ -169,7 +171,9 @@ interface UpdateProductInput {
     archived?: boolean;
     /** Replace the product's metadata map. */
     metadata?: Record<string, string>;
+    /** The product's whole price list, in the order it lists them from now on. */
     prices?: UpdatePriceInput[];
+    /** The product's whole entitlement list, in the order it lists them from now on. */
     entitlements?: EntitlementInput[];
 }
 interface Feature {
@@ -182,7 +186,7 @@ interface Feature {
 }
 /**
  * An in-place edit to a feature. `name` is always allowed; `meter` re-configures a
- * metered feature's aggregation — but the server refuses a meter change once usage has
+ * metered feature's aggregation - but the server refuses a meter change once usage has
  * been recorded (it would rewrite billed history). At least one field must be present.
  */
 interface UpdateFeatureInput {
@@ -217,7 +221,7 @@ interface CreateUsageAlertInput {
 }
 interface TrackResult {
     ok: true;
-    /** True when the idempotency key was already seen — the call was a no-op. */
+    /** True when the idempotency key was already seen - the call was a no-op. */
     deduplicated: boolean;
     /** Remaining balance for the feature; `null` if unlimited. */
     balance: number | null;
@@ -234,7 +238,7 @@ type Product = ProductResponse;
 type Subscription = SubscriptionResponse;
 /** A single fetched subscription (`subscriptions.get`) - {@link Subscription} plus the stable `customerExternalId` + `productSlug`. */
 type SubscriptionDetail = SubscriptionDetailResponse;
-/** A subscription line item — the base plan or an attached add-on (Phase D2). */
+/** A subscription line item - the base plan or an attached add-on (Phase D2). */
 type SubscriptionItem = SubscriptionItemResponse;
 interface CreateSubscriptionInput {
     customerId: string;

package/dist/{billing-status-BZQN_gm7.d.cts → billing-status-DZkB0VPK.d.cts}

@@ -5,21 +5,21 @@
  * against it (see billing-status.test.ts); webhook-delivery status is a free-text column
  * server-side with a fixed vocabulary, documented here.
  */
-/** A charge's lifecycle status — mirrors `@billow/core` `CHARGE_STATUSES`. */
+/** A charge's lifecycle status - mirrors `@billow/core` `CHARGE_STATUSES`. */
 declare const CHARGE_STATUSES: readonly ["pending", "processing", "succeeded", "failed", "requires_reconciliation", "disputed"];
 type ChargeStatus = (typeof CHARGE_STATUSES)[number];
-/** An invoice's lifecycle status — mirrors `@billow/core` `INVOICE_STATUSES`. */
+/** An invoice's lifecycle status - mirrors `@billow/core` `INVOICE_STATUSES`. */
 declare const INVOICE_STATUSES: readonly ["draft", "open", "paid", "uncollectible", "void"];
 type InvoiceStatus = (typeof INVOICE_STATUSES)[number];
-/** A refund's lifecycle status — mirrors `@billow/core` `REFUND_STATUSES`. */
+/** A refund's lifecycle status - mirrors `@billow/core` `REFUND_STATUSES`. */
 declare const REFUND_STATUSES: readonly ["pending", "succeeded", "failed"];
 type RefundStatus = (typeof REFUND_STATUSES)[number];
-/** A saved payment method's status — mirrors `@billow/core` `PAYMENT_METHOD_STATUSES`. */
+/** A saved payment method's status - mirrors `@billow/core` `PAYMENT_METHOD_STATUSES`. */
 declare const PAYMENT_METHOD_STATUSES: readonly ["active", "expired", "removed"];
 type PaymentMethodStatus = (typeof PAYMENT_METHOD_STATUSES)[number];
 /**
  * A webhook delivery attempt's status. Not a DB enum (a free-text column); the dispatcher
- * inserts one row per attempt with exactly `delivered` (a 2xx) or `failed` (anything else) —
+ * inserts one row per attempt with exactly `delivered` (a 2xx) or `failed` (anything else) -
  * see `packages/server/src/jobs/outbox.ts`. (Retry/backoff state lives on the outbox event,
  * a separate table, not on the delivery record.)
  */

package/dist/{billing-status-BZQN_gm7.d.ts → billing-status-DZkB0VPK.d.ts}

@@ -5,21 +5,21 @@
  * against it (see billing-status.test.ts); webhook-delivery status is a free-text column
  * server-side with a fixed vocabulary, documented here.
  */
-/** A charge's lifecycle status — mirrors `@billow/core` `CHARGE_STATUSES`. */
+/** A charge's lifecycle status - mirrors `@billow/core` `CHARGE_STATUSES`. */
 declare const CHARGE_STATUSES: readonly ["pending", "processing", "succeeded", "failed", "requires_reconciliation", "disputed"];
 type ChargeStatus = (typeof CHARGE_STATUSES)[number];
-/** An invoice's lifecycle status — mirrors `@billow/core` `INVOICE_STATUSES`. */
+/** An invoice's lifecycle status - mirrors `@billow/core` `INVOICE_STATUSES`. */
 declare const INVOICE_STATUSES: readonly ["draft", "open", "paid", "uncollectible", "void"];
 type InvoiceStatus = (typeof INVOICE_STATUSES)[number];
-/** A refund's lifecycle status — mirrors `@billow/core` `REFUND_STATUSES`. */
+/** A refund's lifecycle status - mirrors `@billow/core` `REFUND_STATUSES`. */
 declare const REFUND_STATUSES: readonly ["pending", "succeeded", "failed"];
 type RefundStatus = (typeof REFUND_STATUSES)[number];
-/** A saved payment method's status — mirrors `@billow/core` `PAYMENT_METHOD_STATUSES`. */
+/** A saved payment method's status - mirrors `@billow/core` `PAYMENT_METHOD_STATUSES`. */
 declare const PAYMENT_METHOD_STATUSES: readonly ["active", "expired", "removed"];
 type PaymentMethodStatus = (typeof PAYMENT_METHOD_STATUSES)[number];
 /**
  * A webhook delivery attempt's status. Not a DB enum (a free-text column); the dispatcher
- * inserts one row per attempt with exactly `delivered` (a 2xx) or `failed` (anything else) —
+ * inserts one row per attempt with exactly `delivered` (a 2xx) or `failed` (anything else) -
  * see `packages/server/src/jobs/outbox.ts`. (Retry/backoff state lives on the outbox event,
  * a separate table, not on the delivery record.)
  */

package/dist/{chunk-CCG4F5FK.js → chunk-47J7FYM5.js}

@@ -44,5 +44,5 @@ function isTerminal(status) {
 }
 
 export { ACTIVE_SUBSCRIPTION_STATUSES, CHARGE_STATUSES, INVOICE_STATUSES, NEVER_ACTIVATED_SUBSCRIPTION_STATUSES, PAYMENT_METHOD_STATUSES, REFUND_STATUSES, SUBSCRIPTION_STATUSES, TERMINAL_SUBSCRIPTION_STATUSES, WEBHOOK_DELIVERY_STATUSES, grantsAccess, isTerminal };
-//# sourceMappingURL=chunk-CCG4F5FK.js.map
-//# sourceMappingURL=chunk-CCG4F5FK.js.map
+//# sourceMappingURL=chunk-47J7FYM5.js.map
+//# sourceMappingURL=chunk-47J7FYM5.js.map

package/dist/chunk-47J7FYM5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/billing-status.ts","../src/subscription-status.ts"],"names":[],"mappings":";AASO,IAAM,eAAA,GAAkB;AAAA,EAC7B,SAAA;AAAA,EACA,YAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,yBAAA;AAAA,EACA;AACF;AAIO,IAAM,mBAAmB,CAAC,OAAA,EAAS,MAAA,EAAQ,MAAA,EAAQ,iBAAiB,MAAM;AAI1E,IAAM,eAAA,GAAkB,CAAC,SAAA,EAAW,WAAA,EAAa,QAAQ;AAIzD,IAAM,uBAAA,GAA0B,CAAC,QAAA,EAAU,SAAA,EAAW,SAAS;AAS/D,IAAM,yBAAA,GAA4B,CAAC,WAAA,EAAa,QAAQ;;;ACxBxD,IAAM,qBAAA,GAAwB;AAAA,EACnC,YAAA;AAAA,EACA,oBAAA;AAAA,EACA,UAAA;AAAA,EACA,QAAA;AAAA,EACA,UAAA;AAAA,EACA,QAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF;AAQO,IAAM,4BAAA,GAA8D;AAAA,EACzE,UAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF;AAGO,IAAM,8BAAA,GAAgE;AAAA,EAC3E,oBAAA;AAAA,EACA;AACF;AAGO,IAAM,qCAAA,GAAuE;AAAA,EAClF,YAAA;AAAA,EACA;AACF;AAGO,SAAS,aAAa,MAAA,EAAqC;AAChE,EAAA,OAAO,4BAAA,CAA6B,SAAS,MAAM,CAAA;AACrD;AAGO,SAAS,WAAW,MAAA,EAAqC;AAC9D,EAAA,OAAO,8BAAA,CAA+B,SAAS,MAAM,CAAA;AACvD","file":"chunk-47J7FYM5.js","sourcesContent":["/**\n * Charge / invoice / refund / payment-method / webhook-delivery status vocabularies,\n * mirrored for the SDK (which cannot import the server-side `@billow/core`). The DB-enum\n * ones (charge, invoice, refund, payment method) mirror core enums and are parity-tested\n * against it (see billing-status.test.ts); webhook-delivery status is a free-text column\n * server-side with a fixed vocabulary, documented here.\n */\n\n/** A charge's lifecycle status - mirrors `@billow/core` `CHARGE_STATUSES`. */\nexport const CHARGE_STATUSES = [\n  \"pending\",\n  \"processing\",\n  \"succeeded\",\n  \"failed\",\n  \"requires_reconciliation\",\n  \"disputed\",\n] as const;\nexport type ChargeStatus = (typeof CHARGE_STATUSES)[number];\n\n/** An invoice's lifecycle status - mirrors `@billow/core` `INVOICE_STATUSES`. */\nexport const INVOICE_STATUSES = [\"draft\", \"open\", \"paid\", \"uncollectible\", \"void\"] as const;\nexport type InvoiceStatus = (typeof INVOICE_STATUSES)[number];\n\n/** A refund's lifecycle status - mirrors `@billow/core` `REFUND_STATUSES`. */\nexport const REFUND_STATUSES = [\"pending\", \"succeeded\", \"failed\"] as const;\nexport type RefundStatus = (typeof REFUND_STATUSES)[number];\n\n/** A saved payment method's status - mirrors `@billow/core` `PAYMENT_METHOD_STATUSES`. */\nexport const PAYMENT_METHOD_STATUSES = [\"active\", \"expired\", \"removed\"] as const;\nexport type PaymentMethodStatus = (typeof PAYMENT_METHOD_STATUSES)[number];\n\n/**\n * A webhook delivery attempt's status. Not a DB enum (a free-text column); the dispatcher\n * inserts one row per attempt with exactly `delivered` (a 2xx) or `failed` (anything else) -\n * see `packages/server/src/jobs/outbox.ts`. (Retry/backoff state lives on the outbox event,\n * a separate table, not on the delivery record.)\n */\nexport const WEBHOOK_DELIVERY_STATUSES = [\"delivered\", \"failed\"] as const;\nexport type WebhookDeliveryStatus = (typeof WEBHOOK_DELIVERY_STATUSES)[number];\n","/**\n * The subscription status vocabulary + access predicate, mirrored from @billow/core\n * (`enums.ts` + `billing/subscription-state.ts`) so SDK consumers can type and branch on\n * billow's own model instead of hand-maintaining a union that drifts (a real bug: an app\n * copy once carried a non-existent `ended` status - that string is a webhook event type,\n * not a subscription status).\n *\n * Mirrored, not imported: @billow/core is a server package the published SDK cannot depend\n * on (the same reason @billow/contracts mirrors core's pure logic). The parity test\n * `subscription-status.test.ts` imports @billow/core and fails CI on any drift.\n */\n\n/** The 8 canonical subscription statuses, in lifecycle order. */\nexport const SUBSCRIPTION_STATUSES = [\n  \"incomplete\",\n  \"incomplete_expired\",\n  \"trialing\",\n  \"active\",\n  \"past_due\",\n  \"paused\",\n  \"canceled\",\n  \"unpaid\",\n] as const;\n\nexport type SubscriptionStatus = (typeof SUBSCRIPTION_STATUSES)[number];\n\n/**\n * Statuses that currently grant access (a live commitment): `trialing`, `active`, and\n * `past_due` (access is retained through dunning). Note `paused` does NOT grant access.\n */\nexport const ACTIVE_SUBSCRIPTION_STATUSES: readonly SubscriptionStatus[] = [\n  \"trialing\",\n  \"active\",\n  \"past_due\",\n];\n\n/** Statuses a subscription can never leave: `incomplete_expired` and `canceled`. */\nexport const TERMINAL_SUBSCRIPTION_STATUSES: readonly SubscriptionStatus[] = [\n  \"incomplete_expired\",\n  \"canceled\",\n];\n\n/** Statuses in which a subscription never activated (no access was ever granted). */\nexport const NEVER_ACTIVATED_SUBSCRIPTION_STATUSES: readonly SubscriptionStatus[] = [\n  \"incomplete\",\n  \"incomplete_expired\",\n];\n\n/** Whether access should currently be granted for a subscription in this state. */\nexport function grantsAccess(status: SubscriptionStatus): boolean {\n  return ACTIVE_SUBSCRIPTION_STATUSES.includes(status);\n}\n\n/** Whether this is a terminal status the subscription can never leave. */\nexport function isTerminal(status: SubscriptionStatus): boolean {\n  return TERMINAL_SUBSCRIPTION_STATUSES.includes(status);\n}\n"]}

package/dist/{chunk-J6JIZGWB.js → chunk-XKN7ZRAR.js}

@@ -20,19 +20,26 @@ var BillowApiError = class extends Error {
   code;
   /** Structured error context from the server (e.g. per-field validation issues), when present. */
   details;
-  /** billow's per-request id (`x-request-id`) — quote it in a bug report to trace the server log. */
+  /** billow's per-request id (`x-request-id`) - quote it in a bug report to trace the server log. */
   requestId;
-  constructor(status, code, message, details, requestId) {
+  /**
+   * How many seconds to wait before trying again, from the response's `Retry-After` header (sent
+   * with a `429 rate_limited`); undefined when the response did not say.
+   */
+  retryAfterSeconds;
+  constructor(status, code, message, details, requestId, retryAfterSeconds) {
     super(message);
     this.name = "BillowApiError";
     this.status = status;
     this.code = code;
     this.details = details;
     this.requestId = requestId;
+    this.retryAfterSeconds = retryAfterSeconds;
   }
 };
 var DEFAULT_TIMEOUT_MS = 6e4;
 var DEFAULT_RETRY_BACKOFF_MS = 500;
+var MAX_RETRY_AFTER_SECONDS = 3600;
 function makeContext(bearer, opts) {
   return {
     fetch: opts.fetch ?? fetch,
@@ -51,7 +58,7 @@ function isRetryable(status, safeToRepeat2) {
 function backoffMs(base, attempt, retryAfter) {
   if (retryAfter) {
     const secs = Number(retryAfter);
-    if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
+    if (Number.isFinite(secs) && secs >= 0) return Math.min(secs, MAX_RETRY_AFTER_SECONDS) * 1e3;
   }
   return base * 2 ** attempt;
 }
@@ -173,9 +180,25 @@ function errorFrom(res, data) {
     err.code ?? "error",
     err.message ?? String(res.status),
     err.details,
-    requestIdOf(res)
+    requestIdOf(res),
+    retryAfterOf(res)
   );
 }
+var IMF_FIXDATE = /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+function retryAfterOf(res) {
+  const value = res.headers.get("retry-after")?.trim();
+  if (!value) return void 0;
+  let seconds;
+  if (/^\d+$/.test(value)) {
+    seconds = Number(value);
+  } else if (IMF_FIXDATE.test(value)) {
+    seconds = Math.ceil((Date.parse(value) - Date.now()) / 1e3);
+  } else {
+    return void 0;
+  }
+  if (!Number.isFinite(seconds)) return void 0;
+  return Math.min(Math.max(0, seconds), MAX_RETRY_AFTER_SECONDS);
+}
 async function apiRequestBinary(ctx, method, path2, options) {
   const res = await sendWithResilience(
     ctx,
@@ -529,6 +552,31 @@ function createCreditsResource(ctx) {
         options
       )
     },
+    includedWindows: {
+      /**
+       * The Included Credit Windows of one or more subscriptions (`subscription`, an id or a list
+       * of up to 100), or of a customer (`customer`, by external id) - newest first: what each
+       * period Billow granted includes (the whole period, each month of it under a monthly rule,
+       * or a trial), how far it was issued, and its `state`. With `current: true`, only each
+       * subscription's latest window that has started - what it stands at now. Auto-paginating by
+       * cursor: `await` the first page, `for await (…)` every window, or `.listAll()` to collect
+       * them.
+       */
+      list: (params, options) => {
+        const { subscription, ...rest } = params;
+        const subscriptions = Array.isArray(subscription) ? subscription.join(",") : subscription;
+        return makeCursorListPromise(
+          (p) => apiRequest(
+            ctx,
+            "GET",
+            `/v1/credits/included-windows${toQuery({ ...p, subscription: subscriptions })}`,
+            void 0,
+            options
+          ),
+          rest
+        );
+      }
+    },
     topUps: {
       /**
        * Buy a Credit Pack for a customer: answers the top-up with `checkoutUrl`, the hosted
@@ -1136,7 +1184,7 @@ function createSettingsResource(ctx) {
     },
     /**
      * Usage settlement grace (hours): defers *collection* of a boundary-adjacent priced
-     * calendar-meter renewal past the tz month boundary until late usage settles — the billed
+     * calendar-meter renewal past the tz month boundary until late usage settles - the billed
      * windows/amount are unchanged, only the invoice timing shifts. `0` disables it (the default);
      * a no-op for any subscription without a priced calendar meter. Cap 72h.
      */
@@ -1263,7 +1311,7 @@ function createSubscriptionsResource(ctx) {
       void 0,
       options
     ),
-    /** Cancel — immediately, or at period end with `{ atPeriodEnd: true }`. */
+    /** Cancel - immediately, or at period end with `{ atPeriodEnd: true }`. */
     cancel: (id, opts) => apiRequest(
       ctx,
       "POST",
@@ -1276,7 +1324,18 @@ function createSubscriptionsResource(ctx) {
       "POST",
       `/v1/subscriptions/${encodeURIComponent(id)}/resume-cancellation`
     ),
+    /**
+     * Pause an active or trialing subscription: no renewals and no access until it is resumed.
+     * Refused while one of its invoices is still being collected.
+     */
     pause: (id) => apiRequest(ctx, "POST", `/v1/subscriptions/${encodeURIComponent(id)}/pause`),
+    /**
+     * Resume a paused subscription. Paused time is never billed: resumed before its paid period
+     * ends, it carries on and renews at `currentPeriodEnd`; resumed after, a fresh full period
+     * starts now and is charged at once like a renewal, with the ended period's usage (a decline
+     * returns it `past_due`). Usage recorded while paused is never billed. A paused trial resumes
+     * `trialing`. Duplicate calls are safe.
+     */
     resume: (id) => apiRequest(ctx, "POST", `/v1/subscriptions/${encodeURIComponent(id)}/resume`),
     /** Apply a coupon to an existing subscription. */
     applyCoupon: (id, code) => apiRequest(
@@ -1285,7 +1344,7 @@ function createSubscriptionsResource(ctx) {
       `/v1/subscriptions/${encodeURIComponent(id)}/coupon`,
       { code }
     ),
-    /** Change plan — immediate prorated upgrade, or downgrade scheduled for period end. `productId` accepts the product's id or slug. */
+    /** Change plan - immediate prorated upgrade, or downgrade scheduled for period end. `productId` accepts the product's id or slug. */
     changePlan: (id, productId) => apiRequest(ctx, "POST", `/v1/subscriptions/${encodeURIComponent(id)}/change-plan`, { productId }),
     /** Clear a pending downgrade. Duplicate calls are safe. */
     clearScheduledPlanChange: (id) => apiRequest(
@@ -1359,7 +1418,7 @@ function createWebhookEndpointsResource(ctx) {
     ),
     /** Delete an endpoint and its delivery history. */
     delete: (id) => apiRequest(ctx, "DELETE", `/v1/webhook-endpoints/${encodeURIComponent(id)}`),
-    /** Rotate the signing secret — the new plaintext is returned once. */
+    /** Rotate the signing secret - the new plaintext is returned once. */
     rotateSecret: (id) => apiRequest(
       ctx,
       "POST",
@@ -1398,7 +1457,7 @@ var Billow = class {
   /** Custom domains for the hosted customer portal (live keys, behind a rollout flag). */
   hostedDomains;
   /**
-   * Organization settings (Phase D3, F) — the configurable dunning schedule, usage settlement grace,
+   * Organization settings (Phase D3, F) - the configurable dunning schedule, usage settlement grace,
    * and the cross-currency reporting currency + FX-rate registry (ADR-0013).
    */
   settings;
@@ -1426,7 +1485,7 @@ var Billow = class {
   coupons = {
     /** Define a coupon (a reusable discount template). */
     create: (input) => this.#request("POST", "/v1/coupons", input),
-    /** List coupons (secret key only — enumerates live promo codes). Auto-paginating. */
+    /** List coupons (secret key only - enumerates live promo codes). Auto-paginating. */
     list: (params = {}, options) => makeListPromise(
       (p) => this.#request("GET", `/v1/coupons${toQuery(p)}`, void 0, options),
       params
@@ -1434,13 +1493,13 @@ var Billow = class {
     /** Deactivate a coupon (existing discounts keep running). */
     deactivate: (id) => this.#request("POST", `/v1/coupons/${encodeURIComponent(id)}/deactivate`)
   };
-  /** Manage developer webhook endpoints — register, rotate secrets, inspect deliveries.
+  /** Manage developer webhook endpoints - register, rotate secrets, inspect deliveries.
    *  (To VERIFY incoming deliveries, import `constructEvent` from `@usebillow/sdk/webhooks`.) */
   features = {
     /** Define a feature (a boolean access gate, or a metered feature with a meter). */
     create: (input) => this.#request("POST", "/v1/features", input),
     /**
-     * Edit a feature in place: its `name`, and — for a metered feature — its `meter`
+     * Edit a feature in place: its `name`, and - for a metered feature - its `meter`
      * aggregation. The server refuses a meter change once usage has been recorded (it
      * would rewrite billed history), so set the meter right at create time or before you
      * start tracking. Returns the updated feature.
@@ -1497,7 +1556,7 @@ var Billow = class {
      * choose a credential set and `target` to probe one verify target (Paymob: a
      * method); pass `sampleToken` (SANDBOX ONLY) to run a functional sub-test.
      * This probe hits the provider's live API (mutates nothing here), so it takes a
-     * per-call {@link CallOptions} for a timeout / cancellation — `opts` is spread into
+     * per-call {@link CallOptions} for a timeout / cancellation - `opts` is spread into
      * the body, so `options` stays a separate trailing arg (never merged in).
      */
     verify: (provider, opts, options) => this.#request(
@@ -1524,7 +1583,7 @@ var Billow = class {
       )
     }
   };
-  /** The merchant's business identity — the seller block on documents and email from-name. */
+  /** The merchant's business identity - the seller block on documents and email from-name. */
   businessProfile = {
     /** The stored profile, or null if one was never saved. */
     get: (options) => this.#request(
@@ -1540,11 +1599,11 @@ var Billow = class {
   };
   /**
    * Hosted customer surfaces (Phase G, ADR-0014). Mint a portal session for one of
-   * your signed-in users and redirect them to the returned `url` — the self-serve
+   * your signed-in users and redirect them to the returned `url` - the self-serve
    * portal, or a `checkout` hand-off for `productId`. The Customer's own calls go
    * through {@link BillowPortal}, constructed with the session token.
    */
-  /** Identity of this key's tenant — org, environment, configured currencies. */
+  /** Identity of this key's tenant - org, environment, configured currencies. */
   me(options) {
     return this.#request("GET", "/v1/me", void 0, options);
   }
@@ -1564,14 +1623,14 @@ var Billow = class {
   // ── The headline verbs ──────────────────────────────────────────────
   /**
    * Gate access to a feature. `featureId` is the feature slug. Returns
-   * `{ allowed, balance }` — `balance` is `null` for unlimited/boolean features.
+   * `{ allowed, balance }` - `balance` is `null` for unlimited/boolean features.
    */
   check(input, options) {
     return this.#request("POST", "/v1/check", input, options);
   }
   /**
    * Record usage of a metered feature (`value` defaults to 1; negative credits
-   * back). Pass `idempotencyKey` to make a retried call a no-op — which also makes the call
+   * back). Pass `idempotencyKey` to make a retried call a no-op - which also makes the call
    * safe to retry automatically when `maxRetries` is set.
    */
   track(input, options) {
@@ -1608,7 +1667,7 @@ var BillowPublishable = class {
     this.#ctx = makeContext(publishableKey, opts);
   }
   products = {
-    /** The active catalog — products and their prices, for a pricing table. */
+    /** The active catalog - products and their prices, for a pricing table. */
     list: (options) => apiRequest(
       this.#ctx,
       "GET",
@@ -1632,7 +1691,7 @@ var BillowPortal = class {
     if (!sessionToken) throw new Error("billow: a portal session token is required");
     this.#ctx = makeContext(sessionToken, opts);
   }
-  /** The portal shell: flow, return URL, merchant brand, and customer identity —
+  /** The portal shell: flow, return URL, merchant brand, and customer identity -
    *  the lightweight payload the hosting app frames every page with, and the
    *  validate-and-route check at login. */
   session(options) {
@@ -1760,5 +1819,5 @@ var BillowPortal = class {
 };
 
 export { BILLOW_ERROR_CODES, Billow, BillowApiError, BillowPortal, BillowPublishable, currencyExponent, formatMoney, isSecretField, toMajorUnits, toMinorUnits };
-//# sourceMappingURL=chunk-J6JIZGWB.js.map
-//# sourceMappingURL=chunk-J6JIZGWB.js.map
+//# sourceMappingURL=chunk-XKN7ZRAR.js.map
+//# sourceMappingURL=chunk-XKN7ZRAR.js.map