@usebillow/sdk 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -1,11 +1,13 @@
-import { c as TaxBehavior, d as Customer, U as UnappliedPaymentReason, S as SavedPaymentMethod, e as CreateChargeInput, R as RequestOptions, f as Charge, g as CreateMerchantInitiatedChargeInput, I as IdempotentRequestOptions, h as CallOptions, i as PayInvoiceInput, C as CreateProductInput, j as UpdateProductInput, k as MigrationResult, l as CreateSubscriptionInput, B as BillowOptions, a as CreateCouponInput, m as Coupon, F as FeatureKind, M as MeterConfig, n as Feature, o as UpdateFeatureInput, p as UsageAlert, q as CreateUsageAlertInput, b as CheckResult, T as TrackResult, E as EntitlementView, A as AttachResult } from './billing-DZ4rIyg7.cjs';
-export { r as ActivatedSubscriptionResult, s as BillingInterval, t as ContractAddSubscriptionItemInput, u as ContractApplySubscriptionCouponInput, v as ContractCancelSubscriptionInput, w as ContractChangeSubscriptionPlanInput, x as ContractCreateChargeInput, y as ContractCreateCustomerInput, z as ContractCreateMerchantInitiatedChargeInput, D as ContractCreatePortalSessionInput, G as ContractCreateProductInput, H as ContractCreateSubscriptionInput, J as ContractCreateWebhookEndpointInput, K as ContractMigrateSubscribersInput, L as ContractRefundChargeInput, N as ContractResolveRefundInput, O as ContractUpdateProductInput, Q as ContractUpdateSubscriptionItemInput, V as ContractUpdateWebhookEndpointInput, W as CouponDuration, X as CouponKind, Y as CreateSubscriptionResult, Z as EntitlementInput, _ as InvoicePaymentResult, $ as MeterAggregation, a0 as MeterFilter, a1 as MeterRoundingMode, a2 as PendingSubscriptionCheckoutResult, a3 as PriceInput, P as Product, a4 as ProductEntitlement, a5 as ProductPrice, a6 as Subscription, a7 as SubscriptionDetail, a8 as SubscriptionItem, a9 as UpdatePriceInput, aa as UsageAlertKind, ab as UsageAlertMetric, ac as UsageModel, ad as UsageTier } from './billing-DZ4rIyg7.cjs';
+import { f as SavedPaymentMethod, g as CreateHostedDomainInput, h as PayInvoiceInput } from './index.d-CKQAhQfJ.cjs';
+export { i as ContractAddSubscriptionItemInput, j as ContractApplySubscriptionCouponInput, k as ContractCancelSubscriptionInput, l as ContractChangeSubscriptionPlanInput, m as ContractCreateChargeInput, n as ContractCreateCustomerInput, o as ContractCreateMerchantInitiatedChargeInput, p as ContractCreatePortalSessionInput, q as ContractCreateProductInput, r as ContractCreateSubscriptionInput, s as ContractCreateWebhookEndpointInput, M as ContractMigrateSubscribersInput, R as ContractRefundChargeInput, t as ContractResolveRefundInput, U as ContractUpdateProductInput, u as ContractUpdateSubscriptionItemInput, v as ContractUpdateWebhookEndpointInput, H as HostedDomain, w as HostedDomainList, I as InvoicePaymentResult } from './index.d-CKQAhQfJ.cjs';
 import { C as ChargeStatus, P as PaymentMethodStatus, I as InvoiceStatus, R as RefundStatus, W as WebhookDeliveryStatus } from './billing-status-BZQN_gm7.cjs';
 export { a as CHARGE_STATUSES, b as INVOICE_STATUSES, c as PAYMENT_METHOD_STATUSES, d as REFUND_STATUSES, e as WEBHOOK_DELIVERY_STATUSES } from './billing-status-BZQN_gm7.cjs';
 import { SubscriptionStatus } from './status.cjs';
 export { ACTIVE_SUBSCRIPTION_STATUSES, NEVER_ACTIVATED_SUBSCRIPTION_STATUSES, SUBSCRIPTION_STATUSES, TERMINAL_SUBSCRIPTION_STATUSES, grantsAccess, isTerminal } from './status.cjs';
