msteams-mcp 0.2.1

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

@@ -0,0 +1,64 @@
+/**
+ * CSA (Chat Service Aggregator) API client for favorites and teams operations.
+ *
+ * Handles all calls to teams.microsoft.com/api/csa endpoints.
+ * Base URL is extracted from session config to support different Teams environments.
+ */
+import { type Result } from '../types/result.js';
+import { type TeamWithChannels } from '../utils/parsers.js';
+/** 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 {
+    favorites: FavoriteItem[];
+    folderHierarchyVersion?: number;
+    folderId?: string;
+}
+/**
+ * Gets the user's favourite/pinned conversations.
+ */
+export declare function getFavorites(): Promise<Result<FavoritesResult>>;
+/**
+ * Adds a conversation to the user's favourites.
+ */
+export declare function addFavorite(conversationId: string): Promise<Result<void>>;
+/**
+ * Removes a conversation from the user's favourites.
+ */
+export declare function removeFavorite(conversationId: string): Promise<Result<void>>;
+/** Response from getting the user's teams and channels. */
+export interface TeamsListResult {
+    teams: TeamWithChannels[];
+}
+/**
+ * Gets all teams and channels the user is a member of.
+ *
+ * This returns the complete list of teams with their channels - not a search,
+ * but a full enumeration of the user's memberships.
+ */
+export declare function getMyTeamsAndChannels(): Promise<Result<TeamsListResult>>;
+/** A custom emoji from the organisation. */
+export interface CustomEmoji {
+    /** The emoji ID (use as reaction key). */
+    id: string;
+    /** Short name/shortcut for the emoji. */
+    shortcut: string;
+    /** Description of the emoji. */
+    description: string;
+    /** When the emoji was created. */
+    createdOn?: number;
+}
+/** Response from getting custom emojis. */
+export interface CustomEmojisResult {
+    emojis: CustomEmoji[];
+}
+/**
+ * Gets the organisation's custom emojis.
+ */
+export declare function getCustomEmojis(): Promise<Result<CustomEmojisResult>>;

package/dist/api/csa-api.js

