@memberjunction/communication-ms-graph 5.0.0 → 5.2.0

package/README.md

@@ -0,0 +1,251 @@
+# @memberjunction/communication-ms-graph
+
+Microsoft Graph (Office 365 / Exchange Online) provider for the MemberJunction Communication Framework. This provider enables full mailbox operations -- sending, receiving, searching, managing folders, attachments, drafts, and more -- through the Microsoft Graph API with Azure AD application authentication.
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph msgraph["@memberjunction/communication-ms-graph"]
+        MSP["MSGraphProvider"]
+        AUTH["Auth Module\n(ClientSecretCredential)"]
+        CFG["Config Module\n(Environment Variables)"]
+        CRED["MSGraphCredentials"]
+    end
+
+    subgraph azure["Azure / Microsoft"]
+        AAD["Azure AD\n(OAuth2 Client Credentials)"]
+        GRAPH["Microsoft Graph API\n(/users/email/...)"]
+        MAIL["Exchange Online\nMailbox"]
+    end
+
+    subgraph base["@memberjunction/communication-types"]
+        BCP["BaseCommunicationProvider"]
+    end
+
+    BCP --> MSP
+    MSP --> AUTH
+    MSP --> CFG
+    MSP --> CRED
+    AUTH --> AAD
+    MSP --> GRAPH
+    GRAPH --> MAIL
+
+    style msgraph fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style azure fill:#7c5295,stroke:#563a6b,color:#fff
+    style base fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
+
+## Installation
+
+```bash
+npm install @memberjunction/communication-ms-graph
+```
+
+## Configuration
+
+Set the following environment variables:
+
+```env
+AZURE_TENANT_ID=your-azure-tenant-id
+AZURE_CLIENT_ID=your-azure-app-client-id
+AZURE_CLIENT_SECRET=your-azure-app-client-secret
+AZURE_ACCOUNT_EMAIL=mailbox@yourdomain.com
+```
+
+### Required Azure AD App Permissions (Application type)
+
+| Permission | Operations |
+|-----------|------------|
+| `Mail.Send` | SendSingleMessage, ForwardMessage, ReplyToMessage |
+| `Mail.Read` | GetMessages, GetSingleMessage, SearchMessages, ListFolders, ListAttachments, DownloadAttachment |
+| `Mail.ReadWrite` | CreateDraft, DeleteMessage, MoveMessage, MarkAsRead, ArchiveMessage |
+| `User.Read.All` | GetServiceAccount (user lookup, optional) |
+
+## Supported Operations
+
+This provider supports all 14 operations defined in `BaseCommunicationProvider`:
+
+| Operation | Description |
+|-----------|-------------|
+| `SendSingleMessage` | Send email via Graph API |
+| `GetMessages` | Retrieve messages with filtering and header extraction |
+| `GetSingleMessage` | Retrieve a single message by ID |
+| `ForwardMessage` | Forward email to new recipients |
+| `ReplyToMessage` | Reply to an existing email thread |
+| `CreateDraft` | Create a draft message in the mailbox |
+| `DeleteMessage` | Move to Deleted Items or permanently delete |
+| `MoveMessage` | Move message to a different mail folder |
+| `ListFolders` | List mail folders with optional message counts |
+| `MarkAsRead` | Mark messages as read or unread (batch) |
+| `ArchiveMessage` | Move message to Archive folder |
+| `SearchMessages` | Full-text search with KQL syntax and date filtering |
+| `ListAttachments` | List attachments on a message |
+| `DownloadAttachment` | Download attachment content as base64/Buffer |
+
+## Usage
+
+### Sending Email
+
+```typescript
+import { CommunicationEngine } from '@memberjunction/communication-engine';
+import { Message } from '@memberjunction/communication-types';
+
+const engine = CommunicationEngine.Instance;
+await engine.Config(false, contextUser);
+
+const message = new Message();
+message.From = 'user@yourdomain.com';
+message.To = 'recipient@example.com';
+message.Subject = 'Hello from MS Graph';
+message.HTMLBody = '<h1>Hello</h1><p>Sent via Microsoft Graph.</p>';
+message.ContextData = { saveToSentItems: true };
+
+const result = await engine.SendSingleMessage(
+    'Microsoft Graph',
+    'Standard Email',
+    message
+);
+```
+
+### Per-Request Credentials
+
+Override credentials on a per-request basis for multi-tenant scenarios:
+
+```typescript
+import { MSGraphCredentials } from '@memberjunction/communication-ms-graph';
+
+const result = await engine.SendSingleMessage(
+    'Microsoft Graph',
+    'Standard Email',
+    message,
+    undefined,
+    false,
+    {
+        tenantId: 'customer-tenant-id',
+        clientId: 'customer-app-id',
+        clientSecret: 'customer-secret',
+        accountEmail: 'user@customer.com'
+    } as MSGraphCredentials
+);
+```
+
+### Reading Messages
+
+```typescript
+const provider = engine.GetProvider('Microsoft Graph');
+
+const result = await provider.GetMessages({
+    NumMessages: 10,
+    UnreadOnly: true,
+    IncludeHeaders: true,
+    ContextData: {
+        ReturnAsPlainText: true,
+        MarkAsRead: true
+    }
+});
+
+result.Messages.forEach(msg => {
+    console.log(`${msg.From}: ${msg.Subject}`);
+    console.log(`Thread: ${msg.ThreadID}`);
+});
+```
+
+### Searching Messages
+
+MS Graph supports KQL (Keyword Query Language) for search:
+
+```typescript
+const result = await provider.SearchMessages({
+    Query: 'invoice',
+    FromDate: new Date('2025-01-01'),
+    MaxResults: 25,
+    FolderID: 'inbox-folder-id'
+});
+```
+
+### Creating Drafts
+
+```typescript
+const result = await engine.CreateDraft(message, 'Microsoft Graph', contextUser);
+if (result.Success) {
+    console.log(`Draft ID: ${result.DraftID}`);
+}
+```
+
+### Managing Folders
+
+```typescript
+// List top-level folders
+const folders = await provider.ListFolders({ IncludeCounts: true });
+folders.Folders.forEach(f => {
+    console.log(`${f.Name}: ${f.MessageCount} total, ${f.UnreadCount} unread`);
+});
+
+// List subfolders
+const subfolders = await provider.ListFolders({
+    ParentFolderID: 'parent-folder-id',
+    IncludeCounts: true
+});
+
+// Move a message
+await provider.MoveMessage({
+    MessageID: 'msg-id',
+    DestinationFolderID: 'folder-id'
+});
+
+// Archive a message
+await provider.ArchiveMessage({ MessageID: 'msg-id' });
+```
+
+### Downloading Attachments
+
+```typescript
+const attachments = await provider.ListAttachments({ MessageID: 'msg-id' });
+for (const att of attachments.Attachments) {
+    const download = await provider.DownloadAttachment({
+        MessageID: 'msg-id',
+        AttachmentID: att.ID
+    });
+    // download.Content is a Buffer
+    // download.ContentBase64 is the raw base64 string
+}
+```
+
+## Client Caching
+
+The provider caches Microsoft Graph `Client` instances per credential set for performance. Environment credential clients are shared across all calls; per-request credential clients are cached by `tenantId:clientId`.
+
+## System Folder Mapping
+
+| Exchange Display Name | SystemFolderType |
+|----------------------|-----------------|
+| Inbox | `inbox` |
+| Sent Items | `sent` |
+| Drafts | `drafts` |
+| Deleted Items | `trash` |
+| Junk Email | `spam` |
+| Archive | `archive` |
+| Other folders | `other` |
+
+## HTML to Text Conversion
+
+When `ReturnAsPlainText` is set in `ContextData`, the provider uses the `html-to-text` library to convert HTML email bodies to plain text with 130-character word wrap.
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@memberjunction/communication-types` | Base provider class and type definitions |
+| `@memberjunction/core` | Logging utilities |
+| `@memberjunction/global` | RegisterClass decorator |
+| `@microsoft/microsoft-graph-client` | Microsoft Graph SDK |
+| `@azure/identity` | Azure AD ClientSecretCredential |
+| `html-to-text` | HTML to plain text conversion |
+
+## Development
+
+```bash
+npm run build    # Compile TypeScript
+npm run clean    # Remove dist directory
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/communication-ms-graph",
   "type": "module",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "MemberJunction: Microsoft Graph Provider for the MJ Communication Framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,14 +23,14 @@
   "dependencies": {
     "@azure/identity": "^4.13.0",
     "@azure/msal-node": "^5.0.3",
-    "@memberjunction/ai": "5.0.0",
-    "@memberjunction/ai-provider-bundle": "5.0.0",
-    "@memberjunction/aiengine": "5.0.0",
-    "@memberjunction/communication-types": "5.0.0",
-    "@memberjunction/core": "5.0.0",
-    "@memberjunction/core-entities": "5.0.0",
-    "@memberjunction/global": "5.0.0",
-    "@memberjunction/sqlserver-dataprovider": "5.0.0",
+    "@memberjunction/ai": "5.2.0",
+    "@memberjunction/ai-provider-bundle": "5.2.0",
+    "@memberjunction/aiengine": "5.2.0",
+    "@memberjunction/communication-types": "5.2.0",
+    "@memberjunction/core": "5.2.0",
+    "@memberjunction/core-entities": "5.2.0",
+    "@memberjunction/global": "5.2.0",
+    "@memberjunction/sqlserver-dataprovider": "5.2.0",
     "@microsoft/microsoft-graph-client": "^3.0.7",
     "@microsoft/microsoft-graph-types": "^2.43.1",
     "@types/html-to-text": "^9.0.4",