@brainfish-ai/devdoc 0.1.42 → 0.1.44

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

@@ -0,0 +1,254 @@
+/**
+ * Collection Indexer
+ * Builds a searchable index of all API endpoints for the AI agent
+ */ /**
+ * Find a request by ID in the collection (recursive)
+ */ export function findRequestById(collection, id) {
+    // 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) {
+    // 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: 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: 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.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, depth = 0) {
+    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 = {};
+        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, parentTags = []) {
+    const results = [];
+    // 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) {
+    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) {
+    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, query, method) {
+    // 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.js

@@ -0,0 +1,227 @@
+/**
+ * Recursively collect all requests from a collection
+ */ function collectAllRequests(collection) {
+    const requests = [
+        ...collection.requests
+    ];
+    for (const folder of collection.folders){
+        requests.push(...collectAllRequests(folder));
+    }
+    return requests;
+}
+/**
+ * Extract base URL from endpoints
+ */ function extractBaseUrl(requests) {
+    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) {
+    const authTypes = new Set();
+    const authCounts = {};
+    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 = 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) {
+    const groups = 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 = {
+            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) {
+    // 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) {
+    const patterns = [];
+    // 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, _apiName) {
+    const useCases = [];
+    for (const group of groups.slice(0, 5)){
+        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) {
+    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) {
+    const sections = [];
+    // 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');
+}

package/renderer/lib/api-docs/agent/types.js

@@ -0,0 +1,5 @@
+/**
+ * Agent Mode Types
+ * Types for the AI-powered API documentation assistant
+ */ // Navigation action
+export { };

package/renderer/lib/api-docs/agent/use-suggestions.js

@@ -0,0 +1,97 @@
+'use client';
+import { useState, useEffect, useMemo } from 'react';
+/**
+ * Shared hook for fetching contextual suggestions
+ * Used by both AgentChat and AgentPopupButton
+ * 
+ * Server-side caching with KV (1 week TTL) - no client-side cache needed
+ */ export function useSuggestions({ currentEndpoint, endpointIndex = [], limit }) {
+    const [suggestions, setSuggestions] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    // Stable key for request deduplication
+    const requestKey = useMemo(()=>currentEndpoint?.id || `general:${endpointIndex.length}`, [
+        currentEndpoint?.id,
+        endpointIndex.length
+    ]);
+    // Fallback suggestions
+    const fallbackSuggestions = useMemo(()=>{
+        if (currentEndpoint) {
+            return [
+                {
+                    title: 'What does this',
+                    label: 'endpoint do?',
+                    prompt: `What does ${currentEndpoint.name} do?`
+                },
+                {
+                    title: 'What parameters',
+                    label: 'are required?',
+                    prompt: 'What parameters are required?'
+                },
+                {
+                    title: 'Python example',
+                    label: 'Show code',
+                    prompt: 'Show me a Python example'
+                }
+            ];
+        }
+        return [
+            {
+                title: 'Find an endpoint',
+                label: 'to create resources',
+                prompt: 'Find endpoints for creating resources'
+            },
+            {
+                title: 'How do I',
+                label: 'authenticate?',
+                prompt: 'How do I authenticate?'
+            },
+            {
+                title: 'Overview',
+                label: 'What can I do?',
+                prompt: 'What can I do with this API?'
+            }
+        ];
+    }, [
+        currentEndpoint
+    ]);
+    // Fetch suggestions from API (server handles KV caching)
+    useEffect(()=>{
+        let cancelled = false;
+        setIsLoading(true);
+        fetch('/api/suggestions', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                endpointIndex,
+                currentEndpointId: currentEndpoint?.id
+            })
+        }).then((res)=>res.json()).then((data)=>{
+            if (cancelled) return;
+            if (data.suggestions) {
+                const allSuggestions = data.suggestions;
+                setSuggestions(limit ? allSuggestions.slice(0, limit) : allSuggestions);
+            }
+        }).catch((err)=>{
+            if (cancelled) return;
+            console.warn('[useSuggestions] Failed to fetch suggestions:', err);
+            setSuggestions(limit ? fallbackSuggestions.slice(0, limit) : fallbackSuggestions);
+        }).finally(()=>{
+            if (!cancelled) setIsLoading(false);
+        });
+        return ()=>{
+            cancelled = true;
+        };
+    }, [
+        requestKey,
+        currentEndpoint,
+        endpointIndex,
+        limit,
+        fallbackSuggestions
+    ]);
+    return {
+        suggestions,
+        isLoading
+    };
+}