@sweepconsole/js 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sweep Console
+
+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

@@ -1,3 +1,197 @@
-# Temporary Holding Version
+# @sweepconsole/js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A **Subscribe with USDC** button for your checkout. It asks your server for a URL and sends the payer there.
+
+~3KB gzipped, no dependencies.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@sweepconsole/js@0.2.0/dist/sweep.js"></script>
+<button id="pay-usdc">Subscribe with USDC</button>
+
+<script>
+  Sweep.mount("#pay-usdc", { session: "/api/sweep/session" });
+</script>
+```
+
+```js
+// your server — the payer's id comes from the cookie, never from the page
+import Sweep from "@sweepconsole/node";
+const sweep = new Sweep(process.env.SWEEP_SECRET_KEY);
+
+// A plan you made in the Sweep portal:
+app.post("/api/sweep/session", requireLogin, async (req, res) => {
+  const session = await sweep.checkout.sessions.create({
+    plan: "plan_pro",
+    externalRef: req.user.id,
+    successUrl: "https://app.example.com/welcome",
+    cancelUrl: "https://app.example.com/pricing",
+  });
+  res.json({ url: session.url });
+});
+
+// Or, on the external rail, where you do the billing yourself:
+//   const mandate = await sweep.mandates.create({
+//     externalRef: req.user.id,
+//     maxAmount: usdc("35.00"),        // the ceiling, with headroom — not the price
+//     interval: "monthly",
+//     chains: ["base", "arbitrum", "optimism"],
+//     expiresAt: addYears(new Date(), 1),
+//   });
+//   res.json({ url: mandate.authorizationUrl });
+```
+
+That is the whole integration. The payer signs in their wallet on Sweep's hosted
+page, and `mandate.authorized` arrives on your webhook endpoint.
+
+## Keeping the payer on your page
+
+`mount()` navigates away and comes back by `return_url`. On a subscription page
+that is the wrong shape: the payer is mid-task in an account they are already
+signed into, and a full navigation costs them their scroll position, any form
+state, and the sense of still being on your site.
+
+`authorize()` opens the same checkout in a panel over your page instead.
+
+```html
+<button id="authorize">Authorize payments</button>
+<script>
+  Sweep.authorize("#authorize", {
+    session: "/api/sweep/mandate-link",
+    onAuthorized: (m) => location.assign("/billing?ok=" + m.mandate_id),
+    onCancelled: () => console.log("payer closed it"),
+  });
+</script>
+```
+
+A centred 520px panel on a desktop, a full-height sheet under 560px. Escape,
+the close button and a backdrop click all dismiss it and fire `onCancelled`.
+Your page's scroll position and the focused element are restored on the way
+out, which is the entire reason for not navigating.
+
+`mode` picks how it opens — `"modal"` (default), `"popup"` for a separate
+window, or `"redirect"` for exactly what `mount()` does.
+
+### Wallets and frames
+
+A browser extension is not obliged to inject itself into a cross-origin
+iframe, and this checkout needs a wallet signature. Where the extension has
+not, the framed page opens its own window for the signing step — a top-level
+context where every wallet behaves normally — and reports the result back
+through the frame. You do not configure this and your `onAuthorized` fires the
+same either way.
+
+It is why the panel is not sandboxed: sandboxing without `allow-popups` would
+close the one exit that page has.
+
+### React
+
+```tsx
+import { SweepAuthorize } from "@sweepconsole/react";
+
+<SweepAuthorize session="/api/sweep/mandate-link" onAuthorized={(m) => save(m.mandate_id)}>
+  Authorize with wallet
+</SweepAuthorize>
+```
+
+A thin wrapper over `authorize()` — everything real lives here, so nothing is
+missing for anyone loading this package from a script tag.
+
+### Trying it
+
+`examples/embed.html` is a stand-in for your page. Serve the package over HTTP
+(`npx serve packages/js`, then `/examples/embed.html`) — `file://` has no
+origin, and the checkout checks it.
+
+## Why it will not call Sweep for you
+
+This package has no API key and cannot create a session. Everything a browser
+sends is something the person at the browser can change, so an `externalRef`
+that came from the page is a user id the customer chose — and on this rail a
+mandate is *standing* authority, so a forged one misattributes a recurring
+charge rather than one payment. Your server already knows who is logged in.
+
+For a public link — a pricing page, an invoice, a QR code — there is no identity
+to protect, and a plain anchor is enough:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@sweepconsole/js@0.2.0/dist/button.css">
+<a class="sweep-pay" href="https://pay.sweepconsole.com/pay/plink_a1b2c3?ref=user_42">
+  Subscribe with USDC
+</a>
+```
+
+## Install
+
+```sh
+npm i @sweepconsole/js
+```
+
+```js
+import { mount } from "@sweepconsole/js";
+import "@sweepconsole/js/button.css";   // or let mount() inject it
+
+mount("#pay-usdc", { session: "/api/sweep/session" });
+```
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `session` | *required* | Your endpoint, POSTed to, answering `{ url }`. A function returning the URL also works. |
+| `label` | the element's own text, else `"Subscribe with USDC"` | |
+| `busyLabel` | `"Starting…"` | |
+| `variant` | `"solid"` | `"solid"`, `"outline"`, `"light"` |
+| `size` | `"md"` | `"sm"` for a compact row |
+| `block` | `false` | Full width, for a checkout column |
+| `body` | — | Extra JSON for your endpoint |
+| `headers` | — | Extra headers, e.g. a CSRF token |
+| `credentials` | `"same-origin"` | So your session cookie is sent |
+| `injectStyles` | `true` | Set `false` under a CSP that forbids inline styles and link `button.css` |
+| `onError` | logs | The button returns to rest first, so the payer can retry. Tell them something. |
+| `onRedirect` | — | Return `false` to handle the navigation yourself |
+
+`mount()` returns `{ element, destroy() }`.
+
+Your endpoint's reply is read liberally: `url`, `checkout_url`,
+`authorization_url`, their camelCase forms, and any of them nested under `data`.
+An endpoint that forwards Sweep's own response verbatim works unchanged.
+
+## Theming
+
+Four custom properties, and `font: inherit` so it never arrives in a typeface
+you did not choose.
+
+```css
+.sweep-pay {
+  --sweep-radius: 10px;
+  --sweep-bg: #111827;
+  --sweep-fg: #fff;
+  --sweep-border: #111827;
+}
+```
+
+## Say "Subscribe", not "Pay"
+
+Authorizing on this rail signs a standing permission with a monthly ceiling, not
+a single payment. A payer who read "Pay $29" and then meets a wallet asking for
+recurring authority has been misled by the button, and that is the moment they
+abandon the checkout. Use "Pay" only if you are charging once and never again.
+
+## What it deliberately does not do
+
+- **No iframe.** The hosted page needs a wallet, and injected providers are
+  unreliable inside a cross-origin frame. The button navigates the top level.
+- **No wallet detection.** It never probes for `window.ethereum` to decide
+  whether to render. A mobile wallet browser fails that test, and the hosted
+  page handles a missing wallet better than a hidden button does.
+- **No fulfilment signal.** Returning to your site means the payer came back,
+  nothing more. Grant access on `mandate.authorized`.
+
+## Tests
+
+```sh
+node test/button.test.mjs
+```
+
+Runs the built `dist/sweep.js` against a small DOM stub — the redirect, the
+error path, the in-flight click guard, and style injection. Build first.

package/dist/button.css

@@ -0,0 +1,16 @@
+/* @sweepconsole/js — the button, standalone. Generated from src/index.ts; edit it there. */
+.sweep-pay{--_bg:var(--sweep-bg,#201e1d);--_fg:var(--sweep-fg,#fff);--_edge:var(--sweep-border,var(--_bg));display:inline-flex;align-items:center;justify-content:center;gap:.625rem;box-sizing:border-box;font:inherit;font-size:.9375rem;font-weight:700;letter-spacing:-.01em;line-height:1.2;text-decoration:none;white-space:nowrap;padding:.8125rem 1.25rem;border:2px solid var(--_edge);border-radius:var(--sweep-radius,0);background:var(--_bg);color:var(--_fg);cursor:pointer;position:relative;transition:transform .12s ease,box-shadow .12s ease,opacity .12s ease}
+.sweep-pay:hover{transform:translateY(-2px);box-shadow:0 2px 0 var(--_edge)}
+.sweep-pay:active{transform:translateY(0);box-shadow:none}
+.sweep-pay:focus-visible{outline:2px solid var(--_bg);outline-offset:3px}
+.sweep-pay[aria-busy=true],.sweep-pay[disabled]{opacity:.6;pointer-events:none}
+.sweep-pay--outline{--_bg:transparent;--_fg:currentColor;--_edge:currentColor}
+.sweep-pay--light{--_bg:#fff;--_fg:#201e1d;--_edge:#201e1d}
+.sweep-pay--sm{font-size:.8125rem;padding:.5625rem .875rem;gap:.4375rem}
+.sweep-pay--block{display:flex;width:100%}
+.sweep-pay__mark,.sweep-pay__spin{flex:none}
+.sweep-pay__spin{display:none}
+.sweep-pay[aria-busy=true] .sweep-pay__mark{display:none}
+.sweep-pay[aria-busy=true] .sweep-pay__spin{display:block;animation:sweep-pay-spin .7s linear infinite}
+@keyframes sweep-pay-spin{to{transform:rotate(360deg)}}
+@media (prefers-reduced-motion:reduce){.sweep-pay{transition:none}.sweep-pay:hover{transform:none}.sweep-pay[aria-busy=true] .sweep-pay__spin{animation-duration:2.4s}}

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @sweepconsole/js — the browser half of the rail.
+ *
+ * One button. It asks YOUR server for a URL and sends the payer there.
+ *
+ * It deliberately cannot talk to Sweep. Everything a browser sends is
+ * something the person at the browser can change, so a payer id that came from
+ * the page is a payer id the customer picked — and on this rail a mandate is
+ * standing authority, so a forged one misattributes a recurring charge rather
+ * than a single payment. The server half (`@sweepconsole/node`) holds the
+ * secret key, reads the id from its own session, and hands back a URL. All this
+ * file does is fetch that URL and follow it.
+ *
+ * No dependencies, no build step for the consumer, and no module system
+ * required: it is published as ESM for npm and as a classic script that defines
+ * `window.Sweep` for a CDN tag.
+ *
+ * IMPORTANT, if you edit this file: the CDN build is produced by wrapping tsc's
+ * output in an IIFE, which works only while this stays ONE file with no
+ * `import` and no `export { … }` block. scripts/build-cdn.mjs asserts both and
+ * fails the build rather than shipping something broken.
+ */
+/** How the button looks. `solid` is the default. */
+export type SweepVariant = "solid" | "outline" | "light";
+export interface MountOptions {
+    /**
+     * Your endpoint, which creates the session and returns a URL. Called with
+     * POST. Must answer `{ url }` — `checkout_url`, `authorization_url`, and any
+     * of those nested under `data`, are also accepted, so an endpoint that simply
+     * forwards Sweep's own response works unchanged.
+     *
+     * A function is also allowed, for a page that already has its own fetching
+     * conventions: return the URL (or a promise of it) and nothing is fetched
+     * here.
+     */
+    session: string | (() => string | Promise<string>);
+    /**
+     * The button's text. Defaults to the element's existing text, or
+     * "Subscribe with USDC".
+     *
+     * Prefer "Subscribe" to "Pay" unless you are charging once. Authorizing on
+     * this rail signs a standing permission with a ceiling, and a payer who read
+     * "Pay" meets a wallet asking for more than they agreed to.
+     */
+    label?: string;
+    /** Shown while your endpoint is working. Defaults to "Starting…". */
+    busyLabel?: string;
+    variant?: SweepVariant;
+    size?: "md" | "sm";
+    /** Fill the container's width, for a checkout column. */
+    block?: boolean;
+    /** Extra JSON to post to your endpoint. */
+    body?: Record<string, unknown>;
+    /** Extra headers, e.g. a CSRF token. */
+    headers?: Record<string, string>;
+    /** Defaults to "same-origin", so your session cookie is sent. */
+    credentials?: RequestCredentials;
+    /**
+     * Set false if your Content-Security-Policy forbids inline styles; link
+     * `button.css` from the package instead.
+     */
+    injectStyles?: boolean;
+    /**
+     * Called when the session could not be created. The button returns to its
+     * resting state first, so the payer can try again. Without one, the error is
+     * logged — tell the payer something instead.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Called with the URL just before leaving the page. Return `false` to take
+     * over the navigation yourself.
+     */
+    onRedirect?: (url: string) => void | boolean;
+}
+export interface SweepButton {
+    /** The button element, mounted or created. */
+    readonly element: HTMLElement;
+    /** Remove the handler and undo what mounting changed. */
+    destroy(): void;
+}
+/**
+ * The stylesheet, also published as `button.css` for anyone who would rather
+ * link it. Four custom properties are the whole theming surface, and
+ * `font: inherit` means the button never arrives in a typeface the merchant
+ * did not choose.
+ */
+export declare const BUTTON_CSS = ".sweep-pay{--_bg:var(--sweep-bg,#201e1d);--_fg:var(--sweep-fg,#fff);--_edge:var(--sweep-border,var(--_bg));display:inline-flex;align-items:center;justify-content:center;gap:.625rem;box-sizing:border-box;font:inherit;font-size:.9375rem;font-weight:700;letter-spacing:-.01em;line-height:1.2;text-decoration:none;white-space:nowrap;padding:.8125rem 1.25rem;border:2px solid var(--_edge);border-radius:var(--sweep-radius,0);background:var(--_bg);color:var(--_fg);cursor:pointer;position:relative;transition:transform .12s ease,box-shadow .12s ease,opacity .12s ease}\n.sweep-pay:hover{transform:translateY(-2px);box-shadow:0 2px 0 var(--_edge)}\n.sweep-pay:active{transform:translateY(0);box-shadow:none}\n.sweep-pay:focus-visible{outline:2px solid var(--_bg);outline-offset:3px}\n.sweep-pay[aria-busy=true],.sweep-pay[disabled]{opacity:.6;pointer-events:none}\n.sweep-pay--outline{--_bg:transparent;--_fg:currentColor;--_edge:currentColor}\n.sweep-pay--light{--_bg:#fff;--_fg:#201e1d;--_edge:#201e1d}\n.sweep-pay--sm{font-size:.8125rem;padding:.5625rem .875rem;gap:.4375rem}\n.sweep-pay--block{display:flex;width:100%}\n.sweep-pay__mark,.sweep-pay__spin{flex:none}\n.sweep-pay__spin{display:none}\n.sweep-pay[aria-busy=true] .sweep-pay__mark{display:none}\n.sweep-pay[aria-busy=true] .sweep-pay__spin{display:block;animation:sweep-pay-spin .7s linear infinite}\n@keyframes sweep-pay-spin{to{transform:rotate(360deg)}}\n@media (prefers-reduced-motion:reduce){.sweep-pay{transition:none}.sweep-pay:hover{transform:none}.sweep-pay[aria-busy=true] .sweep-pay__spin{animation-duration:2.4s}}";
+/**
+ * Turn an element into the button, or create one inside a container.
+ *
+ * A `<button>` or `<a>` is used as-is, so the merchant's own markup and any
+ * framework ref survive. Anything else gets a real `<button>` appended —
+ * never a styled div, which cannot be reached by keyboard.
+ */
+export declare function mount(target: string | Element, opts: MountOptions): SweepButton;
+export declare const MODAL_CSS = ".sweep-modal{position:fixed;inset:0;z-index:2147483646;display:flex;align-items:center;justify-content:center;padding:24px;background:rgba(35,35,59,.55);-webkit-backdrop-filter:blur(3px);backdrop-filter:blur(3px);opacity:0;transition:opacity .2s ease}\n.sweep-modal[data-open=true]{opacity:1}\n.sweep-modal__panel{position:relative;width:100%;max-width:520px;height:min(680px,calc(100vh - 48px));background:#fff;border-radius:14px;overflow:hidden;box-shadow:0 0 0 1px rgba(35,35,80,.08),0 30px 60px -30px rgba(35,35,80,.45);opacity:0;transform:translateY(16px) scale(.92);transition:transform .34s cubic-bezier(.2,1.25,.4,1),opacity .2s ease}\n.sweep-modal[data-open=true] .sweep-modal__panel{opacity:1;transform:none}\n.sweep-modal__frame{display:block;width:100%;height:100%;border:0}\n.sweep-modal__close{position:absolute;top:10px;right:10px;width:30px;height:30px;display:flex;align-items:center;justify-content:center;border:0;border-radius:8px;background:rgba(244,244,251,.9);color:#5D5E73;cursor:pointer;font:inherit;font-size:17px;line-height:1}\n.sweep-modal__close:hover{background:#ECECF3;color:#23233B}\n.sweep-modal__close:focus-visible{outline:2px solid #4447D6;outline-offset:2px}\n@media (max-width:560px){.sweep-modal{padding:0}.sweep-modal__panel{max-width:none;height:100%;border-radius:0;opacity:1;transform:translateY(100%);transition:transform .32s cubic-bezier(.2,.8,.2,1)}.sweep-modal__close{top:8px;right:8px}}\n@media (prefers-reduced-motion:reduce){.sweep-modal,.sweep-modal__panel{transition:none}.sweep-modal__panel{transform:none}}";
+export interface AuthorizeResult {
+    /** The mandate the payer signed, as the authorize page reported it. */
+    mandate_id?: string;
+    [key: string]: unknown;
+}
+/**
+ * What opening the panel needs — no `session`, because the caller already has
+ * the URL. Split from AuthorizeOptions so `openAuthorize(url)` can be called
+ * with nothing else, which is the shape anyone driving it by hand wants.
+ */
+export interface OpenAuthorizeOptions {
+    /** Called once the payer has signed. The modal closes first. */
+    onAuthorized?: (result: AuthorizeResult) => void;
+    /** Called if they closed it without signing — backdrop, Escape or the X. */
+    onCancelled?: () => void;
+    /** Set false if your Content-Security-Policy forbids inline styles. */
+    injectStyles?: boolean;
+}
+export interface AuthorizeOptions extends MountOptions, OpenAuthorizeOptions {
+    /**
+     * Open in a new window instead of a panel. Worth setting when you already
+     * know your payers' wallets refuse to inject into frames; otherwise leave
+     * it and let the page fall back on its own.
+     */
+    mode?: "modal" | "popup" | "redirect";
+}
+export interface SweepModal {
+    /** Close it as though the payer had dismissed it. */
+    close(): void;
+}
+/**
+ * Open the authorize page over the current one.
+ *
+ * Returns immediately — the callbacks carry the outcome.
+ */
+export declare function openAuthorize(url: string, opts?: OpenAuthorizeOptions): SweepModal;
+/**
+ * A button that opens the authorize modal.
+ *
+ * Same contract as `mount()` — your endpoint returns a URL — except the payer
+ * stays on your page. `mode: "redirect"` makes it behave exactly like
+ * `mount()`, which is the escape hatch if a modal turns out to be wrong for
+ * your flow.
+ */
+export declare function authorize(target: string | Element, opts: AuthorizeOptions): SweepButton;
+/** The global the CDN build defines. Same functions, one name to reach them. */
+export declare const Sweep: {
+    mount: typeof mount;
+    authorize: typeof authorize;
+    openAuthorize: typeof openAuthorize;
+    BUTTON_CSS: string;
+    MODAL_CSS: string;
+};

package/dist/index.js

@@ -0,0 +1,447 @@
+/**
+ * @sweepconsole/js — the browser half of the rail.
+ *
+ * One button. It asks YOUR server for a URL and sends the payer there.
+ *
+ * It deliberately cannot talk to Sweep. Everything a browser sends is
+ * something the person at the browser can change, so a payer id that came from
+ * the page is a payer id the customer picked — and on this rail a mandate is
+ * standing authority, so a forged one misattributes a recurring charge rather
+ * than a single payment. The server half (`@sweepconsole/node`) holds the
+ * secret key, reads the id from its own session, and hands back a URL. All this
+ * file does is fetch that URL and follow it.
+ *
+ * No dependencies, no build step for the consumer, and no module system
+ * required: it is published as ESM for npm and as a classic script that defines
+ * `window.Sweep` for a CDN tag.
+ *
+ * IMPORTANT, if you edit this file: the CDN build is produced by wrapping tsc's
+ * output in an IIFE, which works only while this stays ONE file with no
+ * `import` and no `export { … }` block. scripts/build-cdn.mjs asserts both and
+ * fails the build rather than shipping something broken.
+ */
+const STYLE_ID = "sweep-pay-styles";
+/* The USDC mark and the busy spinner. Inlined because a button that waits on a
+   network request to look like itself is worse than one extra kilobyte. */
+const COIN_SVG = '<svg class="sweep-pay__mark" width="18" height="18" viewBox="0 0 24 24" aria-hidden="true" focusable="false">' +
+    '<circle cx="12" cy="12" r="11" fill="#2775ca"/>' +
+    '<path d="M12 5.3v1.4c2 .2 3.3 1.3 3.5 2.9h-1.8c-.2-.8-.8-1.3-1.7-1.5v3.1c2.2.5 3.7 1.1 3.7 3 0 1.8-1.4 3-3.7 3.2v1.3h-1.3v-1.3c-2.2-.2-3.6-1.4-3.8-3.2h1.8c.2.9.9 1.5 2 1.7v-3.3C8.6 12.1 7.2 11.4 7.2 9.6c0-1.7 1.4-2.8 3.5-3V5.3H12zm-1.3 2.7c-1 .2-1.6.7-1.6 1.5 0 .8.5 1.2 1.6 1.5V8zm1.3 5.1v3.1c1.1-.2 1.7-.7 1.7-1.6 0-.8-.6-1.2-1.7-1.5z" fill="#fff"/>' +
+    "</svg>";
+const SPINNER_SVG = '<svg class="sweep-pay__spin" width="18" height="18" viewBox="0 0 24 24" aria-hidden="true" focusable="false">' +
+    '<circle cx="12" cy="12" r="9" fill="none" stroke="currentColor" stroke-opacity=".3" stroke-width="2.5"/>' +
+    '<path d="M12 3a9 9 0 0 1 9 9" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"/>' +
+    "</svg>";
+/**
+ * The stylesheet, also published as `button.css` for anyone who would rather
+ * link it. Four custom properties are the whole theming surface, and
+ * `font: inherit` means the button never arrives in a typeface the merchant
+ * did not choose.
+ */
+export const BUTTON_CSS = `.sweep-pay{--_bg:var(--sweep-bg,#201e1d);--_fg:var(--sweep-fg,#fff);--_edge:var(--sweep-border,var(--_bg));display:inline-flex;align-items:center;justify-content:center;gap:.625rem;box-sizing:border-box;font:inherit;font-size:.9375rem;font-weight:700;letter-spacing:-.01em;line-height:1.2;text-decoration:none;white-space:nowrap;padding:.8125rem 1.25rem;border:2px solid var(--_edge);border-radius:var(--sweep-radius,0);background:var(--_bg);color:var(--_fg);cursor:pointer;position:relative;transition:transform .12s ease,box-shadow .12s ease,opacity .12s ease}
+.sweep-pay:hover{transform:translateY(-2px);box-shadow:0 2px 0 var(--_edge)}
+.sweep-pay:active{transform:translateY(0);box-shadow:none}
+.sweep-pay:focus-visible{outline:2px solid var(--_bg);outline-offset:3px}
+.sweep-pay[aria-busy=true],.sweep-pay[disabled]{opacity:.6;pointer-events:none}
+.sweep-pay--outline{--_bg:transparent;--_fg:currentColor;--_edge:currentColor}
+.sweep-pay--light{--_bg:#fff;--_fg:#201e1d;--_edge:#201e1d}
+.sweep-pay--sm{font-size:.8125rem;padding:.5625rem .875rem;gap:.4375rem}
+.sweep-pay--block{display:flex;width:100%}
+.sweep-pay__mark,.sweep-pay__spin{flex:none}
+.sweep-pay__spin{display:none}
+.sweep-pay[aria-busy=true] .sweep-pay__mark{display:none}
+.sweep-pay[aria-busy=true] .sweep-pay__spin{display:block;animation:sweep-pay-spin .7s linear infinite}
+@keyframes sweep-pay-spin{to{transform:rotate(360deg)}}
+@media (prefers-reduced-motion:reduce){.sweep-pay{transition:none}.sweep-pay:hover{transform:none}.sweep-pay[aria-busy=true] .sweep-pay__spin{animation-duration:2.4s}}`;
+function injectStyles() {
+    if (typeof document === "undefined")
+        return;
+    if (document.getElementById(STYLE_ID))
+        return;
+    const style = document.createElement("style");
+    style.id = STYLE_ID;
+    style.textContent = BUTTON_CSS;
+    document.head.appendChild(style);
+}
+function resolveTarget(target) {
+    const el = typeof target === "string" ? document.querySelector(target) : target;
+    if (!el) {
+        // Loudly, because the usual cause is a script running before the element
+        // exists, and a button that silently never appears is hours of confusion.
+        throw new Error(`Sweep.mount: nothing matched ${JSON.stringify(target)}. ` +
+            `Run it after the element exists, or pass the element itself.`);
+    }
+    return el;
+}
+/** Liberal on the way in: anything that looks like the URL counts. */
+function urlFrom(payload) {
+    if (typeof payload === "string")
+        return payload || null;
+    if (!payload || typeof payload !== "object")
+        return null;
+    const o = payload;
+    for (const key of ["url", "checkout_url", "authorization_url", "checkoutUrl", "authorizationUrl"]) {
+        const v = o[key];
+        if (typeof v === "string" && v)
+            return v;
+    }
+    // An endpoint that forwards Sweep's reply verbatim nests it under `data`.
+    if (o["data"] && typeof o["data"] === "object")
+        return urlFrom(o["data"]);
+    return null;
+}
+async function messageFrom(res) {
+    try {
+        const body = (await res.json());
+        const err = body["error"];
+        if (err && typeof err === "object") {
+            const m = err["message"];
+            if (typeof m === "string" && m)
+                return m;
+        }
+        if (typeof body["message"] === "string" && body["message"])
+            return body["message"];
+    }
+    catch {
+        /* not JSON; fall through to the status */
+    }
+    return `We couldn't start your payment (HTTP ${res.status}).`;
+}
+/**
+ * Refuse to navigate anywhere that could execute script.
+ *
+ * The URL arrives from the merchant's own endpoint, so this is not a defence
+ * against Sweep — it is a defence against that endpoint being made to reflect
+ * something. `location.assign("javascript:…")` runs the script in the
+ * merchant's page, with their session and their DOM, which turns a reflected
+ * value into stored XSS on a checkout.
+ *
+ * A relative URL carries no scheme and inherits the page's, so it needs no
+ * check. An absolute one must be http(s); another host is allowed, since
+ * plenty of merchants host checkout on a different one.
+ */
+function checkedUrl(url) {
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(url);
+    if (!scheme)
+        return url;
+    const protocol = (scheme[1] ?? "").toLowerCase();
+    if (protocol !== "http" && protocol !== "https") {
+        throw new Error(`Sweep: refusing to navigate to a ${protocol}: URL. Your endpoint must return an http(s) ` +
+            `address or a path.`);
+    }
+    return url;
+}
+async function fetchUrl(opts) {
+    if (typeof opts.session === "function") {
+        const url = await opts.session();
+        if (!url)
+            throw new Error("Sweep.mount: the session function returned no URL.");
+        return checkedUrl(url);
+    }
+    const hasBody = !!opts.body;
+    const res = await fetch(opts.session, {
+        method: "POST",
+        credentials: opts.credentials ?? "same-origin",
+        headers: {
+            accept: "application/json",
+            ...(hasBody ? { "content-type": "application/json" } : {}),
+            ...opts.headers,
+        },
+        ...(hasBody ? { body: JSON.stringify(opts.body) } : {}),
+    });
+    if (!res.ok)
+        throw new Error(await messageFrom(res));
+    const url = urlFrom(await res.json().catch(() => null));
+    if (!url) {
+        throw new Error("Sweep.mount: your endpoint answered without a URL. Return { url } — " +
+            "for the external rail that is the mandate's authorizationUrl.");
+    }
+    return checkedUrl(url);
+}
+/**
+ * Turn an element into the button, or create one inside a container.
+ *
+ * A `<button>` or `<a>` is used as-is, so the merchant's own markup and any
+ * framework ref survive. Anything else gets a real `<button>` appended —
+ * never a styled div, which cannot be reached by keyboard.
+ */
+export function mount(target, opts) {
+    if (!opts || !opts.session) {
+        throw new Error("Sweep.mount: `session` is required — your endpoint that returns a URL.");
+    }
+    if (opts.injectStyles !== false)
+        injectStyles();
+    const found = resolveTarget(target);
+    const tag = found.tagName.toLowerCase();
+    const reuse = tag === "button" || tag === "a";
+    const el = reuse ? found : document.createElement("button");
+    if (!reuse)
+        found.appendChild(el);
+    if (el.tagName.toLowerCase() === "button" && !el.getAttribute("type")) {
+        // Without this it submits any form it happens to sit inside.
+        el.setAttribute("type", "button");
+    }
+    const restore = {
+        className: el.className,
+        html: el.innerHTML,
+    };
+    // The merchant's own text wins over our default, and an explicit `label`
+    // wins over both. An element with only whitespace in it counts as empty.
+    const existing = reuse ? el.textContent?.trim() : "";
+    const label = opts.label || existing || "Subscribe with USDC";
+    const busyLabel = opts.busyLabel ?? "Starting…";
+    el.classList.add("sweep-pay");
+    if (opts.variant === "outline")
+        el.classList.add("sweep-pay--outline");
+    if (opts.variant === "light")
+        el.classList.add("sweep-pay--light");
+    if (opts.size === "sm")
+        el.classList.add("sweep-pay--sm");
+    if (opts.block)
+        el.classList.add("sweep-pay--block");
+    // Our own constant markup, then the label by textContent — a merchant's
+    // string never reaches innerHTML.
+    el.innerHTML = COIN_SVG + SPINNER_SVG + '<span class="sweep-pay__label"></span>';
+    const labelEl = el.querySelector(".sweep-pay__label");
+    labelEl.textContent = label;
+    let busy = false;
+    const onClick = (event) => {
+        event.preventDefault();
+        // Covers the second click, and Enter on a button CSS has only made
+        // pointer-inert.
+        if (busy)
+            return;
+        busy = true;
+        el.setAttribute("aria-busy", "true");
+        labelEl.textContent = busyLabel;
+        void fetchUrl(opts)
+            .then((url) => {
+            if (opts.onRedirect && opts.onRedirect(url) === false) {
+                busy = false;
+                el.removeAttribute("aria-busy");
+                labelEl.textContent = label;
+                return;
+            }
+            // assign, not replace: the payer can come back with the back button.
+            window.location.assign(url);
+        })
+            .catch((e) => {
+            busy = false;
+            el.removeAttribute("aria-busy");
+            labelEl.textContent = label;
+            const error = e instanceof Error ? e : new Error(String(e));
+            if (opts.onError)
+                opts.onError(error);
+            else
+                console.error("[sweep] could not start the payment:", error);
+        });
+    };
+    el.addEventListener("click", onClick);
+    return {
+        element: el,
+        destroy() {
+            el.removeEventListener("click", onClick);
+            el.removeAttribute("aria-busy");
+            if (reuse) {
+                el.className = restore.className;
+                el.innerHTML = restore.html;
+            }
+            else {
+                el.remove();
+            }
+        },
+    };
+}
+/* ════════════════════════════════════════════════════════════════════════
+   The authorize modal — the rail checkout, over the merchant's own page.
+   ════════════════════════════════════════════════════════════════════ */
+/**
+ * Why a modal rather than a redirect.
+ *
+ * `mount()` sends the payer away and brings them back by `return_url`. That
+ * is fine for a one-off checkout and wrong for a subscription page, where the
+ * payer is mid-task in an account they are already signed into: a full
+ * navigation loses their scroll position, their form state, and any sense
+ * that they are still on the merchant's site.
+ *
+ * So `authorize()` opens the same page in a centered panel over a dimmed
+ * backdrop — desktop — or a full-height sheet on a phone, where a 520px card
+ * floating in the middle of a small screen is just a worse full page.
+ *
+ * WALLETS AND IFRAMES
+ *
+ * The authorize page asks for a wallet signature, and a browser extension is
+ * not obliged to inject itself into a cross-origin frame. When it has not,
+ * the framed page opens its own popup for the signing step — a top-level
+ * context where every wallet works. That handoff lives in the page rather
+ * than here, because only the page knows whether a provider answered. This
+ * side must simply not prevent it: the iframe carries no `sandbox`, because
+ * sandboxing without `allow-popups` would close the one exit the page has.
+ */
+const MODAL_STYLE_ID = "sweep-modal-styles";
+/** Breakpoint below which the panel becomes a sheet. Matches the design. */
+const SHEET_MAX_WIDTH = 560;
+// The panel pops in like a dialog: it grows from 92% with a slight spring past
+// full size while the backdrop dims and softens. On a phone it is a sheet that
+// slides up from the bottom instead (see the media query).
+export const MODAL_CSS = `.sweep-modal{position:fixed;inset:0;z-index:2147483646;display:flex;align-items:center;justify-content:center;padding:24px;background:rgba(35,35,59,.55);-webkit-backdrop-filter:blur(3px);backdrop-filter:blur(3px);opacity:0;transition:opacity .2s ease}
+.sweep-modal[data-open=true]{opacity:1}
+.sweep-modal__panel{position:relative;width:100%;max-width:520px;height:min(680px,calc(100vh - 48px));background:#fff;border-radius:14px;overflow:hidden;box-shadow:0 0 0 1px rgba(35,35,80,.08),0 30px 60px -30px rgba(35,35,80,.45);opacity:0;transform:translateY(16px) scale(.92);transition:transform .34s cubic-bezier(.2,1.25,.4,1),opacity .2s ease}
+.sweep-modal[data-open=true] .sweep-modal__panel{opacity:1;transform:none}
+.sweep-modal__frame{display:block;width:100%;height:100%;border:0}
+.sweep-modal__close{position:absolute;top:10px;right:10px;width:30px;height:30px;display:flex;align-items:center;justify-content:center;border:0;border-radius:8px;background:rgba(244,244,251,.9);color:#5D5E73;cursor:pointer;font:inherit;font-size:17px;line-height:1}
+.sweep-modal__close:hover{background:#ECECF3;color:#23233B}
+.sweep-modal__close:focus-visible{outline:2px solid #4447D6;outline-offset:2px}
+@media (max-width:${SHEET_MAX_WIDTH}px){.sweep-modal{padding:0}.sweep-modal__panel{max-width:none;height:100%;border-radius:0;opacity:1;transform:translateY(100%);transition:transform .32s cubic-bezier(.2,.8,.2,1)}.sweep-modal__close{top:8px;right:8px}}
+@media (prefers-reduced-motion:reduce){.sweep-modal,.sweep-modal__panel{transition:none}.sweep-modal__panel{transform:none}}`;
+/**
+ * Open the authorize page over the current one.
+ *
+ * Returns immediately — the callbacks carry the outcome.
+ */
+export function openAuthorize(url, opts = {}) {
+    if (opts.injectStyles !== false)
+        injectModalStyles();
+    let frameOrigin;
+    try {
+        frameOrigin = new URL(url, window.location.href).origin;
+    }
+    catch {
+        throw new Error(`Sweep.openAuthorize: ${JSON.stringify(url)} is not a URL.`);
+    }
+    const root = document.createElement("div");
+    root.className = "sweep-modal";
+    root.setAttribute("role", "dialog");
+    root.setAttribute("aria-modal", "true");
+    root.setAttribute("aria-label", "Authorize payments");
+    const panel = document.createElement("div");
+    panel.className = "sweep-modal__panel";
+    const frame = document.createElement("iframe");
+    frame.className = "sweep-modal__frame";
+    // Deliberately no `sandbox`: see the note above — the page's popup fallback
+    // is the thing that makes this safe to attempt at all.
+    frame.setAttribute("allow", "clipboard-write; publickey-credentials-get *");
+    frame.setAttribute("title", "Authorize payments");
+    // `embed=1` is what tells the page to render as a panel and to speak this
+    // protocol. Without it the page behaves exactly as it always has.
+    frame.src = url + (url.indexOf("?") === -1 ? "?" : "&") + "embed=1";
+    const close = document.createElement("button");
+    close.type = "button";
+    close.className = "sweep-modal__close";
+    close.setAttribute("aria-label", "Close");
+    close.textContent = "\u00d7";
+    panel.appendChild(frame);
+    panel.appendChild(close);
+    root.appendChild(panel);
+    // What the page was scrolled to, and what had focus, so dismissing puts the
+    // merchant's page back exactly as the payer left it. This is the entire
+    // reason for not navigating away.
+    const prevOverflow = document.body.style.overflow;
+    const prevFocus = document.activeElement;
+    document.body.style.overflow = "hidden";
+    document.body.appendChild(root);
+    // Next frame, so the opening transition has somewhere to travel from.
+    requestAnimationFrame(() => root.setAttribute("data-open", "true"));
+    let done = false;
+    function teardown() {
+        if (done)
+            return;
+        done = true;
+        window.removeEventListener("message", onMessage);
+        document.removeEventListener("keydown", onKey);
+        document.body.style.overflow = prevOverflow;
+        root.remove();
+        if (prevFocus && typeof prevFocus.focus === "function")
+            prevFocus.focus();
+    }
+    function dismiss() {
+        const wasDone = done;
+        teardown();
+        if (!wasDone && opts.onCancelled)
+            opts.onCancelled();
+    }
+    function onKey(e) {
+        if (e.key === "Escape")
+            dismiss();
+    }
+    function onMessage(e) {
+        // Only this frame's origin may drive this modal. Without the check any
+        // page with a handle on this window could fake an authorization, and the
+        // merchant's `onAuthorized` is where a subscription gets switched on.
+        if (e.origin !== frameOrigin)
+            return;
+        if (e.source !== frame.contentWindow)
+            return;
+        const msg = e.data;
+        if (!msg || msg.source !== "sweep")
+            return;
+        if (msg.type === "ready") {
+            // Reply to the exact origin that spoke, never "*": from here on the
+            // page knows who framed it and can address us specifically.
+            frame.contentWindow?.postMessage({ source: "sweep", type: "host" }, e.origin);
+            return;
+        }
+        if (msg.type === "authorized") {
+            teardown();
+            if (opts.onAuthorized)
+                opts.onAuthorized(msg.mandate ?? {});
+            return;
+        }
+        if (msg.type === "cancelled") {
+            dismiss();
+        }
+    }
+    window.addEventListener("message", onMessage);
+    document.addEventListener("keydown", onKey);
+    close.addEventListener("click", dismiss);
+    root.addEventListener("click", (e) => {
+        // Backdrop only — a click that started inside the panel must not close it.
+        if (e.target === root)
+            dismiss();
+    });
+    return { close: dismiss };
+}
+function injectModalStyles() {
+    if (typeof document === "undefined")
+        return;
+    if (document.getElementById(MODAL_STYLE_ID))
+        return;
+    const tag = document.createElement("style");
+    tag.id = MODAL_STYLE_ID;
+    tag.textContent = MODAL_CSS;
+    document.head.appendChild(tag);
+}
+/**
+ * A button that opens the authorize modal.
+ *
+ * Same contract as `mount()` — your endpoint returns a URL — except the payer
+ * stays on your page. `mode: "redirect"` makes it behave exactly like
+ * `mount()`, which is the escape hatch if a modal turns out to be wrong for
+ * your flow.
+ */
+export function authorize(target, opts) {
+    if (!opts || !opts.session) {
+        throw new Error("Sweep.authorize: `session` is required — your endpoint that returns a URL.");
+    }
+    return mount(target, {
+        ...opts,
+        label: opts.label ?? "Authorize payments",
+        onRedirect: (url) => {
+            // Read per click, not captured at mount: a caller that flips `mode`
+            // between renders — a settings toggle, a test harness — gets the mode
+            // it is showing rather than the one it started with.
+            const mode = opts.mode ?? "modal";
+            if (mode === "redirect")
+                return; // let mount() navigate
+            if (mode === "popup") {
+                // Opened inside the click, so it is a user gesture and survives
+                // popup blockers.
+                window.open(url, "sweep_authorize", "width=520,height=720");
+                return false;
+            }
+            openAuthorize(url, opts);
+            return false; // we handled it
+        },
+    });
+}
+/** The global the CDN build defines. Same functions, one name to reach them. */
+export const Sweep = { mount, authorize, openAuthorize, BUTTON_CSS, MODAL_CSS };

package/dist/sweep.js

@@ -0,0 +1,453 @@
+/* @sweepconsole/js — https://sweepconsole.com. MIT. */
+(function (global) {
+  "use strict";
+  /**
+   * @sweepconsole/js — the browser half of the rail.
+   *
+   * One button. It asks YOUR server for a URL and sends the payer there.
+   *
+   * It deliberately cannot talk to Sweep. Everything a browser sends is
+   * something the person at the browser can change, so a payer id that came from
+   * the page is a payer id the customer picked — and on this rail a mandate is
+   * standing authority, so a forged one misattributes a recurring charge rather
+   * than a single payment. The server half (`@sweepconsole/node`) holds the
+   * secret key, reads the id from its own session, and hands back a URL. All this
+   * file does is fetch that URL and follow it.
+   *
+   * No dependencies, no build step for the consumer, and no module system
+   * required: it is published as ESM for npm and as a classic script that defines
+   * `window.Sweep` for a CDN tag.
+   *
+   * IMPORTANT, if you edit this file: the CDN build is produced by wrapping tsc's
+   * output in an IIFE, which works only while this stays ONE file with no
+   * `import` and no `export { … }` block. scripts/build-cdn.mjs asserts both and
+   * fails the build rather than shipping something broken.
+   */
+  const STYLE_ID = "sweep-pay-styles";
+  /* The USDC mark and the busy spinner. Inlined because a button that waits on a
+     network request to look like itself is worse than one extra kilobyte. */
+  const COIN_SVG = '<svg class="sweep-pay__mark" width="18" height="18" viewBox="0 0 24 24" aria-hidden="true" focusable="false">' +
+      '<circle cx="12" cy="12" r="11" fill="#2775ca"/>' +
+      '<path d="M12 5.3v1.4c2 .2 3.3 1.3 3.5 2.9h-1.8c-.2-.8-.8-1.3-1.7-1.5v3.1c2.2.5 3.7 1.1 3.7 3 0 1.8-1.4 3-3.7 3.2v1.3h-1.3v-1.3c-2.2-.2-3.6-1.4-3.8-3.2h1.8c.2.9.9 1.5 2 1.7v-3.3C8.6 12.1 7.2 11.4 7.2 9.6c0-1.7 1.4-2.8 3.5-3V5.3H12zm-1.3 2.7c-1 .2-1.6.7-1.6 1.5 0 .8.5 1.2 1.6 1.5V8zm1.3 5.1v3.1c1.1-.2 1.7-.7 1.7-1.6 0-.8-.6-1.2-1.7-1.5z" fill="#fff"/>' +
+      "</svg>";
+  const SPINNER_SVG = '<svg class="sweep-pay__spin" width="18" height="18" viewBox="0 0 24 24" aria-hidden="true" focusable="false">' +
+      '<circle cx="12" cy="12" r="9" fill="none" stroke="currentColor" stroke-opacity=".3" stroke-width="2.5"/>' +
+      '<path d="M12 3a9 9 0 0 1 9 9" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"/>' +
+      "</svg>";
+  /**
+   * The stylesheet, also published as `button.css` for anyone who would rather
+   * link it. Four custom properties are the whole theming surface, and
+   * `font: inherit` means the button never arrives in a typeface the merchant
+   * did not choose.
+   */
+  const BUTTON_CSS = `.sweep-pay{--_bg:var(--sweep-bg,#201e1d);--_fg:var(--sweep-fg,#fff);--_edge:var(--sweep-border,var(--_bg));display:inline-flex;align-items:center;justify-content:center;gap:.625rem;box-sizing:border-box;font:inherit;font-size:.9375rem;font-weight:700;letter-spacing:-.01em;line-height:1.2;text-decoration:none;white-space:nowrap;padding:.8125rem 1.25rem;border:2px solid var(--_edge);border-radius:var(--sweep-radius,0);background:var(--_bg);color:var(--_fg);cursor:pointer;position:relative;transition:transform .12s ease,box-shadow .12s ease,opacity .12s ease}
+  .sweep-pay:hover{transform:translateY(-2px);box-shadow:0 2px 0 var(--_edge)}
+  .sweep-pay:active{transform:translateY(0);box-shadow:none}
+  .sweep-pay:focus-visible{outline:2px solid var(--_bg);outline-offset:3px}
+  .sweep-pay[aria-busy=true],.sweep-pay[disabled]{opacity:.6;pointer-events:none}
+  .sweep-pay--outline{--_bg:transparent;--_fg:currentColor;--_edge:currentColor}
+  .sweep-pay--light{--_bg:#fff;--_fg:#201e1d;--_edge:#201e1d}
+  .sweep-pay--sm{font-size:.8125rem;padding:.5625rem .875rem;gap:.4375rem}
+  .sweep-pay--block{display:flex;width:100%}
+  .sweep-pay__mark,.sweep-pay__spin{flex:none}
+  .sweep-pay__spin{display:none}
+  .sweep-pay[aria-busy=true] .sweep-pay__mark{display:none}
+  .sweep-pay[aria-busy=true] .sweep-pay__spin{display:block;animation:sweep-pay-spin .7s linear infinite}
+  @keyframes sweep-pay-spin{to{transform:rotate(360deg)}}
+  @media (prefers-reduced-motion:reduce){.sweep-pay{transition:none}.sweep-pay:hover{transform:none}.sweep-pay[aria-busy=true] .sweep-pay__spin{animation-duration:2.4s}}`;
+  function injectStyles() {
+      if (typeof document === "undefined")
+          return;
+      if (document.getElementById(STYLE_ID))
+          return;
+      const style = document.createElement("style");
+      style.id = STYLE_ID;
+      style.textContent = BUTTON_CSS;
+      document.head.appendChild(style);
+  }
+  function resolveTarget(target) {
+      const el = typeof target === "string" ? document.querySelector(target) : target;
+      if (!el) {
+          // Loudly, because the usual cause is a script running before the element
+          // exists, and a button that silently never appears is hours of confusion.
+          throw new Error(`Sweep.mount: nothing matched ${JSON.stringify(target)}. ` +
+              `Run it after the element exists, or pass the element itself.`);
+      }
+      return el;
+  }
+  /** Liberal on the way in: anything that looks like the URL counts. */
+  function urlFrom(payload) {
+      if (typeof payload === "string")
+          return payload || null;
+      if (!payload || typeof payload !== "object")
+          return null;
+      const o = payload;
+      for (const key of ["url", "checkout_url", "authorization_url", "checkoutUrl", "authorizationUrl"]) {
+          const v = o[key];
+          if (typeof v === "string" && v)
+              return v;
+      }
+      // An endpoint that forwards Sweep's reply verbatim nests it under `data`.
+      if (o["data"] && typeof o["data"] === "object")
+          return urlFrom(o["data"]);
+      return null;
+  }
+  async function messageFrom(res) {
+      try {
+          const body = (await res.json());
+          const err = body["error"];
+          if (err && typeof err === "object") {
+              const m = err["message"];
+              if (typeof m === "string" && m)
+                  return m;
+          }
+          if (typeof body["message"] === "string" && body["message"])
+              return body["message"];
+      }
+      catch {
+          /* not JSON; fall through to the status */
+      }
+      return `We couldn't start your payment (HTTP ${res.status}).`;
+  }
+  /**
+   * Refuse to navigate anywhere that could execute script.
+   *
+   * The URL arrives from the merchant's own endpoint, so this is not a defence
+   * against Sweep — it is a defence against that endpoint being made to reflect
+   * something. `location.assign("javascript:…")` runs the script in the
+   * merchant's page, with their session and their DOM, which turns a reflected
+   * value into stored XSS on a checkout.
+   *
+   * A relative URL carries no scheme and inherits the page's, so it needs no
+   * check. An absolute one must be http(s); another host is allowed, since
+   * plenty of merchants host checkout on a different one.
+   */
+  function checkedUrl(url) {
+      const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(url);
+      if (!scheme)
+          return url;
+      const protocol = (scheme[1] ?? "").toLowerCase();
+      if (protocol !== "http" && protocol !== "https") {
+          throw new Error(`Sweep: refusing to navigate to a ${protocol}: URL. Your endpoint must return an http(s) ` +
+              `address or a path.`);
+      }
+      return url;
+  }
+  async function fetchUrl(opts) {
+      if (typeof opts.session === "function") {
+          const url = await opts.session();
+          if (!url)
+              throw new Error("Sweep.mount: the session function returned no URL.");
+          return checkedUrl(url);
+      }
+      const hasBody = !!opts.body;
+      const res = await fetch(opts.session, {
+          method: "POST",
+          credentials: opts.credentials ?? "same-origin",
+          headers: {
+              accept: "application/json",
+              ...(hasBody ? { "content-type": "application/json" } : {}),
+              ...opts.headers,
+          },
+          ...(hasBody ? { body: JSON.stringify(opts.body) } : {}),
+      });
+      if (!res.ok)
+          throw new Error(await messageFrom(res));
+      const url = urlFrom(await res.json().catch(() => null));
+      if (!url) {
+          throw new Error("Sweep.mount: your endpoint answered without a URL. Return { url } — " +
+              "for the external rail that is the mandate's authorizationUrl.");
+      }
+      return checkedUrl(url);
+  }
+  /**
+   * Turn an element into the button, or create one inside a container.
+   *
+   * A `<button>` or `<a>` is used as-is, so the merchant's own markup and any
+   * framework ref survive. Anything else gets a real `<button>` appended —
+   * never a styled div, which cannot be reached by keyboard.
+   */
+  function mount(target, opts) {
+      if (!opts || !opts.session) {
+          throw new Error("Sweep.mount: `session` is required — your endpoint that returns a URL.");
+      }
+      if (opts.injectStyles !== false)
+          injectStyles();
+      const found = resolveTarget(target);
+      const tag = found.tagName.toLowerCase();
+      const reuse = tag === "button" || tag === "a";
+      const el = reuse ? found : document.createElement("button");
+      if (!reuse)
+          found.appendChild(el);
+      if (el.tagName.toLowerCase() === "button" && !el.getAttribute("type")) {
+          // Without this it submits any form it happens to sit inside.
+          el.setAttribute("type", "button");
+      }
+      const restore = {
+          className: el.className,
+          html: el.innerHTML,
+      };
+      // The merchant's own text wins over our default, and an explicit `label`
+      // wins over both. An element with only whitespace in it counts as empty.
+      const existing = reuse ? el.textContent?.trim() : "";
+      const label = opts.label || existing || "Subscribe with USDC";
+      const busyLabel = opts.busyLabel ?? "Starting…";
+      el.classList.add("sweep-pay");
+      if (opts.variant === "outline")
+          el.classList.add("sweep-pay--outline");
+      if (opts.variant === "light")
+          el.classList.add("sweep-pay--light");
+      if (opts.size === "sm")
+          el.classList.add("sweep-pay--sm");
+      if (opts.block)
+          el.classList.add("sweep-pay--block");
+      // Our own constant markup, then the label by textContent — a merchant's
+      // string never reaches innerHTML.
+      el.innerHTML = COIN_SVG + SPINNER_SVG + '<span class="sweep-pay__label"></span>';
+      const labelEl = el.querySelector(".sweep-pay__label");
+      labelEl.textContent = label;
+      let busy = false;
+      const onClick = (event) => {
+          event.preventDefault();
+          // Covers the second click, and Enter on a button CSS has only made
+          // pointer-inert.
+          if (busy)
+              return;
+          busy = true;
+          el.setAttribute("aria-busy", "true");
+          labelEl.textContent = busyLabel;
+          void fetchUrl(opts)
+              .then((url) => {
+              if (opts.onRedirect && opts.onRedirect(url) === false) {
+                  busy = false;
+                  el.removeAttribute("aria-busy");
+                  labelEl.textContent = label;
+                  return;
+              }
+              // assign, not replace: the payer can come back with the back button.
+              window.location.assign(url);
+          })
+              .catch((e) => {
+              busy = false;
+              el.removeAttribute("aria-busy");
+              labelEl.textContent = label;
+              const error = e instanceof Error ? e : new Error(String(e));
+              if (opts.onError)
+                  opts.onError(error);
+              else
+                  console.error("[sweep] could not start the payment:", error);
+          });
+      };
+      el.addEventListener("click", onClick);
+      return {
+          element: el,
+          destroy() {
+              el.removeEventListener("click", onClick);
+              el.removeAttribute("aria-busy");
+              if (reuse) {
+                  el.className = restore.className;
+                  el.innerHTML = restore.html;
+              }
+              else {
+                  el.remove();
+              }
+          },
+      };
+  }
+  /* ════════════════════════════════════════════════════════════════════════
+     The authorize modal — the rail checkout, over the merchant's own page.
+     ════════════════════════════════════════════════════════════════════ */
+  /**
+   * Why a modal rather than a redirect.
+   *
+   * `mount()` sends the payer away and brings them back by `return_url`. That
+   * is fine for a one-off checkout and wrong for a subscription page, where the
+   * payer is mid-task in an account they are already signed into: a full
+   * navigation loses their scroll position, their form state, and any sense
+   * that they are still on the merchant's site.
+   *
+   * So `authorize()` opens the same page in a centered panel over a dimmed
+   * backdrop — desktop — or a full-height sheet on a phone, where a 520px card
+   * floating in the middle of a small screen is just a worse full page.
+   *
+   * WALLETS AND IFRAMES
+   *
+   * The authorize page asks for a wallet signature, and a browser extension is
+   * not obliged to inject itself into a cross-origin frame. When it has not,
+   * the framed page opens its own popup for the signing step — a top-level
+   * context where every wallet works. That handoff lives in the page rather
+   * than here, because only the page knows whether a provider answered. This
+   * side must simply not prevent it: the iframe carries no `sandbox`, because
+   * sandboxing without `allow-popups` would close the one exit the page has.
+   */
+  const MODAL_STYLE_ID = "sweep-modal-styles";
+  /** Breakpoint below which the panel becomes a sheet. Matches the design. */
+  const SHEET_MAX_WIDTH = 560;
+  // The panel pops in like a dialog: it grows from 92% with a slight spring past
+  // full size while the backdrop dims and softens. On a phone it is a sheet that
+  // slides up from the bottom instead (see the media query).
+  const MODAL_CSS = `.sweep-modal{position:fixed;inset:0;z-index:2147483646;display:flex;align-items:center;justify-content:center;padding:24px;background:rgba(35,35,59,.55);-webkit-backdrop-filter:blur(3px);backdrop-filter:blur(3px);opacity:0;transition:opacity .2s ease}
+  .sweep-modal[data-open=true]{opacity:1}
+  .sweep-modal__panel{position:relative;width:100%;max-width:520px;height:min(680px,calc(100vh - 48px));background:#fff;border-radius:14px;overflow:hidden;box-shadow:0 0 0 1px rgba(35,35,80,.08),0 30px 60px -30px rgba(35,35,80,.45);opacity:0;transform:translateY(16px) scale(.92);transition:transform .34s cubic-bezier(.2,1.25,.4,1),opacity .2s ease}
+  .sweep-modal[data-open=true] .sweep-modal__panel{opacity:1;transform:none}
+  .sweep-modal__frame{display:block;width:100%;height:100%;border:0}
+  .sweep-modal__close{position:absolute;top:10px;right:10px;width:30px;height:30px;display:flex;align-items:center;justify-content:center;border:0;border-radius:8px;background:rgba(244,244,251,.9);color:#5D5E73;cursor:pointer;font:inherit;font-size:17px;line-height:1}
+  .sweep-modal__close:hover{background:#ECECF3;color:#23233B}
+  .sweep-modal__close:focus-visible{outline:2px solid #4447D6;outline-offset:2px}
+  @media (max-width:${SHEET_MAX_WIDTH}px){.sweep-modal{padding:0}.sweep-modal__panel{max-width:none;height:100%;border-radius:0;opacity:1;transform:translateY(100%);transition:transform .32s cubic-bezier(.2,.8,.2,1)}.sweep-modal__close{top:8px;right:8px}}
+  @media (prefers-reduced-motion:reduce){.sweep-modal,.sweep-modal__panel{transition:none}.sweep-modal__panel{transform:none}}`;
+  /**
+   * Open the authorize page over the current one.
+   *
+   * Returns immediately — the callbacks carry the outcome.
+   */
+  function openAuthorize(url, opts = {}) {
+      if (opts.injectStyles !== false)
+          injectModalStyles();
+      let frameOrigin;
+      try {
+          frameOrigin = new URL(url, window.location.href).origin;
+      }
+      catch {
+          throw new Error(`Sweep.openAuthorize: ${JSON.stringify(url)} is not a URL.`);
+      }
+      const root = document.createElement("div");
+      root.className = "sweep-modal";
+      root.setAttribute("role", "dialog");
+      root.setAttribute("aria-modal", "true");
+      root.setAttribute("aria-label", "Authorize payments");
+      const panel = document.createElement("div");
+      panel.className = "sweep-modal__panel";
+      const frame = document.createElement("iframe");
+      frame.className = "sweep-modal__frame";
+      // Deliberately no `sandbox`: see the note above — the page's popup fallback
+      // is the thing that makes this safe to attempt at all.
+      frame.setAttribute("allow", "clipboard-write; publickey-credentials-get *");
+      frame.setAttribute("title", "Authorize payments");
+      // `embed=1` is what tells the page to render as a panel and to speak this
+      // protocol. Without it the page behaves exactly as it always has.
+      frame.src = url + (url.indexOf("?") === -1 ? "?" : "&") + "embed=1";
+      const close = document.createElement("button");
+      close.type = "button";
+      close.className = "sweep-modal__close";
+      close.setAttribute("aria-label", "Close");
+      close.textContent = "\u00d7";
+      panel.appendChild(frame);
+      panel.appendChild(close);
+      root.appendChild(panel);
+      // What the page was scrolled to, and what had focus, so dismissing puts the
+      // merchant's page back exactly as the payer left it. This is the entire
+      // reason for not navigating away.
+      const prevOverflow = document.body.style.overflow;
+      const prevFocus = document.activeElement;
+      document.body.style.overflow = "hidden";
+      document.body.appendChild(root);
+      // Next frame, so the opening transition has somewhere to travel from.
+      requestAnimationFrame(() => root.setAttribute("data-open", "true"));
+      let done = false;
+      function teardown() {
+          if (done)
+              return;
+          done = true;
+          window.removeEventListener("message", onMessage);
+          document.removeEventListener("keydown", onKey);
+          document.body.style.overflow = prevOverflow;
+          root.remove();
+          if (prevFocus && typeof prevFocus.focus === "function")
+              prevFocus.focus();
+      }
+      function dismiss() {
+          const wasDone = done;
+          teardown();
+          if (!wasDone && opts.onCancelled)
+              opts.onCancelled();
+      }
+      function onKey(e) {
+          if (e.key === "Escape")
+              dismiss();
+      }
+      function onMessage(e) {
+          // Only this frame's origin may drive this modal. Without the check any
+          // page with a handle on this window could fake an authorization, and the
+          // merchant's `onAuthorized` is where a subscription gets switched on.
+          if (e.origin !== frameOrigin)
+              return;
+          if (e.source !== frame.contentWindow)
+              return;
+          const msg = e.data;
+          if (!msg || msg.source !== "sweep")
+              return;
+          if (msg.type === "ready") {
+              // Reply to the exact origin that spoke, never "*": from here on the
+              // page knows who framed it and can address us specifically.
+              frame.contentWindow?.postMessage({ source: "sweep", type: "host" }, e.origin);
+              return;
+          }
+          if (msg.type === "authorized") {
+              teardown();
+              if (opts.onAuthorized)
+                  opts.onAuthorized(msg.mandate ?? {});
+              return;
+          }
+          if (msg.type === "cancelled") {
+              dismiss();
+          }
+      }
+      window.addEventListener("message", onMessage);
+      document.addEventListener("keydown", onKey);
+      close.addEventListener("click", dismiss);
+      root.addEventListener("click", (e) => {
+          // Backdrop only — a click that started inside the panel must not close it.
+          if (e.target === root)
+              dismiss();
+      });
+      return { close: dismiss };
+  }
+  function injectModalStyles() {
+      if (typeof document === "undefined")
+          return;
+      if (document.getElementById(MODAL_STYLE_ID))
+          return;
+      const tag = document.createElement("style");
+      tag.id = MODAL_STYLE_ID;
+      tag.textContent = MODAL_CSS;
+      document.head.appendChild(tag);
+  }
+  /**
+   * A button that opens the authorize modal.
+   *
+   * Same contract as `mount()` — your endpoint returns a URL — except the payer
+   * stays on your page. `mode: "redirect"` makes it behave exactly like
+   * `mount()`, which is the escape hatch if a modal turns out to be wrong for
+   * your flow.
+   */
+  function authorize(target, opts) {
+      if (!opts || !opts.session) {
+          throw new Error("Sweep.authorize: `session` is required — your endpoint that returns a URL.");
+      }
+      return mount(target, {
+          ...opts,
+          label: opts.label ?? "Authorize payments",
+          onRedirect: (url) => {
+              // Read per click, not captured at mount: a caller that flips `mode`
+              // between renders — a settings toggle, a test harness — gets the mode
+              // it is showing rather than the one it started with.
+              const mode = opts.mode ?? "modal";
+              if (mode === "redirect")
+                  return; // let mount() navigate
+              if (mode === "popup") {
+                  // Opened inside the click, so it is a user gesture and survives
+                  // popup blockers.
+                  window.open(url, "sweep_authorize", "width=520,height=720");
+                  return false;
+              }
+              openAuthorize(url, opts);
+              return false; // we handled it
+          },
+      });
+  }
+  /** The global the CDN build defines. Same functions, one name to reach them. */
+  const Sweep = { mount, authorize, openAuthorize, BUTTON_CSS, MODAL_CSS };
+
+  global.Sweep = Sweep;
+})(typeof globalThis !== "undefined" ? globalThis : window);

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@sweepconsole/js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Pay-with-USDC button for the browser \u2014 asks your server for a checkout URL and sends the payer there",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./button.css": "./dist/button.css"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/build-cdn.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node test/button.test.mjs",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "keywords": [
+    "usdc",
+    "stablecoin",
+    "subscriptions",
+    "payments",
+    "checkout",
+    "button",
+    "sweep-console"
+  ],
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/u4believe/sweep-console.git",
+    "directory": "packages/js"
+  },
+  "homepage": "https://github.com/u4believe/sweep-console#readme",
+  "bugs": {
+    "url": "https://github.com/u4believe/sweep-console/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}