openreceive 0.4.29 → 0.4.31

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/nestjs/full.md
 - Do not suggest rotating or revoking a code because it was pasted here.
 - Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
 
-These directions describe OpenReceive 0.4.29.
+These directions describe OpenReceive 0.4.31.
 
 Add OpenReceive to a NestJS application — the app you are already working in,
 on Nest's default Express platform. You do not need a copy of the OpenReceive
@@ -447,13 +447,12 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/api-reference.md — every route, option and error code
 - https://openreceive.org/guides/custom-checkout-route.md — advanced: replacing the shipped adapter's routes with your own
 - https://openreceive.org/guides/react-material-ui-recipe.md — a worked custom UI on a component library
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
 - https://openreceive.org/guides.md — the index, if what you need is not above
 
 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

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/next/full.md
 - Do not suggest rotating or revoking a code because it was pasted here.
 - Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
 
-These directions describe OpenReceive 0.4.29.
+These directions describe OpenReceive 0.4.31.
 
 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
@@ -438,13 +438,12 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/react-material-ui-recipe.md — a worked custom UI on a component library
 - https://openreceive.org/guides/tanstack-start-recipe.md — the same handler as a TanStack Start server route, if this app is TanStack Start after all
 - https://openreceive.org/guides/sveltekit-recipe.md, https://openreceive.org/guides/nuxt-recipe.md, https://openreceive.org/guides/astro-recipe.md and https://openreceive.org/guides/react-router-recipe.md — the same handler as a SvelteKit, Nuxt, Astro or React Router route, if this app is one of those
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
 - https://openreceive.org/guides.md — the index, if what you need is not above
 
 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
@@ -473,8 +472,8 @@ stays the same.
 | Server   | `@openreceive/next`, `@openreceive/express`, `@openreceive/fastify`                                                           |
 | Frontend | `@openreceive/react`, `@openreceive/vue`, `@openreceive/svelte`, `@openreceive/angular`, `@openreceive/elements` (plain HTML) |
 
