glyphpay 0.2.0 → 0.3.0

package/README.md

@@ -8,6 +8,16 @@ 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 |
 
+The CLI covers setup, diagnostics, and credential lifecycle:
+
+| Command | What it does |
+| --- | --- |
+| `glyphpay connect` | Pair a site through the browser and write the server credential. |
+| `glyphpay doctor` | Check env, token, Stripe readiness, webhook URL, and an optional signed test event. |
+| `glyphpay rotate` | Re-pair the site and replace the credential. |
+| `glyphpay disconnect` | Revoke the credential and remove the local keys. |
+| `glyphpay init` | Scaffold the Next.js App Router routes and env placeholders. |
+
 ## Connect a site from the CLI
 
 ```sh
@@ -29,13 +39,40 @@ GLYPHPAY_CALLBACK_SECRET=dgcb_...
 
 The browser never receives the credential. Keep the token in server environment variables and never prefix it with `NEXT_PUBLIC_`, `VITE_` or `PUBLIC_`.
 
+## Check, rotate, and disconnect
+
+```sh
+npx glyphpay doctor
+npx glyphpay doctor --json
+npx glyphpay rotate
+npx glyphpay disconnect
+```
+
+`doctor` verifies the local env file, checks for credentials leaked into public-prefixed variables, validates the token with Glyph Pay, checks Stripe charge readiness and the registered webhook, and optionally sends a signed test event:
+
+```sh
+npx glyphpay doctor --send-test-event
+```
+
+The test event has type `webhook.test` and a zero-dollar `data` payload. Ignore event types you do not handle in `onEvent`; do not treat the test event as a real payment.
+
+`rotate` re-runs browser approval and reuses the registered callback URL when the current token is still valid. `disconnect` revokes the credential immediately and removes `GLYPHPAY_TOKEN` and `GLYPHPAY_CALLBACK_SECRET` from the env file; pass `--yes` in scripts or `--keep-env` to leave the local values in place.
+
+## Scaffold a Next.js site
+
+```sh
+npx glyphpay init
+```
+
+The command detects `app` or `src/app`, creates `lib/glyphpay.ts` (or `.js`), adds the checkout and webhook route handlers, and appends placeholders to `.env.example` without changing existing values. It refuses to overwrite existing files unless you pass `--force`; use `--dry-run` to preview. Then run `glyphpay connect` and wire `priceOrder()` and `onEvent()` to your order database.
+
 ## 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
+## Add to the client site
 
 ```sh
 pnpm add glyphpay

package/dist/cli.d.ts

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 /**
- * `glyphpay connect` - browser pairing for a client site.
+ * Glyph Pay command line.
  *
- * 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.
+ * `connect` 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.
+ *
+ * `doctor` verifies the local setup and, optionally, delivers a signed test
+ * webhook. `disconnect` revokes the credential. `rotate` re-pairs and replaces
+ * it. `init` scaffolds the Next.js App Router integration.
  *
  * Zero runtime dependencies: Node 18+ built-ins and global fetch only.
  */
@@ -18,10 +21,10 @@ export declare class CliApiError extends Error {
     readonly code: string;
     constructor(status: number, code: string, message: string);
 }
