@memberjunction/communication-ms-graph 5.48.0 → 5.50.0

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 } from "@memberjunction/communication-types";
+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 { Client } from '@microsoft/microsoft-graph-client';
 import { Message } from "@microsoft/microsoft-graph-types";
 /**
@@ -99,6 +99,11 @@ export declare class MSGraphProvider extends BaseCommunicationProvider {
      * Gets the API URI for Graph API calls.
      */
     private getApiUri;
+    /**
+     * Flattens a Graph recipient collection (toRecipients/ccRecipients/bccRecipients)
+     * into bare email addresses, dropping entries with no resolvable address.
+     */
+    private extractRecipientAddresses;
     /**
      * Sends a single email message via MS Graph.
      *
@@ -208,6 +213,77 @@ export declare class MSGraphProvider extends BaseCommunicationProvider {
      * MS Graph supports all mailbox operations.
      */
     getSupportedOperations(): ProviderOperation[];
+    /**
+     * Builds the base URL for Graph subscription resources. Subscriptions live at the
+     * Graph service root (`/v1.0/subscriptions`), NOT under the users-rooted
+     * {@link getApiUri}. Built from `AZURE_GRAPH_ENDPOINT` so sovereign-cloud overrides
+     * are honored.
+     */
+    private getSubscriptionsUri;
+    /**
+     * Resolves the Graph `resource` folder segment for a subscription. Returns the
+     * segment to embed in `mailFolders('<segment>')`, or `null` when a custom folder name
+     * could not be resolved to an ID.
+     *
+     * Hot path first: an explicit `folderId` is used verbatim, and a well-known folder
+     * name is passed through - both with zero extra Graph calls. Only a custom display
+     * name incurs a resolution lookup.
+     */
+    private resolveSubscriptionFolderSegment;
+    /**
+     * Creates a Microsoft Graph change-notification subscription for messages in a
+     * mailbox folder. Graph validates the notification endpoint synchronously during
+     * this call (it must echo the validation token), so an unreachable/incorrect endpoint
+     * surfaces here as a Graph error.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     * @param params - What to watch, where to notify, and the clientState secret
+     * @param credentials - Optional credentials override for this request
+     * @returns Promise<SubscriptionResult> - Subscription ID and expiration on success
+     */
+    CreateSubscription(params: CreateSubscriptionParams, credentials?: MSGraphCredentials): Promise<SubscriptionResult>;
+    /**
+     * Renews an existing Graph subscription before it expires. The caller MUST pass
+     * credentials for the same app registration that created the subscription - Graph
+     * subscriptions are visible only to their creator, so a credential mismatch surfaces
+     * as a 404.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     * @param params - The subscription ID and requested new expiration
+     * @param credentials - Optional credentials override for this request
+     * @returns Promise<SubscriptionResult> - The renewed expiration on success
+     */
+    RenewSubscription(params: RenewSubscriptionParams, credentials?: MSGraphCredentials): Promise<SubscriptionResult>;
+    /**
+     * Deletes an existing Graph subscription. Idempotent from the consumer's perspective:
+     * a 404 (already gone) is treated as success. The caller MUST pass credentials for
+     * the same app registration that created the subscription.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     * @param params - The subscription ID to delete
+     * @param credentials - Optional credentials override for this request
+     * @returns Promise<BaseMessageResult> - Result of the delete operation
+     */
+    DeleteSubscription(params: DeleteSubscriptionParams, credentials?: MSGraphCredentials): Promise<BaseMessageResult>;
+    /**
+     * Parses and validates an inbound Graph change notification. Pure: no Graph client,
+     * no network. Safe on hostile/garbage input - never throws; returns `Success: false`
+     * with a 400 suggested status on malformed payloads.
+     *
+     * Graph has no cryptographic signature scheme, so `SignatureValid` is left undefined;
+     * the consumer authenticates each notification by comparing its `ClientState` against
+     * the secret stored alongside the subscription.
+     *
+     * @param input - Transport-neutral capture of the inbound webhook request
+     * @returns Promise<ParseNotificationResult> - Handshake or normalized notifications
+     */
+    ParseNotification(input: WebhookNotificationInput, _credentials?: MSGraphCredentials): Promise<ParseNotificationResult>;
+    /**
+     * Returns MS Graph's subscription capabilities. Graph mail subscriptions last at most
+     * 4230 minutes (~3 days), support all three change types, and require synchronous
+     * endpoint validation at create time.
+     */
+    GetSubscriptionCapabilities(): SubscriptionCapabilities;
     /**
      * Gets a single message by ID from MS Graph.
      *
@@ -285,5 +361,42 @@ export declare class MSGraphProvider extends BaseCommunicationProvider {
      * Maps folder display name to system folder type.
      */
     private mapSystemFolderType;
