@three-ws/x402-payment-modal 1.1.0

package/docs/theming.md

@@ -0,0 +1,124 @@
+# Theming
+
+The modal ships its own styles so it looks finished out of the box, then gives
+you clean hooks to skin it to your brand. There is no build step and no CSS file
+to import — styles are injected at runtime.
+
+For the markup these classes wrap, see the step model in
+[architecture](./architecture.md).
+
+## How styles are injected
+
+On first use, the modal injects a single `<style id="x402-styles">` block into
+the document head. It is injected **once**; subsequent opens reuse it.
+
+To override it, do one of:
+
+1. Define your own rules with **higher specificity** in a stylesheet loaded
+   **after** the module runs (so your rules win on equal specificity, or beat
+   the injected ones).
+2. Use `!important` on the specific declarations you want to force.
+3. Override the exposed **CSS custom property** (`--x402-z`) where one exists.
+
+The modal is **light by default** and includes a built-in dark theme via
+`@media (prefers-color-scheme: dark)` — it follows the OS setting automatically.
+
+## CSS classes
+
+| Class                  | Element / role                                                      |
+|------------------------|---------------------------------------------------------------------|
+| `.x402-overlay`        | Root overlay. Holds `--x402-z` (z-index, default `2147483600`).      |
+| `.x402-modal`          | The modal card container.                                           |
+| `.x402-head`           | Header region (merchant/action/close).                             |
+| `.x402-merchant`       | Merchant block in the header.                                       |
+| `.x402-name`           | Merchant name text.                                                 |
+| `.x402-action`         | Action label text (from `action`).                                 |
+| `.x402-close`          | Close button.                                                       |
+| `.x402-price-row`      | Row holding price + network.                                       |
+| `.x402-price`          | Numeric price.                                                     |
+| `.x402-currency`       | Currency label (e.g. USDC).                                        |
+| `.x402-network`        | Network badge (e.g. Base / Solana).                               |
+| `.x402-body`           | Main content area.                                                 |
+| `.x402-step`           | A lifecycle step row. Modifiers below.                             |
+| `.x402-step.x402-active` | The step currently in progress.                                 |
+| `.x402-step.x402-done` | A completed step.                                                  |
+| `.x402-step.x402-error`| A step that failed.                                               |
+| `.x402-wallet-btn`     | A wallet choice button (Phantom / EVM).                           |
+| `.x402-pay-btn`        | Primary pay / confirm button.                                     |
+| `.x402-pay-secondary`  | Secondary action button (e.g. demoted pay under SIWX).            |
+| `.x402-error-box`      | Error message container.                                          |
+| `.x402-receipt`        | Settled-payment receipt block.                                    |
+| `.x402-result`         | The paid endpoint's returned result.                             |
+| `.x402-foot`           | Footer (brand attribution + footer note).                        |
+
+The four `.x402-step` rows correspond to the discover / connect / authorize /
+verify lifecycle described in [architecture](./architecture.md).
+
+## Overriding the z-index
+
+The overlay z-index is a custom property so you can lower it under your own
+top-layer UI (or raise it) without touching the rest of the stylesheet:
+
+```css
+.x402-overlay {
+  --x402-z: 9999;
+}
+```
+
+Default is `2147483600` (just under the 32-bit max) so the modal sits above most
+app chrome.
+
+## Dark mode
+
+Dark styling is automatic via `prefers-color-scheme: dark`. To force a single
+theme regardless of OS, override the relevant classes. For example, to force the
+light look everywhere:
+
+```css
+@media (prefers-color-scheme: dark) {
+  .x402-modal { background: #ffffff; color: #111111; }
+}
+```
+
+## Worked example: brand the pay button and modal radius
+
+Load this **after** the module so it wins:
+
+```html
+<script type="module" src="https://unpkg.com/@three-ws/x402-payment-modal"></script>
+<style>
+  /* Rounder card */
+  .x402-modal {
+    border-radius: 18px;
+  }
+
+  /* Brand-colored primary button with a hover lift */
+  .x402-pay-btn {
+    background: #4f46e5;          /* indigo */
+    color: #fff;
+    border: none;
+    transition: transform 120ms ease, background 120ms ease;
+  }
+  .x402-pay-btn:hover {
+    background: #4338ca;
+    transform: translateY(-1px);
+  }
+  .x402-pay-btn:active {
+    transform: translateY(0);
+  }
+  .x402-pay-btn:focus-visible {
+    outline: 2px solid #818cf8;
+    outline-offset: 2px;
+  }
+
+  /* Tone down the secondary action */
+  .x402-pay-secondary {
+    background: transparent;
+    color: #4f46e5;
+  }
+</style>
+```
+
+If a rule still loses to the injected stylesheet, raise specificity (e.g.
+`.x402-overlay .x402-pay-btn`) or add `!important` to the individual
+declarations.

