@littlebearapps/outlook-assistant 3.7.2 → 3.8.0

package/calendar/update.js

@@ -0,0 +1,287 @@
+/**
+ * Update event functionality.
+ *
+ * Wraps the Microsoft Graph PATCH /me/events/{id} endpoint. Sends only
+ * the fields the caller provides — anything left out is preserved
+ * server-side. Useful for re-scheduling, adding/removing attendees,
+ * editing the body, or tweaking metadata without rebuilding the event
+ * from scratch (which loses RSVP state).
+ *
+ * Supports the following Graph event properties:
+ *   - subject
+ *   - start          (ISO string or {dateTime, timeZone} object)
+ *   - end            (same shape as start)
+ *   - attendees      (full replacement list of emails)
+ *   - body           (sent as HTML)
+ *   - location       (displayName)
+ *   - isOnlineMeeting
+ *   - sensitivity    (normal | personal | private | confidential)
+ *   - showAs         (free | tentative | busy | oof | workingElsewhere | unknown)
+ *   - importance     (low | normal | high)
+ *   - categories     (full replacement array of category names)
+ *   - reminderMinutesBeforeStart
+ *
+ * `dryRun: true` returns a preview of the PATCH payload without calling
+ * Graph — useful for confirming behaviour before mutating real data.
+ */
+const { callGraphAPI } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+const { DEFAULT_TIMEZONE } = require('../config');
+
+const SENSITIVITY_VALUES = new Set([
+  'normal',
+  'personal',
+  'private',
+  'confidential',
+]);
+const SHOW_AS_VALUES = new Set([
+  'free',
+  'tentative',
+  'busy',
+  'oof',
+  'workingElsewhere',
+  'unknown',
+]);
+const IMPORTANCE_VALUES = new Set(['low', 'normal', 'high']);
+
+/**
+ * Update event handler
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleUpdateEvent(args) {
+  const {
+    eventId,
+    subject,
+    start,
+    end,
+    attendees,
+    body,
+    location,
+    isOnlineMeeting,
+    sensitivity,
+    showAs,
+    importance,
+    categories,
+    reminderMinutesBeforeStart,
+    dryRun = false,
+  } = args;
+
+  if (!eventId) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Event ID is required to update an event.',
+        },
+      ],
+    };
+  }
+
+  // Build the patch body from only the fields the caller actually provided.
+  // Graph treats absent properties as "no change", so we never overwrite
+  // something the user didn't intend to touch.
+  const patch = {};
+
+  if (subject !== undefined) patch.subject = subject;
+
+  if (start !== undefined) {
+    patch.start = {
+      dateTime: start.dateTime || start,
+      timeZone: start.timeZone || DEFAULT_TIMEZONE,
+    };
+  }
+
+  if (end !== undefined) {
+    patch.end = {
+      dateTime: end.dateTime || end,
+      timeZone: end.timeZone || DEFAULT_TIMEZONE,
+    };
+  }
+
+  if (attendees !== undefined) {
+    // Replaces the full attendee list — Graph PATCH on this property is
+    // not additive. Caller must pass the desired complete list.
+    patch.attendees = (attendees || []).map((email) => ({
+      emailAddress: { address: email },
+      type: 'required',
+    }));
+  }
+
+  if (body !== undefined) {
+    patch.body = { contentType: 'HTML', content: body };
+  }
+
+  if (location !== undefined) {
+    patch.location = { displayName: location };
+  }
+
+  if (isOnlineMeeting !== undefined) {
+    patch.isOnlineMeeting = Boolean(isOnlineMeeting);
+  }
+
+  if (sensitivity !== undefined) {
+    if (!SENSITIVITY_VALUES.has(sensitivity)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid sensitivity: '${sensitivity}'. Must be one of: ${[...SENSITIVITY_VALUES].join(', ')}.`,
+          },
+        ],
+      };
+    }
+    patch.sensitivity = sensitivity;
+  }
+
+  if (showAs !== undefined) {
+    if (!SHOW_AS_VALUES.has(showAs)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid showAs: '${showAs}'. Must be one of: ${[...SHOW_AS_VALUES].join(', ')}.`,
+          },
+        ],
+      };
+    }
+    patch.showAs = showAs;
+  }
+
+  if (importance !== undefined) {
+    if (!IMPORTANCE_VALUES.has(importance)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid importance: '${importance}'. Must be one of: ${[...IMPORTANCE_VALUES].join(', ')}.`,
+          },
+        ],
+      };
+    }
+    patch.importance = importance;
+  }
+
+  if (categories !== undefined) {
+    // Full replacement, like attendees. Pass [] to clear all categories.
+    patch.categories = Array.isArray(categories) ? categories : [];
+  }
+
+  if (reminderMinutesBeforeStart !== undefined) {
+    const reminder = Number(reminderMinutesBeforeStart);
+    if (!Number.isFinite(reminder) || reminder < 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid reminderMinutesBeforeStart: '${reminderMinutesBeforeStart}'. Must be a non-negative number.`,
+          },
+        ],
+      };
+    }
+    patch.reminderMinutesBeforeStart = reminder;
+  }
+
+  if (Object.keys(patch).length === 0) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'No fields to update — provide at least one updatable field (subject, start, end, attendees, body, location, isOnlineMeeting, sensitivity, showAs, importance, categories, reminderMinutesBeforeStart).',
+        },
+      ],
+    };
+  }
+
+  // dryRun: don't touch Graph; just show the caller what would be sent.
+  if (dryRun) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: [
+            `**Dry run** — would PATCH \`me/events/${eventId}\` with:`,
+            '',
+            '```json',
+            JSON.stringify(patch, null, 2),
+            '```',
+            '',
+            `Fields that would change: ${Object.keys(patch).join(', ')}`,
+          ].join('\n'),
+        },
+      ],
+      _meta: {
+        eventId,
+        dryRun: true,
+        patch,
+        fieldsChanged: Object.keys(patch),
+      },
+    };
+  }
+
+  try {
+    const accessToken = await ensureAuthenticated();
+    const endpoint = `me/events/${eventId}`;
+
+    const response = await callGraphAPI(accessToken, 'PATCH', endpoint, patch);
+
+    const output = [
+      `Event '${response.subject || eventId}' updated successfully.`,
+    ];
+    if (response.id) {
+      output.push(`**ID**: \`${response.id}\``);
+    }
+    if (response.start) {
+      output.push(
+        `**Start**: ${response.start.dateTime} (${response.start.timeZone})`
+      );
+    }
+    if (response.end) {
+      output.push(
+        `**End**: ${response.end.dateTime} (${response.end.timeZone})`
+      );
+    }
+    if (response.webLink) {
+      output.push(`**Link**: ${response.webLink}`);
+    }
+    output.push(`\nFields changed: ${Object.keys(patch).join(', ')}`);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: output.join('\n'),
+        },
+      ],
+      _meta: {
+        eventId: response.id,
+        subject: response.subject,
+        start: response.start,
+        end: response.end,
+        fieldsChanged: Object.keys(patch),
+      },
+    };
+  } catch (error) {
+    if (error.message === 'Authentication required') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: "Authentication required. Please use the 'authenticate' tool first.",
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error updating event: ${error.message}`,
+        },
+      ],
+    };
+  }
+}
+
+module.exports = handleUpdateEvent;

package/categories/index.js

@@ -116,9 +116,9 @@ async function handleListCategories(args) {
       output.push('|----------|-------|-----|');
       categories.forEach((cat) => {
         const colorName = COLOR_NAMES[cat.color] || cat.color;
-        const idDisplay =
-          outputVerbosity === 'full' ? cat.id : `${cat.id.substring(0, 8)}...`;
-        output.push(`| ${cat.displayName} | ${colorName} | ${idDisplay} |`);
+        // F-9: emit full IDs at standard verbosity. Truncated IDs were
+        // unusable downstream (the ellipsis became part of the copy).
+        output.push(`| ${cat.displayName} | ${colorName} | ${cat.id} |`);
       });
     }
 
@@ -255,7 +255,9 @@ async function handleCreateCategory(args) {
  * Update category handler
  */
 async function handleUpdateCategory(args) {
-  const { id, displayName, color } = args;
+  // F-34: accept `categoryId` as a deprecated alias for `id`.
+  const id = args.id || args.categoryId;
+  const { displayName, color } = args;
 
   if (!id) {
     return {
@@ -298,34 +300,45 @@ async function handleUpdateCategory(args) {
     if (displayName) updateData.displayName = displayName;
     if (color) updateData.color = color;
 
-    const response = await callGraphAPI(
+    await callGraphAPI(
       accessToken,
       'PATCH',
       `me/outlook/masterCategories/${id}`,
       updateData
     );
 
-    // Prefer input values over response (PATCH may return partial data)
-    const updatedName = displayName || response.displayName;
-    const updatedColor = color || response.color;
-    const colorName = COLOR_NAMES[updatedColor] || updatedColor;
+    // F-35: Graph silently drops master-category color updates on
+    // some account types. Re-fetch the category and diff requested
+    // values against what Graph actually stored, so the caller
+    // doesn't get a misleading "Category updated!" when nothing
+    // changed.
+    const fresh = await callGraphAPI(
+      accessToken,
+      'GET',
+      `me/outlook/masterCategories/${id}`
+    );
 
-    const updatedCategory = {
-      ...response,
-      displayName: updatedName,
-      color: updatedColor,
-    };
+    const warnings = [];
+    if (color && fresh.color !== color) {
+      warnings.push(
+        `Requested color \`${color}\` but Graph stored \`${fresh.color}\` (master-category colors may be immutable on this account type).`
+      );
+    }
+    if (displayName && fresh.displayName !== displayName) {
+      warnings.push(
+        `Requested name \`${displayName}\` but Graph stored \`${fresh.displayName}\`.`
+      );
+    }
+
+    const colorName = COLOR_NAMES[fresh.color] || fresh.color;
+    let text = `Category updated!\n\n**Name**: ${fresh.displayName}\n**Color**: ${colorName} (${fresh.color})\n**ID**: ${fresh.id || id}`;
+    if (warnings.length > 0) {
+      text += `\n\n**⚠ Warning**:\n${warnings.map((w) => `- ${w}`).join('\n')}`;
+    }
 
     return {
-      content: [
-        {
-          type: 'text',
-          text: `Category updated!\n\n**Name**: ${updatedName}\n**Color**: ${colorName} (${updatedColor})\n**ID**: ${response.id || id}`,
-        },
-      ],
-      _meta: {
-        category: formatCategory(updatedCategory),
-      },
+      content: [{ type: 'text', text }],
+      _meta: { category: formatCategory(fresh) },
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
@@ -353,7 +366,8 @@ async function handleUpdateCategory(args) {
  * Delete category handler
  */
 async function handleDeleteCategory(args) {
-  const { id } = args;
+  // F-34: accept `categoryId` as a deprecated alias for `id`.
+  const id = args.id || args.categoryId;
 
   if (!id) {
     return {
@@ -824,8 +838,9 @@ const categoriesTools = [
       properties: {
         action: {
           type: 'string',
-          enum: ['list', 'create', 'update', 'delete'],
-          description: 'Action to perform (default: list)',
+          enum: ['list', 'create', 'update', 'set', 'delete'],
+          description:
+            "Action to perform (default: list). 'set' is a deprecated alias for 'update'.",
         },
         // list params
         outputVerbosity: {
@@ -850,7 +865,12 @@ const categoriesTools = [
           type: 'string',
           description: 'Category ID (action=update/delete, required)',
         },
+        categoryId: {
+          type: 'string',
+          description: 'DEPRECATED: alias for `id`. Will be removed in v3.8.0.',
+        },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -858,13 +878,22 @@ const categoriesTools = [
       switch (action) {
         case 'create':
           return handleCreateCategory(args);
+        case 'set': // deprecated alias
         case 'update':
           return handleUpdateCategory(args);
         case 'delete':
           return handleDeleteCategory(args);
         case 'list':
-        default:
           return handleListCategories(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: list, create, update, delete.`,
+              },
+            ],
+          };
       }
     },
   },
@@ -901,6 +930,7 @@ const categoriesTools = [
             'set (replace all), add (append), remove (remove specific). Default: set',
         },
       },
+      additionalProperties: false,
       required: ['categories'],
     },
     handler: handleApplyCategory,
@@ -945,6 +975,7 @@ const categoriesTools = [
             'Where to put emails from this sender (action=set, default: focused)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -955,8 +986,16 @@ const categoriesTools = [
         case 'delete':
           return handleSetFocusedInboxOverride(args);
         case 'list':
-        default:
           return handleGetFocusedInboxOverrides(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: list, set, delete.`,
+              },
+            ],
+          };
       }
     },
   },

package/config.js

@@ -23,6 +23,48 @@ if (!homeDir) {
   );
 }
 
+/**
+ * Resolve the OAuth audience segment used in Microsoft Graph endpoints.
+ *
+ * Microsoft's identity platform v2.0 routes by audience:
+ *   - `common`         — personal AND work/school accounts (multi-tenant + personal)
+ *   - `consumers`      — personal Microsoft accounts only
+ *   - `organizations`  — work/school accounts only
+ *   - `<tenant-guid>`  — single-tenant
+ *
+ * The right value depends on the Azure app registration's "Supported account
+ * types" setting. An app registered as "Personal Microsoft accounts only" is
+ * rejected by `/common/` with `AADSTS9002331` and must use `/consumers/`;
+ * a single-tenant app must use its tenant GUID; etc.
+ *
+ * Defaulting to `common` preserves existing behaviour. Set
+ * `OUTLOOK_AUTH_AUDIENCE` to override.
+ */
+const AUTH_AUDIENCE = process.env.OUTLOOK_AUTH_AUDIENCE || 'common';
+
+// Surface obvious misconfigurations at startup rather than failing later with a
+// cryptic AADSTS error from Microsoft. Warn rather than throw so we never break
+// an existing deployment on upgrade — Graph itself remains the source of truth
+// for what audiences it accepts.
+const VALID_AUDIENCE_LITERALS = new Set([
+  'common',
+  'consumers',
+  'organizations',
+]);
+const TENANT_GUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+if (
+  !VALID_AUDIENCE_LITERALS.has(AUTH_AUDIENCE) &&
+  !TENANT_GUID_RE.test(AUTH_AUDIENCE)
+) {
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[outlook-assistant] OUTLOOK_AUTH_AUDIENCE="${AUTH_AUDIENCE}" is not a recognised value. ` +
+      `Expected one of: common, consumers, organizations, or a tenant GUID. ` +
+      `Proceeding anyway — Microsoft's identity platform will reject it at runtime if invalid.`
+  );
+}
+
 module.exports = {
   // Server information
   SERVER_NAME: 'outlook-assistant',
@@ -54,9 +96,10 @@ module.exports = {
     ],
     tokenStorePath: path.join(homeDir, '.outlook-assistant-tokens.json'),
     authServerUrl: 'http://localhost:3333',
-    deviceCodeEndpoint:
-      'https://login.microsoftonline.com/common/oauth2/v2.0/devicecode',
-    tokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    audience: AUTH_AUDIENCE,
+    deviceCodeEndpoint: `https://login.microsoftonline.com/${AUTH_AUDIENCE}/oauth2/v2.0/devicecode`,
+    tokenEndpoint: `https://login.microsoftonline.com/${AUTH_AUDIENCE}/oauth2/v2.0/token`,
+    authorizeEndpoint: `https://login.microsoftonline.com/${AUTH_AUDIENCE}/oauth2/v2.0/authorize`,
     defaultAuthMethod: process.env.OUTLOOK_AUTH_METHOD || 'device-code',
   },
 
@@ -97,6 +140,9 @@ module.exports = {
   // Immutable IDs (opt-in: IDs persist through folder moves)
   USE_IMMUTABLE_IDS: process.env.OUTLOOK_IMMUTABLE_IDS === 'true',
 
-  // Timezone
-  DEFAULT_TIMEZONE: 'Australia/Melbourne', // Updated for Nathan's timezone
+  // Timezone — IANA zone (e.g. "Australia/Melbourne", "Europe/London",
+  // "America/New_York"). Override per-deployment via OUTLOOK_DEFAULT_TIMEZONE.
+  // Default preserves the historic value for backwards compatibility.
+  DEFAULT_TIMEZONE:
+    process.env.OUTLOOK_DEFAULT_TIMEZONE || 'Australia/Melbourne',
 };