Improve metrics clarity, exploration, and refresh reliability

src/lib/metrics.ts

@@ -0,0 +1,49 @@
+export type MetricsDays = 1 | 7 | 30;
+
+export function parseMetricsDays(value: string | null | undefined): MetricsDays {
+    const days = Number(value ?? 7);
+    return days === 1 || days === 7 || days === 30 ? days : 7;
+}
+
+/** All durations are hours. Observed is known server time, not collection coverage. */
+export interface Utilization {
+    observed: number;
+    active: number;
+    idle: number;
+    unknown: number;
+    playerHours: number;
+}
+
+export interface ServerMetrics extends Utilization {
+    server: string;
+}
+
+export interface MapMetrics extends Utilization {
+    game: string;
+    map: string;
+    /** Map wall time, not summed server time. */
+    full: number;
+    capacityObserved: number;
+}
+
+export interface MetricPoint extends Utilization {
+    /** UTC bucket boundary, including when the selected interval starts later. */
+    at: number;
+    startAt: number;
+    endAt: number;
+    partial: boolean;
+}
+
+export interface MetricsData {
+    days: MetricsDays;
+    since: number;
+    now: number;
+    /** Retained sample timestamps describe collection, not gameplay freshness. */
+    firstRetainedSampleAt: number | null;
+    latestSampleAt: number | null;
+    registeredServerCount: number;
+    summary: Utilization;
+    servers: ServerMetrics[];
+    maps: MapMetrics[];
+    points: MetricPoint[];
+}