@memberjunction/communication-engine 5.0.0 → 5.1.0

package/README.md

@@ -0,0 +1,198 @@
+# @memberjunction/communication-engine
+
+Server-side communication engine for MemberJunction. This package extends `CommunicationEngineBase` from `@memberjunction/communication-types` to provide the concrete implementation for sending messages, creating drafts, and managing communication runs through registered providers.
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph engine["@memberjunction/communication-engine"]
+        CE["CommunicationEngine\n(Singleton)"]
+        PMS["ProcessedMessageServer"]
+    end
+
+    subgraph base["@memberjunction/communication-types"]
+        CEB["CommunicationEngineBase"]
+        BCP["BaseCommunicationProvider"]
+        MSG["Message"]
+    end
+
+    subgraph providers["Registered Providers"]
+        SG["SendGrid"]
+        GM["Gmail"]
+        TW["Twilio"]
+        MSP["MS Graph"]
+    end
+
+    subgraph templates["@memberjunction/templates"]
+        TE["TemplateEngineServer"]
+    end
+
+    CEB --> CE
+    CE -->|GetProvider| BCP
+    CE -->|processes| MSG
+    MSG --> PMS
+    PMS -->|renders via| TE
+    BCP --> SG
+    BCP --> GM
+    BCP --> TW
+    BCP --> MSP
+
+    style engine fill:#7c5295,stroke:#563a6b,color:#fff
+    style base fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style providers fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style templates fill:#b8762f,stroke:#8a5722,color:#fff
+```
+
+## Installation
+
+```bash
+npm install @memberjunction/communication-engine
+```
+
+## Key Classes
+
+### CommunicationEngine
+
+Singleton engine that orchestrates message sending across all registered providers. Handles provider lookup via the MJGlobal class factory, message processing (template rendering), communication run lifecycle, and logging.
+
+```typescript
+import { CommunicationEngine } from '@memberjunction/communication-engine';
+import { Message, MessageRecipient } from '@memberjunction/communication-types';
+
+const engine = CommunicationEngine.Instance;
+await engine.Config(false, contextUser);
+```
+
+### Sending a Single Message
+
+```typescript
+const message = new Message();
+message.From = 'sender@example.com';
+message.To = 'recipient@example.com';
+message.Subject = 'Welcome';
+message.HTMLBody = '<h1>Hello</h1>';
+
+const result = await engine.SendSingleMessage(
+    'SendGrid',           // provider name
+    'Email',              // provider message type name
+    message,
+    undefined,            // optional CommunicationRunEntity
+    false                 // previewOnly
+);
+
+if (result.Success) {
+    console.log('Message sent');
+}
+```
+
+### Sending to Multiple Recipients
+
+```typescript
+const recipients: MessageRecipient[] = [
+    { To: 'alice@example.com', FullName: 'Alice', ContextData: { role: 'admin' } },
+    { To: 'bob@example.com', FullName: 'Bob', ContextData: { role: 'user' } }
+];
+
+const message = new Message();
+message.From = 'noreply@example.com';
+message.BodyTemplate = templateEntity; // uses template for personalization
+message.Subject = 'Update';
+
+const results = await engine.SendMessages(
+    'SendGrid',
+    'Email',
+    message,
+    recipients,
+    false // previewOnly
+);
+// results is MessageResult[] - one per recipient
+```
+
+### Creating a Draft
+
+```typescript
+const message = new Message();
+message.From = 'user@example.com';
+message.To = 'recipient@example.com';
+message.Subject = 'Draft Email';
+message.HTMLBody = '<p>Content here</p>';
+
+const result = await engine.CreateDraft(
+    message,
+    'Microsoft Graph', // only providers with SupportsDrafts
+    contextUser
+);
+
+if (result.Success) {
+    console.log(`Draft ID: ${result.DraftID}`);
+}
+```
+
+### Per-Request Credentials
+
+All send methods accept an optional `credentials` parameter for per-request credential overrides:
+
+```typescript
+import { SendGridCredentials } from '@memberjunction/communication-sendgrid';
+
+const result = await engine.SendSingleMessage(
+    'SendGrid',
+    'Email',
+    message,
+    undefined,
+    false,
+    { apiKey: 'SG.customer-specific-key' } // per-request credentials
+);
+```
+
+### ProcessedMessageServer
+
+Server-side implementation of `ProcessedMessage` that renders templates using `TemplateEngineServer`. Automatically processes body, HTML body, and subject templates with the provided context data.
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant CE as CommunicationEngine
+    participant PMS as ProcessedMessageServer
+    participant TE as TemplateEngineServer
+    participant P as Provider
+
+    App->>CE: SendSingleMessage(providerName, messageType, message)
+    CE->>CE: GetProvider(providerName)
+    CE->>PMS: new ProcessedMessageServer(message)
+    CE->>PMS: Process()
+    PMS->>TE: RenderTemplate(bodyTemplate, contextData)
+    TE-->>PMS: rendered content
+    PMS-->>CE: ProcessResult
+    CE->>P: SendSingleMessage(processedMessage, credentials)
+    P-->>CE: MessageResult
+    CE-->>App: MessageResult
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `Config(forceRefresh, contextUser, provider)` | Initialize the engine and load metadata |
+| `GetProvider(providerName)` | Retrieve a provider instance from the class factory |
+| `SendSingleMessage(provider, type, message, run?, preview?, credentials?)` | Send one message |
+| `SendMessages(provider, type, message, recipients, preview?, credentials?)` | Send to multiple recipients |
+| `CreateDraft(message, providerName, contextUser?, credentials?)` | Create a draft message |
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@memberjunction/communication-types` | Base engine, provider, and message types |
+| `@memberjunction/core` | UserInfo, logging, metadata access |
+| `@memberjunction/core-entities` | CommunicationRunEntity and related entities |
+| `@memberjunction/global` | MJGlobal class factory for provider instantiation |
+| `@memberjunction/templates` | Server-side template rendering engine |
+
+## Development
+
+```bash
+npm run build    # Compile TypeScript
+npm start        # Watch mode
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/communication-engine",
   "type": "module",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "MemberJunction: Core Communication Framework Library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,11 +20,11 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@memberjunction/global": "5.0.0",
-    "@memberjunction/core": "5.0.0",
-    "@memberjunction/templates": "5.0.0",
-    "@memberjunction/core-entities": "5.0.0",
-    "@memberjunction/communication-types": "5.0.0",
+    "@memberjunction/global": "5.1.0",
+    "@memberjunction/core": "5.1.0",
+    "@memberjunction/templates": "5.1.0",
+    "@memberjunction/core-entities": "5.1.0",
+    "@memberjunction/communication-types": "5.1.0",
     "rxjs": "^7.8.2"
   },
   "repository": {