@memberjunction/entity-communications-client 4.0.0 → 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +126 -185
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,10 +1,40 @@
1
1
  # @memberjunction/entity-communications-client
2
2
 
3
- A client library for interacting with the MemberJunction Entity Communications Engine. This package provides a GraphQL-based client implementation for executing communication requests against views of entity records.
4
-
5
- ## Overview
6
-
7
- The Entity Communications Client enables you to send templated messages (email, SMS, etc.) to recipients based on entity data views. It supports various communication providers and message types while leveraging MemberJunction's templating system for dynamic content generation.
3
+ 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.
4
+
5
+ ## Architecture
6
+
7
+ ```mermaid
8
+ graph TD
9
+ subgraph client["@memberjunction/entity-comm-client"]
10
+ ECC["EntityCommunicationsEngineClient"]
11
+ end
12
+
13
+ subgraph base["@memberjunction/entity-communications-base"]
14
+ ECB["EntityCommunicationsEngineBase"]
15
+ PARAMS["EntityCommunicationParams"]
16
+ RESULT["EntityCommunicationResult"]
17
+ end
18
+
19
+ subgraph graphql["@memberjunction/graphql-dataprovider"]
20
+ GQL["GraphQLDataProvider"]
21
+ end
22
+
23
+ subgraph api["MJAPI Server"]
24
+ RESOLVER["GraphQL Resolver"]
25
+ SERVER["EntityCommunicationsEngine\n(Server)"]
26
+ end
27
+
28
+ ECB --> ECC
29
+ ECC -->|mutation| GQL
30
+ GQL -->|HTTP| RESOLVER
31
+ RESOLVER --> SERVER
32
+
33
+ style client fill:#b8762f,stroke:#8a5722,color:#fff
34
+ style base fill:#2d6a9f,stroke:#1a4971,color:#fff
35
+ style graphql fill:#7c5295,stroke:#563a6b,color:#fff
36
+ style api fill:#2d8659,stroke:#1a5c3a,color:#fff
37
+ ```
8
38
 
9
39
  ## Installation
10
40
 
