@benclmnt/postmock 0.0.1

package/dist/src/events.d.ts

@@ -0,0 +1,49 @@
+import type { Bounce, ClickEvent, InboundMessage, OpenEvent, OutboundMessage, SubscriptionChange } from "./state/types.ts";
+/** Domain events (docs/11 §2). Webhooks, stats and message events subscribe to them. */
+export interface EventMap {
+    /** A message was accepted for delivery. */
+    sent: {
+        message: OutboundMessage;
+    };
+    delivered: {
+        message: OutboundMessage;
+        recipient: string;
+        deliveredAt: Date;
+        details: string;
+    };
+    bounced: {
+        bounce: Bounce;
+    };
+    opened: {
+        open: OpenEvent;
+    };
+    clicked: {
+        click: ClickEvent;
+    };
+    spamComplaint: {
+        bounce: Bounce;
+    };
+    subscriptionChange: {
+        change: SubscriptionChange;
+    };
+    inboundReceived: {
+        message: InboundMessage;
+    };
+    /** An SMTP message failed validation after DATA (docs/07 §1.4). */
+    smtpApiError: {
+        bounce: Bounce;
+    };
+}
+export type EventName = keyof EventMap;
+type Listener<K extends EventName> = (payload: EventMap[K]) => void | Promise<void>;
+/**
+ * `emit` awaits each listener in subscription order, so a request or control call that emits returns
+ * after every listener finished. A listener that needs later work (a webhook retry) schedules it on
+ * the clock. A listener that throws fails the emitter (AGENTS.md rule 5).
+ */
+export declare class EventBus {
+    private listeners;
+    on<K extends EventName>(name: K, listener: Listener<K>): () => void;
+    emit<K extends EventName>(name: K, payload: EventMap[K]): Promise<void>;
+}
+export {};

package/dist/src/events.js

@@ -0,0 +1,19 @@
+/**
+ * `emit` awaits each listener in subscription order, so a request or control call that emits returns
+ * after every listener finished. A listener that needs later work (a webhook retry) schedules it on
+ * the clock. A listener that throws fails the emitter (AGENTS.md rule 5).
+ */
+export class EventBus {
+    listeners = {};
+    on(name, listener) {
+        const set = this.listeners[name] ?? new Set();
+        this.listeners[name] = set;
+        set.add(listener);
+        return () => set.delete(listener);
+    }
+    async emit(name, payload) {
+        for (const listener of [...(this.listeners[name] ?? [])]) {
+            await listener(payload);
+        }
+    }
+}

package/dist/src/http/app.d.ts

@@ -0,0 +1,8 @@
+import type { HttpBindings } from "@hono/node-server";
+import { Hono } from "hono";
+import "../api/index.ts";
+import type { Runtime } from "../runtime.ts";
+/** The Postmark REST API on any host and port, at the root path (docs/08 R1). */
+export declare function createApiApp(runtime: Runtime): Hono<{
+    Bindings: HttpBindings;
+}>;

package/dist/src/http/app.js

@@ -0,0 +1,51 @@
+import { Hono } from "hono";
+import "../api/index.js";
+import { ApiError } from "../errors.js";
+import { authenticate } from "./auth.js";
+import { applyFault } from "./faults.js";
+import { decodeJsonBody, Query } from "./normalize.js";
+import { errorResponse, jsonResponse, textResponse, Unsupported } from "./respond.js";
+import { apiRoutes } from "./routes.js";
+/** The Postmark REST API on any host and port, at the root path (docs/08 R1). */
+export function createApiApp(runtime) {
+    const app = new Hono();
+    app.all("*", async (c) => {
+        const request = c.req.raw;
+        const url = new URL(request.url);
+        const fault = await applyFault(runtime.store.state, request.method, url.pathname, c.env);
+        if (fault)
+            return fault;
+        const matched = apiRoutes.match(request.method, url.pathname);
+        // The body of an unknown route is not captured (docs/02 §9 Q9).
+        if (!matched)
+            return textResponse(404, `postmock: no route for ${request.method} ${url.pathname}`);
+        const { route, params } = matched;
+        try {
+            const auth = authenticate(route.auth, request.headers, runtime.store.state, `${route.method} ${route.path}`, runtime.clock.now());
+            const body = decodeJsonBody(await request.arrayBuffer());
+            const result = await route.handler({
+                ...runtime,
+                method: route.method,
+                params,
+                query: new Query(url.searchParams),
+                body,
+                headers: request.headers,
+                auth,
+            });
+            return jsonResponse(result);
+        }
+        catch (error) {
+            if (error instanceof ApiError)
+                return errorResponse(error);
+            if (error instanceof Unsupported)
+                return textResponse(501, `postmock: ${error.message}`);
+            throw error;
+        }
+    });
+    // A bug in postmock: a loud 500 that no Postmark client mistakes for a Postmark envelope.
+    app.onError((error) => {
+        console.error(error);
+        return textResponse(500, `postmock crashed: ${error.stack ?? error.message}`);
+    });
+    return app;
+}

