@brainfish-ai/devdoc 0.1.42 → 0.1.43

package/renderer/lib/api-docs/parsers/openapi/transformer.js

@@ -0,0 +1,192 @@
+/**
+ * OpenAPI Transformer
+ * 
+ * Ported from Hoppscotch's openapi/index.ts
+ * Converts OpenAPI Document to BrainfishCollection
+ */ /* eslint-disable @typescript-eslint/no-explicit-any */ import { makeBrainfishCollection, makeBrainfishRESTRequest, makeBrainfishRESTResponseOriginalRequest } from '../../factories';
+import { objectHasProperty, cloneDeep } from '../../utils';
+import { hasUnresolvedRefs } from './dereferencer';
+import { replaceOpenApiPathTemplating, parseOpenAPIParams, parseOpenAPIHeaders, parseOpenAPIVariables, parseOpenAPIResponses } from './extractors';
+import { parseOpenAPIBody } from './extractors/body';
+import { parseOpenAPIAuth, extractSecurityHeaders, getDefaultAuth } from './extractors/auth';
+/**
+ * Formats an operation name for display
+ * Converts snake_case/kebab-case operationIds to readable Title Case
+ * Prefers summary over operationId if available
+ */ function formatOperationName(info) {
+    const summary = info.summary?.trim();
+    const operationId = info.operationId?.trim();
+    // Prefer summary as it's usually more human-readable
+    if (summary) {
+        return summary;
+    }
+    // If only operationId is available, convert to readable format
+    if (operationId) {
+        return operationId// Replace underscores and hyphens with spaces
+        .replace(/[_-]/g, ' ')// Handle camelCase by adding space before capital letters
+        .replace(/([a-z])([A-Z])/g, '$1 $2')// Capitalize first letter of each word
+        .replace(/\b\w/g, (char)=>char.toUpperCase())// Clean up multiple spaces
+        .replace(/\s+/g, ' ').trim();
+    }
+    return 'Untitled Request';
+}
+/**
+ * Parses OpenAPI URL from document (v2 or v3)
+ */ function parseOpenAPIUrl(doc) {
+    // OpenAPI V2 has host and basePath in document properties
+    if (objectHasProperty(doc, 'swagger')) {
+        const host = doc.host?.trim() || '<<baseUrl>>';
+        const basePath = doc.basePath?.trim() || '';
+        return `${host}${basePath}`;
+    }
+    // OpenAPI V3 has servers array
+    if (objectHasProperty(doc, 'servers')) {
+        const serverUrl = doc.servers?.[0]?.url;
+        return !serverUrl || serverUrl === './' ? '<<baseUrl>>' : serverUrl;
+    }
+    // Fallback
+    return '<<baseUrl>>';
+}
+/**
+ * Converts an OpenAPI path to Brainfish requests
+ */ function convertPathToBrainfishReqs(doc, pathName, pathObj) {
+    const methods = [
+        'get',
+        'head',
+        'post',
+        'put',
+        'delete',
+        'options',
+        'patch'
+    ];
+    return methods.filter((method)=>!!pathObj[method]).map((method)=>{
+        const info = pathObj[method];
+        const openAPIUrl = parseOpenAPIUrl(doc);
+        const openAPIPath = replaceOpenApiPathTemplating(pathName);
+        const endpoint = openAPIUrl.endsWith('/') && openAPIPath.startsWith('/') ? openAPIUrl + openAPIPath.slice(1) : openAPIUrl + openAPIPath;
+        const params = parseOpenAPIParams(info.parameters ?? []);
+        const baseHeaders = parseOpenAPIHeaders(info.parameters ?? []);
+        // Get the primary auth key (handled by global auth) to exclude from additional headers
+        const defaultAuth = getDefaultAuth(doc);
+        const primaryAuthKey = defaultAuth?.authType === 'api-key' ? defaultAuth.key : undefined;
+        // Extract additional security headers (e.g., agent-key when access-token is primary)
+        const securityHeaders = extractSecurityHeaders(doc, info, primaryAuthKey);
+        // Merge headers: base headers + security headers (avoiding duplicates)
+        const existingKeys = new Set(baseHeaders.map((h)=>h.key.toLowerCase()));
+        const additionalSecurityHeaders = securityHeaders.filter((h)=>!existingKeys.has(h.key.toLowerCase())).map((h)=>({
+                key: h.key,
+                value: h.value,
+                active: h.active,
+                description: h.description
+            }));
+        const headers = [
+            ...baseHeaders,
+            ...additionalSecurityHeaders
+        ];
+        const requestVariables = parseOpenAPIVariables(info.parameters ?? []);
+        const auth = parseOpenAPIAuth(doc, info);
+        const body = parseOpenAPIBody(doc, info);
+        const displayName = formatOperationName(info);
+        const originalRequest = makeBrainfishRESTResponseOriginalRequest({
+            name: displayName,
+            method: method.toUpperCase(),
+            endpoint,
+            params,
+            headers,
+            body,
+            auth,
+            requestVariables
+        });
+        const responses = parseOpenAPIResponses(doc, info, originalRequest);
+        const request = makeBrainfishRESTRequest({
+            name: displayName,
+            description: info.description ?? null,
+            method: method.toUpperCase(),
+            endpoint,
+            params,
+            headers,
+            auth,
+            body,
+            requestVariables,
+            responses,
+            tags: info.tags ?? [],
+            operationId: info.operationId ?? undefined
+        });
+        return {
+            request,
+            metadata: {
+                tags: info.tags ?? []
+            }
+        };
+    });
+}
+/**
+ * Converts OpenAPI documents to BrainfishCollections
+ */ export function convertOpenAPIToCollection(docs) {
+    // Check for unresolved references before conversion
+    for (const doc of docs){
+        if (hasUnresolvedRefs(doc)) {
+            console.warn('Document contains unresolved references which may affect import quality');
+        // Continue anyway to provide a best-effort import
+        }
+    }
+    const collections = docs.map((doc)=>{
+        const name = doc.info.title;
+        const description = doc.info.description ?? null;
+        // Extract tag descriptions from OpenAPI spec
+        const tagDescriptions = {};
+        if ('tags' in doc && Array.isArray(doc.tags)) {
+            doc.tags.forEach((tag)=>{
+                if (tag.name && tag.description) {
+                    tagDescriptions[tag.name] = tag.description;
+                }
+            });
+        }
+        // Convert all paths to requests
+        const paths = Object.entries(doc.paths ?? {}).map(([pathName, pathObj])=>convertPathToBrainfishReqs(doc, pathName, pathObj)).flat();
+        // Organize requests by tags
+        const requestsByTags = {};
+        const requestsWithoutTags = [];
+        paths.forEach(({ metadata, request })=>{
+            const tags = metadata.tags;
+            if (tags.length === 0) {
+                requestsWithoutTags.push(request);
+                return;
+            }
+            for (const tag of tags){
+                if (!requestsByTags[tag]) {
+                    requestsByTags[tag] = [];
+                }
+                // Clone request for each tag (request can belong to multiple tags)
+                requestsByTags[tag].push(cloneDeep(request));
+            }
+        });
+        // Create folders (collections) for each tag
+        const folders = Object.entries(requestsByTags).map(([tagName, requests])=>makeBrainfishCollection({
+                name: tagName,
+                description: tagDescriptions[tagName] ?? null,
+                requests,
+                folders: [],
+                variables: [],
+                auth: {
+                    authType: 'inherit',
+                    authActive: true
+                },
+                headers: []
+            }));
+        // Create main collection
+        return makeBrainfishCollection({
+            name,
+            description,
+            folders,
+            requests: requestsWithoutTags,
+            variables: [],
+            auth: {
+                authType: 'inherit',
+                authActive: true
+            },
+            headers: []
+        });
+    });
+    return collections;
+}

