@benclmnt/postmock 0.0.1

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

@@ -0,0 +1,252 @@
+import { z } from "zod";
+import { ApiError, apiError } from "../../errors.js";
+import { absent, parseBody, queryInt } from "../../http/normalize.js";
+import { Unsupported } from "../../http/respond.js";
+import { defineRoute } from "../../http/routes.js";
+import { draftFromJson, refuseSenderAfterDataError, validateOutbound, } from "../../pipeline/submit.js";
+import { newMessageId } from "../../state/ids.js";
+import { findStream } from "../../state/servers.js";
+import { formatTimestamp } from "../../time.js";
+import { renderContent } from "../templates/content.js";
+import { invalidField, nullable, sendTemplate, templateIdField, templateModelField, } from "../templates/templates.js";
+import { bulkStatusJson, bulkSubmission, scheduleBulk } from "./bulk.js";
+// Bulk API (docs/03 §1.6; refs/api_bulk-email.md). Not in the Swagger spec.
+/** 422 / 14 on all three endpoints until the account is approved (refs/api_bulk-email.md:411-420). */
+function requireBulkApproval(state) {
+    if (!state.account.bulkApiEnabled) {
+        throw apiError(14, {
+            message: "This endpoint requires approval to access. Contact support to use the Bulk API postmarkapp.com/contact",
+        });
+    }
+}
+const header = z.object({ Name: z.string(), Value: z.unknown().optional() });
+const metadata = nullable(z.record(z.string(), z.unknown()));
+const headers = nullable(z.array(header));
+const passed = z.unknown().optional();
+const bulkMessage = z.object({
+    To: passed,
+    Cc: passed,
+    Bcc: passed,
+    TemplateModel: templateModelField,
+    Metadata: metadata,
+    Headers: headers,
+});
+const bulkBody = z.object({
+    From: passed,
+    ReplyTo: passed,
+    Subject: absent(z.string()),
+    HtmlBody: absent(z.string()),
+    TextBody: absent(z.string()),
+    TemplateId: templateIdField,
+    TemplateAlias: absent(z.string()),
+    InlineCss: absent(z.boolean()),
+    Tag: passed,
+    Metadata: metadata,
+    MessageStream: absent(z.string()),
+    TrackOpens: passed,
+    TrackLinks: passed,
+    Attachments: passed,
+    Headers: headers,
+    Messages: z.array(bulkMessage),
+});
+function mergeHeaders(request, message) {
+    if (request === undefined)
+        return message;
+    const names = new Set((message ?? []).map((h) => h.Name.toLowerCase()));
+    return [...request.filter((h) => !names.has(h.Name.toLowerCase())), ...(message ?? [])];
+}
+/**
+ * Validates every message before any is accepted: one malformed field rejects the request with its
+ * own code, several with ErrorCode 11 and an `Errors` map keyed by field (refs/api_bulk-email.md:185,
+ * :213-231, :406-407). A message that fails to render is checked with its source content, so the
+ * render failure stays a `FailedCount` (refs/api_bulk-email.md:308).
+ */
+function checkMessages(ctx, auth, jobs, source) {
+    const errors = new Map();
+    for (const job of jobs) {
+        const draft = job.rendered.ok ? job.draft : withContent(job.draft, source);
+        const validation = validateOutbound(ctx, bulkSubmission(auth, draft, job.request, null, null));
+        if (validation.outcome === "valid")
+            continue;
+        const { field, error } = validation;
+        errors.set(`${field}/${error.ErrorCode}/${error.Message}`, { field, error });
+    }
+    const found = [...errors.values()];
+    const [only] = found;
+    if (only === undefined)
+        return;
+    // Every send rejection is HTTP 422 (docs/03 §3.1).
+    if (found.length === 1)
+        throw new ApiError(422, only.error);
+    const Errors = {};
+    for (const { field, error } of found)
+        Errors[field] = [...(Errors[field] ?? []), error];
+    throw apiError(11, {
+        message: "Multiple errors occurred. Inspect the Errors property for more information.",
+        extra: { Errors },
+    });
+}
+const withContent = (draft, content) => ({
+    ...draft,
+    Subject: content.Subject ?? undefined,
+    HtmlBody: content.HtmlBody ?? undefined,
+    TextBody: content.TextBody ?? undefined,
+});
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The request-level checks: body fields, template, stream. */
+function checkRequest(state, auth, body) {
+    const parsed = parseBody(bulkBody, body ?? {});
+    if (!parsed.success) {
+        const path = parsed.error.issues[0]?.path ?? [];
+        throw invalidField(String(path.findLast((p) => typeof p === "string")));
+    }
+    const input = parsed.data;
+    if (input.Messages.length === 0)
+        throw new Unsupported("a bulk request with no Messages");
+    const templated = input.TemplateId !== undefined || input.TemplateAlias !== undefined;
+    let content = {
+        Subject: input.Subject ?? null,
+        HtmlBody: input.HtmlBody ?? null,
+        TextBody: input.TextBody ?? null,
+    };
+    let layout = null;
+    let templateId = null;
+    if (templated) {
+        // Content beside a template: 1123, as on /email/withTemplate (INFERRED).
+        if (Object.values(content).some((v) => v !== null)) {
+            throw apiError(1123, {
+                message: "Subject, HtmlBody and TextBody cannot be used when sending with a template.",
+            });
+        }
+        const sent = sendTemplate(state, auth.server.ID, input);
+        content = sent.template;
+        templateId = sent.template.TemplateId;
+        layout = sent.layout;
+    }
+    // Absent: the default broadcast stream (refs/api_bulk-email.md:81; docs/04 Q7 for its ID).
+    const streamId = input.MessageStream ?? "broadcast";
+    const stream = findStream(state, auth, streamId);
+    if (stream === undefined)
+        throw apiError(1226, { family: "streams" });
+    if (stream.MessageStreamType !== "Broadcasts") {
+        throw new Unsupported(`bulk sends on a ${stream.MessageStreamType} stream are not captured`);
+    }
+    return { input, content, layout, templateId, streamId };
+}
+defineRoute({
+    method: "POST",
+    path: "/email/bulk",
+    auth: "server",
+    handler: async (ctx) => {
+        const { store, auth } = ctx;
+        const { state } = store;
+        requireBulkApproval(state);
+        let request;
+        try {
+            request = checkRequest(state, auth, ctx.body);
+        }
+        catch (error) {
+            if (error instanceof ApiError && isObject(ctx.body)) {
+                refuseSenderAfterDataError(ctx, auth, draftFromJson(ctx.body).From);
+            }
+            throw error;
+        }
+        const { input, content, layout, templateId, streamId } = request;
+        // Body keys arrive in any case (docs/08 R8); `request` keeps each entry as sent.
+        const rawMessages = Object.entries(ctx.body).find(([key]) => key.toLowerCase() === "messages")?.[1];
+        const jobs = input.Messages.map((message, i) => {
+            // Message-level metadata keys win over request-level keys (INFERRED per key).
+            const Metadata = input.Metadata === undefined && message.Metadata === undefined
+                ? undefined
+                : { ...input.Metadata, ...message.Metadata };
+            const rendered = renderContent(content, layout, message.TemplateModel ?? {}, input.InlineCss ?? true);
+            // Keys are canonical here; `draftFromJson` keeps one folding rule for every JSON draft.
+            const draft = draftFromJson({
+                From: input.From,
+                To: message.To,
+                Cc: message.Cc,
+                Bcc: message.Bcc,
+                ReplyTo: input.ReplyTo,
+                Tag: input.Tag,
+                MessageStream: streamId,
+                Headers: mergeHeaders(input.Headers, message.Headers),
+                Attachments: input.Attachments,
+                Metadata,
+                TrackOpens: input.TrackOpens,
+                TrackLinks: input.TrackLinks,
+            });
+            return {
+                draft: rendered.ok ? withContent(draft, rendered.content) : draft,
+                rendered,
+                request: rawMessages[i],
+            };
+        });
+        checkMessages(ctx, auth, jobs, content);
+        const bulk = {
+            Id: newMessageId(),
+            ServerID: auth.server.ID,
+            SubmittedAt: ctx.clock.now(),
+            Status: "Accepted",
+            TotalMessages: jobs.length,
+            PercentageCompleted: 0,
+            ReleasedCount: 0,
+            FailedCount: 0,
+            // A templated request has no request Subject, so the key is omitted (INFERRED).
+            Subject: input.Subject ?? null,
+            messageIds: [],
+            unsupported: null,
+        };
+        state.bulkRequests.set(bulk.Id, bulk);
+        scheduleBulk(ctx, auth, bulk, jobs, templateId);
+        // The dotnet live test reads TotalMessages from the POST answer, so it is the full status
+        // object (sdk/postmark-dotnet/src/Postmark.Tests/ClientBulkSendingTests.cs:51-54).
+        return bulkStatusJson(bulk);
+    },
+});
+/** Another server's request is 404 / 12 like an unknown one (refs/api_bulk-email.md:427-429). */
+defineRoute({
+    method: "GET",
+    path: "/email/bulk/:id",
+    auth: "server",
+    handler: ({ store, params, auth }) => {
+        requireBulkApproval(store.state);
+        const bulk = store.state.bulkRequests.get(params.id ?? "");
+        if (bulk === undefined || bulk.ServerID !== auth.server.ID)
+            throw apiError(12);
+        return bulkStatusJson(bulk);
+    },
+});
+// PaginationKey: unpadded base64 of the next page's first request, like the doc example
+// `{"SubmittedAt":…}` (refs/api_bulk-email.md:380, :395). postmock adds its Id and uses the URL-safe
+// alphabet, so the key needs no escaping in a query string (INFERRED).
+const encodeKey = (bulk) => Buffer.from(JSON.stringify({ SubmittedAt: formatTimestamp(bulk.SubmittedAt, "utc"), Id: bulk.Id })).toString("base64url");
+defineRoute({
+    method: "GET",
+    path: "/email/bulk",
+    auth: "server",
+    handler: ({ store, query, auth }) => {
+        requireBulkApproval(store.state);
+        const paging = query.pick(z.object({ count: queryInt }));
+        // docs/03 Q20: the count default and range are not documented.
+        if (!paging.success || paging.data.count < 1 || paging.data.count > 500) {
+            throw new Unsupported("GET /email/bulk needs a count from 1 to 500; other values are not captured");
+        }
+        const requests = [...store.state.bulkRequests.values()]
+            .filter((b) => b.ServerID === auth.server.ID)
+            .reverse()
+            .sort((a, b) => b.SubmittedAt.getTime() - a.SubmittedAt.getTime());
+        const key = query.get("paginationKey");
+        let start = 0;
+        if (key !== undefined) {
+            start = requests.findIndex((b) => encodeKey(b) === key);
+            if (start === -1)
+                throw apiError(13);
+        }
+        const page = requests.slice(start, start + paging.data.count);
+        const next = requests[start + paging.data.count];
+        return {
+            Requests: page.map(bulkStatusJson),
+            ...(next !== undefined && { PaginationKey: encodeKey(next) }),
+        };
+    },
+});

