stageflow 0.30.0 → 0.32.0

package/dist/email/host.js

@@ -0,0 +1,119 @@
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { EmailAccounts } from "./accounts.js";
+import { LocalEmailAdapter } from "./adapter.js";
+import { EmailError } from "./port.js";
+const hosts = new Map();
+export function emailHostFor(cwd) {
+    const key = path.resolve(cwd);
+    let host = hosts.get(key);
+    if (host?.releasing)
+        throw new EmailError("EMAIL_CONNECTION_FAILED", true);
+    if (!host) {
+        const accounts = new EmailAccounts(key);
+        host = { accounts, mailbox: new LocalEmailAdapter(accounts) };
+        hosts.set(key, host);
+    }
+    return host;
+}
+export async function releaseEmailHost(cwd) {
+    const key = path.resolve(cwd);
+    const host = hosts.get(key);
+    if (!host)
+        return;
+    host.releasing ??= host.mailbox.stop();
+    await host.releasing;
+    if (hosts.get(key) === host)
+        hosts.delete(key);
+}
+export function validateStageEmailAccounts(accounts, stage) {
+    for (const permission of stage.email ?? [])
+        accounts.get(permission.accountId);
+}
+export function stageEmail(mailbox, stage, runId, context) {
+    const permissions = structuredClone(stage.email ?? []);
+    const stageId = stage.id;
+    const artifacts = context ? { ...context, stageId } : undefined;
+    function authorize(accountId, operation) {
+        if (!permissions.some(permission => permission.accountId === accountId && permission.operations.includes(operation))) {
+            throw new EmailError("EMAIL_UNAUTHORIZED");
+        }
+    }
+    function operationKey(key) {
+        if (typeof key !== "string" || !key.length || key.length > 120)
+            throw new EmailError("EMAIL_INVALID_INPUT");
+        return createHash("sha256").update(JSON.stringify([runId, stageId, key])).digest("hex");
+    }
+    return {
+        async search(input) {
+            authorize(input?.accountId, "search");
+            return mailbox.search(input);
+        },
+        async getMessage(ref) {
+            authorize(ref?.accountId, "getMessage");
+            return mailbox.getMessage(ref);
+        },
+        async send(input) {
+            authorize(input?.accountId, "send");
+            return mailbox.send({ ...input, operationKey: operationKey(input.operationKey) }, artifacts);
+        },
+        async reply(input) {
+            authorize(input?.ref?.accountId, "reply");
+            return mailbox.reply({ ...input, operationKey: operationKey(input.operationKey) }, artifacts);
+        },
+        async downloadAttachment(input) {
+            authorize(input?.ref?.accountId, "downloadAttachment");
+            return mailbox.downloadAttachment(input, artifacts);
+        },
+    };
+}
+export function emailWorkerEnvironment(env, accounts) {
+    const result = { ...env };
+    for (const account of accounts.list())
+        for (const connection of [account.imap, account.smtp]) {
+            if (connection.auth.secretRef.startsWith("env:"))
+                delete result[connection.auth.secretRef.slice(4)];
+        }
+    return result;
+}
+/** The inherited IPC channel identifies the child; no caller-provided run or stage identity is accepted. */
+export function workerStageEmail() {
+    function request(operation, input) {
+        return new Promise((resolve, reject) => {
+            if (!process.connected || !process.send) {
+                reject(new EmailError("EMAIL_UNAUTHORIZED"));
+                return;
+            }
+            const requestId = randomUUID();
+            const finish = (error, result) => {
+                clearTimeout(timer);
+                process.off("message", receive);
+                process.off("disconnect", disconnected);
+                if (error)
+                    reject(error);
+                else
+                    resolve(result);
+            };
+            const submitting = operation === "send" || operation === "reply";
+            const disconnected = () => finish(new EmailError(submitting ? "EMAIL_SEND_OUTCOME_UNKNOWN" : "EMAIL_CONNECTION_FAILED", !submitting));
+            const receive = (message) => {
+                const response = message;
+                if (response?.type !== "email.response" || response.requestId !== requestId)
+                    return;
+                finish(response.error ? new EmailError(response.error.code, response.error.retryable, response.error.unsupportedFields) : undefined, response.result ?? response.receipt);
+            };
+            const timer = setTimeout(disconnected, 65000);
+            process.on("message", receive);
+            process.once("disconnect", disconnected);
+            process.send({ type: `email.${operation}`, requestId, input }, error => { if (error)
+                disconnected(); });
+        });
+    }
+    return {
+        send(input) { return request("send", input); },
+        reply(input) { return request("reply", input); },
+        search(input) { return request("search", input); },
+        getMessage(ref) { return request("getMessage", ref); },
+        downloadAttachment(input) { return request("downloadAttachment", input); },
+    };
+}

