glyphpay 0.3.0 → 0.5.0

package/README.md

@@ -1,165 +1,184 @@
-# glyphpay
-
-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 |
-
-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
-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_`.
-
-## 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.
-
-## 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
-```
+# glyphpay
+
+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 |
+
+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 deliveries` | Page/filter webhook deliveries and retry one with `--retry <id>`. |
+| `glyphpay init` | Scaffold routes for Next.js, Remix, Astro, SvelteKit, Hono, or Express. |
+
+## 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_`.
+
+## 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.
+
+## Inspect and retry webhook deliveries
+
+```sh
+npx glyphpay deliveries
+npx glyphpay deliveries --retry evt_...
+```
+
+`deliveries` pages through callback outbox records for the credential's client and environment: event type, delivery state, attempt count, timestamp, and the last error. Filter with `--state pending|delivered|failed`, control the page with `--limit 1..100`, and pass the returned `--cursor` for the next page. A retry sends the exact stored signed event again and persists the result. Retry is one attempt; fix the endpoint first. The admin **Connections** tab exposes the same filtering, pagination, and retry operations.
+
+## Scaffold a site
+
+```sh
+npx glyphpay init
+```
+
+The command detects the project framework from `package.json`. It creates a server connector plus the framework-native checkout and webhook entry points, and appends placeholders to `.env.example` without changing existing values. Supported targets:
+
+- **Next.js App Router** — `app/api/glyphpay/*` or `src/app/api/glyphpay/*` route handlers.
+- **SvelteKit** — `src/routes/api/glyphpay/*/+server.ts` with `src/lib/server/glyphpay.ts`.
+- **Astro** — `src/pages/api/glyphpay/*.ts`; use server/SSR output and an adapter.
+- **Remix** — `app/routes/api.glyphpay.*.ts` with `app/lib/glyphpay.server.ts`.
+- **Hono** — `src/glyphpay-routes.ts`; mount it with `app.route("/api/glyphpay", glyphpayRoutes)`.
+- **Express** — `src/glyphpay-routes.ts`; mount it with `app.use("/api/glyphpay", glyphpayRoutes)`. The webhook route uses `express.raw` so signatures verify against the original bytes.
+
+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.
+
+## 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, `glyphpay init` generates a small adapter that preserves the raw webhook body.
+
+## 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/cli.d.ts

@@ -9,7 +9,8 @@
  *
  * `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.
+ * it. `init` scaffolds a framework integration. `deliveries` lists callback
+ * attempts and replays one on demand.
  *
  * Zero runtime dependencies: Node 18+ built-ins and global fetch only.
  */
@@ -48,6 +49,14 @@ export interface CliOptions {
     dryRun?: boolean;
     /** Init: project directory. Defaults to the current directory. */
     dir?: string;
+    /** Deliveries: replay one failed or delivered callback by id. */
+    retry?: string;
+    /** Deliveries: filter by delivery state. */
+    state?: "pending" | "delivered" | "failed";
+    /** Deliveries: opaque next-page cursor returned by the API. */
+    cursor?: string;
+    /** Deliveries: page size, 1-100. */
+    limit?: number;
 }
 export interface ConnectResult {
     businessName: string;
@@ -61,7 +70,29 @@ export interface DisconnectResult {
     alreadyRevoked: boolean;
     canceled: boolean;
 }
-type Command = "connect" | "rotate" | "disconnect" | "doctor" | "init" | "help" | "version";
+export interface CallbackDeliveryView {
+    id: string;
+    paymentId: string;
+    type: string;
+    state: "pending" | "delivered" | "failed";
+    attempts: number;
+    lastError: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CallbackDeliveriesResponse {
+    businessId: string;
+    businessName: string;
+    environment: "test" | "live";
+    deliveries: CallbackDeliveryView[];
+    nextCursor: string | null;
+}
+export interface CallbackReplayResponse {
+    outcome: "delivered" | "retry" | "failed";
+    detail?: string;
+    delivery: CallbackDeliveryView;
+}
+type Command = "connect" | "rotate" | "disconnect" | "doctor" | "init" | "deliveries" | "help" | "version";
 interface ParsedCommand {
     command: Command;
     options: CliOptions;
@@ -107,6 +138,7 @@ export interface DoctorReport {
     checks: DoctorCheck[];
 }
 export declare function runDoctor(options?: CliOptions): Promise<DoctorReport>;
+export declare function runDeliveries(options?: CliOptions): Promise<CallbackDeliveriesResponse | CallbackReplayResponse>;
 export declare function runInit(options?: CliOptions): Promise<void>;
 export declare function main(argv?: string[]): Promise<number>;
 export {};

package/dist/cli.js

@@ -9,7 +9,8 @@
  *
  * `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.