package/dist/src/http/auth.d.ts

@@ -0,0 +1,7 @@
+import type { State } from "../state/store.ts";
+import type { AuthRequirement, AuthResult } from "./routes.ts";
+/**
+ * Checks the token header the route needs. A missing, unknown or wrong-type token is HTTP 401,
+ * ErrorCode 10 (docs/02 §3.4). The other token header is ignored.
+ */
+export declare function authenticate<A extends AuthRequirement>(requirement: A, headers: Headers, state: State, routeName: string, now: Date): AuthResult[A];

package/dist/src/http/auth.js

@@ -0,0 +1,32 @@
+import { apiError } from "../errors.js";
+import { TEST_TOKEN, testTokenContext } from "../state/servers.js";
+import { Unsupported } from "./respond.js";
+// "The header name and value are case insensitive." refs/api_overview.md:21 (docs/02 §3.1).
+const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+/**
+ * Checks the token header the route needs. A missing, unknown or wrong-type token is HTTP 401,
+ * ErrorCode 10 (docs/02 §3.4). The other token header is ignored.
+ */
+export function authenticate(requirement, headers, state, routeName, now) {
+    if (requirement === "account") {
+        const token = headers.get("X-Postmark-Account-Token");
+        if (token !== null && state.account.tokens.some((t) => same(t, token))) {
+            return { kind: "account" };
+        }
+        throw apiError(10);
+    }
+    const token = headers.get("X-Postmark-Server-Token");
+    if (token === null)
+        throw apiError(10);
+    if (same(token, TEST_TOKEN)) {
+        if (requirement === "serverOrTest")
+            return testTokenContext(now);
+        throw new Unsupported(`${TEST_TOKEN} on ${routeName}: behavior not captured (docs/02 §9 Q8)`);
+    }
+    for (const server of state.servers.values()) {
+        if (server.ApiTokens.some((t) => same(t, token))) {
+            return { kind: "server", server };
+        }
+    }
+    throw apiError(10);
+}

package/dist/src/http/faults.d.ts

@@ -0,0 +1,8 @@
+import type { HttpBindings } from "@hono/node-server";
+import type { State } from "../state/store.ts";
+/**
+ * Applies the first fault that matches the request and uses one of its `times`
+ * (docs/09 §5 `POST /control/faults`). `timeout` holds the request open until the client gives up;
+ * `reset` destroys the socket.
+ */
+export declare function applyFault(state: State, method: string, pathname: string, env: HttpBindings): Promise<Response | undefined>;

package/dist/src/http/faults.js

@@ -0,0 +1,33 @@
+import { ApiError } from "../errors.js";
+import { errorResponse } from "./respond.js";
+import { RouteTable } from "./routes.js";
+/**
+ * Applies the first fault that matches the request and uses one of its `times`
+ * (docs/09 §5 `POST /control/faults`). `timeout` holds the request open until the client gives up;
+ * `reset` destroys the socket.
+ */
+export async function applyFault(state, method, pathname, env) {
+    const fault = state.faults.find((f) => {
+        if (f.remaining <= 0)
+            return false;
+        const table = new RouteTable();
+        table.add({ method: f.method.toUpperCase(), path: f.path });
+        return table.match(method, pathname) !== undefined;
+    });
+    if (!fault)
+        return undefined;
+    fault.remaining -= 1;
+    return reply(fault, env);
+}
+async function reply(fault, env) {
+    const { reply } = fault;
+    if (reply === "reset") {
+        env.incoming.socket.destroy();
+        return new Response(null, { status: 499 });
+    }
+    if (reply === "timeout") {
+        await new Promise((resolve) => env.incoming.socket.once("close", resolve));
+        return new Response(null, { status: 499 });
+    }
+    return errorResponse(new ApiError(reply.status, reply.body));
+}

