@oneuptime/common 12.0.28 → 12.0.30

package/build/dist/Types/OnCallDutyPolicy/OnCallCalendarFeedUtil.js

@@ -0,0 +1,800 @@
+import moment from "moment-timezone";
+import User from "../../Models/DatabaseModels/User";
+import ICalendar, { ICalendarEventStatus, ICalendarTransparency, } from "../Calendar/ICalendar";
+import OneUptimeDate from "../Date";
+import ObjectID from "../ObjectID";
+import Timezone from "../Timezone";
+import CalendarFeedWindow, { MAX_EVENTS, MAX_GAP_EVENTS, } from "./CalendarFeedWindow";
+import LayerUtil from "./Layer";
+import MaterializedShiftUtil from "./MaterializedShift";
+import ScheduleShiftUtil from "./ScheduleShiftUtil";
+import ShiftSeamUtil from "./ShiftSeamUtil";
+/*
+ * Pure mapper from materialized on-call shifts to an iCalendar document.
+ *
+ * Everything here is deterministic on its inputs (no clock reads, no I/O), so
+ * the same shifts always serialize to the same bytes — the property the body
+ * cache and ETag depend on. The server-side renderer decides WHAT to feed in
+ * (which shifts, which window, which timezone) and this module decides how
+ * that looks in a calendar.
+ *
+ * Rules implemented (see the on-call calendar feeds design):
+ * - UID is (schedule, seam-normalised start), never the user, so an override
+ *   swap updates the event in place; policy variants add the policy id, gaps
+ *   have their own namespace.
+ * - DTSTAMP/LAST-MODIFIED are the schedule inputs' last-modified instant and
+ *   SEQUENCE is the schedule's shiftConfigVersion, so an unchanged schedule
+ *   renders byte-identically.
+ * - Every DTSTART/DTEND is UTC; the DESCRIPTION carries the schedule-zone,
+ *   UTC and viewer-zone wall clock.
+ * - TRANSP:TRANSPARENT, STATUS:CONFIRMED, CATEGORIES:On-Call; no CLASS.
+ */
+export var OnCallCalendarFeedKind;
+(function (OnCallCalendarFeedKind) {
+    OnCallCalendarFeedKind["Personal"] = "personal";
+    OnCallCalendarFeedKind["Schedule"] = "schedule";
+    OnCallCalendarFeedKind["Project"] = "project";
+})(OnCallCalendarFeedKind || (OnCallCalendarFeedKind = {}));
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+// Engine artefact tolerance when merging envelope segments (1 s seams).
+const ENVELOPE_MERGE_TOLERANCE_MILLISECONDS = 1000;
+/*
+ * ScheduleShiftUtil.getCoverageGaps ignores holes of five seconds or less
+ * (its contiguity tolerance for the engine's one-second seams). The trailing
+ * hole this file adds itself is held to the same threshold.
+ */
+const TRAILING_GAP_TOLERANCE_MILLISECONDS = 5 * 1000;
+const ENVELOPE_USER_ID = "00000000-0000-4000-8000-000000000000";
+const EMAIL_LIKE_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+class OnCallCalendarFeedUtil {
+    /*
+     * ---------------------------------------------------------------------
+     * Identity and links
+     * ---------------------------------------------------------------------
+     */
+    // oncall-<scheduleId>-<startEpochSeconds>@oneuptime (+ -<policyId> for variants).
+    static getShiftUid(shift) {
+        const base = `oncall-${shift.scheduleId}-${OnCallCalendarFeedUtil.epochSeconds(shift.start)}`;
+        const suffix = shift.policyVariantOf
+            ? `-${shift.policyVariantOf.policyId}`
+            : "";
+        return `${base}${suffix}@${OnCallCalendarFeedUtil.UID_DOMAIN}`;
+    }
+    static getGapUid(scheduleId, start) {
+        return `oncall-gap-${scheduleId}-${OnCallCalendarFeedUtil.epochSeconds(start)}@${OnCallCalendarFeedUtil.UID_DOMAIN}`;
+    }
+    static getScheduleUrl(dashboardUrl, projectId, scheduleId) {
+        return `${OnCallCalendarFeedUtil.trimTrailingSlash(dashboardUrl)}/${projectId}/on-call-duty/schedules/${scheduleId}`;
+    }
+    static getUserOverridesUrl(dashboardUrl, projectId) {
+        return `${OnCallCalendarFeedUtil.trimTrailingSlash(dashboardUrl)}/${projectId}/on-call-duty/user-overrides`;
+    }
+    static getTimeLogUrl(dashboardUrl, projectId) {
+        return `${OnCallCalendarFeedUtil.trimTrailingSlash(dashboardUrl)}/${projectId}/on-call-duty/user-time-logs`;
+    }
+    /*
+     * ---------------------------------------------------------------------
+     * Calendar header
+     * ---------------------------------------------------------------------
+     */
+    static buildCalendarName(options) {
+        const personal = OnCallCalendarFeedUtil.PERSONAL_CALENDAR_NAME;
+        if (options.kind === OnCallCalendarFeedKind.Schedule) {
+            const name = OnCallCalendarFeedUtil.cleanName(options.scheduleName) ||
+                "On-Call Schedule";
+            return {
+                name,
+                displayName: OnCallCalendarFeedUtil.truncateName(name, OnCallCalendarFeedUtil.MAX_SCHEDULE_CALENDAR_NAME_LENGTH),
+            };
+        }
+        if (options.kind === OnCallCalendarFeedKind.Project) {
+            const project = OnCallCalendarFeedUtil.cleanName(options.projectName) || "Project";
+            const name = `${personal} · ${project}`;
+            return { name, displayName: name };
+        }
+        const filter = OnCallCalendarFeedUtil.cleanName(options.filterScheduleName);
+        const name = filter ? `${personal} · ${filter}` : personal;
+        return { name, displayName: name };
+    }
+    static buildCalendarDescription(options) {
+        var _a;
+        let intro;
+        if (options.kind === OnCallCalendarFeedKind.Schedule) {
+            intro = `Everyone's on-call shifts on ${OnCallCalendarFeedUtil.cleanName(options.scheduleName) ||
+                "this schedule"} from OneUptime.`;
+        }
+        else if (options.kind === OnCallCalendarFeedKind.Project) {
+            intro = `Everyone's on-call shifts across ${OnCallCalendarFeedUtil.cleanName(options.projectName) || "this project"} from OneUptime.`;
+        }
+        else {
+            const filter = OnCallCalendarFeedUtil.cleanName(options.filterScheduleName);
+            intro = filter
+                ? `Your on-call shifts on ${filter} from OneUptime.`
+                : "Your on-call shifts from OneUptime.";
+        }
+        const notes = ((_a = options.notes) !== null && _a !== void 0 ? _a : [])
+            .map((note) => {
+            return note.trim();
+        })
+            .filter((note) => {
+            return note !== "";
+        });
+        return [intro, OnCallCalendarFeedUtil.REFRESH_CAVEAT, ...notes].join(" ");
+    }
+    static buildCalendarHeader(options) {
+        const names = OnCallCalendarFeedUtil.buildCalendarName(options);
+        const header = {
+            productId: OnCallCalendarFeedUtil.PRODUCT_ID,
+            name: names.name,
+            displayName: names.displayName,
+            description: OnCallCalendarFeedUtil.buildCalendarDescription(options),
+            timezone: OnCallCalendarFeedUtil.isValidTimezone(options.timezone)
+                ? options.timezone
+                : Timezone.UTC,
+            refreshInterval: OnCallCalendarFeedUtil.REFRESH_INTERVAL,
+        };
+        if (options.lastModifiedAt !== undefined) {
+            header.lastModified = options.lastModifiedAt;
+        }
+        return header;
+    }
+    /*
+     * ---------------------------------------------------------------------
+     * Shift -> VEVENT
+     * ---------------------------------------------------------------------
+     */
+    /*
+     * How a person is named in this feed. The personal feed shows whatever the
+     * materializer resolved (an email fallback is fine — it is the subscriber's
+     * own data); the shared schedule/project feeds never show an email.
+     */
+    static getDisplayName(name, kind) {
+        const trimmed = (name !== null && name !== void 0 ? name : "").trim();
+        if (trimmed === "") {
+            return OnCallCalendarFeedUtil.FALLBACK_USER_NAME;
+        }
+        if (kind !== OnCallCalendarFeedKind.Personal &&
+            EMAIL_LIKE_REGEX.test(trimmed)) {
+            return OnCallCalendarFeedUtil.FALLBACK_USER_NAME;
+        }
+        return trimmed;
+    }
+    static buildSummary(shift, kind) {
+        const scheduleName = OnCallCalendarFeedUtil.cleanName(shift.scheduleName) || "Schedule";
+        let summary = `On-call · ${scheduleName}`;
+        const distinctPolicies = OnCallCalendarFeedUtil.getDistinctPolicies(shift.policies);
+        if (shift.policyVariantOf) {
+            summary += ` · ${shift.policyVariantOf.policyName}`;
+        }
+        else if (kind === OnCallCalendarFeedKind.Personal &&
+            distinctPolicies.length === 1) {
+            summary += ` · ${distinctPolicies[0].policyName}`;
+        }
+        if (shift.override) {
+            summary += ` (covering for ${OnCallCalendarFeedUtil.getDisplayName(shift.override.originalUserName, kind)})`;
+        }
+        if (kind === OnCallCalendarFeedKind.Personal) {
+            return summary;
+        }
+        return `${OnCallCalendarFeedUtil.getDisplayName(shift.userName, kind)} · ${summary}`;
+    }
+    static buildDescription(shift, context, allShifts) {
+        const kind = context.kind;
+        const lines = [];
+        const userName = OnCallCalendarFeedUtil.getDisplayName(shift.userName, kind);
+        const originalUserName = shift.override
+            ? OnCallCalendarFeedUtil.getDisplayName(shift.override.originalUserName, kind)
+            : null;
+        lines.push(`Who: ${userName}${originalUserName ? `, covering for ${originalUserName}` : ""}`);
+        const scheduleZone = OnCallCalendarFeedUtil.getScheduleZone(shift);
+        const isLegacyZone = !OnCallCalendarFeedUtil.isValidTimezone(shift.scheduleTimezone);
+        lines.push(`Schedule: ${OnCallCalendarFeedUtil.cleanName(shift.scheduleName) || "Schedule"} (${isLegacyZone
+            ? OnCallCalendarFeedUtil.LEGACY_TIMEZONE_NOTE
+            : scheduleZone})`);
+        if (shift.layerName) {
+            lines.push(`Layer: ${shift.layerName}`);
+        }
+        lines.push(...OnCallCalendarFeedUtil.buildShiftTimeLines(shift, scheduleZone, isLegacyZone, context.viewerTimezone));
+        const distinctPolicies = OnCallCalendarFeedUtil.getDistinctPolicies(shift.policies);
+        // A variant pages through ONE policy, not the schedule's whole attachment set.
+        const pagingPolicies = OnCallCalendarFeedUtil.getPagingPolicies(shift);
+        if (pagingPolicies.length === 0) {
+            lines.push(OnCallCalendarFeedUtil.NO_POLICY_LINE);
+        }
+        else {
+            const label = kind === OnCallCalendarFeedKind.Personal
+                ? "Pages you via"
+                : "Pages via";
+            lines.push(`${label}: ${OnCallCalendarFeedUtil.describePolicies(pagingPolicies)}`);
+        }
+        if (shift.override) {
+            const scope = shift.override.onCallDutyPolicyId
+                ? `scoped to ${OnCallCalendarFeedUtil.findPolicyName(distinctPolicies, shift.override.onCallDutyPolicyId)}`
+                : "global override";
+            lines.push(`Override: ${originalUserName} → ${userName} from ${OnCallCalendarFeedUtil.formatInZone(shift.override.overrideStartsAt, scheduleZone)} to ${OnCallCalendarFeedUtil.formatInZone(shift.override.overrideEndsAt, scheduleZone)} (${scope})`);
+        }
+        if (shift.policyVariantOf) {
+            const insteadOf = originalUserName !== null && originalUserName !== void 0 ? originalUserName : "the rostered user";
+            lines.push(kind === OnCallCalendarFeedKind.Personal
+                ? `For ${shift.policyVariantOf.policyName} you are paged instead of ${insteadOf} because of a policy-specific override.`
+                : `For ${shift.policyVariantOf.policyName}, ${userName} is paged instead of ${insteadOf} because of a policy-specific override.`);
+        }
+        else {
+            /*
+             * A pre-built index (every render builds one) beats re-scanning the
+             * whole shift array for every shift, which is quadratic at feed sizes
+             * near MAX_EVENTS.
+             */
+            const variantIndex = context.variantIndex !== undefined
+                ? context.variantIndex
+                : allShifts
+                    ? OnCallCalendarFeedUtil.buildVariantIndex(allShifts)
+                    : null;
+            if (variantIndex) {
+                lines.push(...OnCallCalendarFeedUtil.buildVariantMirrorLines(shift, variantIndex, kind, scheduleZone));
+            }
+        }
+        if (shift.isPast) {
+            lines.push(`${OnCallCalendarFeedUtil.PAST_SHIFT_LINE} ${OnCallCalendarFeedUtil.getTimeLogUrl(context.dashboardUrl, shift.projectId)}`);
+        }
+        lines.push(`Need cover? ${OnCallCalendarFeedUtil.getUserOverridesUrl(context.dashboardUrl, shift.projectId)}`);
+        lines.push(OnCallCalendarFeedUtil.REFRESH_LINE);
+        return lines.join("\n");
+    }
+    static shiftToEvent(shift, context, allShifts) {
+        return {
+            uid: OnCallCalendarFeedUtil.getShiftUid(shift),
+            dtStamp: shift.lastModifiedAt,
+            lastModified: shift.lastModifiedAt,
+            sequence: OnCallCalendarFeedUtil.toSequence(shift.shiftConfigVersion),
+            start: shift.start,
+            end: shift.end,
+            summary: OnCallCalendarFeedUtil.buildSummary(shift, context.kind),
+            description: OnCallCalendarFeedUtil.buildDescription(shift, context, allShifts),
+            url: OnCallCalendarFeedUtil.getScheduleUrl(context.dashboardUrl, shift.projectId, shift.scheduleId),
+            status: ICalendarEventStatus.Confirmed,
+            transparency: ICalendarTransparency.Transparent,
+            categories: [OnCallCalendarFeedUtil.CATEGORY],
+        };
+    }
+    /*
+     * One VEVENT per shift, in deterministic (start, schedule, key) order.
+     *
+     * `contextShifts` are shifts that do NOT become events but may explain the
+     * ones that do (the personal feed's pre-filter list); it defaults to the
+     * rendered shifts.
+     */
+    static shiftsToEvents(shifts, context, contextShifts) {
+        const sorted = MaterializedShiftUtil.sortByStart(shifts);
+        const eventContext = Object.assign(Object.assign({}, context), { variantIndex: OnCallCalendarFeedUtil.buildVariantIndex(contextShifts !== null && contextShifts !== void 0 ? contextShifts : sorted) });
+        return sorted.map((shift) => {
+            return OnCallCalendarFeedUtil.shiftToEvent(shift, eventContext);
+        });
+    }
+    /*
+     * ---------------------------------------------------------------------
+     * Window
+     * ---------------------------------------------------------------------
+     */
+    // Shifts that overlap [feedStart, feedEnd), unclipped, sorted.
+    static filterShiftsToWindow(shifts, feedStart, feedEnd) {
+        return MaterializedShiftUtil.sortByStart(shifts).filter((shift) => {
+            return (shift.start.getTime() < feedEnd.getTime() &&
+                shift.end.getTime() > feedStart.getTime());
+        });
+    }
+    /*
+     * Keep the feed under maxEvents by cutting whole UTC days off the END of
+     * the window (the nearest future matters most). When even the first day
+     * holds more than maxEvents shifts, the cut lands on the first excluded
+     * shift's start instead.
+     */
+    static shrinkWindowToFit(input) {
+        const maxEvents = input.maxEvents !== undefined && input.maxEvents > 0
+            ? Math.floor(input.maxEvents)
+            : MAX_EVENTS;
+        const inWindow = OnCallCalendarFeedUtil.filterShiftsToWindow(input.shifts, input.feedStart, input.feedEnd);
+        if (inWindow.length <= maxEvents) {
+            return {
+                shifts: inWindow,
+                feedEnd: input.feedEnd,
+                truncated: false,
+                daysDropped: 0,
+            };
+        }
+        const firstExcluded = inWindow[maxEvents];
+        let newFeedEnd = new Date(CalendarFeedWindow.startOfUtcDay(firstExcluded.start));
+        if (newFeedEnd.getTime() <= input.feedStart.getTime()) {
+            newFeedEnd = new Date(firstExcluded.start.getTime());
+        }
+        let kept = inWindow.filter((shift) => {
+            return shift.start.getTime() < newFeedEnd.getTime();
+        });
+        /*
+         * Shifts that started before the window (in progress at feedStart) all
+         * share "start < newFeedEnd"; if there are more than maxEvents of those
+         * no cut point exists and a hard slice is the only option left.
+         */
+        if (kept.length > maxEvents) {
+            kept = kept.slice(0, maxEvents);
+        }
+        const daysDropped = Math.max(0, Math.ceil((input.feedEnd.getTime() - newFeedEnd.getTime()) / MILLISECONDS_PER_DAY));
+        return { shifts: kept, feedEnd: newFeedEnd, truncated: true, daysDropped };
+    }
+    /*
+     * ---------------------------------------------------------------------
+     * Coverage gaps
+     * ---------------------------------------------------------------------
+     */
+    /*
+     * Where the schedule's layers INTEND to cover, regardless of who (or
+     * whether anyone) is assigned and of when the layer starts: each layer is
+     * expanded with one synthetic user from the window start, so the result is
+     * exactly its restriction windows — the whole window for an unrestricted
+     * layer, Mon-Fri 09:00-17:00 for a business-hours layer. A coverage hole
+     * is only worth an event when it falls inside this envelope.
+     */
+    static computeCoverageEnvelope(input) {
+        const layerUtil = new LayerUtil();
+        const segments = [];
+        let truncated = false;
+        const syntheticUser = new User();
+        syntheticUser.id = new ObjectID(ENVELOPE_USER_ID);
+        for (const layer of input.layers) {
+            const result = layerUtil.getEventsWithMeta({
+                users: [syntheticUser],
+                startDateTimeOfLayer: input.windowStart,
+                restrictionTimes: layer.restrictionTimes,
+                handOffTime: layer.handOffTime,
+                rotation: layer.rotation,
+                timezone: layer.timezone,
+                calendarStartDate: input.windowStart,
+                calendarEndDate: input.windowEnd,
+            }, input.maxSimulationIterations !== undefined
+                ? { maxSimulationIterations: input.maxSimulationIterations }
+                : undefined);
+            truncated = truncated || result.truncated;
+            for (const event of result.events) {
+                segments.push({ start: event.start, end: event.end });
+            }
+        }
+        /*
+         * The engine's 1-second seams (09:00:01 starts) would otherwise leak into
+         * gap events; normalise them exactly as the shifts themselves are.
+         */
+        return {
+            segments: OnCallCalendarFeedUtil.mergeSegments(ShiftSeamUtil.normalizeSeams(segments), ENVELOPE_MERGE_TOLERANCE_MILLISECONDS),
+            truncated,
+        };
+    }
+    /*
+     * "No coverage" events: every hole before, between and after the shifts
+     * inside [feedStart, feedEnd) that intersects the envelope, clipped to the
+     * envelope, merged, at least minimumGapSeconds long, oldest first, capped at
+     * maxGapEvents. Off-hours of a business-hours schedule are outside the
+     * envelope and are therefore never emitted.
+     */
+    static buildCoverageGapEvents(input) {
+        var _a;
+        const maxGapEvents = input.maxGapEvents !== undefined && input.maxGapEvents >= 0
+            ? Math.floor(input.maxGapEvents)
+            : MAX_GAP_EVENTS;
+        const minimumGapMilliseconds = Math.max(0, (_a = input.minimumGapSeconds) !== null && _a !== void 0 ? _a : 0) * 1000;
+        const shifts = [...input.shifts]
+            .sort((a, b) => {
+            return a.start.getTime() - b.start.getTime();
+        })
+            .map((segment) => {
+            return {
+                userId: "",
+                start: segment.start,
+                end: segment.end,
+                coverageSeconds: OneUptimeDate.getDifferenceInSeconds(segment.end, segment.start),
+            };
+        });
+        const rawGaps = ScheduleShiftUtil.getCoverageGaps(shifts, input.feedStart, input.feedEnd);
+        /*
+         * getCoverageGaps (shared with the dashboard's coverage view) treats the
+         * window end as an arbitrary cut and never reports the stretch after the
+         * last shift. For a feed the window end IS the horizon the envelope was
+         * computed for, so a rotation that stops mid-window (every user removed
+         * after a date, a layer whose users run out) must show its tail as "No
+         * coverage" too. The envelope intersection below still clips it to the
+         * hours a layer intended to cover, so a business-hours schedule whose last
+         * shift ends on Friday still emits nothing for the weekend.
+         */
+        if (shifts.length > 0) {
+            const coveredUntil = shifts.reduce((max, shift) => {
+                return Math.max(max, shift.end.getTime());
+            }, shifts[0].end.getTime());
+            if (input.feedEnd.getTime() - coveredUntil >
+                TRAILING_GAP_TOLERANCE_MILLISECONDS) {
+                rawGaps.push({ start: new Date(coveredUntil), end: input.feedEnd });
+            }
+        }
+        const envelope = OnCallCalendarFeedUtil.mergeSegments(input.envelope
+            .map((segment) => {
+            return {
+                start: new Date(Math.max(segment.start.getTime(), input.feedStart.getTime())),
+                end: new Date(Math.min(segment.end.getTime(), input.feedEnd.getTime())),
+            };
+        })
+            .filter((segment) => {
+            return segment.end.getTime() > segment.start.getTime();
+        }), ENVELOPE_MERGE_TOLERANCE_MILLISECONDS);
+        const pieces = [];
+        for (const gap of rawGaps) {
+            for (const intended of envelope) {
+                const start = Math.max(gap.start.getTime(), intended.start.getTime());
+                const end = Math.min(gap.end.getTime(), intended.end.getTime());
+                if (end > start) {
+                    pieces.push({ start: new Date(start), end: new Date(end) });
+                }
+            }
+        }
+        const gaps = OnCallCalendarFeedUtil.mergeSegments(pieces, 0).filter((gap) => {
+            return gap.end.getTime() - gap.start.getTime() >= minimumGapMilliseconds;
+        });
+        const truncated = gaps.length > maxGapEvents;
+        const kept = gaps.slice(0, maxGapEvents);
+        return {
+            events: kept.map((gap) => {
+                return OnCallCalendarFeedUtil.gapToEvent(gap, input);
+            }),
+            gaps: kept,
+            truncated,
+        };
+    }
+    static gapToEvent(gap, input) {
+        const scheduleName = OnCallCalendarFeedUtil.cleanName(input.scheduleName) || "Schedule";
+        const url = OnCallCalendarFeedUtil.getScheduleUrl(input.dashboardUrl, input.projectId, input.scheduleId);
+        return {
+            uid: OnCallCalendarFeedUtil.getGapUid(input.scheduleId, gap.start),
+            dtStamp: input.lastModifiedAt,
+            lastModified: input.lastModifiedAt,
+            sequence: OnCallCalendarFeedUtil.toSequence(input.shiftConfigVersion),
+            start: gap.start,
+            end: gap.end,
+            summary: `No coverage · ${scheduleName}`,
+            description: [
+                `Nobody is on call for ${scheduleName} during this time, although a layer is meant to cover it.`,
+                `Fix the rotation: ${url}`,
+                OnCallCalendarFeedUtil.REFRESH_LINE,
+            ].join("\n"),
+            url,
+            status: ICalendarEventStatus.Confirmed,
+            transparency: ICalendarTransparency.Transparent,
+            categories: [OnCallCalendarFeedUtil.CATEGORY],
+        };
+    }
+    /*
+     * ---------------------------------------------------------------------
+     * Whole documents
+     * ---------------------------------------------------------------------
+     */
+    static buildDocument(input) {
+        var _a, _b, _c;
+        const context = {
+            kind: input.kind,
+            dashboardUrl: input.dashboardUrl,
+            viewerTimezone: input.viewerTimezone,
+        };
+        const events = [
+            ...OnCallCalendarFeedUtil.shiftsToEvents(input.shifts, context, input.contextShifts),
+            ...((_a = input.gapEvents) !== null && _a !== void 0 ? _a : []),
+        ].sort((a, b) => {
+            const byStart = a.start.getTime() - b.start.getTime();
+            if (byStart !== 0) {
+                return byStart;
+            }
+            if (a.uid === b.uid) {
+                return 0;
+            }
+            return a.uid < b.uid ? -1 : 1;
+        });
+        const lastModifiedAt = (_b = input.lastModifiedAt) !== null && _b !== void 0 ? _b : OnCallCalendarFeedUtil.getLatestModification(input.shifts, input.gapEvents);
+        const calendar = OnCallCalendarFeedUtil.buildCalendarHeader({
+            kind: input.kind,
+            scheduleName: input.scheduleName,
+            projectName: input.projectName,
+            filterScheduleName: input.filterScheduleName,
+            timezone: (_c = input.calendarTimezone) !== null && _c !== void 0 ? _c : input.viewerTimezone,
+            lastModifiedAt: lastModifiedAt !== null && lastModifiedAt !== void 0 ? lastModifiedAt : undefined,
+            notes: input.notes,
+        });
+        return { calendar, events };
+    }
+    static render(input) {
+        var _a;
+        const document = OnCallCalendarFeedUtil.buildDocument(input);
+        return {
+            body: ICalendar.serialize(document),
+            eventCount: document.events.length,
+            lastModifiedAt: (_a = document.calendar.lastModified) !== null && _a !== void 0 ? _a : null,
+        };
+    }
+    /*
+     * The empty VCALENDAR every "200 but nothing to show" case serves (feed
+     * disabled, rotated token inside its grace, project below plan, no eligible
+     * schedule). X-WR-CALDESC carries the reason so a subscriber who looks can
+     * tell why their calendar went blank.
+     */
+    static renderEmpty(input) {
+        const calendar = OnCallCalendarFeedUtil.buildCalendarHeader({
+            kind: input.kind,
+            scheduleName: input.scheduleName,
+            projectName: input.projectName,
+            filterScheduleName: input.filterScheduleName,
+            timezone: input.timezone,
+            notes: [input.reason],
+        });
+        return ICalendar.serialize({ calendar, events: [] });
+    }
+    /*
+     * ---------------------------------------------------------------------
+     * Helpers
+     * ---------------------------------------------------------------------
+     */
+    static isValidTimezone(timezone) {
+        return (typeof timezone === "string" &&
+            timezone.trim() !== "" &&
+            moment.tz.zone(timezone) !== null);
+    }
+    // The zone a shift's wall clock is rendered in; legacy schedules use UTC.
+    static getScheduleZone(shift) {
+        return OnCallCalendarFeedUtil.isValidTimezone(shift.scheduleTimezone)
+            ? shift.scheduleTimezone
+            : Timezone.UTC;
+    }
+    static truncateName(name, maxLength) {
+        const characters = Array.from(name);
+        if (characters.length <= maxLength) {
+            return name;
+        }
+        return `${characters
+            .slice(0, Math.max(0, maxLength - 1))
+            .join("")
+            .trimEnd()}…`;
+    }
+    // Sort by start and merge segments that overlap or sit within `toleranceMs`.
+    static mergeSegments(segments, toleranceMilliseconds) {
+        const sorted = segments
+            .filter((segment) => {
+            return segment.end.getTime() > segment.start.getTime();
+        })
+            .map((segment) => {
+            return {
+                start: new Date(segment.start.getTime()),
+                end: new Date(segment.end.getTime()),
+            };
+        })
+            .sort((a, b) => {
+            return a.start.getTime() - b.start.getTime();
+        });
+        const merged = [];
+        for (const segment of sorted) {
+            const last = merged[merged.length - 1];
+            if (last &&
+                segment.start.getTime() <= last.end.getTime() + toleranceMilliseconds) {
+                if (segment.end.getTime() > last.end.getTime()) {
+                    last.end = segment.end;
+                }
+                continue;
+            }
+            merged.push(segment);
+        }
+        return merged;
+    }
+    static getDistinctPolicies(policies) {
+        const seen = new Set();
+        const distinct = [];
+        for (const policy of policies) {
+            if (seen.has(policy.policyId)) {
+                continue;
+            }
+            seen.add(policy.policyId);
+            distinct.push(policy);
+        }
+        return distinct.sort((a, b) => {
+            return OnCallCalendarFeedUtil.compareStrings(a.policyName, b.policyName);
+        });
+    }
+    // "Payments › Primary (step 1); Billing › Backup (step 2)"
+    static describePolicies(policies) {
+        return [...policies]
+            .sort((a, b) => {
+            return (OnCallCalendarFeedUtil.compareStrings(a.policyName, b.policyName) ||
+                a.ruleOrder - b.ruleOrder ||
+                OnCallCalendarFeedUtil.compareStrings(a.ruleName, b.ruleName));
+        })
+            .map((policy) => {
+            return `${policy.policyName} › ${policy.ruleName} (step ${policy.ruleOrder})`;
+        })
+            .join("; ");
+    }
+    static buildShiftTimeLines(shift, scheduleZone, isLegacyZone, viewerTimezone) {
+        const zones = [scheduleZone];
+        if (scheduleZone !== Timezone.UTC) {
+            zones.push(Timezone.UTC);
+        }
+        if (OnCallCalendarFeedUtil.isValidTimezone(viewerTimezone) &&
+            !zones.includes(viewerTimezone)) {
+            zones.push(viewerTimezone);
+        }
+        const starts = OnCallCalendarFeedUtil.formatInZones(shift.start, zones);
+        const ends = OnCallCalendarFeedUtil.formatInZones(shift.end, zones);
+        const lines = [];
+        for (let i = 0; i < zones.length; i++) {
+            const zone = zones[i];
+            const range = `${starts[i]} → ${ends[i]}`;
+            if (i === 0) {
+                lines.push(`Shift: ${range} (${isLegacyZone
+                    ? `UTC — ${OnCallCalendarFeedUtil.LEGACY_TIMEZONE_NOTE}`
+                    : `${zone} — schedule zone`})`);
+                continue;
+            }
+            const label = zone === Timezone.UTC && zone !== viewerTimezone
+                ? "UTC"
+                : `${zone} (your zone)`;
+            lines.push(`Shift in ${label}: ${range}`);
+        }
+        return lines;
+    }
+    /*
+     * Mirror lines on a base shift for every policy variant that takes part of
+     * it over.
+     *
+     * Matching is (same schedule) + (time overlap) + (different person). The
+     * variant's own `policyVariantOf.globalUserId` is deliberately NOT required
+     * to equal this shift's user: the materializer records only the FIRST
+     * overlapping base user, so a variant spanning a handover would otherwise
+     * inform the first person and leave the second — whose shift the variant
+     * also takes over — reading "Pages you via <policy>" for a window in which
+     * somebody else is paged for it.
+     *
+     * The quoted window is clipped to the overlap so the sentence names exactly
+     * the part of THIS shift that is taken over.
+     */
+    static buildVariantMirrorLines(shift, variantIndex, kind, scheduleZone) {
+        const candidates = variantIndex.get(shift.scheduleId);
+        if (!candidates || candidates.length === 0) {
+            return [];
+        }
+        const lines = [];
+        for (const other of candidates) {
+            if (!other.policyVariantOf || other.userId === shift.userId) {
+                continue;
+            }
+            const overlapStart = Math.max(other.start.getTime(), shift.start.getTime());
+            const overlapEnd = Math.min(other.end.getTime(), shift.end.getTime());
+            if (overlapStart >= overlapEnd) {
+                continue;
+            }
+            lines.push(`For ${other.policyVariantOf.policyName}, ${OnCallCalendarFeedUtil.getDisplayName(other.userName, kind)} is paged instead from ${OnCallCalendarFeedUtil.formatInZone(new Date(overlapStart), scheduleZone)} to ${OnCallCalendarFeedUtil.formatInZone(new Date(overlapEnd), scheduleZone)}.`);
+        }
+        return lines;
+    }
+    /*
+     * Bucket the policy-variant shifts of a feed by schedule id, sorted inside
+     * each bucket so the DESCRIPTION lines are deterministic (the body cache and
+     * the ETag depend on it). Returns null when there is not a single variant —
+     * the overwhelmingly common case — so the mirror-line pass is skipped
+     * outright instead of scanning every shift for every shift.
+     */
+    static buildVariantIndex(shifts) {
+        let index = null;
+        for (const shift of shifts) {
+            if (!shift.policyVariantOf) {
+                continue;
+            }
+            if (!index) {
+                index = new Map();
+            }
+            const bucket = index.get(shift.scheduleId);
+            if (bucket) {
+                bucket.push(shift);
+            }
+            else {
+                index.set(shift.scheduleId, [shift]);
+            }
+        }
+        if (!index) {
+            return null;
+        }
+        for (const bucket of index.values()) {
+            bucket.sort((a, b) => {
+                return (a.start.getTime() - b.start.getTime() ||
+                    a.end.getTime() - b.end.getTime() ||
+                    OnCallCalendarFeedUtil.compareStrings(a.policyVariantOf.policyId, b.policyVariantOf.policyId) ||
+                    OnCallCalendarFeedUtil.compareStrings(a.userId, b.userId));
+            });
+        }
+        return index;
+    }
+    /*
+     * The policies this shift actually pages through. A policy-variant shift
+     * exists for exactly one policy — the schedule's other policies still page
+     * the rostered user — but the materializer stamps every shift of a schedule
+     * with its full attachment set, so listing them all on a variant would
+     * contradict the sentence directly below it. Falls back to the full list if
+     * the variant's policy is somehow not among them, so a shift never claims to
+     * page nobody.
+     */
+    static getPagingPolicies(shift) {
+        if (!shift.policyVariantOf) {
+            return shift.policies;
+        }
+        const variantPolicyId = shift.policyVariantOf.policyId;
+        const scoped = shift.policies.filter((policy) => {
+            return policy.policyId === variantPolicyId;
+        });
+        return scoped.length > 0 ? scoped : shift.policies;
+    }
+    static formatInZones(date, zones) {
+        return OneUptimeDate.getDateAsFormattedStringInMultipleTimezones({
+            date,
+            timezones: zones,
+            use12HourFormat: false,
+        }).split("\n");
+    }
+    // Same formatter as the shift lines, so every date in a DESCRIPTION matches.
+    static formatInZone(date, zone) {
+        var _a;
+        return (_a = OnCallCalendarFeedUtil.formatInZones(date, [zone])[0]) !== null && _a !== void 0 ? _a : "";
+    }
+    static findPolicyName(policies, policyId) {
+        const match = policies.find((policy) => {
+            return policy.policyId === policyId;
+        });
+        return match ? match.policyName : "an escalation policy";
+    }
+    static getLatestModification(shifts, gapEvents) {
+        let latest = null;
+        for (const shift of shifts) {
+            const time = shift.lastModifiedAt.getTime();
+            if (latest === null || time > latest) {
+                latest = time;
+            }
+        }
+        for (const event of gapEvents !== null && gapEvents !== void 0 ? gapEvents : []) {
+            const time = event.dtStamp.getTime();
+            if (latest === null || time > latest) {
+                latest = time;
+            }
+        }
+        return latest === null ? null : new Date(latest);
+    }
+    static toSequence(version) {
+        return Number.isFinite(version) ? Math.max(0, Math.floor(version)) : 0;
+    }
+    static epochSeconds(date) {
+        return Math.floor(date.getTime() / 1000);
+    }
+    static cleanName(name) {
+        return (name !== null && name !== void 0 ? name : "").replace(/\s+/g, " ").trim();
+    }
+    static trimTrailingSlash(url) {
+        return url.replace(/\/+$/, "");
+    }
+    static compareStrings(a, b) {
+        if (a === b) {
+            return 0;
+        }
+        return a < b ? -1 : 1;
+    }
+}
+OnCallCalendarFeedUtil.PRODUCT_ID = "-//OneUptime//On-Call Calendar Feed//EN";
+OnCallCalendarFeedUtil.REFRESH_INTERVAL = "PT1H";
+OnCallCalendarFeedUtil.UID_DOMAIN = "oneuptime";
+OnCallCalendarFeedUtil.CATEGORY = "On-Call";
+OnCallCalendarFeedUtil.PERSONAL_CALENDAR_NAME = "OneUptime On-Call";
+// Confluence Team Calendars rejects longer calendar names.
+OnCallCalendarFeedUtil.MAX_SCHEDULE_CALENDAR_NAME_LENGTH = 28;
+OnCallCalendarFeedUtil.FALLBACK_USER_NAME = "Unnamed user";
+OnCallCalendarFeedUtil.REFRESH_CAVEAT = "Calendar apps refresh subscribed feeds on their own schedule (Google Calendar every 12-24 h, Outlook on the web about every 3 h, Apple Calendar per its fetch setting), so recent changes can lag.";
+OnCallCalendarFeedUtil.REFRESH_LINE = "Changes appear after your calendar app next refreshes (Google Calendar: up to 24 h).";
+OnCallCalendarFeedUtil.PAST_SHIFT_LINE = "Past shifts reflect the current rotation, not who was actually paged — see the On-Call Time Log report.";
+OnCallCalendarFeedUtil.NO_POLICY_LINE = "Not attached to any escalation policy, so it will not page anyone.";
+OnCallCalendarFeedUtil.LEGACY_TIMEZONE_NOTE = "schedule has no timezone set (expanded in the server's zone, as paging does)";
+export default OnCallCalendarFeedUtil;
+//# sourceMappingURL=OnCallCalendarFeedUtil.js.map