@brainfish-ai/devdoc 0.1.48 → 0.1.49

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

@@ -147,25 +147,84 @@
     }
     return results;
 }
+/**
+ * Detect if a request is a GraphQL operation based on its tags
+ */ function isGraphQLOperation(tags) {
+    const graphqlTags = [
+        'query',
+        'mutation',
+        'subscription',
+        'queries',
+        'mutations',
+        'subscriptions'
+    ];
+    return tags.some((tag)=>graphqlTags.includes(tag.toLowerCase()));
+}
+/**
+ * Get the GraphQL operation type from tags
+ */ function getGraphQLOperationType(tags) {
+    const tagLower = tags.map((t)=>t.toLowerCase());
+    if (tagLower.includes('query') || tagLower.includes('queries')) return 'query';
+    if (tagLower.includes('mutation') || tagLower.includes('mutations')) return 'mutation';
+    if (tagLower.includes('subscription') || tagLower.includes('subscriptions')) return 'subscription';
+    return undefined;
+}
+/**
+ * Extract GraphQL variable names from the request body
+ */ function extractGraphQLVariables(body) {
+    if (!body) return [];
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed.variables && typeof parsed.variables === 'object') {
+            return Object.keys(parsed.variables);
+        }
+    } catch  {
+    // Not valid JSON, ignore
+    }
+    return [];
+}
 /**
  * Builds an endpoint index for AI context
  */ export function buildEndpointIndex(collection) {
     const allRequests = extractRequests(collection);
-    return allRequests.map(({ request, tags })=>({
+    return allRequests.map(({ request, tags })=>{
+        const allTags = [
+            ...new Set([
+                ...tags,
+                ...request.tags
+            ])
+        ].filter(Boolean);
+        const isGraphQL = isGraphQLOperation(allTags);
+        const operationType = isGraphQL ? getGraphQLOperationType(allTags) : undefined;
+        // For GraphQL operations, create a more meaningful path
+        let path = request.endpoint;
+        if (isGraphQL && operationType) {
+            // Create path like "query:getUser" or "mutation:createUser"
+            path = `${operationType}:${request.name}`;
+        }
+        // For GraphQL, extract variable names from the body
+        let parameters = request.params.map((p)=>p.key);
+        if (isGraphQL && request.body.body && typeof request.body.body === 'string') {
+            const graphqlVars = extractGraphQLVariables(request.body.body);
+            if (graphqlVars.length > 0) {
+                parameters = graphqlVars;
+            }
+        }
+        return {
             id: request.id,
             name: request.name,
-            method: request.method,
-            path: request.endpoint,
+            method: isGraphQL ? operationType?.toUpperCase() || 'GRAPHQL' : request.method,
+            path,
             description: request.description,
-            parameters: request.params.map((p)=>p.key),
+            parameters,
             hasBody: request.body.body !== null,
-            tags: [
-                ...new Set([
-                    ...tags,
-                    ...request.tags
-                ])
-            ].filter(Boolean)
-        }));
+            tags: allTags,
+            type: isGraphQL ? 'graphql' : 'rest',
+            ...operationType && {
+                operationType
+            }
+        };
+    });
 }
 /**
  * Formats the endpoint index as a string for the AI system prompt
@@ -249,6 +308,8 @@
             description: ep.description,
             parameters: ep.parameters,
             hasBody: ep.hasBody,
-            tags: ep.tags
+            tags: ep.tags,
+            type: ep.type,
+            operationType: ep.operationType
         }));
 }

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

@@ -1,5 +1,5 @@
 'use client';
-import { useState, useEffect, useMemo } from 'react';
+import { useState, useEffect, useMemo, useRef } from 'react';
 /**
  * Shared hook for fetching contextual suggestions
  * Used by both AgentChat and AgentPopupButton
@@ -8,19 +8,28 @@ import { useState, useEffect, useMemo } from 'react';
  */ 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
+    // Use refs for values that shouldn't trigger re-fetches when they change
+    const endpointIndexRef = useRef(endpointIndex);
+    endpointIndexRef.current = endpointIndex;
+    const limitRef = useRef(limit);
+    limitRef.current = limit;
+    // Extract primitive values for stable dependencies
+    const currentEndpointId = currentEndpoint?.id;
+    const currentEndpointName = currentEndpoint?.name;
+    const endpointIndexLength = endpointIndex.length;
+    // Stable key for request deduplication - only based on primitives
+    const requestKey = useMemo(()=>currentEndpointId || `general:${endpointIndexLength}`, [
+        currentEndpointId,
+        endpointIndexLength
     ]);
