@benclmnt/postmock 0.0.1

package/dist/src/state/types.js

@@ -0,0 +1,41 @@
+// Entities for the whole surface (docs/03–07).
+// PascalCase fields carry a wire field of the same name; its value is formatted at the edge
+// (a `Date` becomes the docs/02 §7.1 shape). camelCase fields are postmock-internal.
+// `null` means "not set"; each API group decides whether the wire omits the key or sends null.
+// Lowercase on the wire: the SDK live tests send `red` and read back `red`
+// (sdk/postmark.js/test/integration/Servers.test.ts:57-70; refs/api_servers-api.md:67 example).
+export const SERVER_COLORS = [
+    "purple",
+    "blue",
+    "turquoise",
+    "green",
+    "red",
+    "yellow",
+    "grey",
+    "orange",
+];
+// docs/04 §1.4.
+export const BOUNCE_TYPES = {
+    HardBounce: { TypeCode: 1, Name: "Hard bounce" },
+    Transient: { TypeCode: 2, Name: "Message delayed/Undeliverable" },
+    Unsubscribe: { TypeCode: 16, Name: "Unsubscribe request" },
+    Subscribe: { TypeCode: 32, Name: "Subscribe request" },
+    AutoResponder: { TypeCode: 64, Name: "Auto responder" },
+    AddressChange: { TypeCode: 128, Name: "Address change" },
+    DnsError: { TypeCode: 256, Name: "DNS error" },
+    SpamNotification: { TypeCode: 512, Name: "Spam notification" },
+    OpenRelayTest: { TypeCode: 1024, Name: "Open relay test" },
+    Unknown: { TypeCode: 2048, Name: "Unknown" },
+    SoftBounce: { TypeCode: 4096, Name: "Soft bounce" },
+    VirusNotification: { TypeCode: 8192, Name: "Virus notification" },
+    ChallengeVerification: { TypeCode: 16384, Name: "Spam challenge verification" },
+    BadEmailAddress: { TypeCode: 100000, Name: "Invalid email address" },
+    SpamComplaint: { TypeCode: 100001, Name: "Spam complaint" },
+    ManuallyDeactivated: { TypeCode: 100002, Name: "Manually deactivated" },
+    Unconfirmed: { TypeCode: 100003, Name: "Registration not confirmed" },
+    Blocked: { TypeCode: 100006, Name: "ISP block" },
+    SMTPApiError: { TypeCode: 100007, Name: "SMTP API error" },
+    InboundError: { TypeCode: 100008, Name: "Processing failed" },
+    DMARCPolicy: { TypeCode: 100009, Name: "DMARC Policy" },
+    TemplateRenderingFailed: { TypeCode: 100010, Name: "Template rendering failed" },
+};

package/dist/src/time.d.ts

@@ -0,0 +1,11 @@
+/** Minutes east of UTC for US Eastern at `instant` (-300 or -240). */
+export declare function easternOffsetMinutes(instant: Date): number;
+/** The instant of an Eastern wall-clock time. */
+export declare function easternWallTime(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, ms?: number): Date;
+/**
+ * ISO 8601 with 7 fraction digits, e.g. `2014-02-17T07:25:01.4178645-05:00` (docs/02 §7.1).
+ * `zone: "utc"` gives the `Z` form some surfaces use (bounce list, webhooks, bulk).
+ */
+export declare function formatTimestamp(instant: Date, zone?: "eastern" | "utc"): string;
+/** `YYYY-MM-DD` in Eastern time, the stats `Date` shape (docs/08 E8). */
+export declare function formatEasternDate(instant: Date): string;

package/dist/src/time.js

