@benclmnt/postmock 0.0.1

package/dist/src/render/mustachio.js

@@ -0,0 +1,265 @@
+import { Unsupported } from "../http/respond.js";
+// Postmark renders the unsubscribe placeholder at send time on broadcast streams (docs/03 §5.4);
+// the renderer keeps it as written.
+const UNSUBSCRIBE = /^pm:unsubscribe$/;
+const CONTENT = /^@content$/;
+// Key characters: letters, digits, `_`, `-` (INFERRED; the article shows only word keys).
+const PATH = /^((?:\.\.\/)*)([\p{L}\p{N}_-]+(?:\.[\p{L}\p{N}_-]+)*)$/u;
+// Error texts are INFERRED: only "The syntax for this template is invalid." is documented
+// (refs/api_templates-api.md:862).
+const messages = {
+    syntax: "The syntax for this template is invalid.",
+    path: (raw) => `The path '${raw}' is not valid. Please see documentation for examples of valid paths.`,
+    unclosed: (raw) => `A block for the path '${raw}' was opened but not closed. Close it with '{{/${raw}}}'.`,
+    unopened: (raw) => `A closing tag '{{/${raw}}}' was found without a matching opening tag.`,
+};
+function parsePath(raw) {
+    if (raw === ".")
+        return { raw, up: 0, keys: [] };
+    const match = PATH.exec(raw);
+    if (!match)
+        return undefined;
+    return { raw, up: (match[1] ?? "").length / 3, keys: (match[2] ?? "").split(".") };
+}
+function positionOf(source, index) {
+    const before = source.slice(0, index);
+    const lineStart = before.lastIndexOf("\n") + 1;
+    return { line: before.split("\n").length, column: index - lineStart + 1 };
+}
+/** Parses Mustachio source. Every syntax error is collected with its position. */
+export function parseTemplate(source) {
+    const errors = [];
+    const root = [];
+    const stack = [];
+    let contentPlaceholders = 0;
+    const target = () => stack.at(-1)?.node.children ?? root;
+    const fail = (message, at) => errors.push({ Message: message, Line: at.line, CharacterPosition: at.column });
+    let index = 0;
+    while (index < source.length) {
+        const open = source.indexOf("{{", index);
+        if (open === -1) {
+            target().push({ kind: "text", text: source.slice(index) });
+            break;
+        }
+        if (open > index)
+            target().push({ kind: "text", text: source.slice(index, open) });
+        const at = positionOf(source, open);
+        const triple = source.startsWith("{{{", open);
+        const closer = triple ? "}}}" : "}}";
+        const end = source.indexOf(closer, open + closer.length);
+        // An unterminated tag is an error, not text (INFERRED).
+        if (end === -1) {
+            fail(messages.syntax, at);
+            break;
+        }
+        const tag = source.slice(open, end + closer.length);
+        const inner = source.slice(open + closer.length, end).trim();
+        index = end + closer.length;
+        if (UNSUBSCRIBE.test(inner)) {
+            target().push({ kind: "text", text: tag });
+            continue;
+        }
+        if (triple || inner.startsWith("&")) {
+            const raw = triple ? inner : inner.slice(1).trim();
+            if (triple && CONTENT.test(raw)) {
+                contentPlaceholders += 1;
+                target().push({ kind: "content" });
+                continue;
+            }
+            const path = parsePath(raw);
+            if (path)
+                target().push({ kind: "value", path, escape: false });
+            else
+                fail(messages.path(raw), at);
+            continue;
+        }
+        const sigil = inner.charAt(0);
+        if (sigil === "!" || sigil === ">" || sigil === "=") {
+            // Comments, partials and delimiter changes are not in the article.
+            throw new Unsupported(`Mustachio tag '${tag}' is not documented (docs/06 §3.5)`);
+        }
+        if (sigil === "#" || sigil === "^") {
+            const body = inner.slice(1).trim();
+            const each = sigil === "#" ? /^each\s+(.+)$/.exec(body) : null;
+            const raw = each ? (each[1] ?? "").trim() : body;
+            // A bad path still opens a block, so its close tag adds no second error.
+            const path = parsePath(raw) ?? { raw, up: 0, keys: [] };
+            if (path.keys.length === 0 && raw !== ".")
+                fail(messages.path(raw), at);
+            const node = each
+                ? { kind: "each", path, children: [] }
+                : { kind: "section", path, inverted: sigil === "^", children: [] };
+            target().push(node);
+            stack.push({ node, closeName: each ? "each" : raw, at });
+            continue;
+        }
+        if (sigil === "/") {
+            const name = inner.slice(1).trim();
+            if (stack.at(-1)?.closeName === name)
+                stack.pop();
+            else
+                fail(messages.unopened(name), at);
+            continue;
+        }
+        const path = parsePath(inner);
+        if (path)
+            target().push({ kind: "value", path, escape: true });
+        else
+            fail(messages.path(inner), at);
+    }
+    for (const open of stack) {
+        fail(messages.unclosed(open.node.path.raw), open.at);
+    }
+    return errors.length > 0
+        ? { ok: false, errors }
+        : { ok: true, template: { nodes: root, contentPlaceholders } };
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function resolve(path, scopes) {
+    // Each `../` leaves one scope; `{{#each}}` opens two: the collection, then the item (article :98-107).
+    let value = scopes[scopes.length - 1 - path.up];
+    for (const key of path.keys) {
+        value = isObject(value) && Object.hasOwn(value, key) ? value[key] : undefined;
+    }
+    return value;
+}
+// Missing, null, false and empty values skip a section (article :111, :264). Zero skips it too
+// (INFERRED, as in Mustache).
+const truthy = (value) => value !== undefined &&
+    value !== null &&
+    value !== false &&
+    value !== 0 &&
+    value !== "" &&
+    !(Array.isArray(value) && value.length === 0);
+// `{{x}}` HTML-encodes in every part (article :300). The encoded set is INFERRED.
+const ENTITIES = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+const escapeHtml = (text) => text.replace(/[&<>"']/g, (c) => ENTITIES[c] ?? c);
+function scalarText(value, raw) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return String(value);
+    // .NET prints booleans as True/False (INFERRED).
+    if (typeof value === "boolean")
+        return value ? "True" : "False";
+    throw new Unsupported(`rendering the object or array at '{{${raw}}}' is not captured`);
+}
+/**
+ * Renders a parsed template with a model. `content` fills `{{{ @content }}}` in a layout.
+ * A missing value renders as "" (docs/06 §3.5, INFERRED).
+ */
+export function renderTemplate(template, model, content = "") {
+    const renderNode = (node, scopes) => {
+        switch (node.kind) {
+            case "text":
+                return node.text;
+            case "content":
+                return content;
+            case "value": {
+                const text = scalarText(resolve(node.path, scopes), node.path.raw);
+                return node.escape ? escapeHtml(text) : text;
+            }
+            case "section": {
+                const value = resolve(node.path, scopes);
+                if (node.inverted)
+                    return truthy(value) ? "" : render(node.children, scopes);
+                if (!truthy(value))
+                    return "";
+                // Mustache iterates here; the article iterates only with `#each`.
+                if (Array.isArray(value)) {
+                    throw new Unsupported(`'{{#${node.path.raw}}}' on a list is not captured; use #each`);
+                }
+                return render(node.children, [...scopes, value]);
+            }
+            case "each": {
+                const value = resolve(node.path, scopes);
+                if (!truthy(value))
+                    return "";
+                if (!Array.isArray(value)) {
+                    throw new Unsupported(`'{{#each ${node.path.raw}}}' on a non-list is not captured`);
+                }
+                return value.map((item) => render(node.children, [...scopes, value, item])).join("");
+            }
+        }
+    };
+    const render = (nodes, scopes) => nodes.map((node) => renderNode(node, scopes)).join("");
+    return render(template.nodes, [model]);
+}
+const newInferred = () => ({ usage: "value", children: new Map() });
+/** Collects every key a template reads into `into` (root of the suggested model). */
+function inferInto(template, into) {
+    // A scope entry is null where no key can be added: the list level of `#each`.
+    const walk = (nodes, scopes) => {
+        for (const node of nodes) {
+            if (node.kind === "text" || node.kind === "content")
+                continue;
+            let target = scopes[scopes.length - 1 - node.path.up] ?? null;
+            node.path.keys.forEach((key) => {
+                if (target === null)
+                    return;
+                if (target.usage === "value")
+                    target.usage = "object";
+                const child = target.children.get(key) ?? newInferred();
+                target.children.set(key, child);
+                target = child;
+            });
+            if (node.kind === "value")
+                continue;
+            if (target === null || node.path.keys.length === 0) {
+                const inner = node.kind === "each" ? [null, target] : [target];
+                walk(node.children, [...scopes, ...inner]);
+                continue;
+            }
+            if (node.kind === "each") {
+                target.usage = "collection";
+                walk(node.children, [...scopes, null, target]);
+            }
+            else {
+                if (target.usage === "value")
+                    target.usage = "object";
+                walk(node.children, [...scopes, target]);
+            }
+        }
+    };
+    walk(template.nodes, [into]);
+}
+function modelOf(key, node) {
+    const inner = () => node.children.size === 0
+        ? `${key}_Value`
+        : Object.fromEntries([...node.children].map(([k, child]) => [k, modelOf(k, child)]));
+    // A list gets three items: sdk/postmark-dotnet/src/Postmark.Tests/ClientTemplateTests.cs:203-205.
+    if (node.usage === "collection")
+        return [inner(), inner(), inner()];
+    return inner();
+}
+/**
+ * `SuggestedTemplateModel`: a placeholder `<key>_Value` for every key the templates read
+ * (refs/api_templates-api.md:844, :873-886).
+ */
+export function suggestModel(templates) {
+    const root = newInferred();
+    for (const template of templates)
+        inferInto(template, root);
+    return Object.fromEntries([...root.children].map(([k, child]) => [k, modelOf(k, child)]));
+}
+/** Deep merge; `override` values win and its keys come first (refs/api_templates-api.md:873-886). */
+export function mergeModels(base, override) {
+    const out = {};
+    for (const [key, value] of Object.entries(override)) {
+        const under = base[key];
+        out[key] = isObject(value) && isObject(under) ? mergeModels(under, value) : value;
+    }
+    for (const [key, value] of Object.entries(base)) {
+        if (!(key in out))
+            out[key] = value;
+    }
+    return out;
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,12 @@
+import { EventBus } from "./events.ts";
+import { type Plugin } from "./plugins.ts";
+import { Clock } from "./state/clock.ts";
+import { Store } from "./state/store.ts";
+/** Everything a request handler, the pipeline, a seed, a plugin or a listener shares. */
+export interface Runtime {
+    store: Store;
+    events: EventBus;
+    clock: Clock;
+}
+/** A runtime with every plugin installed. Tests pass a `Clock` with a frozen real time. */
+export declare function createRuntime(plugins?: readonly Plugin[], clock?: Clock): Runtime;

package/dist/src/runtime.js

@@ -0,0 +1,11 @@
+import { EventBus } from "./events.js";
+import { PLUGINS } from "./plugins.js";
+import { Clock } from "./state/clock.js";
+import { Store } from "./state/store.js";
+/** A runtime with every plugin installed. Tests pass a `Clock` with a frozen real time. */
+export function createRuntime(plugins = PLUGINS, clock = new Clock()) {
+    const runtime = { store: new Store(), events: new EventBus(), clock };
+    for (const plugin of plugins)
+        plugin.install?.(runtime);
+    return runtime;
+}

package/dist/src/server.d.ts

@@ -0,0 +1,25 @@
+import { type Plugin } from "./plugins.ts";
+import { type Runtime } from "./runtime.ts";
+export interface PostmockConfig {
+    host: string;
+    /** Plain-http REST port; 0 picks a free port. */
+    apiPort: number;
+    controlPort: number;
+    /** REST over TLS for DNS routing (docs/01 §3.3 option B): PEM key and cert for the Postmark host names. */
+    https?: {
+        port: number;
+        key: string;
+        cert: string;
+    };
+    seed: string;
+    /** Defaults to every plugin in `src/plugins/`. */
+    plugins?: readonly Plugin[];
+}
+export interface RunningPostmock {
+    runtime: Runtime;
+    /** URL per listener: `api`, `control`, `https` when configured, and one per plugin listener. */
+    listeners: Record<string, string>;
+    close(): Promise<void>;
+}
+/** Seeds the state, then starts the REST, control and plugin listeners. */
+export declare function startPostmock(config: PostmockConfig): Promise<RunningPostmock>;

package/dist/src/server.js

@@ -0,0 +1,49 @@
+import { createServer as createHttpsServer } from "node:https";
+import { serve } from "@hono/node-server";
+import { createControlApp } from "./control/app.js";
+import { applySeed } from "./control/seed.js";
+import { createApiApp } from "./http/app.js";
+import { PLUGINS } from "./plugins.js";
+import { createRuntime } from "./runtime.js";
+function listen(name, fetch, host, port, tls) {
+    return new Promise((resolve) => {
+        const onListen = (info) => resolve({
+            name,
+            url: `${tls ? "https" : "http"}://${host}:${info.port}`,
+            close: () => new Promise((done, fail) => server.close((e) => (e ? fail(e) : done()))),
+        });
+        const server = tls
+            ? serve({ fetch, hostname: host, port, createServer: createHttpsServer, serverOptions: tls }, onListen)
+            : serve({ fetch, hostname: host, port }, onListen);
+    });
+}
+/** Seeds the state, then starts the REST, control and plugin listeners. */
+export async function startPostmock(config) {
+    const runtime = createRuntime(config.plugins ?? PLUGINS);
+    await applySeed(runtime, config.seed);
+    const api = createApiApp(runtime);
+    const started = [await listen("api", api.fetch, config.host, config.apiPort)];
+    if (config.https) {
+        const { port, key, cert } = config.https;
+        started.push(await listen("https", api.fetch, config.host, port, { key, cert }));
+    }
+    for (const plugin of config.plugins ?? PLUGINS) {
+        if (plugin.start)
+            started.push(await plugin.start(runtime, config.host));
+    }
+    // Control binds last: once it answers, every listener is up (the Compose health check).
+    started.push(await listen("control", createControlApp(runtime, config.seed).fetch, config.host, config.controlPort));
+    const names = started.map((l) => l.name);
+    const duplicate = names.find((n, i) => names.indexOf(n) !== i);
+    if (duplicate !== undefined)
+        throw new Error(`two listeners named ${duplicate}`);
+    return {
+        runtime,
+        listeners: Object.fromEntries(started.map((l) => [l.name, l.url])),
+        close: async () => {
+            await Promise.all(started.map((l) => l.close()));
+            await runtime.clock.idle();
+            runtime.clock.reset();
+        },
+    };
+}

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

@@ -0,0 +1,35 @@
+import type { State } from "../state/store.ts";
+import type { Server } from "../state/types.ts";
+/**
+ * Who an SMTP session authenticated as. Kept as the credential, not the server object, so a
+ * revoked token or a `POST /control/reset` takes effect on an open pooled connection.
+ */
+export type SmtpIdentity = {
+    kind: "serverToken";
+    token: string;
+} | {
+    kind: "smtpToken";
+    accessKey: string;
+};
+/** The server a message goes to, and the stream an SMTP token pins. */
+export interface SmtpSender {
+    server: Server;
+    /** Set for an SMTP token (one token per stream, docs/07 §1.2); null for a server token. */
+    tokenStream: string | null;
+}
+/** What `smtp-server` hands to `onAuth`: PLAIN and LOGIN carry a password, CRAM-MD5 a verifier. */
+export type AuthAttempt = {
+    username: string;
+    password: string;
+} | {
+    username: string;
+    validatePassword(password: string): boolean;
+};
+/**
+ * docs/07 §1.2: a server API token is both username and password; an SMTP token is Access Key and
+ * Secret Key. An account token, an unknown or revoked token, and a server with
+ * `SmtpApiActivated: false` fail AUTH. DIGEST-MD5 never reaches here: it is not offered (504).
+ */
+export declare function authenticate(state: State, attempt: AuthAttempt): SmtpIdentity;
+/** The current sender for an identity; throws 535 once the token or its SMTP access is gone. */
+export declare function resolveSender(state: State, identity: SmtpIdentity): SmtpSender;

package/dist/src/smtp/auth.js

@@ -0,0 +1,66 @@
+import { Unsupported } from "../http/respond.js";
+import { TEST_TOKEN } from "../state/servers.js";
+import { SmtpReply } from "./reply.js";
+// Reply code and text for bad credentials are not captured (docs/07 §1.4, Q3): INFERRED 535.
+const invalid = () => new SmtpReply(535, "Authentication credentials invalid");
+const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+function passwordMatches(attempt, expected, ignoreCase) {
+    if ("validatePassword" in attempt)
+        return attempt.validatePassword(expected);
+    return ignoreCase ? same(attempt.password, expected) : attempt.password === expected;
+}
+/**
+ * docs/07 §1.2: a server API token is both username and password; an SMTP token is Access Key and
+ * Secret Key. An account token, an unknown or revoked token, and a server with
+ * `SmtpApiActivated: false` fail AUTH. DIGEST-MD5 never reaches here: it is not offered (504).
+ */
+export function authenticate(state, attempt) {
+    const { username } = attempt;
+    // docs/07 §2.2 Q4: whether POSTMARK_API_TEST works over SMTP is not captured.
+    if (same(username, TEST_TOKEN)) {
+        throw new Unsupported(`${TEST_TOKEN} over SMTP is not captured (docs/07 Q4)`);
+    }
+    const smtpToken = state.smtpTokens.get(username);
+    if (smtpToken !== undefined) {
+        if (!passwordMatches(attempt, smtpToken.secretKey, false))
+            throw invalid();
+        const identity = { kind: "smtpToken", accessKey: username };
+        resolveSender(state, identity);
+        return identity;
+    }
+    const held = serverByToken(state, username);
+    // Server tokens compare without case, as on REST (docs/02 §3.1). CRAM-MD5 hashes the stored
+    // spelling, so a client there must send the token as stored.
+    if (held === undefined || !passwordMatches(attempt, held.token, true))
+        throw invalid();
+    const identity = { kind: "serverToken", token: held.token };
+    resolveSender(state, identity);
+    return identity;
+}
+function serverByToken(state, token) {
+    for (const server of state.servers.values()) {
+        const stored = server.ApiTokens.find((t) => same(t, token));
+        if (stored !== undefined)
+            return { server, token: stored };
+    }
+    return undefined;
+}
+/** The current sender for an identity; throws 535 once the token or its SMTP access is gone. */
+export function resolveSender(state, identity) {
+    let sender;
+    if (identity.kind === "serverToken") {
+        const held = serverByToken(state, identity.token);
+        if (held !== undefined)
+            sender = { server: held.server, tokenStream: null };
+    }
+    else {
+        const token = state.smtpTokens.get(identity.accessKey);
+        const server = token && state.servers.get(token.serverId);
+        if (token !== undefined && server !== undefined) {
+            sender = { server, tokenStream: token.messageStream };
+        }
+    }
+    if (sender === undefined || !sender.server.SmtpApiActivated)
+        throw invalid();
+    return sender;
+}

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

@@ -0,0 +1,16 @@
+import type { StartedListener } from "../plugins.ts";
+import type { Runtime } from "../runtime.ts";
+/** 10 MB total, measured after base64 (docs/07 §3). Advertised as EHLO `SIZE`; same on SMTP is INFERRED. */
+export declare const MAX_MESSAGE_BYTES: number;
+export interface SmtpOptions {
+    host: string;
+    /** Every port serves the same listener; `0` picks a free port. */
+    ports: number[];
+    /** PEM key and cert. With them the listener offers STARTTLS; it never requires it (docs/07 §1.2). */
+    tls: {
+        key: string;
+        cert: string;
+    } | null;
+}
+/** Starts the Postmark SMTP endpoint (docs/07 §1). The URL names the first port. */
+export declare function startSmtp(runtime: Runtime, options: SmtpOptions): Promise<StartedListener>;

package/dist/src/smtp/listener.js

@@ -0,0 +1,121 @@
+import { SMTPServer } from "smtp-server";
+import { Unsupported } from "../http/respond.js";
+import { authenticate, resolveSender } from "./auth.js";
+import { receive } from "./receive.js";
+import { SmtpReply, takeFault, UNSUPPORTED_CODE } from "./reply.js";
+/** 10 MB total, measured after base64 (docs/07 §3). Advertised as EHLO `SIZE`; same on SMTP is INFERRED. */
+export const MAX_MESSAGE_BYTES = 10 * 1024 * 1024;
+// setTimeout's ceiling. Postmark's idle timeout is not captured (docs/07 Q11), so postmock never
+// closes an idle connection; smtp-server reads 0 as its 60 s default.
+const NEVER_MS = 2 ** 31 - 1;
+/** An `smtp-server` callback error: an `SmtpReply`, a 502 for `Unsupported`, else a crash (554). */
+function toReply(error) {
+    if (error instanceof SmtpReply)
+        return error;
+    if (error instanceof Unsupported)
+        return new SmtpReply(UNSUPPORTED_CODE, `postmock: ${error.message}`);
+    console.error(error);
+    return new SmtpReply(554, `postmock crashed: ${error.message}`);
+}
+const settle = (work, callback) => {
+    Promise.resolve()
+        .then(work)
+        .then((value) => callback(null, value), (error) => callback(toReply(error)));
+};
+function createServer(runtime, options) {
+    const identities = new WeakMap();
+    const identity = (session) => {
+        const found = identities.get(session);
+        if (found === undefined)
+            throw new Error("smtp-server let an unauthenticated session through");
+        return found;
+    };
+    const server = new SMTPServer({
+        // Greeting name and EHLO order are not captured (docs/07 Q2).
+        name: "postmock",
+        banner: "postmock",
+        // docs/07 Mock must: AUTH PLAIN LOGIN CRAM-MD5, before or after STARTTLS; DIGEST-MD5 gets 504.
+        authMethods: ["PLAIN", "LOGIN", "CRAM-MD5"],
+        allowInsecureAuth: true,
+        authOptional: false,
+        size: MAX_MESSAGE_BYTES,
+        disableReverseLookup: true,
+        socketTimeout: NEVER_MS,
+        closeTimeout: 1,
+        // Without 8BITMIME a client encodes 8-bit bodies, so the stored source keeps every byte as
+        // UTF-8 text. Postmark's EHLO list is not captured (docs/07 Q2).
+        hide8BITMIME: true,
+        ...(options.tls === null ? { hideSTARTTLS: true } : options.tls),
+        onConnect: (_session, callback) => settle(() => takeFault(runtime.store, "connect"), callback),
+        onAuth: (auth, session, callback) => settle(() => {
+            // @types/smtp-server omits CRAM-MD5, which passes `validatePassword` instead of a password.
+            const cram = auth;
+            const username = auth.username ?? "";
+            const attempt = cram.validatePassword === undefined
+                ? { username, password: auth.password ?? "" }
+                : { username, validatePassword: cram.validatePassword };
+            identities.set(session, authenticate(runtime.store.state, attempt));
+            return { user: attempt.username };
+        }, callback),
+        onMailFrom: (_address, session, callback) => settle(() => {
+            resolveSender(runtime.store.state, identity(session));
+            takeFault(runtime.store, "mail");
+        }, callback),
+        // docs/07 §1.4: every recipient is accepted; problems become SMTPApiError bounces after DATA.
+        onRcptTo: (_address, _session, callback) => settle(() => takeFault(runtime.store, "rcpt"), callback),
+        onData: (stream, session, callback) => settle(async () => {
+            const raw = await collect(stream);
+            // Oversize at DATA: SMTP 552 is INFERRED (docs/07 Q3).
+            if (stream.sizeExceeded) {
+                throw new SmtpReply(552, `Message exceeds fixed maximum message size ${MAX_MESSAGE_BYTES}`);
+            }
+            const sender = resolveSender(runtime.store.state, identity(session));
+            takeFault(runtime.store, "data");
+            const rcptTo = session.envelope.rcptTo.map((r) => r.address);
+            const messageId = await receive(runtime, sender, raw, rcptTo);
+            // The 250 text is not captured (docs/07 Q1); naming the MessageID is INFERRED.
+            return `Ok: queued as ${messageId}`;
+        }, callback),
+    });
+    // A client that drops the socket mid-transaction is normal pool behavior (docs/07 §1.6).
+    server.on("error", (error) => {
+        if (error.code !== "ECONNRESET" && error.code !== "EPIPE")
+            console.error(error);
+    });
+    return server;
+}
+const collect = async (stream) => {
+    const chunks = [];
+    for await (const chunk of stream)
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+};
+function listen(server, host, port) {
+    return new Promise((resolve, reject) => {
+        server.server.once("error", reject);
+        server.listen(port, host, () => {
+            server.server.off("error", reject);
+            resolve(server.server.address().port);
+        });
+    });
+}
+/** Starts the Postmark SMTP endpoint (docs/07 §1). The URL names the first port. */
+export async function startSmtp(runtime, options) {
+    const servers = [];
+    const ports = [];
+    const close = async () => {
+        await Promise.all(servers.map((s) => new Promise((done) => s.close(() => done()))));
+    };
+    try {
+        for (const port of options.ports) {
+            const server = createServer(runtime, options);
+            servers.push(server);
+            ports.push(await listen(server, options.host, port));
+        }
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+    return { name: "smtp", url: `smtp://${options.host}:${ports[0]}`, close };
+}

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

@@ -0,0 +1,36 @@
+import type { ParsedMail } from "mailparser";
+import type { OutboundDraft } from "../pipeline/submit.ts";
+import type { SmtpSender } from "./auth.ts";
+/** mailparser options: keep the bodies as sent; derive nothing. */
+export declare const PARSE_OPTIONS: {
+    readonly skipHtmlToText: true;
+    readonly skipTextToHtml: true;
+    readonly skipTextLinks: true;
+    readonly skipImageLinks: true;
+};
+export interface SmtpDraft {
+    draft: OutboundDraft & {
+        From: string | undefined;
+        Tag: string | undefined;
+        Metadata: Record<string, string>;
+    };
+    /** The stream the message goes to, for an `SMTPApiError` bounce when the draft is rejected. */
+    stream: string;
+    keepId: boolean;
+}
+/**
+ * Maps one parsed SMTP transaction to a raw draft. `submitOutbound` checks every value
+ * (docs/11 §2). Recipients come from the envelope (docs/07 Mock must). The `To` and `Cc` headers
+ * only sort them and name them; an `RCPT TO` address neither header names is a Bcc, since clients
+ * strip the `Bcc` header (docs/07 §1.1). A header address outside the envelope is dropped (INFERRED).
+ */
+export declare function draftFromMime(mail: ParsedMail, rcptTo: string[], sender: SmtpSender): SmtpDraft;
+/**
+ * The copy Postmark delivers and serves as the raw source: incoming `X-PM-*` headers removed
+ * (docs/07 §1.3), `X-PM-Tag` added as in the dump example (refs/api_messages-api.md:276), and
+ * every `Message-ID` replaced unless `X-PM-KeepID: true`
+ * (refs/user-guide_send-email-with-smtp.md:101). The replacement `<uuid@mtasv.net>` is INFERRED.
+ * The dump example's `X-PM-Message-Id` is left out: the pipeline mints the MessageID after this
+ * source is built. The body bytes stay unchanged.
+ */
+export declare function deliveredSource(raw: string, tag: string | undefined, keepId: boolean): string;