openreceive-rails 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7ef5df95a3cc1af66502a65a1b130aad1a88ab8ff93dcd26b4e93a1d732dca2
-  data.tar.gz: 291e45e4efa083eee2345490086e97e757ae3009aa0f79ba3a7ef3ba55a04bb5
+  metadata.gz: 96a850e9b25d9797bff5f7b668b8e8bf26c891991058bf58ffd911c0abcdcbb4
+  data.tar.gz: 33d4e8872eb37baf2d77f0f47b5224dafa4851f056e43ff0c047f9b3e05ab647
 SHA512:
-  metadata.gz: 36a33f19c0791f0e127c7cb4bc6b746aa377a124d5e1c9cef9c553826416f6fb51383029c0b8ba1b0ad11e33e4b069e3156bff2d751adbafe0718825c99a9105
-  data.tar.gz: 18e1177d9a7974614eb8db63fe27c5414b21a0758c7e2f4f02d4e955970403217ebf6bbf3c94e1d7d840219ba99cdaf944f4bc0e64ad395fc7318937fef5e85f
+  metadata.gz: 2447535630f828c0185846df6f79b995ac0968c8a7a0e22ccf02104e3b9003333e3754476f65addb09823ae1678004639c8dfeb95e6f914f54c26fd610f575f0
+  data.tar.gz: c01e0905acbd634606783b0b6fe05eb16002238f7987cb92ac48c97da788f49a82b42242e82ca60d19624d359a6841583bf7a9caab73f2f8902c44f0a567a70d

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.3.3 - 2026-09-02
+
+### A missing migration says so, with the fix
+
+When the `openreceive_meta` table is absent, the engine now raises
+`OpenReceive::ConfigurationError` naming the exact commands —
+`bin/rails generate openreceive:install`, then `bin/rails db:migrate` — and
+linking the storage guide, instead of leaking a raw
+`ActiveRecord::StatementInvalid` from the first query. The check runs only on
+request-serving paths, so `db:migrate`, `db:prepare`, and the generator are
+unaffected, and a healed database is retried rather than remembered as broken.
+
+### NWC configuration errors reach Node parity
+
+A missing `NWC_URI` explains the receive-only requirement and links the
+get-a-code page (still starting with the pinned "Set NWC_URI"); a malformed
+one is framed as "set, but not a valid NWC code" with the parse reason and the
+same URL, instead of surfacing the bare parse error. `validate!` failures
+(authorize, amount_for, on_paid, rate limiting, opportunistic reconcile) each
+state their fix and link the owning guide, and the rate-limiting client-IP
+warning links the rate-limiting guide.
+
+### The gem carries the agent skills
+
+`skills/` ships in the gem — the integrate and debug playbooks for coding
+agents, kept byte-identical to the repository tree by
+`npm run generate:skills`.
+
 ## 0.3.2 - 2026-08-29
 
 No changes to this gem in 0.3.2. The release is the overpaid-deposit refund

data/app/models/open_receive_meta.rb

@@ -24,9 +24,24 @@ class OpenReceiveMeta < ActiveRecord::Base
   # written by a NEWER library must not be operated by this one (columns or
   # state transitions it does not know about). An unreadable or absent marker
   # means "not versioned" — the pre-versioned migrations could not seed a row —
-  # and is not a refusal. Mirrors the JS repository's assertSupportedSchema.
+  # and is not a refusal. A missing TABLE is different: that is diagnosable as
+  # "the install migration never ran here", and saying so beats the raw
+  # StatementInvalid the first payments query would raise a moment later.
+  # Mirrors the JS repository's assertSupportedSchema.
+  #
+  # Reached only from the request-serving paths (every OpenReceivePayment
+  # entry point and the reconcile gate) — never unconditionally at boot — so
+  # `db:migrate`, `db:prepare`, the install generator, and asset builds still
+  # run against an unmigrated database. A raise is not memoized: once the host
+  # runs the migration, the same process starts serving.
   def self.assert_supported_schema!
     @schema_version_checked ||= begin
+      unless table_exists?
+        raise OpenReceive::ConfigurationError,
+              "The openreceive_meta table does not exist — the OpenReceive tables have not been " \
+              "migrated in this database. Run `bin/rails generate openreceive:install`, then " \
+              "`bin/rails db:migrate`. https://openreceive.org/guides/storage.md"
+      end
       stored = stored_schema_version
       if !stored.nil? && stored > OpenReceive::Server::PAYMENTS_SCHEMA_VERSION
         raise OpenReceive::ConfigurationError,

data/lib/openreceive/configuration.rb

