@memberjunction/communication-gmail 3.4.0 → 4.1.0

package/dist/GmailProvider.js

@@ -1,54 +1,37 @@
-"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;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LoadProvider = exports.GmailProvider = void 0;
-const communication_types_1 = require("@memberjunction/communication-types");
-const global_1 = require("@memberjunction/global");
-const core_1 = require("@memberjunction/core");
-const Config = __importStar(require("./config"));
-const googleApis = __importStar(require("googleapis"));
-let GmailProvider = class GmailProvider extends communication_types_1.BaseCommunicationProvider {
+import { BaseCommunicationProvider, resolveCredentialValue, validateRequiredCredentials } from "@memberjunction/communication-types";
+import { RegisterClass } from "@memberjunction/global";
+import { LogError, LogStatus } from "@memberjunction/core";
+import * as Config from "./config.js";
+import googleApis from 'googleapis';
+/**
+ * Implementation of the Gmail provider for sending and receiving messages
+ */
+let GmailProvider = class GmailProvider extends BaseCommunicationProvider {
     constructor() {
         super(...arguments);
+        /** Cached Gmail client for environment credentials */
         this.envGmailClient = null;
+        /** Cache of Gmail clients for per-request credentials */
         this.clientCache = new Map();
     }
+    /**
+     * Resolves credentials by merging request credentials with environment fallback
+     */
     resolveCredentials(credentials) {
         const disableFallback = credentials?.disableEnvironmentFallback ?? false;
-        const clientId = (0, communication_types_1.resolveCredentialValue)(credentials?.clientId, Config.GMAIL_CLIENT_ID, disableFallback);
-        const clientSecret = (0, communication_types_1.resolveCredentialValue)(credentials?.clientSecret, Config.GMAIL_CLIENT_SECRET, disableFallback);
-        const redirectUri = (0, communication_types_1.resolveCredentialValue)(credentials?.redirectUri, Config.GMAIL_REDIRECT_URI, disableFallback);
-        const refreshToken = (0, communication_types_1.resolveCredentialValue)(credentials?.refreshToken, Config.GMAIL_REFRESH_TOKEN, disableFallback);
-        const serviceAccountEmail = (0, communication_types_1.resolveCredentialValue)(credentials?.serviceAccountEmail, Config.GMAIL_SERVICE_ACCOUNT_EMAIL, disableFallback);
-        (0, communication_types_1.validateRequiredCredentials)({ clientId, clientSecret, redirectUri, refreshToken }, ['clientId', 'clientSecret', 'redirectUri', 'refreshToken'], 'Gmail');
+        const clientId = resolveCredentialValue(credentials?.clientId, Config.GMAIL_CLIENT_ID, disableFallback);
+        const clientSecret = resolveCredentialValue(credentials?.clientSecret, Config.GMAIL_CLIENT_SECRET, disableFallback);
+        const redirectUri = resolveCredentialValue(credentials?.redirectUri, Config.GMAIL_REDIRECT_URI, disableFallback);
+        const refreshToken = resolveCredentialValue(credentials?.refreshToken, Config.GMAIL_REFRESH_TOKEN, disableFallback);
+        const serviceAccountEmail = resolveCredentialValue(credentials?.serviceAccountEmail, Config.GMAIL_SERVICE_ACCOUNT_EMAIL, disableFallback);
+        // Validate required credentials
+        validateRequiredCredentials({ clientId, clientSecret, redirectUri, refreshToken }, ['clientId', 'clientSecret', 'redirectUri', 'refreshToken'], 'Gmail');
         return {
             clientId: clientId,
             clientSecret: clientSecret,
@@ -57,17 +40,27 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             serviceAccountEmail: serviceAccountEmail || ''
         };
     }
+    /**
+     * Creates a Gmail client with the given credentials
+     */
     createGmailClient(creds) {
+        // Create OAuth2 client
         const oauth2Client = new googleApis.google.auth.OAuth2(creds.clientId, creds.clientSecret, creds.redirectUri);
+        // Set refresh token to automatically refresh access tokens
         oauth2Client.setCredentials({
             refresh_token: creds.refreshToken
         });
+        // Create Gmail API client
         return googleApis.google.gmail({
             version: 'v1',
             auth: oauth2Client
         });
     }
+    /**
+     * Gets a Gmail client for the given credentials, using caching for efficiency
+     */
     getGmailClient(creds) {
+        // Check if using environment credentials (can use shared client)
         const isEnvCredentials = creds.clientId === Config.GMAIL_CLIENT_ID &&
             creds.clientSecret === Config.GMAIL_CLIENT_SECRET &&
             creds.refreshToken === Config.GMAIL_REFRESH_TOKEN;
@@ -80,6 +73,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             }
             return this.envGmailClient;
         }
+        // For per-request credentials, use cached client by credential key
         const cacheKey = `${creds.clientId}:${creds.refreshToken.substring(0, 10)}`;
         let cached = this.clientCache.get(cacheKey);
         if (!cached) {
@@ -91,11 +85,15 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         }
         return cached;
     }
