@intx/mail-memory 0.1.2 → 0.3.0

package/dist/search.js

@@ -0,0 +1,151 @@
+import { parseHeaderSection } from "@intx/mime";
+/**
+ * Execute an IMAP SEARCH-equivalent query over an in-memory mailbox.
+ *
+ * Supports: from, to, cc, bcc, header (field match), before/after/on,
+ * sentBefore/sentAfter/sentOn, hasFlags, missingFlags, body, text,
+ * largerThan, smallerThan, and boolean and/or/not composition.
+ *
+ * Returns MessageRef[] for all matching messages, ordered by UID.
+ */
+export function executeSearch(mailboxName, store, query) {
+    const results = [];
+    for (const msg of store.messages) {
+        if (matchMessage(msg, query)) {
+            results.push({ uid: msg.uid, mailbox: mailboxName });
+        }
+    }
+    return results;
+}
+function matchMessage(msg, query) {
+    if (query.from !== undefined) {
+        if (!msg.envelope.from.toLowerCase().includes(query.from.toLowerCase())) {
+            return false;
+        }
+    }
+    if (query.to !== undefined) {
+        const queryTo = query.to;
+        const toMatch = msg.envelope.to.some((addr) => addr.toLowerCase().includes(queryTo.toLowerCase()));
+        if (!toMatch)
+            return false;
+    }
+    if (query.cc !== undefined) {
+        const headers = lazyHeaders(msg);
+        const ccHeader = headers.get("cc") ?? "";
+        if (!ccHeader.toLowerCase().includes(query.cc.toLowerCase())) {
+            return false;
+        }
+    }
+    if (query.bcc !== undefined) {
+        const headers = lazyHeaders(msg);
+        const bccHeader = headers.get("bcc") ?? "";
+        if (!bccHeader.toLowerCase().includes(query.bcc.toLowerCase())) {
+            return false;
+        }
+    }
+    if (query.header !== undefined) {
+        const { field, contains } = query.header;
+        const headers = lazyHeaders(msg);
+        const value = headers.get(field.toLowerCase()) ?? "";
+        if (!value.toLowerCase().includes(contains.toLowerCase())) {
+            return false;
+        }
+    }
+    if (query.before !== undefined) {
+        if (msg.envelope.date >= query.before)
+            return false;
+    }
+    if (query.after !== undefined) {
+        if (msg.envelope.date <= query.after)
+            return false;
+    }
+    if (query.on !== undefined) {
+        const d = msg.envelope.date;
+        const q = query.on;
+        if (d.getUTCFullYear() !== q.getUTCFullYear() ||
+            d.getUTCMonth() !== q.getUTCMonth() ||
+            d.getUTCDate() !== q.getUTCDate()) {
+            return false;
+        }
+    }
+    // Sent date filters use the Date header (same as envelope date here).
+    if (query.sentBefore !== undefined) {
+        if (msg.envelope.date >= query.sentBefore)
+            return false;
+    }
+    if (query.sentAfter !== undefined) {
+        if (msg.envelope.date <= query.sentAfter)
+            return false;
+    }
+    if (query.sentOn !== undefined) {
+        const d = msg.envelope.date;
+        const q = query.sentOn;
+        if (d.getUTCFullYear() !== q.getUTCFullYear() ||
+            d.getUTCMonth() !== q.getUTCMonth() ||
+            d.getUTCDate() !== q.getUTCDate()) {
+            return false;
+        }
+    }
+    if (query.hasFlags !== undefined) {
+        for (const flag of query.hasFlags) {
+            if (!msg.flags.has(flag))
+                return false;
+        }
+    }
+    if (query.missingFlags !== undefined) {
+        for (const flag of query.missingFlags) {
+            if (msg.flags.has(flag))
+                return false;
+        }
+    }
+    if (query.largerThan !== undefined) {
+        if (msg.raw.length <= query.largerThan)
+            return false;
+    }
+    if (query.smallerThan !== undefined) {
+        if (msg.raw.length >= query.smallerThan)
+            return false;
+    }
+    if (query.body !== undefined || query.text !== undefined) {
+        const rawText = new TextDecoder("utf-8", { fatal: false }).decode(msg.raw);
+        if (query.body !== undefined) {
+            const { bodyOffset } = parseHeaderSection(msg.raw);
+            const bodyText = new TextDecoder("utf-8", { fatal: false }).decode(msg.raw.slice(bodyOffset));
+            if (!bodyText.toLowerCase().includes(query.body.toLowerCase())) {
+                return false;
+            }
+        }
+        if (query.text !== undefined) {
+            if (!rawText.toLowerCase().includes(query.text.toLowerCase())) {
+                return false;
+            }
+        }
+    }
+    if (query.and !== undefined) {
+        for (const sub of query.and) {
+            if (!matchMessage(msg, sub))
+                return false;
+        }
+    }
+    if (query.or !== undefined) {
+        if (query.or.length > 0) {
+            const anyMatch = query.or.some((sub) => matchMessage(msg, sub));
+            if (!anyMatch)
+                return false;
+        }
+    }
+    if (query.not !== undefined) {
+        if (matchMessage(msg, query.not))
+            return false;
+    }
+    return true;
+}
+const headerCache = new WeakMap();
+function lazyHeaders(msg) {
+    const cached = headerCache.get(msg);
+    if (cached !== undefined)
+        return cached;
+    const { headers } = parseHeaderSection(msg.raw);
+    headerCache.set(msg, headers);
+    return headers;
+}

