@littlebearapps/outlook-assistant 3.13.0 → 3.14.1

package/email/mail-tips.js

@@ -6,6 +6,7 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * All available mail tip types from Microsoft Graph API
@@ -25,17 +26,27 @@ const MAIL_TIP_TYPES = [
 
 /**
  * Format mail tips into readable markdown
+ *
+ * Graph's mailTips resource reports `mailboxFull`, `deliveryRestricted` and
+ * `isModerated` as booleans. The older `mailboxFullStatus`,
+ * `deliveryRestriction` and `moderationStatus` shapes are still recognised.
  * @param {Array} mailTips - Array of mail tip objects from Graph API
- * @returns {string} - Formatted markdown output
+ * @returns {{formatted: string, warningCount: number, issues: Array<{address: string, type: string}>}}
+ *   `issues` lists each flagged condition per recipient, with `type` one of
+ *   outOfOffice, mailboxFull, customTip, deliveryRestricted, moderated,
+ *   external or externalMembers. Every issue is also a warning in the text,
+ *   so the text never shows ✓ for a recipient send-email would refuse
  */
 function formatMailTips(mailTips) {
   const lines = [];
+  const issues = [];
   let warningCount = 0;
 
   for (const tip of mailTips) {
     const email = tip.emailAddress?.address || 'Unknown';
     const tipLines = [];
     const warnings = [];
+    const flag = (type) => issues.push({ address: email, type });
 
     // Out-of-office / automatic replies
     if (
@@ -43,6 +54,7 @@ function formatMailTips(mailTips) {
       tip.automaticReplies.message.trim() !== ''
     ) {
       warnings.push('Out of Office');
+      flag('outOfOffice');
       const reply = tip.automaticReplies;
       tipLines.push(
         `  **Out of Office**: ${reply.message.replace(/\n/g, ' ').substring(0, 200)}`
@@ -57,8 +69,9 @@ function formatMailTips(mailTips) {
     }
 
     // Mailbox full
-    if (tip.mailboxFullStatus) {
+    if (tip.mailboxFull === true || tip.mailboxFullStatus === true) {
       warnings.push('Mailbox Full');
+      flag('mailboxFull');
       tipLines.push(
         `  **Mailbox Full**: Recipient's mailbox is full — delivery may fail`
       );
@@ -67,30 +80,38 @@ function formatMailTips(mailTips) {
     // Custom mail tip (admin-configured)
     if (tip.customMailTip) {
       warnings.push('Custom Tip');
+      flag('customTip');
       tipLines.push(`  **Notice**: ${tip.customMailTip}`);
     }
 
     // Delivery restriction
-    if (tip.deliveryRestriction) {
-      const restriction = tip.deliveryRestriction;
-      if (restriction.isDeliveryRestricted) {
-        warnings.push('Delivery Restricted');
-        tipLines.push(
-          `  **Delivery Restricted**: ${restriction.message || 'Cannot deliver to this recipient'}`
-        );
-      }
+    if (
+      tip.deliveryRestricted === true ||
+      tip.deliveryRestriction?.isDeliveryRestricted
+    ) {
+      warnings.push('Delivery Restricted');
+      flag('deliveryRestricted');
+      tipLines.push(
+        `  **Delivery Restricted**: ${tip.deliveryRestriction?.message || 'Cannot deliver to this recipient'}`
+      );
     }
 
     // Moderation status
-    if (tip.moderationStatus && tip.moderationStatus !== 'notModerated') {
+    if (
+      tip.isModerated === true ||
+      (tip.moderationStatus && tip.moderationStatus !== 'notModerated')
+    ) {
       warnings.push('Moderated');
+      flag('moderated');
       tipLines.push(
         `  **Moderated**: Messages to this recipient require approval`
       );
     }
 
-    // Recipient scope (external)
-    if (tip.recipientScope === 'external') {
+    // Recipient scope: external, externalPartner or externalNonPartner
+    if (/^external/i.test(tip.recipientScope || '')) {
+      warnings.push('External');
+      flag('external');
       tipLines.push(`  **External**: Recipient is outside your organisation`);
     }
 
@@ -101,12 +122,27 @@ function formatMailTips(mailTips) {
     }
 
     // Group member counts
-    if (tip.totalMemberCount > 0) {
+    if (tip.externalMemberCount > 0) {
+      warnings.push('External Members');
+      flag('externalMembers');
+    }
+    if (tip.totalMemberCount > 0 || tip.externalMemberCount > 0) {
       tipLines.push(
         `  *Group members*: ${tip.totalMemberCount} total (${tip.externalMemberCount || 0} external)`
       );
     }
 
+    // Graph couldn't check this recipient, so its other fields say nothing.
+    if (tip.error) {
+      warnings.push('Not Checked');
+      const code = /^[A-Za-z0-9]{1,64}$/.test(tip.error.code || '')
+        ? ` (${tip.error.code})`
+        : '';
+      tipLines.push(
+        `  **Not checked**: Graph returned an error for this recipient${code}`
+      );
+    }
+
     // Build section for this recipient
     const statusIcon = warnings.length > 0 ? '⚠' : '✓';
     lines.push(`### ${statusIcon} ${email}`);
@@ -124,7 +160,29 @@ function formatMailTips(mailTips) {
     lines.push('');
   }
 
-  return { formatted: lines.join('\n'), warningCount };
+  return { formatted: lines.join('\n'), warningCount, issues };
+}
+
+/**
+ * Whether Graph returned anything actionable for a recipient: any field a
+ * personal Outlook.com account leaves out. A recipientScope of `none` (or
+ * none at all) says nothing.
+ * @param {object} tip - One mailTips object from Graph
+ * @returns {boolean}
+ */
+function hasTipContent(tip) {
+  return Boolean(
+    tip.error ||
+    tip.mailboxFull ||
+    tip.deliveryRestricted ||
+    tip.isModerated ||
+    tip.automaticReplies?.message ||
+    tip.maxMessageSize ||
+    tip.totalMemberCount ||
+    tip.externalMemberCount ||
+    tip.customMailTip ||
+    (tip.recipientScope && tip.recipientScope !== 'none')
+  );
 }
 
 /**
@@ -136,14 +194,7 @@ async function handleGetMailTips(args) {
   const { recipients, tipTypes } = args;
 
   if (!recipients || recipients.length === 0) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'At least one recipient email address is required.',
-        },
-      ],
-    };
+    return toolError('At least one recipient email address is required.');
   }
 
   // Normalise recipients to a clean array of email strings
@@ -171,14 +222,7 @@ async function handleGetMailTips(args) {
   recipientList = recipientList.filter((e) => e.length > 0);
 
   if (recipientList.length === 0) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'At least one valid recipient email address is required.',
-        },
-      ],
-    };
+    return toolError('At least one valid recipient email address is required.');
   }
 
   try {
@@ -206,28 +250,23 @@ async function handleGetMailTips(args) {
             text: 'No mail tips returned. Mail Tips is M365-only — personal Outlook.com accounts return empty responses, so recipient validation is unavailable on this account.',
           },
         ],
+        _meta: {
+          recipientCount: 0,
+          warningCount: 0,
+          allEmpty: true,
+          issues: [],
+        },
       };
     }
 
-    const { formatted, warningCount } = formatMailTips(mailTips);
+    const { formatted, warningCount, issues } = formatMailTips(mailTips);
 
     // F-23: Detect a "fully empty" tips response — every recipient
     // returned with no actionable fields. Personal Outlook.com
     // accounts surface this as a successful empty response rather
     // than a feature-unsupported error, leading to false confidence
     // when callers see "No issues detected".
-    const allEmpty = mailTips.every((tip) => {
-      const hasContent =
-        tip.recipientNotFound ||
-        tip.mailboxFull ||
-        tip.deliveryRestricted ||
-        tip.isModerated ||
-        tip.automaticReplies?.message ||
-        tip.maxMessageSize ||
-        tip.totalMemberCount ||
-        tip.customMailTip;
-      return !hasContent;
-    });
+    const allEmpty = mailTips.every((tip) => !hasTipContent(tip));
 
     let header = `# Mail Tips\n\n`;
     header += `**Recipients checked**: ${mailTips.length}\n`;
@@ -244,24 +283,14 @@ async function handleGetMailTips(args) {
         recipientCount: mailTips.length,
         warningCount,
         allEmpty,
+        issues,
       },
     };
   } 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 getting mail tips: ${error.message}` },
-      ],
-    };
+    return toolError(`Error getting mail tips: ${error.message}`);
   }
 }
 

package/email/mark-as-read.js

@@ -5,6 +5,8 @@ const _config = require('../config'); // Reserved for future use
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 /**
  * Mark email as read handler
@@ -17,14 +19,7 @@ async function handleMarkAsRead(args) {
   const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!emailId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Email ID is required.',
-        },
-      ],
-    };
+    return toolError('Email ID is required.');
   }
 
   try {
@@ -56,60 +51,29 @@ async function handleMarkAsRead(args) {
         ],
       };
     } catch (error) {
-      console.error(
+      log.debug(
         `Error marking email as ${isRead ? 'read' : 'unread'}: ${error.message}`
       );
 
       // Improved error handling with more specific messages
       if (error.message.includes("doesn't belong to the targeted mailbox")) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `The email ID seems invalid or doesn't belong to your mailbox. Please try with a different email ID.`,
-            },
-          ],
-        };
+        return toolError(
+          `The email ID seems invalid or doesn't belong to your mailbox. Please try with a different email ID.`
+        );
       } else if (error.message.includes('UNAUTHORIZED')) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: 'Authentication failed. Please re-authenticate and try again.',
-            },
-          ],
-        };
+        return authRequiredError();
       } else {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Failed to mark email as ${isRead ? 'read' : 'unread'}: ${error.message}`,
-            },
-          ],
-        };
+        return toolError(
+          `Failed to mark email as ${isRead ? 'read' : 'unread'}: ${error.message}`
+        );
       }
     }
   } 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 accessing email: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error accessing email: ${error.message}`);
   }
 }
 

package/email/mime.js

@@ -7,6 +7,24 @@
 const { callGraphAPIRaw } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
+
+/**
+ * The longest prefix of `text` that fits in `maxBytes` of UTF-8 without
+ * splitting a character (which would render as U+FFFD).
+ * @param {string} text
+ * @param {number} maxBytes
+ * @returns {string}
+ */
+function utf8Prefix(text, maxBytes) {
+  const bytes = Buffer.from(text, 'utf8');
+  if (bytes.length <= maxBytes) return text;
+  let end = maxBytes;
+  // Step back over continuation bytes (10xxxxxx) to a character start.
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+  return bytes.subarray(0, end).toString('utf8');
+}
 
 /**
  * Parse MIME headers from raw content
@@ -98,14 +116,7 @@ async function handleGetMimeContent(args) {
   const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!emailId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Email ID is required.',
-        },
-      ],
-    };
+    return toolError('Email ID is required.');
   }
 
   try {
@@ -117,14 +128,9 @@ async function handleGetMimeContent(args) {
       const mimeContent = await callGraphAPIRaw(accessToken, emailId, prefix);
 
       if (!mimeContent) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Failed to retrieve MIME content for email ${emailId}.`,
-            },
-          ],
-        };
+        return toolError(
+          `Failed to retrieve MIME content for email ${emailId}.`
+        );
       }
 
       const stats = getMimeStats(mimeContent);
@@ -133,7 +139,13 @@ async function handleGetMimeContent(args) {
       // Check size limit
       if (maxSize > 0 && stats.bytes > maxSize) {
         if (headersOnly) {
-          // Return just headers if over limit
+          // Return just headers if over limit, themselves capped at
+          // maxSize (#306): a large header block used to come back whole.
+          const headerBytes = Buffer.byteLength(parsed.headerSection, 'utf8');
+          const headerText =
+            headerBytes > maxSize
+              ? `${utf8Prefix(parsed.headerSection, maxSize)}\n… (headers cut at maxSize ${maxSize} bytes of ${headerBytes})`
+              : parsed.headerSection;
           return {
             content: [
               {
@@ -142,7 +154,7 @@ async function handleGetMimeContent(args) {
                   `# MIME Content (Headers Only - Content Truncated)\n\n` +
                   `**Size**: ${stats.formattedSize} (exceeds ${maxSize} byte limit)\n` +
                   `**Lines**: ${stats.lines}\n\n` +
-                  `## MIME Headers\n\n\`\`\`\n${parsed.headerSection}\n\`\`\``,
+                  `## MIME Headers\n\n\`\`\`\n${headerText}\n\`\`\``,
               },
             ],
             _meta: {
@@ -174,6 +186,7 @@ async function handleGetMimeContent(args) {
             truncated: true,
             maxSizeExceeded: true,
           },
+          isError: true,
         };
       }
 
@@ -238,53 +251,28 @@ async function handleGetMimeContent(args) {
         },
       };
     } catch (error) {
-      console.error(`Error getting MIME content: ${error.message}`);
+      log.debug(`Error getting MIME content: ${error.message}`);
 
       if (error.message.includes("doesn't belong to the targeted mailbox")) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `The email ID seems invalid or doesn't belong to your mailbox.`,
-            },
-          ],
-        };
+        return toolError(
+          `The email ID seems invalid or doesn't belong to your mailbox.`
+        );
       }
 
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Failed to get MIME content: ${error.message}`,
-          },
-        ],
-      };
+      return toolError(`Failed to get MIME content: ${error.message}`);
     }
   } 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 accessing email: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error accessing email: ${error.message}`);
   }
 }
 
 module.exports = {
   handleGetMimeContent,
+  utf8Prefix,
   parseMimeHeaders,
   getMimeStats,
 };

package/email/read.js

@@ -9,9 +9,12 @@ const { ensureAuthenticated } = require('../auth');
 const {
   formatEmailContent,
   VERBOSITY,
+  DEFAULT_LIMITS,
 } = require('../utils/response-formatter');
 const { getEmailFields } = require('../utils/field-presets');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 /**
  * Get field preset based on verbosity and options
@@ -48,17 +51,11 @@ async function handleReadEmail(args) {
   const includeHeaders = args.includeHeaders || false;
   // Message IDs are mailbox-scoped: an ID issued by a shared/delegated mailbox
   // is not resolvable under /me. Route to /users/{mailbox} when supplied.
-  const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
+  const sharedMailbox = args.sharedMailbox || args.email || null;
+  const prefix = buildMailboxPrefix(sharedMailbox);
 
   if (!emailId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Email ID is required.',
-        },
-      ],
-    };
+    return toolError('Email ID is required.');
   }
 
   try {
@@ -85,20 +82,15 @@ async function handleReadEmail(args) {
       );
 
       if (!email) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Email with ID ${emailId} not found.`,
-            },
-          ],
-        };
+        return toolError(`Email with ID ${emailId} not found.`);
       }
 
       // Format using shared formatter (returns Markdown)
       const formattedOutput = formatEmailContent(email, verbosity, {
         includeHeaders: includeHeaders,
         includeAllHeaders: false, // Only important headers by default
+        sharedMailbox,
+        maxFullBodyChars: DEFAULT_LIMITS.maxFullBodyChars,
       });
 
       return {
@@ -116,49 +108,23 @@ async function handleReadEmail(args) {
         },
       };
     } catch (error) {
-      console.error(`Error reading email: ${error.message}`);
+      log.debug(`Error reading email: ${error.message}`);
 
       // Improved error handling with more specific messages
       if (error.message.includes("doesn't belong to the targeted mailbox")) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `The email ID seems invalid or doesn't belong to your mailbox. Please try with a different email ID.`,
-            },
-          ],
-        };
+        return toolError(
+          `The email ID seems invalid or doesn't belong to your mailbox. Please try with a different email ID.`
+        );
       } else {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Failed to read email: ${error.message}`,
-            },
-          ],
-        };
+        return toolError(`Failed to read email: ${error.message}`);
       }
     }
   } 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 accessing email: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error accessing email: ${error.message}`);
   }
 }