-    // Fallback suggestions
+    // Fallback suggestions - only depend on primitive values
     const fallbackSuggestions = useMemo(()=>{
-        if (currentEndpoint) {
+        if (currentEndpointName) {
             return [
                 {
                     title: 'What does this',
                     label: 'endpoint do?',
-                    prompt: `What does ${currentEndpoint.name} do?`
+                    prompt: `What does ${currentEndpointName} do?`
                 },
                 {
                     title: 'What parameters',
@@ -52,9 +61,10 @@ import { useState, useEffect, useMemo } from 'react';
             }
         ];
     }, [
-        currentEndpoint
+        currentEndpointName
     ]);
     // Fetch suggestions from API (server handles KV caching)
+    // Only re-fetch when requestKey changes (based on endpoint ID or index length)
     useEffect(()=>{
         let cancelled = false;
         setIsLoading(true);
@@ -64,19 +74,21 @@ import { useState, useEffect, useMemo } from 'react';
                 'Content-Type': 'application/json'
             },
             body: JSON.stringify({
-                endpointIndex,
-                currentEndpointId: currentEndpoint?.id
+                endpointIndex: endpointIndexRef.current,
+                currentEndpointId
             })
         }).then((res)=>res.json()).then((data)=>{
             if (cancelled) return;
             if (data.suggestions) {
                 const allSuggestions = data.suggestions;
-                setSuggestions(limit ? allSuggestions.slice(0, limit) : allSuggestions);
+                const currentLimit = limitRef.current;
+                setSuggestions(currentLimit ? allSuggestions.slice(0, currentLimit) : allSuggestions);
             }
         }).catch((err)=>{
             if (cancelled) return;
             console.warn('[useSuggestions] Failed to fetch suggestions:', err);
-            setSuggestions(limit ? fallbackSuggestions.slice(0, limit) : fallbackSuggestions);
+            const currentLimit = limitRef.current;
+            setSuggestions(currentLimit ? fallbackSuggestions.slice(0, currentLimit) : fallbackSuggestions);
         }).finally(()=>{
             if (!cancelled) setIsLoading(false);
         });
@@ -85,9 +97,7 @@ import { useState, useEffect, useMemo } from 'react';
         };
     }, [
         requestKey,
-        currentEndpoint,
-        endpointIndex,
-        limit,
+        currentEndpointId,
         fallbackSuggestions
     ]);
     return {

package/renderer/lib/api-docs/code-editor/mode-context.js

@@ -4,14 +4,14 @@ import React, { createContext, useContext, useState, useCallback, useEffect, use
 import { switchView } from '@/lib/docs-navigation';
 const ModeContext = /*#__PURE__*/ createContext(null);
 /**
- * Parse view mode from URL hash
- */ function parseViewFromHash() {
+ * Parse view mode from URL pathname
+ */ function parseViewFromPath() {
     if (typeof window === 'undefined') return 'docs';
-    const hash = window.location.hash.slice(1);
-    if (!hash) return 'docs';
+    const pathname = window.location.pathname;
+    if (!pathname || pathname === '/') return 'docs';
     // Check for view suffix at the end
-    if (hash.endsWith('/playground')) return 'playground';
-    if (hash.endsWith('/notes')) return 'notes';
+    if (pathname.endsWith('/playground')) return 'playground';
+    if (pathname.endsWith('/notes')) return 'notes';
     return 'docs';
 }
 /**
@@ -39,29 +39,27 @@ const ModeContext = /*#__PURE__*/ createContext(null);
     }
 }
 export function ModeProvider({ children, defaultMode = 'docs' }) {
-    // Track current hash to derive mode
-    const [hash, setHash] = useState(()=>typeof window !== 'undefined' ? window.location.hash : '');
-    // Derive mode from URL hash
+    // Track current pathname to derive mode
+    const [pathname, setPathname] = useState(()=>typeof window !== 'undefined' ? window.location.pathname : '');
+    // Derive mode from URL pathname
     const mode = useMemo(()=>{
-        const view = parseViewFromHash();
+        const view = parseViewFromPath();
         return viewToPlaygroundMode(view);
     }, [
-        hash
+        pathname
     ]);
     // Notes-specific state (not URL-based yet)
     const [activeFilePath, setActiveFilePathState] = useState(null);
     const [streamingContent, setStreamingContent] = useState(null);
     const [notesRefreshTrigger, setNotesRefreshTrigger] = useState(0);
-    // Listen for hash changes to update mode
+    // Listen for pathname changes to update mode
     useEffect(()=>{
-        const handleHashChange = ()=>{
-            setHash(window.location.hash);
+        const handlePathChange = ()=>{
+            setPathname(window.location.pathname);
         };
-        window.addEventListener('hashchange', handleHashChange);
-        window.addEventListener('popstate', handleHashChange);
+        window.addEventListener('popstate', handlePathChange);
         return ()=>{
-            window.removeEventListener('hashchange', handleHashChange);
-            window.removeEventListener('popstate', handleHashChange);
+            window.removeEventListener('popstate', handlePathChange);
         };
     }, []);
     // Wrapper for setActiveFilePath

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

@@ -158,7 +158,14 @@ import { parseOpenAPIAuth, extractSecurityHeaders, getDefaultAuth } from './extr
                     requestsByTags[tag] = [];
                 }
                 // Clone request for each tag (request can belong to multiple tags)
-                requestsByTags[tag].push(cloneDeep(request));
+                // Generate unique ID per tag to avoid multiple highlights when selecting
+                const clonedRequest = cloneDeep(request);
+                if (tags.length > 1) {
+                    // Append tag slug to ID for uniqueness when endpoint appears in multiple tags
+                    const tagSlug = tag.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+                    clonedRequest.id = `${request.id}--${tagSlug}`;
+                }
+                requestsByTags[tag].push(clonedRequest);
             }
         });
         // Create folders (collections) for each tag

