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

package/examples/react/README.md

@@ -1,7 +1,9 @@
-# React example — `<X402Button>`
+# React example
 
-A drop-in React component that wraps `pay()` from
-[`@three-ws/x402-payment-modal`](https://www.npmjs.com/package/@three-ws/x402-payment-modal).
+Uses the package's **shipped** React wrapper —
+[`@three-ws/x402-payment-modal/react`](../../docs/react.md) — not a hand-rolled
+component. You get `<X402Button>` (a drop-in button) and `useX402()` (a headless
+hook), both SSR-safe.
 
 ## Install
 
@@ -9,12 +11,14 @@ A drop-in React component that wraps `pay()` from
 npm i @three-ws/x402-payment-modal
 ```
 
+`react` is an optional peer dependency you already have.
+
 ## Use it
 
-Copy [`X402Button.jsx`](./X402Button.jsx) into your project, then:
+[`App.jsx`](./App.jsx) shows both the button and the hook. The button form:
 
 ```jsx
-import X402Button from './X402Button';
+import { X402Button } from '@three-ws/x402-payment-modal/react';
 
 export default function Demo() {
   return (
@@ -24,7 +28,8 @@ export default function Demo() {
       body={{ url: 'https://en.wikipedia.org/wiki/x402' }}
       merchant="Acme Summaries"
       action="Summarize article"
-      label="Summarize for 0.01 USDC"
+      label="Summarize for $0.01"
+      caps={{ maxPerCall: 100_000 }}     // 0.10 USDC, stablecoin caps only
       onResult={(r) => console.log('paid', r.payment)}
       onError={(e) => console.error('payment failed', e)}
     />
@@ -32,38 +37,36 @@ export default function Demo() {
 }
 ```
 
-### Props
+The headless form, for full control over the trigger UI:
 
-| 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.   |
+```jsx
+import { useX402 } from '@three-ws/x402-payment-modal/react';
 
-`onResult` receives `{ ok, result, payment?, siwx?, response }`.
+function Buy() {
+  const { pay, isPaying } = useX402({ merchant: 'Acme' });
+  return (
+    <button disabled={isPaying} onClick={() => pay({ endpoint: '/api/paid/premium' })}>
+      {isPaying ? 'Processing…' : 'Pay'}
+    </button>
+  );
+}
+```
 
-## SSR safety
+### `<X402Button>` props
 
-The package is browser-only (it renders a modal and connects to a wallet), so
-`X402Button` imports it lazily **inside the click handler**:
+See the [React reference](../../docs/react.md#x402button) for the full table.
+`onResult` receives `{ ok, result, payment?, siwx?, response }`; `onError` is
+**not** called when the user cancels.
 
-```js
-const { pay } = await import('@three-ws/x402-payment-modal');
-```
+## SSR safety
 
-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.
+The wrapper dynamically imports the browser-only core on first payment, so nothing
+from the package runs during render or on the server — safe in Next.js, Remix, and
+Astro without a `dynamic`/`ssr:false` wrapper.
 
 ## 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
+EVM payments sign in the browser (EIP-3009) and need no backend. **Solana payments
+require a checkout endpoint** that builds and settles the transfer — see
 [`../../docs/server-setup.md`](../../docs/server-setup.md) and the runnable
-[`examples/server-express`](../server-express) server.
+[`examples/server-express`](../server-express).

package/examples/server-express/server.js

@@ -45,7 +45,7 @@ app.use('/api/x402-checkout', x402CheckoutRouter({ rpcUrl: SOLANA_RPC_URL }));
 // IMPORTANT: verifying and settling the X-PAYMENT payload against an x402
 // facilitator is OUT OF SCOPE for this demo. In production you would verify the
 // payment proof (and idempotency) before returning 200. See the docs:
-// https://github.com/three-ws/x402-payment-modal/tree/main/docs
+// https://github.com/nirholas/x402-payment-modal/tree/main/docs
 //
 // Synthetic placeholders below — replace payTo / feePayer with YOUR addresses.
 const DEMO_PAY_TO = 'So11111111111111111111111111111111111111112'; // replace me
@@ -55,22 +55,29 @@ app.get('/api/paid/hello', (req, res) => {
   const hasPayment = Boolean(req.get('X-PAYMENT'));
 
   if (!hasPayment) {
-    // No payment yet → answer with the x402 v2 challenge. We offer TWO Solana
-    // tokens — USDC and THREE — so the modal shows a token picker and the buyer
-    // chooses which to pay in. `solanaAccept` builds each spec-shaped entry.
+    // No payment yet → answer with the x402 v2 challenge. USDC is the default
+    // settlement asset. `solanaAccept` builds the spec-shaped accept entry.
     const common = { payTo: DEMO_PAY_TO, feePayer: DEMO_FEE_PAYER, maxTimeoutSeconds: 60 };
+    const accepts = [
+      solanaAccept({ token: 'usdc', uiAmount: 0.01, ...common }), // $0.01 in USDC
+    ];
+    // OPTIONAL: offer a second SPL token so the modal shows a token picker and
+    // the buyer chooses which to pay in. Set ACCEPT_SECOND_TOKEN=three (or pass
+    // any explicit mint to solanaAccept) to enable it. USDC stays the default.
+    if (process.env.ACCEPT_SECOND_TOKEN) {
+      accepts.push(
+        solanaAccept({ token: process.env.ACCEPT_SECOND_TOKEN, uiAmount: 1000, ...common }),
+      );
+    }
     return res.status(402).json({
       x402Version: 2,
       error: 'Payment required',
       resource: {
         url: `${req.protocol}://${req.get('host')}/api/paid/hello`,
-        description: 'A friendly hello — pay in USDC or THREE.',
+        description: 'A friendly hello — pay per call in USDC.',
         mimeType: 'application/json',
       },
-      accepts: [
-        solanaAccept({ token: 'usdc', uiAmount: 0.01, ...common }),  // $0.01 in USDC
-        solanaAccept({ token: 'three', uiAmount: 1000, ...common }), // or 1,000 THREE
-      ],
+      accepts,
     });
   }
 

