@7365admin1/layer-common 4.119.0 → 4.121.0

package/utils/feedback-handling-settings.ts

@@ -0,0 +1,139 @@
+/**
+ * Site Settings -> "Feedback handling" (TLR, 2026-10-13): the form behind
+ * `FeedbackHandlingSettings.vue`, stored on the site as
+ * `metadata.feedbackSettings` and validated by core
+ * (`site-feature-settings.util.ts`).
+ *
+ * A site that never saved this reads as: Mon-Fri 09:00-18:00, holidays not
+ * excluded, no routes, escalation off, nothing auto-closed - which is exactly
+ * today's behaviour, because the server does nothing without a route, an
+ * enabled escalation or a listed category.
+ */
+
+export type TFeedbackWindowTarget = "ma" | "provider";
+
+export type TFeedbackRouteForm = {
+  category: string;
+  provider: string;
+  officeHours: TFeedbackWindowTarget;
+  afterHours: TFeedbackWindowTarget;
+};
+
+/** `id` is the level's stable key (set by the server on its first save; "" for a new step). */
+export type TEscalationLevelForm = { id: string; afterHours: number | string; users: string[]; emails: string[] };
+
+export type TFeedbackHandlingForm = {
+  workingDays: number[];
+  officeStart: string;
+  officeEnd: string;
+  excludePublicHolidays: boolean;
+  routes: TFeedbackRouteForm[];
+  escalationEnabled: boolean;
+  workingTimeOnly: boolean;
+  levels: TEscalationLevelForm[];
+  autoCloseCategories: string[];
+};
+
+export const MAX_ESCALATION_LEVELS = 5;
+
+/** Mon first, as people read a week. `value` is the stored 0 = Sunday. */
+export const WEEK_DAYS = [
+  { title: "Mon", value: 1 },
+  { title: "Tue", value: 2 },
+  { title: "Wed", value: 3 },
+  { title: "Thu", value: 4 },
+  { title: "Fri", value: 5 },
+  { title: "Sat", value: 6 },
+  { title: "Sun", value: 0 },
+];
+
+const HHMM = /^([01]\d|2[0-3]):[0-5]\d$/;
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const OBJECT_ID = /^[a-f0-9]{24}$/i;
+
+const list = (v: unknown) => (Array.isArray(v) ? v : []);
+
+/** The stored value (or nothing) as the form. */
+export function feedbackHandlingForm(stored: any): TFeedbackHandlingForm {
+  const s = stored && typeof stored === "object" ? stored : {};
+  const days = list(s.workingDays).filter((d: unknown) => Number.isInteger(d) && (d as number) >= 0 && (d as number) <= 6);
+  return {
+    workingDays: days.length ? days : [1, 2, 3, 4, 5],
+    officeStart: HHMM.test(s.officeStart) ? s.officeStart : "09:00",
+    officeEnd: HHMM.test(s.officeEnd) ? s.officeEnd : "18:00",
+    excludePublicHolidays: s.excludePublicHolidays === true,
+    routes: list(s.routes).map((r: any) => ({
+      category: String(r?.category ?? ""),
+      provider: r?.provider ? String(r.provider) : "",
+      officeHours: r?.officeHours === "provider" ? "provider" : "ma",
+      afterHours: r?.afterHours === "provider" ? "provider" : "ma",
+    })),
+    escalationEnabled: s.escalation?.enabled === true,
+    workingTimeOnly: s.escalation?.workingTimeOnly === true,
+    levels: list(s.escalation?.levels).map((l: any) => ({
+      id: typeof l?.id === "string" ? l.id : "",
+      afterHours: Number(l?.afterHours) || 1,
+      users: list(l?.users).map(String),
+      emails: list(l?.emails).map(String),
+    })),
+    autoCloseCategories: list(s.autoCloseCategories).map(String),
+  };
+}
+
+/** Plain-English problems that stop a save; empty = fine. */
+export function feedbackHandlingErrors(form: TFeedbackHandlingForm): string[] {
+  const errors: string[] = [];
+  if (!form.workingDays.length) errors.push("Pick at least one office day.");
+  if (!HHMM.test(form.officeStart) || !HHMM.test(form.officeEnd) || form.officeEnd <= form.officeStart)
+    errors.push("Office hours must end after they start.");
+  const seen = new Set<string>();
+  form.routes.forEach((r, i) => {
+    const row = `Row ${i + 1}`;
+    if (!r.category.trim()) errors.push(`${row}: choose a category.`);
+    else if (seen.has(r.category.trim().toLowerCase())) errors.push(`${row}: ${r.category} is listed twice.`);
+    seen.add(r.category.trim().toLowerCase());
+    if ((r.officeHours === "provider" || r.afterHours === "provider") && !OBJECT_ID.test(r.provider))
+      errors.push(`${row}: choose which provider receives it.`);
+  });
+  if (form.escalationEnabled) {
+    if (!form.levels.length) errors.push("Add at least one escalation step, or turn escalation off.");
+    if (form.levels.length > MAX_ESCALATION_LEVELS) errors.push(`At most ${MAX_ESCALATION_LEVELS} escalation steps.`);
+    form.levels.forEach((l, i) => {
+      const step = `Step ${i + 1}`;
+      const hours = Number(l.afterHours);
+      if (!Number.isFinite(hours) || hours < 1 || hours > 1440) errors.push(`${step}: hours must be between 1 and 1440.`);
+      if (!l.users.length && !l.emails.length) errors.push(`${step}: choose somebody to notify.`);
+      for (const e of l.emails) if (!EMAIL.test(e.trim())) errors.push(`${step}: "${e}" is not an email address.`);
+    });
+  }
+  return errors;
+}
+
+/** The form as the stored `metadata.feedbackSettings` value. */
+export function feedbackSettingsFromForm(form: TFeedbackHandlingForm) {
+  return {
+    workingDays: [...form.workingDays].sort((a, b) => a - b),
+    officeStart: form.officeStart,
+    officeEnd: form.officeEnd,
+    excludePublicHolidays: form.excludePublicHolidays,
+    routes: form.routes.map((r) => ({
+      category: r.category.trim(),
+      officeHours: r.officeHours,
+      afterHours: r.afterHours,
+      provider: r.officeHours === "provider" || r.afterHours === "provider" ? r.provider : null,
+    })),
+    escalation: {
+      enabled: form.escalationEnabled,
+      workingTimeOnly: form.workingTimeOnly,
+      // A step keeps its id so a re-ordered or edited step is not sent again;
+      // a new step has none and the server gives it one.
+      levels: form.levels.map((l) => ({
+        ...(l.id ? { id: l.id } : {}),
+        afterHours: Number(l.afterHours),
+        users: [...new Set(l.users)],
+        emails: [...new Set(l.emails.map((e) => e.trim().toLowerCase()))],
+      })),
+    },
+    autoCloseCategories: [...new Set(form.autoCloseCategories)],
+  };
+}

