@benclmnt/postmock 0.0.1

package/dist/src/api/account/servers.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import { apiError } from "../../errors.js";
+import { absent, intLike, parseBody } from "../../http/normalize.js";
+import { Unsupported } from "../../http/respond.js";
+import { SERVER_COLORS } from "../../state/types.js";
+import { pathId } from "./paging.js";
+// Servers API (docs/06 §4.2; refs/api_servers-api.md). Messages of summary rows are INFERRED.
+/** A doc enum value matched without case (INFERRED), answered in the doc spelling. */
+const oneOf = (values) => z.string().transform((value, ctx) => {
+    const found = values.find((v) => v.toLowerCase() === value.toLowerCase());
+    if (found !== undefined)
+        return found;
+    ctx.issues.push({ code: "custom", message: `not one of ${values.join(", ")}`, input: value });
+    return z.NEVER;
+});
+const isHttpUrl = (value) => {
+    try {
+        return ["http:", "https:"].includes(new URL(value).protocol);
+    }
+    catch {
+        return false;
+    }
+};
+// `null` keeps a hook URL; `""` clears it (the dotnet server test resets hooks to "",
+// sdk/postmark-dotnet/src/Postmark.Tests/ClientServerInformationTests.cs:87-94).
+const hookUrl = z.preprocess((v) => (v === null ? undefined : v), z
+    .string()
+    .refine((v) => v === "" || isHttpUrl(v))
+    .optional());
+const flag = absent(z.boolean());
+// refs/api_servers-api.md:121-137 (create body); edit takes the same fields but DeliveryType (:256-271).
+const settingsSchema = z.object({
+    Name: absent(z.string()),
+    Color: absent(oneOf(SERVER_COLORS)),
+    SmtpApiActivated: flag,
+    RawEmailEnabled: flag,
+    DeliveryType: absent(oneOf(["Live", "Sandbox"])),
+    InboundHookUrl: hookUrl,
+    BounceHookUrl: hookUrl,
+    OpenHookUrl: hookUrl,
+    DeliveryHookUrl: hookUrl,
+    ClickHookUrl: hookUrl,
+    PostFirstOpenOnly: flag,
+    InboundDomain: absent(z.string()),
+    InboundSpamThreshold: absent(intLike.pipe(z.number().min(0).max(30))),
+    TrackOpens: flag,
+    TrackLinks: absent(oneOf(["None", "HtmlAndText", "HtmlOnly", "TextOnly"])),
+    IncludeBounceContentInHook: flag,
+    EnableSmtpApiErrorHooks: flag,
+});
+const HOOK_FIELDS = new Set([
+    "InboundHookUrl",
+    "BounceHookUrl",
+    "OpenHookUrl",
+    "DeliveryHookUrl",
+    "ClickHookUrl",
+]);
+/**
+ * The settings of a create or edit body. A body that is no JSON object is
+ * 609. A bad value gets its field's ErrorCode (refs/api_overview.md:101-108); a field of the wrong
+ * JSON type has no documented code, so it answers 501.
+ */
+export function parseServerInput(state, body, self) {
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        throw apiError(609);
+    const parsed = parseBody(settingsSchema, body);
+    if (!parsed.success) {
+        const field = String(parsed.error.issues[0]?.path[0]);
+        if (field === "Color")
+            throw apiError(607);
+        if (field === "TrackLinks")
+            throw apiError(612);
+        if (field === "DeliveryType")
+            throw apiError(613);
+        if (field === "InboundSpamThreshold")
+            throw apiError(611);
+        if (HOOK_FIELDS.has(field)) {
+            throw apiError(606, { message: `The '${field}' is not a valid URL.` });
+        }
+        throw new Unsupported(`server field '${field}' has the wrong type: Postmark's answer is not captured`);
+    }
+    const input = parsed.data;
+    const others = [...state.servers.values()].filter((s) => s.ID !== self?.ID);
+    if (input.Name !== undefined) {
+        const name = input.Name.toLowerCase();
+        if (others.some((s) => s.Name.toLowerCase() === name))
+            throw apiError(603);
+    }
+    if (input.InboundDomain !== undefined) {
+        const domain = input.InboundDomain.toLowerCase();
+        if (domain.includes("postmarkapp.com")) {
+            throw apiError(608, { message: "The inbound domain cannot contain postmarkapp.com." });
+        }
+        // The MX check (ErrorCode 610) needs DNS; postmock accepts every inbound domain.
+        if (others.some((s) => s.InboundDomain.toLowerCase() === domain))
+            throw apiError(602);
+    }
+    return input;
+}
+/**
+ * Applies an edit body to a server: `PUT /servers/{id}` (account token) and `PUT /server` (server
+ * token) take the same fields. DeliveryType is fixed at create (refs/api_servers-api.md:38).
+ */
+export function editServer(state, server, body) {
+    const input = parseServerInput(state, body, server);
+    if (input.DeliveryType !== undefined && input.DeliveryType !== server.DeliveryType) {
+        throw new Unsupported("a DeliveryType change: Postmark's answer is not captured");
+    }
+    Object.assign(server, definedSettings(input));
+    return server;
+}
+/** The settings a create or edit sets: absent fields keep their value (docs/08 R9). */
+export const definedSettings = (input) => Object.fromEntries(Object.entries(input).filter(([, v]) => v !== undefined));
+export function findServer(state, id) {
+    const server = state.servers.get(pathId(id) ?? -1);
+    // No ErrorCode in the servers table names a missing server (docs/02 §4.4).
+    if (server === undefined)
+        throw new Unsupported(`server ${id} not found: Postmark's answer is not captured`);
+    return server;
+}
+const ownerOf = (item) => ("ServerID" in item ? item.ServerID : item.serverId);
+function dropOwned(map, serverId) {
+    for (const [key, item] of map)
+        if (ownerOf(item) === serverId)
+            map.delete(key);
+}
+/** Removes a server and everything it owns. */
+export function deleteServer(state, server) {
+    state.servers.delete(server.ID);
+    const id = server.ID;
+    for (const map of [
+        state.streams,
+        state.outbound,
+        state.inbound,
+        state.bounces,
+        state.suppressions,
+        state.templates,
+        state.bulkRequests,
+        state.webhooks,
+        state.inboundRules,
+        state.smtpTokens,
+    ]) {
+        dropOwned(map, id);
+    }
+    state.opens = state.opens.filter((o) => o.ServerID !== id);
+    state.clicks = state.clicks.filter((c) => c.ServerID !== id);
+    state.webhookAttempts = state.webhookAttempts.filter((a) => a.serverId !== id);
+}

