@littlebearapps/outlook-assistant 3.3.0

package/utils/field-presets.js

@@ -0,0 +1,311 @@
+/**
+ * Field selection presets for Microsoft Graph API email queries
+ *
+ * Named presets for common use cases to optimize API calls
+ * and reduce response size/token usage.
+ */
+
+/**
+ * Field presets for different use cases
+ */
+const FIELD_PRESETS = {
+  /**
+   * Minimal fields for listing/scanning emails
+   * Use case: Quick folder scan, batch operations needing just IDs
+   */
+  list: ['id', 'subject', 'from', 'receivedDateTime', 'isRead'],
+
+  /**
+   * Minimal fields for reading a single email
+   * Use case: Quick read at minimal verbosity (includes bodyPreview + toRecipients)
+   */
+  'read-minimal': [
+    'id',
+    'subject',
+    'from',
+    'toRecipients',
+    'receivedDateTime',
+    'bodyPreview',
+    'hasAttachments',
+    'importance',
+    'isRead',
+  ],
+
+  /**
+   * Standard fields for reading email content
+   * Use case: Viewing email details with body
+   */
+  read: [
+    'id',
+    'subject',
+    'from',
+    'toRecipients',
+    'ccRecipients',
+    'receivedDateTime',
+    'body',
+    'bodyPreview',
+    'hasAttachments',
+    'importance',
+    'isRead',
+  ],
+
+  /**
+   * Extended fields for legal/forensic use
+   * Use case: Evidence collection, compliance, legal review
+   */
+  forensic: [
+    'id',
+    'subject',
+    'from',
+    'toRecipients',
+    'ccRecipients',
+    'bccRecipients',
+    'receivedDateTime',
+    'sentDateTime',
+    'body',
+    'bodyPreview',
+    'hasAttachments',
+    'importance',
+    'isRead',
+    'internetMessageHeaders',
+    'internetMessageId',
+    'conversationId',
+    'conversationIndex',
+    'parentFolderId',
+  ],
+
+  /**
+   * Full fields for export operations
+   * Use case: Complete email backup, migration, archival
+   */
+  export: [
+    'id',
+    'subject',
+    'from',
+    'toRecipients',
+    'ccRecipients',
+    'bccRecipients',
+    'replyTo',
+    'receivedDateTime',
+    'sentDateTime',
+    'createdDateTime',
+    'lastModifiedDateTime',
+    'body',
+    'bodyPreview',
+    'hasAttachments',
+    'importance',
+    'isRead',
+    'isDraft',
+    'internetMessageHeaders',
+    'internetMessageId',
+    'conversationId',
+    'conversationIndex',
+    'parentFolderId',
+    'categories',
+    'flag',
+    'webLink',
+    'changeKey',
+  ],
+
+  /**
+   * Search result fields (optimized for relevance display)
+   * Use case: Search results with context
+   */
+  search: [
+    'id',
+    'subject',
+    'from',
+    'toRecipients',
+    'receivedDateTime',
+    'bodyPreview',
+    'hasAttachments',
+    'importance',
+    'isRead',
+    'parentFolderId',
+  ],
+
+  /**
+   * Delta query fields (for incremental sync)
+   * Use case: Tracking changes in folder
+   */
+  delta: [
+    'id',
+    'subject',
+    'from',
+    'receivedDateTime',
+    'isRead',
+    'parentFolderId',
+    'changeKey',
+  ],
+
+  /**
+   * Conversation fields (for thread grouping)
+   * Use case: Viewing email threads
+   */
+  conversation: [
+    'id',
+    'subject',
+    'from',
+    'toRecipients',
+    'receivedDateTime',
+    'bodyPreview',
+    'conversationId',
+    'conversationIndex',
+    'isRead',
+  ],
+};
+
+/**
+ * Extended email fields (comprehensive list)
+ * Used as reference for export preset
+ */
+const EXTENDED_EMAIL_FIELDS = [
+  'id',
+  'subject',
+  'from',
+  'sender',
+  'toRecipients',
+  'ccRecipients',
+  'bccRecipients',
+  'replyTo',
+  'receivedDateTime',
+  'sentDateTime',
+  'createdDateTime',
+  'lastModifiedDateTime',
+  'body',
+  'bodyPreview',
+  'hasAttachments',
+  'importance',
+  'isRead',
+  'isDraft',
+  'isDeliveryReceiptRequested',
+  'isReadReceiptRequested',
+  'internetMessageHeaders',
+  'internetMessageId',
+  'conversationId',
+  'conversationIndex',
+  'parentFolderId',
+  'categories',
+  'flag',
+  'webLink',
+  'changeKey',
+  'inferenceClassification',
+];
+
+/**
+ * Folder fields for folder operations
+ */
+const FOLDER_FIELDS = {
+  /**
+   * Basic folder info
+   */
+  basic: ['id', 'displayName', 'parentFolderId'],
+
+  /**
+   * Folder with item counts
+   */
+  withCounts: [
+    'id',
+    'displayName',
+    'parentFolderId',
+    'totalItemCount',
+    'unreadItemCount',
+  ],
+
+  /**
+   * Full folder details
+   * Note: sizeInBytes is NOT available on mailFolder resource type
+   */
+  full: [
+    'id',
+    'displayName',
+    'parentFolderId',
+    'childFolderCount',
+    'totalItemCount',
+    'unreadItemCount',
+    'isHidden',
+  ],
+};
+
+/**
+ * Gets field selection string for Graph API $select parameter
+ * @param {string} preset - Preset name (list, read, forensic, export, search, delta, conversation)
+ * @returns {string} - Comma-separated field list
+ */
+function getEmailFields(preset = 'list') {
+  const fields = FIELD_PRESETS[preset];
+  if (!fields) {
+    console.error(`Unknown preset: ${preset}, falling back to 'list'`);
+    return FIELD_PRESETS.list.join(',');
+  }
+  return fields.join(',');
+}
+
+/**
+ * Gets folder field selection string
+ * @param {string} preset - Preset name (basic, withCounts, full)
+ * @returns {string} - Comma-separated field list
+ */
+function getFolderFields(preset = 'basic') {
+  const fields = FOLDER_FIELDS[preset];
+  if (!fields) {
+    console.error(`Unknown folder preset: ${preset}, falling back to 'basic'`);
+    return FOLDER_FIELDS.basic.join(',');
+  }
+  return fields.join(',');
+}
+
+/**
+ * Builds custom field selection from array
+ * @param {Array<string>} fields - Array of field names
+ * @returns {string} - Comma-separated field list
+ */
+function buildFieldSelection(fields) {
+  if (!fields || !Array.isArray(fields) || fields.length === 0) {
+    return getEmailFields('list');
+  }
+  return fields.join(',');
+}
+
+/**
+ * Merges preset with additional fields
+ * @param {string} preset - Base preset name
+ * @param {Array<string>} additionalFields - Extra fields to include
+ * @returns {string} - Combined field selection
+ */
+function mergeFields(preset, additionalFields = []) {
+  const baseFields = FIELD_PRESETS[preset] || FIELD_PRESETS.list;
+  const merged = [...new Set([...baseFields, ...additionalFields])];
+  return merged.join(',');
+}
+
+/**
+ * Validates that requested fields are valid Graph API fields
+ * @param {Array<string>} fields - Fields to validate
+ * @returns {object} - { valid: Array, invalid: Array }
+ */
+function validateFields(fields) {
+  const validFields = new Set(EXTENDED_EMAIL_FIELDS);
+  const result = { valid: [], invalid: [] };
+
+  fields.forEach((field) => {
+    if (validFields.has(field)) {
+      result.valid.push(field);
+    } else {
+      result.invalid.push(field);
+    }
+  });
+
+  return result;
+}
+
+module.exports = {
+  FIELD_PRESETS,
+  EXTENDED_EMAIL_FIELDS,
+  FOLDER_FIELDS,
+  getEmailFields,
+  getFolderFields,
+  buildFieldSelection,
+  mergeFields,
+  validateFields,
+};

