@oneuptime/common 14.0.7 → 14.0.9

package/Types/StatusPage/IncidentScopeAddedPagesNotification.ts

@@ -0,0 +1,343 @@
+import { JSONObject } from "../JSON";
+import StatusPageSubscriberNotificationStatus from "./StatusPageSubscriberNotificationStatus";
+
+/*
+ * An incident can be limited to some status pages (Incident.statusPages), and
+ * the pages it is limited to often change while it is open: a site turns out
+ * to be affected after all, or an incident a monitor created on its own gets
+ * scoped once someone works out who is affected. Subscribers of a page hear
+ * about an incident once, when it is created, so without a way back a page
+ * added later never got the 'created' notification at all.
+ *
+ * Whether a newly added page should hear about it now is the editor's call,
+ * so it is asked when pages are added (the dashboard ticks it by default)
+ * rather than decided automatically, and the answer travels with that update
+ * as a misc data prop - like SubscriberUpdateNotification and
+ * IncidentCreatedRenotify, it is not a column. IncidentService turns it into a
+ * Pending 'created' notification, and the Incident:SendNotificationToSubscribers
+ * job sends it to the pages in the scope that are not yet listed in
+ * Incident.statusPagesNotifiedOnCreation. That record is what keeps the pages
+ * that were already told from hearing it twice: the request re-queues the
+ * notification, and the record decides who it goes to.
+ *
+ * The record only exists once the job has settled a send, so two cases have
+ * none, and each is handled so that only the pages the edit adds are told:
+ *
+ * - the notification went out before the record existed (an incident from an
+ *   earlier release, Success or Failed with no record). It reached every page
+ *   that listed the incident's monitors back then, so there is no way to tell
+ *   an added page from one that was told, and nothing is queued. An empty
+ *   record would otherwise read as "nobody was told" and announce the incident
+ *   a second time;
+ * - the notification was Skipped and never sent (published without
+ *   announcing it, or declared without monitors). The pages the incident was
+ *   limited to before the edit were deliberately not told, so the update
+ *   writes them in as the record when it queues the notification (see
+ *   getRecordToSeedOnQueue): the job then tells the added pages only, not the
+ *   pages the editor chose not to announce it on.
+ *
+ * Everything here is shared by the dashboard, which offers the checkbox, and
+ * the server, which acts on it, so the two cannot drift apart: the dashboard
+ * offers the checkbox exactly when getAction would queue.
+ */
+
+// What an update that adds status pages does to the 'created' notification.
+export enum IncidentScopeAddedPagesNotificationAction {
+  /*
+   * Nothing to do: no page was added, every added page was told already, or
+   * the incident is not to be announced.
+   */
+  None = "None",
+  // Put the 'created' notification back to Pending.
+  Queue = "Queue",
+  /*
+   * It is Pending, or being sent right now. A queued send reads the scope
+   * when it goes out, and a send that is running reads it again once it has
+   * finished and queues itself once more for any page added meanwhile, so the
+   * added pages are reached without any change here. IncidentService checks
+   * once the update is written, in case the send finished in between.
+   */
+  AlreadyQueued = "AlreadyQueued",
+}
+
+export interface IncidentScopeAddedPagesNotificationState {
+  subscriberNotificationStatusOnIncidentCreated?:
+    | StatusPageSubscriberNotificationStatus
+    | undefined
+    | null;
+  shouldStatusPageSubscribersBeNotifiedOnIncidentCreated?:
+    | boolean
+    | undefined
+    | null;
+  // Both as they will be once the update is written.
+  isVisibleOnStatusPage?: boolean | undefined | null;
+  isPrivate?: boolean | undefined | null;
+  /*
+   * Incident.statusPagesNotifiedOnCreation as stored: the pages the job has a
+   * record of telling. Null or undefined when it has none (see the header).
+   */
+  statusPagesNotifiedOnCreation?: unknown;
+}
+
+export interface StatusPageScopeChange {
+  addedStatusPageIds: Array<string>;
+  removedStatusPageIds: Array<string>;
+}
+
+export default class IncidentScopeAddedPagesNotification {
+  // The misc data prop an update request carries to ask for the notification.
+  public static readonly miscDataKey: string =
+    "notifyAddedStatusPagesOfIncidentCreated";
+
+  public static readonly queuedMessage: string =
+    "Status pages were added to this incident. Their subscribers will be sent the notification that this incident was created.";
+
+  /*
+   * The status the job leaves when pages were added to the scope while it was
+   * sending: queued again, for the pages it had not reached.
+   */
+  public static readonly addedWhileSendingMessage: string =
+    "Status pages were added to this incident while its subscribers were being sent the notification that it was created. The added pages will be sent it next.";
+
+  public static readonly formFieldTitle: string =
+    "Send the incident-created notification to newly added pages";
+
+  public static readonly formFieldDescription: string =
+    "Subscribers of the status pages you add are sent the notification that this incident was created. Pages that were already told are not sent it again.";
+
+  /*
+   * Only a real yes counts. The flag arrives over JSON, so accept the string
+   * form a hand-written API request might send, and nothing looser: a stray
+   * "false" or 1 must never email every subscriber of a status page.
+   */
+  public static isRequested(
+    miscDataProps: JSONObject | undefined | null,
+  ): boolean {
+    if (!miscDataProps || typeof miscDataProps !== "object") {
+      return false;
+    }
+
+    const value: unknown = miscDataProps[this.miscDataKey];
+
+    return value === true || value === "true";
+  }
+
+  public static getMiscDataProps(): JSONObject {
+    return {
+      [this.miscDataKey]: true,
+    };
+  }
+
+  /*
+   * The status page ids in any shape a status page list arrives in - a model,
+   * a {_id} or {id} object, an ObjectID or a bare string - lower-cased (the
+   * database reads uuids back lower-cased) and without duplicates, in the
+   * order first seen.
+   */
+  public static normalizeStatusPageIds(value: unknown): Array<string> {
+    if (value === undefined || value === null) {
+      return [];
+    }
+
+    const entries: Array<unknown> = Array.isArray(value) ? value : [value];
+    const ids: Array<string> = [];
+
+    for (const entry of entries) {
+      const id: string | undefined = this.getStatusPageId(entry);
+
+      if (id && !ids.includes(id)) {
+        ids.push(id);
+      }
+    }
+
+    return ids;
+  }
+
+  // Which pages a change of the scope from `before` to `after` adds and removes.
+  public static getScopeChange(data: {
+    before: unknown;
+    after: unknown;
+  }): StatusPageScopeChange {
+    const before: Array<string> = this.normalizeStatusPageIds(data.before);
+    const after: Array<string> = this.normalizeStatusPageIds(data.after);
+
+    return {
+      addedStatusPageIds: after.filter((id: string) => {
+        return !before.includes(id);
+      }),
+      removedStatusPageIds: before.filter((id: string) => {
+        return !after.includes(id);
+      }),
+    };
+  }
+
+  /*
+   * The pages Incident.statusPagesNotifiedOnCreation lists, or null when there
+   * is no record: never written (the job has not settled a send since the
+   * record was introduced), or not a list.
+   */
+  public static getRecordedStatusPageIds(value: unknown): Array<string> | null {
+    if (!Array.isArray(value)) {
+      return null;
+    }
+
+    return this.normalizeStatusPageIds(value);
+  }
+
+  /*
+   * What adding `addedStatusPageIds` to an incident's scope does to its
+   * 'created' notification, given where that notification is:
+   *
+   * - no page added: nothing, whatever else the update does;
+   * - notifying on creation is off: nothing. An incident declared with
+   *   notifications off was deliberately kept quiet, and scoping it does not
+   *   change that;
+   * - hidden from status pages or private once the update is written:
+   *   nothing. The job would only skip it again. Publishing the incident
+   *   offers to announce it to the pages that were not told
+   *   (IncidentCreatedRenotify.canRenotifyOnPublish), including pages added
+   *   while it was hidden;
+   * - every added page is in the record: nothing, they were told already
+   *   (a page removed earlier and added back, or an unscoped incident being
+   *   narrowed to pages it reached);
+   * - Success or Failed with no record: nothing. It went out before the
+   *   record existed, to every page that listed the monitors then (see the
+   *   header);
+   * - Success, Skipped or Failed otherwise: queue it again. The job then
+   *   sends it to the pages in the scope it has no record of telling - the
+   *   added pages, plus, after a failure, the pages the failed send did not
+   *   reach;
+   * - Pending or InProgress: already on its way, and it reaches the added
+   *   pages (see AlreadyQueued).
+   */
+  public static getAction(data: {
+    addedStatusPageIds: Array<string>;
+    incident: IncidentScopeAddedPagesNotificationState;
+  }): IncidentScopeAddedPagesNotificationAction {
+    const addedStatusPageIds: Array<string> = this.normalizeStatusPageIds(
+      data.addedStatusPageIds,
+    );
+
+    if (addedStatusPageIds.length === 0) {
+      return IncidentScopeAddedPagesNotificationAction.None;
+    }
+
+    const incident: IncidentScopeAddedPagesNotificationState = data.incident;
+
+    if (
+      incident.shouldStatusPageSubscribersBeNotifiedOnIncidentCreated !== true
+    ) {
+      return IncidentScopeAddedPagesNotificationAction.None;
+    }
+
+    // A null visibility is hidden to the job, so it is here too.
+    if (
+      incident.isVisibleOnStatusPage !== true ||
+      incident.isPrivate === true
+    ) {
+      return IncidentScopeAddedPagesNotificationAction.None;
+    }
+
+    const status: StatusPageSubscriberNotificationStatus | undefined | null =
+      incident.subscriberNotificationStatusOnIncidentCreated;
+
+    const recorded: Array<string> | null = this.getRecordedStatusPageIds(
+      incident.statusPagesNotifiedOnCreation,
+    );
+
+    if (recorded === null) {
+      if (
+        status === StatusPageSubscriberNotificationStatus.Success ||
+        status === StatusPageSubscriberNotificationStatus.Failed
+      ) {
+        return IncidentScopeAddedPagesNotificationAction.None;
+      }
+    } else if (
+      addedStatusPageIds.every((id: string): boolean => {
+        return recorded.includes(id);
+      })
+    ) {
+      return IncidentScopeAddedPagesNotificationAction.None;
+    }
+
+    switch (status) {
+      case StatusPageSubscriberNotificationStatus.Pending:
+      case StatusPageSubscriberNotificationStatus.InProgress:
+        return IncidentScopeAddedPagesNotificationAction.AlreadyQueued;
+      default:
+        /*
+         * Success, Skipped and Failed - and a missing status, which the
+         * column's Pending default makes impossible but which would otherwise
+         * never be sent.
+         */
+        return IncidentScopeAddedPagesNotificationAction.Queue;
+    }
+  }
+
+  /*
+   * The record an update that queues the notification (action Queue) has to
+   * write along with it, or undefined when the stored record stands.
+   *
+   * With a record, the job already knows who was told. Without one the
+   * notification was never sent (getAction does not queue a Success or
+   * Failed one without a record), so the pages the incident was limited to
+   * before the update were deliberately not told - it was published without
+   * announcing it, or declared without monitors. They are written in as the
+   * record, so the job tells only the pages the update adds. An incident
+   * that was not limited to any page before has nothing to leave out: every
+   * page it is now limited to is one the update adds.
+   */
+  public static getRecordToSeedOnQueue(data: {
+    statusPagesNotifiedOnCreation: unknown;
+    statusPageIdsBeforeUpdate: unknown;
+  }): Array<string> | undefined {
+    if (this.getRecordedStatusPageIds(data.statusPagesNotifiedOnCreation)) {
+      return undefined;
+    }
+
+    return this.normalizeStatusPageIds(data.statusPageIdsBeforeUpdate);
+  }
+
+  private static getStatusPageId(entry: unknown): string | undefined {
+    if (!entry) {
+      return undefined;
+    }
+
+    let id: unknown = entry;
+
+    if (typeof entry === "object") {
+      const relation: {
+        _id?: unknown;
+        id?: unknown;
+        _type?: unknown;
+        value?: unknown;
+      } = entry as {
+        _id?: unknown;
+        id?: unknown;
+        _type?: unknown;
+        value?: unknown;
+      };
+
+      // A model, an ObjectID, a {_id}/{id} object or a serialized ObjectID.
+      if (relation._id !== undefined && relation._id !== null) {
+        id = relation._id;
+      } else if (relation.id !== undefined && relation.id !== null) {
+        id = relation.id;
+      } else if (relation._type === "ObjectID" && relation.value) {
+        id = relation.value;
+      }
+    }
+
+    if (typeof id !== "string" && typeof id !== "object") {
+      return undefined;
+    }
+
+    const text: string = String(id).trim().toLowerCase();
+
+    if (!text || text === "[object object]") {
+      return undefined;
+    }
+
+    return text;
+  }
+}