package/dist/src/api/bounces/json.d.ts

@@ -0,0 +1,25 @@
+import { type Bounce } from "../../state/types.ts";
+/**
+ * A bounce in doc field order (refs/api_bounce-api.md:155-176, 247-270). A list item has a `Z`
+ * `BouncedAt` and no `Content`; a single bounce has an Eastern offset and `Content` (Q12).
+ */
+export declare const bounceJson: (b: Bounce, now: Date, shape: "list" | "single") => {
+    ID: number;
+    Type: "AddressChange" | "AutoResponder" | "BadEmailAddress" | "Blocked" | "ChallengeVerification" | "DMARCPolicy" | "DnsError" | "HardBounce" | "InboundError" | "ManuallyDeactivated" | "OpenRelayTest" | "SMTPApiError" | "SoftBounce" | "SpamComplaint" | "SpamNotification" | "Subscribe" | "TemplateRenderingFailed" | "Transient" | "Unconfirmed" | "Unknown" | "Unsubscribe" | "VirusNotification";
+    TypeCode: 1 | 2 | 16 | 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096 | 8192 | 16384 | 100000 | 100001 | 100002 | 100003 | 100006 | 100007 | 100008 | 100009 | 100010;
+    Name: "Address change" | "Auto responder" | "DMARC Policy" | "DNS error" | "Hard bounce" | "ISP block" | "Invalid email address" | "Manually deactivated" | "Message delayed/Undeliverable" | "Open relay test" | "Processing failed" | "Registration not confirmed" | "SMTP API error" | "Soft bounce" | "Spam challenge verification" | "Spam complaint" | "Spam notification" | "Subscribe request" | "Template rendering failed" | "Unknown" | "Unsubscribe request" | "Virus notification";
+    Tag: string | null;
+    MessageID: string;
+    ServerID: number;
+    MessageStream: string;
+    Description: string;
+    Details: string;
+    Email: string;
+    From: string | null;
+    BouncedAt: string;
+    DumpAvailable: boolean;
+    Inactive: boolean;
+    CanActivate: boolean;
+    Subject: string;
+    Content?: string;
+};

package/dist/src/api/bounces/json.js

