@three-ws/x402-payment-modal 1.1.0 → 1.2.0

package/README.md

@@ -1,11 +1,20 @@
 # @three-ws/x402-payment-modal
 
-**A drop-in payment modal for any [x402](https://x402.org) paid endpoint.** One ES
-module, zero runtime dependencies. It turns an HTTP `402 Payment Required`
-challenge into a polished checkout: wallet connect (Phantom on Solana, MetaMask /
-any EVM wallet on Base via EIP-3009), the `402 → sign → settle` flow, optional
-SIWX re-entry, client-side spending caps, and a receipt — vanilla JS, no bundler
-required.
+> The complete drop-in checkout for any [x402](https://x402.org) paid endpoint — wallet connect, sign, settle, receipt.
+
+[![npm](https://img.shields.io/npm/v/@three-ws/x402-payment-modal.svg)](https://www.npmjs.com/package/@three-ws/x402-payment-modal)
+[![npm downloads](https://img.shields.io/npm/dm/@three-ws/x402-payment-modal.svg)](https://www.npmjs.com/package/@three-ws/x402-payment-modal)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@three-ws/x402-payment-modal.svg)](https://bundlephobia.com/package/@three-ws/x402-payment-modal)
+[![License: Proprietary](https://img.shields.io/badge/license-Proprietary-red.svg)](./LICENSE)
+
+**A drop-in payment modal for any [x402](https://x402.org) paid endpoint.** The
+browser client is one ES module with zero runtime dependencies; it turns an HTTP
+`402 Payment Required` challenge into a polished checkout: wallet connect (Phantom
+/ Solflare / Backpack on Solana, MetaMask / any EVM wallet on Base via EIP-3009),
+the `402 → sign → settle` flow, optional SIWX re-entry, client-side spending caps,
+and a receipt. It ships a **server** checkout adapter for the Solana rail
+(`./server`, `./server/express`, `./server/vercel`) and a **React** wrapper
+(`./react`) — pick only the pieces you need. Vanilla JS, no bundler required.
 
 ```html
 <script type="module" src="https://unpkg.com/@three-ws/x402-payment-modal"></script>
@@ -41,17 +50,61 @@ throttle retries, and the receipt, so you ship a paid endpoint in minutes.
 - **Solana + EVM.** Phantom (Solana) and any injected EVM wallet (Base USDC
   via EIP-3009 `transferWithAuthorization`). The modal picks the right path from
   the 402 challenge.
-- **Pay in USDC _or_ THREE on Solana.** Offer both and the buyer gets a token
-  picker — pay in USDC, or in [$THREE](https://three.ws/three-token), the three.ws
-  utility token, recognized on sight (symbol, decimals, branding). See
-  [Accepting multiple Solana tokens](#accepting-multiple-solana-tokens-usdc--three).
+- **USDC by default, multi-token if you want it.** USDC is the always-on default
+  on Solana. Optionally offer a second SPL token (the modal ships a built-in
+  `THREE` opt-in) and the buyer gets a token picker — each token is recognized on
+  sight (symbol, decimals). See
+  [Accepting multiple Solana tokens](#accepting-multiple-solana-tokens).
 - **SIWX re-entry.** If a wallet already paid for a resource, it can sign back in
   instead of paying again. See [docs/siwx.md](docs/siwx.md).
 - **Spending caps.** Optional per-call / hourly / daily caps enforced in the
   browser. See [docs/spending-caps.md](docs/spending-caps.md).
-- **Themeable.** Light + automatic dark mode, all classes overridable. See
+- **Themeable.** Light + automatic dark mode, a full `--x402-*` design-token
+  surface, runtime brand-matching, and a header logo. See
   [docs/theming.md](docs/theming.md).
-- **Accessible.** Focus management, `aria-modal`, keyboard `Esc` to close.
+- **Accessible.** Focus trap + restore, `aria-modal`, `aria-live` step
+  announcements, `:focus-visible` rings, `prefers-reduced-motion`, keyboard `Esc`
+  to close.
+- **Server + React adapters in the box.** Framework-agnostic Solana checkout
+  (`./server`) with Express and Vercel adapters, and a first-class React wrapper
+  (`./react`) — all behind separate export subpaths, all optional.
+
+---
+
+## Which x402 modal do I want?
+
+This package has a lighter sibling, **[`@three-ws/x402-modal`](https://www.npmjs.com/package/@three-ws/x402-modal)**.
+Both render a drop-in modal; choose by how much you need.
+
+| | **`@three-ws/x402-payment-modal`** (this) | `@three-ws/x402-modal` |
+| --- | --- | --- |
+| Goal | Full checkout SDK: client **+ server + React** | Minimal client-only modal |
+| Chains | Solana **and** EVM (Base/Arbitrum/Optimism) | Client modal, EVM-leaning |
+| Solana server adapter | ✅ `./server` + Express + Vercel | ❌ bring your own |
+| React wrapper | ✅ `./react` (`X402Button`, `useX402`) | ❌ |
+| SIWX re-entry | ✅ | — |
+| Client spending caps | ✅ per-call / hour / day | — |
+| Multi-token picker (USDC + opt-in SPL) | ✅ | — |
+| Builder-code (ERC-8021) echo | ✅ | — |
+| Footprint | Larger (more surface) | Smaller, fewer knobs |
+
+**Rule of thumb:** taking real Solana payments, want a React component, or need
+caps/SIWX → use **this** package. Just need a tiny EVM paywall button and nothing
+else → the lighter `@three-ws/x402-modal` is enough.
+
+## Package subpaths
+
+Import only what you use — each subpath is independent and its peer deps are
+optional.
+
+| Subpath | Import | Needs |
+| --- | --- | --- |
+| `.` | `@three-ws/x402-payment-modal` | nothing (browser) |
+| `./min` | `@three-ws/x402-payment-modal/min` | nothing — pre-minified bundle |
+| `./server` | `@three-ws/x402-payment-modal/server` | `@solana/web3.js`, `@solana/spl-token` |
+| `./server/express` | `@three-ws/x402-payment-modal/server/express` | + `express` |
+| `./server/vercel` | `@three-ws/x402-payment-modal/server/vercel` | `@solana/web3.js`, `@solana/spl-token` |
+| `./react` | `@three-ws/x402-payment-modal/react` | `react` |
 
 ---
 
@@ -73,15 +126,28 @@ npm install @three-ws/x402-payment-modal
 import { pay, configure } from '@three-ws/x402-payment-modal';
 ```
 
-For Solana payments you also run a tiny server endpoint — install the optional
-peer deps there:
+### Optional peer dependencies
+
+The core client has **no runtime dependencies**. The other subpaths declare
+*optional* peer deps — install them only when you use that subpath:
+
+| You use… | Install |
+| --- | --- |
+| `./server` or `./server/vercel` (Solana checkout) | `@solana/web3.js @solana/spl-token` |
+| `./server/express` | `@solana/web3.js @solana/spl-token express` |
+| `./react` | `react` (you already have it) |
 
 ```bash
+# Solana checkout server
 npm install @solana/web3.js @solana/spl-token
+# …and express if you use the Express adapter
+npm install express
 ```
 
 > EVM-only sites need **nothing** server-side: the wallet signs EIP-3009
-> typed-data entirely in the browser.
+> typed-data entirely in the browser. The Solana/EVM crypto helpers used by the
+> client are loaded lazily from a CDN **only** when a payment is attempted, so
+> they are not in your bundle.
 
 ---
 
@@ -135,34 +201,34 @@ server.
 
 ---
 
-## How it works
-
-```
- click ──▶ GET/POST endpoint
-            │
-            ▼  HTTP 402  { accepts: [ {network, amount, asset, payTo, ...} ] }
-       ┌─────────────┐
-       │   discover  │  modal shows price + network
-       └─────────────┘
-            │
-            ▼
-       ┌─────────────┐
-       │   connect   │  Phantom (Solana)  or  EVM wallet (Base)
-       └─────────────┘
-            │
-       ┌────┴───────────────────────────────────────┐
-       ▼ Solana                                       ▼ EVM
-  POST /api/x402-checkout?action=prepare          sign EIP-3009
-  Phantom signTransaction                         transferWithAuthorization
-  POST /api/x402-checkout?action=encode           (browser only — no server)
-       └────┬───────────────────────────────────────┘
-            ▼
-       ┌─────────────┐
-       │   verify    │  retry endpoint with `X-PAYMENT: <base64>`
-       └─────────────┘   (auto-retries once on a 429 throttle)
-            │
-            ▼  200 + `X-PAYMENT-RESPONSE` settlement header
-        receipt + result
+## Architecture
+
+Three independent pieces, each optional except the client:
+
+- **Client** (`.` / `./min`) — renders the modal, detects wallets, drives the
+  `402 → sign → settle` flow. Zero runtime deps.
+- **Server adapter** (`./server*`) — Solana only. Builds the SPL transfer Phantom
+  signs and wraps it into the `X-PAYMENT` envelope. EVM never touches it.
+- **React wrapper** (`./react`) — `X402Button` + `useX402`, SSR-safe.
+
+```mermaid
+flowchart TD
+    A[User clicks pay] --> B[Client: GET/POST endpoint]
+    B --> C{HTTP 402 + accepts?}
+    C -->|no, 200| X[Error: not an x402 endpoint]
+    C -->|yes| D[discover: show price + network]
+    D --> E[connect: pick & connect wallet]
+    E --> F{network}
+    F -->|EVM| G[sign EIP-3009 typed-data\nbrowser only, no server]
+    F -->|Solana| H[POST ./server ?action=prepare]
+    H --> I[Phantom signs the v0 tx]
+    I --> J[POST ./server ?action=encode → X-PAYMENT]
+    G --> K[verify: retry with X-PAYMENT]
+    J --> K
+    K --> L{settled?}
+    L -->|429 throttle| K
+    L -->|2xx| M[receipt + result → resolve PayResult]
+    L -->|4xx/5xx| N[error + roll back any cap reservation]
 ```
 
 Full walkthrough in [docs/architecture.md](docs/architecture.md).
@@ -235,12 +301,18 @@ configure({
 | `checkoutOrigin` | `data-x402-checkout-origin` | the script's own origin |
 | `checkoutPath` | `data-x402-checkout-path` | `/api/x402-checkout` |
 | `footerNote` | `data-x402-footer-note` | `x402 · onchain settled` |
-| `brand.name` / `brand.url` | `data-x402-brand-name` / `-brand-url` | `three.ws` |
-| `builderCode.wallet` / `.service` | `data-x402-builder-wallet` / `-builder-service` | three.ws codes |
+| `brand.name` / `brand.url` | `data-x402-brand-name` / `-brand-url` | `null` (footer link hidden) |
+| `brand.logo` | — | `null` (no header logo) |
+| `theme` | — | `'auto'` (follow the OS) |
+| `cssVars` | — | `null` (use built-in tokens) |
+| `builderCode.wallet` / `.service` | `data-x402-builder-wallet` / `-builder-service` | `''` (no self-attribution) |
 | `esm.solanaWeb3` / `esm.nobleHashesSha3` | — | pinned esm.sh URLs |
 
-Repoint `esm.*` at a self-hosted mirror if a strict Content-Security-Policy
-blocks `esm.sh`. (The EVM/Base path needs no third-party code at all.)
+`theme` is `'auto' | 'light' | 'dark'`; `cssVars` is a flat map of `--x402-*`
+design tokens (e.g. `{ '--x402-accent': '#ff5c00', '--x402-radius': '8px' }`) for
+runtime brand-matching — see [docs/theming.md](docs/theming.md). Repoint `esm.*`
+at a self-hosted mirror if a strict Content-Security-Policy blocks `esm.sh`. (The
+EVM/Base path needs no third-party code at all.)
 
 ---
 
@@ -268,20 +340,62 @@ app.listen(3000);
 export { default } from '@three-ws/x402-payment-modal/server/vercel';
 ```
 
-Lower-level helpers (`prepareSolanaCheckout`, `encodeX402Payment`,
-`handleCheckout`, `CheckoutError`) are exported from
+Pass `rpcUrls: [...]` (an ordered list, tried with failover) instead of a single
+`rpcUrl` for production — the public RPC is rate-limited and warns once at
+startup. Lower-level helpers (`prepareSolanaCheckout`, `encodeX402Payment`,
+`handleCheckout`, `CheckoutError`, `solanaAccept`) are exported from
 `@three-ws/x402-payment-modal/server`. Full guide:
 [docs/server-setup.md](docs/server-setup.md).
 
 ---
 
-## Accepting multiple Solana tokens (USDC + THREE)
+## React
+
+The `./react` subpath ships a hook and a button. The browser-only core is
+dynamically imported on first use, so both are **SSR-safe** — nothing runs during
+render or on the server.
+
+```jsx
+import { X402Button, useX402 } from '@three-ws/x402-payment-modal/react';
+
+// Drop-in button:
+<X402Button
+  endpoint="/api/paid/summarize"
+  method="POST"
+  body={{ url: 'https://en.wikipedia.org/wiki/x402' }}
+  merchant="Acme"
+  action="Summarize"
+  label="Summarize for $0.01"
+  onResult={(r) => console.log('paid', r.payment)}
+  onError={(e) => console.error(e)}
+/>;
+
+// …or drive it yourself with the hook:
+function Buy() {
+  const { pay, isPaying, result, error } = useX402({ merchant: 'Acme' });
+  return (
+    <button disabled={isPaying} onClick={() => pay({ endpoint: '/api/paid/summarize' })}>
+      {isPaying ? 'Processing…' : 'Pay'}
+    </button>
+  );
+}
+```
+
+`useX402(defaults)` returns `{ pay, status, result, error, reset, isPaying }`
+where `status` is `idle | paying | done | error`. Full reference:
+[docs/react.md](docs/react.md).
+
+---
 
-An x402 challenge can list more than one accepted payment. List a USDC accept
-**and** a [$THREE](https://three.ws/three-token) accept on Solana, and the modal
-renders a token picker: the buyer chooses which to pay in, the headline price and
-the transaction follow the choice. No client wiring — the checkout endpoint
-already builds an SPL transfer for whatever mint the chosen accept names.
+## Accepting multiple Solana tokens
+
+USDC is the default settlement asset, but an x402 challenge can list more than one
+accepted payment. List a USDC accept **and** a second SPL-token accept on Solana,
+and the modal renders a token picker: the buyer chooses which to pay in, the
+headline price and the transaction follow the choice. No client wiring — the
+checkout endpoint already builds an SPL transfer for whatever mint the chosen
+accept names. The package ships a built-in `THREE` opt-in token as a ready
+example, but any mint works.
 
 Build the accepts with the `solanaAccept` helper (no hardcoded mints):
 
@@ -304,9 +418,10 @@ and emits a spec-shaped `accept`. The constants `THREE_MINT`, `USDC_MINT_SOLANA`
 and `WELL_KNOWN_SOLANA_TOKENS` are exported too. On the client, the same mints
 are exposed at `window.X402.tokens` for inline merchants.
 
-> **THREE is a utility token, not a stablecoin.** Its price floats, so the modal
-> can't dollar-denominate it for browser-side spending caps — enforce caps for
-> THREE server-side. USDC caps work in the browser as usual.
+> **Non-stable tokens float against the dollar.** The modal can't
+> dollar-denominate a floating-price token for browser-side spending caps — so
+> enforce caps for any non-stable token (like `THREE`) server-side. USDC and
+> other stablecoin caps work in the browser as usual.
 
 ---
 
@@ -315,10 +430,13 @@ are exposed at `window.X402.tokens` for inline merchants.
 - [Architecture](docs/architecture.md) — the full payment lifecycle.
 - [Client API reference](docs/api-reference.md)
 - [Server setup](docs/server-setup.md)
+- [React reference](docs/react.md) — `X402Button` + `useX402`.
 - [Theming](docs/theming.md)
 - [SIWX re-entry](docs/siwx.md)
 - [Spending caps](docs/spending-caps.md)
+- [Examples](docs/EXAMPLES.md) — runnable plain-HTML, React, and Express samples.
 - [Tutorial](TUTORIAL.md) — build a paid endpoint end-to-end.
+- [Contributing](CONTRIBUTING.md)
 
 ---
 
@@ -334,14 +452,71 @@ Modern evergreen browsers (ES2020, `BigInt`, dynamic `import()`, `fetch`,
 - Payments are signed in the user's wallet — this package never sees a private
   key. The Solana checkout server only builds an unsigned transaction and base64-
   wraps the user-signed one; it cannot move funds.
+- **SIWX** re-entry is a gasless CAIP-122 signature, never a transfer. The client
+  detects the offer, signs, and submits the proof; the **server** must verify the
+  nonce/domain/expiry/signature and check the entitlement — see
+  [docs/siwx.md](docs/siwx.md).
 - Spending caps are a **client-side guardrail**, not a security boundary — a user
   can clear `localStorage`. Enforce real limits server-side.
-- Pin the script to a version or self-host it for production.
+- Pin the script to a version or self-host it for production (the lazily-loaded
+  crypto helpers can be repointed at a mirror via `configure({ esm })` to satisfy
+  a strict CSP).
+
+## FAQ & troubleshooting
+
+**The modal opens but says "Couldn't confirm the price."**
+Discovery hit a response that wasn't an x402 challenge. The endpoint must answer
+the *unpaid* request with HTTP `402` (or an MCP-style `401`) carrying an `accepts`
+array — in the JSON body or a base64 `payment-required` header. A `200` means the
+endpoint isn't paywalled; the modal surfaces that instead of silently succeeding.
+
+**Do I need a server?**
+Only for **Solana**. EVM (Base/Arbitrum/Optimism USDC) signs EIP-3009 typed-data
+entirely in the browser. For Solana, mount `./server` so the modal can build the
+SPL transfer Phantom signs — see [docs/server-setup.md](docs/server-setup.md).
+
+**Solana payments fail with an RPC error under load.**
+You're on the public RPC (it warns once at startup). Pass a dedicated endpoint —
+`x402CheckoutRouter({ rpcUrls: ['https://your-helius-url', ...] })` — and the
+adapter rotates across the list on transient failures.
+
+**A Token-2022 mint (e.g. THREE) wouldn't settle in an older version.**
+Fixed in 1.2.0 — the server now detects each mint's owning program (legacy SPL
+Token vs Token-2022) and derives ATAs and `transferChecked` against the right one.
+
+**`esm.sh` is blocked by my Content-Security-Policy.**
+The client lazy-loads `@solana/web3.js` and `@noble/hashes` from a CDN only when a
+payment is attempted. Repoint them at a self-hosted mirror:
+`configure({ esm: { solanaWeb3: '/vendor/solana-web3.js', nobleHashesSha3: '/vendor/noble-sha3.js' } })`.
+EVM-only sites load no third-party code at all.
+
+**Why did `pay()` reject?**
+A user dismissing the modal rejects with `err.code === 'cancelled'` — treat it as
+a no-op, not a failure. Any other rejection is a real error. The declarative
+auto-binder swallows cancellation and only fires `x402:error` for genuine failures.
+
+**My spending caps don't apply to a non-stablecoin.**
+Browser caps are denominated in micro-USD and the dependency-free client doesn't
+fetch live prices, so caps only bind stablecoins (USDC/USDT/DAI). Enforce caps for
+floating-price tokens server-side — see [docs/spending-caps.md](docs/spending-caps.md).
+
+**Can the user pick which token to pay in?**
+Yes — if the 402 challenge lists more than one Solana `accept`, the modal renders
+a token picker. See [Accepting multiple Solana tokens](#accepting-multiple-solana-tokens).
+
+---
+
+## Related packages
+
+- **[`@three-ws/x402-modal`](https://www.npmjs.com/package/@three-ws/x402-modal)** —
+  the lighter client-only sibling. See [the comparison above](#which-x402-modal-do-i-want).
+- **[x402 protocol](https://x402.org)** — the open "HTTP 402 Payment Required"
+  micropayment standard this package implements (v2 envelope).
 
 ## License
 
-[Apache-2.0](LICENSE) © three.ws
+Proprietary — Copyright (c) 2026 nirholas. All Rights Reserved. Unauthorized use, copying, modification, or distribution is prohibited. See [LICENSE](./LICENSE).
 
-> Maintained inside the [three.ws](https://three.ws) monorepo and published as a
-> standalone package. Issues and PRs:
-> <https://github.com/nirholas/three.ws/issues>.
+> Standalone package. Browser client is dependency-free; server/react peer deps
+> are optional. Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and
+> <https://github.com/nirholas/x402-payment-modal/issues>.

package/dist/index.d.ts

@@ -58,12 +58,17 @@ export interface PayResult {
 	};
 }
 
-/** Branding shown in the modal footer. */
+/** Branding shown in the modal header/footer. */
 export interface BrandConfig {
 	name?: string;
 	url?: string;
+	/** Logo shown in the modal header (URL). */
+	logo?: string;
 }
 
+/** Forced color scheme. `auto` (default) follows the OS preference. */
+export type X402Theme = 'auto' | 'light' | 'dark';
+
 /** ERC-8021 builder-code self-attribution echoed when the 402 challenge declares one. */
 export interface BuilderCodeConfig {
 	wallet?: string;
@@ -84,6 +89,10 @@ export interface X402Config {
 	footerNote?: string;
 	builderCode?: BuilderCodeConfig;
 	esm?: EsmConfig;
+	/** Force the modal's color scheme. Default `auto` (follow the OS). */
+	theme?: X402Theme;
+	/** Flat map of `--x402-*` design tokens to brand-match at runtime, e.g. `{ '--x402-accent': '#ff5c00' }`. */
+	cssVars?: Record<string, string> | null;
 }
 
 /**
@@ -107,8 +116,10 @@ export const version: string;
 
 /** Solana USDC mint (mainnet). */
 export const USDC_MINT_SOLANA: string;
-/** $THREE — the three.ws utility token mint. Recognized by the modal so a 402
- *  `accept` using it renders as THREE without merchant-supplied metadata. */
+/** THREE — an optional opt-in SPL token mint recognized by the modal so a 402
+ *  `accept` using it renders as THREE without merchant-supplied metadata. USDC
+ *  remains the always-on default; this token is used only when an endpoint
+ *  chooses to accept it. */
 export const THREE_MINT: string;
 
 export interface KnownSolanaToken {