openreceive 0.4.13 → 0.4.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01e1bb860a7a293671cf05f57aab92369123dcade28a58bdb21c7c0917d3e53c
-  data.tar.gz: ccdce9021e041361aa8340972fea01cdf4e762bcf4798903900185ec9535f63c
+  metadata.gz: 291e8df2ba4b159d4b5bede37b77df8449773110c8ec307f732e7f1f176df239
+  data.tar.gz: b81c08dd8358630ea628eb2d04cda593d1ba99e559612ffdffcaf9568c46f5e6
 SHA512:
-  metadata.gz: 72862dc8a7059c13ff37db4261c4c6f37daaf2eba0e7bceebaf6cc2eeae8754938bb2aa853790856a0429922d6eff465d65f8e293759d9757c998b7b7060b107
-  data.tar.gz: c3f5e0fc7c645e3a298579f29f926e1c33ee7bfa9fc5f764ef5e826d0905f34705439adde32156eb3758944dd14346ef18a50a4b315901683a3a512a056509e0
+  metadata.gz: a29c57a32d0e44750b4122d10e4c4bad8f451ca97dce0c8dfcbd5011e77666871d4d090bf1325e3bfc69fc74cabb815b217c15a836e62b6941a7b89ab02ded45
+  data.tar.gz: fd92160562d64c75466cb814419e1ca7bb781df453dfe275bae5d229595195f99b1be945c3e31070591834ad083f0fa07d54e9290557bbc3bf2be3bf9ead27e4

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.15 - 2026-10-06
+
+- Install agent skills with `bin/rails openreceive:skills` (optional
+  `--dir .claude/skills`). The core `openreceive` gem owns the one offline
+  bundle; Rails/server gems no longer duplicate it. Other Ruby hosts can use
+  `npx skills add OpenReceive/openreceive`.
+
+`OpenReceive::Nwc.normalize_wallet_error` maps nwc-ruby 0.3's
+`NotSentError`, `TransportError` and `InfoUnavailableError` to
+`WALLET_UNAVAILABLE` (retryable) instead of `OTHER`, matching the shared
+`error-normalization` vectors.
+
+## 0.4.14 - 2026-10-04
+
+Release in lockstep with the 0.4.14 reconciliation fixes (in
+`openreceive-rails`) and the plain-HTML refund documentation in the bundled
+integration skill. No change to this gem's API.
+
 ## 0.4.13 - 2026-10-01
 
 Release in lockstep with the 0.4.13 reconciliation fixes (in

data/README.md

@@ -74,3 +74,13 @@ cross-language vectors in `spec/test-vectors`.
 - Changelog: [CHANGELOG.md](CHANGELOG.md)
 
 MIT license.
+
+## Agent skills
+
+In Rails, run `bin/rails openreceive:skills` from your application. The offline
+skills ship once in the core `openreceive` gem. Non-Rails projects can 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.

data/lib/openreceive/core.rb

@@ -316,6 +316,7 @@ module OpenReceive
       "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",
@@ -325,6 +326,7 @@ module OpenReceive
       "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",
@@ -333,6 +335,7 @@ module OpenReceive
       "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",

data/lib/openreceive/skills.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module OpenReceive
+  module Skills
+    def self.install(directory: ".agents/skills", output: $stdout)
+      source = File.join(Gem.loaded_specs.fetch("openreceive").full_gem_path, "skills")
+      target = File.expand_path(directory)
+      names = %w[integrate-openreceive debug-openreceive-payment]
+      names.each do |name|
+        raise "Bundled skill missing: #{name}. Reinstall openreceive." unless File.file?(File.join(source, name, "SKILL.md"))
+      end
+      FileUtils.mkdir_p(target)
+      target = File.realpath(target)
+      source = File.realpath(source)
+      if target == source || target.start_with?(source + File::SEPARATOR)
+        raise "Choose a skills directory outside the installed package's bundle."
+      end
+      names.each do |name|
+        destination = File.join(target, name)
+        FileUtils.rm_r(destination) if File.exist?(destination) || File.symlink?(destination)
+        FileUtils.cp_r(File.join(source, name), destination)
+        output.puts "Wrote #{destination}"
+      end
+      output.puts "For Claude Code: bin/rails openreceive:skills --dir .claude/skills"
+      0
+    end
+  end
+end

data/lib/openreceive/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenReceive
-  VERSION = "0.4.13"
+  VERSION = "0.4.15"
 end

data/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

data/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
 

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.13.
+These directions describe OpenReceive 0.4.15.
 
 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

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.13.
+These directions describe OpenReceive 0.4.15.
 
 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
@@ -167,15 +167,19 @@ itself, and they hold for every integration.
   late becomes `refund_required`, and the payer claims it on a SECOND VISIT,
   after leaving your page to fetch an address from another wallet. Three things
   must exist or that money is unreachable through your UI: a per-order URL your
-  server serves (`/checkout/:reference` — `syncUrl` on the drop-ins), your own
-  order-summary route to restore the order from, and the ATTEMPT.
+  server serves (`/checkout/:reference` — `syncUrl` on `<Checkout>`, `sync-url`
+  or `resumable` on `<openreceive-checkout>`), your own order-summary route to
+  restore the order from, and the ATTEMPT.
   `/checkouts/prepare` returns no attempts, so a checkout rebuilt from the
   reference alone opens on the method grid. Re-picking the same coin
   (`POST /swaps`) re-serves the committed attempt — but only while it is live,
   and the shadow invoice behind a swap lasts about half an hour, after which the
   same click mints a NEW deposit address and the refund is off-screen. Keep the
   `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
-  such window. https://openreceive.org/guides/swap-refunds.md
+  such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
+  `<Checkout>`; the `resume-payment-hash` attribute, fed from the
+  `openreceive-state` event (`event.detail.state.payment_hash`), on
+  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amount_for` and both drop-ins render it above the
   amount. Without it the checkout is a QR and "$1.00" with no sign of what the

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.13.
+These directions describe OpenReceive 0.4.15.
 
 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
@@ -157,15 +157,19 @@ itself, and they hold for every integration.
   late becomes `refund_required`, and the payer claims it on a SECOND VISIT,
   after leaving your page to fetch an address from another wallet. Three things
   must exist or that money is unreachable through your UI: a per-order URL your
-  server serves (`/checkout/:reference` — `syncUrl` on the drop-ins), your own
-  order-summary route to restore the order from, and the ATTEMPT.
+  server serves (`/checkout/:reference` — `syncUrl` on `<Checkout>`, `sync-url`
+  or `resumable` on `<openreceive-checkout>`), your own order-summary route to
+  restore the order from, and the ATTEMPT.
   `/checkouts/prepare` returns no attempts, so a checkout rebuilt from the
   reference alone opens on the method grid. Re-picking the same coin
   (`POST /swaps`) re-serves the committed attempt — but only while it is live,
   and the shadow invoice behind a swap lasts about half an hour, after which the
   same click mints a NEW deposit address and the refund is off-screen. Keep the
   `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
-  such window. https://openreceive.org/guides/swap-refunds.md
+  such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
+  `<Checkout>`; the `resume-payment-hash` attribute, fed from the
+  `openreceive-state` event (`event.detail.state.payment_hash`), on
+  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amount_for` and both drop-ins render it above the amount.
   Without it the checkout is a QR and "$1.00" with no sign of what the dollar

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Fastify)
 