package/renderer/lib/cache/purge.js

@@ -0,0 +1,98 @@
+/**
+ * Vercel Edge Cache Purge Utilities
+ * 
+ * Functions for invalidating CDN-cached content after deployments
+ */ /**
+ * Purge Vercel Edge cache for a project
+ * Uses Vercel's Purge Cache API to invalidate CDN-cached content
+ * 
+ * @param slug - Project slug to purge cache for
+ * @returns Promise that resolves when purge is complete (or skipped)
+ */ export async function purgeProjectCache(slug) {
+    const token = process.env.VERCEL_API_TOKEN;
+    const teamId = process.env.VERCEL_TEAM_ID;
+    const projectId = process.env.VERCEL_PROJECT_ID;
+    if (!token) {
+        console.log('[Cache] Skipping purge: VERCEL_API_TOKEN not set');
+        return;
+    }
+    const tags = [
+        `project-${slug}`,
+        `assets-${slug}`
+    ];
+    try {
+        // Try tag-based purge first (more targeted)
+        const tagPurgeSuccess = await purgeByTags(tags, token, teamId);
+        if (tagPurgeSuccess) {
+            console.log('[Cache] Edge cache purged for tags:', tags);
+            return;
+        }
+        // Fallback to project-wide cache purge
+        if (projectId) {
+            const projectPurgeSuccess = await purgeProjectWide(projectId, token, teamId);
+            if (projectPurgeSuccess) {
+                console.log('[Cache] Project cache purged successfully');
+                return;
+            }
+        }
+        console.warn('[Cache] Cache purge failed - content may be stale for up to 5 minutes');
+    } catch (error) {
+        console.warn('[Cache] Purge error:', error);
+    }
+}
+/**
+ * Purge cache by tags using Vercel's tag-based invalidation
+ */ async function purgeByTags(tags, token, teamId) {
+    try {
+        const url = new URL('https://api.vercel.com/v1/cache');
+        if (teamId) {
+            url.searchParams.set('teamId', teamId);
+        }
+        const response = await fetch(url.toString(), {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                tags
+            })
+        });
+        return response.ok;
+    } catch  {
+        return false;
+    }
+}
+/**
+ * Purge entire project cache (fallback when tag purge fails)
+ */ async function purgeProjectWide(projectId, token, teamId) {
+    try {
+        const url = new URL(`https://api.vercel.com/v1/projects/${projectId}/cache`);
+        if (teamId) {
+            url.searchParams.set('teamId', teamId);
+        }
+        const response = await fetch(url.toString(), {
+            method: 'DELETE',
+            headers: {
+                'Authorization': `Bearer ${token}`
+            }
+        });
+        return response.ok;
+    } catch  {
+        return false;
+    }
+}
+/**
+ * Purge specific asset paths from cache
+ * 
+ * @param slug - Project slug
+ * @param paths - Array of asset paths to purge
+ */ export async function purgeAssetPaths(slug, paths) {
+    const tags = paths.map((p)=>`assets-${slug}-${p.replace(/[^a-z0-9]/gi, '-')}`);
+    const token = process.env.VERCEL_API_TOKEN;
+    const teamId = process.env.VERCEL_TEAM_ID;
+    if (!token) {
+        return;
+    }
+    await purgeByTags(tags, token, teamId);
+}

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

