npm - @dxv-systems/helpdesk - Versions diffs - 0.1.0 → 0.3.0 - Mend

@dxv-systems/helpdesk 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/README.md CHANGED Viewed

@@ -1,279 +1,299 @@
-# @dxv-systems/helpdesk
-Domain logic for a mailbox helpdesk on Microsoft Graph: idempotent delta ingestion, conservative threading, a ticket state machine, noise detection, draft placement that keeps the quoted history, retry-safe sending, and an auto-send policy evaluator.
-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`, `deleteDraft`. 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: "drafts_in_app" }),
-};
-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`, `drafts_in_app`, `drafts_in_outlook` | `read_only` |
-| `writeModes` | per-mailbox override, `{ "support@client.example": "drafts_in_app" }` (case-insensitive) | none |
-**Write modes.**
-- `read_only`: sync and drafting work, and the drafter's text is stored on the run (`commentText`), but the package makes no mailbox write at all. `approveAndSend` and `retryPlacement` answer `{ status: "write_blocked", mode }`; draft cleanup is skipped.
-- `drafts_in_app`: the drafter's text 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 reuses that draft and builds the same body again instead of prepending twice. Drafts are never deleted in this mode.
-- `drafts_in_outlook`: drafts are placed in Outlook as soon as the drafter reports (the behaviour described under Drafting below).
-The package default is `read_only`, so a mailbox nobody configured is never written to. A pilot typically passes `drafts_in_app`.
-**Kill switch.** With `paused: true`, `ingestPage`, `syncMailbox`, `ensureDraft`, `completeDraft`, `regenerateDraft`, `editDraft`, `retryPlacement`, `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.
-**Auto-send** stays impossible unless the policy is enabled, the mailbox is in `drafts_in_outlook` and the helpdesk is not paused: `AutoSendContext` requires `paused` and `writeMode` (use `writeModeFor(controls, mailbox)`), and the evaluator denies with `paused` or `write_mode` before any other rule. `drafts_in_app` denies too, because it promises that nothing reaches Outlook without a person.
-Every gateway write also passes a guard that throws `MailboxWriteBlockedError` for a write the mode does not allow, 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 |
-| drafted | `auto_send` | sent |
-| 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) and, only in `drafts_in_outlook`, deletes the latest run's draft and, during a regeneration, the previous generation's (see Draft cleanup). In `drafts_in_app` and `read_only` 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. Until auto-send is wired, every draft ends in review, with `reviewReason` `low_confidence`, `policy`, `stale_draft`, `drafter_failed`, `placement_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 "Al beantwoord in Outlook" and "Geen antwoord nodig" 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; pass it to `evaluateAutoSend`, which denies with `auto_response_suppressed`.
-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, then (in `drafts_in_outlook`) places the draft with `createReply(messageId, { comment: text })`. The `comment` goes above the quoted history; PATCHing the body instead would replace it.
-**Staff edits keep the quote.** Never call `updateDraftBody` yourself. `editDraft(deps, { threadId, text })` takes the full HTML body Exchange returned at placement (stored as `placedBodyHtml`), swaps everything between `<body>` and the start of the quote for the new text, keeps everything from the quote on, writes the result, and sets the ticket back to review (`staff_edited`). The quote start is found by the Outlook/OWA markers (`appendonsend`, `divRplyFwdMsg`, `OutlookMessageHeader`), an `<hr>` followed by `From:`/`Van:`, or a `<blockquote>`. If none is found it throws `QuoteNotFoundError` before calling Graph; it never writes a body without the history. `replaceDraftComment` is exported for apps that need the pure step.
-**Failures never strand a ticket.** A drafter that cannot start, a failure result, or a failed placement moves the ticket to review with `drafter_failed` or `placement_failed`, the error stored on the run, and the page still completes. `regenerateDraft` (review to drafted, next generation) and `retryPlacement` are the staff actions; `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`). In `drafts_in_outlook` the staff run is placed like a drafter's draft (`createReply` with the text as comment; a failure gives `placement_failed`). From there it is an ordinary run: further edits, `approveAndSend`, cleanup and send intents work unchanged. One internal rule decides which run staff work on, for the domain functions and the inbox alike.
-## Draft cleanup
-The helpdesk deletes only Outlook drafts it created itself, through `MailboxGateway.deleteDraft` (which refuses anything that is not a draft and answers `deleted`, `gone` or `not_draft`). It only ever passes an id stored on a draft run of that thread and mailbox.
-- **Regeneration:** once the new generation's draft is placed, the previous generation's draft is deleted. A failed or unplaced regeneration leaves the old draft where it is.
-- **Replied from Outlook:** `markRepliedExternally` deletes the latest run's draft. If staff sent that very draft, the answer is `not_draft` or `gone`, which is fine.
-- **No reply needed:** `dismissThread` deletes the latest run's draft, and the previous generation's while a regeneration is still running.
-- **Never:** a draft whose send intent is `intended`, `sending`, `unknown` or `sent` is never deleted, because it may be on its way to a customer. An `unknown` outcome stays for staff to resolve.
-- **Failures:** a failed delete never fails the action or the ticket state. The error is stored as `draftCleanupError` on the run and the id stays; on `deleted`, `gone` and `not_draft` the id is cleared so it is not tried twice.
-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 })` (in `drafts_in_app` the draft is created at step 2, see Pilot controls):
-1. The ticket must be in review and have a placed draft (`drafts_in_app`: stored draft text); a draft 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.
-2. A send intent (`send:<mailbox>:<draftId>`) is stored first, then compare-and-set from `intended` to `sending`, then `sendDraft` is called. Only one caller wins that compare-and-set.
-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`.
-## Auto-send policy (phase 3, not wired)
-`evaluateAutoSend(policy, context)` is a pure function returning `{ allow: true }` or `{ allow: false, reason, detail? }` for the audit trail. Rules, first deny wins: not paused, write mode `drafts_in_outlook`, policy enabled (default off), not ignored mail, not an internal sender (own addresses, connected mailboxes, `internalDomains`), ticket in `drafted`, draft not stale, a scope (senders and/or categories; none configured means deny), minimum confidence, office hours (IANA zone, ISO weekdays, start inclusive and end exclusive), and a maximum of auto replies per thread. A suppress-header mail is denied before any of these (`auto_response_suppressed`). Nothing in the package calls it.
-## 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) |
-| `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 threads/:id/retry-placement` | `retryPlacement` |
-| `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), `quote_not_found`, `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 (made at that moment in `drafts_in_app`, the existing one in `drafts_in_outlook`) 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 (filters by status, assignee and mailbox; "Meer laden") and the open thread; on a phone the two are shown one at a time with "Terug naar tickets". A paused helpdesk shows a banner. In `read_only` the send button is disabled with the reason next to it; in `drafts_in_app` the draft says it goes to Outlook only on approval. Without a usable draft the reply box is empty ("Jouw antwoord"), 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 draft asks again with "Toch versturen", and an unclear send shows "Het staat in Verzonden items" / "Het is niet verstuurd". "Geen antwoord nodig" (offered in new, drafted and review, not while a send is under way or unclear) asks inline first and says when the Outlook draft will be deleted; the ticket then 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.
+# @dxv-systems/helpdesk
+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 (with their `direction`, `inbound` or `outbound`), sync state (one link per folder), 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`. `getLatestMessageForThread` returns the newest inbound message only. |
+| `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`, `ingestSentPage`, `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 Inbox delta page and processes it; `ingestSentPage(deps, mailbox)` does the same for Sent Items (see Sent Items). `syncMailbox` runs Inbox pages until the round is complete, then Sent Items pages, each folder with its own `maxPages` budget, and returns the results of both in one array (`IngestResult.folder` is `inbox` or `sentitems`). An Inbox round that is not complete yet skips Sent Items for that run.
+- **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.
+### Sent Items
+The ticket shows every reply the mailbox sent to the customer, whether it went out through the helpdesk or from Outlook. `ingestSentPage` reads the mailbox's Sent Items folder (`folderId: "sentitems"`) with the same rules as the Inbox: items first, link stored last, an expired link restarts from `max(connectedAt, sentLastReceivedAt - 48 h)`, and the kill switch returns `{ status: "paused" }`. The folder has its own link and newest time on the sync state (`sentLink`, `sentLastReceivedAt`).
+- **Display only.** A sent mail is stored as a message with `direction: "outbound"`, `fromAddress` the mailbox, and `receivedAt` the send time. It never changes a ticket: no state change, no new `latestInboundId`, no draft, and it never opens a ticket.
+- **Matching.** Always inside the same mailbox. An `In-Reply-To` that names a stored mail picks that ticket. Otherwise the ticket is found through the `References` chain and the `conversationId`; a ticket found only by conversation also needs a header hit, or a To or Cc recipient that is one of its participants. The sent mail is stored only when exactly one ticket is left. No match, or more than one: it is skipped and counted in `IngestResult.unmatched`, and never stored.
+- **Replies sent by the helpdesk.** With immutable ids a draft keeps its id after it is sent, so the Sent Items copy of an approved reply has the id the send intent recorded. The inbox uses that to show it once (see Inbox UI).
+- **Skipped:** drafts, mail sent before `connectedAt`, and mail already stored (a re-read changes nothing).
+- **Removed items** set `removedAt`: gone from Sent Items.
+- **Customer replies to our mail.** A customer reply's `In-Reply-To` usually names our sent mail. Once that mail is synced, the reply threads through its headers like any other.
+Mail the mailbox sent to itself or that lands in its own Inbox is still skipped by the Inbox sync.
+## 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 is stored only once Sent Items is synced (and never when it matched no ticket); 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 inbound message (never our own sent mail), `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)` (every message of both directions, 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; `outbound: true` for mail synced from Sent Items), latest draft, send status (`send.messageId`: the sent mail's id once the status is `sent`), 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). A sent mail's body and attachments load the same way. For a delivery report (`bounce: true` in the detail's messages, inbound only) 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. The one exception is `send.messageId` of a sent reply: once sent, the draft id is the id of the mail in Sent Items.
+**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, every reply the mailbox sent on the right ("Jouw antwoord · vanaf <mailbox>", the body and files loaded like customer mail, "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. A reply just sent through the helpdesk shows its approved text until its Sent Items copy is synced (up to one sync interval); from then on only the copy is shown.
+- **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.
+## Upgrading from 0.2
+0.3 syncs Sent Items. The app's store and inbox queries need these changes before the new version runs:
+1. **Messages: a `direction` column**, `'inbound'` or `'outbound'`, not null, default `'inbound'`. Every existing row is inbound mail, so the default backfills it. Store it on insert (`createThread`, `appendMessage`) and return it from every read of a message.
+2. **Sync state: `sent_link` and `sent_last_received_at`**, both nullable text (or timestamp for the second). `saveSyncState` must store `sentLink` and `sentLastReceivedAt` and `getSyncState` must return them. If they are not stored, Sent Items is read again from `connectedAt` on every run: nothing is stored twice, but every run costs more.
+3. **`getLatestMessageForThread` filters on `direction = 'inbound'`.** Without the filter, `unignoreThread` could make our own sent mail the message to answer.
+4. **`listMessages` returns both directions**, oldest first. The inbox shows outbound messages as replies. `findMessageThreads` and `findThreadsByConversationId` also look at both directions; no change is needed there if they do not filter on it.
+5. **`syncMailbox` results** now hold Inbox and Sent Items pages in one array. Code that reads them can use `IngestResult.folder` (`inbox` or `sentitems`) and the new `unmatched` count (always 0 for the Inbox).
+6. **`InboxThreadDetail`**: messages have `outbound`, and `send` has `messageId`. Only relevant to apps that read the detail themselves; the React page handles both.
+No new permissions: Sent Items is part of the same mailbox access. A mailbox that is already connected starts syncing its Sent Items from `connectedAt` on the first run after the upgrade, so earlier replies are picked up too.
+## 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. `deliver({ ..., folder: "sentitems", to: [...] })` puts a mail in the fake mailbox's Sent Items.
+## Development
+```bash
+npm run build --workspace @dxv-systems/helpdesk
+npm run test  --workspace @dxv-systems/helpdesk
+```
+Output is CommonJS, like the other packages.