@dxv-systems/helpdesk 0.0.0-stage → 0.1.0

package/dist/inbox/plain-text.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.htmlToPlainText = htmlToPlainText;
+const NAMED_ENTITIES = {
+    nbsp: " ",
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    euro: "€",
+    hellip: "…",
+    ndash: "–",
+    mdash: "—",
+    lsquo: "‘",
+    rsquo: "’",
+    ldquo: "“",
+    rdquo: "”",
+    copy: "©",
+    reg: "®",
+    eacute: "é",
+    euml: "ë",
+    iuml: "ï",
+    ouml: "ö",
+    uuml: "ü",
+};
+function codePoint(n) {
+    if (!Number.isFinite(n) || n <= 0 || n > 0x10ffff || (n >= 0xd800 && n <= 0xdfff))
+        return "";
+    return String.fromCodePoint(n);
+}
+function decodeEntities(text) {
+    return text.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi, (whole, ref) => {
+        if (ref[0] === "#") {
+            const hex = ref[1] === "x" || ref[1] === "X";
+            return codePoint(parseInt(ref.slice(hex ? 2 : 1), hex ? 16 : 10));
+        }
+        return NAMED_ENTITIES[ref.toLowerCase()] ?? whole;
+    });
+}
+const BLOCK_END = /<\/(p|div|li|tr|h[1-6]|blockquote|pre|table|section|article)\s*>/gi;
+const LINE_BREAK = /<(br|hr)\b[^>]*>/gi;
+function htmlToPlainText(html) {
+    const text = html
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/<(head|style|script|title|noscript|template)\b[\s\S]*?<\/\1\s*>/gi, "")
+        .replace(LINE_BREAK, "\n")
+        .replace(BLOCK_END, "\n")
+        .replace(/<li\b[^>]*>/gi, "• ")
+        .replace(/<[^>]*>/g, "")
+        .replace(/<[^>]*$/, "");
+    return decodeEntities(text)
+        .replace(/[^\S\r\n]/g, " ")
+        .replace(/\r\n?/g, "\n")
+        .replace(/ +\n/g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}

package/dist/inbox/types.d.ts

@@ -0,0 +1,108 @@
+import type { MailboxWriteMode, ReviewReason, SendStatus, TicketState } from "../types";
+export interface HelpdeskStaff {
+    id: string;
+    name: string;
+    email: string;
+}
+export interface InboxPerson {
+    id: string;
+    name: string;
+}
+export interface InboxMailboxView {
+    address: string;
+    writeMode: MailboxWriteMode;
+}
+export interface InboxPilotView {
+    paused: boolean;
+    mailboxes: InboxMailboxView[];
+}
+export interface InboxThreadSummary {
+    id: string;
+    mailbox: string;
+    state: TicketState;
+    subject: string;
+    customerAddress: string;
+    lastActivityAt: string;
+    reviewReason: ReviewReason | null;
+    assignee: InboxPerson | null;
+}
+export interface InboxSyncIssue {
+    mailbox: string;
+    failingSince: string;
+}
+export interface InboxThreadList {
+    viewer: InboxPerson;
+    pilot: InboxPilotView;
+    syncIssues: InboxSyncIssue[];
+    threads: InboxThreadSummary[];
+    nextCursor: string | null;
+}
+export interface InboxMessageView {
+    id: string;
+    fromAddress: string;
+    subject: string;
+    receivedAt: string;
+    noise: boolean;
+    removed: boolean;
+}
+export interface InboxMessageBody {
+    id: string;
+    text: string;
+    attachments: InboxAttachmentView[];
+}
+export interface InboxReplyAttachmentView {
+    id: string;
+    name: string;
+    size: number;
+    sent: boolean;
+}
+export interface InboxUploadTarget {
+    uploadUrl: string;
+    uploadToken: string;
+    contentType: string;
+}
+export interface InboxAttachmentView {
+    id: string;
+    name: string;
+    size: number;
+    kind: "file" | "item" | "reference";
+    href: string | null;
+    unavailable: "item" | "reference" | "too_large" | null;
+}
+export interface InboxDraftView {
+    generation: number;
+    status: "requested" | "started" | "succeeded" | "failed";
+    text: string | null;
+    confidence: number | null;
+    category: string | null;
+    stale: boolean;
+    inOutlook: boolean;
+}
+export type InboxAction = "edit" | "regenerate" | "send" | "retry_placement" | "replied_externally" | "mark_waiting" | "close" | "unignore" | "dismiss" | "resolve_send" | "attach";
+export interface InboxThreadDetail {
+    viewer: InboxPerson;
+    thread: InboxThreadSummary & {
+        relatedThreadId: string | null;
+        dismissedBy: string | null;
+        participants: string[];
+        createdAt: string;
+    };
+    pilot: {
+        paused: boolean;
+        writeMode: MailboxWriteMode;
+    };
+    messages: InboxMessageView[];
+    draft: InboxDraftView | null;
+    send: {
+        status: SendStatus;
+        at: string;
+    } | null;
+    replyAttachments: InboxReplyAttachmentView[];
+    actions: InboxAction[];
+}
+export type InboxSendOutcome = "sent" | "already_sent" | "in_progress" | "unknown_outcome";
+export interface InboxActionResult {
+    detail: InboxThreadDetail;
+    message: string;
+    outcome?: InboxSendOutcome;
+}