package/dist/src/api/data-removals/routes.d.ts

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

package/dist/src/api/data-removals/routes.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { apiError } from "../../errors.js";
+import { parseBody } from "../../http/normalize.js";
+import { Unsupported } from "../../http/respond.js";
+import { defineRoute } from "../../http/routes.js";
+import { isEmailAddress } from "../../recipients/transitions.js";
+// Data Removals API: docs/04 §5. A request stays Pending: the time to Done and what it erases are
+// not captured (Q16). The 1300 and 1301 texts are INFERRED from their summary rows.
+const EMPTY = "Empty request.";
+const NOT_FOUND = "Missing or incorrect data removal request ID.";
+const json = (r) => ({ ID: r.ID, Status: r.Status });
+function checkAccess(enabled) {
+    if (!enabled)
+        throw apiError(1302);
+}
+const createSchema = z.object({
+    RequestedBy: z.string(),
+    RequestedFor: z.string(),
+    NotifyWhenCompleted: z.boolean(),
+});
+defineRoute({
+    method: "POST",
+    path: "/data-removals",
+    auth: "account",
+    handler: ({ store, clock, body }) => {
+        checkAccess(store.state.account.dataRemovalsEnabled);
+        if (body === undefined || z.object({}).strict().safeParse(body).success) {
+            throw apiError(1300, { message: EMPTY });
+        }
+        const parsed = parseBody(createSchema, body);
+        if (!parsed.success)
+            throw new Unsupported("malformed data removal body: error not captured (Q16)");
+        const request = parsed.data;
+        if (!isEmailAddress(request.RequestedFor)) {
+            throw new Unsupported("invalid RequestedFor: error not captured (docs/04 Q16)");
+        }
+        const removal = {
+            ID: store.nextId("dataRemoval"),
+            ...request,
+            Status: "Pending",
+            createdAt: clock.now(),
+        };
+        store.state.dataRemovals.set(removal.ID, removal);
+        return json(removal);
+    },
+});
+defineRoute({
+    method: "GET",
+    path: "/data-removals/:id",
+    auth: "account",
+    handler: ({ store, params }) => {
+        checkAccess(store.state.account.dataRemovalsEnabled);
+        const raw = params.id;
+        const removal = /^\d+$/.test(raw) ? store.state.dataRemovals.get(Number(raw)) : undefined;
+        if (removal === undefined)
+            throw apiError(1301, { message: NOT_FOUND });
+        return json(removal);
+    },
+});

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

