@oneuptime/common 12.0.0 → 12.0.2

package/Tests/Utils/StatusPage/ReportPeriod.test.ts

@@ -0,0 +1,218 @@
+/*
+ * The window a scheduled status page report covers.
+ *
+ * The reported bug: "is there a way to have the reports be sent out monthly,
+ * i.e. to show July 1st - July 31st?" - it was not, because the window was
+ * always "the last N days counted back from whenever the cron fired", so a
+ * monthly report sent on 1 Aug covered 2 Jul - 1 Aug and never lined up with a
+ * calendar month. These tests pin the calendar option that fixes it, the
+ * timezone the boundaries are resolved in, and the rolling behaviour that
+ * existing status pages keep.
+ */
+
+import OneUptimeDate from "../../../Types/Date";
+import EventInterval from "../../../Types/Events/EventInterval";
+import Recurring from "../../../Types/Events/Recurring";
+import PositiveNumber from "../../../Types/PositiveNumber";
+import StatusPageReportPeriodType from "../../../Types/StatusPage/StatusPageReportPeriodType";
+import Timezone from "../../../Types/Timezone";
+import StatusPageReportPeriodUtil, {
+  StatusPageReportPeriod,
+} from "../../../Utils/StatusPage/ReportPeriod";
+import { describe, expect, test } from "@jest/globals";
+
+function every(intervalType: EventInterval, intervalCount: number): Recurring {
+  const recurring: Recurring = new Recurring();
+  recurring.intervalType = intervalType;
+  recurring.intervalCount = new PositiveNumber(intervalCount);
+  return recurring;
+}
+
+function iso(date: Date): string {
+  return date.toISOString();
+}
+
+describe("StatusPageReportPeriodUtil.getReportPeriod", () => {
+  describe("the previous calendar period", () => {
+    test("a monthly report sent in August covers all of July", () => {
+      const period: StatusPageReportPeriod =
+        StatusPageReportPeriodUtil.getReportPeriod({
+          periodType: StatusPageReportPeriodType.PreviousCalendarPeriod,
+          reportRecurringInterval: every(EventInterval.Month, 1),
+          timezone: Timezone.UTC,
+          sentAt: OneUptimeDate.fromString("2026-08-01T09:00:00.000Z"),
+        });
+
+      expect(iso(period.startDate)).toBe("2026-07-01T00:00:00.000Z");
+      expect(iso(period.endDate)).toBe("2026-07-31T23:59:59.999Z");
+      expect(period.periodName).toBe("July 2026");
+      expect(period.reportDates).toBe("Jul 1, 2026 - Jul 31, 2026");
+      expect(period.numberOfDays).toBe(31);
+    });
+
+    test("still covers July when the email goes out later in August", () => {
+      /*
+       * The period is the last WHOLE one, not "the month before this instant",
+       * so moving the send time inside August must not slide the window.
+       */
+      const period: StatusPageReportPeriod =
+        StatusPageReportPeriodUtil.getReportPeriod({
+          periodType: StatusPageReportPeriodType.PreviousCalendarPeriod,
+          reportRecurringInterval: every(EventInterval.Month, 1),
+          timezone: Timezone.UTC,
+          sentAt: OneUptimeDate.fromString("2026-08-27T16:45:00.000Z"),
+        });
+
+      expect(iso(period.startDate)).toBe("2026-07-01T00:00:00.000Z");
+      expect(period.periodName).toBe("July 2026");
+    });
+
+    test("resolves the month boundary in the report timezone, not the server's", () => {
+      /*
+       * 1 Aug 03:00 UTC is still 31 Jul in New York, so a status page reporting
+       * in New York has not finished July yet and must report June.
+       */
+      const period: StatusPageReportPeriod =
+        StatusPageReportPeriodUtil.getReportPeriod({
+          periodType: StatusPageReportPeriodType.PreviousCalendarPeriod,
+          reportRecurringInterval: every(EventInterval.Month, 1),
+          timezone: Timezone.AmericaNew_York,
+          sentAt: OneUptimeDate.fromString("2026-08-01T03:00:00.000Z"),
+        });
+
+      // 1 Jun 00:00 EDT and 30 Jun 23:59:59.999 EDT, both UTC-4.
+      expect(iso(period.startDate)).toBe("2026-06-01T04:00:00.000Z");
+      expect(iso(period.endDate)).toBe("2026-07-01T03:59:59.999Z");
+      expect(period.periodName).toBe("June 2026");
+    });
+
+    test("a quarterly report covers the three whole months before it", () => {
+      const period: StatusPageReportPeriod =
+        StatusPageReportPeriodUtil.getReportPeriod({
+          periodType: StatusPageReportPeriodType.PreviousCalendarPeriod,
+          reportRecurringInterval: every(EventInterval.Month, 3),
+          timezone: Timezone.UTC,
+          sentAt: OneUptimeDate.fromString("2026-10-01T09:00:00.000Z"),
+        });
+
+      expect(iso(period.startDate)).toBe("2026-07-01T00:00:00.000Z");
+      expect(iso(period.endDate)).toBe("2026-09-30T23:59:59.999Z");
+      // Three months have no single name a reader knows, so it stays a range.
+      expect(period.periodName).toBe("Jul 1, 2026 - Sep 30, 2026");
+    });
+
+    test("a weekly report covers Monday to Sunday", () => {
+      // Wednesday 5 Aug 2026.
+      const period: StatusPageReportPeriod =
+        StatusPageReportPeriodUtil.getReportPeriod({
+          periodType: StatusPageReportPeriodType.PreviousCalendarPeriod,
+          reportRecurringInterval: every(EventInterval.Week, 1),
+          timezone: Timezone.UTC,
+          sentAt: OneUptimeDate.fromString("2026-08-05T09:00:00.000Z"),
+        });
+
+      // Monday 27 Jul through Sunday 2 Aug.
+      expect(iso(period.startDate)).toBe("2026-07-27T00:00:00.000Z");
+      expect(iso(period.endDate)).toBe("2026-08-02T23:59:59.999Z");
+      expect(period.periodName).toBe("the week of Jul 27, 2026");
+      expect(period.numberOfDays).toBe(7);
+    });
+
+    test("a daily report covers yesterday", () => {
+      const period: StatusPageReportPeriod =
+        StatusPageReportPeriodUtil.getReportPeriod({
+          periodType: StatusPageReportPeriodType.PreviousCalendarPeriod,
+          reportRecurringInterval: every(EventInterval.Day, 1),
+          timezone: Timezone.UTC,
+          sentAt: OneUptimeDate.fromString("2026-08-05T09:00:00.000Z"),
+        });
+
+      expect(iso(period.startDate)).toBe("2026-08-04T00:00:00.000Z");
+      expect(iso(period.endDate)).toBe("2026-08-04T23:59:59.999Z");
+      expect(period.periodName).toBe("Aug 4, 2026");
+    });
+
+    test("a yearly report covers the previous calendar year", () => {
+      const period: StatusPageReportPeriod =
+        StatusPageReportPeriodUtil.getReportPeriod({
+          periodType: StatusPageReportPeriodType.PreviousCalendarPeriod,
+          reportRecurringInterval: every(EventInterval.Year, 1),
+          timezone: Timezone.UTC,
+          sentAt: OneUptimeDate.fromString("2026-01-01T00:05:00.000Z"),
+        });
+
+      expect(iso(period.startDate)).toBe("2025-01-01T00:00:00.000Z");
+      expect(iso(period.endDate)).toBe("2025-12-31T23:59:59.999Z");
+      expect(period.periodName).toBe("2025");
+    });
+
+    test("falls back to a daily period when no frequency is configured", () => {
+      const period: StatusPageReportPeriod =
+        StatusPageReportPeriodUtil.getReportPeriod({
+          periodType: StatusPageReportPeriodType.PreviousCalendarPeriod,
+          timezone: Timezone.UTC,
+          sentAt: OneUptimeDate.fromString("2026-08-05T09:00:00.000Z"),
+        });
+
+      // Recurring's own default is every 1 day.
+      expect(iso(period.startDate)).toBe("2026-08-04T00:00:00.000Z");
+    });
+  });
+
+  describe("the rolling window", () => {
+    test("ends when the report is sent and runs back the configured days", () => {
+      const period: StatusPageReportPeriod =
+        StatusPageReportPeriodUtil.getReportPeriod({
+          periodType: StatusPageReportPeriodType.Rolling,
+          reportDataInDays: 30,
+          timezone: Timezone.UTC,
+          sentAt: OneUptimeDate.fromString("2026-07-30T09:00:00.000Z"),
+        });
+
+      expect(iso(period.startDate)).toBe("2026-06-30T09:00:00.000Z");
+      expect(iso(period.endDate)).toBe("2026-07-30T09:00:00.000Z");
+      expect(period.periodName).toBe("the last 30 days");
+    });
+
+    test("keeps the reportDates string custom email templates were written against", () => {
+      const period: StatusPageReportPeriod =
+        StatusPageReportPeriodUtil.getReportPeriod({
+          periodType: StatusPageReportPeriodType.Rolling,
+          reportDataInDays: 30,
+          timezone: Timezone.UTC,
+          sentAt: OneUptimeDate.fromString("2026-07-30T09:00:00.000Z"),
+        });
+
+      expect(period.reportDates).toBe("30 days (Jun 30, 2026 - Jul 30, 2026)");
+    });
+
+    test("is what a status page with no period configured gets", () => {
+      // Every column is null on status pages created before this setting existed.
+      const period: StatusPageReportPeriod =
+        StatusPageReportPeriodUtil.getReportPeriod({
+          sentAt: OneUptimeDate.fromString("2026-07-30T09:00:00.000Z"),
+        });
+
+      expect(iso(period.startDate)).toBe("2026-06-30T09:00:00.000Z");
+      expect(period.numberOfDays).toBe(
+        StatusPageReportPeriodUtil.DEFAULT_REPORT_DATA_IN_DAYS,
+      );
+      expect(period.timezone).toBe(Timezone.UTC);
+    });
+
+    test("refuses a zero, negative or non-numeric day count", () => {
+      for (const badValue of [0, -5, NaN, undefined]) {
+        const period: StatusPageReportPeriod =
+          StatusPageReportPeriodUtil.getReportPeriod({
+            periodType: StatusPageReportPeriodType.Rolling,
+            reportDataInDays: badValue as number,
+            sentAt: OneUptimeDate.fromString("2026-07-30T09:00:00.000Z"),
+          });
+
+        expect(period.numberOfDays).toBe(
+          StatusPageReportPeriodUtil.DEFAULT_REPORT_DATA_IN_DAYS,
+        );
+      }
+    });
+  });
+});

