@7365admin1/layer-common 4.118.10 → 4.120.0

package/composables/useDataRetention.ts

@@ -0,0 +1,43 @@
+/**
+ * PDPA data retention per site (`/api/data-retention`, API-core). The setting
+ * itself is one site switch (`metadata.dataRetention`, useSiteFeatureSettings).
+ * Documents are not part of data retention in this version.
+ */
+export type TRetentionRule = { dataType: string; keepMonths: number };
+
+export const RETENTION_TYPES = [
+  { value: "visitors", label: "Visitor records" },
+  { value: "feedback", label: "Feedback" },
+  { value: "work-orders", label: "Work orders" },
+  { value: "incident-reports", label: "Incident reports" },
+  { value: "occurrence-books", label: "Occurrence books" },
+  { value: "attendance", label: "Attendance" },
+] as const;
+
+export default function useDataRetention() {
+  const api = () => useNuxtApp().$api;
+
+  /** Read-only counts of what the given (or saved) rules would remove today. */
+  function previewDataRetention(site: string, body: { rules?: TRetentionRule[] } = {}) {
+    return api()<Record<string, any>>("/api/data-retention/preview", { method: "POST", body: { site, ...body } });
+  }
+
+  function listDataPurgeRecords(site: string) {
+    return api()<Record<string, any>>("/api/data-retention/records", { method: "GET", query: { site } });
+  }
+
+  async function downloadDataPurgeCertificate(site: string, id: string) {
+    const res = await api()<Blob>(`/api/data-retention/records/${id}/certificate`, { method: "GET", query: { site } });
+    if (!res) throw new Error("Could not download the certificate.");
+    const url = window.URL.createObjectURL(res);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `data-removal-record-${id}.pdf`;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    window.URL.revokeObjectURL(url);
+  }
+
+  return { previewDataRetention, listDataPurgeRecords, downloadDataPurgeCertificate };
+}

package/composables/useDocument.ts

