@brainfish-ai/devdoc 0.1.42 → 0.1.43

package/renderer/lib/api-docs/playground/request-runner.js

@@ -0,0 +1,224 @@
+/**
+ * Request Runner
+ * 
+ * Executes HTTP requests via backend proxy to bypass CORS
+ * and ensure auth headers are sent properly.
+ * Supports streaming responses for SSE endpoints.
+ */ import { buildRequest } from './request-builder';
+/**
+ * Executes a REST request via the backend proxy
+ */ export async function executeRequest(request, options = {}) {
+    try {
+        // Build the request
+        const builtRequest = buildRequest(request, options);
+        // Send request through our backend proxy
+        const proxyResponse = await fetch('/api/proxy', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                url: builtRequest.url,
+                method: builtRequest.method,
+                headers: builtRequest.headers,
+                requestBody: builtRequest.body instanceof FormData ? undefined // FormData not supported through JSON proxy
+                 : builtRequest.body
+            }),
+            signal: options.signal
+        });
+        if (!proxyResponse.ok) {
+            const errorData = await proxyResponse.json().catch(()=>({}));
+            return {
+                status: proxyResponse.status,
+                statusText: proxyResponse.statusText,
+                headers: {},
+                body: JSON.stringify(errorData),
+                responseTime: 0,
+                size: 0,
+                error: errorData.error || 'Proxy request failed'
+            };
+        }
+        const result = await proxyResponse.json();
+        return {
+            status: result.status,
+            statusText: result.statusText,
+            headers: result.headers || {},
+            body: result.body,
+            responseTime: result.responseTime || 0,
+            size: result.size || 0,
+            error: result.error
+        };
+    } catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error('Request cancelled');
+        }
+        return {
+            status: 0,
+            statusText: 'Error',
+            headers: {},
+            body: null,
+            responseTime: 0,
+            size: 0,
+            error: error instanceof Error ? error.message : 'Unknown error'
+        };
+    }
+}
+/**
+ * Executes a streaming request (for SSE endpoints)
+ * Falls back to regular request if the endpoint isn't actually SSE
+ */ export async function executeStreamingRequest(request, options = {}) {
+    const startTime = Date.now();
+    try {
+        const builtRequest = buildRequest(request, options);
+        // Use streaming proxy
+        const response = await fetch('/api/proxy-stream', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                url: builtRequest.url,
+                method: builtRequest.method,
+                headers: builtRequest.headers,
+                requestBody: builtRequest.body instanceof FormData ? undefined : builtRequest.body
+            }),
+            signal: options.signal
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(()=>({}));
+            return {
+                status: response.status,
+                statusText: response.statusText,
+                headers: {},
+                body: JSON.stringify(errorData),
+                responseTime: Date.now() - startTime,
+                size: 0,
+                error: errorData.error || 'Proxy request failed'
+            };
+        }
+        const contentType = response.headers.get('content-type') || '';
+        // Check if streaming response (our proxy wraps SSE responses as SSE)
+        const isProxyStreaming = contentType.includes('text/event-stream');
+        if (isProxyStreaming && response.body) {
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let accumulated = '';
+            let metadata = null;
+            let totalSize = 0;
+            let buffer = '';
+            try {
+                while(true){
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    buffer += decoder.decode(value, {
+                        stream: true
+                    });
+                    // Process complete SSE events (ending with \n\n)
+                    const events = buffer.split('\n\n');
+                    buffer = events.pop() || ''; // Keep incomplete event in buffer
+                    for (const eventStr of events){
+                        const lines = eventStr.split('\n');
+                        for (const line of lines){
+                            if (line.startsWith('data: ')) {
+                                try {
+                                    const event = JSON.parse(line.slice(6));
+                                    if (event.type === 'metadata') {
+                                        metadata = {
+                                            status: event.status,
+                                            statusText: event.statusText,
+                                            headers: event.headers
+                                        };
+                                        options.onStreamStart?.(metadata);
+                                    } else if (event.type === 'chunk') {
+                                        // Accumulate raw SSE data - formatting happens in response viewer
+                                        accumulated += event.data;
+                                        totalSize += event.size || 0;
+                                        options.onChunk?.(event.data, accumulated);
+                                    } else if (event.type === 'done') {
+                                        totalSize = event.totalSize || totalSize;
+                                    } else if (event.type === 'error') {
+                                        return {
+                                            status: metadata?.status || 0,
+                                            statusText: metadata?.statusText || 'Error',
+                                            headers: metadata?.headers || {},
+                                            body: accumulated,
+                                            responseTime: Date.now() - startTime,
+                                            size: totalSize,
+                                            error: event.error,
+                                            isStreaming: true
+                                        };
+                                    }
+                                } catch  {
+                                // Ignore parse errors for partial data
+                                }
+                            }
+                        }
+                    }
+                }
+            } catch (readError) {
+                // Handle read errors gracefully
+                if (readError instanceof Error && readError.name === 'AbortError') {
+                    throw readError;
+                }
+            }
+            return {
+                status: metadata?.status || 200,
+                statusText: metadata?.statusText || 'OK',
+                headers: metadata?.headers || {},
+                body: accumulated,
+                responseTime: Date.now() - startTime,
+                size: totalSize,
+                isStreaming: true
+            };
+        }
+        // Non-streaming response from streaming proxy (endpoint wasn't SSE)
+        const result = await response.json();
+        return {
+            status: result.status,
+            statusText: result.statusText,
+            headers: result.headers || {},
+            body: result.body,
+            responseTime: Date.now() - startTime,
+            size: result.size || 0,
+            error: result.error,
+            isStreaming: false
+        };
+    } catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error('Request cancelled');
+        }
+        return {
+            status: 0,
+            statusText: 'Error',
+            headers: {},
+            body: null,
+            responseTime: Date.now() - startTime,
+            size: 0,
+            error: error instanceof Error ? error.message : 'Unknown error'
+        };
+    }
+}
+/**
+ * Creates a cancelable request execution
+ */ export function createCancelableRequest(request, options = {}) {
+    const abortController = new AbortController();
+    return {
+        execute: ()=>executeRequest(request, {
+                ...options,
+                signal: abortController.signal
+            }),
+        cancel: ()=>abortController.abort()
+    };
+}
+/**
+ * Creates a cancelable streaming request execution
+ */ export function createCancelableStreamingRequest(request, options = {}) {
+    const abortController = new AbortController();
+    return {
+        execute: ()=>executeStreamingRequest(request, {
+                ...options,
+                signal: abortController.signal
+            }),
+        cancel: ()=>abortController.abort()
+    };
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Playground Types
+ * 
+ * Types for the API playground (Try It Out functionality)
+ */ export { };

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

@@ -0,0 +1,23 @@
+/**
+ * Brainfish API Documentation Types
+ * 
+ * These types are inspired by Hoppscotch's data structures but adapted for Brainfish.
+ * Ported from Hoppscotch's HoppCollection and HoppRESTRequest types.
+ */ // ============================================================================
+// Core Request Types
+// ============================================================================
+// ============================================================================
+// Helper Type Guards
+// ============================================================================
+export function isBrainfishRESTAuthBasic(auth) {
+    return auth.authType === 'basic';
+}
+export function isBrainfishRESTAuthBearer(auth) {
+    return auth.authType === 'bearer';
+}
+export function isBrainfishRESTAuthAPIKey(auth) {
+    return auth.authType === 'api-key';
+}
+export function isBrainfishRESTAuthOAuth2(auth) {
+    return auth.authType === 'oauth-2';
+}

package/renderer/lib/api-docs/utils.js

@@ -0,0 +1,212 @@
+/**
+ * Utility Functions for Brainfish API Documentation
+ */ /**
+ * Checks if a value is a valid HTTP method
+ */ export function isValidHTTPMethod(value) {
+    const validMethods = [
+        'GET',
+        'POST',
+        'PUT',
+        'DELETE',
+        'PATCH',
+        'HEAD',
+        'OPTIONS'
+    ];
+    return validMethods.includes(value);
+}
+/**
+ * Checks if a number is numeric
+ */ export function isNumeric(value) {
+    if (typeof value === 'number') return !isNaN(value);
+    if (typeof value === 'string') {
+        const num = Number(value);
+        return !isNaN(num) && isFinite(num);
+    }
+    return false;
+}
+/**
+ * Gets status code reason phrase
+ */ export function getStatusCodeReasonPhrase(code, defaultPhrase) {
+    const statusCodes = {
+        200: 'OK',
+        201: 'Created',
+        202: 'Accepted',
+        204: 'No Content',
+        400: 'Bad Request',
+        401: 'Unauthorized',
+        403: 'Forbidden',
+        404: 'Not Found',
+        500: 'Internal Server Error',
+        502: 'Bad Gateway',
+        503: 'Service Unavailable'
+    };
+    return statusCodes[code] || defaultPhrase || 'Unknown';
+}
+/**
+ * Checks if an object has a specific property
+ */ export function objectHasProperty(obj, propName) {
+    return !!obj && typeof obj === 'object' && Object.prototype.hasOwnProperty.call(obj, propName);
+}
+/**
+ * Deep clone an object
+ */ export function cloneDeep(obj) {
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    if (obj instanceof Date) {
+        return new Date(obj.getTime());
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item)=>cloneDeep(item));
+    }
+    const cloned = {};
+    for(const key in obj){
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            cloned[key] = cloneDeep(obj[key]);
+        }
+    }
+    return cloned;
+}
+/**
+ * Strips markdown syntax from text and returns plain text
+ * Useful for displaying markdown content in compact UI areas like sidebars
+ */ export function stripMarkdown(markdown) {
+    if (!markdown) return '';
+    let text = markdown;
+    // Remove code blocks (```...```)
+    text = text.replace(/```[\s\S]*?```/g, '');
+    // Remove inline code (`...`)
+    text = text.replace(/`([^`]+)`/g, '$1');
+    // Remove headers (# ## ###)
+    text = text.replace(/^#{1,6}\s+(.+)$/gm, '$1');
+    // Remove bold (**text** or __text__)
+    text = text.replace(/\*\*([^*]+)\*\*/g, '$1');
+    text = text.replace(/__([^_]+)__/g, '$1');
+    // Remove italic (*text* or _text_)
+    text = text.replace(/\*([^*]+)\*/g, '$1');
+    text = text.replace(/_([^_]+)_/g, '$1');
+    // Remove links [text](url)
+    text = text.replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1');
+    // Remove images ![alt](url)
+    text = text.replace(/!\[([^\]]*)\]\([^\)]+\)/g, '$1');
+    // Remove horizontal rules (--- or ***)
+    text = text.replace(/^[-*]{3,}$/gm, '');
+    // Remove list markers (-, *, +, 1.)
+    text = text.replace(/^[\s]*[-*+]\s+/gm, '');
+    text = text.replace(/^[\s]*\d+\.\s+/gm, '');
+    // Remove blockquotes (>)
+    text = text.replace(/^>\s+/gm, '');
+    // Clean up multiple newlines
+    text = text.replace(/\n{3,}/g, '\n\n');
+    // Trim whitespace
+    text = text.trim();
+    return text;
+}
+/**
+ * Gets a preview of text (strips markdown and truncates)
+ */ export function getTextPreview(text, maxLength = 150) {
+    if (!text) return '';
+    const stripped = stripMarkdown(text);
+    if (stripped.length <= maxLength) {
+        return stripped;
+    }
+    // Truncate at word boundary
+    const truncated = stripped.substring(0, maxLength);
+    const lastSpace = truncated.lastIndexOf(' ');
+    if (lastSpace > maxLength * 0.7) {
+        return truncated.substring(0, lastSpace) + '...';
+    }
+    return truncated + '...';
+}
+/**
+ * Get all headings from markdown text
+ * Properly handles code blocks to avoid extracting code as headings
+ */ function getAllHeadings(markdown) {
+    const headings = [];
+    const lines = markdown.split('\n');
+    let inCodeBlock = false;
+    for (const line of lines){
+        // Check for code block delimiters (``` or ~~~)
+        if (line.trim().startsWith('```') || line.trim().startsWith('~~~')) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        // Skip lines inside code blocks
+        if (inCodeBlock) {
+            continue;
+        }
+        // Match markdown headings (# ## ### etc.)
+        // Must start with # followed by space, then have actual text content
+        const match = line.match(/^(#{1,6})\s+(.+)$/);
+        if (match) {
+            const text = match[2].trim();
+            // Skip if text looks like JSON or code (starts with special chars)
+            if (text.startsWith('{') || text.startsWith('"') || text.startsWith('[') || text.startsWith('}') || text.startsWith(']') || text === '{' || text === '}') {
+                continue;
+            }
+            headings.push({
+                level: match[1].length,
+                text: text
+            });
+        }
+    }
+    return headings;
+}
+/**
+ * Get the lowest heading level in the document
+ */ function getLowestHeadingLevel(headings) {
+    if (headings.length === 0) return 1;
+    return Math.min(...headings.map((h)=>h.level));
+}
+/**
+ * Generate a URL-friendly slug from text
+ */ function generateSlug(text, idCounts) {
+    let baseId = text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    // Ensure uniqueness by appending a counter if needed
+    if (idCounts[baseId] !== undefined) {
+        idCounts[baseId]++;
+        baseId = `${baseId}-${idCounts[baseId]}`;
+    } else {
+        idCounts[baseId] = 0;
+    }
+    return baseId;
+}
+export function extractMarkdownHeadings(markdown) {
+    if (!markdown?.trim()) return [];
+    const allHeadings = getAllHeadings(markdown);
+    const lowestLevel = getLowestHeadingLevel(allHeadings);
+    const idCounts = {};
+    const entries = [];
+    let currentParent = null;
+    // Add "Introduction" if description doesn't start with a heading
+    if (!markdown.trim().startsWith('#')) {
+        entries.push({
+            level: lowestLevel,
+            text: 'Introduction',
+            id: generateSlug('Introduction', idCounts),
+            children: []
+        });
+    }
+    // Process headings - only include lowest level and one level deeper
+    for (const heading of allHeadings){
+        // Skip headings that are not at the lowest two levels
+        if (heading.level !== lowestLevel && heading.level !== lowestLevel + 1) {
+            continue;
+        }
+        const entry = {
+            level: heading.level,
+            text: heading.text,
+            id: generateSlug(heading.text, idCounts)
+        };
+        if (heading.level === lowestLevel) {
+            // This is a top-level heading
+            entry.children = [];
+            entries.push(entry);
+            currentParent = entry;
+        } else if (currentParent && currentParent.children) {
+            // This is a child heading
+            currentParent.children.push(entry);
+        }
+    }
+    return entries;
+}

