@usebillow/sdk 0.8.0 → 0.10.0

package/dist/{hosted-domains-BP91tg9P.d.ts → hosted-domains-DSs5Iw9U.d.ts}

@@ -1,4 +1,4 @@
-import { H as HostedDomainResponse } from './index.d-CKQAhQfJ.js';
+import { H as HostedDomainResponse } from './index.d-DSEYhV2c.js';
 
 /**
  * Public SDK types for prepaid credits. Re-exported by ../types.ts.
@@ -67,9 +67,33 @@ interface CreateCreditGrantInput {
 }
 /** A Credit Account's status: `frozen` takes no new reservations; `closed` (erased) takes nothing. */
 type CreditAccountStatus = "active" | "frozen" | "closed";
+/** What current Included Credit Windows include, and where it stands. */
+interface IncludedCredits {
+    /** What the windows include. */
+    granted: string;
+    /** Consumed from their credits, net of reversals. */
+    used: string;
+    held: string;
+    /** Unheld and spendable, credits recorded but not issued yet included. */
+    remaining: string;
+}
+/** One subscription's current Included Credit Window, in a customer's balance. */
+interface IncludedPeriod extends IncludedCredits {
+    subscriptionId: string;
+    /** The window (ISO 8601), half-open: its credits expire at `end`. */
+    start: string;
+    end: string;
+    /** The billing period it belongs to (a trial's is the trial). */
+    periodStart: string;
+    periodEnd: string;
+    /** The next window's start within the paid period (a monthly refill), or null. */
+    nextRefillAt: string | null;
+}
 /**
  * A customer's credit balance, true at `asOf`. A balance never grants spending authority - only a
- * reservation does. A customer with no credit account yet reads as zeros, `active`, `exhausted`.
+ * reservation does. A customer with no credit account yet reads as their subscriptions' recorded
+ * included credits alone (zeros without any), `active`, `exhausted` when nothing is spendable.
+ * Included credits count from the instant their window is current, before Billow issues them.
  */
 interface CreditBalance {
     /** The customer's external id. */
@@ -79,7 +103,10 @@ interface CreditBalance {
     spendable: string;
     /** Credits held by open reservations. */
     held: string;
-    /** Credits consumed since `periodStart`, net of reversals. */
+    /**
+     * Credits consumed since `periodStart`, net of their reversals: a reversal counts against the
+     * period of the consumption it reverses, so this is never negative.
+     */
     consumedThisPeriod: string;
     /** The current included period's start, else the first instant of the current UTC month. */
     periodStart: string;
@@ -99,22 +126,23 @@ interface CreditBalance {
         /** Spendable on a category not listed: the grants that pay for every category. */
         otherCategories: string;
     };
-    /** The active included grants (a subscription's period allowance); null when there are none. */
-    currentPeriod: {
-        granted: string;
-        /** Consumed from them, net of reversals. */
-        used: string;
-        held: string;
-        /** Unheld and spendable. */
-        remaining: string;
+    /**
+     * The current Included Credit Windows together - the billing period, or the current month under
+     * a monthly allocation - across the customer's subscriptions; null when none is current (between
+     * a period's end and the payment that grants the next).
+     */
+    currentPeriod: (IncludedCredits & {
+        /** The earliest current window's start. */
         start: string;
-        /** When they expire (the period end); null if one never does. */
-        end: string | null;
-    } | null;
+        /** The earliest current window's end: when the first of these credits stop. */
+        end: string;
+    }) | null;
+    /** Each subscription's current window, soonest end first (empty when none is current). */
+    includedPeriods: IncludedPeriod[];
     thresholds: {
         lowPercent: number;
         criticalPercent: number;
-        /** What the percentages apply to: the current period's credits, else the last top-up's. */
+        /** What the percentages apply to: the current windows' credits, else the last top-up's. */
         reference: string | null;
         level: CreditThresholdLevel;
     };
@@ -127,7 +155,11 @@ type CreditTransactionType = "grant" | "hold" | "release" | "consume" | "expire"
 interface CreditLedgerEntry {
     id: string;
     type: CreditTransactionType;
-    /** Why Billow posted it, as a system code (`api_grant`, `grant_expired`, ...); never free text. */
+    /**
+     * Why Billow posted it, as a system code (`api_grant`, `grant_expired`, `subscription_period`,
+     * `subscription_upgrade`, `subscription_canceled`, `subscription_charged_back`, ...); never free
+     * text.
+     */
     reason: string | null;
     /** How it moved the account's unheld credits (signed). */
     availableDelta: string;
@@ -144,6 +176,8 @@ interface CreditLedgerEntry {
     callerReason: string | null;
     /** The metadata of the resource it belongs to: its reservation, reversal or top-up, else its grant. */
     metadata: Record<string, string> | null;
+    /** On an included grant's transaction: the subscription whose window issued the grant. */
+    subscriptionId: string | null;
     createdAt: string;
 }
 /** What `credits.usage.get` totals each row by. */
@@ -326,6 +360,79 @@ interface CreateCreditIncludedRuleInput {
 type UpdateCreditIncludedRuleInput = Partial<Omit<CreateCreditIncludedRuleInput, "priceId">> & {
     archived?: boolean;
 };
+/**
+ * Where an Included Credit Window stands: `scheduled` (a later window, not started), `pending`
+ * (current, waiting to be issued - Billow issues it within seconds), `blocked` (current, but its
+ * last issue attempt could not go through - see `blockedCause` - and Billow retries it with
+ * backoff), `issued`, `suspended` (held by a pause), `lapsed` (over without being issued: a period
+ * paid after it ended, or one that passed while paused), `ended` (ended early, with `endCause`),
+ * or `account_closed` (the customer was erased, so it never issues).
+ */
+type CreditWindowState = "scheduled" | "pending" | "blocked" | "issued" | "suspended" | "lapsed" | "ended" | "account_closed";
+/**
+ * An Included Credit Window: what one window of a period Billow granted a subscription includes -
+ * the whole billing period, one month of it under a monthly rule, or a trial - and how far its
+ * credits have been issued.
+ */
+interface CreditIncludedWindow {
+    id: string;
+    subscriptionId: string;
+    /** The customer's external id. */
+    customerId: string;
+    /** The window (ISO 8601), half-open: its credits expire at `end`. */
+    start: string;
+    end: string;
+    /** The billing period it belongs to (a trial's is the trial). */
+    periodStart: string;
+    periodEnd: string;
+    /** The next window's start within the period (a monthly refill), or null for its last window. */
+    nextRefillAt: string | null;
+    /** How the rule allocated the period when it was granted. */
+    allocation: CreditAllocationInterval;
+    /** The categories its credits may pay for; null = every category. */
+    eligibility: string[] | null;
+    /** Microcredits the window includes. */
+    entitled: string;
+    /** Microcredits issued to the customer for it so far. */
+    issued: string;
+    state: CreditWindowState;
+    /**
+     * For a `blocked` window: `capacity` (its credits would take the customer's balance past the
+     * largest total Billow holds) or `error` (an unexpected fault); null otherwise.
+     */
+    blockedCause: "capacity" | "error" | null;
+    /** For a `pending` or `blocked` window: since when it has been due. */
+    dueSince: string | null;
+    /** When an `ended` window ended early; null otherwise. */
+    endedAt: string | null;
+    /**
+     * Why an `ended` window ended early: `canceled` (the subscription was canceled immediately) or
+     * `charged_back` (the payment for its period was lost to a chargeback); null otherwise.
+     */
+    endCause: "canceled" | "charged_back" | null;
+    /**
+     * When a plan upgrade inside the period last raised what the window includes (or added the
+     * window, to a period that had none); null for a window as its period was granted.
+     */
+    raisedAt: string | null;
+    createdAt: string;
+}
+/**
+ * Whose Included Credit Windows to list: one or more subscriptions, or a customer (by external id)
+ * - exactly one of the two.
+ */
+type CreditIncludedWindowListParams = ({
+    subscription: string | string[];
+    customer?: never;
+} | {
+    customer: string;
+    subscription?: never;
+}) & {
+    /** Only each subscription's latest window that has started (what the subscription shows now). */
+    current?: boolean;
+    limit?: number;
+    cursor?: string;
+};
 /**
  * A top-up's state: `pending` until its payment settles; `succeeded` (credits granted) or
  * `failed` (a later payment on the same checkout still succeeds it); `unfulfilled` - paid after
@@ -427,4 +534,4 @@ interface HostedDomainDisabledData extends HostedDomainEventBase {
     reason: Extract<HostedDomainStatusReason, "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended">;
 }
 
-export type { CreditTopUpStatus as A, CreditTransactionType as B, CreditGrantKind as C, CreditUsageGroupBy as D, HostedDomainEventBase as E, HostedDomainStatus as F, HostedDomainStatusReason as G, HostedDomainActivatedData as H, UpdateCreditPackInput as U, CreditThresholdLevel as a, HostedDomainDnsFailingData as b, HostedDomainReassignmentPendingData as c, HostedDomainDisabledData as d, CreditGrant as e, CreditTopUp as f, CreateCreditGrantInput as g, CreditGrantRequestResult as h, CreditPacks as i, CreateCreditPackInput as j, CreditPack as k, CreateCreditIncludedRuleInput as l, CreditIncludedRule as m, UpdateCreditIncludedRuleInput as n, CreateCreditTopUpInput as o, CreditTopUpRequestResult as p, CreditTopUpListParams as q, CreditBalance as r, CreditLedgerEntry as s, CreditUsageParams as t, CreditUsage as u, CreditAccountStatus as v, CreditAllocationInterval as w, CreditMoney as x, CreditPackBreakdown as y, CreditPackListItem as z };
+export type { CreditPackBreakdown as A, CreditPackListItem as B, CreditGrantKind as C, CreditTopUpStatus as D, CreditTransactionType as E, CreditUsageGroupBy as F, CreditWindowState as G, HostedDomainActivatedData as H, HostedDomainEventBase as I, HostedDomainStatus as J, HostedDomainStatusReason as K, IncludedCredits as L, IncludedPeriod as M, UpdateCreditPackInput as U, CreditThresholdLevel as a, HostedDomainDnsFailingData as b, HostedDomainReassignmentPendingData as c, HostedDomainDisabledData as d, CreditGrant as e, CreditTopUp as f, CreditIncludedWindow as g, CreateCreditGrantInput as h, CreditGrantRequestResult as i, CreditPacks as j, CreateCreditPackInput as k, CreditPack as l, CreateCreditIncludedRuleInput as m, CreditIncludedRule as n, UpdateCreditIncludedRuleInput as o, CreditIncludedWindowListParams as p, CreateCreditTopUpInput as q, CreditTopUpRequestResult as r, CreditTopUpListParams as s, CreditBalance as t, CreditLedgerEntry as u, CreditUsageParams as v, CreditUsage as w, CreditAccountStatus as x, CreditAllocationInterval as y, CreditMoney as z };

package/dist/index.cjs

@@ -36,19 +36,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,
@@ -67,7 +74,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;
 }
@@ -189,9 +196,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,
@@ -576,6 +599,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
@@ -1183,7 +1231,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.
      */
@@ -1310,7 +1358,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",
@@ -1323,7 +1371,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(
@@ -1332,7 +1391,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(
@@ -1406,7 +1465,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",
@@ -1445,7 +1504,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;
@@ -1473,7 +1532,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
@@ -1481,13 +1540,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.
@@ -1544,7 +1603,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(
@@ -1571,7 +1630,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(
@@ -1587,11 +1646,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);
   }
@@ -1611,14 +1670,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) {
@@ -1655,7 +1714,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",
@@ -1679,7 +1738,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) {