@7365admin1/core 3.82.0 → 3.84.0

package/dist/index.mjs

@@ -58577,6 +58577,7 @@ var robotSchema = Joi74.object({
   // Optional, so every caller written before this field existed still validates.
   type: Joi74.string().valid(...ROBOT_TYPES).optional().allow("", null),
   robotSn: Joi74.string().optional().allow("", null),
+  brand: Joi74.string().optional().allow("", null),
   appKey: Joi74.string().required(),
   appToken: Joi74.string().required(),
   createdBy: Joi74.string().hex().required(),
@@ -58638,6 +58639,7 @@ function MRobot(value) {
      */
     type: value.type || "cleaning",
     robotSn: value.robotSn ?? "",
+    brand: value.brand || "ounitech",
     appKey: value.appKey ?? "",
     appToken: value.appToken ?? "",
     createdBy: value.createdBy ?? "",
@@ -58801,6 +58803,9 @@ function useRobotRepo() {
             // Not a secret - it is the vendor's device serial, and the apps
             // need it to address a robot. The CREDENTIALS stay out.
             robotSn: 1,
+            // Not a secret - it names which protocol the robot speaks, and a
+            // screen needs it to know which controls to draw.
+            brand: 1,
             createdByName: 1,
             createdAt: 1,
             status: 1
@@ -59194,30 +59199,30 @@ function parseRobotCommand(body) {
   if (kind !== "full" && kind !== "area" && kind !== "spot" && kind !== "return") {
     return { ok: false, message: 'kind must be one of "full", "area", "spot", "return".' };
   }
-  const has = (k) => Object.prototype.hasOwnProperty.call(b, k);
+  const has2 = (k) => Object.prototype.hasOwnProperty.call(b, k);
   const optionKeys = ["cleanTimes", "modeFlag", "subModeFlag", "levelFlag"];
   if (kind === "return") {
     for (const k of [...optionKeys, "areas", "points"]) {
-      if (has(k))
+      if (has2(k))
         return { ok: false, message: `${k} is not valid for a return command.` };
     }
     return { ok: true, command: { kind: "return" } };
   }
-  if (kind !== "area" && has("areas")) {
+  if (kind !== "area" && has2("areas")) {
     return { ok: false, message: "areas is only valid for an area command." };
   }
-  if (kind !== "spot" && has("points")) {
+  if (kind !== "spot" && has2("points")) {
     return { ok: false, message: "points is only valid for a spot command." };
   }
   const int = (k, allowed, fallback) => {
-    if (!has(k))
+    if (!has2(k))
       return fallback;
     const v = b[k];
     if (typeof v !== "number" || !Number.isInteger(v) || !allowed.includes(v))
       return null;
     return v;
   };
-  const cleanTimes = has("cleanTimes") ? typeof b.cleanTimes === "number" && Number.isInteger(b.cleanTimes) && b.cleanTimes >= 0 && b.cleanTimes <= 99 ? b.cleanTimes : null : DEFAULTS.cleanTimes;
+  const cleanTimes = has2("cleanTimes") ? typeof b.cleanTimes === "number" && Number.isInteger(b.cleanTimes) && b.cleanTimes >= 0 && b.cleanTimes <= 99 ? b.cleanTimes : null : DEFAULTS.cleanTimes;
   if (cleanTimes === null)
     return { ok: false, message: "cleanTimes must be an integer 0-99." };
   const modeFlag = int("modeFlag", [1, 2, 3], DEFAULTS.modeFlag);
@@ -59433,6 +59438,125 @@ function robotActionsFor(actor) {
   );
 }
 
+// src/utils/robot-adapter.util.ts
+var ROBOT_CAPABILITIES = [
+  /** Read the current location of the robot [x, y, yaw]. */
+  "readLocation",
+  /** Request the robot move to an [x, y, yaw] coordinate. */
+  "navigateToPoint",
+  /** Pause a robot while it is navigating, and resume it. */
+  "pauseResume",
+  /** Read the route/path taken, or the ETA to the destination. */
+  "pathAndEta",
+  /** Read the battery level. */
+  "battery",
+  /** Send the robot to its docking/charging station. */
+  "sendToDock",
+  /** Switch the on-board map and re-localise the robot. */
+  "relocalize",
+  /** Start a process — "clean zone A". */
+  "startProcess",
+  /** Pause, resume or stop a running process. */
+  "pauseProcess",
+  /** Know, rather than infer, when a process has finished. */
+  "processCompletion",
+  /** Report which floor the robot is on. */
+  "floorReporting",
+  /** Ride a lift between floors under our coordination. */
+  "multiFloor"
+];
+var TIER_REQUIREMENTS = {
+  "full-control": [
+    "readLocation",
+    "navigateToPoint",
+    "pauseResume",
+    "pathAndEta",
+    "battery",
+    "sendToDock",
+    "relocalize",
+    "startProcess",
+    "pauseProcess",
+    "processCompletion"
+  ],
+  "traffic-light": [
+    "readLocation",
+    "pauseResume",
+    "battery",
+    "sendToDock",
+    "startProcess",
+    "pauseProcess",
+    "processCompletion"
+  ],
+  "read-only": ["readLocation", "pathAndEta", "battery", "processCompletion"]
+};
+var has = (caps, c) => Object.prototype.hasOwnProperty.call(caps, c) && caps[c] === true;
+function robotTier(capabilities) {
+  const caps = capabilities ?? {};
+  for (const tier of ["full-control", "traffic-light", "read-only"]) {
+    if (TIER_REQUIREMENTS[tier].every((c) => has(caps, c)))
+      return tier;
+  }
+  return "no-interface";
+}
+function missingForTier(capabilities, tier) {
+  const caps = capabilities ?? {};
+  return TIER_REQUIREMENTS[tier].filter((c) => !has(caps, c));
+}
+function supports(capabilities, capability) {
+  return has(capabilities ?? {}, capability);
+}
+function uncontrollableFleetWarning(tiers) {
+  const count = tiers.filter(
+    (t) => t === "read-only" || t === "no-interface"
+  ).length;
+  if (count <= 1) {
+    return { ok: true, count, message: "" };
+  }
+  return {
+    ok: false,
+    count,
+    message: `This site has ${count} robot fleets that cannot be controlled (read-only or no interface). A shared space supports at most one: beyond that, robots cannot reliably be kept out of each other's way.`
+  };
+}
+var COMMAND_NEEDS = {
+  full: "startProcess",
+  area: "startProcess",
+  spot: "startProcess",
+  return: "sendToDock",
+  pause: "pauseProcess",
+  resume: "pauseProcess",
+  cancel: "pauseProcess",
+  navigate: "navigateToPoint",
+  relocalize: "relocalize"
+};
+function commandSupported(capabilities, kind) {
+  const needed = Object.prototype.hasOwnProperty.call(COMMAND_NEEDS, kind) ? COMMAND_NEEDS[kind] : void 0;
+  if (!needed)
+    return false;
+  return supports(capabilities, needed);
+}
+var adapters = /* @__PURE__ */ new Map();
+function registerRobotAdapter(adapter) {
+  if (!adapter?.brand)
+    throw new Error("A robot adapter must name its brand.");
+  adapters.set(adapter.brand, adapter);
+}
+function robotAdapterFor(brand) {
+  if (typeof brand !== "string" || !brand)
+    return null;
+  return adapters.get(brand) ?? null;
+}
+function registeredRobotBrands() {
+  return [...adapters.values()].map((a) => ({
+    brand: a.brand,
+    displayName: a.displayName,
+    tier: robotTier(a.capabilities)
+  }));
+}
+function clearRobotAdapters() {
+  adapters.clear();
+}
+
 // src/utils/lift-contract.util.ts
 var LIFT_DOOR = {
   CLOSED: 0,
@@ -59572,6 +59696,179 @@ function createLiftSimulator(options) {
   };
 }
 
+// src/utils/building-map.util.ts
+var WALL_HEIGHT_M = 2.5;
+var WALL_THICKNESS_M = 0.1;
+var DEFAULT_SCALE_M_PER_PX = 0.05;
+function scaleFromMeasurement(pixelDistance, realDistanceM) {
+  if (!Number.isFinite(pixelDistance) || pixelDistance <= 0) {
+    throw new Error("A measurement needs a positive pixel distance.");
+  }
+  if (!Number.isFinite(realDistanceM) || realDistanceM <= 0) {
+    throw new Error("A measurement needs a positive real distance in metres.");
+  }
+  return realDistanceM / pixelDistance;
+}
+function vertexDistancePx(a, b) {
+  return Math.hypot(b.x - a.x, b.y - a.y);
+}
+function levelScale(level) {
+  const measurement = level.measurements?.find((m) => {
+    const a = level.vertices[m.start];
+    const b = level.vertices[m.end];
+    return a && b && m.distanceM > 0 && vertexDistancePx(a, b) > 0;
+  });
+  if (measurement) {
+    return scaleFromMeasurement(
+      vertexDistancePx(level.vertices[measurement.start], level.vertices[measurement.end]),
+      measurement.distanceM
+    );
+  }
+  return level.scaleMPerPx > 0 ? level.scaleMPerPx : DEFAULT_SCALE_M_PER_PX;
+}
+function levelPixelToMetres(level, px, py, imageHeightPx) {
+  const scale = levelScale(level);
+  return {
+    x: level.originXM + px * scale,
+    y: level.originYM + (imageHeightPx - py) * scale
+  };
+}
+function levelSolids(level, imageHeightPx) {
+  const toM = (v) => levelPixelToMetres(level, v.x, v.y, imageHeightPx);
+  const walls = [];
+  for (const wall of level.walls ?? []) {
+    const a = level.vertices[wall.start];
+    const b = level.vertices[wall.end];
+    if (!a || !b)
+      continue;
+    const pa = toM(a);
+    const pb = toM(b);
+    const lengthM = Math.hypot(pb.x - pa.x, pb.y - pa.y);
+    if (lengthM <= 0)
+      continue;
+    const heightM = wall.heightM ?? WALL_HEIGHT_M;
+    walls.push({
+      centre: {
+        x: (pa.x + pb.x) / 2,
+        y: (pa.y + pb.y) / 2,
+        // Boxes are centred, so a wall standing ON the floor sits at half its
+        // own height above the level's elevation.
+        z: level.elevationM + heightM / 2
+      },
+      lengthM,
+      thicknessM: wall.thicknessM ?? WALL_THICKNESS_M,
+      heightM,
+      yaw: Math.atan2(pb.y - pa.y, pb.x - pa.x)
+    });
+  }
+  const floors = [];
+  for (const floor of level.floors ?? []) {
+    const points = (floor.vertices ?? []).map((i) => level.vertices[i]).filter(Boolean).map(toM);
+    if (points.length < 3)
+      continue;
+    floors.push({ points, elevationM: level.elevationM, hole: floor.hole === true });
+  }
+  return { level: level.name, elevationM: level.elevationM, walls, floors };
+}
+function buildingSolids(map, imageHeightFor) {
+  return (map.levels ?? []).map((level) => levelSolids(level, imageHeightFor(level)));
+}
+function wallsFromOccupancyGrid(grid, options) {
+  const threshold = options?.threshold ?? 100;
+  const minRun = Math.max(2, options?.minRunPx ?? 6);
+  const { data, width, height } = grid;
+  if (!width || !height || !data || data.length < width * height) {
+    return { vertices: [], walls: [] };
+  }
+  const occupied = (x, y) => Number(data[y * width + x]) <= threshold;
+  const consumed = new Uint8Array(width * height);
+  const vertices = [];
+  const walls = [];
+  const index = /* @__PURE__ */ new Map();
+  const vertexAt = (x, y) => {
+    const key = `${x}:${y}`;
+    const found = index.get(key);
+    if (found !== void 0)
+      return found;
+    vertices.push({ x, y, z: 0 });
+    index.set(key, vertices.length - 1);
+    return vertices.length - 1;
+  };
+  const addRun = (x1, y1, x2, y2) => {
+    walls.push({ start: vertexAt(x1, y1), end: vertexAt(x2, y2) });
+  };
+  for (let y = 0; y < height; y++) {
+    let run = 0;
+    for (let x = 0; x <= width; x++) {
+      const on = x < width && occupied(x, y);
+      if (on) {
+        run++;
+        continue;
+      }
+      if (run >= minRun) {
+        const startX = x - run;
+        addRun(startX, y, x - 1, y);
+        for (let i = startX; i < x; i++)
+          consumed[y * width + i] = 1;
+      }
+      run = 0;
+    }
+  }
+  for (let x = 0; x < width; x++) {
+    let run = 0;
+    for (let y = 0; y <= height; y++) {
+      const on = y < height && occupied(x, y) && !consumed[y * width + x];
+      if (on) {
+        run++;
+        continue;
+      }
+      if (run >= minRun) {
+        addRun(x, y - run, x, y - 1);
+      }
+      run = 0;
+    }
+  }
+  return { vertices, walls };
+}
+function buildingMapFromRobotMaps(name, maps, floorHeightM = 3) {
+  const levels = [...maps ?? []].sort((a, b) => a.floorNo - b.floorNo).map((map) => {
+    const vertices = [];
+    if (map.baseX || map.baseY) {
+      vertices.push({
+        x: map.baseX ?? 0,
+        y: map.baseY ?? 0,
+        z: 0,
+        name: `L${map.floorNo}_charger`,
+        isCharger: true,
+        theta: map.baseTheta ?? 0
+      });
+    }
+    for (const area of map.areaList ?? []) {
+      vertices.push({
+        x: area.x,
+        y: area.y,
+        z: 0,
+        name: area.areaName,
+        isCleaningZone: true
+      });
+    }
+    return {
+      name: map.mapName?.trim() || `L${map.floorNo}`,
+      elevationM: (map.floorNo - 1) * floorHeightM,
+      drawing: { fileKey: map.backgroundFileKey },
+      scaleMPerPx: map.resolution && map.resolution > 0 ? map.resolution : DEFAULT_SCALE_M_PER_PX,
+      originXM: map.originX ?? 0,
+      originYM: map.originY ?? 0,
+      vertices,
+      walls: [],
+      floors: [],
+      doors: [],
+      measurements: []
+    };
+  });
+  return { name, levels, lifts: [] };
+}
+
 // src/services/robot-fleet.service.ts
 import { BadRequestError as BadRequestError134, NotFoundError as NotFoundError43 } from "@7365admin1/node-server-utils";
 
@@ -59829,6 +60126,129 @@ function useRobotFleetService(deps) {
   };
 }
 
+// src/services/ounitech.adapter.ts
+var OUNITECH_BRAND = "ounitech";
+var OUNITECH_CAPABILITIES = {
+  // The tracking stream carries x, y, theta.
+  readLocation: true,
+  // `/portal/robots/return-to-base`.
+  sendToDock: true,
+  // `start-full-cleaning`, `start-area-cleaning`, `start-spot-cleaning` — RMF's
+  // "start a process (such as clean Zone_A)", and their areas are RMF's zones.
+  startProcess: true,
+  // Everything below is FALSE on purpose, and each one is a question already put
+  // to the vendor. Their app can do most of it; the API cannot.
+  navigateToPoint: false,
+  // app: "Move to Target Point in standby mode"
+  relocalize: false,
+  // app: "Set Origin"
+  pauseResume: false,
+  // handlebar + app: Pause/Resume, long-press cancel
+  pauseProcess: false,
+  // app: "End work"
+  battery: false,
+  // nothing in the API carries it
+  pathAndEta: false,
+  // nothing in the API carries it
+  processCompletion: false,
+  // no task id is returned, so completion is inferred
+  floorReporting: false,
+  // the tracking stream has no floorNo
+  multiFloor: false
+  // their app does cross-floor; the API does not expose it
+};
+function createOunitechAdapter(credentials, options) {
+  const cloud = useRobotCloudService(credentials, options);
+  function toAdapterRobot(raw) {
+    return {
+      robotSn: raw.robotSn,
+      name: raw.robotName,
+      online: raw.onlineFlag !== false,
+      mode: robotModeFromList(raw),
+      statusName: raw.statusName,
+      // Null, not 0 or a guess. A screen must be able to tell "we do not know"
+      // from "empty", and `floorKnown: false` is what stops a robot being drawn
+      // on a storey nobody confirmed.
+      batteryPercent: null,
+      floorNo: null,
+      floorKnown: false,
+      position: null
+    };
+  }
+  return {
+    brand: OUNITECH_BRAND,
+    displayName: "Ounitech (Q3-G / Q3-W)",
+    capabilities: OUNITECH_CAPABILITIES,
+    async listRobots() {
+      const fleet = await cloud.getRobots();
+      return fleet.map(toAdapterRobot);
+    },
+    async getRobot(robotSn) {
+      const fleet = await cloud.getRobots();
+      const match = fleet.find((r) => r.robotSn === robotSn);
+      if (!match) {
+        return {
+          robotSn,
+          online: false,
+          mode: "UNAVAILABLE",
+          statusName: "Not found in the robot cloud",
+          batteryPercent: null,
+          floorNo: null,
+          floorKnown: false,
+          position: null
+        };
+      }
+      return toAdapterRobot(match);
+    },
+    async sendCommand(robotSn, command) {
+      const options2 = {
+        cleanTimes: 1,
+        modeFlag: 1,
+        subModeFlag: 0,
+        levelFlag: 1
+      };
+      switch (command.kind) {
+        case "full":
+          await cloud.startFullCleaning(robotSn, options2);
+          return;
+        case "area":
+          await cloud.startAreaCleaning(robotSn, command.areas, options2);
+          return;
+        case "spot":
+          await cloud.startSpotCleaning(robotSn, command.points, options2);
+          return;
+        case "return":
+          await cloud.returnToBase(robotSn);
+          return;
+        default:
+          throw new Error(
+            `Ounitech robots do not support "${command.kind}" through the API yet.`
+          );
+      }
+    },
+    async getMaps(robotSn) {
+      return cloud.getMaps(robotSn);
+    },
+    async getPlans(robotSn) {
+      return cloud.getPlans(robotSn);
+    }
+  };
+}
+function registerOunitechBrand() {
+  const unconfigured = () => {
+    throw new Error(
+      "No Ounitech credentials for this robot. Add the app key and token on the robot's record."
+    );
+  };
+  registerRobotAdapter({
+    brand: OUNITECH_BRAND,
+    displayName: "Ounitech (Q3-G / Q3-W)",
+    capabilities: OUNITECH_CAPABILITIES,
+    listRobots: async () => unconfigured(),
+    getRobot: async () => unconfigured()
+  });
+}
+
 // src/controllers/robot-fleet.controller.ts
 import Joi76 from "joi";
 import { BadRequestError as BadRequestError135, logger as logger106 } from "@7365admin1/node-server-utils";
@@ -93743,6 +94163,7 @@ export {
   ConsoleAuditAction,
   ConsoleAuditTarget,
   DEFAULT_RING_SECONDS,
+  DEFAULT_SCALE_M_PER_PX,
   DEFAULT_SITE_TIMEZONE,
   DEVICE_STATUS,
   DOBStatus,
@@ -93881,6 +94302,8 @@ export {
   ORG_OWNER_REPAIR_CLAIM_TAKEN_REASON,
   ORG_OWNER_REPAIR_DEFAULT,
   ORG_OWNER_REPAIR_OFF_REASON,
+  OUNITECH_BRAND,
+  OUNITECH_CAPABILITIES,
   OrgNature,
   OvernightParkingRequestSort,
   OvernightParkingRequestStatus,
@@ -93908,6 +94331,7 @@ export {
   REALTIME_MAX_FANOUT,
   REGISTERED_VEHICLE_CATEGORIES,
   ROBOT_APP_SCOPES,
+  ROBOT_CAPABILITIES,
   ROBOT_CLOUD_DOC_CONFIRMATIONS,
   ROBOT_CLOUD_PATHS,
   ROBOT_MODULE,
@@ -93959,6 +94383,8 @@ export {
   VerificationType,
   VisitorSort,
   VisitorStatus,
+  WALL_HEIGHT_M,
+  WALL_THICKNESS_M,
   addressSchema,
   allowedFieldsSite,
   allowedNatures,
@@ -93970,6 +94396,8 @@ export {
   attendanceSchema,
   attendanceSettingsSchema,
   buildSelfServiceEmailContext,
+  buildingMapFromRobotMaps,
+  buildingSolids,
   building_level_namespace_collection,
   building_units_namespace_collection,
   buildings_namespace_collection,
@@ -93996,13 +94424,16 @@ export {
   chatSchema,
   claimReadsAsStale,
   clampPtzSpeed,
+  clearRobotAdapters,
   clockDriftSeconds,
+  commandSupported,
   consoleRoleAllows,
   consoleRoleAllowsAll,
   consoleSpellings,
   console_audit_namespace_collection,
   createLiftSimulator,
   createManpowerRemarksDaily,
+  createOunitechAdapter,
   createSseParser,
   customerSchema,
   customerSitePropertyFields,
@@ -94073,6 +94504,9 @@ export {
   isTermsCurrent,
   isTrackingStale,
   isValidTimezone,
+  levelPixelToMetres,
+  levelScale,
+  levelSolids,
   listStaffUserIds,
   liveStatusFor,
   manpowerDesignationsSchema,
@@ -94084,6 +94518,7 @@ export {
   maskNric,
   memberModulesHandlers,
   metresToPixel,
+  missingForTier,
   moduleDeniedForCaller,
   moduleGateEnforceKeys,
   moduleGateMode,
@@ -94138,6 +94573,9 @@ export {
   recordConsoleAction,
   refuseServiceProviderInviteAction,
   registerCameraTransport,
+  registerOunitechBrand,
+  registerRobotAdapter,
+  registeredRobotBrands,
   relayForRecorder,
   remarksSchema,
   renderPagePdf,
@@ -94155,6 +94593,7 @@ export {
   resolveSiteTimezone,
   resolveStaffRole,
   robotActionsFor,
+  robotAdapterFor,
   robotCloudBody,
   robotCloudSign,
   robotCloudSigningString,
@@ -94163,8 +94602,10 @@ export {
   robotModeFromList,
   robotSchema,
   robotScopeForApp,
+  robotTier,
   robotTypesVisibleTo,
   rtspUrl,
+  scaleFromMeasurement,
   schema,
   schemaAppSlugNotification,
   schemaApprovedBy,
@@ -94336,7 +94777,9 @@ export {
   stripFacialImageMetadata,
   subscriptionPlanSchema,
   summariseBulkCameraPlan,
+  supports,
   trackingBackoffMs,
+  uncontrollableFleetWarning,
   updateRemarksStatusEod,
   updateRemarksisAcknowledged,
   updateSiteSchema,
@@ -94580,8 +95023,10 @@ export {
   vehicleSchema,
   vehicleViewOf,
   vehicles_namespace_collection,
+  vertexDistancePx,
   visitors_namespace_collection,
   wallConfig,
+  wallsFromOccupancyGrid,
   withLiveLink,
   workOrderSchema,
   work_orders2_namespace_collection,