@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

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

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.

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

const message = new Message();
message.From = '[email protected]';
message.To = '[email protected]';
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

const recipients: MessageRecipient[] = [
    { To: '[email protected]', FullName: 'Alice', ContextData: { role: 'admin' } },
    { To: '[email protected]', FullName: 'Bob', ContextData: { role: 'user' } }
];

const message = new Message();
message.From = '[email protected]';
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

const message = new Message();
message.From = '[email protected]';
message.To = '[email protected]';
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:

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.

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

npm run build    # Compile TypeScript
npm start        # Watch mode