@memberjunction/communication-types

Core types, interfaces, and abstract base classes for the MemberJunction Communication Framework. This package defines the contract that all communication providers must implement, along with shared message types, credential utilities, and the communication engine base class.

Architecture

graph TD
    subgraph base["@memberjunction/communication-types"]
        ENGINE["CommunicationEngineBase"]
        BCP["BaseCommunicationProvider"]
        MSG["Message / ProcessedMessage"]
        CRED["Credential Utilities"]
        TYPES["Params and Result Types"]
    end

    subgraph providers["Provider Implementations"]
        SG["SendGrid Provider"]
        GM["Gmail Provider"]
        TW["Twilio Provider"]
        MSP["MS Graph Provider"]
    end

    subgraph engine["@memberjunction/communication-engine"]
        CE["CommunicationEngine"]
    end

    ENGINE --> CE
    BCP --> SG
    BCP --> GM
    BCP --> TW
    BCP --> MSP
    MSG --> BCP
    CRED --> BCP
    TYPES --> BCP

    style base fill:#2d6a9f,stroke:#1a4971,color:#fff
    style providers fill:#2d8659,stroke:#1a5c3a,color:#fff
    style engine fill:#7c5295,stroke:#563a6b,color:#fff

Installation

npm install @memberjunction/communication-types

Key Exports

CommunicationEngineBase

Singleton base class that loads communication metadata (providers, message types, entity communication fields) and provides lifecycle management for communication runs and logs.

import { CommunicationEngineBase } from '@memberjunction/communication-types';

const engine = CommunicationEngineBase.Instance;
await engine.Config(false, contextUser);

// Access loaded metadata
const providers = engine.Providers;           // MJCommunicationProviderEntityExtended[]
const messageTypes = engine.BaseMessageTypes; // CommunicationBaseMessageTypeEntity[]

BaseCommunicationProvider

Abstract base class that all communication providers must extend. Defines both core operations (must implement) and extended mailbox operations (optional override).

classDiagram
    class BaseCommunicationProvider {
        <<abstract>>
        +SendSingleMessage(message, credentials?) MessageResult
        +GetMessages(params, credentials?) GetMessagesResult
        +ForwardMessage(params, credentials?) ForwardMessageResult
        +ReplyToMessage(params, credentials?) ReplyToMessageResult
        +CreateDraft(params, credentials?) CreateDraftResult
        +getSupportedOperations() ProviderOperation[]
        +supportsOperation(op) boolean
        +GetSingleMessage() GetSingleMessageResult
        +DeleteMessage() DeleteMessageResult
        +MoveMessage() MoveMessageResult
        +ListFolders() ListFoldersResult
        +MarkAsRead() MarkAsReadResult
        +ArchiveMessage() ArchiveMessageResult
        +SearchMessages() SearchMessagesResult
        +ListAttachments() ListAttachmentsResult
        +DownloadAttachment() DownloadAttachmentResult
    }

    class SendGridProvider {
        SendSingleMessage only
    }
    class GmailProvider {
        All 14 operations
    }
    class MSGraphProvider {
        All 14 operations
    }
    class TwilioProvider {
        Send Get Forward Reply
    }

    BaseCommunicationProvider <|-- SendGridProvider
    BaseCommunicationProvider <|-- GmailProvider
    BaseCommunicationProvider <|-- MSGraphProvider
    BaseCommunicationProvider <|-- TwilioProvider

    style BaseCommunicationProvider fill:#2d6a9f,stroke:#1a4971,color:#fff
    style SendGridProvider fill:#b8762f,stroke:#8a5722,color:#fff
    style GmailProvider fill:#2d8659,stroke:#1a5c3a,color:#fff
    style MSGraphProvider fill:#2d8659,stroke:#1a5c3a,color:#fff
    style TwilioProvider fill:#7c5295,stroke:#563a6b,color:#fff

Core Operations (Abstract -- Must Implement)

| Method | Description | |--------|-------------| | SendSingleMessage() | Send a single message through the provider | | GetMessages() | Retrieve messages from the provider | | ForwardMessage() | Forward a message to new recipients | | ReplyToMessage() | Reply to an existing message | | CreateDraft() | Create a draft message (return error if unsupported) |

Extended Operations (Optional -- Override to Support)

These methods have default implementations that return "not supported" errors. Override them in providers that have full mailbox access.

