msteams-mcp 0.2.0

package/dist/teams/direct-api.js

@@ -0,0 +1,1305 @@
+/**
+ * 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 * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { stripHtml, buildMessageLink, parseJwtProfile, parsePeopleResults, parseSearchResults, } from '../utils/parsers.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, '../..');
+const SESSION_STATE_PATH = path.join(PROJECT_ROOT, 'session-state.json');
+const TOKEN_CACHE_PATH = path.join(PROJECT_ROOT, 'token-cache.json');
+/**
+ * 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 function getMe() {
+    if (!fs.existsSync(SESSION_STATE_PATH)) {
+        return null;
+    }
+    try {
+        const state = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));
+        const teamsOrigin = state.origins?.find((o) => o.origin === 'https://teams.microsoft.com');
+        if (!teamsOrigin)
+            return null;
+        // Look through localStorage for any JWT with user info
+        for (const item of teamsOrigin.localStorage) {
+            try {
+                const val = JSON.parse(item.value);
+                if (!val.secret || typeof val.secret !== 'string')
+                    continue;
+                if (!val.secret.startsWith('ey'))
+                    continue;
+                const parts = val.secret.split('.');
+                if (parts.length !== 3)
+                    continue;
+                const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
+                // Use shared parsing function
+                const profile = parseJwtProfile(payload);
+                if (profile) {
+                    return profile;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * Extracts the Substrate search token from session state.
+ */
+export function extractSubstrateToken() {
+    if (!fs.existsSync(SESSION_STATE_PATH)) {
+        return null;
+    }
+    try {
+        const state = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));
+        const teamsOrigin = state.origins?.find((o) => o.origin === 'https://teams.microsoft.com');
+        if (!teamsOrigin)
+            return null;
+        for (const item of teamsOrigin.localStorage) {
+            try {
+                const val = JSON.parse(item.value);
+                if (val.target?.includes('substrate.office.com/search/SubstrateSearch')) {
+                    const token = val.secret;
+                    // Parse JWT to get expiry
+                    const parts = token.split('.');
+                    if (parts.length === 3) {
+                        const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
+                        const expiry = new Date(payload.exp * 1000);
+                        return { token, expiry };
+                    }
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * Gets a valid token, either from cache or by extracting from session.
+ */
+export function getValidToken() {
+    // Try cache first
+    if (fs.existsSync(TOKEN_CACHE_PATH)) {
+        try {
+            const cache = JSON.parse(fs.readFileSync(TOKEN_CACHE_PATH, 'utf8'));
+            if (cache.substrateTokenExpiry > Date.now()) {
+                return cache.substrateToken;
+            }
+        }
+        catch {
+            // Cache invalid, continue to extraction
+        }
+    }
+    // Extract from session state
+    const extracted = extractSubstrateToken();
+    if (!extracted)
+        return null;
+    // Check if not expired
+    if (extracted.expiry.getTime() <= Date.now()) {
+        return null;
+    }
+    // Cache the token
+    const cache = {
+        substrateToken: extracted.token,
+        substrateTokenExpiry: extracted.expiry.getTime(),
+        extractedAt: Date.now(),
+    };
+    fs.writeFileSync(TOKEN_CACHE_PATH, JSON.stringify(cache, null, 2));
+    return extracted.token;
+}
+/**
+ * Clears the token cache (forces re-extraction on next call).
+ */
+export function clearTokenCache() {
+    if (fs.existsSync(TOKEN_CACHE_PATH)) {
+        fs.unlinkSync(TOKEN_CACHE_PATH);
+    }
+}
+/**
+ * Checks if we have a valid token for direct API calls.
+ */
+export function hasValidToken() {
+    return getValidToken() !== null;
+}
+/**
+ * Gets token status for diagnostics.
+ */
+export function getTokenStatus() {
+    const extracted = extractSubstrateToken();
+    if (!extracted) {
+        return { hasToken: false };
+    }
+    const now = Date.now();
+    const expiryMs = extracted.expiry.getTime();
+    return {
+        hasToken: expiryMs > now,
+        expiresAt: extracted.expiry.toISOString(),
+        minutesRemaining: Math.max(0, Math.round((expiryMs - now) / 1000 / 60)),
+    };
+}
+/**
+ * Makes a direct search API call to Substrate.
+ */
+export async function directSearch(query, options = {}) {
+    const token = getValidToken();
+    if (!token) {
+        throw new Error('No valid token available. Browser login required.');
+    }
+    const from = options.from ?? 0;
+    const size = options.size ?? 25;
+    // Generate unique IDs for this request
+    const cvid = crypto.randomUUID();
+    const logicalId = crypto.randomUUID();
+    const body = {
+        entityRequests: [{
+                entityType: 'Message',
+                contentSources: ['Teams'],
+                propertySet: 'Optimized',
+                fields: [
+                    'Extension_SkypeSpaces_ConversationPost_Extension_FromSkypeInternalId_String',
+                    'Extension_SkypeSpaces_ConversationPost_Extension_ThreadType_String',
+                    'Extension_SkypeSpaces_ConversationPost_Extension_SkypeGroupId_String',
+                ],
+                query: {
+                    queryString: `${query} AND NOT (isClientSoftDeleted:TRUE)`,
+                    displayQueryString: query,
+                },
+                from,
+                size,
+                topResultsCount: 5,
+            }],
+        QueryAlterationOptions: {
+            EnableAlteration: true,
+            EnableSuggestion: true,
+            SupportedRecourseDisplayTypes: ['Suggestion'],
+        },
+        cvid,
+        logicalId,
+        scenario: {
+            Dimensions: [
+                { DimensionName: 'QueryType', DimensionValue: 'Messages' },
+                { DimensionName: 'FormFactor', DimensionValue: 'general.web.reactSearch' },
+            ],
+            Name: 'powerbar',
+        },
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    };
+    const response = await fetch('https://substrate.office.com/searchservice/api/v2/query', {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+            'Origin': 'https://teams.microsoft.com',
+            'Referer': 'https://teams.microsoft.com/',
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401) {
+        clearTokenCache();
+        throw new Error('Token expired or invalid. Browser login required.');
+    }
+    if (!response.ok) {
+        throw new Error(`API error: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    // Use shared parsing function
+    const { results, total } = parseSearchResults(data.EntitySets, from, size);
+    const maxResults = options.maxResults ?? size;
+    const limitedResults = results.slice(0, maxResults);
+    return {
+        results: limitedResults,
+        pagination: {
+            from,
+            size,
+            returned: limitedResults.length,
+            total,
+            hasMore: total !== undefined
+                ? from + results.length < total
+                : results.length >= size,
+        },
+    };
+}
+/**
+ * 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 function extractTeamsToken() {
+    if (!fs.existsSync(SESSION_STATE_PATH)) {
+        return null;
+    }
+    try {
+        const state = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));
+        const teamsOrigin = state.origins?.find((o) => o.origin === 'https://teams.microsoft.com');
+        if (!teamsOrigin)
+            return null;
+        let chatToken = null;
+        let chatTokenExpiry = null;
+        let skypeToken = null;
+        let skypeTokenExpiry = null;
+        let userMri = null;
+        for (const item of teamsOrigin.localStorage) {
+            try {
+                const val = JSON.parse(item.value);
+                if (!val.target || !val.secret)
+                    continue;
+                const secret = val.secret;
+                if (typeof secret !== 'string' || !secret.startsWith('ey'))
+                    continue;
+                const parts = secret.split('.');
+                if (parts.length !== 3)
+                    continue;
+                const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
+                const tokenExpiry = new Date(payload.exp * 1000);
+                // Extract user MRI from any token
+                if (payload.oid && !userMri) {
+                    userMri = `8:orgid:${payload.oid}`;
+                }
+                // Prefer chatsvcagg.teams.microsoft.com token
+                if (val.target.includes('chatsvcagg.teams.microsoft.com')) {
+                    if (!chatTokenExpiry || tokenExpiry > chatTokenExpiry) {
+                        chatToken = secret;
+                        chatTokenExpiry = tokenExpiry;
+                    }
+                }
+                // Fallback to api.spaces.skype.com token
+                if (val.target.includes('api.spaces.skype.com')) {
+                    if (!skypeTokenExpiry || tokenExpiry > skypeTokenExpiry) {
+                        skypeToken = secret;
+                        skypeTokenExpiry = tokenExpiry;
+                    }
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        // If we still don't have userMri, try to get it from the Substrate token
+        if (!userMri) {
+            const substrateInfo = extractSubstrateToken();
+            if (substrateInfo) {
+                try {
+                    const parts = substrateInfo.token.split('.');
+                    if (parts.length === 3) {
+                        const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
+                        if (payload.oid) {
+                            userMri = `8:orgid:${payload.oid}`;
+                        }
+                    }
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        // Prefer chatsvc token, fallback to skype token
+        const token = chatToken || skypeToken;
+        const expiry = chatToken ? chatTokenExpiry : skypeTokenExpiry;
+        if (token && expiry && userMri && expiry.getTime() > Date.now()) {
+            return { token, expiry, userMri };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * Extracts authentication info needed for sending messages.
+ * Uses cookies (skypetoken_asm) which are required for the chatsvc API.
+ */
+export function extractMessageAuth() {
+    if (!fs.existsSync(SESSION_STATE_PATH)) {
+        return null;
+    }
+    try {
+        const state = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));
+        let skypeToken = null;
+        let authToken = null;
+        let userMri = null;
+        // Extract tokens from cookies
+        for (const cookie of state.cookies || []) {
+            if (cookie.name === 'skypetoken_asm' && cookie.domain?.includes('teams.microsoft.com')) {
+                skypeToken = cookie.value;
+            }
+            if (cookie.name === 'authtoken' && cookie.domain?.includes('teams.microsoft.com')) {
+                // Decode the URL-encoded cookie value
+                authToken = decodeURIComponent(cookie.value);
+                if (authToken.startsWith('Bearer=')) {
+                    authToken = authToken.substring(7); // Remove "Bearer=" prefix
+                }
+            }
+        }
+        // Get userMri from token payload or localStorage
+        if (skypeToken) {
+            try {
+                const parts = skypeToken.split('.');
+                if (parts.length >= 2) {
+                    const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
+                    if (payload.skypeid) {
+                        userMri = payload.skypeid;
+                    }
+                }
+            }
+            catch {
+                // Not a JWT format, that's fine
+            }
+        }
+        // Fallback to extracting userMri from authToken
+        if (!userMri && authToken) {
+            try {
+                const parts = authToken.split('.');
+                if (parts.length === 3) {
+                    const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
+                    if (payload.oid) {
+                        userMri = `8:orgid:${payload.oid}`;
+                    }
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (skypeToken && authToken && userMri) {
+            return { skypeToken, authToken, userMri };
+        }
+    }
+    catch {
+        return null;
+    }
+    return 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 function extractCsaToken() {
+    if (!fs.existsSync(SESSION_STATE_PATH)) {
+        return null;
+    }
+    try {
+        const state = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));
+        // Look for the MSAL token with chatsvcagg.teams.microsoft.com audience
+        for (const origin of state.origins || []) {
+            for (const item of (origin.localStorage || [])) {
+                if (item.name.includes('chatsvcagg.teams.microsoft.com') && !item.name.startsWith('tmp.')) {
+                    try {
+                        const data = JSON.parse(item.value);
+                        if (data.secret) {
+                            return data.secret;
+                        }
+                    }
+                    catch {
+                        // Ignore parse errors
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * Gets user's display name from session state.
+ */
+export function getUserDisplayName() {
+    if (!fs.existsSync(SESSION_STATE_PATH)) {
+        return null;
+    }
+    try {
+        const state = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));
+        const teamsOrigin = state.origins?.find((o) => o.origin === 'https://teams.microsoft.com');
+        if (!teamsOrigin)
+            return null;
+        for (const item of teamsOrigin.localStorage) {
+            try {
+                // Look for user profile data
+                if (item.value?.includes('displayName') || item.value?.includes('givenName')) {
+                    const val = JSON.parse(item.value);
+                    if (val.displayName)
+                        return val.displayName;
+                    if (val.name?.displayName)
+                        return val.name.displayName;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        // Try to get from token
+        const teamsToken = extractTeamsToken();
+        if (teamsToken) {
+            try {
+                const parts = teamsToken.token.split('.');
+                if (parts.length === 3) {
+                    const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
+                    if (payload.name)
+                        return payload.name;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * 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 async function sendMessage(conversationId, content, region = 'amer') {
+    const auth = extractMessageAuth();
+    if (!auth) {
+        return { success: false, error: 'No valid authentication. Browser login required.' };
+    }
+    const displayName = getUserDisplayName() || 'User';
+    // Generate unique message ID
+    const clientMessageId = Date.now().toString();
+    const now = new Date().toISOString();
+    // Wrap content in paragraph if not already HTML
+    const htmlContent = content.startsWith('<') ? content : `<p>${content}</p>`;
+    const body = {
+        content: htmlContent,
+        messagetype: 'RichText/Html',
+        contenttype: 'text',
+        imdisplayname: displayName,
+        clientmessageid: clientMessageId,
+    };
+    // Use the Teams messaging API with skypetoken authentication
+    const url = `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}/messages`;
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Authentication': `skypetoken=${auth.skypeToken}`,
+                'Authorization': `Bearer ${auth.authToken}`,
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+                'Origin': 'https://teams.microsoft.com',
+                'Referer': 'https://teams.microsoft.com/',
+                'X-Ms-Client-Version': '1415/1.0.0.2025010401',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            return {
+                success: false,
+                error: `API error: ${response.status} - ${errorText}`
+            };
+        }
+        const data = await response.json();
+        return {
+            success: true,
+            messageId: clientMessageId,
+            timestamp: data.OriginalArrivalTime,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : 'Unknown error',
+        };
+    }
+}
+/**
+ * Sends a message to your own notes/self-chat.
+ */
+export async function sendNoteToSelf(content) {
+    return sendMessage('48:notes', content);
+}
+/**
+ * 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 async function searchPeople(query, limit = 10) {
+    const token = getValidToken();
+    if (!token) {
+        throw new Error('No valid token available. Browser login required.');
+    }
+    // Generate unique IDs for this request (required by the API)
+    const cvid = crypto.randomUUID();
+    const logicalId = crypto.randomUUID();
+    const body = {
+        EntityRequests: [{
+                Query: {
+                    QueryString: query,
+                    DisplayQueryString: query,
+                },
+                EntityType: 'People',
+                Size: limit,
+                Fields: [
+                    'Id',
+                    'MRI',
+                    'DisplayName',
+                    'EmailAddresses',
+                    'GivenName',
+                    'Surname',
+                    'JobTitle',
+                    'Department',
+                    'CompanyName',
+                ],
+            }],
+        cvid,
+        logicalId,
+    };
+    const response = await fetch('https://substrate.office.com/search/api/v1/suggestions?scenario=powerbar', {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+            'Origin': 'https://teams.microsoft.com',
+            'Referer': 'https://teams.microsoft.com/',
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401) {
+        clearTokenCache();
+        throw new Error('Token expired or invalid. Browser login required.');
+    }
+    if (!response.ok) {
+        throw new Error(`API error: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    // Use shared parsing function
+    const results = parsePeopleResults(data.Groups);
+    return {
+        results,
+        returned: results.length,
+    };
+}
+/**
+ * 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 async function getFrequentContacts(limit = 50) {
+    const token = getValidToken();
+    if (!token) {
+        throw new Error('No valid token available. Browser login required.');
+    }
+    // Generate unique IDs for this request (required by the API)
+    const cvid = crypto.randomUUID();
+    const logicalId = crypto.randomUUID();
+    const body = {
+        EntityRequests: [{
+                Query: {
+                    QueryString: '',
+                    DisplayQueryString: '',
+                },
+                EntityType: 'People',
+                Size: limit,
+                Fields: [
+                    'Id',
+                    'MRI',
+                    'DisplayName',
+                    'EmailAddresses',
+                    'GivenName',
+                    'Surname',
+                    'JobTitle',
+                    'Department',
+                    'CompanyName',
+                ],
+            }],
+        cvid,
+        logicalId,
+    };
+    const response = await fetch('https://substrate.office.com/search/api/v1/suggestions?scenario=peoplecache', {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+            'Origin': 'https://teams.microsoft.com',
+            'Referer': 'https://teams.microsoft.com/',
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401) {
+        clearTokenCache();
+        throw new Error('Token expired or invalid. Browser login required.');
+    }
+    if (!response.ok) {
+        throw new Error(`API error: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    // Use shared parsing function
+    const contacts = parsePeopleResults(data.Groups);
+    return {
+        contacts,
+        returned: contacts.length,
+    };
+}
+/**
+ * Extracts unique participant names from recent messages in a conversation.
+ * Used as a fallback when conversation properties don't include member names.
+ */
+async function extractParticipantNamesFromMessages(conversationId, auth, region = 'amer') {
+    const url = `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}/messages?view=msnp24Equivalent&pageSize=10`;
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'Authentication': `skypetoken=${auth.skypeToken}`,
+                'Authorization': `Bearer ${auth.authToken}`,
+                'Accept': 'application/json',
+                'Origin': 'https://teams.microsoft.com',
+                'Referer': 'https://teams.microsoft.com/',
+            },
+        });
+        if (!response.ok) {
+            return undefined;
+        }
+        const data = await response.json();
+        const messages = data.messages;
+        if (!messages || messages.length === 0) {
+            return undefined;
+        }
+        // Extract unique sender names (excluding the current user)
+        const senderNames = new Set();
+        for (const msg of messages) {
+            const fromMri = msg.from || '';
+            const displayName = msg.imdisplayname;
+            // Skip messages from self and system messages
+            if (fromMri === auth.userMri || !displayName) {
+                continue;
+            }
+            senderNames.add(displayName);
+        }
+        if (senderNames.size === 0) {
+            return undefined;
+        }
+        const names = Array.from(senderNames);
+        return names.length <= 3
+            ? names.join(', ')
+            : `${names.slice(0, 3).join(', ')} + ${names.length - 3} more`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Gets properties for a single conversation (name, type, etc.).
+ *
+ * Uses the chatsvc conversation endpoint to fetch metadata.
+ *
+ * @param conversationId - The conversation ID
+ * @param auth - Pre-extracted auth info (to avoid repeated extraction)
+ * @param region - Region for the API (default: "amer")
+ */
+async function getConversationProperties(conversationId, auth, region = 'amer') {
+    const url = `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}?view=msnp24Equivalent`;
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'Authentication': `skypetoken=${auth.skypeToken}`,
+                'Authorization': `Bearer ${auth.authToken}`,
+                'Accept': 'application/json',
+                'Origin': 'https://teams.microsoft.com',
+                'Referer': 'https://teams.microsoft.com/',
+            },
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        // Extract the thread properties which contain the conversation details
+        const threadProps = data.threadProperties;
+        const productType = threadProps?.productThreadType;
+        // Try to get display name from various sources
+        let displayName;
+        // For Teams channels: topicThreadTopic is the channel name, topic is fallback
+        if (threadProps?.topicThreadTopic) {
+            displayName = threadProps.topicThreadTopic;
+        }
+        // For standard channels: topic is the channel name
+        if (!displayName && threadProps?.topic) {
+            displayName = threadProps.topic;
+        }
+        // For Teams (the team itself, not a channel): spaceThreadTopic is the team name
+        if (!displayName && threadProps?.spaceThreadTopic) {
+            displayName = threadProps.spaceThreadTopic;
+        }
+        // For group chats: threadtopic may be set
+        if (!displayName && threadProps?.threadtopic) {
+            displayName = threadProps.threadtopic;
+        }
+        // For 1:1 chats and group chats without a topic: build from members
+        if (!displayName) {
+            const members = data.members;
+            if (members && members.length > 0) {
+                // Filter out the current user and build a name from the other participants
+                // Check multiple possible field names for the display name
+                const otherMembers = members
+                    .filter(m => m.mri !== auth.userMri && m.id !== auth.userMri)
+                    .map(m => (m.friendlyName || m.displayName || m.name))
+                    .filter((name) => !!name);
+                if (otherMembers.length > 0) {
+                    displayName = otherMembers.length <= 3
+                        ? otherMembers.join(', ')
+                        : `${otherMembers.slice(0, 3).join(', ')} + ${otherMembers.length - 3} more`;
+                }
+            }
+        }
+        // Determine conversation type from productThreadType or ID patterns
+        let conversationType;
+        // Use productThreadType if available (most accurate)
+        if (productType) {
+            if (productType === 'Meeting') {
+                conversationType = 'Meeting';
+            }
+            else if (productType.includes('Channel') || productType === 'TeamsTeam') {
+                conversationType = 'Channel';
+            }
+            else if (productType === 'Chat' || productType === 'OneOnOne') {
+                conversationType = 'Chat';
+            }
+        }
+        // Fallback to ID pattern detection
+        if (!conversationType) {
+            if (conversationId.includes('meeting_')) {
+                conversationType = 'Meeting';
+            }
+            else if (threadProps?.groupId) {
+                // Has a groupId means it's part of a Team
+                conversationType = 'Channel';
+            }
+            else if (conversationId.includes('@thread.tacv2') || conversationId.includes('@thread.v2')) {
+                conversationType = 'Chat';
+            }
+            else if (conversationId.startsWith('8:')) {
+                conversationType = 'Chat';
+            }
+        }
+        return { displayName, conversationType };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 async function getFavorites(region = 'amer') {
+    const auth = extractMessageAuth();
+    const csaToken = extractCsaToken();
+    if (!auth?.skypeToken || !csaToken) {
+        return { success: false, favorites: [], error: 'No valid authentication. Browser login required.' };
+    }
+    const url = `https://teams.microsoft.com/api/csa/${region}/api/v1/teams/users/me/conversationFolders?supportsAdditionalSystemGeneratedFolders=true&supportsSliceItems=true`;
+    try {
+        // Use GET request to retrieve folders (POST is only for modifications)
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'Authentication': `skypetoken=${auth.skypeToken}`,
+                'Authorization': `Bearer ${csaToken}`,
+                'Accept': 'application/json',
+                'Origin': 'https://teams.microsoft.com',
+                'Referer': 'https://teams.microsoft.com/',
+            },
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            return {
+                success: false,
+                favorites: [],
+                error: `API error: ${response.status} - ${errorText}`
+            };
+        }
+        const data = await response.json();
+        // Find the Favorites folder
+        const folders = data.conversationFolders;
+        const favoritesFolder = folders?.find((f) => {
+            const folder = f;
+            return folder.folderType === 'Favorites';
+        });
+        if (!favoritesFolder) {
+            return {
+                success: true,
+                favorites: [],
+                folderHierarchyVersion: data.folderHierarchyVersion,
+            };
+        }
+        const items = favoritesFolder.conversationFolderItems;
+        const favorites = (items || []).map((item) => {
+            const i = item;
+            return {
+                conversationId: i.conversationId,
+                createdTime: i.createdTime,
+                lastUpdatedTime: i.lastUpdatedTime,
+            };
+        });
+        // Enrich favorites with display names by fetching conversation properties in parallel
+        // We need the message auth for the chatsvc API (different from CSA auth)
+        if (auth) {
+            const enrichmentPromises = favorites.map(async (fav) => {
+                const props = await getConversationProperties(fav.conversationId, auth, region);
+                if (props) {
+                    fav.displayName = props.displayName;
+                    fav.conversationType = props.conversationType;
+                }
+                // Fallback: if no display name found, try extracting from recent messages
+                if (!fav.displayName) {
+                    const nameFromMessages = await extractParticipantNamesFromMessages(fav.conversationId, auth, region);
+                    if (nameFromMessages) {
+                        fav.displayName = nameFromMessages;
+                    }
+                }
+            });
+            // Wait for all enrichment calls to complete (with a reasonable timeout)
+            await Promise.allSettled(enrichmentPromises);
+        }
+        return {
+            success: true,
+            favorites,
+            folderHierarchyVersion: data.folderHierarchyVersion,
+            folderId: favoritesFolder.id,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            favorites: [],
+            error: err instanceof Error ? err.message : 'Unknown error',
+        };
+    }
+}
+/**
+ * Internal helper to modify the favourites folder (add or remove items).
+ */
+async function modifyFavorite(conversationId, action, region) {
+    const auth = extractMessageAuth();
+    const csaToken = extractCsaToken();
+    if (!auth?.skypeToken || !csaToken) {
+        return { success: false, error: 'No valid authentication. Browser login required.' };
+    }
+    // Get the current folder state to get the folderId and version
+    const currentState = await getFavorites(region);
+    if (!currentState.success) {
+        return { success: false, error: currentState.error };
+    }
+    if (!currentState.folderId) {
+        return { success: false, error: 'Could not find Favorites folder' };
+    }
+    const url = `https://teams.microsoft.com/api/csa/${region}/api/v1/teams/users/me/conversationFolders?supportsAdditionalSystemGeneratedFolders=true&supportsSliceItems=true`;
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Authentication': `skypetoken=${auth.skypeToken}`,
+                'Authorization': `Bearer ${csaToken}`,
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+                'Origin': 'https://teams.microsoft.com',
+                'Referer': 'https://teams.microsoft.com/',
+            },
+            body: JSON.stringify({
+                folderHierarchyVersion: currentState.folderHierarchyVersion,
+                actions: [
+                    {
+                        action,
+                        folderId: currentState.folderId,
+                        itemId: conversationId,
+                    },
+                ],
+            }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            return {
+                success: false,
+                error: `API error: ${response.status} - ${errorText}`
+            };
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : 'Unknown error',
+        };
+    }
+}
+/**
+ * Adds a conversation to the user's favourites.
+ *
+ * @param conversationId - The conversation ID to add
+ * @param region - Region for the API (default: "amer")
+ */
+export async function addFavorite(conversationId, region = 'amer') {
+    return modifyFavorite(conversationId, 'AddItem', region);
+}
+/**
+ * Removes a conversation from the user's favourites.
+ *
+ * @param conversationId - The conversation ID to remove
+ * @param region - Region for the API (default: "amer")
+ */
+export async function removeFavorite(conversationId, region = 'amer') {
+    return modifyFavorite(conversationId, 'RemoveItem', region);
+}
+/**
+ * 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 async function saveMessage(conversationId, messageId, region = 'amer') {
+    return setMessageSavedState(conversationId, messageId, true, region);
+}
+/**
+ * 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 async function unsaveMessage(conversationId, messageId, region = 'amer') {
+    return setMessageSavedState(conversationId, messageId, false, region);
+}
+/**
+ * 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 async function getThreadMessages(conversationId, options = {}, region = 'amer') {
+    const auth = extractMessageAuth();
+    if (!auth) {
+        return { success: false, error: 'No valid authentication. Browser login required.' };
+    }
+    const limit = options.limit ?? 50;
+    // Build URL with query parameters
+    let url = `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}/messages?view=msnp24Equivalent&pageSize=${limit}`;
+    if (options.startTime) {
+        url += `&startTime=${options.startTime}`;
+    }
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'Authentication': `skypetoken=${auth.skypeToken}`,
+                'Authorization': `Bearer ${auth.authToken}`,
+                'Accept': 'application/json',
+                'Origin': 'https://teams.microsoft.com',
+                'Referer': 'https://teams.microsoft.com/',
+            },
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            return {
+                success: false,
+                error: `API error: ${response.status} - ${errorText}`
+            };
+        }
+        const data = await response.json();
+        // Parse messages from the response
+        // The API returns { messages: [...] } array
+        const rawMessages = data.messages;
+        if (!Array.isArray(rawMessages)) {
+            return {
+                success: true,
+                conversationId,
+                messages: [],
+            };
+        }
+        const messages = [];
+        for (const raw of rawMessages) {
+            const msg = raw;
+            // Skip non-message types (e.g., typing indicators, control messages)
+            const messageType = msg.messagetype;
+            if (!messageType || messageType.startsWith('Control/') || messageType === 'ThreadActivity/AddMember') {
+                continue;
+            }
+            const id = msg.id || msg.originalarrivaltime;
+            if (!id)
+                continue;
+            const content = msg.content || '';
+            const contentType = msg.messagetype || 'Text';
+            // Parse sender info
+            const fromMri = msg.from || '';
+            const displayName = msg.imdisplayname || msg.displayName;
+            const timestamp = msg.originalarrivaltime ||
+                msg.composetime ||
+                new Date(parseInt(id, 10)).toISOString();
+            // Build message link - id is already the timestamp in milliseconds
+            const messageLink = /^\d+$/.test(id)
+                ? buildMessageLink(conversationId, id)
+                : undefined;
+            messages.push({
+                id,
+                content: stripHtml(content),
+                contentType,
+                sender: {
+                    mri: fromMri,
+                    displayName,
+                },
+                timestamp,
+                conversationId,
+                clientMessageId: msg.clientmessageid,
+                isFromMe: fromMri === auth.userMri,
+                messageLink,
+            });
+        }
+        // Sort by timestamp (oldest first)
+        messages.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+        return {
+            success: true,
+            conversationId,
+            messages,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : 'Unknown error',
+        };
+    }
+}
+// stripHtml is imported from ../utils/parsers.js
+/**
+ * Internal function to set the saved state of a message.
+ */
+async function setMessageSavedState(conversationId, messageId, saved, region) {
+    const auth = extractMessageAuth();
+    if (!auth) {
+        return { success: false, error: 'No valid authentication. Browser login required.' };
+    }
+    const url = `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}/rcmetadata/${messageId}`;
+    try {
+        const response = await fetch(url, {
+            method: 'PUT',
+            headers: {
+                'Authentication': `skypetoken=${auth.skypeToken}`,
+                'Authorization': `Bearer ${auth.authToken}`,
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+                'Origin': 'https://teams.microsoft.com',
+                'Referer': 'https://teams.microsoft.com/',
+            },
+            body: JSON.stringify({
+                s: saved ? 1 : 0,
+                mid: parseInt(messageId, 10),
+            }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            return {
+                success: false,
+                error: `API error: ${response.status} - ${errorText}`
+            };
+        }
+        return {
+            success: true,
+            conversationId,
+            messageId,
+            saved,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : 'Unknown error',
+        };
+    }
+}
+// parsePersonSuggestion is imported from ../utils/parsers.js
+// Re-export buildMessageLink for backward compatibility
+export { buildMessageLink };
+/**
+ * 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 async function getJoinedTeams(region = 'amer') {
+    const auth = extractMessageAuth();
+    const csaToken = extractCsaToken();
+    if (!auth?.skypeToken || !csaToken) {
+        return { success: false, error: 'No valid authentication. Browser login required.' };
+    }
+    const url = `https://teams.microsoft.com/api/csa/${region}/api/v3/teams/users/me?isPrefetch=false&enableMembershipSummary=true&supportsAdditionalSystemGeneratedFolders=true&supportsSliceItems=true&enableEngageCommunities=false`;
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'Authentication': `skypetoken=${auth.skypeToken}`,
+                'Authorization': `Bearer ${csaToken}`,
+                'Accept': 'application/json',
+                'Origin': 'https://teams.microsoft.com',
+                'Referer': 'https://teams.microsoft.com/',
+            },
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            return {
+                success: false,
+                error: `API error: ${response.status} - ${errorText}`
+            };
+        }
+        const data = await response.json();
+        // Parse the teams array from the response
+        const rawTeams = data.teams;
+        if (!Array.isArray(rawTeams)) {
+            return {
+                success: true,
+                teams: [],
+            };
+        }
+        const teams = rawTeams.map((t) => {
+            const team = t;
+            const rawChannels = team.channels;
+            const channels = (rawChannels || []).map((c) => {
+                const channel = c;
+                return {
+                    id: channel.id,
+                    displayName: channel.displayName || 'Unknown Channel',
+                    description: channel.description,
+                    isFavorite: channel.isFavorite,
+                    membershipType: channel.membershipType,
+                };
+            });
+            return {
+                id: team.threadId || team.id,
+                displayName: team.displayName || 'Unknown Team',
+                description: team.description,
+                pictureETag: team.pictureETag,
+                isFavorite: team.isFavorite,
+                channels,
+            };
+        });
+        return {
+            success: true,
+            teams,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : 'Unknown error',
+        };
+    }
+}
+/**
+ * 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 async function getTeamChannels(teamId, region = 'amer') {
+    const result = await getJoinedTeams(region);
+    if (!result.success) {
+        return { success: false, error: result.error };
+    }
+    const team = result.teams?.find(t => t.id === teamId);
+    if (!team) {
+        return { success: false, error: `Team not found: ${teamId}` };
+    }
+    return {
+        success: true,
+        channels: team.channels,
+    };
+}
+/**
+ * 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 async function findChannel(query, options = {}, region = 'amer') {
+    const result = await getJoinedTeams(region);
+    if (!result.success) {
+        return { success: false, error: result.error };
+    }
+    const queryLower = query.toLowerCase();
+    const teamNameLower = options.teamName?.toLowerCase();
+    const matches = [];
+    for (const team of result.teams || []) {
+        // Skip if team name filter is specified and doesn't match
+        if (teamNameLower && !team.displayName.toLowerCase().includes(teamNameLower)) {
+            continue;
+        }
+        for (const channel of team.channels) {
+            if (channel.displayName.toLowerCase().includes(queryLower)) {
+                matches.push({
+                    channel,
+                    team: {
+                        id: team.id,
+                        displayName: team.displayName,
+                    },
+                });
+            }
+        }
+    }
+    return {
+        success: true,
+        channels: matches,
+    };
+}