@memberjunction/communication-ms-graph 6.1.0-edge.5 → 6.1.0-edge.7

package/README.md

@@ -60,11 +60,17 @@ AZURE_ACCOUNT_EMAIL=mailbox@yourdomain.com
 | `Mail.Send` | SendSingleMessage, ForwardMessage, ReplyToMessage |
 | `Mail.Read` | GetMessages, GetSingleMessage, SearchMessages, ListFolders, ListAttachments, DownloadAttachment |
 | `Mail.ReadWrite` | CreateDraft, DeleteMessage, MoveMessage, MarkAsRead, ArchiveMessage |
+| `Calendars.Read` | GetEvents |
 | `User.Read.All` | GetServiceAccount (user lookup, optional) |
 
+`Calendars.Read` is sufficient for `GetEvents`; `Calendars.ReadWrite` is not required, since nothing
+here creates or modifies an event. As **Application** permissions these are granted against the
+tenant, not against one mailbox — narrowing an app to specific mailboxes is done in Exchange with
+RBAC for Applications, not by these grants.
+
 ## Supported Operations
 
-This provider supports all 14 operations defined in `BaseCommunicationProvider`:
+This provider supports all 15 operations defined in `BaseCommunicationProvider`:
 
 | Operation | Description |
 |-----------|-------------|
@@ -82,6 +88,7 @@ This provider supports all 14 operations defined in `BaseCommunicationProvider`:
 | `SearchMessages` | Full-text search with KQL syntax and date filtering |
 | `ListAttachments` | List attachments on a message |
 | `DownloadAttachment` | Download attachment content as base64/Buffer |
+| `GetEvents` | Read calendar events for one mailbox |
 
 ## Usage
 