package/examples/README.md

@@ -0,0 +1,22 @@
+# Examples
+
+Runnable examples for [`@three-ws/x402-payment-modal`](https://www.npmjs.com/package/@three-ws/x402-payment-modal)
+— a zero-dependency, vanilla-JS payment modal for any x402 paid HTTP endpoint.
+
+| Example | What it shows | Fastest way to try it |
+| --- | --- | --- |
+| [`plain-html/`](./plain-html) | No build step. Declarative `data-x402-*` buttons, a programmatic `pay()` call, and `x402:result` / `x402:error` event handling — all from a single CDN `<script>`. | Open `plain-html/index.html` in a browser (or serve the folder, e.g. `npx serve plain-html`). |
+| [`react/`](./react) | A reusable `<X402Button>` component that wraps `pay()` with a dynamic import, so it is SSR-safe. | Copy `react/X402Button.jsx` into your app — see [`react/README.md`](./react/README.md). |
+| [`server-express/`](./server-express) | A complete Express server that mounts the Solana checkout router and serves a demo paid endpoint returning a real x402 v2 challenge. | `cd server-express && npm install && npm start`, then open http://localhost:3000 |
+
+## Which do I need?
+
+- **EVM payments** sign in the browser (EIP-3009) — the **plain-html** or
+  **react** client is all you need.
+- **Solana payments** also require the **server-express** checkout endpoint to
+  build and settle the transfer. See
+  [`../docs/server-setup.md`](../docs/server-setup.md).
+
+> The client examples point at placeholder endpoints
+> (`https://api.example.com/...`). Swap in a real x402-enabled endpoint to take
+> an actual payment.

package/examples/plain-html/index.html

@@ -0,0 +1,229 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>x402 Payment Modal — Plain HTML demo</title>
+
+  <!--
+    ─────────────────────────────────────────────────────────────────────────
+    DEMO ONLY
+
+    This page shows three ways to use @three-ws/x402-payment-modal with no
+    build step at all — just an ES module loaded from a CDN.
+
+      (a) Declarative: a button annotated with data-x402-* attributes. The
+          library auto-binds these on load — zero JavaScript required.
+      (b) Programmatic: a button wired in an inline module that imports pay().
+      (c) Events: x402:result / x402:error bubble from the clicked element;
+          we listen and render the outcome into #outcome below.
+
+    The endpoint below (https://api.example.com/...) is a PLACEHOLDER. To
+    actually take a payment, point data-x402-endpoint / pay({ endpoint }) at a
+    REAL x402-enabled HTTP endpoint that responds with HTTP 402 + an x402
+    challenge. The modal handles the 402 → connect wallet → sign → settle flow.
+
+    Self-hosting: instead of the unpkg URL you can serve the module yourself,
+    e.g. <script type="module" src="/vendor/x402.min.js" ...>. The data-x402-*
+    config attributes work the same way on a self-hosted <script> tag.
+    ─────────────────────────────────────────────────────────────────────────
+  -->
+
+  <style>
+    :root {
+      --bg: #0b0c10;
+      --card: #15171e;
+      --border: #262a35;
+      --text: #e7e9ee;
+      --muted: #9aa1b1;
+      --accent: #6c8cff;
+      --accent-press: #5476f5;
+      --ok: #3ddc97;
+      --err: #ff6b6b;
+    }
+    * { box-sizing: border-box; }
+    html, body { height: 100%; }
+    body {
+      margin: 0;
+      background: radial-gradient(1200px 600px at 50% -10%, #1a1d27 0%, var(--bg) 60%);
+      color: var(--text);
+      font: 15px/1.5 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+      display: grid;
+      place-items: center;
+      padding: 32px 16px;
+    }
+    .card {
+      width: 100%;
+      max-width: 520px;
+      background: var(--card);
+      border: 1px solid var(--border);
+      border-radius: 16px;
+      padding: 28px;
+      box-shadow: 0 24px 60px rgba(0, 0, 0, 0.45);
+    }
+    h1 { font-size: 20px; margin: 0 0 4px; letter-spacing: -0.01em; }
+    p.lede { margin: 0 0 22px; color: var(--muted); }
+    h2 {
+      font-size: 12px;
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+      color: var(--muted);
+      margin: 22px 0 8px;
+    }
+    .row { display: flex; gap: 10px; flex-wrap: wrap; align-items: center; }
+    button {
+      appearance: none;
+      border: 0;
+      border-radius: 10px;
+      padding: 11px 18px;
+      font: inherit;
+      font-weight: 600;
+      color: #fff;
+      background: var(--accent);
+      cursor: pointer;
+      transition: transform 0.08s ease, background 0.15s ease, box-shadow 0.15s ease;
+    }
+    button:hover { background: var(--accent-press); }
+    button:active { transform: translateY(1px); }
+    button:focus-visible { outline: 2px solid #fff; outline-offset: 2px; }
+    button[disabled] { opacity: 0.55; cursor: progress; }
+    .hint { color: var(--muted); font-size: 13px; }
+    code {
+      background: #0c0e14;
+      border: 1px solid var(--border);
+      border-radius: 6px;
+      padding: 1px 6px;
+      font-size: 12px;
+    }
+    #outcome {
+      margin-top: 22px;
+      min-height: 44px;
+      border: 1px dashed var(--border);
+      border-radius: 12px;
+      padding: 14px 16px;
+      color: var(--muted);
+      font-size: 13px;
+      white-space: pre-wrap;
+      word-break: break-word;
+      transition: border-color 0.2s ease;
+    }
+    #outcome.ok { border-color: var(--ok); color: var(--ok); }
+    #outcome.err { border-color: var(--err); color: var(--err); }
+    .footer { margin-top: 20px; color: var(--muted); font-size: 12px; }
+    a { color: var(--accent); }
+  </style>
+
+  <!--
+    (a) Declarative usage.
+
+    Loading the module runs init() automatically: any element carrying a
+    data-x402-endpoint attribute becomes a pay trigger. Config that applies to
+    the whole page (brand, where the Solana checkout endpoint lives) rides on
+    THIS script tag as data-x402-* attributes.
+  -->
+  <script
+    type="module"
+    src="https://unpkg.com/@three-ws/x402-payment-modal"
+    data-x402-brand-name="Acme Summaries"
+    data-x402-brand-url="https://example.com"
+    data-x402-checkout-origin="https://example.com"
+    data-x402-footer-note="Payments settle in USDC. Powered by x402."
+  ></script>
+</head>
+
+<body>
+  <main class="card">
+    <h1>x402 Payment Modal</h1>
+    <p class="lede">Pay any x402 endpoint in one click — no wallet integration code.</p>
+
+    <!-- (a) Zero-JS declarative button. The attributes describe the request. -->
+    <h2>Declarative (no JavaScript)</h2>
+    <div class="row">
+      <button
+        id="declarative-pay"
+        data-x402-endpoint="https://api.example.com/paid/summarize"
+        data-x402-method="POST"
+        data-x402-body='{"url":"https://en.wikipedia.org/wiki/x402"}'
+        data-x402-merchant="Acme Summaries"
+        data-x402-action="Summarize article"
+      >
+        Summarize for 0.01 USDC
+      </button>
+      <span class="hint">Driven entirely by <code>data-x402-*</code> attributes.</span>
+    </div>
+
+    <!-- (b) Programmatic button — wired by the inline module below. -->
+    <h2>Programmatic (inline module)</h2>
+    <div class="row">
+      <button id="programmatic-pay">Translate for 0.01 USDC</button>
+      <span class="hint">Calls <code>pay()</code> from a <code>&lt;script type="module"&gt;</code>.</span>
+    </div>
+
+    <!-- (c) Outcome surface — populated by the x402:result / x402:error listeners. -->
+    <h2>Outcome</h2>
+    <div id="outcome" role="status" aria-live="polite">No payment attempted yet.</div>
+
+    <p class="footer">
+      Endpoints above are placeholders — swap in a real x402 endpoint to take a payment.
+      You can also self-host the module instead of unpkg.
+    </p>
+  </main>
+
+  <script type="module">
+    // (b) Programmatic usage: import pay() straight from the CDN module.
+    // In a self-hosted setup, import from your own URL instead, e.g.
+    //   import { pay } from '/vendor/x402.min.js';
+    import { pay } from 'https://unpkg.com/@three-ws/x402-payment-modal';
+
+    const button = document.getElementById('programmatic-pay');
+
+    button.addEventListener('click', async () => {
+      button.disabled = true;
+      const original = button.textContent;
+      button.textContent = 'Processing…';
+      try {
+        const result = await pay({
+          endpoint: 'https://api.example.com/paid/translate',
+          method: 'POST',
+          body: { text: 'Hello, world', to: 'es' },
+          merchant: 'Acme Translate',
+          action: 'Translate text',
+        });
+        // result = { ok, result, payment?, siwx?, response }
+        console.log('Payment result:', result);
+      } catch (err) {
+        // The modal rejects with err.code === 'cancelled' when dismissed.
+        if (err && err.code === 'cancelled') {
+          console.log('User cancelled the payment.');
+        } else {
+          console.error('Payment failed:', err);
+        }
+      } finally {
+        button.disabled = false;
+        button.textContent = original;
+      }
+    });
+
+    // (c) Event listeners. x402:result and x402:error bubble from the element
+    // that triggered the payment, so a single document-level listener covers
+    // both the declarative and programmatic buttons.
+    const outcome = document.getElementById('outcome');
+
+    document.addEventListener('x402:result', (event) => {
+      const detail = event.detail; // PayResult: { ok, result, payment?, siwx?, response }
+      outcome.className = 'ok';
+      const payer = detail.payment?.payer ? `\nPayer: ${detail.payment.payer}` : '';
+      const tx = detail.payment?.transaction ? `\nTx: ${detail.payment.transaction}` : '';
+      outcome.textContent = `Paid ✓  (${detail.payment?.network ?? 'settled'})${payer}${tx}`;
+    });
+
+    // detail.error is a string. Note: dismissing the modal does NOT fire this
+    // event — the auto-binder swallows the cancellation — so anything here is a
+    // genuine failure.
+    document.addEventListener('x402:error', (event) => {
+      outcome.className = 'err';
+      outcome.textContent = `Payment failed: ${event.detail?.error ?? 'unknown error'}`;
+    });
+  </script>
+</body>
+</html>

package/examples/react/README.md

@@ -0,0 +1,69 @@
+# React example — `<X402Button>`
+
+A drop-in React component that wraps `pay()` from
+[`@three-ws/x402-payment-modal`](https://www.npmjs.com/package/@three-ws/x402-payment-modal).
+
+## Install
+
+```bash
+npm i @three-ws/x402-payment-modal
+```
+
+## Use it
+
+Copy [`X402Button.jsx`](./X402Button.jsx) into your project, then:
+
+```jsx
+import X402Button from './X402Button';
+
+export default function Demo() {
+  return (
+    <X402Button
+      endpoint="https://api.example.com/paid/summarize"
+      method="POST"
+      body={{ url: 'https://en.wikipedia.org/wiki/x402' }}
+      merchant="Acme Summaries"
+      action="Summarize article"
+      label="Summarize for 0.01 USDC"
+      onResult={(r) => console.log('paid', r.payment)}
+      onError={(e) => console.error('payment failed', e)}
+    />
+  );
+}
+```
+
+### Props
+
+| Prop       | Type       | Notes                                                       |
+| ---------- | ---------- | ---------------------------------------------------------- |
+| `endpoint` | `string`   | Required. The x402-enabled HTTP endpoint to call.          |
+| `method`   | `string`   | HTTP method (default `GET`).                               |
+| `body`     | `object`   | Request body (sent as JSON).                               |
+| `merchant` | `string`   | Display name shown in the modal.                           |
+| `action`   | `string`   | Short description of what the user is paying for.          |
+| `label`    | `string`   | Button text (default `Pay`). `children` overrides it.      |
+| `onResult` | `function` | Called with the `PayResult` on success.                    |
+| `onError`  | `function` | Called on failure. **Not** called when the user cancels.   |
+
+`onResult` receives `{ ok, result, payment?, siwx?, response }`.
+
+## SSR safety
+
+The package is browser-only (it renders a modal and connects to a wallet), so
+`X402Button` imports it lazily **inside the click handler**:
+
+```js
+const { pay } = await import('@three-ws/x402-payment-modal');
+```
+
+Nothing from the package runs during render or on the server, so the component
+is safe in Next.js, Remix, and other SSR frameworks without `dynamic`/`ssr:false`
+wrappers.
+
+## Solana payments need a server
+
+EVM payments sign in the browser (EIP-3009) and need no backend. **Solana
+payments require a checkout endpoint** that builds and settles the transfer.
+Stand one up before going live — see
+[`../../docs/server-setup.md`](../../docs/server-setup.md) and the runnable
+[`examples/server-express`](../server-express) server.

package/examples/react/X402Button.jsx

@@ -0,0 +1,84 @@
+/**
+ * <X402Button> — a thin React wrapper around @three-ws/x402-payment-modal.
+ *
+ * The package is a browser-only ES module (it renders a modal and talks to a
+ * wallet), so we dynamically import it INSIDE the click handler. That keeps the
+ * component SSR-safe: nothing from the package is touched during render or on
+ * the server.
+ *
+ * Usage:
+ *
+ *   import X402Button from './X402Button';
+ *
+ *   <X402Button
+ *     endpoint="https://api.example.com/paid/summarize"
+ *     method="POST"
+ *     body={{ url: 'https://en.wikipedia.org/wiki/x402' }}
+ *     merchant="Acme Summaries"
+ *     action="Summarize article"
+ *     label="Summarize for 0.01 USDC"
+ *     onResult={(r) => console.log('paid', r)}
+ *     onError={(e) => console.error(e)}
+ *   />
+ *
+ * For Solana payments your app must also run the server checkout endpoint
+ * (see ../../docs/server-setup.md and examples/server-express). EVM payments
+ * sign in-browser and need no server.
+ */
+
+import { useCallback, useState } from 'react';
+
+export default function X402Button({
+  endpoint,
+  method = 'GET',
+  body,
+  merchant,
+  action,
+  label = 'Pay',
+  onResult,
+  onError,
+  children,
+  ...rest
+}) {
+  const [processing, setProcessing] = useState(false);
+
+  const handleClick = useCallback(async () => {
+    if (processing) return;
+    setProcessing(true);
+
+    try {
+      // Dynamic import keeps the browser-only module out of the SSR bundle.
+      const { pay } = await import('@three-ws/x402-payment-modal');
+
+      const result = await pay({
+        endpoint,
+        method,
+        body,
+        merchant,
+        action,
+      });
+
+      // result = { ok, result, payment?, siwx?, response }
+      onResult?.(result);
+    } catch (err) {
+      // The modal rejects with err.code === 'cancelled' when the user dismisses
+      // it. That is not an error — stay silent so we don't flash a failure.
+      if (err && err.code === 'cancelled') return;
+      onError?.(err);
+    } finally {
+      setProcessing(false);
+    }
+  }, [processing, endpoint, method, body, merchant, action, onResult, onError]);
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      disabled={processing}
+      aria-busy={processing}
+      {...rest}
+    >
+      {processing ? 'Processing…' : children ?? label}
+    </button>
+  );
+}

package/examples/server-express/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "x402-checkout-example",
+  "private": true,
+  "version": "1.0.0",
+  "description": "Runnable Express server that mounts the @three-ws/x402-payment-modal Solana checkout router and serves a demo paid endpoint.",
+  "type": "module",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "@solana/spl-token": "*",
+    "@solana/web3.js": "*",
+    "@three-ws/x402-payment-modal": "*",
+    "express": "*"
+  }
+}

package/examples/server-express/public/index.html

@@ -0,0 +1,89 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>x402 Express checkout demo</title>
+  <style>
+    body {
+      margin: 0;
+      min-height: 100vh;
+      display: grid;
+      place-items: center;
+      background: #0b0c10;
+      color: #e7e9ee;
+      font: 15px/1.5 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    }
+    .card {
+      background: #15171e;
+      border: 1px solid #262a35;
+      border-radius: 16px;
+      padding: 28px;
+      max-width: 460px;
+      text-align: center;
+      box-shadow: 0 24px 60px rgba(0, 0, 0, 0.45);
+    }
+    h1 { font-size: 20px; margin: 0 0 6px; }
+    p { color: #9aa1b1; margin: 0 0 20px; }
+    button {
+      border: 0;
+      border-radius: 10px;
+      padding: 11px 18px;
+      font: inherit;
+      font-weight: 600;
+      color: #fff;
+      background: #6c8cff;
+      cursor: pointer;
+    }
+    button:hover { background: #5476f5; }
+    button[disabled] { opacity: 0.55; cursor: progress; }
+    #out {
+      margin-top: 18px;
+      min-height: 22px;
+      font-size: 13px;
+      color: #9aa1b1;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+  </style>
+</head>
+<body>
+  <main class="card">
+    <h1>x402 Express checkout demo</h1>
+    <p>Click to pay the local <code>/api/paid/hello</code> endpoint in USDC.</p>
+    <button id="pay">Say hello for 0.01 USDC</button>
+    <div id="out" role="status" aria-live="polite"></div>
+  </main>
+
+  <script type="module">
+    // Loaded from the CDN for the demo; bundle it locally for production.
+    import { pay, configure } from 'https://unpkg.com/@three-ws/x402-payment-modal';
+
+    // Tell the modal where this server's Solana checkout endpoint lives.
+    configure({
+      checkoutOrigin: window.location.origin,
+      checkoutPath: '/api/x402-checkout',
+      brand: { name: 'x402 Express demo', url: window.location.origin },
+    });
+
+    const out = document.getElementById('out');
+    document.getElementById('pay').addEventListener('click', async (e) => {
+      e.target.disabled = true;
+      try {
+        const result = await pay({
+          endpoint: '/api/paid/hello',
+          merchant: 'x402 Express demo',
+          action: 'Say hello',
+        });
+        out.textContent = `Paid ✓  ${JSON.stringify(result.result ?? result.ok)}`;
+      } catch (err) {
+        out.textContent = err?.code === 'cancelled'
+          ? 'Cancelled.'
+          : `Failed: ${err?.message ?? err}`;
+      } finally {
+        e.target.disabled = false;
+      }
+    });
+  </script>
+</body>
+</html>