glyphpay 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# glyphpay
 
-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.
+Drop-in connector that lets a website take payments through [GlyphPay](https://glyphpay.net) by Design Glyph. Payments go to the site owner's own Stripe connected account.
+
+| Import | Runs on | What it gives you |
+| --- | --- | --- |
+| `glyphpay/server` | Site's server | `glyphPay()`: `checkout` and `webhook` route handlers, plus `createPayment`, `getPayment`, `refund`, `reconcile` |
+| `glyphpay/react` | Browser | `<GlyphPayCheckout />` |
+| `glyphpay/browser` | Browser, any site | `mountCheckout(el, options)` for sites without React |
+
+## Connect a site from the CLI
+
+```sh
+npx glyphpay connect --url https://client-site.com
+```
+
+The command opens Glyph Pay in your browser. Sign in as the client's billing email (or a Design Glyph admin), pick the client account, confirm the webhook URL and approve the pairing code. The terminal receives a test service credential and, when a webhook URL was registered, its signing secret. It writes both to `.env.local`:
+
+```sh
+GLYPHPAY_TOKEN=dgsvc_test_...
+GLYPHPAY_CALLBACK_SECRET=dgcb_...
+```
+
+- `--url <site>` registers `<site>/api/glyphpay/webhook`. Pass a full URL to use a different route.
+- `--env <path>` targets another env file; `--print` prints the values instead of writing.
+- `--no-open`, `--base-url` and `--timeout` help scripts and local testing.
+- Codes expire after ten minutes. Approving again rotates the token: the previous token stops working immediately.
+- Pairing is disabled while the platform is in live mode.
+
+The browser never receives the credential. Keep the token in server environment variables and never prefix it with `NEXT_PUBLIC_`, `VITE_` or `PUBLIC_`.
+
+## Manual setup: connect the client in Design Glyph admin
+
+1. **Admin → Clients → (client)**: make sure Stripe onboarding is complete (charges enabled).
+2. **Issue a service credential** (test first). Copy the `dgsvc_test_…` token. It is shown only once.
+3. **Set the callback URL** to `https://<client-site>/api/glyphpay/webhook`. Copy the signing secret. It is also shown only once.
+
+## 2. Add to the client site
+
+```sh
+pnpm add glyphpay
+```
+
+`.env` (server only, never `NEXT_PUBLIC_`):
+
+```sh
+GLYPHPAY_TOKEN=dgsvc_test_...
+GLYPHPAY_CALLBACK_SECRET=...
+```
+
+`lib/glyphpay.ts`
+
+```ts
+import { glyphPay, CheckoutError } from "glyphpay/server";
+
+export const glyphpay = glyphPay({
+  token: process.env.GLYPHPAY_TOKEN,
+  callbackSecret: process.env.GLYPHPAY_CALLBACK_SECRET,
+
+  // Price the order from YOUR data. Never trust an amount sent by the browser.
+  async priceOrder(body) {
+    const cart = await db.carts.get((body as { cartId: string }).cartId);
+    if (!cart?.items.length) throw new CheckoutError("Your cart is empty.");
+    // orderId must change whenever the total changes, or GlyphPay returns 409.
+    return { orderId: `${cart.id}-v${cart.version}`, amountCents: cart.totalCents, description: `Order ${cart.id}` };
+  },
+
+  // Signed and verified. At-least-once delivery: dedupe on event.id. Throw to have it retried.
+  async onEvent(event) {
+    if (event.type === "payment.succeeded") await db.orders.markPaid(event.data.orderId, event.id);
+  },
+});
+```
+
+`app/api/glyphpay/checkout/route.ts`
+
+```ts
+import { glyphpay } from "@/lib/glyphpay";
+export const POST = glyphpay.checkout;
+```
+
+`app/api/glyphpay/webhook/route.ts`
+
+```ts
+import { glyphpay } from "@/lib/glyphpay";
+export const POST = glyphpay.webhook;
+```
+
+Checkout page:
+
+```tsx
+import { GlyphPayCheckout } from "glyphpay/react";
+
+<GlyphPayCheckout order={{ cartId }} returnUrl={`/thank-you?cart=${cartId}`} appearance={{ theme: "stripe" }} />
+```
+
+Style the button with `.glyphpay button { … }`. Errors appear in `.glyphpay [role=alert]`.
+
+Without React:
+
+```html
+<div id="pay"></div>
+<script type="module">
+  import { mountCheckout } from "glyphpay/browser";
+  mountCheckout(document.getElementById("pay"), { order: { cartId: "42" }, returnUrl: "/thank-you" });
+</script>
+```
+
+The route handlers take a standard `Request` and return a `Response`, so the same two lines work in Remix, Astro, Hono, SvelteKit, and Cloudflare Workers. In Express, use `createPayment` and `verifyCallback` directly.
+
+## How a payment flows
+
+1. The component POSTs `order` to `/api/glyphpay/checkout`. `priceOrder` sets the amount, and the site's server calls GlyphPay with the token.
+2. The browser gets back only `clientSecret`, `publishableKey`, and `stripeAccount`, then mounts Stripe's Payment Element.
+3. The shopper pays, and Stripe redirects to `returnUrl`. **The redirect doesn't prove payment.**
+4. GlyphPay POSTs `payment.succeeded` to `/api/glyphpay/webhook`, and `onEvent` marks the order paid. The thank-you page reads the order status from your database, or calls `glyphpay.getPayment(paymentId)`.
+
+Refunds run server-side:
+
+```ts
+await glyphpay.refund(paymentId, { idempotencyKey: `${orderId}-refund-1` });
+```
+
+## Develop
+
+```sh
+cd packages/glyphpay && npm install && npm test
+```

package/dist/browser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * GlyphPay connector, browser half. Framework-free: works on any site.
+ * Talks only to the site's own checkout route; the service credential never reaches the browser.
+ */
+import { type Appearance } from "@stripe/stripe-js";
+export interface CheckoutOptions {
+    /** JSON posted to your checkout route, e.g. `{ cartId }`. Your server prices it; never send a trusted amount. */
+    order: unknown;
+    /** Where Stripe sends the shopper after paying. Confirm the order server-side there (callback/getPayment), not from the URL. */
+    returnUrl: string;
+    /** Your site's checkout route. Default `/api/glyphpay/checkout`. */
+    endpoint?: string;
+    /** Stripe Elements appearance (theme, colors, fonts). */
+    appearance?: Appearance;
+    buttonText?: string;
+}
+/**
+ * Renders `<form class="glyphpay">` (Stripe Payment Element + submit button + `role=alert` message)
+ * into `container`. Style it with `.glyphpay button { … }`. Returns an unmount function.
+ */
+export declare function mountCheckout(container: HTMLElement, options: CheckoutOptions): () => void;

package/dist/browser.js

@@ -0,0 +1,52 @@
+/**
+ * GlyphPay connector, browser half. Framework-free: works on any site.
+ * Talks only to the site's own checkout route; the service credential never reaches the browser.
+ */
+import { loadStripe } from "@stripe/stripe-js";
+/**
+ * Renders `<form class="glyphpay">` (Stripe Payment Element + submit button + `role=alert` message)
+ * into `container`. Style it with `.glyphpay button { … }`. Returns an unmount function.
+ */
+export function mountCheckout(container, options) {
+    let unmounted = false;
+    const form = document.createElement("form");
+    form.className = "glyphpay";
+    const slot = document.createElement("div");
+    const button = document.createElement("button");
+    button.type = "submit";
+    button.disabled = true;
+    button.textContent = options.buttonText ?? "Pay now";
+    const message = document.createElement("p");
+    message.setAttribute("role", "alert");
+    form.append(slot, button, message);
+    container.append(form);
+    (async () => {
+        const res = await fetch(options.endpoint ?? "/api/glyphpay/checkout", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(options.order ?? null),
+        });
+        const session = await res.json().catch(() => ({}));
+        if (!res.ok)
+            throw new Error(session.error ?? "Checkout is unavailable right now.");
+        const stripe = await loadStripe(session.publishableKey, { stripeAccount: session.stripeAccount });
+        if (!stripe)
+            throw new Error("Could not load the payment form.");
+        if (unmounted)
+            return;
+        const elements = stripe.elements({ clientSecret: session.clientSecret, appearance: options.appearance });
+        const payment = elements.create("payment");
+        payment.on("ready", () => { button.disabled = false; });
+        payment.mount(slot);
+        form.addEventListener("submit", async (event) => {
+            event.preventDefault();
+            button.disabled = true;
+            message.textContent = "";
+            // On success Stripe always redirects to returnUrl (adds payment_intent & redirect_status params).
+            const { error } = await stripe.confirmPayment({ elements, confirmParams: { return_url: new URL(options.returnUrl, location.href).href } });
+            message.textContent = error.message ?? "Payment failed. Please try again.";
+            button.disabled = false;
+        });
+    })().catch((error) => { message.textContent = error.message; });
+    return () => { unmounted = true; form.remove(); };
+}

