@dxv-systems/helpdesk 0.0.0-stage → 0.2.0

package/dist/drafting.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.currentReplyRun = currentReplyRun;
+exports.ensureDraft = ensureDraft;
+exports.startDraftFor = startDraftFor;
+exports.completeDraft = completeDraft;
+exports.regenerateDraft = regenerateDraft;
+exports.editDraft = editDraft;
+exports.sweepStuckDrafts = sweepStuckDrafts;
+exports.unignoreThread = unignoreThread;
+const controls_1 = require("./controls");
+const errors_1 = require("./errors");
+const internal_1 = require("./internal");
+const states_1 = require("./states");
+const DEFAULT_MIN_CONFIDENCE = 0.7;
+const DEFAULT_RESUME_DRAFT_MS = 2 * 60 * 1000;
+const DEFAULT_DRAFT_TIMEOUT_MS = 15 * 60 * 1000;
+const inFlight = (run) => run.status === "requested" || run.status === "started";
+function currentReplyRun(deps, thread, run) {
+    if (!run || run.status === "failed")
+        return null;
+    if (!deps.drafter && run.inboundMessageId !== thread.latestInboundId)
+        return null;
+    return run;
+}
+function reviewReasonFor(deps, thread, run) {
+    if (run.status === "failed")
+        return "drafter_failed";
+    if (thread.latestInboundId !== run.inboundMessageId)
+        return "stale_draft";
+    if ((run.confidence ?? 0) < (deps.config.minConfidence ?? DEFAULT_MIN_CONFIDENCE)) {
+        return "low_confidence";
+    }
+    return "policy";
+}
+async function moveToReview(deps, thread, run) {
+    const events = thread.state === "new" ? ["draft", "needs_review"] : ["needs_review"];
+    const reason = reviewReasonFor(deps, thread, run);
+    const updated = await (0, internal_1.applyEvents)(deps, thread, events, { reviewReason: reason });
+    await (0, internal_1.notify)(deps, { type: "review_needed", threadId: thread.id, mailbox: thread.mailbox, subject: thread.subject, reason });
+    return updated;
+}
+async function failRun(deps, run, error) {
+    const failed = await deps.store.updateDraftRun(run.idempotencyKey, { status: "failed", error });
+    const thread = await (0, internal_1.loadThread)(deps, run.threadId);
+    if (thread.state === "new" || thread.state === "drafted")
+        await moveToReview(deps, thread, failed);
+}
+async function startRun(deps, run, message) {
+    if (!deps.drafter)
+        return failRun(deps, run, "no drafter configured");
+    try {
+        const { runId } = await deps.drafter.start({
+            idempotencyKey: run.idempotencyKey,
+            mailbox: run.mailbox,
+            threadId: run.threadId,
+            messageId: run.inboundMessageId,
+            conversationId: message.conversationId,
+            subject: message.subject,
+            from: message.fromAddress,
+        });
+        await deps.store.updateDraftRun(run.idempotencyKey, { status: "started", externalRunId: runId });
+    }
+    catch (err) {
+        await failRun(deps, run, (0, internal_1.errorText)(err));
+    }
+}
+function newRun(deps, thread, messageId, generation) {
+    return {
+        mailbox: thread.mailbox,
+        threadId: thread.id,
+        inboundMessageId: messageId,
+        generation,
+        idempotencyKey: `draft:${thread.mailbox}:${messageId}:${generation}`,
+        status: "requested",
+        externalRunId: null,
+        requestedAt: (0, internal_1.nowIso)(deps),
+        error: null,
+        text: null,
+        confidence: null,
+        reason: null,
+        category: null,
+        placedDraftId: null,
+        placedBodyHtml: null,
+        commentText: null,
+    };
+}
+async function ensureDraft(deps, threadId, message) {
+    if ((await (0, controls_1.loadControls)(deps)).paused)
+        return "paused";
+    return startDraftFor(deps, threadId, message);
+}
+async function startDraftFor(deps, threadId, message) {
+    const thread = await (0, internal_1.loadThread)(deps, threadId);
+    (0, controls_1.assertInScope)(deps.config, thread.mailbox);
+    if (thread.state === "drafted") {
+        const latest = await deps.store.getLatestDraftRunForThread(thread.id);
+        if (latest && !inFlight(latest))
+            await moveToReview(deps, thread, latest);
+        return "exists";
+    }
+    if (thread.state !== "new" || thread.latestInboundId !== message.id)
+        return "not_needed";
+    if (!deps.drafter) {
+        await (0, internal_1.applyEvents)(deps, thread, ["draft", "needs_review"], { reviewReason: "no_draft" });
+        await (0, internal_1.notify)(deps, { type: "review_needed", threadId: thread.id, mailbox: thread.mailbox, subject: thread.subject, reason: "no_draft" });
+        return "no_drafter";
+    }
+    const existing = await deps.store.getLatestDraftRun(thread.mailbox, message.id);
+    if (existing) {
+        const age = deps.clock.now().getTime() - Date.parse(existing.requestedAt);
+        const resumeAfter = deps.config.resumeDraftAfterMs ?? DEFAULT_RESUME_DRAFT_MS;
+        if (existing.status === "requested" && age >= resumeAfter) {
+            await startRun(deps, existing, message);
+            return "started";
+        }
+        return "exists";
+    }
+    const active = await deps.store.getLatestDraftRunForThread(thread.id);
+    if (active && inFlight(active))
+        return "busy";
+    const { created, run } = await deps.store.createDraftRunIfAbsent(newRun(deps, thread, message.id, 1));
+    if (!created)
+        return "exists";
+    await startRun(deps, run, message);
+    return "started";
+}
+async function completeDraft(deps, input) {
+    if ((await (0, controls_1.loadControls)(deps)).paused)
+        return (0, controls_1.paused)();
+    (0, controls_1.assertInScope)(deps.config, input.mailbox);
+    const run = await deps.store.getLatestDraftRun(input.mailbox, input.inboundMessageId);
+    if (!run)
+        throw new errors_1.DraftNotReadyError(input.inboundMessageId, "no draft run recorded");
+    if (run.idempotencyKey !== input.idempotencyKey)
+        return run;
+    if (!inFlight(run))
+        return run;
+    const { result } = input;
+    if (!result.ok) {
+        await failRun(deps, run, result.error);
+        return deps.store.updateDraftRun(run.idempotencyKey, {});
+    }
+    const current = await deps.store.updateDraftRun(run.idempotencyKey, {
+        status: "succeeded",
+        text: result.text,
+        commentText: result.text,
+        confidence: result.confidence,
+        reason: result.reason,
+        category: result.category ?? null,
+    });
+    const thread = await (0, internal_1.loadThread)(deps, run.threadId);
+    if (thread.state === "new" || thread.state === "drafted")
+        await moveToReview(deps, thread, current);
+    return current;
+}
+async function regenerateDraft(deps, threadId) {
+    if ((await (0, controls_1.loadControls)(deps)).paused)
+        return (0, controls_1.paused)();
+    const thread = await (0, internal_1.loadThread)(deps, threadId);
+    (0, controls_1.assertInScope)(deps.config, thread.mailbox);
+    if (!deps.drafter)
+        throw new errors_1.DraftNotReadyError(threadId, "no drafter configured");
+    if (!thread.latestInboundId)
+        throw new errors_1.DraftNotReadyError(threadId, "no inbound message");
+    const message = await deps.store.getMessage(thread.mailbox, thread.latestInboundId);
+    if (!message)
+        throw new errors_1.DraftNotReadyError(threadId, "inbound message not stored");
+    const latest = await deps.store.getLatestDraftRun(thread.mailbox, message.id);
+    await (0, internal_1.applyEvents)(deps, thread, ["redraft"], { reviewReason: null });
+    const { created, run } = await deps.store.createDraftRunIfAbsent(newRun(deps, thread, message.id, (latest?.generation ?? 0) + 1));
+    if (created)
+        await startRun(deps, run, message);
+    return run;
+}
+async function writeStaffReply(deps, thread, text) {
+    const inboundId = thread.latestInboundId;
+    if (!inboundId)
+        throw new errors_1.DraftNotReadyError(thread.id, "no inbound message");
+    (0, states_1.transition)(thread.state, "redraft");
+    const latest = await deps.store.getLatestDraftRun(thread.mailbox, inboundId);
+    const { run } = await deps.store.createDraftRunIfAbsent({
+        ...newRun(deps, thread, inboundId, (latest?.generation ?? 0) + 1),
+        status: "succeeded",
+        reason: "staff",
+        commentText: text,
+    });
+    if (run.status !== "succeeded")
+        throw new errors_1.DraftNotReadyError(thread.id, "a draft is being written");
+    const current = await deps.store.updateDraftRun(run.idempotencyKey, { commentText: text });
+    await (0, internal_1.applyEvents)(deps, thread, ["redraft", "needs_review"], { reviewReason: "staff_edited" });
+    return current;
+}
+async function editDraft(deps, input) {
+    if ((await (0, controls_1.loadControls)(deps)).paused)
+        return (0, controls_1.paused)();
+    const thread = await (0, internal_1.loadThread)(deps, input.threadId);
+    (0, controls_1.assertInScope)(deps.config, thread.mailbox);
+    if (input.text.trim() === "")
+        throw new errors_1.EmptyReplyError(thread.id);
+    const run = currentReplyRun(deps, thread, await deps.store.getLatestDraftRunForThread(thread.id));
+    if (!run)
+        return writeStaffReply(deps, thread, input.text);
+    if (run.status !== "succeeded")
+        throw new errors_1.DraftNotReadyError(thread.id, "no draft text to edit");
+    (0, states_1.transition)(thread.state, "redraft");
+    const updated = await deps.store.updateDraftRun(run.idempotencyKey, { commentText: input.text });
+    await (0, internal_1.applyEvents)(deps, thread, ["redraft", "needs_review"], { reviewReason: "staff_edited" });
+    return updated;
+}
+async function sweepStuckDrafts(deps, mailbox) {
+    if ((await (0, controls_1.loadControls)(deps)).paused)
+        return (0, controls_1.paused)();
+    (0, controls_1.assertInScope)(deps.config, mailbox);
+    const timeout = deps.config.draftTimeoutMs ?? DEFAULT_DRAFT_TIMEOUT_MS;
+    const cutoff = new Date(deps.clock.now().getTime() - timeout).toISOString();
+    let failed = 0;
+    for (const listed of await deps.store.listInFlightDraftRuns(mailbox, cutoff)) {
+        const run = await deps.store.getLatestDraftRun(mailbox, listed.inboundMessageId);
+        if (!run || run.idempotencyKey !== listed.idempotencyKey || !inFlight(run))
+            continue;
+        await failRun(deps, run, "no report from the drafter in time");
+        failed++;
+    }
+    return failed;
+}
+async function unignoreThread(deps, threadId) {
+    if ((await (0, controls_1.loadControls)(deps)).paused)
+        return (0, controls_1.paused)();
+    const thread = await (0, internal_1.loadThread)(deps, threadId);
+    (0, controls_1.assertInScope)(deps.config, thread.mailbox);
+    (0, states_1.transition)(thread.state, "unignore");
+    const message = await deps.store.getLatestMessageForThread(thread.id);
+    if (!message)
+        throw new errors_1.DraftNotReadyError(thread.id, "thread has no message");
+    const updated = await (0, internal_1.applyEvents)(deps, thread, ["unignore"], {
+        latestInboundId: message.id,
+        reviewReason: null,
+        dismissedBy: null,
+    });
+    await startDraftFor(deps, thread.id, message);
+    return updated;
+}

