@benclmnt/postmock 0.0.1

package/dist/src/plugins/webhooks.js

@@ -0,0 +1,80 @@
+import { deliverInbound } from "../inbound/deliver.js";
+import { egressEnv, setEgress } from "../webhooks/egress.js";
+import { emitOutbound } from "../webhooks/outbound.js";
+import { bouncePayload, clickPayload, deliveryPayload, openPayload, subscriptionChangePayload, } from "../webhooks/payloads.js";
+const bounceContent = (hook, trigger) => hook.kind === "webhook"
+    ? hook.webhook.Triggers[trigger].IncludeContent
+    : hook.server.IncludeBounceContentInHook;
+/** The webhook emitter: every domain event becomes a POST to the hooks that ask for it (docs/05 §5). */
+const webhooks = {
+    install(runtime) {
+        setEgress(runtime, egressEnv.parse(process.env));
+        const { events } = runtime;
+        events.on("delivered", (e) => emitOutbound(runtime, {
+            serverId: e.message.ServerID,
+            messageStream: e.message.MessageStream,
+            recordType: "Delivery",
+            trigger: "Delivery",
+            serverHookField: "DeliveryHookUrl",
+            payload: () => deliveryPayload(e),
+        }));
+        const toBounceHooks = (bounce) => emitOutbound(runtime, {
+            serverId: bounce.ServerID,
+            messageStream: bounce.MessageStream,
+            recordType: "Bounce",
+            trigger: "Bounce",
+            serverHookField: "BounceHookUrl",
+            payload: (hook) => bouncePayload("Bounce", bounce, bounceContent(hook, "Bounce")),
+        });
+        events.on("bounced", ({ bounce }) => toBounceHooks(bounce));
+        // SMTP API errors reach the bounce hooks only with the server switch (docs/05 §2.8).
+        events.on("smtpApiError", async ({ bounce }) => {
+            if (runtime.store.state.servers.get(bounce.ServerID)?.EnableSmtpApiErrorHooks === true) {
+                await toBounceHooks(bounce);
+            }
+        });
+        events.on("spamComplaint", ({ bounce }) => emitOutbound(runtime, {
+            serverId: bounce.ServerID,
+            messageStream: bounce.MessageStream,
+            recordType: "SpamComplaint",
+            trigger: "SpamComplaint",
+            serverHookField: null,
+            payload: (hook) => bouncePayload("SpamComplaint", bounce, bounceContent(hook, "SpamComplaint")),
+        }));
+        events.on("opened", ({ open }) => emitOutbound(runtime, {
+            serverId: open.ServerID,
+            messageStream: open.MessageStream,
+            recordType: "Open",
+            trigger: "Open",
+            serverHookField: "OpenHookUrl",
+            payload: (hook) => {
+                const firstOnly = hook.kind === "webhook"
+                    ? hook.webhook.Triggers.Open.PostFirstOpenOnly
+                    : hook.server.PostFirstOpenOnly;
+                return firstOnly && !open.FirstOpen ? null : openPayload(open);
+            },
+        }));
+        events.on("clicked", ({ click }) => emitOutbound(runtime, {
+            serverId: click.ServerID,
+            messageStream: click.MessageStream,
+            recordType: "Click",
+            trigger: "Click",
+            serverHookField: "ClickHookUrl",
+            payload: () => clickPayload(click),
+        }));
+        events.on("subscriptionChange", ({ change }) => emitOutbound(runtime, {
+            serverId: change.ServerID,
+            messageStream: change.MessageStream,
+            recordType: "SubscriptionChange",
+            trigger: "SubscriptionChange",
+            serverHookField: null,
+            payload: () => subscriptionChangePayload(change),
+        }));
+        // A blocked message waits for a bypass (docs/05 §4.1).
+        events.on("inboundReceived", async ({ message }) => {
+            if (message.Status !== "Blocked")
+                await deliverInbound(runtime, message);
+        });
+    },
+};
+export default webhooks;

package/dist/src/plugins.d.ts

