msteams-mcp 0.2.1

package/dist/utils/auth-guards.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Authentication guard utilities.
+ *
+ * Provides reusable auth checks that return Result types for consistent
+ * error handling across API modules.
+ */
+import { type McpError } from '../types/errors.js';
+import { type Result } from '../types/result.js';
+import { type MessageAuthInfo, type RegionConfig } from '../auth/token-extractor.js';
+/** Authentication info for messaging and CSA APIs. */
+export interface CsaAuthInfo {
+    auth: MessageAuthInfo;
+    csaToken: string;
+}
+/**
+ * Requires a valid Substrate token with proactive refresh.
+ *
+ * This async version attempts to refresh tokens if they're approaching
+ * expiry (within 10 minutes). Use this in tool handlers for better UX.
+ */
+export declare function requireSubstrateTokenAsync(): Promise<Result<string, McpError>>;
+/**
+ * Requires valid message authentication.
+ * Use for chatsvc messaging APIs.
+ */
+export declare function requireMessageAuth(): Result<MessageAuthInfo, McpError>;
+/**
+ * Requires valid CSA authentication (message auth + CSA token).
+ * Use for favourites and team list APIs.
+ */
+export declare function requireCsaAuth(): Result<CsaAuthInfo, McpError>;
+/** Authentication info for calendar/meetings API. */
+export interface CalendarAuthInfo {
+    skypeToken: string;
+    spacesToken: string;
+}
+/**
+ * Requires valid calendar authentication (Skype token + Spaces token).
+ * Use for mt/part calendar APIs.
+ */
+export declare function requireCalendarAuth(): Result<CalendarAuthInfo, McpError>;
+/**
+ * Gets the user's region from session, with caching.
+ *
+ * The region is extracted from the DISCOVER-REGION-GTM config in localStorage.
+ * Falls back to 'amer' if not available (shouldn't happen with valid session).
+ */
+export declare function getRegion(): string;
+/**
+ * Gets the Teams base URL from session config.
+ *
+ * Returns the base URL for API calls (e.g., "https://teams.microsoft.com" for
+ * commercial cloud, or "https://teams.microsoft.us" for GCC).
+ * Falls back to default if config not available.
+ */
+export declare function getTeamsBaseUrl(): string;
+/**
+ * Gets the full region config including partition and URLs.
+ *
+ * Returns null if no valid session - caller should handle auth error.
+ */
+export declare function getRegionConfig(): RegionConfig | null;
+/**
+ * Clears the cached region config.
+ * Call this after login/logout to pick up new session.
+ */
+export declare function clearRegionCache(): void;

package/dist/utils/auth-guards.js