package/dist/errors.d.ts

@@ -0,0 +1,60 @@
+import type { TicketState } from "./types";
+export declare class HelpdeskError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class InvalidTransitionError extends HelpdeskError {
+    readonly from: TicketState;
+    readonly event: string;
+    constructor(from: TicketState, event: string);
+}
+export declare class StaleThreadError extends HelpdeskError {
+    constructor(threadId: string);
+}
+export declare class MailboxNotConnectedError extends HelpdeskError {
+    constructor(mailbox: string);
+}
+export declare class InvalidDeltaPageError extends HelpdeskError {
+    constructor();
+}
+export declare class DeltaLinkExpiredError extends HelpdeskError {
+    constructor(message?: string);
+}
+export declare class DraftNotReadyError extends HelpdeskError {
+    constructor(threadId: string, why: string);
+}
+export declare class EmptyReplyError extends HelpdeskError {
+    constructor(threadId: string);
+}
+export declare class StaleDraftError extends HelpdeskError {
+    constructor(threadId: string);
+}
+export declare class MailboxNotInScopeError extends HelpdeskError {
+    readonly mailbox: string;
+    constructor(mailbox: string);
+}
+export declare class MailboxWriteBlockedError extends HelpdeskError {
+    readonly mailbox: string;
+    readonly mode: string;
+    readonly operation: string;
+    constructor(mailbox: string, mode: string, operation: string);
+}
+export declare class SendPendingError extends HelpdeskError {
+    readonly sendStatus: "sending" | "unknown";
+    constructor(threadId: string, sendStatus: "sending" | "unknown");
+}
+export declare class AttachmentsUnavailableError extends HelpdeskError {
+    constructor();
+}
+export declare class AttachmentLimitError extends HelpdeskError {
+    readonly limit: "count" | "size";
+    constructor(limit: "count" | "size");
+}
+export declare class ReplyAttachmentNotFoundError extends HelpdeskError {
+    constructor(id: string);
+}
+export declare class ThreadNotFoundError extends HelpdeskError {
+    constructor(threadId: string);
+}
+export declare function isDeltaLinkExpired(err: unknown): boolean;
+export declare function isTransientMailError(err: unknown): boolean;

