@benclmnt/postmock 0.0.1

package/dist/src/webhooks/outbound.js

@@ -0,0 +1,47 @@
+import { deliver, OUTBOUND } from "./deliver.js";
+/**
+ * Sends an event to every verified `/webhooks` row of its stream with the trigger on, then to the
+ * server hook URL (docs/05 §1.5, §5). Server hook URLs apply to every stream (INFERRED, Q10).
+ */
+export async function emitOutbound(runtime, event) {
+    const server = runtime.store.state.servers.get(event.serverId);
+    if (server === undefined)
+        return;
+    const hooks = [];
+    for (const webhook of runtime.store.state.webhooks.values()) {
+        if (webhook.ServerID === server.ID &&
+            webhook.MessageStream === event.messageStream &&
+            webhook.Status === "verified" &&
+            webhook.Triggers[event.trigger].Enabled) {
+            hooks.push({
+                hook: { kind: "webhook", webhook },
+                target: {
+                    serverId: server.ID,
+                    hook: { kind: "webhook", webhookId: webhook.ID, trigger: event.trigger },
+                    url: webhook.Url,
+                    httpAuth: webhook.HttpAuth,
+                    headers: webhook.HttpHeaders,
+                },
+            });
+        }
+    }
+    const field = event.serverHookField;
+    if (field !== null && server[field] !== "") {
+        hooks.push({
+            hook: { kind: "server", server },
+            target: {
+                serverId: server.ID,
+                hook: { kind: "server", field },
+                url: server[field],
+                httpAuth: null,
+                headers: [],
+            },
+        });
+    }
+    for (const { hook, target } of hooks) {
+        const payload = event.payload(hook);
+        if (payload !== null) {
+            await deliver(runtime, { target, recordType: event.recordType, payload, policy: OUTBOUND });
+        }
+    }
+}

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

@@ -0,0 +1,111 @@
+import type { EventMap } from "../events.ts";
+import { type Bounce, type ClickEvent, type InboundMessage, type OpenEvent, type SubscriptionChange } from "../state/types.ts";
+/** docs/05 §2.1, §2.2, §2.8. `Content` only when the hook asks for it. */
+export declare function bouncePayload(recordType: "Bounce" | "SpamComplaint", bounce: Bounce, includeContent: boolean): {
+    RecordType: "Bounce" | "SpamComplaint";
+    MessageStream: string;
+    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;
+    MessageID: string;
+    Metadata: Record<string, string>;
+    ServerID: number;
+    Description: string;
+    Details: string;
+    Email: string;
+    From: string | null;
+    BouncedAt: string;
+    DumpAvailable: boolean;
+    Inactive: boolean;
+    CanActivate: boolean;
+    Subject: string;
+    Content?: string;
+};
+/** docs/05 §2.3: one event per recipient. */
+export declare function deliveryPayload({ message, recipient, deliveredAt, details, }: EventMap["delivered"]): {
+    RecordType: string;
+    MessageStream: string;
+    ServerID: number;
+    MessageID: string;
+    Recipient: string;
+    Tag: string;
+    DeliveredAt: string;
+    Details: string;
+    Metadata: Record<string, string>;
+};
+/** docs/05 §2.4. No `ServerID`. */
+export declare function openPayload(open: OpenEvent): {
+    Client?: import("../state/types.ts").ClientInfo;
+    OS?: import("../state/types.ts").ClientInfo;
+    Platform?: "Desktop" | "Mobile" | "Unknown" | "WebMail";
+    UserAgent: string;
+    RecordType: string;
+    MessageStream: string;
+    FirstOpen: boolean;
+    ReadSeconds: number;
+    Geo?: import("../state/types.ts").Geo;
+    MessageID: string;
+    Metadata: Record<string, string>;
+    ReceivedAt: string;
+    Tag: string;
+    Recipient: string;
+};
+/** docs/05 §2.5. No `ServerID`. */
+export declare function clickPayload(click: ClickEvent): {
+    Client?: import("../state/types.ts").ClientInfo;
+    OS?: import("../state/types.ts").ClientInfo;
+    Platform?: "Desktop" | "Mobile" | "Unknown" | "WebMail";
+    UserAgent: string;
+    RecordType: string;
+    MessageStream: string;
+    ClickLocation: "HTML" | "Text";
+    OriginalLink: string;
+    Geo?: import("../state/types.ts").Geo;
+    MessageID: string;
+    Metadata: Record<string, string>;
+    ReceivedAt: string;
+    Tag: string;
+    Recipient: string;
+};
+/** docs/05 §2.6. `MessageID`, `SuppressionReason` and `Tag` stay null where the change has none. */
+export declare function subscriptionChangePayload(change: SubscriptionChange): {
+    RecordType: string;
+    MessageID: string | null;
+    ServerID: number;
+    MessageStream: string;
+    ChangedAt: string;
+    Recipient: string;
+    Origin: import("../state/types.ts").SuppressionOrigin;
+    SuppressSending: boolean;
+    SuppressionReason: import("../state/types.ts").SuppressionReason | null;
+    Tag: string | null;
+    Metadata: Record<string, string>;
+};
+/** docs/05 §2.7, §4.2. No `RecordType`. `RawEmail` only with the server's `RawEmailEnabled`. */
+export declare function inboundPayload(message: InboundMessage, rawEmailEnabled: boolean): {
+    FromName: string;
+    MessageStream: string;
+    From: string;
+    FromFull: import("../state/types.ts").InboundAddress;
+    To: string;
+    ToFull: import("../state/types.ts").InboundAddress[];
+    Cc: string;
+    CcFull: import("../state/types.ts").InboundAddress[];
+    Bcc: string;
+    BccFull: import("../state/types.ts").InboundAddress[];
+    OriginalRecipient: string;
+    Subject: string;
+    MessageID: string;
+    ReplyTo: string;
+    MailboxHash: string;
+    Date: string;
+    TextBody: string;
+    HtmlBody: string;
+    StrippedTextReply: string;
+    Tag: string;
+    Headers: import("../state/types.ts").Header[];
+    Attachments: import("../state/types.ts").InboundAttachment[];
+    RawEmail?: string;
+};

