@littlebearapps/platform-admin-sdk 2.0.0 → 2.2.0

package/templates/shared/tests/e2e/usage-api.test.ts

@@ -0,0 +1,909 @@
+/**
+ * Usage API - End-to-End Tests
+ *
+ * Tests the full request/response cycle for usage API endpoints:
+ * - GET /usage - Get usage metrics with filtering
+ * - GET /usage/costs - Get cost breakdown
+ * - GET /usage/thresholds - Get threshold warnings
+ * - GET /usage/compare - Period comparison
+ * - GET /usage/settings - Get alert settings
+ * - PUT /usage/settings - Update alert settings
+ *
+ * Uses mocked CloudflareGraphQL and KV to test:
+ * - Query parameter parsing
+ * - Response formatting
+ * - Error handling
+ * - Caching behaviour
+ *
+ * @module tests/e2e/usage-api
+ * @created 2026-01-05
+ * @task task-17.23 - E2E tests for filtering/sorting
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { KVNamespace, D1Database } from '@cloudflare/workers-types';
+import { MockKVNamespace, MockD1Database } from '../helpers/mock-storage';
+import { clearRegistryCache } from '../../dashboard/src/lib/cloudflare';
+
+// Mock the CloudflareGraphQL class since it makes external API calls
+vi.mock('../../dashboard/src/lib/cloudflare', async (importOriginal) => {
+  const actual = (await importOriginal()) as Record<string, unknown>;
+
+  // Create a mock class with static methods using Object.assign for proper typing
+  // Note: Vitest 4 requires regular functions (not arrow functions) for constructor mocks
+  const MockCloudflareGraphQL = Object.assign(
+    vi.fn().mockImplementation(function () {
+      return {
+        getAllMetrics: vi.fn().mockResolvedValue(MOCK_USAGE_DATA),
+        getAllEnhancedMetrics: vi.fn().mockResolvedValue({
+          ...MOCK_USAGE_DATA,
+          sparklines: {
+            workersRequests: { points: [], trend: 'stable' },
+            workersErrors: { points: [], trend: 'stable' },
+            d1RowsRead: { points: [], trend: 'stable' },
+            kvReads: { points: [], trend: 'stable' },
+          },
+          errorBreakdown: [],
+          queues: [],
+          cache: { hits: 0, misses: 0, hitRate: 0 },
+          comparison: {
+            workersRequests: { current: 100, previous: 80, trend: 'up', percentChange: 25 },
+            workersErrors: { current: 5, previous: 5, trend: 'stable', percentChange: 0 },
+            d1RowsRead: { current: 1000, previous: 900, trend: 'up', percentChange: 11.1 },
+            totalCost: { current: 5, previous: 4, trend: 'up', percentChange: 25 },
+          },
+        }),
+        getMetricsForDateRange: vi.fn().mockResolvedValue(MOCK_USAGE_DATA),
+      };
+    }),
+    {
+      // Static methods
+      getSamePeriodLastMonth: vi.fn((startDate: string, endDate: string) => {
+        // Calculate 1 month prior
+        const start = new Date(startDate);
+        const end = new Date(endDate);
+        start.setMonth(start.getMonth() - 1);
+        end.setMonth(end.getMonth() - 1);
+        return {
+          startDate: start.toISOString().split('T')[0],
+          endDate: end.toISOString().split('T')[0],
+        };
+      }),
+      validateCustomDateRange: vi.fn(
+        (params: {
+          startDate: string;
+          endDate: string;
+          priorStartDate?: string;
+          priorEndDate?: string;
+        }) => {
+          const { startDate, endDate, priorStartDate, priorEndDate } = params;
+          // Simple validation for tests
+          if (!startDate || !endDate) {
+            return { error: 'Missing date parameters' };
+          }
+          const start = new Date(startDate);
+          const end = new Date(endDate);
+          if (isNaN(start.getTime()) || isNaN(end.getTime())) {
+            return { error: 'Invalid date format' };
+          }
+          if (end < start) {
+            return { error: 'End date must be on or after start date' };
+          }
+          // Calculate prior period (same duration ending day before start)
+          const duration = end.getTime() - start.getTime();
+          const priorEnd = new Date(start.getTime() - 24 * 60 * 60 * 1000);
+          const priorStart = new Date(priorEnd.getTime() - duration);
+          return {
+            current: { startDate, endDate },
+            prior: {
+              startDate: priorStartDate || priorStart.toISOString().split('T')[0],
+              endDate: priorEndDate || priorEnd.toISOString().split('T')[0],
+            },
+          };
+        }
+      ),
+    }
+  );
+
+  return {
+    ...actual,
+    CloudflareGraphQL: MockCloudflareGraphQL,
+  };
+});
+
+// Import the worker after mocking
+import UsageWorker from '../../workers/platform-usage';
+
+// Mock usage data fixture - matches AccountUsage interface from graphql.ts
+const MOCK_USAGE_DATA = {
+  period: '30d' as const,
+  workers: [
+    {
+      scriptName: 'my-project-api',
+      requests: 100000,
+      cpuTimeMs: 5000,
+      duration50thMs: 10,
+      duration99thMs: 100,
+      errors: 50,
+    },
+    {
+      scriptName: 'platform-dashboard',
+      requests: 50000,
+      cpuTimeMs: 2000,
+      duration50thMs: 5,
+      duration99thMs: 50,
+      errors: 10,
+    },
+    {
+      scriptName: 'test-project-api',
+      requests: 25000,
+      cpuTimeMs: 1000,
+      duration50thMs: 3,
+      duration99thMs: 30,
+      errors: 5,
+    },
+  ],
+  d1: [
+    {
+      databaseId: 'db-001',
+      databaseName: 'my-project-db',
+      rowsRead: 500000,
+      rowsWritten: 10000,
+      queryCount: 50000,
+    },
+    {
+      databaseId: 'db-002',
+      databaseName: 'platform-metrics',
+      rowsRead: 100000,
+      rowsWritten: 5000,
+      queryCount: 10000,
+    },
+  ],
+  kv: [
+    {
+      namespaceId: 'kv-001',
+      namespaceName: 'my-project-cache',
+      reads: 50000,
+      writes: 1000,
+      deletes: 100,
+      lists: 50,
+    },
+  ],
+  r2: [
+    {
+      bucketName: 'my-project-ai-logs',
+      storageBytes: 1073741824, // 1 GB
+      objectCount: 10000,
+      classAOperations: 1000,
+      classBOperations: 5000,
+      egressBytes: 10737418240, // 10 GB
+    },
+  ],
+  durableObjects: {
+    requests: 1000,
+    storageBytes: 1024 * 1024,
+    gbSeconds: 100,
+    storageReadUnits: 500,
+    storageWriteUnits: 100,
+    storageDeleteUnits: 10,
+  },
+  vectorize: [
+    {
+      name: 'my-project-content',
+      vectorCount: 2199,
+      dimensions: 1536,
+      queries: 500,
+    },
+  ],
+  aiGateway: [
+    {
+      gatewayId: 'my-project',
+      requests: 5000,
+      tokens: 1000000,
+      cacheHits: 500,
+    },
+  ],
+  pages: [
+    {
+      projectName: 'platform-dashboard',
+      subdomain: 'platform-dashboard',
+      productionDeployments: 8,
+      previewDeployments: 2,
+      totalBuilds: 10,
+      lastDeployedAt: '2026-01-05T10:00:00Z',
+    },
+  ],
+};
+
+// Env type matching the worker's Env interface
+interface TestEnv {
+  PLATFORM_CACHE: KVNamespace;
+  PLATFORM_DB: D1Database;
+  CLOUDFLARE_ACCOUNT_ID: string;
+  CLOUDFLARE_API_TOKEN: string;
+  SLACK_WEBHOOK_URL?: string;
+  GITHUB_TOKEN?: string;
+  // Platform SDK bindings (mocked)
+  PLATFORM_TELEMETRY: { send: () => Promise<void>; sendBatch: () => Promise<void> };
+  PLATFORM_DLQ: { send: () => Promise<void>; sendBatch: () => Promise<void> };
+  PLATFORM_ANALYTICS: { writeDataPoint: () => void };
+  CIRCUIT_BREAKER: KVNamespace;
+}
+
+// Response type interfaces for type-safe JSON parsing
+interface CostFormatted {
+  workers: string;
+  d1: string;
+  kv?: string;
+  r2?: string;
+  total: string;
+}
+
+interface ThresholdConfig {
+  warningPct?: number;
+  highPct?: number;
+  criticalPct?: number;
+  absoluteMax?: number;
+  enabled?: boolean;
+}
+
+interface UsageResponse {
+  success: boolean;
+  period?: string;
+  project?: string;
+  data?: {
+    summary?: {
+      totalWorkers: number;
+      totalD1Databases: number;
+      totalRequests: number;
+    };
+  };
+  costs?: {
+    formatted?: CostFormatted;
+  };
+  thresholds?: Record<string, ThresholdConfig>;
+  responseTimeMs?: number;
+  error?: string;
+  cached?: boolean;
+  projectCosts?: unknown;
+  sparklines?: unknown;
+  comparison?: {
+    workersRequests?: unknown;
+    totalCost?: unknown;
+  };
+  compareMode?: string;
+  current?: unknown;
+  prior?: unknown;
+}
+
+// Create mock environment - cast to TestEnv for worker compatibility
+function createMockEnv(kvData: Record<string, string> = {}): TestEnv & {
+  PLATFORM_CACHE: MockKVNamespace & { store: Map<string, string> };
+  PLATFORM_DB: MockD1Database;
+} {
+  const kv = new MockKVNamespace();
+  // Override get to actually return values from the store, handling JSON type
+  kv.get = vi.fn((key: string, type?: string) => {
+    const value = kv.store.get(key) ?? null;
+    if (value && type === 'json') {
+      return Promise.resolve(JSON.parse(value));
+    }
+    return Promise.resolve(value);
+  }) as typeof kv.get;
+
+  // Pre-populate with initial data
+  Object.entries(kvData).forEach(([key, value]) => {
+    kv.store.set(key, value);
+  });
+
+  // Create mock D1 database
+  const db = new MockD1Database();
+
+  // Create mock circuit breaker KV (same as PLATFORM_CACHE for simplicity)
+  const circuitBreakerKv = new MockKVNamespace();
+
+  return {
+    PLATFORM_CACHE: kv as unknown as KVNamespace & MockKVNamespace & { store: Map<string, string> },
+    PLATFORM_DB: db as unknown as D1Database & MockD1Database,
+    CLOUDFLARE_ACCOUNT_ID: 'test-account-id',
+    CLOUDFLARE_API_TOKEN: 'test-api-token',
+    // Platform SDK mock bindings
+    PLATFORM_TELEMETRY: {
+      send: vi.fn().mockResolvedValue(undefined),
+      sendBatch: vi.fn().mockResolvedValue(undefined),
+    },
+    PLATFORM_DLQ: {
+      send: vi.fn().mockResolvedValue(undefined),
+      sendBatch: vi.fn().mockResolvedValue(undefined),
+    },
+    PLATFORM_ANALYTICS: {
+      writeDataPoint: vi.fn(),
+    },
+    CIRCUIT_BREAKER: circuitBreakerKv as unknown as KVNamespace,
+  } as TestEnv & {
+    PLATFORM_CACHE: MockKVNamespace & { store: Map<string, string> };
+    PLATFORM_DB: MockD1Database;
+  };
+}
+
+/**
+ * Set up mock D1 with project registry data for project filtering tests.
+ * The worker calls getProjects() which queries D1 for the project registry.
+ * Without this setup, all project filters fall back to 'all'.
+ */
+function setupProjectRegistry(db: MockD1Database): void {
+  // Queue project registry results (queried first by loadRegistry)
+  db.queueAllResult({
+    results: [
+      {
+        project_id: 'my-project',
+        display_name: 'Brand Copilot',
+        description: 'AI-powered content generation',
+        color: '#4F46E5',
+        icon: null,
+        owner: null,
+        repo_path: null,
+        status: 'active',
+        primary_resource: null,
+        custom_limit: null,
+      },
+      {
+        project_id: 'platform',
+        display_name: 'Platform',
+        description: 'Infrastructure monitoring',
+        color: '#059669',
+        icon: null,
+        owner: null,
+        repo_path: null,
+        status: 'active',
+        primary_resource: null,
+        custom_limit: null,
+      },
+      {
+        project_id: 'test-project',
+        display_name: 'Test Project',
+        description: 'Opportunity discovery',
+        color: '#D97706',
+        icon: null,
+        owner: null,
+        repo_path: null,
+        status: 'active',
+        primary_resource: null,
+        custom_limit: null,
+      },
+    ],
+  });
+
+  // Queue resource mapping results (queried second by loadRegistry)
+  db.queueAllResult({
+    results: [
+      { resource_type: 'worker', resource_id: 'my-project-api', project_id: 'my-project' },
+      { resource_type: 'worker', resource_id: 'platform-usage', project_id: 'platform' },
+      { resource_type: 'worker', resource_id: 'test-project', project_id: 'test-project' },
+    ],
+  });
+}
+
+// Create mock request
+function createRequest(path: string, method = 'GET', body?: unknown): Request {
+  const url = new URL(path, 'https://usage-api.example.com');
+  const init: RequestInit = {
+    method,
+    headers: { 'Content-Type': 'application/json' },
+  };
+  if (body) {
+    init.body = JSON.stringify(body);
+  }
+  return new Request(url.toString(), init);
+}
+
+// Mock execution context
+const mockCtx = {
+  waitUntil: vi.fn(),
+  passThroughOnException: vi.fn(),
+} as unknown as ExecutionContext;
+
+describe('Usage API - End-to-End Tests', () => {
+  let env: ReturnType<typeof createMockEnv>;
+
+  beforeEach(() => {
+    env = createMockEnv();
+    vi.clearAllMocks();
+    // Clear the project registry cache so each test starts fresh
+    clearRegistryCache();
+  });
+
+  describe('GET /usage', () => {
+    it('returns usage metrics with default parameters', async () => {
+      const request = createRequest('/usage');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+      expect(response.headers.get('Content-Type')).toBe('application/json');
+
+      const body = (await response.json()) as UsageResponse;
+
+      expect(body.success).toBe(true);
+      expect(body.period).toBe('30d');
+      expect(body.project).toBe('all');
+      expect(body.data).toBeDefined();
+      expect(body.costs).toBeDefined();
+      expect(body.thresholds).toBeDefined();
+    });
+
+    it('filters by period (24h)', async () => {
+      const request = createRequest('/usage?period=24h');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.period).toBe('24h');
+    });
+
+    it('filters by period (7d)', async () => {
+      const request = createRequest('/usage?period=7d');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.period).toBe('7d');
+    });
+
+    it('filters by project (my-project)', async () => {
+      // Set up project registry so 'my-project' is recognized as valid
+      setupProjectRegistry(env.PLATFORM_DB);
+
+      const request = createRequest('/usage?project=my-project');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.project).toBe('my-project');
+    });
+
+    it('filters by project (platform)', async () => {
+      // Set up project registry so 'platform' is recognized as valid
+      setupProjectRegistry(env.PLATFORM_DB);
+
+      const request = createRequest('/usage?project=platform');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.project).toBe('platform');
+    });
+
+    it('filters by project (test-project)', async () => {
+      // Set up project registry so 'test-project' is recognized as valid
+      setupProjectRegistry(env.PLATFORM_DB);
+
+      const request = createRequest('/usage?project=test-project');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.project).toBe('test-project');
+    });
+
+    it('combines period and project filters', async () => {
+      // Set up project registry so 'my-project' is recognized as valid
+      setupProjectRegistry(env.PLATFORM_DB);
+
+      const request = createRequest('/usage?period=7d&project=my-project');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.period).toBe('7d');
+      expect(body.project).toBe('my-project');
+    });
+
+    it('defaults invalid period to 30d', async () => {
+      const request = createRequest('/usage?period=invalid');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.period).toBe('30d');
+    });
+
+    it('defaults invalid project to all', async () => {
+      // Set up project registry so we can test that 'invalid' falls back to 'all'
+      setupProjectRegistry(env.PLATFORM_DB);
+
+      const request = createRequest('/usage?project=invalid');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.project).toBe('all');
+    });
+
+    it('includes formatted cost breakdown', async () => {
+      const request = createRequest('/usage');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      const body = (await response.json()) as UsageResponse;
+
+      expect(body.costs?.formatted).toBeDefined();
+      expect(body.costs?.formatted?.workers).toMatch(/^\$[\d.]+$/);
+      expect(body.costs?.formatted?.d1).toMatch(/^\$[\d.]+$/);
+      expect(body.costs?.formatted?.total).toMatch(/^\$[\d.]+$/);
+    });
+
+    it('includes summary statistics', async () => {
+      const request = createRequest('/usage');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      const body = (await response.json()) as UsageResponse;
+
+      expect(body.data?.summary).toBeDefined();
+      expect(body.data?.summary?.totalWorkers).toBeGreaterThanOrEqual(0);
+      expect(body.data?.summary?.totalD1Databases).toBeGreaterThanOrEqual(0);
+      expect(body.data?.summary?.totalRequests).toBeGreaterThanOrEqual(0);
+    });
+
+    it('includes CORS headers', async () => {
+      const request = createRequest('/usage');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.headers.get('Access-Control-Allow-Origin')).toBe('*');
+    });
+
+    it('returns 500 when API credentials missing', async () => {
+      const badEnv = {
+        ...env,
+        CLOUDFLARE_ACCOUNT_ID: '',
+        CLOUDFLARE_API_TOKEN: '',
+      };
+
+      const request = createRequest('/usage');
+      const response = await UsageWorker.fetch(request, badEnv, mockCtx);
+
+      expect(response.status).toBe(500);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(false);
+      expect(body.error).toBe('Configuration Error');
+    });
+  });
+
+  describe('GET /usage/costs', () => {
+    it('returns cost breakdown', async () => {
+      const request = createRequest('/usage/costs');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(true);
+      expect(body.costs).toBeDefined();
+      expect(body.projectCosts).toBeDefined();
+    });
+
+    it('includes formatted costs', async () => {
+      const request = createRequest('/usage/costs');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      const body = (await response.json()) as UsageResponse;
+
+      expect(body.costs?.formatted?.workers).toBeDefined();
+      expect(body.costs?.formatted?.d1).toBeDefined();
+      expect(body.costs?.formatted?.total).toBeDefined();
+    });
+  });
+
+  describe('GET /usage/thresholds', () => {
+    it('returns threshold analysis', async () => {
+      const request = createRequest('/usage/thresholds');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(true);
+      expect(body.thresholds).toBeDefined();
+    });
+
+    it('respects period parameter', async () => {
+      const request = createRequest('/usage/thresholds?period=7d');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.period).toBe('7d');
+    });
+  });
+
+  describe('GET /usage/enhanced', () => {
+    it('returns enhanced metrics with sparklines', async () => {
+      const request = createRequest('/usage/enhanced');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(true);
+      expect(body.sparklines).toBeDefined();
+      expect(body.comparison).toBeDefined();
+    });
+
+    it('includes comparison data', async () => {
+      const request = createRequest('/usage/enhanced');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      const body = (await response.json()) as UsageResponse;
+
+      expect(body.comparison?.workersRequests).toBeDefined();
+      expect(body.comparison?.totalCost).toBeDefined();
+    });
+  });
+
+  describe('GET /usage/compare', () => {
+    it('returns comparison with lastMonth mode', async () => {
+      const request = createRequest('/usage/compare?compare=lastMonth');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(true);
+      expect(body.compareMode).toBe('lastMonth');
+      expect(body.current).toBeDefined();
+      expect(body.prior).toBeDefined();
+      expect(body.comparison).toBeDefined();
+    });
+
+    it('returns 400 for missing compare parameter', async () => {
+      const request = createRequest('/usage/compare');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(400);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(false);
+      expect(body.error).toBe('Invalid compare mode');
+    });
+
+    it('returns 400 for invalid compare mode', async () => {
+      const request = createRequest('/usage/compare?compare=invalid');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(400);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(false);
+    });
+
+    it('requires dates for custom compare mode', async () => {
+      const request = createRequest('/usage/compare?compare=custom');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(400);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(false);
+      expect(body.error).toBe('Missing date parameters');
+    });
+
+    it('accepts custom date range', async () => {
+      const request = createRequest(
+        '/usage/compare?compare=custom&startDate=2025-11-01&endDate=2025-11-07'
+      );
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(true);
+      expect(body.compareMode).toBe('custom');
+    });
+  });
+
+  describe('GET /usage/settings', () => {
+    it('returns default thresholds when no custom config exists', async () => {
+      const request = createRequest('/usage/settings');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(true);
+      expect(body.thresholds).toBeDefined();
+      expect(body.cached).toBe(false);
+    });
+
+    it('returns cached thresholds when custom config exists', async () => {
+      // Pre-populate KV with custom config
+      const customConfig = {
+        thresholds: {
+          workers: { warningPct: 60, highPct: 80, criticalPct: 95, absoluteMax: 10, enabled: true },
+        },
+        updated: '2025-11-01T00:00:00Z',
+      };
+      env.PLATFORM_CACHE.store.set('alert-thresholds:config', JSON.stringify(customConfig));
+
+      const request = createRequest('/usage/settings');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(true);
+      expect(body.thresholds?.workers?.warningPct).toBe(60);
+      expect(body.cached).toBe(true);
+    });
+  });
+
+  describe('PUT /usage/settings', () => {
+    it('updates threshold configuration', async () => {
+      const request = createRequest('/usage/settings', 'PUT', {
+        thresholds: {
+          workers: { warningPct: 60, highPct: 80, criticalPct: 95, absoluteMax: 10, enabled: true },
+        },
+      });
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(true);
+      expect(body.thresholds?.workers?.warningPct).toBe(60);
+    });
+
+    it('returns 400 for missing thresholds', async () => {
+      const request = createRequest('/usage/settings', 'PUT', {});
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(400);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(false);
+      expect(body.error).toBe('Invalid request body');
+    });
+
+    it('validates percentage values (0-100)', async () => {
+      const request = createRequest('/usage/settings', 'PUT', {
+        thresholds: {
+          workers: { warningPct: 150 }, // Invalid: > 100
+        },
+      });
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(400);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(false);
+      expect(body.error).toBe('Invalid threshold value');
+    });
+
+    it('validates absoluteMax is non-negative', async () => {
+      const request = createRequest('/usage/settings', 'PUT', {
+        thresholds: {
+          workers: { absoluteMax: -5 }, // Invalid: < 0
+        },
+      });
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(400);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.success).toBe(false);
+    });
+
+    it('merges with existing configuration', async () => {
+      // Pre-populate with existing config
+      const existingConfig = {
+        thresholds: {
+          workers: { warningPct: 50, highPct: 75, criticalPct: 90, absoluteMax: 5, enabled: true },
+          d1: { warningPct: 50, highPct: 75, criticalPct: 90, absoluteMax: 10, enabled: true },
+        },
+        updated: '2025-11-01T00:00:00Z',
+      };
+      env.PLATFORM_CACHE.store.set('alert-thresholds:config', JSON.stringify(existingConfig));
+
+      // Update only workers
+      const request = createRequest('/usage/settings', 'PUT', {
+        thresholds: {
+          workers: { absoluteMax: 15 },
+        },
+      });
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+
+      const body = (await response.json()) as UsageResponse;
+      // Workers should be updated
+      expect(body.thresholds?.workers?.absoluteMax).toBe(15);
+      // D1 should retain existing values
+      expect(body.thresholds?.d1?.absoluteMax).toBe(10);
+    });
+  });
+
+  describe('HTTP Methods', () => {
+    it('handles OPTIONS for CORS preflight', async () => {
+      const request = createRequest('/usage', 'OPTIONS');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(200);
+      expect(response.headers.get('Access-Control-Allow-Methods')).toContain('GET');
+      expect(response.headers.get('Access-Control-Allow-Methods')).toContain('PUT');
+    });
+
+    it('returns 405 for POST to /usage', async () => {
+      const request = createRequest('/usage', 'POST');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(405);
+    });
+
+    it('returns 404 for unknown paths', async () => {
+      const request = createRequest('/unknown');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      expect(response.status).toBe(404);
+    });
+  });
+
+  describe('Caching Behaviour', () => {
+    it('returns cached data when available', async () => {
+      // First request populates cache
+      const request1 = createRequest('/usage');
+      await UsageWorker.fetch(request1, env, mockCtx);
+
+      // Second request should hit cache (within same hour)
+      const request2 = createRequest('/usage');
+      const response2 = await UsageWorker.fetch(request2, env, mockCtx);
+
+      const body = (await response2.json()) as UsageResponse;
+      // Note: cached flag depends on actual cache hit in KV mock
+      expect(body.success).toBe(true);
+    });
+
+    it('uses different cache keys for different periods', async () => {
+      // Request 24h
+      const request1 = createRequest('/usage?period=24h');
+      await UsageWorker.fetch(request1, env, mockCtx);
+
+      // Request 7d
+      const request2 = createRequest('/usage?period=7d');
+      await UsageWorker.fetch(request2, env, mockCtx);
+
+      // Verify both requests completed successfully
+      expect(env.PLATFORM_CACHE.store.size).toBeGreaterThanOrEqual(0);
+    });
+
+    it('uses different cache keys for different projects', async () => {
+      // Request all projects
+      const request1 = createRequest('/usage?project=all');
+      await UsageWorker.fetch(request1, env, mockCtx);
+
+      // Request my-project
+      const request2 = createRequest('/usage?project=my-project');
+      await UsageWorker.fetch(request2, env, mockCtx);
+
+      // Both should be cached separately
+      expect(env.PLATFORM_CACHE.store.size).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('Response Time Tracking', () => {
+    it('includes responseTimeMs in response', async () => {
+      const request = createRequest('/usage');
+      const response = await UsageWorker.fetch(request, env, mockCtx);
+
+      const body = (await response.json()) as UsageResponse;
+      expect(body.responseTimeMs).toBeDefined();
+      expect(typeof body.responseTimeMs).toBe('number');
+    });
+  });
+});