@memberjunction/entity-communications-client

Client-side (Angular / browser) implementation of the MemberJunction Entity Communications Engine. This package sends entity communication requests to the server via GraphQL, enabling bulk messaging to records retrieved from entity views.

Architecture

graph TD
    subgraph client["@memberjunction/entity-comm-client"]
        ECC["EntityCommunicationsEngineClient"]
    end

    subgraph base["@memberjunction/entity-communications-base"]
        ECB["EntityCommunicationsEngineBase"]
        PARAMS["EntityCommunicationParams"]
        RESULT["EntityCommunicationResult"]
    end

    subgraph graphql["@memberjunction/graphql-dataprovider"]
        GQL["GraphQLDataProvider"]
    end

    subgraph api["MJAPI Server"]
        RESOLVER["GraphQL Resolver"]
        SERVER["EntityCommunicationsEngine\n(Server)"]
    end

    ECB --> ECC
    ECC -->|mutation| GQL
    GQL -->|HTTP| RESOLVER
    RESOLVER --> SERVER

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

Installation

npm install @memberjunction/entity-communications-client
Copy

Usage

Basic Example

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

const client = new EntityCommunicationsEngineClient();
await client.Config();

const params: EntityCommunicationParams = {
    EntityID: '123',
    RunViewParams: {
        ViewID: '456',
        ExtraFilter: 'IsActive = 1',
        MaxRows: 100
    },
    ProviderName: 'SendGrid',
    ProviderMessageTypeName: 'Email',
    Message: {
        From: 'noreply@example.com',
        To: '{{Email}}',
        Subject: 'Important Update',
        Body: 'Hello {{FirstName}}, we have an update for you.',
        ContextData: {
            CompanyName: 'Acme Corp'
        }
    },
    PreviewOnly: false,
    IncludeProcessedMessages: true
};

const result = await client.RunEntityCommunication(params);

if (result.Success) {
    console.log(`Sent ${result.Results.length} messages`);
} else {
    console.error(`Failed: ${result.ErrorMessage}`);
}
Copy

Preview Mode

Test communications without actually sending messages:

const params: EntityCommunicationParams = {
    // ...same parameters...
    PreviewOnly: true,
    IncludeProcessedMessages: true
};

const result = await client.RunEntityCommunication(params);
result.Results.forEach(item => {
    console.log('Would send to:', item.RecipientData);
    console.log('Subject:', item.Message.ProcessedSubject);
    console.log('Body:', item.Message.ProcessedBody);
});
Copy

Using Templates

const params: EntityCommunicationParams = {
    EntityID: '123',
    RunViewParams: { ViewID: '456' },
    ProviderName: 'SendGrid',
    ProviderMessageTypeName: 'Email',
    Message: {
        From: 'welcome@example.com',
        To: '{{Email}}',
        SubjectTemplate: subjectTemplate,
        BodyTemplate: bodyTemplate,
        HTMLBodyTemplate: htmlTemplate,
        ContextData: { Year: new Date().getFullYear() }
    }
};
Copy

How It Works

The client serializes EntityCommunicationParams and sends them to the MJAPI server via a GraphQL mutation. The server-side EntityCommunicationsEngine handles the actual view execution, template rendering, and message delivery through communication providers.

sequenceDiagram
    participant UI as Angular UI
    participant Client as EntityCommClient
    participant GQL as GraphQL Provider
    participant API as MJAPI
    participant Server as EntityCommEngine

    UI->>Client: RunEntityCommunication(params)
    Client->>Client: Serialize params
    Client->>GQL: GraphQL mutation
    GQL->>API: HTTP POST
    API->>Server: RunEntityCommunication(params)
    Server->>Server: Execute view, render templates, send
    Server-->>API: EntityCommunicationResult
    API-->>GQL: Response
    GQL-->>Client: Deserialized result
    Client-->>UI: EntityCommunicationResult
Copy

API Reference

Error Handling

const result = await client.RunEntityCommunication(params);

if (!result.Success) {
    console.error('Communication failed:', result.ErrorMessage);

    // Check individual message failures
    result.Results?.forEach(item => {
        if (!item.Message.Success) {
            console.error(`Failed for ${item.RecipientData.Email}:`, item.Message.Error);
        }
    });
}
Copy

Dependencies

Development

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