@7365admin1/layer-common 3.2.7 → 3.2.8-staging.201

package/utils/dashboard.test.ts

@@ -0,0 +1,118 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { buildWorkOrderStatus } from "./dashboard.ts";
+
+/**
+ * THE DEFECT THIS FILE EXISTS FOR.
+ *
+ * The Property Management "Work Order Status" panel read
+ * `workOrderStatusSummary` - a key no endpoint returns - and fell through to
+ * the `openWorkOrder` KPI metric, which carries no `completed` field. So
+ * Completed read 0 on every site on every day, and Pending was silently
+ * recomputed as (open work orders - in progress) instead of read.
+ *
+ * The shape below is the one `new-dashboard.repo.ts` actually sends.
+ */
+test("the server's breakdown is read, not recomputed", () => {
+  const rows = buildWorkOrderStatus({
+    pending: 20,
+    inProgress: 12,
+    completed: 55,
+  });
+
+  assert.deepEqual(
+    rows.map((r) => [r.label, r.value]),
+    [
+      ["Completed", 55],
+      ["In Progress", 12],
+      ["Pending", 20],
+    ]
+  );
+});
+
+/**
+ * The exact regression. Before the fix this same input drew
+ * Completed 0 / In Progress 12 / Pending 28.
+ */
+test("Completed is never zero when the server says it is not", () => {
+  const completed = buildWorkOrderStatus({
+    pending: 20,
+    inProgress: 12,
+    completed: 55,
+  }).find((r) => r.label === "Completed");
+
+  assert.equal(completed?.value, 55);
+});
+
+/**
+ * The bars are share-of-largest-bucket, so the biggest is always full width
+ * and the rest are proportional to it. This is the widths the panel draws.
+ */
+test("each bar is its share of the largest bucket", () => {
+  const rows = buildWorkOrderStatus({ pending: 25, inProgress: 50, completed: 100 });
+
+  assert.deepEqual(
+    rows.map((r) => r.percent),
+    [100, 50, 25]
+  );
+});
+
+/** Three empty buckets must draw three empty bars, not divide by zero. */
+test("an all-zero breakdown does not divide by zero", () => {
+  const rows = buildWorkOrderStatus({ pending: 0, inProgress: 0, completed: 0 });
+
+  assert.equal(rows.length, 3);
+  for (const row of rows) {
+    assert.equal(row.value, 0);
+    assert.equal(row.percent, 0, row.label);
+    assert.ok(Number.isFinite(row.percent), row.label);
+  }
+});
+
+/** A partial payload is read for what it has and zeroed for what it does not. */
+test("missing buckets read as zero rather than undefined", () => {
+  const rows = buildWorkOrderStatus({ completed: 7 });
+
+  assert.deepEqual(
+    rows.map((r) => r.value),
+    [7, 0, 0]
+  );
+});
+
+/**
+ * NO FALLBACK, DELIBERATELY. When the breakdown is absent there is nothing
+ * honest to draw, so the panel must show its empty state - not bars built out
+ * of a different metric. An empty array is what triggers that.
+ */
+test("no breakdown means no bars, never invented ones", () => {
+  assert.deepEqual(buildWorkOrderStatus(undefined), []);
+  assert.deepEqual(buildWorkOrderStatus(null), []);
+  assert.deepEqual(buildWorkOrderStatus(42 as never), []);
+  assert.deepEqual(buildWorkOrderStatus("55" as never), []);
+});
+
+/**
+ * The tone is a token NAME, not a colour. The template writes `var(--<tone>)`,
+ * so a tone that is not a real token silently paints nothing.
+ */
+test("every row carries a real design token name", () => {
+  const rows = buildWorkOrderStatus({ pending: 1, inProgress: 2, completed: 3 });
+
+  assert.deepEqual(
+    rows.map((r) => r.tone),
+    ["ok", "err", "warn"]
+  );
+});
+
+/**
+ * The buckets are the whole of the server's status report - it folds every
+ * unrecognised status into `pending` rather than dropping it - so nothing the
+ * server counted goes missing on the way to the screen.
+ */
+test("the three buckets account for the whole breakdown", () => {
+  const src = { pending: 20, inProgress: 12, completed: 55 };
+  const total = buildWorkOrderStatus(src).reduce((sum, r) => sum + r.value, 0);
+
+  assert.equal(total, src.pending + src.inProgress + src.completed);
+});

