openreceive-rails 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dbfdf2839c02c9304b822e46e2e15cec7a15b9a54868ba26548f7d777bd8042
-  data.tar.gz: aa47745eb8b94dde5c846ac2814f4328cb2cfe62355c6d3c6090c97d492cca2e
+  metadata.gz: b0e01e9b76a2a924c07b7403a1a103e5db904147fcd8a44f385cf42ba616b97c
+  data.tar.gz: 59c7558cd8a72dc905517c8812750c1ed53f56495797ccc40b4eca5924eb2cb5
 SHA512:
-  metadata.gz: fb6cda2f07f78cca96802de2db826421fb304b56bd5c3c4e4873d735449369b613146aa615f876a45e74c738613cf032357e1d6344b303a3c278762780c68ade
-  data.tar.gz: 8d9c887792d1029cff868ecc466b21f90a62da9b7414e5a752501227d9e767d2ad421ec084f4771824e9392fda91240583fd93b7600574625d4fb4795a7e04d9
+  metadata.gz: 636b758e07b9bdce4155984fc29629b2ac7b90aee6302605836513595900f837933fba80df7b3ec06e0f40537dc6c8f223b0ffcdeeb5dd5eef25111e390006fd
+  data.tar.gz: c591cacae9e9e4adedd2aa633fdaa6b2e375829d11f3746c94a01dd56abb930a5c135c7f7d0a304d3a38dd5542d9a5e7ce480dc50d013e2752721cb00ba924e8

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.4.4 - 2026-09-07
+
+Version lockstep with the 0.4.4 npm release (every checkout image now ships
+inside the JavaScript; a Rails host no longer copies `dist/assets` or sets
+`asset-base-url`, and the quickstart no longer says to). Ruby changes in this
+gem:
+
+- `OpenReceive::ApplicationController`'s header comment is corrected: the
+  engine inherits `config.parent_controller` for forgery protection only and
+  reads nothing else from it. The quickstart documents what that inheritance
+  also brings (every global `before_action`, including redirect-to-login
+  filters) and the two remedies.
+- The bundled agent skill gains references for Django, FastAPI, Fastify,
+  Laravel and Next.js beside Node, Rails and BTCPay Server.
+
+## 0.4.3 - 2026-09-03
+
+Version lockstep with the 0.4.3 npm release (container-query checkout
+layout, themed pre-create screens, padded root, money caption).
+
+The opportunistic reconcile pass logs one short line per status poll:
+`[openreceive] payment.reconcile.completed: 1 pending attempt_count=1
+window=<from>..<until>` — what the pass decided (zero counts dropped, `of N
+attempts` when a truncated walk could not reach every hash), the same shape
+as the Node engine's line. It replaces the sentence about batched
+`list_transactions` windows. Rails' own request logging for the poll route
+is unchanged; use `config.log_level` or `Rails.logger.silence` there.
+
 ## 0.4.2 - 2026-09-03
 
 Version lockstep with the 0.4.2 npm release (the scoped frontend stylesheet).

data/app/controllers/openreceive/application_controller.rb

@@ -2,8 +2,20 @@
 
 module OpenReceive
   # Base controller for the engine. It inherits DYNAMICALLY from the configured
-  # `config.parent_controller` (default "ActionController::Base"; a host sets "ApplicationController")
-  # so the engine automatically gets the host's authentication and current_user.
+  # `config.parent_controller` (default "ActionController::Base"; the generated
+  # initializer sets "ApplicationController"). What that inheritance is FOR is the
+  # host's forgery protection: apps that never adopted `load_defaults 5.2` have
+  # `protect_from_forgery` only on their own ApplicationController, so pointing the
+  # engine at the bare base class would silently drop CSRF on cookie-authenticated
+  # checkout routes. The engine reads nothing else from the parent — no
+  # `current_user`, no helpers; `config.authorize` receives the raw request and
+  # the host's policy reads its own session from it.
+  #
+  # Everything else the parent declares is inherited too, including every global
+  # `before_action`. A filter that redirects to a login page will redirect these
+  # JSON routes as well. Hosts with such filters point `config.parent_controller`
+  # at a slimmer controller, or `skip_before_action` on this class in a
+  # `config.to_prepare` block. The Rails quickstart documents both.
   #
   # Set `parent_controller` in a normal initializer — not `after_initialize`. Production
   # eager-loads this class before after_initialize runs, so a late parent_controller change

data/lib/openreceive/rails/version.rb