@@ -0,0 +1,11 @@
+import type { SubmitResult } from "../../pipeline/submit.ts";
+/** The `POST /email` response, or the error envelope (HTTP 422 for every send code). */
+export declare function sendResponse(result: SubmitResult, to: string): {
+    To: string;
+    SubmittedAt: string;
+    MessageID: string;
+    ErrorCode: number;
+    Message: string;
+};
+/** One batch item: the send response, or `{ErrorCode, Message}` only (docs/03 §2). */
+export declare function batchItem(result: SubmitResult, to: string): import("../../errors.ts").ErrorBody;

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

@@ -0,0 +1,33 @@
+import { apiErrorOf } from "../../errors.js";
+import { batchItemError } from "../../pipeline/inactive.js";
+import { formatTimestamp } from "../../time.js";
+/**
+ * A send result, in the order of refs/api_email-api.md "Example response". `to` is the request `To`
+ * value, echoed as sent (docs/03 §1.2). The test token answers "Test job accepted" (docs/03 §4).
+ */
+function success(result, to) {
+    const [submittedAt, messageId, text] = result.outcome === "accepted"
+        ? [result.message.ReceivedAt, result.message.MessageID, "OK"]
+        : [result.submittedAt, result.messageId, "Test job accepted"];
+    return {
+        To: to,
+        SubmittedAt: formatTimestamp(submittedAt),
+        MessageID: messageId,
+        ErrorCode: 0,
+        Message: text,
+    };
+}
+/** The `POST /email` response, or the error envelope (HTTP 422 for every send code). */
+export function sendResponse(result, to) {
+    if (result.outcome === "rejected" || result.outcome === "partiallySuppressed") {
+        throw apiErrorOf(result.error);
+    }
+    return success(result, to);
+}
+/** One batch item: the send response, or `{ErrorCode, Message}` only (docs/03 §2). */
+export function batchItem(result, to) {
+    if (result.outcome === "rejected" || result.outcome === "partiallySuppressed") {
+        return batchItemError(result.error);
+    }
+    return success(result, to);
+}

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

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

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

