@benclmnt/postmock 0.0.1

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

@@ -0,0 +1,57 @@
+import type { Account, Bounce, BulkRequest, ClickEvent, DataRemoval, Domain, Fault, InboundMessage, InboundRule, MessageStream, OpenEvent, OutboundMessage, SenderSignature, Server, SmtpFault, SmtpToken, StatsFact, Suppression, Template, Webhook, WebhookAttempt } from "./types.ts";
+export type IdKind = "server" | "bounce" | "template" | "webhook" | "webhookAttempt" | "inboundRule" | "domain" | "sender" | "dataRemoval";
+export interface State {
+    account: Account;
+    servers: Map<number, Server>;
+    /** Key: `streamKey(serverId, streamId)`. */
+    streams: Map<string, MessageStream>;
+    /**
+     * `streamKey`s of archived streams deleted at their purge date. Unarchive answers 1232 for them;
+     * a new stream with the same ID removes the key (docs/04 §4.3).
+     */
+    purgedStreams: Set<string>;
+    /** Key: MessageID. */
+    outbound: Map<string, OutboundMessage>;
+    /** Key: MessageID. */
+    inbound: Map<string, InboundMessage>;
+    bounces: Map<number, Bounce>;
+    /** Key: `suppressionKey(serverId, streamId, email)`. */
+    suppressions: Map<string, Suppression>;
+    opens: OpenEvent[];
+    clicks: ClickEvent[];
+    /** Stats API facts, in event order. */
+    stats: StatsFact[];
+    templates: Map<number, Template>;
+    bulkRequests: Map<string, BulkRequest>;
+    webhooks: Map<number, Webhook>;
+    webhookAttempts: WebhookAttempt[];
+    inboundRules: Map<number, InboundRule>;
+    domains: Map<number, Domain>;
+    senders: Map<number, SenderSignature>;
+    dataRemovals: Map<number, DataRemoval>;
+    /** Key: access key. */
+    smtpTokens: Map<string, SmtpToken>;
+    faults: Fault[];
+    smtpFaults: SmtpFault[];
+    usedIds: Record<IdKind, Set<number>>;
+    /** Highest used ID per kind. */
+    maxIds: Record<IdKind, number>;
+}
+/** The whole in-memory account. `reset()` swaps in an empty state; hold the Store, not the state. */
+export declare class Store {
+    state: State;
+    private seedDepth;
+    reset(): void;
+    /**
+     * Runs a seed. Inside it `nextId` throws: a seed part claims fixed IDs from its track's range
+     * (docs/11 §5), so its IDs do not depend on the parts other tracks add.
+     */
+    seeding<T>(apply: () => Promise<T>): Promise<T>;
+    /** The next ID of a kind, above every ID used so far (docs/04 Mock must: bounce IDs increase). */
+    nextId(kind: IdKind): number;
+    /** Claims a fixed ID. */
+    useId(kind: IdKind, id: number): number;
+    private claim;
+}
+export declare const streamKey: (serverId: number, streamId: string) => string;
+export declare const suppressionKey: (serverId: number, streamId: string, email: string) => string;

package/dist/src/state/store.js