@@ -12,15 +42,6 @@ The Entity Communications Client enables you to send templated messages (email,
12
42
  npm install @memberjunction/entity-communications-client
13
43
  ```
14
44
 
15
- ## Dependencies
16
-
17
- This package depends on:
18
- - `@memberjunction/global` - Core MemberJunction utilities
19
- - `@memberjunction/core` - Core MemberJunction functionality
20
- - `@memberjunction/core-entities` - Entity definitions
21
- - `@memberjunction/entity-communications-base` - Base classes for entity communications
22
- - `@memberjunction/graphql-dataprovider` - GraphQL data provider for API calls
23
-
24
45
  ## Usage
25
46
 
26
47
  ### Basic Example
@@ -29,219 +50,139 @@ This package depends on:
29
50
  import { EntityCommunicationsEngineClient } from '@memberjunction/entity-communications-client';
30
51
  import { EntityCommunicationParams } from '@memberjunction/entity-communications-base';
31
52
 
32
- // Initialize the client
33
53
  const client = new EntityCommunicationsEngineClient();
34
-
35
- // Configure the client (required before first use)
36
54
  await client.Config();
37
55
 
38
- // Set up communication parameters
39
56
  const params: EntityCommunicationParams = {
40
- EntityID: '123', // ID of the entity to communicate about
41
- RunViewParams: {
42
- ViewID: '456', // ID of the view that defines recipients
43
- ExtraFilter: 'IsActive = 1', // Additional filtering
44
- OrderBy: 'LastName ASC',
45
- MaxRows: 100
46
- },
47
- ProviderName: 'SendGrid', // Communication provider to use
48
- ProviderMessageTypeName: 'Email', // Type of message
49
- Message: {
50
- From: 'noreply@example.com',
51
- To: '{{Email}}', // Can use template variables
52
- Subject: 'Important Update',
53
- Body: 'Hello {{FirstName}}, we have an update for you.',
54
- ContextData: {
55
- // Additional data for template rendering
56
- CompanyName: 'Acme Corp',
57
- UpdateDate: new Date()
58
- }
59
- },
60
- PreviewOnly: false, // Set to true to preview without sending
61
- IncludeProcessedMessages: true // Include processed message content in results
57
+ EntityID: '123',
58
+ RunViewParams: {
59
+ ViewID: '456',
60
+ ExtraFilter: 'IsActive = 1',
61
+ MaxRows: 100
62
+ },
63
+ ProviderName: 'SendGrid',
64
+ ProviderMessageTypeName: 'Email',
65
+ Message: {
66
+ From: 'noreply@example.com',
67
+ To: '{{Email}}',
68
+ Subject: 'Important Update',
69
+ Body: 'Hello {{FirstName}}, we have an update for you.',
70
+ ContextData: {
71
+ CompanyName: 'Acme Corp'
72
+ }
73
+ },
74
+ PreviewOnly: false,
75
+ IncludeProcessedMessages: true
62
76
  };
63
77
 
64
- // Execute the communication
65
78
  const result = await client.RunEntityCommunication(params);
66
79
 
67
80
  if (result.Success) {
68
- console.log(`Successfully sent ${result.Results.length} messages`);
69
-
70
- // Process results
71
- result.Results.forEach(item => {
72
- console.log(`Sent to: ${item.RecipientData.Email}`);
73
- console.log(`Message: ${item.Message.ProcessedBody}`);
74
- });
81
+ console.log(`Sent ${result.Results.length} messages`);
75
82
  } else {
76
- console.error(`Communication failed: ${result.ErrorMessage}`);
83
+ console.error(`Failed: ${result.ErrorMessage}`);
77
84
  }
78
85
  ```
79
86
 
80
- ### Using Templates
81
-
82
- ```typescript
83
- import { TemplateEntityExtended } from '@memberjunction/templates-base-types';
84
-
85
- // Load your template (example)
86
- const template = await getTemplate('Welcome Email'); // Your template loading logic
87
-
88
- const params: EntityCommunicationParams = {
89
- EntityID: '123',
90
- RunViewParams: {
91
- ViewID: '456',
92
- // View should return records with fields matching template variables
93
- },
94
- ProviderName: 'SendGrid',
95
- ProviderMessageTypeName: 'Email',
96
- Message: {
97
- From: 'welcome@example.com',
98
- To: '{{Email}}',
99
- SubjectTemplate: subjectTemplate, // Template for subject line
100
- BodyTemplate: bodyTemplate, // Template for plain text body
101
- HTMLBodyTemplate: htmlTemplate, // Template for HTML body
102
- ContextData: {
103
- // Global context data available to all recipients
104
- Year: new Date().getFullYear()
105
- }
106
- }
107
- };
108
-
109
- const result = await client.RunEntityCommunication(params);
110
- ```
111
-
112
87
  ### Preview Mode
113
88
 
114
- To test your communications without actually sending messages:
89
+ Test communications without actually sending messages:
115
90
 
116
91
  ```typescript
117
92
  const params: EntityCommunicationParams = {
118
- // ... other parameters ...
119
- PreviewOnly: true, // Enable preview mode
120
- IncludeProcessedMessages: true // Get the processed message content
93
+ // ...same parameters...
94
+ PreviewOnly: true,
95
+ IncludeProcessedMessages: true
121
96
  };
122
97
 
123
98
  const result = await client.RunEntityCommunication(params);
124
-
125
- // Review what would be sent
126
99
  result.Results.forEach(item => {
127
- console.log('Would send to:', item.RecipientData);
128
- console.log('Subject:', item.Message.ProcessedSubject);
129
- console.log('Body:', item.Message.ProcessedBody);
100
+ console.log('Would send to:', item.RecipientData);
101
+ console.log('Subject:', item.Message.ProcessedSubject);
102
+ console.log('Body:', item.Message.ProcessedBody);
130
103
  });
131
104
  ```
132
105
 
133
- ## API Reference
134
-
135
- ### EntityCommunicationsEngineClient
136
-
137
- The main client class for entity communications.
138
-
139
- #### Methods
140
-
141
- ##### `Config(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<void>`
142
-
143
- Configures the client by loading necessary metadata. Must be called before using other methods.
144
-
145
- - `forceRefresh` - Force reload of metadata cache
146
- - `contextUser` - User context for permissions
147
- - `provider` - Custom metadata provider
148
-
149
- ##### `RunEntityCommunication(params: EntityCommunicationParams): Promise<EntityCommunicationResult>`
150
-
151
- Executes a communication request against entity records.
152
-
153
- - `params` - Communication parameters (see below)
154
- - Returns: Promise resolving to communication results
155
-
156
- ### Types
157
-
158
- #### EntityCommunicationParams
159
-
160
- ```typescript
161
- interface EntityCommunicationParams {
162
- EntityID: string; // ID of the entity to communicate about
163
- RunViewParams: RunViewParams; // View parameters to select recipients
164
- ProviderName: string; // Name of communication provider
165
- ProviderMessageTypeName: string; // Type of message for the provider
166
- Message: Message; // Message content and templates
167
- PreviewOnly?: boolean; // If true, preview without sending
168
- IncludeProcessedMessages?: boolean; // Include processed content in results
169
- }
170
- ```
171
-
172
- #### Message
106
+ ### Using Templates
173
107
 
174
108
  ```typescript
175
- interface Message {
176
- MessageType?: CommunicationProviderMessageTypeEntity;
177
- From?: string; // Sender address
178
- To?: string; // Recipient address (can use templates)
179
- Body?: string; // Plain text body
180
- BodyTemplate?: TemplateEntityExtended;
181
- HTMLBody?: string; // HTML body
182
- HTMLBodyTemplate?: TemplateEntityExtended;
183
- Subject?: string; // Subject line
184
- SubjectTemplate?: TemplateEntityExtended;
185
- ContextData?: any; // Additional template context
186
- }
109
+ const params: EntityCommunicationParams = {
110
+ EntityID: '123',
111
+ RunViewParams: { ViewID: '456' },
112
+ ProviderName: 'SendGrid',
113
+ ProviderMessageTypeName: 'Email',
114
+ Message: {
115
+ From: 'welcome@example.com',
116
+ To: '{{Email}}',
117
+ SubjectTemplate: subjectTemplate,
118
+ BodyTemplate: bodyTemplate,
119
+ HTMLBodyTemplate: htmlTemplate,
120
+ ContextData: { Year: new Date().getFullYear() }
121
+ }
122
+ };
187
123
  ```
188
124
 
189
- #### EntityCommunicationResult
190
-
191
- ```typescript
192
- interface EntityCommunicationResult {
193
- Success: boolean; // Whether communication succeeded
194
- ErrorMessage?: string; // Error details if failed
195
- Results?: EntityCommunicationResultItem[]; // Individual message results
196
- }
197
-
198
- interface EntityCommunicationResultItem {
199
- RecipientData: any; // Data for this recipient
200
- Message: ProcessedMessage; // The processed message
201
- }
125
+ ## How It Works
126
+
127
+ 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.
128
+
129
+ ```mermaid
130
+ sequenceDiagram
131
+ participant UI as Angular UI
132
+ participant Client as EntityCommClient
133
+ participant GQL as GraphQL Provider
134
+ participant API as MJAPI
135
+ participant Server as EntityCommEngine
136
+
137
+ UI->>Client: RunEntityCommunication(params)
138
+ Client->>Client: Serialize params
139
+ Client->>GQL: GraphQL mutation
140
+ GQL->>API: HTTP POST
141
+ API->>Server: RunEntityCommunication(params)
142
+ Server->>Server: Execute view, render templates, send
143
+ Server-->>API: EntityCommunicationResult
144
+ API-->>GQL: Response
145
+ GQL-->>Client: Deserialized result
146
+ Client-->>UI: EntityCommunicationResult
202
147
  ```
203
148
 
204
- ## Integration with MemberJunction
205
-
206
- This client integrates seamlessly with other MemberJunction packages:
207
-
208
- - **Templates**: Use `@memberjunction/templates-base-types` for dynamic content
209
- - **Entities**: Works with any entity defined in your MemberJunction schema
210
- - **Views**: Leverages MemberJunction views to select communication recipients
211
- - **Providers**: Supports all registered communication providers (SendGrid, Twilio, MS Graph, etc.)
212
-
213
- ## Configuration
149
+ ## API Reference
214
150
 
215
- The client uses GraphQL to communicate with the MemberJunction API. Ensure your GraphQL endpoint is properly configured through the `GraphQLDataProvider`.
151
+ | Method | Description |
152
+ |--------|-------------|
153
+ | `Config(forceRefresh?, contextUser?, provider?)` | Load metadata (required before first use) |
154
+ | `RunEntityCommunication(params)` | Execute entity communication via GraphQL |
216
155
 
217
156
  ## Error Handling
218
157
 
219
- The client provides detailed error information:
220
-
221
158
  ```typescript
222
159
  const result = await client.RunEntityCommunication(params);
223
160
 
224
161
  if (!result.Success) {
225
- console.error('Communication failed:', result.ErrorMessage);
226
-
227
- // Check individual message failures
228
- result.Results?.forEach(item => {
229
- if (!item.Message.Success) {
230
- console.error(`Failed for ${item.RecipientData.Email}:`, item.Message.Error);
231
- }
232
- });
162
+ console.error('Communication failed:', result.ErrorMessage);
163
+
164
+ // Check individual message failures
165
+ result.Results?.forEach(item => {
166
+ if (!item.Message.Success) {
167
+ console.error(`Failed for ${item.RecipientData.Email}:`, item.Message.Error);
168
+ }
169
+ });
233
170
  }
234
171
  ```
235
172
 
236
- ## Best Practices
173
+ ## Dependencies
237
174
 
238
- 1. **Always call `Config()` before first use** - This loads necessary metadata
239
- 2. **Use preview mode for testing** - Set `PreviewOnly: true` to test without sending
240
- 3. **Handle errors gracefully** - Check both overall and individual message success
241
- 4. **Use templates for consistency** - Leverage MemberJunction's template system
242
- 5. **Filter recipients carefully** - Use view filters to target the right audience
243
- 6. **Include context data** - Provide all necessary data for template rendering
175
+ | Package | Purpose |
176
+ |---------|---------|
177
+ | `@memberjunction/entity-communications-base` | Shared types and base engine |
178
+ | `@memberjunction/graphql-dataprovider` | GraphQL client for API communication |
179
+ | `@memberjunction/core` | Core framework utilities |
180
+ | `@memberjunction/core-entities` | Entity type definitions |
181
+ | `@memberjunction/global` | Class registration |
244
182
 
245
- ## License
183
+ ## Development
246
184
 
247
- ISC
185
+ ```bash
186
+ npm run build # Compile TypeScript
187
+ npm start # Watch mode
188
+ ```
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@memberjunction/entity-communications-client",
3
3
  "type": "module",
4
- "version": "4.0.0",
4
+ "version": "4.2.0",
5
5
  "description": "MemberJunction: Client for interacting with Entity Communications Engine",
6
6
  "main": "dist/index.js",
7
7
  "types": "dist/index.d.ts",
@@ -20,12 +20,12 @@
20
20
  "typescript": "^5.9.3"
21
21
  },
22
22
  "dependencies": {
23
- "@memberjunction/communication-types": "4.0.0",
24
- "@memberjunction/core": "4.0.0",
25
- "@memberjunction/core-entities": "4.0.0",
26
- "@memberjunction/entity-communications-base": "4.0.0",
27
- "@memberjunction/global": "4.0.0",
28
- "@memberjunction/graphql-dataprovider": "4.0.0"
23
+ "@memberjunction/communication-types": "4.2.0",
24
+ "@memberjunction/core": "4.2.0",
25
+ "@memberjunction/core-entities": "4.2.0",
26
+ "@memberjunction/entity-communications-base": "4.2.0",
27
+ "@memberjunction/global": "4.2.0",
28
+ "@memberjunction/graphql-dataprovider": "4.2.0"
29
29
  },
30
30
  "repository": {
31
31
  "type": "git",