@littlebearapps/outlook-assistant 3.8.2 → 3.9.1

package/folder/delete.js

@@ -3,26 +3,21 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
-const { getFolderIdByName } = require('../email/folder-utils');
-
-/**
- * Protected folder names that cannot be deleted
- */
-const PROTECTED_FOLDERS = [
-  'inbox',
-  'drafts',
-  'sentitems',
-  'deleteditems',
-  'junkemail',
-  'archive',
-  'outbox',
-];
+const { resolveFolder, WELL_KNOWN } = require('./resolve');
 
 /**
  * Delete folder handler
+ *
+ * System folders are guarded by NAME/alias below — `WELL_KNOWN` covers the
+ * Graph names, display-name variants ("Sent Items", "Deleted Items") and short
+ * aliases ("sent"/"junk"/"spam"). A raw `folderId` that happens to point at a
+ * system folder is backstopped by Graph, which rejects deleting distinguished
+ * folders (mailFolder exposes no selectable `wellKnownName`, so we can't cheaply
+ * re-check protection on a resolved-by-ID folder).
+ *
  * @param {object} args - Tool arguments
  * @param {string} [args.folderId] - Folder ID to delete
- * @param {string} [args.folderName] - Folder name to delete (resolved to ID)
+ * @param {string} [args.folderName] - Folder name/path to delete (resolved to ID)
  * @returns {object} - MCP response
  */
 async function handleDeleteFolder(args) {
@@ -39,8 +34,8 @@ async function handleDeleteFolder(args) {
     };
   }
 
