/api/v1/tenants/[id]/usage (management)

UsageResponse = z.object({
  tenant_id: z.string(),
  plan: TenantPlan,
  billing_period: BillingPeriod,
  usage: z.object({
    storage_gb: UsageMetric,
    requests: UsageMetric,
    hrm_inferences: UsageMetric,
    vector_searches: z.object({
      total: z.number().int(),
      cost: z.number(),
    }),
    graph_queries: z.object({
      total: z.number().int(),
      cost: z.number(),
    }),
  }),
  estimated_cost: z.object({
    base: z.number(), // Plan base cost
    usage: z.number(), // Overage cost
    total: z.number(), // Total estimated
    currency: z.literal('USD'),
  }),
})

export type UsageResponse = z.infer<typeof UsageResponse>

apiRequestCounter = new promClient.Counter({
  name: 'api_requests_total',
  help: 'Total number of API requests',
  labelNames: ['method', 'path', 'status', 'tenant_id'],
  registers: [register],
})

apiRequestDuration = new promClient.Histogram({
  name: 'api_request_duration_seconds',
  help: 'API request duration in seconds',
  labelNames: ['method', 'path', 'tenant_id'],
  buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5],
  registers: [register],
})

apiRequestErrors = new promClient.Counter({
  name: 'api_request_errors_total',
  help: 'Total number of API request errors',
  labelNames: ['method', 'path', 'error_type', 'tenant_id'],
  registers: [register],
})

interface RouteContext {
  params: Promise<{ id: string }>
}

export async function GET(request: NextRequest, context: RouteContext) {
  const requestId = generateRequestId()
  const { id: rawTenantId } = await context.params
  const pathLabel = '/api/v1/tenants/[id]/usage'
  const requestLogger = createRequestLogger(request)
  const traceContext = extractTraceContext(request.headers)
  const span = tracer.startSpan('tenant.usage.fetch', traceContext, {
    'http.method': 'GET',
    'http.route': pathLabel,
    'request.id': requestId,
    'tenant.id': rawTenantId,
  })
  const stopTimer = apiRequestDuration.startTimer()
  const startedAt = Date.now()

  let statusCode = 200
  let tenantIdForLog = rawTenantId
  let rateLimitInfo: RateLimitMetadata | undefined
  let planForLog: string | undefined

  try {
    const tenantId = validateTenantId(rawTenantId)
    tenantIdForLog = tenantId
    tracer.setSpanAttributes(span.spanId, { 'tenant.id': tenantId })

    requestLogger.info('Fetching tenant usage', {
      requestId,
      tenantId,
    })

    const authContext = await resolveAuthContext(request)
    const usage = await getTenantUsage(authContext, tenantId)
    planForLog = usage?.plan ?? undefined

    const evaluation = await enforceRateLimit({
      context: authContext,
      tenantId,
      tenantPlan: usage?.plan as string | undefined,
    }) ?? { metadata: { limit: 0, remaining: 0 }, retryAfter: 0 }

    rateLimitInfo = {
      ...evaluation.metadata,
      retryAfter: evaluation.retryAfter,
    }

    tracer.setSpanAttributes(span.spanId, {
      'rate.limit.limit': evaluation.metadata?.limit ?? 0,
      'rate.limit.remaining': evaluation.metadata?.remaining ?? 0,
      'tenant.plan': usage?.plan as string | undefined ?? '',
    })

    if (evaluation.blocked) {
      throw new RateLimitExceededError(evaluation.retryAfter ?? 60)
    }

    tenantOperations.inc({ tenant_id: tenantId, operation_type: 'usage_read' })
    tracer.addSpanEvent(span.spanId, 'usage.fetched', { 'tenant.id': tenantId })

    requestLogger.info('Tenant usage fetched', {
      requestId,
      tenantId,
      metadata: { plan: usage?.plan as string | undefined },
    })

    const response = apiSuccess<UsageResponse>(usage as UsageResponse)
    return withRequestMetadata(response, requestId, rateLimitInfo)
  } catch (error) {
    const normalizedError =
      error instanceof ApiError
        ? error
        : new ApiError(500, 'INTERNAL_ERROR', 'Failed to get usage')

    statusCode = normalizedError.statusCode

    apiRequestErrors.inc({
      method: 'GET',
      path: pathLabel,
      tenant_id: tenantIdForLog,
      error_type: normalizedError.code,
    })

    tracer.recordError(span.spanId, normalizedError)

    requestLogger.error('Failed to fetch tenant usage', {
      requestId,
      tenantId: tenantIdForLog,
      error: normalizedError,
      metadata: { plan: planForLog },
    })

    const response = apiError(normalizedError, requestId)
    return withRequestMetadata(response, requestId, rateLimitInfo)
  } finally {
    stopTimer({
      method: 'GET',
      path: pathLabel,
      tenant_id: tenantIdForLog,
    })

    apiRequestCounter.inc({
      method: 'GET',
      path: pathLabel,
      tenant_id: tenantIdForLog,
    })

    const durationMs = Date.now() - startedAt
    requestLogger.logResponse('GET', pathLabel, statusCode, durationMs, {
      requestId,
      tenantId: tenantIdForLog,
      metadata: { plan: planForLog, rateLimit: rateLimitInfo },
    })

    tracer.setSpanAttributes(span.spanId, {
      'http.status_code': statusCode,
      'tenant.id': tenantIdForLog,
      'tenant.plan': planForLog ?? '',
    })

    tracer.endSpan(span.spanId)
  }
}

new RateLimitExceededError(evaluation.retryAfter ?? 60)

apiSuccess<UsageResponse>(usage as UsageResponse)

new ApiError(500, 'INTERNAL_ERROR', 'Failed to get usage')

tracer.recordError(span.spanId, normalizedError)

apiError(normalizedError, requestId)