Expand telemetry: anonymous IDs, D1 storage, new events

- Anonymous persistent client ID (localStorage UUID) attached
  to all telemetry and error payloads
- New events: scenario_browsed, turn_completed (with per-phase
  timing), tutorial_started/completed/skipped
- D1 database for persistent event storage with IP hash and UA
- Server uses waitUntil for non-blocking D1 writes
- Both /telemetry and /error endpoints write to D1
- 1120 tests across 66 suites

Author: rgilks

migrations/0001_create_events.sql

@@ -0,0 +1,15 @@
+-- Telemetry and error events table
+CREATE TABLE IF NOT EXISTS events (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts        INTEGER NOT NULL,
+  anon_id   TEXT,
+  event     TEXT NOT NULL,
+  props     TEXT,
+  ip_hash   TEXT,
+  ua        TEXT,
+  created   TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX idx_events_ts ON events(ts);
+CREATE INDEX idx_events_event ON events(event);
+CREATE INDEX idx_events_anon ON events(anon_id);

src/client/main.ts

@@ -163,6 +163,12 @@ class GameClient {
   private connection: ConnectionManager;
   private turnTimer!: TurnTimerManager;
 
+  // Phase timing for telemetry
+  private phaseStartedAt: number | null = null;
+  private turnStartedAt: number | null = null;
+  private phaseDurations: Record<string, number> = {};
+  private lastTurnNumber = -1;
+
   // Presentation orchestration deps
   // (lazy — renderer/ui available after constructor)
   private _presentationDeps: PresentationDeps | null = null;
@@ -284,6 +290,7 @@ class GameClient {
     );
     this.ui = new UIManager();
     this.tutorial = new Tutorial();
+    this.tutorial.onTelemetry = (evt) => track(evt);
     this.tooltipEl = byId('shipTooltip');
 
     this.connection = createConnectionManager({
@@ -393,8 +400,16 @@ class GameClient {
   }
 
   private setState(newState: ClientState) {
+    const prevState = this.ctx.state;
     this.ctx.state = newState;
 
+    // Accumulate phase duration for telemetry
+    this.recordPhaseDuration(prevState);
+
+    if (newState.startsWith('playing_')) {
+      this.phaseStartedAt = Date.now();
+    }
+
     // Hide tooltip on state changes
     hide(this.tooltipEl);
 
@@ -568,6 +583,10 @@ class GameClient {
     this.ctx.scenario = scenario;
     this.ctx.playerId = 0;
     this.lastLoggedTurn = -1;
+    this.lastTurnNumber = -1;
+    this.turnStartedAt = null;
+    this.phaseStartedAt = null;
+    this.phaseDurations = {};
     this.renderer.setPlayerId(0);
     this.ctx.transport = this.createLocalTransport();
 
@@ -851,6 +870,10 @@ class GameClient {
         this.dispatch({ type: 'exitToMenu' });
         return;
 
+      case 'backToMenu':
+        track('scenario_browsed');
+        return;
+
       case 'selectShip':
         this.dispatch({
           type: 'selectShip',
@@ -1092,6 +1115,37 @@ class GameClient {
     }
   }
 
+  // --- Phase timing telemetry ---
+
+  private recordPhaseDuration(prevState: ClientState) {
+    if (this.phaseStartedAt !== null && prevState.startsWith('playing_')) {
+      const phase = prevState.replace('playing_', '');
+      // Skip non-player phases
+      if (phase !== 'opponentTurn' && phase !== 'movementAnim') {
+        const elapsed = Date.now() - this.phaseStartedAt;
+        this.phaseDurations[phase] =
+          (this.phaseDurations[phase] ?? 0) + elapsed;
+      }
+      this.phaseStartedAt = null;
+    }
+  }
+
+  private emitTurnCompleted() {
+    if (this.turnStartedAt === null) return;
+
+    const totalMs = Date.now() - this.turnStartedAt;
+    track('turn_completed', {
+      turn: this.lastTurnNumber,
+      totalMs,
+      phases: { ...this.phaseDurations },
+      scenario: this.ctx.scenario,
+      mode: this.ctx.isLocalGame ? 'local' : 'multiplayer',
+    });
+
+    this.phaseDurations = {};
+    this.turnStartedAt = Date.now();
+  }
+
   // --- Game actions ---
 
   private onAnimationComplete() {
@@ -1113,6 +1167,15 @@ class GameClient {
     );
 
     if (transition.turnLogNumber !== null && transition.turnLogPlayerLabel) {
+      // Emit turn_completed for the previous turn
+      if (this.lastTurnNumber > 0) {
+        this.emitTurnCompleted();
+      } else {
+        // First turn — just start timing
+        this.turnStartedAt = Date.now();
+      }
+
+      this.lastTurnNumber = transition.turnLogNumber;
       this.lastLoggedTurn = transition.turnLogNumber;
       this.ui.logTurn(transition.turnLogNumber, transition.turnLogPlayerLabel);
     }

src/client/telemetry.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+
+import { getOrCreateAnonId, type StorageLike } from './telemetry';
+
+const mockStorage = (initial: Record<string, string> = {}): StorageLike => {
+  const store = { ...initial };
+  return {
+    getItem: (key: string) => store[key] ?? null,
+    setItem: (key: string, value: string) => {
+      store[key] = value;
+    },
+  };
+};
+
+describe('getOrCreateAnonId', () => {
+  it('generates a UUID when storage is empty', () => {
+    const storage = mockStorage();
+    const id = getOrCreateAnonId(storage);
+
+    expect(id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/,
+    );
+  });
+
+  it('persists the ID to storage', () => {
+    const storage = mockStorage();
+    const id = getOrCreateAnonId(storage);
+
+    expect(storage.getItem('deltav_anon_id')).toBe(id);
+  });
+
+  it('returns existing ID from storage', () => {
+    const storage = mockStorage({
+      deltav_anon_id: 'existing-id',
+    });
+    const id = getOrCreateAnonId(storage);
+
+    expect(id).toBe('existing-id');
+  });
+
+  it('returns same ID on repeated calls', () => {
+    const storage = mockStorage();
+    const first = getOrCreateAnonId(storage);
+    const second = getOrCreateAnonId(storage);
+
+    expect(first).toBe(second);
+  });
+
+  it('falls back to random ID when storage throws', () => {
+    const storage: StorageLike = {
+      getItem: () => {
+        throw new Error('blocked');
+      },
+      setItem: () => {
+        throw new Error('blocked');
+      },
+    };
+    const id = getOrCreateAnonId(storage);
+
+    expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-/);
+  });
+});

src/client/telemetry.ts

@@ -2,15 +2,48 @@
 //
 // Both track() and reportError() fire-and-forget POST
 // to server endpoints. No PII is collected. Payloads are
-// structured JSON logged via console.* on the server,
-// captured automatically by Cloudflare Workers Logs.
+// structured JSON logged via console.* on the server
+// and stored in D1 for querying.
+
+export interface StorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+const ANON_ID_KEY = 'deltav_anon_id';
+
+export const getOrCreateAnonId = (storage: StorageLike): string => {
+  try {
+    const existing = storage.getItem(ANON_ID_KEY);
+    if (existing) return existing;
+
+    const id = crypto.randomUUID();
+    storage.setItem(ANON_ID_KEY, id);
+    return id;
+  } catch {
+    // Fallback for incognito / storage disabled
+    return crypto.randomUUID();
+  }
+};
+
+// Eagerly resolve on module load
+let anonId: string;
+try {
+  anonId = getOrCreateAnonId(localStorage);
+} catch {
+  anonId = crypto.randomUUID();
+}
 
 const post = (path: string, body: Record<string, unknown>): void => {
   try {
     fetch(path, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(body),
+      body: JSON.stringify({
+        ...body,
+        anonId,
+        ts: Date.now(),
+      }),
       keepalive: true,
     }).catch(() => {});
   } catch {
@@ -21,11 +54,7 @@ const post = (path: string, body: Record<string, unknown>): void => {
 // --- Telemetry ---
 
 export const track = (event: string, props?: Record<string, unknown>): void => {
-  post('/telemetry', {
-    event,
-    ...props,
-    ts: Date.now(),
-  });
+  post('/telemetry', { event, ...props });
 };
 
 // --- Error reporting ---
@@ -37,7 +66,6 @@ export const reportError = (
   post('/error', {
     error,
     ...context,
-    ts: Date.now(),
     url: window.location.href,
     ua: navigator.userAgent,
   });

src/client/tutorial.ts

@@ -65,6 +65,9 @@ export class Tutorial {
   private progressEl: HTMLElement;
   private activeStepId: string | null = null;
 
+  /** External callback for telemetry events */
+  onTelemetry: ((event: string) => void) | null = null;
+
   constructor() {
     this.tipEl = byId('tutorialTip');
     this.textEl = byId('tutorialTipText');
@@ -114,6 +117,10 @@ export class Tutorial {
   }
 
   private showStep(step: TutorialStep) {
+    if (this.shownSteps.size === 0) {
+      this.onTelemetry?.('tutorial_started');
+    }
+
     this.activeStepId = step.id;
     this.textEl.textContent = step.text;
     show(this.tipEl, 'block');
@@ -143,13 +150,15 @@ export class Tutorial {
 
     // Check if all steps are shown
     if (this.shownSteps.size >= STEPS.length) {
+      this.onTelemetry?.('tutorial_completed');
       this.complete();
     }
 
     this.hideTip();
   }
 
   private skip() {
+    this.onTelemetry?.('tutorial_skipped');
     this.complete();
     this.hideTip();
   }

src/client/ui/events.ts

@@ -22,4 +22,6 @@ export type UIEvent =
   | { type: 'rematch' }
   | { type: 'exit' }
   | { type: 'selectShip'; shipId: string }
-  | { type: 'chat'; text: string };
+  | { type: 'chat'; text: string }
+  // Navigation
+  | { type: 'backToMenu' };

src/client/ui/ui.ts

@@ -189,6 +189,7 @@ export class UIManager {
     }
 
     byId('backBtn').addEventListener('click', () => {
+      this.onEvent?.({ type: 'backToMenu' });
       this.showMenu();
     });