@three-ws/x402-modal 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `@three-ws/x402-modal` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-06-30
+
+### Added
+- Comprehensive documentation: README (CDN + npm install, sub-60s quickstart,
+  discover→connect→sign→settle sequence diagram, full API reference, configuration
+  and `data-*` attribute reference, Vanilla/React/CDN framework guides, theming
+  hooks, security, FAQ), plus `docs/EXAMPLES.md` (9 runnable recipes), updated
+  `docs/CONFIGURATION.md` / `docs/BACKEND.md`, and `CONTRIBUTING.md`.
+
+### Changed
+- Published as `@three-ws/x402-modal`. Defaults are now vendor-neutral: the `brand`
+  footer link and `builderCode` attribution default to `null` (off) until a host
+  opts in. The modal settles a 402 from any origin with zero configuration; USDC
+  is the default settlement asset.
+- The build banner is derived from package metadata (no hardcoded host/branding).
+
+[0.2.0]: https://github.com/nirholas/x402-modal/releases/tag/v0.2.0

package/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to @three-ws/x402-modal
+
+Thanks for helping improve the x402 payment modal. This guide covers the local
+setup, the build, the tests, and the conventions the project follows.
+
+## Prerequisites
+
+- **Node.js >= 18** (the package declares this in `engines`).
+- npm (ships with Node).
+
+No global tooling is required — `esbuild` is the only dev dependency.
+
+## Setup
+
+```sh
+git clone https://github.com/nirholas/x402-modal.git
+cd x402-modal
+npm install
+```
+
+## Project layout
+
+| Path                   | What it is |
+|------------------------|------------|
+| `src/x402-modal.js`    | The canonical, side-effect-free core. The public API lives here. |
+| `src/global.js`        | The CDN entry: reads `data-x402-*` off its `<script>`, auto-binds, exposes `window.X402`. |
+| `src/util.js`          | Pure, DOM-free helpers (encoding, network maps, SIWX message, caps math). Unit-tested in Node. |
+| `types/index.d.ts`     | TypeScript declarations for the public API. |
+| `build.mjs`            | esbuild config — emits `dist/x402-modal.mjs` (ESM) and `dist/x402.global.js` (IIFE). |
+| `test/*.test.js`       | Node `node:test` suites. No DOM required. |
+| `examples/`            | A runnable demo page and a reference Solana backend helper. |
+| `docs/`                | Protocol, configuration, backend, and examples references. |
+
+## Build
+
+```sh
+npm run build
+```
+
+This produces two artifacts in `dist/`:
+
+- `dist/x402-modal.mjs` — ESM, side-effect-free, for bundlers and npm consumers.
+- `dist/x402.global.js` — minified IIFE, the drop-in CDN `<script>`.
+
+The build banner is derived from `package.json`, so no host or branding is
+hardcoded in `build.mjs`. The Solana web3.js and keccak imports stay as runtime
+CDN URLs and are never bundled.
+
+## Test
+
+```sh
+npm test
+```
+
+Runs every `test/*.test.js` with Node's built-in test runner. All tests must
+pass before a change is merged. Tests run in plain Node — keep new logic that
+needs coverage in `src/util.js` (DOM-free) so it stays unit-testable.
+
+## Conventions
+
+- **No new runtime dependencies.** The package is deliberately dependency-free;
+  the only network modules (Solana web3.js, a keccak) are dynamic-imported from a
+  CDN, on demand. Adding an npm runtime dependency needs a strong reason.
+- **Keep the core side-effect-free.** `src/x402-modal.js` must never touch
+  `window` or auto-bind on import — that behavior belongs in `src/global.js`.
+- **Defaults stay vendor-neutral.** `brand` and `builderCode` default to `null`.
+  Don't ship a default footer or builder code.
+- **Update types and docs with the code.** A public-API change updates
+  `types/index.d.ts`, the README API reference, and the relevant `docs/` file in
+  the same change. Every doc sample must actually run.
+- **Match the existing style.** Tab indentation, small functions, comments that
+  explain *why*, not *what*.
+
+## Submitting a change
+
+1. Branch from `main`.
+2. Make the change; run `npm run build && npm test`.
+3. Update `types/`, the README, and `docs/` for any public-API change.
+4. Open a PR describing the change and the user-visible effect.
+
+## Reporting issues
+
+Open an issue at <https://github.com/nirholas/x402-modal/issues>. For a payment
+flow bug, include the network (Base / Solana), the wallet, and the shape of the
+`402` body's `accepts[]` entry (redact addresses if needed).
+
+## License
+
+By contributing you agree your contributions become the proprietary property of
+the Owner. Proprietary — Copyright (c) 2026 nirholas. All Rights Reserved.
+Unauthorized use, copying, modification, or distribution is prohibited. See
+[LICENSE](./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.