package/utils/inventory-presets.ts

@@ -56,8 +56,50 @@ export const INVENTORY_PRESETS: TPermissionPreset[] = [
   },
 ];
 
-/** Presets per module key; only inventory has them today. */
-export const PERMISSION_PRESETS: Record<string, TPermissionPreset[]> = { inventory: INVENTORY_PRESETS };
+/**
+ * Security Ops in plain words: the two jobs the module actually has.
+ *
+ * WHY A PRESET AND NOT A NEW PERMISSION. Neither of these is a new right: both
+ * sets are made of strings that already exist. The preset only spares somebody
+ * hunting a permission tree, and that matters here because the alternative
+ * people reach for is a wildcard role, which is how a service provider's
+ * administrator ends up supervising a security site.
+ *
+ * GEOFENCING IS NOT IN EITHER SET, and cannot be: `applyPermissionPreset` is
+ * scoped to one resource, and `manage-geofence` belongs to `site-settings`.
+ * That matters because the owner's definition of a head of security
+ * (2026-10-13) is this permission AND geofencing, and the server reads exactly
+ * that pair to decide who is told when an action is raised or sent for
+ * verification. So the preset's description has to send the administrator to
+ * tick the other box, rather than quietly leaving the job half done.
+ *
+ * `start-site-visit` is deliberately NOT in the head of security set: it is the
+ * right to go and do a visit, and somebody who never walks a site should not
+ * have to hold it to be told what is happening on one. Holding it as well does
+ * not disqualify them.
+ */
+export const SECURITY_OPS_PRESETS: TPermissionPreset[] = [
+  {
+    key: "officer",
+    label: "Security Ops officer",
+    description:
+      "Goes to the site, works through the visit checklists and checks out. Sees their own work.",
+    actions: ["start-site-visit"],
+  },
+  {
+    key: "head",
+    label: "Head of security",
+    description:
+      "Sees every officer's visits and actions. Also tick Manage geofencing under Site settings: that pair is what decides who is told when an action is raised or sent for verification.",
+    actions: ["see-all-site-visits"],
+  },
+];
+
+/** Presets per module key. */
+export const PERMISSION_PRESETS: Record<string, TPermissionPreset[]> = {
+  inventory: INVENTORY_PRESETS,
+  "security-ops": SECURITY_OPS_PRESETS,
+};
 
 /**
  * The permission list with `resource`'s grants replaced by `preset`'s actions --
@@ -143,3 +185,67 @@ export function inventoryControls(a?: Partial<TInventoryAccess> | null) {
     unitPrice: c.canManage || c.canApprove || c.canHandle || c.canReports,
   };
 }
+
+/**
+ * Whole-role starting points (TLR A7), offered in the create-role dialog when
+ * the catalogue has every module they use. Keys are the security catalogue's
+ * own (`composables/useSecurityPermission.ts`). Applying one REPLACES the
+ * ticks in the dialog and saves nothing; the admin adjusts and saves.
+ */
+export type TRolePreset = {
+  key: string;
+  label: string;
+  description: string;
+  permissions: string[];
+};
+
+/**
+ * The Guardhouse officer's grants, by module, in the same nested form as the
+ * security catalogue that offers them (`useSecurityPermission.ts`). A grant
+ * list, not a check: `constants/permissions.ts` (what this package CHECKS)
+ * deliberately has no Passes & Keys entry, so the role editors there gain no
+ * extra checkbox.
+ */
+const GUARDHOUSE_OFFICER: Record<string, string[]> = {
+  // check-out is a visitor update on the server
+  "visitor-mgmt": ["add-visitor", "see-all-visitor", "see-visitor-details", "update-visitor"],
+  "daily-occurrence-books": ["see-all-daily-occurrence", "see-daily-occurrence-details"],
+  "daily-occurrence-entries": ["add-daily-occurrence-entries", "see-daily-occurrence-entries-details"],
+  "incident-reports": ["add-incident-report", "see-incident-reports", "see-incident-report-details"],
+  feedbacks: ["add-feedback", "see-all-feedback", "see-feedback-details"],
+  // issuing and taking back a key is a pass/key update on the server
+  "passes-and-keys-mgmt": ["see-all-passes-and-keys", "update-passes-and-keys"],
+};
+
+const grants = (byModule: Record<string, string[]>) =>
+  Object.entries(byModule).flatMap(([resource, actions]) => actions.map((action) => [resource, action].join(":")));
+
+export const ROLE_PRESETS: TRolePreset[] = [
+  {
+    key: "guardhouse-officer",
+    label: "Guardhouse officer",
+    description:
+      "Register, see and check out visitors; fill in the daily occurrence book; raise and view incident reports and feedback; issue and take back passes and keys. No delete rights.",
+    permissions: grants(GUARDHOUSE_OFFICER),
+  },
+];
+
+/**
+ * The dialog state for `preset` against the offered catalogue, or null when
+ * the catalogue lacks any of it. Never returns an empty list: an empty
+ * permission list means "everything" on the server.
+ */
+export function applyRolePreset(
+  catalogue: Record<string, Record<string, unknown> | undefined>,
+  preset: TRolePreset,
+): { selected: string[]; enabled: string[] } | null {
+  const offered = preset.permissions.every((p) => {
+    const [resource, action] = p.split(":");
+    return Boolean(catalogue?.[resource]?.[action]);
+  });
+  if (!offered || !preset.permissions.length) return null;
+  return {
+    selected: [...preset.permissions],
+    enabled: [...new Set(preset.permissions.map((p) => p.split(":")[0]))],
+  };
+}