package/dist/email/messages.d.ts

@@ -0,0 +1,44 @@
+import type { FetchMessageObject } from "imapflow";
+import { type EmailMessage, type EmailMessageRef, type EmailMessageSummary, type SearchEmailsInput } from "./port.js";
+import type { EmailAccount } from "./accounts.js";
+export declare const EMAIL_SOURCE_LIMIT: number;
+export type MailRecord = {
+    uid: number;
+    source: Buffer;
+    flags: Set<string>;
+    receivedAt: Date;
+};
+type Reference = {
+    scope: string;
+    accountId: string;
+    mailbox: string;
+    generation: string;
+    uid: number;
+};
+export declare function messageRef(account: EmailAccount, mailbox: string, generation: string, uid: number): EmailMessageRef;
+export declare function decodeRef(account: EmailAccount, ref: EmailMessageRef): Reference;
+export declare function validateMailbox(mailbox: string): void;
+export declare const EMAIL_SEARCH_FIELDS: string[];
+export type MailQuery = {
+    mailbox: string;
+    limit: number;
+    sort: "newest" | "oldest";
+    fingerprint: string;
+    filters: SearchEmailsInput;
+};
+type Cursor = {
+    query: string;
+    scope: string;
+    accountId: string;
+    generation: string;
+    high: number;
+    last: number;
+};
+export declare function searchQuery(input: SearchEmailsInput): MailQuery;
+export declare function matchesSearch(summary: EmailMessageSummary, query: MailQuery): boolean;
+export declare function searchCursor(account: EmailAccount, query: MailQuery, generation: string, high: number, last: number, key: Buffer): string;
+export declare function decodeCursor(account: EmailAccount, query: MailQuery, generation: string, cursor: string | undefined, key: Buffer): Cursor | undefined;
+export declare function parseMessage(account: EmailAccount, mailbox: string, generation: string, record: MailRecord): Promise<EmailMessage>;
+export declare function summarize(message: EmailMessage): EmailMessageSummary;
+export declare function envelopeSummary(account: EmailAccount, mailbox: string, generation: string, value: FetchMessageObject): EmailMessageSummary;
+export {};

package/dist/email/messages.js

