@openinc/parse-server-opendash 4.1.8 → 4.2.0

package/dist/features/openservice/serviceSchedules/calendarSync/functions/planToEvent.js

@@ -0,0 +1,145 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planToEvent = planToEvent;
+const dayjs_1 = __importDefault(require("dayjs"));
+const outlookRecurrence_js_1 = require("./outlookRecurrence.js");
+/**
+ * A maintenance plan as a calendar event.
+ *
+ * Returns `undefined` for a plan that has no date to put in a calendar — a
+ * manual, sensor- or meter-driven plan has no due date until something happens,
+ * and inventing one would show maintenance that nobody scheduled.
+ */
+function planToEvent(plan) {
+    const start = cadenceStart(plan.cadence);
+    if (!start)
+        return undefined;
+    const timed = timeOfDay(plan, start);
+    const event = {
+        subject: eventSubject(plan),
+        body: { contentType: "Text", content: stepsAsText(plan.steps) },
+        start: graphStart(start, timed),
+        end: graphEnd(start, timed),
+        isAllDay: timed ? undefined : true,
+        isReminderOn: false,
+    };
+    const reminder = reminderMinutes(plan.notifications);
+    if (reminder !== undefined) {
+        event.isReminderOn = true;
+        event.reminderMinutesBeforeStart = reminder;
+    }
+    const recurrence = (0, outlookRecurrence_js_1.cadenceToRecurrence)(plan.cadence, start);
+    if (recurrence)
+        event.recurrence = recurrence;
+    return event;
+}
+/**
+ * The instant the series starts.
+ *
+ * Only an RRULE cadence has one. `until` is not consulted here: it bounds the
+ * series (the recurrence range does that), it does not start it.
+ */
+function cadenceStart(cadence) {
+    if (cadence?.kind !== "rrule" || !cadence.dtstart)
+        return undefined;
+    const start = new Date(cadence.dtstart);
+    return Number.isNaN(start.getTime()) ? undefined : start;
+}
+/**
+ * The time of day the event should keep, as `{hour, minute}` — or `undefined`
+ * for an all-day event.
+ *
+ * Two sources, in this order:
+ *
+ * 1. the plan's own `dtstart`, if it names a time (not UTC midnight) — the plan
+ *    is the leading side for anything the plan can express;
+ * 2. otherwise the time the **event** has in Outlook, so a user who dragged a
+ *    maintenance appointment to 9:00 keeps it. A plan whose due date shifts
+ *    then moves the appointment to the new *day* at the same time — which is
+ *    where v1 went wrong: it kept the whole original start and quietly ignored
+ *    the new date.
+ */
+function timeOfDay(plan, start) {
+    if (start.getUTCHours() !== 0 || start.getUTCMinutes() !== 0) {
+        return { hour: start.getUTCHours(), minute: start.getUTCMinutes() };
+    }
+    const snapshot = plan.snapshot;
+    if (!snapshot || snapshot.isAllDay || !snapshot.start?.dateTime) {
+        return undefined;
+    }
+    const previous = new Date(snapshot.start.dateTime.endsWith("Z")
+        ? snapshot.start.dateTime
+        : `${snapshot.start.dateTime.slice(0, 23)}Z`);
+    if (Number.isNaN(previous.getTime()))
+        return undefined;
+    if (previous.getUTCHours() === 0 && previous.getUTCMinutes() === 0) {
+        return undefined;
+    }
+    return { hour: previous.getUTCHours(), minute: previous.getUTCMinutes() };
+}
+function graphStart(start, timed) {
+    if (!timed) {
+        return { dateTime: dateOnly(start), timeZone: "UTC" };
+    }
+    return { dateTime: atTime(start, timed), timeZone: "UTC" };
+}
+function graphEnd(start, timed) {
+    if (!timed) {
+        // An all-day event ends on the following day — Graph's half-open interval.
+        return {
+            dateTime: dateOnly((0, dayjs_1.default)(start).add(1, "day").toDate()),
+            timeZone: "UTC",
+        };
+    }
+    const end = (0, dayjs_1.default)(atTime(start, timed)).add(1, "hour");
+    return { dateTime: end.format("YYYY-MM-DDTHH:mm:ss"), timeZone: "UTC" };
+}
+function dateOnly(date) {
+    return date.toISOString().slice(0, 10);
+}
+function atTime(date, timed) {
+    return `${dateOnly(date)}T${pad(timed.hour)}:${pad(timed.minute)}:00`;
+}
+function pad(value) {
+    return String(value).padStart(2, "0");
+}
+/**
+ * `"Flex 1" - Ölwechsel` — the convention the inbound direction reads back
+ * ([`parseSubject`](./eventToPlan.ts)), so a plan created here and edited in
+ * Outlook keeps its machine.
+ */
+function eventSubject(plan) {
+    const title = plan.title?.trim() || "Wartung";
+    return plan.equipmentName ? `"${plan.equipmentName}" - ${title}` : title;
+}
+/**
+ * The checklist as the event's note.
+ *
+ * The point of the appointment is that someone reads it in Outlook and knows
+ * what to bring — a title alone rarely says that.
+ */
+function stepsAsText(steps) {
+    const lines = [...(steps ?? [])]
+        .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+        .map((step) => step.title?.trim())
+        .filter((title) => !!title)
+        .map((title) => `• ${title}`);
+    return lines.join("\n");
+}
+/**
+ * The plan's earliest warning as Outlook reminder minutes.
+ *
+ * A plan can warn several groups at different times; a calendar event has one
+ * reminder. The earliest one is the useful one — it is the moment the work
+ * first needs attention. `0` (reminder on the due date) is deliberate, not
+ * "no reminder": `undefined` means the plan warns nobody.
+ */
+function reminderMinutes(notifications) {
+    if (!notifications?.length)
+        return undefined;
+    const offsets = notifications.map((rule) => rule.trigger === "before" ? Math.max(0, rule.offsetDays ?? 0) : 0);
+    return Math.max(...offsets) * 24 * 60;
+}

