@7365admin1/layer-common 4.90.1 → 4.90.2-staging.484

package/utils/hid-permission-assignments.ts

@@ -0,0 +1,198 @@
+/**
+ * WHO IS ASSIGNED TO A HID READER — the editing model behind the permissions
+ * dialog.
+ *
+ * This is the step that actually grants access. Enrolling a person gives the
+ * reader a face, a card or a PIN it can RECOGNISE; it puts nobody in the group
+ * the access rule is attached to, so a recognised person is still refused at
+ * the door (access log event 6). `PUT /sites/:siteId/permissions` is the only
+ * call in the system that writes that group membership.
+ *
+ * Two contracts make this file necessary rather than inlining the logic in the
+ * component:
+ *
+ * 1. **The PUT REPLACES the whole assignment set for the reader.** The server
+ *    keeps other readers' rows and overwrites this reader's with exactly what
+ *    is sent. The candidate list, however, is fetched ONE CATEGORY AT A TIME.
+ *    Saving from the tab in front of you while sending only that tab's people
+ *    would silently revoke every resident if you were looking at the service
+ *    providers tab. So the edit state is held for the whole reader and the
+ *    payload is always built from all of it.
+ *
+ * 2. **The body schema accepts three keys and nothing else.**
+ *    `hidPermissionAssignmentSchema` is `{ subjectId, category, intercom }`,
+ *    and Joi rejects unknown keys rather than stripping them. The candidate
+ *    rows carry `name`, `subtitle`, `location` and friends for display, so the
+ *    payload has to be narrowed deliberately — passing a candidate straight
+ *    through is a 400.
+ */
+
+/**
+ * The real categories. `intercom` is a candidate FILTER, never a category.
+ *
+ * Mirrors `HID_PERMISSION_CATEGORIES` in core, and has to: `seedAssignments`
+ * DROPS a row whose category is not in this list, so a category missing here
+ * silently loses that grant from the edit state - and the save that follows,
+ * being a whole-reader replace, would revoke it.
+ */
+export const HID_PERMISSION_CATEGORIES: THidPermissionCategory[] = [
+  "resident",
+  "property_management",
+  "service_provider",
+  "service_provider_member",
+];
+
+export type HidAssignmentState = Map<string, { category: THidPermissionCategory; intercom: boolean }>;
+
+/** Body row for `updateSitePermissions` — exactly the keys Joi allows. */
+export type HidAssignmentPayload = {
+  subjectId: string;
+  category: THidPermissionCategory;
+  intercom: boolean;
+};
+
+function isRealCategory(value: unknown): value is THidPermissionCategory {
+  return HID_PERMISSION_CATEGORIES.includes(value as THidPermissionCategory);
+}
+
+/**
+ * The reader's CURRENT assignments, as the edit state.
+ *
+ * Seeded from `getSitePermissions`, which returns every category at once —
+ * that is what makes a whole-reader payload possible from a one-category view.
+ * Rows with an unrecognised category are dropped rather than carried: sending
+ * one back fails the enum check and takes the entire save with it.
+ */
+export function seedAssignments(
+  assignments: readonly THidPermissionAssignment[] | undefined | null,
+): HidAssignmentState {
+  const state: HidAssignmentState = new Map();
+  if (!Array.isArray(assignments)) return state;
+  for (const assignment of assignments) {
+    const subjectId = String(assignment?.subjectId ?? "");
+    if (!subjectId || !isRealCategory(assignment?.category)) continue;
+    state.set(subjectId, {
+      category: assignment.category,
+      intercom: assignment.intercom === true,
+    });
+  }
+  return state;
+}
+
+/**
+ * Add or remove one person.
+ *
+ * `saved` is the state the dialog opened with, and it is consulted for one
+ * reason: the `intercom` flag. Nothing here edits that flag, but
+ * `userHasSiteIntercomPermission` reads it off these same rows, so it must
+ * survive a round trip through the checkbox.
+ *
+ * - **Untick then save** drops it, which is right — an unassigned person
+ *   holding a dangling intercom right would keep answering the door panel
+ *   after losing the door.
+ * - **Untick then re-tick, without saving** must restore it. Removing from the
+ *   draft forgets the flag, so re-adding recovers it from `saved`; otherwise a
+ *   misclick corrected a second later would silently revoke intercom on the
+ *   next save, with nothing on screen to show it had happened.
+ */
+export function setAssignment(
+  state: HidAssignmentState,
+  saved: HidAssignmentState,
+  subjectId: string,
+  category: THidPermissionCategory,
+  selected: boolean,
+): HidAssignmentState {
+  const next: HidAssignmentState = new Map(state);
+  const id = String(subjectId ?? "");
+  if (!id || !isRealCategory(category)) return next;
+  if (!selected) {
+    next.delete(id);
+    return next;
+  }
+  const intercom = next.get(id)?.intercom ?? saved.get(id)?.intercom ?? false;
+  next.set(id, { category, intercom: intercom === true });
+  return next;
+}
+
+/** The whole reader's assignments, narrowed to the three keys the API accepts. */
+export function toAssignmentPayload(state: HidAssignmentState): HidAssignmentPayload[] {
+  return [...state.entries()].map(([subjectId, value]) => ({
+    subjectId,
+    category: value.category,
+    intercom: value.intercom === true,
+  }));
+}
+
+/**
+ * The server sends `selected` with each candidate, describing what is SAVED.
+ * Once the dialog is open the local edit state is the truth, so the flag is
+ * recomputed rather than trusted — otherwise paging or searching would redraw
+ * a row with the saved value and quietly discard an unsaved tick.
+ */
+export function applySelection(
+  candidates: readonly THidPermissionCandidate[] | undefined | null,
+  state: HidAssignmentState,
+): THidPermissionCandidate[] {
+  if (!Array.isArray(candidates)) return [];
+  return candidates.map((candidate) => ({
+    ...candidate,
+    selected: state.has(String(candidate?.subjectId ?? "")),
+  }));
+}
+
+/** Per-category totals for the dialog header, counted over the whole reader. */
+export function countByCategory(state: HidAssignmentState): Record<THidPermissionCategory, number> {
+  const counts = { resident: 0, property_management: 0, service_provider: 0 } as Record<
+    THidPermissionCategory,
+    number
+  >;
+  for (const value of state.values()) counts[value.category] += 1;
+  return counts;
+}
+
+/** Has anything changed since the dialog opened? Drives the Save button. */
+export function hasChanges(saved: HidAssignmentState, draft: HidAssignmentState): boolean {
+  if (saved.size !== draft.size) return true;
+  for (const [subjectId, value] of draft) {
+    const before = saved.get(subjectId);
+    if (!before) return true;
+    if (before.category !== value.category) return true;
+    if (before.intercom !== value.intercom) return true;
+  }
+  return false;
+}
+
+/**
+ * What a listing response tells us: the rows, and how many pages exist.
+ *
+ * It deliberately does NOT return the current page, and the caller must keep
+ * owning that. `paginate` in `@7365admin1/node-server-utils` returns only
+ * `{ items, pages, pageRange }` — it never echoes the page it was asked for. A
+ * caller that read one back therefore got a default on every fetch and pinned
+ * itself to page one, so the pager moved and the rows never did.
+ *
+ * `items` sits at the root on some of these endpoints and under `data` on
+ * others, so both are read.
+ */
+export function readCandidatePage(response: unknown): {
+  items: THidPermissionCandidate[];
+  pages: number;
+  pageRange: string;
+} {
+  const source = (response && typeof response === "object" ? response : {}) as Record<string, unknown>;
+  const nested = (source.data && typeof source.data === "object" ? source.data : {}) as Record<string, unknown>;
+  const items = Array.isArray(source.items)
+    ? source.items
+    : Array.isArray(nested.items)
+      ? nested.items
+      : [];
+  const pages = Number(source.pages ?? nested.pages ?? 1);
+  // `paginate` builds this ("1-10 of 37") and the table renders it verbatim.
+  // Without it the pager draws its placeholder, "-- - -- of --".
+  const pageRange = String(source.pageRange ?? nested.pageRange ?? "");
+  return {
+    items: items as THidPermissionCandidate[],
+    pages: Number.isFinite(pages) && pages > 0 ? pages : 1,
+    pageRange,
+  };
+}

