rhombus-node-mcp 0.1.56 → 0.1.57

package/dist/api/camera-uptime-tool-api.js

@@ -1,4 +1,6 @@
+import { logger } from "../logger.js";
 import { postApi } from "../network/network.js";
+import { cachedPostApi } from "../network/org-reference-cache.js";
 function computeUptimeStats(cameraUuid, cameraName, locationUuid, windows, startTimeSec, endTimeSec) {
     const totalPeriodSeconds = endTimeSec - startTimeSec;
     let totalUptimeSeconds = 0;
@@ -47,8 +49,11 @@ export async function getCameraUptime(cameraUuid, startTimeSec, endTimeSec, requ
         route: "/camera/getUptimeWindows",
         body: {
             cameraUuid,
-            startTime: startTimeSec,
-            endTime: endTimeSec,
+            // The endpoint takes MILLISECONDS despite its (formerly wrong) swagger
+            // docs saying seconds — passing seconds makes the server clamp the
+            // range away entirely and return zero windows for every camera.
+            startTime: startTimeSec * 1000,
+            endTime: endTimeSec * 1000,
         },
         modifiers: requestModifiers,
         sessionId,
@@ -58,8 +63,31 @@ export async function getCameraUptime(cameraUuid, startTimeSec, endTimeSec, requ
     }
     return computeUptimeStats(cameraUuid, undefined, undefined, (res.uptimeWindows ?? []), startTimeSec, endTimeSec);
 }
+async function getFleetUptimeWindowsForOrg(startTimeSec, endTimeSec, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/camera/getUptimeWindowsForOrg",
+        body: {
+            startTimeMs: startTimeSec * 1000,
+            endTimeMs: endTimeSec * 1000,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    if (res.error || !Array.isArray(res.uptimeByDevice)) {
+        // Most likely an older webservice without the batch route yet.
+        logger.warn(`getUptimeWindowsForOrg unavailable (${res.status ?? "no uptimeByDevice in response"}); falling back to per-camera fan-out`);
+        return null;
+    }
+    const windowsByCamera = new Map();
+    for (const entry of res.uptimeByDevice) {
+        if (entry?.deviceUuid) {
+            windowsByCamera.set(entry.deviceUuid, entry.uptimeWindows ?? []);
+        }
+    }
+    return windowsByCamera;
+}
 export async function getFleetUptime(startTimeSec, endTimeSec, requestModifiers, sessionId) {
-    const cameraListRes = await postApi({
+    const cameraListRes = await cachedPostApi({
         route: "/camera/getMinimalCameraStateList",
         body: {},
         modifiers: requestModifiers,
@@ -73,28 +101,37 @@ export async function getFleetUptime(startTimeSec, endTimeSec, requestModifiers,
         locationUuid: c.locationUuid,
     }));
     const uptimeResults = [];
-    const batchSize = 10;
-    for (let i = 0; i < cameras.length; i += batchSize) {
-        const batch = cameras.slice(i, i + batchSize);
-        const batchResults = await Promise.all(batch.map(async (cam) => {
-            try {
-                const res = await postApi({
-                    route: "/camera/getUptimeWindows",
-                    body: {
-                        cameraUuid: cam.uuid,
-                        startTime: startTimeSec,
-                        endTime: endTimeSec,
-                    },
-                    modifiers: requestModifiers,
-                    sessionId,
-                });
-                return computeUptimeStats(cam.uuid, cam.name, cam.locationUuid, (res.uptimeWindows ?? []), startTimeSec, endTimeSec);
-            }
-            catch {
-                return computeUptimeStats(cam.uuid, cam.name, cam.locationUuid, [], startTimeSec, endTimeSec);
-            }
-        }));
-        uptimeResults.push(...batchResults);
+    const batchWindows = await getFleetUptimeWindowsForOrg(startTimeSec, endTimeSec, requestModifiers, sessionId);
+    if (batchWindows) {
+        for (const cam of cameras) {
+            uptimeResults.push(computeUptimeStats(cam.uuid, cam.name, cam.locationUuid, batchWindows.get(cam.uuid) ?? [], startTimeSec, endTimeSec));
+        }
+    }
+    else {
+        const batchSize = 10;
+        for (let i = 0; i < cameras.length; i += batchSize) {
+            const batch = cameras.slice(i, i + batchSize);
+            const batchResults = await Promise.all(batch.map(async (cam) => {
+                try {
+                    const res = await postApi({
+                        route: "/camera/getUptimeWindows",
+                        body: {
+                            cameraUuid: cam.uuid,
+                            // milliseconds — see getCameraUptime
+                            startTime: startTimeSec * 1000,
+                            endTime: endTimeSec * 1000,
+                        },
+                        modifiers: requestModifiers,
+                        sessionId,
+                    });
+                    return computeUptimeStats(cam.uuid, cam.name, cam.locationUuid, (res.uptimeWindows ?? []), startTimeSec, endTimeSec);
+                }
+                catch {
+                    return computeUptimeStats(cam.uuid, cam.name, cam.locationUuid, [], startTimeSec, endTimeSec);
+                }
+            }));
+            uptimeResults.push(...batchResults);
+        }
     }
     uptimeResults.sort((a, b) => a.uptimePercentage - b.uptimePercentage);
     const avgUptime = uptimeResults.length > 0

package/dist/api/clips-tool-api.js

@@ -1,4 +1,4 @@
-import { postApi } from "../network/network.js";
+import { postApi, throwIfApiError } from "../network/network.js";
 export async function getSavedClips(args, requestModifiers, sessionId) {
     const res = await postApi({
         route: "/event/getClipsWithProgress",
@@ -68,8 +68,7 @@ export async function getClipGroups(requestModifiers, sessionId) {
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error)
-        throw new Error(JSON.stringify(res));
+    throwIfApiError(res);
     return {
         clipGroups: (res.clipGroups || []).map((group) => ({
             uuid: group.uuid ?? undefined,
@@ -85,8 +84,7 @@ export async function getSharedClipGroups(requestModifiers, sessionId) {
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error)
-        throw new Error(JSON.stringify(res));
+    throwIfApiError(res);
     return {
         sharedClipGroups: (res.sharedClipGroups || []).map((group) => ({
             uuid: group.uuid ?? undefined,
@@ -108,8 +106,7 @@ export async function createClip(cameraUuid, startTimeMs, endTimeMs, requestModi
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error)
-        throw new Error(JSON.stringify(res));
+    throwIfApiError(res);
     return { spliceResult: { success: true, clipUuid: res.clipUuid ?? undefined } };
 }
 export async function deleteClip(clipUuid, requestModifiers, sessionId) {
@@ -119,7 +116,46 @@ export async function deleteClip(clipUuid, requestModifiers, sessionId) {
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error)
-        throw new Error(JSON.stringify(res));
+    throwIfApiError(res);
     return { deleteResult: { success: true } };
 }
+/**
+ * Retitle / re-describe a saved clip.
+ *
+ * `updateSavedClip` is a whole-object write, not a selective one: omitting
+ * `title` blanks the title rather than leaving it. So this reads the clip first
+ * and merges, which also gives the caller a real "no such clip" error instead of
+ * a silent no-op on a bad uuid.
+ */
+export async function updateClip(clipUuid, changes, requestModifiers, sessionId) {
+    const current = await postApi({
+        route: "/event/getSavedClipDetails",
+        body: { clipUuid },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(current);
+    const existing = current.savedClip;
+    if (!existing) {
+        return {
+            error: `No saved clip has the uuid "${clipUuid}". Use requestType 'saved' to list the clips that exist — do not guess a uuid.`,
+        };
+    }
+    const res = await postApi({
+        route: "/event/updateSavedClip",
+        body: {
+            savedClipUuid: clipUuid,
+            title: changes.title ?? existing.title ?? undefined,
+            description: changes.description ?? existing.description ?? undefined,
+            accessSettings: existing.accessSettings ?? undefined,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return {
+        updateResult: { success: true, clipUuid },
+        warningMsg: res.warningMsg ?? undefined,
+        existingTitle: existing.title ?? undefined,
+    };
+}

package/dist/api/create-tool-api.js

@@ -1,11 +1,13 @@
 import { logger } from "../logger.js";
-import { postApi } from "../network/network.js";
-export async function createVideoWall(options, requestModifiers, sessionId) {
-    // our grid layout settings is a little complicated. we'll dumb it down
-    // to certain presets based on length of device list
-    const numDevices = options?.settings.numVisibleDevicesAtOnce ??
-        options?.deviceList?.length ??
-        1;
+import { postApi, throwIfApiError } from "../network/network.js";
+/**
+ * Our grid layout settings are a little complicated, so we dumb them down to
+ * presets chosen by how many devices are visible at once.
+ *
+ * Exported because UPDATE has to recompute it: a wall grown from 4 cameras to 9
+ * while keeping its 2x2 layout would render five of them invisibly.
+ */
+export function computeGridSettings(numDevices) {
     let gridSettings;
     if (numDevices <= 1) {
         gridSettings = {
@@ -118,6 +120,10 @@ export async function createVideoWall(options, requestModifiers, sessionId) {
             gridSize: { width: 8, height: 8 },
         };
     }
+    return gridSettings;
+}
+export async function createVideoWall(options, requestModifiers, sessionId) {
+    const gridSettings = computeGridSettings(options?.settings.numVisibleDevicesAtOnce ?? options?.deviceList?.length ?? 1);
     const body = {
         videoWall: {
             displayName: options?.displayName,
@@ -178,3 +184,45 @@ export async function handleCreateVideoWallRequest(videoWallCreateOptions, reque
         };
     }
 }
+/**
+ * api2's `updateVideoWalls` REPLACES the whole videoWall object, so the caller
+ * must read the current wall and merge before calling this — see the tool's
+ * update branch.
+ */
+export async function updateVideoWall(videoWall, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/camera/updateVideoWalls",
+        body: { videoWall },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return {
+        updated: { success: true, uuid: videoWall.uuid },
+        warningMsg: res.warningMsg ?? undefined,
+    };
+}
+export async function deleteVideoWall(uuid, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/camera/deleteVideoWall",
+        body: { uuid },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return {
+        deleted: { success: true, uuid },
+        warningMsg: res.warningMsg ?? undefined,
+    };
+}
+/** The raw wall, for the read-modify-write that update requires. */
+export async function findVideoWall(uuid, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/camera/getVideoWalls",
+        body: {},
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return res.videoWalls?.find(wall => wall?.uuid === uuid) ?? undefined;
+}

package/dist/api/door-tool-api.js

@@ -1,4 +1,4 @@
-import { postApi } from "../network/network.js";
+import { postApi, throwIfApiError } from "../network/network.js";
 export async function getDoorControllerRules(doorControllerUuid, requestModifiers, sessionId) {
     const res = await postApi({
         route: "/doorcontroller/getDoorControllerRules",
@@ -6,9 +6,7 @@ export async function getDoorControllerRules(doorControllerUuid, requestModifier
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error) {
-        throw new Error(JSON.stringify(res));
-    }
+    throwIfApiError(res);
     return (res.rules?.map((rule) => ({
         uuid: rule.uuid ?? undefined,
         name: rule.name ?? undefined,
@@ -24,9 +22,7 @@ export async function createDoorControllerRule(ruleConfig, requestModifiers, ses
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error) {
-        throw new Error(JSON.stringify(res));
-    }
+    throwIfApiError(res);
     return {
         uuid: res.ruleUuid ?? undefined,
         success: true,
@@ -39,9 +35,7 @@ export async function getDoorPolicies(requestModifiers, sessionId) {
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error) {
-        throw new Error(JSON.stringify(res));
-    }
+    throwIfApiError(res);
     return (res.policies?.map((policy) => ({
         uuid: policy.uuid ?? undefined,
         name: policy.name ?? undefined,
@@ -56,11 +50,78 @@ export async function createDoorPolicy(policyConfig, requestModifiers, sessionId
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error) {
-        throw new Error(JSON.stringify(res));
-    }
+    throwIfApiError(res);
     return {
         uuid: res.policyUuid ?? undefined,
         success: true,
     };
 }
+/**
+ * api2's `updateDoorPolicy` REPLACES the policy object, so the caller must read
+ * the current policy and merge before calling this.
+ */
+export async function updateDoorPolicy(policyConfig, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/policy/updateDoorPolicy",
+        body: { policy: policyConfig },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return { success: true, warningMsg: res.warningMsg ?? undefined };
+}
+export async function deleteDoorPolicy(policyUuid, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/policy/deleteDoorPolicy",
+        body: { policyUuid },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return { success: true, uuid: policyUuid, warningMsg: res.warningMsg ?? undefined };
+}
+export async function getDoorControllerRule(doorControllerUuid, ruleUuid, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/doorcontroller/getDoorControllerRule",
+        body: {
+            doorControllerUuid,
+            ruleUuid,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return res.rule ?? undefined;
+}
+/**
+ * api2's `updateDoorControllerRule` REPLACES the rule, so the caller must read
+ * the current rule and merge before calling this.
+ */
+export async function updateDoorControllerRule(doorControllerUuid, ruleConfig, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/doorcontroller/updateDoorControllerRule",
+        body: {
+            doorControllerUuid,
+            rule: ruleConfig,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    // Doorcontroller_UpdateDoorControllerRuleWSResponse carries only `rule` — no
+    // warningMsg channel exists on it, unlike the policy endpoints.
+    return { success: true, rule: res.rule ?? undefined };
+}
+export async function deleteDoorControllerRule(doorControllerUuid, ruleUuid, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/doorcontroller/deleteDoorControllerRule",
+        body: {
+            doorControllerUuid,
+            ruleUuid,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return { success: true, uuid: ruleUuid };
+}

package/dist/api/entity-lookup-tool-api.js

@@ -30,13 +30,20 @@ export async function getAllEntities(deviceUuids, timeZone, tempUnit, requestMod
         getEnvironmentalGateways(timeZone, requestModifiers, sessionId),
     ];
     const responses = await Promise.all(promises);
-    // Filter each response to only include devices with matching UUIDs and fetch device features
+    // Filter each response to only include devices with matching UUIDs and fetch device features.
+    // deviceUuids === null means "no UUID filter" (return all entities); in that case skip the
+    // per-device getDeviceFeatures fan-out — running it for every device in the org would be an
+    // N+1 feature-call storm. License/feature details are only attached for explicit UUID lists.
     for (let i = 0; i < responses.length; i++) {
         const response = responses[i];
         // Look through keys and find any with an array
         for (const key of Object.keys(response)) {
             const value = response[key];
             if (Array.isArray(value)) {
+                if (deviceUuids === null) {
+                    response[`${key}Count`] = value.length;
+                    continue;
+                }
                 // Filter to only include devices with matching UUIDs
                 const filteredDevices = value.filter((item) => {
                     return deviceUuids.includes(item.uuid);

package/dist/api/events-tool-api.js

@@ -1,6 +1,8 @@
 import z from "zod";
 import { FIVE_SECONDS_MS, THREE_HOURS_MS } from "../constants.js";
+import { logger } from "../logger.js";
 import { postApi } from "../network/network.js";
+import { getAccessControlledDoors } from "./get-entity-tool-api.js";
 import { formatTimestamp } from "../util.js";
 import { tempFunc, TempUnit } from "../utils/temp.js";
 // Type definitions
@@ -33,7 +35,13 @@ function mapAccessControlEvent(credEvent, timeZone) {
         datetime: credEvent?.timestampMs ? formatTimestamp(credEvent.timestampMs, timeZone) : undefined,
     };
 }
-async function getAccessControlEventsForDoor(doorUuid, startTime, endTime, timeZone, requestModifiers, sessionId) {
+// Newest-N cap per door: the pagination loop below walks backwards through a
+// door's history and would otherwise fetch every event in a wide time window.
+const MAX_ACCESS_CONTROL_EVENTS_PER_DOOR = 500;
+// Defensive default window when no startTime reaches this layer.
+const DEFAULT_ACCESS_CONTROL_WINDOW_MS = 24 * 60 * 60 * 1000;
+async function getAccessControlEventsForDoor(doorUuid, startTimeArg, endTime, timeZone, requestModifiers, sessionId) {
+    const startTime = startTimeArg ?? Date.now() - DEFAULT_ACCESS_CONTROL_WINDOW_MS;
     const allEvents = [];
     let createdBeforeMs = endTime;
     while (true) {
@@ -58,6 +66,10 @@ async function getAccessControlEventsForDoor(doorUuid, startTime, endTime, timeZ
             .map((credEvent) => mapAccessControlEvent(credEvent, timeZone))
             .filter(Boolean);
         allEvents.push(...mappedEvents);
+        if (allEvents.length >= MAX_ACCESS_CONTROL_EVENTS_PER_DOOR) {
+            logger.info(`access-control events for door ${doorUuid} capped at newest ${MAX_ACCESS_CONTROL_EVENTS_PER_DOOR}`);
+            break;
+        }
         if (componentEvents.length < ACCESS_CONTROL_EVENT_BATCH_SIZE) {
             break;
         }
@@ -84,7 +96,68 @@ async function getAccessControlEventsForDoor(doorUuid, startTime, endTime, timeZ
         }
         createdBeforeMs = oldestTimestamp;
     }
-    return allEvents;
+    // Pages accumulate newest → oldest, so slicing keeps the newest events.
+    return allEvents.slice(0, MAX_ACCESS_CONTROL_EVENTS_PER_DOOR);
+}
+/** Substrings marking a component event type that only an access-controlled door emits. */
+const DOOR_RELATED_COMPONENT_EVENT_MARKERS = [
+    "Door",
+    "Credential",
+    "RequestToExit",
+    "AccessControlUnit",
+    "Aperio",
+];
+function isDoorRelatedComponentEventQuery(eventTypes) {
+    // No filter means "all types", which includes the door ones.
+    if (eventTypes.length === 0)
+        return true;
+    return eventTypes.some(t => DOOR_RELATED_COMPONENT_EVENT_MARKERS.some(marker => t.includes(marker)));
+}
+/**
+ * Explains an empty component-events result when the caller scoped it to a location
+ * that has no access-controlled doors.
+ *
+ * Without this the tool returns a bare `{componentEvents: []}` and the model reports
+ * "no door activity" — which is what happened in prod when it queried a real but
+ * doorless location while 42 doors sat at seven other locations. The door list is a
+ * cached call, and this only runs on the empty-result path, so it costs nothing on
+ * the hot path.
+ */
+export async function describeEmptyComponentEventResult(locationUuid, eventTypes, requestModifiers, sessionId) {
+    if (!isDoorRelatedComponentEventQuery(eventTypes))
+        return undefined;
+    let doors;
+    try {
+        const response = await getAccessControlledDoors(requestModifiers, sessionId);
+        doors = response.accessControlledDoors ?? [];
+    }
+    catch (error) {
+        logger.debug(`Could not load doors to annotate empty component-events result: ${error}`);
+        return undefined;
+    }
+    if (doors.some(door => door.locationUuid === locationUuid))
+        return undefined;
+    const doorsPerLocation = new Map();
+    for (const door of doors) {
+        if (door.locationUuid) {
+            doorsPerLocation.set(door.locationUuid, (doorsPerLocation.get(door.locationUuid) ?? 0) + 1);
+        }
+    }
+    if (doorsPerLocation.size === 0) {
+        return (`No component events were returned, and this organization has no access-controlled doors at any location. ` +
+            `Do not report this as "no door activity" without saying that no doors are configured.`);
+    }
+    const MAX_LISTED_LOCATIONS = 20;
+    const listed = [...doorsPerLocation.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, MAX_LISTED_LOCATIONS)
+        .map(([uuid, count]) => `${uuid} (${count})`)
+        .join(", ");
+    const omitted = doorsPerLocation.size - Math.min(doorsPerLocation.size, MAX_LISTED_LOCATIONS);
+    return (`Location ${locationUuid} has no access-controlled doors, so this query could not return door events — ` +
+        `the empty result does not mean there was no door activity. Doors exist at these locations ` +
+        `(locationUuid and door count): ${listed}${omitted > 0 ? `, and ${omitted} more` : ""}. ` +
+        `Re-run this query for those locations before answering.`);
 }
 export async function getBrivoAccessControlEvents(startTime, endTime, timeZone, requestModifiers, sessionId) {
     // Step 1: fetch Brivo integration config to get configured doors and their location UUIDs
@@ -99,8 +172,8 @@ export async function getBrivoAccessControlEvents(startTime, endTime, timeZone,
     const doorInfoMap = brivoSettings?.doorInfoMap ?? {};
     const brivoDoors = Object.entries(doorInfoMap)
         .filter(([, info]) => info != null)
-        .map(([brivoDoornId, info]) => ({
-        brivoDoornId,
+        .map(([brivoDoorId, info]) => ({
+        brivoDoorId,
         doorName: info.doorName ?? undefined,
         locationUuid: info.locationUuid ?? undefined,
     }));
@@ -194,7 +267,7 @@ export async function getAccessControlEvents(doorUuids, startTime, endTime, time
     // Flatten all componentEvents into a single array
     const accessControlEvents = responses.flatMap(events => events);
     accessControlEvents.sort((a, b) => (b.timestampMs || 0) - (a.timestampMs || 0));
-    console.error(`componentEvents: ${JSON.stringify(accessControlEvents)}`);
+    logger.debug(`componentEvents: ${accessControlEvents.length} access-control events`);
     return accessControlEvents;
 }
 export async function getCameraFootageSeekpointEvents(cameraUuid, duration, startTime, requestModifiers, sessionId) {
@@ -438,7 +511,7 @@ startTime, endTime, timeZone, requestModifiers, sessionId) {
     });
     // Sort events by timestamp (newest first)
     events.sort((a, b) => (b.timestampMs || 0) - (a.timestampMs || 0));
-    console.error(`componentEvents: ${JSON.stringify(events)}`);
+    logger.debug(`componentEvents: ${events.length} events`);
     return events;
 }
 export async function getButtonPressEvents(sensorUuid, startTime, endTime, timeZone, requestModifiers, sessionId) {