@@ -0,0 +1,146 @@
+/**
+ * Docs Link Utilities
+ * 
+ * Shared utilities for resolving internal documentation links.
+ * Used by Card component, MdxLink, and other components that handle
+ * navigation within documentation.
+ */ /**
+ * Check if a URL is external (starts with http/https or //)
+ */ export function isExternalLink(href) {
+    return href.startsWith('http') || href.startsWith('//');
+}
+/**
+ * Check if a path segment matches a known tab ID
+ */ export function isTabId(segment, tabIds) {
+    if (!tabIds || tabIds.length === 0) return false;
+    return tabIds.includes(segment);
+}
+/**
+ * Parse a link href and determine its type and target
+ */ export function parseLink(href, context) {
+    // External links
+    if (isExternalLink(href)) {
+        return {
+            href,
+            isTabLink: false,
+            isPageLink: false,
+            isExternal: true
+        };
+    }
+    // Anchor links (same page)
+    if (href.startsWith('#')) {
+        return {
+            href,
+            isTabLink: false,
+            isPageLink: false,
+            isExternal: false
+        };
+    }
+    // Internal links starting with /
+    if (href.startsWith('/')) {
+        const pathSegment = href.slice(1) // Remove leading /
+        ;
+        const pathParts = pathSegment.split('/');
+        const firstPart = pathParts[0];
+        // Check if this is a direct tab link (e.g., /facebook-pages-api)
+        if (pathParts.length === 1 && isTabId(firstPart, context.tabIds)) {
+            return {
+                href,
+                isTabLink: true,
+                isPageLink: false,
+                isExternal: false,
+                targetTab: firstPart
+            };
+        }
+        // Check if path already has proper structure (/tab/page/slug or /tab/endpoint/id)
+        if (href.includes('/page/') || href.includes('/endpoint/') || href.includes('/section/')) {
+            return {
+                href,
+                isTabLink: false,
+                isPageLink: true,
+                isExternal: false
+            };
+        }
+        // Simple page path - needs to be resolved with active tab context
+        return {
+            href,
+            isTabLink: false,
+            isPageLink: true,
+            isExternal: false,
+            targetSlug: pathSegment
+        };
+    }
+    // Relative links (no leading /)
+    return {
+        href,
+        isTabLink: false,
+        isPageLink: true,
+        isExternal: false,
+        targetSlug: href
+    };
+}
+/**
+ * Resolve a link href to its final URL based on context
+ * 
+ * - Tab links: /facebook-pages-api → /facebook-pages-api (unchanged)
+ * - Page links within tab: /quickstart → /documentation/page/quickstart
+ * - Already resolved: /tab/page/slug → /tab/page/slug (unchanged)
+ * - External: https://... → https://... (unchanged)
+ */ export function resolveLink(href, context) {
+    if (!href) return href;
+    const parsed = parseLink(href, context);
+    // External links and anchor links stay as-is
+    if (parsed.isExternal || href.startsWith('#')) {
+        return href;
+    }
+    // Tab links stay as-is
+    if (parsed.isTabLink) {
+        return href;
+    }
+    // Already resolved paths stay as-is
+    if (href.includes('/page/') || href.includes('/endpoint/') || href.includes('/section/')) {
+        return href;
+    }
+    // Simple page paths need to be prefixed with active tab
+    if (parsed.targetSlug && context.activeTab) {
+        return `/${context.activeTab}/page/${parsed.targetSlug}`;
+    }
+    return href;
+}
+export function getLinkAction(href, context) {
+    if (!href) {
+        return {
+            type: 'navigate',
+            href: ''
+        };
+    }
+    const parsed = parseLink(href, context);
+    if (parsed.isExternal) {
+        return {
+            type: 'external',
+            href
+        };
+    }
+    if (href.startsWith('#')) {
+        return {
+            type: 'anchor',
+            href
+        };
+    }
+    if (parsed.isTabLink && parsed.targetTab) {
+        return {
+            type: 'switchTab',
+            tabId: parsed.targetTab
+        };
+    }
+    if (parsed.targetSlug) {
+        return {
+            type: 'navigatePage',
+            slug: parsed.targetSlug
+        };
+    }
+    return {
+        type: 'navigate',
+        href: resolveLink(href, context)
+    };
+}

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

@@ -2,7 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import React, { createContext, useContext, useCallback } from 'react';
 const DocsNavigationContext = /*#__PURE__*/ createContext(null);
-export function DocsNavigationProvider({ children, onNavigateToPage, onNavigateToEndpoint, onSwitchTab, activeTab }) {
+export function DocsNavigationProvider({ children, onNavigateToPage, onNavigateToEndpoint, onSwitchTab, activeTab, tabIds }) {
     const navigateToPage = useCallback((slug)=>{
         if (onNavigateToPage) {
             onNavigateToPage(slug);
@@ -30,7 +30,8 @@ export function DocsNavigationProvider({ children, onNavigateToPage, onNavigateT
             navigateToEndpoint,
             switchToTab,
             isApiDocsView: !!onNavigateToPage,
-            activeTab
+            activeTab,
+            tabIds
         },
         children: children
     });