@dxv-systems/helpdesk 0.0.0-stage → 0.2.0

package/dist/testing/index.js

@@ -0,0 +1,472 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createManualClock = createManualClock;
+exports.createMemoryStore = createMemoryStore;
+exports.createFakeMailbox = createFakeMailbox;
+exports.createFakeDrafter = createFakeDrafter;
+exports.createMemoryReplyAttachments = createMemoryReplyAttachments;
+exports.createTestWorld = createTestWorld;
+const errors_1 = require("../errors");
+const clone = (v) => structuredClone(v);
+const tick = () => Promise.resolve();
+function createManualClock(startIso = "2026-11-02T09:00:00.000Z") {
+    let t = Date.parse(startIso);
+    return {
+        now: () => new Date(t),
+        advance: (ms) => {
+            t += ms;
+        },
+        set: (iso) => {
+            t = Date.parse(iso);
+        },
+    };
+}
+const mkey = (mailbox, id) => `${mailbox}\u0000${id}`;
+function createMemoryStore() {
+    const threads = new Map();
+    const messages = new Map();
+    const draftRuns = [];
+    const sendIntents = new Map();
+    const syncStates = new Map();
+    const newestFirst = (a, b) => b.lastActivityAt.localeCompare(a.lastActivityAt);
+    return {
+        threads,
+        messages,
+        draftRuns,
+        sendIntents,
+        syncStates,
+        async getSyncState(mailbox) {
+            await tick();
+            const s = syncStates.get(mailbox);
+            return s ? clone(s) : null;
+        },
+        async saveSyncState(mailbox, state) {
+            await tick();
+            syncStates.set(mailbox, clone(state));
+        },
+        async getMessage(mailbox, id) {
+            await tick();
+            const m = messages.get(mkey(mailbox, id));
+            return m ? clone(m) : null;
+        },
+        async markMessageRemoved(mailbox, id, at) {
+            await tick();
+            const m = messages.get(mkey(mailbox, id));
+            if (m)
+                m.removedAt = at;
+        },
+        async getThread(id) {
+            await tick();
+            const t = threads.get(id);
+            return t ? clone(t) : null;
+        },
+        async getLatestMessageForThread(threadId) {
+            await tick();
+            const last = [...messages.values()]
+                .filter((m) => m.threadId === threadId)
+                .sort((a, b) => a.receivedAt.localeCompare(b.receivedAt))
+                .at(-1);
+            return last ? clone(last) : null;
+        },
+        async listInFlightDraftRuns(mailbox, olderThan) {
+            await tick();
+            return draftRuns
+                .filter((r) => r.mailbox === mailbox &&
+                (r.status === "requested" || r.status === "started") &&
+                r.requestedAt < olderThan)
+                .map(clone);
+        },
+        async findThreadsByConversationId(mailbox, conversationId) {
+            await tick();
+            const ids = new Set([...messages.values()]
+                .filter((m) => m.mailbox === mailbox && m.conversationId === conversationId)
+                .map((m) => m.threadId));
+            return [...ids].map((id) => clone(threads.get(id))).sort(newestFirst);
+        },
+        async findMessageThreads(mailbox, internetMessageIds) {
+            await tick();
+            const wanted = new Set(internetMessageIds);
+            return [...messages.values()]
+                .filter((m) => m.mailbox === mailbox && m.internetMessageId && wanted.has(m.internetMessageId))
+                .map((m) => ({ threadId: m.threadId, internetMessageId: m.internetMessageId }));
+        },
+        async findThreadsBySubjectKey(mailbox, subjectKey, activeSince) {
+            await tick();
+            return [...threads.values()]
+                .filter((t) => t.mailbox === mailbox && t.subjectKey === subjectKey && t.lastActivityAt >= activeSince)
+                .map(clone)
+                .sort(newestFirst);
+        },
+        async createThread(thread, firstMessage) {
+            await tick();
+            if (messages.has(mkey(firstMessage.mailbox, firstMessage.id)))
+                return "duplicate";
+            threads.set(thread.id, clone(thread));
+            messages.set(mkey(firstMessage.mailbox, firstMessage.id), clone(firstMessage));
+            return "created";
+        },
+        async appendMessage(message, update) {
+            await tick();
+            if (messages.has(mkey(message.mailbox, message.id)))
+                return "duplicate";
+            const t = threads.get(update.threadId);
+            if (!t || t.state !== update.expectedState)
+                return "stale";
+            Object.assign(t, update.patch);
+            messages.set(mkey(message.mailbox, message.id), clone(message));
+            return "appended";
+        },
+        async updateThread(update) {
+            await tick();
+            const t = threads.get(update.threadId);
+            if (!t || t.state !== update.expectedState)
+                return false;
+            Object.assign(t, update.patch);
+            return true;
+        },
+        async createDraftRunIfAbsent(run) {
+            await tick();
+            const found = draftRuns.find((r) => r.idempotencyKey === run.idempotencyKey);
+            if (found)
+                return { created: false, run: clone(found) };
+            draftRuns.push(clone(run));
+            return { created: true, run: clone(run) };
+        },
+        async getLatestDraftRun(mailbox, inboundMessageId) {
+            await tick();
+            const runs = draftRuns.filter((r) => r.mailbox === mailbox && r.inboundMessageId === inboundMessageId);
+            const last = runs.sort((a, b) => a.generation - b.generation).at(-1);
+            return last ? clone(last) : null;
+        },
+        async getLatestDraftRunForThread(threadId) {
+            await tick();
+            const last = draftRuns.filter((r) => r.threadId === threadId).at(-1);
+            return last ? clone(last) : null;
+        },
+        async updateDraftRun(key, patch) {
+            await tick();
+            const run = draftRuns.find((r) => r.idempotencyKey === key);
+            if (!run)
+                throw new Error(`no draft run ${key}`);
+            Object.assign(run, patch);
+            return clone(run);
+        },
+        async listSendIntentsByStatus(mailbox, status) {
+            await tick();
+            return [...sendIntents.values()]
+                .filter((i) => i.mailbox === mailbox && i.status === status)
+                .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
+                .map(clone);
+        },
+        async createSendIntentIfAbsent(intent) {
+            await tick();
+            const found = sendIntents.get(intent.id);
+            if (found)
+                return { created: false, intent: clone(found) };
+            sendIntents.set(intent.id, clone(intent));
+            return { created: true, intent: clone(intent) };
+        },
+        async getSendIntent(id) {
+            await tick();
+            const i = sendIntents.get(id);
+            return i ? clone(i) : null;
+        },
+        async transitionSendIntent(id, from, patch) {
+            await tick();
+            const i = sendIntents.get(id);
+            if (!i || !from.includes(i.status))
+                return null;
+            Object.assign(i, patch);
+            return clone(i);
+        },
+    };
+}
+const WRITE_METHODS = ["createReply", "updateDraftBody", "sendDraft"];
+function createFakeMailbox(address) {
+    const mails = new Map();
+    const log = [];
+    const drafts = new Map();
+    let expired = false;
+    let draftCounter = 0;
+    const summary = (m) => ({
+        id: m.id,
+        removed: false,
+        ...(m.subject !== undefined ? { subject: m.subject } : {}),
+        ...(m.from ? { from: { address: m.from } } : {}),
+        ...(m.receivedDateTime ? { receivedDateTime: m.receivedDateTime } : {}),
+        ...(m.internetMessageId ? { internetMessageId: m.internetMessageId } : {}),
+        ...(m.conversationId ? { conversationId: m.conversationId } : {}),
+        ...(m.isDraft ? { isDraft: true } : {}),
+        ...(m.attachments ? { hasAttachments: m.attachments.some((a) => !a.isInline) } : {}),
+    });
+    const box = {
+        address,
+        sendBehaviour: { kind: "ok" },
+        sent: [],
+        drafts,
+        getMessageCalls: 0,
+        draftAttachments: new Map(),
+        addAttachmentError: null,
+        outage: null,
+        deltaCalls: [],
+        calls: [],
+        get writeCalls() {
+            return box.calls.filter((c) => WRITE_METHODS.includes(c.split(":")[0] ?? ""));
+        },
+        deliver(mail) {
+            mails.set(mail.id, mail);
+            log.push(summary(mail));
+        },
+        touch(id) {
+            const m = mails.get(id);
+            if (m)
+                log.push({ ...summary(m), isRead: true, categories: ["seen"] });
+        },
+        remove(id, reason = "deleted") {
+            mails.delete(id);
+            log.push({ id, removed: true, removedReason: reason });
+        },
+        expireLinks() {
+            expired = true;
+        },
+        async delta(options) {
+            await tick();
+            box.calls.push("delta");
+            box.deltaCalls.push(options);
+            if (box.outage)
+                throw box.outage;
+            const size = options.pageSize ?? 50;
+            let start = 0;
+            if (options.link) {
+                if (expired)
+                    throw new errors_1.DeltaLinkExpiredError();
+                start = Number(options.link.split(":")[1]);
+            }
+            const since = options.since ? Date.parse(String(options.since)) : null;
+            const visible = (i) => Boolean(options.link) ||
+                since === null ||
+                i.removed ||
+                !i.receivedDateTime ||
+                Date.parse(i.receivedDateTime) >= since;
+            const slice = log.slice(start, start + size);
+            const end = start + slice.length;
+            const more = end < log.length;
+            return {
+                items: slice.filter(visible),
+                nextLink: more ? `p:${end}` : null,
+                deltaLink: more ? null : `d:${end}`,
+            };
+        },
+        async getMessage(id, options) {
+            await tick();
+            box.calls.push(`getMessage:${id}`);
+            box.getMessageCalls++;
+            if (box.outage)
+                throw box.outage;
+            const m = mails.get(id);
+            if (!m) {
+                const draft = box.sent.includes(id) ? undefined : drafts.get(id);
+                return draft ? { ...clone(draft), isDraft: true } : null;
+            }
+            const headers = Object.entries(m.headers ?? {}).map(([name, value]) => ({ name, value }));
+            return {
+                ...summary(m),
+                body: { contentType: "text", content: m.bodyText ?? "hello" },
+                toRecipients: [{ address }],
+                ccRecipients: [],
+                replyTo: (m.replyTo ?? []).map((address) => ({ address })),
+                ...(options?.includeHeaders
+                    ? {
+                        internetMessageHeaders: headers,
+                        ...(m.inReplyTo ? { inReplyTo: m.inReplyTo } : {}),
+                        ...(m.references ? { references: m.references } : {}),
+                    }
+                    : {}),
+            };
+        },
+        async listAttachments(messageId) {
+            await tick();
+            box.calls.push(`listAttachments:${messageId}`);
+            return (mails.get(messageId)?.attachments ?? []).map((a) => ({
+                id: a.id,
+                name: a.name,
+                contentType: a.contentType ?? "application/octet-stream",
+                size: a.size ?? a.content?.byteLength ?? 0,
+                isInline: a.isInline === true,
+                kind: a.kind ?? "file",
+            }));
+        },
+        async downloadAttachment(messageId, attachmentId) {
+            await tick();
+            box.calls.push(`downloadAttachment:${messageId}:${attachmentId}`);
+            const found = mails.get(messageId)?.attachments?.find((a) => a.id === attachmentId);
+            if (!found?.content)
+                throw Object.assign(new Error("attachment not found"), { status: 404 });
+            return found.content;
+        },
+        async createReply(messageId, options) {
+            await tick();
+            box.calls.push(`createReply:${messageId}`);
+            const original = mails.get(messageId);
+            const id = `draft-${++draftCounter}`;
+            const comment = (options?.comment ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;");
+            const content = `<html><head></head><body><div>${comment}</div><div id="appendonsend"></div>` +
+                `<hr><div id="divRplyFwdMsg"><b>From:</b> ${original?.from ?? "?"}</div>` +
+                `<blockquote>${original?.bodyText ?? "quoted original"}</blockquote></body></html>`;
+            const draft = {
+                id,
+                isDraft: true,
+                body: { contentType: "html", content },
+                toRecipients: [],
+                ccRecipients: [],
+                replyTo: [],
+            };
+            drafts.set(id, draft);
+            return clone(draft);
+        },
+        async updateDraftBody(draftId, body) {
+            await tick();
+            box.calls.push(`updateDraftBody:${draftId}`);
+            const d = drafts.get(draftId);
+            if (!d)
+                throw new Error(`no draft ${draftId}`);
+            d.body = clone(body);
+        },
+        async addAttachment(draftId, attachment) {
+            await tick();
+            box.calls.push(`addAttachment:${draftId}:${attachment.name}`);
+            if (box.addAttachmentError)
+                throw box.addAttachmentError;
+            const list = box.draftAttachments.get(draftId) ?? [];
+            list.push({ name: attachment.name, contentType: attachment.contentType, size: attachment.content.byteLength });
+            box.draftAttachments.set(draftId, list);
+            return {};
+        },
+        async sendDraft(draftId) {
+            await tick();
+            box.calls.push(`sendDraft:${draftId}`);
+            const b = box.sendBehaviour;
+            if (b.kind === "reject")
+                throw b.error;
+            box.sent.push(draftId);
+            if (b.kind === "lost_response")
+                throw b.error;
+        },
+    };
+    return box;
+}
+function createFakeDrafter() {
+    const runs = new Map();
+    const drafter = {
+        requests: [],
+        runs,
+        failStart: null,
+        async start(request) {
+            await tick();
+            drafter.requests.push(request);
+            if (drafter.failStart)
+                throw drafter.failStart;
+            const existing = runs.get(request.idempotencyKey);
+            if (existing)
+                return { runId: existing };
+            const runId = `run-${runs.size + 1}`;
+            runs.set(request.idempotencyKey, runId);
+            return { runId };
+        },
+    };
+    return drafter;
+}
+function createMemoryReplyAttachments() {
+    const rows = new Map();
+    const store = {
+        rows,
+        async add(a) {
+            rows.set(a.id, { ...a });
+        },
+        async listForThread(threadId) {
+            return [...rows.values()].filter((a) => a.threadId === threadId).map((a) => ({ ...a }));
+        },
+        async update(id, patch) {
+            const row = rows.get(id);
+            if (row)
+                rows.set(id, { ...row, ...patch });
+        },
+        async removeUnsent(id) {
+            const row = rows.get(id);
+            if (!row || row.sentIntentId !== null)
+                return null;
+            rows.delete(id);
+            return row;
+        },
+    };
+    const pending = new Map();
+    const stored = new Map();
+    const meta = new Map();
+    const removed = [];
+    let n = 0;
+    const files = {
+        stored,
+        removed,
+        upload(uploadToken, content) {
+            const p = pending.get(uploadToken);
+            if (!p)
+                throw new Error(`unknown upload ${uploadToken}`);
+            p.content = content;
+        },
+        async createUpload(input) {
+            const uploadToken = `upload-${++n}`;
+            pending.set(uploadToken, { ...input });
+            return { uploadUrl: `https://files.test/${uploadToken}`, uploadToken, contentType: input.contentType };
+        },
+        async completeUpload({ staffId, uploadToken }) {
+            const p = pending.get(uploadToken);
+            if (!p || p.staffId !== staffId)
+                throw new Error("invalid upload token");
+            if (!p.content || p.content.byteLength !== p.size)
+                throw new Error("the file was not uploaded");
+            pending.delete(uploadToken);
+            const fileId = `file-${++n}`;
+            stored.set(fileId, p.content);
+            meta.set(fileId, { name: p.name, contentType: p.contentType });
+            return { fileId, name: p.name, contentType: p.contentType, size: p.size };
+        },
+        async read({ fileId }) {
+            const content = stored.get(fileId);
+            if (!content)
+                throw new Error(`file ${fileId} not found`);
+            return content;
+        },
+        async remove({ fileId }) {
+            removed.push(fileId);
+            stored.delete(fileId);
+        },
+    };
+    return { store, files };
+}
+function createTestWorld(options = {}) {
+    const addresses = options.mailboxes ?? ["support@client.test"];
+    const mailboxes = Object.fromEntries(addresses.map((a) => [a, createFakeMailbox(a)]));
+    const store = createMemoryStore();
+    const clock = createManualClock();
+    const drafter = createFakeDrafter();
+    let n = 0;
+    const deps = {
+        store,
+        clock,
+        drafter,
+        gatewayFor: (mailbox) => {
+            const box = mailboxes[mailbox];
+            if (!box)
+                throw new Error(`unknown mailbox ${mailbox}`);
+            return box;
+        },
+        config: {
+            ownAddresses: ["noreply@app.test"],
+            connectedMailboxes: addresses,
+            ...options.config,
+        },
+        newId: () => `id-${++n}`,
+        ...(options.controls ? { controls: options.controls } : {}),
+    };
+    return { deps, store, clock, drafter, mailboxes };
+}

package/dist/threading.d.ts

@@ -0,0 +1,18 @@
+import type { HelpdeskStore, Thread } from "./types";
+export interface ThreadCandidate {
+    mailbox: string;
+    conversationId?: string | null;
+    inReplyTo?: string | null;
+    references?: string[] | null;
+    subject?: string;
+    from: string;
+    receivedAt: string;
+}
+export interface ThreadMatch {
+    thread: Thread | null;
+    via: "conversation" | "headers" | "subject" | "none";
+}
+export declare function normalizeMessageId(id: string | null | undefined): string | null;
+export declare function matchThread(store: HelpdeskStore, candidate: ThreadCandidate, options?: {
+    subjectWindowMs?: number;
+}): Promise<ThreadMatch>;

package/dist/threading.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeMessageId = normalizeMessageId;
+exports.matchThread = matchThread;
+const subject_1 = require("./subject");
+const DEFAULT_SUBJECT_WINDOW_MS = 14 * 24 * 60 * 60 * 1000;
+function normalizeMessageId(id) {
+    const v = (id ?? "").trim().replace(/^<+|>+$/g, "").trim().toLowerCase();
+    return v || null;
+}
+const isFinal = (t) => t.state === "closed" || t.state === "ignored";
+const byActivityDesc = (a, b) => b.lastActivityAt.localeCompare(a.lastActivityAt);
+function onlyOpenOrOne(threads) {
+    if (threads.length === 1)
+        return threads[0] ?? null;
+    const open = threads.filter((t) => !isFinal(t));
+    return open.length === 1 ? (open[0] ?? null) : null;
+}
+async function matchThread(store, candidate, options = {}) {
+    const none = { thread: null, via: "none" };
+    const { mailbox } = candidate;
+    const from = candidate.from.trim().toLowerCase();
+    const sameMailbox = (t) => t.mailbox === mailbox;
+    const knowsSender = (t) => t.participants.includes(from);
+    const forward = (0, subject_1.isForwardSubject)(candidate.subject);
+    const parent = normalizeMessageId(candidate.inReplyTo);
+    const refs = [...new Set([parent, ...(candidate.references ?? []).map(normalizeMessageId)])].filter((x) => x !== null);
+    const hits = refs.length ? await store.findMessageThreads(mailbox, refs) : [];
+    const headerThreadIds = new Set(hits.map((h) => h.threadId));
+    if (candidate.conversationId) {
+        const found = (await store.findThreadsByConversationId(mailbox, candidate.conversationId))
+            .filter(sameMailbox)
+            .sort(byActivityDesc);
+        const conversationThread = found.find((t) => knowsSender(t) || headerThreadIds.has(t.id));
+        if (conversationThread) {
+            if (headerThreadIds.size > 0 && !headerThreadIds.has(conversationThread.id))
+                return none;
+            return { thread: conversationThread, via: "conversation" };
+        }
+    }
+    if (headerThreadIds.size > 0) {
+        const direct = parent ? hits.find((h) => h.internetMessageId === parent) : undefined;
+        const ids = direct ? [direct.threadId] : [...headerThreadIds];
+        const threads = [];
+        for (const id of ids) {
+            const t = await store.getThread(id);
+            if (t && sameMailbox(t))
+                threads.push(t);
+        }
+        const chosen = onlyOpenOrOne(threads);
+        if (chosen && !(forward && !knowsSender(chosen)))
+            return { thread: chosen, via: "headers" };
+    }
+    const key = (0, subject_1.normalizeSubject)(candidate.subject);
+    if (!key)
+        return none;
+    const received = Date.parse(candidate.receivedAt);
+    if (Number.isNaN(received))
+        return none;
+    const since = new Date(received - (options.subjectWindowMs ?? DEFAULT_SUBJECT_WINDOW_MS));
+    const bySubject = (await store.findThreadsBySubjectKey(mailbox, key, since.toISOString()))
+        .filter((t) => sameMailbox(t) && knowsSender(t))
+        .sort(byActivityDesc);
+    const chosen = onlyOpenOrOne(bySubject);
+    return chosen ? { thread: chosen, via: "subject" } : none;
+}