@terreno/comms 57.2.0 → 57.4.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 +31 -0
  13. package/dist/commsQuery.js +135 -0
  14. package/dist/commsRetry.d.ts +12 -0
  15. package/dist/commsRetry.js +78 -0
  16. package/dist/commsService.d.ts +11 -4
  17. package/dist/commsService.js +224 -47
  18. package/dist/index.d.ts +3 -3
  19. package/dist/index.js +3 -1
  20. package/dist/routes/commsDashboard.d.ts +9 -0
  21. package/dist/routes/commsDashboard.js +412 -0
  22. package/dist/templates.d.ts +9 -0
  23. package/dist/templates.js +34 -1
  24. package/dist/types.d.ts +12 -0
  25. package/dist/webhooks/sendgridWebhooks.d.ts +10 -0
  26. package/dist/webhooks/sendgridWebhooks.js +250 -0
  27. package/dist/webhooks/twilioWebhooks.d.ts +11 -0
  28. package/dist/webhooks/twilioWebhooks.js +174 -0
  29. package/package.json +30 -9
  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 +163 -0
  41. package/src/commsRetry.ts +87 -0
  42. package/src/commsService.test.ts +128 -0
  43. package/src/commsService.ts +184 -20
  44. package/src/index.ts +9 -2
  45. package/src/routes/commsDashboard.test.ts +310 -0
  46. package/src/routes/commsDashboard.ts +324 -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 +14 -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,34 +610,51 @@ 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,
635
+ userId: sendOptions?.userId ? String(sendOptions.userId) : undefined,
574
636
  };
575
637
  const before = await this.applyBeforeSend(context, hookErrors);
576
638
  const activeMessage = this.applyMailDefaults(before.message as MailMessage);
577
639
  context.message = activeMessage;
578
640
  if (before.cancel) {
579
641
  const result = this.cancelledResult();
580
- await this.logResult({
642
+ const logged = await this.logResult({
581
643
  attempts: [this.attemptFromResult(provider.id, result)],
582
644
  channel: "mail",
583
645
  context,
584
646
  hookErrors,
647
+ metadata: sendOptions?.extraMetadata,
585
648
  provider: provider.id,
586
649
  result,
650
+ retriedFromId: sendOptions?.retriedFromId,
587
651
  status: "cancelled",
588
652
  subject: activeMessage.subject,
589
653
  templateId: activeMessage.templateId,
590
654
  to: activeMessage.to,
655
+ userId: context.userId,
591
656
  });
592
- return result;
657
+ return this.withLoggedId(result, logged);
593
658
  }
594
659
 
595
660
  const first = await this.sendMailOnce(provider, activeMessage);
@@ -599,42 +664,48 @@ export class CommsService {
599
664
  hookErrors,
600
665
  logFields: {
601
666
  channel: "mail",
602
- metadata: first.metadata,
667
+ metadata: this.mergeSendMetadata(first, sendOptions),
668
+ retriedFromId: sendOptions?.retriedFromId,
603
669
  subject: activeMessage.subject,
604
670
  templateId: activeMessage.templateId,
605
671
  to: activeMessage.to,
672
+ userId: context.userId,
606
673
  },
607
674
  provider: provider.id,
608
675
  retry: (): Promise<SendResult> => this.sendMailOnce(provider, activeMessage),
609
676
  });
610
677
  }
611
678
 