package/utils/dashboard.ts

@@ -0,0 +1,53 @@
+/**
+ * Dashboard arithmetic that is worth testing on its own.
+ *
+ * `DashboardMain.vue` is 4,800 lines of template and wiring, and none of it is
+ * reachable from `node --test`. The one piece with real arithmetic in it - the
+ * work-order status breakdown - lives here instead, so the defect that made
+ * "Completed" read zero on every Property Management dashboard has a test that
+ * fails if it ever comes back.
+ */
+
+export type TWorkOrderStatusSource = {
+  pending?: number;
+  inProgress?: number;
+  completed?: number;
+} | null | undefined;
+
+export type TWorkOrderStatusRow = {
+  label: string;
+  value: number;
+  /** Share of the largest bucket, 0-100 - the bar's width. */
+  percent: number;
+  /** A design token name, not a colour: the caller writes `var(--<tone>)`. */
+  tone: "ok" | "err" | "warn";
+};
+
+/**
+ * The three status bars, from the breakdown the server sends as
+ * `workOrderStatus` (new-dashboard.repo.ts, property branch).
+ *
+ * NO FALLBACK. The screen used to read `workOrderStatusSummary` - a key no
+ * endpoint returns - and fall through to the `openWorkOrder` KPI metric, which
+ * carries no `completed` field: Completed was therefore ALWAYS 0 and Pending
+ * was silently recomputed as (open work orders - in progress) instead of read.
+ * Without the real breakdown there is nothing honest to draw, so this returns
+ * an empty list and the panel shows its empty state.
+ */
+export function buildWorkOrderStatus(
+  src: TWorkOrderStatusSource
+): TWorkOrderStatusRow[] {
+  if (!src || typeof src !== "object") return [];
+
+  const completed = Number(src.completed ?? 0);
+  const inProgress = Number(src.inProgress ?? 0);
+  const pending = Number(src.pending ?? 0);
+  // `1` floors the divisor: three empty buckets must not divide by zero.
+  const max = Math.max(completed, inProgress, pending, 1);
+
+  return [
+    { label: "Completed", value: completed, percent: (completed / max) * 100, tone: "ok" },
+    { label: "In Progress", value: inProgress, percent: (inProgress / max) * 100, tone: "err" },
+    { label: "Pending", value: pending, percent: (pending / max) * 100, tone: "warn" },
+  ];
+}

package/utils/data.test.ts

