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

package/composables/useHidNavigation.ts

@@ -46,9 +46,33 @@ export default function useHidNavigation() {
           },
         },
         {
+          // "HID Reader Users" now points at `access-mgmt/administrator`, not at
+          // `access-mgmt/hid-users`.
+          //
+          // Both routes mount a roster of the reader's users, but only this one
+          // can act on them. `administrator` renders HidUserEnrollment WITHOUT
+          // `card-management`, and that prop is what gates the Enroll action:
+          //   <template v-if="!props.cardManagement" #actions>
+          // `hid-users` renders HidReaderUserRoster, which is read-only apart
+          // from PIN management. So the menu entry with this name used to lead
+          // to the screen that cannot enrol, while the screen that can was
+          // reachable only by typing the URL.
+          //
+          // `hid-users` is left in place and simply unlisted - the same state
+          // `administrator` was in - so any existing link to it still resolves.
           title: "HID Reader Users",
           route: {
-            name: "org-site-access-mgmt-hid-users",
+            name: "org-site-access-mgmt-administrator",
+            params: { org, site },
+          },
+        },
+        {
+          // The signed-in member's own pass, not somebody else's. Every other
+          // entry in this group acts on a resident or a visitor; this one has
+          // no subject but the caller.
+          title: "HID QR Code",
+          route: {
+            name: "org-site-access-mgmt-hid-qr-code",
             params: { org, site },
           },
         },

package/composables/useHidReaderSelection.ts

@@ -0,0 +1,50 @@
+import {
+  EMPTY_HID_READER_CHOICE,
+  resolveHidReaderId,
+  type HidReaderChoice,
+} from "../utils/hid-reader-selection";
+
+/**
+ * ONE HID READER CHOICE, SHARED BY EVERY HID SCREEN.
+ *
+ * Declared at MODULE scope on purpose. Each screen held its own `ref("")`, and
+ * because the HID screens are separate pages the ref was rebuilt on every
+ * navigation — HID Reader Users, HID Cards, Access Logs and HID QR Code each
+ * reset to the first reader no matter what had just been picked next door.
+ *
+ * A module-scoped ref is enough because moving between those pages is a ROUTE
+ * change, not a page load: the menu's items carry a `route` and
+ * `NavigationItem.vue` renders them through `:to`, so vue-router handles them
+ * and this module is never re-evaluated.
+ *
+ * Deliberately NOT persisted. `localStorage` would carry the choice through a
+ * hard refresh as well, which is a real but much smaller benefit than the
+ * navigation case, and it is worth adding only once somebody has felt the
+ * absence. See `utils/hid-reader-selection.ts` for the staleness rule that
+ * would have to hold either way.
+ *
+ * Intercom keeps its own reader and is not wired to this. Its question is which
+ * panel you are calling, not which door you are administering, and joining them
+ * would mean switching reader on Access Logs changed who you would dial.
+ */
+const choice = ref<HidReaderChoice>({ ...EMPTY_HID_READER_CHOICE });
+
+export default function useHidReaderSelection() {
+  /** Remember a choice. The site travels with it; an id alone means nothing. */
+  function selectHidReader(siteId: string, readerId: string) {
+    choice.value = { siteId: String(siteId ?? ""), readerId: String(readerId ?? "") };
+  }
+
+  /**
+   * The reader this screen should show, given the readers it just loaded.
+   *
+   * Call it after the reader list arrives, and write the answer back with
+   * `selectHidReader` so the screens agree on what "current" means even when
+   * one of them had to fall back to the first reader.
+   */
+  function resolveForSite(siteId: string, readers: readonly { _id?: unknown }[]) {
+    return resolveHidReaderId(siteId, readers, choice.value);
+  }
+
+  return { choice, selectHidReader, resolveForSite };
+}

package/composables/useMember.ts

