@usebillow/sdk 0.5.0

package/dist/chunk-Z6VXPONT.js

@@ -0,0 +1,1493 @@
+// src/client.ts
+var REQUEST_ID_HEADER = "x-request-id";
+function toQuery(params) {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== void 0 && v !== null && v !== "") q.set(k, String(v));
+  }
+  const s = q.toString();
+  return s ? `?${s}` : "";
+}
+var BillowApiError = class extends Error {
+  status;
+  /**
+   * A known {@link BillowErrorCode} (widened to `string` so a newer server's code still type-checks),
+   * or one the SDK raises itself: `invalid_response` for a success (2xx other than 204) whose body
+   * was empty or could not be read or parsed. The request reached billow and was answered, but what
+   * it answered is unknown - for a write, treat the outcome as UNKNOWN (retry it under the same
+   * idempotency key), never as done or as refused.
+   */
+  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. */
+  requestId;
+  constructor(status, code, message, details, requestId) {
+    super(message);
+    this.name = "BillowApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.requestId = requestId;
+  }
+};
+var DEFAULT_TIMEOUT_MS = 6e4;
+var DEFAULT_RETRY_BACKOFF_MS = 500;
+function makeContext(bearer, opts) {
+  return {
+    fetch: opts.fetch ?? fetch,
+    baseUrl: resolveBaseUrl(opts.baseUrl),
+    bearer,
+    timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    maxRetries: opts.maxRetries ?? 0,
+    retryBackoffMs: opts.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS
+  };
+}
+function isRetryable(status, safeToRepeat2) {
+  if (status === 429) return true;
+  if (status === null) return safeToRepeat2;
+  return safeToRepeat2 && status >= 500 && status <= 599;
+}
+function backoffMs(base, attempt, retryAfter) {
+  if (retryAfter) {
+    const secs = Number(retryAfter);
+    if (Number.isFinite(secs) && secs >= 0) return secs * 1e3;
+  }
+  return base * 2 ** attempt;
+}
+function abortReason(signal) {
+  return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(abortReason(signal));
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(abortReason(signal));
+      },
+      { once: true }
+    );
+  });
+}
+async function sendWithResilience(ctx, url, init, opts) {
+  const { timeoutMs, safeToRepeat: safeToRepeat2, callerSignal } = opts;
+  if (callerSignal?.aborted) throw abortReason(callerSignal);
+  for (let attempt = 0; ; attempt++) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const onCallerAbort = () => controller.abort(abortReason(callerSignal));
+    callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+    const timer = timeoutMs > 0 ? setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs) : void 0;
+    let res = null;
+    let err;
+    try {
+      res = await ctx.fetch(url, { ...init, signal: controller.signal });
+    } catch (e) {
+      err = e;
+    } finally {
+      if (timer) clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+    if (callerSignal?.aborted) throw abortReason(callerSignal);
+    if (res?.ok) return res;
+    const status = res ? res.status : null;
+    if (attempt < ctx.maxRetries && isRetryable(status, safeToRepeat2)) {
+      await sleep(
+        backoffMs(ctx.retryBackoffMs, attempt, res?.headers.get("retry-after") ?? null),
+        callerSignal
+      );
+      continue;
+    }
+    if (res) return res;
+    if (timedOut) throw new Error(`billow request timed out after ${timeoutMs}ms`);
+    throw err instanceof Error ? err : new Error("billow request failed");
+  }
+}
+function safeToRepeat(method, hasIdempotencyKey) {
+  return method === "GET" || method === "HEAD" || hasIdempotencyKey;
+}
+var DEFAULT_BASE_URL = "https://api.usebillow.com";
+function resolveBaseUrl(explicit) {
+  const fromEnv = typeof process !== "undefined" ? process.env?.["BILLOW_URL"] : void 0;
+  return (explicit || fromEnv || DEFAULT_BASE_URL).replace(/\/$/, "");
+}
+async function apiRequest(ctx, method, path, body, options) {
+  return (await apiRequestWithStatus(ctx, method, path, body, options)).data;
+}
+async function apiRequestWithStatus(ctx, method, path, body, options) {
+  const init = {
+    method,
+    headers: {
+      authorization: `Bearer ${ctx.bearer}`,
+      ...body ? { "content-type": "application/json" } : {},
+      ...options?.idempotencyKey ? { "idempotency-key": options.idempotencyKey } : {}
+    }
+  };
+  if (body) init.body = JSON.stringify(body);
+  const res = await sendWithResilience(ctx, `${ctx.baseUrl}${path}`, init, {
+    timeoutMs: options?.timeoutMs ?? ctx.timeoutMs,
+    safeToRepeat: safeToRepeat(method, !!options?.idempotencyKey),
+    callerSignal: options?.signal
+  });
+  const text = await res.text().catch(() => null);
+  if (!res.ok) throw errorFrom(res, safeParse(text ?? ""));
+  return { status: res.status, data: parseSuccessBody(res, text) };
+}
+function requestIdOf(res) {
+  return res.headers.get(REQUEST_ID_HEADER) ?? void 0;
+}
+function safeParse(text) {
+  if (text.trim() === "") return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {};
+  }
+}
+function parseSuccessBody(res, text) {
+  if (res.status === 204) return {};
+  if (text !== null && text.trim() !== "") {
+    try {
+      return JSON.parse(text);
+    } catch {
+    }
+  }
+  throw new BillowApiError(
+    res.status,
+    "invalid_response",
+    `billow returned an empty or unreadable response body (HTTP ${res.status})`,
+    void 0,
+    requestIdOf(res)
+  );
+}
+function errorFrom(res, data) {
+  const err = data.error ?? {};
+  return new BillowApiError(
+    res.status,
+    err.code ?? "error",
+    err.message ?? String(res.status),
+    err.details,
+    requestIdOf(res)
+  );
+}
+async function apiRequestBinary(ctx, method, path, options) {
+  const res = await sendWithResilience(
+    ctx,
+    `${ctx.baseUrl}${path}`,
+    { method, headers: { authorization: `Bearer ${ctx.bearer}` } },
+    {
+      timeoutMs: options?.timeoutMs ?? ctx.timeoutMs,
+      safeToRepeat: safeToRepeat(method, false),
+      callerSignal: options?.signal
+    }
+  );
+  if (!res.ok) throw errorFrom(res, safeParse(await res.text().catch(() => "")));
+  return res.arrayBuffer();
+}
+
+// src/error-codes.ts
+var BILLOW_ERROR_CODES = [
+  "not_found",
+  "validation_error",
+  "authentication_error",
+  "api_key_expired",
+  "permission_denied",
+  "conflict",
+  "invalid_state_transition",
+  "provider_error",
+  "rate_limited",
+  "quota_exceeded",
+  "internal_error",
+  // Prepaid credits. 402 is shared with `quota_exceeded`: switch on the code, never the status.
+  "insufficient_credits",
+  "account_frozen",
+  "account_closed",
+  "idempotency_conflict",
+  "commit_exceeds_hold",
+  "reversal_exceeds_consumption"
+];
+
+// src/money.ts
+var CURRENCY_EXPONENTS = {
+  // Zero-decimal
+  BIF: 0,
+  CLP: 0,
+  DJF: 0,
+  GNF: 0,
+  ISK: 0,
+  JPY: 0,
+  KMF: 0,
+  KRW: 0,
+  PYG: 0,
+  RWF: 0,
+  UGX: 0,
+  VND: 0,
+  VUV: 0,
+  XAF: 0,
+  XOF: 0,
+  XPF: 0,
+  // Three-decimal
+  BHD: 3,
+  IQD: 3,
+  JOD: 3,
+  KWD: 3,
+  LYD: 3,
+  OMR: 3,
+  TND: 3,
+  // Four-decimal
+  CLF: 4,
+  UYW: 4
+};
+function currencyExponent(currency) {
+  return CURRENCY_EXPONENTS[currency.toUpperCase()] ?? 2;
+}
+function toMinorUnits(major, currency) {
+  return Math.round(major * 10 ** currencyExponent(currency));
+}
+function toMajorUnits(minor, currency) {
+  return minor / 10 ** currencyExponent(currency);
+}
+function formatMoney(minor, currency) {
+  const exponent = currencyExponent(currency);
+  const major = minor / 10 ** exponent;
+  try {
+    return new Intl.NumberFormat("en", {
+      style: "currency",
+      currency,
+      minimumFractionDigits: exponent,
+      maximumFractionDigits: exponent
+    }).format(major);
+  } catch {
+    return `${major.toFixed(exponent)} ${currency}`;
+  }
+}
+
+// src/types/admin-integrations.ts
+function isSecretField(field) {
+  return field.secret === true || field.type === "password";
+}
+
+// src/pagination.ts
+function makePagedList(fetchFirst, startWalk) {
+  let firstPage;
+  const first = () => {
+    if (!firstPage) {
+      const p = fetchFirst();
+      firstPage = p;
+      p.catch(() => {
+        if (firstPage === p) firstPage = void 0;
+      });
+    }
+    return firstPage;
+  };
+  async function* iterate() {
+    const next = startWalk();
+    let page = await first();
+    while (page) {
+      yield* page.data;
+      const following = next(page);
+      page = following ? await following : null;
+    }
+  }
+  const listAll = async () => {
+    const out = [];
+    for await (const item of iterate()) out.push(item);
+    return out;
+  };
+  return Object.assign(first(), {
+    [Symbol.asyncIterator]: iterate,
+    listAll
+  });
+}
+function makeListPromise(fetchPage, params) {
+  return makePagedList(
+    () => fetchPage(params),
+    () => {
+      let limit;
+      let offset = params.offset ?? 0;
+      return (page) => {
+        limit ??= page.limit > 0 ? page.limit : params.limit ?? 0;
+        offset += page.data.length;
+        if (!(limit > 0 && page.data.length >= limit)) return null;
+        return fetchPage({ ...params, limit, offset });
+      };
+    }
+  );
+}
+function makeCursorListPromise(fetchPage, params) {
+  return makePagedList(
+    () => fetchPage(params),
+    () => (page) => page.nextCursor === null ? null : fetchPage({ ...params, limit: page.limit, cursor: page.nextCursor })
+  );
+}
+
+// src/resources/charges.ts
+function createChargesResource(ctx) {
+  return {
+    /** Create a customer-present charge -> returns a hosted checkout URL. Pass an
+     *  `idempotencyKey` to make the create safe to retry (with `maxRetries`). */
+    create: (input, options) => apiRequest(ctx, "POST", "/v1/charges", input, options),
+    /** Charge the customer's current saved card without customer presence. */
+    createMerchantInitiated: (input, options) => apiRequest(ctx, "POST", "/v1/charges/mit", input, options),
+    /** Fetch a charge. Pass `{ sync: true }` to force an authoritative provider pull. */
+    get: (id, opts) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/charges/${encodeURIComponent(id)}${opts?.sync ? "?sync=true" : ""}`,
+      void 0,
+      opts
+    ),
+    /** List charges (paginated). Filters: status, currency, customer (external id), from, to. */
+    list: (params = {}, options) => makeListPromise(
+      (p) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/charges${toQuery(p)}`,
+        void 0,
+        options
+      ),
+      params
+    ),
+    /** Download the one-off charge's receipt as a PDF (raw bytes). */
+    receipt: (id, options) => apiRequestBinary(ctx, "GET", `/v1/charges/${encodeURIComponent(id)}/receipt.pdf`, options),
+    /** Download the immutable credit note for a succeeded refund. */
+    creditNote: (chargeId, refundId, options) => apiRequestBinary(
+      ctx,
+      "GET",
+      `/v1/charges/${encodeURIComponent(chargeId)}/refunds/${encodeURIComponent(refundId)}/credit-note.pdf`,
+      options
+    ),
+    /**
+     * Refund a succeeded charge: `{ amount }` (minor units) for a partial, `{}` for its whole
+     * remaining balance. The `idempotencyKey` is required and must identify this one refund
+     * (e.g. your own refund request's id): a retry under it - yours, or the SDK's own
+     * `maxRetries` - answers the same refund, in whatever status, instead of refunding again.
+     * Reuse the key whenever the outcome is unknown (a timeout or dropped connection); a new
+     * key asks for a new refund, e.g. after this one `failed`. `replayed` tells the refund an
+     * earlier request under the key made (`true`) from one this call made (`false`).
+     *
+     * Always check `status`: resolving does not mean refunded. A provider that declines the
+     * refund answers `502 provider_error`, which throws with `maxRetries: 0` (the default); with
+     * `maxRetries > 0` the SDK retries that 502 under the same key, so the call resolves instead
+     * with the declined refund replayed: `status: "failed"`, `replayed: true`.
+     */
+    refund: async (chargeId, input, options) => {
+      const { status, data } = await apiRequestWithStatus(
+        ctx,
+        "POST",
+        `/v1/charges/${encodeURIComponent(chargeId)}/refund`,
+        input,
+        options
+      );
+      return { ...data, replayed: status === 200 };
+    },
+    /** A charge's refunds, newest first (`needsReview` flags one awaiting an Operator). */
+    listRefunds: (chargeId, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/charges/${encodeURIComponent(chargeId)}/refunds`,
+      void 0,
+      options
+    ),
+    /** Reconcile a pending refund with the provider now; resolves to the refund as it stands. */
+    recheckRefund: (chargeId, refundId, options) => apiRequest(
+      ctx,
+      "POST",
+      `${refundPath(chargeId, refundId)}/recheck`,
+      void 0,
+      options
+    ),
+    /**
+     * Record the outcome you verified in the provider dashboard for a refund awaiting review
+     * (`needsReview`): `succeeded` settles it with a credit note, `failed` releases its amount.
+     * A refund with a provider conflict (`providerConflictStatus`) resolves only as `succeeded`.
+     */
+    resolveRefund: (chargeId, refundId, input, options) => apiRequest(ctx, "POST", `${refundPath(chargeId, refundId)}/resolve`, input, options)
+  };
+}
+function refundPath(chargeId, refundId) {
+  return `/v1/charges/${encodeURIComponent(chargeId)}/refunds/${encodeURIComponent(refundId)}`;
+}
+function createCheckoutMethodsResource(ctx) {
+  return {
+    /** The customer-present methods + fees offered for a currency (for a method picker). */
+    list: (params, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/checkout-methods${toQuery(params)}`,
+      void 0,
+      options
+    )
+  };
+}
+
+// src/resources/credits.ts
+function createCreditsResource(ctx) {
+  return {
+    grants: {
+      /**
+       * Grant prepaid credits to a Customer. The `idempotencyKey` is required and must identify
+       * this one grant (e.g. your own promotion or support-ticket id): a retry under it - yours,
+       * or the SDK's own `maxRetries` - answers the same grant instead of granting twice, with
+       * `replayed: true`. Reusing the key for a different grant throws `idempotency_conflict`
+       * (409). Credit quantities are decimal strings of microcredits in both directions.
+       */
+      create: async (input, options) => {
+        const { status, data } = await apiRequestWithStatus(
+          ctx,
+          "POST",
+          "/v1/credits/grants",
+          input,
+          options
+        );
+        return { ...data, replayed: status === 200 };
+      }
+    },
+    packs: {
+      /**
+       * The Credit Packs a customer can buy in `currency` (ISO 4217), cheapest first: credits and
+       * bonus (decimal strings of microcredits), price (minor units), and the derived
+       * `pricePerCredit` and `savingsBps` - so your pricing page never hardcodes a price.
+       */
+      list: (currency, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/packs${toQuery({ currency })}`,
+        void 0,
+        options
+      ),
+      /** Configure a Credit Pack on a one-time catalog Price. */
+      create: (input, options) => apiRequest(ctx, "POST", "/v1/credits/packs", input, options),
+      /** A Credit Pack's configuration, archived or not. */
+      get: (packId, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/packs/${encodeURIComponent(packId)}`,
+        void 0,
+        options
+      ),
+      /** Edit a pack's terms or Price, or archive it; top-ups already made keep their terms. */
+      update: (packId, input, options) => apiRequest(
+        ctx,
+        "PATCH",
+        `/v1/credits/packs/${encodeURIComponent(packId)}`,
+        input,
+        options
+      )
+    },
+    topUps: {
+      /**
+       * Buy a Credit Pack for a customer: answers the top-up with `checkoutUrl`, the hosted
+       * checkout to send the buyer to. Credits are granted when the payment succeeds (listen for
+       * `credit_top_up.succeeded`). The `idempotencyKey` is required and must identify this one
+       * purchase: a retry under it answers the same top-up as it now stands (`replayed: true`) and
+       * buys nothing again; reusing it for another purchase throws `idempotency_conflict` (409).
+       * A retry can also throw `conflict` (409), with `details.reason`: `checkout_in_progress` -
+       * the first request is still opening the checkout, so retry the same key shortly - or
+       * `checkout_unavailable` - its checkout could not be opened and never will be, so buy again
+       * under a new key.
+       */
+      create: async (input, options) => {
+        const { status, data } = await apiRequestWithStatus(
+          ctx,
+          "POST",
+          "/v1/credits/top-ups",
+          input,
+          options
+        );
+        return { ...data, replayed: status === 200 };
+      },
+      /** A top-up as it now stands: status, checkout, grants, and what refunds revoked. */
+      get: (topUpId, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/top-ups/${encodeURIComponent(topUpId)}`,
+        void 0,
+        options
+      ),
+      /**
+       * A customer's top-ups (by external id), newest first, optionally of one status.
+       * Auto-paginating by cursor: `await` the first page, `for await (…)` every top-up, or
+       * `.listAll()` to collect them.
+       */
+      list: (customer, params = {}, options) => {
+        const { status, ...page } = params;
+        return makeCursorListPromise(
+          (p) => apiRequest(
+            ctx,
+            "GET",
+            `/v1/credits/top-ups${toQuery({ customer, status, ...p })}`,
+            void 0,
+            options
+          ),
+          page
+        );
+      }
+    },
+    balance: {
+      /**
+       * A Customer's credit balance (by external id): spendable, held, consumed this period,
+       * expiring soon, by kind and category, the current period and the threshold level, true at
+       * `asOf`. A Customer with no credit account yet reads as zeros.
+       */
+      get: (customer, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/balance${toQuery({ customer })}`,
+        void 0,
+        options
+      )
+    },
+    ledger: {
+      /**
+       * A Customer's credit ledger (by external id), newest first. Auto-paginating by cursor:
+       * `await` the first page, `for await (…)` every entry, or `.listAll()` to collect them -
+       * entries arriving meanwhile never make the walk skip or repeat one.
+       */
+      list: (customer, params = {}, options) => makeCursorListPromise(
+        (p) => apiRequest(
+          ctx,
+          "GET",
+          `/v1/credits/ledger${toQuery({ customer, ...p })}`,
+          void 0,
+          options
+        ),
+        params
+      )
+    },
+    usage: {
+      /**
+       * A Customer's credit consumption (by external id) per UTC day, by Credit Action or
+       * category, over at most 92 days (the 30 ending today by default).
+       */
+      get: (customer, params = {}, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/usage${toQuery({ customer, ...params })}`,
+        void 0,
+        options
+      )
+    }
+  };
+}
+
+// src/resources/customers.ts
+function createCustomersResource(ctx) {
+  return {
+    create: (input) => apiRequest(ctx, "POST", "/v1/customers", input),
+    get: (externalId, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/customers/${encodeURIComponent(externalId)}`,
+      void 0,
+      options
+    ),
+    /** List customers (`q` searches external id / email / name). Auto-paginating: `await` the
+     *  first page, `for await (…)` every page, or `.listAll()` to collect them. */
+    list: (params = {}, options) => makeListPromise(
+      (p) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/customers${toQuery(p)}`,
+        void 0,
+        options
+      ),
+      params
+    ),
+    /** Full per-customer view: profile + subscriptions + charges + cards + balances. */
+    overview: (externalId, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/customers/${encodeURIComponent(externalId)}/overview`,
+      void 0,
+      options
+    ),
+    paymentMethods: {
+      list: (customer, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/customers/${encodeURIComponent(customer)}/payment-methods`,
+        void 0,
+        options
+      ).then((r) => r.paymentMethods),
+      setDefault: (customer, id) => apiRequest(
+        ctx,
+        "POST",
+        `/v1/customers/${encodeURIComponent(customer)}/payment-methods/${encodeURIComponent(id)}/default`
+      ),
+      remove: (customer, id) => apiRequest(
+        ctx,
+        "DELETE",
+        `/v1/customers/${encodeURIComponent(customer)}/payment-methods/${encodeURIComponent(id)}`
+      )
+    },
+    /** Export all portable customer data held by Billow. Secret-key only. */
+    exportData: (externalId, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/customers/${encodeURIComponent(externalId)}/export`,
+      void 0,
+      options
+    ),
+    /** Anonymize PII after access-granting subscriptions have ended. Secret-key only. */
+    anonymize: (externalId, options) => apiRequest(
+      ctx,
+      "DELETE",
+      `/v1/customers/${encodeURIComponent(externalId)}`,
+      void 0,
+      options
+    )
+  };
+}
+
+// src/resources/deliverability.ts
+function createDeliverabilityResource(ctx) {
+  return {
+    /** Email deliveries (newest first), optionally filtered by status. Auto-paginating. */
+    emails: (params = {}, options) => makeListPromise(
+      (p) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/deliverability/emails${toQuery(p)}`,
+        void 0,
+        options
+      ),
+      params
+    ),
+    /** Outbound events (newest first), optionally filtered by status. Auto-paginating. */
+    events: (params = {}, options) => makeListPromise(
+      (p) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/deliverability/events${toQuery(p)}`,
+        void 0,
+        options
+      ),
+      params
+    ),
+    /** Inbound provider webhooks (newest first), optionally filtered by outcome. Auto-paginating. */
+    inbound: (params = {}, options) => makeListPromise(
+      (p) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/deliverability/inbound${toQuery(p)}`,
+        void 0,
+        options
+      ),
+      params
+    )
+  };
+}
+
+// src/resources/invoices.ts
+function createInvoicesResource(ctx) {
+  return {
+    /** List invoices. Filters: status, customer (external id), from, to. Auto-paginating. */
+    list: (params = {}, options) => makeListPromise(
+      (p) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/invoices${toQuery(p)}`,
+        void 0,
+        options
+      ),
+      params
+    ),
+    /** Fetch an invoice with its line items. */
+    get: (id, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/invoices/${encodeURIComponent(id)}`,
+      void 0,
+      options
+    ),
+    /**
+     * Record that an open invoice was paid outside the gateway (bank transfer, cash, cheque).
+     * Settles the invoice and advances the subscription exactly like a gateway payment.
+     * `amount` must equal the invoice total. Operator (secret key) only.
+     */
+    recordPayment: (id, input) => apiRequest(
+      ctx,
+      "POST",
+      `/v1/invoices/${encodeURIComponent(id)}/record-payment`,
+      input
+    ),
+    /** Open or resume hosted checkout for an existing outstanding invoice. */
+    pay: (id, input = {}, options) => apiRequest(
+      ctx,
+      "POST",
+      `/v1/invoices/${encodeURIComponent(id)}/pay`,
+      input,
+      options
+    ),
+    /** Download the invoice as a PDF (raw bytes). */
+    pdf: (id, options) => apiRequestBinary(ctx, "GET", `/v1/invoices/${encodeURIComponent(id)}/pdf`, options),
+    /** Download the invoice's payment receipt as a PDF (raw bytes; 404 if unpaid). */
+    receipt: (id, options) => apiRequestBinary(ctx, "GET", `/v1/invoices/${encodeURIComponent(id)}/receipt.pdf`, options)
+  };
+}
+
+// src/resources/marketplace.ts
+function createMarketplaceResource(ctx) {
+  return {
+    /** Every available Integration with this tenant's install state (no secret values). */
+    catalog: (options) => apiRequest(
+      ctx,
+      "GET",
+      "/v1/marketplace",
+      void 0,
+      options
+    ).then((r) => r.catalog),
+    /** One catalog entry by slug. */
+    get: (slug, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/marketplace/${encodeURIComponent(slug)}`,
+      void 0,
+      options
+    ).then((r) => r.item),
+    /** Install or reconfigure an Integration; `values` are the manifest form's field values. */
+    upsert: (slug, values) => apiRequest(ctx, "PUT", `/v1/marketplace/${encodeURIComponent(slug)}`, {
+      values
+    }).then((r) => r.item),
+    /** Enable or disable an installed Integration. */
+    setEnabled: (slug, enabled) => apiRequest(
+      ctx,
+      "POST",
+      `/v1/marketplace/${encodeURIComponent(slug)}/enabled`,
+      { enabled }
+    ).then((r) => r.item),
+    /** Uninstall an Integration. */
+    remove: (slug) => apiRequest(
+      ctx,
+      "DELETE",
+      `/v1/marketplace/${encodeURIComponent(slug)}`
+    ),
+    /**
+     * Verify an installed Integration's config. An email Integration sends a test
+     * message to `to` (returns `{ sent, to }`); an accounting Integration runs a
+     * non-mutating connectivity check with no recipient (returns `{ ok: true }`).
+     */
+    test: (slug, to) => apiRequest(
+      ctx,
+      "POST",
+      `/v1/marketplace/${encodeURIComponent(slug)}/test`,
+      to ? { to } : {}
+    )
+  };
+}
+
+// src/resources/metrics.ts
+function createMetricsResource(ctx) {
+  return {
+    /** KPI cards for a currency over a window (`from`/`to` default to the last 30 days). */
+    overview: (params = {}, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/metrics/overview${toQuery(params)}`,
+      void 0,
+      options
+    ),
+    /** A single bucketed metric (revenue / mrr / subs / success rate) over a window. */
+    timeseries: (params = {}, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/metrics/timeseries${toQuery(params)}`,
+      void 0,
+      options
+    ),
+    /**
+     * KPIs rolled up into the org's reporting currency across all billing currencies
+     * (Phase H). Resolves to `null` when no reporting currency is configured.
+     */
+    rollup: (params = {}, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/metrics/rollup${toQuery(params)}`,
+      void 0,
+      options
+    ).then((r) => r.rollup)
+  };
+}
+
+// src/resources/portal-sessions.ts
+function createPortalSessionsResource(ctx) {
+  return {
+    create: (input) => apiRequest(ctx, "POST", "/v1/portal-sessions", input)
+  };
+}
+
+// src/resources/products.ts
+function createProductsResource(ctx) {
+  return {
+    /** Define a product (its first active version + prices + entitlements). */
+    create: (input) => apiRequest(ctx, "POST", "/v1/products", input),
+    /**
+     * Update a product: rename, archive/unarchive, and/or edit its prices +
+     * entitlements in place.
+     */
+    update: (slug, input) => apiRequest(ctx, "PATCH", `/v1/products/${encodeURIComponent(slug)}`, input),
+    /** Fetch a product (active version + prices + entitlements) by slug. */
+    get: (slug, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/products/${encodeURIComponent(slug)}`,
+      void 0,
+      options
+    ),
+    /** List products. `includeArchived` also returns archived ones (for admin views). */
+    list: (params = {}, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/products${params.includeArchived ? "?includeArchived=true" : ""}`,
+      void 0,
+      options
+    ).then((r) => r.products),
+    /** Delete a plan (soft-delete, ADR-0015). */
+    delete: (slug) => apiRequest(ctx, "DELETE", `/v1/products/${encodeURIComponent(slug)}`),
+    /** Migrate every live subscriber of `fromSlug` onto `toSlug`. */
+    migrateSubscribers: (fromSlug, toSlug) => apiRequest(
+      ctx,
+      "POST",
+      `/v1/products/${encodeURIComponent(fromSlug)}/migrate-subscribers`,
+      { toSlug }
+    ),
+    /** Live-subscriber count per product, keyed by product id. */
+    subscriberCounts: (options) => apiRequest(
+      ctx,
+      "GET",
+      "/v1/products/subscriber-counts",
+      void 0,
+      options
+    ).then((r) => r.counts)
+  };
+}
+
+// src/resources/settings.ts
+function createSettingsResource(ctx) {
+  return {
+    /** The dunning retry schedule: configured gaps in days (null = default), + the default. */
+    dunning: {
+      get: (options) => apiRequest(
+        ctx,
+        "GET",
+        "/v1/settings/dunning",
+        void 0,
+        options
+      ),
+      /** Set the retry gaps (whole days); pass `null`/`[]` to reset to the default. */
+      update: (retryDays) => apiRequest(
+        ctx,
+        "PUT",
+        "/v1/settings/dunning",
+        { retryDays }
+      )
+    },
+    /**
+     * 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
+     * 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.
+     */
+    usageSettlementGrace: {
+      get: (options) => apiRequest(
+        ctx,
+        "GET",
+        "/v1/settings/usage-settlement-grace",
+        void 0,
+        options
+      ),
+      /** Set the grace window in whole hours (0–72); `0` disables. */
+      update: (graceHours) => apiRequest(ctx, "PUT", "/v1/settings/usage-settlement-grace", {
+        graceHours
+      })
+    },
+    /** The currency cross-currency reporting rolls up into (null = none configured). */
+    reporting: {
+      get: (options) => apiRequest(
+        ctx,
+        "GET",
+        "/v1/settings/reporting",
+        void 0,
+        options
+      ),
+      /** Set the reporting currency (3-letter ISO), or `null` to clear it. */
+      update: (currency) => apiRequest(ctx, "PUT", "/v1/settings/reporting", {
+        currency
+      })
+    },
+    /** The manually-maintained FX rates the per-invoice reporting snapshot draws on. */
+    fxRates: {
+      list: (options) => apiRequest(
+        ctx,
+        "GET",
+        "/v1/settings/fx-rates",
+        void 0,
+        options
+      ).then((r) => r.rates),
+      /** Upsert one `base → quote` rate (`rate` is the decimal quote-per-base, > 0). */
+      set: (baseCurrency, quoteCurrency, rate) => apiRequest(ctx, "PUT", "/v1/settings/fx-rates", {
+        baseCurrency,
+        quoteCurrency,
+        rate
+      }),
+      /** Remove a `base → quote` rate. */
+      remove: (baseCurrency, quoteCurrency) => apiRequest(
+        ctx,
+        "DELETE",
+        `/v1/settings/fx-rates?base=${encodeURIComponent(baseCurrency)}&quote=${encodeURIComponent(quoteCurrency)}`
+      )
+    },
+    /** Transactional email templates (PRD-10): per-template subject/message overrides. */
+    emailTemplates: {
+      /** Every template, merged with this project's overrides, in display order. */
+      list: (options) => apiRequest(
+        ctx,
+        "GET",
+        "/v1/settings/email-templates",
+        void 0,
+        options
+      ).then((r) => r.templates),
+      /** Update one template's override (validated against its variable allowlist). */
+      update: (key, input) => apiRequest(
+        ctx,
+        "PUT",
+        `/v1/settings/email-templates/${encodeURIComponent(key)}`,
+        input
+      ).then((r) => r.template),
+      /**
+       * Send a `[Test]`-prefixed sample of one template to `to`. Dashboard-only:
+       * the API rejects developer keys (the dashboard restricts the recipient to
+       * the signed-in operator; a developer key has no such guarantee).
+       */
+      test: (key, to) => apiRequest(
+        ctx,
+        "POST",
+        `/v1/settings/email-templates/${encodeURIComponent(key)}/test`,
+        { to }
+      )
+    }
+  };
+}
+
+// src/resources/subscriptions.ts
+function createSubscriptionsResource(ctx) {
+  return {
+    /** Start a subscription -> returns the subscription plus a hosted checkout URL. `productId`
+     *  accepts the product's id or slug. Pass an `idempotencyKey` to make it safe to retry. */
+    create: (input, options) => apiRequest(ctx, "POST", "/v1/subscriptions", input, options),
+    /** Grant a free comp subscription (operator action). `productId` accepts the product's id or slug. */
+    comp: (input) => apiRequest(ctx, "POST", "/v1/subscriptions", {
+      ...input,
+      comp: true
+    }),
+    /** List subscriptions (paginated). Filters: status, customer (external id). */
+    list: (params = {}, options) => makeListPromise(
+      (p) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/subscriptions${toQuery(p)}`,
+        void 0,
+        options
+      ),
+      params
+    ),
+    get: (id, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/subscriptions/${encodeURIComponent(id)}`,
+      void 0,
+      options
+    ),
+    /**
+     * The single subscription that currently determines the customer's access, resolved by
+     * billow's own rule (access-granting statuses first, then newest) - or `null` if the
+     * customer has none. Prefer this over picking from `list()` yourself: it avoids the
+     * "newer failed-checkout subscription shadows an older active one" selection bug.
+     */
+    current: (params, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/subscriptions/current${toQuery(params)}`,
+      void 0,
+      options
+    ),
+    /** Cancel — immediately, or at period end with `{ atPeriodEnd: true }`. */
+    cancel: (id, opts) => apiRequest(
+      ctx,
+      "POST",
+      `/v1/subscriptions/${encodeURIComponent(id)}/cancel`,
+      opts ?? {}
+    ),
+    /** Reverse a scheduled period-end cancellation. Duplicate calls are safe. */
+    resumeCancellation: (id) => apiRequest(
+      ctx,
+      "POST",
+      `/v1/subscriptions/${encodeURIComponent(id)}/resume-cancellation`
+    ),
+    pause: (id) => apiRequest(ctx, "POST", `/v1/subscriptions/${encodeURIComponent(id)}/pause`),
+    resume: (id) => apiRequest(ctx, "POST", `/v1/subscriptions/${encodeURIComponent(id)}/resume`),
+    /** Apply a coupon to an existing subscription. */
+    applyCoupon: (id, code) => apiRequest(
+      ctx,
+      "POST",
+      `/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. */
+    changePlan: (id, productId) => apiRequest(ctx, "POST", `/v1/subscriptions/${encodeURIComponent(id)}/change-plan`, { productId }),
+    /** Clear a pending downgrade. Duplicate calls are safe. */
+    clearScheduledPlanChange: (id) => apiRequest(
+      ctx,
+      "DELETE",
+      `/v1/subscriptions/${encodeURIComponent(id)}/change-plan`
+    ),
+    items: {
+      /** List a subscription's items (base + add-ons). */
+      list: (id, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/subscriptions/${encodeURIComponent(id)}/items`,
+        void 0,
+        options
+      ).then((r) => r.items),
+      /** Attach an add-on Product. `productId` accepts the product's id or slug. */
+      add: (id, productId, quantity) => apiRequest(
+        ctx,
+        "POST",
+        `/v1/subscriptions/${encodeURIComponent(id)}/items`,
+        { productId, ...quantity != null ? { quantity } : {} }
+      ),
+      /** Change an item's quantity (seats). */
+      updateQuantity: (id, itemId, quantity) => apiRequest(
+        ctx,
+        "PATCH",
+        `/v1/subscriptions/${encodeURIComponent(id)}/items/${encodeURIComponent(itemId)}`,
+        { quantity }
+      ),
+      /** Detach an add-on item. */
+      remove: (id, itemId) => apiRequest(
+        ctx,
+        "DELETE",
+        `/v1/subscriptions/${encodeURIComponent(id)}/items/${encodeURIComponent(itemId)}`
+      )
+    }
+  };
+}
+
+// src/resources/webhook-endpoints.ts
+function createWebhookEndpointsResource(ctx) {
+  return {
+    /** Register an endpoint. The signing secret is returned once. */
+    create: (input) => apiRequest(ctx, "POST", "/v1/webhook-endpoints", input),
+    /** List endpoints (newest first; secrets are never returned). Auto-paginating. */
+    list: (params = {}, options) => makeListPromise(
+      (p) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/webhook-endpoints${toQuery(p)}`,
+        void 0,
+        options
+      ),
+      params
+    ),
+    /** Fetch one endpoint by id. */
+    get: (id, options) => apiRequest(
+      ctx,
+      "GET",
+      `/v1/webhook-endpoints/${encodeURIComponent(id)}`,
+      void 0,
+      options
+    ),
+    /** Update an endpoint's URL, enabled flag, or event filter. */
+    update: (id, input) => apiRequest(
+      ctx,
+      "PATCH",
+      `/v1/webhook-endpoints/${encodeURIComponent(id)}`,
+      input
+    ),
+    /** 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. */
+    rotateSecret: (id) => apiRequest(
+      ctx,
+      "POST",
+      `/v1/webhook-endpoints/${encodeURIComponent(id)}/rotate-secret`
+    ),
+    /** List delivery attempts for an endpoint (newest first). Auto-paginating. */
+    deliveries: (id, params = {}, options) => makeListPromise(
+      (p) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/webhook-endpoints/${encodeURIComponent(id)}/deliveries${toQuery(p)}`,
+        void 0,
+        options
+      ),
+      params
+    )
+  };
+}
+
+// src/index.ts
+var Billow = class {
+  #ctx;
+  customers;
+  charges;
+  checkoutMethods;
+  /** Prepaid credits: grant them to a Customer (quantities are decimal strings of microcredits). */
+  credits;
+  invoices;
+  metrics;
+  webhookEndpoints;
+  products;
+  subscriptions;
+  portalSessions;
+  deliverability;
+  marketplace;
+  /**
+   * Organization settings (Phase D3, F) — the configurable dunning schedule, usage settlement grace,
+   * and the cross-currency reporting currency + FX-rate registry (ADR-0013).
+   */
+  settings;
+  constructor(apiKey, opts = {}) {
+    if (!apiKey) throw new Error("billow: an API key is required");
+    this.#ctx = makeContext(apiKey, opts);
+    this.customers = createCustomersResource(this.#ctx);
+    this.charges = createChargesResource(this.#ctx);
+    this.checkoutMethods = createCheckoutMethodsResource(this.#ctx);
+    this.credits = createCreditsResource(this.#ctx);
+    this.invoices = createInvoicesResource(this.#ctx);
+    this.metrics = createMetricsResource(this.#ctx);
+    this.webhookEndpoints = createWebhookEndpointsResource(this.#ctx);
+    this.products = createProductsResource(this.#ctx);
+    this.subscriptions = createSubscriptionsResource(this.#ctx);
+    this.portalSessions = createPortalSessionsResource(this.#ctx);
+    this.deliverability = createDeliverabilityResource(this.#ctx);
+    this.marketplace = createMarketplaceResource(this.#ctx);
+    this.settings = createSettingsResource(this.#ctx);
+  }
+  #request(method, path, body, options) {
+    return apiRequest(this.#ctx, method, path, body, options);
+  }
+  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: (params = {}, options) => makeListPromise(
+      (p) => this.#request("GET", `/v1/coupons${toQuery(p)}`, void 0, options),
+      params
+    ),
+    /** 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.
+   *  (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`
+     * 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.
+     */
+    update: (slug, input) => this.#request("PATCH", `/v1/features/${encodeURIComponent(slug)}`, input),
+    /** List features in the tenant. Auto-paginating. */
+    list: (params = {}, options) => makeListPromise(
+      (p) => this.#request("GET", `/v1/features${toQuery(p)}`, void 0, options),
+      params
+    ),
+    /**
+     * Usage Alerts + Spend caps on a metered feature (Phase C). A `threshold`
+     * Alert notifies (webhook + optional customer email) as usage crosses its
+     * thresholds; a `cap` blocks `check` once reached.
+     */
+    alerts: {
+      /** List the alerts + spend cap on a metered feature (by slug). */
+      list: (feature, options) => this.#request(
+        "GET",
+        `/v1/features/${encodeURIComponent(feature)}/alerts`,
+        void 0,
+        options
+      ).then((r) => r.alerts),
+      /** Define an Alert or Spend cap on a metered feature. */
+      create: (feature, input) => this.#request(
+        "POST",
+        `/v1/features/${encodeURIComponent(feature)}/alerts`,
+        input
+      ),
+      /** Delete one alert/cap rule by id. */
+      remove: (feature, id) => this.#request(
+        "DELETE",
+        `/v1/features/${encodeURIComponent(feature)}/alerts/${encodeURIComponent(id)}`
+      )
+    }
+  };
+  integrations = {
+    /** The registered payment providers + their config manifests (drives the picker + form). */
+    providers: (options) => this.#request(
+      "GET",
+      "/v1/integrations/providers",
+      void 0,
+      options
+    ).then((r) => r.providers),
+    /** List configured credential sets per currency (provider + non-secret config). Secret-only. */
+    list: (options) => this.#request(
+      "GET",
+      "/v1/integrations",
+      void 0,
+      options
+    ).then((r) => r.integrations),
+    /**
+     * Verify a provider's configuration against its live API. Pass `currency` to
+     * 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
+     * the body, so `options` stays a separate trailing arg (never merged in).
+     */
+    verify: (provider, opts, options) => this.#request(
+      "POST",
+      "/v1/integrations/verify",
+      { provider, ...opts },
+      options
+    ),
+    /** Manage stored payment-provider credentials (the dashboard's "manage credentials" forms). */
+    credentials: {
+      /** The editable view of stored credential sets (secrets are never returned). */
+      list: (options) => this.#request(
+        "GET",
+        "/v1/integrations/credentials",
+        void 0,
+        options
+      ).then((r) => r.credentials),
+      /** Create or rotate a (provider, currency) credential set. */
+      upsert: (input) => this.#request("PUT", "/v1/integrations/credentials", input),
+      /** Delete a (provider, currency) credential set. */
+      remove: (provider, currency) => this.#request(
+        "DELETE",
+        `/v1/integrations/credentials/${encodeURIComponent(provider)}/${encodeURIComponent(currency)}`
+      )
+    }
+  };
+  /** 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(
+      "GET",
+      "/v1/business-profile",
+      void 0,
+      options
+    ).then((r) => r.profile),
+    /** Create or update the profile; omit a field to keep it, send "" to clear it. */
+    update: (input) => this.#request("PUT", "/v1/business-profile", input).then(
+      (r) => r.profile
+    )
+  };
+  /**
+   * 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
+   * 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. */
+  me(options) {
+    return this.#request("GET", "/v1/me", void 0, options);
+  }
+  /**
+   * Global search (PRD-12) across customers, invoices, subscriptions, and charges
+   * for the key's `(project, environment)`. Bounded per entity (default 5, max 10);
+   * a blank query returns empty results. Backs the dashboard's ⌘K palette.
+   */
+  search(q, limit, options) {
+    return this.#request(
+      "GET",
+      `/v1/search${toQuery({ q, limit })}`,
+      void 0,
+      options
+    );
+  }
+  // ── The headline verbs ──────────────────────────────────────────────
+  /**
+   * Gate access to a feature. `featureId` is the feature slug. Returns
+   * `{ 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
+   * safe to retry automatically when `maxRetries` is set.
+   */
+  track(input, options) {
+    return this.#request(
+      "POST",
+      "/v1/track",
+      input,
+      input.idempotencyKey ? { ...options, idempotencyKey: input.idempotencyKey } : options
+    );
+  }
+  /** List a customer's live entitlements (one per feature). */
+  entitlements(customerId, options) {
+    return this.#request(
+      "GET",
+      `/v1/customers/${encodeURIComponent(customerId)}/entitlements`,
+      void 0,
+      options
+    );
+  }
+  /** Start a subscription → returns a hosted checkout URL to redirect the customer to. */
+  attach(input, options) {
+    return this.#request("POST", "/v1/attach", input, options);
+  }
+};
+var BillowPublishable = class {
+  #ctx;
+  constructor(publishableKey, opts = {}) {
+    if (!publishableKey) throw new Error("billow: a publishable key is required");
+    if (!publishableKey.includes("_pk_")) {
+      throw new Error(
+        "billow: BillowPublishable needs a publishable key (bl_<env>_pk_\u2026), not a secret key"
+      );
+    }
+    this.#ctx = makeContext(publishableKey, opts);
+  }
+  products = {
+    /** The active catalog — products and their prices, for a pricing table. */
+    list: (options) => apiRequest(
+      this.#ctx,
+      "GET",
+      "/v1/products",
+      void 0,
+      options
+    ).then((r) => r.products),
+    /** Fetch one active product (with its prices) by slug. */
+    get: (slug, options) => apiRequest(
+      this.#ctx,
+      "GET",
+      `/v1/products/${encodeURIComponent(slug)}`,
+      void 0,
+      options
+    )
+  };
+};
+var BillowPortal = class {
+  #ctx;
+  constructor(sessionToken, opts = {}) {
+    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 lightweight payload the hosting app frames every page with, and the
+   *  validate-and-route check at login. */
+  session(options) {
+    return apiRequest(this.#ctx, "GET", "/portal/session", void 0, options);
+  }
+  /** The self-serve home payload: identity + subscriptions + usage + saved cards. */
+  me(options) {
+    return apiRequest(this.#ctx, "GET", "/portal/me", void 0, options);
+  }
+  invoices = {
+    /** The Customer's invoices (newest first). Auto-paginating. */
+    list: (params = {}, options) => makeListPromise(
+      (p) => apiRequest(
+        this.#ctx,
+        "GET",
+        `/portal/invoices${toQuery(p)}`,
+        void 0,
+        options
+      ),
+      params
+    ),
+    /** Open or resume checkout for this customer's outstanding invoice. */
+    pay: (id, input = {}, options) => apiRequest(
+      this.#ctx,
+      "POST",
+      `/portal/invoices/${encodeURIComponent(id)}/pay`,
+      input,
+      options
+    ),
+    /** Download one of the Customer's invoices as a PDF (raw bytes). */
+    pdf: (id, options) => apiRequestBinary(this.#ctx, "GET", `/portal/invoices/${encodeURIComponent(id)}/pdf`, options),
+    /** Download the payment receipt for one of the Customer's invoices (raw bytes). */
+    receiptPdf: (id, options) => apiRequestBinary(
+      this.#ctx,
+      "GET",
+      `/portal/invoices/${encodeURIComponent(id)}/receipt.pdf`,
+      options
+    )
+  };
+  subscriptions = {
+    /** Schedule one of the Customer's subscriptions to cancel at period end. */
+    cancel: (id) => apiRequest(
+      this.#ctx,
+      "POST",
+      `/portal/subscriptions/${encodeURIComponent(id)}/cancel`
+    ),
+    /** Reverse a scheduled period-end cancellation. */
+    resumeCancellation: (id) => apiRequest(
+      this.#ctx,
+      "POST",
+      `/portal/subscriptions/${encodeURIComponent(id)}/resume-cancellation`
+    ),
+    /** Move one of the Customer's subscriptions to another plan (upgrade now / downgrade scheduled). */
+    changePlan: (id, productId) => apiRequest(
+      this.#ctx,
+      "POST",
+      `/portal/subscriptions/${encodeURIComponent(id)}/plan`,
+      { productId }
+    ),
+    /** Clear a pending downgrade. */
+    clearScheduledPlanChange: (id) => apiRequest(
+      this.#ctx,
+      "DELETE",
+      `/portal/subscriptions/${encodeURIComponent(id)}/plan`
+    )
+  };
+  paymentMethod = {
+    /** Open a checkout to save or replace the Customer's card (zero-amount tokenization). */
+    update: (returnUrl) => apiRequest(
+      this.#ctx,
+      "POST",
+      "/portal/payment-method/update",
+      returnUrl ? { returnUrl } : {}
+    )
+  };
+  paymentMethods = {
+    list: (options) => apiRequest(
+      this.#ctx,
+      "GET",
+      "/portal/payment-methods",
+      void 0,
+      options
+    ).then((r) => r.paymentMethods),
+    setDefault: (id) => apiRequest(
+      this.#ctx,
+      "POST",
+      `/portal/payment-methods/${encodeURIComponent(id)}/default`
+    ),
+    remove: (id) => apiRequest(
+      this.#ctx,
+      "DELETE",
+      `/portal/payment-methods/${encodeURIComponent(id)}`
+    )
+  };
+  /** The checkout hand-off, for a session minted with `flow: "checkout"`. */
+  checkout = {
+    /** The plan being confirmed (product + base price). */
+    get: (options) => apiRequest(this.#ctx, "GET", "/portal/checkout", void 0, options),
+    /** Subscribe to the plan → returns the hosted Paymob checkout URL to redirect to. */
+    start: () => apiRequest(this.#ctx, "POST", "/portal/checkout")
+  };
+};
+
+export { BILLOW_ERROR_CODES, Billow, BillowApiError, BillowPortal, BillowPublishable, currencyExponent, formatMoney, isSecretField, toMajorUnits, toMinorUnits };
+//# sourceMappingURL=chunk-Z6VXPONT.js.map
+//# sourceMappingURL=chunk-Z6VXPONT.js.map