package/dist/src/webhooks/payloads.js

@@ -0,0 +1,128 @@
+import { BOUNCE_TYPES, } from "../state/types.js";
+import { formatTimestamp } from "../time.js";
+// Webhook bodies per RecordType, keys in doc order (docs/05 §2). Dates use the `Z` form of the doc
+// examples. A send without a tag gives `Tag: ""`, as inbound does (INFERRED).
+const at = (instant) => formatTimestamp(instant, "utc");
+const tag = (value) => value ?? "";
+/** docs/05 §2.1, §2.2, §2.8. `Content` only when the hook asks for it. */
+export function bouncePayload(recordType, bounce, includeContent) {
+    return {
+        RecordType: recordType,
+        MessageStream: bounce.MessageStream,
+        ID: bounce.ID,
+        Type: bounce.Type,
+        TypeCode: BOUNCE_TYPES[bounce.Type].TypeCode,
+        Name: BOUNCE_TYPES[bounce.Type].Name,
+        Tag: tag(bounce.Tag),
+        MessageID: bounce.MessageID,
+        Metadata: bounce.Metadata,
+        ServerID: bounce.ServerID,
+        Description: bounce.Description,
+        Details: bounce.Details,
+        Email: bounce.Email,
+        From: bounce.From,
+        BouncedAt: at(bounce.BouncedAt),
+        DumpAvailable: bounce.Content !== "",
+        Inactive: bounce.Inactive,
+        CanActivate: bounce.CanActivate,
+        Subject: bounce.Subject,
+        ...(includeContent && { Content: bounce.Content }),
+    };
+}
+/** docs/05 §2.3: one event per recipient. */
+export function deliveryPayload({ message, recipient, deliveredAt, details, }) {
+    return {
+        RecordType: "Delivery",
+        MessageStream: message.MessageStream,
+        ServerID: message.ServerID,
+        MessageID: message.MessageID,
+        Recipient: recipient,
+        Tag: tag(message.Tag),
+        DeliveredAt: at(deliveredAt),
+        Details: details,
+        Metadata: message.Metadata,
+    };
+}
+/** Client, OS, Platform and Geo are left out when unknown (docs/05 §2.4). */
+const reader = (e) => ({
+    ...(e.Client !== null && { Client: e.Client }),
+    ...(e.OS !== null && { OS: e.OS }),
+    ...(e.Platform !== null && { Platform: e.Platform }),
+    UserAgent: e.UserAgent,
+});
+/** docs/05 §2.4. No `ServerID`. */
+export function openPayload(open) {
+    return {
+        RecordType: "Open",
+        MessageStream: open.MessageStream,
+        FirstOpen: open.FirstOpen,
+        ...reader(open),
+        ReadSeconds: open.ReadSeconds,
+        ...(open.Geo !== null && { Geo: open.Geo }),
+        MessageID: open.MessageID,
+        Metadata: open.Metadata,
+        ReceivedAt: at(open.ReceivedAt),
+        Tag: tag(open.Tag),
+        Recipient: open.Recipient,
+    };
+}
+/** docs/05 §2.5. No `ServerID`. */
+export function clickPayload(click) {
+    return {
+        RecordType: "Click",
+        MessageStream: click.MessageStream,
+        ClickLocation: click.ClickLocation,
+        ...reader(click),
+        OriginalLink: click.OriginalLink,
+        ...(click.Geo !== null && { Geo: click.Geo }),
+        MessageID: click.MessageID,
+        Metadata: click.Metadata,
+        ReceivedAt: at(click.ReceivedAt),
+        Tag: tag(click.Tag),
+        Recipient: click.Recipient,
+    };
+}
+/** docs/05 §2.6. `MessageID`, `SuppressionReason` and `Tag` stay null where the change has none. */
+export function subscriptionChangePayload(change) {
+    return {
+        RecordType: "SubscriptionChange",
+        MessageID: change.MessageID,
+        ServerID: change.ServerID,
+        MessageStream: change.MessageStream,
+        ChangedAt: at(change.ChangedAt),
+        Recipient: change.Recipient,
+        Origin: change.Origin,
+        SuppressSending: change.SuppressSending,
+        SuppressionReason: change.SuppressionReason,
+        Tag: change.Tag,
+        Metadata: change.Metadata,
+    };
+}
+/** docs/05 §2.7, §4.2. No `RecordType`. `RawEmail` only with the server's `RawEmailEnabled`. */
+export function inboundPayload(message, rawEmailEnabled) {
+    return {
+        FromName: message.FromName,
+        MessageStream: message.MessageStream,
+        From: message.From,
+        FromFull: message.FromFull,
+        To: message.To,
+        ToFull: message.ToFull,
+        Cc: message.Cc,
+        CcFull: message.CcFull,
+        Bcc: message.Bcc,
+        BccFull: message.BccFull,
+        OriginalRecipient: message.OriginalRecipient,
+        Subject: message.Subject,
+        MessageID: message.MessageID,
+        ReplyTo: message.ReplyTo,
+        MailboxHash: message.MailboxHash,
+        Date: message.Date,
+        TextBody: message.TextBody,
+        HtmlBody: message.HtmlBody,
+        StrippedTextReply: message.StrippedTextReply,
+        Tag: message.Tag,
+        Headers: message.Headers,
+        Attachments: message.Attachments,
+        ...(rawEmailEnabled && { RawEmail: message.rawEmail }),
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@benclmnt/postmock",
+  "version": "0.0.1",
+  "description": "A mock Postmark server for testing code that sends email through Postmark",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "postmock": "dist/src/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/server.d.ts",
+      "default": "./dist/src/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@11.22.0",
+  "scripts": {
+    "start": "node src/main.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "check": "biome check . && tsc --noEmit && vitest run",
+    "test": "vitest run",
+    "conformance": "node conformance/run.ts",
+    "conformance:check": "node conformance/check.ts",
+    "compat-table": "node tools/compat-table.ts"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.1",
+    "hono": "^4.13.8",
+    "libmime": "5.4.4",
+    "mailparser": "^3.9.28",
+    "smtp-server": "^3.19.13",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.13",
+    "@types/libmime": "^5.3.0",
+    "@types/mailparser": "^3.4.6",
+    "@types/node": "^24.13.4",
+    "@types/nodemailer": "^8.0.1",
+    "@types/smtp-server": "^3.5.13",
+    "nodemailer": "^9.1.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
+  }
+}