package/utils/hid-reader-selection.ts

@@ -0,0 +1,52 @@
+/**
+ * WHICH HID READER THE OPERATOR IS WORKING ON — the one rule behind it.
+ *
+ * Every HID screen used to hold its own `ref("")` and default it to
+ * `readers[0]`, so picking HID 2 on HID Reader Users and clicking through to
+ * HID Cards put you back on HID 1. They are separate PAGES, so the component
+ * unmounted and the ref was rebuilt from scratch every time — there was no way
+ * to make a choice stick. "I am working on HID 2" is a mode, not a per-screen
+ * preference.
+ *
+ * Navigation between those pages is a route change rather than a page load
+ * (`NavigationItem.vue` renders the menu's `route` through `:to`), so the
+ * module-scoped ref in `useHidReaderSelection` survives it. This file holds the
+ * part worth testing: deciding whether a remembered choice may still be used.
+ */
+
+export type HidReaderChoice = { siteId: string; readerId: string };
+
+/** Anything with an id — the four screens all carry a different reader shape. */
+type ReaderLike = { _id?: unknown };
+
+export const EMPTY_HID_READER_CHOICE: HidReaderChoice = { siteId: "", readerId: "" };
+
+/**
+ * The reader a screen should show, given what this site actually has.
+ *
+ * A remembered id is honoured ONLY when it belongs to this site and is still in
+ * the list. That single condition covers every way it goes stale:
+ *
+ * - the operator switched site, so the id belongs to a site they have left
+ * - the reader was deleted or deactivated since they chose it
+ * - nothing has been chosen yet
+ *
+ * In all three the first reader is returned instead. The alternative — using
+ * the id anyway — sends requests for a reader the site does not own, which come
+ * back empty and read on screen as a reader with no users, no cards and no
+ * logs, rather than as the mistake it is.
+ */
+export function resolveHidReaderId(
+  siteId: string,
+  readers: readonly ReaderLike[] | null | undefined,
+  choice: HidReaderChoice = EMPTY_HID_READER_CHOICE,
+): string {
+  const ids = (Array.isArray(readers) ? readers : [])
+    .map((reader) => String(reader?._id ?? ""))
+    .filter(Boolean);
+
+  if (choice.siteId === String(siteId ?? "") && ids.includes(choice.readerId)) {
+    return choice.readerId;
+  }
+  return ids[0] ?? "";
+}

