msteams-mcp 0.2.0

package/dist/types/result.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Result type for operations that can fail.
+ *
+ * Provides a discriminated union for success/failure that
+ * forces callers to handle errors explicitly.
+ */
+import type { McpError } from './errors.js';
+/** Successful result with a value. */
+export interface Ok<T> {
+    ok: true;
+    value: T;
+}
+/** Failed result with an error. */
+export interface Err<E = McpError> {
+    ok: false;
+    error: E;
+}
+/** A result that can be either a success or failure. */
+export type Result<T, E = McpError> = Ok<T> | Err<E>;
+/**
+ * Creates a successful result.
+ */
+export declare function ok<T>(value: T): Ok<T>;
+/**
+ * Creates a failed result.
+ */
+export declare function err<E = McpError>(error: E): Err<E>;
+/**
+ * Unwraps a result, throwing if it's an error.
+ */
+export declare function unwrap<T>(result: Result<T>): T;
+/**
+ * Unwraps a result with a default value for errors.
+ */
+export declare function unwrapOr<T>(result: Result<T>, defaultValue: T): T;
+/**
+ * Maps a successful result to a new value.
+ */
+export declare function map<T, U>(result: Result<T>, fn: (value: T) => U): Result<U>;
+/**
+ * Maps a successful result to a new result (flatMap).
+ */
+export declare function andThen<T, U>(result: Result<T>, fn: (value: T) => Result<U>): Result<U>;

package/dist/types/result.js

@@ -0,0 +1,51 @@
+/**
+ * Result type for operations that can fail.
+ *
+ * Provides a discriminated union for success/failure that
+ * forces callers to handle errors explicitly.
+ */
+/**
+ * Creates a successful result.
+ */
+export function ok(value) {
+    return { ok: true, value };
+}
+/**
+ * Creates a failed result.
+ */
+export function err(error) {
+    return { ok: false, error };
+}
+/**
+ * Unwraps a result, throwing if it's an error.
+ */
+export function unwrap(result) {
+    if (result.ok) {
+        return result.value;
+    }
+    throw new Error(result.error.message);
+}
+/**
+ * Unwraps a result with a default value for errors.
+ */
+export function unwrapOr(result, defaultValue) {
+    return result.ok ? result.value : defaultValue;
+}
+/**
+ * Maps a successful result to a new value.
+ */
+export function map(result, fn) {
+    if (result.ok) {
+        return ok(fn(result.value));
+    }
+    return result;
+}
+/**
+ * Maps a successful result to a new result (flatMap).
+ */
+export function andThen(result, fn) {
+    if (result.ok) {
+        return fn(result.value);
+    }
+    return result;
+}

package/dist/types/teams.d.ts

@@ -0,0 +1,79 @@
+/**
+ * TypeScript interfaces for Teams data structures.
+ * These will be refined based on research findings.
+ */
+export interface TeamsSearchResult {
+    id: string;
+    type: 'message' | 'file' | 'person';
+    content: string;
+    sender?: string;
+    timestamp?: string;
+    channelName?: string;
+    teamName?: string;
+    conversationId?: string;
+    messageId?: string;
+    /** Direct link to open this message in Teams */
+    messageLink?: string;
+}
+export interface TeamsMessage {
+    id: string;
+    content: string;
+    sender: string;
+    timestamp: string;
+    channelName?: string;
+    teamName?: string;
+    replyCount?: number;
+    reactions?: TeamsReaction[];
+}
+export interface TeamsReaction {
+    type: string;
+    count: number;
+}
+export interface InterceptedRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    postData?: string;
+    timestamp: Date;
+}
+export interface InterceptedResponse {
+    url: string;
+    status: number;
+    headers: Record<string, string>;
+    body?: string;
+    timestamp: Date;
+}
+export interface SearchApiEndpoint {
+    url: string;
+    method: string;
+    description: string;
+    requestFormat?: unknown;
+    responseFormat?: unknown;
+}
+/** Pagination options for search requests. */
+export interface SearchPaginationOptions {
+    /** Starting offset (0-based). Default: 0 */
+    from?: number;
+    /** Page size. Default: 25 */
+    size?: number;
+    /** Maximum total results to fetch across all pages. */
+    maxResults?: number;
+}
+/** Pagination metadata returned with search results. */
+export interface SearchPaginationResult {
+    /** Number of results returned in this response. */
+    returned: number;
+    /** Starting offset used for this request. */
+    from: number;
+    /** Page size requested. */
+    size: number;
+    /** Total results available (if known). */
+    total?: number;
+    /** Whether more results are available. */
+    hasMore: boolean;
+}
+/** Search results with pagination metadata. */
+export interface TeamsSearchResultsWithPagination {
+    results: TeamsSearchResult[];
+    pagination: SearchPaginationResult;
+}

package/dist/types/teams.js

@@ -0,0 +1,5 @@
+/**
+ * TypeScript interfaces for Teams data structures.
+ * These will be refined based on research findings.
+ */
+export {};