@@ -7,6 +7,7 @@ export default function useDocument() {
     site = "",
     parentId = "",
     expiry = "all",
+    archived = false,
   }: {
     page?: number;
     search?: string;
@@ -19,6 +20,8 @@ export default function useDocument() {
      * Document (Expired). Defaults to "all" so existing callers are unaffected.
      */
     expiry?: string;
+    /** The Archived tab (core document archive). Left out = the normal lists. */
+    archived?: boolean;
   } = {}) {
     const query: Record<string, any> = {
       page,
@@ -28,6 +31,7 @@ export default function useDocument() {
       site,
       parentId,
       expiry,
+      ...(archived ? { archived: true } : {}),
     };
 
     return useNuxtApp().$api<Record<string, any>>(`/api/documents`, {
@@ -60,6 +64,14 @@ export default function useDocument() {
     });
   }
 
+  /** Archive keeps the document but hides it from the main list; restore brings it back. */
+  function setArchived(id: string, archived: boolean) {
+    return useNuxtApp().$api<Record<string, any>>(
+      `/api/documents/${id}/${archived ? "archive" : "unarchive"}`,
+      { method: "PUT" }
+    );
+  }
+
   function getById(id: string) {
     return useNuxtApp().$api<Record<string, any>>(`/api/documents/${id}`, {
       method: "GET",
@@ -108,6 +120,7 @@ export default function useDocument() {
     add,
     deleteById,
     updateById,
+    setArchived,
     getDocumentsBySiteId,
     create,
     createFolder,

package/composables/useFeedback.ts

@@ -162,6 +162,17 @@ export default function useFeedback() {
     );
   }
 
+  /** A linked copy of this feedback for another provider at the same site. */
+  function sendToProvider(id: string, provider: string) {
+    return useNuxtApp().$api<Record<string, any>>(
+      "/api/feedbacks2/send-to-provider",
+      {
+        method: "POST",
+        body: { _id: id, provider },
+      }
+    );
+  }
+
   function addFeedBackWorkOrder(payload: any) {
     return useNuxtApp().$api<Record<string, any>>(
       "/api/feedbacks2/create-work-order",
@@ -204,5 +215,6 @@ export default function useFeedback() {
     updateStatusComplete,
     addFeedBackWorkOrder,
     updateStatusFeedback,
+    sendToProvider,
   };
 }

package/composables/useHandoverChecklist.ts

@@ -0,0 +1,111 @@
+/**
+ * Room handover / takeover checklists (API-core `/api/handover-checklists`).
+ * The managing agent sets up a checklist per room; guards fill one in at each
+ * handover (before use) and takeover (after use). No facility booking needed.
+ */
+export type THandoverItem = {
+  label: string;
+  quantity?: number | null;
+  tagNo?: string | null;
+  referencePhotoId?: string | null;
+};
+
+export type THandoverTemplate = {
+  _id?: string;
+  title: string;
+  description?: string | null;
+  items: THandoverItem[];
+  updatedAt?: string;
+};
+
+export type THandoverRecordItem = THandoverItem & {
+  result: "in-order" | "not-in-order";
+  remarks?: string | null;
+  damagePhotoIds?: string[];
+};
+
+export type THandoverRecord = {
+  _id: string;
+  templateId: string;
+  title: string;
+  stage: "handover" | "takeover";
+  items?: THandoverRecordItem[];
+  notInOrderCount?: number;
+  photoIds?: string[];
+  remarks?: string | null;
+  officerName?: string | null;
+  completedAt: string;
+};
+
+export const HANDOVER_STAGE_LABELS: Record<string, string> = {
+  handover: "Handover (before use)",
+  takeover: "Takeover (after use)",
+};
+
+/**
+ * Ready-made checklists an MA can start from (renovation, move in / out). They
+ * only open the editor pre-filled; nothing is saved until the MA clicks Save.
+ */
+export const HANDOVER_STARTERS: Array<{ name: string; template: THandoverTemplate }> = [
+  {
+    name: "Lift & lobby protection (renovation)",
+    template: {
+      title: "Lift & lobby protection (renovation)",
+      description: "Check before renovation works start and again after they finish. Take photos of any damage.",
+      items: [
+        { label: "Lift protection in place (wall panels and floor)" },
+        { label: "Lobby floor protection in place" },
+        { label: "Lift interior condition (walls, doors, floor, buttons)" },
+        { label: "Lobby walls, doors and fittings condition" },
+        { label: "Common corridor clean, no debris" },
+      ],
+    },
+  },
+  {
+    name: "Move in / move out",
+    template: {
+      title: "Move in / move out",
+      description: "Check before the move starts and again after it ends. Take photos of any damage.",
+      items: [
+        { label: "Lift protection in place" },
+        { label: "Lobby floor protection in place" },
+        { label: "Lift interior condition (walls, doors, floor, buttons)" },
+        { label: "Lobby and corridor condition" },
+        { label: "Loading bay / driveway clear and undamaged" },
+      ],
+    },
+  },
+];
+
+export default function useHandoverChecklist() {
+  const base = "/api/handover-checklists";
+
+  function getTemplates(site: string) {
+    return useNuxtApp().$api<THandoverTemplate[]>(`${base}/templates/site/${site}`, { method: "GET" });
+  }
+
+  function addTemplate(site: string, body: THandoverTemplate) {
+    return useNuxtApp().$api<{ _id: string }>(`${base}/templates/site/${site}`, { method: "POST", body });
+  }
+
+  function updateTemplate(id: string, body: THandoverTemplate) {
+    return useNuxtApp().$api<Record<string, any>>(`${base}/templates/${id}`, { method: "PUT", body });
+  }
+
+  function deleteTemplate(id: string) {
+    return useNuxtApp().$api<Record<string, any>>(`${base}/templates/${id}`, { method: "DELETE" });
+  }
+
+  function getRecords(site: string, query: { page?: number; limit?: number; templateId?: string } = {}) {
+    return useNuxtApp().$api<{ items: THandoverRecord[]; total: number; page: number; limit: number }>(
+      `${base}/site/${site}`,
+      { method: "GET", query },
+    );
+  }
+
+  function getRecord(id: string) {
+    return useNuxtApp().$api<THandoverRecord>(`${base}/${id}`, { method: "GET" });
+  }
+
+  return { getTemplates, addTemplate, updateTemplate, deleteTemplate, getRecords, getRecord };
+}

package/composables/useKeyPresses.ts

@@ -0,0 +1,57 @@
+import { readKeySettings, keyPressName, type TKeyPress } from "../utils/key-presses";
+import useSite from "./useSite";
+
+/**
+ * One read per site per page load, shared by every caller (a list draws one
+ * press name per row). ponytail: never expires; a press added in another tab
+ * shows after a reload.
+ */
+const presses = new Map<string, Promise<TKeyPress[]>>();
+
+/**
+ * The site's key presses (`metadata.keySettings.cabinets`). Empty for a site
+ * that has none, which is every site until it adds one - every screen that
+ * uses this then looks exactly as before.
+ */
+export default function useKeyPresses(site: MaybeRefOrGetter<string>) {
+  const cabinets = ref<TKeyPress[]>([]);
+  const { getSiteById } = useSite();
+
+  async function load() {
+    const id = toValue(site);
+    // No site, or a site whose list is now empty: no press names left over.
+    if (!id) {
+      cabinets.value = [];
+      return;
+    }
+    if (!presses.has(id)) {
+      presses.set(
+        id,
+        getSiteById(id)
+          .then((site) => readKeySettings(site).cabinets)
+          .catch(() => {
+            presses.delete(id);
+            return [];
+          }),
+      );
+    }
+    const list = await presses.get(id)!;
+    // A slower answer for a site the caller has since left is dropped.
+    if (toValue(site) === id) cabinets.value = Array.isArray(list) ? list : [];
+  }
+  watch(() => toValue(site), load, { immediate: true });
+
+  const nameOf = (id?: string | null) => keyPressName(cabinets.value, id);
+  /** For a key autocomplete's `item-props`: the press as the item's second line. */
+  const keyItemProps = (item: any) => {
+    const name = nameOf(item?.cabinet);
+    return name ? { subtitle: name } : {};
+  };
+
+  /** After the site's presses are saved: read them again. */
+  function forget(id: string = toValue(site)) {
+    presses.delete(id);
+  }
+
+  return { cabinets, nameOf, keyItemProps, load, forget };
+}

package/composables/usePassKey.ts

@@ -125,6 +125,7 @@ export default function usePassKey() {
     statuses = [],
     sortBy,
     prefixAndName,
+    cabinets,
   }: {
     _ids?: any;
     page?: number;
@@ -137,6 +138,8 @@ export default function usePassKey() {
     statuses?: string[] | null;
     sortBy?: object;
     prefixAndName?: string;
+    /** Key press ids; "" = keys in no press. Left out = no press filter. */
+    cabinets?: string[];
   }) {
     return useNuxtApp().$api("/api/keys/search/v1", {
       method: "POST",
@@ -152,6 +155,7 @@ export default function usePassKey() {
         statuses,
         sortBy,
         prefixAndName,
+        ...(cabinets?.length ? { cabinets } : {}),
       },
     });
   }

package/composables/useSecurityPermission.ts

@@ -735,6 +735,38 @@ export default function useSecurityPermission() {
         description: "Allows the user to delete routes.",
       },
     },
+    /**
+     * NEW. Security Ops - the site visit and its checklists.
+     *
+     * NO ROLE HOLDS THESE YET. The module is new, so every one of these strings
+     * has a count of zero today. API-core's `siteVisit` gate is therefore
+     * COUNTED, not enforcing (`SITE_VISIT_PERMISSION_MODE`, default `log`): it
+     * records who WOULD be refused and refuses nobody, the same way the NFC
+     * patrol and incident report gates shipped. Provision roles against that
+     * count before anyone sets it to `enforce`.
+     *
+     * THREE PLACES, BY HAND. These spellings have to match API-core
+     * (`SITE_VISIT_PERMISSIONS` in `site-authz.util.ts`) and the RN app
+     * (`permission.catalog.ts`), which does NOT import this file - it keeps a
+     * literal copy and compares strings exactly. `roles-picker-covers-mobile-gates`
+     * in web-app-security is the test that holds the three together.
+     *
+     * The geofence right is NOT here: it is a site setting, so it lives in
+     * `useCommonPermission.ts` as `site-settings:manage-geofence` beside the
+     * other panels.
+     */
+    "security-ops": {
+      "start-site-visit": {
+        check: true,
+        description:
+          "Allows the user to check in at a site, fill in the visit checklists and check out.",
+      },
+      "see-all-site-visits": {
+        check: true,
+        description:
+          "Allows the user to view site visits across the sites they can reach, including other executives' visits.",
+      },
+    },
     // NEW. Seeing the CCTV wall, as distinct from setting cameras up
     // (`site-settings:manage-cctv-camera`).
     "cctv-mgmt": {
@@ -768,6 +800,12 @@ export default function useSecurityPermission() {
       "manage-nfc-management": siteSettingsPermissions["manage-nfc-management"],
       "manage-nfc-patrol-settings":
         siteSettingsPermissions["manage-nfc-patrol-settings"],
+      // Security Ops geofencing. This block CHERRY-PICKS from
+      // `siteSettingsPermissions` rather than spreading it, so a new entry in
+      // the common catalogue does not reach the security role editor on its own
+      // - without this line no administrator on a security site could grant the
+      // right, and the Geofencing panel would be invisible to everyone.
+      "manage-geofence": siteSettingsPermissions["manage-geofence"],
       "manage-red-dot-settings": {
         check: true,
         description:

package/composables/useSettingsPermission.ts

@@ -129,6 +129,20 @@ export function useSettingsPermission() {
       "update-vehicle": { check: true, description: "Allows the user to update vehicle details." },
     },
   };
+  /**
+   * The Geofencing panel - Security Ops site visits.
+   *
+   * MUST ALSO BE IN `canManageSiteSettings` BELOW. That computed is an OR of
+   * every panel gate and it is what decides whether the Settings page renders at
+   * all, so a role holding ONLY this right would otherwise be given a page it
+   * cannot open. Adding a panel is always two lines, never one.
+   */
+  const canManageGeofence = computed(() => {
+    if (!userAppRole.value) return false;
+    if (userAppRole.value.permissions.includes("*")) return true;
+    return hasPermission(userAppRole.value, permissions, "site-settings", "manage-geofence");
+  });
+
   const canManageVehicleQr = computed(() => {
     if (!userAppRole.value) return false;
     if (userAppRole.value.permissions.includes("*")) return true;
@@ -136,7 +150,7 @@ export function useSettingsPermission() {
   });
 
   const canManageSiteSettings = computed(() => {
-    return canManageSiteInformation.value || canManageANPRCamera.value || canManageCCTVCamera.value || canManageDeliveryCompanies.value || canManageResidentVisitors.value || canManageWorkOrderSettings.value || canManageBillingAndSOAConfiguration.value || canManageNFCManagement.value || canManageNFCPatrolSettings.value || canManageEntryPass.value || canManageRedDotSettings.value
+    return canManageSiteInformation.value || canManageANPRCamera.value || canManageCCTVCamera.value || canManageDeliveryCompanies.value || canManageResidentVisitors.value || canManageWorkOrderSettings.value || canManageBillingAndSOAConfiguration.value || canManageNFCManagement.value || canManageNFCPatrolSettings.value || canManageEntryPass.value || canManageRedDotSettings.value || canManageGeofence.value
   })
 
   return {
@@ -151,6 +165,7 @@ export function useSettingsPermission() {
     canManageNFCPatrolSettings,
     canManageEntryPass,
     canManageRedDotSettings,
+    canManageGeofence,
     canManageVehicleQr,
     canManageSiteSettings
 

package/composables/useSiteFeatureSettings.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-site switches (`site.metadata.<key>`, core `site-feature-settings.util.ts`).
+ *
+ * Every settings panel that writes one saves ONLY its own switch through
+ * `PATCH /api/sites/:id/feature-settings` `{ field: "metadata.<key>", value }`.
+ * Never the whole `metadata`: a panel that sends back what it read could wipe
+ * a switch another panel (or another person) saved in the meantime. The
+ * server validates the value and refuses data retention and feedback handling
+ * changes from anyone but the site's owner (or Seven365).
+ */
+export const SITE_FEATURE_KEYS = [
+  "visitorFields",
+  "keySettings",
+  "incidentReportEmails",
+  "feedbackSettings",
+  "dataRetention",
+  "maStaffRegistration",
+] as const;
+
+export type TSiteFeatureKey = (typeof SITE_FEATURE_KEYS)[number];
+
+/** The request body for one switch. */
+export function siteFeatureSettingBody(key: TSiteFeatureKey, value: unknown) {
+  if (!SITE_FEATURE_KEYS.includes(key)) throw new Error(`Unknown site setting: ${key}`);
+  return { field: `metadata.${key}`, value };
+}
+
+export default function useSiteFeatureSettings() {
+  async function saveSiteFeature(siteId: string, key: TSiteFeatureKey, value: unknown) {
+    return await useNuxtApp().$api<Record<string, any>>(`/api/sites/${siteId}/feature-settings`, {
+      method: "PATCH",
+      body: siteFeatureSettingBody(key, value),
+    });
+  }
+
+  return { saveSiteFeature };
+}

package/composables/useVisitor.ts

@@ -273,3 +273,25 @@ export default function () {
     visitorDataFromScannedQRCodeCheckIn,
   };
 }
+
+/**
+ * The site's guardhouse registration switches (`site.metadata.visitorFields`).
+ * Anything a site never saved reads as "default" = today's form.
+ */
+export type TVisitorFieldSwitches = {
+  nric: "default" | "hidden";
+  contact: "default" | "hidden" | "required";
+  vehicle: "default" | "required";
+};
+
+export function getVisitorFieldSwitches(site: any): TVisitorFieldSwitches {
+  const v = site?.metadata?.visitorFields ?? {};
+  return {
+    nric: v.nric === "hidden" ? "hidden" : "default",
+    contact: v.contact === "hidden" || v.contact === "required" ? v.contact : "default",
+    vehicle: v.vehicle === "required" ? "required" : "default",
+  };
+}
+
+/** Same words as the server's refusal, so the guard reads one message. */
+export const VEHICLE_REQUIRED_MESSAGE = "This site requires a vehicle number for every visitor.";

package/constants/permissions.ts

@@ -150,6 +150,9 @@ export const PERMISSIONS = {
     "manage-nfc-patrol-settings",
     "manage-entry-pass",
     "manage-red-dot-settings",
+    // Security Ops: the site boundary and the guardhouse check-in code. The
+    // server reads this one too - API-core `GEOFENCE_MANAGE_PERMISSIONS`.
+    "manage-geofence",
   ],
 
   // ---- module apps (cleaning, landscape, M&E, pest, pool) ----

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "4.118.10",
+  "version": "4.120.0",
   "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.",
@@ -37,7 +37,7 @@
     "build": "nuxt build .playground",
     "generate": "nuxt generate .playground",
     "preview": "nuxt preview .playground",
-    "test": "esbuild composables/useANPRSettings.ts --format=esm --outfile=test/.build/useANPRSettings.mjs --log-level=error && esbuild composables/useSite.ts --format=esm --outfile=test/.build/useSite.mjs --log-level=error && esbuild composables/useVisitorSocket.ts --format=esm --outfile=test/.build/useVisitorSocket.mjs --log-level=error && esbuild composables/usePlateToastWindow.ts --format=esm --outfile=test/.build/usePlateToastWindow.mjs --log-level=error && esbuild utils/client-invite-modules.ts --bundle --platform=node --format=esm --outfile=test/.build/client-invite-modules.mjs --log-level=error && esbuild utils/robot-display.ts --bundle --platform=node --format=esm --outfile=test/.build/robot-display.mjs --log-level=error && esbuild utils/building-map.ts --bundle --platform=node --format=esm --outfile=test/.build/building-map.mjs --log-level=error && esbuild utils/robot-building.ts --bundle --platform=node --format=esm --outfile=test/.build/robot-building.mjs --log-level=error && esbuild utils/robot-fleet-core.ts --bundle --platform=node --format=esm --outfile=test/.build/robot-fleet-core.mjs --log-level=error && esbuild utils/rmf-editor.ts --bundle --platform=node --format=esm --outfile=test/.build/rmf-editor.mjs --log-level=error && node --experimental-strip-types --test \"test/*.test.mjs\" && yarn test:units",
+    "test": "esbuild composables/useANPRSettings.ts --format=esm --outfile=test/.build/useANPRSettings.mjs --log-level=error && esbuild composables/useSite.ts --format=esm --outfile=test/.build/useSite.mjs --log-level=error && esbuild composables/useSiteFeatureSettings.ts --format=esm --outfile=test/.build/useSiteFeatureSettings.mjs --log-level=error && esbuild composables/useVisitor.ts --format=esm --outfile=test/.build/useVisitor.mjs --log-level=error && esbuild composables/useVisitorSocket.ts --format=esm --outfile=test/.build/useVisitorSocket.mjs --log-level=error && esbuild composables/usePlateToastWindow.ts --format=esm --outfile=test/.build/usePlateToastWindow.mjs --log-level=error && esbuild utils/client-invite-modules.ts --bundle --platform=node --format=esm --outfile=test/.build/client-invite-modules.mjs --log-level=error && esbuild utils/robot-display.ts --bundle --platform=node --format=esm --outfile=test/.build/robot-display.mjs --log-level=error && esbuild utils/building-map.ts --bundle --platform=node --format=esm --outfile=test/.build/building-map.mjs --log-level=error && esbuild utils/robot-building.ts --bundle --platform=node --format=esm --outfile=test/.build/robot-building.mjs --log-level=error && esbuild utils/robot-fleet-core.ts --bundle --platform=node --format=esm --outfile=test/.build/robot-fleet-core.mjs --log-level=error && esbuild utils/rmf-editor.ts --bundle --platform=node --format=esm --outfile=test/.build/rmf-editor.mjs --log-level=error && node --experimental-strip-types --test \"test/*.test.mjs\" && yarn test:units",
     "test:units": "node --experimental-strip-types --test \"utils/*.test.ts\"",
     "release": "yarn run build && changeset publish"
   },

package/types/key-log.d.ts

@@ -19,6 +19,8 @@ declare type TKeyLog = {
   keyNo?: number;
   userType?: string;
   updatedBy?: string;
+  /** Key press id from the site's `metadata.keySettings.cabinets`. */
+  cabinet?: string;
 };
 
 declare type TKeyLogResponse = {

package/types/passKey.d.ts

@@ -8,6 +8,8 @@ declare type TPassKey = {
   createdAt?: Date;
   site: string;
   status?: string;
+  /** Key press id (keys only), from the site's key presses. */
+  cabinet?: string;
 };
 
 declare type TPassKeyResponse = {

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)],
+  };
+}