-import { a as CreditThresholdLevel, b as CreditGrant, c as CreditTopUp, d as CreateCreditGrantInput, e as CreditGrantRequestResult, f as CreditPacks, g as CreateCreditPackInput, h as CreditPack, U as UpdateCreditPackInput, i as CreateCreditTopUpInput, j as CreditTopUpRequestResult, k as CreditTopUpListParams, l as CreditBalance, m as CreditLedgerEntry, n as CreditUsageParams, o as CreditUsage } from './credits-C3Fe3TO0.cjs';
-export { p as CreditAccountStatus, C as CreditGrantKind, q as CreditMoney, r as CreditPackListItem, s as CreditTopUpStatus, t as CreditTransactionType, u as CreditUsageGroupBy } from './credits-C3Fe3TO0.cjs';
+import { c as TaxBehavior, d as Customer, U as UnappliedPaymentReason, e as CreateChargeInput, R as RequestOptions, f as Charge, g as CreateMerchantInitiatedChargeInput, I as IdempotentRequestOptions, h as CallOptions, C as CreateProductInput, i as UpdateProductInput, j as MigrationResult, k as CreateSubscriptionInput, B as BillowOptions, a as CreateCouponInput, l as Coupon, F as FeatureKind, M as MeterConfig, m as Feature, n as UpdateFeatureInput, o as UsageAlert, p as CreateUsageAlertInput, b as CheckResult, T as TrackResult, E as EntitlementView, A as AttachResult } from './billing-B-VyZCXV.cjs';
+export { q as ActivatedSubscriptionResult, r as BillingInterval, s as CouponDuration, t as CouponKind, u as CreateSubscriptionResult, v as EntitlementInput, w as MeterAggregation, x as MeterFilter, y as MeterRoundingMode, z as PendingSubscriptionCheckoutResult, D as PriceInput, P as Product, G as ProductEntitlement, H as ProductPrice, S as Subscription, J as SubscriptionDetail, K as SubscriptionItem, L as UpdatePriceInput, N as UsageAlertKind, O as UsageAlertMetric, Q as UsageModel, V as UsageTier } from './billing-B-VyZCXV.cjs';
+import { a as CreditThresholdLevel, e as CreditGrant, f as CreditTopUp, g as CreateCreditGrantInput, h as CreditGrantRequestResult, i as CreditPacks, j as CreateCreditPackInput, k as CreditPack, U as UpdateCreditPackInput, l as CreateCreditTopUpInput, m as CreditTopUpRequestResult, n as CreditTopUpListParams, o as CreditBalance, p as CreditLedgerEntry, q as CreditUsageParams, r as CreditUsage } from './hosted-domains-BYYl2DSa.cjs';
+export { s as CreditAccountStatus, C as CreditGrantKind, t as CreditMoney, u as CreditPackBreakdown, v as CreditPackListItem, w as CreditTopUpStatus, x as CreditTransactionType, y as CreditUsageGroupBy, H as HostedDomainActivatedData, d as HostedDomainDisabledData, b as HostedDomainDnsFailingData, z as HostedDomainEventBase, c as HostedDomainReassignmentPendingData, A as HostedDomainStatus, B as HostedDomainStatusReason } from './hosted-domains-BYYl2DSa.cjs';
 import 'zod';
 
 /**
@@ -703,6 +705,192 @@ interface Whoami {
     /** Currencies configured for this Project (payment credential sets). */
     currencies: string[];
     defaultCurrency: string;
