@7365admin1/core 3.80.0 → 3.81.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@7365admin1/core",
   "license": "MIT",
-  "version": "3.80.0",
+  "version": "3.81.0",
   "author": "7365admin1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -13,7 +13,7 @@
     "build": "tsup src/index.ts --format cjs,esm --dts && shx cp -r src/public dist && shx cp -r src/utils/handlebars dist",
     "release": "yarn run build && changeset publish",
     "lint": "tsc",
-    "test": "tsup src/config.ts src/utils/anpr-revoke.util.ts src/utils/anpr-plate.util.ts src/utils/vehicle-request.util.ts src/utils/camera-view.util.ts src/utils/camera-bulk-import.util.ts src/utils/dashboard-metrics.util.ts src/utils/camera-capability.util.ts src/utils/camera-playback.util.ts src/services/camera-device-http.service.ts src/utils/camera-alert.util.ts src/utils/dahua-protocol.util.ts src/utils/site-name.util.ts src/utils/service-provider-invite.util.ts src/utils/notification-category.util.ts src/utils/hid-card.util.ts src/utils/hid-json.util.ts src/utils/hid-access.util.ts src/models/customer-site.model.ts src/models/site-camera.model.ts src/models/member.model.ts src/models/subscription.model.ts src/utils/session-id.util.ts src/utils/occurrence-query.util.ts src/utils/occurrence-book-create.util.ts src/utils/update-result.util.ts src/utils/hid-amico-authz.util.ts src/utils/promo-code-currency.util.ts src/utils/console-audit.util.ts src/utils/org-suspension.util.ts src/utils/session-revoke.util.ts src/models/hid-amico.model.ts src/models/patrol-email.model.ts src/utils/patrol-email-pdf.util.ts src/utils/visitor-status.util.ts src/utils/self-service-email.util.ts src/utils/hid-secret.util.ts src/models/visitor-invite.model.ts src/models/guard-invite.model.ts src/utils/site-timezone.util.ts src/utils/bulletin-service-apps.util.ts src/models/bulletin-board.model.ts src/utils/vehicle-import.util.ts src/utils/expired-vehicle-sweep.util.ts src/models/vehicle.model.ts src/controllers/chat.controller.ts src/utils/file-owner.util.ts src/utils/console-permission.util.ts src/utils/role-scope.util.ts src/utils/org-default-roles.util.ts src/utils/org-modules.util.ts src/utils/site-modules.util.ts src/utils/resident-app-modules.util.ts src/utils/resident-default-role.util.ts src/utils/invite-role-scope.util.ts src/models/personal-emergency-chain.model.ts src/utils/self-signup-files.util.ts src/models/person.model.ts src/utils/module-gate.util.ts src/utils/member-lookup.util.ts src/utils/notification-access.util.ts src/utils/module-access.util.ts src/services/module-gate.service.ts src/controllers/site.controller.ts src/controllers/organization.controller.ts src/controllers/member.controller.ts src/utils/org-owner-repair.util.ts src/utils/socket-session.util.ts src/utils/people-create-gate.util.ts src/utils/service-app-type.util.ts --format esm --out-dir test/.build --no-dts --silent && node --test test/*.test.mjs",
+    "test": "tsup src/config.ts src/utils/robot-cloud.util.ts src/utils/robot-tracking.util.ts src/utils/robot-apps.util.ts src/utils/robot-permission.util.ts src/utils/anpr-revoke.util.ts src/utils/anpr-plate.util.ts src/utils/vehicle-request.util.ts src/utils/camera-view.util.ts src/utils/camera-bulk-import.util.ts src/utils/dashboard-metrics.util.ts src/utils/camera-capability.util.ts src/utils/camera-playback.util.ts src/services/camera-device-http.service.ts src/utils/camera-alert.util.ts src/utils/dahua-protocol.util.ts src/utils/site-name.util.ts src/utils/service-provider-invite.util.ts src/utils/notification-category.util.ts src/utils/hid-card.util.ts src/utils/hid-json.util.ts src/utils/hid-access.util.ts src/models/customer-site.model.ts src/models/site-camera.model.ts src/models/member.model.ts src/models/subscription.model.ts src/utils/session-id.util.ts src/utils/occurrence-query.util.ts src/utils/occurrence-book-create.util.ts src/utils/update-result.util.ts src/utils/hid-amico-authz.util.ts src/utils/promo-code-currency.util.ts src/utils/console-audit.util.ts src/utils/org-suspension.util.ts src/utils/session-revoke.util.ts src/models/hid-amico.model.ts src/models/patrol-email.model.ts src/utils/patrol-email-pdf.util.ts src/utils/visitor-status.util.ts src/utils/self-service-email.util.ts src/utils/hid-secret.util.ts src/models/visitor-invite.model.ts src/models/guard-invite.model.ts src/utils/site-timezone.util.ts src/utils/bulletin-service-apps.util.ts src/models/bulletin-board.model.ts src/utils/vehicle-import.util.ts src/utils/expired-vehicle-sweep.util.ts src/models/vehicle.model.ts src/controllers/chat.controller.ts src/utils/file-owner.util.ts src/utils/console-permission.util.ts src/utils/role-scope.util.ts src/utils/org-default-roles.util.ts src/utils/org-modules.util.ts src/utils/site-modules.util.ts src/utils/resident-app-modules.util.ts src/utils/resident-default-role.util.ts src/utils/invite-role-scope.util.ts src/models/personal-emergency-chain.model.ts src/utils/self-signup-files.util.ts src/models/person.model.ts src/utils/module-gate.util.ts src/utils/member-lookup.util.ts src/utils/notification-access.util.ts src/utils/module-access.util.ts src/services/module-gate.service.ts src/controllers/site.controller.ts src/controllers/organization.controller.ts src/controllers/member.controller.ts src/utils/org-owner-repair.util.ts src/utils/socket-session.util.ts src/utils/people-create-gate.util.ts src/utils/service-app-type.util.ts --format esm --out-dir test/.build --no-dts --silent && node --test test/*.test.mjs",
     "test:camera": "yarn test",
     "test:e2e": "yarn build && node --test --test-concurrency=1 --test-timeout=600000 \"test/e2e/*.test.mjs\""
   },

