@oneuptime/common 14.0.13 → 14.0.14

package/Types/NotificationRule/OnCallRuleKind.ts

@@ -0,0 +1,194 @@
+import Dictionary from "../Dictionary";
+import NotificationRuleType from "./NotificationRuleType";
+
+/*
+ * THE FOUR KINDS OF ON-CALL RULE, AND THE ADDRESS OF EACH ONE'S TAB.
+ *
+ * A person keeps on-call notification rules for four kinds of page:
+ * incidents, incident episodes, alerts and alert episodes. They live on one
+ * On-Call Rules page with a tab per kind - in User Settings for your own,
+ * and under Users > (a member) > On-Call for an admin looking at somebody
+ * else's. The address says which tab is open: `?type=alerts`. The first tab,
+ * Incidents, is the bare address, so every tab has exactly one address.
+ *
+ * Everything that sends somebody to fix a rule builds that address from
+ * here: the dashboard's own links (the setup checklist, a policy's readiness
+ * card, a team's compliance page) and the server's emails (the setup
+ * reminder, "you were paged without a notification rule"). The server cannot
+ * import dashboard code, so this lives in Common for both.
+ *
+ * The page used to be four pages, one per kind, at
+ * `user-settings/incident-on-call-rules` and its three siblings. Those
+ * addresses still work: they forward to the tab they named
+ * (MOVED_ON_CALL_RULES_PATHS).
+ */
+enum OnCallRuleKind {
+  Incidents = "incidents",
+  IncidentEpisodes = "incident-episodes",
+  Alerts = "alerts",
+  AlertEpisodes = "alert-episodes",
+}
+
+// In tab order. The first is the tab a bare address opens.
+export const ON_CALL_RULE_KINDS: ReadonlyArray<OnCallRuleKind> = [
+  OnCallRuleKind.Incidents,
+  OnCallRuleKind.IncidentEpisodes,
+  OnCallRuleKind.Alerts,
+  OnCallRuleKind.AlertEpisodes,
+];
+
+export const DEFAULT_ON_CALL_RULE_KIND: OnCallRuleKind =
+  OnCallRuleKind.Incidents;
+
+// The query parameter that names the open tab.
+export const ON_CALL_RULE_KIND_QUERY_PARAM: string = "type";
+
+/*
+ * The page's last path segment: `user-settings/on-call-rules` for your own,
+ * `users/<id>/on-call-rules` for a member's.
+ */
+export const ON_CALL_RULES_PAGE_PATH: string = "on-call-rules";
+
+/*
+ * The four pages the tabs replaced, by the last part of their address (the
+ * same in User Settings and under Users > (a member)), and the tab each one
+ * forwards to.
+ */
+export const MOVED_ON_CALL_RULES_PATHS: Readonly<
+  Record<string, OnCallRuleKind>
+> = {
+  "incident-on-call-rules": OnCallRuleKind.Incidents,
+  "incident-episode-on-call-rules": OnCallRuleKind.IncidentEpisodes,
+  "alert-on-call-rules": OnCallRuleKind.Alerts,
+  "alert-episode-on-call-rules": OnCallRuleKind.AlertEpisodes,
+};
+
+const RULE_TYPE_BY_KIND: Readonly<
+  Record<OnCallRuleKind, NotificationRuleType>
+> = {
+  [OnCallRuleKind.Incidents]: NotificationRuleType.ON_CALL_EXECUTED_INCIDENT,
+  [OnCallRuleKind.IncidentEpisodes]:
+    NotificationRuleType.ON_CALL_EXECUTED_INCIDENT_EPISODE,
+  [OnCallRuleKind.Alerts]: NotificationRuleType.ON_CALL_EXECUTED_ALERT,
+  [OnCallRuleKind.AlertEpisodes]:
+    NotificationRuleType.ON_CALL_EXECUTED_ALERT_EPISODE,
+};
+
+// The rule type every rule on a kind's tab has.
+export const getRuleTypeForOnCallRuleKind: (
+  kind: OnCallRuleKind,
+) => NotificationRuleType = (kind: OnCallRuleKind): NotificationRuleType => {
+  return RULE_TYPE_BY_KIND[kind];
+};
+
+/*
+ * The tab a rule of this type is on. The two shift rule types ("when I go on
+ * call", "when I go off call") have no tab of their own and are not paged
+ * for an event, so a link about one opens the first tab, as a bare address
+ * does.
+ */
+export const getOnCallRuleKindForRuleType: (
+  ruleType: NotificationRuleType,
+) => OnCallRuleKind = (ruleType: NotificationRuleType): OnCallRuleKind => {
+  for (const kind of ON_CALL_RULE_KINDS) {
+    if (RULE_TYPE_BY_KIND[kind] === ruleType) {
+      return kind;
+    }
+  }
+
+  return DEFAULT_ON_CALL_RULE_KIND;
+};
+
+/*
+ * The tab an address asks for, or null when it asks for none we have: no
+ * parameter, an empty one, or a kind this build does not know (a link from
+ * a newer server, or one typed by hand). Case and surrounding spaces are
+ * forgiven, since people type and paste these.
+ */
+export const readOnCallRuleKind: (
+  value: string | null | undefined,
+) => OnCallRuleKind | null = (
+  value: string | null | undefined,
+): OnCallRuleKind | null => {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const normalized: string = value.trim().toLowerCase();
+
+  for (const kind of ON_CALL_RULE_KINDS) {
+    if (kind === normalized) {
+      return kind;
+    }
+  }
+
+  return null;
+};
+
+/*
+ * The query that opens the page on a kind's tab: { type: "alerts" }, and
+ * nothing for the first tab, whose address is the bare one - the address the
+ * page itself shows once that tab is open.
+ */
+export const getOnCallRuleKindQuery: (
+  kind: OnCallRuleKind,
+) => Dictionary<string> = (kind: OnCallRuleKind): Dictionary<string> => {
+  if (kind === DEFAULT_ON_CALL_RULE_KIND) {
+    return {};
+  }
+
+  return { [ON_CALL_RULE_KIND_QUERY_PARAM]: kind };
+};
+
+// The query that opens the page on the tab holding a rule type's rules.
+export const getOnCallRuleKindQueryForRuleType: (
+  ruleType: NotificationRuleType,
+) => Dictionary<string> = (
+  ruleType: NotificationRuleType,
+): Dictionary<string> => {
+  return getOnCallRuleKindQuery(getOnCallRuleKindForRuleType(ruleType));
+};
+
+// Whether a value is one of the rule types this build knows.
+export const isKnownNotificationRuleType: (
+  value: unknown,
+) => value is NotificationRuleType = (
+  value: unknown,
+): value is NotificationRuleType => {
+  return Object.values(NotificationRuleType).includes(
+    value as NotificationRuleType,
+  );
+};
+
+export interface OnCallRulesLink {
+  // Under the dashboard's address: `/<projectId>/user-settings/on-call-rules`.
+  path: string;
+  // What opens the tab, as getOnCallRuleKindQuery gives it.
+  query: Dictionary<string>;
+}
+
+/*
+ * Where somebody fixes a missing rule of this type, for a link built outside
+ * the dashboard (the server's emails): their own On-Call Rules page in the
+ * project, on the tab that holds the rule type. Null for a rule type this
+ * build has never heard of, which the caller sends to Notification Methods -
+ * the one page that matters for every gap there could ever be.
+ */
+export const getUserSettingsOnCallRulesLink: (data: {
+  projectId: string;
+  ruleType: unknown;
+}) => OnCallRulesLink | null = (data: {
+  projectId: string;
+  ruleType: unknown;
+}): OnCallRulesLink | null => {
+  if (!isKnownNotificationRuleType(data.ruleType)) {
+    return null;
+  }
+
+  return {
+    path: `/${data.projectId}/user-settings/${ON_CALL_RULES_PAGE_PATH}`,
+    query: getOnCallRuleKindQueryForRuleType(data.ruleType),
+  };
+};
+
+export default OnCallRuleKind;