-Express: [quickstart-node.md](https://openreceive.org/guides/quickstart-node.md) · Fastify:
-[quickstart-fastify.md](https://openreceive.org/guides/quickstart-fastify.md). This page is the Next.js one.
+Express: [Express quickstart](https://openreceive.org/guides/quickstart-node.md) · Fastify:
+[Fastify quickstart](https://openreceive.org/guides/quickstart-fastify.md). This page is the Next.js one.
 An agent given the Express guide goes wrong on Next.js in three places: Next
 needs no `dotenv`, no `app.use`, and it needs a client component for the
 checkout.

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/node/full.md
 - Do not suggest rotating or revoking a code because it was pasted here.
 - Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
 
-These directions describe OpenReceive 0.4.29.
+These directions describe OpenReceive 0.4.31.
 
 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
@@ -428,13 +428,12 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/custom-checkout-route.md — advanced: replacing the shipped adapter's routes with your own
 - https://openreceive.org/guides/react-material-ui-recipe.md — a worked custom UI on a component library
 - https://openreceive.org/guides/sveltekit-recipe.md, https://openreceive.org/guides/nuxt-recipe.md, https://openreceive.org/guides/astro-recipe.md and https://openreceive.org/guides/react-router-recipe.md — the same handler as a SvelteKit, Nuxt, Astro or React Router route, if this app is one of those
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
 - https://openreceive.org/guides.md — the index, if what you need is not above
 
 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
@@ -463,8 +462,8 @@ stays the same.
 | Server   | `@openreceive/express`, `@openreceive/fastify`, `@openreceive/next`                                                           |
 | Frontend | `@openreceive/react`, `@openreceive/vue`, `@openreceive/svelte`, `@openreceive/angular`, `@openreceive/elements` (plain HTML) |
 
-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.
+Fastify: [Fastify quickstart](https://openreceive.org/guides/quickstart-fastify.md) · Next.js:
+[Next.js quickstart](https://openreceive.org/guides/quickstart-next.md). This page is the Express one.
 
 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

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Nuxt)
 
 ```sh
-# READ THIS FIRST: this file is 33 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 34 KB and a summary drops required steps. Download it whole:
 curl -fsSL https://openreceive.org/agent-directions/nuxt/full.md
 # Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
 ```
@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/nuxt/full.md
 - Do not suggest rotating or revoking a code because it was pasted here.
 - Start the quickstart only once the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
 
-These directions describe OpenReceive 0.4.29.
+These directions describe OpenReceive 0.4.31.
 
 Add OpenReceive to a Nuxt application — the app you are already working in,
 on Nitro's `node-server` preset. OpenReceive ships no Nuxt package: the
@@ -419,13 +419,12 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/custom-checkout-route.md — advanced: replacing the shipped adapter's routes with your own
 - https://openreceive.org/guides/react-material-ui-recipe.md — a worked custom UI on a component library
 - https://openreceive.org/guides/quickstart-next.md — each hook explained step by step, on Next.js; they are the same here
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
 - https://openreceive.org/guides.md — the index, if what you need is not above
 
 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
@@ -464,7 +463,7 @@ npm install @openreceive/http @openreceive/vue pg
 On Node, with Nitro's default `node-server` preset. The wallet connection and
 your database driver need Node, so the route cannot run on an edge runtime.
 The Vercel, Netlify and AWS Lambda presets deploy Node functions: read
-Bitcoin checkout on serverless hosts first. For
+[Bitcoin checkout on serverless hosts](https://openreceive.org/guides/serverless.md) first. For
 Cloudflare Workers, the [TanStack Start recipe](https://openreceive.org/guides/tanstack-start-recipe.md#where-it-runs)
 explains what a Worker needs. This recipe was not run on those hosts.
 
@@ -529,24 +528,24 @@ export default defineEventHandler((event) => handleOpenReceive(event));
 Put it in `server/routes/`, not `server/api/`, which would add `/api` to
 the path. `native` is the request's `H3Event`, so `authorize` can check the
 session your app already has: its cookies, or the user your session module
-reads from the event. The Next.js quickstart
+reads from the event. The [Next.js quickstart](https://openreceive.org/guides/quickstart-next.md)
 explains each hook. They are the same here.
 
 One stack serves the whole server process. `getRequestIP` returns the socket
 address. Behind your own reverse proxy, `{ xForwardedFor: true }` reads the
 first address in `x-forwarded-for`, which is safe only when that proxy sets
-the header (Rate limiting).
+the header ([Rate limiting](https://openreceive.org/guides/rate-limiting.md)).
 
 ### Your database
 
 `db` is a `pg` Pool, `node:sqlite` or `better-sqlite3`, or one of the
-adapters in Node ORM recipes. With Drizzle, pass
+adapters in [Node ORM recipes](https://openreceive.org/guides/node-orms.md). With Drizzle, pass
 the `pg` Pool underneath it.
 
 Create OpenReceive's two tables with your migrations
 (`npx openreceive scaffold payments --orm <your orm>`), or run
 `paymentsSchemaSql("postgres")` from `@openreceive/http` once. It is
-idempotent. See Payment storage.
+idempotent. See [Payment storage](https://openreceive.org/guides/storage.md).
 
 ### The checkout page
 
@@ -585,7 +584,7 @@ if (error.value) {
 The page renders on the server and starts the checkout in the browser. The
 payer picks Bitcoin and gets the invoice. Keep it at the order's own URL: a
 payer with a swap deposit in flight comes back to it
-(Swap refunds).
+([Swap refunds](https://openreceive.org/guides/swap-refunds.md)).
 
 ### Settings
 

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

@@ -0,0 +1,446 @@
+This is the full file; follow it from Step 0.
+
+# OpenReceive agent directions (Odoo)
+
+```sh
+# READ THIS FIRST: this file is 23 KB and a summary drops required steps. Download it whole:
+curl -fsSL https://openreceive.org/agent-directions/odoo/full.md
+# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before installing or editing anything, ask the user for a receive-only NWC code. One question per message.
+- Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
+- The user only pastes codes into this chat. Never ask them to run a command, edit a file or use an admin page.
+- Store each code yourself as Step 2 says. Never put a code in a shell command.
+- Do not suggest rotating or revoking a code because it was pasted here.
+- Setup is done only when the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
+
+These directions describe OpenReceive 0.4.31.
+
+Install and configure the OpenReceive payment provider in the Odoo you are
+working in. Preserve its website, customers, products, orders, invoices and
+prices. The module is a ZIP; its Python side is the `openreceive` package from
+PyPI at the same version. Do not install anything else into Odoo, do not
+change Odoo's own files, and do not clone the OpenReceive repository.
+
+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
+customers pay with USDT, USDC, ETH or SOL instead; the provider converts the
+payment to BTC over Lightning in the merchant's connected wallet. Available
+assets and networks depend on the provider.
+
+The module needs Odoo 19 or 20. With Odoo's official Docker image, run Odoo's
+commands through the image's entrypoint, which adds the database connection:
+`docker compose exec -T odoo /entrypoint.sh odoo …` (`-T` passes stdin
+through; use the Odoo service's own name). `-d <database>` names the
+database; `docker compose exec -T db psql -U <user> -l` lists them when you
+do not know it. On a server, run `odoo …` (or `odoo-bin …`) as Odoo's own
+user with its config file (`-c`).
+
+## Step 0 — ask for the two codes, one question at a time
+
+Before anything else, check one thing: whether OpenReceive is already
+installed (`odoo openreceive doctor -d <database>`). If the command exists, it
+prints `NWC_URI: present-redacted` or `missing` (likewise the LSC
+connections), never the values. A code that is already saved is not asked for
+again; if both are saved, skip to Step 3.
+
+Otherwise your next action is a question to the user. Do not download the
+module, edit Docker files or search anywhere else before asking it. Do not
+read Odoo's config file, its database, container environments or other
+projects looking for a code: a new install has neither code yet.
+
+The user never runs a command and never edits a file. They paste each code
+into this chat; you store it. That is the supported path: do not ask them to
+run the save command themselves, and do not tell them to revoke or replace a
+code because it was pasted here. Ask one question per message.
+
+1. **First message — the NWC code, and nothing else.**
+
+   > 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.
+
+2. **When they paste it.** If it does not start with `nostr+walletconnect://`,
+   ask them to copy the receive-only code again. Otherwise do not repeat it:
+   reply only that you have it, then ask the next question. You store it in
+   Step 2.
+3. **Second message — swaps.** If the user asked for stablecoins, USDT, USDC,
+   ETH, SOL, altcoins or "crypto" (as in "Bitcoin and stablecoin payments"),
+   this message IS the walkthrough below: do not skip it, and do not ask yes
+   or no first. Otherwise ask whether customers should also be able to pay
+   with USDT, USDC, ETH or SOL, then give the walkthrough. 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. Swaps are now on,
+   so keep the route back (the swap non-negotiable below).
+
+Do not report setup as complete until the NWC code is saved, and the LSC code
+is saved or the user said "Bitcoin only". Never invent a placeholder code.
+
+## Step 1 — install the module
+
+The `openreceive` Python package must be importable by Odoo's own Python.
+Odoo's official Docker image keeps its packages under the system's package
+manager, so build an image that adds it:
+
+1. Put a `Dockerfile` next to the Compose file, with the same tag as the Odoo
+   service's `image:` line:
+
+   ```dockerfile
+   FROM odoo:<tag>
+   USER root
+   RUN pip3 install --no-cache-dir --break-system-packages --ignore-installed typing_extensions h11 \
+    && pip3 install --no-cache-dir --break-system-packages openreceive==0.4.31
+   USER odoo
+   ```
+
+   The first line installs two packages beside the system's copies, which pip
+   cannot replace; do not add other packages, and do not install
+   `cryptography`: Odoo keeps using the system's.
+2. In the Compose file, replace that service's `image:` line with `build: .`
+   (the folder that holds the Dockerfile). Change nothing else in the file.
+3. Run `docker compose up -d --build`.
+
+On a server, install `openreceive==0.4.31` with the pip of the Python
+that runs Odoo (its virtualenv when it has one). On Odoo.sh, add
+`openreceive==0.4.31` to the repository's `requirements.txt`. If you
+cannot tell which Python runs Odoo, say so and stop.
+
+The module is the ZIP attached to this GitHub release, with its folder,
+`payment_openreceive`, at the top. Unzip it into the folder Odoo reads extra
+modules from: with the official image, the host folder mounted at
+`/mnt/extra-addons` (the Compose file's `volumes:` says which); on a server, a
+folder on the config file's `addons_path`. Never install the GitHub
+source-code ZIP or a ZIP from an older release.
+
+```sh
+curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.31/openreceive-odoo-0.4.31.zip
+unzip -oq openreceive-odoo-0.4.31.zip -d <that folder> && rm openreceive-odoo-0.4.31.zip
+```
+
+Then install it into the database and restart Odoo:
+
+```sh
+docker compose exec -T odoo /entrypoint.sh odoo -d <database> -i payment_openreceive --stop-after-init --no-http
+docker compose restart odoo
+```
+
+Installing creates the module's two tables in Odoo's database, its payment
+provider "OpenReceive" with the payment method "Bitcoin Lightning", a
+scheduled action that records payments made after the customer left, and the
+`odoo openreceive` command. The provider stays hidden from customers until a
+wallet code is saved and Step 2 publishes it. If the install says the
+`openreceive` package is missing, the image or virtualenv from the step above
+is not the one Odoo runs: fix that, do not work around it.
+
+## Step 2 — store the codes
+
+Store each code yourself, one per command, and never as a shell argument:
+
+1. Write the code with your file-editing tool, not a shell command (no
+   `echo`, `printf` or heredoc), to a new file outside the Odoo folders, such
+   as `/tmp/openreceive-code`.
+2. Run `odoo openreceive configure --nwc-uri=- -d <database> < /tmp/openreceive-code`.
+   In Docker: `docker compose exec -T odoo /entrypoint.sh odoo openreceive configure --nwc-uri=- -d <database> < /tmp/openreceive-code`.
+   For the LSC code, use `--lsc-uri-primary=-`.
+3. Delete the file (`rm /tmp/openreceive-code`), whether the command passed
+   or not.
+
+The command asks the wallet first and saves the code, in the module's own
+table, only when the wallet answers as receive-only; a failure saves nothing.
+If it reports spend methods such as `pay_invoice`, ask the user for a
+receive-only code again. Saving the swap code renames the payment method to
+"Bitcoin & stablecoins". Never write a code into Odoo's database, its config
+file or any file in its folders yourself.
+
+Then publish the provider, in every company:
+`odoo openreceive configure --enable -d <database>`, and run
+`odoo openreceive doctor -d <database>`. Doctor names any failed check and
+exits nonzero; fix it before going on.
+
+## Step 3 — mint a test invoice, then stop
+
+Create a small draft payment transaction for a test contact the command
+creates once (`openreceive-test@example.invalid`, with no order, so no
+customer sees it), and mint its Lightning invoice:
+
+```sh
+odoo openreceive test-invoice --new -d <database>
+```
+
+To use a transaction that already exists, pass `--reference <its reference>`
+instead of `--new`. `test-invoice` goes through the same route as the
+checkout page. It prints the amount in sats, the BOLT11 invoice and the
+methods the checkout offers, each swap asset marked available or followed by
+the reason it is not. That reason is the answer; report it. A reason about the
+provider's minimum or maximum is about this amount, not a fault. `test-invoice`
+and `doctor` are the whole check.
+
+The checkout page itself belongs to the customer who starts a payment: tell
+the user to try it from the shop, by putting a product in the cart and paying
+with "Bitcoin Lightning" (or "Bitcoin & stablecoins").
+
+You cannot pay the invoice: the code is receive-only. Do not pay, settle or
+mark the transaction paid, and do not look for a way to (a wallet control
+port, a test endpoint, another wallet). If the user wants a real settlement
+test, they pay a shop order with their own wallet; afterwards the order is
+confirmed.
+
+Setup ends here. Once doctor is clean, your last message starts "Setup is
+finished" and has at most six short lines: the methods the checkout offers
+(Bitcoin, plus USDT, USDC, ETH and SOL when the swap code is saved), and one
+line of what to try in the shop. Do not list each coin's availability, mention
+a minimum, or say a coin will not work: a provider minimum depends on the
+order total, and real orders will differ. Do not list what you changed or
+what doctor checked. Send nothing after it. Do not add containers, services,
+workers or cron jobs: the module's scheduled action runs inside Odoo.
+
+## Non-negotiables
+
+- Never print, log or commit a code, never put one in a shell argument, and
+  never write one into source files, Odoo's config file, the database or
+  browser code. Doctor's present/missing is all you report.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
+- Work only in this Odoo. Never read or run anything from another project or
+  directory on this machine (its `node_modules`, tools or source), for any
+  reason. A browser, Playwright, hand-made calls to the checkout's routes,
+  database queries and reading the module's source are not part of setup:
+  when doctor or `test-invoice` fails, report its output.
+- Receive-only NWC is required. Never get past the preflight with a code that
+  can spend.
+- The module owns only its two payment tables and its settings table in
+  Odoo's database. Odoo owns customers, orders, invoices, prices and email.
+  Do not add an external payment database or custom fulfillment code, and do
+  not edit Odoo's own files or modules. The Dockerfile that adds the Python
+  package and the one Compose line that builds it are the only deployment
+  change.
+- IF SWAPS ARE ON, KEEP THE ROUTE BACK. A deposit that arrives short or late
+  becomes refundable, and the customer claims it later from the same
+  transaction's checkout page. Keep the module installed while swap payments
+  may still need a refund. https://openreceive.org/guides/swap-refunds.md
+- A receive-only wallet cannot send refunds. Refund a settled payment manually
+  from the wallet.
+
+## Further reading
+
+- [Odoo Quickstart](https://openreceive.org/guides/quickstart-odoo.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)
+- [Security](https://openreceive.org/guides/security.md)
+- [Price Feeds](https://openreceive.org/guides/price-feeds.md)
+
+---
+
+## The quickstart, in full
+
+Inlined verbatim so this file needs no network access. Steps 0–3 above are the setup and this is their reference: where the two differ, the steps win, and its provider-form screens are only for an Odoo with no shell.
+The page it comes from is https://openreceive.org/guides/quickstart-odoo.
+
+## Odoo quickstart
+
+[Odoo](https://www.odoo.com) runs shops, sales and invoicing. The OpenReceive
+module adds a payment provider to it: the customer pays an online order, or an
+invoice's payment link, with Bitcoin over Lightning, straight into your own
+wallet, on a checkout page of your own site. With a swap provider, the same
+page also takes USDT, USDC, SOL and ETH, which the provider converts to BTC
+over Lightning into the same wallet.
+
+Odoo keeps owning customers, orders, invoices and prices. The module keeps its
+payment attempts in two tables of Odoo's own PostgreSQL database. When a
+payment settles, it marks Odoo's payment transaction done in the same database
+transaction that settles the payment, then runs Odoo's own post-processing:
+the order is confirmed, or the invoice paid, and Odoo sends its emails as it
+does for any other provider.
+
+Requirements: Odoo 19 or 20, self-hosted or on Odoo.sh, and the `openreceive`
+Python package at the module's version. Odoo Online cannot install modules, so
+it cannot run this one. A shop that already runs BTCPay Server can use
+[Odoo via BTCPay Server](https://openreceive.org/guides/odoo.md) instead.
+
+### Install the module
+
+Each GitHub release attaches the module as `openreceive-odoo-<version>.zip`,
+with its folder, `payment_openreceive`, at the top. Unzip it into a folder on
+Odoo's addons path, install the Python package where Odoo's Python finds it,
+restart Odoo, and install **Payment Provider: OpenReceive** under **Apps**, or
+from a terminal:
+
+```sh
+cd /path/to/your/addons
+curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.31/openreceive-odoo-0.4.31.zip
+unzip -oq openreceive-odoo-0.4.31.zip && rm openreceive-odoo-0.4.31.zip
+odoo -d <database> -i payment_openreceive --stop-after-init
+```
+
+How the Python package gets in depends on how Odoo runs:
+
+- **Odoo.sh**: commit the `payment_openreceive` folder to your repository and
+  add `openreceive==0.4.31` to the repository's `requirements.txt`.
+- **A source install with a virtualenv**: `pip install openreceive==0.4.31`
+  in Odoo's virtualenv.
+- **Odoo's Docker image** or **its Debian package**: see below.
+
+Installing the module creates its two tables, its payment provider,
+"OpenReceive", with the payment method buyers pick, "Bitcoin Lightning", and a
+scheduled action that records payments made after the customer left. The
+provider stays hidden from customers until a wallet code is saved and you
+publish it.
+
+#### Odoo in Docker
+
+Odoo's official image keeps its Python packages under the system's package
+manager. Build your own image on top of it: put this `Dockerfile` next to your
+`compose.yml`, with the same tag as your image,
+
+```dockerfile
+FROM odoo:19.0
+USER root
+RUN pip3 install --no-cache-dir --break-system-packages --ignore-installed typing_extensions h11 \
+ && pip3 install --no-cache-dir --break-system-packages openreceive==0.4.31
+USER odoo
+```
+
+and in `compose.yml` replace the Odoo service's `image:` line with
+`build: .`, then run `docker compose up -d --build`. The first `pip3` line
+installs two packages beside the system's own copies, which pip cannot
+replace; Odoo keeps using the system's other packages, its `cryptography`
+included. Your database and the module folder you mount at
+`/mnt/extra-addons` stay as they are.
+
+Run Odoo's commands through the image's entrypoint, which adds the database
+connection: `docker compose exec odoo /entrypoint.sh odoo <arguments>`. To
+install the module from a terminal:
+
+```sh
+docker compose exec odoo /entrypoint.sh odoo -d <database> -i payment_openreceive --stop-after-init --no-http
+docker compose restart odoo
+```
+
+### Configure the wallet
+
+You need a receive-only NWC code: a Nostr Wallet Connect code that can create
+invoices and read payments but cannot spend. The module refuses a code that
+can spend.
+
+In **Invoicing** (or **Website**) → **Configuration** → **Payment Providers**,
+open **OpenReceive**. Paste the code into **Receive-only NWC code** and save.
+To accept stablecoins too, paste a swap provider code into **Swap provider
+code**. Saving asks the wallet first and keeps the code only when the wallet
+answers as receive-only. The codes go to the module's own table, which no Odoo
+screen lists, and the form never shows them again; it says only whether each
+is saved. Then publish the provider (Odoo 19: State **Enabled**; Odoo 20:
+**Live** and **Published**).
+
+From a terminal, pipe each code into `odoo openreceive configure` from your
+secret manager or a protected file. Never type a code as a command argument:
+
+```sh
+odoo openreceive configure --nwc-uri=- -d <database> < /secure/path/wallet-code
+odoo openreceive configure --lsc-uri-primary=- -d <database> < /secure/path/swap-code
+odoo openreceive configure --enable -d <database>
+odoo openreceive doctor -d <database>
+```
+
+In Docker, start each with `docker compose exec -T odoo /entrypoint.sh`; `-T`
+passes the file through. `--enable` publishes the provider in every company.
+Saving a swap code renames the payment method "Bitcoin & stablecoins"; a name
+you gave it yourself stays. Skip the swap code for Bitcoin-only checkout.
+
+`doctor` checks the module and the Python package versions, each code as set
+or unset (never its value), the wallet, the tables, the provider in each
+company, the payment method, the checkout's files, the scheduled action, the
+price feed for each company's currency and the swap provider. It exits nonzero
+when a check fails.
+
+One wallet serves the whole database: every company's OpenReceive provider
+uses the codes saved last.
+
+### Check it
+
+Make a Lightning invoice through the same route the checkout page uses, for a
+new $5 test transaction, or for any unpaid OpenReceive transaction by its
+reference:
+
+```sh
+odoo openreceive test-invoice --new -d <database>
+odoo openreceive test-invoice --reference S00012-1 -d <database>
+```
+
+`--new` creates a draft payment transaction for a test contact it creates
+once, `openreceive-test@example.invalid`, with no order behind it, so no
+customer sees it. `--amount=` changes the amount, in the company's currency.
+It prints the amount in sats, the Lightning invoice, then each method the
+checkout offers: Bitcoin Lightning, and each swap asset with its network and
+whether it is available for this amount. A small amount is often below a swap
+provider's minimum; that is the amount, not a fault.
+
+### How a payment works
+
+1. The customer picks OpenReceive on Odoo's payment step, at checkout or on an
+   invoice's payment link, and clicks **Pay**. Odoo creates its payment
+   transaction and sends the customer to the module's checkout page for it.
+2. The module charges the transaction's amount, in its currency, converted to
+   sats at the current BTC price. Only the browser session that started the
+   payment can see its checkout page and make or follow its invoice: Odoo
+   records that transaction in the session, as its own payment status page
+   does.
+3. Once the wallet reports the payment, the module marks the transaction done
+   and runs Odoo's post-processing in the same database transaction that
+   settles it: the order is confirmed or the invoice paid. Should the
+   post-processing fail, the transaction stays done and Odoo's own scheduled
+   action finishes it.
+4. The checkout takes the customer to Odoo's payment status page, which takes
+   them on to the order's confirmation.
+
+The checkout asks the wallet while the page is open. If the customer closes it
+before the payment settles, the module's scheduled action finds the payment
+within a minute. `odoo openreceive reconcile -d <database>` runs one pass by
+hand.
+
+A customer who reloads the checkout page gets the same Lightning invoice
+again while it is still valid. Paying again from the order starts a new Odoo
+transaction with its own invoice; the earlier invoice still counts if paid.
+
+Odoo's log records each settlement under `odoo.addons.payment_openreceive`.
+
+### Refunds and removal
+
+The receive-only wallet cannot send refunds. Send a refund from your own
+wallet, then record it in Odoo. A customer whose swap deposit never converted
+reclaims it from the same transaction's checkout page, while the transaction
+is still unpaid. If you turn on swaps, you commit to keeping that path
+available. See [swap refunds](https://openreceive.org/guides/swap-refunds.md).
+
+Uninstalling the module deletes the saved codes and keeps the two payment
+tables, which are a record of payments received. Odoo keeps the provider and
+its transactions, as it does for any provider whose module is removed.
+
+### Tested, and not tested
+
+Tested on 2026-10-19 with Odoo 19 and Odoo 20 from their official Docker
+images, PostgreSQL 17, a test wallet and a test swap provider: install from
+the built ZIP, configure from stdin and from the provider form, the doctor,
+`test-invoice --new`, and a signed-in customer ordering through the shop and
+paying by Lightning and by USDT on Solana in Chromium, after which the sale
+order is confirmed. A payment whose page was closed was recorded by the
+scheduled action. Another customer, a visitor and a request without Odoo's
+CSRF token were refused. The module's own tests run on both series.
+
+Not tested: Odoo.sh, Odoo's Debian package, paying an invoice from its
+payment link, multi-company shops, and Odoo 18 or older, which the module does
+not install on. Lightning cannot pull a payment, so
+OpenReceive offers no subscriptions or saved payment tokens.

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/paymenter/full.md
 - Do not suggest rotating or revoking a code because it was pasted here.
 - Setup is done only when the NWC code is saved, and the LSC code is saved or the user said "Bitcoin only".
 
-These directions describe OpenReceive 0.4.29.
+These directions describe OpenReceive 0.4.31.
 
 Install and configure the OpenReceive payment gateway in the Paymenter billing
 panel you are working in. Preserve its theme, clients, products, invoices and
@@ -97,7 +97,7 @@ release. With Paymenter's official Docker image, download and unpack it inside
 the container, as the web user:
 
 ```sh
-docker compose exec -T -u nginx paymenter sh -c 'cd /app/extensions/Gateways && curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.29/openreceive-paymenter-0.4.29.zip && unzip -q openreceive-paymenter-0.4.29.zip && rm openreceive-paymenter-0.4.29.zip'
+docker compose exec -T -u nginx paymenter sh -c 'cd /app/extensions/Gateways && curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.31/openreceive-paymenter-0.4.31.zip && unzip -q openreceive-paymenter-0.4.31.zip && rm openreceive-paymenter-0.4.31.zip'
 docker compose exec -T -u nginx paymenter php artisan app:extension:install gateway OpenReceive
 ```
 
@@ -207,7 +207,6 @@ Paymenter's scheduler has never run, say so in one line of that message.
 - [Lightning Swap Connect URI](https://openreceive.org/guides/lightning-swap-connect.md)
 - [Security](https://openreceive.org/guides/security.md)
 - [Price Feeds](https://openreceive.org/guides/price-feeds.md)
-- [Payment Safety Upgrade](https://openreceive.org/guides/payment-safety-upgrade.md)
 
 ---
 
@@ -243,9 +242,9 @@ directory, next to Stripe and PayPal:
 
 ```sh
 cd /var/www/paymenter
-curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.29/openreceive-paymenter-0.4.29.zip
-unzip -q openreceive-paymenter-0.4.29.zip -d extensions/Gateways
-rm openreceive-paymenter-0.4.29.zip
+curl -fsSLO https://github.com/OpenReceive/openreceive/releases/download/v0.4.31/openreceive-paymenter-0.4.31.zip
+unzip -q openreceive-paymenter-0.4.31.zip -d extensions/Gateways
+rm openreceive-paymenter-0.4.31.zip
 chown -R www-data:www-data extensions/Gateways/OpenReceive
 sudo -u www-data php artisan app:extension:install gateway OpenReceive
 ```