@@ -0,0 +1,182 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { simpleParser } from "mailparser";
+import { EmailError } from "./port.js";
+import { safeAttachmentFilename } from "./attachments.js";
+export const EMAIL_SOURCE_LIMIT = 1024 * 1024;
+const BODY_LIMIT = 128 * 1024;
+function scopeId(account) {
+    return createHash("sha256").update(account.scope).digest("hex");
+}
+export function messageRef(account, mailbox, generation, uid) {
+    const value = { scope: scopeId(account), accountId: account.accountId, mailbox, generation, uid };
+    return { accountId: account.accountId, mailbox, id: Buffer.from(JSON.stringify(value)).toString("base64url") };
+}
+export function decodeRef(account, ref) {
+    try {
+        if (typeof ref.id !== "string" || ref.id.length > 2048 || !/^[A-Za-z0-9_-]+$/.test(ref.id))
+            throw new Error();
+        const value = JSON.parse(Buffer.from(ref.id, "base64url").toString());
+        if (value.scope !== scopeId(account) || value.accountId !== account.accountId)
+            throw new EmailError("EMAIL_UNAUTHORIZED");
+        if (typeof value.generation !== "string" || !/^\d+$/.test(value.generation) || !Number.isSafeInteger(value.uid) || value.uid < 1)
+            throw new Error();
+        validateMailbox(value.mailbox);
+        if (ref.mailbox !== undefined && ref.mailbox !== value.mailbox)
+            throw new Error();
+        return value;
+    }
+    catch (error) {
+        if (error instanceof EmailError && error.code === "EMAIL_UNAUTHORIZED")
+            throw error;
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    }
+}
+export function validateMailbox(mailbox) {
+    if (typeof mailbox !== "string" || !mailbox.length || mailbox.length > 200 || /[\x00-\x1f\x7f]/.test(mailbox))
+        throw new EmailError("EMAIL_INVALID_INPUT");
+}
+export const EMAIL_SEARCH_FIELDS = ["from", "to", "subject", "unread", "flagged", "receivedAfter", "receivedBefore"];
+export function searchQuery(input) {
+    const mailbox = input.mailbox ?? "INBOX";
+    validateMailbox(mailbox);
+    const limit = input.limit ?? 20;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    if (input.sort !== undefined && !["newest", "oldest"].includes(input.sort))
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    for (const field of ["from", "to", "subject", "text"]) {
+        if (input[field] !== undefined && (typeof input[field] !== "string" || !input[field].length || input[field].length > 4096 || /[\x00-\x1f\x7f]/.test(input[field])))
+            throw new EmailError("EMAIL_INVALID_INPUT");
+    }
+    for (const field of ["unread", "flagged", "hasAttachments"]) {
+        if (input[field] !== undefined && typeof input[field] !== "boolean")
+            throw new EmailError("EMAIL_INVALID_INPUT");
+    }
+    for (const field of ["receivedAfter", "receivedBefore"]) {
+        const value = input[field];
+        if (value !== undefined) {
+            if (typeof value !== "string" || !/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,3})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.test(value) || !Number.isFinite(Date.parse(value)))
+                throw new EmailError("EMAIL_INVALID_INPUT");
+            const calendar = new Date(`${value.slice(0, 10)}T00:00:00Z`);
+            if (calendar.toISOString().slice(0, 10) !== value.slice(0, 10))
+                throw new EmailError("EMAIL_INVALID_INPUT");
+        }
+    }
+    if (input.receivedAfter && input.receivedBefore && Date.parse(input.receivedAfter) >= Date.parse(input.receivedBefore))
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    const unsupported = ["text", "hasAttachments"].filter(field => input[field] !== undefined);
+    if (unsupported.length)
+        throw new EmailError("EMAIL_SEARCH_UNSUPPORTED", false, unsupported);
+    const sort = input.sort ?? "newest";
+    const filters = { accountId: input.accountId };
+    for (const field of EMAIL_SEARCH_FIELDS) {
+        const value = input[field];
+        if (value !== undefined)
+            filters[field] = value;
+    }
+    const fingerprint = createHash("sha256").update(JSON.stringify({ mailbox, limit, sort, filters })).digest("hex");
+    return { mailbox, limit, sort, fingerprint, filters };
+}
+export function matchesSearch(summary, query) {
+    const input = query.filters;
+    if (input.from !== undefined && !summary.from.some(value => value.address.toLowerCase() === input.from.toLowerCase()))
+        return false;
+    if (input.to !== undefined && !summary.to.some(value => value.address.toLowerCase() === input.to.toLowerCase()))
+        return false;
+    if (input.subject !== undefined && !summary.subject?.toLowerCase().includes(input.subject.toLowerCase()))
+        return false;
+    if (input.unread !== undefined && summary.unread !== input.unread)
+        return false;
+    if (input.flagged !== undefined && summary.flagged !== input.flagged)
+        return false;
+    const received = Date.parse(summary.receivedAt);
+    return !(input.receivedAfter && received < Date.parse(input.receivedAfter)) && !(input.receivedBefore && received >= Date.parse(input.receivedBefore));
+}
+export function searchCursor(account, query, generation, high, last, key) {
+    const value = { query: query.fingerprint, scope: scopeId(account), accountId: account.accountId, generation, high, last };
+    const encoded = Buffer.from(JSON.stringify(value)).toString("base64url");
+    return `${encoded}.${createHmac("sha256", key).update(encoded).digest("base64url")}`;
+}
+export function decodeCursor(account, query, generation, cursor, key) {
+    if (cursor === undefined)
+        return;
+    try {
+        if (typeof cursor !== "string" || cursor.length > 2048 || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(cursor))
+            throw new Error();
+        const [encoded, signature] = cursor.split(".");
+        const actual = Buffer.from(signature, "base64url");
+        const expected = createHmac("sha256", key).update(encoded).digest();
+        if (actual.toString("base64url") !== signature || actual.length !== expected.length || !timingSafeEqual(actual, expected))
+            throw new Error();
+        const value = JSON.parse(Buffer.from(encoded, "base64url").toString());
+        if (value.accountId !== account.accountId || value.scope !== scopeId(account) || value.query !== query.fingerprint)
+            throw new Error();
+        if (!Number.isSafeInteger(value.high) || !Number.isSafeInteger(value.last) || value.last < 1 || value.last > value.high)
+            throw new Error();
+        if (value.generation !== generation)
+            throw new EmailError("EMAIL_STALE_REFERENCE");
+        return value;
+    }
+    catch (error) {
+        if (error instanceof EmailError)
+            throw error;
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    }
+}
+function addresses(value) {
+    const objects = value ? (Array.isArray(value) ? value : [value]) : [];
+    const result = objects.flatMap(object => object.value).filter(value => value.address).map(value => ({ address: value.address.slice(0, 320), ...(value.name ? { name: value.name.slice(0, 200) } : {}) }));
+    if (result.length > 100)
+        throw new EmailError("EMAIL_RESOURCE_LIMIT");
+    return result;
+}
+export async function parseMessage(account, mailbox, generation, record) {
+    if (record.source.length > EMAIL_SOURCE_LIMIT)
+        throw new EmailError("EMAIL_RESOURCE_LIMIT");
+    let parsed;
+    try {
+        parsed = await simpleParser(record.source, { skipHtmlToText: true, skipTextToHtml: true, skipImageLinks: true, maxHtmlLengthToParse: BODY_LIMIT });
+    }
+    catch {
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    }
+    const text = parsed.text ?? "";
+    const html = typeof parsed.html === "string" ? parsed.html : undefined;
+    if (Buffer.byteLength(text) > BODY_LIMIT || (html !== undefined && Buffer.byteLength(html) > BODY_LIMIT) || parsed.attachments.length > 100)
+        throw new EmailError("EMAIL_RESOURCE_LIMIT");
+    const references = parsed.references ? (Array.isArray(parsed.references) ? parsed.references : [parsed.references]) : [];
+    if (references.length > 100 || references.some(value => value.length > 998))
+        throw new EmailError("EMAIL_RESOURCE_LIMIT");
+    const autoSubmitted = parsed.headers.get("auto-submitted");
+    const precedence = parsed.headers.get("precedence");
+    const automated = (typeof autoSubmitted === "string" && autoSubmitted.trim().toLowerCase() !== "no")
+        || (typeof precedence === "string" && /^(bulk|list|junk)$/i.test(precedence.trim()));
+    return { ref: messageRef(account, mailbox, generation, record.uid),
+        ...(automated ? { automated: true } : {}),
+        ...(parsed.messageId ? { messageId: parsed.messageId.slice(0, 998) } : {}),
+        ...(parsed.inReplyTo ? { inReplyTo: parsed.inReplyTo.slice(0, 998) } : {}),
+        from: addresses(parsed.from), to: addresses(parsed.to), cc: addresses(parsed.cc), replyTo: addresses(parsed.replyTo),
+        ...(parsed.subject !== undefined ? { subject: parsed.subject.slice(0, 4096) } : {}),
+        receivedAt: record.receivedAt.toISOString(), unread: !record.flags.has("\\Seen"), flagged: record.flags.has("\\Flagged"),
+        hasAttachments: parsed.attachments.length > 0, preview: text.slice(0, 512), text, ...(html !== undefined ? { html } : {}), references,
+        attachments: parsed.attachments.map((value, index) => ({ id: String(index), ...(value.filename ? { filename: safeAttachmentFilename(value.filename) } : {}), contentType: value.contentType.replace(/[\x00-\x1f\x7f]/g, "").slice(0, 200), size: value.size })) };
+}
+export function summarize(message) {
+    const { cc: _cc, replyTo: _replyTo, text: _text, html: _html, inReplyTo: _inReplyTo, references: _references, attachments: _attachments, ...summary } = message;
+    return summary;
+}
+export function envelopeSummary(account, mailbox, generation, value) {
+    function safeAddresses(values = []) {
+        if (!Array.isArray(values))
+            return [];
+        if (values.length > 100)
+            throw new EmailError("EMAIL_RESOURCE_LIMIT");
+        return values.filter(value => value && typeof value.address === "string" && value.address).map(value => ({ address: value.address.slice(0, 320), ...(typeof value.name === "string" && value.name ? { name: value.name.slice(0, 200) } : {}) }));
+    }
+    return { ref: messageRef(account, mailbox, generation, value.uid), from: safeAddresses(value.envelope?.from), to: safeAddresses(value.envelope?.to),
+        ...(value.threadId ? { threadId: value.threadId.slice(0, 998) } : {}),
+        ...(value.envelope?.messageId ? { messageId: value.envelope.messageId.slice(0, 998) } : {}),
+        ...(typeof value.envelope?.subject === "string" ? { subject: value.envelope.subject.slice(0, 4096) } : {}),
+        receivedAt: value.internalDate instanceof Date && Number.isFinite(value.internalDate.getTime()) ? value.internalDate.toISOString() : new Date(0).toISOString(),
+        unread: !value.flags?.has("\\Seen"), flagged: value.flags?.has("\\Flagged") ?? false };
+}