@@ -147,16 +147,23 @@ module OpenReceive
     end
 
     def validate!
-      raise ConfigurationError, "OpenReceive.config.authorize is required." if @authorize.nil?
+      if @authorize.nil?
+        raise ConfigurationError,
+              "OpenReceive.config.authorize is required — authentication belongs to the host. " \
+              "Set config.authorize in config/initializers/openreceive.rb to check the payer's " \
+              "session. https://openreceive.org/guides/authorization.md"
+      end
       if @rate_limiting && @rate_limit
         raise ConfigurationError,
-              "Set either OpenReceive.config.rate_limiting or a custom rate_limit hook, not both."
+              "Set either OpenReceive.config.rate_limiting or a custom rate_limit hook, not " \
+              "both: rate_limiting is the built-in per-IP limiter, rate_limit replaces it with " \
+              "your own policy. https://openreceive.org/guides/rate-limiting.md"
       end
       if @rate_limiting && advanced_hooks?
         raise ConfigurationError,
               "config.rate_limiting counts engine-owned OpenReceivePayment rows; with a custom " \
               "repository (resolve_checkout/on_checkout_created), pass a custom rate_limit hook " \
-              "backed by your own store instead."
+              "backed by your own store instead. https://openreceive.org/guides/rate-limiting.md"
       end
       if @opportunistic_reconcile && advanced_hooks?
         # Same fail-at-construction idiom as the JS handler: the default
@@ -166,19 +173,28 @@ module OpenReceive
               "config.opportunistic_reconcile (on by default) scans engine-owned " \
               "OpenReceivePayment rows through the shared openreceive_meta gate; with a custom " \
               "repository (resolve_checkout/on_checkout_created), set " \
-              "config.opportunistic_reconcile = false and run your own settlement worker."
+              "config.opportunistic_reconcile = false and run your own settlement worker. " \
+              "https://openreceive.org/guides/storage.md"
       end
       if @on_paid.nil?
-        raise ConfigurationError, "OpenReceive.config.on_paid is required to durably record settlement."
+        raise ConfigurationError,
+              "OpenReceive.config.on_paid is required to durably record settlement. Set " \
+              "config.on_paid to fulfill the order — it runs once, for the reference's first " \
+              "settled attempt. https://openreceive.org/guides/api-reference.md#openreceiveconfigure"
       end
       if @resolve_checkout.nil? != @on_checkout_created.nil?
         raise ConfigurationError,
-              "OpenReceive.config.resolve_checkout and on_checkout_created must be configured together (advanced mode)."
+              "OpenReceive.config.resolve_checkout and on_checkout_created must be configured " \
+              "together (advanced mode). Set both, or neither and use quickstart amount_for. " \
+              "https://openreceive.org/guides/api-reference.md#openreceiveconfigure"
       end
       if !advanced_hooks? && @amount_for.nil?
         raise ConfigurationError,
               "Set OpenReceive.config.amount_for (quickstart), " \
-              "or resolve_checkout and on_checkout_created (advanced)."
+              "or resolve_checkout and on_checkout_created (advanced). " \
+              "amount_for(reference) returns the amount to charge — e.g. { \"sats\" => 2100 } — " \
+              "or nil for an unknown reference. " \
+              "https://openreceive.org/guides/api-reference.md#openreceiveconfigure"
       end
       resolved_nwc_client
       true
@@ -234,7 +250,8 @@ module OpenReceive
             warned_unattributable = true
             rails_logger&.warn(
               "[openreceive] rate limiting is enabled but no client IP could be resolved; " \
-              "attempts from this request are not counted. Configure config.client_ip."
+              "attempts from this request are not counted. Configure config.client_ip. " \
+              "https://openreceive.org/guides/rate-limiting.md"
             )
           end
           next true
@@ -377,21 +394,52 @@ module OpenReceive
       return @nwc_client unless @nwc_client.nil?
 
       connection = @nwc || ENV["NWC_URI"]&.strip
-      if connection.nil? || connection.empty?
-        raise ConfigurationError, "Set NWC_URI, or configure OpenReceive.config.nwc/nwc_client explicitly."
-      end
+      raise ConfigurationError, missing_nwc_message if connection.nil? || connection.empty?
       return connection if connection.respond_to?(:make_invoice) || connection.respond_to?(:makeInvoice)
 
