@7365admin1/layer-common 4.82.0 → 4.82.1-staging.470

package/plugins/secure-member.client.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { routeDenied } from "../utils/module-routes.ts";
+import useStaffView, { STAFF_VIEW_ROLE, staffViewCovers } from "../composables/useStaffView.ts";
 
 const hexSchema = z
   .string()
@@ -63,6 +64,13 @@ export default defineNuxtPlugin(() => {
   const { userAppRole, userAppRoleStatus, userAppModulesDenied, id, orgNature } =
     useLocalSetup();
 
+  // "Open as Seven365 staff": the server holds the view against the session.
+  // While it covers the route's organisation, staff work there with full setup
+  // rights instead of their own (absent) membership. Nothing is written.
+  const { loadStaffView } = useStaffView();
+  let staffViewActive = false;
+  let lastStaffOrg = "";
+
   // Resolved once per signed-in session, not once per navigation. Keyed by the
   // user cookie so signing in as somebody else re-resolves.
   // Keyed by user AND the site the role was resolved AT, so switching site
@@ -87,8 +95,8 @@ export default defineNuxtPlugin(() => {
   // both do -- and that is a real answer ("no organisation role"), not an error.
   // Treating it as an error is what would bounce those accounts off their own
   // pages; leaving it unanswered is what let gates fail open.
-  async function resolveAppRole(userId: string, site: string) {
-    const key = `${userId}|${site}`;
+  async function resolveAppRole(userId: string, site: string, staffOrg = "") {
+    const key = `${userId}|${site}${staffOrg ? `|staff:${staffOrg}` : ""}`;
     if (resolvedFor === key) return;
     if (inFlight) {
       // A lookup for the SAME key is the one we want: await it and stop, which
@@ -105,15 +113,25 @@ export default defineNuxtPlugin(() => {
     // question, so the resolved role stays on screen and nothing flickers.
     if (resolvedFor === null || SEND_SITE) userAppRoleStatus.value = "loading";
     inFlightKey = key;
-    inFlight = run(userId, site).finally(() => {
+    inFlight = run(userId, site, staffOrg).finally(() => {
       inFlight = null;
     });
     return inFlight;
   }
 
-  async function run(userId: string, site: string) {
+  async function run(userId: string, site: string, staffOrg = "") {
     const APP = useRuntimeConfig().public.APP;
 
+    staffViewActive = !!staffOrg;
+    if (staffOrg) {
+      hasMemberDocument = true;
+      id.value = staffOrg;
+      userAppRole.value = STAFF_VIEW_ROLE;
+      resolvedFor = `${userId}|${site}|staff:${staffOrg}`;
+      userAppRoleStatus.value = "resolved";
+      return;
+    }
+
     try {
       // The org query is not sent: without it the server's site rule answers
       // with the membership pinned to `site` or, failing that, with exactly the
@@ -157,7 +175,8 @@ export default defineNuxtPlugin(() => {
   // that is not a list all mean nothing is denied -- never "hide everything".
   // It never touches the role or its status.
   async function resolveDenied(userId: string, site: string) {
-    if (!hasMemberDocument) {
+    // Seven365 staff are not capped by the client's module list.
+    if (!hasMemberDocument || staffViewActive) {
       deniedFor = deniedWanted = null;
       userAppModulesDenied.value = [];
       return;
@@ -192,8 +211,13 @@ export default defineNuxtPlugin(() => {
     // default open granted everything, gates that fail closed denied everything.
     // Awaited, so no gate is ever evaluated against an unresolved role.
     const site = idParam(to.params.site);
+    const routeOrg = idParam(to.params.org) || idParam(to.params.organization);
+    // Only an organisation's pages can be opened as staff, so only they ask.
+    const view = userId && routeOrg ? await bounded(loadStaffView()).catch(() => null) : null;
+    const staffOrg = staffViewCovers(view, routeOrg) ? routeOrg : "";
+    lastStaffOrg = staffOrg;
 
-    if (userId) await resolveAppRole(userId, site);
+    if (userId) await resolveAppRole(userId, site, staffOrg);
     if (userId) await resolveDenied(userId, site);
     else if (userAppModulesDenied.value.length) {
       // Signed out: never carry the previous person's list.
@@ -268,7 +292,7 @@ export default defineNuxtPlugin(() => {
     const site = idParam(router.currentRoute.value.params.site);
 
     refreshing = (async () => {
-      await run(userId, site);
+      await run(userId, site, lastStaffOrg);
       deniedFor = null;
       await resolveDenied(userId, site);
     })()

package/types/document.d.ts

@@ -3,4 +3,18 @@ declare type TDocument = {
   name: string;
   attachment: string;
   type: string;
+  /**
+   * Set at upload or renewal, absent when the document never expires.
+   *
+   * An ISO instant on the way out of the API and a `YYYY-MM-DD` string on the
+   * way back in, which is what `InputDatePicker` binds to - hence the loose
+   * type rather than `string`.
+   */
+  expiryDate?: string | Date | null;
+  remarks?: string;
+  size?: number;
+  parentId?: string | null;
+  createdAt?: string | Date;
+  updatedAt?: string | Date;
+  status?: string;
 };

package/types/facility.d.ts

@@ -73,6 +73,10 @@ declare type TFacility = {
   hourInterval?: number;
   isBookingFeeEnabled: boolean;
   isGuestEnabled: boolean;
+  /** Residents may complete this facility's checklist themselves. */
+  isResidentChecklistEnabled?: boolean;
+  /** Security may complete it. Mutually exclusive with the above. */
+  isSecurityChecklistEnabled?: boolean;
   bookingAmount: number | null;
   peakBookingFeeAmount?: number | null;
   bookingFeeGuestAmount?: number | null;

package/types/member.d.ts

@@ -10,6 +10,10 @@ declare type TMember = {
   customerOrgId?: string;
   customerSiteId?: string;
   status?: string;
+  email?: string;
+  /** The building unit this member manages (a unit's Management tab). */
+  unit?: string | null;
+  unitName?: string;
   createdAt?: string;
   updatedAt?: string;
   deletedAt?: string;

package/types/people.d.ts

@@ -22,11 +22,38 @@ declare type TPeople = {
   email?: string;
   files?: { name: string, id: string }[];
   isOwner?: boolean;
+  /**
+   * Owner / occupant / person-in-charge, as the BUSINESS people form asks it.
+   * Absent on everyone else - `isOwner` is still the flag that decides unit
+   * ownership, and the server derives it from this when it is sent. See
+   * `OccupancyRoles` in core's `person.model.ts`.
+   */
+  occupancyRole?: TOccupancyRole;
+  // Link to this person's `users` row. Empty for the person types that carry
+  // no login, and empty for a resident whose account was never written.
+  user?: string;
+};
+
+declare type TOccupancyRole = "owner" | "occupant" | "person-in-charge";
+
+/** One standing and everything the product says about it. See `utils/occupancy-role.ts`. */
+declare type TOccupancyRoleOption = {
+  value: TOccupancyRole;
+  /** The label a stored role is printed with. */
+  title: string;
+  /** The row menu's wording. */
+  action: string;
+  /** The confirmation's heading and its sentence. */
+  prompt: string;
+  description: string;
 };
 
 declare type TPlateNumber = { plateNumber: string, recNo?: string, _id?: string, status: TVehicleStatus, type: TVehicleType, anprCameras?: TVehicleAnprCamera[] };
 
 
-declare type TPeoplePayload = Pick<TGuest, "name" | "block" | "level" | "unit" | "unitName" | "contact" | "plateNumber" | "nric" | "contact" | "remarks" | "org" | "site" | "start" | "end" | "type" | "isOwner"> & { status?: string }
+// `""` is the FORM's "nothing picked yet" - it is stripped from the payload
+// before it is sent, because absence is what the server reads as "never
+// asked". See `PeopleFormMgmt.vue`.
+declare type TPeoplePayload = Pick<TGuest, "name" | "block" | "level" | "unit" | "unitName" | "contact" | "plateNumber" | "nric" | "contact" | "remarks" | "org" | "site" | "start" | "end" | "type" | "isOwner"> & { status?: string; user?: string; occupancyRole?: TOccupancyRole | "" }
 
 declare type TPeopleType = "guest" | "resident" | "tenant"

package/types/service-provider.d.ts

@@ -7,6 +7,11 @@ declare type TServiceProvider = {
   serviceProviderOrgId: string;
   type: string;
   nature: string;
+  status?: string;
+  email?: string;
+  /** The building unit this provider serves (a unit's Management tab). */
+  unit?: string | null;
+  unitName?: string;
 };
 
 declare type TServiceProviderName = {

package/types/staff-view.d.ts

@@ -0,0 +1,10 @@
+/** "Open as Seven365 staff": the client/site a staff session has open (core `staff-view.util.ts`). */
+declare type TStaffView = {
+  user: string;
+  org: string;
+  orgName: string;
+  site: string;
+  siteName: string;
+  app: string;
+  startedAt: string;
+};

package/utils/hid-enrolment-subject.ts

@@ -0,0 +1,144 @@
+/**
+ * WHO A HID ENROLMENT IS FOR — the pure decisions behind the subject picker.
+ *
+ * `HidUserEnrollment.vue` can enrol a resident or a staff member. The write path
+ * always carried both (`subjectLink` maps them onto `person` or `member`); what
+ * was missing was a way to choose. These are the parts of that choice worth
+ * testing on their own, kept here because a `.vue` component has no test harness
+ * in this repo.
+ */
+
+export type HidEnrolmentSubject = "resident" | "property_management";
+
+/**
+ * The dropdown's options, in the order they are drawn.
+ *
+ * `title`/`value` because `AppSelect` takes that shape. A service-provider
+ * option is expected next; adding it here is most of the work, since the write
+ * path already maps `service_provider` onto `serviceProvider`.
+ */
+export const HID_ENROLMENT_SUBJECTS: ReadonlyArray<{
+  title: string;
+  value: HidEnrolmentSubject;
+}> = [
+  { title: "Resident", value: "resident" },
+  { title: "Member", value: "property_management" },
+];
+
+/**
+ * What an EDIT calls the subject it is already attached to.
+ *
+ * Wider than the dropdown on purpose. An identity's category cannot change after
+ * it is created, so an edit states it rather than offering it — and the records
+ * in the wild include `service_provider`, which the dropdown does not offer yet
+ * but `openEdit` does resolve. Falling back to the first option would label a
+ * contractor "Resident", which is worse than saying nothing useful.
+ */
+export function subjectCategoryLabel(category: unknown): string {
+  const labels: Record<string, string> = {
+    resident: "Resident",
+    property_management: "Member",
+    service_provider: "Service provider",
+    visitor: "Visitor",
+  };
+  return labels[String(category ?? "")] ?? "Unknown";
+}
+
+/**
+ * One page of `GET /api/members`, read defensively.
+ *
+ * `paginate` puts `{ items, pages }` at the root, but `items` sits under `data`
+ * on some of this product's endpoints, so both are read — the same allowance
+ * `readCandidatePage` makes. A response that carries neither is an empty page
+ * rather than a thrown error: an empty staff picker with a placeholder beats a
+ * broken dialog.
+ */
+export function readMemberPage(response: unknown): {
+  items: Record<string, unknown>[];
+  pages: number;
+  total: number;
+} {
+  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 raw = Array.isArray(source.items)
+    ? source.items
+    : Array.isArray(nested.items)
+      ? nested.items
+      : [];
+  const pages = Number(source.pages ?? nested.pages ?? 1);
+  const items = raw.filter((row): row is Record<string, unknown> => Boolean(row) && typeof row === "object");
+  /*
+   * `total` drives "showing 10 of 23" and the Load more button. It falls back to
+   * the page's own length, not to zero, so a response without it simply reads as
+   * "this is everything" — a missing count must never make the button offer a
+   * page that is not there.
+   */
+  const total = Number(source.total ?? nested.total ?? items.length);
+  return {
+    items,
+    pages: Number.isFinite(pages) && pages > 0 ? Math.floor(pages) : 1,
+    total: Number.isFinite(total) && total >= 0 ? Math.floor(total) : items.length,
+  };
+}
+
+/**
+ * Can this member actually be enrolled?
+ *
+ * Reader access is bound by USER id — `resolvePermissionUserBindings` in
+ * `iservice365-core` drops every subject without one — so a member with no app
+ * account cannot be given access and is not a candidate. The id arrives as a
+ * string from JSON but may be an object if a caller passes a raw document, so
+ * both are read rather than trusting the shape.
+ */
+export function memberHasAccount(row: Record<string, unknown> | null | undefined): boolean {
+  const user = row?.user;
+  if (!user) return false;
+  if (typeof user === "object") {
+    const id = (user as { _id?: unknown; toString?: () => string })._id ?? user;
+    return Boolean(String(id ?? "").trim());
+  }
+  return Boolean(String(user).trim());
+}
+
+/**
+ * How a member reads in the picker: their name, and their role beneath it.
+ *
+ * THE ACCOUNT'S NAME FIRST, then the membership's. The two diverge — a
+ * membership is created with whatever name was typed at invite time, and the
+ * person may have set their own on the account since — and the account name is
+ * the one they are known by. `userName` comes from the members endpoint's own
+ * lookup into `users`; a member with no account has none, but such a row is not
+ * a candidate anyway (`memberHasAccount`).
+ *
+ * Every step falls back, because a row with no name at all still has to be
+ * selectable rather than blank, or it cannot be told apart from the next one.
+ */
+export function memberCandidateOf(row: Record<string, unknown>): {
+  subjectId: string;
+  name: string;
+  subtitle: string;
+} {
+  const text = (value: unknown) => String(value ?? "").trim();
+  return {
+    subjectId: text(row._id),
+    name: text(row.userName) || text(row.name) || text(row.email) || "Member",
+    subtitle: text(row.roleName) || text(row.email) || "",
+  };
+}
+
+/**
+ * Why somebody the operator can see elsewhere is not in this list.
+ *
+ * Left unexplained, an absence reads as a broken screen — the same reason the
+ * resident cascade carries `unitResidentNote`. Returns "" when there is nothing
+ * to say, so the caller can render it unconditionally.
+ */
+export function hiddenSubjectNote(count: number, noun: "resident" | "member"): string {
+  if (!Number.isFinite(count) || count <= 0) return "";
+  const whole = Math.floor(count);
+  const subject = whole === 1 ? `1 ${noun}` : `${whole} ${noun}s`;
+  const verb = whole === 1 ? "is" : "are";
+  const holder = whole === 1 ? "that person has" : "they have";
+  return `${subject} at this site ${verb} not listed:`
+    + ` HID enrollment needs an app account, and ${holder} none yet.`;
+}

package/utils/hid-permission-assignments.ts

@@ -0,0 +1,190 @@
+/**
+ * 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 three real categories. `intercom` is a candidate FILTER, never a category. */
+export const HID_PERMISSION_CATEGORIES: THidPermissionCategory[] = [
+  "resident",
+  "property_management",
+  "service_provider",
+];
+
+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] ?? "";
+}