+    /**
+     * Resolves a folder name to its Microsoft Graph well-known name when it is one,
+     * matching case-insensitively against both friendly aliases and the canonical Graph
+     * names. Graph accepts a well-known name directly in a resource path (no ID-resolution
+     * call needed). Returns undefined for a custom display name, which then requires a
+     * lookup. Shared by findSystemFolder and the CreateSubscription resource builder.
+     */
+    private resolveWellKnownFolder;
+    /**
+     * Extracts an HTTP status code from a thrown Microsoft Graph client error. The
+     * middleware client throws a GraphError-shaped object carrying a numeric statusCode;
+     * this narrows an untyped catch value to that code (or undefined when absent).
+     */
+    private getGraphStatusCode;
+    /**
+     * Parses the mailbox identifier (user ID / email) out of a Graph change-notification
+     * resource string. Tolerant of both Users/{id}/Messages/{msgId} and
+     * users/{id}/mailFolders('...')/messages/{msgId} shapes, case-insensitively. Returns
+     * undefined when no pattern matches - the identifier is a routing convenience only.
+     */
+    private parseIdentifierFromResource;
+    /**
+     * Maps a raw Graph changeType value onto the normalized SubscriptionChangeType union,
+     * returning undefined for anything unrecognized.
+     */
+    private mapChangeType;
+    /**
+     * Maps a raw Graph lifecycleEvent value onto the normalized lifecycle-event union,
+     * returning undefined for anything unrecognized.
+     */
+    private mapLifecycleEvent;
+    /**
+     * Clamps a requested subscription expiration to Graph's maximum lifetime, returning an
+     * ISO-8601 UTC string. When no expiration is requested (or it exceeds the max), the
+     * maximum-allowed expiration from now is used.
+     */
+    private clampExpiration;
 }
 //# sourceMappingURL=MSGraphProvider.d.ts.map

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

@@ -16,6 +16,11 @@ import { LogError, LogStatus } from "@memberjunction/core";
 import { compile } from 'html-to-text';
 import * as Auth from "./auth.js";
 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.