+    /** Whether the Project's custom-domain endpoints (`hostedDomains`) are open: live only, behind a rollout flag. */
+    hostedDomainsEnabled: boolean;
+}
+
+/**
+ * Public SDK types for Rate Cards, quotes, credit reservations and consumption reversals.
+ * Re-exported by ../types.ts.
+ *
+ * Every credit quantity - and every count of units - is a `string` of a whole number, e.g.
+ * `"5000000"` for 5 credits: never a `number`, which would silently round past 2^53.
+ */
+/** One Credit Action's price in a Rate Card version: `ceil(units * unitPrice / perUnits)` a line. */
+interface CreditRateCardItem {
+    /** The Credit Action key, e.g. `send_message`. */
+    action: string;
+    /** The category it is spent from: a reservation holds one category. */
+    category: string;
+    /** Microcredits per `perUnits` units. */
+    unitPrice: string;
+    /** How many units `unitPrice` buys. */
+    perUnits: string;
+}
+/** An immutable Rate Card version: a price change is a new version. */
+interface CreditRateCard {
+    id: string;
+    /** 1, 2, 3... in the order versions were published (and take effect). */
+    version: number;
+    /** From when it prices new quotes and reservations made from items. */
+    effectiveAt: string;
+    /** Its prices, by action. */
+    items: CreditRateCardItem[];
+    createdAt: string;
+}
+/** Publish a new Rate Card version: every Credit Action it prices, once each. */
+interface PublishCreditRateCardInput {
+    /**
+     * When it takes effect (ISO 8601 with a timezone): now when omitted; never in the past, nor
+     * before the version before it takes effect.
+     */
+    effectiveAt?: string;
+    items: Array<{
+        /** 1-100 lowercase letters, digits, dots, hyphens or underscores. */
+        action: string;
+        category: string;
+        /** Whole microcredits as a decimal string; "0" for an action that costs nothing. */
+        unitPrice: string;
+        /** Whole units as a decimal string; "1" when omitted. */
+        perUnits?: string;
+    }>;
+}
+/** Opaque context on a line (e.g. a model name), unpriced: a JSON object of at most 4 KiB. */
+type CreditDimensions = Record<string, unknown>;
+/** One line of a quote or a commit: a Credit Action and how many units of it. */
+interface CreditLineItem {
+    action: string;
+    /** Whole units as a decimal string, positive. */
+    units: string;
+    /** Never personal data: what a commit records stays with the ledger for good. */
+    dimensions?: CreditDimensions | null;
+}
+/** A line as priced, with the terms it was priced on. */
+interface CreditPricedLine {
+    action: string;
+    units: string;
+    unitPrice: string;
+    perUnits: string;
+    /** `ceil(units * unitPrice / perUnits)` microcredits. */
+    amount: string;
+    dimensions: CreditDimensions | null;
+}
+/** Price a customer's Credit Actions (all of one category) at the current Rate Card version. */
+interface CreateCreditQuoteInput {
+    /** The customer's external id. */
+    customerId: string;
+    /** 1 to 100 lines. */
+    items: CreditLineItem[];
+}
+/** A quote: what the lines cost at the version it pins, reservable until `expiresAt` (15 minutes). */
+interface CreditQuote {
+    id: string;
+    /** The customer's external id. */
+    customerId: string;
+    rateCardVersion: number;
+    category: string;
+    /** What the lines cost in all: what a reservation over the quote holds. */
+    amount: string;
+    items: CreditPricedLine[];
+    expiresAt: string;
+    createdAt: string;
+}
+/**
+ * A credit reservation's state: `held` until committed, released or expired; `protected` (paid
+ * for, still being fulfilled) never expires; `committed`, `released` and `expired` are final.
+ */
+type CreditReservationStatus = "held" | "protected" | "committed" | "released" | "expired";
+/** Credits held for one operation. */
+interface CreditReservation {
+    id: string;
+    /** The customer's external id. */
+    customerId: string;
+    /** Your own id for the operation, unique per customer. */
+    operationKey: string;
+    category: string;
+    /** Microcredits held when it was made. */
+    amount: string;
+    /** Microcredits its commit consumed (the rest was released with it). */
+    consumed: string;
+    status: CreditReservationStatus;
+    /** The quote it was made over; null when made from items. */
+    quoteId: string | null;
+    /** The Rate Card version its commit prices at. */
+    rateCardVersion: number;
+    /** When it is released if still `held`. */
+    expiresAt: string;
+    protectedAt: string | null;
+    settledAt: string | null;
+    /**
+     * The commit's consumption: what `credits.consumptions.reverse` names. Null until committed, and
+     * for a commit that cost nothing (it consumed nothing).
+     */
+    consumptionId: string | null;
+    metadata: Record<string, string> | null;
+    createdAt: string;
+}
+/** What a reservation holds for and how it is identified; give `quoteId` or `items`. */
+interface CreateCreditReservationBase {
+    /** The customer's external id. */
+    customerId: string;
+    /**
+     * Your own id for the operation (1-255 characters), unique per customer. Never personal data:
+     * erasure replaces it with `erased_<reservation id>`, a prefix you may not use.
+     */
+    operationKey: string;
+    /** How long the hold lasts unsettled; your project's default when omitted, up to its maximum. */
+    ttlSeconds?: number;
+    /** At most 20 keys (40 characters) and values (500 characters). Never personal data. */
+    metadata?: Record<string, string>;
+}
+/** Hold credits over a quote (its amount, at the version it pins), or over Credit Actions. */
+type CreateCreditReservationInput = CreateCreditReservationBase & ({
+    quoteId: string;
+    items?: never;
+} | {
+    /** Priced at the current version, all of one category; 1 to 100 lines. */
+    items: Array<{
+        action: string;
+        units: string;
+    }>;
+    quoteId?: never;
+});
+/** What `credits.reservations.create` answers: the reservation its idempotency key stands for. */
+interface CreditReservationRequestResult extends CreditReservation {
+    /**
+     * `true` when the idempotency key was already used: this is the reservation that earlier request
+     * made, as it was made, and nothing new was held. `false` when this call made it.
+     */
+    replayed: boolean;
+}
+/** Give back part or all of what a commit consumed. */
+interface ReverseCreditConsumptionInput {
+    /** Positive whole microcredits as a decimal string. */
+    amount: string;
+    /** Why (at most 500 characters), kept on the reversal and cleared on erasure. */
+    reason?: string;
+    /** At most 20 keys (40 characters) and values (500 characters). Never personal data. */
+    metadata?: Record<string, string>;
+}
+/** A consumption reversal. */
+interface CreditReversal {
+    id: string;
+    /** The customer's external id. */
+    customerId: string;
+    consumptionId: string;
+    /** The `reverse` ledger transaction. */
+    transactionId: string;
+    amount: string;
+    /** Of `amount`, what came back to a grant past its expiry and expired again at once. */
+    forfeited: string;
+    reason: string | null;
+    metadata: Record<string, string> | null;
+    createdAt: string;
+}
+/** What `credits.consumptions.reverse` answers: the reversal its idempotency key stands for. */
+interface CreditReversalRequestResult extends CreditReversal {
+    /** `true` when an earlier request under the key made it, and nothing was given back again. */
+    replayed: boolean;
 }
 
 /** What surface a portal session lands the Customer on. */