package/renderer/lib/api-docs/parsers/openapi/validator.js

@@ -0,0 +1,24 @@
+/**
+ * OpenAPI Validator
+ * 
+ * Ported from Hoppscotch's openapi-import-worker.ts
+ * Converts Web Worker pattern to direct function calls for Next.js
+ */ import SwaggerParser from '@apidevtools/swagger-parser';
+/**
+ * Validates an OpenAPI document using SwaggerParser
+ * 
+ * @param docs - The OpenAPI document to validate
+ * @returns Promise resolving to validated OpenAPI document
+ * @throws Error if validation fails
+ */ export async function validateOpenAPISpec(docs) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const validated = await SwaggerParser.validate(docs, {
+            // @ts-expect-error - this is a valid option, but types may not be updated
+            continueOnError: true
+        });
+        return validated;
+    } catch  {
+        throw new Error('COULD_NOT_VALIDATE');
+    }
+}

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

@@ -0,0 +1,65 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useState, useCallback } from 'react';
+const PlaygroundContext = /*#__PURE__*/ createContext(null);
+export function PlaygroundProvider({ children }) {
+    const [pendingPrefill, setPendingPrefill] = useState(null);
+    const [currentRequestPayload, setCurrentRequestPayloadState] = useState(null);
+    const [triggerSend, setTriggerSend] = useState(false);
+    const setPrefill = useCallback((data)=>{
+        setPendingPrefill(data);
+    }, []);
+    const clearPrefill = useCallback(()=>{
+        setPendingPrefill(null);
+    }, []);
+    const setCurrentRequestPayload = useCallback((payload)=>{
+        setCurrentRequestPayloadState(payload);
+    }, []);
+    const requestSend = useCallback(()=>{
+        setTriggerSend(true);
+    }, []);
+    const clearSendTrigger = useCallback(()=>{
+        setTriggerSend(false);
+    }, []);
+    return /*#__PURE__*/ _jsx(PlaygroundContext.Provider, {
+        value: {
+            pendingPrefill,
+            setPrefill,
+            clearPrefill,
+            currentRequestPayload,
+            setCurrentRequestPayload,
+            triggerSend,
+            requestSend,
+            clearSendTrigger
+        },
+        children: children
+    });
+}
+export function usePlaygroundPrefill() {
+    const context = useContext(PlaygroundContext);
+    if (!context) {
+        throw new Error('usePlaygroundPrefill must be used within a PlaygroundProvider');
+    }
+    return context;
+}
+export function useCurrentRequestPayload() {
+    const context = useContext(PlaygroundContext);
+    if (!context) {
+        throw new Error('useCurrentRequestPayload must be used within a PlaygroundProvider');
+    }
+    return {
+        currentRequestPayload: context.currentRequestPayload,
+        setCurrentRequestPayload: context.setCurrentRequestPayload
+    };
+}
+export function useSendTrigger() {
+    const context = useContext(PlaygroundContext);
+    if (!context) {
+        throw new Error('useSendTrigger must be used within a PlaygroundProvider');
+    }
+    return {
+        triggerSend: context.triggerSend,
+        requestSend: context.requestSend,
+        clearSendTrigger: context.clearSendTrigger
+    };
+}

