openreceive 0.4.21 → 0.4.23

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

@@ -0,0 +1,531 @@
+This is the full file; follow it from Step 0.
+
+# OpenReceive agent directions (Lovable)
+
+```text
+READ THIS FIRST: this file is 25 KB and a summary drops required steps. Read all of it:
+https://openreceive.org/agent-directions/lovable/full.md
+If your fetch tool gave you a summary, fetch that URL again for the full text.
+```
+
+**Step 0 in brief** (Step 0 below has the details):
+
+- Before adding packages or editing anything, ask the user for a receive-only NWC code. One question per message.
+- Next ask for the LSC code. If the user wants stablecoins, USDT, USDC, ETH, SOL or crypto, do not ask yes/no first.
+- Ask for NWC_URI and LSC_URI_PRIMARY with Lovable's secret input. Never put a code in .env, code or a VITE_ name.
+- You have no terminal: never ask the user to run a command. Every step is a file, a package, a migration or a secret.
+- 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.23.
+
+Add OpenReceive to this Lovable app: a TanStack Start app on Cloudflare
+Workers, with Lovable Cloud or a connected Supabase project as its database.
+These directions are written for Lovable's agent. You have no terminal, so
+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.
+
+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
+database.
+
+## What OpenReceive is
+
+A payment library that runs inside THIS app's server code. It mounts as one
+TanStack Start server route (`src/routes/openreceive.$.ts`), issues Lightning
+invoices against a wallet the merchant already controls, and settles each
+payment into this app's Supabase database. There is no OpenReceive account
+and no API key, and OpenReceive never holds the funds: the sats land in the
+merchant's wallet.
+
+The one required credential is a receive-only NWC code (Nostr Wallet
+Connect): a string from the merchant's wallet that can create invoices and
+read their status, and cannot spend. A swap provider (an "LSC" code)
+optionally lets the payer send USDT, USDC, ETH or SOL instead, converted into
+that same Lightning payment. Step 0 collects those credentials. You write two
+hooks in TypeScript, `amountFor` and `authorize`, and one SQL function,
+`openreceive_on_paid`, that marks the order paid. OpenReceive supplies
+invoices, polling, settlement and the checkout UI. It never owns orders,
+users, prices, or fulfillment.
+
+On Lovable, OpenReceive keeps its payment rows in this app's Supabase
+database and reaches it over Supabase's HTTPS API with the project's secret
+key, because a Worker cannot open a Postgres connection to Supabase.
+
+## Step 0 — ask for the two codes, one secret at a time
+
+If the user says the codes are already saved as this project's secrets
+(`NWC_URI`, and `LSC_URI_PRIMARY` unless they want Bitcoin only), believe
+them: do not ask for them, and go to Step 1. You cannot read a secret's value,
+and you do not need to.
+
+Otherwise, before anything else, your next action is a question to the user.
+Do not add packages, write migrations or edit files before asking it. A new
+shop has neither code yet.
+
+Two server-only secrets are needed before the integration:
+
+- `NWC_URI` — a receive-only Nostr Wallet Connect code,
+  `nostr+walletconnect://…`. Required for Bitcoin.
+- `LSC_URI_PRIMARY` — a Lightning Swap Connect URI,
+  `lightning+swapconnect://…`. Required for USDT, USDC, ETH and SOL. Skip it
+  only when the user says they want Bitcoin alone.
+
+Ask for each one with Lovable's secure secret input, named exactly as above.
+The user never edits a file: they paste each code into this chat or into
+that secret input, and Lovable stores it as a project secret. A code pasted
+into the chat is saved as a secret too. Never repeat a code back. Ask one
+question per message.
+
+1. **First message — the NWC code, and nothing else.** Ask for the secret
+   `NWC_URI` and walk them through getting it:
+
+   > To receive payments I need a receive-only wallet code. In Rizful: open
+   > the menu, tap NWC, choose Receive-only NWC code, and tap Copy
+   > (https://openreceive.org/get_a_nwc_code_to_receive_payments). If you would
+   > rather run your own wallet, Alby Hub works too: Connections → Add
+   > Connection → Read Only. Paste it into the secret input for NWC_URI.
+
+2. **When it is saved.** If the user pasted it into the chat and it does not
+   start with `nostr+walletconnect://`, ask them to copy the receive-only code
+   again. Reply only that it is saved, then ask the next question.
+3. **Second message — swaps.** If the user asked for stablecoins, USDT, USDC,
+   ETH, SOL, altcoins or "crypto" (as in "Bitcoin and stablecoin payments"),
+   this message IS the walkthrough below: send it as it is, and do not ask yes
+   or no first. Otherwise ask whether payers should also be able to pay with
+   USDT, USDC, ETH or SOL, then give the walkthrough. The walkthrough:
+
+   > Go to https://lightning-swap.com, sign in for API keys, create a key, and
+   > copy the whole URI (https://openreceive.org/set_up_swap_provider). Paste
+   > it into the secret input for LSC_URI_PRIMARY — or say "Bitcoin only" and
+   > I will continue without it.
+
+   Mention FixedFloat only if they already use it. Swaps on means the refund
+   route back is part of this integration (the swap non-negotiable below).
+4. **Supabase.** Lovable sets `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY`
+   for server code when Lovable Cloud, or a connected Supabase project, is on.
+   Do not ask for them or try to create them: Lovable reserves the
+   `SUPABASE_` prefix. If this project has no backend yet, ask the user to
+   turn on Lovable Cloud, and wait until they have.
+
+Never give a code a `VITE_` prefix, never put one in `.env` (Lovable commits
+that file), and never write one into code or a log. Do not invent placeholder
+codes. Start Step 1 only once `NWC_URI` is saved and `LSC_URI_PRIMARY` is
+saved or explicitly declined.
+
+## Step 1 — the packages
+
+Add `@openreceive/http` and `@openreceive/react` at 0.4.23 or newer.
+Nothing else: no `pg`, no Postgres driver, no OpenReceive scaffold. Do not
+change the Vite or Wrangler configuration.
+
+## Step 2 — the migration
+
+Fetch https://openreceive.org/guides/supabase-migration.md and copy its SQL
+block, unchanged, into one new Supabase migration, then apply it. Do not edit
+it, split it, rename anything in it, or drop its `revoke` lines. It creates
+`openreceive_payments` and `openreceive_meta` with row level security on and
+every grant revoked from `anon` and `authenticated`, the functions the server
+calls to write them, and `openreceive_on_paid` as a placeholder that refuses
+every settlement.
+
+## Step 3 — the order and its buyer
+
+- **The order's id is the `reference`.** Create the order before checkout,
+  keep it across retries, never reuse it. A fresh id per page load lets one
+  order be paid twice.
+- **The order row is the price.** Order creation copies live prices into the
+  order. `amountFor` reads only that order and returns
+  `{ currency, value, description }`, the value a decimal string such as
+  `"12.50"`, and `null` for an order that is not payable.
+- **The buyer is a cookie.** The checkout calls the payment routes from the
+  browser with the page's cookies and nothing else, and a Lovable app keeps
+  its Supabase sign-in in the browser, not in a cookie. So in a migration add
+  `buyer_token text` to the orders table, and create orders in a server
+  function (`createServerFn`) that reads the `buyer` cookie, or sets one to
+  `crypto.randomUUID()` (HttpOnly, Secure, SameSite=Lax, path `/`, one
+  year) with `getCookie` and `setCookie` from `@tanstack/react-start/server`,
+  then inserts the order with `buyer_token` set to it through `supabaseAdmin`
+  from `@/integrations/supabase/client.server`, and returns the id. If the app
+  creates orders in the browser today, move that insert into this function.
+  Keep the order's user column too, if the app has sign-in.
+- **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`.
+
+## Step 4 — `openreceive_on_paid`
+
+In a second new migration, replace the placeholder with the SQL that marks
+this app's order paid. Use `create or replace`, and this app's own table,
+column and status names:
+
+```sql
+create or replace function public.openreceive_on_paid(
+  p_reference text, p_payment_hash text, p_paid_at bigint
+) returns void language plpgsql as $$
+begin
+  update public.orders
+     set status = 'paid'
+   where id = p_reference::uuid   -- or just p_reference, if the ids are text
+     and status = 'pending';
+end
+$$;
+```
+
+It runs inside the transaction that records the payment, for the order's
+first settled payment only. If it raises, nothing is recorded, and the next
+request retries it. Its `WHERE` on the unpaid status is the guard against a
+second fulfillment. Keep it to database writes.
+
+## Step 5 — the payment route
+
+Write `src/routes/openreceive.$.ts` and `src/lib/openreceive.server.ts`
+exactly as the recipe's "On Supabase (Lovable)" section shows:
+
+- `storage: { supabase: { url: process.env.SUPABASE_URL, key: process.env.SUPABASE_SERVICE_ROLE_KEY } }`,
+  read inside the handler, never at module scope.
+- No `onPaid` and no `db`: `openreceive_on_paid` is the fulfillment.
+- `findOrder` reads the order with `supabaseAdmin`; `authorize` compares the
+  request's `buyer` cookie with the order's `buyer_token`.
+- Build the stack inside each request and close it in `finally`.
+- Import the server module only inside the route's handlers, so it never
+  reaches the browser bundle.
+
+## Step 6 — the checkout page
+
+Add `src/routes/checkout.$reference.tsx` with `<Checkout reference={reference}
+prefix="/openreceive" />` from `@openreceive/react`, and import
+`@openreceive/react/styles.css` there. After the order is created, navigate
+to `/checkout/<id>`. Use the drop-in; do not build your own checkout UI.
+
+## After setup — hand over, then stop
+
+You cannot pay the invoice: the code is receive-only. Do not pay, settle or
+mark an order paid, and do not look for a way to.
+
+If the checkout answers 503, the server log names the fix: usually the
+migration is not applied, or `openreceive_on_paid` is still the placeholder.
+
+Setup ends here. Your last message starts "Setup is finished" and has at most
+five short lines: where to place an order in the preview, the methods the
+checkout offers, and that a small real payment from their own wallet marks
+the order paid. Send nothing after it. Do not list what changed, offer more
+work, or end the message on a question. Name the methods: Bitcoin, plus
+USDT, USDC, ETH and SOL when `LSC_URI_PRIMARY` is saved. Do not mention
+minimums, and never say a coin will not work or will not be offered.
+
+## Non-negotiables
+
+The recipe below has the code. These are the rules it cannot state for
+itself.
+
+- OpenReceive never owns orders, users, prices, or fulfillment.
+- Keep `NWC_URI` / `LSC_URI_*` server-only: secrets read with `process.env`
+  in `.server.ts` modules. Never a `VITE_` variable, `.env`, browser code or
+  a log.
+- Do not suggest rotating, revoking or replacing a code because it was pasted
+  into this chat; that is the supported path.
+- `SUPABASE_SERVICE_ROLE_KEY` reads and writes every table. Read it only in
+  server modules.
+- Never grant `anon` or `authenticated` anything on an `openreceive_*` table
+  or function, and never add a row level security policy to those tables.
+  The server refuses to serve while they can reach them.
+- The host owns the price. `amountFor` reads it from the order; reject
+  payer-supplied amounts.
+- `authorize` runs on every request, and the `resource` it receives is a CLAIM
+  the payer made, not proof. Check the `buyer` cookie against the order.
+- Receive-only NWC is required; a spend-capable code fails closed unless
+  explicitly overridden. Never set that override.
+- There is NO merchant-initiated refund of a settled Lightning payment, because
+  the wallet cannot spend. Swap refunds — a payer reclaiming a deposit that
+  never converted — are the only refund OpenReceive performs. Do not build,
+  promise, or imply a Lightning refund path.
+- IF YOU TURN SWAPS ON, BUILD THE ROUTE BACK. A deposit that arrives short or
+  late is refunded on a SECOND visit, so the order needs its own URL
+  (`/checkout/$reference`, with `syncUrl` on `<Checkout>`), and the attempt
+  must come back with it: keep the `payment_hash` from `onState` and pass it
+  as `resumePaymentHash`. https://openreceive.org/guides/swap-refunds.md
+- Show the payer what they are buying: return a `description` beside the
+  price from `amountFor`.
+- HTTP JSON is snake_case; TypeScript APIs are camelCase.
+- Money is integers or decimal strings — never binary floats.
+
+## More documentation
+
+Fetch one when the moment comes. Each is raw markdown, so a plain GET is
+enough.
+
+- https://openreceive.org/guides/lovable.md — what the user does on Lovable around these steps
+- https://openreceive.org/guides/supabase.md — Supabase over HTTPS: how the storage works, and what the server checks before it serves
+- https://openreceive.org/guides/supabase-migration.md — the migration for Step 2
+- https://openreceive.org/guides/authorization.md — before you write `authorize`
+- 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 props, including `syncUrl` and `resumePaymentHash`
+- https://openreceive.org/guides/checkout-ux.md — the rules the drop-in already follows
+- https://openreceive.org/guides/provider-registry.md — where the wallet logos and pay tutorials come from: inside the JavaScript, nothing to serve
+- https://openreceive.org/guides/automated-swaps.md — only if `LSC_URI_PRIMARY` is set
+- https://openreceive.org/guides/swap-refunds.md — the refund flow, and the route back to it
+- https://openreceive.org/guides/lightning-swap-connect.md — what an `LSC_URI_*` code actually is
+- https://openreceive.org/guides/environment-variables.md — every variable, and what is deliberately not one
+- https://openreceive.org/guides/price-feeds.md — where the fiat→sats rate comes from
+- https://openreceive.org/guides/rate-limiting.md — before a public shop goes live
+- https://openreceive.org/guides/security.md and https://openreceive.org/guides/deploying.md — before this goes anywhere real
+- https://openreceive.org/guides/api-reference.md — every route, option and error code
+- https://openreceive.org/guides.md — the index, if what you need is not above
+
+Questions, or a problem with the library itself:
+https://openreceive.org/contact
+
+---
+
+## The quickstart, in full
+
+Inlined verbatim so this file needs no network access. Steps 0–6 above are the setup on Lovable and this recipe is their reference: follow its On Supabase (Lovable) section, not its pg pool, and skip its npm commands. Where the two differ, the steps win.
+The page it comes from is https://openreceive.org/guides/tanstack-start-recipe.
+
+## TanStack Start recipe
+
+OpenReceive ships no TanStack Start package. A TanStack Start server route
+takes a Web-standard `Request` and returns a `Response`, and so does
+`@openreceive/http`, so the integration is the route below. Your server code
+creates each Lightning invoice, the payment goes straight to your wallet, and
+payment attempts are stored in your app's Postgres database. There is no
+OpenReceive account and no background worker.
+
+Optional swaps let customers pay with **USDT, USDC, SOL, and ETH**. A swap
+provider you configure converts the payment to **BTC over Lightning**, and it
+settles into the same wallet. Available assets and networks depend on the
+provider.
+
+This recipe was checked with `@tanstack/react-start` 1.168 and
+`@openreceive/*` 0.4.19. The app was built with Lovable's Vite config for
+Cloudflare Workers and run under workerd: a buyer's checkout showed a real
+Lightning invoice, and a stranger was refused. The Supabase route below runs
+in OpenReceive's CI as a Worker, against Supabase's own Postgres image and
+API server: a buyer's invoice, a stranger refused, one live attempt under
+concurrent requests, and a payment that `openreceive_on_paid` fulfills once.
+
+```sh
+npm install @openreceive/http @openreceive/react pg
+```
+
+### Where it runs
+
+- **Node** (the `node-server` preset, or any Node host): any Postgres.
+- **Cloudflare Workers** (the `cloudflare-module` preset, Lovable's default):
+  with Node compatibility, and a Postgres whose certificate a public
+  authority signed, such as Neon.
+- **Cloudflare Workers with Supabase**, which is every Lovable app: a Worker
+  cannot open a Postgres connection to Supabase, whose certificate comes from
+  a private authority. Use [On Supabase](#on-supabase-lovable) below, which
+  stores payments through Supabase's HTTPS API instead.
+
+Workers ties every socket to the request that opened it, and forbids network
+calls at import. So the route builds its database pool and its OpenReceive
+stack inside each request, and closes both before it responds. Each request
+then opens its own wallet connection; in our test a checkout request took one
+to four seconds. The same code works on Node.
+
+### The payment route
+
+Keep the handler in a `.server.ts` module. Route files are also bundled for
+the browser, so the route loads the module only when a request arrives:
+
+```ts
+// src/routes/openreceive.$.ts — every route under /openreceive/
+import { createFileRoute } from "@tanstack/react-router";
+
+async function openReceive({ request }: { request: Request }): Promise<Response> {
+  const { handleOpenReceive } = await import("@/lib/openreceive.server");
+  return handleOpenReceive(request);
+}
+
+export const Route = createFileRoute("/openreceive/$")({
+  server: { handlers: { GET: openReceive, POST: openReceive } },
+});
+```
+
+```ts
+// src/lib/openreceive.server.ts
+import { createStack } from "@openreceive/http";
+import pg from "pg";
+import { findOrder, currentVisitor } from "./orders.server"; // your own orders
+
+export async function handleOpenReceive(request: Request): Promise<Response> {
+  // Read process.env inside the handler: on Workers it is empty at import.
+  const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL, max: 1 });
+  const stack = createStack({
+    wallet: { nwc: process.env.NWC_URI ?? "" },
+    storage: {
+      db: pool,
+      // Runs once, inside the transaction that records the payment.
+      onPaid: async ({ reference, paidAt, query }) => {
+        await query(
+          "UPDATE orders SET state = 'paid', paid_at = $1 WHERE id = $2 AND state = 'awaiting_payment'",
+          [paidAt, reference],
+        );
+      },
+    },
+    // The price comes from the order row, never from the request.
+    amountFor: async (reference) => {
+      const order = await findOrder(pool, reference);
+      return order?.state === "awaiting_payment"
+        ? { currency: order.currency, value: order.amount, description: order.title }
+        : null;
+    },
+    // Only the buyer may pay for their order.
+    authorize: async ({ request: incoming, resource }) => {
+      const order = resource.reference ? await findOrder(pool, resource.reference) : undefined;
+      const visitor = currentVisitor(incoming);
+      return Boolean(order && visitor && order.visitor === visitor);
+    },
+    // Cloudflare sets cf-connecting-ip on every request, and a client cannot.
+    // On Node behind your own proxy, read the header that proxy sets.
+    rateLimiting: {
+      ip: ({ request: incoming }) => incoming.headers.get("cf-connecting-ip") ?? undefined,
+    },
+  });
+  try {
+    return await stack.handler(request, { native: request });
+  } finally {
+    await stack.close();
+    await pool.end();
+  }
+}
+```
+
+`authorize` sees the incoming request with its cookies, so check it with
+the session your app already has. The Next.js quickstart
+explains each hook. They are the same here.
+
+Create OpenReceive's two tables with your migrations, or run
+`paymentsSchemaSql("postgres")` from `@openreceive/http` once. It is
+idempotent. See Payment storage.
+
+### On Supabase (Lovable)
+
+On Supabase the route keeps payments in your Supabase database through its
+HTTPS API, with the project's secret key. There is no `pg` pool. Use
+`@openreceive/*` 0.4.23 or newer:
+
+```sh
+npm install @openreceive/http @openreceive/react
+```
+
+1. Apply the migration from `npx openreceive scaffold payments --supabase`.
+   It creates OpenReceive's tables, locked away from the browser's Supabase
+   key, and the functions that write them.
+2. Replace its placeholder `openreceive_on_paid` with the SQL that marks your
+   order paid. It runs inside the transaction that records the payment, for
+   the order's first payment only, so a failure there records nothing:
+
+   ```sql
+   create or replace function public.openreceive_on_paid(
+     p_reference text, p_payment_hash text, p_paid_at bigint
+   ) returns void language plpgsql as $$
+   begin
+     update public.orders set status = 'paid'
+      where id = p_reference::uuid and status = 'pending';
+   end
+   $$;
+   ```
+
+3. Write the route's server module:
+
+```ts
+// src/lib/openreceive.server.ts
+import { createStack } from "@openreceive/http";
+import { findOrder, currentBuyer } from "./orders.server"; // your own orders
+
+export async function handleOpenReceive(request: Request): Promise<Response> {
+  // Read process.env inside the handler: on Workers it is empty at import.
+  // Lovable sets SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY for server code.
+  const stack = createStack({
+    wallet: { nwc: process.env.NWC_URI ?? "" },
+    storage: {
+      supabase: {
+        url: process.env.SUPABASE_URL ?? "",
+        key: process.env.SUPABASE_SERVICE_ROLE_KEY ?? "",
+      },
+    },
+    // The price comes from the order row, never from the request.
+    amountFor: async (reference) => {
+      const order = await findOrder(reference);
+      return order?.status === "pending"
+        ? { currency: order.currency, value: order.total, description: order.title }
+        : null;
+    },
+    // Only the buyer may pay for their order.
+    authorize: async ({ request: incoming, resource }) => {
+      const order = resource.reference ? await findOrder(resource.reference) : null;
+      const buyer = currentBuyer(incoming);
+      return Boolean(order && buyer && order.buyer_token === buyer);
+    },
+    rateLimiting: {
+      ip: ({ request: incoming }) => incoming.headers.get("cf-connecting-ip") ?? undefined,
+    },
+  });
+  try {
+    return await stack.handler(request, { native: request });
+  } finally {
+    await stack.close();
+  }
+}
+```
+
+There is no `onPaid`: `openreceive_on_paid` is the fulfillment. `findOrder`
+reads the order with your server-side Supabase client; in a Lovable app that
+is `supabaseAdmin` from `@/integrations/supabase/client.server`.
+
+The checkout calls the payment routes from the browser with the page's
+cookies, and nothing else. A Lovable app keeps its Supabase sign-in in the
+browser, not in a cookie, so `authorize` cannot see who is signed in. Give
+the buyer a cookie of their own instead: create orders in a server function
+that sets an HttpOnly `buyer` cookie (a random value, kept across orders) and
+stores the same value on the order as `buyer_token`. `currentBuyer` reads it
+back from the request's `cookie` header.
+
+Before it serves, the server checks the database, and the payment routes
+answer 503 until the migration is applied and `openreceive_on_paid` is
+yours; the log names the fix. More: Supabase over HTTPS.
+
+### The checkout page
+
+```tsx
+// src/routes/checkout.$reference.tsx
+import { Checkout } from "@openreceive/react";
+import "@openreceive/react/styles.css";
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/checkout/$reference")({
+  component: OrderCheckout,
+});
+
+function OrderCheckout() {
+  const { reference } = Route.useParams();
+  return <Checkout reference={reference} prefix="/openreceive" />;
+}
+```
+
+It renders on the server and starts the checkout in the browser. The payer
+picks Bitcoin and gets the invoice.
+
+### Settings
+
+- `NWC_URI`: a receive-only code from your wallet
+  ([get one](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
+  Optional: `LSC_URI_PRIMARY` for swaps
+  ([set one up](https://openreceive.org/set_up_swap_provider)).
+- `DATABASE_URL`: your Postgres. On serverless hosts use the pooled URL. The
+  storage is tested through a transaction pooler.
+- On Supabase over HTTPS, instead of `DATABASE_URL`: `SUPABASE_URL` and the
+  secret key in `SUPABASE_SERVICE_ROLE_KEY`. Lovable sets both itself.
+
+Set them as server secrets, never with a `VITE_` prefix, which would put them
+in the browser bundle.
+
+No worker or cron job is needed. Each request to the payment routes also
+checks the wallet for settled invoices, through a lock in your database. A
+payer who closes the tab is settled on the next request.

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 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/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.21.
+These directions describe OpenReceive 0.4.23.
 
 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
@@ -58,11 +58,12 @@ owns orders, users, prices, or fulfillment.
 
 ## Step 0 — ask for the two codes, one question at a time
 
-Before anything else, look at one file: the project's `.env.local`, if it exists.
-Read it only far enough to see whether `NWC_URI` and `LSC_URI_PRIMARY` are
-there and non-empty, and never print the values. A code that is already
-set is not asked for again; if both are set, skip to step 5
-(making the server load the file), then the quickstart.
+Before anything else, check one file: the project's `.env.local`, if it exists.
+`grep -E '^(NWC_URI|LSC_URI_PRIMARY)=.' .env.local | cut -d= -f1` names the codes
+it sets without printing them. Check with that, here and after each write,
+not by reading the file, and never print the values. A code that is already
+set is not asked for again; if both are set, skip to step 5 (making the
+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
@@ -98,14 +99,17 @@ you store it. Ask one question per message.
    Do not mention `.env`, exports, or "tell me when it's set".
 2. **When they paste it.** If it does not start with `nostr+walletconnect://`,
    ask them to copy the receive-only code again. Otherwise write
-   `NWC_URI=<paste>` into the project's `.env.local`, creating the file if needed.
-   Make sure `.gitignore` covers `.env.local` (and `.dockerignore`, if the app has
-   one). Never echo the value, commit it, or put it in client code. Reply only
-   that it is saved, then ask the next question.
-3. **Second message — swaps.** If the user already asked for stablecoins or
-   altcoins, skip the yes/no and go straight to the walkthrough. Otherwise ask
-   whether payers should also be able to pay with USDT, USDC, ETH or SOL. The
-   walkthrough:
+   `NWC_URI=<paste>` into the project's `.env.local` with your file-editing
+   tool, creating the file if needed. Never write it with a shell command
+   (`echo`, `printf`, a heredoc, `python -c`): the command line shows the
+   code. Make sure `.gitignore` covers `.env.local` (and `.dockerignore`, if
+   the app has one). Never echo the value, commit it, or put it in client
+   code. Reply only that it is saved, then ask the next question.
+3. **Second message — swaps.** If the user asked for stablecoins, USDT, USDC,
+   ETH, SOL, altcoins or "crypto" (as in "Bitcoin and stablecoin payments"),
+   this message IS the walkthrough below: send it as it is, and do not ask yes
+   or no first. Otherwise ask whether payers should also be able to pay with
+   USDT, USDC, ETH or SOL, then give the walkthrough. The walkthrough:
 
    > Go to https://lightning-swap.com, sign in for API keys, create a key, and
    > copy the whole URI (https://openreceive.org/set_up_swap_provider). Paste
@@ -115,10 +119,10 @@ you store it. Ask one question per message.
    Mention FixedFloat only if they already use it.
 4. **When they paste it.** If it does not start with
    `lightning+swapconnect://`, ask them to copy it again. Otherwise add
-   `LSC_URI_PRIMARY=<paste>` to the same `.env.local`, without echoing it. Swaps
-   are now on, so build the refund route back (the swap non-negotiable below) as
-   part of this integration. If they chose Bitcoin only, leave
-   `LSC_URI_PRIMARY` unset and skip that route.
+   `LSC_URI_PRIMARY=<paste>` to the same `.env.local` with the file-editing
+   tool, never a shell command. Swaps are now on, so build the refund route
+   back (the swap non-negotiable below) as part of this integration. If they
+   chose Bitcoin only, leave `LSC_URI_PRIMARY` unset and skip that route.
 5. **Make the server load the file — yourself.** Next loads
    `.env.local` into `process.env` on its own: do not add `dotenv`, and never
    give a credential a `NEXT_PUBLIC_` prefix, which inlines it into the browser
@@ -153,23 +157,28 @@ Doctor reads `.env.local` itself. Never source it into a shell: the `&` in a
 code splits the value and prints the pieces.
 
 Give the user that checkout link. The browser check in the quickstart's step 6
-(payment-method icons, wallet logos, a pay tutorial) is theirs: tell them what
-to look at, and do not run it yourself.
+(payment-method icons, wallet logos, a pay tutorial) is theirs: name it in one
+line of your closing message, and do not run it yourself.
 
 You cannot pay the invoice: the code is receive-only. Do not pay, settle or
 mark an order paid, and do not look for a way to (a wallet control port, a
 test endpoint, another wallet). If the user wants a real settlement test, they
 pay on that link from their own wallet, and `onPaid` marks the order paid.
 
-Setup ends here. Say "Setup is finished" in one message of at most five
-lines, with the link and what to check. Do not list what changed, offer more
-work, or end the message on a question.
+Setup ends here. Your last message starts "Setup is finished" and has at most
+five short lines (about 80 characters each): the link, the methods it offers,
+and one line of what to look at. Send nothing after it. Do not list what
+changed, copy out the quickstart's browser checklist, offer more work, or end
+the message on a question.
 
 - The link is to a real unpaid order. Keep that order; do not delete it.
+- When this app's orders belong to a session or cookie, the user's browser
+  cannot open the order you made. Then the link is the shop's own page:
+  "Open <shop url> and click Buy: it opens the checkout." Do not explain order
+  ownership or mention your test order.
 - Name the methods it offers: Bitcoin, plus USDT, USDC, ETH and SOL when
-  `LSC_URI_PRIMARY` is saved. Never say a coin will not work or will not be
-  offered. Swap minimums apply per order, and a coin whose minimum is above an
-  order's total says so on its own tile.
+  `LSC_URI_PRIMARY` is saved. Do not mention minimums, and never say a coin
+  will not work or will not be offered.
 
 ## Non-negotiables
 
@@ -186,6 +195,21 @@ itself, and they hold for every integration.
 - Work only in this application. Never read or run anything from another
   project on this machine (its `node_modules`, tools or source), for any
   reason. A browser and Playwright are not part of setup.
+- Restart only this app's server, on the port it already uses: stop the
+  process you started, or the one listening on that port, by its pid (or
+  restart its Compose service). Never `pkill` or `killall` by name: that
+  stops other people's servers too. Start it the way this project already
+  does (its README, Procfile, compose file or package script), on its own
+  port, not a port you pick.
+- Run commands where the app runs. When a compose file builds it, run its
+  package manager, generators, migrations and doctor inside that service
+  (`docker compose exec` or `run`), and rebuild the image after adding a
+  package. This machine's language version and database path are not the
+  app's.
+- To check that the running app sees the codes, run doctor: it reports each
+  one as present or missing and never prints a value. Never print the
+  environment (`printenv`, `env`, `docker compose config`), even filtered to
+  names.
 - The host owns the price. `amountFor` reads it from your own data; reject
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM