@benclmnt/postmock 0.0.1

package/dist/src/pipeline/submit.js

@@ -0,0 +1,415 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { errorBody } from "../errors.js";
+import { absent, base64, canonicalizeKeys, objectOrEmptyArray } from "../http/normalize.js";
+import { Unsupported } from "../http/respond.js";
+import { composeMime } from "../mime/compose.js";
+import { testBounces } from "../recipients/test-bounces.js";
+import { newMessageId } from "../state/ids.js";
+import { findStream } from "../state/servers.js";
+import { suppressedAddresses } from "../state/suppressions.js";
+import { parseAddressList } from "./addresses.js";
+import { inactiveRecipientsError } from "./inactive.js";
+// R9: null and "" are absent for optional values (docs/08; php, dotnet, gem send them).
+const text = absent(z.string());
+const nullable = (schema) => z.preprocess((v) => (v === null ? undefined : v), schema.optional());
+const TRACK_LINKS = z.enum(["None", "HtmlAndText", "HtmlOnly", "TextOnly"]);
+/** Field shape checks, in draft field order. REST sends JSON types; SMTP sends header text (docs/07 §1.3). */
+const draftSchema = (channel) => z.object({
+    From: text,
+    To: text,
+    Cc: text,
+    Bcc: text,
+    ReplyTo: text,
+    Subject: text,
+    HtmlBody: text,
+    TextBody: text,
+    Tag: text,
+    MessageStream: text,
+    Headers: nullable(z.array(z.object({ Name: z.string(), Value: z.string() }))),
+    Attachments: nullable(z.array(z.object({
+        Name: z.string(),
+        Content: base64,
+        ContentType: z.string(),
+        // postmark.js sends null, php and gem a name or a `cid:` url (docs/03 §1.7).
+        ContentID: z.string().nullable().optional(),
+    }))),
+    // php sends an empty metadata array as `[]` (sdk/postmark-php/src/Postmark/PostmarkClient.php:97,113).
+    Metadata: nullable(objectOrEmptyArray(z.record(z.string(), z.string()))),
+    // SMTP: `X-PM-TrackOpens: true`; absent or false means no tracking (docs/07 §1.3).
+    TrackOpens: channel === "rest"
+        ? absent(z.boolean())
+        : absent(z
+            .string()
+            .regex(/^(true|false)$/i)
+            .transform((v) => v.toLowerCase() === "true")),
+    TrackLinks: absent(TRACK_LINKS),
+});
+/**
+ * The draft of one JSON message object. Keys match without case at every level, `ContentId` too
+ * (docs/08 R8); unknown keys are ignored (R12). Every JSON channel builds its draft here.
+ */
+export function draftFromJson(body) {
+    const canonical = canonicalizeKeys(draftSchema("rest"), body);
+    const keys = Object.keys(draftSchema("rest").shape);
+    return Object.fromEntries(keys.map((key) => [key, canonical[key]]));
+}
+// Limits: docs/03 §1.2, docs/07 §3. Lengths count UTF-16 code units (docs/03 §1.9).
+const MB = 1024 * 1024;
+const MAX_BODY_BYTES = 5 * MB;
+const MAX_MESSAGE_BYTES = 10 * MB;
+const MAX_RECIPIENTS = 50;
+const MAX_FROM = 255;
+const MAX_SUBJECT = 2000;
+const MAX_TAG = 1000;
+const MAX_METADATA_FIELDS = 10;
+const MAX_METADATA_KEY = 20;
+const MAX_METADATA_VALUE = 80;
+// refs/user-guide_send-email-with-api.md:176 (docs/07 §3).
+const FORBIDDEN_EXTENSIONS = new Set("vbs exe bin bat chm com cpl crt hlp hta inf ins isp jse lnk mdb pcd pif reg scr sct shs vbe vba wsf wsh wsl msc msi msp mst".split(" "));
+const reject = (field, error) => ({
+    outcome: "rejected",
+    field,
+    error,
+});
+// ErrorCode 300 is documented for each case below (refs/api_overview.md:69). Only the address
+// texts are documented (refs/api_bulk-email.md:221-227); the other texts are INFERRED (docs/03 Q4).
+const invalid = (field, message) => reject(field, errorBody(300, { message }));
+const invalidAddress = (field, raw) => invalid(field, `Invalid '${field}' address: '${raw}'.`);
+/**
+ * The checks of a send, with no state change: the data checks (field types, size, stream,
+ * addresses, recipients, content, limits, attachments) and the sender check. Account approval and
+ * suppressions belong to `acceptOutbound`. Throws `Unsupported` for uncaptured cases.
+ */
+export function validateOutbound(runtime, submission) {
+    const data = checkData(runtime, submission);
+    if (data.outcome === "rejected") {
+        refuseSenderAfterDataError(runtime, submission.auth, submission.draft.From);
+        return data;
+    }
+    if (submission.auth.kind === "test")
+        return data;
+    const { from, draft, recipients } = data.outbound;
+    if (!senderAuthorized(runtime.store.state, from)) {
+        return reject("From", errorBody(400, { params: { from: from.Email } }));
+    }
+    // A fake bounce type with an uncaptured effect answers 501 before anything is stored. It runs
+    // after the sender check, so an unknown sender keeps the captured 400.
+    testBounces(draft.Headers ?? [], recipients);
+    return data;
+}
+/**
+ * Which error Postmark answers for a message that fails a data check and the sender check is not
+ * captured (docs/03 §3.4). A caller that answers a data error calls this first. The test token
+ * belongs to no account and has no sender check (sdk/postmark-gem/spec/integration/api_client_messages_spec.rb:5-10,
+ * :45-48; sdk/postmark-java/src/test/java/integration/MessageTest.java:27-36).
+ */
+export function refuseSenderAfterDataError(runtime, auth, rawFrom) {
+    if (auth.kind === "test" || typeof rawFrom !== "string")
+        return;
+    const [from, ...more] = parseAddressList(rawFrom) ?? [];
+    if (from === undefined || more.length > 0)
+        return;
+    if (!senderAuthorized(runtime.store.state, from)) {
+        throw new Unsupported(`a message that fails a data check and the sender check for ${from.Email} (docs/03 §3.4)`);
+    }
+}
+/** The data checks; check order follows docs/03 §3.3 (INFERRED). */
+function checkData(runtime, submission) {
+    const parsed = draftSchema(submission.channel).safeParse(submission.draft);
+    // ErrorCode 403 for a field of the wrong type is INFERRED (docs/02 §9 Q13); text shape from
+    // refs/api_overview.md:43-50. The first failing field is named.
+    if (!parsed.success) {
+        const field = String(parsed.error.issues[0]?.path[0]);
+        return reject(field, errorBody(403, { message: `Invalid request field(s): '${field}'.` }));
+    }
+    const draft = parsed.data;
+    checkSize(draft);
+    const streamId = draft.MessageStream ?? "outbound";
+    const stream = findStream(runtime.store.state, submission.auth, streamId);
+    if (stream === undefined) {
+        return reject("MessageStream", errorBody(1235, { params: { stream: streamId } }));
+    }
+    if (stream.MessageStreamType === "Inbound")
+        return reject("MessageStream", errorBody(1236));
+    if (stream.ArchivedAt !== null) {
+        throw new Unsupported(`send to archived stream '${streamId}' is not captured (docs/04 Q15)`);
+    }
+    if (draft.From === undefined)
+        return invalidAddress("From", "");
+    const [from, ...moreFrom] = parseAddressList(draft.From) ?? [];
+    if (from === undefined || moreFrom.length > 0)
+        return invalidAddress("From", draft.From);
+    const lists = {
+        To: [],
+        Cc: [],
+        Bcc: [],
+        ReplyTo: [],
+    };
+    for (const field of ["To", "Cc", "Bcc", "ReplyTo"]) {
+        const addresses = parseAddressList(draft[field] ?? "");
+        if (addresses === undefined)
+            return invalidAddress(field, draft[field] ?? "");
+        lists[field] = addresses;
+    }
+    // `To` is required (docs/03 §1.2); the empty-`To` text is INFERRED (docs/03 Q4).
+    if (draft.To === undefined || lists.To.length === 0)
+        return invalidAddress("To", draft.To ?? "");
+    const recipients = [...lists.To, ...lists.Cc, ...lists.Bcc];
+    if (recipients.length > MAX_RECIPIENTS) {
+        return invalid("To", `Exceeded the maximum of ${MAX_RECIPIENTS} recipients per message.`);
+    }
+    if (draft.HtmlBody === undefined && draft.TextBody === undefined) {
+        return invalid("TextBody", "Provide either email TextBody or HtmlBody or both.");
+    }
+    const limitError = checkLimits(draft);
+    if (limitError !== undefined)
+        return invalid(limitError.field, limitError.message);
+    for (const attachment of draft.Attachments ?? []) {
+        const extension = /\.([^.]*)$/.exec(attachment.Name)?.[1]?.toLowerCase();
+        if (extension !== undefined && FORBIDDEN_EXTENSIONS.has(extension)) {
+            return reject("Attachments", errorBody(411));
+        }
+    }
+    return {
+        outcome: "valid",
+        outbound: {
+            submission,
+            draft: { ...draft, From: draft.From, To: draft.To },
+            streamId,
+            from,
+            lists,
+            recipients,
+        },
+    };
+}
+/**
+ * Account approval → suppression check → store (docs/11 §2), with no event. The test token stops
+ * before them: it validates data only, and account state and suppressions are INFERRED not to
+ * apply to it (docs/02 Q18).
+ */
+function storeOutbound(runtime, outbound) {
+    const { submission, draft, streamId, from, lists, recipients } = outbound;
+    const { auth } = submission;
+    const now = runtime.clock.now();
+    if (auth.kind === "test") {
+        return { outcome: "validated", messageId: newMessageId(), submittedAt: now };
+    }
+    const { account } = runtime.store.state;
+    if (account.approval === "unapproved")
+        return { outcome: "rejected", error: errorBody(413) };
+    const fromDomain = domainOf(from);
+    if (account.approval === "pending" && recipients.some((r) => domainOf(r) !== fromDomain)) {
+        return { outcome: "rejected", error: errorBody(412) };
+    }
+    const inactive = inactiveRecipients(runtime, auth.server.ID, streamId, recipients);
+    if (inactive.length === recipients.length) {
+        return { outcome: "rejected", error: inactiveRecipientsError(uniqueEmails(inactive)) };
+    }
+    const messageId = newMessageId();
+    const message = {
+        MessageID: messageId,
+        ServerID: auth.server.ID,
+        MessageStream: streamId,
+        From: draft.From,
+        To: lists.To,
+        Cc: lists.Cc,
+        Bcc: lists.Bcc,
+        ReplyTo: draft.ReplyTo ?? null,
+        Subject: draft.Subject ?? null,
+        HtmlBody: draft.HtmlBody ?? null,
+        TextBody: draft.TextBody ?? null,
+        Tag: draft.Tag ?? null,
+        Headers: draft.Headers ?? [],
+        Attachments: (draft.Attachments ?? []).map((a) => ({
+            Name: a.Name,
+            Content: a.Content.toString("base64"),
+            ContentType: a.ContentType,
+            // `""` is "not inline", like null and absent (docs/03 §1.7).
+            ContentID: a.ContentID || null,
+            ContentLength: a.Content.length,
+        })),
+        Metadata: draft.Metadata ?? {},
+        // A server with open tracking on forces it on (docs/03 §5.3); a message without an HTML body
+        // is never tracked (docs/07 §3).
+        TrackOpens: draft.HtmlBody !== undefined && (auth.server.TrackOpens || (draft.TrackOpens ?? false)),
+        // A message value overrides the server value (docs/03 §5.2).
+        TrackLinks: draft.TrackLinks ?? auth.server.TrackLinks,
+        Status: "Sent",
+        Sandboxed: auth.server.DeliveryType === "Sandbox",
+        ReceivedAt: now,
+        MessageEvents: [],
+        channel: submission.channel,
+        request: submission.request,
+        rawSource: submission.channel === "smtp" ? submission.rawSource : restSource(outbound, messageId, now),
+        bulkRequestId: submission.bulkRequestId,
+        templateId: submission.templateId,
+        suppressedRecipients: uniqueEmails(inactive),
+    };
+    runtime.store.state.outbound.set(message.MessageID, message);
+    return inactive.length === 0
+        ? { outcome: "accepted", message }
+        : {
+            outcome: "partiallySuppressed",
+            message,
+            error: inactiveRecipientsError(uniqueEmails(inactive)),
+        };
+}
+/**
+ * The MIME source of a REST send, served by the dump endpoint. The gem live test finds the subject
+ * in it (sdk/postmark-gem/spec/integration/api_client_resources_spec.rb:36-40). Postmark adds
+ * `X-PM-Tag` and `X-PM-Message-Id` (refs/api_messages-api.md:276). A `Message-ID` from `Headers`
+ * is kept; otherwise it is `<uuid@mtasv.net>`, as on SMTP (src/smtp/mime.ts, INFERRED). The layout
+ * is INFERRED.
+ */
+function restSource({ draft, from, lists }, messageId, now) {
+    const address = (a) => ({ email: a.Email, name: a.Name ?? undefined });
+    const custom = (draft.Headers ?? []).map((h) => ({ name: h.Name, value: h.Value }));
+    const hasMessageId = custom.some((h) => h.name.toLowerCase() === "message-id");
+    return composeMime({
+        from: address(from),
+        to: lists.To.map(address),
+        cc: lists.Cc.map(address),
+        replyTo: draft.ReplyTo,
+        subject: draft.Subject ?? "",
+        text: draft.TextBody,
+        html: draft.HtmlBody,
+        headers: [
+            ...custom,
+            ...(draft.Tag === undefined ? [] : [{ name: "X-PM-Tag", value: draft.Tag }]),
+            { name: "X-PM-Message-Id", value: messageId },
+            ...(hasMessageId ? [] : [{ name: "Message-ID", value: `<${randomUUID()}@mtasv.net>` }]),
+        ],
+        attachments: (draft.Attachments ?? []).map((a) => ({
+            name: a.Name,
+            content: a.Content.toString("base64"),
+            contentType: a.ContentType,
+            contentId: a.ContentID || undefined,
+        })),
+    }, now);
+}
+/**
+ * Stores every accepted message, then emits `sent` for each, in order. A `sent` listener that
+ * changes state (archives a stream, adds a suppression) cannot affect a later message of the
+ * same request.
+ */
+export async function acceptOutbounds(runtime, outbounds) {
+    const results = outbounds.map((outbound) => storeOutbound(runtime, outbound));
+    for (const result of results) {
+        if ("message" in result)
+            await runtime.events.emit("sent", { message: result.message });
+    }
+    return results;
+}
+export async function acceptOutbound(runtime, outbound) {
+    const [result] = await acceptOutbounds(runtime, [outbound]);
+    return result;
+}
+/** `validateOutbound`, then `acceptOutbound` for a valid draft. */
+export async function submitOutbound(runtime, submission) {
+    const validation = validateOutbound(runtime, submission);
+    return validation.outcome === "valid"
+        ? acceptOutbound(runtime, validation.outbound)
+        : { outcome: "rejected", error: validation.error };
+}
+/**
+ * Body parts over 5 MB or a message over 10 MB, measured after base64, is HTTP 413 (docs/07 §3).
+ * The 413 body is not captured (docs/02 Q10), so postmock answers 501.
+ */
+function checkSize(draft) {
+    const bodies = [draft.HtmlBody, draft.TextBody].map((b) => Buffer.byteLength(b ?? ""));
+    const attachments = (draft.Attachments ?? []).reduce((sum, a) => sum + Math.ceil(a.Content.length / 3) * 4, 0);
+    const total = bodies.reduce((a, b) => a + b, 0) + attachments;
+    if (bodies.some((b) => b > MAX_BODY_BYTES) || total > MAX_MESSAGE_BYTES) {
+        throw new Unsupported("HTTP 413 for an oversized message: body not captured (docs/02 Q10)");
+    }
+}
+/** The first limit the draft breaks, as a 300 message (texts INFERRED, docs/03 Q4). */
+function checkLimits(draft) {
+    if ((draft.From ?? "").length > MAX_FROM) {
+        return {
+            field: "From",
+            message: `The 'From' field exceeds the maximum length of ${MAX_FROM} characters.`,
+        };
+    }
+    if ((draft.Subject ?? "").length > MAX_SUBJECT) {
+        return {
+            field: "Subject",
+            message: `The 'Subject' field exceeds the maximum length of ${MAX_SUBJECT} characters.`,
+        };
+    }
+    if ((draft.Tag ?? "").length > MAX_TAG) {
+        return {
+            field: "Tag",
+            message: `The 'Tag' field exceeds the maximum length of ${MAX_TAG} characters.`,
+        };
+    }
+    const metadata = Object.entries(draft.Metadata ?? {});
+    if (metadata.length > MAX_METADATA_FIELDS) {
+        return {
+            field: "Metadata",
+            message: `Metadata may contain at most ${MAX_METADATA_FIELDS} fields.`,
+        };
+    }
+    const seen = new Set();
+    for (const [key, value] of metadata) {
+        if (key.length > MAX_METADATA_KEY) {
+            return {
+                field: "Metadata",
+                message: `Metadata field name '${key}' exceeds the maximum length of ${MAX_METADATA_KEY} characters.`,
+            };
+        }
+        if (value.length > MAX_METADATA_VALUE) {
+            return {
+                field: "Metadata",
+                message: `Metadata field '${key}' value exceeds the maximum length of ${MAX_METADATA_VALUE} characters.`,
+            };
+        }
+        if (seen.has(key.toLowerCase()))
+            return { field: "Metadata", message: `Metadata field '${key}' appears more than once.` };
+        seen.add(key.toLowerCase());
+    }
+    return undefined;
+}
+const domainOf = (address) => address.Email.split("@").at(-1).toLowerCase();
+/**
+ * True for a `From` on a DKIM-verified account Domain (any local part, CAPTURED:
+ * captures/20260916T231736Z-from-verification/03) or a confirmed Sender Signature's address. False
+ * only where the captured 400 applies: no account Domain and no Signature matches the `From`
+ * (captures/20260916T231736Z-from-verification/01). Names match without case. Every other state
+ * is not captured and throws `Unsupported` (docs/03 §3.4).
+ */
+function senderAuthorized(state, from) {
+    const domain = domainOf(from);
+    const email = from.Email.toLowerCase();
+    const signatures = [...state.senders.values()].filter((s) => s.EmailAddress.toLowerCase() === email);
+    const domains = [...state.domains.values()].filter((d) => d.Name.toLowerCase() === domain);
+    if (signatures.some((s) => s.Confirmed) || domains.some((d) => d.DKIMVerified))
+        return true;
+    if (signatures.length > 0) {
+        throw new Unsupported(`a send from the unconfirmed sender signature ${from.Email} (docs/03 Q3)`);
+    }
+    if (domains.length > 0) {
+        throw new Unsupported(`a send from the domain ${domain} without verified DKIM (docs/03 Q3)`);
+    }
+    const parent = [...state.domains.values()].find((d) => domain.endsWith(`.${d.Name.toLowerCase()}`));
+    if (parent !== undefined) {
+        throw new Unsupported(`a send from ${domain}, a subdomain of the domain ${parent.Name} (docs/03 Q3)`);
+    }
+    return false;
+}
+/** Recipients on the send stream's suppression list; each stream has its own list (docs/04 §3.3). */
+function inactiveRecipients(runtime, serverId, streamId, recipients) {
+    const emails = recipients.map((r) => r.Email);
+    const suppressed = new Set(suppressedAddresses(runtime.store.state, serverId, streamId, emails));
+    return recipients.filter((r) => suppressed.has(r.Email));
+}
+/** Each address once, in first-seen spelling; addresses compare without case. */
+function uniqueEmails(addresses) {
+    const byLower = new Map();
+    for (const { Email } of addresses) {
+        if (!byLower.has(Email.toLowerCase()))
+            byLower.set(Email.toLowerCase(), Email);
+    }
+    return [...byLower.values()];
+}

package/dist/src/plugins/message-events.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from "../plugins.ts";
+/**
+ * Appends the `MessageEvents` of outbound message details (docs/06 §1.6). Details values are
+ * strings (refs/api_messages-api.md:181-236).
+ */
+declare const messageEvents: Plugin;
+export default messageEvents;

package/dist/src/plugins/message-events.js

@@ -0,0 +1,76 @@
+/**
+ * Appends the `MessageEvents` of outbound message details (docs/06 §1.6). Details values are
+ * strings (refs/api_messages-api.md:181-236).
+ */
+const messageEvents = {
+    install(runtime) {
+        const { events } = runtime;
+        const add = (message, event) => {
+            message?.MessageEvents.push(event);
+        };
+        // A bounce or subscription change can name no stored message (a manual suppression).
+        const outbound = (id) => id === null ? undefined : runtime.store.state.outbound.get(id);
+        events.on("bounced", ({ bounce }) => {
+            const message = outbound(bounce.MessageID);
+            if (bounce.Type === "Transient") {
+                add(message, {
+                    Recipient: bounce.Email,
+                    Type: "Transient",
+                    ReceivedAt: bounce.BouncedAt,
+                    Details: { DeliveryMessage: bounce.Details },
+                });
+            }
+            else if (bounce.Type !== "SpamComplaint" && bounce.Type !== "SMTPApiError") {
+                add(message, {
+                    Recipient: bounce.Email,
+                    Type: "Bounced",
+                    ReceivedAt: bounce.BouncedAt,
+                    Details: { Summary: bounce.Details, BounceID: String(bounce.ID) },
+                });
+            }
+        });
+        // A complaint is a bounce of type SpamComplaint; the doc lists no own event type (INFERRED).
+        events.on("spamComplaint", ({ bounce }) => add(outbound(bounce.MessageID), {
+            Recipient: bounce.Email,
+            Type: "Bounced",
+            ReceivedAt: bounce.BouncedAt,
+            Details: { Summary: bounce.Description, BounceID: String(bounce.ID) },
+        }));
+        // Only the stored first open and first click per link appear, like the opens and clicks reads.
+        events.on("opened", ({ open }) => {
+            if (!runtime.store.state.opens.includes(open))
+                return;
+            add(outbound(open.MessageID), {
+                Recipient: open.Recipient,
+                Type: "Opened",
+                ReceivedAt: open.ReceivedAt,
+                Details: { Summary: `Email opened with ${open.UserAgent}` },
+            });
+        });
+        events.on("clicked", ({ click }) => {
+            if (!runtime.store.state.clicks.includes(click))
+                return;
+            const body = click.ClickLocation === "HTML" ? "HTMLBody" : "TextBody";
+            add(outbound(click.MessageID), {
+                Recipient: click.Recipient,
+                Type: "LinkClicked",
+                ReceivedAt: click.ReceivedAt,
+                Details: {
+                    Summary: `Tracked Link '${click.OriginalLink}' was clicked from the ${body}.`,
+                    Link: click.OriginalLink,
+                    ClickLocation: click.ClickLocation,
+                },
+            });
+        });
+        events.on("subscriptionChange", ({ change }) => add(outbound(change.MessageID), {
+            Recipient: change.Recipient,
+            Type: "SubscriptionChanged",
+            ReceivedAt: change.ChangedAt,
+            Details: {
+                Origin: change.Origin,
+                SuppressSending: change.SuppressSending ? "True" : "False",
+            },
+        }));
+    },
+};
+export default messageEvents;

