@oneuptime/common 14.0.6 → 14.0.8

package/Types/StatusPage/SubscriberNotificationPreview.ts

@@ -0,0 +1,322 @@
+import URL from "../API/URL";
+import { JSONObject } from "../JSON";
+import IncidentSubscriberAudience, {
+  IncidentSubscriberAudienceCounts,
+  IncidentSubscriberAudienceResult,
+} from "./IncidentSubscriberAudience";
+import StatusPageSubscriberUnsubscribe from "./StatusPageSubscriberUnsubscribe";
+
+/*
+ * "Preview notification" and "Send test to me": the email a status page's
+ * subscribers would get about an incident, shown before anything is sent -
+ * on the last step of declaring an incident, and while a public note is being
+ * written.
+ *
+ * The server (App/FeatureSet/Notification/API/SubscriberNotificationPreview)
+ * builds each page's email through SubscriberIncidentEmailBuilder, the one
+ * code path the subscriber jobs send through, and renders it with the mailer's
+ * own MailService.render. So the subject and HTML shown here are the ones a
+ * subscriber gets, apart from one thing: every subscriber's unsubscribe link
+ * carries their own token, which a preview has no subscriber to take it from,
+ * so the preview's link is a sample (getPreviewUnsubscribeUrl).
+ *
+ * Only counts ever leave the server: no subscriber address is read out.
+ *
+ * Everything here is shared by the server, which answers, and the dashboard,
+ * which asks and shows, so the two cannot drift apart.
+ */
+
+// Which email is previewed.
+export enum SubscriberNotificationPreviewEvent {
+  // "Incident created", for an incident that is being declared.
+  IncidentCreated = "IncidentCreated",
+  // "Incident update", for a public note being written on an incident.
+  IncidentPublicNoteCreated = "IncidentPublicNoteCreated",
+}
+
+/*
+ * Why a status page's subscribers get the email they get. The jobs use the
+ * page's custom email template only when it has a body and the page sends
+ * through its own SMTP server; everything else gets the default email.
+ */
+export enum SubscriberEmailTemplateChoiceReason {
+  // The page's custom template, sent through the page's own SMTP server.
+  CustomTemplate = "CustomTemplate",
+  // No custom email template is linked to the page for this event.
+  NoCustomTemplate = "NoCustomTemplate",
+  // A custom template is linked, but the page has no SMTP server of its own.
+  CustomTemplateNeedsCustomSmtp = "CustomTemplateNeedsCustomSmtp",
+  // A custom template is linked, but its body is empty.
+  CustomTemplateIsEmpty = "CustomTemplateIsEmpty",
+}
+
+export interface SubscriberEmailTemplateChoice {
+  usesCustomTemplate: boolean;
+  reason: SubscriberEmailTemplateChoiceReason;
+  // The linked custom template's name, when there is one (used or not).
+  customTemplateName?: string | undefined;
+}
+
+// Why nothing will be sent, whatever the email would look like.
+export enum SubscriberNotificationPreviewNothingSentReason {
+  // No monitor: subscribers hear about an incident through its monitors.
+  NoMonitors = "NoMonitors",
+  // The incident exists and is hidden from status pages (or private).
+  HiddenFromStatusPages = "HiddenFromStatusPages",
+  // The incident being declared is private.
+  PrivateIncident = "PrivateIncident",
+  // 'Notify Status Page Subscribers' is off on the incident being declared.
+  NotifyOff = "NotifyOff",
+  // No status page that lists its monitors will show it.
+  NoStatusPages = "NoStatusPages",
+}
+
+// One status page's email, as its subscribers would get it.
+export interface SubscriberNotificationPreviewStatusPage {
+  statusPageId: string;
+  name: string;
+  // The audience summary's "up to" counts, per channel (IncidentSubscriberAudience).
+  subscriberCounts: IncidentSubscriberAudienceCounts;
+  subject: string;
+  html: string;
+  templateChoice: SubscriberEmailTemplateChoice;
+}
+
+export interface SubscriberNotificationPreviewResult {
+  event: SubscriberNotificationPreviewEvent;
+  /*
+   * Set when nothing will be sent at all; there are no emails to show then.
+   * Null when at least one status page will be sent the email.
+   */
+  nothingSentReason: SubscriberNotificationPreviewNothingSentReason | null;
+  /*
+   * The pages that will be sent the email that the caller can see, in name
+   * order. A page the caller cannot read is neither named nor previewed: it
+   * is counted in audience.hiddenStatusPageCount.
+   */
+  statusPages: Array<SubscriberNotificationPreviewStatusPage>;
+  // Who will be told, as the "Will notify" summary shows it.
+  audience: IncidentSubscriberAudienceResult;
+}
+
+/*
+ * The fields of the Declare Incident form that reach the 'incident created'
+ * email. The email shows no state, so the state is not asked for.
+ */
+export interface SubscriberNotificationPreviewIncidentDraft {
+  title: string;
+  description: string;
+  incidentSeverityId: string | null;
+  monitorIds: Array<string>;
+  statusPageIds: Array<string>;
+  labelIds: Array<string>;
+  // The custom field values, by field name, as the incident would store them.
+  customFields: JSONObject;
+  isPrivate: boolean;
+  shouldStatusPageSubscribersBeNotifiedOnIncidentCreated: boolean;
+}
+
+export type SubscriberNotificationPreviewRequest =
+  | {
+      event: SubscriberNotificationPreviewEvent.IncidentCreated;
+      incident: SubscriberNotificationPreviewIncidentDraft;
+    }
+  | {
+      event: SubscriberNotificationPreviewEvent.IncidentPublicNoteCreated;
+      incidentId: string;
+      // The note being written, as Markdown.
+      note: string;
+      // When the note will say it was posted; null means now.
+      postedAt: Date | null;
+    };
+
+// "Send test to me": one page's email, sent to the caller's own address.
+export type SubscriberNotificationSendTestRequest =
+  SubscriberNotificationPreviewRequest & {
+    statusPageId: string;
+  };
+
+export interface SubscriberNotificationSendTestResult {
+  // The caller's own account email, where the test went.
+  sentTo: string;
+}
+
+export default class SubscriberNotificationPreview {
+  // Where the router is mounted, under the notification API.
+  public static readonly routerPath: string =
+    "/subscriber-notification-preview";
+
+  public static readonly previewPath: string = "/preview";
+
+  public static readonly sendTestPath: string = "/send-test";
+
+  // The longest note or description a preview takes.
+  public static readonly maxTextLength: number = 100000;
+
+  // The longest title a preview takes.
+  public static readonly maxTitleLength: number = 1000;
+
+  /*
+   * The most custom field values an incident being previewed carries, and
+   * how long they may be together, written out as JSON. Each value is
+   * rendered, Markdown included, and goes into every page's email, so
+   * without a bound one request could make the server render as much as it
+   * can be sent. A project's own fields fit many times over.
+   */
+  public static readonly maxCustomFieldCount: number = 250;
+
+  public static readonly maxCustomFieldsLength: number = 200000;
+
+  // What a test email's subject starts with, so it reads as a test.
+  public static readonly testEmailSubjectPrefix: string = "[Test] ";
+
+  /*
+   * The unsubscribe link a preview and a test email carry. A subscriber's
+   * real link carries its own token (StatusPageSubscriberUnsubscribe), which
+   * a preview has no subscriber for, so this one names no subscription: the
+   * status page opens it as an out-of-date link and changes nothing.
+   */
+  public static getPreviewUnsubscribeUrl(statusPageUrl: string): string {
+    return URL.fromString(statusPageUrl)
+      .addRoute(
+        `/${StatusPageSubscriberUnsubscribe.PAGE_ROUTE_SEGMENT}/preview`,
+      )
+      .toString();
+  }
+
+  public static toJSON(
+    result: SubscriberNotificationPreviewResult,
+  ): JSONObject {
+    return {
+      event: result.event,
+      nothingSentReason: result.nothingSentReason,
+      statusPages: result.statusPages.map(
+        (statusPage: SubscriberNotificationPreviewStatusPage): JSONObject => {
+          return {
+            statusPageId: statusPage.statusPageId,
+            name: statusPage.name,
+            subscriberCounts: { ...statusPage.subscriberCounts },
+            subject: statusPage.subject,
+            html: statusPage.html,
+            templateChoice: {
+              usesCustomTemplate: statusPage.templateChoice.usesCustomTemplate,
+              reason: statusPage.templateChoice.reason,
+              customTemplateName:
+                statusPage.templateChoice.customTemplateName || null,
+            },
+          };
+        },
+      ),
+      audience: IncidentSubscriberAudience.toJSON(result.audience),
+    };
+  }
+
+  /*
+   * The server's answer as the dashboard receives it. Read defensively: a
+   * field that is missing or of the wrong type reads as "nothing", so a
+   * preview can never break the form it opens from.
+   */
+  public static fromJSON(
+    json: JSONObject,
+  ): SubscriberNotificationPreviewResult {
+    const events: Array<string> = Object.values(
+      SubscriberNotificationPreviewEvent,
+    );
+    const reasons: Array<string> = Object.values(
+      SubscriberNotificationPreviewNothingSentReason,
+    );
+    const choiceReasons: Array<string> = Object.values(
+      SubscriberEmailTemplateChoiceReason,
+    );
+
+    const statusPagesJson: Array<JSONObject> = Array.isArray(
+      json["statusPages"],
+    )
+      ? ((json["statusPages"] as Array<unknown>).filter(
+          (item: unknown): boolean => {
+            return Boolean(item) && typeof item === "object";
+          },
+        ) as Array<JSONObject>)
+      : [];
+
+    return {
+      event: events.includes(String(json["event"]))
+        ? (json["event"] as SubscriberNotificationPreviewEvent)
+        : SubscriberNotificationPreviewEvent.IncidentCreated,
+      nothingSentReason: reasons.includes(String(json["nothingSentReason"]))
+        ? (json[
+            "nothingSentReason"
+          ] as SubscriberNotificationPreviewNothingSentReason)
+        : null,
+      statusPages: statusPagesJson.map(
+        (item: JSONObject): SubscriberNotificationPreviewStatusPage => {
+          const choice: JSONObject =
+            (item["templateChoice"] as JSONObject | undefined) || {};
+
+          return {
+            statusPageId: String(item["statusPageId"] || ""),
+            name: String(item["name"] || ""),
+            subscriberCounts: IncidentSubscriberAudience.countsFromJSON(
+              item["subscriberCounts"],
+            ),
+            subject: String(item["subject"] || ""),
+            html: String(item["html"] || ""),
+            templateChoice: {
+              usesCustomTemplate: choice["usesCustomTemplate"] === true,
+              reason: choiceReasons.includes(String(choice["reason"]))
+                ? (choice["reason"] as SubscriberEmailTemplateChoiceReason)
+                : SubscriberEmailTemplateChoiceReason.NoCustomTemplate,
+              customTemplateName:
+                typeof choice["customTemplateName"] === "string" &&
+                choice["customTemplateName"]
+                  ? choice["customTemplateName"]
+                  : undefined,
+            },
+          };
+        },
+      ),
+      audience: IncidentSubscriberAudience.fromJSON(
+        (json["audience"] as JSONObject | undefined) || {},
+      ),
+    };
+  }
+
+  // A request as it travels: the dates as ISO strings.
+  public static requestToJSON(
+    request:
+      | SubscriberNotificationPreviewRequest
+      | SubscriberNotificationSendTestRequest,
+  ): JSONObject {
+    const json: JSONObject = {
+      event: request.event,
+    };
+
+    if (request.event === SubscriberNotificationPreviewEvent.IncidentCreated) {
+      json["incident"] = {
+        title: request.incident.title,
+        description: request.incident.description,
+        incidentSeverityId: request.incident.incidentSeverityId,
+        monitorIds: [...request.incident.monitorIds],
+        statusPageIds: [...request.incident.statusPageIds],
+        labelIds: [...request.incident.labelIds],
+        customFields: { ...request.incident.customFields },
+        isPrivate: request.incident.isPrivate,
+        shouldStatusPageSubscribersBeNotifiedOnIncidentCreated:
+          request.incident
+            .shouldStatusPageSubscribersBeNotifiedOnIncidentCreated,
+      };
+    } else {
+      json["incidentId"] = request.incidentId;
+      json["note"] = request.note;
+      json["postedAt"] = request.postedAt
+        ? request.postedAt.toISOString()
+        : null;
+    }
+
+    if ("statusPageId" in request && request.statusPageId) {
+      json["statusPageId"] = request.statusPageId;
+    }
+
+    return json;
+  }
+}

