openreceive 0.4.22 → 0.4.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ab3f684223bbce9a03d09d44e0ec67529cbc2b6616d2b50fb28a42f664e1a9a
-  data.tar.gz: 067be079ba6ccc64c251183495e7252837f596be0f244e1eceee557b08491f38
+  metadata.gz: fb5542a9163a02e90baa6f8938172785600029980002c119fde4631b452da20c
+  data.tar.gz: 7f71eb77da79968df633485d01ca9e7a89bbd839186a1daf1d137323f889daba
 SHA512:
-  metadata.gz: 913b9d2b647168a3e383199a15078eaa807496ac18fe941e25d7d1bddc0e114f654aaa9cccecdff347fd9eb578043ac397fe6cca484b0088bb7659ac5583aff0
-  data.tar.gz: d4a72bb5286fcaaa4c58aeef127c488fcf6921f921ea3676b9115bb3138500954a5c5bcbe5c6b369ed6e5e36f759d985c080db351a83f898edc4e67d7d2a3dd8
+  metadata.gz: 75465da88449b28ff097b5b4a4d7eadb141e2ba8be2a1e4797ae021fd23ba876df3b50cbef86e7afb0b05df4f718e957dd78a5c4979cda2558e79bb9642c20c4
+  data.tar.gz: 90884d4fef6027acb5919a5a9d36c0e7d1ba066d13d21db1793c940dad7c2c6653288a26efb0540eccb7b7baf37a4817e99d3826fb58af034aa594bc303ff260

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.23 - 2026-10-11
+
+Release with the complete 0.4.23 package family. The bundled agent skill adds
+directions for Lovable's agent. Its BTCPay Server directions ask for one code
+per message and never search the machine for one, its WooCommerce directions
+install the plugin from WordPress.org, and its Laravel directions add GMP to
+the Docker image. No Ruby runtime changes from 0.4.22.
+
 ## 0.4.22 - 2026-10-10
 
 Release with the complete 0.4.22 package family. The bundled agent skills'

data/lib/openreceive/version.rb

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

data/skills/integrate-openreceive/SKILL.md

@@ -38,6 +38,9 @@ connected wallet; asset and network availability depends on the provider.
    - Django: [references/django.md](references/django.md)
    - Laravel: [references/laravel.md](references/laravel.md)
    - WordPress + WooCommerce: [references/woocommerce.md](references/woocommerce.md) — the packaged gateway and merchant settings.
+   - Lovable (TanStack Start on Cloudflare Workers, with Supabase):
+     [references/lovable.md](references/lovable.md) — no terminal; codes are
+     Lovable secrets and payments go through Supabase's HTTPS API.
    - 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.

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (BTCPay Server)
 
 ```sh
-# READ THIS FIRST: this file is 12 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 16 KB and a summary drops required steps. Download it whole:
 curl -fsSL https://openreceive.org/agent-directions/btcpay/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/btcpay/full.md
 - Never tick the spend-capable override to make a save succeed.
 - Do not suggest rotating or revoking a code because it was pasted here.
 
-These directions describe OpenReceive 0.4.22.
+These directions describe OpenReceive 0.4.23.
 
 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
@@ -54,31 +54,84 @@ refund path on the same checkout screen.
    BTCPay refuses to load it below.
 2. Check whether the plugin is installed (the Plugins menu — the plug icon in
    the top-right corner — under Installed Plugins, or the store navigation
-   shows an "OpenReceive" entry). If not, install it from the BTCPay plugin
-   directory (the same Plugins menu → Plugin Directory, search "openreceive",
-   then Install and Restart now), as the quickstart says; do not invent an
-   installer command.
+   shows an "OpenReceive" entry; through Greenfield,
+   `GET /api/v1/stores/{storeId}/openreceive/settings` answers 404 until it
+   is). If not, install it from the BTCPay plugin directory (the same Plugins
+   menu → Plugin Directory, search "openreceive", then Install and Restart
+   now), as the quickstart says; do not invent an installer command. BTCPay
+   installs plugins only from its UI. If you cannot use it, ask the user to:
+   name those clicks, and wait until they say it is installed.
 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.
+   `lightningNodeIsOpenReceive` and `lscPrimaryConfigured`. A code that is
+   already saved is not asked for again; if both are, skip to Verifying.
+
+Otherwise your next action is a question to the user. A store without a
+connection has no code anywhere on this machine. Do not search for one: do not
+read other files, Docker containers, compose files beyond this deployment's,
+or process environments, and never run `printenv`. Hunting for a code burns
+the turn and can leak other secrets into the transcript.
+
+The user never edits BTCPay's settings for you. They paste each code
+into the chat; you save it (Step 1). 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 save it in
+   > BTCPay.
+
+   If the plugin still needs installing, ask for that in the same message.
+2. **When they paste it.** If it does not start with `nostr+walletconnect://`,
+   ask them to copy the receive-only code again. Otherwise save it (Step 1),
+   reply only that it is saved, then ask the next question. 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.
+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: send it as it is, and do not ask yes
+   or no first. Otherwise ask whether payers 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 save 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 save it
+   (Step 1); saving it turns swaps on.
+
+The quickstart below shows the same steps in BTCPay's UI.
+
+## Step 1 — save the codes through the Greenfield API
+
+Use a Greenfield API key the user gives you (Account → API Keys) that can
+modify the store's settings. A swap provider on a local network needs a server
+admin's key. Save each code yourself, one request each, and never in a
+command line:
+
+1. Write the request body with your file-editing tool, not a shell command (no
+   `echo`, `printf` or heredoc), to a new file outside the deployment
+   directory, such as `/tmp/openreceive-settings.json`:
+   `{"nwcUri": "<the NWC code>"}`. For the LSC code the body is
+   `{"lscPrimary": "<the LSC code>"}`; saving it turns swaps on.
+2. Send it, with your server's address, the key and the store id:
+   `curl -fsS -X PUT -H "Authorization: token $BTCPAY_API_KEY" -H "Content-Type: application/json" --data @/tmp/openreceive-settings.json "$BTCPAY_URL/api/v1/stores/$BTCPAY_STORE_ID/openreceive/settings"`.
+3. Delete the file (`rm /tmp/openreceive-settings.json`), whether the request
+   passed or not.
+
+The response never contains a code. `lightningNodeIsOpenReceive: true` means
+the wallet is saved; `swapsEnabled` and `lscPrimaryConfigured` say the same
+for swaps. A refusal answers 422 with a `code` and a `message`: a code that
+can spend is refused on purpose, so ask the user for a receive-only code
+instead of setting the override.
 
 ## Non-negotiables
 
