@oneuptime/common 14.0.7 → 14.0.8

package/Tests/Types/StatusPage/SubscriberNotificationTemplatePreview.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, test } from "@jest/globals";
+import SafeHtml from "../../../Types/SafeHtml";
+import StatusPageSubscriberNotificationEventType from "../../../Types/StatusPage/StatusPageSubscriberNotificationEventType";
+import StatusPageSubscriberNotificationMethod from "../../../Types/StatusPage/StatusPageSubscriberNotificationMethod";
+import SubscriberNotificationTemplatePreview, {
+  SubscriberNotificationTemplatePreviewResult,
+  SubscriberNotificationTemplateSampleValues,
+} from "../../../Types/StatusPage/SubscriberNotificationTemplatePreview";
+import SubscriberNotificationTemplateVariables from "../../../Types/StatusPage/SubscriberNotificationTemplateVariables";
+
+/*
+ * The template editor's live preview: a custom subscriber notification
+ * template filled with sample values, by the compiler the subscriber jobs use,
+ * with each value in the format its channel gets it in.
+ */
+
+const INCIDENT_CREATED: StatusPageSubscriberNotificationEventType =
+  StatusPageSubscriberNotificationEventType.SubscriberIncidentCreated;
+
+function render(data: {
+  method: StatusPageSubscriberNotificationMethod;
+  body: string;
+  subject?: string;
+  eventType?: StatusPageSubscriberNotificationEventType | undefined;
+}): SubscriberNotificationTemplatePreviewResult {
+  return SubscriberNotificationTemplatePreview.render({
+    eventType: "eventType" in data ? data.eventType : INCIDENT_CREATED,
+    notificationMethod: data.method,
+    templateBody: data.body,
+    emailSubject: data.subject,
+  });
+}
+
+describe("the email body", () => {
+  test("HTML variables go in as HTML and plain ones escaped, as the jobs fill them", () => {
+    const preview: SubscriberNotificationTemplatePreviewResult = render({
+      method: StatusPageSubscriberNotificationMethod.Email,
+      body: '<h1>{{incidentTitle}}</h1>{{incidentDescription}}<p>{{resourcesAffected}}</p><a href="{{unsubscribeUrl}}">x</a>',
+      subject: "{{statusPageName}}: {{incidentTitle}}",
+    });
+
+    expect(preview.isAvailable).toBe(true);
+    expect(preview.isHtml).toBe(true);
+    expect(preview.body).toBe(
+      '<h1>Checkout requests are failing</h1><p>Customers in <strong>Europe</strong> cannot complete a checkout. We are investigating.</p><p>Europe: Checkout API<br/>Americas: Payments API</p><a href="https://status.example.com/unsubscribe/preview">x</a>',
+    );
+    expect(preview.subject).toBe("Acme Status: Checkout requests are failing");
+    expect(preview.unknownPlaceholders).toEqual([]);
+  });
+
+  test("a sample that looks like HTML in a plain variable is escaped, never markup", () => {
+    const values: SubscriberNotificationTemplateSampleValues =
+      SubscriberNotificationTemplatePreview.getSampleValues({
+        eventType: INCIDENT_CREATED,
+        templates: [],
+      });
+
+    // Only the variables that are HTML in an email body are SafeHtml.
+    const htmlNames: Array<string> = Object.entries(values.emailBody)
+      .filter(([, value]: [string, unknown]): boolean => {
+        return SafeHtml.isSafeHtml(value);
+      })
+      .map(([name]: [string, unknown]): string => {
+        return name;
+      })
+      .sort();
+
+    expect(htmlNames).toEqual(
+      SubscriberNotificationTemplateVariables.getEmailBodyHtmlVariableNamesForEventType(
+        INCIDENT_CREATED,
+      ).sort(),
+    );
+  });
+
+  test("no subject: none is shown, so the default subject is said to be used", () => {
+    expect(
+      render({
+        method: StatusPageSubscriberNotificationMethod.Email,
+        body: "<p>{{incidentTitle}}</p>",
+      }).subject,
+    ).toBeNull();
+  });
+});
+
+describe("the other channels", () => {
+  test("SMS gets plain text", () => {
+    const preview: SubscriberNotificationTemplatePreviewResult = render({
+      method: StatusPageSubscriberNotificationMethod.SMS,
+      body: "{{incidentTitle}}: {{incidentDescription}} ({{resourcesAffected}})",
+      subject: "{{incidentTitle}}",
+    });
+
+    expect(preview.isHtml).toBe(false);
+    expect(preview.subject).toBeNull();
+    expect(preview.body).toBe(
+      "Checkout requests are failing: Customers in Europe cannot complete a checkout. We are investigating. (Europe: Checkout API; Americas: Payments API)",
+    );
+  });
+
+  test("Slack and Microsoft Teams get Markdown", () => {
+    for (const method of [
+      StatusPageSubscriberNotificationMethod.Slack,
+      StatusPageSubscriberNotificationMethod.MicrosoftTeams,
+    ]) {
+      expect(
+        render({
+          method: method,
+          body: "**{{incidentTitle}}**\n{{incidentDescription}}",
+        }).body,
+      ).toBe(
+        "**Checkout requests are failing**\nCustomers in **Europe** cannot complete a checkout. We are investigating.",
+      );
+    }
+  });
+});
+
+describe("placeholders", () => {
+  test("a custom field placeholder gets a sample; one the event does not offer is listed and left as written", () => {
+    const preview: SubscriberNotificationTemplatePreviewResult = render({
+      method: StatusPageSubscriberNotificationMethod.SMS,
+      body: "{{customFields.impact_details}} {{incidentStat}} {{scheduledMaintenanceTitle}}",
+    });
+
+    expect(preview.body).toBe(
+      "Sample impact_details {{incidentStat}} {{scheduledMaintenanceTitle}}",
+    );
+    expect(preview.unknownPlaceholders).toEqual([
+      "incidentStat",
+      "scheduledMaintenanceTitle",
+    ]);
+  });
+
+  test.each(
+    Object.values(StatusPageSubscriberNotificationEventType).filter(
+      (eventType: StatusPageSubscriberNotificationEventType): boolean => {
+        return (
+          eventType !==
+          StatusPageSubscriberNotificationEventType.SubscriberReport
+        );
+      },
+    ),
+  )(
+    "every variable %s offers has a real sample",
+    (eventType: StatusPageSubscriberNotificationEventType) => {
+      const values: SubscriberNotificationTemplateSampleValues =
+        SubscriberNotificationTemplatePreview.getSampleValues({
+          eventType: eventType,
+          templates: [],
+        });
+
+      for (const name of SubscriberNotificationTemplateVariables.getVariableNamesForEventType(
+        eventType,
+      )) {
+        expect(values.plainText[name]).toBeTruthy();
+        expect(values.plainText[name]).not.toBe(`[${name}]`);
+      }
+    },
+  );
+});
+
+describe("what has no preview", () => {
+  test("the report template, and no event type", () => {
+    expect(
+      render({
+        method: StatusPageSubscriberNotificationMethod.Email,
+        body: "{{report.reportDates}}",
+        eventType: StatusPageSubscriberNotificationEventType.SubscriberReport,
+      }).isAvailable,
+    ).toBe(false);
+
+    expect(
+      render({
+        method: StatusPageSubscriberNotificationMethod.Email,
+        body: "<p>x</p>",
+        eventType: undefined,
+      }).isAvailable,
+    ).toBe(false);
+  });
+});