-These directions describe OpenReceive 0.4.13.
+These directions describe OpenReceive 0.4.15.
 
 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
@@ -149,15 +149,19 @@ itself, and they hold for every integration.
   late becomes `refund_required`, and the payer claims it on a SECOND VISIT,
   after leaving your page to fetch an address from another wallet. Three things
   must exist or that money is unreachable through your UI: a per-order URL your
-  server serves (`/checkout/:reference` — `syncUrl` on the drop-ins), your own
-  order-summary route to restore the order from, and the ATTEMPT.
+  server serves (`/checkout/:reference` — `syncUrl` on `<Checkout>`, `sync-url`
+  or `resumable` on `<openreceive-checkout>`), your own order-summary route to
+  restore the order from, and the ATTEMPT.
   `/checkouts/prepare` returns no attempts, so a checkout rebuilt from the
   reference alone opens on the method grid. Re-picking the same coin
   (`POST /swaps`) re-serves the committed attempt — but only while it is live,
   and the shadow invoice behind a swap lasts about half an hour, after which the
   same click mints a NEW deposit address and the refund is off-screen. Keep the
   `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
-  such window. https://openreceive.org/guides/swap-refunds.md
+  such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
+  `<Checkout>`; the `resume-payment-hash` attribute, fed from the
+  `openreceive-state` event (`event.detail.state.payment_hash`), on
+  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and both drop-ins render it above the amount.
   Without it the checkout is a QR and "$1.00" with no sign of what the dollar
@@ -375,7 +379,9 @@ there is nothing else to generate. Details:
 No ORM? You can pass a bare driver handle (`pg`, `node:sqlite`,
 `better-sqlite3`) as the `db` in step 4. The scaffold has no flavor for it.
 Instead of scaffolding, run the same DDL once yourself, using
-`paymentsSchemaSql(dialect)` from `@openreceive/http`.
+`paymentsSchemaSql(dialect)` from `@openreceive/http`. Your adapter already
+pulls that package in, but this import is yours, so install it too:
+`npm install @openreceive/http`.
 
 ### 3. Add wallet credentials
 

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.13.
+These directions describe OpenReceive 0.4.15.
 
 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
@@ -158,15 +158,19 @@ itself, and they hold for every integration.
   late becomes `refund_required`, and the payer claims it on a SECOND VISIT,
   after leaving your page to fetch an address from another wallet. Three things
   must exist or that money is unreachable through your UI: a per-order URL your
-  server serves (`/checkout/:reference` — `syncUrl` on the drop-ins), your own
-  order-summary route to restore the order from, and the ATTEMPT.
+  server serves (`/checkout/:reference` — `syncUrl` on `<Checkout>`, `sync-url`
+  or `resumable` on `<openreceive-checkout>`), your own order-summary route to
+  restore the order from, and the ATTEMPT.
   `/checkouts/prepare` returns no attempts, so a checkout rebuilt from the
   reference alone opens on the method grid. Re-picking the same coin
   (`POST /swaps`) re-serves the committed attempt — but only while it is live,
   and the shadow invoice behind a swap lasts about half an hour, after which the
   same click mints a NEW deposit address and the refund is off-screen. Keep the
   `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
