@benclmnt/postmock 0.0.1

package/dist/src/smtp/mime.js

@@ -0,0 +1,181 @@
+import { randomUUID } from "node:crypto";
+import libmime from "libmime";
+import { Unsupported } from "../http/respond.js";
+/** mailparser options: keep the bodies as sent; derive nothing. */
+export const PARSE_OPTIONS = {
+    skipHtmlToText: true,
+    skipTextToHtml: true,
+    skipTextLinks: true,
+    skipImageLinks: true,
+};
+/** Header lines that become draft fields or MIME structure, not custom `Headers` (INFERRED). */
+const STRUCTURAL = new Set([
+    "from",
+    "to",
+    "cc",
+    "bcc",
+    "reply-to",
+    "subject",
+    "date",
+    "message-id",
+    "mime-version",
+    "content-type",
+    "content-transfer-encoding",
+]);
+/** X-PM-* headers that set draft fields (docs/07 §1.3). Other X-PM-* go to `Headers`. */
+const FIELD_HEADERS = new Set([
+    "x-pm-message-stream",
+    "x-pm-tag",
+    "x-pm-trackopens",
+    "x-pm-tracklinks",
+    "x-pm-keepid",
+]);
+const METADATA_PREFIX = "x-pm-metadata-";
+/**
+ * Header lines in order, unfolded, RFC 2047 encoded-words decoded (nodemailer encodes every
+ * non-ASCII header value, docs/07 §1.7). Empty values are absent.
+ */
+function rawHeaders(mail) {
+    return mail.headerLines.map(({ line }) => {
+        const colon = line.indexOf(":");
+        return {
+            name: line.slice(0, colon).trim(),
+            value: libmime.decodeWords(line
+                .slice(colon + 1)
+                .replace(/\r?\n(?=[ \t])/g, "")
+                .trim()),
+        };
+    });
+}
+const flatten = (list) => list.flatMap((a) => (a.group === undefined ? [a] : flatten(a.group)));
+const addresses = (field) => field === undefined ? [] : flatten([field].flat().flatMap((o) => o.value));
+/**
+ * A Postmark address list: `"Name" <a@b>, c@d` (docs/03 §1.8), with decoded display names.
+ * An entry mailparser found no address in stays as its text, so the pipeline rejects it.
+ */
+const addressText = (list) => list.length === 0
+    ? undefined
+    : list
+        .map((a) => {
+        if (!a.address)
+            return a.name;
+        if (a.name === "")
+            return a.address;
+        return `"${a.name.replace(/["\\]/g, "\\$&")}" <${a.address}>`;
+    })
+        .join(", ");
+/**
+ * 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 function draftFromMime(mail, rcptTo, sender) {
+    const headers = rawHeaders(mail);
+    const first = (name) => headers.find((h) => h.name.toLowerCase() === name && h.value !== "")?.value;
+    const envelope = new Set(rcptTo.map((r) => r.toLowerCase()));
+    const claimed = new Set();
+    // A malformed entry (no address) stays, so the pipeline rejects it.
+    const sort = (list) => list.filter((a) => {
+        if (!a.address)
+            return true;
+        const key = a.address.toLowerCase();
+        if (!envelope.has(key) || claimed.has(key))
+            return false;
+        claimed.add(key);
+        return true;
+    });
+    const to = sort(addresses(mail.to));
+    const cc = sort(addresses(mail.cc));
+    const bcc = rcptTo.filter((r) => !claimed.has(r.toLowerCase()));
+    const streamHeader = first("x-pm-message-stream");
+    let stream = streamHeader ?? "outbound";
+    if (sender.tokenStream !== null) {
+        // docs/07 Q13: an SMTP token with a header naming another stream is not captured.
+        if (streamHeader !== undefined && streamHeader !== sender.tokenStream) {
+            throw new Unsupported(`X-PM-Message-Stream '${streamHeader}' with an SMTP token for '${sender.tokenStream}' is not captured (docs/07 Q13)`);
+        }
+        stream = sender.tokenStream;
+    }
+    const metadata = {};
+    const custom = [];
+    const keepId = first("x-pm-keepid")?.toLowerCase() === "true";
+    for (const header of headers) {
+        const lower = header.name.toLowerCase();
+        if (lower.startsWith(METADATA_PREFIX)) {
+            addMetadata(metadata, header.name.slice(METADATA_PREFIX.length), header.value);
+        }
+        else if (lower === "message-id" && keepId) {
+            custom.push(header);
+        }
+        else if (!STRUCTURAL.has(lower) && !FIELD_HEADERS.has(lower)) {
+            custom.push(header);
+        }
+    }
+    const draft = {
+        From: addressText(addresses(mail.from)),
+        To: addressText(to),
+        Cc: addressText(cc),
+        Bcc: bcc.length === 0 ? undefined : bcc.join(", "),
+        ReplyTo: addressText(addresses(mail.replyTo)),
+        Subject: mail.subject,
+        HtmlBody: mail.html === false ? undefined : mail.html,
+        TextBody: mail.text,
+        Tag: first("x-pm-tag"),
+        MessageStream: stream,
+        Headers: custom.map((h) => ({ Name: h.name, Value: h.value })),
+        // A part with no file name, disposition or Content-ID is a body alternative (for example
+        // `text/calendar; method=REQUEST`), not an attachment; it stays in the raw source.
+        Attachments: mail.attachments
+            .filter((a) => a.filename !== undefined || a.contentDisposition !== undefined || a.cid !== undefined)
+            .map((a) => ({
+            Name: a.filename ?? "",
+            Content: a.content.toString("base64"),
+            ContentType: a.contentType,
+            ContentID: a.cid === undefined ? null : `cid:${a.cid}`,
+        })),
+        Metadata: metadata,
+        TrackOpens: first("x-pm-trackopens"),
+        TrackLinks: first("x-pm-tracklinks"),
+    };
+    return { draft, stream, keepId };
+}
+/**
+ * "When sending with SMTP, if you add duplicate keys, we will append the additional keys with an
+ * incremental number" (refs/support_article_1125-custom-metadata-faq.md:70). Duplicates compare
+ * without case as on the API (`:68-69`); that SMTP uses the API rule and the suffix form
+ * `key1`, `key2` are INFERRED.
+ */
+function addMetadata(metadata, key, value) {
+    const taken = (k) => Object.keys(metadata).some((m) => m.toLowerCase() === k.toLowerCase());
+    let name = key;
+    for (let n = 1; taken(name); n += 1)
+        name = `${key}${n}`;
+    metadata[name] = value;
+}
+/**
+ * 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 function deliveredSource(raw, tag, keepId) {
+    const split = /\r?\n\r?\n/.exec(raw);
+    const head = split === null ? raw : raw.slice(0, split.index);
+    const body = split === null ? "" : raw.slice(split.index);
+    const eol = head.includes("\r\n") ? "\r\n" : "\n";
+    const lines = head.split(/\r?\n(?![ \t])/);
+    const kept = lines.filter((line) => {
+        const name = line.slice(0, line.indexOf(":")).trim().toLowerCase();
+        return !name.startsWith("x-pm-") && (keepId || name !== "message-id");
+    });
+    const added = [
+        ...(tag === undefined ? [] : [`X-PM-Tag: ${tag}`]),
+        ...(keepId && kept.some((l) => /^message-id\s*:/i.test(l))
+            ? []
+            : [`Message-ID: <${randomUUID()}@mtasv.net>`]),
+    ];
+    return [...kept, ...added].join(eol) + body;
+}

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

@@ -0,0 +1,21 @@
+import type { ErrorBody } from "../errors.ts";
+import type { Runtime } from "../runtime.ts";
+import { type Bounce } from "../state/types.ts";
+import type { SmtpSender } from "./auth.ts";
+/**
+ * One accepted DATA transaction. Postmark accepts every message at SMTP and turns each
+ * message-level error into an `SMTPApiError` bounce (docs/07 §1.4). Returns the Postmark MessageID.
+ */
+export declare function receive(runtime: Runtime, sender: SmtpSender, raw: Buffer, rcptTo: string[]): Promise<string>;
+export interface Failure {
+    serverId: number;
+    stream: string;
+    messageId: string;
+    tag: string | null;
+    from: string | null;
+    subject: string;
+    metadata: Record<string, string>;
+    source: string;
+}
+/** The `SMTPApiError` bounce of one recipient; a seed builds past ones with it. */
+export declare function smtpApiErrorBounce(id: number, at: Date, failure: Failure, email: string, error: ErrorBody): Bounce;