@@ -714,10 +902,18 @@ interface CreatePortalSessionInput {
     flow?: PortalSessionFlow;
     /** Product slug to subscribe to — required when `flow` is `checkout`. */
     productId?: string;
-    /** Where the surface returns the Customer when they finish or exit. */
+    /**
+     * Where the surface returns the Customer when they finish or exit: an absolute `https` URL
+     * without credentials (and, in live, without a port other than 443). A loopback host such as
+     * `localhost` is also accepted over `http`, on any port, in either environment.
+     */
     returnUrl?: string;
 }
-/** The minted portal session: redirect the Customer to `url` (it carries the bearer). */
+/**
+ * The minted portal session: redirect the Customer to `url` at once. Its token is a single-use
+ * entry token - Billow's hosted portal exchanges it on first open, after which the link works
+ * only for the browser that opened it.
+ */
 interface PortalSession {
     id: string;
     url: string;
@@ -725,6 +921,21 @@ interface PortalSession {
     /** ISO-8601 expiry — the session (and its URL) stop working after this. */
     expiresAt: string;
 }
+/** The single-use entry exchange's input (`BillowPortal.exchange`). */
+interface PortalSessionExchangeInput {
+    /** The `Host` the link was opened on: it must be the host the session is bound to. */
+    host: string;
+    /** The session token the browser already holds, if any: a revisit by the browser that
+     *  exchanged the link lands on its own session, and only that browser's. */
+    sessionToken?: string;
+}
+/** What the exchange returns: the session's bearer from now on, and its unchanged expiry. */
+interface PortalSessionExchange {
+    sessionToken: string;
+    flow: PortalSessionFlow;
+    /** ISO-8601 expiry of the session, set when it was minted. */
+    expiresAt: string;
+}
 /**
  * The portal shell: the session's flow + return URL, the merchant's
  * customer-facing brand, and the Customer's identity. The lightweight payload a
@@ -944,41 +1155,13 @@ interface CustomerCreditsExport {
         updatedAt: string;
     } | null;
     grants: CreditGrant[];
-    reservations: Array<{
-        id: string;
-        /** The customer's external id. */
-        customerId: string;
-        operationKey: string;
-        category: string;
-        amount: string;
-        consumed: string;
-        status: "held" | "protected" | "committed" | "released" | "expired";
-        expiresAt: string;
-        protectedAt: string | null;
-        settledAt: string | null;
-        /** The commit's `consume` ledger transaction. */
-        consumptionId: string | null;
-        metadata: Record<string, string> | null;
-        createdAt: string;
-    }>;
+    reservations: CreditReservation[];
     /** Every credit top-up, as it now stands. */
     topUps: CreditTopUp[];
     /** Every consumption reversal, with your own reason and metadata (cleared on erasure). */
