openreceive 0.4.24 → 0.4.26

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Next.js)
 
 ```sh
-# READ THIS FIRST: this file is 41 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 42 KB and a summary drops required steps. Download it whole:
 curl -fsSL https://openreceive.org/agent-directions/next/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/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.24.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -128,6 +128,8 @@ you store it. Ask one question per message.
    give a credential a `NEXT_PUBLIC_` prefix, which inlines it into the browser
    bundle. When the app is started with Docker Compose, give the service
    `env_file: .env.local`. Restart the dev 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
@@ -240,7 +242,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 `amountFor` 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 dollar
@@ -296,6 +303,12 @@ products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The library 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 `onSettled` on `<Checkout>`: `onPaid` has already
+  marked the order paid. Keep that checkout mounted, because it is the payer's
+  receipt.
 - **Pass this app's `db` handle.** Do not add a Prisma/Drizzle relation from
   Order to `openreceive_payments`, and do not implement `PaymentRepository`
   unless no supported handle can reach this database. `reference` is not unique
@@ -381,6 +394,7 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/serverless.md — when the app runs serverless (Netlify, AWS Lambda, Cloud Run, Google AI Studio): pooled database URLs, timeouts, and why it needs no cron or worker
 - https://openreceive.org/guides/node-orms.md — recipes for Prisma, Drizzle, Knex, TypeORM, Sequelize
 - https://openreceive.org/guides/frontend-checkout.md — the drop-in's props, attributes and slots
+- https://openreceive.org/guides/mobile-apps.md — when a mobile app takes the payment: the checkout page it opens, and what the App Store and Google Play allow
 - https://openreceive.org/guides/checkout-ux.md — read before building any custom UI
 - https://openreceive.org/guides/headless-checkout.md — the controller, the display models, refunds
 - https://openreceive.org/guides/provider-registry.md — where the wallet logos and pay
@@ -397,6 +411,7 @@ 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/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.md — the index, if what you need is not above
 
 Questions, or a problem with the library itself:

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Node.js)
 
 ```sh
-# READ THIS FIRST: this file is 37 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 39 KB and a summary drops required steps. Download it whole:
 curl -fsSL https://openreceive.org/agent-directions/node/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/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.24.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -125,6 +125,8 @@ you store it. Ask one question per message.
    `import "dotenv/config";` at the top of the server entry, as the quickstart
    does. When the app is started with Docker Compose, give the service
    `env_file: .env`. Restart the server after writing the file.
+   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
@@ -236,7 +238,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 `amountFor` 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 dollar
@@ -286,6 +293,13 @@ products, and you do not join them.
   expired invoice does not cancel the order; a later checkout may mint another
   attempt. The library 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 `onSettled` on `<Checkout>`, or 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 `db` handle.** Do not add a Prisma/Drizzle relation from
   Order to `openreceive_payments`, and do not implement `PaymentRepository`
   unless no supported handle can reach this database. `reference` is not unique
@@ -371,6 +385,7 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/serverless.md — when the app runs serverless (Netlify, AWS Lambda, Cloud Run, Google AI Studio): pooled database URLs, timeouts, and why it needs no cron or worker
 - https://openreceive.org/guides/node-orms.md — recipes for Prisma, Drizzle, Knex, TypeORM, Sequelize
 - https://openreceive.org/guides/frontend-checkout.md — the drop-in's props, attributes and slots
+- https://openreceive.org/guides/mobile-apps.md — when a mobile app takes the payment: the checkout page it opens, and what the App Store and Google Play allow
 - https://openreceive.org/guides/checkout-ux.md — read before building any custom UI
 - https://openreceive.org/guides/headless-checkout.md — the controller, the display models, refunds
 - https://openreceive.org/guides/provider-registry.md — where the wallet logos and pay
@@ -386,6 +401,7 @@ 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/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.md — the index, if what you need is not above
 
 Questions, or a problem with the library itself:

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 40 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 42 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.24.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -380,6 +393,7 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/environment-variables.md — every variable, and what is deliberately not one
 - 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 attributes and slots, and the standalone build
+- https://openreceive.org/guides/mobile-apps.md — when a mobile app takes the payment: the checkout page it opens, and what the App Store and Google Play allow
 - https://openreceive.org/guides/checkout-ux.md — read before building any custom UI
 - https://openreceive.org/guides/headless-checkout.md — the controller, the display models, refunds
 - https://openreceive.org/guides/provider-registry.md — where the wallet logos and pay
@@ -586,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,

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.24.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -364,6 +377,7 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/environment-variables.md — every variable, and what is deliberately not one
 - https://openreceive.org/guides/storage.md — the engine tables and the attempt state machine
 - https://openreceive.org/guides/frontend-checkout.md — the drop-in's props, attributes and slots
+- https://openreceive.org/guides/mobile-apps.md — when a mobile app takes the payment: the checkout page it opens, and what the App Store and Google Play allow
 - https://openreceive.org/guides/checkout-ux.md — read before building any custom UI
 - https://openreceive.org/guides/headless-checkout.md — the controller, the display models, refunds
 - https://openreceive.org/guides/provider-registry.md — where the wallet logos and pay

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.24.
+These directions describe OpenReceive 0.4.26.
 
 Install and configure the OpenReceive payment gateway in the WooCommerce store
 you are working in. Preserve its theme, checkout, customer accounts, order
@@ -95,7 +95,7 @@ is saved or the user said "Bitcoin only". Never invent a placeholder code.
 Install this release from the WordPress.org plugin directory:
 
 ```sh
-wp plugin install openreceive --version=0.4.24 --activate
+wp plugin install openreceive --version=0.4.26 --activate
 ```
 
 If that fails because WordPress.org does not have this version yet, install
@@ -103,7 +103,7 @@ 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.24/openreceive-wordpress-0.4.24.zip --activate
+wp plugin install https://github.com/OpenReceive/openreceive/releases/download/v0.4.26/openreceive-wordpress-0.4.26.zip --activate
 ```
 
 It needs WooCommerce active, and PHP 8.2+ with GMP and sodium in BOTH the web
@@ -252,7 +252,7 @@ database or application.
 
 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.24.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.24/openreceive-wordpress-0.4.24.zip)
+Download [openreceive-wordpress-0.4.26.zip](https://github.com/OpenReceive/openreceive/releases/download/v0.4.26/openreceive-wordpress-0.4.26.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
@@ -262,7 +262,7 @@ GMP/sodium, Composer and WP-CLI:
 ```sh
 git clone https://github.com/OpenReceive/openreceive.git
 cd openreceive
-git checkout v0.4.24
+git checkout v0.4.26
 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.24
+  version: 0.4.26
 platform: ruby
 authors:
 - OpenReceive
@@ -60,8 +60,10 @@ files:
 - skills/integrate-openreceive/references/django.md
 - skills/integrate-openreceive/references/fastapi.md
 - skills/integrate-openreceive/references/fastify.md
+- skills/integrate-openreceive/references/flask.md
 - skills/integrate-openreceive/references/laravel.md
 - skills/integrate-openreceive/references/lovable.md
+- skills/integrate-openreceive/references/nestjs.md
 - skills/integrate-openreceive/references/next.md
 - skills/integrate-openreceive/references/node.md
 - skills/integrate-openreceive/references/php.md