+ * it. `init` scaffolds a framework integration. `deliveries` lists callback
+ * attempts and replays one on demand.
  *
  * Zero runtime dependencies: Node 18+ built-ins and global fetch only.
  */
@@ -19,7 +20,7 @@ import { access, chmod, mkdir, readFile, stat, writeFile } from "node:fs/promise
 import { dirname, join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { pathToFileURL } from "node:url";
-const VERSION = "0.3.0";
+const VERSION = "0.5.0";
 const DEFAULT_BASE_URL = "https://designglyph.web.app";
 const DEFAULT_ENV_FILE = ".env.local";
 const DEFAULT_TIMEOUT_SECONDS = 600;
@@ -72,6 +73,8 @@ function commandFor(value) {
         return "doctor";
     if (value === "init")
         return "init";
+    if (value === "deliveries" || value === "webhooks")
+        return "deliveries";
     return null;
 }
 export function parseArgs(argv) {
@@ -164,6 +167,53 @@ export function parseArgs(argv) {
             }
             continue;
         }
+        if (flag === "--retry") {
+            if (inlineValue !== undefined) {
+                if (!inlineValue)
+                    throw new CliUsageError("--retry needs a delivery id.");
+                options.retry = inlineValue;
+            }
+            else {
+                const [value, next] = takeValue(argv, index, flag);
+                options.retry = value;
+                index = next;
+            }
+            continue;
+        }
+        if (flag === "--state") {
+            const raw = inlineValue ?? takeValue(argv, index, flag)[0];
+            if (inlineValue === undefined)
+                index += 1;
+            if (raw !== "pending" && raw !== "delivered" && raw !== "failed") {
+                throw new CliUsageError("--state must be pending, delivered, or failed.");
+            }
+            options.state = raw;
+            continue;
+        }
+        if (flag === "--cursor") {
+            if (inlineValue !== undefined) {
+                if (!inlineValue)
+                    throw new CliUsageError("--cursor needs a value.");
+                options.cursor = inlineValue;
+            }
+            else {
+                const [value, next] = takeValue(argv, index, flag);
+                options.cursor = value;
+                index = next;
+            }
+            continue;
+        }
+        if (flag === "--limit") {
+            const raw = inlineValue ?? takeValue(argv, index, flag)[0];
+            if (inlineValue === undefined)
+                index += 1;
+            const parsed = Number(raw);
+            if (!Number.isInteger(parsed) || parsed < 1 || parsed > 100) {
+                throw new CliUsageError("--limit must be an integer between 1 and 100.");
+            }
+            options.limit = parsed;
+            continue;
+        }
         if (flag === "--dir") {
             if (inlineValue !== undefined) {
                 if (!inlineValue)
@@ -195,39 +245,47 @@ export function parseArgs(argv) {
     return { command, options };
 }
 export function helpText() {
-    return `glyphpay - take payments on your site through Glyph Pay
-
-Usage
-  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
-
-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})
-
-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
+    return `glyphpay - take payments on your site through Glyph Pay
+
+Usage
+  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 deliveries [options]    List recent webhook deliveries
+  glyphpay init [options]          Scaffold an integration for your framework
+  glyphpay --version
+
+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})
+
+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
+
+Deliveries
+  --state <state>          pending, delivered, or failed
+  --limit <n>              Page size, 1-100 (default: 50)
+  --cursor <cursor>        Next-page cursor from the previous response
+  --retry <id>             Send one stored webhook again (alias: webhooks)
+  --json                   Print a machine-readable response
+
+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.`;
 }
 /* ------------------------------------------------------------------ */
@@ -838,45 +896,245 @@ export async function runDoctor(options = {}) {
     }
     return report;
 }
+/* ------------------------------------------------------------------ */
+/* Webhook deliveries                                                  */
+/* ------------------------------------------------------------------ */
+function printDelivery(delivery) {
+    say(`  ${delivery.id}  ${delivery.type}  ${delivery.state.toUpperCase()}  ` +
+        `attempt ${delivery.attempts}  ${delivery.updatedAt}`);
+    if (delivery.lastError)
+        say(`    ${delivery.lastError}`);
+}
+export async function runDeliveries(options = {}) {
+    const baseUrl = baseUrlFor(options);
+    const envFile = resolve(options.envFile ?? DEFAULT_ENV_FILE);
+    const contents = await readEnvFile(envFile);
+    const token = readEnvValue(contents, TOKEN_KEY);
+    if (!token) {
+        throw new CliUsageError(`No ${TOKEN_KEY} found in ${relative(process.cwd(), envFile) || envFile}. Run glyphpay connect first.`);
+    }
+    if (options.retry) {
+        const result = await api(baseUrl, `/credential/deliveries/${encodeURIComponent(options.retry)}/replay`, {}, token);
+        if (options.json) {
+            say(JSON.stringify(result, null, 2));
+        }
+        else {
+            say();
+            say(style(1, `Webhook ${result.outcome === "delivered" ? "delivered" : "not delivered"}.`));
+            printDelivery(result.delivery);
+            if (result.detail)
+                say(`  ${result.detail}`);
+        }
+        return result;
+    }
+    const params = new URLSearchParams();
+    if (options.state)
+        params.set("state", options.state);
+    if (options.limit)
+        params.set("limit", String(options.limit));
+    if (options.cursor)
+        params.set("cursor", options.cursor);
+    const query = params.toString();
+    const result = await api(baseUrl, `/credential/deliveries${query ? `?${query}` : ""}`, undefined, token);
+    if (options.json) {
+        say(JSON.stringify(result, null, 2));
+        return result;
+    }
+    say();
+    say(style(1, `Webhook deliveries - ${result.businessName} (${result.environment} mode)`));
+    say();
+    if (result.deliveries.length === 0) {
+        say(options.state ? `No ${options.state} deliveries recorded.` : "No deliveries recorded yet.");
+    }
+    else {
+        for (const delivery of result.deliveries)
+            printDelivery(delivery);
+        say();
+        say("Retry one with `glyphpay deliveries --retry <id>`.");
+        if (result.nextCursor) {
+            const next = ["glyphpay deliveries"];
+            if (options.state)
+                next.push("--state", options.state);
+            if (options.limit)
+                next.push("--limit", String(options.limit));
+            next.push("--cursor", result.nextCursor);
+            say(`Next page: ${next.join(" ")}`);
+        }
+    }
+    return result;
+}
 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}\`);
-    }
-  },
-});
+    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 routeTemplate(libImport) {
+    return `import { glyphpay } from "${libImport}";\n\nexport const POST = glyphpay.checkout;\n`;
 }
-function webhookRouteTemplate() {
-    return `import { glyphpay } from "../../../../lib/glyphpay";
-
-export const POST = glyphpay.webhook;
-`;
+function webhookRouteTemplate(libImport) {
+    return `import { glyphpay } from "${libImport}";\n\nexport const POST = glyphpay.webhook;\n`;
+}
+function detectFramework(dependencies) {
+    if (dependencies.next)
+        return "next";
+    if (dependencies["@sveltejs/kit"])
+        return "sveltekit";
+    if (dependencies.astro)
+        return "astro";
+    if (dependencies["@remix-run/node"] || dependencies["@remix-run/react"])
+        return "remix";
+    if (dependencies.hono)
+        return "hono";
+    if (dependencies.express)
+        return "express";
+    return null;
+}
+function svelteRoute(kind, isTs) {
+    const typeImport = isTs ? `import type { RequestHandler } from "./$types";\n\n` : "\n";
+    const annotation = isTs ? ": RequestHandler" : "";
+    return `import { glyphpay } from "$lib/server/glyphpay";\n${typeImport}export const POST${annotation} = ({ request }) => glyphpay.${kind}(request);\n`;
+}
+function astroRoute(kind, isTs) {
+    const typeImport = isTs ? `import type { APIRoute } from "astro";\n\n` : "\n";
+    const annotation = isTs ? ": APIRoute" : "";
+    return `import { glyphpay } from "../../../lib/glyphpay";\n${typeImport}export const POST${annotation} = ({ request }) => glyphpay.${kind}(request);\n`;
+}
+function remixRoute(kind, isTs) {
+    const typeImport = isTs ? `import type { ActionFunctionArgs } from "@remix-run/node";\n\n` : "\n";
+    const signature = isTs ? "{ request }: ActionFunctionArgs" : "{ request }";
+    return `import { glyphpay } from "~/lib/glyphpay.server";\n${typeImport}export async function action(${signature}) {\n  return glyphpay.${kind}(request);\n}\n`;
+}
+function honoRoutes() {
+    return `import { Hono } from "hono";\nimport { glyphpay } from "./lib/glyphpay";\n\nexport const glyphpayRoutes = new Hono();\n\nglyphpayRoutes.post("/checkout", (c) => glyphpay.checkout(c.req.raw));\nglyphpayRoutes.post("/webhook", (c) => glyphpay.webhook(c.req.raw));\n`;
+}
+function expressRoutes(isTs) {
+    const typeImport = isTs
+        ? `import type { Request as ExpressRequest, Response as ExpressResponse } from "express";\n`
+        : "";
+    const signature = isTs ? ": ExpressRequest" : "";
+    const responseType = isTs ? ": ExpressResponse" : "";
+    const handlerType = isTs ? "(request: Request) => Promise<Response>" : "handler";
+    return `import express from "express";\nimport { glyphpay } from "./lib/glyphpay";\n${typeImport}\nexport const glyphpayRoutes = express.Router();\n\nasync function adapt(handler${isTs ? `: ${handlerType}` : ""}, req${signature}, res${responseType}) {\n  const body =\n    req.method === "GET" || req.method === "HEAD"\n      ? undefined\n      : Buffer.isBuffer(req.body)\n        ? req.body\n        : typeof req.body === "string"\n          ? req.body\n          : JSON.stringify(req.body ?? {});\n  const protocol = req.protocol || "http";\n  const host = req.get("host") || "localhost";\n  const request = new Request(\`\${protocol}://\${host}\${req.originalUrl}\`, {\n    method: req.method,\n    headers: req.headers as unknown as HeadersInit,\n    body,\n  });\n  const response = await handler(request);\n  res.status(response.status);\n  response.headers.forEach((value, key) => res.setHeader(key, value));\n  res.send(Buffer.from(await response.arrayBuffer()));\n}\n\nglyphpayRoutes.post("/checkout", express.json(), (req, res) => adapt(glyphpay.checkout, req, res));\nglyphpayRoutes.post("/webhook", express.raw({ type: "application/json" }), (req, res) => adapt(glyphpay.webhook, req, res));\n`;
+}
+async function frameworkPlan(projectRoot, framework) {
+    const isTs = await fileExists(join(projectRoot, "tsconfig.json"));
+    const extension = isTs ? "ts" : "js";
+    const envComment = "# Glyph Pay — server-side only. Keep these in the server environment.\n";
+    if (framework === "next") {
+        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 importPath = "../../../../lib/glyphpay";
+        return {
+            framework,
+            libPath: join(projectRoot, libDir, `glyphpay.${extension}`),
+            files: [
+                { path: join(projectRoot, libDir, `glyphpay.${extension}`), contents: libTemplate(isTs) },
+                { path: join(projectRoot, appDir, "api", "glyphpay", "checkout", `route.${extension}`), contents: routeTemplate(importPath) },
+                { path: join(projectRoot, appDir, "api", "glyphpay", "webhook", `route.${extension}`), contents: webhookRouteTemplate(importPath) },
+            ],
+            envComment,
+            notes: ["The generated routes live at /api/glyphpay/checkout and /api/glyphpay/webhook."],
+        };
+    }
+    if (framework === "sveltekit") {
+        const libPath = join(projectRoot, "src", "lib", "server", `glyphpay.${extension}`);
+        return {
+            framework,
+            libPath,
+            files: [
+                { path: libPath, contents: libTemplate(isTs) },
+                { path: join(projectRoot, "src", "routes", "api", "glyphpay", "checkout", `+server.${extension}`), contents: svelteRoute("checkout", isTs) },
+                { path: join(projectRoot, "src", "routes", "api", "glyphpay", "webhook", `+server.${extension}`), contents: svelteRoute("webhook", isTs) },
+            ],
+            envComment,
+            notes: ["Use adapter-node or another server adapter; static SvelteKit builds cannot run checkout."],
+        };
+    }
+    if (framework === "astro") {
+        const libPath = join(projectRoot, "src", "lib", `glyphpay.${extension}`);
+        return {
+            framework,
+            libPath,
+            files: [
+                { path: libPath, contents: libTemplate(isTs) },
+                { path: join(projectRoot, "src", "pages", "api", "glyphpay", `checkout.${extension}`), contents: astroRoute("checkout", isTs) },
+                { path: join(projectRoot, "src", "pages", "api", "glyphpay", `webhook.${extension}`), contents: astroRoute("webhook", isTs) },
+            ],
+            envComment,
+            notes: ["Set output to server/SSR in astro.config and install a server adapter before deploying."],
+        };
+    }
+    if (framework === "remix") {
+        const libPath = join(projectRoot, "app", "lib", `glyphpay.server.${extension}`);
+        return {
+            framework,
+            libPath,
+            files: [
+                { path: libPath, contents: libTemplate(isTs) },
+                { path: join(projectRoot, "app", "routes", `api.glyphpay.checkout.${extension}`), contents: remixRoute("checkout", isTs) },
+                { path: join(projectRoot, "app", "routes", `api.glyphpay.webhook.${extension}`), contents: remixRoute("webhook", isTs) },
+            ],
+            envComment,
+            notes: ["Routes assume the standard ~ alias; adjust the import if your tsconfig uses another alias."],
+        };
+    }
+    if (framework === "hono") {
+        const libPath = join(projectRoot, "src", "lib", `glyphpay.${extension}`);
+        return {
+            framework,
+            libPath,
+            files: [
+                { path: libPath, contents: libTemplate(isTs) },
+                { path: join(projectRoot, "src", `glyphpay-routes.${extension}`), contents: honoRoutes() },
+            ],
+            envComment,
+            notes: ["Mount the router in your app: app.route(\"/api/glyphpay\", glyphpayRoutes)."],
+        };
+    }
+    const libPath = join(projectRoot, "src", "lib", `glyphpay.${extension}`);
+    return {
+        framework: "express",
+        libPath,
+        files: [
+            { path: libPath, contents: libTemplate(isTs) },
+            { path: join(projectRoot, "src", `glyphpay-routes.${extension}`), contents: expressRoutes(isTs) },
+        ],
+        envComment,
+        notes: [
+            "Mount the router with app.use(\"/api/glyphpay\", glyphpayRoutes).",
+            "The webhook route uses express.raw so the signature is verified against the original bytes.",
+        ],
+    };
 }
 function installCommand(hasPnpmLock, hasYarnLock, hasBunLock) {
     if (hasPnpmLock)
@@ -891,7 +1149,7 @@ 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.`);
+        throw new CliUsageError(`No package.json found in ${projectRoot}. Run init in a web project.`);
     }
     let pkg;
     try {
@@ -901,29 +1159,13 @@ export async function runInit(options = {}) {
         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 framework = detectFramework(dependencies);
+    if (!framework) {
+        throw new CliUsageError("glyphpay init supports Next.js, Remix, Astro, SvelteKit, Express, and Hono. Install one of those frameworks first.");
+    }
+    const plan = await frameworkPlan(projectRoot, framework);
     const envPath = join(projectRoot, ".env.example");
-    const generated = [
-        { path: libPath, contents: libTemplate(isTs) },
-        { path: checkoutPath, contents: routeTemplate() },
-        { path: webhookPath, contents: webhookRouteTemplate() },
-    ];
+    const generated = plan.files;
     const existing = [];
     for (const file of generated) {
         if (await fileExists(file.path))
@@ -933,9 +1175,7 @@ export async function runInit(options = {}) {
         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 envBase = envExisting.trim().length > 0 ? envExisting : plan.envComment;
     const envNext = ensureEnvKeys(envBase, [TOKEN_KEY, CALLBACK_SECRET_KEY]);
     const envChanged = envNext !== envExisting;
     const display = (path) => relative(projectRoot, path).replace(/\\/g, "/");
@@ -949,6 +1189,7 @@ export async function runInit(options = {}) {
     }
     say();
     say(style(1, "Glyph Pay init"));
+    say(`Framework: ${plan.framework}`);
     say();
     for (const file of generated) {
         const verb = existing.includes(display(file.path)) ? "Updated" : options.dryRun ? "Would create" : "Created";
@@ -962,7 +1203,9 @@ export async function runInit(options = {}) {
     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)}.`);
+    say(`  3. Wire priceOrder() and onEvent() in ${display(plan.libPath)}.`);
+    for (const note of plan.notes)
+        say(`  ${note}`);
     if (options.dryRun) {
         say();
         say("Dry run: no files were written.");
@@ -990,6 +1233,10 @@ export async function main(argv = process.argv.slice(2)) {
             await runInit(parsed.options);
             return 0;
         }
+        if (parsed.command === "deliveries") {
+            const result = await runDeliveries(parsed.options);
+            return "outcome" in result && result.outcome !== "delivered" ? 1 : 0;
+        }
         if (parsed.command === "disconnect") {
             await runDisconnect(parsed.options);
             return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glyphpay",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Drop-in GlyphPay checkout for websites, with a CLI for setup, diagnostics, and credential lifecycle.",
   "homepage": "https://glyphpay.net",
   "keywords": [