package/dist/email/port.d.ts

@@ -0,0 +1,161 @@
+export type EmailErrorCode = "EMAIL_INVALID_INPUT" | "EMAIL_ACCOUNT_NOT_FOUND" | "EMAIL_ACCOUNT_DISABLED" | "EMAIL_UNAUTHORIZED" | "EMAIL_AUTH_FAILED" | "EMAIL_TOKEN_EXPIRED" | "EMAIL_CONNECTION_FAILED" | "EMAIL_TIMEOUT" | "EMAIL_RATE_LIMIT" | "EMAIL_MESSAGE_NOT_FOUND" | "EMAIL_STALE_REFERENCE" | "EMAIL_UNSUPPORTED" | "EMAIL_SEARCH_UNSUPPORTED" | "EMAIL_RESOURCE_LIMIT" | "EMAIL_SEND_OUTCOME_UNKNOWN" | "EMAIL_OPERATION_CONFLICT" | "EMAIL_RECIPIENTS_REJECTED" | "EMAIL_EVENT_ACCEPTANCE_FAILED" | "EMAIL_STORAGE_FAILED" | "EMAIL_TRIGGER_TARGET_INVALID";
+export declare class EmailError extends Error {
+    readonly code: EmailErrorCode;
+    readonly retryable: boolean;
+    readonly unsupportedFields?: string[] | undefined;
+    constructor(code: EmailErrorCode, retryable?: boolean, unsupportedFields?: string[] | undefined);
+}
+export type EmailAddress = {
+    address: string;
+    name?: string;
+};
+export type EmailMessageRef = {
+    accountId: string;
+    id: string;
+    mailbox?: string;
+};
+export type EmailAttachment = {
+    id: string;
+    filename?: string;
+    contentType: string;
+    size: number;
+};
+/** Host authority. Never deserialize this value from a worker request. */
+export type EmailArtifactContext = {
+    workspaceDir: string;
+    stageId: string;
+    attempt: number;
+};
+export type DownloadEmailAttachmentInput = {
+    ref: EmailMessageRef;
+    attachmentId: string;
+};
+export type DownloadEmailAttachmentResult = EmailAttachment & {
+    artifact: string;
+};
+export type PreparedEmailAttachment = {
+    filename: string;
+    content: Buffer;
+};
+export type EmailMessageSummary = {
+    ref: EmailMessageRef;
+    messageId?: string;
+    threadId?: string;
+    from: EmailAddress[];
+    to: EmailAddress[];
+    subject?: string;
+    receivedAt: string;
+    unread: boolean;
+    flagged: boolean;
+    hasAttachments?: boolean;
+    preview?: string;
+    automated?: boolean;
+};
+export type EmailMessage = EmailMessageSummary & {
+    cc: EmailAddress[];
+    replyTo: EmailAddress[];
+    text: string;
+    html?: string;
+    inReplyTo?: string;
+    references: string[];
+    attachments: EmailAttachment[];
+};
+export type SendEmailInput = {
+    accountId: string;
+    operationKey: string;
+    from?: string;
+    to: EmailAddress[];
+    cc?: EmailAddress[];
+    bcc?: EmailAddress[];
+    subject: string;
+    text: string;
+    html?: string;
+    inReplyTo?: string;
+    references?: string[];
+    attachments?: {
+        artifact: string;
+        filename?: string;
+    }[];
+};
+export type ReplyToEmailInput = {
+    ref: EmailMessageRef;
+    operationKey: string;
+    from?: string;
+    text: string;
+    html?: string;
+    replyAll?: boolean;
+    attachments?: SendEmailInput["attachments"];
+};
+export type SendEmailResult = {
+    operationId: string;
+    messageId?: string;
+    accepted: string[];
+    rejected: string[];
+    submittedAt: string;
+    warnings?: string[];
+    sentCopy?: {
+        state: "pending" | "completed" | "failed" | "unknown";
+        error?: EmailErrorCode;
+    };
+};
+export type SearchEmailsInput = {
+    accountId: string;
+    mailbox?: string;
+    text?: string;
+    from?: string;
+    to?: string;
+    subject?: string;
+    unread?: boolean;
+    flagged?: boolean;
+    hasAttachments?: boolean;
+    receivedAfter?: string;
+    receivedBefore?: string;
+    limit?: number;
+    cursor?: string;
+    sort?: "newest" | "oldest";
+};
+export type SearchEmailsResult = {
+    messages: EmailMessageSummary[];
+    nextCursor?: string;
+};
+export type EmailConnectionStatus = {
+    state: "ok" | "failed";
+    error?: {
+        code: EmailErrorCode;
+        retryable: boolean;
+    };
+};
+export type EmailAccountStatus = {
+    accountId: string;
+    checkedAt: string;
+    imap?: EmailConnectionStatus;
+    smtp?: EmailConnectionStatus;
+    capabilities: {
+        operations: string[];
+        searchFields: string[];
+        idle: boolean;
+    };
+};
+export type EmailReceivedEvent = {
+    type: "email.received";
+    version: 1;
+    eventId: string;
+    accountId: string;
+    message: EmailMessageSummary;
+    receivedAt: string;
+    detectedAt: string;
+};
+export interface EmailMailbox {
+    /** Host-only historical event retrieval. Validates current provider identity without changing watcher progress. */
+    getReceivedEvent?(ref: EmailMessageRef): Promise<EmailReceivedEvent>;
+    testAccount(accountId: string, protocol?: "imap" | "smtp" | "both"): Promise<EmailAccountStatus>;
+    send(input: SendEmailInput, context?: EmailArtifactContext): Promise<SendEmailResult>;
+    reply(input: ReplyToEmailInput, context?: EmailArtifactContext): Promise<SendEmailResult>;
+    downloadAttachment(input: DownloadEmailAttachmentInput, context?: EmailArtifactContext): Promise<DownloadEmailAttachmentResult>;
+    getMessage(ref: EmailMessageRef): Promise<EmailMessage>;
+    search(input: SearchEmailsInput): Promise<SearchEmailsResult>;
+}
+export interface EmailEventSource {
+    start(emit: (event: EmailReceivedEvent) => Promise<void>): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/email/port.js

@@ -0,0 +1,12 @@
+export class EmailError extends Error {
+    code;
+    retryable;
+    unsupportedFields;
+    constructor(code, retryable = false, unsupportedFields) {
+        super(code);
+        this.code = code;
+        this.retryable = retryable;
+        this.unsupportedFields = unsupportedFields;
+        this.name = "EmailError";
+    }
+}

package/dist/email/replies.d.ts

@@ -0,0 +1,5 @@
+import type { EmailAccount } from "./accounts.js";
+import { type EmailMessage, type ReplyToEmailInput, type SendEmailInput } from "./port.js";
+export declare function validateReply(input: unknown): ReplyToEmailInput;
+/** Only normalized source data can supply recipients and conversation headers. */
+export declare function replyMessage(account: EmailAccount, original: EmailMessage, input: ReplyToEmailInput): SendEmailInput;

package/dist/email/replies.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { EmailError } from "./port.js";
+import { messageIdSchema } from "./submissions.js";
+import { attachmentReferencesSchema } from "./attachments.js";
+const replySchema = z.object({
+    ref: z.object({ accountId: z.string().min(1), id: z.string().min(1).max(2048), mailbox: z.string().max(200).optional() }).strict(),
+    operationKey: z.string().min(1).max(200), from: z.email().optional(),
+    text: z.string().max(262144), html: z.string().max(262144).optional(), replyAll: z.boolean().default(false),
+    attachments: attachmentReferencesSchema.optional(),
+}).strict();
+export function validateReply(input) {
+    const parsed = replySchema.safeParse(input);
+    if (!parsed.success)
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    return parsed.data;
+}
+/** Only normalized source data can supply recipients and conversation headers. */
+export function replyMessage(account, original, input) {
+    if (original.automated)
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    function usable(values) {
+        return values.filter(value => z.email().safeParse(value.address).success).map(value => ({
+            address: value.address,
+            ...(value.name ? { name: value.name.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 200) } : {}),
+        }));
+    }
+    const replyTo = usable(original.replyTo);
+    const sender = replyTo.length ? replyTo : usable(original.from);
+    const seen = new Set([account.address, ...account.senderAliases].map(value => value.toLowerCase()));
+    function unique(values) {
+        return values.filter(value => {
+            const key = value.address.toLowerCase();
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+    }
+    const to = unique(input.replyAll ? [...sender, ...usable(original.to)] : sender);
+    const cc = input.replyAll ? unique(usable(original.cc)) : [];
+    if (!to.length && !cc.length)
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    const messageId = messageIdSchema.safeParse(original.messageId).success ? original.messageId : undefined;
+    const priorId = messageIdSchema.safeParse(original.inReplyTo).success ? original.inReplyTo : undefined;
+    const references = [...new Set(original.references.filter(value => messageIdSchema.safeParse(value).success))];
+    if (!references.length && priorId)
+        references.push(priorId);
+    if (messageId && !references.includes(messageId))
+        references.push(messageId);
+    if (references.length > 100 || references.join(" ").length > 8192)
+        throw new EmailError("EMAIL_RESOURCE_LIMIT");
+    const subject = (original.subject ?? "").replace(/[\x00-\x1f\x7f]/g, " ").replace(/^(?:\s*re\s*:\s*)+/i, "").trim().slice(0, 994);
+    return { accountId: account.accountId, operationKey: input.operationKey, from: input.from, to, cc,
+        subject: subject ? `Re: ${subject}` : "Re:", text: input.text, html: input.html, attachments: input.attachments,
+        ...(messageId ? { inReplyTo: messageId } : {}), ...(references.length ? { references } : {}) };
+}

package/dist/email/submissions.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import type { EmailAccount } from "./accounts.js";
+import { type SendEmailInput, type SendEmailResult, type EmailErrorCode } from "./port.js";
+export declare const messageIdSchema: z.ZodString;
+export declare function validateSend(input: unknown, account: EmailAccount): SendEmailInput;
+export type SubmissionRecord = {
+    operationId: string;
+    accountId: string;
+    operationKey: string;
+    hash: string;
+    state: "pending" | "submitted" | "failed" | "unknown";
+    createdAt: string;
+    receipt?: SendEmailResult;
+    error?: {
+        code: EmailErrorCode;
+        retryable: boolean;
+    };
+};
+/** The host is the single writer. Pending records survive crashes as uncertain outcomes. */
+export declare class EmailSubmissions {
+    private readonly file;
+    private records;
+    private readonly active;
+    private accepting;
+    constructor(scope: string);
+    list(): SubmissionRecord[];
+    drain(): Promise<void>;
+    setAccepting(accepting: boolean): void;
+    send(input: SendEmailInput, submit: (operationId: string, accepted: (receipt: SendEmailResult) => void) => Promise<SendEmailResult>, identity?: unknown): Promise<SendEmailResult>;
+    private persist;
+}