package/renderer/lib/api-docs/playground/navigation-context.js

@@ -0,0 +1,74 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useState, useCallback } from 'react';
+const PlaygroundNavigationContext = /*#__PURE__*/ createContext(undefined);
+export function PlaygroundNavigationProvider({ children }) {
+    const [state, setState] = useState({
+        activeTab: null,
+        highlightField: null,
+        showError: false
+    });
+    const navigateToTab = useCallback((tab)=>{
+        setState((prev)=>({
+                ...prev,
+                activeTab: tab,
+                highlightField: null,
+                showError: false
+            }));
+    }, []);
+    const navigateAndHighlight = useCallback((tab, field, showError = true)=>{
+        setState({
+            activeTab: tab,
+            highlightField: field || null,
+            showError
+        });
+        // Auto-clear highlight after a delay
+        if (field) {
+            setTimeout(()=>{
+                setState((prev)=>({
+                        ...prev,
+                        highlightField: null,
+                        showError: false
+                    }));
+            }, 3000);
+        }
+    }, []);
+    const clearHighlight = useCallback(()=>{
+        setState((prev)=>({
+                ...prev,
+                highlightField: null,
+                showError: false
+            }));
+    }, []);
+    const setActiveTab = useCallback((tab)=>{
+        setState((prev)=>({
+                ...prev,
+                activeTab: tab
+            }));
+    }, []);
+    const resetNavigation = useCallback(()=>{
+        setState({
+            activeTab: null,
+            highlightField: null,
+            showError: false
+        });
+    }, []);
+    return /*#__PURE__*/ _jsx(PlaygroundNavigationContext.Provider, {
+        value: {
+            state,
+            navigateToTab,
+            navigateAndHighlight,
+            clearHighlight,
+            setActiveTab,
+            resetNavigation
+        },
+        children: children
+    });
+}
+export function usePlaygroundNavigation() {
+    const context = useContext(PlaygroundNavigationContext);
+    if (context === undefined) {
+        throw new Error('usePlaygroundNavigation must be used within a PlaygroundNavigationProvider');
+    }
+    return context;
+}

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