+ */
+const MSGRAPH_MAX_SUBSCRIPTION_MINUTES = 4230;
 /**
  * Implementation of the MS Graph provider for sending and receiving messages.
  *
@@ -106,6 +111,13 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
     getApiUri() {
         return Auth.ApiConfig.uri;
     }
+    /**
+     * Flattens a Graph recipient collection (toRecipients/ccRecipients/bccRecipients)
+     * into bare email addresses, dropping entries with no resolvable address.
+     */
+    extractRecipientAddresses(recipients) {
+        return recipients?.map((recipient) => recipient.emailAddress?.address || '').filter((address) => address.length > 0) || [];
+    }
     /**
      * Sends a single email message via MS Graph.
      *
@@ -166,6 +178,18 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
             }
             // Use email address directly in API path instead of looking up user ID
             const sendMessagePath = `${this.getApiUri()}/${encodeURIComponent(senderEmail)}/sendMail`;
+            // DRY RUN: full pipeline ran (credential resolution/validation, sender selection,
+            // complete Graph sendMail payload + headers + API path construction above) — stop at
+            // the transport boundary, never calling Microsoft Graph.
+            if (message.DryRun) {
+                LogStatus(`[DryRun] Microsoft Graph: sendMail payload constructed for ${message.To} — external send skipped`);
+                return {
+                    Message: message,
+                    Success: true,
+                    Error: '',
+                    DryRun: true
+                };
+            }
             await client.api(sendMessagePath).post(sendMail);
             return {
                 Message: message,
@@ -280,6 +304,8 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
             return {
                 From: msgTyped.from?.emailAddress?.address || '',
                 To: primaryToRecipient,
+                ToRecipients: this.extractRecipientAddresses(msgTyped.toRecipients),
+                CCRecipients: this.extractRecipientAddresses(msgTyped.ccRecipients),
                 ReplyTo: replyTo,
                 Subject: msgTyped.subject || '',
                 Body: contextData?.ReturnAsPlainText || contextData?.ReturnAsPlainTex ? this.HTMLConverter(msgTyped.body?.content || '') : msgTyped.body?.content || '',
@@ -568,9 +594,274 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
             'ArchiveMessage',
             'SearchMessages',
             'ListAttachments',
-            'DownloadAttachment'
+            'DownloadAttachment',
+            'CreateSubscription',
+            'RenewSubscription',
+            'DeleteSubscription',
+            'ParseNotification'
         ];
     }
+    // ========================================================================
+    // PUSH-NOTIFICATION SUBSCRIPTIONS
+    // Graph change-notification subscriptions. CRUD rides the existing authenticated
+    // client; ParseNotification is pure (no client, no network). The provider is
+    // stateless - the consumer persists subscription IDs/expirations/secrets.
+    // ========================================================================
+    /**
+     * Builds the base URL for Graph subscription resources. Subscriptions live at the
+     * Graph service root (`/v1.0/subscriptions`), NOT under the users-rooted
+     * {@link getApiUri}. Built from `AZURE_GRAPH_ENDPOINT` so sovereign-cloud overrides
+     * are honored.
+     */
+    getSubscriptionsUri() {
+        return `${Config.AZURE_GRAPH_ENDPOINT}/v1.0/subscriptions`;
+    }
+    /**
+     * Resolves the Graph `resource` folder segment for a subscription. Returns the
+     * segment to embed in `mailFolders('<segment>')`, or `null` when a custom folder name
+     * could not be resolved to an ID.
+     *
+     * Hot path first: an explicit `folderId` is used verbatim, and a well-known folder
+     * name is passed through - both with zero extra Graph calls. Only a custom display
+     * name incurs a resolution lookup.
+     */
+    async resolveSubscriptionFolderSegment(client, mailboxId, context) {
+        if (context?.folderId) {
+            return context.folderId;
+        }
+        const folderName = context?.folderName || 'inbox';
+        const wellKnown = this.resolveWellKnownFolder(folderName);
+        if (wellKnown) {
+            return wellKnown;
+        }
+        // Custom display name - resolve to an ID rather than subscribing to a guessed path.
+        return await this.findSystemFolder(client, mailboxId, folderName);
+    }
+    /**
+     * Creates a Microsoft Graph change-notification subscription for messages in a
+     * mailbox folder. Graph validates the notification endpoint synchronously during
+     * this call (it must echo the validation token), so an unreachable/incorrect endpoint
+     * surfaces here as a Graph error.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     * @param params - What to watch, where to notify, and the clientState secret
+     * @param credentials - Optional credentials override for this request
+     * @returns Promise<SubscriptionResult> - Subscription ID and expiration on success
+     */
+    async CreateSubscription(params, credentials) {
+        // Fail-fast input validation (before any Graph call).
+        if (!params.ClientState) {
+            return { Success: false, ErrorMessage: 'CreateSubscription requires a non-empty ClientState' };
+        }
+        if (params.ClientState.length > 128) {
+            return { Success: false, ErrorMessage: `ClientState exceeds Microsoft Graph's 128-character limit (got ${params.ClientState.length})` };
+        }
+        if (!params.NotificationUrl || !params.NotificationUrl.toLowerCase().startsWith('https://')) {
+            return { Success: false, ErrorMessage: 'NotificationUrl must be an https:// URL' };
+        }
+        if (params.LifecycleNotificationUrl && !params.LifecycleNotificationUrl.toLowerCase().startsWith('https://')) {
+            return { Success: false, ErrorMessage: 'LifecycleNotificationUrl must be an https:// URL' };
+        }
+        if (!params.ChangeTypes || params.ChangeTypes.length === 0) {
+            return { Success: false, ErrorMessage: 'CreateSubscription requires at least one ChangeType' };
+        }
+        try {
+            const creds = this.resolveCredentials(credentials);
+            const client = this.getGraphClient(creds);
+            const mailboxId = params.Identifier || creds.accountEmail;
+            const context = params.ContextData;
+            const folderSegment = await this.resolveSubscriptionFolderSegment(client, mailboxId, context);
+            if (!folderSegment) {
+                return {
+                    Success: false,
+                    ErrorMessage: `Could not resolve folder '${context?.folderName}' for mailbox '${mailboxId}'`
+                };
+            }
+            const body = {
+                changeType: params.ChangeTypes.join(','),
+                notificationUrl: params.NotificationUrl,
+                resource: `/users/${mailboxId}/mailFolders('${folderSegment}')/messages`,
+                clientState: params.ClientState,
+                expirationDateTime: this.clampExpiration(params.RequestedExpiration)
+            };
+            if (params.LifecycleNotificationUrl) {
+                body.lifecycleNotificationUrl = params.LifecycleNotificationUrl;
+            }
+            const resp = await client.api(this.getSubscriptionsUri()).post(body);
+            return {
+                Success: true,
+                SubscriptionID: resp?.id,
+                ExpiresAt: resp?.expirationDateTime ? new Date(resp.expirationDateTime) : undefined,
+                Result: resp
+            };
+        }
+        catch (ex) {
+            LogError('Error creating subscription via MS Graph', undefined, ex);
+            return {
+                Success: false,
+                ErrorMessage: `Error creating subscription: ${ex instanceof Error ? ex.message : String(ex)}`
+            };
+        }
+    }
+    /**
+     * Renews an existing Graph subscription before it expires. The caller MUST pass
+     * credentials for the same app registration that created the subscription - Graph
+     * subscriptions are visible only to their creator, so a credential mismatch surfaces
+     * as a 404.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     * @param params - The subscription ID and requested new expiration
+     * @param credentials - Optional credentials override for this request
+     * @returns Promise<SubscriptionResult> - The renewed expiration on success
+     */
+    async RenewSubscription(params, credentials) {
+        try {
+            const creds = this.resolveCredentials(credentials);
+            const client = this.getGraphClient(creds);
+            const resp = await client.api(`${this.getSubscriptionsUri()}/${params.SubscriptionID}`).patch({
+                expirationDateTime: this.clampExpiration(params.RequestedExpiration)
+            });
+            return {
+                Success: true,
+                SubscriptionID: resp?.id ?? params.SubscriptionID,
+                ExpiresAt: resp?.expirationDateTime ? new Date(resp.expirationDateTime) : undefined,
+                Result: resp
+            };
+        }
+        catch (ex) {
+            if (this.getGraphStatusCode(ex) === 404) {
+                LogError(`Subscription '${params.SubscriptionID}' not found during renewal - expired or created under different credentials`);
+                return {
+                    Success: false,
+                    ErrorMessage: 'subscription not found - expired or created under different credentials'
+                };
+            }
+            LogError('Error renewing subscription via MS Graph', undefined, ex);
+            return {
+                Success: false,
+                ErrorMessage: `Error renewing subscription: ${ex instanceof Error ? ex.message : String(ex)}`
+            };
+        }
+    }
+    /**
+     * Deletes an existing Graph subscription. Idempotent from the consumer's perspective:
+     * a 404 (already gone) is treated as success. The caller MUST pass credentials for
+     * the same app registration that created the subscription.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     * @param params - The subscription ID to delete
+     * @param credentials - Optional credentials override for this request
+     * @returns Promise<BaseMessageResult> - Result of the delete operation
+     */
+    async DeleteSubscription(params, credentials) {
+        try {
+            const creds = this.resolveCredentials(credentials);
+            const client = this.getGraphClient(creds);
+            await client.api(`${this.getSubscriptionsUri()}/${params.SubscriptionID}`).delete();
+            return { Success: true };
+        }
+        catch (ex) {
+            if (this.getGraphStatusCode(ex) === 404) {
+                // Already gone - deletion is idempotent from the consumer's perspective.
+                return { Success: true };
+            }
+            LogError('Error deleting subscription via MS Graph', undefined, ex);
+            return {
+                Success: false,
+                ErrorMessage: `Error deleting subscription: ${ex instanceof Error ? ex.message : String(ex)}`
+            };
+        }
+    }
+    /**
+     * Parses and validates an inbound Graph change notification. Pure: no Graph client,
+     * no network. Safe on hostile/garbage input - never throws; returns `Success: false`
+     * with a 400 suggested status on malformed payloads.
+     *
+     * Graph has no cryptographic signature scheme, so `SignatureValid` is left undefined;
+     * the consumer authenticates each notification by comparing its `ClientState` against
+     * the secret stored alongside the subscription.
+     *
+     * @param input - Transport-neutral capture of the inbound webhook request
+     * @returns Promise<ParseNotificationResult> - Handshake or normalized notifications
+     */
+    async ParseNotification(input, _credentials) {
+        // 1. Endpoint-validation handshake. QueryParams are already framework-decoded per
+        //    the WebhookNotificationInput contract - echo the token verbatim.
+        const validationToken = input?.QueryParams?.['validationToken'];
+        if (validationToken !== undefined) {
+            return {
+                Success: true,
+                Handshake: {
+                    ResponseStatus: 200,
+                    ResponseBody: validationToken,
+                    ResponseContentType: 'text/plain'
+                },
+                Notifications: [],
+                SuggestedResponseStatus: 200
+            };
+        }
+        // 2. Parse the notification batch. Never throw on bad input.
+        let payload;
+        try {
+            payload = JSON.parse(input?.RawBody ?? '');
+        }
+        catch {
+            return {
+                Success: false,
+                ErrorMessage: 'Malformed notification body (invalid JSON)',
+                Notifications: [],
+                SuggestedResponseStatus: 400
+            };
+        }
+        const items = payload?.value;
+        if (!Array.isArray(items)) {
+            return {
+                Success: false,
+                ErrorMessage: 'Notification body missing value[] array',
+                Notifications: [],
+                SuggestedResponseStatus: 400
+            };
+        }
+        const notifications = items.map((raw) => {
+            const item = (raw ?? {});
+            const lifecycleEvent = item['lifecycleEvent'];
+            const resourceData = item['resourceData'];
+            const messageId = typeof resourceData?.id === 'string' ? resourceData.id : undefined;
+            return {
+                Kind: lifecycleEvent != null ? 'lifecycle' : 'message',
+                SubscriptionID: typeof item['subscriptionId'] === 'string' ? item['subscriptionId'] : undefined,
+                ClientState: typeof item['clientState'] === 'string' ? item['clientState'] : undefined,
+                Identifier: this.parseIdentifierFromResource(item['resource']),
+                ChangeType: this.mapChangeType(item['changeType']),
+                MessageIDs: messageId ? [messageId] : [],
+                LifecycleEvent: this.mapLifecycleEvent(lifecycleEvent),
+                RawData: raw
+            };
+        });
+        return {
+            Success: true,
+            SignatureValid: undefined,
+            Notifications: notifications,
+            SuggestedResponseStatus: 202
+        };
+    }
+    /**
+     * Returns MS Graph's subscription capabilities. Graph mail subscriptions last at most
+     * 4230 minutes (~3 days), support all three change types, and require synchronous
+     * endpoint validation at create time.
+     */
+    GetSubscriptionCapabilities() {
+        return {
+            MaxLifetimeMinutes: MSGRAPH_MAX_SUBSCRIPTION_MINUTES,
+            SupportedChangeTypes: ['created', 'updated', 'deleted'],
+            RequiresEndpointValidation: true,
+            // Graph is subscription-managed (CreateSubscription/RenewSubscription/DeleteSubscription)
+            // and HINT-mode: notifications carry resourceData IDs, the consumer re-fetches via
+            // GetMessages/GetSingleMessage — the payload is never delivered inline.
+            SupportsSubscriptionManagement: true,
+            DeliversPayloadInline: false
+        };
+    }
     /**
      * Gets a single message by ID from MS Graph.
      *
@@ -597,6 +888,8 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
                 Message: {
                     From: msgTyped.from?.emailAddress?.address || '',
                     To: replyTo.length > 0 ? replyTo[0] : '',
+                    ToRecipients: this.extractRecipientAddresses(msgTyped.toRecipients),
+                    CCRecipients: this.extractRecipientAddresses(msgTyped.ccRecipients),
                     ReplyTo: replyTo,
                     Subject: msgTyped.subject || '',
                     Body: msgTyped.body?.content || '',
@@ -850,6 +1143,8 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
             const messages = response.value.map((msg) => ({
                 From: msg.from?.emailAddress?.address || '',
                 To: msg.toRecipients?.[0]?.emailAddress?.address || '',
+                ToRecipients: this.extractRecipientAddresses(msg.toRecipients),
+                CCRecipients: this.extractRecipientAddresses(msg.ccRecipients),
                 Subject: msg.subject || '',
                 Body: msg.bodyPreview || '',
                 ExternalSystemRecordID: msg.id || '',
@@ -962,19 +1257,8 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
      */
     async findSystemFolder(client, emailAddress, folderName) {
         try {
-            // MS Graph well-known folder names
-            const wellKnownNames = {
-                'inbox': 'inbox',
-                'sent': 'sentitems',
-                'drafts': 'drafts',
-                'deleteditems': 'deleteditems',
-                'trash': 'deleteditems',
-                'junkemail': 'junkemail',
-                'spam': 'junkemail',
-                'archive': 'archive'
-            };
-            const normalizedName = folderName.toLowerCase();
-            const graphFolderName = wellKnownNames[normalizedName] || normalizedName;
+            // MS Graph well-known folder names (shared with the subscription resolver)
+            const graphFolderName = this.resolveWellKnownFolder(folderName) || folderName.toLowerCase();
             // Try well-known folder endpoint first - use email address directly
             const folderPath = `${this.getApiUri()}/${encodeURIComponent(emailAddress)}/mailFolders/${graphFolderName}`;
             const folder = await client.api(folderPath).get();
@@ -1042,6 +1326,82 @@ let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
         };
         return mapping[displayName.toLowerCase()] || 'other';
     }