package/utils/occupancy-role.ts

@@ -0,0 +1,109 @@
+/**
+ * OWNER / OCCUPANT / PERSON IN CHARGE - the three standings a business
+ * tenancy has, and everything the product says about them.
+ *
+ * One list, because three screens read it: the form that asks the question
+ * (`PeopleFormMgmt`), the list and preview that print the answer back, and
+ * the row menu that reassigns it (`people-mgmt`). The values are the ones the
+ * server stores and validates - `OccupancyRoles` in core's `person.model.ts`
+ * - so a value added on one side has to be added on the other.
+ */
+export const OCCUPANCY_ROLE_OPTIONS: TOccupancyRoleOption[] = [
+  {
+    value: "owner",
+    title: "Owner",
+    action: "Assign Owner",
+    prompt: "Assign Owner",
+    description:
+      "The legal titleholder or primary deed owner of the property.",
+  },
+  {
+    value: "occupant",
+    title: "Occupant",
+    action: "Assign Occupant",
+    prompt: "Assign Occupant",
+    description:
+      "The person currently living in, renting, or utilizing the physical unit.",
+  },
+  {
+    value: "person-in-charge",
+    title: "Person in Charge",
+    action: "Assign Person in Charge",
+    prompt: "Assign Person in Charge (PIC)",
+    description:
+      "The designated manager responsible for maintenance, emergencies, and daily operations.",
+  },
+];
+
+/**
+ * The same three, in the order the ROW MENU draws them, which is not the
+ * order the form's radio does. Derived rather than re-typed so the wording
+ * cannot drift between the two.
+ */
+export const OCCUPANCY_ROLE_ACTIONS: TOccupancyRoleOption[] = (
+  ["person-in-charge", "owner", "occupant"] as TOccupancyRole[]
+).map(
+  (value) =>
+    OCCUPANCY_ROLE_OPTIONS.find(
+      (option) => option.value === value,
+    ) as TOccupancyRoleOption,
+);
+
+/**
+ * The label for a stored role, or "" for a person who was never asked - which
+ * is everyone on a residential site and everyone saved before the question
+ * existed. Callers decide what to print instead; nobody should print a raw
+ * `person-in-charge` at a user.
+ */
+export function occupancyRoleLabel(role?: string | null): string {
+  return (
+    OCCUPANCY_ROLE_OPTIONS.find((option) => option.value === role)?.title ?? ""
+  );
+}
+
+/**
+ * Does this person hold OWNER at their unit?
+ *
+ * The role when there is one, `isOwner` when there is not - the same test the
+ * server applies (`holdsUnitOwner` in core's `unit-owner.util.ts`). A person
+ * recorded before the role existed carries only the flag, and the people list
+ * already prints them as "Owner".
+ */
+export function holdsUnitOwner(person?: {
+  occupancyRole?: string | null;
+  isOwner?: boolean;
+}): boolean {
+  if (!person) return false;
+
+  if (person.occupancyRole) return person.occupancyRole === "owner";
+
+  return person.isOwner === true;
+}
+
+/**
+ * MUST THIS PERSON HAND THE UNIT OVER BEFORE THEY CAN BE DEACTIVATED?
+ *
+ * The owner of a unit does not leave while they still own it - the standing
+ * moves to another tenant at the same block, level and unit first.
+ *
+ * Keyed to the ROLE and never to `isOwner`, exactly as the server keys it
+ * (`mustHandOverBeforeDeactivating` in core): the flag is on every resident in
+ * the estate, and no residential screen can change it, so a rule keyed to it
+ * would trap records that can never satisfy it.
+ */
+export function mustHandOverBeforeDeactivating(person?: {
+  occupancyRole?: string | null;
+}): boolean {
+  return person?.occupancyRole === "owner";
+}
+
+/**
+ * Why a deactivation was held back. The SERVER carries the enforcing copy of
+ * this rule and of these words (core `unit-owner.util.ts`); this one exists so
+ * the console can say it before the round trip rather than after.
+ */
+export function ownerHandoverRequiredMessage(name?: string): string {
+  const who = name?.trim() ? `"${name.trim()}"` : "This person";
+
+  return `${who} is the owner of this unit. Assign the owner role to another tenant at the same block, level and unit before deactivating them.`;
+}

