@dxv-systems/helpdesk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,273 @@
-# Temporary Holding Version
+# @dxv-systems/helpdesk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Domain logic for a mailbox helpdesk on Microsoft Graph: idempotent delta ingestion, conservative threading, a ticket state machine, noise detection, and one way of answering: a reply (written by staff or by an AI drafter) is approved by a person in the helpdesk and only then sent from the mailbox, with the quoted history kept and no double sends.
+
+Pure logic behind interfaces, plus the staff inbox (see Inbox UI). No database, no environment reading, and zero runtime dependencies. The app implements four small interfaces and calls the functions below. All time comes from an injected `Clock`.
+
+```bash
+npm i @dxv-systems/helpdesk
+```
+
+## Integrating into an app
+
+The app owns the schema and the cron, and mounts the inbox (see Inbox UI). It passes one `HelpdeskDeps` object to every function.
+
+| Interface | What the app implements |
+|---|---|
+| `HelpdeskStore` | Threads (including the nullable `dismissedBy` staff id), messages, sync state, draft runs, send intents. Methods marked atomic in `types.ts` must be one transaction. Unique keys: message on `(mailbox, id)`, draft run on `(mailbox, inboundMessageId, generation)`, send intent on `id`. |
+| `MailboxGateway` | One mailbox: `delta`, `getMessage`, `createReply`, `updateDraftBody`, `sendDraft` (and optionally `listAttachments`, `downloadAttachment`, `addAttachment`). Declared structurally against `@dxv-systems/mail-graph`'s `MailboxClient`, so `createMailboxClient(http, address)` can be passed as is. Use immutable ids (`Prefer: IdType="ImmutableId"`). An expired delta link (410, `syncStateNotFound`, `resyncRequired`) may throw `DeltaLinkExpiredError` or mail-graph's `GraphDeltaExpiredError`; both are recognised by name or signal. |
+| `Drafter` (optional) | Without one, no draft is generated and staff write every reply (see Staff-written replies). `start(request)` starts a run and returns its id. It must treat the same `idempotencyKey` as the same run. The result comes back later through `completeDraft`. |
+| `Notifier` (optional) | `review_needed` and `send_outcome_unknown`. A throwing notifier never breaks the flow. |
+
+```ts
+const deps: HelpdeskDeps = {
+  store,
+  gatewayFor: (mailbox) => createMailboxClient(http, mailbox),
+  drafter,
+  clock: { now: () => new Date() },
+  config: { ownAddresses: ["noreply@app.example"], connectedMailboxes: ["support@client.example"] },
+  // Read again at the start of every call; a function lets a flipped switch apply at once.
+  controls: async () => ({ paused: await killSwitchIsOn(), writeMode: "approve_and_send" }),
+};
+
+await connectMailbox(deps, "support@client.example");   // once, when the mailbox is connected
+await syncMailbox(deps, "support@client.example");      // cron, one run per mailbox at a time
+await completeDraft(deps, { mailbox, inboundMessageId, idempotencyKey, result }); // when the drafter reports back
+await sweepStuckDrafts(deps, mailbox);                  // cron: fails runs with no report after 15 minutes
+```
+
+**What the app must call:** `connectMailbox` once per mailbox; `syncMailbox` on a cron; `completeDraft` whenever the drafter reports (pass the run's `idempotencyKey`; a report for anything but the latest run is ignored); `sweepStuckDrafts` on a cron (a run still in flight after `config.draftTimeoutMs`, default 15 minutes, fails so the ticket reaches review as `drafter_failed`; a report that arrives later is a no-op); and the staff actions below.
+
+## Pilot controls
+
+Three switches the app passes in `deps.controls` (a value, or a function that is called at the start of every entry point, so a change applies on the next call without a restart). The package reads no environment and keeps no state of its own.
+
+| Control | Values | Default |
+|---|---|---|
+| `paused` | `true` stops everything (kill switch) | `false` |
+| `writeMode` | `read_only`, `approve_and_send` | `read_only` |
+| `writeModes` | per-mailbox override, `{ "support@client.example": "approve_and_send" }` (case-insensitive), so a mailbox that is still being set up can stay `read_only` | none |
+
+**Write modes.** The helpdesk has one way of answering: a reply is written in the helpdesk (by staff, or proposed by the drafter), a person approves it there, and the helpdesk sends it from the mailbox. Nothing is placed in Outlook before that approval.
+
+- `read_only`: sync and drafting work, and the reply text is stored on the run (`commentText`), but the package makes no mailbox write at all. `approveAndSend` answers `{ status: "write_blocked", mode }`. This is the safe state while a client is being set up.
+- `approve_and_send`: the reply lives only in app state, and `editDraft` changes only the stored text. Nothing reaches Outlook until a person approves: `approveAndSend` then calls `createReply(inboundId)` without a comment, puts the approved text in front of the body Exchange returned (`prependToDraftBody`, right after `<body>`, so the quoted history stays), writes it with `updateDraftBody` and calls `sendDraft`. The send intent is keyed per draft run (`send:<mailbox>:<run key>`) and records the draft id, so a retry after a failed send reuses that draft and builds the same body again instead of prepending twice.
+
+The package default is `read_only`, so a mailbox nobody configured is never written to.
+
+**Kill switch.** With `paused: true`, `ingestPage`, `syncMailbox`, `ensureDraft`, `completeDraft`, `regenerateDraft`, `editDraft`, `sweepStuckDrafts`, `unignoreThread`, `approveAndSend`, `markRepliedExternally` and `dismissThread` return `{ status: "paused" }` (`ensureDraft`: `"paused"`) and make no Graph call, no drafter call and no store write. `isPaused(result)` narrows it. A sync that is paused between pages returns the pages already done. A drafter report that arrives while paused is dropped; the run stays in flight and, after the pause, `sweepStuckDrafts` moves it to review as `drafter_failed`. Bookkeeping without mailbox access (`connectMailbox`, `resolveUnknownSend`, `markWaiting`, `closeThread`) is not paused. Use it as the emergency stop: removing the Exchange role can take up to 2 hours to apply.
+
+**Mailbox scope.** `config.connectedMailboxes` is the helpdesk's scope. Any call for another mailbox (a `mailbox` argument, a thread or a drafter report of another mailbox, or a gateway whose `address` differs from the mailbox asked for) throws `MailboxNotInScopeError` before any Graph call. The same Entra app may reach other mailboxes for other features; this helpdesk never touches them.
+
+Every gateway write also passes a guard that throws `MailboxWriteBlockedError` for a write the mode does not allow (any write in `read_only`), as a last line of defence behind the checks above.
+
+Run `syncMailbox` for a mailbox from one worker at a time (a lock or a queue). Overlapping runs are safe against duplicates, but they can move the stored link backwards, which only costs a re-read.
+
+## Ingestion
+
+`ingestPage(deps, mailbox)` fetches one delta page and processes it; `syncMailbox` loops until the round is complete.
+
+- **Idempotent on the immutable message id.** A message already stored is never inserted again. A re-read of stored mail only finishes work a crash left open (a draft run that was never created, a draft ready to be routed to review).
+- **The link is stored last.** `nextLink` or `deltaLink` is saved after every item of the page is processed. A crash re-reads the page.
+- **Expired link.** `DeltaLinkExpiredError` (or any error named so) clears the link and restarts a first-page delta from `max(connectedAt, lastReceivedAt - 48 h)`. Stored mail is skipped by id.
+- **Skipped without a trace:** drafts, mail the mailbox sent itself, and mail received before `connectedAt`.
+- **Changes to existing mail** (read state, categories) are reported by delta as items we already store. They change nothing and never reopen a ticket.
+- **Removed items** set `removedAt` on the stored message. The ticket keeps its state. `removedAt` means "gone from the Inbox", nothing more: Graph reports a move to another folder and a delete alike, both as `@removed` with reason `deleted` (seen in a real tenant).
+- Items are processed oldest first, so a reply in the same page finds its parent.
+
+## Threading
+
+`matchThread` in this order, always inside one mailbox (also checked on the rows a store returns):
+
+1. **`conversationId`.** Accepted when the sender already wrote in that thread, or the mail's In-Reply-To / References point into it. An unknown sender with only a matching conversation id starts a new thread: Exchange groups mail without thread headers by subject, so a bare match can join strangers. If the headers point at a different thread than the conversation id, it also starts a new thread.
+2. **`In-Reply-To` and the whole `References` chain**, against stored `internetMessageId`s (lowercase, no angle brackets). The whole chain matters because the reply a customer answers is our own sent mail, which we never stored; the earlier ids in the chain still hit. Several open threads in one chain: no match. One open thread next to closed or ignored ones: the open one. A forward (`FW:`, `Fwd:`, `WG:`) from someone outside the thread is new business even though it carries old headers.
+3. **Normalised subject plus the same sender**, within 14 days (`subjectWindowMs`). Prefixes `Re`, `Antw`, `AW`, `SV`, `FW`, `Fwd`, `WG`, `TR`, `VS`, `Re[2]`, and gateway tags like `[EXTERN]` are stripped. An empty subject never matches. More than one open candidate: no match.
+
+## Ticket states
+
+`New`, `Ignored`, `Drafted`, `Review`, `Sent`, `Waiting`, `Closed`.
+
+| From | Event | To |
+|---|---|---|
+| new | `ignore` | ignored |
+| new | `draft` | drafted |
+| drafted | `needs_review` | review |
+| review | `approve` | sent |
+| review | `redraft` | drafted |
+| sent | `settle` | waiting |
+| waiting | `customer_reply` | new |
+| waiting | `close` | closed |
+| ignored | `unignore` | new |
+| new, drafted, review | `dismiss` | ignored |
+| sent, waiting | `bounce` | review |
+
+`transition(state, event)` is the pure function; anything else throws `InvalidTransitionError` (with `from` and `event`). `ignore` belongs to the noise filter and `dismiss` to staff, so the filter can never set aside a ticket that already has a draft. `unignoreThread` is the staff action for mail that was wrongly ignored: ignored to new, `latestInboundId` set to the newest message, `dismissedBy` cleared, and a draft starts.
+
+**No reply needed.** `dismissThread(deps, { threadId, dismissedBy })` is the staff action for mail that needs no answer (a newsletter the filter missed, "thanks, got it", spam): new, drafted or review to ignored, with `Thread.dismissedBy` set to the staff id (null on a ticket the noise filter ignored, so analytics can tell the two apart). It returns `{ status: "paused" }` under the kill switch and refuses a mailbox outside the scope. It throws `SendPendingError` (code `send_in_progress` or `send_outcome_unknown`) while a send is under way or unclear; a `sending` intent older than 2 minutes is turned into `unknown` first, so staff get the resolve buttons. After the state change it stops an in-flight draft run (marked failed, so a late report is a no-op). It touches no mailbox. `approveAndSend` checks the state again after it claims the send, so a dismissal that lands just before the claim stops the send (`StaleThreadError`, the intent becomes `failed`). Ignored stays final: a later reply opens a new ticket. Only the app decides when to call `markWaiting` (sent to waiting) and `closeThread` (waiting to closed, for example after N quiet days).
+
+**Where a state is set in practice.** A noise mail opens its ticket directly as `ignored` (the New to Ignored step is collapsed into creation, so a crash cannot leave a noise ticket in `new`). `completeDraft` goes new to drafted to review in one write. Every reply ends in review, because a person always approves it, with `reviewReason` `low_confidence`, `policy`, `stale_draft`, `drafter_failed`, `staff_edited` or (no drafter) `no_draft`. A bounce of a sent reply brings a ticket back to review with `delivery_failed`.
+
+**A customer mail (one that is not noise) arrives for a ticket in:**
+
+| State | What happens |
+|---|---|
+| new | Appended. No second draft run starts while one is in flight; its result is stale and goes to review. |
+| drafted | Appended, state kept. The draft is stale. |
+| review | Appended, state kept, `reviewReason` becomes `stale_draft`. Staff regenerates (review to drafted) or approves with `acceptStale`. |
+| sent, waiting | Same ticket goes to `new` (via `settle` then `customer_reply`) and a draft starts. |
+| closed, ignored | Final. The mail opens a new ticket with `relatedThreadId` pointing at the old one. |
+
+A noise mail (out-of-office, bounce) that threads onto a ticket is stored in it and changes nothing, so an auto-reply to our answer does not wake a waiting ticket.
+
+**Bounces of a sent reply.** A bounce (NDR) is matched to its ticket on its own terms, because its sender is never a participant. The NDR body quotes the headers of the bounced reply; their `In-Reply-To` and `References` point at the customer mail we answered, which is stored. When those name no single ticket, the conversation id is used, but only if exactly one ticket in that conversation is `sent` or `waiting`. A matched ticket in `sent` or `waiting` gets the NDR as a message and goes to review with `reviewReason: "delivery_failed"` (label "Niet afgeleverd"), and the notifier gets `review_needed` with that reason. In any other state the NDR is only stored. No match: the NDR opens its own ignored ticket as before. The inbox then offers only "Opnieuw verstuurd vanuit Outlook" (`replied_externally`) and "Geen antwoord meer nodig" (`dismiss`) for that ticket: the reply was already sent, so staff resend it from Outlook (for example to a corrected address) and say so, or set the ticket aside. `IngestResult.deliveryFailures` counts these.
+
+## Noise detection
+
+`classifyNoise` returns `{ action: "ignore" | "process", reason }`. Every rule needs a positive signal; unclear means process.
+
+- bounces: sender `postmaster` / `mailer-daemon` or Exchange Online's system sender (`microsoftexchange` plus 32 hex characters), a `delivery-status` content type, or Exchange's NDR header. A subject alone never counts. Checked before `Auto-Submitted`, which NDRs usually carry as well.
+- `Auto-Submitted` present and not `no`
+- `Precedence: bulk | junk | list | auto_reply`
+- out-of-office: `X-Autoreply`, `X-Autorespond`, or a subject that starts with the Outlook prefix (`Automatic reply:`, `Automatisch antwoord:`, `Out of Office:` and similar)
+- `List-Id` or `List-Unsubscribe`
+- sender local part `noreply`, `no-reply`, `do-not-reply`, `donotreply`, `bounce(s)`, unless `Reply-To` holds a different address that is not machine-like or ours (a website form). Then the mail is processed, `Reply-To` becomes the ticket's `customerAddress`, and both addresses are participants so threading keeps working. `Auto-Submitted`, bounces and lists still ignore such mail.
+- the app's own addresses and every connected mailbox
+
+`X-Auto-Response-Suppress` does not ignore mail: it asks auto-responders to stay quiet, and business systems set it on mail a person may need to answer. The mail is processed and `StoredMessage.suppressAutoResponse` is set, so the app can see that no automatic answer was wanted.
+
+Not noise on purpose: acknowledgements ("bedankt"), `info@`, `notifications@`, `newsletter@` and the client's own domain. Wrongly ignoring a customer is worse than a needless draft.
+
+## Drafting
+
+`ensureDraft` runs from ingestion for a new ticket. It creates the run with `createDraftRunIfAbsent` (one per inbound message) and calls `drafter.start` with `draft:<mailbox>:<messageId>:<generation>` as the idempotency key. A run that was claimed but never started is resumed after 2 minutes, with the same key.
+
+`completeDraft` stores the text, confidence, reason and category on the run and moves the ticket to review. It writes nothing to the mailbox.
+
+**Staff edits.** `editDraft(deps, { threadId, text })` stores the new text (`commentText`) and sets the ticket back to review (`staff_edited`). It writes nothing to the mailbox; the approved text is put in front of the quoted history only when the reply is sent (see Sending). Never call `updateDraftBody` yourself.
+
+**Failures never strand a ticket.** A drafter that cannot start or a failure result moves the ticket to review with `drafter_failed`, the error stored on the run, and the page still completes. `regenerateDraft` (review to drafted, next generation) is the staff action; `markRepliedExternally` closes a review when staff answered from Outlook.
+
+**Staff-written replies.** Staff can always write the reply themselves when there is no usable draft: no run, a failed run, or (without a drafter) only a run for older mail. Without `deps.drafter`, `ensureDraft` moves a new ticket straight to review with `reviewReason: "no_draft"` (and notifies `review_needed`); `regenerateDraft` throws `DraftNotReadyError`. `editDraft` then creates the next generation of the run for the newest inbound message as a staff run: status `succeeded`, `text: null` (no drafter text), `reason: "staff"`, the staff text in `commentText`. The ticket goes review to drafted to review (`staff_edited`). From there it is an ordinary run: further edits, `approveAndSend` and send intents work unchanged. One internal rule decides which run staff work on, for the domain functions and the inbox alike.
+
+## Outlook drafts
+
+The only Outlook draft the helpdesk makes is the one `approveAndSend` creates at the moment a person approves, and it is sent straight away. The helpdesk never deletes a draft. A send that Graph refused (`failed_not_sent`) leaves that draft in Outlook's Drafts; the next approval reuses it. If staff then answer from Outlook or mark the ticket as needing no reply, the leftover draft stays in Drafts until someone removes it there.
+
+Known limit: if the process dies between `createReply` and storing the draft id, that Outlook draft is a duplicate nobody knows about. Its id was never stored, so it stays until someone deletes it in Outlook.
+
+## Sending
+
+`approveAndSend(deps, { threadId, approvedBy })`:
+
+1. The ticket must be in review and have reply text (a finished draft run, or a staff reply saved with `editDraft`); a reply older than the newest customer mail needs `acceptStale: true`. A reply whose own text (`commentText`, else `text`) is empty or whitespace throws `EmptyReplyError` before any intent or Graph call: a quoted history alone is never sent. `editDraft` refuses blank text the same way. In `read_only` the answer is `write_blocked`.
+2. A send intent (`send:<mailbox>:<run key>`) is stored first, then compare-and-set from `intended` to `sending`. Only one caller wins that compare-and-set. Then the Outlook draft is created with `createReply(inboundId)`, the text goes in front of the quoted body, any files are added, and `sendDraft` is called.
+3. Success marks the intent `sent` and the ticket `sent`. A second approval returns `already_sent`.
+4. An HTTP 400, 401, 403 or 429 means Graph refused it: `failed_not_sent`, and the same flow can be retried.
+5. Anything else (network error, timeout, 5xx, 404) may have sent. The result is `unknown_outcome`, the intent becomes `unknown`, `send_outcome_unknown` is notified, and the package never resends. A `sending` intent left behind by a dead worker turns into `unknown` after 2 minutes. Staff checks Sent Items and calls `resolveUnknownSend` with `sent` or `not_sent`.
+
+Concurrent callers get `in_progress` or `already_sent`.
+
+## Inbox UI
+
+The staff inbox ships with the package: a route handler (`@dxv-systems/helpdesk/server`, framework-neutral, `handle(Request): Promise<Response>`) and a React page (`@dxv-systems/helpdesk/react`, a `"use client"` entry; React is an optional peer dependency). The app mounts both and implements one more interface for the reads the domain store does not have.
+
+**Route** `app/api/helpdesk/[...path]/route.ts`:
+
+```ts
+import { createHelpdeskHandlers } from "@dxv-systems/helpdesk/server";
+import { helpdeskDeps } from "@/lib/helpdesk/deps";     // the same HelpdeskDeps the cron uses
+import { helpdeskInbox } from "@/lib/helpdesk/inbox";   // HelpdeskInboxQueries over the app's tables
+import { getSession } from "@/lib/auth";
+
+const { handle } = createHelpdeskHandlers({
+  deps: helpdeskDeps,
+  inbox: helpdeskInbox,
+  getStaff: async (request) => {
+    const user = await getSession(request);
+    return user?.isStaff ? { id: user.id, name: user.name, email: user.email } : null;
+  },
+  isProduction: process.env.VERCEL_ENV === "production",
+});
+
+export { handle as GET, handle as POST, handle as PUT, handle as DELETE };
+```
+
+**Page** `app/(staff)/helpdesk/page.tsx`:
+
+```tsx
+import { HelpdeskInbox } from "@dxv-systems/helpdesk/react";
+
+export default function HelpdeskPage() {
+  return <HelpdeskInbox renderCustomerContext={(thread) => <CustomerCard email={thread.customerAddress} />} />;
+}
+```
+
+| `createHelpdeskHandlers` option | |
+|---|---|
+| `deps` | The `HelpdeskDeps` (store, `gatewayFor`, optional drafter, notifier, `controls`, clock, config). The handlers call the domain functions with it and nothing else. |
+| `inbox` | `HelpdeskInboxQueries`: `listThreads(query)` (filters `states`, `mailbox`, `assigneeId`: undefined is anyone, null is unassigned; `cursor` and `limit`; newest activity first; returns `{ rows: [{ thread, assignee }], nextCursor }`), `listMessages(threadId)` (oldest first), `getAssignee(threadId)`, `setAssignee(threadId, { id, name } \| null)`. Assignment is app data; the domain never reads it. |
+| `getStaff(request)` | `{ id, name, email }` for staff, null for anyone else (every route answers 401). `id` is stored as `approvedBy` on a send and as `dismissedBy` on a dismissal. |
+| `isProduction` | Outside production every route answers 403 `not_production`. |
+| `basePath` | Default `/api/helpdesk`. |
+| `appOrigin` | Writes with an `Origin` header from elsewhere answer 403. Default: the request URL's origin. |
+| `onError` | Unexpected errors (default `console.error`); the response is a generic 500 without details. |
+
+**Routes** (under `basePath`). Every write answers `{ detail, message, outcome? }` with the thread as it is after the action.
+
+| Route | Calls |
+|---|---|
+| `GET threads?state=review,new&mailbox=&assignee=me\|none\|<id>&cursor=&limit=` | `inbox.listThreads`; also returns the pilot switches per mailbox |
+| `GET threads/:id` | thread, messages (metadata), latest draft, send status, and `actions` the state machine and pilot controls allow now |
+| `GET threads/:id/messages/:messageId` | `gateway.getMessage` through the scope check; body as plain text, plus its attachments (`gateway.listAttachments`, inline images left out). For a delivery report (`bounce: true` in the detail's messages) also `bounce`: `{ recipient, statusCode, reason, diagnostic }`, read on the server, with `reason` one plain Dutch sentence (e.g. 5.1.1 "Dit adres bestaat niet.") |
+| `GET threads/:id/messages/:messageId/attachments/:attachmentId` | download of one file attachment of that message (`gateway.downloadAttachment`) |
+| `PUT threads/:id/draft` `{ text }` | `editDraft` |
+| `POST threads/:id/regenerate` | `regenerateDraft` |
+| `POST threads/:id/send` `{ acceptStale? }` | `approveAndSend` |
+| `POST`/`DELETE threads/:id/assign` | `inbox.setAssignee` (to the signed-in staff member / nobody) |
+| `POST threads/:id/waiting` | `markWaiting` |
+| `POST threads/:id/close` | `closeThread` |
+| `POST threads/:id/unignore` | `unignoreThread` |
+| `POST threads/:id/replied-externally` | `markRepliedExternally` |
+| `POST threads/:id/dismiss` | `dismissThread`, with the signed-in staff id as `dismissedBy` |
+| `POST threads/:id/resolve-send` `{ outcome: "sent" \| "not_sent" }` | `resolveUnknownSend` |
+
+Errors are `{ error, message }` with a Dutch `message` (`INBOX_ERROR_MESSAGES`): `paused` (423), `write_blocked` (409, with `mode`), `mailbox_not_in_scope` (403), `stale_draft`, `draft_not_ready`, `invalid_transition`, `stale_thread`, `send_in_progress`, `send_outcome_unknown` (409), `empty_reply` (422), `send_failed` (502, Graph refused, nothing sent), `thread_not_found` (404). A send whose outcome is unclear answers 200 with `outcome: "unknown_outcome"`. Responses never carry draft bodies from Outlook, idempotency keys, draft ids or raw error text.
+
+**Attachments.** The message body route lists the attachments of a customer mail; inline images (signature logos) are left out. A file up to 4 MB gets a download link on the app itself; a larger file, an attached mail (`item`) or a link to a shared file (`reference`) is listed with a note to open it in Outlook, because a Vercel function answers at most 4.5 MB. The download is checked like the body (the message must belong to the ticket, scope check, paused refuses) and the attachment id must be one Graph lists for that message. It is always served as `application/octet-stream` with `Content-Disposition: attachment`, `X-Content-Type-Options: nosniff` and a sandbox CSP, so customer files never render on the app's origin. Both gateway methods are optional: a gateway without them shows no attachments. mail-graph's `MailboxClient` has them. Attachments are never stored by the helpdesk.
+
+**Files on a reply.** With `deps.attachments` (`ReplyAttachmentsDeps`: a `ReplyAttachmentStore` over the app's table and `ReplyFiles` over its file storage) and a gateway with `addAttachment`, staff can add files to the reply they are writing. The file never passes the app server: `startReplyUpload` checks the ticket and the limits and lets the app presign a direct upload, the browser PUTs the file to storage, and `addReplyAttachment` has the app verify the stored object before the file joins the reply. Limits: 10 files and 20 MB together per reply, checked before the upload and again on the real object. Files can be added while the reply can still be approved (review, not a bounced ticket) and removed until it is sent (`removeReplyAttachment`). Outlook is touched only at approval: `approveAndSend` adds the files to the draft it creates at that moment, right before `sendDraft`; a file that cannot be added fails the send as `failed_not_sent`, so nothing goes out without the approved files, and a retry on the same draft skips files already on it. After the send the files are marked as sent with that intent, also when staff confirm an unclear send. Dismissing a ticket or "Al beantwoord in Outlook" drops the unsent files. Routes: `POST threads/:id/attachments/upload` (`{ name, contentType, size }`, answers the upload target), `POST threads/:id/attachments` (`{ uploadToken }`), `DELETE threads/:id/attachments/:attachmentId`. The detail carries `replyAttachments` (unsent ones, and those of the latest sent reply) and the action `attach`.
+
+**Message bodies are text only.** The package has no HTML sanitiser, so it never sends mail HTML to the page: the body is asked from Graph as text, and any HTML that still comes back goes through `htmlToPlainText` (tags, scripts, styles and comments dropped, entities decoded). The page renders it as a text node with `white-space: pre-wrap`. Bodies are fetched per message, once per open thread; while the helpdesk is paused they are not fetched (no Graph call), the rest of the thread still shows.
+
+| `HelpdeskInbox` prop | |
+|---|---|
+| `apiBasePath` | Default `/api/helpdesk`. |
+| `classNames` | Partial `HelpdeskInboxClassNames`; defaults (`DEFAULT_HELPDESK_INBOX_CLASSNAMES`) use the shadcn tokens of the company app template. The only way to style it. |
+| `pollIntervalMs` | List and open thread refresh, default 30000, at least 5000. A draft being edited is never overwritten. |
+| `fetch` | Custom fetch (tests, a wrapper that adds headers). |
+| `renderCustomerContext` | `(thread) => ReactNode`, shown above the messages: the app's own data for the customer or project. |
+| `initialThreadId`, `onThreadChange` | Open a thread first (a link from a `review_needed` notification) and keep the open thread in the URL. |
+
+What staff sees: one page with the list and the open ticket side by side; on a phone the two are shown one at a time with "Terug naar tickets" (hidden from `md` up, where the list stays visible). A paused helpdesk shows a banner.
+
+- **List.** Status and assignee filters side by side (native, labelled selects with the app's input style; the chosen status shows the count the list already has), a mailbox filter below them when there are several mailboxes, and "Meer laden". Each ticket shows its subject and time, the customer, and one status badge.
+- **One status badge.** State and review reason make one label: a bounced reply shows "Niet afgeleverd" instead of "Te beoordelen"; other reasons appear as small text next to the badge ("Voorstel klaar", "Zelf antwoorden").
+- **Header.** Subject, the status badge, `customer · naar <mailbox>`, the assignment ("Niet toegewezen · Aan mij", "Toegewezen aan jou", "Toegewezen aan <naam> · Aan mij") and a "Meer acties" menu with "Geen antwoord nodig", "Al beantwoord in Outlook" (both ask inline first) and "Toewijzing weghalen".
+- **Conversation.** One chronological list: customer mails on the left with initials, the sent reply on the right ("Jouw antwoord · vanaf <mailbox>", its files, "Verstuurd, staat in Verzonden items"). Attachments are file chips with type and size. A delivery report is an event ("Jouw antwoord is niet afgeleverd", the Dutch reason, and the raw text under "Technische details van Microsoft"), never the raw mail. Only the latest sent reply is shown; the helpdesk keeps no copy of earlier ones.
+- **Reply.** A "Jouw antwoord" card: "Voorstel van de AI · pas aan waar nodig" while the text is the drafter's, the reply box, files ("Bijlage toevoegen", max. 10 files, 20 MB together), and a footer with the sending mailbox and "Nieuw voorstel", "Opslaan" and "Goedkeuren en versturen". In `read_only` the ticket carries an "Alleen lezen" badge and the send button is disabled with the reason next to it. Without a usable draft the box is empty, and sending saves the typed reply first; a blank reply cannot be sent. Sending always asks for confirmation inline (recipient and mailbox named; edits are saved first), a stale reply asks again with "Toch versturen", and an unclear send shows "Het staat in Verzonden items" / "Het is niet verstuurd".
+- **Bounced ticket.** Instead of the reply card, "Wat nu?" with "Opnieuw verstuurd vanuit Outlook" (`replied-externally`) and "Geen antwoord meer nodig" (`dismiss`).
+
+A dismissed ticket leaves the list (a ticket whose new state falls outside the chosen view always does) and stays open with "Toch behandelen" to undo it.
+
+## Testing
+
+`@dxv-systems/helpdesk/testing` has in-memory fakes (`createMemoryStore`, `createFakeMailbox`, `createFakeDrafter`, `createManualClock`, and `createTestWorld` to wire them), with the uniqueness and compare-and-set rules a real store needs. Apps can run their own store against the same scenarios. `createTestWorld({ controls })` sets the pilot controls (without them the package defaults apply), and each fake mailbox records every gateway call in `calls` and the mailbox writes in `writeCalls`, so a test can assert that read-only or paused made none.
+
+## Development
+
+```bash
+npm run build --workspace @dxv-systems/helpdesk
+npm run test  --workspace @dxv-systems/helpdesk
+```
+
+Output is CommonJS, like the other packages.

package/dist/bounce.d.ts

@@ -0,0 +1,13 @@
+import type { HelpdeskStore, Thread } from "./types";
+export declare function bouncedReplyRefs(bodyText: string): string[];
+export interface BounceReport {
+    recipient: string | null;
+    statusCode: string | null;
+    diagnostic: string;
+}
+export declare function readBounceReport(text: string): BounceReport;
+export declare function matchBounce(store: HelpdeskStore, input: {
+    mailbox: string;
+    refs: string[];
+    conversationId: string | null;
+}): Promise<Thread | null>;

package/dist/bounce.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bouncedReplyRefs = bouncedReplyRefs;
+exports.readBounceReport = readBounceReport;
+exports.matchBounce = matchBounce;
+const threading_1 = require("./threading");
+const QUOTED_HEADER = /^(?:in-reply-to|references)[ \t]*:[ \t]*(.*(?:\r?\n[ \t]+.*)*)/gim;
+function bouncedReplyRefs(bodyText) {
+    const ids = new Set();
+    for (const match of bodyText.matchAll(QUOTED_HEADER)) {
+        for (const raw of match[1]?.match(/<[^<>\s]+>/g) ?? []) {
+            const id = (0, threading_1.normalizeMessageId)(raw);
+            if (id)
+                ids.add(id);
+        }
+    }
+    return [...ids];
+}
+const MAX_DIAGNOSTIC_CHARS = 2000;
+const ADDRESS = String.raw `<?([^\s<>;:()"',]+@[^\s<>;:()"',]+)>?`;
+const RECIPIENT_PATTERNS = [
+    new RegExp(String.raw `^(?:final|original)-recipient:[ \t]*(?:rfc822;)?[ \t]*${ADDRESS}[ \t]*$`, "im"),
+    new RegExp(String.raw `^recipient:[ \t]*${ADDRESS}[ \t]*$`, "im"),
+    new RegExp(String.raw `(?:your message to|je bericht aan|uw bericht aan)[ \t]+${ADDRESS}(?=[\s.,]|$)`, "i"),
+    new RegExp(String.raw `(?:delivery has failed to these recipients or groups|bezorging is mislukt voor deze ontvangers of groepen):\s*${ADDRESS}(?=[\s.,]|$)`, "i"),
+];
+const CODE_PATTERNS = [/\b[245]\d\d[ -]#?([245]\.\d{1,3}\.\d{1,3})\b/, /(?:status:|#)[ \t]*([245]\.\d{1,3}\.\d{1,3})\b/i, /\b([45]\.\d{1,3}\.\d{1,3})\b/];
+const DIAGNOSTIC_START = /(?:diagnostic information for administrators|diagnostische gegevens voor beheerders)\s*:/i;
+const DIAGNOSTIC_END = /(?:original message headers|oorspronkelijke berichtkoppen)\s*:/i;
+function readBounceReport(text) {
+    const body = text.replace(/\r\n?/g, "\n");
+    let recipient = null;
+    for (const re of RECIPIENT_PATTERNS) {
+        const found = re.exec(body)?.[1];
+        if (found) {
+            recipient = found.replace(/[.]+$/, "").toLowerCase();
+            break;
+        }
+    }
+    let statusCode = null;
+    for (const re of CODE_PATTERNS) {
+        const found = re.exec(body)?.[1];
+        if (found) {
+            statusCode = found;
+            break;
+        }
+    }
+    const start = DIAGNOSTIC_START.exec(body);
+    const rest = start ? body.slice(start.index + start[0].length) : body;
+    const end = DIAGNOSTIC_END.exec(rest);
+    let diagnostic = (end ? rest.slice(0, end.index) : rest).replace(/\n{3,}/g, "\n\n").trim();
+    if (diagnostic.length > MAX_DIAGNOSTIC_CHARS)
+        diagnostic = `${diagnostic.slice(0, MAX_DIAGNOSTIC_CHARS).trimEnd()}…`;
+    return { recipient, statusCode, diagnostic };
+}
+const awaitsDelivery = (t) => t.state === "sent" || t.state === "waiting";
+async function matchBounce(store, input) {
+    const { mailbox, refs, conversationId } = input;
+    if (refs.length > 0) {
+        const ids = [...new Set((await store.findMessageThreads(mailbox, refs)).map((h) => h.threadId))];
+        const threads = [];
+        for (const id of ids) {
+            const t = await store.getThread(id);
+            if (t && t.mailbox === mailbox)
+                threads.push(t);
+        }
+        if (threads.length === 1)
+            return threads[0] ?? null;
+        const answered = threads.filter(awaitsDelivery);
+        if (answered.length === 1)
+            return answered[0] ?? null;
+        if (threads.length > 1)
+            return null;
+    }
+    if (!conversationId)
+        return null;
+    const answered = (await store.findThreadsByConversationId(mailbox, conversationId)).filter((t) => t.mailbox === mailbox && awaitsDelivery(t));
+    return answered.length === 1 ? (answered[0] ?? null) : null;
+}

package/dist/controls.d.ts

@@ -0,0 +1,13 @@
+import type { HelpdeskConfig, HelpdeskControls, HelpdeskDeps, MailboxGateway, MailboxWriteMode, Paused } from "./types";
+export declare const DEFAULT_WRITE_MODE: MailboxWriteMode;
+export declare const paused: () => Paused;
+export declare function isPaused(value: unknown): value is Paused;
+export declare function loadControls(deps: HelpdeskDeps): Promise<HelpdeskControls>;
+export declare function writeModeFor(controls: HelpdeskControls, mailbox: string): MailboxWriteMode;
+export declare function assertInScope(config: HelpdeskConfig, mailbox: string): void;
+export interface MailboxAccess {
+    mailbox: string;
+    mode: MailboxWriteMode;
+    gateway(): MailboxGateway;
+}
+export declare function mailboxAccess(deps: HelpdeskDeps, controls: HelpdeskControls, mailbox: string): MailboxAccess;

package/dist/controls.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paused = exports.DEFAULT_WRITE_MODE = void 0;
+exports.isPaused = isPaused;
+exports.loadControls = loadControls;
+exports.writeModeFor = writeModeFor;
+exports.assertInScope = assertInScope;
+exports.mailboxAccess = mailboxAccess;
+const errors_1 = require("./errors");
+exports.DEFAULT_WRITE_MODE = "read_only";
+const ALLOWED_WRITES = {
+    read_only: [],
+    approve_and_send: ["createReply", "updateDraftBody", "addAttachment", "sendDraft"],
+};
+const norm = (address) => address.trim().toLowerCase();
+const paused = () => ({ status: "paused" });
+exports.paused = paused;
+function isPaused(value) {
+    return typeof value === "object" && value !== null && value.status === "paused";
+}
+async function loadControls(deps) {
+    const controls = typeof deps.controls === "function" ? await deps.controls() : deps.controls;
+    return controls ?? { paused: false };
+}
+function writeModeFor(controls, mailbox) {
+    const key = norm(mailbox);
+    for (const [address, mode] of Object.entries(controls.writeModes ?? {})) {
+        if (norm(address) === key)
+            return mode;
+    }
+    return controls.writeMode ?? exports.DEFAULT_WRITE_MODE;
+}
+function assertInScope(config, mailbox) {
+    if (!config.connectedMailboxes.some((a) => norm(a) === norm(mailbox))) {
+        throw new errors_1.MailboxNotInScopeError(mailbox);
+    }
+}
+function mailboxAccess(deps, controls, mailbox) {
+    assertInScope(deps.config, mailbox);
+    const mode = writeModeFor(controls, mailbox);
+    return { mailbox, mode, gateway: () => guardedGateway(deps, mailbox, mode) };
+}
+function guardedGateway(deps, mailbox, mode) {
+    const gw = deps.gatewayFor(mailbox);
+    if (norm(gw.address) !== norm(mailbox))
+        throw new errors_1.MailboxNotInScopeError(gw.address);
+    const allow = (op) => {
+        if (!ALLOWED_WRITES[mode].includes(op))
+            throw new errors_1.MailboxWriteBlockedError(mailbox, mode, op);
+    };
+    return {
+        address: gw.address,
+        delta: (options) => gw.delta(options),
+        getMessage: (id, options) => gw.getMessage(id, options),
+        ...(gw.listAttachments && gw.downloadAttachment
+            ? {
+                listAttachments: (id) => gw.listAttachments(id),
+                downloadAttachment: (id, attachmentId) => gw.downloadAttachment(id, attachmentId),
+            }
+            : {}),
+        ...(gw.addAttachment
+            ? {
+                async addAttachment(draftId, attachment) {
+                    allow("addAttachment");
+                    return gw.addAttachment(draftId, attachment);
+                },
+            }
+            : {}),
+        async createReply(id, options) {
+            allow("createReply");
+            return gw.createReply(id, options);
+        },
+        async updateDraftBody(id, body) {
+            allow("updateDraftBody");
+            return gw.updateDraftBody(id, body);
+        },
+        async sendDraft(id) {
+            allow("sendDraft");
+            return gw.sendDraft(id);
+        },
+    };
+}

package/dist/draft-body.d.ts

@@ -0,0 +1,4 @@
+export declare function renderCommentHtml(text: string): string;
+export declare function findQuoteStart(html: string): number;
+export declare function hasQuotedHistory(html: string): boolean;
+export declare function prependToDraftBody(bodyHtml: string, text: string): string;

package/dist/draft-body.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderCommentHtml = renderCommentHtml;
+exports.findQuoteStart = findQuoteStart;
+exports.hasQuotedHistory = hasQuotedHistory;
+exports.prependToDraftBody = prependToDraftBody;
+const QUOTE_MARKERS = [
+    /<div[^>]*\bid=["']appendonsend["']/i,
+    /<div[^>]*\bid=["']divRplyFwdMsg["']/i,
+    /<div[^>]*\bid=["']OutlookMessageHeader["']/i,
+    /<hr\b[^>]*>(?=[\s\S]{0,400}?(?:From|Van|Von)\s*:)/i,
+    /<blockquote\b/i,
+];
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function renderCommentHtml(text) {
+    const paragraphs = text.replace(/\r\n?/g, "\n").trim().split(/\n{2,}/);
+    return paragraphs
+        .map((p) => `<div>${escapeHtml(p).replace(/\n/g, "<br>")}</div>`)
+        .join("<div><br></div>");
+}
+function findQuoteStart(html) {
+    const found = QUOTE_MARKERS.map((re) => html.search(re)).filter((i) => i >= 0);
+    return found.length ? Math.min(...found) : -1;
+}
+function hasQuotedHistory(html) {
+    return findQuoteStart(html) >= 0;
+}
+function prependToDraftBody(bodyHtml, text) {
+    const bodyTag = /<body\b[^>]*>/i.exec(bodyHtml);
+    const at = bodyTag ? bodyTag.index + bodyTag[0].length : 0;
+    return bodyHtml.slice(0, at) + renderCommentHtml(text) + bodyHtml.slice(at);
+}

package/dist/drafting.d.ts

@@ -0,0 +1,18 @@
+import type { DraftResult, DraftRun, HelpdeskDeps, Paused, StoredMessage, Thread } from "./types";
+export declare function currentReplyRun(deps: HelpdeskDeps, thread: Thread, run: DraftRun | null): DraftRun | null;
+export type EnsureDraftOutcome = "started" | "exists" | "busy" | "not_needed" | "no_drafter" | "paused";
+export declare function ensureDraft(deps: HelpdeskDeps, threadId: string, message: StoredMessage): Promise<EnsureDraftOutcome>;
+export declare function startDraftFor(deps: HelpdeskDeps, threadId: string, message: StoredMessage): Promise<Exclude<EnsureDraftOutcome, "paused">>;
+export declare function completeDraft(deps: HelpdeskDeps, input: {
+    mailbox: string;
+    inboundMessageId: string;
+    idempotencyKey: string;
+    result: DraftResult;
+}): Promise<DraftRun | Paused>;
+export declare function regenerateDraft(deps: HelpdeskDeps, threadId: string): Promise<DraftRun | Paused>;
+export declare function editDraft(deps: HelpdeskDeps, input: {
+    threadId: string;
+    text: string;
+}): Promise<DraftRun | Paused>;
+export declare function sweepStuckDrafts(deps: HelpdeskDeps, mailbox: string): Promise<number | Paused>;
+export declare function unignoreThread(deps: HelpdeskDeps, threadId: string): Promise<Thread | Paused>;