@@ -0,0 +1,48 @@
+// Postmark reads zoneless query dates as US Eastern time and emits Eastern offsets
+// (docs/02 §7.1; refs/api_messages-api.md:40-41).
+const EASTERN = "America/New_York";
+const partsFormat = new Intl.DateTimeFormat("en-US", {
+    timeZone: EASTERN,
+    hourCycle: "h23",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+});
+/** Minutes east of UTC for US Eastern at `instant` (-300 or -240). */
+export function easternOffsetMinutes(instant) {
+    const parts = partsFormat.formatToParts(instant);
+    const get = (type) => Number(parts.find((x) => x.type === type)?.value);
+    const wall = Date.UTC(get("year"), get("month") - 1, get("day"), get("hour"), get("minute"), get("second"));
+    return Math.round((wall - Math.floor(instant.getTime() / 1000) * 1000) / 60000);
+}
+/** The instant of an Eastern wall-clock time. */
+export function easternWallTime(year, month, day, hour = 0, minute = 0, second = 0, ms = 0) {
+    const wall = Date.UTC(year, month - 1, day, hour, minute, second, ms);
+    let offset = easternOffsetMinutes(new Date(wall));
+    offset = easternOffsetMinutes(new Date(wall - offset * 60000));
+    return new Date(wall - offset * 60000);
+}
+const pad = (n, width = 2) => String(Math.abs(n)).padStart(width, "0");
+/**
+ * ISO 8601 with 7 fraction digits, e.g. `2014-02-17T07:25:01.4178645-05:00` (docs/02 §7.1).
+ * `zone: "utc"` gives the `Z` form some surfaces use (bounce list, webhooks, bulk).
+ */
+export function formatTimestamp(instant, zone = "eastern") {
+    const offset = zone === "utc" ? 0 : easternOffsetMinutes(instant);
+    const w = new Date(instant.getTime() + offset * 60000);
+    const date = `${w.getUTCFullYear()}-${pad(w.getUTCMonth() + 1)}-${pad(w.getUTCDate())}`;
+    const time = `${pad(w.getUTCHours())}:${pad(w.getUTCMinutes())}:${pad(w.getUTCSeconds())}`;
+    const fraction = `${pad(w.getUTCMilliseconds(), 3)}0000`;
+    const suffix = zone === "utc"
+        ? "Z"
+        : `${offset < 0 ? "-" : "+"}${pad(Math.trunc(offset / 60))}:${pad(offset % 60)}`;
+    return `${date}T${time}.${fraction}${suffix}`;
+}
+/** `YYYY-MM-DD` in Eastern time, the stats `Date` shape (docs/08 E8). */
+export function formatEasternDate(instant) {
+    const w = new Date(instant.getTime() + easternOffsetMinutes(instant) * 60000);
+    return `${w.getUTCFullYear()}-${pad(w.getUTCMonth() + 1)}-${pad(w.getUTCDate())}`;
+}

package/dist/src/tracking.d.ts

@@ -0,0 +1,53 @@
+import type { Runtime } from "./runtime.ts";
+import type { ClickEvent, ClientInfo, Geo, OpenEvent, OutboundMessage } from "./state/types.ts";
+/** A recipient action that real Postmark could not record. The control API answers 400. */
+export declare class TrackingRefused extends Error {
+}
+export type Platform = NonNullable<OpenEvent["Platform"]>;
+/** What the recipient's client tells Postmark. Postmark derives Client, OS, Platform from it. */
+export interface RecipientAgent {
+    UserAgent: string;
+    Client: ClientInfo | null;
+    OS: ClientInfo | null;
+    Platform: Platform | null;
+    Geo: Geo | null;
+}
+/**
+ * The unique http(s) links Postmark rewrites for the message's `TrackLinks` mode. The same URL in
+ * the HTML and the text body is one link (refs/api_stats-api.md:648). The URL pattern is INFERRED.
+ */
+export declare function trackedLinks(message: OutboundMessage, location?: ClickEvent["ClickLocation"]): string[];
+/**
+ * The recipient's mail server accepts the message (docs/05 §2.3). The `Delivered` message event is
+ * the delivery record that opens and clicks check, so it is written here, not by a listener.
+ */
+export declare function recordDelivery(runtime: Runtime, input: {
+    messageId: string;
+    recipient: string;
+    details: string;
+}, at?: Date): Promise<{
+    MessageID: string;
+    Recipient: string;
+    ReceivedAt: Date;
+}>;
+/**
+ * The recipient opens the message. Every open fires `opened` (webhook, stats). The Messages API
+ * keeps only the first open per recipient (refs/api_messages-api.md:753-754).
+ */
+export declare function recordOpen(runtime: Runtime, input: {
+    messageId: string;
+    recipient: string;
+    agent: RecipientAgent;
+    readSeconds: number;
+}, at?: Date): Promise<OpenEvent>;
+/**
+ * The recipient clicks a tracked link. Every click fires `clicked`. The Messages API keeps one
+ * click per recipient and unique link (refs/api_messages-api.md:864).
+ */
+export declare function recordClick(runtime: Runtime, input: {
+    messageId: string;
+    recipient: string;
+    link: string;
+    location: ClickEvent["ClickLocation"];
+    agent: RecipientAgent;
+}, at?: Date): Promise<ClickEvent>;

