openreceive 0.4.25 → 0.4.27

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 48 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.25.
+These directions describe OpenReceive 0.4.27.
 
 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
@@ -314,6 +327,27 @@ products, and you do not join them.
   classes would sit in front of the engine's own JSON-only, same-site and
   authorize gates and change the wire contract. Your DRF views stay yours.
 
+### If the database is Supabase
+
+Supabase is Postgres, so the tables above go there like any others. Three
+things differ; https://openreceive.org/guides/supabase.md has each in full.
+
+- Connect through its transaction pooler (port `6543`, user
+  `postgres.<project-ref>`). Run migrations through the session pooler
+  (port `5432` on the same host). Django already turns prepared statements off for PostgreSQL, which the
+  transaction pooler needs.
+- Verify Supabase's certificate authority: commit the project's
+  `prod-ca-2021.crt` (it is not a secret) and add
+  `?sslmode=verify-full&sslrootcert=prod-ca-2021.crt` to the URL.
+- After the migration, close both tables to Supabase's Data API, or anyone
+  with the project's anon key can read `swap_data`:
+
+  ```sql
+  alter table openreceive_payments enable row level security;
+  alter table openreceive_meta enable row level security;
+  revoke all on table openreceive_payments, openreceive_meta from anon, authenticated;
+  ```
+
 ## If you build your own checkout UI
 
 The engine serves JSON only, so the view is yours — but the drop-ins

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 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/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.25.
+These directions describe OpenReceive 0.4.27.
 
 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.
@@ -318,6 +332,27 @@ orders, users, or products, and you do not join them.
   second session from your ORM. Database writes only in the hook; emails,
   jobs, and pushes in `after_paid` or after commit.
 
+### If the database is Supabase
+
+Supabase is Postgres, so the tables above go there like any others. Three
+things differ; https://openreceive.org/guides/supabase.md has each in full.
+
+- Connect through its transaction pooler (port `6543`, user
+  `postgres.<project-ref>`). Run migrations through the session pooler
+  (port `5432` on the same host). The transaction pooler keeps no prepared statements: give the SQLAlchemy
+  engine `connect_args={"prepare_threshold": None}`.
+- Verify Supabase's certificate authority: commit the project's
+  `prod-ca-2021.crt` (it is not a secret) and add
+  `?sslmode=verify-full&sslrootcert=prod-ca-2021.crt` to the URL.
+- After the migration, close both tables to Supabase's Data API, or anyone
+  with the project's anon key can read `swap_data`:
+
+  ```sql
+  alter table openreceive_payments enable row level security;
+  alter table openreceive_meta enable row level security;
+  revoke all on table openreceive_payments, openreceive_meta from anon, authenticated;
+  ```
+
 ## If you build your own checkout UI
 
 The drop-ins (`<Checkout>`, `<openreceive-checkout>`) already obey all of this.

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 39 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 41 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.25.
+These directions describe OpenReceive 0.4.27.
 
 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
@@ -300,6 +314,30 @@ products, and you do not join them.
   only in the hook; emails, jobs, and pushes after commit. Placeholder style is
   the dialect you declared: `?` on sqlite, `$1` on postgres.
 
+### If the database is Supabase
+
+Supabase is Postgres, so the tables above go there like any others. Three
+things differ; https://openreceive.org/guides/supabase.md has each in full.
+
+- Connect through its transaction pooler (port `6543`, user
+  `postgres.<project-ref>`). Run migrations through the session pooler
+  (port `5432` on the same host).
+- Verify Supabase's certificate authority: delete `sslmode` from the URL and
+  give `pg` `ssl: { ca }`, the text of the project's `prod-ca-2021.crt` (an
+  environment variable such as `SUPABASE_CA_CERT`; it is not a secret). Never
+  `rejectUnauthorized: false`.
+- After the migration, close both tables to Supabase's Data API, or anyone
+  with the project's anon key can read `swap_data`:
+
+  ```sql
+  alter table openreceive_payments enable row level security;
+  alter table openreceive_meta enable row level security;
+  revoke all on table openreceive_payments, openreceive_meta from anon, authenticated;
+  ```
+
+`npx openreceive scaffold payments --supabase` writes the HTTPS-API route,
+which is for Cloudflare Workers only. A Node server uses the connection above.
+
 ## If you build your own checkout UI
 
 The drop-ins (`<Checkout>`, `<openreceive-checkout>`) already obey all of this.

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