-  such window. https://openreceive.org/guides/swap-refunds.md
+  such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
+  `<Checkout>`; the `resume-payment-hash` attribute, fed from the
+  `openreceive-state` event (`event.detail.state.payment_hash`), on
+  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and both drop-ins render it above the
   amount. Without it the checkout is a QR and "$1.00" with no sign of what the

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.13.
+These directions describe OpenReceive 0.4.15.
 
 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
@@ -149,15 +149,19 @@ itself, and they hold for every integration.
   late becomes `refund_required`, and the payer claims it on a SECOND VISIT,
   after leaving your page to fetch an address from another wallet. Three things
   must exist or that money is unreachable through your UI: a per-order URL your
-  server serves (`/checkout/:reference` — `syncUrl` on the drop-ins), your own
-  order-summary route to restore the order from, and the ATTEMPT.
+  server serves (`/checkout/:reference` — `syncUrl` on `<Checkout>`, `sync-url`
+  or `resumable` on `<openreceive-checkout>`), your own order-summary route to
+  restore the order from, and the ATTEMPT.
   `/checkouts/prepare` returns no attempts, so a checkout rebuilt from the
   reference alone opens on the method grid. Re-picking the same coin
   (`POST /swaps`) re-serves the committed attempt — but only while it is live,
   and the shadow invoice behind a swap lasts about half an hour, after which the
   same click mints a NEW deposit address and the refund is off-screen. Keep the
   `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
-  such window. https://openreceive.org/guides/swap-refunds.md
+  such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
+  `<Checkout>`; the `resume-payment-hash` attribute, fed from the
+  `openreceive-state` event (`event.detail.state.payment_hash`), on
+  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and both drop-ins render it above the amount.
   Without it the checkout is a QR and "$1.00" with no sign of what the dollar
@@ -381,7 +385,9 @@ there is nothing else to generate. Details:
 No ORM? You can pass a bare driver handle (`pg`, `node:sqlite`,
 `better-sqlite3`) as the `db` in step 4. The scaffold has no flavor for it.
 Instead of scaffolding, run the same DDL once yourself, using
-`paymentsSchemaSql(dialect)` from `@openreceive/http`.
+`paymentsSchemaSql(dialect)` from `@openreceive/http`. Your adapter already
+pulls that package in, but this import is yours, so install it too:
+`npm install @openreceive/http`.
 
 ### 3. Add wallet credentials
 

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.13.
+These directions describe OpenReceive 0.4.15.
 
 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
@@ -146,15 +146,19 @@ itself, and they hold for every integration.
   late becomes `refund_required`, and the payer claims it on a SECOND VISIT,
   after leaving your page to fetch an address from another wallet. Three things
   must exist or that money is unreachable through your UI: a per-order URL your
-  server serves (`/checkout/:reference` — `syncUrl` on the drop-ins), your own
-  order-summary route to restore the order from, and the ATTEMPT.
+  server serves (`/checkout/:reference` — `syncUrl` on `<Checkout>`, `sync-url`
+  or `resumable` on `<openreceive-checkout>`), your own order-summary route to
+  restore the order from, and the ATTEMPT.
   `/checkouts/prepare` returns no attempts, so a checkout rebuilt from the
   reference alone opens on the method grid. Re-picking the same coin
   (`POST /swaps`) re-serves the committed attempt — but only while it is live,
   and the shadow invoice behind a swap lasts about half an hour, after which the
   same click mints a NEW deposit address and the refund is off-screen. Keep the
   `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