@@ -0,0 +1,64 @@
+import { apiError } from "../../errors.js";
+import { Unsupported } from "../../http/respond.js";
+import { defineRoute } from "../../http/routes.js";
+import { acceptOutbound, acceptOutbounds, draftFromJson, validateOutbound, } from "../../pipeline/submit.js";
+import { batchItem, sendResponse } from "./json.js";
+const MAX_BATCH_MESSAGES = 500;
+const MAX_BATCH_BYTES = 50 * 1024 * 1024;
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const validateJson = (runtime, auth, body) => validateOutbound(runtime, {
+    auth,
+    channel: "rest",
+    draft: draftFromJson(body),
+    request: body,
+    bulkRequestId: null,
+    templateId: null,
+});
+// refs/api_email-api.md (docs/03 §1.2).
+defineRoute({
+    method: "POST",
+    path: "/email",
+    auth: "serverOrTest",
+    handler: async (ctx) => {
+        // An empty or non-object body is not captured (docs/02 Q16).
+        if (!isObject(ctx.body))
+            throw new Unsupported("an /email body that is not a JSON object");
+        const validation = validateJson(ctx, ctx.auth, ctx.body);
+        if (validation.outcome === "rejected")
+            return sendResponse(validation, "");
+        const { outbound } = validation;
+        return sendResponse(await acceptOutbound(ctx, outbound), outbound.draft.To);
+    },
+});
+// refs/api_email-api.md (docs/03 §1.3, §2): 200 with one item per message, in request order.
+defineRoute({
+    method: "POST",
+    path: "/email/batch",
+    auth: "serverOrTest",
+    handler: async (ctx) => {
+        // An empty body, a non-array, or a non-object item is not captured (docs/02 Q16).
+        if (!Array.isArray(ctx.body) || !ctx.body.every(isObject)) {
+            throw new Unsupported("a batch body that is not a JSON array of objects");
+        }
+        if (ctx.body.length > MAX_BATCH_MESSAGES)
+            throw apiError(410);
+        // HTTP 413 above 50 MB (refs/api_overview.md:30); its body is not captured (docs/02 Q10).
+        if (Buffer.byteLength(JSON.stringify(ctx.body)) > MAX_BATCH_BYTES) {
+            throw new Unsupported("HTTP 413 for an oversized batch: body not captured (docs/02 Q10)");
+        }
+        // Every item is validated before any is stored, so a 501 leaves no partial batch behind.
+        const validations = ctx.body.map((body) => validateJson(ctx, ctx.auth, body));
+        // Whether 1235 is per item or for the whole request is not captured (docs/03 §8 Q14).
+        if (validations.some((v) => v.outcome === "rejected" && v.error.ErrorCode === 1235)) {
+            throw new Unsupported("an unknown MessageStream in a batch (docs/03 §8 Q14)");
+        }
+        const accepted = await acceptOutbounds(ctx, validations.flatMap((v) => (v.outcome === "valid" ? [v.outbound] : [])));
+        let next = 0;
+        const items = validations.map((validation) => {
+            if (validation.outcome === "rejected")
+                return batchItem(validation, "");
+            return batchItem(accepted[next++], validation.outbound.draft.To);
+        });
+        return items;
+    },
+});

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

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

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

