@7365admin1/layer-common 4.82.1-staging.475 → 4.83.0

package/utils/hid-enrolment-subject.ts

@@ -1,144 +0,0 @@
-/**
- * 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

@@ -1,190 +0,0 @@
-/**
- * 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

@@ -1,52 +0,0 @@
-/**
- * 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

@@ -1,109 +0,0 @@
-/**
- * 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/sanitize-html.ts

@@ -1,16 +0,0 @@
-import DOMPurify from "dompurify";
-
-/**
- * The one way rich text typed by a user (announcements, facility descriptions,
- * policies) reaches `v-html`. Keeps formatting, drops scripts, event handlers,
- * `javascript:` links and embedded frames/forms. Browser-only (the apps are
- * `ssr: false`); without a DOM it returns "" rather than unsanitised HTML.
- */
-export function sanitizeHtml(html: unknown): string {
-  if (html === null || html === undefined || html === "") return "";
-  if (typeof window === "undefined" || !DOMPurify.isSupported) return "";
-  return DOMPurify.sanitize(String(html), {
-    USE_PROFILES: { html: true },
-    FORBID_TAGS: ["style", "form", "input", "button", "iframe", "object", "embed"],
-  });
-}

package/utils/security-headers.ts

@@ -1,52 +0,0 @@
-/**
- * Response headers every web app sends, on the HTML shell (Nitro route rules)
- * and on the static files (nitro writes the same rules into Cloudflare's
- * `_headers`). One list, so the eleven apps cannot drift apart.
- *
- * The ENFORCED Content-Security-Policy only carries the directives that cannot
- * break a screen: who may frame us (clickjacking), no plugins, no <base> swap.
- * The full policy ships as Report-Only first: the apps load Google Fonts,
- * camera players and documents in iframes, sockets and the Spaces CDN, and a
- * wrong guess there blanks a page. Violations show in the browser console;
- * once a release runs clean, move it to the enforced header.
- *
- * HSTS deliberately has no `preload`: preload is decided for the whole
- * iservice365.org domain at the apex and is hard to undo (owner/leads action).
- */
-export const CSP_ENFORCED = [
-  "frame-ancestors 'self'",
-  "object-src 'none'",
-  "base-uri 'self'",
-].join("; ");
-
-export const CSP_REPORT_ONLY = [
-  "default-src 'self'",
-  "script-src 'self'",
-  "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
-  "font-src 'self' data: https://fonts.gstatic.com",
-  "img-src 'self' data: blob: https:",
-  "media-src 'self' blob: https:",
-  "connect-src 'self' https: wss:",
-  "frame-src 'self' https:",
-  "worker-src 'self' blob:",
-  "object-src 'none'",
-  "base-uri 'self'",
-  "frame-ancestors 'self'",
-  "form-action 'self' https:",
-  "upgrade-insecure-requests",
-].join("; ");
-
-export const SECURITY_HEADERS: Record<string, string> = {
-  "strict-transport-security": "max-age=31536000; includeSubDomains",
-  "x-content-type-options": "nosniff",
-  "x-frame-options": "SAMEORIGIN",
-  "referrer-policy": "strict-origin-when-cross-origin",
-  // camera/mic: QR scan, photo capture; geolocation: attendance;
-  // usb/serial/hid: card readers (useWebUsb). Everything else is off.
-  "permissions-policy":
-    "camera=(self), microphone=(self), geolocation=(self), usb=(self), serial=(self), hid=(self), payment=(self), display-capture=(self), bluetooth=(), midi=(), magnetometer=(), gyroscope=(), accelerometer=()",
-  // allow-popups: payment and document windows we open keep working.
-  "cross-origin-opener-policy": "same-origin-allow-popups",
-  "content-security-policy": CSP_ENFORCED,
-  "content-security-policy-report-only": CSP_REPORT_ONLY,
-};

package/utils/service-type.ts

@@ -1,30 +0,0 @@
-/**
- * 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;
-}