package/dist/src/http/normalize.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+export declare class Query {
+    private readonly values;
+    private readonly raw;
+    constructor(params: URLSearchParams);
+    /** The last value for `name`. */
+    get(name: string): string | undefined;
+    /** Every value for `name`: postmark.js repeats a key for an array (docs/02 §2.6). */
+    all(name: string): string[];
+    /** `metadata_<key>=value` pairs, prefix matched without case, key case kept (docs/08 R3). */
+    prefixed(prefix: string): Record<string, string>;
+    /** Parses the schema's keys (each read with `get`) with the schema. */
+    pick<S extends z.ZodObject>(schema: S): z.ZodSafeParseResult<z.output<S>>;
+}
+/** `true`/`True`/`1` and the false forms (docs/08 R4). */
+export declare const queryBool: z.ZodPipe<z.ZodString, z.ZodTransform<boolean, string>>;
+export declare const queryInt: z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>;
+export interface QueryDate {
+    instant: Date;
+    /** True for `YYYY-MM-DD`; an inclusive `todate` then covers the whole day. */
+    dateOnly: boolean;
+}
+/**
+ * `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS`, and `...SS.fffffff` (docs/08 R5). Month and day may have one
+ * digit: the postmark.js live stats test sends `2026-9-7`. A zoneless value is US
+ * Eastern time (docs/02 §7.1). postmark.js sends `Date#toISOString()`, which carries `Z`.
+ */
+export declare function parseQueryDate(value: string): QueryDate | undefined;
+/**
+ * The exclusive end of an inclusive `todate`: the next Eastern midnight for a date-only value,
+ * else the instant plus 1 ms.
+ */
+export declare function inclusiveUpperBound({ instant, dateOnly }: QueryDate): Date;
+export declare const queryDate: z.ZodPipe<z.ZodString, z.ZodTransform<QueryDate, string>>;
+/**
+ * The request body as JSON. Bytes decode as UTF-8 whatever the charset (docs/08 R13).
+ * Empty, whitespace or the literal `null` is absent, with or without Content-Type (docs/08 R7).
+ * Malformed JSON is ErrorCode 402 (docs/02 §7).
+ */
+export declare function decodeJsonBody(bytes: ArrayBuffer): unknown;
+/**
+ * Renames body keys to the schema's spelling, matched without case, at every object level the
+ * schema describes: `HTMLBody`, `htmlBody` → `HtmlBody`; `ReturnPathDOmain` → `ReturnPathDomain`
+ * (docs/08 R8). Record keys (Metadata) keep their case. Unknown keys pass through; zod strips them
+ * (docs/08 R12).
+ */
+export declare function canonicalizeKeys(schema: unknown, value: unknown): unknown;
+/** Parses a JSON body with key case folding (docs/08 R8). The route maps issues to ErrorCodes. */
+export declare function parseBody<S extends z.ZodType>(schema: S, body: unknown): z.ZodSafeParseResult<z.output<S>>;
+/** An optional scalar where `null` and `""` mean absent (docs/08 R9). */
+export declare const absent: <S extends z.ZodType>(schema: S) => z.ZodPreprocess<z.ZodOptional<S>, unknown>;
+/** An integer sent as a number or a numeric string (docs/08 R10: cli `TemplateId`, py server IDs). */
+export declare const intLike: z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>;
+/** An object that PHP serializes as `[]` when empty (docs/08 R10: `TemplateModel: []`). */
+export declare const objectOrEmptyArray: <S extends z.ZodType>(schema: S) => z.ZodPreprocess<S, unknown>;
+/** Base64 content; line breaks inside are allowed (docs/08 R11: the gem wraps every 60 chars). */
+export declare const base64: z.ZodPipe<z.ZodString, z.ZodTransform<Buffer<ArrayBuffer>, string>>;