package/Tests/Types/StatusPage/SubscriberNotificationTemplateVariables.test.ts

@@ -1,5 +1,6 @@
 import StatusPageSubscriberNotificationEventType from "../../../Types/StatusPage/StatusPageSubscriberNotificationEventType";
 import SubscriberNotificationTemplateVariables, {
+  SubscriberNotificationTemplateDynamicVariable,
   SubscriberNotificationTemplateVariable,
 } from "../../../Types/StatusPage/SubscriberNotificationTemplateVariables";
 import { describe, expect, test } from "@jest/globals";
@@ -25,6 +26,17 @@ const STATUS_PAGE: Array<string> = [
 
 const COMMON: Array<string> = [...STATUS_PAGE, "resourcesAffected"];
 
+// What every incident event offers on top of its own variables.
+const INCIDENT: Array<string> = ["incidentLabels", "affectedStatusPages"];
+
+const INCIDENT_EVENTS: Array<StatusPageSubscriberNotificationEventType> = [
+  StatusPageSubscriberNotificationEventType.SubscriberIncidentCreated,
+  StatusPageSubscriberNotificationEventType.SubscriberIncidentStateChanged,
+  StatusPageSubscriberNotificationEventType.SubscriberIncidentNoteCreated,
+  StatusPageSubscriberNotificationEventType.SubscriberIncidentNoteUpdated,
+  StatusPageSubscriberNotificationEventType.SubscriberIncidentPostmortemPublished,
+];
+
 // Messages about the subscription itself, or the report - not about a resource.
 const ACCOUNT_EVENTS: Array<StatusPageSubscriberNotificationEventType> = [
   StatusPageSubscriberNotificationEventType.SubscriberSubscriptionConfirmation,
@@ -151,6 +163,38 @@ describe("SubscriberNotificationTemplateVariables", () => {
         "postedAt",
         "note",
         "detailsUrl",
+        ...INCIDENT,
+      ],
+    ],
+    [
+      Event.SubscriberIncidentCreated,
+      [
+        "incidentTitle",
+        "incidentDescription",
+        "incidentSeverity",
+        "detailsUrl",
+        ...INCIDENT,
+      ],
+    ],
+    [
+      Event.SubscriberIncidentStateChanged,
+      [
+        "incidentTitle",
+        "incidentDescription",
+        "incidentSeverity",
+        "incidentState",
+        "detailsUrl",
+        ...INCIDENT,
+      ],
+    ],
+    [
+      Event.SubscriberIncidentPostmortemPublished,
+      [
+        "incidentTitle",
+        "incidentSeverity",
+        "postmortemNote",
+        "detailsUrl",
+        ...INCIDENT,
       ],
     ],
     [
@@ -208,6 +252,221 @@ describe("SubscriberNotificationTemplateVariables", () => {
     },
   );
 
+  /*
+   * In the body of an email template, a variable is either HTML already
+   * (rendered Markdown, or the resource list built from escaped names) or
+   * plain text, which the body escapes. The workers' tests hold each worker
+   * to this split, so it has to be exactly the HTML ones: a title marked as
+   * HTML would go into the email unescaped.
+   */
+  test.each([
+    [
+      Event.SubscriberIncidentCreated,
+      ["resourcesAffected", "incidentDescription"],
+    ],
+    [
+      Event.SubscriberIncidentStateChanged,
+      ["resourcesAffected", "incidentDescription"],
+    ],
+    [Event.SubscriberIncidentNoteCreated, ["resourcesAffected", "note"]],
+    [Event.SubscriberIncidentNoteUpdated, ["resourcesAffected", "note"]],
+    [
+      Event.SubscriberIncidentPostmortemPublished,
+      ["resourcesAffected", "postmortemNote"],
+    ],
+    [
+      Event.SubscriberAnnouncementCreated,
+      ["resourcesAffected", "announcementDescription"],
+    ],
+    [
+      Event.SubscriberAnnouncementUpdated,
+      ["resourcesAffected", "announcementDescription"],
+    ],
+    [
+      Event.SubscriberScheduledMaintenanceCreated,
+      ["resourcesAffected", "scheduledMaintenanceDescription"],
+    ],
+    [
+      Event.SubscriberScheduledMaintenanceStateChanged,
+      ["resourcesAffected", "scheduledMaintenanceDescription"],
+    ],
+    [
+      Event.SubscriberScheduledMaintenanceNoteCreated,
+      ["resourcesAffected", "scheduledMaintenanceDescription", "note"],
+    ],
+    [
+      Event.SubscriberScheduledMaintenanceNoteUpdated,
+      ["resourcesAffected", "scheduledMaintenanceDescription", "note"],
+    ],
+    [
+      Event.SubscriberEpisodeCreated,
+      ["resourcesAffected", "episodeDescription"],
+    ],
+    [Event.SubscriberEpisodeStateChanged, ["resourcesAffected"]],
+    [Event.SubscriberEpisodeNoteCreated, ["resourcesAffected", "note"]],
+    [Event.SubscriberEpisodeNoteUpdated, ["resourcesAffected", "note"]],
+    [Event.SubscriberSubscriptionConfirmation, []],
+    [Event.SubscriberSubscribed, []],
+    [Event.SubscriberManageSubscription, []],
+  ] as Array<[StatusPageSubscriberNotificationEventType, Array<string>]>)(
+    "%s marks exactly its HTML variables as HTML in an email body",
+    (
+      event: StatusPageSubscriberNotificationEventType,
+      htmlVariables: Array<string>,
+    ) => {
+      expect(
+        [
+          ...SubscriberNotificationTemplateVariables.getEmailBodyHtmlVariableNamesForEventType(
+            event,
+          ),
+        ].sort(),
+      ).toEqual([...htmlVariables].sort());
+    },
+  );
+
+  test.each(ALL_EVENTS)(
+    "%s never marks a title, name, severity, state, time or URL as HTML",
+    (event: StatusPageSubscriberNotificationEventType) => {
+      for (const name of SubscriberNotificationTemplateVariables.getEmailBodyHtmlVariableNamesForEventType(
+        event,
+      )) {
+        expect(name).not.toMatch(
+          /Title$|Name$|Severity$|State$|Url$|At$|Time$/,
+        );
+      }
+    },
+  );
+
+  /*
+   * The incident custom fields: one variable per field, by the field's
+   * Template Variable key, so they are listed as a family by prefix.
+   */
+  describe("the custom field variables", () => {
+    test.each(INCIDENT_EVENTS)(
+      "%s offers {{customFields.<key>}}",
+      (event: StatusPageSubscriberNotificationEventType) => {
+        const dynamic: Array<SubscriberNotificationTemplateDynamicVariable> =
+          SubscriberNotificationTemplateVariables.getDynamicVariablesForEventType(
+            event,
+          );
+
+        expect(
+          dynamic.map(
+            (variable: SubscriberNotificationTemplateDynamicVariable) => {
+              return [variable.prefix, variable.placeholder];
+            },
+          ),
+        ).toEqual([["customFields.", "<key>"]]);
+        expect(dynamic[0]!.description).toMatch(/Internal/);
+        // A Rich text field's value is rendered Markdown in an email body.
+        expect(dynamic[0]!.mayBeHtmlInEmailBody).toBe(true);
+      },
+    );
+
+    test.each(
+      ALL_EVENTS.filter(
+        (event: StatusPageSubscriberNotificationEventType): boolean => {
+          return !INCIDENT_EVENTS.includes(event);
+        },
+      ),
+    )(
+      "%s offers no custom fields",
+      (event: StatusPageSubscriberNotificationEventType) => {
+        expect(
+          SubscriberNotificationTemplateVariables.getDynamicVariablesForEventType(
+            event,
+          ),
+        ).toEqual([]);
+        expect(
+          SubscriberNotificationTemplateVariables.isVariableOffered(
+            event,
+            "customFields.site",
+          ),
+        ).toBe(false);
+      },
+    );
+
+    test.each([
+      ["customFields.site", true],
+      ["customFields.affected_location_2", true],
+      ["customFields.", false],
+      ["customFields.Site", false],
+      ["customFields.site-name", false],
+      ["customFields.site.name", false],
+      ["customFields._site", false],
+      ["customFieldssite", false],
+      ["incidentTitle", true],
+      ["affectedStatusPages", true],
+      ["episodeTitle", false],
+    ] as Array<[string, boolean]>)(
+      "an incident template can use {{%s}}: %s",
+      (name: string, offered: boolean) => {
+        expect(
+          SubscriberNotificationTemplateVariables.isVariableOffered(
+            Event.SubscriberIncidentCreated,
+            name,
+          ),
+        ).toBe(offered);
+      },
+    );
+
+    test("a listed variable is not taken for a custom field", () => {
+      expect(
+        SubscriberNotificationTemplateVariables.getDynamicVariableForName(
+          Event.SubscriberIncidentCreated,
+          "incidentTitle",
+        ),
+      ).toBeNull();
+      expect(
+        SubscriberNotificationTemplateVariables.getDynamicVariableForName(
+          Event.SubscriberIncidentCreated,
+          "customFields.site",
+        )?.prefix,
+      ).toBe("customFields.");
+    });
+
+    test("returns a new list each time", () => {
+      const first: Array<SubscriberNotificationTemplateDynamicVariable> =
+        SubscriberNotificationTemplateVariables.getDynamicVariablesForEventType(
+          Event.SubscriberIncidentCreated,
+        );
+      first[0]!.prefix = "changed.";
+
+      expect(
+        SubscriberNotificationTemplateVariables.getDynamicVariablesForEventType(
+          Event.SubscriberIncidentCreated,
+        )[0]!.prefix,
+      ).toBe("customFields.");
+    });
+
+    test.each(INCIDENT_EVENTS)(
+      "%s marks the affected status pages and labels as plain text",
+      (event: StatusPageSubscriberNotificationEventType) => {
+        const html: Array<string> =
+          SubscriberNotificationTemplateVariables.getEmailBodyHtmlVariableNamesForEventType(
+            event,
+          );
+
+        expect(html).not.toContain("affectedStatusPages");
+        expect(html).not.toContain("incidentLabels");
+      },
+    );
+
+    test.each(INCIDENT_EVENTS)(
+      "%s warns that the affected status pages are internal",
+      (event: StatusPageSubscriberNotificationEventType) => {
+        const affected: SubscriberNotificationTemplateVariable | undefined =
+          SubscriberNotificationTemplateVariables.getAvailableVariablesForEventType(
+            event,
+          ).find((variable: SubscriberNotificationTemplateVariable) => {
+            return variable.name === "affectedStatusPages";
+          });
+
+        expect(affected?.description).toMatch(/Internal/);
+      },
+    );
+  });
+
   test("the report documents its structured fields rather than flat values", () => {
     const report: Array<string> = names(Event.SubscriberReport);
 
@@ -215,3 +474,68 @@ describe("SubscriberNotificationTemplateVariables", () => {
     expect(report).toContain("report.rows");
   });
 });
+
+/*
+ * The placeholders that read the team's incident records - labels and custom
+ * fields - which only someone who may read incidents may place in a
+ * template (SubscriberTemplateIncidentRecordAccess). Everything else a
+ * template offers is on the status page already.
+ */
+describe("SubscriberNotificationTemplateVariables.getIncidentRecordPlaceholders", () => {
+  test("finds labels and every custom field placeholder, each once, sorted", () => {
+    expect(
+      SubscriberNotificationTemplateVariables.getIncidentRecordPlaceholders([
+        "<p>{{ customFields.root_cause }} {{incidentLabels}}</p>",
+        "{{customFields.customer_account}} {{customFields.root_cause}}",
+        null,
+        undefined,
+      ]),
+    ).toEqual([
+      "customFields.customer_account",
+      "customFields.root_cause",
+      "incidentLabels",
+    ]);
+  });
+
+  test("a guessed key counts, whether or not such a field exists", () => {
+    expect(
+      SubscriberNotificationTemplateVariables.getIncidentRecordPlaceholders([
+        "{{customFields.a}}{{customFields.b_2}}",
+      ]),
+    ).toEqual(["customFields.a", "customFields.b_2"]);
+  });
+
+  test("what the status page shows does not count", () => {
+    const publicVariables: Array<string> = Array.from(
+      new Set(
+        ALL_EVENTS.flatMap(
+          (event: StatusPageSubscriberNotificationEventType) => {
+            return names(event);
+          },
+        ),
+      ),
+    ).filter((name: string) => {
+      return name !== "incidentLabels";
+    });
+
+    expect(
+      SubscriberNotificationTemplateVariables.getIncidentRecordPlaceholders([
+        publicVariables
+          .map((name: string) => {
+            return `{{${name}}}`;
+          })
+          .join(" "),
+      ]),
+    ).toEqual([]);
+    expect(publicVariables).toContain("affectedStatusPages");
+    expect(publicVariables).toContain("incidentTitle");
+  });
+
+  test("only what the compiler would fill: other spellings are left as written", () => {
+    expect(
+      SubscriberNotificationTemplateVariables.getIncidentRecordPlaceholders([
+        "{customFields.a} {{customFields.a-b}} {{ customfields.a }} {{incidentlabels}}",
+      ]),
+    ).toEqual([]);
+  });
+});

package/Tests/Types/StatusPage/SubscriberUpdateNotification.test.ts

@@ -106,19 +106,26 @@ describe("SubscriberUpdateNotification.isRequested", () => {
 });
 
 describe("SubscriberUpdateNotification.getSkipReasonForOriginalNotificationStatus", () => {
-  test.each([
-    StatusPageSubscriberNotificationStatus.Pending,
-    StatusPageSubscriberNotificationStatus.InProgress,
-  ])(
-    "skips while the original notification is %s, because it will carry the edit",
-    (status: StatusPageSubscriberNotificationStatus) => {
-      expect(
-        SubscriberUpdateNotification.getSkipReasonForOriginalNotificationStatus(
-          status,
-        ),
-      ).toBe(SubscriberUpdateNotification.notYetNotifiedMessage);
-    },
-  );
+  test("skips while the original notification is Pending, because it will carry the edit", () => {
+    expect(
+      SubscriberUpdateNotification.getSkipReasonForOriginalNotificationStatus(
+        StatusPageSubscriberNotificationStatus.Pending,
+      ),
+    ).toBe(SubscriberUpdateNotification.notYetNotifiedMessage);
+  });
+
+  /*
+   * A send in progress read the item before the edit and goes on with what
+   * it read: skipping the update would leave subscribers with the old text.
+   * It waits instead (isOriginalNotificationBeingSent).
+   */
+  test("does not skip while the original notification is InProgress: that send may carry the text from before the edit", () => {
+    expect(
+      SubscriberUpdateNotification.getSkipReasonForOriginalNotificationStatus(
+        StatusPageSubscriberNotificationStatus.InProgress,
+      ),
+    ).toBeNull();
+  });
 
   test.each([
     StatusPageSubscriberNotificationStatus.Success,
@@ -198,3 +205,43 @@ describe("SubscriberNotificationTrigger", () => {
     ]);
   });
 });
+
+describe("SubscriberUpdateNotification.isOriginalNotificationBeingSent", () => {
+  test("waits while the original notification is InProgress", () => {
+    expect(
+      SubscriberUpdateNotification.isOriginalNotificationBeingSent(
+        StatusPageSubscriberNotificationStatus.InProgress,
+      ),
+    ).toBe(true);
+  });
+
+  test.each([
+    StatusPageSubscriberNotificationStatus.Pending,
+    StatusPageSubscriberNotificationStatus.Success,
+    StatusPageSubscriberNotificationStatus.Skipped,
+    StatusPageSubscriberNotificationStatus.Failed,
+    undefined,
+    null,
+  ])("does not wait once it is %s", (status: unknown) => {
+    expect(
+      SubscriberUpdateNotification.isOriginalNotificationBeingSent(
+        status as StatusPageSubscriberNotificationStatus,
+      ),
+    ).toBe(false);
+  });
+
+  test("never both waits and skips: every status has one decision", () => {
+    for (const status of Object.values(
+      StatusPageSubscriberNotificationStatus,
+    )) {
+      const waits: boolean =
+        SubscriberUpdateNotification.isOriginalNotificationBeingSent(status);
+      const skips: boolean =
+        SubscriberUpdateNotification.getSkipReasonForOriginalNotificationStatus(
+          status,
+        ) !== null;
+
+      expect(waits && skips).toBe(false);
+    }
+  });
+});