@littlebearapps/outlook-assistant 3.11.2 → 3.12.1

package/email/conversations.js

@@ -12,6 +12,10 @@ const {
 } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { getEmailFields } = require('../utils/field-presets');
+const { resolveFolderPath } = require('./folder-utils');
+const { buildMailboxPrefix } = require('../utils/mailbox');
+const { writeClaimedFile, makeClaimedDir } = require('../utils/safe-write');
+const { escapeODataString } = require('../utils/odata-helpers');
 const {
   formatEmailContent,
   formatEmailsAsCSV,
@@ -59,6 +63,8 @@ async function handleListConversations(args) {
   const folder = args.folder || 'inbox';
   const count = Math.min(args.count || 20, 50);
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
+  // Optional: scope to a shared/delegated mailbox instead of the signed-in user.
+  const sharedMailbox = args.sharedMailbox || args.email || null;
 
   try {
     const accessToken = await ensureAuthenticated();
@@ -77,7 +83,13 @@ async function handleListConversations(args) {
       'bodyPreview',
     ].join(',');
 
-    const endpoint = `me/mailFolders/${folder}/messages`;
+    // resolveFolderPath handles well-known names, custom/localized names, nested
+    // paths, and raw IDs, scoped to the signed-in user or the shared mailbox.
+    const endpoint = await resolveFolderPath(
+      accessToken,
+      folder,
+      sharedMailbox
+    );
     const queryParams = {
       $select: selectFields,
       $orderby: 'receivedDateTime desc',
@@ -240,6 +252,102 @@ async function handleListConversations(args) {
   }
 }
 
+// Upper bounds on the messages one conversation read/export will load. The
+// inline read returns every message in the tool result, so it stops sooner.
+const GET_CONVERSATION_MESSAGE_LIMIT = 100;
+const EXPORT_CONVERSATION_MESSAGE_LIMIT = 1000;
+
+/**
+ * Fetch the messages in a conversation, oldest first (or newest first).
+ *
+ * Graph rejects `$filter=conversationId eq '…'` combined with `$orderby` on
+ * personal Microsoft accounts (400 InefficientFilter), so the query carries no
+ * `$orderby`: the pages are fetched and the messages are sorted here. Paging
+ * stops at the caller's `limit` or if Graph repeats a nextLink; either
+ * way the result is marked truncated. (Not callGraphAPIPaginated: it can't
+ * report truncation or catch a repeated nextLink.)
+ * @param {string} accessToken - Access token
+ * @param {string} prefix - Mailbox prefix (`me` or `users/{mailbox}`)
+ * @param {string} conversationId - Conversation ID
+ * @param {string} selectFields - `$select` fields
+ * @param {object} options
+ * @param {number} options.limit - Most messages to load
+ * @param {boolean} [options.newestFirst=false] - Sort newest first instead
+ * @returns {Promise<{messages: Array<object>, truncated: boolean}>}
+ */
+async function fetchConversationMessages(
+  accessToken,
+  prefix,
+  conversationId,
+  selectFields,
+  { limit, newestFirst = false }
+) {
+  let messages = [];
+  let truncated = false;
+  const seenLinks = new Set();
+  let url = `${prefix}/messages`;
+  let queryParams = {
+    $select: selectFields,
+    $filter: `conversationId eq '${escapeODataString(String(conversationId))}'`,
+    $top: Math.min(100, limit),
+  };
+
+  while (url) {
+    const response = await callGraphAPI(
+      accessToken,
+      'GET',
+      url,
+      null,
+      queryParams
+    );
+    messages.push(...(response.value || []));
+    const nextLink = response['@odata.nextLink'];
+    if (messages.length > limit) {
+      messages = messages.slice(0, limit);
+      truncated = true;
+      break;
+    }
+    if (nextLink && (messages.length >= limit || seenLinks.has(nextLink))) {
+      truncated = true;
+      break;
+    }
+    if (nextLink) seenLinks.add(nextLink);
+    url = nextLink;
+    queryParams = {}; // the nextLink already carries every parameter
+  }
+
+  return { messages: sortByReceivedDate(messages, newestFirst), truncated };
+}
+
+/**
+ * Note added to output when a conversation hit a fetch limit.
+ * @param {number} count - Messages loaded
+ * @returns {string}
+ */
+function truncationNote(count) {
+  return `**Note**: Conversation truncated at ${count} messages.`;
+}
+
+/**
+ * Sort messages by receivedDateTime (stable; messages without a valid date
+ * go last in either direction).
+ * @param {Array<object>} messages - Messages to sort
+ * @param {boolean} newestFirst - Sort newest first instead of oldest first
+ * @returns {Array<object>} - New sorted array
+ */
+function sortByReceivedDate(messages, newestFirst) {
+  const time = (msg) => {
+    const t = Date.parse(msg.receivedDateTime);
+    return Number.isNaN(t) ? null : t;
+  };
+  return [...messages].sort((a, b) => {
+    const ta = time(a);
+    const tb = time(b);
+    if (ta === null || tb === null) return (ta === null) - (tb === null);
+    return newestFirst ? tb - ta : ta - tb;
+  });
+}
+
 /**
  * Get conversation handler - retrieves all messages in a thread
  * @param {object} args - Tool arguments
@@ -252,6 +360,8 @@ async function handleGetConversation(args) {
   const conversationId = args.conversationId;
   const includeHeaders = args.includeHeaders || false;
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
+  const sharedMailbox = args.sharedMailbox || args.email || null;
+  const prefix = buildMailboxPrefix(sharedMailbox);
 
   if (!conversationId) {
     return {
@@ -267,41 +377,13 @@ async function handleGetConversation(args) {
     const selectFields = getEmailFields(fieldPreset);
 
     // Search all folders for messages with this conversation ID
-    const endpoint = 'me/messages';
-    const queryParams = {
-      $select: selectFields,
-      $filter: `conversationId eq '${conversationId}'`,
-      $orderby: 'receivedDateTime asc',
-      $top: 100,
-    };
-
-    let response;
-    try {
-      response = await callGraphAPI(
-        accessToken,
-        'GET',
-        endpoint,
-        null,
-        queryParams
-      );
-    } catch (apiError) {
-      if (
-        apiError.message.includes('ErrorInvalidUrlQueryFilter') ||
-        apiError.message.includes('InefficientFilter') ||
-        apiError.message.includes('filter')
-      ) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Conversation retrieval by conversationId is not supported on personal Microsoft accounts. Use read-email with individual message IDs instead.`,
-            },
-          ],
-        };
-      }
-      throw apiError;
-    }
-    const messages = response.value || [];
+    const { messages, truncated } = await fetchConversationMessages(
+      accessToken,
+      prefix,
+      conversationId,
+      selectFields,
+      { limit: GET_CONVERSATION_MESSAGE_LIMIT }
+    );
 
     if (messages.length === 0) {
       return {
@@ -320,6 +402,7 @@ async function handleGetConversation(args) {
     output.push(`**Subject**: ${messages[0].subject || '(no subject)'}`);
     output.push(`**Messages**: ${messages.length}`);
     output.push(`**Conversation ID**: \`${conversationId}\`\n`);
+    if (truncated) output.push(`${truncationNote(messages.length)}\n`);
     output.push('---\n');
 
     messages.forEach((msg, index) => {
@@ -339,6 +422,7 @@ async function handleGetConversation(args) {
         conversationId,
         messageCount: messages.length,
         subject: messages[0]?.subject,
+        truncated,
       },
     };
   } catch (error) {
@@ -379,6 +463,8 @@ async function handleExportConversation(args) {
   const outputDir = args.outputDir || require('os').tmpdir();
   const _includeAttachments = args.includeAttachments !== false;
   const order = args.order || 'chronological';
+  const sharedMailbox = args.sharedMailbox || args.email || null;
+  const prefix = buildMailboxPrefix(sharedMailbox);
 
   if (!conversationId) {
     return {
@@ -402,42 +488,16 @@ async function handleExportConversation(args) {
     const accessToken = await ensureAuthenticated();
 
     // Get all messages in conversation
-    const selectFields = getEmailFields('export');
-    const endpoint = 'me/messages';
-    const queryParams = {
-      $select: selectFields,
-      $filter: `conversationId eq '${conversationId}'`,
-      $orderby: `receivedDateTime ${order === 'reverse' ? 'desc' : 'asc'}`,
-      $top: 100,
-    };
-
-    let response;
-    try {
-      response = await callGraphAPI(
-        accessToken,
-        'GET',
-        endpoint,
-        null,
-        queryParams
-      );
-    } catch (apiError) {
-      if (
-        apiError.message.includes('ErrorInvalidUrlQueryFilter') ||
-        apiError.message.includes('InefficientFilter') ||
-        apiError.message.includes('filter')
-      ) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Conversation export is not supported on personal Microsoft accounts. Use export with target=message and individual message IDs instead.`,
-            },
-          ],
-        };
+    const { messages, truncated } = await fetchConversationMessages(
+      accessToken,
+      prefix,
+      conversationId,
+      getEmailFields('export'),
+      {
+        limit: EXPORT_CONVERSATION_MESSAGE_LIMIT,
+        newestFirst: order === 'reverse',
       }
-      throw apiError;
-    }
-    const messages = response.value || [];
+    );
 
     if (messages.length === 0) {
       return {
@@ -461,26 +521,34 @@ async function handleExportConversation(args) {
     const date = formatDateForFilename(messages[0].receivedDateTime);
     const filenameBase = `${date}_${subject}_conversation`;
 
+    // Every file is written exclusively (never overwrites, never follows a
+    // symlink); a name already taken gets a -1, -2, … suffix.
+    const writeExport = (dir, base, extension, content) =>
+      writeClaimedFile(dir, base, extension, null, content, 'utf8');
+
     const exportedFiles = [];
     const exportStats = { messages: messages.length, attachments: 0, bytes: 0 };
 
     switch (format) {
       case 'eml': {
-        // Export each message as individual .eml file
-        const emlDir = path.join(resolvedDir, filenameBase);
-        if (!fs.existsSync(emlDir)) {
-          fs.mkdirSync(emlDir, { recursive: true });
-        }
+        // Export each message as individual .eml file, into a directory this
+        // export creates (never an existing one, which could be a symlink).
+        const emlDir = makeClaimedDir(resolvedDir, filenameBase);
 
         for (let i = 0; i < messages.length; i++) {
           const msg = messages[i];
-          const mimeContent = await callGraphAPIRaw(accessToken, msg.id);
+          const mimeContent = await callGraphAPIRaw(
+            accessToken,
+            msg.id,
+            prefix
+          );
           const msgDate = formatDateForFilename(msg.receivedDateTime);
-          const emlPath = path.join(
+          const emlPath = writeExport(
             emlDir,
-            `${i + 1}_${msgDate}_${sanitizeForFilename(msg.from?.emailAddress?.name || 'unknown', 20)}.eml`
+            `${i + 1}_${msgDate}_${sanitizeForFilename(msg.from?.emailAddress?.name || 'unknown', 20)}`,
+            'eml',
+            mimeContent
           );
-          fs.writeFileSync(emlPath, mimeContent, 'utf8');
           exportStats.bytes += Buffer.byteLength(mimeContent, 'utf8');
           exportedFiles.push(emlPath);
         }
@@ -489,11 +557,14 @@ async function handleExportConversation(args) {
 
       case 'mbox': {
         // Export all messages to single MBOX file
-        const mboxPath = path.join(resolvedDir, `${filenameBase}.mbox`);
         let mboxContent = '';
 
         for (const msg of messages) {
-          const mimeContent = await callGraphAPIRaw(accessToken, msg.id);
+          const mimeContent = await callGraphAPIRaw(
+            accessToken,
+            msg.id,
+            prefix
+          );
           const from = msg.from?.emailAddress?.address || 'unknown@unknown.com';
           const msgDate = new Date(msg.receivedDateTime);
           const mboxDate = msgDate.toUTCString().replace('GMT', '+0000');
@@ -504,7 +575,12 @@ async function handleExportConversation(args) {
           mboxContent += '\n\n';
         }
 
-        fs.writeFileSync(mboxPath, mboxContent, 'utf8');
+        const mboxPath = writeExport(
+          resolvedDir,
+          filenameBase,
+          'mbox',
+          mboxContent
+        );
         exportStats.bytes = Buffer.byteLength(mboxContent, 'utf8');
         exportedFiles.push(mboxPath);
         break;
@@ -512,7 +588,6 @@ async function handleExportConversation(args) {
 
       case 'markdown': {
         // Export as threaded Markdown document
-        const mdPath = path.join(resolvedDir, `${filenameBase}.md`);
         const mdContent = [];
 
         mdContent.push(
@@ -559,7 +634,7 @@ async function handleExportConversation(args) {
         }
 
         const content = mdContent.join('\n');
-        fs.writeFileSync(mdPath, content, 'utf8');
+        const mdPath = writeExport(resolvedDir, filenameBase, 'md', content);
         exportStats.bytes = Buffer.byteLength(content, 'utf8');
         exportedFiles.push(mdPath);
         break;
@@ -567,7 +642,6 @@ async function handleExportConversation(args) {
 
       case 'json': {
         // Export as JSON
-        const jsonPath = path.join(resolvedDir, `${filenameBase}.json`);
         const jsonContent = JSON.stringify(
           {
             conversationId,
@@ -580,7 +654,12 @@ async function handleExportConversation(args) {
           2
         );
 
-        fs.writeFileSync(jsonPath, jsonContent, 'utf8');
+        const jsonPath = writeExport(
+          resolvedDir,
+          filenameBase,
+          'json',
+          jsonContent
+        );
         exportStats.bytes = Buffer.byteLength(jsonContent, 'utf8');
         exportedFiles.push(jsonPath);
         break;
@@ -588,7 +667,6 @@ async function handleExportConversation(args) {
 
       case 'html': {
         // Export as HTML document
-        const htmlPath = path.join(resolvedDir, `${filenameBase}.html`);
         const htmlContent = [];
 
         htmlContent.push('<!DOCTYPE html>');
@@ -645,7 +723,12 @@ async function handleExportConversation(args) {
 
         htmlContent.push('</body></html>');
         const content = htmlContent.join('\n');
-        fs.writeFileSync(htmlPath, content, 'utf8');
+        const htmlPath = writeExport(
+          resolvedDir,
+          filenameBase,
+          'html',
+          content
+        );
         exportStats.bytes = Buffer.byteLength(content, 'utf8');
         exportedFiles.push(htmlPath);
         break;
@@ -653,9 +736,13 @@ async function handleExportConversation(args) {
 
       case 'csv': {
         // Export as CSV
-        const csvPath = path.join(resolvedDir, `${filenameBase}.csv`);
         const csvContent = formatEmailsAsCSV(messages);
-        fs.writeFileSync(csvPath, csvContent, 'utf8');
+        const csvPath = writeExport(
+          resolvedDir,
+          filenameBase,
+          'csv',
+          csvContent
+        );
         exportStats.bytes = Buffer.byteLength(csvContent, 'utf8');
         exportedFiles.push(csvPath);
         break;
@@ -677,6 +764,7 @@ async function handleExportConversation(args) {
     output.push(`**Subject**: ${messages[0].subject || '(no subject)'}`);
     output.push(`**Format**: ${format.toUpperCase()}`);
     output.push(`**Messages**: ${exportStats.messages}`);
+    if (truncated) output.push(truncationNote(exportStats.messages));
     output.push(`**Total Size**: ${sizeFormatted}`);
     output.push(`**Output Directory**: ${resolvedDir}\n`);
     output.push('## Exported Files\n');
@@ -695,6 +783,7 @@ async function handleExportConversation(args) {
         messageCount: exportStats.messages,
         bytes: exportStats.bytes,
         files: exportedFiles,
+        truncated,
       },
     };
   } catch (error) {

package/email/delta.js

@@ -8,21 +8,99 @@ const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { formatEmailList, VERBOSITY } = require('../utils/response-formatter');
 const { getEmailFields } = require('../utils/field-presets');
+const { buildMailboxPrefix } = require('../utils/mailbox');
+const { resolveFolder, looksLikeFolderId } = require('../folder/resolve');
+
+/**
+ * Extract the mailbox segment (`me` or `users/{address}`) from a delta/
+ * continuation token URL. Returns null when the token carries no mailbox
+ * segment we can recognise (e.g. an opaque or relative value) — those are
+ * passed through untouched for backward compatibility.
+ * @param {string} token - Delta or continuation token (a full Graph URL)
+ * @returns {string|null} - Mailbox prefix found in the token path, or null
+ */
+function mailboxFromToken(token) {
+  let pathname = token;
+  try {
+    pathname = new URL(token).pathname;
+  } catch {
+    // Not an absolute URL — match against the raw value.
+  }
+  const match = pathname.match(/(?:^|\/)(me|users\/[^/]+)(?:\/|$)/i);
+  if (!match) {
+    return null;
+  }
+  // Token URLs carry the percent-encoded form; local prefixes are raw.
+  // Decode so the two compare on equal footing.
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return match[1];
+  }
+}
+
+/**
+ * Decide whether a delta token's mailbox clearly differs from the target.
+ * Only identifiers of the same kind are compared: `me` against `me`, or an
+ * address against an address. Graph may hand back continuation links that
+ * name the mailbox by object ID (`users/<guid>`), which can't be matched to an
+ * address locally, so those are let through rather than wrongly rejected.
+ * @param {string} tokenMailbox - Mailbox segment from the token (`me` or `users/...`)
+ * @param {string} prefix - Mailbox prefix for this call (`me` or `users/...`)
+ * @returns {boolean} - True when the two identifiably name different mailboxes
+ */
+function mailboxesConflict(tokenMailbox, prefix) {
+  const token = tokenMailbox.toLowerCase();
+  const target = prefix.toLowerCase();
+  if (token === target) return false;
+  const isAddress = (p) => p.startsWith('users/') && p.includes('@');
+  if (token === 'me' || target === 'me') {
+    // `me` versus a named mailbox is a mismatch, unless the named one is an
+    // opaque object ID that could be the signed-in user.
+    const other = token === 'me' ? target : token;
+    return isAddress(other);
+  }
+  return isAddress(token) && isAddress(target);
+}
+
+const DEFAULT_PAGE_SIZE = 100;
+const MAX_PAGE_SIZE = 200;
+
+/**
+ * Turn the caller's `maxResults` into a delta page size: an integer from 1 to
+ * 200. Missing or non-numeric values give the default (100); fractions are
+ * floored; zero and negatives become 1; anything over 200 becomes 200.
+ * @param {*} value - Raw `maxResults` argument
+ * @returns {number} - Page size to request
+ */
+function clampPageSize(value) {
+  const n =
+    typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+  if (typeof n !== 'number' || !Number.isFinite(n)) {
+    return DEFAULT_PAGE_SIZE;
+  }
+  return Math.min(Math.max(Math.floor(n), 1), MAX_PAGE_SIZE);
+}
 
 /**
  * List emails delta handler - incremental sync
  * @param {object} args - Tool arguments
  * @param {string} [args.folder] - Folder to sync (default: inbox)
  * @param {string} [args.deltaToken] - Token from previous delta call (omit for initial sync)
- * @param {number} [args.maxResults] - Max results per page (default: 100)
+ * @param {number} [args.maxResults] - Page size, 1-200 (default: 100). Sent as
+ *   `Prefer: odata.maxpagesize` on every page; `$top` would cap the whole sync.
  * @param {string} [args.outputVerbosity] - Output detail level
  * @returns {object} - MCP response with emails, deltaToken, and change summary
  */
 async function handleListEmailsDelta(args) {
   const folder = args.folder || 'inbox';
   const deltaToken = args.deltaToken;
-  const maxResults = Math.min(args.maxResults || 100, 200);
+  const maxResults = clampPageSize(args.maxResults);
   const verbosity = args.outputVerbosity || 'standard';
+  // Optional: scope the delta sync to a shared/delegated mailbox rather than
+  // the signed-in account. Accepts a custom/localized folder name or path.
+  const sharedMailbox = args.sharedMailbox || args.email || null;
+  const prefix = buildMailboxPrefix(sharedMailbox);
 
   try {
     const accessToken = await ensureAuthenticated();
@@ -32,24 +110,52 @@ async function handleListEmailsDelta(args) {
     let queryParams = {};
 
     if (deltaToken) {
-      // Continue from previous sync - use deltaLink directly
+      // Continue from previous sync - use deltaLink directly. The token is
+      // authoritative: it already encodes the mailbox and folder, so the
+      // `folder`/`sharedMailbox` args are ignored. Reject a token from a
+      // different mailbox rather than silently syncing the wrong one.
+      const tokenMailbox = mailboxFromToken(deltaToken);
+      if (tokenMailbox && mailboxesConflict(tokenMailbox, prefix)) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text:
+                `Delta token mailbox mismatch: the token belongs to \`${tokenMailbox}\` but this call targets \`${prefix}\`.\n\n` +
+                'A delta token is bound to the mailbox and folder it was issued for. Use the token from that same mailbox/folder, or omit `deltaToken` to start a fresh initial sync here.',
+            },
+          ],
+        };
+      }
       endpoint = deltaToken;
     } else {
-      // Initial sync - start fresh
-      endpoint = `me/mailFolders/${folder}/messages/delta`;
-      queryParams = {
-        $select: getEmailFields('delta'),
-        $top: maxResults.toString(),
-      };
+      // Initial sync - start fresh. Resolve the folder (well-known name,
+      // nested path, display name, or raw ID) within the target mailbox so
+      // custom subfolders work for shared mailboxes too.
+      // Resolution failures (not-found / ambiguous) carry their own actionable
+      // message; let them propagate to the handler's catch like any other error.
+      // A raw folder ID (accepted here before name resolution existed) is
+      // treated as an ID, not searched for as a display name.
+      const resolved = await resolveFolder(
+        accessToken,
+        looksLikeFolderId(folder)
+          ? { id: folder, mailbox: sharedMailbox }
+          : { name: folder, mailbox: sharedMailbox }
+      );
+      endpoint = `${prefix}/mailFolders/${resolved.id}/messages/delta`;
+      // No `$top`: on messages/delta it caps the whole sync, not the page.
+      queryParams = { $select: getEmailFields('delta') };
     }
 
-    // Fetch delta results
+    // Fetch delta results. Graph honours the page size only on requests that
+    // carry the Prefer header, so continuation calls must send it too.
     const response = await callGraphAPI(
       accessToken,
       'GET',
       endpoint,
       null,
-      deltaToken ? {} : queryParams
+      queryParams,
+      { Prefer: `odata.maxpagesize=${maxResults}` }
     );
 
     // Process results
@@ -151,7 +257,7 @@ async function handleListEmailsDelta(args) {
       // Pagination info
       if (hasMoreChanges) {
         resultText += `\n### More Pages Available\n`;
-        resultText += `This page returned a continuation token. Call \`search-emails deltaMode=true deltaToken=<token>\` again to fetch the next page. The real delta token only emits once paging completes.\n`;
+        resultText += `This page returned a continuation token. Call \`search-emails deltaMode=true deltaToken=<token>\` again to fetch the next page, and pass the same \`maxResults\` on every page to keep the page size. The real delta token only emits once paging completes.\n`;
       }
 
       // Token (delta or continuation)
@@ -175,7 +281,11 @@ async function handleListEmailsDelta(args) {
       ],
       _meta: {
         syncType: isInitialSync ? 'initial' : 'incremental',
-        folder: folder,
+        mailbox: sharedMailbox || 'me',
+        // With a token the folder comes from the token, not the `folder` arg
+        // (which is ignored) — don't echo a value we didn't use.
+        folder: isInitialSync ? folder : null,
+        folderSource: isInitialSync ? 'argument' : 'deltaToken',
         itemCount: processedEmails.length,
         hasMoreChanges: hasMoreChanges,
         changesSummary: changesSummary,