package/Types/StatusPage/SubscriberNotificationResend.ts

@@ -0,0 +1,132 @@
+import StatusPageSubscriberNotificationStatus from "./StatusPageSubscriberNotificationStatus";
+
+/*
+ * Sending a status page subscriber notification again: an incident public
+ * note's, or the notification that an incident was created.
+ *
+ * A notification is sent again by putting its status back to Pending; the
+ * job that sends it picks up Pending rows. What that reaches differs:
+ *
+ * - a public note (and a state change) is sent to every status page the
+ *   incident reaches now, including the pages that were sent it before;
+ * - the incident-created notification keeps a record of the pages it was
+ *   sent to in full (Incident.statusPagesNotifiedOnCreation). Retry after a
+ *   failure resumes after them; Resend after a success, and 'Resend to all
+ *   pages' after a failure (IncidentCreatedResend), empty the record so every
+ *   page is sent it again.
+ *
+ * Which of the two a settled notification offers is decided here, so the
+ * dashboard's buttons and the server's checks cannot drift apart:
+ *
+ * - Success offers Resend: it went out, and someone wants it to go out again
+ *   (a list that was fixed, a page added after a scope change);
+ * - Failed offers Retry: not everyone was sent it;
+ * - Skipped offers nothing. A note posted with notify off keeps
+ *   shouldStatusPageSubscribersBeNotifiedOnNoteCreated false - a column no
+ *   one may update - and the job only sends notes with it true, so a skipped
+ *   note put back to Pending would sit there forever. Other skips (a hidden
+ *   incident, no monitors) would only be skipped again; publishing a hidden
+ *   incident offers its own 'notify' checkbox (IncidentCreatedRenotify);
+ * - Pending and InProgress offer nothing: the notification is on its way.
+ */
+export enum SubscriberNotificationResendAction {
+  // After a failure: send it again to whoever was not sent it.
+  Retry = "Retry",
+  // After a success: send it again to everyone it reaches now.
+  Resend = "Resend",
+}
+
+export default class SubscriberNotificationResend {
+  /*
+   * Why the server refuses to send a public note's notification again,
+   * shown to whoever asked.
+   */
+  public static readonly notePostedWithoutNotifyingMessage: string =
+    "This note was posted without notifying subscribers, so there is nothing to resend. Post a new note with Notify Status Page Subscribers ticked to tell them.";
+
+  public static readonly beingSentMessage: string =
+    "This notification is being sent right now. Wait until it has finished, then send it again.";
+
+  public static readonly noPermissionToResendNoteMessage: string =
+    "You do not have permission to send this note's notification again. Sending it again needs the permission to post public notes that notify subscribers, as well as the permission to edit public notes.";
+
+  public static readonly noPermissionToNotifyAboutEditMessage: string =
+    "You do not have permission to notify subscribers about this edit. Notifying them needs the permission to post public notes that notify subscribers, as well as the permission to edit public notes. Save the edit without notifying subscribers, or ask someone who can post notifying notes.";
+
+  public static readonly updateBeingSentMessage: string =
+    "This note's update notification is being sent right now. Wait until it has finished, then save your edit with Notify subscribers about this update ticked again - or save it without notifying subscribers.";
+
+  /*
+   * What a notification in `status` offers: Retry after a failure, and
+   * Resend after a success where the caller supports resending one
+   * (`isResendAfterSuccessOffered`). Null for anything else.
+   *
+   * A caller that leaves `isResendAfterSuccessOffered` off keeps the old
+   * behaviour: only a failed notification can be sent again.
+   */
+  public static getAction(data: {
+    status: StatusPageSubscriberNotificationStatus | undefined | null;
+    isResendAfterSuccessOffered: boolean;
+  }): SubscriberNotificationResendAction | null {
+    if (data.status === StatusPageSubscriberNotificationStatus.Failed) {
+      return SubscriberNotificationResendAction.Retry;
+    }
+
+    if (
+      data.status === StatusPageSubscriberNotificationStatus.Success &&
+      data.isResendAfterSuccessOffered
+    ) {
+      return SubscriberNotificationResendAction.Resend;
+    }
+
+    return null;
+  }
+
+  /*
+   * Why a public note's notification may not be put back to Pending by a
+   * user or an API key, or null when it may:
+   *
+   * - a note posted with notify off: the job never sends it (see the header),
+   *   so the note would sit in Pending forever;
+   * - a notification being sent right now: the send settles its own status
+   *   when it finishes and would overwrite the Pending, so the request would
+   *   be lost without a word.
+   *
+   * Success and Failed are the cases the dashboard offers. Pending is
+   * allowed and changes nothing. A skipped notification of a note that does
+   * notify (the incident was hidden, or had no monitors, when it went out)
+   * is allowed too: the job looks at it afresh, so it goes out if what
+   * skipped it has changed. The dashboard does not offer that one.
+   */
+  public static getPublicNoteResendRefusal(data: {
+    status: StatusPageSubscriberNotificationStatus | undefined | null;
+    shouldStatusPageSubscribersBeNotifiedOnNoteCreated:
+      | boolean
+      | undefined
+      | null;
+  }): string | null {
+    if (data.shouldStatusPageSubscribersBeNotifiedOnNoteCreated === false) {
+      return this.notePostedWithoutNotifyingMessage;
+    }
+
+    if (data.status === StatusPageSubscriberNotificationStatus.InProgress) {
+      return this.beingSentMessage;
+    }
+
+    return null;
+  }
+
+  /*
+   * Whether an update asks for a public note's notification to be sent
+   * again: it writes Pending into the note's 'posted' status column. The
+   * workers write that column too, but as root, which is never checked.
+   */
+  public static isPublicNoteResendRequested(
+    data: { subscriberNotificationStatusOnNoteCreated?: unknown } | undefined,
+  ): boolean {
+    return (
+      data?.subscriberNotificationStatusOnNoteCreated ===
+      StatusPageSubscriberNotificationStatus.Pending
+    );
+  }
+}

