refactor: consolidate duplicated helpers, extract shared factories, drop dead code

Behaviour-preserving structural cleanup across the monorepo. No functional
changes except one deliberate display refinement (noted below). Full suite,
type-check, and lint pass.

Shared helpers / dedup:
- core: new `fetchJson(url, { timeoutMs, headers, label, userAgent, nullOnError,
  errorMessage, init })`; migrated ~31 inline AbortController/AbortSignal fetch
  sites across integrations onto it, each preserving its exact timeout, headers,
  User-Agent presence, and throw-vs-null error mode. Added `haversineKm` and
  routed fuel / overlay-nautical / overlay-natural-events / ev-charging /
  parking / geocoding off their local great-circle copies. New `safeEqual`
  util (apps/api) and `useExploreFilters` hook (core).
- web: deduped `formatBytes` / `formatRelativeTime` / `formatDistance` onto lib
  helpers; extracted `floatingChipSx`, `ResultListItem`/`ResultList`,
  `removeLayerAndSource`/`upsertGeoJsonSource` (layerStyleUtils), `OverlayLegend`,
  `useStyleSyncedLayer`, admin `ServiceStatusChip`/`MetaRow`,
  `useDataSourceAttribution`, `PanelDetailHeader`/`SectionLabel`.

Config-driven integration factories (exact-match sites only; divergent providers
left explicit):
- `defineTransitProvider`, `createTidesIntegration`, `createBboxPhotoProvider`
  (integration-framework / integration-photos); geocoding `resolveEndpoint` +
  shared types; isochrone types re-exported from the framework contract.

apps/api integration-host: extracted `buildIntegrationContext` /
`buildIntegrationDb` / `warnInvalidConfig` so cold start and reload share one
context builder; made reload emit `integration.error` + warn on duplicate id,
symmetric with cold start.

Dead code removed: core `geo.ts` + unused coordinate helpers; apps/api `MemCache`
+ `road-snap`; web `DirectionsDestinationMarker` + `useIntegrationAttribution`;
4 duplicate `photos-*/types.ts` + 6 duplicate `geocoding-*/types.ts`; duplicate
`knowledge-ourairports/csv.ts` (test relocated to ourairports-data); dead apps/api
knowledge types.

Display refinement: shared `formatBytes` now renders TB-scale sizes as "TB"
rather than overflowing into "GB" — the only observable change.

Author: Medformatik

apps/api/src/integration-host.ts

@@ -1,4 +1,3 @@
-import { timingSafeEqual } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { and, asc, count, desc, eq } from "drizzle-orm";
@@ -7,6 +6,7 @@ import { db } from "../db/index.js";
 import { dataManagerFeedState, dataManagerJobStages, dataManagerJobs } from "../db/schema.js";
 import { getProviderHealth } from "../services/provider-health/registry.js";
 import { requireAdmin } from "../utils/require-admin.js";
+import { safeEqual } from "../utils/safe-equal.js";
 
 /**
  * `/api/data-manager/transit/*` — operator-facing surface for the self-hosted
@@ -31,13 +31,6 @@ interface AuthResult {
   reason?: string;
 }
 
-function safeEqual(a: string, b: string): boolean {
-  const aBuf = Buffer.from(a);
-  const bBuf = Buffer.from(b);
-  if (aBuf.length !== bBuf.length) return false;
-  return timingSafeEqual(aBuf, bBuf);
-}
-
 function extractBearerToken(req: FastifyRequest): string | null {
   const header = req.headers.authorization;
   if (typeof header === "string" && header.startsWith("Bearer ")) {

apps/api/src/routes/data-manager.ts

@@ -1,27 +1,24 @@
-export type IsochroneTravelMode = "driving" | "walking" | "cycling";
+// The isochrone data types are the canonical contract from
+// `@openmapx/integration-framework`; re-exported here so the existing
+// `services/isochrone/*` + route imports keep resolving. `IsochroneProvider`
+// is the apps/api-internal provider contract (not part of the framework).
+import type {
+  IsochroneContour,
+  IsochroneGeometry,
+  IsochroneMultiPolygon,
+  IsochronePolygon,
+  IsochroneResult,
+  IsochroneTravelMode,
+} from "@openmapx/integration-framework";
 
-export interface IsochronePolygon {
-  type: "Polygon";
-  coordinates: number[][][];
-}
-
-export interface IsochroneMultiPolygon {
-  type: "MultiPolygon";
-  coordinates: number[][][][];
-}
-
-export type IsochroneGeometry = IsochronePolygon | IsochroneMultiPolygon;
-
-export interface IsochroneContour {
-  time: number;
-  geometry: IsochroneGeometry;
-}
-
-export interface IsochroneResult {
-  origin: [number, number];
-  mode: IsochroneTravelMode;
-  contours: IsochroneContour[];
-}
+export type {
+  IsochroneContour,
+  IsochroneGeometry,
+  IsochroneMultiPolygon,
+  IsochronePolygon,
+  IsochroneResult,
+  IsochroneTravelMode,
+};
 
 export interface IsochroneProvider {
   isochrone(

apps/api/src/services/isochrone/provider.ts

@@ -122,54 +122,6 @@ export function round(value: number, decimals: number): number {
   return Math.round(value * factor) / factor;
 }
 
-// In-memory LRU cache with soft/hard TTL for stale-while-revalidate
-// Sits in front of Redis as L1: sub-millisecond reads for hot queries.
-// Soft TTL: data is "stale" but still served (background refresh triggered).
-// Hard TTL: data is evicted, falls through to Redis / upstream.
-
-interface MemEntry<T> {
-  data: T;
-  softExpiry: number;
-  hardExpiry: number;
-}
-
-export class MemCache<T> {
-  private cache = new Map<string, MemEntry<T>>();
-  private readonly maxSize: number;
-
-  constructor(maxSize: number) {
-    this.maxSize = maxSize;
-  }
-
-  get(key: string): { data: T; stale: boolean } | null {
-    const entry = this.cache.get(key);
-    if (!entry) return null;
-    const now = Date.now();
-    if (now > entry.hardExpiry) {
-      this.cache.delete(key);
-      return null;
-    }
-    // Move to end (most recently used)
-    this.cache.delete(key);
-    this.cache.set(key, entry);
-    return { data: entry.data, stale: now > entry.softExpiry };
-  }
-
-  set(key: string, data: T, softTtlMs: number, hardTtlMs: number): void {
-    // Evict oldest if at capacity
-    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
-      const oldest = this.cache.keys().next().value;
-      if (oldest !== undefined) this.cache.delete(oldest);
-    }
-    const now = Date.now();
-    this.cache.set(key, {
-      data,
-      softExpiry: now + softTtlMs,
-      hardExpiry: now + hardTtlMs,
-    });
-  }
-}
-
 // Centralized TTL constants
 
 export const TTL = {

apps/api/src/services/knowledge/types.ts

@@ -1,7 +1,7 @@
-import { timingSafeEqual } from "node:crypto";
 import { fromNodeHeaders } from "better-auth/node";
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { auth } from "../auth";
+import { safeEqual } from "./safe-equal.js";
 
 export type AdminSession = NonNullable<Awaited<ReturnType<typeof auth.api.getSession>>>;
 
@@ -44,13 +44,6 @@ function socketPeerAddress(request: FastifyRequest): string | undefined {
  */
 const LOCAL_ADMIN_TOKEN_HEADER = "x-openmapx-local-admin";
 
