openreceive 0.4.3 → 0.4.5

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

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.3.
+These directions describe OpenReceive 0.4.5.
 
 Add OpenReceive to a Node application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the packages are on npm, and the
@@ -13,6 +13,12 @@ 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) — do not add React to a Vue app. Reuse the app's existing
+session/auth in `authorize` and its existing database handle in `storage.db`.
+
 ## What OpenReceive is
 
 A payment library that runs inside YOUR server. It mounts HTTP routes in the
@@ -211,8 +217,11 @@ components.
   "switch payment method".
 - No "Open wallet" button on desktop.
 - Wallet suggestions: `getPaymentWizardRoutes()` +
-  `createWizardRouteDisplays`. Lightning only. Host the icons with
-  `assetBaseUrl` / `asset-base-url`.
+  `createWizardRouteDisplays`. Lightning only. Every image ships inside
+  the JavaScript — logos as data URIs, tutorials once `loadPayTutorialImages()`
+  resolves (`image` is `undefined` until then) — so serve nothing and set no
+  asset option. When it works, the logos and payment icons render; a missing
+  image means a CSP `img-src` that blocks `data:`, and the console names it.
 
 ## More documentation
 
@@ -226,10 +235,9 @@ enough; drop the `.md` for the same page a person would read.
 - 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 packaged icons and pay
-  tutorials come from, and how to serve them. The asset rule is the one a custom
-  UI is most likely to get wrong; this is the page that owns it, not the summary
-  in checkout-ux.md
+- 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
@@ -252,7 +260,7 @@ https://openreceive.org/contact
 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-node.
 
-## Node quickstart
+## Node quickstart (Express)
 
 Express + React. Requires Node ≥ 22.
 
@@ -273,6 +281,9 @@ identical.
 | Server   | `@openreceive/express`, `@openreceive/fastify`, `@openreceive/next`                                                           |
 | Frontend | `@openreceive/react`, `@openreceive/vue`, `@openreceive/svelte`, `@openreceive/angular`, `@openreceive/elements` (plain HTML) |
 
+Fastify: [quickstart-fastify.md](https://openreceive.org/guides/quickstart-fastify.md) · Next.js:
+[quickstart-next.md](https://openreceive.org/guides/quickstart-next.md). This page is the Express one.
+
 On a fresh project, also install what this guide assumes is already there: the
 framework and an env loader (`npm install express dotenv`), plus your ORM
 before step 2 (`npm install prisma @prisma/client` on the Prisma path) —
@@ -455,12 +466,13 @@ so a white card never lands on a dark page. The checkout is styled by CSS
 variables under `data-theme`; [Frontend checkout](https://openreceive.org/guides/frontend-checkout.md) has
 the knobs.
 
-The payment-method icons are compiled into `@openreceive/browser` and need
-nothing from your bundler. The wallet logos and pay tutorials are files in
-`@openreceive/provider-data`, and outside Vite/Rollup (esbuild, webpack, a
-plain script tag) they cannot resolve their own URLs — the drop-in needs this
-exactly as a custom UI does. Serve that package's `dist/assets` tree and pass
-the base as `assetBaseUrl="/openreceive-assets"`
+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 defer tutorial screenshots until first open; 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)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
@@ -484,3 +496,10 @@ and probes the wallet relay to confirm the code is receive-only. Add
 `--url http://localhost:3000` to confirm the routes are mounted; every failing
 line states its own fix.
 → [openreceive doctor](https://openreceive.org/guides/api-reference.md#openreceive-doctor)
+
+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.