@openreceive/fastify 0.4.14 → 0.4.17

package/skills/integrate-openreceive/references/laravel.md

@@ -1,749 +0,0 @@
-# OpenReceive agent directions (Laravel)
-
-These directions describe OpenReceive 0.4.14.
-
-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
-(`openreceive/laravel`), the frontend packages are 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 package and the routes its service
-provider mounts — 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`, `ShopUser`, an encrypted-cookie visitor) 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 view layer, its authentication (Breeze, Fortify,
-Jetstream, Sanctum, a plain session guard — whatever `Auth` already uses), its
-Eloquent models and its database. Pick the frontend package that matches what
-already renders here (`@openreceive/elements` for Blade/Livewire/Inertia-less
-pages; `/react`, `/vue`, `/svelte` or `/angular` for an existing SPA or Inertia
-app) — do not add React to a Blade app. Reuse the app's existing
-`$request->user()` or session in `Host::authorize`; the engine's migration adds
-only its own two tables to the app's database, through `php artisan migrate`.
-
-## What OpenReceive is
-
-A payment library that runs inside YOUR server. It mounts HTTP routes in 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` on one `App\OpenReceive\Host` class;
-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 the package,
-edit the app, write `.env.example`, or search anywhere else before asking
-it. Do not read deploy config (compose files, Forge/Vapor/Envoyer panels), 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.** Laravel loads
-   `.env` itself. If the app runs `php artisan config:cache`, run
-   `php artisan config:clear` (or re-cache) after writing the file: a cached
-   config never reads `.env` again. When the app 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.
-
-### Upgrading an existing install
-
-This is not the opening move of a new integration. When OpenReceive is ALREADY
-installed here, `php artisan openreceive:doctor` reports every credential as
-set/unset (never the value), the host class and any placeholder hooks, the
-route mount, and the wallet preflight. Check the installed
-`openreceive/laravel` (`composer show openreceive/laravel`) 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 — and if this app runs
-in containers, rebuild the images: `vendor/` is baked into the image, so an
-in-place `composer update` is undone by the next `compose up`.
-
-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 engine — not a second order model,
-  and not an Eloquent model over `openreceive_payments`.
-- Keep `NWC_URI` / `LSC_URI_*` server-only. Never put them in browser code,
-  logs, or assets.
-- 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
-  the payer made, not proof. Read the Illuminate request it is handed — the
-  session, `$request->user()`; never trust a body field. `openreceive:install`
-  scaffolds `use AllowAllAuthorize;`, a placeholder trait that allows
-  everything (the engine warns at boot while it is there) — replace it with
-  this app's real ownership check, same as `onPaid`.
-- `onPaid` 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 `<Checkout>`, `sync-url`
-  or `resumable` on `<openreceive-checkout>`), 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. 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
-- 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 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.
-  `<openreceive-checkout>` / React's `<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.)
-- HTTP JSON is snake_case; the browser packages' TypeScript APIs are camelCase.
-- Money is integers or decimal strings — never binary floats.
-
-## Your tables, not ours
-
-The install migration adds `openreceive_payments` and `openreceive_meta` to 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 `<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).
-  `amountFor` 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' => …]` with `value` 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 —
-  `$request->user()`, a policy, a session key, an encrypted cookie, whatever
-  it is. `$context->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 engine refuses a new checkout under a reference that already
-  settled (409).
-- **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
-  inside `onPaid` — `Order::where(...)->where('state', 'awaiting_payment')->update(...)`
-  (or this app's equivalent), with no `DB::transaction()` of your own around it.
-  Database writes only in the hook; emails, jobs, and broadcasts after commit
-  (implement `OpenReceive\Hosts\AfterPaid` for those).
-
-## If you build your own checkout UI
-
-The engine serves JSON only, so the view is yours — but the drop-ins
-(`<openreceive-checkout>`, React's `<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.
-  The registry answers ~37 wallets: pass
-  `providerPreviewLimit` and build "show all" from `display.providerCount`,
-  or they push the QR off the screen.
-
-## 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 engine 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 mounted engine's routes with your own
-- https://openreceive.org/guides/react-material-ui-recipe.md — a worked custom UI on a component library
-- https://openreceive.org/guides.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-laravel.
-
-## Laravel quickstart
-
-Requires PHP ≥ 8.2 (64-bit) and Laravel ≥ 11 (12 current). You also need these
-PHP extensions:
-
-- `ext-gmp`, which is REQUIRED. The NWC transport's elliptic-curve math depends
-  on it.
-- `sodium` and `mbstring`.
-- The `pdo_*` driver for your database (`pdo_pgsql`, `pdo_mysql` or
-  `pdo_sqlite`).
-
-`php -m` lists what your build has. To add gmp on Debian/Ubuntu, run
-`apt-get install php8.2-gmp`. In the official Docker image, run
-`docker-php-ext-install gmp`.
-
-Add the Laravel package:
-
-```sh
-composer require openreceive/laravel
-```
-
-That is the whole install. `openreceive/laravel` depends on
-`openreceive/openreceive`, the engine. So the default wallet client works with
-nothing else added. It is built from `NWC_URI`. Package discovery registers the
-service provider. If your app brings its own NWC client, bind
-`OpenReceive\Nwc\ReceiveNwcClient` in the container instead.
-
-Then run:
-
-```sh
-php artisan openreceive:install
-php artisan migrate
-```
-
-`openreceive:install` writes three files:
-
-- `config/openreceive.php`: the settings. The host hook is a CLASS NAME, not a
-  closure. `php artisan config:cache` serializes this file, and a closure
-  anywhere in it makes the cache fail.
-- `app/OpenReceive/Host.php`: the three hooks (`authorize`, `amountFor`,
-  `onPaid`), with the two generated placeholders wired in and the fulfillment
-  note as comments.
-- `database/migrations/*_create_openreceive_tables.php`: one migration for both
-  engine tables (`openreceive_payments` and `openreceive_meta`). Its DDL comes
-  from the engine's `PaymentsSchema::statements()` for your connection's
-  driver: PostgreSQL, MySQL/MariaDB or SQLite. `php artisan migrate` runs it
-  like any of your own migrations. There is no second runner.
-
-→ [OpenReceive\Storage](https://openreceive.org/guides/api-reference.md#openreceivestorage)
-
-There is no Eloquent model for the engine's tables, and you do not write one.
-The engine owns the table's commit locking, write-once settlement, and
-reconciliation state machine. `reference` is indexed but not unique, because
-one reference may have many historical attempts. `payment_hash` is globally
-unique.
-
-#### Fulfill exactly once
-
-Within OpenReceive's own settlement paths, `onPaid` runs at most once per
-reference. A second payment to a second invoice is recorded with
-`status_reason = "duplicate_settlement"` and never fulfills again.
-
-One case is yours to handle. **If anything other than OpenReceive can also
-fulfill an order**, such as an admin action, a second payment processor, or a
-replayed job, those paths race each other. Then `onPaid` must be idempotent.
-The generated `Host.php` explains this and shows the guarded transition:
-
-```php
-public function onPaid(PaymentSettlement $settlement): void
-{
-    $claimed = Order::where('id', $settlement->reference)
-        ->where('state', 'awaiting_payment')
-        ->update(['state' => 'paid', 'paid_at' => Carbon::createFromTimestampUTC($settlement->paidAt)]);
-    if ($claimed === 0) {
-        return; // someone else already fulfilled it
-    }
-    // The 'paid' state IS the flag. Ship the goods and send the mail from a job
-    // that drains it after commit, or from afterPaid() below — never from here.
-}
-```
-
-Delivery is at-least-once. `onPaid` runs inside the settlement transaction. If
-it throws, the transaction rolls back and the next pass retries. So keep
-`onPaid` to database writes on the order. An email or webhook sent from here
-would survive the rollback and go out again. The `'paid'` transition above is
-the flag. Drain it after commit in one of two ways:
-
-- Let your own job drain it.
-- Implement `OpenReceive\Hosts\AfterPaid`. Its
-  `afterPaid(PaymentSettlement $settlement)` runs after COMMIT, best-effort,
-  for the same first settled attempt. Put `FulfillOrder::dispatch(…)` or an
-  event there.
-
-Do not open a `DB::transaction()` of your own inside `onPaid`. The engine
-already holds the transaction on this connection, and PDO refuses a nested
-`BEGIN`.
-
-**A query-builder `update()` fires no model events.** That is intended. It
-runs one conditional `UPDATE`, so the claim is atomic and no model code runs
-between the check and the write. It also means no observer, no `saved` event
-and no `Model::updated` listener runs. That is fine for a job that drains the
-flag. It does not work for a model that owns the transition through events. If
-yours does, take a row lock for the duration instead:
-
-```php
-public function onPaid(PaymentSettlement $settlement): void
-{
-    $order = Order::lockForUpdate()->find($settlement->reference);   // SELECT … FOR UPDATE
-    if ($order === null || $order->state !== 'awaiting_payment') {
-        return;
-    }
-    $order->update(['state' => 'paid', 'paid_at' => Carbon::createFromTimestampUTC($settlement->paidAt)]);  // events fire
-}
-```
-
-**Unlocking a download works the same way.** If the payer bought a file, do not
-unlock it in the browser. Gate the download route on the paid order row, and
-serve the file only if that row exists:
-`Order::where('id', $id)->where('user_id', $request->user()->id)->where('state', 'paid')->firstOrFail()`,
-or a 404 otherwise. The `'paid'` written above is the unlock. The client never
-decides that an order was fulfilled. It re-reads the row. Buy a Button's
-`ShopController::download` does this in twenty lines.
-
-Both shapes are idempotent and correct. They differ only in whether your model
-layer runs:
-
-- The query-builder `update()` skips the model layer. It is the right default.
-- The row lock holds the row for the duration of the method. Use it when the
-  transition has to go through your model.
-
-The generated fulfillment note says the same thing. If your fulfillment is a
-read-modify-write that one conditional `UPDATE` cannot express, take the lock.
-
-Buy a Button
-(`examples/buttons/server/laravel`)
-is a runnable illustration of this boundary. It is not a template to copy
-models from. It has products, visitors, and orders, and the three hooks are the
-only bridge. Map that shape onto the models in THIS app.
-
-### Add wallet credentials
-
-Laravel loads `.env` itself, and `config/openreceive.php` reads the values
-through `env()`:
-
-```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)).
-
-Under `php artisan config:cache`, Laravel never reads `.env` at runtime. The
-values are captured when you cache, as with every other Laravel secret. So
-re-run `config:cache` after changing one. The engine redacts connection
-strings in every log line. `php artisan openreceive:doctor` prints each
-variable only as set or unset.
-→ [Environment variables](https://openreceive.org/guides/environment-variables.md).
-
-### Configure the host hooks
-
-`app/OpenReceive/Host.php` needs three things: authorization, the trusted
-price, and fulfillment. All three receive the `reference`. This is a string you
-choose, and it is the fulfillment identity. Use your order id:
-
-- one per thing you fulfill,
-- created before checkout,
-- kept across retries,
-- never reused.
-
-OpenReceive never looks inside it. But `onPaid` commits fulfillment once per
-reference, and a new checkout under a reference that already settled is
-refused with 409. A fresh id per page load would let one order be paid twice.
-
-```php
-<?php
-
-namespace App\OpenReceive;
-
-use App\Models\Order;                      // YOUR model — it could be named anything.
-use Carbon\Carbon;
-use OpenReceive\Host as OpenReceiveHost;
-use OpenReceive\PaymentSettlement;
-use OpenReceive\Server\AuthorizeContext;
-
-final class Host implements OpenReceiveHost
-{
-    // Your policy, called before every checkout/payment/swap request.
-    //   $context->action    — "checkout.prepare", "checkout.create", "payment.check",
-    //                         "swap.quote", "swap.create", "swap.read" or "swap.refund"
-    //   $context->request   — the Illuminate\Http\Request: read the session, the
-    //                         authenticated user, cookies or headers, as in a controller
-    //   $context->resource  — ['reference' => …, 'payment_hash' => ?] copied from the
-    //                         payer's JSON body. It names an order; it does not prove
-    //                         this caller owns it. reference is always a validated
-    //                         non-empty string (≤200 chars); payment_hash is null except
-    //                         on payment.check / swap.read / swap.refund.
-    // Return true to allow, false for a 403. Here: only the signed-in customer
-    // who placed the order may act on it.
-    public function authorize(AuthorizeContext $context): bool
-    {
-        $order = Order::find($context->reference());
-        return $order !== null && $order->user_id === $context->request->user()?->id;
-    }
-
-    // The price for a reference — here, your order id — from your own data; null
-    // when there is nothing to pay for (a 404). `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.
-    public function amountFor(string $reference): ?array
-    {
-        $order = Order::find($reference);
-        return $order === null ? null : [
-            'currency' => 'USD',
-            'value' => $order->total,                       // a decimal string column
-            'description' => $order->items()->count().' items',
-        ];
-    }
-
-    // Runs inside the settlement transaction, only for the order's first settled
-    // attempt. The WHERE clause is the lock: a second fulfillment path of yours
-    // (admin action, replayed job) updates zero rows and does nothing. Plain
-    // Eloquent on the default connection, because the engine holds the
-    // transaction on that connection's PDO — the query joins it.
-    public function onPaid(PaymentSettlement $settlement): void
-    {
-        Order::where('id', $settlement->reference)
-            ->where('state', 'awaiting_payment')
-            ->update(['state' => 'paid', 'paid_at' => Carbon::createFromTimestampUTC($settlement->paidAt)]);
-    }
-}
-```
-
-`config/openreceive.php` names that class
-(`'host' => App\OpenReceive\Host::class`). The provider resolves it from the
-container, so it may take constructor dependencies. `onPaid` runs inside the
-settlement transaction, only for the first settled attempt for a reference.
-→ [OpenReceive\Host](https://openreceive.org/guides/api-reference.md#openreceivehost) ·
-[the authorize context](https://openreceive.org/guides/api-reference.md#the-authorize-context-php)
-
-The routes mount under `config('openreceive.route_prefix')` (`openreceive`),
-with the middleware in `config('openreceive.middleware')` (`['web']`). The
-`web` group is how the engine picks up your application's session and CSRF
-protection. Laravel's `VerifyCsrfToken` reads `X-CSRF-TOKEN`. The checkout
-client sends it automatically from
-`<meta name="csrf-token" content="{{ csrf_token() }}">`, so keep that tag in
-the layout that renders the checkout.
-
-The `web` group also brings every middleware it carries. A global `auth`
-redirect on the `web` group would send the engine's JSON routes to a login page
-too. Keep such guards on your own route groups, not on `web` itself.
-
-The generated `Host.php` ships two placeholders. Replace both, not just
-`onPaid`:
-
-- `use LoggingOnPaid;` only logs the settlement and fulfills nothing. Replace
-  it with your real fulfillment (as above). Until you do, orders would be
-  recorded as settled without ever being fulfilled, so the engine warns every
-  time your application boots.
-- `use AllowAllAuthorize;` allows everything. It treats possession of the
-  reference as authorization, which is safe only while references are
-  unguessable. The engine warns at boot until you replace it with your own
-  ownership check (as above).
-
-The amount always comes from your own order record. Payer-supplied amounts are
-rejected. The engine's `PaymentRepository` interface remains the escape hatch
-for apps with custom storage. It is not part of the quickstart.
-
-For public web shops, turn on the per-IP invoice cap with
-`'rate_limiting' => true`. Leave it off (the default) when many payers share
-one IP. The client IP is `$request->ip()`, so behind a proxy Laravel's
-`TrustProxies` decides who the payer is. → [Rate limiting](https://openreceive.org/guides/rate-limiting.md)
-
-In production, the engine builds the wallet client when your app boots. It
-also runs the receive-only preflight right away: it reaches the wallet and
-checks that the code cannot spend. A missing `NWC_URI`, a dead relay, or a
-spend-capable wallet then stops the deploy. Otherwise those problems would
-show up as 500 errors for customers on the first checkout. Outside production
-(tests, consoles), the engine builds the client lazily, on first use, so no
-live wallet is needed.
-
-PHP builds the whole engine again on every request. Under PHP-FPM or Apache,
-that same preflight would then run per request. To avoid that, the package
-caches the wallet's info event in your default cache store for
-`config('openreceive.wallet_info_cache_seconds')` (600). A checkout request
-then costs one relay round trip, not two.
-
-### Render the checkout
-
-Serve the compiled `styles.css` without Tailwind processing. Either import it
-from JavaScript (with a CSS-capable bundler) or use a plain
-`<link rel="stylesheet">`. Do not `@import` it into your Tailwind entry. Its
-rules have zero specificity, so your own styles can override checkout styles.
-Scoping does not prevent that.
-
-The engine serves JSON checkout routes only. Your view does the rendering. Any
-OpenReceive frontend package works against the `/openreceive` mount. The
-smallest is the custom element. Its default `prefix` is already
-`/openreceive`. The package ships a self-contained `styles.css`, scoped to what
-OpenReceive renders. Laravel ships Vite, so the package installs like any other
-frontend dependency:
-
-```sh
-npm install @openreceive/elements
-```
-
-```js
-// resources/js/app.js — in the entry @vite() already loads
-import { defineElements } from "@openreceive/elements";
-import "@openreceive/elements/styles.css";
-
-// Registers the <openreceive-checkout> tag with the browser. Without this,
-// the tag in the Blade below is unknown markup and renders as nothing; with
-// it, the element wakes up wherever the tag appears. Call once per page —
-// order relative to the markup does not matter.
-defineElements();
-```
-
-```blade
-{{-- resources/views/orders/pay.blade.php --}}
-<openreceive-checkout reference="{{ $order->id }}"></openreceive-checkout>
-```
-
-The element creates the checkout for `reference`, then renders and polls
-itself. React, Vue, Svelte, and Angular apps use the matching wrapper package
-instead, with the same props and defaults
-([Frontend checkout](https://openreceive.org/guides/frontend-checkout.md)). Build a custom checkout only if
-this app cannot use a drop-in. In that case `@openreceive/browser/headless` is
-the API ([Headless checkout](https://openreceive.org/guides/headless-checkout.md)).
-
-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 load tutorial screenshots only when a tutorial is first opened.
-Single-file builds, including the standalone checkout, include them upfront. If
-your Content-Security-Policy has a strict `img-src`, allow `data:`
-([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
-
-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, check 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.
-
-**No npm in this project?** Every GitHub release attaches
-`standalone-checkout-<version>.tar.gz`. It holds one self-registering ESM file,
-its stylesheet and a `MANIFEST.json` of hashes. Unpack it into
-`public/openreceive/`, and the same element needs just two tags:
-
-```blade
-<link rel="stylesheet" href="/openreceive/openreceive-checkout.css" />
-<script type="module" src="/openreceive/openreceive-checkout.js"></script>
-
-<openreceive-checkout reference="{{ $order->id }}"></openreceive-checkout>
-```
-
-`MANIFEST.json` carries the version and a SHA-256 per file. Keep the tarball
-version in step with the Composer package.
-
-### Reconciliation
-
-Settlement runs on the request path. You do not need a cron job. Disable or
-tune it with `'opportunistic_reconcile'` (`false`, or
-`['min_interval_seconds' => …]`).
-
-Optionally, run one worker so settlement does not wait for the next page
-load:
-
-```sh
-php artisan openreceive:notifications
-```
-
-The worker listens for the wallet's NWC-02 `payment_received` notifications.
-The same process also runs a periodic reconcile pass. Run one per deployment,
-not one per web instance.
-
-Two more commands help:
-
-- `php artisan openreceive:reconcile` runs one pass, if you want to drive it
-  yourself.
-- `php artisan openreceive:doctor` reports every credential as set or unset,
-  the host and its placeholders, the route mount, and the wallet preflight.
-
-### Swap secrets
-
-The package recognizes `LSC_URI_PRIMARY` and `LSC_URI_BACKUP`, using the
-shared [Lightning Swap Connect](https://openreceive.org/guides/lightning-swap-connect.md) vectors. Setting
-either one auto-builds the matching provider. So an app that wants swaps only
-supplies the connection strings
-([Environment variables](https://openreceive.org/guides/environment-variables.md)). To override this, use the
-`openreceive.swap_providers` container binding. Bind a list of your own
-adapters to replace the auto-built set, or `[]` to disable swaps.
-
-One `openreceive_payments` row holds at most one provider order, in its
-server-only `swap_data`. The engine never returns `swap_data` from its routes
-or writes it to a log. Do not select it into your own API, serialize it, or
-log it. It may contain a provider credential.
-
-**Setting either connection string commits you to refunds.** A swap deposit can
-arrive short or late. The provider then marks it `refund_required`, and only
-your UI can claim it. The payer claims it on a second visit, after leaving your
-page to get an address in another wallet. That needs three things:
-
-- a per-order URL your app serves,
-- a route that restores the order behind it,
-- something that restores the ATTEMPT, since `/checkouts/prepare` returns none.
-
-[Swap refunds](https://openreceive.org/guides/swap-refunds.md) covers all of it. Read it before you set
-`LSC_URI_PRIMARY`.