openreceive-rails 0.4.13 → 0.4.15

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

@@ -1,615 +0,0 @@
-# OpenReceive agent directions (FastAPI)
-
-These directions describe OpenReceive 0.4.13.
-
-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
-(`openreceive[fastapi]`), the checkout UI is on npm, and the quickstart is
-appended to this file in full, so you can do the whole integration without
-fetching anything. Prefer the published packages and the routes the router
-serves — do not reimplement wallet RPC, settlement, or pricing.
-
-Do not clone the OpenReceive repository into this app, and do not copy a demo's
-models (`ShopOrder`, a signed-cookie visitor, an in-memory catalog) over tables
-that already exist. Find this application's order, product, and user models —
-whatever they are actually named — and map the three hooks onto those.
-
-Keep this application's frontend framework, authentication and database. Pick
-the UI package that matches the frontend that is already here
-(`@openreceive/react`, `/vue`, `/svelte`, `/angular`, or `/elements` for
-plain HTML or Jinja templates) — do not add React to an HTMX app. Keep
-FastAPI's dependency system: the auth dependency this app already resolves
-its user with is what `authorize` should call on `context.request`, and the
-database OpenReceive gets is a sync SQLAlchemy `Engine` for the SAME
-database this app already uses.
-
-## What OpenReceive is
-
-A payment library that runs inside YOUR server. It is an `APIRouter`
-(`openreceive_router`, included under `/openreceive`) that serves its HTTP
-routes inside the application you are editing, issues Lightning invoices
-against a wallet the merchant already controls, and calls back into your code
-when one settles. There is no OpenReceive account and no API key, and
-OpenReceive never holds the funds — the sats land in the wallet the merchant
-connected.
-
-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 from the user; you write three hooks — `authorize`, `amountFor`,
-`onPaid`;
-OpenReceive supplies invoices, polling, settlement and the checkout UI. It never
-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`, 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.
-
-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
-it. Do not read deploy config (compose files, platform secrets), Docker containers, or process environments, and never run
-`printenv`. A new shop has neither code yet: hunting for one burns the turn and
-can leak other secrets into the transcript.
-
-Two server-only URIs are needed before the quickstart:
-
-- `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.
-
-The user never edits an environment file. They paste each code into the chat;
-you store it. Ask one question per message.
-
-1. **First message — the NWC code, and nothing else.** Ask for it 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 the code here and I will store it.
-
-   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`, creating the file if needed.
-   Make sure `.gitignore` covers `.env` (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:
-
-   > 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 here and I will store it — or say "Bitcoin only" and I will continue
-   > without it.
-
-   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`, 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.
-5. **Make the server load the file — yourself.** OpenReceive reads
-   `os.environ`, and a `.env` file on disk is not in it. Start the dev server
-   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.
-
-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
-runs the receive-only preflight: if it reports spend methods such as
-`pay_invoice`, remove `NWC_URI` from `.env` and ask for a receive-only code
-again. Never set the spend-capable override to get past it.
-
-After the router is wired, run `openreceive doctor --app <module>:app`. It
-reports `NWC_URI` presence without printing it, probes the wallet, and names
-any hook still on a placeholder and whether the migration ran. Exit code 1 is a
-finding to fix, not a reason to skip the check.
-
-### Upgrading an existing install
-
-This is not the opening move of a new integration. When OpenReceive is ALREADY
-installed here, the doctor above is the first check. Compare the installed
-`openreceive` (`pip show openreceive`) and `@openreceive/browser` against the
-release named at the top of this file: the headless display models below do
-not exist in older versions, and the first tile click throws with nothing
-saying why. Upgrade first.
-
-Only then start the quickstart.
-
-## Non-negotiables
-
-The quickstart below has the code. These are the rules it cannot state for
-itself, and they hold for every integration.
-
-- OpenReceive never owns orders, users, prices, or fulfillment. The section
-  below is how those tables sit next to the library — not a second order model,
-  and not a Prisma/Drizzle relation to `openreceive_payments`.
-- Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
-  logs, or assets.
-- The host owns the price. `amount_for` reads it from your own data; reject
-  payer-supplied amounts.
-- `authorize` runs on every request, and the `resource` it receives is a CLAIM
-  the payer made, not proof. Read the Starlette request's session, cookie or
-  auth dependency; never trust a body field.
-- `on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
-  per thing you fulfill, created before checkout, kept across retries, never
-  reused. A fresh id per page load lets one order be paid twice.
-- Receive-only NWC is required; a spend-capable code fails closed at boot unless
-  explicitly overridden.
-- 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, and only from the
-  `refund_required` provider state. 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 becomes `refund_required`, and the payer claims it on a SECOND VISIT,
-  after leaving your page to fetch an address from another wallet. Three things
-  must exist or that money is unreachable through your UI: a per-order URL your
-  server serves (`/checkout/:reference` — `syncUrl` on the drop-ins), your own
-  order-summary route to restore the order from, and the ATTEMPT.
-  `/checkouts/prepare` returns no attempts, so a checkout rebuilt from the
-  reference alone opens on the method grid. Re-picking the same coin
-  (`POST /swaps`) re-serves the committed attempt — but only while it is live,
-  and the shadow invoice behind a swap lasts about half an hour, after which the
-  same click mints a NEW deposit address and the refund is off-screen. Keep the
-  `payment_hash` and reopen the attempt with `POST /swaps/status`, which has no
-  such window. 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
-  is for.
-- Show the payer the transaction record: `createTransactionDetails(...)` rows,
-  collapsed behind a caret, on the live checkout AND on the receipt. A payment
-  hash and a deposit txid are the only evidence a payer has that they paid you.
-  `<Checkout>` / `<openreceive-checkout>` already render this panel and the
-  `description` — these two rules cost you code only on a custom UI or your own
-  receipt page, never a reason to replace the drop-in. (It returns no rows
-  while the rail is `checkout_lock` — before the payer has chosen anything
-  there is no transaction — so render the caret only when the rows are
-  non-empty.)
-- Include the router under the prefix — `app.include_router(
-  openreceive_router(host, engine=engine), prefix="/openreceive")` — and give
-  the app `lifespan=openreceive_lifespan(host, engine=engine)` so a bad wallet
-  stops the deploy. Do not add a CSRF layer for these routes: FastAPI has
-  none and the engine's `Sec-Fetch-Site: cross-site` refusal is the
-  protection. Behind a reverse proxy run uvicorn with `--proxy-headers`, or
-  `rate_limiting` counts the proxy as the one payer.
-- The engine is synchronous by design: the router's endpoint runs in
-  Starlette's threadpool. Do not wrap it in `async def` code of your own, and
-  do not hand OpenReceive an async database session — it wants a sync
-  SQLAlchemy `Engine`.
-- HTTP JSON is snake_case, and so is the Python API (`payment_hash`,
-  `amount_msats`).
-- Money is integers or decimal strings — never binary floats.
-
-## Your tables, not ours
-
-`openreceive scaffold payments --alembic` (or `--sql`) emits
-`openreceive_payments` and `openreceive_meta` for THIS application's database.
-That is the whole persistence OpenReceive needs. It does not replace your
-orders, users, or products, and you do not join them.
-
-- **Find this app's models first.** They may be named `Order`, `Invoice`,
-  `Booking`, `Product`, `Variant`, `User`, `Account` — anything. Wire the hooks
-  to those. Do not generate a parallel `ShopOrder` / `ShopProduct` / `ShopUser`
-  stack.
-- **The payable row's id is the `reference`.** Create it before checkout, keep
-  it across retries, never reuse it. Pass that id to `<Checkout>` /
-  `<openreceive-checkout>`. A fresh id per page load lets one order be paid
-  twice.
-- **Products (or the catalog) are the price authority.** Order creation reads
-  live prices into the order (snapshot line items if this app has them).
-  `amount_for` reads only that order — never a payer-supplied amount, never a
-  live catalog lookup that could re-price a cart already placed. Return
-  `{"currency", "value"}` as a decimal STRING, plus a `description` of what
-  they are buying.
-- **Users own the order; OpenReceive never sees them.** `authorize` uses the
-  same ownership check this app already uses on the order show / pay page —
-  the `current_user` dependency, a session cookie, whatever it is, resolved
-  from `context.request`. `context.resource["reference"]` is a claim the
-  payer sent, not proof.
-- **The order is unpaid or paid.** Do not copy `pending` / `expired` / `failed`
-  / `attention` onto it. Those are attempt statuses on `openreceive_payments`. An
-  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).
-- **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.
-  `reference` is not unique (many attempts per order). Fulfillment is a
-  guarded transition on YOUR order row inside `on_paid` — `UPDATE … WHERE
-  state = 'awaiting_payment'` (or this app's equivalent) through
-  `settlement.connection`, the settlement transaction's own connection, not a
-  second session from your ORM. Database writes only in the hook; emails,
-  jobs, and pushes in `after_paid` or after commit.
-
-## If you build your own checkout UI
-
-The drop-ins (`<Checkout>`, `<openreceive-checkout>`) already obey all of this.
-This list is the short form of https://openreceive.org/guides/checkout-ux.md, for a
-UI built on `@openreceive/browser/headless`. Read that before writing
-components.
-
-- Check Bitcoin → Switch payment method → Bitcoin: the grid must hide the
-  Lightning invoice, then restore the same bolt11 without another mint.
-- `createCheckoutController` is the engine. Do not hand-roll a poll loop.
-- `createCheckoutStatusModel` for the status line. Do not draw a
-  Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's.
-- `resolveWizardSelection` decides whether to ask "which network?". A
-  one-network asset starts the swap from the tile. Key `selectedAssetByGroup`
-  by group (`USDT`), valued by `pay_in_asset` (`USDT_TRON`).
-- `createMethodGridDisplay` for tiles, including `limitMessage` so an
-  unavailable method says the minimum in the payer's currency.
-- `createSwapDisplayModel` → `display.copyRows` for deposits: address, memo,
-  and the bare amount each get a copy row. Render `swap.networkWarning*` as
-  the model gives it.
-- `swap.deposit_amount` is the only amount a payer is told to send. Never put
-  a fiat valuation of it (`swap.fee.pay_in_fiat`) next to a stablecoin amount:
-  "$50.03" under "50.05 USDC" reads as a typo, and the payer asks which one to
-  send. The one fiat figure on a USDT/USDC deposit panel is the cart total
-  (`payout_fiat`); express "you send" and the fee in the token. Use
-  `createSwapFeeBreakdown(fee, swap)` — with the swap, not the fee alone — and
-  it applies this for you; SOL and ETH keep a fiat breakdown.
-- `createCheckoutSession` owns mint and swap start. To start swaps, pass its
-  `swap` option (`selection`, `prefix`, `fetch`) together. Without it
-  `startSwap` reports through `onError`.
-- `createQrSvg` is async. Use `createQrSvgController` so you do not render
-  `[object Promise]`.
-- `checkoutLabels` for every payer-facing string. Only write copy it lacks.
-- `stageSwapRefund` then `confirmSwapRefund` — only the second submits.
-  Validate with `getSwapRefundFormError`. Treat `409` as a normal outcome.
-- Pass `{ resumable: true }` to `createSwapDisplayModel` when the payer has
-  a URL they can come back to, and render `display.refundReturnLabel`.
-  Resume helpers (`createGuestCheckoutResume`, `createGuestOrderFetcher`)
-  are on `@openreceive/browser`, not `/headless`.
-- A refund replaces the deposit panel. On `refund_required` also drop
-  "switch payment method".
-- No "Open wallet" button on desktop.
-- Wallet suggestions: `getPaymentWizardRoutes()` +
-  `createWizardRouteDisplays`. Lightning only. Logos are data URIs; tutorial
-  images load from a JavaScript chunk. For a custom headless UI, load it when
-  a tutorial opens and look up the returned table by the tutorial's `path`:
-
-  ```js
-  import { loadPayTutorialImages } from "@openreceive/browser/headless";
-
-  const images = await loadPayTutorialImages();
-  const src = images[tutorial.path]; // data URI for the selected tutorial
-  ```
-
-  Render `src` as the image source and update your UI after loading. Existing
-  display objects do not update: their `tutorial.image` stays `undefined` if
-  created before loading. Alternatively, await the loader, recreate the displays
-  with `createWizardRouteDisplays`, and render the new `tutorial.image`.
-  Show the caption while loading or if loading fails; never use an empty image
-  source. Deploy all JavaScript chunks and allow `data:` in CSP `img-src`.
-  For missing images, check CSP errors, failed chunks, and stale displays.
-  Registry paths are lookup keys; there is no asset option or image route.
-
-## More documentation
-
-Fetch one when the moment comes. Each is raw markdown, so a plain GET is
-enough; drop the `.md` for the same page a person would read.
-
-- https://openreceive.org/guides/authorization.md — before you write `authorize`
-- 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 props, attributes and slots
-- 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
-  tutorials come from: inside the JavaScript, nothing to serve. This is the page
-  that owns the image rule, not the summary in checkout-ux.md
-- 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. Read it before you turn swaps on
-- https://openreceive.org/guides/lightning-swap-connect.md — what an `LSC_URI_*` code actually is
-- https://openreceive.org/guides/price-feeds.md — where the fiat→sats rate comes from, and how to replace it
-- https://openreceive.org/guides/host-testing.md — testing your three hooks without a live wallet or provider
-- 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/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/guides.md — the index, if what you need is not above
-
-Questions, or a problem with the library itself:
-https://openreceive.org/contact
-
-- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
-
----
-
-## The quickstart, in full
-
-Inlined verbatim so this file needs no network access — follow it once Step 0
-passes. The page it comes from is https://openreceive.org/guides/quickstart-fastapi.
-
-## FastAPI quickstart
-
-FastAPI + React. Requires Python ≥ 3.10, FastAPI ≥ 0.115 (Starlette ≥ 0.40)
-and a SQLAlchemy 2 `Engine` for OpenReceive's two tables.
-
-### 1. Install
-
-```sh
-pip install "openreceive[fastapi]"
-npm install @openreceive/react
-```
-
-OpenReceive is one Python distribution with framework extras.
-`openreceive[fastapi]` brings FastAPI, Starlette and SQLAlchemy. The base
-package includes the wallet client (websockets, coincurve, cryptography), the
-HTTP engine and the `openreceive` CLI. The npm package is the checkout UI for
-your frontend. On a different stack, swap the two: use `openreceive[django]`
-with the Django quickstart. A page without a bundler uses
-`@openreceive/elements` instead of React.
-
-|          | Packages                                                                                                                      |
-| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Server   | `openreceive[fastapi]`, `openreceive[django]`, `openreceive[sqlalchemy]` (Flask and plain WSGI/ASGI: the Flask recipe) |
-| 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
-install the package.
-
-### 2. Migrate the payment tables
-
-```sh
-openreceive scaffold payments --alembic --dialect postgres    # or sqlite | mysql
-```
-
-`openreceive scaffold payments --alembic` writes one Alembic revision into
-`alembic/versions/`. The DDL is frozen in the file, and it creates two tables:
-
-- `openreceive_payments`, the payment attempts
-- `openreceive_meta`, the reconcile gate
-
-Set the revision's `down_revision` to your current head (`alembic heads`).
-Then apply it the way you apply your own revisions: `alembic upgrade head`.
-The command never opens a database connection.
-→ [openreceive scaffold payments](https://openreceive.org/guides/api-reference.md#openreceive-scaffold-payments-python)
-
-No Alembic? `openreceive scaffold payments --sql --dialect postgres` prints
-the same DDL. Feed it to `psql`, a Flyway file, or whatever runs your
-migrations. In code, `payments_schema_sql(dialect)` from
-`openreceive.storage.sql` returns the same string. OpenReceive owns the
-tables' logic at runtime: locking, write-once settlement, and the
-reconciliation state machine. There is nothing else to generate. Details: [Payment storage](https://openreceive.org/guides/storage.md).
-
-### 3. Add wallet credentials
-
-Put the credentials in the server's environment. That can be a `.env` your
-process manager loads, `uvicorn --env-file .env`, or your secret store:
-
-```dotenv
-NWC_URI=
-LSC_URI_PRIMARY=
-LSC_URI_BACKUP=
-```
-
-1. Get a receive-only NWC code from a compatible wallet
-   ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
-   Put it in `NWC_URI`.
-2. Optional: set up a [swap provider](https://openreceive.org/set_up_swap_provider).
-   Put its connection string in `LSC_URI_PRIMARY`, and a second one in
-   `LSC_URI_BACKUP` if you have one.
-
-Never put these values in browser code. Your app refuses to start if the NWC
-code also advertises spend methods such as `pay_invoice`. Create a
-receive-only code instead ([Security](https://openreceive.org/guides/security.md)).
-
-OpenReceive reads `os.environ`, so a `.env` file on disk is not enough on its
-own. `uvicorn --env-file .env` loads one in development. In production, the
-process manager or secret store injects the values.
-[Environment variables](https://openreceive.org/guides/environment-variables.md) lists every variable.
-
-### 4. Wire OpenReceive
-
-The wiring takes twelve lines:
-
-- your three hooks as a `Host`
-- a router included under a prefix
-- a lifespan that checks the wallet at startup
-
-The router builds the wallet client from `NWC_URI` and mounts the
-framework-free engine. There is no background reconciler, meaning no job that checks pending
-payments on a timer. Settlement runs during normal requests instead, through
-the durable reconcile gate.
-
-```python
-from fastapi import FastAPI
-from sqlalchemy import create_engine
-from openreceive.fastapi import openreceive_lifespan, openreceive_router
-from openreceive.server import Host
-from .app import current_user, orders  # your existing models and auth dependency
-
-# OpenReceive's own sync Engine for its two tables — the SAME database as
-# your orders, its own connection pool. On SQLite give it a dedicated Engine.
-engine = create_engine("postgresql+psycopg://…")
-
-host = Host(
-    # The price for a reference — here, your order id — from your own data;
-    # OpenReceive converts it into the Lightning invoice. Return None when
-    # there is nothing to pay for. `value` is a decimal STRING from the order
-    # row, never a float and never a request param. `description` is what the
-    # payer is buying, in your own words.
-    amount_for=lambda reference: (
-        {"currency": "USD", "value": str(order.total), "description": order.summary}
-        if (order := orders.find(reference))
-        else None
-    ),
-    # Your own access check: may this caller do this action to this reference?
-    # `context.request` is the untouched Starlette Request — reuse the same
-    # dependency your order page uses. `context.resource["reference"]` is a
-    # claim the payer's browser sent, not proof.
-    authorize=lambda context: orders.viewer_may(
-        current_user(context.request), context.resource["reference"], context.action
-    ),
-    # INSIDE the settlement transaction; runs only for the reference's first
-    # settled attempt. Use `settlement.connection` (that transaction) for the
-    # order write, never a second session. The WHERE clause is the lock.
-    on_paid=lambda settlement: settlement.connection.execute(
-        orders.claim_paid(settlement.reference, settlement.paid_at)
-    ),
-)
-
-app = FastAPI(lifespan=openreceive_lifespan(host, engine=engine))
-app.include_router(
-    # Recommended for public web shops: `rate_limiting=True` caps invoice
-    # creation at 60 per client IP per hour. Leave it off (the default) for
-    # point-of-sale deployments, where many payers share the terminal's IP.
-    openreceive_router(host, engine=engine, rate_limiting=True),
-    prefix="/openreceive",
-)
-```
-
-`authorize` receives the Starlette `Request`. Cookies, headers, and whatever
-`SessionMiddleware` or auth dependency this app already has are readable
-there. FastAPI ships no session of its own, so you must bind the payer's
-`reference` to something the request proves. Behind a reverse proxy, run
-uvicorn with `--proxy-headers`. Otherwise `rate_limiting` counts the proxy as
-the one payer.
-
-**There is no CSRF layer to add.** FastAPI has no CSRF (cross-site request
-forgery) layer, and OpenReceive does not want one. Every mounted route refuses
-a request whose `Sec-Fetch-Site` header says `cross-site`. That stops another
-origin's page from minting or refunding on a logged-in payer's behalf. The
-Express and Fastify adapters rely on exactly the same protection. Its limit is
-the header itself. A client that does not send it, such as a non-browser or an
-old browser, is not refused. So `authorize` stays the actual boundary.
-[Security](https://openreceive.org/guides/security.md) has the full account.
-
-`openreceive_lifespan` runs the receive-only wallet preflight when uvicorn
-starts. It stops the process if the code is missing, unreachable, or able to
-spend. That way the deploy fails instead of the first payer. Pass `lazy=True`
-for tests and for build steps that have no secrets. The first request then
-checks the wallet, and requests get `503 WALLET_UNAVAILABLE` until the check
-passes.
-→ [openreceive_router](https://openreceive.org/guides/api-reference.md#openreceive_router) ·
-[openreceive_lifespan](https://openreceive.org/guides/api-reference.md#openreceive_lifespan) ·
-[the authorize context](https://openreceive.org/guides/api-reference.md#the-authorize-context)
-
-`rate_limiting=True` is for public web shops. Leave it off for point-of-sale,
-where many payers share one IP. → [Rate limiting](https://openreceive.org/guides/rate-limiting.md)
-
-An optional worker, `openreceive notifications --app main:app`, listens for
-wallet payment notifications so settlement does not wait for the next page
-load. → [openreceive notifications](https://openreceive.org/guides/api-reference.md#openreceive-notifications)
-
-Your app also needs an ordinary order-creation route that validates the cart,
-prices with exact decimal math, and returns the order id the page will pass as
-the `reference`. OpenReceive never prices from payer input.
-
-The `reference` is a string you choose, and it is the fulfillment identity:
-your order id. Use one per thing you fulfill, create it before checkout, keep
-it across retries, and never reuse it. OpenReceive never looks inside it, but
-the reference still matters:
-
-- `on_paid` commits fulfillment once per reference.
-- A new checkout under a reference that already settled is refused with 409.
-- A fresh id per page load lets one order be paid twice.
-
-Naming boundary: the Python API is snake_case (`payment_hash`,
-`amount_msats`), and so is everything on the wire. The mounted HTTP routes and
-the browser snapshots use the same names.
-
-### 5. Render checkout
-
-```tsx
-import { Checkout } from "@openreceive/react";
-import "@openreceive/react/styles.css";
-
-<Checkout reference={order.id} prefix="/openreceive" />;
-```
-
-The checkout renders, polls, and settles itself.
-
-`@openreceive/react` and `@openreceive/elements` each ship a compiled
-`styles.css`. Each sheet is self-contained, so a plain
-`<link rel="stylesheet">` works with no build step. Each is also scoped: every
-rule applies only inside what OpenReceive renders.
-
-Serve the compiled `styles.css` without Tailwind processing. Import it from
-JavaScript if your bundler handles CSS, or use a plain
-`<link rel="stylesheet">`. Do not `@import` it into your app's Tailwind entry.
-Its rules have zero specificity, so your page's styles can override checkout
-styles. Scoping does not prevent that.
-
-`<Checkout>` is complete as rendered. It already shows the `description` from
-`amountFor` and the collapsed transaction-details panel. Do not build a custom
-UI to show them. The display rules for them become your job only if you
-replace the drop-in component ([Checkout UX](https://openreceive.org/guides/checkout-ux.md)).
-
-Match the host page's theme. By default the checkout follows the payer's
-stored choice, then the system color scheme. If this page always uses one
-theme, lock it with `<Checkout theme="dark" … />`. On the custom element, set
-the `theme` attribute. Locking the theme keeps a white card off a dark page.
-CSS variables under `data-theme` style the checkout.
-[Frontend checkout](https://openreceive.org/guides/frontend-checkout.md) lists the settings you can change.
-
-Everything the checkout draws ships inside the JavaScript: the payment-method
-icons, the wallet logos, and the pay tutorials. There is no image file to copy
-or serve, and no asset option to set. Deploy your normal JavaScript and CSS
-build output, including any generated JavaScript chunks. Bundlers with code
-splitting can wait to load tutorial screenshots until a tutorial first opens.
-Single-file builds, including the standalone checkout, include them from the
-start. If your Content-Security-Policy has a strict `img-src`, allow `data:`
-([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
-
-That is the whole loop. Your server owns the price and the order. The payer
-gets an invoice. `onPaid` runs inside the settlement transaction. If that
-transaction rolls back, the callback may run again. For delivery to outside
-systems, use an outbox in your app: record the message in the transaction and
-send it after commit.
-
-A page without a bundler renders the same checkout as a custom element:
-`<openreceive-checkout reference="…" prefix="/openreceive">` from
-`@openreceive/elements`. You can also serve its standalone build from your
-static directory.
-
-Buy a Button is a runnable illustration of the boundary
-(`examples/buttons/server/fastapi`).
-It is not a template to copy models from. It keeps products, visitors and
-orders in SQLite, and the three hooks are the only bridge to OpenReceive. It
-is the smallest correct FastAPI integration of the packaged checkout. Map that
-shape onto the models in THIS app.
-
-### 6. Verify
-
-```sh
-openreceive doctor --app main:app
-```
-
-`openreceive doctor` checks Python, `NWC_URI`, and swap-provider
-configuration. It also probes the wallet relay to confirm the code is
-receive-only. With `--app module:attr` (your FastAPI app, the router, or an
-`OpenReceiveApp`), it also confirms the migration ran and names any hook still
-on a placeholder. Add `--url http://localhost:8000` to confirm the routes are
-mounted. Every failing line states its own fix, and the command exits with
-code 1 when anything fails. `openreceive debug-report` prints the same output
-as a redacted support report.
-→ [openreceive doctor](https://openreceive.org/guides/api-reference.md#openreceive-doctor-python)
-
-Then open the checkout in a browser, confirm the payment-method icons and
-wallet logos render, and open a wallet's pay tutorial to check its screenshots.
-If an image is missing, inspect the console for CSP violations and the Network
-panel for failed JavaScript chunks. Allow `data:` in `img-src` and deploy the
-complete build output. Do not add image routes, copy package source images, or
-use registry `icon_path` / tutorial `path` keys as browser URLs.
-
-Swap credentials (`LSC_URI_*`) stay server-side too. The provider order id and
-token live in the attempt's server-only `swap_data` column. They never reach a
-response or a log ([Automated swaps](https://openreceive.org/guides/automated-swaps.md)).