@terreno/comms 57.0.0-beta.1 → 57.1.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.
package/src/index.ts CHANGED
@@ -10,6 +10,7 @@ export {CommsService} from "./commsService";
10
10
  export {CommsMessage} from "./models/commsMessage";
11
11
  export {PushToken} from "./models/pushToken";
12
12
  export type {
13
+ CommsMessageAttempt,
13
14
  CommsMessageDocument,
14
15
  CommsMessageMethods,
15
16
  CommsMessageModel,
@@ -26,13 +27,18 @@ export type {
26
27
  export type {MessageTemplate, RenderTemplateOptions} from "./templates";
27
28
  export {renderTemplate} from "./templates";
28
29
  export type {
30
+ BeforeSendResult,
29
31
  CheckVerificationOptions,
30
32
  CommsChannel,
33
+ CommsErrorClass,
34
+ CommsHookContext,
35
+ CommsHookMessage,
31
36
  CommsMessageStatus,
32
37
  CommsOptions,
33
38
  DeliveryEvent,
34
39
  MailMessage,
35
40
  MailProvider,
41
+ OptOutEvent,
36
42
  PushMessage,
37
43
  PushProvider,
38
44
  SendPushToUserMessage,
package/src/modelTypes.ts CHANGED
@@ -1,35 +1,64 @@
1
1
  import type {FindExactlyOnePlugin, FindOneOrNonePlugin, HasUpsert} from "@terreno/api";
2
2
  import type mongoose from "mongoose";
3
3
 
4
- import type {CommsChannel, CommsMessageStatus} from "./types";
4
+ import type {CommsChannel, CommsErrorClass, CommsMessageStatus} from "./types";
5
5
 
6
6
  export type CommsMessageMethods = Record<never, never>;
7
7
 
8
+ export interface CommsMessageAttempt {
9
+ at: Date;
10
+ error?: string;
11
+ errorClass?: CommsErrorClass;
12
+ errorCode?: string;
13
+ provider: string;
14
+ providerMessageId?: string;
15
+ }
16
+
8
17
  export interface CommsMessageDocument
9
18
  extends mongoose.Document<mongoose.Types.ObjectId>,
10
19
  CommsMessageMethods {
20
+ attemptCount: number;
21
+ attempts: CommsMessageAttempt[];
11
22
  channel: CommsChannel;
12
23
  created: Date;
13
24
  deleted: boolean;
14
25
  error?: string;
26
+ errorClass?: CommsErrorClass;
27
+ errorCode?: string;
28
+ lastAttemptAt?: Date;
15
29
  metadata?: Record<string, unknown>;
30
+ payload?: unknown;
31
+ payloadExpiresAt?: Date;
16
32
  provider: string;
17
33
  providerMessageId?: string;
34
+ retriedById?: mongoose.Types.ObjectId;
35
+ retriedFromId?: mongoose.Types.ObjectId;
18
36
  status: CommsMessageStatus;
19
37
  subject?: string;
38
+ templateId?: string;
20
39
  to: string;
21
40
  updated: Date;
22
41
  userId?: mongoose.Types.ObjectId;
23
42
  }
24
43
 
25
44
  export interface LogSendParams {
45
+ attemptCount?: number;
46
+ attempts?: CommsMessageAttempt[];
26
47
  channel: CommsChannel;
27
48
  error?: string;
49
+ errorClass?: CommsErrorClass;
50
+ errorCode?: string;
51
+ lastAttemptAt?: Date;
28
52
  metadata?: Record<string, unknown>;
53
+ payload?: unknown;
54
+ payloadExpiresAt?: Date;
29
55
  provider: string;
30
56
  providerMessageId?: string;
57
+ retriedById?: mongoose.Types.ObjectId | string;
58
+ retriedFromId?: mongoose.Types.ObjectId | string;
31
59
  status: CommsMessageStatus;
32
60
  subject?: string;
61
+ templateId?: string;
33
62
  to: string;
34
63
  userId?: mongoose.Types.ObjectId | string;
35
64
  }
@@ -37,6 +66,19 @@ export interface LogSendParams {
37
66
  export interface CommsMessageStatics
38
67
  extends FindExactlyOnePlugin<CommsMessageDocument>,
39
68
  FindOneOrNonePlugin<CommsMessageDocument> {
69
+ appendAttempt(params: {
70
+ error?: string;
71
+ errorClass?: CommsErrorClass;
72
+ errorCode?: string;
73
+ id: mongoose.Types.ObjectId | string;
74
+ metadata?: Record<string, unknown>;
75
+ payload?: unknown;
76
+ payloadExpiresAt?: Date;
77
+ providerMessageId?: string;
78
+ status: CommsMessageStatus;
79
+ attempt: CommsMessageAttempt;
80
+ }): Promise<CommsMessageDocument | null>;
81
+ clearExpiredPayloads(): Promise<number>;
40
82
  logSend(params: LogSendParams): Promise<CommsMessageDocument | null>;
41
83
  }
42
84
 
@@ -1,17 +1,28 @@
1
1
  import {beforeEach, describe, it} from "bun:test";
2
2
  import {setupDb} from "@terreno/api/testing";
3
3
  import {assert} from "chai";
4
+ import {DateTime} from "luxon";
4
5
 
5
6
  import {CommsMessage} from "./commsMessage";
6
7
 
7
8
  const COMMS_MESSAGE_FIELDS = [
9
+ "attemptCount",
10
+ "attempts",
8
11
  "channel",
9
12
  "error",
13
+ "errorClass",
14
+ "errorCode",
15
+ "lastAttemptAt",
10
16
  "metadata",
17
+ "payload",
18
+ "payloadExpiresAt",
11
19
  "provider",
12
20
  "providerMessageId",
21
+ "retriedById",
22
+ "retriedFromId",
13
23
  "status",
14
24
  "subject",
25
+ "templateId",
15
26
  "to",
16
27
  "userId",
17
28
  ] as const;
@@ -50,4 +61,49 @@ describe("CommsMessage", () => {
50
61
  assert.isNull(result);
51
62
  assert.equal(await CommsMessage.countDocuments(), 0);
52
63
  });
64
+
65
+ it("clears expired payloads without deleting the log row", async (): Promise<void> => {
66
+ const message = await CommsMessage.logSend({
67
+ attemptCount: 1,
68
+ attempts: [{at: DateTime.utc().toJSDate(), provider: "console"}],
69
+ channel: "mail",
70
+ payload: {subject: "Welcome"},
71
+ payloadExpiresAt: DateTime.utc().minus({days: 1}).toJSDate(),
72
+ provider: "console",
73
+ status: "sent",
74
+ to: "person@example.com",
75
+ });
76
+ assert.isNotNull(message);
77
+ const refreshed = await CommsMessage.findExactlyOne({_id: message?._id});
78
+ assert.isUndefined(refreshed.payload);
79
+ assert.isUndefined(refreshed.payloadExpiresAt);
80
+ assert.equal(refreshed.status, "sent");
81
+ });
82
+
83
+ it("appends a second attempt onto the same row", async (): Promise<void> => {
84
+ const created = await CommsMessage.logSend({
85
+ attemptCount: 1,
86
+ attempts: [{at: DateTime.utc().toJSDate(), errorCode: "429", provider: "console"}],
87
+ channel: "mail",
88
+ errorClass: "transient",
89
+ errorCode: "429",
90
+ provider: "console",
91
+ status: "failed",
92
+ to: "person@example.com",
93
+ });
94
+ assert.isNotNull(created);
95
+ const appended = await CommsMessage.appendAttempt({
96
+ attempt: {
97
+ at: DateTime.utc().toJSDate(),
98
+ provider: "console",
99
+ providerMessageId: "mail-2",
100
+ },
101
+ id: String(created?._id),
102
+ providerMessageId: "mail-2",
103
+ status: "sent",
104
+ });
105
+ assert.equal(appended?.attemptCount, 2);
106
+ assert.equal(await CommsMessage.countDocuments(), 1);
107
+ assert.equal(appended?.status, "sent");
108
+ });
53
109
  });
@@ -5,6 +5,7 @@ import {
5
5
  isDeletedPlugin,
6
6
  logger,
7
7
  } from "@terreno/api";
8
+ import {DateTime} from "luxon";
8
9
  import mongoose from "mongoose";
9
10
 
10
11
  import type {
@@ -19,6 +20,47 @@ const commsMessageSchema: CommsMessageSchema = new mongoose.Schema<
19
20
  CommsMessageModel
20
21
  >(
21
22
  {
23
+ attemptCount: {
24
+ default: 0,
25
+ description: "Number of facade send attempts recorded on this row",
26
+ type: Number,
27
+ },
28
+ attempts: {
29
+ default: [],
30
+ description: "Per-attempt provider results including the inline retry",
31
+ type: [
32
+ {
33
+ _id: false,
34
+ at: {
35
+ description: "When this send attempt ran",
36
+ required: true,
37
+ type: Date,
38
+ },
39
+ error: {
40
+ description: "Provider error message for this attempt",
41
+ type: String,
42
+ },
43
+ errorClass: {
44
+ description: "Classified failure category for this attempt",
45
+ enum: ["config", "permanent", "transient"],
46
+ type: String,
47
+ },
48
+ errorCode: {
49
+ description: "Provider-native error code for this attempt",
50
+ type: String,
51
+ },
52
+ provider: {
53
+ description: "Provider identifier used for this attempt",
54
+ required: true,
55
+ type: String,
56
+ },
57
+ providerMessageId: {
58
+ description: "Provider-assigned identifier returned by this attempt",
59
+ type: String,
60
+ },
61
+ },
62
+ ],
63
+ },
22
64
  channel: {
23
65
  description: "Communication channel used for the send attempt",
24
66
  enum: ["mail", "push", "sms", "verification"],
@@ -29,10 +71,33 @@ const commsMessageSchema: CommsMessageSchema = new mongoose.Schema<
29
71
  description: "Provider error returned for a failed send attempt",
30
72
  type: String,
31
73
  },
74
+ errorClass: {
75
+ description: "Classified failure category used for retry eligibility",
76
+ enum: ["config", "permanent", "transient"],
77
+ type: String,
78
+ },
79
+ errorCode: {
80
+ description: "Provider-native error code for a failed send attempt",
81
+ index: true,
82
+ type: String,
83
+ },
84
+ lastAttemptAt: {
85
+ description: "Timestamp of the most recent send attempt",
86
+ type: Date,
87
+ },
32
88
  metadata: {
33
89
  description: "Additional metadata associated with the send attempt",
34
90
  type: mongoose.Schema.Types.Mixed,
35
91
  },
92
+ payload: {
93
+ description: "Redacted rendered message retained for admin retry",
94
+ type: mongoose.Schema.Types.Mixed,
95
+ },
96
+ payloadExpiresAt: {
97
+ description: "When the retained payload should be cleared",
98
+ index: true,
99
+ type: Date,
100
+ },
36
101
  provider: {
37
102
  description: "Identifier of the provider handling the send attempt",
38
103
  minlength: 1,
@@ -44,9 +109,19 @@ const commsMessageSchema: CommsMessageSchema = new mongoose.Schema<
44
109
  index: true,
45
110
  type: String,
46
111
  },
112
+ retriedById: {
113
+ description: "Admin-dashboard retry that was created from this row",
114
+ ref: "CommsMessage",
115
+ type: mongoose.Schema.Types.ObjectId,
116
+ },
117
+ retriedFromId: {
118
+ description: "Original CommsMessage this admin retry was created from",
119
+ ref: "CommsMessage",
120
+ type: mongoose.Schema.Types.ObjectId,
121
+ },
47
122
  status: {
48
123
  description: "Current delivery status of the communication",
49
- enum: ["bounced", "delivered", "failed", "sent"],
124
+ enum: ["bounced", "cancelled", "delivered", "failed", "sent"],
50
125
  required: true,
51
126
  type: String,
52
127
  },
@@ -54,6 +129,10 @@ const commsMessageSchema: CommsMessageSchema = new mongoose.Schema<
54
129
  description: "Mail subject when the communication channel is mail",
55
130
  type: String,
56
131
  },
132
+ templateId: {
133
+ description: "Provider or app template identifier used to render the message",
134
+ type: String,
135
+ },
57
136
  to: {
58
137
  description: "Recipient identifier for the communication",
59
138
  required: true,
@@ -69,16 +148,85 @@ const commsMessageSchema: CommsMessageSchema = new mongoose.Schema<
69
148
  );
70
149
 
71
150
  commsMessageSchema.statics = {
151
+ async appendAttempt(
152
+ this: CommsMessageModel,
153
+ params: {
154
+ attempt: CommsMessageDocument["attempts"][number];
155
+ error?: string;
156
+ errorClass?: CommsMessageDocument["errorClass"];
157
+ errorCode?: string;
158
+ id: mongoose.Types.ObjectId | string;
159
+ metadata?: Record<string, unknown>;
160
+ payload?: unknown;
161
+ payloadExpiresAt?: Date;
162
+ providerMessageId?: string;
163
+ status: CommsMessageDocument["status"];
164
+ }
165
+ ): Promise<CommsMessageDocument | null> {
166
+ let document: CommsMessageDocument | null;
167
+ try {
168
+ document = await this.findOneOrNone({_id: params.id});
169
+ if (!document) {
170
+ return null;
171
+ }
172
+ document.attempts = [...document.attempts, params.attempt];
173
+ document.attemptCount = document.attempts.length;
174
+ document.error = params.error;
175
+ document.errorClass = params.errorClass;
176
+ document.errorCode = params.errorCode;
177
+ document.lastAttemptAt = params.attempt.at;
178
+ document.providerMessageId = params.providerMessageId;
179
+ document.status = params.status;
180
+ if (params.metadata) {
181
+ document.metadata = {...document.metadata, ...params.metadata};
182
+ document.markModified("metadata");
183
+ }
184
+ if (params.payload !== undefined) {
185
+ document.payload = params.payload;
186
+ document.payloadExpiresAt = params.payloadExpiresAt;
187
+ }
188
+ await document.save();
189
+ } catch {
190
+ logger.warn("[comms] Failed to append communication attempt");
191
+ return null;
192
+ }
193
+ await this.clearExpiredPayloads();
194
+ return document;
195
+ },
196
+ async clearExpiredPayloads(this: CommsMessageModel): Promise<number> {
197
+ try {
198
+ const expired = await this.find({
199
+ payload: {$exists: true},
200
+ payloadExpiresAt: {$lte: DateTime.utc().toJSDate()},
201
+ })
202
+ .select("_id")
203
+ .limit(50);
204
+ if (expired.length === 0) {
205
+ return 0;
206
+ }
207
+ const result = await this.updateMany(
208
+ {_id: {$in: expired.map((row) => row._id)}},
209
+ {$unset: {payload: 1, payloadExpiresAt: 1}}
210
+ );
211
+ return result.modifiedCount;
212
+ } catch (error: unknown) {
213
+ logger.warn(`[comms] Failed to clear expired payloads: ${String(error)}`);
214
+ return 0;
215
+ }
216
+ },
72
217
  async logSend(
73
218
  this: CommsMessageModel,
74
219
  params: LogSendParams
75
220
  ): Promise<CommsMessageDocument | null> {
221
+ let created: CommsMessageDocument;
76
222
  try {
77
- return await this.create(params);
223
+ created = await this.create(params);
78
224
  } catch {
79
225
  logger.warn("[comms] Failed to record communication send");
80
226
  return null;
81
227
  }
228
+ await this.clearExpiredPayloads();
229
+ return created;
82
230
  },
83
231
  };
84
232
 
@@ -11,4 +11,5 @@ registerSimpleMongoPreload({
11
11
 
12
12
  beforeEach((): void => {
13
13
  process.env.NODE_ENV = "test";
14
+ Reflect.deleteProperty(process.env, "SENDGRID_API_KEY");
14
15
  });
@@ -0,0 +1,56 @@
1
+ import {describe, it} from "bun:test";
2
+ import {assert} from "chai";
3
+
4
+ import type {
5
+ CommsHookContext,
6
+ CommsMessageStatus,
7
+ CommsOptions,
8
+ DeliveryEvent,
9
+ OptOutEvent,
10
+ SendResult,
11
+ } from "./types";
12
+
13
+ const cancelled: CommsMessageStatus = "cancelled";
14
+
15
+ const hookContext: CommsHookContext = {
16
+ attempt: 2,
17
+ channel: "mail",
18
+ isRetry: true,
19
+ message: {subject: "Hi", to: "person@example.com"},
20
+ messageId: "abc",
21
+ provider: "console",
22
+ userId: "user-1",
23
+ };
24
+
25
+ const optOut: OptOutEvent = {
26
+ channel: "mail",
27
+ provider: "sendgrid",
28
+ reason: "unsubscribe",
29
+ to: "person@example.com",
30
+ };
31
+
32
+ const delivery: DeliveryEvent = {
33
+ channel: "mail",
34
+ errorClass: "permanent",
35
+ errorCode: "bounce",
36
+ providerMessageId: "sg-1",
37
+ status: "bounced",
38
+ };
39
+
40
+ const onRetry: NonNullable<CommsOptions["onRetry"]> = async (
41
+ context: CommsHookContext,
42
+ result: SendResult
43
+ ): Promise<void> => {
44
+ assert.equal(context.attempt, 2);
45
+ assert.equal(result.errorClass, "transient");
46
+ };
47
+
48
+ describe("comms contract types", () => {
49
+ it("exports cancelled status, hook context, opt-out, and delivery error fields", (): void => {
50
+ assert.equal(cancelled, "cancelled");
51
+ assert.equal(hookContext.attempt, 2);
52
+ assert.equal(optOut.reason, "unsubscribe");
53
+ assert.equal(delivery.errorCode, "bounce");
54
+ assert.equal(typeof onRetry, "function");
55
+ });
56
+ });
package/src/types.ts CHANGED
@@ -1,37 +1,37 @@
1
1
  import type mongoose from "mongoose";
2
2
 
3
+ export type CommsErrorClass = "config" | "permanent" | "transient";
4
+
3
5
  export interface SendResult {
4
6
  accepted: boolean;
5
7
  error?: string;
8
+ errorClass?: CommsErrorClass;
9
+ errorCode?: string;
6
10
  isPermanentFailure?: boolean;
11
+ metadata?: Record<string, unknown>;
7
12
  providerMessageId?: string;
8
13
  }
9
14
 
10
15
  export interface MailMessage {
16
+ dynamicTemplateData?: Record<string, unknown>;
11
17
  from?: string;
12
18
  html?: string;
13
19
  metadata?: Record<string, string>;
14
20
  replyTo?: string;
15
21
  subject: string;
22
+ templateId?: string;
16
23
  text?: string;
17
24
  to: string | string[];
18
25
  }
19
26
 
20
- export interface MailProvider {
21
- readonly id: string;
22
- sendMail(message: MailMessage): Promise<SendResult>;
23
- }
27
+ export type CommsChannel = "mail" | "push" | "sms" | "verification";
28
+ export type CommsMessageStatus = "bounced" | "cancelled" | "delivered" | "failed" | "sent";
24
29
 
25
30
  export interface SmsMessage {
26
31
  body: string;
27
32
  to: string;
28
33
  }
29
34
 
30
- export interface SmsProvider {
31
- readonly id: string;
32
- sendSms(message: SmsMessage): Promise<SendResult>;
33
- }
34
-
35
35
  export interface PushMessage {
36
36
  badge?: number;
37
37
  body: string;
@@ -41,16 +41,43 @@ export interface PushMessage {
41
41
  tokens: string[];
42
42
  }
43
43
 
44
- export interface PushProvider {
45
- readonly id: string;
46
- sendPush(message: PushMessage): Promise<SendResult[]>;
47
- }
48
-
49
44
  export interface StartVerificationOptions {
50
45
  channel: "email" | "sms";
51
46
  to: string;
52
47
  }
53
48
 
49
+ export type CommsHookMessage = MailMessage | PushMessage | SmsMessage | StartVerificationOptions;
50
+
51
+ export interface CommsHookContext {
52
+ attempt: number;
53
+ channel: CommsChannel;
54
+ isRetry: boolean;
55
+ message: CommsHookMessage;
56
+ messageId?: string;
57
+ provider: string;
58
+ userId?: string;
59
+ }
60
+
61
+ export interface BeforeSendResult {
62
+ cancel?: boolean;
63
+ message?: CommsHookMessage;
64
+ }
65
+
66
+ export interface MailProvider {
67
+ readonly id: string;
68
+ sendMail(message: MailMessage): Promise<SendResult>;
69
+ }
70
+
71
+ export interface SmsProvider {
72
+ readonly id: string;
73
+ sendSms(message: SmsMessage): Promise<SendResult>;
74
+ }
75
+
76
+ export interface PushProvider {
77
+ readonly id: string;
78
+ sendPush(message: PushMessage): Promise<SendResult[]>;
79
+ }
80
+
54
81
  export interface CheckVerificationOptions {
55
82
  code: string;
56
83
  to: string;
@@ -69,21 +96,35 @@ export interface VerificationProvider {
69
96
 
70
97
  export interface DeliveryEvent {
71
98
  channel: "mail" | "push" | "sms";
99
+ errorClass?: CommsErrorClass;
100
+ errorCode?: string;
72
101
  providerMessageId: string;
73
102
  raw?: unknown;
74
103
  status: "bounced" | "delivered" | "failed" | "opened";
75
104
  }
76
105
 
77
- export type CommsChannel = "mail" | "push" | "sms" | "verification";
78
- export type CommsMessageStatus = "bounced" | "delivered" | "failed" | "sent";
106
+ export interface OptOutEvent {
107
+ channel: "mail" | "sms";
108
+ provider: string;
109
+ raw?: unknown;
110
+ reason: string;
111
+ to: string;
112
+ }
79
113
 
80
114
  export interface CommsOptions {
115
+ beforeSend?: (context: CommsHookContext) => Promise<BeforeSendResult | undefined>;
81
116
  defaultFrom?: string;
82
117
  logMessages?: boolean;
83
118
  mail?: MailProvider;
84
119
  onDeliveryEvent?: (event: DeliveryEvent) => Promise<void>;
120
+ onError?: (context: CommsHookContext, result: SendResult) => Promise<void>;
121
+ onOptOut?: (event: OptOutEvent) => Promise<void>;
122
+ onRetry?: (context: CommsHookContext, result: SendResult) => Promise<void>;
123
+ onSend?: (context: CommsHookContext, result: SendResult) => Promise<void>;
85
124
  push?: PushProvider;
125
+ redactPayload?: (context: CommsHookContext, payload: unknown) => unknown;
86
126
  redactRecipients?: boolean;
127
+ retainPayloadDays?: number;
87
128
  sms?: SmsProvider;
88
129
  verification?: VerificationProvider;
89
130
  }