@7365admin1/layer-common 3.2.2-staging.188 → 3.2.2-staging.190

package/components/DashboardMain.vue

@@ -2060,7 +2060,7 @@ const customizeWidgets = computed(() => {
         key: "visitors",
         title: "Visitors",
         description:
-          "See today's visitor traffic and who is currently on site.",
+          "See today's visitor traffic, and how many passes are still not checked out.",
       },
       {
         key: "facilityBookings",
@@ -2117,7 +2117,7 @@ const customizeWidgets = computed(() => {
         key: "visitors",
         title: "Visitors",
         description:
-          "See today's visitor traffic and who is currently on site.",
+          "See today's visitor traffic, and how many passes are still not checked out.",
       },
       {
         key: "patrolCompliance",
@@ -2288,7 +2288,7 @@ function getPropertyKpiCards() {
       color: KPI_TONES.info.color,
       tint: KPI_TONES.info.tint,
       value: formatNumber(toNumber(workOrderMetric?.count)),
-      percentage: toNumber(workOrderMetric?.percentage),
+      percentage: toNumberOrNaN(workOrderMetric?.percentage),
       meta: getMetricMeta(workOrderMetric),
       raw: workOrderMetric,
       filter: undefined,
@@ -2300,7 +2300,7 @@ function getPropertyKpiCards() {
       color: KPI_TONES.err.color,
       tint: KPI_TONES.err.tint,
       value: formatNumber(toNumber(incidentMetric?.count)),
-      percentage: toNumber(incidentMetric?.percentage),
+      percentage: toNumberOrNaN(incidentMetric?.percentage),
       meta: getMetricMeta(incidentMetric),
       raw: incidentMetric,
       filter: undefined,
@@ -2312,7 +2312,7 @@ function getPropertyKpiCards() {
       color: KPI_TONES.warn.color,
       tint: KPI_TONES.warn.tint,
       value: formatNumber(toNumber(visitorMetric?.count)),
-      percentage: toNumber(visitorMetric?.percentage),
+      percentage: toNumberOrNaN(visitorMetric?.percentage),
       meta: getMetricMeta(visitorMetric),
       raw: visitorMetric,
       filter: {
@@ -2331,7 +2331,7 @@ function getPropertyKpiCards() {
       color: KPI_TONES.ok.color,
       tint: KPI_TONES.ok.tint,
       value: formatNumber(toNumber(facilityMetric?.count)),
-      percentage: toNumber(facilityMetric?.percentage),
+      percentage: toNumberOrNaN(facilityMetric?.percentage),
       meta: getMetricMeta(facilityMetric),
       raw: facilityMetric,
       filter: undefined,
@@ -2366,7 +2366,7 @@ function getSecurityKpiCards() {
       color: KPI_TONES.info.color,
       tint: KPI_TONES.info.tint,
       value: formatNumber(toNumber(workOrderMetric?.count)),
-      percentage: toNumber(workOrderMetric?.percentage),
+      percentage: toNumberOrNaN(workOrderMetric?.percentage),
       meta: getMetricMeta(workOrderMetric),
       raw: workOrderMetric,
       filter: undefined,
@@ -2378,7 +2378,7 @@ function getSecurityKpiCards() {
       color: KPI_TONES.err.color,
       tint: KPI_TONES.err.tint,
       value: formatNumber(toNumber(incidentMetric?.count)),
-      percentage: toNumber(incidentMetric?.percentage),
+      percentage: toNumberOrNaN(incidentMetric?.percentage),
       meta: getMetricMeta(incidentMetric),
       raw: incidentMetric,
       filter: undefined,
@@ -2390,7 +2390,7 @@ function getSecurityKpiCards() {
       color: KPI_TONES.warn.color,
       tint: KPI_TONES.warn.tint,
       value: formatNumber(toNumber(visitorMetric?.count)),
-      percentage: toNumber(visitorMetric?.percentage),
+      percentage: toNumberOrNaN(visitorMetric?.percentage),
       meta: getMetricMeta(visitorMetric),
       raw: visitorMetric,
       filter: {
@@ -2408,8 +2408,10 @@ function getSecurityKpiCards() {
       icon: "mdi-office-building",
       color: KPI_TONES.ok.color,
       tint: KPI_TONES.ok.tint,
-      value: `${toNumber(patrolMetric?.count)}%`,
-      percentage: toNumber(patrolMetric?.percentage),
+      // Through the shared helper, so a `null` rate (no checkpoint was due)
+      // reads as not-measured here too, not as 0%.
+      value: getMetricValue(patrolMetric, "patrolCompliance"),
+      percentage: toNumberOrNaN(patrolMetric?.percentage),
       meta: getMetricMeta(patrolMetric),
       raw: patrolMetric,
       filter: undefined,
@@ -2436,7 +2438,7 @@ const rawKpiCards = computed(() => {
       tint: getCardTint(mapping.color, index),
       color: mapping.color || getCardColor(index),
       value: typeof value === "string" ? value : formatNumber(value),
-      percentage: toNumber(metric.percentage),
+      percentage: toNumberOrNaN(metric.percentage),
       meta: getMetricMeta(metric),
       raw: metric,
       filter: undefined as any,
@@ -2917,7 +2919,9 @@ function getMetric(keys: string[]): DashboardMetric {
 
 function getMetricValue(metric: DashboardMetric, key?: string) {
   if (key === "patrolCompliance") {
-    return `${formatNumber(toNumber(metric.count))}%`;
+    const rate = toNumberOrNaN(metric.count);
+    // `null` = no checkpoint was due in this period. Not 0%, not 100%.
+    return Number.isFinite(rate) ? `${formatNumber(rate)}%` : "—";
   }
   const completed = toNumber(metric.completed);
   const total = toNumber(metric.total);
@@ -2935,11 +2939,18 @@ function getMetricMeta(metric: DashboardMetric) {
     parts.push(`${formatNumber(toNumber(metric.inProgress))} in progress`);
   if (typeof metric.pending !== "undefined")
     parts.push(`${formatNumber(toNumber(metric.pending))} pending`);
-  if (typeof metric.highSeverity !== "undefined")
+  // `null` here is the API saying incident severity is not recorded at all.
+  // Printing "0 high severity" would answer a question nothing measured.
+  if (metric.highSeverity !== undefined && metric.highSeverity !== null)
     parts.push(`${formatNumber(toNumber(metric.highSeverity))} high severity`);
-  if (typeof metric.currentlyOnSite !== "undefined")
+  // NOT a live occupancy figure. The server counts every visitor transaction
+  // with a check-in and no check-out, with NO date bound, and nothing in the
+  // product ever closes a stale one - so a pass left open years ago is still
+  // in here. Say what it counts. Same wording the Visitor Management screen
+  // already uses for the same filter ("Not Checked Out").
+  if (metric.currentlyOnSite !== undefined && metric.currentlyOnSite !== null)
     parts.push(
-      `${formatNumber(toNumber(metric.currentlyOnSite))} currently on site`
+      `${formatNumber(toNumber(metric.currentlyOnSite))} not checked out (all time)`
     );
   if (
     typeof (metric as any).missedCheckpoints !== "undefined" ||
@@ -3905,6 +3916,21 @@ function toNumber(value: any) {
   return Number.isFinite(n) ? n : 0;
 }
 
+/**
+ * A figure the server may report as "not measured".
+ *
+ * `toNumber()` turns `null` into `0`, which is wrong for anything the API
+ * deliberately sends as `null` - a trend with no prior period to compare
+ * against, a compliance rate with no checkpoint due, a severity the incident
+ * form never records. Those must read as absent, not as zero. `NaN` is what
+ * the tile already treats as "no pill" / "no figure".
+ */
+function toNumberOrNaN(value: any) {
+  if (value === null || value === undefined || value === "") return NaN;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : NaN;
+}
+
 function normalizeStatus(value: any) {
   const text = String(value || "").trim();
   if (!text) return "To-Do";

package/components/Nfc/PatrolReport/DailyReportTab.vue

@@ -17,6 +17,13 @@
     </template>
 
 
+    <!-- A failed request is not an empty result. Saying "no patrol log found"
+         for a 500 states something about the data the server never said. -->
+    <ReportEmptyState
+      v-else-if="!loading && failed"
+      title="Report unavailable"
+      message="The patrol logs could not be loaded. Please try again."
+    />
     <ReportEmptyState
       v-else-if="!loading && notFound"
       title="No Daily Report"
@@ -51,7 +58,7 @@ defineEmits<{
   export: [type: "pdf" | "csv"];
 }>();
 
-const { report, loading, notFound, fetchReport } = useNFCPatrolDailyReport(
+const { report, loading, notFound, failed, fetchReport } = useNFCPatrolDailyReport(
   props.filters,
   props.site,
 );

package/components/Nfc/PatrolReport/MonthlyReportTab.vue

@@ -21,6 +21,13 @@
       />
     </template>
 
+    <!-- A failed request is not an empty result. Saying "no patrol log found"
+         for a 500 states something about the data the server never said. -->
+    <ReportEmptyState
+      v-else-if="!loading && failed"
+      title="Report unavailable"
+      message="The patrol logs could not be loaded. Please try again."
+    />
     <ReportEmptyState
       v-else-if="!loading"
       title="No Monthly Report"
@@ -55,7 +62,7 @@ defineEmits<{
   export: [type: "pdf" | "csv"];
 }>();
 
-const { report, loading, notFound, fetchReport } =
+const { report, loading, notFound, failed, fetchReport } =
   useNFCPatrolMonthlyReport(props.filters, props.site);
 
 watch(

package/components/Nfc/PatrolReport/MonthlyReportTable.vue

@@ -26,8 +26,10 @@
             {{ row.checked }}
           </td>
 
+          <!-- A month with no checkpoint due has no rate. "0%" there reads as
+               total failure, so it says nothing instead. -->
           <td class="text-center">
-            {{ row.checkedPercentage }}%
+            {{ row.checkedPercentage === null ? "—" : `${row.checkedPercentage}%` }}
           </td>
 
           <td class="text-center">
@@ -35,7 +37,7 @@
           </td>
 
           <td class="text-center">
-            {{ row.missedPercentage }}%
+            {{ row.missedPercentage === null ? "—" : `${row.missedPercentage}%` }}
           </td>
         </tr>
       </tbody>

package/components/Nfc/PatrolReport/PatrolReportTab.vue

@@ -22,6 +22,13 @@
       />
     </template>
 
+    <!-- A failed request is not an empty result. Saying "no patrol log found"
+         for a 500 states something about the data the server never said. -->
+    <ReportEmptyState
+      v-else-if="!loading && failed"
+      title="Report unavailable"
+      message="The patrol logs could not be loaded. Please try again."
+    />
     <ReportEmptyState
       v-else-if="!loading && notFound"
       title="No Patrol Log"
@@ -63,6 +70,7 @@ const {
   report,
   loading,
   notFound,
+  failed,
   selectedActivityRemarks,
   dialogRemarks,
   fetchReport,

package/composables/useNFCPatrolDailyReport.ts

@@ -52,16 +52,24 @@ export function useNFCPatrolDailyReport(
   const report = ref<NFCPatrolSummaryReport | null>(null);
   const loading = ref(false);
   const notFound = ref(false);
+  /**
+   * A request that FAILED is not a route with no patrols. Without this the
+   * screen answered a 500 with "No patrol log found for this route", which is
+   * a statement about the data the server never made.
+   */
+  const failed = ref(false);
 
   async function fetchReport() {
     if (!site || !filters.date || !filters.route) {
       report.value = null;
       notFound.value = false;
+      failed.value = false;
       return;
     }
 
     loading.value = true;
     notFound.value = false;
+    failed.value = false;
 
     try {
       const [logsRes, siteInfo] = await Promise.all([
@@ -92,6 +100,10 @@ export function useNFCPatrolDailyReport(
         report.value = null;
         notFound.value = true;
       }
+    } catch {
+      report.value = null;
+      notFound.value = false;
+      failed.value = true;
     } finally {
       loading.value = false;
     }
@@ -101,6 +113,7 @@ export function useNFCPatrolDailyReport(
     report,
     loading,
     notFound,
+    failed,
     fetchReport,
   };
 }

package/composables/useNFCPatrolMonthlyReport.ts

@@ -2,11 +2,11 @@ import type {
   NFCPatrolReportFilters,
   NFCPatrolSummaryReport,
   NFCPatrolReportSummaryRow,
-  NFCPatrolMonthlyReportRow,
   NFCPatrolMonthlyReport,
 } from "../types/nfc-patrol-report";
 import useNFCPatrolLog from "./useNFCPatrolLog";
 import useSite from "./useSite";
+import { collectAllPages, mapLogsToMonthlyRows } from "../utils/nfc-patrol-report";
 
 interface NFCPatrolLogListResponse {
   items?: Record<string, any>[];
@@ -14,55 +14,6 @@ interface NFCPatrolLogListResponse {
   pageRange?: string;
 }
 
-const MONTHS = [
-  "January",
-  "February",
-  "March",
-  "April",
-  "May",
-  "June",
-  "July",
-  "August",
-  "September",
-  "October",
-  "November",
-  "December",
-];
-function mapLogsToMonthlyRows(
-  logs: Record<string, any>[],
-): NFCPatrolMonthlyReportRow[] {
-  const rows = MONTHS.map((month) => ({
-    month,
-    checked: 0,
-    checkedPercentage: 0,
-    missed: 0,
-    missedPercentage: 0,
-  }));
-
-  logs.forEach((log) => {
-    const monthIndex = new Date(log.date).getMonth();
-
-    for (const checkpoint of log.checkPoints ?? []) {
-      if (checkpoint.status === "Completed") {
-        rows[monthIndex].checked++;
-      } else if (checkpoint.status === "Skipped") {
-        rows[monthIndex].missed++;
-      }
-    }
-  });
-
-  rows.forEach((row) => {
-    const total = row.checked + row.missed;
-
-    if (total > 0) {
-      row.checkedPercentage = Math.round((row.checked / total) * 100);
-      row.missedPercentage = Math.round((row.missed / total) * 100);
-    }
-  });
-
-  return rows;
-}
-
 function buildAddress(address?: Record<string, string>) {
   if (!address) return undefined;
 
@@ -90,32 +41,42 @@ export function useNFCPatrolMonthlyReport(
   const report = ref<NFCPatrolMonthlyReport | null>(null);
   const loading = ref(false);
   const notFound = ref(false);
+  /**
+   * A request that FAILED is not a route with no patrols. Without this the
+   * screen answered a 500 with "No patrol log found for this route", which is
+   * a statement about the data the server never made.
+   */
+  const failed = ref(false);
 
   async function fetchReport() {
     if (!site || !filters.route) {
       report.value = null;
       notFound.value = false;
+      failed.value = false;
       return;
     }
 
     loading.value = true;
     notFound.value = false;
+    failed.value = false;
     const currentYear = new Date().getFullYear().toString();
     try {
-      const [logsRes, siteInfo] = await Promise.all([
-        getPatrolLogs({
-            page: 1,
+      // The whole year, not page one of it. `collectAllPages` reads the page
+      // count out of the first reply and walks the rest.
+      const [logs, siteInfo] = await Promise.all([
+        collectAllPages((page) =>
+          getPatrolLogs({
+            page,
             limit: 100,
             site,
             routeId: filters.route,
             date: currentYear,
             type: "month",
-        }),
+          }),
+        ),
         getSiteById(site),
       ]);
 
-      const logs = logsRes.items ?? [];
-
       if (logs.length) {
         const routeName = logs[0]?.route?.name ?? "-";
 
@@ -131,6 +92,10 @@ export function useNFCPatrolMonthlyReport(
         report.value = null;
         notFound.value = true;
       }
+    } catch {
+      report.value = null;
+      notFound.value = false;
+      failed.value = true;
     } finally {
       loading.value = false;
     }
@@ -140,6 +105,7 @@ export function useNFCPatrolMonthlyReport(
     report,
     loading,
     notFound,
+    failed,
     fetchReport,
   };
 }

package/composables/useNFCPatrolReport.ts

@@ -91,6 +91,12 @@ export function useNFCPatrolReport(
   const report = ref<NFCPatrolReport | null>(null);
   const loading = ref(false);
   const notFound = ref(false);
+  /**
+   * A request that FAILED is not a route with no patrols. Without this the
+   * screen answered a 500 with "No patrol log found for this route", which is
+   * a statement about the data the server never made.
+   */
+  const failed = ref(false);
   const selectedActivityRemarks = ref("");
   const dialogRemarks = ref(false);
 
@@ -98,11 +104,13 @@ export function useNFCPatrolReport(
     if (!site || !filters.date || !filters.route || !filters.timeRange) {
       report.value = null;
       notFound.value = false;
+      failed.value = false;
       return;
     }
 
     loading.value = true;
     notFound.value = false;
+    failed.value = false;
 
     try {
       const [logsRes, siteInfo] = await Promise.all([
@@ -128,6 +136,10 @@ export function useNFCPatrolReport(
         report.value = null;
         notFound.value = true;
       }
+    } catch {
+      report.value = null;
+      notFound.value = false;
+      failed.value = true;
     } finally {
       loading.value = false;
     }
@@ -165,6 +177,7 @@ export function useNFCPatrolReport(
     report,
     loading,
     notFound,
+    failed,
     selectedActivityRemarks,
     dialogRemarks,
     fetchReport,

package/package.json

@@ -2,7 +2,7 @@
   "name": "@7365admin1/layer-common",
   "license": "MIT",
   "type": "module",
-  "version": "3.2.2-staging.188",
+  "version": "3.2.2-staging.190",
   "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/types/nfc-patrol-report.ts

@@ -85,9 +85,10 @@ export interface NFCPatrolSummaryReport {
 export interface NFCPatrolMonthlyReportRow {
   month: string;
   checked: number;
-  checkedPercentage: number;
+  /** `null` when no checkpoint was due that month - see `utils/nfc-patrol-report.ts`. */
+  checkedPercentage: number | null;
   missed: number;
-  missedPercentage: number;
+  missedPercentage: number | null;
 }
 
 export interface NFCPatrolMonthlyReport {

package/utils/nfc-patrol-report.test.ts

@@ -0,0 +1,130 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { collectAllPages, mapLogsToMonthlyRows } from "./nfc-patrol-report.ts";
+
+/**
+ * THE DEFECT THIS FILE EXISTS FOR.
+ *
+ * The yearly patrol-compliance table was built from `page: 1, limit: 100` of a
+ * paged endpoint and never looked at `pages`. A route patrolled daily produces
+ * ~300 runs a year, so months past the first page rendered "0 / 0% / 0 / 0%" -
+ * indistinguishable from a month in which every checkpoint was missed, in a
+ * table a manager can print and hand to a client.
+ */
+
+/** 12 months x 25 runs x (4 completed + 1 skipped). Every month is 80%/20%. */
+function yearOfLogs() {
+  const logs: Record<string, any>[] = [];
+  for (let m = 0; m < 12; m++) {
+    for (let d = 1; d <= 25; d++) {
+      const checkPoints = [
+        { status: "Completed" },
+        { status: "Completed" },
+        { status: "Completed" },
+        { status: "Completed" },
+        { status: "Skipped" },
+      ];
+      logs.push({
+        date: `2026-${String(m + 1).padStart(2, "0")}-${String(d).padStart(2, "0")}T08:00:00.000Z`,
+        checkPoints,
+      });
+    }
+  }
+  return logs;
+}
+
+function pagedFetcher(all: Record<string, any>[], limit = 100) {
+  const pages = Math.ceil(all.length / limit);
+  const seen: number[] = [];
+  return {
+    seen,
+    fetchPage: async (page: number) => {
+      seen.push(page);
+      return { items: all.slice((page - 1) * limit, page * limit), pages };
+    },
+  };
+}
+
+test("every page the endpoint reports is read, not just the first", async () => {
+  const all = yearOfLogs();
+  const { fetchPage, seen } = pagedFetcher(all);
+
+  const items = await collectAllPages(fetchPage);
+
+  assert.equal(items.length, all.length, "all 300 runs collected");
+  assert.deepEqual(seen, [1, 2, 3], "walked every page the reply declared");
+});
+
+test("a full year reports the same rate in every month", async () => {
+  const items = await collectAllPages(pagedFetcher(yearOfLogs()).fetchPage);
+  const rows = mapLogsToMonthlyRows(items);
+
+  assert.equal(rows.length, 12);
+  for (const row of rows) {
+    assert.equal(row.checked, 100, `${row.month} checked`);
+    assert.equal(row.missed, 25, `${row.month} missed`);
+    assert.equal(row.checkedPercentage, 80, `${row.month} % checked`);
+    assert.equal(row.missedPercentage, 20, `${row.month} % missed`);
+  }
+});
+
+test("only the first page would have zeroed the rest of the year", () => {
+  // What the screen used to do: one page of 100, the other 200 runs dropped.
+  const firstPageOnly = yearOfLogs().slice(0, 100);
+  const rows = mapLogsToMonthlyRows(firstPageOnly);
+
+  assert.equal(rows[0].checkedPercentage, 80, "January measured");
+  assert.equal(rows[4].checked, 0, "May had no runs on page 1");
+  assert.equal(
+    rows[4].checkedPercentage,
+    null,
+    "and it must NOT read 0% - nothing was measured",
+  );
+});
+
+test("a month with no checkpoint due reports no rate at all", () => {
+  const rows = mapLogsToMonthlyRows([]);
+
+  for (const row of rows) {
+    assert.equal(row.checked, 0);
+    assert.equal(row.missed, 0);
+    assert.equal(row.checkedPercentage, null);
+    assert.equal(row.missedPercentage, null);
+  }
+});
+
+test("a month where every checkpoint was missed still reports 0%", () => {
+  const rows = mapLogsToMonthlyRows([
+    { date: "2026-03-04T08:00:00.000Z", checkPoints: [{ status: "Skipped" }, { status: "Skipped" }] },
+  ]);
+
+  assert.equal(rows[2].checkedPercentage, 0, "0% here is a real measurement");
+  assert.equal(rows[2].missedPercentage, 100);
+  assert.equal(rows[0].checkedPercentage, null, "January measured nothing");
+});
+
+test("a single-page reply is not re-fetched", async () => {
+  const { fetchPage, seen } = pagedFetcher(yearOfLogs().slice(0, 10));
+  await collectAllPages(fetchPage);
+  assert.deepEqual(seen, [1]);
+});
+
+test("a reply with no page count is treated as one page", async () => {
+  const calls: number[] = [];
+  const items = await collectAllPages(async (page) => {
+    calls.push(page);
+    return { items: [{ date: "2026-01-02T00:00:00.000Z", checkPoints: [] }] };
+  });
+  assert.deepEqual(calls, [1]);
+  assert.equal(items.length, 1);
+});
+
+test("undated or malformed logs are skipped, not counted into January", () => {
+  const rows = mapLogsToMonthlyRows([
+    { date: "not-a-date", checkPoints: [{ status: "Completed" }] },
+    { checkPoints: [{ status: "Completed" }] },
+  ]);
+  assert.equal(rows[0].checked, 0);
+  assert.equal(rows[0].checkedPercentage, null);
+});

package/utils/nfc-patrol-report.ts

@@ -0,0 +1,101 @@
+/**
+ * Patrol-report arithmetic that is worth testing on its own.
+ *
+ * The yearly compliance table used to be built from `page: 1, limit: 100` of a
+ * paged endpoint. A route patrolled daily produces far more than 100 runs a
+ * year, so every month past the first page rendered "0 / 0% / 0 / 0%" - eight
+ * months of measured zeros in a table a manager can print and hand to a
+ * client. The page walk and the month mapping live here so they have tests.
+ */
+
+/** One page of the patrol-log endpoint's reply. */
+export type TPatrolLogPage = {
+  items?: Record<string, any>[];
+  pages?: number;
+};
+
+export type TPatrolMonthRow = {
+  month: string;
+  checked: number;
+  missed: number;
+  /** `null` when no checkpoint was due that month - a rate over nothing is not a measurement. */
+  checkedPercentage: number | null;
+  missedPercentage: number | null;
+};
+
+export const MONTHS = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December",
+];
+
+/**
+ * Read every page the endpoint says exists, not just the first.
+ *
+ * ponytail: sequential. A year of one route is a handful of pages, and firing
+ * them in parallel would only trade a few hundred ms for a burst on the API.
+ * `maxPages` is a runaway guard, not a product limit - if it ever bites, the
+ * caller is asking for a range the report was not designed for.
+ */
+export async function collectAllPages(
+  fetchPage: (page: number) => Promise<TPatrolLogPage>,
+  maxPages = 50,
+): Promise<Record<string, any>[]> {
+  const first = await fetchPage(1);
+  const items = [...(first?.items ?? [])];
+  const pages = Math.min(Number(first?.pages) || 1, maxPages);
+
+  for (let page = 2; page <= pages; page++) {
+    const next = await fetchPage(page);
+    items.push(...(next?.items ?? []));
+  }
+
+  return items;
+}
+
+/**
+ * One row per calendar month. A month with no checkpoint due keeps its zero
+ * counts - zero checkpoints really were checked - but reports `null` for both
+ * percentages, because a percentage of nothing is not a measurement and "0%"
+ * reads exactly like total failure.
+ */
+export function mapLogsToMonthlyRows(
+  logs: Record<string, any>[],
+): TPatrolMonthRow[] {
+  const rows: TPatrolMonthRow[] = MONTHS.map((month) => ({
+    month,
+    checked: 0,
+    missed: 0,
+    checkedPercentage: null,
+    missedPercentage: null,
+  }));
+
+  for (const log of logs) {
+    const monthIndex = new Date(log?.date).getMonth();
+    if (Number.isNaN(monthIndex)) continue;
+
+    for (const checkpoint of log?.checkPoints ?? []) {
+      if (checkpoint?.status === "Completed") rows[monthIndex].checked++;
+      else if (checkpoint?.status === "Skipped") rows[monthIndex].missed++;
+    }
+  }
+
+  for (const row of rows) {
+    const total = row.checked + row.missed;
+    if (total > 0) {
+      row.checkedPercentage = Math.round((row.checked / total) * 100);
+      row.missedPercentage = Math.round((row.missed / total) * 100);
+    }
+  }
+
+  return rows;
+}