@@ -0,0 +1,95 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { findServiceProviderIdBySite, levelCount } from "./data.ts";
+
+const SITE = "68f05fcc0c11062938dadada";
+const OTHER_SITE = "68f05fcc0c11062938d00001";
+const PROVIDER = "68f05fcc0c11062938d00002";
+
+test("returns the provider that covers this site", () => {
+  assert.equal(
+    findServiceProviderIdBySite(
+      "service-provider",
+      [{ _id: PROVIDER, siteId: SITE }],
+      SITE
+    ),
+    PROVIDER
+  );
+});
+
+test("a non-service-provider account is not scoped by provider at all", () => {
+  assert.equal(findServiceProviderIdBySite("customer", [], SITE), null);
+  assert.equal(findServiceProviderIdBySite("", undefined, SITE), null);
+});
+
+/**
+ * Returning null here would drop the provider filter and show the whole site -
+ * another provider's work orders included. Refusing is the correct behaviour.
+ */
+test("refuses rather than falling back to an unscoped request", () => {
+  assert.throws(() =>
+    findServiceProviderIdBySite(
+      "service-provider",
+      [{ _id: PROVIDER, siteId: OTHER_SITE }],
+      SITE
+    )
+  );
+});
+
+/**
+ * The thrown message is rendered verbatim in a toast on six applications, so it
+ * is part of the user interface. Assert what it SAYS, not that it throws: the
+ * old message passed a "throws" assertion while quoting a raw ObjectId at a
+ * security officer and naming no action.
+ */
+test("the message names an action and never quotes an internal id", () => {
+  for (const providers of [[{ _id: PROVIDER, siteId: OTHER_SITE }], [], undefined]) {
+    let message = "";
+    try {
+      findServiceProviderIdBySite("service-provider", providers, SITE);
+      assert.fail("expected it to refuse");
+    } catch (error: any) {
+      message = error.message;
+    }
+    assert.doesNotMatch(message, /[0-9a-f]{24}/i, `leaks an id: ${message}`);
+    assert.doesNotMatch(message, /siteId/i, `internal wording: ${message}`);
+    assert.match(message, /not linked to this site/i);
+    assert.match(message, /administrator/i);
+  }
+});
+
+/**
+ * An account with no serviceProviders field at all used to die on
+ * `undefined.find(...)` - a TypeError, which the toast renders as a raw
+ * JavaScript error instead of the sentence above.
+ */
+test("an account with no provider list still gets the sentence, not a TypeError", () => {
+  assert.throws(
+    () => findServiceProviderIdBySite("service-provider", undefined, SITE),
+    (error: any) => error.constructor === Error && !/undefined/.test(error.message)
+  );
+});
+
+/**
+ * A block whose record carries no `levels` array used to throw during render
+ * (`Cannot read properties of undefined (reading 'length')`), which blanks the
+ * entire blocks table - not just the offending row.
+ */
+test("a block with no levels field counts as zero instead of throwing", () => {
+  assert.equal(levelCount({ levels: undefined }), 0);
+  assert.equal(levelCount({}), 0);
+  assert.equal(levelCount(undefined), 0);
+  assert.equal(levelCount(null), 0);
+});
+
+test("a block with no levels field is not confused with a block that has none", () => {
+  assert.equal(levelCount({ levels: [] }), 0);
+  assert.equal(levelCount({ levels: [{ name: "1" }, { name: "2" }] }), 2);
+});
+
+test("a non-array levels value is counted as zero, not as its own length", () => {
+  // The API has been seen to answer with a count rather than the array.
+  assert.equal(levelCount({ levels: 7 as unknown as [] }), 0);
+  assert.equal(levelCount({ levels: "12" as unknown as [] }), 0);
+});

package/utils/data.ts

@@ -30,17 +30,40 @@ export const errorConverter = (data: any): string => {
   return error;
 };
 
