feat(analytics): add usage analytics page with caching layer

- Add Analytics page with usage trends, model breakdown, sessions table
- Add server-side caching layer for better-ccusage data (TTL-based)
- Add request coalescing to prevent duplicate concurrent API calls
- Add /api/usage/refresh endpoint to manually clear cache
- Add date-range filter, summary cards, trend charts components
- Fix API parameter mismatch (since/until in YYYYMMDD format)
- Wire up Refresh button with loading state animation

Author: kaitranntt

bun.lock

@@ -4,6 +4,7 @@
     "": {
       "name": "@kaitranntt/ccs",
       "dependencies": {
+        "better-ccusage": "^1.2.6",
         "boxen": "^8.0.1",
         "chalk": "^5.6.2",
         "chokidar": "^5.0.0",
@@ -445,6 +446,8 @@
 
     "before-after-hook": ["[email protected]", "", {}, "sha512-q6tR3RPqIB1pMiTRMFcZwuG5T8vwp+vUvEG0vuI6B+Rikh5BfPp2fQ82c925FOs+b0lcFQ8CFrL+KbilfZFhOQ=="],
 
+    "better-ccusage": ["[email protected]", "", { "bin": { "better-ccusage": "dist/index.js" } }, "sha512-IZCYBX1kF0IfJ6ho9JMwLKn2o820WRiVGZ+2tVS2olODU5J7Np5mJ1j1i5HtazZPNo2S9wKU9C9iysc0f8Cjqw=="],
+
     "body-parser": ["[email protected]", "", { "dependencies": { "bytes": "~3.1.2", "content-type": "~1.0.5", "debug": "2.6.9", "depd": "2.0.0", "destroy": "~1.2.0", "http-errors": "~2.0.1", "iconv-lite": "~0.4.24", "on-finished": "~2.4.1", "qs": "~6.14.0", "raw-body": "~2.5.3", "type-is": "~1.6.18", "unpipe": "~1.0.0" } }, "sha512-ZTgYYLMOXY9qKU/57FAo8F+HA2dGX7bqGc71txDRC1rS4frdFI5R7NhluHxH6M0YItAP0sHB4uqAOcYKxO6uGA=="],
 
     "bottleneck": ["[email protected]", "", {}, "sha512-VHiNCbI1lKdl44tGrhNfU3lup0Tj/ZBMJB5/2ZbNXRCPuRCO7ed2mgcK4r17y+KB2EfuYuRaVlwNbAeaWGSpbw=="],

package.json

@@ -79,6 +79,7 @@
     "postinstall": "node scripts/postinstall.js"
   },
   "dependencies": {
+    "better-ccusage": "^1.2.6",
     "boxen": "^8.0.1",
     "chalk": "^5.6.2",
     "chokidar": "^5.0.0",

src/types/external.d.ts

@@ -2,6 +2,81 @@
  * Type shims for incomplete external dependencies
  */
 
+// better-ccusage types (package has JS exports but incomplete TS subpath support)
+declare module 'better-ccusage/data-loader' {
+  export interface ModelBreakdown {
+    modelName: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    cost: number;
+  }
+
+  export interface DailyUsage {
+    date: string;
+    source: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    cost: number;
+    totalCost: number;
+    modelsUsed: string[];
+    modelBreakdowns: ModelBreakdown[];
+  }
+
+  export interface MonthlyUsage {
+    month: string;
+    source: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    totalCost: number;
+    modelsUsed: string[];
+    modelBreakdowns: ModelBreakdown[];
+  }
+
+  export interface SessionUsage {
+    sessionId: string;
+    projectPath: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    cost: number;
+    totalCost: number;
+    lastActivity: string;
+    versions: string[];
+    modelsUsed: string[];
+    modelBreakdowns: ModelBreakdown[];
+    source: string;
+  }
+
+  export interface DataLoaderOptions {
+    mode?: 'calculate' | 'cached';
+    claudePaths?: string[];
+  }
+
+  export function loadDailyUsageData(options?: DataLoaderOptions): Promise<DailyUsage[]>;
+  export function loadMonthlyUsageData(options?: DataLoaderOptions): Promise<MonthlyUsage[]>;
+  export function loadSessionData(options?: DataLoaderOptions): Promise<SessionUsage[]>;
+}
+
+declare module 'better-ccusage/calculate-cost' {
+  export interface Totals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    costUSD: number;
+  }
+
+  export function calculateTotals(entries: unknown[]): Totals;
+  export function getTotalTokens(entries: unknown[]): number;
+}
+
 declare module 'cli-table3' {
   interface TableOptions {
     head?: string[];

src/web-server/index.ts

@@ -47,6 +47,10 @@ export async function startServer(options: ServerOptions): Promise<ServerInstanc
   const { overviewRoutes } = await import('./overview-routes');
   app.use('/api/overview', overviewRoutes);
 
+  // Usage analytics routes
+  const { usageRoutes } = await import('./usage-routes');
+  app.use('/api/usage', usageRoutes);
+
   // Dev mode: use Vite middleware for HMR
   if (options.dev) {
     const { createServer: createViteServer } = await import('vite');