package/dist/send.d.ts

@@ -0,0 +1,52 @@
+import type { OutboundMessage, SendReceipt } from "@intx/types/runtime";
+import type { AddressEntry } from "./mailbox.js";
+/**
+ * Callback for delivering messages to recipients not registered on this
+ * transport. The federation layer provides this to forward messages to
+ * the hub for remote routing.
+ */
+export type RemoteSendHandler = (rawMessage: Uint8Array, recipients: string[]) => Promise<void>;
+/**
+ * Context passed to MessageSentHandler callbacks after a message is fully
+ * assembled and delivered.
+ */
+export type MessageSentContext = {
+    senderAddress: string;
+    rawMessage: Uint8Array;
+    messageId: string;
+    /** Deduplicated union of to and cc — the full routing set. */
+    recipients: string[];
+    /** To addresses only (before merging with cc). */
+    to: string[];
+    /** CC addresses only. Empty array when no CC recipients. */
+    cc: string[];
+    /** True when all recipients were delivered locally (no remote leg). */
+    localOnly: boolean;
+};
+/**
+ * Callback fired after a message is fully assembled and delivered. The
+ * send is already complete when this fires — a handler rejection does
+ * not mean the message was not delivered.
+ *
+ * Used by the sidecar to commit outbound wire messages to the git audit
+ * trail and forward metadata to the hub.
+ */
+export type MessageSentHandler = (ctx: MessageSentContext) => Promise<void>;
+/**
+ * Execute the send() flow:
+ * 1. Validate sender registration, split recipients into local/remote
+ * 2. Build signed content part (MIME bytes to sign)
+ * 3. Sign with sender's CryptoProvider
+ * 4. Assemble the complete RFC 2822 message
+ * 5. Append to each local recipient's INBOX and sender's Sent mailbox
+ * 6. Forward to remote recipients via onRemoteSend
+ * 7. Schedule watch callbacks asynchronously via queueMicrotask
+ * 8. Fire onMessageSent callback (fire-and-forget)
+ *
+ * If onRemoteSend is not provided and there are remote recipients, send()
+ * throws. If onRemoteSend rejects, the error propagates — local delivery
+ * that already completed is not rolled back. This is a known limitation:
+ * partial delivery is possible when a message has both local and remote
+ * recipients and the remote leg fails.
+ */
+export declare function executeSend(senderAddress: string, message: OutboundMessage, entries: Map<string, AddressEntry>, onRemoteSend?: RemoteSendHandler, onMessageSent?: MessageSentHandler): Promise<SendReceipt>;