package/test/e2e/robot-scope.e2e.test.mjs

@@ -12,8 +12,9 @@
 // 1. THE LIST HANDS OUT CREDENTIALS. `robot.repo.ts` projects `appKey` and
 //    `appToken` into the response. Any signed-in account on the platform could
 //    name any organisation and site in the URL and read that estate's robot
-//    credentials. Case 0 shows the fields really are in the payload; cases 1, 2
-//    and 5 show they are now out of reach.
+//    credentials. Cases 1, 2 and 5 show the estate is now out of reach, and case
+//    0 shows the credentials are no longer in the payload AT ALL - not even for a
+//    caller standing at the robot's own estate.
 //
 // 2. THE WRITE COULD BE AIMED ANYWHERE. `metadata.siteId` came off the body, so a
 //    robot could be aimed at another client's estate (case 3), and it is
@@ -24,18 +25,17 @@
 //    the service looked the display name up from it. It now comes from the
 //    session.
 //
-// A STRAIGHT WORD ABOUT THE WRITE PATH, because the cases below are shaped by it:
-// `POST /api/robots` does not work today and did not before this change. The
-// service overwrites `value.createdBy` with `createdBy._id`, an `ObjectId`, and
-// `MRobot` then re-validates against `robotSchema`, where `createdBy` is
-// `Joi.string()`. Every create therefore ends in
-// `400 "createdBy" must be a string` and nothing is ever stored. That is a
-// pre-existing defect, reported on the PR and deliberately NOT fixed here.
+// A STRAIGHT WORD ABOUT THE WRITE PATH: `POST /api/robots` never worked. The
+// service overwrote `value.createdBy` with `createdBy._id`, an `ObjectId`, and
+// `MRobot` then re-validated against `robotSchema`, where `createdBy` is
+// `Joi.string()`. Every create ended in `400 "createdBy" must be a string` and
+// no robot was ever stored, by anybody, through either app. It is fixed here,
+// because the cleaning robot integration cannot begin without the ability to
+// register a robot.
 //