package/utils/key-presses.ts

@@ -0,0 +1,55 @@
+/**
+ * Key presses (cabinets) and the Passes & keys site switches (TLR B8 / D2).
+ * Stored on the site as `metadata.keySettings`; read with the same defaults
+ * as core's `getKeySettings`, so a site that never saved anything reads as
+ * today: no presses, no daily list, check-out never blocked by the server.
+ */
+export type TKeyPress = { id: string; name: string };
+
+export type TKeySettings = {
+  cabinets: TKeyPress[];
+  dailyUnreturnedAlert: boolean;
+  alertTime: string;
+  blockCheckoutWithKeys: boolean;
+};
+
+export function readKeySettings(site: any): TKeySettings {
+  const k = site?.metadata?.keySettings ?? {};
+  return {
+    cabinets: Array.isArray(k.cabinets)
+      ? k.cabinets.filter((c: any) => c && typeof c.id === "string" && typeof c.name === "string")
+      : [],
+    dailyUnreturnedAlert: k.dailyUnreturnedAlert === true,
+    alertTime: typeof k.alertTime === "string" && /^([01]\d|2[0-3]):[0-5]\d$/.test(k.alertTime) ? k.alertTime : "18:00",
+    blockCheckoutWithKeys: k.blockCheckoutWithKeys === true,
+  };
+}
+
+/** The press's name, or "" when the key has none (or one since removed). */
+export function keyPressName(cabinets: TKeyPress[], id?: string | null): string {
+  if (!id) return "";
+  return cabinets.find((c) => c.id === id)?.name ?? "";
+}
+
+/**
+ * The list as saved: names trimmed, empty rows dropped, and an id for each new
+ * row made from its name (lowercase letters, digits and dashes, unique). An
+ * existing row keeps its id, so renaming a press keeps every key in it.
+ */
+export function cleanKeyPresses(rows: Array<{ id?: string; name?: string }>): TKeyPress[] {
+  const out: TKeyPress[] = [];
+  const taken = new Set(rows.map((r) => r.id).filter(Boolean) as string[]);
+  for (const row of rows) {
+    const name = String(row.name ?? "").trim().slice(0, 60);
+    if (!name) continue;
+    let id = row.id;
+    if (!id) {
+      const base = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 34) || "press";
+      id = base;
+      for (let n = 2; taken.has(id); n++) id = `${base}-${n}`;
+      taken.add(id);
+    }
+    out.push({ id, name });
+  }
+  return out;
+}