package/dist/features/openservice/serviceSchedules/calendarSync/index.d.ts

@@ -0,0 +1,8 @@
+export { eventToPlanFields, mergeReminderRule, OUTLOOK_REMINDER_RULE_ID, parseSubject, } from "./functions/eventToPlan.js";
+export { buildRRule, cadenceToRecurrence, eventToCadence, parseRRule, } from "./functions/outlookRecurrence.js";
+export { planToEvent } from "./functions/planToEvent.js";
+export { findMetaForEvent, findMetaForPlan, SERVICE_CALENDAR_SYNC_CONTEXT, ServiceCalendarMetaConfig, } from "./service/serviceCalendarMeta.js";
+export { CALENDAR_SYNC_CONTEXT_FLAG, ServiceCalendarSyncPoller, } from "./service/ServiceCalendarSyncPoller.js";
+export { connectionForTenant, syncPlanToCalendar, } from "./service/syncPlanToCalendar.js";
+export { OUTLOOK_CONFIG_KEY } from "./types/ServiceSyncTypes.js";
+export type { ServiceCadence, ServiceNotificationRule, ServiceSyncConfigValues, } from "./types/ServiceSyncTypes.js";

package/dist/features/openservice/serviceSchedules/calendarSync/index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OUTLOOK_CONFIG_KEY = exports.syncPlanToCalendar = exports.connectionForTenant = exports.ServiceCalendarSyncPoller = exports.CALENDAR_SYNC_CONTEXT_FLAG = exports.ServiceCalendarMetaConfig = exports.SERVICE_CALENDAR_SYNC_CONTEXT = exports.findMetaForPlan = exports.findMetaForEvent = exports.planToEvent = exports.parseRRule = exports.eventToCadence = exports.cadenceToRecurrence = exports.buildRRule = exports.parseSubject = exports.OUTLOOK_REMINDER_RULE_ID = exports.mergeReminderRule = exports.eventToPlanFields = void 0;
+var eventToPlan_js_1 = require("./functions/eventToPlan.js");
+Object.defineProperty(exports, "eventToPlanFields", { enumerable: true, get: function () { return eventToPlan_js_1.eventToPlanFields; } });
+Object.defineProperty(exports, "mergeReminderRule", { enumerable: true, get: function () { return eventToPlan_js_1.mergeReminderRule; } });
+Object.defineProperty(exports, "OUTLOOK_REMINDER_RULE_ID", { enumerable: true, get: function () { return eventToPlan_js_1.OUTLOOK_REMINDER_RULE_ID; } });
+Object.defineProperty(exports, "parseSubject", { enumerable: true, get: function () { return eventToPlan_js_1.parseSubject; } });
+var outlookRecurrence_js_1 = require("./functions/outlookRecurrence.js");
+Object.defineProperty(exports, "buildRRule", { enumerable: true, get: function () { return outlookRecurrence_js_1.buildRRule; } });
+Object.defineProperty(exports, "cadenceToRecurrence", { enumerable: true, get: function () { return outlookRecurrence_js_1.cadenceToRecurrence; } });
+Object.defineProperty(exports, "eventToCadence", { enumerable: true, get: function () { return outlookRecurrence_js_1.eventToCadence; } });
+Object.defineProperty(exports, "parseRRule", { enumerable: true, get: function () { return outlookRecurrence_js_1.parseRRule; } });
+var planToEvent_js_1 = require("./functions/planToEvent.js");
+Object.defineProperty(exports, "planToEvent", { enumerable: true, get: function () { return planToEvent_js_1.planToEvent; } });
+var serviceCalendarMeta_js_1 = require("./service/serviceCalendarMeta.js");
+Object.defineProperty(exports, "findMetaForEvent", { enumerable: true, get: function () { return serviceCalendarMeta_js_1.findMetaForEvent; } });
+Object.defineProperty(exports, "findMetaForPlan", { enumerable: true, get: function () { return serviceCalendarMeta_js_1.findMetaForPlan; } });
+Object.defineProperty(exports, "SERVICE_CALENDAR_SYNC_CONTEXT", { enumerable: true, get: function () { return serviceCalendarMeta_js_1.SERVICE_CALENDAR_SYNC_CONTEXT; } });
+Object.defineProperty(exports, "ServiceCalendarMetaConfig", { enumerable: true, get: function () { return serviceCalendarMeta_js_1.ServiceCalendarMetaConfig; } });
+var ServiceCalendarSyncPoller_js_1 = require("./service/ServiceCalendarSyncPoller.js");
+Object.defineProperty(exports, "CALENDAR_SYNC_CONTEXT_FLAG", { enumerable: true, get: function () { return ServiceCalendarSyncPoller_js_1.CALENDAR_SYNC_CONTEXT_FLAG; } });
+Object.defineProperty(exports, "ServiceCalendarSyncPoller", { enumerable: true, get: function () { return ServiceCalendarSyncPoller_js_1.ServiceCalendarSyncPoller; } });
+var syncPlanToCalendar_js_1 = require("./service/syncPlanToCalendar.js");
+Object.defineProperty(exports, "connectionForTenant", { enumerable: true, get: function () { return syncPlanToCalendar_js_1.connectionForTenant; } });
+Object.defineProperty(exports, "syncPlanToCalendar", { enumerable: true, get: function () { return syncPlanToCalendar_js_1.syncPlanToCalendar; } });
+var ServiceSyncTypes_js_1 = require("./types/ServiceSyncTypes.js");
+Object.defineProperty(exports, "OUTLOOK_CONFIG_KEY", { enumerable: true, get: function () { return ServiceSyncTypes_js_1.OUTLOOK_CONFIG_KEY; } });