package/utils/service-type.ts

@@ -0,0 +1,30 @@
+/**
+ * A SERVICE PROVIDER'S LINE OF BUSINESS, AS PEOPLE NAME IT.
+ *
+ * `/api/service-providers` returns the service CODE (`mechanical_electrical_services`),
+ * which is a database value, not something to show an operator. This is the same
+ * mapping `API-core src/utils/converter.ts spmServiceNewToOld` applies — copied
+ * rather than imported, because that is a server package this layer does not
+ * depend on.
+ *
+ * NOT the same labels as `utils/module-applications.ts APPLICATIONS`. Those name
+ * the seven role-permission applications ("Mechanical & electrical", "Pest
+ * control") and are keyed `mechanical-electrical`, not `*_services`. These are
+ * the shorter names the service-provider screens use ("M&E", "Pest Control").
+ *
+ * An unknown code is returned untouched: a new service type shows as its raw
+ * code, which is visibly odd, rather than vanishing from the row.
+ */
+const SERVICE_TYPE_LABELS: Readonly<Record<string, string>> = Object.freeze({
+  security_agency: "Security",
+  cleaning_services: "Cleaning",
+  pool_maintenance_services: "Pool Maintenance",
+  pest_control_services: "Pest Control",
+  landscaping_services: "Landscape",
+  mechanical_electrical_services: "Mechanical & Electrical",
+});
+
+export function serviceTypeLabel(service: string | null | undefined): string {
+  const code = String(service ?? "");
+  return SERVICE_TYPE_LABELS[code] ?? code;
+}