@@ -0,0 +1,147 @@
+/**
+ * Authentication guard utilities.
+ *
+ * Provides reusable auth checks that return Result types for consistent
+ * error handling across API modules.
+ */
+import { ErrorCode, createError } from '../types/errors.js';
+import { err, ok } from '../types/result.js';
+import { getValidSubstrateToken, extractMessageAuth, extractCsaToken, extractSubstrateToken, extractSkypeSpacesToken, extractRegionConfig, } from '../auth/token-extractor.js';
+import { TOKEN_REFRESH_THRESHOLD_MS } from '../constants.js';
+import { refreshTokensViaBrowser } from '../auth/token-refresh.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Error Messages
+// ─────────────────────────────────────────────────────────────────────────────
+const AUTH_ERROR_MESSAGES = {
+    messageAuth: 'No valid authentication. Browser login required.',
+    csaToken: 'No valid authentication for favourites. Browser login required.',
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Guard Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Checks if the Substrate token needs refresh (expired or approaching expiry).
+ *
+ * @returns true if token is expired or will expire within the refresh threshold
+ */
+function shouldRefreshSubstrateToken() {
+    const substrate = extractSubstrateToken();
+    if (!substrate)
+        return false;
+    const timeRemaining = substrate.expiry.getTime() - Date.now();
+    // Refresh if expired (timeRemaining <= 0) OR approaching expiry
+    return timeRemaining < TOKEN_REFRESH_THRESHOLD_MS;
+}
+/**
+ * Requires a valid Substrate token with proactive refresh.
+ *
+ * This async version attempts to refresh tokens if they're approaching
+ * expiry (within 10 minutes). Use this in tool handlers for better UX.
+ */
+export async function requireSubstrateTokenAsync() {
+    // Check if we need to refresh proactively
+    if (shouldRefreshSubstrateToken()) {
+        const refreshResult = await refreshTokensViaBrowser();
+        if (refreshResult.ok) {
+            // Refresh succeeded, get the new token
+            const token = getValidSubstrateToken();
+            if (token) {
+                return ok(token);
+            }
+        }
+        // Refresh failed but token might still be valid, continue
+    }
+    // Try to get existing token
+    const token = getValidSubstrateToken();
+    if (!token) {
+        // Token expired and refresh not available/failed
+        return err(createError(ErrorCode.AUTH_EXPIRED, 'Token expired and automatic refresh failed. Please run teams_login to re-authenticate.', { suggestions: ['Call teams_login to re-authenticate'] }));
+    }
+    return ok(token);
+}
+/**
+ * Requires valid message authentication.
+ * Use for chatsvc messaging APIs.
+ */
+export function requireMessageAuth() {
+    const auth = extractMessageAuth();
+    if (!auth) {
+        return err(createError(ErrorCode.AUTH_REQUIRED, AUTH_ERROR_MESSAGES.messageAuth));
+    }
+    return ok(auth);
+}
+/**
+ * Requires valid CSA authentication (message auth + CSA token).
+ * Use for favourites and team list APIs.
+ */
+export function requireCsaAuth() {
+    const auth = extractMessageAuth();
+    const csaToken = extractCsaToken();
+    if (!auth?.skypeToken || !csaToken) {
+        return err(createError(ErrorCode.AUTH_REQUIRED, AUTH_ERROR_MESSAGES.csaToken));
+    }
+    return ok({ auth, csaToken });
+}
+/**
+ * Requires valid calendar authentication (Skype token + Spaces token).
+ * Use for mt/part calendar APIs.
+ */
+export function requireCalendarAuth() {
+    const auth = extractMessageAuth();
+    const spacesToken = extractSkypeSpacesToken();
+    if (!auth?.skypeToken || !spacesToken) {
+        return err(createError(ErrorCode.AUTH_REQUIRED, 'Calendar access requires authentication. Please run teams_login.', { suggestions: ['Call teams_login to authenticate'] }));
+    }
+    return ok({ skypeToken: auth.skypeToken, spacesToken });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Region Configuration
+// ─────────────────────────────────────────────────────────────────────────────
+import { DEFAULT_TEAMS_BASE_URL } from './api-config.js';
+/** Default region when session config is unavailable. */
+const DEFAULT_REGION = 'amer';
+/** Cached region config to avoid repeated localStorage parsing. */
+let cachedRegionConfig = null;
+/**
+ * Gets the user's region from session, with caching.
+ *
+ * The region is extracted from the DISCOVER-REGION-GTM config in localStorage.
+ * Falls back to 'amer' if not available (shouldn't happen with valid session).
+ */
+export function getRegion() {
+    if (!cachedRegionConfig) {
+        cachedRegionConfig = extractRegionConfig();
+    }
+    return cachedRegionConfig?.region ?? DEFAULT_REGION;
+}
+/**
+ * Gets the Teams base URL from session config.
+ *
+ * Returns the base URL for API calls (e.g., "https://teams.microsoft.com" for
+ * commercial cloud, or "https://teams.microsoft.us" for GCC).
+ * Falls back to default if config not available.
+ */
+export function getTeamsBaseUrl() {
+    if (!cachedRegionConfig) {
+        cachedRegionConfig = extractRegionConfig();
+    }
+    return cachedRegionConfig?.teamsBaseUrl ?? DEFAULT_TEAMS_BASE_URL;
+}
+/**
+ * Gets the full region config including partition and URLs.
+ *
+ * Returns null if no valid session - caller should handle auth error.
+ */
+export function getRegionConfig() {
+    if (!cachedRegionConfig) {
+        cachedRegionConfig = extractRegionConfig();
+    }
+    return cachedRegionConfig;
+}
+/**
+ * Clears the cached region config.
+ * Call this after login/logout to pick up new session.
+ */
+export function clearRegionCache() {
+    cachedRegionConfig = null;
+}

package/dist/utils/http.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP utilities with retry, timeout, and error handling.
+ */
+import { type Result } from '../types/result.js';
+/** Options for HTTP requests. */
+export interface HttpOptions extends Omit<RequestInit, 'signal'> {
+    /** Timeout in milliseconds (default: 30000). */
+    timeoutMs?: number;
+    /** Maximum retry attempts (default: 3). */
+    maxRetries?: number;
+    /** Base delay for exponential backoff in ms (default: 1000). */
+    retryBaseDelayMs?: number;
+    /** Maximum delay between retries in ms (default: 10000). */
+    retryMaxDelayMs?: number;
+}
+/** Successful HTTP response. */
+export interface HttpResponse<T = unknown> {
+    status: number;
+    headers: Headers;
+    data: T;
+}
+/**
+ * Makes an HTTP request with timeout, retry, and error handling.
+ */
+export declare function httpRequest<T = unknown>(url: string, options?: HttpOptions): Promise<Result<HttpResponse<T>>>;
+/**
+ * Clears the rate limit state (for testing).
+ */
+export declare function clearRateLimitState(): void;

package/dist/utils/http.js

@@ -0,0 +1,112 @@
+/**
+ * HTTP utilities with retry, timeout, and error handling.
+ */
+import { ErrorCode, createError, classifyHttpError, extractRetryAfter, } from '../types/errors.js';
+import { ok, err } from '../types/result.js';
+/** Rate limit state tracking. */
+let rateLimitedUntil = null;
+/**
+ * Makes an HTTP request with timeout, retry, and error handling.
+ */
+export async function httpRequest(url, options = {}) {
+    const { timeoutMs = 30000, maxRetries = 3, retryBaseDelayMs = 1000, retryMaxDelayMs = 10000, ...fetchOptions } = options;
+    // Check rate limit state
+    if (rateLimitedUntil && Date.now() < rateLimitedUntil) {
+        const waitMs = rateLimitedUntil - Date.now();
+        return err(createError(ErrorCode.RATE_LIMITED, `Rate limited. Retry after ${Math.ceil(waitMs / 1000)}s`, { retryable: true, retryAfterMs: waitMs }));
+    }
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            const result = await fetchWithTimeout(url, fetchOptions, timeoutMs);
+            if (result.ok) {
+                return result;
+            }
+            lastError = result.error;
+            // Handle rate limiting
+            if (result.error.code === ErrorCode.RATE_LIMITED && result.error.retryAfterMs) {
+                rateLimitedUntil = Date.now() + result.error.retryAfterMs;
+            }
+            // Don't retry non-retryable errors
+            if (!result.error.retryable) {
+                return result;
+            }
+            // Don't retry on last attempt
+            if (attempt === maxRetries) {
+                return result;
+            }
+            // Calculate backoff delay
+            const delay = Math.min(retryBaseDelayMs * Math.pow(2, attempt - 1), retryMaxDelayMs);
+            await sleep(delay);
+        }
+        catch (error) {
+            // Unexpected errors
+            lastError = createError(ErrorCode.UNKNOWN, error instanceof Error ? error.message : String(error), { retryable: false });
+            if (attempt === maxRetries) {
+                return err(lastError);
+            }
+        }
+    }
+    return err(lastError ?? createError(ErrorCode.UNKNOWN, 'Request failed'));
+}
+/**
+ * Makes a single fetch request with timeout.
+ */
+async function fetchWithTimeout(url, options, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            ...options,
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        // Handle error responses
+        if (!response.ok) {
+            const retryAfterMs = extractRetryAfter(response.headers);
+            const errorText = await response.text().catch(() => '');
+            return err(createError(classifyHttpError(response.status, errorText), `HTTP ${response.status}: ${errorText || response.statusText}`, { retryAfterMs }));
+        }
+        // Parse JSON response
+        const contentType = response.headers.get('content-type') || '';
+        let data;
+        if (contentType.includes('application/json')) {
+            const text = await response.text();
+            data = text ? JSON.parse(text) : {};
+        }
+        else {
+            data = await response.text();
+        }
+        return ok({
+            status: response.status,
+            headers: response.headers,
+            data,
+        });
+    }
+    catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof Error) {
+            if (error.name === 'AbortError') {
+                return err(createError(ErrorCode.TIMEOUT, `Request timed out after ${timeoutMs}ms`, { retryable: true }));
+            }
+            if (error.message.includes('ECONNRESET') ||
+                error.message.includes('ETIMEDOUT') ||
+                error.message.includes('ENOTFOUND')) {
+                return err(createError(ErrorCode.NETWORK_ERROR, error.message, { retryable: true }));
+            }
+        }
+        return err(createError(ErrorCode.UNKNOWN, error instanceof Error ? error.message : String(error), { retryable: false }));
+    }
+}
+/**
+ * Sleep for a specified duration.
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Clears the rate limit state (for testing).
+ */
+export function clearRateLimitState() {
+    rateLimitedUntil = null;
+}