package/dist/utils/api-config.d.ts

@@ -0,0 +1,66 @@
+/**
+ * API endpoint configuration and header utilities.
+ *
+ * Centralises all API URLs and common request headers.
+ */
+/** Valid API regions. */
+export declare const VALID_REGIONS: readonly ["amer", "emea", "apac"];
+export type Region = typeof VALID_REGIONS[number];
+/**
+ * Validates a region string.
+ * @throws Error if region is invalid.
+ */
+export declare function validateRegion(region: string): Region;
+/**
+ * Attempts to parse region from a URL or returns default.
+ */
+export declare function parseRegionFromUrl(url: string): Region;
+/** Substrate API endpoints. */
+export declare const SUBSTRATE_API: {
+    /** Full-text message search. */
+    readonly search: "https://substrate.office.com/searchservice/api/v2/query";
+    /** People and message typeahead suggestions. */
+    readonly suggestions: "https://substrate.office.com/search/api/v1/suggestions";
+    /** Frequent contacts list. */
+    readonly frequentContacts: "https://substrate.office.com/search/api/v1/suggestions?scenario=peoplecache";
+    /** People search. */
+    readonly peopleSearch: "https://substrate.office.com/search/api/v1/suggestions?scenario=powerbar";
+    /** Channel search (org-wide, not just user's teams). */
+    readonly channelSearch: "https://substrate.office.com/search/api/v1/suggestions?scenario=powerbar&setflight=TurnOffMPLSuppressionTeams,EnableTeamsChannelDomainPowerbar&domain=TeamsChannel";
+};
+/** Chat service API endpoints. */
+export declare const CHATSVC_API: {
+    /**
+     * Get messages URL for a conversation.
+     *
+     * For thread replies in channels, provide replyToMessageId to append
+     * `;messageid={id}` to the conversation path. This tells Teams the message
+     * is a reply to an existing thread rather than a new top-level post.
+     */
+    readonly messages: (region: Region, conversationId: string, replyToMessageId?: string) => string;
+    /** Get conversation metadata URL. */
+    readonly conversation: (region: Region, conversationId: string) => string;
+    /** Save/unsave message metadata URL. */
+    readonly messageMetadata: (region: Region, conversationId: string, messageId: string) => string;
+    /** Edit a specific message URL. */
+    readonly editMessage: (region: Region, conversationId: string, messageId: string) => string;
+    /** Delete a specific message URL (soft delete). */
+    readonly deleteMessage: (region: Region, conversationId: string, messageId: string) => string;
+};
+/** CSA (Chat Service Aggregator) API endpoints. */
+export declare const CSA_API: {
+    /** Conversation folders (favourites) URL. */
+    readonly conversationFolders: (region: Region) => string;
+    /** Teams list (all teams/channels user is a member of). */
+    readonly teamsList: (region: Region) => string;
+};
+/** Common request headers for Teams API calls. */
+export declare function getTeamsHeaders(): HeadersInit;
+/** Headers for Bearer token authentication. */
+export declare function getBearerHeaders(token: string): HeadersInit;
+/** Headers for Skype token + Bearer authentication. */
+export declare function getSkypeAuthHeaders(skypeToken: string, authToken: string): HeadersInit;
+/** Headers for CSA API (Skype token + CSA Bearer). */
+export declare function getCsaHeaders(skypeToken: string, csaToken: string): HeadersInit;
+/** Client version header for messaging API. */
+export declare function getMessagingHeaders(skypeToken: string, authToken: string): HeadersInit;

package/dist/utils/api-config.js

