@open-mercato/ai-assistant 0.4.2-canary-c02407ff85

package/src/modules/ai_assistant/lib/api-endpoint-index.ts

@@ -0,0 +1,381 @@
+/**
+ * API Endpoint Index
+ *
+ * Parses OpenAPI spec and indexes endpoints for discovery via hybrid search.
+ */
+
+import type { OpenApiDocument } from '@open-mercato/shared/lib/openapi'
+import type { SearchService } from '@open-mercato/search/service'
+import type { IndexableRecord } from '@open-mercato/search/types'
+import {
+  API_ENDPOINT_ENTITY_ID,
+  GLOBAL_TENANT_ID,
+  API_ENDPOINT_SEARCH_CONFIG,
+  endpointToIndexableRecord,
+  computeEndpointsChecksum,
+} from './api-endpoint-index-config'
+
+/**
+ * Indexed API endpoint structure
+ */
+export interface ApiEndpoint {
+  id: string
+  operationId: string
+  method: string
+  path: string
+  summary: string
+  description: string
+  tags: string[]
+  requiredFeatures: string[]
+  parameters: ApiParameter[]
+  requestBodySchema: Record<string, unknown> | null
+  deprecated: boolean
+}
+
+export interface ApiParameter {
+  name: string
+  in: 'path' | 'query' | 'header'
+  required: boolean
+  type: string
+  description: string
+}
+
+/**
+ * Entity type for API endpoints in search index
+ * @deprecated Use API_ENDPOINT_ENTITY_ID from api-endpoint-index-config.ts
+ */
+export const API_ENDPOINT_ENTITY = API_ENDPOINT_ENTITY_ID
+
+/**
+ * In-memory cache of parsed endpoints (avoid re-parsing on each request)
+ */
+let endpointsCache: ApiEndpoint[] | null = null
+let endpointsByOperationId: Map<string, ApiEndpoint> | null = null
+
+/**
+ * Get all parsed API endpoints (cached)
+ */
+export async function getApiEndpoints(): Promise<ApiEndpoint[]> {
+  if (endpointsCache) {
+    return endpointsCache
+  }
+
+  endpointsCache = await parseApiEndpoints()
+  endpointsByOperationId = new Map(endpointsCache.map((e) => [e.operationId, e]))
+
+  return endpointsCache
+}
+
+/**
+ * Get endpoint by operationId
+ */
+export async function getEndpointByOperationId(operationId: string): Promise<ApiEndpoint | null> {
+  await getApiEndpoints() // Ensure cache is populated
+  return endpointsByOperationId?.get(operationId) ?? null
+}
+
+/**
+ * Parse OpenAPI spec into indexable endpoints
+ * Fetches the OpenAPI spec from the running app's /api/docs/openapi endpoint
+ */
+async function parseApiEndpoints(): Promise<ApiEndpoint[]> {
+  const baseUrl =
+    process.env.NEXT_PUBLIC_API_BASE_URL ||
+    process.env.NEXT_PUBLIC_APP_URL ||
+    process.env.APP_URL ||
+    'http://localhost:3000'
+
+  const openApiUrl = `${baseUrl}/api/docs/openapi`
+
+  try {
+    console.error(`[API Index] Fetching OpenAPI spec from ${openApiUrl}...`)
+    const response = await fetch(openApiUrl)
+
+    if (!response.ok) {
+      console.error(`[API Index] Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`)
+      return []
+    }
+
+    const doc = (await response.json()) as OpenApiDocument
+    console.error(`[API Index] Successfully fetched OpenAPI spec`)
+    return extractEndpoints(doc)
+  } catch (error) {
+    console.error('[API Index] Could not fetch OpenAPI spec:', error instanceof Error ? error.message : error)
+    console.error('[API Index] Make sure the app is running at', baseUrl)
+    return []
+  }
+}
+
+/**
+ * Extract endpoints from OpenAPI document
+ */
+function extractEndpoints(doc: OpenApiDocument): ApiEndpoint[] {
+  const endpoints: ApiEndpoint[] = []
+  const validMethods = ['get', 'post', 'put', 'patch', 'delete']
+
+  if (!doc.paths) {
+    return endpoints
+  }
+
+  for (const [path, pathItem] of Object.entries(doc.paths)) {
+    if (!pathItem || typeof pathItem !== 'object') continue
+
+    for (const [method, operation] of Object.entries(pathItem)) {
+      if (!validMethods.includes(method.toLowerCase())) continue
+      if (!operation || typeof operation !== 'object') continue
+
+      const op = operation as any
+
+      // Generate operationId if not present
+      const operationId = op.operationId || generateOperationId(path, method)
+
+      const endpoint: ApiEndpoint = {
+        id: operationId,
+        operationId,
+        method: method.toUpperCase(),
+        path,
+        summary: op.summary || '',
+        description: op.description || op.summary || `${method.toUpperCase()} ${path}`,
+        tags: op.tags || [],
+        requiredFeatures: op['x-require-features'] || [],
+        deprecated: op.deprecated || false,
+        parameters: extractParameters(op.parameters || []),
+        requestBodySchema: extractRequestBodySchema(op.requestBody, doc.components?.schemas),
+      }
+
+      endpoints.push(endpoint)
+    }
+  }
+
+  console.error(`[API Index] Parsed ${endpoints.length} endpoints from OpenAPI spec`)
+  return endpoints
+}
+
+/**
+ * Generate operationId from path and method
+ */
+function generateOperationId(path: string, method: string): string {
+  const pathParts = path
+    .replace(/^\//, '')
+    .replace(/\{([^}]+)\}/g, 'by_$1')
+    .split('/')
+    .filter(Boolean)
+    .join('_')
+
+  return `${method.toLowerCase()}_${pathParts}`
+}
+
+/**
+ * Extract parameter info
+ */
+function extractParameters(params: any[]): ApiParameter[] {
+  return params
+    .filter((p) => p.in === 'path' || p.in === 'query')
+    .map((p) => ({
+      name: p.name,
+      in: p.in,
+      required: p.required ?? false,
+      type: p.schema?.type || 'string',
+      description: p.description || '',
+    }))
+}
+
+/**
+ * Extract request body schema (simplified)
+ */
+function extractRequestBodySchema(
+  requestBody: any,
+  schemas?: Record<string, any>
+): Record<string, unknown> | null {
+  if (!requestBody?.content?.['application/json']?.schema) {
+    return null
+  }
+
+  const schema = requestBody.content['application/json'].schema
+
+  // Resolve $ref if present
+  if (schema.$ref && schemas) {
+    const refPath = schema.$ref.replace('#/components/schemas/', '')
+    return schemas[refPath] || schema
+  }
+
+  return schema
+}
+
+/**
+ * Checksum from last indexing operation
+ */
+let lastIndexChecksum: string | null = null
+
+/**
+ * Index endpoints for search discovery using hybrid search strategies.
+ * Uses checksum-based change detection to avoid unnecessary re-indexing.
+ *
+ * @param searchService - The search service to use for indexing
+ * @param force - Force re-indexing even if checksum hasn't changed
+ * @returns Number of endpoints indexed
+ */
+export async function indexApiEndpoints(
+  searchService: SearchService,
+  force = false
+): Promise<number> {
+  const endpoints = await getApiEndpoints()
+
+  if (endpoints.length === 0) {
+    console.error('[API Index] No endpoints to index')
+    return 0
+  }
+
+  // Compute checksum to detect changes
+  const checksum = computeEndpointsChecksum(
+    endpoints.map((e) => ({ operationId: e.operationId, method: e.method, path: e.path }))
+  )
+
+  // Skip if checksum matches and not forced
+  if (!force && lastIndexChecksum === checksum) {
+    console.error(`[API Index] Skipping indexing - ${endpoints.length} endpoints unchanged`)
+    return 0
+  }
+
+  // Convert to indexable records using the proper format
+  const records: IndexableRecord[] = endpoints.map((endpoint) =>
+    endpointToIndexableRecord(endpoint)
+  )
+
+  try {
+    console.error(`[API Index] Starting bulk index of ${records.length} endpoints...`)
+    // Bulk index using all available strategies (fulltext + vector)
+    // Use Promise.race with timeout to prevent hanging
+    const timeoutMs = 60000 // 60 second timeout
+    const indexPromise = searchService.bulkIndex(records)
+    const timeoutPromise = new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error(`Bulk index timed out after ${timeoutMs}ms`)), timeoutMs)
+    )
+
+    await Promise.race([indexPromise, timeoutPromise])
+    lastIndexChecksum = checksum
+    console.error(`[API Index] Indexed ${records.length} API endpoints for hybrid search`)
+    return records.length
+  } catch (error) {
+    console.error('[API Index] Failed to index endpoints:', error)
+    // Still return the count - some strategies may have succeeded
+    lastIndexChecksum = checksum
+    return records.length
+  }
+}
+
+/**
+ * Build searchable content from endpoint
+ */
+function buildSearchableContent(endpoint: ApiEndpoint): string {
+  const parts = [
+    endpoint.operationId,
+    endpoint.method,
+    endpoint.path,
+    endpoint.summary,
+    endpoint.description,
+    ...endpoint.tags,
+    ...endpoint.parameters.map((p) => `${p.name} ${p.description}`),
+  ]
+
+  return parts.filter(Boolean).join(' ')
+}
+
+/**
+ * Search endpoints using hybrid search (fulltext + vector).
+ * Falls back to in-memory search if search service is not available.
+ */
+export async function searchEndpoints(
+  searchService: SearchService | null,
+  query: string,
+  options: { limit?: number; method?: string } = {}
+): Promise<ApiEndpoint[]> {
+  const { limit = API_ENDPOINT_SEARCH_CONFIG.defaultLimit, method } = options
+
+  // Ensure endpoints are loaded
+  await getApiEndpoints()
+
+  // Try hybrid search first if search service is available
+  if (searchService) {
+    try {
+      // Use hybrid search (fulltext + vector)
+      const results = await searchService.search(query, {
+        tenantId: GLOBAL_TENANT_ID,
+        organizationId: null,
+        entityTypes: [API_ENDPOINT_ENTITY_ID],
+        limit: limit * 2, // Get extra to account for filtering
+      })
+
+      // Map search results back to ApiEndpoint objects
+      const endpoints: ApiEndpoint[] = []
+      for (const result of results) {
+        if (endpoints.length >= limit) break
+
+        const endpoint = endpointsByOperationId?.get(result.recordId)
+        if (endpoint) {
+          // Apply method filter if not handled by search
+          if (method && endpoint.method !== method.toUpperCase()) continue
+          endpoints.push(endpoint)
+        }
+      }
+
+      if (endpoints.length > 0) {
+        return endpoints
+      }
+
+      // Fall through to fallback if no results from hybrid search
+      console.error('[API Index] No hybrid search results, falling back to in-memory search')
+    } catch (error) {
+      console.error('[API Index] Hybrid search failed, falling back to in-memory:', error)
+    }
+  }
+
+  // Fallback: Simple in-memory text matching
+  return searchEndpointsFallback(query, { limit, method })
+}
+
+/**
+ * Fallback in-memory search when hybrid search is not available.
+ */
+function searchEndpointsFallback(
+  query: string,
+  options: { limit?: number; method?: string } = {}
+): ApiEndpoint[] {
+  const { limit = API_ENDPOINT_SEARCH_CONFIG.defaultLimit, method } = options
+
+  if (!endpointsCache) {
+    return []
+  }
+
+  const queryLower = query.toLowerCase()
+  const queryTerms = queryLower.split(/\s+/).filter(Boolean)
+
+  let matches = endpointsCache.filter((endpoint) => {
+    const content = buildSearchableContent(endpoint).toLowerCase()
+    return queryTerms.some((term) => content.includes(term))
+  })
+
+  // Filter by method if specified
+  if (method) {
+    matches = matches.filter((e) => e.method === method.toUpperCase())
+  }
+
+  // Sort by relevance (number of matching terms)
+  matches.sort((a, b) => {
+    const aContent = buildSearchableContent(a).toLowerCase()
+    const bContent = buildSearchableContent(b).toLowerCase()
+    const aScore = queryTerms.filter((t) => aContent.includes(t)).length
+    const bScore = queryTerms.filter((t) => bContent.includes(t)).length
+    return bScore - aScore
+  })
+
+  return matches.slice(0, limit)
+}
+
+/**
+ * Clear endpoint cache (for testing)
+ */
+export function clearEndpointCache(): void {
+  endpointsCache = null
+  endpointsByOperationId = null
+}

