@open-mercato/ai-assistant 0.6.1-develop.3291.1.6fad645fd0 → 0.6.1

package/src/modules/ai_assistant/api/usage/sessions/[sessionId]/route.ts

@@ -0,0 +1,130 @@
+import { NextResponse, type NextRequest } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
+import { AiTokenUsageRepository } from '../../../../data/repositories/AiTokenUsageRepository'
+import { hasRequiredFeatures } from '../../../../lib/auth'
+import { toInteger, toIsoString } from '../../../../lib/usage-serialization'
+
+const REQUIRED_FEATURE = 'ai_assistant.settings.manage'
+
+const sessionIdParamSchema = z.object({
+  sessionId: z
+    .string()
+    .trim()
+    .uuid('sessionId must be a valid UUID'),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'AI Assistant',
+  summary: 'Per-step token usage events for a session',
+  methods: {
+    GET: {
+      operationId: 'aiAssistantUsageSessionDetail',
+      summary: 'Fetch per-step token usage event rows for a single session.',
+      description:
+        'Returns up to 200 raw `ai_token_usage_events` rows for the given `sessionId`, ' +
+        'ordered by `created_at ASC, step_index ASC`. Tenant-scoped. ' +
+        'Requires `ai_assistant.settings.manage`.',
+      responses: [
+        {
+          status: 200,
+          description: 'Array of per-step event rows for the session.',
+          mediaType: 'application/json',
+        },
+      ],
+      errors: [
+        { status: 400, description: 'Invalid session id (must be a UUID).' },
+        { status: 401, description: 'Unauthenticated caller.' },
+        { status: 403, description: 'Caller lacks `ai_assistant.settings.manage`.' },
+        { status: 404, description: 'No events found for the given session id in the caller\'s tenant.' },
+        { status: 500, description: 'Internal failure.' },
+      ],
+    },
+  },
+}
+
+export const metadata = {
+  path: '/ai_assistant/usage/sessions/[sessionId]',
+  GET: { requireAuth: true, requireFeatures: [REQUIRED_FEATURE] },
+}
+
+interface RouteContext {
+  params: Promise<{ sessionId: string }>
+}
+
+function jsonError(status: number, message: string, code: string, extra?: Record<string, unknown>): NextResponse {
+  return NextResponse.json({ error: message, code, ...(extra ?? {}) }, { status })
+}
+
+export async function GET(req: NextRequest, context: RouteContext): Promise<Response> {
+  const auth = await getAuthFromRequest(req)
+  if (!auth) {
+    return jsonError(401, 'Unauthorized', 'unauthenticated')
+  }
+
+  const rawParams = await context.params
+  const paramResult = sessionIdParamSchema.safeParse(rawParams)
+  if (!paramResult.success) {
+    return jsonError(400, 'Invalid session id.', 'validation_error', {
+      issues: paramResult.error.issues,
+    })
+  }
+
+  const { sessionId } = paramResult.data
+
+  try {
+    const container = await createRequestContainer()
+    const rbacService = container.resolve<RbacService>('rbacService')
+    const acl = await rbacService.loadAcl(auth.sub, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+
+    if (!hasRequiredFeatures([REQUIRED_FEATURE], acl.features, acl.isSuperAdmin, rbacService)) {
+      return jsonError(403, `Caller lacks required feature "${REQUIRED_FEATURE}".`, 'forbidden')
+    }
+
+    if (!auth.tenantId) {
+      return jsonError(404, `No events found for session "${sessionId}".`, 'session_not_found')
+    }
+
+    const em = container.resolve<EntityManager>('em')
+    const repo = new AiTokenUsageRepository(em)
+    const events = await repo.listEventsForSession(auth.tenantId, sessionId)
+
+    if (events.length === 0) {
+      return jsonError(404, `No events found for session "${sessionId}".`, 'session_not_found')
+    }
+
+    const serialized = events.map((event) => ({
+      id: event.id,
+      tenantId: event.tenantId,
+      organizationId: event.organizationId ?? null,
+      userId: event.userId,
+      agentId: event.agentId,
+      moduleId: event.moduleId,
+      sessionId: event.sessionId,
+      turnId: event.turnId,
+      stepIndex: toInteger(event.stepIndex),
+      providerId: event.providerId,
+      modelId: event.modelId,
+      inputTokens: toInteger(event.inputTokens),
+      outputTokens: toInteger(event.outputTokens),
+      cachedInputTokens: event.cachedInputTokens == null ? null : toInteger(event.cachedInputTokens),
+      reasoningTokens: event.reasoningTokens == null ? null : toInteger(event.reasoningTokens),
+      finishReason: event.finishReason ?? null,
+      loopAbortReason: event.loopAbortReason ?? null,
+      createdAt: toIsoString(event.createdAt),
+      updatedAt: toIsoString(event.updatedAt),
+    }))
+
+    return NextResponse.json({ events: serialized, total: serialized.length, sessionId })
+  } catch (error) {
+    console.error('[AI Usage Session Detail] GET error:', error)
+    return jsonError(500, 'Failed to fetch session event data.', 'internal_error')
+  }
+}

package/src/modules/ai_assistant/api/usage/sessions/__tests__/route.test.ts

@@ -0,0 +1,123 @@
+const authMock = jest.fn()
+const loadAclMock = jest.fn()
+const createRequestContainerMock = jest.fn()
+const executeMock = jest.fn()
+
+jest.mock('@open-mercato/shared/lib/auth/server', () => ({
+  getAuthFromRequest: (...args: unknown[]) => authMock(...args),
+}))
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: (...args: unknown[]) => createRequestContainerMock(...args),
+}))
+
+import { GET } from '../route'
+
+function buildRequest(params: Record<string, string> = {}) {
+  const url = new URL('http://localhost/api/ai_assistant/usage/sessions')
+  for (const [k, v] of Object.entries(params)) {
+    url.searchParams.set(k, v)
+  }
+  return new Request(url.toString(), { method: 'GET' })
+}
+
+function defaultParams(overrides: Record<string, string> = {}) {
+  return {
+    from: '2026-05-01',
+    to: '2026-05-31',
+    ...overrides,
+  }
+}
+
+function makeSessionRow(overrides: Record<string, unknown> = {}) {
+  return {
+    session_id: '11111111-1111-4111-8111-111111111111',
+    agent_id: 'catalog.assistant',
+    module_id: 'catalog',
+    user_id: '22222222-2222-4222-8222-222222222222',
+    started_at: '2026-05-01T12:00:00.000Z',
+    last_event_at: '2026-05-01T12:30:00.000Z',
+    step_count: 5n,
+    turn_count: 3n,
+    input_tokens: 1000n,
+    output_tokens: 500n,
+    cached_input_tokens: 10n,
+    reasoning_tokens: 20n,
+    ...overrides,
+  }
+}
+
+describe('GET /api/ai_assistant/usage/sessions', () => {
+  let consoleErrorSpy: jest.SpyInstance
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    authMock.mockResolvedValue({ sub: 'user-1', tenantId: 'tenant-1', orgId: null })
+    loadAclMock.mockResolvedValue({ features: ['ai_assistant.settings.manage'], isSuperAdmin: false })
+    executeMock
+      .mockResolvedValueOnce([{ total: 1n }])
+      .mockResolvedValueOnce([makeSessionRow()])
+    createRequestContainerMock.mockResolvedValue({
+      resolve: (name: string) => {
+        if (name === 'rbacService') return { loadAcl: loadAclMock, hasAllFeatures: (req: string[], have: string[]) => req.every((r) => have.includes(r)) }
+        if (name === 'em') return { getConnection: () => ({ execute: executeMock }) }
+        throw new Error(`Unknown token: ${name}`)
+      },
+    })
+  })
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore()
+  })
+
+  it('returns 401 when unauthenticated', async () => {
+    authMock.mockResolvedValue(null)
+    const res = await GET(buildRequest(defaultParams()) as Parameters<typeof GET>[0])
+    expect(res.status).toBe(401)
+  })
+
+  it('returns 403 when caller lacks ai_assistant.settings.manage', async () => {
+    loadAclMock.mockResolvedValue({ features: ['ai_assistant.view'], isSuperAdmin: false })
+    const res = await GET(buildRequest(defaultParams()) as Parameters<typeof GET>[0])
+    expect(res.status).toBe(403)
+  })
+
+  it('returns 400 when from is missing', async () => {
+    const res = await GET(buildRequest({ to: '2026-05-31' }) as Parameters<typeof GET>[0])
+    expect(res.status).toBe(400)
+    const body = await res.json()
+    expect(body.code).toBe('validation_error')
+  })
+
+  it('serializes bigint aggregates and string timestamps returned by the database driver', async () => {
+    const res = await GET(buildRequest(defaultParams({ limit: '50', offset: '0' })) as Parameters<typeof GET>[0])
+
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body.total).toBe(1)
+    expect(body.sessions).toHaveLength(1)
+    expect(body.sessions[0]).toMatchObject({
+      sessionId: '11111111-1111-4111-8111-111111111111',
+      agentId: 'catalog.assistant',
+      moduleId: 'catalog',
+      userId: '22222222-2222-4222-8222-222222222222',
+      startedAt: '2026-05-01T12:00:00.000Z',
+      lastEventAt: '2026-05-01T12:30:00.000Z',
+      stepCount: 5,
+      turnCount: 3,
+      inputTokens: 1000,
+      outputTokens: 500,
+      cachedInputTokens: 10,
+      reasoningTokens: 20,
+    })
+  })
+
+  it('passes the agent filter to the aggregate queries', async () => {
+    const res = await GET(buildRequest(defaultParams({ agentId: 'catalog.assistant' })) as Parameters<typeof GET>[0])
+
+    expect(res.status).toBe(200)
+    expect(executeMock.mock.calls[0][1]).toEqual(['tenant-1', '2026-05-01', '2026-05-31', 'catalog.assistant'])
+    expect(executeMock.mock.calls[1][1]).toEqual(['tenant-1', '2026-05-01', '2026-05-31', 'catalog.assistant', 100, 0])
+  })
+})

