@memberjunction/communication-ms-graph 3.4.0 → 4.1.0

package/dist/MSGraphProvider.js

@@ -1,63 +1,65 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LoadMSGraphProvider = exports.MSGraphProvider = void 0;
-const communication_types_1 = require("@memberjunction/communication-types");
-const microsoft_graph_client_1 = require("@microsoft/microsoft-graph-client");
-const identity_1 = require("@azure/identity");
-const azureTokenCredentials_1 = require("@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials");
-const global_1 = require("@memberjunction/global");
-const core_1 = require("@memberjunction/core");
-const html_to_text_1 = require("html-to-text");
-const Auth = __importStar(require("./auth"));
-const Config = __importStar(require("./config"));
-let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCommunicationProvider {
+import { BaseCommunicationProvider, 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";
+import { RegisterClass } from "@memberjunction/global";
+import { LogError, LogStatus } from "@memberjunction/core";
+import { compile } from 'html-to-text';
+import * as Auth from "./auth.js";
+import * as Config from "./config.js";
+/**
+ * Implementation of the MS Graph provider for sending and receiving messages.
+ *
+ * @remarks
+ * Microsoft Graph provides full mailbox access. This provider supports:
+ * - Sending messages
+ * - Fetching messages from inbox
+ * - Forwarding messages
+ * - Replying to messages
+ * - Creating drafts
+ *
+ * @example
+ * ```typescript
+ * // Using environment credentials (default)
+ * await engine.SendSingleMessage('Microsoft Graph', 'Standard Email', message);
+ *
+ * // Using per-request credentials
+ * await engine.SendSingleMessage('Microsoft Graph', 'Standard Email', message, undefined, false, {
+ *     tenantId: 'customer-tenant-id',
+ *     clientId: 'customer-client-id',
+ *     clientSecret: 'customer-client-secret',
+ *     accountEmail: 'customer@domain.com'
+ * });
+ * ```
+ */
+let MSGraphProvider = class MSGraphProvider extends BaseCommunicationProvider {
     constructor() {
         super();
-        this.ServiceAccount = null;
+        // Cache clients by credential hash for performance with per-request credentials
         this.clientCache = new Map();
-        this.HTMLConverter = (0, html_to_text_1.compile)({
+        this.HTMLConverter = compile({
             wordwrap: 130
         });
     }
+    /**
+     * Resolves MS Graph credentials from request and environment.
+     */
     resolveCredentials(credentials) {
         const disableFallback = credentials?.disableEnvironmentFallback ?? false;
-        const tenantId = (0, communication_types_1.resolveCredentialValue)(credentials?.tenantId, Config.AZURE_TENANT_ID, disableFallback);
-        const clientId = (0, communication_types_1.resolveCredentialValue)(credentials?.clientId, Config.AZURE_CLIENT_ID, disableFallback);
-        const clientSecret = (0, communication_types_1.resolveCredentialValue)(credentials?.clientSecret, Config.AZURE_CLIENT_SECRET, disableFallback);
-        const accountEmail = (0, communication_types_1.resolveCredentialValue)(credentials?.accountEmail, Config.AZURE_ACCOUNT_EMAIL, disableFallback);
-        (0, communication_types_1.validateRequiredCredentials)({ tenantId, clientId, clientSecret, accountEmail }, ['tenantId', 'clientId', 'clientSecret', 'accountEmail'], 'Microsoft Graph');
+        const tenantId = resolveCredentialValue(credentials?.tenantId, Config.AZURE_TENANT_ID, disableFallback);
+        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');
         return {
             tenantId: tenantId,
             clientId: clientId,
@@ -65,46 +67,55 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             accountEmail: accountEmail
         };
     }
+    /**
+     * Gets or creates a Graph client for the given credentials.
+     * Uses cached client if credentials match environment (default case).
+     */
     getGraphClient(creds) {
+        // Check if using environment credentials (can use shared client)
         const isEnvCredentials = creds.tenantId === Config.AZURE_TENANT_ID &&
             creds.clientId === Config.AZURE_CLIENT_ID &&
             creds.clientSecret === Config.AZURE_CLIENT_SECRET;
         if (isEnvCredentials) {
+            // Use the shared Auth.GraphClient for environment credentials
             return Auth.GraphClient;
         }
+        // For per-request credentials, use cached client by credential key
         const cacheKey = `${creds.tenantId}:${creds.clientId}`;
         let client = this.clientCache.get(cacheKey);
         if (!client) {
-            const credential = new identity_1.ClientSecretCredential(creds.tenantId, creds.clientId, creds.clientSecret);
-            const authProvider = new azureTokenCredentials_1.TokenCredentialAuthenticationProvider(credential, {
+            const credential = new ClientSecretCredential(creds.tenantId, creds.clientId, creds.clientSecret);
+            const authProvider = new TokenCredentialAuthenticationProvider(credential, {
                 scopes: ['https://graph.microsoft.com/.default'],
             });
-            client = microsoft_graph_client_1.Client.initWithMiddleware({ authProvider });
+            client = Client.initWithMiddleware({ authProvider });
             this.clientCache.set(cacheKey, client);
         }
         return client;
     }
+    /**
+     * Gets the API URI for Graph API calls.
+     */
     getApiUri() {
         return Auth.ApiConfig.uri;
     }
+    /**
+     * Sends a single email message via MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Send (Application)
+     */
     async SendSingleMessage(message, credentials) {
         try {
+            // Resolve credentials
             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;
             }
-            const user = await this.GetServiceAccountWithClient(client, senderEmail);
-            if (!user) {
-                return {
-                    Message: message,
-                    Success: false,
-                    Error: 'Service account not found'
-                };
-            }
             if (!message) {
                 return {
                     Message: message,
@@ -140,12 +151,14 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
                 saveToSentItems: message.ContextData?.saveToSentItems ?? false
             };
             if (message.Headers) {
+                // Convert Headers (Record<string, string>) to internetMessageHeaders (Array[{key:value}])
                 sendMail.message.internetMessageHeaders = Object.entries(message.Headers).map(([key, value]) => ({
                     name: key.startsWith('X-') ? key : `X-${key}`,
                     value: value
                 }));
             }
-            const sendMessagePath = `${this.getApiUri()}/${user.id}/sendMail`;
+            // Use email address directly in API path instead of looking up user ID
+            const sendMessagePath = `${this.getApiUri()}/${encodeURIComponent(senderEmail)}/sendMail`;
             await client.api(sendMessagePath).post(sendMail);
             return {
                 Message: message,
@@ -154,7 +167,7 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
         }
         catch (ex) {
-            (0, core_1.LogError)(ex);
+            LogError(ex);
             return {
                 Message: message,
                 Success: false,
@@ -162,17 +175,15 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
         }
     }
+    /**
+     * Replies to an email message via MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Send (Application)
+     */
     async ReplyToMessage(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const user = await this.GetServiceAccountWithClient(client, creds.accountEmail);
-            if (!user) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
             const reply = {
                 message: {
                     toRecipients: [
@@ -195,7 +206,8 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
                 },
                 comment: params.Message.ProcessedBody || params.Message.ProcessedHTMLBody
             };
-            const sendMessagePath = `${this.getApiUri()}/${user.id}/messages/${params.MessageID}/reply`;
+            // Use email address directly in API path
+            const sendMessagePath = `${this.getApiUri()}/${encodeURIComponent(creds.accountEmail)}/messages/${params.MessageID}/reply`;
             const result = await client.api(sendMessagePath).post(reply);
             return {
                 Success: true,
@@ -203,25 +215,23 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
         }
         catch (ex) {
-            (0, core_1.LogError)(ex);
+            LogError(ex);
             return {
                 Success: false,
                 ErrorMessage: 'Error sending message'
             };
         }
     }
+    /**
+     * Retrieves email messages from a mailbox via MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application), or Mail.ReadWrite if using ContextData.MarkAsRead option
+     */
     async GetMessages(params, credentials) {
         const creds = this.resolveCredentials(credentials);
         const client = this.getGraphClient(creds);
         const contextData = params.ContextData;
         const emailToUse = params.Identifier || contextData?.Email || creds.accountEmail;
-        const user = await this.GetServiceAccountWithClient(client, emailToUse);
-        if (!user || !user.id) {
-            return {
-                Success: false,
-                Messages: []
-            };
-        }
         let filter = "";
         const top = params.NumMessages;
         if (params.UnreadOnly) {
@@ -230,7 +240,8 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
         if (contextData && contextData.Filter) {
             filter = contextData.Filter;
         }
-        const messagesPath = `${this.getApiUri()}/${user.id}/messages`;
+        // Use email address directly in API path
+        const messagesPath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages`;
         const response = await client.api(messagesPath)
             .filter(filter).top(top).get();
         if (!response) {
@@ -246,14 +257,19 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             Messages: []
         };
         let headers = null;
+        // GetHeaders is an async function for one specific message.  I need
+        // to resolve all of them into a structure, indexed by sourceMessage.id
+        // and then apply that in the mapped message below.
         if (params.IncludeHeaders) {
-            const headersPromises = sourceMessages.map((message) => this.GetHeadersWithClient(client, params, user, message.id));
+            const headersPromises = sourceMessages.map((message) => this.GetHeadersWithEmail(client, emailToUse, params, message.id));
             headers = await Promise.all(headersPromises);
         }
         const messages = sourceMessages.map((message, index) => {
             const msgTyped = message;
             const replyTo = msgTyped.replyTo?.map((replyTo) => replyTo.emailAddress?.address || '') || [];
             const primaryToRecipient = replyTo.length > 0 ? replyTo[0] : '';
+            // the blow hokey thing with ReturnAsPlainTex without the t is to have
+            // back-compat with the old code when this typo existed
             return {
                 From: msgTyped.from?.emailAddress?.address || '',
                 To: primaryToRecipient,
@@ -272,11 +288,16 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
         messageResults.Messages = messages;
         if (contextData && contextData.MarkAsRead) {
             for (const message of messages) {
-                this.MarkMessageAsReadWithClient(client, user.id, message.ExternalSystemRecordID);
+                this.MarkMessageAsReadWithEmail(client, emailToUse, message.ExternalSystemRecordID);
             }
         }
         return messageResults;
     }
+    /**
+     * Forwards an email message via MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Send (Application)
+     */
     async ForwardMessage(params, credentials) {
         try {
             if (!params.MessageID) {
@@ -287,13 +308,6 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             }
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
-            const user = await this.GetServiceAccountWithClient(client, creds.accountEmail);
-            if (!user) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
             const forward = {
                 comment: params.Message,
                 toRecipients: params.ToRecipients.map((recipient) => ({
@@ -312,7 +326,8 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
                     }
                 }))
             };
-            const sendMessagePath = `${this.getApiUri()}/${user.id}/messages/${params.MessageID}/forward`;
+            // Use email address directly in API path
+            const sendMessagePath = `${this.getApiUri()}/${encodeURIComponent(creds.accountEmail)}/messages/${params.MessageID}/forward`;
             const forwardResult = await client.api(sendMessagePath).post(forward);
             return {
                 Success: true,
@@ -320,16 +335,23 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
         }
         catch (ex) {
-            (0, core_1.LogError)(ex);
+            LogError(ex);
             return {
                 ErrorMessage: 'An Error occurred while forwarding the message',
                 Success: false
             };
         }
     }
-    async GetHeadersWithClient(client, params, user, messageID) {
+    /**
+     * Gets headers for a specific message using email address directly.
+     * This is the preferred method for new code as it avoids an extra API call to look up the user.
+     *
+     * @protected
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
+    async GetHeadersWithEmail(client, emailAddress, params, messageID) {
         if (params.IncludeHeaders && messageID) {
-            const messageHeaderPath = `${this.getApiUri()}/${user.id}/messages/${messageID}?$select=internetMessageHeaders`;
+            const messageHeaderPath = `${this.getApiUri()}/${encodeURIComponent(emailAddress)}/messages/${messageID}?$select=internetMessageHeaders`;
             const messageHeaderResponse = await client.api(messageHeaderPath).get();
             return messageHeaderResponse.internetMessageHeaders?.map((header) => ({
                 [header.name]: header.value
@@ -337,69 +359,144 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
         }
         return {};
     }
-    async GetHeaders(params, user, messageID) {
-        return this.GetHeadersWithClient(Auth.GraphClient, params, user, messageID);
+    /**
+     * Marks a message as read using email address directly.
+     * This is the preferred method for new code as it avoids an extra API call to look up the user.
+     *
+     * @protected
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
+    async MarkMessageAsReadWithEmail(client, emailAddress, messageID) {
+        try {
+            const updatePath = `${this.getApiUri()}/${encodeURIComponent(emailAddress)}/messages/${messageID}`;
+            const updatedMessage = {
+                isRead: true
+            };
+            await client.api(updatePath).update(updatedMessage);
+            LogStatus(`Message ${messageID} marked as read`);
+            return true;
+        }
+        catch (ex) {
+            LogError(ex);
+            return false;
+        }
     }
+    /**
+     * Gets the user account information by making an API call to MS Graph.
+     * This method looks up the full User object from the Graph API.
+     *
+     * @protected
+     * @requires MS Graph Scope: User.Read.All (Application) - Required to look up user information
+     */
     async GetServiceAccountWithClient(client, email) {
-        const endpoint = `${this.getApiUri()}/${email}`;
-        const user = await client.api(endpoint).get();
-        if (!user) {
-            (0, core_1.LogError)('Error: could not get user info');
-            return null;
+        try {
+            const endpoint = `${this.getApiUri()}/${encodeURIComponent(email)}`;
+            const user = await client.api(endpoint).get();
+            if (!user) {
+                LogError('Error: could not get user info');
+                return null;
+            }
+            const userID = user.id;
+            if (!userID) {
+                LogError('Error: userID not set for user');
+                return null;
+            }
+            return user;
         }
-        const userID = user.id;
-        if (!userID) {
-            (0, core_1.LogError)('Error: userID not set for user');
+        catch (ex) {
+            LogError('Error getting service account', undefined, ex);
             return null;
         }
-        return user;
     }
+    /**
+     * Gets the service account using default client.
+     * Caches the result for subsequent calls.
+     *
+     * @protected
+     * @requires MS Graph Scope: User.Read.All (Application) - Required to look up user information
+     */
     async GetServiceAccount(email) {
-        if (this.ServiceAccount) {
-            return this.ServiceAccount;
-        }
         const accountEmail = email || Config.AZURE_ACCOUNT_EMAIL;
-        const user = await this.GetServiceAccountWithClient(Auth.GraphClient, accountEmail);
-        if (user) {
-            this.ServiceAccount = user;
+        return this.GetServiceAccountWithClient(Auth.GraphClient, accountEmail);
+    }
+    /**
+     * Gets headers for a message using User object (requires prior user lookup).
+     * For better performance, consider using GetHeadersWithEmail() instead.
+     *
+     * @protected
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
+    async GetHeadersWithClient(client, params, user, messageID) {
+        const userId = user.id || user.userPrincipalName;
+        if (!userId) {
+            return {};
+        }
+        if (params.IncludeHeaders && messageID) {
+            const messageHeaderPath = `${this.getApiUri()}/${encodeURIComponent(userId)}/messages/${messageID}?$select=internetMessageHeaders`;
+            const messageHeaderResponse = await client.api(messageHeaderPath).get();
+            return messageHeaderResponse.internetMessageHeaders?.map((header) => ({
+                [header.name]: header.value
+            })) || {};
         }
-        return user;
+        return {};
+    }
+    /**
+     * Gets headers using default client.
+     *
+     * @protected
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
+    async GetHeaders(params, user, messageID) {
+        return this.GetHeadersWithClient(Auth.GraphClient, params, user, messageID);
     }
+    /**
+     * Marks a message as read using User ID.
+     * For better performance, consider using MarkMessageAsReadWithEmail() instead.
+     *
+     * @protected
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
     async MarkMessageAsReadWithClient(client, userID, messageID) {
         try {
-            const updatePath = `${this.getApiUri()}/${userID}/messages/${messageID}`;
+            const updatePath = `${this.getApiUri()}/${encodeURIComponent(userID)}/messages/${messageID}`;
             const updatedMessage = {
                 isRead: true
             };
             await client.api(updatePath).update(updatedMessage);
-            (0, core_1.LogStatus)(`Message ${messageID} marked as read`);
+            LogStatus(`Message ${messageID} marked as read`);
             return true;
         }
         catch (ex) {
-            (0, core_1.LogError)(ex);
+            LogError(ex);
             return false;
         }
     }
+    /**
+     * Marks a message as read using default client.
+     *
+     * @protected
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
     async MarkMessageAsRead(userID, messageID) {
         return this.MarkMessageAsReadWithClient(Auth.GraphClient, userID, messageID);
     }
+    /**
+     * Creates a draft email message via MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
     async CreateDraft(params, credentials) {
         try {
             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;
             }
-            const user = await this.GetServiceAccountWithClient(client, senderEmail);
-            if (!user) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
+            // Build message object (similar to SendSingleMessage but saved as draft)
             const draftMessage = {
                 subject: params.Message.ProcessedSubject,
                 body: {
@@ -417,15 +514,17 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
                 }))
             };
             if (params.Message.Headers) {
+                // Convert Headers (Record<string, string>) to internetMessageHeaders (Array[{key:value}])
                 draftMessage.internetMessageHeaders = Object.entries(params.Message.Headers)
                     .map(([key, value]) => ({
                     name: key.startsWith('X-') ? key : `X-${key}`,
                     value: value
                 }));
             }
-            const createDraftPath = `${this.getApiUri()}/${user.id}/messages`;
+            // Create draft by POSTing to messages endpoint (not sendMail) - use email address directly
+            const createDraftPath = `${this.getApiUri()}/${encodeURIComponent(senderEmail)}/messages`;
             const result = await client.api(createDraftPath).post(draftMessage);
-            (0, core_1.LogStatus)(`Draft created via MS Graph: ${result.id}`);
+            LogStatus(`Draft created via MS Graph: ${result.id}`);
             return {
                 Success: true,
                 DraftID: result.id,
@@ -433,13 +532,20 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
         }
         catch (ex) {
-            (0, core_1.LogError)('Error creating draft via MS Graph', undefined, ex);
+            LogError('Error creating draft via MS Graph', undefined, ex);
             return {
                 Success: false,
                 ErrorMessage: 'Error creating draft'
             };
         }
     }
+    // ========================================================================
+    // EXTENDED OPERATIONS - MS Graph supports full mailbox access
+    // ========================================================================
+    /**
+     * Returns the list of operations supported by MS Graph provider.
+     * MS Graph supports all mailbox operations.
+     */
     getSupportedOperations() {
         return [
             'SendSingleMessage',
@@ -458,19 +564,18 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             'DownloadAttachment'
         ];
     }
+    /**
+     * Gets a single message by ID from MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
     async GetSingleMessage(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
             const emailToUse = params.ContextData?.Email || creds.accountEmail;
-            const user = await this.GetServiceAccountWithClient(client, emailToUse);
-            if (!user || !user.id) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
-            const messagePath = `${this.getApiUri()}/${user.id}/messages/${params.MessageID}`;
+            // Use email address directly in API path
+            const messagePath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${params.MessageID}`;
             const msgResponse = await client.api(messagePath).get();
             if (!msgResponse) {
                 return {
@@ -499,68 +604,70 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
         }
         catch (ex) {
-            (0, core_1.LogError)('Error getting single message via MS Graph', undefined, ex);
+            LogError('Error getting single message via MS Graph', undefined, ex);
             return {
                 Success: false,
                 ErrorMessage: `Error getting message: ${ex instanceof Error ? ex.message : String(ex)}`
             };
         }
     }
+    /**
+     * Deletes a message using MS Graph.
+     * If PermanentDelete is false, moves to Deleted Items folder.
+     *
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
     async DeleteMessage(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
             const emailToUse = params.ContextData?.Email || creds.accountEmail;
-            const user = await this.GetServiceAccountWithClient(client, emailToUse);
-            if (!user || !user.id) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
-            const messagePath = `${this.getApiUri()}/${user.id}/messages/${params.MessageID}`;
+            // Use email address directly in API path
+            const messagePath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${params.MessageID}`;
             if (params.PermanentDelete) {
+                // Permanently delete the message
                 await client.api(messagePath).delete();
             }
             else {
-                const deletedItemsFolder = await this.findSystemFolder(client, user.id, 'deleteditems');
+                // Move to Deleted Items (soft delete)
+                const deletedItemsFolder = await this.findSystemFolder(client, emailToUse, 'deleteditems');
                 if (deletedItemsFolder) {
                     await client.api(`${messagePath}/move`).post({
                         destinationId: deletedItemsFolder
                     });
                 }
                 else {
+                    // Fall back to permanent delete if we can't find Deleted Items
                     await client.api(messagePath).delete();
                 }
             }
-            (0, core_1.LogStatus)(`Message ${params.MessageID} deleted via MS Graph`);
+            LogStatus(`Message ${params.MessageID} deleted via MS Graph`);
             return { Success: true };
         }
         catch (ex) {
-            (0, core_1.LogError)('Error deleting message via MS Graph', undefined, ex);
+            LogError('Error deleting message via MS Graph', undefined, ex);
             return {
                 Success: false,
                 ErrorMessage: `Error deleting message: ${ex instanceof Error ? ex.message : String(ex)}`
             };
         }
     }
+    /**
+     * Moves a message to a different folder using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
     async MoveMessage(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
             const emailToUse = params.ContextData?.Email || creds.accountEmail;
-            const user = await this.GetServiceAccountWithClient(client, emailToUse);
-            if (!user || !user.id) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
-            const movePath = `${this.getApiUri()}/${user.id}/messages/${params.MessageID}/move`;
+            // Use email address directly in API path
+            const movePath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${params.MessageID}/move`;
             const result = await client.api(movePath).post({
                 destinationId: params.DestinationFolderID
             });
-            (0, core_1.LogStatus)(`Message ${params.MessageID} moved to folder ${params.DestinationFolderID}`);
+            LogStatus(`Message ${params.MessageID} moved to folder ${params.DestinationFolderID}`);
             return {
                 Success: true,
                 NewMessageID: result?.id,
@@ -568,31 +675,30 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
         }
         catch (ex) {
-            (0, core_1.LogError)('Error moving message via MS Graph', undefined, ex);
+            LogError('Error moving message via MS Graph', undefined, ex);
             return {
                 Success: false,
                 ErrorMessage: `Error moving message: ${ex instanceof Error ? ex.message : String(ex)}`
             };
         }
     }
+    /**
+     * Lists mail folders using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
     async ListFolders(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
             const emailToUse = params.ContextData?.Email || creds.accountEmail;
-            const user = await this.GetServiceAccountWithClient(client, emailToUse);
-            if (!user || !user.id) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
+            // Use email address directly in API path
             let foldersPath;
             if (params.ParentFolderID) {
-                foldersPath = `${this.getApiUri()}/${user.id}/mailFolders/${params.ParentFolderID}/childFolders`;
+                foldersPath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/mailFolders/${params.ParentFolderID}/childFolders`;
             }
             else {
-                foldersPath = `${this.getApiUri()}/${user.id}/mailFolders`;
+                foldersPath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/mailFolders`;
             }
             const response = await client.api(foldersPath).get();
             if (!response?.value) {
@@ -617,56 +723,55 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
         }
         catch (ex) {
-            (0, core_1.LogError)('Error listing folders via MS Graph', undefined, ex);
+            LogError('Error listing folders via MS Graph', undefined, ex);
             return {
                 Success: false,
                 ErrorMessage: `Error listing folders: ${ex instanceof Error ? ex.message : String(ex)}`
             };
         }
     }
+    /**
+     * Marks messages as read or unread using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
     async MarkAsRead(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
             const emailToUse = params.ContextData?.Email || creds.accountEmail;
-            const user = await this.GetServiceAccountWithClient(client, emailToUse);
-            if (!user || !user.id) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
+            // Use email address directly in API path - update each message
             const updatePromises = params.MessageIDs.map(async (messageId) => {
-                const updatePath = `${this.getApiUri()}/${user.id}/messages/${messageId}`;
+                const updatePath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${messageId}`;
                 return client.api(updatePath).update({ isRead: params.IsRead });
             });
             await Promise.all(updatePromises);
-            (0, core_1.LogStatus)(`Marked ${params.MessageIDs.length} message(s) as ${params.IsRead ? 'read' : 'unread'}`);
+            LogStatus(`Marked ${params.MessageIDs.length} message(s) as ${params.IsRead ? 'read' : 'unread'}`);
             return { Success: true };
         }
         catch (ex) {
-            (0, core_1.LogError)('Error marking messages as read via MS Graph', undefined, ex);
+            LogError('Error marking messages as read via MS Graph', undefined, ex);
             return {
                 Success: false,
                 ErrorMessage: `Error marking messages: ${ex instanceof Error ? ex.message : String(ex)}`
             };
         }
     }
+    /**
+     * Archives a message by moving it to the Archive folder using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
     async ArchiveMessage(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
             const emailToUse = params.ContextData?.Email || creds.accountEmail;
-            const user = await this.GetServiceAccountWithClient(client, emailToUse);
-            if (!user || !user.id) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
-            let archiveFolderId = await this.findSystemFolder(client, user.id, 'archive');
+            // Find or create the Archive folder - use email address directly
+            let archiveFolderId = await this.findSystemFolder(client, emailToUse, 'archive');
             if (!archiveFolderId) {
-                archiveFolderId = await this.createMailFolder(client, user.id, 'Archive');
+                // Try to create an Archive folder
+                archiveFolderId = await this.createMailFolder(client, emailToUse, 'Archive');
             }
             if (!archiveFolderId) {
                 return {
@@ -674,41 +779,43 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
                     ErrorMessage: 'Could not find or create Archive folder'
                 };
             }
-            const movePath = `${this.getApiUri()}/${user.id}/messages/${params.MessageID}/move`;
+            // Move the message to Archive - use email address directly in API path
+            const movePath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${params.MessageID}/move`;
             await client.api(movePath).post({
                 destinationId: archiveFolderId
             });
-            (0, core_1.LogStatus)(`Message ${params.MessageID} archived`);
+            LogStatus(`Message ${params.MessageID} archived`);
             return { Success: true };
         }
         catch (ex) {
-            (0, core_1.LogError)('Error archiving message via MS Graph', undefined, ex);
+            LogError('Error archiving message via MS Graph', undefined, ex);
             return {
                 Success: false,
                 ErrorMessage: `Error archiving message: ${ex instanceof Error ? ex.message : String(ex)}`
             };
         }
     }
+    /**
+     * Searches messages using MS Graph search or filter.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
     async SearchMessages(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
             const emailToUse = params.ContextData?.Email || creds.accountEmail;
-            const user = await this.GetServiceAccountWithClient(client, emailToUse);
-            if (!user || !user.id) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
+            // Build search path - use email address directly in API path
             let messagesPath;
             if (params.FolderID) {
-                messagesPath = `${this.getApiUri()}/${user.id}/mailFolders/${params.FolderID}/messages`;
+                messagesPath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/mailFolders/${params.FolderID}/messages`;
             }
             else {
-                messagesPath = `${this.getApiUri()}/${user.id}/messages`;
+                messagesPath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages`;
             }
+            // Build filter conditions
             const filters = [];
+            // Date range filters
             if (params.FromDate) {
                 filters.push(`receivedDateTime ge ${params.FromDate.toISOString()}`);
             }
@@ -716,6 +823,7 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
                 filters.push(`receivedDateTime le ${params.ToDate.toISOString()}`);
             }
             let apiRequest = client.api(messagesPath);
+            // Use $search for text queries (MS Graph supports KQL)
             if (params.Query) {
                 apiRequest = apiRequest.search(`"${params.Query}"`);
             }
@@ -750,26 +858,25 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
         }
         catch (ex) {
-            (0, core_1.LogError)('Error searching messages via MS Graph', undefined, ex);
+            LogError('Error searching messages via MS Graph', undefined, ex);
             return {
                 Success: false,
                 ErrorMessage: `Error searching messages: ${ex instanceof Error ? ex.message : String(ex)}`
             };
         }
     }
+    /**
+     * Lists attachments on a message using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
     async ListAttachments(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
             const emailToUse = params.ContextData?.Email || creds.accountEmail;
-            const user = await this.GetServiceAccountWithClient(client, emailToUse);
-            if (!user || !user.id) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
-            const attachmentsPath = `${this.getApiUri()}/${user.id}/messages/${params.MessageID}/attachments`;
+            // Use email address directly in API path
+            const attachmentsPath = `${this.getApiUri()}/${encodeURIComponent(emailToUse)}/messages/${params.MessageID}/attachments`;
             const response = await client.api(attachmentsPath).get();
             if (!response?.value) {
                 return {
@@ -792,26 +899,25 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
         }
         catch (ex) {
-            (0, core_1.LogError)('Error listing attachments via MS Graph', undefined, ex);
+            LogError('Error listing attachments via MS Graph', undefined, ex);
             return {
                 Success: false,
                 ErrorMessage: `Error listing attachments: ${ex instanceof Error ? ex.message : String(ex)}`
             };
         }
     }
+    /**
+     * Downloads an attachment from a message using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
     async DownloadAttachment(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const client = this.getGraphClient(creds);
             const emailToUse = params.ContextData?.Email || creds.accountEmail;
-            const user = await this.GetServiceAccountWithClient(client, emailToUse);
-            if (!user || !user.id) {
-                return {
-                    Success: false,
-                    ErrorMessage: 'Service account not found'
-                };
-            }
-            const attachmentPath = `${this.getApiUri()}/${user.id}/messages/${params.MessageID}/attachments/${params.AttachmentID}`;
+            // 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();
             if (!response) {
                 return {
@@ -819,6 +925,7 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
                     ErrorMessage: 'Attachment not found'
                 };
             }
+            // MS Graph returns file attachments with contentBytes as base64
             const contentBase64 = response.contentBytes;
             return {
                 Success: true,
@@ -830,15 +937,25 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
         }
         catch (ex) {
-            (0, core_1.LogError)('Error downloading attachment via MS Graph', undefined, ex);
+            LogError('Error downloading attachment via MS Graph', undefined, ex);
             return {
                 Success: false,
                 ErrorMessage: `Error downloading attachment: ${ex instanceof Error ? ex.message : String(ex)}`
             };
         }
     }
-    async findSystemFolder(client, userId, folderName) {
+    // ========================================================================
+    // HELPER METHODS
+    // ========================================================================
+    /**
+     * Finds a system folder by well-known name.
+     *
+     * @private
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
+    async findSystemFolder(client, emailAddress, folderName) {
         try {
+            // MS Graph well-known folder names
             const wellKnownNames = {
                 'inbox': 'inbox',
                 'sent': 'sentitems',
@@ -851,13 +968,15 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
             };
             const normalizedName = folderName.toLowerCase();
             const graphFolderName = wellKnownNames[normalizedName] || normalizedName;
-            const folderPath = `${this.getApiUri()}/${userId}/mailFolders/${graphFolderName}`;
+            // 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();
             return folder?.id || null;
         }
         catch {
+            // Folder not found or access denied - try search
             try {
-                const foldersPath = `${this.getApiUri()}/${userId}/mailFolders`;
+                const foldersPath = `${this.getApiUri()}/${encodeURIComponent(emailAddress)}/mailFolders`;
                 const response = await client.api(foldersPath)
                     .filter(`displayName eq '${folderName}'`)
                     .get();
@@ -866,24 +985,35 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
                 }
             }
             catch {
+                // Ignore search errors
             }
             return null;
         }
     }
-    async createMailFolder(client, userId, folderName) {
+    /**
+     * Creates a new mail folder.
+     *
+     * @private
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
+    async createMailFolder(client, emailAddress, folderName) {
         try {
-            const foldersPath = `${this.getApiUri()}/${userId}/mailFolders`;
+            // Use email address directly in API path
+            const foldersPath = `${this.getApiUri()}/${encodeURIComponent(emailAddress)}/mailFolders`;
             const result = await client.api(foldersPath).post({
                 displayName: folderName
             });
-            (0, core_1.LogStatus)(`Created mail folder '${folderName}' with ID: ${result.id}`);
+            LogStatus(`Created mail folder '${folderName}' with ID: ${result.id}`);
             return result.id;
         }
         catch (ex) {
-            (0, core_1.LogError)(`Error creating mail folder '${folderName}'`, undefined, ex);
+            LogError(`Error creating mail folder '${folderName}'`, undefined, ex);
             return null;
         }
     }
+    /**
+     * Checks if a folder name is a system folder.
+     */
     isSystemFolder(displayName) {
         const systemFolders = [
             'inbox', 'sent items', 'drafts', 'deleted items', 'junk email',
@@ -891,6 +1021,9 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
         ];
         return systemFolders.includes(displayName.toLowerCase());
     }
+    /**
+     * Maps folder display name to system folder type.
+     */
     mapSystemFolderType(displayName) {
         const mapping = {
             'inbox': 'inbox',
@@ -903,12 +1036,9 @@ let MSGraphProvider = class MSGraphProvider extends communication_types_1.BaseCo
         return mapping[displayName.toLowerCase()] || 'other';
     }
 };
-exports.MSGraphProvider = MSGraphProvider;
-exports.MSGraphProvider = MSGraphProvider = __decorate([
-    (0, global_1.RegisterClass)(communication_types_1.BaseCommunicationProvider, 'Microsoft Graph'),
+MSGraphProvider = __decorate([
+    RegisterClass(BaseCommunicationProvider, 'Microsoft Graph'),
     __metadata("design:paramtypes", [])
 ], MSGraphProvider);
-function LoadMSGraphProvider() {
-}
-exports.LoadMSGraphProvider = LoadMSGraphProvider;
+export { MSGraphProvider };
 //# sourceMappingURL=MSGraphProvider.js.map