@littlebearapps/outlook-assistant 3.12.1 → 3.14.0

package/calendar/create.js

@@ -1,10 +1,14 @@
 /**
  * Create event functionality
  */
+const { randomUUID } = require('crypto');
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { DEFAULT_TIMEZONE } = require('../config');
-const { buildAttendees } = require('./attendees');
+const { buildAttendees, checkAttendeeAllowlist } = require('./attendees');
+const { checkRateLimit } = require('../utils/safety');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { previewCreateEvent } = require('./preview');
 
 /**
  * Create event handler
@@ -12,17 +16,12 @@ const { buildAttendees } = require('./attendees');
  * @returns {object} - MCP response
  */
 async function handleCreateEvent(args) {
-  const { subject, start, end, attendees, body } = args;
+  const { subject, start, end, attendees, body, dryRun = false } = args;
 
   if (!subject || !start || !end) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Subject, start, and end times are required to create an event.',
-        },
-      ],
-    };
+    return toolError(
+      'Subject, start, and end times are required to create an event.'
+    );
   }
 
   // Plain strings are required attendees; {email, type} sets the type (#249).
@@ -36,37 +35,46 @@ async function handleCreateEvent(args) {
         isError: true,
       };
     }
+    const allowlistError = checkAttendeeAllowlist(graphAttendees, { dryRun });
+    if (allowlistError) return allowlistError;
   }
 
+  // Request body
+  const bodyContent = {
+    subject,
+    start: {
+      dateTime: start.dateTime || start,
+      timeZone: start.timeZone || DEFAULT_TIMEZONE,
+    },
+    end: {
+      dateTime: end.dateTime || end,
+      timeZone: end.timeZone || DEFAULT_TIMEZONE,
+    },
+    attendees: graphAttendees,
+    body: { contentType: 'HTML', content: body || '' },
+  };
+
   try {
+    // dryRun: say who would be invited; create nothing (#274).
+    if (dryRun) return await previewCreateEvent(bodyContent);
+
+    // Counts real creates only; unlimited unless a limit is configured.
+    const rateLimitError = checkRateLimit('create-event');
+    if (rateLimitError) return rateLimitError;
+
     // Get access token
     const accessToken = await ensureAuthenticated();
 
     // Build API endpoint
     const endpoint = `me/events`;
 
-    // Request body
-    const bodyContent = {
-      subject,
-      start: {
-        dateTime: start.dateTime || start,
-        timeZone: start.timeZone || DEFAULT_TIMEZONE,
-      },
-      end: {
-        dateTime: end.dateTime || end,
-        timeZone: end.timeZone || DEFAULT_TIMEZONE,
-      },
-      attendees: graphAttendees,
-      body: { contentType: 'HTML', content: body || '' },
-    };
-
-    // Make API call
-    const response = await callGraphAPI(
-      accessToken,
-      'POST',
-      endpoint,
-      bodyContent
-    );
+    // A fresh transactionId per call (#280): Graph treats POSTs that share
+    // one as the same event, so a 429 retry in utils/graph-api.js (which
+    // re-sends this exact body) can't book the meeting twice.
+    const response = await callGraphAPI(accessToken, 'POST', endpoint, {
+      ...bodyContent,
+      transactionId: randomUUID(),
+    });
 
     const output = [`Event '${subject}' has been successfully created.`];
     if (response.id) {
@@ -102,24 +110,10 @@ async function handleCreateEvent(args) {
     };
   } 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 creating event: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error creating event: ${error.message}`);
   }
 }
 

package/calendar/decline.js

@@ -3,6 +3,8 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { previewDeclineEvent } = require('./preview');
 
 /**
  * Decline event handler
@@ -10,23 +12,20 @@ const { ensureAuthenticated } = require('../auth');
  * @returns {object} - MCP response
  */
 async function handleDeclineEvent(args) {
-  const { eventId, comment, sendResponse } = args;
+  const { eventId, comment, sendResponse, dryRun = false } = args;
 
   if (!eventId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Event ID is required to decline an event.',
-        },
-      ],
-    };
+    return toolError('Event ID is required to decline an event.');
   }
 
   try {
     // Get access token
     const accessToken = await ensureAuthenticated();
 
+    // dryRun: read the event and say whether the organiser would be
+    // emailed; send nothing.
+    if (dryRun) return await previewDeclineEvent(accessToken, args);
+
     // Build API endpoint
     const endpoint = `me/events/${eventId}/decline`;
 
@@ -53,24 +52,10 @@ async function handleDeclineEvent(args) {
     };
   } 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 declining event: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error declining event: ${error.message}`);
   }
 }
 

