rhombus-node-mcp 0.1.55 → 0.1.57

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

@@ -1,4 +1,4 @@
-import { postApi } from "../network/network.js";
+import { apiWarning, postApi, throwIfApiError } from "../network/network.js";
 import { formatTimestamp } from "../util.js";
 import { removeNulls } from "../utils/remove-nulls.js";
 export async function getFaceEvents(args, timeZone, requestModifiers, sessionId) {
@@ -78,8 +78,7 @@ export async function searchSimilarFaces(faceEventUuid, timeZone, requestModifie
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error)
-        throw new Error(JSON.stringify(res));
+    throwIfApiError(res);
     return (res.faceEvents || []).map((event) => ({
         uuid: event.uuid ?? undefined,
         deviceUuid: event.deviceUuid ?? undefined,
@@ -98,8 +97,7 @@ export async function getFaceMatchmakers(requestModifiers, sessionId) {
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error)
-        throw new Error(JSON.stringify(res));
+    throwIfApiError(res);
     return (res.faceMatchmakers || []).map((m) => ({
         uuid: m.uuid ?? undefined,
         personUuid: m.personUuid ?? undefined,
@@ -122,8 +120,7 @@ export async function getFaceEventsByPerson(personUuid, timeZone, requestModifie
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error)
-        throw new Error(JSON.stringify(res));
+    throwIfApiError(res);
     const faceEvents = (res.faceEvents || []).map((event) => ({
         uuid: event.uuid ?? undefined,
         personUuid: event.personUuid ?? undefined,
@@ -137,3 +134,111 @@ export async function getFaceEventsByPerson(personUuid, timeZone, requestModifie
         lastEvaluatedKey: res.lastEvaluatedKey,
     };
 }
+// ---------------------------------------------------------------------------
+// Person write paths
+// ---------------------------------------------------------------------------
+export async function findPerson(personUuid, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/faceRecognition/person/findPeopleByOrg",
+        body: {},
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return res.people?.find(person => person?.uuid === personUuid) ?? undefined;
+}
+export async function createPerson(name, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/faceRecognition/person/createPerson",
+        body: { name },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return {
+        success: true,
+        uuid: res.person?.uuid ?? undefined,
+        warningMsg: apiWarning(res),
+    };
+}
+/**
+ * Selective person update.
+ *
+ * api2 marks which fields were deliberately set via `updatedSetMethodMap`
+ * rather than inferring it from presence — so a field omitted from that map is
+ * left alone, and a field IN the map with no value is cleared. Only the fields
+ * the caller actually changed are flagged.
+ *
+ * The keys are SETTER names (`setName`, `setEmail`), NOT field names. The spec
+ * declares the map as an open `{string: boolean}`, so nothing enforces this.
+ * Sending `{name: true}` returns `error: false` and bumps the record's
+ * `updatedOn` while leaving the name unchanged — a silent no-op that reports
+ * success. Verified against api2.itg on 2026-08-05; pinned by
+ * `test/api/faces-tool-api.test.ts`.
+ */
+export async function updatePerson(personUuid, changes, requestModifiers, sessionId) {
+    const updatedSetMethodMap = {};
+    if (changes.name !== undefined)
+        updatedSetMethodMap.setName = true;
+    if (changes.email !== undefined)
+        updatedSetMethodMap.setEmail = true;
+    const res = await postApi({
+        route: "/faceRecognition/person/updatePerson",
+        body: {
+            personSelectiveUpdate: {
+                uuid: personUuid,
+                name: changes.name,
+                email: changes.email,
+                updatedSetMethodMap,
+            },
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return { success: true, uuid: personUuid, warningMsg: apiWarning(res) };
+}
+export async function deletePerson(personUuid, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/faceRecognition/person/deletePerson",
+        body: {
+            personUuid,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return { success: true, uuid: personUuid, warningMsg: apiWarning(res) };
+}
+export async function changePersonLabel(personUuid, label, action, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: action === "add"
+            ? "/faceRecognition/person/addPersonLabel"
+            : "/faceRecognition/person/removePersonLabel",
+        body: {
+            personUuid,
+            label,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return { success: true, uuid: personUuid, label, warningMsg: apiWarning(res) };
+}
+/**
+ * Delete one enrolled face image. Keyed on `faceId`, NOT on a person uuid — a
+ * person can have several matchmakers, and deleting one only removes that
+ * enrolled image, leaving the person and their other faces intact.
+ */
+export async function deleteFaceMatchmaker(faceId, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/faceRecognition/matchmaker/deleteFaceMatchmaker",
+        body: {
+            faceId,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return { success: true, faceId, warningMsg: apiWarning(res) };
+}

package/dist/api/get-accessible-apps.js

@@ -1,5 +1,11 @@
 import { logger } from "../logger.js";
 import { postApi } from "../network/network.js";
+import { RhombusAppEnum } from "../types/schema.js";
+/**
+ * `enduser.id` for a support session whose payload carries no `supportSession`
+ * block (webservice older than the additive `sessionType`/`supportSession` fields).
+ */
+export const SUPPORT_SESSION_MARKER = "support-session";
 /**
  * Single cached `getCurrentUser` fetch per session. Both `resolveAccessibleApps`
  * and `resolveSessionIdentity` read from this cache, so identity for tracing
@@ -7,6 +13,38 @@ import { postApi } from "../network/network.js";
  * the session; failures are NOT cached so transient errors don't poison it.
  */
 const cache = new Map();
+function optionalString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * `sessionType` and `supportSession` are ADDITIVE fields on
+ * GetCurrentUserWSResponse (webservice, SUPPORT_AUTHORITY_MIND C.4). They are
+ * not in the generated client type until the openapi is regenerated, so they
+ * are read off the raw payload and tolerated when absent.
+ */
+function readSupportFields(res) {
+    if (!res || typeof res !== "object")
+        return {};
+    const raw = res;
+    const sessionType = optionalString(raw.sessionType);
+    const ss = raw.supportSession;
+    if (!ss || typeof ss !== "object")
+        return { sessionType };
+    const s = ss;
+    return {
+        sessionType,
+        supportSession: {
+            authorityUuid: optionalString(s.authorityUuid),
+            name: optionalString(s.name),
+            email: optionalString(s.email),
+            orgUuid: optionalString(s.orgUuid),
+        },
+    };
+}
+function describeIdentity(identity) {
+    const who = [identity.name, identity.email].filter(Boolean).join(" ");
+    return `${who ? `${who} ` : ""}(${identity.userId ?? "no id"})`;
+}
 async function fetchSession(sessionId) {
     const cached = cache.get(sessionId);
     if (cached !== undefined)
@@ -22,11 +60,31 @@ async function fetchSession(sessionId) {
             return null;
         }
         const user = res.user;
-        const apps = (user?.accessibleRhombusApps ?? []).filter((a) => a !== null && a !== undefined);
+        const { sessionType, supportSession } = readSupportFields(res);
+        // A successful getCurrentUser with no `user` is a support-authority session
+        // (the webservice never populates `user` for a SupportUserPrincipal). Such a
+        // session acts inside the customer's console, so it gets exactly the
+        // CONSOLE tool set — never the permissive console+partner union that an
+        // empty accessibleRhombusApps list used to fall into.
+        if (sessionType === "SUPPORT" || user === null || user === undefined) {
+            const identity = {
+                userId: supportSession?.authorityUuid ?? SUPPORT_SESSION_MARKER,
+                orgUuid: supportSession?.orgUuid,
+                email: supportSession?.email,
+                name: supportSession?.name,
+                sessionType: "SUPPORT",
+            };
+            const entry = { apps: [RhombusAppEnum.CONSOLE], identity };
+            cache.set(sessionId, entry);
+            logger.info(`resolveAccessibleApps: session ${sessionId} -> support session ${describeIdentity(identity)}; tool set=CONSOLE`);
+            return entry;
+        }
+        const apps = (user.accessibleRhombusApps ?? []).filter((a) => a !== null && a !== undefined);
         const identity = {
-            userId: user?.uuid ?? user?.rhombusUserUuid ?? undefined,
-            orgUuid: user?.orgUuid ?? undefined,
-            email: user?.email ?? undefined,
+            userId: user.uuid ?? user.rhombusUserUuid ?? undefined,
+            orgUuid: user.orgUuid ?? undefined,
+            email: user.email ?? undefined,
+            sessionType: "USER",
         };
         const entry = { apps, identity };
         cache.set(sessionId, entry);
@@ -40,6 +98,7 @@ async function fetchSession(sessionId) {
 }
 /**
  * Fetches `user.accessibleRhombusApps` from getCurrentUser for the given session.
+ * Support-authority sessions resolve to exactly `[CONSOLE]`.
  * Returns null on error or missing session; callers should fall back to a
  * permissive default.
  */
@@ -49,8 +108,11 @@ export async function resolveAccessibleApps(sessionId) {
     return (await fetchSession(sessionId))?.apps ?? null;
 }
 /**
- * Fetches identity (user uuid, org uuid, email) from getCurrentUser for the
- * given session, reusing the same cached response as `resolveAccessibleApps`.
+ * Fetches identity (user uuid, org uuid, email, session type) from
+ * getCurrentUser for the given session, reusing the same cached response as
+ * `resolveAccessibleApps`. For support sessions the identity comes from
+ * `supportSession` (authorityUuid / name / email) when the webservice sends it,
+ * else `userId` is the fixed {@link SUPPORT_SESSION_MARKER}.
  * Returns null on error or missing session.
  */
 export async function resolveSessionIdentity(sessionId) {

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

@@ -1,9 +1,9 @@
 import { logger } from "../logger.js";
-import { postApi } from "../network/network.js";
+import { cachedPostApi } from "../network/org-reference-cache.js";
 import { formatTimestamp } from "../util.js";
 import { tempFunc } from "../utils/temp.js";
 export async function getCameraList(requestModifiers, sessionId) {
-    const body = await postApi({
+    const body = await cachedPostApi({
         route: "/camera/getMinimalCameraStateList",
         body: {},
         modifiers: requestModifiers,
@@ -14,7 +14,7 @@ export async function getCameraList(requestModifiers, sessionId) {
     };
 }
 export async function getDoorbellCameras(requestModifiers, sessionId) {
-    const body = await postApi({
+    const body = await cachedPostApi({
         route: "/doorbellcamera/getMinimalStateList",
         body: {},
         modifiers: requestModifiers,
@@ -25,7 +25,7 @@ export async function getDoorbellCameras(requestModifiers, sessionId) {
     };
 }
 export async function getBadgeReaders(requestModifiers, sessionId) {
-    return await postApi({
+    return await cachedPostApi({
         route: "/badgereader/getMinimalStateList",
         body: {},
         modifiers: requestModifiers,
@@ -37,7 +37,7 @@ export async function getBadgeReaders(requestModifiers, sessionId) {
     });
 }
 export async function getAccessControlledDoors(requestModifiers, sessionId) {
-    return await postApi({
+    return await cachedPostApi({
         route: "/component/findAccessControlledDoors",
         body: {},
         modifiers: requestModifiers,
@@ -60,7 +60,7 @@ export async function getAccessControlledDoors(requestModifiers, sessionId) {
     });
 }
 export async function getAudioGateways(timeZone, requestModifiers, sessionId) {
-    return await postApi({
+    return await cachedPostApi({
         route: "/audiogateway/getMinimalAudioGatewayStateList",
         body: {},
         modifiers: requestModifiers,
@@ -79,7 +79,7 @@ export async function getAudioGateways(timeZone, requestModifiers, sessionId) {
     });
 }
 export async function getDoorSensors(requestModifiers, sessionId) {
-    return await postApi({
+    return await cachedPostApi({
         route: "/door/getMinimalDoorStateList",
         body: {},
         modifiers: requestModifiers,
@@ -91,7 +91,7 @@ export async function getDoorSensors(requestModifiers, sessionId) {
     });
 }
 export async function getEnvironmentalSensors(timeZone, tempUnit, requestModifiers, sessionId) {
-    return await postApi({
+    return await cachedPostApi({
         route: "/climate/getMinimalClimateStateList",
         body: {},
         modifiers: requestModifiers,
@@ -115,7 +115,7 @@ export async function getEnvironmentalSensors(timeZone, tempUnit, requestModifie
     });
 }
 export async function getMotionSensors(requestModifiers, sessionId) {
-    return await postApi({
+    return await cachedPostApi({
         route: "/occupancy/getMinimalOccupancySensorStateList",
         body: {},
         modifiers: requestModifiers,
@@ -127,7 +127,7 @@ export async function getMotionSensors(requestModifiers, sessionId) {
     });
 }
 export async function getButtons(timeZone, requestModifiers, sessionId) {
-    return await postApi({
+    return await cachedPostApi({
         route: "/button/getMinimalButtonStateList",
         body: {},
         modifiers: requestModifiers,
@@ -146,7 +146,7 @@ export async function getButtons(timeZone, requestModifiers, sessionId) {
     });
 }
 export async function getKeypads(requestModifiers, sessionId) {
-    return await postApi({
+    return await cachedPostApi({
         route: "/keypad/getKeypadsForOrg",
         body: {},
         modifiers: requestModifiers,
@@ -158,7 +158,7 @@ export async function getKeypads(requestModifiers, sessionId) {
     });
 }
 export async function getEnvironmentalGateways(timeZone, requestModifiers, sessionId) {
-    return await postApi({
+    return await cachedPostApi({
         route: "/climate/getMinimalEnvironmentalGatewayStates",
         body: {},
         modifiers: requestModifiers,

package/dist/api/get-org-information-tool-api.js

@@ -1,6 +1,6 @@
-import { postApi } from "../network/network.js";
+import { cachedPostApi } from "../network/org-reference-cache.js";
 export async function getOrg(requestModifiers, sessionId) {
-    return await postApi({
+    return await cachedPostApi({
         route: "/org/getOrgV2",
         body: {},
         modifiers: requestModifiers,

package/dist/api/guest-management-tool-api.js

@@ -1,4 +1,4 @@
-import { postApi } from "../network/network.js";
+import { apiWarning, postApi, throwIfApiError } from "../network/network.js";
 export async function getAllGuestsByOrg(requestModifiers, sessionId) {
     const res = await postApi({
         route: "/guestmanagement/getAllGuestsByOrg",
@@ -73,3 +73,77 @@ export async function getActivitiesForLocation(locationUuid, startTimeMs, endTim
         timestampMs: a.timestampMs ?? undefined,
     })) ?? []);
 }
+// ---------------------------------------------------------------------------
+// Guest write paths
+// ---------------------------------------------------------------------------
+export async function createGuest(guest, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/guestmanagement/createGuest",
+        body: { guest },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return { success: true, email: guest.email, warningMsg: apiWarning(res) };
+}
+/** Guests are addressed by EMAIL, not a uuid — there is no delete-by-uuid. */
+export async function deleteGuest(email, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/guestmanagement/deleteGuest",
+        body: { email },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return { success: true, email, warningMsg: apiWarning(res) };
+}
+export async function getGuestPasses(range, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/accesscontrol/guestpass/findGuestPasses",
+        body: {
+            startAfterMs: range.startAfterMs,
+            startBeforeMs: range.startBeforeMs,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return {
+        guestPasses: res.guestPasses?.flatMap(pass => pass
+            ? [
+                {
+                    uuid: pass.uuid ?? undefined,
+                    locationUuid: pass.locationUuid ?? undefined,
+                    lifecycle: pass.lifecycle ?? undefined,
+                    note: pass.note ?? undefined,
+                    passStartTimeMs: pass.passStartTimeMs ?? undefined,
+                    principalType: pass.principalType ?? undefined,
+                },
+            ]
+            : []) ?? [],
+        lastEvaluatedKey: res.lastEvaluatedKey ?? undefined,
+    };
+}
+/**
+ * Guest pass state changes.
+ *
+ * They are not interchangeable: suspend is reversible via unsuspend, expire ends
+ * the pass but keeps its record and history, and delete removes the record
+ * outright.
+ */
+export async function changeGuestPassState(guestPassUuid, action, requestModifiers, sessionId) {
+    const routes = {
+        expire: "/accesscontrol/guestpass/expireGuestPass",
+        suspend: "/accesscontrol/guestpass/suspendGuestPass",
+        unsuspend: "/accesscontrol/guestpass/unsuspendGuestPass",
+        delete: "/accesscontrol/guestpass/deleteGuestPass",
+    };
+    const res = await postApi({
+        route: routes[action],
+        body: { guestPassUuid },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    return { success: true, uuid: guestPassUuid, action, warningMsg: apiWarning(res) };
+}

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

@@ -1,18 +1,43 @@
-import { postApi } from "../network/network.js";
+import { postApi, throwIfApiError } from "../network/network.js";
+import { cachedPostApi, clearOrgReferenceCache } from "../network/org-reference-cache.js";
+function mapLocation(raw) {
+    const addressParts = [raw.address1, raw.address2, raw.postalCode, raw.countryCode]
+        .map(part => part?.trim())
+        .filter((part) => !!part);
+    return {
+        uuid: raw.uuid ?? undefined,
+        name: raw.name ?? undefined,
+        address1: raw.address1 ?? undefined,
+        address2: raw.address2 ?? undefined,
+        postalCode: raw.postalCode ?? undefined,
+        countryCode: raw.countryCode ?? undefined,
+        // Pre-joined so callers never have to reassemble it (and so the model
+        // doesn't invent a format).
+        address: addressParts.length > 0 ? addressParts.join(", ") : undefined,
+        timezone: raw.tz ?? undefined,
+        labels: raw.labels?.filter((label) => !!label) ?? [],
+        latitude: raw.latitude ?? undefined,
+        longitude: raw.longitude ?? undefined,
+        policyUuid: raw.policyUuid ?? undefined,
+    };
+}
 export async function getLocations(requestModifiers, sessionId) {
-    const res = await postApi({
+    const res = await cachedPostApi({
         route: "/location/getLocationsV2",
         body: {},
         modifiers: requestModifiers,
         sessionId,
     });
+    throwIfApiError(res);
     return {
-        locations: (res.locations || []).map((loc) => ({
-            uuid: loc.uuid ?? undefined,
-            name: loc.name ?? undefined,
-        })),
+        locations: res.locations?.flatMap(raw => (raw ? [mapLocation(raw)] : [])) ?? [],
+        warningMsg: res.warningMsg ?? undefined,
     };
 }
+export async function findLocation(locationUuid, requestModifiers, sessionId) {
+    const { locations } = await getLocations(requestModifiers, sessionId);
+    return locations.find(location => location.uuid === locationUuid);
+}
 export async function createLocation(name, address, requestModifiers, sessionId) {
     const res = await postApi({
         route: "/location/createLocation",
@@ -20,37 +45,104 @@ export async function createLocation(name, address, requestModifiers, sessionId)
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error)
-        throw new Error(JSON.stringify(res));
-    return { uuid: res.locationUuid ?? res.uuid ?? undefined, success: true };
-}
-export async function updateLocation(locationUuid, name, address, requestModifiers, sessionId) {
-    const body = { locationUuid };
-    if (name)
-        body.name = name;
-    if (address)
-        body.address = address;
+    throwIfApiError(res);
+    // The org-wide location list is cached for up to 60s; without this, a read
+    // straight after the write still reports the old list.
+    clearOrgReferenceCache();
+    return {
+        uuid: res.locationUuid ?? res.uuid ?? undefined,
+        success: true,
+        warningMsg: res.warningMsg ?? undefined,
+    };
+}
+/**
+ * `selectiveUpdateLocation` leaves out-of-body fields alone, unlike
+ * `updateLocation` which replaces the record — so a rename can't blank the
+ * address, and setting a timezone can't blank the labels.
+ */
+export async function updateLocation(update, requestModifiers, sessionId) {
     const res = await postApi({
-        route: "/location/updateLocation",
-        body,
+        route: "/location/selectiveUpdateLocation",
+        body: update,
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error)
-        throw new Error(JSON.stringify(res));
-    return { success: true };
+    throwIfApiError(res);
+    clearOrgReferenceCache();
+    return {
+        updated: { success: true, locationUuid: update.locationUuid },
+        warningMsg: res.warningMsg ?? undefined,
+    };
 }
-export async function getLocationLabels(requestModifiers, sessionId) {
+export async function deleteLocation(locationUuid, requestModifiers, sessionId) {
     const res = await postApi({
+        route: "/location/deleteLocation",
+        body: { uuid: locationUuid },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    clearOrgReferenceCache();
+    return {
+        deleted: { success: true, locationUuid },
+        warningMsg: res.warningMsg ?? undefined,
+    };
+}
+export async function getLocationLabels(requestModifiers, sessionId) {
+    const res = await cachedPostApi({
         route: "/location/getLocationLabelsForOrg",
         body: {},
         modifiers: requestModifiers,
         sessionId,
     });
-    if (res.error)
-        throw new Error(JSON.stringify(res));
-    return (res.locationLabels || []).map((label) => ({
-        uuid: label.uuid ?? undefined,
-        name: label.name ?? undefined,
-    }));
+    throwIfApiError(res);
+    // api2 returns location labels as bare strings on some orgs and objects on
+    // others; normalise both to {name}.
+    const raw = res.locationLabels ?? [];
+    const labels = [];
+    for (const label of raw) {
+        if (typeof label === "string") {
+            if (label.trim())
+                labels.push({ name: label.trim() });
+        }
+        else if (label && typeof label === "object") {
+            const record = label;
+            labels.push({ uuid: record.uuid ?? undefined, name: record.name ?? undefined });
+        }
+    }
+    return labels;
+}
+export async function addLocationLabel(locationUuid, label, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/location/addLocationLabel",
+        body: {
+            locationIdentifier: locationUuid,
+            label,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    clearOrgReferenceCache();
+    return {
+        labelChanged: { success: true, locationUuid, label },
+        warningMsg: res.warningMsg ?? undefined,
+    };
+}
+export async function removeLocationLabel(locationUuid, label, requestModifiers, sessionId) {
+    const res = await postApi({
+        route: "/location/removeLocationLabel",
+        body: {
+            locationIdentifier: locationUuid,
+            label,
+        },
+        modifiers: requestModifiers,
+        sessionId,
+    });
+    throwIfApiError(res);
+    clearOrgReferenceCache();
+    return {
+        labelChanged: { success: true, locationUuid, label },
+        warningMsg: res.warningMsg ?? undefined,
+    };
 }