@openreceive/browser 0.4.9 → 0.4.11

package/dist/headless.d.ts

@@ -1,7 +1,7 @@
 import { AssetIndexEntry, PaymentWizardRoute } from '@openreceive/provider-data';
 export { PaymentWizardRoute, PaymentWizardRouteRequest, getPaymentWizardRoutes, loadPayTutorialImages, payTutorialImage } from '@openreceive/provider-data';
-import { P as PaymentIconId, a as ParseOpenReceiveOptionalIntegerOptions, b as PaymentMethod, R as ResolvedTheme, T as ThemePreference, c as PaymentMethodOption, d as TickingValueOptions, e as TickingValueController, f as TransientFeedbackOptions, g as TransientFeedbackController, C as CheckoutInvoiceSnapshot, U as UnixSeconds, S as SwapDisplayModel, h as CheckoutSnapshot, i as SwapDepositRisk, j as CheckoutState, k as TransactionDetailsInput, l as TransactionDetailRow, m as CreateCheckoutStateOptions, n as CheckoutStatusModelInput, o as CheckoutStatusModel, p as CheckoutPaymentMethod, B as BrowserLoggerOption, q as ThemeAttributeTarget, r as CheckoutElementAttributes, s as CheckoutElementAttributeOptions, t as CheckoutElementEventHandlers, u as CheckoutElementListeners, v as CreateCheckoutShellOptions, w as CheckoutShellElements, x as CheckoutShellOptions, y as CheckoutShellModel, z as CreateOpenReceiveThemeToggleElementOptions, A as ThemeToggleElementAttributeOptions, D as ThemeToggleElementAttributes, E as StoredThemeModelOptions, F as ThemeModel, G as ThemeModelOptions, H as ReadThemePreferenceOptions, I as ThemeControlTargets, J as ThemeStorageOptions, K as PaymentWizardControllerOptions, L as PaymentWizardController, M as PaymentWizardSelection, N as PaymentWizardModel, W as WizardRouteAssetDisplay, O as WizardRouteDisplay, Q as PaymentWizardSelectionAction } from './status-Doh8Wz4D.js';
-export { V as BrowserLogContext, X as BrowserLogger, Y as BrowserRequestError, Z as CheckoutController, _ as CheckoutControllerOptions, $ as CheckoutPhase, a0 as CheckoutShellRootAttributes, a1 as CheckoutStatusRefresh, a2 as OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES, a3 as OPENRECEIVE_CHECKOUT_DATA_SELECTORS, a4 as OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES, a5 as OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS, a6 as OPENRECEIVE_CHECKOUT_ELEMENT_PARTS, a7 as OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS, a8 as OPENRECEIVE_CHECKOUT_ELEMENT_SLOTS, a9 as OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME, aa as OPENRECEIVE_COPY_FEEDBACK_MS, ab as OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS, ac as OPENRECEIVE_DEFAULT_PREFIX, ad as OPENRECEIVE_PAYMENT_WIZARD_ATTRIBUTES, ae as OPENRECEIVE_PAYMENT_WIZARD_SELECTORS, af as OPENRECEIVE_PROVIDER_PREVIEW_LIMIT, ag as OPENRECEIVE_STYLE_ROOT_ATTRIBUTE, ah as OPENRECEIVE_STYLE_ROOT_SELECTOR, ai as OPENRECEIVE_THEME_STORAGE_KEY, aj as OPENRECEIVE_THEME_TOGGLE_ELEMENT_ATTRIBUTES, ak as OPENRECEIVE_THEME_TOGGLE_ELEMENT_EVENTS, al as OPENRECEIVE_THEME_TOGGLE_ELEMENT_PARTS, am as OPENRECEIVE_THEME_TOGGLE_ELEMENT_PART_SELECTORS, an as OPENRECEIVE_THEME_TOGGLE_ELEMENT_TAG_NAME, ao as QrEncoder, ap as QrSvgController, aq as QrSvgControllerOptions, ar as Status, as as SwapCopyRow, at as SwapRefundStaging, au as WizardProviderDisplay, av as assertDisplayInvoice, aw as copyInvoice, ax as createCheckoutActionEvent, ay as createCheckoutController, az as createCheckoutErrorEvent, aA as createCheckoutProviderCopyEvent, aB as createCheckoutStateEvent, aC as createQrPayloadSvg, aD as createQrSvg, aE as createQrSvgController, aF as createStatusFetcher, aG as createThemeChangeEvent, aH as currentCheckoutUrl, aI as deriveCheckoutStateLabels, aJ as deriveStatus, aK as enterCheckoutResumePath, aL as escapeHtml, aM as formatAmountCaption, aN as formatDepositAmount, aO as formatFiatAmount, aP as formatMsats, aQ as formatSwapLimit, aR as formatUnixTime, aS as openWallet, aT as paymentIconSvgs, aU as prepareCheckout, aV as requestCheckout } from './status-Doh8Wz4D.js';
+import { P as PaymentIconId, a as ParseOpenReceiveOptionalIntegerOptions, b as PaymentMethod, R as ResolvedTheme, T as ThemePreference, c as PaymentMethodOption, d as TickingValueOptions, e as TickingValueController, f as TransientFeedbackOptions, g as TransientFeedbackController, C as CheckoutInvoiceSnapshot, U as UnixSeconds, S as SwapDisplayModel, h as CheckoutSnapshot, i as SwapDepositRisk, j as CheckoutState, k as TransactionDetailsInput, l as TransactionDetailRow, m as CreateCheckoutStateOptions, n as CheckoutStatusModelInput, o as CheckoutStatusModel, p as CheckoutPaymentMethod, B as BrowserLoggerOption, q as ThemeAttributeTarget, r as CheckoutElementAttributes, s as CheckoutElementAttributeOptions, t as CheckoutElementEventHandlers, u as CheckoutElementListeners, v as CreateCheckoutShellOptions, w as CheckoutShellElements, x as CheckoutShellOptions, y as CheckoutShellModel, z as CreateOpenReceiveThemeToggleElementOptions, A as ThemeToggleElementAttributeOptions, D as ThemeToggleElementAttributes, E as StoredThemeModelOptions, F as ThemeModel, G as ThemeModelOptions, H as ReadThemePreferenceOptions, I as ThemeControlTargets, J as ThemeStorageOptions, K as PaymentWizardControllerOptions, L as PaymentWizardController, M as PaymentWizardSelection, N as PaymentWizardModel, W as WizardRouteAssetDisplay, O as WizardRouteDisplay, Q as PaymentWizardSelectionAction } from './status-hEzap3jk.js';
+export { V as BrowserLogContext, X as BrowserLogger, Y as BrowserRequestError, Z as CheckoutController, _ as CheckoutControllerOptions, $ as CheckoutPhase, a0 as CheckoutShellRootAttributes, a1 as CheckoutStatusRefresh, a2 as OPENRECEIVE_CHECKOUT_DATA_ATTRIBUTES, a3 as OPENRECEIVE_CHECKOUT_DATA_SELECTORS, a4 as OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES, a5 as OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS, a6 as OPENRECEIVE_CHECKOUT_ELEMENT_PARTS, a7 as OPENRECEIVE_CHECKOUT_ELEMENT_PART_SELECTORS, a8 as OPENRECEIVE_CHECKOUT_ELEMENT_SLOTS, a9 as OPENRECEIVE_CHECKOUT_ELEMENT_TAG_NAME, aa as OPENRECEIVE_COPY_FEEDBACK_MS, ab as OPENRECEIVE_DEFAULT_POLL_INTERVAL_MS, ac as OPENRECEIVE_DEFAULT_PREFIX, ad as OPENRECEIVE_PAYMENT_WIZARD_ATTRIBUTES, ae as OPENRECEIVE_PAYMENT_WIZARD_SELECTORS, af as OPENRECEIVE_PROVIDER_PREVIEW_LIMIT, ag as OPENRECEIVE_STYLE_ROOT_ATTRIBUTE, ah as OPENRECEIVE_STYLE_ROOT_SELECTOR, ai as OPENRECEIVE_THEME_STORAGE_KEY, aj as OPENRECEIVE_THEME_TOGGLE_ELEMENT_ATTRIBUTES, ak as OPENRECEIVE_THEME_TOGGLE_ELEMENT_EVENTS, al as OPENRECEIVE_THEME_TOGGLE_ELEMENT_PARTS, am as OPENRECEIVE_THEME_TOGGLE_ELEMENT_PART_SELECTORS, an as OPENRECEIVE_THEME_TOGGLE_ELEMENT_TAG_NAME, ao as QrEncoder, ap as QrSvgController, aq as QrSvgControllerOptions, ar as Status, as as SwapCopyRow, at as SwapRefundStaging, au as WizardProviderDisplay, av as assertDisplayInvoice, aw as copyInvoice, ax as createCheckoutActionEvent, ay as createCheckoutController, az as createCheckoutErrorEvent, aA as createCheckoutProviderCopyEvent, aB as createCheckoutStateEvent, aC as createQrPayloadSvg, aD as createQrSvg, aE as createQrSvgController, aF as createStatusFetcher, aG as createThemeChangeEvent, aH as currentCheckoutUrl, aI as deriveCheckoutStateLabels, aJ as deriveStatus, aK as enterCheckoutResumePath, aL as escapeHtml, aM as formatAmountCaption, aN as formatDepositAmount, aO as formatFiatAmount, aP as formatMsats, aQ as formatSwapLimit, aR as formatUnixTime, aS as openWallet, aT as paymentIconSvgs, aU as prepareCheckout, aV as requestCheckout } from './status-hEzap3jk.js';
 import '@openreceive/core';
 
 /** Each packaged payment icon as a `data:image/svg+xml` URI, keyed by id. */