package/Types/OnCallDutyPolicy/FirstResponders.ts

@@ -1,6 +1,7 @@
 import BadDataException from "../Exception/BadDataException";
-import { JSONObject, ObjectType } from "../JSON";
+import { JSONObject } from "../JSON";
 import ObjectID from "../ObjectID";
+import { readMiscDataId } from "./MiscDataId";
 
 /*
  * WHO GETS PAGED FIRST.
@@ -71,36 +72,6 @@ export const countFirstResponders: (ids: FirstResponderIds) => number = (
   );
 };
 
-/*
- * The id one entry of a list names: a string (what the dashboard sends), an
- * ObjectID (what the API's deserializer makes of { _type: "ObjectID" }), or
- * that JSON itself when a caller inside the server passes it on.
- */
-const readId: (entry: unknown) => string | null = (
-  entry: unknown,
-): string | null => {
-  if (typeof entry === "string") {
-    return entry.trim() || null;
-  }
-
-  if (entry instanceof ObjectID) {
-    return entry.toString().trim() || null;
-  }
-
-  if (entry && typeof entry === "object" && !Array.isArray(entry)) {
-    const record: JSONObject = entry as JSONObject;
-
-    if (
-      record["_type"] === ObjectType.ObjectID &&
-      typeof record["value"] === "string"
-    ) {
-      return record["value"].trim() || null;
-    }
-  }
-
-  return null;
-};
-
 /**
  * Who a policy create asks to page first, read from its misc data.
  *
@@ -139,7 +110,7 @@ export const readFirstResponderIds: (
     }
 
     for (const entry of value) {
-      const id: string | null = readId(entry);
+      const id: string | null = readMiscDataId(entry);
 
       if (!id || !ObjectID.isValidUUID(id)) {
         throw new BadDataException(

package/Types/OnCallDutyPolicy/MiscDataId.ts

@@ -0,0 +1,38 @@
+import { JSONObject, ObjectType } from "../JSON";
+import ObjectID from "../ObjectID";
+
+/*
+ * The id one entry of a list of ids in a create request's misc data names:
+ * a string (what the dashboard sends), an ObjectID (what the API's
+ * deserializer makes of { _type: "ObjectID" }), or that JSON itself when a
+ * caller inside the server passes it on. Null for anything else, and for an
+ * empty string.
+ *
+ * Shared by the readers of what a create form asks along with the record:
+ * who a new on-call policy pages first (FirstResponders) and who takes turns
+ * in a new on-call schedule (ScheduleFirstLayer).
+ */
+export const readMiscDataId: (entry: unknown) => string | null = (
+  entry: unknown,
+): string | null => {
+  if (typeof entry === "string") {
+    return entry.trim() || null;
+  }
+
+  if (entry instanceof ObjectID) {
+    return entry.toString().trim() || null;
+  }
+
+  if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+    const record: JSONObject = entry as JSONObject;
+
+    if (
+      record["_type"] === ObjectType.ObjectID &&
+      typeof record["value"] === "string"
+    ) {
+      return record["value"].trim() || null;
+    }
+  }
+
+  return null;
+};