@@ -121,11 +174,16 @@ Only then start the quickstart.
 
 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
+needing attention. Without the UI, check through Greenfield instead:
+`GET /api/v1/stores/{storeId}/openreceive/settings` shows the wallet and
+swaps, `POST /api/v1/stores/{storeId}/openreceive/wallet/test` with `{}`
+runs the wallet preflight again, and a test invoice
+(`POST /api/v1/stores/{storeId}/invoices` with an amount) must list a
+`BTC-LN` payment method whose `destination` is a BOLT11. 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.
 
-Setup ends when the health check is clean. Say "Setup is finished" in one
+Setup ends when the health check, or those Greenfield checks, are clean. Say "Setup is finished" in one
 message. Do not offer more work or end the message on a question.
 
 ## More documentation

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/django/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.22.
+These directions describe OpenReceive 0.4.23.
 
 Add OpenReceive to a Django project — the app you are already working in. You
 do not need a copy of the OpenReceive source: the Python package is on PyPI

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/fastapi/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.22.
+These directions describe OpenReceive 0.4.23.
 
 Add OpenReceive to a FastAPI application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the engine is on PyPI

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/fastify/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.22.
+These directions describe OpenReceive 0.4.23.
 
 Add OpenReceive to a Fastify application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the packages are on npm, and

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Laravel)
 
 ```sh
-# READ THIS FIRST: this file is 44 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 45 KB and a summary drops required steps. Download it whole:
 curl -fsSL https://openreceive.org/agent-directions/laravel/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/laravel/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.22.
+These directions describe OpenReceive 0.4.23.
 
 Add OpenReceive to a Laravel application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the package is on Packagist
@@ -417,8 +417,24 @@ PHP extensions:
   `pdo_sqlite`).
 
 `php -m` lists what your build has. To add gmp on Debian/Ubuntu, run
-`apt-get install php8.2-gmp`. In the official Docker image, run
-`docker-php-ext-install gmp`.
+`apt-get install php8.2-gmp`. The official `php` Docker images do not ship
+it, and `docker-php-ext-install gmp` alone fails without the GMP headers. Add
+both to the Dockerfile, before the step that installs the app's Composer
+packages, and rebuild the image:
+
+```dockerfile
+RUN apt-get update && apt-get install -y --no-install-recommends libgmp-dev \
+    && docker-php-ext-install gmp \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+Run `composer require` with a PHP that has gmp. On a machine without one,
+use the rebuilt image with the project mounted, then rebuild again so the
+image installs the new lock:
+`docker compose run --rm --no-deps -v "$PWD":/app web composer require openreceive/laravel -W`.
+Never pass `--ignore-platform-req=ext-gmp` or `--ignore-platform-reqs`:
+Composer then installs a package that fails as soon as it talks to the
+wallet.
 
 Add the Laravel package:
 

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

