@usebillow/sdk 0.9.0 → 0.11.0

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,
@@ -496,6 +519,35 @@ function createCreditsResource(ctx) {
         return { ...data, replayed: status === 200 };
       }
     },
+    accounts: {
+      /**
+       * Freeze a customer's Credit Account (by external id): it takes no new reservations - a
+       * reserve throws `account_frozen` (423) - until unfrozen, while holds already made still
+       * commit and release, and grants, top-ups, reversals and included credits still fund it.
+       * Safe to retry: freezing a frozen account changes nothing and answers `changed: false`. A
+       * customer with no account yet gets one, frozen. Throws `account_closed` (409) for an erased
+       * customer.
+       */
+      freeze: (customer, options) => apiRequest(
+        ctx,
+        "POST",
+        "/v1/credits/accounts/freeze",
+        { customerId: customer },
+        options
+      ),
+      /**
+       * Unfreeze a customer's Credit Account (by external id): it takes reservations again. Safe to
+       * retry: unfreezing an account that is not frozen changes nothing and answers
+       * `changed: false`.
+       */
+      unfreeze: (customer, options) => apiRequest(
+        ctx,
+        "POST",
+        "/v1/credits/accounts/unfreeze",
+        { customerId: customer },
+        options
+      )
+    },
     packs: {
       /**
        * The Credit Packs a customer can buy in `currency` (ISO 4217), cheapest first: credits and
@@ -1208,7 +1260,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.
      */
@@ -1335,7 +1387,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",
@@ -1368,7 +1420,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(
@@ -1442,7 +1494,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",
@@ -1481,7 +1533,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;
@@ -1509,7 +1561,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
@@ -1517,13 +1569,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.
@@ -1580,7 +1632,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(
@@ -1607,7 +1659,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(
@@ -1623,11 +1675,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);
   }
@@ -1647,14 +1699,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) {
@@ -1691,7 +1743,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",
@@ -1715,7 +1767,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) {