package/utils/list-export.ts

@@ -0,0 +1,39 @@
+/**
+ * CSV download of a list screen (TLR B6): the rows the list itself can read,
+ * through the same list API and filters, paged through to the end. Browser-safe.
+ */
+import { toCsv } from "./attendance-proxy.ts";
+
+export type TExportColumn = { title: string; value: (row: any) => unknown };
+
+/** Largest page the list APIs accept (core feedback / work-order: max 100). */
+export const EXPORT_PAGE_SIZE = 100;
+/** ponytail: hard cap, so one click never pulls an estate's whole history; raise or add a server export if hit. */
+export const EXPORT_MAX_ROWS = 5000;
+
+/**
+ * Every row from `fetchPage(1..n)`, stopping at the last page, an empty page,
+ * or `maxRows`. `fetchPage` returns the list API's `{ items, pages }`.
+ */
+export async function collectAllPages(
+  fetchPage: (page: number, limit: number) => Promise<{ items?: any[]; pages?: number } | null | undefined>,
+  maxRows = EXPORT_MAX_ROWS,
+  limit = EXPORT_PAGE_SIZE,
+): Promise<{ rows: any[]; truncated: boolean }> {
+  const rows: any[] = [];
+  for (let page = 1; rows.length < maxRows; page++) {
+    const res = await fetchPage(page, limit);
+    const items = Array.isArray(res?.items) ? res!.items : [];
+    rows.push(...items);
+    const last = Number(res?.pages) || 0;
+    if (!items.length || page >= last) return { rows: rows.slice(0, maxRows), truncated: rows.length > maxRows };
+  }
+  return { rows: rows.slice(0, maxRows), truncated: true };
+}
+
+export function listCsv(columns: TExportColumn[], rows: any[]): string {
+  return toCsv(
+    columns.map((c) => c.title),
+    rows.map((row) => columns.map((c) => c.value(row))),
+  );
+}