package/utils/graph-api.js

@@ -0,0 +1,268 @@
+/**
+ * Microsoft Graph API helper functions
+ */
+const https = require('https');
+const config = require('../config');
+const mockData = require('./mock-data');
+
+/**
+ * Makes a request to the Microsoft Graph API
+ * @param {string} accessToken - The access token for authentication
+ * @param {string} method - HTTP method (GET, POST, etc.)
+ * @param {string} path - API endpoint path
+ * @param {object} data - Data to send for POST/PUT requests
+ * @param {object} queryParams - Query parameters
+ * @returns {Promise<object>} - The API response
+ */
+async function callGraphAPI(
+  accessToken,
+  method,
+  path,
+  data = null,
+  queryParams = {}
+) {
+  // For test tokens, we'll simulate the API call
+  if (config.USE_TEST_MODE && accessToken.startsWith('test_access_token_')) {
+    return mockData.simulateGraphAPIResponse(method, path, data, queryParams);
+  }
+
+  try {
+    // Check if path already contains the full URL (from nextLink)
+    let finalUrl;
+    if (path.startsWith('http://') || path.startsWith('https://')) {
+      // Path is already a full URL (from pagination nextLink)
+      finalUrl = path;
+    } else {
+      // Build URL from path and queryParams
+      // Encode path segments properly
+      const encodedPath = path
+        .split('/')
+        .map((segment) => encodeURIComponent(segment))
+        .join('/');
+
+      // Build query string from parameters with special handling for OData filters
+      let queryString = '';
+      if (Object.keys(queryParams).length > 0) {
+        // Handle $filter parameter specially to ensure proper URI encoding
+        const filter = queryParams.$filter;
+        if (filter) {
+          delete queryParams.$filter; // Remove from regular params
+        }
+
+        // Build query string with proper encoding for regular params
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(queryParams)) {
+          params.append(key, value);
+        }
+
+        queryString = params.toString();
+
+        // Add filter parameter separately with proper encoding
+        if (filter) {
+          if (queryString) {
+            queryString += `&$filter=${encodeURIComponent(filter)}`;
+          } else {
+            queryString = `$filter=${encodeURIComponent(filter)}`;
+          }
+        }
+
+        if (queryString) {
+          queryString = '?' + queryString;
+        }
+      }
+
+      finalUrl = `${config.GRAPH_API_ENDPOINT}${encodedPath}${queryString}`;
+    }
+
+    return new Promise((resolve, reject) => {
+      const options = {
+        method: method,
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          'Content-Type': 'application/json',
+        },
+      };
+
+      const req = https.request(finalUrl, options, (res) => {
+        let responseData = '';
+
+        res.on('data', (chunk) => {
+          responseData += chunk;
+        });
+
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            try {
+              responseData = responseData ? responseData : '{}';
+              const jsonResponse = JSON.parse(responseData);
+              resolve(jsonResponse);
+            } catch (error) {
+              reject(new Error(`Error parsing API response: ${error.message}`));
+            }
+          } else if (res.statusCode === 401) {
+            // Token expired or invalid
+            reject(new Error('UNAUTHORIZED'));
+          } else {
+            // Truncate response to avoid leaking sensitive data in error messages
+            const safeResponse = responseData.substring(0, 200);
+            reject(
+              new Error(
+                `API call failed with status ${res.statusCode}: ${safeResponse}`
+              )
+            );
+          }
+        });
+      });
+
+      req.on('error', (error) => {
+        reject(new Error(`Network error during API call: ${error.message}`));
+      });
+
+      if (
+        data &&
+        (method === 'POST' || method === 'PATCH' || method === 'PUT')
+      ) {
+        req.write(JSON.stringify(data));
+      }
+
+      req.end();
+    });
+  } catch (error) {
+    console.error('Error calling Graph API:', error);
+    throw error;
+  }
+}
+
+/**
+ * Calls Graph API with pagination support to retrieve all results up to maxCount
+ * @param {string} accessToken - The access token for authentication
+ * @param {string} method - HTTP method (GET only for pagination)
+ * @param {string} path - API endpoint path
+ * @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
+ */
+async function callGraphAPIPaginated(
+  accessToken,
+  method,
+  path,
+  queryParams = {},
+  maxCount = 0
+) {
+  if (method !== 'GET') {
+    throw new Error('Pagination only supports GET requests');
+  }
+
+  const allItems = [];
+  let nextLink;
+  let currentUrl = path;
+  let currentParams = { ...queryParams };
+
+  try {
+    do {
+      // Make API call
+      const response = await callGraphAPI(
+        accessToken,
+        method,
+        currentUrl,
+        null,
+        currentParams
+      );
+
+      // Add items from this page
+      if (response.value && Array.isArray(response.value)) {
+        allItems.push(...response.value);
+      }
+
+      // Check if we've reached the desired count
+      if (maxCount > 0 && allItems.length >= maxCount) {
+        break;
+      }
+
+      // Get next page URL
+      nextLink = response['@odata.nextLink'];
+
+      if (nextLink) {
+        // Pass the full nextLink URL directly to callGraphAPI
+        currentUrl = nextLink;
+        currentParams = {}; // nextLink already contains all params
+      }
+    } while (nextLink);
+
+    // Trim to exact count if needed
+    const finalItems = maxCount > 0 ? allItems.slice(0, maxCount) : allItems;
+
+    return {
+      value: finalItems,
+      '@odata.count': finalItems.length,
+    };
+  } catch (error) {
+    console.error('Error during pagination:', error);
+    throw error;
+  }
+}
+
+/**
+ * Calls Graph API to get raw MIME content (for email export)
+ * @param {string} accessToken - The access token for authentication
+ * @param {string} emailId - The email ID to export
+ * @returns {Promise<string>} - Raw MIME content as string
+ */
+async function callGraphAPIRaw(accessToken, emailId) {
+  // Test mode: return mock MIME content
+  if (config.USE_TEST_MODE && accessToken.startsWith('test_access_token_')) {
+    return mockData.getMockMimeContent
+      ? mockData.getMockMimeContent(emailId)
+      : `MIME-Version: 1.0\nContent-Type: text/plain\n\nTest email content for ${emailId}`;
+  }
+
+  return new Promise((resolve, reject) => {
+    const path = `me/messages/${encodeURIComponent(emailId)}/$value`;
+    const finalUrl = `${config.GRAPH_API_ENDPOINT}${path}`;
+
+    const options = {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'message/rfc822', // Request MIME format
+      },
+    };
+
+    const req = https.request(finalUrl, options, (res) => {
+      let responseData = '';
+
+      // Collect data as UTF-8 string
+      res.setEncoding('utf8');
+
+      res.on('data', (chunk) => {
+        responseData += chunk;
+      });
+
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve(responseData);
+        } else if (res.statusCode === 401) {
+          reject(new Error('UNAUTHORIZED'));
+        } else {
+          reject(
+            new Error(
+              `MIME export failed with status ${res.statusCode}: ${responseData.substring(0, 200)}`
+            )
+          );
+        }
+      });
+    });
+
+    req.on('error', (error) => {
+      reject(new Error(`Network error during MIME export: ${error.message}`));
+    });
+
+    req.end();
+  });
+}
+
+module.exports = {
+  callGraphAPI,
+  callGraphAPIPaginated,
+  callGraphAPIRaw,
+};