package/Tests/Utils/Telemetry/HostIpAddresses.test.ts

@@ -0,0 +1,291 @@
+import {
+  MAX_HOST_IP_ADDRESSES_LENGTH,
+  MAX_HOST_IP_ADDRESS_COUNT,
+  normalizeHostIpAddresses,
+} from "../../../Utils/Telemetry/HostIpAddresses";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * Regression suite for issue #3006. The OTel `host.ip` resource attribute
+ * is an array of every address on every interface, and a Docker host with
+ * IPv6 enabled reports one entry per bridge, per veth and per link-local.
+ * The reporter's host produced 55 addresses / ~1454 characters, which
+ * overflowed the then-varchar(500) Host.hostIpAddresses column and aborted
+ * the whole Host metadata write.
+ */
+
+/** Rebuilds the exact shape reported in the issue: 55 addresses. */
+function issueReporterAddresses(): Array<string> {
+  const addresses: Array<string> = [];
+
+  // 1 LAN IPv4.
+  addresses.push("192.168.1.42");
+
+  // 11 Docker bridge IPv4 addresses.
+  for (let i: number = 0; i < 11; i++) {
+    addresses.push(`172.${17 + i}.0.1`);
+  }
+
+  // 36 IPv6 link-local addresses.
+  for (let i: number = 0; i < 36; i++) {
+    addresses.push(`fe80::42:acff:fe11:${(0x1000 + i).toString(16)}`);
+  }
+
+  // 7 IPv6 ULA addresses.
+  for (let i: number = 0; i < 7; i++) {
+    addresses.push(`fd00:dead:beef:${i}::1`);
+  }
+
+  return addresses;
+}
+
+describe("normalizeHostIpAddresses", () => {
+  describe("empty and absent input", () => {
+    test("returns null for undefined", () => {
+      expect(normalizeHostIpAddresses(undefined)).toBeNull();
+    });
+
+    test("returns null for null", () => {
+      expect(normalizeHostIpAddresses(null)).toBeNull();
+    });
+
+    test("returns null for an empty array", () => {
+      expect(normalizeHostIpAddresses([])).toBeNull();
+    });
+
+    test("returns null when every entry is blank", () => {
+      expect(normalizeHostIpAddresses(["", "   ", "\t", "\n"])).toBeNull();
+    });
+
+    test("returns null rather than an empty string, so callers leave the column untouched", () => {
+      // An empty string would overwrite a previously discovered list with "".
+      expect(normalizeHostIpAddresses(["  "])).not.toBe("");
+    });
+  });
+
+  describe("basic joining", () => {
+    test("joins with ', ' to match the stored format", () => {
+      expect(normalizeHostIpAddresses(["192.168.1.42", "10.0.0.5"])).toBe(
+        "192.168.1.42, 10.0.0.5",
+      );
+    });
+
+    test("returns a single address unchanged", () => {
+      expect(normalizeHostIpAddresses(["10.0.0.5"])).toBe("10.0.0.5");
+    });
+
+    test("trims surrounding whitespace on each entry", () => {
+      expect(normalizeHostIpAddresses(["  10.0.0.5 ", "\t::1\n"])).toBe(
+        "10.0.0.5, ::1",
+      );
+    });
+
+    test("drops blank entries but keeps the rest", () => {
+      expect(normalizeHostIpAddresses(["10.0.0.5", "", "  ", "::1"])).toBe(
+        "10.0.0.5, ::1",
+      );
+    });
+
+    test("preserves source order", () => {
+      const ips: Array<string> = ["203.0.113.9", "10.0.0.5", "192.168.1.42"];
+      expect(normalizeHostIpAddresses(ips)).toBe(
+        "203.0.113.9, 10.0.0.5, 192.168.1.42",
+      );
+    });
+  });
+
+  describe("deduplication", () => {
+    test("removes exact duplicates", () => {
+      expect(
+        normalizeHostIpAddresses(["10.0.0.5", "10.0.0.5", "10.0.0.5"]),
+      ).toBe("10.0.0.5");
+    });
+
+    test("removes duplicates that differ only in IPv6 hex casing", () => {
+      /*
+       * Resource detectors disagree on IPv6 casing, so the same address can
+       * arrive twice in one batch in two different cases.
+       */
+      expect(normalizeHostIpAddresses(["FE80::1", "fe80::1"])).toBe("FE80::1");
+    });
+
+    test("removes duplicates that differ only in surrounding whitespace", () => {
+      expect(normalizeHostIpAddresses(["10.0.0.5", " 10.0.0.5  "])).toBe(
+        "10.0.0.5",
+      );
+    });
+
+    test("keeps the first-seen spelling of a duplicate", () => {
+      expect(normalizeHostIpAddresses(["fe80::AB", "FE80::ab"])).toBe(
+        "fe80::AB",
+      );
+    });
+
+    test("dedupes without disturbing the order of the survivors", () => {
+      expect(
+        normalizeHostIpAddresses(["a::1", "b::1", "A::1", "c::1", "B::1"]),
+      ).toBe("a::1, b::1, c::1");
+    });
+  });
+
+  describe("non-string entries", () => {
+    test("skips values that are not strings", () => {
+      const ips: Array<string> = [
+        "10.0.0.5",
+        // Defensive: the OTLP payload is untrusted JSON.
+        null as unknown as string,
+        undefined as unknown as string,
+        42 as unknown as string,
+        {} as unknown as string,
+        "::1",
+      ];
+      expect(normalizeHostIpAddresses(ips)).toBe("10.0.0.5, ::1");
+    });
+
+    test("returns null when every entry is a non-string", () => {
+      const ips: Array<string> = [
+        null as unknown as string,
+        7 as unknown as string,
+      ];
+      expect(normalizeHostIpAddresses(ips)).toBeNull();
+    });
+  });
+
+  describe("the issue #3006 payload", () => {
+    const addresses: Array<string> = issueReporterAddresses();
+
+    test("the fixture reproduces the reported shape", () => {
+      expect(addresses).toHaveLength(55);
+      expect(addresses.join(", ").length).toBeGreaterThan(1000);
+    });
+
+    test("is stored in full — every address survives", () => {
+      const result: string = normalizeHostIpAddresses(addresses) as string;
+      expect(result.split(", ")).toHaveLength(55);
+      for (const address of addresses) {
+        expect(result).toContain(address);
+      }
+    });
+
+    test("exceeds the old varchar(500) bound, which is why the column is now text", () => {
+      const result: string = normalizeHostIpAddresses(addresses) as string;
+      expect(result.length).toBeGreaterThan(500);
+    });
+  });
+
+  describe("count cap", () => {
+    function manyAddresses(count: number): Array<string> {
+      return Array.from({ length: count }, (_unused: unknown, i: number) => {
+        return `10.${Math.floor(i / 256)}.${i % 256}.1`;
+      });
+    }
+
+    test("keeps everything below the cap", () => {
+      const ips: Array<string> = manyAddresses(MAX_HOST_IP_ADDRESS_COUNT - 1);
+      const result: string = normalizeHostIpAddresses(ips) as string;
+      expect(result.split(", ")).toHaveLength(MAX_HOST_IP_ADDRESS_COUNT - 1);
+    });
+
+    test("keeps exactly the cap when handed exactly the cap", () => {
+      const ips: Array<string> = manyAddresses(MAX_HOST_IP_ADDRESS_COUNT);
+      const result: string = normalizeHostIpAddresses(ips) as string;
+      expect(result.split(", ")).toHaveLength(MAX_HOST_IP_ADDRESS_COUNT);
+    });
+
+    test("caps a pathological collector at the maximum count", () => {
+      const ips: Array<string> = manyAddresses(MAX_HOST_IP_ADDRESS_COUNT * 4);
+      const result: string = normalizeHostIpAddresses(ips) as string;
+      expect(result.split(", ")).toHaveLength(MAX_HOST_IP_ADDRESS_COUNT);
+    });
+
+    test("the addresses kept when capping are the first ones reported", () => {
+      const ips: Array<string> = manyAddresses(MAX_HOST_IP_ADDRESS_COUNT + 10);
+      const result: string = normalizeHostIpAddresses(ips) as string;
+      expect(result.startsWith(ips[0] as string)).toBe(true);
+      expect(result).not.toContain(ips[MAX_HOST_IP_ADDRESS_COUNT] as string);
+    });
+
+    test("duplicates do not consume cap slots", () => {
+      const ips: Array<string> = [
+        ...manyAddresses(10),
+        ...manyAddresses(10),
+        ...manyAddresses(10),
+      ];
+      const result: string = normalizeHostIpAddresses(ips) as string;
+      expect(result.split(", ")).toHaveLength(10);
+    });
+  });
+
+  describe("length cap", () => {
+    function longAddresses(count: number): Array<string> {
+      // 39 characters each — a fully expanded IPv6 address.
+      return Array.from({ length: count }, (_unused: unknown, i: number) => {
+        return `2001:0db8:0000:0000:0000:ff00:0042:${(0x1000 + i).toString(16)}`;
+      });
+    }
+
+    test("never exceeds the serialized length cap", () => {
+      const ips: Array<string> = longAddresses(MAX_HOST_IP_ADDRESS_COUNT);
+      const result: string = normalizeHostIpAddresses(ips) as string;
+      expect(result.length).toBeLessThanOrEqual(MAX_HOST_IP_ADDRESSES_LENGTH);
+    });
+
+    test("truncates whole addresses only — never a partial one", () => {
+      const ips: Array<string> = longAddresses(MAX_HOST_IP_ADDRESS_COUNT);
+      const result: string = normalizeHostIpAddresses(ips) as string;
+      for (const part of result.split(", ")) {
+        expect(ips).toContain(part);
+      }
+    });
+
+    test("a single address longer than the whole cap is dropped, not clipped", () => {
+      const huge: string = "a".repeat(MAX_HOST_IP_ADDRESSES_LENGTH + 1);
+      expect(normalizeHostIpAddresses([huge])).toBeNull();
+    });
+
+    test("a huge first entry does not suppress the entries after it being considered", () => {
+      /*
+       * The scan stops at the first entry that would overflow, so a huge
+       * leading entry costs the rest of the list. That is deliberate — but
+       * pin it so the behavior is a decision, not an accident.
+       */
+      const huge: string = "a".repeat(MAX_HOST_IP_ADDRESSES_LENGTH + 1);
+      expect(normalizeHostIpAddresses([huge, "10.0.0.5"])).toBeNull();
+      expect(normalizeHostIpAddresses(["10.0.0.5", huge])).toBe("10.0.0.5");
+    });
+
+    test("the separator counts toward the cap", () => {
+      // Two entries that only fit if the ", " between them is ignored.
+      const half: number = Math.floor(MAX_HOST_IP_ADDRESSES_LENGTH / 2);
+      const a: string = "a".repeat(half);
+      const b: string = "b".repeat(MAX_HOST_IP_ADDRESSES_LENGTH - half);
+      const result: string = normalizeHostIpAddresses([a, b]) as string;
+      expect(result).toBe(a);
+      expect(result.length).toBeLessThanOrEqual(MAX_HOST_IP_ADDRESSES_LENGTH);
+    });
+  });
+
+  describe("caps are sane", () => {
+    test("the length cap comfortably clears the reported 55-address payload", () => {
+      expect(MAX_HOST_IP_ADDRESSES_LENGTH).toBeGreaterThan(
+        issueReporterAddresses().join(", ").length * 2,
+      );
+    });
+
+    test("the count cap comfortably clears the reported 55-address payload", () => {
+      expect(MAX_HOST_IP_ADDRESS_COUNT).toBeGreaterThan(55 * 2);
+    });
+  });
+
+  describe("idempotence", () => {
+    test("re-normalizing an already-normalized list is a no-op", () => {
+      const once: string = normalizeHostIpAddresses(
+        issueReporterAddresses(),
+      ) as string;
+      const twice: string = normalizeHostIpAddresses(
+        once.split(", "),
+      ) as string;
+      expect(twice).toBe(once);
+    });
+  });
+});

