# Gmail Folder Routing — Design

**Date:** 2026-06-03
**Status:** Approved (design); pending implementation

## Goal

Route a ticket's Gmail thread into Gmail "folders" (labels) as the ticket moves
through its lifecycle, plus a manual `/folder` command for ad-hoc filing.

- On **ticket creation**, the source email thread goes into a **Triage** folder
  (instead of the current plain archive).
- On **escalation**, the thread moves to an **Escalated** folder.
- On **resolution** (close), the thread moves to a **Resolved** folder.
- A **`/folder`** slash command lets staff move the current ticket's thread to one
  of four manual folders: **For Jake**, **Spam**, **Dashboard Errors**,
  **Partnership Offers**.

Discord-originated tickets (`gmailThreadId` prefixed `discord-`) have no Gmail
thread and are untouched by all of the above.

## Decisions (locked)

| Decision | Choice |
|----------|--------|
| Folder semantics | **Exclusive** — moving to a folder removes every other managed label and drops the thread out of the Inbox. A thread lives in exactly one managed folder. |
| "Spam" target | Gmail's **built-in system `SPAM`** label (trains the filter, hides from normal views). |
| Label names | **Configurable via `.env`**, defaulting to the names above. |
| Missing labels | **Auto-created** on first use (idempotent, cached). The system `SPAM` label is never created. |
| `/folder` options | Exactly the **4 manual folders**. Triage/Escalated/Resolved are lifecycle-driven only, not manually selectable. |
| De-escalation | **Leaves the folder as Escalated** — no auto-move back. |

Gmail labels are additive by nature; "exclusive folder" behavior is synthesized by
always removing the other managed labels on every move (removing an absent label is
a no-op, so this is safe and idempotent).

## Architecture

### 1. New module — `services/gmailLabels.js`

Single home for all label logic. Folders defined by logical key:

| Key | Source | Default name |
|-----|--------|--------------|
| `TRIAGE` | `CONFIG.GMAIL_LABEL_TRIAGE` (`.env GMAIL_LABEL_TRIAGE`) | `Triage` |
| `ESCALATED` | `CONFIG.GMAIL_LABEL_ESCALATED` | `Escalated` |
| `RESOLVED` | `CONFIG.GMAIL_LABEL_RESOLVED` | `Resolved` |
| `FOR_JAKE` | `CONFIG.GMAIL_LABEL_FOR_JAKE` | `For Jake` |
| `DASHBOARD_ERRORS` | `CONFIG.GMAIL_LABEL_DASHBOARD_ERRORS` | `Dashboard Errors` |
| `PARTNERSHIP_OFFERS` | `CONFIG.GMAIL_LABEL_PARTNERSHIP_OFFERS` | `Partnership Offers` |
| `SPAM` | built-in system label `SPAM` | (not configurable) |

`MANAGED_USER_KEYS` = all keys except `SPAM` (these are the user labels whose IDs
get resolved/created and which participate in the remove-others set).

**Exports:**

- `moveThreadToFolder(threadId, folderKey, gmail = getGmailClient())` — the one
  operation everything calls.
  1. Resolve the target label ID (`resolveLabelId`), and the IDs of all managed
     user labels (to build the remove set).
  2. `addLabelIds = [targetId]`.
  3. `removeLabelIds = [all managed user-label IDs except target] + ['INBOX', 'UNREAD']`
     (computed by `computeLabelMutation`). For `SPAM` target, the user labels are
     all removed and `SPAM` is added; `INBOX`/`UNREAD` removed as usual.
  4. `await gmail.users.threads.modify({ userId: 'me', id: threadId, requestBody: { addLabelIds, removeLabelIds } })`.
  - On a `400` "invalid label" (stale cached ID for a label deleted in Gmail),
    clear the cache and retry once.

