feat(alerts): add scheduleStartAt + scheduleOffsetMinutes

.changeset/silent-zebras-switch.md

@@ -0,0 +1,7 @@
+---
+"@hyperdx/api": minor
+"@hyperdx/app": minor
+"@hyperdx/common-utils": minor
+---
+
+feat(alerts): add anchored alert scheduling with `scheduleStartAt` and `scheduleOffsetMinutes`

packages/api/openapi.json

@@ -169,6 +169,20 @@
             "$ref": "#/components/schemas/AlertInterval",
             "example": "1h"
           },
+          "scheduleOffsetMinutes": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC).",
+            "nullable": true,
+            "example": 2
+          },
+          "scheduleStartAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.",
+            "nullable": true,
+            "example": "2026-02-08T10:00:00.000Z"
+          },
           "source": {
             "$ref": "#/components/schemas/AlertSource",
             "example": "tile"

packages/api/src/controllers/alerts.ts

@@ -24,6 +24,8 @@ export type AlertInput = {
   source?: AlertSource;
   channel: AlertChannel;
   interval: AlertInterval;
+  scheduleOffsetMinutes?: number;
+  scheduleStartAt?: string | null;
   thresholdType: AlertThresholdType;
   threshold: number;
 
@@ -105,9 +107,30 @@ export const validateAlertInput = async (
 };
 
 const makeAlert = (alert: AlertInput, userId?: ObjectId): Partial<IAlert> => {
+  // Preserve existing DB value when scheduleStartAt is omitted from updates
+  // (undefined), while still allowing explicit clears via null.
+  const hasScheduleStartAt = alert.scheduleStartAt !== undefined;
+  // If scheduleStartAt is explicitly provided, offset-based alignment is ignored.
+  // Force persisted offset to 0 so updates can't leave stale non-zero offsets.
+  // If scheduleStartAt is explicitly cleared and offset is omitted, also reset
+  // to 0 to avoid preserving stale values from older documents.
+  const normalizedScheduleOffsetMinutes =
+    hasScheduleStartAt && alert.scheduleStartAt != null
+      ? 0
+      : hasScheduleStartAt && alert.scheduleOffsetMinutes == null
+        ? 0
+        : alert.scheduleOffsetMinutes;
+
   return {
     channel: alert.channel,
     interval: alert.interval,
+    ...(normalizedScheduleOffsetMinutes != null && {
+      scheduleOffsetMinutes: normalizedScheduleOffsetMinutes,
+    }),
+    ...(hasScheduleStartAt && {
+      scheduleStartAt:
+        alert.scheduleStartAt == null ? null : new Date(alert.scheduleStartAt),
+    }),
     source: alert.source,
     threshold: alert.threshold,
     thresholdType: alert.thresholdType,

packages/api/src/models/alert.ts

@@ -1,3 +1,4 @@
+import { ALERT_INTERVAL_TO_MINUTES } from '@hyperdx/common-utils/dist/types';
 import mongoose, { Schema } from 'mongoose';
 
 import type { ObjectId } from '.';
@@ -44,6 +45,8 @@ export interface IAlert {
   id: string;
   channel: AlertChannel;
   interval: AlertInterval;
+  scheduleOffsetMinutes?: number;
+  scheduleStartAt?: Date | null;
   source?: AlertSource;
   state: AlertState;
   team: ObjectId;
@@ -88,6 +91,29 @@ const AlertSchema = new Schema<IAlert>(
       type: String,
       required: true,
     },
+    scheduleOffsetMinutes: {
+      type: Number,
+      min: 0,
+      // Maximum offset for daily windows (24h - 1 minute).
+      max: 1439,
+      validate: {
+        validator: function (this: IAlert, value: number | undefined) {
+          if (value == null) {
+            return true;
+          }
+
+          const intervalMinutes = ALERT_INTERVAL_TO_MINUTES[this.interval];
+          return intervalMinutes == null || value < intervalMinutes;
+        },
+        message:
+          'scheduleOffsetMinutes must be less than the alert interval in minutes',
+      },
+      required: false,
+    },
+    scheduleStartAt: {
+      type: Date,
+      required: false,
+    },
     channel: Schema.Types.Mixed, // slack, email, etc
     state: {
       type: String,

packages/api/src/routers/api/__tests__/alerts.test.ts

@@ -5,7 +5,7 @@ import {
   makeTile,
   randomMongoId,
 } from '@/fixtures';
-import Alert from '@/models/alert';
+import Alert, { AlertSource, AlertThresholdType } from '@/models/alert';
 import Webhook, { WebhookDocument, WebhookService } from '@/models/webhook';
 
 const MOCK_TILES = [makeTile(), makeTile(), makeTile(), makeTile(), makeTile()];
@@ -116,6 +116,245 @@ describe('alerts router', () => {
     expect(allAlerts.body.data[0].threshold).toBe(10);
   });
 
+  it('preserves scheduleStartAt when omitted in updates and clears when null', async () => {
+    const dashboard = await agent
+      .post('/dashboards')
+      .send(MOCK_DASHBOARD)
+      .expect(200);
+
+    const scheduleStartAt = '2024-01-01T00:00:00.000Z';
+    const createdAlert = await agent
+      .post('/alerts')
+      .send({
+        ...makeAlertInput({
+          dashboardId: dashboard.body.id,
+          tileId: dashboard.body.tiles[0].id,
+          webhookId: webhook._id.toString(),
+        }),
+        scheduleStartAt,
+      })
+      .expect(200);
+
+    const updatePayload = {
+      channel: createdAlert.body.data.channel,
+      interval: createdAlert.body.data.interval,
+      threshold: 10,
+      thresholdType: createdAlert.body.data.thresholdType,
+      source: createdAlert.body.data.source,
+      dashboardId: dashboard.body.id,
+      tileId: dashboard.body.tiles[0].id,
+    };
+
+    await agent
+      .put(`/alerts/${createdAlert.body.data._id}`)
+      .send(updatePayload)
+      .expect(200);
+
+    const alertAfterOmittedScheduleStartAt = await Alert.findById(
+      createdAlert.body.data._id,
+    );
+    expect(
+      alertAfterOmittedScheduleStartAt?.scheduleStartAt?.toISOString(),
+    ).toBe(scheduleStartAt);
+
+    await agent
+      .put(`/alerts/${createdAlert.body.data._id}`)
+      .send({
+        ...updatePayload,
+        scheduleStartAt: null,
+      })
+      .expect(200);
+
+    const alertAfterNullScheduleStartAt = await Alert.findById(
+      createdAlert.body.data._id,
+    );
+    expect(alertAfterNullScheduleStartAt?.scheduleStartAt).toBeNull();
+  });
+
+  it('preserves scheduleOffsetMinutes when schedule fields are omitted in updates', async () => {
+    const dashboard = await agent
+      .post('/dashboards')
+      .send(MOCK_DASHBOARD)
+      .expect(200);
+
+    const createdAlert = await agent
+      .post('/alerts')
+      .send({
+        ...makeAlertInput({
+          dashboardId: dashboard.body.id,
+          tileId: dashboard.body.tiles[0].id,
+          interval: '15m',
+          webhookId: webhook._id.toString(),
+        }),
+        scheduleOffsetMinutes: 2,
+      })
+      .expect(200);
+
+    await agent
+      .put(`/alerts/${createdAlert.body.data._id}`)
+      .send({
+        channel: createdAlert.body.data.channel,
+        interval: createdAlert.body.data.interval,
+        threshold: 10,
+        thresholdType: createdAlert.body.data.thresholdType,
+        source: createdAlert.body.data.source,
+        dashboardId: dashboard.body.id,
+        tileId: dashboard.body.tiles[0].id,
+      })
+      .expect(200);
+
+    const updatedAlert = await Alert.findById(createdAlert.body.data._id);
+    expect(updatedAlert?.scheduleOffsetMinutes).toBe(2);
+    expect(updatedAlert?.scheduleStartAt).toBeUndefined();
+  });
+
+  it('resets scheduleOffsetMinutes to 0 when scheduleStartAt is set without offset', async () => {
+    const dashboard = await agent
+      .post('/dashboards')
+      .send(MOCK_DASHBOARD)
+      .expect(200);
+
+    const createdAlert = await agent
+      .post('/alerts')
+      .send({
+        ...makeAlertInput({
+          dashboardId: dashboard.body.id,
+          tileId: dashboard.body.tiles[0].id,
+          webhookId: webhook._id.toString(),
+        }),
+        scheduleOffsetMinutes: 2,
+      })
+      .expect(200);
+
+    expect(createdAlert.body.data.scheduleOffsetMinutes).toBe(2);
+
+    const scheduleStartAt = '2024-01-01T00:00:00.000Z';
+
+    await agent
+      .put(`/alerts/${createdAlert.body.data._id}`)
+      .send({
+        channel: createdAlert.body.data.channel,
+        interval: createdAlert.body.data.interval,
+        threshold: createdAlert.body.data.threshold,
+        thresholdType: createdAlert.body.data.thresholdType,
+        source: createdAlert.body.data.source,
+        dashboardId: dashboard.body.id,
+        tileId: dashboard.body.tiles[0].id,
+        scheduleStartAt,
+      })
+      .expect(200);
+
+    const updatedAlert = await Alert.findById(createdAlert.body.data._id);
+    expect(updatedAlert?.scheduleOffsetMinutes).toBe(0);
+    expect(updatedAlert?.scheduleStartAt?.toISOString()).toBe(scheduleStartAt);
+  });
+
+  it('resets stale scheduleOffsetMinutes when scheduleStartAt is cleared without offset', async () => {
+    const dashboard = await agent
+      .post('/dashboards')
+      .send(MOCK_DASHBOARD)
+      .expect(200);
+
+    const staleAlert = await Alert.create({
+      team: team._id,
+      channel: {
+        type: 'webhook',
+        webhookId: webhook._id.toString(),
+      },
+      interval: '15m',
+      threshold: 8,
+      thresholdType: AlertThresholdType.ABOVE,
+      source: AlertSource.TILE,
+      dashboard: dashboard.body.id,
+      tileId: dashboard.body.tiles[0].id,
+      scheduleOffsetMinutes: 2,
+      scheduleStartAt: new Date('2024-01-01T00:00:00.000Z'),
+    });
+
+    await agent
+      .put(`/alerts/${staleAlert._id.toString()}`)
+      .send({
+        ...makeAlertInput({
+          dashboardId: dashboard.body.id,
+          tileId: dashboard.body.tiles[0].id,
+          interval: '15m',
+          webhookId: webhook._id.toString(),
+        }),
+        scheduleStartAt: null,
+      })
+      .expect(200);
+
+    const updatedAlert = await Alert.findById(staleAlert._id);
+    expect(updatedAlert?.scheduleOffsetMinutes).toBe(0);
+    expect(updatedAlert?.scheduleStartAt).toBeNull();
+  });
+
+  it('rejects scheduleStartAt values more than 1 year in the future', async () => {
+    const dashboard = await agent
+      .post('/dashboards')
+      .send(MOCK_DASHBOARD)
+      .expect(200);
+
+    const farFutureScheduleStartAt = new Date(
+      Date.now() + 366 * 24 * 60 * 60 * 1000,
+    ).toISOString();
+
+    await agent
+      .post('/alerts')
+      .send({
+        ...makeAlertInput({
+          dashboardId: dashboard.body.id,
+          tileId: dashboard.body.tiles[0].id,
+          webhookId: webhook._id.toString(),
+        }),
+        scheduleStartAt: farFutureScheduleStartAt,
+      })
+      .expect(400);
+  });
+
+  it('rejects scheduleStartAt values older than 10 years in the past', async () => {
+    const dashboard = await agent
+      .post('/dashboards')
+      .send(MOCK_DASHBOARD)
+      .expect(200);
+
+    const tooOldScheduleStartAt = new Date(
+      Date.now() - 11 * 365 * 24 * 60 * 60 * 1000,
+    ).toISOString();
+
+    await agent
+      .post('/alerts')
+      .send({
+        ...makeAlertInput({
+          dashboardId: dashboard.body.id,
+          tileId: dashboard.body.tiles[0].id,
+          webhookId: webhook._id.toString(),
+        }),
+        scheduleStartAt: tooOldScheduleStartAt,
+      })
+      .expect(400);
+  });
+
+  it('rejects scheduleOffsetMinutes when scheduleStartAt is provided', async () => {
+    const dashboard = await agent
+      .post('/dashboards')
+      .send(MOCK_DASHBOARD)
+      .expect(200);
+
+    await agent
+      .post('/alerts')
+      .send({
+        ...makeAlertInput({
+          dashboardId: dashboard.body.id,
+          tileId: dashboard.body.tiles[0].id,
+          webhookId: webhook._id.toString(),
+        }),
+        scheduleOffsetMinutes: 2,
+        scheduleStartAt: new Date().toISOString(),
+      })
+      .expect(400);
+  });
+
   it('preserves createdBy field during updates', async () => {
     const dashboard = await agent
       .post('/dashboards')