package/Types/OnCallDutyPolicy/ScheduleFirstLayer.ts

@@ -0,0 +1,165 @@
+import EventInterval from "../Events/EventInterval";
+import Recurring from "../Events/Recurring";
+import BadDataException from "../Exception/BadDataException";
+import { JSONObject } from "../JSON";
+import ObjectID from "../ObjectID";
+import { readMiscDataId } from "./MiscDataId";
+import { getDefaultLayerRotation } from "./ScheduleLayerDefaults";
+
+/*
+ * WHO TAKES TURNS.
+ *
+ * A new on-call schedule used to cover nobody: Create On-Call Schedule asked
+ * for a name, a time zone and a description, and the schedule only put
+ * anyone on call once a layer had been added on its Layers page and people
+ * added to it one at a time. A policy that escalated to it paged no one
+ * meanwhile. Now the create form also asks "Who takes turns?", with the
+ * people picker.
+ *
+ * The picks travel with the create as misc data: the people under
+ * firstLayerUsers (user ids, in the order they take turns) and, when the form
+ * says how long each turn lasts, that rotation under firstLayerRotation (a
+ * Recurring, as a layer's own rotation is written). The server reads them
+ * here and, once the schedule exists, adds its first layer - "Layer 1", on
+ * call from now, handing off once per rotation - with those people in that
+ * order (OnCallDutyPolicyScheduleService.create).
+ *
+ * Nobody picked, or nothing sent (an API caller, Terraform, an import): no
+ * layer, exactly as before.
+ *
+ * React-free and server-safe: the server, the dashboard and their tests read
+ * it.
+ */
+
+export const SCHEDULE_FIRST_LAYER_USERS_KEY: string = "firstLayerUsers";
+
+export const SCHEDULE_FIRST_LAYER_ROTATION_KEY: string = "firstLayerRotation";
+
+export interface ScheduleFirstLayer {
+  /*
+   * Who takes turns, in the order they do: user ids, lowercased, each once.
+   * Never empty.
+   */
+  userIds: Array<string>;
+  // How long each turn lasts.
+  rotation: Recurring;
+}
+
+const EVENT_INTERVALS: Array<string> = Object.values(EventInterval);
+
+/*
+ * The rotation the create asks the first layer to hand off on. Not sent:
+ * the default, a week. Anything sent that is not a rotation of whole,
+ * positive intervals is refused rather than replaced: the caller asked for
+ * a rotation, and a layer that silently hands off on another one would page
+ * the wrong person.
+ */
+export const readScheduleFirstLayerRotation: (value: unknown) => Recurring = (
+  value: unknown,
+): Recurring => {
+  if (value === undefined || value === null) {
+    return getDefaultLayerRotation();
+  }
+
+  const invalid: BadDataException = new BadDataException(
+    `${SCHEDULE_FIRST_LAYER_ROTATION_KEY} must be a rotation: how many hours, days, weeks, months or years each turn lasts.`,
+  );
+
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw invalid;
+  }
+
+  let rotation: Recurring;
+
+  try {
+    rotation =
+      value instanceof Recurring
+        ? value
+        : Recurring.fromJSON(value as JSONObject);
+  } catch {
+    throw invalid;
+  }
+
+  const count: number = rotation.intervalCount?.toNumber();
+
+  if (
+    !EVENT_INTERVALS.includes(rotation.intervalType) ||
+    typeof count !== "number" ||
+    !Number.isInteger(count) ||
+    count < 1
+  ) {
+    throw invalid;
+  }
+
+  // A copy of its own: the caller's value is left alone.
+  return Recurring.fromJSON(rotation.toJSON());
+};
+
+/**
+ * Who takes turns in a new schedule, and how long each turn lasts, read from
+ * the create's misc data.
+ *
+ * Returns null when there is nobody: no misc data, no firstLayerUsers, or an
+ * empty list - the schedule is created without layers, as before. Each
+ * person is listed once (compared without case), in the order sent. A list
+ * that holds something other than user ids is refused rather than skipped,
+ * and so is a rotation that is not one (readScheduleFirstLayerRotation): a
+ * caller who asked for people to take turns must not get a schedule that
+ * silently covers nobody.
+ */
+export const readScheduleFirstLayer: (
+  miscDataProps: JSONObject | null | undefined,
+) => ScheduleFirstLayer | null = (
+  miscDataProps: JSONObject | null | undefined,
+): ScheduleFirstLayer | null => {
+  if (
+    !miscDataProps ||
+    typeof miscDataProps !== "object" ||
+    Array.isArray(miscDataProps)
+  ) {
+    return null;
+  }
+
+  // Checked even with nobody to put in the layer: a bad value is a mistake.
+  const rotation: Recurring = readScheduleFirstLayerRotation(
+    miscDataProps[SCHEDULE_FIRST_LAYER_ROTATION_KEY],
+  );
+
+  const value: unknown = miscDataProps[SCHEDULE_FIRST_LAYER_USERS_KEY];
+
+  if (value === undefined || value === null) {
+    return null;
+  }
+
+  if (!Array.isArray(value)) {
+    throw new BadDataException(
+      `${SCHEDULE_FIRST_LAYER_USERS_KEY} must be a list of user ids.`,
+    );
+  }
+
+  const userIds: Array<string> = [];
+
+  for (const entry of value) {
+    const id: string | null = readMiscDataId(entry);
+
+    if (!id || !ObjectID.isValidUUID(id)) {
+      throw new BadDataException(
+        `${SCHEDULE_FIRST_LAYER_USERS_KEY} must be a list of user ids. ${JSON.stringify(
+          entry instanceof ObjectID ? entry.toString() : entry,
+        )} is not one.`,
+      );
+    }
+
+    const normalized: string = id.toLowerCase();
+
+    if (!userIds.includes(normalized)) {
+      userIds.push(normalized);
+    }
+  }
+
+  if (userIds.length === 0) {
+    return null;
+  }
+
+  return { userIds, rotation };
+};