@@ -0,0 +1,27 @@
+import { dumpAvailable } from "../../recipients/transitions.js";
+import { BOUNCE_TYPES } from "../../state/types.js";
+import { formatTimestamp } from "../../time.js";
+/**
+ * A bounce in doc field order (refs/api_bounce-api.md:155-176, 247-270). A list item has a `Z`
+ * `BouncedAt` and no `Content`; a single bounce has an Eastern offset and `Content` (Q12).
+ */
+export const bounceJson = (b, now, shape) => ({
+    ID: b.ID,
+    Type: b.Type,
+    TypeCode: BOUNCE_TYPES[b.Type].TypeCode,
+    Name: BOUNCE_TYPES[b.Type].Name,
+    Tag: b.Tag,
+    MessageID: b.MessageID,
+    ServerID: b.ServerID,
+    MessageStream: b.MessageStream,
+    Description: b.Description,
+    Details: b.Details,
+    Email: b.Email,
+    From: b.From,
+    BouncedAt: formatTimestamp(b.BouncedAt, shape === "list" ? "utc" : "eastern"),
+    DumpAvailable: dumpAvailable(b, now),
+    Inactive: b.Inactive,
+    CanActivate: b.CanActivate,
+    Subject: b.Subject,
+    ...(shape === "single" && { Content: b.Content }),
+});

package/dist/src/api/bounces/routes.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/api/bounces/routes.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { apiError } from "../../errors.js";
+import { inclusiveUpperBound, queryBool, queryDate, queryInt } from "../../http/normalize.js";
+import { paged } from "../../http/respond.js";
+import { defineRoute } from "../../http/routes.js";
+import { activateBounce, bounceVisible, dumpAvailable, findBounce, } from "../../recipients/transitions.js";
+import { BOUNCE_TYPES } from "../../state/types.js";
+import { bounceJson } from "./json.js";
+// Bounce API: docs/04 §1. Every 1000 and 1001 message text is INFERRED (summary rows,
+// refs/api_overview.md:116-117).
+const bounceType = z.string().refine((t) => Object.hasOwn(BOUNCE_TYPES, t));
+const listQuery = z.object({
+    count: queryInt.pipe(z.number().int().min(1).max(500)),
+    offset: queryInt.pipe(z.number().int().min(0)),
+    type: bounceType.optional(),
+    inactive: queryBool.optional(),
+    emailFilter: z.string().optional(),
+    tag: z.string().optional(),
+    messageID: z.string().optional(),
+    fromdate: queryDate.optional(),
+    todate: queryDate.optional(),
+    messagestream: z.string().default("outbound"),
+});
+const QUERY_MESSAGES = {
+    count: "Count must be an integer between 1 and 500.",
+    offset: "Offset must be a non-negative integer.",
+    type: "Illegal bounce type.",
+    inactive: "Inactive must be true or false.",
+    fromdate: "FromDate must be a date.",
+    todate: "ToDate must be a date.",
+};
+defineRoute({
+    method: "GET",
+    path: "/bounces",
+    auth: "server",
+    handler: ({ store, clock, query, auth }) => {
+        const parsed = query.pick(listQuery);
+        if (!parsed.success) {
+            const field = String(parsed.error.issues[0]?.path[0]);
+            throw apiError(1000, { message: QUERY_MESSAGES[field] ?? `Invalid ${field}.` });
+        }
+        const q = parsed.data;
+        if (q.count + q.offset > 10000) {
+            throw apiError(1000, { message: "Count plus offset cannot exceed 10,000." });
+        }
+        const now = clock.now();
+        const from = q.fromdate?.instant.getTime();
+        const to = q.todate && inclusiveUpperBound(q.todate).getTime();
+        const matches = [...store.state.bounces.values()]
+            .filter((b) => b.ServerID === auth.server.ID &&
+            bounceVisible(b, now) &&
+            b.MessageStream === q.messagestream &&
+            (q.type === undefined || b.Type === q.type) &&
+            (q.inactive === undefined || b.Inactive === q.inactive) &&
+            // Substring match, case rule INFERRED (docs/04 §1.2, Q1).
+            (q.emailFilter === undefined ||
+                b.Email.toLowerCase().includes(q.emailFilter.toLowerCase())) &&
+            (q.tag === undefined || b.Tag === q.tag) &&
+            (q.messageID === undefined || b.MessageID.toLowerCase() === q.messageID.toLowerCase()) &&
+            (from === undefined || b.BouncedAt.getTime() >= from) &&
+            (to === undefined || b.BouncedAt.getTime() < to))
+            // Newest first (refs/api_bounce-api.md:151-196 example order).
+            .sort((a, b) => b.BouncedAt.getTime() - a.BouncedAt.getTime() || b.ID - a.ID)
+            .map((b) => ({ RecordType: "Bounce", ...bounceJson(b, now, "list") }));
+        return paged("Bounces", matches, q.count, q.offset);
+    },
+});
+/** The bounce ID from the path; a non-integer is an unknown bounce (INFERRED). */
+function bounceOf(ctx) {
+    const raw = ctx.params.bounceid;
+    if (!/^\d+$/.test(raw))
+        throw apiError(1001, { message: "The bounce was not found." });
+    return findBounce(ctx, ctx.auth.server, Number(raw));
+}
+defineRoute({
+    method: "GET",
+    path: "/bounces/:bounceid",
+    auth: "server",
+    handler: (ctx) => bounceJson(bounceOf(ctx), ctx.clock.now(), "single"),
+});
+defineRoute({
+    method: "GET",
+    path: "/bounces/:bounceid/dump",
+    auth: "server",
+    handler: (ctx) => {
+        const bounce = bounceOf(ctx);
+        if (bounce.Content === "")
+            return { Body: "" };
+        if (!dumpAvailable(bounce, ctx.clock.now())) {
+            throw apiError(1001, { message: "The bounce dump is no longer available." });
+        }
+        return { Body: bounce.Content };
+    },
+});
+// Accepts an empty body and `{}` (docs/04 §3.4); the body is not read.
+defineRoute({
+    method: "PUT",
+    path: "/bounces/:bounceid/activate",
+    auth: "server",
+    handler: async (ctx) => {
+        const bounce = bounceOf(ctx);
+        await activateBounce(ctx, bounce);
+        return { Message: "OK", Bounce: bounceJson(bounce, ctx.clock.now(), "single") };
+    },
+});
+// postmark.js calls `/deliveryStats`; literals match without case (docs/04 §6).
+defineRoute({
+    method: "GET",
+    path: "/deliverystats",
+    auth: "server",
+    handler: ({ store, clock, auth }) => {
+        const now = clock.now();
+        const bounces = [...store.state.bounces.values()].filter((b) => b.ServerID === auth.server.ID && bounceVisible(b, now));
+        const types = Object.keys(BOUNCE_TYPES)
+            .map((type) => ({
+            Type: type,
+            Name: BOUNCE_TYPES[type].Name,
+            Count: bounces.filter((b) => b.Type === type).length,
+        }))
+            .filter((row) => row.Count > 0);
+        return {
+            // Inactive bounces, INFERRED from the example ratio (refs/api_bounce-api.md:41-47).
+            InactiveMails: bounces.filter((b) => b.Inactive).length,
+            Bounces: [{ Name: "All", Count: bounces.length }, ...types],
+        };
+    },
+});

