@jbctechsolutions/mcp-office365 3.0.0 → 4.0.1

package/dist/graph/client/graph-client.js

@@ -16,6 +16,7 @@ import { Client, ResponseType, AuthenticationHandler, RetryHandler, RetryHandler
 import { getAccessToken } from '../auth/index.js';
 import { buildBatchPayload, splitIntoBatches, parseBatchResponse } from './batch.js';
 import { ResponseCache, CacheTTL, createCacheKey } from './cache.js';
+import { ImmutableIdMiddleware } from './immutable-id-middleware.js';
 // The SDK's RetryHandler only considers 429/503/504 retriable (its private
 // static RETRY_STATUS_CODES), gating `this.isRetry(response)` BEFORE our
 // shouldRetry callback runs — so a callback can only *narrow* that set, never
@@ -79,15 +80,19 @@ export class GraphClient {
                 return shouldRetryGraphRequest(method, url, response?.status ?? 0);
             };
             // Chain mirrors the SDK default order (auth → retry → redirect → http),
-            // minus the cosmetic TelemetryHandler. RedirectHandler matters: the
-            // binary download endpoints (/content, /photo/$value, meeting recordings)
-            // 302 to a pre-authenticated CDN URL, so the redirect must be followed
-            // explicitly rather than relying on the underlying fetch default.
+            // minus the cosmetic TelemetryHandler, plus the immutable-ID preference
+            // (U5b-3) sitting right after auth so its Prefer header rides every retry
+            // attempt without being re-appended. RedirectHandler matters: the binary
+            // download endpoints (/content, /photo/$value, meeting recordings) 302 to
+            // a pre-authenticated CDN URL, so the redirect must be followed explicitly
+            // rather than relying on the underlying fetch default.
             const auth = new AuthenticationHandler(authProvider);
+            const immutableId = new ImmutableIdMiddleware();
             const retry = new RetryHandler(new RetryHandlerOptions(undefined, undefined, shouldRetry));
             const redirect = new RedirectHandler();
             const http = new HTTPMessageHandler();
-            auth.setNext(retry);
+            auth.setNext(immutableId);
+            immutableId.setNext(retry);
             retry.setNext(redirect);
             redirect.setNext(http);
             this.client = Client.initWithMiddleware({ middleware: auth });
@@ -207,7 +212,9 @@ export class GraphClient {
             .select('id,subject,from,toRecipients,ccRecipients,receivedDateTime,sentDateTime,isRead,hasAttachments,importance,flag,bodyPreview,conversationId,internetMessageId,parentFolderId')
             .top(limit)
             .get();
-        return response.value;
+        const messages = response.value;
+        await this.upgradeMessageIdsToImmutable(messages);
+        return messages;
     }
     /**
      * Searches messages in a specific folder.
@@ -220,7 +227,9 @@ export class GraphClient {
             .select('id,subject,from,toRecipients,ccRecipients,receivedDateTime,sentDateTime,isRead,hasAttachments,importance,flag,bodyPreview,conversationId,internetMessageId')
             .top(limit)
             .get();
-        return response.value;
+        const messages = response.value;
+        await this.upgradeMessageIdsToImmutable(messages);
+        return messages;
     }
     /**
      * Property-only structured search (U7 / D9): `$filter` on messages. The filter
@@ -252,7 +261,9 @@ export class GraphClient {
             .select(MESSAGE_SEARCH_SELECT)
             .top(limit)
             .get();
-        return response.value;
+        const messages = response.value;
+        await this.upgradeMessageIdsToImmutable(messages);
+        return messages;
     }
     /**
      * Mixed property + free-text structured search (U7 / D9): `POST /search/query`
@@ -281,7 +292,77 @@ export class GraphClient {
         const response = (await client.api('/search/query').post(body));
         const hits = response.value?.[0]?.hitsContainers?.[0]?.hits ?? [];
         // Guard against a hit without a resource so no undefined enters the mapper.
-        return hits.map((h) => h.resource).filter((r) => r != null);
+        const messages = hits.map((h) => h.resource).filter((r) => r != null);
+        await this.upgradeMessageIdsToImmutable(messages);
+        return messages;
+    }
+    /**
+     * Translates Exchange item IDs between formats (U5b-3 / D2). Used to upgrade
+     * the mutable REST IDs that `$search` returns into immutable REST entry IDs, so
+     * search-minted self-encoding tokens (`em_`) survive a later move. Returns a map
+     * of source ID → immutable target ID; IDs that Graph could not translate are
+     * simply absent (partial success is normal and handled by the caller).
+     */
+    async translateExchangeIds(inputIds, sourceIdType = 'restId', targetIdType = 'restImmutableEntryId') {
+        const out = new Map();
+        if (inputIds.length === 0) {
+            return out;
+        }
+        const client = await this.getClient();
+        // Graph caps translateExchangeIds at 1000 input IDs per call; chunk to stay
+        // under it even though search result sets are far smaller.
+        for (let i = 0; i < inputIds.length; i += 1000) {
+            const chunk = inputIds.slice(i, i + 1000);
+            const response = (await client.api('/me/translateExchangeIds').post({
+                inputIds: chunk,
+                sourceIdType,
+                targetIdType,
+            }));
+            for (const pair of response.value ?? []) {
+                if (pair.sourceId != null && pair.sourceId.length > 0 && pair.targetId != null && pair.targetId.length > 0) {
+                    out.set(pair.sourceId, pair.targetId);
+                }
+            }
+        }
+        return out;
+    }
+    /**
+     * Rewrites the mutable `$search`-minted IDs on a message list to their
+     * immutable equivalents in place (U5b-3 / D2), so the mapper mints durable
+     * `em_` tokens. Graceful degradation: if translation fails wholesale (throw) or
+     * for individual IDs (absent from the map), those messages keep their mutable
+     * ID — the `em_` token still resolves this session, it just isn't move-durable.
+     * Returns the number of IDs left un-upgraded (the caller's `degraded_ids` count).
+     */
+    async upgradeMessageIdsToImmutable(messages) {
+        const mutableIds = messages
+            .map((m) => m.id)
+            .filter((id) => typeof id === 'string' && id.length > 0);
+        if (mutableIds.length === 0) {
+            return 0;
+        }
+        let translated;
+        try {
+            translated = await this.translateExchangeIds(mutableIds);
+        }
+        catch {
+            // Whole-batch failure (throttled/unavailable): leave every ID mutable.
+            return mutableIds.length;
+        }
+        let degraded = 0;
+        for (const message of messages) {
+            if (typeof message.id !== 'string' || message.id.length === 0) {
+                continue;
+            }
+            const immutable = translated.get(message.id);
+            if (immutable != null) {
+                message.id = immutable;
+            }
+            else {
+                degraded += 1;
+            }
+        }
+        return degraded;
     }
     /**
      * Lists messages in a conversation by conversationId.
@@ -317,27 +398,62 @@ export class GraphClient {
      */
     async getMessagesDelta(folderId, deltaLink) {
         const client = await this.getClient();
-        let response;
+        let page;
         if (deltaLink != null) {
-            response = await client.api(deltaLink).get();
+            page = await client.api(deltaLink).get();
         }
         else {
-            response = await client
+            page = await client
                 .api(`/me/mailFolders/${folderId}/messages/delta`)
                 .select('id,subject,from,toRecipients,ccRecipients,receivedDateTime,sentDateTime,isRead,hasAttachments,importance,flag,bodyPreview,conversationId,internetMessageId,parentFolderId')
                 .top(50)
                 .get();
         }
-        const messages = [...(response.value ?? [])];
-        let nextLink = response['@odata.nextLink'];
+        const messages = [...(page.value ?? [])];
+        // The deltaLink lands on the LAST page; paging through nextLinks and reading
+        // it from the first response would yield '' whenever the delta spans >1 page.
+        let nextLink = page['@odata.nextLink'];
         while (nextLink != null) {
-            const nextPage = await client.api(nextLink).get();
-            messages.push(...(nextPage.value ?? []));
-            nextLink = nextPage['@odata.nextLink'];
+            page = await client.api(nextLink).get();
+            messages.push(...(page.value ?? []));
+            nextLink = page['@odata.nextLink'];
         }
-        const newDeltaLink = response['@odata.deltaLink'] ?? '';
+        const newDeltaLink = page['@odata.deltaLink'] ?? '';
         return { messages, deltaLink: newDeltaLink };
     }
+    /**
+     * Gets calendar-view delta for incremental event sync (U12).
+     *
+     * The v1.0 event delta is served by `/me/calendarView/delta`, bounded by a
+     * start/end window that is baked into the returned deltaLink — subsequent
+     * rounds just follow that link. `$select` is unsupported here, so full event
+     * objects come back; deletes arrive as `@removed` entries. The deltaLink lands
+     * on the *last* page, so it is read after paging (not from the first response).
+     */
+    async getCalendarViewDelta(startDateTime, endDateTime, deltaLink) {
+        const client = await this.getClient();
+        let page;
+        if (deltaLink != null) {
+            page = await client.api(deltaLink).get();
+        }
+        else {
+            const start = encodeURIComponent(startDateTime);
+            const end = encodeURIComponent(endDateTime);
+            page = await client
+                .api(`/me/calendarView/delta?startDateTime=${start}&endDateTime=${end}`)
+                .header('Prefer', 'odata.maxpagesize=50')
+                .get();
+        }
+        const events = [...(page.value ?? [])];
+        let nextLink = page['@odata.nextLink'];
+        while (nextLink != null) {
+            page = await client.api(nextLink).get();
+            events.push(...(page.value ?? []));
+            nextLink = page['@odata.nextLink'];
+        }
+        const newDeltaLink = page['@odata.deltaLink'] ?? '';
+        return { events, deltaLink: newDeltaLink };
+    }
     // ===========================================================================
     // Mail Rules
     // ===========================================================================
@@ -1583,6 +1699,10 @@ export class GraphClient {
         const client = await this.getClient();
         return await client.api('/planner/buckets').post({ planId, name });
     }
+    async getBucket(bucketId) {
+        const client = await this.getClient();
+        return await client.api(`/planner/buckets/${bucketId}`).get();
+    }
     async updateBucket(bucketId, updates, etag) {
         const client = await this.getClient();
         return await client.api(`/planner/buckets/${bucketId}`).header('If-Match', etag).patch(updates);
@@ -1599,6 +1719,12 @@ export class GraphClient {
         const response = await client.api(`/planner/plans/${planId}/tasks`).get();
         return response.value;
     }
+    /** All Planner tasks assigned to the signed-in user, across every plan. */
+    async listMyPlannerTasks() {
+        const client = await this.getClient();
+        const response = await client.api('/me/planner/tasks').get();
+        return response.value;
+    }
     async getPlannerTask(taskId) {
         const client = await this.getClient();
         return await client.api(`/planner/tasks/${taskId}`).get();
@@ -1662,6 +1788,116 @@ export class GraphClient {
         const response = await client.api('/communications/getPresencesByUserId').post({ ids: userIds });
         return response.value;
     }
+    // ===========================================================================
+    // Shared Mailbox / Delegate Access (/users/{upn}/...) — read-only (#40)
+    // ===========================================================================
+    //
+    // These mirror the `/me/...` read paths but target another user's mailbox,
+    // calendar, or drive via delegate/shared access. Unlike the `/me` variants,
+    // they deliberately DO NOT swallow errors: a 403 must surface (mapped to
+    // GRAPH_PERMISSION_DENIED at the dispatch chokepoint) so the caller learns
+    // they lack shared access rather than getting a silent empty/`null` result.
+    // Results are returned with raw Graph ids (durable tokens are `/me`- and
+    // account-scoped, so they cannot address another mailbox's items).
+    async listSharedMailFolders(mailbox) {
+        const client = await this.getClient();
+        const response = await client
+            .api(`/users/${encodeURIComponent(mailbox)}/mailFolders`)
+            .select('id,displayName,parentFolderId,totalItemCount,unreadItemCount')
+            .top(100)
+            .get();
+        return response.value;
+    }
+    async listSharedMessages(mailbox, folderId, limit = 25, unreadOnly = false) {
+        const client = await this.getClient();
+        const apiPath = folderId != null
+            ? `/users/${encodeURIComponent(mailbox)}/mailFolders/${encodeURIComponent(folderId)}/messages`
+            : `/users/${encodeURIComponent(mailbox)}/messages`;
+        let request = client
+            .api(apiPath)
+            .select('id,subject,from,toRecipients,ccRecipients,receivedDateTime,sentDateTime,isRead,hasAttachments,importance,flag,bodyPreview,conversationId')
+            .top(limit);
+        if (unreadOnly) {
+            // Graph rejects `$orderby` on a property not led by `$filter` (isRead),
+            // so drop the sort when filtering unread and rely on the default order.
+            request = request.filter('isRead eq false');
+        }
+        else {
+            request = request.orderby('receivedDateTime desc');
+        }
+        const response = await request.get();
+        return response.value;
+    }
+    async getSharedMessage(mailbox, messageId, includeBody = false) {
+        const client = await this.getClient();
+        const select = includeBody
+            ? 'id,subject,from,toRecipients,ccRecipients,receivedDateTime,sentDateTime,isRead,hasAttachments,importance,flag,body,bodyPreview,conversationId,parentFolderId'
+            : 'id,subject,from,toRecipients,ccRecipients,receivedDateTime,sentDateTime,isRead,hasAttachments,importance,flag,bodyPreview,conversationId,parentFolderId';
+        return await client
+            .api(`/users/${encodeURIComponent(mailbox)}/messages/${encodeURIComponent(messageId)}`)
+            .select(select)
+            .get();
+    }
+    async searchSharedMessages(mailbox, query, limit = 25) {
+        const client = await this.getClient();
+        // Mail $search cannot be combined with $orderby, so ordering is omitted.
+        // Strip embedded double quotes so a stray `"` can't break out of the
+        // quoted KQL `$search="..."` term.
+        const safeQuery = query.replace(/"/g, ' ');
+        const response = await client
+            .api(`/users/${encodeURIComponent(mailbox)}/messages`)
+            .query({ $search: `"${safeQuery}"` })
+            .select('id,subject,from,toRecipients,ccRecipients,receivedDateTime,sentDateTime,isRead,hasAttachments,importance,flag,bodyPreview,conversationId')
+            .top(limit)
+            .get();
+        return response.value;
+    }
+    async listSharedEvents(mailbox, limit = 25, startDate, endDate) {
+        const client = await this.getClient();
+        if (startDate != null && endDate != null) {
+            const response = await client
+                .api(`/users/${encodeURIComponent(mailbox)}/calendarView`)
+                .query({ startDateTime: startDate.toISOString(), endDateTime: endDate.toISOString() })
+                .select('id,subject,start,end,location,isAllDay,organizer,attendees,bodyPreview')
+                .orderby('start/dateTime')
+                .top(limit)
+                .get();
+            return response.value;
+        }
+        const response = await client
+            .api(`/users/${encodeURIComponent(mailbox)}/events`)
+            .select('id,subject,start,end,location,isAllDay,organizer,attendees,bodyPreview')
+            .orderby('start/dateTime')
+            .top(limit)
+            .get();
+        return response.value;
+    }
+    async getSharedEvent(mailbox, eventId) {
+        const client = await this.getClient();
+        return await client
+            .api(`/users/${encodeURIComponent(mailbox)}/events/${encodeURIComponent(eventId)}`)
+            .select('id,subject,start,end,location,isAllDay,organizer,attendees,body,recurrence,bodyPreview')
+            .get();
+    }
+    async listSharedDriveItems(mailbox, itemId) {
+        const client = await this.getClient();
+        const apiPath = itemId != null
+            ? `/users/${encodeURIComponent(mailbox)}/drive/items/${encodeURIComponent(itemId)}/children`
+            : `/users/${encodeURIComponent(mailbox)}/drive/root/children`;
+        const response = await client.api(apiPath).get();
+        return response.value;
+    }
+    async searchSharedDriveItems(mailbox, query, limit = 25) {
+        const client = await this.getClient();
+        // Escape for the OData string literal first (a lone `'` closes the literal;
+        // OData escapes it by doubling), then URL-encode the whole term.
+        const safeQuery = encodeURIComponent(query.replace(/'/g, "''"));
+        const response = await client
+            .api(`/users/${encodeURIComponent(mailbox)}/drive/root/search(q='${safeQuery}')`)
+            .top(limit)
+            .get();
+        return response.value;
+    }
     /**
      * Sends multiple requests in a single $batch call to the Graph API.
      * Automatically splits into multiple batches if there are more than 20 requests.
@@ -1853,6 +2089,166 @@ export class GraphClient {
         const client = await this.getClient();
         return await client.api(`/drives/${driveId}/items/${itemId}/content`).responseType(ResponseType.ARRAYBUFFER).get();
     }
+    // ===========================================================================
+    // SharePoint Lists
+    // ===========================================================================
+    /**
+     * Lists the SharePoint lists in a site.
+     */
+    async listSharePointLists(siteId) {
+        const client = await this.getClient();
+        const response = await client
+            .api(`/sites/${siteId}/lists`)
+            .select('id,name,displayName,description,webUrl,createdDateTime,lastModifiedDateTime')
+            .get();
+        return response.value;
+    }
+    /**
+     * Gets a specific SharePoint list.
+     */
+    async getSharePointList(siteId, listId) {
+        const client = await this.getClient();
+        return await client.api(`/sites/${siteId}/lists/${listId}`).get();
+    }
+    /**
+     * Creates a SharePoint list in a site.
+     */
+    async createSharePointList(siteId, body) {
+        const client = await this.getClient();
+        return await client.api(`/sites/${siteId}/lists`).post(body);
+    }
+    /**
+     * Lists the column definitions for a SharePoint list.
+     */
+    async listSharePointListColumns(siteId, listId) {
+        const client = await this.getClient();
+        const response = await client
+            .api(`/sites/${siteId}/lists/${listId}/columns`)
+            .get();
+        return response.value;
+    }
+    /**
+     * Lists the items in a SharePoint list, expanding their field values.
+     */
+    async listSharePointListItems(siteId, listId, limit = 50) {
+        const client = await this.getClient();
+        const response = await client
+            .api(`/sites/${siteId}/lists/${listId}/items`)
+            .expand('fields')
+            .top(limit)
+            .get();
+        return response.value;
+    }
+    /**
+     * Gets a specific SharePoint list item, expanding its field values.
+     */
+    async getSharePointListItem(siteId, listId, itemId) {
+        const client = await this.getClient();
+        return await client
+            .api(`/sites/${siteId}/lists/${listId}/items/${itemId}`)
+            .expand('fields')
+            .get();
+    }
+    /**
+     * Creates an item in a SharePoint list from a map of column → value.
+     */
+    async createSharePointListItem(siteId, listId, fields) {
+        const client = await this.getClient();
+        return await client.api(`/sites/${siteId}/lists/${listId}/items`).post({ fields });
+    }
+    /**
+     * Updates the field values of a SharePoint list item.
+     */
+    async updateSharePointListItem(siteId, listId, itemId, fields) {
+        const client = await this.getClient();
+        return await client.api(`/sites/${siteId}/lists/${listId}/items/${itemId}/fields`).patch(fields);
+    }
+    /**
+     * Deletes an item from a SharePoint list.
+     */
+    async deleteSharePointListItem(siteId, listId, itemId) {
+        const client = await this.getClient();
+        await client.api(`/sites/${siteId}/lists/${listId}/items/${itemId}`).delete();
+    }
+    // ===========================================================================
+    // OneNote
+    // ===========================================================================
+    /**
+     * Lists all OneNote notebooks for the current user.
+     */
+    async listNotebooks() {
+        const client = await this.getClient();
+        const response = await client.api('/me/onenote/notebooks').get();
+        return response.value;
+    }
+    /**
+     * Lists OneNote sections, optionally scoped to a notebook.
+     */
+    async listNoteSections(notebookGraphId) {
+        const client = await this.getClient();
+        const apiPath = notebookGraphId != null
+            ? `/me/onenote/notebooks/${notebookGraphId}/sections`
+            : '/me/onenote/sections';
+        const response = await client.api(apiPath).get();
+        return response.value;
+    }
+    /**
+     * Lists OneNote pages, optionally scoped to a section.
+     */
+    async listNotePages(sectionGraphId) {
+        const client = await this.getClient();
+        if (sectionGraphId != null) {
+            const response = await client.api(`/me/onenote/sections/${sectionGraphId}/pages`).get();
+            return response.value;
+        }
+        const response = await client
+            .api('/me/onenote/pages')
+            .top(50)
+            .orderby('lastModifiedDateTime desc')
+            .get();
+        return response.value;
+    }
+    /**
+     * Gets a OneNote page's metadata.
+     */
+    async getNotePage(pageGraphId) {
+        const client = await this.getClient();
+        return await client.api(`/me/onenote/pages/${pageGraphId}`).get();
+    }
+    /**
+     * Gets a OneNote page's HTML content.
+     */
+    async getNotePageContent(pageGraphId) {
+        const client = await this.getClient();
+        return await client
+            .api(`/me/onenote/pages/${pageGraphId}/content`)
+            .responseType(ResponseType.TEXT)
+            .get();
+    }
+    /**
+     * Searches OneNote pages by keyword.
+     */
+    async searchNotePages(query) {
+        const client = await this.getClient();
+        // Strip embedded double-quotes so they can't unbalance the quoted $search
+        // expression (`$search="..."`) and 400 the request.
+        const safeQuery = query.replace(/"/g, '');
+        const response = await client
+            .api('/me/onenote/pages')
+            .search(`"${safeQuery}"`)
+            .get();
+        return response.value;
+    }
+    /**
+     * Creates a new OneNote page in a section from raw HTML.
+     */
+    async createNotePage(sectionGraphId, html) {
+        const client = await this.getClient();
+        return await client
+            .api(`/me/onenote/sections/${sectionGraphId}/pages`)
+            .header('Content-Type', 'text/html')
+            .post(html);
+    }
 }
 /**
  * Creates a new Graph client instance.