msteams-mcp 0.2.1

package/dist/__fixtures__/api-responses.js

@@ -0,0 +1,245 @@
+/**
+ * API response fixtures for testing.
+ *
+ * These are based on real API response structures documented in docs/API-REFERENCE.md.
+ * They represent the shape of data returned by Teams/Substrate APIs.
+ */
+/**
+ * Substrate v2 search result item.
+ * From: POST https://substrate.office.com/searchservice/api/v2/query
+ */
+export const searchResultItem = {
+    Id: 'AAMkAGE1OWFlZjc0LWYxMjQtNGM1Mi05NzJlLTU0MTU2ZGU1OGM1YQBGAAAAAACaT2h4EH4ZT5pQgKA-example',
+    ReferenceId: 'abc123-def456.1000.1',
+    HitHighlightedSummary: 'Let me check the <c0>budget</c0> report for Q3',
+    Summary: 'Let me check the budget report for Q3',
+    Source: {
+        DateTimeReceived: '2026-01-20T14:30:00.000Z', // = 1768919400000
+        From: {
+            EmailAddress: {
+                Name: 'Smith, John',
+                Address: 'john.smith@company.com',
+            },
+        },
+        ChannelName: 'General',
+        TeamName: 'Finance Team',
+        Extensions: {
+            SkypeSpaces_ConversationPost_Extension_SkypeGroupId: '19:abcdef123456@thread.tacv2',
+        },
+        // Top-level post: messageid matches DateTimeReceived timestamp
+        ClientConversationId: '19:abcdef123456@thread.tacv2;messageid=1768919400000',
+    },
+};
+/**
+ * Search result with HTML content that needs stripping.
+ */
+export const searchResultWithHtml = {
+    Id: 'AAMkBGFiY2RlZg',
+    ReferenceId: 'xyz789.1000.1',
+    HitHighlightedSummary: '<p>Meeting <strong>notes</strong> from &amp; yesterday&apos;s call</p><br/><div>Action items:</div>',
+    Source: {
+        DateTimeReceived: '2026-01-21T09:00:00.000Z',
+        From: 'Jane Doe',
+        ClientThreadId: '19:meeting123@thread.v2',
+    },
+};
+/**
+ * Minimal search result with only required fields.
+ */
+export const searchResultMinimal = {
+    Id: 'minimal-id',
+    HitHighlightedSummary: 'A short message here',
+};
+/**
+ * Search result too short to be valid (content < 5 chars).
+ */
+export const searchResultTooShort = {
+    Id: 'short-id',
+    HitHighlightedSummary: 'Hi',
+};
+/**
+ * Full EntitySets response structure from v2 query.
+ */
+export const searchEntitySetsResponse = {
+    EntitySets: [
+        {
+            ResultSets: [
+                {
+                    Total: 4307,
+                    Results: [
+                        searchResultItem,
+                        searchResultWithHtml,
+                    ],
+                },
+            ],
+        },
+    ],
+};
+/**
+ * Person suggestion from Substrate suggestions API.
+ * From: POST https://substrate.office.com/search/api/v1/suggestions
+ */
+export const personSuggestion = {
+    Id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890@company.onmicrosoft.com',
+    MRI: '8:orgid:a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+    DisplayName: 'Smith, John',
+    GivenName: 'John',
+    Surname: 'Smith',
+    EmailAddresses: ['john.smith@company.com'],
+    CompanyName: 'Acme Corp',
+    Department: 'Engineering',
+    JobTitle: 'Senior Engineer',
+};
+/**
+ * Person with minimal info using a proper GUID (no optional fields).
+ */
+export const personMinimal = {
+    Id: 'b1c2d3e4-f5a6-7890-bcde-1234567890ab',
+    DisplayName: 'Jane Doe',
+};
+/**
+ * Person with base64-encoded GUID (real-world API response format).
+ * The base64 '93qkaTtFGWpUHjyRafgdhg==' decodes to GUID '69a47af7-453b-6a19-541e-3c9169f81d86'.
+ */
+export const personWithBase64Id = {
+    Id: '93qkaTtFGWpUHjyRafgdhg==',
+    MRI: '8:orgid:93qkaTtFGWpUHjyRafgdhg==',
+    DisplayName: 'Rob MacDonald',
+    EmailAddresses: ['rob@company.com'],
+};
+/**
+ * Groups response from suggestions API.
+ */
+export const peopleGroupsResponse = {
+    Groups: [
+        {
+            Suggestions: [
+                personSuggestion,
+                personMinimal,
+            ],
+        },
+    ],
+};
+/**
+ * JWT payload with full user info.
+ */
+export const jwtPayloadFull = {
+    oid: 'user-object-id-guid',
+    name: 'Macdonald, Rob',
+    upn: 'rob.macdonald@company.com',
+    preferred_username: 'rob@company.com',
+    email: 'rob.m@personal.com',
+    given_name: 'Rob',
+    family_name: 'Macdonald',
+    tid: 'tenant-id-guid',
+    exp: 1705850000,
+    iat: 1705846400,
+};
+/**
+ * JWT payload with minimal info (only required fields).
+ */
+export const jwtPayloadMinimal = {
+    oid: 'another-user-guid',
+    name: 'Alice Smith',
+    exp: 1705850000,
+};
+/**
+ * JWT payload for name parsing tests - "Surname, GivenName" format.
+ */
+export const jwtPayloadCommaName = {
+    oid: 'comma-name-user',
+    name: 'Jones, David',
+    upn: 'david.jones@company.com',
+};
+/**
+ * JWT payload for name parsing tests - "GivenName Surname" format.
+ */
+export const jwtPayloadSpaceName = {
+    oid: 'space-name-user',
+    name: 'Sarah Connor',
+    upn: 'sarah.connor@company.com',
+};
+/**
+ * Channel thread reply - messageid differs from message timestamp.
+ * The parent post was at 1768919400000 (2026-01-20T14:30:00.000Z),
+ * this reply is at 1768921200000 (2026-01-20T15:00:00.000Z).
+ */
+export const searchResultThreadReply = {
+    Id: 'AAMkThreadReply',
+    ReferenceId: 'thread-reply.1000.1',
+    HitHighlightedSummary: 'Thanks for the update on the budget!',
+    Source: {
+        DateTimeReceived: '2026-01-20T15:00:00.000Z', // = 1768921200000
+        From: {
+            EmailAddress: {
+                Name: 'Doe, Jane',
+                Address: 'jane.doe@company.com',
+            },
+        },
+        ChannelName: 'General',
+        TeamName: 'Finance Team',
+        Extensions: {
+            SkypeSpaces_ConversationPost_Extension_SkypeGroupId: '19:abcdef123456@thread.tacv2',
+        },
+        // Parent message ID (1768919400000) differs from this message's timestamp (1768921200000)
+        ClientConversationId: '19:abcdef123456@thread.tacv2;messageid=1768919400000',
+        ClientThreadId: '19:abcdef123456@thread.tacv2',
+    },
+};
+/**
+ * Message source with explicit message ID.
+ */
+export const sourceWithMessageId = {
+    MessageId: '1705760000000',
+    DateTimeReceived: '2026-01-20T12:00:00.000Z',
+    ClientConversationId: '19:thread@tacv2',
+};
+/**
+ * Message source with ID in ClientConversationId.
+ */
+export const sourceWithConvIdMessageId = {
+    DateTimeReceived: '2026-01-20T12:00:00.000Z',
+    ClientConversationId: '19:thread@tacv2;messageid=1705770000000',
+};
+/**
+ * Thread message from chatsvc API.
+ * From: GET /api/chatsvc/{region}/v1/users/ME/conversations/{id}/messages
+ */
+export const threadMessage = {
+    id: '1705760000000',
+    content: '<p>Hello team!</p>',
+    messagetype: 'RichText/Html',
+    contenttype: 'text',
+    from: '8:orgid:user-guid-123',
+    imdisplayname: 'John Smith',
+    originalarrivaltime: '2026-01-20T12:00:00.000Z',
+    composetime: '2026-01-20T11:59:58.000Z',
+    clientmessageid: 'client-msg-123',
+};
+/**
+ * Favorites folder response.
+ * From: POST /api/csa/{region}/api/v1/teams/users/me/conversationFolders
+ */
+export const favoritesFolderResponse = {
+    folderHierarchyVersion: 1705850000000,
+    conversationFolders: [
+        {
+            id: 'tenant-guid~user-guid~Favorites',
+            sortType: 'UserDefinedCustomOrder',
+            name: 'Favorites',
+            folderType: 'Favorites',
+            conversationFolderItems: [
+                {
+                    conversationId: '19:abc@thread.tacv2',
+                    createdTime: 1705700000000,
+                    lastUpdatedTime: 1705800000000,
+                },
+                {
+                    conversationId: '19:xyz@thread.v2',
+                    createdTime: 1705600000000,
+                    lastUpdatedTime: 1705750000000,
+                },
+            ],
+        },
+    ],
+};