package/dist/errors.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThreadNotFoundError = exports.ReplyAttachmentNotFoundError = exports.AttachmentLimitError = exports.AttachmentsUnavailableError = exports.SendPendingError = exports.MailboxWriteBlockedError = exports.MailboxNotInScopeError = exports.StaleDraftError = exports.EmptyReplyError = exports.DraftNotReadyError = exports.DeltaLinkExpiredError = exports.InvalidDeltaPageError = exports.MailboxNotConnectedError = exports.StaleThreadError = exports.InvalidTransitionError = exports.HelpdeskError = void 0;
+exports.isDeltaLinkExpired = isDeltaLinkExpired;
+exports.isTransientMailError = isTransientMailError;
+class HelpdeskError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+exports.HelpdeskError = HelpdeskError;
+class InvalidTransitionError extends HelpdeskError {
+    constructor(from, event) {
+        super("invalid_transition", `Cannot apply "${event}" to a ticket in state "${from}"`);
+        this.from = from;
+        this.event = event;
+    }
+}
+exports.InvalidTransitionError = InvalidTransitionError;
+class StaleThreadError extends HelpdeskError {
+    constructor(threadId) {
+        super("stale_thread", `Thread ${threadId} changed while it was being updated`);
+    }
+}
+exports.StaleThreadError = StaleThreadError;
+class MailboxNotConnectedError extends HelpdeskError {
+    constructor(mailbox) {
+        super("mailbox_not_connected", `Mailbox ${mailbox} has no sync state; connect it first`);
+    }
+}
+exports.MailboxNotConnectedError = MailboxNotConnectedError;
+class InvalidDeltaPageError extends HelpdeskError {
+    constructor() {
+        super("invalid_delta_page", "Delta page has neither nextLink nor deltaLink");
+    }
+}
+exports.InvalidDeltaPageError = InvalidDeltaPageError;
+class DeltaLinkExpiredError extends HelpdeskError {
+    constructor(message = "Delta link expired") {
+        super("delta_link_expired", message);
+    }
+}
+exports.DeltaLinkExpiredError = DeltaLinkExpiredError;
+class DraftNotReadyError extends HelpdeskError {
+    constructor(threadId, why) {
+        super("draft_not_ready", `Thread ${threadId} has no sendable draft: ${why}`);
+    }
+}
+exports.DraftNotReadyError = DraftNotReadyError;
+class EmptyReplyError extends HelpdeskError {
+    constructor(threadId) {
+        super("empty_reply", `Thread ${threadId} has an empty reply text; refusing to send`);
+    }
+}
+exports.EmptyReplyError = EmptyReplyError;
+class StaleDraftError extends HelpdeskError {
+    constructor(threadId) {
+        super("stale_draft", `Thread ${threadId} received newer mail after this draft; pass acceptStale to send anyway`);
+    }
+}
+exports.StaleDraftError = StaleDraftError;
+class MailboxNotInScopeError extends HelpdeskError {
+    constructor(mailbox) {
+        super("mailbox_not_in_scope", `Mailbox ${mailbox} is not one of this helpdesk's mailboxes`);
+        this.mailbox = mailbox;
+    }
+}
+exports.MailboxNotInScopeError = MailboxNotInScopeError;
+class MailboxWriteBlockedError extends HelpdeskError {
+    constructor(mailbox, mode, operation) {
+        super("mailbox_write_blocked", `${operation} on ${mailbox} is not allowed in write mode ${mode}`);
+        this.mailbox = mailbox;
+        this.mode = mode;
+        this.operation = operation;
+    }
+}
+exports.MailboxWriteBlockedError = MailboxWriteBlockedError;
+class SendPendingError extends HelpdeskError {
+    constructor(threadId, sendStatus) {
+        super(sendStatus === "sending" ? "send_in_progress" : "send_outcome_unknown", `Thread ${threadId} has a send that is ${sendStatus === "sending" ? "under way" : "of unknown outcome"}`);
+        this.sendStatus = sendStatus;
+    }
+}
+exports.SendPendingError = SendPendingError;
+class AttachmentsUnavailableError extends HelpdeskError {
+    constructor() {
+        super("attachments_unavailable", "This app cannot add files to replies");
+    }
+}
+exports.AttachmentsUnavailableError = AttachmentsUnavailableError;
+class AttachmentLimitError extends HelpdeskError {
+    constructor(limit) {
+        super("attachment_limit", limit === "count" ? "Too many files on this reply" : "The files on this reply are too large together");
+        this.limit = limit;
+    }
+}
+exports.AttachmentLimitError = AttachmentLimitError;
+class ReplyAttachmentNotFoundError extends HelpdeskError {
+    constructor(id) {
+        super("reply_attachment_not_found", `Reply attachment ${id} does not exist or was already sent`);
+    }
+}
+exports.ReplyAttachmentNotFoundError = ReplyAttachmentNotFoundError;
+class ThreadNotFoundError extends HelpdeskError {
+    constructor(threadId) {
+        super("thread_not_found", `Thread ${threadId} does not exist`);
+    }
+}
+exports.ThreadNotFoundError = ThreadNotFoundError;
+const EXPIRED_NAMES = new Set(["DeltaLinkExpiredError", "GraphDeltaExpiredError"]);
+const EXPIRED_CODES = new Set(["delta_link_expired", "syncStateNotFound", "resyncRequired"]);
+function isDeltaLinkExpired(err) {
+    if (err instanceof DeltaLinkExpiredError)
+        return true;
+    const e = err;
+    if (!e || typeof e !== "object")
+        return false;
+    return ((typeof e.name === "string" && EXPIRED_NAMES.has(e.name)) ||
+        (typeof e.code === "string" && EXPIRED_CODES.has(e.code)) ||
+        e.status === 410);
+}
+function isTransientMailError(err) {
+    const e = err;
+    if (!e || typeof e !== "object")
+        return false;
+    if (e.name === "TimeoutError" || e.name === "AbortError")
+        return true;
+    if (typeof e.status !== "number")
+        return false;
+    return e.status === 0 || e.status === 408 || e.status === 429 || e.status >= 500;
+}

