@oneuptime/common 14.0.6 → 14.0.8

package/Types/StatusPage/SubscriberNotificationTemplatePreview.ts

@@ -0,0 +1,301 @@
+import SafeHtml from "../SafeHtml";
+import StatusPageSubscriberNotificationEventType from "./StatusPageSubscriberNotificationEventType";
+import StatusPageSubscriberNotificationMethod from "./StatusPageSubscriberNotificationMethod";
+import SubscriberNotificationPreview from "./SubscriberNotificationPreview";
+import SubscriberNotificationTemplateCompiler, {
+  SubscriberNotificationEmailBodyTemplateVariables,
+  SubscriberNotificationTextTemplateVariables,
+} from "./SubscriberNotificationTemplateCompiler";
+import SubscriberNotificationTemplateVariables, {
+  SubscriberNotificationTemplateDynamicVariable,
+  SubscriberNotificationTemplateVariable,
+} from "./SubscriberNotificationTemplateVariables";
+
+/*
+ * The live preview of a custom subscriber notification template while it is
+ * written: the template filled with sample values, by the compiler the
+ * subscriber jobs fill it with (SubscriberNotificationTemplateCompiler).
+ *
+ * Each value comes in the format its channel gets it in, as the jobs give
+ * them: an email body gets HTML for the variables that are HTML there (a
+ * description, a note, the resource list) and every other value escaped;
+ * the subject and SMS get plain text; Slack and Teams get Markdown. So what
+ * the preview shows is what a template does with real values - including a
+ * placeholder the event does not offer, which is sent as written and is
+ * listed as such.
+ *
+ * The report template is the exception: it is rendered by the full
+ * Handlebars engine with a structured report, which placeholders cannot
+ * stand in for, so it has no preview.
+ *
+ * Kept free of React and of the server, so the dashboard renders it and
+ * tests can read it directly.
+ */
+
+// One sample value, in the three forms the channels take.
+interface SampleValue {
+  text: string;
+  markdown?: string | undefined;
+  // For a variable that is HTML in an email body.
+  html?: string | undefined;
+}
+
+const SAMPLE_STATUS_PAGE_URL: string = "https://status.example.com";
+
+const SAMPLE_VALUES: Record<string, SampleValue> = {
+  statusPageName: { text: "Acme Status" },
+  statusPageUrl: { text: SAMPLE_STATUS_PAGE_URL },
+  unsubscribeUrl: {
+    text: SubscriberNotificationPreview.getPreviewUnsubscribeUrl(
+      SAMPLE_STATUS_PAGE_URL,
+    ),
+  },
+  confirmationUrl: {
+    text: `${SAMPLE_STATUS_PAGE_URL}/confirm-subscription/sample`,
+  },
+  manageSubscriptionUrl: {
+    text: `${SAMPLE_STATUS_PAGE_URL}/update-subscription/sample`,
+  },
+  detailsUrl: { text: `${SAMPLE_STATUS_PAGE_URL}/incidents/sample` },
+  resourcesAffected: {
+    text: "Europe: Checkout API; Americas: Payments API",
+    html: "Europe: Checkout API<br/>Americas: Payments API",
+  },
+  incidentTitle: { text: "Checkout requests are failing" },
+  incidentDescription: {
+    text: "Customers in Europe cannot complete a checkout. We are investigating.",
+    markdown:
+      "Customers in **Europe** cannot complete a checkout. We are investigating.",
+    html: "<p>Customers in <strong>Europe</strong> cannot complete a checkout. We are investigating.</p>",
+  },
+  incidentSeverity: { text: "Major" },
+  incidentState: { text: "Identified" },
+  incidentLabels: { text: "Europe, Payments" },
+  affectedStatusPages: { text: "Acme Status, Acme Europe Status" },
+  postedAt: { text: "Sep 27, 2026, 10:30 AM UTC" },
+  note: {
+    text: "We found the cause and are rolling out a fix. Next update in 30 minutes.",
+    markdown:
+      "We found the cause and are rolling out a fix. **Next update in 30 minutes.**",
+    html: "<p>We found the cause and are rolling out a fix. <strong>Next update in 30 minutes.</strong></p>",
+  },
+  postmortemNote: {
+    text: "A configuration change overloaded the payment gateway. We have added a safeguard.",
+    markdown:
+      "A configuration change overloaded the payment gateway. We have added a **safeguard**.",
+    html: "<p>A configuration change overloaded the payment gateway. We have added a <strong>safeguard</strong>.</p>",
+  },
+  announcementTitle: { text: "New status page features" },
+  announcementDescription: {
+    text: "You can now choose which services you hear about.",
+    markdown: "You can now choose **which services** you hear about.",
+    html: "<p>You can now choose <strong>which services</strong> you hear about.</p>",
+  },
+  scheduledMaintenanceTitle: { text: "Database upgrade" },
+  scheduledMaintenanceDescription: {
+    text: "Checkout may be slow for up to ten minutes.",
+    markdown: "Checkout may be slow for up to **ten minutes**.",
+    html: "<p>Checkout may be slow for up to <strong>ten minutes</strong>.</p>",
+  },
+  scheduledMaintenanceState: { text: "Scheduled" },
+  scheduledStartTime: { text: "Sep 30, 2026, 02:00 AM UTC" },
+  scheduledEndTime: { text: "Sep 30, 2026, 03:00 AM UTC" },
+  episodeTitle: { text: "Checkout degradation" },
+  episodeDescription: {
+    text: "Several incidents are affecting checkout.",
+    markdown: "Several incidents are affecting **checkout**.",
+    html: "<p>Several incidents are affecting <strong>checkout</strong>.</p>",
+  },
+  episodeSeverity: { text: "Major" },
+  episodeState: { text: "Identified" },
+};
+
+export interface SubscriberNotificationTemplateSampleValues {
+  // An email template's body: HTML values as SafeHtml, the rest plain.
+  emailBody: SubscriberNotificationEmailBodyTemplateVariables;
+  // An email subject, SMS and webhook.
+  plainText: SubscriberNotificationTextTemplateVariables;
+  // Slack and Microsoft Teams.
+  markdown: SubscriberNotificationTextTemplateVariables;
+}
+
+export interface SubscriberNotificationTemplatePreviewResult {
+  // False when this event's templates cannot be previewed (the report).
+  isAvailable: boolean;
+  // Whether body is HTML (an email template's body).
+  isHtml: boolean;
+  // An email template's subject, filled in; null for other channels, or none.
+  subject: string | null;
+  body: string;
+  // Placeholders the event does not offer: they are sent as written.
+  unknownPlaceholders: Array<string>;
+}
+
+export default class SubscriberNotificationTemplatePreview {
+  public static isAvailableForEventType(
+    eventType: StatusPageSubscriberNotificationEventType | undefined,
+  ): boolean {
+    return (
+      Boolean(eventType) &&
+      Object.values(StatusPageSubscriberNotificationEventType).includes(
+        eventType!,
+      ) &&
+      eventType !== StatusPageSubscriberNotificationEventType.SubscriberReport
+    );
+  }
+
+  /*
+   * A sample for every variable the event offers, and for each custom field
+   * placeholder these templates place ({{customFields.<key>}}), in each
+   * channel's format.
+   */
+  public static getSampleValues(data: {
+    eventType: StatusPageSubscriberNotificationEventType;
+    templates: Array<string | null | undefined>;
+  }): SubscriberNotificationTemplateSampleValues {
+    const values: SubscriberNotificationTemplateSampleValues = {
+      emailBody: {},
+      plainText: {},
+      markdown: {},
+    };
+
+    for (const variable of SubscriberNotificationTemplateVariables.getAvailableVariablesForEventType(
+      data.eventType,
+    )) {
+      this.addSample({
+        values: values,
+        name: variable.name,
+        sample: SAMPLE_VALUES[variable.name] || {
+          text: `[${variable.name}]`,
+        },
+        isHtmlInEmailBody: this.isHtmlInEmailBody(variable),
+      });
+    }
+
+    for (const name of SubscriberNotificationTemplateCompiler.getPlaceholderNames(
+      data.templates,
+    )) {
+      const dynamicVariable: SubscriberNotificationTemplateDynamicVariable | null =
+        SubscriberNotificationTemplateVariables.getDynamicVariableForName(
+          data.eventType,
+          name,
+        );
+
+      if (!dynamicVariable) {
+        continue;
+      }
+
+      this.addSample({
+        values: values,
+        name: name,
+        sample: {
+          text: `Sample ${name.slice(dynamicVariable.prefix.length)}`,
+        },
+        isHtmlInEmailBody: false,
+      });
+    }
+
+    return values;
+  }
+
+  // The template, filled with sample values as its channel would be.
+  public static render(data: {
+    eventType: StatusPageSubscriberNotificationEventType | undefined;
+    notificationMethod: StatusPageSubscriberNotificationMethod | undefined;
+    templateBody: string | null | undefined;
+    emailSubject?: string | null | undefined;
+  }): SubscriberNotificationTemplatePreviewResult {
+    const isEmail: boolean =
+      data.notificationMethod === StatusPageSubscriberNotificationMethod.Email;
+    const templateBody: string = data.templateBody || "";
+    const emailSubject: string = (isEmail && data.emailSubject) || "";
+
+    if (!this.isAvailableForEventType(data.eventType)) {
+      return {
+        isAvailable: false,
+        isHtml: isEmail,
+        subject: null,
+        body: "",
+        unknownPlaceholders: [],
+      };
+    }
+
+    const eventType: StatusPageSubscriberNotificationEventType =
+      data.eventType!;
+
+    const values: SubscriberNotificationTemplateSampleValues =
+      this.getSampleValues({
+        eventType: eventType,
+        templates: [templateBody, emailSubject],
+      });
+
+    const unknownPlaceholders: Array<string> = Array.from(
+      SubscriberNotificationTemplateCompiler.getPlaceholderNames([
+        templateBody,
+        emailSubject,
+      ]),
+    )
+      .filter((name: string): boolean => {
+        return !SubscriberNotificationTemplateVariables.isVariableOffered(
+          eventType,
+          name,
+        );
+      })
+      .sort();
+
+    if (isEmail) {
+      return {
+        isAvailable: true,
+        isHtml: true,
+        subject: emailSubject
+          ? SubscriberNotificationTemplateCompiler.compileTemplate(
+              emailSubject,
+              values.plainText,
+            )
+          : null,
+        body: SubscriberNotificationTemplateCompiler.compileEmailBodyTemplate(
+          templateBody,
+          values.emailBody,
+        ),
+        unknownPlaceholders: unknownPlaceholders,
+      };
+    }
+
+    const isMarkdownChannel: boolean =
+      data.notificationMethod ===
+        StatusPageSubscriberNotificationMethod.Slack ||
+      data.notificationMethod ===
+        StatusPageSubscriberNotificationMethod.MicrosoftTeams;
+
+    return {
+      isAvailable: true,
+      isHtml: false,
+      subject: null,
+      body: SubscriberNotificationTemplateCompiler.compileTemplate(
+        templateBody,
+        isMarkdownChannel ? values.markdown : values.plainText,
+      ),
+      unknownPlaceholders: unknownPlaceholders,
+    };
+  }
+
+  private static isHtmlInEmailBody(
+    variable: SubscriberNotificationTemplateVariable,
+  ): boolean {
+    return variable.isHtmlInEmailBody === true;
+  }
+
+  private static addSample(data: {
+    values: SubscriberNotificationTemplateSampleValues;
+    name: string;
+    sample: SampleValue;
+    isHtmlInEmailBody: boolean;
+  }): void {
+    data.values.plainText[data.name] = data.sample.text;
+    data.values.markdown[data.name] = data.sample.markdown || data.sample.text;
+    data.values.emailBody[data.name] =
+      data.isHtmlInEmailBody && data.sample.html
+        ? SafeHtml.fromTrustedHtml(data.sample.html)
+        : data.sample.text;
+  }
+}

