stack/apps/api/src/llm-usage/llm-usage.controller.ts

import { Controller, Get, Param, Query } from "@nestjs/common";
import type { LlmUsageLog } from "@prisma/client";
import { LlmUsageService } from "./llm-usage.service";
import { UsageAnalyticsQueryDto, UsageAnalyticsResponseDto } from "./dto";

/**
 * LLM Usage Controller
 *
 * Provides endpoints for querying LLM usage analytics and logs.
 * All endpoints return data in the standard API response format.
 */
@Controller("llm-usage")
export class LlmUsageController {
  constructor(private readonly llmUsageService: LlmUsageService) {}

  /**
   * Get aggregated usage analytics.
   * Supports filtering by workspace, provider, model, user, and date range.
   *
   * @param query - Analytics query parameters
   * @returns Aggregated usage analytics
   */
  @Get("analytics")
  async getAnalytics(
    @Query() query: UsageAnalyticsQueryDto
  ): Promise<{ data: UsageAnalyticsResponseDto }> {
    const data: UsageAnalyticsResponseDto = await this.llmUsageService.getUsageAnalytics(query);
    return { data };
  }

  /**
   * Get all usage logs for a specific workspace.
   *
   * @param workspaceId - Workspace UUID
   * @returns Array of usage logs
   */
  @Get("by-workspace/:workspaceId")
  async getUsageByWorkspace(
    @Param("workspaceId") workspaceId: string
  ): Promise<{ data: LlmUsageLog[] }> {
    const data: LlmUsageLog[] = await this.llmUsageService.getUsageByWorkspace(workspaceId);
    return { data };
  }

  /**
   * Get usage logs for a specific provider within a workspace.
   *
   * @param workspaceId - Workspace UUID
   * @param provider - Provider name
   * @returns Array of usage logs
   */
  @Get("by-workspace/:workspaceId/provider/:provider")
  async getUsageByProvider(
    @Param("workspaceId") workspaceId: string,
    @Param("provider") provider: string
  ): Promise<{ data: LlmUsageLog[] }> {
    const data: LlmUsageLog[] = await this.llmUsageService.getUsageByProvider(
      workspaceId,
      provider
    );
    return { data };
  }

  /**
   * Get usage logs for a specific model within a workspace.
   *
   * @param workspaceId - Workspace UUID
   * @param model - Model name
   * @returns Array of usage logs
   */
  @Get("by-workspace/:workspaceId/model/:model")
  async getUsageByModel(
    @Param("workspaceId") workspaceId: string,
    @Param("model") model: string
  ): Promise<{ data: LlmUsageLog[] }> {
    const data: LlmUsageLog[] = await this.llmUsageService.getUsageByModel(workspaceId, model);
    return { data };
  }
}