package/calendar/delete.js

@@ -3,6 +3,8 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { previewDeleteEvent } = require('./preview');
 
 /**
  * Delete event handler
@@ -10,23 +12,20 @@ const { ensureAuthenticated } = require('../auth');
  * @returns {object} - MCP response
  */
 async function handleDeleteEvent(args) {
-  const { eventId } = args;
+  const { eventId, dryRun = false } = args;
 
   if (!eventId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Event ID is required to delete an event.',
-        },
-      ],
-    };
+    return toolError('Event ID is required to delete an event.');
   }
 
   try {
     // Get access token
     const accessToken = await ensureAuthenticated();
 
+    // dryRun: read the event and say who (if anyone) would get a
+    // cancellation; delete nothing.
+    if (dryRun) return await previewDeleteEvent(accessToken, args);
+
     // Build API endpoint
     const endpoint = `me/events/${eventId}`;
 
@@ -43,24 +42,10 @@ async function handleDeleteEvent(args) {
     };
   } 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 deleting event: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error deleting event: ${error.message}`);
   }
 }
 

package/calendar/index.js

@@ -8,6 +8,8 @@ const handleCancelEvent = require('./cancel');
 const handleDeleteEvent = require('./delete');
 const handleUpdateEvent = require('./update');
 const { ATTENDEE_TYPES } = require('./attendees');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError } = require('../utils/tool-error');
 
 // One attendee: an email string, or {email, type} (#249). schema-coerce
 // doesn't validate inside array items, so calendar/attendees.js re-checks.
@@ -32,11 +34,7 @@ const calendarTools = [
     name: 'list-events',
     description:
       'List calendar events for the signed-in user (read-only). By default returns upcoming events (start ≥ now). Optional `startAfter`, `startBefore` and `subject` filters find past, current or specifically-named events; supplying any of them replaces the default "now" lower bound and the filters are AND-ed together. Results are oldest first, except when the search only looks backwards (`startBefore` without `startAfter`, or `subject` alone), where they are newest first. Each event shows its subject, location, start/end, a body preview and its id. Use `count` (default 10, max 100) to control page size. Each start/end is returned as a canonical UTC ISO-8601 instant (e.g. `2026-04-02T22:00:00.000Z`) followed by a labelled local rendering in the configured display timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`) — the UTC value is authoritative, so consumers never have to guess the zone.',