package/src/modules/ai_assistant/lib/auth.ts

@@ -0,0 +1,185 @@
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+
+/**
+ * Successful authentication result.
+ */
+export type McpAuthSuccess = {
+  success: true
+  keyId: string
+  keyName: string
+  tenantId: string | null
+  organizationId: string | null
+  userId: string
+  features: string[]
+  isSuperAdmin: boolean
+}
+
+/**
+ * Failed authentication result.
+ */
+export type McpAuthFailure = {
+  success: false
+  error: string
+}
+
+/**
+ * Result from MCP authentication.
+ */
+export type McpAuthResult = McpAuthSuccess | McpAuthFailure
+
+/**
+ * Authenticate an MCP request using an API key.
+ *
+ * This function validates the API key secret and loads the associated
+ * ACL (features, organizations, super admin status) from the key's roles.
+ *
+ * @param apiKeySecret - The full API key secret (e.g., 'omk_xxxx.yyyy...')
+ * @param container - Awilix DI container with 'em' and 'rbacService'
+ * @returns Authentication result with user context or error
+ */
+export async function authenticateMcpRequest(
+  apiKeySecret: string,
+  container: AwilixContainer
+): Promise<McpAuthResult> {
+  if (!apiKeySecret || typeof apiKeySecret !== 'string') {
+    return { success: false, error: 'API key is required' }
+  }
+
+  const trimmedSecret = apiKeySecret.trim()
+  if (!trimmedSecret) {
+    return { success: false, error: 'API key is required' }
+  }
+
+  if (!trimmedSecret.startsWith('omk_')) {
+    return { success: false, error: 'Invalid API key format' }
+  }
+
+  try {
+    const em = container.resolve('em') as EntityManager
+
+    const { findApiKeyBySecret } = await import(
+      '@open-mercato/core/modules/api_keys/services/apiKeyService'
+    )
+
+    const apiKey = await findApiKeyBySecret(em, trimmedSecret)
+
+    if (!apiKey) {
+      return { success: false, error: 'Invalid or expired API key' }
+    }
+
+    const userId = `api_key:${apiKey.id}`
+
+    const rbacService = container.resolve('rbacService') as {
+      loadAcl: (
+        userId: string,
+        scope: { tenantId: string | null; organizationId: string | null }
+      ) => Promise<{
+        isSuperAdmin: boolean
+        features: string[]
+        organizations: string[] | null
+      }>
+    }
+
+    const acl = await rbacService.loadAcl(userId, {
+      tenantId: apiKey.tenantId ?? null,
+      organizationId: apiKey.organizationId ?? null,
+    })
+
+    try {
+      apiKey.lastUsedAt = new Date()
+      await em.persistAndFlush(apiKey)
+    } catch {
+      // Best-effort update; ignore write failures
+    }
+
+    return {
+      success: true,
+      keyId: apiKey.id,
+      keyName: apiKey.name,
+      tenantId: apiKey.tenantId ?? null,
+      organizationId: apiKey.organizationId ?? null,
+      userId,
+      features: acl.features,
+      isSuperAdmin: acl.isSuperAdmin,
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    console.error('[MCP Auth] Authentication failed:', message)
+    return { success: false, error: 'Authentication failed' }
+  }
+}
+
+/**
+ * Check if user has the required features for a resource.
+ *
+ * Supports:
+ * - Super admin bypass (always returns true)
+ * - Direct feature match (e.g., 'customers.view')
+ * - Global wildcard ('*' grants all features)
+ * - Prefix wildcard (e.g., 'customers.*' grants 'customers.people.view')
+ *
+ * @param requiredFeatures - List of features required for access
+ * @param userFeatures - List of features the user has
+ * @param isSuperAdmin - Whether the user is a super admin
+ * @returns True if user has access
+ */
+export function hasRequiredFeatures(
+  requiredFeatures: string[] | undefined,
+  userFeatures: string[],
+  isSuperAdmin: boolean
+): boolean {
+  if (isSuperAdmin) return true
+  if (!requiredFeatures?.length) return true
+
+  return requiredFeatures.every((required) => {
+    if (userFeatures.includes(required)) return true
+    if (userFeatures.includes('*')) return true
+
+    // Check wildcard patterns (e.g., 'customers.*' grants 'customers.people.view')
+    return userFeatures.some((feature) => {
+      if (feature.endsWith('.*')) {
+        const prefix = feature.slice(0, -2)
+        return required.startsWith(prefix + '.')
+      }
+      return false
+    })
+  })
+}
+
+/**
+ * Extract API key from HTTP request headers.
+ *
+ * Supports two header formats:
+ * - x-api-key: <secret>
+ * - Authorization: ApiKey <secret>
+ *
+ * @param headers - Request headers (Map, Headers, or plain object)
+ * @returns The API key secret or null if not found
+ */
+export function extractApiKeyFromHeaders(
+  headers: Headers | Map<string, string> | Record<string, string | undefined>
+): string | null {
+  const getHeader = (name: string): string | null => {
+    if (headers instanceof Headers) {
+      return headers.get(name)
+    }
+    if (headers instanceof Map) {
+      return headers.get(name) ?? null
+    }
+    const value = headers[name] ?? headers[name.toLowerCase()]
+    return typeof value === 'string' ? value : null
+  }
+
+  const xApiKey = getHeader('x-api-key')?.trim()
+  if (xApiKey) {
+    return xApiKey
+  }
+
+  const authHeader = getHeader('authorization')?.trim()
+  if (authHeader && authHeader.toLowerCase().startsWith('apikey ')) {
+    return authHeader.slice(7).trim()
+  }
+
+  return null
+}

package/src/modules/ai_assistant/lib/chat-config.ts

@@ -0,0 +1,152 @@
+import type { ModuleConfigService } from '@open-mercato/core/modules/configs/lib/module-config-service'
+
+// Types
+export type ChatProviderId = 'openai' | 'anthropic' | 'google'
+
+export type ChatModelInfo = {
+  id: string
+  name: string
+  contextWindow: number
+}
+
+export type ChatProviderInfo = {
+  name: string
+  envKeyRequired: string
+  defaultModel: string
+  models: ChatModelInfo[]
+}
+
+export type ChatProviderConfig = {
+  providerId: ChatProviderId
+  model: string
+  updatedAt: string
+}
+
+// Constants
+export const CHAT_CONFIG_KEY = 'chat_provider'
+
+export const CHAT_PROVIDERS: Record<ChatProviderId, ChatProviderInfo> = {
+  openai: {
+    name: 'OpenAI',
+    envKeyRequired: 'OPENAI_API_KEY',
+    defaultModel: 'gpt-4o',
+    models: [
+      { id: 'gpt-4o', name: 'GPT-4o', contextWindow: 128000 },
+      { id: 'gpt-4o-mini', name: 'GPT-4o Mini', contextWindow: 128000 },
+      { id: 'gpt-4-turbo', name: 'GPT-4 Turbo', contextWindow: 128000 },
+      { id: 'gpt-3.5-turbo', name: 'GPT-3.5 Turbo', contextWindow: 16385 },
+    ],
+  },
+  anthropic: {
+    name: 'Anthropic',
+    envKeyRequired: 'ANTHROPIC_API_KEY',
+    defaultModel: 'claude-sonnet-4-5-20250929',
+    models: [
+      { id: 'claude-sonnet-4-5-20250929', name: 'Claude Sonnet 4.5', contextWindow: 200000 },
+      { id: 'claude-sonnet-4-20250514', name: 'Claude Sonnet 4', contextWindow: 200000 },
+      { id: 'claude-3-5-sonnet-20241022', name: 'Claude 3.5 Sonnet', contextWindow: 200000 },
+      { id: 'claude-3-5-haiku-20241022', name: 'Claude 3.5 Haiku', contextWindow: 200000 },
+    ],
+  },
+  google: {
+    name: 'Google',
+    envKeyRequired: 'GOOGLE_GENERATIVE_AI_API_KEY',
+    defaultModel: 'gemini-1.5-pro',
+    models: [
+      { id: 'gemini-1.5-pro', name: 'Gemini 1.5 Pro', contextWindow: 2097152 },
+      { id: 'gemini-1.5-flash', name: 'Gemini 1.5 Flash', contextWindow: 1048576 },
+      { id: 'gemini-pro', name: 'Gemini Pro', contextWindow: 32000 },
+    ],
+  },
+}
+
+export const DEFAULT_CHAT_CONFIG: Omit<ChatProviderConfig, 'updatedAt'> = {
+  providerId: 'openai',
+  model: 'gpt-4o',
+}
+
+// Provider configuration checks
+export function isProviderConfigured(providerId: ChatProviderId): boolean {
+  switch (providerId) {
+    case 'openai':
+      return Boolean(process.env.OPENAI_API_KEY?.trim())
+    case 'anthropic':
+      return Boolean(process.env.ANTHROPIC_API_KEY?.trim())
+    case 'google':
+      return Boolean(process.env.GOOGLE_GENERATIVE_AI_API_KEY?.trim())
+    default:
+      return false
+  }
+}
+
+export function getConfiguredProviders(): ChatProviderId[] {
+  const providers: ChatProviderId[] = []
+  const allProviders: ChatProviderId[] = ['openai', 'anthropic', 'google']
+  for (const providerId of allProviders) {
+    if (isProviderConfigured(providerId)) {
+      providers.push(providerId)
+    }
+  }
+  return providers
+}
+
+// Config resolution
+type Resolver = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+export async function resolveChatConfig(
+  resolver: Resolver,
+  options?: { defaultValue?: ChatProviderConfig | null }
+): Promise<ChatProviderConfig | null> {
+  const fallback = options?.defaultValue ?? null
+  let service: ModuleConfigService
+  try {
+    service = resolver.resolve<ModuleConfigService>('moduleConfigService')
+  } catch {
+    return fallback
+  }
+  try {
+    const value = await service.getValue<ChatProviderConfig>('ai_assistant', CHAT_CONFIG_KEY, { defaultValue: fallback })
+    return value
+  } catch {
+    return fallback
+  }
+}
+
+export async function saveChatConfig(
+  resolver: Resolver,
+  config: Omit<ChatProviderConfig, 'updatedAt'>
+): Promise<ChatProviderConfig> {
+  let service: ModuleConfigService
+  try {
+    service = resolver.resolve<ModuleConfigService>('moduleConfigService')
+  } catch {
+    throw new Error('Configuration service unavailable')
+  }
+  const fullConfig: ChatProviderConfig = {
+    ...config,
+    updatedAt: new Date().toISOString(),
+  }
+  await service.setValue('ai_assistant', CHAT_CONFIG_KEY, fullConfig)
+  return fullConfig
+}
+
+export function createDefaultConfig(): ChatProviderConfig {
+  return { ...DEFAULT_CHAT_CONFIG, updatedAt: new Date().toISOString() }
+}
+
+// Get model info by ID
+export function getModelInfo(providerId: ChatProviderId, modelId: string): ChatModelInfo | null {
+  const provider = CHAT_PROVIDERS[providerId]
+  if (!provider) return null
+  return provider.models.find((m) => m.id === modelId) ?? null
+}
+
+// Format context window for display
+export function formatContextWindow(contextWindow: number): string {
+  if (contextWindow >= 1000000) {
+    return `${(contextWindow / 1000000).toFixed(1)}M`
+  }
+  return `${(contextWindow / 1000).toFixed(0)}K`
+}