package/dist/src/http/normalize.js

@@ -0,0 +1,225 @@
+import { z } from "zod";
+import { apiError } from "../errors.js";
+import { easternWallTime, formatEasternDate } from "../time.js";
+import { Unsupported } from "./respond.js";
+// Request normalization: the accept rules of docs/08 §4.1. SDKs disagree on key case,
+// boolean text and date shapes, so the server accepts every form an official SDK sends.
+// Query names match without case and without underscores: SDKs send `fromEmail`, `fromemail`,
+// `clientName` for the doc's `client_name` (docs/08 R3; docs/06 §1.1, INFERRED).
+const foldQueryKey = (key) => key.toLowerCase().replaceAll("_", "");
+export class Query {
+    values = new Map();
+    raw;
+    constructor(params) {
+        this.raw = params;
+        for (const [key, value] of params) {
+            // An empty `key=` is absent (docs/08 R4; gem and dotnet send them).
+            if (value === "")
+                continue;
+            const folded = foldQueryKey(key);
+            this.values.set(folded, [...(this.values.get(folded) ?? []), value]);
+        }
+    }
+    /** The last value for `name`. */
+    get(name) {
+        return this.values.get(foldQueryKey(name))?.at(-1);
+    }
+    /** Every value for `name`: postmark.js repeats a key for an array (docs/02 §2.6). */
+    all(name) {
+        return this.values.get(foldQueryKey(name)) ?? [];
+    }
+    /** `metadata_<key>=value` pairs, prefix matched without case, key case kept (docs/08 R3). */
+    prefixed(prefix) {
+        const out = {};
+        for (const [key, value] of this.raw) {
+            if (value !== "" && key.toLowerCase().startsWith(prefix.toLowerCase())) {
+                out[key.slice(prefix.length)] = value;
+            }
+        }
+        return out;
+    }
+    /** Parses the schema's keys (each read with `get`) with the schema. */
+    pick(schema) {
+        const input = {};
+        for (const key of Object.keys(schema.shape)) {
+            const value = this.get(key);
+            if (value !== undefined)
+                input[key] = value;
+        }
+        return schema.safeParse(input);
+    }
+}
+/** `true`/`True`/`1` and the false forms (docs/08 R4). */
+export const queryBool = z.string().transform((value, ctx) => {
+    const lower = value.toLowerCase();
+    if (lower === "true" || lower === "1")
+        return true;
+    if (lower === "false" || lower === "0")
+        return false;
+    ctx.issues.push({ code: "custom", message: `not a boolean: ${value}`, input: value });
+    return z.NEVER;
+});
+export const queryInt = z
+    .string()
+    .regex(/^-?\d+$/)
+    .transform(Number);
+const DATE_RE = /^(\d{4})-(\d{1,2})-(\d{1,2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,7}))?)? ?(Z|[+-]\d{2}:?\d{2})?)?$/;
+/**
+ * `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS`, and `...SS.fffffff` (docs/08 R5). Month and day may have one
+ * digit: the postmark.js live stats test sends `2026-9-7`. A zoneless value is US
+ * Eastern time (docs/02 §7.1). postmark.js sends `Date#toISOString()`, which carries `Z`.
+ */
+export function parseQueryDate(value) {
+    const m = DATE_RE.exec(value);
+    if (!m)
+        return undefined;
+    const [, y, mo, d, h, mi, s, frac, zone] = m;
+    const n = (x) => Number(x ?? 0);
+    // Date.UTC rolls 2024-13-45 over into 2025; a field out of range is no date.
+    const probe = new Date(Date.UTC(n(y), n(mo) - 1, n(d), n(h), n(mi), n(s)));
+    if (probe.getUTCFullYear() !== n(y) ||
+        probe.getUTCMonth() !== n(mo) - 1 ||
+        probe.getUTCDate() !== n(d) ||
+        probe.getUTCHours() !== n(h) ||
+        probe.getUTCMinutes() !== n(mi) ||
+        probe.getUTCSeconds() !== n(s)) {
+        return undefined;
+    }
+    const ms = Math.floor(Number(`0.${frac ?? 0}`) * 1000);
+    if (h === undefined)
+        return { instant: easternWallTime(n(y), n(mo), n(d)), dateOnly: true };
+    if (zone === undefined) {
+        return { instant: easternWallTime(n(y), n(mo), n(d), n(h), n(mi), n(s), ms), dateOnly: false };
+    }
+    const utc = Date.UTC(n(y), n(mo) - 1, n(d), n(h), n(mi), n(s), ms);
+    const [zoneHours, zoneMinutes] = [Number(zone.slice(1, 3)), Number(zone.slice(-2))];
+    if (zone !== "Z" && (zoneHours > 14 || zoneMinutes > 59))
+        return undefined;
+    const offset = zone === "Z" ? 0 : (zone.startsWith("-") ? -1 : 1) * (zoneHours * 60 + zoneMinutes);
+    return { instant: new Date(utc - offset * 60000), dateOnly: false };
+}
+/**
+ * The exclusive end of an inclusive `todate`: the next Eastern midnight for a date-only value,
+ * else the instant plus 1 ms.
+ */
+export function inclusiveUpperBound({ instant, dateOnly }) {
+    if (!dateOnly)
+        return new Date(instant.getTime() + 1);
+    // 30 h past a midnight is inside the next day on 23 h and 25 h DST days.
+    const [y, m, d] = formatEasternDate(new Date(instant.getTime() + 30 * 3600_000))
+        .split("-")
+        .map(Number);
+    return easternWallTime(y, m, d);
+}
+export const queryDate = z.string().transform((value, ctx) => {
+    const parsed = parseQueryDate(value);
+    if (parsed)
+        return parsed;
+    ctx.issues.push({ code: "custom", message: `not a date: ${value}`, input: value });
+    return z.NEVER;
+});
+/**
+ * The request body as JSON. Bytes decode as UTF-8 whatever the charset (docs/08 R13).
+ * Empty, whitespace or the literal `null` is absent, with or without Content-Type (docs/08 R7).
+ * Malformed JSON is ErrorCode 402 (docs/02 §7).
+ */
+export function decodeJsonBody(bytes) {
+    const text = new TextDecoder("utf-8").decode(bytes).trim();
+    if (text === "")
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw apiError(402);
+    }
+    return value === null ? undefined : value;
+}
+const defOf = (schema) => schema._zod.def;
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * Renames body keys to the schema's spelling, matched without case, at every object level the
+ * schema describes: `HTMLBody`, `htmlBody` → `HtmlBody`; `ReturnPathDOmain` → `ReturnPathDomain`
+ * (docs/08 R8). Record keys (Metadata) keep their case. Unknown keys pass through; zod strips them
+ * (docs/08 R12).
+ */
+export function canonicalizeKeys(schema, value) {
+    const def = defOf(schema);
+    switch (def.type) {
+        case "object": {
+            if (!isPlainObject(value))
+                return value;
+            const shape = def.shape;
+            const byFolded = new Map(Object.keys(shape).map((k) => [k.toLowerCase(), k]));
+            const out = {};
+            for (const [key, item] of Object.entries(value)) {
+                const canonical = byFolded.get(key.toLowerCase());
+                const target = canonical ?? key;
+                // Postmark's answer is not captured; answer 501, not a guess (AGENTS.md rule 5).
+                if (target in out)
+                    throw new Unsupported(`body has two spellings of key '${target}'`);
+                out[target] = canonical === undefined ? item : canonicalizeKeys(shape[canonical], item);
+            }
+            return out;
+        }
+        case "array":
+            return Array.isArray(value) ? value.map((v) => canonicalizeKeys(def.element, v)) : value;
+        case "record":
+            return isPlainObject(value)
+                ? Object.fromEntries(Object.entries(value).map(([k, v]) => [k, canonicalizeKeys(def.valueType, v)]))
+                : value;
+        case "optional":
+        case "nullable":
+        case "default":
+        case "prefault":
+        case "readonly":
+        case "catch":
+        case "nonoptional":
+            return canonicalizeKeys(def.innerType, value);
+        case "pipe":
+            return canonicalizeKeys(defOf(def.in).type === "transform" ? def.out : def.in, value);
+        case "union":
+            return def.options.reduce((v, option) => canonicalizeKeys(option, v), value);
+        case "intersection":
+            return canonicalizeKeys(def.right, canonicalizeKeys(def.left, value));
+        case "tuple": {
+            if (!Array.isArray(value))
+                return value;
+            const items = def.items;
+            return value.map((v, i) => {
+                const item = i < items.length ? items[i] : def.rest;
+                return item === undefined || item === null ? v : canonicalizeKeys(item, v);
+            });
+        }
+        case "lazy":
+            return canonicalizeKeys(def.getter(), value);
+        default:
+            return value;
+    }
+}
+/** Parses a JSON body with key case folding (docs/08 R8). The route maps issues to ErrorCodes. */
+export function parseBody(schema, body) {
+    return schema.safeParse(canonicalizeKeys(schema, body));
+}
+/** An optional scalar where `null` and `""` mean absent (docs/08 R9). */
+export const absent = (schema) => z.preprocess((v) => (v === null || v === "" ? undefined : v), schema.optional());
+/** An integer sent as a number or a numeric string (docs/08 R10: cli `TemplateId`, py server IDs). */
+export const intLike = z.union([
+    z.number().int(),
+    z
+        .string()
+        .regex(/^-?\d+$/)
+        .transform(Number),
+]);
+/** An object that PHP serializes as `[]` when empty (docs/08 R10: `TemplateModel: []`). */
+export const objectOrEmptyArray = (schema) => z.preprocess((v) => (Array.isArray(v) && v.length === 0 ? {} : v), schema);
+/** Base64 content; line breaks inside are allowed (docs/08 R11: the gem wraps every 60 chars). */
+export const base64 = z.string().transform((value, ctx) => {
+    const compact = value.replace(/\s+/g, "");
+    if (/^[A-Za-z0-9+/]*={0,2}$/.test(compact) && compact.length % 4 === 0) {
+        return Buffer.from(compact, "base64");
+    }
+    ctx.issues.push({ code: "custom", message: "not base64", input: value });
+    return z.NEVER;
+});

