@three-ws/x402-payment-modal 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to `@three-ws/x402-payment-modal` are documented here. This
+project adheres to [Semantic Versioning](https://semver.org).
+
+## 1.1.0
+
+### Added
+
+- **Pay in USDC _or_ THREE on Solana.** When a 402 challenge offers more than one
+  Solana token, the modal renders a token picker so the buyer chooses which to
+  pay in; the headline price and the built transaction follow the choice. USDC
+  and [$THREE](https://three.ws/three-token) (`FeMb…pump`) are recognized by mint
+  — correct symbol, decimals, and branding even when the `accept` omits
+  `extra.name`/`extra.decimals`.
+- **`solanaAccept()` server helper** — build a spec-shaped Solana `accept` from
+  `token: 'usdc' | 'three'` (or an explicit `mint`) with the price as `uiAmount`
+  (human) or `amount` (atomic). Exports `THREE_MINT`, `USDC_MINT_SOLANA`, and
+  `WELL_KNOWN_SOLANA_TOKENS`.
+- **`window.X402.tokens`** + client exports `THREE_MINT`, `USDC_MINT_SOLANA`,
+  `KNOWN_SOLANA_TOKENS` for inline merchants composing challenges in the browser.
+
+### Notes
+
+- THREE is a utility token, not a stablecoin: the browser can't dollar-denominate
+  it, so client-side spending caps apply to USDC only — enforce THREE caps
+  server-side. Settlement is unchanged — the checkout endpoint already transfers
+  any SPL mint named by the chosen `accept`.
+
+## 1.0.0
+
+Initial public release. Extracted from the three.ws platform as a standalone,
+dependency-free package.
+
+### Added
+
+- **Drop-in payment modal** for any x402 paid endpoint — declarative
+  (`data-x402-endpoint` auto-binding) and programmatic (`pay()` / `window.X402`).
+- **Solana payments** via Phantom (USDC), backed by the bundled checkout server
+  helpers (`prepare` / `encode`).
+- **EVM payments** via any injected wallet (Base USDC, EIP-3009
+  `transferWithAuthorization`) — signed entirely in the browser, no server call.
+- **SIWX (Sign-In-With-X / CAIP-122) re-entry** — wallets that already paid can
+  sign in instead of paying again, with automatic fallback to the pay flow.
+- **Client-side spending caps** — per-call / hourly / daily limits enforced in
+  `localStorage`, with rollback on failure.
+- **`configure()` + script-tag `data-*` config** for checkout origin, branding,
+  builder-code attribution, and esm.sh CDN URLs.
+- **Framework-agnostic server module** with Express and Vercel adapters
+  (`@three-ws/x402-payment-modal/server`).
+- **Theming** — light + automatic dark mode, all classes overridable, `--x402-z`
+  z-index custom property.
+- **Automatic 429 throttle retry** — re-sends the same signed payment up to twice
+  while an upstream rate limit resets (no double charge; payment isn't settled
+  until the merchant call succeeds).
+- TypeScript definitions, full docs (`docs/`), tutorial, and runnable examples
+  (plain HTML, React, Express).

package/LICENSE

@@ -0,0 +1,180 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Derivative Works, and to permit persons to whom the Derivative Works
+      are furnished to do so.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      conditions consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 nirholas
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,347 @@
+# @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.
+
+```html
+<script type="module" src="https://unpkg.com/@three-ws/x402-payment-modal"></script>
+
+<button
+  data-x402-endpoint="https://api.example.com/paid/summarize"
+  data-x402-method="POST"
+  data-x402-body='{"text":"hello"}'
+  data-x402-merchant="Acme"
+  data-x402-action="Summarize">
+  Pay &amp; Run
+</button>
+```
+
+That's the whole integration. Clicking the button opens the modal, runs the
+payment, calls your endpoint with the signed `X-PAYMENT` header, and fires an
+`x402:result` event with the response.
+
+---
+
+## Why
+
+x402 lets any HTTP endpoint charge a micropayment per call: the server answers an
+unpaid request with `402` and a list of accepted payments; the client pays and
+retries with an `X-PAYMENT` header. The protocol is simple — the *wallet UX* is
+not. This package is the missing front end: a single, framework-agnostic modal
+that handles wallet detection, chain switching, signing, settlement, errors,
+throttle retries, and the receipt, so you ship a paid endpoint in minutes.
+
+- **Zero dependencies, zero build.** Plain ES module. Drop in a `<script>` tag or
+  `import` it. The Solana/EVM crypto helpers are loaded lazily from a CDN *only*
+  when a payment is actually attempted.
+- **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).
+- **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
+  [docs/theming.md](docs/theming.md).
+- **Accessible.** Focus management, `aria-modal`, keyboard `Esc` to close.
+
+---
+
+## Install
+
+**Via CDN (no build step):**
+
+```html
+<script type="module" src="https://unpkg.com/@three-ws/x402-payment-modal"></script>
+```
+
+**Via npm (bundler / framework):**
+
+```bash
+npm install @three-ws/x402-payment-modal
+```
+
+```js
+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:
+
+```bash
+npm install @solana/web3.js @solana/spl-token
+```
+
+> EVM-only sites need **nothing** server-side: the wallet signs EIP-3009
+> typed-data entirely in the browser.
+
+---
+
+## Quick start
+
+### 1. Declarative (HTML attributes)
+
+Any element with `data-x402-endpoint` is auto-bound on load and re-scanned as the
+DOM changes:
+
+```html
+<button
+  data-x402-endpoint="/api/paid/translate"
+  data-x402-method="POST"
+  data-x402-body='{"text":"bonjour","to":"en"}'
+  data-x402-merchant="Acme Translate"
+  data-x402-action="Translate">
+  Translate ($0.01)
+</button>
+
+<script type="module" src="https://unpkg.com/@three-ws/x402-payment-modal"></script>
+
+<script>
+  document.querySelector('button').addEventListener('x402:result', (e) => {
+    console.log('paid + result:', e.detail.result);
+  });
+</script>
+```
+
+### 2. Programmatic
+
+```js
+import { pay } from '@three-ws/x402-payment-modal';
+
+try {
+  const { result, payment } = await pay({
+    endpoint: '/api/paid/translate',
+    method: 'POST',
+    body: { text: 'bonjour', to: 'en' },
+    merchant: 'Acme Translate',
+    action: 'Translate',
+  });
+  console.log(result, 'tx:', payment?.transaction);
+} catch (err) {
+  if (err.code !== 'cancelled') console.error(err);
+}
+```
+
+See the runnable [examples/](examples/) — plain HTML, React, and an Express
+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
+```
+
+Full walkthrough in [docs/architecture.md](docs/architecture.md).
+
+---
+
+## Client API
+
+| Export | Signature | Purpose |
+| --- | --- | --- |
+| `pay` | `pay(opts) => Promise<PayResult>` | Open the modal and run a payment. |
+| `configure` | `configure(opts) => Config` | Set checkout origin, branding, builder-code, CDN URLs. |
+| `init` | `init() => void` | Bind `[data-x402-endpoint]` elements (auto-called). |
+| `version` | `string` | Library version. |
+
+Also exposed as `window.X402.{ pay, init, configure, version }` for inline
+scripts.
+
+**`pay(opts)`** — `opts`:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `endpoint` | `string` | **Required.** The paid (x402) URL. |
+| `method` | `string` | Default `GET`, or `POST` when `body` is set. |
+| `body` | `object \| string` | Objects are JSON-stringified. |
+| `headers` | `object` | Extra headers merged into the paid call. |
+| `merchant` | `string` | Shown in the modal header. |
+| `action` | `string` | Shown in the modal header. |
+| `autoConnect` | `boolean` | Skip the picker when exactly one wallet is detected. |
+| `caps` | `SpendingCaps` | `{ maxPerCall, maxPerHour, maxPerDay }` in atomic micro-USD. |
+
+Resolves to `PayResult`: `{ ok: true, result, payment?: { network, transaction,
+payer }, siwx?: { address, network }, response: { status, headers } }`. Rejects
+with an `Error` whose `.code === 'cancelled'` when the user closes the modal.
+
+**DOM events** (bubbling `CustomEvent`s on the clicked element):
+`x402:result` (`detail` = `PayResult`), `x402:error` (`detail` = `{ error }`),
+`x402:siwx-signed` (`detail` = `{ address, network }`).
+
+Full reference: [docs/api-reference.md](docs/api-reference.md).
+
+---
+
+## Configuration
+
+Defaults work out of the box. Override host-specific bits with `configure()`:
+
+```js
+import { configure } from '@three-ws/x402-payment-modal';
+
+configure({
+  checkoutOrigin: 'https://pay.acme.com', // where your Solana checkout endpoint lives
+  brand: { name: 'Acme', url: 'https://acme.com' },
+  footerNote: 'Acme Pay',
+});
+```
+
+…or with `data-*` attributes on the script tag (no inline module needed):
+
+```html
+<script type="module"
+  src="https://unpkg.com/@three-ws/x402-payment-modal"
+  data-x402-checkout-origin="https://pay.acme.com"
+  data-x402-brand-name="Acme"
+  data-x402-brand-url="https://acme.com"></script>
+```
+
+| Option | `data-*` attribute | Default |
+| --- | --- | --- |
+| `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 |
+| `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.)
+
+---
+
+## Server (Solana only)
+
+Phantom signs serialized transactions but doesn't build instructions, so the
+Solana path needs a tiny endpoint to build the SPL transfer and wrap the signed
+tx into the `X-PAYMENT` envelope. The package ships it.
+
+**Express:**
+
+```js
+import express from 'express';
+import { x402CheckoutRouter } from '@three-ws/x402-payment-modal/server/express';
+
+const app = express();
+app.use(express.json());
+app.use('/api/x402-checkout', x402CheckoutRouter({ rpcUrl: process.env.SOLANA_RPC_URL }));
+app.listen(3000);
+```
+
+**Vercel / Next.js** — `api/x402-checkout.js`:
+
+```js
+export { default } from '@three-ws/x402-payment-modal/server/vercel';
+```
+
+Lower-level helpers (`prepareSolanaCheckout`, `encodeX402Payment`,
+`handleCheckout`, `CheckoutError`) 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)
+
+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.
+
+Build the accepts with the `solanaAccept` helper (no hardcoded mints):
+
+```js
+import { solanaAccept } from '@three-ws/x402-payment-modal/server';
+
+// feePayer is your facilitator's sponsor account (pays the SOL network fee).
+const accepts = [
+  solanaAccept({ token: 'usdc',  uiAmount: 0.25, payTo, feePayer }), // $0.25 in USDC
+  solanaAccept({ token: 'three', uiAmount: 1000, payTo, feePayer }), // or 1,000 THREE
+];
+
+// Return them in your 402 body / PAYMENT-REQUIRED envelope:
+//   { x402Version: 2, accepts }
+```
+
+`solanaAccept` takes `token: 'usdc' | 'three'` (or an explicit `mint` for any
+SPL token), the price as `uiAmount` (human units) or `amount` (atomic string),
+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.
+
+---
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — the full payment lifecycle.
+- [Client API reference](docs/api-reference.md)
+- [Server setup](docs/server-setup.md)
+- [Theming](docs/theming.md)
+- [SIWX re-entry](docs/siwx.md)
+- [Spending caps](docs/spending-caps.md)
+- [Tutorial](TUTORIAL.md) — build a paid endpoint end-to-end.
+
+---
+
+## Browser support
+
+Modern evergreen browsers (ES2020, `BigInt`, dynamic `import()`, `fetch`,
+`crypto.getRandomValues`). The Solana wallet path requires
+[Phantom](https://phantom.app); the EVM path requires an injected wallet
+(`window.ethereum`).
+
+## Security
+
+- 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.
+- 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.
+
+## License
+
+[Apache-2.0](LICENSE) © three.ws
+
+> 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>.