@littlebearapps/outlook-assistant 3.13.0 → 3.14.1

package/folder/delete.js

@@ -3,8 +3,108 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
-const { resolveFolder, WELL_KNOWN } = require('./resolve');
+const { resolveFolder, listChildFolders, WELL_KNOWN } = require('./resolve');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { dryRunResult } = require('../utils/safety');
+
+const COUNT_FIELDS = 'totalItemCount,unreadItemCount';
+const COUNT_SELECT = `id,displayName,childFolderCount,${COUNT_FIELDS}`;
+/** Most subfolders a dry run counts before reporting "at least". */
+const PREVIEW_FOLDER_LIMIT = 100;
+
+const LOSS_NOTE =
+  "It doesn't go to Deleted Items, and Graph doesn't document a way to restore it (Outlook's \"Recover deleted items\" may work for a limited time, but don't rely on it). Move out anything you need first.";
+
+function plural(count, word) {
+  return `${count} ${word}${count === 1 ? '' : 's'}`;
+}
+
+/** The folder's quoted path, or its ID if Graph gave it no name. */
+function folderLabel(resolved, quote = "'") {
+  return resolved.path
+    ? `${quote}${resolved.path}${quote}`
+    : `(unnamed, id ${resolved.id})`;
+}
+
+/**
+ * Count every subfolder below `root`, and the items in them, breadth-first.
+ * Stops after PREVIEW_FOLDER_LIMIT subfolders and flags the count partial.
+ */
+async function countSubfolders(accessToken, root, mailbox) {
+  let subfolders = 0;
+  let items = 0;
+  let partial = false;
+  const queue = root.childFolderCount > 0 ? [root.id] : [];
+  while (queue.length > 0) {
+    if (subfolders >= PREVIEW_FOLDER_LIMIT) {
+      partial = true;
+      break;
+    }
+    const children = await listChildFolders(
+      accessToken,
+      queue.shift(),
+      COUNT_SELECT,
+      mailbox
+    );
+    for (const child of children) {
+      subfolders += 1;
+      items += child.totalItemCount || 0;
+      if (child.childFolderCount > 0) queue.push(child.id);
+    }
+  }
+  return { subfolders, items, partial };
+}
+
+/**
+ * dryRun preview for delete (#274): the folder, and the items and
+ * subfolders that would be lost with it. Reads only, and reads the folder
+ * itself only if resolving it didn't already (`resolved.fields`).
+ */
+async function previewDeleteFolder(accessToken, resolved, mailbox) {
+  const prefix = buildMailboxPrefix(mailbox);
+  const folder =
+    resolved.fields ||
+    (await callGraphAPI(
+      accessToken,
+      'GET',
+      `${prefix}/mailFolders/${resolved.id}`,
+      null,
+      { $select: COUNT_SELECT }
+    ));
+  const items = folder.totalItemCount || 0;
+  const unread = folder.unreadItemCount || 0;
+  const below = await countSubfolders(
+    accessToken,
+    { ...folder, id: resolved.id },
+    mailbox
+  );
+  const where = mailbox ? ` in ${mailbox}` : '';
+  const name = `${folderLabel(resolved)}${where}`;
+
+  let summary;
+  if (items === 0 && below.subfolders === 0) {
+    summary = `Deletes folder ${name}. It's empty: no items or subfolders.`;
+  } else {
+    const atLeast = below.partial ? 'at least ' : '';
+    summary = `Deletes folder ${name} and everything in it: ${plural(items, 'item')}`;
+    if (unread > 0) summary += ` (${unread} unread)`;
+    if (below.subfolders > 0) {
+      summary += `, plus ${atLeast}${plural(below.subfolders, 'subfolder')} holding ${atLeast}${below.items} more ${below.items === 1 ? 'item' : 'items'}`;
+    }
+    summary += '.';
+  }
+
+  return dryRunResult([summary, LOSS_NOTE], {
+    action: 'delete',
+    folderId: resolved.id,
+    path: resolved.path,
+    items,
+    subfolders: below.subfolders,
+    subfolderItems: below.items,
+    partial: below.partial,
+  });
+}
 
 /**
  * Delete folder handler
@@ -22,31 +122,19 @@ const { buildMailboxPrefix } = require('../utils/mailbox');
  * @returns {object} - MCP response
  */
 async function handleDeleteFolder(args) {
-  const { folderId, folderName } = args;
+  const { folderId, folderName, dryRun = false } = args;
   const sharedMailbox = args.sharedMailbox || args.email || null;
   const prefix = buildMailboxPrefix(sharedMailbox);
 
   if (!folderId && !folderName) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Either folderId or folderName is required.',
-        },
-      ],
-    };
+    return toolError('Either folderId or folderName is required.');
   }
 
   // Name/alias guard for the common accidental case.
   if (folderName && WELL_KNOWN[folderName.toLowerCase().trim()]) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Cannot delete protected folder "${folderName}". Protected folders: Inbox, Drafts, Sent Items, Deleted Items, Junk Email, Archive, Outbox.`,
-        },
-      ],
-    };
+    return toolError(
+      `Cannot delete protected folder "${folderName}". Protected folders: Inbox, Drafts, Sent Items, Deleted Items, Junk Email, Archive, Outbox.`
+    );
   }
 
   try {
@@ -60,11 +148,16 @@ async function handleDeleteFolder(args) {
         id: folderId,
         name: folderName,
         mailbox: sharedMailbox,
+        // A dry run by ID reads the counts in the same request.
+        ...(dryRun && { extraSelect: COUNT_FIELDS }),
       });
     } catch (resolveError) {
-      return {
-        content: [{ type: 'text', text: resolveError.message }],
-      };
+      return toolError(resolveError.message);
+    }
+
+    // dryRun: say what would be lost; delete nothing.
+    if (dryRun) {
+      return await previewDeleteFolder(accessToken, resolved, sharedMailbox);
     }
 
     // Delete the folder
@@ -77,29 +170,15 @@ async function handleDeleteFolder(args) {
       content: [
         {
           type: 'text',
-          text: `Folder "${resolved.path}" deleted successfully.`,
+          text: `Folder ${folderLabel(resolved, '"')} deleted successfully.`,
         },
       ],
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error deleting folder: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error deleting folder: ${error.message}`);
   }
 }
 