package/dist/src/http/respond.d.ts

@@ -0,0 +1,23 @@
+import type { ApiError } from "../errors.ts";
+/**
+ * Behavior postmock does not know yet (an uncaptured response, an unbuilt route).
+ * Answers 501 with a plain-text reason, so a test fails loudly instead of learning a guess
+ * (AGENTS.md rule 5).
+ */
+export declare class Unsupported extends Error {
+}
+/**
+ * Serializes JSON. Refuses `undefined` (no JSON body: an empty 200 breaks php, gem, java and dotnet,
+ * docs/08 §1.5) and a raw Date (each surface formats its own dates, docs/02 §7.1).
+ */
+export declare function toJson(body: unknown): string;
+/** Every success is HTTP 200 with a JSON body (docs/08 E1, E2). */
+export declare const jsonResponse: (body: unknown) => Response;
+/** `{ErrorCode, Message}` with `X-PM-ApiErrorCode` (docs/02 §4.1; docs/08 E3). */
+export declare const errorResponse: (error: ApiError) => Response;
+export declare const textResponse: (status: number, text: string) => Response;
+/**
+ * A list page with its wrapper key and `TotalCount`, both present when empty. `TotalCount` counts
+ * every match, not the page (docs/08 E9).
+ */
+export declare function paged<T>(key: string, items: readonly T[], count: number, offset: number): Record<string, unknown>;

