@openreceive/browser 0.2.3 → 0.3.0

package/dist/{status-B1vDOhvh.d.ts → status-C-zvqBau.d.ts}

@@ -174,6 +174,8 @@ declare const OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES: {
     readonly meta: "data-openreceive-meta";
     readonly state: "data-openreceive-state";
     readonly actions: "data-openreceive-actions";
+    /** What the payer is buying, when the host's amount hook named it. */
+    readonly orderDescription: "data-openreceive-order-description";
     readonly theme: "data-openreceive-theme";
     readonly themeToggle: "data-openreceive-theme-toggle";
 };
@@ -183,6 +185,7 @@ declare const OPENRECEIVE_CHECKOUT_DATA_SELECTORS: {
     readonly meta: "[data-openreceive-meta]";
     readonly state: "[data-openreceive-state]";
     readonly actions: "[data-openreceive-actions]";
+    readonly orderDescription: "[data-openreceive-order-description]";
     readonly theme: "[data-openreceive-theme]";
     readonly themeToggle: "[data-openreceive-theme-toggle]";
 };
@@ -190,6 +193,17 @@ declare const OPENRECEIVE_CHECKOUT_ELEMENT_PARTS: {
     readonly copy: "copy";
     readonly startOver: "start-over";
 };
+/**
+ * Named slots the checkout element projects host light-DOM children into.
+ *
+ * `order` is the element's answer to React's render-prop `children`: a line-item
+ * strip, a thumbnail, a "you are buying" summary, drawn from the order
+ * OpenReceive does not own. It is projected through a `<slot>` in the shadow
+ * root, so it survives every re-render of the shell's `innerHTML` untouched.
+ */
+declare const OPENRECEIVE_CHECKOUT_ELEMENT_SLOTS: {
+    readonly order: "order";
+};
 declare const OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS: {
     readonly copy: "[part=\"copy\"]";
     readonly startOver: "[part=\"start-over\"]";
@@ -259,6 +273,17 @@ declare const OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES: {
      * default), no decode link is rendered and the invoice never leaves the page.
      */
     readonly decodeLinkUrl: "decode-link-url";
+    /**
+     * Where this app serves the packages' `dist/assets` trees, as one base URL —
+     * the string form of the `resolveAssetUrl` seam, so plain markup and the
+     * Vue/Svelte/Angular wrappers can reach it (a function cannot cross an HTML
+     * attribute). Every packaged key is a relative path under one `assets/` root,
+     * so the value is joined to it directly: `asset-base-url="/openreceive-assets"`
+     * makes `assets/icons/btc.svg` load from
+     * `/openreceive-assets/assets/icons/btc.svg`. A `resolveAssetUrl` passed to
+     * `defineElements` wins over it.
+     */
+    readonly assetBaseUrl: "asset-base-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. */
@@ -312,6 +337,11 @@ interface CopyInvoiceOptions {
 }
 interface OpenWalletOptions {
     invoice: string;
+    /**
+     * Where to send the `lightning:` URI. Omitted, {@link openWallet} calls
+     * `location.assign` on the CURRENT window, which navigates the payer off a
+     * still-polling checkout on any device that has a handler registered.
+     */
     open?: (uri: string) => void;
     logger?: BrowserLoggerOption;
     logContext?: BrowserLogContext;
@@ -385,21 +415,89 @@ interface SwapFeeBreakdown {
     /** The fee as a percentage of the cart total, e.g. "5.9%", when computable. */
     readonly feePercent?: string;
 }
+/** One value the payer has to reproduce, with the affordance that lets them. */
+interface SwapCopyRow {
+    readonly label: string;
+    readonly value: string;
+    /** The untruncated string a copy button writes, when it differs from `value`. */
+    readonly copyValue?: string;
+    /** Render the value in a selectable field rather than a code block. */
+    readonly selectable: boolean;
+}
+/**
+ * How a deposit on this rail can actually go missing, which is what decides how
+ * loud the deposit panel should be.
+ *
+ * The exposure comes from the deposit ADDRESS failing to pin the chain or the
+ * asset, never from whether the coin is native:
+ *
+ * - `chain_ambiguous` — the address is byte-identical on other chains, so a
+ *   withdrawal can land somewhere unreachable. Every EVM rail (`ETH_ETH`,
+ *   `USDT_ETH`, `USDC_ETH`): a `0x…` address is the same string on Ethereum,
+ *   Arbitrum, Optimism, Base, BSC and Polygon and carries nothing that says
+ *   which. A rail whose network OpenReceive cannot classify is reported here
+ *   too — an unrecognized format has no rule proving it is safe.
+ * - `asset_only` — the address format pins the chain, but the asset is a token
+ *   on it, and every exchange's withdrawal dropdown offers that ticker on a
+ *   dozen networks (`USDT_TRON`).
+ * - `pinned` — the address format pins the chain AND the asset is that chain's
+ *   native coin, so neither mistake is reachable (`SOL_SOL`). Sending an SPL
+ *   token to a Solana address still will not credit the order, so the panel
+ *   still states the exact amount — it just does not shout about lost funds.
+ *
+ * `chain_ambiguous` and `asset_only` both warrant the full alarm; they are kept
+ * apart because they are different mistakes and a custom UI may want to say so.
+ * Note the counter-intuitive half: `ETH_ETH` is a NATIVE coin and needs the
+ * alarm most of anything on the list.
+ */
+type SwapDepositRisk = "chain_ambiguous" | "asset_only" | "pinned";
 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". */
+    /**
+     * Which of the two ways a deposit is lost is reachable on this rail. Drives
+     * `networkWarningTitle`/`networkWarning` below, and is exposed so a custom UI
+     * can pick its own chrome without re-deriving the asset table. See
+     * {@link SwapDepositRisk}.
+     */
+    readonly depositRisk: SwapDepositRisk;
+    /**
+     * Deposit-panel heading. A strong alert ("Wrong currency or network = lost
+     * funds") when `depositRisk` is anything but `pinned`, and a quiet
+     * "Send the exact amount" when it is. A banner shown on every rail is read on
+     * none, and the rails where it is load-bearing are the ones that pay for it.
+     */
     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). */
+    /**
+     * Full plain-text network warning (accessible / non-HTML consumers). The
+     * lost-funds sentence is present only when `depositRisk` is not `pinned`; the
+     * "pay with one method only" sentence is on every rail, because double-paying
+     * is reachable on all of them.
+     */
     readonly networkWarning: string;
     readonly depositAddress: string;
     readonly depositMemo?: string;
+    /**
+     * BARE, with no asset symbol appended: it pastes into a wallet's amount field,
+     * where "0.032664 SOL" is not a number. Join the symbol at the point of
+     * display if a sentence needs it.
+     */
     readonly depositAmount: string;
+    /**
+     * Every value the payer must reproduce, as labelled rows: the deposit address,
+     * the memo where the rail has one, and the amount. The amount is the one that
+     * gets left out and the one that costs money — on token rails (USDT_TRON,
+     * USDT_ETH, USDC_ETH) the QR encodes the bare address and carries NO amount,
+     * so the payer types it off the screen, and a short send against a fixed-rate
+     * swap order is an underpayment: `refund_required`, a refund form, and a payer
+     * who has to come back.
+     */
+    readonly copyRows: readonly SwapCopyRow[];
     readonly providerStateLabel: string;
     readonly providerStateDetail: string;
     readonly state: "creating" | "deposit" | "progress" | "settled" | "expired" | "refund_required" | "refund_pending" | "refunded" | "attention" | "failed";
@@ -441,6 +539,11 @@ interface CheckoutInvoiceSnapshot {
     readonly expires_at?: number;
     readonly settled_at?: number;
     readonly swap?: CheckoutInvoiceSwapSnapshot;
+    /**
+     * What the payer is buying, carried through from the snapshot. Data, not a
+     * derived label, so it survives `normalizeCheckoutState`.
+     */
+    readonly description?: string;
 }
 interface CheckoutPaymentMethod {
     readonly pay_in_asset: string;
@@ -475,6 +578,13 @@ interface CheckoutSnapshot {
     readonly active?: CheckoutInvoiceSnapshot;
     readonly invoices: readonly CheckoutInvoiceSnapshot[];
     readonly payment_methods?: readonly CheckoutPaymentMethod[];
+    /**
+     * What the payer is buying, in the host's own words — one display string the
+     * host returned from `amountFor` / `amount_for`. OpenReceive owns no line
+     * items, so this is the whole of what it carries; a richer summary is the
+     * host's own markup (React `children`, the element's `order` slot).
+     */
+    readonly description?: string;
 }
 interface CheckoutElementAttributeOptions {
     /**
@@ -514,6 +624,14 @@ interface CheckoutElementAttributeOptions {
      * renders no "Decode" link and the invoice is never sent to a third party.
      */
     readonly decodeLinkUrl?: string;
+    /**
+     * Where this app serves the packages' `dist/assets` trees, as one base URL.
+     * The string form of the `resolveAssetUrl` seam: every packaged asset key is a
+     * relative path under one `assets/` root, so the value is joined to it
+     * directly. Emitted as the element's `asset-base-url` attribute, which is how
+     * the Vue/Svelte/Angular wrappers reach a seam a function cannot cross.
+     */
+    readonly assetBaseUrl?: 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. */
@@ -688,12 +806,49 @@ interface CheckoutControllerOptions extends Omit<CheckoutWatcherOptions, "onStat
      * to render a snapshot without polling.
      */
     readonly prefix?: string;
+    /**
+     * False renders the snapshot without a status fetcher of its own. `prefix`
+     * still names the mount, so the swap-refund calls keep working — polling and
+     * "where the routes live" are two questions.
+     */
+    readonly polling?: boolean;
     readonly fetch?: typeof globalThis.fetch;
     readonly statusHeaders?: Readonly<Record<string, string>>;
     readonly clipboard?: Pick<Clipboard, "writeText">;
     readonly open?: (uri: string) => void;
 }
-interface CheckoutController {
+/**
+ * The two-step swap refund, and the staging that makes it survive polling. The
+ * controller implements it; a renderer that is handed one (React's
+ * `PaymentWizard`) takes exactly this much of it.
+ */
+interface SwapRefundStaging {
+    /**
+     * Step one: post `/swaps/status` and hold the address the payer typed so the
+     * panel can show it back for confirmation. It touches no refund route —
+     * nothing is submitted until {@link confirmSwapRefund}.
+     *
+     * The staged address is folded into every later snapshot, so polling cannot
+     * wipe what the payer is reviewing. `attemptId` is
+     * `SwapDisplayModel.attemptId`; the payment hash is resolved from the
+     * snapshot already in hand.
+     */
+    stageSwapRefund(options: {
+        readonly attemptId: string;
+        readonly refundAddress: string;
+    }): Promise<CheckoutInvoiceSnapshot>;
+    /** Step two: the only call that posts `/swaps/refunds`. */
+    confirmSwapRefund(options: {
+        readonly attemptId: string;
+        readonly refundAddress: string;
+    }): Promise<CheckoutInvoiceSnapshot>;
+    /**
+     * Drop the staged address. The payer leaving the swap for Lightning is the one
+     * exit that is not a submitted refund.
+     */
+    clearSwapRefundStaging(): void;
+}
+interface CheckoutController extends SwapRefundStaging {
     start(): CheckoutState;
     stop(): void;
     getState(): CheckoutState | undefined;
@@ -814,6 +969,8 @@ interface WizardRouteAssetDisplay {
     readonly label: string;
     readonly subtitle: string;
     readonly icon: string;
+    /** The packaged key behind `icon`, for a host serving the files itself. */
+    readonly iconPath: string;
     readonly selected: boolean;
 }
 interface WizardProviderTutorialDisplay {
@@ -828,6 +985,13 @@ interface WizardProviderDisplay {
     readonly kind: string;
     readonly url: string;
     readonly icon: string;
+    /**
+     * The packaged path the icon came from (`assets/provider-icons/strike.png`).
+     * `icon` is only loadable when the host's bundler resolved it; this is the
+     * key a host that serves the files itself maps, without going back to
+     * `providerRegistry` for `icon_path`.
+     */
+    readonly iconPath: string;
     readonly tutorials: readonly WizardProviderTutorialDisplay[];
     readonly copyLabel: string;
     readonly copiedLabel: string;
@@ -901,6 +1065,23 @@ declare function createQrSvg(invoice: string, options?: QrOptions): Promise<stri
 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>;
+/**
+ * Hand the invoice to the payer's wallet as a `lightning:` URI, and return the
+ * URI. **Touch devices.**
+ *
+ * The default path is `location.assign` on the CURRENT window — the right
+ * primitive for a custom-scheme deep link on a phone, and the wrong thing
+ * anywhere else. With no registered `lightning:` handler the call does nothing
+ * visible; with one, it navigates the payer off a checkout that is still
+ * polling `/payments/check`. Pass `open` to route the URI somewhere that is not
+ * the checkout window.
+ *
+ * This is why the shipped `<Checkout>` renders no wallet button of its own and
+ * exposes `components.OpenWalletButton` as an opt-in slot instead: a desktop
+ * payer is never sent to a handler that does not exist, next to the QR code
+ * that IS the desktop payment path. A custom UI drawing its own button owns
+ * that decision — see docs/guides/headless-checkout.md.
+ */
 declare function openWallet(options: OpenWalletOptions): string;
 
 declare function createCheckoutController(options: CheckoutControllerOptions): CheckoutController;
@@ -998,4 +1179,4 @@ declare function deriveStatus(invoice: StatusInvoiceLike, options?: {
     readonly now?: UnixSeconds;
 }): Status;
 
-export { type CheckoutStatusRefresh 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 UnixSeconds as U, type BrowserLogger as V, type WizardRouteAssetDisplay as W, BrowserRequestError as X, type CheckoutController as Y, type CheckoutControllerOptions as Z, type CheckoutPhase as _, type PaymentMethod as a, OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES as a0, OPENRECEIVE_CHECKOUT_DATA_SELECTORS as a1, OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES as a2, OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS as a3, OPENRECEIVE_CHECKOUT_ELEMENT_PARTS as a4, OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS as a5, OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME as a6, OPENRECEIVE_COPY_FEEDBACK_MS as a7, OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS as a8, OPENRECEIVE_DEFAULT_PREFIX as a9, formatAmountCaption as aA, formatDepositAmount as aB, formatFiatAmount as aC, formatMsats as aD, formatSwapLimit as aE, formatUnixTime as aF, openWallet as aG, prepareCheckout as aH, requestCheckout as aI, type BrowserLogLevel as aJ, type BrowserLogEntry as aK, type CopyInvoiceOptions as aL, type GuestCheckoutResumeController as aM, type GuestCheckoutResumeOptions as aN, type OpenWalletOptions as aO, type PrepareCheckoutOptions as aP, type QrOptions as aQ, type RequestCheckoutOptions as aR, type StatusInvoiceLike as aS, createGuestCheckoutResume as aT, createGuestOrderFetcher as aU, createLightningUri as aV, createQrPngDataUrl as aW, OPENRECEIVE_PAYMENT_WIZARD_ATTRIBUTES as aa, OPENRECEIVE_PAYMENT_WIZARD_SELECTORS as ab, OPENRECEIVE_THEME_STORAGE_KEY as ac, OPENRECEIVE_THEME_TOGGLE_ELEMENT_ATTRIBUTES as ad, OPENRECEIVE_THEME_TOGGLE_ELEMENT_EVENTS as ae, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PARTS as af, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PART_SELECTORS as ag, OPENRECEIVE_THEME_TOGGLE_ELEMENT_TAG_NAME as ah, type QrEncoder as ai, type Status as aj, type WizardProviderDisplay as ak, assertDisplayInvoice as al, copyInvoice as am, createCheckoutActionEvent as an, createCheckoutController as ao, createCheckoutErrorEvent as ap, createCheckoutProviderCopyEvent as aq, createCheckoutStateEvent as ar, createQrPayloadSvg as as, createQrSvg as at, createStatusFetcher as au, createThemeChangeEvent as av, deriveCheckoutStateLabels as aw, deriveStatus as ax, enterCheckoutResumePath as ay, escapeHtml 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 };
+export { type CheckoutStatusRefresh 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 UnixSeconds as U, type BrowserLogger as V, type WizardRouteAssetDisplay as W, BrowserRequestError as X, type CheckoutController as Y, type CheckoutControllerOptions as Z, type CheckoutPhase as _, type PaymentMethod as a, OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES as a0, OPENRECEIVE_CHECKOUT_DATA_SELECTORS as a1, OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES as a2, OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS as a3, OPENRECEIVE_CHECKOUT_ELEMENT_PARTS as a4, OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS as a5, OPENRECEIVE_CHECKOUT_ELEMENT_SLOTS as a6, OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME as a7, OPENRECEIVE_COPY_FEEDBACK_MS as a8, OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS as a9, deriveStatus as aA, enterCheckoutResumePath as aB, escapeHtml as aC, formatAmountCaption as aD, formatDepositAmount as aE, formatFiatAmount as aF, formatMsats as aG, formatSwapLimit as aH, formatUnixTime as aI, openWallet as aJ, prepareCheckout as aK, requestCheckout as aL, type BrowserLogLevel as aM, type BrowserLogEntry as aN, type CopyInvoiceOptions as aO, type GuestCheckoutResumeController as aP, type GuestCheckoutResumeOptions as aQ, type OpenWalletOptions as aR, type PrepareCheckoutOptions as aS, type QrOptions as aT, type RequestCheckoutOptions as aU, type StatusInvoiceLike as aV, createGuestCheckoutResume as aW, createGuestOrderFetcher as aX, createLightningUri as aY, createQrPngDataUrl as aZ, OPENRECEIVE_DEFAULT_PREFIX as aa, OPENRECEIVE_PAYMENT_WIZARD_ATTRIBUTES as ab, OPENRECEIVE_PAYMENT_WIZARD_SELECTORS as ac, OPENRECEIVE_THEME_STORAGE_KEY as ad, OPENRECEIVE_THEME_TOGGLE_ELEMENT_ATTRIBUTES as ae, OPENRECEIVE_THEME_TOGGLE_ELEMENT_EVENTS as af, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PARTS as ag, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PART_SELECTORS as ah, OPENRECEIVE_THEME_TOGGLE_ELEMENT_TAG_NAME as ai, type QrEncoder as aj, type Status as ak, type SwapCopyRow as al, type SwapRefundStaging as am, type WizardProviderDisplay as an, assertDisplayInvoice as ao, copyInvoice as ap, createCheckoutActionEvent as aq, createCheckoutController as ar, createCheckoutErrorEvent as as, createCheckoutProviderCopyEvent as at, createCheckoutStateEvent as au, createQrPayloadSvg as av, createQrSvg as aw, createStatusFetcher as ax, createThemeChangeEvent as ay, deriveCheckoutStateLabels as az, type PaymentMethodOption as b, type TickingValueOptions as c, type TickingValueController as d, type TransientFeedbackOptions as e, type TransientFeedbackController as f, type CheckoutSnapshot as g, type SwapDepositRisk as h, type CheckoutState as i, type TransactionDetailsInput as j, type TransactionDetailRow 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 };