@memberjunction/communication-ms-graph 3.4.0 → 4.0.0

package/dist/MSGraphProvider.d.ts

@@ -0,0 +1,284 @@
+import { BaseCommunicationProvider, CreateDraftParams, CreateDraftResult, ForwardMessageParams, ForwardMessageResult, GetMessagesParams, GetMessagesResult, GetSingleMessageParams, GetSingleMessageResult, DeleteMessageParams, DeleteMessageResult, MoveMessageParams, MoveMessageResult, ListFoldersParams, ListFoldersResult, MarkAsReadParams, MarkAsReadResult, ArchiveMessageParams, ArchiveMessageResult, SearchMessagesParams, SearchMessagesResult, ListAttachmentsParams, ListAttachmentsResult, DownloadAttachmentParams, DownloadAttachmentResult, ProviderOperation, MessageResult, ProcessedMessage, ProviderCredentialsBase, ReplyToMessageParams, ReplyToMessageResult } from "@memberjunction/communication-types";
+import { Client } from '@microsoft/microsoft-graph-client';
+import { Message } from "@microsoft/microsoft-graph-types";
+/**
+ * Credentials for Microsoft Graph (Azure AD) email provider.
+ *
+ * @example
+ * ```typescript
+ * // Use with SendSingleMessage
+ * await provider.SendSingleMessage(message, {
+ *     tenantId: 'your-tenant-id',
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-client-secret',
+ *     accountEmail: 'user@domain.com'
+ * });
+ *
+ * // Override only accountEmail (use env vars for auth)
+ * await provider.SendSingleMessage(message, {
+ *     accountEmail: 'different-mailbox@domain.com'
+ * });
+ *
+ * // Disable environment fallback
+ * await provider.SendSingleMessage(message, {
+ *     tenantId: 'your-tenant-id',
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-client-secret',
+ *     accountEmail: 'user@domain.com',
+ *     disableEnvironmentFallback: true
+ * });
+ * ```
+ */
+export interface MSGraphCredentials extends ProviderCredentialsBase {
+    /**
+     * Azure AD tenant ID (GUID).
+     * If not provided, falls back to AZURE_TENANT_ID environment variable.
+     */
+    tenantId?: string;
+    /**
+     * Azure AD application (client) ID (GUID).
+     * If not provided, falls back to AZURE_CLIENT_ID environment variable.
+     */
+    clientId?: string;
+    /**
+     * Azure AD application client secret.
+     * If not provided, falls back to AZURE_CLIENT_SECRET environment variable.
+     */
+    clientSecret?: string;
+    /**
+     * Email address of the mailbox to send from.
+     * If not provided, falls back to AZURE_ACCOUNT_EMAIL environment variable.
+     * Can also be overridden via message.From.
+     */
+    accountEmail?: string;
+}
+/**
+ * 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'
+ * });
+ * ```
+ */
+export declare class MSGraphProvider extends BaseCommunicationProvider {
+    private HTMLConverter;
+    private clientCache;
+    constructor();
+    /**
+     * Resolves MS Graph credentials from request and environment.
+     */
+    private resolveCredentials;
+    /**
+     * Gets or creates a Graph client for the given credentials.
+     * Uses cached client if credentials match environment (default case).
+     */
+    private getGraphClient;
+    /**
+     * Gets the API URI for Graph API calls.
+     */
+    private getApiUri;
+    /**
+     * Sends a single email message via MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Send (Application)
+     */
+    SendSingleMessage(message: ProcessedMessage, credentials?: MSGraphCredentials): Promise<MessageResult>;
+    /**
+     * Replies to an email message via MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Send (Application)
+     */
+    ReplyToMessage(params: ReplyToMessageParams, credentials?: MSGraphCredentials): Promise<ReplyToMessageResult>;
+    /**
+     * Retrieves email messages from a mailbox via MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application), or Mail.ReadWrite if using ContextData.MarkAsRead option
+     */
+    GetMessages(params: GetMessagesParams<Record<string, unknown>>, credentials?: MSGraphCredentials): Promise<GetMessagesResult<Message>>;
+    /**
+     * Forwards an email message via MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Send (Application)
+     */
+    ForwardMessage(params: ForwardMessageParams, credentials?: MSGraphCredentials): Promise<ForwardMessageResult>;
+    /**
+     * 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)
+     */
+    protected GetHeadersWithEmail(client: Client, emailAddress: string, params: GetMessagesParams, messageID: string | undefined): Promise<Record<string, string>>;
+    /**
+     * 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)
+     */
+    protected MarkMessageAsReadWithEmail(client: Client, emailAddress: string, messageID: string): Promise<boolean>;
+    /**
+     * 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
+     */
+    protected GetServiceAccountWithClient(client: Client, email: string): Promise<{
+        id?: string;
+        userPrincipalName?: string;
+    } | null>;
+    /**
+     * 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
+     */
+    protected GetServiceAccount(email?: string): Promise<{
+        id?: string;
+        userPrincipalName?: string;
+    } | null>;
+    /**
+     * 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)
+     */
+    protected GetHeadersWithClient(client: Client, params: GetMessagesParams, user: {
+        id?: string;
+        userPrincipalName?: string;
+    }, messageID: string | undefined): Promise<Record<string, string>>;
+    /**
+     * Gets headers using default client.
+     *
+     * @protected
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
+    protected GetHeaders(params: GetMessagesParams, user: {
+        id?: string;
+        userPrincipalName?: string;
+    }, messageID: string | undefined): Promise<Record<string, string>>;
+    /**
+     * Marks a message as read using User ID.
+     * For better performance, consider using MarkMessageAsReadWithEmail() instead.
+     *
+     * @protected
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
+    protected MarkMessageAsReadWithClient(client: Client, userID: string, messageID: string): Promise<boolean>;
+    /**
+     * Marks a message as read using default client.
+     *
+     * @protected
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
+    protected MarkMessageAsRead(userID: string, messageID: string): Promise<boolean>;
+    /**
+     * Creates a draft email message via MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
+    CreateDraft(params: CreateDraftParams, credentials?: MSGraphCredentials): Promise<CreateDraftResult>;
+    /**
+     * Returns the list of operations supported by MS Graph provider.
+     * MS Graph supports all mailbox operations.
+     */
+    getSupportedOperations(): ProviderOperation[];
+    /**
+     * Gets a single message by ID from MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
+    GetSingleMessage(params: GetSingleMessageParams, credentials?: MSGraphCredentials): Promise<GetSingleMessageResult>;
+    /**
+     * Deletes a message using MS Graph.
+     * If PermanentDelete is false, moves to Deleted Items folder.
+     *
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
+    DeleteMessage(params: DeleteMessageParams, credentials?: MSGraphCredentials): Promise<DeleteMessageResult>;
+    /**
+     * Moves a message to a different folder using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
+    MoveMessage(params: MoveMessageParams, credentials?: MSGraphCredentials): Promise<MoveMessageResult>;
+    /**
+     * Lists mail folders using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
+    ListFolders(params: ListFoldersParams, credentials?: MSGraphCredentials): Promise<ListFoldersResult>;
+    /**
+     * Marks messages as read or unread using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
+    MarkAsRead(params: MarkAsReadParams, credentials?: MSGraphCredentials): Promise<MarkAsReadResult>;
+    /**
+     * Archives a message by moving it to the Archive folder using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
+    ArchiveMessage(params: ArchiveMessageParams, credentials?: MSGraphCredentials): Promise<ArchiveMessageResult>;
+    /**
+     * Searches messages using MS Graph search or filter.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
+    SearchMessages(params: SearchMessagesParams, credentials?: MSGraphCredentials): Promise<SearchMessagesResult>;
+    /**
+     * Lists attachments on a message using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
+    ListAttachments(params: ListAttachmentsParams, credentials?: MSGraphCredentials): Promise<ListAttachmentsResult>;
+    /**
+     * Downloads an attachment from a message using MS Graph.
+     *
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
+    DownloadAttachment(params: DownloadAttachmentParams, credentials?: MSGraphCredentials): Promise<DownloadAttachmentResult>;
+    /**
+     * Finds a system folder by well-known name.
+     *
+     * @private
+     * @requires MS Graph Scope: Mail.Read (Application)
+     */
+    private findSystemFolder;
+    /**
+     * Creates a new mail folder.
+     *
+     * @private
+     * @requires MS Graph Scope: Mail.ReadWrite (Application)
+     */
+    private createMailFolder;
+    /**
+     * Checks if a folder name is a system folder.
+     */
+    private isSystemFolder;
+    /**
+     * Maps folder display name to system folder type.
+     */
+    private mapSystemFolderType;
+}
+//# sourceMappingURL=MSGraphProvider.d.ts.map

package/dist/MSGraphProvider.d.ts.map

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