package/Types/CustomField/CustomFieldDefinition.ts

@@ -0,0 +1,24 @@
+import CustomFieldType from "./CustomFieldType";
+
+/*
+ * One custom field, as the rest of the product needs to read it: the shape
+ * that comes back from a `*CustomField` definition table, narrowed to the four
+ * properties anything rendering or filtering by it actually uses.
+ *
+ * Lives in Types rather than beside the table columns that first needed it
+ * because the facet bar builds its chips from the same definitions, and that
+ * code is compiled by App's `tsc`, which has no React in it — importing the
+ * type from a .tsx would pull React into a program that cannot resolve it.
+ * `CustomFieldColumns` re-exports it, so existing imports keep working.
+ */
+export interface CustomFieldDefinition {
+  name: string;
+  description?: string | undefined;
+  customFieldType?: CustomFieldType | undefined;
+  /**
+   * Serialized options for a Dropdown / MultiSelectDropdown field. Parse with
+   * `parseCustomFieldDropdownOptions` — the value is either the legacy
+   * one-per-line format or a JSON array of `{ value, color }`.
+   */
+  dropdownOptions?: string | undefined;
+}

package/Types/Date.ts

@@ -9,6 +9,12 @@ import Zod, { ZodSchema } from "../Utils/Schema/Zod";
 
 export const Moment: typeof moment = moment;
 
