feat(outlook): add Microsoft Graph calendar tools

Six calendar operations against graph.microsoft.com/v1.0: list events (calendarView
with nextLink paging), get, create, update (partial PATCH), delete, and respond to
invites. Shared calendar-utils handles Graph's offset-less dateTime+timeZone shape,
attendee normalization, and event flattening. All tools carry the Microsoft Graph
error extractor and 429/backoff retry (honors Retry-After) for the mailbox concurrency
limit. Registered in the tool registry and barrel.

Author: mzxchandra

apps/sim/tools/outlook/calendar-tools.test.ts

@@ -0,0 +1,119 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { outlookCalendarCreateEventTool } from '@/tools/outlook/calendar_create_event'
+import { outlookCalendarDeleteEventTool } from '@/tools/outlook/calendar_delete_event'
+import { outlookCalendarGetEventTool } from '@/tools/outlook/calendar_get_event'
+import { outlookCalendarListEventsTool } from '@/tools/outlook/calendar_list_events'
+import { outlookCalendarRespondTool } from '@/tools/outlook/calendar_respond'
+import { outlookCalendarUpdateEventTool } from '@/tools/outlook/calendar_update_event'
+
+const tools = [
+  outlookCalendarListEventsTool,
+  outlookCalendarGetEventTool,
+  outlookCalendarCreateEventTool,
+  outlookCalendarUpdateEventTool,
+  outlookCalendarDeleteEventTool,
+  outlookCalendarRespondTool,
+]
+
+describe('outlook calendar tools', () => {
+  it('every tool uses the outlook oauth provider and a snake_case id', () => {
+    for (const tool of tools) {
+      expect(tool.oauth).toEqual({ required: true, provider: 'outlook' })
+      expect(tool.id).toMatch(/^outlook_calendar_[a-z_]+$/)
+      expect(tool.version).toBe('1.0.0')
+      expect(tool.outputs?.message).toBeDefined()
+    }
+  })
+
+  it('exposes the expected tool ids', () => {
+    expect(tools.map((t) => t.id)).toEqual([
+      'outlook_calendar_list_events',
+      'outlook_calendar_get_event',
+      'outlook_calendar_create_event',
+      'outlook_calendar_update_event',
+      'outlook_calendar_delete_event',
+      'outlook_calendar_respond',
+    ])
+  })
+
+  it('builds a calendarView URL with the time window and paging', () => {
+    const url = outlookCalendarListEventsTool.request.url as (p: unknown) => string
+    const built = url({
+      accessToken: 't',
+      startDateTime: '2025-06-03T00:00:00Z',
+      endDateTime: '2025-06-10T00:00:00Z',
+      maxResults: 5,
+    })
+    expect(built).toContain('https://graph.microsoft.com/v1.0/me/calendarView')
+    expect(built).toContain('startDateTime=2025-06-03T00%3A00%3A00Z')
+    expect(built).toContain('%24top=5')
+    expect(built).toContain('%24orderby=start%2FdateTime')
+
+    // A nextLink page token is used verbatim.
+    expect(url({ accessToken: 't', pageToken: 'https://graph.microsoft.com/next' })).toBe(
+      'https://graph.microsoft.com/next'
+    )
+  })
+
+  it('builds a create-event body with Graph datetime shape and attendees', () => {
+    const body = outlookCalendarCreateEventTool.request.body as (
+      p: unknown
+    ) => Record<string, unknown>
+    const built = body({
+      accessToken: 't',
+      subject: 'Sync',
+      startDateTime: '2025-06-03T10:00:00-08:00',
+      endDateTime: '2025-06-03T11:00:00-08:00',
+      attendees: 'a@x.com, b@y.com',
+      isOnlineMeeting: true,
+    })
+    expect(built.subject).toBe('Sync')
+    expect(built.start).toEqual({ dateTime: '2025-06-03T18:00:00', timeZone: 'UTC' })
+    expect(built.attendees).toHaveLength(2)
+    expect(built.isOnlineMeeting).toBe(true)
+    // We intentionally do NOT set onlineMeetingProvider so Graph uses the mailbox
+    // default (Teams on work/school accounts) instead of hardcoding a work-only value.
+    expect('onlineMeetingProvider' in built).toBe(false)
+  })
+
+  it('rejects an invalid respond responseType', () => {
+    const url = outlookCalendarRespondTool.request.url as (p: unknown) => string
+    expect(() => url({ accessToken: 't', eventId: 'e1', responseType: 'maybe' })).toThrow(
+      /Invalid responseType/
+    )
+    expect(url({ accessToken: 't', eventId: 'e1', responseType: 'accept' })).toBe(
+      'https://graph.microsoft.com/v1.0/me/events/e1/accept'
+    )
+  })
+
+  it('omits the comment key when empty so sendResponse=false is accepted by Graph', () => {
+    const body = outlookCalendarRespondTool.request.body as (p: unknown) => Record<string, unknown>
+    // Empty/whitespace comment with sendResponse off: comment must NOT be present.
+    const noComment = body({
+      eventId: 'e1',
+      responseType: 'accept',
+      sendResponse: false,
+      comment: '',
+    })
+    expect(noComment).toEqual({ sendResponse: false })
+    expect('comment' in noComment).toBe(false)
+
+    const nullComment = body({ eventId: 'e1', responseType: 'decline', sendResponse: false })
+    expect('comment' in nullComment).toBe(false)
+
+    // A real comment is included, and sendResponse defaults to true.
+    const withComment = body({ eventId: 'e1', responseType: 'accept', comment: 'See you there' })
+    expect(withComment).toEqual({ sendResponse: true, comment: 'See you there' })
+  })
+
+  it('enables retry with backoff on every calendar tool (429/mailbox concurrency)', () => {
+    for (const tool of tools) {
+      expect(tool.request.retry?.enabled).toBe(true)
+      // false so POST/PATCH (create/update/respond) also retry on a 429 throttle.
+      expect(tool.request.retry?.retryIdempotentOnly).toBe(false)
+    }
+  })
+})