package/dist/src/tracking.js

@@ -0,0 +1,150 @@
+import { recipientsOf } from "./recipients/transitions.js";
+// What a real recipient can do with a delivered message: its server accepts it, the recipient
+// opens it, the recipient clicks a tracked link (CONTROL-API.md principle). Control endpoints and
+// seeds record these here; the Messages API and the stats plugin read the result.
+/** A recipient action that real Postmark could not record. The control API answers 400. */
+export class TrackingRefused extends Error {
+}
+const LINK = /https?:\/\/[^\s"'<>]+/g;
+/**
+ * The unique http(s) links Postmark rewrites for the message's `TrackLinks` mode. The same URL in
+ * the HTML and the text body is one link (refs/api_stats-api.md:648). The URL pattern is INFERRED.
+ */
+export function trackedLinks(message, location) {
+    const mode = message.TrackLinks;
+    const html = mode === "HtmlAndText" || mode === "HtmlOnly";
+    const text = mode === "HtmlAndText" || mode === "TextOnly";
+    const parts = [
+        html && location !== "Text" ? (message.HtmlBody ?? "") : "",
+        text && location !== "HTML" ? (message.TextBody ?? "") : "",
+    ];
+    return [...new Set(parts.flatMap((part) => part.match(LINK) ?? []))];
+}
+const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+// A bounce of these types means the message never reached the recipient (INFERRED from the type
+// names, refs/api_bounce-api.md). An auto responder or a spam complaint means it did.
+const UNDELIVERED = new Set([
+    "HardBounce",
+    "SoftBounce",
+    "BadEmailAddress",
+    "Blocked",
+    "DnsError",
+    "ManuallyDeactivated",
+    "Unconfirmed",
+    "DMARCPolicy",
+    "SMTPApiError",
+    "TemplateRenderingFailed",
+]);
+/** A recipient of a stored, sent message, spelled as sent. */
+function messageRecipient(runtime, messageId, recipient) {
+    const message = runtime.store.state.outbound.get(messageId);
+    if (message === undefined)
+        throw new TrackingRefused(`no outbound message ${messageId}`);
+    // A sandbox server delivers nothing (docs/07).
+    if (message.Sandboxed)
+        throw new TrackingRefused(`message ${messageId} is sandboxed`);
+    if (message.Status === "Queued")
+        throw new TrackingRefused(`message ${messageId} is queued`);
+    const address = recipientsOf(message).find((r) => same(r, recipient));
+    if (address === undefined) {
+        throw new TrackingRefused(`message ${messageId} was not sent to ${recipient}`);
+    }
+    // A send skips an address suppressed at send time (docs/04 §3.3).
+    if (message.suppressedRecipients.some((r) => same(r, address))) {
+        throw new TrackingRefused(`${address} was suppressed when ${messageId} was sent`);
+    }
+    const bounced = [...runtime.store.state.bounces.values()].some((b) => b.MessageID === messageId && same(b.Email, address) && UNDELIVERED.has(b.Type));
+    if (bounced)
+        throw new TrackingRefused(`message ${messageId} bounced for ${address}`);
+    return { message, address };
+}
+/** A recipient whose server accepted the message by `at`: only they can open or click. */
+function deliveredRecipient(runtime, messageId, recipient, at) {
+    const found = messageRecipient(runtime, messageId, recipient);
+    const delivered = found.message.MessageEvents.some((e) => e.Type === "Delivered" &&
+        same(e.Recipient, found.address) &&
+        e.ReceivedAt.getTime() <= at.getTime());
+    if (!delivered) {
+        throw new TrackingRefused(`message ${messageId} was not delivered to ${found.address}`);
+    }
+    return found;
+}
+/**
+ * The recipient's mail server accepts the message (docs/05 §2.3). The `Delivered` message event is
+ * the delivery record that opens and clicks check, so it is written here, not by a listener.
+ */
+export async function recordDelivery(runtime, input, at = runtime.clock.now()) {
+    const { message, address } = messageRecipient(runtime, input.messageId, input.recipient);
+    const delivered = message.MessageEvents.some((e) => e.Type === "Delivered" && same(e.Recipient, address));
+    if (delivered)
+        throw new TrackingRefused(`message ${message.MessageID} already reached ${address}`);
+    // DestinationServer and DestinationIP are left out: postmock delivers to no real server.
+    message.MessageEvents.push({
+        Recipient: address,
+        Type: "Delivered",
+        ReceivedAt: at,
+        Details: { DeliveryMessage: input.details },
+    });
+    await runtime.events.emit("delivered", {
+        message,
+        recipient: address,
+        deliveredAt: at,
+        details: input.details,
+    });
+    return { MessageID: message.MessageID, Recipient: address, ReceivedAt: at };
+}
+/**
+ * The recipient opens the message. Every open fires `opened` (webhook, stats). The Messages API
+ * keeps only the first open per recipient (refs/api_messages-api.md:753-754).
+ */
+export async function recordOpen(runtime, input, at = runtime.clock.now()) {
+    const { message, address } = deliveredRecipient(runtime, input.messageId, input.recipient, at);
+    if (!message.TrackOpens) {
+        throw new TrackingRefused(`message ${message.MessageID} has no open tracking`);
+    }
+    const opens = runtime.store.state.opens;
+    const first = !opens.some((o) => o.MessageID === message.MessageID && same(o.Recipient, address));
+    const open = {
+        ...eventBase(message, address, at),
+        FirstOpen: first,
+        ReadSeconds: input.readSeconds,
+        ...input.agent,
+    };
+    if (first)
+        opens.push(open);
+    await runtime.events.emit("opened", { open });
+    return open;
+}
+/**
+ * The recipient clicks a tracked link. Every click fires `clicked`. The Messages API keeps one
+ * click per recipient and unique link (refs/api_messages-api.md:864).
+ */
+export async function recordClick(runtime, input, at = runtime.clock.now()) {
+    const { message, address } = deliveredRecipient(runtime, input.messageId, input.recipient, at);
+    if (!trackedLinks(message, input.location).includes(input.link)) {
+        throw new TrackingRefused(`message ${message.MessageID} has no tracked link ${input.link} in its ${input.location} body (TrackLinks ${message.TrackLinks})`);
+    }
+    const clicks = runtime.store.state.clicks;
+    const first = !clicks.some((c) => c.MessageID === message.MessageID &&
+        same(c.Recipient, address) &&
+        c.OriginalLink === input.link);
+    const click = {
+        ...eventBase(message, address, at),
+        ClickLocation: input.location,
+        OriginalLink: input.link,
+        ...input.agent,
+    };
+    if (first)
+        clicks.push(click);
+    await runtime.events.emit("clicked", { click });
+    return click;
+}
+const eventBase = (message, recipient, at) => ({
+    ServerID: message.ServerID,
+    MessageID: message.MessageID,
+    MessageStream: message.MessageStream,
+    Recipient: recipient,
+    Tag: message.Tag,
+    Metadata: message.Metadata,
+    ReceivedAt: at,
+});

package/dist/src/webhooks/deliver.d.ts

@@ -0,0 +1,60 @@
+import type { Runtime } from "../runtime.ts";
+import type { Header, WebhookAttempt, WebhookRecordType, WebhookTriggers } from "../state/types.ts";
+export type ServerHookField = "InboundHookUrl" | "BounceHookUrl" | "OpenHookUrl" | "DeliveryHookUrl" | "ClickHookUrl";
+/** Where one event goes: a `/webhooks` row and its trigger, or a server hook URL field. */
+export interface Target {
+    serverId: number;
+    hook: {
+        kind: "webhook";
+        webhookId: number;
+        trigger: keyof WebhookTriggers;
+    } | {
+        kind: "server";
+        field: ServerHookField;
+    };
+    url: string;
+    httpAuth: {
+        Username: string;
+        Password: string;
+    } | null;
+    headers: Header[];
+}
+type Outcome = WebhookAttempt["outcome"];
+type Verdict = "success" | "retry" | "stop";
+/** How a receiver's answer is read, and when a failed event is sent again. */
+export interface RetryPolicy {
+    /** Minutes before each retry, in order. */
+    delaysMin: readonly number[];
+    timeoutMs: number;
+    /** Send `X-PM-Retries-Remaining`. */
+    retriesHeader: boolean;
+    classify(outcome: Outcome): Verdict;
+}
+/**
+ * Outbound events (docs/05 §3.4, §3.5): 2xx succeeds; 408, 429, 5xx and a network error retry;
+ * other codes drop the event. The outbound timeout is not documented (Q5); postmock uses the
+ * documented inbound 2 minutes (INFERRED).
+ */
+export declare const OUTBOUND: RetryPolicy;
+/**
+ * Inbound (docs/05 §3.6): only 200 succeeds and only 403 stops. A 204 retries: the doc says
+ * "non-200" (conflict R2, Q6). Whether inbound requests carry `X-PM-Retries-Remaining` is Q8;
+ * postmock leaves it out.
+ */
+export declare const INBOUND: RetryPolicy;
+export type AttemptResult = WebhookAttempt["result"];
+export interface WebhookEvent {
+    target: Target;
+    recordType: WebhookRecordType;
+    payload: object;
+    policy: RetryPolicy;
+    /** Runs after each attempt is logged. */
+    onResult?: (result: AttemptResult) => void;
+}
+/**
+ * Sends one event and awaits the first attempt. A retry goes on the clock and runs on a later
+ * `clock/advance` or when real time reaches it. Every attempt resends the same body bytes under the
+ * same trace ID (docs/05 §6).
+ */
+export declare function deliver(runtime: Runtime, event: WebhookEvent): Promise<void>;
+export {};

package/dist/src/webhooks/deliver.js

@@ -0,0 +1,172 @@
+import { randomUUID } from "node:crypto";
+import { allows, egressOf } from "./egress.js";
+/**
+ * Outbound events (docs/05 §3.4, §3.5): 2xx succeeds; 408, 429, 5xx and a network error retry;
+ * other codes drop the event. The outbound timeout is not documented (Q5); postmock uses the
+ * documented inbound 2 minutes (INFERRED).
+ */
+export const OUTBOUND = {
+    delaysMin: [1, 5, 10, 10, 10, 15],
+    timeoutMs: 120_000,
+    retriesHeader: true,
+    classify: (outcome) => {
+        if ("error" in outcome)
+            return "retry";
+        const { status } = outcome;
+        if (status >= 200 && status < 300)
+            return "success";
+        return status === 408 || status === 429 || status >= 500 ? "retry" : "stop";
+    },
+};
+/**
+ * Inbound (docs/05 §3.6): only 200 succeeds and only 403 stops. A 204 retries: the doc says
+ * "non-200" (conflict R2, Q6). Whether inbound requests carry `X-PM-Retries-Remaining` is Q8;
+ * postmock leaves it out.
+ */
+export const INBOUND = {
+    delaysMin: [1, 5, 10, 10, 10, 15, 30, 60, 120, 360],
+    timeoutMs: 120_000,
+    retriesHeader: false,
+    classify: (outcome) => {
+        if ("error" in outcome)
+            return "retry";
+        if (outcome.status === 200)
+            return "success";
+        return outcome.status === 403 ? "stop" : "retry";
+    },
+};
+const MAX_REDIRECTS = 10;
+/**
+ * Sends one event and awaits the first attempt. A retry goes on the clock and runs on a later
+ * `clock/advance` or when real time reaches it. Every attempt resends the same body bytes under the
+ * same trace ID (docs/05 §6).
+ */
+export function deliver(runtime, event) {
+    return attempt(runtime, event, JSON.stringify(event.payload), randomUUID(), 1);
+}
+async function attempt(runtime, event, body, traceId, n) {
+    const { target, policy } = event;
+    if (n > 1 && !stillConfigured(runtime, target))
+        return;
+    const remaining = policy.delaysMin.length - (n - 1);
+    const { url, headers } = request(target, traceId, policy.retriesHeader ? remaining : null);
+    const at = runtime.clock.now();
+    const sent = await post(egressOf(runtime), url, headers, body, policy.timeoutMs);
+    const outcome = "stop" in sent ? { error: sent.stop } : sent;
+    // A refused target gets no retry: the configuration, not the receiver, decides it.
+    const verdict = "stop" in sent ? "stop" : policy.classify(outcome);
+    const result = verdict === "retry" && remaining === 0 ? "exhausted" : verdict;
+    const delayMs = result === "retry" ? policy.delaysMin[n - 1] * 60_000 : null;
+    runtime.store.state.webhookAttempts.push({
+        id: runtime.store.nextId("webhookAttempt"),
+        serverId: target.serverId,
+        webhookId: target.hook.kind === "webhook" ? target.hook.webhookId : null,
+        recordType: event.recordType,
+        url: target.url,
+        traceId,
+        headers: [...headers].map(([Name, Value]) => ({ Name, Value })),
+        body,
+        attempt: n,
+        at,
+        outcome,
+        result,
+        nextAttemptAt: delayMs === null ? null : new Date(at.getTime() + delayMs),
+    });
+    // Retry delays count from the attempt's start, so the schedule does not drift by request time.
+    if (delayMs !== null) {
+        const wait = Math.max(0, at.getTime() + delayMs - runtime.clock.now().getTime());
+        runtime.clock.schedule(wait, () => attempt(runtime, event, body, traceId, n + 1));
+    }
+    event.onResult?.(result);
+}
+/**
+ * A retry goes out only while the hook still asks for it: the server exists, and the webhook row
+ * exists, is verified, keeps its `Url` and its trigger on, or the server hook field keeps its URL
+ * (INFERRED, docs/05 D4).
+ */
+function stillConfigured(runtime, target) {
+    const { servers, webhooks } = runtime.store.state;
+    const server = servers.get(target.serverId);
+    if (server === undefined)
+        return false;
+    const { hook } = target;
+    if (hook.kind === "server")
+        return server[hook.field] === target.url;
+    const webhook = webhooks.get(hook.webhookId);
+    return (webhook !== undefined &&
+        webhook.ServerID === server.ID &&
+        webhook.Status === "verified" &&
+        webhook.Url === target.url &&
+        webhook.Triggers[hook.trigger].Enabled);
+}
+/**
+ * URL userinfo and `HttpAuth` become `Authorization: Basic`; the userinfo leaves the request URL
+ * (docs/05 §3.2, Q18). With both, `HttpAuth` wins (INFERRED, Q3). The query string stays.
+ */
+function request(target, traceId, retriesRemaining) {
+    const url = new URL(target.url);
+    const userinfo = url.username === "" && url.password === ""
+        ? null
+        : { Username: decodeURIComponent(url.username), Password: decodeURIComponent(url.password) };
+    url.username = "";
+    url.password = "";
+    const auth = target.httpAuth ?? userinfo;
+    const headers = new Headers();
+    for (const header of target.headers)
+        headers.append(header.Name, header.Value);
+    headers.set("Content-Type", "application/json");
+    headers.set("X-PM-Webhook-Trace-Id", traceId);
+    if (retriesRemaining !== null)
+        headers.set("X-PM-Retries-Remaining", String(retriesRemaining));
+    if (auth !== null) {
+        const token = Buffer.from(`${auth.Username}:${auth.Password}`).toString("base64");
+        headers.set("Authorization", `Basic ${token}`);
+    }
+    return { url, headers };
+}
+/**
+ * POSTs and follows up to 10 redirects; the final answer decides (docs/05 §3.3). Every hop must be
+ * http or https to an allowed host; a redirect `Location` with userinfo or an unparsable one stops
+ * the event. A refused hop opens no socket.
+ */
+async function post(egress, url, headers, body, timeoutMs) {
+    let current = url;
+    for (let hop = 0;; hop++) {
+        if (current.protocol !== "http:" && current.protocol !== "https:") {
+            return { stop: `redirect refused: scheme ${current.protocol} is not http or https` };
+        }
+        if (!allows(egress, current)) {
+            return {
+                stop: `egress refused: host ${current.hostname} is not loopback and not in POSTMOCK_WEBHOOKS_ALLOW_HOSTS`,
+            };
+        }
+        let response;
+        try {
+            response = await fetch(current, {
+                method: "POST",
+                headers,
+                body,
+                redirect: "manual",
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            await response.body?.cancel();
+        }
+        catch (error) {
+            const cause = error.cause;
+            return { error: cause?.message ?? error.message };
+        }
+        const location = response.headers.get("Location");
+        if (response.status < 300 || response.status >= 400 || location === null) {
+            return { status: response.status };
+        }
+        if (hop === MAX_REDIRECTS)
+            return { error: `more than ${MAX_REDIRECTS} redirects` };
+        const next = URL.parse(location, current.href);
+        if (next === null)
+            return { stop: `redirect refused: Location '${location}' is not a URL` };
+        if (next.username !== "" || next.password !== "") {
+            return { stop: "redirect refused: Location carries userinfo" };
+        }
+        current = next;
+    }
+}

package/dist/src/webhooks/egress.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import type { Runtime } from "../runtime.ts";
+/**
+ * Which hosts the emitter may reach. By default only loopback: SDK suites configure hooks at real
+ * hosts (www.example.com, www.postmark.com), and a test run must not POST to the internet or to
+ * Postmark (AGENTS.md rule 7). `POSTMOCK_WEBHOOKS_ALLOW_HOSTS` adds hostnames; `*` allows every host.
+ */
+export interface Egress {
+    allowHosts: ReadonlySet<string>;
+}
+export declare const LOOPBACK_ONLY: Egress;
+export declare const egressEnv: z.ZodPipe<z.ZodPipe<z.ZodPipe<z.ZodObject<{
+    POSTMOCK_WEBHOOKS_ALLOW_HOSTS: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>, z.ZodTransform<string[], {
+    POSTMOCK_WEBHOOKS_ALLOW_HOSTS: string;
+}>>, z.ZodArray<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodTransform<string, string>>>>, z.ZodTransform<Egress, string[]>>;
+export declare const setEgress: (runtime: Runtime, egress: Egress) => void;
+export declare const egressOf: (runtime: Runtime) => Egress;
+export declare function allows(egress: Egress, url: URL): boolean;

package/dist/src/webhooks/egress.js

@@ -0,0 +1,40 @@
+import { isIP } from "node:net";
+import { z } from "zod";
+export const LOOPBACK_ONLY = { allowHosts: new Set() };
+/** An entry is a hostname, an IPv4 address, or an IPv6 address with or without brackets; no port. */
+const hostEntry = z
+    .string()
+    .transform((entry) => entry.toLowerCase())
+    .transform((entry) => (/^\[.*\]$/.test(entry) ? entry.slice(1, -1) : entry))
+    .refine((host) => host === "*" || isIP(host) === 6 || !host.includes(":"), {
+    message: "an allowed host takes no port",
+});
+export const egressEnv = z
+    .object({ POSTMOCK_WEBHOOKS_ALLOW_HOSTS: z.string().default("") })
+    .transform(({ POSTMOCK_WEBHOOKS_ALLOW_HOSTS: hosts }) => hosts
+    .split(",")
+    .map((h) => h.trim())
+    .filter((h) => h !== ""))
+    .pipe(z.array(hostEntry))
+    .transform((hosts) => ({ allowHosts: new Set(hosts) }));
+const egressByRuntime = new WeakMap();
+export const setEgress = (runtime, egress) => {
+    egressByRuntime.set(runtime, egress);
+};
+export const egressOf = (runtime) => egressByRuntime.get(runtime) ?? LOOPBACK_ONLY;
+/**
+ * `localhost`, `127.0.0.0/8` and `::1` by their literal form. postmock resolves no name itself, but
+ * `fetch` resolves `localhost` through the OS resolver (normally a loopback address).
+ */
+function isLoopback(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if (host === "localhost")
+        return true;
+    if (isIP(host) === 4)
+        return host.startsWith("127.");
+    return isIP(host) === 6 && host === "::1";
+}
+export function allows(egress, url) {
+    const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    return egress.allowHosts.has("*") || egress.allowHosts.has(host) || isLoopback(host);
+}

package/dist/src/webhooks/outbound.d.ts

@@ -0,0 +1,26 @@
+import type { Runtime } from "../runtime.ts";
+import type { Server, Webhook, WebhookRecordType, WebhookTriggers } from "../state/types.ts";
+import { type ServerHookField } from "./deliver.ts";
+/** A hook that receives an event: a `/webhooks` row, or the server's own hook URL. */
+export type Hook = {
+    kind: "webhook";
+    webhook: Webhook;
+} | {
+    kind: "server";
+    server: Server;
+};
+export interface OutboundEvent {
+    serverId: number;
+    messageStream: string;
+    recordType: Exclude<WebhookRecordType, "Inbound">;
+    trigger: keyof WebhookTriggers;
+    /** The server hook URL field for this event; none for SpamComplaint and SubscriptionChange. */
+    serverHookField: ServerHookField | null;
+    /** The body for one hook, or null when that hook filters the event out. */
+    payload: (hook: Hook) => object | null;
+}
+/**
+ * Sends an event to every verified `/webhooks` row of its stream with the trigger on, then to the
+ * server hook URL (docs/05 §1.5, §5). Server hook URLs apply to every stream (INFERRED, Q10).
+ */
+export declare function emitOutbound(runtime: Runtime, event: OutboundEvent): Promise<void>;