+/*
+ * The units a calendar (rather than a fixed-length) interval can be measured in.
+ * See getStartOfCalendarUnit / addRemoveCalendarUnits below.
+ */
+export type CalendarUnit = "hour" | "day" | "week" | "month" | "year";
+
 export default class OneUptimeDate {
   // get date time from unix timestamp
 
@@ -363,6 +369,27 @@ export default class OneUptimeDate {
     ).trim();
   }
 
+  /*
+   * Format an instant with an explicit moment format string, resolved in an
+   * IANA timezone. The formatted-string helpers above each bake in a layout;
+   * this one is for callers that need a specific shape ("MMMM YYYY" for the
+   * month a status page report covers) and know exactly which zone it must be
+   * read in. Falls back to the viewer's / process's zone without one.
+   */
+  public static getDateAsCustomFormattedStringInTimezone(data: {
+    date: Date | string;
+    format: string;
+    timezone?: string | undefined;
+  }): string {
+    const date: Date = this.fromString(data.date);
+
+    if (!data.timezone) {
+      return this.inCurrentTimezone(date).format(data.format);
+    }
+
+    return moment(date).tz(data.timezone).format(data.format);
+  }
+
   /**
    * Reinterpret the wall-clock components of `date` — read in the CURRENT
    * timezone, i.e. the one the pickers render in — as the SAME wall-clock in
@@ -1213,6 +1240,91 @@ export default class OneUptimeDate {
     return moment(date).endOf("day").toDate();
   }
 
+  /*
+   * Calendar arithmetic - "the previous calendar month", "add 3 calendar
+   * months" - as opposed to the fixed-length arithmetic the rest of this class
+   * does. A calendar month is 28-31 days long and a calendar day is 23-25 hours
+   * long across a DST transition, so anything that has to line up with a wall
+   * clock (a status page report that must read "Jul 1 - Jul 31", a schedule that
+   * must keep firing at 09:00 local) cannot be expressed by adding milliseconds.
+   *
+   * Every helper below takes an optional IANA timezone. Without one the
+   * boundaries land in the process's local zone, which on a server is UTC.
+   */
+  private static toMomentCalendarUnit(
+    unit: CalendarUnit,
+    forStartOf: boolean,
+  ): moment.unitOfTime.StartOf & moment.unitOfTime.DurationConstructor {
+    /*
+     * moment's "week" starts on the locale's first day, which differs between
+     * environments and would make a weekly report cover Sun-Sat on one host and
+     * Mon-Sun on another. ISO weeks are always Monday-Sunday, so the boundary is
+     * the same everywhere. Durations have no such ambiguity - a week is 7 days -
+     * and moment has no "isoWeek" duration, so only startOf is remapped.
+     */
+    if (unit === "week" && forStartOf) {
+      return "isoWeek" as moment.unitOfTime.StartOf &
+        moment.unitOfTime.DurationConstructor;
+    }
+
+    return unit as moment.unitOfTime.StartOf &
+      moment.unitOfTime.DurationConstructor;
+  }
+
+  private static inTimezone(
+    date: Date,
+    timezone?: string | undefined,
+  ): moment.Moment {
+    return timezone ? moment.tz(date, timezone) : moment(date);
+  }
+
+  /*
+   * The instant the calendar unit containing `date` began - e.g. the first
+   * millisecond of that month, in `timezone`.
+   */
+  public static getStartOfCalendarUnit(
+    date: Date,
+    unit: CalendarUnit,
+    timezone?: string | undefined,
+  ): Date {
+    return this.inTimezone(this.fromString(date), timezone)
+      .startOf(this.toMomentCalendarUnit(unit, true))
+      .toDate();
+  }
+
+  /*
+   * Move `date` by whole calendar units, keeping the wall clock in `timezone`.
+   * Adding one month to Jan 31 lands on Feb 28/29 (moment clamps), and adding a
+   * day across a DST boundary still lands at the same local time.
+   */
+  public static addRemoveCalendarUnits(
+    date: Date,
+    unit: CalendarUnit,
+    count: number,
+    timezone?: string | undefined,
+  ): Date {
+    return this.inTimezone(this.fromString(date), timezone)
+      .add(count, this.toMomentCalendarUnit(unit, false))
+      .toDate();
+  }
+
+  /*
+   * How many whole calendar units fit between the two instants, measured in
+   * `timezone`. Used to jump a recurrence forward to "now" in one step instead
+   * of looping one interval at a time.
+   */
+  public static getCalendarUnitsBetween(
+    startDate: Date,
+    endDate: Date,
+    unit: CalendarUnit,
+    timezone?: string | undefined,
+  ): number {
+    return this.inTimezone(this.fromString(endDate), timezone).diff(
+      this.inTimezone(this.fromString(startDate), timezone),
+      this.toMomentCalendarUnit(unit, false),
+    );
+  }
+
   public static isBetween(date: Date, startDate: Date, endDate: Date): boolean {
     date = this.fromString(date);
     startDate = this.fromString(startDate);