@benclmnt/postmock 0.0.1

package/dist/src/api/message-streams/routes.js

@@ -0,0 +1,211 @@
+import { z } from "zod";
+import { apiError } from "../../errors.js";
+import { absent, parseBody, queryBool } from "../../http/normalize.js";
+import { Unsupported } from "../../http/respond.js";
+import { defineRoute } from "../../http/routes.js";
+import { streamKey } from "../../state/store.js";
+import { formatTimestamp } from "../../time.js";
+import { liveStream, PURGE_DELAY_MS, schedulePurge, streamJson } from "./streams.js";
+// Message Streams API: docs/04 §4. Error texts come from the docs/02 §4.4 table.
+const MAX_STREAMS = 10; // refs/api_message-streams-api.md:4
+/** Default streams that cannot be archived (refs/api_overview.md:136). */
+const UNARCHIVABLE = new Set(["outbound", "inbound"]);
+/** 1220 when the account has no Message Streams API access (docs/04 §4.4). */
+function streamsOf(ctx) {
+    if (!ctx.store.state.account.messageStreamsApiEnabled)
+        throw apiError(1220);
+    return [...ctx.store.state.streams.values()].filter((s) => s.ServerID === ctx.auth.server.ID);
+}
+function streamOf(ctx) {
+    streamsOf(ctx);
+    return liveStream(ctx.store.state, ctx.auth.server.ID, ctx.params.id);
+}
+/** Enum text matched without case, stored in doc case (INFERRED, like query keys: docs/08 R3). */
+const oneOf = (values, text) => values.find((v) => v.toLowerCase() === text.toLowerCase());
+const STREAM_TYPES = ["Transactional", "Broadcasts", "Inbound"];
+const HANDLING_TYPES = ["None", "Postmark", "Custom"];
+defineRoute({
+    method: "GET",
+    path: "/message-streams",
+    auth: "server",
+    handler: (ctx) => {
+        const typeText = ctx.query.get("MessageStreamType") ?? "All";
+        const type = oneOf(["All", ...STREAM_TYPES], typeText);
+        if (type === undefined)
+            throw apiError(1221);
+        const archived = queryBool.safeParse(ctx.query.get("IncludeArchivedStreams") ?? "false");
+        if (!archived.success)
+            throw new Unsupported("invalid IncludeArchivedStreams: not captured");
+        // count and offset are accepted and ignored (docs/08 R6).
+        const streams = streamsOf(ctx).filter((s) => (type === "All" || s.MessageStreamType === type) &&
+            (archived.data || s.ArchivedAt === null));
+        return { MessageStreams: streams.map(streamJson), TotalCount: streams.length };
+    },
+});
+defineRoute({
+    method: "GET",
+    path: "/message-streams/:id",
+    auth: "server",
+    handler: (ctx) => streamJson(streamOf(ctx)),
+});
+const handlingSchema = z
+    .object({ UnsubscribeHandlingType: absent(z.string()) })
+    .nullable()
+    .optional();
+/**
+ * The checked `UnsubscribeHandlingType` for a stream type (1238–1240). Broadcasts require
+ * unsubscribe management (refs/api_message-streams-api.md:50); a Transactional or Inbound stream
+ * with `Postmark` or `Custom` is not captured.
+ */
+function handlingType(ctx, streamType, text) {
+    if (text === undefined)
+        return streamType === "Broadcasts" ? "Postmark" : "None";
+    const value = oneOf(HANDLING_TYPES, text);
+    if (value === undefined)
+        throw apiError(1240);
+    if (value === "Custom" && !ctx.store.state.account.customUnsubscribeEnabled)
+        throw apiError(1238);
+    if (streamType === "Broadcasts" && value === "None")
+        throw apiError(1239);
+    if (streamType !== "Broadcasts" && value !== "None") {
+        throw new Unsupported(`UnsubscribeHandlingType ${value} on a ${streamType} stream: not captured`);
+    }
+    return value;
+}
+/** 1234: HTML in a description (tag rule INFERRED). Length limits (1224, 1231) are not documented. */
+function checkDescription(description) {
+    if (description !== undefined && /<\/?[a-z!][^>]*>/i.test(description))
+        throw apiError(1234);
+}
+const createSchema = z.object({
+    ID: z.unknown(),
+    Name: absent(z.string()),
+    Description: absent(z.string()),
+    MessageStreamType: absent(z.string()),
+    SubscriptionManagementConfiguration: handlingSchema,
+});
+defineRoute({
+    method: "POST",
+    path: "/message-streams",
+    auth: "server",
+    handler: (ctx) => {
+        const streams = streamsOf(ctx);
+        const parsed = parseBody(createSchema, ctx.body ?? {});
+        if (!parsed.success)
+            throw new Unsupported("malformed stream body: error not captured");
+        const body = parsed.data;
+        const id = body.ID;
+        if (typeof id !== "string" || id === "")
+            throw apiError(1222);
+        if (id.toLowerCase().startsWith("pm-"))
+            throw apiError(1233);
+        // Allowed characters after the first letter are INFERRED.
+        if (!/^[A-Za-z][A-Za-z0-9_-]{0,29}$/.test(id))
+            throw apiError(1227);
+        if (body.Name === undefined)
+            throw apiError(1223);
+        checkDescription(body.Description);
+        const type = oneOf(STREAM_TYPES, body.MessageStreamType ?? "");
+        if (type === "Inbound")
+            throw apiError(1228); // every server has its inbound stream
+        if (type === undefined)
+            throw apiError(1221);
+        // IDs clash without case (INFERRED); lookups keep case.
+        if (streams.some((s) => s.ID.toLowerCase() === id.toLowerCase()))
+            throw apiError(1230);
+        if (streams.length >= MAX_STREAMS)
+            throw apiError(1225);
+        const handling = handlingType(ctx, type, body.SubscriptionManagementConfiguration?.UnsubscribeHandlingType);
+        const stream = {
+            ID: id,
+            ServerID: ctx.auth.server.ID,
+            Name: body.Name,
+            Description: body.Description ?? null,
+            MessageStreamType: type,
+            CreatedAt: ctx.clock.now(),
+            UpdatedAt: null,
+            ArchivedAt: null,
+            ExpectedPurgeDate: null,
+            SubscriptionManagementConfiguration: { UnsubscribeHandlingType: handling },
+        };
+        // The ID of a purged stream is free again (INFERRED).
+        ctx.store.state.purgedStreams.delete(streamKey(stream.ServerID, id));
+        ctx.store.state.streams.set(streamKey(stream.ServerID, id), stream);
+        return streamJson(stream);
+    },
+});
+// dotnet sends `Name: null` to keep the name (R9); an empty string is no valid name (INFERRED).
+const editSchema = z.object({
+    Name: z.string().nullable().optional(),
+    Description: absent(z.string()),
+    SubscriptionManagementConfiguration: handlingSchema,
+});
+// java sends the whole stream object; only these three fields change (docs/04 §4.1).
+defineRoute({
+    method: "PATCH",
+    path: "/message-streams/:id",
+    auth: "server",
+    handler: (ctx) => {
+        const stream = streamOf(ctx);
+        if (stream.ArchivedAt !== null)
+            throw new Unsupported("edit of an archived stream: not captured");
+        const parsed = parseBody(editSchema, ctx.body ?? {});
+        if (!parsed.success)
+            throw new Unsupported("malformed stream body: error not captured");
+        const body = parsed.data;
+        checkDescription(body.Description);
+        const text = body.SubscriptionManagementConfiguration?.UnsubscribeHandlingType;
+        const handling = text === undefined
+            ? stream.SubscriptionManagementConfiguration.UnsubscribeHandlingType
+            : handlingType(ctx, stream.MessageStreamType, text);
+        if (body.Name === "")
+            throw apiError(1223);
+        if (body.Name !== undefined && body.Name !== null)
+            stream.Name = body.Name;
+        if (body.Description !== undefined)
+            stream.Description = body.Description;
+        stream.SubscriptionManagementConfiguration = { UnsubscribeHandlingType: handling };
+        stream.UpdatedAt = ctx.clock.now();
+        return streamJson(stream);
+    },
+});
+// Archive and unarchive accept an empty body and `{}` (docs/04 §6); the body is not read.
+defineRoute({
+    method: "POST",
+    path: "/message-streams/:id/archive",
+    auth: "server",
+    handler: (ctx) => {
+        const stream = streamOf(ctx);
+        if (UNARCHIVABLE.has(stream.ID))
+            throw apiError(1229);
+        if (stream.ArchivedAt !== null)
+            throw new Unsupported("archive of an archived stream: not captured");
+        const now = ctx.clock.now();
+        stream.ArchivedAt = now;
+        stream.ExpectedPurgeDate = new Date(now.getTime() + PURGE_DELAY_MS);
+        schedulePurge(ctx, stream, stream.ExpectedPurgeDate);
+        // ID string and ServerID integer (docs/04 §4.2 disagreements; dotnet reads int ServerID).
+        return {
+            ID: stream.ID,
+            ServerID: stream.ServerID,
+            ExpectedPurgeDate: formatTimestamp(stream.ExpectedPurgeDate),
+        };
+    },
+});
+defineRoute({
+    method: "POST",
+    path: "/message-streams/:id/unarchive",
+    auth: "server",
+    handler: (ctx) => {
+        streamsOf(ctx);
+        const key = streamKey(ctx.auth.server.ID, ctx.params.id);
+        if (ctx.store.state.purgedStreams.has(key))
+            throw apiError(1232);
+        const stream = streamOf(ctx);
+        if (stream.ArchivedAt === null)
+            throw new Unsupported("unarchive of an active stream: not captured");
+        stream.ArchivedAt = null;
+        stream.ExpectedPurgeDate = null;
+        return streamJson(stream);
+    },
+});

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