@@ -0,0 +1,20 @@
+import type { Runtime } from "./runtime.ts";
+export interface StartedListener {
+    /** Key in `RunningPostmock.listeners` and the startup line, e.g. `smtp`. */
+    name: string;
+    url: string;
+    close(): Promise<void>;
+}
+/**
+ * A feature that needs more than routes: event listeners (webhooks, stats) or its own listener
+ * (SMTP, TLS). One file per plugin in `src/plugins/`, default export. A plugin reads its own env
+ * keys in `start`, parsed there with zod (docs/11 §5).
+ */
+export interface Plugin {
+    /** Runs once per runtime, before any seed. */
+    install?(runtime: Runtime): void;
+    /** Starts a listener after the seed is applied. */
+    start?(runtime: Runtime, host: string): Promise<StartedListener>;
+}
+/** Every plugin in `src/plugins/`, in filename order. */
+export declare const PLUGINS: Plugin[];

package/dist/src/plugins.js

@@ -0,0 +1,9 @@
+import { importAll } from "./discover.js";
+/** Every plugin in `src/plugins/`, in filename order. */
+export const PLUGINS = (await importAll(new URL("./plugins/", import.meta.url))).map((found) => {
+    const plugin = found.module.default;
+    if (typeof plugin !== "object" || plugin === null) {
+        throw new Error(`${found.url.pathname} has no default export plugin object`);
+    }
+    return plugin;
+});

package/dist/src/recipients/test-bounces.d.ts

@@ -0,0 +1,15 @@
+import { type Address, type BounceType, type Header } from "../state/types.ts";
+/** The black-hole domain whose recipients bounce at once (docs/07 §2.3). */
+export declare const BOUNCE_TESTING_DOMAIN = "bounce-testing.postmarkapp.com";
+export interface TestBounce {
+    email: string;
+    type: BounceType;
+}
+/**
+ * The fake bounce of each recipient on `bounce-testing.postmarkapp.com` (docs/07 §2.3). The type
+ * comes from `X-PM-Bounce-Type`, else the local part; case and `_` do not matter. An unknown local
+ * part and `SpamComplaint` give HardBounce (DOC). The header winning over the local part is
+ * INFERRED. Throws `Unsupported` for an unknown header value and for a type whose effect on the
+ * address is not captured, so a send can refuse before it stores anything.
+ */
+export declare function testBounces(headers: readonly Header[], recipients: readonly Address[]): TestBounce[];

package/dist/src/recipients/test-bounces.js

@@ -0,0 +1,31 @@
+import { Unsupported } from "../http/respond.js";
+import { BOUNCE_TYPES } from "../state/types.js";
+import { bounceEffectCaptured } from "./transitions.js";
+/** The black-hole domain whose recipients bounce at once (docs/07 §2.3). */
+export const BOUNCE_TESTING_DOMAIN = "bounce-testing.postmarkapp.com";
+const TYPES = new Map(Object.keys(BOUNCE_TYPES).map((type) => [type.toLowerCase(), type]));
+const known = (value) => TYPES.get(value.replaceAll("_", "").toLowerCase());
+/**
+ * The fake bounce of each recipient on `bounce-testing.postmarkapp.com` (docs/07 §2.3). The type
+ * comes from `X-PM-Bounce-Type`, else the local part; case and `_` do not matter. An unknown local
+ * part and `SpamComplaint` give HardBounce (DOC). The header winning over the local part is
+ * INFERRED. Throws `Unsupported` for an unknown header value and for a type whose effect on the
+ * address is not captured, so a send can refuse before it stores anything.
+ */
+export function testBounces(headers, recipients) {
+    const header = headers.find((h) => h.Name.toLowerCase() === "x-pm-bounce-type")?.Value;
+    return recipients.flatMap(({ Email }) => {
+        const at = Email.lastIndexOf("@");
+        if (Email.slice(at + 1).toLowerCase() !== BOUNCE_TESTING_DOMAIN)
+            return [];
+        const named = known(header ?? Email.slice(0, at));
+        if (named === undefined && header !== undefined) {
+            throw new Unsupported(`X-PM-Bounce-Type '${header}': not a bounce type (docs/07 §2.3)`);
+        }
+        const type = named === undefined || named === "SpamComplaint" ? "HardBounce" : named;
+        if (!bounceEffectCaptured(type)) {
+            throw new Unsupported(`a fake ${type} bounce: its effect on the address is not captured (docs/04 Q13)`);
+        }
+        return [{ email: Email, type }];
+    });
+}

