@openreceive/browser 0.1.1 → 0.2.1

package/dist/status-CLCX5lfx.d.ts

@@ -0,0 +1,963 @@
+import { PaymentWizardRoute, AssetIndexEntry } from '@openreceive/provider-data';
+import { TransactionSettlementStatus } from '@openreceive/core';
+
+/**
+ * Trim insignificant trailing zeros from a decimal crypto amount for display,
+ * e.g. "12.25900000" -> "12.259" and "5.000" -> "5". Only fractional digits are
+ * stripped: integer amounts like "100" keep their zeros, and non-numeric input
+ * is returned unchanged.
+ */
+declare function formatDepositAmount(amount: string): string;
+declare function escapeHtml(value: string): string;
+/**
+ * Throws on a non-amount, and every caller lets it: wire construction, amount
+ * validation, and the display sites share this formatter, and a malformed
+ * amount from our own server is a bug that must surface, not be smoothed over.
+ */
+declare function formatMsats(amountMsats: number): string;
+declare function formatFiatAmount(fiat: {
+    readonly currency?: string;
+    readonly value?: string;
+} | null | undefined): string | undefined;
+/** Combined QR caption, e.g. `19,174 sats / $12.00 US`. */
+declare function formatAmountCaption(options: {
+    readonly amountLabel?: string;
+    readonly fiatLabel?: string;
+    readonly fiatCurrency?: string;
+}): string | undefined;
+/**
+ * Renders an invoice-side (Lightning receive) msat limit as a short amount for
+ * display under a disabled swap asset, e.g. "$10.00". Converts to the
+ * checkout's own fiat currency using its rate; falls back to a sats figure when
+ * the checkout is sats/BTC-denominated or no usable rate is available.
+ *
+ * Minimums ceil and maximums floor to the display scale so the note never
+ * understates a floor or overstates a ceiling.
+ */
+declare function formatSwapLimit(checkout: {
+    readonly amount_msats: number;
+    readonly fiat?: {
+        readonly currency: string;
+        readonly value: string;
+    };
+}, limitMsats: number | undefined, rounding?: "ceil" | "floor"): string | undefined;
+/**
+ * ECHOES rather than throws on a value it cannot render — the one place this
+ * rule reads differently from the amount rule above, deliberately.
+ * `formatMsats` throws because wire construction and amount validation share
+ * it and a bad amount there must surface; nothing constructs or validates
+ * anything through this formatter, so degrading to the raw value is its
+ * contract.
+ */
+declare function formatUnixTime(seconds: number): string;
+/** The payer-facing labels a {@link CheckoutState} carries next to its raw fields. */
+interface CheckoutStateLabels {
+    readonly amountLabel?: string;
+    readonly fiatLabel?: string;
+    readonly paymentHashLabel?: string;
+}
+/**
+ * THE label rule — one copy, applied everywhere a checkout is shown.
+ *
+ * `normalizeCheckoutState` runs it so every CheckoutState already carries its
+ * labels, and the elements renderer runs it over raw attributes in create mode,
+ * before there is an attempt to build a state from. It replaces the label half
+ * of the deleted `createCheckoutDisplayModel`; the other half (the `lightning:`
+ * URI) belongs to `createCheckoutState`, which is the only place that knows the
+ * rail.
+ *
+ * `transactionStateLabel` is deliberately NOT here: it was a verbatim copy of
+ * `transaction_state`, which the state already carries, and nothing read it.
+ */
+declare function deriveCheckoutStateLabels(source: {
+    readonly amount_msats?: number;
+    readonly fiat_quote?: {
+        readonly fiat?: {
+            readonly currency?: string;
+            readonly value?: string;
+        };
+    } | null;
+    readonly payment_hash?: string;
+}): CheckoutStateLabels;
+
+declare const OPENRECEIVE_THEME_STORAGE_KEY: "openreceive.theme";
+declare const OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS: 3000;
+/**
+ * Default base path the shipped OpenReceive router is mounted at. When a developer passes
+ * only an order id (React `<Checkout reference>` / `<openreceive-checkout reference>`), this is
+ * the prefix every route is derived from — see `checkoutRoutes` in ./routes.ts. It is
+ * the only URL input the checkout components accept.
+ */
+declare const OPENRECEIVE_DEFAULT_PREFIX: "/openreceive";
+declare const OPENRECEIVE_COPY_FEEDBACK_MS: 1800;
+declare const OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME: "openreceive-checkout";
+declare const OPENRECEIVE_THEME_TOGGLE_ELEMENT_TAG_NAME: "openreceive-theme-toggle";
+declare const OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS: {
+    readonly copy: "openreceive-copy";
+    readonly openWallet: "openreceive-open-wallet";
+    readonly state: "openreceive-state";
+    readonly settled: "openreceive-settled";
+    readonly providerCopy: "openreceive-provider-copy";
+    readonly startOver: "openreceive-start-over";
+    readonly error: "openreceive-error";
+};
+declare const OPENRECEIVE_THEME_TOGGLE_ELEMENT_EVENTS: {
+    readonly change: "openreceive-theme-change";
+};
+declare const OPENRECEIVE_PAYMENT_WIZARD_ATTRIBUTES: {
+    readonly root: "data-openreceive-wizard";
+    readonly breadcrumb: "data-or-breadcrumb";
+    readonly method: "data-or-method";
+    readonly route: "data-or-route";
+    readonly swapStart: "data-or-swap-start";
+    readonly swapBack: "data-or-swap-back";
+    readonly swapQr: "data-or-swap-qr";
+    readonly swapCopy: "data-or-swap-copy";
+    readonly swapCopyLabel: "data-or-swap-copy-label";
+    readonly swapSelectAll: "data-or-swap-select-all";
+    readonly swapNetwork: "data-or-swap-network";
+    readonly swapNetworkValue: "data-or-swap-network-value";
+    readonly pickerSelect: "data-or-picker-select";
+    readonly pickerContinue: "data-or-picker-continue";
+    readonly swapRefundForm: "data-or-swap-refund-form";
+    readonly swapRefundAddress: "data-or-swap-refund-address";
+    readonly swapRefundAllowed: "data-or-swap-refund-allowed";
+    readonly swapRefundConfirm: "data-or-swap-refund-confirm";
+    readonly swapRefundPayInAsset: "data-or-swap-refund-pay-in-asset";
+    readonly swapRefundNetworkLabel: "data-or-swap-refund-network-label";
+    readonly swapRefundError: "data-or-swap-refund-error";
+    readonly providerCopy: "data-or-provider-copy";
+    readonly providerTutorial: "data-or-provider-tutorial";
+    readonly providerTutorialIndex: "data-or-provider-tutorial-index";
+};
+declare const OPENRECEIVE_PAYMENT_WIZARD_SELECTORS: {
+    readonly root: "[data-openreceive-wizard]";
+    readonly breadcrumb: "[data-or-breadcrumb]";
+    readonly method: "[data-or-method]";
+    readonly route: "[data-or-route]";
+    readonly swapStart: "[data-or-swap-start]";
+    readonly swapBack: "[data-or-swap-back]";
+    readonly swapQr: "[data-or-swap-qr]";
+    readonly swapCopy: "[data-or-swap-copy]";
+    readonly swapCopyLabel: "[data-or-swap-copy-label]";
+    readonly swapSelectAll: "[data-or-swap-select-all]";
+    readonly swapNetwork: "[data-or-swap-network]";
+    readonly swapNetworkValue: "[data-or-swap-network-value]";
+    readonly pickerSelect: "[data-or-picker-select]";
+    readonly pickerContinue: "[data-or-picker-continue]";
+    readonly swapRefundForm: "[data-or-swap-refund-form]";
+    readonly swapRefundAddress: "[data-or-swap-refund-address]";
+    readonly swapRefundAllowed: "[data-or-swap-refund-allowed]";
+    readonly swapRefundConfirm: "[data-or-swap-refund-confirm]";
+    readonly swapRefundPayInAsset: "[data-or-swap-refund-pay-in-asset]";
+    readonly swapRefundNetworkLabel: "[data-or-swap-refund-network-label]";
+    readonly swapRefundError: "[data-or-swap-refund-error]";
+    readonly providerCopy: "[data-or-provider-copy]";
+    readonly providerTutorial: "[data-or-provider-tutorial]";
+    readonly providerTutorialIndex: "[data-or-provider-tutorial-index]";
+};
+declare const OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES: {
+    readonly root: "data-openreceive-checkout";
+    readonly qr: "data-openreceive-qr";
+    readonly meta: "data-openreceive-meta";
+    readonly state: "data-openreceive-state";
+    readonly actions: "data-openreceive-actions";
+    readonly theme: "data-openreceive-theme";
+    readonly themeToggle: "data-openreceive-theme-toggle";
+};
+declare const OPENRECEIVE_CHECKOUT_DATA_SELECTORS: {
+    readonly root: "[data-openreceive-checkout]";
+    readonly qr: "[data-openreceive-qr]";
+    readonly meta: "[data-openreceive-meta]";
+    readonly state: "[data-openreceive-state]";
+    readonly actions: "[data-openreceive-actions]";
+    readonly theme: "[data-openreceive-theme]";
+    readonly themeToggle: "[data-openreceive-theme-toggle]";
+};
+declare const OPENRECEIVE_CHECKOUT_ELEMENT_PARTS: {
+    readonly copy: "copy";
+    readonly startOver: "start-over";
+};
+declare const OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS: {
+    readonly copy: "[part=\"copy\"]";
+    readonly startOver: "[part=\"start-over\"]";
+};
+declare const OPENRECEIVE_THEME_TOGGLE_ELEMENT_PARTS: {
+    readonly button: "button";
+};
+declare const OPENRECEIVE_THEME_TOGGLE_ELEMENT_PART_SELECTORS: {
+    readonly button: "[part=\"button\"]";
+};
+type CheckoutElementEventName = (typeof OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS)[keyof typeof OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS];
+interface CheckoutProviderCopyEventDetail {
+    readonly providerId: string;
+}
+interface CheckoutStateEventDetail {
+    readonly state: CheckoutState;
+}
+interface CheckoutErrorEventDetail {
+    readonly error: unknown;
+}
+interface ThemeChangeEventDetail {
+    readonly theme: ThemePreference;
+    readonly resolvedTheme: ResolvedTheme;
+}
+declare function createCheckoutProviderCopyEvent(providerId: string): CustomEvent<CheckoutProviderCopyEventDetail>;
+declare function createCheckoutActionEvent(eventName: typeof OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS.copy | typeof OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS.openWallet | typeof OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS.startOver): CustomEvent;
+declare function createCheckoutStateEvent(eventName: typeof OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS.state | typeof OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS.settled, state: CheckoutState): CustomEvent<CheckoutStateEventDetail>;
+declare function createCheckoutErrorEvent(error: unknown): CustomEvent<CheckoutErrorEventDetail>;
+declare function createThemeChangeEvent(theme: ThemeModel): CustomEvent<ThemeChangeEventDetail>;
+declare const OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES: {
+    readonly reference: "reference";
+    /**
+     * Base path the shipped router is mounted at (default `/openreceive`). The
+     * element's ONLY URL input: create, prepare, payment-check and the four swap
+     * routes are all derived from it. There is deliberately no per-route
+     * attribute — see `checkoutRoutes` in ../internal/routes.ts.
+     */
+    readonly prefix: "prefix";
+    /** JSON-encoded create-time metadata forwarded to the create request. */
+    readonly metadata: "metadata";
+    readonly invoiceId: "invoice-id";
+    readonly invoice: "invoice";
+    readonly rail: "rail";
+    readonly paymentHash: "payment-hash";
+    readonly amountMsats: "amount-msats";
+    readonly fiatCurrency: "fiat-currency";
+    readonly fiatValue: "fiat-value";
+    readonly status: "status";
+    readonly expiresAt: "expires-at";
+    readonly theme: "theme";
+    readonly paymentWizard: "payment-wizard";
+    /**
+     * Opt into History API URL sync to `{resume-path-prefix}/{reference}`.
+     * Summary fetch always runs in create mode; this only controls URL mutation.
+     */
+    readonly syncUrl: "sync-url";
+    /** History API path prefix when `sync-url` is set. Default `/checkout`. */
+    readonly resumePathPrefix: "resume-path-prefix";
+    /**
+     * Order id owned by the app router (e.g. Next.js). When set, the element does not
+     * push/replace the URL via the History API.
+     */
+    readonly routeReference: "route-reference";
+    /**
+     * Base URL of an external bolt11 decoder. When set, the checkout shows a
+     * "Decode" link to `{decode-link-url}?invoice={bolt11}`. Omitted (the
+     * default), no decode link is rendered and the invoice never leaves the page.
+     */
+    readonly decodeLinkUrl: "decode-link-url";
+    /** `polling="false"` renders the snapshot without status polling (no POST /payments/check). */
+    readonly polling: "polling";
+    /** Status poll cadence in milliseconds; defaults to OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS. */
+    readonly pollIntervalMs: "poll-interval-ms";
+};
+declare const OPENRECEIVE_THEME_TOGGLE_ELEMENT_ATTRIBUTES: {
+    readonly rootSelector: "root-selector";
+    readonly checkoutSelector: "checkout-selector";
+    readonly defaultTheme: "default-theme";
+    readonly storageKey: "storage-key";
+};
+
+interface TransientFeedbackOptions<T> {
+    readonly resetValue: T;
+    readonly delayMs?: number;
+    readonly setTimeout?: typeof globalThis.setTimeout;
+    readonly clearTimeout?: typeof globalThis.clearTimeout;
+    readonly onValue: (value: T) => void;
+}
+interface TransientFeedbackController<T> {
+    show(value: T): void;
+    clear(): void;
+}
+interface TickingValueOptions {
+    readonly active?: boolean;
+    readonly intervalMs?: number;
+    readonly now?: () => number;
+    readonly setInterval?: typeof globalThis.setInterval;
+    readonly clearInterval?: typeof globalThis.clearInterval;
+    readonly onValue: (value: number) => void;
+}
+interface TickingValueController {
+    start(): void;
+    stop(): void;
+    refresh(): void;
+}
+interface QrEncoder {
+    toString(payload: string, options: Record<string, unknown>): Promise<string> | string;
+    toDataURL?(payload: string, options: Record<string, unknown>): Promise<string> | string;
+}
+interface QrOptions {
+    encoder?: QrEncoder;
+    width?: number;
+}
+interface CopyInvoiceOptions {
+    invoice: string;
+    clipboard?: Pick<Clipboard, "writeText">;
+    logger?: BrowserLoggerOption;
+    logContext?: BrowserLogContext;
+}
+interface OpenWalletOptions {
+    invoice: string;
+    open?: (uri: string) => void;
+    logger?: BrowserLoggerOption;
+    logContext?: BrowserLogContext;
+}
+type BrowserLogLevel = "debug" | "info" | "warn" | "error";
+interface BrowserLogEntry {
+    readonly level: BrowserLogLevel;
+    readonly event: string;
+    readonly message: string;
+    readonly [key: string]: unknown;
+}
+type BrowserLogger = (entry: BrowserLogEntry) => void;
+/**
+ * Browser logger option. Omit/`undefined` attaches the built-in console logger
+ * (honoring `LOG_LEVEL`). Pass `false` to disable OpenReceive browser logs.
+ */
+type BrowserLoggerOption = BrowserLogger | false;
+interface BrowserLogContext {
+    readonly reference?: string;
+    readonly invoice_id?: string;
+    readonly payment_hash?: string;
+    readonly amount_msats?: number;
+    readonly transaction_state?: string;
+    readonly workflow_state?: string;
+    readonly [key: string]: unknown;
+}
+type CheckoutPhase = "invoice_created" | "verifying" | "settled" | "expired" | "failed" | "cancelled";
+type SwapProviderState = "creating_provider_order" | "awaiting_deposit" | "confirming" | "exchanging" | "paying_invoice" | "completed" | "expired" | "refund_required" | "refund_pending" | "refunded" | "attention" | "failed";
+/**
+ * Provider-reported fiat equivalents of both sides of a swap. `pay_in_fiat` is the
+ * value of the crypto the payer must send; `payout_fiat` is the cart total delivered
+ * to the merchant. Their gap is the swap fee the payer absorbs.
+ */
+interface CheckoutInvoiceSwapFee {
+    readonly currency: string;
+    readonly pay_in_fiat: string;
+    readonly payout_fiat: string;
+}
+interface CheckoutInvoiceSwapSnapshot {
+    readonly attempt_id?: string;
+    readonly provider: string;
+    readonly provider_order_id?: string;
+    readonly pay_in_asset: string;
+    readonly deposit_address: string;
+    readonly deposit_memo?: string;
+    readonly deposit_amount: string;
+    readonly provider_state: SwapProviderState;
+    readonly provider_expires_at: number;
+    readonly deposit_tx_id?: string;
+    readonly payout_tx_id?: string;
+    readonly refund_address?: string;
+    readonly refund_tx_id?: string;
+    readonly attention?: boolean;
+    readonly attention_reason?: string;
+    readonly refund_reason?: string;
+    readonly deposit_received_amount?: string;
+    readonly refund_amount?: string;
+    readonly fee?: CheckoutInvoiceSwapFee;
+}
+/**
+ * Formatted fee breakout for the deposit panel, explaining why the payer sends more
+ * than the cart total. All figures are display-ready fiat strings.
+ */
+interface SwapFeeBreakdown {
+    /** Cart total delivered to the merchant, e.g. "$10.00". */
+    readonly cartTotal: string;
+    /** Fiat value of the crypto the payer sends, e.g. "$10.59". */
+    readonly youSend: string;
+    /** The swap fee absorbed by the payer (exchange spread + network fees), e.g. "$0.59". */
+    readonly fee: string;
+    /** The fee as a percentage of the cart total, e.g. "5.9%", when computable. */
+    readonly feePercent?: string;
+}
+interface SwapDisplayModel {
+    readonly provider: string;
+    readonly attemptId: string;
+    readonly payInAsset: string;
+    readonly assetLabel: string;
+    readonly networkLabel: string;
+    /** Strong deposit-panel alert title, e.g. "Wrong currency or network = lost funds". */
+    readonly networkWarningTitle: string;
+    /** Exact amount + asset + network to emphasize, e.g. "15.01 USDT on the Solana network". */
+    readonly networkWarningEmphasis: string;
+    /** Full plain-text network warning (accessible / non-HTML consumers). */
+    readonly networkWarning: string;
+    readonly depositAddress: string;
+    readonly depositMemo?: string;
+    readonly depositAmount: string;
+    readonly providerStateLabel: string;
+    readonly providerStateDetail: string;
+    readonly state: "creating" | "deposit" | "progress" | "settled" | "expired" | "refund_required" | "refund_pending" | "refunded" | "attention" | "failed";
+    readonly expiresInSeconds: number;
+    readonly countdownLabel: string;
+    readonly qrPayload: string;
+    /** Ready-to-render fee breakout, present when the provider reported fiat equivalents. */
+    readonly feeBreakdown?: SwapFeeBreakdown;
+    readonly depositTxId?: string;
+    readonly payoutTxId?: string;
+    readonly refundAddress?: string;
+    /**
+     * Whether the refund form may be submitted. The review-then-confirm gate is
+     * entirely client-side: OpenReceive mints no refund tokens, the server sends
+     * none, and the confirmed request carries only reference, payment_hash, and
+     * refund_address.
+     */
+    readonly refundAllowed: boolean;
+    readonly refundTxId?: string;
+    readonly refundReason?: string;
+    readonly depositReceivedAmount?: string;
+    readonly refundAmount?: string;
+    readonly providerOrderId?: string;
+}
+interface CheckoutInvoiceSnapshot {
+    readonly invoice_id: string;
+    readonly invoice?: string | null;
+    readonly rail: "lightning" | "swap" | "checkout_lock";
+    readonly payment_hash?: string;
+    readonly amount_msats?: number;
+    readonly fiat_quote?: {
+        readonly fiat?: {
+            readonly currency?: string;
+            readonly value?: string;
+        };
+    } | null;
+    readonly transaction_state?: string;
+    readonly workflow_state?: string;
+    readonly expires_at?: number;
+    readonly settled_at?: number;
+    readonly swap?: CheckoutInvoiceSwapSnapshot;
+}
+interface CheckoutPaymentMethod {
+    readonly pay_in_asset: string;
+    readonly label: string;
+    readonly network_label: string;
+    readonly provider: string;
+    readonly available: boolean;
+    readonly unavailable_reason?: string;
+    readonly unavailable_message?: string;
+    readonly pay_amount?: string;
+    readonly minimum_pay_amount?: string;
+    readonly maximum_pay_amount?: string;
+    readonly minimum_invoice_amount_msats?: number;
+    readonly maximum_invoice_amount_msats?: number;
+}
+/**
+ * Client-side snapshot of one Checkout (the server's `Checkout` /
+ * the wire's `WireCheckout`), aggregated across its payment
+ * attempts as the browser polls. Snake_case because it holds wire data
+ * verbatim.
+ */
+interface CheckoutSnapshot {
+    readonly checkout_id: string;
+    readonly reference: string;
+    readonly status: "open" | "paid" | "expired";
+    readonly paid_at?: number;
+    readonly amount_msats: number;
+    readonly fiat?: {
+        readonly currency: string;
+        readonly value: string;
+    };
+    readonly active?: CheckoutInvoiceSnapshot;
+    readonly invoices: readonly CheckoutInvoiceSnapshot[];
+    readonly payment_methods?: readonly CheckoutPaymentMethod[];
+}
+interface CheckoutElementAttributeOptions {
+    /**
+     * Order id for create mode. When no checkout snapshot is supplied, the element is rendered
+     * with this as its `reference` attribute (paired with `prefix`) and owns the whole
+     * create/poll lifecycle itself. Ignored when a snapshot is supplied — the snapshot's
+     * `reference` wins.
+     */
+    readonly reference?: string;
+    /**
+     * Base path the shipped router is mounted at. Emitted as the element's `prefix` attribute
+     * so a create-mode element (`reference` with no `invoice`) can derive its create/order
+     * routes without spelling them out.
+     */
+    readonly prefix?: string;
+    /**
+     * Optional create-time metadata (parity with the React `<Checkout metadata>`
+     * prop): JSON-encoded onto the element's `metadata` attribute and sent with
+     * the Lightning mint request.
+     */
+    readonly metadata?: Record<string, unknown>;
+    readonly theme?: ResolvedTheme;
+    readonly paymentWizard?: boolean;
+    /**
+     * Opt into History API URL sync to `{resumePathPrefix}/{reference}` (default `/checkout/:id`).
+     * This controls URL mutation only; order-resume data remains a host concern.
+     */
+    readonly syncUrl?: boolean;
+    /** History API path prefix when `syncUrl` is set. Default `/checkout`. */
+    readonly resumePathPrefix?: string;
+    /**
+     * Order id from the app router (e.g. Next.js). When set, skip History API URL sync.
+     */
+    readonly routeReference?: string;
+    /**
+     * Base URL of an external bolt11 decoder. Omitted (the default), the element
+     * renders no "Decode" link and the invoice is never sent to a third party.
+     */
+    readonly decodeLinkUrl?: string;
+    /** False renders the snapshot without status polling (no POST /payments/check). */
+    readonly polling?: boolean;
+    /** Status poll cadence in milliseconds; defaults to OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS. */
+    readonly pollIntervalMs?: number;
+}
+interface ThemeToggleElementAttributeOptions {
+    readonly rootSelector?: string;
+    readonly checkoutSelector?: string;
+    readonly defaultTheme?: ThemePreference;
+    readonly storageKey?: string;
+}
+type CheckoutElementAttributeName = (typeof OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES)[keyof typeof OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES];
+type CheckoutElementAttributes = Partial<Record<CheckoutElementAttributeName, string>>;
+type ThemeToggleElementAttributeName = (typeof OPENRECEIVE_THEME_TOGGLE_ELEMENT_ATTRIBUTES)[keyof typeof OPENRECEIVE_THEME_TOGGLE_ELEMENT_ATTRIBUTES];
+type ThemeToggleElementAttributes = Partial<Record<ThemeToggleElementAttributeName, string>>;
+interface CheckoutElementEventHandlers {
+    readonly onCopy?: (event: Event) => void;
+    readonly onOpenWallet?: (event: Event) => void;
+    readonly onState?: (event: Event) => void;
+    readonly onSettled?: (event: Event) => void;
+    readonly onProviderCopy?: (event: Event) => void;
+    readonly onStartOver?: (event: Event) => void;
+    readonly onError?: (event: Event) => void;
+}
+type CheckoutElementListeners = Partial<Record<CheckoutElementEventName, (event: Event) => void>>;
+interface CheckoutShellOptions extends Omit<CheckoutElementAttributeOptions, "theme">, CheckoutElementEventHandlers, StoredThemeModelOptions {
+    readonly rootSelector?: string;
+    readonly checkoutSelector?: string;
+    /**
+     * When false, omit the package theme toggle and do not stamp `data-theme` on the
+     * shell root or checkout. The checkout inherits from an ancestor `[data-theme]`
+     * (e.g. React `ThemeScope`). Default true for standalone embeds.
+     */
+    readonly themeToggle?: boolean;
+}
+interface CheckoutShellCheckoutBinding {
+    readonly tagName: typeof OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME;
+    readonly attributes: CheckoutElementAttributes;
+    readonly listeners: CheckoutElementListeners;
+}
+interface CheckoutShellThemeToggleBinding {
+    readonly tagName: typeof OPENRECEIVE_THEME_TOGGLE_ELEMENT_TAG_NAME;
+    readonly attributes: ThemeToggleElementAttributes;
+}
+interface CheckoutShellModel {
+    readonly theme: ThemeModel;
+    readonly rootAttributes: Partial<ThemeModel["attributes"]>;
+    readonly checkout: CheckoutShellCheckoutBinding;
+    readonly themeToggle: CheckoutShellThemeToggleBinding | null;
+}
+interface CheckoutElementDocument {
+    createElement(tagName: string): HTMLElement;
+}
+interface CreateOpenReceiveThemeToggleElementOptions extends ThemeToggleElementAttributeOptions {
+    readonly document?: CheckoutElementDocument;
+}
+interface CreateCheckoutShellOptions extends CheckoutShellOptions {
+    readonly document?: CheckoutElementDocument;
+    readonly root?: ThemeAttributeTarget | null;
+}
+interface CheckoutShellElements {
+    readonly theme: ThemeModel;
+    readonly rootAttributes: Partial<ThemeModel["attributes"]>;
+    readonly checkout: HTMLElement;
+    readonly themeToggle: HTMLElement | null;
+}
+/**
+ * The ONE derived view of a checkout: a snapshot plus a clock, flattened onto
+ * the attempt the payer is looking at, with the phase machine's verdict and the
+ * labels the UI prints. Produced only by `createCheckoutState`.
+ *
+ * It extends {@link CheckoutStateLabels}, so the labels ship with the state —
+ * including in the `openreceive-state` CustomEvent's `detail.state`.
+ */
+interface CheckoutState extends CheckoutStateLabels {
+    readonly checkout_id: string;
+    readonly reference: string;
+    readonly invoice_id: string;
+    readonly invoice: string;
+    readonly rail: "lightning" | "swap" | "checkout_lock";
+    readonly lightning_uri: string;
+    readonly payment_hash?: string;
+    readonly amount_msats?: number;
+    readonly fiat_quote?: CheckoutInvoiceSnapshot["fiat_quote"];
+    readonly transaction_state: string;
+    readonly workflow_state: string;
+    readonly expires_at?: number;
+    readonly expires_in_seconds?: number;
+    readonly phase: CheckoutPhase;
+    readonly settled: boolean;
+    readonly terminal: boolean;
+    readonly paid: boolean;
+    readonly settled_at?: number;
+    readonly swap?: CheckoutInvoiceSwapSnapshot;
+}
+interface CheckoutStatusModelInput {
+    readonly phase?: CheckoutPhase;
+    readonly waiting?: boolean;
+    readonly expires_in_seconds?: number;
+}
+interface CheckoutStatusModel {
+    readonly phase: CheckoutPhase;
+    readonly waiting: boolean;
+    readonly title: string;
+    readonly detail: string;
+    readonly countdownPrefix: string;
+    readonly expires_in_seconds?: number;
+    readonly countdownLabel?: string;
+}
+type CheckoutStatusRefresh = (reference: string) => Promise<CheckoutSnapshot | null>;
+type RequestCheckoutOptions = RequestCheckoutBaseOptions;
+/**
+ * `prepareCheckout` posts only the order id — it locks the amount and lists
+ * payment methods without minting — so there is no memo or metadata to carry.
+ */
+type PrepareCheckoutOptions = Pick<RequestCheckoutBaseOptions, "prefix" | "reference" | "fetch" | "headers">;
+interface RequestCheckoutBaseOptions {
+    /**
+     * Base path the shipped router is mounted at (e.g. `/openreceive`). The create and
+     * prepare routes are derived from it — see {@link checkoutRoutes}. It is required
+     * because it is the only URL input: there is no per-route override.
+     */
+    readonly prefix: string;
+    readonly reference: string;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly memo?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+interface CreateOpenReceiveStatusFetcherOptions {
+    /**
+     * Base path the shipped router is mounted at. The fetcher polls
+     * `${prefix}/payments/check` and reads live swap state from
+     * `${prefix}/swaps/status` — see {@link checkoutRoutes}.
+     */
+    readonly prefix: string;
+    readonly snapshot: CheckoutSnapshot;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+interface CheckoutWatcherOptions {
+    readonly snapshot: CheckoutSnapshot;
+    readonly refreshStatus?: CheckoutStatusRefresh;
+    readonly pollIntervalMs?: number;
+    readonly now?: () => number;
+    readonly setInterval?: typeof globalThis.setInterval;
+    readonly clearInterval?: typeof globalThis.clearInterval;
+    readonly logger?: BrowserLoggerOption;
+    readonly onState: (state: CheckoutState) => void;
+    readonly onSnapshot?: (snapshot: CheckoutSnapshot) => void;
+    readonly onError?: (error: unknown) => void;
+}
+interface CheckoutControllerOptions extends Omit<CheckoutWatcherOptions, "onState"> {
+    readonly onState?: (state: CheckoutState) => void;
+    /**
+     * Base path the shipped router is mounted at. Omitted, the controller does no
+     * status polling of its own — pass `refreshStatus` instead, or nothing at all
+     * to render a snapshot without polling.
+     */
+    readonly prefix?: string;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly statusHeaders?: Readonly<Record<string, string>>;
+    readonly clipboard?: Pick<Clipboard, "writeText">;
+    readonly open?: (uri: string) => void;
+}
+interface CheckoutController {
+    start(): CheckoutState;
+    stop(): void;
+    getState(): CheckoutState | undefined;
+    reloadState(): Promise<CheckoutState>;
+    /**
+     * Stop all timers and mark the checkout `cancelled`: the returned state (and
+     * every later `getState()`) carries the terminal `cancelled` phase.
+     */
+    cancel(): CheckoutState;
+    copyInvoice(): Promise<void>;
+    openWallet(): string;
+}
+interface CreateCheckoutStateOptions {
+    readonly now?: number;
+    readonly logger?: BrowserLoggerOption;
+    /**
+     * How this state was produced. Controls which browser log events fire:
+     * - `create` (default): `checkout.state.created`
+     * - `refresh`: `checkout.state.refreshed` plus `swap.state.changed` when swap fields move
+     * - `countdown`: no log (avoids per-second spam from the expiry ticker)
+     */
+    readonly source?: "create" | "refresh" | "countdown";
+    /** Prior checkout state; used with `source: "refresh"` to emit swap transition audits. */
+    readonly previousState?: CheckoutState;
+}
+type PaymentMethod = "bitcoin";
+type ThemePreference = "light" | "dark" | "system";
+type ResolvedTheme = "light" | "dark";
+interface PaymentMethodOption {
+    readonly id: PaymentMethod;
+    readonly title: string;
+    readonly detail: string;
+}
+interface ParseOpenReceiveOptionalIntegerOptions {
+    readonly label?: string;
+}
+interface ThemeModelOptions {
+    readonly systemDark?: boolean;
+}
+interface ThemeStorageOptions {
+    readonly storage?: Storage;
+    readonly storageKey?: string;
+}
+interface ReadThemePreferenceOptions extends ThemeStorageOptions {
+    readonly defaultTheme?: ThemePreference;
+}
+interface StoredThemeModelOptions extends ReadThemePreferenceOptions, ThemeModelOptions {
+}
+interface ThemeAttributeTarget {
+    getAttribute(name: string): string | null;
+    setAttribute(name: string, value: string): void;
+}
+interface ThemeLabelTarget {
+    textContent: string | null;
+}
+interface ThemeControlTargets {
+    readonly root?: ThemeAttributeTarget | null;
+    readonly checkout?: ThemeAttributeTarget | null;
+    readonly toggle?: ThemeLabelTarget | null;
+}
+interface ThemeModel {
+    readonly theme: ThemePreference;
+    readonly resolvedTheme: ResolvedTheme;
+    readonly nextTheme: ThemePreference;
+    readonly toggleLabel: string;
+    readonly attributes: {
+        readonly "data-theme": ResolvedTheme;
+        readonly "data-openreceive-theme": ResolvedTheme;
+    };
+    readonly checkoutElementAttributes: {
+        readonly theme: ResolvedTheme;
+    };
+}
+interface PaymentWizardSelection {
+    readonly selectedMethod: PaymentMethod | null;
+    readonly selectedBitcoinRoute: string | null;
+}
+type PaymentWizardSelectionAction = {
+    readonly type: "select_method";
+    readonly method: PaymentMethod;
+} | {
+    readonly type: "change_method";
+} | {
+    readonly type: "change_route";
+} | {
+    readonly type: "select_route";
+    readonly route: string;
+};
+interface PaymentWizardState {
+    readonly selectedRouteId: string | null;
+    readonly routes: readonly PaymentWizardRoute[];
+}
+interface PaymentWizardModel {
+    readonly selection: PaymentWizardSelection;
+    readonly wizard: PaymentWizardState;
+    readonly routeAssets: readonly AssetIndexEntry[];
+    readonly selectedRoute: string | null;
+}
+interface PaymentWizardControllerOptions {
+    readonly selection?: PaymentWizardSelection;
+    readonly onSelection?: (selection: PaymentWizardSelection) => void;
+}
+interface PaymentWizardController {
+    getSelection(): PaymentWizardSelection;
+    getModel(): PaymentWizardModel;
+    update(action: PaymentWizardSelectionAction): PaymentWizardSelection;
+    selectMethod(method: PaymentMethod): PaymentWizardSelection;
+    changeMethod(): PaymentWizardSelection;
+    selectRoute(route: string): PaymentWizardSelection;
+}
+interface WizardRouteAssetDisplay {
+    readonly id: string;
+    readonly label: string;
+    readonly subtitle: string;
+    readonly icon: string;
+    readonly selected: boolean;
+}
+interface WizardProviderTutorialDisplay {
+    readonly index: number;
+    readonly path: string;
+    readonly image: string;
+    readonly caption: string;
+}
+interface WizardProviderDisplay {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly url: string;
+    readonly icon: string;
+    readonly tutorials: readonly WizardProviderTutorialDisplay[];
+    readonly copyLabel: string;
+    readonly copiedLabel: string;
+    readonly openLabel: string;
+}
+interface WizardRouteDisplay {
+    readonly key: string;
+    readonly title: string;
+    readonly subtitle: string;
+    readonly providers: readonly WizardProviderDisplay[];
+}
+/**
+ * One display row for post-settlement transaction details. Values are already
+ * formatted for UI; `copyValue` is the full string when the display value is truncated.
+ * Never includes NWC secrets — those are not part of checkout public state.
+ * Optional `href` is a block-explorer or Lightning invoice decode link.
+ */
+interface TransactionDetailRow {
+    readonly label: string;
+    readonly value: string;
+    readonly copyValue?: string;
+    readonly href?: string;
+    readonly hrefLabel?: string;
+}
+interface TransactionDetailsInput {
+    readonly reference?: string;
+    readonly checkout_id?: string;
+    readonly invoice_id?: string;
+    readonly invoice?: string | null;
+    readonly rail?: "lightning" | "swap" | "checkout_lock";
+    readonly payment_hash?: string;
+    readonly amount_msats?: number;
+    readonly fiat_quote?: CheckoutInvoiceSnapshot["fiat_quote"];
+    readonly transaction_state?: string;
+    readonly workflow_state?: string;
+    readonly expires_at?: number;
+    readonly settled_at?: number;
+    readonly swap?: CheckoutInvoiceSwapSnapshot;
+    /**
+     * Base URL of a host-chosen bolt11 decoder. Omitted (the default), the
+     * Lightning invoice row carries no decode link and the invoice is never
+     * handed to a third party.
+     */
+    readonly decodeLinkUrl?: string;
+}
+
+declare function assertDisplayInvoice(invoice: string): void;
+declare function createLightningUri(invoice: string): string;
+
+declare class BrowserRequestError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly retryable?: boolean;
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, options: {
+        readonly status: number;
+        readonly code?: string;
+        readonly retryable?: boolean;
+        readonly retryAfterSeconds?: number;
+    });
+}
+declare function requestCheckout(options: RequestCheckoutOptions): Promise<CheckoutSnapshot>;
+/**
+ * Lock the host order amount and load payment methods without minting Lightning.
+ * Bitcoin selection later calls {@link requestCheckout} to mint (or reuse) a bolt11.
+ */
+declare function prepareCheckout(options: PrepareCheckoutOptions): Promise<CheckoutSnapshot>;
+declare function createStatusFetcher(options: CreateOpenReceiveStatusFetcherOptions): CheckoutStatusRefresh;
+
+declare function createQrSvg(invoice: string, options?: QrOptions): Promise<string>;
+declare function createQrPayloadSvg(payload: string, options?: QrOptions): Promise<string>;
+declare function createQrPngDataUrl(invoice: string, options?: QrOptions): Promise<string>;
+declare function copyInvoice(options: CopyInvoiceOptions): Promise<void>;
+declare function openWallet(options: OpenWalletOptions): string;
+
+declare function createCheckoutController(options: CheckoutControllerOptions): CheckoutController;
+
+/**
+ * Guest checkout resume helpers for no-account content sites.
+ *
+ * Pattern:
+ * - Put the public `reference` in the URL (`/checkout/:reference`) so refresh/share works.
+ * - Let the host authorize access to the order using its normal session or guest-order policy.
+ * - Mirror an optional host order summary in sessionStorage for instant same-tab restore;
+ *   use the host-supplied `fetchOrder` when storage is empty.
+ *
+ */
+interface GuestCheckoutResumeOptions<TOrder> {
+    /**
+     * URL path prefix before the order id. Default `"/checkout"` → `/checkout/:reference`.
+     * Leading/trailing slashes are normalized.
+     */
+    readonly pathPrefix?: string;
+    /** sessionStorage key prefix for host order summaries (required so hosts do not collide). */
+    readonly storageKeyPrefix: string;
+    /** Extract the public order id used as the storage/URL key. */
+    readonly referenceOf: (order: TOrder) => string;
+    /** Validate a value from storage or a fetch body as a host order. */
+    readonly parseOrder: (value: unknown) => TOrder | undefined;
+    /**
+     * Load an order when sessionStorage misses (new tab / shared link).
+     * Return `undefined` for missing or unauthorized orders.
+     */
+    readonly fetchOrder?: (reference: string) => Promise<TOrder | undefined>;
+    /** Path to push when leaving a checkout URL. Default `"/"`. */
+    readonly homePath?: string;
+}
+interface GuestCheckoutResumeController<TOrder> {
+    /** Normalized path prefix including a leading slash, e.g. `"/checkout"`. */
+    readonly pathPrefix: string;
+    checkoutPath(reference: string): string;
+    /** Parse `/checkout/:reference` from a pathname. Returns undefined when not a resume URL. */
+    parseReference(pathname: string): string | undefined;
+    rememberOrder(order: TOrder): void;
+    readRememberedOrder(reference: string): TOrder | undefined;
+    /** Forget one order, or every order under this storage prefix when `reference` is omitted. */
+    forgetOrder(reference?: string): void;
+    /** Push the checkout path when not already there (History API / SPAs). */
+    enterCheckout(reference: string): void;
+    /** Return to `homePath` when the current location is a checkout resume URL. */
+    leaveCheckout(): void;
+    /** sessionStorage first, then optional `fetchOrder`. */
+    loadOrderForResume(reference: string): Promise<TOrder | undefined>;
+}
+/**
+ * Create a host-owned guest resume controller. OpenReceive does not invent a host session —
+ * this is the reusable URL + sessionStorage glue so demos (and apps) do not copy-paste it.
+ */
+declare function createGuestCheckoutResume<TOrder>(options: GuestCheckoutResumeOptions<TOrder>): GuestCheckoutResumeController<TOrder>;
+/**
+ * Push `/checkout/:reference` (or a custom path prefix) via the History API when not already
+ * there. Used by `<Checkout syncUrl>` and hosts that sync the URL after creating an order.
+ * No-ops when `routeReference` is provided (app router already owns the URL).
+ */
+declare function enterCheckoutResumePath(reference: string, options?: {
+    readonly pathPrefix?: string;
+    /** When set, skip History API sync (Next.js / file-based routes own the URL). */
+    readonly routeReference?: string;
+}): void;
+/**
+ * Guest resume fetch for a host-owned order endpoint. OpenReceive ships no order-read route.
+ * Pass the result as `fetchOrder` to {@link createGuestCheckoutResume}.
+ */
+declare function createGuestOrderFetcher<TOrder>(options: {
+    readonly parseOrder: (value: unknown) => TOrder | undefined;
+    /**
+     * Build the URL of the HOST APPLICATION's own order endpoint (e.g. `/orders/:id`).
+     * Nothing here is an OpenReceive route: the mounted router's routes all come from
+     * `prefix` (see ./routes.ts), and it serves no order-read endpoint at all.
+     */
+    readonly hostOrderUrl: (reference: string) => string;
+    readonly fetch?: typeof globalThis.fetch;
+}): (reference: string) => Promise<TOrder | undefined>;
+
+/** The payer-facing status: exactly {@link TransactionSettlementStatus}, derived from the server's verdict and the expiry clock. */
+type Status = TransactionSettlementStatus;
+interface StatusInvoiceLike {
+    readonly transaction_state?: string;
+    readonly expires_at?: number | string | null;
+}
+declare function deriveStatus(invoice: StatusInvoiceLike, options?: {
+    readonly now?: number;
+}): Status;
+
+export { OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES as $, type ThemeToggleElementAttributes as A, type BrowserLoggerOption as B, type CheckoutInvoiceSnapshot as C, type StoredThemeModelOptions as D, type ThemeModel as E, type ThemeModelOptions as F, type ReadThemePreferenceOptions as G, type ThemeControlTargets as H, type ThemeStorageOptions as I, type PaymentWizardControllerOptions as J, type PaymentWizardController as K, type PaymentWizardSelection as L, type PaymentWizardModel as M, type WizardRouteDisplay as N, type PaymentWizardSelectionAction as O, type ParseOpenReceiveOptionalIntegerOptions as P, type BrowserLogContext as Q, type ResolvedTheme as R, type SwapDisplayModel as S, type ThemePreference as T, type BrowserLogger as U, BrowserRequestError as V, type WizardRouteAssetDisplay as W, type CheckoutController as X, type CheckoutControllerOptions as Y, type CheckoutPhase as Z, type CheckoutStatusRefresh as _, type PaymentMethod as a, OPENRECEIVE_CHECKOUT_DATA_SELECTORS as a0, OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES as a1, OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS as a2, OPENRECEIVE_CHECKOUT_ELEMENT_PARTS as a3, OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS as a4, OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME as a5, OPENRECEIVE_COPY_FEEDBACK_MS as a6, OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS as a7, OPENRECEIVE_DEFAULT_PREFIX as a8, OPENRECEIVE_PAYMENT_WIZARD_ATTRIBUTES as a9, formatDepositAmount as aA, formatFiatAmount as aB, formatMsats as aC, formatSwapLimit as aD, formatUnixTime as aE, openWallet as aF, prepareCheckout as aG, requestCheckout as aH, type BrowserLogLevel as aI, type BrowserLogEntry as aJ, type CopyInvoiceOptions as aK, type GuestCheckoutResumeController as aL, type GuestCheckoutResumeOptions as aM, type OpenWalletOptions as aN, type PrepareCheckoutOptions as aO, type QrOptions as aP, type RequestCheckoutOptions as aQ, type StatusInvoiceLike as aR, createGuestCheckoutResume as aS, createGuestOrderFetcher as aT, createLightningUri as aU, createQrPngDataUrl as aV, OPENRECEIVE_PAYMENT_WIZARD_SELECTORS as aa, OPENRECEIVE_THEME_STORAGE_KEY as ab, OPENRECEIVE_THEME_TOGGLE_ELEMENT_ATTRIBUTES as ac, OPENRECEIVE_THEME_TOGGLE_ELEMENT_EVENTS as ad, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PARTS as ae, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PART_SELECTORS as af, OPENRECEIVE_THEME_TOGGLE_ELEMENT_TAG_NAME as ag, type QrEncoder as ah, type Status as ai, type WizardProviderDisplay as aj, assertDisplayInvoice as ak, copyInvoice as al, createCheckoutActionEvent as am, createCheckoutController as an, createCheckoutErrorEvent as ao, createCheckoutProviderCopyEvent as ap, createCheckoutStateEvent as aq, createQrPayloadSvg as ar, createQrSvg as as, createStatusFetcher as at, createThemeChangeEvent as au, deriveCheckoutStateLabels as av, deriveStatus as aw, enterCheckoutResumePath as ax, escapeHtml as ay, formatAmountCaption as az, type PaymentMethodOption as b, type TickingValueOptions as c, type TickingValueController as d, type TransientFeedbackOptions as e, type TransientFeedbackController as f, type CheckoutInvoiceSwapSnapshot as g, type CheckoutState as h, type TransactionDetailsInput as i, type TransactionDetailRow as j, type CheckoutSnapshot as k, type CreateCheckoutStateOptions as l, type CheckoutStatusModelInput as m, type CheckoutStatusModel as n, type CheckoutPaymentMethod as o, type ThemeAttributeTarget as p, type CheckoutElementAttributes as q, type CheckoutElementAttributeOptions as r, type CheckoutElementEventHandlers as s, type CheckoutElementListeners as t, type CreateCheckoutShellOptions as u, type CheckoutShellElements as v, type CheckoutShellOptions as w, type CheckoutShellModel as x, type CreateOpenReceiveThemeToggleElementOptions as y, type ThemeToggleElementAttributeOptions as z };