@memberjunction/communication-engine 5.34.1 → 5.36.0

package/dist/SendToAudience.d.ts

@@ -0,0 +1,75 @@
+import { UserInfo, type IMetadataProvider } from '@memberjunction/core';
+import { type Message, type MessageResult, type ProviderCredentialsBase } from '@memberjunction/communication-types';
+import type { AudienceSource } from '@memberjunction/lists-base';
+/**
+ * Reasons a record was excluded from a `SendToAudience` send. The set is
+ * intentionally small — anything more granular belongs in the underlying
+ * provider's bounce/return-path handling.
+ */
+export type AudienceSkipReason = 'MISSING_RECIPIENT_FIELD' | 'INVALID_RECIPIENT_FIELD';
+export interface AudienceSkipDetail {
+    RecordID: string;
+    Reason: AudienceSkipReason;
+    Message: string;
+}
+/**
+ * Result of a `SendToAudience` call. Mirrors the per-message
+ * `MessageResult[]` from `SendMessages` and additionally surfaces the
+ * audience-resolution metadata so the caller can render an "Audience
+ * Summary" panel (per mockup 21) without re-running the resolve.
+ */
+export interface SendToAudienceResult {
+    TotalAudienceSize: number;
+    WillReceiveCount: number;
+    SkippedCount: number;
+    Skipped: AudienceSkipDetail[];
+    Results: MessageResult[];
+    /** When `previewOnly` is true, `Results` is empty and this flag indicates we never dispatched. */
+    PreviewOnly: boolean;
+}
+/**
+ * Args for `SendToAudience`. Kept separate from `Message` because the
+ * audience layer adds its own dimensions (source, field mapping) that
+ * don't belong on the underlying transport-level `Message` type.
+ */
+export interface SendToAudienceParams {
+    /** Where the audience comes from — a List, View, or ad-hoc filter. */
+    Source: AudienceSource;
+    /**
+     * Name of the field on the audience entity that holds the recipient
+     * address (e.g. `'Email'` for Contacts, `'PhoneNumber'` for SMS). Records
+     * that don't have a non-empty value for this field are skipped and
+     * surfaced in `Skipped` so the UI can show them to the sender.
+     */
+    RecipientField: string;
+    /** Optional name of a "full name" field, used to populate `MessageRecipient.FullName`. */
+    FullNameField?: string;
+    /** Provider name (e.g. `'SendGrid'`). Same value the underlying `SendMessages` takes. */
+    ProviderName: string;
+    /** Provider message type name (e.g. `'SingleEmail'`). */
+    ProviderMessageTypeName: string;
+    /** Base message — `From`, subject/body, etc. `To` is overwritten per recipient. */
+    Message: Message;
+    /** Optional per-request credentials override. Forwarded to `SendMessages`. */
+    Credentials?: ProviderCredentialsBase;
+    /** When true, resolve + build recipient list but don't actually send. */
+    PreviewOnly?: boolean;
+    /** Context user — required, used for authorization on the underlying provider. */
+    ContextUser: UserInfo;
+    /** Optional multi-provider scope. Forwarded to the resolver + RunView. */
+    Provider?: IMetadataProvider;
+}
+/**
+ * Resolve an `AudienceSource` into concrete `MessageRecipient`s, then
+ * fan out via `CommunicationEngine.SendMessages`. The translation step
+ * is deliberately kept here (not on the engine) because it's
+ * audience-aware: it knows about entity primary keys, the recipient
+ * field mapping, and the skip-on-missing-field policy.
+ *
+ * Records whose `RecipientField` is missing or empty are skipped and
+ * returned in `Skipped` rather than failing the whole send — matches
+ * the plan's "skip records missing the mapped field with a warning"
+ * contract.
+ */
+export declare function SendToAudience(args: SendToAudienceParams): Promise<SendToAudienceResult>;
+//# sourceMappingURL=SendToAudience.d.ts.map

package/dist/SendToAudience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SendToAudience.d.ts","sourceRoot":"","sources":["../src/SendToAudience.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,QAAQ,EAAE,KAAK,iBAAiB,EAAY,MAAM,sBAAsB,CAAC;AACrG,OAAO,EAAoB,KAAK,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAEvI,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAIjE;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,GAAG,yBAAyB,CAAC;AAEvF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,kGAAkG;IAClG,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,MAAM,EAAE,cAAc,CAAC;IACvB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,uBAAuB,EAAE,MAAM,CAAC;IAChC,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kFAAkF;IAClF,WAAW,EAAE,QAAQ,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA4G9F"}

package/dist/SendToAudience.js