@@ -151,6 +158,39 @@ result.Messages.forEach(msg => {
 });
 ```
 
+### Reading Calendar Events
+
+Requires `Calendars.Read`. **Whether you pass a window changes what comes back**, so `GetEvents`
+reports which it did via `RecurrenceExpanded` rather than leaving you to guess:
+
+```typescript
+const provider = engine.GetProvider('Microsoft Graph');
+
+// With a window -> /calendarView: a recurring series is EXPANDED into one entry per occurrence.
+const occurrences = await provider.GetEvents({
+    Identifier: 'rep@example.com',
+    NumEvents: 50,
+    StartDateTime: new Date('2026-09-01T00:00:00Z'),
+    EndDateTime: new Date('2026-09-08T00:00:00Z')
+});
+console.log(occurrences.RecurrenceExpanded); // true
+
+// Without one -> /events: a weekly stand-up is ONE row, the series master, whose start time is
+// whenever the series began — possibly years ago.
+const masters = await provider.GetEvents({ Identifier: 'rep@example.com', NumEvents: 50 });
+console.log(masters.RecurrenceExpanded); // false
+```
+
+Three things worth knowing before syncing on this:
+
+- **The window selects overlap, not start times.** An event that began before `StartDateTime` and is
+  still running when the window opens is returned. An event straddling a boundary therefore appears
+  in both adjacent windows — dedupe on the event id.
+- **`NumEvents` is one page.** It becomes `$top`; there is no `@odata.nextLink` following. To cover a
+  period completely, narrow the window rather than raise the number.
+- **Cancelled events are excluded by default** and cannot be recovered after the fact — Graph does not
+  return them once filtered. Pass `IncludeCancelled: true` if you are logging history.
+
 ### Searching Messages
 
 MS Graph supports KQL (Keyword Query Language) for search:

package/dist/MSGraphProvider.d.ts

@@ -1,4 +1,4 @@
-import { BaseCommunicationProvider, CreateDraftParams, CreateDraftResult, ForwardMessageParams, ForwardMessageResult, GetMessagesParams, GetMessagesResult, GetSingleMessageParams, GetSingleMessageResult, DeleteMessageParams, DeleteMessageResult, MoveMessageParams, MoveMessageResult, ListFoldersParams, ListFoldersResult, MarkAsReadParams, MarkAsReadResult, ArchiveMessageParams, ArchiveMessageResult, SearchMessagesParams, SearchMessagesResult, ListAttachmentsParams, ListAttachmentsResult, DownloadAttachmentParams, DownloadAttachmentResult, ProviderOperation, MessageResult, ProcessedMessage, ProviderCredentialsBase, ReplyToMessageParams, ReplyToMessageResult, CreateSubscriptionParams, RenewSubscriptionParams, DeleteSubscriptionParams, SubscriptionResult, SubscriptionCapabilities, WebhookNotificationInput, ParseNotificationResult, BaseMessageResult } from "@memberjunction/communication-types";
+import { BaseCommunicationProvider, MessageRetrievalCapabilities, CreateDraftParams, CreateDraftResult, ForwardMessageParams, ForwardMessageResult, GetEventsParams, GetEventsResult, GetMessagesParams, GetMessagesResult, GetSingleMessageParams, GetSingleMessageResult, DeleteMessageParams, DeleteMessageResult, MoveMessageParams, MoveMessageResult, ListFoldersParams, ListFoldersResult, MarkAsReadParams, MarkAsReadResult, ArchiveMessageParams, ArchiveMessageResult, SearchMessagesParams, SearchMessagesResult, ListAttachmentsParams, ListAttachmentsResult, DownloadAttachmentParams, DownloadAttachmentResult, ProviderOperation, MessageResult, ProcessedMessage, ProviderCredentialsBase, ReplyToMessageParams, ReplyToMessageResult, CreateSubscriptionParams, RenewSubscriptionParams, DeleteSubscriptionParams, SubscriptionResult, SubscriptionCapabilities, WebhookNotificationInput, ParseNotificationResult, BaseMessageResult } from "@memberjunction/communication-types";
 import { Client } from '@microsoft/microsoft-graph-client';
 import { Message } from "@microsoft/microsoft-graph-types";
 /**
@@ -78,6 +78,11 @@ export interface MSGraphCredentials extends ProviderCredentialsBase {
  * ```
  */
 export declare class MSGraphProvider extends BaseCommunicationProvider {
+    /**
+     * Graph filters both of these server-side, so neither is emulated here — `receivedDateTime`
+     * comparisons and `isRead` are ordinary `$filter` clauses.
+     */
+    get MessageRetrieval(): MessageRetrievalCapabilities;
     private HTMLConverter;
     /**
      * Cache clients keyed by tenant + clientId. Bounded LRU(100) + 1-hour TTL —
@@ -90,6 +95,18 @@ export declare class MSGraphProvider extends BaseCommunicationProvider {
      * Resolves MS Graph credentials from request and environment.
      */
     private resolveCredentials;
+    /**
+     * The mailbox an operation will act on, or a refusal that says how to supply one.
+     *
+     * WHY THIS THROWS. Every caller interpolates the result into a Graph path. Returning `undefined`
+     * would put the literal string "undefined" in the URL and come back as a 404 that reads like
+     * "message not found" — a wrong answer that looks like a real one. This package does not enable
+     * `strictNullChecks`, so the compiler would not have caught that either.
+     *
+     * `credentials.accountEmail` is the LAST candidate on purpose: it is a default for the deployment,
+     * and anything the caller named for this specific request outranks it.
+     */
+    private resolveMailbox;
     /**
      * Gets or creates a Graph client for the given credentials.
      * Uses cached client if credentials match environment (default case).
@@ -208,6 +225,40 @@ export declare class MSGraphProvider extends BaseCommunicationProvider {
      * @requires MS Graph Scope: Mail.ReadWrite (Application)
      */
     CreateDraft(params: CreateDraftParams, credentials?: MSGraphCredentials): Promise<CreateDraftResult>;
+    /**
+     * Reads calendar events for one mailbox.
+     *
+     * @requires MS Graph Scope: Calendars.Read (Application)
+     *
+     * TWO ENDPOINTS, AND THE CHOICE IS VISIBLE TO THE CALLER. Graph exposes calendar data two ways
+     * and they do not return the same thing:
+     *
+     *   - `/calendarView` REQUIRES a start and end and EXPANDS recurring series into one entry per
+     *     occurrence. A weekly stand-up in a two-week window comes back as two events, each with its
+     *     own start time and id.
+     *   - `/events` needs no window and does NOT expand. That same stand-up is one row, the series
+     *     master, whose start time is whenever the series began - possibly years ago.
+     *
+     * A caller logging what actually happened wants occurrences; one asking "what meetings exist"
+     * may want masters. Silently picking would be a trap, because the two are indistinguishable by
+     * inspection - so the window decides, and `RecurrenceExpanded` on the result REPORTS which
+     * happened rather than leaving the caller to infer it.
+     *
+     * CANCELLED EVENTS ARE EXCLUDED BY DEFAULT and cannot be recovered afterwards - Graph does not
+     * return them once filtered - so `IncludeCancelled` is honoured before the `$top` cap rather
+     * than by discarding rows after the fetch, which would silently shrink the page.
+     */
+    GetEvents(params: GetEventsParams, credentials?: MSGraphCredentials): Promise<GetEventsResult>;
+    /**
+     * Graph event -> the normalized shape. Lossy by design; `SourceData` keeps the original.
+     *
+     * A start Graph cannot express as an instant becomes NULL rather than a guess. Graph returns
+     * naive local strings plus a separate timeZone, so a value with neither a zone suffix nor a UTC
+     * marker genuinely has no instant here, and inventing one would file a meeting at the wrong time.
+     */
+    private toGetEventsEvent;
+    /** A Graph date slot as an instant, or null when it does not determine one. */
+    private static graphInstant;
     /**
      * Returns the list of operations supported by MS Graph provider.
      * MS Graph supports all mailbox operations.

package/dist/MSGraphProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MSGraphProvider.d.ts","sourceRoot":"","sources":["../src/MSGraphProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"MSGraphProvider.d.ts","sourceRoot":"","sources":["../src/MSGraphProvider.ts"],"names":[],"mappings":"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"}

package/dist/MSGraphProvider.js

@@ -7,7 +7,8 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { BaseCommunicationProvider, resolveCredentialValue, validateRequiredCredentials } from "@memberjunction/communication-types";
+var MSGraphProvider_1;
+import { BaseCommunicationProvider, CombineFilterClauses, resolveCredentialValue, validateRequiredCredentials } from "@memberjunction/communication-types";
 import { Client } from '@microsoft/microsoft-graph-client';
 import { ClientSecretCredential } from '@azure/identity';
 import { TokenCredentialAuthenticationProvider } from "@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials/index.js";
@@ -20,6 +21,16 @@ import * as Config from "./config.js";
  * The maximum lifetime, in minutes, that Microsoft Graph allows for a mail-resource
  * change-notification subscription (~3 days). Requested expirations are clamped to this.
  */
+/**
+ * Format an instant the way an OData `$filter` comparison wants it: ISO-8601, UTC, UNQUOTED.
+ *
+ * Quoting it makes Graph compare a datetime against a string and reject the request, which is the
+ * mistake this exists to keep out of the call sites. `toISOString` is always UTC with a trailing Z
+ * regardless of the Date's origin, so a caller passing a local-time Date still filters correctly.
+ */
+function ODataInstant(when) {
+    return when.toISOString();
+}
 const MSGRAPH_MAX_SUBSCRIPTION_MINUTES = 4230;
 /**
  * Implementation of the MS Graph provider for sending and receiving messages.
@@ -46,7 +57,14 @@ const MSGRAPH_MAX_SUBSCRIPTION_MINUTES = 4230;
  * });
  * ```
  */
-let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
+let MSGraphProvider = MSGraphProvider_1 = class MSGraphProvider extends BaseCommunicationProvider {
+    /**
+     * Graph filters both of these server-side, so neither is emulated here — `receivedDateTime`
+     * comparisons and `isRead` are ordinary `$filter` clauses.
+     */
+    get MessageRetrieval() {
+        return { FilterByReceivedDate: true, FilterByUnread: true };
+    }
     constructor() {
         super();
         /**
@@ -71,7 +89,12 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         const clientId = resolveCredentialValue(credentials?.clientId, Config.AZURE_CLIENT_ID, disableFallback);
         const clientSecret = resolveCredentialValue(credentials?.clientSecret, Config.AZURE_CLIENT_SECRET, disableFallback);
         const accountEmail = resolveCredentialValue(credentials?.accountEmail, Config.AZURE_ACCOUNT_EMAIL, disableFallback);
-        validateRequiredCredentials({ tenantId, clientId, clientSecret, accountEmail }, ['tenantId', 'clientId', 'clientSecret', 'accountEmail'], 'Microsoft Graph');
+        // The THREE authentication fields, which is exactly what a service principal is and exactly
+        // what the `Azure Service Principal` credential type declares. `accountEmail` used to be
+        // required here, which made every stored credential of that type unusable: there was no
+        // fourth field for an operator to fill in, so every operation failed before doing anything.
+        // A mailbox is resolved per operation instead — see `resolveMailbox`.
+        validateRequiredCredentials({ tenantId, clientId, clientSecret }, ['tenantId', 'clientId', 'clientSecret'], 'Microsoft Graph');
         return {
             tenantId: tenantId,
             clientId: clientId,
@@ -79,6 +102,25 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
             accountEmail: accountEmail
         };
     }
+    /**
+     * The mailbox an operation will act on, or a refusal that says how to supply one.
+     *
+     * WHY THIS THROWS. Every caller interpolates the result into a Graph path. Returning `undefined`
+     * would put the literal string "undefined" in the URL and come back as a 404 that reads like
+     * "message not found" — a wrong answer that looks like a real one. This package does not enable
+     * `strictNullChecks`, so the compiler would not have caught that either.
+     *
+     * `credentials.accountEmail` is the LAST candidate on purpose: it is a default for the deployment,
+     * and anything the caller named for this specific request outranks it.
+     */
+    resolveMailbox(operation, creds, ...preferred) {
+        for (const candidate of [...preferred, creds.accountEmail]) {
+            if (candidate && candidate.trim() !== '')
+                return candidate.trim();
+        }
+        throw new Error(`Microsoft Graph: ${operation} needs a mailbox and none was supplied. Pass one on the ` +
+            `request, or set accountEmail on the credential (or AZURE_ACCOUNT_EMAIL) as a default.`);
+    }
     /**
      * Gets or creates a Graph client for the given credentials.
      * Uses cached client if credentials match environment (default case).
@@ -129,12 +171,9 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
             // Smart selection: use message.From if provided and different from resolved accountEmail
-            let senderEmail = creds.accountEmail;
-            if (message.From &&
-                message.From.trim() !== '' &&
-                message.From !== creds.accountEmail) {
-                senderEmail = message.From;
-            }
+            // Whatever the caller named outranks the credential default; a request that names
+            // neither is refused here rather than sending from "undefined".
+            const senderEmail = this.resolveMailbox('SendSingleMessage', creds, message.From);
             if (!message) {
                 return {
                     Message: message,
@@ -237,8 +276,13 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
                 },
                 comment: params.Message.ProcessedBody || params.Message.ProcessedHTMLBody
             };
-            // Use email address directly in API path
-            const sendMessagePath = `${this.getApiUri()}/${encodeURIComponent(creds.accountEmail)}/messages/${params.MessageID}/reply`;
+            // `ContextData.Email` FIRST, as eleven sibling operations already read it. Without it this
+            // site could only resolve `creds.accountEmail` — which the `Azure Service Principal`
+            // credential type declares no property for, and which `disableEnvironmentFallback` removes
+            // the environment source for. Reply was therefore unreachable on exactly the stored
+            // credential the mailbox rework exists to support.
+            const mailbox = this.resolveMailbox('ReplyToMessage', creds, params.ContextData?.Email);
+            const sendMessagePath = `${this.getApiUri()}/${encodeURIComponent(mailbox)}/messages/${params.MessageID}/reply`;
             const result = await client.api(sendMessagePath).post(reply);
             return {
                 Success: true,
@@ -249,7 +293,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
             LogError(ex);
             return {
                 Success: false,
-                ErrorMessage: 'Error sending message'
+                ErrorMessage: `Error sending message: ${ex instanceof Error ? ex.message : String(ex)}`
             };
         }
     }
@@ -262,15 +306,29 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         const creds = this.resolveCredentials(credentials);
         const client = this.getGraphClient(creds);
         const contextData = params.ContextData;
-        const emailToUse = params.Identifier || contextData?.Email || creds.accountEmail;
-        let filter = "";
+        const emailToUse = this.resolveMailbox('GetMessages', creds, params.Identifier, contextData?.Email);
         const top = params.NumMessages;
+        const applied = { ReceivedAfter: false, ReceivedBefore: false, UnreadOnly: false };
+        const clauses = [];
         if (params.UnreadOnly) {
-            filter = "(isRead eq false)";
+            clauses.push("(isRead eq false)");
+            applied.UnreadOnly = true;
         }
+        if (params.ReceivedAfter) {
+            clauses.push(`(receivedDateTime ge ${ODataInstant(params.ReceivedAfter)})`);
+            applied.ReceivedAfter = true;
+        }
+        if (params.ReceivedBefore) {
+            clauses.push(`(receivedDateTime le ${ODataInstant(params.ReceivedBefore)})`);
+            applied.ReceivedBefore = true;
+        }
+        // COMPOSED, not assigned. This branch used to overwrite `filter` outright, so a caller that
+        // passed UnreadOnly together with a ContextData.Filter silently lost the UnreadOnly clause
+        // and got read mail back. Anything the caller supplies here now narrows alongside the rest.
         if (contextData && contextData.Filter) {
-            filter = contextData.Filter;
+            clauses.push(String(contextData.Filter));
         }
+        const filter = CombineFilterClauses(clauses, " and ");
         // Use email address directly in API path
         const messagesPath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages`;
         const response = await client.api(messagesPath)
@@ -285,7 +343,8 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         const messageResults = {
             Success: true,
             SourceData: sourceMessages,
-            Messages: []
+            Messages: [],
+            AppliedFilters: applied
         };
         let headers = null;
         // GetHeaders is an async function for one specific message.  I need
@@ -360,7 +419,8 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
                 }))
             };
             // Use email address directly in API path
-            const sendMessagePath = `${this.getApiUri()}/${encodeURIComponent(creds.accountEmail)}/messages/${params.MessageID}/forward`;
+            const mailbox = this.resolveMailbox('ForwardMessage', creds);
+            const sendMessagePath = `${this.getApiUri()}/${encodeURIComponent(mailbox)}/messages/${params.MessageID}/forward`;
             const forwardResult = await client.api(sendMessagePath).post(forward);
             return {
                 Success: true,
@@ -370,7 +430,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         catch (ex) {
             LogError(ex);
             return {
-                ErrorMessage: 'An Error occurred while forwarding the message',
+                ErrorMessage: `An Error occurred while forwarding the message: ${ex instanceof Error ? ex.message : String(ex)}`,
                 Success: false
             };
         }
@@ -523,12 +583,9 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
             // Smart selection: use message.From if provided and different from resolved accountEmail
-            let senderEmail = creds.accountEmail;
-            if (params.Message.From &&
-                params.Message.From.trim() !== '' &&
-                params.Message.From !== creds.accountEmail) {
-                senderEmail = params.Message.From;
-            }
+            // Whatever the caller named outranks the credential default; a request that names
+            // neither is refused here rather than sending from "undefined".
+            const senderEmail = this.resolveMailbox('CreateDraft', creds, params.Message.From);
             // Build message object (similar to SendSingleMessage but saved as draft)
             const draftMessage = {
                 subject: params.Message.ProcessedSubject,
@@ -568,13 +625,143 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
             LogError('Error creating draft via MS Graph', undefined, ex);
             return {
                 Success: false,
-                ErrorMessage: 'Error creating draft'
+                ErrorMessage: `Error creating draft: ${ex instanceof Error ? ex.message : String(ex)}`
             };
         }
     }
     // ========================================================================
     // EXTENDED OPERATIONS - MS Graph supports full mailbox access
     // ========================================================================
+    /**
+     * Reads calendar events for one mailbox.
+     *
+     * @requires MS Graph Scope: Calendars.Read (Application)
+     *
+     * TWO ENDPOINTS, AND THE CHOICE IS VISIBLE TO THE CALLER. Graph exposes calendar data two ways
+     * and they do not return the same thing:
+     *
+     *   - `/calendarView` REQUIRES a start and end and EXPANDS recurring series into one entry per
+     *     occurrence. A weekly stand-up in a two-week window comes back as two events, each with its
+     *     own start time and id.
+     *   - `/events` needs no window and does NOT expand. That same stand-up is one row, the series
+     *     master, whose start time is whenever the series began - possibly years ago.
+     *
+     * A caller logging what actually happened wants occurrences; one asking "what meetings exist"
+     * may want masters. Silently picking would be a trap, because the two are indistinguishable by
+     * inspection - so the window decides, and `RecurrenceExpanded` on the result REPORTS which
+     * happened rather than leaving the caller to infer it.
+     *
+     * CANCELLED EVENTS ARE EXCLUDED BY DEFAULT and cannot be recovered afterwards - Graph does not
+     * return them once filtered - so `IncludeCancelled` is honoured before the `$top` cap rather
+     * than by discarding rows after the fetch, which would silently shrink the page.
+     */
+    async GetEvents(params, credentials) {
+        const creds = this.resolveCredentials(credentials);
+        const client = this.getGraphClient(creds);
+        const contextData = params.ContextData;
+        const mailbox = params.Identifier || contextData?.Email || creds.accountEmail;
+        if (!mailbox) {
+            return {
+                Success: false,
+                Events: [],
+                ErrorMessage: 'GetEvents needs an Identifier (mailbox) or credentials scoped to one.'
+            };
+        }
+        const expand = !!params.StartDateTime && !!params.EndDateTime;
+        const base = `${this.getApiUri()}/${encodeURIComponent(mailbox)}`;
+        try {
+            let request = expand
+                ? client
+                    .api(`${base}/calendarView`)
+                    .query({
+                    startDateTime: params.StartDateTime.toISOString(),
+                    endDateTime: params.EndDateTime.toISOString()
+                })
+                    .orderby('start/dateTime')
+                : client.api(`${base}/events`).orderby('lastModifiedDateTime desc');
+            // Ask for UTC explicitly rather than relying on it. Graph returns start/end in UTC when no
+            // `Prefer: outlook.timezone` is sent, so this changes nothing today — but the default is
+            // Microsoft's to change, and every other value would need a tz database to resolve. Saying
+            // it makes the mapper's UTC assumption a request rather than a bet. `graphInstant` keeps
+            // its null fallback for the case where a non-UTC zone comes back anyway.
+            request = request.header('Prefer', 'outlook.timezone="UTC"');
+            // Applied server-side so the $top cap counts only events the caller asked for. Filtering
+            // after the fetch would return fewer than NumEvents and look like an empty calendar.
+            //
+            // $filter AND $orderby TOGETHER ARE ACCEPTED HERE. Outlook's backend requires every
+            // $orderby property to also appear in $filter for MESSAGES, returning 400
+            // `InefficientFilter` otherwise, and Microsoft's announcement of that rule is titled for
+            // Mail, Calendar and Contacts — so this combination looks like it should fail. It does
+            // not: both shapes below were sent against a live tenant and returned 200. Recorded here
+            // because the unit tests mock the Graph client and can never catch a 400, so the next
+            // reader has no way to re-derive it short of running the query again.
+            if (!params.IncludeCancelled) {
+                request = request.filter('isCancelled eq false');
+            }
+            const response = await request.top(params.NumEvents).get();
+            if (!response) {
+                return { Success: false, Events: [], ErrorMessage: 'Graph returned no response for the calendar read.' };
+            }
+            const sourceEvents = response.value ?? [];
+            return {
+                Success: true,
+                SourceData: sourceEvents,
+                RecurrenceExpanded: expand,
+                Events: sourceEvents.map((e) => this.toGetEventsEvent(e))
+            };
+        }
+        catch (err) {
+            // Surfaced, not swallowed into an empty list: a caller advancing a watermark must be able
+            // to tell "could not read" from "nothing scheduled".
+            return {
+                Success: false,
+                Events: [],
+                ErrorMessage: `Graph calendar read failed for ${mailbox}: ${err instanceof Error ? err.message : String(err)}`
+            };
+        }
+    }
+    /**
+     * Graph event -> the normalized shape. Lossy by design; `SourceData` keeps the original.
+     *
+     * A start Graph cannot express as an instant becomes NULL rather than a guess. Graph returns
+     * naive local strings plus a separate timeZone, so a value with neither a zone suffix nor a UTC
+     * marker genuinely has no instant here, and inventing one would file a meeting at the wrong time.
+     */
+    toGetEventsEvent(raw) {
+        const event = raw;
+        const organizer = event.organizer?.emailAddress?.address?.trim().toLowerCase() || undefined;
+        const attendees = (event.attendees ?? [])
+            .map((a) => a.emailAddress?.address?.trim().toLowerCase())
+            .filter((a) => !!a && a !== organizer);
+        return {
+            ExternalSystemRecordID: event.id ?? '',
+            SeriesID: event.seriesMasterId ?? null,
+            Subject: event.subject ?? '',
+            Body: event.bodyPreview ?? '',
+            StartTime: MSGraphProvider_1.graphInstant(event.start),
+            EndTime: MSGraphProvider_1.graphInstant(event.end),
+            Location: event.location?.displayName ?? null,
+            Organizer: organizer,
+            Attendees: [...new Set(attendees)],
+            IsCancelled: event.isCancelled === true
+        };
+    }
+    /** A Graph date slot as an instant, or null when it does not determine one. */
+    static graphInstant(slot) {
+        const raw = slot?.dateTime?.trim();
+        if (!raw)
+            return null;
+        // Both alternatives anchored. Unanchored, the `[Zz]` matched a "z" ANYWHERE in the string, so
+        // a value that merely contained one counted as carrying an offset and skipped the UTC check.
+        const hasOffset = /(?:[Zz]|[+-]\d{2}:?\d{2})$/.test(raw);
+        const zone = (slot?.timeZone ?? 'UTC').trim().toUpperCase();
+        // Only UTC is safe to assume. Any other named zone would need a tz database to resolve, and
+        // guessing puts the meeting hours away from when it happened.
+        if (!hasOffset && zone !== 'UTC')
+            return null;
+        const parsed = new Date(hasOffset ? raw : `${raw}Z`);
+        return Number.isNaN(parsed.getTime()) ? null : parsed;
+    }
     /**
      * Returns the list of operations supported by MS Graph provider.
      * MS Graph supports all mailbox operations.
@@ -598,7 +785,8 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
             'CreateSubscription',
             'RenewSubscription',
             'DeleteSubscription',
-            'ParseNotification'
+            'ParseNotification',
+            'GetEvents'
         ];
     }
     // ========================================================================
@@ -668,7 +856,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const mailboxId = params.Identifier || creds.accountEmail;
+            const mailboxId = this.resolveMailbox('CreateSubscription', creds, params.Identifier);
             const context = params.ContextData;
             const folderSegment = await this.resolveSubscriptionFolderSegment(client, mailboxId, context);
             if (!folderSegment) {
@@ -871,7 +1059,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const emailToUse = params.ContextData?.Email || creds.accountEmail;
+            const emailToUse = this.resolveMailbox('GetSingleMessage', creds, params.ContextData?.Email);
             // Use email address directly in API path
             const messagePath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${params.MessageID}`;
             const msgResponse = await client.api(messagePath).get();
@@ -921,7 +1109,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const emailToUse = params.ContextData?.Email || creds.accountEmail;
+            const emailToUse = this.resolveMailbox('DeleteMessage', creds, params.ContextData?.Email);
             // Use email address directly in API path
             const messagePath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${params.MessageID}`;
             if (params.PermanentDelete) {
@@ -961,7 +1149,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const emailToUse = params.ContextData?.Email || creds.accountEmail;
+            const emailToUse = this.resolveMailbox('MoveMessage', creds, params.ContextData?.Email);
             // Use email address directly in API path
             const movePath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${params.MessageID}/move`;
             const result = await client.api(movePath).post({
@@ -991,7 +1179,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const emailToUse = params.ContextData?.Email || creds.accountEmail;
+            const emailToUse = this.resolveMailbox('ListFolders', creds, params.ContextData?.Email);
             // Use email address directly in API path
             let foldersPath;
             if (params.ParentFolderID) {
@@ -1039,7 +1227,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const emailToUse = params.ContextData?.Email || creds.accountEmail;
+            const emailToUse = this.resolveMailbox('MarkAsRead', creds, params.ContextData?.Email);
             // Use email address directly in API path - update each message
             const updatePromises = params.MessageIDs.map(async (messageId) => {
                 const updatePath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${messageId}`;
@@ -1066,7 +1254,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const emailToUse = params.ContextData?.Email || creds.accountEmail;
+            const emailToUse = this.resolveMailbox('ArchiveMessage', creds, params.ContextData?.Email);
             // Find or create the Archive folder - use email address directly
             let archiveFolderId = await this.findSystemFolder(client, emailToUse, 'archive');
             if (!archiveFolderId) {
@@ -1104,7 +1292,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const emailToUse = params.ContextData?.Email || creds.accountEmail;
+            const emailToUse = this.resolveMailbox('SearchMessages', creds, params.ContextData?.Email);
             // Build search path - use email address directly in API path
             let messagesPath;
             if (params.FolderID) {
@@ -1176,7 +1364,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const emailToUse = params.ContextData?.Email || creds.accountEmail;
+            const emailToUse = this.resolveMailbox('ListAttachments', creds, params.ContextData?.Email);
             // Use email address directly in API path
             const attachmentsPath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${params.MessageID}/attachments`;
             const response = await client.api(attachmentsPath).get();
@@ -1217,7 +1405,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const emailToUse = params.ContextData?.Email || creds.accountEmail;
+            const emailToUse = this.resolveMailbox('DownloadAttachment', creds, params.ContextData?.Email);
             // Use email address directly in API path
             const attachmentPath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${params.MessageID}/attachments/${params.AttachmentID}`;
             const response = await client.api(attachmentPath).get();
@@ -1403,7 +1591,7 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         return effective.toISOString();
     }
 };
-MSGraphProvider = __decorate([
+MSGraphProvider = MSGraphProvider_1 = __decorate([
     RegisterClass(BaseCommunicationProvider, 'Microsoft Graph'),
     __metadata("design:paramtypes", [])
 ], MSGraphProvider);