@jbctechsolutions/mcp-office365 2.5.1

package/dist/graph/repository.js

@@ -0,0 +1,2999 @@
+/**
+ * Copyright (c) 2026 JBC Tech Solutions, LLC
+ * Licensed under the MIT License. See LICENSE file in the project root.
+ */
+import { GraphClient } from './client/index.js';
+import { mapMailFolderToRow, mapCalendarToFolderRow, mapMessageToEmailRow, mapEventToEventRow, mapContactToContactRow, mapTaskToTaskRow, hashStringToNumber, } from './mappers/index.js';
+import { downloadAttachment, getDownloadDir } from './attachments.js';
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Repository implementation using Microsoft Graph API.
+ *
+ * Provides read-only access to Outlook data via the Graph API.
+ */
+export class GraphRepository {
+    client;
+    deltaLinks = new Map();
+    idCache = {
+        folders: new Map(),
+        messages: new Map(),
+        conversations: new Map(),
+        events: new Map(),
+        contacts: new Map(),
+        tasks: new Map(),
+        taskLists: new Map(),
+        attachments: new Map(),
+        rules: new Map(),
+        contactFolders: new Map(),
+        categories: new Map(),
+        focusedOverrides: new Map(),
+        calendarGroups: new Map(),
+        calendars: new Map(),
+        calendarPermissions: new Map(),
+        teams: new Map(),
+        channels: new Map(),
+        channelMessages: new Map(),
+        chats: new Map(),
+        chatMessages: new Map(),
+        checklistItems: new Map(),
+        linkedResources: new Map(),
+        taskAttachments: new Map(),
+        plans: new Map(),
+        plannerBuckets: new Map(),
+        plannerTasks: new Map(),
+        plannerTaskDetails: new Map(),
+        onlineMeetings: new Map(),
+        recordings: new Map(),
+        transcripts: new Map(),
+        driveItems: new Map(),
+        sites: new Map(),
+        documentLibraries: new Map(),
+        libraryDriveItems: new Map(),
+    };
+    constructor(deviceCodeCallback) {
+        this.client = new GraphClient(deviceCodeCallback);
+    }
+    // ===========================================================================
+    // Folders
+    // ===========================================================================
+    listFolders() {
+        // Note: Graph API is async, but IRepository interface is sync
+        // We need to use a sync wrapper or change the interface
+        // For now, we'll throw and require the async version
+        throw new Error('Use listFoldersAsync() for Graph repository');
+    }
+    async listFoldersAsync() {
+        const folders = await this.client.listMailFolders();
+        // Update ID cache
+        for (const folder of folders) {
+            if (folder.id != null) {
+                const numericId = hashStringToNumber(folder.id);
+                this.idCache.folders.set(numericId, folder.id);
+            }
+        }
+        return folders.map(mapMailFolderToRow);
+    }
+    getFolder(_id) {
+        throw new Error('Use getFolderAsync() for Graph repository');
+    }
+    async getFolderAsync(id) {
+        const graphId = this.idCache.folders.get(id);
+        if (graphId == null) {
+            // Try to find it by listing all folders
+            await this.listFoldersAsync();
+            const refreshedGraphId = this.idCache.folders.get(id);
+            if (refreshedGraphId == null) {
+                return undefined;
+            }
+            const folder = await this.client.getMailFolder(refreshedGraphId);
+            return folder != null ? mapMailFolderToRow(folder) : undefined;
+        }
+        const folder = await this.client.getMailFolder(graphId);
+        return folder != null ? mapMailFolderToRow(folder) : undefined;
+    }
+    // ===========================================================================
+    // Emails
+    // ===========================================================================
+    listEmails(_folderId, _limit, _offset) {
+        throw new Error('Use listEmailsAsync() for Graph repository');
+    }
+    async listEmailsAsync(folderId, limit, offset) {
+        const graphFolderId = this.idCache.folders.get(folderId);
+        if (graphFolderId == null) {
+            // Refresh folder cache
+            await this.listFoldersAsync();
+            const refreshedId = this.idCache.folders.get(folderId);
+            if (refreshedId == null) {
+                return [];
+            }
+            return this.listEmailsWithGraphId(refreshedId, limit, offset);
+        }
+        return this.listEmailsWithGraphId(graphFolderId, limit, offset);
+    }
+    async listEmailsWithGraphId(folderId, limit, offset) {
+        const messages = await this.client.listMessages(folderId, limit, offset);
+        // Update ID cache
+        for (const message of messages) {
+            if (message.id != null) {
+                const numericId = hashStringToNumber(message.id);
+                this.idCache.messages.set(numericId, message.id);
+            }
+            if (message.conversationId != null) {
+                this.idCache.conversations.set(hashStringToNumber(message.conversationId), message.conversationId);
+            }
+        }
+        return messages.map((m) => mapMessageToEmailRow(m, folderId));
+    }
+    listUnreadEmails(_folderId, _limit, _offset) {
+        throw new Error('Use listUnreadEmailsAsync() for Graph repository');
+    }
+    async listUnreadEmailsAsync(folderId, limit, offset) {
+        const graphFolderId = this.idCache.folders.get(folderId);
+        if (graphFolderId == null) {
+            await this.listFoldersAsync();
+            const refreshedId = this.idCache.folders.get(folderId);
+            if (refreshedId == null) {
+                return [];
+            }
+            return this.listUnreadEmailsWithGraphId(refreshedId, limit, offset);
+        }
+        return this.listUnreadEmailsWithGraphId(graphFolderId, limit, offset);
+    }
+    async listUnreadEmailsWithGraphId(folderId, limit, offset) {
+        const messages = await this.client.listUnreadMessages(folderId, limit, offset);
+        for (const message of messages) {
+            if (message.id != null) {
+                const numericId = hashStringToNumber(message.id);
+                this.idCache.messages.set(numericId, message.id);
+            }
+            if (message.conversationId != null) {
+                this.idCache.conversations.set(hashStringToNumber(message.conversationId), message.conversationId);
+            }
+        }
+        return messages.map((m) => mapMessageToEmailRow(m, folderId));
+    }
+    searchEmails(_query, _limit) {
+        throw new Error('Use searchEmailsAsync() for Graph repository');
+    }
+    async searchEmailsAsync(query, limit) {
+        const messages = await this.client.searchMessages(query, limit);
+        for (const message of messages) {
+            if (message.id != null) {
+                const numericId = hashStringToNumber(message.id);
+                this.idCache.messages.set(numericId, message.id);
+            }
+            if (message.conversationId != null) {
+                this.idCache.conversations.set(hashStringToNumber(message.conversationId), message.conversationId);
+            }
+        }
+        return messages.map((m) => mapMessageToEmailRow(m));
+    }
+    searchEmailsInFolder(_folderId, _query, _limit) {
+        throw new Error('Use searchEmailsInFolderAsync() for Graph repository');
+    }
+    async searchEmailsInFolderAsync(folderId, query, limit) {
+        const graphFolderId = this.idCache.folders.get(folderId);
+        if (graphFolderId == null) {
+            await this.listFoldersAsync();
+            const refreshedId = this.idCache.folders.get(folderId);
+            if (refreshedId == null) {
+                return [];
+            }
+            return this.searchEmailsInFolderWithGraphId(refreshedId, query, limit);
+        }
+        return this.searchEmailsInFolderWithGraphId(graphFolderId, query, limit);
+    }
+    async searchEmailsInFolderWithGraphId(folderId, query, limit) {
+        const messages = await this.client.searchMessagesInFolder(folderId, query, limit);
+        for (const message of messages) {
+            if (message.id != null) {
+                const numericId = hashStringToNumber(message.id);
+                this.idCache.messages.set(numericId, message.id);
+            }
+            if (message.conversationId != null) {
+                this.idCache.conversations.set(hashStringToNumber(message.conversationId), message.conversationId);
+            }
+        }
+        return messages.map((m) => mapMessageToEmailRow(m, folderId));
+    }
+    /**
+     * Advanced search using raw KQL query syntax.
+     */
+    async searchEmailsAdvancedAsync(query, limit) {
+        const messages = await this.client.searchMessagesKql(query, limit);
+        for (const msg of messages) {
+            if (msg.id != null) {
+                this.idCache.messages.set(hashStringToNumber(msg.id), msg.id);
+            }
+            if (msg.conversationId != null) {
+                this.idCache.conversations.set(hashStringToNumber(msg.conversationId), msg.conversationId);
+            }
+        }
+        return messages.map((m) => mapMessageToEmailRow(m));
+    }
+    /**
+     * Advanced search in a specific folder using raw KQL query syntax.
+     */
+    async searchEmailsAdvancedInFolderAsync(folderId, query, limit) {
+        const graphFolderId = this.idCache.folders.get(folderId);
+        if (graphFolderId == null) {
+            throw new Error(`Folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        }
+        const messages = await this.client.searchMessagesKqlInFolder(graphFolderId, query, limit);
+        for (const msg of messages) {
+            if (msg.id != null) {
+                this.idCache.messages.set(hashStringToNumber(msg.id), msg.id);
+            }
+            if (msg.conversationId != null) {
+                this.idCache.conversations.set(hashStringToNumber(msg.conversationId), msg.conversationId);
+            }
+        }
+        return messages.map((m) => mapMessageToEmailRow(m));
+    }
+    async checkNewEmailsAsync(folderId) {
+        const graphFolderId = this.idCache.folders.get(folderId);
+        if (graphFolderId == null)
+            throw new Error(`Folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const existingDeltaLink = this.deltaLinks.get(folderId);
+        const isInitialSync = existingDeltaLink == null;
+        const { messages, deltaLink } = await this.client.getMessagesDelta(graphFolderId, existingDeltaLink);
+        if (deltaLink) {
+            this.deltaLinks.set(folderId, deltaLink);
+        }
+        for (const msg of messages) {
+            if (msg.id != null) {
+                this.idCache.messages.set(hashStringToNumber(msg.id), msg.id);
+            }
+            if (msg.conversationId != null) {
+                this.idCache.conversations.set(hashStringToNumber(msg.conversationId), msg.conversationId);
+            }
+        }
+        const activeMessages = messages.filter((m) => m['@removed'] == null);
+        return {
+            emails: activeMessages.map((m) => mapMessageToEmailRow(m)),
+            isInitialSync,
+        };
+    }
+    getEmail(_id) {
+        throw new Error('Use getEmailAsync() for Graph repository');
+    }
+    /**
+     * Populates the message ID cache by listing messages from mail folders.
+     * Used as a fallback when getEmailAsync is called with an ID not yet in cache
+     * (e.g. after server restart or when list_emails/search_emails wasn't called first).
+     */
+    async refreshMessageCacheForGetEmail(targetId) {
+        let folders;
+        try {
+            folders = await this.listFoldersAsync();
+        }
+        catch {
+            return false;
+        }
+        if (folders.length === 0)
+            return false;
+        const MESSAGE_LIMIT_PER_FOLDER = 100;
+        const MAX_FOLDERS_TO_SCAN = 15;
+        for (let i = 0; i < Math.min(folders.length, MAX_FOLDERS_TO_SCAN); i++) {
+            const folder = folders[i];
+            const graphFolderId = this.idCache.folders.get(folder.id);
+            if (graphFolderId == null)
+                continue;
+            let messages;
+            try {
+                messages = await this.client.listMessages(graphFolderId, MESSAGE_LIMIT_PER_FOLDER, 0);
+            }
+            catch {
+                continue;
+            }
+            if (!Array.isArray(messages))
+                continue;
+            for (const message of messages) {
+                if (message.id != null) {
+                    const numericId = hashStringToNumber(message.id);
+                    this.idCache.messages.set(numericId, message.id);
+                    if (numericId === targetId)
+                        return true;
+                }
+                if (message.conversationId != null) {
+                    this.idCache.conversations.set(hashStringToNumber(message.conversationId), message.conversationId);
+                }
+            }
+        }
+        return this.idCache.messages.has(targetId);
+    }
+    async getEmailAsync(id) {
+        let graphId = this.idCache.messages.get(id);
+        if (graphId == null) {
+            const found = await this.refreshMessageCacheForGetEmail(id);
+            if (found)
+                graphId = this.idCache.messages.get(id) ?? undefined;
+        }
+        if (graphId == null) {
+            return undefined;
+        }
+        const message = await this.client.getMessage(graphId);
+        return message != null ? mapMessageToEmailRow(message) : undefined;
+    }
+    getUnreadCount() {
+        throw new Error('Use getUnreadCountAsync() for Graph repository');
+    }
+    async getUnreadCountAsync() {
+        const folders = await this.client.listMailFolders();
+        return folders.reduce((sum, f) => sum + (f.unreadItemCount ?? 0), 0);
+    }
+    getUnreadCountByFolder(_folderId) {
+        throw new Error('Use getUnreadCountByFolderAsync() for Graph repository');
+    }
+    async getUnreadCountByFolderAsync(folderId) {
+        const graphId = this.idCache.folders.get(folderId);
+        if (graphId == null) {
+            await this.listFoldersAsync();
+            const refreshedId = this.idCache.folders.get(folderId);
+            if (refreshedId == null) {
+                return 0;
+            }
+            const folder = await this.client.getMailFolder(refreshedId);
+            return folder?.unreadItemCount ?? 0;
+        }
+        const folder = await this.client.getMailFolder(graphId);
+        return folder?.unreadItemCount ?? 0;
+    }
+    // ===========================================================================
+    // Conversation / Thread
+    // ===========================================================================
+    /**
+     * Lists all messages in a conversation thread.
+     *
+     * Looks up the message to get its conversationId, resolves the Graph string
+     * conversationId from cache, then queries for all messages with that ID.
+     */
+    async listConversationAsync(messageId, limit) {
+        const email = await this.getEmailAsync(messageId);
+        if (email == null)
+            throw new Error(`Message ID ${messageId} not found`);
+        if (email.conversationId == null)
+            throw new Error('Message has no conversation ID');
+        const graphConversationId = this.idCache.conversations.get(email.conversationId);
+        if (graphConversationId == null)
+            throw new Error('Conversation ID not found in cache. Try fetching the email first to populate the cache.');
+        const messages = await this.client.listConversationMessages(graphConversationId, limit);
+        for (const msg of messages) {
+            if (msg.id != null) {
+                this.idCache.messages.set(hashStringToNumber(msg.id), msg.id);
+            }
+            if (msg.conversationId != null) {
+                this.idCache.conversations.set(hashStringToNumber(msg.conversationId), msg.conversationId);
+            }
+        }
+        return messages.map((m) => mapMessageToEmailRow(m));
+    }
+    // ===========================================================================
+    // Calendar
+    // ===========================================================================
+    listCalendars() {
+        throw new Error('Use listCalendarsAsync() for Graph repository');
+    }
+    async listCalendarsAsync() {
+        const calendars = await this.client.listCalendars();
+        for (const calendar of calendars) {
+            if (calendar.id != null) {
+                const numericId = hashStringToNumber(calendar.id);
+                this.idCache.folders.set(numericId, calendar.id);
+                this.idCache.calendars.set(numericId, calendar.id);
+            }
+        }
+        return calendars.map(mapCalendarToFolderRow);
+    }
+    listEvents(_limit) {
+        throw new Error('Use listEventsAsync() for Graph repository');
+    }
+    async listEventsAsync(limit) {
+        const events = await this.client.listEvents(limit);
+        for (const event of events) {
+            if (event.id != null) {
+                const numericId = hashStringToNumber(event.id);
+                this.idCache.events.set(numericId, event.id);
+            }
+        }
+        return events.map((e) => mapEventToEventRow(e));
+    }
+    listEventsByFolder(_folderId, _limit) {
+        throw new Error('Use listEventsByFolderAsync() for Graph repository');
+    }
+    async listEventsByFolderAsync(folderId, limit) {
+        const graphCalendarId = this.idCache.folders.get(folderId);
+        if (graphCalendarId == null) {
+            return this.listEventsAsync(limit);
+        }
+        const events = await this.client.listEvents(limit, graphCalendarId);
+        for (const event of events) {
+            if (event.id != null) {
+                const numericId = hashStringToNumber(event.id);
+                this.idCache.events.set(numericId, event.id);
+            }
+        }
+        return events.map((e) => mapEventToEventRow(e, graphCalendarId));
+    }
+    searchEvents(_query, _startDate, _endDate, _limit) {
+        throw new Error('Use searchEventsAsync() for Graph repository');
+    }
+    async searchEventsAsync(query, startDate, endDate, limit) {
+        // Graph doesn't have direct event search, so we filter client-side
+        const start = startDate != null ? new Date(startDate) : undefined;
+        const end = endDate != null ? new Date(endDate) : undefined;
+        const events = await this.client.listEvents(1000, undefined, start, end);
+        for (const event of events) {
+            if (event.id != null) {
+                const numericId = hashStringToNumber(event.id);
+                this.idCache.events.set(numericId, event.id);
+            }
+        }
+        let rows = events.map((e) => mapEventToEventRow(e));
+        // Filter by title client-side if query provided
+        if (query != null) {
+            const queryLower = query.toLowerCase();
+            rows = rows.filter((row) => {
+                // EventRow doesn't have title, so we need to check the original event
+                const originalEvent = events.find((e) => e.id != null && hashStringToNumber(e.id) === row.id);
+                const subject = originalEvent?.subject?.toLowerCase() ?? '';
+                return subject.includes(queryLower);
+            });
+        }
+        return rows.slice(0, limit);
+    }
+    listEventsByDateRange(_startDate, _endDate, _limit) {
+        throw new Error('Use listEventsByDateRangeAsync() for Graph repository');
+    }
+    async listEventsByDateRangeAsync(startDate, endDate, limit) {
+        const start = new Date(startDate * 1000);
+        const end = new Date(endDate * 1000);
+        const events = await this.client.listEvents(limit, undefined, start, end);
+        for (const event of events) {
+            if (event.id != null) {
+                const numericId = hashStringToNumber(event.id);
+                this.idCache.events.set(numericId, event.id);
+            }
+        }
+        return events.map((e) => mapEventToEventRow(e));
+    }
+    getEvent(_id) {
+        throw new Error('Use getEventAsync() for Graph repository');
+    }
+    async getEventAsync(id) {
+        const graphId = this.idCache.events.get(id);
+        if (graphId == null) {
+            return undefined;
+        }
+        const event = await this.client.getEvent(graphId);
+        return event != null ? mapEventToEventRow(event) : undefined;
+    }
+    async listEventInstancesAsync(eventId, startDate, endDate) {
+        const graphId = this.idCache.events.get(eventId);
+        if (graphId == null) {
+            throw new Error(`Event ID ${eventId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        }
+        const instances = await this.client.listEventInstances(graphId, startDate, endDate);
+        for (const inst of instances) {
+            if (inst.id != null) {
+                this.idCache.events.set(hashStringToNumber(inst.id), inst.id);
+            }
+        }
+        return instances.map((e) => mapEventToEventRow(e));
+    }
+    // ===========================================================================
+    // Contacts
+    // ===========================================================================
+    listContacts(_limit, _offset) {
+        throw new Error('Use listContactsAsync() for Graph repository');
+    }
+    async listContactsAsync(limit, offset) {
+        const contacts = await this.client.listContacts(limit, offset);
+        for (const contact of contacts) {
+            if (contact.id != null) {
+                const numericId = hashStringToNumber(contact.id);
+                this.idCache.contacts.set(numericId, contact.id);
+            }
+        }
+        return contacts.map(mapContactToContactRow);
+    }
+    searchContacts(_query, _limit) {
+        throw new Error('Use searchContactsAsync() for Graph repository');
+    }
+    async searchContactsAsync(query, limit) {
+        const contacts = await this.client.searchContacts(query, limit);
+        for (const contact of contacts) {
+            if (contact.id != null) {
+                const numericId = hashStringToNumber(contact.id);
+                this.idCache.contacts.set(numericId, contact.id);
+            }
+        }
+        return contacts.map(mapContactToContactRow);
+    }
+    getContact(_id) {
+        throw new Error('Use getContactAsync() for Graph repository');
+    }
+    async getContactAsync(id) {
+        const graphId = this.idCache.contacts.get(id);
+        if (graphId == null) {
+            return undefined;
+        }
+        const contact = await this.client.getContact(graphId);
+        return contact != null ? mapContactToContactRow(contact) : undefined;
+    }
+    // ===========================================================================
+    // Contact Folders
+    // ===========================================================================
+    async listContactFoldersAsync() {
+        const folders = await this.client.listContactFolders();
+        return folders.map((folder) => {
+            const graphId = folder.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.contactFolders.set(numericId, graphId);
+            return {
+                id: numericId,
+                name: folder.displayName ?? '',
+                parentFolderId: folder.parentFolderId ?? null,
+            };
+        });
+    }
+    async createContactFolderAsync(name) {
+        const created = await this.client.createContactFolder(name);
+        const graphId = created.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.contactFolders.set(numericId, graphId);
+        return numericId;
+    }
+    async deleteContactFolderAsync(folderId) {
+        const graphId = this.idCache.contactFolders.get(folderId);
+        if (graphId == null)
+            throw new Error(`Contact folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.deleteContactFolder(graphId);
+        this.idCache.contactFolders.delete(folderId);
+    }
+    async listContactsInFolderAsync(folderId, limit = 100) {
+        const graphId = this.idCache.contactFolders.get(folderId);
+        if (graphId == null)
+            throw new Error(`Contact folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const contacts = await this.client.listContactsInFolder(graphId, limit);
+        return contacts.map((c) => {
+            if (c.id != null) {
+                this.idCache.contacts.set(hashStringToNumber(c.id), c.id);
+            }
+            return mapContactToContactRow(c);
+        });
+    }
+    // ===========================================================================
+    // Contact Photos
+    // ===========================================================================
+    async getContactPhotoAsync(contactId) {
+        const graphId = this.idCache.contacts.get(contactId);
+        if (graphId == null)
+            throw new Error(`Contact ID ${contactId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const photoData = await this.client.getContactPhoto(graphId);
+        const downloadDir = getDownloadDir();
+        const filePath = path.join(downloadDir, `contact-${contactId}-photo.jpg`);
+        fs.writeFileSync(filePath, Buffer.from(photoData));
+        return { filePath, contentType: 'image/jpeg' };
+    }
+    async setContactPhotoAsync(contactId, filePath) {
+        const graphId = this.idCache.contacts.get(contactId);
+        if (graphId == null)
+            throw new Error(`Contact ID ${contactId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const photoData = fs.readFileSync(filePath);
+        const ext = path.extname(filePath).toLowerCase();
+        const contentType = ext === '.png' ? 'image/png' : 'image/jpeg';
+        await this.client.setContactPhoto(graphId, photoData, contentType);
+    }
+    // ===========================================================================
+    // Tasks
+    // ===========================================================================
+    listTasks(_limit, _offset) {
+        throw new Error('Use listTasksAsync() for Graph repository');
+    }
+    async listTasksAsync(limit, offset) {
+        const tasks = await this.client.listAllTasks(limit, offset, true);
+        for (const task of tasks) {
+            if (task.id != null && task.taskListId != null) {
+                const numericId = hashStringToNumber(task.id);
+                this.idCache.tasks.set(numericId, { taskListId: task.taskListId, taskId: task.id });
+                const listNumericId = hashStringToNumber(task.taskListId);
+                this.idCache.taskLists.set(listNumericId, task.taskListId);
+            }
+        }
+        return tasks.map(mapTaskToTaskRow);
+    }
+    listIncompleteTasks(_limit, _offset) {
+        throw new Error('Use listIncompleteTasksAsync() for Graph repository');
+    }
+    async listIncompleteTasksAsync(limit, offset) {
+        const tasks = await this.client.listAllTasks(limit, offset, false);
+        for (const task of tasks) {
+            if (task.id != null && task.taskListId != null) {
+                const numericId = hashStringToNumber(task.id);
+                this.idCache.tasks.set(numericId, { taskListId: task.taskListId, taskId: task.id });
+                const listNumericId = hashStringToNumber(task.taskListId);
+                this.idCache.taskLists.set(listNumericId, task.taskListId);
+            }
+        }
+        return tasks.map(mapTaskToTaskRow);
+    }
+    searchTasks(_query, _limit) {
+        throw new Error('Use searchTasksAsync() for Graph repository');
+    }
+    async searchTasksAsync(query, limit) {
+        const tasks = await this.client.searchTasks(query, limit);
+        for (const task of tasks) {
+            if (task.id != null && task.taskListId != null) {
+                const numericId = hashStringToNumber(task.id);
+                this.idCache.tasks.set(numericId, { taskListId: task.taskListId, taskId: task.id });
+            }
+        }
+        return tasks.map(mapTaskToTaskRow);
+    }
+    getTask(_id) {
+        throw new Error('Use getTaskAsync() for Graph repository');
+    }
+    async getTaskAsync(id) {
+        const taskInfo = this.idCache.tasks.get(id);
+        if (taskInfo == null) {
+            return undefined;
+        }
+        const task = await this.client.getTask(taskInfo.taskListId, taskInfo.taskId);
+        if (task == null) {
+            return undefined;
+        }
+        return mapTaskToTaskRow({ ...task, taskListId: taskInfo.taskListId });
+    }
+    async listTaskListsAsync() {
+        const lists = await this.client.listTaskLists();
+        return lists.map((list) => {
+            const graphId = list.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.taskLists.set(numericId, graphId);
+            return {
+                id: numericId,
+                name: list.displayName ?? '',
+                isDefault: list.wellknownListName === 'defaultList',
+            };
+        });
+    }
+    // ===========================================================================
+    // Notes (NOT SUPPORTED)
+    // ===========================================================================
+    listNotes(_limit, _offset) {
+        // Microsoft Graph does not have an API for Outlook Notes
+        return [];
+    }
+    listNotesAsync(_limit, _offset) {
+        // Microsoft Graph does not have an API for Outlook Notes
+        return Promise.resolve([]);
+    }
+    getNote(_id) {
+        // Microsoft Graph does not have an API for Outlook Notes
+        return undefined;
+    }
+    getNoteAsync(_id) {
+        // Microsoft Graph does not have an API for Outlook Notes
+        return Promise.resolve(undefined);
+    }
+    // ===========================================================================
+    // Utility Methods
+    // ===========================================================================
+    /**
+     * Gets the Graph client instance for direct access if needed.
+     */
+    getClient() {
+        return this.client;
+    }
+    /**
+     * Returns the Graph client (satisfies IMailSendRepository).
+     */
+    getGraphClient() {
+        return this.client;
+    }
+    /**
+     * Returns the Graph string ID for a cached draft numeric ID (satisfies IMailSendRepository).
+     */
+    getGraphIdForDraft(draftId) {
+        return this.idCache.messages.get(draftId);
+    }
+    /**
+     * Gets the Graph string ID from a numeric ID.
+     */
+    getGraphId(type, numericId) {
+        switch (type) {
+            case 'folder':
+                return this.idCache.folders.get(numericId);
+            case 'message':
+                return this.idCache.messages.get(numericId);
+            case 'event':
+                return this.idCache.events.get(numericId);
+            case 'contact':
+                return this.idCache.contacts.get(numericId);
+        }
+    }
+    /**
+     * Gets task info from a numeric ID.
+     */
+    getTaskInfo(numericId) {
+        return this.idCache.tasks.get(numericId);
+    }
+    /**
+     * Gets the Graph string ID for a task list from a numeric ID.
+     */
+    getTaskListGraphId(numericId) {
+        return this.idCache.taskLists.get(numericId);
+    }
+    // ===========================================================================
+    // Write Operations (Async)
+    // ===========================================================================
+    // Sync versions throw — use async versions from index.ts handler
+    moveEmail(_emailId, _destinationFolderId) {
+        throw new Error('Use moveEmailAsync() for Graph repository');
+    }
+    deleteEmail(_emailId) {
+        throw new Error('Use deleteEmailAsync() for Graph repository');
+    }
+    archiveEmail(_emailId) {
+        throw new Error('Use archiveEmailAsync() for Graph repository');
+    }
+    junkEmail(_emailId) {
+        throw new Error('Use junkEmailAsync() for Graph repository');
+    }
+    markEmailRead(_emailId, _isRead) {
+        throw new Error('Use markEmailReadAsync() for Graph repository');
+    }
+    setEmailFlag(_emailId, _flagStatus) {
+        throw new Error('Use setEmailFlagAsync() for Graph repository');
+    }
+    setEmailCategories(_emailId, _categories) {
+        throw new Error('Use setEmailCategoriesAsync() for Graph repository');
+    }
+    setEmailImportance(_emailId, _importance) {
+        throw new Error('Use setEmailImportanceAsync() for Graph repository');
+    }
+    createFolder(_name, _parentFolderId) {
+        throw new Error('Use createFolderAsync() for Graph repository');
+    }
+    deleteFolder(_folderId) {
+        throw new Error('Use deleteFolderAsync() for Graph repository');
+    }
+    renameFolder(_folderId, _newName) {
+        throw new Error('Use renameFolderAsync() for Graph repository');
+    }
+    moveFolder(_folderId, _destinationParentId) {
+        throw new Error('Use moveFolderAsync() for Graph repository');
+    }
+    emptyFolder(_folderId) {
+        throw new Error('Use emptyFolderAsync() for Graph repository');
+    }
+    // Async implementations
+    async moveEmailAsync(emailId, destinationFolderId) {
+        const graphMessageId = this.idCache.messages.get(emailId);
+        const graphFolderId = this.idCache.folders.get(destinationFolderId);
+        if (graphMessageId == null)
+            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        if (graphFolderId == null)
+            throw new Error(`Folder ID ${destinationFolderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.moveMessage(graphMessageId, graphFolderId);
+    }
+    async deleteEmailAsync(emailId) {
+        const graphId = this.idCache.messages.get(emailId);
+        if (graphId == null)
+            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.deleteMessage(graphId);
+    }
+    async archiveEmailAsync(emailId) {
+        const graphId = this.idCache.messages.get(emailId);
+        if (graphId == null)
+            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.archiveMessage(graphId);
+    }
+    async junkEmailAsync(emailId) {
+        const graphId = this.idCache.messages.get(emailId);
+        if (graphId == null)
+            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.junkMessage(graphId);
+    }
+    async markEmailReadAsync(emailId, isRead) {
+        const graphId = this.idCache.messages.get(emailId);
+        if (graphId == null)
+            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.updateMessage(graphId, { isRead });
+    }
+    async setEmailFlagAsync(emailId, flagStatus) {
+        const graphId = this.idCache.messages.get(emailId);
+        if (graphId == null)
+            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const flagStatusMap = {
+            0: 'notFlagged',
+            1: 'flagged',
+            2: 'complete',
+        };
+        await this.client.updateMessage(graphId, {
+            flag: { flagStatus: flagStatusMap[flagStatus] ?? 'notFlagged' },
+        });
+    }
+    async setEmailCategoriesAsync(emailId, categories) {
+        const graphId = this.idCache.messages.get(emailId);
+        if (graphId == null)
+            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.updateMessage(graphId, { categories });
+    }
+    async setEmailImportanceAsync(emailId, importance) {
+        const graphId = this.idCache.messages.get(emailId);
+        if (graphId == null)
+            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.updateMessage(graphId, { importance });
+    }
+    async createFolderAsync(name, parentFolderId) {
+        const graphParentId = parentFolderId != null
+            ? this.idCache.folders.get(parentFolderId)
+            : undefined;
+        const folder = await this.client.createMailFolder(name, graphParentId ?? undefined);
+        // Update cache with new folder
+        if (folder.id != null) {
+            const numericId = hashStringToNumber(folder.id);
+            this.idCache.folders.set(numericId, folder.id);
+        }
+        return mapMailFolderToRow(folder);
+    }
+    async deleteFolderAsync(folderId) {
+        const graphId = this.idCache.folders.get(folderId);
+        if (graphId == null)
+            throw new Error(`Folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.deleteMailFolder(graphId);
+        this.idCache.folders.delete(folderId);
+    }
+    async renameFolderAsync(folderId, newName) {
+        const graphId = this.idCache.folders.get(folderId);
+        if (graphId == null)
+            throw new Error(`Folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.renameMailFolder(graphId, newName);
+    }
+    async moveFolderAsync(folderId, destinationParentId) {
+        const graphFolderId = this.idCache.folders.get(folderId);
+        const graphParentId = this.idCache.folders.get(destinationParentId);
+        if (graphFolderId == null)
+            throw new Error(`Folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        if (graphParentId == null)
+            throw new Error(`Parent folder ID ${destinationParentId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.moveMailFolder(graphFolderId, graphParentId);
+    }
+    async emptyFolderAsync(folderId) {
+        const graphId = this.idCache.folders.get(folderId);
+        if (graphId == null)
+            throw new Error(`Folder ID ${folderId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.emptyMailFolder(graphId);
+    }
+    // ===========================================================================
+    // Draft & Send Operations (Async)
+    // ===========================================================================
+    /**
+     * Creates a new draft message.
+     *
+     * Converts email address strings to Recipient objects, calls the Graph client,
+     * adds the returned draft to idCache.messages, and returns its numeric ID.
+     */
+    async createDraftAsync(params) {
+        const toRecipients = (params.to ?? []).map(addr => ({
+            emailAddress: { address: addr },
+        }));
+        const ccRecipients = (params.cc ?? []).map(addr => ({
+            emailAddress: { address: addr },
+        }));
+        const bccRecipients = (params.bcc ?? []).map(addr => ({
+            emailAddress: { address: addr },
+        }));
+        const draft = await this.client.createDraft({
+            subject: params.subject,
+            body: { contentType: params.bodyType, content: params.body },
+            toRecipients,
+            ccRecipients,
+            bccRecipients,
+        });
+        const graphId = draft.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.messages.set(numericId, graphId);
+        return { numericId, graphId };
+    }
+    /**
+     * Updates an existing draft message.
+     *
+     * Looks up the Graph string ID from idCache.messages, then calls the client.
+     */
+    async updateDraftAsync(draftId, updates) {
+        const graphId = this.idCache.messages.get(draftId);
+        if (graphId == null)
+            throw new Error(`Message ID ${draftId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.updateDraft(graphId, updates);
+    }
+    /**
+     * Lists draft messages.
+     *
+     * Uses the well-known 'drafts' folder name directly with the Graph API.
+     */
+    async listDraftsAsync(limit, offset) {
+        return this.listEmailsWithGraphId('drafts', limit, offset);
+    }
+    /**
+     * Sends an existing draft message.
+     *
+     * Looks up the Graph string ID from idCache.messages, then calls the client.
+     */
+    async sendDraftAsync(draftId) {
+        const graphId = this.idCache.messages.get(draftId);
+        if (graphId == null)
+            throw new Error(`Message ID ${draftId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.sendDraft(graphId);
+    }
+    /**
+     * Sends a new email directly without creating a draft first.
+     *
+     * Converts email address strings to Recipient objects and calls the client.
+     */
+    async sendMailAsync(params) {
+        const toRecipients = params.to.map(addr => ({
+            emailAddress: { address: addr },
+        }));
+        const ccRecipients = (params.cc ?? []).map(addr => ({
+            emailAddress: { address: addr },
+        }));
+        const bccRecipients = (params.bcc ?? []).map(addr => ({
+            emailAddress: { address: addr },
+        }));
+        await this.client.sendMail({
+            subject: params.subject,
+            body: { contentType: params.bodyType, content: params.body },
+            toRecipients,
+            ccRecipients,
+            bccRecipients,
+        });
+    }
+    /**
+     * Replies to a message (or replies all).
+     *
+     * Looks up the Graph string ID from idCache.messages, then calls the client.
+     */
+    async replyMessageAsync(messageId, comment, replyAll) {
+        const graphId = this.idCache.messages.get(messageId);
+        if (graphId == null)
+            throw new Error(`Message ID ${messageId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.replyMessage(graphId, comment, replyAll);
+    }
+    /**
+     * Forwards a message to specified recipients.
+     *
+     * Looks up the Graph string ID from idCache.messages, converts recipient
+     * email strings to Recipient objects, then calls the client.
+     */
+    async forwardMessageAsync(messageId, toRecipients, comment) {
+        const graphId = this.idCache.messages.get(messageId);
+        if (graphId == null)
+            throw new Error(`Message ID ${messageId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const recipients = toRecipients.map(addr => ({
+            emailAddress: { address: addr },
+        }));
+        await this.client.forwardMessage(graphId, recipients, comment);
+    }
+    // ===========================================================================
+    // Reply/Forward as Draft Operations (Async)
+    // ===========================================================================
+    /**
+     * Creates a reply (or reply-all) draft for a message.
+     *
+     * Looks up the Graph string ID from idCache.messages, creates the draft
+     * via the client, caches the new draft ID, and optionally updates the body.
+     *
+     * @returns The numeric and graph IDs of the new draft.
+     */
+    async replyAsDraftAsync(messageId, replyAll = false, comment, bodyType = 'text') {
+        const graphMessageId = this.idCache.messages.get(messageId);
+        if (graphMessageId == null)
+            throw new Error(`Message ID ${messageId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const draft = replyAll
+            ? await this.client.createReplyAllDraft(graphMessageId)
+            : await this.client.createReplyDraft(graphMessageId);
+        const graphId = draft.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.messages.set(numericId, graphId);
+        if (comment != null) {
+            await this.client.updateDraft(graphId, {
+                body: { contentType: bodyType, content: comment },
+            });
+        }
+        return { numericId, graphId };
+    }
+    /**
+     * Creates a forward draft for a message.
+     *
+     * Looks up the Graph string ID from idCache.messages, creates the draft
+     * via the client, caches the new draft ID, and optionally updates the
+     * recipients and body.
+     *
+     * @returns The numeric and graph IDs of the new draft.
+     */
+    async forwardAsDraftAsync(messageId, toRecipients, comment, bodyType = 'text') {
+        const graphMessageId = this.idCache.messages.get(messageId);
+        if (graphMessageId == null)
+            throw new Error(`Message ID ${messageId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const draft = await this.client.createForwardDraft(graphMessageId);
+        const graphId = draft.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.messages.set(numericId, graphId);
+        const updates = {};
+        if (toRecipients != null && toRecipients.length > 0) {
+            updates.toRecipients = toRecipients.map(addr => ({
+                emailAddress: { address: addr },
+            }));
+        }
+        if (comment != null) {
+            updates.body = { contentType: bodyType, content: comment };
+        }
+        if (Object.keys(updates).length > 0) {
+            await this.client.updateDraft(graphId, updates);
+        }
+        return { numericId, graphId };
+    }
+    // ---------------------------------------------------------------------------
+    // Calendar Scheduling
+    // ---------------------------------------------------------------------------
+    async getScheduleAsync(params) {
+        return await this.client.getSchedule({
+            schedules: params.emailAddresses,
+            startTime: { dateTime: params.startTime, timeZone: 'UTC' },
+            endTime: { dateTime: params.endTime, timeZone: 'UTC' },
+            availabilityViewInterval: params.availabilityViewInterval ?? 30,
+        });
+    }
+    async findMeetingTimesAsync(params) {
+        const hours = Math.floor(params.durationMinutes / 60);
+        const minutes = params.durationMinutes % 60;
+        const meetingDuration = `PT${hours}H${minutes}M`;
+        const attendees = params.attendees.map(addr => ({
+            emailAddress: { address: addr },
+            type: 'required',
+        }));
+        const request = {
+            attendees,
+            meetingDuration,
+            maxCandidates: params.maxCandidates ?? 5,
+        };
+        if (params.startTime != null && params.endTime != null) {
+            request.timeConstraint = {
+                timeslots: [{
+                        start: { dateTime: params.startTime, timeZone: 'UTC' },
+                        end: { dateTime: params.endTime, timeZone: 'UTC' },
+                    }],
+            };
+        }
+        return await this.client.findMeetingTimes(request);
+    }
+    // ===========================================================================
+    // Attachment Operations (Async)
+    // ===========================================================================
+    /**
+     * Lists attachments for a given email.
+     *
+     * Looks up the Graph message ID from idCache.messages, calls
+     * client.listAttachments, hashes each attachment ID to a numeric key,
+     * and caches it in idCache.attachments with { messageId, attachmentId }.
+     *
+     * @returns Array of attachment metadata objects.
+     */
+    async listAttachmentsAsync(emailId) {
+        const graphMessageId = this.idCache.messages.get(emailId);
+        if (graphMessageId == null)
+            throw new Error(`Message ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const attachments = await this.client.listAttachments(graphMessageId);
+        return attachments.map((att) => {
+            const attId = att.id ?? '';
+            const numericId = hashStringToNumber(attId);
+            this.idCache.attachments.set(numericId, {
+                messageId: graphMessageId,
+                attachmentId: attId,
+            });
+            return {
+                id: numericId,
+                name: att.name ?? '',
+                size: att.size ?? 0,
+                contentType: att.contentType ?? 'application/octet-stream',
+                isInline: att.isInline ?? false,
+            };
+        });
+    }
+    /**
+     * Downloads an attachment for a given email.
+     *
+     * Looks up { messageId, attachmentId } from idCache.attachments,
+     * then delegates to the downloadAttachment helper which fetches
+     * the content and writes it to disk.
+     *
+     * @returns Metadata about the downloaded file including its local path.
+     */
+    async downloadAttachmentAsync(attachmentId) {
+        const cached = this.idCache.attachments.get(attachmentId);
+        if (cached == null)
+            throw new Error(`Attachment ID ${attachmentId} not found in cache. Call list_attachments first.`);
+        return downloadAttachment(this.client, cached.messageId, cached.attachmentId);
+    }
+    // ===========================================================================
+    // Calendar Write Operations (Async)
+    // ===========================================================================
+    /**
+     * Creates a new calendar event.
+     *
+     * Builds a Graph API event object from the given params, calls
+     * client.createEvent(), adds the result to idCache.events, and
+     * returns the numeric ID.
+     */
+    async createEventAsync(params) {
+        const tz = params.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+        const graphEvent = {
+            subject: params.subject,
+            start: { dateTime: params.start, timeZone: tz },
+            end: { dateTime: params.end, timeZone: tz },
+        };
+        if (params.isAllDay === true) {
+            graphEvent.isAllDay = true;
+        }
+        if (params.location != null) {
+            graphEvent.location = { displayName: params.location };
+        }
+        if (params.body != null) {
+            graphEvent.body = {
+                contentType: params.bodyType ?? 'text',
+                content: params.body,
+            };
+        }
+        if (params.attendees != null && params.attendees.length > 0) {
+            graphEvent.attendees = params.attendees.map((a) => ({
+                emailAddress: { address: a.email, name: a.name },
+                type: a.type ?? 'required',
+            }));
+        }
+        if (params.recurrence != null) {
+            graphEvent.recurrence = params.recurrence;
+        }
+        if (params.is_online_meeting === true) {
+            graphEvent.isOnlineMeeting = true;
+            graphEvent.onlineMeetingProvider = params.online_meeting_provider ?? 'teamsForBusiness';
+        }
+        const graphCalendarId = params.calendarId != null
+            ? this.idCache.folders.get(params.calendarId)
+            : undefined;
+        const created = await this.client.createEvent(graphEvent, graphCalendarId);
+        const graphId = created.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.events.set(numericId, graphId);
+        return numericId;
+    }
+    /**
+     * Updates an existing calendar event.
+     *
+     * Looks up the Graph string ID from idCache.events, then calls
+     * client.updateEvent(). Throws if the event is not cached.
+     */
+    async updateEventAsync(eventId, updates) {
+        const graphId = this.idCache.events.get(eventId);
+        if (graphId == null)
+            throw new Error(`Event ID ${eventId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.updateEvent(graphId, updates);
+    }
+    /**
+     * Deletes a calendar event.
+     *
+     * Looks up the Graph string ID from idCache.events, calls
+     * client.deleteEvent(), and removes the entry from idCache.
+     * Throws if the event is not cached.
+     */
+    async deleteEventAsync(eventId) {
+        const graphId = this.idCache.events.get(eventId);
+        if (graphId == null)
+            throw new Error(`Event ID ${eventId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.deleteEvent(graphId);
+        this.idCache.events.delete(eventId);
+    }
+    /**
+     * Responds to a calendar event invitation.
+     *
+     * Looks up the Graph string ID from idCache.events, then calls
+     * client.respondToEvent(). Throws if the event is not cached.
+     */
+    async respondToEventAsync(eventId, response, sendResponse, comment) {
+        const graphId = this.idCache.events.get(eventId);
+        if (graphId == null)
+            throw new Error(`Event ID ${eventId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.respondToEvent(graphId, response, sendResponse, comment);
+    }
+    // ===========================================================================
+    // Contact Write Operations (Async)
+    // ===========================================================================
+    /**
+     * Creates a new contact.
+     *
+     * Maps snake_case input fields to Graph API camelCase fields, calls
+     * client.createContact(), caches the resulting ID, and returns a numeric ID.
+     */
+    async createContactAsync(params) {
+        const graphContact = {};
+        if (params.given_name != null)
+            graphContact.givenName = params.given_name;
+        if (params.surname != null)
+            graphContact.surname = params.surname;
+        if (params.email != null)
+            graphContact.emailAddresses = [{ address: params.email }];
+        if (params.phone != null)
+            graphContact.businessPhones = [params.phone];
+        if (params.mobile_phone != null)
+            graphContact.mobilePhone = params.mobile_phone;
+        if (params.company != null)
+            graphContact.companyName = params.company;
+        if (params.job_title != null)
+            graphContact.jobTitle = params.job_title;
+        // Build address only if any address field is present
+        if (params.street_address != null || params.city != null || params.state != null || params.postal_code != null || params.country != null) {
+            const address = {};
+            if (params.street_address != null)
+                address.street = params.street_address;
+            if (params.city != null)
+                address.city = params.city;
+            if (params.state != null)
+                address.state = params.state;
+            if (params.postal_code != null)
+                address.postalCode = params.postal_code;
+            if (params.country != null)
+                address.countryOrRegion = params.country;
+            graphContact.businessAddress = address;
+        }
+        const created = await this.client.createContact(graphContact);
+        const graphId = created.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.contacts.set(numericId, graphId);
+        return numericId;
+    }
+    /**
+     * Updates an existing contact.
+     *
+     * Looks up the Graph string ID from idCache.contacts, then calls
+     * client.updateContact(). Throws if the contact is not cached.
+     */
+    async updateContactAsync(contactId, updates) {
+        const graphId = this.idCache.contacts.get(contactId);
+        if (graphId == null)
+            throw new Error(`Contact ID ${contactId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.updateContact(graphId, updates);
+    }
+    /**
+     * Deletes a contact.
+     *
+     * Looks up the Graph string ID from idCache.contacts, calls
+     * client.deleteContact(), and removes the entry from idCache.
+     * Throws if the contact is not cached.
+     */
+    async deleteContactAsync(contactId) {
+        const graphId = this.idCache.contacts.get(contactId);
+        if (graphId == null)
+            throw new Error(`Contact ID ${contactId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.deleteContact(graphId);
+        this.idCache.contacts.delete(contactId);
+    }
+    // ===========================================================================
+    // Task Write Operations (Async)
+    // ===========================================================================
+    /**
+     * Creates a new task in a task list.
+     *
+     * Looks up the Graph task list ID from idCache.taskLists, builds a
+     * Graph API task object from the given params, calls client.createTask(),
+     * caches the resulting ID, and returns a numeric ID.
+     */
+    async createTaskAsync(params) {
+        const graphListId = this.idCache.taskLists.get(params.task_list_id);
+        if (graphListId == null)
+            throw new Error(`Task list ID ${params.task_list_id} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const graphTask = {
+            title: params.title,
+        };
+        if (params.body != null) {
+            graphTask.body = {
+                contentType: params.body_type ?? 'text',
+                content: params.body,
+            };
+        }
+        if (params.due_date != null) {
+            graphTask.dueDateTime = {
+                dateTime: params.due_date,
+                timeZone: 'UTC',
+            };
+        }
+        if (params.importance != null) {
+            graphTask.importance = params.importance;
+        }
+        if (params.reminder_date != null) {
+            graphTask.isReminderOn = true;
+            graphTask.reminderDateTime = {
+                dateTime: params.reminder_date,
+                timeZone: 'UTC',
+            };
+        }
+        if (params.categories != null) {
+            graphTask.categories = params.categories;
+        }
+        if (params.recurrence != null) {
+            graphTask.recurrence = {
+                pattern: {
+                    type: params.recurrence.pattern,
+                    interval: params.recurrence.interval ?? 1,
+                    ...(params.recurrence.days_of_week != null ? { daysOfWeek: params.recurrence.days_of_week } : {}),
+                    ...(params.recurrence.day_of_month != null ? { dayOfMonth: params.recurrence.day_of_month } : {}),
+                },
+                range: {
+                    type: params.recurrence.range_type,
+                    startDate: params.recurrence.start_date,
+                    ...(params.recurrence.end_date != null ? { endDate: params.recurrence.end_date } : {}),
+                    ...(params.recurrence.occurrences != null ? { numberOfOccurrences: params.recurrence.occurrences } : {}),
+                },
+            };
+        }
+        const created = await this.client.createTask(graphListId, graphTask);
+        const graphId = created.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.tasks.set(numericId, { taskListId: graphListId, taskId: graphId });
+        return numericId;
+    }
+    /**
+     * Updates an existing task.
+     *
+     * Looks up the Graph task info from idCache.tasks, then calls
+     * client.updateTask(). Throws if the task is not cached.
+     */
+    async updateTaskAsync(taskId, updates) {
+        const taskInfo = this.idCache.tasks.get(taskId);
+        if (taskInfo == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.updateTask(taskInfo.taskListId, taskInfo.taskId, updates);
+    }
+    /**
+     * Marks a task as completed.
+     *
+     * Convenience method that calls updateTaskAsync with status: 'completed'
+     * and the current time as completedDateTime.
+     */
+    async completeTaskAsync(taskId) {
+        await this.updateTaskAsync(taskId, {
+            status: 'completed',
+            completedDateTime: {
+                dateTime: new Date().toISOString(),
+                timeZone: 'UTC',
+            },
+        });
+    }
+    /**
+     * Deletes a task.
+     *
+     * Looks up the Graph task info from idCache.tasks, calls
+     * client.deleteTask(), and removes the entry from idCache.
+     * Throws if the task is not cached.
+     */
+    async deleteTaskAsync(taskId) {
+        const taskInfo = this.idCache.tasks.get(taskId);
+        if (taskInfo == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.deleteTask(taskInfo.taskListId, taskInfo.taskId);
+        this.idCache.tasks.delete(taskId);
+    }
+    /**
+     * Creates a new task list.
+     *
+     * Calls client.createTaskList(), caches the resulting ID in
+     * idCache.taskLists, and returns a numeric ID.
+     */
+    async createTaskListAsync(displayName) {
+        const created = await this.client.createTaskList(displayName);
+        const graphId = created.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.taskLists.set(numericId, graphId);
+        return numericId;
+    }
+    /**
+     * Renames a task list.
+     */
+    async renameTaskListAsync(listId, name) {
+        const graphId = this.idCache.taskLists.get(listId);
+        if (graphId == null)
+            throw new Error(`Task list ID ${listId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.updateTaskList(graphId, { displayName: name });
+    }
+    /**
+     * Deletes a task list.
+     */
+    async deleteTaskListAsync(listId) {
+        const graphId = this.idCache.taskLists.get(listId);
+        if (graphId == null)
+            throw new Error(`Task list ID ${listId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.deleteTaskList(graphId);
+        this.idCache.taskLists.delete(listId);
+    }
+    // ===========================================================================
+    // Checklist Items
+    // ===========================================================================
+    async listChecklistItemsAsync(taskId) {
+        const taskInfo = this.idCache.tasks.get(taskId);
+        if (taskInfo == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const items = await this.client.listChecklistItems(taskInfo.taskListId, taskInfo.taskId);
+        return items.map((item) => {
+            const graphId = item.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.checklistItems.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, checklistItemId: graphId });
+            return {
+                id: numericId,
+                displayName: item.displayName ?? '',
+                isChecked: item.isChecked ?? false,
+                createdDateTime: item.createdDateTime ?? '',
+            };
+        });
+    }
+    async createChecklistItemAsync(taskId, displayName, isChecked = false) {
+        const taskInfo = this.idCache.tasks.get(taskId);
+        if (taskInfo == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const item = await this.client.createChecklistItem(taskInfo.taskListId, taskInfo.taskId, displayName, isChecked);
+        const graphId = item.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.checklistItems.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, checklistItemId: graphId });
+        return numericId;
+    }
+    async updateChecklistItemAsync(checklistItemId, updates) {
+        const cached = this.idCache.checklistItems.get(checklistItemId);
+        if (cached == null)
+            throw new Error(`Checklist item ID ${checklistItemId} not found in cache. Try listing checklist items first.`);
+        const graphUpdates = {};
+        if (updates.displayName != null)
+            graphUpdates['displayName'] = updates.displayName;
+        if (updates.isChecked != null)
+            graphUpdates['isChecked'] = updates.isChecked;
+        await this.client.updateChecklistItem(cached.taskListId, cached.taskId, cached.checklistItemId, graphUpdates);
+    }
+    async deleteChecklistItemAsync(checklistItemId) {
+        const cached = this.idCache.checklistItems.get(checklistItemId);
+        if (cached == null)
+            throw new Error(`Checklist item ID ${checklistItemId} not found in cache. Try listing checklist items first.`);
+        await this.client.deleteChecklistItem(cached.taskListId, cached.taskId, cached.checklistItemId);
+        this.idCache.checklistItems.delete(checklistItemId);
+    }
+    // ===========================================================================
+    // Linked Resources
+    // ===========================================================================
+    async listLinkedResourcesAsync(taskId) {
+        const taskInfo = this.idCache.tasks.get(taskId);
+        if (taskInfo == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const items = await this.client.listLinkedResources(taskInfo.taskListId, taskInfo.taskId);
+        return items.map((item) => {
+            const graphId = item.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.linkedResources.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, linkedResourceId: graphId });
+            return {
+                id: numericId,
+                webUrl: item.webUrl ?? '',
+                applicationName: item.applicationName ?? '',
+                displayName: item.displayName ?? '',
+            };
+        });
+    }
+    async createLinkedResourceAsync(taskId, webUrl, applicationName, displayName) {
+        const taskInfo = this.idCache.tasks.get(taskId);
+        if (taskInfo == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const item = await this.client.createLinkedResource(taskInfo.taskListId, taskInfo.taskId, webUrl, applicationName, displayName);
+        const graphId = item.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.linkedResources.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, linkedResourceId: graphId });
+        return numericId;
+    }
+    async deleteLinkedResourceAsync(linkedResourceId) {
+        const cached = this.idCache.linkedResources.get(linkedResourceId);
+        if (cached == null)
+            throw new Error(`Linked resource ID ${linkedResourceId} not found in cache. Try listing linked resources first.`);
+        await this.client.deleteLinkedResource(cached.taskListId, cached.taskId, cached.linkedResourceId);
+        this.idCache.linkedResources.delete(linkedResourceId);
+    }
+    // ===========================================================================
+    // Task Attachments
+    // ===========================================================================
+    async listTaskAttachmentsAsync(taskId) {
+        const taskInfo = this.idCache.tasks.get(taskId);
+        if (taskInfo == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const items = await this.client.listTaskAttachments(taskInfo.taskListId, taskInfo.taskId);
+        return items.map((item) => {
+            const graphId = item.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.taskAttachments.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, attachmentId: graphId });
+            return {
+                id: numericId,
+                name: item['name'] ?? '',
+                size: item.size ?? 0,
+                contentType: item.contentType ?? '',
+            };
+        });
+    }
+    async createTaskAttachmentAsync(taskId, name, contentBytes, contentType) {
+        const taskInfo = this.idCache.tasks.get(taskId);
+        if (taskInfo == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try listing tasks first.`);
+        const item = await this.client.createTaskAttachment(taskInfo.taskListId, taskInfo.taskId, name, contentBytes, contentType);
+        const graphId = item.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.taskAttachments.set(numericId, { taskListId: taskInfo.taskListId, taskId: taskInfo.taskId, attachmentId: graphId });
+        return numericId;
+    }
+    async deleteTaskAttachmentAsync(taskAttachmentId) {
+        const cached = this.idCache.taskAttachments.get(taskAttachmentId);
+        if (cached == null)
+            throw new Error(`Task attachment ID ${taskAttachmentId} not found in cache. Try listing task attachments first.`);
+        await this.client.deleteTaskAttachment(cached.taskListId, cached.taskId, cached.attachmentId);
+        this.idCache.taskAttachments.delete(taskAttachmentId);
+    }
+    // ===========================================================================
+    // Mail Rules (Async)
+    // ===========================================================================
+    /**
+     * Lists all inbox mail rules.
+     */
+    async listMailRulesAsync() {
+        const rules = await this.client.listMailRules();
+        return rules.map((rule) => {
+            const graphId = rule.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.rules.set(numericId, graphId);
+            return {
+                id: numericId,
+                displayName: rule.displayName ?? '',
+                sequence: rule.sequence ?? 0,
+                isEnabled: rule.isEnabled ?? true,
+                conditions: rule.conditions ?? {},
+                actions: rule.actions ?? {},
+            };
+        });
+    }
+    /**
+     * Creates a new inbox mail rule.
+     */
+    async createMailRuleAsync(rule) {
+        const created = await this.client.createMailRule(rule);
+        const graphId = created.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.rules.set(numericId, graphId);
+        return numericId;
+    }
+    /**
+     * Deletes an inbox mail rule.
+     */
+    async deleteMailRuleAsync(ruleId) {
+        const graphId = this.idCache.rules.get(ruleId);
+        if (graphId == null)
+            throw new Error(`Rule ID ${ruleId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.deleteMailRule(graphId);
+        this.idCache.rules.delete(ruleId);
+    }
+    // ===========================================================================
+    // Automatic Replies (Out of Office)
+    // ===========================================================================
+    /**
+     * Gets the current automatic replies (OOF) settings.
+     */
+    async getAutomaticRepliesAsync() {
+        const settings = await this.client.getAutomaticReplies();
+        const startDt = settings.scheduledStartDateTime;
+        const endDt = settings.scheduledEndDateTime;
+        return {
+            status: settings.status ?? 'disabled',
+            externalAudience: settings.externalAudience ?? 'none',
+            internalReplyMessage: settings.internalReplyMessage ?? '',
+            externalReplyMessage: settings.externalReplyMessage ?? '',
+            scheduledStartDateTime: startDt?.dateTime ?? null,
+            scheduledEndDateTime: endDt?.dateTime ?? null,
+        };
+    }
+    /**
+     * Sets the automatic replies (OOF) settings.
+     */
+    async setAutomaticRepliesAsync(params) {
+        const settings = { status: params.status };
+        if (params.externalAudience != null)
+            settings['externalAudience'] = params.externalAudience;
+        if (params.internalReplyMessage != null)
+            settings['internalReplyMessage'] = params.internalReplyMessage;
+        if (params.externalReplyMessage != null)
+            settings['externalReplyMessage'] = params.externalReplyMessage;
+        if (params.scheduledStartDateTime != null)
+            settings['scheduledStartDateTime'] = { dateTime: params.scheduledStartDateTime, timeZone: 'UTC' };
+        if (params.scheduledEndDateTime != null)
+            settings['scheduledEndDateTime'] = { dateTime: params.scheduledEndDateTime, timeZone: 'UTC' };
+        await this.client.setAutomaticReplies(settings);
+    }
+    // ===========================================================================
+    // Mailbox Settings
+    // ===========================================================================
+    /**
+     * Gets the current mailbox settings (language, time zone, formats, working hours).
+     */
+    async getMailboxSettingsAsync() {
+        const settings = await this.client.getMailboxSettings();
+        const lang = settings.language;
+        return {
+            language: lang?.locale ?? null,
+            timeZone: settings.timeZone ?? null,
+            dateFormat: settings.dateFormat ?? null,
+            timeFormat: settings.timeFormat ?? null,
+            workingHours: settings.workingHours ?? null,
+        };
+    }
+    /**
+     * Updates mailbox settings (language, time zone, date/time formats).
+     */
+    async updateMailboxSettingsAsync(params) {
+        const settings = {};
+        if (params.language != null)
+            settings['language'] = { locale: params.language };
+        if (params.timeZone != null)
+            settings['timeZone'] = params.timeZone;
+        if (params.dateFormat != null)
+            settings['dateFormat'] = params.dateFormat;
+        if (params.timeFormat != null)
+            settings['timeFormat'] = params.timeFormat;
+        await this.client.updateMailboxSettings(settings);
+    }
+    // ===========================================================================
+    // Master Categories
+    // ===========================================================================
+    /**
+     * Lists all master categories.
+     */
+    async listCategoriesAsync() {
+        const categories = await this.client.listMasterCategories();
+        return categories.map((cat) => {
+            const graphId = cat.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.categories.set(numericId, graphId);
+            return {
+                id: numericId,
+                name: cat.displayName ?? '',
+                color: cat.color ?? 'none',
+            };
+        });
+    }
+    /**
+     * Creates a new master category.
+     */
+    async createCategoryAsync(name, color) {
+        const created = await this.client.createMasterCategory(name, color);
+        const graphId = created.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.categories.set(numericId, graphId);
+        return numericId;
+    }
+    /**
+     * Deletes a master category.
+     */
+    async deleteCategoryAsync(categoryId) {
+        const graphId = this.idCache.categories.get(categoryId);
+        if (graphId == null)
+            throw new Error(`Category ID ${categoryId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.deleteMasterCategory(graphId);
+        this.idCache.categories.delete(categoryId);
+    }
+    // ===========================================================================
+    // Focused Inbox Overrides
+    // ===========================================================================
+    /**
+     * Lists all focused inbox overrides.
+     */
+    async listFocusedOverridesAsync() {
+        const overrides = await this.client.listFocusedOverrides();
+        return overrides.map((o) => {
+            const graphId = o.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.focusedOverrides.set(numericId, graphId);
+            return {
+                id: numericId,
+                senderAddress: o.senderEmailAddress?.address ?? '',
+                classifyAs: o.classifyAs ?? '',
+            };
+        });
+    }
+    /**
+     * Creates a focused inbox override.
+     */
+    async createFocusedOverrideAsync(senderAddress, classifyAs) {
+        const created = await this.client.createFocusedOverride(senderAddress, classifyAs);
+        const graphId = created.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.focusedOverrides.set(numericId, graphId);
+        return numericId;
+    }
+    /**
+     * Deletes a focused inbox override.
+     */
+    async deleteFocusedOverrideAsync(overrideId) {
+        const graphId = this.idCache.focusedOverrides.get(overrideId);
+        if (graphId == null)
+            throw new Error(`Focused override ID ${overrideId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        await this.client.deleteFocusedOverride(graphId);
+        this.idCache.focusedOverrides.delete(overrideId);
+    }
+    // ===========================================================================
+    // Message Headers & MIME
+    // ===========================================================================
+    /**
+     * Gets internet message headers for an email.
+     */
+    async getMessageHeadersAsync(emailId) {
+        const graphId = this.idCache.messages.get(emailId);
+        if (graphId == null)
+            throw new Error(`Email ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        return await this.client.getMessageHeaders(graphId);
+    }
+    /**
+     * Gets the MIME content of a message and saves it as an .eml file.
+     */
+    async getMessageMimeAsync(emailId) {
+        const graphId = this.idCache.messages.get(emailId);
+        if (graphId == null)
+            throw new Error(`Email ID ${emailId} not found in cache. Try searching for or listing the item first to refresh the cache.`);
+        const mime = await this.client.getMessageMime(graphId);
+        const downloadDir = getDownloadDir();
+        const filePath = path.join(downloadDir, `email-${emailId}.eml`);
+        fs.writeFileSync(filePath, mime, 'utf-8');
+        return { filePath };
+    }
+    // ===========================================================================
+    // Mail Tips
+    // ===========================================================================
+    /**
+     * Gets mail tips for the specified email addresses.
+     */
+    async getMailTipsAsync(emailAddresses) {
+        const tips = await this.client.getMailTips(emailAddresses);
+        return tips.map((tip) => {
+            const t = tip;
+            const emailAddr = t.emailAddress;
+            const autoReplies = t.automaticReplies;
+            return {
+                emailAddress: emailAddr?.address ?? '',
+                automaticReplies: (autoReplies?.message != null && autoReplies.message !== '') ? { message: autoReplies.message } : null,
+                mailboxFull: t.mailboxFull ?? false,
+                deliveryRestricted: t.deliveryRestricted ?? false,
+                externalMemberCount: t.externalMemberCount ?? 0,
+                maxMessageSize: t.maxMessageSize ?? 0,
+            };
+        });
+    }
+    // ===========================================================================
+    // Calendar Groups
+    // ===========================================================================
+    /**
+     * Lists all calendar groups.
+     */
+    async listCalendarGroupsAsync() {
+        const groups = await this.client.listCalendarGroups();
+        return groups.map((group) => {
+            const graphId = group.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.calendarGroups.set(numericId, graphId);
+            return {
+                id: numericId,
+                name: group.name ?? '',
+                classId: group.classId?.toString() ?? '',
+            };
+        });
+    }
+    /**
+     * Creates a new calendar group.
+     */
+    async createCalendarGroupAsync(name) {
+        const created = await this.client.createCalendarGroup(name);
+        const graphId = created.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.calendarGroups.set(numericId, graphId);
+        return numericId;
+    }
+    // ===========================================================================
+    // Calendar Permissions
+    // ===========================================================================
+    /**
+     * Lists all permissions for a calendar.
+     */
+    async listCalendarPermissionsAsync(calendarId) {
+        const graphCalendarId = this.idCache.calendars.get(calendarId);
+        if (graphCalendarId == null) {
+            throw new Error(`Calendar ID ${calendarId} not found in cache. Please call list_calendars first.`);
+        }
+        const permissions = await this.client.listCalendarPermissions(graphCalendarId);
+        return permissions.map((perm) => {
+            const graphPermId = perm.id;
+            const numericId = hashStringToNumber(graphPermId);
+            this.idCache.calendarPermissions.set(numericId, { calendarId: graphCalendarId, permissionId: graphPermId });
+            return {
+                id: numericId,
+                emailAddress: perm.emailAddress?.address ?? '',
+                role: perm.role ?? 'none',
+                isRemovable: perm.isRemovable ?? false,
+                isInsideOrganization: perm.isInsideOrganization ?? false,
+            };
+        });
+    }
+    /**
+     * Creates a calendar permission (shares a calendar with someone).
+     */
+    async createCalendarPermissionAsync(calendarId, email, role) {
+        const graphCalendarId = this.idCache.calendars.get(calendarId);
+        if (graphCalendarId == null) {
+            throw new Error(`Calendar ID ${calendarId} not found in cache. Please call list_calendars first.`);
+        }
+        const permission = await this.client.createCalendarPermission(graphCalendarId, {
+            emailAddress: {
+                address: email,
+                name: email,
+            },
+            role,
+        });
+        const graphPermId = permission.id;
+        const numericId = hashStringToNumber(graphPermId);
+        this.idCache.calendarPermissions.set(numericId, { calendarId: graphCalendarId, permissionId: graphPermId });
+        return numericId;
+    }
+    /**
+     * Deletes a calendar permission.
+     */
+    async deleteCalendarPermissionAsync(permissionId) {
+        const cached = this.idCache.calendarPermissions.get(permissionId);
+        if (cached == null) {
+            throw new Error(`Calendar permission ID ${permissionId} not found in cache. Please call list_calendar_permissions first.`);
+        }
+        await this.client.deleteCalendarPermission(cached.calendarId, cached.permissionId);
+        this.idCache.calendarPermissions.delete(permissionId);
+    }
+    // ===========================================================================
+    // Room Lists & Rooms
+    // ===========================================================================
+    /**
+     * Lists all room lists.
+     */
+    async listRoomListsAsync() {
+        const lists = await this.client.listRoomLists();
+        return lists.map((item) => ({
+            name: item.name ?? '',
+            address: item.address ?? '',
+        }));
+    }
+    /**
+     * Lists rooms, optionally filtered by a room list email.
+     */
+    async listRoomsAsync(roomListEmail) {
+        const rooms = await this.client.listRooms(roomListEmail);
+        return rooms.map((item) => ({
+            name: item.name ?? '',
+            address: item.address ?? '',
+        }));
+    }
+    // ===========================================================================
+    // Teams
+    // ===========================================================================
+    /**
+     * Lists all joined teams with cached numeric IDs.
+     */
+    async listTeamsAsync() {
+        const teams = await this.client.listJoinedTeams();
+        return teams.map((team) => {
+            const graphId = team.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.teams.set(numericId, graphId);
+            return { id: numericId, name: team.displayName ?? '', description: team.description ?? '' };
+        });
+    }
+    /**
+     * Lists all channels in a team with cached numeric IDs.
+     */
+    async listChannelsAsync(teamId) {
+        const graphTeamId = this.idCache.teams.get(teamId);
+        if (graphTeamId == null)
+            throw new Error(`Team ID ${teamId} not found in cache. Try listing teams first.`);
+        const channels = await this.client.listChannels(graphTeamId);
+        return channels.map((ch) => {
+            const graphId = ch.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.channels.set(numericId, { teamId: graphTeamId, channelId: graphId });
+            return { id: numericId, name: ch.displayName ?? '', description: ch.description ?? '', membershipType: ch.membershipType ?? 'standard' };
+        });
+    }
+    /**
+     * Gets a specific channel by cached numeric ID.
+     */
+    async getChannelAsync(channelId) {
+        const cached = this.idCache.channels.get(channelId);
+        if (cached == null)
+            throw new Error(`Channel ID ${channelId} not found in cache. Try listing channels first.`);
+        const ch = await this.client.getChannel(cached.teamId, cached.channelId);
+        return { id: channelId, name: ch.displayName ?? '', description: ch.description ?? '', membershipType: ch.membershipType ?? 'standard', webUrl: ch.webUrl ?? '' };
+    }
+    /**
+     * Creates a new channel in a team.
+     */
+    async createChannelAsync(teamId, name, description) {
+        const graphTeamId = this.idCache.teams.get(teamId);
+        if (graphTeamId == null)
+            throw new Error(`Team ID ${teamId} not found in cache. Try listing teams first.`);
+        const ch = await this.client.createChannel(graphTeamId, name, description);
+        const graphId = ch.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.channels.set(numericId, { teamId: graphTeamId, channelId: graphId });
+        return numericId;
+    }
+    /**
+     * Updates a channel's properties.
+     */
+    async updateChannelAsync(channelId, updates) {
+        const cached = this.idCache.channels.get(channelId);
+        if (cached == null)
+            throw new Error(`Channel ID ${channelId} not found in cache. Try listing channels first.`);
+        const graphUpdates = {};
+        if (updates.name != null)
+            graphUpdates['displayName'] = updates.name;
+        if (updates.description != null)
+            graphUpdates['description'] = updates.description;
+        await this.client.updateChannel(cached.teamId, cached.channelId, graphUpdates);
+    }
+    /**
+     * Deletes a channel.
+     */
+    async deleteChannelAsync(channelId) {
+        const cached = this.idCache.channels.get(channelId);
+        if (cached == null)
+            throw new Error(`Channel ID ${channelId} not found in cache. Try listing channels first.`);
+        await this.client.deleteChannel(cached.teamId, cached.channelId);
+        this.idCache.channels.delete(channelId);
+    }
+    /**
+     * Lists members of a team.
+     */
+    async listTeamMembersAsync(teamId) {
+        const graphTeamId = this.idCache.teams.get(teamId);
+        if (graphTeamId == null)
+            throw new Error(`Team ID ${teamId} not found in cache. Try listing teams first.`);
+        const members = await this.client.listTeamMembers(graphTeamId);
+        return members.map((m) => ({
+            id: m.id ?? '',
+            displayName: m.displayName ?? '',
+            email: m.email ?? '',
+            roles: m.roles ?? [],
+        }));
+    }
+    // ===========================================================================
+    // Channel Messages
+    // ===========================================================================
+    /**
+     * Lists recent messages in a channel.
+     */
+    async listChannelMessagesAsync(channelId, limit = 25) {
+        const cached = this.idCache.channels.get(channelId);
+        if (cached == null)
+            throw new Error(`Channel ID ${channelId} not found in cache. Try listing channels first.`);
+        const messages = await this.client.listChannelMessages(cached.teamId, cached.channelId, limit);
+        return messages.map((msg) => {
+            const graphId = msg.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.channelMessages.set(numericId, { teamId: cached.teamId, channelId: cached.channelId, messageId: graphId });
+            return {
+                id: numericId,
+                senderName: msg.from?.user?.displayName ?? msg.from?.application?.displayName ?? '',
+                senderEmail: msg.from?.user?.email ?? '',
+                bodyPreview: msg.body?.content?.substring(0, 200) ?? '',
+                bodyContent: msg.body?.content ?? '',
+                contentType: msg.body?.contentType ?? 'html',
+                createdDateTime: msg.createdDateTime ?? '',
+            };
+        });
+    }
+    /**
+     * Gets a specific channel message with its replies.
+     */
+    async getChannelMessageAsync(messageId) {
+        const cached = this.idCache.channelMessages.get(messageId);
+        if (cached == null)
+            throw new Error(`Message ID ${messageId} not found in cache. Try listing channel messages first.`);
+        const [msg, repliesRaw] = await Promise.all([
+            this.client.getChannelMessage(cached.teamId, cached.channelId, cached.messageId),
+            this.client.listChannelMessageReplies(cached.teamId, cached.channelId, cached.messageId),
+        ]);
+        const replies = repliesRaw.map((r) => {
+            const rGraphId = r.id;
+            const rNumericId = hashStringToNumber(rGraphId);
+            return {
+                id: rNumericId,
+                senderName: r.from?.user?.displayName ?? r.from?.application?.displayName ?? '',
+                senderEmail: r.from?.user?.email ?? '',
+                bodyContent: r.body?.content ?? '',
+                contentType: r.body?.contentType ?? 'html',
+                createdDateTime: r.createdDateTime ?? '',
+            };
+        });
+        return {
+            id: messageId,
+            senderName: msg.from?.user?.displayName ?? msg.from?.application?.displayName ?? '',
+            senderEmail: msg.from?.user?.email ?? '',
+            bodyContent: msg.body?.content ?? '',
+            contentType: msg.body?.contentType ?? 'html',
+            createdDateTime: msg.createdDateTime ?? '',
+            replies,
+        };
+    }
+    /**
+     * Sends a new message to a channel.
+     */
+    async sendChannelMessageAsync(channelId, body, contentType = 'html') {
+        const cached = this.idCache.channels.get(channelId);
+        if (cached == null)
+            throw new Error(`Channel ID ${channelId} not found in cache. Try listing channels first.`);
+        const msg = await this.client.sendChannelMessage(cached.teamId, cached.channelId, body, contentType);
+        const graphId = msg.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.channelMessages.set(numericId, { teamId: cached.teamId, channelId: cached.channelId, messageId: graphId });
+        return numericId;
+    }
+    /**
+     * Replies to a channel message.
+     */
+    async replyToChannelMessageAsync(messageId, body, contentType = 'html') {
+        const cached = this.idCache.channelMessages.get(messageId);
+        if (cached == null)
+            throw new Error(`Message ID ${messageId} not found in cache. Try listing channel messages first.`);
+        const reply = await this.client.replyToChannelMessage(cached.teamId, cached.channelId, cached.messageId, body, contentType);
+        const graphId = reply.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.channelMessages.set(numericId, { teamId: cached.teamId, channelId: cached.channelId, messageId: graphId });
+        return numericId;
+    }
+    // ===========================================================================
+    // Chats
+    // ===========================================================================
+    async listChatsAsync(limit = 25) {
+        const chats = await this.client.listChats(limit);
+        return chats.map((chat) => {
+            const graphId = chat.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.chats.set(numericId, graphId);
+            const chatRecord = chat;
+            const preview = chatRecord.lastMessagePreview;
+            const previewBody = preview?.body;
+            const previewContent = previewBody?.content?.substring(0, 200) ?? '';
+            return {
+                id: numericId,
+                topic: chat.topic ?? '',
+                chatType: chat.chatType ?? 'oneOnOne',
+                lastMessagePreview: previewContent,
+                createdDateTime: chat.createdDateTime ?? '',
+            };
+        });
+    }
+    async getChatAsync(chatId) {
+        const graphId = this.idCache.chats.get(chatId);
+        if (graphId == null)
+            throw new Error(`Chat ID ${chatId} not found in cache. Try listing chats first.`);
+        const chat = await this.client.getChat(graphId);
+        return {
+            id: chatId,
+            topic: chat.topic ?? '',
+            chatType: chat.chatType ?? 'oneOnOne',
+            createdDateTime: chat.createdDateTime ?? '',
+            webUrl: chat.webUrl ?? '',
+        };
+    }
+    async listChatMessagesAsync(chatId, limit = 25) {
+        const graphChatId = this.idCache.chats.get(chatId);
+        if (graphChatId == null)
+            throw new Error(`Chat ID ${chatId} not found in cache. Try listing chats first.`);
+        const messages = await this.client.listChatMessages(graphChatId, limit);
+        return messages.map((msg) => {
+            const graphId = msg.id;
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.chatMessages.set(numericId, { chatId: graphChatId, messageId: graphId });
+            return {
+                id: numericId,
+                senderName: msg.from?.user?.displayName ?? msg.from?.application?.displayName ?? '',
+                senderEmail: msg.from?.user?.email ?? '',
+                bodyPreview: msg.body?.content?.substring(0, 200) ?? '',
+                bodyContent: msg.body?.content ?? '',
+                contentType: msg.body?.contentType ?? 'html',
+                createdDateTime: msg.createdDateTime ?? '',
+            };
+        });
+    }
+    async sendChatMessageAsync(chatId, body, contentType = 'html') {
+        const graphChatId = this.idCache.chats.get(chatId);
+        if (graphChatId == null)
+            throw new Error(`Chat ID ${chatId} not found in cache. Try listing chats first.`);
+        const msg = await this.client.sendChatMessage(graphChatId, body, contentType);
+        const graphId = msg.id;
+        const numericId = hashStringToNumber(graphId);
+        this.idCache.chatMessages.set(numericId, { chatId: graphChatId, messageId: graphId });
+        return numericId;
+    }
+    // ===========================================================================
+    // Message Reactions
+    // ===========================================================================
+    async listMessageReactionsAsync(messageId, messageType) {
+        const mapReactions = (msg) => {
+            const reactions = (msg.reactions ?? []);
+            return reactions.map((r) => {
+                const userObj = r.user;
+                const innerUser = userObj?.user;
+                return {
+                    reactionType: r.reactionType ?? '',
+                    user: { displayName: innerUser?.displayName ?? '' },
+                    createdDateTime: r.createdDateTime ?? '',
+                };
+            });
+        };
+        if (messageType === 'channel') {
+            const cached = this.idCache.channelMessages.get(messageId);
+            if (cached == null)
+                throw new Error(`Message ID ${messageId} not found in cache. Try listing channel messages first.`);
+            const msg = await this.client.getChannelMessage(cached.teamId, cached.channelId, cached.messageId);
+            return mapReactions(msg);
+        }
+        else {
+            const cached = this.idCache.chatMessages.get(messageId);
+            if (cached == null)
+                throw new Error(`Message ID ${messageId} not found in cache. Try listing chat messages first.`);
+            const msg = await this.client.getChatMessage(cached.chatId, cached.messageId);
+            return mapReactions(msg);
+        }
+    }
+    async addMessageReactionAsync(messageId, messageType, reactionType) {
+        if (messageType === 'channel') {
+            const cached = this.idCache.channelMessages.get(messageId);
+            if (cached == null)
+                throw new Error(`Message ID ${messageId} not found in cache. Try listing channel messages first.`);
+            await this.client.setChannelMessageReaction(cached.teamId, cached.channelId, cached.messageId, reactionType);
+        }
+        else {
+            const cached = this.idCache.chatMessages.get(messageId);
+            if (cached == null)
+                throw new Error(`Message ID ${messageId} not found in cache. Try listing chat messages first.`);
+            await this.client.setChatMessageReaction(cached.chatId, cached.messageId, reactionType);
+        }
+    }
+    async removeMessageReactionAsync(messageId, messageType, reactionType) {
+        if (messageType === 'channel') {
+            const cached = this.idCache.channelMessages.get(messageId);
+            if (cached == null)
+                throw new Error(`Message ID ${messageId} not found in cache. Try listing channel messages first.`);
+            await this.client.unsetChannelMessageReaction(cached.teamId, cached.channelId, cached.messageId, reactionType);
+        }
+        else {
+            const cached = this.idCache.chatMessages.get(messageId);
+            if (cached == null)
+                throw new Error(`Message ID ${messageId} not found in cache. Try listing chat messages first.`);
+            await this.client.unsetChatMessageReaction(cached.chatId, cached.messageId, reactionType);
+        }
+    }
+    async listChatMembersAsync(chatId) {
+        const graphChatId = this.idCache.chats.get(chatId);
+        if (graphChatId == null)
+            throw new Error(`Chat ID ${chatId} not found in cache. Try listing chats first.`);
+        const members = await this.client.listChatMembers(graphChatId);
+        return members.map((m) => ({
+            displayName: m.displayName ?? '',
+            email: m.email ?? '',
+            roles: m.roles ?? [],
+        }));
+    }
+    // ===========================================================================
+    // Planner Plans
+    // ===========================================================================
+    /**
+     * Lists all plans the current user has.
+     */
+    async listPlansAsync() {
+        const plans = await this.client.listPlans();
+        return plans.map((plan) => {
+            const graphId = plan.id;
+            const numericId = hashStringToNumber(graphId);
+            const etag = plan['@odata.etag'] ?? '';
+            this.idCache.plans.set(numericId, { planId: graphId, etag });
+            return {
+                id: numericId,
+                title: plan.title ?? '',
+                owner: plan.owner ?? '',
+                createdDateTime: plan.createdDateTime ?? '',
+            };
+        });
+    }
+    /**
+     * Gets a specific plan by cached numeric ID.
+     */
+    async getPlanAsync(planId) {
+        const cached = this.idCache.plans.get(planId);
+        if (cached == null)
+            throw new Error(`Plan ID ${planId} not found in cache. Try listing plans first.`);
+        const plan = await this.client.getPlan(cached.planId);
+        const etag = plan['@odata.etag'] ?? '';
+        this.idCache.plans.set(planId, { planId: cached.planId, etag });
+        return {
+            id: planId,
+            title: plan.title ?? '',
+            owner: plan.owner ?? '',
+            createdDateTime: plan.createdDateTime ?? '',
+            etag,
+        };
+    }
+    /**
+     * Creates a new plan.
+     */
+    async createPlanAsync(title, groupId) {
+        const plan = await this.client.createPlan(title, groupId);
+        const graphId = plan.id;
+        const numericId = hashStringToNumber(graphId);
+        const etag = plan['@odata.etag'] ?? '';
+        this.idCache.plans.set(numericId, { planId: graphId, etag });
+        return numericId;
+    }
+    /**
+     * Updates a plan (requires cached ETag).
+     */
+    async updatePlanAsync(planId, updates) {
+        const cached = this.idCache.plans.get(planId);
+        if (cached == null)
+            throw new Error(`Plan ID ${planId} not found in cache. Try listing plans first.`);
+        const graphUpdates = {};
+        if (updates.title != null)
+            graphUpdates['title'] = updates.title;
+        const result = await this.client.updatePlan(cached.planId, graphUpdates, cached.etag);
+        const newEtag = result['@odata.etag'] ?? cached.etag;
+        this.idCache.plans.set(planId, { planId: cached.planId, etag: newEtag });
+    }
+    // ===========================================================================
+    // Planner Buckets
+    // ===========================================================================
+    /**
+     * Lists all buckets in a plan.
+     */
+    async listBucketsAsync(planId) {
+        const cached = this.idCache.plans.get(planId);
+        if (cached == null)
+            throw new Error(`Plan ID ${planId} not found in cache. Try listing plans first.`);
+        const buckets = await this.client.listBuckets(cached.planId);
+        return buckets.map((bucket) => {
+            const graphId = bucket.id;
+            const numericId = hashStringToNumber(graphId);
+            const etag = bucket['@odata.etag'] ?? '';
+            this.idCache.plannerBuckets.set(numericId, { planId: cached.planId, bucketId: graphId, etag });
+            return {
+                id: numericId,
+                name: bucket.name ?? '',
+                planId,
+                orderHint: bucket.orderHint ?? '',
+            };
+        });
+    }
+    /**
+     * Creates a new bucket in a plan.
+     */
+    async createBucketAsync(planId, name) {
+        const cached = this.idCache.plans.get(planId);
+        if (cached == null)
+            throw new Error(`Plan ID ${planId} not found in cache. Try listing plans first.`);
+        const bucket = await this.client.createBucket(cached.planId, name);
+        const graphId = bucket.id;
+        const numericId = hashStringToNumber(graphId);
+        const etag = bucket['@odata.etag'] ?? '';
+        this.idCache.plannerBuckets.set(numericId, { planId: cached.planId, bucketId: graphId, etag });
+        return numericId;
+    }
+    /**
+     * Updates a bucket (requires cached ETag).
+     */
+    async updateBucketAsync(bucketId, updates) {
+        const cached = this.idCache.plannerBuckets.get(bucketId);
+        if (cached == null)
+            throw new Error(`Bucket ID ${bucketId} not found in cache. Try listing buckets first.`);
+        const graphUpdates = {};
+        if (updates.name != null)
+            graphUpdates['name'] = updates.name;
+        const result = await this.client.updateBucket(cached.bucketId, graphUpdates, cached.etag);
+        const newEtag = result['@odata.etag'] ?? cached.etag;
+        this.idCache.plannerBuckets.set(bucketId, { planId: cached.planId, bucketId: cached.bucketId, etag: newEtag });
+    }
+    /**
+     * Deletes a bucket (requires cached ETag).
+     */
+    async deleteBucketAsync(bucketId) {
+        const cached = this.idCache.plannerBuckets.get(bucketId);
+        if (cached == null)
+            throw new Error(`Bucket ID ${bucketId} not found in cache. Try listing buckets first.`);
+        await this.client.deleteBucket(cached.bucketId, cached.etag);
+        this.idCache.plannerBuckets.delete(bucketId);
+    }
+    // ===========================================================================
+    // Planner Tasks
+    // ===========================================================================
+    /**
+     * Lists all tasks in a plan.
+     */
+    async listPlannerTasksAsync(planId) {
+        const cached = this.idCache.plans.get(planId);
+        if (cached == null)
+            throw new Error(`Plan ID ${planId} not found in cache. Try listing plans first.`);
+        const tasks = await this.client.listPlannerTasks(cached.planId);
+        return tasks.map((task) => {
+            const graphId = task.id;
+            const numericId = hashStringToNumber(graphId);
+            const etag = task['@odata.etag'] ?? '';
+            this.idCache.plannerTasks.set(numericId, { taskId: graphId, etag });
+            // Resolve bucket numeric ID if present
+            let bucketNumericId = null;
+            if (task.bucketId != null) {
+                bucketNumericId = hashStringToNumber(task.bucketId);
+            }
+            return {
+                id: numericId,
+                title: task.title ?? '',
+                bucketId: bucketNumericId,
+                assignees: task.assignments != null ? Object.keys(task.assignments) : [],
+                percentComplete: task.percentComplete ?? 0,
+                priority: task.priority ?? 5,
+                startDateTime: task.startDateTime ?? '',
+                dueDateTime: task.dueDateTime ?? '',
+                createdDateTime: task.createdDateTime ?? '',
+            };
+        });
+    }
+    /**
+     * Gets a specific planner task by cached numeric ID.
+     */
+    async getPlannerTaskAsync(taskId) {
+        const cached = this.idCache.plannerTasks.get(taskId);
+        if (cached == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try listing planner tasks first.`);
+        const task = await this.client.getPlannerTask(cached.taskId);
+        const etag = task['@odata.etag'] ?? '';
+        this.idCache.plannerTasks.set(taskId, { taskId: cached.taskId, etag });
+        let bucketNumericId = null;
+        if (task.bucketId != null) {
+            bucketNumericId = hashStringToNumber(task.bucketId);
+        }
+        return {
+            id: taskId,
+            title: task.title ?? '',
+            bucketId: bucketNumericId,
+            assignees: task.assignments != null ? Object.keys(task.assignments) : [],
+            percentComplete: task.percentComplete ?? 0,
+            priority: task.priority ?? 5,
+            startDateTime: task.startDateTime ?? '',
+            dueDateTime: task.dueDateTime ?? '',
+            createdDateTime: task.createdDateTime ?? '',
+            conversationThreadId: task.conversationThreadId ?? '',
+            orderHint: task.orderHint ?? '',
+            etag,
+        };
+    }
+    /**
+     * Creates a new planner task.
+     */
+    async createPlannerTaskAsync(planId, title, bucketId, assignments, priority, startDate, dueDate) {
+        const cachedPlan = this.idCache.plans.get(planId);
+        if (cachedPlan == null)
+            throw new Error(`Plan ID ${planId} not found in cache. Try listing plans first.`);
+        const body = { planId: cachedPlan.planId, title };
+        if (bucketId != null) {
+            const cachedBucket = this.idCache.plannerBuckets.get(bucketId);
+            if (cachedBucket == null)
+                throw new Error(`Bucket ID ${bucketId} not found in cache. Try listing buckets first.`);
+            body.bucketId = cachedBucket.bucketId;
+        }
+        if (assignments != null)
+            body.assignments = assignments;
+        if (priority != null)
+            body.priority = priority;
+        if (startDate != null)
+            body.startDateTime = startDate;
+        if (dueDate != null)
+            body.dueDateTime = dueDate;
+        const task = await this.client.createPlannerTask(body);
+        const graphId = task.id;
+        const numericId = hashStringToNumber(graphId);
+        const etag = task['@odata.etag'] ?? '';
+        this.idCache.plannerTasks.set(numericId, { taskId: graphId, etag });
+        return numericId;
+    }
+    /**
+     * Updates a planner task (requires cached ETag).
+     */
+    async updatePlannerTaskAsync(taskId, updates) {
+        const cached = this.idCache.plannerTasks.get(taskId);
+        if (cached == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try listing planner tasks first.`);
+        const graphUpdates = {};
+        if (updates.title != null)
+            graphUpdates['title'] = updates.title;
+        if (updates.bucketId != null) {
+            const cachedBucket = this.idCache.plannerBuckets.get(updates.bucketId);
+            if (cachedBucket == null)
+                throw new Error(`Bucket ID ${updates.bucketId} not found in cache. Try listing buckets first.`);
+            graphUpdates['bucketId'] = cachedBucket.bucketId;
+        }
+        if (updates.percentComplete != null)
+            graphUpdates['percentComplete'] = updates.percentComplete;
+        if (updates.priority != null)
+            graphUpdates['priority'] = updates.priority;
+        if (updates.startDate != null)
+            graphUpdates['startDateTime'] = updates.startDate;
+        if (updates.dueDate != null)
+            graphUpdates['dueDateTime'] = updates.dueDate;
+        if (updates.assignments != null)
+            graphUpdates['assignments'] = updates.assignments;
+        const result = await this.client.updatePlannerTask(cached.taskId, graphUpdates, cached.etag);
+        const newEtag = result['@odata.etag'] ?? cached.etag;
+        this.idCache.plannerTasks.set(taskId, { taskId: cached.taskId, etag: newEtag });
+    }
+    /**
+     * Deletes a planner task (requires cached ETag).
+     */
+    async deletePlannerTaskAsync(taskId) {
+        const cached = this.idCache.plannerTasks.get(taskId);
+        if (cached == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try listing planner tasks first.`);
+        await this.client.deletePlannerTask(cached.taskId, cached.etag);
+        this.idCache.plannerTasks.delete(taskId);
+    }
+    // ===========================================================================
+    // Planner Task Details
+    // ===========================================================================
+    /**
+     * Gets details for a planner task (description, checklist, references).
+     */
+    async getPlannerTaskDetailsAsync(taskId) {
+        const cached = this.idCache.plannerTasks.get(taskId);
+        if (cached == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try listing planner tasks first.`);
+        const details = await this.client.getPlannerTaskDetails(cached.taskId);
+        const etag = details['@odata.etag'] ?? '';
+        this.idCache.plannerTaskDetails.set(taskId, { taskId: cached.taskId, etag });
+        return {
+            id: taskId,
+            description: details.description ?? '',
+            checklist: details.checklist ?? {},
+            references: details.references ?? {},
+            etag,
+        };
+    }
+    /**
+     * Lists all tasks in a plan with their details (description, checklist, references)
+     * fetched in batched requests. This avoids N+1 queries when you need both the task
+     * list and each task's details.
+     *
+     * Details are fetched via the Graph $batch API (up to 20 per batch).
+     * Partial failures are handled gracefully: tasks whose detail fetch failed will
+     * have `details` set to `undefined`.
+     */
+    async listPlannerTasksWithDetailsAsync(planId) {
+        // Step 1: List all tasks (populates idCache.plannerTasks)
+        const tasks = await this.listPlannerTasksAsync(planId);
+        if (tasks.length === 0)
+            return [];
+        // Step 2: Build batch requests for each task's details
+        const batchRequests = tasks.map((task) => {
+            const cached = this.idCache.plannerTasks.get(task.id);
+            // cached is guaranteed to exist since listPlannerTasksAsync just populated it
+            const graphTaskId = cached.taskId;
+            return {
+                id: String(task.id),
+                method: 'GET',
+                url: `/planner/tasks/${graphTaskId}/details`,
+            };
+        });
+        // Step 3: Execute batch requests (automatically splits into batches of 20)
+        const batchResults = await this.client.batchRequests(batchRequests);
+        // Step 4: Merge details into tasks
+        return tasks.map((task) => {
+            const result = batchResults.get(String(task.id));
+            if (result != null && result.status >= 200 && result.status < 300) {
+                const detailBody = result.body;
+                const etag = result.headers?.ETag ?? result.headers?.etag ?? '';
+                // Cache the task detail ETag for later updates
+                const cachedTask = this.idCache.plannerTasks.get(task.id);
+                if (cachedTask != null) {
+                    this.idCache.plannerTaskDetails.set(task.id, { taskId: cachedTask.taskId, etag });
+                }
+                return {
+                    ...task,
+                    details: {
+                        description: detailBody.description ?? '',
+                        checklist: detailBody.checklist ?? {},
+                        references: detailBody.references ?? {},
+                        etag,
+                    },
+                };
+            }
+            // Partial failure: return task without details
+            return { ...task, details: undefined };
+        });
+    }
+    /**
+     * Updates details for a planner task (requires cached ETag from getPlannerTaskDetailsAsync).
+     */
+    async updatePlannerTaskDetailsAsync(taskId, updates) {
+        const cachedTask = this.idCache.plannerTasks.get(taskId);
+        if (cachedTask == null)
+            throw new Error(`Task ID ${taskId} not found in cache. Try listing planner tasks first.`);
+        const cachedDetails = this.idCache.plannerTaskDetails.get(taskId);
+        if (cachedDetails == null)
+            throw new Error(`Task details ETag for task ${taskId} not found in cache. Call get_planner_task_details first.`);
+        const graphUpdates = {};
+        if (updates.description != null)
+            graphUpdates['description'] = updates.description;
+        if (updates.checklist != null)
+            graphUpdates['checklist'] = updates.checklist;
+        if (updates.references != null)
+            graphUpdates['references'] = updates.references;
+        const result = await this.client.updatePlannerTaskDetails(cachedTask.taskId, graphUpdates, cachedDetails.etag);
+        const newEtag = result['@odata.etag'] ?? cachedDetails.etag;
+        this.idCache.plannerTaskDetails.set(taskId, { taskId: cachedTask.taskId, etag: newEtag });
+    }
+    // ===========================================================================
+    // Planner Visualization Data
+    // ===========================================================================
+    /**
+     * Assembles plan, buckets, and tasks into a unified visualization data object.
+     */
+    async getPlanVisualizationDataAsync(planId) {
+        const plan = await this.getPlanAsync(planId);
+        const buckets = await this.listBucketsAsync(planId);
+        const tasks = await this.listPlannerTasksAsync(planId);
+        return {
+            plan: {
+                id: plan.id,
+                title: plan.title,
+            },
+            buckets: buckets.map(b => ({
+                id: b.id,
+                name: b.name,
+                orderHint: b.orderHint,
+            })),
+            tasks: tasks.map(t => ({
+                id: t.id,
+                title: t.title,
+                bucketId: t.bucketId ?? 0,
+                percentComplete: t.percentComplete,
+                priority: t.priority,
+                startDateTime: t.startDateTime || null,
+                dueDateTime: t.dueDateTime || null,
+                assignments: t.assignees,
+            })),
+        };
+    }
+    // ===========================================================================
+    // Online Meetings
+    // ===========================================================================
+    async listOnlineMeetingsAsync(limit) {
+        const meetings = await this.client.listOnlineMeetings(limit ?? 20);
+        return meetings.map((meeting) => {
+            const graphId = meeting.id ?? '';
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.onlineMeetings.set(numericId, graphId);
+            return {
+                id: numericId,
+                subject: meeting.subject ?? '',
+                startDateTime: meeting.startDateTime ?? '',
+                endDateTime: meeting.endDateTime ?? '',
+                joinUrl: meeting.joinWebUrl ?? '',
+            };
+        });
+    }
+    async getOnlineMeetingAsync(meetingId) {
+        const mapMeeting = (m) => ({
+            id: meetingId,
+            subject: m.subject ?? '',
+            startDateTime: m.startDateTime ?? '',
+            endDateTime: m.endDateTime ?? '',
+            joinUrl: m.joinWebUrl ?? '',
+            participants: m.participants ?? null,
+        });
+        const graphId = this.idCache.onlineMeetings.get(meetingId);
+        if (graphId == null) {
+            // Try to refresh cache
+            await this.listOnlineMeetingsAsync(100);
+            const refreshedId = this.idCache.onlineMeetings.get(meetingId);
+            if (refreshedId == null)
+                return undefined;
+            const meeting = await this.client.getOnlineMeeting(refreshedId);
+            return mapMeeting(meeting);
+        }
+        const meeting = await this.client.getOnlineMeeting(graphId);
+        return mapMeeting(meeting);
+    }
+    async listMeetingRecordingsAsync(meetingId) {
+        const graphMeetingId = this.idCache.onlineMeetings.get(meetingId);
+        if (graphMeetingId == null)
+            throw new Error(`Meeting ID ${meetingId} not found in cache. Try listing online meetings first.`);
+        const recordings = await this.client.listMeetingRecordings(graphMeetingId);
+        return recordings.map((recording) => {
+            const graphId = recording.id ?? '';
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.recordings.set(numericId, { meetingId: graphMeetingId, recordingId: graphId });
+            return {
+                id: numericId,
+                createdDateTime: recording.createdDateTime ?? '',
+                recordingContentUrl: recording.recordingContentUrl ?? '',
+            };
+        });
+    }
+    async downloadMeetingRecordingAsync(recordingId, outputPath) {
+        const cached = this.idCache.recordings.get(recordingId);
+        if (cached == null)
+            throw new Error(`Recording ID ${recordingId} not found in cache. Call list_meeting_recordings first.`);
+        const content = await this.client.getMeetingRecordingContent(cached.meetingId, cached.recordingId);
+        fs.writeFileSync(outputPath, Buffer.from(content));
+        return outputPath;
+    }
+    async listMeetingTranscriptsAsync(meetingId) {
+        const graphMeetingId = this.idCache.onlineMeetings.get(meetingId);
+        if (graphMeetingId == null)
+            throw new Error(`Meeting ID ${meetingId} not found in cache. Try listing online meetings first.`);
+        const transcripts = await this.client.listMeetingTranscripts(graphMeetingId);
+        return transcripts.map((transcript) => {
+            const graphId = transcript.id ?? '';
+            const numericId = hashStringToNumber(graphId);
+            this.idCache.transcripts.set(numericId, { meetingId: graphMeetingId, transcriptId: graphId });
+            return {
+                id: numericId,
+                createdDateTime: transcript.createdDateTime ?? '',
+                contentUrl: transcript.contentUrl ?? '',
+            };
+        });
+    }
+    async getMeetingTranscriptContentAsync(transcriptId, format) {
+        const cached = this.idCache.transcripts.get(transcriptId);
+        if (cached == null)
+            throw new Error(`Transcript ID ${transcriptId} not found in cache. Call list_meeting_transcripts first.`);
+        return await this.client.getMeetingTranscriptContent(cached.meetingId, cached.transcriptId, format ?? 'text/vtt');
+    }
+    // ===========================================================================
+    // Excel Online (Workbook)
+    // ===========================================================================
+    async listWorksheetsAsync(fileId) {
+        const driveItemId = this.idCache.driveItems.get(fileId);
+        if (driveItemId == null)
+            throw new Error(`Drive item ID ${fileId} not found in cache. List OneDrive or SharePoint files first.`);
+        return await this.client.listWorksheets(driveItemId);
+    }
+    async getWorksheetRangeAsync(fileId, worksheetName, range) {
+        const driveItemId = this.idCache.driveItems.get(fileId);
+        if (driveItemId == null)
+            throw new Error(`Drive item ID ${fileId} not found in cache. List OneDrive or SharePoint files first.`);
+        return await this.client.getWorksheetRange(driveItemId, worksheetName, range);
+    }
+    async getUsedRangeAsync(fileId, worksheetName) {
+        const driveItemId = this.idCache.driveItems.get(fileId);
+        if (driveItemId == null)
+            throw new Error(`Drive item ID ${fileId} not found in cache. List OneDrive or SharePoint files first.`);
+        return await this.client.getUsedRange(driveItemId, worksheetName);
+    }
+    async updateWorksheetRangeAsync(fileId, worksheetName, range, values) {
+        const driveItemId = this.idCache.driveItems.get(fileId);
+        if (driveItemId == null)
+            throw new Error(`Drive item ID ${fileId} not found in cache. List OneDrive or SharePoint files first.`);
+        return await this.client.updateWorksheetRange(driveItemId, worksheetName, range, values);
+    }
+    async getTableDataAsync(fileId, tableName) {
+        const driveItemId = this.idCache.driveItems.get(fileId);
+        if (driveItemId == null)
+            throw new Error(`Drive item ID ${fileId} not found in cache. List OneDrive or SharePoint files first.`);
+        return await this.client.getTableData(driveItemId, tableName);
+    }
+    // OneDrive
+    // ===========================================================================
+    /**
+     * Lists files/folders in a drive folder (or root).
+     */
+    async listDriveItemsAsync(folderId) {
+        let graphFolderId;
+        if (folderId != null) {
+            graphFolderId = this.idCache.driveItems.get(folderId);
+            if (graphFolderId == null)
+                throw new Error(`Drive item ID ${folderId} not found in cache. Try listing drive items first.`);
+        }
+        const items = await this.client.listDriveItems(graphFolderId);
+        return items.map((item) => {
+            const itemId = item.id;
+            const numericId = hashStringToNumber(itemId);
+            this.idCache.driveItems.set(numericId, itemId);
+            return {
+                id: numericId,
+                name: item.name ?? '',
+                size: item.size ?? 0,
+                lastModified: item.lastModifiedDateTime ?? '',
+                isFolder: item.folder != null,
+                webUrl: item.webUrl ?? '',
+            };
+        });
+    }
+    /**
+     * Searches drive items by query.
+     */
+    async searchDriveItemsAsync(query, limit) {
+        const items = await this.client.searchDriveItems(query, limit);
+        return items.map((item) => {
+            const itemId = item.id;
+            const numericId = hashStringToNumber(itemId);
+            this.idCache.driveItems.set(numericId, itemId);
+            return {
+                id: numericId,
+                name: item.name ?? '',
+                size: item.size ?? 0,
+                lastModified: item.lastModifiedDateTime ?? '',
+                isFolder: item.folder != null,
+                webUrl: item.webUrl ?? '',
+            };
+        });
+    }
+    /**
+     * Gets metadata for a specific drive item.
+     */
+    async getDriveItemAsync(itemId) {
+        const graphId = this.idCache.driveItems.get(itemId);
+        if (graphId == null)
+            throw new Error(`Drive item ID ${itemId} not found in cache. Try listing drive items first.`);
+        const item = await this.client.getDriveItem(graphId);
+        const fileObj = item.file;
+        const createdByObj = item.createdBy;
+        const createdByUser = createdByObj?.user;
+        return {
+            id: itemId,
+            name: item.name ?? '',
+            size: item.size ?? 0,
+            lastModified: item.lastModifiedDateTime ?? '',
+            isFolder: item.folder != null,
+            webUrl: item.webUrl ?? '',
+            mimeType: fileObj?.mimeType ?? '',
+            createdBy: createdByUser?.displayName ?? '',
+        };
+    }
+    /**
+     * Downloads a drive item to a local file.
+     */
+    async downloadFileAsync(itemId, outputPath) {
+        const graphId = this.idCache.driveItems.get(itemId);
+        if (graphId == null)
+            throw new Error(`Drive item ID ${itemId} not found in cache. Try listing drive items first.`);
+        const content = await this.client.downloadDriveItem(graphId);
+        const buffer = Buffer.from(content);
+        fs.writeFileSync(outputPath, buffer);
+        return { savedPath: outputPath, size: buffer.length };
+    }
+    /**
+     * Uploads a local file to OneDrive.
+     */
+    async uploadFileAsync(parentPath, fileName, localFilePath) {
+        const content = fs.readFileSync(localFilePath);
+        const result = await this.client.uploadDriveItem(parentPath, fileName, content);
+        const resultId = result.id;
+        const numericId = hashStringToNumber(resultId);
+        this.idCache.driveItems.set(numericId, resultId);
+        return numericId;
+    }
+    /**
+     * Lists recently accessed drive items.
+     */
+    async listRecentFilesAsync() {
+        const items = await this.client.listRecentDriveItems();
+        return items.map((item) => {
+            const itemId = item.id;
+            const numericId = hashStringToNumber(itemId);
+            this.idCache.driveItems.set(numericId, itemId);
+            return {
+                id: numericId,
+                name: item.name ?? '',
+                size: item.size ?? 0,
+                lastModified: item.lastModifiedDateTime ?? '',
+                isFolder: item.folder != null,
+                webUrl: item.webUrl ?? '',
+            };
+        });
+    }
+    /**
+     * Lists drive items shared with the user.
+     */
+    async listSharedWithMeAsync() {
+        const items = await this.client.listSharedWithMe();
+        return items.map((item) => {
+            const itemId = item.id;
+            const numericId = hashStringToNumber(itemId);
+            this.idCache.driveItems.set(numericId, itemId);
+            return {
+                id: numericId,
+                name: item.name ?? '',
+                size: item.size ?? 0,
+                lastModified: item.lastModifiedDateTime ?? '',
+                isFolder: item.folder != null,
+                webUrl: item.webUrl ?? '',
+            };
+        });
+    }
+    /**
+     * Creates a sharing link for a drive item.
+     */
+    async createSharingLinkAsync(itemId, type, scope) {
+        const graphId = this.idCache.driveItems.get(itemId);
+        if (graphId == null)
+            throw new Error(`Drive item ID ${itemId} not found in cache. Try listing drive items first.`);
+        const result = await this.client.createSharingLink(graphId, type, scope);
+        const link = result.link;
+        return {
+            webUrl: link?.webUrl ?? '',
+            type: link?.type ?? type,
+            scope: link?.scope ?? scope,
+        };
+    }
+    /**
+     * Deletes a drive item.
+     */
+    async deleteDriveItemAsync(itemId) {
+        const graphId = this.idCache.driveItems.get(itemId);
+        if (graphId == null)
+            throw new Error(`Drive item ID ${itemId} not found in cache. Try listing drive items first.`);
+        await this.client.deleteDriveItem(graphId);
+        this.idCache.driveItems.delete(itemId);
+    }
+    // ===========================================================================
+    // SharePoint Sites & Document Libraries
+    // ===========================================================================
+    /**
+     * Lists followed SharePoint sites, caching IDs.
+     */
+    async listSitesAsync() {
+        const sites = await this.client.listFollowedSites();
+        const result = [];
+        for (const site of sites) {
+            const siteId = site.id;
+            if (siteId != null) {
+                const numericId = hashStringToNumber(siteId);
+                this.idCache.sites.set(numericId, siteId);
+                result.push({
+                    id: numericId,
+                    name: site.name ?? '',
+                    webUrl: site.webUrl ?? '',
+                    displayName: site.displayName ?? '',
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Searches SharePoint sites by keyword, caching IDs.
+     */
+    async searchSitesAsync(query) {
+        const sites = await this.client.searchSites(query);
+        const result = [];
+        for (const site of sites) {
+            const siteId = site.id;
+            if (siteId != null) {
+                const numericId = hashStringToNumber(siteId);
+                this.idCache.sites.set(numericId, siteId);
+                result.push({
+                    id: numericId,
+                    name: site.name ?? '',
+                    webUrl: site.webUrl ?? '',
+                    displayName: site.displayName ?? '',
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Gets details for a specific SharePoint site.
+     */
+    async getSiteAsync(siteId) {
+        const graphId = this.idCache.sites.get(siteId);
+        if (graphId == null)
+            throw new Error(`Site ID ${siteId} not found in cache. Try listing or searching sites first.`);
+        const site = await this.client.getSite(graphId);
+        return {
+            id: siteId,
+            name: site.name ?? '',
+            webUrl: site.webUrl ?? '',
+            displayName: site.displayName ?? '',
+            description: site.description ?? '',
+        };
+    }
+    /**
+     * Lists document libraries for a SharePoint site, caching IDs.
+     */
+    async listDocumentLibrariesAsync(siteId) {
+        const graphSiteId = this.idCache.sites.get(siteId);
+        if (graphSiteId == null)
+            throw new Error(`Site ID ${siteId} not found in cache. Try listing or searching sites first.`);
+        const drives = await this.client.listDocumentLibraries(graphSiteId);
+        const result = [];
+        for (const drive of drives) {
+            const driveId = drive.id;
+            if (driveId != null) {
+                const numericId = hashStringToNumber(driveId);
+                this.idCache.documentLibraries.set(numericId, { siteId: graphSiteId, driveId });
+                result.push({
+                    id: numericId,
+                    name: drive.name ?? '',
+                    webUrl: drive.webUrl ?? '',
+                    driveType: drive.driveType ?? '',
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Lists items in a document library or folder, caching IDs.
+     */
+    async listLibraryItemsAsync(libraryId, folderId) {
+        const libCached = this.idCache.documentLibraries.get(libraryId);
+        if (libCached == null)
+            throw new Error(`Library ID ${libraryId} not found in cache. Try listing document libraries first.`);
+        let folderItemId;
+        if (folderId != null) {
+            const folderCached = this.idCache.libraryDriveItems.get(folderId);
+            if (folderCached == null)
+                throw new Error(`Folder ID ${folderId} not found in cache. Try listing library items first.`);
+            folderItemId = folderCached.itemId;
+        }
+        const items = await this.client.listLibraryItems(libCached.driveId, folderItemId);
+        const result = [];
+        for (const item of items) {
+            const itemGraphId = item.id;
+            if (itemGraphId != null) {
+                const numericId = hashStringToNumber(itemGraphId);
+                this.idCache.libraryDriveItems.set(numericId, { driveId: libCached.driveId, itemId: itemGraphId });
+                result.push({
+                    id: numericId,
+                    name: item.name ?? '',
+                    size: item.size ?? 0,
+                    webUrl: item.webUrl ?? '',
+                    lastModifiedDateTime: item.lastModifiedDateTime ?? '',
+                    isFolder: item.folder != null,
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Downloads a file from a document library to the specified path.
+     */
+    async downloadLibraryFileAsync(itemId, outputPath) {
+        const cached = this.idCache.libraryDriveItems.get(itemId);
+        if (cached == null)
+            throw new Error(`Item ID ${itemId} not found in cache. Try listing library items first.`);
+        const content = await this.client.downloadLibraryFile(cached.driveId, cached.itemId);
+        const resolvedPath = path.resolve(outputPath);
+        const dir = path.dirname(resolvedPath);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(resolvedPath, Buffer.from(content));
+        return resolvedPath;
+    }
+    /**
+     * Gets the Graph string ID for a folder from the cache.
+     */
+    getFolderGraphId(folderId) {
+        return this.idCache.folders.get(folderId);
+    }
+}
+/**
+ * Creates a Microsoft Graph API repository.
+ */
+export function createGraphRepository(deviceCodeCallback) {
+    return new GraphRepository(deviceCodeCallback);
+}
+//# sourceMappingURL=repository.js.map