@@ -0,0 +1,28 @@
+import type { Runtime } from "../../runtime.ts";
+import type { State } from "../../state/store.ts";
+import type { MessageStream } from "../../state/types.ts";
+/** Archived streams are deleted 45 days after archiving (refs/api_message-streams-api.md:48). */
+export declare const PURGE_DELAY_MS: number;
+/**
+ * Deletes an archived stream with its suppressions and bounces at its purge date, unless it was
+ * unarchived before. "deleted (alongside associated data)":
+ * sdk/postmark-dotnet/src/Postmark/PostmarkClient.cs:1242. Messages of the stream stay (INFERRED).
+ */
+export declare function schedulePurge(runtime: Runtime, stream: MessageStream, due: Date): void;
+/** A stream of the server, or 422 / 1226. IDs match with case kept (INFERRED). */
+export declare function liveStream(state: State, serverId: number, id: string): MessageStream;
+/** refs/api_message-streams-api.md:40-50, in doc field order. */
+export declare const streamJson: (s: MessageStream) => {
+    ID: string;
+    ServerID: number;
+    Name: string;
+    Description: string | null;
+    MessageStreamType: import("../../state/types.ts").MessageStreamType;
+    CreatedAt: string;
+    UpdatedAt: string | null;
+    ArchivedAt: string | null;
+    ExpectedPurgeDate: string | null;
+    SubscriptionManagementConfiguration: {
+        UnsubscribeHandlingType: import("../../state/types.ts").UnsubscribeHandlingType;
+    };
+};

