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

package/CHANGELOG.md

@@ -3,15 +3,77 @@
 All notable changes to `@three-ws/x402-payment-modal` are documented here. This
 project adheres to [Semantic Versioning](https://semver.org).
 
+## 1.2.0
+
+Hardening pass for scale and a UX/accessibility overhaul.
+
+### Fixed
+
+- **Token-2022 mints now settle.** `prepareSolanaCheckout`
+  hardcoded the legacy SPL Token program, so building a Token-2022 payment threw
+  `TokenInvalidAccountOwnerError`. The server now detects each mint's owning
+  program (legacy vs Token-2022) and derives ATAs, the idempotent-create, and
+  `transferChecked` against the right one.
+
+### Added — wallets
+
+- **Multi-wallet detection.** Solana now detects Phantom, Solflare, Backpack,
+  Glow, and Coinbase Wallet (was Phantom-only); EVM uses **EIP-6963** multi-
+  provider discovery (falling back to `window.ethereum[.providers]`) so a user
+  with several wallets isn't stuck with whichever won the injection race. The
+  connect screen lists every detected wallet; auto-connect only fires when
+  exactly one is present.
+
+### Added — developer experience
+
+- **First-class React export** — `import { X402Button, useX402 } from
+  '@three-ws/x402-payment-modal/react'`. `useX402()` exposes a
+  `{ pay, status, result, error, reset, isPaying }` state machine; both are
+  SSR-safe (the browser-only core is dynamically imported on first use). `react`
+  is an optional peer dependency.
+
+### Added — reliability & scale
+
+- **RPC failover** — `prepareSolanaCheckout` / `handleCheckout` accept `rpcUrls`
+  (and `devnetRpcUrls`); each is tried in order on a transient RPC error.
+  Connections are reused per URL, and unset RPC now warns (the public RPC is a
+  load footgun).
+- **Faster, cheaper prepare** — the independent RPC reads (decimals, recipient
+  ATA existence, blockhash) run in parallel; USDC/THREE/wSOL decimals + program
+  are short-circuited; recipient-ATA existence and mint metadata are cached
+  (LRU-bounded). Cluster-scoped caches survive RPC failover.
+- **Resilient crypto-helper loading** — the on-demand `@solana/web3.js` /
+  `@noble/hashes` import now falls back across multiple independent CDNs with a
+  per-attempt timeout, and is pre-warmed when the modal opens. A single CDN
+  outage no longer breaks Solana payments. Set `configure({ esm })` to self-host.
+- **Idempotency key** — one key per payment, reused across every retry and "Try
+  again", sent as `Idempotency-Key` so a re-sent payment settles at most once.
+- Unexpected checkout failures are now logged (root cause) instead of collapsing
+  silently into a generic 502; pass `options.logger` to route them.
+
+### Added — UX, UI & accessibility
+
+- **Design-token theming** — the full palette is exposed as `--x402-*` CSS custom
+  properties. `configure({ theme: 'light'|'dark'|'auto', cssVars, brand: { logo } })`
+  forces a color scheme, brand-matches tokens at runtime, and shows a header logo.
+- **Accessibility** — focus trap + focus restore, `aria-live` step announcements,
+  `:focus-visible` rings, `prefers-reduced-motion` support, and WCAG-AA contrast.
+- **Polish** — crisp inline SVG icons (close, lock, wallet, success check),
+  an animated success receipt, step cross-fade, shimmer skeletons during
+  discovery, a mobile bottom-sheet layout with safe-area insets, humanized error
+  copy (no internal step ids), an install-a-wallet hint when none is detected,
+  a "you authorize exactly X — nothing more" trust line, and prose rendering for
+  string results.
+
 ## 1.1.0
 
 ### Added
 
-- **Pay in USDC _or_ THREE on Solana.** When a 402 challenge offers more than one
+- **Multi-token Solana picker.** 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
+  is the always-on default; an optional opt-in `THREE` token is recognized by
+  mint — correct symbol and decimals 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`
@@ -22,15 +84,15 @@ project adheres to [Semantic Versioning](https://semver.org).
 
 ### 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`.
+- For any non-stable token (such as the optional `THREE`), the browser can't
+  dollar-denominate the price, so client-side spending caps apply to stablecoins
+  only — enforce caps for non-stable tokens 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.
+Initial public release as a standalone, dependency-free package.
 
 ### Added
 

package/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to @three-ws/x402-payment-modal
+
+Thanks for helping improve the drop-in x402 checkout. This guide covers the local
+setup, the layout, and the bar for a change to land.
+
+## Prerequisites
+
+- Node.js **>= 18** (the package targets `engines.node >= 18`).
+- npm (the repo uses npm; a lockfile-free `npm install` is fine).
+
+## Setup
+
+```bash
+git clone https://github.com/nirholas/x402-payment-modal.git
+cd x402-payment-modal
+npm install
+npm run build   # bundles dist/x402.js + dist/x402.min.js from src/index.js
+npm test        # node --test — should report 14 pass / 2 skip
+```
+
+The two skipped tests (`prepareSolanaCheckout builds a tx …`) hit a **live Solana
+RPC** and are skipped by default. To run them, point a real RPC at the test
+environment per the comments in `test/token2022.integration.test.js`.
+
+## Repository layout
+
+| Path | What it is |
+| --- | --- |
+| `src/index.js` | The browser client — the `.` and `./min` exports. Zero runtime deps. |
+| `server/checkout.js` | Framework-agnostic Solana checkout (`./server`). |
+| `server/express.js`, `server/vercel.js` | Adapters (`./server/express`, `./server/vercel`). |
+| `react/index.js` | React wrapper (`./react`): `X402Button`, `useX402`. |
+| `types/*.d.ts` | TypeScript definitions for each subpath. |
+| `build.mjs` | esbuild bundling `src` → `dist`. |
+| `test/*.test.js` | `node --test` suites for the server helpers. |
+| `docs/` | Reference docs (API, server, react, theming, caps, SIWX, architecture). |
+| `examples/` | Runnable samples (plain HTML, React, Express, Solana paywall). |
+
+## Making a change
+
+1. **Match the existing patterns.** Read the neighboring code/docs first; keep the
+   naming, file organization, and comment style consistent.
+2. **No mocks, no placeholders, no TODOs.** Use real APIs. Every code sample in a
+   doc must actually run; every link must resolve.
+3. **Keep the client dependency-free.** The `.` export must not gain a runtime
+   dependency. Crypto helpers are lazy-loaded from a CDN on demand only.
+4. **Keep peer deps optional.** `@solana/web3.js`, `@solana/spl-token`, `express`,
+   and `react` stay in `peerDependenciesMeta` as `optional: true`.
+5. **Update the types.** A public API change must update the relevant `types/*.d.ts`.
+6. **Document it.** A new option, export, or subpath updates the matching doc in
+   `docs/` (and `README.md` / `CHANGELOG.md` for anything user-visible).
+
+## Before opening a PR
+
+```bash
+npm run build && npm test
+```
+
+- `npm test` must stay **14 pass / 2 skip** (the 2 skips need a live RPC).
+- If you touched `src/`, rebuild — `dist/` is generated and shipped.
+- Review your own diff: every changed line should be justified.
+
+## Commit & PR style
+
+- Small, focused commits with a clear subject (`fix:`, `feat:`, `docs:` …).
+- Describe the *why*, not just the *what*. Link the issue if there is one.
+- For a behavior change, add or update a test.
+
+## Reporting bugs
+
+Open an issue at <https://github.com/nirholas/x402-payment-modal/issues> with:
+
+- The subpath involved (`.`, `./server`, `./react`, …).
+- A minimal reproduction (a paste of the 402 challenge JSON helps a lot).
+- Browser + wallet (for client issues) or Node version + RPC (for server issues).
+
+## License
+
+Proprietary — Copyright (c) 2026 nirholas. All Rights Reserved. Unauthorized use, copying, modification, or distribution is prohibited. See [LICENSE](./LICENSE). By contributing you assign all right, title, and interest in your contributions to the Owner, and agree they are governed by the project's proprietary license.

package/LICENSE

@@ -1,180 +1,38 @@
-                                 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.
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2026 nirholas. All Rights Reserved.
+
+This software, including all source code, documentation, configuration, build
+output, and associated files in this repository (collectively, the "Software"),
+is the proprietary and confidential property of nirholas (the "Owner"). The
+Software is protected by copyright laws and international treaty provisions. All
+right, title, and interest in and to the Software, including all copyrights,
+trademarks, trade secrets, patents, and other intellectual property rights, are
+and shall remain the sole and exclusive property of the Owner.
+
+NO LICENSE OR RIGHT IS GRANTED. No person or entity is granted any license or
+right to access, use, copy, reproduce, modify, adapt, translate, merge, publish,
+distribute, sublicense, sell, lease, rent, lend, transmit, host, display,
+perform, create derivative works from, decompile, disassemble, reverse engineer,
+or otherwise exploit the Software, in whole or in part, in any form or by any
+means, without the express prior written permission of the Owner in each
+instance.
+
+Unauthorized access, use, reproduction, modification, or distribution of the
+Software, or of any portion of it, is strictly prohibited, constitutes
+infringement of the Owner's intellectual property rights, and may result in
+severe civil and criminal penalties. Violations will be prosecuted to the
+maximum extent permitted by law.
+
+Third-party components, dependencies, and protocols referenced or required by the
+Software remain governed by their own respective licenses; this License applies
+solely to the original works authored by the Owner contained in this repository.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, TITLE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE OWNER
+BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For licensing inquiries, contact the Owner at https://github.com/nirholas.