@memberjunction/entity-communications-base

Shared types and base classes for entity-based communications in MemberJunction. This package defines the parameter, result, and data structures used by both the client-side (entity-comm-client) and server-side (entity-comm-server) entity communication implementations.

Architecture

graph TD
    subgraph base["@memberjunction/entity-communications-base"]
        ENGINE["EntityCommunicationsEngineBase\n(Abstract Singleton)"]
        PARAMS["EntityCommunicationParams"]
        RESULT["EntityCommunicationResult"]
        EXT["MJEntityCommunicationMessageTypeEntityExtended"]
    end

    subgraph client["entity-comm-client"]
        CC["EntityCommunicationsEngineClient\n(GraphQL)"]
    end

    subgraph server["entity-comm-server"]
        CS["EntityCommunicationsEngine\n(Server-Side)"]
    end

    subgraph types["@memberjunction/communication-types"]
        MSG["Message / ProcessedMessage"]
    end

    ENGINE --> CC
    ENGINE --> CS
    PARAMS --> CC
    PARAMS --> CS
    RESULT --> CC
    RESULT --> CS
    MSG --> PARAMS

    style base fill:#2d6a9f,stroke:#1a4971,color:#fff
    style client fill:#b8762f,stroke:#8a5722,color:#fff
    style server fill:#2d8659,stroke:#1a5c3a,color:#fff
    style types fill:#7c5295,stroke:#563a6b,color:#fff

Installation

npm install @memberjunction/entity-communications-base

Key Exports

EntityCommunicationsEngineBase

Abstract singleton base class that loads entity communication metadata including message types, field mappings, and provider associations. Both the client and server implementations extend this class.

import { EntityCommunicationsEngineBase } from '@memberjunction/entity-communications-base';

// After Config(), access loaded metadata
const messageTypes = engine.EntityCommunicationMessageTypes;

// Check entity support
if (engine.EntitySupportsCommunication(entityID)) {
    const types = engine.GetEntityCommunicationMessageTypes(entityID);
}

Abstract Method

abstract RunEntityCommunication(
    params: EntityCommunicationParams
): Promise<EntityCommunicationResult>;

Both EntityCommunicationsEngineClient and EntityCommunicationsEngine (server) implement this method with their respective communication strategies.

EntityCommunicationParams

Defines the parameters for running an entity-based communication.

import { EntityCommunicationParams } from '@memberjunction/entity-communications-base';

const params: EntityCommunicationParams = {
    EntityID: 'entity-uuid',
    RunViewParams: {
        EntityName: 'Contacts',
        ExtraFilter: 'Status = "Active"',
        OrderBy: 'LastName, FirstName'
    },
    ProviderName: 'SendGrid',
    ProviderMessageTypeName: 'Email',
    Message: {
        Subject: 'Monthly Newsletter',
        Body: 'Hello {{FirstName}}!',
        HTMLBody: '<h1>Hello {{FirstName}}!</h1>',
        ContextData: { CompanyName: 'Acme Corp' }
    },
    PreviewOnly: false,
    IncludeProcessedMessages: true
};

Property	Type	Required	Description
EntityID	string	Yes	UUID of the entity to communicate with
RunViewParams	RunViewParams	Yes	View parameters for selecting recipient records
ProviderName	string	Yes	Communication provider name (e.g., “SendGrid”)
ProviderMessageTypeName	string	Yes	Message type (e.g., “Email”, “SMS”)
Message	Message	Yes	Message content and optional templates
PreviewOnly	boolean	No	Preview without sending
IncludeProcessedMessages	boolean	No	Include rendered content in results

EntityCommunicationResult / EntityCommunicationResultItem

interface EntityCommunicationResult {
    Success: boolean;
    ErrorMessage?: string;
    Results?: EntityCommunicationResultItem[];
}

interface EntityCommunicationResultItem {
    RecipientData: Record<string, unknown>;  // Entity record fields
    Message: ProcessedMessage;               // Rendered message
}

MJEntityCommunicationMessageTypeEntityExtended

Extends the base EntityCommunicationMessageTypeEntity with communication field mappings, linking base message types to entity-specific fields for recipient resolution.

const messageTypes = engine.GetEntityCommunicationMessageTypes(entityID);
messageTypes.forEach(mt => {
    console.log(`Type: ${mt.BaseMessageType}`);
    mt.CommunicationFields.forEach(field => {
        console.log(`  Field: ${field.FieldName} (Priority: ${field.Priority})`);
    });
});

Data Flow

sequenceDiagram
    participant App as Application
    participant Engine as EntityCommEngine
    participant View as RunView
    participant Comm as CommunicationEngine

    App->>Engine: RunEntityCommunication(params)
    Engine->>Engine: Validate entity and message type
    Engine->>View: RunView(params.RunViewParams)
    View-->>Engine: Entity records[]
    loop For each record
        Engine->>Engine: Build message with record context
        Engine->>Comm: SendSingleMessage(provider, type, msg)
        Comm-->>Engine: MessageResult
    end
    Engine-->>App: EntityCommunicationResult

Dependencies

Package	Purpose
@memberjunction/core	BaseEngine, RunView, UserInfo, EntityInfo
@memberjunction/core-entities	Entity Communication metadata types
@memberjunction/communication-types	Message and ProcessedMessage classes
@memberjunction/global	RegisterClass decorator

Development

npm run build    # Compile TypeScript
npm start        # Watch mode