glyphpay 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# glyphpay
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Drop-in connector that lets a website take payments through [GlyphPay](https://glyphpay.net) by Design Glyph. Payments go to the site owner's own Stripe connected account.
+
+| Import | Runs on | What it gives you |
+| --- | --- | --- |
+| `glyphpay/server` | Site's server | `glyphPay()`: `checkout` and `webhook` route handlers, plus `createPayment`, `getPayment`, `refund`, `reconcile` |
+| `glyphpay/react` | Browser | `<GlyphPayCheckout />` |
+| `glyphpay/browser` | Browser, any site | `mountCheckout(el, options)` for sites without React |
+
+## 1. Connect the client in Design Glyph admin
+
+1. **Admin → Clients → (client)**: make sure Stripe onboarding is complete (charges enabled).
+2. **Issue a service credential** (test first). Copy the `dgsvc_test_…` token. It is shown only once.
+3. **Set the callback URL** to `https://<client-site>/api/glyphpay/webhook`. Copy the signing secret. It is also shown only once.
+
+## 2. Add to the client site
+
+```sh
+pnpm add glyphpay
+```
+
+`.env` (server only, never `NEXT_PUBLIC_`):
+
+```sh
+GLYPHPAY_TOKEN=dgsvc_test_...
+GLYPHPAY_CALLBACK_SECRET=...
+```
+
+`lib/glyphpay.ts`
+
+```ts
+import { glyphPay, CheckoutError } from "glyphpay/server";
+
+export const glyphpay = glyphPay({
+  token: process.env.GLYPHPAY_TOKEN,
+  callbackSecret: process.env.GLYPHPAY_CALLBACK_SECRET,
+
+  // Price the order from YOUR data. Never trust an amount sent by the browser.
+  async priceOrder(body) {
+    const cart = await db.carts.get((body as { cartId: string }).cartId);
+    if (!cart?.items.length) throw new CheckoutError("Your cart is empty.");
+    // orderId must change whenever the total changes, or GlyphPay returns 409.
+    return { orderId: `${cart.id}-v${cart.version}`, amountCents: cart.totalCents, description: `Order ${cart.id}` };
+  },
+
+  // Signed and verified. At-least-once delivery: dedupe on event.id. Throw to have it retried.
+  async onEvent(event) {
+    if (event.type === "payment.succeeded") await db.orders.markPaid(event.data.orderId, event.id);
+  },
+});
+```
+
+`app/api/glyphpay/checkout/route.ts`
+
+```ts
+import { glyphpay } from "@/lib/glyphpay";
+export const POST = glyphpay.checkout;
+```
+
+`app/api/glyphpay/webhook/route.ts`
+
+```ts
+import { glyphpay } from "@/lib/glyphpay";
+export const POST = glyphpay.webhook;
+```
+
+Checkout page:
+
+```tsx
+import { GlyphPayCheckout } from "glyphpay/react";
+
+<GlyphPayCheckout order={{ cartId }} returnUrl={`/thank-you?cart=${cartId}`} appearance={{ theme: "stripe" }} />
+```
+
+Style the button with `.glyphpay button { … }`. Errors appear in `.glyphpay [role=alert]`.
+
+Without React:
+
+```html
+<div id="pay"></div>
+<script type="module">
+  import { mountCheckout } from "glyphpay/browser";
+  mountCheckout(document.getElementById("pay"), { order: { cartId: "42" }, returnUrl: "/thank-you" });
+</script>
+```
+
+The route handlers take a standard `Request` and return a `Response`, so the same two lines work in Remix, Astro, Hono, SvelteKit, and Cloudflare Workers. In Express, use `createPayment` and `verifyCallback` directly.
+
+## How a payment flows
+
+1. The component POSTs `order` to `/api/glyphpay/checkout`. `priceOrder` sets the amount, and the site's server calls GlyphPay with the token.
+2. The browser gets back only `clientSecret`, `publishableKey`, and `stripeAccount`, then mounts Stripe's Payment Element.
+3. The shopper pays, and Stripe redirects to `returnUrl`. **The redirect doesn't prove payment.**
+4. GlyphPay POSTs `payment.succeeded` to `/api/glyphpay/webhook`, and `onEvent` marks the order paid. The thank-you page reads the order status from your database, or calls `glyphpay.getPayment(paymentId)`.
+
+Refunds run server-side:
+
+```ts
+await glyphpay.refund(paymentId, { idempotencyKey: `${orderId}-refund-1` });
+```
+
+## Develop
+
+```sh
+cd packages/glyphpay && npm install && npm test
+```

package/dist/browser.d.ts

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

package/dist/browser.js

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

package/dist/react.d.ts

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

package/dist/react.js

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

package/dist/server.d.ts

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

package/dist/server.js

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

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "glyphpay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Drop-in GlyphPay checkout for websites: server route handlers plus a React or plain-JS payment form.",
+  "homepage": "https://glyphpay.net",
+  "keywords": ["glyphpay", "payments", "checkout", "stripe", "react", "nextjs"],
+  "license": "UNLICENSED",
+  "type": "module",
+  "files": ["dist"],
+  "exports": {
+    "./server": { "types": "./dist/server.d.ts", "default": "./dist/server.js" },
+    "./browser": { "types": "./dist/browser.d.ts", "default": "./dist/browser.js" },
+    "./react": { "types": "./dist/react.d.ts", "default": "./dist/react.js" }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "tsc && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@stripe/stripe-js": "^10.2.1"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "typescript": "^5"
+  }
+}