+      # Parse with the engine's own parser first, so a malformed code surfaces
+      # as a framed configuration error (what is wrong, the fix, the help URL)
+      # rather than a bare parse failure from whichever layer touched it first.
+      begin
+        OpenReceive.parse_nwc_uri(connection)
+      rescue OpenReceive::NwcUriParseError => e
+        raise ConfigurationError, invalid_nwc_message(e.message)
+      end
       OpenReceive::NwcRubyReceiveClient.new(
         client: build_nwc_ruby_client(connection), connection_uri: connection
       )
     end
 
+    # Mirrors the JS core formatMissingNwcMessage: what is missing, the
+    # concrete fix, and where to get a receive-only code.
+    def missing_nwc_message
+      [
+        "OpenReceive needs a receive-only NWC code to receive payments.",
+        "Set NWC_URI to your receive-only Nostr Wallet Connect connection string, " \
+        "or configure OpenReceive.config.nwc/nwc_client explicitly.",
+        "Get one here: #{OpenReceive::NWC_CODE_HELP_URL}"
+      ].join("\n")
+    end
+
+    # Mirrors the JS core formatInvalidNwcMessage; the subject names where the
+    # bad value came from so the operator knows which setting to fix.
+    def invalid_nwc_message(reason)
+      subject = @nwc.nil? ? "NWC_URI" : "OpenReceive.config.nwc"
+      [
+        "#{subject} is set, but it is not a valid NWC code.",
+        "Reason: #{reason}",
+        "Get a receive-only NWC code here: #{OpenReceive::NWC_CODE_HELP_URL}"
+      ].join("\n")
+    end
+
     def build_nwc_ruby_client(connection)
       require "nwc_ruby"
       ::NwcRuby::Client.from_uri(connection)
     rescue LoadError
-      raise ConfigurationError, "Install nwc-ruby or configure nwc_client."
+      raise ConfigurationError,
+            "Install nwc-ruby (add `gem \"nwc-ruby\"` to the Gemfile) or configure " \
+            "OpenReceive.config.nwc_client with your own NWC client. " \
+            "https://openreceive.org/guides/api-reference.md#openreceiveconfigure"
     end
   end
 

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.3.2"
+    VERSION = "0.3.3"
   end
 end

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

