openreceive-rails 0.4.10 → 0.4.13

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.13.
 
 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
@@ -31,62 +31,90 @@ The one required credential is a receive-only NWC code (Nostr Wallet Connect):
 a string from the merchant's wallet that can create invoices and read their
 status, and cannot spend. A swap provider (an "LSC" code) optionally lets the
 payer send USDT, USDC, ETH or SOL instead, converted into that same
-Lightning payment. You supply those credentials and three hooks — `authorize`, `amountFor`,
+Lightning payment. Step 0 collects those credentials from the user; you write three hooks — `authorize`, `amountFor`,
 `onPaid`;
 OpenReceive supplies invoices, polling, settlement and the checkout UI. It never
 owns orders, users, prices, or fulfillment.
 
-## Step 0 — check the environment before you write code
-
-Do this before installing packages or editing files.
-
-1. Look for `NWC_URI` in this app's server environment — `.env`, the process
-   env, the deploy config, whatever this app already uses. If the app runs in a
-   container the value is in none of those: ask the running process
-   (`docker exec <container> printenv NWC_URI`), because finding the NAME in a
-   compose file proves nothing about the value. Never print or echo the value
-   itself; only report whether it is set. Check for `LSC_URI_PRIMARY` in the
-   same pass.
-2. If BOTH are already set — the common case in an existing app — say so and go
-   straight to the quickstart. Steps 3 and 4 are for an environment that is
-   missing one; do not stop to ask about altcoins that are already configured.
-   If only `NWC_URI` is set, Bitcoin already works: continue, and raise the
-   altcoin question at step 4 rather than blocking on it.
-3. If `NWC_URI` is missing or empty, stop and tell the user exactly what to
-   create:
-
-   > OpenReceive cannot issue an invoice without a receive-only NWC code. Get
-   > one at https://openreceive.org/get_a_nwc_code_to_receive_payments, then
-   > put `NWC_URI=<the code>` in this app's server environment — for most apps
-   > that is a `.env` file in the project root — and tell me when it's set.
-
-   Wait for the user before wiring OpenReceive; do not invent a placeholder
-   value. Waiting is not idleness: you may write `.env.example` with the
-   variable NAMES only (`NWC_URI=`, `LSC_URI_PRIMARY=`) so the merchant has a
-   file to copy, and keep building the parts of the host that do not touch
-   OpenReceive — the order model, the cart, the routes. The stop guards the
-   credential, not the rest of the app.
-4. If `LSC_URI_PRIMARY` was not already set, ask the user: "Do you want to
-   accept altcoins and stablecoins (USDT, USDC, ETH, SOL) as well as
-   Bitcoin?"
-
-   - Yes → send them to https://openreceive.org/set_up_swap_provider for a
-     swap-provider (LSC) code, to set as `LSC_URI_PRIMARY` in the same server
-     environment. Do NOT wait for it: no application code reads the value, so
-     the integration is identical with or without it — the library picks it up
-     from the environment and swaps switch on. What a yes DOES change is the
-     refund route back (the swap non-negotiable below): build it as part of
-     this integration, not when the code arrives.
-   - No → skip it. Bitcoin over Lightning works with `NWC_URI` alone, and you
-     can add a swap provider later without changing application code.
-5. Check the environment again and confirm `NWC_URI` is present.
-   `LSC_URI_PRIMARY` may land later; swaps stay off until it does, and no code
-   changes when it arrives.
-6. If OpenReceive is ALREADY installed here, check the installed versions of
-   `@openreceive/node` and `@openreceive/browser` against the release named at
-   the top of this file. The headless display models below do not exist in
-   older versions, and the first tile click throws with nothing saying why.
-   Upgrade first.
+## Step 0 — ask for the two codes, one question at a time
+
+Before anything else, look at one file: the project's `.env`, if it exists.
+Read it only far enough to see whether `NWC_URI` and `LSC_URI_PRIMARY` are
+there and non-empty, and never print the values. A code that is already
+set is not asked for again; if both are set, skip to step 5
+(making the server load the file), then the quickstart.
+
+Otherwise your next action is a question to the user. Do not install packages,
+edit the app, write `.env.example`, or search anywhere else before asking
+it. Do not read deploy config (compose files, platform secrets), Docker containers, or process environments, and never run
+`printenv`. A new shop has neither code yet: hunting for one burns the turn and
+can leak other secrets into the transcript.
+
+Two server-only URIs are needed before the quickstart:
+
+- `NWC_URI` — a receive-only Nostr Wallet Connect code,
+  `nostr+walletconnect://…`. Required for Bitcoin.
+- `LSC_URI_PRIMARY` — a Lightning Swap Connect URI,
+  `lightning+swapconnect://…`. Required for USDT, USDC, ETH and SOL. Skip it
+  only when the user says they want Bitcoin alone.
+
+The user never edits an environment file. They paste each code into the chat;
+you store it. Ask one question per message.
+
+1. **First message — the NWC code, and nothing else.** Ask for it and walk them
+   through getting it:
+
+   > To receive payments I need a receive-only wallet code. In Rizful: open
+   > the menu, tap NWC, choose Receive-only NWC code, and tap Copy
+   > (https://openreceive.org/get_a_nwc_code_to_receive_payments). If you would
+   > rather run your own wallet, Alby Hub works too: Connections → Add
+   > Connection → Read Only. Paste the code here and I will store it.
+
+   Do not mention `.env`, exports, or "tell me when it's set".
+2. **When they paste it.** If it does not start with `nostr+walletconnect://`,
+   ask them to copy the receive-only code again. Otherwise write
+   `NWC_URI=<paste>` into the project's `.env`, creating the file if needed.
+   Make sure `.gitignore` covers `.env` (and `.dockerignore`, if the app has
+   one). Never echo the value, commit it, or put it in client code. Reply only
+   that it is saved, then ask the next question.
+3. **Second message — swaps.** If the user already asked for stablecoins or
+   altcoins, skip the yes/no and go straight to the walkthrough. Otherwise ask
+   whether payers should also be able to pay with USDT, USDC, ETH or SOL. The
+   walkthrough:
+
+   > Go to https://lightning-swap.com, sign in for API keys, create a key, and
+   > copy the whole URI (https://openreceive.org/set_up_swap_provider). Paste
+   > it here and I will store it — or say "Bitcoin only" and I will continue
+   > without it.
+
+   Mention FixedFloat only if they already use it.
+4. **When they paste it.** If it does not start with
+   `lightning+swapconnect://`, ask them to copy it again. Otherwise add
+   `LSC_URI_PRIMARY=<paste>` to the same `.env`, without echoing it. Swaps
+   are now on, so build the refund route back (the swap non-negotiable below) as
+   part of this integration. If they chose Bitcoin only, leave
+   `LSC_URI_PRIMARY` unset and skip that route.
+5. **Make the server load the file — yourself.** OpenReceive reads
+   `process.env`, and a `.env` file on disk is not in it. Put
+   `import "dotenv/config";` at the top of the server entry, as the quickstart
+   does. When the app is started with Docker Compose, give the service
+   `env_file: .env`. Restart the server after writing the file.
+
+Do not invent placeholder URIs. Start the quickstart only once `NWC_URI` is
+saved and `LSC_URI_PRIMARY` is saved or explicitly declined. The first boot
+runs the receive-only preflight: if it reports spend methods such as
+`pay_invoice`, remove `NWC_URI` from `.env` and ask for a receive-only code
+again. Never set the spend-capable override to get past it.
+
+### Upgrading an existing install
+
+This is not the opening move of a new integration. When OpenReceive is ALREADY
+installed here, `npx openreceive doctor` reports every credential as set/unset
+(never the value) and probes the wallet. Check the installed
+`@openreceive/node` and `@openreceive/browser` against the release named at the
+top of this file: the headless display models below do not exist in older
+versions, and the first tile click throws with nothing saying why. Upgrade
+first.
 
 Only then start the quickstart.
 
@@ -104,7 +132,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -276,6 +304,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -293,11 +323,11 @@ Express + React. Requires Node ≥ 22.
 npm install @openreceive/express @openreceive/react
 ```
 
-Install the adapter for your server and the UI package for your frontend; the
+Install the adapter for your server and the UI package for your frontend. The
 wallet client, HTTP handler, and contracts come along as dependencies. The
-`openreceive` package is the CLI only — `npx openreceive …` below needs no
-install. Different stack? Swap the two packages; the rest of this guide is
-identical.
+`openreceive` package is only the CLI, and `npx openreceive …` below needs no
+install. On a different stack, swap the two packages; the rest of this guide
+stays the same.
 
 |          | Packages                                                                                                                      |
 | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
@@ -307,14 +337,16 @@ identical.
 Fastify: [quickstart-fastify.md](https://openreceive.org/guides/quickstart-fastify.md) · Next.js:
 [quickstart-next.md](https://openreceive.org/guides/quickstart-next.md). This page is the Express one.
 
-On a fresh project, also install what this guide assumes is already there: the
-framework and an env loader (`npm install express dotenv`), plus your ORM
-before step 2 (`npm install prisma @prisma/client` on the Prisma path) —
-`openreceive scaffold` emits files for the ORM you name but never installs it.
+On a fresh project, also install what this guide assumes you already have: the
+framework and an env loader (`npm install express dotenv`). Install your ORM
+before step 2 too (`npm install prisma @prisma/client` on the Prisma path).
+`openreceive scaffold` emits files for the ORM you name, but it never installs
+that ORM.
 
-npm environments that run with `ignore-scripts` (some editor sandboxes) skip
-Prisma's engine download and esbuild's binary postinstall, so a typecheck or
-build that fails only there is environmental, not a code problem.
+Some editor sandboxes run npm with `ignore-scripts`. That setting skips
+Prisma's engine download and esbuild's binary postinstall. If a typecheck or
+build fails only in such an environment, the environment is the cause, not
+your code.
 
 ### 2. Migrate the payment tables
 
@@ -322,19 +354,19 @@ build that fails only there is environmental, not a code problem.
 npx openreceive scaffold payments --orm prisma   # or drizzle | typeorm | sequelize | knex
 ```
 
-`openreceive scaffold payments` emits one schema/migration file for your ORM
-and a wiring guide. It never touches a database.
+`openreceive scaffold payments` writes one schema or migration file for your
+ORM, plus a wiring guide. It never touches a database.
 → [openreceive scaffold payments](https://openreceive.org/guides/api-reference.md#openreceive-scaffold-payments)
 
-Then run the emitted migration through your normal workflow (for example
-`npx prisma migrate dev`). OpenReceive owns the tables' logic at runtime; there
-is nothing else to generate. Details:
+Then run the generated migration the way you normally do (for example
+`npx prisma migrate dev`). OpenReceive runs the tables' logic at runtime, so
+there is nothing else to generate. Details:
 [Payment storage](https://openreceive.org/guides/storage.md), [Node ORM recipes](https://openreceive.org/guides/node-orms.md).
 
-No ORM? A bare driver handle (`pg`, `node:sqlite`, `better-sqlite3`) is a
-supported `db` in step 4, and there is no scaffold flavor for it — execute the
-same DDL once yourself with `paymentsSchemaSql(dialect)` from
-`@openreceive/http` instead of scaffolding.
+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`.
 
 ### 3. Add wallet credentials
 
@@ -347,25 +379,27 @@ LSC_URI_BACKUP=
 ```
 
 1. Get a receive-only NWC code from a compatible wallet
-   ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments))
-   → `NWC_URI`.
-2. Optionally set up a [swap provider](https://openreceive.org/set_up_swap_provider)
-   → `LSC_URI_PRIMARY` (and `LSC_URI_BACKUP` if you have one).
+   ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
+   Put it in `NWC_URI`.
+2. Optional: set up a [swap provider](https://openreceive.org/set_up_swap_provider).
+   Put its connection string in `LSC_URI_PRIMARY`, and a second one in
+   `LSC_URI_BACKUP` if you have one.
 
-Never put these values in browser code. Your application refuses to start if
-the NWC code also advertises spend methods such as `pay_invoice`; mint a
-receive-only code ([Security](https://openreceive.org/guides/security.md)).
+Never put these values in browser code. Your app refuses to start if the NWC
+code also advertises spend methods such as `pay_invoice`. Create a
+receive-only code instead ([Security](https://openreceive.org/guides/security.md)).
 
-OpenReceive reads `process.env`; creating a `.env` file is not enough on its
-own. How that file (or production secrets) get into the process —
-`dotenv` on Express/Fastify, Next.js auto-load, secret managers in
-production — is on [Environment variables](https://openreceive.org/guides/environment-variables.md).
+OpenReceive reads `process.env`, so creating a `.env` file is not enough on
+its own. [Environment variables](https://openreceive.org/guides/environment-variables.md) explains how that
+file or your production secrets get into the process: `dotenv` on
+Express/Fastify, auto-load on Next.js, and secret managers in production.
 
 ### 4. Wire OpenReceive
 
-One factory: your hooks plus a database handle. The adapter builds the
-wallet client and the host; there is no background reconciler —
-settlement piggybacks on requests through the durable gate.
+One factory call takes your hooks and a database handle. The adapter builds
+the wallet client and the host. There is no background reconciler, meaning no job that checks pending
+payments on a timer. Settlement runs during normal requests instead, through
+the durable reconcile gate.
 
 ```ts
 import "dotenv/config"; // loads .env into process.env; nothing else does
@@ -442,25 +476,34 @@ An optional worker, `startNotificationWorker({ service, host })`, listens for
 wallet payment notifications so settlement does not wait for the next page
 load. → [startNotificationWorker](https://openreceive.org/guides/api-reference.md#startnotificationworker)
 
-Composing the pieces yourself (`createOpenReceive` + `createHost`) is
-supported when you need a shared wallet client or a custom repository.
+You can also compose the pieces yourself (`createOpenReceive` + `createHost`)
+when you need a shared wallet client or a custom repository.
 → [createOpenReceive](https://openreceive.org/guides/api-reference.md#createopenreceive) ·
 [createHost](https://openreceive.org/guides/api-reference.md#createhost)
 
-Your app also needs an ordinary order-creation route that validates the cart,
-prices with exact decimal math, and returns the order id the page will pass as
-the `reference`. OpenReceive never prices from payer input.
+Your app also needs an ordinary route that creates the order. It validates the
+cart, computes the price with exact decimal math, and returns the order id.
+The page passes that id as the `reference`. OpenReceive never takes a price
+from payer input.
+
+The `reference` is a string you choose, and it identifies what gets fulfilled.
+Use your order id. Make it:
+
+- one per thing you fulfill,
+- created before checkout,
+- kept across retries,
+- never reused.
 
-The `reference` is a string you choose, and it is the fulfillment identity:
-your order id — one per thing you fulfill, created before checkout, kept
-across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
-settled is refused with 409, and a fresh id per page load lets one order be
-paid twice.
+OpenReceive never looks inside the `reference`, but it relies on it:
+
+- `onPaid` commits fulfillment once per reference.
+- A new checkout under a reference that already settled is refused with 409.
+- A fresh id on every page load would let one order be paid twice.
 
 Naming boundary: TypeScript APIs use camelCase fields (`paymentHash`,
-`amountMsats`); everything on the wire — the mounted HTTP routes and the
-browser snapshots — is snake_case (`payment_hash`, `amount_msats`).
+`amountMsats`). Everything on the wire is snake_case (`payment_hash`,
+`amount_msats`). The wire means the mounted HTTP routes and the browser
+snapshots.
 
 ### 5. Render checkout
 
@@ -471,45 +514,51 @@ import "@openreceive/react/styles.css";
 <Checkout reference={order.id} prefix="/openreceive" />;
 ```
 
-The checkout renders, polls, and settles itself. The compiled `styles.css`
-sheets (`@openreceive/react`, `@openreceive/elements`) are self-contained — a
-plain `<link rel="stylesheet">` works with no build step — and scoped: every
+The checkout renders, polls, and settles itself.
+
+`@openreceive/react` and `@openreceive/elements` each ship a compiled
+`styles.css`. Each sheet is self-contained, so a plain
+`<link rel="stylesheet">` works with no build step. Each is also scoped: every
 rule applies only inside what OpenReceive renders.
 
-Serve the compiled `styles.css` without Tailwind processing: import it from
-JavaScript (with a CSS-capable bundler) or use a plain `<link rel="stylesheet">`.
-Do not `@import` it into the host Tailwind entry. Its zero-specificity rules
-allow host styles to override checkout styles; scoping does not prevent that.
+Serve the compiled `styles.css` without Tailwind processing. Import it from
+JavaScript if your bundler handles CSS, or use a plain
+`<link rel="stylesheet">`. Do not `@import` it into your app's Tailwind entry.
+Its rules have zero specificity, so your page's styles can override checkout
+styles. Scoping does not prevent that.
 
-`<Checkout>` is complete as rendered: it already shows the `description` from
+`<Checkout>` is complete as rendered. It already shows the `description` from
 `amountFor` and the collapsed transaction-details panel. Do not build a custom
-UI to satisfy those rules — they only become your job if you replace the
-drop-in ([Checkout UX](https://openreceive.org/guides/checkout-ux.md)).
+UI to show them. The display rules for them become your job only if you
+replace the drop-in component ([Checkout UX](https://openreceive.org/guides/checkout-ux.md)).
 
-Match the host page's theme: by default the checkout follows the payer's
-stored choice, then the system scheme. If this page is always one theme, lock
-it — `<Checkout theme="dark" … />` (`theme` attribute on the custom element) —
-so a white card never lands on a dark page. The checkout is styled by CSS
-variables under `data-theme`; [Frontend checkout](https://openreceive.org/guides/frontend-checkout.md) has
-the knobs.
+Match the host page's theme. By default the checkout follows the payer's
+stored choice, then the system color scheme. If this page always uses one
+theme, lock it with `<Checkout theme="dark" … />`. On the custom element, set
+the `theme` attribute. Locking the theme keeps a white card off a dark page.
+CSS variables under `data-theme` style the checkout.
+[Frontend checkout](https://openreceive.org/guides/frontend-checkout.md) lists the settings you can change.
 
 Everything the checkout draws ships inside the JavaScript: the payment-method
-icons, the wallet logos and the pay tutorials. There is no image file to copy
-or serve and no asset option to set. Deploy your normal JavaScript and CSS
+icons, the wallet logos, and the pay tutorials. There is no image file to copy
+or serve, and no asset option to set. Deploy your normal JavaScript and CSS
 build output, including any generated JavaScript chunks. Bundlers with code
-splitting can defer tutorial screenshots until first open; single-file builds
-(including the standalone checkout) include them upfront. If your
-Content-Security-Policy has a strict `img-src`, allow `data:`
+splitting can wait to load tutorial screenshots until a tutorial first opens.
+Single-file builds, including the standalone checkout, include them from the
+start. If your Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
-That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+That is the whole loop. Your server owns the price and the order. The payer
+gets an invoice. `onPaid` runs inside the settlement transaction. If that
+transaction rolls back, the callback may run again. For delivery to outside
+systems, use an outbox in your app: record the message in the transaction and
+send it after commit.
 
-A runnable illustration of this boundary — not a template to copy models from —
-is Buy a Button
+Buy a Button is a runnable illustration of this boundary
 (`examples/buttons/server/node-express`).
-It has products, visitors, and orders, with the three hooks as the only bridge.
-Map that shape onto the models in THIS app.
+It is not a template to copy models from. It has products, visitors, and
+orders, and the three hooks are the only bridge to OpenReceive. Map that shape
+onto the models in THIS app.
 
 ### 6. Verify
 
@@ -517,16 +566,17 @@ Map that shape onto the models in THIS app.
 npx openreceive doctor
 ```
 
-`openreceive doctor` checks Node, `NWC_URI`, and swap-provider configuration,
-and probes the wallet relay to confirm the code is receive-only. Add
-`--db <file-or-url>` to confirm the migration ran, and
-`--url http://localhost:3000` to confirm the routes are mounted; every failing
+`openreceive doctor` checks Node, `NWC_URI`, and the swap-provider
+configuration. It also probes the wallet relay to confirm the code is
+receive-only. Add `--db <file-or-url>` to confirm the migration ran. Add
+`--url http://localhost:3000` to confirm the routes are mounted. Every failing
 line states its own fix.
 → [openreceive doctor](https://openreceive.org/guides/api-reference.md#openreceive-doctor)
 
-Then open the checkout in a browser, confirm the payment-method icons and
-wallet logos render, and open a wallet's pay tutorial to check its screenshots.
-If an image is missing, inspect the console for CSP violations and the Network
-panel for failed JavaScript chunks. Allow `data:` in `img-src` and deploy the
-complete build output. Do not add image routes, copy package source images, or
-use registry `icon_path` / tutorial `path` keys as browser URLs.
+Then open the checkout in a browser. Confirm the payment-method icons and
+wallet logos render. Open a wallet's pay tutorial to check its screenshots.
+If an image is missing, look in the console for CSP violations and in the
+Network panel for failed JavaScript chunks. To fix it, allow `data:` in
+`img-src` and deploy the complete build output. Do not add image routes or
+copy package source images. Do not use registry `icon_path` or tutorial
+`path` keys as browser URLs.