-    reversals: Array<{
-        id: string;
-        /** The customer's external id. */
-        customerId: string;
-        /** The consumption reversed: its commit's `consume` ledger transaction. */
-        consumptionId: string;
-        /** The `reverse` ledger transaction. */
-        transactionId: string;
-        amount: string;
-        /** Of `amount`, what came back to an expired grant and expired again at once. */
-        forfeited: string;
-        reason: string | null;
-        metadata: Record<string, string> | null;
-        createdAt: string;
-    }>;
+    reversals: CreditReversal[];
+    /** Every quote made for the customer (even with no credit account), with its priced lines. */
+    quotes: CreditQuote[];
     /** Every ledger transaction, in the order it was written, with its postings. */
     ledger: Array<{
         id: string;
@@ -1268,11 +1451,14 @@ declare function createCreditsResource(ctx: RequestContext): {
          * 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: (input: CreateCreditTopUpInput, options: IdempotentRequestOptions) => Promise<CreditTopUpRequestResult>;
         /** A top-up as it now stands: status, checkout, grants, and what refunds revoked. */
@@ -1307,6 +1493,80 @@ declare function createCreditsResource(ctx: RequestContext): {
          */
         get: (customer: string, params?: CreditUsageParams, options?: CallOptions) => Promise<CreditUsage>;
     };
+    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: PublishCreditRateCardInput, options?: CallOptions) => Promise<CreditRateCard>;
+        /** The version in effect now (`not_found` before the first takes effect). */
+        current: (options?: CallOptions) => Promise<CreditRateCard>;
+        /** One version, by its number. */
+        get: (version: number, options?: CallOptions) => Promise<CreditRateCard>;
+        /**
+         * The published versions, newest first. Auto-paginating by cursor: `await` the first page,
+         * `for await (…)` every version, or `.listAll()` to collect them.
+         */
+        list: (params?: CursorListParams, options?: CallOptions) => CursorListPromise<CreditRateCard>;
+    };
+    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: CreateCreditQuoteInput, options?: CallOptions) => Promise<CreditQuote>;
+        /** A quote as it was made. */
+        get: (quoteId: string, options?: CallOptions) => Promise<CreditQuote>;
+    };
+    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: (input: CreateCreditReservationInput, options: IdempotentRequestOptions) => Promise<CreditReservationRequestResult>;
+        /** A reservation as it now stands. */
+        get: (reservationId: string, options?: CallOptions) => Promise<CreditReservation>;
+        /**
+         * 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: string, operationKey: string, options?: CallOptions) => Promise<CreditReservation>;
+        /**
+         * 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: string, items: CreditLineItem[], options?: CallOptions) => Promise<CreditReservation>;
+        /** Release the whole hold. Safe to retry; after a commit it throws (409). */
+        release: (reservationId: string, options?: CallOptions) => Promise<CreditReservation>;
+        /**
+         * 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: string, options?: CallOptions) => Promise<CreditReservation>;
+    };
+    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: (consumptionId: string, input: ReverseCreditConsumptionInput, options: IdempotentRequestOptions) => Promise<CreditReversalRequestResult>;
+    };
 };
 
 declare function createCustomersResource(ctx: RequestContext): {
@@ -1376,6 +1636,272 @@ declare function createDeliverabilityResource(ctx: RequestContext): {
     inbound: (params?: InboundWebhookListParams, options?: CallOptions) => ListPromise<InboundWebhookListItem>;
 };
 
+/**
+ * Custom domains for the hosted customer portal (live keys only, behind a per-Project rollout
+ * flag). Add a hostname, create the two DNS records it answers, and Billow verifies them.
+ */
+declare function createHostedDomainsResource(ctx: RequestContext): {
+    /** The Project's domains, and whether its plan allows adding more (`whiteLabel`). */
+    list: (options?: CallOptions) => Promise<{
+        data: {
+            id: string;
+            hostname: string;
+            hostnameUnicode: string;
+            environment: "live";
+            status: "failed" | "active" | "pending_verification" | "verified" | "disabled";
+            statusReason: "verification_expired" | "tls_unavailable" | "edge_blocked" | "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended" | null;
+            isPrimary: boolean;
+            records: {
+                type: "TXT" | "CNAME";
+                name: string;
+                value: string;
+            }[];
+            dns: {
+                checkedAt: string | null;
+                failingSince: string | null;
+                graceEndsAt: string | null;
+                txt: {
+                    status: "found" | "missing" | "inconclusive" | null;
+                    values: string[];
+                };
+                cname: {
+                    status: "found" | "missing" | "inconclusive" | "wrong" | null;
+                    chain: string[];
+                };
+            };
+            edge: {
+                status: string | null;
+                sslStatus: string | null;
+                errors: string[];
+                certificateExpiresAt: string | null;
+                checkedAt: string | null;
+            };
+            reassignment: {
+                role: "owner" | "claimant";
+                dueAt: string;
+            } | null;
+            entitlementLapse: {
+                lapsedAt: string;
+                servingEndsAt: string;
+                disablesAt: string;
+            } | null;
+            verificationExpiresAt: string | null;
+            verifiedAt: string | null;
+            activatedAt: string | null;
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        whiteLabel: {
+            entitled: boolean;
+            requiredPlan: string;
+        };
+    }>;
+    /**
+     * 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: CreateHostedDomainInput, options?: CallOptions) => Promise<{
+        id: string;
+        hostname: string;
+        hostnameUnicode: string;
+        environment: "live";
+        status: "failed" | "active" | "pending_verification" | "verified" | "disabled";
+        statusReason: "verification_expired" | "tls_unavailable" | "edge_blocked" | "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended" | null;
+        isPrimary: boolean;
+        records: {
+            type: "TXT" | "CNAME";
+            name: string;
+            value: string;
+        }[];
+        dns: {
+            checkedAt: string | null;
+            failingSince: string | null;
+            graceEndsAt: string | null;
+            txt: {
+                status: "found" | "missing" | "inconclusive" | null;
+                values: string[];
+            };
+            cname: {
+                status: "found" | "missing" | "inconclusive" | "wrong" | null;
+                chain: string[];
+            };
+        };
+        edge: {
+            status: string | null;
+            sslStatus: string | null;
+            errors: string[];
+            certificateExpiresAt: string | null;
+            checkedAt: string | null;
+        };
+        reassignment: {
+            role: "owner" | "claimant";
+            dueAt: string;
+        } | null;
+        entitlementLapse: {
+            lapsedAt: string;
+            servingEndsAt: string;
+            disablesAt: string;
+        } | null;
+        verificationExpiresAt: string | null;
+        verifiedAt: string | null;
+        activatedAt: string | null;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    get: (id: string, options?: CallOptions) => Promise<{
+        id: string;
+        hostname: string;
+        hostnameUnicode: string;
+        environment: "live";
+        status: "failed" | "active" | "pending_verification" | "verified" | "disabled";
+        statusReason: "verification_expired" | "tls_unavailable" | "edge_blocked" | "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended" | null;
+        isPrimary: boolean;
+        records: {
+            type: "TXT" | "CNAME";
+            name: string;
+            value: string;
+        }[];
+        dns: {
+            checkedAt: string | null;
+            failingSince: string | null;
+            graceEndsAt: string | null;
+            txt: {
+                status: "found" | "missing" | "inconclusive" | null;
+                values: string[];
+            };
+            cname: {
+                status: "found" | "missing" | "inconclusive" | "wrong" | null;
+                chain: string[];
+            };
+        };
+        edge: {
+            status: string | null;
+            sslStatus: string | null;
+            errors: string[];
+            certificateExpiresAt: string | null;
+            checkedAt: string | null;
+        };
+        reassignment: {
+            role: "owner" | "claimant";
+            dueAt: string;
+        } | null;
+        entitlementLapse: {
+            lapsedAt: string;
+            servingEndsAt: string;
+            disablesAt: string;
+        } | null;
+        verificationExpiresAt: string | null;
+        verifiedAt: string | null;
+        activatedAt: string | null;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /** Check the DNS records now (2 per minute per domain); answers the refreshed domain. */
+    verify: (id: string, options?: CallOptions) => Promise<{
+        id: string;
+        hostname: string;
+        hostnameUnicode: string;
+        environment: "live";
+        status: "failed" | "active" | "pending_verification" | "verified" | "disabled";
+        statusReason: "verification_expired" | "tls_unavailable" | "edge_blocked" | "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended" | null;
+        isPrimary: boolean;
+        records: {
+            type: "TXT" | "CNAME";
+            name: string;
+            value: string;
+        }[];
+        dns: {
+            checkedAt: string | null;
+            failingSince: string | null;
+            graceEndsAt: string | null;
+            txt: {
+                status: "found" | "missing" | "inconclusive" | null;
+                values: string[];
+            };
+            cname: {
+                status: "found" | "missing" | "inconclusive" | "wrong" | null;
+                chain: string[];
+            };
+        };
+        edge: {
+            status: string | null;
+            sslStatus: string | null;
+            errors: string[];
+            certificateExpiresAt: string | null;
+            checkedAt: string | null;
+        };
+        reassignment: {
+            role: "owner" | "claimant";
+            dueAt: string;
+        } | null;
+        entitlementLapse: {
+            lapsedAt: string;
+            servingEndsAt: string;
+            disablesAt: string;
+        } | null;
+        verificationExpiresAt: string | null;
+        verifiedAt: string | null;
+        activatedAt: string | null;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /** Make an active domain the default host for new portal sessions. */
+    makePrimary: (id: string, options?: CallOptions) => Promise<{
+        id: string;
+        hostname: string;
+        hostnameUnicode: string;
+        environment: "live";
+        status: "failed" | "active" | "pending_verification" | "verified" | "disabled";
+        statusReason: "verification_expired" | "tls_unavailable" | "edge_blocked" | "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended" | null;
+        isPrimary: boolean;
+        records: {
+            type: "TXT" | "CNAME";
+            name: string;
+            value: string;
+        }[];
+        dns: {
+            checkedAt: string | null;
+            failingSince: string | null;
+            graceEndsAt: string | null;
+            txt: {
+                status: "found" | "missing" | "inconclusive" | null;
+                values: string[];
+            };
+            cname: {
+                status: "found" | "missing" | "inconclusive" | "wrong" | null;
+                chain: string[];
+            };
+        };
+        edge: {
+            status: string | null;
+            sslStatus: string | null;
+            errors: string[];
+            certificateExpiresAt: string | null;
+            checkedAt: string | null;
+        };
+        reassignment: {
+            role: "owner" | "claimant";
+            dueAt: string;
+        } | null;
+        entitlementLapse: {
+            lapsedAt: string;
+            servingEndsAt: string;
+            disablesAt: string;
+        } | null;
+        verificationExpiresAt: string | null;
+        verifiedAt: string | null;
+        activatedAt: string | null;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    /** Remove a domain; the portal sessions on it end immediately. */
+    remove: (id: string, options?: CallOptions) => Promise<{
+        id: string;
+        hostname: string;
+        removed: true;
+    }>;
+};
+
 declare function createInvoicesResource(ctx: RequestContext): {
     /** List invoices. Filters: status, customer (external id), from, to. Auto-paginating. */
     list: (params?: InvoiceListParams, options?: CallOptions) => ListPromise<InvoiceListItem>;
@@ -2066,6 +2592,8 @@ declare class Billow {
     portalSessions: ReturnType<typeof createPortalSessionsResource>;
     deliverability: ReturnType<typeof createDeliverabilityResource>;
     marketplace: ReturnType<typeof createMarketplaceResource>;
+    /** Custom domains for the hosted customer portal (live keys, behind a rollout flag). */
+    hostedDomains: ReturnType<typeof createHostedDomainsResource>;
     /**
      * Organization settings (Phase D3, F) — the configurable dunning schedule, usage settlement grace,
      * and the cross-currency reporting currency + FX-rate registry (ADR-0013).
@@ -2298,6 +2826,13 @@ declare class BillowPortal {
      *  the lightweight payload the hosting app frames every page with, and the
      *  validate-and-route check at login. */
     session(options?: CallOptions): Promise<PortalSessionInfo>;
+    /**
+     * The single-use entry exchange (ADR-0039): on a client built with a minted link's entry
+     * token, trade it for the session token to use from now on. Succeeds once per link, and
+     * afterwards only for the browser presenting that exchange's `sessionToken`; anything else is
+     * a 401. For a hosted surface; an integrator's own surface may keep using the entry token.
+     */
+    exchange(input: PortalSessionExchangeInput, options?: CallOptions): Promise<PortalSessionExchange>;
     /** The self-serve home payload: identity + subscriptions + usage + saved cards. */
     me(options?: CallOptions): Promise<PortalView>;
     invoices: {
@@ -2305,6 +2840,8 @@ declare class BillowPortal {
         list: (params?: ListParams & {
             status?: InvoiceListItem["status"];
         }, options?: CallOptions) => ListPromise<InvoiceListItem>;
+        /** One of the Customer's invoices, in the list's shape. */
+        get: (id: string, options?: CallOptions) => Promise<InvoiceListItem>;
         /** Open or resume checkout for this customer's outstanding invoice. */
         pay: (id: string, input?: PayInvoiceInput, options?: CallOptions) => Promise<{
             invoiceId: string;
@@ -2376,4 +2913,4 @@ declare class BillowPortal {
     };
 }
 
-export { AttachResult, BILLOW_ERROR_CODES, Billow, BillowApiError, type BillowErrorCode, BillowOptions, BillowPortal, BillowPublishable, type BusinessProfile, CallOptions, type CatalogItem, Charge, type ChargeListItem, type ChargeListParams, type ChargeSearchHit, ChargeStatus, CheckResult, type CheckoutMethodInfo, type ConfigField, type ConfigFieldOption, type ConfigFieldType, Coupon, CreateChargeInput, CreateCouponInput, CreateCreditGrantInput, CreateCreditPackInput, CreateCreditTopUpInput, CreateMerchantInitiatedChargeInput, type CreatePortalSessionInput, CreateProductInput, CreateSubscriptionInput, CreateUsageAlertInput, type CreateWebhookEndpointInput, type CredentialSet, CreditBalance, CreditGrant, CreditGrantRequestResult, CreditLedgerEntry, CreditPack, CreditPacks, CreditThresholdLevel, CreditTopUp, CreditTopUpListParams, CreditTopUpRequestResult, CreditUsage, CreditUsageParams, type CursorListParams, type CursorListPromise, type CursorPaginated, Customer, type CustomerAnonymizationResult, type CustomerCreditsExport, type CustomerDataExport, type CustomerListItem, type CustomerListParams, type CustomerOverview, type CustomerSearchHit, type CustomerUsage, type CustomerUsageDetail, type EmailDeliveryListItem, type EmailDeliveryListParams, type EmailDeliveryStatus, type EmailTemplateSetting, EntitlementView, type ExchangeRate, type ExportJsonValue, type ExternalPaymentMethod, type ExternalPaymentResult, Feature, FeatureKind, IdempotentRequestOptions, type InboundWebhookListItem, type InboundWebhookListParams, type InboundWebhookOutcome, type IntegrationDefinition, type IntegrationKind, type IntegrationTier, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListItem, type InvoiceListParams, type InvoiceSearchHit, InvoiceStatus, type ListParams, type ListPromise, MeterConfig, type MetricsOverview, type MetricsParams, type MetricsRollup, MigrationResult, type OutboxEventListItem, type OutboxEventListParams, type OutboxEventStatus, type Paginated, PayInvoiceInput, type PaymentMethod, PaymentMethodStatus, type PaymentProviderDefinition, type PortalCardSetupResult, type PortalCheckout, type PortalPlanChange, type PortalSession, type PortalSessionFlow, type PortalSessionInfo, type PortalSubscriptionStatus, type PortalView, type ProviderCredentialSummary, type ProviderVerifyResult, type ProviderVerifyTarget, type ProviderVerifyTargetResult, type RecordExternalPaymentInput, type Refund, type RefundChargeInput, type RefundRequestResult, type RefundReviewReason, RefundStatus, RequestOptions, type ResolveRefundInput, SavedPaymentMethod, type ScheduledSubscriptionChange, type SearchResults, type SubscriptionListItem, type SubscriptionListParams, type SubscriptionSearchHit, SubscriptionStatus, TaxBehavior, type TimeseriesInterval, type TimeseriesMetric, type TimeseriesParams, type TimeseriesPoint, type TimeseriesResult, TrackResult, UnappliedPaymentReason, type UpdateBusinessProfileInput, UpdateCreditPackInput, type UpdateEmailTemplateInput, UpdateFeatureInput, UpdateProductInput, type UpdateWebhookEndpointInput, type UpsertCredentialsInput, UsageAlert, type WebhookDelivery, WebhookDeliveryStatus, type WebhookEndpoint, type WebhookEndpointWithSecret, type Whoami, currencyExponent, formatMoney, isSecretField, toMajorUnits, toMinorUnits };
+export { AttachResult, BILLOW_ERROR_CODES, Billow, BillowApiError, type BillowErrorCode, BillowOptions, BillowPortal, BillowPublishable, type BusinessProfile, CallOptions, type CatalogItem, Charge, type ChargeListItem, type ChargeListParams, type ChargeSearchHit, ChargeStatus, CheckResult, type CheckoutMethodInfo, type ConfigField, type ConfigFieldOption, type ConfigFieldType, Coupon, CreateChargeInput, CreateCouponInput, CreateCreditGrantInput, CreateCreditPackInput, type CreateCreditQuoteInput, type CreateCreditReservationInput, CreateCreditTopUpInput, CreateHostedDomainInput, CreateMerchantInitiatedChargeInput, type CreatePortalSessionInput, CreateProductInput, CreateSubscriptionInput, CreateUsageAlertInput, type CreateWebhookEndpointInput, type CredentialSet, CreditBalance, type CreditDimensions, CreditGrant, CreditGrantRequestResult, CreditLedgerEntry, type CreditLineItem, CreditPack, CreditPacks, type CreditPricedLine, type CreditQuote, type CreditRateCard, type CreditRateCardItem, type CreditReservation, type CreditReservationRequestResult, type CreditReservationStatus, type CreditReversal, type CreditReversalRequestResult, CreditThresholdLevel, CreditTopUp, CreditTopUpListParams, CreditTopUpRequestResult, CreditUsage, CreditUsageParams, type CursorListParams, type CursorListPromise, type CursorPaginated, Customer, type CustomerAnonymizationResult, type CustomerCreditsExport, type CustomerDataExport, type CustomerListItem, type CustomerListParams, type CustomerOverview, type CustomerSearchHit, type CustomerUsage, type CustomerUsageDetail, type EmailDeliveryListItem, type EmailDeliveryListParams, type EmailDeliveryStatus, type EmailTemplateSetting, EntitlementView, type ExchangeRate, type ExportJsonValue, type ExternalPaymentMethod, type ExternalPaymentResult, Feature, FeatureKind, IdempotentRequestOptions, type InboundWebhookListItem, type InboundWebhookListParams, type InboundWebhookOutcome, type IntegrationDefinition, type IntegrationKind, type IntegrationTier, type Invoice, type InvoiceDetail, type InvoiceLineItem, type InvoiceListItem, type InvoiceListParams, type InvoiceSearchHit, InvoiceStatus, type ListParams, type ListPromise, MeterConfig, type MetricsOverview, type MetricsParams, type MetricsRollup, MigrationResult, type OutboxEventListItem, type OutboxEventListParams, type OutboxEventStatus, type Paginated, PayInvoiceInput, type PaymentMethod, PaymentMethodStatus, type PaymentProviderDefinition, type PortalCardSetupResult, type PortalCheckout, type PortalPlanChange, type PortalSession, type PortalSessionExchange, type PortalSessionExchangeInput, type PortalSessionFlow, type PortalSessionInfo, type PortalSubscriptionStatus, type PortalView, type ProviderCredentialSummary, type ProviderVerifyResult, type ProviderVerifyTarget, type ProviderVerifyTargetResult, type PublishCreditRateCardInput, type RecordExternalPaymentInput, type Refund, type RefundChargeInput, type RefundRequestResult, type RefundReviewReason, RefundStatus, RequestOptions, type ResolveRefundInput, type ReverseCreditConsumptionInput, SavedPaymentMethod, type ScheduledSubscriptionChange, type SearchResults, type SubscriptionListItem, type SubscriptionListParams, type SubscriptionSearchHit, SubscriptionStatus, TaxBehavior, type TimeseriesInterval, type TimeseriesMetric, type TimeseriesParams, type TimeseriesPoint, type TimeseriesResult, TrackResult, UnappliedPaymentReason, type UpdateBusinessProfileInput, UpdateCreditPackInput, type UpdateEmailTemplateInput, UpdateFeatureInput, UpdateProductInput, type UpdateWebhookEndpointInput, type UpsertCredentialsInput, UsageAlert, type WebhookDelivery, WebhookDeliveryStatus, type WebhookEndpoint, type WebhookEndpointWithSecret, type Whoami, currencyExponent, formatMoney, isSecretField, toMajorUnits, toMinorUnits };