+/**
+ * A service-provider account can only be shown ITS OWN work orders, feedbacks
+ * and key logs, so every one of those screens scopes its request by the
+ * provider record that links this account to the site currently in the URL.
+ *
+ * When that link does not exist there is nothing to scope by, and returning
+ * null instead would drop the filter and show the WHOLE site - another
+ * provider's work orders included. So this still refuses, deliberately.
+ *
+ * What it refuses WITH is the part that matters. The message is thrown straight
+ * into a toast on six applications, so it is written for the person reading it:
+ * it says what is missing and what to do about it. It used to read
+ * "Service provider with siteId 68f0...dadada not found", which quotes an
+ * internal identifier at a security officer and names no action - the screen
+ * looked broken when the truth was simply that this site is not one of theirs.
+ *
+ * The site list in the sidebar offers EVERY site in the organisation, not only
+ * the ones this account covers, so an officer can walk into this by picking a
+ * neighbouring site. That is why the wording assumes an ordinary mistake and
+ * not a fault.
+ */
 export const findServiceProviderIdBySite = (
   type: string,
   serviceProviders: any,
   siteId: string
 ) => {
   if (type === "service-provider") {
-    const result = serviceProviders.find(
+    const result = serviceProviders?.find(
       (item: Record<string, any>) => item.siteId === siteId
     );
     if (!result?._id) {
-      throw new Error(`Service provider with siteId ${siteId} not found`);
+      throw new Error(
+        "Your service provider account is not linked to this site, so there is nothing to show here. Choose a site your company covers, or ask your administrator to link your company to this one."
+      );
     }
     return result?._id;
   }
@@ -137,3 +160,18 @@ export const generateRefNumber = () => {
   const ref = (timestamp + random).substring(0, 10).toUpperCase();
   return ref;
 };
+
+/**
+ * HOW MANY LEVELS A BLOCK HAS.
+ *
+ * `levels` is optional on a building record - a block created before levels
+ * were captured, or one the list endpoint returns without them, simply has no
+ * such field. Two screens read `building.levels.length` directly, which throws
+ * a TypeError DURING RENDER: Vue tears the component down and the whole blocks
+ * table disappears, so one incomplete row blanks every other row with it.
+ *
+ * Counting in one place means both screens - and anything added later - answer
+ * "no levels recorded" with a zero instead of taking the table down.
+ */
+export const levelCount = (building?: { levels?: unknown } | null): number =>
+  Array.isArray(building?.levels) ? building.levels.length : 0;

package/utils/hid-discover.test.ts

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import test from "node:test";
+
+import useHidAmico, { isUnknownSiteFieldError } from "../composables/useHidAmico.ts";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+type Call = { url: string; body: Record<string, unknown> };
+
+/**
+ * The composable calls the Nuxt auto-import `useNuxtApp().$api(...)`. Install a
+ * stub for it so the request body can be read without a Nuxt app.
+ */
+function stubApi(handler: (call: Call) => unknown) {
+  const calls: Call[] = [];
+  (globalThis as Record<string, unknown>).useNuxtApp = () => ({
+    $api: (url: string, options: { body: Record<string, unknown> }) => {
+      const call = { url, body: options.body };
+      calls.push(call);
+      return Promise.resolve(handler(call));
+    },
+  });
+  return calls;
+}
+
+function fetchError(message: string) {
+  return Object.assign(new Error("400 Bad Request"), { data: { message } });
+}
+
+test("discoverReader sends site in the request body", async () => {
+  const calls = stubApi(() => ({ data: { deviceId: "D1", portals: [] } }));
+
+  await useHidAmico().discoverReader({
+    baseUrl: "https://reader.example",
+    username: "operator",
+    password: "secret",
+    site: "0123456789abcdef01234567",
+  });
+
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].url, "/api/access-management/hid/readers/discover");
+  assert.equal(calls[0].body.site, "0123456789abcdef01234567");
+  assert.equal(calls[0].body.baseUrl, "https://reader.example");
+});
+
+test("discoverReader retries without site when the API predates core #1878", async () => {
+  const calls = stubApi((call) => {
+    if ("site" in call.body) throw fetchError('"site" is not allowed');
+    return { data: { deviceId: "D1", portals: [] } };
+  });
+
+  const response = await useHidAmico().discoverReader({
+    baseUrl: "https://reader.example",
+    username: "operator",
+    password: "secret",
+    site: "0123456789abcdef01234567",
+  });
+
+  assert.equal(calls.length, 2);
+  assert.equal("site" in calls[1].body, false);
+  assert.equal(calls[1].body.baseUrl, "https://reader.example");
+  assert.deepEqual(response, { data: { deviceId: "D1", portals: [] } });
+});
+
+test("discoverReader does not retry a real refusal", async () => {
+  const calls = stubApi(() => {
+    throw fetchError("You are not authorized to manage readers for this site.");
+  });
+
+  await assert.rejects(
+    useHidAmico().discoverReader({
+      baseUrl: "https://reader.example",
+      username: "operator",
+      password: "secret",
+      site: "0123456789abcdef01234567",
+    }),
+  );
+  assert.equal(calls.length, 1);
+});
+
+test("isUnknownSiteFieldError only matches the unknown-key message", () => {
+  assert.equal(isUnknownSiteFieldError(fetchError('"site" is not allowed')), true);
+  assert.equal(isUnknownSiteFieldError(new Error('"site" is not allowed')), true);
+  assert.equal(isUnknownSiteFieldError(fetchError('"site" is required')), false);
+  assert.equal(isUnknownSiteFieldError(fetchError('"baseUrl" is not allowed')), false);
+  assert.equal(isUnknownSiteFieldError(fetchError("Unauthorized")), false);
+  assert.equal(isUnknownSiteFieldError(null), false);
+});
+
+test("the reader form takes site as a prop and puts it in the discover call", () => {
+  const source = readFileSync(join(root, "components", "HidReaderForm.vue"), "utf8");
+  assert.match(source, /site:\s*\{\s*type:\s*String/);
+  assert.match(source, /discoverReader\(\{[\s\S]*?site:\s*props\.site[\s\S]*?\}\)/);
+});
+
+test("reader management passes its site prop down to the form", () => {
+  const source = readFileSync(join(root, "components", "HidReaderManagement.vue"), "utf8");
+  assert.match(source, /<HidReaderForm[\s\S]*?:site="site"[\s\S]*?\/>/);
+});

package/utils/list-page.test.ts

@@ -0,0 +1,60 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readListPage, NO_PAGE_RANGE } from "./list-page.ts";
+
+const rows = (n: number, from = 1) =>
+    Array.from({ length: n }, (_, i) => ({ _id: `row-${from + i}` }));
+
+describe("readListPage", () => {
+    it("keeps the server's total when it is bigger than the page - the failing case", () => {
+        // 47 announcements served 10 at a time. Deriving from the page gives
+        // "10" and one page, which is the defect this replaces.
+        const got = readListPage({ items: rows(10), pages: 5, pageRange: "1-10 of 47" });
+
+        assert.equal(got.items.length, 10);
+        assert.equal(got.pages, 5);
+        assert.equal(got.pageRange, "1-10 of 47");
+    });
+
+    it("keeps the server's page 2 range rather than re-slicing", () => {
+        const got = readListPage({ items: rows(10, 11), pages: 5, pageRange: "11-20 of 47" });
+
+        assert.equal(got.items.length, 10);
+        assert.equal(got.items[0]._id, "row-11");
+        assert.equal(got.pageRange, "11-20 of 47");
+    });
+
+    it("passes a single page through unchanged", () => {
+        const got = readListPage({ items: rows(7), pages: 1, pageRange: "1-7 of 7" });
+
+        assert.deepEqual(
+            { pages: got.pages, pageRange: got.pageRange, n: got.items.length },
+            { pages: 1, pageRange: "1-7 of 7", n: 7 }
+        );
+    });
+
+    it("reports a genuinely empty list as the server described it", () => {
+        const got = readListPage({ items: [], pages: 0, pageRange: "0 - 0 of 0" });
+
+        assert.deepEqual(got, { items: [], pages: 0, pageRange: "0 - 0 of 0" });
+    });
+
+    it("does not invent a zero when the request failed and there is no reply", () => {
+        for (const reply of [null, undefined]) {
+            const got = readListPage(reply);
+
+            assert.deepEqual(got.items, []);
+            assert.equal(got.pages, 0);
+            // "0 of 0" would be a statement about the data. This is not one.
+            assert.equal(got.pageRange, NO_PAGE_RANGE);
+        }
+    });
+
+    it("does not fall back to the page length when the envelope omits its totals", () => {
+        const got = readListPage({ items: rows(10) });
+
+        assert.equal(got.pages, 0);
+        assert.equal(got.pageRange, NO_PAGE_RANGE);
+        assert.notEqual(got.pageRange, "1-10 of 10");
+    });
+});

