msteams-mcp 0.2.0

package/dist/teams/api-interceptor.js

@@ -0,0 +1,391 @@
+/**
+ * Network request interception for Teams API calls.
+ * Captures search requests and responses for direct API usage.
+ */
+import { stripHtml, parseV2Result } from '../utils/parsers.js';
+// Patterns that indicate search-related API calls
+const SEARCH_API_PATTERNS = [
+    /substrate\.office\.com\/searchservice\/api\/v2\/query/i, // v2 query (full search)
+    /substrate\.office\.com\/search\/api\/v1\/suggestions/i, // v1 suggestions (typeahead)
+    /substrate\.office\.com\/search/i, // Other substrate search
+    /\/api\/csa\/.*\/containers\/.*\/posts/i, // Channel posts
+    /\/api\/chatsvc\/.*\/messages/i, // Chat messages
+];
+function isSearchApiUrl(url) {
+    return SEARCH_API_PATTERNS.some(pattern => pattern.test(url));
+}
+// stripHtml imported from ../utils/parsers.js
+/**
+ * Parses Substrate search API response.
+ * Handles both suggestions endpoint and full query endpoint.
+ */
+function parseSubstrateResponse(body) {
+    if (!body || typeof body !== 'object')
+        return [];
+    const results = [];
+    const obj = body;
+    // Try Groups[].Suggestions[] structure (suggestions endpoint)
+    const groups = obj.Groups;
+    if (Array.isArray(groups)) {
+        for (const group of groups) {
+            const g = group;
+            const suggestions = g.Suggestions;
+            const entityType = g.Type;
+            if (Array.isArray(suggestions)) {
+                for (const suggestion of suggestions) {
+                    const s = suggestion;
+                    // Skip people suggestions, we want messages
+                    if (entityType === 'People')
+                        continue;
+                    const result = parseSubstrateItem(s);
+                    if (result)
+                        results.push(result);
+                }
+            }
+        }
+    }
+    // Try EntitySets[].ResultSets[].Results[] structure (v2 query endpoint)
+    // Delegate to parsers.ts parseV2Result for consistency
+    const entitySets = obj.EntitySets;
+    if (Array.isArray(entitySets)) {
+        for (const entitySet of entitySets) {
+            const es = entitySet;
+            const resultSets = es.ResultSets;
+            if (Array.isArray(resultSets)) {
+                for (const resultSet of resultSets) {
+                    const rs = resultSet;
+                    const items = rs.Results;
+                    if (Array.isArray(items)) {
+                        for (const item of items) {
+                            const result = parseV2Result(item);
+                            if (result)
+                                results.push(result);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Try value[] array (common Microsoft API pattern)
+    const value = obj.value;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const result = parseSubstrateItem(item);
+            if (result)
+                results.push(result);
+        }
+    }
+    return results;
+}
+/**
+ * Extracts pagination metadata from v2 query response.
+ */
+function extractV2Pagination(body) {
+    if (!body || typeof body !== 'object')
+        return { returned: 0 };
+    const obj = body;
+    let returned = 0;
+    let total;
+    const entitySets = obj.EntitySets;
+    if (Array.isArray(entitySets)) {
+        for (const entitySet of entitySets) {
+            const es = entitySet;
+            // Try to get total from EntitySet
+            const esTotal = es.Total ?? es.TotalCount ?? es.Count;
+            if (typeof esTotal === 'number') {
+                total = esTotal;
+            }
+            const resultSets = es.ResultSets;
+            if (Array.isArray(resultSets)) {
+                for (const resultSet of resultSets) {
+                    const rs = resultSet;
+                    // Try to get total from ResultSet
+                    const rsTotal = rs.Total ?? rs.TotalCount ?? rs.TotalEstimate;
+                    if (typeof rsTotal === 'number' && total === undefined) {
+                        total = rsTotal;
+                    }
+                    const items = rs.Results;
+                    if (Array.isArray(items)) {
+                        returned += items.length;
+                    }
+                }
+            }
+        }
+    }
+    return { total, returned };
+}
+/**
+ * Parses a single Substrate search result item (suggestions endpoint).
+ */
+function parseSubstrateItem(item) {
+    // Try to extract content from various possible locations
+    const content = getStringField(item, 'Summary') ||
+        getStringField(item, 'Body') ||
+        getStringField(item, 'Content') ||
+        getStringField(item, 'Snippet') ||
+        getNestedContent(item, 'HitHighlightedSummary') ||
+        getNestedContent(item, 'Preview') ||
+        '';
+    // Skip if no meaningful content
+    if (content.length < 5)
+        return null;
+    const id = getStringField(item, 'Id') ||
+        getStringField(item, 'DocId') ||
+        getStringField(item, 'ResourceId') ||
+        `substrate-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const sender = getStringField(item, 'From') ||
+        getStringField(item, 'Author') ||
+        getStringField(item, 'DisplayName') ||
+        getNestedName(item, 'Sender') ||
+        getNestedName(item, 'From');
+    const timestamp = getStringField(item, 'ReceivedTime') ||
+        getStringField(item, 'CreatedDateTime') ||
+        getStringField(item, 'LastModifiedTime') ||
+        getStringField(item, 'SentDateTime');
+    const channelName = getStringField(item, 'ChannelName') ||
+        getStringField(item, 'Topic');
+    const teamName = getStringField(item, 'TeamName') ||
+        getStringField(item, 'GroupName');
+    return {
+        id,
+        type: 'message',
+        content: stripHtml(content),
+        sender,
+        timestamp,
+        channelName,
+        teamName,
+    };
+}
+// Note: parseV2QueryItem functionality is now delegated to parseV2Result in parsers.ts
+/**
+ * Parses Teams posts API response.
+ */
+function parsePostsResponse(body) {
+    if (!body || typeof body !== 'object')
+        return [];
+    const results = [];
+    const obj = body;
+    const posts = obj.posts;
+    if (!Array.isArray(posts))
+        return [];
+    for (const post of posts) {
+        const p = post;
+        const message = p.message;
+        if (!message)
+            continue;
+        const content = getStringField(message, 'content') || '';
+        if (content.length < 5)
+            continue;
+        const id = getStringField(p, 'id') || `post-${Date.now()}`;
+        const sender = [
+            getStringField(message, 'fromGivenNameInToken'),
+            getStringField(message, 'fromFamilyNameInToken'),
+        ].filter(Boolean).join(' ') || getStringField(message, 'imdisplayname');
+        const timestamp = getStringField(p, 'latestMessageTime') || getStringField(p, 'originalArrivalTime');
+        results.push({
+            id,
+            type: 'message',
+            content: stripHtml(content),
+            sender,
+            timestamp,
+            conversationId: getStringField(p, 'containerId'),
+            messageId: id,
+        });
+    }
+    return results;
+}
+function getStringField(obj, field) {
+    const value = obj[field];
+    return typeof value === 'string' ? value : undefined;
+}
+function getNestedContent(obj, field) {
+    const value = obj[field];
+    if (typeof value === 'string')
+        return value;
+    if (value && typeof value === 'object') {
+        const nested = value;
+        return getStringField(nested, 'Content') || getStringField(nested, 'Text');
+    }
+    return undefined;
+}
+function getNestedName(obj, field) {
+    const value = obj[field];
+    if (typeof value === 'string')
+        return value;
+    if (value && typeof value === 'object') {
+        const nested = value;
+        return (getStringField(nested, 'DisplayName') ||
+            getStringField(nested, 'Name') ||
+            getStringField(nested, 'EmailAddress'));
+    }
+    return undefined;
+}
+/**
+ * Parses a captured response based on its URL pattern.
+ */
+export function parseSearchResults(response) {
+    if (!response.body || response.status >= 400)
+        return [];
+    const url = response.url.toLowerCase();
+    if (url.includes('substrate.office.com')) {
+        return parseSubstrateResponse(response.body);
+    }
+    if (url.includes('/posts') || url.includes('/csa/')) {
+        return parsePostsResponse(response.body);
+    }
+    // Try generic parsing
+    return parseSubstrateResponse(response.body);
+}
+/**
+ * Parses a captured response and returns results with pagination info.
+ */
+export function parseSearchResultsWithPagination(response, requestedFrom = 0, requestedSize = 25) {
+    const results = parseSearchResults(response);
+    // Extract pagination from v2 query response
+    let pagination = {
+        returned: results.length,
+        from: requestedFrom,
+        size: requestedSize,
+        hasMore: results.length >= requestedSize,
+    };
+    if (response.url.includes('searchservice/api/v2/query')) {
+        const v2Pagination = extractV2Pagination(response.body);
+        pagination = {
+            returned: v2Pagination.returned,
+            from: requestedFrom,
+            size: requestedSize,
+            total: v2Pagination.total,
+            hasMore: v2Pagination.total !== undefined
+                ? requestedFrom + v2Pagination.returned < v2Pagination.total
+                : v2Pagination.returned >= requestedSize,
+        };
+    }
+    return { results, pagination };
+}
+/**
+ * Sets up request/response interception on a page.
+ * Returns an interceptor with a promise-based wait for results.
+ */
+export function setupApiInterceptor(page, debug = false) {
+    const responses = [];
+    let resolveWait = null;
+    let stopped = false;
+    const responseHandler = async (response) => {
+        if (stopped)
+            return;
+        const url = response.url();
+        if (!isSearchApiUrl(url))
+            return;
+        if (debug) {
+            console.log(`  [api] Captured response: ${url.substring(0, 80)}...`);
+        }
+        let body;
+        try {
+            const contentType = response.headers()['content-type'] || '';
+            if (contentType.includes('application/json')) {
+                body = await response.json();
+            }
+        }
+        catch {
+            // Response body may not be available
+            return;
+        }
+        const captured = {
+            url,
+            status: response.status(),
+            body,
+        };
+        responses.push(captured);
+        // Parse results and resolve if we got something
+        const results = parseSearchResults(captured);
+        if (results.length > 0 && resolveWait) {
+            if (debug) {
+                console.log(`  [api] Parsed ${results.length} results from ${url.substring(0, 60)}...`);
+            }
+            resolveWait(results);
+            resolveWait = null;
+        }
+    };
+    page.on('response', responseHandler);
+    return {
+        responses,
+        waitForSearchResults(timeoutMs = 10000) {
+            return new Promise((resolve) => {
+                // Check if we already have results
+                for (const resp of responses) {
+                    const results = parseSearchResults(resp);
+                    if (results.length > 0) {
+                        resolve(results);
+                        return;
+                    }
+                }
+                // Wait for new results
+                resolveWait = resolve;
+                // Timeout fallback
+                setTimeout(() => {
+                    if (resolveWait) {
+                        resolveWait = null;
+                        // Try to get any results we have
+                        for (const resp of responses) {
+                            const results = parseSearchResults(resp);
+                            if (results.length > 0) {
+                                resolve(results);
+                                return;
+                            }
+                        }
+                        resolve([]);
+                    }
+                }, timeoutMs);
+            });
+        },
+        waitForSearchResultsWithPagination(timeoutMs = 10000) {
+            return new Promise((resolve) => {
+                const defaultPagination = {
+                    returned: 0,
+                    from: 0,
+                    size: 25,
+                    hasMore: false,
+                };
+                // Check if we already have results
+                for (const resp of responses) {
+                    const parsed = parseSearchResultsWithPagination(resp);
+                    if (parsed.results.length > 0) {
+                        resolve(parsed);
+                        return;
+                    }
+                }
+                // Wait for new results
+                const resolveWithPagination = (results) => {
+                    // Find the response that gave us these results
+                    for (const resp of responses) {
+                        const parsed = parseSearchResultsWithPagination(resp);
+                        if (parsed.results.length > 0) {
+                            resolve(parsed);
+                            return;
+                        }
+                    }
+                    resolve({ results, pagination: { ...defaultPagination, returned: results.length } });
+                };
+                resolveWait = resolveWithPagination;
+                // Timeout fallback
+                setTimeout(() => {
+                    if (resolveWait) {
+                        resolveWait = null;
+                        for (const resp of responses) {
+                            const parsed = parseSearchResultsWithPagination(resp);
+                            if (parsed.results.length > 0) {
+                                resolve(parsed);
+                                return;
+                            }
+                        }
+                        resolve({ results: [], pagination: defaultPagination });
+                    }
+                }, timeoutMs);
+            });
+        },
+        stop() {
+            stopped = true;
+            page.off('response', responseHandler);
+        },
+    };
+}

package/dist/teams/direct-api.d.ts

@@ -0,0 +1,321 @@
+/**
+ * Direct API client for Teams/Substrate search.
+ *
+ * Extracts auth tokens from browser session state and makes
+ * direct HTTP calls without needing an active browser.
+ */
+import type { TeamsSearchResult, SearchPaginationResult } from '../types/teams.js';
+import { buildMessageLink, type PersonSearchResult, type UserProfile } from '../utils/parsers.js';
+interface TeamsTokenInfo {
+    token: string;
+    expiry: Date;
+    userMri: string;
+}
+interface MessageAuthInfo {
+    skypeToken: string;
+    authToken: string;
+    userMri: string;
+}
+interface DirectSearchResult {
+    results: TeamsSearchResult[];
+    pagination: SearchPaginationResult;
+}
+export type { UserProfile } from '../utils/parsers.js';
+/**
+ * Gets the current user's profile from cached JWT tokens.
+ *
+ * Extracts user info from MSAL tokens stored in session state.
+ * No API call needed - just parses existing tokens.
+ */
+export declare function getMe(): UserProfile | null;
+/**
+ * Extracts the Substrate search token from session state.
+ */
+export declare function extractSubstrateToken(): {
+    token: string;
+    expiry: Date;
+} | null;
+/**
+ * Gets a valid token, either from cache or by extracting from session.
+ */
+export declare function getValidToken(): string | null;
+/**
+ * Clears the token cache (forces re-extraction on next call).
+ */
+export declare function clearTokenCache(): void;
+/**
+ * Checks if we have a valid token for direct API calls.
+ */
+export declare function hasValidToken(): boolean;
+/**
+ * Gets token status for diagnostics.
+ */
+export declare function getTokenStatus(): {
+    hasToken: boolean;
+    expiresAt?: string;
+    minutesRemaining?: number;
+};
+/**
+ * Makes a direct search API call to Substrate.
+ */
+export declare function directSearch(query: string, options?: {
+    from?: number;
+    size?: number;
+    maxResults?: number;
+}): Promise<DirectSearchResult>;
+/**
+ * Extracts the Teams API token and user MRI from session state.
+ * This is different from the Substrate token - it's used for chat APIs.
+ *
+ * The chat API requires a token with audience:
+ * - https://chatsvcagg.teams.microsoft.com (preferred)
+ * - https://api.spaces.skype.com (fallback)
+ */
+export declare function extractTeamsToken(): TeamsTokenInfo | null;
+/**
+ * Extracts authentication info needed for sending messages.
+ * Uses cookies (skypetoken_asm) which are required for the chatsvc API.
+ */
+export declare function extractMessageAuth(): MessageAuthInfo | null;
+/**
+ * Extracts the CSA (Chat Service Aggregator) token for the conversationFolders API.
+ * This token is different from the chatsvc token and is required for favorites operations.
+ */
+export declare function extractCsaToken(): string | null;
+/**
+ * Gets user's display name from session state.
+ */
+export declare function getUserDisplayName(): string | null;
+export interface SendMessageResult {
+    success: boolean;
+    messageId?: string;
+    timestamp?: number;
+    error?: string;
+}
+export type { PersonSearchResult } from '../utils/parsers.js';
+/** Search people results with count. */
+export interface PeopleSearchResults {
+    results: PersonSearchResult[];
+    returned: number;
+}
+/** Frequent contacts result. */
+export interface FrequentContactsResult {
+    contacts: PersonSearchResult[];
+    returned: number;
+}
+/** A favourite/pinned conversation item. */
+export interface FavoriteItem {
+    conversationId: string;
+    displayName?: string;
+    conversationType?: string;
+    createdTime?: number;
+    lastUpdatedTime?: number;
+}
+/** Response from getting favorites. */
+export interface FavoritesResult {
+    success: boolean;
+    favorites: FavoriteItem[];
+    folderHierarchyVersion?: number;
+    folderId?: string;
+    error?: string;
+}
+/** Result of modifying favorites. */
+export interface FavoriteModifyResult {
+    success: boolean;
+    error?: string;
+}
+/** Result of saving/unsaving a message. */
+export interface SaveMessageResult {
+    success: boolean;
+    conversationId?: string;
+    messageId?: string;
+    saved?: boolean;
+    error?: string;
+}
+/**
+ * Sends a message to a Teams conversation.
+ *
+ * Uses the skypetoken_asm cookie for authentication, which is required
+ * by the Teams chatsvc API.
+ *
+ * @param conversationId - The conversation ID (e.g., "48:notes" for self-chat)
+ * @param content - Message content (HTML supported)
+ * @param region - Region for the API (default: "amer")
+ */
+export declare function sendMessage(conversationId: string, content: string, region?: string): Promise<SendMessageResult>;
+/**
+ * Sends a message to your own notes/self-chat.
+ */
+export declare function sendNoteToSelf(content: string): Promise<SendMessageResult>;
+/**
+ * Searches for people by name or email using the Substrate suggestions API.
+ *
+ * Uses the same auth token as message search.
+ *
+ * @param query - Search term (name, email, or partial match)
+ * @param limit - Maximum number of results (default: 10)
+ */
+export declare function searchPeople(query: string, limit?: number): Promise<PeopleSearchResults>;
+/**
+ * Gets the user's frequently contacted people.
+ *
+ * Uses the peoplecache scenario which returns contacts ranked by
+ * interaction frequency. Useful for resolving ambiguous names
+ * (e.g., "Rob" → "Rob Smith <rob.smith@company.com>").
+ *
+ * @param limit - Maximum number of contacts to return (default: 50)
+ */
+export declare function getFrequentContacts(limit?: number): Promise<FrequentContactsResult>;
+/**
+ * Gets the user's favourite/pinned conversations.
+ *
+ * Uses the conversationFolders API with CSA token authentication.
+ * Requires both the skypetoken (from cookies) and the CSA token (from MSAL).
+ *
+ * @param region - Region for the API (default: "amer")
+ */
+export declare function getFavorites(region?: string): Promise<FavoritesResult>;
+/**
+ * Adds a conversation to the user's favourites.
+ *
+ * @param conversationId - The conversation ID to add
+ * @param region - Region for the API (default: "amer")
+ */
+export declare function addFavorite(conversationId: string, region?: string): Promise<FavoriteModifyResult>;
+/**
+ * Removes a conversation from the user's favourites.
+ *
+ * @param conversationId - The conversation ID to remove
+ * @param region - Region for the API (default: "amer")
+ */
+export declare function removeFavorite(conversationId: string, region?: string): Promise<FavoriteModifyResult>;
+/**
+ * Saves (bookmarks) a message.
+ *
+ * @param conversationId - The conversation ID containing the message
+ * @param messageId - The message ID to save (numeric string)
+ * @param region - Region for the API (default: "amer")
+ */
+export declare function saveMessage(conversationId: string, messageId: string, region?: string): Promise<SaveMessageResult>;
+/**
+ * Unsaves (removes bookmark from) a message.
+ *
+ * @param conversationId - The conversation ID containing the message
+ * @param messageId - The message ID to unsave (numeric string)
+ * @param region - Region for the API (default: "amer")
+ */
+export declare function unsaveMessage(conversationId: string, messageId: string, region?: string): Promise<SaveMessageResult>;
+/** A message from a thread/conversation. */
+export interface ThreadMessage {
+    id: string;
+    content: string;
+    contentType: string;
+    sender: {
+        mri: string;
+        displayName?: string;
+    };
+    timestamp: string;
+    conversationId: string;
+    clientMessageId?: string;
+    isFromMe?: boolean;
+    messageLink?: string;
+}
+/** Result of getting thread messages. */
+export interface GetThreadResult {
+    success: boolean;
+    conversationId?: string;
+    messages?: ThreadMessage[];
+    error?: string;
+}
+/**
+ * Gets messages from a Teams conversation/thread.
+ *
+ * This retrieves messages from a conversation, which can be:
+ * - A 1:1 or group chat
+ * - A channel thread
+ * - Self-notes (48:notes)
+ *
+ * @param conversationId - The conversation ID (e.g., "19:abc@thread.tacv2")
+ * @param options - Optional parameters for pagination
+ * @param options.limit - Maximum number of messages to return (default: 50)
+ * @param options.startTime - Only get messages after this timestamp (epoch ms)
+ * @param region - Region for the API (default: "amer")
+ */
+export declare function getThreadMessages(conversationId: string, options?: {
+    limit?: number;
+    startTime?: number;
+}, region?: string): Promise<GetThreadResult>;
+export { buildMessageLink };
+/** A channel within a team. */
+export interface TeamChannel {
+    id: string;
+    displayName: string;
+    description?: string;
+    isFavorite?: boolean;
+    membershipType?: string;
+}
+/** A team the user is a member of. */
+export interface Team {
+    id: string;
+    displayName: string;
+    description?: string;
+    pictureETag?: string;
+    isFavorite?: boolean;
+    channels: TeamChannel[];
+}
+/** Result of getting joined teams. */
+export interface JoinedTeamsResult {
+    success: boolean;
+    teams?: Team[];
+    error?: string;
+}
+/** A channel with its parent team info. */
+export interface ChannelWithTeam {
+    channel: TeamChannel;
+    team: {
+        id: string;
+        displayName: string;
+    };
+}
+/** Result of finding channels. */
+export interface FindChannelResult {
+    success: boolean;
+    channels?: ChannelWithTeam[];
+    error?: string;
+}
+/**
+ * Gets all teams and channels the user is a member of.
+ *
+ * Uses the CSA v3 teams/users/me endpoint which returns the full
+ * teams and channels structure.
+ *
+ * @param region - Region for the API (default: "amer")
+ */
+export declare function getJoinedTeams(region?: string): Promise<JoinedTeamsResult>;
+/**
+ * Gets channels for a specific team.
+ *
+ * This is a convenience wrapper that calls getJoinedTeams and filters
+ * to the specified team.
+ *
+ * @param teamId - The team ID to get channels for
+ * @param region - Region for the API (default: "amer")
+ */
+export declare function getTeamChannels(teamId: string, region?: string): Promise<{
+    success: boolean;
+    channels?: TeamChannel[];
+    error?: string;
+}>;
+/**
+ * Finds channels by name across all teams the user is a member of.
+ *
+ * Performs a case-insensitive substring match on channel names.
+ *
+ * @param query - The channel name to search for (partial match)
+ * @param options - Optional filters
+ * @param options.teamName - Filter to a specific team name (partial match)
+ * @param region - Region for the API (default: "amer")
+ */
+export declare function findChannel(query: string, options?: {
+    teamName?: string;
+}, region?: string): Promise<FindChannelResult>;