package/dist/send.js

@@ -0,0 +1,191 @@
+import { appendToMailbox } from "./mailbox.js";
+import { assembleSignedContent, assembleMessage, generateMessageId, parseHeaderSection, createDetachedSignatureFromProvider, } from "@intx/mime";
+import { buildMessageHeaders } from "./headers.js";
+const CONVERSATION_TYPES = new Set([
+    "conversation.message",
+    "conversation.join",
+    "conversation.leave",
+]);
+/**
+ * Execute the send() flow:
+ * 1. Validate sender registration, split recipients into local/remote
+ * 2. Build signed content part (MIME bytes to sign)
+ * 3. Sign with sender's CryptoProvider
+ * 4. Assemble the complete RFC 2822 message
+ * 5. Append to each local recipient's INBOX and sender's Sent mailbox
+ * 6. Forward to remote recipients via onRemoteSend
+ * 7. Schedule watch callbacks asynchronously via queueMicrotask
+ * 8. Fire onMessageSent callback (fire-and-forget)
+ *
+ * If onRemoteSend is not provided and there are remote recipients, send()
+ * throws. If onRemoteSend rejects, the error propagates — local delivery
+ * that already completed is not rolled back. This is a known limitation:
+ * partial delivery is possible when a message has both local and remote
+ * recipients and the remote leg fails.
+ */
+export async function executeSend(senderAddress, message, entries, onRemoteSend, onMessageSent) {
+    const senderEntry = entries.get(senderAddress);
+    if (senderEntry === undefined) {
+        throw new Error(`Sender "${senderAddress}" is not registered with this transport`);
+    }
+    const senderCrypto = senderEntry.crypto;
+    const recipients = Array.isArray(message.to) ? message.to : [message.to];
+    if (recipients.length === 0) {
+        throw new Error("OutboundMessage must have at least one recipient");
+    }
+    const ccAddressList = message.cc !== undefined
+        ? Array.isArray(message.cc)
+            ? message.cc
+            : [message.cc]
+        : [];
+    const allAddressees = [...new Set([...recipients, ...ccAddressList])];
+    const remoteRecipients = allAddressees.filter((addr) => !entries.has(addr));
+    if (remoteRecipients.length > 0 && onRemoteSend === undefined) {
+        throw new Error(`Recipient "${remoteRecipients[0]}" is not registered with this transport`);
+    }
+    const isConversation = CONVERSATION_TYPES.has(message.type);
+    if (isConversation && message.payload !== undefined) {
+        throw new Error("Conversation messages must not carry a structured payload");
+    }
+    if (!isConversation && message.content !== undefined) {
+        throw new Error("Structured messages must not carry a text content field");
+    }
+    const messageId = generateMessageId(senderAddress);
+    const now = new Date();
+    let content;
+    if (isConversation) {
+        content = {
+            kind: "conversation",
+            text: message.content ?? "",
+        };
+    }
+    else {
+        const payload = message.payload ?? {};
+        const envelope = {
+            type: message.type,
+            version: "1",
+            body: payload,
+        };
+        const structured = {
+            kind: "structured",
+            json: envelope,
+        };
+        if (message.summary !== undefined)
+            structured.summary = message.summary;
+        content = structured;
+    }
+    const signedContentBytes = assembleSignedContent(content);
+    const signatureBytes = await createDetachedSignatureFromProvider(signedContentBytes, senderCrypto);
+    const ccAddresses = ccAddressList.length > 0 ? ccAddressList : undefined;
+    const refs = buildReferences(message.inReplyTo, undefined);
+    const mimeHeaders = {
+        from: senderAddress,
+        to: recipients,
+        cc: ccAddresses,
+        date: now,
+        messageId,
+        subject: message.subject,
+        inReplyTo: message.inReplyTo,
+        references: refs,
+        mimeVersion: "1.0",
+        interchangeType: message.type,
+        interchangeCorrelationId: message.correlationId,
+        interchangeTenantId: message.tenantId,
+        interchangeAgentId: undefined,
+        interchangeSessionId: message.sessionId,
+        interchangeOfferingId: undefined,
+        interchangeSchemaVersion: undefined,
+        traceparent: undefined,
+        tracestate: undefined,
+    };
+    const rawBytes = assembleMessage(mimeHeaders, signedContentBytes, signatureBytes);
+    const envelope = {
+        messageId,
+        from: senderAddress,
+        to: recipients,
+        subject: message.subject ?? "",
+        date: now,
+        inReplyTo: message.inReplyTo,
+        references: refs ?? [],
+        interchangeType: message.type,
+        interchangeCorrelationId: message.correlationId,
+    };
+    // Deliver to each local recipient's INBOX.
+    const deliveredUids = [];
+    for (const recipient of allAddressees) {
+        const entry = entries.get(recipient);
+        if (entry === undefined)
+            continue;
+        const inbox = entry.mailboxes.get("INBOX");
+        if (inbox === undefined) {
+            throw new Error(`Mailbox "INBOX" does not exist for recipient "${recipient}"`);
+        }
+        const uid = appendToMailbox(inbox, rawBytes, envelope, []);
+        deliveredUids.push({ address: recipient, uid });
+    }
+    // Append copy to sender's Sent mailbox.
+    const sentStore = senderEntry.mailboxes.get("Sent");
+    if (sentStore === undefined) {
+        throw new Error(`Mailbox "Sent" does not exist for sender "${senderAddress}"`);
+    }
+    appendToMailbox(sentStore, rawBytes, envelope, ["\\Seen"]);
+    // Fire local recipient watch callbacks ASYNCHRONOUSLY (per MESSAGE.md
+    // requirement). queueMicrotask ensures callbacks never run synchronously
+    // on the sender's call stack, preserving real IMAP IDLE async delivery
+    // semantics. Scheduled before the remote send so local delivery
+    // notifications are not delayed by network latency.
+    const { headers: parsedHeaders } = parseHeaderSection(rawBytes);
+    const msgHeaders = buildMessageHeaders(parsedHeaders);
+    for (const { address, uid } of deliveredUids) {
+        const entry = entries.get(address);
+        if (entry === undefined) {
+            throw new Error(`Entry for "${address}" disappeared between delivery and callback dispatch`);
+        }
+        const callbacks = entry.watchCallbacks.get("INBOX");
+        if (callbacks === undefined || callbacks.size === 0)
+            continue;
+        const event = {
+            type: "exists",
+            uid,
+            headers: msgHeaders,
+        };
+        for (const cb of callbacks) {
+            queueMicrotask(() => cb(event));
+        }
+    }
+    // Forward to remote recipients via federation hook.
+    if (remoteRecipients.length > 0 && onRemoteSend !== undefined) {
+        await onRemoteSend(rawBytes, remoteRecipients);
+    }
+    if (onMessageSent !== undefined) {
+        const localOnly = remoteRecipients.length === 0;
+        onMessageSent({
+            senderAddress,
+            rawMessage: rawBytes,
+            messageId,
+            recipients: allAddressees,
+            to: recipients,
+            cc: ccAddressList,
+            localOnly,
+        }).catch((err) => {
+            queueMicrotask(() => {
+                throw err instanceof Error
+                    ? err
+                    : new Error(`MessageSentHandler failed: ${String(err)}`);
+            });
+        });
+    }
+    return {
+        messageId,
+        status: remoteRecipients.length > 0 ? "queued" : "delivered",
+    };
+}
+function buildReferences(inReplyTo, existingReferences) {
+    if (inReplyTo === undefined)
+        return existingReferences;
+    const refs = existingReferences ?? [];
+    if (!refs.includes(inReplyTo)) {
+        return [...refs, inReplyTo];
+    }
+    return refs;
+}

