@brainfish-ai/devdoc 0.1.21

package/renderer/lib/api-docs/agent/indexer.ts

@@ -0,0 +1,323 @@
+/**
+ * Collection Indexer
+ * Builds a searchable index of all API endpoints for the AI agent
+ */
+
+import type { BrainfishCollection, BrainfishRESTRequest, FormDataKeyValue } from '../types'
+import type { EndpointIndex } from './types'
+
+/**
+ * Find a request by ID in the collection (recursive)
+ */
+export function findRequestById(
+  collection: BrainfishCollection, 
+  id: string
+): BrainfishRESTRequest | null {
+  // Check direct requests
+  const found = collection.requests.find(r => r.id === id)
+  if (found) return found
+  
+  // Check folders recursively
+  for (const folder of collection.folders) {
+    const request = findRequestById(folder, id)
+    if (request) return request
+  }
+  return null
+}
+
+/**
+ * Format full request details for AI context
+ * Returns a structured object with all the information the AI needs
+ */
+export function formatRequestForAI(request: BrainfishRESTRequest): {
+  id: string
+  name: string
+  method: string
+  path: string
+  description: string | null
+  parameters: Array<{ name: string; description: string; required: boolean }>
+  headers: Array<{ name: string; description: string; required: boolean }>
+  auth: { type: string; details?: Record<string, unknown> }
+  body: {
+    required: boolean
+    contentType: string | null
+    schema: string | Array<{ key: string; isFile: boolean }> | null
+    example?: string
+  }
+  responses: Array<{
+    code: number
+    status: string
+    description?: string
+    example?: string
+  }>
+} {
+  // Format parameters
+  const parameters = request.params.map(p => ({
+    name: p.key,
+    description: p.description || '',
+    required: p.active,
+  }))
+
+  // Format headers
+  const headers = request.headers
+    .filter(h => !['Content-Type', 'Authorization'].includes(h.key)) // Filter out auto-managed headers
+    .map(h => ({
+      name: h.key,
+      description: h.description || '',
+      required: h.active,
+    }))
+
+  // Format auth
+  const auth: { type: string; details?: Record<string, unknown> } = {
+    type: request.auth.authType,
+  }
+  if (request.auth.authType === 'api-key') {
+    auth.details = {
+      keyName: request.auth.key,
+      location: request.auth.addTo === 'HEADERS' ? 'header' : 'query',
+    }
+  } else if (request.auth.authType === 'bearer') {
+    auth.details = { headerFormat: 'Bearer <token>' }
+  } else if (request.auth.authType === 'basic') {
+    auth.details = { format: 'Basic base64(username:password)' }
+  }
+
+  // Format body
+  const body: {
+    required: boolean
+    contentType: string | null
+    schema: string | Array<{ key: string; isFile: boolean }> | null
+    example?: string
+  } = {
+    required: request.body.body !== null,
+    contentType: request.body.contentType,
+    schema: null,
+  }
+
+  if (request.body.body !== null) {
+    if (Array.isArray(request.body.body)) {
+      // Form data
+      body.schema = (request.body.body as FormDataKeyValue[]).map(item => ({
+        key: item.key,
+        isFile: item.isFile,
+      }))
+    } else if (typeof request.body.body === 'string') {
+      // JSON or raw body - try to parse and extract schema info
+      try {
+        const parsed = JSON.parse(request.body.body)
+        body.example = request.body.body
+        // Extract field names and types from example
+        body.schema = JSON.stringify(
+          extractSchemaFromExample(parsed),
+          null,
+          2
+        )
+      } catch {
+        // Raw string body
+        body.example = request.body.body.slice(0, 500)
+        body.schema = 'raw text'
+      }
+    }
+  }
+
+  // Format responses
+  const responses = Object.entries(request.responses).map(([name, resp]) => ({
+    code: resp.code,
+    status: resp.status,
+    description: name !== resp.status ? name : undefined,
+    example: resp.body ? resp.body.slice(0, 500) : undefined,
+  }))
+
+  return {
+    id: request.id,
+    name: request.name,
+    method: request.method,
+    path: request.endpoint,
+    description: request.description,
+    parameters,
+    headers,
+    auth,
+    body,
+    responses,
+  }
+}
+
+/**
+ * Extract a simple schema from a JSON example
+ */
+function extractSchemaFromExample(obj: unknown, depth = 0): unknown {
+  if (depth > 3) return '...' // Prevent deep recursion
+  
+  if (obj === null) return 'null'
+  if (typeof obj === 'string') return 'string'
+  if (typeof obj === 'number') return 'number'
+  if (typeof obj === 'boolean') return 'boolean'
+  
+  if (Array.isArray(obj)) {
+    if (obj.length === 0) return '[]'
+    return [extractSchemaFromExample(obj[0], depth + 1)]
+  }
+  
+  if (typeof obj === 'object') {
+    const result: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = extractSchemaFromExample(value, depth + 1)
+    }
+    return result
+  }
+  
+  return 'unknown'
+}
+
+/**
+ * Recursively extracts all requests from a collection and its nested folders
+ */
+function extractRequests(
+  collection: BrainfishCollection,
+  parentTags: string[] = []
+): { request: BrainfishRESTRequest; tags: string[] }[] {
+  const results: { request: BrainfishRESTRequest; tags: string[] }[] = []
+  
+  // Add requests from this level
+  for (const request of collection.requests) {
+    results.push({
+      request,
+      tags: [...parentTags, collection.name].filter(t => t !== 'root'),
+    })
+  }
+  
+  // Recursively process folders
+  for (const folder of collection.folders) {
+    const folderResults = extractRequests(folder, [...parentTags, collection.name])
+    results.push(...folderResults)
+  }
+  
+  return results
+}
+
+/**
+ * Builds an endpoint index for AI context
+ */
+export function buildEndpointIndex(collection: BrainfishCollection): EndpointIndex[] {
+  const allRequests = extractRequests(collection)
+  
+  return allRequests.map(({ request, tags }) => ({
+    id: request.id,
+    name: request.name,
+    method: request.method,
+    path: request.endpoint,
+    description: request.description,
+    parameters: request.params.map(p => p.key),
+    hasBody: request.body.body !== null,
+    tags: [...new Set([...tags, ...request.tags])].filter(Boolean),
+  }))
+}
+
+/**
+ * Formats the endpoint index as a string for the AI system prompt
+ */
+export function formatEndpointsForContext(endpoints: EndpointIndex[]): string {
+  return endpoints
+    .map((ep, i) => {
+      const params = ep.parameters.length > 0 
+        ? `\n   Parameters: ${ep.parameters.join(', ')}` 
+        : ''
+      const tags = ep.tags.length > 0 
+        ? `\n   Tags: ${ep.tags.join(', ')}` 
+        : ''
+      
+      return `${i + 1}. [${ep.method}] ${ep.path}
+   ID: ${ep.id}
+   Name: ${ep.name}${ep.description ? `\n   Description: ${ep.description.slice(0, 200)}${ep.description.length > 200 ? '...' : ''}` : ''}${params}${tags}`
+    })
+    .join('\n\n')
+}
+
+/**
+ * Fuzzy/BM25-like search over endpoints
+ */
+export function searchEndpoints(
+  endpoints: EndpointIndex[],
+  query: string,
+  method?: string
+): EndpointIndex[] {
+  // Tokenize query
+  const queryTokens = query.toLowerCase().split(/\s+/).filter(t => t.length > 1)
+  const queryLower = query.toLowerCase()
+  
+  // Score each endpoint
+  const scoredEndpoints = endpoints
+    .filter(ep => !method || ep.method === method)
+    .map(ep => {
+      let score = 0
+      const nameLower = ep.name.toLowerCase()
+      const pathLower = ep.path.toLowerCase()
+      const descLower = (ep.description || '').toLowerCase()
+      const tagsLower = ep.tags.map(t => t.toLowerCase())
+      const paramsLower = ep.parameters.map(p => p.toLowerCase())
+      
+      // Exact phrase match (highest priority)
+      if (nameLower.includes(queryLower)) score += 100
+      if (pathLower.includes(queryLower)) score += 80
+      if (descLower.includes(queryLower)) score += 60
+      
+      // Token matching
+      for (const token of queryTokens) {
+        // Name matches (most important)
+        if (nameLower === token) score += 50
+        else if (nameLower.startsWith(token)) score += 30
+        else if (nameLower.includes(token)) score += 20
+        
+        // Path segment matches
+        const pathParts = pathLower.split('/').filter(Boolean)
+        if (pathParts.some(part => part === token)) score += 40
+        if (pathParts.some(part => part.startsWith(token))) score += 25
+        if (pathParts.some(part => part.includes(token))) score += 15
+        
+        // Description matches
+        if (descLower.includes(token)) score += 15
+        
+        // Tag matches
+        if (tagsLower.some(tag => tag === token)) score += 30
+        if (tagsLower.some(tag => tag.includes(token))) score += 15
+        
+        // Parameter matches
+        if (paramsLower.some(param => param === token)) score += 25
+        if (paramsLower.some(param => param.includes(token))) score += 10
+        
+        // HTTP method relevance
+        if (ep.method.toLowerCase() === token) score += 20
+        
+        // Fuzzy matching for similar words
+        const allWords = [nameLower, ...pathParts, ...tagsLower, ...paramsLower]
+        for (const word of allWords) {
+          if (word.length > 2 && token.length > 2) {
+            const minLen = Math.min(word.length, token.length)
+            let matches = 0
+            for (let i = 0; i < minLen; i++) {
+              if (word[i] === token[i]) matches++
+            }
+            if (matches / minLen > 0.7) score += 5
+          }
+        }
+      }
+      
+      return { ...ep, score }
+    })
+  
+  // Filter and sort by score
+  return scoredEndpoints
+    .filter(ep => ep.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 10)
+    .map(ep => ({
+      id: ep.id,
+      name: ep.name,
+      method: ep.method,
+      path: ep.path,
+      description: ep.description,
+      parameters: ep.parameters,
+      hasBody: ep.hasBody,
+      tags: ep.tags,
+    }))
+}

