@openreceive/node 0.4.16 → 0.4.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openreceive/node",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "description": "Accept Bitcoin Lightning payments in Node.js with your own wallet and optional USDT, USDC, SOL and ETH swaps.",
   "keywords": [
     "bitcoin",
@@ -17,7 +17,7 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "@getalby/sdk": "^8.0.3",
-    "@openreceive/core": "0.4.16"
+    "@openreceive/core": "0.4.17"
   },
   "bin": {
     "openreceive": "./bin/openreceive.mjs"

package/skills/integrate-openreceive/SKILL.md

@@ -143,7 +143,7 @@ and BTCPay manage installation through their plugins; follow their references.
 | FastAPI | `openreceive doctor --app main:app` | `nwc_client`, `price_provider`, `swap_providers` on `openreceive_router`, using `openreceive.testing` fakes |
 | Laravel | `php artisan openreceive:doctor` | Bind `ReceiveNwcClient`, `PriceProvider`, and `OpenReceiveServiceProvider::SWAP_PROVIDERS` in the container |
 | Plain PHP | `php bin/doctor` (host script calling `$engine->doctor()`) | Build `Service` with `OpenReceive\Testing\FakeWallet`, `FakeSwapProvider`, and `OpenReceive\Rates\StaticPriceProvider` |
-| WordPress | `wp openreceive doctor` | Repository development: the documented Docker `compose.testkit.yml` override |
+| WordPress | `wp openreceive doctor`, then `wp openreceive test-invoice <order id>` for a real invoice | Repository development: the documented Docker `compose.testkit.yml` override |
 | BTCPay | Follow the plugin reference's connection and checkout checks | Use the plugin's Docker test setup in its reference |
 
 The routes, persistence, reconciliation, and fulfillment hooks then run the

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.16.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/btcpay.md`), not through a summarizing tool: a summary drops steps.
 
 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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.16.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/django.md`), not through a summarizing tool: a summary drops steps.
 
 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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.16.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/fastapi.md`), not through a summarizing tool: a summary drops steps.
 
 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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Fastify)
 
-These directions describe OpenReceive 0.4.16.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/fastify.md`), not through a summarizing tool: a summary drops steps.
 
 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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.16.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/laravel.md`), not through a summarizing tool: a summary drops steps.
 
 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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.16.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/next.md`), not through a summarizing tool: a summary drops steps.
 
 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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.16.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/node.md`), not through a summarizing tool: a summary drops steps.
 
 Add OpenReceive to a Node application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the packages are on npm, and the

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (PHP)
 
-These directions describe OpenReceive 0.4.16.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/php.md`), not through a summarizing tool: a summary drops steps.
 
 Add OpenReceive to a PHP application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the engine is on Packagist

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.16.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/rails.md`), not through a summarizing tool: a summary drops steps.
 
 Add OpenReceive to a Rails application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the gem is on RubyGems, the

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

@@ -1,64 +1,155 @@
 # OpenReceive agent directions (WordPress + WooCommerce)
 
-These directions describe OpenReceive 0.4.16.
-
-Install and configure the OpenReceive gateway in the existing WooCommerce
-store. Preserve its theme, checkout, customer accounts, order model and prices.
-The plugin bundles the PHP engine and checkout assets; the merchant does not
-install npm or Composer packages on the WordPress server.
-
-## Step 0 — collect and save the codes, one at a time
-
-Inspect WordPress, WooCommerce and PHP versions and GMP/sodium in both the web
-and WP-CLI runtimes. If installed, use `wp openreceive doctor` to see which
-credentials are set, without displaying their values. Skip codes already set.
-Do not search other projects, container environments or deployment secrets.
-
-Ask for the missing receive-only NWC code first, with this walkthrough:
-
-> In Rizful, open the menu → NWC → Receive-only NWC code → Copy
-> (https://openreceive.org/get_a_nwc_code_to_receive_payments). Alby Hub also
-> works: Connections → Add Connection → Read Only. Paste the code here and
-> I will save it for you.
-
-Install the exact built plugin archive described below if needed. When the code
-arrives, save it yourself with `wp openreceive configure --nwc-uri=-`, supplying
-the code through the process's stdin. Never put it in shell arguments, shell
-history, logs, source files or browser code. Do not ask the user to edit PHP or
-an environment file. The command encrypts the code and runs wallet preflight
-before saving; a failure preserves existing settings. Constants in wp-config.php
-remain authoritative; if a constant must change, use the host's secret workflow.
-
-Next ask whether customers should also pay with USDT, USDC, SOL and ETH, unless
-the user already requested these. A configured swap provider converts payments
-to BTC over Lightning in the merchant's connected wallet; available assets and
-networks depend on the provider. Ask for the LSC code separately:
-
-> Go to https://lightning-swap.com, sign in for API keys, create a key, and copy
-> the whole URI (https://openreceive.org/set_up_swap_provider). Paste it here
-> and I will save it, or say “Bitcoin only”.
-
-Save it with `wp openreceive configure --lsc-uri-primary=-` through stdin.
-Mention FixedFloat only if the merchant already uses it. Save an optional backup
-separately with `--lsc-uri-backup=-`. Do not use generic `wp wc payment_gateway`
-or REST settings writes for credentials: they are deliberately rejected.
-
-Run `wp openreceive configure --enable`, then `wp openreceive doctor`. Resolve
-failed checks before checkout testing. Create an unpaid test order and verify
-that the order-pay page opens, lists the configured methods, and resumes its
-Lightning invoice on reload. Ask the merchant to pay only if they want a real
-settlement test.
-
-The plugin owns only its payment-attempt tables in the WordPress database.
-WooCommerce owns orders, totals, stock and email. Do not add an external
-idempotency store, payment database, browser wallet credentials or custom
-fulfillment implementation. Guest return links use WooCommerce's order key;
-the plugin verifies it before issuing an expiring order-bound cookie.
-
-Run `wp openreceive doctor` after configuration. Use the documented scheduled
-reconciliation or optional notifications command for offline settlement.
-Manual merchant refunds and provider-managed payer swap refunds are separate
-flows; a receive-only NWC wallet cannot send payments.
+These directions describe OpenReceive 0.4.17. If you fetched this file, fetch it raw (`curl -fsSL https://openreceive.org/agent-directions/woocommerce.md`), not through a summarizing tool: a summary drops steps.
+
+Install and configure the OpenReceive payment gateway in the WooCommerce store
+you are working in. Preserve its theme, checkout, customer accounts, order
+model and prices. The plugin bundles the PHP engine and checkout assets: do not
+install npm or Composer packages on the WordPress server, and do not clone the
+OpenReceive repository unless the release download in Step 1 fails.
+
+The one required credential is a receive-only NWC code (Nostr Wallet Connect):
+a string from the merchant's wallet that can create invoices and read their
+status, and cannot spend. A swap provider (an "LSC" code) optionally lets
+customers pay with USDT, USDC, ETH or SOL instead; the provider converts the
+payment to BTC over Lightning in the merchant's connected wallet. Available
+assets and networks depend on the provider.
+
+Run every `wp` command below where this store's WP-CLI runs. When WordPress
+runs in Docker Compose, prefix it with the service that has WP-CLI, for
+example `docker compose run --rm -T cli wp …` or
+`docker compose exec -T wordpress wp …`. `-T` passes stdin through. If the
+store has no WP-CLI at all (managed hosting without a shell), say so and walk
+the user through the quickstart's admin screens instead.
+
+## Step 0 — ask for the two codes, one question at a time
+
+Before anything else, check one thing: whether OpenReceive is already
+installed (`wp plugin is-active openreceive`). If it is, run
+`wp openreceive doctor`. It prints `NWC_URI: set` or `unset` (likewise
+`LSC_URI_PRIMARY`), never the values. A code that is already set is not asked
+for again; if both are set, skip to `wp openreceive configure --enable` at
+the end of Step 2.
+
+Otherwise your next action is a question to the user. Do not install the
+plugin, edit Docker files or search anywhere else before asking it. Do not
+read wp-config.php, deploy config, container environments or other projects
+looking for a code: a new store has neither code yet.
+
+The user never runs a command and never edits a file. They paste each code
+into this chat; you store it. That is the supported path: do not ask them to
+run the save command themselves, and do not tell them to revoke or replace a
+code because it was pasted here. Ask one question per message.
+
+1. **First message — the NWC code, and nothing else.**
+
+   > To receive payments I need a receive-only wallet code. In Rizful: open
+   > the menu, tap NWC, choose Receive-only NWC code, and tap Copy
+   > (https://openreceive.org/get_a_nwc_code_to_receive_payments). If you would
+   > rather run your own wallet, Alby Hub works too: Connections → Add
+   > Connection → Read Only. Paste the code here and I will store it.
+
+2. **When they paste it.** If it does not start with `nostr+walletconnect://`,
+   ask them to copy the receive-only code again. Otherwise do not repeat it:
+   reply only that you have it, then ask the next question. You store it in
+   Step 2.
+3. **Second message — swaps.** If the user asked for stablecoins, USDT, USDC,
+   ETH, SOL, altcoins or "crypto" (as in "Bitcoin and stablecoin payments"),
+   this message IS the walkthrough below: do not skip it, and do not ask yes
+   or no first. Otherwise ask whether customers should also be able to pay
+   with USDT, USDC, ETH or SOL, then give the walkthrough. The walkthrough:
+
+   > Go to https://lightning-swap.com, sign in for API keys, create a key, and
+   > copy the whole URI (https://openreceive.org/set_up_swap_provider). Paste
+   > it here and I will store it — or say "Bitcoin only" and I will continue
+   > without it.
+
+   Mention FixedFloat only if they already use it.
+4. **When they paste it.** If it does not start with
+   `lightning+swapconnect://`, ask them to copy it again. Swaps are now on,
+   so keep the route back (the swap non-negotiable below).
+
+Do not report setup as complete until the NWC code is saved, and the LSC code
+is saved or the user said "Bitcoin only". Never invent a placeholder code.
+
+## Step 1 — install the plugin
+
+Install the plugin built for this release. Never install the GitHub
+source-code ZIP or a ZIP from an older release:
+
+```sh
+wp plugin install https://github.com/OpenReceive/openreceive/releases/download/v0.4.17/openreceive-wordpress-0.4.17.zip --activate
+```
+
+It needs WooCommerce active, and PHP 8.2+ with GMP and sodium in BOTH the web
+PHP and the WP-CLI PHP. On the official `wordpress` and `wordpress:cli` Docker
+images, activation fails with "OpenReceive requires the PHP sodium and GMP
+extensions": add GMP to both images as "Enable GMP in both PHP runtimes" below
+says, rebuild both, then install again. If the URL answers 404, build the same
+tag as "Get the installable archive" below says.
+
+## Step 2 — store the codes, then enable the gateway
+
+Store each code yourself, one per command, and never as a shell argument:
+
+1. Write the code with your file-editing tool, not a shell command (no
+   `echo`, `printf` or heredoc), to a new file outside the repository, such
+   as `/tmp/openreceive-code`.
+2. Run `wp openreceive configure --nwc-uri=- < /tmp/openreceive-code`. In
+   Docker: `docker compose run --rm -T cli wp openreceive configure --nwc-uri=- < /tmp/openreceive-code`.
+   For the LSC code, use `--lsc-uri-primary=-`.
+3. Delete the file (`rm /tmp/openreceive-code`), whether the command passed
+   or not.
+
+The command runs the receive-only wallet preflight, encrypts the code and
+prints only "Settings saved; wallet preflight passed."; a failure keeps the
+previous settings. If it reports spend methods such as `pay_invoice`, ask the
+user for a receive-only code again. Never turn on the spend-capable override.
+`wp wc payment_gateway` and WooCommerce REST writes of these fields are
+rejected on purpose; do not use them. A code set as a constant in
+wp-config.php wins over the stored one and changes only through the host's
+secret workflow.
+
+Then run `wp openreceive configure --enable` and `wp openreceive doctor`.
+Doctor names any failed check and exits nonzero; fix it before going on.
+
+## Step 3 — mint a test invoice
+
+Create a pending test order that pays with OpenReceive, then mint its
+Lightning invoice from the terminal:
+
+```sh
+wp wc shop_order create --user=<admin user id> --payment_method=openreceive \
+  --line_items='[{"product_id":<product id>,"quantity":1}]' --porcelain
+wp openreceive test-invoice <order id>
+```
+
+`test-invoice` goes through the same checkout route as the order-pay page. It
+prints the amount in sats, the BOLT11 invoice and the order-pay link. Give the
+user that link: it opens the checkout with the configured methods and resumes
+this same invoice. Ask them to pay only if they want a real settlement test,
+and tell them the test order is theirs to delete.
+
+## Non-negotiables
+
+- Never print, log or commit a code, never put one in a shell argument, and
+  never write one into source files, wp-config.php or browser code. Doctor's
+  set/unset is all you report.
+- Receive-only NWC is required. Never turn on the spend-capable override to
+  get past the preflight.
+- The plugin owns only its payment-attempt tables in the WordPress database.
+  WooCommerce owns orders, totals, stock and email. Do not add an external
+  idempotency store, payment database or custom fulfillment code.
+- IF SWAPS ARE ON, KEEP THE ROUTE BACK. A deposit that arrives short or late
+  becomes refundable, and the customer claims it later on the same order-pay
+  link (guests return with the order key in it). Keep order-pay links
+  reachable, and keep the plugin installed while swap orders may still need a
+  refund. https://openreceive.org/guides/swap-refunds.md
+- A receive-only wallet cannot send merchant refunds. Refund a settled
+  payment manually from the wallet.
+- Settlement runs on checkout requests and an every-minute scheduled job. On a
+  low-traffic store, run WordPress scheduled work from a system cron;
+  `wp openreceive notifications` is an optional long-running worker.
 
 ## Further reading
 
@@ -95,7 +186,7 @@ database or application.
 
 ### Get the installable archive
 
-Download [openreceive-wordpress-0.4.16.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.16/openreceive-wordpress-0.4.16.zip)
+Download [openreceive-wordpress-0.4.17.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.17/openreceive-wordpress-0.4.17.zip)
 from the matching release. Historical releases may lack this asset. If that exact
 URL returns 404, build the same tag below; never silently install an older ZIP.
 The GitHub source-code ZIP is not an installable plugin. On a development machine
@@ -104,7 +195,7 @@ with Node 22+, PHP 8.2+ with GMP/sodium, Composer and WP-CLI:
 ```sh
 git clone https://github.com/OpenReceive/openreceive.git
 cd openreceive
-git checkout v0.4.16
+git checkout v0.4.17
 npm ci
 npm run build:packages
 composer install --working-dir=packages/php/wordpress
@@ -189,6 +280,19 @@ reports the failed check with credentials redacted and exits nonzero on failure.
 The default payment title becomes “Bitcoin & crypto (OpenReceive)” with swaps;
 a customized title is preserved.
 
+To check checkout from the terminal, mint an invoice for an unpaid order whose
+payment method is OpenReceive:
+
+```sh
+wp wc shop_order create --user=<admin user id> --payment_method=openreceive \
+  --line_items='[{"product_id":<product id>,"quantity":1}]' --porcelain
+wp openreceive test-invoice <order id>
+```
+
+`test-invoice` uses the same checkout route as the order-pay page. It prints the
+amount in sats, the Lightning invoice and the order-pay link, which opens the
+checkout on that invoice. Delete the test order when you are done.
+
 ### Checkout and settlement
 
 Both WooCommerce checkout blocks and classic checkout send the customer to the