openreceive 0.4.26 → 0.4.28

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 42 KB and a summary drops required steps. Download it whole:
+# READ THIS FIRST: this file is 44 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.26.
+These directions describe OpenReceive 0.4.28.
 
 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
@@ -68,7 +68,9 @@ server load the file), then the quickstart.
 On a hosted builder (v0, Vercel, Replit, Lovable), the user may say instead
 that both codes are already set as the project's environment variables or
 secrets. Believe them: do not ask for the codes, do not write `.env.local`, and
-do not read or print the variables. Next reads them from the environment.
+do not read or print the variables. Next reads them from the environment. Do not add them to a compose file or any other deploy config
+either: they already reach the app, and a line such as `NWC_URI: ${NWC_URI}`
+replaces them with an empty value.
 
 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
@@ -317,7 +319,31 @@ products, and you do not join them.
   app's equivalent) through the `query` the library hands you, on that same
   settlement transaction, not a second connection from your ORM. Database writes
   only in the hook; emails, jobs, and pushes after commit. Placeholder style is
-  the dialect you declared: `?` on sqlite, `$1` on postgres.
+  the dialect you declared: `?` on sqlite and mysql, `$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
 
@@ -535,13 +561,14 @@ export const dynamic = "force-dynamic";
 export const { GET, POST } = openReceiveNextHandlers({
   wallet: { nwc: process.env.NWC_URI! }, // receive-only NWC code; your app refuses to start otherwise
   storage: {
-    db, // pg Pool/Client, node:sqlite, better-sqlite3, or a custom adapter
+    db, // pg Pool/Client, mysql2 Pool, node:sqlite, better-sqlite3, or a custom adapter
     onPaid: async ({ reference, paidAt, query }) => {
       // Settlement transaction; runs only for the first settled attempt for a
       // reference. The WHERE clause is the lock: a second fulfillment path of
       // yours (admin action, replayed job) updates zero rows and does nothing.
-      // Use `query` here, not your ORM's other connection. `?` on sqlite, `$1`
-      // on postgres.
+      // Use `query` here, not your ORM's other connection. `?` on sqlite and
+      // mysql, `$1` on postgres. MySQL has no RETURNING: after the UPDATE,
+      // `SELECT ROW_COUNT() AS claimed` tells you the same thing.
       const claimed = await query(
         "UPDATE orders SET state = 'paid', paid_at = ? WHERE id = ? AND state = 'awaiting_payment' RETURNING id",
         [paidAt, reference],

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 39 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/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.26.
+These directions describe OpenReceive 0.4.28.
 
 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
@@ -65,7 +65,9 @@ server load the file), then the quickstart.
 On a hosted builder (v0, Vercel, Replit, Lovable), the user may say instead
 that both codes are already set as the project's environment variables or
 secrets. Believe them: do not ask for the codes, do not write `.env`, and
-do not read or print the variables. Skip step 5's file loading: the platform already puts them in `process.env`.
+do not read or print the variables. Skip step 5's file loading: the platform already puts them in `process.env`. Do not add them to a compose file or any other deploy config
+either: they already reach the app, and a line such as `NWC_URI: ${NWC_URI}`
+replaces them with an empty value.
 
 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
@@ -308,7 +310,31 @@ products, and you do not join them.
   app's equivalent) through the `query` the library hands you, on that same
   settlement transaction, not a second connection from your ORM. Database writes
   only in the hook; emails, jobs, and pushes after commit. Placeholder style is
-  the dialect you declared: `?` on sqlite, `$1` on postgres.
+  the dialect you declared: `?` on sqlite and mysql, `$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
 
@@ -517,13 +543,14 @@ app.use(express.json());
 const openreceive = openReceiveExpress({
   wallet: { nwc: process.env.NWC_URI! }, // receive-only NWC code; your app refuses to start otherwise
   storage: {
-    db, // pg Pool/Client, node:sqlite, better-sqlite3, or a custom adapter
+    db, // pg Pool/Client, mysql2 Pool, node:sqlite, better-sqlite3, or a custom adapter
     onPaid: async ({ reference, paidAt, query }) => {
       // Settlement transaction; runs only for the first settled attempt for a
       // reference. The WHERE clause is the lock: a second fulfillment path of
       // yours (admin action, replayed job) updates zero rows and does nothing.
-      // Use `query` here, not your ORM's other connection. `?` on sqlite, `$1`
-      // on postgres.
+      // Use `query` here, not your ORM's other connection. `?` on sqlite and
+      // mysql, `$1` on postgres. MySQL has no RETURNING: after the UPDATE,
+      // `SELECT ROW_COUNT() AS claimed` tells you the same thing.
       const claimed = await query(
         "UPDATE orders SET state = 'paid', paid_at = ? WHERE id = ? AND state = 'awaiting_payment' RETURNING id",
         [paidAt, reference],