package/dist/src/http/respond.js

@@ -0,0 +1,37 @@
+/**
+ * Behavior postmock does not know yet (an uncaptured response, an unbuilt route).
+ * Answers 501 with a plain-text reason, so a test fails loudly instead of learning a guess
+ * (AGENTS.md rule 5).
+ */
+export class Unsupported extends Error {
+}
+// docs/02 §4.1 example: `Content-Type: application/json`; charset pending capture Q4.
+const JSON_TYPE = "application/json";
+/**
+ * Serializes JSON. Refuses `undefined` (no JSON body: an empty 200 breaks php, gem, java and dotnet,
+ * docs/08 §1.5) and a raw Date (each surface formats its own dates, docs/02 §7.1).
+ */
+export function toJson(body) {
+    if (body === undefined)
+        throw new Error("response body is undefined");
+    return JSON.stringify(body, function (key, value) {
+        if (this[key] instanceof Date)
+            throw new Error(`unformatted Date at key '${key}'`);
+        return value;
+    });
+}
+/** Every success is HTTP 200 with a JSON body (docs/08 E1, E2). */
+export const jsonResponse = (body) => new Response(toJson(body), { status: 200, headers: { "Content-Type": JSON_TYPE } });
+/** `{ErrorCode, Message}` with `X-PM-ApiErrorCode` (docs/02 §4.1; docs/08 E3). */
+export const errorResponse = (error) => new Response(toJson(error.body), {
+    status: error.status,
+    headers: { "Content-Type": JSON_TYPE, "X-PM-ApiErrorCode": String(error.body.ErrorCode) },
+});
+export const textResponse = (status, text) => new Response(text, { status, headers: { "Content-Type": "text/plain; charset=utf-8" } });
+/**
+ * A list page with its wrapper key and `TotalCount`, both present when empty. `TotalCount` counts
+ * every match, not the page (docs/08 E9).
+ */
+export function paged(key, items, count, offset) {
+    return { TotalCount: items.length, [key]: items.slice(offset, offset + count) };
+}