package/dist/features/openservice/serviceSchedules/calendarSync/service/ServiceCalendarSyncPoller.d.ts

@@ -0,0 +1,54 @@
+import { Config } from "../../../../../types/index.js";
+/**
+ * Marker on a save that came from the calendar.
+ *
+ * The outbound side (`syncPlanToCalendar`, called from the `Service_Schedule`
+ * afterSave hook) checks it and stays quiet — otherwise every inbound change
+ * would be written straight back to Outlook, produce a new `changeKey`, come
+ * back through the delta feed as a foreign change, and loop forever. The stored
+ * `changeKey` is the second line of defence; this is the first, and unlike v1's
+ * `!master` check it does not disable outbound sync for every other
+ * master-key writer (the scheduler pausing a plan, a migration, a script).
+ */
+export declare const CALENDAR_SYNC_CONTEXT_FLAG = "fromCalendarSync";
+/**
+ * Pulls Outlook changes into open.SERVICE **v2** maintenance plans.
+ *
+ * One poller per configured connection, driven by the Graph *delta* feed: the
+ * first call reads the whole calendar, each later call only what changed, and
+ * the cursor lives in the Config row so a restart resumes instead of
+ * re-importing. The v1 poller does the same for `Maintenance_Schedule` from the
+ * same connection — the two keep separate cursors (`delta_link` vs
+ * `delta_link_v2`) so neither consumes the other's changes.
+ */
+export declare class ServiceCalendarSyncPoller {
+    private timer;
+    private config;
+    constructor(config: Config);
+    private get values();
+    private get manager();
+    start(intervalMs?: number): this;
+    stop(): void;
+    private poll;
+    private processEvent;
+    private createPlan;
+    private updatePlan;
+    /**
+     * A deleted appointment archives the plan — it never destroys it.
+     *
+     * Executions document that work happened; deleting the plan they point at
+     * would strand that history (the `beforeDelete` hook refuses it, too). The
+     * meta entry goes, so the same plan can be linked to a new event later.
+     */
+    private handleRemoved;
+    /** The machine named in the subject, else the configured fallback. */
+    private resolveEquipment;
+    private findEquipmentByLabel;
+    /**
+     * The cursor is re-read from the Config row on every tick, and written back
+     * after it: the row is also the admin form's storage, so it can change
+     * underneath us.
+     */
+    private loadDeltaLink;
+    private saveDeltaLink;
+}