package/dist/src/api/bulk/bulk.d.ts

@@ -0,0 +1,43 @@
+import type { ServerAuth } from "../../http/routes.ts";
+import { type OutboundDraft, type Submission } from "../../pipeline/submit.ts";
+import type { Runtime } from "../../runtime.ts";
+import type { BulkRequest } from "../../state/types.ts";
+import type { RenderOutcome } from "../templates/content.ts";
+/** Processing starts after this delay, then releases one message per step (INFERRED timings). */
+export declare const BULK_START_MS = 1000;
+export declare const BULK_STEP_MS = 10;
+export interface BulkJob {
+    /** The draft with rendered content, or the render failure that counts it as failed. */
+    draft: OutboundDraft;
+    rendered: RenderOutcome;
+    /** The `Messages[]` entry, for `GET /control/messages`. */
+    request: unknown;
+}
+/**
+ * The status object of all three endpoints. Absent values are omitted, never null
+ * (refs/api_bulk-email.md:238-240); `SubmittedAt` uses `Z` (refs/api_bulk-email.md:204).
+ */
+export declare const bulkStatusJson: (bulk: BulkRequest) => {
+    Id: string;
+    SubmittedAt: string;
+    Status: "Accepted" | "Cancelled" | "Completed" | "Processing";
+    TotalMessages: number;
+    PercentageCompleted: number;
+    ReleasedCount: number;
+    FailedCount: number;
+    Subject?: string;
+};
+/** A bulk message submission. */
+export declare const bulkSubmission: (auth: ServerAuth, draft: OutboundDraft, request: unknown, bulkRequestId: string | null, templateId: number | null) => Submission;
+/**
+ * Accepted → Processing → Completed. A message with every recipient suppressed, or one that failed
+ * to render, counts in `FailedCount`; the rest in `ReleasedCount` (refs/api_bulk-email.md:303-316).
+ * A message that state changed since accept (a deleted stream) fails its checks and counts as
+ * failed too (INFERRED). A message with only some recipients suppressed counts as released
+ * (INFERRED, docs/03 Q21). A cancelled request releases nothing more.
+ *
+ * `Unsupported` in a job (an archived stream, a listener) has no request to answer with 501, and
+ * the docs give no count for it. The request stops releasing and keeps its counters, so it never
+ * reaches Completed; the reason goes to stderr and `GET /control/bulk/:id` (AGENTS.md rule 5).
+ */
+export declare function scheduleBulk(runtime: Runtime, auth: ServerAuth, bulk: BulkRequest, jobs: readonly BulkJob[], templateId: number | null): void;