@@ -5,6 +5,6 @@ module OpenReceive
   # top-level `::Rails` framework constant — engine code always references the framework as
   # `::Rails` to avoid shadowing.
   module Rails
-    VERSION = "0.4.2"
+    VERSION = "0.4.4"
   end
 end

data/lib/openreceive/reconcile.rb

@@ -230,17 +230,25 @@ module OpenReceive
     # attempts are pending), so operators can watch settlement discovery and
     # the batched list_transactions window without raising the log level. All
     # pending attempts share one creation-time window walked at most twice —
-    # never one wallet call per invoice.
+    # never one wallet call per invoice. One short line per poll: this fires
+    # on every status poll while a payer waits. Mirrors the JS
+    # payment.reconcile.completed line.
     def log_reconcile_pass(attempts, results, overlap_seconds, observed_at)
       logger = openreceive_logger
       return if logger.nil?
 
       counts = results.group_by { |checked| checked["status"] }.transform_values(&:length)
+      decided = %w[settled pending not_found].filter_map do |status|
+        count = counts[status]
+        "#{count} #{status.tr('_', ' ')}" unless count.nil? || count.zero?
+      end
+      decided = ["0 decided"] if decided.empty?
+      # Attempts scanned vs hashes decided: a gap is how a truncated scan shows up.
+      scanned = results.length == attempts.length ? "" : " of #{attempts.length} attempts"
       window_from = [attempts.map { |attempt| Integer(attempt.fetch("created_at")) }.min - overlap_seconds, 0].max
       logger.info(
-        "[openreceive] reconcile pass: #{attempts.length} pending attempt(s) in one " \
-        "batched list_transactions window (from #{window_from} until #{observed_at + overlap_seconds}, <=2 walks): " \
-        "#{counts.map { |status, count| "#{count} #{status}" }.join(', ')}"
+        "[openreceive] payment.reconcile.completed: #{decided.join(', ')}#{scanned} " \
+        "attempt_count=#{attempts.length} window=#{window_from}..#{observed_at + overlap_seconds}"
       )
     rescue StandardError
       # Diagnostics must never affect the pass.

data/skills/integrate-openreceive/SKILL.md

@@ -5,7 +5,8 @@ description: >
   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).
+  openreceive-rails gem), or when connecting a BTCPay Server store to a
+  receive-only NWC wallet with the OpenReceive plugin.
 license: MIT
 ---
 
@@ -23,15 +24,24 @@ code** (`NWC_URI`).
 1. Identify the server stack of the application you are in.
 2. Open the matching reference — it is complete (quickstart inlined) and needs
    no network access:
-   - Node (Express / Fastify / Next.js): [references/node.md](references/node.md)
+   - Node, Express: [references/node.md](references/node.md)
+   - 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)
+   - Django: [references/django.md](references/django.md)
+   - Laravel: [references/laravel.md](references/laravel.md)
+   - BTCPay Server: [references/btcpay.md](references/btcpay.md) — a plugin,
+     configured in BTCPay's store UI or Greenfield API; no application code,
+     no npm packages, no gem. The rest of this file is about the library.
 3. Follow its **Step 0** first: confirm `NWC_URI` is set in the server
    environment before writing code. Never print the value; never invent a
    placeholder.
 