+    /**
+     * Gets the authenticated user's email address for a given cached client
+     */
     async getUserEmail(cached) {
         if (cached.userEmail) {
             return cached.userEmail;
         }
         try {
+            // Get user profile to verify authentication
             const response = await cached.client.users.getProfile({
                 userId: 'me'
             });
@@ -106,37 +104,48 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             return null;
         }
         catch (error) {
-            (0, core_1.LogError)('Failed to get Gmail user email', undefined, error);
+            LogError('Failed to get Gmail user email', undefined, error);
             return null;
         }
     }
+    /**
+     * Encode and format email content for Gmail API
+     */
     createEmailContent(message, creds) {
+        // Get sender email
         const from = message.From || creds.serviceAccountEmail;
         const fromName = message.FromName || '';
         const fromHeader = fromName ? `${fromName} <${from}>` : from;
+        // Create email content
         const subject = message.ProcessedSubject;
         const to = message.To;
         const cc = message.CCRecipients?.join(', ') || '';
         const bcc = message.BCCRecipients?.join(', ') || '';
+        // Headers
         let emailContent = [
             `From: ${fromHeader}`,
             `To: ${to}`,
             `Subject: ${subject}`
         ];
+        // Add CC and BCC if present
         if (cc)
             emailContent.push(`Cc: ${cc}`);
         if (bcc)
             emailContent.push(`Bcc: ${bcc}`);
+        // Add content type and message body
         if (message.ProcessedHTMLBody) {
+            // For HTML emails
             const boundary = `boundary_${Math.random().toString(36).substring(2)}`;
             emailContent.push('MIME-Version: 1.0');
             emailContent.push(`Content-Type: multipart/alternative; boundary="${boundary}"`);
             emailContent.push('');
+            // Text part
             emailContent.push(`--${boundary}`);
             emailContent.push('Content-Type: text/plain; charset=UTF-8');
             emailContent.push('');
             emailContent.push(message.ProcessedBody || '');
             emailContent.push('');
+            // HTML part
             emailContent.push(`--${boundary}`);
             emailContent.push('Content-Type: text/html; charset=UTF-8');
             emailContent.push('');
@@ -145,16 +154,26 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             emailContent.push(`--${boundary}--`);
         }
         else {
+            // Plain text email
             emailContent.push('Content-Type: text/plain; charset=UTF-8');
             emailContent.push('');
             emailContent.push(message.ProcessedBody || '');
         }
         return Buffer.from(emailContent.join('\r\n')).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
     }