@@ -0,0 +1,200 @@
+/**
+ * CSA (Chat Service Aggregator) API client for favorites and teams operations.
+ *
+ * Handles all calls to teams.microsoft.com/api/csa endpoints.
+ * Base URL is extracted from session config to support different Teams environments.
+ */
+import { httpRequest } from '../utils/http.js';
+import { CSA_API, getCsaHeaders } from '../utils/api-config.js';
+import { ErrorCode, createError } from '../types/errors.js';
+import { ok, err } from '../types/result.js';
+import { requireCsaAuth, getRegion, getTeamsBaseUrl } from '../utils/auth-guards.js';
+import { getConversationProperties, extractParticipantNames, } from './chatsvc-api.js';
+import { parseTeamsList, } from '../utils/parsers.js';
+/** Gets region and base URL together for API calls. */
+function getApiConfig() {
+    return {
+        region: getRegion(),
+        baseUrl: getTeamsBaseUrl(),
+    };
+}
+/**
+ * Gets the user's favourite/pinned conversations.
+ */
+export async function getFavorites() {
+    const authResult = requireCsaAuth();
+    if (!authResult.ok) {
+        return authResult;
+    }
+    const { auth, csaToken } = authResult.value;
+    const { region, baseUrl } = getApiConfig();
+    const url = CSA_API.conversationFolders(region, baseUrl);
+    const response = await httpRequest(url, {
+        method: 'GET',
+        headers: getCsaHeaders(auth.skypeToken, csaToken, baseUrl),
+    });
+    if (!response.ok) {
+        return response;
+    }
+    const data = response.value.data;
+    // Find the Favorites folder
+    const folders = data.conversationFolders;
+    const favoritesFolder = folders?.find((f) => {
+        const folder = f;
+        return folder.folderType === 'Favorites';
+    });
+    if (!favoritesFolder) {
+        return ok({
+            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 in parallel
+    const enrichmentPromises = favorites.map(async (fav) => {
+        const props = await getConversationProperties(fav.conversationId);
+        if (props.ok) {
+            fav.displayName = props.value.displayName;
+            fav.conversationType = props.value.conversationType;
+        }
+        // Fallback: extract from recent messages if no display name
+        if (!fav.displayName) {
+            const names = await extractParticipantNames(fav.conversationId);
+            if (names.ok && names.value) {
+                fav.displayName = names.value;
+            }
+        }
+    });
+    await Promise.allSettled(enrichmentPromises);
+    return ok({
+        favorites,
+        folderHierarchyVersion: data.folderHierarchyVersion,
+        folderId: favoritesFolder.id,
+    });
+}
+/**
+ * Adds a conversation to the user's favourites.
+ */
+export async function addFavorite(conversationId) {
+    return modifyFavorite(conversationId, 'AddItem');
+}
+/**
+ * Removes a conversation from the user's favourites.
+ */
+export async function removeFavorite(conversationId) {
+    return modifyFavorite(conversationId, 'RemoveItem');
+}
+/**
+ * Internal helper to modify the favourites folder.
+ */
+async function modifyFavorite(conversationId, action) {
+    const authResult = requireCsaAuth();
+    if (!authResult.ok) {
+        return authResult;
+    }
+    const { auth, csaToken } = authResult.value;
+    const { region, baseUrl } = getApiConfig();
+    // Get current folder state
+    const currentState = await getFavorites();
+    if (!currentState.ok) {
+        return err(currentState.error);
+    }
+    if (!currentState.value.folderId) {
+        return err(createError(ErrorCode.NOT_FOUND, 'Could not find Favorites folder'));
+    }
+    const url = CSA_API.conversationFolders(region, baseUrl);
+    const response = await httpRequest(url, {
+        method: 'POST',
+        headers: getCsaHeaders(auth.skypeToken, csaToken, baseUrl),
+        body: JSON.stringify({
+            folderHierarchyVersion: currentState.value.folderHierarchyVersion,
+            actions: [
+                {
+                    action,
+                    folderId: currentState.value.folderId,
+                    itemId: conversationId,
+                },
+            ],
+        }),
+    });
+    if (!response.ok) {
+        return response;
+    }
+    return ok(undefined);
+}
+/**
+ * Gets all teams and channels the user is a member of.
+ *
+ * This returns the complete list of teams with their channels - not a search,
+ * but a full enumeration of the user's memberships.
+ */
+export async function getMyTeamsAndChannels() {
+    const authResult = requireCsaAuth();
+    if (!authResult.ok) {
+        return authResult;
+    }
+    const { auth, csaToken } = authResult.value;
+    const { region, baseUrl } = getApiConfig();
+    const url = CSA_API.teamsList(region, baseUrl);
+    const response = await httpRequest(url, {
+        method: 'GET',
+        headers: getCsaHeaders(auth.skypeToken, csaToken, baseUrl),
+    });
+    if (!response.ok) {
+        return response;
+    }
+    const teams = parseTeamsList(response.value.data);
+    return ok({ teams });
+}
+/**
+ * Gets the organisation's custom emojis.
+ */
+export async function getCustomEmojis() {
+    const authResult = requireCsaAuth();
+    if (!authResult.ok) {
+        return authResult;
+    }
+    const { auth, csaToken } = authResult.value;
+    const { region, baseUrl } = getApiConfig();
+    const url = CSA_API.customEmojis(region, baseUrl);
+    const response = await httpRequest(url, {
+        method: 'GET',
+        headers: getCsaHeaders(auth.skypeToken, csaToken, baseUrl),
+    });
+    if (!response.ok) {
+        return response;
+    }
+    const data = response.value.data;
+    const categories = data.categories;
+    const emojis = [];
+    if (categories) {
+        for (const category of categories) {
+            const emoticons = category.emoticons;
+            if (emoticons) {
+                for (const emoticon of emoticons) {
+                    if (emoticon.isDeleted)
+                        continue;
+                    const id = emoticon.id;
+                    const shortcuts = emoticon.shortcuts;
+                    const description = emoticon.description;
+                    const createdOn = emoticon.createdOn;
+                    emojis.push({
+                        id,
+                        shortcut: shortcuts?.[0] || id.split(';')[0],
+                        description: description || shortcuts?.[0] || id.split(';')[0],
+                        createdOn,
+                    });
+                }
+            }
+        }
+    }
+    return ok({ emojis });
+}

package/dist/api/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * API module exports.
+ */
+export * from './substrate-api.js';
+export * from './chatsvc-api.js';
+export * from './csa-api.js';
+export * from './calendar-api.js';

package/dist/api/index.js

@@ -0,0 +1,7 @@
+/**
+ * API module exports.
+ */
+export * from './substrate-api.js';
+export * from './chatsvc-api.js';
+export * from './csa-api.js';
+export * from './calendar-api.js';

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

@@ -0,0 +1,50 @@
+/**
+ * Substrate API client for search and people operations.
+ *
+ * Handles all calls to substrate.office.com endpoints.
+ */
+import { type Result } from '../types/result.js';
+import { type PersonSearchResult, type ChannelSearchResult } from '../utils/parsers.js';
+import type { TeamsSearchResult, SearchPaginationResult } from '../types/teams.js';
+/** Search result with pagination. */
+export interface SearchResult {
+    results: TeamsSearchResult[];
+    pagination: SearchPaginationResult;
+}
+/** People search result. */
+export interface PeopleSearchResult {
+    results: PersonSearchResult[];
+    returned: number;
+}
+/**
+ * Searches Teams messages using the Substrate v2 query API.
+ */
+export declare function searchMessages(query: string, options?: {
+    from?: number;
+    size?: number;
+    maxResults?: number;
+}): Promise<Result<SearchResult>>;
+/**
+ * Searches for people by name or email.
+ */
+export declare function searchPeople(query: string, limit?: number): Promise<Result<PeopleSearchResult>>;
+/**
+ * Gets the user's frequently contacted people.
+ */
+export declare function getFrequentContacts(limit?: number): Promise<Result<PeopleSearchResult>>;
+/** Channel search result. */
+export interface ChannelSearchResultSet {
+    results: ChannelSearchResult[];
+    returned: number;
+}
+/**
+ * Searches for Teams channels by name using both:
+ * 1. User's own teams/channels (Teams List API) - reliable, shows membership
+ * 2. Organisation-wide discovery (Substrate suggestions) - broader but less reliable
+ *
+ * Results are merged and deduplicated, with membership status indicated.
+ *
+ * @param query - Channel name to search for
+ * @param limit - Maximum number of results (default: 10, max: 50)
+ */
+export declare function searchChannels(query: string, limit?: number): Promise<Result<ChannelSearchResultSet>>;

package/dist/api/substrate-api.js

@@ -0,0 +1,305 @@
+/**
+ * Substrate API client for search and people operations.
+ *
+ * Handles all calls to substrate.office.com endpoints.
+ */
+import { httpRequest } from '../utils/http.js';
+import { SUBSTRATE_API, getBearerHeaders } from '../utils/api-config.js';
+import { ErrorCode } from '../types/errors.js';
+import { ok } from '../types/result.js';
+import { clearTokenCache } from '../auth/token-extractor.js';
+import { requireSubstrateTokenAsync } from '../utils/auth-guards.js';
+import { parseSearchResults, parsePeopleResults, parseChannelResults, filterChannelsByName, } from '../utils/parsers.js';
+import { getMyTeamsAndChannels } from './csa-api.js';
+/**
+ * Searches Teams messages using the Substrate v2 query API.
+ */
+export async function searchMessages(query, options = {}) {
+    const tokenResult = await requireSubstrateTokenAsync();
+    if (!tokenResult.ok) {
+        return tokenResult;
+    }
+    const token = tokenResult.value;
+    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 httpRequest(SUBSTRATE_API.search, {
+        method: 'POST',
+        headers: getBearerHeaders(token),
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        // Clear cache on auth errors
+        if (response.error.code === ErrorCode.AUTH_EXPIRED) {
+            clearTokenCache();
+        }
+        return response;
+    }
+    const data = response.value.data;
+    const { results, total } = parseSearchResults(data.EntitySets);
+    const maxResults = options.maxResults ?? size;
+    const limitedResults = results.slice(0, maxResults);
+    return ok({
+        results: limitedResults,
+        pagination: {
+            from,
+            size,
+            returned: limitedResults.length,
+            total,
+            hasMore: total !== undefined
+                ? from + results.length < total
+                : results.length >= size,
+        },
+    });
+}
+/**
+ * Searches for people by name or email.
+ */
+export async function searchPeople(query, limit = 10) {
+    const tokenResult = await requireSubstrateTokenAsync();
+    if (!tokenResult.ok) {
+        return tokenResult;
+    }
+    const token = tokenResult.value;
+    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 httpRequest(SUBSTRATE_API.peopleSearch, {
+        method: 'POST',
+        headers: getBearerHeaders(token),
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        if (response.error.code === ErrorCode.AUTH_EXPIRED) {
+            clearTokenCache();
+        }
+        return response;
+    }
+    const results = parsePeopleResults(response.value.data.Groups);
+    return ok({
+        results,
+        returned: results.length,
+    });
+}
+/**
+ * Gets the user's frequently contacted people.
+ */
+export async function getFrequentContacts(limit = 50) {
+    const tokenResult = await requireSubstrateTokenAsync();
+    if (!tokenResult.ok) {
+        return tokenResult;
+    }
+    const token = tokenResult.value;
+    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 httpRequest(SUBSTRATE_API.frequentContacts, {
+        method: 'POST',
+        headers: getBearerHeaders(token),
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        if (response.error.code === ErrorCode.AUTH_EXPIRED) {
+            clearTokenCache();
+        }
+        return response;
+    }
+    const contacts = parsePeopleResults(response.value.data.Groups);
+    return ok({
+        results: contacts,
+        returned: contacts.length,
+    });
+}
+/**
+ * Searches for Teams channels by name using both:
+ * 1. User's own teams/channels (Teams List API) - reliable, shows membership
+ * 2. Organisation-wide discovery (Substrate suggestions) - broader but less reliable
+ *
+ * Results are merged and deduplicated, with membership status indicated.
+ *
+ * @param query - Channel name to search for
+ * @param limit - Maximum number of results (default: 10, max: 50)
+ */
+export async function searchChannels(query, limit = 10) {
+    const tokenResult = await requireSubstrateTokenAsync();
+    if (!tokenResult.ok) {
+        return tokenResult;
+    }
+    const token = tokenResult.value;
+    // Run both searches in parallel
+    const [orgSearchResult, myTeamsResult] = await Promise.all([
+        searchChannelsOrgWide(query, limit, token),
+        getMyTeamsAndChannels(),
+    ]);
+    // Build a map of channel IDs the user is a member of
+    const memberChannelIds = new Set();
+    const myChannelsMatching = [];
+    if (myTeamsResult.ok) {
+        // Filter the user's channels by the query and collect matching ones
+        const matching = filterChannelsByName(myTeamsResult.value.teams, query);
+        for (const channel of matching) {
+            memberChannelIds.add(channel.channelId);
+            myChannelsMatching.push(channel);
+        }
+        // Also add all channel IDs to the set for membership lookup
+        for (const team of myTeamsResult.value.teams) {
+            for (const channel of team.channels) {
+                memberChannelIds.add(channel.channelId);
+            }
+        }
+    }
+    // Process org-wide results, marking membership status
+    const orgChannels = [];
+    if (orgSearchResult.ok) {
+        for (const channel of orgSearchResult.value) {
+            // Mark whether user is a member
+            channel.isMember = memberChannelIds.has(channel.channelId);
+            orgChannels.push(channel);
+        }
+    }
+    // Merge results: start with user's matching channels (definitely accessible),
+    // then add org-wide results that aren't duplicates
+    const seenIds = new Set();
+    const merged = [];
+    // First add channels from user's teams (reliable, known accessible)
+    for (const channel of myChannelsMatching) {
+        if (!seenIds.has(channel.channelId)) {
+            seenIds.add(channel.channelId);
+            merged.push(channel);
+        }
+    }
+    // Then add org-wide results that aren't duplicates
+    for (const channel of orgChannels) {
+        if (!seenIds.has(channel.channelId)) {
+            seenIds.add(channel.channelId);
+            merged.push(channel);
+        }
+    }
+    // Apply limit
+    const limited = merged.slice(0, limit);
+    return ok({
+        results: limited,
+        returned: limited.length,
+    });
+}
+/**
+ * Internal: Searches for channels org-wide using the Substrate suggestions API.
+ *
+ * This is a typeahead/autocomplete API, so matching behaviour may be inconsistent
+ * for multi-word queries. Used as a supplement to the user's own teams list.
+ */
+async function searchChannelsOrgWide(query, limit, token) {
+    const cvid = crypto.randomUUID();
+    const logicalId = crypto.randomUUID();
+    const body = {
+        EntityRequests: [{
+                Query: {
+                    QueryString: query,
+                    DisplayQueryString: query,
+                },
+                EntityType: 'TeamsChannel',
+                Size: Math.min(limit, 50),
+            }],
+        cvid,
+        logicalId,
+    };
+    const response = await httpRequest(SUBSTRATE_API.channelSearch, {
+        method: 'POST',
+        headers: getBearerHeaders(token),
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        if (response.error.code === ErrorCode.AUTH_EXPIRED) {
+            clearTokenCache();
+        }
+        return response;
+    }
+    const data = response.value.data;
+    const results = parseChannelResults(data?.Groups);
+    // Mark all org-wide results as isMember: false initially
+    // (caller will update based on actual membership)
+    for (const result of results) {
+        result.isMember = false;
+    }
+    return ok(results);
+}

package/dist/auth/crypto.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Encryption utilities for credential storage.
+ *
+ * Uses machine-specific key derivation to encrypt sensitive data at rest.
+ * This is not foolproof security, but significantly raises the bar compared
+ * to plaintext storage.
+ */
+/** Encrypted data format. */
+export interface EncryptedData {
+    /** Initialisation vector (hex). */
+    iv: string;
+    /** Encrypted content (hex). */
+    content: string;
+    /** Authentication tag (hex). */
+    tag: string;
+    /** Version marker for format compatibility. */
+    version: number;
+}
+/**
+ * Encrypts a string value.
+ */
+export declare function encrypt(plaintext: string): EncryptedData;
+/**
+ * Decrypts encrypted data.
+ *
+ * @throws Error if decryption fails (wrong machine, corrupted data, etc.)
+ */
+export declare function decrypt(data: EncryptedData): string;
+/**
+ * Checks if data looks like encrypted format.
+ */
+export declare function isEncrypted(data: unknown): data is EncryptedData;