@@ -0,0 +1,531 @@
+This is the full file; follow it from Step 0.
+
+# OpenReceive agent directions (Lovable)
+
+```text
+READ THIS FIRST: this file is 25 KB and a summary drops required steps. Read all of it:
+https://openreceive.org/agent-directions/lovable/full.md
+If your fetch tool gave you a summary, fetch that URL again for the full text.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before adding packages 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.
+- Ask for NWC_URI and LSC_URI_PRIMARY with Lovable's secret input. Never put a code in .env, code or a VITE_ name.
+- You have no terminal: never ask the user to run a command. Every step is a file, a package, a migration or a secret.
+- Do not suggest rotating or revoking a code because it was pasted here.
+- Start Step 1 only once NWC_URI is saved, and LSC_URI_PRIMARY is saved or the user said "Bitcoin only".
+
+These directions describe OpenReceive 0.4.23.
+
+Add OpenReceive to this Lovable app: a TanStack Start app on Cloudflare
+Workers, with Lovable Cloud or a connected Supabase project as its database.
+These directions are written for Lovable's agent. You have no terminal, so
+every step is a file edit, a package, a Supabase migration or a secret. Never
+ask the user to run a command. The TanStack Start recipe is appended to this
+file in full; its "On Supabase (Lovable)" section is the code to follow.
+
+Do not clone the OpenReceive repository, and do not copy a demo's models over
+tables that already exist. Find this app's orders and products, whatever they
+are named, and map the hooks onto those. Keep this app's UI, sign-in and
+database.
+
+## What OpenReceive is
+
+A payment library that runs inside THIS app's server code. It mounts as one
+TanStack Start server route (`src/routes/openreceive.$.ts`), issues Lightning
+invoices against a wallet the merchant already controls, and settles each
+payment into this app's Supabase database. There is no OpenReceive account
+and no API key, and OpenReceive never holds the funds: the sats land in the
+merchant's wallet.
+
+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. Step 0 collects those credentials. You write two
+hooks in TypeScript, `amountFor` and `authorize`, and one SQL function,
+`openreceive_on_paid`, that marks the order paid. OpenReceive supplies
+invoices, polling, settlement and the checkout UI. It never owns orders,
+users, prices, or fulfillment.
+
+On Lovable, OpenReceive keeps its payment rows in this app's Supabase
+database and reaches it over Supabase's HTTPS API with the project's secret
+key, because a Worker cannot open a Postgres connection to Supabase.
+
+## Step 0 — ask for the two codes, one secret at a time
+
+If the user says the codes are already saved as this project's secrets
+(`NWC_URI`, and `LSC_URI_PRIMARY` unless they want Bitcoin only), believe
+them: do not ask for them, and go to Step 1. You cannot read a secret's value,
+and you do not need to.
+
+Otherwise, before anything else, your next action is a question to the user.
+Do not add packages, write migrations or edit files before asking it. A new
+shop has neither code yet.
+
+Two server-only secrets are needed before the integration:
+
+- `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.
+
+Ask for each one with Lovable's secure secret input, named exactly as above.
+The user never edits a file: they paste each code into this chat or into
+that secret input, and Lovable stores it as a project secret. A code pasted
+into the chat is saved as a secret too. Never repeat a code back. Ask one
+question per message.
+
+1. **First message — the NWC code, and nothing else.** Ask for the secret
+   `NWC_URI` 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 it into the secret input for NWC_URI.
+
+2. **When it is saved.** If the user pasted it into the chat and it does not
+   start with `nostr+walletconnect://`, ask them to copy the receive-only code
+   again. Reply only that it is saved, then ask the next question.
+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: send it as it is, and do not ask yes
+   or no first. Otherwise ask whether payers 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 into the secret input for LSC_URI_PRIMARY — or say "Bitcoin only" and
+   > I will continue without it.
+
+   Mention FixedFloat only if they already use it. Swaps on means the refund
+   route back is part of this integration (the swap non-negotiable below).
+4. **Supabase.** Lovable sets `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY`
+   for server code when Lovable Cloud, or a connected Supabase project, is on.
+   Do not ask for them or try to create them: Lovable reserves the
+   `SUPABASE_` prefix. If this project has no backend yet, ask the user to
+   turn on Lovable Cloud, and wait until they have.
+
+Never give a code a `VITE_` prefix, never put one in `.env` (Lovable commits
+that file), and never write one into code or a log. Do not invent placeholder
+codes. Start Step 1 only once `NWC_URI` is saved and `LSC_URI_PRIMARY` is
+saved or explicitly declined.
+
+## Step 1 — the packages
+
+Add `@openreceive/http` and `@openreceive/react` at 0.4.23 or newer.
+Nothing else: no `pg`, no Postgres driver, no OpenReceive scaffold. Do not
+change the Vite or Wrangler configuration.
+
+## Step 2 — the migration
+
+Fetch https://openreceive.org/guides/supabase-migration.md and copy its SQL
+block, unchanged, into one new Supabase migration, then apply it. Do not edit
+it, split it, rename anything in it, or drop its `revoke` lines. It creates
+`openreceive_payments` and `openreceive_meta` with row level security on and
+every grant revoked from `anon` and `authenticated`, the functions the server
+calls to write them, and `openreceive_on_paid` as a placeholder that refuses
+every settlement.
+
+## Step 3 — the order and its buyer
+
+- **The order's id is the `reference`.** Create the order before checkout,
+  keep it across retries, never reuse it. A fresh id per page load lets one
+  order be paid twice.
+- **The order row is the price.** Order creation copies live prices into the
+  order. `amountFor` reads only that order and returns
+  `{ currency, value, description }`, the value a decimal string such as
+  `"12.50"`, and `null` for an order that is not payable.
+- **The buyer is a cookie.** The checkout calls the payment routes from the
+  browser with the page's cookies and nothing else, and a Lovable app keeps
+  its Supabase sign-in in the browser, not in a cookie. So in a migration add
+  `buyer_token text` to the orders table, and create orders in a server
+  function (`createServerFn`) that reads the `buyer` cookie, or sets one to
+  `crypto.randomUUID()` (HttpOnly, Secure, SameSite=Lax, path `/`, one
+  year) with `getCookie` and `setCookie` from `@tanstack/react-start/server`,
+  then inserts the order with `buyer_token` set to it through `supabaseAdmin`
+  from `@/integrations/supabase/client.server`, and returns the id. If the app
+  creates orders in the browser today, move that insert into this function.
+  Keep the order's user column too, if the app has sign-in.
+- **The order is unpaid or paid.** Do not copy attempt statuses (`pending`,
+  `expired`, `failed`, `attention`) onto it, and do not add a relation to
+  `openreceive_payments`.
+
+## Step 4 — `openreceive_on_paid`
+
+In a second new migration, replace the placeholder with the SQL that marks
+this app's order paid. Use `create or replace`, and this app's own table,
+column and status names:
+
+```sql
+create or replace function public.openreceive_on_paid(
+  p_reference text, p_payment_hash text, p_paid_at bigint
+) returns void language plpgsql as $$
+begin
+  update public.orders
+     set status = 'paid'
+   where id = p_reference::uuid   -- or just p_reference, if the ids are text
+     and status = 'pending';
+end
+$$;
+```
+
+It runs inside the transaction that records the payment, for the order's
+first settled payment only. If it raises, nothing is recorded, and the next
+request retries it. Its `WHERE` on the unpaid status is the guard against a
+second fulfillment. Keep it to database writes.
+
+## Step 5 — the payment route
+
+Write `src/routes/openreceive.$.ts` and `src/lib/openreceive.server.ts`
+exactly as the recipe's "On Supabase (Lovable)" section shows:
+
+- `storage: { supabase: { url: process.env.SUPABASE_URL, key: process.env.SUPABASE_SERVICE_ROLE_KEY } }`,
+  read inside the handler, never at module scope.
+- No `onPaid` and no `db`: `openreceive_on_paid` is the fulfillment.
+- `findOrder` reads the order with `supabaseAdmin`; `authorize` compares the
+  request's `buyer` cookie with the order's `buyer_token`.
+- Build the stack inside each request and close it in `finally`.
+- Import the server module only inside the route's handlers, so it never
+  reaches the browser bundle.
+
+## Step 6 — the checkout page
+
+Add `src/routes/checkout.$reference.tsx` with `<Checkout reference={reference}
+prefix="/openreceive" />` from `@openreceive/react`, and import
+`@openreceive/react/styles.css` there. After the order is created, navigate
+to `/checkout/<id>`. Use the drop-in; do not build your own checkout UI.
+
+## After setup — hand over, then stop
+
+You cannot pay the invoice: the code is receive-only. Do not pay, settle or
+mark an order paid, and do not look for a way to.
+
+If the checkout answers 503, the server log names the fix: usually the
+migration is not applied, or `openreceive_on_paid` is still the placeholder.
+
+Setup ends here. Your last message starts "Setup is finished" and has at most
+five short lines: where to place an order in the preview, the methods the
+checkout offers, and that a small real payment from their own wallet marks
+the order paid. Send nothing after it. Do not list what changed, offer more
+work, or end the message on a question. Name the methods: Bitcoin, plus
+USDT, USDC, ETH and SOL when `LSC_URI_PRIMARY` is saved. Do not mention
+minimums, and never say a coin will not work or will not be offered.
+
+## Non-negotiables
+
+The recipe below has the code. These are the rules it cannot state for
+itself.
+
+- OpenReceive never owns orders, users, prices, or fulfillment.
+- Keep `NWC_URI` / `LSC_URI_*` server-only: secrets read with `process.env`
+  in `.server.ts` modules. Never a `VITE_` variable, `.env`, browser code or
+  a log.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
+- `SUPABASE_SERVICE_ROLE_KEY` reads and writes every table. Read it only in
+  server modules.
+- Never grant `anon` or `authenticated` anything on an `openreceive_*` table
+  or function, and never add a row level security policy to those tables.
+  The server refuses to serve while they can reach them.
+- The host owns the price. `amountFor` reads it from the order; reject
+  payer-supplied amounts.
+- `authorize` runs on every request, and the `resource` it receives is a CLAIM
+  the payer made, not proof. Check the `buyer` cookie against the order.
+- Receive-only NWC is required; a spend-capable code fails closed unless
+  explicitly overridden. Never set that override.
+- There is NO merchant-initiated refund of a settled Lightning payment, because
+  the wallet cannot spend. Swap refunds — a payer reclaiming a deposit that
+  never converted — are the only refund OpenReceive performs. Do not build,
+  promise, or imply a Lightning refund path.
+- IF YOU TURN SWAPS ON, BUILD THE ROUTE BACK. A deposit that arrives short or
+  late is refunded on a SECOND visit, so the order needs its own URL
+  (`/checkout/$reference`, with `syncUrl` on `<Checkout>`), and the attempt
+  must come back with it: keep the `payment_hash` from `onState` and pass it
+  as `resumePaymentHash`. https://openreceive.org/guides/swap-refunds.md
+- Show the payer what they are buying: return a `description` beside the
+  price from `amountFor`.
+- HTTP JSON is snake_case; TypeScript APIs are camelCase.
+- Money is integers or decimal strings — never binary floats.
+
+## More documentation
+
+Fetch one when the moment comes. Each is raw markdown, so a plain GET is
+enough.
+
+- https://openreceive.org/guides/lovable.md — what the user does on Lovable around these steps
+- https://openreceive.org/guides/supabase.md — Supabase over HTTPS: how the storage works, and what the server checks before it serves
+- https://openreceive.org/guides/supabase-migration.md — the migration for Step 2
+- https://openreceive.org/guides/authorization.md — before you write `authorize`
+- https://openreceive.org/guides/storage.md — the payment tables and the attempt state machine
+- https://openreceive.org/guides/frontend-checkout.md — the drop-in's props, including `syncUrl` and `resumePaymentHash`
+- https://openreceive.org/guides/checkout-ux.md — the rules the drop-in already follows
+- https://openreceive.org/guides/provider-registry.md — where the wallet logos and pay tutorials come from: inside the JavaScript, nothing to serve
+- https://openreceive.org/guides/automated-swaps.md — only if `LSC_URI_PRIMARY` is set
+- https://openreceive.org/guides/swap-refunds.md — the refund flow, and the route back to it
+- https://openreceive.org/guides/lightning-swap-connect.md — what an `LSC_URI_*` code actually is
+- https://openreceive.org/guides/environment-variables.md — every variable, and what is deliberately not one
+- https://openreceive.org/guides/price-feeds.md — where the fiat→sats rate comes from
+- https://openreceive.org/guides/rate-limiting.md — before a public shop goes live
+- https://openreceive.org/guides/security.md and https://openreceive.org/guides/deploying.md — before this goes anywhere real
+- https://openreceive.org/guides/api-reference.md — every route, option and error code
+- 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
+
+---
+
+## The quickstart, in full
+
+Inlined verbatim so this file needs no network access. Steps 0–6 above are the setup on Lovable and this recipe is their reference: follow its On Supabase (Lovable) section, not its pg pool, and skip its npm commands. Where the two differ, the steps win.
+The page it comes from is https://openreceive.org/guides/tanstack-start-recipe.
+
+## TanStack Start recipe
+
+OpenReceive ships no TanStack Start package. A TanStack Start server route
+takes a Web-standard `Request` and returns a `Response`, and so does
+`@openreceive/http`, so the integration is the route below. Your server code
+creates each Lightning invoice, the payment goes straight to your wallet, and
+payment attempts are stored in your app's Postgres database. There is no
+OpenReceive account and no background worker.
+
+Optional swaps let customers pay with **USDT, USDC, SOL, and ETH**. A swap
+provider you configure converts the payment to **BTC over Lightning**, and it
+settles into the same wallet. Available assets and networks depend on the
+provider.
+
+This recipe was checked with `@tanstack/react-start` 1.168 and
+`@openreceive/*` 0.4.19. The app was built with Lovable's Vite config for
+Cloudflare Workers and run under workerd: a buyer's checkout showed a real
+Lightning invoice, and a stranger was refused. The Supabase route below runs
+in OpenReceive's CI as a Worker, against Supabase's own Postgres image and
+API server: a buyer's invoice, a stranger refused, one live attempt under
+concurrent requests, and a payment that `openreceive_on_paid` fulfills once.
+
+```sh
+npm install @openreceive/http @openreceive/react pg
+```
+
+### Where it runs
+
+- **Node** (the `node-server` preset, or any Node host): any Postgres.
+- **Cloudflare Workers** (the `cloudflare-module` preset, Lovable's default):
+  with Node compatibility, and a Postgres whose certificate a public
+  authority signed, such as Neon.
+- **Cloudflare Workers with Supabase**, which is every Lovable app: a Worker
+  cannot open a Postgres connection to Supabase, whose certificate comes from
+  a private authority. Use [On Supabase](#on-supabase-lovable) below, which
+  stores payments through Supabase's HTTPS API instead.
+
+Workers ties every socket to the request that opened it, and forbids network
+calls at import. So the route builds its database pool and its OpenReceive
+stack inside each request, and closes both before it responds. Each request
+then opens its own wallet connection; in our test a checkout request took one
+to four seconds. The same code works on Node.
+
+### The payment route
+
+Keep the handler in a `.server.ts` module. Route files are also bundled for
+the browser, so the route loads the module only when a request arrives:
+
+```ts
+// src/routes/openreceive.$.ts — every route under /openreceive/
+import { createFileRoute } from "@tanstack/react-router";
+
+async function openReceive({ request }: { request: Request }): Promise<Response> {
+  const { handleOpenReceive } = await import("@/lib/openreceive.server");
+  return handleOpenReceive(request);
+}
+
+export const Route = createFileRoute("/openreceive/$")({
+  server: { handlers: { GET: openReceive, POST: openReceive } },
+});
+```
+
+```ts
+// src/lib/openreceive.server.ts
+import { createStack } from "@openreceive/http";
+import pg from "pg";
+import { findOrder, currentVisitor } from "./orders.server"; // your own orders
+
+export async function handleOpenReceive(request: Request): Promise<Response> {
+  // Read process.env inside the handler: on Workers it is empty at import.
+  const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL, max: 1 });
+  const stack = createStack({
+    wallet: { nwc: process.env.NWC_URI ?? "" },
+    storage: {
+      db: pool,
+      // Runs once, inside the transaction that records the payment.
+      onPaid: async ({ reference, paidAt, query }) => {
+        await query(
+          "UPDATE orders SET state = 'paid', paid_at = $1 WHERE id = $2 AND state = 'awaiting_payment'",
+          [paidAt, reference],
+        );
+      },
+    },
+    // The price comes from the order row, never from the request.
+    amountFor: async (reference) => {
+      const order = await findOrder(pool, reference);
+      return order?.state === "awaiting_payment"
+        ? { currency: order.currency, value: order.amount, description: order.title }
+        : null;
+    },
+    // Only the buyer may pay for their order.
+    authorize: async ({ request: incoming, resource }) => {
+      const order = resource.reference ? await findOrder(pool, resource.reference) : undefined;
+      const visitor = currentVisitor(incoming);
+      return Boolean(order && visitor && order.visitor === visitor);
+    },
+    // Cloudflare sets cf-connecting-ip on every request, and a client cannot.
+    // On Node behind your own proxy, read the header that proxy sets.
+    rateLimiting: {
+      ip: ({ request: incoming }) => incoming.headers.get("cf-connecting-ip") ?? undefined,
+    },
+  });
+  try {
+    return await stack.handler(request, { native: request });
+  } finally {
+    await stack.close();
+    await pool.end();
+  }
+}
+```
+
+`authorize` sees the incoming request with its cookies, so check it with
+the session your app already has. The Next.js quickstart
+explains each hook. They are the same here.
+
+Create OpenReceive's two tables with your migrations, or run
+`paymentsSchemaSql("postgres")` from `@openreceive/http` once. It is
+idempotent. See Payment storage.
+
+### On Supabase (Lovable)
+
+On Supabase the route keeps payments in your Supabase database through its
+HTTPS API, with the project's secret key. There is no `pg` pool. Use
+`@openreceive/*` 0.4.23 or newer:
+
+```sh
+npm install @openreceive/http @openreceive/react
+```
+
+1. Apply the migration from `npx openreceive scaffold payments --supabase`.
+   It creates OpenReceive's tables, locked away from the browser's Supabase
+   key, and the functions that write them.
+2. Replace its placeholder `openreceive_on_paid` with the SQL that marks your
+   order paid. It runs inside the transaction that records the payment, for
+   the order's first payment only, so a failure there records nothing:
+
+   ```sql
+   create or replace function public.openreceive_on_paid(
+     p_reference text, p_payment_hash text, p_paid_at bigint
+   ) returns void language plpgsql as $$
+   begin
+     update public.orders set status = 'paid'
+      where id = p_reference::uuid and status = 'pending';
+   end
+   $$;
+   ```
+
+3. Write the route's server module:
+
+```ts
+// src/lib/openreceive.server.ts
+import { createStack } from "@openreceive/http";
+import { findOrder, currentBuyer } from "./orders.server"; // your own orders
+
+export async function handleOpenReceive(request: Request): Promise<Response> {
+  // Read process.env inside the handler: on Workers it is empty at import.
+  // Lovable sets SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY for server code.
+  const stack = createStack({
+    wallet: { nwc: process.env.NWC_URI ?? "" },
+    storage: {
+      supabase: {
+        url: process.env.SUPABASE_URL ?? "",
+        key: process.env.SUPABASE_SERVICE_ROLE_KEY ?? "",
+      },
+    },
+    // The price comes from the order row, never from the request.
+    amountFor: async (reference) => {
+      const order = await findOrder(reference);
+      return order?.status === "pending"
+        ? { currency: order.currency, value: order.total, description: order.title }
+        : null;
+    },
+    // Only the buyer may pay for their order.
+    authorize: async ({ request: incoming, resource }) => {
+      const order = resource.reference ? await findOrder(resource.reference) : null;
+      const buyer = currentBuyer(incoming);
+      return Boolean(order && buyer && order.buyer_token === buyer);
+    },
+    rateLimiting: {
+      ip: ({ request: incoming }) => incoming.headers.get("cf-connecting-ip") ?? undefined,
+    },
+  });
+  try {
+    return await stack.handler(request, { native: request });
+  } finally {
+    await stack.close();
+  }
+}
+```
+
+There is no `onPaid`: `openreceive_on_paid` is the fulfillment. `findOrder`
+reads the order with your server-side Supabase client; in a Lovable app that
+is `supabaseAdmin` from `@/integrations/supabase/client.server`.
+
+The checkout calls the payment routes from the browser with the page's
+cookies, and nothing else. A Lovable app keeps its Supabase sign-in in the
+browser, not in a cookie, so `authorize` cannot see who is signed in. Give
+the buyer a cookie of their own instead: create orders in a server function
+that sets an HttpOnly `buyer` cookie (a random value, kept across orders) and
+stores the same value on the order as `buyer_token`. `currentBuyer` reads it
+back from the request's `cookie` header.
+
+Before it serves, the server checks the database, and the payment routes
+answer 503 until the migration is applied and `openreceive_on_paid` is
+yours; the log names the fix. More: Supabase over HTTPS.
+
+### The checkout page
+
+```tsx
+// src/routes/checkout.$reference.tsx
+import { Checkout } from "@openreceive/react";
+import "@openreceive/react/styles.css";
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/checkout/$reference")({
+  component: OrderCheckout,
+});
+
+function OrderCheckout() {
+  const { reference } = Route.useParams();
+  return <Checkout reference={reference} prefix="/openreceive" />;
+}
+```
+
+It renders on the server and starts the checkout in the browser. The payer
+picks Bitcoin and gets the invoice.
+
+### Settings
+
+- `NWC_URI`: a receive-only code from your wallet
+  ([get one](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
+  Optional: `LSC_URI_PRIMARY` for swaps
+  ([set one up](https://openreceive.org/set_up_swap_provider)).
+- `DATABASE_URL`: your Postgres. On serverless hosts use the pooled URL. The
+  storage is tested through a transaction pooler.
+- On Supabase over HTTPS, instead of `DATABASE_URL`: `SUPABASE_URL` and the
+  secret key in `SUPABASE_SERVICE_ROLE_KEY`. Lovable sets both itself.
+
+Set them as server secrets, never with a `VITE_` prefix, which would put them
+in the browser bundle.
+
+No worker or cron job is needed. Each request to the payment routes also
+checks the wallet for settled invoices, through a lock in your database. A
+payer who closes the tab is settled on the next request.

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.22.
+These directions describe OpenReceive 0.4.23.
 
 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

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.22.
+These directions describe OpenReceive 0.4.23.
 
 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

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/php/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.22.
+These directions describe OpenReceive 0.4.23.
 
 Add OpenReceive to a PHP application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the engine is on Packagist
@@ -133,8 +133,10 @@ again. Never set the spend-capable override to get past it.
 
 Then check the PHP runtime: `php -m` must list `gmp`, `sodium`, `mbstring`,
 `json`, `pdo` and one PDO driver. `ext-gmp` is REQUIRED — the NWC transport
-signs every request with it — and `php:*-cli`/`-fpm` images do not ship it
-(`docker-php-ext-install gmp`). PHP must be ≥ 8.2 and 64-bit.
+signs every request with it — and `php:*-cli`/`-fpm` images do not ship it:
+install `libgmp-dev` first, then `docker-php-ext-install gmp`, in the
+Dockerfile. Never pass `--ignore-platform-req=ext-gmp` to Composer. PHP must
+be ≥ 8.2 and 64-bit.
 
 ### Upgrading an existing install
 

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/rails/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.22.
+These directions describe OpenReceive 0.4.23.
 
 Add OpenReceive to a Rails application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the gem is on RubyGems, the

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

@@ -17,7 +17,7 @@ curl -fsSL https://openreceive.org/agent-directions/woocommerce/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.22.
+These directions describe OpenReceive 0.4.23.
 
 Install and configure the OpenReceive payment gateway in the WooCommerce store
 you are working in. Preserve its theme, checkout, customer accounts, order
@@ -92,11 +92,18 @@ is saved or the user said "Bitcoin only". Never invent a placeholder code.
 
 ## Step 1 — install the plugin
 
-Install the plugin built for this release. Never install the GitHub
+Install this release from the WordPress.org plugin directory:
+
+```sh
+wp plugin install openreceive --version=0.4.23 --activate
+```
+
+If that fails because WordPress.org does not have this version yet, install
+the ZIP attached to the same GitHub release. Never install the GitHub
 source-code ZIP or a ZIP from an older release:
 
 ```sh
-wp plugin install https://github.com/OpenReceive/openreceive/releases/download/v0.4.22/openreceive-wordpress-0.4.22.zip --activate
+wp plugin install https://github.com/OpenReceive/openreceive/releases/download/v0.4.23/openreceive-wordpress-0.4.23.zip --activate
 ```
 
 It needs WooCommerce active, and PHP 8.2+ with GMP and sodium in BOTH the web
@@ -105,7 +112,7 @@ images, activation warns "OpenReceive is not running: this site needs the PHP
 GMP extension" and the plugin stays idle: add GMP to both images as "Enable GMP in both PHP runtimes" below
 says, rebuild both, then install again. If the Compose file has only `image:`
 lines, use the two Dockerfiles and `build:` keys under "Compose files with only
-`image:` lines" below, and add no other service. If the URL answers 404, build the same
+`image:` lines" below, and add no other service. If the ZIP URL answers 404, build the same
 tag as "Get the installable archive" below says.
 
 ## Step 2 — store the codes, then enable the gateway
@@ -230,10 +237,11 @@ The [WordPress integration entry point](https://openreceive.org/integrations/wor
 redirects to the WooCommerce integration, which uses this same guide and agent
 directions. OpenReceive checkout on WordPress requires WooCommerce.
 
-Activate WooCommerce first. Then install the built OpenReceive plugin zip
-through **Plugins → Add New → Upload Plugin**. You cannot upload the source
-directory as-is. It needs a build first. The plugin is not yet submitted to
-WordPress.org.
+Activate WooCommerce first. Then install OpenReceive from the
+[WordPress.org plugin directory](https://wordpress.org/plugins/openreceive/):
+in **Plugins → Add New**, search for **OpenReceive**, then install and
+activate it. With WP-CLI, run `wp plugin install openreceive --activate`.
+WordPress offers each new release as an ordinary plugin update.
 
 Requirements: WordPress 6.6+, WooCommerce 9+, 64-bit PHP 8.2+ with GMP and sodium,
 and MySQL 8 or MariaDB 10.5+. When you activate the plugin, it creates tables for
@@ -242,16 +250,19 @@ database or application.
 
 ### Get the installable archive
 
-Download [openreceive-wordpress-0.4.22.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.22/openreceive-wordpress-0.4.22.zip)
-from the matching release. Historical releases may lack this asset. If that exact
-URL returns 404, build the same tag below; never silently install an older ZIP.
-The GitHub source-code ZIP is not an installable plugin. On a development machine
-with Node 22+, PHP 8.2+ with GMP/sodium, Composer and WP-CLI:
+Each GitHub release also attaches the same plugin as a ZIP, for a site that
+cannot reach WordPress.org or when WordPress.org does not list a release yet.
+Download [openreceive-wordpress-0.4.23.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.23/openreceive-wordpress-0.4.23.zip)
+and install it through **Plugins → Add New → Upload Plugin**. Historical
+releases may lack this asset. If that exact URL returns 404, build the same tag
+below; never silently install an older ZIP. The GitHub source-code ZIP is not
+an installable plugin. On a development machine with Node 22+, PHP 8.2+ with
+GMP/sodium, Composer and WP-CLI:
 
 ```sh
 git clone https://github.com/OpenReceive/openreceive.git
 cd openreceive
-git checkout v0.4.22
+git checkout v0.4.23
 npm ci
 npm run build:packages
 composer install --working-dir=packages/php/wordpress

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openreceive
 version: !ruby/object:Gem::Version
-  version: 0.4.22
+  version: 0.4.23
 platform: ruby
 authors:
 - OpenReceive
@@ -61,6 +61,7 @@ files:
 - skills/integrate-openreceive/references/fastapi.md
 - skills/integrate-openreceive/references/fastify.md
 - skills/integrate-openreceive/references/laravel.md
+- skills/integrate-openreceive/references/lovable.md
 - skills/integrate-openreceive/references/next.md
 - skills/integrate-openreceive/references/node.md
 - skills/integrate-openreceive/references/php.md