@@ -0,0 +1,98 @@
+function emptyState() {
+    return {
+        account: {
+            tokens: [],
+            approval: "approved",
+            bulkApiEnabled: true,
+            dataRemovalsEnabled: true,
+            messageStreamsApiEnabled: true,
+            customUnsubscribeEnabled: false,
+            serverDeletionEnabled: false,
+        },
+        servers: new Map(),
+        streams: new Map(),
+        purgedStreams: new Set(),
+        outbound: new Map(),
+        inbound: new Map(),
+        bounces: new Map(),
+        suppressions: new Map(),
+        opens: [],
+        clicks: [],
+        stats: [],
+        templates: new Map(),
+        bulkRequests: new Map(),
+        webhooks: new Map(),
+        webhookAttempts: [],
+        inboundRules: new Map(),
+        domains: new Map(),
+        senders: new Map(),
+        dataRemovals: new Map(),
+        smtpTokens: new Map(),
+        faults: [],
+        smtpFaults: [],
+        usedIds: {
+            server: new Set(),
+            bounce: new Set(),
+            template: new Set(),
+            webhook: new Set(),
+            webhookAttempt: new Set(),
+            inboundRule: new Set(),
+            domain: new Set(),
+            sender: new Set(),
+            dataRemoval: new Set(),
+        },
+        maxIds: {
+            server: 0,
+            bounce: 0,
+            template: 0,
+            webhook: 0,
+            webhookAttempt: 0,
+            inboundRule: 0,
+            domain: 0,
+            sender: 0,
+            dataRemoval: 0,
+        },
+    };
+}
+/** The whole in-memory account. `reset()` swaps in an empty state; hold the Store, not the state. */
+export class Store {
+    state = emptyState();
+    seedDepth = 0;
+    reset() {
+        this.state = emptyState();
+    }
+    /**
+     * Runs a seed. Inside it `nextId` throws: a seed part claims fixed IDs from its track's range
+     * (docs/11 §5), so its IDs do not depend on the parts other tracks add.
+     */
+    async seeding(apply) {
+        this.seedDepth += 1;
+        try {
+            return await apply();
+        }
+        finally {
+            this.seedDepth -= 1;
+        }
+    }
+    /** The next ID of a kind, above every ID used so far (docs/04 Mock must: bounce IDs increase). */
+    nextId(kind) {
+        if (this.seedDepth > 0)
+            throw new Error(`${kind} needs a fixed ID while seeding (store.useId)`);
+        return this.claim(kind, this.state.maxIds[kind] + 1);
+    }
+    /** Claims a fixed ID. */
+    useId(kind, id) {
+        if (!Number.isInteger(id) || id < 1 || this.state.usedIds[kind].has(id)) {
+            throw new Error(`${kind} ID ${id} is taken or invalid`);
+        }
+        return this.claim(kind, id);
+    }
+    claim(kind, id) {
+        this.state.usedIds[kind].add(id);
+        this.state.maxIds[kind] = Math.max(this.state.maxIds[kind], id);
+        return id;
+    }
+}
+export const streamKey = (serverId, streamId) => `${serverId}/${streamId}`;
+// Addresses compare without case (docs/04 Mock must, INFERRED).
+export const suppressionKey = (serverId, streamId, email) => `${serverId}/${streamId}/${email.toLowerCase()}`;

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

@@ -0,0 +1,9 @@
+import { type State } from "./store.ts";
+import type { Suppression } from "./types.ts";
+/** The suppression row of an address on one stream; addresses compare without case. */
+export declare const findSuppression: (state: State, serverId: number, streamId: string, email: string) => Suppression | undefined;
+/**
+ * The addresses of `emails` that a send on the stream must refuse with ErrorCode 406, in input
+ * order. Only the send stream's list counts (docs/04 §3.3; Q3).
+ */
+export declare const suppressedAddresses: (state: State, serverId: number, streamId: string, emails: readonly string[]) => string[];

package/dist/src/state/suppressions.js

@@ -0,0 +1,8 @@
+import { suppressionKey } from "./store.js";
+/** The suppression row of an address on one stream; addresses compare without case. */
+export const findSuppression = (state, serverId, streamId, email) => state.suppressions.get(suppressionKey(serverId, streamId, email));
+/**
+ * The addresses of `emails` that a send on the stream must refuse with ErrorCode 406, in input
+ * order. Only the send stream's list counts (docs/04 §3.3; Q3).
+ */
+export const suppressedAddresses = (state, serverId, streamId, emails) => emails.filter((email) => findSuppression(state, serverId, streamId, email) !== undefined);

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