package/dist/inbox/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./types";
+export * from "./errors";
+export * from "./states";
+export { DEFAULT_WRITE_MODE, isPaused, writeModeFor } from "./controls";
+export { normalizeSubject, isForwardSubject } from "./subject";
+export { classifyNoise, type NoiseInput, type NoiseVerdict } from "./noise";
+export { matchThread, normalizeMessageId, type ThreadCandidate, type ThreadMatch } from "./threading";
+export { connectMailbox, ingestPage, isSyncFailing, syncMailbox, SYNC_FAILING_AFTER, type IngestResult, } from "./ingest";
+export { ensureDraft, completeDraft, regenerateDraft, editDraft, retryPlacement, sweepStuckDrafts, unignoreThread, type EnsureDraftOutcome, } from "./drafting";
+export { renderCommentHtml, replaceDraftComment, prependToDraftBody, hasQuotedHistory, findQuoteStart, } from "./draft-body";
+export { approveAndSend, reconcileUnknownSends, resolveUnknownSend, markRepliedExternally, markWaiting, closeThread, dismissThread, classifySendError, type SendOutcome, } from "./sending";
+export { MAX_REPLY_ATTACHMENT_BYTES, MAX_REPLY_ATTACHMENTS, addReplyAttachment, pendingReplyAttachments, removeReplyAttachment, startReplyUpload, } from "./reply-attachments";
+export { evaluateAutoSend, DEFAULT_AUTO_SEND_POLICY, type AutoSendPolicy, type AutoSendContext, type AutoSendDecision, type OfficeHours, } from "./autosend";

package/dist/index.js