-    annotations: {
-      title: 'List Calendar Events',
-      readOnlyHint: true,
-      openWorldHint: false,
-    },
+    ...toolMetadata('list-events', 'List Calendar Events'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -71,13 +69,8 @@ const calendarTools = [
   {
     name: 'create-event',
     description:
-      "Create a new calendar event on the signed-in user's default calendar. Returns the created event with its `id`, `webLink`, and (if attendees are present) an auto-generated online-meeting URL — attendees receive invitations on save. Times use the configured timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`); omit the `Z` suffix to send local time. Use `manage-event` action=`update` to modify an event after creation, or `manage-event` action=`cancel`/`delete` to remove it.",
-    annotations: {
-      title: 'Create Calendar Event',
-      readOnlyHint: false,
-      destructiveHint: false,
-      openWorldHint: false,
-    },
+      "Create a new calendar event on the signed-in user's default calendar. Returns the created event with its `id`, `webLink`, and (if attendees are present) an auto-generated online-meeting URL — attendees receive invitations on save, so pass `dryRun: true` first to preview who would be invited (and how many are external) without creating anything. When `OUTLOOK_ALLOWED_RECIPIENTS` is set, every attendee must be allowed or nothing is created. Times use the configured timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`); omit the `Z` suffix to send local time. Use `manage-event` action=`update` to modify an event after creation, or `manage-event` action=`cancel`/`delete` to remove it.",
+    ...toolMetadata('create-event', 'Create Calendar Event'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -103,6 +96,11 @@ const calendarTools = [
           type: 'string',
           description: 'Optional body content for the event',
         },
+        dryRun: {
+          type: 'boolean',
+          description:
+            'Preview only: nothing is created and no invitations are sent. Shows who would be invited and how many are external (default false).',
+        },
       },
       additionalProperties: false,
       required: ['subject', 'start', 'end'],
@@ -112,13 +110,8 @@ const calendarTools = [
   {
     name: 'manage-event',
     description:
-      "Manage an existing calendar event (destructive: covers update/decline/cancel/delete — use dryRun where supported to preview). action=`update` edits fields in place via PATCH (subject, start, end, attendees, body, location, isOnlineMeeting, sensitivity, showAs, importance, categories, reminderMinutesBeforeStart) — only fields you pass are changed; pass `dryRun: true` to preview the PATCH payload. action=`decline` declines an invitation (optional `comment`; `sendResponse: false` declines without notifying the organiser). action=`cancel` cancels an event you organised and notifies attendees. action=`delete` removes the event from your calendar (Graph doesn't document a guaranteed recovery path, so don't count on restoring it); deleting a meeting you organised that has attendees still emails them a cancellation, so use `cancel` (with an optional `comment`) when you want to control that message. Returns the updated event on update; status confirmation otherwise. Note: there is no `accept` action — accept invitations in the Outlook UI (Graph's accept verb is unreliable across personal/M365).",
-    annotations: {
-      title: 'Manage Calendar Event',
-      readOnlyHint: false,
-      destructiveHint: true,
-      openWorldHint: false,
-    },
+      "Manage an existing calendar event. `dryRun: true` previews any action without changing or sending anything: who would be emailed, with an external count (decline/cancel/delete), or the PATCH body (update). action=`update` edits fields via PATCH (subject, start, end, attendees, body, location, isOnlineMeeting, sensitivity, showAs, importance, categories, reminderMinutesBeforeStart); only fields you pass change. action=`decline` declines an invitation (optional `comment`; `sendResponse: false` declines without notifying the organiser). action=`cancel` cancels an event you organised and emails attendees. action=`delete` removes the event from your calendar (Graph documents no guaranteed recovery); deleting a meeting you organised that has attendees still emails them a cancellation, so use `cancel` with a `comment` to control that message. Returns the updated event on update; a confirmation otherwise. There is no `accept` action: accept invitations in the Outlook UI, as Graph's accept verb is unreliable.",
+    ...toolMetadata('manage-event', 'Manage Calendar Event'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -186,7 +179,7 @@ const calendarTools = [
           type: 'array',
           items: ATTENDEE_ITEM_SCHEMA,
           description:
-            "Full replacement attendee list — pass the complete desired list, or [] to clear (action=update only). Each entry is an email address string or an {email, type} object (type 'required', 'optional' or 'resource'). A string, or an object without a type, keeps the type that address already has on the event (new addresses are required); an explicit type always wins.",
+            "Full replacement attendee list — pass the complete desired list, or [] to clear (action=update only). Each entry is an email address string or an {email, type} object (type 'required', 'optional' or 'resource'). A string, or an object without a type, keeps the type that address already has on the event (new addresses are required); an explicit type always wins. When OUTLOOK_ALLOWED_RECIPIENTS is set, every address on the list must be allowed or the update is refused.",
         },
         body: {
           type: 'string',
@@ -236,7 +229,7 @@ const calendarTools = [
         dryRun: {
           type: 'boolean',
           description:
-            'Preview the PATCH without applying it (action=update only). Returns the body that would be sent to Graph.',
+            'Preview only: nothing is changed or sent. Shows who would be emailed (decline/cancel/delete) or the PATCH body (update). Default false.',
         },
       },
       additionalProperties: false,
@@ -251,14 +244,9 @@ const calendarTools = [
         normalised.eventId = normalised.id;
       }
       if (!normalised.eventId) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: 'Required parameter `eventId` (or alias `id`) is missing.',
-            },
-          ],
-        };
+        return toolError(
+          'Required parameter `eventId` (or alias `id`) is missing.'
+        );
       }
       args = normalised;
       switch (args.action) {
@@ -271,14 +259,9 @@ const calendarTools = [
         case 'delete':
           return handleDeleteEvent(args);
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: "Invalid action. Use 'update', 'decline', 'cancel', or 'delete'.",
-              },
-            ],
-          };
+          return toolError(
+            "Invalid action. Use 'update', 'decline', 'cancel', or 'delete'."
+          );
       }
     },
   },

package/calendar/list.js

@@ -9,6 +9,7 @@ const {
   buildODataFilter,
 } = require('../utils/odata-helpers');
 const { parseIsoInstant } = require('../utils/datetime');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 const MAX_SUBJECT_LENGTH = 255;
 
@@ -312,24 +313,10 @@ async function handleListEvents(args) {
     };
   } 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 listing events: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error listing events: ${error.message}`);
   }
 }
 
@@ -337,6 +324,7 @@ async function handleListEvents(args) {
 // and tests). Helpers are attached for unit testing without changing callers.
 handleListEvents.toUtcIso = toUtcIso;
 handleListEvents.formatLocal = formatLocal;
+handleListEvents.toUtcIso = toUtcIso;
 
 module.exports = handleListEvents;
 module.exports.buildListEventsFilter = buildListEventsFilter;