@terreno/comms 57.1.0 → 57.3.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 (57) hide show
  1. package/README.md +58 -0
  2. package/dist/adapters/expoPush.d.ts +54 -0
  3. package/dist/adapters/expoPush.js +400 -0
  4. package/dist/adapters/sendgrid.d.ts +3 -0
  5. package/dist/adapters/sendgrid.js +7 -1
  6. package/dist/adapters/twilioSms.d.ts +36 -0
  7. package/dist/adapters/twilioSms.js +232 -0
  8. package/dist/adapters/twilioVerify.d.ts +44 -0
  9. package/dist/adapters/twilioVerify.js +212 -0
  10. package/dist/commsApp.d.ts +4 -1
  11. package/dist/commsApp.js +28 -2
  12. package/dist/commsQuery.d.ts +30 -0
  13. package/dist/commsQuery.js +134 -0
  14. package/dist/commsRetry.d.ts +16 -0
  15. package/dist/commsRetry.js +79 -0
  16. package/dist/commsService.d.ts +11 -4
  17. package/dist/commsService.js +217 -47
  18. package/dist/index.d.ts +3 -3
  19. package/dist/index.js +3 -1
  20. package/dist/routes/commsDashboard.d.ts +11 -0
  21. package/dist/routes/commsDashboard.js +414 -0
  22. package/dist/templates.d.ts +9 -0
  23. package/dist/templates.js +34 -1
  24. package/dist/types.d.ts +11 -0
  25. package/dist/webhooks/sendgridWebhooks.d.ts +16 -0
  26. package/dist/webhooks/sendgridWebhooks.js +251 -0
  27. package/dist/webhooks/twilioWebhooks.d.ts +18 -0
  28. package/dist/webhooks/twilioWebhooks.js +175 -0
  29. package/package.json +27 -6
  30. package/src/adapters/expoPush.test.ts +585 -0
  31. package/src/adapters/expoPush.ts +304 -0
  32. package/src/adapters/sendgrid.ts +8 -0
  33. package/src/adapters/twilioSms.test.ts +374 -0
  34. package/src/adapters/twilioSms.ts +237 -0
  35. package/src/adapters/twilioVerify.test.ts +207 -0
  36. package/src/adapters/twilioVerify.ts +227 -0
  37. package/src/commsApp.test.ts +13 -0
  38. package/src/commsApp.ts +38 -3
  39. package/src/commsQuery.test.ts +165 -0
  40. package/src/commsQuery.ts +162 -0
  41. package/src/commsRetry.ts +87 -0
  42. package/src/commsService.test.ts +68 -0
  43. package/src/commsService.ts +177 -20
  44. package/src/index.ts +9 -2
  45. package/src/routes/commsDashboard.test.ts +310 -0
  46. package/src/routes/commsDashboard.ts +327 -0
  47. package/src/templates.test.ts +63 -1
  48. package/src/templates.ts +47 -0
  49. package/src/tests/bunSetup.ts +8 -0
  50. package/src/types.ts +13 -0
  51. package/src/webhooks/sendgridWebhooks.test.ts +520 -0
  52. package/src/webhooks/sendgridWebhooks.ts +166 -0
  53. package/src/webhooks/twilioWebhooks.test.ts +352 -0
  54. package/src/webhooks/twilioWebhooks.ts +154 -0
  55. package/dist/routes/commsExplorer.d.ts +0 -7
  56. package/dist/routes/commsExplorer.js +0 -147
  57. package/src/routes/commsExplorer.ts +0 -114
@@ -1,5 +1,6 @@
1
1
  import {APIError, logger} from "@terreno/api";
2
2
  import {DateTime} from "luxon";
3
+ import mongoose from "mongoose";
3
4
 