package/dist/src/api/bulk/bulk.js

@@ -0,0 +1,81 @@
+import { Unsupported } from "../../http/respond.js";
+import { acceptOutbound, validateOutbound, } from "../../pipeline/submit.js";
+import { formatTimestamp } from "../../time.js";
+// The bulk request status object and its processing on the clock (docs/03 §1.6; refs/api_bulk-email.md).
+/** Processing starts after this delay, then releases one message per step (INFERRED timings). */
+export const BULK_START_MS = 1000;
+export const BULK_STEP_MS = 10;
+/**
+ * The status object of all three endpoints. Absent values are omitted, never null
+ * (refs/api_bulk-email.md:238-240); `SubmittedAt` uses `Z` (refs/api_bulk-email.md:204).
+ */
+export const bulkStatusJson = (bulk) => ({
+    Id: bulk.Id,
+    SubmittedAt: formatTimestamp(bulk.SubmittedAt, "utc"),
+    Status: bulk.Status,
+    TotalMessages: bulk.TotalMessages,
+    PercentageCompleted: bulk.PercentageCompleted,
+    ReleasedCount: bulk.ReleasedCount,
+    FailedCount: bulk.FailedCount,
+    ...(bulk.Subject !== null && { Subject: bulk.Subject }),
+});
+/** A bulk message submission. */
+export const bulkSubmission = (auth, draft, request, bulkRequestId, templateId) => ({
+    auth,
+    channel: "rest",
+    draft,
+    request,
+    bulkRequestId,
+    templateId,
+});
+/**
+ * Accepted → Processing → Completed. A message with every recipient suppressed, or one that failed
+ * to render, counts in `FailedCount`; the rest in `ReleasedCount` (refs/api_bulk-email.md:303-316).
+ * A message that state changed since accept (a deleted stream) fails its checks and counts as
+ * failed too (INFERRED). A message with only some recipients suppressed counts as released
+ * (INFERRED, docs/03 Q21). A cancelled request releases nothing more.
+ *
+ * `Unsupported` in a job (an archived stream, a listener) has no request to answer with 501, and
+ * the docs give no count for it. The request stops releasing and keeps its counters, so it never
+ * reaches Completed; the reason goes to stderr and `GET /control/bulk/:id` (AGENTS.md rule 5).
+ */
+export function scheduleBulk(runtime, auth, bulk, jobs, templateId) {
+    const { clock } = runtime;
+    clock.schedule(BULK_START_MS, () => {
+        if (bulk.Status === "Accepted")
+            bulk.Status = "Processing";
+    });
+    jobs.forEach((job, i) => {
+        clock.schedule(BULK_START_MS + (i + 1) * BULK_STEP_MS, async () => {
+            if (bulk.Status !== "Processing" || bulk.unsupported !== null)
+                return;
+            try {
+                bulk[(await release(runtime, auth, bulk, job, templateId)) ? "ReleasedCount" : "FailedCount"] += 1;
+            }
+            catch (error) {
+                if (!(error instanceof Unsupported))
+                    throw error;
+                bulk.unsupported = error.message;
+                console.error(`postmock: bulk request ${bulk.Id} stopped: ${error.message}`);
+                return;
+            }
+            const done = bulk.ReleasedCount + bulk.FailedCount;
+            bulk.PercentageCompleted = (done / bulk.TotalMessages) * 100;
+            if (done === bulk.TotalMessages)
+                bulk.Status = "Completed";
+        });
+    });
+}
+/** Sends one bulk message; true when it was released. */
+async function release(runtime, auth, bulk, job, templateId) {
+    if (!job.rendered.ok)
+        return false;
+    const validation = validateOutbound(runtime, bulkSubmission(auth, job.draft, job.request, bulk.Id, templateId));
+    if (validation.outcome === "rejected")
+        return false;
+    const result = await acceptOutbound(runtime, validation.outbound);
+    if (result.outcome !== "accepted" && result.outcome !== "partiallySuppressed")
+        return false;
+    bulk.messageIds.push(result.message.MessageID);
+    return true;
+}

package/dist/src/api/bulk/routes.d.ts

@@ -0,0 +1 @@
+export {};