package/dist/src/api/message-streams/streams.js

@@ -0,0 +1,50 @@
+import { apiError } from "../../errors.js";
+import { streamKey } from "../../state/store.js";
+import { formatTimestamp } from "../../time.js";
+/** Archived streams are deleted 45 days after archiving (refs/api_message-streams-api.md:48). */
+export const PURGE_DELAY_MS = 45 * 24 * 60 * 60 * 1000;
+/**
+ * Deletes an archived stream with its suppressions and bounces at its purge date, unless it was
+ * unarchived before. "deleted (alongside associated data)":
+ * sdk/postmark-dotnet/src/Postmark/PostmarkClient.cs:1242. Messages of the stream stay (INFERRED).
+ */
+export function schedulePurge(runtime, stream, due) {
+    const key = streamKey(stream.ServerID, stream.ID);
+    runtime.clock.schedule(due.getTime() - runtime.clock.now().getTime(), () => {
+        const state = runtime.store.state;
+        if (state.streams.get(key)?.ExpectedPurgeDate?.getTime() !== due.getTime())
+            return;
+        state.streams.delete(key);
+        state.purgedStreams.add(key);
+        const inStream = (row) => row.ServerID === stream.ServerID && row.MessageStream === stream.ID;
+        for (const [k, row] of state.suppressions)
+            if (inStream(row))
+                state.suppressions.delete(k);
+        for (const [id, bounce] of state.bounces)
+            if (inStream(bounce))
+                state.bounces.delete(id);
+    });
+}
+/** A stream of the server, or 422 / 1226. IDs match with case kept (INFERRED). */
+export function liveStream(state, serverId, id) {
+    const stream = state.streams.get(streamKey(serverId, id));
+    if (stream === undefined)
+        throw apiError(1226, { family: "streams" });
+    return stream;
+}
+const stamp = (d) => (d === null ? null : formatTimestamp(d));
+/** refs/api_message-streams-api.md:40-50, in doc field order. */
+export const streamJson = (s) => ({
+    ID: s.ID,
+    ServerID: s.ServerID,
+    Name: s.Name,
+    Description: s.Description,
+    MessageStreamType: s.MessageStreamType,
+    CreatedAt: formatTimestamp(s.CreatedAt),
+    UpdatedAt: stamp(s.UpdatedAt),
+    ArchivedAt: stamp(s.ArchivedAt),
+    ExpectedPurgeDate: stamp(s.ExpectedPurgeDate),
+    SubscriptionManagementConfiguration: {
+        UnsubscribeHandlingType: s.SubscriptionManagementConfiguration.UnsubscribeHandlingType,
+    },
+});

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