package/renderer/lib/cache.js

@@ -0,0 +1,157 @@
+/**
+ * Universal caching utility that works in both local and production environments
+ *
+ * - Local development: Uses node-cache (in-memory)
+ * - Production (Vercel): Uses Vercel KV
+ *
+ * Environment-based cache selection:
+ * 1. Explicit override: CACHE_TYPE=local or CACHE_TYPE=kv
+ * 2. Auto-detect: KV_REST_API_URL or KV_URL present → Uses Vercel KV
+ * 3. Fallback: Uses local node-cache
+ *
+ * Example usage:
+ * ```typescript
+ * import { CacheUtils } from '@/utils/cache';
+ *
+ * // Get from cache
+ * const cached = await CacheUtils.get<MyType>('my-key', { logHit: true });
+ *
+ * // Set with TTL
+ * await CacheUtils.set('my-key', data, 3600, { log: true }); // 1 hour TTL
+ *
+ * // Delete
+ * await CacheUtils.del('my-key', { log: true });
+ * ```
+ */ import NodeCache from 'node-cache';
+import { kv } from '@vercel/kv';
+/**
+ * Cache environment configuration
+ */ const CACHE_CONFIG = {
+    // Environment variables that indicate KV should be used
+    KV_INDICATORS: [
+        'KV_REST_API_URL',
+        'KV_URL'
+    ],
+    // Allow explicit override via CACHE_TYPE env var
+    CACHE_TYPE: process.env.CACHE_TYPE
+};
+/**
+ * Determine cache type based on environment variables
+ */ function getCacheType() {
+    // Explicit override takes precedence
+    if (CACHE_CONFIG.CACHE_TYPE === 'local') {
+        return 'local';
+    }
+    if (CACHE_CONFIG.CACHE_TYPE === 'kv') {
+        return 'kv';
+    }
+    // Auto-detect based on KV environment variables
+    const hasKVConfig = CACHE_CONFIG.KV_INDICATORS.some((envVar)=>!!process.env[envVar]);
+    return hasKVConfig ? 'kv' : 'local';
+}
+// Determine cache type at module load time
+const cacheType = getCacheType();
+// Initialize cache backends based on environment
+let localCache = null;
+if (cacheType === 'kv') {
+    console.log('[Cache] Using Vercel KV cache');
+} else {
+    console.log('[Cache] Using local node-cache');
+    localCache = new NodeCache({
+        stdTTL: 60 * 60 * 24,
+        checkperiod: 60 * 10,
+        useClones: false
+    });
+}
+/**
+ * Universal cache utility functions
+ */ export class CacheUtils {
+    /**
+   * Get a value from cache with optional logging
+   */ static async get(key, options) {
+        try {
+            let value;
+            if (cacheType === 'kv') {
+                value = await kv.get(key);
+            } else {
+                value = localCache?.get(key);
+            }
+            // Fix: Only return null for missing keys (undefined), not for falsy values
+            const result = value !== undefined ? value : null;
+            if (options?.logHit) {
+                if (result !== null) {
+                    console.log(`[Cache] HIT: ${key}`);
+                } else {
+                    console.log(`[Cache] MISS: ${key}`);
+                }
+            }
+            return result;
+        } catch (error) {
+            console.warn(`[Cache] Get error for key "${key}":`, error);
+            return null;
+        }
+    }
+    /**
+   * Set a value in cache with TTL and logging
+   */ static async set(key, value, ttlSeconds, options) {
+        try {
+            if (cacheType === 'kv') {
+                if (ttlSeconds) {
+                    await kv.set(key, value, {
+                        ex: ttlSeconds
+                    });
+                } else {
+                    await kv.set(key, value);
+                }
+            } else {
+                const ttl = ttlSeconds || 60 * 60 * 24; // Default to 24 hours
+                localCache?.set(key, value, ttl);
+            }
+            if (options?.log) {
+                const ttlInfo = ttlSeconds ? ` (TTL: ${ttlSeconds}s)` : '';
+                console.log(`[Cache] SET: ${key}${ttlInfo}`);
+            }
+        } catch (error) {
+            console.warn(`[Cache] Set error for key "${key}":`, error);
+        }
+    }
+    /**
+   * Delete a key from cache
+   */ static async del(key, options) {
+        try {
+            if (cacheType === 'kv') {
+                await kv.del(key);
+            } else {
+                localCache?.del(key);
+            }
+            if (options?.log) {
+                console.log(`[Cache] DEL: ${key}`);
+            }
+        } catch (error) {
+            console.warn(`[Cache] Delete error for key "${key}":`, error);
+        }
+    }
+    /**
+   * Clear all cache entries (use with caution!)
+   */ static async clear() {
+        try {
+            if (cacheType === 'kv') {
+                await kv.flushdb();
+            } else {
+                localCache?.flushAll();
+            }
+            console.log('[Cache] Cleared all entries');
+        } catch (error) {
+            console.warn('[Cache] Clear error:', error);
+        }
+    }
+    /**
+   * Get current cache type for debugging/monitoring
+   */ static getCacheType() {
+        return cacheType;
+    }
+}
+// Legacy exports for backward compatibility
+export const cache = CacheUtils;
+export { cacheType };
+export default CacheUtils;