@@ -0,0 +1,163 @@
+/**
+ * Request Builder
+ * 
+ * Builds HTTP requests from BrainfishRESTRequest
+ * Ported and simplified from Hoppscotch's EffectiveURL and request building logic
+ */ /**
+ * Builds auth headers from auth configuration
+ */ function buildAuthHeaders(auth) {
+    const headers = {};
+    if (auth.authType === 'basic' && auth.authActive) {
+        const credentials = btoa(`${auth.username}:${auth.password}`);
+        headers['Authorization'] = `Basic ${credentials}`;
+    } else if (auth.authType === 'bearer' && auth.authActive) {
+        headers['Authorization'] = `Bearer ${auth.token}`;
+    } else if (auth.authType === 'api-key' && auth.authActive) {
+        if (auth.addTo === 'HEADERS') {
+            headers[auth.key] = auth.value;
+        }
+    } else if (auth.authType === 'oauth-2' && auth.authActive) {
+        // For OAuth2, we'll use the token if available
+        if (auth.grantTypeInfo.token) {
+            headers['Authorization'] = `Bearer ${auth.grantTypeInfo.token}`;
+        }
+    }
+    return headers;
+}
+/**
+ * Builds auth query parameters
+ */ function buildAuthParams(auth) {
+    const params = {};
+    if (auth.authType === 'api-key' && auth.authActive) {
+        if (auth.addTo === 'QUERY_PARAMS') {
+            params[auth.key] = auth.value;
+        }
+    }
+    return params;
+}
+/**
+ * Builds request body from body configuration
+ */ function buildRequestBody(body, bodyValue) {
+    if (!body.body || body.contentType === null) {
+        return undefined;
+    }
+    // Use provided bodyValue if available (from playground editor)
+    if (bodyValue !== undefined && bodyValue !== null) {
+        if (body.contentType === 'application/json') {
+            // Return as-is - user might be editing
+            return bodyValue;
+        } else if (body.contentType === 'application/x-www-form-urlencoded') {
+            // Parse as form data
+            const params = new URLSearchParams();
+            bodyValue.split('\n').forEach((line)=>{
+                const [key, ...valueParts] = line.split(':');
+                if (key && valueParts.length > 0) {
+                    params.append(key.trim(), valueParts.join(':').trim());
+                }
+            });
+            return params.toString();
+        }
+        return bodyValue;
+    }
+    // Use body from request
+    if (Array.isArray(body.body)) {
+        // Form data
+        if (body.contentType === 'multipart/form-data') {
+            const formData = new FormData();
+            body.body.forEach((item)=>{
+                // Note: In a real implementation, isFile would indicate a file upload
+                // For now, we just append the string value
+                if (typeof item.value === 'string') {
+                    formData.append(item.key, item.value);
+                } else {
+                    // File or Blob value
+                    formData.append(item.key, item.value);
+                }
+            });
+            return formData;
+        } else if (body.contentType === 'application/x-www-form-urlencoded') {
+            // URL encoded form
+            const params = new URLSearchParams();
+            body.body.forEach((item)=>{
+                if (typeof item.value === 'string') {
+                    params.append(item.key, item.value);
+                }
+            });
+            return params;
+        }
+    } else if (typeof body.body === 'string') {
+        return body.body;
+    }
+    return undefined;
+}
+/**
+ * Builds the final URL with path variables and query parameters
+ */ function buildURL(endpoint, params, variables, authParams) {
+    // Replace path variables (<<variable>> or {variable})
+    let url = endpoint;
+    variables.forEach((variable)=>{
+        // Replace <<variable>> pattern
+        url = url.replace(new RegExp(`<<${variable.key}>>`, 'g'), variable.value || '');
+        // Replace {variable} pattern
+        url = url.replace(new RegExp(`\\{${variable.key}\\}`, 'g'), variable.value || '');
+    });
+    // Build query string
+    const queryParams = new URLSearchParams();
+    // Add request params
+    params.filter((p)=>p.active && p.key).forEach((param)=>{
+        queryParams.append(param.key, param.value);
+    });
+    // Add auth params
+    Object.entries(authParams).forEach(([key, value])=>{
+        queryParams.append(key, value);
+    });
+    // Append query string to URL
+    const queryString = queryParams.toString();
+    if (queryString) {
+        const separator = url.includes('?') ? '&' : '?';
+        url = `${url}${separator}${queryString}`;
+    }
+    return url;
+}
+/**
+ * Builds a complete HTTP request from BrainfishRESTRequest
+ */ export function buildRequest(request, options) {
+    // Use provided values or fall back to request defaults
+    const params = options?.params || request.params;
+    const headers = options?.headers || request.headers;
+    const variables = options?.variables || request.requestVariables;
+    const bodyValue = options?.body;
+    // Build auth headers and params
+    const authHeaders = buildAuthHeaders(request.auth);
+    const authParams = buildAuthParams(request.auth);
+    // Build URL
+    const url = buildURL(request.endpoint, params, variables, authParams);
+    // Build body
+    const body = buildRequestBody(request.body, bodyValue ?? undefined);
+    // Build headers
+    const finalHeaders = {
+        ...authHeaders
+    };
+    headers.filter((h)=>h.active && h.key).forEach((header)=>{
+        finalHeaders[header.key] = header.value;
+    });
+    // Add content-type if body exists (but don't override if already set)
+    if (body && request.body.contentType && !finalHeaders['Content-Type']) {
+        finalHeaders['Content-Type'] = request.body.contentType;
+    }
+    // For POST/PUT/PATCH requests without body, add default Content-Type
+    // Some APIs require this header even for empty requests
+    if (!finalHeaders['Content-Type'] && [
+        'POST',
+        'PUT',
+        'PATCH'
+    ].includes(request.method)) {
+        finalHeaders['Content-Type'] = 'application/json';
+    }
+    return {
+        url,
+        method: request.method,
+        headers: finalHeaders,
+        body
+    };
+}