@@ -0,0 +1,149 @@
+import type { ClickEvent, InboundMessage, OpenEvent, OutboundMessage } from "../../state/types.ts";
+/** Search item (refs/api_messages-api.md:62-89). `Attachments` are names (docs/06 §1.5, Q3). */
+export declare const outboundJson: (m: OutboundMessage) => {
+    Tag: string;
+    MessageID: string;
+    MessageStream: string;
+    To: import("../../state/types.ts").Address[];
+    Cc: import("../../state/types.ts").Address[];
+    Bcc: import("../../state/types.ts").Address[];
+    Recipients: string[];
+    ReceivedAt: string;
+    From: string;
+    Subject: string;
+    Attachments: string[];
+    Status: import("../../state/types.ts").OutboundStatus;
+    TrackOpens: boolean;
+    TrackLinks: import("../../state/types.ts").TrackLinks;
+    Metadata: Record<string, string>;
+    Sandboxed: boolean;
+};
+/** Details (refs/api_messages-api.md:147-238). */
+export declare const outboundDetailsJson: (m: OutboundMessage) => {
+    Tag: string;
+    MessageID: string;
+    MessageStream: string;
+    To: import("../../state/types.ts").Address[];
+    Cc: import("../../state/types.ts").Address[];
+    Bcc: import("../../state/types.ts").Address[];
+    Recipients: string[];
+    ReceivedAt: string;
+    From: string;
+    Subject: string;
+    Attachments: string[];
+    Status: import("../../state/types.ts").OutboundStatus;
+    TrackOpens: boolean;
+    TrackLinks: import("../../state/types.ts").TrackLinks;
+    Metadata: Record<string, string>;
+    Sandboxed: boolean;
+    TextBody: string;
+    HtmlBody: string;
+    Body: string;
+    MessageEvents: {
+        Recipient: string;
+        Type: import("../../state/types.ts").MessageEventType;
+        ReceivedAt: string;
+        Details: Record<string, string>;
+    }[];
+};
+/**
+ * Search item (refs/api_messages-api.md:335-372). postmark.js also reads `Bcc`, `BccFull` and
+ * `MessageStream` (sdk/postmark.js/src/client/models/messages/InboundMessage.ts:8-28).
+ */
+export declare const inboundJson: (m: InboundMessage) => {
+    From: string;
+    FromName: string;
+    FromFull: {
+        Email: string;
+        Name: string;
+    };
+    To: string;
+    ToFull: import("../../state/types.ts").InboundAddress[];
+    CcFull: import("../../state/types.ts").InboundAddress[];
+    Cc: string;
+    Bcc: string;
+    BccFull: import("../../state/types.ts").InboundAddress[];
+    ReplyTo: string;
+    OriginalRecipient: string;
+    Subject: string;
+    Date: string;
+    MailboxHash: string;
+    Tag: string;
+    Attachments: {
+        Name: string;
+        ContentID: string;
+        ContentType: string;
+        ContentLength: number;
+    }[];
+    MessageID: string;
+    MessageStream: string;
+    Status: import("../../state/types.ts").InboundStatus;
+};
+/** Details (refs/api_messages-api.md:431-518). */
+export declare const inboundDetailsJson: (m: InboundMessage) => {
+    From: string;
+    FromName: string;
+    FromFull: {
+        Email: string;
+        Name: string;
+    };
+    To: string;
+    ToFull: import("../../state/types.ts").InboundAddress[];
+    CcFull: import("../../state/types.ts").InboundAddress[];
+    Cc: string;
+    Bcc: string;
+    BccFull: import("../../state/types.ts").InboundAddress[];
+    ReplyTo: string;
+    OriginalRecipient: string;
+    Subject: string;
+    Date: string;
+    MailboxHash: string;
+    Tag: string;
+    Attachments: {
+        Name: string;
+        ContentID: string;
+        ContentType: string;
+        ContentLength: number;
+    }[];
+    MessageStream: string;
+    TextBody: string;
+    HtmlBody: string;
+    StrippedTextReply: string;
+    Headers: import("../../state/types.ts").Header[];
+    MessageID: string;
+    BlockedReason: string;
+    Status: import("../../state/types.ts").InboundStatus;
+};
+/**
+ * An open (refs/api_messages-api.md:671-699). The single-message example has no `RecordType`
+ * (:769-797). `FirstOpen` and `ReadSeconds` are not in the Messages API docs; they stay out.
+ */
+export declare const openJson: (o: OpenEvent, single: boolean) => {
+    Client?: import("../../state/types.ts").ClientInfo;
+    OS?: import("../../state/types.ts").ClientInfo;
+    Platform?: "Desktop" | "Mobile" | "Unknown" | "WebMail";
+    UserAgent: string;
+    Geo?: import("../../state/types.ts").Geo;
+    MessageID: string;
+    MessageStream: string;
+    ReceivedAt: string;
+    Tag: string;
+    Recipient: string;
+    RecordType?: string;
+};
+/** A click (refs/api_messages-api.md:879-909, :979-1009). */
+export declare const clickJson: (c: ClickEvent, single: boolean) => {
+    Client?: import("../../state/types.ts").ClientInfo;
+    OS?: import("../../state/types.ts").ClientInfo;
+    Platform?: "Desktop" | "Mobile" | "Unknown" | "WebMail";
+    UserAgent: string;
+    Geo?: import("../../state/types.ts").Geo;
+    MessageID: string;
+    MessageStream: string;
+    ReceivedAt: string;
+    Tag: string;
+    Recipient: string;
+    RecordType?: string;
+    ClickLocation: "HTML" | "Text";
+    OriginalLink: string;
+};

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

