@littlebearapps/platform-admin-sdk 2.0.0 → 2.2.0

package/templates/shared/tests/integration/platform-usage.test.ts

@@ -0,0 +1,956 @@
+/**
+ * Integration Tests for Platform Usage Worker (Data Warehouse)
+ *
+ * Tests the platform-usage worker including:
+ * - Scheduled handler with adaptive sampling
+ * - Circuit breaker middleware
+ * - Anomaly detection
+ * - API endpoints reading from D1
+ * - Projected burn calculations
+ *
+ * @module tests/integration/platform-usage
+ * @created 2026-01-09
+ * @task Phase 8 - Write tests for platform-usage worker
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+// ============================================================================
+// Test Utilities
+// ============================================================================
+
+/**
+ * Mock KV namespace for testing
+ */
+interface MockKV {
+  get: (key: string) => Promise<string | null>;
+  put: (key: string, value: string) => Promise<void>;
+  delete: (key: string) => Promise<void>;
+  _store: Record<string, string>;
+}
+
+function createMockKV(initialData: Record<string, string> = {}): MockKV {
+  const store = { ...initialData };
+
+  const mockKV: MockKV = {
+    _store: store,
+    get: vi.fn((key: string) => Promise.resolve(store[key] || null)),
+    put: vi.fn((key: string, value: string) => {
+      store[key] = value;
+      return Promise.resolve();
+    }),
+    delete: vi.fn((key: string) => {
+      delete store[key];
+      return Promise.resolve();
+    }),
+  };
+
+  return mockKV;
+}
+
+// ============================================================================
+// Sampling Mode Constants (mirror worker)
+// ============================================================================
+
+enum SamplingMode {
+  FULL = 1,
+  HALF = 2,
+  QUARTER = 4,
+  MINIMAL = 24,
+}
+
+const D1_WRITE_LIMIT = 1_000_000;
+const SAMPLING_THRESHOLDS = {
+  FULL: 0.6,
+  HALF: 0.8,
+  QUARTER: 0.9,
+};
+
+// ============================================================================
+// Circuit Breaker Constants (mirror middleware)
+// ============================================================================
+
+const CB_PROJECT_KEYS = {
+  GLOBAL_STOP: 'GLOBAL_STOP_ALL',
+  TEST_PROJECT: 'PROJECT:TEST-PROJECT:STATUS',
+  MY_PROJECT: 'PROJECT:MY-PROJECT:STATUS',
+};
+
+const CB_ERROR_CODES = {
+  GLOBAL: 'GLOBAL_CIRCUIT_BREAKER',
+  PROJECT: 'PROJECT_CIRCUIT_BREAKER',
+};
+
+// ============================================================================
+// Adaptive Sampling Tests
+// ============================================================================
+
+describe('Platform Usage - Adaptive Sampling', () => {
+  describe('determineSamplingMode', () => {
+    const determineSamplingMode = (writes24h: number): SamplingMode => {
+      const usageRatio = writes24h / D1_WRITE_LIMIT;
+      if (usageRatio > SAMPLING_THRESHOLDS.QUARTER) return SamplingMode.MINIMAL;
+      if (usageRatio > SAMPLING_THRESHOLDS.HALF) return SamplingMode.QUARTER;
+      if (usageRatio > SAMPLING_THRESHOLDS.FULL) return SamplingMode.HALF;
+      return SamplingMode.FULL;
+    };
+
+    it('returns FULL when writes < 60% of limit', () => {
+      // Less than 600k writes
+      expect(determineSamplingMode(500_000)).toBe(SamplingMode.FULL);
+      expect(determineSamplingMode(0)).toBe(SamplingMode.FULL);
+      expect(determineSamplingMode(599_999)).toBe(SamplingMode.FULL);
+    });
+
+    it('returns HALF when writes between 60-80% of limit', () => {
+      // Between 600k and 800k writes
+      expect(determineSamplingMode(600_001)).toBe(SamplingMode.HALF);
+      expect(determineSamplingMode(700_000)).toBe(SamplingMode.HALF);
+      expect(determineSamplingMode(799_999)).toBe(SamplingMode.HALF);
+    });
+
+    it('returns QUARTER when writes between 80-90% of limit', () => {
+      // Between 800k and 900k writes
+      expect(determineSamplingMode(800_001)).toBe(SamplingMode.QUARTER);
+      expect(determineSamplingMode(850_000)).toBe(SamplingMode.QUARTER);
+      expect(determineSamplingMode(899_999)).toBe(SamplingMode.QUARTER);
+    });
+
+    it('returns MINIMAL when writes > 90% of limit', () => {
+      // More than 900k writes
+      expect(determineSamplingMode(900_001)).toBe(SamplingMode.MINIMAL);
+      expect(determineSamplingMode(950_000)).toBe(SamplingMode.MINIMAL);
+      expect(determineSamplingMode(999_999)).toBe(SamplingMode.MINIMAL);
+    });
+  });
+
+  describe('shouldRunThisHour', () => {
+    const shouldRunThisHour = (mode: SamplingMode, hour: number): boolean => {
+      switch (mode) {
+        case SamplingMode.FULL:
+          return true;
+        case SamplingMode.HALF:
+          return hour % 2 === 0;
+        case SamplingMode.QUARTER:
+          return hour % 4 === 0;
+        case SamplingMode.MINIMAL:
+          return hour === 0;
+      }
+    };
+
+    it('FULL mode runs every hour', () => {
+      for (let hour = 0; hour < 24; hour++) {
+        expect(shouldRunThisHour(SamplingMode.FULL, hour)).toBe(true);
+      }
+    });
+
+    it('HALF mode runs on even hours only', () => {
+      expect(shouldRunThisHour(SamplingMode.HALF, 0)).toBe(true);
+      expect(shouldRunThisHour(SamplingMode.HALF, 1)).toBe(false);
+      expect(shouldRunThisHour(SamplingMode.HALF, 2)).toBe(true);
+      expect(shouldRunThisHour(SamplingMode.HALF, 3)).toBe(false);
+      expect(shouldRunThisHour(SamplingMode.HALF, 12)).toBe(true);
+      expect(shouldRunThisHour(SamplingMode.HALF, 23)).toBe(false);
+    });
+
+    it('QUARTER mode runs every 4 hours', () => {
+      expect(shouldRunThisHour(SamplingMode.QUARTER, 0)).toBe(true);
+      expect(shouldRunThisHour(SamplingMode.QUARTER, 1)).toBe(false);
+      expect(shouldRunThisHour(SamplingMode.QUARTER, 4)).toBe(true);
+      expect(shouldRunThisHour(SamplingMode.QUARTER, 8)).toBe(true);
+      expect(shouldRunThisHour(SamplingMode.QUARTER, 12)).toBe(true);
+      expect(shouldRunThisHour(SamplingMode.QUARTER, 15)).toBe(false);
+    });
+
+    it('MINIMAL mode runs at midnight only', () => {
+      expect(shouldRunThisHour(SamplingMode.MINIMAL, 0)).toBe(true);
+      for (let hour = 1; hour < 24; hour++) {
+        expect(shouldRunThisHour(SamplingMode.MINIMAL, hour)).toBe(false);
+      }
+    });
+  });
+
+  describe('D1 Write Counting', () => {
+    it('stores write count in KV with 24h expiry pattern', async () => {
+      const kv = createMockKV();
+      const CB_KEYS = { D1_WRITES_24H: 'platform-usage:d1-writes-24h' };
+
+      // Simulate incrementing write count
+      const currentWrites = 1000;
+      await kv.put(CB_KEYS.D1_WRITES_24H, String(currentWrites + 50));
+
+      expect(kv.put).toHaveBeenCalledWith(CB_KEYS.D1_WRITES_24H, '1050');
+    });
+
+    it('handles missing write count (returns 0)', async () => {
+      const kv = createMockKV(); // Empty KV
+      const CB_KEYS = { D1_WRITES_24H: 'platform-usage:d1-writes-24h' };
+
+      const stored = await kv.get(CB_KEYS.D1_WRITES_24H);
+      const count = stored ? parseInt(stored, 10) : 0;
+
+      expect(count).toBe(0);
+    });
+  });
+});
+
+// ============================================================================
+// Circuit Breaker Tests
+// ============================================================================
+
+describe('Platform Usage - Circuit Breaker', () => {
+  describe('checkCircuitBreaker middleware', () => {
+    const checkCircuitBreaker = async (
+      projectKey: string,
+      kv: ReturnType<typeof createMockKV>
+    ): Promise<{ response: boolean; code: string | null; status: number }> => {
+      // Check global stop first
+      const globalStop = await kv.get(CB_PROJECT_KEYS.GLOBAL_STOP);
+      if (globalStop === 'true') {
+        return { response: true, code: CB_ERROR_CODES.GLOBAL, status: 503 };
+      }
+
+      // Check project-specific status
+      const projectStatus = await kv.get(projectKey);
+      if (projectStatus === 'paused') {
+        return { response: true, code: CB_ERROR_CODES.PROJECT, status: 503 };
+      }
+
+      return { response: false, code: null, status: 200 };
+    };
+
+    it('returns null when circuit breaker is open (OK to proceed)', async () => {
+      const kv = createMockKV(); // No flags set
+      const result = await checkCircuitBreaker(CB_PROJECT_KEYS.TEST_PROJECT, kv);
+
+      expect(result.response).toBe(false);
+      expect(result.code).toBeNull();
+    });
+
+    it('returns 503 when GLOBAL_STOP_ALL is set', async () => {
+      const kv = createMockKV({ [CB_PROJECT_KEYS.GLOBAL_STOP]: 'true' });
+      const result = await checkCircuitBreaker(CB_PROJECT_KEYS.TEST_PROJECT, kv);
+
+      expect(result.response).toBe(true);
+      expect(result.code).toBe(CB_ERROR_CODES.GLOBAL);
+      expect(result.status).toBe(503);
+    });
+
+    it('returns 503 when PROJECT:TEST-PROJECT:STATUS is paused', async () => {
+      const kv = createMockKV({ [CB_PROJECT_KEYS.TEST_PROJECT]: 'paused' });
+      const result = await checkCircuitBreaker(CB_PROJECT_KEYS.TEST_PROJECT, kv);
+
+      expect(result.response).toBe(true);
+      expect(result.code).toBe(CB_ERROR_CODES.PROJECT);
+      expect(result.status).toBe(503);
+    });
+
+    it('returns 503 when PROJECT:MY-PROJECT:STATUS is paused', async () => {
+      const kv = createMockKV({ [CB_PROJECT_KEYS.MY_PROJECT]: 'paused' });
+      const result = await checkCircuitBreaker(CB_PROJECT_KEYS.MY_PROJECT, kv);
+
+      expect(result.response).toBe(true);
+      expect(result.code).toBe(CB_ERROR_CODES.PROJECT);
+      expect(result.status).toBe(503);
+    });
+
+    it('global stop takes precedence over project pause', async () => {
+      const kv = createMockKV({
+        [CB_PROJECT_KEYS.GLOBAL_STOP]: 'true',
+        [CB_PROJECT_KEYS.TEST_PROJECT]: 'paused',
+      });
+      const result = await checkCircuitBreaker(CB_PROJECT_KEYS.TEST_PROJECT, kv);
+
+      expect(result.code).toBe(CB_ERROR_CODES.GLOBAL);
+    });
+  });
+
+  describe('Auto-Trip Logic', () => {
+    it('trips circuit breakers when D1 writes exceed limit', async () => {
+      const kv = createMockKV({
+        'platform-usage:d1-writes-24h': String(D1_WRITE_LIMIT + 1),
+      });
+
+      const writes24h = parseInt((await kv.get('platform-usage:d1-writes-24h')) || '0', 10);
+
+      if (writes24h >= D1_WRITE_LIMIT) {
+        await kv.put(CB_PROJECT_KEYS.TEST_PROJECT, 'paused');
+        await kv.put(CB_PROJECT_KEYS.MY_PROJECT, 'paused');
+      }
+
+      expect(kv.put).toHaveBeenCalledWith(CB_PROJECT_KEYS.TEST_PROJECT, 'paused');
+      expect(kv.put).toHaveBeenCalledWith(CB_PROJECT_KEYS.MY_PROJECT, 'paused');
+    });
+
+    it('does not trip when writes below limit', async () => {
+      const kv = createMockKV({
+        'platform-usage:d1-writes-24h': '500000',
+      });
+
+      const writes24h = parseInt((await kv.get('platform-usage:d1-writes-24h')) || '0', 10);
+
+      if (writes24h >= D1_WRITE_LIMIT) {
+        await kv.put(CB_PROJECT_KEYS.TEST_PROJECT, 'paused');
+      }
+
+      // put should only be called with the initial store setup, not for pausing
+      expect(kv._store[CB_PROJECT_KEYS.TEST_PROJECT]).toBeUndefined();
+    });
+  });
+
+  describe('Circuit Breaker Response Format', () => {
+    it('includes correct headers in 503 response', () => {
+      const errorInfo = {
+        error: 'Service paused due to resource limits',
+        code: CB_ERROR_CODES.PROJECT,
+        retryAfterSeconds: 1800,
+      };
+
+      const headers = {
+        'Content-Type': 'application/json',
+        'Retry-After': String(errorInfo.retryAfterSeconds),
+        'X-Circuit-Breaker': errorInfo.code,
+      };
+
+      expect(headers['Content-Type']).toBe('application/json');
+      expect(headers['Retry-After']).toBe('1800');
+      expect(headers['X-Circuit-Breaker']).toBe(CB_ERROR_CODES.PROJECT);
+    });
+
+    it('global circuit breaker has 1 hour retry', () => {
+      const errorInfo = {
+        code: CB_ERROR_CODES.GLOBAL,
+        retryAfterSeconds: 3600,
+      };
+
+      expect(errorInfo.retryAfterSeconds).toBe(3600);
+    });
+
+    it('project circuit breaker has 30 minute retry', () => {
+      const errorInfo = {
+        code: CB_ERROR_CODES.PROJECT,
+        retryAfterSeconds: 1800,
+      };
+
+      expect(errorInfo.retryAfterSeconds).toBe(1800);
+    });
+  });
+});
+
+// ============================================================================
+// Anomaly Detection Tests
+// ============================================================================
+
+describe('Platform Usage - Anomaly Detection', () => {
+  describe('7-Day Rolling Stats', () => {
+    it('calculates average from daily rollups', () => {
+      const dailyValues = [100, 120, 110, 130, 115, 125, 105];
+      const avg = dailyValues.reduce((sum, v) => sum + v, 0) / dailyValues.length;
+
+      expect(avg).toBeCloseTo(115, 1);
+    });
+
+    it('calculates standard deviation correctly', () => {
+      const values = [100, 120, 110, 130, 115, 125, 105];
+      const avg = values.reduce((sum, v) => sum + v, 0) / values.length;
+      const variance = values.reduce((sum, v) => sum + Math.pow(v - avg, 2), 0) / values.length;
+      const stddev = Math.sqrt(variance);
+
+      expect(stddev).toBeGreaterThan(0);
+      expect(stddev).toBeLessThan(15); // Should be around 9-10
+    });
+
+    it('requires minimum 7 days of data', () => {
+      const samples = 5; // Less than 7
+      const shouldAlert = samples >= 7;
+
+      expect(shouldAlert).toBe(false);
+    });
+  });
+
+  describe('Anomaly Threshold', () => {
+    it('detects anomaly when value > 3 stddev above mean', () => {
+      const avg = 100;
+      const stddev = 10;
+      const currentValue = 135; // 3.5 stddev above
+
+      const deviation = (currentValue - avg) / stddev;
+
+      expect(deviation).toBeGreaterThan(3);
+    });
+
+    it('does not detect anomaly for normal variation', () => {
+      const avg = 100;
+      const stddev = 10;
+      const currentValue = 120; // 2 stddev above
+
+      const deviation = (currentValue - avg) / stddev;
+
+      expect(deviation).toBeLessThan(3);
+    });
+
+    it('handles zero stddev gracefully', () => {
+      const avg = 100;
+      const stddev = 0;
+      const currentValue = 150;
+
+      // Use 1 as minimum stddev to avoid division by zero
+      const safeStddev = stddev || 1;
+      const deviation = (currentValue - avg) / safeStddev;
+
+      expect(deviation).toBe(50);
+    });
+  });
+
+  describe('Anomaly Recording', () => {
+    it('stores anomaly with correct fields', () => {
+      const anomaly = {
+        id: '1704758400000-abc1234',
+        detected_at: Math.floor(Date.now() / 1000),
+        metric_name: 'total_cost_usd',
+        project: 'all',
+        current_value: 150,
+        rolling_avg: 100,
+        rolling_stddev: 10,
+        deviation_factor: 5,
+        alert_sent: 0,
+        resolved: 0,
+      };
+
+      expect(anomaly.metric_name).toBe('total_cost_usd');
+      expect(anomaly.deviation_factor).toBeGreaterThan(3);
+      expect(anomaly.alert_sent).toBe(0);
+    });
+
+    it('tracks which metrics to monitor', () => {
+      const metricsToMonitor = ['workers_requests', 'd1_rows_written', 'total_cost_usd'];
+
+      expect(metricsToMonitor).toContain('workers_requests');
+      expect(metricsToMonitor).toContain('d1_rows_written');
+      expect(metricsToMonitor).toContain('total_cost_usd');
+      expect(metricsToMonitor).toHaveLength(3);
+    });
+  });
+});
+
+// ============================================================================
+// API Endpoint Tests (D1 Data Source)
+// ============================================================================
+
+describe('Platform Usage - API Endpoints', () => {
+  describe('GET /usage', () => {
+    it('parses period parameter correctly', () => {
+      const parseQueryParams = (url: URL): { period: string; project: string } => {
+        const period = url.searchParams.get('period') || '24h';
+        const project = url.searchParams.get('project') || 'all';
+        return { period, project };
+      };
+
+      const url = new URL('https://example.com/usage?period=7d&project=test-project');
+      const params = parseQueryParams(url);
+
+      expect(params.period).toBe('7d');
+      expect(params.project).toBe('test-project');
+    });
+
+    it('defaults to 24h period and all project', () => {
+      const parseQueryParams = (url: URL): { period: string; project: string } => {
+        const period = url.searchParams.get('period') || '24h';
+        const project = url.searchParams.get('project') || 'all';
+        return { period, project };
+      };
+
+      const url = new URL('https://example.com/usage');
+      const params = parseQueryParams(url);
+
+      expect(params.period).toBe('24h');
+      expect(params.project).toBe('all');
+    });
+
+    it('includes dataSource field indicating D1 or GraphQL', () => {
+      const response = {
+        success: true,
+        period: '24h',
+        dataSource: 'd1',
+        timestamp: new Date().toISOString(),
+      };
+
+      expect(response.dataSource).toBe('d1');
+    });
+  });
+
+  describe('GET /usage/daily', () => {
+    it('returns daily cost breakdown in correct format', () => {
+      const dailyCosts = {
+        days: [
+          {
+            date: '2026-01-08',
+            workers: 0.5,
+            d1: 0.2,
+            kv: 0.1,
+            r2: 0.3,
+            durableObjects: 0.05,
+            vectorize: 0.02,
+            aiGateway: 0.1,
+            workersAI: 0.15,
+            queues: 0.01,
+            total: 1.43,
+          },
+        ],
+        totals: {
+          workers: 0.5,
+          d1: 0.2,
+          kv: 0.1,
+          r2: 0.3,
+          durableObjects: 0.05,
+          vectorize: 0.02,
+          aiGateway: 0.1,
+          workersAI: 0.15,
+          queues: 0.01,
+          total: 1.43,
+        },
+        period: {
+          start: '2026-01-08',
+          end: '2026-01-08',
+        },
+      };
+
+      expect(dailyCosts.days).toHaveLength(1);
+      expect(dailyCosts.days[0].date).toBe('2026-01-08');
+      expect(dailyCosts.totals.total).toBeCloseTo(1.43, 2);
+    });
+
+    it('falls back to GraphQL when D1 has no data', () => {
+      const d1Data = { days: [] };
+      const shouldFallback = !d1Data || d1Data.days.length === 0;
+
+      expect(shouldFallback).toBe(true);
+    });
+  });
+
+  describe('Response Caching', () => {
+    it('caches successful responses in KV', async () => {
+      const kv = createMockKV();
+      const cacheKey = 'usage:24h:all';
+      const cacheData = JSON.stringify({ success: true, data: {} });
+
+      await kv.put(cacheKey, cacheData);
+
+      expect(kv.put).toHaveBeenCalledWith(cacheKey, cacheData);
+    });
+
+    it('uses correct cache key format', () => {
+      const getCacheKey = (prefix: string, period: string, project: string): string => {
+        return `${prefix}:${period}:${project}`;
+      };
+
+      expect(getCacheKey('usage', '24h', 'all')).toBe('usage:24h:all');
+      expect(getCacheKey('usage', '7d', 'test-project')).toBe('usage:7d:test-project');
+      expect(getCacheKey('daily', '30d', 'my-project')).toBe('daily:30d:my-project');
+    });
+  });
+});
+
+// ============================================================================
+// Projected Burn Tests
+// ============================================================================
+
+describe('Platform Usage - Projected Burn', () => {
+  describe('Daily Burn Rate Calculation', () => {
+    it('calculates daily rate from current month data', () => {
+      const monthData = [
+        { date: '2026-01-01', total_cost_usd: 5.0 },
+        { date: '2026-01-02', total_cost_usd: 6.0 },
+        { date: '2026-01-03', total_cost_usd: 5.5 },
+        { date: '2026-01-04', total_cost_usd: 6.5 },
+        { date: '2026-01-05', total_cost_usd: 5.0 },
+      ];
+
+      const totalCost = monthData.reduce((sum, d) => sum + d.total_cost_usd, 0);
+      const days = monthData.length;
+      const dailyRate = totalCost / days;
+
+      expect(dailyRate).toBeCloseTo(5.6, 1);
+    });
+
+    it('handles zero days gracefully', () => {
+      const monthData: { date: string; total_cost_usd: number }[] = [];
+      const days = monthData.length;
+      const dailyRate =
+        days > 0 ? monthData.reduce((sum, d) => sum + d.total_cost_usd, 0) / days : 0;
+
+      expect(dailyRate).toBe(0);
+    });
+  });
+
+  describe('Monthly Projection', () => {
+    it('projects full month cost correctly', () => {
+      const currentDate = new Date('2026-01-10');
+      const dayOfMonth = currentDate.getDate(); // 10
+      const daysInMonth = 31;
+      const daysRemaining = daysInMonth - dayOfMonth; // 21
+
+      const currentSpend = 50; // $50 in first 10 days
+      const dailyRate = currentSpend / dayOfMonth; // $5/day
+      const projectedTotal = currentSpend + dailyRate * daysRemaining;
+
+      expect(projectedTotal).toBeCloseTo(155, 0); // $50 + $5 * 21 = $155
+    });
+
+    it('calculates percentage change vs last month', () => {
+      const projectedMonthly = 155;
+      const lastMonthCost = 140;
+      const pctChange = ((projectedMonthly - lastMonthCost) / lastMonthCost) * 100;
+
+      expect(pctChange).toBeCloseTo(10.7, 1);
+    });
+  });
+
+  describe('Confidence Level', () => {
+    it('returns low confidence with < 10 days data', () => {
+      const days = 5;
+      const confidence = days >= 20 ? 'high' : days >= 10 ? 'medium' : 'low';
+
+      expect(confidence).toBe('low');
+    });
+
+    it('returns medium confidence with 10-19 days data', () => {
+      const days = 15;
+      const confidence = days >= 20 ? 'high' : days >= 10 ? 'medium' : 'low';
+
+      expect(confidence).toBe('medium');
+    });
+
+    it('returns high confidence with >= 20 days data', () => {
+      const days = 25;
+      const confidence = days >= 20 ? 'high' : days >= 10 ? 'medium' : 'low';
+
+      expect(confidence).toBe('high');
+    });
+  });
+
+  describe('ProjectedBurn Interface', () => {
+    it('includes all required fields', () => {
+      const projectedBurn = {
+        current_period_days: 10,
+        current_period_cost: 50,
+        daily_burn_rate: 5,
+        projected_monthly_cost: 155,
+        projected_vs_last_month_pct: 10.7,
+        last_month_cost: 140,
+        confidence: 'medium' as const,
+      };
+
+      expect(projectedBurn.current_period_days).toBe(10);
+      expect(projectedBurn.daily_burn_rate).toBe(5);
+      expect(projectedBurn.confidence).toBe('medium');
+      expect(projectedBurn.projected_monthly_cost).toBe(155);
+    });
+  });
+});
+
+// ============================================================================
+// Data Warehouse Tests (3-Tier Rollup)
+// ============================================================================
+
+describe('Platform Usage - Data Warehouse', () => {
+  describe('Hourly Snapshots (Tier 1)', () => {
+    it('generates valid snapshot hour format', () => {
+      const getCurrentHour = (): string => {
+        const now = new Date();
+        now.setMinutes(0, 0, 0);
+        // Format: YYYY-MM-DDTHH:00:00Z (replace :MM:SS.sssZ with :00:00Z)
+        return now.toISOString().replace(/:\d{2}:\d{2}\.\d{3}Z$/, ':00:00Z');
+      };
+
+      const hour = getCurrentHour();
+      expect(hour).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:00:00Z$/);
+    });
+
+    it('includes all cost categories', () => {
+      const snapshot = {
+        workers_cost_usd: 0.5,
+        d1_cost_usd: 0.2,
+        kv_cost_usd: 0.1,
+        r2_cost_usd: 0.3,
+        do_cost_usd: 0.05,
+        vectorize_cost_usd: 0.02,
+        aigateway_cost_usd: 0.1,
+        pages_cost_usd: 0.0,
+        queues_cost_usd: 0.01,
+        workersai_cost_usd: 0.15,
+        total_cost_usd: 1.43,
+      };
+
+      const calculatedTotal =
+        snapshot.workers_cost_usd +
+        snapshot.d1_cost_usd +
+        snapshot.kv_cost_usd +
+        snapshot.r2_cost_usd +
+        snapshot.do_cost_usd +
+        snapshot.vectorize_cost_usd +
+        snapshot.aigateway_cost_usd +
+        snapshot.pages_cost_usd +
+        snapshot.queues_cost_usd +
+        snapshot.workersai_cost_usd;
+
+      expect(calculatedTotal).toBeCloseTo(snapshot.total_cost_usd, 2);
+    });
+  });
+
+  describe('Daily Rollup (Tier 2)', () => {
+    it('aggregates hourly snapshots correctly', () => {
+      const hourlySnapshots = [
+        { workers_requests: 100, total_cost_usd: 0.5 },
+        { workers_requests: 150, total_cost_usd: 0.7 },
+        { workers_requests: 120, total_cost_usd: 0.6 },
+      ];
+
+      const dailyRollup = {
+        workers_requests: hourlySnapshots.reduce((sum, h) => sum + h.workers_requests, 0),
+        total_cost_usd: hourlySnapshots.reduce((sum, h) => sum + h.total_cost_usd, 0),
+        samples_count: hourlySnapshots.length,
+      };
+
+      expect(dailyRollup.workers_requests).toBe(370);
+      expect(dailyRollup.total_cost_usd).toBeCloseTo(1.8, 1);
+      expect(dailyRollup.samples_count).toBe(3);
+    });
+  });
+
+  describe('Monthly Rollup (Tier 3)', () => {
+    it('aggregates daily rollups correctly', () => {
+      const dailyRollups = [
+        { total_cost_usd: 5.0 },
+        { total_cost_usd: 6.0 },
+        { total_cost_usd: 5.5 },
+      ];
+
+      const monthlyRollup = {
+        total_cost_usd: dailyRollups.reduce((sum, d) => sum + d.total_cost_usd, 0),
+        days_count: dailyRollups.length,
+      };
+
+      expect(monthlyRollup.total_cost_usd).toBeCloseTo(16.5, 1);
+      expect(monthlyRollup.days_count).toBe(3);
+    });
+  });
+
+  describe('Data Retention', () => {
+    it('hourly data retained for 7 days', () => {
+      const HOURLY_RETENTION_DAYS = 7;
+      expect(HOURLY_RETENTION_DAYS).toBe(7);
+    });
+
+    it('daily data retained for 90 days', () => {
+      const DAILY_RETENTION_DAYS = 90;
+      expect(DAILY_RETENTION_DAYS).toBe(90);
+    });
+
+    it('monthly data retained forever', () => {
+      const MONTHLY_RETENTION = 'forever';
+      expect(MONTHLY_RETENTION).toBe('forever');
+    });
+  });
+});
+
+// ============================================================================
+// GitHub Billing Integration Tests
+// ============================================================================
+
+describe('Platform Usage - GitHub Enterprise Billing', () => {
+  describe('GitHub API Endpoints', () => {
+    it('queries correct billing endpoints', () => {
+      const endpoints = [
+        'https://api.github.com/orgs/my-org/settings/billing/advanced-security',
+        'https://api.github.com/orgs/my-org/settings/billing/actions',
+        'https://api.github.com/orgs/my-org/settings/billing/shared-storage',
+      ];
+
+      expect(endpoints).toHaveLength(3);
+      expect(endpoints[0]).toContain('advanced-security');
+      expect(endpoints[1]).toContain('actions');
+      expect(endpoints[2]).toContain('shared-storage');
+    });
+
+    it('requires GITHUB_TOKEN to collect billing', () => {
+      const env = { GITHUB_TOKEN: undefined };
+      const canCollect = !!env.GITHUB_TOKEN;
+
+      expect(canCollect).toBe(false);
+    });
+  });
+
+  describe('Third-Party Usage Storage', () => {
+    it('stores GitHub billing data with correct provider', () => {
+      const usageRecord = {
+        provider: 'github',
+        resource_type: 'advanced_security_seats',
+        usage_value: 5,
+        usage_unit: 'seats',
+      };
+
+      expect(usageRecord.provider).toBe('github');
+      expect(usageRecord.resource_type).toBe('advanced_security_seats');
+    });
+
+    it('stores multiple GitHub metrics', () => {
+      const metricsToStore = [
+        { resource_type: 'advanced_security_seats', usage_unit: 'seats' },
+        { resource_type: 'actions_minutes', usage_unit: 'minutes' },
+        { resource_type: 'storage_bytes', usage_unit: 'bytes' },
+      ];
+
+      expect(metricsToStore).toHaveLength(3);
+    });
+  });
+});
+
+// ============================================================================
+// Slack Alert Tests
+// ============================================================================
+
+describe('Platform Usage - Slack Alerts', () => {
+  describe('Anomaly Alert Format', () => {
+    it('includes all required fields', () => {
+      const alert = {
+        text: ':warning: Usage Anomaly Detected',
+        attachments: [
+          {
+            color: 'warning',
+            fields: [
+              { title: 'Metric', value: 'total_cost_usd', short: true },
+              { title: 'Deviation', value: '3.5 stddev', short: true },
+              { title: 'Current', value: '$150.00', short: true },
+              { title: '7-Day Avg', value: '$100.00', short: true },
+              { title: 'Projected Monthly', value: '$450.00', short: true },
+            ],
+          },
+        ],
+      };
+
+      expect(alert.text).toContain('Anomaly');
+      expect(alert.attachments[0].fields).toHaveLength(5);
+    });
+
+    it('uses danger colour for high deviation', () => {
+      const deviation = 5.5;
+      const colour = deviation > 5 ? 'danger' : 'warning';
+
+      expect(colour).toBe('danger');
+    });
+
+    it('uses warning colour for moderate deviation', () => {
+      const deviation = 3.5;
+      const colour = deviation > 5 ? 'danger' : 'warning';
+
+      expect(colour).toBe('warning');
+    });
+  });
+
+  describe('Circuit Breaker Alert Format', () => {
+    it('includes write count and limit', () => {
+      const alert = {
+        text: ':rotating_light: Circuit Breaker Tripped',
+        attachments: [
+          {
+            color: 'danger',
+            fields: [
+              { title: 'D1 Writes (24h)', value: '1,000,001', short: true },
+              { title: 'Limit', value: '1,000,000', short: true },
+              { title: 'Action', value: 'Test Project & My Project paused for 24h', short: true },
+            ],
+          },
+        ],
+      };
+
+      expect(alert.attachments[0].color).toBe('danger');
+      expect(alert.attachments[0].fields.find((f) => f.title === 'Limit')?.value).toBe('1,000,000');
+    });
+  });
+
+  describe('Alert Rate Limiting', () => {
+    it('skips alert when webhook URL not configured', () => {
+      const env = { SLACK_WEBHOOK_URL: undefined };
+      const shouldSendAlert = !!env.SLACK_WEBHOOK_URL;
+
+      expect(shouldSendAlert).toBe(false);
+    });
+  });
+});
+
+// ============================================================================
+// HTTP Endpoint Tests
+// ============================================================================
+
+describe('Platform Usage - HTTP Endpoints', () => {
+  describe('Health Check', () => {
+    it('returns health status JSON', () => {
+      const response = {
+        status: 'ok',
+        service: 'platform-usage',
+        timestamp: expect.any(String),
+      };
+
+      expect(response.status).toBe('ok');
+      expect(response.service).toBe('platform-usage');
+    });
+  });
+
+  describe('Circuit Breaker Status Endpoint', () => {
+    it('returns all circuit breaker states', () => {
+      const response = {
+        success: true,
+        circuitBreakers: {
+          globalStop: false,
+          testProjectPaused: false,
+          brandCopilotPaused: false,
+        },
+        sampling: {
+          currentMode: 'FULL',
+          d1Writes24h: 50000,
+          d1WriteLimit: 1000000,
+          d1WritePercentage: 5,
+        },
+      };
+
+      expect(response.circuitBreakers).toBeDefined();
+      expect(response.sampling).toBeDefined();
+    });
+  });
+
+  describe('Settings Endpoint', () => {
+    it('accepts threshold settings updates', () => {
+      const settings = {
+        workers: { warningPct: 50, highPct: 75, criticalPct: 90, absoluteMax: 5, enabled: true },
+        d1: { warningPct: 40, highPct: 60, criticalPct: 80, absoluteMax: 20, enabled: true },
+      };
+
+      expect(settings.workers.absoluteMax).toBe(5);
+      expect(settings.d1.absoluteMax).toBe(20);
+    });
+  });
+
+  describe('Available Endpoints', () => {
+    it('lists all endpoints correctly', () => {
+      const endpoints = [
+        '/',
+        '/usage',
+        '/usage/daily',
+        '/usage/compare',
+        '/costs',
+        '/costs/thresholds',
+        '/costs/enhanced',
+        '/health',
+        '/settings',
+        '/circuit-breaker/status',
+        '/circuit-breaker/reset',
+        '/workersai',
+      ];
+
+      expect(endpoints).toContain('/usage');
+      expect(endpoints).toContain('/usage/daily');
+      expect(endpoints).toContain('/circuit-breaker/status');
+    });
+  });
+});