@littlebearapps/outlook-assistant 3.5.2 → 3.7.0

package/rules/rule-builder.js

@@ -0,0 +1,284 @@
+/**
+ * Shared rule builder utilities for creating and updating mail rules.
+ * Converts flat MCP tool parameters into Microsoft Graph API rule objects.
+ */
+const { getFolderIdByName } = require('../email/folder-utils');
+const { checkRecipientAllowlist } = require('../utils/safety');
+
+const VALID_IMPORTANCE = ['low', 'normal', 'high'];
+const VALID_SENSITIVITY = ['normal', 'personal', 'private', 'confidential'];
+
+/**
+ * Parse a comma-separated string into a trimmed, non-empty array.
+ * @param {string} str - Comma-separated values
+ * @returns {string[]}
+ */
+function parseCommaSeparated(str) {
+  if (!str) return [];
+  return str
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Convert a comma-separated email string into Graph API recipient objects.
+ * @param {string} emailString - Comma-separated email addresses
+ * @returns {Array<{emailAddress: {address: string}}>}
+ */
+function formatRecipientObjects(emailString) {
+  return parseCommaSeparated(emailString).map((email) => ({
+    emailAddress: { address: email },
+  }));
+}
+
+/**
+ * Build a Graph API conditions object from flat tool parameters.
+ * @param {object} args - Tool arguments
+ * @returns {{ conditions: object, warnings: string[] }}
+ */
+function buildConditions(args) {
+  const conditions = {};
+  const warnings = [];
+
+  // String collections (comma-separated → array with OR logic)
+  if (args.containsSubject) {
+    conditions.subjectContains = parseCommaSeparated(args.containsSubject);
+  }
+  if (args.bodyContains) {
+    conditions.bodyContains = parseCommaSeparated(args.bodyContains);
+  }
+  if (args.bodyOrSubjectContains) {
+    conditions.bodyOrSubjectContains = parseCommaSeparated(
+      args.bodyOrSubjectContains
+    );
+  }
+  if (args.senderContains) {
+    conditions.senderContains = parseCommaSeparated(args.senderContains);
+  }
+  if (args.recipientContains) {
+    conditions.recipientContains = parseCommaSeparated(args.recipientContains);
+  }
+
+  // Recipient collections (comma-separated emails → recipient objects)
+  if (args.fromAddresses) {
+    const recipients = formatRecipientObjects(args.fromAddresses);
+    if (recipients.length > 0) {
+      conditions.fromAddresses = recipients;
+    }
+  }
+  if (args.sentToAddresses) {
+    const recipients = formatRecipientObjects(args.sentToAddresses);
+    if (recipients.length > 0) {
+      conditions.sentToAddresses = recipients;
+    }
+  }
+
+  // Boolean conditions
+  if (args.hasAttachments === true) conditions.hasAttachment = true;
+  if (args.sentToMe === true) conditions.sentToMe = true;
+  if (args.sentOnlyToMe === true) conditions.sentOnlyToMe = true;
+  if (args.sentCcMe === true) conditions.sentCcMe = true;
+  if (args.isAutomaticReply === true) conditions.isAutomaticReply = true;
+
+  // Enum conditions
+  if (args.importance) {
+    if (!VALID_IMPORTANCE.includes(args.importance)) {
+      warnings.push(
+        `Invalid importance "${args.importance}". Must be: ${VALID_IMPORTANCE.join(', ')}`
+      );
+    } else {
+      conditions.importance = args.importance;
+    }
+  }
+  if (args.sensitivity) {
+    if (!VALID_SENSITIVITY.includes(args.sensitivity)) {
+      warnings.push(
+        `Invalid sensitivity "${args.sensitivity}". Must be: ${VALID_SENSITIVITY.join(', ')}`
+      );
+    } else {
+      conditions.sensitivity = args.sensitivity;
+    }
+  }
+
+  return { conditions, warnings };
+}
+
+/**
+ * Build a Graph API actions object from flat tool parameters.
+ * Async because folder resolution requires API calls.
+ * @param {object} args - Tool arguments
+ * @param {string} accessToken - Graph API access token
+ * @returns {Promise<{ actions: object, warnings: string[] }>}
+ */
+async function buildActions(args, accessToken) {
+  const actions = {};
+  const warnings = [];
+
+  // Folder-based actions (name → ID resolution)
+  if (args.moveToFolder) {
+    const folderId = await getFolderIdByName(accessToken, args.moveToFolder);
+    if (!folderId) {
+      warnings.push(`Target folder "${args.moveToFolder}" not found.`);
+    } else {
+      actions.moveToFolder = folderId;
+    }
+  }
+  if (args.copyToFolder) {
+    const folderId = await getFolderIdByName(accessToken, args.copyToFolder);
+    if (!folderId) {
+      warnings.push(`Copy-to folder "${args.copyToFolder}" not found.`);
+    } else {
+      actions.copyToFolder = folderId;
+    }
+  }
+
+  // Boolean actions
+  if (args.markAsRead === true) actions.markAsRead = true;
+  if (args.stopProcessingRules === true) actions.stopProcessingRules = true;
+  if (args.deleteMessage === true) {
+    actions.delete = true;
+    warnings.push('This rule will move matching messages to Deleted Items.');
+  }
+
+  // Enum actions
+  if (args.markImportance) {
+    if (!VALID_IMPORTANCE.includes(args.markImportance)) {
+      warnings.push(
+        `Invalid markImportance "${args.markImportance}". Must be: ${VALID_IMPORTANCE.join(', ')}`
+      );
+    } else {
+      actions.markImportance = args.markImportance;
+    }
+  }
+
+  // Recipient-based actions (comma-separated emails → recipient objects)
+  if (args.forwardTo) {
+    const recipients = formatRecipientObjects(args.forwardTo);
+    if (recipients.length > 0) {
+      // Check allowlist if configured
+      const allowlistError = checkRecipientAllowlist(recipients);
+      if (allowlistError) {
+        warnings.push(
+          `Forward recipients blocked by allowlist: ${args.forwardTo}`
+        );
+      } else {
+        actions.forwardTo = recipients;
+        warnings.push(
+          `This rule will forward all matching emails to: ${args.forwardTo}. Verify these addresses are correct.`
+        );
+      }
+    }
+  }
+  if (args.redirectTo) {
+    const recipients = formatRecipientObjects(args.redirectTo);
+    if (recipients.length > 0) {
+      const allowlistError = checkRecipientAllowlist(recipients);
+      if (allowlistError) {
+        warnings.push(
+          `Redirect recipients blocked by allowlist: ${args.redirectTo}`
+        );
+      } else {
+        actions.redirectTo = recipients;
+        warnings.push(
+          `This rule will redirect all matching emails to: ${args.redirectTo}. The original sender will appear as the sender.`
+        );
+      }
+    }
+  }
+
+  // Category actions
+  if (args.assignCategories) {
+    actions.assignCategories = parseCommaSeparated(args.assignCategories);
+  }
+
+  return { actions, warnings };
+}
+
+/**
+ * Build a Graph API exceptions object from except* prefixed parameters.
+ * @param {object} args - Tool arguments
+ * @returns {{ exceptions: object, warnings: string[] }}
+ */
+function buildExceptions(args) {
+  const exceptions = {};
+  const warnings = [];
+
+  if (args.exceptFromAddresses) {
+    const recipients = formatRecipientObjects(args.exceptFromAddresses);
+    if (recipients.length > 0) {
+      exceptions.fromAddresses = recipients;
+    }
+  }
+  if (args.exceptSubjectContains) {
+    exceptions.subjectContains = parseCommaSeparated(
+      args.exceptSubjectContains
+    );
+  }
+  if (args.exceptSenderContains) {
+    exceptions.senderContains = parseCommaSeparated(args.exceptSenderContains);
+  }
+  if (args.exceptBodyContains) {
+    exceptions.bodyContains = parseCommaSeparated(args.exceptBodyContains);
+  }
+  if (args.exceptHasAttachments === true) {
+    exceptions.hasAttachment = true;
+  }
+
+  return { exceptions, warnings };
+}
+
+/**
+ * Check if any condition was provided in the args.
+ * @param {object} args - Tool arguments
+ * @returns {boolean}
+ */
+function hasAnyCondition(args) {
+  return Boolean(
+    args.fromAddresses ||
+    args.containsSubject ||
+    args.hasAttachments === true ||
+    args.bodyContains ||
+    args.bodyOrSubjectContains ||
+    args.senderContains ||
+    args.recipientContains ||
+    args.sentToAddresses ||
+    args.importance ||
+    args.sensitivity ||
+    args.sentToMe === true ||
+    args.sentOnlyToMe === true ||
+    args.sentCcMe === true ||
+    args.isAutomaticReply === true
+  );
+}
+
+/**
+ * Check if any action was provided in the args.
+ * @param {object} args - Tool arguments
+ * @returns {boolean}
+ */
+function hasAnyAction(args) {
+  return Boolean(
+    args.moveToFolder ||
+    args.copyToFolder ||
+    args.markAsRead === true ||
+    args.markImportance ||
+    args.forwardTo ||
+    args.redirectTo ||
+    args.assignCategories ||
+    args.stopProcessingRules === true ||
+    args.deleteMessage === true
+  );
+}
+
+module.exports = {
+  VALID_IMPORTANCE,
+  VALID_SENSITIVITY,
+  parseCommaSeparated,
+  formatRecipientObjects,
+  buildConditions,
+  buildActions,
+  buildExceptions,
+  hasAnyCondition,
+  hasAnyAction,
+};

package/rules/update.js

@@ -0,0 +1,213 @@
+/**
+ * Update rule functionality
+ */
+const { callGraphAPI } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+const { checkRateLimit, formatRuleDryRunPreview } = require('../utils/safety');
+const { getInboxRules } = require('./list');
+const {
+  buildConditions,
+  buildActions,
+  buildExceptions,
+} = require('./rule-builder');
+
+/**
+ * Update rule handler — modify an existing rule by name or ID.
+ * Conditions, actions, and exceptions use replace semantics (not merge).
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleUpdateRule(args) {
+  const { ruleName, ruleId, name, isEnabled, sequence, dryRun } = args;
+
+  // Rate limit
+  const rateLimitError = checkRateLimit('manage-rules');
+  if (rateLimitError) return rateLimitError;
+
+  if (!ruleName && !ruleId) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Either ruleName or ruleId is required to identify the rule to update.',
+        },
+      ],
+    };
+  }
+
+  if (sequence !== undefined && (isNaN(sequence) || sequence < 1)) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Sequence must be a positive number greater than zero.',
+        },
+      ],
+    };
+  }
+
+  try {
+    const accessToken = await ensureAuthenticated();
+
+    // Resolve rule ID
+    let resolvedId = ruleId;
+    let currentRule = null;
+
+    const rules = await getInboxRules(accessToken);
+
+    if (resolvedId) {
+      currentRule = rules.find((r) => r.id === resolvedId);
+    } else {
+      currentRule = rules.find((r) => r.displayName === ruleName);
+      if (currentRule) resolvedId = currentRule.id;
+    }
+
+    if (!currentRule) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Rule "${ruleName || ruleId}" not found.`,
+          },
+        ],
+      };
+    }
+
+    // Build PATCH payload — only include fields the user provided
+    const patch = {};
+    const allWarnings = [];
+
+    if (name) patch.displayName = name;
+    if (isEnabled !== undefined) patch.isEnabled = isEnabled;
+    if (sequence) patch.sequence = Math.max(1, Math.floor(sequence));
+
+    // Build conditions if any condition param was provided
+    const { conditions, warnings: condWarnings } = buildConditions(args);
+    if (Object.keys(conditions).length > 0) {
+      patch.conditions = conditions;
+      allWarnings.push(
+        'Conditions replaced (not merged). Use dryRun=true to preview before updating.'
+      );
+    }
+    allWarnings.push(...condWarnings);
+
+    // Build actions if any action param was provided
+    const { actions, warnings: actWarnings } = await buildActions(
+      args,
+      accessToken
+    );
+    if (Object.keys(actions).length > 0) {
+      patch.actions = actions;
+      allWarnings.push(
+        'Actions replaced (not merged). Use dryRun=true to preview before updating.'
+      );
+    }
+    allWarnings.push(...actWarnings);
+
+    // Check for fatal folder-not-found
+    const folderNotFound = actWarnings.some((w) => w.includes('not found'));
+    if (folderNotFound && Object.keys(actions).length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: actWarnings.filter((w) => w.includes('not found')).join('\n'),
+          },
+        ],
+      };
+    }
+
+    // Build exceptions if any except* param was provided
+    const { exceptions, warnings: excWarnings } = buildExceptions(args);
+    if (Object.keys(exceptions).length > 0) {
+      patch.exceptions = exceptions;
+    }
+    allWarnings.push(...excWarnings);
+
+    // Check that something is actually being changed
+    if (Object.keys(patch).length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `No changes specified for rule "${currentRule.displayName}". Provide at least one parameter to update (name, isEnabled, sequence, conditions, actions, or exceptions).`,
+          },
+        ],
+      };
+    }
+
+    // Dry-run: show before/after preview
+    if (dryRun) {
+      const updatedRule = { ...currentRule, ...patch };
+      const currentPreview = formatRuleDryRunPreview(currentRule);
+      const updatedPreview = formatRuleDryRunPreview(updatedRule);
+
+      let text = `DRY RUN — Update preview for "${currentRule.displayName}" (not applied):\n\n`;
+      text += `CURRENT:\n${currentPreview}\n\n`;
+      text += `AFTER UPDATE:\n${updatedPreview}`;
+      if (allWarnings.length > 0) {
+        text += `\n\nWarnings:\n${allWarnings.map((w) => `- ${w}`).join('\n')}`;
+      }
+      return {
+        content: [{ type: 'text', text }],
+      };
+    }
+
+    // Execute PATCH
+    await callGraphAPI(
+      accessToken,
+      'PATCH',
+      `me/mailFolders/inbox/messageRules/${resolvedId}`,
+      patch
+    );
+
+    const changedFields = Object.keys(patch)
+      .map((k) => {
+        if (k === 'displayName') return `name → "${patch.displayName}"`;
+        if (k === 'isEnabled') {
+          return patch.isEnabled ? 'enabled' : 'disabled';
+        }
+        if (k === 'sequence') return `sequence → ${patch.sequence}`;
+        if (k === 'conditions') return 'conditions updated';
+        if (k === 'actions') return 'actions updated';
+        if (k === 'exceptions') return 'exceptions updated';
+        return k;
+      })
+      .join(', ');
+
+    let text = `Successfully updated rule "${currentRule.displayName}": ${changedFields}.`;
+    // Filter out the replace/merge info warnings from the response since the update is done
+    const relevantWarnings = allWarnings.filter(
+      (w) => !w.includes('replaced (not merged)')
+    );
+    if (relevantWarnings.length > 0) {
+      text += `\n\nNotes:\n${relevantWarnings.map((w) => `- ${w}`).join('\n')}`;
+    }
+
+    return {
+      content: [{ type: 'text', text }],
+    };
+  } catch (error) {
+    if (error.message === 'Authentication required') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error updating rule: ${error.message}`,
+        },
+      ],
+    };
+  }
+}
+
+module.exports = handleUpdateRule;

package/settings/index.js

@@ -56,13 +56,7 @@ function formatAutomaticReplies(settings) {
 
   const lines = [];
   lines.push(
-    `**Status**: ${
-      settings.status === 'disabled'
-        ? '🔴 Disabled'
-        : settings.status === 'alwaysEnabled'
-          ? '🟢 Always Enabled'
-          : '📅 Scheduled'
-    }`
+    `**Status**: ${{ disabled: '🔴 Disabled', alwaysEnabled: '🟢 Always Enabled' }[settings.status] || '📅 Scheduled'}`
   );
 
   if (settings.status !== 'disabled') {
@@ -113,7 +107,7 @@ async function handleGetMailboxSettings(args) {
 
     const settings = await callGraphAPI(accessToken, 'GET', endpoint);
 
-    let output = [];
+    const output = [];
     output.push('# Mailbox Settings\n');
 
     if (section && section !== 'all') {
@@ -287,7 +281,7 @@ async function handleSetAutomaticReplies(args) {
       'me/mailboxSettings/automaticRepliesSetting'
     );
 
-    let output = [];
+    const output = [];
     output.push('Automatic replies updated!\n');
     output.push(formatAutomaticReplies(updated));
 
@@ -413,17 +407,11 @@ async function handleSetWorkingHours(args) {
     );
 
     // Build update
+    const padTime = (t) =>
+      t.length === 5 ? `${t}:00.0000000` : `${t}.0000000`;
     const workingHours = {
-      startTime: startTime
-        ? startTime.length === 5
-          ? startTime + ':00.0000000'
-          : startTime + '.0000000'
-        : current.startTime,
-      endTime: endTime
-        ? endTime.length === 5
-          ? endTime + ':00.0000000'
-          : endTime + '.0000000'
-        : current.endTime,
+      startTime: startTime ? padTime(startTime) : current.startTime,
+      endTime: endTime ? padTime(endTime) : current.endTime,
       daysOfWeek: daysOfWeek
         ? daysOfWeek.map((d) => d.toLowerCase())
         : current.daysOfWeek,
@@ -442,7 +430,7 @@ async function handleSetWorkingHours(args) {
       'me/mailboxSettings/workingHours'
     );
 
-    let output = [];
+    const output = [];
     output.push('Working hours updated!\n');
     output.push(formatWorkingHours(updated));
 
@@ -491,7 +479,7 @@ async function handleGetAutomaticReplies() {
       'me/mailboxSettings/automaticRepliesSetting'
     );
 
-    let output = [];
+    const output = [];
     output.push('# Automatic Replies\n');
     output.push(formatAutomaticReplies(settings));
 
@@ -533,7 +521,7 @@ async function handleGetWorkingHours() {
       'me/mailboxSettings/workingHours'
     );
 
-    let output = [];
+    const output = [];
     output.push('# Working Hours\n');
     output.push(formatWorkingHours(settings));
 

package/utils/field-presets.js

@@ -107,6 +107,26 @@ const FIELD_PRESETS = {
     'changeKey',
   ],
 
+  /**
+   * Draft fields for viewing/editing drafts
+   * Use case: Draft creation, update, listing
+   */
+  draft: [
+    'id',
+    'subject',
+    'from',
+    'toRecipients',
+    'ccRecipients',
+    'bccRecipients',
+    'body',
+    'bodyPreview',
+    'lastModifiedDateTime',
+    'isDraft',
+    'importance',
+    'hasAttachments',
+    'conversationId',
+  ],
+
   /**
    * Search result fields (optimized for relevance display)
    * Use case: Search results with context

package/utils/graph-api.js

@@ -7,6 +7,7 @@ const mockData = require('./mock-data');
 
 /**
  * Makes a request to the Microsoft Graph API
+ * In test mode (USE_TEST_MODE=true), routes to mock data instead of the real API.
  * @param {string} accessToken - The access token for authentication
  * @param {string} method - HTTP method (GET, POST, etc.)
  * @param {string} path - API endpoint path
@@ -14,6 +15,8 @@ const mockData = require('./mock-data');
  * @param {object} queryParams - Query parameters
  * @param {object} extraHeaders - Additional headers (e.g. Prefer for immutable IDs)
  * @returns {Promise<object>} - The API response
+ * @throws {Error} 'UNAUTHORIZED' if the server returns HTTP 401 (token expired or invalid)
+ * @throws {Error} If the HTTP status is outside 2xx, or if JSON parsing or network fails
  */
 async function callGraphAPI(
   accessToken,
@@ -69,7 +72,7 @@ async function callGraphAPI(
         }
 
         if (queryString) {
-          queryString = '?' + queryString;
+          queryString = `?${queryString}`;
         }
       }
 
@@ -153,6 +156,8 @@ async function callGraphAPI(
  * @param {object} queryParams - Initial query parameters
  * @param {number} maxCount - Maximum number of items to retrieve (0 = all)
  * @returns {Promise<object>} - Combined API response with all items
+ * @throws {Error} If method is not 'GET'
+ * @throws {Error} If any page request fails for any other reason
  */
 async function callGraphAPIPaginated(
   accessToken,
@@ -268,9 +273,12 @@ async function callGraphAPIBatch(accessToken, requests) {
 
 /**
  * Calls Graph API to get raw MIME content (for email export)
+ * In test mode (USE_TEST_MODE=true), returns mock MIME content instead of calling the real API.
  * @param {string} accessToken - The access token for authentication
  * @param {string} emailId - The email ID to export
  * @returns {Promise<string>} - Raw MIME content as string
+ * @throws {Error} 'UNAUTHORIZED' if the server returns HTTP 401 (token expired or invalid)
+ * @throws {Error} If the HTTP status is outside 2xx or a network error occurs
  */
 async function callGraphAPIRaw(accessToken, emailId) {
   // Test mode: return mock MIME content

package/utils/response-formatter.js

@@ -187,7 +187,7 @@ function formatEmailListAsTable(emails, folder, meta = {}) {
     const date = formatDateShort(email.receivedDateTime);
     const status = email.isRead ? '📖' : '📬';
     const subject = truncateText(email.subject || '(no subject)', 40);
-    const shortId = email.id.substring(0, 20) + '...';
+    const shortId = `${email.id.substring(0, 20)}...`;
 
     output += `| ${i + 1} | ${status} | ${date} | ${truncateText(from, 20)} | ${subject} | \`${shortId}\` |\n`;
   });
@@ -237,10 +237,12 @@ function formatEmailContent(
 
   if (verbosity === VERBOSITY.FULL) {
     output += `\n**ID:** \`${email.id}\``;
-    if (email.conversationId)
+    if (email.conversationId) {
       output += `\n**Conversation ID:** \`${email.conversationId}\``;
-    if (email.internetMessageId)
+    }
+    if (email.internetMessageId) {
       output += `\n**Message-ID:** \`${email.internetMessageId}\``;
+    }
   }
 
   output += '\n\n---\n\n';
@@ -457,7 +459,7 @@ function formatRecipients(recipients) {
 function truncateText(text, maxLength) {
   if (!text) return '';
   if (text.length <= maxLength) return text;
-  return text.substring(0, maxLength - 3) + '...';
+  return `${text.substring(0, maxLength - 3)}...`;
 }
 
 /**
@@ -490,10 +492,10 @@ function escapeCSV(value) {
   const isFormula = formulaChars.some((ch) => str.startsWith(ch));
 
   if (isFormula) {
-    return '"' + "'" + str.replace(/"/g, '""') + '"';
+    return `"` + `'${str.replace(/"/g, '""')}"`;
   }
   if (needsQuoting) {
-    return '"' + str.replace(/"/g, '""') + '"';
+    return `"${str.replace(/"/g, '""')}"`;
   }
   return str;
 }