package/Types/StatusPage/SubscriberNotificationTemplateVariables.ts

@@ -1,11 +1,109 @@
+import {
+  CUSTOM_FIELD_TEMPLATE_VARIABLE_PREFIX,
+  isValidCustomFieldVariableKey,
+} from "../CustomField/CustomFieldVariableKey";
 import BadDataException from "../Exception/BadDataException";
 import StatusPageSubscriberNotificationEventType from "./StatusPageSubscriberNotificationEventType";
+import SubscriberNotificationTemplateCompiler from "./SubscriberNotificationTemplateCompiler";
 
 export interface SubscriberNotificationTemplateVariable {
   name: string;
   description: string;
+  /*
+   * In the body of an EMAIL template this variable is HTML already (rendered
+   * Markdown, or the resource list built from escaped names) and goes in as
+   * it is. Every other variable is plain text there, and is HTML-escaped (see
+   * SubscriberNotificationTemplateCompiler). A subject, SMS, Slack and Teams
+   * get every variable as text, never as HTML.
+   */
+  isHtmlInEmailBody?: boolean;
 }
 
+/*
+ * A family of variables whose names are not known in advance: one per
+ * incident custom field, {{customFields.<key>}}, where <key> is the field's
+ * Template Variable key (IncidentCustomField.variableKey). Which keys exist
+ * depends on the project, so the family is listed by its prefix, and the
+ * worker passes one variable for every field the project has - an empty
+ * string when the incident holds no value for it.
+ */
+export interface SubscriberNotificationTemplateDynamicVariable {
+  // What every name in the family starts with, dot included.
+  prefix: string;
+  // How the rest of the name is shown in the reference: "<key>".
+  placeholder: string;
+  // Whether what follows the prefix is a name in the family.
+  isValidKey: (key: string) => boolean;
+  description: string;
+  /*
+   * Some members are HTML in an email body - a Rich text field's rendered
+   * Markdown, a Long text field's lines, a Date and time field's time
+   * zones - and the rest are plain text, which is escaped there.
+   */
+  mayBeHtmlInEmailBody?: boolean;
+}
+
+/*
+ * The variables every incident event offers on top of its own: the
+ * incident's labels, the status pages it is on, and its custom fields.
+ *
+ * affectedStatusPages and the custom fields are internal data - a status
+ * page's subscribers are usually outside the team, and the list of pages
+ * names every other audience the incident reaches - so the worker never puts
+ * them into a message on its own. They reach subscribers only where a
+ * template author places them, and the template form warns about it.
+ */
+const INCIDENT_VARIABLES: Array<SubscriberNotificationTemplateVariable> = [
+  {
+    name: "incidentLabels",
+    description: "Labels of the incident, separated by commas",
+  },
+  {
+    name: "affectedStatusPages",
+    description:
+      "Names of every status page the incident is shown on, separated by commas. Internal: it names the status pages of every audience the incident reaches",
+  },
+];
+
+const INCIDENT_DYNAMIC_VARIABLES: Array<SubscriberNotificationTemplateDynamicVariable> =
+  [
+    {
+      prefix: CUSTOM_FIELD_TEMPLATE_VARIABLE_PREFIX,
+      placeholder: "<key>",
+      isValidKey: isValidCustomFieldVariableKey,
+      description:
+        "The value of an incident custom field, by the field's Template Variable key. Internal: any custom field can be placed, whether or not it is marked to be included in subscriber notifications",
+      mayBeHtmlInEmailBody: true,
+    },
+  ];
+
+/*
+ * The variables that read the team's own incident records rather than what
+ * the incident's status pages already show: its labels, and every custom
+ * field ({{customFields.<key>}}), marked for subscribers or not. The title,
+ * description, severity, state and public notes are on the status page for
+ * anyone who can see it; these are not, and the status page roles that may
+ * write templates may not read them. So a template can place them only if
+ * whoever writes it may read them (Server/Utils/StatusPage/
+ * SubscriberTemplateIncidentRecordAccess).
+ *
+ * {{affectedStatusPages}} is not one of them: it names status pages, which
+ * the same roles read.
+ */
+const INCIDENT_RECORD_VARIABLE_NAMES: ReadonlyArray<string> = [
+  "incidentLabels",
+];
+
+// The incident events, which offer INCIDENT_VARIABLES and the custom fields.
+const INCIDENT_EVENT_TYPES: ReadonlyArray<StatusPageSubscriberNotificationEventType> =
+  [
+    StatusPageSubscriberNotificationEventType.SubscriberIncidentCreated,
+    StatusPageSubscriberNotificationEventType.SubscriberIncidentStateChanged,
+    StatusPageSubscriberNotificationEventType.SubscriberIncidentNoteCreated,
+    StatusPageSubscriberNotificationEventType.SubscriberIncidentNoteUpdated,
+    StatusPageSubscriberNotificationEventType.SubscriberIncidentPostmortemPublished,
+  ];
+
 /*
  * The variables a custom status page subscriber notification template can use
  * for each event type, as {{variableName}}.
@@ -38,7 +136,11 @@ export default class SubscriberNotificationTemplateVariables {
 
     const commonVariables: Array<SubscriberNotificationTemplateVariable> = [
       ...statusPageVariables,
-      { name: "resourcesAffected", description: "List of affected resources" },
+      {
+        name: "resourcesAffected",
+        description: "List of affected resources",
+        isHtmlInEmailBody: true,
+      },
     ];
 
     switch (eventType) {
@@ -72,9 +174,11 @@ export default class SubscriberNotificationTemplateVariables {
           {
             name: "incidentDescription",
             description: "Description of the incident",
+            isHtmlInEmailBody: true,
           },
           { name: "incidentSeverity", description: "Severity of the incident" },
           { name: "detailsUrl", description: "URL to view incident details" },
+          ...INCIDENT_VARIABLES,
         ];
 
       case StatusPageSubscriberNotificationEventType.SubscriberIncidentStateChanged:
@@ -84,6 +188,7 @@ export default class SubscriberNotificationTemplateVariables {
           {
             name: "incidentDescription",
             description: "Description of the incident",
+            isHtmlInEmailBody: true,
           },
           { name: "incidentSeverity", description: "Severity of the incident" },
           {
@@ -91,6 +196,7 @@ export default class SubscriberNotificationTemplateVariables {
             description: "Current state of the incident",
           },
           { name: "detailsUrl", description: "URL to view incident details" },
+          ...INCIDENT_VARIABLES,
         ];
 
       case StatusPageSubscriberNotificationEventType.SubscriberIncidentNoteCreated:
@@ -104,8 +210,13 @@ export default class SubscriberNotificationTemplateVariables {
             description: "Current state of the incident",
           },
           { name: "postedAt", description: "When the note was posted" },
-          { name: "note", description: "Content of the note" },
+          {
+            name: "note",
+            description: "Content of the note",
+            isHtmlInEmailBody: true,
+          },
           { name: "detailsUrl", description: "URL to view incident details" },
+          ...INCIDENT_VARIABLES,
         ];
 
       case StatusPageSubscriberNotificationEventType.SubscriberIncidentPostmortemPublished:
@@ -116,8 +227,10 @@ export default class SubscriberNotificationTemplateVariables {
           {
             name: "postmortemNote",
             description: "Content of the postmortem note",
+            isHtmlInEmailBody: true,
           },
           { name: "detailsUrl", description: "URL to view incident details" },
+          ...INCIDENT_VARIABLES,
         ];
 
       case StatusPageSubscriberNotificationEventType.SubscriberAnnouncementCreated:
@@ -131,6 +244,7 @@ export default class SubscriberNotificationTemplateVariables {
           {
             name: "announcementDescription",
             description: "Description of the announcement",
+            isHtmlInEmailBody: true,
           },
           {
             name: "detailsUrl",
@@ -148,6 +262,7 @@ export default class SubscriberNotificationTemplateVariables {
           {
             name: "scheduledMaintenanceDescription",
             description: "Description of the scheduled maintenance",
+            isHtmlInEmailBody: true,
           },
           {
             name: "scheduledStartTime",
@@ -173,6 +288,7 @@ export default class SubscriberNotificationTemplateVariables {
           {
             name: "scheduledMaintenanceDescription",
             description: "Description of the scheduled maintenance",
+            isHtmlInEmailBody: true,
           },
           {
             name: "scheduledMaintenanceState",
@@ -195,13 +311,18 @@ export default class SubscriberNotificationTemplateVariables {
           {
             name: "scheduledMaintenanceDescription",
             description: "Description of the scheduled maintenance",
+            isHtmlInEmailBody: true,
           },
           {
             name: "scheduledMaintenanceState",
             description: "Current state of the scheduled maintenance",
           },
           { name: "postedAt", description: "When the note was posted" },
-          { name: "note", description: "Content of the note" },
+          {
+            name: "note",
+            description: "Content of the note",
+            isHtmlInEmailBody: true,
+          },
           {
             name: "detailsUrl",
             description: "URL to view scheduled maintenance details",
@@ -215,6 +336,7 @@ export default class SubscriberNotificationTemplateVariables {
           {
             name: "episodeDescription",
             description: "Description of the incident",
+            isHtmlInEmailBody: true,
           },
           { name: "episodeSeverity", description: "Severity of the incident" },
           { name: "detailsUrl", description: "URL to view incident details" },
@@ -238,7 +360,11 @@ export default class SubscriberNotificationTemplateVariables {
           ...commonVariables,
           { name: "episodeTitle", description: "Title of the incident" },
           { name: "episodeSeverity", description: "Severity of the incident" },
-          { name: "note", description: "Content of the note" },
+          {
+            name: "note",
+            description: "Content of the note",
+            isHtmlInEmailBody: true,
+          },
           { name: "detailsUrl", description: "URL to view incident details" },
         ];
 
@@ -319,6 +445,19 @@ export default class SubscriberNotificationTemplateVariables {
     }
   }
 
+  // The variables that are HTML, not plain text, in an email template's body.
+  public static getEmailBodyHtmlVariableNamesForEventType(
+    eventType: StatusPageSubscriberNotificationEventType,
+  ): Array<string> {
+    return this.getAvailableVariablesForEventType(eventType)
+      .filter((variable: SubscriberNotificationTemplateVariable): boolean => {
+        return variable.isHtmlInEmailBody === true;
+      })
+      .map((variable: SubscriberNotificationTemplateVariable): string => {
+        return variable.name;
+      });
+  }
+
   public static getVariableNamesForEventType(
     eventType: StatusPageSubscriberNotificationEventType,
   ): Array<string> {
@@ -328,4 +467,78 @@ export default class SubscriberNotificationTemplateVariables {
       },
     );
   }
+
+  /*
+   * The families of variables this event offers on top of the listed ones,
+   * by prefix: the incident events' {{customFields.<key>}}.
+   */
+  public static getDynamicVariablesForEventType(
+    eventType: StatusPageSubscriberNotificationEventType,
+  ): Array<SubscriberNotificationTemplateDynamicVariable> {
+    return INCIDENT_EVENT_TYPES.includes(eventType)
+      ? INCIDENT_DYNAMIC_VARIABLES.map(
+          (
+            variable: SubscriberNotificationTemplateDynamicVariable,
+          ): SubscriberNotificationTemplateDynamicVariable => {
+            return { ...variable };
+          },
+        )
+      : [];
+  }
+
+  /*
+   * The family this name belongs to, when it is one: the prefix followed by
+   * a key of the family's shape (for a custom field, the shape its Template
+   * Variable key is made in, which the template compiler fills). Null for a
+   * listed variable, a bare prefix, or a name the event does not offer.
+   */
+  public static getDynamicVariableForName(
+    eventType: StatusPageSubscriberNotificationEventType,
+    name: string,
+  ): SubscriberNotificationTemplateDynamicVariable | null {
+    for (const variable of this.getDynamicVariablesForEventType(eventType)) {
+      if (
+        name.startsWith(variable.prefix) &&
+        variable.isValidKey(name.slice(variable.prefix.length))
+      ) {
+        return variable;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * The placeholders in these texts - a template's body and email subject -
+   * that read the team's incident records (INCIDENT_RECORD_VARIABLE_NAMES
+   * and any {{customFields.<key>}}, whether or not such a field exists),
+   * each once, sorted. Found exactly as the compiler finds what it fills,
+   * whatever the template's event type: an update can change the event type
+   * without touching the text.
+   */
+  public static getIncidentRecordPlaceholders(
+    texts: Array<string | null | undefined>,
+  ): Array<string> {
+    return Array.from(
+      SubscriberNotificationTemplateCompiler.getPlaceholderNames(texts),
+    )
+      .filter((name: string): boolean => {
+        return (
+          INCIDENT_RECORD_VARIABLE_NAMES.includes(name) ||
+          name.startsWith(CUSTOM_FIELD_TEMPLATE_VARIABLE_PREFIX)
+        );
+      })
+      .sort();
+  }
+
+  // Whether a template for this event can use {{name}}.
+  public static isVariableOffered(
+    eventType: StatusPageSubscriberNotificationEventType,
+    name: string,
+  ): boolean {
+    return (
+      this.getVariableNamesForEventType(eventType).includes(name) ||
+      this.getDynamicVariableForName(eventType, name) !== null
+    );
+  }
 }

package/Types/StatusPage/SubscriberUpdateNotification.ts

@@ -63,27 +63,48 @@ export default class SubscriberUpdateNotification {
 
   /*
    * Returns why an update notification should not be sent given where the
-   * original ("posted") notification is, or null when it may go out.
+   * original ("posted") notification is, or null when it may go out - or
+   * wait (see isOriginalNotificationBeingSent).
    *
-   * While the original is still Pending or InProgress, subscribers have not
-   * heard of the item at all. The original notification reads the item when it
-   * is sent, so it already carries this edit - a second "updated" message
-   * about something they were never told about would only confuse them.
+   * While the original is still Pending, subscribers have not heard of the
+   * item at all, and the original will carry this edit: the edit changed the
+   * row's version, so the run that claims the original
+   * (SubscriberNotificationClaim, which checks the version it read) has read
+   * the item since. A second "updated" message about something they were
+   * never told about would only confuse them.
+   *
+   * InProgress is different: that send read the item before it claimed it,
+   * and goes on with what it read, so it may carry the text from before the
+   * edit - a typo fixed, or an ETA corrected, right after posting is exactly
+   * that case. The update waits for it instead
+   * (isOriginalNotificationBeingSent), and goes out once it has settled.
    *
    * Every settled state lets the update through: Success is the normal case,
-   * and Skipped or Failed mean subscribers were not told originally, which the
-   * editor is now explicitly asking to do.
+   * and Skipped or Failed mean subscribers were not told originally (or not
+   * all of them), which the editor is now explicitly asking to do.
    */
   public static getSkipReasonForOriginalNotificationStatus(
     originalStatus: StatusPageSubscriberNotificationStatus | undefined | null,
   ): string | null {
-    if (
-      originalStatus === StatusPageSubscriberNotificationStatus.Pending ||
-      originalStatus === StatusPageSubscriberNotificationStatus.InProgress
-    ) {
+    if (originalStatus === StatusPageSubscriberNotificationStatus.Pending) {
       return this.notYetNotifiedMessage;
     }
 
     return null;
   }
+
+  /*
+   * Whether the update notification waits: the original ("posted")
+   * notification is being sent right now, with the item as it was read
+   * before the edit. The update is left Pending, untouched, and the job
+   * decides again on a later run, once the original has settled - then it
+   * goes out, since subscribers may have been sent the text from before the
+   * edit. A send that never settles is failed by the sweeper
+   * (StatusPageSubscriber:TimeoutStuckNotifications), which lets it through.
+   */
+  public static isOriginalNotificationBeingSent(
+    originalStatus: StatusPageSubscriberNotificationStatus | undefined | null,
+  ): boolean {
+    return originalStatus === StatusPageSubscriberNotificationStatus.InProgress;
+  }
 }