-  such window. https://openreceive.org/guides/swap-refunds.md
+  such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
+  `<Checkout>`; the `resume-payment-hash` attribute, fed from the
+  `openreceive-state` event (`event.detail.state.payment_hash`), on
+  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and both drop-ins render it above the amount.
   Without it the checkout is a QR and "$1.00" with no sign of what the dollar
@@ -366,7 +370,9 @@ there is nothing else to generate. Details:
 No ORM? You can pass a bare driver handle (`pg`, `node:sqlite`,
 `better-sqlite3`) as the `db` in step 4. The scaffold has no flavor for it.
 Instead of scaffolding, run the same DDL once yourself, using
-`paymentsSchemaSql(dialect)` from `@openreceive/http`.
+`paymentsSchemaSql(dialect)` from `@openreceive/http`. Your adapter already
+pulls that package in, but this import is yours, so install it too:
+`npm install @openreceive/http`.
 
 ### 3. Add wallet credentials
 

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (PHP)
 
-These directions describe OpenReceive 0.4.13.
+These directions describe OpenReceive 0.4.15.
 
 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
@@ -171,7 +171,9 @@ itself, and they hold for every integration.
   and the shadow invoice behind a swap lasts about half an hour, after which the
   same click mints a NEW deposit address and the refund is off-screen. Keep the
   `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
-  such window. https://openreceive.org/guides/swap-refunds.md
+  such window. On the element: the `resume-payment-hash` attribute, fed from
+  the `openreceive-state` event (`event.detail.state.payment_hash`).
+  https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and the drop-in renders it above the amount.
   Without it the checkout is a QR and "$1.00" with no sign of what the dollar

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.13.
+These directions describe OpenReceive 0.4.15.
 
 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
@@ -153,15 +153,19 @@ itself, and they hold for every integration.
   late becomes `refund_required`, and the payer claims it on a SECOND VISIT,
   after leaving your page to fetch an address from another wallet. Three things
   must exist or that money is unreachable through your UI: a per-order URL your
-  server serves (`/checkout/:reference` — `syncUrl` on the drop-ins), your own
-  order-summary route to restore the order from, and the ATTEMPT.
+  server serves (`/checkout/:reference` — `syncUrl` on `<Checkout>`, `sync-url`
+  or `resumable` on `<openreceive-checkout>`), your own order-summary route to
+  restore the order from, and the ATTEMPT.
   `/checkouts/prepare` returns no attempts, so a checkout rebuilt from the
   reference alone opens on the method grid. Re-picking the same coin
   (`POST /swaps`) re-serves the committed attempt — but only while it is live,
   and the shadow invoice behind a swap lasts about half an hour, after which the
   same click mints a NEW deposit address and the refund is off-screen. Keep the
   `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
-  such window. https://openreceive.org/guides/swap-refunds.md
+  such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
+  `<Checkout>`; the `resume-payment-hash` attribute, fed from the
+  `openreceive-state` event (`event.detail.state.payment_hash`), on
+  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `config.amount_for` and both drop-ins render it above the
   amount. Without it the checkout is a QR and "$1.00" with no sign of what the

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

@@ -1,23 +1,53 @@
 # OpenReceive agent directions (WordPress + WooCommerce)
 
-These directions describe OpenReceive 0.4.13.
+These directions describe OpenReceive 0.4.15.
 
 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.15.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.15/openreceive-wordpress-0.4.15.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.15
 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openreceive
 version: !ruby/object:Gem::Version
-  version: 0.4.13
+  version: 0.4.15
 platform: ruby
 authors:
 - OpenReceive
@@ -51,6 +51,7 @@ files:
 - lib/openreceive/keccak256.rb
 - lib/openreceive/nwc_ruby.rb
 - lib/openreceive/rates.rb
+- lib/openreceive/skills.rb
 - lib/openreceive/swap_address.rb
 - lib/openreceive/version.rb
 - skills/debug-openreceive-payment/SKILL.md