-  // Guard against deleting protected folders
-  if (folderName && PROTECTED_FOLDERS.includes(folderName.toLowerCase())) {
+  // Name/alias guard for the common accidental case.
+  if (folderName && WELL_KNOWN[folderName.toLowerCase().trim()]) {
     return {
       content: [
         {
@@ -54,32 +49,27 @@ async function handleDeleteFolder(args) {
   try {
     const accessToken = await ensureAuthenticated();
 
-    let resolvedId = folderId;
-
-    // Resolve folder name to ID if needed
-    if (!resolvedId && folderName) {
-      resolvedId = await getFolderIdByName(accessToken, folderName);
-      if (!resolvedId) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Folder "${folderName}" not found. Use folders (action=list) to see available folders.`,
-            },
-          ],
-        };
-      }
+    // Resolve (by name/path OR explicit ID) so nested folders are addressable
+    // and the confirmation can report the full path. (#216)
+    let resolved;
+    try {
+      resolved = await resolveFolder(accessToken, {
+        id: folderId,
+        name: folderName,
+      });
+    } catch (resolveError) {
+      return {
+        content: [{ type: 'text', text: resolveError.message }],
+      };
     }
 
     // Delete the folder
-    await callGraphAPI(accessToken, 'DELETE', `me/mailFolders/${resolvedId}`);
-
-    const displayName = folderName || resolvedId;
+    await callGraphAPI(accessToken, 'DELETE', `me/mailFolders/${resolved.id}`);
     return {
       content: [
         {
           type: 'text',
-          text: `Folder "${displayName}" deleted successfully.`,
+          text: `Folder "${resolved.path}" deleted successfully.`,
         },
       ],
     };

package/folder/index.js

@@ -12,7 +12,7 @@ const folderTools = [
   {
     name: 'folders',
     description:
-      'Manage mail folders (tool-level destructiveHint=true because `delete` permanently removes a folder; `list` and `stats` are read-only sub-actions despite the annotation). action=`list` (default) returns the folder tree with id/displayName/parentFolderId (toggle `includeItemCounts` for unread/total, `includeChildren` for hierarchy). action=`create` makes a new folder under the inbox (or under `folder`/`folderId`/`folderName`) and returns its id. action=`move` relocates emails (`emailIds` array) into `targetFolder`. action=`stats` returns counts (totalItemCount/unreadItemCount) suitable for pagination planning — pair with `outputVerbosity` to limit noise. action=`delete` permanently removes a folder and its contents — there is no recycle-bin recovery.',
+      "Manage mail folders (tool-level destructiveHint=true because `delete` permanently removes a folder; `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 — on Outlook.com the folder is moved to Deleted Items (recoverable until you empty it); M365/Exchange accounts may hard-delete per retention policy.",
     annotations: {
       title: 'Mail Folders',
       readOnlyHint: false,
@@ -43,7 +43,13 @@ const folderTools = [
         },
         parentFolder: {
           type: 'string',
-          description: 'Parent folder name, default is root (action=create)',
+          description:
+            'Parent folder name or path (e.g. "Clients/Acme"); default is root (action=create)',
+        },
+        parentFolderId: {
+          type: 'string',
+          description:
+            'Parent folder ID — alternative to parentFolder for unambiguous targeting (action=create)',
         },
         // move params
         emailIds: {
@@ -53,7 +59,13 @@ const folderTools = [
         },
         targetFolder: {
           type: 'string',
-          description: 'Folder name to move emails to (action=move, required)',
+          description:
+            'Destination folder name or path, e.g. "Triage/Delete" (action=move; or use targetFolderId)',
+        },
+        targetFolderId: {
+          type: 'string',
+          description:
+            'Destination folder ID — alternative to targetFolder for unambiguous/nested targeting (action=move)',
         },
         sourceFolder: {
           type: 'string',
@@ -63,22 +75,22 @@ const folderTools = [
         folder: {
           type: 'string',
           description:
-            'Folder name (inbox, sent, drafts, etc.). Default: inbox (action=stats)',
+            'Folder name or path (inbox, sent, "Triage/Delete", etc.). Default: inbox (action=stats)',
         },
         outputVerbosity: {
           type: 'string',
           enum: ['minimal', 'standard', 'full'],
           description: 'Output detail level (action=stats, default: standard)',
         },
-        // delete params
+        // delete/stats params
         folderId: {
           type: 'string',
-          description: 'Folder ID to delete (action=delete)',
+          description: 'Folder ID (action=stats/delete)',
         },
         folderName: {
           type: 'string',
           description:
-            'Folder name to delete — resolved to ID (action=delete). Cannot delete protected folders (Inbox, Drafts, Sent, etc.)',
+            'Folder name or path to delete — resolved to ID (action=delete). Cannot delete protected folders (Inbox, Drafts, Sent, etc.)',
         },
       },
       additionalProperties: false,

package/folder/list.js

@@ -1,8 +1,8 @@
 /**
  * List folders functionality
  */
-const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { listChildFolders } = require('./resolve');
 
 /**
  * List folders handler
@@ -74,73 +74,54 @@ async function handleListFolders(args) {
  * @returns {Promise<Array>} - Array of folder objects with hierarchy
  */
 async function getAllFoldersHierarchy(accessToken, includeItemCounts) {
-  try {
-    // Determine select fields based on whether to include counts
-    const selectFields = includeItemCounts
-      ? 'id,displayName,parentFolderId,childFolderCount,totalItemCount,unreadItemCount'
-      : 'id,displayName,parentFolderId,childFolderCount';
-
-    // Get all mail folders
-    const response = await callGraphAPI(
-      accessToken,
-      'GET',
-      'me/mailFolders',
-      null,
-      {
-        $top: 100,
-        $select: selectFields,
-      }
-    );
-
-    if (!response.value) {
-      return [];
+  // Determine select fields based on whether to include counts
+  const selectFields = includeItemCounts
+    ? 'id,displayName,parentFolderId,childFolderCount,totalItemCount,unreadItemCount'
+    : 'id,displayName,parentFolderId,childFolderCount';
+
+  // Full recursive, paginated walk so nested folders at ANY depth appear with
+  // their complete path (not just one level). (#216 review)
+  const top = await listChildFolders(accessToken, null, selectFields);
+  const all = [];
+  const visited = new Set();
+  const queue = top.map((folder) => ({
+    folder,
+    path: folder.displayName,
+    parentPath: null,
+    depth: 1,
+    isTopLevel: true,
+  }));
+
+  for (let i = 0; i < queue.length; i++) {
+    const { folder, path, parentPath, depth, isTopLevel } = queue[i];
+    if (visited.has(folder.id)) {
+      continue;
     }
+    visited.add(folder.id);
+    all.push({ ...folder, path, parentFolder: parentPath, isTopLevel });
 
-    // Get child folders for folders with children
-    const foldersWithChildren = response.value.filter(
-      (f) => f.childFolderCount > 0
-    );
-
-    const childFolderPromises = foldersWithChildren.map(async (folder) => {
+    if (folder.childFolderCount > 0 && depth < 20) {
+      let children;
       try {
-        const childResponse = await callGraphAPI(
-          accessToken,
-          'GET',
-          `me/mailFolders/${folder.id}/childFolders`,
-          null,
-          { $select: selectFields }
-        );
-
-        // Add parent folder info to each child
-        const childFolders = childResponse.value || [];
-        childFolders.forEach((child) => {
-          child.parentFolder = folder.displayName;
-        });
-
-        return childFolders;
+        children = await listChildFolders(accessToken, folder.id, selectFields);
       } catch (error) {
         console.error(
           `Error getting child folders for "${folder.displayName}": ${error.message}`
         );
-        return [];
+        continue;
       }
-    });
-
-    const childFolders = await Promise.all(childFolderPromises);
-    const allChildFolders = childFolders.flat();
-
-    // Add top-level flag to parent folders
-    const topLevelFolders = response.value.map((folder) => ({
-      ...folder,
-      isTopLevel: true,
-    }));
-
-    // Combine all folders
-    return [...topLevelFolders, ...allChildFolders];
-  } catch (error) {
-    console.error(`Error getting all folders: ${error.message}`);
-    throw error;
+      for (const child of children) {
+        queue.push({
+          folder: child,
+          path: `${path}/${child.displayName}`,
+          parentPath: path,
+          depth: depth + 1,
+          isTopLevel: false,
+        });
+      }
+    }
   }
+  return all;
 }
 
 /**
@@ -184,14 +165,13 @@ function formatFolderList(folders, includeItemCounts) {
     return a.displayName.localeCompare(b.displayName);
   });
 
-  // Format each folder
+  // Format each folder. Emit the full path and folder ID so callers can
+  // address nested folders directly — `folders move targetFolder="Parent/Child"`
+  // or `targetFolderId=...`. (#216)
   const folderLines = sortedFolders.map((folder) => {
-    let folderInfo = folder.displayName;
-
-    // Add parent folder info if available
-    if (folder.parentFolder) {
-      folderInfo += ` (in ${folder.parentFolder})`;
-    }
+    // Full path (computed during the recursive walk) so nested folders are
+    // addressable directly. (#216)
+    let folderInfo = folder.path || folder.displayName;
 
     // Add item counts if requested
     if (includeItemCounts) {
@@ -204,6 +184,8 @@ function formatFolderList(folders, includeItemCounts) {
       }
     }
 
+    folderInfo += ` [id: ${folder.id}]`;
+
     return folderInfo;
   });
 
@@ -269,6 +251,9 @@ function formatFolderHierarchy(folders, includeItemCounts) {
       }
     }
 
+    // Surface the folder ID so callers can address it directly. (#216)
+    line += ` [id: ${folder.id}]`;
+
     // Add children
     const childLines = folder.children
       .map((childId) => formatSubtree(childId, level + 1))

package/folder/move.js

@@ -3,7 +3,7 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
-const { getFolderIdByName } = require('../email/folder-utils');
+const { resolveFolder } = require('./resolve');
 
 /**
  * Move emails handler
@@ -13,6 +13,7 @@ const { getFolderIdByName } = require('../email/folder-utils');
 async function handleMoveEmails(args) {
   const emailIds = args.emailIds || '';
   const targetFolder = args.targetFolder || '';
+  const targetFolderId = args.targetFolderId || '';
   const sourceFolder = args.sourceFolder || '';
 
   if (!emailIds) {
@@ -26,12 +27,12 @@ async function handleMoveEmails(args) {
     };
   }
 
-  if (!targetFolder) {
+  if (!targetFolder && !targetFolderId) {
     return {
       content: [
         {
           type: 'text',
-          text: 'Target folder name is required.',
+          text: 'Target folder is required — pass `targetFolder` (name or "Parent/Child" path) or `targetFolderId`.',
         },
       ],
     };
@@ -62,7 +63,7 @@ async function handleMoveEmails(args) {
     const result = await moveEmailsToFolder(
       accessToken,
       ids,
-      targetFolder,
+      { name: targetFolder, id: targetFolderId },
       sourceFolder
     );
 
@@ -101,28 +102,27 @@ async function handleMoveEmails(args) {
  * Move emails to a folder
  * @param {string} accessToken - Access token
  * @param {Array<string>} emailIds - Array of email IDs to move
- * @param {string} targetFolderName - Name of the target folder
+ * @param {{name?: string, id?: string}} targetSpec - Target folder name/path or ID
  * @param {string} sourceFolderName - Name of the source folder (optional)
  * @returns {Promise<object>} - Result object with status and message
  */
 async function moveEmailsToFolder(
   accessToken,
   emailIds,
-  targetFolderName,
+  targetSpec,
   _sourceFolderName
 ) {
   try {
-    // Get the target folder ID
-    const targetFolderId = await getFolderIdByName(
-      accessToken,
-      targetFolderName
-    );
-    if (!targetFolderId) {
-      return {
-        success: false,
-        message: `Target folder "${targetFolderName}" not found. Please specify a valid folder name.`,
-      };
+    // Resolve the target folder (supports "Parent/Child" paths, aliases, and
+    // explicit IDs — nested folders are now addressable). (#216)
+    let target;
+    try {
+      target = await resolveFolder(accessToken, targetSpec);
+    } catch (resolveError) {
+      return { success: false, message: resolveError.message };
     }
+    const targetFolderId = target.id;
+    const targetLabel = target.path;
 
     // Track successful and failed moves
     const results = {
@@ -152,7 +152,7 @@ async function moveEmailsToFolder(
     let message = '';
 
     if (results.successful.length > 0) {
-      message += `Successfully moved ${results.successful.length} email(s) to "${targetFolderName}".`;
+      message += `Successfully moved ${results.successful.length} email(s) to "${targetLabel}".`;
     }
 
     if (results.failed.length > 0) {