@@ -0,0 +1,40 @@
+import { apiError } from "../../errors.js";
+import { defineRoute } from "../../http/routes.js";
+import { deliverInbound } from "../../inbound/deliver.js";
+// Bypass and retry of inbound messages (refs/api_messages-api.md:525-601, docs/06 §1).
+// The 701 texts are INFERRED from the docs/02 §4.4 summary.
+function transition({ store, params, auth }, from, action) {
+    const message = store.state.inbound.get(params.id ?? "");
+    if (message === undefined || message.ServerID !== auth.server.ID) {
+        throw apiError(701, { message: "This message was not found." });
+    }
+    if (message.Status !== from)
+        throw apiError(701, { message: `This message cannot be ${action}.` });
+    return message;
+}
+defineRoute({
+    method: "PUT",
+    path: "/messages/inbound/:id/bypass",
+    auth: "server",
+    handler: async (ctx) => {
+        const message = transition(ctx, "Blocked", "bypassed");
+        message.Status = "Queued";
+        await deliverInbound(ctx, message);
+        return { ErrorCode: 0, Message: `Successfully bypassed message: ${message.MessageID}.` };
+    },
+});
+// A retry starts the retry schedule again (INFERRED).
+defineRoute({
+    method: "PUT",
+    path: "/messages/inbound/:id/retry",
+    auth: "server",
+    handler: async (ctx) => {
+        const message = transition(ctx, "Failed", "retried");
+        message.Status = "Queued";
+        await deliverInbound(ctx, message);
+        return {
+            ErrorCode: 0,
+            Message: `Successfully rescheduled failed message: ${message.MessageID}.`,
+        };
+    },
+});

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

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

package/dist/src/api/index.js

@@ -0,0 +1,3 @@
+import { importAll } from "../discover.js";
+// Loads every `src/api/<group>/routes.ts`; each registers its routes with `defineRoute`.
+await importAll(new URL("./", import.meta.url), "routes");

package/dist/src/api/message-streams/routes.d.ts

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