-// So for the write the guard is proved by WHICH refusal a caller gets: an
-// unauthorised caller is stopped by the guard (404, before the service), an
-// authorised one gets through the guard and falls over at the model (400). Cases
-// 3 and 6 are that pair. The spec does not pretend a robot is ever stored.
+// So the write is now proved BOTH ways: an unauthorised caller is stopped by the
+// guard (404, before the service), and an authorised one is stored (201). Cases
+// 3 and 6 are that pair.
 //
 // The fix is `requireSiteReach`, the rule `/api/attendances`, `/api/site-cameras`
 // and `/api/documents` already use, so the contracted agency still reaches its
@@ -66,6 +66,10 @@ const COLL = "robots";
 
 // What an authorised create fails with today: the pre-existing model defect,
 // reached only AFTER the guard has let the caller through.
+// The refusal every create used to end in, kept so case 3 can assert the guard
+// stopped the request BEFORE the model rather than at it. Creates now succeed:
+// the service handed `MRobot` an ObjectId where the schema wanted a string, so
+// no robot could ever be registered through either app.
 const MODEL_REFUSAL = '"createdBy" must be a string';
 
 describe("robots and their credentials are scoped to their estate", { concurrency: 1 }, () => {
@@ -127,20 +131,30 @@ describe("robots and their credentials are scoped to their estate", { concurrenc
     assert.equal(list.status, 200);
     assert.equal(list.body?.items?.length, 1);
 
-    // This is what the leak was worth: the projection really does carry the
-    // robot's credentials. The fields are checked for PRESENCE only.
+    // The projection no longer carries the robot's credentials AT ALL - not even
+    // to a caller standing at the robot's own estate. The tenancy guard decided
+    // WHO could read them; this decides that nobody reads them over HTTP. The
+    // connector reads them server-side.
     const row = list.body.items[0];
-    assert.equal("appKey" in row, true);
-    assert.equal("appToken" in row, true);
-
-    // And the write route answers: past the guard, into the model.
+    assert.equal("appKey" in row, false);
+    assert.equal("appToken" in row, false);
+    // and the row is still a usable listing.
+    assert.equal(typeof row.name, "string");
+
+    // And the write route answers - and now SUCCEEDS. It never did before: the
+    // service handed `MRobot` an ObjectId where the schema wanted a string, so
+    // every create ended in `400 "createdBy" must be a string`.
     const create = await h.api("/robots", {
       method: "POST",
       sid: outsiderSid,
       body: newRobot(id.siteA, id.orgA, "rb-baseline"),
     });
-    assert.equal(create.status, 400);
-    assert.equal(create.body?.message, MODEL_REFUSAL);
+    assert.equal(create.status, 201);
+
+    // Stored against the SESSION's account, and defaulted to a cleaning robot.
+    const stored = await byName("rb-baseline");
+    assert.equal(String(stored.metadata.siteId), String(id.siteA));
+    assert.equal(stored.type, "cleaning");
   });
 
   // ---- refusals -----------------------------------------------------------
@@ -167,8 +181,9 @@ describe("robots and their credentials are scoped to their estate", { concurrenc
       body: newRobot(id.siteB, id.orgB, "rb-planted"),
     });
 
-    // 404 from the guard, NOT the model's 400 - the request never reached the
-    // service. Case 6 is the same request from someone who may make it.
+    // 404 from the guard - the request never reached the service, so nothing was
+    // stored. Case 6 is the same request from someone who may make it, and it
+    // now succeeds, which is what makes this refusal meaningful.
     assert.equal(res.status, 404);
     assert.notEqual(res.body?.message, MODEL_REFUSAL);
     assert.equal(await countAtSite(id.siteB), before);
@@ -195,21 +210,28 @@ describe("robots and their credentials are scoped to their estate", { concurrenc
 
   // ---- still works: the people who are supposed to reach it ---------------
 
-  record("6. an authorised create still gets PAST the guard (and dies at the model)", async () => {
+  record("6. an authorised create gets past the guard AND is stored", async () => {
     const res = await h.api("/robots", {
       method: "POST",
       sid: managerSid,
       body: newRobot(id.siteB, id.orgB, "rb-allowed"),
     });
 
-    assert.equal(res.status, 400);
-    assert.equal(res.body?.message, MODEL_REFUSAL);
+    assert.equal(res.status, 201);
+    const stored = await byName("rb-allowed");
+    assert.equal(String(stored.metadata.siteId), String(id.siteB));
   });
 
   record("7. the site B client still LISTS site B", async () => {
     const res = await h.api(listUrl(id.orgB, id.siteB), { sid: managerSid });
     assert.equal(res.status, 200);
-    assert.equal(res.body?.items?.length, 1);
+
+    // A count, not an exact one: case 6 now genuinely stores a robot at site B,
+    // so pinning this to 1 would only be asserting the order the cases run in.
+    // What matters is that site B's own robots are here and site A's are not.
+    const names = (res.body?.items ?? []).map((r) => r.name);
+    assert.ok(names.length >= 1);
+    assert.equal(names.includes("rb-baseline"), false, "site A's robot");
   });
 
   record("8. the contracted agency still LISTS its client's site (customer.sites branch)", async () => {
@@ -217,18 +239,21 @@ describe("robots and their credentials are scoped to their estate", { concurrenc
     // ACTIVE `customer.sites` engagement.
     const res = await h.api(listUrl(id.orgB, id.siteB), { sid: cleanerSid });
     assert.equal(res.status, 200);
-    assert.equal(res.body?.items?.length, 1);
+
+    const names = (res.body?.items ?? []).map((r) => r.name);
+    assert.ok(names.length >= 1);
+    assert.equal(names.includes("rb-baseline"), false, "site A's robot");
   });
 
-  record("9. the contracted agency's create still gets past the guard too", async () => {
+  record("9. the contracted agency's create gets past the guard too", async () => {
     const res = await h.api("/robots", {
       method: "POST",
       sid: cleanerSid,
       body: newRobot(id.siteB, id.orgB, "rb-agency"),
     });
 
-    assert.equal(res.status, 400);
-    assert.equal(res.body?.message, MODEL_REFUSAL);
+    assert.equal(res.status, 201);
+    assert.notEqual(await byName("rb-agency"), null);
   });
 
   record("10. Seven365 platform staff still reach any estate on both routes", async () => {
@@ -240,8 +265,7 @@ describe("robots and their credentials are scoped to their estate", { concurrenc
       sid: staffSid,
       body: newRobot(id.siteA, id.orgA, "rb-staff"),
     });
-    assert.equal(create.status, 400);
-    assert.equal(create.body?.message, MODEL_REFUSAL);
+    assert.equal(create.status, 201);
   });
 
   // ---- the refusal leaks nothing ------------------------------------------

package/test/robot-apps.test.mjs

@@ -0,0 +1,154 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  ROBOT_APP_SCOPES,
+  canMonitorRobotType,
+  canSetUpRobotType,
+  robotScopeForApp,
+  robotTypesVisibleTo,
+} from "./.build/utils/robot-apps.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * The owner's rule, 2026-09-22: iService365 is the fleet manager for EVERY
+ * robot on a property. A cleaning robot is set up in the cleaning apps, a
+ * security robot in the security apps, Property Management does both because
+ * the property owns the fleet, the Seven365 console does everything everywhere,
+ * and the managing agent watches without configuring.
+ *
+ * These assert that table, and the two ways it can fail quietly: an app nobody
+ * declared getting everything instead of nothing, and a refusal being read as
+ * "no filter".
+ * ----------------------------------------------------------------------- */
+
+const HYGIENE_WEB = "iservice365-web-app-hygiene";
+const ICLEAN = "iservice365-hygiene-mobile-app";
+const SECURITY_WEB = "iservice365-web-app-security";
+const ISECURE = "iservice365-security-mobile-app";
+const PM_WEB = "iservice365-web-app-property-management";
+const IMA = "iservice365-ma-mobile-app";
+const CONSOLE = "iservice365-web-app-admin";
+
+/* ------------------------------------------------------- the owner's rule */
+
+test("cleaning apps see cleaning robots and NOT security patrols", () => {
+  for (const app of [HYGIENE_WEB, ICLEAN]) {
+    assert.equal(canSetUpRobotType(app, "cleaning"), true, app);
+    assert.equal(canMonitorRobotType(app, "cleaning"), true, app);
+
+    // A cleaner must never be shown where a security patrol is.
+    assert.equal(canSetUpRobotType(app, "security"), false, app);
+    assert.equal(canMonitorRobotType(app, "security"), false, app);
+  }
+});
+
+test("security apps see security robots and NOT cleaning robots", () => {
+  for (const app of [SECURITY_WEB, ISECURE]) {
+    assert.equal(canSetUpRobotType(app, "security"), true, app);
+    assert.equal(canMonitorRobotType(app, "security"), true, app);
+    assert.equal(canSetUpRobotType(app, "cleaning"), false, app);
+    assert.equal(canMonitorRobotType(app, "cleaning"), false, app);
+  }
+});
+
+test("Property Management sets up and monitors BOTH", () => {
+  for (const type of ["cleaning", "security"]) {
+    assert.equal(canSetUpRobotType(PM_WEB, type), true, type);
+    assert.equal(canMonitorRobotType(PM_WEB, type), true, type);
+  }
+});
+
+test("the Seven365 console does everything, for every robot type", () => {
+  for (const type of ["cleaning", "security"]) {
+    assert.equal(canSetUpRobotType(CONSOLE, type), true, type);
+    assert.equal(canMonitorRobotType(CONSOLE, type), true, type);
+  }
+});
+
+test("the managing agent watches the whole fleet but configures nothing", () => {
+  assert.equal(canMonitorRobotType(IMA, "cleaning"), true);
+  assert.equal(canMonitorRobotType(IMA, "security"), true);
+
+  // Setup is a different job from monitoring - iMA365 must not be able to
+  // re-point a robot at a different cloud.
+  assert.equal(canSetUpRobotType(IMA, "cleaning"), false);
+  assert.equal(canSetUpRobotType(IMA, "security"), false);
+});
+
+/* ------------------------------------------------------------ fails closed */
+
+test("an app nobody declared gets NO robots, not all of them", () => {
+  // A new service app, a renamed deployment, a typo in an env var. The wrong
+  // default here is a landscaping app listing a building's security patrols.
+  for (const unknown of [
+    "iservice365-landscaping-mobile-app",
+    "iservice365-web-app-pest-control",
+    "not-an-app",
+    "",
+    null,
+    undefined,
+    42,
+    {},
+  ]) {
+    assert.deepEqual(
+      robotScopeForApp(unknown),
+      { setup: [], monitor: [] },
+      String(unknown)
+    );
+    assert.equal(canMonitorRobotType(unknown, "cleaning"), false);
+    assert.equal(canSetUpRobotType(unknown, "security"), false);
+  }
+});
+
+test("an unknown robot type is refused everywhere, including the console", () => {
+  for (const app of Object.keys(ROBOT_APP_SCOPES)) {
+    assert.equal(canSetUpRobotType(app, "drone"), false, app);
+    assert.equal(canMonitorRobotType(app, undefined), false, app);
+  }
+});
+
+/* --------------------------------------------------- the listing filter */
+
+test("no type requested means every type the app may monitor", () => {
+  assert.deepEqual(robotTypesVisibleTo(PM_WEB), ["cleaning", "security"]);
+  assert.deepEqual(robotTypesVisibleTo(ICLEAN), ["cleaning"]);
+  assert.deepEqual(robotTypesVisibleTo(ISECURE, ""), ["security"]);
+  assert.deepEqual(robotTypesVisibleTo(PM_WEB, null), ["cleaning", "security"]);
+});
+
+test("a permitted type narrows the listing to that type", () => {
+  assert.deepEqual(robotTypesVisibleTo(PM_WEB, "security"), ["security"]);
+  assert.deepEqual(robotTypesVisibleTo(CONSOLE, "cleaning"), ["cleaning"]);
+});
+
+test("asking for a type the app may not see returns [] - list NOTHING", () => {
+  // The case that must never be read as "no filter": if a caller treats the
+  // empty array as "no constraint", a refusal becomes a listing of every robot
+  // on the estate.
+  assert.deepEqual(robotTypesVisibleTo(ICLEAN, "security"), []);
+  assert.deepEqual(robotTypesVisibleTo(ISECURE, "cleaning"), []);
+  assert.deepEqual(robotTypesVisibleTo(IMA, "drone"), []);
+  assert.deepEqual(robotTypesVisibleTo("not-an-app", "cleaning"), []);
+});
+
+test("an app that monitors nothing is never widened by an empty request", () => {
+  // iMA365 configures nothing, so its SETUP list is empty - but that must not
+  // make `robotTypesVisibleTo` return everything for an unlisted app.
+  assert.deepEqual(robotTypesVisibleTo("not-an-app"), []);
+  assert.deepEqual(robotTypesVisibleTo("not-an-app", undefined), []);
+});
+
+/* ------------------------------------------------------------ the table */
+
+test("every declared app names only known robot types", () => {
+  const known = new Set(["cleaning", "security"]);
+  for (const [app, scope] of Object.entries(ROBOT_APP_SCOPES)) {
+    for (const t of [...scope.setup, ...scope.monitor]) {
+      assert.equal(known.has(t), true, `${app} declares unknown type ${t}`);
+    }
+    // Anything an app can set up, it must also be able to see.
+    for (const t of scope.setup) {
+      assert.equal(scope.monitor.includes(t), true, `${app} sets up ${t} blind`);
+    }
+  }
+});

package/test/robot-cloud.test.mjs

@@ -0,0 +1,222 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { test } from "node:test";
+
+import {
+  ROBOT_CLOUD_PATHS,
+  ROBOT_STATUS_NAMES,
+  areaColourToHex,
+  hexToAreaColour,
+  isDispatchable,
+  metresToPixel,
+  pixelToMetres,
+  planDayFromJsDay,
+  robotCloudBody,
+  robotCloudSign,
+  robotCloudSigningString,
+  robotCloudTimestamp,
+  robotMode,
+  robotModeFromList,
+} from "./.build/utils/robot-cloud.util.mjs";
+
+/* --------------------------------------------------------------------------
+ * What these guard.
+ *
+ * The cleaning-robot cloud authenticates every request with a SHA-1 over a
+ * string whose field order, separators and url path are all load-bearing: get
+ * any character wrong and every call is rejected with no clue why. And its
+ * status vocabulary is 27 codes deep, where mapping one of them to the wrong
+ * side of "is this robot free?" sends a second job to a robot already cleaning.
+ *
+ * Source: "Robot Cloud API Document (2025.05.27)".
+ * ----------------------------------------------------------------------- */
+
+/* ------------------------------------------------------------------ signing */
+
+test("the signing string is exactly the documented field order", () => {
+  assert.equal(
+    robotCloudSigningString("APPID", "20250520200000", "/portal/x", "SECRET"),
+    "appid=APPID,timestamp=20250520200000,url=/portal/x,secret=SECRET"
+  );
+});
+
+test("the signature is sha1 of that string, in lower-case hex", () => {
+  const expected = createHash("sha1")
+    .update("appid=a,timestamp=20250520200000,url=/portal/x,secret=s")
+    .digest("hex");
+
+  assert.equal(robotCloudSign("a", "20250520200000", "/portal/x", "s"), expected);
+  assert.match(
+    robotCloudSign("a", "20250520200000", "/portal/x", "s"),
+    /^[0-9a-f]{40}$/
+  );
+});
+
+test("the url is part of the hash, so two endpoints never share a signature", () => {
+  // The document's own examples show get-map-list and get-file-url carrying the
+  // SAME sign at the same timestamp, which its own formula makes impossible.
+  // That is a copy-paste in the PDF; this asserts the formula, not the PDF.
+  const a = robotCloudSign("a", "20250520200000", ROBOT_CLOUD_PATHS.mapList, "s");
+  const b = robotCloudSign("a", "20250520200000", ROBOT_CLOUD_PATHS.fileUrl, "s");
+  assert.notEqual(a, b);
+});
+
+test("a path without a leading slash is refused rather than silently signed", () => {
+  assert.throws(
+    () => robotCloudSign("a", "20250520200000", "portal/x", "s"),
+    /must start with/
+  );
+});
+
+test("missing credentials throw instead of signing an empty secret", () => {
+  assert.throws(() => robotCloudSign("", "20250520200000", "/p", "s"), /appid/);
+  assert.throws(() => robotCloudSign("a", "20250520200000", "/p", ""), /secret/);
+});
+
+test("the timestamp is yyyyMMddHHmmss, zero-padded", () => {
+  assert.equal(
+    robotCloudTimestamp(new Date(Date.UTC(2025, 4, 20, 20, 0, 0))),
+    "20250520200000"
+  );
+  // Single-digit month, day, hour, minute and second all pad.
+  assert.equal(
+    robotCloudTimestamp(new Date(Date.UTC(2025, 0, 2, 3, 4, 5))),
+    "20250102030405"
+  );
+});
+
+test("the secret is hashed and never becomes a field in the body", () => {
+  const body = robotCloudBody(
+    "APPID",
+    "SUPER-SECRET",
+    ROBOT_CLOUD_PATHS.robotList,
+    { robotSn: "CASDF03456" },
+    new Date(Date.UTC(2025, 4, 20, 20, 0, 0))
+  );
+
+  assert.deepEqual(Object.keys(body).sort(), [
+    "appid",
+    "robotSn",
+    "sign",
+    "timestamp",
+  ]);
+  assert.equal(
+    JSON.stringify(body).includes("SUPER-SECRET"),
+    false,
+    "the secret must never be transmitted"
+  );
+});
+
+/* ------------------------------------------------------------------ status */
+
+test("an unknown status is UNAVAILABLE, never dispatchable", () => {
+  // The branch that matters: a firmware code we have never seen must not read
+  // as "free, send it a job".
+  for (const unknown of [42, -1, 998, null, undefined, "1", NaN]) {
+    assert.equal(robotMode(unknown), "UNAVAILABLE", `status ${unknown}`);
+    assert.equal(isDispatchable(unknown), false, `status ${unknown}`);
+  }
+});
+
+test("only idle, ready and charged robots are dispatchable", () => {
+  assert.deepEqual(
+    Object.keys(ROBOT_STATUS_NAMES)
+      .map(Number)
+      .filter(isDispatchable)
+      .sort((a, b) => a - b),
+    [1, 9, 24]
+  );
+});
+
+test("every cleaning status is WORKING and refuses a second job", () => {
+  for (const cleaning of [2, 10, 12]) {
+    assert.equal(robotMode(cleaning), "WORKING");
+    assert.equal(isDispatchable(cleaning), false);
+  }
+});
+
+test("switching floor is IN_TRANSIT - the lift case, not an idle robot", () => {
+  assert.equal(robotMode(21), "IN_TRANSIT");
+  assert.equal(isDispatchable(21), false);
+});
+
+test("every documented status has both a name and a mode", () => {
+  for (const code of Object.keys(ROBOT_STATUS_NAMES).map(Number)) {
+    assert.ok(ROBOT_STATUS_NAMES[code], `status ${code} has no name`);
+    assert.notEqual(
+      robotMode(code),
+      undefined,
+      `status ${code} has no mode`
+    );
+  }
+});
+
+test("offline beats a stale cached status", () => {
+  // get-robot-list can report a status from before the robot dropped off.
+  assert.equal(robotModeFromList({ statusFlag: 1, onlineFlag: false }), "UNAVAILABLE");
+  assert.equal(robotModeFromList({ statusFlag: 1, onlineFlag: true }), "IDLE");
+});
+
+/* ------------------------------------------------------------- coordinates */
+
+test("pixels and metres round-trip through the map transform", () => {
+  // The example map from the document.
+  const map = { originX: -49.713, originY: -35.846, resolution: 0.05 };
+  const height = 800;
+
+  const metres = pixelToMetres(504, 416, map, height);
+  const back = metresToPixel(metres.x, metres.y, map, height);
+
+  assert.deepEqual(back, { x: 504, y: 416 });
+});
+
+test("the transform matches the documented formula", () => {
+  const map = { originX: -49.713, originY: -35.846, resolution: 0.05 };
+  const { x, y } = pixelToMetres(100, 200, map, 800);
+
+  assert.equal(Number(x.toFixed(4)), Number((-49.713 + 100 * 0.05).toFixed(4)));
+  assert.equal(
+    Number(y.toFixed(4)),
+    Number((-35.846 + (800 - 200) * 0.05).toFixed(4))
+  );
+});
+
+test("a zero resolution throws rather than dividing by zero", () => {
+  assert.throws(
+    () => metresToPixel(0, 0, { originX: 0, originY: 0, resolution: 0 }, 800),
+    /resolution/
+  );
+});
+
+/* ------------------------------------------------------------------- areas */
+
+test("area colours round-trip between the map's hex and the plan's object", () => {
+  // The two endpoints name the same area two different ways.
+  assert.deepEqual(hexToAreaColour("FF0B0B83"), {
+    r: 255,
+    g: 11,
+    b: 11,
+    a: 131,
+  });
+  assert.equal(areaColourToHex({ r: 255, g: 11, b: 11, a: 131 }), "FF0B0B83");
+  assert.equal(areaColourToHex(hexToAreaColour("B7CAEFFF")), "B7CAEFFF");
+});
+
+test("the plan example's colour survives the round trip", () => {
+  const fromPlan = { r: 186, g: 20, b: 75, a: 255 };
+  assert.deepEqual(hexToAreaColour(areaColourToHex(fromPlan)), fromPlan);
+});
+
+test("a malformed colour is refused, not half-parsed", () => {
+  assert.throws(() => hexToAreaColour("FF0B0B"), /8 hex digits/);
+  assert.throws(() => hexToAreaColour("ZZ0B0B83"), /8 hex digits/);
+  assert.throws(() => areaColourToHex({ r: 256, g: 0, b: 0, a: 0 }), /out of range/);
+});
+
+/* --------------------------------------------------------------- job plans */
+
+test("plan days are 1-7 Monday-Sunday, not JavaScript's 0-6 Sunday-Saturday", () => {
+  assert.equal(planDayFromJsDay(0), 7, "Sunday");
+  assert.equal(planDayFromJsDay(1), 1, "Monday");
+  assert.equal(planDayFromJsDay(6), 6, "Saturday");
+});