package/dist/utils/parsers.d.ts

@@ -0,0 +1,247 @@
+/**
+ * Pure parsing functions for Teams API responses.
+ *
+ * These functions transform raw API responses into our internal types.
+ * They are extracted here for testability - no side effects or external dependencies.
+ */
+import type { TeamsSearchResult, ExtractedLink } from '../types/teams.js';
+export type { ExtractedLink };
+/** Person search result from Substrate suggestions API. */
+export interface PersonSearchResult {
+    id: string;
+    mri: string;
+    displayName: string;
+    email?: string;
+    givenName?: string;
+    surname?: string;
+    jobTitle?: string;
+    department?: string;
+    companyName?: string;
+}
+/** User profile extracted from JWT tokens. */
+export interface UserProfile {
+    id: string;
+    mri: string;
+    email: string;
+    displayName: string;
+    givenName?: string;
+    surname?: string;
+    tenantId?: string;
+}
+/**
+ * Extracts links from HTML content before stripping.
+ * Returns an array of { url, text } objects.
+ */
+export declare function extractLinks(html: string): ExtractedLink[];
+/**
+ * Strips HTML tags from content for display.
+ */
+export declare function stripHtml(html: string): string;
+/**
+ * Determines the conversation type from a Teams conversation ID.
+ *
+ * Conversation ID formats:
+ * - Channels: 19:xxx@thread.tacv2
+ * - Meetings: 19:meeting_xxx@thread.v2
+ * - 1:1 chats: 19:guid_guid@unq.gbl.spaces
+ * - Group chats: 19:xxx@thread.v2 (non-meeting)
+ */
+export declare function getConversationType(conversationId: string): 'channel' | 'meeting' | 'chat';
+/**
+ * Builds a deep link to open a message in Teams.
+ *
+ * Different conversation types require different URL formats:
+ * - Channels: /l/message/{channelId}/{msgId}?parentMessageId={parentId} (for thread replies)
+ * - Chats/Meetings: /l/message/{chatId}/{msgId}?context={"contextType":"chat"}
+ *
+ * @param conversationId - The conversation/thread ID (e.g., "19:xxx@thread.tacv2")
+ * @param messageTimestamp - The message timestamp in epoch milliseconds
+ * @param parentMessageId - For channel thread replies, the ID of the parent/root message
+ * @param teamsBaseUrl - Optional Teams base URL (for GCC/GCC-High support)
+ */
+export declare function buildMessageLink(conversationId: string, messageTimestamp: string | number, parentMessageId?: string, teamsBaseUrl?: string): string;
+/**
+ * Extracts a timestamp-based message ID from various sources.
+ * Teams uses epoch milliseconds as message IDs in URLs.
+ *
+ * IMPORTANT: For channel threaded replies, the ;messageid= in ClientConversationId
+ * is the PARENT thread's ID, not this message's ID. We must prefer the actual
+ * message timestamp (DateTimeReceived/DateTimeSent) for accurate deep links.
+ */
+export declare function extractMessageTimestamp(source: Record<string, unknown> | undefined, timestamp?: string): string | undefined;
+/**
+ * Parses a person suggestion from the Substrate API response.
+ *
+ * The API can return IDs in various formats:
+ * - GUID with tenant: "ab76f827-...@tenant.onmicrosoft.com"
+ * - Base64-encoded GUID: "93qkaTtFGWpUHjyRafgdhg=="
+ */
+export declare function parsePersonSuggestion(item: Record<string, unknown>): PersonSearchResult | null;
+/**
+ * Parses a v2 query result item into a search result.
+ */
+export declare function parseV2Result(item: Record<string, unknown>): TeamsSearchResult | null;
+/**
+ * Parses user profile from a JWT payload.
+ *
+ * @param payload - Decoded JWT payload object
+ * @returns User profile or null if required fields are missing
+ */
+export declare function parseJwtProfile(payload: Record<string, unknown>): UserProfile | null;
+/**
+ * Calculates token expiry status from an expiry timestamp.
+ *
+ * @param expiryMs - Token expiry time in milliseconds since epoch
+ * @param nowMs - Current time in milliseconds (for testing)
+ * @returns Token status including whether it's valid and time remaining
+ */
+export declare function calculateTokenStatus(expiryMs: number, nowMs?: number): {
+    isValid: boolean;
+    expiresAt: string;
+    minutesRemaining: number;
+};
+/**
+ * Parses the pagination result from a search API response.
+ *
+ * @param entitySets - Raw EntitySets array from API response
+ * @returns Parsed results and total count if available
+ */
+export declare function parseSearchResults(entitySets: unknown[] | undefined): {
+    results: TeamsSearchResult[];
+    total?: number;
+};
+/**
+ * Parses people search results from the Groups/Suggestions structure.
+ *
+ * @param groups - Raw Groups array from suggestions API response
+ * @returns Array of parsed person results
+ */
+export declare function parsePeopleResults(groups: unknown[] | undefined): PersonSearchResult[];
+/** Channel search result from Substrate suggestions API or Teams List API. */
+export interface ChannelSearchResult {
+    channelId: string;
+    channelName: string;
+    teamName: string;
+    teamId: string;
+    channelType: string;
+    description?: string;
+    isMember?: boolean;
+}
+/**
+ * Parses a single channel suggestion from the API response.
+ *
+ * @param suggestion - Raw suggestion object from API
+ * @returns Parsed channel result or null if required fields are missing
+ */
+export declare function parseChannelSuggestion(suggestion: Record<string, unknown>): ChannelSearchResult | null;
+/**
+ * Parses channel search results from the Groups/Suggestions structure.
+ *
+ * @param groups - Raw Groups array from suggestions API response
+ * @returns Array of parsed channel results
+ */
+export declare function parseChannelResults(groups: unknown[] | undefined): ChannelSearchResult[];
+/** Team with channels from the Teams List API response. */
+export interface TeamWithChannels {
+    teamId: string;
+    teamName: string;
+    threadId: string;
+    description?: string;
+    channels: ChannelSearchResult[];
+}
+/**
+ * Parses the Teams List API response to extract all teams and channels.
+ *
+ * @param data - Raw response data from /api/csa/{region}/api/v3/teams/users/me
+ * @returns Array of teams with their channels
+ */
+export declare function parseTeamsList(data: Record<string, unknown> | undefined): TeamWithChannels[];
+/**
+ * Filters channels from the Teams List by name.
+ *
+ * @param teams - Array of teams with channels from parseTeamsList
+ * @param query - Search query (case-insensitive partial match)
+ * @returns Matching channels flattened into a single array
+ */
+export declare function filterChannelsByName(teams: TeamWithChannels[], query: string): ChannelSearchResult[];
+/**
+ * Decodes a base64-encoded GUID to its standard string representation.
+ *
+ * Microsoft encodes GUIDs as 16 bytes with little-endian ordering for the
+ * first three groups (Data1, Data2, Data3).
+ *
+ * @param base64 - Base64-encoded GUID (typically 24 chars with == padding)
+ * @returns The GUID string in standard format, or null if invalid
+ */
+export declare function decodeBase64Guid(base64: string): string | null;
+/**
+ * Extracts the Azure AD object ID (GUID) from various formats.
+ *
+ * Handles:
+ * - MRI format: "8:orgid:ab76f827-27e2-4c67-a765-f1a53145fa24"
+ * - MRI with base64: "8:orgid:93qkaTtFGWpUHjyRafgdhg=="
+ * - Skype ID format: "orgid:ab76f827-27e2-4c67-a765-f1a53145fa24"
+ * - ID with tenant: "ab76f827-27e2-4c67-a765-f1a53145fa24@56b731a8-..."
+ * - Raw GUID: "ab76f827-27e2-4c67-a765-f1a53145fa24"
+ * - Base64-encoded GUID: "93qkaTtFGWpUHjyRafgdhg=="
+ *
+ * @param identifier - User identifier in any supported format
+ * @returns The extracted GUID or null if invalid format
+ */
+export declare function extractObjectId(identifier: string): string | null;
+/**
+ * Builds a 1:1 conversation ID from two user object IDs.
+ *
+ * The conversation ID format for 1:1 chats in Teams is:
+ * `19:{userId1}_{userId2}@unq.gbl.spaces`
+ *
+ * The user IDs are sorted lexicographically to ensure consistency -
+ * both participants will generate the same conversation ID.
+ *
+ * @param userId1 - First user's object ID (GUID, MRI, or ID with tenant)
+ * @param userId2 - Second user's object ID (GUID, MRI, or ID with tenant)
+ * @returns The constructed conversation ID, or null if either ID is invalid
+ */
+export declare function buildOneOnOneConversationId(userId1: string, userId2: string): string | null;
+/**
+ * Safely extracts a timestamp from an activity feed message.
+ *
+ * Tries multiple sources in order of preference:
+ * 1. originalarrivaltime - Primary timestamp field
+ * 2. composetime - When message was composed
+ * 3. id as numeric timestamp - Fallback if ID is a Unix timestamp
+ *
+ * Returns null if no valid timestamp can be determined, preventing
+ * RangeError from Date operations on invalid values.
+ *
+ * @param msg - Raw message object from activity feed API
+ * @returns ISO timestamp string, or null if no valid timestamp found
+ */
+export declare function extractActivityTimestamp(msg: Record<string, unknown>): string | null;
+/** Common fields from a virtual conversation message (48:saved, 48:threads, etc). */
+export interface VirtualConversationItem {
+    id: string;
+    content: string;
+    contentType: string;
+    sender: {
+        mri: string;
+        displayName?: string;
+    };
+    timestamp: string;
+    sourceConversationId: string;
+    sourceReferenceId?: string;
+    messageLink?: string;
+    links?: ExtractedLink[];
+}
+/**
+ * Parses a raw message from a virtual conversation (48:saved, 48:threads, etc).
+ *
+ * Virtual conversations contain references to messages in other conversations.
+ * The clumpId field contains the source conversation ID, and secondaryReferenceId
+ * contains a composite key with the source message/post ID.
+ *
+ * @param msg - Raw message object from virtual conversation API
+ * @param referencePattern - Regex to extract source ID from secondaryReferenceId
+ * @returns Parsed virtual conversation item, or null if message should be skipped
+ */
+export declare function parseVirtualConversationMessage(msg: Record<string, unknown>, referencePattern: RegExp): VirtualConversationItem | null;