package/examples/solana-crypto-paywall/README.md

@@ -0,0 +1,81 @@
+# Solana crypto paywall — `@three-ws/x402-payment-modal` demo
+
+A complete, runnable demo that paywalls a **free crypto-price API** (CoinGecko)
+behind an **x402 USDC payment on Solana**, served to the payment modal we ship on
+npm. It exists to prove the published modal works end to end on a plain page:
+
+```
+click ─▶ 402 challenge ─▶ Phantom connect ─▶ sign SPL transfer
+      ─▶ PayAI /verify ─▶ fetch CoinGecko ─▶ PayAI /settle ─▶ prices + receipt
+```
+
+Three things make it a real test, not a mock:
+
+1. **The modal loads from npm.** `public/index.html` pulls
+   `https://unpkg.com/@three-ws/x402-payment-modal@1.2.0` — the exact artifact we
+   publish — so you're testing the shipped code, not local source.
+2. **The data is gated for real.** `/api/paid/crypto` returns live CoinGecko
+   prices **only** after the payment verifies *and* settles on-chain via the
+   [PayAI](https://facilitator.payai.network) facilitator. No payment, no data.
+3. **The payout wallet is set at runtime.** There is no `.env` and no source
+   constant for it — you start the server, paste a Solana address into the page,
+   and that address becomes the `payTo` in the 402 challenge.
+
+## Run it (inside this package's repo)
+
+The server reuses the repo's `express` + `@solana/*` and imports the package's
+checkout helpers from source, so no install is needed:
+
+```bash
+node examples/solana-crypto-paywall/server.mjs
+# ▸ open http://localhost:4021
+```
+
+Then in the page:
+
+1. **Set your payout wallet** — paste a base58 Solana address, click *Save*.
+2. **Pick coins** — BTC / ETH / SOL / … (live from CoinGecko).
+3. **Pay & unlock** — approve $0.01 USDC in Phantom. Prices + an on-chain
+   receipt (with a Solscan link) appear when settlement lands.
+
+> Paying is a **real Solana mainnet micropayment** — you need Phantom with a
+> little USDC. The fee payer is covered by the facilitator, so you don't need SOL.
+
+## Run it standalone (outside the repo)
+
+```bash
+npm install
+# in server.mjs, change the two relative imports to the package subpaths:
+#   '../../server/express.js'  →  '@three-ws/x402-payment-modal/server/express'
+#   '../../server/checkout.js' →  '@three-ws/x402-payment-modal/server'
+npm start
+```
+
+## What's runtime vs. fixed
+
+| Thing | Where it comes from |
+| --- | --- |
+| **Payout wallet (`payTo`)** | **Set at runtime from the page** — `POST /api/config`, in memory. No env. |
+| Fee-payer sponsor | Public PayAI account `2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4` (pays SOL fees; not a secret, not the payout). Override with `X402_FEE_PAYER_SOLANA` only if you change facilitators. |
+| Facilitator | `https://facilitator.payai.network` (no API key). Override with `X402_FACILITATOR_URL`. |
+| Solana RPC | Public mainnet RPC. Override with `SOLANA_RPC_URL` for anything beyond a quick try. |
+| Price | Fixed at `$0.01` USDC. |
+| Port | `4021`, or `PORT`. |
+
+## Endpoints
+
+| Method & path | Purpose |
+| --- | --- |
+| `GET /api/config` | Current payout wallet, fee payer, price, coin catalog. |
+| `POST /api/config` `{ payTo }` | Set the payout wallet at runtime (validated Solana address). |
+| `POST /api/paid/crypto` `{ ids }` | The paid resource. 402 until paid; verifies + settles, then returns live prices. |
+| `ALL /api/x402-checkout` | The package's Solana `prepare`/`encode` router the modal calls. |
+
+## Files
+
+- `server.mjs` — Express app: runtime config, the 402 → verify → fetch → settle
+  paid endpoint, and the package's checkout router.
+- `facilitator.mjs` — minimal x402 `/verify` + `/settle` facilitator client (the
+  merchant half of the protocol), implementing the standard x402 v2 wire format.
+- `public/index.html` — the demo page: runtime payout panel, coin picker, and
+  designed loading / empty / error / populated states with an on-chain receipt.

package/examples/solana-crypto-paywall/facilitator.mjs

@@ -0,0 +1,170 @@
+// Minimal x402 facilitator client — Solana `exact` scheme, USDC on mainnet.
+//
+// The browser modal signs the SPL transfer (Phantom) and posts it back as a
+// base64 `X-PAYMENT` header. The merchant (this server) is responsible for the
+// other half of the protocol: ask a facilitator to (1) /verify the signed
+// payment matches what we offered, then (2) /settle it on-chain. PayAI's public
+// facilitator co-signs as the fee payer and broadcasts — so the merchant never
+// holds a private key and pays no gas.
+//
+// This is the standard x402 v2 verify/settle wire format, trimmed to exactly
+// what the Solana exact path needs so the example stays self-contained and easy
+// to read:
+//
+//   POST {facilitator}/verify  { x402Version, paymentPayload, paymentRequirements }
+//     → { isValid: boolean, invalidReason?, payer? }
+//   POST {facilitator}/settle  { x402Version, paymentPayload, paymentRequirements }
+//     → { success: boolean, transaction?, network?, payer?, errorReason? }
+//
+// No API key required for PayAI's public Solana lane. Override the URL with
+// X402_FACILITATOR_URL if you run your own.
+
+import { createHash } from 'node:crypto';
+
+export const X402_VERSION = 2;
+
+// PayAI supports Solana + Base mainnet with no auth token. The reference
+// x402.org facilitator only settles base-sepolia, so it can't stand in here.
+const FACILITATOR_URL = (process.env.X402_FACILITATOR_URL || 'https://facilitator.payai.network').replace(/\/+$/, '');
+const FACILITATOR_TOKEN = process.env.X402_FACILITATOR_TOKEN || null;
+const TIMEOUT_MS = 20_000;
+
+/** Decode the base64-JSON `X-PAYMENT` header into a v2 PaymentPayload. */
+export function decodePaymentHeader(header) {
+	if (!header) {
+		throw httpError(402, 'payment_required', 'X-PAYMENT header required');
+	}
+	let json;
+	try {
+		json = Buffer.from(String(header), 'base64').toString('utf8');
+	} catch (err) {
+		throw httpError(400, 'invalid_payment', `X-PAYMENT base64 decode failed: ${err.message}`);
+	}
+	let payload;
+	try {
+		payload = JSON.parse(json);
+	} catch (err) {
+		throw httpError(400, 'invalid_payment', `X-PAYMENT JSON parse failed: ${err.message}`);
+	}
+	if (!payload || typeof payload !== 'object') {
+		throw httpError(400, 'invalid_payment', 'X-PAYMENT must decode to a JSON object');
+	}
+	return payload;
+}
+
+/**
+ * Verify a decoded payment against the requirement we advertised.
+ * Resolves to `{ payer }` when valid; throws a 402 when the facilitator
+ * rejects it (so the modal can re-prompt the buyer to pay).
+ */
+export async function verifyPayment({ paymentPayload, requirement }) {
+	const result = await callFacilitator('/verify', {
+		x402Version: X402_VERSION,
+		paymentPayload,
+		paymentRequirements: requirement,
+	});
+	if (!result.isValid) {
+		throw httpError(402, 'invalid_payment', `payment rejected: ${result.invalidReason || 'unknown reason'}`);
+	}
+	// Defense-in-depth: a buggy/compromised facilitator must not be able to
+	// verify a payment for a different chain than the one we offered.
+	if (result.network && result.network !== requirement.network) {
+		throw httpError(502, 'facilitator_bad_response', `verify network mismatch: offered ${requirement.network}, got ${result.network}`);
+	}
+	return { payer: result.payer || null };
+}
+
+/**
+ * Settle the verified payment on-chain via the facilitator. Carries a
+ * deterministic Idempotency-Key so a retried settle (timeout / 5xx) is
+ * de-duplicated by the facilitator instead of charging the buyer twice.
+ */
+export async function settlePayment({ paymentPayload, requirement }) {
+	const idempotencyKey = buildIdempotencyKey({ paymentPayload, requirement });
+	const result = await callFacilitator(
+		'/settle',
+		{ x402Version: X402_VERSION, paymentPayload, paymentRequirements: requirement },
+		{ idempotencyKey },
+	);
+	if (!result.success) {
+		throw httpError(502, 'settle_failed', `settlement failed: ${result.errorReason || 'unknown reason'}`);
+	}
+	return {
+		transaction: result.transaction || null,
+		network: result.network || requirement.network,
+		payer: result.payer || null,
+	};
+}
+
+/** Base64-JSON settlement receipt for the `X-PAYMENT-RESPONSE` header. */
+export function encodePaymentResponse(settled) {
+	return Buffer.from(
+		JSON.stringify({
+			success: true,
+			transaction: settled.transaction,
+			network: settled.network,
+			payer: settled.payer,
+		}),
+		'utf8',
+	).toString('base64');
+}
+
+// ── internals ───────────────────────────────────────────────────────────────
+
+function buildIdempotencyKey({ paymentPayload, requirement }) {
+	const material = JSON.stringify({
+		network: requirement?.network,
+		payTo: requirement?.payTo,
+		asset: requirement?.asset,
+		amount: requirement?.amount,
+		scheme: requirement?.scheme,
+		payload: paymentPayload,
+	});
+	return createHash('sha256').update(material).digest('hex').slice(0, 32);
+}
+
+async function callFacilitator(path, body, { idempotencyKey } = {}) {
+	const headers = { 'content-type': 'application/json', accept: 'application/json' };
+	if (FACILITATOR_TOKEN) headers.Authorization = `Bearer ${FACILITATOR_TOKEN}`;
+	if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
+
+	let res;
+	try {
+		res = await fetch(`${FACILITATOR_URL}${path}`, {
+			method: 'POST',
+			headers,
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(TIMEOUT_MS),
+		});
+	} catch (err) {
+		throw httpError(502, 'facilitator_unreachable', `facilitator ${path} fetch failed: ${err.message}`);
+	}
+
+	const text = await res.text();
+	let data = {};
+	if (text) {
+		try {
+			data = JSON.parse(text);
+		} catch {
+			throw httpError(502, 'facilitator_bad_response', `facilitator ${path} returned non-JSON (status ${res.status})`);
+		}
+	}
+
+	if (!res.ok) {
+		// A rejected payment payload is a client problem, not an outage — normalize
+		// it so verifyPayment can re-issue a clean 402 instead of a 5xx.
+		if (path === '/verify' && (data.isValid === false || res.status === 400)) {
+			return { isValid: false, invalidReason: data.invalidReason || data.error || `payment rejected (status ${res.status})` };
+		}
+		const detail = data.error || data.errorReason || data.message || text.slice(0, 200) || `status ${res.status}`;
+		throw httpError(502, 'facilitator_error', `facilitator ${path} ${res.status}: ${detail}`);
+	}
+	return data;
+}
+
+function httpError(status, code, message) {
+	const err = new Error(message);
+	err.status = status;
+	err.code = code;
+	return err;
+}

package/examples/solana-crypto-paywall/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "x402-solana-crypto-paywall",
+  "private": true,
+  "version": "1.0.0",
+  "description": "Demo: a free crypto-price API paywalled with x402 on Solana, served to the @three-ws/x402-payment-modal. Payout wallet is set at runtime, not from env.",
+  "type": "module",
+  "scripts": {
+    "start": "node server.mjs",
+    "dev": "node server.mjs"
+  },
+  "dependencies": {
+    "@three-ws/x402-payment-modal": "*",
+    "@solana/web3.js": "^1.95.0",
+    "@solana/spl-token": "^0.4.0",
+    "express": "^4.19.0"
+  }
+}