botrun-horse 2.29.2 → 2.30.0

package/botrun-c/admin/lib/__tests__/user-resolver.test.ts

@@ -0,0 +1,439 @@
+/**
+ * 實質性保護傘測試：user-resolver.ts
+ * 測試現有的使用者解析功能，確保重構前功能完整
+ */
+
+import { createMockAuth, createMockUser } from './mocks/firebase.mock';
+import * as userResolverModule from '../user-resolver';
+
+// Mock Firebase 模組
+jest.mock('../firebase.js', () => ({
+  getAuth: jest.fn(),
+  getFirestore: jest.fn(),
+}));
+
+describe('user-resolver.ts - 實質性保護傘測試', () => {
+  let mockAuth: any;
+  let mockFirestore: any;
+  let getAuthMock: jest.Mock;
+  let getFirestoreMock: jest.Mock;
+
+  beforeEach(() => {
+    mockAuth = createMockAuth();
+    mockFirestore = {
+      collection: jest.fn(() => ({
+        doc: jest.fn(() => ({
+          set: jest.fn().mockResolvedValue(undefined),
+          get: jest.fn().mockResolvedValue({ exists: false }),
+          update: jest.fn().mockResolvedValue(undefined),
+        })),
+      })),
+    };
+
+    const firebaseModule = require('../firebase.js');
+    getAuthMock = firebaseModule.getAuth as jest.Mock;
+    getFirestoreMock = firebaseModule.getFirestore as jest.Mock;
+    getAuthMock.mockReturnValue(mockAuth);
+    getFirestoreMock.mockReturnValue(mockFirestore);
+  });
+
+  describe('resolveUser()', () => {
+    test('應該透過 Email 解析使用者', async () => {
+      mockAuth.getUserByEmail = jest.fn().mockResolvedValue(createMockUser());
+
+      const user = await userResolverModule.resolveUser('test@example.com');
+
+      expect(mockAuth.getUserByEmail).toHaveBeenCalledWith('test@example.com');
+      expect(user).toEqual({
+        uid: 'test-uid-123',
+        email: 'test@example.com',
+        displayName: 'Test User',
+        createdAt: expect.any(Date),
+        lastSignInTime: expect.any(Date),
+      });
+    });
+
+    test('應該透過 UID 解析使用者', async () => {
+      mockAuth.getUser = jest.fn().mockResolvedValue(createMockUser());
+
+      const user = await userResolverModule.resolveUser('test-uid-123');
+
+      expect(mockAuth.getUser).toHaveBeenCalledWith('test-uid-123');
+      expect(user.uid).toBe('test-uid-123');
+    });
+
+    test('Email 和 UID 應該由 @ 符號區分', async () => {
+      mockAuth.getUserByEmail = jest.fn().mockResolvedValue(createMockUser());
+      mockAuth.getUser = jest.fn().mockResolvedValue(createMockUser());
+
+      // 包含 @ 的應該用 email 方式
+      await userResolverModule.resolveUser('user@example.com');
+      expect(mockAuth.getUserByEmail).toHaveBeenCalled();
+      expect(mockAuth.getUser).not.toHaveBeenCalled();
+
+      // 清空 mock
+      jest.clearAllMocks();
+      getAuthMock.mockReturnValue(mockAuth);
+
+      // 不包含 @ 的應該用 UID 方式
+      await userResolverModule.resolveUser('uid-without-at');
+      expect(mockAuth.getUser).toHaveBeenCalled();
+      expect(mockAuth.getUserByEmail).not.toHaveBeenCalled();
+    });
+
+    test('找不到使用者時應該拋出錯誤', async () => {
+      mockAuth.getUserByEmail = jest.fn().mockRejectedValue({
+        code: 'auth/user-not-found',
+      });
+
+      await expect(
+        userResolverModule.resolveUser('notfound@example.com')
+      ).rejects.toThrow('找不到使用者');
+    });
+
+    test('應該返回完整的使用者資訊（包含時間戳記）', async () => {
+      const mockUserData = createMockUser({
+        metadata: {
+          creationTime: new Date('2025-01-01'),
+          lastSignInTime: new Date('2025-12-09'),
+        },
+      });
+      mockAuth.getUserByEmail = jest.fn().mockResolvedValue(mockUserData);
+
+      const user = await userResolverModule.resolveUser('test@example.com');
+
+      expect(user).toHaveProperty('uid');
+      expect(user).toHaveProperty('email');
+      expect(user).toHaveProperty('displayName');
+      expect(user).toHaveProperty('createdAt');
+      expect(user.createdAt).toBeInstanceOf(Date);
+    });
+
+    test('沒有 lastSignInTime 時應該為 undefined', async () => {
+      mockAuth.getUserByEmail = jest.fn().mockResolvedValue(
+        createMockUser({
+          metadata: {
+            creationTime: new Date('2025-01-01'),
+            lastSignInTime: null,
+          },
+        })
+      );
+
+      const user = await userResolverModule.resolveUser('test@example.com');
+      expect(user.lastSignInTime).toBeUndefined();
+    });
+  });
+
+  describe('resolveUsers()', () => {
+    test('應該批次解析多個使用者', async () => {
+      mockAuth.getUserByEmail = jest.fn()
+        .mockResolvedValueOnce(createMockUser({ email: 'user1@example.com' }))
+        .mockResolvedValueOnce(createMockUser({ email: 'user2@example.com' }));
+
+      const users = await userResolverModule.resolveUsers([
+        'user1@example.com',
+        'user2@example.com',
+      ]);
+
+      expect(users).toHaveLength(2);
+      expect(users[0].email).toBe('user1@example.com');
+      expect(users[1].email).toBe('user2@example.com');
+    });
+
+    test('單個失敗不應該中斷整個批次', async () => {
+      mockAuth.getUserByEmail = jest.fn()
+        .mockResolvedValueOnce(createMockUser({ email: 'user1@example.com' }))
+        .mockRejectedValueOnce({ code: 'auth/user-not-found' })
+        .mockResolvedValueOnce(createMockUser({ email: 'user3@example.com' }));
+
+      const users = await userResolverModule.resolveUsers([
+        'user1@example.com',
+        'notfound@example.com',
+        'user3@example.com',
+      ]);
+
+      // 應該返回成功的 2 個
+      expect(users).toHaveLength(2);
+      expect(users[0].email).toBe('user1@example.com');
+      expect(users[1].email).toBe('user3@example.com');
+    });
+
+    test('空清單應該返回空陣列', async () => {
+      const users = await userResolverModule.resolveUsers([]);
+      expect(users).toEqual([]);
+    });
+  });
+
+  describe('resolveOrCreateUser()', () => {
+    test('現有使用者應該直接返回，created=false', async () => {
+      mockAuth.getUserByEmail = jest.fn().mockResolvedValue(createMockUser());
+
+      const result = await userResolverModule.resolveOrCreateUser('test@example.com');
+
+      expect(result.created).toBe(false);
+      expect(result.user.email).toBe('test@example.com');
+      expect(result.user.uid).toBe('test-uid-123');
+    });
+
+    test('不存在的使用者應該建立新使用者（createIfNotExists=true）', async () => {
+      mockAuth.getUserByEmail = jest.fn()
+        .mockRejectedValueOnce({ code: 'auth/user-not-found' });
+
+      mockAuth.createUser = jest.fn().mockResolvedValue({
+        uid: 'new-uid-456',
+        email: 'newuser@example.com',
+        displayName: 'newuser',
+      });
+
+      const result = await userResolverModule.resolveOrCreateUser(
+        'newuser@example.com',
+        { createIfNotExists: true, defaultPlan: 'Lite' }
+      );
+
+      expect(result.created).toBe(true);
+      expect(result.user.uid).toBe('new-uid-456');
+      expect(mockAuth.createUser).toHaveBeenCalledWith({
+        email: 'newuser@example.com',
+        displayName: 'newuser',
+      });
+    });
+
+    test('不存在且 createIfNotExists=false 應該拋出錯誤', async () => {
+      mockAuth.getUserByEmail = jest.fn()
+        .mockRejectedValueOnce({ code: 'auth/user-not-found' });
+
+      await expect(
+        userResolverModule.resolveOrCreateUser('notfound@example.com', {
+          createIfNotExists: false,
+        })
+      ).rejects.toThrow('找不到使用者');
+    });
+
+    test('必須是 Email 格式（不能是 UID）', async () => {
+      await expect(
+        userResolverModule.resolveOrCreateUser('uid-without-at', {
+          createIfNotExists: true,
+        })
+      ).rejects.toThrow('必須提供 Email 格式');
+    });
+
+    test('建立使用者時應該設定 Firestore users 文件', async () => {
+      mockAuth.getUserByEmail = jest.fn()
+        .mockRejectedValueOnce({ code: 'auth/user-not-found' });
+
+      mockAuth.createUser = jest.fn().mockResolvedValue({
+        uid: 'new-uid-456',
+        email: 'newuser@example.com',
+        displayName: 'newuser',
+      });
+
+      const mockSetFn = jest.fn().mockResolvedValue(undefined);
+      const mockDocFn = jest.fn(() => ({ set: mockSetFn }));
+      const mockCollectionFn = jest.fn(() => ({ doc: mockDocFn }));
+      mockFirestore.collection = mockCollectionFn;
+
+      await userResolverModule.resolveOrCreateUser('newuser@example.com', {
+        createIfNotExists: true,
+        defaultPlan: 'Lite',
+      });
+
+      expect(mockCollectionFn).toHaveBeenCalledWith('users');
+      expect(mockDocFn).toHaveBeenCalledWith('new-uid-456');
+      expect(mockSetFn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          email: 'newuser@example.com',
+          displayName: 'newuser',
+          plan: 'Lite',
+        })
+      );
+    });
+
+    test('建立使用者時應該設定訂閱資訊', async () => {
+      mockAuth.getUserByEmail = jest.fn()
+        .mockRejectedValueOnce({ code: 'auth/user-not-found' });
+
+      mockAuth.createUser = jest.fn().mockResolvedValue({
+        uid: 'new-uid-456',
+        email: 'newuser@example.com',
+        displayName: 'newuser',
+      });
+
+      const mockSetFn = jest.fn().mockResolvedValue(undefined);
+      const mockDocFn = jest.fn(() => ({ set: mockSetFn }));
+      const mockCollectionFn = jest.fn(() => ({ doc: mockDocFn }));
+      mockFirestore.collection = mockCollectionFn;
+
+      const endDate = new Date('2026-01-01');
+
+      await userResolverModule.resolveOrCreateUser('newuser@example.com', {
+        createIfNotExists: true,
+        defaultPlan: 'Max-1',
+        subscriptionEndDate: endDate,
+      });
+
+      // 應該設定兩個集合：users 和 user_subscriptions
+      expect(mockCollectionFn).toHaveBeenCalledWith('users');
+      expect(mockCollectionFn).toHaveBeenCalledWith('user_subscriptions');
+    });
+
+    test('displayName 應該從 email 前綴產生', async () => {
+      mockAuth.getUserByEmail = jest.fn()
+        .mockRejectedValueOnce({ code: 'auth/user-not-found' });
+
+      mockAuth.createUser = jest.fn().mockResolvedValue({
+        uid: 'new-uid-456',
+        email: 'john.doe@example.com',
+        displayName: 'john.doe',
+      });
+
+      await userResolverModule.resolveOrCreateUser('john.doe@example.com', {
+        createIfNotExists: true,
+      });
+
+      expect(mockAuth.createUser).toHaveBeenCalledWith(
+        expect.objectContaining({
+          displayName: 'john.doe',
+        })
+      );
+    });
+  });
+
+  describe('batchProvisionUsers()', () => {
+    test('應該批次建立使用者', async () => {
+      const endDate = new Date('2026-01-01');
+
+      mockAuth.getUserByEmail = jest.fn()
+        .mockRejectedValueOnce({ code: 'auth/user-not-found' })
+        .mockRejectedValueOnce({ code: 'auth/user-not-found' });
+
+      mockAuth.createUser = jest.fn()
+        .mockResolvedValueOnce({ uid: 'uid-1', email: 'user1@example.com' })
+        .mockResolvedValueOnce({ uid: 'uid-2', email: 'user2@example.com' });
+
+      const results = await userResolverModule.batchProvisionUsers(
+        ['user1@example.com', 'user2@example.com'],
+        'Lite',
+        endDate
+      );
+
+      expect(results).toHaveLength(2);
+      expect(results[0].success).toBe(true);
+      expect(results[0].created).toBe(true);
+      expect(results[1].success).toBe(true);
+      expect(results[1].created).toBe(true);
+    });
+
+    test('應該區別建立和更新的使用者', async () => {
+      const endDate = new Date('2026-01-01');
+
+      mockAuth.getUserByEmail = jest.fn()
+        .mockResolvedValueOnce(createMockUser({ email: 'existing@example.com' }))
+        .mockRejectedValueOnce({ code: 'auth/user-not-found' });
+
+      mockAuth.createUser = jest.fn().mockResolvedValue({
+        uid: 'new-uid',
+        email: 'new@example.com',
+      });
+
+      const mockUpdateFn = jest.fn().mockResolvedValue(undefined);
+      const mockDocFn = jest.fn(() => ({
+        set: jest.fn().mockResolvedValue(undefined),
+        get: jest.fn().mockResolvedValue({ exists: true }),
+        update: mockUpdateFn,
+      }));
+      const mockCollectionFn = jest.fn(() => ({ doc: mockDocFn }));
+      mockFirestore.collection = mockCollectionFn;
+
+      const results = await userResolverModule.batchProvisionUsers(
+        ['existing@example.com', 'new@example.com'],
+        'Max-1',
+        endDate
+      );
+
+      expect(results[0].created).toBe(false); // 既有使用者
+      expect(results[1].created).toBe(true);  // 新建立的使用者
+    });
+
+    test('無效的 Email 應該返回錯誤', async () => {
+      const endDate = new Date('2026-01-01');
+
+      const results = await userResolverModule.batchProvisionUsers(
+        ['invalid-email', 'valid@example.com'],
+        'Lite',
+        endDate
+      );
+
+      expect(results[0].success).toBe(false);
+      expect(results[0].error).toContain('無效的 Email 格式');
+    });
+
+    test('空 Email 應該被跳過', async () => {
+      mockAuth.getUserByEmail = jest.fn();
+      mockAuth.createUser = jest.fn();
+
+      const results = await userResolverModule.batchProvisionUsers(
+        ['', '  ', 'valid@example.com'],
+        'Lite',
+        new Date('2026-01-01')
+      );
+
+      expect(results[0].success).toBe(false);
+      expect(results[1].success).toBe(false);
+    });
+
+    test('應該更新既有使用者的方案和訂閱', async () => {
+      mockAuth.getUserByEmail = jest.fn()
+        .mockResolvedValue(createMockUser({ email: 'existing@example.com' }));
+
+      const mockUpdateFn = jest.fn().mockResolvedValue(undefined);
+      const mockDocFn = jest.fn(() => ({
+        get: jest.fn().mockResolvedValue({ exists: true }),
+        update: mockUpdateFn,
+      }));
+      const mockCollectionFn = jest.fn(() => ({ doc: mockDocFn }));
+      mockFirestore.collection = mockCollectionFn;
+
+      const endDate = new Date('2026-01-01');
+
+      await userResolverModule.batchProvisionUsers(
+        ['existing@example.com'],
+        'Max-2',
+        endDate
+      );
+
+      // 應該更新 user_subscriptions
+      expect(mockUpdateFn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          plan: 'Max-2',
+          status: 'active',
+          subscriptionEndDate: endDate,
+        })
+      );
+    });
+
+    test('應該統計成功、建立和失敗的數量', async () => {
+      mockAuth.getUserByEmail = jest.fn()
+        .mockResolvedValueOnce(createMockUser())
+        .mockRejectedValueOnce({ code: 'auth/user-not-found' });
+
+      mockAuth.createUser = jest.fn().mockResolvedValue({
+        uid: 'new-uid',
+        email: 'new@example.com',
+      });
+
+      const results = await userResolverModule.batchProvisionUsers(
+        ['existing@example.com', 'new@example.com', 'invalid-email'],
+        'Lite',
+        new Date('2026-01-01')
+      );
+
+      const successful = results.filter((r) => r.success);
+      const created = results.filter((r) => r.created);
+      const failed = results.filter((r) => !r.success);
+
+      expect(successful.length).toBe(2); // 既有 + 新建立
+      expect(created.length).toBe(1);    // 只有新建立
+      expect(failed.length).toBe(1);     // 無效的 Email
+    });
+  });
+});