| Method | Description | |--------|-------------| | GetSingleMessage() | Retrieve a single message by ID | | DeleteMessage() | Delete or trash a message | | MoveMessage() | Move a message to a different folder | | ListFolders() | List available folders/labels | | MarkAsRead() | Mark messages as read or unread | | ArchiveMessage() | Archive a message | | SearchMessages() | Search messages by query string | | ListAttachments() | List attachments on a message | | DownloadAttachment() | Download an attachment by ID |

Capability Discovery

const operations = provider.getSupportedOperations();

if (provider.supportsOperation('SearchMessages')) {
    const results = await provider.SearchMessages({ Query: 'invoice' });
}

Message Classes

• Message: Holds all data for a single communication including optional template references, CC/BCC recipients, headers, and scheduled send time.
• ProcessedMessage: Abstract subclass of Message with rendered content (ProcessedBody, ProcessedHTMLBody, ProcessedSubject) and a Process() method for template rendering.
• MessageRecipient: Represents a single recipient with per-recipient template context data.
• MessageResult: Result of a send operation including success/failure status, error details, and the processed message.

import { Message, ProcessedMessage, MessageRecipient } from '@memberjunction/communication-types';

const message = new Message();
message.From = '[email protected]';
message.To = '[email protected]';
message.Subject = 'Hello';
message.Body = 'Plain text body';
message.HTMLBody = '<p>HTML body</p>';
message.CCRecipients = ['[email protected]'];
message.BCCRecipients = ['[email protected]'];
message.Headers = { 'X-Custom': 'value' };
message.SendAt = new Date('2025-01-01');

// Template-based messages
message.BodyTemplate = templateEntity;
message.SubjectTemplate = subjectTemplateEntity;
message.ContextData = { name: 'John', company: 'Acme Corp' };

Credential Utilities

The credential system supports per-request credential overrides while maintaining backward compatibility with environment variables.

import {
    ProviderCredentialsBase,
    resolveCredentialValue,
    validateRequiredCredentials,
    resolveCredentials
} from '@memberjunction/communication-types';

// Resolve a single credential (request value takes precedence over env fallback)
const apiKey = resolveCredentialValue(
    credentials?.apiKey,        // from request
    process.env.SENDGRID_KEY,   // environment fallback
    false                       // disableEnvironmentFallback
);

// Validate all required fields are present
validateRequiredCredentials(
    { apiKey, tenantId },
    ['apiKey', 'tenantId'],
    'MyProvider'
);

// Resolve multiple fields with source tracking
const result = resolveCredentials(
    requestCredentials,
    envCredentials,
    ['apiKey', 'secret'],
    false
);
// result.source: 'request' | 'environment' | 'mixed'
// result.fieldSources: { apiKey: 'request', secret: 'environment' }

Communication Runs and Logging

The engine provides methods for tracking communication activities through database entities:

const run = await engine.StartRun();
const log = await engine.StartLog(processedMessage, run);
// ... send message ...
log.Status = 'Complete';
await log.Save();
await engine.EndRun(run);

Type Definitions

All parameter and result types used across the framework:

| Type | Purpose | |------|---------| | GetMessagesParams / GetMessagesResult | Message retrieval | | ForwardMessageParams / ForwardMessageResult | Message forwarding | | ReplyToMessageParams / ReplyToMessageResult | Message replies | | CreateDraftParams / CreateDraftResult | Draft creation | | GetSingleMessageParams / GetSingleMessageResult | Single message retrieval | | DeleteMessageParams / DeleteMessageResult | Message deletion | | MoveMessageParams / MoveMessageResult | Folder management | | ListFoldersParams / ListFoldersResult | Folder listing | | MarkAsReadParams / MarkAsReadResult | Read status | | SearchMessagesParams / SearchMessagesResult | Message search | | ListAttachmentsParams / ListAttachmentsResult | Attachment listing | | DownloadAttachmentParams / DownloadAttachmentResult | Attachment download | | ProviderOperation | Union type of all operation names | | MessageFolder / MessageAttachment | Data structures for folders and attachments |

Dependencies

| Package | Purpose | |---------|---------| | @memberjunction/core | BaseEngine, UserInfo, logging utilities | | @memberjunction/core-entities | Generated entity types for Communication metadata | | @memberjunction/global | RegisterClass decorator and MJGlobal class factory | | @memberjunction/templates-base-types | Template entity types for message templating |

Development

npm run build    # Compile TypeScript
npm start        # Watch mode