openreceive 0.4.21 → 0.4.23

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Fastify)
 
 ```sh
-# READ THIS FIRST: this file is 36 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 38 KB and a summary drops required steps. Download it whole:
 curl -fsSL https://openreceive.org/agent-directions/fastify/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/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.21.
+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
@@ -58,11 +58,12 @@ owns orders, users, prices, or fulfillment.
 
 ## 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.
+Before anything else, check one file: the project's `.env`, if it exists.
+`grep -E '^(NWC_URI|LSC_URI_PRIMARY)=.' .env | cut -d= -f1` names the codes
+it sets without printing them. Check with that, here and after each write,
+not by reading the file, 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
@@ -93,14 +94,17 @@ you store it. Ask one question per message.
    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:
+   `NWC_URI=<paste>` into the project's `.env` with your file-editing tool,
+   creating the file if needed. Never write it with a shell command (`echo`,
+   `printf`, a heredoc, `python -c`): the command line shows the code. 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 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
@@ -110,10 +114,10 @@ you store it. Ask one question per message.
    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.
+   `LSC_URI_PRIMARY=<paste>` to the same `.env` with the file-editing tool,
+   never a shell command. 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
@@ -148,23 +152,28 @@ Doctor reads `.env` itself. Never source it into a shell: the `&` in a
 code splits the value and prints the pieces.
 
 Give the user that checkout link. The browser check in the quickstart's step 6
-(payment-method icons, wallet logos, a pay tutorial) is theirs: tell them what
-to look at, and do not run it yourself.
+(payment-method icons, wallet logos, a pay tutorial) is theirs: name it in one
+line of your closing message, and do not run it yourself.
 
 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 (a wallet control port, a
 test endpoint, another wallet). If the user wants a real settlement test, they
 pay on that link from their own wallet, and `onPaid` marks the order paid.
 
-Setup ends here. Say "Setup is finished" in one message of at most five
-lines, with the link and what to check. Do not list what changed, offer more
-work, or end the message on a question.
+Setup ends here. Your last message starts "Setup is finished" and has at most
+five short lines (about 80 characters each): the link, the methods it offers,
+and one line of what to look at. Send nothing after it. Do not list what
+changed, copy out the quickstart's browser checklist, offer more work, or end
+the message on a question.
 
 - The link is to a real unpaid order. Keep that order; do not delete it.
+- When this app's orders belong to a session or cookie, the user's browser
+  cannot open the order you made. Then the link is the shop's own page:
+  "Open <shop url> and click Buy: it opens the checkout." Do not explain order
+  ownership or mention your test order.
 - Name the methods it offers: Bitcoin, plus USDT, USDC, ETH and SOL when
-  `LSC_URI_PRIMARY` is saved. Never say a coin will not work or will not be
-  offered. Swap minimums apply per order, and a coin whose minimum is above an
-  order's total says so on its own tile.
+  `LSC_URI_PRIMARY` is saved. Do not mention minimums, and never say a coin
+  will not work or will not be offered.
 
 ## Non-negotiables
 
@@ -181,6 +190,21 @@ itself, and they hold for every integration.
 - Work only in this application. Never read or run anything from another
   project on this machine (its `node_modules`, tools or source), for any
   reason. A browser and Playwright are not part of setup.
+- Restart only this app's server, on the port it already uses: stop the
+  process you started, or the one listening on that port, by its pid (or
+  restart its Compose service). Never `pkill` or `killall` by name: that
+  stops other people's servers too. Start it the way this project already
+  does (its README, Procfile, compose file or package script), on its own
+  port, not a port you pick.
+- Run commands where the app runs. When a compose file builds it, run its
+  package manager, generators, migrations and doctor inside that service
+  (`docker compose exec` or `run`), and rebuild the image after adding a
+  package. This machine's language version and database path are not the
+  app's.
+- To check that the running app sees the codes, run doctor: it reports each
+  one as present or missing and never prints a value. Never print the
+  environment (`printenv`, `env`, `docker compose config`), even filtered to
+  names.
 - The host owns the price. `amountFor` reads it from your own data; reject
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
@@ -256,7 +280,10 @@ products, and you do not join them.
   are buying.
 - **Users own the order; OpenReceive never sees them.** `authorize` uses the
   same ownership check this app already uses on the order show / pay page —
-  `sessions.currentUser(request)`, a cookie, whatever it is.
+  `sessions.currentUser(native)`, a cookie, whatever it is. Pass `native` (the
+  Fastify request) to this app's own cookie and session helpers, never
+  `request`: that one is a Web Request, a helper that reads
+  `req.headers.cookie` finds nothing on it, and every payer gets a 403.
   `resource.reference` is a claim the payer sent, not proof.
 - **The order is unpaid or paid.** Do not copy `pending` / `expired` / `failed`
   / `attention` onto it. Those are attempt statuses on `openreceive_payments`. An
@@ -521,11 +548,14 @@ await app.register(openReceiveFastify, {
   // Your own access check: may this caller do this action to this reference?
   // `resource.reference` is your own order id, sent back by the payer's
   // browser — a claim, not proof — already validated as a non-empty string.
-  // `native` is the untouched Fastify request, so a session decorated by
-  // @fastify/session (or whatever this app uses) is readable here too.
-  authorize: async ({ action, request, resource }) =>
+  // `native` is the untouched Fastify request: pass it to this app's own
+  // cookie and session helpers, and a session decorated by @fastify/session
+  // (or whatever this app uses) is readable on it. `request` is a Web
+  // Request, so a helper that reads `req.headers.cookie` finds nothing on it
+  // and every payer gets a 403.
+  authorize: async ({ action, native, resource }) =>
     orders.viewerMay(
-      await sessions.currentUser(request),
+      await sessions.currentUser(native),
       resource.reference,
       action,
     ),
@@ -541,7 +571,7 @@ await app.register(openReceiveFastify, {
 ```
 
 Register the plugin after whichever plugin gives you sessions or auth
