stageflow 0.31.0 → 0.32.0

package/dist/email/submissions.js

@@ -0,0 +1,123 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { attachmentReferencesSchema } from "./attachments.js";
+import { EmailError } from "./port.js";
+const address = z.object({ address: z.email(), name: z.string().max(200).regex(/^[^\r\n]*$/).optional() }).strict();
+export const messageIdSchema = z.string().max(998).regex(/^[\x21-\x7e]+$/).regex(/^<[^<>\s@]+@[^<>\s@]+>$/);
+const sendSchema = z.object({
+    accountId: z.string().min(1), operationKey: z.string().min(1).max(200),
+    from: z.email().optional(), to: z.array(address).max(100), cc: z.array(address).max(100).default([]),
+    bcc: z.array(address).max(100).default([]), subject: z.string().max(998).regex(/^[^\r\n]*$/),
+    text: z.string().max(262144), html: z.string().max(262144).optional(),
+    inReplyTo: messageIdSchema.optional(), references: z.array(messageIdSchema).max(100).refine(values => values.join(" ").length <= 8192).optional(),
+    attachments: attachmentReferencesSchema.optional(),
+}).strict().refine(input => input.to.length + input.cc.length + input.bcc.length > 0);
+export function validateSend(input, account) {
+    const parsed = sendSchema.safeParse(input);
+    if (!parsed.success)
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    const from = parsed.data.from ?? account.address;
+    if (![account.address, ...account.senderAliases].some(value => value.toLowerCase() === from.toLowerCase())) {
+        throw new EmailError("EMAIL_UNAUTHORIZED");
+    }
+    return { ...parsed.data, from };
+}
+/** The host is the single writer. Pending records survive crashes as uncertain outcomes. */
+export class EmailSubmissions {
+    file;
+    records;
+    active = new Map();
+    accepting = true;
+    constructor(scope) {
+        this.file = path.join(scope, ".stageflow", "email-submissions.json");
+        this.records = existsSync(this.file) ? JSON.parse(readFileSync(this.file, "utf8")) : [];
+        for (const record of this.records)
+            if (record.state === "pending")
+                record.state = "unknown";
+        for (const record of this.records)
+            if (record.receipt?.sentCopy?.state === "pending") {
+                record.receipt.sentCopy = { state: "unknown" };
+                record.receipt.warnings = ["EMAIL_SENT_COPY_OUTCOME_UNKNOWN"];
+            }
+    }
+    list() { return structuredClone(this.records); }
+    async drain() { await Promise.allSettled(this.active.values()); }
+    setAccepting(accepting) { this.accepting = accepting; }
+    async send(input, submit, identity) {
+        if (!this.accepting)
+            throw new EmailError("EMAIL_CONNECTION_FAILED", true);
+        const hash = createHash("sha256").update(JSON.stringify(identity === undefined ? input : { input, identity })).digest("hex");
+        const key = `${input.accountId}\0${input.operationKey}`;
+        const found = this.records.find(record => record.accountId === input.accountId && record.operationKey === input.operationKey);
+        if (found) {
+            if (found.hash !== hash)
+                throw new EmailError("EMAIL_OPERATION_CONFLICT");
+            const active = this.active.get(key);
+            if (active)
+                return active;
+            if (found.receipt)
+                return structuredClone(found.receipt);
+            if (found.state === "failed" && found.error)
+                throw new EmailError(found.error.code, found.error.retryable);
+            throw new EmailError("EMAIL_SEND_OUTCOME_UNKNOWN");
+        }
+        // Completed records expire after 30 days; unresolved records are never evicted.
+        const cutoff = Date.now() - 30 * 86400000;
+        this.records = this.records.filter(record => !["submitted", "failed"].includes(record.state)
+            || ["pending", "unknown"].includes(record.receipt?.sentCopy?.state ?? "") || Date.parse(record.createdAt) >= cutoff);
+        if (this.records.length >= 10000)
+            throw new EmailError("EMAIL_RESOURCE_LIMIT");
+        const record = { operationId: randomUUID(), accountId: input.accountId,
+            operationKey: input.operationKey, hash, state: "pending", createdAt: new Date().toISOString() };
+        this.records.push(record);
+        this.persist();
+        let checkpointed = false;
+        const work = Promise.resolve().then(() => submit(record.operationId, receipt => {
+            checkpointed = true;
+            record.state = "submitted";
+            record.receipt = structuredClone(receipt);
+            this.persist();
+        })).then(receipt => {
+            record.state = "submitted";
+            record.receipt = receipt;
+            this.persist();
+            return structuredClone(receipt);
+        }).catch(error => {
+            if (checkpointed && record.receipt) {
+                if (record.receipt.sentCopy?.state === "pending") {
+                    record.receipt.sentCopy = { state: "unknown", error: "EMAIL_STORAGE_FAILED" };
+                    record.receipt.warnings = ["EMAIL_SENT_COPY_OUTCOME_UNKNOWN"];
+                }
+                record.receipt.warnings = [...record.receipt.warnings ?? [], "EMAIL_STORAGE_FAILED"];
+                try {
+                    this.persist();
+                }
+                catch { /* The durable pending record still forbids resubmission. */ }
+                return structuredClone(record.receipt);
+            }
+            const fault = error instanceof EmailError ? error : new EmailError("EMAIL_SEND_OUTCOME_UNKNOWN");
+            record.state = fault.code === "EMAIL_SEND_OUTCOME_UNKNOWN" ? "unknown" : "failed";
+            record.error = { code: fault.code, retryable: fault.retryable };
+            delete record.receipt;
+            try {
+                this.persist();
+            }
+            catch {
+                // The previously durable pending record is sufficient to forbid resubmission.
+                record.state = "unknown";
+                throw new EmailError("EMAIL_SEND_OUTCOME_UNKNOWN");
+            }
+            throw fault;
+        }).finally(() => { this.active.delete(key); });
+        this.active.set(key, work);
+        return work;
+    }
+    persist() {
+        mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 });
+        const temporary = `${this.file}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, JSON.stringify(this.records), { mode: 0o600 });
+        renameSync(temporary, this.file);
+    }
+}

package/dist/email/triggers.d.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import type { RunStore } from "../runstore/port.js";
+import type { RunManager } from "../runtime/runManager.js";
+import type { EmailAccounts } from "./accounts.js";
+import { type EmailMailbox, type EmailReceivedEvent, type EmailMessageRef } from "./port.js";
+export type EmailReplayOutcome = {
+    ref: EmailMessageRef;
+    status: "matched" | "skipped" | "alreadyHandled" | "pending" | "started" | "failed";
+    code?: string;
+    dispatchKey?: string;
+    runId?: string;
+};
+export type EmailReplayResult = {
+    selected: number;
+    matched: number;
+    skipped: number;
+    alreadyHandled: number;
+    pending: number;
+    failed: number;
+    started: number;
+    outcomes: EmailReplayOutcome[];
+    refs: EmailMessageRef[];
+    ruleVersion: number;
+    nextCursor?: string;
+};
+declare const ruleInput: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    accountId: z.ZodString;
+    folder: z.ZodDefault<z.ZodString>;
+    from: z.ZodOptional<z.ZodEmail>;
+    subjectContains: z.ZodOptional<z.ZodString>;
+    pipeline: z.ZodString;
+    task: z.ZodObject<{
+        id: z.ZodString;
+        goal: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+        constraints: z.ZodOptional<z.ZodString>;
+        checkout: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    includeBody: z.ZodDefault<z.ZodBoolean>;
+    bodyLimit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type EmailTriggerRule = z.output<typeof ruleInput> & {
+    triggerId: string;
+    version: number;
+    activeAfter: string;
+};
+export type EmailDispatch = {
+    dispatchKey: string;
+    eventId: string;
+    triggerId: string;
+    ruleVersion: number;
+    accountId: string;
+    status: "pending" | "started" | "failed" | "suspended";
+    runId?: string;
+    code?: string;
+    attempts?: number;
+    retryAt?: string;
+    completedAt?: string;
+};
+declare const queueInput: z.ZodObject<{
+    maxPending: z.ZodDefault<z.ZodNumber>;
+    workers: z.ZodDefault<z.ZodNumber>;
+    batchSize: z.ZodDefault<z.ZodNumber>;
+    intervalMs: z.ZodDefault<z.ZodNumber>;
+    retryMaxMs: z.ZodDefault<z.ZodNumber>;
+    retentionMs: z.ZodDefault<z.ZodNumber>;
+    maxCompleted: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+type Options = {
+    cwd: string;
+    accounts: EmailAccounts;
+    mailbox: EmailMailbox;
+    manager: RunManager;
+    store: RunStore;
+    now?: () => Date;
+    queue?: z.input<typeof queueInput>;
+    /** Fault injection at the durable dispatch seam. */
+    checkpoint?: (point: "beforeRun" | "afterRun", dispatch: EmailDispatch) => Promise<void>;
+};
+/** Durable rule evaluation and dispatch above the normal run execution path. */
+export declare class EmailTriggers {
+    private readonly options;
+    private readonly db;
+    private readonly now;
+    private readonly queue;
+    private readonly active;
+    private readonly activeFolders;
+    private timer?;
+    private nextBatchAt;
+    private lastFolder?;
+    private stopPromise?;
+    private faultCode?;
+    private readonly suspensions;
+    private stopped;
+    private closed;
+    private readonly unsubscribe;
+    constructor(options: Options);
+    list(): EmailTriggerRule[];
+    get(triggerId: string): EmailTriggerRule;
+    create(input: unknown): Promise<EmailTriggerRule>;
+    update(triggerId: string, patch: unknown): Promise<EmailTriggerRule>;
+    remove(triggerId: string): void;
+    history(): EmailDispatch[];
+    health(): {
+        pending?: number;
+        suspended?: number;
+        active: number;
+        saturated?: boolean;
+        code?: string;
+    };
+    accept(event: EmailReceivedEvent): Promise<void>;
+    /** Preview one search page, or admit an exact selection through the normal queue. */
+    replay(input: unknown, execute?: boolean): Promise<EmailReplayResult>;
+    private dispatchKey;
+    private hasDispatch;
+    /** Run one due batch. The timer continues recovery without waiting for runs to finish. */
+    recover(): Promise<void>;
+    stop(): Promise<void>;
+    resume(dispatchKey: string): EmailDispatch;
+    cancel(dispatchKey: string): void;
+    cleanup(): void;
+    private schedule;
+    private pump;
+    private attempt;
+    private isPending;
+    private accountRevision;
+    private saveOutcome;
+    private saveStarted;
+    private assertOpen;
+    private assertAccepting;
+    private validate;
+    private saveRule;
+    private save;
+    private records;
+    private suspendObsolete;
+    private suspendAccount;
+    private dispatch;
+}
+export {};