package/dist/api/calendar-api.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Calendar API client for meeting operations.
+ *
+ * Handles calls to teams.microsoft.com/api/mt/part/{region}/v2.1/me/calendars endpoints.
+ */
+import { type Result } from '../types/result.js';
+/** Organiser information for a meeting. */
+export interface MeetingOrganizer {
+    name: string;
+    email: string;
+}
+/** A calendar meeting/event. */
+export interface Meeting {
+    /** Unique identifier for the meeting. */
+    id: string;
+    /** Meeting subject/title. */
+    subject: string;
+    /** Start time (ISO 8601). */
+    startTime: string;
+    /** End time (ISO 8601). */
+    endTime: string;
+    /** Meeting organiser. */
+    organizer: MeetingOrganizer;
+    /** Location (room name or text). */
+    location?: string;
+    /** Whether this is a Teams online meeting. */
+    isOnlineMeeting: boolean;
+    /** Teams join URL (if online meeting). */
+    joinUrl?: string;
+    /** Meeting chat thread ID (for use with teams_get_thread). */
+    threadId?: string;
+    /** Your RSVP status. */
+    myResponse: 'None' | 'Accepted' | 'Tentative' | 'Declined';
+    /** Calendar show-as status. */
+    showAs: 'Free' | 'Busy' | 'Tentative' | 'OutOfOffice' | 'Unknown';
+    /** Whether you're the organiser. */
+    isOrganizer: boolean;
+    /** Event type (Single, Occurrence, Exception, SeriesMaster). */
+    eventType: string;
+}
+/** Options for fetching calendar view. */
+export interface CalendarViewOptions {
+    /** Start of date range (ISO 8601). Defaults to now. */
+    startDate?: string;
+    /** End of date range (ISO 8601). Defaults to 7 days from now. */
+    endDate?: string;
+    /** Maximum results to return. */
+    limit?: number;
+}
+/** Response from getting calendar view. */
+export interface CalendarViewResult {
+    /** Number of meetings returned. */
+    count: number;
+    /** List of meetings. */
+    meetings: Meeting[];
+}
+/**
+ * Gets meetings from the user's calendar for a date range.
+ *
+ * The region and partition are extracted from the user's session (DISCOVER-REGION-GTM),
+ * so we always use the correct endpoint without guessing.
+ *
+ * @param options - Options for filtering meetings
+ * @returns List of meetings
+ */
+export declare function getCalendarView(options?: CalendarViewOptions): Promise<Result<CalendarViewResult>>;