package/utils/notification-target.ts

@@ -204,6 +204,16 @@ const SITE_PAGES: Record<string, TSitePage[]> = {
   robotAlert: [{ apps: ["security", "property-management", "hygiene"], page: () => "robot-management/alerts" }],
   // hygiene has its Service Providers page too since 2026-09-28
   serviceProviderInviteAnswer: [{ apps: SERVICE_APPS, page: () => "service-providers" }],
+  /**
+   * Security Ops: an action was raised, sent for verification, signed off,
+   * reopened, or went overdue. Lands on the Ops Review page, which is where the
+   * register is read.
+   *
+   * WITHOUT THIS ENTRY THE ROW IS A DEAD END. `notificationTarget` answers null
+   * for a kind it has no page for, so every overdue escalation ever written has
+   * opened nothing at all. Adding it repairs those too, not only the new alerts.
+   */
+  "security-ops": [{ apps: ["security"], page: () => "security-ops" }],
 };
 SITE_PAGES.myVisitors = SITE_PAGES.visitors;
 

package/utils/site-access.ts

@@ -8,7 +8,7 @@ export type SiteAccessRole = { _id: string; name: string; type?: string; scope?:
 export type SiteAccessRow = {
   site: string;
   name: string;
-  membership: { role: string; roleName?: string } | null;
+  membership: { role: string; roleName?: string; securityOps?: boolean } | null;
   roles: SiteAccessRole[];
 };
 export type SiteChoice = { site: string; name: string; on: boolean; role: string; roles: SiteAccessRole[]; replacedRole?: string };
@@ -31,6 +31,18 @@ export function initialChoices(rows: SiteAccessRow[]): SiteChoice[] {
   });
 }
 
+/**
+ * Is this person already marked as Security Ops?
+ *
+ * ONE ANSWER FOR THE WHOLE PERSON, because that is the question the switch
+ * asks: an officer is an officer everywhere they are sent. Any marked site
+ * means yes, so a person whose rows disagree (only reachable by an older client
+ * or a hand edit) reads as marked, and saving settles every row to one value.
+ */
+export function initialSecurityOps(rows: SiteAccessRow[]): boolean {
+  return (rows ?? []).some((r) => Boolean(r.membership?.securityOps));
+}
+
 /** One site's Role list: "Organisation roles" first, then "<Site> roles". */
 export function roleItems(choice: Pick<SiteChoice, "name" | "roles">): RoleItem[] {
   const org = choice.roles.filter(isOrgRole);