@openreceive/browser 0.2.4 → 0.3.1

package/dist/{status-D3VhJsUp.d.ts → status-BZEGi6Ca.d.ts}

@@ -102,6 +102,7 @@ declare const OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS: 3000;
  */
 declare const OPENRECEIVE_DEFAULT_PREFIX: "/openreceive";
 declare const OPENRECEIVE_COPY_FEEDBACK_MS: 1800;
+declare const OPENRECEIVE_PROVIDER_PREVIEW_LIMIT: 4;
 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: {
@@ -174,6 +175,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 +186,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 +194,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\"]";
@@ -253,12 +268,31 @@ declare const OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES: {
      * push/replace the URL via the History API.
      */
     readonly routeReference: "route-reference";
+    /**
+     * Does a payer who closes this tab have a URL that brings them back to this
+     * checkout? Only the refund screen's copy depends on it — see
+     * `SwapDisplayModel.refundReturnLabel`. Unset, the element infers it from
+     * `sync-url` / `route-reference`; set it when the host owns a per-order route
+     * of its own, which the element cannot see.
+     */
+    readonly resumable: "resumable";
     /**
      * 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";
+    /**
+     * 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. */
@@ -390,6 +424,15 @@ 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.
@@ -448,7 +491,22 @@ interface SwapDisplayModel {
     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";
@@ -467,6 +525,18 @@ interface SwapDisplayModel {
      * refund_address.
      */
     readonly refundAllowed: boolean;
+    /**
+     * What to tell the payer about getting BACK to this refund screen, already
+     * decided from whether the host said the checkout is resumable.
+     *
+     * `checkoutLabels.refundReturnWarning` — "Bookmark this page…" — is only true
+     * if the checkout HAS a URL. A swap checkout that lives at one route with no
+     * per-order path (a single-page shop, a modal) sends that payer back to an
+     * empty checkout and their deposit is unreachable through the UI. So the
+     * choice is made here, from one declared fact, rather than left to every host
+     * to notice: render this string, never either label directly.
+     */
+    readonly refundReturnLabel: string;
     readonly refundTxId?: string;
     readonly refundReason?: string;
     readonly depositReceivedAmount?: string;
@@ -490,6 +560,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;
@@ -524,6 +599,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 {
     /**
@@ -558,11 +640,24 @@ interface CheckoutElementAttributeOptions {
      * Order id from the app router (e.g. Next.js). When set, skip History API URL sync.
      */
     readonly routeReference?: string;
+    /**
+     * Does a payer who closes this tab have a URL that brings them back? Emitted
+     * in every mode, because the refund screen it governs shows in every mode.
+     */
+    readonly resumable?: boolean;
     /**
      * 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;
+    /**
+     * 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. */
@@ -737,12 +832,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;
@@ -863,6 +995,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 {
@@ -893,7 +1027,18 @@ interface WizardRouteDisplay {
     readonly key: string;
     readonly title: string;
     readonly subtitle: string;
+    /**
+     * The providers to draw — every one the route has, or the first
+     * `providerPreviewLimit` of them.
+     */
     readonly providers: readonly WizardProviderDisplay[];
+    /**
+     * How many the route has in total, before any preview limit. The registry
+     * carries ~37 wallets for Lightning, so a host that renders them beside a QR
+     * needs a limit and a "show all N" affordance; this is the N, and
+     * {@link WizardRouteDisplay.providers}.length is what it is showing.
+     */
+    readonly providerCount: number;
 }
 /**
  * One display row for post-settlement transaction details. Values are already
@@ -975,6 +1120,42 @@ declare function copyInvoice(options: CopyInvoiceOptions): Promise<void>;
  * that decision — see docs/guides/headless-checkout.md.
  */
 declare function openWallet(options: OpenWalletOptions): string;
+/**
+ * A QR that follows a changing payload, without every host rewriting the same
+ * effect.
+ *
+ * {@link createQrSvg} and {@link createQrPayloadSvg} are ASYNC, and that is the
+ * trap: `dangerouslySetInnerHTML={{ __html: createQrSvg(invoice) }}` type-checks
+ * (React types `__html` as `string | TrustedHTML`, and `TrustedHTML` is an empty
+ * interface every object satisfies) and paints the literal text
+ * "[object Promise]" inside the QR box. Resolving it by hand then needs the
+ * other half nobody writes the first time: a slow encode that lands AFTER the
+ * payload changed must not paint the old QR over the new one.
+ *
+ * So: call `show`/`showPayload` whenever the payload changes and render what
+ * `onValue` last handed you. Only the newest call can publish — an earlier
+ * encode still in flight is dropped, resolved or rejected. `stop()` drops the
+ * one in flight, for a host going away. Same shape as
+ * {@link createTickingValueController}: DOM-free, framework-free, one
+ * implementation instead of one per renderer.
+ */
+interface QrSvgControllerOptions {
+    /** The newest encoded SVG. Not called for a superseded or stopped encode. */
+    onValue(svg: string): void;
+    /** Encode failures, on the same terms. */
+    onError?(error: unknown): void;
+    readonly encoder?: QrEncoder;
+    readonly width?: number;
+}
+interface QrSvgController {
+    /** Encode a bolt11, as the `lightning:` URI a wallet expects. */
+    show(invoice: string): void;
+    /** Encode a payload verbatim — a swap deposit URI, say. */
+    showPayload(payload: string): void;
+    /** Publish nothing further; the encode in flight is abandoned. */
+    stop(): void;
+}
+declare function createQrSvgController(options: QrSvgControllerOptions): QrSvgController;
 
 declare function createCheckoutController(options: CheckoutControllerOptions): CheckoutController;
 
@@ -1071,4 +1252,4 @@ declare function deriveStatus(invoice: StatusInvoiceLike, options?: {
     readonly now?: UnixSeconds;
 }): Status;
 
-export { type CheckoutPhase as $, type ThemeToggleElementAttributeOptions as A, type BrowserLoggerOption as B, type CheckoutInvoiceSnapshot as C, type ThemeToggleElementAttributes as D, type StoredThemeModelOptions as E, type ThemeModel as F, type ThemeModelOptions as G, type ReadThemePreferenceOptions as H, type ThemeControlTargets as I, type ThemeStorageOptions as J, type PaymentWizardControllerOptions as K, type PaymentWizardController as L, type PaymentWizardSelection as M, type PaymentWizardModel as N, type WizardRouteDisplay as O, type ParseOpenReceiveOptionalIntegerOptions as P, type PaymentWizardSelectionAction as Q, type ResolvedTheme as R, type SwapDisplayModel as S, type ThemePreference as T, type UnixSeconds as U, type BrowserLogContext as V, type WizardRouteAssetDisplay as W, type BrowserLogger as X, BrowserRequestError as Y, type CheckoutController as Z, type CheckoutControllerOptions as _, type PaymentMethod as a, type CheckoutStatusRefresh as a0, OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES as a1, OPENRECEIVE_CHECKOUT_DATA_SELECTORS as a2, OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES as a3, OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS as a4, OPENRECEIVE_CHECKOUT_ELEMENT_PARTS as a5, OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS as a6, OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME as a7, OPENRECEIVE_COPY_FEEDBACK_MS as a8, OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS as a9, escapeHtml as aA, formatAmountCaption as aB, formatDepositAmount as aC, formatFiatAmount as aD, formatMsats as aE, formatSwapLimit as aF, formatUnixTime as aG, openWallet as aH, prepareCheckout as aI, requestCheckout as aJ, type BrowserLogLevel as aK, type BrowserLogEntry as aL, type CopyInvoiceOptions as aM, type GuestCheckoutResumeController as aN, type GuestCheckoutResumeOptions as aO, type OpenWalletOptions as aP, type PrepareCheckoutOptions as aQ, type QrOptions as aR, type RequestCheckoutOptions as aS, type StatusInvoiceLike as aT, createGuestCheckoutResume as aU, createGuestOrderFetcher as aV, createLightningUri as aW, createQrPngDataUrl as aX, 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 WizardProviderDisplay as al, assertDisplayInvoice as am, copyInvoice as an, createCheckoutActionEvent as ao, createCheckoutController as ap, createCheckoutErrorEvent as aq, createCheckoutProviderCopyEvent as ar, createCheckoutStateEvent as as, createQrPayloadSvg as at, createQrSvg as au, createStatusFetcher as av, createThemeChangeEvent as aw, deriveCheckoutStateLabels as ax, deriveStatus as ay, enterCheckoutResumePath as az, type PaymentMethodOption as b, type TickingValueOptions as c, type TickingValueController as d, type TransientFeedbackOptions as e, type TransientFeedbackController as f, type SwapDepositRisk as g, type CheckoutInvoiceSwapSnapshot as h, type CheckoutState as i, type TransactionDetailsInput as j, type TransactionDetailRow as k, type CheckoutSnapshot as l, type CreateCheckoutStateOptions as m, type CheckoutStatusModelInput as n, type CheckoutStatusModel as o, type CheckoutPaymentMethod as p, type ThemeAttributeTarget as q, type CheckoutElementAttributes as r, type CheckoutElementAttributeOptions as s, type CheckoutElementEventHandlers as t, type CheckoutElementListeners as u, type CreateCheckoutShellOptions as v, type CheckoutShellElements as w, type CheckoutShellOptions as x, type CheckoutShellModel as y, type CreateOpenReceiveThemeToggleElementOptions 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, createGuestOrderFetcher 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, createQrSvgController as aA, createStatusFetcher as aB, createThemeChangeEvent as aC, deriveCheckoutStateLabels as aD, deriveStatus as aE, enterCheckoutResumePath as aF, escapeHtml as aG, formatAmountCaption as aH, formatDepositAmount as aI, formatFiatAmount as aJ, formatMsats as aK, formatSwapLimit as aL, formatUnixTime as aM, openWallet as aN, prepareCheckout as aO, requestCheckout as aP, type BrowserLogLevel as aQ, type BrowserLogEntry as aR, type CopyInvoiceOptions as aS, type GuestCheckoutResumeController as aT, type GuestCheckoutResumeOptions as aU, type OpenWalletOptions as aV, type PrepareCheckoutOptions as aW, type QrOptions as aX, type RequestCheckoutOptions as aY, type StatusInvoiceLike as aZ, createGuestCheckoutResume as a_, OPENRECEIVE_DEFAULT_PREFIX as aa, OPENRECEIVE_PAYMENT_WIZARD_ATTRIBUTES as ab, OPENRECEIVE_PAYMENT_WIZARD_SELECTORS as ac, OPENRECEIVE_PROVIDER_PREVIEW_LIMIT as ad, OPENRECEIVE_THEME_STORAGE_KEY as ae, OPENRECEIVE_THEME_TOGGLE_ELEMENT_ATTRIBUTES as af, OPENRECEIVE_THEME_TOGGLE_ELEMENT_EVENTS as ag, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PARTS as ah, OPENRECEIVE_THEME_TOGGLE_ELEMENT_PART_SELECTORS as ai, OPENRECEIVE_THEME_TOGGLE_ELEMENT_TAG_NAME as aj, type QrEncoder as ak, type QrSvgController as al, type QrSvgControllerOptions as am, type Status as an, type SwapCopyRow as ao, type SwapRefundStaging as ap, type WizardProviderDisplay as aq, assertDisplayInvoice as ar, copyInvoice as as, createCheckoutActionEvent as at, createCheckoutController as au, createCheckoutErrorEvent as av, createCheckoutProviderCopyEvent as aw, createCheckoutStateEvent as ax, createQrPayloadSvg as ay, createQrSvg as az, type PaymentMethodOption as b, createLightningUri as b0, createQrPngDataUrl as b1, 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 };