package/dist/src/recipients/transitions.d.ts

@@ -0,0 +1,57 @@
+import type { Runtime } from "../runtime.ts";
+import type { Bounce, BounceType, OutboundMessage, Server } from "../state/types.ts";
+/** Bounces are kept 45 days (refs/api_bounce-api.md:4); their suppression rows stay (T14, INFERRED). */
+export declare const BOUNCE_RETENTION_MS: number;
+/** No dump after 30 days (refs/api_bounce-api.md:141). */
+export declare const DUMP_RETENTION_MS: number;
+export declare const BOUNCE_DESCRIPTIONS: Record<BounceType, string>;
+/** False for a bounce type whose effect on the address is not captured: recording one throws `Unsupported`. */
+export declare const bounceEffectCaptured: (type: BounceType) => boolean;
+export declare const recipientsOf: (message: OutboundMessage) => string[];
+/** A bounce is readable until retention ends (T14). */
+export declare const bounceVisible: (bounce: Bounce, now: Date) => boolean;
+export declare const dumpAvailable: (bounce: Bounce, now: Date) => boolean;
+/** A bounce of this server within retention, or 422 / 1001. */
+export declare function findBounce(runtime: Runtime, server: Server, id: number): Bounce;
+export interface BounceReport {
+    message: OutboundMessage;
+    /** One recipient of the message. */
+    email: string;
+    type: BounceType;
+    details: string;
+    /** Raw dump; "" when none. */
+    content: string;
+}
+/**
+ * The recipient server (or the recipient, for SpamComplaint) reports a bounce: T1, T3, T4.
+ * A deactivating type marks the bounce inactive and adds a Recipient row on the message stream
+ * unless one exists. Emits the bounce event, then `subscriptionChange` for a new row (Q12 order).
+ */
+export declare const recordBounce: (runtime: Runtime, report: BounceReport) => Promise<Bounce>;
+/** `recordBounce` with a bounce ID the caller claimed and a time: a seed records past bounces (docs/11 §5). */
+export declare function recordBounceAt(runtime: Runtime, report: BounceReport, { id, at }: {
+    id: number;
+    at: Date;
+}): Promise<Bounce>;
+/**
+ * The recipient unsubscribes through Postmark's link on a Broadcasts stream with
+ * `UnsubscribeHandlingType: Postmark` (T5). Returns false when the address is already unsubscribed;
+ * an unsubscribe over another row is not captured.
+ */
+export declare function recordUnsubscribe(runtime: Runtime, message: OutboundMessage, email: string): Promise<boolean>;
+/** `PUT /bounces/{id}/activate` (T11, T12). */
+export declare function activateBounce(runtime: Runtime, bounce: Bounce): Promise<void>;
+export interface SuppressionStatus {
+    EmailAddress: string;
+    Status: "Suppressed" | "Deleted" | "Failed";
+    Message: string | null;
+}
+/**
+ * Address syntax for the Suppressions API: one `@`, no spaces, a dot in the domain. The exact rule
+ * is INFERRED; `not-a-correct-email-address` fails (sdk/postmark-dotnet/src/Postmark.Tests/ClientSuppressionTests.cs:40).
+ */
+export declare const isEmailAddress: (value: string) => boolean;
+/** `POST .../suppressions`, one item (T6). */
+export declare function suppressByCustomer(runtime: Runtime, serverId: number, stream: string, email: string): Promise<SuppressionStatus>;
+/** `POST .../suppressions/delete`, one item (T7–T10). */
+export declare function deleteSuppression(runtime: Runtime, serverId: number, stream: string, email: string): Promise<SuppressionStatus>;

