@dxv-systems/helpdesk 0.0.0-stage → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,339 @@
+export interface MailAddress {
+    address: string;
+    name?: string;
+}
+export interface MessageBody {
+    contentType: "html" | "text";
+    content: string;
+}
+export interface InternetMessageHeader {
+    name: string;
+    value: string;
+}
+export type AttachmentKind = "file" | "item" | "reference";
+export interface AttachmentInfo {
+    id: string;
+    name: string;
+    contentType: string;
+    size: number;
+    isInline: boolean;
+    kind: AttachmentKind;
+}
+export interface MessageSummary {
+    id: string;
+    subject?: string;
+    from?: MailAddress;
+    receivedDateTime?: string;
+    internetMessageId?: string;
+    conversationId?: string;
+    isRead?: boolean;
+    isDraft?: boolean;
+    categories?: string[];
+    hasAttachments?: boolean;
+}
+export interface DeltaItem extends MessageSummary {
+    removed: boolean;
+    removedReason?: string;
+}
+export interface DeltaPage {
+    items: DeltaItem[];
+    nextLink: string | null;
+    deltaLink: string | null;
+}
+export interface DeltaOptions {
+    folderId?: string;
+    link?: string;
+    since?: Date | string;
+    pageSize?: number;
+}
+export interface Message extends MessageSummary {
+    body: MessageBody;
+    sentDateTime?: string;
+    toRecipients: MailAddress[];
+    ccRecipients: MailAddress[];
+    replyTo: MailAddress[];
+    internetMessageHeaders?: InternetMessageHeader[];
+    inReplyTo?: string;
+    references?: string[];
+}
+export interface GetMessageOptions {
+    bodyType?: "html" | "text";
+    includeHeaders?: boolean;
+}
+export interface CreateReplyOptions {
+    replyAll?: boolean;
+    comment?: string;
+}
+export interface MailboxGateway {
+    readonly address: string;
+    delta(options: DeltaOptions): Promise<DeltaPage>;
+    getMessage(id: string, options?: GetMessageOptions): Promise<Message | null>;
+    createReply(messageId: string, options?: CreateReplyOptions): Promise<Message>;
+    updateDraftBody(draftId: string, body: MessageBody): Promise<void>;
+    sendDraft(draftId: string): Promise<void>;
+    listAttachments?(messageId: string): Promise<AttachmentInfo[]>;
+    downloadAttachment?(messageId: string, attachmentId: string): Promise<Uint8Array>;
+    addAttachment?(draftId: string, attachment: {
+        name: string;
+        contentType: string;
+        content: Uint8Array;
+    }): Promise<unknown>;
+}
+export interface Clock {
+    now(): Date;
+}
+export interface ReplyAttachment {
+    id: string;
+    threadId: string;
+    mailbox: string;
+    fileId: string;
+    name: string;
+    contentType: string;
+    size: number;
+    addedBy: string;
+    createdAt: string;
+    placedDraftId: string | null;
+    sentIntentId: string | null;
+}
+export type ReplyAttachmentPatch = Partial<Pick<ReplyAttachment, "placedDraftId" | "sentIntentId">>;
+export interface ReplyAttachmentStore {
+    add(attachment: ReplyAttachment): Promise<void>;
+    listForThread(threadId: string): Promise<ReplyAttachment[]>;
+    update(id: string, patch: ReplyAttachmentPatch): Promise<void>;
+    removeUnsent(id: string): Promise<ReplyAttachment | null>;
+}
+export interface StoredReplyFile {
+    fileId: string;
+    name: string;
+    contentType: string;
+    size: number;
+}
+export interface ReplyFiles {
+    createUpload(input: {
+        staffId: string;
+        name: string;
+        contentType: string;
+        size: number;
+    }): Promise<{
+        uploadUrl: string;
+        uploadToken: string;
+        contentType: string;
+    }>;
+    completeUpload(input: {
+        staffId: string;
+        uploadToken: string;
+    }): Promise<StoredReplyFile>;
+    read(input: {
+        fileId: string;
+        staffId: string;
+    }): Promise<Uint8Array>;
+    remove(input: {
+        fileId: string;
+        staffId: string;
+    }): Promise<void>;
+}
+export interface ReplyAttachmentsDeps {
+    store: ReplyAttachmentStore;
+    files: ReplyFiles;
+}
+export type TicketState = "new" | "ignored" | "drafted" | "review" | "sent" | "waiting" | "closed";
+export type ReviewReason = "low_confidence" | "policy" | "stale_draft" | "drafter_failed" | "staff_edited" | "no_draft" | "delivery_failed";
+export interface Thread {
+    id: string;
+    mailbox: string;
+    state: TicketState;
+    subjectKey: string;
+    subject: string;
+    customerAddress: string;
+    participants: string[];
+    createdAt: string;
+    lastActivityAt: string;
+    latestInboundId: string | null;
+    reviewReason: ReviewReason | null;
+    autoReplyCount: number;
+    relatedThreadId: string | null;
+    dismissedBy: string | null;
+}
+export type ThreadPatch = Partial<Pick<Thread, "state" | "participants" | "lastActivityAt" | "latestInboundId" | "reviewReason" | "autoReplyCount" | "dismissedBy">>;
+export interface ThreadUpdate {
+    threadId: string;
+    expectedState: TicketState;
+    patch: ThreadPatch;
+}
+export type NoiseReason = "auto_submitted" | "precedence" | "bounce" | "out_of_office" | "mailing_list" | "machine_sender" | "own_address" | "connected_mailbox" | "none";
+export interface StoredMessage {
+    id: string;
+    mailbox: string;
+    threadId: string;
+    internetMessageId: string | null;
+    conversationId: string | null;
+    subject: string;
+    fromAddress: string;
+    receivedAt: string;
+    noise: {
+        action: "ignore" | "process";
+        reason: NoiseReason;
+    };
+    suppressAutoResponse: boolean;
+    removedAt: string | null;
+}
+export interface SyncState {
+    link: string | null;
+    connectedAt: string;
+    lastReceivedAt: string | null;
+    failingSince?: string | null;
+    failures?: number;
+    lastError?: string | null;
+}
+export interface SyncFailing {
+    status: "failing";
+    failures: number;
+    failingSince: string;
+    error: string;
+}
+export type DraftRunStatus = "requested" | "started" | "succeeded" | "failed";
+export interface DraftRun {
+    mailbox: string;
+    threadId: string;
+    inboundMessageId: string;
+    generation: number;
+    idempotencyKey: string;
+    status: DraftRunStatus;
+    externalRunId: string | null;
+    requestedAt: string;
+    error: string | null;
+    text: string | null;
+    confidence: number | null;
+    reason: string | null;
+    category: string | null;
+    placedDraftId: string | null;
+    placedBodyHtml: string | null;
+    commentText: string | null;
+}
+export type SendStatus = "intended" | "sending" | "sent" | "failed" | "unknown";
+export interface SendIntent {
+    id: string;
+    mailbox: string;
+    threadId: string;
+    draftId: string | null;
+    approvedBy: string;
+    status: SendStatus;
+    createdAt: string;
+    updatedAt: string;
+    error: string | null;
+}
+export type SendIntentPatch = Partial<Pick<SendIntent, "status" | "updatedAt" | "error" | "draftId">>;
+export interface HelpdeskStore {
+    getSyncState(mailbox: string): Promise<SyncState | null>;
+    saveSyncState(mailbox: string, state: SyncState): Promise<void>;
+    getMessage(mailbox: string, id: string): Promise<StoredMessage | null>;
+    markMessageRemoved(mailbox: string, id: string, at: string): Promise<void>;
+    getThread(id: string): Promise<Thread | null>;
+    getLatestMessageForThread(threadId: string): Promise<StoredMessage | null>;
+    findThreadsByConversationId(mailbox: string, conversationId: string): Promise<Thread[]>;
+    findMessageThreads(mailbox: string, internetMessageIds: string[]): Promise<Array<{
+        threadId: string;
+        internetMessageId: string;
+    }>>;
+    findThreadsBySubjectKey(mailbox: string, subjectKey: string, activeSince: string): Promise<Thread[]>;
+    createThread(thread: Thread, firstMessage: StoredMessage): Promise<"created" | "duplicate">;
+    appendMessage(message: StoredMessage, update: ThreadUpdate): Promise<"appended" | "duplicate" | "stale">;
+    updateThread(update: ThreadUpdate): Promise<boolean>;
+    createDraftRunIfAbsent(run: DraftRun): Promise<{
+        created: boolean;
+        run: DraftRun;
+    }>;
+    getLatestDraftRun(mailbox: string, inboundMessageId: string): Promise<DraftRun | null>;
+    getLatestDraftRunForThread(threadId: string): Promise<DraftRun | null>;
+    listInFlightDraftRuns(mailbox: string, olderThan: string): Promise<DraftRun[]>;
+    updateDraftRun(key: string, patch: Partial<Omit<DraftRun, "idempotencyKey">>): Promise<DraftRun>;
+    listSendIntentsByStatus?(mailbox: string, status: SendStatus): Promise<SendIntent[]>;
+    createSendIntentIfAbsent(intent: SendIntent): Promise<{
+        created: boolean;
+        intent: SendIntent;
+    }>;
+    getSendIntent(id: string): Promise<SendIntent | null>;
+    transitionSendIntent(id: string, from: SendStatus[], patch: SendIntentPatch): Promise<SendIntent | null>;
+}
+export interface DraftRequest {
+    idempotencyKey: string;
+    mailbox: string;
+    threadId: string;
+    messageId: string;
+    conversationId: string | null;
+    subject: string;
+    from: string;
+}
+export type DraftResult = {
+    ok: true;
+    text: string;
+    confidence: number;
+    reason: string;
+    category?: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface Drafter {
+    start(request: DraftRequest): Promise<{
+        runId: string;
+    }>;
+}
+export type HelpdeskNotification = {
+    type: "review_needed";
+    threadId: string;
+    mailbox: string;
+    subject: string;
+    reason: ReviewReason;
+} | {
+    type: "send_outcome_unknown";
+    threadId: string;
+    mailbox: string;
+    subject: string;
+    draftId: string | null;
+} | {
+    type: "sync_failing";
+    mailbox: string;
+    since: string;
+} | {
+    type: "sync_recovered";
+    mailbox: string;
+    since: string;
+};
+export interface Notifier {
+    notify(event: HelpdeskNotification): Promise<void>;
+}
+export interface HelpdeskConfig {
+    ownAddresses: string[];
+    connectedMailboxes: string[];
+    subjectWindowMs?: number;
+    restartOverlapMs?: number;
+    resumeDraftAfterMs?: number;
+    draftTimeoutMs?: number;
+    minConfidence?: number;
+    pageSize?: number;
+}
+export type MailboxWriteMode = "read_only" | "approve_and_send";
+export interface HelpdeskControls {
+    paused: boolean;
+    writeMode?: MailboxWriteMode;
+    writeModes?: Record<string, MailboxWriteMode>;
+}
+export interface Paused {
+    status: "paused";
+}
+export interface WriteBlocked {
+    status: "write_blocked";
+    mode: MailboxWriteMode;
+}
+export interface HelpdeskDeps {
+    store: HelpdeskStore;
+    gatewayFor(mailbox: string): MailboxGateway;
+    drafter?: Drafter;
+    clock: Clock;
+    config: HelpdeskConfig;
+    controls?: HelpdeskControls | (() => HelpdeskControls | Promise<HelpdeskControls>);
+    notifier?: Notifier;
+    attachments?: ReplyAttachmentsDeps;
+    newId?: () => string;
+}

package/dist/types.js

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

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@dxv-systems/helpdesk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Mailbox helpdesk domain logic for DXV apps — idempotent delta ingestion, conservative threading, ticket state machine, noise detection, and replies that a person approves in the helpdesk before they are sent from the mailbox (quoted history kept, retry-safe, never sent twice). Pure logic behind interfaces, plus the staff inbox as a route handler (./server) and a React component (./react). Zero runtime dependencies.",
+  "keywords": [
+    "dxv",
+    "helpdesk",
+    "mail",
+    "microsoft-graph",
+    "threading",
+    "tickets"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.1",
+    "@types/node": "^20.19.0",
+    "@types/react": "^18.3.12",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dxv-systems/dxv-packages.git",
+    "directory": "packages/helpdesk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}