4
5
  import {
5
6
  ConsoleMailProvider,
@@ -7,6 +8,7 @@ import {
7
8
  ConsoleSmsProvider,
8
9
  ConsoleVerificationProvider,
9
10
  } from "./adapters/console";
11
+ import {evaluateRetryBlock, throwRetryBlock} from "./commsRetry";
10
12
  import {CommsMessage} from "./models/commsMessage";
11
13
  import {PushToken} from "./models/pushToken";
12
14
  import type {CommsMessageAttempt, CommsMessageDocument} from "./modelTypes";
@@ -17,12 +19,14 @@ import type {
17
19
  CommsHookMessage,
18
20
  CommsMessageStatus,
19
21
  CommsOptions,
22
+ CommsSendOptions,
20
23
  DeliveryEvent,
21
24
  MailMessage,
22
25
  MailProvider,
23
26
  OptOutEvent,
24
27
  PushMessage,
25
28
  PushProvider,
29
+ RetryMessageOptions,
26
30
  SendPushToUserMessage,
27
31
  SendResult,
28
32
  SmsMessage,
@@ -96,6 +100,7 @@ export class CommsService {
96
100
  await row.save();
97
101
  } catch (error: unknown) {
98
102
  logger.warn(`[comms] Failed to apply delivery event: ${String(error)}`);
103
+ throw error;
99
104
  }
100
105
  }
101
106
 
@@ -104,6 +109,19 @@ export class CommsService {
104
109
  await this.invokeHook(onOptOut ? (): Promise<void> => onOptOut(event) : undefined, "onOptOut");
105
110
  }
106
111
 
112
+ async deactivatePushToken(token: string): Promise<void> {
113
+ try {
114
+ const tokenDoc = await PushToken.findOneOrNone({token});
115
+ if (!tokenDoc || tokenDoc.active === false) {
116
+ return;
117
+ }
118
+ tokenDoc.active = false;
119
+ await tokenDoc.save();
120
+ } catch (error: unknown) {
121
+ logger.warn(`[comms] Failed to deactivate push token: ${String(error)}`);
122
+ }
123
+ }
124
+
107
125
  async clearExpiredPayloads(): Promise<number> {
108
126
  return CommsMessage.clearExpiredPayloads();
109
127
  }
@@ -271,6 +289,7 @@ export class CommsService {
271
289
  omitPayload,
272
290
  provider,
273
291
  result,
292
+ retriedFromId,
274
293
  status,
275
294
  subject,
276
295
  templateId,
@@ -285,6 +304,7 @@ export class CommsService {
285
304
  omitPayload?: boolean;
286
305
  provider: string;
287
306
  result: SendResult;
307
+ retriedFromId?: string;
288
308
  status: CommsMessageStatus;
289
309
  subject?: string;
290
310
  templateId?: string;
@@ -316,6 +336,7 @@ export class CommsService {
316
336
  payloadExpiresAt: payload === undefined ? undefined : this.payloadExpiresAt(),
317
337
  provider,
318
338
  providerMessageId: result.providerMessageId,
339
+ retriedFromId,
319
340
  status,
320
341
  subject,
321
342
  templateId,
@@ -434,6 +455,7 @@ export class CommsService {
434
455
  logFields: {
435
456
  channel: CommsChannel;
436
457
  metadata?: Record<string, unknown>;
458
+ retriedFromId?: string;
437
459
  subject?: string;
438
460
  templateId?: string;
439
461
  to: string | string[];
@@ -450,6 +472,7 @@ export class CommsService {
450
472
  metadata: logFields.metadata,
451
473
  provider,
452
474
  result: first,
475
+ retriedFromId: logFields.retriedFromId,
453
476
  status: first.accepted ? "sent" : "failed",
454
477
  subject: logFields.subject,
455
478
  templateId: logFields.templateId,
@@ -464,7 +487,21 @@ export class CommsService {
464
487
  }
465
488
  await this.notifyOutcomeHooks(context, retried.result, hookErrors);
466
489
  await this.patchHookErrors(finalLogged, hookErrors);
467
- return retried.result;
490
+ return this.withLoggedId(retried.result, finalLogged);
491
+ }
492
+
493
+ private withLoggedId(result: SendResult, logged: CommsMessageDocument | null): SendResult {
494
+ if (!logged) {
495
+ return result;
496
+ }
497
+ return {...result, loggedMessageId: String(logged._id)};
498
+ }
499
+
500
+ private loggedIdFromSend(result: SendResult | SendResult[]): string | undefined {
501
+ if (Array.isArray(result)) {
502
+ return result.map((row) => row.loggedMessageId).find((id) => Boolean(id));
503
+ }
504
+ return result.loggedMessageId;
468
505
  }
469
506
 
470
507
  private cancelledResult(): SendResult {
@@ -511,6 +548,17 @@ export class CommsService {
511
548
  }
512
549
  }
513
550
 
551
+ private mergeSendMetadata(
552
+ result: SendResult,
553
+ sendOptions?: CommsSendOptions
554
+ ): Record<string, unknown> | undefined {
555
+ const extra = sendOptions?.extraMetadata;
556
+ if (!result.metadata && !extra) {
557
+ return result.metadata;
558
+ }
559
+ return {...result.metadata, ...extra};
560
+ }
561
+
514
562
  private mailProvider(): MailProvider {
515
563
  if (this.options.mail) {
516
564
  return this.options.mail;
@@ -562,13 +610,26 @@ export class CommsService {
562
610
  };
563
611
  }
564
612
 
565
- async sendMail(message: MailMessage): Promise<SendResult> {
613
+ isChannelConfigured(channel: CommsChannel): boolean {
614
+ if (channel === "mail") {
615
+ return Boolean(this.options.mail) || !isProduction();
616
+ }
617
+ if (channel === "sms") {
618
+ return Boolean(this.options.sms) || !isProduction();
619
+ }
620
+ if (channel === "push") {
621
+ return Boolean(this.options.push) || !isProduction();
622
+ }
623
+ return Boolean(this.options.verification) || !isProduction();
624
+ }
625
+
626
+ async sendMail(message: MailMessage, sendOptions?: CommsSendOptions): Promise<SendResult> {
566
627
  const provider = this.mailProvider();
567
628
  const hookErrors: Record<string, string[]> = {};
568
629
  const context: CommsHookContext = {
569
630
  attempt: 1,
570
631
  channel: "mail",
571
- isRetry: false,
632
+ isRetry: sendOptions?.isRetry === true,
572
633
  message: this.applyMailDefaults(message),
573
634
  provider: provider.id,
574
635
  };
@@ -577,19 +638,21 @@ export class CommsService {
577
638
  context.message = activeMessage;
578
639
  if (before.cancel) {
579
640
  const result = this.cancelledResult();
580
- await this.logResult({
641
+ const logged = await this.logResult({
581
642
  attempts: [this.attemptFromResult(provider.id, result)],
582
643
  channel: "mail",
583
644
  context,
584
645
  hookErrors,
646
+ metadata: sendOptions?.extraMetadata,
585
647
  provider: provider.id,
586
648
  result,
649
+ retriedFromId: sendOptions?.retriedFromId,
587
650
  status: "cancelled",
588
651
  subject: activeMessage.subject,
589
652
  templateId: activeMessage.templateId,
590
653
  to: activeMessage.to,
591
654
  });
592
- return result;
655
+ return this.withLoggedId(result, logged);
593
656
  }
594
657
 
595
658
  const first = await this.sendMailOnce(provider, activeMessage);
@@ -599,7 +662,8 @@ export class CommsService {
599
662
  hookErrors,
600
663
  logFields: {
601
664
  channel: "mail",
602
- metadata: first.metadata,
665
+ metadata: this.mergeSendMetadata(first, sendOptions),
666
+ retriedFromId: sendOptions?.retriedFromId,
603
667
  subject: activeMessage.subject,
604
668
  templateId: activeMessage.templateId,
605
669
  to: activeMessage.to,
@@ -609,13 +673,13 @@ export class CommsService {
609
673
  });
610
674
  }
611
675
 
612
- async sendSms(message: SmsMessage): Promise<SendResult> {
676
+ async sendSms(message: SmsMessage, sendOptions?: CommsSendOptions): Promise<SendResult> {
613
677
  const provider = this.smsProvider();
614
678
  const hookErrors: Record<string, string[]> = {};
615
679
  const context: CommsHookContext = {
616
680
  attempt: 1,
617
681
  channel: "sms",
618
- isRetry: false,
682
+ isRetry: sendOptions?.isRetry === true,
619
683
  message,
620
684
  provider: provider.id,
621
685
  };
@@ -624,17 +688,19 @@ export class CommsService {
624
688
  context.message = activeMessage;
625
689
  if (before.cancel) {
626
690
  const result = this.cancelledResult();
627
- await this.logResult({
691
+ const logged = await this.logResult({
628
692
  attempts: [this.attemptFromResult(provider.id, result)],
629
693
  channel: "sms",
630
694
  context,
631
695
  hookErrors,
696
+ metadata: sendOptions?.extraMetadata,
632
697
  provider: provider.id,
633
698
  result,
699
+ retriedFromId: sendOptions?.retriedFromId,
634
700
  status: "cancelled",
635
701
  to: activeMessage.to,
636
702
  });
637
- return result;
703
+ return this.withLoggedId(result, logged);
638
704
  }
639
705
 
640
706
  const first = await this.sendSmsOnce(provider, activeMessage);
@@ -644,6 +710,8 @@ export class CommsService {
644
710
  hookErrors,
645
711
  logFields: {
646
712
  channel: "sms",
713
+ metadata: this.mergeSendMetadata(first, sendOptions),
714
+ retriedFromId: sendOptions?.retriedFromId,
647
715
  to: activeMessage.to,
648
716
  },
649
717
  provider: provider.id,
@@ -651,7 +719,10 @@ export class CommsService {
651
719
  });
652
720
  }
653
721
 
654
- async sendPushToUser(message: SendPushToUserMessage): Promise<SendResult[]> {
722
+ async sendPushToUser(
723
+ message: SendPushToUserMessage,
724
+ sendOptions?: CommsSendOptions
725
+ ): Promise<SendResult[]> {
655
726
  const provider = this.pushProvider();
656
727
  const hookErrors: Record<string, string[]> = {};
657
728
  const tokens = await PushToken.find({active: true, userId: message.userId});
@@ -659,7 +730,6 @@ export class CommsService {
659
730
  return [];
660
731
  }
661
732
 
662
- const tokenDocs = new Map(tokens.map((token) => [token.token, token]));
663
733
  const providerMessage: PushMessage = {
664
734
  badge: message.badge,
665
735
  body: message.body,
@@ -671,7 +741,7 @@ export class CommsService {
671
741
  const context: CommsHookContext = {
672
742
  attempt: 1,
673
743
  channel: "push",
674
- isRetry: false,
744
+ isRetry: sendOptions?.isRetry === true,
675
745
  message: providerMessage,
676
746
  provider: provider.id,
677
747
  userId: String(message.userId),
@@ -681,7 +751,7 @@ export class CommsService {
681
751
  context.message = activeMessage;
682
752
  if (before.cancel) {
683
753
  const result = this.cancelledResult();
684
- await Promise.all(
754
+ const loggedRows = await Promise.all(
685
755
  tokens.map(
686
756
  (token): Promise<CommsMessageDocument | null> =>
687
757
  this.logResult({
@@ -689,15 +759,17 @@ export class CommsService {
689
759
  channel: "push",
690
760
  context: this.cloneContext(context),
691
761
  hookErrors,
762
+ metadata: sendOptions?.extraMetadata,
692
763
  provider: provider.id,
693
764
  result,
765
+ retriedFromId: sendOptions?.retriedFromId,
694
766
  status: "cancelled",
695
767
  to: token.token,
696
768
  userId: String(message.userId),
697
769
  })
698
770
  )
699
771
  );
700
- return tokens.map(() => result);
772
+ return tokens.map((_, index) => this.withLoggedId(result, loggedRows[index] ?? null));
701
773
  }
702
774
 
703
775
  const sendTokens = activeMessage.tokens;
@@ -719,8 +791,10 @@ export class CommsService {
719
791
  channel: "push",
720
792
  context: tokenContext,
721
793
  hookErrors,
794
+ metadata: this.mergeSendMetadata(result, sendOptions),
722
795
  provider: provider.id,
723
796
  result,
797
+ retriedFromId: sendOptions?.retriedFromId,
724
798
  status: result.accepted ? "sent" : "failed",
725
799
  to: tokenValue,
726
800
  userId: String(message.userId),
@@ -795,15 +869,18 @@ export class CommsService {
795
869
  tokenHookErrors
796
870
  );
797
871
  await this.patchHookErrors(logged, tokenHookErrors);
798
- const tokenDoc = tokenDocs.get(tokenValue);
799
- if (tokenDoc && !result.accepted && isPermanentPushFailure(result)) {
800
- tokenDoc.active = false;
801
- await tokenDoc.save();
872
+ if (!result.accepted && isPermanentPushFailure(result)) {
873
+ await this.deactivatePushToken(tokenValue);
802
874
  }
803
875
  })
804
876
  );
805
877
 
806
- return sendTokens.map((tokenValue) => finalByToken.get(tokenValue) as SendResult);
878
+ return sendTokens.map((tokenValue) =>
879
+ this.withLoggedId(
880
+ finalByToken.get(tokenValue) as SendResult,
881
+ loggedByToken.get(tokenValue) ?? null
882
+ )
883
+ );
807
884
  }
808
885
 
809
886
  async startVerification(options: StartVerificationOptions): Promise<SendResult> {
@@ -898,4 +975,84 @@ export class CommsService {
898
975
  return {error: loggedResult.error, valid: false};
899
976
  }
900
977
  }
978
+
979
+ async retryMessage(options: RetryMessageOptions): Promise<CommsMessageDocument> {
980
+ if (!mongoose.isValidObjectId(options.messageId)) {
981
+ throw new APIError({status: 404, title: "Comms message not found"});
982
+ }
983
+ const original = await CommsMessage.findOneOrNone({_id: options.messageId});
984
+ if (!original) {
985
+ throw new APIError({status: 404, title: "Comms message not found"});
986
+ }
987
+ const block = evaluateRetryBlock({
988
+ isChannelConfigured: (channel) => this.isChannelConfigured(channel),
989
+ message: original,
990
+ });
991
+ if (block) {
992
+ throwRetryBlock(block);
993
+ }
994
+
995
+ const sendOptions: CommsSendOptions = {
996
+ extraMetadata: options.retriedByUserId
997
+ ? {retriedByUserId: options.retriedByUserId}
998
+ : undefined,
999
+ isRetry: true,
1000
+ retriedFromId: String(original._id),
1001
+ };
1002
+ const payload = original.payload as Record<string, unknown>;
1003
+ let sendResult: SendResult | SendResult[] | undefined;
1004
+
1005
+ if (original.channel === "mail") {
1006
+ sendResult = await this.sendMail(
1007
+ {
1008
+ dynamicTemplateData: payload.dynamicTemplateData as Record<string, unknown> | undefined,
1009
+ from: payload.from as string | undefined,
1010
+ html: payload.html as string | undefined,
1011
+ replyTo: payload.replyTo as string | undefined,
1012
+ subject: String(payload.subject ?? original.subject ?? ""),
1013
+ templateId: (payload.templateId as string | undefined) ?? original.templateId,
1014
+ text: payload.text as string | undefined,
1015
+ to: (payload.to as string | string[]) ?? original.to,
1016
+ },
1017
+ sendOptions
1018
+ );
1019
+ } else if (original.channel === "sms") {
1020
+ sendResult = await this.sendSms(
1021
+ {
1022
+ body: String(payload.body ?? ""),
1023
+ to: String(payload.to ?? original.to),
1024
+ },
1025
+ sendOptions
1026
+ );
1027
+ } else if (original.userId) {
1028
+ sendResult = await this.sendPushToUser(
1029
+ {
1030
+ badge: payload.badge as number | undefined,
1031
+ body: String(payload.body ?? ""),
1032
+ data: payload.data as Record<string, unknown> | undefined,
1033
+ sound: payload.sound as string | null | undefined,
1034
+ title: String(payload.title ?? ""),
1035
+ userId: original.userId,
1036
+ },
1037
+ sendOptions
1038
+ );
1039
+ } else {
1040
+ throwRetryBlock({
1041
+ code: "comms-retry-not-retryable",
1042
+ title: "Push retries require a linked user",
1043
+ });
1044
+ }
1045
+
1046
+ const loggedId = this.loggedIdFromSend(sendResult ?? []);
1047
+ if (!loggedId) {
1048
+ throw new APIError({status: 500, title: "Retry did not create a communication log"});
1049
+ }
1050
+ const retried = await CommsMessage.findOneOrNone({_id: loggedId});
1051
+ if (!retried) {
1052
+ throw new APIError({status: 500, title: "Retry did not create a communication log"});
1053
+ }
1054
+ original.retriedById = retried._id;
1055
+ await original.save();
1056
+ return retried;
1057
+ }
901
1058
  }
package/src/index.ts CHANGED
@@ -24,8 +24,13 @@ export type {
24
24
  PushTokenSchema,
25
25
  PushTokenStatics,
26
26
  } from "./modelTypes";
27
- export type {MessageTemplate, RenderTemplateOptions} from "./templates";
28
- export {renderTemplate} from "./templates";
27
+ export type {
28
+ AuthMailTemplateId,
29
+ MessageTemplate,
30
+ RenderAuthMailOptions,
31
+ RenderTemplateOptions,
32
+ } from "./templates";
33
+ export {DEFAULT_AUTH_MAIL_TEMPLATES, renderAuthMail, renderTemplate} from "./templates";
29
34
  export type {
30
35
  BeforeSendResult,
31
36
  CheckVerificationOptions,
@@ -35,12 +40,14 @@ export type {
35
40
  CommsHookMessage,
36
41
  CommsMessageStatus,
37
42
  CommsOptions,
43
+ CommsSendOptions,
38
44
  DeliveryEvent,
39
45
  MailMessage,
40
46
  MailProvider,
41
47
  OptOutEvent,
42
48
  PushMessage,
43
49
  PushProvider,
50
+ RetryMessageOptions,
44
51
  SendPushToUserMessage,
45
52
  SendResult,
46
53
  SmsMessage,