@@ -70,6 +70,8 @@ export default function useMember() {
     status = "active",
     siteId = "",
     roleState = "",
+    /** A building unit id, or "none": members on no unit yet. */
+    unit = "",
     people = false,
   } = {}) {
     const query: Record<string, any> = { page, limit, type, status };
@@ -83,6 +85,7 @@ export default function useMember() {
     if (user) query.user = user;
     if (org) query.org = org;
     if (siteId) query.siteId = siteId;
+    if (unit) query.unit = unit;
     return useNuxtApp().$api<Record<string, any>>("/api/members", {
       method: "GET",
       query,
@@ -158,6 +161,14 @@ export default function useMember() {
     });
   }
 
+  /** Attach a member to a building unit, or detach them (`unit` ""). */
+  function updateMemberUnit(id: string, unit: string) {
+    return useNuxtApp().$api<Record<string, any>>("/api/members/unit", {
+      method: "PUT",
+      body: { id, unit },
+    });
+  }
+
   function getByUserTypeOrg(user: string, type: string, org: string) {
     return useNuxtApp().$api<TMember>(
       `/api/members/user/${user}/app/${type}/org`,
@@ -226,6 +237,7 @@ export default function useMember() {
     undoCrossSiteRoleFix,
     getSiteAccess,
     saveSiteAccess,
+    updateMemberUnit,
     members,
     member,
     page,

package/composables/usePeople.ts

@@ -115,6 +115,24 @@ export default function () {
     });
   }
 
+  /**
+   * The blocks, levels and units at a site that actually have an occupant.
+   * The other half of the unit picker: this narrows the cascade, then
+   * `getPeopleByUnit` answers "which person in this unit?".
+   */
+  async function getOccupiedStructure(
+    site: string,
+    { type = "", status = "active", block = "", level = "" } = {}
+  ) {
+    return await useNuxtApp().$api<Record<string, any>>(
+      `/api/people/site/${site}/occupied-structure`,
+      {
+        method: "GET",
+        query: { type, status, block, level },
+      }
+    );
+  }
+
   async function getPeopleByUnit(
     _id: string,
     { status = "active", type = "" } = {}
@@ -148,6 +166,7 @@ export default function () {
     findPersonByPlateNumberMultipleResult,
     findPersonByContact,
     getPeopleByUnit,
+    getOccupiedStructure,
     searchCompanyList,
     findUsersByPlateNumber,
     reviewResidentPerson,

package/composables/useServiceProvider.ts

@@ -15,6 +15,16 @@ export type TSiteProviderMember = {
   lastLoginAt?: string | null;
   /** a subcontractor: the provider that brought its company onto the site */
   invitedVia?: string;
+  /** The building unit this person is attached to (a unit's Management tab). */
+  unit?: string | null;
+  unitName?: string;
+  /**
+   * The person's user account. NOT yet returned by the endpoint — the
+   * repository projects it but the service layer drops it. Anything acting on
+   * the PERSON (assigning an access card writes it onto the card as `userId`)
+   * needs this rather than `_id`, which identifies the membership.
+   */
+  user?: string | null;
 };
 
 export type TSiteProviderCompany = {
@@ -90,6 +100,8 @@ export default function useServiceProvider() {
     status = "",
     /** "engagements": also providers engaged through an accepted invitation. */
     include = "",
+    /** A building unit id, or "none": providers on no unit yet. */
+    unit = "",
   } = {}) {
     return useNuxtApp().$api<Record<string, any>>("/api/service-providers", {
       method: "GET",
@@ -102,6 +114,7 @@ export default function useServiceProvider() {
         siteId,
         ...(status ? { status } : {}),
         ...(include ? { include } : {}),
+        ...(unit ? { unit } : {}),
       },
     });
   }
@@ -269,6 +282,17 @@ export default function useServiceProvider() {
     );
   }
 
+  /** Attach a provider to a building unit, or detach it (`unit` ""). */
+  async function updateUnit(id: string, unit: string) {
+    return useNuxtApp().$api<Record<string, any>>(
+      `/api/service-providers/${id}/unit`,
+      {
+        method: "PATCH",
+        body: { unit },
+      }
+    );
+  }
+
    async function getByEmail({
     email = "",
     orgId = "",
@@ -293,17 +317,29 @@ export default function useServiceProvider() {
    * Members > Service Providers: the provider people with access to this
    * site, and one entry per provider company with its head count. The
    * site's own organisation only - the server refuses anyone else.
+   * `unit`: a building unit id, or "none" (people on no unit yet).
    */
-  function getSiteMembers(siteId: string): Promise<{
+  function getSiteMembers(siteId: string, unit = ""): Promise<{
     items: TSiteProviderMember[];
     companies: TSiteProviderCompany[];
   }> {
     return useNuxtApp().$api("/api/service-providers/site-members", {
       method: "GET",
-      query: { siteId },
+      query: { siteId, ...(unit ? { unit } : {}) },
     });
   }
 
+  /** Attach one of those people to a building unit, or detach them (`unit` ""). */
+  function updateSiteMemberUnit(id: string, unit: string) {
+    return useNuxtApp().$api<Record<string, any>>(
+      `/api/service-providers/site-members/${id}/unit`,
+      {
+        method: "PATCH",
+        body: { unit },
+      }
+    );
+  }
+
   /** The same list as an Excel file, under the same filters. */
   function exportSiteMembers(
     siteId: string,
@@ -320,6 +356,7 @@ export default function useServiceProvider() {
 
   return {
     getSiteMembers,
+    updateSiteMemberUnit,
     exportSiteMembers,
     serviceProviders,
     serviceProvider,
@@ -338,6 +375,7 @@ export default function useServiceProvider() {
     add,
     addViaInvite,
     updateStatus,
+    updateUnit,
     getByEmail,
   };
 }

package/composables/useSiteCategory.ts

@@ -0,0 +1,45 @@
+/**
+ * THE CATEGORY OF THE SITE THE USER IS CURRENTLY IN.
+ *
+ * One shared answer, published once by the application's layout from the site
+ * it already loaded for the switcher, and read by anything that has to behave
+ * differently on a commercial or industrial site - the business Add Tenant
+ * form, the tenant list. Publishing it rather than re-fetching it per
+ * component means no two screens can disagree about which site this is.
+ *
+ * READ FROM THE CUSTOMER-SITE RECORD, NOT THE SITE RECORD. Both carry a
+ * `category` and `customer-site.service` keeps them equal (it writes the site
+ * on create and on update), but `siteSchema` DEFAULTS the site's own copy to
+ * `commercial` - so a site created without an explicit category reads back as
+ * commercial there even when it is a residential estate. The customer-site
+ * copy has no default: it is either the category somebody chose or nothing.
+ *
+ * An empty category means "not published yet" or "never set", and every
+ * caller must behave as it did before this existed - never assume commercial
+ * from silence.
+ */
+const BUSINESS_SITE_CATEGORIES: string[] = ["commercial", "industrial"];
+
+export default function useSiteCategory() {
+  const siteCategory = useState<string>("current-site-category", () => "");
+
+  function setSiteCategory(value?: string | null) {
+    siteCategory.value = typeof value === "string" ? value : "";
+  }
+
+  /**
+   * The categories whose units are LET TO A BUSINESS rather than lived in.
+   *
+   * These are the sites where a unit has an owner, an occupier and often a
+   * person in charge who is neither, so they are the sites that ask for a
+   * tenant's standing and print it back (see `OCCUPANCY_ROLE_OPTIONS`).
+   *
+   * The category never changes what the APPLICATION is called: the rail says
+   * Property Management on every site it serves.
+   */
+  const isBusinessSite = computed(() =>
+    BUSINESS_SITE_CATEGORIES.includes(siteCategory.value),
+  );
+
+  return { siteCategory, isBusinessSite, setSiteCategory };
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "4.82.0",
+  "version": "4.82.1-staging.469",
   "author": "7365admin1",
   "main": "./nuxt.config.ts",
   "//files": "What a consumer extending this layer actually loads. Without this npm ships the whole working tree - the changesets, the CI workflows, the render harness in tools/ and any scratch directory that happened to exist at publish time. Nuxt resolves a layer by directory, so every runtime directory below has to stay listed; adding a new top-level runtime directory means adding it here too.",

package/pages/[org]/[site]/access-mgmt/administrator/index.vue

@@ -5,7 +5,7 @@
       :org="orgId"
       message="Enable HID as a service for this site before managing HID users."
     >
-      <HidUserEnrollment :site="siteId" />
+      <HidUserEnrollment :site="siteId" :org="orgId" />
     </HidEnabledGate>
   </v-container>
 </template>

package/pages/[org]/[site]/access-mgmt/hid-cards/index.vue

@@ -5,7 +5,7 @@
       :org="orgId"
       message="Enable HID as a service for this site before managing physical HID cards."
     >
-      <HidUserEnrollment :site="siteId" card-management />
+      <HidUserEnrollment :site="siteId" :org="orgId" card-management />
     </HidEnabledGate>
   </v-container>
 </template>

package/pages/[org]/[site]/access-mgmt/hid-qr-code/index.vue

@@ -0,0 +1,23 @@
+<template>
+  <v-container fluid>
+    <HidEnabledGate
+      :site="siteId"
+      :org="orgId"
+      message="Enable HID as a service for this site before generating a QR code."
+    >
+      <HidProfileQrCode :site="siteId" />
+    </HidEnabledGate>
+  </v-container>
+</template>
+
+<script setup lang="ts">
+definePageMeta({
+  layout: "default",
+  middleware: ["01-auth", "02-org"],
+  memberOnly: true,
+});
+
+const route = useRoute();
+const siteId = computed(() => String(route.params.site ?? ""));
+const orgId = computed(() => String(route.params.org ?? ""));
+</script>

package/pages/[org]/[site]/access-mgmt/hid-readers/index.vue

@@ -5,7 +5,7 @@
       :org="orgId"
       message="Enable HID as a service for this site before managing HID readers."
     >
-      <HidReaderManagement :site="siteId" />
+      <HidReaderManagement :site="siteId" :org="orgId" />
     </HidEnabledGate>
   </v-container>
 </template>

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/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.`;
+}