package/utils/list-page.ts

@@ -0,0 +1,38 @@
+/**
+ * READING A PAGINATED LIST REPLY.
+ *
+ * Every paginated endpoint in this product answers with an envelope: the rows
+ * for the page that was asked for, plus `pages` and `pageRange` describing the
+ * WHOLE list. Screens kept re-deriving those two from the rows they had just
+ * been handed - `items.length` is the size of one page, not the size of the
+ * list - so a list of 47 announcements presented itself as 10 and its pager
+ * was told there was one page.
+ *
+ * This is the one place that reads the envelope, so the rule is stated once:
+ * take the server's own totals, and when the reply is missing (a failed
+ * request) say so with a placeholder rather than inventing a zero.
+ */
+
+export const NO_PAGE_RANGE = "-- - -- of --";
+
+export type TListPageReply<T> = {
+    items?: T[] | null;
+    pages?: number | null;
+    pageRange?: string | null;
+} | null | undefined;
+
+export type TListPage<T> = {
+    items: T[];
+    pages: number;
+    pageRange: string;
+};
+
+export function readListPage<T>(reply: TListPageReply<T>): TListPage<T> {
+    return {
+        items: reply?.items ?? [],
+        // The server's page COUNT for the whole list. Never ceil(items/limit).
+        pages: reply?.pages ?? 0,
+        // The server's own "1-10 of 47" string. Never rebuilt from the page.
+        pageRange: reply?.pageRange || NO_PAGE_RANGE,
+    };
+}