package/dist/src/plugins/smtp.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import type { Plugin } from "../plugins.ts";
+/**
+ * `POSTMOCK_SMTP_PORTS`: comma-separated; every port serves the same endpoint. The default `0` picks
+ * a free port, so parallel test runs never collide. Postmark listens on 25, 587 and 2525
+ * (docs/07 §1.2): set `2525` and map the other two to it.
+ * `POSTMOCK_SMTP_TLS_KEY`, `POSTMOCK_SMTP_TLS_CERT`: PEM files; both set offers STARTTLS.
+ */
+export declare const smtpEnv: z.ZodObject<{
+    POSTMOCK_SMTP_PORTS: z.ZodPipe<z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<number[], string>>, z.ZodArray<z.ZodInt>>;
+    POSTMOCK_SMTP_TLS_KEY: z.ZodOptional<z.ZodString>;
+    POSTMOCK_SMTP_TLS_CERT: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const smtp: Plugin;
+export default smtp;

package/dist/src/plugins/smtp.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { readPem } from "../config.js";
+import { startSmtp } from "../smtp/listener.js";
+/**
+ * `POSTMOCK_SMTP_PORTS`: comma-separated; every port serves the same endpoint. The default `0` picks
+ * a free port, so parallel test runs never collide. Postmark listens on 25, 587 and 2525
+ * (docs/07 §1.2): set `2525` and map the other two to it.
+ * `POSTMOCK_SMTP_TLS_KEY`, `POSTMOCK_SMTP_TLS_CERT`: PEM files; both set offers STARTTLS.
+ */
+export const smtpEnv = z
+    .object({
+    POSTMOCK_SMTP_PORTS: z
+        .string()
+        .regex(/^\d+(,\d+)*$/, "a comma-separated port list")
+        .default("0")
+        .transform((v) => v.split(",").map(Number))
+        .pipe(z.array(z.int().max(65535))),
+    POSTMOCK_SMTP_TLS_KEY: z.string().min(1).optional(),
+    POSTMOCK_SMTP_TLS_CERT: z.string().min(1).optional(),
+})
+    .refine((env) => (env.POSTMOCK_SMTP_TLS_KEY === undefined) === (env.POSTMOCK_SMTP_TLS_CERT === undefined), {
+    message: "set both POSTMOCK_SMTP_TLS_KEY and POSTMOCK_SMTP_TLS_CERT, or neither",
+})
+    .refine((env) => env.POSTMOCK_SMTP_PORTS.length === 1 || !env.POSTMOCK_SMTP_PORTS.includes(0), {
+    message: "POSTMOCK_SMTP_PORTS: port 0 is only allowed alone; its port is in the startup URL",
+});
+const smtp = {
+    start: (runtime, host) => {
+        const env = smtpEnv.parse(process.env);
+        return startSmtp(runtime, {
+            host,
+            ports: env.POSTMOCK_SMTP_PORTS,
+            tls: env.POSTMOCK_SMTP_TLS_KEY === undefined || env.POSTMOCK_SMTP_TLS_CERT === undefined
+                ? null
+                : {
+                    key: readPem("POSTMOCK_SMTP_TLS_KEY", env.POSTMOCK_SMTP_TLS_KEY),
+                    cert: readPem("POSTMOCK_SMTP_TLS_CERT", env.POSTMOCK_SMTP_TLS_CERT),
+                },
+        });
+    },
+};
+export default smtp;

package/dist/src/plugins/stats.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from "../plugins.ts";
+/**
+ * Records a Stats API fact for each countable event (docs/06 §2). Facts outlive messages, opens
+ * and clicks, which leave after the retention window (refs/api_stats-api.md:4).
+ */
+declare const stats: Plugin;
+export default stats;

package/dist/src/plugins/stats.js

@@ -0,0 +1,78 @@
+import { recipientsOf } from "../recipients/transitions.js";
+import { trackedLinks } from "../tracking.js";
+/**
+ * Records a Stats API fact for each countable event (docs/06 §2). Facts outlive messages, opens
+ * and clicks, which leave after the retention window (refs/api_stats-api.md:4).
+ */
+const stats = {
+    install(runtime) {
+        const { events } = runtime;
+        const record = (fact) => {
+            runtime.store.state.stats.push(fact);
+        };
+        const from = (b) => ({
+            ServerID: b.ServerID,
+            MessageStream: b.MessageStream,
+            Tag: b.Tag,
+            at: b.BouncedAt,
+        });
+        events.on("sent", ({ message }) => {
+            const linkTracking = message.TrackLinks !== "None";
+            // One fact per recipient: stats count a message once per recipient (refs/api_messages-api.md:50).
+            for (const _ of recipientsOf(message)) {
+                record({
+                    kind: "sent",
+                    ServerID: message.ServerID,
+                    MessageStream: message.MessageStream,
+                    Tag: message.Tag,
+                    at: message.ReceivedAt,
+                    openTracking: message.TrackOpens,
+                    linkTracking,
+                    trackedLinks: linkTracking ? trackedLinks(message).length : 0,
+                });
+            }
+        });
+        // The bounce stats keys are HardBounce, SoftBounce, Transient, SMTPApiError
+        // (refs/api_stats-api.md:197-200). Other bounce types count nowhere (INFERRED).
+        events.on("bounced", ({ bounce }) => {
+            if (bounce.Type === "HardBounce" ||
+                bounce.Type === "SoftBounce" ||
+                bounce.Type === "Transient") {
+                record({ kind: "bounce", type: bounce.Type, ...from(bounce) });
+            }
+        });
+        events.on("smtpApiError", ({ bounce }) => {
+            record({ kind: "bounce", type: "SMTPApiError", ...from(bounce) });
+        });
+        events.on("spamComplaint", ({ bounce }) => record({ kind: "spamComplaint", ...from(bounce) }));
+        events.on("opened", ({ open }) => record({
+            kind: "open",
+            ServerID: open.ServerID,
+            MessageStream: open.MessageStream,
+            Tag: open.Tag,
+            at: open.ReceivedAt,
+            MessageID: open.MessageID,
+            Recipient: open.Recipient,
+            first: open.FirstOpen,
+            platform: open.Platform,
+            // Email client and browser keys use Client.Family (INFERRED; doc examples: refs/api_stats-api.md:588, :741).
+            client: open.Client?.Family ?? null,
+            readSeconds: open.ReadSeconds,
+        }));
+        events.on("clicked", ({ click }) => record({
+            kind: "click",
+            ServerID: click.ServerID,
+            MessageStream: click.MessageStream,
+            Tag: click.Tag,
+            at: click.ReceivedAt,
+            MessageID: click.MessageID,
+            Recipient: click.Recipient,
+            first: runtime.store.state.clicks.includes(click),
+            link: click.OriginalLink,
+            location: click.ClickLocation,
+            platform: click.Platform,
+            browser: click.Client?.Family ?? null,
+        }));
+    },
+};
+export default stats;

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

@@ -0,0 +1,4 @@
+import type { Plugin } from "../plugins.ts";
+/** The webhook emitter: every domain event becomes a POST to the hooks that ask for it (docs/05 §5). */
+declare const webhooks: Plugin;
+export default webhooks;