@@ -747,13 +747,15 @@ interface CheckoutSessionOptions {
     snapshot(): CheckoutSnapshot | undefined;
     /** The order being paid, read at call time (the element's is an attribute). */
     reference(): string | undefined;
+    /** Endpoint is part of checkout identity; trailing slashes are equivalent. */
+    prefix?(): string | undefined;
     /**
      * Mint a Lightning invoice for this reference (POST `${prefix}/checkouts`).
      * The host closes over its own prefix, metadata and fetch. Answer `undefined`
      * to say "this host cannot mint" — React's payment wizard is such a host: it
      * asks its parent for Lightning through `onRequestLightning` instead.
      */
-    requestCheckout?(reference: string): Promise<CheckoutSnapshot> | undefined;
+    requestCheckout?(reference: string, signal?: AbortSignal): Promise<CheckoutSnapshot> | undefined;
     /** Publish a snapshot that now carries the Lightning attempt. */
     onSnapshot?(snapshot: CheckoutSnapshot): void;
     /**
@@ -785,6 +787,14 @@ interface CheckoutSession {
      * carries the accepted range the host renders in its unavailable panel.
      */
     readonly swapQuotes: Readonly<Record<string, CheckoutPaymentMethod>>;
+    /** Invalidate every outstanding action when identity changes. */
+    syncIdentity(): void;
+    reset(): void;
+    dispose(): void;
+    capture(): {
+        readonly signal: AbortSignal;
+        isCurrent(): boolean;
+    };
     ensureLightning(): Promise<void>;
     /**
      * Quote the pay-in asset, then start the swap when the quote confirms the
@@ -825,6 +835,7 @@ declare function createCheckoutShell(snapshot: CheckoutSnapshot, options?: Creat
  * URL input — no call in this module takes a route of its own.
  */
 interface SwapRequestOptions {
+    readonly signal?: AbortSignal;
     readonly fetch: typeof globalThis.fetch;
     readonly prefix: string;
     readonly logger?: BrowserLoggerOption;

package/dist/headless.js

@@ -119,7 +119,7 @@ import {
   swapOptionLimitSentence,
   swapPickerKey,
   updatePaymentWizardSelection
-} from "./chunk-CPVYEWVM.js";
+} from "./chunk-5F7F2ZAM.js";
 
 // src/headless.ts
 import {
@@ -177,7 +177,43 @@ function createCheckoutSession(options) {
   let mintingLightning = false;
   let startingSwapAsset = null;
   let swapQuotes = {};
+  let generation = 0;
+  let abort = new AbortController();
+  const identityKey = () => JSON.stringify([
+    options.reference(),
+    (options.prefix?.() ?? options.swap?.prefix() ?? "").replace(/\/+$/, "")
+  ]);
+  let identity = identityKey();
+  function invalidateActions() {
+    abort.abort();
+    abort = new AbortController();
+    generation += 1;
+    mintingLightning = false;
+    startingSwapAsset = null;
+  }
+  function reset() {
+    invalidateActions();
+    identity = identityKey();
+    wizardError = void 0;
+    swapStartError = void 0;
+    lightningRequested = false;
+    mintingLightning = false;
+    startingSwapAsset = null;
+    swapQuotes = {};
+  }
+  function syncIdentity() {
+    if (identityKey() !== identity) reset();
+  }
+  function capture() {
+    syncIdentity();
+    const captured = generation;
+    return {
+      signal: abort.signal,
+      isCurrent: () => captured === generation && identityKey() === identity
+    };
+  }
   async function ensureLightning() {
+    const action = capture();
     if (mintingLightning) return;
     const reference = options.reference();
     if (reference === void 0 || reference.length === 0) return;
@@ -195,20 +231,25 @@ function createCheckoutSession(options) {
     wizardError = void 0;
     options.onChange();
     try {
-      const pending = options.requestCheckout?.(reference);
+      const pending = options.requestCheckout?.(reference, action.signal);
       if (pending === void 0) return;
       const checkout = await pending;
+      if (!action.isCurrent()) return;
       lightningRequested = true;
       options.onSnapshot?.(mergeMintedCheckout(checkout, options.snapshot()));
     } catch (error) {
+      if (!action.isCurrent()) return;
       wizardError = payerFacingMessage(error, MINT_FAILED);
       options.onError(error);
     } finally {
-      mintingLightning = false;
-      options.onChange();
+      if (action.isCurrent()) {
+        mintingLightning = false;
+        options.onChange();
+      }
     }
   }
   async function startSwap(payInAsset) {
+    const action = capture();
     if (startingSwapAsset !== null) return;
     const swap = options.swap;
     if (swap === void 0) {
@@ -239,9 +280,18 @@ function createCheckoutSession(options) {
     swapStartError = void 0;
     options.onChange();
     try {
-      const quote = await quoteSwapAsset(payInAsset, prefix, fetcher, reference, csrfHeader);
+      const quote = await quoteSwapAsset(
+        payInAsset,
+        prefix,
+        fetcher,
+        reference,
+        csrfHeader,
+        action
+      );
+      if (!action.isCurrent()) return;
       if (quote !== void 0 && quote.available === false) return;
       const started = await startSwapRequest({
+        signal: action.signal,
         fetch: fetcher,
         prefix,
         ...csrfHeader === void 0 ? {} : { csrfHeader },
@@ -249,12 +299,14 @@ function createCheckoutSession(options) {
         payInAsset,
         ...options.logger === void 0 ? {} : { logger: options.logger }
       });
+      if (!action.isCurrent()) return;
       selection.setStarted(started);
       selection.setDismissedInvoiceId(null);
       swap.onStarted?.(started);
       selection.setSelectedAsset(payInAsset);
       options.onChange();
     } catch (error) {
+      if (!action.isCurrent()) return;
       const landed = selection.started();
       if (landed?.swap?.pay_in_asset === payInAsset && landed.invoice_id !== selection.dismissedInvoiceId()) {
         selection.setSelectedAsset(payInAsset);
@@ -264,17 +316,22 @@ function createCheckoutSession(options) {
       selection.setSelectedAsset(payInAsset);
       failSwapStart(error);
     } finally {
-      startingSwapAsset = null;
+      if (action.isCurrent()) {
+        startingSwapAsset = null;
+        options.onChange();
+      }
     }
   }
-  async function quoteSwapAsset(payInAsset, prefix, fetcher, reference, csrfHeader) {
+  async function quoteSwapAsset(payInAsset, prefix, fetcher, reference, csrfHeader, action) {
     const body = await postJson({
+      signal: action.signal,
       fetch: fetcher,
       prefix,
       ...csrfHeader === void 0 ? {} : { csrfHeader },
       ...options.logger === void 0 ? {} : { logger: options.logger },
       body: { reference, action: "swap_quote", pay_in_asset: payInAsset }
     });
+    if (!action.isCurrent()) return void 0;
     const quote = normalizeSwapQuote(body);
     if (quote === void 0) return void 0;
     swapQuotes = { ...swapQuotes, [quote.pay_in_asset]: quote };
@@ -304,12 +361,17 @@ function createCheckoutSession(options) {
     get swapQuotes() {
       return swapQuotes;
     },
+    syncIdentity,
+    reset,
+    dispose: reset,
+    capture,
     ensureLightning,
     startSwap,
     resetLightningRequest() {
-      lightningRequested = false;
+      reset();
     },
     clearSwapStartError() {
+      invalidateActions();
       swapStartError = void 0;
     }
   };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { aW as BrowserLogLevel } from './status-Doh8Wz4D.js';
-export { aX as BrowserLogEntry, X as BrowserLogger, B as BrowserLoggerOption, Y as BrowserRequestError, Z as CheckoutController, _ as CheckoutControllerOptions, h as CheckoutSnapshot, j as CheckoutState, aY as CopyInvoiceOptions, aZ as GuestCheckoutResumeController, a_ as GuestCheckoutResumeOptions, a$ as OpenWalletOptions, b0 as PrepareCheckoutOptions, b1 as QrOptions, b2 as RequestCheckoutOptions, ar as Status, b3 as StatusInvoiceLike, U as UnixSeconds, aw as copyInvoice, ay as createCheckoutController, b4 as createGuestCheckoutResume, b5 as createGuestOrderFetcher, b6 as createLightningUri, b7 as createQrPngDataUrl, aD as createQrSvg, aJ as deriveStatus, aK as enterCheckoutResumePath, aS as openWallet, aU as prepareCheckout, aV as requestCheckout } from './status-Doh8Wz4D.js';
+import { aW as BrowserLogLevel } from './status-hEzap3jk.js';
+export { aX as BrowserLogEntry, X as BrowserLogger, B as BrowserLoggerOption, Y as BrowserRequestError, Z as CheckoutController, _ as CheckoutControllerOptions, h as CheckoutSnapshot, j as CheckoutState, aY as CopyInvoiceOptions, aZ as GuestCheckoutResumeController, a_ as GuestCheckoutResumeOptions, a$ as OpenWalletOptions, b0 as PrepareCheckoutOptions, b1 as QrOptions, b2 as RequestCheckoutOptions, ar as Status, b3 as StatusInvoiceLike, U as UnixSeconds, aw as copyInvoice, ay as createCheckoutController, b4 as createGuestCheckoutResume, b5 as createGuestOrderFetcher, b6 as createLightningUri, b7 as createQrPngDataUrl, aD as createQrSvg, aJ as deriveStatus, aK as enterCheckoutResumePath, aS as openWallet, aU as prepareCheckout, aV as requestCheckout } from './status-hEzap3jk.js';
 import '@openreceive/provider-data';
 import '@openreceive/core';
 

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   openWallet,
   prepareCheckout,
   requestCheckout
-} from "./chunk-CPVYEWVM.js";
+} from "./chunk-5F7F2ZAM.js";
 export {
   BrowserRequestError,
   copyInvoice,

package/dist/{status-Doh8Wz4D.d.ts → status-hEzap3jk.d.ts}

@@ -431,14 +431,17 @@ interface CheckoutInvoiceSwapSnapshot {
 }
 /**
  * Formatted fee breakout for the deposit panel, explaining why the payer sends more
- * than the cart total. All figures are display-ready fiat strings.
+ * than the cart total. All figures are display-ready strings. `cartTotal` is
+ * always fiat; `youSend` and `fee` are fiat for a floating asset and token
+ * amounts ("50.05 USDC") for a stablecoin pegged to the fee currency, where a
+ * fiat valuation would read as the deposit amount with a typo.
  */
 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". */
+    /** What the payer sends: its fiat value ("$10.59") or, for a pegged stablecoin, the deposit amount itself ("10.59 USDC"). */
     readonly youSend: string;
-    /** The swap fee absorbed by the payer (exchange spread + network fees), e.g. "$0.59". */
+    /** The swap fee absorbed by the payer (exchange spread + network fees), e.g. "$0.59" or "0.59 USDC". */
     readonly fee: string;
     /** The fee as a percentage of the cart total, e.g. "5.9%", when computable. */
     readonly feePercent?: string;
@@ -817,8 +820,9 @@ interface RequestCheckoutOptions extends 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" | "csrfHeader">;
+type PrepareCheckoutOptions = Pick<RequestCheckoutBaseOptions, "prefix" | "reference" | "fetch" | "headers" | "csrfHeader" | "signal">;
 interface RequestCheckoutBaseOptions {
+    readonly signal?: AbortSignal;
     /**
      * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openreceive/browser",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "Browser helpers and a headless UI engine for Bitcoin Lightning checkout and optional USDT, USDC, SOL and ETH swaps.",
   "keywords": [
     "bitcoin",
@@ -30,8 +30,8 @@
     "./styles.css": "./dist/styles.css"
   },
   "dependencies": {
-    "@openreceive/core": "0.4.9",
-    "@openreceive/provider-data": "0.4.9",
+    "@openreceive/core": "0.4.11",
+    "@openreceive/provider-data": "0.4.11",
     "qrcode": "^1.5.4"
   },
   "devDependencies": {

package/skills/debug-openreceive-payment/SKILL.md

@@ -70,6 +70,14 @@ same diagnostics redacted, always exit 0 — safe to share.
 - Refunds exist only for swap deposits from `refund_required`. There is **no
   Lightning refund** — the wallet cannot spend. Do not chase one.
   https://openreceive.org/guides/swap-refunds.md
+- "Payer reports two different amounts on a stablecoin checkout" (50.05 or
+  50.03?): the deposit amount is a token quantity, `fee.pay_in_fiat` is its
+  fiat valuation. Only `swap.deposit_amount` is an instruction. From 0.4.10 the
+  packaged checkout renders a USD stablecoin's breakdown in the token and never
+  shows `pay_in_fiat`; on an older bundle, upgrade `@openreceive/*`. To verify,
+  read the row's `deposit_amount` and `fee` and confirm the UI shows only the
+  deposit amount. A custom UI must call `createSwapFeeBreakdown(fee, swap)`
+  with the swap, not the fee alone.
 
 ## 6. Checkout UI shows nothing
 

package/skills/integrate-openreceive/SKILL.md

@@ -86,6 +86,17 @@ state; do not retry-loop it, and do not build an idempotency store around it —
 that serialization is the library's job. (A hook failure while persisting an
 attempt is a **503 retryable**, deliberately distinct.)
 
+## Amounts on the deposit panel
+
+`swap.deposit_amount` is the ONLY amount a payer is ever told to send, in the
+pay-in token. `swap.fee.pay_in_fiat` / `payout_fiat` are fiat valuations that
+explain the spread (why the deposit exceeds the cart total); they are not
+instructions. For a stablecoin pegged to the fee currency (USDT, USDC) the
+packaged checkout expresses the breakdown in the token and never renders
+`pay_in_fiat` — "$50.03" under "50.05 USDC" reads as the same number with a
+typo. A custom UI gets the same rule from `createSwapFeeBreakdown(fee, swap)`;
+pass the swap, not just the fee.
+
 ## Secrets
 
 `NWC_URI` and `LSC_URI_*` are server-only. Never put them in browser code,

package/skills/integrate-openreceive/references/btcpay.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Connect a BTCPay Server store to a receive-only NWC wallet with the OpenReceive
 plugin, and optionally let payers pay BTCPay invoices with USDT, USDC, ETH or
@@ -32,7 +32,7 @@ refund path on the same checkout screen.
 
 ## Step 0 — check the deployment before you change anything
 
-1. Confirm the BTCPay Server version is 2.4.2 or later (Server Settings →
+1. Confirm the BTCPay Server version is 2.4.4 or later (Server Settings →
    About, or `GET /api/v1/server/info`). The plugin declares that minimum and
    BTCPay refuses to load it below.
 2. Check whether the plugin is installed (Server Settings → Plugins, or the
@@ -119,6 +119,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the plugin itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -128,7 +130,7 @@ passes. The page it comes from is https://openreceive.org/guides/quickstart-btcp
 
 ## BTCPay Server quickstart
 
-Requires BTCPay Server ≥ 2.4.2.
+Requires BTCPay Server ≥ 2.4.4.
 
 The OpenReceive plugin makes a receive-only NWC wallet the Lightning node of a
 BTCPay store. BTCPay mints every Lightning invoice in that wallet and records
@@ -143,7 +145,7 @@ invoices, checkout, webhooks and Greenfield API are the host.
 
 ### 1. Prerequisites
 
-- A BTCPay Server, version 2.4.2 or later, on any network (mainnet, testnet,
+- A BTCPay Server, version 2.4.4 or later, on any network (mainnet, testnet,
   signet, regtest). The wallet must be on the same network.
 - A receive-only NWC code for the wallet you want to receive into
   ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
@@ -157,9 +159,9 @@ invoices, checkout, webhooks and Greenfield API are the host.
 
 In BTCPay, open **Server Settings → Plugins**, search the plugin directory
 for **OpenReceive**, click **Install**, and restart BTCPay when prompted.
-BTCPay creates the plugin's one table (`openreceive_swaps`, schema
-`BTCPayServer.Plugins.OpenReceive`) in its own Postgres at startup; nothing
-else is created.
+BTCPay creates the plugin's two tables (`openreceive_invoices` and
+`openreceive_swaps`, schema `BTCPayServer.Plugins.OpenReceive`) in its own
+Postgres at startup; nothing else is created.
 
 To build the plugin from source instead, follow
 [the .NET workspace README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/README.md).

package/skills/integrate-openreceive/references/django.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Django project — the app you are already working in. You
 do not need a copy of the OpenReceive source: the Python package is on PyPI
@@ -130,7 +130,7 @@ itself, and they hold for every integration.
   a placeholder that allows everything (`manage.py check` warns
   `openreceive.W002` while it is set) — replace it with this app's real
   ownership check, same as `on_paid`.
-- `on_paid` must be idempotent. It runs once per `reference` — your order
+- `on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -231,6 +231,13 @@ built on `@openreceive/browser/headless`. Read that before writing components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -300,6 +307,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -473,7 +482,7 @@ The host class needs three things: authorization, the trusted price, and
 fulfillment. All three receive the `reference` — a string you choose, and the
 fulfillment identity: your order id, one per thing you fulfill, created before
 checkout, kept across retries, never reused. OpenReceive never looks inside
-it, but `on_paid` runs once per reference, a new checkout under a reference
+it, but `on_paid` commits fulfillment once per reference, a new checkout under a reference
 that already settled is refused with 409, and a fresh id per page load lets
 one order be paid twice.
 

package/skills/integrate-openreceive/references/fastapi.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a FastAPI application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the engine is on PyPI
@@ -116,7 +116,7 @@ itself, and they hold for every integration.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read the Starlette request's session, cookie or
   auth dependency; never trust a body field.
-- `on_paid` must be idempotent. It runs once per `reference` — your order id, one
+- `on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -228,6 +228,13 @@ components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -294,6 +301,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -468,7 +477,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `on_paid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -517,7 +526,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A page without a bundler renders the same checkout as a custom element:
 `<openreceive-checkout reference="…" prefix="/openreceive">` from

package/skills/integrate-openreceive/references/fastify.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Fastify)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Fastify application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the packages are on npm, and
@@ -107,7 +107,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -211,6 +211,13 @@ components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -277,6 +284,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -470,7 +479,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -519,7 +528,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A runnable illustration of this boundary — not a template to copy models from —
 is Buy a Button

package/skills/integrate-openreceive/references/laravel.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Laravel application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the package is on Packagist
@@ -121,7 +121,7 @@ itself, and they hold for every integration.
   scaffolds `use AllowAllAuthorize;`, a placeholder trait that allows
   everything (the engine warns at boot while it is there) — replace it with
   this app's real ownership check, same as `onPaid`.
-- `onPaid` must be idempotent. It runs once per `reference` — your order
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -216,6 +216,13 @@ built on `@openreceive/browser/headless`. Read that before writing components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -284,6 +291,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -449,7 +458,7 @@ variable as set/unset only.
 price, and fulfillment. All three receive the `reference` — a string you
 choose, and the fulfillment identity: your order id, one per thing you
 fulfill, created before checkout, kept across retries, never reused.
-OpenReceive never looks inside it, but `onPaid` runs once per reference, a new
+OpenReceive never looks inside it, but `onPaid` commits fulfillment once per reference, a new
 checkout under a reference that already settled is refused with 409, and a
 fresh id per page load lets one order be paid twice.
 

package/skills/integrate-openreceive/references/next.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.9.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Next.js App Router application — the app you are already
 working in. You do not need a copy of the OpenReceive source: the packages are
@@ -109,7 +109,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -217,6 +217,13 @@ components.
 - `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
   and the bare amount each get a copy row. Render `swap.networkWarning*` as
   the model gives it.
+- `swap.deposit_amount` is the only amount a payer is told to send. Never put
+  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
+  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
+  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
+  (`payout_fiat`); express "you send" and the fee in the token. Use
+  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
+  it applies this for you; SOL and ETH keep a fiat breakdown.
 - `createCheckoutSession` owns mint and swap start. To start swaps, pass its
   `swap` option (`selection`, `prefix`, `fetch`) together. Without it
   `startSwap` reports through `onError`.
@@ -283,6 +290,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -489,7 +498,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -569,7 +578,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A runnable illustration of this boundary — not a template to copy models from —
 is Buy a Button