package/dist/cli.d.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * `glyphpay connect` - browser pairing for a client site.
+ *
+ * The CLI never asks for a password or an API token. It creates a short-lived
+ * pairing request, opens the Glyph Pay site, and waits while the signed-in
+ * owner approves it in the browser. The service credential and webhook signing
+ * secret are returned only to this process, then written to the site's server
+ * environment file.
+ *
+ * Zero runtime dependencies: Node 18+ built-ins and global fetch only.
+ */
+export declare class CliUsageError extends Error {
+    constructor(message: string);
+}
+export declare class CliApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export interface ConnectOptions {
+    /** Site URL (a webhook path is appended when the URL has no path), or the exact callback URL. */
+    url?: string;
+    /** Env file to update. Defaults to `.env.local`. */
+    envFile?: string;
+    /** Print the credentials instead of writing them to a file. */
+    print?: boolean;
+    /** Skip opening a browser. */
+    noOpen?: boolean;
+    /** API origin. Defaults to GLYPHPAY_API_URL or production. */
+    baseUrl?: string;
+    /** How long to wait for browser approval. */
+    timeoutSeconds?: number;
+}
+export interface ConnectResult {
+    businessName: string;
+    environment: "test" | "live";
+    callbackUrl: string | null;
+    writtenTo: string | null;
+}
+interface ParsedCommand {
+    command: "connect" | "help" | "version";
+    options: ConnectOptions;
+}
+export declare function parseArgs(argv: string[]): ParsedCommand;
+export declare function helpText(): string;
+/** `shop.example.com` -> `https://shop.example.com/api/glyphpay/webhook`. */
+export declare function toCallbackUrl(raw: string): string;
+/**
+ * Replace values in an env file without touching unrelated lines. The first
+ * occurrence of a managed key is rewritten; duplicate managed keys are dropped
+ * so the file keeps a single source of truth.
+ */
+export declare function upsertEnv(contents: string, values: Record<string, string>): string;
+export declare function openBrowser(url: string): boolean;
+export declare function runConnect(options?: ConnectOptions): Promise<ConnectResult>;
+export declare function main(argv?: string[]): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,409 @@
+#!/usr/bin/env node
+/**
+ * `glyphpay connect` - browser pairing for a client site.
+ *
+ * The CLI never asks for a password or an API token. It creates a short-lived
+ * pairing request, opens the Glyph Pay site, and waits while the signed-in
+ * owner approves it in the browser. The service credential and webhook signing
+ * secret are returned only to this process, then written to the site's server
+ * environment file.
+ *
+ * Zero runtime dependencies: Node 18+ built-ins and global fetch only.
+ */
+import { spawn } from "node:child_process";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+const VERSION = "0.2.0";
+const DEFAULT_BASE_URL = "https://designglyph.web.app";
+const DEFAULT_ENV_FILE = ".env.local";
+const DEFAULT_TIMEOUT_SECONDS = 600;
+const TOKEN_KEY = "GLYPHPAY_TOKEN";
+const CALLBACK_SECRET_KEY = "GLYPHPAY_CALLBACK_SECRET";
+const WEBHOOK_PATH = "/api/glyphpay/webhook";
+export class CliUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliUsageError";
+    }
+}
+export class CliApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = "CliApiError";
+        this.status = status;
+        this.code = code;
+    }
+}
+const useColor = !!process.stdout.isTTY && !process.env.NO_COLOR;
+function style(code, text) {
+    return useColor ? `\u001b[${code}m${text}\u001b[0m` : text;
+}
+function say(text = "") {
+    process.stdout.write(`${text}\n`);
+}
+function sleep(ms) {
+    return new Promise((done) => setTimeout(done, ms));
+}
+/* ------------------------------------------------------------------ */
+/* Argument parsing                                                    */
+/* ------------------------------------------------------------------ */
+function takeValue(argv, index, flag) {
+    const value = argv[index + 1];
+    if (!value || value.startsWith("-"))
+        throw new CliUsageError(`${flag} needs a value.`);
+    return [value, index + 1];
+}
+export function parseArgs(argv) {
+    const options = {};
+    let command = "connect";
+    let sawCommand = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--help" || argument === "-h" || argument === "help")
+            return { command: "help", options };
+        if (argument === "--version" || argument === "-v")
+            return { command: "version", options };
+        if (argument === "connect" || argument === "login") {
+            if (sawCommand)
+                throw new CliUsageError("Only one command can run at a time.");
+            sawCommand = true;
+            command = "connect";
+            continue;
+        }
+        if (argument === "--print") {
+            options.print = true;
+            continue;
+        }
+        if (argument === "--no-open") {
+            options.noOpen = true;
+            continue;
+        }
+        const [flag, inlineValue] = argument.includes("=") ? argument.split(/=(.*)/s, 2) : [argument, undefined];
+        if (flag === "--url" || flag === "--callback-url") {
+            if (inlineValue !== undefined) {
+                if (!inlineValue)
+                    throw new CliUsageError(`${flag} needs a value.`);
+                options.url = inlineValue;
+            }
+            else {
+                const [value, next] = takeValue(argv, index, flag);
+                options.url = value;
+                index = next;
+            }
+            continue;
+        }
+        if (flag === "--env") {
+            if (inlineValue !== undefined) {
+                if (!inlineValue)
+                    throw new CliUsageError("--env needs a path.");
+                options.envFile = inlineValue;
+            }
+            else {
+                const [value, next] = takeValue(argv, index, flag);
+                options.envFile = value;
+                index = next;
+            }
+            continue;
+        }
+        if (flag === "--base-url") {
+            if (inlineValue !== undefined) {
+                if (!inlineValue)
+                    throw new CliUsageError("--base-url needs a URL.");
+                options.baseUrl = inlineValue;
+            }
+            else {
+                const [value, next] = takeValue(argv, index, flag);
+                options.baseUrl = value;
+                index = next;
+            }
+            continue;
+        }
+        if (flag === "--timeout") {
+            const raw = inlineValue ?? takeValue(argv, index, flag)[0];
+            if (inlineValue === undefined)
+                index += 1;
+            const parsed = Number(raw);
+            if (!Number.isFinite(parsed) || parsed < 10 || parsed > 1800) {
+                throw new CliUsageError("--timeout must be between 10 and 1800 seconds.");
+            }
+            options.timeoutSeconds = Math.floor(parsed);
+            continue;
+        }
+        if (argument.startsWith("-"))
+            throw new CliUsageError(`Unknown option: ${argument}`);
+        throw new CliUsageError(`Unknown command: ${argument}`);
+    }
+    return { command, options };
+}
+export function helpText() {
+    return `glyphpay - take payments on your site through Glyph Pay
+
+Usage
+  glyphpay connect [options]     Connect a site (alias: glyphpay login)
+  glyphpay --version
+
+Options
+  --url <site-url>         Site to connect. Adds /api/glyphpay/webhook when the
+                           URL has no path. Or pass the exact callback URL.
+  --env <path>             Env file to update (default: ${DEFAULT_ENV_FILE})
+  --print                  Print the credentials instead of writing a file
+  --no-open                Do not open a browser automatically
+  --base-url <url>         Glyph Pay API origin (default: ${DEFAULT_BASE_URL})
+  --timeout <seconds>      Wait for approval (default: ${DEFAULT_TIMEOUT_SECONDS})
+  -h, --help               Show this help
+  -v, --version            Show the version
+
+The browser step signs in to Glyph Pay, lets you pick the client account, and
+approves this machine. The service credential goes only to this terminal.`;
+}
+/* ------------------------------------------------------------------ */
+/* URL and env-file helpers                                            */
+/* ------------------------------------------------------------------ */
+/** `shop.example.com` -> `https://shop.example.com/api/glyphpay/webhook`. */
+export function toCallbackUrl(raw) {
+    let value = raw.trim();
+    if (!value)
+        throw new CliUsageError("Enter the site's URL.");
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(value))
+        value = `https://${value}`;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new CliUsageError(`"${raw}" is not a valid URL.`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new CliUsageError("The site URL must start with https:// (or http:// for local development).");
+    }
+    if (url.username || url.password)
+        throw new CliUsageError("The site URL must not contain a username or password.");
+    if (url.pathname === "/" || url.pathname === "")
+        url.pathname = WEBHOOK_PATH;
+    url.hash = "";
+    return url.toString();
+}
+/**
+ * Replace values in an env file without touching unrelated lines. The first
+ * occurrence of a managed key is rewritten; duplicate managed keys are dropped
+ * so the file keeps a single source of truth.
+ */
+export function upsertEnv(contents, values) {
+    const eol = contents.includes("\r\n") ? "\r\n" : "\n";
+    const lines = contents.length
+        ? contents.replace(/\r\n/g, "\n").replace(/\n+$/, "").split("\n")
+        : [];
+    const pending = new Map(Object.entries(values));
+    const handled = new Set();
+    const output = [];
+    for (const line of lines) {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+        const key = match?.[1];
+        if (key && pending.has(key)) {
+            output.push(`${key}=${pending.get(key)}`);
+            pending.delete(key);
+            handled.add(key);
+            continue;
+        }
+        if (key && handled.has(key))
+            continue;
+        output.push(line);
+    }
+    for (const [key, value] of pending)
+        output.push(`${key}=${value}`);
+    return `${output.join(eol)}${eol}`;
+}
+function isNotFound(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+async function readEnvFile(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return "";
+        throw error;
+    }
+}
+async function writeEnvFile(path, contents) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, contents, { encoding: "utf8", mode: 0o600 });
+    try {
+        await chmod(path, 0o600);
+    }
+    catch {
+        // Windows does not use POSIX modes; the file still lives in the project.
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Browser and API                                                     */
+/* ------------------------------------------------------------------ */
+export function openBrowser(url) {
+    const command = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(command, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => undefined);
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function api(baseUrl, path, body) {
+    let response;
+    try {
+        response = await fetch(`${baseUrl.replace(/\/$/, "")}/api/cli/v1${path}`, {
+            method: body === undefined ? "GET" : "POST",
+            headers: {
+                accept: "application/json",
+                ...(body === undefined ? {} : { "content-type": "application/json" }),
+                "user-agent": `glyphpay-cli/${VERSION}`,
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch {
+        throw new CliApiError(0, "network", "Could not reach Glyph Pay. Check your connection and try again.");
+    }
+    const payload = (await response.json().catch(() => null));
+    if (!response.ok || !payload?.ok) {
+        throw new CliApiError(response.status, payload && "error" in payload ? payload.error?.code ?? "request_failed" : "request_failed", (payload && "error" in payload ? payload.error?.message : null) ??
+            `Glyph Pay request failed (HTTP ${response.status}).`);
+    }
+    return payload.data;
+}
+async function waitForApproval(baseUrl, deviceCode, firstInterval, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let interval = Math.max(1, firstInterval);
+    let lastNetworkError = null;
+    while (Date.now() < deadline) {
+        await sleep(interval * 1000);
+        try {
+            const result = await api(baseUrl, "/device/token", { deviceCode });
+            if (result.status === "approved")
+                return result;
+            interval = Math.max(1, result.interval || interval);
+            lastNetworkError = null;
+        }
+        catch (error) {
+            if (error instanceof CliApiError && error.status === 429) {
+                interval = Math.min(interval + 2, 10);
+                continue;
+            }
+            if (error instanceof CliApiError && (error.status === 404 || error.status === 410))
+                throw error;
+            lastNetworkError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    throw new CliApiError(0, "timeout", `Timed out waiting for approval${lastNetworkError ? ` (last error: ${lastNetworkError})` : ""}. ` +
+        "Run the command again for a fresh code.");
+}
+/* ------------------------------------------------------------------ */
+/* Connect                                                             */
+/* ------------------------------------------------------------------ */
+export async function runConnect(options = {}) {
+    const baseUrl = options.baseUrl?.trim() || process.env.GLYPHPAY_API_URL?.trim() || DEFAULT_BASE_URL;
+    const timeoutSeconds = options.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+    const callbackUrl = options.url ? toCallbackUrl(options.url) : null;
+    const created = await api(baseUrl, "/device", { callbackUrl });
+    say();
+    say(style(1, "Glyph Pay - connect a site"));
+    say();
+    say(`1. Open ${style(4, created.verificationUrl)}`);
+    say(`2. Sign in and approve pairing code ${style(1, created.userCode)}.`);
+    say(`   The code expires at ${new Date(created.expiresAt).toLocaleTimeString()}.`);
+    if (options.noOpen) {
+        say("   (Browser opening skipped: --no-open.)");
+    }
+    else if (openBrowser(created.verificationUrl)) {
+        say("   A browser window should open.");
+    }
+    else {
+        say("   Could not open a browser. Open the link above manually.");
+    }
+    say();
+    say("Waiting for approval...");
+    const approved = await waitForApproval(baseUrl, created.deviceCode, created.interval, timeoutSeconds * 1000);
+    const values = { [TOKEN_KEY]: approved.token };
+    if (approved.callbackSecret)
+        values[CALLBACK_SECRET_KEY] = approved.callbackSecret;
+    say();
+    say(style(1, `Connected ${approved.businessName} (${approved.environment} mode).`));
+    if (approved.callbackUrl)
+        say(`Webhook registered: ${approved.callbackUrl}`);
+    else
+        say("No webhook was registered. Add one later in Glyph Pay admin if your site needs payment events.");
+    let writtenTo = null;
+    if (options.print) {
+        say();
+        say("Add these to your server environment (never NEXT_PUBLIC_):");
+        for (const [key, value] of Object.entries(values))
+            say(`${key}=${value}`);
+    }
+    else {
+        const file = resolve(options.envFile ?? DEFAULT_ENV_FILE);
+        try {
+            const next = upsertEnv(await readEnvFile(file), values);
+            await writeEnvFile(file, next);
+            writtenTo = file;
+            const display = relative(process.cwd(), file) || file;
+            say(`Wrote ${Object.keys(values).join(" and ")} to ${display}.`);
+        }
+        catch (error) {
+            say();
+            say(style(33, `Could not write ${file}: ${error instanceof Error ? error.message : String(error)}`));
+            say("Copy these values into your server environment now; they are shown only this once:");
+            for (const [key, value] of Object.entries(values))
+                say(`${key}=${value}`);
+            throw new CliApiError(1, "env_write_failed", "The credentials were printed above but not saved to a file.");
+        }
+    }
+    say();
+    say("The token is shown only once. Run this command again to rotate it.");
+    return {
+        businessName: approved.businessName,
+        environment: approved.environment,
+        callbackUrl: approved.callbackUrl,
+        writtenTo,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Entry point                                                         */
+/* ------------------------------------------------------------------ */
+export async function main(argv = process.argv.slice(2)) {
+    try {
+        const parsed = parseArgs(argv);
+        if (parsed.command === "help") {
+            say(helpText());
+            return 0;
+        }
+        if (parsed.command === "version") {
+            say(VERSION);
+            return 0;
+        }
+        await runConnect(parsed.options);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            say(style(31, error.message));
+            say("Run `glyphpay --help` for usage.");
+            return 2;
+        }
+        say();
+        say(style(31, error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    void main().then((code) => {
+        process.exitCode = code;
+    });
+}

package/dist/react.d.ts

@@ -0,0 +1,6 @@
+import { type CheckoutOptions } from "./browser.js";
+export type { CheckoutOptions };
+/** Drop-in checkout. Remounts when `order` changes; other props are read once on mount. */
+export declare function GlyphPayCheckout({ className, ...options }: CheckoutOptions & {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/react.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { mountCheckout } from "./browser.js";
+/** Drop-in checkout. Remounts when `order` changes; other props are read once on mount. */
+export function GlyphPayCheckout({ className, ...options }) {
+    const ref = useRef(null);
+    const orderKey = JSON.stringify(options.order);
+    // ponytail: keyed on order only, so inline appearance/returnUrl objects don't remount Stripe every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    useEffect(() => mountCheckout(ref.current, options), [orderKey]);
+    return _jsx("div", { ref: ref, className: className });
+}

package/dist/server.d.ts

@@ -0,0 +1,95 @@
+/**
+ * GlyphPay connector, server half. Holds the dgsvc_ service credential, so it
+ * must only ever run on the client site's server (route handlers, API routes).
+ * Runtime-agnostic: uses fetch + Web Crypto (Node 20+, Next.js, edge, Workers).
+ */
+export interface GlyphPayOptions {
+    /** Service credential from Design Glyph admin (dgsvc_test_… / dgsvc_live_…). Never ship to the browser. */
+    token: string | undefined;
+    /** Signing secret shown when the callback URL was saved in Design Glyph admin. Needed for `webhook`. */
+    callbackSecret?: string;
+    /** Defaults to the Design Glyph production origin. */
+    baseUrl?: string;
+    /**
+     * Price the order from YOUR data (DB, cart, CMS). Never trust an amount sent by the browser.
+     * `orderId` must change whenever the amount or description changes (e.g. `${cartId}-v${version}`):
+     * GlyphPay ties one payment to one orderId and rejects a changed amount with a 409.
+     * Throw `CheckoutError` to show the shopper a message.
+     */
+    priceOrder?: (body: unknown, req: Request) => Promise<Order> | Order;
+    /** Runs once per verified callback. Delivery is at-least-once, so dedupe on `event.id`. Throw to have it retried. */
+    onEvent?: (event: GlyphPayEvent) => Promise<void> | void;
+}
+export interface Order {
+    orderId: string;
+    amountCents: number;
+    description: string;
+}
+export interface CheckoutSession {
+    id: string;
+    paymentIntentId: string;
+    clientSecret: string;
+    publishableKey: string;
+    stripeAccount: string;
+}
+export type PaymentStatus = "creating" | "requires_payment_method" | "processing" | "succeeded" | "canceled" | "failed";
+export interface Payment {
+    id: string;
+    orderId: string;
+    status: PaymentStatus;
+    amountCents: number;
+    applicationFeeCents: number;
+    currency: "usd";
+    refundedCents: number;
+    refunds: {
+        stripeRefundId: string | null;
+        amountCents: number;
+        status: string;
+    }[];
+    disputes: {
+        status: string;
+        amountCents: number;
+    }[];
+    /** True while not terminal. Callbacks (or polling) are the source of truth, never the browser redirect. */
+    stale: boolean;
+    updatedAt: string;
+}
+export interface Refund {
+    paymentId: string;
+    refundId: string;
+    amountCents: number;
+    status: string;
+}
+export interface GlyphPayEvent {
+    id: string;
+    type: "payment.succeeded" | "payment.failed" | "payment.processing" | "payment.canceled" | "payment.refund_updated" | "payment.dispute_updated";
+    createdAt: string;
+    livemode: boolean;
+    data: Payment;
+}
+/** Error from the GlyphPay API (status/message are the API's). */
+export declare class GlyphPayError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+/** Throw from `priceOrder` to send `message` to the shopper with a 400. */
+export declare class CheckoutError extends Error {
+}
+export declare function glyphPay(options: GlyphPayOptions): {
+    /** Route handler: `export const POST = glyphpay.checkout`. Prices the order, returns what the browser needs. */
+    checkout: (req: Request) => Promise<Response>;
+    /** Route handler for the callback URL registered in Design Glyph admin: `export const POST = glyphpay.webhook`. */
+    webhook: (req: Request) => Promise<Response>;
+    /** Idempotent per orderId: calling again returns the same payment. */
+    createPayment: (order: Order) => Promise<CheckoutSession>;
+    getPayment: (paymentId: string) => Promise<Payment>;
+    /** Omit amountCents to refund the remaining balance. Reusing an idempotencyKey replays the same refund. */
+    refund: (paymentId: string, input: {
+        idempotencyKey: string;
+        amountCents?: number;
+    }) => Promise<Refund>;
+    /** Re-read the payment from Stripe if a callback looks missed. */
+    reconcile: (paymentId: string) => Promise<Payment>;
+};
+/** Verifies `Designglyph-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "t.body")>` and returns the event. Rejects >5 min skew. */
+export declare function verifyCallback(rawBody: string, header: string | null, secret: string): Promise<GlyphPayEvent>;

package/dist/server.js

@@ -0,0 +1,96 @@
+/**
+ * GlyphPay connector, server half. Holds the dgsvc_ service credential, so it
+ * must only ever run on the client site's server (route handlers, API routes).
+ * Runtime-agnostic: uses fetch + Web Crypto (Node 20+, Next.js, edge, Workers).
+ */
+/** Error from the GlyphPay API (status/message are the API's). */
+export class GlyphPayError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Throw from `priceOrder` to send `message` to the shopper with a 400. */
+export class CheckoutError extends Error {
+}
+export function glyphPay(options) {
+    const baseUrl = (options.baseUrl ?? "https://designglyph.web.app").replace(/\/$/, "");
+    async function call(method, path, body) {
+        // ponytail: checked per call, not at construction, so `next build` works without env vars.
+        if (!/^dgsvc_(test|live)_/.test(options.token ?? ""))
+            throw new GlyphPayError(500, "GlyphPay token is missing or not a dgsvc_ service credential.");
+        const res = await fetch(`${baseUrl}/api/client/v1${path}`, {
+            method,
+            headers: { authorization: `Bearer ${options.token}`, ...(body === undefined ? {} : { "content-type": "application/json" }) },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok || !json?.ok)
+            throw new GlyphPayError(res.status, json?.error?.message ?? `GlyphPay request failed (HTTP ${res.status}).`);
+        return json.data;
+    }
+    const id = (paymentId) => encodeURIComponent(paymentId);
+    const api = {
+        /** Idempotent per orderId: calling again returns the same payment. */
+        createPayment: (order) => call("POST", "/payments", { ...order, currency: "usd" }),
+        getPayment: (paymentId) => call("GET", `/payments/${id(paymentId)}`),
+        /** Omit amountCents to refund the remaining balance. Reusing an idempotencyKey replays the same refund. */
+        refund: (paymentId, input) => call("POST", `/payments/${id(paymentId)}/refunds`, input),
+        /** Re-read the payment from Stripe if a callback looks missed. */
+        reconcile: (paymentId) => call("POST", `/payments/${id(paymentId)}/reconcile`),
+    };
+    return {
+        ...api,
+        /** Route handler: `export const POST = glyphpay.checkout`. Prices the order, returns what the browser needs. */
+        checkout: async (req) => {
+            try {
+                if (!options.priceOrder)
+                    throw new Error("GlyphPay: priceOrder is required for checkout.");
+                const session = await api.createPayment(await options.priceOrder(await req.json().catch(() => null), req));
+                const { clientSecret, publishableKey, stripeAccount } = session;
+                return Response.json({ clientSecret, publishableKey, stripeAccount, paymentId: session.id }, { headers: { "cache-control": "no-store" } });
+            }
+            catch (error) {
+                if (error instanceof CheckoutError)
+                    return Response.json({ error: error.message }, { status: 400 });
+                console.error("GlyphPay checkout failed:", error instanceof Error ? error.message : error);
+                return Response.json({ error: "Checkout is unavailable right now. Please try again." }, { status: 502 });
+            }
+        },
+        /** Route handler for the callback URL registered in Design Glyph admin: `export const POST = glyphpay.webhook`. */
+        webhook: async (req) => {
+            // 5xx makes GlyphPay retry (up to 72h), so config and handler errors don't lose events. A bad signature is a permanent 400.
+            if (!options.callbackSecret)
+                return new Response("GlyphPay callback secret not configured", { status: 500 });
+            let event;
+            try {
+                event = await verifyCallback(await req.text(), req.headers.get("designglyph-signature"), options.callbackSecret);
+            }
+            catch {
+                return new Response("Invalid signature", { status: 400 });
+            }
+            try {
+                await options.onEvent?.(event);
+            }
+            catch (error) {
+                console.error(`GlyphPay event ${event.id} handler failed:`, error instanceof Error ? error.message : error);
+                return new Response("Handler failed", { status: 500 });
+            }
+            return new Response(null, { status: 204 });
+        },
+    };
+}
+/** Verifies `Designglyph-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "t.body")>` and returns the event. Rejects >5 min skew. */
+export async function verifyCallback(rawBody, header, secret) {
+    const { t, v1 } = Object.fromEntries((header ?? "").split(",").map((part) => part.trim().split("=")));
+    const enc = new TextEncoder();
+    const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+    const signature = /^[0-9a-f]{64}$/.test(v1 ?? "") ? Uint8Array.from(v1.match(/../g), (h) => parseInt(h, 16)) : null;
+    const fresh = Math.abs(Date.now() / 1000 - Number(t)) <= 300;
+    // subtle.verify compares in constant time.
+    if (!signature || !fresh || !(await crypto.subtle.verify("HMAC", key, signature, enc.encode(`${t}.${rawBody}`)))) {
+        throw new GlyphPayError(400, "Invalid GlyphPay signature.");
+    }
+    return JSON.parse(rawBody);
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "glyphpay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Drop-in GlyphPay checkout for websites, plus `glyphpay connect` for browser-based setup.",
+  "homepage": "https://glyphpay.net",
+  "keywords": [
+    "glyphpay",
+    "payments",
+    "checkout",
+    "stripe",
+    "react",
+    "nextjs"
+  ],
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "glyphpay": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "tsc && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@stripe/stripe-js": "^10.2.1"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/react": "^19",
+    "typescript": "^5"
+  }
+}