+    /**
+     * Sends a single message using the Gmail API
+     * @param message - The message to send
+     * @param credentials - Optional credentials override for this request.
+     *                      If not provided, uses environment variables.
+     *                      Set `credentials.disableEnvironmentFallback = true` to require explicit credentials.
+     */
     async SendSingleMessage(message, credentials) {
         try {
+            // Resolve credentials (request credentials with env fallback)
             const creds = this.resolveCredentials(credentials);
             const cached = this.getGmailClient(creds);
+            // Get user email
             const userEmail = await this.getUserEmail(cached);
             if (!userEmail) {
                 return {
@@ -163,7 +182,9 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     Error: 'Could not get user email'
                 };
             }
+            // Create raw email content in base64 URL-safe format
             const raw = this.createEmailContent(message, creds);
+            // Send the email
             const result = await cached.client.users.messages.send({
                 userId: 'me',
                 requestBody: {
@@ -171,7 +192,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                 }
             });
             if (result && result.status >= 200 && result.status < 300) {
-                (0, core_1.LogStatus)(`Email sent via Gmail: ${result.statusText}`);
+                LogStatus(`Email sent via Gmail: ${result.statusText}`);
                 return {
                     Message: message,
                     Success: true,
@@ -179,7 +200,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                 };
             }
             else {
-                (0, core_1.LogError)('Failed to send email via Gmail', undefined, result);
+                LogError('Failed to send email via Gmail', undefined, result);
                 return {
                     Message: message,
                     Success: false,
@@ -189,7 +210,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error sending message';
-            (0, core_1.LogError)('Error sending message via Gmail', undefined, error);
+            LogError('Error sending message via Gmail', undefined, error);
             return {
                 Message: message,
                 Success: false,
@@ -197,8 +218,16 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             };
         }
     }
+    /**
+     * Gets messages from Gmail
+     * @param params - Parameters for fetching messages
+     * @param credentials - Optional credentials override for this request.
+     *                      If not provided, uses environment variables.
+     *                      Set `credentials.disableEnvironmentFallback = true` to require explicit credentials.
+     */
     async GetMessages(params, credentials) {
         try {
+            // Resolve credentials (request credentials with env fallback)
             const creds = this.resolveCredentials(credentials);
             const cached = this.getGmailClient(creds);
             const userEmail = await this.getUserEmail(cached);
@@ -209,6 +238,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     ErrorMessage: 'Could not get user email'
                 };
             }
+            // Build query
             let query = '';
             if (params.UnreadOnly) {
                 query = 'is:unread';
@@ -216,6 +246,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             if (params.ContextData?.query) {
                 query = params.ContextData.query;
             }
+            // Get messages
             const response = await cached.client.users.messages.list({
                 userId: 'me',
                 maxResults: params.NumMessages,
@@ -227,6 +258,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     Messages: []
                 };
             }
+            // Get full message details for each message ID
             const messagePromises = response.data.messages.map(async (message) => {
                 const fullMessage = await cached.client.users.messages.get({
                     userId: 'me',
@@ -236,7 +268,9 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                 return fullMessage.data;
             });
             const fullMessages = await Promise.all(messagePromises);
+            // Process messages into standard format
             const processedMessages = fullMessages.map(message => {
+                // Extract headers
                 const headers = message.payload?.headers || [];
                 const getHeader = (name) => {
                     const header = headers.find(h => h.name?.toLowerCase() === name.toLowerCase());
@@ -246,11 +280,14 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                 const to = getHeader('to');
                 const subject = getHeader('subject');
                 const replyTo = getHeader('reply-to') ? [getHeader('reply-to')] : [from];
+                // Extract body
                 let body = '';
                 if (message.payload?.body?.data) {
+                    // Base64 encoded data
                     body = Buffer.from(message.payload.body.data, 'base64').toString('utf-8');
                 }
                 else if (message.payload?.parts) {
+                    // Multipart message, try to find text part
                     const textPart = message.payload.parts.find(part => part.mimeType === 'text/plain');
                     if (textPart && textPart.body?.data) {
                         body = Buffer.from(textPart.body.data, 'base64').toString('utf-8');
@@ -266,6 +303,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     ThreadID: message.threadId || ''
                 };
             });
+            // Mark as read if requested
             if (params.ContextData?.MarkAsRead) {
                 for (const message of fullMessages) {
                     if (message.id) {
@@ -281,7 +319,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error getting messages';
-            (0, core_1.LogError)('Error getting messages from Gmail', undefined, error);
+            LogError('Error getting messages from Gmail', undefined, error);
             return {
                 Success: false,
                 Messages: [],
@@ -289,6 +327,13 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             };
         }
     }
+    /**
+     * Reply to a message using Gmail API
+     * @param params - Parameters for replying to a message
+     * @param credentials - Optional credentials override for this request.
+     *                      If not provided, uses environment variables.
+     *                      Set `credentials.disableEnvironmentFallback = true` to require explicit credentials.
+     */
     async ReplyToMessage(params, credentials) {
         try {
             if (!params.MessageID) {
@@ -297,8 +342,10 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     ErrorMessage: 'Message ID not provided'
                 };
             }
+            // Resolve credentials (request credentials with env fallback)
             const creds = this.resolveCredentials(credentials);
             const cached = this.getGmailClient(creds);
+            // Get the original message to obtain threadId
             const originalMessage = await cached.client.users.messages.get({
                 userId: 'me',
                 id: params.MessageID
@@ -309,7 +356,9 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     ErrorMessage: 'Could not get thread ID from original message'
                 };
             }
+            // Create raw email content
             const raw = this.createEmailContent(params.Message, creds);
+            // Send the reply in the same thread
             const result = await cached.client.users.messages.send({
                 userId: 'me',
                 requestBody: {
@@ -332,13 +381,20 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error replying to message';
-            (0, core_1.LogError)('Error replying to message via Gmail', undefined, error);
+            LogError('Error replying to message via Gmail', undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    /**
+     * Forward a message using Gmail API
+     * @param params - Parameters for forwarding a message
+     * @param credentials - Optional credentials override for this request.
+     *                      If not provided, uses environment variables.
+     *                      Set `credentials.disableEnvironmentFallback = true` to require explicit credentials.
+     */
     async ForwardMessage(params, credentials) {
         try {
             if (!params.MessageID) {
@@ -347,8 +403,10 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     ErrorMessage: 'Message ID not provided'
                 };
             }
+            // Resolve credentials (request credentials with env fallback)
             const creds = this.resolveCredentials(credentials);
             const cached = this.getGmailClient(creds);
+            // Get the original message
             const originalMessage = await cached.client.users.messages.get({
                 userId: 'me',
                 id: params.MessageID,
@@ -360,26 +418,33 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     ErrorMessage: 'Could not get raw content of original message'
                 };
             }
+            // Convert raw message to proper format
             const rawContent = Buffer.from(originalMessage.data.raw, 'base64').toString('utf-8');
+            // Build forwarded message
             const userEmail = await this.getUserEmail(cached);
             const to = params.ToRecipients.join(', ');
             const cc = params.CCRecipients?.join(', ') || '';
             const bcc = params.BCCRecipients?.join(', ') || '';
+            // Parse the original email to extract subject
             const subjectMatch = rawContent.match(/Subject: (.*?)(\r?\n)/);
             const subject = subjectMatch ? `Fwd: ${subjectMatch[1]}` : 'Fwd: ';
+            // Headers for new message
             const emailContent = [
                 `From: ${userEmail}`,
                 `To: ${to}`,
                 `Subject: ${subject}`
             ];
+            // Add CC and BCC if present
             if (cc)
                 emailContent.push(`Cc: ${cc}`);
             if (bcc)
                 emailContent.push(`Bcc: ${bcc}`);
+            // Add content type
             const boundary = `boundary_${Math.random().toString(36).substring(2)}`;
             emailContent.push('MIME-Version: 1.0');
             emailContent.push(`Content-Type: multipart/mixed; boundary="${boundary}"`);
             emailContent.push('');
+            // Forward comment
             if (params.Message) {
                 emailContent.push(`--${boundary}`);
                 emailContent.push('Content-Type: text/plain; charset=UTF-8');
@@ -387,6 +452,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                 emailContent.push(params.Message);
                 emailContent.push('');
             }
+            // Original message as attachment
             emailContent.push(`--${boundary}`);
             emailContent.push('Content-Type: message/rfc822; name="forwarded_message.eml"');
             emailContent.push('Content-Disposition: attachment; filename="forwarded_message.eml"');
@@ -394,10 +460,12 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             emailContent.push(rawContent);
             emailContent.push('');
             emailContent.push(`--${boundary}--`);
+            // Encode email content
             const raw = Buffer.from(emailContent.join('\r\n')).toString('base64')
                 .replace(/\+/g, '-')
                 .replace(/\//g, '_')
                 .replace(/=+$/, '');
+            // Send the forwarded message
             const result = await cached.client.users.messages.send({
                 userId: 'me',
                 requestBody: {
@@ -419,13 +487,16 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error forwarding message';
-            (0, core_1.LogError)('Error forwarding message via Gmail', undefined, error);
+            LogError('Error forwarding message via Gmail', undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    /**
+     * Helper to mark a message as read
+     */
     async markMessageAsRead(gmailClient, messageId) {
         try {
             await gmailClient.users.messages.modify({
@@ -438,12 +509,20 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             return true;
         }
         catch (error) {
-            (0, core_1.LogError)(`Error marking message ${messageId} as read`, undefined, error);
+            LogError(`Error marking message ${messageId} as read`, undefined, error);
             return false;
         }
     }
+    /**
+     * Creates a draft message in Gmail
+     * @param params - Parameters for creating a draft
+     * @param credentials - Optional credentials override for this request.
+     *                      If not provided, uses environment variables.
+     *                      Set `credentials.disableEnvironmentFallback = true` to require explicit credentials.
+     */
     async CreateDraft(params, credentials) {
         try {
+            // Resolve credentials (request credentials with env fallback)
             const creds = this.resolveCredentials(credentials);
             const cached = this.getGmailClient(creds);
             const userEmail = await this.getUserEmail(cached);
@@ -453,7 +532,9 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     ErrorMessage: 'Could not get user email'
                 };
             }
+            // Reuse existing email content creation logic
             const raw = this.createEmailContent(params.Message, creds);
+            // Create draft using Gmail API
             const result = await cached.client.users.drafts.create({
                 userId: 'me',
                 requestBody: {
@@ -461,7 +542,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                 }
             });
             if (result && result.status >= 200 && result.status < 300) {
-                (0, core_1.LogStatus)(`Draft created via Gmail: ${result.data.id}`);
+                LogStatus(`Draft created via Gmail: ${result.data.id}`);
                 return {
                     Success: true,
                     DraftID: result.data.id || undefined,
@@ -469,7 +550,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                 };
             }
             else {
-                (0, core_1.LogError)('Failed to create draft via Gmail', undefined, result);
+                LogError('Failed to create draft via Gmail', undefined, result);
                 return {
                     Success: false,
                     ErrorMessage: `Failed to create draft: ${result?.statusText || 'Unknown error'}`
@@ -478,13 +559,20 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error creating draft';
-            (0, core_1.LogError)('Error creating draft via Gmail', undefined, error);
+            LogError('Error creating draft via Gmail', undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    // ========================================================================
+    // EXTENDED OPERATIONS - Gmail supports all mailbox operations via labels
+    // ========================================================================
+    /**
+     * Returns the list of operations supported by the Gmail provider.
+     * Gmail supports all operations through its label-based system.
+     */
     getSupportedOperations() {
         return [
             'SendSingleMessage',
@@ -495,7 +583,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             'CreateDraft',
             'DeleteMessage',
             'MoveMessage',
-            'ListFolders',
+            'ListFolders', // Gmail uses labels instead of folders
             'MarkAsRead',
             'ArchiveMessage',
             'SearchMessages',
@@ -503,6 +591,11 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             'DownloadAttachment'
         ];
     }
+    /**
+     * Gets a single message by ID
+     * @param params - Parameters for retrieving the message
+     * @param credentials - Optional credentials override for this request
+     */
     async GetSingleMessage(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
@@ -527,53 +620,68 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error getting message';
-            (0, core_1.LogError)(`Error getting message ${params.MessageID} from Gmail`, undefined, error);
+            LogError(`Error getting message ${params.MessageID} from Gmail`, undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    /**
+     * Deletes a message from Gmail
+     * @param params - Parameters for deleting the message
+     * @param credentials - Optional credentials override for this request
+     */
     async DeleteMessage(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const cached = this.getGmailClient(creds);
             if (params.PermanentDelete) {
+                // Permanently delete the message
                 await cached.client.users.messages.delete({
                     userId: 'me',
                     id: params.MessageID
                 });
             }
             else {
+                // Move to trash (adds TRASH label, removes INBOX)
                 await cached.client.users.messages.trash({
                     userId: 'me',
                     id: params.MessageID
                 });
             }
-            (0, core_1.LogStatus)(`Message ${params.MessageID} deleted from Gmail (permanent: ${params.PermanentDelete})`);
+            LogStatus(`Message ${params.MessageID} deleted from Gmail (permanent: ${params.PermanentDelete})`);
             return {
                 Success: true
             };
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error deleting message';
-            (0, core_1.LogError)(`Error deleting message ${params.MessageID} from Gmail`, undefined, error);
+            LogError(`Error deleting message ${params.MessageID} from Gmail`, undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    /**
+     * Moves a message to a different label (Gmail's equivalent of folders)
+     * In Gmail, moving is done by adding/removing labels
+     * @param params - Parameters for moving the message
+     * @param credentials - Optional credentials override for this request
+     */
     async MoveMessage(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const cached = this.getGmailClient(creds);
+            // First get current labels on the message
             const message = await cached.client.users.messages.get({
                 userId: 'me',
                 id: params.MessageID,
                 format: 'minimal'
             });
             const currentLabels = message.data.labelIds || [];
+            // Remove INBOX and other category labels, add the destination label
             const labelsToRemove = currentLabels.filter(label => label === 'INBOX' ||
                 label === 'CATEGORY_PERSONAL' ||
                 label === 'CATEGORY_SOCIAL' ||
@@ -588,21 +696,26 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     removeLabelIds: labelsToRemove
                 }
             });
-            (0, core_1.LogStatus)(`Message ${params.MessageID} moved to label ${params.DestinationFolderID}`);
+            LogStatus(`Message ${params.MessageID} moved to label ${params.DestinationFolderID}`);
             return {
                 Success: true,
-                NewMessageID: params.MessageID
+                NewMessageID: params.MessageID // Gmail doesn't change message ID on move
             };
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error moving message';
-            (0, core_1.LogError)(`Error moving message ${params.MessageID} in Gmail`, undefined, error);
+            LogError(`Error moving message ${params.MessageID} in Gmail`, undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    /**
+     * Lists Gmail labels (Gmail's equivalent of folders)
+     * @param params - Parameters for listing labels
+     * @param credentials - Optional credentials override for this request
+     */
     async ListFolders(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
@@ -616,6 +729,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     Folders: []
                 };
             }
+            // Get detailed info for each label if counts requested
             let labels = response.data.labels;
             if (params.IncludeCounts) {
                 const detailedLabels = await Promise.all(labels.map(async (label) => {
@@ -642,6 +756,8 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                 IsSystemFolder: label.type === 'system',
                 SystemFolderType: this.mapGmailLabelToSystemFolder(label.id || '')
             }));
+            // Filter by parent if specified (Gmail doesn't have nested labels in the API the same way)
+            // User labels can have "/" in names to simulate hierarchy
             if (params.ParentFolderID) {
                 const parent = folders.find(f => f.ID === params.ParentFolderID);
                 if (parent) {
@@ -661,17 +777,23 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error listing labels';
-            (0, core_1.LogError)('Error listing labels from Gmail', undefined, error);
+            LogError('Error listing labels from Gmail', undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    /**
+     * Marks messages as read or unread
+     * @param params - Parameters for marking messages
+     * @param credentials - Optional credentials override for this request
+     */
     async MarkAsRead(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const cached = this.getGmailClient(creds);
+            // Process all messages
             await Promise.all(params.MessageIDs.map(async (messageId) => {
                 await cached.client.users.messages.modify({
                     userId: 'me',
@@ -681,24 +803,30 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                         : { addLabelIds: ['UNREAD'] }
                 });
             }));
-            (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 (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error marking messages';
-            (0, core_1.LogError)('Error marking messages as read/unread in Gmail', undefined, error);
+            LogError('Error marking messages as read/unread in Gmail', undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    /**
+     * Archives a message (removes INBOX label in Gmail)
+     * @param params - Parameters for archiving the message
+     * @param credentials - Optional credentials override for this request
+     */
     async ArchiveMessage(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const cached = this.getGmailClient(creds);
+            // In Gmail, archiving is simply removing the INBOX label
             await cached.client.users.messages.modify({
                 userId: 'me',
                 id: params.MessageID,
@@ -706,25 +834,32 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     removeLabelIds: ['INBOX']
                 }
             });
-            (0, core_1.LogStatus)(`Message ${params.MessageID} archived in Gmail`);
+            LogStatus(`Message ${params.MessageID} archived in Gmail`);
             return {
                 Success: true
             };
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error archiving message';
-            (0, core_1.LogError)(`Error archiving message ${params.MessageID} in Gmail`, undefined, error);
+            LogError(`Error archiving message ${params.MessageID} in Gmail`, undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    /**
+     * Searches messages using Gmail's search syntax
+     * @param params - Parameters for searching messages
+     * @param credentials - Optional credentials override for this request
+     */
     async SearchMessages(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const cached = this.getGmailClient(creds);
+            // Build Gmail search query
             let query = params.Query;
+            // Add date filters if specified
             if (params.FromDate) {
                 const fromDateStr = this.formatDateForGmail(params.FromDate);
                 query += ` after:${fromDateStr}`;
@@ -733,9 +868,11 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                 const toDateStr = this.formatDateForGmail(params.ToDate);
                 query += ` before:${toDateStr}`;
             }
+            // Add folder/label filter
             if (params.FolderID) {
                 query += ` label:${params.FolderID}`;
             }
+            // Search messages
             const response = await cached.client.users.messages.list({
                 userId: 'me',
                 q: query,
@@ -748,6 +885,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     TotalCount: 0
                 };
             }
+            // Get full message details
             const fullMessages = await Promise.all(response.data.messages.map(async (msg) => {
                 const full = await cached.client.users.messages.get({
                     userId: 'me',
@@ -766,13 +904,18 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error searching messages';
-            (0, core_1.LogError)('Error searching messages in Gmail', undefined, error);
+            LogError('Error searching messages in Gmail', undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    /**
+     * Lists attachments on a message
+     * @param params - Parameters for listing attachments
+     * @param credentials - Optional credentials override for this request
+     */
     async ListAttachments(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
@@ -798,17 +941,23 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error listing attachments';
-            (0, core_1.LogError)(`Error listing attachments for message ${params.MessageID}`, undefined, error);
+            LogError(`Error listing attachments for message ${params.MessageID}`, undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    /**
+     * Downloads an attachment from a message
+     * @param params - Parameters for downloading the attachment
+     * @param credentials - Optional credentials override for this request
+     */
     async DownloadAttachment(params, credentials) {
         try {
             const creds = this.resolveCredentials(credentials);
             const cached = this.getGmailClient(creds);
+            // First get attachment metadata to find filename and content type
             const message = await cached.client.users.messages.get({
                 userId: 'me',
                 id: params.MessageID,
@@ -818,6 +967,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             if (message.data.payload) {
                 attachmentInfo = this.findAttachmentInfo(message.data.payload, params.AttachmentID);
             }
+            // Download the attachment
             const response = await cached.client.users.messages.attachments.get({
                 userId: 'me',
                 messageId: params.MessageID,
@@ -829,6 +979,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                     ErrorMessage: 'Attachment content not found'
                 };
             }
+            // Gmail returns base64url encoded data, convert to standard base64
             const base64Data = response.data.data.replace(/-/g, '+').replace(/_/g, '/');
             const content = Buffer.from(base64Data, 'base64');
             return {
@@ -842,13 +993,19 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Error downloading attachment';
-            (0, core_1.LogError)(`Error downloading attachment ${params.AttachmentID}`, undefined, error);
+            LogError(`Error downloading attachment ${params.AttachmentID}`, undefined, error);
             return {
                 Success: false,
                 ErrorMessage: errorMessage
             };
         }
     }
+    // ========================================================================
+    // HELPER METHODS
+    // ========================================================================
+    /**
+     * Parses a Gmail message into the standard GetMessageMessage format
+     */
     parseGmailMessage(message) {
         const headers = message.payload?.headers || [];
         const getHeader = (name) => {
@@ -860,6 +1017,7 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         const subject = getHeader('subject');
         const replyTo = getHeader('reply-to') ? [getHeader('reply-to')] : [from];
         const dateStr = getHeader('date');
+        // Extract body
         let body = '';
         if (message.payload?.body?.data) {
             body = Buffer.from(message.payload.body.data, 'base64').toString('utf-8');
@@ -870,14 +1028,17 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                 body = Buffer.from(textPart.body.data, 'base64').toString('utf-8');
             }
         }
+        // Parse date
         let receivedAt;
         if (dateStr) {
             try {
                 receivedAt = new Date(dateStr);
             }
             catch {
+                // Ignore parse errors
             }
         }
+        // Internal date from Gmail (epoch milliseconds)
         let createdAt;
         if (message.internalDate) {
             createdAt = new Date(parseInt(message.internalDate, 10));
@@ -894,6 +1055,9 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
             CreatedAt: createdAt
         };
     }
+    /**
+     * Maps Gmail label IDs to system folder types
+     */
     mapGmailLabelToSystemFolder(labelId) {
         const labelMap = {
             'INBOX': 'inbox',
@@ -912,13 +1076,20 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         };
         return labelMap[labelId] || undefined;
     }
+    /**
+     * Formats a date for Gmail search query (YYYY/MM/DD)
+     */
     formatDateForGmail(date) {
         const year = date.getFullYear();
         const month = (date.getMonth() + 1).toString().padStart(2, '0');
         const day = date.getDate().toString().padStart(2, '0');
         return `${year}/${month}/${day}`;
     }
+    /**
+     * Recursively extracts attachment information from message parts
+     */
     extractAttachments(part, attachments) {
+        // Check if this part is an attachment
         if (part.filename && part.body?.attachmentId) {
             attachments.push({
                 ID: part.body.attachmentId,
@@ -930,12 +1101,16 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
                 ContentID: part.headers?.find(h => h.name?.toLowerCase() === 'content-id')?.value?.replace(/[<>]/g, '') || undefined
             });
         }
+        // Recursively process nested parts
         if (part.parts) {
             for (const nestedPart of part.parts) {
                 this.extractAttachments(nestedPart, attachments);
             }
         }
     }
+    /**
+     * Finds attachment info (filename, content type) by attachment ID
+     */
     findAttachmentInfo(part, attachmentId) {
         if (part.body?.attachmentId === attachmentId) {
             return {
@@ -953,11 +1128,8 @@ let GmailProvider = class GmailProvider extends communication_types_1.BaseCommun
         return null;
     }
 };
-exports.GmailProvider = GmailProvider;
-exports.GmailProvider = GmailProvider = __decorate([
-    (0, global_1.RegisterClass)(communication_types_1.BaseCommunicationProvider, 'Gmail')
+GmailProvider = __decorate([
+    RegisterClass(BaseCommunicationProvider, 'Gmail')
 ], GmailProvider);
-function LoadProvider() {
-}
-exports.LoadProvider = LoadProvider;
+export { GmailProvider };
 //# sourceMappingURL=GmailProvider.js.map