package/Types/StatusPage/IncidentSubscriberAudience.ts

@@ -0,0 +1,332 @@
+import { JSONObject } from "../JSON";
+
+/*
+ * Who an incident's status page notifications reach, shown before anything is
+ * sent: on the last step of declaring an incident, and above a public note
+ * while it is being written. "Will notify: Site 03 (up to 41 email), Site 07
+ * (up to 18 email)".
+ *
+ * POST /incident/subscriber-audience (IncidentAPI) answers it, from the same
+ * helper the subscriber jobs send through (IncidentStatusPageScope), so the
+ * preview and the send cannot disagree about which pages an incident reaches.
+ * It takes either an incident that is being declared - the monitors and the
+ * status pages picked on the form - or one that exists.
+ *
+ * The counts are "up to": they count the confirmed subscribers of each page
+ * who have not unsubscribed, per channel. A subscriber who picked only some
+ * of a page's resources, or only some event types, is filtered out at send
+ * time; and for an incident limited to specific pages an email address or
+ * phone number on two of them gets one message, not two. Addresses themselves
+ * never leave the server - only counts do.
+ *
+ * Everything here is shared by the server, which builds the answer, and the
+ * dashboard, which reads it, so the two cannot drift apart.
+ */
+
+// Why a status page that lists the incident's monitors is not notified.
+export enum IncidentSubscriberAudienceExclusionReason {
+  // The incident is limited to other status pages.
+  OutsideIncidentScope = "OutsideIncidentScope",
+  // The page only shows incidents limited to it, and this one is not.
+  OnlyShowsScopedIncidents = "OnlyShowsScopedIncidents",
+  // The page does not show incidents at all (Show Incidents is off).
+  HidesIncidents = "HidesIncidents",
+  /*
+   * Asked for a Retry of the incident's 'created' notification only: the
+   * page was already sent it in full (Incident.statusPagesNotifiedOnCreation),
+   * and Retry resumes after it.
+   */
+  AlreadyNotified = "AlreadyNotified",
+}
+
+// How many subscribers of one status page each channel reaches, at most.
+export interface IncidentSubscriberAudienceCounts {
+  email: number;
+  sms: number;
+  slack: number;
+  microsoftTeams: number;
+  webhook: number;
+}
+
+export type IncidentSubscriberAudienceChannel =
+  keyof IncidentSubscriberAudienceCounts;
+
+export interface IncidentSubscriberAudienceNamedStatusPage {
+  statusPageId: string;
+  name: string;
+}
+
+// A status page that will be notified.
+export interface IncidentSubscriberAudienceStatusPage
+  extends IncidentSubscriberAudienceNamedStatusPage {
+  subscriberCounts: IncidentSubscriberAudienceCounts;
+}
+
+// A status page that lists the incident's monitors but will not be notified.
+export interface IncidentSubscriberAudienceExcludedStatusPage
+  extends IncidentSubscriberAudienceNamedStatusPage {
+  reason: IncidentSubscriberAudienceExclusionReason;
+}
+
+export interface IncidentSubscriberAudienceResult {
+  /*
+   * Whether the incident is on any monitor. Status page subscribers hear
+   * about an incident through its monitors, so one on none notifies nobody.
+   */
+  hasMonitors: boolean;
+  /*
+   * Whether it is limited to specific status pages. Only then are email and
+   * SMS sent once per address across pages.
+   */
+  isScoped: boolean;
+  /*
+   * For an incident that exists: it is hidden from status pages (not
+   * visible, or private), so nothing is sent whatever pages it reaches.
+   */
+  isHiddenFromStatusPages: boolean;
+  // The status pages that will be notified that the caller can see, by name.
+  statusPages: Array<IncidentSubscriberAudienceStatusPage>;
+  /*
+   * How many more status pages will be notified that the caller cannot see.
+   * Status pages are label-scoped, and a page the caller may not read is not
+   * named in this answer, nor are its subscribers counted. (The names of the
+   * pages an incident is limited to are part of the incident itself, and
+   * readable by anyone who can read it.)
+   */
+  hiddenStatusPageCount: number;
+  /*
+   * Status pages the caller can see that list the monitors but will not be
+   * notified, with why. Pages the caller cannot see are left out.
+   */
+  excludedStatusPages: Array<IncidentSubscriberAudienceExcludedStatusPage>;
+  /*
+   * Status pages the incident is limited to that list none of its monitors.
+   * The scope only narrows where the monitors already reach, so the incident
+   * does not show on, or notify, these. Only pages the caller can see.
+   */
+  selectedStatusPagesNotListingMonitors: Array<IncidentSubscriberAudienceNamedStatusPage>;
+}
+
+// The order channels are listed in, and what each is called on screen.
+export const INCIDENT_SUBSCRIBER_AUDIENCE_CHANNELS: ReadonlyArray<{
+  channel: IncidentSubscriberAudienceChannel;
+  label: string;
+}> = [
+  { channel: "email", label: "email" },
+  { channel: "sms", label: "SMS" },
+  { channel: "slack", label: "Slack" },
+  { channel: "microsoftTeams", label: "Microsoft Teams" },
+  { channel: "webhook", label: "webhook" },
+];
+
+export default class IncidentSubscriberAudience {
+  // The route, under the API's base URL.
+  public static readonly apiPath: string = "/incident/subscriber-audience";
+
+  // How many monitors or status pages one request may name.
+  public static readonly maxIdsPerRequest: number = 1000;
+
+  public static getEmptyCounts(): IncidentSubscriberAudienceCounts {
+    return {
+      email: 0,
+      sms: 0,
+      slack: 0,
+      microsoftTeams: 0,
+      webhook: 0,
+    };
+  }
+
+  public static getTotal(counts: IncidentSubscriberAudienceCounts): number {
+    return INCIDENT_SUBSCRIBER_AUDIENCE_CHANNELS.reduce(
+      (
+        total: number,
+        entry: { channel: IncidentSubscriberAudienceChannel },
+      ): number => {
+        return total + (counts[entry.channel] || 0);
+      },
+      0,
+    );
+  }
+
+  /*
+   * The channels of one page that reach anyone, in display order, with their
+   * counts: [{channel: "email", label: "email", count: 41}, ...].
+   */
+  public static getNonEmptyChannels(
+    counts: IncidentSubscriberAudienceCounts,
+  ): Array<{
+    channel: IncidentSubscriberAudienceChannel;
+    label: string;
+    count: number;
+  }> {
+    return INCIDENT_SUBSCRIBER_AUDIENCE_CHANNELS.map(
+      (entry: {
+        channel: IncidentSubscriberAudienceChannel;
+        label: string;
+      }) => {
+        return {
+          channel: entry.channel,
+          label: entry.label,
+          count: counts[entry.channel] || 0,
+        };
+      },
+    ).filter((entry: { count: number }): boolean => {
+      return entry.count > 0;
+    });
+  }
+
+  // Whether anyone at all will be sent anything.
+  public static reachesAnyone(
+    audience: IncidentSubscriberAudienceResult,
+  ): boolean {
+    if (audience.isHiddenFromStatusPages || !audience.hasMonitors) {
+      return false;
+    }
+
+    return (
+      audience.hiddenStatusPageCount > 0 ||
+      audience.statusPages.some(
+        (statusPage: IncidentSubscriberAudienceStatusPage): boolean => {
+          return this.getTotal(statusPage.subscriberCounts) > 0;
+        },
+      )
+    );
+  }
+
+  /*
+   * The server's answer as the dashboard receives it. Read defensively: the
+   * summary is advisory, and a field that is missing or of the wrong type
+   * must read as "nothing" rather than break the form it sits on.
+   */
+  public static fromJSON(json: JSONObject): IncidentSubscriberAudienceResult {
+    const toArray: (value: unknown) => Array<JSONObject> = (
+      value: unknown,
+    ): Array<JSONObject> => {
+      return Array.isArray(value)
+        ? (value.filter((item: unknown): boolean => {
+            return Boolean(item) && typeof item === "object";
+          }) as Array<JSONObject>)
+        : [];
+    };
+
+    const toCount: (value: unknown) => number = (value: unknown): number => {
+      const count: number = Number(value);
+      return Number.isFinite(count) && count > 0 ? Math.floor(count) : 0;
+    };
+
+    const toNamed: (
+      item: JSONObject,
+    ) => IncidentSubscriberAudienceNamedStatusPage = (
+      item: JSONObject,
+    ): IncidentSubscriberAudienceNamedStatusPage => {
+      return {
+        statusPageId: String(item["statusPageId"] || ""),
+        name: String(item["name"] || ""),
+      };
+    };
+
+    const reasons: Array<string> = Object.values(
+      IncidentSubscriberAudienceExclusionReason,
+    );
+
+    return {
+      hasMonitors: json["hasMonitors"] === true,
+      isScoped: json["isScoped"] === true,
+      isHiddenFromStatusPages: json["isHiddenFromStatusPages"] === true,
+      statusPages: toArray(json["statusPages"]).map(
+        (item: JSONObject): IncidentSubscriberAudienceStatusPage => {
+          return {
+            ...toNamed(item),
+            subscriberCounts: this.countsFromJSON(item["subscriberCounts"]),
+          };
+        },
+      ),
+      hiddenStatusPageCount: toCount(json["hiddenStatusPageCount"]),
+      excludedStatusPages: toArray(json["excludedStatusPages"])
+        .filter((item: JSONObject): boolean => {
+          return reasons.includes(String(item["reason"]));
+        })
+        .map(
+          (item: JSONObject): IncidentSubscriberAudienceExcludedStatusPage => {
+            return {
+              ...toNamed(item),
+              reason: item[
+                "reason"
+              ] as IncidentSubscriberAudienceExclusionReason,
+            };
+          },
+        ),
+      selectedStatusPagesNotListingMonitors: toArray(
+        json["selectedStatusPagesNotListingMonitors"],
+      ).map(toNamed),
+    };
+  }
+
+  /*
+   * One page's counts as they arrive, each a whole number of at least 0: a
+   * count that is missing or not a number reads as 0.
+   */
+  public static countsFromJSON(
+    value: unknown,
+  ): IncidentSubscriberAudienceCounts {
+    const counts: JSONObject =
+      value && typeof value === "object" && !Array.isArray(value)
+        ? (value as JSONObject)
+        : {};
+
+    const toCount: (count: unknown) => number = (count: unknown): number => {
+      const number: number = Number(count);
+      return Number.isFinite(number) && number > 0 ? Math.floor(number) : 0;
+    };
+
+    return {
+      email: toCount(counts["email"]),
+      sms: toCount(counts["sms"]),
+      slack: toCount(counts["slack"]),
+      microsoftTeams: toCount(counts["microsoftTeams"]),
+      webhook: toCount(counts["webhook"]),
+    };
+  }
+
+  public static toJSON(audience: IncidentSubscriberAudienceResult): JSONObject {
+    return {
+      hasMonitors: audience.hasMonitors,
+      isScoped: audience.isScoped,
+      isHiddenFromStatusPages: audience.isHiddenFromStatusPages,
+      statusPages: audience.statusPages.map(
+        (statusPage: IncidentSubscriberAudienceStatusPage): JSONObject => {
+          return {
+            statusPageId: statusPage.statusPageId,
+            name: statusPage.name,
+            subscriberCounts: {
+              ...statusPage.subscriberCounts,
+            },
+          };
+        },
+      ),
+      hiddenStatusPageCount: audience.hiddenStatusPageCount,
+      excludedStatusPages: audience.excludedStatusPages.map(
+        (
+          statusPage: IncidentSubscriberAudienceExcludedStatusPage,
+        ): JSONObject => {
+          return {
+            statusPageId: statusPage.statusPageId,
+            name: statusPage.name,
+            reason: statusPage.reason,
+          };
+        },
+      ),
+      selectedStatusPagesNotListingMonitors:
+        audience.selectedStatusPagesNotListingMonitors.map(
+          (
+            statusPage: IncidentSubscriberAudienceNamedStatusPage,
+          ): JSONObject => {
+            return {
+              statusPageId: statusPage.statusPageId,
+              name: statusPage.name,
+            };
+          },
+        ),
+    };
+  }
+}