-function safeEqual(a: string, b: string): boolean {
-  const aBuf = Buffer.from(a);
-  const bBuf = Buffer.from(b);
-  if (aBuf.length !== bBuf.length) return false;
-  return timingSafeEqual(aBuf, bBuf);
-}
-
 function getLocalAdminToken(): string | null {
   const token = process.env.OPENMAPX_LOCAL_ADMIN_TOKEN?.trim();
   return token ? token : null;

apps/api/src/utils/cache.ts

@@ -0,0 +1,13 @@
+import { timingSafeEqual } from "node:crypto";
+
+/**
+ * Constant-time string comparison. Returns false immediately on a length
+ * mismatch (the length is not secret), otherwise compares the bytes without an
+ * early-out so the timing does not leak how many characters matched.
+ */
+export function safeEqual(a: string, b: string): boolean {
+  const aBuf = Buffer.from(a);
+  const bBuf = Buffer.from(b);
+  if (aBuf.length !== bBuf.length) return false;
+  return timingSafeEqual(aBuf, bBuf);
+}

apps/api/src/utils/require-admin.ts

@@ -23,6 +23,7 @@ import Typography from "@mui/material/Typography";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useState } from "react";
 import { useEnv } from "@/lib/EnvProvider";
+import { relativeTimeFromIso } from "@/lib/formatTime";
 import { TableSkeleton } from "../shared/TableSkeleton";
 import { ActorCell } from "./ActorCell";
 
@@ -191,14 +192,6 @@ function ActionChip({ action }: { action: string }) {
   );
 }
 
-function formatRelativeTime(iso: string): string {
-  const diff = Date.now() - new Date(iso).getTime();
-  if (diff < 60000) return "just now";
-  if (diff < 3600000) return `${Math.floor(diff / 60000)}m ago`;
-  if (diff < 86400000) return `${Math.floor(diff / 3600000)}h ago`;
-  return new Date(iso).toLocaleDateString();
-}
-
 export function AuditLog() {
   const env = useEnv();
   const queryClient = useQueryClient();
@@ -427,7 +420,7 @@ export function AuditLog() {
                           color: "text.secondary",
                         }}
                       >
-                        {formatRelativeTime(entry.createdAt)}
+                        {relativeTimeFromIso(entry.createdAt)}
                       </Typography>
                     </Tooltip>
                   </TableCell>

apps/api/src/utils/road-snap.ts

@@ -22,6 +22,7 @@ import Typography from "@mui/material/Typography";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useState } from "react";
 import { useEnv } from "@/lib/EnvProvider";
+import { relativeTimeFromIso } from "@/lib/formatTime";
 import { TableSkeleton } from "../shared/TableSkeleton";
 import { ActorCell } from "./ActorCell";
 import { JobDetail } from "./JobDetail";
@@ -54,14 +55,6 @@ function formatJobType(type: string): string {
   return type.replace(/\./g, " › ").replace(/_/g, " ");
 }
 
-function formatRelativeTime(iso: string): string {
-  const diff = Date.now() - new Date(iso).getTime();
-  if (diff < 60000) return "just now";
-  if (diff < 3600000) return `${Math.floor(diff / 60000)}m ago`;
-  if (diff < 86400000) return `${Math.floor(diff / 3600000)}h ago`;
-  return new Date(iso).toLocaleDateString();
-}
-
 function JobRow({ job }: { job: AdminJob }) {
   const [expanded, setExpanded] = useState(false);
 
@@ -118,7 +111,7 @@ function JobRow({ job }: { job: AdminJob }) {
                 color: "text.secondary",
               }}
             >
-              {formatRelativeTime(job.createdAt)}
+              {relativeTimeFromIso(job.createdAt)}
             </Typography>
           </Tooltip>
         </TableCell>