package/src/modules/ai_assistant/api/usage/sessions/route.ts

@@ -0,0 +1,184 @@
+import { NextResponse, type NextRequest } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
+import { hasRequiredFeatures } from '../../../lib/auth'
+import { toInteger, toIsoString } from '../../../lib/usage-serialization'
+
+const REQUIRED_FEATURE = 'ai_assistant.settings.manage'
+
+const MAX_PAGE_SIZE = 100
+
+const querySchema = z.object({
+  from: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'from must be a date in YYYY-MM-DD format'),
+  to: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'to must be a date in YYYY-MM-DD format'),
+  agentId: z.string().min(1).max(256).optional(),
+  limit: z
+    .string()
+    .optional()
+    .transform((val) => (val !== undefined ? parseInt(val, 10) : MAX_PAGE_SIZE))
+    .refine((val) => !isNaN(val) && val > 0 && val <= MAX_PAGE_SIZE, {
+      message: `limit must be between 1 and ${MAX_PAGE_SIZE}`,
+    }),
+  offset: z
+    .string()
+    .optional()
+    .transform((val) => (val !== undefined ? parseInt(val, 10) : 0))
+    .refine((val) => !isNaN(val) && val >= 0, { message: 'offset must be a non-negative integer' }),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'AI Assistant',
+  summary: 'Per-session token usage totals',
+  methods: {
+    GET: {
+      operationId: 'aiAssistantUsageSessions',
+      summary: 'List per-session token usage totals for a date window.',
+      description:
+        'Returns aggregated token-usage data grouped by `session_id` from `ai_token_usage_events` ' +
+        'for the given date window. Tenant-scoped. Optionally filtered by `agentId`. ' +
+        'Paginated via `limit` / `offset`. Requires `ai_assistant.settings.manage`.',
+      query: querySchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Array of session-level usage summaries plus pagination metadata.',
+          mediaType: 'application/json',
+        },
+      ],
+      errors: [
+        { status: 400, description: 'Invalid query parameters.' },
+        { status: 401, description: 'Unauthenticated caller.' },
+        { status: 403, description: 'Caller lacks `ai_assistant.settings.manage`.' },
+        { status: 500, description: 'Internal failure.' },
+      ],
+    },
+  },
+}
+
+export const metadata = {
+  path: '/ai_assistant/usage/sessions',
+  GET: { requireAuth: true, requireFeatures: [REQUIRED_FEATURE] },
+}
+
+function jsonError(status: number, message: string, code: string, extra?: Record<string, unknown>): NextResponse {
+  return NextResponse.json({ error: message, code, ...(extra ?? {}) }, { status })
+}
+
+export async function GET(req: NextRequest): Promise<Response> {
+  const auth = await getAuthFromRequest(req)
+  if (!auth) {
+    return jsonError(401, 'Unauthorized', 'unauthenticated')
+  }
+
+  const { searchParams } = new URL(req.url)
+  const rawQuery = {
+    from: searchParams.get('from') ?? undefined,
+    to: searchParams.get('to') ?? undefined,
+    agentId: searchParams.get('agentId') ?? undefined,
+    limit: searchParams.get('limit') ?? undefined,
+    offset: searchParams.get('offset') ?? undefined,
+  }
+
+  const queryResult = querySchema.safeParse(rawQuery)
+  if (!queryResult.success) {
+    return jsonError(400, 'Invalid query parameters.', 'validation_error', {
+      issues: queryResult.error.issues,
+    })
+  }
+
+  const { from, to, agentId, limit, offset } = queryResult.data
+
+  try {
+    const container = await createRequestContainer()
+    const rbacService = container.resolve<RbacService>('rbacService')
+    const acl = await rbacService.loadAcl(auth.sub, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+    })
+
+    if (!hasRequiredFeatures([REQUIRED_FEATURE], acl.features, acl.isSuperAdmin, rbacService)) {
+      return jsonError(403, `Caller lacks required feature "${REQUIRED_FEATURE}".`, 'forbidden')
+    }
+
+    if (!auth.tenantId) {
+      return NextResponse.json({ sessions: [], total: 0, limit, offset })
+    }
+
+    const em = container.resolve<EntityManager>('em')
+    const connection = em.getConnection()
+
+    const params: unknown[] = [auth.tenantId, from, to]
+    let agentFilter = ''
+    if (agentId) {
+      agentFilter = 'and agent_id = ?'
+      params.push(agentId)
+    }
+
+    const countParams = [...params]
+    const countSql = `
+      select count(distinct session_id)::bigint as total
+      from ai_token_usage_events
+      where tenant_id = ?
+        and created_at >= ?::date
+        and created_at < (?::date + interval '1 day')
+        ${agentFilter}
+    `
+    const countRows = await connection.execute(countSql, countParams, 'all')
+    const totalRaw = Array.isArray(countRows) && countRows.length > 0
+      ? (countRows[0] as Record<string, unknown>).total
+      : '0'
+    const total = toInteger(totalRaw)
+
+    params.push(limit, offset)
+    const dataSql = `
+      select
+        session_id,
+        agent_id,
+        module_id,
+        user_id,
+        min(created_at) as started_at,
+        max(created_at) as last_event_at,
+        count(*)::bigint as step_count,
+        count(distinct turn_id)::bigint as turn_count,
+        sum(input_tokens)::bigint as input_tokens,
+        sum(output_tokens)::bigint as output_tokens,
+        sum(coalesce(cached_input_tokens, 0))::bigint as cached_input_tokens,
+        sum(coalesce(reasoning_tokens, 0))::bigint as reasoning_tokens
+      from ai_token_usage_events
+      where tenant_id = ?
+        and created_at >= ?::date
+        and created_at < (?::date + interval '1 day')
+        ${agentFilter}
+      group by session_id, agent_id, module_id, user_id
+      order by started_at desc
+      limit ? offset ?
+    `
+    const dataRows = await connection.execute(dataSql, params, 'all')
+
+    const sessions = Array.isArray(dataRows)
+      ? (dataRows as Array<Record<string, unknown>>).map((row) => ({
+          sessionId: row.session_id as string,
+          agentId: row.agent_id as string,
+          moduleId: row.module_id as string,
+          userId: row.user_id as string,
+          startedAt: toIsoString(row.started_at),
+          lastEventAt: toIsoString(row.last_event_at),
+          stepCount: toInteger(row.step_count),
+          turnCount: toInteger(row.turn_count),
+          inputTokens: toInteger(row.input_tokens),
+          outputTokens: toInteger(row.output_tokens),
+          cachedInputTokens: toInteger(row.cached_input_tokens),
+          reasoningTokens: toInteger(row.reasoning_tokens),
+        }))
+      : []
+
+    return NextResponse.json({ sessions, total, limit, offset })
+  } catch (error) {
+    console.error('[AI Usage Sessions] GET error:', error)
+    return jsonError(500, 'Failed to fetch session usage data.', 'internal_error')
+  }
+}