- `resolveLabelId(gmail, key)` — returns the Gmail label ID for a key.
  - `SPAM` short-circuits to `'SPAM'`.
  - Otherwise: check the module-scoped name→ID cache; on miss, `users.labels.list`
    and match by name (case-sensitive, Gmail's behavior); if still absent,
    `users.labels.create` it (`labelListVisibility: 'labelShow'`,
    `messageListVisibility: 'show'`) and cache the new ID.

- `computeLabelMutation(targetKey, idByKey)` — **pure** function returning
  `{ addLabelIds, removeLabelIds }`. Split out for unit testing without the network.

**Caching:** module-scoped `Map` of label-name → ID, populated lazily. Cleared and
re-fetched on a stale-label error.

**Client:** `getGmailClient` is required from `services/gmail.js` (acyclic —
`gmail.js` does not depend on `gmailLabels.js`). Callers that already hold a client
(the poll loop) pass it in; others let the default create one.

### 2. Triage on ticket creation — `gmail-poll.js`

Today every processed message hits `markGmailMessageRead` (strips `INBOX`+`UNREAD`)
at the shared bottom of the per-message loop (~line 397). Restructure so the
archive action is branch-specific:

- **New ticket created** (and the **reopened** closed→open case, which runs in the
  create branch) → `await moveThreadToFolder(parsed.threadId, 'TRIAGE', gmail)`.
- **Follow-up to an existing open ticket** (the `if (ticketChan)` append branch) →
  keep `markGmailMessageRead(gmail, msgRef)`. A reply on a thread already filed
  under "For Jake"/"Resolved" should not be dragged back to Triage automatically.
- **Self / limit-exceeded / create-failure** early-`continue` paths → unchanged
  plain archive (they already call `markGmailMessageRead` before `continue`).

The shared bottom `markGmailMessageRead` call is removed; the two surviving paths
(append, create) each archive/move explicitly.

`moveThreadToFolder` on creation is awaited inside the existing try/catch; a failure
is logged via the poll's existing error handling and does not abort the loop.

### 3. Escalated hook — `handlers/commands/escalation.js`

`runEscalation` is shared by the `/escalate` slash command and the tier-pick
buttons (single hook site). Inside the existing
`if (!isDiscordTicket && ticket.gmailThreadId)` block (where the escalation
notification email is already sent), add:

```js
moveThreadToFolder(ticket.gmailThreadId, 'ESCALATED')
  .catch(err => logError('gmailLabels: escalate move', err).catch(() => {}));
```

Non-fatal — a label failure never blocks the escalation. De-escalation
(`runDeescalation`) is **not** modified.

### 4. Resolved hook — two close finalizers

Both finalizers set `status: 'closed'` and remain separate:
- `handlers/commands/close.js` → `finalizeForceClose`
- `handlers/buttons.js` → `runFinalClose`

In each, for non-Discord tickets (`!ticket.gmailThreadId.startsWith('discord-')`),
after the status update, add a non-fatal:

```js
moveThreadToFolder(ticket.gmailThreadId, 'RESOLVED')
  .catch(err => logError('gmailLabels: resolved move', err).catch(() => {}));
```

One added line per finalizer. The move runs regardless of whether a close email is
sent (so close-without-email still files the thread under Resolved).

### 5. `/folder` command

- **Registration** (`commands/register.js`): `SlashCommandBuilder` named `folder`,
  `setDefaultMemberPermissions(ManageMessages)`, Guild context / GuildInstall, with
  a required string option `destination` and choices:
  - `For Jake` → `FOR_JAKE`
  - `Spam` → `SPAM`
  - `Dashboard Errors` → `DASHBOARD_ERRORS`
  - `Partnership Offers` → `PARTNERSHIP_OFFERS`
- **Dispatch** (`handlers/commands/index.js`): add `folder: handleFolder` to
  `COMMAND_HANDLERS`; add a `/folder` line to `/help`.
- **Handler** `handleFolder(interaction)`:
  1. `findTicketForChannel(interaction)`; bail if none.
  2. If `ticket.gmailThreadId.startsWith('discord-')` → ephemeral
     "This ticket has no email thread, so it can't be moved to a Gmail folder."
  3. Otherwise `await moveThreadToFolder(ticket.gmailThreadId, folderKey)`.
  4. Ephemeral reply: "Moved this ticket's email thread to **<label>**."
  5. `logTicketEvent('Email thread filed', [...], interaction).catch(() => {})`.
  6. On error, ephemeral "Failed to move the email thread: <reason>."

### 6. Config & docs

- `config.js`: add the six `GMAIL_LABEL_*` keys with the default names above.
- `.env.example`: document the six vars (default-on naming).
- Not added to `ALLOWED_CONFIG_KEYS` — settings-site contract unchanged.

## Data flow

```
inbound email (poll, flow ON)
  └─ new ticket  ──> moveThreadToFolder(thread, TRIAGE)   [add Triage; remove others+INBOX+UNREAD]
  └─ follow-up   ──> markGmailMessageRead(msg)            [remove INBOX+UNREAD on the new msg only]

/escalate or tier button ──> runEscalation ──> moveThreadToFolder(thread, ESCALATED)
close (slash or button)  ──> finalize       ──> moveThreadToFolder(thread, RESOLVED)
/folder <dest>           ──> handleFolder    ──> moveThreadToFolder(thread, <dest|SPAM>)
```

Every `moveThreadToFolder` resolves IDs (creating missing user labels), then one
`threads.modify` enforcing exclusive-folder semantics.

## Error handling

- Lifecycle hooks (Triage/Escalated/Resolved) are non-fatal `.catch` — Gmail
  problems never block ticket flow. Errors logged via `logError`.
- `/folder` surfaces failures to the invoking staffer ephemerally.
- Stale cached label ID → one cache-clear + retry inside `moveThreadToFolder`.
- Label operations are independent of `CONFIG.GMAIL_POLL_ENABLED` (the `/email`
  toggle): they are explicit staff/lifecycle actions, not polling. Triage-on-create
  only fires during polling, so it is naturally inert while the flow is off.

## Files touched

| File | Change |
|------|--------|
| `services/gmailLabels.js` | **New** — folder defs, `moveThreadToFolder`, `resolveLabelId`, `computeLabelMutation`, cache |
| `tests/gmailLabels.test.js` | **New** — unit tests for mutation logic + label resolution |
| `config.js` | Add six `GMAIL_LABEL_*` config keys (defaults) |
| `.env.example` | Document the six label-name vars |
| `gmail-poll.js` | Triage on create/reopen; keep plain archive for follow-ups & non-ticket paths |
| `handlers/commands/escalation.js` | `runEscalation`: move thread to Escalated (non-fatal) |
| `handlers/commands/close.js` | `finalizeForceClose`: move thread to Resolved (non-fatal) |
| `handlers/buttons.js` | `runFinalClose`: move thread to Resolved (non-fatal) |
| `commands/register.js` | Register `/folder` with 4 choices |
| `handlers/commands/index.js` | `handleFolder` + dispatch entry + `/help` line |

No DB schema changes. No destructive data ops — `threads.modify` only relabels;
nothing is deleted or trashed. (Moving to `SPAM` is reversible from Gmail.)

## Verification

- `npm test` — existing suite plus new `tests/gmailLabels.test.js`
  (`computeLabelMutation` exclusivity; `resolveLabelId` cache-hit / create-on-miss /
  SPAM short-circuit, with a fake gmail client).
- `node --check` on every edited file.
- Manual (post-deploy): create an email ticket → its thread lands in Triage and
  leaves the inbox; `/escalate` → Escalated; `/folder For Jake` → For Jake (and out
  of Escalated); close → Resolved. Discord ticket → `/folder` reports no email
  thread.