@@ -0,0 +1,114 @@
+import { recipientsOf } from "../../recipients/transitions.js";
+import { formatTimestamp } from "../../time.js";
+// Wire shapes of the Messages API, in doc field order. A null string field is sent as "", as the
+// inbound examples show for `Tag` and `MailboxHash` (INFERRED for outbound).
+/** Search item (refs/api_messages-api.md:62-89). `Attachments` are names (docs/06 §1.5, Q3). */
+export const outboundJson = (m) => ({
+    Tag: m.Tag ?? "",
+    MessageID: m.MessageID,
+    MessageStream: m.MessageStream,
+    To: m.To,
+    Cc: m.Cc,
+    Bcc: m.Bcc,
+    // Cc and Bcc addresses in `Recipients` are INFERRED; the example has To only.
+    Recipients: recipientsOf(m),
+    ReceivedAt: formatTimestamp(m.ReceivedAt),
+    From: m.From,
+    Subject: m.Subject ?? "",
+    Attachments: m.Attachments.map((a) => a.Name),
+    Status: m.Status,
+    TrackOpens: m.TrackOpens,
+    TrackLinks: m.TrackLinks,
+    Metadata: m.Metadata,
+    Sandboxed: m.Sandboxed,
+});
+const messageEventJson = (e) => ({
+    Recipient: e.Recipient,
+    Type: e.Type,
+    ReceivedAt: formatTimestamp(e.ReceivedAt),
+    Details: e.Details,
+});
+/** Details (refs/api_messages-api.md:147-238). */
+export const outboundDetailsJson = (m) => ({
+    TextBody: m.TextBody ?? "",
+    HtmlBody: m.HtmlBody ?? "",
+    Body: m.rawSource,
+    ...outboundJson(m),
+    MessageEvents: m.MessageEvents.map(messageEventJson),
+});
+/**
+ * Search item (refs/api_messages-api.md:335-372). postmark.js also reads `Bcc`, `BccFull` and
+ * `MessageStream` (sdk/postmark.js/src/client/models/messages/InboundMessage.ts:8-28).
+ */
+export const inboundJson = (m) => ({
+    From: m.From,
+    FromName: m.FromName,
+    FromFull: { Email: m.FromFull.Email, Name: m.FromFull.Name },
+    To: m.To,
+    ToFull: m.ToFull,
+    CcFull: m.CcFull,
+    Cc: m.Cc,
+    Bcc: m.Bcc,
+    BccFull: m.BccFull,
+    ReplyTo: m.ReplyTo,
+    OriginalRecipient: m.OriginalRecipient,
+    Subject: m.Subject,
+    Date: m.Date,
+    MailboxHash: m.MailboxHash,
+    Tag: m.Tag,
+    Attachments: m.Attachments.map((a) => ({
+        Name: a.Name,
+        ContentID: a.ContentID,
+        ContentType: a.ContentType,
+        ContentLength: a.ContentLength,
+    })),
+    MessageID: m.MessageID,
+    MessageStream: m.MessageStream,
+    Status: m.Status,
+});
+/** Details (refs/api_messages-api.md:431-518). */
+export const inboundDetailsJson = (m) => {
+    const { MessageID, Status, ...rest } = inboundJson(m);
+    return {
+        ...rest,
+        TextBody: m.TextBody,
+        HtmlBody: m.HtmlBody,
+        StrippedTextReply: m.StrippedTextReply,
+        Headers: m.Headers,
+        MessageID,
+        BlockedReason: m.BlockedReason ?? "",
+        Status,
+    };
+};
+/** Client, OS, Platform and Geo are left out when unknown (refs/api_messages-api.md:707). */
+const agentJson = (e) => ({
+    ...(e.Client && { Client: e.Client }),
+    ...(e.OS && { OS: e.OS }),
+    ...(e.Platform && { Platform: e.Platform }),
+    UserAgent: e.UserAgent,
+    ...(e.Geo && { Geo: e.Geo }),
+});
+const tail = (e) => ({
+    MessageID: e.MessageID,
+    MessageStream: e.MessageStream,
+    ReceivedAt: formatTimestamp(e.ReceivedAt),
+    Tag: e.Tag ?? "",
+    Recipient: e.Recipient,
+});
+/**
+ * An open (refs/api_messages-api.md:671-699). The single-message example has no `RecordType`
+ * (:769-797). `FirstOpen` and `ReadSeconds` are not in the Messages API docs; they stay out.
+ */
+export const openJson = (o, single) => ({
+    ...(!single && { RecordType: "Open" }),
+    ...agentJson(o),
+    ...tail(o),
+});
+/** A click (refs/api_messages-api.md:879-909, :979-1009). */
+export const clickJson = (c, single) => ({
+    ...(!single && { RecordType: "Click" }),
+    ClickLocation: c.ClickLocation,
+    ...agentJson(c),
+    OriginalLink: c.OriginalLink,
+    ...tail(c),
+});