+    /**
+     * Resolves a folder name to its Microsoft Graph well-known name when it is one,
+     * matching case-insensitively against both friendly aliases and the canonical Graph
+     * names. Graph accepts a well-known name directly in a resource path (no ID-resolution
+     * call needed). Returns undefined for a custom display name, which then requires a
+     * lookup. Shared by findSystemFolder and the CreateSubscription resource builder.
+     */
+    resolveWellKnownFolder(folderName) {
+        const wellKnownNames = {
+            'inbox': 'inbox',
+            'sent': 'sentitems',
+            'sentitems': 'sentitems',
+            'drafts': 'drafts',
+            'deleteditems': 'deleteditems',
+            'trash': 'deleteditems',
+            'junkemail': 'junkemail',
+            'spam': 'junkemail',
+            'archive': 'archive'
+        };
+        return wellKnownNames[folderName.toLowerCase()];
+    }
+    /**
+     * Extracts an HTTP status code from a thrown Microsoft Graph client error. The
+     * middleware client throws a GraphError-shaped object carrying a numeric statusCode;
+     * this narrows an untyped catch value to that code (or undefined when absent).
+     */
+    getGraphStatusCode(ex) {
+        if (ex && typeof ex === 'object' && 'statusCode' in ex) {
+            const sc = ex.statusCode;
+            return typeof sc === 'number' ? sc : undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Parses the mailbox identifier (user ID / email) out of a Graph change-notification
+     * resource string. Tolerant of both Users/{id}/Messages/{msgId} and
+     * users/{id}/mailFolders('...')/messages/{msgId} shapes, case-insensitively. Returns
+     * undefined when no pattern matches - the identifier is a routing convenience only.
+     */
+    parseIdentifierFromResource(resource) {
+        if (typeof resource !== 'string') {
+            return undefined;
+        }
+        const match = resource.match(/users\/([^/]+)/i);
+        return match ? match[1] : undefined;
+    }
+    /**
+     * Maps a raw Graph changeType value onto the normalized SubscriptionChangeType union,
+     * returning undefined for anything unrecognized.
+     */
+    mapChangeType(raw) {
+        if (raw === 'created' || raw === 'updated' || raw === 'deleted') {
+            return raw;
+        }
+        return undefined;
+    }
+    /**
+     * Maps a raw Graph lifecycleEvent value onto the normalized lifecycle-event union,
+     * returning undefined for anything unrecognized.
+     */
+    mapLifecycleEvent(raw) {
+        if (raw === 'subscriptionRemoved' || raw === 'missed' || raw === 'reauthorizationRequired') {
+            return raw;
+        }
+        return undefined;
+    }
+    /**
+     * Clamps a requested subscription expiration to Graph's maximum lifetime, returning an
+     * ISO-8601 UTC string. When no expiration is requested (or it exceeds the max), the
+     * maximum-allowed expiration from now is used.
+     */
+    clampExpiration(requested) {
+        const max = new Date(Date.now() + MSGRAPH_MAX_SUBSCRIPTION_MINUTES * 60 * 1000);
+        const effective = requested && requested.getTime() < max.getTime() ? requested : max;
+        return effective.toISOString();
+    }
 };
 MSGraphProvider = __decorate([
     RegisterClass(BaseCommunicationProvider, 'Microsoft Graph'),