-decorations, because `authorize` sees the same request object. The plugin
+decorations, because `native` is that same request object. The plugin
 handles shutdown for you. It registers an `onClose` hook that closes the
 wallet client together with the app, so you have no `ready`/`close` pair to
 manage. A deploy health check awaits `fastify.ready()` instead.

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 42 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.21.
+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
@@ -59,11 +59,12 @@ owns orders, users, prices, or fulfillment.
 
 ## 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.
+Before anything else, check one file: the project's `.env`, if it exists.
+`grep -E '^(NWC_URI|LSC_URI_PRIMARY)=.' .env | cut -d= -f1` names the codes
+it sets without printing them. Check with that, here and after each write,
+not by reading the file, 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 the package,
 edit the app, write `.env.example`, or search anywhere else before asking
@@ -94,14 +95,17 @@ you store it. Ask one question per message.
    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:
+   `NWC_URI=<paste>` into the project's `.env` with your file-editing tool,
+   creating the file if needed. Never write it with a shell command (`echo`,
+   `printf`, a heredoc, `python -c`): the command line shows the code. 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 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
@@ -111,16 +115,21 @@ you store it. Ask one question per message.
    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.
+   `LSC_URI_PRIMARY=<paste>` to the same `.env` with the file-editing tool,
+   never a shell command. 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.** Laravel loads
    `.env` itself. If the app runs `php artisan config:cache`, run
    `php artisan config:clear` (or re-cache) after writing the file: a cached
    config never reads `.env` again. When the app is started with Docker
-   Compose, give the service `env_file: .env`. Restart the server after
-   writing the file.
+   Compose, give the service `env_file: .env`. A Compose variable reaches
+   artisan commands, but not the web server: `php artisan serve` hands
+   requests only what `.env` holds, and php-fpm clears the environment by
+   default. So make the running app read the codes too: keep them in the
+   `.env` the server reads (an image that copies `.env.example` over it
+   drops them), start `php artisan serve` with `--no-reload`, or set
+   `clear_env = no` for php-fpm. 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
@@ -151,22 +160,28 @@ check; fix it before going on.
 
 Give the user that checkout link. The browser check in the quickstart's
 "Render the checkout" section (payment-method icons, wallet logos, a pay
-tutorial) is theirs: tell them what to look at, and do not run it yourself.
+tutorial) is theirs: name it in one line of your closing message, and do not
+run it yourself.
 
 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 (a wallet control port, a
 test endpoint, another wallet). If the user wants a real settlement test, they
 pay on that link from their own wallet, and `onPaid` marks the order paid.
 
-Setup ends here. Say "Setup is finished" in one message of at most five
-lines, with the link and what to check. Do not list what changed, offer more
-work, or end the message on a question.
+Setup ends here. Your last message starts "Setup is finished" and has at most
+five short lines (about 80 characters each): the link, the methods it offers,
+and one line of what to look at. Send nothing after it. Do not list what
+changed, copy out the quickstart's browser checklist, offer more work, or end
+the message on a question.
 
 - The link is to a real unpaid order. Keep that order; do not delete it.
+- When this app's orders belong to a session or cookie, the user's browser
+  cannot open the order you made. Then the link is the shop's own page:
+  "Open <shop url> and click Buy: it opens the checkout." Do not explain order
+  ownership or mention your test order.
 - Name the methods it offers: Bitcoin, plus USDT, USDC, ETH and SOL when
-  `LSC_URI_PRIMARY` is saved. Never say a coin will not work or will not be
-  offered. Swap minimums apply per order, and a coin whose minimum is above an
-  order's total says so on its own tile.
+  `LSC_URI_PRIMARY` is saved. Do not mention minimums, and never say a coin
+  will not work or will not be offered.
 
 ## Non-negotiables
 
@@ -183,6 +198,22 @@ itself, and they hold for every integration.
 - Work only in this application. Never read or run anything from another
   project on this machine (its `node_modules`, tools or source), for any
   reason. A browser and Playwright are not part of setup.
+- Restart only this app's server, on the port it already uses: stop the
+  process you started, or the one listening on that port, by its pid (or
+  restart its Compose service). Never `pkill` or `killall` by name: that
+  stops other people's servers too. Start it the way this project already
+  does (its README, Procfile, compose file or package script), on its own
+  port, not a port you pick.
+- Run commands where the app runs. When a compose file builds it, run its
+  package manager, generators, migrations and doctor inside that service
+  (`docker compose exec` or `run`), and rebuild the image after adding a
+  package. This machine's language version and database path are not the
+  app's.
+- To check that the running app sees the codes, run doctor: it reports each
+  one as present or missing and never prints a value. Never print the
+  environment (`printenv`, `env`, `docker compose config`), even filtered to
+  names. Doctor runs as an artisan command, so also open the checkout page:
+  the web server can miss a code that doctor sees (step 5).
 - The host owns the price. `amountFor` reads it from your own data; reject
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
@@ -386,16 +417,34 @@ 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:
 
 ```sh
-composer require openreceive/laravel
+composer require openreceive/laravel -W
 ```
 
-That is the whole install. `openreceive/laravel` depends on
+`-W` lets Composer move Guzzle to 7.x: the wallet client's WebSocket
+middleware needs Guzzle 7, and a Laravel 13 app can lock Guzzle 8. That is
+the whole install. `openreceive/laravel` depends on
 `openreceive/openreceive`, the engine. So the default wallet client works with
 nothing else added. It is built from `NWC_URI`. Package discovery registers the
 service provider. If your app brings its own NWC client, bind