apps/sim/tools/outlook/calendar-utils.test.ts

@@ -0,0 +1,120 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  buildGraphEventDateTime,
+  DEFAULT_OUTLOOK_TIME_ZONE,
+  flattenGraphEvent,
+  normalizeAttendees,
+} from '@/tools/outlook/calendar-utils'
+import type { GraphEvent } from '@/tools/outlook/types'
+
+describe('buildGraphEventDateTime', () => {
+  it('treats a date-only value as an all-day midnight start in the given zone', () => {
+    expect(buildGraphEventDateTime('2025-06-03', 'America/Los_Angeles')).toEqual({
+      dateTime: '2025-06-03T00:00:00',
+      timeZone: 'America/Los_Angeles',
+    })
+  })
+
+  it('defaults the zone to UTC when none is given for a date-only value', () => {
+    expect(buildGraphEventDateTime('2025-06-03')).toEqual({
+      dateTime: '2025-06-03T00:00:00',
+      timeZone: DEFAULT_OUTLOOK_TIME_ZONE,
+    })
+  })
+
+  it('keeps a naive datetime as wall-clock time in the provided zone', () => {
+    expect(buildGraphEventDateTime('2025-06-03T10:00:00', 'America/New_York')).toEqual({
+      dateTime: '2025-06-03T10:00:00',
+      timeZone: 'America/New_York',
+    })
+  })
+
+  it('converts a Z-suffixed datetime to an offset-less UTC value', () => {
+    expect(buildGraphEventDateTime('2025-06-03T10:00:00Z')).toEqual({
+      dateTime: '2025-06-03T10:00:00',
+      timeZone: 'UTC',
+    })
+  })
+
+  it('converts an offset datetime to the equivalent UTC instant', () => {
+    // 10:00 at -08:00 is 18:00 UTC
+    expect(buildGraphEventDateTime('2025-06-03T10:00:00-08:00')).toEqual({
+      dateTime: '2025-06-03T18:00:00',
+      timeZone: 'UTC',
+    })
+  })
+})
+
+describe('normalizeAttendees', () => {
+  it('returns an empty array for undefined', () => {
+    expect(normalizeAttendees(undefined)).toEqual([])
+  })
+
+  it('splits a comma-separated string into required attendees', () => {
+    expect(normalizeAttendees('a@x.com, b@y.com')).toEqual([
+      { emailAddress: { address: 'a@x.com' }, type: 'required' },
+      { emailAddress: { address: 'b@y.com' }, type: 'required' },
+    ])
+  })
+
+  it('accepts an array and honors a custom type', () => {
+    expect(normalizeAttendees(['a@x.com'], 'optional')).toEqual([
+      { emailAddress: { address: 'a@x.com' }, type: 'optional' },
+    ])
+  })
+
+  it('drops empty entries', () => {
+    expect(normalizeAttendees('a@x.com,,\n , b@y.com')).toEqual([
+      { emailAddress: { address: 'a@x.com' }, type: 'required' },
+      { emailAddress: { address: 'b@y.com' }, type: 'required' },
+    ])
+  })
+})
+
+describe('flattenGraphEvent', () => {
+  it('flattens the Graph event into editor-friendly fields', () => {
+    const event: GraphEvent = {
+      id: 'evt-1',
+      subject: 'Standup',
+      bodyPreview: 'Daily sync',
+      start: { dateTime: '2025-06-03T10:00:00.0000000', timeZone: 'UTC' },
+      end: { dateTime: '2025-06-03T10:30:00.0000000', timeZone: 'UTC' },
+      isAllDay: false,
+      webLink: 'https://outlook.office.com/evt-1',
+      location: { displayName: 'Room 1' },
+      organizer: { emailAddress: { name: 'Alice', address: 'alice@x.com' } },
+      onlineMeeting: { joinUrl: 'https://teams.example/join' },
+      attendees: [
+        {
+          type: 'required',
+          status: { response: 'accepted' },
+          emailAddress: { name: 'Bob', address: 'bob@y.com' },
+        },
+      ],
+    }
+
+    expect(flattenGraphEvent(event)).toEqual({
+      id: 'evt-1',
+      subject: 'Standup',
+      bodyPreview: 'Daily sync',
+      start: { dateTime: '2025-06-03T10:00:00.0000000', timeZone: 'UTC' },
+      end: { dateTime: '2025-06-03T10:30:00.0000000', timeZone: 'UTC' },
+      isAllDay: false,
+      location: 'Room 1',
+      organizer: { name: 'Alice', address: 'alice@x.com' },
+      attendees: [{ name: 'Bob', address: 'bob@y.com', type: 'required', response: 'accepted' }],
+      onlineMeeting: { joinUrl: 'https://teams.example/join' },
+      webLink: 'https://outlook.office.com/evt-1',
+    })
+  })
+
+  it('returns a null onlineMeeting when the event has no join URL', () => {
+    const event: GraphEvent = { id: 'evt-2' }
+    const flattened = flattenGraphEvent(event)
+    expect(flattened.onlineMeeting).toBeNull()
+    expect(flattened.attendees).toEqual([])
+  })
+})

