glyphpay 0.1.0 → 0.2.0

package/README.md

@@ -8,7 +8,28 @@ Drop-in connector that lets a website take payments through [GlyphPay](https://g
 | `glyphpay/react` | Browser | `<GlyphPayCheckout />` |
 | `glyphpay/browser` | Browser, any site | `mountCheckout(el, options)` for sites without React |
 
-## 1. Connect the client in Design Glyph admin
+## 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.

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/package.json

@@ -1,16 +1,40 @@
 {
   "name": "glyphpay",
-  "version": "0.1.0",
-  "description": "Drop-in GlyphPay checkout for websites: server route handlers plus a React or plain-JS payment form.",
+  "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"],
+  "keywords": [
+    "glyphpay",
+    "payments",
+    "checkout",
+    "stripe",
+    "react",
+    "nextjs"
+  ],
   "license": "UNLICENSED",
   "type": "module",
-  "files": ["dist"],
+  "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" }
+    "./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",
@@ -24,9 +48,12 @@
     "react": ">=18"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true }
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@types/node": "^22.20.5",
     "@types/react": "^19",
     "typescript": "^5"
   }