@@ -0,0 +1,88 @@
+---
+name: debug-openreceive-payment
+description: >
+  Diagnose a failing OpenReceive integration. Use when an OpenReceive-powered
+  checkout misbehaves: the server refuses to boot, checkout routes return 403,
+  404, 409, or 5xx, a paid invoice never settles, a swap refund seems
+  unreachable, or the checkout UI renders nothing.
+license: MIT
+---
+
+# Debug an OpenReceive payment
+
+Work top-down: configuration, then the request, then settlement. Every guide
+URL below is raw markdown — fetch it when the step needs it.
+
+## 1. Run the doctor first
+
+```sh
+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?
+```
+
+Each failing line states its own fix. `npx openreceive debug-report` prints the
+same diagnostics redacted, always exit 0 — safe to share.
+
+## 2. Boot failures
+
+| Symptom | Cause and fix |
+| --- | --- |
+| `MISSING_NWC` / "needs a receive-only NWC code" | `NWC_URI` is not in the server process env. A `.env` file alone is not enough — something must load it (`dotenv/config`, Next auto-load). Get a code: https://openreceive.org/get_a_nwc_code_to_receive_payments |
+| `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 |
+| "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
+
+| Status | Meaning | Where to look |
+| --- | --- | --- |
+| 403 FORBIDDEN | Your own `authorize` hook denied it, or the request looked cross-site. Check the session/cookie actually reaches the checkout routes. https://openreceive.org/guides/authorization.md |
+| 404 NOT_FOUND | `amountFor` returned `null` (unknown reference), or the `payment_hash` does not belong to that reference. |
+| 409 CONFLICT | **Normal state, not a bug**: the reference already settled, or an unpaid checkout for that method is already live. Show it as order state; never retry-loop. |
+| 503 retryable | The host hook failed while persisting the attempt (instructions withheld), or the wallet is unavailable. Read the server log for the underlying error. |
+| Framework 404 / HTML error page | The router is not mounted, or mounted at a different prefix than the UI's `prefix` prop. `doctor --url` distinguishes these. |
+
+## 4. Paid but never settles
+
+- Settlement is opportunistic: any OpenReceive request runs one reconcile pass
+  through a durable gate (min 2s 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.
+- 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.
+- `onPaid` runs once per reference, first settled attempt only, inside the
+  settlement transaction. If your fulfillment did not run, check whether the
+  guarded `UPDATE … WHERE` matched zero rows (already transitioned).
+  https://openreceive.org/guides/storage.md
+
+## 5. Swaps and refunds
+
+- A deposit that arrives short or late becomes `refund_required`; the payer
+  claims it on a second visit. That needs a per-order URL you serve
+  (`/checkout/:reference`, `syncUrl` on the drop-ins). Keep the
+  `payment_hash`: `POST /swaps/status` reopens the attempt with no expiry
+  window, while re-picking the coin mints a new deposit after ~30 minutes.
+- Refunds exist only for swap deposits from `refund_required`. There is **no
+  Lightning refund** — the wallet cannot spend. Do not chase one.
+  https://openreceive.org/guides/swap-refunds.md
+
+## 6. Checkout UI shows nothing
+
+- 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).
+- "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
+
+## Still stuck
+
+The full route/option/error reference:
+https://openreceive.org/guides/api-reference.md · machine-readable contract:
+https://openreceive.org/openapi.yaml · library bug reports:
+https://openreceive.org/contact

data/skills/integrate-openreceive/SKILL.md

@@ -0,0 +1,116 @@
+---
+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).
+license: MIT
+---
+
+# Integrate OpenReceive
+
+OpenReceive is a payment library that runs inside the application you are
+editing. It mounts HTTP routes there, issues Lightning invoices against a
+wallet the merchant already controls, and calls back into your code when one
+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`).
+
+## Pick the stack, then follow its directions
+
+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)
+   - Rails: [references/rails.md](references/rails.md)
+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`.
+
+## The three server objects
+
+| Object | Built with | Talks to |
+| --- | --- | --- |
+| Wallet client | `createOpenReceive()` | the merchant's wallet — mints invoices, reads settlement, holds the NWC code |
+| Host | `createHost()` | your database — your hooks plus the `openreceive_payments` table |
+| HTTP routes | `openReceiveExpress()` / `openReceiveFastify()` / `openReceiveNext()` / the Rails engine | the browser — mounted at `/openreceive` by default |
+
+The quickstart's one-factory form (`openReceiveExpress({ wallet, storage,
+amountFor, authorize })`) builds all three; compose them separately only for a
+shared wallet client or a custom repository. The checkout UI
+(`<Checkout reference={...} prefix="/openreceive" />`) is the optional fourth
+piece.
+
+## The host contract: authorize, amountFor, onPaid
+
+Your application keeps orders, users, prices, and fulfillment. Three hooks are
+the entire bridge — wire them to the models this app already has, never to
+copied demo models:
+
+- `amountFor(reference)` — the authoritative price, read from your own data.
+  Return `{ currency, value, description }` with `value` a **decimal string**
+  (never a float, never payer input), or `null` when there is nothing to pay
+  for. The `reference` is your order id: one per thing you fulfill, created
+  before checkout, kept across retries, never reused.
+- `authorize({ action, request, resource })` — your own access check, run on
+  every request. `resource.reference` is a claim the payer made, not proof;
+  read a real session.
+- `onPaid({ reference, paidAt, query })` — fulfillment, run once per reference
+  inside the settlement transaction, only for the first settled attempt. Use
+  the provided `query`, not your ORM's other connection, and guard the
+  transition (`UPDATE … WHERE state = 'awaiting_payment'`).
+
+## 409 is a state, not a failure
+
+The library serializes attempts per reference. A create that returns **409
+CONFLICT** is normal checkout flow: the reference already settled, or an unpaid
+checkout for that payment method is already in progress. Surface it as order
+state; do not retry-loop it, and do not build an idempotency store around it —
+that serialization is the library's job. (A hook failure while persisting an
+attempt is a **503 retryable**, deliberately distinct.)
+
+## Secrets
+
+`NWC_URI` and `LSC_URI_*` are server-only. Never put them in browser code,
+logs, assets, or tests. Boot fails closed if the NWC code advertises spend
+methods such as `pay_invoice` — mint a receive-only code
+(https://openreceive.org/get_a_nwc_code_to_receive_payments) instead of
+overriding.
+
+## Database tables
+
+```sh
+npx openreceive scaffold payments --orm prisma   # or drizzle | typeorm | sequelize | knex
+```
+
+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.
+
+## Verify, and test without a real wallet
+
+`npx openreceive doctor` checks the configuration and says what to fix.
+
+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
+
+## Deeper documentation
+
+Fetch on demand — each URL is raw markdown:
+https://openreceive.org/guides/authorization.md ·
+https://openreceive.org/guides/storage.md ·
+https://openreceive.org/guides/api-reference.md ·
+https://openreceive.org/guides/security.md ·
+https://openreceive.org/openapi.yaml (the normative HTTP contract) ·
+https://openreceive.org/llms.txt (the full index)