@littlebearapps/outlook-assistant 3.8.2 → 3.9.1

package/folder/resolve.js

@@ -0,0 +1,315 @@
+/**
+ * Shared, path-aware, ambiguity-aware mail-folder resolver. (#216)
+ *
+ * Replaces the two top-level-only resolvers (`getFolderIdByName` in
+ * email/folder-utils.js and `resolveFolderName` in folder/stats.js) that could
+ * not address nested folders. Accepts, in priority order:
+ *   1. an explicit folder ID (never guessed from a name),
+ *   2. a well-known alias (inbox, archive, sent, ...),
+ *   3. a folder PATH like "Triage/Delete" or "Inbox/Clients/Acme"
+ *      (case-insensitive, traversed segment-by-segment via childFolders),
+ *   4. a bare display name (unique top-level match wins for back-compat;
+ *      otherwise the whole tree is searched, with ambiguity reported).
+ *
+ * Returns `{ id, displayName, parentId, path }`. Throws a caller-friendly Error
+ * on not-found or ambiguity (listing candidate paths + IDs).
+ *
+ * `/` is the path separator, so a folder whose display name literally contains
+ * `/` cannot be addressed by path — use its folderId (documented on the tool).
+ */
+const { callGraphAPI } = require('../utils/graph-api');
+
+// Alias → Graph well-known folder name (usable directly as a path segment).
+const WELL_KNOWN = {
+  inbox: 'inbox',
+  drafts: 'drafts',
+  sent: 'sentitems',
+  sentitems: 'sentitems',
+  'sent items': 'sentitems',
+  deleted: 'deleteditems',
+  deleteditems: 'deleteditems',
+  'deleted items': 'deleteditems',
+  junk: 'junkemail',
+  junkemail: 'junkemail',
+  'junk email': 'junkemail',
+  spam: 'junkemail',
+  archive: 'archive',
+  outbox: 'outbox',
+};
+
+// NB: mailFolder has no selectable `wellKnownName` property (Graph 400s on it,
+// verified against consumer accounts) — well-known folders are addressed by
+// name in the URL, not via a returned field.
+const FOLDER_SELECT = 'id,displayName,parentFolderId,childFolderCount';
+// Safety caps against pathological/looping nesting when walking the tree for a
+// bare-name search. Beyond these we refuse to guess and ask for a path/ID.
+const MAX_TREE_DEPTH = 20;
+const MAX_TREE_REQUESTS = 200;
+
+function notFoundError(spec) {
+  return new Error(
+    `Folder "${spec}" not found. Use \`folders\` action=list to see folders ` +
+      `(with IDs and full paths), pass a folder path like "Parent/Child", or a folderId.`
+  );
+}
+
+function ambiguousError(spec, candidates) {
+  const shown = candidates.slice(0, 20);
+  const lines = shown
+    .map((c) => `  - ${c.path}  (folderId: ${c.id})`)
+    .join('\n');
+  const more =
+    candidates.length > shown.length
+      ? `\n  … and ${candidates.length - shown.length} more`
+      : '';
+  return new Error(
+    `Folder "${spec}" is ambiguous — ${candidates.length} folders match:\n${lines}${more}\n` +
+      `Disambiguate with a folder path (e.g. "Parent/Child") or a folderId.`
+  );
+}
+
+/**
+ * List child folders of `parentId` (or top-level when null), following
+ * @odata.nextLink so folders with many children resolve completely.
+ * @returns {Promise<Array<{id, displayName, parentFolderId, childFolderCount}>>}
+ */
+async function listChildFolders(accessToken, parentId, select = FOLDER_SELECT) {
+  const all = [];
+  let path = parentId
+    ? `me/mailFolders/${parentId}/childFolders`
+    : 'me/mailFolders';
+  let params = { $top: 100, $select: select };
+  // Follow pagination; nextLink already encodes params. Guard against a
+  // repeated/malformed nextLink so a bad server response can't loop forever.
+  const seen = new Set();
+  while (path) {
+    if (seen.has(path)) {
+      throw new Error(
+        'Graph returned a repeated folder pagination link — aborting to avoid a loop.'
+      );
+    }
+    seen.add(path);
+    const resp = await callGraphAPI(accessToken, 'GET', path, null, params);
+    if (Array.isArray(resp.value)) {
+      all.push(...resp.value);
+    }
+    path = resp['@odata.nextLink'] || null;
+    params = {};
+  }
+  return all;
+}
+
+function toRecord(folder, path) {
+  return {
+    id: folder.id,
+    displayName: folder.displayName,
+    parentId: folder.parentFolderId || null,
+    path: path || folder.displayName,
+  };
+}
+
+async function resolveWellKnown(accessToken, alias) {
+  const resp = await callGraphAPI(
+    accessToken,
+    'GET',
+    `me/mailFolders/${WELL_KNOWN[alias]}`,
+    null,
+    { $select: FOLDER_SELECT }
+  );
+  return toRecord(resp, resp.displayName);
+}
+
+async function resolveById(accessToken, id) {
+  const resp = await callGraphAPI(
+    accessToken,
+    'GET',
+    `me/mailFolders/${id}`,
+    null,
+    { $select: FOLDER_SELECT }
+  );
+  return toRecord(resp, resp.displayName);
+}
+
+/**
+ * Build a flat list of every folder with its full path, breadth-first.
+ * Accepts an already-fetched top-level list to avoid re-fetching.
+ */
+async function buildTree(accessToken, topLevel) {
+  const top = topLevel || (await listChildFolders(accessToken, null));
+  const out = [];
+  const visited = new Set();
+  const queue = top.map((f) => ({ folder: f, path: f.displayName, depth: 1 }));
+  let requests = 0;
+  // Index-based iteration (no O(n^2) shift); visited-set defends against
+  // cyclic/duplicate API data.
+  for (let i = 0; i < queue.length; i++) {
+    const { folder, path, depth } = queue[i];
+    if (visited.has(folder.id)) {
+      continue;
+    }
+    visited.add(folder.id);
+    out.push(toRecord(folder, path));
+    if (folder.childFolderCount > 0) {
+      // Refuse to return a "unique" bare-name result from a truncated scan —
+      // a match could exist in the unexplored remainder. Ask for a path/ID.
+      if (depth >= MAX_TREE_DEPTH) {
+        throw new Error(
+          `Folder tree exceeds the ${MAX_TREE_DEPTH}-level resolution limit — ` +
+            'use an explicit folder path or folderId.'
+        );
+      }
+      if (++requests > MAX_TREE_REQUESTS) {
+        throw new Error(
+          'Folder tree is too large to search by bare name — ' +
+            'use an explicit folder path or folderId.'
+        );
+      }
+      const children = await listChildFolders(accessToken, folder.id);
+      for (const child of children) {
+        queue.push({
+          folder: child,
+          path: `${path}/${child.displayName}`,
+          depth: depth + 1,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+function matchName(folders, name) {
+  const lower = name.toLowerCase();
+  return folders.filter((f) => f.displayName.toLowerCase() === lower);
+}
+
+/**
+ * Resolve a bare display name: a unique top-level match wins (fast path,
+ * back-compat); otherwise search the whole tree, reporting ambiguity.
+ */
+async function resolveByName(accessToken, name) {
+  const top = await listChildFolders(accessToken, null);
+  const topMatches = matchName(top, name);
+  if (topMatches.length === 1) {
+    return toRecord(topMatches[0], topMatches[0].displayName);
+  }
+  if (topMatches.length > 1) {
+    throw ambiguousError(
+      name,
+      topMatches.map((m) => ({ id: m.id, path: m.displayName }))
+    );
+  }
+  // Not top-level — search nested folders.
+  const tree = await buildTree(accessToken, top);
+  const matches = matchName(tree, name);
+  if (matches.length === 0) {
+    throw notFoundError(name);
+  }
+  if (matches.length > 1) {
+    throw ambiguousError(name, matches);
+  }
+  return matches[0];
+}
+
+/**
+ * Resolve a path (segments already split/trimmed) by traversing childFolders.
+ */
+async function resolvePath(accessToken, segments) {
+  let current;
+  const first = segments[0];
+  if (WELL_KNOWN[first.toLowerCase()]) {
+    current = await resolveWellKnown(accessToken, first.toLowerCase());
+  } else {
+    const top = await listChildFolders(accessToken, null);
+    const matches = matchName(top, first);
+    if (matches.length === 0) {
+      throw notFoundError(first);
+    }
+    if (matches.length > 1) {
+      throw ambiguousError(
+        first,
+        matches.map((m) => ({ id: m.id, path: m.displayName }))
+      );
+    }
+    current = toRecord(matches[0], matches[0].displayName);
+  }
+
+  for (let i = 1; i < segments.length; i++) {
+    const seg = segments[i];
+    const children = await listChildFolders(accessToken, current.id);
+    const matches = matchName(children, seg);
+    if (matches.length === 0) {
+      throw notFoundError(`${current.path}/${seg}`);
+    }
+    if (matches.length > 1) {
+      throw ambiguousError(
+        `${current.path}/${seg}`,
+        matches.map((m) => ({
+          id: m.id,
+          path: `${current.path}/${m.displayName}`,
+        }))
+      );
+    }
+    current = {
+      id: matches[0].id,
+      displayName: matches[0].displayName,
+      parentId: current.id,
+      path: `${current.path}/${matches[0].displayName}`,
+    };
+  }
+  return current;
+}
+
+/**
+ * Resolve a folder from a name/path and/or explicit ID.
+ * @param {string} accessToken
+ * @param {{name?: string, id?: string}} spec
+ * @returns {Promise<{id: string, displayName: string, parentId: string|null, path: string}>}
+ *   `path` is the full slash-separated path when resolved by name/path/alias;
+ *   when resolved by ID it is the folder's display name only (ancestors are not
+ *   fetched).
+ */
+async function resolveFolder(accessToken, spec = {}) {
+  const id = (spec.id || '').trim();
+  if (id) {
+    return resolveById(accessToken, id);
+  }
+  const name = (spec.name || '').trim();
+  if (!name) {
+    throw new Error('A folder name, path, or folderId is required.');
+  }
+  if (name.includes('/')) {
+    // Trim each segment and drop leading/trailing empties ("/Inbox/" is fine),
+    // but reject INTERIOR empty segments ("A//B") so a typo can't silently
+    // collapse to a real folder — important for the destructive delete path.
+    const segments = name.split('/').map((s) => s.trim());
+    while (segments.length && segments[0] === '') {
+      segments.shift();
+    }
+    while (segments.length && segments[segments.length - 1] === '') {
+      segments.pop();
+    }
+    if (segments.length === 0) {
+      throw new Error(`Invalid folder path "${spec.name}".`);
+    }
+    if (segments.some((s) => s === '')) {
+      throw new Error(
+        `Invalid folder path "${spec.name}": empty path segment.`
+      );
+    }
+    if (segments.length === 1) {
+      return resolveFolder(accessToken, { name: segments[0] });
+    }
+    return resolvePath(accessToken, segments);
+  }
+  if (WELL_KNOWN[name.toLowerCase()]) {
+    return resolveWellKnown(accessToken, name.toLowerCase());
+  }
+  return resolveByName(accessToken, name);
+}
+
+module.exports = {
+  WELL_KNOWN,
+  resolveFolder,
+  listChildFolders,
+  buildTree,
+};

package/folder/stats.js

@@ -6,6 +6,7 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { resolveFolder } = require('./resolve');
 const config = require('../config');
 
 const { VERBOSITY, DEFAULT_LIMITS } = config;
@@ -17,24 +18,25 @@ const { VERBOSITY, DEFAULT_LIMITS } = config;
  */
 async function handleGetFolderStats(args) {
   const folderName = args.folder || 'inbox';
+  const folderIdArg = args.folderId || '';
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
 
   try {
     const accessToken = await ensureAuthenticated();
 
-    // Resolve folder name to ID
-    const folderId = await resolveFolderName(accessToken, folderName);
-
-    if (!folderId) {
+    // Resolve folder (name/path/alias/ID → concrete folder). (#216)
+    let resolved;
+    try {
+      resolved = await resolveFolder(accessToken, {
+        name: folderName,
+        id: folderIdArg,
+      });
+    } catch (resolveError) {
       return {
-        content: [
-          {
-            type: 'text',
-            text: `Folder "${folderName}" not found.`,
-          },
-        ],
+        content: [{ type: 'text', text: resolveError.message }],
       };
     }
+    const folderId = resolved.id;
 
     // Get folder details with full stats
     const folder = await callGraphAPI(
@@ -90,71 +92,6 @@ async function handleGetFolderStats(args) {
   }
 }
 
-/**
- * Resolve folder name to ID
- * @param {string} accessToken - Access token
- * @param {string} folderName - Folder name or well-known name
- * @returns {Promise<string|null>} - Folder ID or null
- */
-async function resolveFolderName(accessToken, folderName) {
-  const wellKnownFolders = {
-    inbox: 'inbox',
-    sent: 'sentitems',
-    sentitems: 'sentitems',
-    'sent items': 'sentitems',
-    drafts: 'drafts',
-    deleted: 'deleteditems',
-    deleteditems: 'deleteditems',
-    'deleted items': 'deleteditems',
-    junk: 'junkemail',
-    junkemail: 'junkemail',
-    'junk email': 'junkemail',
-    spam: 'junkemail',
-    archive: 'archive',
-    outbox: 'outbox',
-  };
-
-  const normalised = folderName.toLowerCase().trim();
-
-  // Check if it's a well-known folder
-  if (wellKnownFolders[normalised]) {
-    try {
-      const response = await callGraphAPI(
-        accessToken,
-        'GET',
-        `me/mailFolders/${wellKnownFolders[normalised]}`,
-        null,
-        { $select: 'id' }
-      );
-      return response.id;
-    } catch (_error) {
-      // Fall through to search
-    }
-  }
-
-  // Search for folder by name
-  try {
-    const response = await callGraphAPI(
-      accessToken,
-      'GET',
-      'me/mailFolders',
-      null,
-      {
-        $filter: `displayName eq '${folderName}'`,
-        $select: 'id',
-      }
-    );
-
-    if (response.value && response.value.length > 0) {
-      return response.value[0].id;
-    }
-  } catch (error) {
-    console.error(`Error searching for folder: ${error.message}`);
-  }
-
-  return null;
-}
-
 /**
  * Get date range of emails in folder
  * @param {string} accessToken - Access token

package/llms.txt

@@ -22,13 +22,13 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 
 ## Key Differentiators
 
-- **Progressive search**: Automatically falls back through 4 search strategies when Microsoft's `$search` API is unavailable (personal accounts) — most Graph API wrappers fail silently. Explicit "no results" messaging instead of unfiltered fallback.
+- **Progressive search**: Automatically falls back through 4 search strategies when Microsoft's `$search` API is unavailable (personal accounts) — most Graph API wrappers fail silently. Explicit "no results" messaging instead of unfiltered fallback. Cross-folder search (`searchAllFolders`) reliably returns a superset of inbox results.
 - **Remote-friendly auth**: Device code flow (default) — no auth server, no port forwarding, no SSH tunnels. State persists across MCP server restarts. Works from Untether, mosh, SSH, and headless environments.
 - **Email forensics**: Built-in header analysis for DKIM, SPF, DMARC authentication, delivery chains, and spam scores — useful for phishing investigation and compliance
 - **Delta sync**: Incremental inbox monitoring — returns only new, modified, and deleted emails since last check, with tokens for continuous polling
 - **Batch operations**: Flag, move, export, or categorise multiple emails in a single tool call; search-driven export for batch archiving without collecting IDs
 - **Pre-send intelligence**: Check recipients for out-of-office, mailbox full, delivery restrictions, and moderation before sending — no other Outlook MCP server offers this
-- **Compound automation**: Rules + categories + folders + Focused Inbox for complete inbox management in one conversation
+- **Compound automation**: Rules + categories + nested folders (addressable by path or ID) + Focused Inbox for complete inbox management in one conversation
 
 ## Safety & Token Efficiency
 
@@ -63,7 +63,7 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 - **Email (8 tools)**: `search-emails`, `read-email`, `send-email`, `draft`, `update-email`, `attachments`, `export`, `get-mail-tips`
 - **Calendar (3 tools)**: `list-events`, `create-event`, `manage-event`
 - **Contacts (2 tools)**: `manage-contact`, `search-people`
-- **Folders (1 tool)**: `folders` — list, create, move, stats
+- **Folders (1 tool)**: `folders` — list, create, move, stats, delete; folders addressable by nested path (`Parent/Child`) or ID
 - **Rules (1 tool)**: `manage-rules` — list, create, update, reorder, delete
 - **Categories (3 tools)**: `manage-category`, `apply-category`, `manage-focused-inbox`
 - **Settings (1 tool)**: `mailbox-settings` — get, set auto-replies, set working hours
@@ -79,6 +79,6 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 - [FAQ](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/faq/faq.md): Frequently asked questions — install, accounts, permissions, tokens, send safety, updates, uninstall (also at <https://littlebearapps.com/help/outlook-assistant/faq/>)
 - [CLAUDE.md](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CLAUDE.md): Quick reference for development
 - [CONTRIBUTING](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CONTRIBUTING.md): Contribution guidelines
-- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.8.0 — `manage-event` gains an `update` action covering 12 fields with `dryRun` (#173, closes #124); new `OUTLOOK_AUTH_AUDIENCE` env var fixes AADSTS9002331 for personal-only Azure apps (#174); new `OUTLOOK_DEFAULT_TIMEZONE` env var overrides the hardcoded Australia/Melbourne default (#175))
-- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.8.x polish, v3.9.0 new Graph APIs)
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.9.0 — nested folder addressing by path/ID (#216); reliable cross-folder search with `kqlQuery` renamed to `searchExpression` (#169); plus the v3.8.3 patch — security `overrides` clearing the audit gate (#215), `openWorldHint` on external-content tools (#92), canonical UTC ISO-8601 `list-events` times (#118))
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.7.5 polish, v3.8.x carry-over, v3.10.0+ new Graph APIs)
 - [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.8.2",
+  "version": "3.9.1",
   "mcpName": "io.github.littlebearapps/outlook-assistant",
   "description": "Outlook Assistant — MCP server with 22 tools for email, calendar, contacts, and settings via Microsoft Graph API",
   "main": "index.js",
@@ -58,6 +58,7 @@
   "files": [
     "index.js",
     "config.js",
+    "request-handler.js",
     "outlook-auth-server.js",
     "auth/",
     "calendar/",
@@ -96,6 +97,9 @@
     "node": ">=18.18.0"
   },
   "overrides": {
-    "minimatch": ">=3.1.3"
+    "minimatch": ">=3.1.3",
+    "hono": "^4.12.31",
+    "fast-uri": "^3.1.4",
+    "body-parser": "^2.3.0"
   }
 }

package/request-handler.js

@@ -0,0 +1,144 @@
+/**
+ * MCP request dispatcher for the Outlook Assistant server.
+ *
+ * Extracted from index.js so the dispatch + error-shaping logic is
+ * unit-testable without starting the stdio transport.
+ *
+ * IMPORTANT (#213): a `tools/call` that fails MUST return a visible MCP
+ * tool-error result (`{ content: [...], isError: true }`). Returning a
+ * content-less `{ error: {...} }` object gets coerced by the SDK into
+ * `{ content: [] }`, which the client renders as EMPTY OUTPUT — the exact
+ * symptom reported for device-code auth in a remote connector session.
+ */
+const config = require('./config');
+const { coerceArgsAgainstSchema } = require('./utils/schema-coerce');
+
+/**
+ * Build the MCP fallbackRequestHandler for a given tool set.
+ * @param {Array<{name: string, description?: string, inputSchema?: object, annotations?: object, handler?: Function}>} TOOLS
+ * @returns {(request: object) => Promise<object>}
+ */
+function createRequestHandler(TOOLS) {
+  return async (request) => {
+    try {
+      const { method, params, id } = request;
+      console.error(`REQUEST: ${method} [${id}]`);
+
+      // Initialize handler
+      if (method === 'initialize') {
+        console.error(`INITIALIZE REQUEST: ID [${id}]`);
+        return {
+          protocolVersion: '2024-11-05',
+          capabilities: {
+            tools: TOOLS.reduce((acc, tool) => {
+              acc[tool.name] = {};
+              return acc;
+            }, {}),
+          },
+          serverInfo: {
+            name: config.SERVER_NAME,
+            version: config.SERVER_VERSION,
+          },
+        };
+      }
+
+      // Tools list handler
+      if (method === 'tools/list') {
+        console.error(`TOOLS LIST REQUEST: ID [${id}]`);
+        console.error(`TOOLS COUNT: ${TOOLS.length}`);
+        console.error(`TOOLS NAMES: ${TOOLS.map((t) => t.name).join(', ')}`);
+
+        return {
+          tools: TOOLS.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            ...(tool.annotations && { annotations: tool.annotations }),
+          })),
+        };
+      }
+
+      // Required empty responses for other capabilities
+      if (method === 'resources/list') return { resources: [] };
+      if (method === 'prompts/list') return { prompts: [] };
+
+      // Tool call handler
+      if (method === 'tools/call') {
+        try {
+          const { name, arguments: args = {} } = params || {};
+
+          console.error(`TOOL CALL: ${name}`);
+
+          // Find the tool handler
+          const tool = TOOLS.find((t) => t.name === name);
+
+          if (tool && tool.handler) {
+            // Coerce + validate args against the tool's inputSchema before
+            // dispatching. Catches array-as-string, boolean-as-string, unknown
+            // params, and out-of-enum action values at the MCP boundary so
+            // handlers receive properly-typed JS values. (#160, #162)
+            if (tool.inputSchema) {
+              const coerced = coerceArgsAgainstSchema(args, tool.inputSchema);
+              if (coerced.error) {
+                return {
+                  content: [
+                    {
+                      type: 'text',
+                      text: `Invalid arguments for tool '${name}':\n${coerced.error}`,
+                    },
+                  ],
+                  isError: true,
+                };
+              }
+              return await tool.handler(coerced.args);
+            }
+            return await tool.handler(args);
+          }
+
+          // Tool not found — return visible isError content, not a
+          // content-less { error } (which renders as empty output). (#213)
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Tool not found: ${name}`,
+              },
+            ],
+            isError: true,
+          };
+        } catch (error) {
+          console.error(`Error in tools/call:`, error);
+          // Surface the failure as visible tool-error content so it is not
+          // silently rendered as empty output by the client. (#213)
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Error processing tool call: ${error.message}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      // For any other method, return method not found
+      return {
+        error: {
+          code: -32601,
+          message: `Method not found: ${method}`,
+        },
+      };
+    } catch (error) {
+      console.error(`Error in fallbackRequestHandler:`, error);
+      return {
+        error: {
+          code: -32603,
+          message: `Error processing request: ${error.message}`,
+        },
+      };
+    }
+  };
+}
+
+module.exports = { createRequestHandler };

package/utils/graph-api.js

@@ -90,8 +90,18 @@ async function callGraphAPI(
         headers.Prefer = 'IdType="ImmutableId"';
       }
 
-      // Merge any extra headers (caller overrides take precedence)
+      // Merge any extra headers (caller overrides take precedence). `Prefer`
+      // is multi-valued in HTTP (comma-separated); combine both values rather
+      // than letting a caller Prefer (e.g. outlook.timezone) clobber the global
+      // immutable-IDs Prefer, or vice versa.
+      const combinedPrefer =
+        headers.Prefer && extraHeaders.Prefer
+          ? `${headers.Prefer}, ${extraHeaders.Prefer}`
+          : null;
       Object.assign(headers, extraHeaders);
+      if (combinedPrefer) {
+        headers.Prefer = combinedPrefer;
+      }
 
       const options = {
         method: method,