@openreceive/node 0.4.14 → 0.4.16

package/README.md

@@ -48,3 +48,14 @@ exposing payment instructions.
 - [Optional swaps](https://github.com/openreceive/openreceive/blob/master/docs/guides/automated-swaps.md)
 - [Test with a fake wallet](https://github.com/openreceive/openreceive/blob/master/docs/guides/host-testing.md)
 - [Deploy and reconcile payments](https://github.com/openreceive/openreceive/blob/master/docs/guides/deploying.md)
+
+## Agent skills
+
+Run `npx openreceive skills install` from your application after installing an
+OpenReceive server adapter. The offline copy ships in `@openreceive/node`, a
+server-adapter dependency. For a frontend-only project, use
+`npx skills add OpenReceive/openreceive`.
+See [agent setup](https://openreceive.org/agents). The bundled installers write
+to `.agents/skills/`; use `--dir .claude/skills` for Claude Code. They replace
+only `integrate-openreceive` and `debug-openreceive-payment`, preserving
+unrelated skills.

package/dist/{chunk-GOWL2Y6H.js → chunk-LD7HMUY3.js}

@@ -28,6 +28,7 @@ var NWC_ERROR_CODE_ALIASES = {
   EXPIRED: "INVOICE_EXPIRED",
   FETCH_ERROR: "WALLET_UNAVAILABLE",
   FORBIDDEN: "RESTRICTED",
+  INFO_UNAVAILABLE_ERROR: "WALLET_UNAVAILABLE",
   INVOICE_NOT_FOUND: "NOT_FOUND",
   INVALID_PARAMETER: "INVALID_REQUEST",
   INVALID_PARAMETERS: "INVALID_REQUEST",
@@ -37,6 +38,7 @@ var NWC_ERROR_CODE_ALIASES = {
   NIP47_NETWORK_ERROR: "WALLET_UNAVAILABLE",
   NOSTR_NETWORK_ERROR: "WALLET_UNAVAILABLE",
   NOT_AUTHORIZED: "UNAUTHORIZED",
+  NOT_SENT_ERROR: "WALLET_UNAVAILABLE",
   NOT_SUPPORTED: "UNSUPPORTED_METHOD",
   NOTFOUND: "NOT_FOUND",
   PERMISSION_DENIED: "RESTRICTED",
@@ -45,6 +47,7 @@ var NWC_ERROR_CODE_ALIASES = {
   SERVICE_UNAVAILABLE: "WALLET_UNAVAILABLE",
   TIMED_OUT: "TIMEOUT",
   TIMEOUT_ERROR: "TIMEOUT",
+  TRANSPORT_ERROR: "WALLET_UNAVAILABLE",
   UNKNOWN_METHOD: "UNSUPPORTED_METHOD",
   UNSUPPORTED: "UNSUPPORTED_METHOD",
   UNSUPPORTED_ENCRYPTION_MODE: "UNSUPPORTED_ENCRYPTION",

package/dist/cli.js

@@ -2,13 +2,13 @@ import {
   createNwcReceiveClient,
   readLscConnectionsFromEnvironment,
   redactSecrets
-} from "./chunk-GOWL2Y6H.js";
+} from "./chunk-LD7HMUY3.js";
 
 // src/cli.ts
-import { existsSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, realpathSync, rmSync } from "node:fs";
 import { createRequire } from "node:module";
 import path2 from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import {
   formatInvalidNwcMessage,
   NwcUriParseError,
@@ -928,6 +928,8 @@ Commands:
   debug-report        Print the same diagnostics as a redacted support report
                       (alias of doctor; always exits 0).
   scaffold payments   Emit the openreceive_payments + openreceive_meta migration and wiring guide for your ORM.
+  skills install      Copy bundled agent skills into .agents/skills.
+                      --dir <path> selects another directory (e.g. .claude/skills).
 
 Options:
   -h, --help           Show this help.
@@ -965,6 +967,33 @@ async function runCli(options) {
         walletClientFactory: options.walletClientFactory
       });
     }
+    if (command === "skills") {
+      if (args[0] !== "install" || !(args.length === 1 || args.length === 3 && args[1] === "--dir" && args[2] && !args[2].startsWith("--"))) {
+        throw new Error("Usage: openreceive skills install [--dir <path>]");
+      }
+      const source = realpathSync(fileURLToPath(new URL("../skills/", import.meta.url)));
+      let target = path2.resolve(cwd, args[2] ?? ".agents/skills");
+      const names = ["integrate-openreceive", "debug-openreceive-payment"];
+      for (const name of names) {
+        if (!existsSync(path2.join(source, name, "SKILL.md"))) {
+          throw new Error(`Bundled skill missing: ${name}. Reinstall @openreceive/node.`);
+        }
+      }
+      mkdirSync(target, { recursive: true });
+      target = realpathSync(target);
+      if (target === source || target.startsWith(`${source}${path2.sep}`)) {
+        throw new Error("Choose a skills directory outside the installed package's bundle.");
+      }
+      for (const name of names) {
+        const destination = path2.join(target, name);
+        rmSync(destination, { recursive: true, force: true });
+        cpSync(path2.join(source, name), destination, { recursive: true });
+        stdout.write(`Wrote ${destination}
+`);
+      }
+      stdout.write("For Claude Code: openreceive skills install --dir .claude/skills\n");
+      return 0;
+    }
     if (command === "scaffold") {
       const [target = "help", ...scaffoldArgs] = args;
       if (target === "help" || target === "--help" || target === "-h") {
@@ -1047,6 +1076,7 @@ async function runDiagnostics(input) {
   }
   const lines = [
     `OpenReceive ${input.command}`,
+    "Agent skills: run `npx openreceive skills install`",
     `node: ${process.version}`,
     `cwd: ${input.cwd}`,
     "storage: payment-attempt rows live in the host database (no separate store)",

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   summarizeReconcilePass,
   summarizeSwapProviderApiRequest,
   summarizeSwapProviderApiResponse
-} from "./chunk-GOWL2Y6H.js";
+} from "./chunk-LD7HMUY3.js";
 
 // src/index.ts
 import { OpenReceiveError as OpenReceiveError2 } from "@openreceive/core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openreceive/node",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "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.14"
+    "@openreceive/core": "0.4.16"
   },
   "bin": {
     "openreceive": "./bin/openreceive.mjs"

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

@@ -19,6 +19,12 @@ URL below is raw markdown — fetch it when the step needs it.
 npx openreceive doctor                     # Node version, NWC_URI, swap config, wallet probe
 npx openreceive doctor --db <db>           # + are openreceive_payments/openreceive_meta migrated?
 npx openreceive doctor --url http://localhost:3000   # + are the routes actually mounted?
+bin/rails openreceive:doctor               # Rails
+manage.py openreceive_doctor               # Django
+openreceive doctor --app main:app           # FastAPI
+php artisan openreceive:doctor             # Laravel
+wp openreceive doctor                      # WordPress
+php bin/doctor                             # plain PHP: host script calling $engine->doctor()
 ```
 
 Each failing line states its own fix. `npx openreceive debug-report` prints the
@@ -32,7 +38,7 @@ same diagnostics redacted, always exit 0 — safe to share.
 | `INVALID_NWC` / "not a valid NWC code" | The value is malformed (must be `nostr+walletconnect://` with 64-hex pubkey and secret, ≥1 `wss` relay). Re-copy it from the wallet. |
 | "NOT receive-only" / spend methods advertised | The wallet minted a spend-capable code; OpenReceive fails closed because a leak would drain the wallet. Mint a receive-only code. Overriding (`allowSpendCapableWallet` / `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC`) is a last resort. |
 | Wallet preflight failed (methods/encryption) | The wallet must advertise `make_invoice` + `list_transactions` and NIP-04 or NIP-44 v2. Use a compatible wallet. |
-| "The openreceive_meta table does not exist" / raw `no such table: openreceive_payments` | The migration was never applied. Node: `npx openreceive scaffold payments --orm <yours>`, then run the emitted migration through the app's normal workflow. Rails: `bin/rails generate openreceive:install`, then `bin/rails db:migrate`. https://openreceive.org/guides/storage.md |
+| "The openreceive_meta table does not exist" / raw `no such table: openreceive_payments` | The migration was never applied. Node: `npx openreceive scaffold payments --orm <yours>`, then run the emitted migration through the app's normal workflow. Rails: `bin/rails generate openreceive:install`, then `bin/rails db:migrate`. Django: `manage.py openreceive_install <app> && manage.py migrate`. FastAPI: `openreceive scaffold payments --alembic --dialect <db>` (or `--sql`), then apply through the host workflow. Laravel: `php artisan openreceive:install && php artisan migrate`. Plain PHP: apply `OpenReceive\Storage\PaymentsSchema::statements($dialect)` through the host workflow. WordPress: check plugin activation/upgrades applied the tables. https://openreceive.org/guides/storage.md |
 | "requires amountFor / onPaid / authorize / host" | The factory is missing a required hook — see the host contract in https://openreceive.org/guides/api-reference.md |
 
 ## 3. Request-time errors from the routes
@@ -51,7 +57,12 @@ same diagnostics redacted, always exit 0 — safe to share.
 - Settlement is opportunistic: any OpenReceive request runs one reconcile pass
   through a durable gate (min 3s between wallet scans, stretched by invoice
   age). A quiet server settles on the next request — or run the optional
-  notification worker. No timer is missing; that is the design.
+  notifications worker: Rails `bin/rails openreceive:notifications`, Django
+  `manage.py openreceive_notifications`, FastAPI
+  `openreceive notifications --app main:app`, Laravel
+  `php artisan openreceive:notifications`, WordPress `wp openreceive notifications`,
+  or plain PHP's host script `php bin/notifications`. Node hosts run their
+  separate worker using the notifications API. No web-process timer is missing.
 - An unpaid attempt closes only after a successful wallet scan at/after expiry
   plus a 900s grace constant — a local clock alone never closes one. `expired`
   arriving "late" is correct.
@@ -83,8 +94,13 @@ same diagnostics redacted, always exit 0 — safe to share.
 
 - The components require `prefix` — the exact base path the routes are mounted
   at (`"/openreceive"` unless you changed it).
-- Import the stylesheet (`@openreceive/react/styles.css` or the elements
-  sheet).
+- Import `@openreceive/react/styles.css` or `@openreceive/elements/styles.css`
+  alongside the component registration. For standalone Django/Laravel/PHP,
+  serve both `openreceive-checkout.js` (as a module) and
+  `openreceive-checkout.css`. Django serves them from `static/openreceive/`
+  via `collectstatic`; Laravel/PHP serve the unpacked standalone assets from
+  the public directory. Check that both requests succeed and the custom
+  element is registered. Do not process the compiled stylesheet with Tailwind.
 - "invoice must not be an NWC connection string" means a server secret leaked
   into a browser payload — stop and fix the server response; never render it.
   https://openreceive.org/guides/frontend-checkout.md

package/skills/integrate-openreceive/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: integrate-openreceive
 description: >
-  Integrate OpenReceive inbound Bitcoin Lightning payments into an application.
-  Use when adding Bitcoin, Lightning, or crypto checkout to a Node.js, Express,
-  Fastify, Next.js, Rails, React, Vue, Svelte, Angular, or plain-HTML
-  application with OpenReceive (the @openreceive/* npm packages or the
-  openreceive-rails gem), or when connecting a BTCPay Server store to a
-  receive-only NWC wallet with the OpenReceive plugin.
+  Integrate OpenReceive Bitcoin Lightning checkout and optional USDT, USDC,
+  SOL, and ETH swaps. Use for Node.js, Express, Fastify, Next.js, Rails,
+  Python, Django, FastAPI, Laravel, plain PHP, WordPress/WooCommerce,
+  React, Vue, Svelte, Angular, or plain HTML applications, or connecting
+  BTCPay Server to a receive-only NWC wallet. A configured swap provider
+  converts these payments to BTC over Lightning in the merchant's connected
+  wallet; asset and network availability depends on the provider.
 license: MIT
 ---
 
@@ -19,6 +20,10 @@ settles. There is no OpenReceive account and no API key; funds land directly in
 the merchant's wallet. The one required credential is a **receive-only NWC
 code** (`NWC_URI`).
 
+Optional swaps let customers pay with USDT, USDC, SOL, and ETH. A configured
+swap provider converts these payments to BTC over Lightning in the merchant's
+connected wallet; asset and network availability depends on the provider.
+
 ## Pick the stack, then follow its directions
 
 1. Identify the server stack of the application you are in.
@@ -28,6 +33,8 @@ code** (`NWC_URI`).
    - Node, Fastify: [references/fastify.md](references/fastify.md)
    - Node, Next.js App Router: [references/next.md](references/next.md)
    - Rails: [references/rails.md](references/rails.md)
+   - Python, FastAPI: [references/fastapi.md](references/fastapi.md)
+   - Plain PHP: [references/php.md](references/php.md)
    - Django: [references/django.md](references/django.md)
    - Laravel: [references/laravel.md](references/laravel.md)
    - WordPress + WooCommerce: [references/woocommerce.md](references/woocommerce.md) — the packaged gateway and merchant settings.
@@ -44,6 +51,9 @@ Fastify: `npm install @openreceive/fastify @openreceive/react`; Next.js:
 `npm install @openreceive/next @openreceive/react`. Swap the UI package (`vue`,
 `svelte`, `angular`, `elements`) for the frontend the app already has. Install
 (Rails): `bundle add openreceive-rails`.
+Django: `pip install "openreceive[django]"`; FastAPI:
+`pip install "openreceive[fastapi]"`; Laravel: `composer require openreceive/laravel`;
+plain PHP: `composer require openreceive/openreceive nyholm/psr7 nyholm/psr7-server`.
 
 ## The three server objects
 
@@ -108,25 +118,36 @@ overriding.
 
 ## Database tables
 
-```sh
-npx openreceive scaffold payments --orm prisma   # or drizzle | typeorm | sequelize | knex
-```
+Generate the two tables in the host's existing database:
 
-emits the `openreceive_payments` + `openreceive_meta` migration for THIS app's
-database (Rails: `bin/rails generate openreceive:install`); run it through the
-app's normal migration workflow. The tables sit beside your models — no
-relations to them, no separate database, no Redis.
+| Stack | Generate and apply |
+| --- | --- |
+| Node | `npx openreceive scaffold payments --orm <orm>`, then the app's normal migration command |
+| Rails | `bin/rails generate openreceive:install && bin/rails db:migrate` |
+| Django | `manage.py openreceive_install <app> && manage.py migrate` |
+| FastAPI | `openreceive scaffold payments --alembic --dialect <db>` (or `--sql`), then apply through the app's migration workflow |
+| Laravel | `php artisan openreceive:install && php artisan migrate` |
+| Plain PHP | Use `OpenReceive\Storage\PaymentsSchema::statements($dialect)` in the host's migration workflow, as in the PHP reference |
 
-## Verify, and test without a real wallet
+These emit `openreceive_payments` + `openreceive_meta`. The tables sit beside
+your models — no relations to them, no separate database, no Redis. WordPress
+and BTCPay manage installation through their plugins; follow their references.
 
-`npx openreceive doctor` checks the configuration and says what to fix.
+## Verify, and test without a real wallet
 
-For tests, inject a fake wallet at the stable seams — `client` on
-`createOpenReceive` (any object with `preflight`, `makeInvoice`,
-`listTransactions`) or `config.nwc_client` in Rails — plus
-`StaticPriceProvider` for fiat pricing without a network. Your routes,
-persistence, reconcile, and `onPaid` then run the production code paths.
-Details: https://openreceive.org/guides/host-testing.md
+| Stack | Doctor | Test seam |
+| --- | --- | --- |
+| Node | `npx openreceive doctor` | `client` on `createOpenReceive` (`preflight`, `makeInvoice`, `listTransactions`), plus `StaticPriceProvider` |
+| Rails | `bin/rails openreceive:doctor` | `config.nwc_client`, `config.swap_providers`, `config.price_provider` |
+| Django | `manage.py openreceive_doctor` | `OPENRECEIVE["SERVICE"]`, a factory returning a `Service` built on `openreceive.testing` fakes |
+| 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 |
+| 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
+production paths. Details: https://openreceive.org/guides/host-testing.md
 
 ## Deeper documentation
 

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.16.
 
 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
@@ -164,13 +164,17 @@ 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.

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.16.
 
 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
@@ -366,17 +366,18 @@ Then add the app, point it at a host class, and mount the routes:
 INSTALLED_APPS += ["openreceive.django"]
 
 OPENRECEIVE = {
-    "HOST": "shop.openreceive_host.Host",   # the class with the three hooks (generated below)
+    "HOST": "shop.openreceive_host.Host",  # the class with the three hooks (generated below)
     "PRICE_CURRENCIES": ["USD"],
-    "RATE_LIMITING": False,                 # True for public web shops (see below)
-    "OPPORTUNISTIC_RECONCILE": True,        # or {"min_interval_seconds": …}; False only with your own worker
-    "DATABASE": "default",                  # the DATABASES alias that holds the two engine tables
+    "RATE_LIMITING": False,  # True for public web shops (see below)
+    "OPPORTUNISTIC_RECONCILE": True,  # or {"min_interval_seconds": …}; False only with your own worker
+    "DATABASE": "default",  # the DATABASES alias that holds the two engine tables
 }
 ```
 
 ```python
 # urls.py
 from django.urls import include, path
+
 urlpatterns += [path("openreceive/", include("openreceive.django.urls"))]
 ```
 
@@ -420,9 +421,9 @@ The generated host module explains this and shows the guarded transition:
 
 ```python
 def on_paid(self, settlement: PaymentSettlement) -> None:
-    claimed = Order.objects.filter(
-        pk=settlement.reference, state="awaiting_payment"
-    ).update(state="paid", paid_at=datetime.fromtimestamp(settlement.paid_at, tz=UTC))
+    claimed = Order.objects.filter(pk=settlement.reference, state="awaiting_payment").update(
+        state="paid", paid_at=datetime.fromtimestamp(settlement.paid_at, tz=UTC)
+    )
     if claimed == 0:
         return  # someone else already fulfilled it
 
@@ -450,7 +451,9 @@ instead:
 
 ```python
 def on_paid(self, settlement: PaymentSettlement) -> None:
-    order = Order.objects.select_for_update().filter(pk=settlement.reference).first()  # SELECT … FOR UPDATE
+    order = (
+        Order.objects.select_for_update().filter(pk=settlement.reference).first()
+    )  # SELECT … FOR UPDATE
     if order is None or order.state != "awaiting_payment":
         return
     order.state = "paid"
@@ -533,8 +536,9 @@ from openreceive.server import HookContext
 from openreceive.storage import PaymentSettlement
 
 from shop.models import Order  # YOUR model — it could be named anything. OpenReceive
-                               # never sees it or touches its table; these hooks are the
-                               # only bridge between the engine and your data.
+# never sees it or touches its table; these hooks are the
+# only bridge between the engine and your data.
+
 
 class Host:
     # Your policy, called before every checkout/payment/swap request. `context`
@@ -564,8 +568,11 @@ class Host:
         order = Order.objects.filter(pk=reference).first()
         if order is None:
             return None
-        return {"currency": "USD", "value": str(order.total),
-                "description": f"{order.items.count()} items"}
+        return {
+            "currency": "USD",
+            "value": str(order.total),
+            "description": f"{order.items.count()} items",
+        }
 
     # Runs inside the settlement transaction, only for the order's first settled
     # attempt. The WHERE clause is the lock: a second fulfillment path of yours

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.14.
+These directions describe OpenReceive 0.4.16.
 
 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.14.
+These directions describe OpenReceive 0.4.16.
 
 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.14.
+These directions describe OpenReceive 0.4.16.
 
 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.14.
+These directions describe OpenReceive 0.4.16.
 
 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.14.
+These directions describe OpenReceive 0.4.16.
 
 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.14.
+These directions describe OpenReceive 0.4.16.
 
 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.14.
+These directions describe OpenReceive 0.4.16.
 
 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,23 +1,53 @@
 # OpenReceive agent directions (WordPress + WooCommerce)
 
-These directions describe OpenReceive 0.4.14.
+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 — inspect configuration
+## Step 0 — collect and save the codes, one at a time
 
-Check WordPress, WooCommerce and PHP versions, GMP and sodium availability,
-whether the plugin is installed, and whether the Doctor panel reports the
-receive-only NWC credential as set. Never display its value. For a real store,
-ask the merchant to configure a receive-only wallet if none is available.
-For repository development, use the Docker demo's explicit testkit override.
+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.
 
-Upload a built plugin archive, not a zip of the source directory. The plugin
-has not yet been accepted into the WordPress.org directory. Configuration and
-the complete quickstart follow below.
+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
@@ -32,48 +62,13 @@ flows; a receive-only NWC wallet cannot send payments.
 
 ## Further reading
 
-- [Express Quickstart (Node)](https://openreceive.org/guides/quickstart-node.md)
-- [Fastify Quickstart](https://openreceive.org/guides/quickstart-fastify.md)
-- [FastAPI Quickstart](https://openreceive.org/guides/quickstart-fastapi.md)
-- [Django Quickstart](https://openreceive.org/guides/quickstart-django.md)
-- [Next.js Quickstart](https://openreceive.org/guides/quickstart-next.md)
-- [Rails Quickstart](https://openreceive.org/guides/quickstart-rails.md)
-- [PHP Quickstart (plain PHP)](https://openreceive.org/guides/quickstart-php.md)
-- [Laravel Quickstart](https://openreceive.org/guides/quickstart-laravel.md)
-- [BTCPay Server Quickstart](https://openreceive.org/guides/quickstart-btcpay.md)
-- [BTCPay Plugin Reference](https://openreceive.org/guides/btcpay-reference.md)
-- [Node ORM Recipes](https://openreceive.org/guides/node-orms.md)
-- [Authorization](https://openreceive.org/guides/authorization.md)
-- [Rate Limiting](https://openreceive.org/guides/rate-limiting.md)
-- [Frontend Checkout](https://openreceive.org/guides/frontend-checkout.md)
-- [Checkout UX](https://openreceive.org/guides/checkout-ux.md)
-- [Headless Checkout](https://openreceive.org/guides/headless-checkout.md)
+- [WordPress + WooCommerce Quickstart](https://openreceive.org/guides/quickstart-woocommerce.md)
 - [Automated Swaps](https://openreceive.org/guides/automated-swaps.md)
 - [Swap Refunds](https://openreceive.org/guides/swap-refunds.md)
 - [Lightning Swap Connect URI](https://openreceive.org/guides/lightning-swap-connect.md)
-- [Environment Variables](https://openreceive.org/guides/environment-variables.md)
-- [Payment Storage](https://openreceive.org/guides/storage.md)
-- [Deploying OpenReceive](https://openreceive.org/guides/deploying.md)
-- [Testing Your OpenReceive Integration](https://openreceive.org/guides/host-testing.md)
-- [API Reference](https://openreceive.org/guides/api-reference.md)
 - [Security](https://openreceive.org/guides/security.md)
-- [Provider Registry](https://openreceive.org/guides/provider-registry.md)
 - [Price Feeds](https://openreceive.org/guides/price-feeds.md)
-- [React Material UI Recipe](https://openreceive.org/guides/react-material-ui-recipe.md)
-- [Flask Recipe](https://openreceive.org/guides/flask-recipe.md)
-- [Writing Your Own Checkout Route](https://openreceive.org/guides/custom-checkout-route.md)
-- [Agent Directions: Node.js](https://openreceive.org/guides/agent-directions-node.md)
-- [Agent Directions: Fastify](https://openreceive.org/guides/agent-directions-fastify.md)
-- [Agent Directions: FastAPI](https://openreceive.org/guides/agent-directions-fastapi.md)
-- [Agent Directions: Django](https://openreceive.org/guides/agent-directions-django.md)
-- [Agent Directions: Next.js](https://openreceive.org/guides/agent-directions-next.md)
-- [Agent Directions: Rails](https://openreceive.org/guides/agent-directions-rails.md)
-- [Agent Directions: PHP](https://openreceive.org/guides/agent-directions-php.md)
-- [Agent Directions: Laravel](https://openreceive.org/guides/agent-directions-laravel.md)
-- [Agent Directions: BTCPay Server](https://openreceive.org/guides/agent-directions-btcpay.md)
-- [WordPress + WooCommerce Quickstart](https://openreceive.org/guides/quickstart-woocommerce.md)
-
-- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+- [Payment Safety Upgrade](https://openreceive.org/guides/payment-safety-upgrade.md)
 
 ---
 
@@ -84,6 +79,10 @@ passes. The page it comes from is https://openreceive.org/guides/quickstart-wooc
 
 ## WordPress + WooCommerce quickstart
 
+The [WordPress integration entry point](https://openreceive.org/integrations/wordpress)
+redirects to the WooCommerce integration, which uses this same guide and agent
+directions. OpenReceive checkout on WordPress requires WooCommerce.
+
 Activate WooCommerce first. Then install the built OpenReceive plugin zip
 through **Plugins → Add New → Upload Plugin**. You cannot upload the source
 directory as-is. It needs a build first. The plugin is not yet submitted to
@@ -96,15 +95,16 @@ database or application.
 
 ### Get the installable archive
 
-If the [OpenReceive GitHub release](https://github.com/OpenReceive/openreceive/releases)
-you picked lists `openreceive-wordpress-<version>.zip`, use that file. The GitHub
-source-code zip is not the plugin archive. If the release has no built zip yet,
-build one on a development machine with Node 22+, PHP 8.2+, Composer and WP-CLI:
+Download [openreceive-wordpress-0.4.16.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.16/openreceive-wordpress-0.4.16.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
+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 <release-tag>
+git checkout v0.4.16
 npm ci
 npm run build:packages
 composer install --working-dir=packages/php/wordpress
@@ -116,6 +116,40 @@ needs WP-CLI on `PATH`. Otherwise, set `OPENRECEIVE_WP_CLI` to the absolute path
 of its phar. Your WordPress server needs neither Node nor Composer. The built
 plugin already bundles its dependencies and checkout assets.
 
+### Enable GMP in both PHP runtimes
+
+GMP is required by the bundled elliptic-curve dependency. Enable it for both
+web PHP (Apache/FPM) and the PHP executable running WP-CLI. Installing it in
+only the WordPress container does not update a separate CLI container.
+
+For Debian-based official PHP/WordPress images, add to **each** Dockerfile:
+
+```dockerfile
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends libgmp-dev \
+    && docker-php-ext-install gmp \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+For Alpine-based PHP/CLI images:
+
+```dockerfile
+USER root
+RUN apk add --no-cache gmp \
+    && apk add --no-cache --virtual .gmp-build $PHPIZE_DEPS gmp-dev \
+    && docker-php-ext-install gmp \
+    && apk del .gmp-build
+```
+
+Restore the base image's original runtime user after installing extensions.
+Rebuild and recreate both containers. On Debian/Ubuntu hosts, install the GMP
+package matching the active PHP version (for example `php8.2-gmp` for PHP 8.2),
+then restart that version's web PHP service. Verify `php --ri gmp` and
+`wp openreceive doctor` for CLI, and the gateway Doctor panel for web PHP.
+On managed WordPress hosting, ask the host to enable GMP and sodium in both
+runtimes; if they cannot, this plugin cannot run there. Do not use Composer's
+`--ignore-platform-reqs` to bypass the requirements.
+
 ### Configure the wallet
 
 1. Open **WooCommerce → Settings → Payments → OpenReceive**.
@@ -134,6 +168,27 @@ providers, you can also set the `OPENRECEIVE_LSC_URI_PRIMARY` and
 `OPENRECEIVE_LSC_URI_BACKUP` constants. Never put these values in browser code
 or logs.
 
+#### Configure through WP-CLI
+
+`wp openreceive configure` accepts one credential at a time from stdin. Feed
+stdin through your secret manager or an existing protected file, never a code
+literal in the command line:
+
+```sh
+wp openreceive configure --nwc-uri=- < /secure/path/wallet-code
+wp openreceive configure --lsc-uri-primary=- < /secure/path/swap-code
+wp openreceive configure --enable
+wp openreceive doctor
+```
+
+Omit the swap command for Bitcoin-only checkout. `--lsc-uri-backup=-` adds a
+backup. These commands share admin preflight and encrypted storage. Credential
+flags accept only `-`; blank input leaves settings intact. Generic WooCommerce
+REST and `wp wc payment_gateway` credential updates are rejected. `doctor`
+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.
+
 ### Checkout and settlement
 
 Both WooCommerce checkout blocks and classic checkout send the customer to the