@@ -0,0 +1,71 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AUTO_SEND_POLICY = exports.evaluateAutoSend = exports.startReplyUpload = exports.removeReplyAttachment = exports.pendingReplyAttachments = exports.addReplyAttachment = exports.MAX_REPLY_ATTACHMENTS = exports.MAX_REPLY_ATTACHMENT_BYTES = exports.classifySendError = exports.dismissThread = exports.closeThread = exports.markWaiting = exports.markRepliedExternally = exports.resolveUnknownSend = exports.reconcileUnknownSends = exports.approveAndSend = exports.findQuoteStart = exports.hasQuotedHistory = exports.prependToDraftBody = exports.replaceDraftComment = exports.renderCommentHtml = exports.unignoreThread = exports.sweepStuckDrafts = exports.retryPlacement = exports.editDraft = exports.regenerateDraft = exports.completeDraft = exports.ensureDraft = exports.SYNC_FAILING_AFTER = exports.syncMailbox = exports.isSyncFailing = exports.ingestPage = exports.connectMailbox = exports.normalizeMessageId = exports.matchThread = exports.classifyNoise = exports.isForwardSubject = exports.normalizeSubject = exports.writeModeFor = exports.isPaused = exports.DEFAULT_WRITE_MODE = void 0;
+__exportStar(require("./types"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./states"), exports);
+var controls_1 = require("./controls");
+Object.defineProperty(exports, "DEFAULT_WRITE_MODE", { enumerable: true, get: function () { return controls_1.DEFAULT_WRITE_MODE; } });
+Object.defineProperty(exports, "isPaused", { enumerable: true, get: function () { return controls_1.isPaused; } });
+Object.defineProperty(exports, "writeModeFor", { enumerable: true, get: function () { return controls_1.writeModeFor; } });
+var subject_1 = require("./subject");
+Object.defineProperty(exports, "normalizeSubject", { enumerable: true, get: function () { return subject_1.normalizeSubject; } });
+Object.defineProperty(exports, "isForwardSubject", { enumerable: true, get: function () { return subject_1.isForwardSubject; } });
+var noise_1 = require("./noise");
+Object.defineProperty(exports, "classifyNoise", { enumerable: true, get: function () { return noise_1.classifyNoise; } });
+var threading_1 = require("./threading");
+Object.defineProperty(exports, "matchThread", { enumerable: true, get: function () { return threading_1.matchThread; } });
+Object.defineProperty(exports, "normalizeMessageId", { enumerable: true, get: function () { return threading_1.normalizeMessageId; } });
+var ingest_1 = require("./ingest");
+Object.defineProperty(exports, "connectMailbox", { enumerable: true, get: function () { return ingest_1.connectMailbox; } });
+Object.defineProperty(exports, "ingestPage", { enumerable: true, get: function () { return ingest_1.ingestPage; } });
+Object.defineProperty(exports, "isSyncFailing", { enumerable: true, get: function () { return ingest_1.isSyncFailing; } });
+Object.defineProperty(exports, "syncMailbox", { enumerable: true, get: function () { return ingest_1.syncMailbox; } });
+Object.defineProperty(exports, "SYNC_FAILING_AFTER", { enumerable: true, get: function () { return ingest_1.SYNC_FAILING_AFTER; } });
+var drafting_1 = require("./drafting");
+Object.defineProperty(exports, "ensureDraft", { enumerable: true, get: function () { return drafting_1.ensureDraft; } });
+Object.defineProperty(exports, "completeDraft", { enumerable: true, get: function () { return drafting_1.completeDraft; } });
+Object.defineProperty(exports, "regenerateDraft", { enumerable: true, get: function () { return drafting_1.regenerateDraft; } });
+Object.defineProperty(exports, "editDraft", { enumerable: true, get: function () { return drafting_1.editDraft; } });
+Object.defineProperty(exports, "retryPlacement", { enumerable: true, get: function () { return drafting_1.retryPlacement; } });
+Object.defineProperty(exports, "sweepStuckDrafts", { enumerable: true, get: function () { return drafting_1.sweepStuckDrafts; } });
+Object.defineProperty(exports, "unignoreThread", { enumerable: true, get: function () { return drafting_1.unignoreThread; } });
+var draft_body_1 = require("./draft-body");
+Object.defineProperty(exports, "renderCommentHtml", { enumerable: true, get: function () { return draft_body_1.renderCommentHtml; } });
+Object.defineProperty(exports, "replaceDraftComment", { enumerable: true, get: function () { return draft_body_1.replaceDraftComment; } });
+Object.defineProperty(exports, "prependToDraftBody", { enumerable: true, get: function () { return draft_body_1.prependToDraftBody; } });
+Object.defineProperty(exports, "hasQuotedHistory", { enumerable: true, get: function () { return draft_body_1.hasQuotedHistory; } });
+Object.defineProperty(exports, "findQuoteStart", { enumerable: true, get: function () { return draft_body_1.findQuoteStart; } });
+var sending_1 = require("./sending");
+Object.defineProperty(exports, "approveAndSend", { enumerable: true, get: function () { return sending_1.approveAndSend; } });
+Object.defineProperty(exports, "reconcileUnknownSends", { enumerable: true, get: function () { return sending_1.reconcileUnknownSends; } });
+Object.defineProperty(exports, "resolveUnknownSend", { enumerable: true, get: function () { return sending_1.resolveUnknownSend; } });
+Object.defineProperty(exports, "markRepliedExternally", { enumerable: true, get: function () { return sending_1.markRepliedExternally; } });
+Object.defineProperty(exports, "markWaiting", { enumerable: true, get: function () { return sending_1.markWaiting; } });
+Object.defineProperty(exports, "closeThread", { enumerable: true, get: function () { return sending_1.closeThread; } });
+Object.defineProperty(exports, "dismissThread", { enumerable: true, get: function () { return sending_1.dismissThread; } });
+Object.defineProperty(exports, "classifySendError", { enumerable: true, get: function () { return sending_1.classifySendError; } });
+var reply_attachments_1 = require("./reply-attachments");
+Object.defineProperty(exports, "MAX_REPLY_ATTACHMENT_BYTES", { enumerable: true, get: function () { return reply_attachments_1.MAX_REPLY_ATTACHMENT_BYTES; } });
+Object.defineProperty(exports, "MAX_REPLY_ATTACHMENTS", { enumerable: true, get: function () { return reply_attachments_1.MAX_REPLY_ATTACHMENTS; } });
+Object.defineProperty(exports, "addReplyAttachment", { enumerable: true, get: function () { return reply_attachments_1.addReplyAttachment; } });
+Object.defineProperty(exports, "pendingReplyAttachments", { enumerable: true, get: function () { return reply_attachments_1.pendingReplyAttachments; } });
+Object.defineProperty(exports, "removeReplyAttachment", { enumerable: true, get: function () { return reply_attachments_1.removeReplyAttachment; } });
+Object.defineProperty(exports, "startReplyUpload", { enumerable: true, get: function () { return reply_attachments_1.startReplyUpload; } });
+var autosend_1 = require("./autosend");
+Object.defineProperty(exports, "evaluateAutoSend", { enumerable: true, get: function () { return autosend_1.evaluateAutoSend; } });
+Object.defineProperty(exports, "DEFAULT_AUTO_SEND_POLICY", { enumerable: true, get: function () { return autosend_1.DEFAULT_AUTO_SEND_POLICY; } });

package/dist/ingest.d.ts

@@ -0,0 +1,25 @@
+import type { HelpdeskDeps, Paused, SyncFailing, SyncState } from "./types";
+export interface IngestResult {
+    fetched: number;
+    created: number;
+    appended: number;
+    ignored: number;
+    duplicates: number;
+    unchanged: number;
+    removed: number;
+    skippedDrafts: number;
+    skippedOwn: number;
+    skippedPredates: number;
+    gone: number;
+    draftsStarted: number;
+    deliveryFailures: number;
+    restarted: boolean;
+    hasMore: boolean;
+}
+export declare function connectMailbox(deps: HelpdeskDeps, mailbox: string): Promise<SyncState>;
+export declare function ingestPage(deps: HelpdeskDeps, mailbox: string): Promise<IngestResult | Paused>;
+export declare function syncMailbox(deps: HelpdeskDeps, mailbox: string, options?: {
+    maxPages?: number;
+}): Promise<IngestResult[] | Paused | SyncFailing>;
+export declare const SYNC_FAILING_AFTER = 3;
+export declare function isSyncFailing(value: unknown): value is SyncFailing;

package/dist/ingest.js

@@ -0,0 +1,335 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYNC_FAILING_AFTER = void 0;
+exports.connectMailbox = connectMailbox;
+exports.ingestPage = ingestPage;
+exports.syncMailbox = syncMailbox;
+exports.isSyncFailing = isSyncFailing;
+const controls_1 = require("./controls");
+const drafting_1 = require("./drafting");
+const errors_1 = require("./errors");
+const internal_1 = require("./internal");
+const bounce_1 = require("./bounce");
+const noise_1 = require("./noise");
+const states_1 = require("./states");
+const subject_1 = require("./subject");
+const threading_1 = require("./threading");
+const DEFAULT_RESTART_OVERLAP_MS = 48 * 60 * 60 * 1000;
+const MAX_ATTEMPTS = 3;
+async function connectMailbox(deps, mailbox) {
+    (0, controls_1.assertInScope)(deps.config, mailbox);
+    const existing = await deps.store.getSyncState(mailbox);
+    if (existing)
+        return existing;
+    const state = { link: null, connectedAt: (0, internal_1.nowIso)(deps), lastReceivedAt: null };
+    await deps.store.saveSyncState(mailbox, state);
+    return state;
+}
+function headerValue(msg, name) {
+    return msg.internetMessageHeaders?.find((h) => h.name.toLowerCase() === name)?.value;
+}
+function threadingHeaders(msg) {
+    const inReplyTo = msg.inReplyTo ?? headerValue(msg, "in-reply-to") ?? null;
+    const raw = headerValue(msg, "references");
+    const references = msg.references ?? (raw ? (raw.match(/<[^>]+>/g) ?? []) : []);
+    return { inReplyTo, references };
+}
+function restartFrom(state, overlapMs) {
+    if (!state.lastReceivedAt)
+        return state.connectedAt;
+    const back = Date.parse(state.lastReceivedAt) - overlapMs;
+    return new Date(Math.max(Date.parse(state.connectedAt), back)).toISOString();
+}
+async function fetchPage(deps, gateway, state) {
+    const pageSize = deps.config.pageSize;
+    const first = (s) => gateway.delta(s.link
+        ? { link: s.link, ...(pageSize ? { pageSize } : {}) }
+        : {
+            folderId: "inbox",
+            since: restartFrom(s, deps.config.restartOverlapMs ?? DEFAULT_RESTART_OVERLAP_MS),
+            ...(pageSize ? { pageSize } : {}),
+        });
+    try {
+        return { page: await first(state), restarted: false };
+    }
+    catch (err) {
+        if (!state.link || !(0, errors_1.isDeltaLinkExpired)(err))
+            throw err;
+        return { page: await first({ ...state, link: null }), restarted: true };
+    }
+}
+function emptyResult() {
+    return {
+        fetched: 0,
+        created: 0,
+        appended: 0,
+        ignored: 0,
+        duplicates: 0,
+        unchanged: 0,
+        removed: 0,
+        skippedDrafts: 0,
+        skippedOwn: 0,
+        skippedPredates: 0,
+        gone: 0,
+        draftsStarted: 0,
+        deliveryFailures: 0,
+        restarted: false,
+        hasMore: false,
+    };
+}
+async function reconcileExisting(deps, existing, result) {
+    if (existing.removedAt)
+        return;
+    const thread = await deps.store.getThread(existing.threadId);
+    if (thread && (thread.state === "new" || thread.state === "drafted")) {
+        if ((await (0, drafting_1.startDraftFor)(deps, thread.id, existing)) === "started")
+            result.draftsStarted++;
+    }
+}
+async function processNew(deps, gateway, mailbox, item, state, result) {
+    const connectedAt = Date.parse(state.connectedAt);
+    if (item.receivedDateTime && Date.parse(item.receivedDateTime) < connectedAt) {
+        result.skippedPredates++;
+        return;
+    }
+    const msg = await gateway.getMessage(item.id, {
+        includeHeaders: true,
+        bodyType: "text",
+    });
+    if (!msg) {
+        result.gone++;
+        return;
+    }
+    const receivedAt = msg.receivedDateTime ?? item.receivedDateTime ?? (0, internal_1.nowIso)(deps);
+    const from = (msg.from?.address ?? item.from?.address ?? "").trim().toLowerCase();
+    const subject = msg.subject ?? item.subject ?? "";
+    const headers = threadingHeaders(msg);
+    const noise = (0, noise_1.classifyNoise)({
+        from,
+        subject,
+        headers: msg.internetMessageHeaders,
+        replyTo: msg.replyTo.map((a) => a.address),
+        ownAddresses: deps.config.ownAddresses,
+        connectedMailboxes: deps.config.connectedMailboxes,
+    });
+    const isNoise = noise.action === "ignore";
+    const customer = noise.customerAddress ?? from;
+    const people = [...new Set([from, customer].filter(Boolean))];
+    const base = {
+        id: item.id,
+        mailbox,
+        internetMessageId: (0, threading_1.normalizeMessageId)(msg.internetMessageId ?? item.internetMessageId),
+        conversationId: msg.conversationId ?? item.conversationId ?? null,
+        subject,
+        fromAddress: from,
+        receivedAt,
+        noise: { action: noise.action, reason: noise.reason },
+        suppressAutoResponse: noise.suppressAutoResponse === true,
+        removedAt: null,
+    };
+    if (noise.reason === "bounce") {
+        const refs = [...new Set([...(0, bounce_1.bouncedReplyRefs)(msg.body?.content ?? ""), ...headerRefs(headers)])];
+        if (await recordBounce(deps, mailbox, base, refs, result))
+            return;
+    }
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        const match = await (0, threading_1.matchThread)(deps.store, {
+            mailbox,
+            conversationId: base.conversationId,
+            inReplyTo: headers.inReplyTo,
+            references: headers.references,
+            subject,
+            from,
+            receivedAt,
+        }, { subjectWindowMs: deps.config.subjectWindowMs });
+        let outcome;
+        let threadId;
+        const existing = match.thread;
+        const reply = existing && !isNoise ? (0, states_1.onCustomerReply)(existing.state) : null;
+        if (existing && (isNoise || reply?.kind === "append")) {
+            threadId = existing.id;
+            const patch = {};
+            if (!isNoise && reply?.kind === "append") {
+                patch.state = reply.next;
+                patch.participants = [...new Set([...existing.participants, ...people])];
+                patch.latestInboundId = item.id;
+                patch.lastActivityAt = receivedAt;
+                if (existing.state === "review")
+                    patch.reviewReason = "stale_draft";
+                if (reply.next === "new")
+                    patch.reviewReason = null;
+            }
+            outcome = await deps.store.appendMessage({ ...base, threadId }, { threadId, expectedState: existing.state, patch });
+        }
+        else {
+            threadId = (0, internal_1.newId)(deps);
+            const thread = {
+                id: threadId,
+                mailbox,
+                state: isNoise ? "ignored" : "new",
+                subjectKey: (0, subject_1.normalizeSubject)(subject),
+                subject: subject || "(no subject)",
+                customerAddress: customer,
+                participants: people,
+                createdAt: (0, internal_1.nowIso)(deps),
+                lastActivityAt: receivedAt,
+                latestInboundId: isNoise ? null : item.id,
+                reviewReason: null,
+                autoReplyCount: 0,
+                relatedThreadId: existing?.id ?? null,
+                dismissedBy: null,
+            };
+            outcome = await deps.store.createThread(thread, { ...base, threadId });
+        }
+        if (outcome === "stale")
+            continue;
+        if (outcome === "duplicate") {
+            result.duplicates++;
+            const stored = await deps.store.getMessage(mailbox, item.id);
+            if (stored)
+                await reconcileExisting(deps, stored, result);
+            return;
+        }
+        if (outcome === "created")
+            result.created++;
+        else
+            result.appended++;
+        if (isNoise) {
+            result.ignored++;
+            return;
+        }
+        const stored = { ...base, threadId };
+        if ((await (0, drafting_1.startDraftFor)(deps, threadId, stored)) === "started")
+            result.draftsStarted++;
+        return;
+    }
+    throw new errors_1.StaleThreadError(item.id);
+}
+function headerRefs(headers) {
+    return [headers.inReplyTo, ...headers.references]
+        .map(threading_1.normalizeMessageId)
+        .filter((x) => x !== null);
+}
+async function recordBounce(deps, mailbox, message, refs, result) {
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        const thread = await (0, bounce_1.matchBounce)(deps.store, { mailbox, refs, conversationId: message.conversationId });
+        if (!thread)
+            return false;
+        const failed = (0, states_1.canTransition)(thread.state, "bounce");
+        const patch = failed
+            ? { state: (0, states_1.transition)(thread.state, "bounce"), reviewReason: "delivery_failed", lastActivityAt: message.receivedAt }
+            : {};
+        const outcome = await deps.store.appendMessage({ ...message, threadId: thread.id }, { threadId: thread.id, expectedState: thread.state, patch });
+        if (outcome === "stale")
+            continue;
+        if (outcome === "duplicate") {
+            result.duplicates++;
+            return true;
+        }
+        result.appended++;
+        result.ignored++;
+        if (failed) {
+            result.deliveryFailures++;
+            await (0, internal_1.notify)(deps, { type: "review_needed", threadId: thread.id, mailbox, subject: thread.subject, reason: "delivery_failed" });
+        }
+        return true;
+    }
+    throw new errors_1.StaleThreadError(message.id);
+}
+async function processItem(deps, gateway, mailbox, item, state, result) {
+    if (item.removed) {
+        const stored = await deps.store.getMessage(mailbox, item.id);
+        if (stored)
+            await deps.store.markMessageRemoved(mailbox, item.id, (0, internal_1.nowIso)(deps));
+        result.removed++;
+        return;
+    }
+    if (item.isDraft) {
+        result.skippedDrafts++;
+        return;
+    }
+    if (item.from?.address.trim().toLowerCase() === mailbox.trim().toLowerCase()) {
+        result.skippedOwn++;
+        return;
+    }
+    const stored = await deps.store.getMessage(mailbox, item.id);
+    if (stored) {
+        result.unchanged++;
+        await reconcileExisting(deps, stored, result);
+        return;
+    }
+    await processNew(deps, gateway, mailbox, item, state, result);
+}
+async function ingestPage(deps, mailbox) {
+    const controls = await (0, controls_1.loadControls)(deps);
+    if (controls.paused)
+        return (0, controls_1.paused)();
+    const gateway = (0, controls_1.mailboxAccess)(deps, controls, mailbox).gateway();
+    const state = await deps.store.getSyncState(mailbox);
+    if (!state)
+        throw new errors_1.MailboxNotConnectedError(mailbox);
+    const { page, restarted } = await fetchPage(deps, gateway, state);
+    const link = page.nextLink ?? page.deltaLink;
+    if (!link)
+        throw new errors_1.InvalidDeltaPageError();
+    const result = emptyResult();
+    result.restarted = restarted;
+    result.fetched = page.items.length;
+    const stamp = (i) => i.receivedDateTime ?? "";
+    const live = page.items.filter((i) => !i.removed).sort((a, b) => stamp(a).localeCompare(stamp(b)));
+    const gone = page.items.filter((i) => i.removed);
+    let newest = state.lastReceivedAt;
+    for (const item of [...live, ...gone]) {
+        await processItem(deps, gateway, mailbox, item, state, result);
+        if (item.receivedDateTime && (!newest || item.receivedDateTime > newest)) {
+            newest = item.receivedDateTime;
+        }
+    }
+    await deps.store.saveSyncState(mailbox, { ...state, link, lastReceivedAt: newest });
+    result.hasMore = page.nextLink !== null;
+    return result;
+}
+async function syncMailbox(deps, mailbox, options = {}) {
+    const results = [];
+    try {
+        for (let i = 0; i < (options.maxPages ?? 20); i++) {
+            const r = await ingestPage(deps, mailbox);
+            if ((0, controls_1.isPaused)(r))
+                return results.length ? results : r;
+            results.push(r);
+            if (!r.hasMore)
+                break;
+        }
+    }
+    catch (err) {
+        if (!(0, errors_1.isTransientMailError)(err))
+            throw err;
+        return recordSyncFailure(deps, mailbox, err);
+    }
+    await clearSyncFailure(deps, mailbox);
+    return results;
+}
+exports.SYNC_FAILING_AFTER = 3;
+async function recordSyncFailure(deps, mailbox, err) {
+    const state = await deps.store.getSyncState(mailbox);
+    const failingSince = state?.failingSince ?? (0, internal_1.nowIso)(deps);
+    const failures = (state?.failures ?? 0) + 1;
+    const error = (0, internal_1.errorText)(err).slice(0, 300);
+    if (state)
+        await deps.store.saveSyncState(mailbox, { ...state, failingSince, failures, lastError: error });
+    if (failures === exports.SYNC_FAILING_AFTER)
+        await (0, internal_1.notify)(deps, { type: "sync_failing", mailbox, since: failingSince });
+    return { status: "failing", failures, failingSince, error };
+}
+async function clearSyncFailure(deps, mailbox) {
+    const state = await deps.store.getSyncState(mailbox);
+    if (!state || !state.failures)
+        return;
+    await deps.store.saveSyncState(mailbox, { ...state, failingSince: null, failures: 0, lastError: null });
+    if (state.failures >= exports.SYNC_FAILING_AFTER && state.failingSince) {
+        await (0, internal_1.notify)(deps, { type: "sync_recovered", mailbox, since: state.failingSince });
+    }
+}
+function isSyncFailing(value) {
+    return typeof value === "object" && value !== null && value.status === "failing";
+}