package/dist/features/openservice/serviceSchedules/calendarSync/service/ServiceCalendarSyncPoller.js

@@ -0,0 +1,248 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceCalendarSyncPoller = exports.CALENDAR_SYNC_CONTEXT_FLAG = void 0;
+const crypto_1 = require("crypto");
+const node_1 = __importDefault(require("parse/node"));
+const CalendarManager_js_1 = require("../../../schedules/calendarSync/service/CalendarManager.js");
+const index_js_1 = require("../../../../../types/index.js");
+const eventToPlan_js_1 = require("../functions/eventToPlan.js");
+const serviceCalendarMeta_js_1 = require("./serviceCalendarMeta.js");
+/**
+ * Marker on a save that came from the calendar.
+ *
+ * The outbound side (`syncPlanToCalendar`, called from the `Service_Schedule`
+ * afterSave hook) checks it and stays quiet — otherwise every inbound change
+ * would be written straight back to Outlook, produce a new `changeKey`, come
+ * back through the delta feed as a foreign change, and loop forever. The stored
+ * `changeKey` is the second line of defence; this is the first, and unlike v1's
+ * `!master` check it does not disable outbound sync for every other
+ * master-key writer (the scheduler pausing a plan, a migration, a script).
+ */
+exports.CALENDAR_SYNC_CONTEXT_FLAG = "fromCalendarSync";
+/**
+ * Pulls Outlook changes into open.SERVICE **v2** maintenance plans.
+ *
+ * One poller per configured connection, driven by the Graph *delta* feed: the
+ * first call reads the whole calendar, each later call only what changed, and
+ * the cursor lives in the Config row so a restart resumes instead of
+ * re-importing. The v1 poller does the same for `Maintenance_Schedule` from the
+ * same connection — the two keep separate cursors (`delta_link` vs
+ * `delta_link_v2`) so neither consumes the other's changes.
+ */
+class ServiceCalendarSyncPoller {
+    timer = null;
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    get values() {
+        return JSON.parse(this.config.get("value"));
+    }
+    get manager() {
+        const values = this.values;
+        return new CalendarManager_js_1.CalendarManager({
+            tenantId: values.tenant_id,
+            clientID: values.client_id,
+            clientSecret: values.client_secret,
+            userMail: values.user_email,
+        });
+    }
+    start(intervalMs = 5 * 60 * 1000) {
+        const valid = this.manager.isValid;
+        if (valid !== true) {
+            console.error(`[ServiceCalendarSync] Not started — invalid configuration: ${valid}`);
+            return this;
+        }
+        this.poll().catch(console.error);
+        this.timer = setInterval(() => this.poll().catch(console.error), intervalMs);
+        return this;
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    async poll() {
+        const result = await this.manager.fetchDelta(await this.loadDeltaLink());
+        if (!result) {
+            console.error("[ServiceCalendarSync] Could not fetch the calendar delta");
+            return;
+        }
+        for (const event of result.events) {
+            try {
+                await this.processEvent(event);
+            }
+            catch (error) {
+                // One unusable event must not cost us the whole batch — and not the
+                // delta cursor either, or it would be retried forever.
+                console.error("[ServiceCalendarSync] Event could not be processed:", event.id, error);
+            }
+        }
+        await this.saveDeltaLink(result.deltaLink);
+    }
+    async processEvent(event) {
+        if (event["@removed"]) {
+            await this.handleRemoved(event.id);
+            return;
+        }
+        // An "exception" is a single moved or edited occurrence of a series. The
+        // plan's own `cadenceExceptions` could hold that, but Graph does not tell
+        // us *which* occurrence was moved in a form we can map back reliably — and
+        // a wrong exception silently moves a maintenance date. The series master
+        // carries the recurrence; exceptions are left to Outlook.
+        if (event.type === "exception")
+            return;
+        const meta = await (0, serviceCalendarMeta_js_1.findMetaForEvent)(event.id);
+        if (!meta) {
+            // Delta payloads are partial — fetch the whole event before creating.
+            const full = await this.manager.fetchEvent(event.id);
+            if (full)
+                await this.createPlan(full);
+            return;
+        }
+        if (event.changeKey &&
+            (0, serviceCalendarMeta_js_1.metaValues)(meta)?.microsoftCalendarChangeKey === event.changeKey) {
+            return; // Our own write, echoed back by the delta feed.
+        }
+        await this.updatePlan(meta, event);
+    }
+    async createPlan(event) {
+        const fields = (0, eventToPlan_js_1.eventToPlanFields)(event);
+        if (!fields) {
+            console.warn(`[ServiceCalendarSync] Event ${event.id} has no usable start — skipped`);
+            return;
+        }
+        const tenant = this.config.get("tenant");
+        const equipment = await this.resolveEquipment(fields.equipmentName, tenant);
+        const plan = new index_js_1.Service_Schedule();
+        plan.set("title", fields.title);
+        plan.set("active", true);
+        plan.set("tenant", tenant);
+        plan.set("cadence", fields.cadence);
+        if (equipment)
+            plan.set("equipment", equipment);
+        // A plan needs at least one step to be executable. The event's note becomes
+        // its description, so what someone wrote in Outlook is not lost — the
+        // checklist proper is then built in the plan editor.
+        plan.set("steps", [
+            {
+                id: (0, crypto_1.randomUUID)(),
+                order: 0,
+                title: fields.title,
+                ...(fields.description ? { description: fields.description } : {}),
+                required: false,
+            },
+        ]);
+        plan.set("notifications", (0, eventToPlan_js_1.mergeReminderRule)([], fields.notification));
+        await plan.save(null, {
+            useMasterKey: true,
+            context: { [exports.CALENDAR_SYNC_CONTEXT_FLAG]: true },
+        });
+        await (0, serviceCalendarMeta_js_1.saveMeta)(plan.id, event.id, event.changeKey, tenant, event);
+        console.log(`[ServiceCalendarSync] Created plan ${plan.id} from event ${event.id}` +
+            (equipment ? ` (machine ${equipment.id})` : " (no machine)"));
+    }
+    async updatePlan(meta, event) {
+        const planId = meta.get("entryObjectId");
+        if (!planId)
+            return;
+        // Delta payloads are partial: without the full event, an unchanged subject
+        // would arrive as `undefined` and wipe the plan's title.
+        const full = (await this.manager.fetchEvent(event.id)) ?? event;
+        const fields = (0, eventToPlan_js_1.eventToPlanFields)(full);
+        if (!fields)
+            return;
+        const plan = await new node_1.default.Query(index_js_1.Service_Schedule)
+            .include("equipment")
+            .get(planId, { useMasterKey: true });
+        plan.set("title", fields.title);
+        plan.set("cadence", fields.cadence);
+        plan.set("notifications", (0, eventToPlan_js_1.mergeReminderRule)(plan.get("notifications"), fields.notification));
+        // The machine only changes if the subject actually names a different one —
+        // a subject without the prefix leaves the existing assignment alone rather
+        // than falling back to the configured default and moving the plan.
+        if (fields.equipmentName) {
+            const equipment = await this.findEquipmentByLabel(fields.equipmentName, this.config.get("tenant"));
+            if (equipment)
+                plan.set("equipment", equipment);
+        }
+        await plan.save(null, {
+            useMasterKey: true,
+            context: { [exports.CALENDAR_SYNC_CONTEXT_FLAG]: true },
+        });
+        if (event.changeKey)
+            await (0, serviceCalendarMeta_js_1.updateChangeKey)(meta, event.changeKey, full);
+    }
+    /**
+     * A deleted appointment archives the plan — it never destroys it.
+     *
+     * Executions document that work happened; deleting the plan they point at
+     * would strand that history (the `beforeDelete` hook refuses it, too). The
+     * meta entry goes, so the same plan can be linked to a new event later.
+     */
+    async handleRemoved(eventId) {
+        const meta = await (0, serviceCalendarMeta_js_1.findMetaForEvent)(eventId);
+        if (!meta)
+            return;
+        const planId = meta.get("entryObjectId");
+        if (planId) {
+            try {
+                const plan = await new node_1.default.Query(index_js_1.Service_Schedule).get(planId, {
+                    useMasterKey: true,
+                });
+                plan.set("active", false);
+                plan.set("deletedAt", new Date());
+                await plan.save(null, {
+                    useMasterKey: true,
+                    context: { [exports.CALENDAR_SYNC_CONTEXT_FLAG]: true },
+                });
+            }
+            catch (error) {
+                console.error(`[ServiceCalendarSync] Could not archive plan ${planId} of deleted event ${eventId}:`, error);
+            }
+        }
+        await meta.destroy({ useMasterKey: true });
+    }
+    /** The machine named in the subject, else the configured fallback. */
+    async resolveEquipment(label, tenant) {
+        if (label) {
+            const found = await this.findEquipmentByLabel(label, tenant);
+            if (found)
+                return found;
+            console.warn(`[ServiceCalendarSync] No machine named "${label}" — falling back to the default`);
+        }
+        const defaultId = this.values.default_equipment_id;
+        if (!defaultId)
+            return undefined;
+        return ((await new node_1.default.Query(index_js_1.Service_Equipment)
+            .equalTo("objectId", defaultId)
+            .first({ useMasterKey: true })) ?? undefined);
+    }
+    async findEquipmentByLabel(label, tenant) {
+        const query = new node_1.default.Query(index_js_1.Service_Equipment).equalTo("label", label);
+        if (tenant)
+            query.equalTo("tenant", tenant);
+        query.notEqualTo("deleted", true);
+        return (await query.first({ useMasterKey: true })) ?? undefined;
+    }
+    /**
+     * The cursor is re-read from the Config row on every tick, and written back
+     * after it: the row is also the admin form's storage, so it can change
+     * underneath us.
+     */
+    async loadDeltaLink() {
+        this.config = await this.config.fetch({ useMasterKey: true });
+        return this.values.delta_link_v2;
+    }
+    async saveDeltaLink(link) {
+        this.config = await this.config.fetch({ useMasterKey: true });
+        const values = this.values;
+        values.delta_link_v2 = link;
+        this.config.set("value", JSON.stringify(values));
+        await this.config.save(null, { useMasterKey: true });
+    }
+}
+exports.ServiceCalendarSyncPoller = ServiceCalendarSyncPoller;

package/dist/features/openservice/serviceSchedules/calendarSync/service/serviceCalendarMeta.d.ts

@@ -0,0 +1,55 @@
+import type { MetaConfig } from "../../../../../types/custom/MetaField.js";
+import { Meta_Entry, Tenant } from "../../../../../types/index.js";
+import type { GraphEventResponse } from "../../../schedules/calendarSync/types/Event.js";
+/**
+ * Which calendar event belongs to which v2 maintenance plan.
+ *
+ * Same mechanism as v1 (a `Meta_Entry` per plan), but a **separate context**:
+ * one Outlook connection serves both generations, and a v1 entry pointing at a
+ * `Maintenance_Schedule` must never be mistaken for a v2 one pointing at an
+ * `OD3_Service_Schedule`. The stored `changeKey` is what keeps the two sides
+ * from echoing each other — see `ServiceCalendarSyncPoller`.
+ */
+export declare const SERVICE_CALENDAR_SYNC_CONTEXT: string;
+/**
+ * The last known state of the event, as far as the sync needs it.
+ *
+ * Kept so an outbound update can preserve what the user set in Outlook and this
+ * side has no field for — the event's times above all: a plan knows a due
+ * *date*, and writing that back must not turn someone's 9:00 appointment into
+ * an all-day block.
+ */
+export interface ServiceCalendarEventSnapshot {
+    id: string;
+    subject?: string;
+    start: {
+        dateTime: string;
+        timeZone: string;
+    };
+    end: {
+        dateTime: string;
+        timeZone: string;
+    };
+    isAllDay?: boolean;
+    isCancelled?: boolean;
+    recurrence?: GraphEventResponse["recurrence"];
+}
+export interface ServiceCalendarMetaValues {
+    microsoftCalendarEventId: string;
+    microsoftCalendarChangeKey?: string;
+    microsoftCalendarEvent?: ServiceCalendarEventSnapshot;
+}
+/** Shown by the meta plugin when the entry is inspected in the frontend. */
+export declare const ServiceCalendarMetaConfig: MetaConfig;
+export declare function findMetaForPlan(scheduleId: string): Promise<Meta_Entry | null>;
+export declare function findMetaForEvent(eventId: string): Promise<Meta_Entry | null>;
+export declare function saveMeta(scheduleId: string, eventId: string, changeKey?: string, tenant?: Tenant, event?: GraphEventResponse): Promise<Meta_Entry>;
+/**
+ * Remember the `changeKey` of the version we just wrote.
+ *
+ * This is the loop breaker: the delta feed will report our own write back to
+ * us, and the poller recognises it by this key. Losing it means one harmless
+ * extra round trip; writing the wrong one means an endless echo.
+ */
+export declare function updateChangeKey(entry: Meta_Entry, changeKey: string, event?: GraphEventResponse): Promise<void>;
+export declare function metaValues(entry: Meta_Entry): ServiceCalendarMetaValues | undefined;

package/dist/features/openservice/serviceSchedules/calendarSync/service/serviceCalendarMeta.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceCalendarMetaConfig = exports.SERVICE_CALENDAR_SYNC_CONTEXT = void 0;
+exports.findMetaForPlan = findMetaForPlan;
+exports.findMetaForEvent = findMetaForEvent;
+exports.saveMeta = saveMeta;
+exports.updateChangeKey = updateChangeKey;
+exports.metaValues = metaValues;
+const node_1 = __importDefault(require("parse/node"));
+const index_js_1 = require("../../../../../types/index.js");
+/**
+ * Which calendar event belongs to which v2 maintenance plan.
+ *
+ * Same mechanism as v1 (a `Meta_Entry` per plan), but a **separate context**:
+ * one Outlook connection serves both generations, and a v1 entry pointing at a
+ * `Maintenance_Schedule` must never be mistaken for a v2 one pointing at an
+ * `OD3_Service_Schedule`. The stored `changeKey` is what keeps the two sides
+ * from echoing each other — see `ServiceCalendarSyncPoller`.
+ */
+exports.SERVICE_CALENDAR_SYNC_CONTEXT = JSON.stringify([
+    "service",
+    "schedule",
+    "sync",
+    "microsoft",
+]);
+/** Shown by the meta plugin when the entry is inspected in the frontend. */
+exports.ServiceCalendarMetaConfig = {
+    fields: [
+        {
+            name: "microsoftCalendarEventId",
+            type: "string",
+            label: "Microsoft Calendar Event ID",
+        },
+        {
+            name: "microsoftCalendarChangeKey",
+            type: "string",
+            label: "Microsoft Calendar Change Key",
+        },
+    ],
+};
+function toSnapshot(event) {
+    return {
+        id: event.id,
+        subject: event.subject,
+        start: event.start,
+        end: event.end,
+        isAllDay: event.isAllDay,
+        isCancelled: event.isCancelled,
+        recurrence: event.recurrence ?? undefined,
+    };
+}
+async function findMetaForPlan(scheduleId) {
+    return ((await new node_1.default.Query(index_js_1.Meta_Entry)
+        .equalTo("context", exports.SERVICE_CALENDAR_SYNC_CONTEXT)
+        .equalTo("entryClassName", index_js_1.Service_Schedule.className)
+        .equalTo("entryObjectId", scheduleId)
+        .first({ useMasterKey: true })) ?? null);
+}
+async function findMetaForEvent(eventId) {
+    return ((await new node_1.default.Query(index_js_1.Meta_Entry)
+        .equalTo("context", exports.SERVICE_CALENDAR_SYNC_CONTEXT)
+        .equalTo("entryClassName", index_js_1.Service_Schedule.className)
+        // Dot access into the `values` Object column — Mongo resolves it, the
+        // generated type only knows top-level columns.
+        // @ts-expect-error
+        .equalTo("values.microsoftCalendarEventId", eventId)
+        .first({ useMasterKey: true })) ?? null);
+}
+async function saveMeta(scheduleId, eventId, changeKey, tenant, event) {
+    let entry = await findMetaForPlan(scheduleId);
+    if (!entry) {
+        entry = new index_js_1.Meta_Entry();
+        entry.set("context", exports.SERVICE_CALENDAR_SYNC_CONTEXT);
+        entry.set("entryClassName", index_js_1.Service_Schedule.className);
+        entry.set("entryObjectId", scheduleId);
+        entry.set("tenant", tenant);
+        entry.set("config", {});
+    }
+    const values = {
+        microsoftCalendarEventId: eventId,
+    };
+    if (changeKey)
+        values.microsoftCalendarChangeKey = changeKey;
+    if (event)
+        values.microsoftCalendarEvent = toSnapshot(event);
+    entry.set("values", values);
+    return entry.save(null, { useMasterKey: true });
+}
+/**
+ * Remember the `changeKey` of the version we just wrote.
+ *
+ * This is the loop breaker: the delta feed will report our own write back to
+ * us, and the poller recognises it by this key. Losing it means one harmless
+ * extra round trip; writing the wrong one means an endless echo.
+ */
+async function updateChangeKey(entry, changeKey, event) {
+    entry.set("values", {
+        ...entry.get("values"),
+        microsoftCalendarChangeKey: changeKey,
+        ...(event ? { microsoftCalendarEvent: toSnapshot(event) } : {}),
+    });
+    await entry.save(null, { useMasterKey: true });
+}
+function metaValues(entry) {
+    return entry.get("values");
+}