package/botrun-c/admin/lib/analyzers/BillingAnalyticsService.ts

@@ -0,0 +1,242 @@
+/**
+ * 成本分析服務
+ * 計算使用者的成本、ROI、使用趨勢等商業指標
+ */
+
+import { TimeSeriesAnalyzer, TimeSeriesAnalysisResult } from './TimeSeriesAnalyzer.js';
+
+export interface PricingTier {
+  plan: string;
+  rpmLimit: number;
+  tpmLimit: number;
+  rpdLimit: number;
+  monthlyCost: number;
+  costPerMToken?: number;
+  costPerRequest?: number;
+}
+
+export interface BillingMetrics {
+  userId: string;
+  email: string;
+  plan: string;
+  analysisDate: Date;
+  analysisDays: number;
+
+  // 使用量指標（分別統計輸入/輸出）
+  totalRequests: number;
+  totalTokens: number;
+  inputTokens: number;   // 輸入 tokens
+  outputTokens: number;  // 輸出 tokens
+  avgDailyTokens: number;
+  avgDailyRequests: number;
+
+  // 成本指標（分別計算輸入/輸出成本）
+  inputCost: number;     // 輸入成本 ($1/1M)
+  outputCost: number;    // 輸出成本 ($5/1M)
+  totalCost: number;     // 總成本 = inputCost + outputCost
+  monthlyPlanCost: number;
+  estimatedMonthlyCost: number;
+  estimatedAnnualCost: number;
+  costPerToken: number;
+  costPerRequest: number;
+
+  // 使用率指標
+  tpmUtilization: number; // %
+  rpmUtilization: number; // %
+  rpdUtilization: number; // %
+
+  // 排行資訊
+  rank?: number;
+  percentileRank?: number; // 0-100
+}
+
+export interface BillingReport {
+  generatedAt: Date;
+  analysisPeriod: {
+    startDate: Date;
+    endDate: Date;
+    days: number;
+  };
+  totalUsers: number;
+  totalTokensAcrossUsers: number;
+  totalCostAcrossUsers: number;
+  metrics: BillingMetrics[];
+  topSpenders: BillingMetrics[];
+  costBreakdown: {
+    plan: string;
+    userCount: number;
+    totalCost: number;
+    percentage: number;
+  }[];
+}
+
+// Claude Haiku 4.5 定價（2025）
+// 來源：https://docs.claude.com/en/docs/about-claude/pricing
+export const COST_PER_MILLION_INPUT_TOKENS = 1;   // $1 / 1M input tokens
+export const COST_PER_MILLION_OUTPUT_TOKENS = 5;  // $5 / 1M output tokens
+
+export const PRICING_TIERS: Record<string, PricingTier> = {
+  'Lite': {
+    plan: 'Lite',
+    rpmLimit: 6,
+    tpmLimit: 200000,
+    rpdLimit: 32,
+    monthlyCost: 0,  // 固定費用為 0，成本完全基於 Token 使用量
+    costPerMToken: COST_PER_MILLION_OUTPUT_TOKENS,  // 預設使用輸出價格
+    costPerRequest: 0
+  },
+  'Max-1': {
+    plan: 'Max-1',
+    rpmLimit: 6,
+    tpmLimit: 600000,
+    rpdLimit: 111,
+    monthlyCost: 0,  // 固定費用為 0，成本完全基於 Token 使用量
+    costPerMToken: COST_PER_MILLION_OUTPUT_TOKENS,
+    costPerRequest: 0
+  },
+  'Max-2': {
+    plan: 'Max-2',
+    rpmLimit: 6,
+    tpmLimit: 600000,
+    rpdLimit: 450,
+    monthlyCost: 0,  // 固定費用為 0，成本完全基於 Token 使用量
+    costPerMToken: COST_PER_MILLION_OUTPUT_TOKENS,
+    costPerRequest: 0
+  }
+};
+
+export class BillingAnalyticsService {
+  private timeSeriesAnalyzer = new TimeSeriesAnalyzer();
+
+  /**
+   * 計算單一使用者的成本指標
+   * 成本純粹基於實際 Token 使用量：
+   * - 輸入 tokens: $1 / 1M tokens
+   * - 輸出 tokens: $5 / 1M tokens
+   */
+  async calculateUserMetrics(
+    userId: string,
+    userEmail: string,
+    plan: string = 'Lite',
+    days: number = 30
+  ): Promise<BillingMetrics> {
+    const analysis = await this.timeSeriesAnalyzer.analyzeUser(userId, userEmail, days);
+    const pricing = PRICING_TIERS[plan] || PRICING_TIERS['Lite'];
+
+    const totalRequests = analysis.totalRequests;
+    const totalTokens = analysis.totalTokens;
+    const inputTokens = analysis.inputTokens;
+    const outputTokens = analysis.outputTokens;
+    const dailyCount = days || 1;
+
+    // 計算成本 - 分別計算輸入/輸出 Token 成本
+    // 公式：inputCost = (inputTokens / 1M) * $1, outputCost = (outputTokens / 1M) * $5
+    const inputCost = (inputTokens / 1000000) * COST_PER_MILLION_INPUT_TOKENS;
+    const outputCost = (outputTokens / 1000000) * COST_PER_MILLION_OUTPUT_TOKENS;
+    const totalCost = inputCost + outputCost;
+
+    const avgDailyTokens = totalTokens / dailyCount;
+    const avgDailyCost = totalCost / dailyCount;
+
+    // 預估月度成本（基於分析期間的日均用量）
+    const estimatedMonthlyCost = avgDailyCost * 30;
+    const estimatedAnnualCost = estimatedMonthlyCost * 12;
+
+    // 計算使用率
+    const tpmUtilization = pricing.tpmLimit > 0 ? (avgDailyTokens / pricing.tpmLimit) * 100 : 0;
+    const avgDailyRequests = totalRequests / dailyCount;
+    const rpmUtilization = pricing.rpmLimit > 0 ? (avgDailyRequests / pricing.rpmLimit) * 100 : 0;
+    const rpdUtilization = pricing.rpdLimit > 0 ? (avgDailyRequests / pricing.rpdLimit) * 100 : 0;
+
+    // 每 Token / 每 Request 成本
+    const costPerToken = totalTokens > 0 ? totalCost / totalTokens : 0;
+    const costPerRequest = totalRequests > 0 ? totalCost / totalRequests : 0;
+
+    return {
+      userId,
+      email: userEmail,
+      plan,
+      analysisDate: new Date(),
+      analysisDays: days,
+      totalRequests,
+      totalTokens,
+      inputTokens,
+      outputTokens,
+      avgDailyTokens,
+      avgDailyRequests,
+      inputCost,
+      outputCost,
+      totalCost,
+      monthlyPlanCost: 0,  // 無固定月費，成本基於使用量
+      estimatedMonthlyCost,
+      estimatedAnnualCost,
+      costPerToken,
+      costPerRequest,
+      tpmUtilization,
+      rpmUtilization,
+      rpdUtilization
+    };
+  }
+
+  /**
+   * 生成完整的成本分析報告
+   */
+  async generateBillingReport(
+    users: Array<{ id: string; email: string; plan: string }>,
+    days: number = 30
+  ): Promise<BillingReport> {
+    const metrics: BillingMetrics[] = [];
+
+    for (const user of users) {
+      try {
+        const metric = await this.calculateUserMetrics(user.id, user.email, user.plan, days);
+        metrics.push(metric);
+      } catch (error) {
+        console.warn(`⚠️  無法計算 ${user.email} 的成本指標`);
+      }
+    }
+
+    // 添加排行資訊
+    const sortedBySpend = [...metrics].sort((a, b) => b.estimatedMonthlyCost - a.estimatedMonthlyCost);
+    metrics.forEach((metric, index) => {
+      metric.rank = sortedBySpend.findIndex(m => m.userId === metric.userId) + 1;
+      metric.percentileRank = (metric.rank / metrics.length) * 100;
+    });
+
+    // 計算總成本
+    const totalCost = metrics.reduce((sum, m) => sum + m.estimatedMonthlyCost, 0);
+
+    // 按方案分組
+    const planBreakdown = new Map<string, { count: number; cost: number }>();
+    metrics.forEach(metric => {
+      const existing = planBreakdown.get(metric.plan) || { count: 0, cost: 0 };
+      existing.count++;
+      existing.cost += metric.estimatedMonthlyCost;
+      planBreakdown.set(metric.plan, existing);
+    });
+
+    const costBreakdown = Array.from(planBreakdown.entries())
+      .map(([plan, data]) => ({
+        plan,
+        userCount: data.count,
+        totalCost: data.cost,
+        percentage: (data.cost / totalCost) * 100
+      }))
+      .sort((a, b) => b.totalCost - a.totalCost);
+
+    return {
+      generatedAt: new Date(),
+      analysisPeriod: {
+        startDate: new Date(Date.now() - days * 24 * 60 * 60 * 1000),
+        endDate: new Date(),
+        days
+      },
+      totalUsers: metrics.length,
+      totalTokensAcrossUsers: metrics.reduce((sum, m) => sum + m.totalTokens, 0),
+      totalCostAcrossUsers: totalCost,
+      metrics,
+      topSpenders: sortedBySpend.slice(0, 10),
+      costBreakdown
+    };
+  }
+}