package/dist/internal.d.ts

@@ -0,0 +1,8 @@
+import { type TicketEvent } from "./states";
+import type { HelpdeskDeps, HelpdeskNotification, Thread, ThreadPatch } from "./types";
+export declare const newId: (deps: HelpdeskDeps) => string;
+export declare const nowIso: (deps: HelpdeskDeps) => string;
+export declare function errorText(err: unknown): string;
+export declare function notify(deps: HelpdeskDeps, event: HelpdeskNotification): Promise<void>;
+export declare function loadThread(deps: HelpdeskDeps, threadId: string): Promise<Thread>;
+export declare function applyEvents(deps: HelpdeskDeps, thread: Thread, events: TicketEvent[], patch?: ThreadPatch): Promise<Thread>;

package/dist/internal.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nowIso = exports.newId = void 0;
+exports.errorText = errorText;
+exports.notify = notify;
+exports.loadThread = loadThread;
+exports.applyEvents = applyEvents;
+const node_crypto_1 = require("node:crypto");
+const errors_1 = require("./errors");
+const states_1 = require("./states");
+const newId = (deps) => (deps.newId ?? node_crypto_1.randomUUID)();
+exports.newId = newId;
+const nowIso = (deps) => deps.clock.now().toISOString();
+exports.nowIso = nowIso;
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function notify(deps, event) {
+    try {
+        await deps.notifier?.notify(event);
+    }
+    catch {
+    }
+}
+async function loadThread(deps, threadId) {
+    const thread = await deps.store.getThread(threadId);
+    if (!thread)
+        throw new errors_1.ThreadNotFoundError(threadId);
+    return thread;
+}
+async function applyEvents(deps, thread, events, patch = {}) {
+    let state = thread.state;
+    for (const event of events)
+        state = (0, states_1.transition)(state, event);
+    const full = { ...patch, state, lastActivityAt: patch.lastActivityAt ?? (0, exports.nowIso)(deps) };
+    const ok = await deps.store.updateThread({
+        threadId: thread.id,
+        expectedState: thread.state,
+        patch: full,
+    });
+    if (!ok)
+        throw new errors_1.StaleThreadError(thread.id);
+    return { ...thread, ...full, state };
+}