-Install (Node): `npm install @openreceive/express @openreceive/react` — swap
-the adapter (`fastify`, `next`) and UI package (`vue`, `svelte`, `angular`,
-`elements`) for the stack. Install (Rails): `bundle add openreceive-rails`.
+Install, per adapter — Express: `npm install @openreceive/express @openreceive/react`;
+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`.
 
 ## The three server objects
 

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

@@ -0,0 +1,193 @@
+# OpenReceive agent directions (BTCPay Server)
+
+These directions describe OpenReceive 0.4.4.
+
+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
+SOL. You do not need a copy of the OpenReceive source, and there is no
+application code to write: the plugin is configured through BTCPay's store UI
+or its Greenfield API, and the quickstart is appended to this file in full.
+
+This is the BTCPay plugin, not the Node or Rails library. Do not install
+`@openreceive/*` packages or the `openreceive-rails` gem into a BTCPay
+deployment, do not add `openreceive_payments` tables, and do not mount
+OpenReceive HTTP routes. BTCPay's invoices, checkout, webhooks and Greenfield
+API are the host; the plugin only supplies the Lightning backend and the swap
+rail.
+
+## What the plugin is
+
+A BTCPay Server plugin (`BTCPayServer.Plugins.OpenReceive`) that registers a
+Lightning connection-string handler for `type=openreceive;nwc=<NWC URI>`.
+Saving that string makes the NWC wallet the store's Lightning node: BTCPay
+mints every Lightning invoice in that wallet and its own `LightningListener`
+records the payments. The plugin never calls a NIP-47 `pay_*` method, so
+every send-side BTCPay feature (Lightning payouts, pull-payment refunds over
+Lightning, the send tab) is unavailable by design.
+
+The one required credential is a receive-only NWC code. A Lightning Swap
+Connect (LSC) code optionally adds server-side swaps: a provider order aimed at
+the invoice's existing BOLT11, tracked in the plugin's own table, with the
+refund path on the same checkout screen.
+
+## Step 0 — check the deployment before you change anything
+
+1. Confirm the BTCPay Server version is 2.4.2 or later (Server Settings →
+   About, or `GET /api/v1/server/info`). The plugin declares that minimum and
+   BTCPay refuses to load it below.
+2. Check whether the plugin is installed (Server Settings → Plugins, or the
+   store navigation shows an "OpenReceive" entry). If not, install it from the
+   BTCPay plugin directory (Server Settings → Plugins, search "OpenReceive"),
+   as the quickstart says; do not invent an installer command.
+3. Check whether the store already has an OpenReceive connection:
+   `GET /api/v1/stores/{storeId}/openreceive/settings` returns
+   `lightningNodeIsOpenReceive`. If true, the wallet step is done — go to
+   swaps only if the user wants them.
+4. If no receive-only NWC code is available, stop and tell the user exactly
+   what to create:
+
+   > OpenReceive cannot mint an invoice without a receive-only NWC code. Get
+   > one at https://openreceive.org/get_a_nwc_code_to_receive_payments and
+   > paste it into Store → OpenReceive → Test connection, or hand it to me and
+   > I will set it through the Greenfield API.
+
+   Never print, log or echo the code; report only whether it is set. Never
+   paste a bare `nostr+walletconnect://` string into BTCPay's Lightning node
+   screen — that form is claimed by the Nostr plugin, without the receive-only
+   guard.
+5. If the user wants altcoin payments, ask for an LSC code from
+   https://openreceive.org/set_up_swap_provider. Do not wait for it: the
+   wallet works without it, and swaps switch on later with one settings change.
+
+Only then start the quickstart.
+
+## Non-negotiables
+
+- The connection string is `type=openreceive;nwc=<NWC URI>[;allow-spend=true]`
+  and nothing else. Set it through the setup page or
+  `PUT /api/v1/stores/{storeId}/openreceive/settings` with `nwcUri`, never by
+  editing BTCPay's Lightning node screen by hand.
+- Receive-only is required. A code that advertises `pay_invoice` or another
+  spend method is refused on save. The override (`allowSpendCapableWallet`,
+  the checkbox on the setup page) is the user's explicit choice; never tick it
+  to make a save succeed.
+- The wallet's network must match BTCPay's. A mismatch is a refusal, not a
+  warning.
+- The wallet must grant `make_invoice` and `list_transactions`.
+  `lookup_invoice` is optional; do not ask the user for a code that grants it.
+- Swaps require the store's Lightning node to be the OpenReceive connection.
+  Enabling swaps on a store using the internal node is refused
+  (`wallet_required`).
+- Swaps set the store's invoice expiration to 60 minutes when it is shorter,
+  and the plugin refuses to create a swap on an invoice with less than the
+  provider's window left. Do not lower the expiration below 45 minutes on a
+  swap-enabled store.
+- Top-up (amountless) invoices are unsupported on this backend. Do not
+  configure a point of sale or payment link that relies on them with this
+  wallet.
+- Secrets stay server-side. The NWC code and LSC code live in BTCPay's
+  database like every other BTCPay credential; never copy them into
+  screenshots, tickets, browser code or logs. The provider's order token never
+  leaves the server.
+- BTCPay's `LightningListener` is the settlement authority. Provider
+  `completed` is not payment; only the wallet reporting the Lightning invoice
+  settled is. Do not build anything that fulfils on a provider state.
+- There is no merchant-initiated refund of a settled Lightning payment. A swap
+  refund is a payer reclaiming a deposit that never converted, and only from
+  the `refund_required` provider state.
+
+## Verifying
+
+Store → OpenReceive → **Run a health check** (the doctor page) runs every probe now: connection, preflight,
+notifications, last scan, provider reachability, invoice expiration, swaps
+needing attention. On a regtest machine, `packages/dotnet/docker/up.sh` then
+`e2e.sh` in the OpenReceive repository proves the whole path end to end, and
+that is the only situation where cloning the repository is the right move.
+
+## More documentation
+
+Fetch one when the moment comes. Each is raw markdown, so a plain GET is
+enough; drop the `.md` for the same page a person would read.
+
+- https://openreceive.org/guides/btcpay-reference.md — every setting, route, swap state, doctor probe and log event of the plugin
+- https://openreceive.org/guides/security.md — why receive-only is the only wallet credential
+- https://openreceive.org/guides/lightning-swap-connect.md — what an LSC code actually is
+- https://openreceive.org/guides/automated-swaps.md — provider states, and what turning swaps on commits a merchant to
+- https://openreceive.org/guides/swap-refunds.md — the refund states; the route back is BTCPay's own invoice checkout page here
+- https://openreceive.org/guides.md — the index, if what you need is not above
+
+Questions, or a problem with the plugin itself:
+https://openreceive.org/contact
+
+---
+
+## The quickstart, in full
+
+Inlined verbatim so this file needs no network access — follow it once Step 0
+passes. The page it comes from is https://openreceive.org/guides/quickstart-btcpay.
+
+## BTCPay Server quickstart
+
+Requires BTCPay Server ≥ 2.4.2.
+
+The OpenReceive plugin makes a receive-only NWC wallet the Lightning node of a
+BTCPay store. BTCPay mints every Lightning invoice in that wallet and records
+payments through its own settlement machinery. Optionally, payers can pay a
+BTCPay invoice with USDT, USDC, ETH or SOL through a Lightning Swap Connect
+provider; the swap settles into the same wallet. The store's internal node is
+never used.
+
+This is not the Node or Rails library. There are no hooks, no
+`openreceive_payments` table and no OpenReceive HTTP routes: BTCPay's
+invoices, checkout, webhooks and Greenfield API are the host.
+
+### 1. Prerequisites
+
+- A BTCPay Server, version 2.4.2 or later, on any network (mainnet, testnet,
+  signet, regtest). The wallet must be on the same network.
+- A receive-only NWC code for the wallet you want to receive into
+  ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
+  The code must grant `make_invoice` and `list_transactions` and must not
+  advertise any spend method. `lookup_invoice` is optional.
+- Optionally, a Lightning Swap Connect (LSC) code from a
+  [swap provider](https://openreceive.org/set_up_swap_provider), if payers
+  should be able to pay with USDT, USDC, ETH or SOL.
+
+### 2. Install the plugin
+
+In BTCPay, open **Server Settings → Plugins**, search the plugin directory
+for **OpenReceive**, click **Install**, and restart BTCPay when prompted.
+BTCPay creates the plugin's one table (`openreceive_swaps`, schema
+`BTCPayServer.Plugins.OpenReceive`) in its own Postgres at startup; nothing
+else is created.
+
+To build the plugin from source instead, follow
+[the .NET workspace README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/README.md).
+
+### 3. Connect the wallet
+
+Follow the plugin README's illustrated walkthrough:
+[OpenReceive for BTCPay Server](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/BTCPayServer.Plugins.OpenReceive/README.md).
+It opens the **OpenReceive** page in the store's sidebar, saves the
+receive-only NWC code, optionally saves the LSC code to turn swaps on, and
+creates a first test invoice. There is nothing else to configure: you never
+open BTCPay's Lightning node screen, and the plugin never reads the internal
+node.
+
+Saving fails closed if the wallet advertises a spend method such as
+`pay_invoice`. Mint a receive-only code instead; the override for a wallet
+that cannot is a deliberate, logged choice. Swaps raise the store's invoice
+expiration to 60 minutes when it is shorter, because a swap needs at least 45
+minutes of invoice life.
+
+### 4. Check it
+
+**Run a health check** on the OpenReceive page runs every probe in place:
+the connection, the wallet preflight, payment notifications, the last wallet
+scan, the swap provider and its assets, the invoice expiration, and swaps
+that need a human. Each failing probe carries a fix link.
+
+Every setting, Greenfield route, swap state, log event and probe is in the
+[BTCPay plugin reference](https://openreceive.org/guides/btcpay-reference.md), including what is
+unsupported by design: every send-side feature, top-up invoices, and a bare
+`nostr+walletconnect://` string in BTCPay's Lightning node screen.