@openreceive/elements 0.4.10 → 0.4.12

package/dist/{chunk-OMG254JS.js → chunk-DQ6FMWVX.js}

@@ -244,11 +244,13 @@ function createElementCheckoutSession(host) {
   const session = createCheckoutSession({
     snapshot: () => host.latestCheckoutSnapshot(),
     reference: currentReference,
-    requestCheckout: (reference) => {
+    prefix: currentPrefix,
+    requestCheckout: (reference, signal) => {
       const metadata = host.createMetadata();
       const csrfHeader = currentCsrfHeader();
       return requestCheckout({
         prefix: currentPrefix(),
+        signal,
         reference,
         ...metadata === void 0 ? {} : { metadata },
         ...csrfHeader === void 0 ? {} : { csrfHeader },
@@ -290,17 +292,21 @@ function createElementCheckoutSession(host) {
     creating = true;
     createdKey = key;
     session.resetLightningRequest();
+    const action = session.capture();
     try {
       createError = void 0;
       host.syncResumePath(reference);
       const prepared = await prepareCheckout({
+        signal: action.signal,
         prefix,
         reference,
         ...csrfHeader === void 0 ? {} : { csrfHeader },
         fetch: globalThis.fetch
       });
+      if (!action.isCurrent()) return;
       const resumeHash = host.resumePaymentHash();
       const checkout = resumeHash === void 0 ? prepared : await resumeSwapAttempt({
+        signal: action.signal,
         fetch: globalThis.fetch,
         prefix,
         ...csrfHeader === void 0 ? {} : { csrfHeader },
@@ -308,7 +314,7 @@ function createElementCheckoutSession(host) {
         paymentHash: resumeHash,
         snapshot: prepared
       });
-      if (currentCreateKey() !== key) return;
+      if (!action.isCurrent()) return;
       if (checkout.active?.swap !== void 0) {
         host.swapSelection.setSelectedAsset(checkout.active.swap.pay_in_asset);
         host.swapSelection.setDismissedInvoiceId(null);
@@ -323,15 +329,17 @@ function createElementCheckoutSession(host) {
       host.render();
       host.startCheckoutController();
     } catch (error) {
-      if (currentCreateKey() !== key) return;
+      if (!action.isCurrent()) return;
       createError = error instanceof Error && error.message.length > 0 ? error.message : "Could not start checkout.";
       host.dispatchError(error);
       host.render();
     } finally {
-      creating = false;
-      const current = currentCreateKey();
-      if (host.element.isConnected && current !== void 0 && current !== key && host.isCreateMode()) {
-        void createCheckout();
+      if (action.isCurrent()) {
+        creating = false;
+        const current = currentCreateKey();
+        if (host.element.isConnected && current !== void 0 && current !== key && host.isCreateMode()) {
+          void createCheckout();
+        }
       }
     }
   }
@@ -370,9 +378,19 @@ function createElementCheckoutSession(host) {
     retryCreateCheckout,
     ensureLightning: () => session.ensureLightning(),
     startSwap: (payInAsset) => session.startSwap(payInAsset),
+    clearSwapStartError: () => session.clearSwapStartError(),
     applyOwnAttributes,
     writeOwnAttributes,
+    capture: () => session.capture(),
+    dispose() {
+      session.dispose();
+      if (creating) createdKey = void 0;
+      creating = false;
+    },
     forgetCreateKey() {
+      session.reset();
+      creating = false;
+      createError = void 0;
       createdKey = void 0;
     }
   };
@@ -1471,7 +1489,7 @@ function renderCheckoutHtml(view) {
   const settled = statusLabel === "settled";
   const swapFocused = (view.wizard?.selectedSwapAsset ?? null) !== null;
   const methodGridShowing = view.payment_wizard !== false && view.wizard?.selectedMethod == null && !swapFocused;
-  const hideLightning = !settled && (view.lightningRequested === false || swapFocused && !expired || methodGridShowing && !expired);
+  const hideLightning = !settled && (view.lightningRequested === false || swapFocused || methodGridShowing && !expired);
   const wizard = expired && !swapFocused || settled || view.payment_wizard === false ? "" : renderPaymentWizardHtml(view.wizard);
   const copyButton = `<button part="${OPENRECEIVE_CHECKOUT_ELEMENT_PARTS.copy}" class="${orClasses6.btn}" type="button">${COPY_INVOICE_ICON}<span ${OPENRECEIVE_PAYMENT_WIZARD_ATTRIBUTES6.swapCopyLabel}>${escapeHtml7(checkoutLabels6.copyInvoice)}</span></button>`;
   const decodeInvoice = view.invoice.trim() !== "" ? view.invoice : typeof view.wizard?.lightningInvoice === "string" && view.wizard.lightningInvoice.trim() !== "" ? view.wizard.lightningInvoice : void 0;
@@ -1721,8 +1739,12 @@ function defineElements(options = {}) {
       this.startCheckoutController();
     }
     attributeChangedCallback(name, oldValue, newValue) {
-      if (!this.isConnected || this.session.applyingOwnAttributes) return;
+      if (this.session.applyingOwnAttributes) return;
+      const identityChanged = name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.reference || name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.prefix;
+      if (!this.isConnected && !identityChanged) return;
       if (oldValue === newValue) return;
+      if (name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.prefix && oldValue?.replace(/\/+$/, "") === newValue?.replace(/\/+$/, ""))
+        return;
       const displayOnly = name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.theme || name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.syncUrl || name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.resumePathPrefix || name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.routeReference || name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.resumable || name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.decodeLinkUrl;
       if (displayOnly) {
         this.render();
@@ -1738,8 +1760,40 @@ function defineElements(options = {}) {
       }
       const createInputChanged = name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.reference || name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.prefix || name === OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.invoice;
       if (createInputChanged) {
+        const managed = this.latestCheckoutSnapshot !== void 0;
+        this.stopCheckoutController();
         this.session.forgetCreateKey();
+        this.latestCheckoutSnapshot = void 0;
+        this.lastCheckoutState = void 0;
+        this.lastSnapshotDisplayKey = void 0;
+        this.startedSwapInvoice = void 0;
+        this.dismissedSwapInvoiceId = null;
+        this.selectedSwapAsset = null;
+        this.selectedPickerKey = null;
+        this.selectedSwapAssetByGroup = {};
+        this.selection = createPaymentWizardSelection();
+        this.swapOptions = [];
+        this.swapOptionsLoaded = false;
+        this.clearRefundAddressDraft();
+        if (managed && name !== OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3.invoice) {
+          this.session.writeOwnAttributes(() => {
+            for (const key of [
+              "invoice",
+              "invoiceId",
+              "paymentHash",
+              "rail",
+              "amountMsats",
+              "fiatCurrency",
+              "fiatValue",
+              "status",
+              "expiresAt"
+            ]) {
+              this.removeAttribute(OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES3[key]);
+            }
+          });
+        }
       }
+      if (!this.isConnected) return;
       if (this.isCreateMode()) {
         this.render();
         this.syncThemeAncestorObserver();
@@ -1753,6 +1807,7 @@ function defineElements(options = {}) {
       this.startCheckoutController();
     }
     disconnectedCallback() {
+      this.session.dispose();
       this.stopCheckoutController();
       this.stopThemeAncestorObserver();
     }
@@ -2219,6 +2274,7 @@ function defineElements(options = {}) {
         button.addEventListener("click", () => {
           const target = button.getAttribute(OPENRECEIVE_PAYMENT_WIZARD_ATTRIBUTES7.breadcrumb);
           if (target === "swap-asset") {
+            this.session.clearSwapStartError();
             this.selectedSwapAsset = null;
             this.selectedPickerKey = null;
             this.selectedSwapAssetByGroup = {};
@@ -2279,6 +2335,7 @@ function defineElements(options = {}) {
       });
       root.querySelector(OPENRECEIVE_PAYMENT_WIZARD_SELECTORS3.swapBack)?.addEventListener("click", () => {
         const current = this.currentSwapInvoice();
+        this.session.clearSwapStartError();
         this.dismissedSwapInvoiceId = current?.invoice_id ?? null;
         this.selectedSwapAsset = null;
         this.selectedPickerKey = null;
@@ -2426,12 +2483,15 @@ function defineElements(options = {}) {
     async refundSwap(attemptId, refundAddress, confirm) {
       const controller = this.controller;
       if (controller === void 0) return;
+      const action = this.session.capture();
       try {
-        this.startedSwapInvoice = confirm ? await controller.confirmSwapRefund({ attemptId, refundAddress }) : await controller.stageSwapRefund({ attemptId, refundAddress });
+        const invoice = confirm ? await controller.confirmSwapRefund({ attemptId, refundAddress }) : await controller.stageSwapRefund({ attemptId, refundAddress });
+        if (!action.isCurrent() || this.controller !== controller) return;
+        this.startedSwapInvoice = invoice;
         this.dismissedSwapInvoiceId = null;
         this.render();
       } catch (error) {
-        this.dispatchError(error);
+        if (action.isCurrent() && this.controller === controller) this.dispatchError(error);
       }
     }
     currentSwapInvoice() {

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   renderCheckoutHtml,
   renderThemeToggleHtml,
   renderTransactionDetailsHtml
-} from "./chunk-OMG254JS.js";
+} from "./chunk-DQ6FMWVX.js";
 export {
   OPENRECEIVE_CHECKOUT_ELEMENT_ATTRIBUTES,
   OPENRECEIVE_CHECKOUT_ELEMENT_EVENTS,

package/dist/wrapper-shared.js

@@ -1,6 +1,6 @@
 import {
   defineElements
-} from "./chunk-OMG254JS.js";
+} from "./chunk-DQ6FMWVX.js";
 
 // src/wrapper-shared.ts
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openreceive/elements",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "Bitcoin Lightning checkout for any website using custom elements, with optional USDT, USDC, SOL and ETH swaps.",
   "keywords": [
     "bitcoin",
@@ -21,7 +21,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@openreceive/browser": "0.4.10"
+    "@openreceive/browser": "0.4.12"
   },
   "exports": {
     ".": {

package/skills/integrate-openreceive/SKILL.md

@@ -34,9 +34,10 @@ code** (`NWC_URI`).
    - BTCPay Server: [references/btcpay.md](references/btcpay.md) — a plugin,
      configured in BTCPay's store UI or Greenfield API; no application code,
      no npm packages, no gem. The rest of this file is about the library.
-3. Follow its **Step 0** first: confirm `NWC_URI` is set in the server
-   environment before writing code. Never print the value; never invent a
-   placeholder.
+3. Follow its **Step 0** first: before writing code or searching the machine,
+   ask the user for the receive-only NWC code (then the swap URI), one question
+   per message, and store each pasted code in the project's env file yourself.
+   Never print the value; never invent a placeholder.
 
 Install, per adapter — Express: `npm install @openreceive/express @openreceive/react`;
 Fastify: `npm install @openreceive/fastify @openreceive/react`; Next.js:

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.12.
 
 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
@@ -35,10 +35,12 @@ refund path on the same checkout screen.
 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
-   store navigation shows an "OpenReceive" entry). If not, install it from the
-   BTCPay plugin directory (Server Settings → Plugins, search "OpenReceive"),
-   as the quickstart says; do not invent an installer command.
+2. Check whether the plugin is installed (the Plugins menu — the plug icon in
+   the top-right corner — under Installed Plugins, or the store navigation
+   shows an "OpenReceive" entry). If not, install it from the BTCPay plugin
+   directory (the same Plugins menu → Plugin Directory, search "openreceive",
+   then Install and Restart now), as the quickstart says; do not invent an
+   installer command.
 3. Check whether the store already has an OpenReceive connection:
    `GET /api/v1/stores/{storeId}/openreceive/settings` returns
    `lightningNodeIsOpenReceive`. If true, the wallet step is done — go to
@@ -119,6 +121,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
@@ -131,15 +135,15 @@ passes. The page it comes from is https://openreceive.org/guides/quickstart-btcp
 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
-payments through its own settlement machinery. Optionally, payers can pay a
-BTCPay invoice with USDT, USDC, ETH or SOL through a Lightning Swap Connect
-provider; the swap settles into the same wallet. The store's internal node is
+BTCPay store. BTCPay creates every Lightning invoice in that wallet. It records
+payments the same way it records any other payment. You can also let payers pay
+a BTCPay invoice with USDT, USDC, ETH or SOL through a Lightning Swap Connect
+provider. The swap pays into the same wallet. The store's internal node is
 never used.
 
 This is not the Node or Rails library. There are no hooks, no
-`openreceive_payments` table and no OpenReceive HTTP routes: BTCPay's
-invoices, checkout, webhooks and Greenfield API are the host.
+`openreceive_payments` table and no OpenReceive HTTP routes. BTCPay's own
+invoices, checkout, webhooks and Greenfield API do that work.
 
 ### 1. Prerequisites
 
@@ -155,39 +159,66 @@ invoices, checkout, webhooks and Greenfield API are the host.
 
 ### 2. Install the plugin
 
-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.
+Sign in as a **server administrator**. If someone else hosts your server, ask
+them to install the plugin for you.
+
+**1. Open the Plugins menu.** It is the plug icon in the top-right corner.
+
+**2. Click Plugin Directory.**
+
+**3. Search for `openreceive`** and click the **OpenReceive** result.
+
+**4. Click Install in BTCPay Server.** Confirm when prompted, then click
+**Restart now** and wait for BTCPay to come back.
+
+At startup, BTCPay creates the plugin's two tables in its own Postgres
+database: `openreceive_invoices` and `openreceive_swaps`, in the schema
+`BTCPayServer.Plugins.OpenReceive`. 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).
 
 ### 3. Connect the wallet
 
-Follow the plugin README's illustrated walkthrough:
-[OpenReceive for BTCPay Server](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/BTCPayServer.Plugins.OpenReceive/README.md).
-It opens the **OpenReceive** page in the store's sidebar, saves the
-receive-only NWC code, optionally saves the LSC code to turn swaps on, and
-creates a first test invoice. There is nothing else to configure: you never
-open BTCPay's Lightning node screen, and the plugin never reads the internal
-node.
+1. Select your store and open **OpenReceive** in its sidebar, under Wallets.
+2. Paste your receive-only NWC code. To see what the wallet supports first,
+   click **Test connection**.
+3. Click **Save NWC Code**.
+4. To turn swaps on, paste a Lightning Swap Connect code and click **Save swap
+   settings**.
 
-Saving fails closed if the wallet advertises a spend method such as
-`pay_invoice`. Mint a receive-only code instead; the override for a wallet
-that cannot is a deliberate, logged choice. Swaps raise the store's invoice
-expiration to 60 minutes when it is shorter, because a swap needs at least 45
-minutes of invoice life.
+The page then shows **Wallet connected**. If you set up a provider, it also
+shows **Swaps on**. There is nothing else to configure. You never open BTCPay's
+Lightning node screen, and the plugin never reads the internal node.
+
+Screenshots for each of those steps, and for creating a first test invoice,
+are in the plugin's
+[README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/BTCPayServer.Plugins.OpenReceive/README.md).
+
+The plugin refuses to save a code whose wallet advertises a spend method such
+as `pay_invoice`. Create a receive-only code instead. If your wallet cannot
+make one, there is an override, but using it is a deliberate choice and the
+plugin logs it.
+
+Turning swaps on raises the store's invoice expiration to 60 minutes if it is
+shorter. A swap needs the invoice to stay open for at least 45 minutes.
 
 ### 4. Check it
 
-**Run a health check** on the OpenReceive page runs every probe in place:
-the connection, the wallet preflight, payment notifications, the last wallet
-scan, the swap provider and its assets, the invoice expiration, and swaps
-that need a human. Each failing probe carries a fix link.
+Click **Run a health check** on the OpenReceive page. It runs every check
+right there:
+
+- the connection
+- the wallet preflight
+- payment notifications
+- the last wallet scan
+- the swap provider and its assets
+- the invoice expiration
+- swaps that need a human
+
+Each failing check comes with a link to the fix.
 
-Every setting, Greenfield route, swap state, log event and probe is in the
-[BTCPay plugin reference](https://openreceive.org/guides/btcpay-reference.md), including what is
-unsupported by design: every send-side feature, top-up invoices, and a bare
-`nostr+walletconnect://` string in BTCPay's Lightning node screen.
+The [BTCPay plugin reference](https://openreceive.org/guides/btcpay-reference.md) lists every setting,
+Greenfield route, swap state, log event and check. It also lists what the
+plugin does not support by design: every send-side feature, top-up invoices,
+and a bare `nostr+walletconnect://` string in BTCPay's Lightning node screen.