612
- async sendSms(message: SmsMessage): Promise<SendResult> {
679
+ async sendSms(message: SmsMessage, sendOptions?: CommsSendOptions): Promise<SendResult> {
613
680
  const provider = this.smsProvider();
614
681
  const hookErrors: Record<string, string[]> = {};
615
682
  const context: CommsHookContext = {
616
683
  attempt: 1,
617
684
  channel: "sms",
618
- isRetry: false,
685
+ isRetry: sendOptions?.isRetry === true,
619
686
  message,
620
687
  provider: provider.id,
688
+ userId: sendOptions?.userId ? String(sendOptions.userId) : undefined,
621
689
  };
622
690
  const before = await this.applyBeforeSend(context, hookErrors);
623
691
  const activeMessage = before.message as SmsMessage;
624
692
  context.message = activeMessage;
625
693
  if (before.cancel) {
626
694
  const result = this.cancelledResult();
627
- await this.logResult({
695
+ const logged = await this.logResult({
628
696
  attempts: [this.attemptFromResult(provider.id, result)],
629
697
  channel: "sms",
630
698
  context,
631
699
  hookErrors,
700
+ metadata: sendOptions?.extraMetadata,
632
701
  provider: provider.id,
633
702
  result,
703
+ retriedFromId: sendOptions?.retriedFromId,
634
704
  status: "cancelled",
635
705
  to: activeMessage.to,
706
+ userId: context.userId,
636
707
  });
637
- return result;
708
+ return this.withLoggedId(result, logged);
638
709
  }
639
710
 
640
711
  const first = await this.sendSmsOnce(provider, activeMessage);
@@ -644,14 +715,20 @@ export class CommsService {
644
715
  hookErrors,
645
716
  logFields: {
646
717
  channel: "sms",
718
+ metadata: this.mergeSendMetadata(first, sendOptions),
719
+ retriedFromId: sendOptions?.retriedFromId,
647
720
  to: activeMessage.to,
721
+ userId: context.userId,
648
722
  },
649
723
  provider: provider.id,
650
724
  retry: (): Promise<SendResult> => this.sendSmsOnce(provider, activeMessage),
651
725
  });
652
726
  }
653
727
 
654
- async sendPushToUser(message: SendPushToUserMessage): Promise<SendResult[]> {
728
+ async sendPushToUser(
729
+ message: SendPushToUserMessage,
730
+ sendOptions?: CommsSendOptions
731
+ ): Promise<SendResult[]> {
655
732
  const provider = this.pushProvider();
656
733
  const hookErrors: Record<string, string[]> = {};
657
734
  const tokens = await PushToken.find({active: true, userId: message.userId});
@@ -659,7 +736,6 @@ export class CommsService {
659
736
  return [];
660
737
  }
661
738
 
662
- const tokenDocs = new Map(tokens.map((token) => [token.token, token]));
663
739
  const providerMessage: PushMessage = {
664
740
  badge: message.badge,
665
741
  body: message.body,
@@ -671,7 +747,7 @@ export class CommsService {
671
747
  const context: CommsHookContext = {
672
748
  attempt: 1,
673
749
  channel: "push",
674
- isRetry: false,
750
+ isRetry: sendOptions?.isRetry === true,
675
751
  message: providerMessage,
676
752
  provider: provider.id,
677
753
  userId: String(message.userId),
@@ -681,7 +757,7 @@ export class CommsService {
681
757
  context.message = activeMessage;
682
758
  if (before.cancel) {
683
759
  const result = this.cancelledResult();
684
- await Promise.all(
760
+ const loggedRows = await Promise.all(
685
761
  tokens.map(
686
762
  (token): Promise<CommsMessageDocument | null> =>
687
763
  this.logResult({
@@ -689,15 +765,17 @@ export class CommsService {
689
765
  channel: "push",
690
766
  context: this.cloneContext(context),
691
767
  hookErrors,
768
+ metadata: sendOptions?.extraMetadata,
692
769
  provider: provider.id,
693
770
  result,
771
+ retriedFromId: sendOptions?.retriedFromId,
694
772
  status: "cancelled",
695
773
  to: token.token,
696
774
  userId: String(message.userId),
697
775
  })
698
776
  )
699
777
  );
700
- return tokens.map(() => result);
778
+ return tokens.map((_, index) => this.withLoggedId(result, loggedRows[index] ?? null));
701
779
  }
702
780
 
703
781
  const sendTokens = activeMessage.tokens;
@@ -719,8 +797,10 @@ export class CommsService {
719
797
  channel: "push",
720
798
  context: tokenContext,
721
799
  hookErrors,
800
+ metadata: this.mergeSendMetadata(result, sendOptions),
722
801
  provider: provider.id,
723
802
  result,
803
+ retriedFromId: sendOptions?.retriedFromId,
724
804
  status: result.accepted ? "sent" : "failed",
725
805
  to: tokenValue,
726
806
  userId: String(message.userId),
@@ -795,15 +875,18 @@ export class CommsService {
795
875
  tokenHookErrors
796
876
  );
797
877
  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();
878
+ if (!result.accepted && isPermanentPushFailure(result)) {
879
+ await this.deactivatePushToken(tokenValue);
802
880
  }
803
881
  })
804
882
  );
805
883
 
806
- return sendTokens.map((tokenValue) => finalByToken.get(tokenValue) as SendResult);
884
+ return sendTokens.map((tokenValue) =>
885
+ this.withLoggedId(
886
+ finalByToken.get(tokenValue) as SendResult,
887
+ loggedByToken.get(tokenValue) ?? null
888
+ )
889
+ );
807
890
  }
808
891
 
809
892
  async startVerification(options: StartVerificationOptions): Promise<SendResult> {
@@ -898,4 +981,85 @@ export class CommsService {
898
981
  return {error: loggedResult.error, valid: false};
899
982
  }
900
983
  }
984
+
985
+ async retryMessage(options: RetryMessageOptions): Promise<CommsMessageDocument> {
986
+ if (!mongoose.isValidObjectId(options.messageId)) {
987
+ throw new APIError({status: 404, title: "Comms message not found"});
988
+ }
989
+ const original = await CommsMessage.findOneOrNone({_id: options.messageId});
990
+ if (!original) {
991
+ throw new APIError({status: 404, title: "Comms message not found"});
992
+ }
993
+ const block = evaluateRetryBlock({
994
+ isChannelConfigured: (channel) => this.isChannelConfigured(channel),
995
+ message: original,
996
+ });
997
+ if (block) {
998
+ throwRetryBlock(block);
999
+ }
1000
+
1001
+ const sendOptions: CommsSendOptions = {
1002
+ extraMetadata: options.retriedByUserId
1003
+ ? {retriedByUserId: options.retriedByUserId}
1004
+ : undefined,
1005
+ isRetry: true,
1006
+ retriedFromId: String(original._id),
1007
+ userId: original.userId,
1008
+ };
1009
+ const payload = original.payload as Record<string, unknown>;
1010
+ let sendResult: SendResult | SendResult[] | undefined;
1011
+
1012
+ if (original.channel === "mail") {
1013
+ sendResult = await this.sendMail(
1014
+ {
1015
+ dynamicTemplateData: payload.dynamicTemplateData as Record<string, unknown> | undefined,
1016
+ from: payload.from as string | undefined,
1017
+ html: payload.html as string | undefined,
1018
+ replyTo: payload.replyTo as string | undefined,
1019
+ subject: String(payload.subject ?? original.subject ?? ""),
1020
+ templateId: (payload.templateId as string | undefined) ?? original.templateId,
1021
+ text: payload.text as string | undefined,
1022
+ to: (payload.to as string | string[]) ?? original.to,
1023
+ },
1024
+ sendOptions
1025
+ );
1026
+ } else if (original.channel === "sms") {
1027
+ sendResult = await this.sendSms(
1028
+ {
1029
+ body: String(payload.body ?? ""),
1030
+ to: String(payload.to ?? original.to),
1031
+ },
1032
+ sendOptions
1033
+ );
1034
+ } else if (original.userId) {
1035
+ sendResult = await this.sendPushToUser(
1036
+ {
1037
+ badge: payload.badge as number | undefined,
1038
+ body: String(payload.body ?? ""),
1039
+ data: payload.data as Record<string, unknown> | undefined,
1040
+ sound: payload.sound as string | null | undefined,
1041
+ title: String(payload.title ?? ""),
1042
+ userId: original.userId,
1043
+ },
1044
+ sendOptions
1045
+ );
1046
+ } else {
1047
+ throwRetryBlock({
1048
+ code: "comms-retry-not-retryable",
1049
+ title: "Push retries require a linked user",
1050
+ });
1051
+ }
1052
+
1053
+ const loggedId = this.loggedIdFromSend(sendResult ?? []);
1054
+ if (!loggedId) {
1055
+ throw new APIError({status: 500, title: "Retry did not create a communication log"});
1056
+ }
1057
+ const retried = await CommsMessage.findOneOrNone({_id: loggedId});
1058
+ if (!retried) {
1059
+ throw new APIError({status: 500, title: "Retry did not create a communication log"});
1060
+ }
1061
+ original.retriedById = retried._id;
1062
+ await original.save();
1063
+ return retried;
1064
+ }
901
1065
  }
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,