package/dist/thread.d.ts

@@ -0,0 +1,3 @@
+import type { Thread, SearchQuery } from "@intx/types/runtime";
+import type { MailboxStore } from "./mailbox.js";
+export declare function executeThread(mailboxName: string, store: MailboxStore, algorithm: "references" | "orderedsubject", query?: SearchQuery): Thread[];

package/dist/thread.js

@@ -0,0 +1,204 @@
+import { executeSearch } from "./search.js";
+export function executeThread(mailboxName, store, algorithm, query) {
+    let messages;
+    if (query !== undefined) {
+        const refs = executeSearch(mailboxName, store, query);
+        const uidSet = new Set(refs.map((r) => r.uid));
+        messages = store.messages.filter((m) => uidSet.has(m.uid));
+    }
+    else {
+        messages = [...store.messages];
+    }
+    if (messages.length === 0)
+        return [];
+    if (algorithm === "orderedsubject") {
+        return orderedSubjectThread(mailboxName, messages);
+    }
+    return referencesThread(mailboxName, messages);
+}
+/**
+ * RFC 5256 ORDEREDSUBJECT: sort by base subject, then date.
+ * All messages with the same base subject form one thread; the first by date
+ * is the root, the rest are direct children.
+ */
+function orderedSubjectThread(mailboxName, messages) {
+    const bySubject = new Map();
+    for (const msg of messages) {
+        const base = baseSubject(msg.envelope.subject);
+        const bucket = bySubject.get(base);
+        if (bucket === undefined) {
+            bySubject.set(base, [msg]);
+        }
+        else {
+            bucket.push(msg);
+        }
+    }
+    const threads = [];
+    for (const [, msgs] of bySubject) {
+        const sorted = msgs.sort((a, b) => a.envelope.date.getTime() - b.envelope.date.getTime());
+        const root = sorted[0];
+        const rootThread = {
+            ref: { uid: root.uid, mailbox: mailboxName },
+            children: sorted.slice(1).map((m) => ({
+                ref: { uid: m.uid, mailbox: mailboxName },
+                children: [],
+            })),
+        };
+        threads.push(rootThread);
+    }
+    return threads.sort((a, b) => {
+        const aMsg = messages.find((m) => m.uid === a.ref.uid);
+        const bMsg = messages.find((m) => m.uid === b.ref.uid);
+        return aMsg.envelope.date.getTime() - bMsg.envelope.date.getTime();
+    });
+}
+/**
+ * RFC 5256 REFERENCES algorithm.
+ *
+ * Step 1: For each message, create a container. Walk its References list
+ *   (and In-Reply-To if not already in References) and link containers
+ *   as parent-child in left-to-right order.
+ *
+ * Step 2: Build the id_table mapping Message-IDs to containers.
+ *
+ * Step 3: Prune empty containers (those with no message).
+ *
+ * Step 4: Collect root containers.
+ *
+ * Step 5: Sort each container's children by date.
+ */
+function referencesThread(mailboxName, messages) {
+    const idTable = new Map();
+    function getOrCreate(msgId) {
+        const existing = idTable.get(msgId);
+        if (existing !== undefined)
+            return existing;
+        const c = {
+            messageId: msgId,
+            message: null,
+            parent: null,
+            children: [],
+        };
+        idTable.set(msgId, c);
+        return c;
+    }
+    // Step 1 & 2: Build containers and link parent-child relationships.
+    for (const msg of messages) {
+        const container = getOrCreate(msg.envelope.messageId);
+        container.message = msg;
+        // Build the reference list: References + In-Reply-To (deduplicated).
+        const refs = buildRefList(msg.envelope.references, msg.envelope.inReplyTo);
+        // Link: refs[i] is parent of refs[i+1], last ref is parent of this message.
+        let prevContainer = null;
+        for (const refId of refs) {
+            const refContainer = getOrCreate(refId);
+            if (prevContainer !== null &&
+                refContainer.parent === null &&
+                !isAncestor(refContainer, prevContainer)) {
+                prevContainer.children.push(refContainer);
+                refContainer.parent = prevContainer;
+            }
+            prevContainer = refContainer;
+        }
+        // Link the last reference as parent of this message (if no circular reference).
+        if (prevContainer !== null &&
+            container.parent === null &&
+            !isAncestor(container, prevContainer)) {
+            prevContainer.children.push(container);
+            container.parent = prevContainer;
+        }
+    }
+    // Step 3: Find root containers (no parent).
+    const roots = [];
+    for (const [, c] of idTable) {
+        if (c.parent === null) {
+            roots.push(c);
+        }
+    }
+    // Step 4: Prune dummy containers (containers with no message).
+    // A dummy with no children is dropped.
+    // A dummy with children: the children are promoted to the dummy's parent level.
+    const prunedRoots = pruneContainers(roots);
+    // Step 5: Sort and convert to Thread[].
+    return containersToThreads(mailboxName, prunedRoots);
+}
+function buildRefList(references, inReplyTo) {
+    const seen = new Set();
+    const result = [];
+    for (const ref of references) {
+        if (ref && !seen.has(ref)) {
+            seen.add(ref);
+            result.push(ref);
+        }
+    }
+    if (inReplyTo !== undefined && inReplyTo !== "" && !seen.has(inReplyTo)) {
+        result.push(inReplyTo);
+    }
+    return result;
+}
+function isAncestor(potentialAncestor, of) {
+    let cur = of;
+    while (cur !== null) {
+        if (cur === potentialAncestor)
+            return true;
+        cur = cur.parent;
+    }
+    return false;
+}
+function pruneContainers(containers) {
+    const result = [];
+    for (const c of containers) {
+        if (c.message === null && c.children.length === 0) {
+            // Dummy with no children: drop it.
+            continue;
+        }
+        if (c.message === null && c.children.length > 0) {
+            // Dummy with children: promote children (skip the dummy).
+            const promotedChildren = pruneContainers(c.children);
+            result.push(...promotedChildren);
+        }
+        else {
+            // Real message: recurse into children.
+            c.children = pruneContainers(c.children);
+            result.push(c);
+        }
+    }
+    return result;
+}
+function containerDate(c) {
+    if (c.message !== null) {
+        return c.message.envelope.date.getTime();
+    }
+    // For dummy containers, use the earliest child date.
+    let earliest = Infinity;
+    for (const child of c.children) {
+        const d = containerDate(child);
+        if (d < earliest)
+            earliest = d;
+    }
+    return earliest === Infinity ? 0 : earliest;
+}
+function containersToThreads(mailboxName, containers) {
+    // Sort by date of the container (or earliest descendant for dummies).
+    const sorted = containers.sort((a, b) => containerDate(a) - containerDate(b));
+    return sorted
+        .filter((c) => c.message !== null)
+        .map((c) => ({
+        ref: { uid: c.message.uid, mailbox: mailboxName },
+        children: containersToThreads(mailboxName, c.children),
+    }));
+}
+function baseSubject(subject) {
+    // Strip "Re:", "Fwd:", "Fw:" prefixes (case-insensitive) repeatedly.
+    let s = subject.trim();
+    let changed = true;
+    while (changed) {
+        changed = false;
+        const m = s.match(/^(?:re|fwd?)\s*:\s*/i);
+        if (m !== null) {
+            s = s.slice(m[0].length).trim();
+            changed = true;
+        }
+    }
+    return s;
+}