package/Types/OnCallDutyPolicy/ScheduleLayerDefaults.ts

@@ -0,0 +1,160 @@
+import OnCallDutyPolicyScheduleLayer from "../../Models/DatabaseModels/OnCallDutyPolicyScheduleLayer";
+import OneUptimeDate from "../Date";
+import EventInterval from "../Events/EventInterval";
+import Recurring from "../Events/Recurring";
+import ObjectID from "../ObjectID";
+import PositiveNumber from "../PositiveNumber";
+import RestrictionTimes from "./RestrictionTimes";
+
+/*
+ * A NEW LAYER OF AN ON-CALL SCHEDULE, AS IT STARTS.
+ *
+ * One builder for every layer OneUptime adds on someone's behalf, so they
+ * all start the same way:
+ *
+ *   - the first layer of a schedule created with "Who takes turns?"
+ *     (OnCallDutyPolicyScheduleService.create), and
+ *   - a layer added with "Add Layer" on a schedule's Layers page.
+ *
+ * A new layer:
+ *
+ *   - is on call from now: the first person in it is on call at once;
+ *   - hands off once a week, the rotation most on-call teams run, unless the
+ *     caller picks another;
+ *   - hands off for the first time one rotation after it starts, at the same
+ *     time of day in the schedule's time zone;
+ *   - is on call around the clock (no restriction times).
+ *
+ * Everything can be changed on the layer afterwards. A layer created through
+ * the API with no rotation still gets its column's own default (a day), as it
+ * always did: this is what the product picks, not the API contract.
+ *
+ * Server-safe and React-free: the server, the dashboard and their tests use it.
+ */
+
+// How long each turn of a new layer lasts, unless someone picks another.
+export const DEFAULT_LAYER_ROTATION_INTERVAL_TYPE: EventInterval =
+  EventInterval.Week;
+
+export const DEFAULT_LAYER_ROTATION_INTERVAL_COUNT: number = 1;
+
+export const getDefaultLayerRotation: () => Recurring = (): Recurring => {
+  const rotation: Recurring = new Recurring();
+  rotation.intervalType = DEFAULT_LAYER_ROTATION_INTERVAL_TYPE;
+  rotation.intervalCount = new PositiveNumber(
+    DEFAULT_LAYER_ROTATION_INTERVAL_COUNT,
+  );
+  return rotation;
+};
+
+// "Layer 2": the name a layer is given after its place in the schedule.
+export const getLayerName: (position: number) => string = (
+  position: number,
+): string => {
+  return `Layer ${position}`;
+};
+
+/*
+ * The name of a layer added at `order`: "Layer <order>", or the next number
+ * up that no layer of the schedule is called yet. The order alone is not
+ * enough: deleting a layer in the middle moves the ones below it up but
+ * leaves their names, so "Layer 3" can still exist on a schedule of two.
+ */
+export const getNewLayerName: (data: {
+  order: number;
+  existingNames: Array<string>;
+}) => string = (data: {
+  order: number;
+  existingNames: Array<string>;
+}): string => {
+  const taken: Set<string> = new Set<string>(data.existingNames);
+
+  let position: number = Math.max(1, Math.floor(data.order) || 1);
+
+  while (taken.has(getLayerName(position))) {
+    position++;
+  }
+
+  return getLayerName(position);
+};
+
+/*
+ * When a layer that starts at `startsAt` first hands off: one rotation
+ * later, counted in calendar units in the schedule's time zone, so a weekly
+ * layer started on a Tuesday at 14:30 hands off the next Tuesday at 14:30 -
+ * across a daylight saving change too. Hourly rotations are counted in
+ * absolute hours, as the layer engine counts them.
+ */
+export const getFirstHandOffTime: (data: {
+  startsAt: Date;
+  rotation: Recurring;
+  timezone?: string | undefined;
+}) => Date = (data: {
+  startsAt: Date;
+  rotation: Recurring;
+  timezone?: string | undefined;
+}): Date => {
+  const rotation: Recurring = Recurring.fromJSON(data.rotation);
+
+  const count: number = Math.max(
+    1,
+    Math.floor(rotation.intervalCount.toNumber()) || 1,
+  );
+
+  return OneUptimeDate.addRemoveCalendarUnits(
+    data.startsAt,
+    Recurring.toCalendarUnit(rotation.intervalType),
+    count,
+    data.timezone || undefined,
+  );
+};
+
+export interface NewScheduleLayerData {
+  onCallDutyPolicyScheduleId: ObjectID;
+  projectId: ObjectID;
+  name: string;
+  // Left out, the layer service puts the layer last.
+  order?: number | undefined;
+  // How long each turn lasts. Default: getDefaultLayerRotation (a week).
+  rotation?: Recurring | undefined;
+  // When the first turn starts. Default: now.
+  startsAt?: Date | undefined;
+  // The schedule's time zone, which hand-off times are kept in.
+  timezone?: string | undefined;
+}
+
+// A new layer, ready to be created (see the note at the top).
+export const buildNewScheduleLayer: (
+  data: NewScheduleLayerData,
+) => OnCallDutyPolicyScheduleLayer = (
+  data: NewScheduleLayerData,
+): OnCallDutyPolicyScheduleLayer => {
+  const startsAt: Date = data.startsAt || OneUptimeDate.getCurrentDate();
+
+  // A copy: the layer must not share a rotation the caller may change.
+  const rotation: Recurring = data.rotation
+    ? Recurring.fromJSON(Recurring.fromJSON(data.rotation).toJSON())
+    : getDefaultLayerRotation();
+
+  const layer: OnCallDutyPolicyScheduleLayer =
+    new OnCallDutyPolicyScheduleLayer();
+
+  layer.onCallDutyPolicyScheduleId = data.onCallDutyPolicyScheduleId;
+  layer.projectId = data.projectId;
+  layer.name = data.name;
+
+  if (data.order !== undefined) {
+    layer.order = data.order;
+  }
+
+  layer.startsAt = startsAt;
+  layer.rotation = rotation;
+  layer.handOffTime = getFirstHandOffTime({
+    startsAt: startsAt,
+    rotation: rotation,
+    timezone: data.timezone,
+  });
+  layer.restrictionTimes = RestrictionTimes.getDefault();
+
+  return layer;
+};