@openreceive/react 0.4.3 → 0.4.6

package/README.md

@@ -1,6 +1,30 @@
 # @openreceive/react
 
-React checkout components for OpenReceive (`<Checkout>`, `useCheckout`, `PaymentWizard`).
+Add Bitcoin Lightning checkout to your React app with a ready-to-use
+`<Checkout>` component, or build your own payment screen with `useCheckout`
+and `PaymentWizard`. Let customers choose a payment method, scan a QR code,
+and follow payment status without building the checkout flow from scratch.
+
+OpenReceive supports optional swaps from **USDT, USDC, SOL, and ETH** through
+a configured swap provider. The provider converts the payment to **BTC over
+Lightning**, which settles into the merchant's connected wallet. Available
+assets and networks depend on the provider; swaps are optional.
+
+Pair this browser package with an OpenReceive server integration. Your server
+authorizes the order, sets the amount, configures swaps, and verifies
+settlement; wallet and provider credentials stay on the server.
+
+## Install
+
+Use Node.js 22 or later for package tooling and React 18 or later.
+
+```sh
+npm install @openreceive/react
+```
+
+Follow the [frontend checkout guide](https://github.com/openreceive/openreceive/blob/master/docs/guides/frontend-checkout.md)
+to connect the component to your server routes. Use the server-side payment
+hook to fulfill orders; browser callbacks update the interface.
 
 ## Mount
 
@@ -20,7 +44,7 @@ export function Pay() {
 Pass `reference` to let the component create the checkout (create mode), or pass
 a `checkout` snapshot to render one your server already created. Prop names,
 defaults, and the full surface are shared across the wrappers — see
-`docs/internal/wrapper-parity.md` in the repository.
+[frontend checkout guide](https://github.com/openreceive/openreceive/blob/master/docs/guides/frontend-checkout.md).
 
 Event handlers (`onCopy`, `onOpenWallet`, `onState`, `onSettled`,
 `onProviderCopy`, `onStartOver`, `onError`) are ordinary props. React receives
@@ -31,11 +55,12 @@ framework values rather than DOM `CustomEvent`s — `onState` gets the
 and returns the view model plus the copy/open actions. Create mode belongs to
 `<Checkout>`, so the hook takes no create options.
 
-## Icon assets
+## Images
 
-The checkout loads its payment-method icons by URL at runtime; your app must
-serve them where the resolution lands. See
-[Icon assets in `@openreceive/browser`](https://github.com/openreceive/openreceive/blob/master/packages/js/browser/README.md#icon-assets)
-for the per-bundler recipes.
+Everything the checkout draws — payment-method icons, wallet logos, pay
+tutorials — ships inside the JavaScript; nothing to copy, serve or configure,
+under any bundler. If your Content-Security-Policy has a strict `img-src`,
+allow `data:`. See
+[Images in `@openreceive/browser`](https://github.com/openreceive/openreceive/blob/master/packages/js/browser/README.md#images).
 
 Part of [OpenReceive](https://openreceive.org). Start with the [Node quickstart](https://github.com/openreceive/openreceive/blob/master/docs/guides/quickstart-node.md); the full API is in the [API reference](https://github.com/openreceive/openreceive/blob/master/docs/guides/api-reference.md).

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { CheckoutComponentProps, CheckoutState, QrEncoder, BrowserLoggerOption, CheckoutStatusRefresh, Status, SwapRefundStaging, CheckoutSnapshot, AssetUrlResolver, ThemePreference, BrowserLogContext, CheckoutInvoiceSnapshot, ResolvedTheme, ThemeModel, CheckoutPhase, CheckoutStatusModel, UnixSeconds, BrowserLogger, TransactionDetailsSource } from '@openreceive/browser/headless';
+import { CheckoutComponentProps, CheckoutState, QrEncoder, BrowserLoggerOption, CheckoutStatusRefresh, Status, SwapRefundStaging, CheckoutSnapshot, ThemePreference, BrowserLogContext, CheckoutInvoiceSnapshot, ResolvedTheme, ThemeModel, CheckoutPhase, CheckoutStatusModel, UnixSeconds, BrowserLogger, TransactionDetailsSource } from '@openreceive/browser/headless';
 export { TransactionDetailsSource, resolveTransactionDetailRows } from '@openreceive/browser/headless';
 
 interface CheckoutData {
@@ -46,6 +46,8 @@ interface UseCheckoutOptions extends CheckoutData, Omit<CheckoutEventHandlers, "
      * polling — there is nowhere to poll.
      */
     readonly prefix?: string;
+    /** Header name the page's `<meta name="csrf-token">` is sent under; default `X-CSRF-Token`. */
+    readonly csrfHeader?: string;
     readonly polling?: boolean;
     readonly pollIntervalMs?: number;
 }
@@ -162,8 +164,6 @@ interface CheckoutProps extends CheckoutComponentProps, CheckoutEventHandlers, O
      * `useCheckout` model.
      */
     readonly children?: CheckoutChildren;
-    /** Passed through to the payment wizard. See {@link PaymentWizardProps.resolveAssetUrl}. */
-    readonly resolveAssetUrl?: AssetUrlResolver;
     /**
      * Lock the checkout to one theme. Wins over the stored preference and any
      * ancestor ThemeScope, and hides the toggle: a host embedding the checkout in
@@ -233,25 +233,12 @@ interface PaymentWizardProps {
      */
     readonly prefix?: string;
     readonly fetch?: typeof globalThis.fetch;
+    /** Header name the page's `<meta name="csrf-token">` is sent under; default `X-CSRF-Token`. */
+    readonly csrfHeader?: string;
     readonly clipboard?: Pick<Clipboard, "writeText">;
     readonly qrEncoder?: QrEncoder;
     /** Base URL of an external bolt11 decoder; omitted, no "Decode" link is rendered. */
     readonly decodeLinkUrl?: string;
-    /**
-     * Rewrite a packaged asset path (`assets/provider-icons/strike.png`,
-     * `assets/pay_tutorials/strike-1.webp`) into a URL this host can serve. The
-     * packaged URLs only resolve under Vite/Rollup; every other bundler needs
-     * this, or the provider logos and pay tutorials come out as dead `file://`
-     * links. The payment-method icons are compiled in as `data:` URIs and need
-     * nothing; given a resolver they go through it too (`assets/icons/btc.svg`).
-     * See docs/guides/provider-registry.md.
-     */
-    readonly resolveAssetUrl?: AssetUrlResolver;
-    /**
-     * The string form of the same seam: where this host serves the packages'
-     * `dist/assets` trees. `resolveAssetUrl` wins when both are set.
-     */
-    readonly assetBaseUrl?: string;
     /**
      * The two-step refund, from whoever owns the checkout controller —
      * `<Checkout>` passes its `useCheckout` model. Given one, the wizard stages

package/dist/index.js

@@ -47,6 +47,7 @@ function useCheckoutSession(options) {
         },
         prefix: () => optionsRef.current.swap?.prefix(),
         fetch: () => optionsRef.current.swap?.fetch(),
+        csrfHeader: () => optionsRef.current.swap?.csrfHeader?.(),
         onStarted: (invoice) => optionsRef.current.swap?.onStarted?.(invoice)
       },
       get logger() {
@@ -769,6 +770,7 @@ function useCheckout(options) {
         refreshStatus: async (reference) => await refreshStatusRef.current?.(reference) ?? null
       } : {},
       ...prefix === void 0 ? {} : { prefix },
+      ...options.csrfHeader === void 0 ? {} : { csrfHeader: options.csrfHeader },
       pollIntervalMs: options.pollIntervalMs,
       // Omit logger when unset so @openreceive/browser attaches its default console sink.
       // Pass `false` through to disable; wrap custom sinks so inline host callbacks stay stable.
@@ -796,7 +798,7 @@ function useCheckout(options) {
       controller.stop();
       if (controllerRef.current === controller) controllerRef.current = null;
     };
-  }, [checkoutIdentity, polls, prefix, options.pollIntervalMs]);
+  }, [checkoutIdentity, polls, prefix, options.csrfHeader, options.pollIntervalMs]);
   const publicStatus = deriveStatus(state);
   const richStatus = createCheckoutStatusModel2(state);
   React6.useEffect(() => {
@@ -944,7 +946,6 @@ import {
   buildMethodGridEntries,
   checkoutLabels as checkoutLabels5,
   copyInvoice as copyInvoiceHelper3,
-  createAssetBaseUrlResolver,
   createMethodGridDisplay,
   createPaymentWizardController,
   createPaymentWizardModel,
@@ -957,14 +958,15 @@ import {
   getPaymentMethodIcon,
   getSwapOptionIcon,
   getWizardEmptyMessage,
+  loadPayTutorialImages,
   networkButtonClasses,
   networkCheckClasses,
   networkMobileRevealClasses,
   networkSummaryIconClasses,
   orClasses as orClasses6,
   paymentMethods,
-  resolveWizardSelection,
   requestSwapRefund,
+  resolveWizardSelection,
   selectCurrentSwapInvoice,
   swapAssetMatchesRoute,
   swapOptionLimitMessage as swapOptionLimitMessage2
@@ -1142,10 +1144,12 @@ function ProviderTutorialModal(options) {
           {
             className: orClasses4.tutorialFrame
           },
-          React7.createElement("img", {
-            alt: tutorial?.caption ?? "",
+          // No `<img>` until the lazily loaded screenshot is in hand: an
+          // empty src is a request for the page itself.
+          tutorial?.image === void 0 ? null : React7.createElement("img", {
+            alt: tutorial.caption,
             className: orClasses4.tutorialImage,
-            src: tutorial?.image ?? ""
+            src: tutorial.image
           })
         ),
         React7.createElement(
@@ -2020,6 +2024,7 @@ function PaymentWizard(props) {
       },
       prefix: () => props.prefix,
       fetch: () => fetcher,
+      csrfHeader: () => props.csrfHeader,
       onStarted: (invoice) => props.onSwapStarted?.(invoice)
     },
     ...props.logger === void 0 ? {} : { logger: props.logger },
@@ -2073,6 +2078,7 @@ function PaymentWizard(props) {
         ) : await requestSwapRefund({
           fetch: fetcher,
           prefix,
+          ...props.csrfHeader === void 0 ? {} : { csrfHeader: props.csrfHeader },
           reference,
           paymentHash: resolveAttemptPaymentHash(
             [startedSwapInvoice, ...checkout?.invoices ?? []],
@@ -2090,6 +2096,7 @@ function PaymentWizard(props) {
     },
     [
       props.prefix,
+      props.csrfHeader,
       reference,
       fetcher,
       props.onError,
@@ -2107,14 +2114,25 @@ function PaymentWizard(props) {
   );
   const model = createPaymentWizardModel(selection);
   const { wizard } = model;
-  const resolveAssetUrl = props.resolveAssetUrl ?? (props.assetBaseUrl === void 0 || props.assetBaseUrl.trim() === "" ? void 0 : createAssetBaseUrlResolver(props.assetBaseUrl));
+  const tutorialOpen = activeTutorial !== null;
+  const [tutorialImagesReady, setTutorialImagesReady] = React9.useState(false);
+  React9.useEffect(() => {
+    if (!tutorialOpen || tutorialImagesReady) return;
+    let cancelled = false;
+    loadPayTutorialImages().then(
+      () => {
+        if (!cancelled) setTutorialImagesReady(true);
+      },
+      () => void 0
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [tutorialOpen, tutorialImagesReady]);
   const routeAssetDisplays = createWizardRouteAssetDisplays(model.routeAssets, {
-    selectedRoute: model.selectedRoute,
-    ...resolveAssetUrl === void 0 ? {} : { resolveAssetUrl }
-  });
-  const routeDisplays = createWizardRouteDisplays(wizard.routes, {
-    ...resolveAssetUrl === void 0 ? {} : { resolveAssetUrl }
+    selectedRoute: model.selectedRoute
   });
+  const routeDisplays = createWizardRouteDisplays(wizard.routes);
   const showRoutePicker = routeAssetDisplays.length > 0 && (model.selectedRoute === null || routeDisplays.length === 0);
   const activeTutorialProvider = activeTutorial === null ? void 0 : routeDisplays.flatMap((route) => route.providers).find((provider) => provider.id === activeTutorial.providerId);
   const swapAssetOptions = swapOptions.enabled ? swapOptions.options.filter((option) => option.provider.length > 0) : [];
@@ -2258,8 +2276,7 @@ function PaymentWizard(props) {
           void props.onRequestLightning?.();
         }
       },
-      onContinueSwap: selectSwapAsset,
-      ...resolveAssetUrl === void 0 ? {} : { resolveAssetUrl }
+      onContinueSwap: selectSwapAsset
     }) : null,
     // On the grid the note is a section of its own, under the tiles: there is no
     // body to put it in until a method is chosen.
@@ -2532,10 +2549,14 @@ function renderCompactPaymentMethodSelector(options) {
                   React9.createElement("img", {
                     alt: "",
                     className: orClasses6.methodNetworkIcon,
-                    src: getNetworkIcon(option.network_label, options.resolveAssetUrl)
+                    src: getNetworkIcon(option.network_label)
                   })
                 ),
-                React9.createElement("span", { className: "truncate" }, option.network_label),
+                React9.createElement(
+                  "span",
+                  { className: orClasses6.methodNetworkLabel },
+                  option.network_label
+                ),
                 optionSelected ? React9.createElement(
                   "span",
                   {
@@ -2594,7 +2615,7 @@ function renderCompactPaymentMethodSelector(options) {
     React9.createElement(
       "div",
       {
-        className: orClasses6.wizardBody,
+        className: orClasses6.methodBody,
         "aria-labelledby": "payment-method-heading"
       },
       React9.createElement(
@@ -2627,7 +2648,7 @@ function renderCompactPaymentMethodSelector(options) {
                 React9.createElement("img", {
                   alt: "",
                   className: orClasses6.methodIcon,
-                  src: getPaymentMethodIcon(method.id, options.resolveAssetUrl)
+                  src: getPaymentMethodIcon(method.id)
                 })
               ),
               React9.createElement(
@@ -2693,7 +2714,7 @@ function renderCompactPaymentMethodSelector(options) {
                 }) : React9.createElement("img", {
                   alt: "",
                   className: orClasses6.methodIcon,
-                  src: getSwapOptionIcon(displayOption, options.resolveAssetUrl)
+                  src: getSwapOptionIcon(displayOption)
                 })
               ),
               React9.createElement(
@@ -2920,6 +2941,7 @@ function CheckoutSnapshotMode(props) {
 function CheckoutCreate(props) {
   const reference = props.reference;
   const resolvedPrefix = props.prefix ?? OPENRECEIVE_DEFAULT_PREFIX;
+  const csrfHeader = props.csrfHeader;
   const {
     onError,
     metadata,
@@ -2952,6 +2974,7 @@ function CheckoutCreate(props) {
     requestCheckout: (id) => requestCheckout({
       prefix: resolvedPrefix,
       reference: id,
+      ...csrfHeader === void 0 ? {} : { csrfHeader },
       ...metadataRef.current === void 0 ? {} : { metadata: metadataRef.current },
       ...createFetchRef.current === void 0 ? {} : { fetch: createFetchRef.current }
     }),
@@ -2974,11 +2997,13 @@ function CheckoutCreate(props) {
     prepareCheckout({
       prefix: resolvedPrefix,
       reference,
+      ...csrfHeader === void 0 ? {} : { csrfHeader },
       ...createFetchRef.current === void 0 ? {} : { fetch: createFetchRef.current }
     }).then(
       (checkout) => resumePaymentHash === void 0 ? checkout : resumeSwapAttempt({
         fetch: createFetchRef.current ?? globalThis.fetch,
         prefix: resolvedPrefix,
+        ...csrfHeader === void 0 ? {} : { csrfHeader },
         reference,
         paymentHash: resumePaymentHash,
         snapshot: checkout
@@ -2996,7 +3021,7 @@ function CheckoutCreate(props) {
     return () => {
       cancelled = true;
     };
-  }, [reference, resolvedPrefix, resumePaymentHash, attempt]);
+  }, [reference, resolvedPrefix, csrfHeader, resumePaymentHash, attempt]);
   const onSwapStarted = React10.useCallback(
     (invoice) => {
       setCreated((current) => {
@@ -3085,6 +3110,7 @@ function CheckoutView(props) {
     // The dispatcher and CheckoutCreate both resolve this before rendering the
     // view, so the default below only guards a direct CheckoutView call.
     prefix = OPENRECEIVE_DEFAULT_PREFIX,
+    csrfHeader,
     metadata: _metadata,
     createFetch: _createFetch,
     // Not `_`-prefixed like its neighbours: the view reads it, to infer
@@ -3121,8 +3147,6 @@ function CheckoutView(props) {
     components,
     classNames,
     children,
-    resolveAssetUrl,
-    assetBaseUrl,
     className,
     ...sectionProps
   } = props;
@@ -3134,6 +3158,7 @@ function CheckoutView(props) {
     onError,
     refreshStatus,
     prefix,
+    csrfHeader,
     onState,
     onSettled,
     polling,
@@ -3374,6 +3399,7 @@ function CheckoutView(props) {
           onError,
           onSwapFocusChange: setSwapFocused,
           prefix,
+          csrfHeader,
           qrEncoder,
           decodeLinkUrl,
           logContext: getCheckoutLogContext({
@@ -3385,8 +3411,6 @@ function CheckoutView(props) {
           onCopy,
           onRequestLightning,
           onSwapStarted,
-          resolveAssetUrl,
-          assetBaseUrl,
           // Whether a payer who closes the tab has a URL to come back
           // to. Explicit wins — only the host knows about a per-order
           // route of its own; otherwise infer it from the two props that