@@ -0,0 +1,113 @@
+/**
+ * API endpoint configuration and header utilities.
+ *
+ * Centralises all API URLs and common request headers.
+ */
+/** Valid API regions. */
+export const VALID_REGIONS = ['amer', 'emea', 'apac'];
+/**
+ * Validates a region string.
+ * @throws Error if region is invalid.
+ */
+export function validateRegion(region) {
+    if (!VALID_REGIONS.includes(region)) {
+        throw new Error(`Invalid region: ${region}. Valid regions: ${VALID_REGIONS.join(', ')}`);
+    }
+    return region;
+}
+/**
+ * Attempts to parse region from a URL or returns default.
+ */
+export function parseRegionFromUrl(url) {
+    for (const region of VALID_REGIONS) {
+        if (url.includes(`/api/chatsvc/${region}/`) ||
+            url.includes(`/api/csa/${region}/`)) {
+            return region;
+        }
+    }
+    return 'amer'; // Default region
+}
+/** Substrate API endpoints. */
+export const SUBSTRATE_API = {
+    /** Full-text message search. */
+    search: 'https://substrate.office.com/searchservice/api/v2/query',
+    /** People and message typeahead suggestions. */
+    suggestions: 'https://substrate.office.com/search/api/v1/suggestions',
+    /** Frequent contacts list. */
+    frequentContacts: 'https://substrate.office.com/search/api/v1/suggestions?scenario=peoplecache',
+    /** People search. */
+    peopleSearch: 'https://substrate.office.com/search/api/v1/suggestions?scenario=powerbar',
+    /** Channel search (org-wide, not just user's teams). */
+    channelSearch: 'https://substrate.office.com/search/api/v1/suggestions?scenario=powerbar&setflight=TurnOffMPLSuppressionTeams,EnableTeamsChannelDomainPowerbar&domain=TeamsChannel',
+};
+/** Chat service API endpoints. */
+export const CHATSVC_API = {
+    /**
+     * Get messages URL for a conversation.
+     *
+     * For thread replies in channels, provide replyToMessageId to append
+     * `;messageid={id}` to the conversation path. This tells Teams the message
+     * is a reply to an existing thread rather than a new top-level post.
+     */
+    messages: (region, conversationId, replyToMessageId) => {
+        // When replying to a thread, the URL includes ;messageid={threadRootId}
+        const conversationPath = replyToMessageId
+            ? `${conversationId};messageid=${replyToMessageId}`
+            : conversationId;
+        return `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationPath)}/messages`;
+    },
+    /** Get conversation metadata URL. */
+    conversation: (region, conversationId) => `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}`,
+    /** Save/unsave message metadata URL. */
+    messageMetadata: (region, conversationId, messageId) => `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}/rcmetadata/${messageId}`,
+    /** Edit a specific message URL. */
+    editMessage: (region, conversationId, messageId) => `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}/messages/${messageId}`,
+    /** Delete a specific message URL (soft delete). */
+    deleteMessage: (region, conversationId, messageId) => `https://teams.microsoft.com/api/chatsvc/${region}/v1/users/ME/conversations/${encodeURIComponent(conversationId)}/messages/${messageId}?behavior=softDelete`,
+};
+/** CSA (Chat Service Aggregator) API endpoints. */
+export const CSA_API = {
+    /** Conversation folders (favourites) URL. */
+    conversationFolders: (region) => `https://teams.microsoft.com/api/csa/${region}/api/v1/teams/users/me/conversationFolders?supportsAdditionalSystemGeneratedFolders=true&supportsSliceItems=true`,
+    /** Teams list (all teams/channels user is a member of). */
+    teamsList: (region) => `https://teams.microsoft.com/api/csa/${region}/api/v3/teams/users/me?isPrefetch=false&enableMembershipSummary=true`,
+};
+/** Common request headers for Teams API calls. */
+export function getTeamsHeaders() {
+    return {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+        'Origin': 'https://teams.microsoft.com',
+        'Referer': 'https://teams.microsoft.com/',
+    };
+}
+/** Headers for Bearer token authentication. */
+export function getBearerHeaders(token) {
+    return {
+        ...getTeamsHeaders(),
+        'Authorization': `Bearer ${token}`,
+    };
+}
+/** Headers for Skype token + Bearer authentication. */
+export function getSkypeAuthHeaders(skypeToken, authToken) {
+    return {
+        ...getTeamsHeaders(),
+        'Authentication': `skypetoken=${skypeToken}`,
+        'Authorization': `Bearer ${authToken}`,
+    };
+}
+/** Headers for CSA API (Skype token + CSA Bearer). */
+export function getCsaHeaders(skypeToken, csaToken) {
+    return {
+        ...getTeamsHeaders(),
+        'Authentication': `skypetoken=${skypeToken}`,
+        'Authorization': `Bearer ${csaToken}`,
+    };
+}
+/** Client version header for messaging API. */
+export function getMessagingHeaders(skypeToken, authToken) {
+    return {
+        ...getSkypeAuthHeaders(skypeToken, authToken),
+        'X-Ms-Client-Version': '1415/1.0.0.2025010401',
+    };
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 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 } from '../auth/token-extractor.js';
+/** Authentication info for messaging and CSA APIs. */
+export interface CsaAuthInfo {
+    auth: MessageAuthInfo;
+    csaToken: string;
+}
+/**
+ * Requires a valid Substrate token.
+ * Use for search and people APIs.
+ */
+export declare function requireSubstrateToken(): 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>;

package/dist/utils/auth-guards.js

@@ -0,0 +1,54 @@
+/**
+ * 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, } from '../auth/token-extractor.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Error Messages
+// ─────────────────────────────────────────────────────────────────────────────
+const AUTH_ERROR_MESSAGES = {
+    substrateToken: 'No valid token available. Browser login required.',
+    messageAuth: 'No valid authentication. Browser login required.',
+    csaToken: 'No valid authentication for favourites. Browser login required.',
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Guard Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Requires a valid Substrate token.
+ * Use for search and people APIs.
+ */
+export function requireSubstrateToken() {
+    const token = getValidSubstrateToken();
+    if (!token) {
+        return err(createError(ErrorCode.AUTH_REQUIRED, AUTH_ERROR_MESSAGES.substrateToken));
+    }
+    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 });
+}

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,111 @@
+/**
+ * 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')) {
+            data = await response.json();
+        }
+        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;
+}