package/dist/src/recipients/transitions.js

@@ -0,0 +1,279 @@
+import { apiError } from "../errors.js";
+import { Unsupported } from "../http/respond.js";
+import { suppressionKey } from "../state/store.js";
+import { findSuppression } from "../state/suppressions.js";
+// The recipient state machine of docs/04 §3.2: bounces, suppressions and the events between them.
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Bounces are kept 45 days (refs/api_bounce-api.md:4); their suppression rows stay (T14, INFERRED). */
+export const BOUNCE_RETENTION_MS = 45 * DAY_MS;
+/** No dump after 30 days (refs/api_bounce-api.md:141). */
+export const DUMP_RETENTION_MS = 30 * DAY_MS;
+// refs/api_bounce-api.md:397-418.
+export const BOUNCE_DESCRIPTIONS = {
+    HardBounce: "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
+    Transient: "The server could not temporarily deliver your message (ex: Message is delayed due to network troubles).",
+    Unsubscribe: "Unsubscribe or Remove request.",
+    Subscribe: "Subscribe request from someone wanting to get added to the mailing list.",
+    AutoResponder: '"Autoresponder" is an automatic email responder including nondescript NDRs and some "out of office" replies.',
+    AddressChange: "The recipient has requested an address change.",
+    DnsError: "A temporary DNS error.",
+    SpamNotification: "The message was delivered, but was either blocked by the user, or classified as spam, bulk mail, or had rejected content.",
+    OpenRelayTest: "The NDR is actually a test email message to see if the mail server is an open relay.",
+    Unknown: "Unable to classify the NDR.",
+    SoftBounce: "Unable to temporarily deliver message (i.e. mailbox full, account disabled, exceeds quota, out of disk space).",
+    VirusNotification: "The bounce is actually a virus notification warning about a virus/code infected message.",
+    ChallengeVerification: "The bounce is a challenge asking for verification you actually sent the email. Typcial challenges are made by Spam Arrest, or MailFrontier Matador.",
+    BadEmailAddress: "The address is not a valid email address.",
+    SpamComplaint: "The subscriber explicitly marked this message as spam.",
+    ManuallyDeactivated: "The email was manually deactivated.",
+    Unconfirmed: "The subscriber has not clicked on the confirmation link upon registration or import.",
+    Blocked: "Blocked from this ISP due to content or blacklisting.",
+    SMTPApiError: "An error occurred while accepting an email through the SMTP API.",
+    InboundError: "Unable to deliver inbound message to destination inbound hook.",
+    DMARCPolicy: "Email rejected due DMARC Policy.",
+    TemplateRenderingFailed: "An error occurred while attempting to render your template.",
+};
+/**
+ * Bounce types whose effect on the address is known (docs/04 §1.4): `true` deactivates.
+ * HardBounce and SpamComplaint are DOC; `false` rows are INFERRED (Q13). SoftBounce "sometimes"
+ * deactivates (DOC); postmock never does (Q13). Types absent here have an unknown effect.
+ */
+const DEACTIVATES = {
+    HardBounce: true,
+    SpamComplaint: true,
+    Transient: false,
+    Subscribe: false,
+    AutoResponder: false,
+    AddressChange: false,
+    DnsError: false,
+    SpamNotification: false,
+    OpenRelayTest: false,
+    Unknown: false,
+    SoftBounce: false,
+    VirusNotification: false,
+    ChallengeVerification: false,
+};
+/** False for a bounce type whose effect on the address is not captured: recording one throws `Unsupported`. */
+export const bounceEffectCaptured = (type) => DEACTIVATES[type] !== undefined;
+export const recipientsOf = (message) => [...message.To, ...message.Cc, ...message.Bcc].map((a) => a.Email);
+/** A bounce is readable until retention ends (T14). */
+export const bounceVisible = (bounce, now) => now.getTime() - bounce.BouncedAt.getTime() < BOUNCE_RETENTION_MS;
+export const dumpAvailable = (bounce, now) => bounce.Content !== "" && now.getTime() - bounce.BouncedAt.getTime() < DUMP_RETENTION_MS;
+/** A bounce of this server within retention, or 422 / 1001. */
+export function findBounce(runtime, server, id) {
+    const bounce = runtime.store.state.bounces.get(id);
+    if (bounce === undefined ||
+        bounce.ServerID !== server.ID ||
+        !bounceVisible(bounce, runtime.clock.now())) {
+        // Message text INFERRED from the summary row (refs/api_overview.md:117).
+        throw apiError(1001, { message: "The bounce was not found." });
+    }
+    return bounce;
+}
+/**
+ * The recipient server (or the recipient, for SpamComplaint) reports a bounce: T1, T3, T4.
+ * A deactivating type marks the bounce inactive and adds a Recipient row on the message stream
+ * unless one exists. Emits the bounce event, then `subscriptionChange` for a new row (Q12 order).
+ */
+export const recordBounce = (runtime, report) => recordBounceAt(runtime, report, {
+    id: runtime.store.nextId("bounce"),
+    at: runtime.clock.now(),
+});
+/** `recordBounce` with a bounce ID the caller claimed and a time: a seed records past bounces (docs/11 §5). */
+export async function recordBounceAt(runtime, report, { id, at }) {
+    const { store, events } = runtime;
+    const { message, email, type } = report;
+    const deactivates = DEACTIVATES[type];
+    if (deactivates === undefined) {
+        throw new Unsupported(`bounce type ${type}: effect on the address is not captured (docs/04 Q13)`);
+    }
+    const reason = type === "SpamComplaint" ? "SpamComplaint" : "HardBounce";
+    const existing = findSuppression(store.state, message.ServerID, message.MessageStream, email);
+    if (deactivates && existing !== undefined && existing.SuppressionReason !== reason) {
+        throw new Unsupported(`${type} for ${email}, suppressed as ${existing.SuppressionReason}/${existing.Origin}: effect not captured`);
+    }
+    const bounce = {
+        ID: id,
+        ServerID: message.ServerID,
+        MessageStream: message.MessageStream,
+        MessageID: message.MessageID,
+        Type: type,
+        Tag: message.Tag,
+        Description: BOUNCE_DESCRIPTIONS[type],
+        Details: report.details,
+        Email: email,
+        From: message.From,
+        Subject: message.Subject ?? "",
+        BouncedAt: at,
+        Inactive: deactivates,
+        // A spam complaint cannot be reactivated (refs/webhooks_spam-complaint-webhook.md:6,58).
+        CanActivate: type !== "SpamComplaint",
+        Content: report.content,
+        Metadata: message.Metadata,
+    };
+    store.state.bounces.set(bounce.ID, bounce);
+    const event = type === "SpamComplaint" ? "spamComplaint" : "bounced";
+    await events.emit(event, { bounce });
+    if (deactivates && existing === undefined) {
+        await addSuppression(runtime, {
+            serverId: message.ServerID,
+            stream: message.MessageStream,
+            email,
+            reason,
+            origin: "Recipient",
+            message,
+            at,
+        });
+    }
+    return bounce;
+}
+/**
+ * The recipient unsubscribes through Postmark's link on a Broadcasts stream with
+ * `UnsubscribeHandlingType: Postmark` (T5). Returns false when the address is already unsubscribed;
+ * an unsubscribe over another row is not captured.
+ */
+export async function recordUnsubscribe(runtime, message, email) {
+    const existing = findSuppression(runtime.store.state, message.ServerID, message.MessageStream, email);
+    if (existing !== undefined) {
+        if (existing.SuppressionReason === "ManualSuppression" && existing.Origin === "Recipient") {
+            return false;
+        }
+        throw new Unsupported(`unsubscribe over a ${existing.SuppressionReason}/${existing.Origin} row is not captured`);
+    }
+    await addSuppression(runtime, {
+        serverId: message.ServerID,
+        stream: message.MessageStream,
+        email,
+        reason: "ManualSuppression",
+        origin: "Recipient",
+        message,
+        at: runtime.clock.now(),
+    });
+    return true;
+}
+async function addSuppression(runtime, row) {
+    const now = row.at;
+    const suppression = {
+        ServerID: row.serverId,
+        MessageStream: row.stream,
+        EmailAddress: row.email,
+        SuppressionReason: row.reason,
+        Origin: row.origin,
+        CreatedAt: now,
+    };
+    runtime.store.state.suppressions.set(suppressionKey(row.serverId, row.stream, row.email), suppression);
+    // refs/webhooks_subscription-change-webhook.md:35-38: MessageID null for a manual suppression.
+    await runtime.events.emit("subscriptionChange", {
+        change: {
+            MessageID: row.message?.MessageID ?? null,
+            ServerID: row.serverId,
+            MessageStream: row.stream,
+            ChangedAt: now,
+            Recipient: row.email,
+            Origin: row.origin,
+            SuppressSending: true,
+            SuppressionReason: row.reason,
+            Tag: row.message?.Tag ?? null,
+            Metadata: row.message?.Metadata ?? {},
+        },
+    });
+}
+/**
+ * Removes a row the customer may lift and reactivates its bounces (T7, T8, T11). The
+ * `subscriptionChange` event has the null fields of a reactivation (docs/05 §2.6).
+ */
+async function reactivate(runtime, row) {
+    const { store, clock } = runtime;
+    store.state.suppressions.delete(suppressionKey(row.ServerID, row.MessageStream, row.EmailAddress));
+    const email = row.EmailAddress.toLowerCase();
+    // The bounces that caused the row turn active (docs/04 §3.2 T7, flag change INFERRED).
+    for (const bounce of store.state.bounces.values()) {
+        if (bounce.ServerID === row.ServerID &&
+            bounce.MessageStream === row.MessageStream &&
+            bounce.Email.toLowerCase() === email &&
+            bounce.Inactive) {
+            bounce.Inactive = false;
+        }
+    }
+    await runtime.events.emit("subscriptionChange", {
+        change: {
+            MessageID: null,
+            ServerID: row.ServerID,
+            MessageStream: row.MessageStream,
+            ChangedAt: clock.now(),
+            Recipient: row.EmailAddress,
+            Origin: "Customer",
+            SuppressSending: false,
+            SuppressionReason: null,
+            Tag: null,
+            Metadata: {},
+        },
+    });
+}
+/** `PUT /bounces/{id}/activate` (T11, T12). */
+export async function activateBounce(runtime, bounce) {
+    if (!bounce.CanActivate)
+        throw apiError(1003);
+    if (!bounce.Inactive) {
+        throw new Unsupported("activate on an active bounce is not captured (docs/04 Q9)");
+    }
+    const row = findSuppression(runtime.store.state, bounce.ServerID, bounce.MessageStream, bounce.Email);
+    // Every path that removes a row also turns its bounces active.
+    if (row === undefined)
+        throw new Error(`inactive bounce ${bounce.ID} has no suppression row`);
+    if (row.SuppressionReason !== "HardBounce") {
+        throw new Unsupported(`activate with a ${row.SuppressionReason}/${row.Origin} row is not captured`);
+    }
+    await reactivate(runtime, row);
+}
+// refs/api_suppressions-api.md:158-165.
+const AUTHORITY = "You do not have the required authority to change this suppression.";
+const INVALID_ADDRESS = "An invalid email address was provided.";
+/**
+ * Address syntax for the Suppressions API: one `@`, no spaces, a dot in the domain. The exact rule
+ * is INFERRED; `not-a-correct-email-address` fails (sdk/postmark-dotnet/src/Postmark.Tests/ClientSuppressionTests.cs:40).
+ */
+export const isEmailAddress = (value) => /^[^@\s<>()",;:]+@[^@\s<>()",;:]+\.[^@\s<>()",;:]+$/.test(value);
+/** `POST .../suppressions`, one item (T6). */
+export async function suppressByCustomer(runtime, serverId, stream, email) {
+    if (!isEmailAddress(email))
+        return { EmailAddress: email, Status: "Failed", Message: INVALID_ADDRESS };
+    const existing = findSuppression(runtime.store.state, serverId, stream, email);
+    if (existing === undefined) {
+        await addSuppression(runtime, {
+            serverId,
+            stream,
+            email,
+            reason: "ManualSuppression",
+            origin: "Customer",
+            message: null,
+            at: runtime.clock.now(),
+        });
+    }
+    else if (existing.SuppressionReason === "SpamComplaint") {
+        return { EmailAddress: email, Status: "Failed", Message: AUTHORITY };
+    }
+    else if (existing.SuppressionReason !== "ManualSuppression" || existing.Origin !== "Customer") {
+        throw new Unsupported(`suppress ${email} over a ${existing.SuppressionReason}/${existing.Origin} row is not captured`);
+    }
+    return { EmailAddress: email, Status: "Suppressed", Message: null };
+}
+/** `POST .../suppressions/delete`, one item (T7–T10). */
+export async function deleteSuppression(runtime, serverId, stream, email) {
+    // Failed for bad syntax on delete is INFERRED from create (docs/04 §2.4).
+    if (!isEmailAddress(email))
+        return { EmailAddress: email, Status: "Failed", Message: INVALID_ADDRESS };
+    const row = findSuppression(runtime.store.state, serverId, stream, email);
+    if (row === undefined)
+        return { EmailAddress: email, Status: "Deleted", Message: null };
+    if (row.SuppressionReason === "SpamComplaint") {
+        return { EmailAddress: email, Status: "Failed", Message: AUTHORITY };
+    }
+    const liftable = (row.SuppressionReason === "HardBounce" && row.Origin === "Recipient") ||
+        (row.SuppressionReason === "ManualSuppression" && row.Origin === "Customer");
+    if (!liftable) {
+        throw new Unsupported(`delete of a ${row.SuppressionReason}/${row.Origin} row is not captured (docs/04 Q4)`);
+    }
+    await reactivate(runtime, row);
+    return { EmailAddress: email, Status: "Deleted", Message: null };
+}

package/dist/src/render/mustachio.d.ts

@@ -0,0 +1,60 @@
+/** `up` counts `../` prefixes; empty `keys` is `{{.}}`. */
+interface Path {
+    raw: string;
+    up: number;
+    keys: string[];
+}
+type Node = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "value";
+    path: Path;
+    escape: boolean;
+} | {
+    kind: "section";
+    path: Path;
+    inverted: boolean;
+    children: Node[];
+} | {
+    kind: "each";
+    path: Path;
+    children: Node[];
+}
+/** `{{{ @content }}}`: where a layout takes the template (article :320-326). */
+ | {
+    kind: "content";
+};
+/** A `/templates/validate` error: 1-based, `null` when unknown (refs/api_templates-api.md:842). */
+export interface TemplateError {
+    Message: string;
+    Line: number | null;
+    CharacterPosition: number | null;
+}
+export interface ParsedTemplate {
+    nodes: Node[];
+    /** Number of `{{{ @content }}}` placeholders. */
+    contentPlaceholders: number;
+}
+export type ParseResult = {
+    ok: true;
+    template: ParsedTemplate;
+} | {
+    ok: false;
+    errors: TemplateError[];
+};
+/** Parses Mustachio source. Every syntax error is collected with its position. */
+export declare function parseTemplate(source: string): ParseResult;
+/**
+ * Renders a parsed template with a model. `content` fills `{{{ @content }}}` in a layout.
+ * A missing value renders as "" (docs/06 §3.5, INFERRED).
+ */
+export declare function renderTemplate(template: ParsedTemplate, model: unknown, content?: string): string;
+/**
+ * `SuggestedTemplateModel`: a placeholder `<key>_Value` for every key the templates read
+ * (refs/api_templates-api.md:844, :873-886).
+ */
+export declare function suggestModel(templates: readonly ParsedTemplate[]): Record<string, unknown>;
+/** Deep merge; `override` values win and its keys come first (refs/api_templates-api.md:873-886). */
+export declare function mergeModels(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown>;
+export {};