package/Types/StatusPage/SubscriberNotificationTemplateCompiler.ts

@@ -0,0 +1,180 @@
+import SafeHtml from "../SafeHtml";
+
+/*
+ * Fills the {{variable}} placeholders of a status page's custom subscriber
+ * notification templates.
+ *
+ * There are two ways in, and which one a template takes depends on what its
+ * channel renders, never on the variables:
+ *
+ *   - compileEmailBodyTemplate, for the body of an EMAIL template. The body
+ *     is sent as HTML (it is wrapped only by BlankTemplate), so a value is
+ *     inserted as written only when it is a SafeHtml: Markdown the note or
+ *     description was rendered from, the date helper's HTML, the escaped
+ *     resource list. Every other value is plain text - a title, a severity or
+ *     state name, a status page name, a URL - and is HTML-escaped first, so a
+ *     title such as `<a href="https://evil.example">Reset your password</a>`
+ *     reads as those characters instead of arriving as a live link.
+ *   - compileTemplate, for everything that is NOT HTML: an email subject,
+ *     SMS, Slack and Microsoft Teams. Those channels show text as written, so
+ *     escaping would put "&amp;" in front of the reader. Its variables are
+ *     strings, so a SafeHtml (HTML) value cannot reach one by mistake.
+ *
+ * The escaping is the default rather than something each sender remembers to
+ * do: a sender that adds a new plain value to its email variables gets it
+ * escaped without doing anything. App/Tests/SubscriberEmailBodyCompileCallSites
+ * holds every email template body to compileEmailBodyTemplate.
+ *
+ * The admin who writes the template is trusted, as before: the template's own
+ * HTML is sent as written. Only the values put into it are escaped.
+ *
+ * Kept free of server dependencies so the dashboard can fill placeholders too.
+ */
+
+export type SubscriberNotificationTextTemplateVariables = Record<
+  string,
+  string
+>;
+
+export type SubscriberNotificationEmailBodyTemplateVariables = Record<
+  string,
+  string | SafeHtml
+>;
+
+type RenderValueFunction = (name: string) => string | null;
+
+/*
+ * What may sit between the braces of a placeholder: ASCII letters, digits,
+ * underscores and dots, and nothing else (`\w` without the `u` flag is ASCII
+ * only). Written once so that the fill below and isPlaceholderName, which
+ * the custom field template keys are generated against, cannot disagree.
+ */
+const PLACEHOLDER_NAME_SOURCE: string = "[\\w.]+";
+
+const PLACEHOLDER_NAME_PATTERN: RegExp = new RegExp(
+  `^${PLACEHOLDER_NAME_SOURCE}$`,
+);
+
+export default class SubscriberNotificationTemplateCompiler {
+  /**
+   * Whether `{{name}}` is a placeholder these templates fill in. A name with
+   * any other character (a hyphen, a space, a non-ASCII letter) is left in
+   * the message as written, so anything that hands out variable names -
+   * incident custom field keys, for one - has to produce names this accepts.
+   */
+  public static isPlaceholderName(name: string): boolean {
+    return PLACEHOLDER_NAME_PATTERN.test(name);
+  }
+
+  /**
+   * The names of the placeholders these templates hold, each once: exactly
+   * the ones the compile functions below would fill, spaces inside the
+   * braces allowed, so what a template reads can be known before it is
+   * saved or sent. Empty templates are skipped.
+   */
+  public static getPlaceholderNames(
+    templates: Array<string | null | undefined>,
+  ): Set<string> {
+    const names: Set<string> = new Set<string>();
+
+    for (const template of templates) {
+      if (typeof template !== "string" || !template) {
+        continue;
+      }
+
+      for (const match of template.matchAll(
+        SubscriberNotificationTemplateCompiler.getPlaceholderPattern(),
+      )) {
+        names.add(match[1]!);
+      }
+    }
+
+    return names;
+  }
+
+  /**
+   * Compile a template for a channel that does not render HTML: an email
+   * subject, SMS, Slack or Microsoft Teams. Each {{variableName}} is replaced
+   * with its value exactly as written.
+   *
+   * Never use this for the body of an email template: see
+   * compileEmailBodyTemplate.
+   */
+  public static compileTemplate(
+    template: string,
+    variables: SubscriberNotificationTextTemplateVariables,
+  ): string {
+    return SubscriberNotificationTemplateCompiler.fillPlaceholders(
+      template,
+      (name: string): string | null => {
+        if (!Object.prototype.hasOwnProperty.call(variables, name)) {
+          return null;
+        }
+
+        return variables[name] || "";
+      },
+    );
+  }
+
+  /**
+   * Compile the body of an EMAIL template, which is sent as HTML.
+   *
+   * A SafeHtml value is inserted as it is. Any other value is plain text and
+   * is HTML-escaped, so it can neither add markup nor break out of the
+   * attribute it is placed in (href="{{detailsUrl}}").
+   */
+  public static compileEmailBodyTemplate(
+    template: string,
+    variables: SubscriberNotificationEmailBodyTemplateVariables,
+  ): string {
+    return SubscriberNotificationTemplateCompiler.fillPlaceholders(
+      template,
+      (name: string): string | null => {
+        if (!Object.prototype.hasOwnProperty.call(variables, name)) {
+          return null;
+        }
+
+        const value: string | SafeHtml | undefined = variables[name];
+
+        if (SafeHtml.isSafeHtml(value)) {
+          return value.toHtml();
+        }
+
+        if (value === null || value === undefined) {
+          return "";
+        }
+
+        return SafeHtml.escape(String(value));
+      },
+    );
+  }
+
+  /*
+   * One pass over the template, with a replacer function:
+   * - A replacement string would give "$&", "$$", "$`" and "$'" special
+   *   meaning, so a note mentioning "$$5" or a resource named "Store $&" was
+   *   rewritten on its way to subscribers.
+   * - Replacing one variable at a time also expanded placeholders that
+   *   appeared inside an earlier value, so a note containing
+   *   "{{unsubscribeUrl}}" came out as a link.
+   * A placeholder with no variable is left as written.
+   */
+  private static fillPlaceholders(
+    template: string,
+    renderValue: RenderValueFunction,
+  ): string {
+    return template.replace(
+      SubscriberNotificationTemplateCompiler.getPlaceholderPattern(),
+      (placeholder: string, name: string): string => {
+        const rendered: string | null = renderValue(name);
+
+        return rendered === null ? placeholder : rendered;
+      },
+    );
+  }
+
+  // A fresh global pattern each time: a shared one would carry lastIndex.
+  private static getPlaceholderPattern(): RegExp {
+    return new RegExp(`{{\\s*(${PLACEHOLDER_NAME_SOURCE})\\s*}}`, "g");
+  }
+}