msteams-mcp 0.2.1

package/dist/browser/context.js

@@ -0,0 +1,122 @@
+/**
+ * Playwright browser context management.
+ * Creates and manages browser contexts with session persistence.
+ *
+ * Uses the system's installed Chrome or Edge browser rather than downloading
+ * Playwright's bundled Chromium. This significantly reduces install size.
+ */
+import { chromium } from 'playwright';
+import { ensureUserDataDir, hasSessionState, SESSION_STATE_PATH, isSessionLikelyExpired, writeSessionState, readSessionState, } from '../auth/session-store.js';
+import { clearRegionCache } from '../utils/auth-guards.js';
+const DEFAULT_OPTIONS = {
+    headless: true,
+    viewport: { width: 1280, height: 800 },
+};
+/**
+ * Determines the browser channel to use based on the platform.
+ * - Windows: Use Microsoft Edge (always installed on Windows 10+)
+ * - macOS/Linux: Use Chrome
+ *
+ * @returns The browser channel name for Playwright
+ */
+function getBrowserChannel() {
+    return process.platform === 'win32' ? 'msedge' : 'chrome';
+}
+/**
+ * Creates a browser context with optional session state restoration.
+ *
+ * Uses the system's installed Chrome or Edge browser rather than downloading
+ * Playwright's bundled Chromium (~180MB savings).
+ *
+ * @param options - Browser configuration options
+ * @returns Browser manager with browser, context, and page
+ * @throws Error if system browser is not found (with helpful suggestions)
+ */
+export async function createBrowserContext(options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    ensureUserDataDir();
+    const channel = getBrowserChannel();
+    let browser;
+    try {
+        browser = await chromium.launch({
+            headless: opts.headless,
+            channel,
+        });
+    }
+    catch (error) {
+        const browserName = channel === 'msedge' ? 'Microsoft Edge' : 'Google Chrome';
+        const installHint = channel === 'msedge'
+            ? 'Edge should be pre-installed on Windows. Try updating Windows or reinstalling Edge.'
+            : 'Install Chrome from https://www.google.com/chrome/ or run: npx playwright install chromium';
+        throw new Error(`Could not launch ${browserName}. ${installHint}\n\n` +
+            `Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const hasSession = hasSessionState();
+    const sessionExpired = isSessionLikelyExpired();
+    // Restore session if we have one and it's not ancient
+    const shouldRestoreSession = hasSession && !sessionExpired;
+    let context;
+    if (shouldRestoreSession) {
+        try {
+            // Read the decrypted session state
+            const state = readSessionState();
+            if (state) {
+                // Create a temporary file for Playwright (it needs a file path)
+                // We write the decrypted state to a temp location
+                const tempPath = SESSION_STATE_PATH + '.tmp';
+                const fs = await import('fs');
+                fs.writeFileSync(tempPath, JSON.stringify(state), { mode: 0o600 });
+                try {
+                    context = await browser.newContext({
+                        storageState: tempPath,
+                        viewport: opts.viewport,
+                    });
+                }
+                finally {
+                    // Clean up temp file
+                    fs.unlinkSync(tempPath);
+                }
+            }
+            else {
+                throw new Error('Failed to read session state');
+            }
+        }
+        catch (error) {
+            console.warn('Failed to restore session state, starting fresh:', error);
+            context = await browser.newContext({
+                viewport: opts.viewport,
+            });
+        }
+    }
+    else {
+        context = await browser.newContext({
+            viewport: opts.viewport,
+        });
+    }
+    const page = await context.newPage();
+    return {
+        browser,
+        context,
+        page,
+        isNewSession: !shouldRestoreSession,
+    };
+}
+/**
+ * Saves the current browser context's session state.
+ */
+export async function saveSessionState(context) {
+    const state = await context.storageState();
+    writeSessionState(state);
+    // Clear cached region config so new session values are picked up
+    clearRegionCache();
+}
+/**
+ * Closes the browser and optionally saves session state.
+ */
+export async function closeBrowser(manager, saveSession = true) {
+    if (saveSession) {
+        await saveSessionState(manager.context);
+    }
+    await manager.context.close();
+    await manager.browser.close();
+}

package/dist/constants.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Shared constants used across the codebase.
+ *
+ * Centralising these values makes the code more maintainable and
+ * allows for easier configuration changes.
+ */
+/** Minimum content length to be considered valid (characters). */
+export declare const MIN_CONTENT_LENGTH = 5;
+/** Maximum length for config values in debug output (characters). */
+export declare const MAX_DEBUG_CONFIG_VALUE_LENGTH = 5000;
+/** Default page size for search results. */
+export declare const DEFAULT_PAGE_SIZE = 25;
+/** Maximum page size for search results. */
+export declare const MAX_PAGE_SIZE = 100;
+/** Default limit for thread messages. */
+export declare const DEFAULT_THREAD_LIMIT = 50;
+/** Maximum limit for thread messages. */
+export declare const MAX_THREAD_LIMIT = 200;
+/** Default limit for people search. */
+export declare const DEFAULT_PEOPLE_LIMIT = 10;
+/** Maximum limit for people search. */
+export declare const MAX_PEOPLE_LIMIT = 50;
+/** Default limit for frequent contacts. */
+export declare const DEFAULT_CONTACTS_LIMIT = 50;
+/** Maximum limit for frequent contacts. */
+export declare const MAX_CONTACTS_LIMIT = 500;
+/** Default limit for channel search. */
+export declare const DEFAULT_CHANNEL_LIMIT = 10;
+/** Maximum limit for channel search. */
+export declare const MAX_CHANNEL_LIMIT = 50;
+/** Default timeout for waiting for search results. */
+export declare const SEARCH_RESULT_TIMEOUT_MS = 10000;
+/** Default HTTP request timeout. */
+export declare const HTTP_REQUEST_TIMEOUT_MS = 30000;
+/** Short delay for UI interactions. */
+export declare const UI_SHORT_DELAY_MS = 300;
+/** Medium delay for UI state changes. */
+export declare const UI_MEDIUM_DELAY_MS = 1000;
+/** Long delay for API responses to settle. */
+export declare const UI_LONG_DELAY_MS = 2000;
+/** Authentication check interval. */
+export declare const AUTH_CHECK_INTERVAL_MS = 2000;
+/** Default login timeout (5 minutes). */
+export declare const LOGIN_TIMEOUT_MS: number;
+/** Pause after showing progress overlay step (ms). */
+export declare const OVERLAY_STEP_PAUSE_MS = 1500;
+/** Pause after showing final "All done" overlay (ms). */
+export declare const OVERLAY_COMPLETE_PAUSE_MS = 2000;
+/** Session expiry threshold in hours. */
+export declare const SESSION_EXPIRY_HOURS = 12;
+/** Default maximum retry attempts for HTTP requests. */
+export declare const DEFAULT_MAX_RETRIES = 3;
+/** Base delay for exponential backoff (milliseconds). */
+export declare const RETRY_BASE_DELAY_MS = 1000;
+/** Maximum delay between retries (milliseconds). */
+export declare const RETRY_MAX_DELAY_MS = 10000;
+/**
+ * Virtual Conversation IDs.
+ *
+ * These special IDs are used with the standard chatsvc messages endpoint
+ * (/users/ME/conversations/{id}/messages) to retrieve aggregated views
+ * across all conversations. See docs/API-REFERENCE.md for details.
+ */
+/** Prefix for virtual conversation IDs (48:saved, 48:notifications, etc). */
+export declare const VIRTUAL_CONVERSATION_PREFIX = "48:";
+/** Self-chat (notes) conversation ID. */
+export declare const SELF_CHAT_ID = "48:notes";
+/** Activity feed (notifications) conversation ID. */
+export declare const NOTIFICATIONS_ID = "48:notifications";
+/** Saved messages virtual conversation ID. */
+export declare const SAVED_MESSAGES_ID = "48:saved";
+/** Followed threads virtual conversation ID. */
+export declare const FOLLOWED_THREADS_ID = "48:threads";
+/** Default limit for activity feed items. */
+export declare const DEFAULT_ACTIVITY_LIMIT = 50;
+/** Maximum limit for activity feed items. */
+export declare const MAX_ACTIVITY_LIMIT = 200;
+/** Maximum conversations to check when aggregating unread status. */
+export declare const MAX_UNREAD_AGGREGATE_CHECK = 20;
+/** Default number of days ahead to fetch meetings. */
+export declare const DEFAULT_MEETING_DAYS_AHEAD = 7;
+/** Default limit for meeting results. */
+export declare const DEFAULT_MEETING_LIMIT = 50;
+/** Maximum limit for meeting results. */
+export declare const MAX_MEETING_LIMIT = 200;
+/** Threshold for proactive token refresh (10 minutes before expiry). */
+export declare const TOKEN_REFRESH_THRESHOLD_MS: number;
+/** MRI type prefix for Teams/AAD users (type 8). */
+export declare const MRI_TYPE_PREFIX = "8:";
+/** Identity type prefix for organisation users. */
+export declare const ORGID_PREFIX = "orgid:";
+/** Full MRI prefix for organisation users (8:orgid:). */
+export declare const MRI_ORGID_PREFIX = "8:orgid:";
+/** Standard Teams emoji entry. */
+export interface StandardEmoji {
+    key: string;
+    description: string;
+    category: 'reaction' | 'expression' | 'affection' | 'action' | 'animal' | 'object' | 'other';
+}
+/**
+ * Standard Teams emoji shortcuts (built-in, no API call needed).
+ * These are the common emojis available in Teams for reactions and messages.
+ */
+export declare const STANDARD_EMOJIS: readonly StandardEmoji[];

package/dist/constants.js

@@ -0,0 +1,195 @@
+/**
+ * Shared constants used across the codebase.
+ *
+ * Centralising these values makes the code more maintainable and
+ * allows for easier configuration changes.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Content Thresholds
+// ─────────────────────────────────────────────────────────────────────────────
+/** Minimum content length to be considered valid (characters). */
+export const MIN_CONTENT_LENGTH = 5;
+/** Maximum length for config values in debug output (characters). */
+export const MAX_DEBUG_CONFIG_VALUE_LENGTH = 5000;
+// ─────────────────────────────────────────────────────────────────────────────
+// Pagination Defaults
+// ─────────────────────────────────────────────────────────────────────────────
+/** Default page size for search results. */
+export const DEFAULT_PAGE_SIZE = 25;
+/** Maximum page size for search results. */
+export const MAX_PAGE_SIZE = 100;
+/** Default limit for thread messages. */
+export const DEFAULT_THREAD_LIMIT = 50;
+/** Maximum limit for thread messages. */
+export const MAX_THREAD_LIMIT = 200;
+/** Default limit for people search. */
+export const DEFAULT_PEOPLE_LIMIT = 10;
+/** Maximum limit for people search. */
+export const MAX_PEOPLE_LIMIT = 50;
+/** Default limit for frequent contacts. */
+export const DEFAULT_CONTACTS_LIMIT = 50;
+/** Maximum limit for frequent contacts. */
+export const MAX_CONTACTS_LIMIT = 500;
+/** Default limit for channel search. */
+export const DEFAULT_CHANNEL_LIMIT = 10;
+/** Maximum limit for channel search. */
+export const MAX_CHANNEL_LIMIT = 50;
+// ─────────────────────────────────────────────────────────────────────────────
+// Timeouts (milliseconds)
+// ─────────────────────────────────────────────────────────────────────────────
+/** Default timeout for waiting for search results. */
+export const SEARCH_RESULT_TIMEOUT_MS = 10000;
+/** Default HTTP request timeout. */
+export const HTTP_REQUEST_TIMEOUT_MS = 30000;
+/** Short delay for UI interactions. */
+export const UI_SHORT_DELAY_MS = 300;
+/** Medium delay for UI state changes. */
+export const UI_MEDIUM_DELAY_MS = 1000;
+/** Long delay for API responses to settle. */
+export const UI_LONG_DELAY_MS = 2000;
+/** Authentication check interval. */
+export const AUTH_CHECK_INTERVAL_MS = 2000;
+/** Default login timeout (5 minutes). */
+export const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+/** Pause after showing progress overlay step (ms). */
+export const OVERLAY_STEP_PAUSE_MS = 1500;
+/** Pause after showing final "All done" overlay (ms). */
+export const OVERLAY_COMPLETE_PAUSE_MS = 2000;
+// ─────────────────────────────────────────────────────────────────────────────
+// Session Management
+// ─────────────────────────────────────────────────────────────────────────────
+/** Session expiry threshold in hours. */
+export const SESSION_EXPIRY_HOURS = 12;
+// ─────────────────────────────────────────────────────────────────────────────
+// Retry Configuration
+// ─────────────────────────────────────────────────────────────────────────────
+/** Default maximum retry attempts for HTTP requests. */
+export const DEFAULT_MAX_RETRIES = 3;
+/** Base delay for exponential backoff (milliseconds). */
+export const RETRY_BASE_DELAY_MS = 1000;
+/** Maximum delay between retries (milliseconds). */
+export const RETRY_MAX_DELAY_MS = 10000;
+// ─────────────────────────────────────────────────────────────────────────────
+// Conversation IDs
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Virtual Conversation IDs.
+ *
+ * These special IDs are used with the standard chatsvc messages endpoint
+ * (/users/ME/conversations/{id}/messages) to retrieve aggregated views
+ * across all conversations. See docs/API-REFERENCE.md for details.
+ */
+/** Prefix for virtual conversation IDs (48:saved, 48:notifications, etc). */
+export const VIRTUAL_CONVERSATION_PREFIX = '48:';
+/** Self-chat (notes) conversation ID. */
+export const SELF_CHAT_ID = '48:notes';
+/** Activity feed (notifications) conversation ID. */
+export const NOTIFICATIONS_ID = '48:notifications';
+/** Saved messages virtual conversation ID. */
+export const SAVED_MESSAGES_ID = '48:saved';
+/** Followed threads virtual conversation ID. */
+export const FOLLOWED_THREADS_ID = '48:threads';
+// ─────────────────────────────────────────────────────────────────────────────
+// Activity Feed
+// ─────────────────────────────────────────────────────────────────────────────
+/** Default limit for activity feed items. */
+export const DEFAULT_ACTIVITY_LIMIT = 50;
+/** Maximum limit for activity feed items. */
+export const MAX_ACTIVITY_LIMIT = 200;
+// ─────────────────────────────────────────────────────────────────────────────
+// Unread Status
+// ─────────────────────────────────────────────────────────────────────────────
+/** Maximum conversations to check when aggregating unread status. */
+export const MAX_UNREAD_AGGREGATE_CHECK = 20;
+// ─────────────────────────────────────────────────────────────────────────────
+// Calendar/Meetings
+// ─────────────────────────────────────────────────────────────────────────────
+/** Default number of days ahead to fetch meetings. */
+export const DEFAULT_MEETING_DAYS_AHEAD = 7;
+/** Default limit for meeting results. */
+export const DEFAULT_MEETING_LIMIT = 50;
+/** Maximum limit for meeting results. */
+export const MAX_MEETING_LIMIT = 200;
+// ─────────────────────────────────────────────────────────────────────────────
+// Token Refresh
+// ─────────────────────────────────────────────────────────────────────────────
+/** Threshold for proactive token refresh (10 minutes before expiry). */
+export const TOKEN_REFRESH_THRESHOLD_MS = 10 * 60 * 1000;
+// ─────────────────────────────────────────────────────────────────────────────
+// User Identity
+// ─────────────────────────────────────────────────────────────────────────────
+/** MRI type prefix for Teams/AAD users (type 8). */
+export const MRI_TYPE_PREFIX = '8:';
+/** Identity type prefix for organisation users. */
+export const ORGID_PREFIX = 'orgid:';
+/** Full MRI prefix for organisation users (8:orgid:). */
+export const MRI_ORGID_PREFIX = `${MRI_TYPE_PREFIX}${ORGID_PREFIX}`;
+/**
+ * Standard Teams emoji shortcuts (built-in, no API call needed).
+ * These are the common emojis available in Teams for reactions and messages.
+ */
+export const STANDARD_EMOJIS = [
+    // Quick reactions (shown in reaction picker)
+    { key: 'like', description: 'Thumbs up 👍', category: 'reaction' },
+    { key: 'heart', description: 'Heart ❤️', category: 'reaction' },
+    { key: 'laugh', description: 'Laughing 😂', category: 'reaction' },
+    { key: 'surprised', description: 'Surprised 😮', category: 'reaction' },
+    { key: 'sad', description: 'Sad 😢', category: 'reaction' },
+    { key: 'angry', description: 'Angry 😠', category: 'reaction' },
+    // Expressions
+    { key: 'smile', description: 'Smiley 😊', category: 'expression' },
+    { key: 'wink', description: 'Winking 😉', category: 'expression' },
+    { key: 'cry', description: 'Crying 😭', category: 'expression' },
+    { key: 'cwl', description: 'Crying with laughter 😂', category: 'expression' },
+    { key: 'rofl', description: 'Rolling on floor laughing 🤣', category: 'expression' },
+    { key: 'blush', description: 'Blushing 😊', category: 'expression' },
+    { key: 'speechless', description: 'Speechless 😶', category: 'expression' },
+    { key: 'wonder', description: 'Wondering 🤔', category: 'expression' },
+    { key: 'sleepy', description: 'Sleepy 😴', category: 'expression' },
+    { key: 'yawn', description: 'Yawning 🥱', category: 'expression' },
+    { key: 'eyeroll', description: 'Eye roll 🙄', category: 'expression' },
+    { key: 'worry', description: 'Worried 😟', category: 'expression' },
+    { key: 'puke', description: 'Puking 🤮', category: 'expression' },
+    { key: 'giggle', description: 'Giggling 🤭', category: 'expression' },
+    { key: 'tongueout', description: 'Tongue out 😛', category: 'expression' },
+    // Affection
+    { key: 'kiss', description: 'Kiss 😘', category: 'affection' },
+    { key: 'inlove', description: 'In love 😍', category: 'affection' },
+    { key: 'hug', description: 'Hug 🤗', category: 'affection' },
+    { key: 'lips', description: 'Kissing lips 💋', category: 'affection' },
+    // Actions
+    { key: 'facepalm', description: 'Facepalm 🤦', category: 'action' },
+    { key: 'sweat', description: 'Sweating 😓', category: 'action' },
+    { key: 'dance', description: 'Dancing 💃', category: 'action' },
+    { key: 'bow', description: 'Bowing 🙇', category: 'action' },
+    { key: 'headbang', description: 'Banging head on wall', category: 'action' },
+    { key: 'wasntme', description: "It wasn't me 🤷", category: 'action' },
+    { key: 'hungover', description: 'Hungover', category: 'action' },
+    { key: 'shivering', description: 'Shivering 🥶', category: 'action' },
+    // Animals
+    { key: 'penguin', description: 'Penguin 🐧', category: 'animal' },
+    { key: 'cat', description: 'Cat 🐱', category: 'animal' },
+    { key: 'monkey', description: 'Monkey 🐵', category: 'animal' },
+    { key: 'polarbear', description: 'Polar bear 🐻‍❄️', category: 'animal' },
+    { key: 'elephant', description: 'Elephant 🐘', category: 'animal' },
+    // Objects
+    { key: 'flower', description: 'Flower 🌸', category: 'object' },
+    { key: 'sun', description: 'Sun ☀️', category: 'object' },
+    { key: 'star', description: 'Star ⭐', category: 'object' },
+    { key: 'xmastree', description: 'Christmas tree 🎄', category: 'object' },
+    { key: 'cake', description: 'Cake 🎂', category: 'object' },
+    { key: 'gift', description: 'Gift 🎁', category: 'object' },
+    { key: 'cash', description: 'Cash 💵', category: 'object' },
+    { key: 'champagne', description: 'Champagne 🍾', category: 'object' },
+    // Other
+    { key: 'yes', description: 'Yes/Thumbs up ✅', category: 'other' },
+    { key: 'cool', description: 'Cool 😎', category: 'other' },
+    { key: 'party', description: 'Party 🎉', category: 'other' },
+    { key: 'hi', description: 'Wave/Hello 👋', category: 'other' },
+    { key: 'angel', description: 'Angel 😇', category: 'other' },
+    { key: 'devil', description: 'Devil 😈', category: 'other' },
+    { key: 'holidayspirit', description: 'Holiday spirit 🎅', category: 'other' },
+    { key: 'lipssealed', description: 'Lips sealed 🤐', category: 'other' },
+    { key: 'makeup', description: 'Make-up 💄', category: 'other' },
+    { key: 'snowangel', description: 'Snow angel', category: 'other' },
+];

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Teams MCP Server entry point.
+ *
+ * This MCP server enables AI assistants to search Microsoft Teams
+ * messages using browser automation.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Teams MCP Server entry point.
+ *
+ * This MCP server enables AI assistants to search Microsoft Teams
+ * messages using browser automation.
+ */
+import { runServer } from './server.js';
+runServer().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/research/auth-research.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Research script to understand Teams authentication redirect behaviour.
+ *
+ * This script observes:
+ * 1. What happens when navigating to Teams WITH a valid session
+ * 2. What happens when navigating to Teams WITHOUT a session
+ *
+ * Goal: Understand the fastest way to detect if we're authenticated.
+ */
+export {};

package/dist/research/auth-research.js

@@ -0,0 +1,175 @@
+/**
+ * Research script to understand Teams authentication redirect behaviour.
+ *
+ * This script observes:
+ * 1. What happens when navigating to Teams WITH a valid session
+ * 2. What happens when navigating to Teams WITHOUT a session
+ *
+ * Goal: Understand the fastest way to detect if we're authenticated.
+ */
+import { chromium } from 'playwright';
+import { hasSessionState } from '../auth/session-store.js';
+const TEAMS_URL = 'https://teams.microsoft.com';
+async function observeNavigation(page, scenario, startTime) {
+    const events = [];
+    const log = (type, url, extra) => {
+        const now = Date.now();
+        const event = {
+            timestamp: now,
+            elapsed: now - startTime,
+            type,
+            url,
+            ...extra,
+        };
+        events.push(event);
+        console.log(`  [${event.elapsed}ms] ${type}: ${url}${extra?.status ? ` (${extra.status})` : ''}${extra?.note ? ` - ${extra.note}` : ''}`);
+    };
+    // Track all frame navigations
+    page.on('framenavigated', (frame) => {
+        if (frame === page.mainFrame()) {
+            const url = frame.url();
+            const isLogin = url.includes('login.microsoftonline.com') ||
+                url.includes('login.live.com') ||
+                url.includes('login.microsoft.com');
+            const isTeams = url.includes('teams.microsoft.com') ||
+                url.includes('teams.microsoft.us');
+            log('navigation', url, {
+                note: isLogin ? 'LOGIN PAGE' : isTeams ? 'TEAMS' : undefined
+            });
+        }
+    });
+    // Track responses (especially redirects)
+    page.on('response', (response) => {
+        const url = response.url();
+        const status = response.status();
+        // Only log main document responses and redirects
+        if (response.request().resourceType() === 'document' ||
+            (status >= 300 && status < 400)) {
+            log('response', url, {
+                status,
+                note: status >= 300 && status < 400 ? 'REDIRECT' : undefined
+            });
+        }
+    });
+    return events;
+}
+async function runScenario(browser, scenario, useSession) {
+    console.log(`\n${'='.repeat(60)}`);
+    console.log(`SCENARIO: ${scenario}`);
+    console.log(`Session: ${useSession ? 'WITH existing session' : 'NO session (cleared)'}`);
+    console.log('='.repeat(60));
+    let context;
+    if (useSession && hasSessionState()) {
+        console.log('Loading existing session state...');
+        // Handle encrypted session
+        try {
+            const { readSessionState } = await import('../auth/session-store.js');
+            const state = readSessionState();
+            if (state) {
+                context = await browser.newContext({
+                    storageState: state,
+                    viewport: { width: 1280, height: 800 },
+                });
+            }
+            else {
+                throw new Error('Could not read session');
+            }
+        }
+        catch {
+            console.log('Could not load session, using fresh context');
+            context = await browser.newContext({
+                viewport: { width: 1280, height: 800 },
+            });
+        }
+    }
+    else {
+        console.log('Using fresh context (no session)...');
+        context = await browser.newContext({
+            viewport: { width: 1280, height: 800 },
+        });
+    }
+    const page = await context.newPage();
+    const startTime = Date.now();
+    console.log(`\nNavigating to ${TEAMS_URL}...`);
+    console.log('Watching for navigations and redirects:\n');
+    const events = await observeNavigation(page, scenario, startTime);
+    try {
+        // Navigate and wait for initial load
+        await page.goto(TEAMS_URL, {
+            waitUntil: 'domcontentloaded',
+            timeout: 30000,
+        });
+        const afterGoto = Date.now();
+        console.log(`\n  [${afterGoto - startTime}ms] goto() completed (domcontentloaded)`);
+        // Wait a bit more to see if any late redirects happen
+        console.log('\n  Waiting 10 seconds to observe any delayed redirects...\n');
+        for (let i = 1; i <= 10; i++) {
+            await page.waitForTimeout(1000);
+            const currentUrl = page.url();
+            const isLogin = currentUrl.includes('login.microsoftonline.com') ||
+                currentUrl.includes('login.live.com') ||
+                currentUrl.includes('login.microsoft.com');
+            const isTeams = currentUrl.includes('teams.microsoft.com') ||
+                currentUrl.includes('teams.microsoft.us');
+            console.log(`  [${Date.now() - startTime}ms] Check ${i}: ${isLogin ? 'ON LOGIN' : isTeams ? 'ON TEAMS' : 'OTHER'} - ${currentUrl.substring(0, 80)}...`);
+            // If we're on login page, we know we're not authenticated
+            if (isLogin) {
+                console.log('\n  ✓ Detected redirect to login page - NOT authenticated');
+                break;
+            }
+        }
+        const finalUrl = page.url();
+        const duration = Date.now() - startTime;
+        console.log(`\n${'─'.repeat(60)}`);
+        console.log(`RESULT for "${scenario}":`);
+        console.log(`  Final URL: ${finalUrl}`);
+        console.log(`  Total duration: ${duration}ms`);
+        console.log(`  Navigation events: ${events.length}`);
+        const isOnLogin = finalUrl.includes('login.microsoftonline.com') ||
+            finalUrl.includes('login.live.com') ||
+            finalUrl.includes('login.microsoft.com');
+        const isOnTeams = finalUrl.includes('teams.microsoft.com') ||
+            finalUrl.includes('teams.microsoft.us');
+        console.log(`  Authenticated: ${isOnTeams && !isOnLogin ? 'YES (on Teams)' : 'NO (on login page)'}`);
+        return { events, finalUrl, duration };
+    }
+    finally {
+        await context.close();
+    }
+}
+async function main() {
+    console.log('🔬 Teams Authentication Research');
+    console.log('================================\n');
+    console.log('This script observes redirect behaviour during Teams navigation.\n');
+    const browser = await chromium.launch({
+        headless: false, // Visible so we can see what's happening
+    });
+    try {
+        // Scenario 1: With existing session (if available)
+        if (hasSessionState()) {
+            await runScenario(browser, 'WITH SESSION', true);
+        }
+        else {
+            console.log('\n⚠️  No existing session found. Run `npm run cli -- login` first to create one.');
+            console.log('   Skipping "WITH SESSION" scenario.\n');
+        }
+        // Scenario 2: Without session (cleared context)
+        await runScenario(browser, 'WITHOUT SESSION', false);
+        console.log('\n\n' + '='.repeat(60));
+        console.log('SUMMARY');
+        console.log('='.repeat(60));
+        console.log(`
+Key observations to look for:
+1. How quickly does the redirect to login.microsoftonline.com happen?
+2. Does the redirect happen BEFORE or AFTER domcontentloaded?
+3. Are there any intermediate URLs?
+4. What HTTP status codes are used for redirects?
+
+Based on this, we can tune LOGIN_REDIRECT_TIMEOUT_MS in auth.ts
+`);
+    }
+    finally {
+        await browser.close();
+    }
+}
+main().catch(console.error);

package/dist/research/explore.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Research script to explore Teams web app behaviour.
+ *
+ * This script:
+ * 1. Launches a browser with persistent context
+ * 2. Navigates to Teams and handles authentication
+ * 3. Monitors network requests to discover API endpoints
+ * 4. Allows manual interaction to trigger searches
+ * 5. Logs discovered endpoints and data structures
+ */
+export {};