@maytes/checkout-button 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+
+## 1.0.0
+
+### Major Changes
+
+- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - First public release on npm.
+
+  The button is now installable as `@maytes/checkout-button` alongside the existing
+  CDN `<script>` distribution — same package, same API, both fed from this source.
+
+  Framework apps (React, Angular, Vue, Svelte, plain bundled JS) should import the
+  factory directly:
+
+  ```ts
+  import { Maytes } from "@maytes/checkout-button";
+  ```
+
+  That removes the script-injection dance those apps previously needed: no
+  `window.Maytes` global to feature-detect, no polling for the CDN script to
+  finish loading before mounting, and no hand-written `declare global` typings —
+  the package ships its own `.d.ts`.
+
+  The `<script>` tag remains the right integration for no-build sites and jQuery,
+  and is unchanged: pin a SemVer or content-hash URL with SRI in every environment,
+  development included.
+
+### Minor Changes
+
+- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Brand the checkout button with the Maytes wordmark logo and maroon brand color, and make its size auto-scale from a single `--maytes-button-font-size` custom property (default 14px).
+
+- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Add a launch `mode` to `renderButton` and a branded popup loading screen.
+
+  - `renderButton(container, { mode })` accepts `'redirect'` (new default) or `'popup'`. Invalid values throw `MaytesError(CONFIG)`.
+  - `mode: 'popup'` opens a blank popup synchronously on click (preserving the user gesture so browsers do not block it), paints a branded Maytes loading screen into it (logo, spinner, `role="status"`/`aria-live`, a slow-network message that appears after ~8s, and a `prefers-reduced-motion` guard), then `popup.location.replace(url)`s once `createCheckout` resolves.
+  - On mobile viewports `mode: 'popup'` behaves as a same-window redirect.
+  - The misleading `maytes:checkout-failed` (`reason: 'popup-blocked'`) is replaced by a new `maytes:checkout-redirected` event (`detail.url`). A same-window redirect is a normal outcome, not a failure. The `failed` event now only carries `'create-checkout-rejected'` | `'invalid-shape'`.
+  - A popup opened before `createCheckout` resolves is now closed if the call rejects, returns an invalid shape, or the instance is destroyed mid-flight. `destroy()` also closes any open popup.
+  - Exported `POPUP_LOADING_CSS` for the loader stylesheet.
+
+### Patch Changes
+
+- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Harden the checkout button popup lifecycle:
+
+  - Open the hosted checkout URL exactly once (it was navigated twice — `window.open(url)` plus a redundant `location.href` write).
+  - Give each SDK instance a unique popup window name so concurrent merchant tabs no longer share or steal one popup; this also removes the cross-origin `SecurityError` that could hang the overlay.
+  - `destroy()` now detaches every button's click listener and is ignored by an in-flight `createCheckout` that resolves after teardown (no late popup).
+  - Remove the cloned overlay `<style>` from the top document on teardown (same-origin iframe embeds).
+  - Scope the injected style marker and ref-count by SDK version so two SDK versions on one page don't clash.
+  - Clear the overlay immediately when the shopper presses Escape (was delayed up to one poll interval).
+  - Validate that a merchant-supplied `checkoutUrl` is an `http(s)` URL before opening it — matching the protocol guard already applied to the constructed URL, so a buggy backend can't turn the button into a `javascript:`/`data:` popup.
+
+- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Take the Maytes brand colours from the design foundation (`kttipay/designsystem` v0.3.0, vendored by `npm run sync:foundation` and pinned in `foundation.lock.json`) instead of hand-written hexes. The only rendered change: the button's hover shade is now the foundation's burgundy/700 `#3B021D` (was `#3A021C`).
+
+- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Serve the CDN (IIFE) bundle minified, with a sourcemap. The ESM/CJS npm bundles stay unminified so the consumer's bundler can tree-shake them.
+
+- [`c17857f`](https://github.com/kttipay/checkout-button/commit/c17857fcb38bf045ae89fde207a1859ae12214e3) Thanks [@Merkost](https://github.com/Merkost)! - Fix a race in `mode: 'popup'`: if the shopper closed the popup while `createCheckout` was still in flight, the SDK would try to navigate (or, on rejection, report a failure for) a window that was already gone once the promise settled — on top of the `maytes:checkout-closed` event the close-poll had already fired. Both the success and rejection paths now check whether the popup is still open before acting, so closing the popup early produces exactly one `checkout-closed` event and nothing else.
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!-- @hash-sri-start -->
+
+**SRI hashes** (use these in `<script integrity="..." crossorigin="anonymous">`):
+
+```
+checkout-button.js   sha384-dZQS1KceW5Q/UDS8qafQmJFIvORLSL/aNtpkbU94yqZCLB+ifJfxkgNLjHpFADkt
+checkout-button.mjs  sha384-jQbytMpQ6WWb5T8Xd0+f8+B6QclSeIgF7AaYiVCe6UdXK6nYUoC/x+VM3YWTWxH1
+checkout-button.cjs  sha384-XpEcs+bC2pKL1C8nhXv0sPSGWeWHGKrOnOJ/FGhseY0uIY6al831WIS+be4BQTIY
+```
+
+**SemVer CDN links** (readable production pins; use with the SRI hashes above):
+
+- [checkout-button.js](https://js.maytes.co/v1.0.0/checkout-button.js)
+- [checkout-button.mjs](https://js.maytes.co/v1.0.0/checkout-button.mjs)
+- [checkout-button.cjs](https://js.maytes.co/v1.0.0/checkout-button.cjs)
+
+**Hashed CDN links** (byte-level production pins; use with the SRI hashes above):
+
+- [checkout-button.3cf081dc.js](https://js.maytes.co/checkout-button.3cf081dc.js)
+- [checkout-button.5403f24b.mjs](https://js.maytes.co/checkout-button.5403f24b.mjs)
+- [checkout-button.2a6f6a35.cjs](https://js.maytes.co/checkout-button.2a6f6a35.cjs)
+
+<!-- @hash-sri-end -->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maytes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -0,0 +1,106 @@
+# @maytes/checkout-button
+
+Drop-in **Split with Maytes** button. Renders a button and launches the Maytes-hosted checkout. Default mode is same-window redirect; `mode: 'popup'` opts desktop browsers into a centered popup with a branded loader and redirect fallback on mobile or when blocked.
+
+## Install
+
+### Script tag (CDN)
+
+For production, pin an exact release. The readable SemVer URL and the content-hash URL are two names for the **same release bytes** and share the **same SRI value** — pick either:
+
+```html
+<script src="https://js.maytes.co/v1.0.0/checkout-button.js"
+        integrity="sha384-…"
+        crossorigin="anonymous"></script>
+```
+
+```html
+<script src="https://js.maytes.co/checkout-button.795d508b.js"
+        integrity="sha384-…"
+        crossorigin="anonymous"></script>
+```
+
+`v1.0.0` / `795d508b` are examples. The real version, hash, and SRI for each release live in [`CHANGELOG.md`](./CHANGELOG.md), the matching [release](https://github.com/kttipay/checkout-button/releases), and `https://js.maytes.co/integrity.json`.
+
+Use a pinned URL in every environment, development included — pinning is what makes the bytes you tested the bytes your shoppers get.
+
+### npm
+
+```bash
+npm install @maytes/checkout-button
+```
+
+## Usage
+
+`Maytes` is a callable factory (Stripe-style). Each call returns an isolated SDK instance.
+
+```ts
+import { Maytes } from '@maytes/checkout-button';
+
+const maytes = Maytes({
+  createCheckout: async () => {
+    const res = await fetch('/api/maytes/create-checkout', { method: 'POST' });
+    return res.json(); // { checkoutId: string, checkoutUrl?: string }
+  },
+  environment: 'sandbox',
+});
+
+const cleanup = maytes.renderButton(document.getElementById('slot'), { block: true });
+
+// Optional popup mode:
+maytes.renderButton(document.getElementById('popup-slot'), { block: true, mode: 'popup' });
+
+// Imperative alternatives:
+maytes.redirectToCheckout({ checkoutId });
+const url = maytes.checkoutUrl({ checkoutId });
+
+// Teardown:
+cleanup();
+maytes.destroy();
+```
+
+Via the script tag, the same factory is available as the global `window.Maytes(...)`.
+
+## API
+
+| Method | Purpose |
+|---|---|
+| `Maytes(options)` | Create an SDK instance. `options.createCheckout` mints a checkout server-side; `options.environment` selects the Maytes environment. |
+| `renderButton(container, options?)` | Render the button into `container`; returns a cleanup function. Options include `label`, `block`, and `mode: 'redirect' \| 'popup'`. |
+| `redirectToCheckout(options)` | Launch checkout directly (no button). |
+| `checkoutUrl(options)` | Build the hosted checkout URL. |
+| `destroy()` | Tear down the instance and its listeners. |
+
+## Mobile app
+
+After checkout, shoppers split the cost with friends using Maytes payment links (`app.maytes.co/…`). On a phone with the Maytes app installed, those links open directly in the app (iOS Universal Links / Android App Links); otherwise they open in the browser. Maytes handles this end to end — merchants integrate only the button and configure nothing for the app.
+
+## Development
+
+```bash
+npm ci
+npm run dev          # tsup watch
+npm run typecheck
+npm run test:run
+npm run build        # bundles + SRI hashes + CSP scan
+```
+
+Versioning and changelog are managed with [Changesets](./.changeset/README.md). Run `npm run changeset` with your PR.
+
+## Brand colours come from the design foundation
+
+The Maytes brand colours the button paints (`brand.primary` burgundy, `brand.secondary` orange, the burgundy/700 hover shade, and the inverse text white) are **not hand-written** in this package. They are vendored from the design foundation — `kttipay/designsystem` `web/tokens.ts` — into `src/foundation/brand.generated.ts`, pinned to a release tag recorded in `foundation.lock.json`:
+
+```json
+{ "repo": "kttipay/designsystem", "tag": "v0.3.0", "source": "web/tokens.ts" }
+```
+
+- `src/branding.ts`, `src/styles.ts` and `src/button.ts` read every brand colour from that generated module. Never type a Maytes hex into `src/`.
+- To move to a newer foundation release: `npm run sync:foundation -- --tag vX.Y.Z` (fetches the file at that tag with `gh api`, so you need a logged-in `gh`; `--from ../path/to/designsystem/web/tokens.ts` works offline). The script rewrites the generated module and the lock file. Commit both together.
+- A vitest test fails if the generated header's tag drifts from `foundation.lock.json`, so the file can only change through the script.
+
+The design-system repo does not publish an npm package yet. When it does (`@kttipay/foundation` on GitHub Packages), the upgrade path is to replace the vendored module with that dependency and delete the script and lock file.
+
+## License
+
+MIT