package/dist/src/smtp/receive.js

@@ -0,0 +1,89 @@
+import { simpleParser } from "mailparser";
+import { submitOutbound } from "../pipeline/submit.js";
+import { newMessageId } from "../state/ids.js";
+import { suppressionKey } from "../state/store.js";
+import { BOUNCE_TYPES } from "../state/types.js";
+import { deliveredSource, draftFromMime, PARSE_OPTIONS } from "./mime.js";
+/**
+ * One accepted DATA transaction. Postmark accepts every message at SMTP and turns each
+ * message-level error into an `SMTPApiError` bounce (docs/07 §1.4). Returns the Postmark MessageID.
+ */
+export async function receive(runtime, sender, raw, rcptTo) {
+    // Raw MIME as text. nodemailer writes 7-bit ASCII unless the content needs 8BITMIME/SMTPUTF8
+    // (docs/07 §1.7); UTF-8 is the only 8-bit form kept readable.
+    const source = raw.toString("utf8");
+    const mail = await simpleParser(raw, PARSE_OPTIONS);
+    const { draft, stream, keepId } = draftFromMime(mail, rcptTo, sender);
+    const result = await submitOutbound(runtime, {
+        auth: { kind: "server", server: sender.server },
+        channel: "smtp",
+        draft,
+        request: source,
+        rawSource: deliveredSource(source, draft.Tag, keepId),
+        bulkRequestId: null,
+        templateId: null,
+    });
+    const failure = {
+        serverId: sender.server.ID,
+        stream,
+        tag: draft.Tag ?? null,
+        from: draft.From ?? null,
+        subject: mail.subject ?? "",
+        metadata: draft.Metadata,
+        source,
+    };
+    switch (result.outcome) {
+        case "accepted":
+            return result.message.MessageID;
+        case "partiallySuppressed": {
+            const { message } = result;
+            const suppressed = [...message.To, ...message.Cc, ...message.Bcc]
+                .map((a) => a.Email)
+                .filter((email) => runtime.store.state.suppressions.has(suppressionKey(message.ServerID, message.MessageStream, email)));
+            await bounce(runtime, { ...failure, messageId: message.MessageID }, suppressed, result.error);
+            return message.MessageID;
+        }
+        case "rejected": {
+            const messageId = newMessageId();
+            await bounce(runtime, { ...failure, messageId }, rcptTo, result.error);
+            return messageId;
+        }
+        case "validated":
+            throw new Error("SMTP never authenticates with the test token");
+    }
+}
+/**
+ * One `SMTPApiError` (100007) bounce per affected recipient. Description is the short error; the
+ * raw content holds the error code, the long error and the SMTP message
+ * (refs/user-guide_send-email-with-smtp.md:87). One bounce per recipient, the content layout, and
+ * `Inactive`/`CanActivate` false are INFERRED (docs/07 Q9).
+ */
+async function bounce(runtime, failure, recipients, error) {
+    const { store, clock, events } = runtime;
+    for (const email of recipients) {
+        const record = smtpApiErrorBounce(store.nextId("bounce"), clock.now(), failure, email, error);
+        store.state.bounces.set(record.ID, record);
+        await events.emit("smtpApiError", { bounce: record });
+    }
+}
+/** The `SMTPApiError` bounce of one recipient; a seed builds past ones with it. */
+export function smtpApiErrorBounce(id, at, failure, email, error) {
+    return {
+        ID: id,
+        ServerID: failure.serverId,
+        MessageStream: failure.stream,
+        MessageID: failure.messageId,
+        Type: "SMTPApiError",
+        Tag: failure.tag,
+        Description: error.Message,
+        Details: BOUNCE_TYPES.SMTPApiError.Name,
+        Email: email,
+        From: failure.from,
+        Subject: failure.subject,
+        BouncedAt: at,
+        Inactive: false,
+        CanActivate: false,
+        Content: `ErrorCode: ${error.ErrorCode}\r\nMessage: ${error.Message}\r\n\r\n${failure.source}`,
+        Metadata: failure.metadata,
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { Store } from "../state/store.ts";
+import type { SmtpFault } from "../state/types.ts";
+/**
+ * An SMTP error reply. `smtp-server` sends `responseCode` and the message, and adds the enhanced
+ * status code itself. A 421 closes the connection.
+ */
+export declare class SmtpReply extends Error {
+    readonly responseCode: number;
+    constructor(responseCode: number, message: string);
+}
+/** Reply code for behavior postmock does not know yet; the SMTP twin of REST 501 `Unsupported`. */
+export declare const UNSUPPORTED_CODE = 502;
+/** Consumes one armed fault for the stage and throws its reply. */
+export declare function takeFault(store: Store, stage: SmtpFault["stage"]): void;

package/dist/src/smtp/reply.js

@@ -0,0 +1,24 @@
+/**
+ * An SMTP error reply. `smtp-server` sends `responseCode` and the message, and adds the enhanced
+ * status code itself. A 421 closes the connection.
+ */
+export class SmtpReply extends Error {
+    responseCode;
+    constructor(responseCode, message) {
+        super(message);
+        this.responseCode = responseCode;
+    }
+}
+/** Reply code for behavior postmock does not know yet; the SMTP twin of REST 501 `Unsupported`. */
+export const UNSUPPORTED_CODE = 502;
+/** Consumes one armed fault for the stage and throws its reply. */
+export function takeFault(store, stage) {
+    const faults = store.state.smtpFaults;
+    const fault = faults.find((f) => f.stage === stage);
+    if (fault === undefined)
+        return;
+    fault.remaining -= 1;
+    if (fault.remaining === 0)
+        faults.splice(faults.indexOf(fault), 1);
+    throw new SmtpReply(fault.code, fault.message);
+}

package/dist/src/state/clock.d.ts

@@ -0,0 +1,35 @@
+type Run = () => void | Promise<void>;
+/**
+ * Real time plus an offset that `advance()` grows (docs/09 §5 `clock/advance`).
+ * A scheduled task runs once: when real time reaches it, or when `advance()` passes it.
+ * Advances and real-timer tasks run one at a time, in the order they start.
+ */
+export declare class Clock {
+    private offsetMs;
+    private seq;
+    private advancing;
+    private queue;
+    private readonly tasks;
+    private readonly realNow;
+    constructor(realNow?: () => number);
+    now(): Date;
+    schedule(delayMs: number, run: Run): void;
+    /**
+     * Moves time forward by `ms`, after any advance already running. Runs each task due by the end in
+     * due order, with `now()` set to its due time, and awaits it. A task scheduled during the advance
+     * runs too when it falls due by the end.
+     */
+    advance(ms: number): Promise<void>;
+    /** Resolves when every advance and real-timer task started so far has finished. */
+    idle(): Promise<void>;
+    /** Drops pending tasks and the offset. Throws during an advance, which would undo it. */
+    reset(): void;
+    /** Captures offset and pending tasks; the returned function puts them back. */
+    checkpoint(): () => void;
+    private add;
+    private enqueue;
+    /** Time never moves back. */
+    private moveTo;
+    private take;
+}
+export {};

package/dist/src/state/clock.js

@@ -0,0 +1,107 @@
+// setTimeout fires at once for a delay above 2^31-1 ms; such a task waits for `advance()` only.
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * Real time plus an offset that `advance()` grows (docs/09 §5 `clock/advance`).
+ * A scheduled task runs once: when real time reaches it, or when `advance()` passes it.
+ * Advances and real-timer tasks run one at a time, in the order they start.
+ */
+export class Clock {
+    offsetMs = 0;
+    seq = 0;
+    advancing = false;
+    queue = Promise.resolve();
+    tasks = new Set();
+    realNow;
+    constructor(realNow = Date.now) {
+        this.realNow = realNow;
+    }
+    now() {
+        return new Date(this.realNow() + this.offsetMs);
+    }
+    schedule(delayMs, run) {
+        if (!Number.isInteger(delayMs) || delayMs < 0) {
+            throw new Error(`schedule needs delayMs >= 0, got ${delayMs}`);
+        }
+        this.add({ due: this.now().getTime() + delayMs, seq: this.seq++, run, timer: undefined });
+    }
+    /**
+     * Moves time forward by `ms`, after any advance already running. Runs each task due by the end in
+     * due order, with `now()` set to its due time, and awaits it. A task scheduled during the advance
+     * runs too when it falls due by the end.
+     */
+    advance(ms) {
+        if (!Number.isInteger(ms) || ms < 0) {
+            return Promise.reject(new Error(`clock.advance needs ms >= 0, got ${ms}`));
+        }
+        return this.enqueue(async () => {
+            this.advancing = true;
+            try {
+                const target = this.now().getTime() + ms;
+                for (;;) {
+                    const next = [...this.tasks]
+                        .filter((t) => t.due <= target)
+                        .sort((a, b) => a.due - b.due || a.seq - b.seq)[0];
+                    if (next === undefined)
+                        break;
+                    this.moveTo(next.due);
+                    await this.take(next);
+                }
+                this.moveTo(target);
+            }
+            finally {
+                this.advancing = false;
+            }
+        });
+    }
+    /** Resolves when every advance and real-timer task started so far has finished. */
+    idle() {
+        return this.queue;
+    }
+    /** Drops pending tasks and the offset. Throws during an advance, which would undo it. */
+    reset() {
+        if (this.advancing)
+            throw new Error("clock.reset during an advance");
+        for (const task of this.tasks)
+            clearTimeout(task.timer);
+        this.tasks.clear();
+        this.offsetMs = 0;
+    }
+    /** Captures offset and pending tasks; the returned function puts them back. */
+    checkpoint() {
+        const offsetMs = this.offsetMs;
+        const tasks = [...this.tasks].map(({ due, seq, run }) => ({ due, seq, run }));
+        return () => {
+            this.reset();
+            this.offsetMs = offsetMs;
+            for (const task of tasks)
+                this.add({ ...task, timer: undefined });
+        };
+    }
+    add(task) {
+        const delay = task.due - this.now().getTime();
+        if (delay <= MAX_TIMER_MS) {
+            // A task that throws on a real timer is a postmock bug: rethrow so the process crashes.
+            task.timer = setTimeout(() => {
+                this.enqueue(() => this.take(task)).catch((error) => queueMicrotask(() => {
+                    throw error;
+                }));
+            }, Math.max(0, delay)).unref();
+        }
+        this.tasks.add(task);
+    }
+    enqueue(work) {
+        const result = this.queue.then(work);
+        this.queue = result.then(() => { }, () => { });
+        return result;
+    }
+    /** Time never moves back. */
+    moveTo(instant) {
+        this.offsetMs = Math.max(this.now().getTime(), instant) - this.realNow();
+    }
+    async take(task) {
+        if (!this.tasks.delete(task))
+            return;
+        clearTimeout(task.timer);
+        await task.run();
+    }
+}

package/dist/src/state/ids.d.ts

@@ -0,0 +1,6 @@
+/** Postmark MessageID and bulk Id: a UUID (docs/08 E7). Lowercase hex as in doc examples (INFERRED). */
+export declare const newMessageId: () => string;
+/** A server or account token. The UUID shape matches no documented format (INFERRED). */
+export declare const newToken: () => string;
+/** Lowercase hex, for inbound hashes and SMTP token keys. */
+export declare const newHex: (bytes: number) => string;

package/dist/src/state/ids.js

@@ -0,0 +1,7 @@
+import { randomBytes, randomUUID } from "node:crypto";
+/** Postmark MessageID and bulk Id: a UUID (docs/08 E7). Lowercase hex as in doc examples (INFERRED). */
+export const newMessageId = () => randomUUID();
+/** A server or account token. The UUID shape matches no documented format (INFERRED). */
+export const newToken = () => randomUUID();
+/** Lowercase hex, for inbound hashes and SMTP token keys. */
+export const newHex = (bytes) => randomBytes(bytes).toString("hex");

package/dist/src/state/servers.d.ts

@@ -0,0 +1,27 @@
+export declare const TEST_TOKEN = "POSTMARK_API_TEST";
+import { type State, type Store } from "./store.ts";
+import type { MessageStream, Server } from "./types.ts";
+export type ServerSettings = Partial<Omit<Server, "ServerLink" | "InboundAddress">>;
+/**
+ * Creates a server with one API token and the default streams. `settings.ID` claims a fixed ID.
+ * A token that another server already holds throws: auth could not tell the two apart.
+ */
+export declare function createServer(store: Store, now: Date, settings?: ServerSettings): Server;
+/** Adds an account token. Tokens compare without case (docs/02 §3.1). */
+export declare function addAccountToken(store: Store, token: string): void;
+/**
+ * What `POSTMARK_API_TEST` sends against: a new server with default settings and the default
+ * streams, stored nowhere. It validates like a live server and delivers nothing (docs/03 §4).
+ * That it sees only the default streams and settings is INFERRED.
+ */
+export interface TestTokenContext {
+    kind: "test";
+    server: Server;
+    streams: MessageStream[];
+}
+export declare const testTokenContext: (now: Date) => TestTokenContext;
+/** A stream of the server the request authenticated as, stored or test-token. */
+export declare function findStream(state: State, auth: {
+    kind: "server";
+    server: Server;
+} | TestTokenContext, streamId: string): MessageStream | undefined;

package/dist/src/state/servers.js

@@ -0,0 +1,101 @@
+export const TEST_TOKEN = "POSTMARK_API_TEST";
+import { newHex, newToken } from "./ids.js";
+import { streamKey } from "./store.js";
+// A new server has these three streams (docs/04 §4.3; Q7 for the broadcast id).
+const DEFAULT_STREAMS = [
+    ["outbound", "Default Transactional Stream", "Transactional"],
+    ["inbound", "Default Inbound Stream", "Inbound"],
+    ["broadcast", "Default Broadcast Stream", "Broadcasts"],
+];
+function newServer(id, tokens, settings) {
+    const hash = settings.InboundHash ?? newHex(16);
+    return {
+        Name: `Server ${id}`,
+        ApiTokens: tokens,
+        Color: "purple",
+        SmtpApiActivated: true,
+        RawEmailEnabled: false,
+        DeliveryType: "Live",
+        InboundHookUrl: "",
+        BounceHookUrl: "",
+        OpenHookUrl: "",
+        DeliveryHookUrl: "",
+        ClickHookUrl: "",
+        PostFirstOpenOnly: false,
+        InboundDomain: "",
+        InboundSpamThreshold: 0,
+        TrackOpens: false,
+        TrackLinks: "None",
+        IncludeBounceContentInHook: false,
+        EnableSmtpApiErrorHooks: false,
+        ...settings,
+        ID: id,
+        InboundHash: hash,
+        ServerLink: `https://postmarkapp.com/servers/${id}/streams`,
+        InboundAddress: `${hash}@inbound.postmarkapp.com`,
+    };
+}
+const defaultStreams = (serverId, now) => DEFAULT_STREAMS.map(([id, name, type]) => ({
+    ID: id,
+    ServerID: serverId,
+    Name: name,
+    Description: null,
+    MessageStreamType: type,
+    CreatedAt: now,
+    UpdatedAt: null,
+    ArchivedAt: null,
+    ExpectedPurgeDate: null,
+    SubscriptionManagementConfiguration: {
+        UnsubscribeHandlingType: type === "Broadcasts" ? "Postmark" : "None",
+    },
+}));
+/**
+ * Creates a server with one API token and the default streams. `settings.ID` claims a fixed ID.
+ * A token that another server already holds throws: auth could not tell the two apart.
+ */
+export function createServer(store, now, settings = {}) {
+    const tokens = settings.ApiTokens ?? [newToken()];
+    const held = new Map([...store.state.servers.values()].flatMap((other) => other.ApiTokens.map((t) => [t.toLowerCase(), { token: t, server: other.ID }])));
+    for (const token of tokens) {
+        refuseTestToken(token);
+        const holder = held.get(token.toLowerCase());
+        if (holder !== undefined) {
+            throw new Error(`server ${holder.server} already holds token ${holder.token}`);
+        }
+        if (tokens.filter((t) => t.toLowerCase() === token.toLowerCase()).length > 1) {
+            throw new Error(`token ${token} appears twice`);
+        }
+    }
+    const id = settings.ID === undefined ? store.nextId("server") : store.useId("server", settings.ID);
+    const server = newServer(id, tokens, settings);
+    store.state.servers.set(id, server);
+    for (const stream of defaultStreams(id, now)) {
+        store.state.streams.set(streamKey(id, stream.ID), stream);
+    }
+    return server;
+}
+// Auth treats POSTMARK_API_TEST as the test token before any lookup (docs/02 §3.3).
+function refuseTestToken(token) {
+    if (token.toLowerCase() === TEST_TOKEN.toLowerCase()) {
+        throw new Error(`${TEST_TOKEN} is the test token, not a stored token`);
+    }
+}
+/** Adds an account token. Tokens compare without case (docs/02 §3.1). */
+export function addAccountToken(store, token) {
+    refuseTestToken(token);
+    if (store.state.account.tokens.some((t) => t.toLowerCase() === token.toLowerCase())) {
+        throw new Error(`account token ${token} exists`);
+    }
+    store.state.account.tokens.push(token);
+}
+export const testTokenContext = (now) => ({
+    kind: "test",
+    server: newServer(0, [TEST_TOKEN], { Name: TEST_TOKEN, InboundHash: "" }),
+    streams: defaultStreams(0, now),
+});
+/** A stream of the server the request authenticated as, stored or test-token. */
+export function findStream(state, auth, streamId) {
+    return auth.kind === "test"
+        ? auth.streams.find((s) => s.ID === streamId)
+        : state.streams.get(streamKey(auth.server.ID, streamId));
+}