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

package/composables/useHidAmico.ts

@@ -28,6 +28,22 @@ export type HidReaderPayload = {
   lastCallbackType?: string;
 };
 
+export type HidProfileQr = {
+  readerId: string;
+  userId: string;
+  memberId: string;
+  hidUserId: string;
+  registration: string;
+  readerName: string;
+  portalName: string;
+  qrEnabled: boolean;
+  issued: boolean;
+  qrValue: string;
+  issuedAt: string;
+  /** null when the permission lookup itself failed, so "unknown" stays distinct from "no". */
+  assigned: boolean | null;
+};
+
 type HidIdentityPayload = {
   site?: string;
   hidUserId?: string | number;
@@ -139,6 +155,28 @@ export type HidSipAccountData = {
   provisionedAt: string;
 };
 
+/** One row of the site's SIP account list - who owns the extension, never its password. */
+export type HidSipAccountListItem = {
+  _id: string;
+  userId: string;
+  name: string;
+  email: string;
+  /**
+   * What the owner is called after their name on the contact list: their
+   * "Blk 1/Level 1/Unit 1" when they live here, and their membership type -
+   * "Security Agency" - when they do not. "" only when the site knows neither.
+   *
+   * Optional because an API still on the `@7365admin1/core` release that
+   * predates it answers without the field; the contact picker falls back to the
+   * bare name rather than showing a dangling separator.
+   */
+  unitLabel?: string;
+  extension: string;
+  username: string;
+  status: string;
+  provisionedAt: string;
+};
+
 /**
  * True only for the specific validation error an API that predates core #1878
  * returns when the discover body carries `site`. Deliberately narrow: after
@@ -166,6 +204,36 @@ export default function useHidAmico() {
     });
   }
 
+  /**
+   * The signed-in member's own QR code on one reader.
+   *
+   * No user id in the path: the server takes the caller from the session, so
+   * these cannot be pointed at somebody else. `assigned` in the response says
+   * whether the HID permissions screen actually admits this member to the
+   * reader - issuing a code does not grant access, and the screen has to be
+   * able to say so.
+   */
+  function getProfileQr(readerId: string) {
+    return useNuxtApp().$api<{ data: HidProfileQr }>(
+      `${basePath}/readers/${readerId}/profile-qr`,
+      { method: "GET" },
+    );
+  }
+
+  function issueProfileQr(readerId: string) {
+    return useNuxtApp().$api<{ data: HidProfileQr }>(
+      `${basePath}/readers/${readerId}/profile-qr`,
+      { method: "POST" },
+    );
+  }
+
+  function deleteProfileQr(readerId: string) {
+    return useNuxtApp().$api<{ data: HidProfileQr }>(
+      `${basePath}/readers/${readerId}/profile-qr`,
+      { method: "DELETE" },
+    );
+  }
+
   function createReader(payload: HidReaderPayload) {
     return useNuxtApp().$api<HidApiRecord>(`${basePath}/readers`, {
       method: "POST",
@@ -257,6 +325,36 @@ export default function useHidAmico() {
     });
   }
 
+  /**
+   * Which credentials a reader accepts at the door.
+   *
+   * Separate from `setReaderConfiguration` on purpose. That one is the generic
+   * configuration endpoint, gated by an allowlist of writable objects; this is
+   * a dedicated route that validates the four methods against the reader's own
+   * `capabilities` and confirms the write by reading the device back, so a
+   * refusal here names the credential the hardware would not take.
+   */
+  function setReaderIdentificationMethods(readerId: string, payload: HidApiRecord) {
+    return useNuxtApp().$api<HidApiRecord>(
+      `${basePath}/readers/${readerId}/identification-methods`,
+      { method: "PUT", body: payload },
+    );
+  }
+
+  /**
+   * Put a reader back to the settings iService holds for it.
+   *
+   * A POST rather than a GET because it WRITES: reading the reader's
+   * configuration is only the first half, and anything that drifted is
+   * re-applied before this returns.
+   */
+  function reconcileReaderIdentificationMethods(readerId: string) {
+    return useNuxtApp().$api<HidApiRecord>(
+      `${basePath}/readers/${readerId}/identification-methods/reconcile`,
+      { method: "POST" },
+    );
+  }
+
   function getIdentities(readerId: string, query: HidApiRecord = {}) {
     return useNuxtApp().$api<HidApiRecord>(`${basePath}/readers/${readerId}/identities`, {
       method: "GET",
@@ -414,6 +512,27 @@ export default function useHidAmico() {
     );
   }
 
+  function getUserPasswordStatus(readerId: string, hidUserId: string | number) {
+    return useNuxtApp().$api<HidApiRecord>(
+      `${basePath}/readers/${readerId}/users/${hidUserId}/password`,
+      { method: "GET" },
+    );
+  }
+
+  function setUserPassword(readerId: string, hidUserId: string | number, password: string) {
+    return useNuxtApp().$api<HidApiRecord>(
+      `${basePath}/readers/${readerId}/users/${hidUserId}/password`,
+      { method: "PUT", body: { password } },
+    );
+  }
+
+  function deleteUserPassword(readerId: string, hidUserId: string | number) {
+    return useNuxtApp().$api<HidApiRecord>(
+      `${basePath}/readers/${readerId}/users/${hidUserId}/password`,
+      { method: "DELETE" },
+    );
+  }
+
   function deleteUserPin(readerId: string, hidUserId: string | number) {
     return useNuxtApp().$api<{ data: { pinEnrolled: boolean } }>(
       `${basePath}/readers/${readerId}/users/${hidUserId}/pin`,
@@ -474,6 +593,42 @@ export default function useHidAmico() {
     );
   }
 
+  /**
+   * The site's SIP accounts for the intercom contact picker. Site-scoped only:
+   * the organisation never decided who may read this — the site guard does —
+   * and sending one narrowed the list on a customer site whose accounts were
+   * provisioned by a managing agent.
+   */
+  function getSipAccounts(siteId: string) {
+    return useNuxtApp().$api<{ data: HidSipAccountListItem[] }>(
+      `${basePath}/sites/${siteId}/intercom/sip-accounts`,
+      { method: "GET" },
+    );
+  }
+
+  /**
+   * Wake the resident's phone for a call the web phone has just placed.
+   *
+   * The SIP INVITE is the call and travels over the WebSocket, not through the
+   * API; this only rings the resident's mobile so somebody is there to answer
+   * it. It is therefore fired after the INVITE and never awaited in a way that
+   * could fail the call — see `startWebCall` in `HidIntercomManagement.vue`.
+   *
+   * `notified: false` with a reason is a normal response, not an error: staff
+   * extensions and external SIP addresses have no resident behind them.
+   */
+  function notifyIntercomCall(
+    siteId: string,
+    payload: { orgId: string; destination: string; callId: string; readerId?: string },
+  ) {
+    return useNuxtApp().$api<{
+      data: { notified: boolean; delivered?: number; reason?: string };
+    }>(
+      `${basePath}/sites/${siteId}/intercom/notify-call`,
+      { method: "POST", body: payload },
+    );
+  }
+
   function getPermissionCandidates(
     siteId: string,
     query: {
@@ -505,6 +660,9 @@ export default function useHidAmico() {
 
   return {
     getReaders,
+    getProfileQr,
+    issueProfileQr,
+    deleteProfileQr,
     discoverReader,
     createReader,
     updateReader,
@@ -519,6 +677,8 @@ export default function useHidAmico() {
     issueVisitorQr,
     getReaderConfiguration,
     setReaderConfiguration,
+    setReaderIdentificationMethods,
+    reconcileReaderIdentificationMethods,
     getLogs,
     setUserImage,
     deleteUserImage,
@@ -530,6 +690,9 @@ export default function useHidAmico() {
     getUserPinStatus,
     setUserPin,
     deleteUserPin,
+    getUserPasswordStatus,
+    setUserPassword,
+    deleteUserPassword,
     getIdentities,
     getReaderUsers,
     getReaderAccessLogs,
@@ -540,6 +703,8 @@ export default function useHidAmico() {
     makeIntercomCall,
     finalizeIntercomCall,
     ensureSipAccount,
+    getSipAccounts,
+    notifyIntercomCall,
     getSitePermissions,
     getPermissionCandidates,
     updateSitePermissions,

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/composables/useStaffView.ts

@@ -0,0 +1,49 @@
+/**
+ * "OPEN AS SEVEN365 STAFF" (owner, 2026-10-01).
+ *
+ * The server holds the open view against the session (`staff-view:<sid>`), so
+ * this only READS it - nothing here can open one or widen anything. Read once
+ * per page load; Exit clears it on the server and here.
+ */
+const BASE = "/api/users/staff-access";
+
+/** What a staff member is given inside the client they opened: full setup, like the client's owner. */
+export const STAFF_VIEW_ROLE = Object.freeze({
+  name: "Seven365 staff",
+  permissions: ["*"],
+}) as unknown as TRole;
+
+/** Does the open view cover this route's organisation? */
+export function staffViewCovers(view: TStaffView | null | undefined, org: string): boolean {
+  return !!view?.org && !!org && view.org === org;
+}
+
+export default function useStaffView() {
+  const staffView = useState<TStaffView | null>("staff-view", () => null);
+  const staffViewLoaded = useState<boolean>("staff-view-loaded", () => false);
+
+  async function loadStaffView(force = false): Promise<TStaffView | null> {
+    if (staffViewLoaded.value && !force) return staffView.value;
+    try {
+      const res = await useNuxtApp().$api<{ view?: TStaffView | null }>(`${BASE}/view`, {
+        method: "GET",
+        timeout: 5000,
+      });
+      staffView.value = res?.view ?? null;
+    } catch {
+      // No view is the safe answer: staff simply see what they saw before.
+      staffView.value = null;
+    }
+    staffViewLoaded.value = true;
+    return staffView.value;
+  }
+
+  async function exitStaffView(): Promise<string> {
+    const org = staffView.value?.org ?? "";
+    await useNuxtApp().$api(`${BASE}/view/exit`, { method: "POST" });
+    staffView.value = null;
+    return org;
+  }
+
+  return { staffView, staffViewLoaded, loadStaffView, exitStaffView };
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "4.82.0",
+  "version": "4.82.1-staging.470",
   "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>