@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
Copy

Installation

npm install @memberjunction/entity-communications-base
Copy

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);
}
Copy

Abstract Method

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

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
};
Copy

EntityCommunicationResult / EntityCommunicationResultItem

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

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

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})`);
    });
});
Copy

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
Copy

Dependencies

Development

npm run build    # Compile TypeScript
npm start        # Watch mode
Copy