@usebillow/sdk 0.5.0 → 0.6.0

package/dist/billing-CgjcWmvb.d.ts

@@ -0,0 +1,371 @@
+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';
+
+/** Public SDK types for this domain. Re-exported by ../types.ts. */
+interface BillowOptions {
+    /**
+     * Base URL of the Billow API. Falls back to the `BILLOW_URL` env var, then to the hosted
+     * API at `https://api.usebillow.com`. Set it for local development (for example
+     * `http://localhost:4001`) or a self-hosted server.
+     */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /**
+     * Hard per-request timeout in milliseconds; the request is aborted once it elapses.
+     * Defaults to 60_000. Set `0` to disable the timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * 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
+     * `Retry-After` response header takes precedence when present. Defaults to 500.
+     */
+    retryBackoffMs?: number;
+}
+/**
+ * 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
+ *   verbatim on every attempt. Only exposed on writes the server replays (create/attach/track/refund).
+ */
+interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    idempotencyKey?: string;
+}
+/** Options for writes that require a stable idempotency key. */
+type IdempotentRequestOptions = RequestOptions & {
+    idempotencyKey: string;
+};
+/** Per-call overrides for reads and non-replayable writes — cancellation + timeout, no idempotency key. */
+type CallOptions = Omit<RequestOptions, "idempotencyKey">;
+interface Customer {
+    id: string;
+    externalId: string;
+    name?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    /** The customer's tax / VAT registration number, recorded on their invoices. */
+    taxId?: string | null;
+}
+/** How a price's tax relates to its amount: added on top (`exclusive`) or contained (`inclusive`). */
+type TaxBehavior = "exclusive" | "inclusive";
+interface CheckResult {
+    feature: string;
+    allowed: boolean;
+    balance: number | null;
+}
+interface AttachResult {
+    /** Hosted checkout URL to redirect the customer to (null if none was minted). */
+    url: string | null;
+    /** Null until a paid first-cycle checkout succeeds and creates the subscription. */
+    subscriptionId: string | null;
+    checkoutSessionId: string | null;
+}
+type BillingInterval = "day" | "week" | "month" | "year";
+type FeatureKind = "boolean" | "metered";
+type MeterAggregation = "count" | "sum" | "max" | "latest" | "count_unique";
+type MeterRoundingMode = "none" | "round" | "ceil" | "floor";
+interface MeterFilter {
+    key: string;
+    values: string[];
+}
+/** A meter's measurement config (ADR-0011) — how a metered feature's usage aggregates. */
+interface MeterConfig {
+    aggregation: MeterAggregation;
+    eventProperty?: string | null;
+    filters?: MeterFilter[];
+    roundingMode?: MeterRoundingMode;
+    roundingScale?: number | null;
+    /**
+     * Reset window anchoring (plan 07). Omitted/`cycle` = subscription anniversary in UTC
+     * (default). `calendar` tiles windows on calendar months in `resetTz` and REQUIRES a
+     * canonical IANA `resetTz` (e.g. `"Africa/Cairo"`, `"UTC"`).
+     */
+    resetAnchor?: "cycle" | "calendar";
+    resetTz?: string | null;
+}
+/** How a usage price turns billable quantity into money. */
+type UsageModel = "graduated" | "volume" | "package" | "percentage" | "stairstep";
+/** A usage-pricing tier (`upTo: null` = the unbounded last tier). */
+interface UsageTier {
+    upTo: number | null;
+    unitAmount: number;
+    flatAmount?: number;
+}
+
+/** Public SDK types for this domain. Re-exported by ../types.ts. */
+
+interface PriceInput {
+    /** `licensed` = per-unit recurring, billed × the subscription item's quantity (seats). */
+    kind: "fixed_recurring" | "licensed" | "one_time" | "usage";
+    interval?: BillingInterval;
+    intervalCount?: number;
+    /** Amount in minor units (per unit for `usage` prices without tiers). */
+    amount: number;
+    currency: string;
+    /** For `usage` prices: the metered feature's slug. */
+    meterFeature?: string;
+    /** For `usage` prices: the pricing model (default graduated). */
+    usageModel?: UsageModel;
+    /** For `usage` prices: tiers for graduated/volume/stairstep (overrides flat `amount`). */
+    usageTiers?: UsageTier[];
+    /** For `package` pricing: units per package (each priced at `amount`). */
+    packageSize?: number;
+    /** For `percentage` pricing: basis points of the metered amount. */
+    rateBps?: number;
+    /** Tax rate override in basis points; omit to inherit the org default, 0 = zero-rated. */
+    taxRateBps?: number | null;
+    /** Tax behavior override; omit to inherit the org default. */
+    taxBehavior?: TaxBehavior | null;
+}
+interface EntitlementInput {
+    /** The feature's slug (must already exist). */
+    feature: string;
+    /** Included units; `null`/omitted = unlimited. */
+    allowance?: number | null;
+    /** How often the balance refills; omitted = only on renewal. */
+    resetInterval?: BillingInterval;
+    rollover?: boolean;
+}
+interface CreateProductInput {
+    slug: string;
+    name: string;
+    type: "recurring" | "one_time";
+    isAddOn?: boolean;
+    /** Free-form string map that round-trips on the product + on subscription.* webhooks. */
+    metadata?: Record<string, string>;
+    prices: PriceInput[];
+    entitlements?: EntitlementInput[];
+}
+/** A price in a product edit: carry `id` to update that row in place, omit it to add. */
+type UpdatePriceInput = PriceInput & {
+    id?: string;
+};
+/** The result of migrating a plan's subscribers to another plan (ADR-0015). */
+interface MigrationResult {
+    /** How many subscriptions were moved to the target plan. */
+    migrated: number;
+    /** Subscriptions that couldn't be moved, with the reason (wrong currency, not active, …). */
+    skipped: Array<{
+        subscriptionId: string;
+        reason: string;
+    }>;
+}
+/**
+ * Edit a product (ADR-0015): rename, archive, and/or replace its prices/entitlements
+ * in place. `prices`/`entitlements`, when given, reconcile the latest version's rows
+ * (existing subscribers re-price at their next renewal).
+ */
+interface UpdateProductInput {
+    name?: string;
+    archived?: boolean;
+    /** Replace the product's metadata map. */
+    metadata?: Record<string, string>;
+    prices?: UpdatePriceInput[];
+    entitlements?: EntitlementInput[];
+}
+interface Feature {
+    id: string;
+    slug: string;
+    name: string;
+    kind: FeatureKind;
+    /** Meter config for metered features (ADR-0011); null/absent for boolean. */
+    meter?: MeterConfig | null;
+}
+/**
+ * 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
+ * been recorded (it would rewrite billed history). At least one field must be present.
+ */
+interface UpdateFeatureInput {
+    name?: string;
+    meter?: MeterConfig;
+}
+/** A usage-monitoring rule: a `threshold` Alert (notifies) or a `cap` (blocks). */
+type UsageAlertKind = "threshold" | "cap";
+/** How an alert threshold figure reads: absolute usage, percent used, or percent remaining. */
+type UsageAlertMetric = "absolute" | "percent_used" | "percent_remaining";
+/** A configured Alert / Spend cap on a metered feature (Phase C). */
+interface UsageAlert {
+    id: string;
+    kind: UsageAlertKind;
+    metric: UsageAlertMetric;
+    /** Threshold figures (units, or a percentage). One for a cap; one+ for an Alert. */
+    thresholds: number[];
+    /** Threshold Alerts: re-fire every N past the highest threshold; else null. */
+    recurringStep: number | null;
+    /** Threshold Alerts: also email the Customer (webhook always fires). */
+    notifyCustomer: boolean;
+    enabled: boolean;
+}
+interface CreateUsageAlertInput {
+    kind: UsageAlertKind;
+    metric: UsageAlertMetric;
+    thresholds: number[];
+    /** Threshold Alerts only: re-fire every N past the highest threshold. */
+    recurringStep?: number;
+    /** Threshold Alerts only: also email the Customer. */
+    notifyCustomer?: boolean;
+}
+interface TrackResult {
+    ok: true;
+    /** 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;
+}
+interface EntitlementView {
+    feature: string;
+    kind: FeatureKind;
+    allowed: boolean;
+    balance: number | null;
+}
+type ProductPrice = ProductPriceResponse;
+type ProductEntitlement = ProductEntitlementResponse;
+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). */
+type SubscriptionItem = SubscriptionItemResponse;
+interface CreateSubscriptionInput {
+    customerId: string;
+    /** The product slug to subscribe to. */
+    productId: string;
+    redirectionUrl?: string;
+    /** Optional coupon code to apply to the subscription. */
+    couponCode?: string;
+    /** Free-trial length in days (starts `trialing`, no charge until trial end). */
+    trialDays?: number;
+    /** For a trial, collect a card up front via tokenization (default true). */
+    collectCard?: boolean;
+    /** Units of the base price to bill (e.g. seats for a `licensed` plan); default 1. */
+    quantity?: number;
+    /** Limited term: total billing cycles before the subscription ends; omit = open-ended. */
+    cycles?: number;
+    /**
+     * The billing currency (Phase F, ADR-0013). Required only when the product has
+     * recurring prices in more than one currency; inferred when there's a single one.
+     */
+    currency?: string;
+}
+type CouponKind = "percent" | "fixed";
+type CouponDuration = "once" | "repeating" | "forever";
+interface CreateCouponInput {
+    code?: string;
+    kind: CouponKind;
+    /** percent: basis points (1% = 100 bps). fixed: minor units. */
+    value: number;
+    currency?: string;
+    duration: CouponDuration;
+    durationCycles?: number;
+    maxRedemptions?: number;
+    /** ISO-8601 timestamp. */
+    expiresAt?: string;
+    /** Product slugs the coupon is restricted to. */
+    productRestrictions?: string[];
+}
+interface Coupon {
+    id: string;
+    code: string | null;
+    kind: CouponKind;
+    value: number;
+    currency: string | null;
+    duration: CouponDuration;
+    durationCycles: number | null;
+    maxRedemptions: number | null;
+    redeemedCount: number;
+    expiresAt: string | null;
+    /** Set when an operator deactivated the coupon (it can no longer be applied). */
+    deactivatedAt?: string | null;
+    productRestrictions?: string[] | null;
+}
+type ActivatedSubscriptionResult = ActivatedSubscriptionResponse;
+type PendingSubscriptionCheckoutResult = PendingSubscriptionCheckoutResponse;
+type CreateSubscriptionResult = CreateSubscriptionResponse;
+/**
+ * Why a succeeded charge could not be applied to the invoice it paid, so its money awaits an
+ * Operator refund: `duplicate_payment` - another payment had already paid the invoice;
+ * `invoice_closed` - the invoice was voided or written off before this payment arrived.
+ */
+type UnappliedPaymentReason = "duplicate_payment" | "invoice_closed";
+interface Charge {
+    id: string;
+    status: ChargeStatus;
+    customerId: string;
+    customerExternalId: string;
+    invoiceId: string | null;
+    kind: "customer_present" | "mit";
+    subtotal: number;
+    tax: number;
+    total: number;
+    taxRateBps: number | null;
+    taxBehavior: "exclusive" | "inclusive" | null;
+    items: {
+        name: string;
+        amount: number;
+        quantity: number;
+        description?: string;
+    }[];
+    /** Backward-compatible alias of `total`, the amount sent to the provider. */
+    amount: number;
+    currency: string;
+    checkoutUrl: string | null;
+    specialReference: string;
+    providerTransactionId: string | null;
+    errorMessage: string | null;
+    /** Provider-reported dispute/chargeback (PRD-08), read-only. Null unless disputed. */
+    disputedAt: string | null;
+    disputeReason: string | null;
+    disputeId: string | null;
+    disputeAmount: number | null;
+    disputeState: "open" | "won" | "lost" | null;
+    /** Set when this payment could not be applied to its invoice; null otherwise. */
+    unappliedReason: UnappliedPaymentReason | null;
+    createdAt: string;
+}
+interface CreateChargeInput {
+    customerId: string;
+    /** Amount in minor units (e.g. piasters). */
+    amount: number;
+    currency: string;
+    /** Tax rate in basis points. When set, `taxBehavior` defaults to `exclusive`. */
+    taxRateBps?: number;
+    /** Whether `amount` excludes or includes tax. Requires `taxRateBps`. */
+    taxBehavior?: "exclusive" | "inclusive";
+    items?: {
+        name: string;
+        amount: number;
+        quantity: number;
+        description?: string;
+    }[];
+    /** Restrict the offered methods; omit to offer every method the merchant has configured. */
+    methods?: ("card" | "wallet" | "sympl" | "applepay")[];
+    saveCard?: boolean;
+    redirectionUrl?: string;
+}
+/** A standalone off-session charge against the customer's current saved card. */
+interface CreateMerchantInitiatedChargeInput {
+    customerId: string;
+    paymentMethodId: string;
+    amount: number;
+    currency: string;
+    items: {
+        name: string;
+        amount: number;
+        quantity: number;
+        description?: string;
+    }[];
+    taxRateBps?: number;
+    taxBehavior?: "exclusive" | "inclusive";
+}
+
+export type { AttachResult as A, BillowOptions as B, CreateProductInput as C, PriceInput as D, EntitlementView as E, FeatureKind as F, ProductEntitlement as G, ProductPrice as H, IdempotentRequestOptions as I, SubscriptionDetail as J, SubscriptionItem as K, UpdatePriceInput as L, MeterConfig as M, UsageAlertKind as N, UsageAlertMetric as O, Product as P, UsageModel as Q, RequestOptions as R, Subscription as S, TrackResult as T, UnappliedPaymentReason as U, UsageTier as V, CreateCouponInput as a, CheckResult as b, TaxBehavior as c, Customer as d, CreateChargeInput as e, Charge as f, CreateMerchantInitiatedChargeInput as g, CallOptions as h, UpdateProductInput as i, MigrationResult as j, CreateSubscriptionInput as k, Coupon as l, Feature as m, UpdateFeatureInput as n, UsageAlert as o, CreateUsageAlertInput as p, ActivatedSubscriptionResult as q, BillingInterval as r, CouponDuration as s, CouponKind as t, CreateSubscriptionResult as u, EntitlementInput as v, MeterAggregation as w, MeterFilter as x, MeterRoundingMode as y, PendingSubscriptionCheckoutResult as z };

package/dist/{chunk-Z6VXPONT.js → chunk-DYWGZRE2.js}

@@ -117,10 +117,10 @@ 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 apiRequest(ctx, method, path2, body, options) {
+  return (await apiRequestWithStatus(ctx, method, path2, body, options)).data;
 }
-async function apiRequestWithStatus(ctx, method, path, body, options) {
+async function apiRequestWithStatus(ctx, method, path2, body, options) {
   const init = {
     method,
     headers: {
@@ -130,7 +130,7 @@ async function apiRequestWithStatus(ctx, method, path, body, options) {
     }
   };
   if (body) init.body = JSON.stringify(body);
-  const res = await sendWithResilience(ctx, `${ctx.baseUrl}${path}`, init, {
+  const res = await sendWithResilience(ctx, `${ctx.baseUrl}${path2}`, init, {
     timeoutMs: options?.timeoutMs ?? ctx.timeoutMs,
     safeToRepeat: safeToRepeat(method, !!options?.idempotencyKey),
     callerSignal: options?.signal
@@ -176,10 +176,10 @@ function errorFrom(res, data) {
     requestIdOf(res)
   );
 }
-async function apiRequestBinary(ctx, method, path, options) {
+async function apiRequestBinary(ctx, method, path2, options) {
   const res = await sendWithResilience(
     ctx,
-    `${ctx.baseUrl}${path}`,
+    `${ctx.baseUrl}${path2}`,
     { method, headers: { authorization: `Bearer ${ctx.bearer}` } },
     {
       timeoutMs: options?.timeoutMs ?? ctx.timeoutMs,
@@ -487,11 +487,14 @@ function createCreditsResource(ctx) {
        * 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.
+       * buys nothing again - asking the payment provider again for a checkout the first attempt
+       * could not open, within its page's 40 minutes (Stripe only in the first 10, while 30
+       * remain: it answers a timed-out first attempt with the checkout it made, or makes one never
+       * made; Paymob only if the first attempt never made one); reusing it for another purchase
+       * throws `idempotency_conflict` (409). A retry can also throw `conflict` (409), with
+       * `details.reason`: `checkout_in_progress` - another 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(
@@ -573,6 +576,155 @@ function createCreditsResource(ctx) {
         void 0,
         options
       )
+    },
+    rateCards: {
+      /**
+       * Publish a new Rate Card version: what each Credit Action costs, as
+       * `ceil(units * unitPrice / perUnits)` microcredits a line. Versions are immutable - a price
+       * change is a new version - and take effect in order, at `effectiveAt` (now when omitted).
+       */
+      publish: (input, options) => apiRequest(ctx, "POST", "/v1/credits/rate-cards", input, options),
+      /** The version in effect now (`not_found` before the first takes effect). */
+      current: (options) => apiRequest(
+        ctx,
+        "GET",
+        "/v1/credits/rate-cards/current",
+        void 0,
+        options
+      ),
+      /** One version, by its number. */
+      get: (version, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/rate-cards/${encodeURIComponent(String(version))}`,
+        void 0,
+        options
+      ),
+      /**
+       * The published versions, newest first. Auto-paginating by cursor: `await` the first page,
+       * `for await (…)` every version, or `.listAll()` to collect them.
+       */
+      list: (params = {}, options) => makeCursorListPromise(
+        (p) => apiRequest(
+          ctx,
+          "GET",
+          `/v1/credits/rate-cards${toQuery(p)}`,
+          void 0,
+          options
+        ),
+        params
+      )
+    },
+    quotes: {
+      /**
+       * Price a customer's Credit Actions (all of one category) at the current Rate Card version
+       * and keep the price for 15 minutes: a reservation over the quote holds exactly its
+       * `amount`, and its commit prices at the version the quote pinned. A quote holds nothing.
+       */
+      create: (input, options) => apiRequest(ctx, "POST", "/v1/credits/quotes", input, options),
+      /** A quote as it was made. */
+      get: (quoteId, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/quotes/${encodeURIComponent(quoteId)}`,
+        void 0,
+        options
+      )
+    },
+    reservations: {
+      /**
+       * Hold credits for one operation: over a `quoteId`, or over `items` priced at the current
+       * Rate Card version. The `idempotencyKey` is required: a retry under it - after a lost
+       * reply, even once the quote expired - answers the same reservation (`replayed: true`) and
+       * holds nothing again. Reusing it for another request, or a new key with an `operationKey`
+       * the customer already used (`details.reason: "operation_key_used"`), throws
+       * `idempotency_conflict` (409). Throws `insufficient_credits` (402), `account_frozen`
+       * (423), `account_closed` (409), `conflict` (409, `details.reason: "quote_expired"`), or
+       * `validation_error` (422) - e.g. `details.reason: "zero_amount"` when the items cost nothing.
+       * The `operationKey` is an operation id, never personal data: erasure replaces it.
+       */
+      create: async (input, options) => {
+        const { status, data } = await apiRequestWithStatus(
+          ctx,
+          "POST",
+          "/v1/credits/reservations",
+          input,
+          options
+        );
+        return { ...data, replayed: status === 200 };
+      },
+      /** A reservation as it now stands. */
+      get: (reservationId, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/reservations/${encodeURIComponent(reservationId)}`,
+        void 0,
+        options
+      ),
+      /**
+       * A customer's reservation (by external id) made with `operationKey` - how to find one whose
+       * reply was lost. Throws `not_found` (404) when there is none.
+       */
+      findByOperationKey: (customer, operationKey, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/reservations${toQuery({ customer, operationKey })}`,
+        void 0,
+        options
+      ),
+      /**
+       * Commit what the operation used: lines priced at the reservation's Rate Card version,
+       * consuming at most what it holds (`commit_exceeds_hold`, 409) and releasing the rest; lines
+       * that cost nothing in all consume nothing (`consumed: "0"`, `consumptionId: null`). The
+       * same commit again answers it again, so it is safe to retry; anything else after it throws
+       * `invalid_state_transition` (409) with the reservation in `details` - with
+       * `details.reason: "reservation_expired"` once the hold is past its `expiresAt`.
+       */
+      commit: (reservationId, items, options) => apiRequest(
+        ctx,
+        "POST",
+        `/v1/credits/reservations/${encodeURIComponent(reservationId)}/commit`,
+        { items },
+        options
+      ),
+      /** Release the whole hold. Safe to retry; after a commit it throws (409). */
+      release: (reservationId, options) => apiRequest(
+        ctx,
+        "POST",
+        `/v1/credits/reservations/${encodeURIComponent(reservationId)}/release`,
+        void 0,
+        options
+      ),
+      /**
+       * Protect a held reservation whose operation was paid for and is still being fulfilled: it
+       * never expires (commit or release it when done). Safe to retry. A hold already past its
+       * `expiresAt` throws `invalid_state_transition` (409, `details.reason: "reservation_expired"`).
+       */
+      protect: (reservationId, options) => apiRequest(
+        ctx,
+        "POST",
+        `/v1/credits/reservations/${encodeURIComponent(reservationId)}/protect`,
+        void 0,
+        options
+      )
+    },
+    consumptions: {
+      /**
+       * Give back part or all of a commit's consumption (`consumptionId` on the committed
+       * reservation), never more than is left (`reversal_exceeds_consumption`, 409). The
+       * `idempotencyKey` is required: a retry under it answers the same reversal
+       * (`replayed: true`) and gives nothing back again.
+       */
+      reverse: async (consumptionId, input, options) => {
+        const { status, data } = await apiRequestWithStatus(
+          ctx,
+          "POST",
+          `/v1/credits/consumptions/${encodeURIComponent(consumptionId)}/reverse`,
+          input,
+          options
+        );
+        return { ...data, replayed: status === 200 };
+      }
     }
   };
 }
@@ -685,6 +837,33 @@ function createDeliverabilityResource(ctx) {
   };
 }
 
+// src/resources/hosted-domains.ts
+var path = (id, action = "") => `/v1/hosted-domains/${encodeURIComponent(id)}${action}`;
+function createHostedDomainsResource(ctx) {
+  return {
+    /** The Project's domains, and whether its plan allows adding more (`whiteLabel`). */
+    list: (options) => apiRequest(ctx, "GET", "/v1/hosted-domains", void 0, options),
+    /**
+     * Add a subdomain such as `billing.example.com`. Answers the domain with the TXT and CNAME
+     * `records` to create. Needs a plan with white-label branding (`permission_denied` otherwise).
+     */
+    create: (input, options) => apiRequest(ctx, "POST", "/v1/hosted-domains", input, options),
+    get: (id, options) => apiRequest(ctx, "GET", path(id), void 0, options),
+    /** Check the DNS records now (2 per minute per domain); answers the refreshed domain. */
+    verify: (id, options) => apiRequest(ctx, "POST", path(id, "/verify"), void 0, options),
+    /** Make an active domain the default host for new portal sessions. */
+    makePrimary: (id, options) => apiRequest(ctx, "POST", path(id, "/primary"), void 0, options),
+    /** Remove a domain; the portal sessions on it end immediately. */
+    remove: (id, options) => apiRequest(
+      ctx,
+      "DELETE",
+      path(id),
+      void 0,
+      options
+    )
+  };
+}
+
 // src/resources/invoices.ts
 function createInvoicesResource(ctx) {
   return {
@@ -1150,6 +1329,8 @@ var Billow = class {
   portalSessions;
   deliverability;
   marketplace;
+  /** 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,
    * and the cross-currency reporting currency + FX-rate registry (ADR-0013).
@@ -1170,10 +1351,11 @@ var Billow = class {
     this.portalSessions = createPortalSessionsResource(this.#ctx);
     this.deliverability = createDeliverabilityResource(this.#ctx);
     this.marketplace = createMarketplaceResource(this.#ctx);
+    this.hostedDomains = createHostedDomainsResource(this.#ctx);
     this.settings = createSettingsResource(this.#ctx);
   }
-  #request(method, path, body, options) {
-    return apiRequest(this.#ctx, method, path, body, options);
+  #request(method, path2, body, options) {
+    return apiRequest(this.#ctx, method, path2, body, options);
   }
   coupons = {
     /** Define a coupon (a reusable discount template). */
@@ -1489,5 +1671,5 @@ var BillowPortal = class {
 };
 
 export { BILLOW_ERROR_CODES, Billow, BillowApiError, BillowPortal, BillowPublishable, currencyExponent, formatMoney, isSecretField, toMajorUnits, toMinorUnits };
-//# sourceMappingURL=chunk-Z6VXPONT.js.map
-//# sourceMappingURL=chunk-Z6VXPONT.js.map
+//# sourceMappingURL=chunk-DYWGZRE2.js.map
+//# sourceMappingURL=chunk-DYWGZRE2.js.map