openreceive 0.4.25 → 0.4.27

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (PHP)
 
 ```sh
-# READ THIS FIRST: this file is 41 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 43 KB and a summary drops required steps. Download it whole:
 curl -fsSL https://openreceive.org/agent-directions/php/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/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.25.
+These directions describe OpenReceive 0.4.27.
 
 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
@@ -124,6 +124,8 @@ you store it. Ask one question per message.
    front controller before `Service::fromEnvironment()`. When the app is started
    with Docker Compose, give the service `env_file: .env`. Restart PHP-FPM or
    the server after writing the file.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
 
 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
@@ -246,6 +248,10 @@ itself, and they hold for every integration.
   `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
   such window. On the element: the `resume-payment-hash` attribute, fed from
   the `openreceive-state` event (`event.detail.state.payment_hash`).
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
   https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `amountFor` and the drop-in renders it above the amount.
@@ -263,10 +269,11 @@ itself, and they hold for every integration.
   array keys, and the browser packages' TypeScript APIs are camelCase.
 - Money is integers or decimal strings — never binary floats. `amountFor`
   returns `'value' => '12.00'`, a string; never `12.00`.
-- PHP starts every request from nothing. The engine is built for that — the
-  settlement gate is a row in `openreceive_meta`, not process memory — so do
-  not add a cache, a static, or an APCu entry to "remember" the wallet or a
-  reconcile timer between requests.
+- PHP starts every request from nothing. The engine is built for that: the
+  settlement gate is a row in `openreceive_meta`, and under a web server
+  `Service::fromEnvironment()` keeps the wallet's info and the market data in
+  a private temp directory. So do not add a cache, a static, or an APCu entry
+  to "remember" the wallet or a reconcile timer between requests.
 
 ## Your tables, not ours
 
@@ -298,6 +305,12 @@ not replace your orders, users, or products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The engine refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from the `openreceive-settled` event on
+  `<openreceive-checkout>`: `onPaid` has already marked the order paid. Keep
+  that checkout mounted, because it is the payer's receipt.
 - **Pass this app's PDO.** `new SqlPaymentRepository(new PdoConnection($pdo))`
   over the connection the app already opens; do not implement
   `PaymentRepository` unless no PDO can reach this database. `reference` is not