package/folder/index.js

@@ -6,19 +6,17 @@ const handleCreateFolder = require('./create');
 const handleMoveEmails = require('./move');
 const handleGetFolderStats = require('./stats');
 const handleDeleteFolder = require('./delete');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError } = require('../utils/tool-error');
+const { dryRunUnsupported } = require('../utils/safety');
 
 // Consolidated folder tool definition
 const folderTools = [
   {
     name: 'folders',
     description:
-      "Manage mail folders (tool-level destructiveHint=true because `delete` removes a folder and its contents; `list` and `stats` are read-only sub-actions despite the annotation). Folders can be addressed by name, by a slash-separated PATH for nested folders (e.g. `Triage/Delete`, `Inbox/Clients/Acme`, case-insensitive), or by explicit ID; `list` output includes each folder's full path and `[id: …]`. A bare name resolves a unique top-level folder first, then searches nested folders (ambiguous names return the candidates — disambiguate with a path or ID). action=`list` (default) returns the folder tree (toggle `includeItemCounts` for unread/total, `includeChildren` for hierarchy). action=`create` makes a new folder under the root, or under `parentFolder` (name/path) / `parentFolderId`, and returns its id. action=`move` relocates emails (`emailIds`) into `targetFolder` (name/path) or `targetFolderId`. action=`stats` returns counts (totalItemCount/unreadItemCount) for `folder` (name/path) or `folderId`, suitable for pagination planning. action=`delete` removes a folder (by `folderName`/path or `folderId`) and its contents — it does not go to Deleted Items, and Graph doesn't document whether it can be restored (some accounts may offer Outlook's \"Recover deleted items\" for a limited time, but don't rely on it), so move out anything you might need first. Every action accepts `sharedMailbox` (alias `email`) to target a shared/delegated mailbox instead of the signed-in account — folder names, paths, and IDs are then resolved inside that mailbox. Protected folders cannot be deleted in any mailbox.",
-    annotations: {
-      title: 'Mail Folders',
-      readOnlyHint: false,
-      destructiveHint: true,
-      openWorldHint: false,
-    },
+      "Manage mail folders. Address a folder by name, by slash-separated path for nested folders (e.g. `Inbox/Clients/Acme`, case-insensitive) or by ID; a bare name matches a unique top-level folder first, then nested ones (an ambiguous name returns the candidates). action=`list` (default) returns the tree with each folder's path and id (`includeItemCounts`, `includeChildren`). action=`create` makes `name` under the root or `parentFolder`/`parentFolderId`. action=`move` moves `emailIds` into `targetFolder`/`targetFolderId`. action=`stats` returns total/unread counts for `folder` or `folderId`. action=`delete` removes a folder (`folderName`/path or `folderId`) with everything in it, subfolders included. It skips Deleted Items and Graph documents no restore path, so pass `dryRun: true` first to see what would be lost. Protected folders (Inbox, Sent Items, etc.) can't be deleted. Every action accepts `sharedMailbox` (alias `email`) to work in a shared or delegated mailbox (default: your own).",
+    ...toolMetadata('folders', 'Mail Folders'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -40,7 +38,7 @@ const folderTools = [
         sharedMailbox: {
           type: 'string',
           description:
-            'Email address of a shared/delegated mailbox to target instead of the signed-in account (all actions). Requires delegate access + Mail.Read.Shared (list/stats) or Mail.ReadWrite.Shared (create/move/delete). Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+            'Email address of a shared/delegated mailbox to target (all actions; default: the signed-in account). Requires delegate access + Mail.Read.Shared (list/stats) or Mail.ReadWrite.Shared (create/move/delete). Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
         },
         email: {
           type: 'string',
@@ -79,7 +77,8 @@ const folderTools = [
         },
         sourceFolder: {
           type: 'string',
-          description: 'Source folder name, default is inbox (action=move)',
+          description:
+            'Ignored: action=move moves each email by ID from wherever it is. Accepted for older callers.',
         },
         // stats params
         folder: {
@@ -102,12 +101,20 @@ const folderTools = [
           description:
             'Folder name or path to delete — resolved to ID (action=delete). Cannot delete protected folders (Inbox, Drafts, Sent, etc.)',
         },
+        dryRun: {
+          type: 'boolean',
+          description:
+            'Preview only (action=delete): nothing is deleted. Shows the folder and how many items and subfolders would be lost. Other actions refuse dryRun and change nothing. Default false.',
+        },
       },
       additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
       const action = args.action || 'list';
+      if (args.dryRun && action !== 'delete') {
+        return dryRunUnsupported('folders', action, 'delete');
+      }
       switch (action) {
         case 'create':
           return handleCreateFolder(args);
@@ -120,14 +127,9 @@ const folderTools = [
         case 'list':
           return handleListFolders(args);
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Unknown action '${action}'. Valid actions: list, create, move, stats, delete.`,
-              },
-            ],
-          };
+          return toolError(
+            `Unknown action '${action}'. Valid actions: list, create, move, stats, delete.`
+          );
       }
     },
   },

package/folder/list.js

@@ -3,6 +3,8 @@
  */
 const { ensureAuthenticated } = require('../auth');
 const { listChildFolders } = require('./resolve');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 /**
  * List folders handler
@@ -52,24 +54,10 @@ async function handleListFolders(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error listing folders: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error listing folders: ${error.message}`);
   }
 }
 
@@ -133,7 +121,7 @@ async function getAllFoldersHierarchy(
           sharedMailbox
         );
       } catch (error) {
-        console.error(
+        log.debug(
           `Error getting child folders for "${folder.displayName}": ${error.message}`
         );
         warnings.push(

package/folder/move.js

@@ -5,6 +5,8 @@ const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolder } = require('./resolve');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 /**
  * Move emails handler
@@ -19,25 +21,15 @@ async function handleMoveEmails(args) {
   const sharedMailbox = args.sharedMailbox || args.email || null;
 
   if (!emailIds) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Email IDs are required. Please provide a comma-separated list of email IDs to move.',
-        },
-      ],
-    };
+    return toolError(
+      'Email IDs are required. Please provide a comma-separated list of email IDs to move.'
+    );
   }
 
   if (!targetFolder && !targetFolderId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Target folder is required — pass `targetFolder` (name or "Parent/Child" path) or `targetFolderId`.',
-        },
-      ],
-    };
+    return toolError(
+      'Target folder is required — pass `targetFolder` (name or "Parent/Child" path) or `targetFolderId`.'
+    );
   }
 
   try {
@@ -51,14 +43,7 @@ async function handleMoveEmails(args) {
       .filter((id) => id);
 
     if (ids.length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: 'No valid email IDs provided.',
-          },
-        ],
-      };
+      return toolError('No valid email IDs provided.');
     }
 
     // Move emails
@@ -85,24 +70,10 @@ async function handleMoveEmails(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error moving emails: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error moving emails: ${error.message}`);
   }
 }
 
@@ -157,7 +128,7 @@ async function moveEmailsToFolder(
           newId: moved?.id || emailId,
         });
       } catch (error) {
-        console.error(`Error moving email ${emailId}: ${error.message}`);
+        log.debug(`Error moving email ${emailId}: ${error.message}`);
         results.failed.push({
           id: emailId,
           error: error.message,
@@ -203,7 +174,7 @@ async function moveEmailsToFolder(
       results,
     };
   } catch (error) {
-    console.error(`Error in moveEmailsToFolder: ${error.message}`);
+    log.debug(`Error in moveEmailsToFolder: ${error.message}`);
     throw error;
   }
 }

package/folder/resolve.js

@@ -132,15 +132,18 @@ async function resolveWellKnown(accessToken, alias, mailbox) {
   return toRecord(resp, resp.displayName);
 }
 
-async function resolveById(accessToken, id, mailbox) {
+async function resolveById(accessToken, id, mailbox, extraSelect) {
   const resp = await callGraphAPI(
     accessToken,
     'GET',
     `${buildMailboxPrefix(mailbox)}/mailFolders/${id}`,
     null,
-    { $select: FOLDER_SELECT }
+    { $select: extraSelect ? `${FOLDER_SELECT},${extraSelect}` : FOLDER_SELECT }
   );
-  return toRecord(resp, resp.displayName);
+  // The ID asked for stands in if a response leaves `id` out.
+  const folder = { ...resp, id: resp?.id || id };
+  const record = toRecord(folder, folder.displayName);
+  return extraSelect ? { ...record, fields: folder } : record;
 }
 
 /**
@@ -300,8 +303,10 @@ function looksLikeFolderId(value) {
 /**
  * Resolve a folder from a name/path and/or explicit ID.
  * @param {string} accessToken
- * @param {{name?: string, id?: string, mailbox?: string|null}} spec
- * @returns {Promise<{id: string, displayName: string, parentId: string|null, path: string}>}
+ * @param {{name?: string, id?: string, mailbox?: string|null, extraSelect?: string}} spec
+ *   `extraSelect`: more fields to read when resolving by ID (e.g. item
+ *   counts), returned as `fields` so the caller needn't read the folder again
+ * @returns {Promise<{id: string, displayName: string, parentId: string|null, path: string, fields?: object}>}
  *   `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).
@@ -310,7 +315,7 @@ async function resolveFolder(accessToken, spec = {}) {
   const mailbox = spec.mailbox || null;
   const id = (spec.id || '').trim();
   if (id) {
-    return resolveById(accessToken, id, mailbox);
+    return resolveById(accessToken, id, mailbox, spec.extraSelect);
   }
   const name = (spec.name || '').trim();
   if (!name) {

package/folder/stats.js

@@ -9,6 +9,8 @@ const { ensureAuthenticated } = require('../auth');
 const { resolveFolder } = require('./resolve');
 const { buildMailboxPrefix } = require('../utils/mailbox');
 const config = require('../config');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 const { VERBOSITY, DEFAULT_LIMITS } = config;
 
@@ -36,9 +38,7 @@ async function handleGetFolderStats(args) {
         mailbox: sharedMailbox,
       });
     } catch (resolveError) {
-      return {
-        content: [{ type: 'text', text: resolveError.message }],
-      };
+      return toolError(resolveError.message);
     }
     const folderId = resolved.id;
 
@@ -75,24 +75,10 @@ async function handleGetFolderStats(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error getting folder stats: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error getting folder stats: ${error.message}`);
   }
 }
 
@@ -139,7 +125,7 @@ async function getEmailDateRange(accessToken, folderId, mailbox = null) {
       return { newest, oldest };
     }
   } catch (error) {
-    console.error(`Error getting date range: ${error.message}`);
+    log.debug(`Error getting date range: ${error.message}`);
   }
 
   return null;
@@ -194,8 +180,10 @@ function formatFolderStats(folder, dateRange, verbosity) {
       text += `| Date Range | ${oldest} to ${newest} |\n`;
     }
 
-    if (totalItems > 100) {
-      text += `\n_Hint: Use list-emails-delta for efficient incremental sync of large folders._`;
+    // List mode returns at most 50 with no page cursor, so anything bigger
+    // needs delta sync to read in full.
+    if (totalItems > 50) {
+      text += `\n_Hint: Use \`search-emails\` with \`deltaMode: true\` for efficient incremental sync of large folders._`;
     }
 
     return { text, meta };
@@ -224,7 +212,10 @@ function formatFolderStats(folder, dateRange, verbosity) {
   text += `|---------|-------|\n`;
   text += `| Page Size | ${pageSize} emails |\n`;
   text += `| Total Pages | ${totalPages} |\n`;
-  text += `| Estimated API Calls | ${totalPages} (list-emails) |\n`;
+  text +=
+    totalItems > 50
+      ? `| Estimated API Calls | ${Math.ceil(totalItems / 100)} (\`search-emails\` \`deltaMode: true\`, 100 per page; list mode stops at 50) |\n`
+      : `| Estimated API Calls | 1 (\`search-emails\` list mode, \`count\` up to 50) |\n`;
 
   if (dateRange) {
     const newestDate = new Date(dateRange.newest);
@@ -247,12 +238,12 @@ function formatFolderStats(folder, dateRange, verbosity) {
   text += `\n## Recommendations\n\n`;
 
   if (totalItems > 1000) {
-    text += `- **Large folder**: Use \`list-emails-delta\` for incremental sync\n`;
+    text += `- **Large folder**: Use \`search-emails\` with \`deltaMode: true\` for incremental sync\n`;
     text += `- **Use date filters**: \`receivedAfter\` and \`receivedBefore\` to narrow scope\n`;
-  } else if (totalItems > 100) {
-    text += `- **Medium folder**: Consider using \`list-emails-delta\` for efficient updates\n`;
+  } else if (totalItems > 50) {
+    text += `- **Medium folder**: Consider \`search-emails\` with \`deltaMode: true\` for efficient updates\n`;
   } else {
-    text += `- **Small folder**: \`list-emails\` with default pagination is efficient\n`;
+    text += `- **Small folder**: \`search-emails\` in list mode (raise \`count\` up to 50) is enough\n`;
   }
 
   if (unreadItems > 50) {