-export interface ConnectOptions {
+export interface CliOptions {
     /** 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`. */
+    /** Env file to read or update. Defaults to `.env.local`. */
     envFile?: string;
     /** Print the credentials instead of writing them to a file. */
     print?: boolean;
@@ -31,6 +34,20 @@ export interface ConnectOptions {
     baseUrl?: string;
     /** How long to wait for browser approval. */
     timeoutSeconds?: number;
+    /** Machine-readable doctor output. */
+    json?: boolean;
+    /** Skip the interactive disconnect confirmation. */
+    yes?: boolean;
+    /** Keep local env values after a successful disconnect. */
+    keepEnv?: boolean;
+    /** Doctor: deliver a signed test event to the registered webhook. */
+    sendTestEvent?: boolean;
+    /** Init: overwrite generated files. */
+    force?: boolean;
+    /** Init: print planned files without writing. */
+    dryRun?: boolean;
+    /** Init: project directory. Defaults to the current directory. */
+    dir?: string;
 }
 export interface ConnectResult {
     businessName: string;
@@ -38,9 +55,16 @@ export interface ConnectResult {
     callbackUrl: string | null;
     writtenTo: string | null;
 }
+export interface DisconnectResult {
+    businessName: string | null;
+    removedKeys: boolean;
+    alreadyRevoked: boolean;
+    canceled: boolean;
+}
+type Command = "connect" | "rotate" | "disconnect" | "doctor" | "init" | "help" | "version";
 interface ParsedCommand {
-    command: "connect" | "help" | "version";
-    options: ConnectOptions;
+    command: Command;
+    options: CliOptions;
 }
 export declare function parseArgs(argv: string[]): ParsedCommand;
 export declare function helpText(): string;
@@ -52,7 +76,37 @@ export declare function toCallbackUrl(raw: string): string;
  * so the file keeps a single source of truth.
  */
 export declare function upsertEnv(contents: string, values: Record<string, string>): string;
+/** Add missing `KEY=` placeholders without changing an existing value. */
+export declare function ensureEnvKeys(contents: string, keys: string[]): string;
+/** Remove managed keys, preserving every unrelated line. */
+export declare function removeEnvKeys(contents: string, keys: string[]): string;
+/** Read a simple KEY=value line without executing or expanding the file. */
+export declare function readEnvValue(contents: string, key: string): string | null;
+/** Public-prefixed variables must never contain a Glyph Pay credential. */
+export declare function findPublicCredentialKeys(contents: string): string[];
 export declare function openBrowser(url: string): boolean;
-export declare function runConnect(options?: ConnectOptions): Promise<ConnectResult>;
+export declare function runConnect(options?: CliOptions, mode?: "connect" | "rotate"): Promise<ConnectResult>;
+/**
+ * Re-pair the site. If the current env token is still valid, reuse the
+ * callback URL registered on the server so a rotation does not drop webhooks.
+ */
+export declare function runRotate(options?: CliOptions): Promise<ConnectResult>;
+export declare function runDisconnect(options?: CliOptions): Promise<DisconnectResult>;
+export type DoctorCheckStatus = "ok" | "warn" | "error";
+export interface DoctorCheck {
+    id: string;
+    status: DoctorCheckStatus;
+    label: string;
+    detail?: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    envFile: string;
+    environment: string | null;
+    businessName: string | null;
+    checks: DoctorCheck[];
+}
+export declare function runDoctor(options?: CliOptions): Promise<DoctorReport>;
+export declare function runInit(options?: CliOptions): Promise<void>;
 export declare function main(argv?: string[]): Promise<number>;
 export {};

package/dist/cli.js

@@ -1,20 +1,25 @@
 #!/usr/bin/env node
 /**
- * `glyphpay connect` - browser pairing for a client site.
+ * Glyph Pay command line.
  *
- * 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.
+ * `connect` 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.
+ *
+ * `doctor` verifies the local setup and, optionally, delivers a signed test
+ * webhook. `disconnect` revokes the credential. `rotate` re-pairs and replaces
+ * it. `init` scaffolds the Next.js App Router integration.
  *
  * 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 { createHmac, randomBytes } from "node:crypto";
+import { access, chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { pathToFileURL } from "node:url";
-const VERSION = "0.2.0";
+const VERSION = "0.3.0";
 const DEFAULT_BASE_URL = "https://designglyph.web.app";
 const DEFAULT_ENV_FILE = ".env.local";
 const DEFAULT_TIMEOUT_SECONDS = 600;
@@ -56,6 +61,19 @@ function takeValue(argv, index, flag) {
         throw new CliUsageError(`${flag} needs a value.`);
     return [value, index + 1];
 }
+function commandFor(value) {
+    if (value === "connect" || value === "login")
+        return "connect";
+    if (value === "rotate")
+        return "rotate";
+    if (value === "disconnect" || value === "logout")
+        return "disconnect";
+    if (value === "doctor" || value === "check")
+        return "doctor";
+    if (value === "init")
+        return "init";
+    return null;
+}
 export function parseArgs(argv) {
     const options = {};
     let command = "connect";
@@ -66,11 +84,12 @@ export function parseArgs(argv) {
             return { command: "help", options };
         if (argument === "--version" || argument === "-v")
             return { command: "version", options };
-        if (argument === "connect" || argument === "login") {
+        const namedCommand = commandFor(argument);
+        if (namedCommand) {
             if (sawCommand)
                 throw new CliUsageError("Only one command can run at a time.");
             sawCommand = true;
-            command = "connect";
+            command = namedCommand;
             continue;
         }
         if (argument === "--print") {
@@ -81,6 +100,30 @@ export function parseArgs(argv) {
             options.noOpen = true;
             continue;
         }
+        if (argument === "--json") {
+            options.json = true;
+            continue;
+        }
+        if (argument === "--yes" || argument === "-y") {
+            options.yes = true;
+            continue;
+        }
+        if (argument === "--keep-env") {
+            options.keepEnv = true;
+            continue;
+        }
+        if (argument === "--send-test-event") {
+            options.sendTestEvent = true;
+            continue;
+        }
+        if (argument === "--force") {
+            options.force = true;
+            continue;
+        }
+        if (argument === "--dry-run") {
+            options.dryRun = true;
+            continue;
+        }
         const [flag, inlineValue] = argument.includes("=") ? argument.split(/=(.*)/s, 2) : [argument, undefined];
         if (flag === "--url" || flag === "--callback-url") {
             if (inlineValue !== undefined) {
@@ -121,6 +164,19 @@ export function parseArgs(argv) {
             }
             continue;
         }
+        if (flag === "--dir") {
+            if (inlineValue !== undefined) {
+                if (!inlineValue)
+                    throw new CliUsageError("--dir needs a path.");
+                options.dir = inlineValue;
+            }
+            else {
+                const [value, next] = takeValue(argv, index, flag);
+                options.dir = value;
+                index = next;
+            }
+            continue;
+        }
         if (flag === "--timeout") {
             const raw = inlineValue ?? takeValue(argv, index, flag)[0];
             if (inlineValue === undefined)
@@ -142,19 +198,34 @@ export function helpText() {
     return `glyphpay - take payments on your site through Glyph Pay
 
 Usage
-  glyphpay connect [options]     Connect a site (alias: glyphpay login)
+  glyphpay connect [options]       Connect a site (alias: login)
+  glyphpay rotate [options]        Re-pair and rotate the current credential
+  glyphpay disconnect [options]    Revoke the credential and remove local keys
+  glyphpay doctor [options]        Check env, token, Stripe and webhook setup
+  glyphpay init [options]          Scaffold a Next.js App Router integration
   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.
+Connect / rotate
+  --url <site-url>         Site to connect. Adds ${WEBHOOK_PATH} 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
+
+Doctor
+  --json                   Print a machine-readable report
+  --send-test-event        POST a signed webhook.test event to the callback URL
+
+Disconnect
+  --yes, -y                Do not ask for confirmation
+  --keep-env               Keep the local env values after revocation
+
+Init
+  --dir <path>             Project directory (default: current directory)
+  --dry-run                Show planned files without writing them
+  --force                  Overwrite generated files
 
 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.`;
@@ -216,6 +287,50 @@ export function upsertEnv(contents, values) {
         output.push(`${key}=${value}`);
     return `${output.join(eol)}${eol}`;
 }
+/** Add missing `KEY=` placeholders without changing an existing value. */
+export function ensureEnvKeys(contents, keys) {
+    const missing = keys.filter((key) => !new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=`, "m").test(contents));
+    if (missing.length === 0)
+        return contents;
+    const base = contents.length && !contents.endsWith("\n") ? `${contents}\n` : contents;
+    return `${base}${missing.map((key) => `${key}=`).join("\n")}\n`;
+}
+/** Remove managed keys, preserving every unrelated line. */
+export function removeEnvKeys(contents, keys) {
+    if (!contents.length)
+        return "";
+    const managed = new Set(keys);
+    const eol = contents.includes("\r\n") ? "\r\n" : "\n";
+    const lines = contents.replace(/\r\n/g, "\n").replace(/\n+$/, "").split("\n");
+    const output = lines.filter((line) => {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+        return !(match && managed.has(match[1]));
+    });
+    return output.length ? `${output.join(eol)}${eol}` : "";
+}
+/** Read a simple KEY=value line without executing or expanding the file. */
+export function readEnvValue(contents, key) {
+    const match = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=\\s*(.*)$`, "m").exec(contents);
+    if (!match)
+        return null;
+    const raw = match[1].trim();
+    if ((raw.startsWith('"') && raw.endsWith('"')) ||
+        (raw.startsWith("'") && raw.endsWith("'"))) {
+        return raw.slice(1, -1);
+    }
+    return raw;
+}
+/** Public-prefixed variables must never contain a Glyph Pay credential. */
+export function findPublicCredentialKeys(contents) {
+    const exposed = [];
+    for (const line of contents.split(/\r?\n/)) {
+        const match = /^\s*(?:export\s+)?((?:NEXT_PUBLIC_|VITE_|PUBLIC_)[A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (match && /(?:dgsvc_|dgcb_|GLYPHPAY_(?:TOKEN|CALLBACK_SECRET))/.test(match[2])) {
+            exposed.push(match[1]);
+        }
+    }
+    return exposed;
+}
 function isNotFound(error) {
     return typeof error === "object" && error !== null && error.code === "ENOENT";
 }
@@ -239,6 +354,23 @@ async function writeEnvFile(path, contents) {
         // Windows does not use POSIX modes; the file still lives in the project.
     }
 }
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function directoryExists(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /* ------------------------------------------------------------------ */
 /* Browser and API                                                     */
 /* ------------------------------------------------------------------ */
@@ -255,7 +387,7 @@ export function openBrowser(url) {
         return false;
     }
 }
-async function api(baseUrl, path, body) {
+async function api(baseUrl, path, body, token) {
     let response;
     try {
         response = await fetch(`${baseUrl.replace(/\/$/, "")}/api/cli/v1${path}`, {
@@ -263,6 +395,7 @@ async function api(baseUrl, path, body) {
             headers: {
                 accept: "application/json",
                 ...(body === undefined ? {} : { "content-type": "application/json" }),
+                ...(token ? { authorization: `Bearer ${token}` } : {}),
                 "user-agent": `glyphpay-cli/${VERSION}`,
             },
             ...(body === undefined ? {} : { body: JSON.stringify(body) }),
@@ -279,6 +412,12 @@ async function api(baseUrl, path, body) {
     }
     return payload.data;
 }
+function baseUrlFor(options) {
+    return options.baseUrl?.trim() || process.env.GLYPHPAY_API_URL?.trim() || DEFAULT_BASE_URL;
+}
+function fetchCredential(baseUrl, token) {
+    return api(baseUrl, "/credential", undefined, token);
+}
 async function waitForApproval(baseUrl, deviceCode, firstInterval, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     let interval = Math.max(1, firstInterval);
@@ -306,15 +445,15 @@ async function waitForApproval(baseUrl, deviceCode, firstInterval, timeoutMs) {
         "Run the command again for a fresh code.");
 }
 /* ------------------------------------------------------------------ */
-/* Connect                                                             */
+/* Connect and rotate                                                  */
 /* ------------------------------------------------------------------ */
-export async function runConnect(options = {}) {
-    const baseUrl = options.baseUrl?.trim() || process.env.GLYPHPAY_API_URL?.trim() || DEFAULT_BASE_URL;
+export async function runConnect(options = {}, mode = "connect") {
+    const baseUrl = baseUrlFor(options);
     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(style(1, mode === "rotate" ? "Glyph Pay - rotate credential" : "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)}.`);
@@ -329,13 +468,13 @@ export async function runConnect(options = {}) {
         say("   Could not open a browser. Open the link above manually.");
     }
     say();
-    say("Waiting for approval...");
+    say(mode === "rotate" ? "Waiting for approval (the previous token stays valid until then)..." : "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).`));
+    say(style(1, `${mode === "rotate" ? "Rotated" : "Connected"} ${approved.businessName} (${approved.environment} mode).`));
     if (approved.callbackUrl)
         say(`Webhook registered: ${approved.callbackUrl}`);
     else
@@ -366,7 +505,9 @@ export async function runConnect(options = {}) {
         }
     }
     say();
-    say("The token is shown only once. Run this command again to rotate it.");
+    say(mode === "rotate"
+        ? "The previous token is already invalid. Deploy the new values before the next request."
+        : "The token is shown only once. Run this command again to rotate it.");
     return {
         businessName: approved.businessName,
         environment: approved.environment,
@@ -374,6 +515,459 @@ export async function runConnect(options = {}) {
         writtenTo,
     };
 }
+/**
+ * Re-pair the site. If the current env token is still valid, reuse the
+ * callback URL registered on the server so a rotation does not drop webhooks.
+ */
+export async function runRotate(options = {}) {
+    const baseUrl = baseUrlFor(options);
+    const envFile = resolve(options.envFile ?? DEFAULT_ENV_FILE);
+    const contents = await readEnvFile(envFile);
+    const token = readEnvValue(contents, TOKEN_KEY);
+    let url = options.url;
+    if (token) {
+        try {
+            const info = await fetchCredential(baseUrl, token);
+            say();
+            say(`Rotating ${info.businessName} (${info.environment} mode).`);
+            if (!url && info.callbackUrl)
+                url = info.callbackUrl;
+        }
+        catch (error) {
+            if (error instanceof CliApiError && error.status === 401) {
+                say(style(33, "The current token is no longer valid; starting a fresh connection."));
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    return runConnect({ ...options, url }, "rotate");
+}
+/* ------------------------------------------------------------------ */
+/* Disconnect                                                          */
+/* ------------------------------------------------------------------ */
+export async function runDisconnect(options = {}) {
+    const baseUrl = baseUrlFor(options);
+    const envFile = resolve(options.envFile ?? DEFAULT_ENV_FILE);
+    const contents = await readEnvFile(envFile);
+    const token = readEnvValue(contents, TOKEN_KEY);
+    const displayEnv = relative(process.cwd(), envFile) || envFile;
+    if (!token) {
+        throw new CliUsageError(`No ${TOKEN_KEY} found in ${displayEnv}. Nothing to disconnect.`);
+    }
+    if (!options.yes) {
+        if (!process.stdin.isTTY) {
+            throw new CliUsageError("Use --yes when running disconnect non-interactively.");
+        }
+        const prompt = createInterface({ input: process.stdin, output: process.stdout });
+        let answer = "";
+        try {
+            answer = await prompt.question(`Revoke this site's Glyph Pay credential? The site stops working immediately. [y/N] `);
+        }
+        finally {
+            prompt.close();
+        }
+        if (!/^y(es)?$/i.test(answer.trim())) {
+            say("Canceled.");
+            return { businessName: null, removedKeys: false, alreadyRevoked: false, canceled: true };
+        }
+    }
+    let businessName = null;
+    let alreadyRevoked = false;
+    try {
+        const result = await api(baseUrl, "/credential/revoke", {}, token);
+        businessName = result.businessName;
+        alreadyRevoked = result.alreadyRevoked;
+    }
+    catch (error) {
+        if (error instanceof CliApiError && error.status === 401) {
+            alreadyRevoked = true;
+            say(style(33, "The token is already invalid; removing the local credentials."));
+        }
+        else {
+            throw error;
+        }
+    }
+    let removedKeys = false;
+    if (!options.keepEnv) {
+        await writeEnvFile(envFile, removeEnvKeys(contents, [TOKEN_KEY, CALLBACK_SECRET_KEY]));
+        removedKeys = true;
+    }
+    say();
+    say(style(1, alreadyRevoked
+        ? "That credential was already disconnected."
+        : `Disconnected ${businessName ?? "the site"}.`));
+    if (removedKeys)
+        say(`Removed ${TOKEN_KEY} and ${CALLBACK_SECRET_KEY} from ${displayEnv}.`);
+    else
+        say(`The credential is revoked. Local values in ${displayEnv} were kept.`);
+    return { businessName, removedKeys, alreadyRevoked, canceled: false };
+}
+const TOKEN_PATTERN = /^dgsvc_(test|live)_[A-Za-z0-9_-]{1,128}_[A-Za-z0-9_-]{43}$/;
+function addDoctorCheck(report, check, json) {
+    report.checks.push(check);
+    if (json)
+        return;
+    const symbol = check.status === "ok" ? style(32, "✓") : check.status === "warn" ? style(33, "!") : style(31, "✗");
+    say(`${symbol} ${check.label}`);
+    if (check.detail)
+        say(`   ${check.detail}`);
+}
+function signedTestEvent(secret, environment) {
+    const createdAt = new Date().toISOString();
+    const eventId = `evt_test_${randomBytes(8).toString("hex")}`;
+    const body = JSON.stringify({
+        id: eventId,
+        type: "webhook.test",
+        createdAt,
+        livemode: environment === "live",
+        data: {
+            id: "glyphpay_doctor",
+            orderId: "glyphpay-doctor",
+            status: "succeeded",
+            amountCents: 0,
+            applicationFeeCents: 0,
+            currency: "usd",
+            refundedCents: 0,
+            refunds: [],
+            disputes: [],
+            stale: false,
+            updatedAt: createdAt,
+        },
+    });
+    const timestamp = Math.floor(Date.now() / 1000);
+    const signature = createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+    return { body, header: `t=${timestamp},v1=${signature}`, eventId };
+}
+async function deliverTestEvent(callbackUrl, secret, environment) {
+    const { body, header } = signedTestEvent(secret, environment);
+    const response = await fetch(callbackUrl, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "designglyph-signature": header,
+            "user-agent": `glyphpay-cli/${VERSION}`,
+        },
+        body,
+        signal: AbortSignal.timeout(10_000),
+    });
+    const text = await response.text().catch(() => "");
+    return { status: response.status, ok: response.ok, text: text.slice(0, 200) };
+}
+export async function runDoctor(options = {}) {
+    const baseUrl = baseUrlFor(options);
+    const envFile = resolve(options.envFile ?? DEFAULT_ENV_FILE);
+    const displayEnv = relative(process.cwd(), envFile) || envFile;
+    const json = !!options.json;
+    const report = {
+        ok: true,
+        envFile: displayEnv,
+        environment: null,
+        businessName: null,
+        checks: [],
+    };
+    if (!json) {
+        say();
+        say(style(1, "Glyph Pay doctor"));
+        say(`Env file: ${displayEnv}`);
+        say();
+    }
+    const major = Number(process.versions.node.split(".")[0]);
+    addDoctorCheck(report, major >= 18
+        ? { id: "node", status: "ok", label: `Node ${process.versions.node}` }
+        : { id: "node", status: "error", label: `Node ${process.versions.node} is too old`, detail: "The CLI requires Node 18 or newer." }, json);
+    const exists = await fileExists(envFile);
+    addDoctorCheck(report, exists
+        ? { id: "env", status: "ok", label: `Found ${displayEnv}` }
+        : { id: "env", status: "error", label: `${displayEnv} was not found`, detail: "Run `glyphpay connect` first or pass --env <path>." }, json);
+    const contents = await readEnvFile(envFile);
+    const token = readEnvValue(contents, TOKEN_KEY);
+    const callbackSecret = readEnvValue(contents, CALLBACK_SECRET_KEY);
+    const tokenMatch = token ? TOKEN_PATTERN.exec(token) : null;
+    addDoctorCheck(report, token
+        ? { id: "token-present", status: "ok", label: `${TOKEN_KEY} is present` }
+        : { id: "token-present", status: "error", label: `${TOKEN_KEY} is missing`, detail: "Run `glyphpay connect` to issue a credential." }, json);
+    if (token) {
+        addDoctorCheck(report, tokenMatch
+            ? { id: "token-format", status: "ok", label: "Token format is valid", detail: `${tokenMatch[1]} mode` }
+            : { id: "token-format", status: "error", label: "Token format is not a dgsvc_ service credential" }, json);
+    }
+    const exposed = findPublicCredentialKeys(contents);
+    addDoctorCheck(report, exposed.length
+        ? {
+            id: "public-env",
+            status: "error",
+            label: `${exposed.join(", ")} expose a Glyph Pay credential`,
+            detail: "Move these values to server-only variables and rotate the credential.",
+        }
+        : { id: "public-env", status: "ok", label: "No credential is in a public-prefixed variable" }, json);
+    if (callbackSecret) {
+        addDoctorCheck(report, /^dgcb_[A-Za-z0-9_-]{20,}$/.test(callbackSecret)
+            ? { id: "callback-secret-format", status: "ok", label: "Callback signing secret format is valid" }
+            : { id: "callback-secret-format", status: "warn", label: "Callback signing secret has an unexpected format" }, json);
+    }
+    let info = null;
+    if (token && tokenMatch) {
+        try {
+            info = await fetchCredential(baseUrl, token);
+            report.environment = info.environment;
+            report.businessName = info.businessName;
+            addDoctorCheck(report, {
+                id: "token-valid",
+                status: "ok",
+                label: "Glyph Pay accepted the token",
+                detail: `${info.businessName} · ${info.environment} mode`,
+            }, json);
+        }
+        catch (error) {
+            addDoctorCheck(report, {
+                id: "token-valid",
+                status: "error",
+                label: "Glyph Pay rejected the token",
+                detail: error instanceof Error ? error.message : String(error),
+            }, json);
+        }
+    }
+    if (info) {
+        addDoctorCheck(report, info.chargesEnabled
+            ? { id: "stripe", status: "ok", label: "Stripe connected account can accept charges" }
+            : {
+                id: "stripe",
+                status: "error",
+                label: "Stripe connected account is not ready for charges",
+                detail: info.connectedAccountId
+                    ? "Complete Stripe onboarding in Design Glyph admin, then re-check."
+                    : "No connected account is linked to this client yet.",
+            }, json);
+        if (info.callbackUrl) {
+            addDoctorCheck(report, { id: "callback-url", status: "ok", label: "Webhook URL is registered", detail: info.callbackUrl }, json);
+            addDoctorCheck(report, callbackSecret
+                ? { id: "callback-secret", status: "ok", label: "Callback signing secret is present locally" }
+                : {
+                    id: "callback-secret",
+                    status: "error",
+                    label: "Callback signing secret is missing locally",
+                    detail: "Re-register the webhook in Glyph Pay admin and update GLYPHPAY_CALLBACK_SECRET.",
+                }, json);
+            if (callbackSecret) {
+                try {
+                    const reachable = await fetch(info.callbackUrl, {
+                        method: "HEAD",
+                        redirect: "manual",
+                        signal: AbortSignal.timeout(8_000),
+                    });
+                    addDoctorCheck(report, reachable.status >= 500 || reachable.status === 404
+                        ? {
+                            id: "callback-reachable",
+                            status: "warn",
+                            label: `Webhook URL returned HTTP ${reachable.status} to a HEAD request`,
+                            detail: "GlyphPay sends POST requests. A custom route may reject HEAD.",
+                        }
+                        : {
+                            id: "callback-reachable",
+                            status: "ok",
+                            label: `Webhook URL is reachable (HTTP ${reachable.status})`,
+                        }, json);
+                }
+                catch {
+                    addDoctorCheck(report, {
+                        id: "callback-reachable",
+                        status: "warn",
+                        label: "Webhook URL was not reachable from this machine",
+                        detail: "A firewall may block this terminal; Glyph Pay may still reach the public URL.",
+                    }, json);
+                }
+            }
+            if (options.sendTestEvent) {
+                if (!callbackSecret) {
+                    addDoctorCheck(report, { id: "test-event", status: "error", label: "Test event not sent", detail: "No callback signing secret is available." }, json);
+                }
+                else {
+                    try {
+                        const delivered = await deliverTestEvent(info.callbackUrl, callbackSecret, info.environment);
+                        addDoctorCheck(report, delivered.ok
+                            ? {
+                                id: "test-event",
+                                status: "ok",
+                                label: `Signed test event accepted (HTTP ${delivered.status})`,
+                            }
+                            : {
+                                id: "test-event",
+                                status: "error",
+                                label: `Signed test event rejected (HTTP ${delivered.status})`,
+                                detail: delivered.text || "Check the site's webhook route and callback secret.",
+                            }, json);
+                    }
+                    catch (error) {
+                        addDoctorCheck(report, {
+                            id: "test-event",
+                            status: "error",
+                            label: "Could not deliver the signed test event",
+                            detail: error instanceof Error ? error.message : String(error),
+                        }, json);
+                    }
+                }
+            }
+        }
+        else {
+            addDoctorCheck(report, {
+                id: "callback-url",
+                status: "warn",
+                label: "No webhook URL is registered",
+                detail: "Checkout works, but payment.succeeded events will not reach this site.",
+            }, json);
+            if (callbackSecret) {
+                addDoctorCheck(report, {
+                    id: "callback-secret",
+                    status: "warn",
+                    label: "A callback secret is present locally but no webhook URL is registered",
+                }, json);
+            }
+        }
+    }
+    report.ok = !report.checks.some((check) => check.status === "error");
+    if (json) {
+        say(JSON.stringify(report, null, 2));
+    }
+    else {
+        say();
+        say(report.ok
+            ? style(32, "No blocking problems found.")
+            : style(31, "Fix the errors above, then run `glyphpay doctor` again."));
+    }
+    return report;
+}
+function libTemplate(ts) {
+    const cartId = ts
+        ? `const cartId = (body as { cartId?: string } | null)?.cartId;`
+        : `const cartId = body?.cartId;`;
+    return `import { glyphPay, CheckoutError } from "glyphpay/server";
+
+export const glyphpay = glyphPay({
+  token: process.env.GLYPHPAY_TOKEN,
+  callbackSecret: process.env.GLYPHPAY_CALLBACK_SECRET,
+
+  async priceOrder(body) {
+    // Load the cart/order from YOUR database and return its server-side price.
+    // Never trust an amount sent by the browser.
+    ${cartId}
+    if (!cartId) throw new CheckoutError("Your cart is empty.");
+    throw new CheckoutError("Connect priceOrder() to your order database before accepting payments.");
+  },
+
+  async onEvent(event) {
+    // At-least-once delivery: dedupe on event.id before changing an order.
+    if (event.type === "payment.succeeded") {
+      // TODO: mark the order paid and store event.id.
+      console.log(\`GlyphPay payment succeeded for \${event.data.orderId}\`);
+    }
+  },
+});
+`;
+}
+function routeTemplate() {
+    return `import { glyphpay } from "../../../../lib/glyphpay";
+
+export const POST = glyphpay.checkout;
+`;
+}
+function webhookRouteTemplate() {
+    return `import { glyphpay } from "../../../../lib/glyphpay";
+
+export const POST = glyphpay.webhook;
+`;
+}
+function installCommand(hasPnpmLock, hasYarnLock, hasBunLock) {
+    if (hasPnpmLock)
+        return "pnpm add glyphpay";
+    if (hasYarnLock)
+        return "yarn add glyphpay";
+    if (hasBunLock)
+        return "bun add glyphpay";
+    return "npm install glyphpay";
+}
+export async function runInit(options = {}) {
+    const projectRoot = resolve(options.dir ?? process.cwd());
+    const packagePath = join(projectRoot, "package.json");
+    if (!(await fileExists(packagePath))) {
+        throw new CliUsageError(`No package.json found in ${projectRoot}. Run init in a Next.js project.`);
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(await readFile(packagePath, "utf8"));
+    }
+    catch {
+        throw new CliUsageError("package.json is not valid JSON.");
+    }
+    const dependencies = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    if (!dependencies.next) {
+        throw new CliUsageError("glyphpay init currently supports Next.js projects only.");
+    }
+    const hasSrcApp = await directoryExists(join(projectRoot, "src", "app"));
+    const hasRootApp = await directoryExists(join(projectRoot, "app"));
+    const hasPages = (await directoryExists(join(projectRoot, "pages"))) ||
+        (await directoryExists(join(projectRoot, "src", "pages")));
+    if (!hasSrcApp && !hasRootApp && hasPages) {
+        throw new CliUsageError("This project uses the Next.js Pages Router. glyphpay init supports the App Router; see the README for the two route files.");
+    }
+    const appDir = hasSrcApp ? join("src", "app") : join("app");
+    const libDir = hasSrcApp ? join("src", "lib") : join("lib");
+    const isTs = await fileExists(join(projectRoot, "tsconfig.json"));
+    const extension = isTs ? "ts" : "js";
+    const libPath = join(projectRoot, libDir, `glyphpay.${extension}`);
+    const checkoutPath = join(projectRoot, appDir, "api", "glyphpay", "checkout", `route.${extension}`);
+    const webhookPath = join(projectRoot, appDir, "api", "glyphpay", "webhook", `route.${extension}`);
+    const envPath = join(projectRoot, ".env.example");
+    const generated = [
+        { path: libPath, contents: libTemplate(isTs) },
+        { path: checkoutPath, contents: routeTemplate() },
+        { path: webhookPath, contents: webhookRouteTemplate() },
+    ];
+    const existing = [];
+    for (const file of generated) {
+        if (await fileExists(file.path))
+            existing.push(relative(projectRoot, file.path).replace(/\\/g, "/"));
+    }
+    if (existing.length > 0 && !options.force) {
+        throw new CliUsageError(`Refusing to overwrite existing files:\n  ${existing.join("\n  ")}\nRe-run with --force to overwrite them.`);
+    }
+    const envExisting = await readEnvFile(envPath);
+    const envBase = envExisting.trim().length > 0
+        ? envExisting
+        : "# Glyph Pay — server-side only. Never prefix these with NEXT_PUBLIC_.\n";
+    const envNext = ensureEnvKeys(envBase, [TOKEN_KEY, CALLBACK_SECRET_KEY]);
+    const envChanged = envNext !== envExisting;
+    const display = (path) => relative(projectRoot, path).replace(/\\/g, "/");
+    if (!options.dryRun) {
+        for (const file of generated) {
+            await mkdir(dirname(file.path), { recursive: true });
+            await writeFile(file.path, file.contents, "utf8");
+        }
+        if (envChanged)
+            await writeFile(envPath, envNext, "utf8");
+    }
+    say();
+    say(style(1, "Glyph Pay init"));
+    say();
+    for (const file of generated) {
+        const verb = existing.includes(display(file.path)) ? "Updated" : options.dryRun ? "Would create" : "Created";
+        say(`  ${verb} ${display(file.path)}`);
+    }
+    say(`  ${envChanged ? (options.dryRun ? "Would update" : "Updated") : "Unchanged"} .env.example`);
+    const pnpm = await fileExists(join(projectRoot, "pnpm-lock.yaml"));
+    const yarn = await fileExists(join(projectRoot, "yarn.lock"));
+    const bun = (await fileExists(join(projectRoot, "bun.lockb"))) || (await fileExists(join(projectRoot, "bun.lock")));
+    say();
+    say("Next steps:");
+    say(`  1. ${installCommand(pnpm, yarn, bun)}`);
+    say("  2. npx glyphpay connect --url https://your-site.com");
+    say(`  3. Wire priceOrder() and onEvent() in ${display(libPath)}.`);
+    if (options.dryRun) {
+        say();
+        say("Dry run: no files were written.");
+    }
+}
 /* ------------------------------------------------------------------ */
 /* Entry point                                                         */
 /* ------------------------------------------------------------------ */
@@ -388,6 +982,22 @@ export async function main(argv = process.argv.slice(2)) {
             say(VERSION);
             return 0;
         }
+        if (parsed.command === "doctor") {
+            const report = await runDoctor(parsed.options);
+            return report.ok ? 0 : 1;
+        }
+        if (parsed.command === "init") {
+            await runInit(parsed.options);
+            return 0;
+        }
+        if (parsed.command === "disconnect") {
+            await runDisconnect(parsed.options);
+            return 0;
+        }
+        if (parsed.command === "rotate") {
+            await runRotate(parsed.options);
+            return 0;
+        }
         await runConnect(parsed.options);
         return 0;
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "glyphpay",
-  "version": "0.2.0",
-  "description": "Drop-in GlyphPay checkout for websites, plus `glyphpay connect` for browser-based setup.",
+  "version": "0.3.0",
+  "description": "Drop-in GlyphPay checkout for websites, with a CLI for setup, diagnostics, and credential lifecycle.",
   "homepage": "https://glyphpay.net",
   "keywords": [
     "glyphpay",
@@ -14,7 +14,7 @@
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
-    "glyphpay": "./dist/cli.js"
+    "glyphpay": "dist/cli.js"
   },
   "files": [
     "dist"