apps/sim/tools/outlook/calendar-utils.ts

@@ -0,0 +1,133 @@
+import type {
+  CleanedOutlookEvent,
+  CleanedOutlookEventAttendee,
+  GraphAttendee,
+  GraphDateTimeTimeZone,
+  GraphEvent,
+} from '@/tools/outlook/types'
+import type { ToolRetryConfig } from '@/tools/types'
+
+/**
+ * Shared retry config for the Outlook calendar tools.
+ *
+ * Microsoft Graph throttles a single mailbox at roughly four concurrent requests and
+ * returns 429 with a `Retry-After` header when calendar operations fan out (e.g. many
+ * parallel event creates in a workflow). The tool executor retries 429/5xx with backoff
+ * and honors `Retry-After`. `retryIdempotentOnly` is `false` so create/update/respond
+ * (POST/PATCH) also retry — a 429 is a pre-processing throttle, so retrying does not
+ * duplicate the event.
+ */
+export const CALENDAR_RETRY: ToolRetryConfig = {
+  enabled: true,
+  maxRetries: 3,
+  initialDelayMs: 500,
+  maxDelayMs: 30000,
+  retryIdempotentOnly: false,
+}
+
+/** Matches a trailing UTC offset (`Z`, `+02:00`, `-0800`) on an ISO datetime string. */
+const TZ_OFFSET_PATTERN = /([+-]\d{2}:?\d{2}|Z)$/
+
+/** Matches the milliseconds + `Z` suffix produced by `Date.toISOString()`. */
+const ISO_MS_ZULU_PATTERN = /\.\d{3}Z$/
+
+/** Time zone recorded when the caller supplies none and the datetime carries no offset. */
+export const DEFAULT_OUTLOOK_TIME_ZONE = 'UTC'
+
+/** Attendee category understood by Microsoft Graph. */
+export type GraphAttendeeType = 'required' | 'optional' | 'resource'
+
+/** Attendee payload shape Microsoft Graph expects on event create/update. */
+export interface GraphAttendeeInput {
+  emailAddress: { address: string }
+  type: GraphAttendeeType
+}
+
+/**
+ * Build a Microsoft Graph `{ dateTime, timeZone }` value from a user-supplied datetime.
+ *
+ * Graph expects an offset-less `dateTime` paired with a named `timeZone`, unlike Google
+ * Calendar which accepts the offset inside the string. Behavior:
+ * - Date-only input (`2025-06-03`) is pinned to midnight for an all-day event.
+ * - An input carrying a UTC offset (`...Z` or `+02:00`) is converted to the equivalent UTC
+ *   instant so Graph interprets it unambiguously.
+ * - A naive datetime is treated as wall-clock time in the provided (or default) zone.
+ */
+export function buildGraphEventDateTime(value: string, timeZone?: string): GraphDateTimeTimeZone {
+  const trimmed = value.trim()
+
+  if (!trimmed.includes('T')) {
+    return { dateTime: `${trimmed}T00:00:00`, timeZone: timeZone || DEFAULT_OUTLOOK_TIME_ZONE }
+  }
+
+  const offsetMatch = trimmed.match(TZ_OFFSET_PATTERN)
+  if (offsetMatch) {
+    const parsed = new Date(trimmed)
+    if (!Number.isNaN(parsed.getTime())) {
+      return { dateTime: parsed.toISOString().replace(ISO_MS_ZULU_PATTERN, ''), timeZone: 'UTC' }
+    }
+    // Unparseable offset: strip it and fall back to the caller's zone.
+    return {
+      dateTime: trimmed.slice(0, trimmed.length - offsetMatch[0].length),
+      timeZone: timeZone || DEFAULT_OUTLOOK_TIME_ZONE,
+    }
+  }
+
+  return { dateTime: trimmed, timeZone: timeZone || DEFAULT_OUTLOOK_TIME_ZONE }
+}
+
+/**
+ * Normalize a comma/newline-separated string (or array) of email addresses into the Graph
+ * attendee payload shape.
+ */
+export function normalizeAttendees(
+  attendees: string | string[] | undefined,
+  type: GraphAttendeeType = 'required'
+): GraphAttendeeInput[] {
+  if (!attendees) return []
+
+  const list = Array.isArray(attendees) ? attendees : String(attendees).split(/[,\n]/)
+
+  return list
+    .map((address) => address.trim())
+    .filter(Boolean)
+    .map((address) => ({ emailAddress: { address }, type }))
+}
+
+/** Flatten a raw Graph attendee into our cleaned attendee shape. */
+function flattenGraphAttendee(attendee: GraphAttendee): CleanedOutlookEventAttendee {
+  return {
+    name: attendee.emailAddress?.name,
+    address: attendee.emailAddress?.address,
+    type: attendee.type,
+    response: attendee.status?.response,
+  }
+}
+
+/**
+ * Flatten a raw Microsoft Graph event into the cleaned, editor-friendly event shape our
+ * tools return: `id, subject, start, end, organizer, attendees, isAllDay, onlineMeeting,
+ * webLink, bodyPreview`.
+ */
+export function flattenGraphEvent(event: GraphEvent): CleanedOutlookEvent {
+  return {
+    id: event.id,
+    subject: event.subject,
+    bodyPreview: event.bodyPreview,
+    start: event.start
+      ? { dateTime: event.start.dateTime, timeZone: event.start.timeZone }
+      : undefined,
+    end: event.end ? { dateTime: event.end.dateTime, timeZone: event.end.timeZone } : undefined,
+    isAllDay: event.isAllDay,
+    location: event.location?.displayName,
+    organizer: event.organizer?.emailAddress
+      ? {
+          name: event.organizer.emailAddress.name,
+          address: event.organizer.emailAddress.address,
+        }
+      : undefined,
+    attendees: (event.attendees ?? []).map(flattenGraphAttendee),
+    onlineMeeting: event.onlineMeeting?.joinUrl ? { joinUrl: event.onlineMeeting.joinUrl } : null,
+    webLink: event.webLink,
+  }
+}