Add web api endpoint for usage

jahooma · jahooma · commit fde49c75712c · 2025-11-18T17:16:57.000-08:00
diff --git a/cli/src/commands/usage.ts b/cli/src/commands/usage.ts
@@ -1,4 +1,4 @@
-import { BACKEND_URL } from '@codebuff/sdk'
+import { WEBSITE_URL } from '@codebuff/sdk'
 
 import { useChatStore } from '../state/chat-store'
 import { getAuthToken } from '../utils/auth'
@@ -30,7 +30,7 @@ export async function handleUsageCommand(): Promise<{
   }
 
   try {
-    const response = await fetch(`${BACKEND_URL}/api/usage`, {
+    const response = await fetch(`${WEBSITE_URL}/api/v1/usage`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
diff --git a/common/src/constants/analytics-events.ts b/common/src/constants/analytics-events.ts
@@ -102,6 +102,10 @@ export enum AnalyticsEvent {
   CHAT_COMPLETIONS_STREAM_STARTED = 'api.chat_completions_stream_started',
   CHAT_COMPLETIONS_ERROR = 'api.chat_completions_error',
 
+  // Web - Usage API
+  USAGE_API_REQUEST = 'api.usage_request',
+  USAGE_API_AUTH_ERROR = 'api.usage_auth_error',
+
   // Web - Search API
   WEB_SEARCH_REQUEST = 'api.web_search_request',
   WEB_SEARCH_AUTH_ERROR = 'api.web_search_auth_error',
diff --git a/common/src/types/contracts/billing.ts b/common/src/types/contracts/billing.ts
@@ -5,8 +5,15 @@ export type GetUserUsageDataFn = (params: {
   userId: string
   logger: Logger
 }) => Promise<{
-  balance: { totalRemaining: number }
+  usageThisCycle: number
+  balance: {
+    totalRemaining: number
+    totalDebt: number
+    netBalance: number
+    breakdown: Record<string, number>
+  }
   nextQuotaReset: string
+  autoTopupTriggered?: boolean
 }>
 
 export type ConsumeCreditsWithFallbackFn = (params: {
@@ -22,3 +29,15 @@ export type CreditFallbackResult = {
   organizationName?: string
   chargedToOrganization: boolean
 }
+
+export type GetOrganizationUsageResponseFn = (params: {
+  organizationId: string
+  userId: string
+  logger: Logger
+}) => Promise<{
+  type: 'usage-response'
+  usage: number
+  remainingBalance: number
+  balanceBreakdown: Record<string, never>
+  next_quota_reset: null
+}>
diff --git a/web/src/app/api/v1/chat/completions/__tests__/completions.test.ts b/web/src/app/api/v1/chat/completions/__tests__/completions.test.ts
@@ -63,12 +63,24 @@ describe('/api/v1/chat/completions POST endpoint', () => {
     mockGetUserUsageData = mock(async ({ userId }: { userId: string }) => {
       if (userId === 'user-no-credits') {
         return {
-          balance: { totalRemaining: 0 },
+          usageThisCycle: 0,
+          balance: {
+            totalRemaining: 0,
+            totalDebt: 0,
+            netBalance: 0,
+            breakdown: {},
+          },
           nextQuotaReset: '2024-12-31',
         }
       }
       return {
-        balance: { totalRemaining: 100 },
+        usageThisCycle: 0,
+        balance: {
+          totalRemaining: 100,
+          totalDebt: 0,
+          netBalance: 100,
+          breakdown: {},
+        },
         nextQuotaReset: '2024-12-31',
       }
     })
diff --git a/web/src/app/api/v1/docs-search/__tests__/docs-search.test.ts b/web/src/app/api/v1/docs-search/__tests__/docs-search.test.ts
@@ -34,7 +34,13 @@ describe('/api/v1/docs-search POST endpoint', () => {
     mockTrackEvent = mock(() => {})
 
     mockGetUserUsageData = mock(async () => ({
-      balance: { totalRemaining: 10 },
+      usageThisCycle: 0,
+      balance: {
+        totalRemaining: 10,
+        totalDebt: 0,
+        netBalance: 10,
+        breakdown: {},
+      },
       nextQuotaReset: 'soon',
     }))
     mockGetUserInfoFromApiKey = mock(async ({ apiKey }) =>
@@ -99,7 +105,13 @@ describe('/api/v1/docs-search POST endpoint', () => {
 
   test('402 when insufficient credits', async () => {
     mockGetUserUsageData = mock(async () => ({
-      balance: { totalRemaining: 0 },
+      usageThisCycle: 0,
+      balance: {
+        totalRemaining: 0,
+        totalDebt: 0,
+        netBalance: 0,
+        breakdown: {},
+      },
       nextQuotaReset: 'soon',
     }))
     const req = new NextRequest('http://localhost:3000/api/v1/docs-search', {
diff --git a/web/src/app/api/v1/usage/_post.ts b/web/src/app/api/v1/usage/_post.ts
@@ -0,0 +1,141 @@
+import { AnalyticsEvent } from '@codebuff/common/constants/analytics-events'
+import { INVALID_AUTH_TOKEN_MESSAGE } from '@codebuff/common/old-constants'
+import { NextResponse } from 'next/server'
+import { z } from 'zod/v4'
+
+import type { TrackEventFn } from '@codebuff/common/types/contracts/analytics'
+import type {
+  GetUserInfoFromApiKeyFn,
+} from '@codebuff/common/types/contracts/database'
+import type { Logger } from '@codebuff/common/types/contracts/logger'
+import type { NextRequest } from 'next/server'
+
+import type { GetOrganizationUsageResponseFn, GetUserUsageDataFn } from '@codebuff/common/types/contracts/billing'
+
+const usageRequestSchema = z.object({
+  fingerprintId: z.string(),
+  authToken: z.string().optional(),
+  orgId: z.string().optional(),
+})
+
+export async function postUsage(params: {
+  req: NextRequest
+  getUserInfoFromApiKey: GetUserInfoFromApiKeyFn
+  getUserUsageData: GetUserUsageDataFn
+  getOrganizationUsageResponse: GetOrganizationUsageResponseFn
+  trackEvent: TrackEventFn
+  logger: Logger
+}) {
+  const {
+    req,
+    getUserInfoFromApiKey,
+    getUserUsageData,
+    getOrganizationUsageResponse,
+    trackEvent,
+    logger,
+  } = params
+
+  try {
+    let body: unknown
+    try {
+      body = await req.json()
+    } catch (error) {
+      return NextResponse.json(
+        { message: 'Invalid JSON in request body' },
+        { status: 400 },
+      )
+    }
+
+    const parseResult = usageRequestSchema.safeParse(body)
+    if (!parseResult.success) {
+      return NextResponse.json(
+        { message: 'Invalid request body', issues: parseResult.error.issues },
+        { status: 400 },
+      )
+    }
+
+    const { fingerprintId, authToken, orgId } = parseResult.data
+
+    if (!authToken) {
+      return NextResponse.json(
+        { message: 'Authentication required' },
+        { status: 401 },
+      )
+    }
+
+    const userInfo = await getUserInfoFromApiKey({
+      apiKey: authToken,
+      fields: ['id'],
+      logger,
+    })
+
+    if (!userInfo) {
+      trackEvent({
+        event: AnalyticsEvent.USAGE_API_AUTH_ERROR,
+        userId: 'unknown',
+        properties: {
+          reason: 'Invalid API key',
+        },
+        logger,
+      })
+      return NextResponse.json(
+        { message: INVALID_AUTH_TOKEN_MESSAGE },
+        { status: 401 },
+      )
+    }
+
+    const userId = userInfo.id
+
+    trackEvent({
+      event: AnalyticsEvent.USAGE_API_REQUEST,
+      userId,
+      properties: {
+        fingerprintId,
+        hasOrgId: !!orgId,
+      },
+      logger,
+    })
+
+    // If orgId is provided, return organization usage data
+    if (orgId) {
+      try {
+        const orgUsageResponse = await getOrganizationUsageResponse({
+          organizationId: orgId,
+          userId,
+          logger,
+        })
+        return NextResponse.json(orgUsageResponse)
+      } catch (error) {
+        logger.error(
+          { error, orgId, userId },
+          'Error fetching organization usage',
+        )
+        // If organization usage fails, fall back to personal usage
+        logger.info(
+          { orgId, userId },
+          'Falling back to personal usage due to organization error',
+        )
+      }
+    }
+
+    // Return personal usage data (default behavior)
+    const usageData = await getUserUsageData({ userId, logger })
+
+    // Format response to match backend API format
+    const usageResponse = {
+      type: 'usage-response' as const,
+      usage: usageData.usageThisCycle,
+      remainingBalance: usageData.balance.totalRemaining,
+      balanceBreakdown: usageData.balance.breakdown,
+      next_quota_reset: usageData.nextQuotaReset,
+    }
+
+    return NextResponse.json(usageResponse)
+  } catch (error) {
+    logger.error({ error }, 'Error handling /api/v1/usage request')
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 },
+    )
+  }
+}
diff --git a/web/src/app/api/v1/usage/route.ts b/web/src/app/api/v1/usage/route.ts
@@ -0,0 +1,20 @@
+import { getUserUsageData, getOrganizationUsageResponse } from '@codebuff/billing'
+import { trackEvent } from '@codebuff/common/analytics'
+
+import { postUsage } from './_post'
+
+import type { NextRequest } from 'next/server'
+
+import { getUserInfoFromApiKey } from '@/db/user'
+import { logger } from '@/util/logger'
+
+export async function POST(req: NextRequest) {
+  return postUsage({
+    req,
+    getUserInfoFromApiKey,
+    getUserUsageData,
+    getOrganizationUsageResponse,
+    trackEvent,
+    logger,
+  })
+}
diff --git a/web/src/app/api/v1/web-search/__tests__/web-search.test.ts b/web/src/app/api/v1/web-search/__tests__/web-search.test.ts
@@ -34,7 +34,13 @@ describe('/api/v1/web-search POST endpoint', () => {
     mockTrackEvent = mock(() => {})
 
     mockGetUserUsageData = mock(async () => ({
-      balance: { totalRemaining: 10 },
+      usageThisCycle: 0,
+      balance: {
+        totalRemaining: 10,
+        totalDebt: 0,
+        netBalance: 10,
+        breakdown: {},
+      },
       nextQuotaReset: 'soon',
     }))
     mockGetUserInfoFromApiKey = mock(async ({ apiKey }) =>
@@ -77,7 +83,13 @@ describe('/api/v1/web-search POST endpoint', () => {
 
   test('402 when insufficient credits', async () => {
     mockGetUserUsageData = mock(async () => ({
-      balance: { totalRemaining: 0 },
+      usageThisCycle: 0,
+      balance: {
+        totalRemaining: 0,
+        totalDebt: 0,
+        netBalance: 0,
+        breakdown: {},
+      },
       nextQuotaReset: 'soon',
     }))
     const req = new NextRequest('http://localhost:3000/api/v1/web-search', {