package/renderer/lib/api-docs/agent/spec-summary.ts

@@ -0,0 +1,335 @@
+import type { BrainfishCollection, BrainfishRESTRequest, HTTPMethod } from '../types'
+
+interface EndpointSummary {
+  name: string
+  method: HTTPMethod
+  path: string
+  description: string | null
+  tags: string[]
+  hasAuth: boolean
+  hasBody: boolean
+  paramCount: number
+}
+
+interface ResourceGroup {
+  name: string
+  endpoints: EndpointSummary[]
+  operations: {
+    create: number
+    read: number
+    update: number
+    delete: number
+  }
+}
+
+interface AuthSummary {
+  types: string[]
+  primaryMethod: string | null
+}
+
+interface APISummary {
+  name: string
+  description: string | null
+  baseUrl: string | null
+  totalEndpoints: number
+  authSummary: AuthSummary
+  resourceGroups: ResourceGroup[]
+  commonPatterns: string[]
+  suggestedUseCases: string[]
+}
+
+/**
+ * Recursively collect all requests from a collection
+ */
+function collectAllRequests(collection: BrainfishCollection): BrainfishRESTRequest[] {
+  const requests: BrainfishRESTRequest[] = [...collection.requests]
+  
+  for (const folder of collection.folders) {
+    requests.push(...collectAllRequests(folder))
+  }
+  
+  return requests
+}
+
+/**
+ * Extract base URL from endpoints
+ */
+function extractBaseUrl(requests: BrainfishRESTRequest[]): string | null {
+  if (requests.length === 0) return null
+  
+  const firstEndpoint = requests[0].endpoint
+  try {
+    const url = new URL(firstEndpoint)
+    return `${url.protocol}//${url.host}`
+  } catch {
+    // Try to extract from path pattern
+    const match = firstEndpoint.match(/^(https?:\/\/[^\/]+)/)
+    return match ? match[1] : null
+  }
+}
+
+/**
+ * Analyze authentication patterns across endpoints
+ */
+function analyzeAuth(requests: BrainfishRESTRequest[]): AuthSummary {
+  const authTypes = new Set<string>()
+  const authCounts: Record<string, number> = {}
+  
+  for (const req of requests) {
+    const type = req.auth.authType
+    if (type !== 'none' && type !== 'inherit') {
+      authTypes.add(type)
+      authCounts[type] = (authCounts[type] || 0) + 1
+    }
+  }
+  
+  // Find primary auth method (most common)
+  let primaryMethod: string | null = null
+  let maxCount = 0
+  for (const [type, count] of Object.entries(authCounts)) {
+    if (count > maxCount) {
+      maxCount = count
+      primaryMethod = type
+    }
+  }
+  
+  return {
+    types: Array.from(authTypes),
+    primaryMethod,
+  }
+}
+
+/**
+ * Group endpoints by resource/tag
+ */
+function groupByResource(requests: BrainfishRESTRequest[]): ResourceGroup[] {
+  const groups: Map<string, EndpointSummary[]> = new Map()
+  
+  for (const req of requests) {
+    // Use first tag, or extract from path, or use "Other"
+    let groupName = req.tags[0] || extractResourceFromPath(req.endpoint) || 'Other'
+    groupName = groupName.charAt(0).toUpperCase() + groupName.slice(1)
+    
+    const summary: EndpointSummary = {
+      name: req.name,
+      method: req.method,
+      path: req.endpoint,
+      description: req.description,
+      tags: req.tags,
+      hasAuth: req.auth.authType !== 'none',
+      hasBody: req.body.body !== null,
+      paramCount: req.params.filter(p => p.active).length,
+    }
+    
+    if (!groups.has(groupName)) {
+      groups.set(groupName, [])
+    }
+    groups.get(groupName)!.push(summary)
+  }
+  
+  // Convert to array and calculate operations
+  return Array.from(groups.entries()).map(([name, endpoints]) => ({
+    name,
+    endpoints,
+    operations: {
+      create: endpoints.filter(e => e.method === 'POST').length,
+      read: endpoints.filter(e => e.method === 'GET').length,
+      update: endpoints.filter(e => e.method === 'PUT' || e.method === 'PATCH').length,
+      delete: endpoints.filter(e => e.method === 'DELETE').length,
+    },
+  }))
+}
+
+/**
+ * Extract resource name from path
+ */
+function extractResourceFromPath(path: string): string | null {
+  // Remove base URL and extract first path segment
+  const pathMatch = path.match(/\/api\/v?\d*\/?([^\/]+)/) || path.match(/\/([^\/]+)/)
+  if (pathMatch) {
+    return pathMatch[1].replace(/[-_]/g, ' ')
+  }
+  return null
+}
+
+/**
+ * Detect common API patterns
+ */
+function detectPatterns(groups: ResourceGroup[]): string[] {
+  const patterns: string[] = []
+  
+  // Check for RESTful CRUD patterns
+  const hasCRUD = groups.some(g => 
+    g.operations.create > 0 && 
+    g.operations.read > 0 && 
+    (g.operations.update > 0 || g.operations.delete > 0)
+  )
+  if (hasCRUD) {
+    patterns.push('RESTful CRUD operations')
+  }
+  
+  // Check for authentication endpoints
+  const hasAuthEndpoints = groups.some(g => 
+    g.name.toLowerCase().includes('auth') ||
+    g.endpoints.some(e => 
+      e.name.toLowerCase().includes('login') ||
+      e.name.toLowerCase().includes('token') ||
+      e.name.toLowerCase().includes('session')
+    )
+  )
+  if (hasAuthEndpoints) {
+    patterns.push('Authentication/Authorization flows')
+  }
+  
+  // Check for search/filter patterns
+  const hasSearch = groups.some(g =>
+    g.endpoints.some(e => 
+      e.name.toLowerCase().includes('search') ||
+      e.name.toLowerCase().includes('filter') ||
+      e.paramCount > 2
+    )
+  )
+  if (hasSearch) {
+    patterns.push('Search and filtering capabilities')
+  }
+  
+  // Check for batch operations
+  const hasBatch = groups.some(g =>
+    g.endpoints.some(e => 
+      e.name.toLowerCase().includes('batch') ||
+      e.name.toLowerCase().includes('bulk')
+    )
+  )
+  if (hasBatch) {
+    patterns.push('Batch/bulk operations')
+  }
+  
+  // Check for webhooks
+  const hasWebhooks = groups.some(g =>
+    g.name.toLowerCase().includes('webhook') ||
+    g.endpoints.some(e => e.name.toLowerCase().includes('webhook'))
+  )
+  if (hasWebhooks) {
+    patterns.push('Webhook integrations')
+  }
+  
+  return patterns
+}
+
+/**
+ * Generate suggested use cases based on resources
+ */
+function generateUseCases(groups: ResourceGroup[], _apiName: string): string[] {
+  const useCases: string[] = []
+  
+  for (const group of groups.slice(0, 5)) { // Top 5 groups
+    if (group.operations.create > 0) {
+      useCases.push(`Create and manage ${group.name.toLowerCase()}`)
+    }
+    if (group.operations.read > 0 && group.endpoints.length > 1) {
+      useCases.push(`List and retrieve ${group.name.toLowerCase()} data`)
+    }
+  }
+  
+  // Add generic use cases based on patterns
+  const hasAuth = groups.some(g => g.name.toLowerCase().includes('auth'))
+  if (hasAuth) {
+    useCases.push('Implement user authentication flow')
+  }
+  
+  return useCases.slice(0, 6) // Limit to 6 use cases
+}
+
+/**
+ * Generate a comprehensive API summary from a collection
+ */
+export function generateAPISummary(collection: BrainfishCollection): APISummary {
+  const requests = collectAllRequests(collection)
+  const groups = groupByResource(requests)
+  const patterns = detectPatterns(groups)
+  
+  return {
+    name: collection.name,
+    description: collection.description,
+    baseUrl: extractBaseUrl(requests),
+    totalEndpoints: requests.length,
+    authSummary: analyzeAuth(requests),
+    resourceGroups: groups,
+    commonPatterns: patterns,
+    suggestedUseCases: generateUseCases(groups, collection.name),
+  }
+}
+
+/**
+ * Format API summary as a string for the LLM system prompt
+ */
+export function formatAPISummaryForPrompt(summary: APISummary): string {
+  const sections: string[] = []
+  
+  // Header
+  sections.push(`# API Overview: ${summary.name}`)
+  if (summary.description) {
+    sections.push(summary.description)
+  }
+  
+  // Stats
+  sections.push(`\n## Quick Stats`)
+  sections.push(`- Total Endpoints: ${summary.totalEndpoints}`)
+  if (summary.baseUrl) {
+    sections.push(`- Base URL: ${summary.baseUrl}`)
+  }
+  
+  // Auth
+  if (summary.authSummary.types.length > 0) {
+    sections.push(`- Authentication: ${summary.authSummary.types.join(', ')}`)
+    if (summary.authSummary.primaryMethod) {
+      sections.push(`- Primary Auth Method: ${summary.authSummary.primaryMethod}`)
+    }
+  }
+  
+  // Resources
+  sections.push(`\n## API Resources (${summary.resourceGroups.length} groups)`)
+  for (const group of summary.resourceGroups) {
+    const ops = []
+    if (group.operations.create) ops.push(`${group.operations.create} create`)
+    if (group.operations.read) ops.push(`${group.operations.read} read`)
+    if (group.operations.update) ops.push(`${group.operations.update} update`)
+    if (group.operations.delete) ops.push(`${group.operations.delete} delete`)
+    
+    sections.push(`\n### ${group.name} (${group.endpoints.length} endpoints)`)
+    if (ops.length > 0) {
+      sections.push(`Operations: ${ops.join(', ')}`)
+    }
+    
+    // List key endpoints (up to 5 per group)
+    const keyEndpoints = group.endpoints.slice(0, 5)
+    for (const ep of keyEndpoints) {
+      const authIndicator = ep.hasAuth ? '🔐' : ''
+      sections.push(`- [${ep.method}] ${ep.name} ${authIndicator}`)
+      if (ep.description) {
+        sections.push(`  ${ep.description.slice(0, 100)}${ep.description.length > 100 ? '...' : ''}`)
+      }
+    }
+    if (group.endpoints.length > 5) {
+      sections.push(`  ... and ${group.endpoints.length - 5} more`)
+    }
+  }
+  
+  // Patterns
+  if (summary.commonPatterns.length > 0) {
+    sections.push(`\n## Common Patterns`)
+    for (const pattern of summary.commonPatterns) {
+      sections.push(`- ${pattern}`)
+    }
+  }
+  
+  // Use cases
+  if (summary.suggestedUseCases.length > 0) {
+    sections.push(`\n## Suggested Use Cases`)
+    for (const useCase of summary.suggestedUseCases) {
+      sections.push(`- ${useCase}`)
+    }
+  }
+  
+  return sections.join('\n')
+}