@@ -0,0 +1,121 @@
+import { Metadata, RunView, LogError } from '@memberjunction/core';
+import { MessageRecipient } from '@memberjunction/communication-types';
+import { AudienceResolver } from '@memberjunction/lists';
+import { CommunicationEngine } from './Engine.js';
+/**
+ * Resolve an `AudienceSource` into concrete `MessageRecipient`s, then
+ * fan out via `CommunicationEngine.SendMessages`. The translation step
+ * is deliberately kept here (not on the engine) because it's
+ * audience-aware: it knows about entity primary keys, the recipient
+ * field mapping, and the skip-on-missing-field policy.
+ *
+ * Records whose `RecipientField` is missing or empty are skipped and
+ * returned in `Skipped` rather than failing the whole send — matches
+ * the plan's "skip records missing the mapped field with a warning"
+ * contract.
+ */
+export async function SendToAudience(args) {
+    // 1. Resolve the audience.
+    const resolver = new AudienceResolver(args.ContextUser, args.Provider);
+    const resolved = await resolver.Resolve(args.Source);
+    const total = resolved.RecordIds.length;
+    if (total === 0) {
+        return emptyResult(args.PreviewOnly === true);
+    }
+    // 2. Bulk-load the underlying records so we can extract the recipient field.
+    const md = args.Provider ?? new Metadata();
+    const entityInfo = md.EntityByName(resolved.EntityName);
+    if (!entityInfo) {
+        throw new Error(`Entity '${resolved.EntityName}' not found in metadata`);
+    }
+    const pkFields = entityInfo.PrimaryKeys.map((pk) => pk.Name);
+    const fields = unique([...pkFields, args.RecipientField, ...(args.FullNameField ? [args.FullNameField] : [])]);
+    const rv = args.Provider ? RunView.FromMetadataProvider(args.Provider) : new RunView();
+    // For single-PK entities the resolved IDs are raw values. Composite
+    // PKs serialize to `Field1|Value1||Field2|Value2`; we don't support
+    // composite-PK recipient lookups here yet — surface clearly and skip.
+    if (pkFields.length !== 1) {
+        LogError(`SendToAudience: composite-PK entities ('${resolved.EntityName}', PK=${pkFields.join('+')}) are not yet supported. ` +
+            'All records will be reported as skipped.');
+        return {
+            TotalAudienceSize: total,
+            WillReceiveCount: 0,
+            SkippedCount: total,
+            Skipped: resolved.RecordIds.map((id) => ({
+                RecordID: id,
+                Reason: 'INVALID_RECIPIENT_FIELD',
+                Message: 'Composite-PK entities are not yet supported for SendToAudience',
+            })),
+            Results: [],
+            PreviewOnly: args.PreviewOnly === true,
+        };
+    }
+    const pk = pkFields[0];
+    const idList = resolved.RecordIds.map((id) => `'${id.replace(/'/g, "''")}'`).join(',');
+    const loadResult = await rv.RunView({
+        EntityName: resolved.EntityName,
+        ExtraFilter: `${pk} IN (${idList})`,
+        Fields: fields,
+        ResultType: 'simple',
+    }, args.ContextUser);
+    if (!loadResult.Success) {
+        throw new Error(`Failed to load audience records: ${loadResult.ErrorMessage}`);
+    }
+    // 3. Build recipients + collect skip reasons.
+    const recipients = [];
+    const skipped = [];
+    for (const row of loadResult.Results ?? []) {
+        const recordId = String(row[pk]);
+        const to = row[args.RecipientField];
+        const toStr = to == null ? '' : String(to).trim();
+        if (toStr.length === 0) {
+            skipped.push({
+                RecordID: recordId,
+                Reason: 'MISSING_RECIPIENT_FIELD',
+                Message: `Record has no ${args.RecipientField} value`,
+            });
+            continue;
+        }
+        const recipient = new MessageRecipient();
+        recipient.To = toStr;
+        if (args.FullNameField && row[args.FullNameField] != null) {
+            recipient.FullName = String(row[args.FullNameField]);
+        }
+        recipient.ContextData = row;
+        recipients.push(recipient);
+    }
+    // 4. Either preview-only return, or fan out via the engine.
+    if (args.PreviewOnly) {
+        return {
+            TotalAudienceSize: total,
+            WillReceiveCount: recipients.length,
+            SkippedCount: skipped.length,
+            Skipped: skipped,
+            Results: [],
+            PreviewOnly: true,
+        };
+    }
+    const results = await CommunicationEngine.Instance.SendMessages(args.ProviderName, args.ProviderMessageTypeName, args.Message, recipients, false, args.Credentials);
+    return {
+        TotalAudienceSize: total,
+        WillReceiveCount: recipients.length,
+        SkippedCount: skipped.length,
+        Skipped: skipped,
+        Results: results,
+        PreviewOnly: false,
+    };
+}
+function emptyResult(previewOnly) {
+    return {
+        TotalAudienceSize: 0,
+        WillReceiveCount: 0,
+        SkippedCount: 0,
+        Skipped: [],
+        Results: [],
+        PreviewOnly: previewOnly,
+    };
+}
+function unique(items) {
+    return Array.from(new Set(items));
+}
+//# sourceMappingURL=SendToAudience.js.map

package/dist/SendToAudience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SendToAudience.js","sourceRoot":"","sources":["../src/SendToAudience.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './Engine.js';
 export * from './BaseProvider.js';
+export * from './SendToAudience.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 // PUBLIC API SURFACE AREA
 export * from './Engine.js';
 export * from './BaseProvider.js';
+export * from './SendToAudience.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/communication-engine",
   "type": "module",
-  "version": "5.34.1",
+  "version": "5.36.0",
   "description": "MemberJunction: Core Communication Framework Library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,8 @@
   "scripts": {
     "start": "ts-node-dev src/index.ts",
     "build": "tsc && tsc-alias -f",
-    "test": "echo \"No tests configured yet\""
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "author": "MemberJunction.com",
   "license": "ISC",
@@ -20,11 +21,13 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@memberjunction/global": "5.34.1",
-    "@memberjunction/core": "5.34.1",
-    "@memberjunction/templates": "5.34.1",
-    "@memberjunction/core-entities": "5.34.1",
-    "@memberjunction/communication-types": "5.34.1",
+    "@memberjunction/global": "5.36.0",
+    "@memberjunction/core": "5.36.0",
+    "@memberjunction/templates": "5.36.0",
+    "@memberjunction/core-entities": "5.36.0",
+    "@memberjunction/communication-types": "5.36.0",
+    "@memberjunction/lists": "5.36.0",
+    "@memberjunction/lists-base": "5.36.0",
     "rxjs": "^7.8.2"
   },
   "repository": {