package/dist/src/api/messages/query.d.ts

@@ -0,0 +1,19 @@
+import { type Query } from "../../http/normalize.ts";
+/** Messages, opens and clicks leave the API after the default retention (docs/06 §1.1). */
+export declare const RETENTION_MS: number;
+export declare const retained: (at: Date, now: Date) => boolean;
+/**
+ * `count` 1–500 and `offset` ≥ 0 are required; `count + offset` ≤ 10 000
+ * (refs/api_messages-api.md:34-35, :630-631). The clicks and single-message pages do not state the
+ * 10 000 cap; the mock applies it there too (INFERRED, docs/06 §5.4). A page past the cap is
+ * rejected, never clamped.
+ */
+export declare function paging(query: Query): {
+    count: number;
+    offset: number;
+};
+/** `fromdate`/`todate`, inclusive, Eastern time; a date-only `todate` covers its whole day. */
+export declare function dateRange(query: Query): (at: Date) => boolean;
+/** A `status` value from `allowed`, matched without case. */
+export declare function status<S extends string>(query: Query, allowed: Record<string, readonly S[]>): readonly S[] | undefined;
+export declare const sameText: (a: string | null | undefined, b: string) => boolean;

package/dist/src/api/messages/query.js

@@ -0,0 +1,64 @@
+import { apiError } from "../../errors.js";
+import { parseQueryDate } from "../../http/normalize.js";
+import { formatEasternDate } from "../../time.js";
+// Paging and filters shared by the Messages API reads (docs/06 §1.1, §1.7).
+// ErrorCode 700 is DOC (refs/api_overview.md:112); its message texts are INFERRED.
+/** Messages, opens and clicks leave the API after the default retention (docs/06 §1.1). */
+export const RETENTION_MS = 45 * 24 * 60 * 60 * 1000;
+export const retained = (at, now) => now.getTime() - at.getTime() <= RETENTION_MS;
+const invalid = (message) => apiError(700, { message });
+const integer = (query, name) => {
+    const raw = query.get(name);
+    if (raw === undefined)
+        return undefined;
+    return /^-?\d+$/.test(raw) ? Number(raw) : Number.NaN;
+};
+/**
+ * `count` 1–500 and `offset` ≥ 0 are required; `count + offset` ≤ 10 000
+ * (refs/api_messages-api.md:34-35, :630-631). The clicks and single-message pages do not state the
+ * 10 000 cap; the mock applies it there too (INFERRED, docs/06 §5.4). A page past the cap is
+ * rejected, never clamped.
+ */
+export function paging(query) {
+    const count = integer(query, "count");
+    const offset = integer(query, "offset");
+    if (count === undefined || !(count >= 1 && count <= 500)) {
+        throw invalid("The 'count' parameter must be an integer between 1 and 500.");
+    }
+    if (offset === undefined || !(offset >= 0)) {
+        throw invalid("The 'offset' parameter must be an integer of 0 or more.");
+    }
+    if (count + offset > 10000)
+        throw invalid("Count + Offset cannot exceed 10,000 messages.");
+    return { count, offset };
+}
+/** `fromdate`/`todate`, inclusive, Eastern time; a date-only `todate` covers its whole day. */
+export function dateRange(query) {
+    const bound = (name) => {
+        const raw = query.get(name);
+        if (raw === undefined)
+            return undefined;
+        const parsed = parseQueryDate(raw);
+        if (parsed === undefined)
+            throw invalid(`The '${name}' parameter is not a valid date.`);
+        return parsed;
+    };
+    const from = bound("fromdate");
+    const to = bound("todate");
+    return (at) => (from === undefined || at.getTime() >= from.instant.getTime()) &&
+        (to === undefined ||
+            (to.dateOnly
+                ? formatEasternDate(at) <= formatEasternDate(to.instant)
+                : at.getTime() <= to.instant.getTime()));
+}
+/** A `status` value from `allowed`, matched without case. */
+export function status(query, allowed) {
+    const raw = query.get("status");
+    if (raw === undefined)
+        return undefined;
+    const statuses = allowed[raw.toLowerCase()];
+    if (statuses === undefined)
+        throw invalid(`The 'status' parameter '${raw}' is not valid.`);
+    return statuses;
+}
+export const sameText = (a, b) => a != null && a.toLowerCase() === b.toLowerCase();

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

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