@@ -587,8 +600,20 @@ if (str_starts_with($path, '/openreceive')) {
 
 `Service::fromEnvironment()` builds the wallet client from `NWC_URI` and runs
 the receive-only preflight. A missing, invalid or spend-capable code throws
-before any route is served. PHP starts every request from nothing, so that
-check runs on every request that reaches the engine.
+before any route is served.
+
+PHP starts every request from nothing. Without a cache, every checkout route
+would ask the wallet for its info event again and fetch the BTC price and the
+swap provider's currencies and rates again, which costs seconds per click.
+Under a web server, `fromEnvironment()` keeps them in a directory under the
+system temp dir that only the PHP user can open
+(`OpenReceive\Support\FileSharedCache`). The wallet's info is kept for 10
+minutes. A new code gets a new directory, so it is always checked live.
+Command-line runs, such as `bin/doctor` and the notifications worker, always
+ask the wallet. No secret goes in the cache: codes, payments and swap data
+stay out of it. If your app already runs a cache, pass it as `sharedCache:`
+([Service](https://openreceive.org/guides/api-reference.md#openreceiveserverservice)); `sharedCache: false`
+turns caching off.
 
 The settlement gate the engine relies on lives in `openreceive_meta`, not in
 memory. That is why a fleet of PHP-FPM workers shares one wallet-scan budget,
@@ -712,8 +737,11 @@ foreach (\OpenReceive\Server\Doctor::report(
 - where the handler is mounted;
 - the receive-only wallet preflight.
 
-`$engine->doctor()` is the same report for an engine you already built. Put it
-behind a `bin/doctor` script. The demo's is twelve lines.
+`$engine->doctor()` is the same report for an engine you already built, but it
+runs the wallet preflight only when you pass the same factory:
+`$engine->doctor(walletCheck: static fn () => \OpenReceive\Server\Service::fromEnvironment())`.
+Without it the preflight line reads `skipped`. Put the report behind a
+`bin/doctor` script. The demo's is twelve lines.
 → [Doctor](https://openreceive.org/guides/api-reference.md#openreceiveserverdoctor)
 
 Then open the checkout in a browser. Confirm the payment-method icons and

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Rails)
 
 ```sh
-# READ THIS FIRST: this file is 42 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 43 KB and a summary drops required steps. Download it whole:
 curl -fsSL https://openreceive.org/agent-directions/rails/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/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.25.
+These directions describe OpenReceive 0.4.27.
 
 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
@@ -122,6 +122,8 @@ you store it. Ask one question per message.
    add `dotenv-rails` to the Gemfile. When it is started with Docker Compose,
    give the service `env_file: .env`. Restart the server after writing the
    file; the values are read at boot.
+   Under Compose, recreate the container with `docker compose up -d`:
+   `docker compose restart` keeps its old environment.
 
 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
@@ -237,7 +239,12 @@ itself, and they hold for every integration.
   such window. On the drop-ins: `resumePaymentHash`, fed from `onState`, on
   `<Checkout>`; the `resume-payment-hash` attribute, fed from the
   `openreceive-state` event (`event.detail.state.payment_hash`), on
-  `<openreceive-checkout>`. https://openreceive.org/guides/swap-refunds.md
+  `<openreceive-checkout>`.
+  That visit can come hours later, and `authorize` must still know the payer:
+  a session that expired in between answers 403 and strands the deposit. On a
+  guest shop, tie the order to a long-lived signed cookie, or put a secret
+  per-order token in its URL that your page trades for that cookie.
+  https://openreceive.org/guides/swap-refunds.md
 - Show the payer WHAT THEY ARE BUYING. Return an optional `description` beside
   the price from `config.amount_for` and both drop-ins render it above the
   amount. Without it the checkout is a QR and "$1.00" with no sign of what the
@@ -282,6 +289,12 @@ not replace your orders, users, or products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The engine refuses a new checkout under a reference that already
   settled (409).
+- **A paid order's page says it is paid and shows no checkout.** Nothing is left
+  to pay, and a checkout cannot start a new payment for a paid order. Mount the
+  checkout only while the order is unpaid. When it settles on the page, update
+  the page's status line from the `openreceive-settled` event on
+  `<openreceive-checkout>`: `on_paid` has already marked the order paid. Keep
+  that checkout mounted, because it is the payer's receipt.
 - **Do not associate `OpenReceivePayment`.** No `has_many`, no `belongs_to`, no
   foreign key either direction. `reference` is not unique (many attempts per
   order). Fulfillment is a guarded transition on YOUR order row inside
@@ -409,13 +422,16 @@ That is the whole install. `openreceive-rails` depends on `openreceive`,
 nothing else added. It is built from `NWC_URI`. If your app brings its own NWC
 client, set `config.nwc_client` instead.
 
-There is one native prerequisite. `nwc-ruby` uses `rbsecp256k1`, which builds
-libsecp256k1 from source. Minimal images (`ruby:3.3-slim`, fresh Docker builds)
-need the autotools for that, or `bundle install` fails with
-`autoreconf: not found`. Install them before bundling:
+Two native builds need system packages. `nwc-ruby` uses `rbsecp256k1`, which
+builds libsecp256k1 from source and needs the autotools; without them
+`bundle install` fails with `autoreconf: not found`. Its connection libraries
+also need a newer `openssl` gem than Ruby ships, and Bundler compiles that gem
+against the OpenSSL headers; without them it fails installing `openssl` at
+`checking for openssl/ssl.h... no`. Minimal images (`ruby:3.3-slim`, fresh
+Docker builds) have neither. Install them before bundling:
 
 ```sh
-apt-get install -y autoconf automake libtool build-essential pkg-config
+apt-get install -y autoconf automake libtool build-essential pkg-config libssl-dev
 ```
 
 Full Ruby images and typical developer machines already have these.
@@ -603,9 +619,11 @@ settlement transaction, only for the first settled attempt for a reference.
 
 The engine's controllers inherit from `config.parent_controller`. The generated
 initializer sets it to `"ApplicationController"`. That is how the engine picks
-up your application's `protect_from_forgery`. Keep `csrf_meta_tags` in the
-layout that renders the checkout. The checkout client sends `X-CSRF-Token` from
-it automatically.
+up your application's `protect_from_forgery`. The layout that renders the
+checkout needs `<%= csrf_meta_tags %>` in its `<head>`: add it if it is not
+there. The checkout client sends `X-CSRF-Token` from it automatically; without
+it, every checkout answers 403 "Can't verify CSRF token authenticity". Do not
+skip forgery protection for the engine to get past that 403.
 
 The same inheritance also brings every global `before_action` that your
 `ApplicationController` declares. A filter that redirects signed-out users to a