package/dist/src/http/routes.d.ts

@@ -0,0 +1,60 @@
+import type { Runtime } from "../runtime.ts";
+import type { TestTokenContext } from "../state/servers.ts";
+import type { Server } from "../state/types.ts";
+import type { Query } from "./normalize.ts";
+export type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Method + path patterns (`/templates/:idOrAlias`). Literal segments match without case and a
+ * trailing slash is ignored (docs/08 R2). A literal beats a param at the same position, so
+ * `PUT /templates/push` wins over `PUT /templates/:idOrAlias` (docs/08 §2.5).
+ */
+export declare class RouteTable<R extends {
+    method: Method;
+    path: string;
+}> {
+    private readonly entries;
+    add(route: R): void;
+    match(method: string, pathname: string): {
+        route: R;
+        params: Record<string, string>;
+    } | undefined;
+}
+/**
+ * - `server`: a server token; `POSTMARK_API_TEST` answers 501 until its behavior there is known.
+ * - `serverOrTest`: a server token or `POSTMARK_API_TEST` (docs/02 §3.3), which gets a
+ *   `TestTokenContext`.
+ * - `account`: an account token.
+ */
+export type AuthRequirement = "server" | "serverOrTest" | "account";
+export type ServerAuth = {
+    kind: "server";
+    server: Server;
+};
+export type AuthResult = {
+    server: ServerAuth;
+    serverOrTest: ServerAuth | TestTokenContext;
+    account: {
+        kind: "account";
+    };
+};
+export interface RequestContext extends Runtime {
+    method: Method;
+    /** Raw path params, URL-decoded, case kept. */
+    params: Record<string, string>;
+    query: Query;
+    /** Parsed JSON body; `undefined` when empty or the literal `null` (docs/08 R7). */
+    body: unknown;
+    headers: Headers;
+}
+export interface ApiRoute<A extends AuthRequirement = AuthRequirement> {
+    method: Method;
+    path: string;
+    auth: A;
+    /** Returns the JSON body of a 200 response (docs/08 E1). Throws `ApiError` for an error. */
+    handler: (ctx: RequestContext & {
+        auth: AuthResult[A];
+    }) => unknown;
+}
+export declare const apiRoutes: RouteTable<ApiRoute<AuthRequirement>>;
+/** Registers a Postmark API route. Each `src/api/<group>/routes.ts` calls it at import. */
+export declare function defineRoute<A extends AuthRequirement>(route: ApiRoute<A>): void;