@@ -3,7 +3,7 @@ This is the full file; follow it from Step 0.
 # OpenReceive agent directions (Flask)
 
 ```sh
-# READ THIS FIRST: this file is 43 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/flask/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/flask/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 Flask application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the engine is on PyPI
@@ -131,6 +131,8 @@ you store it. Ask one question per message.
    `dotenv -f .env run -- gunicorn …` (python-dotenv's CLI,
    `pip install "python-dotenv[cli]"`), in the app's run script or Procfile,
    not just your own command. 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 reads `.env` from its working directory by itself. Never `source`,
    `export` or `cat` the file: the codes contain `&`, and the shell prints the
    pieces.
@@ -252,7 +254,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
@@ -315,6 +322,12 @@ 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 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.
@@ -325,6 +338,27 @@ orders, users, or products, and you do not join them.
   `db.session`. Database writes only in the hook; emails,
   jobs, and pushes in `after_paid` or after commit.
 
+### If the database is Supabase
+
+Supabase is Postgres, so the tables above go there like any others. Three
+things differ; https://openreceive.org/guides/supabase.md has each in full.
+
+- Connect through its transaction pooler (port `6543`, user
+  `postgres.<project-ref>`). Run migrations through the session pooler
+  (port `5432` on the same host). The transaction pooler keeps no prepared statements: give the SQLAlchemy
+  engine `connect_args={"prepare_threshold": None}`.
+- Verify Supabase's certificate authority: commit the project's
+  `prod-ca-2021.crt` (it is not a secret) and add
+  `?sslmode=verify-full&sslrootcert=prod-ca-2021.crt` to the URL.
+- After the migration, close both tables to Supabase's Data API, or anyone
+  with the project's anon key can read `swap_data`:
+
+  ```sql
+  alter table openreceive_payments enable row level security;
+  alter table openreceive_meta enable row level security;
+  revoke all on table openreceive_payments, openreceive_meta from anon, authenticated;
+  ```
+
 ## If you build your own checkout UI
 
 The drop-ins (`<Checkout>`, `<openreceive-checkout>`) already obey all of this.

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 45 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 46 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.25.
+These directions describe OpenReceive 0.4.27.
 
 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
@@ -130,6 +130,8 @@ you store it. Ask one question per message.
    `.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.
+   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
@@ -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 `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
@@ -293,6 +300,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.
 - **Do not model `openreceive_payments`.** No Eloquent model, no `hasMany`, no
   `belongsTo`, no foreign key either direction. `reference` is not unique (many
   attempts per order). Fulfillment is a guarded transition on YOUR order row

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

@@ -17,7 +17,7 @@ If your fetch tool gave you a summary, fetch that URL again for the full text.
 - 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.25.
+These directions describe OpenReceive 0.4.27.
 
 Add OpenReceive to this Lovable app: a TanStack Start app on Cloudflare
 Workers, with Lovable Cloud or a connected Supabase project as its database.
@@ -26,6 +26,10 @@ 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.
 
+A TanStack Start app on a Node server you run, with its own Postgres, is not
+a Lovable app: follow https://openreceive.org/agent-directions/tanstack-start.md
+for it instead.
+
 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
@@ -117,7 +121,7 @@ saved or explicitly declined.
 
 ## Step 1 — the packages
 
-Add `@openreceive/http` and `@openreceive/react` at 0.4.25 or newer.
+Add `@openreceive/http` and `@openreceive/react` at 0.4.27 or newer.
 Nothing else: no `pg`, no Postgres driver, no OpenReceive scaffold. Do not
 change the Vite or Wrangler configuration.
 
@@ -157,6 +161,12 @@ every settlement.
 - **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`.
+- **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>`: `openreceive_on_paid`
+  has already marked the order paid. Keep that checkout mounted, because it is
+  the payer's receipt.
 
 ## Step 4 — `openreceive_on_paid`