package/dist/inbox/handlers.d.ts

@@ -0,0 +1,36 @@
+import type { HelpdeskDeps, StoredMessage, Thread, TicketState } from "../types";
+import type { HelpdeskStaff, InboxPerson } from "./types";
+export declare const MAX_ATTACHMENT_DOWNLOAD_BYTES: number;
+export declare function contentDisposition(name: string): string;
+export interface InboxThreadQuery {
+    states: TicketState[] | null;
+    mailbox: string | null;
+    assigneeId?: string | null;
+    cursor: string | null;
+    limit: number;
+}
+export interface HelpdeskInboxQueries {
+    listThreads(query: InboxThreadQuery): Promise<{
+        rows: Array<{
+            thread: Thread;
+            assignee: InboxPerson | null;
+        }>;
+        nextCursor: string | null;
+    }>;
+    listMessages(threadId: string): Promise<StoredMessage[]>;
+    getAssignee(threadId: string): Promise<InboxPerson | null>;
+    setAssignee(threadId: string, assignee: InboxPerson | null): Promise<void>;
+}
+export interface HelpdeskHandlersConfig {
+    deps: HelpdeskDeps;
+    inbox: HelpdeskInboxQueries;
+    getStaff(request: Request): Promise<HelpdeskStaff | null>;
+    isProduction: boolean;
+    basePath?: string;
+    appOrigin?: string;
+    onError?(error: unknown): void;
+}
+export interface HelpdeskHandlers {
+    handle(request: Request): Promise<Response>;
+}
+export declare function createHelpdeskHandlers(config: HelpdeskHandlersConfig): HelpdeskHandlers;