@@ -0,0 +1,530 @@
+export type TrackLinks = "None" | "HtmlAndText" | "HtmlOnly" | "TextOnly";
+export declare const SERVER_COLORS: readonly ["purple", "blue", "turquoise", "green", "red", "yellow", "grey", "orange"];
+export type ServerColor = (typeof SERVER_COLORS)[number];
+export interface Header {
+    Name: string;
+    Value: string;
+}
+/** A parsed address. `Name` is null for a bare address (docs/06 §1.5). */
+export interface Address {
+    Email: string;
+    Name: string | null;
+}
+export interface Attachment {
+    Name: string;
+    /** Base64. */
+    Content: string;
+    ContentType: string;
+    ContentID: string | null;
+    /** Decoded byte count. */
+    ContentLength: number;
+}
+export interface Account {
+    tokens: string[];
+    /** 412 pending, 413 unapproved (docs/02 §4.4). */
+    approval: "approved" | "pending" | "unapproved";
+    /** Bulk API access; ErrorCode 14 when false (docs/03 §1.6). */
+    bulkApiEnabled: boolean;
+    /** Data removals access; ErrorCode 1302 when false (docs/04 §5). */
+    dataRemovalsEnabled: boolean;
+    /** Message streams API access; ErrorCode 1220 when false (docs/04 §4.4). */
+    messageStreamsApiEnabled: boolean;
+    /** Custom unsubscribe handling; ErrorCode 1238 when false (docs/04 §4.4). */
+    customUnsubscribeEnabled: boolean;
+    /** Server deletion through the API; ErrorCode 604 when false (refs/api_servers-api.md:483). */
+    serverDeletionEnabled: boolean;
+}
+export interface Server {
+    ID: number;
+    Name: string;
+    ApiTokens: string[];
+    Color: ServerColor;
+    SmtpApiActivated: boolean;
+    RawEmailEnabled: boolean;
+    DeliveryType: "Live" | "Sandbox";
+    ServerLink: string;
+    InboundAddress: string;
+    InboundHookUrl: string;
+    BounceHookUrl: string;
+    OpenHookUrl: string;
+    DeliveryHookUrl: string;
+    ClickHookUrl: string;
+    PostFirstOpenOnly: boolean;
+    InboundDomain: string;
+    InboundHash: string;
+    InboundSpamThreshold: number;
+    TrackOpens: boolean;
+    TrackLinks: TrackLinks;
+    IncludeBounceContentInHook: boolean;
+    EnableSmtpApiErrorHooks: boolean;
+}
+export type MessageStreamType = "Transactional" | "Broadcasts" | "Inbound";
+export type UnsubscribeHandlingType = "None" | "Postmark" | "Custom";
+export interface MessageStream {
+    ID: string;
+    ServerID: number;
+    Name: string;
+    Description: string | null;
+    MessageStreamType: MessageStreamType;
+    CreatedAt: Date;
+    UpdatedAt: Date | null;
+    ArchivedAt: Date | null;
+    ExpectedPurgeDate: Date | null;
+    SubscriptionManagementConfiguration: {
+        UnsubscribeHandlingType: UnsubscribeHandlingType;
+    };
+}
+export type OutboundStatus = "Queued" | "Sent" | "Processed";
+export type MessageEventType = "Delivered" | "Transient" | "Opened" | "LinkClicked" | "Bounced" | "SubscriptionChanged";
+export interface MessageEvent {
+    Recipient: string;
+    Type: MessageEventType;
+    ReceivedAt: Date;
+    Details: Record<string, string>;
+}
+export interface OutboundMessage {
+    MessageID: string;
+    ServerID: number;
+    MessageStream: string;
+    From: string;
+    To: Address[];
+    Cc: Address[];
+    Bcc: Address[];
+    ReplyTo: string | null;
+    Subject: string | null;
+    HtmlBody: string | null;
+    TextBody: string | null;
+    Tag: string | null;
+    Headers: Header[];
+    Attachments: Attachment[];
+    Metadata: Record<string, string>;
+    TrackOpens: boolean;
+    TrackLinks: TrackLinks;
+    Status: OutboundStatus;
+    Sandboxed: boolean;
+    /** `SubmittedAt` on the send response; `ReceivedAt` on the Messages API. */
+    ReceivedAt: Date;
+    MessageEvents: MessageEvent[];
+    channel: "rest" | "smtp";
+    /** The request JSON (REST) or raw MIME (SMTP), for `GET /control/messages` (docs/09 §5). */
+    request: unknown;
+    /** The generated MIME source served by the dump endpoint (docs/06 §1.2). */
+    rawSource: string;
+    bulkRequestId: string | null;
+    templateId: number | null;
+    /** Recipients on the stream's suppression list at send time; Postmark skips them (docs/04 §3.3). */
+    suppressedRecipients: string[];
+}
+export type InboundStatus = "Blocked" | "Processed" | "Queued" | "Failed" | "Scheduled" | "Sent";
+export interface InboundAddress {
+    Email: string;
+    Name: string;
+    MailboxHash: string;
+}
+export interface InboundAttachment {
+    Name: string;
+    Content: string;
+    ContentType: string;
+    ContentLength: number;
+    ContentID: string;
+}
+export interface InboundMessage {
+    MessageID: string;
+    ServerID: number;
+    MessageStream: string;
+    From: string;
+    FromName: string;
+    FromFull: InboundAddress;
+    To: string;
+    ToFull: InboundAddress[];
+    Cc: string;
+    CcFull: InboundAddress[];
+    Bcc: string;
+    BccFull: InboundAddress[];
+    OriginalRecipient: string;
+    ReplyTo: string;
+    Subject: string;
+    MailboxHash: string;
+    /** Sender RFC 2822 `Date` header, as received. */
+    Date: string;
+    TextBody: string;
+    HtmlBody: string;
+    StrippedTextReply: string;
+    Tag: string;
+    Headers: Header[];
+    Attachments: InboundAttachment[];
+    Status: InboundStatus;
+    BlockedReason: string | null;
+    ReceivedAt: Date;
+    rawEmail: string;
+}
+export declare const BOUNCE_TYPES: {
+    readonly HardBounce: {
+        readonly TypeCode: 1;
+        readonly Name: "Hard bounce";
+    };
+    readonly Transient: {
+        readonly TypeCode: 2;
+        readonly Name: "Message delayed/Undeliverable";
+    };
+    readonly Unsubscribe: {
+        readonly TypeCode: 16;
+        readonly Name: "Unsubscribe request";
+    };
+    readonly Subscribe: {
+        readonly TypeCode: 32;
+        readonly Name: "Subscribe request";
+    };
+    readonly AutoResponder: {
+        readonly TypeCode: 64;
+        readonly Name: "Auto responder";
+    };
+    readonly AddressChange: {
+        readonly TypeCode: 128;
+        readonly Name: "Address change";
+    };
+    readonly DnsError: {
+        readonly TypeCode: 256;
+        readonly Name: "DNS error";
+    };
+    readonly SpamNotification: {
+        readonly TypeCode: 512;
+        readonly Name: "Spam notification";
+    };
+    readonly OpenRelayTest: {
+        readonly TypeCode: 1024;
+        readonly Name: "Open relay test";
+    };
+    readonly Unknown: {
+        readonly TypeCode: 2048;
+        readonly Name: "Unknown";
+    };
+    readonly SoftBounce: {
+        readonly TypeCode: 4096;
+        readonly Name: "Soft bounce";
+    };
+    readonly VirusNotification: {
+        readonly TypeCode: 8192;
+        readonly Name: "Virus notification";
+    };
+    readonly ChallengeVerification: {
+        readonly TypeCode: 16384;
+        readonly Name: "Spam challenge verification";
+    };
+    readonly BadEmailAddress: {
+        readonly TypeCode: 100000;
+        readonly Name: "Invalid email address";
+    };
+    readonly SpamComplaint: {
+        readonly TypeCode: 100001;
+        readonly Name: "Spam complaint";
+    };
+    readonly ManuallyDeactivated: {
+        readonly TypeCode: 100002;
+        readonly Name: "Manually deactivated";
+    };
+    readonly Unconfirmed: {
+        readonly TypeCode: 100003;
+        readonly Name: "Registration not confirmed";
+    };
+    readonly Blocked: {
+        readonly TypeCode: 100006;
+        readonly Name: "ISP block";
+    };
+    readonly SMTPApiError: {
+        readonly TypeCode: 100007;
+        readonly Name: "SMTP API error";
+    };
+    readonly InboundError: {
+        readonly TypeCode: 100008;
+        readonly Name: "Processing failed";
+    };
+    readonly DMARCPolicy: {
+        readonly TypeCode: 100009;
+        readonly Name: "DMARC Policy";
+    };
+    readonly TemplateRenderingFailed: {
+        readonly TypeCode: 100010;
+        readonly Name: "Template rendering failed";
+    };
+};
+export type BounceType = keyof typeof BOUNCE_TYPES;
+export interface Bounce {
+    ID: number;
+    ServerID: number;
+    MessageStream: string;
+    MessageID: string;
+    Type: BounceType;
+    Tag: string | null;
+    Description: string;
+    Details: string;
+    Email: string;
+    From: string | null;
+    Subject: string;
+    BouncedAt: Date;
+    Inactive: boolean;
+    CanActivate: boolean;
+    /** Raw dump; `DumpAvailable` is false once it is empty or older than 30 days. */
+    Content: string;
+    Metadata: Record<string, string>;
+}
+export type SuppressionReason = "HardBounce" | "SpamComplaint" | "ManualSuppression";
+export type SuppressionOrigin = "Recipient" | "Customer" | "Admin";
+export interface Suppression {
+    ServerID: number;
+    MessageStream: string;
+    EmailAddress: string;
+    SuppressionReason: SuppressionReason;
+    Origin: SuppressionOrigin;
+    CreatedAt: Date;
+}
+export interface SubscriptionChange {
+    MessageID: string | null;
+    ServerID: number;
+    MessageStream: string;
+    ChangedAt: Date;
+    Recipient: string;
+    Origin: SuppressionOrigin;
+    SuppressSending: boolean;
+    SuppressionReason: SuppressionReason | null;
+    Tag: string | null;
+    Metadata: Record<string, string>;
+}
+export interface ClientInfo {
+    Name: string;
+    Company: string;
+    Family: string;
+}
+export interface Geo {
+    CountryISOCode?: string;
+    Country?: string;
+    RegionISOCode?: string;
+    Region?: string;
+    City?: string;
+    Zip?: string;
+    Coords?: string;
+    IP?: string;
+}
+export interface OpenEvent {
+    ServerID: number;
+    MessageID: string;
+    MessageStream: string;
+    Recipient: string;
+    Tag: string | null;
+    Metadata: Record<string, string>;
+    ReceivedAt: Date;
+    FirstOpen: boolean;
+    UserAgent: string;
+    ReadSeconds: number;
+    Client: ClientInfo | null;
+    OS: ClientInfo | null;
+    Platform: "WebMail" | "Desktop" | "Mobile" | "Unknown" | null;
+    Geo: Geo | null;
+}
+export interface ClickEvent {
+    ServerID: number;
+    MessageID: string;
+    MessageStream: string;
+    Recipient: string;
+    Tag: string | null;
+    Metadata: Record<string, string>;
+    ReceivedAt: Date;
+    UserAgent: string;
+    ClickLocation: "HTML" | "Text";
+    OriginalLink: string;
+    Client: ClientInfo | null;
+    OS: ClientInfo | null;
+    Platform: "WebMail" | "Desktop" | "Mobile" | "Unknown" | null;
+    Geo: Geo | null;
+}
+export type StatsFact = {
+    ServerID: number;
+    MessageStream: string;
+    Tag: string | null;
+    at: Date;
+} & ({
+    kind: "sent";
+    openTracking: boolean;
+    linkTracking: boolean;
+    trackedLinks: number;
+} | {
+    kind: "bounce";
+    type: "HardBounce" | "SoftBounce" | "Transient" | "SMTPApiError";
+} | {
+    kind: "spamComplaint";
+} | {
+    kind: "open";
+    MessageID: string;
+    Recipient: string;
+    /** The recipient's first open of the message ever. */
+    first: boolean;
+    platform: OpenEvent["Platform"];
+    client: string | null;
+    readSeconds: number;
+} | {
+    kind: "click";
+    MessageID: string;
+    Recipient: string;
+    /** The recipient's first click on this link of the message ever. */
+    first: boolean;
+    link: string;
+    location: ClickEvent["ClickLocation"];
+    platform: ClickEvent["Platform"];
+    browser: string | null;
+});
+export interface Template {
+    TemplateId: number;
+    ServerID: number;
+    Name: string;
+    Alias: string;
+    Subject: string | null;
+    HtmlBody: string | null;
+    TextBody: string | null;
+    TemplateType: "Standard" | "Layout";
+    LayoutTemplate: string | null;
+    Active: boolean;
+}
+export interface BulkRequest {
+    Id: string;
+    ServerID: number;
+    SubmittedAt: Date;
+    Status: "Accepted" | "Processing" | "Completed" | "Cancelled";
+    TotalMessages: number;
+    PercentageCompleted: number;
+    ReleasedCount: number;
+    FailedCount: number;
+    Subject: string | null;
+    messageIds: string[];
+    /** Why processing stopped on behavior postmock does not know (`Unsupported`), or null. */
+    unsupported: string | null;
+}
+export interface WebhookTriggers {
+    Open: {
+        Enabled: boolean;
+        PostFirstOpenOnly: boolean;
+    };
+    Click: {
+        Enabled: boolean;
+    };
+    Delivery: {
+        Enabled: boolean;
+    };
+    Bounce: {
+        Enabled: boolean;
+        IncludeContent: boolean;
+    };
+    SpamComplaint: {
+        Enabled: boolean;
+        IncludeContent: boolean;
+    };
+    SubscriptionChange: {
+        Enabled: boolean;
+    };
+}
+export interface Webhook {
+    ID: number;
+    ServerID: number;
+    Url: string;
+    MessageStream: string;
+    Status: "verified" | "unverified";
+    HttpAuth: {
+        Username: string;
+        Password: string;
+    } | null;
+    HttpHeaders: Header[];
+    Triggers: WebhookTriggers;
+}
+export type WebhookRecordType = "Bounce" | "SpamComplaint" | "Delivery" | "Open" | "Click" | "SubscriptionChange" | "Inbound";
+export interface WebhookAttempt {
+    id: number;
+    serverId: number;
+    /** The `/webhooks` row; null for a server hook URL (`BounceHookUrl`, `InboundHookUrl`, …). */
+    webhookId: number | null;
+    recordType: WebhookRecordType;
+    /** The URL as configured, userinfo included. */
+    url: string;
+    traceId: string;
+    /** Request headers as sent, the `Authorization` header included. */
+    headers: Header[];
+    /** The JSON body, the same bytes on every attempt of one event. */
+    body: string;
+    /** 1 for the first attempt. */
+    attempt: number;
+    at: Date;
+    outcome: {
+        status: number;
+    } | {
+        error: string;
+    };
+    /** What the outcome causes (docs/05 §3.4, §3.6). */
+    result: "success" | "retry" | "stop" | "exhausted";
+    nextAttemptAt: Date | null;
+}
+export interface InboundRule {
+    ID: number;
+    ServerID: number;
+    Rule: string;
+}
+export interface Domain {
+    ID: number;
+    Name: string;
+    SPFVerified: boolean;
+    SPFHost: string;
+    SPFTextValue: string;
+    DKIMVerified: boolean;
+    WeakDKIM: boolean;
+    DKIMHost: string;
+    DKIMTextValue: string;
+    DKIMPendingHost: string;
+    DKIMPendingTextValue: string;
+    DKIMRevokedHost: string;
+    DKIMRevokedTextValue: string;
+    SafeToRemoveRevokedKeyFromDNS: boolean;
+    DKIMUpdateStatus: "Pending" | "Verified";
+    ReturnPathDomain: string;
+    ReturnPathDomainVerified: boolean;
+    ReturnPathDomainCNAMEValue: string;
+}
+export interface SenderSignature extends Omit<Domain, "Name"> {
+    Domain: string;
+    EmailAddress: string;
+    ReplyToEmailAddress: string;
+    Name: string;
+    Confirmed: boolean;
+    ConfirmationPersonalNote: string;
+}
+export interface DataRemoval {
+    ID: number;
+    RequestedBy: string;
+    RequestedFor: string;
+    NotifyWhenCompleted: boolean;
+    Status: "Pending" | "Done";
+    createdAt: Date;
+}
+export interface SmtpToken {
+    accessKey: string;
+    secretKey: string;
+    serverId: number;
+    messageStream: string;
+}
+export interface SmtpFault {
+    stage: "connect" | "mail" | "rcpt" | "data";
+    remaining: number;
+    code: number;
+    message: string;
+}
+/** An error reply is built with `apiError`, so its status and code pair exists in docs/02 §4.4. */
+export type FaultReply = {
+    status: number;
+    body: {
+        ErrorCode: number;
+        Message: string;
+    };
+} | "timeout" | "reset";
+export interface Fault {
+    method: string;
+    /** A route pattern, matched like an API route (`/email`, `/templates/:id`). */
+    path: string;
+    remaining: number;
+    reply: FaultReply;
+}