package/dist/api/calendar-api.js

@@ -0,0 +1,179 @@
+/**
+ * Calendar API client for meeting operations.
+ *
+ * Handles calls to teams.microsoft.com/api/mt/part/{region}/v2.1/me/calendars endpoints.
+ */
+import { httpRequest } from '../utils/http.js';
+import { CALENDAR_API, getTeamsHeaders } from '../utils/api-config.js';
+import { ok, err } from '../types/result.js';
+import { ErrorCode, createError } from '../types/errors.js';
+import { requireCalendarAuth } from '../utils/auth-guards.js';
+import { extractRegionConfig } from '../auth/token-extractor.js';
+import { DEFAULT_MEETING_LIMIT, DEFAULT_MEETING_DAYS_AHEAD, } from '../constants.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Parses a raw API meeting response into our Meeting type.
+ */
+function parseMeeting(raw) {
+    // Extract thread ID from skypeTeamsData if present
+    let threadId;
+    const skypeTeamsData = raw.skypeTeamsData;
+    if (skypeTeamsData) {
+        try {
+            const parsed = JSON.parse(skypeTeamsData);
+            threadId = parsed.cid;
+        }
+        catch {
+            // Ignore parsing errors
+        }
+    }
+    // Map response type to our enum values
+    const rawResponse = raw.myResponseType;
+    let myResponse = 'None';
+    if (rawResponse === 'Accepted' || rawResponse === 'Organizer') {
+        myResponse = 'Accepted';
+    }
+    else if (rawResponse === 'Tentative' || rawResponse === 'TentativelyAccepted') {
+        myResponse = 'Tentative';
+    }
+    else if (rawResponse === 'Declined') {
+        myResponse = 'Declined';
+    }
+    // Map showAs values
+    const rawShowAs = raw.showAs;
+    let showAs = 'Unknown';
+    if (rawShowAs === 'Free') {
+        showAs = 'Free';
+    }
+    else if (rawShowAs === 'Busy') {
+        showAs = 'Busy';
+    }
+    else if (rawShowAs === 'Tentative') {
+        showAs = 'Tentative';
+    }
+    else if (rawShowAs === 'Oof' || rawShowAs === 'OutOfOffice') {
+        showAs = 'OutOfOffice';
+    }
+    return {
+        id: raw.objectId,
+        subject: raw.subject || '(No subject)',
+        startTime: raw.startTime,
+        endTime: raw.endTime,
+        organizer: {
+            name: raw.organizerName || 'Unknown',
+            email: raw.organizerAddress || '',
+        },
+        location: raw.location,
+        isOnlineMeeting: raw.isOnlineMeeting === true,
+        joinUrl: raw.skypeTeamsMeetingUrl,
+        threadId,
+        myResponse,
+        showAs,
+        isOrganizer: raw.isOrganizer === true,
+        eventType: raw.eventType || 'Single',
+    };
+}
+/**
+ * Builds the select fields for the calendar API.
+ */
+function getSelectFields() {
+    return [
+        'cleanGlobalObjectId',
+        'endTime',
+        'eventTimeZone',
+        'eventType',
+        'hasAttachments',
+        'iCalUid',
+        'isAllDayEvent',
+        'isAppointment',
+        'isCancelled',
+        'isOnlineMeeting',
+        'isOrganizer',
+        'isPrivate',
+        'lastModifiedTime',
+        'location',
+        'myResponseType',
+        'objectId',
+        'organizerAddress',
+        'organizerName',
+        'schedulingServiceUpdateUrl',
+        'showAs',
+        'skypeTeamsData',
+        'skypeTeamsMeetingUrl',
+        'startTime',
+        'subject',
+    ].join(',');
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// API Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Gets meetings from the user's calendar for a date range.
+ *
+ * The region and partition are extracted from the user's session (DISCOVER-REGION-GTM),
+ * so we always use the correct endpoint without guessing.
+ *
+ * @param options - Options for filtering meetings
+ * @returns List of meetings
+ */
+export async function getCalendarView(options = {}) {
+    const authResult = requireCalendarAuth();
+    if (!authResult.ok) {
+        return authResult;
+    }
+    const { skypeToken, spacesToken } = authResult.value;
+    // Get the user's region/partition from session discovery config
+    const regionConfig = extractRegionConfig();
+    if (!regionConfig) {
+        return err(createError(ErrorCode.AUTH_REQUIRED, 'Could not determine region. Please run teams_login to authenticate.', { suggestions: ['Call teams_login to authenticate'] }));
+    }
+    // Calculate default date range
+    const now = new Date();
+    const defaultEnd = new Date(now);
+    defaultEnd.setDate(defaultEnd.getDate() + DEFAULT_MEETING_DAYS_AHEAD);
+    const startDate = options.startDate || now.toISOString();
+    const endDate = options.endDate || defaultEnd.toISOString();
+    const limit = options.limit || DEFAULT_MEETING_LIMIT;
+    // Build query parameters
+    const params = new URLSearchParams({
+        startDate,
+        endDate,
+        '$top': limit.toString(),
+        '$count': 'true',
+        '$skip': '0',
+        '$orderby': 'startTime asc',
+        // Filter out appointments (blocks), all-day events, and cancelled meetings
+        '$filter': 'isAppointment eq false and isAllDayEvent eq false and isCancelled eq false',
+        '$select': getSelectFields(),
+    });
+    // Use the exact region-partition from session discovery
+    // Some tenants use partitioned URLs (/api/mt/part/amer-02), others don't (/api/mt/emea)
+    const calendarUrl = CALENDAR_API.calendarView(regionConfig.regionPartition, regionConfig.hasPartition, regionConfig.teamsBaseUrl);
+    const url = `${calendarUrl}?${params.toString()}`;
+    const response = await httpRequest(url, {
+        method: 'GET',
+        headers: {
+            ...getTeamsHeaders(regionConfig.teamsBaseUrl),
+            'Authentication': `skypetoken=${skypeToken}`,
+            'Authorization': `Bearer ${spacesToken}`,
+        },
+    });
+    if (!response.ok) {
+        return response;
+    }
+    const data = response.value.data;
+    const rawMeetings = data.value;
+    if (!rawMeetings || !Array.isArray(rawMeetings)) {
+        return ok({
+            count: 0,
+            meetings: [],
+        });
+    }
+    const meetings = rawMeetings.map(parseMeeting);
+    return ok({
+        count: meetings.length,
+        meetings,
+    });
+}