openreceive 0.4.24 → 0.4.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd185f08cf0e3d60b0477eb5f109df48b386e58bac6e2dc9e68438d964f5b009
-  data.tar.gz: bf33fa7ac49d2baff5c17a39d5f88dd29fe5f0f1a3927368be29b41cb6bb0ab1
+  metadata.gz: 66faa619377624dd7e90952d52d7ef0210a0d0ce4726647b34534caef7225e11
+  data.tar.gz: 320f45f340b8e2138f7ae6a7ee0fb7c5e9703e3a42bd0c94692622afbd9bee41
 SHA512:
-  metadata.gz: 52511e9cf27f2cf168a3a8b5c59a0d71fa7b2f8d41e1db67ddda8dda32926b291119b952edc643132368ecec87057b51092d7f2574451c7b71c916ffa0c373cc
-  data.tar.gz: 89caad630814757eb881d325cb728173b28ebb8ff246697a5b92c2e7f0dc21dd8392683d99a4add6366ddb67182a571753ebbe8299b551f7a6018a5f6da9b23a
+  metadata.gz: a048e3a24ef863bfcc34d2277db739631dd529f701d44d7d310b33eec681649ef6942bb8169ff3e6b820591338027ab4b599d04070708249c1567b280b4dca0d
+  data.tar.gz: 67476c05c9dff09b48f41fed17e26ce81150e26089a81658b2e03023ab505e53fbf444f5487d2721ab0def24e3c91fbc352c56a4abd69e469cf8b7371694ad5e

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.26 - 2026-10-14
+
+Release with the complete 0.4.26 package family. The bundled agent skill's
+directions say that a paid order's page shows that it is paid and no
+checkout, and that a Docker Compose app recreates its container after
+writing `.env`. The plain PHP directions describe the engine's new default
+cache. No Ruby runtime changes from 0.4.25.
+
+## 0.4.25 - 2026-10-13
+
+Release with the complete 0.4.25 package family. The bundled agent skill
+adds directions for Flask and NestJS, and every server stack's directions
+link the new guide for mobile apps. No Ruby runtime changes from 0.4.24.
+
 ## 0.4.24 - 2026-10-12
 
 Release with the complete 0.4.24 package family. The gem's registry page

data/lib/openreceive/version.rb

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

data/skills/integrate-openreceive/SKILL.md

@@ -2,7 +2,7 @@
 name: integrate-openreceive
 description: >
   Integrate OpenReceive Bitcoin Lightning checkout and optional USDT, USDC,
-  SOL, and ETH swaps. Use for Node.js, Express, Fastify, Next.js, Rails,
+  SOL, and ETH swaps. Use for Node.js, Express, Fastify, Next.js, NestJS, Rails,
   Python, Django, FastAPI, Laravel, plain PHP, WordPress/WooCommerce,
   React, Vue, Svelte, Angular, or plain HTML applications, or connecting
   BTCPay Server to a receive-only NWC wallet. A configured swap provider
@@ -32,10 +32,13 @@ connected wallet; asset and network availability depends on the provider.
    - Node, Express: [references/node.md](references/node.md)
    - Node, Fastify: [references/fastify.md](references/fastify.md)
    - Node, Next.js App Router: [references/next.md](references/next.md)
+   - Node, NestJS (Express platform): [references/nestjs.md](references/nestjs.md)
    - Rails: [references/rails.md](references/rails.md)
    - Python, FastAPI: [references/fastapi.md](references/fastapi.md)
    - Plain PHP: [references/php.md](references/php.md)
    - Django: [references/django.md](references/django.md)
+   - Flask: [references/flask.md](references/flask.md) — a one-file Blueprint
+     copied from the quickstart; there is no `openreceive.flask` package.
    - 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):
@@ -51,11 +54,12 @@ connected wallet; asset and network availability depends on the provider.
 
 Install, per adapter — Express: `npm install @openreceive/express @openreceive/react`;
 Fastify: `npm install @openreceive/fastify @openreceive/react`; Next.js:
-`npm install @openreceive/next @openreceive/react`. Swap the UI package (`vue`,
+`npm install @openreceive/next @openreceive/react`; NestJS:
+`npm install @openreceive/express @openreceive/http @openreceive/react`. Swap the UI package (`vue`,
 `svelte`, `angular`, `elements`) for the frontend the app already has. Install
 (Rails): `bundle add openreceive-rails`.
 Django: `pip install "openreceive[django]"`; FastAPI:
-`pip install "openreceive[fastapi]"`; Laravel: `composer require openreceive/laravel`;
+`pip install "openreceive[fastapi]"`; Flask: `pip install "openreceive[sqlalchemy]"`; Laravel: `composer require openreceive/laravel`;
 plain PHP: `composer require openreceive/openreceive nyholm/psr7 nyholm/psr7-server`.
 
 ## The three server objects

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

@@ -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.24.
+These directions describe OpenReceive 0.4.26.
 
 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

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Django)
 
 ```sh
-# READ THIS FIRST: this file is 46 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 47 KB and a summary drops required steps. Download it whole:
 curl -fsSL https://openreceive.org/agent-directions/django/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/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.24.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -127,6 +127,8 @@ you store it. Ask one question per message.
    `settings.py` before anything reads the environment. 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
@@ -255,7 +257,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 `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
@@ -303,6 +310,12 @@ 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 relate to `OpenReceivePayment`.** No `ForeignKey`, no `OneToOne`, no
   `ManyToMany` either direction, and no admin `inline` on it. `reference` is not
   unique (many attempts per order). Fulfillment is a guarded transition on YOUR
@@ -391,6 +404,7 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/supabase.md — when the database is Supabase: its pooler, its certificate, and locking the tables away from its Data API
 - 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/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
@@ -406,7 +420,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 mounted engine'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/flask-recipe.md — the same engine as a Flask Blueprint, if this app is Flask after all
+- https://openreceive.org/agent-directions/flask.md — the same engine as a Flask Blueprint: follow those directions instead if this app is Flask after all
 - 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/fastapi.md

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (FastAPI)
 
 ```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/fastapi/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/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.24.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -126,6 +126,8 @@ you store it. Ask one question per message.
    with `uvicorn --env-file .env` (update the app's run script or Procfile, not
    just your own command). When it 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.
    Doctor needs the file too: run it as
    `dotenv -f .env run -- openreceive doctor …`. The `dotenv` command comes
    with python-dotenv, which `uvicorn --env-file` already needs; if it is
@@ -248,7 +250,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 `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 dollar
@@ -308,6 +315,13 @@ 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 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>`: `on_paid` has already
+  marked the order paid. Keep that checkout mounted, because it is the payer's
+  receipt.
 - **Pass a sync SQLAlchemy `Engine` for this app's database.** Do not add an
   ORM relationship from Order to `openreceive_payments`, and do not implement
   `PaymentRepository` unless no SQLAlchemy engine can reach this database.
@@ -392,6 +406,7 @@ enough; drop the `.md` for the same page a person would read.
 - https://openreceive.org/guides/supabase.md — when the database is Supabase: its pooler, its certificate, and locking the tables away from its Data API
 - 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/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
@@ -407,7 +422,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/flask-recipe.md — the same engine as a Flask Blueprint, if this app is Flask after all
+- https://openreceive.org/agent-directions/flask.md — the same engine as a Flask Blueprint: follow those directions instead if this app is Flask after all
 - https://openreceive.org/guides.md — the index, if what you need is not above
 
 Questions, or a problem with the library itself:
@@ -444,7 +459,7 @@ with the Django quickstart. A page without a bundler uses
 
 |          | Packages                                                                                                                      |
 | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Server   | `openreceive[fastapi]`, `openreceive[django]`, `openreceive[sqlalchemy]` (Flask and plain WSGI/ASGI: the Flask recipe) |
+| Server   | `openreceive[fastapi]`, `openreceive[django]`, `openreceive[sqlalchemy]` (Flask and plain WSGI/ASGI: [the Flask quickstart](https://openreceive.org/guides/quickstart-flask.md)) |
 | Frontend | `@openreceive/react`, `@openreceive/vue`, `@openreceive/svelte`, `@openreceive/angular`, `@openreceive/elements` (plain HTML) |
 
 Use `uv` or a virtualenv on Python 3.10 or newer. A system Python 3.9 cannot

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 38 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 40 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.24.
+These directions describe OpenReceive 0.4.26.
 
 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
@@ -123,6 +123,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
@@ -235,7 +237,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
@@ -290,6 +297,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
@@ -375,6 +389,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