@oneuptime/common 14.0.7 → 14.0.8

package/Models/DatabaseModels/StatusPage.ts

@@ -3037,6 +3037,61 @@ export default class StatusPage extends BaseModel {
   })
   public showIncidentsOnStatusPage?: boolean = undefined;
 
+  /*
+   * A page with this on shows, and notifies its subscribers of, only the
+   * incidents scoped to it (Incident.statusPages). Unscoped incidents never
+   * reach it. That matters for a monitor shared by many pages: incidents
+   * created from it by monitor criteria, Slack, Teams, the API or AI carry no
+   * scope, so without this switch they would reach every page within a minute.
+   * With it, none of these pages hears about such an incident until someone
+   * scopes it to them.
+   *
+   * Not plan-gated, unlike showIncidentsOnStatusPage: it only ever narrows
+   * what a page shows.
+   */
+  @ColumnAccessControl({
+    create: [
+      Permission.ProjectOwner,
+      Permission.ProjectAdmin,
+      Permission.ProjectMember,
+      Permission.StatusPageAdmin,
+      Permission.StatusPageMember,
+      Permission.CreateProjectStatusPage,
+    ],
+    read: [
+      Permission.ProjectOwner,
+      Permission.ProjectAdmin,
+      Permission.ProjectMember,
+      Permission.Viewer,
+      Permission.StatusPageAdmin,
+      Permission.StatusPageMember,
+      Permission.StatusPageViewer,
+      Permission.ReadProjectStatusPage,
+    ],
+    update: [
+      Permission.ProjectOwner,
+      Permission.ProjectAdmin,
+      Permission.ProjectMember,
+      Permission.StatusPageAdmin,
+      Permission.StatusPageMember,
+      Permission.EditProjectStatusPage,
+    ],
+  })
+  @TableColumn({
+    isDefaultValueColumn: true,
+    type: TableColumnType.Boolean,
+    title: "Only Show Incidents Scoped to This Page",
+    description:
+      "When on, this status page shows and notifies its subscribers about only the incidents limited to it. Incidents that are not limited to any status page never reach it.",
+    defaultValue: false,
+  })
+  @Column({
+    type: ColumnType.Boolean,
+    default: false,
+    nullable: false,
+  })
+  public onlyShowScopedIncidents?: boolean = undefined;
+
   @ColumnAccessControl({
     create: [
       Permission.ProjectOwner,

package/Models/DatabaseModels/StatusPageSubscriber.ts

@@ -765,6 +765,134 @@ export default class StatusPageSubscriber extends BaseModel {
   })
   public isUnsubscribed?: boolean = undefined;
 
+  /*
+   * When this subscription was cancelled, whoever cancelled it: the recipient
+   * through the unsubscribe link or the manage page, or a teammate on the
+   * dashboard. Set by StatusPageSubscriberService when Is Unsubscribed turns
+   * on and cleared when it turns off, so the subscriber lists can show and
+   * filter on it. Subscriptions cancelled before this column existed have
+   * none.
+   *
+   * Computed and never taken from a client. Nobody can write it: the service
+   * writes it as root, after the caller's own update.
+   */
+  @ColumnAccessControl({
+    create: [],
+    read: [
+      Permission.ProjectOwner,
+      Permission.ProjectAdmin,
+      Permission.ProjectMember,
+      Permission.Viewer,
+      Permission.StatusPageAdmin,
+      Permission.StatusPageMember,
+      Permission.StatusPageViewer,
+      Permission.ReadStatusPageSubscriber,
+    ],
+    update: [],
+  })
+  @TableColumn({
+    computed: true,
+    required: false,
+    type: TableColumnType.Date,
+    title: "Unsubscribed At",
+    description:
+      "When this subscriber unsubscribed. Set by OneUptime when Is Unsubscribed is turned on, and cleared when it is turned off; any value sent for it is ignored.",
+    example: "2024-01-15T09:30:00.000Z",
+  })
+  @Column({
+    type: ColumnType.Date,
+    nullable: true,
+  })
+  public unsubscribedAt?: Date = undefined;
+
+  /*
+   * The secret in this subscriber's unsubscribe link
+   * ({statusPageUrl}/unsubscribe/{id}-{token}, see
+   * Common/Types/StatusPage/StatusPageSubscriberUnsubscribe). Holding the
+   * link is what lets its recipient unsubscribe without signing in, which is
+   * the only way a subscriber of a private status page can.
+   *
+   * 32 random bytes as hex, minted by StatusPageSubscriberService when the
+   * subscriber is created; rows that predate it were backfilled by the
+   * migration that added it. It is computed so a create from the dashboard or
+   * the API passes the column check (which exempts computed columns only on
+   * create) while the service overwrites anything a client sends, and nobody
+   * can read or change it: it only ever leaves the server inside a link sent
+   * to the subscription's own contact.
+   */
+  @ColumnAccessControl({
+    create: [],
+    read: [],
+    update: [],
+  })
+  @TableColumn({
+    computed: true,
+    hideColumnInDocumentation: true,
+    required: false,
+    type: TableColumnType.ShortText,
+    title: "Unsubscribe Token",
+    description:
+      "Random secret in this subscriber's unsubscribe link. Generated by OneUptime; never readable through the API.",
+  })
+  @Column({
+    type: ColumnType.ShortText,
+    length: ColumnLength.ShortText,
+    nullable: true,
+  })
+  public unsubscribeToken?: string = undefined;
+
+  /*
+   * Whether the status page's team added this subscriber - from the
+   * dashboard, with an API key (the REST API, Terraform, a script loading a
+   * list of addresses) or by a workflow - rather than its owner signing up
+   * on the status page.
+   *
+   * A subscriber the team added may be a shared address, such as a site's
+   * mailing list, that any one reader could take off the page with the
+   * unsubscribe link. So when such a subscriber unsubscribes itself, the
+   * page's owners are emailed, the unsubscribe page warns the reader first,
+   * and the subscriber lists name it (see StatusPageSubscriberService).
+   *
+   * Created By (createdByUserId) cannot tell this on its own: only a
+   * signed-in user's create carries one, and an API key's or a workflow's
+   * does not. StatusPageSubscriberService sets this on every create - true
+   * unless the create is a sign-up on the status page - and nobody else can
+   * write it. Subscribers created before it existed were given it from
+   * Created By, so a subscriber an API key added before then reads as a
+   * sign-up.
+   */
+  @ColumnAccessControl({
+    create: [],
+    read: [
+      Permission.ProjectOwner,
+      Permission.ProjectAdmin,
+      Permission.ProjectMember,
+      Permission.Viewer,
+      Permission.StatusPageAdmin,
+      Permission.StatusPageMember,
+      Permission.StatusPageViewer,
+      Permission.ReadStatusPageSubscriber,
+    ],
+    update: [],
+  })
+  @TableColumn({
+    isDefaultValueColumn: true,
+    computed: true,
+    required: true,
+    type: TableColumnType.Boolean,
+    title: "Is Added By Team",
+    description:
+      "Whether your team added this subscriber (from the dashboard, with an API key or by a workflow) rather than the subscriber signing up on the status page. Set by OneUptime when the subscriber is created; any value sent for it is ignored.",
+    defaultValue: false,
+    example: true,
+  })
+  @Column({
+    type: ColumnType.Boolean,
+    nullable: false,
+    default: false,
+  })
+  public isAddedByTeam?: boolean = undefined;
+
   @ColumnAccessControl({
     create: [
       Permission.ProjectOwner,

package/Server/API/IncidentAPI.ts

@@ -30,6 +30,13 @@ import IncidentAIContextBuilder, {
 } from "../Utils/AI/IncidentAIContextBuilder";
 import JSONFunctions from "../../Types/JSONFunctions";
 import Permission, { UserPermission } from "../../Types/Permission";
+import { JSONObject } from "../../Types/JSON";
+import IncidentSubscriberAudience, {
+  IncidentSubscriberAudienceResult,
+} from "../../Types/StatusPage/IncidentSubscriberAudience";
+import IncidentSubscriberAudienceBuilder, {
+  IncidentSubscriberAudienceRequest,
+} from "../Utils/StatusPage/IncidentSubscriberAudienceBuilder";
 
 export default class IncidentAPI extends BaseAPI<
   Incident,
@@ -83,6 +90,161 @@ export default class IncidentAPI extends BaseAPI<
         }
       },
     );
+
+    /*
+     * Who an incident's status page notifications would reach, before it is
+     * declared or a public note is posted (see IncidentSubscriberAudience).
+     * A POST because the monitors and status pages of an incident being
+     * declared travel in the body.
+     */
+    this.router.post(
+      `${new this.entityType()
+        .getCrudApiPath()
+        ?.toString()}/subscriber-audience`,
+      UserMiddleware.getUserMiddleware,
+      UserMiddleware.requireUserAuthentication,
+      async (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => {
+        try {
+          await this.getSubscriberAudience(req, res);
+        } catch (err) {
+          next(err);
+        }
+      },
+    );
+  }
+
+  private async getSubscriberAudience(
+    req: ExpressRequest,
+    res: ExpressResponse,
+  ): Promise<void> {
+    const props: DatabaseCommonInteractionProps =
+      await CommonAPI.getDatabaseCommonInteractionProps(req);
+
+    /*
+     * The project is the caller's tenant. Project API keys are admitted like
+     * signed-in members: the permission check below and the reads the
+     * answer is built from are what bound it.
+     */
+    const projectId: ObjectID = CommonAPI.assertTenantScoped(props);
+
+    // One of the roles that may see the audience (read as Allow grants).
+    IncidentSubscriberAudienceBuilder.assertCallerMaySeeAudience(props);
+
+    const request: IncidentSubscriberAudienceRequest =
+      IncidentAPI.parseSubscriberAudienceRequest({
+        body: req.body,
+        projectId: projectId,
+        props: props,
+      });
+
+    const audience: IncidentSubscriberAudienceResult =
+      await IncidentSubscriberAudienceBuilder.build(request);
+
+    Response.setNoCacheHeaders(res);
+
+    return Response.sendJsonObjectResponse(
+      req,
+      res,
+      IncidentSubscriberAudience.toJSON(audience),
+    );
+  }
+
+  /*
+   * The request body: {incidentId} for an incident that exists, or
+   * {monitorIds, statusPageIds} for one being declared - never both. With
+   * incidentId, excludeStatusPagesNotifiedOnCreation asks who a Retry of
+   * its 'created' notification reaches.
+   */
+  public static parseSubscriberAudienceRequest(data: {
+    body: unknown;
+    projectId: ObjectID;
+    props: DatabaseCommonInteractionProps;
+  }): IncidentSubscriberAudienceRequest {
+    const body: JSONObject =
+      data.body && typeof data.body === "object" && !Array.isArray(data.body)
+        ? (data.body as JSONObject)
+        : {};
+
+    const hasIncidentId: boolean =
+      body["incidentId"] !== undefined && body["incidentId"] !== null;
+    const hasDraft: boolean =
+      (body["monitorIds"] !== undefined && body["monitorIds"] !== null) ||
+      (body["statusPageIds"] !== undefined && body["statusPageIds"] !== null);
+
+    if (hasIncidentId && hasDraft) {
+      throw new BadDataException(
+        "Send either incidentId, or monitorIds and statusPageIds - not both.",
+      );
+    }
+
+    if (hasIncidentId) {
+      return {
+        projectId: data.projectId,
+        props: data.props,
+        incidentId: IncidentAPI.parseObjectID(body["incidentId"], "incidentId"),
+        // Who a Retry of its 'created' notification reaches: only a real yes.
+        ...(body["excludeStatusPagesNotifiedOnCreation"] === true
+          ? { excludeStatusPagesNotifiedOnCreation: true }
+          : {}),
+      };
+    }
+
+    if (!hasDraft) {
+      throw new BadDataException(
+        "Send incidentId, or monitorIds and statusPageIds.",
+      );
+    }
+
+    return {
+      projectId: data.projectId,
+      props: data.props,
+      monitorIds: IncidentAPI.parseObjectIDs(body["monitorIds"], "monitorIds"),
+      statusPageIds: IncidentAPI.parseObjectIDs(
+        body["statusPageIds"],
+        "statusPageIds",
+      ),
+    };
+  }
+
+  // An id as a string or a serialized ObjectID.
+  private static parseObjectID(value: unknown, name: string): ObjectID {
+    let id: string = "";
+
+    if (typeof value === "string") {
+      id = value;
+    } else if (value instanceof ObjectID) {
+      id = value.toString();
+    } else if (value && typeof value === "object") {
+      id = new ObjectID(value as JSONObject).toString();
+    }
+
+    id = id.trim();
+
+    if (!id || !ObjectID.isValidUUID(id)) {
+      throw new BadDataException(`${name} must be a valid ID.`);
+    }
+
+    return new ObjectID(id);
+  }
+
+  private static parseObjectIDs(value: unknown, name: string): Array<ObjectID> {
+    if (value === undefined || value === null) {
+      return [];
+    }
+
+    if (!Array.isArray(value)) {
+      throw new BadDataException(`${name} must be a list of IDs.`);
+    }
+
+    if (value.length > IncidentSubscriberAudience.maxIdsPerRequest) {
+      throw new BadDataException(
+        `${name} can list at most ${IncidentSubscriberAudience.maxIdsPerRequest} IDs.`,
+      );
+    }
+
+    return value.map((item: unknown): ObjectID => {
+      return IncidentAPI.parseObjectID(item, name);
+    });
   }
 
   private async getPostmortemAttachment(