@brainfish-ai/devdoc 0.1.48 → 0.1.49

package/renderer/app/api/chat/route.js

@@ -4,7 +4,25 @@ import { z } from 'zod';
 // Use Node.js runtime for better compatibility
 export const runtime = 'nodejs';
 function buildSystemPrompt(endpoints, docs, changelog, currentEndpointId, apiSummary) {
-    const endpointsList = endpoints.map((ep, i)=>{
+    // Separate GraphQL and REST endpoints for better organization
+    const graphqlEndpoints = endpoints.filter((ep)=>ep.type === 'graphql');
+    const restEndpoints = endpoints.filter((ep)=>ep.type === 'rest');
+    // Format REST endpoints
+    const restEndpointsList = restEndpoints.map((ep, i)=>{
+        const params = ep.parameters.length > 0 ? ` (params: ${ep.parameters.join(', ')})` : '';
+        return `${i + 1}. [${ep.method}] ${ep.name} - ${ep.path}${params}${ep.description ? ` - ${ep.description.slice(0, 100)}` : ''} (id: ${ep.id})`;
+    }).join('\n');
+    // Format GraphQL endpoints with operation type
+    const graphqlEndpointsList = graphqlEndpoints.map((ep, i)=>{
+        const opType = ep.operationType?.toUpperCase() || 'GRAPHQL';
+        const variables = ep.parameters.length > 0 ? ` (variables: ${ep.parameters.join(', ')})` : '';
+        return `${i + 1}. [${opType}] ${ep.name}${variables}${ep.description ? ` - ${ep.description.slice(0, 100)}` : ''} (id: ${ep.id})`;
+    }).join('\n');
+    // Combine endpoint lists
+    const endpointsList = [
+        restEndpointsList && `### REST Endpoints\n${restEndpointsList}`,
+        graphqlEndpointsList && `### GraphQL Operations\n${graphqlEndpointsList}`
+    ].filter(Boolean).join('\n\n') || restEndpoints.concat(graphqlEndpoints).map((ep, i)=>{
         const params = ep.parameters.length > 0 ? ` (params: ${ep.parameters.join(', ')})` : '';
         return `${i + 1}. [${ep.method}] ${ep.name} - ${ep.path}${params}${ep.description ? ` - ${ep.description.slice(0, 100)}` : ''} (id: ${ep.id})`;
     }).join('\n');
@@ -166,16 +184,24 @@ Before answering ANY question about this documentation, you MUST use search_docs
 - Use when user asks about an endpoint, wants documentation, or asks "what is", "how to use"
 - Call this AFTER navigate_to_endpoint to show the documentation view
 
-**prefill_parameters**: Fill in values user provides
+**prefill_parameters**: Fill in values for REST endpoints
 - Use when user gives specific values like "user_id is 123", "set the name to John"
 - Can fill params (query), headers, body, or pathVariables (URL path params)
 - **IMPORTANT**: For URL path parameters like {id}, {document_id}, <<id>>, use pathVariables NOT params
 - Example: If URL is /documents/{id}, use pathVariables: [{key: "id", value: "123"}]
 - **IMPORTANT**: Call switch_to_api_client BEFORE prefilling so user can see the API Client
+- **DO NOT use for GraphQL** - use prefill_graphql_variables instead
+
+**prefill_graphql_variables**: Fill in GraphQL variables
+- Use when user provides specific values for GraphQL query variables
+- Pass a JSON object with the variable values, e.g. { "code": "EU" }
+- **IMPORTANT**: Navigate to the GraphQL operation FIRST, then prefill variables
+- Works in Docs mode (GraphQL Playground)
 
 **switch_to_api_client**: Switch to API Client tab
-- Use when helping users test endpoints, send requests, or prefill data
+- Use when helping users test REST endpoints, send requests, or prefill data
 - Call this FIRST before prefill_parameters so user can see the changes
+- **DO NOT use for GraphQL endpoints** - GraphQL uses the GraphQL Playground in Docs mode
 
 **check_request_validity**: Validate if request is ready to send
 - Use BEFORE sending to check what's missing
@@ -187,11 +213,17 @@ Before answering ANY question about this documentation, you MUST use search_docs
 - ALWAYS check_request_validity first if you haven't already
 - Returns full response with status, body, headers, timing
 
-**get_current_request**: Get the user's current request configuration from the API Client
+**get_current_request**: Get the user's current REST request configuration from the API Client
 - Use when user says "use my request", "use current payload", "based on my config", "copy from playground"
 - Returns: method, URL, query params, headers, body - exactly as configured in the playground
 - ALWAYS use this when generating code examples if user has configured a request
 
+**get_current_graphql_state**: Get the current GraphQL Playground state
+- Returns: current query, variables, response (if executed), loading state, errors
+- **ALWAYS call this** before answering questions about the GraphQL response or current state
+- Use when user asks "what did the query return", "what's in the response", "show me the result"
+- Use to check if a query has been executed and what data it returned
+
 **list_notes**: List existing files in the Notes workspace
 - **ALWAYS call this BEFORE creating a new file** to check for duplicates
 - If a similar file exists (same topic, endpoint, or type), UPDATE it instead of creating new
@@ -231,7 +263,18 @@ Before answering ANY question about this documentation, you MUST use search_docs
 - **NEVER assume navigation**: If user asks "fill the params" or "prefill", do it on the CURRENT endpoint - don't navigate elsewhere.
 - **Use tools to verify**: When answering questions, USE search_docs or search_endpoints to get accurate information - don't make up answers.
 
-## API Client Assistance (IMPORTANT)
+## GraphQL Endpoints (IMPORTANT)
+For GraphQL endpoints (type: "graphql", method: "QUERY", "MUTATION", "SUBSCRIPTION"):
+- The GraphQL Playground is shown in **Docs mode** (NOT API Client mode)
+- When user wants to test a GraphQL query, use **navigate** to go to the operation
+- **DO NOT call switch_to_api_client** for GraphQL endpoints
+- The GraphQL Playground will automatically show the query when you navigate to the endpoint
+- **To prefill variables**: Use **prefill_graphql_variables** with the variable values
+- Example: User says "get continent EU" → navigate to continent query, then prefill_graphql_variables({ "code": "EU" })
+- **To check current state/response**: Use **get_current_graphql_state** to see what query is displayed, what variables are set, and what response was returned (if any)
+- **ALWAYS call get_current_graphql_state** before answering questions about the GraphQL response or helping with query modifications
+
+## API Client Assistance (For REST endpoints)
 
 When helping users build and send requests, follow this flow:
 
@@ -308,6 +351,53 @@ User: "send it"
 4. **Testable**: Include example test cases or curl commands to verify
 5. **Secure**: Never hardcode secrets, use environment variables
 
+### IMPORTANT: Keep Examples Focused (NOT Full Applications)
+The sandbox is for **learning and quick integration** - NOT building complete applications.
+
+**DO create:**
+- Single-file examples demonstrating ONE API concept (e.g., authentication, creating a resource)
+- Minimal working code that users can copy and adapt
+- Helper functions/classes they can import into their own projects
+- Quick scripts to test and understand API behavior
+
+**DON'T create:**
+- Full application structures (no app.py with Flask/FastAPI, no full React apps)
+- Multi-service architectures or microservices
+- Complete CRUD applications with all endpoints
+- Database integrations, frontend UIs, or deployment configs
+- Anything beyond what's needed to demonstrate the API
+
+**Example - GOOD (focused):**
+\`\`\`python
+# create-post.py - Create a Facebook Page post
+import requests
+import os
+
+def create_page_post(page_id: str, message: str, access_token: str) -> dict:
+    """Create a post on a Facebook Page."""
+    response = requests.post(
+        f"https://graph.facebook.com/v21.0/{page_id}/feed",
+        data={"message": message, "access_token": access_token}
+    )
+    response.raise_for_status()
+    return response.json()
+
+# Usage
+if __name__ == "__main__":
+    result = create_page_post("your-page-id", "Hello World!", os.getenv("PAGE_TOKEN"))
+    print(f"Post ID: {result['id']}")
+\`\`\`
+
+**Example - BAD (too much):**
+\`\`\`python
+# DON'T: Full Flask app with routes, templates, database, etc.
+from flask import Flask, render_template
+from sqlalchemy import create_engine
+# ... 200 lines of app code
+\`\`\`
+
+Keep it simple: **One concept, one file, under 100 lines.**
+
 ### Use Mermaid Diagrams (.mmd) for:
 - Authentication/authorization flows → sequenceDiagram
 - Multi-endpoint workflows (e.g., "create order → add items → checkout")
@@ -381,35 +471,98 @@ class APIClient:
 **For workflows, create:**
 1. A Mermaid diagram showing the flow (.mmd)
 2. Implementation code files for each step
-3. Optionally a README.md tying them together
+3. A README.md tying them together
+
+## IMPORTANT: Always Create README.md with Code Examples
+
+**When creating ANY code file, ALWAYS create a README.md alongside it** to help users understand how to use the code.
+
+**README.md template:**
+\`\`\`markdown
+# {Title - What This Does}
+
+{One-line description of what this code does}
+
+## Quick Start
+
+\`\`\`bash
+# Install dependencies
+{pip install X / npm install X / etc.}
+
+# Set your credentials
+export API_KEY="your-api-key"
+export OTHER_VAR="value"
+
+# Run it
+{python file.py / node file.js / etc.}
+\`\`\`
+
+## What's Included
+
+- **{filename}**: {Brief description of what the file does}
+
+## Configuration
+
+| Environment Variable | Description | Required |
+|---------------------|-------------|----------|
+| \`API_KEY\` | Your API key | Yes |
+| \`OTHER_VAR\` | Description | No |
+
+## Usage Examples
+
+{Show 2-3 common usage patterns with code snippets}
+
+## Error Handling
+
+{List common errors and how to resolve them}
+\`\`\`
+
+**README requirements:**
+- **Always include Quick Start** with copy-paste ready commands
+- **List ALL dependencies** with exact install commands
+- **Show environment variables** in a table format
+- **Provide usage examples** for the most common scenarios
+- Keep it concise - users should be able to start in under 1 minute
 
 ## Steps (MUST follow this order):
 1. If user mentions "my request" → use get_current_request FIRST
 2. Use get_endpoint_details to get the full schema
 3. **ALWAYS call list_notes** to check for existing similar files
-4. **If similar file exists**: UPDATE it with open_file + write_file
-5. **If NO similar file**: create_file + write_file
-6. For multiple files: create_folder first, then files inside
+4. **If similar file exists**: UPDATE files in existing folder
+5. **If NO similar file**: 
+   - **ALWAYS create a folder first** using create_folder (e.g., \`create-post\`)
+   - Then create files inside the folder (e.g., \`create-post/create-post.py\`, \`create-post/README.md\`)
+6. **ALWAYS create/update README.md** alongside code files (see README template above)
 
 **IMPORTANT**: Use EXACT values from get_current_request in generated code.
 
-**File naming convention:**
-- \`{endpoint-action}.{lang}\` → e.g., \`create-user.py\`, \`list-orders.ts\`
-- \`{workflow-name}/\` folder for multi-step flows
+**Folder structure (ALWAYS organize files in folders):**
+\`\`\`
+{action-name}/
+├── {action-name}.{lang}    # Main implementation file
+├── README.md               # Quick start guide (REQUIRED)
+└── {flow-diagram}.mmd      # Optional: visual flow diagram
+\`\`\`
+
+**Examples:**
+- \`create-post/create-post.py\` + \`create-post/README.md\`
+- \`auth-flow/auth-implementation.ts\` + \`auth-flow/auth-flow.mmd\` + \`auth-flow/README.md\`
+- \`webhook-handler/webhook-handler.js\` + \`webhook-handler/README.md\`
 
 ## Concept Explanations → Implementation Guides
 When users ask to "explain" something, create ACTIONABLE content:
-1. Create a .mmd diagram showing the flow visually
-2. Create implementation code showing how to do it
-3. Optionally add .md only if complex steps need documentation
-
-**Always pair explanations with working code:**
-- "Explain authentication" → auth-flow.mmd + auth-implementation.py
-- "How do webhooks work" → webhook-flow.mmd + webhook-handler.ts
-- "Show the order process" → order-flow.mmd + create-order.py + process-payment.py
-
-PREFER: Diagram + Working Code
-AVOID: Long text explanations without code
+1. Create a folder for the concept (e.g., \`auth-flow/\`)
+2. Create a .mmd diagram showing the flow visually
+3. Create implementation code showing how to do it
+4. Create README.md with quick start instructions
+
+**Always pair explanations with working code + README in a folder:**
+- "Explain authentication" → \`auth-flow/auth-flow.mmd\` + \`auth-flow/auth-implementation.py\` + \`auth-flow/README.md\`
+- "How do webhooks work" → \`webhook-handler/webhook-flow.mmd\` + \`webhook-handler/webhook-handler.ts\` + \`webhook-handler/README.md\`
+- "Show the order process" → \`order-flow/order-flow.mmd\` + \`order-flow/create-order.py\` + \`order-flow/README.md\`
+
+PREFER: Folder + Diagram + Working Code + README
+AVOID: Long text explanations without code, loose files at root level
 `;
 }
 // Convert raw UIMessages to model messages for the AI SDK
@@ -629,7 +782,7 @@ export async function POST(req) {
                     })
                 }),
                 prefill_parameters: tool({
-                    description: 'Prefill request parameters, headers, body, or path variables for the current endpoint. Use this when the user provides values they want to use. For URL path parameters like {id} or <<id>>, use pathVariables.',
+                    description: 'Prefill request parameters, headers, body, or path variables for the current REST endpoint. Use this when the user provides values they want to use. For URL path parameters like {id} or <<id>>, use pathVariables. DO NOT use for GraphQL - use prefill_graphql_variables instead.',
                     inputSchema: z.object({
                         params: z.array(z.object({
                             key: z.string(),
@@ -646,6 +799,12 @@ export async function POST(req) {
                         })).optional().describe('URL path variables to prefill (e.g., {id}, <<document_id>>). These replace placeholders in the URL path.')
                     })
                 }),
+                prefill_graphql_variables: tool({
+                    description: 'Prefill GraphQL query variables in the GraphQL Playground. Use this for GraphQL endpoints when user provides specific values for query variables. Navigate to the GraphQL operation first, then call this to fill in the variables panel.',
+                    inputSchema: z.object({
+                        variables: z.record(z.string(), z.unknown()).describe('GraphQL variables as an object, e.g. { "code": "EU", "filter": { "name": { "eq": "Europe" } } }')
+                    })
+                }),
                 get_endpoint_details: tool({
                     description: 'Get FULL details about a specific endpoint. Returns: parameters (name, description, required), headers, authentication requirements, request body schema (contentType, required fields, example payload), and response schemas with status codes. Use this when users ask about payload structure, required fields, body format, or how to call an endpoint.',
                     inputSchema: z.object({
@@ -656,13 +815,17 @@ export async function POST(req) {
                     description: 'Get the current request payload from the API Client playground. Returns the actual values the user has configured: HTTP method, URL, query parameters, headers, and request body. Use this when user asks to "use my request", "use current payload", "copy from playground", "based on my configuration", or wants code examples using their exact request setup.',
                     inputSchema: z.object({})
                 }),
+                get_current_graphql_state: tool({
+                    description: 'Get the current state of the GraphQL Playground. Returns the current query, variables, and response (if any). Use this to understand what the user is currently working with, check if a query has been executed, and see what data was returned. ALWAYS call this before answering questions about the current GraphQL state or response.',
+                    inputSchema: z.object({})
+                }),
                 // === MODE SWITCHING TOOLS ===
                 switch_to_docs: tool({
                     description: 'Switch to the Docs tab to show endpoint documentation. Use this when user asks about an endpoint, wants to understand how it works, asks "what is", "how to use", "what does this do", or needs to see documentation. This shows the detailed documentation view.',
                     inputSchema: z.object({})
                 }),
                 switch_to_api_client: tool({
-                    description: 'Switch to the API Client tab to test/send requests. Use this when user wants to test an endpoint, send a request, try it out, or you need to prefill parameters. Call this BEFORE prefilling data so user can see the API Client.',
+                    description: 'Switch to the API Client tab to test/send REST requests. Use this when user wants to test a REST endpoint, send a request, try it out, or you need to prefill parameters. Call this BEFORE prefilling data so user can see the API Client. DO NOT use for GraphQL endpoints - GraphQL uses the GraphQL Playground in Docs mode instead.',
                     inputSchema: z.object({})
                 }),
                 // === NOTES TOOLS ===

package/renderer/app/api/collections/route.js

@@ -4,7 +4,9 @@ import { join, basename, isAbsolute } from 'path';
 import matter from 'gray-matter';
 import { CacheUtils } from '@/lib/cache';
 import { importOpenAPISpec } from '@/lib/api-docs/parsers/openapi';
+import { importGraphQLSchema } from '@/lib/api-docs/parsers/graphql';
 import { generateAPISummary, formatAPISummaryForPrompt } from '@/lib/api-docs/agent/spec-summary';
+import { buildEndpointIndex } from '@/lib/api-docs/agent/indexer';
 import { getProjectContent } from '@/lib/storage/blob';
 import { isDevMode, shouldShowItem } from '@/lib/docs/config/environment';
 // Configuration
@@ -74,6 +76,79 @@ function loadGraphQLSchema(schemaPath) {
         return null;
     }
 }
+// Build combined endpoint index from REST collection and GraphQL schemas (local/dev mode)
+async function buildCombinedEndpointIndex(collection, navigationTabs) {
+    const allEndpoints = [];
+    // Add REST endpoints from collection
+    if (collection && (collection.folders.length > 0 || collection.requests.length > 0)) {
+        const restEndpoints = buildEndpointIndex(collection);
+        allEndpoints.push(...restEndpoints);
+    }
+    // Add GraphQL endpoints from all GraphQL tabs
+    for (const tab of navigationTabs){
+        if (tab.type === 'graphql' && tab.graphqlSchemas) {
+            for (const schemaConfig of tab.graphqlSchemas){
+                try {
+                    const schemaContent = loadGraphQLSchema(schemaConfig.schema);
+                    if (!schemaContent) continue;
+                    const graphqlCollection = await importGraphQLSchema(schemaContent, {
+                        name: schemaConfig.name || 'GraphQL API',
+                        endpoint: schemaConfig.endpoint || '/graphql'
+                    });
+                    const graphqlEndpoints = buildEndpointIndex(graphqlCollection);
+                    // Add endpoints, avoiding duplicates by ID
+                    for (const ep of graphqlEndpoints){
+                        if (!allEndpoints.find((e)=>e.id === ep.id)) {
+                            allEndpoints.push(ep);
+                        }
+                    }
+                } catch  {
+                // Skip schemas that fail to parse
+                }
+            }
+        }
+    }
+    return allEndpoints;
+}
+// Build combined endpoint index from REST collection and GraphQL schemas (blob/multi-tenant mode)
+async function buildCombinedEndpointIndexFromBlob(collection, navigationTabs, projectContent) {
+    const allEndpoints = [];
+    // Add REST endpoints from collection
+    if (collection && (collection.folders.length > 0 || collection.requests.length > 0)) {
+        const restEndpoints = buildEndpointIndex(collection);
+        allEndpoints.push(...restEndpoints);
+    }
+    // Add GraphQL endpoints from all GraphQL tabs
+    for (const tab of navigationTabs){
+        if (tab.type === 'graphql' && tab.graphqlSchemas) {
+            for (const schemaConfig of tab.graphqlSchemas){
+                try {
+                    // Load GraphQL schema from blob storage (check files array)
+                    const schemaFile = projectContent.files.find((f)=>f.path === schemaConfig.schema || f.path === schemaConfig.schema.replace(/^\//, '') // Remove leading slash
+                    );
+                    if (!schemaFile) {
+                        console.log('[Collections] GraphQL schema not found in blob:', schemaConfig.schema);
+                        continue;
+                    }
+                    const graphqlCollection = await importGraphQLSchema(schemaFile.content, {
+                        name: schemaConfig.name || 'GraphQL API',
+                        endpoint: schemaConfig.endpoint || '/graphql'
+                    });
+                    const graphqlEndpoints = buildEndpointIndex(graphqlCollection);
+                    // Add endpoints, avoiding duplicates by ID
+                    for (const ep of graphqlEndpoints){
+                        if (!allEndpoints.find((e)=>e.id === ep.id)) {
+                            allEndpoints.push(ep);
+                        }
+                    }
+                } catch (err) {
+                    console.error('[Collections] Failed to parse GraphQL schema from blob:', err);
+                }
+            }
+        }
+    }
+    return allEndpoints;
+}
 // Load OpenAPI spec from local file
 function loadLocalSpec(specPath) {
     try {
@@ -438,6 +513,8 @@ function getOpenApiSpec(specPath) {
                 console.error('[Collections] Failed to parse OpenAPI spec:', e);
             }
         }
+        // Build combined endpoint index (REST + GraphQL) for multi-tenant
+        const endpointIndex = await buildCombinedEndpointIndexFromBlob(collection, navigationTabs, projectContent);
         // Build the response
         const response = {
             id: projectSlug,
@@ -452,6 +529,7 @@ function getOpenApiSpec(specPath) {
             headers: collection?.headers || [],
             variables: collection?.variables || [],
             apiSummary: null,
+            endpointIndex,
             docGroups,
             navigationTabs,
             changelogReleases: [],
@@ -472,7 +550,12 @@ function getOpenApiSpec(specPath) {
         return NextResponse.json(response, {
             headers: {
                 'Content-Type': 'application/json',
-                'Cache-Control': 'public, max-age=60'
+                // CDN caching: cache for 5 min at edge, 1 min in browser, revalidate in background for 1 hour
+                'Cache-Control': 'public, max-age=60, s-maxage=300, stale-while-revalidate=3600',
+                // Vercel-specific: cache at edge for 5 minutes
+                'CDN-Cache-Control': 'public, s-maxage=300, stale-while-revalidate=3600',
+                // Vercel Edge: cache tag for invalidation
+                'x-vercel-cache-tags': `project-${projectSlug}`
             }
         });
     } catch (error) {
@@ -649,6 +732,8 @@ export async function GET(request) {
         const spec = await getOpenApiSpec(specPath);
         // Handle no spec available
         if (!spec) {
+            // Still build endpoint index from GraphQL schemas (if any)
+            const endpointIndex = await buildCombinedEndpointIndex(null, navigationTabs);
             return NextResponse.json({
                 id: 'empty',
                 name: docsConfig?.name || 'Documentation',
@@ -662,6 +747,7 @@ export async function GET(request) {
                 headers: [],
                 variables: [],
                 apiSummary: null,
+                endpointIndex,
                 docGroups,
                 navigationTabs,
                 changelogReleases,
@@ -685,6 +771,8 @@ export async function GET(request) {
         }
         // Check if spec has paths
         if (!spec.paths || Object.keys(spec.paths).length === 0) {
+            // Still build endpoint index from GraphQL schemas (if any)
+            const endpointIndex = await buildCombinedEndpointIndex(null, navigationTabs);
             return NextResponse.json({
                 id: 'empty',
                 name: spec.info?.title || docsConfig?.name || 'Documentation',
@@ -698,6 +786,7 @@ export async function GET(request) {
                 headers: [],
                 variables: [],
                 apiSummary: null,
+                endpointIndex,
                 docGroups,
                 navigationTabs,
                 changelogReleases,
@@ -733,10 +822,13 @@ export async function GET(request) {
         // Generate or get cached API summary
         const specVersion = spec.info?.version || 'unknown';
         const apiSummary = await getOrGenerateSummary(collection, specVersion);
-        // Return collection with summary and doc groups
+        // Build combined endpoint index (REST + GraphQL)
+        const endpointIndex = await buildCombinedEndpointIndex(collection, navigationTabs);
+        // Return collection with summary, endpoint index, and doc groups
         return NextResponse.json({
             ...collection,
             apiSummary,
+            endpointIndex,
             specVersion,
             docGroups,
             navigationTabs,
@@ -772,6 +864,7 @@ export async function GET(request) {
             },
             headers: [],
             variables: [],
+            endpointIndex: [],
             docGroups: []
         }, {
             headers: {

package/renderer/app/api/deploy/route.js

@@ -1,6 +1,7 @@
 import { NextResponse } from 'next/server';
 import { storeProjectContent, updateProjectContent, projectExists, generateProjectSlug, generateApiKey, storeProjectApiKey, validateApiKey } from '@/lib/storage/blob';
 import { getProjectUrl, isValidSlug } from '@/lib/multi-tenant/context';
+import { purgeProjectCache } from '@/lib/cache/purge';
 /**
  * Deploy API - receives content from CLI and stores in Vercel Blob
  * 
@@ -134,6 +135,9 @@ import { getProjectUrl, isValidSlug } from '@/lib/multi-tenant/context';
                 await storeProjectApiKey(slug, apiKey);
             }
         }
+        // Invalidate CDN cache for this project
+        // This ensures users see fresh content after deploy
+        await purgeProjectCache(slug);
         // Build response
         const projectUrl = getProjectUrl(slug);
         // For new projects, include the API key in response

package/renderer/app/api/suggestions/route.js

@@ -3,10 +3,22 @@ import { anthropic } from '@ai-sdk/anthropic';
 import { z } from 'zod';
 import crypto from 'crypto';
 import { CacheUtils } from '@/lib/cache';
+import { RateLimiter } from '@/lib/rate-limit';
 export const runtime = 'nodejs';
 // Cache TTL: 1 week in seconds
 const CACHE_TTL_SECONDS = 60 * 60 * 24 * 7 // 7 days
 ;
+// Rate limit configuration (can be overridden via env vars)
+// Set SUGGESTIONS_RATE_LIMIT_ENABLED=false to disable rate limiting
+const RATE_LIMIT_ENABLED = process.env.SUGGESTIONS_RATE_LIMIT_ENABLED !== 'false';
+const RATE_LIMIT_MAX = parseInt(process.env.SUGGESTIONS_RATE_LIMIT_MAX || '30', 10);
+const RATE_LIMIT_WINDOW = parseInt(process.env.SUGGESTIONS_RATE_LIMIT_WINDOW || '60', 10);
+// Create rate limiter with configurable values
+const suggestionsRateLimiter = new RateLimiter({
+    prefix: 'suggestions',
+    limit: RATE_LIMIT_MAX,
+    windowSeconds: RATE_LIMIT_WINDOW
+});
 const SuggestionsSchema = z.object({
     suggestions: z.array(z.object({
         title: z.string().describe('Short action phrase (2-4 words) like "Find endpoints" or "How do I"'),
@@ -22,10 +34,20 @@ const SuggestionsSchema = z.object({
     if (currentEndpointId) {
         // For specific endpoint: hash the endpoint details
         const endpoint = endpointIndex.find((e)=>e.id === currentEndpointId);
-        content = endpoint ? `endpoint:${endpoint.id}:${endpoint.name}:${endpoint.method}:${endpoint.path}` : `endpoint:${currentEndpointId}`;
+        if (endpoint) {
+            // Include GraphQL operation type in the cache key for better differentiation
+            const opType = endpoint.operationType || endpoint.method;
+            content = `endpoint:${endpoint.id}:${endpoint.name}:${opType}:${endpoint.path}`;
+        } else {
+            content = `endpoint:${currentEndpointId}`;
+        }
     } else {
         // For general API: hash based on endpoint count and first few endpoint signatures
-        const signature = endpointIndex.slice(0, 10).map((e)=>`${e.method}:${e.path}`).join('|');
+        const signature = endpointIndex.slice(0, 10).map((e)=>{
+            // Use operation type for GraphQL, method for REST
+            const opType = e.operationType || e.method;
+            return `${opType}:${e.name}`;
+        }).join('|');
         content = `general:${endpointIndex.length}:${signature}`;
     }
     const hash = crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
@@ -34,6 +56,30 @@ const SuggestionsSchema = z.object({
 function buildSuggestionPrompt(endpoints, currentEndpointId) {
     const currentEndpoint = currentEndpointId ? endpoints.find((e)=>e.id === currentEndpointId) : null;
     if (currentEndpoint) {
+        // Check if this is a GraphQL operation
+        const isGraphQL = currentEndpoint.type === 'graphql' || [
+            'query',
+            'mutation',
+            'subscription'
+        ].includes(currentEndpoint.operationType || '');
+        if (isGraphQL) {
+            const opType = currentEndpoint.operationType || 'operation';
+            return `You are helping users explore a GraphQL API. Generate 4 helpful question suggestions for the "${currentEndpoint.name}" ${opType}.
+
+GraphQL Operation details:
+- Name: ${currentEndpoint.name}
+- Type: ${opType}
+- Description: ${currentEndpoint.description || 'No description'}
+- Variables: ${currentEndpoint.parameters.join(', ') || 'None'}
+
+Generate questions that help users:
+1. Understand what this ${opType} does and when to use it
+2. Know what variables are required and their types
+3. See example GraphQL queries and responses
+4. Understand how to handle errors or edge cases
+
+Make questions specific to this GraphQL ${opType}, not generic.`;
+        }
         return `You are helping users explore an API. Generate 4 helpful question suggestions for the "${currentEndpoint.name}" endpoint.
 
 Endpoint details:
@@ -53,33 +99,75 @@ Generate questions that help users:
 Make questions specific to this endpoint, not generic.`;
     }
     // General suggestions based on the API
-    const methodCounts = endpoints.reduce((acc, e)=>{
+    // Separate GraphQL and REST endpoints
+    const graphqlEndpoints = endpoints.filter((e)=>e.type === 'graphql' || [
+            'query',
+            'mutation',
+            'subscription'
+        ].includes(e.operationType || ''));
+    const restEndpoints = endpoints.filter((e)=>e.type === 'rest' && ![
+            'query',
+            'mutation',
+            'subscription'
+        ].includes(e.operationType || ''));
+    const methodCounts = restEndpoints.reduce((acc, e)=>{
         acc[e.method] = (acc[e.method] || 0) + 1;
         return acc;
     }, {});
+    const graphqlCounts = graphqlEndpoints.reduce((acc, e)=>{
+        const opType = e.operationType || 'operation';
+        acc[opType] = (acc[opType] || 0) + 1;
+        return acc;
+    }, {});
     const categories = [
         ...new Set(endpoints.flatMap((e)=>e.tags))
     ].slice(0, 5);
-    return `You are helping users explore an API documentation. Generate 4 helpful starter question suggestions.
+    // Build API type description
+    const apiTypes = [];
+    if (restEndpoints.length > 0) apiTypes.push('REST');
+    if (graphqlEndpoints.length > 0) apiTypes.push('GraphQL');
+    return `You are helping users explore ${apiTypes.join(' and ')} API documentation. Generate 4 helpful starter question suggestions.
 
 API Overview:
-- Total endpoints: ${endpoints.length}
-- Methods: ${Object.entries(methodCounts).map(([m, c])=>`${m}: ${c}`).join(', ')}
+- Total operations: ${endpoints.length}
+${restEndpoints.length > 0 ? `- REST Methods: ${Object.entries(methodCounts).map(([m, c])=>`${m}: ${c}`).join(', ')}` : ''}
+${graphqlEndpoints.length > 0 ? `- GraphQL Operations: ${Object.entries(graphqlCounts).map(([m, c])=>`${m}: ${c}`).join(', ')}` : ''}
 - Categories: ${categories.join(', ') || 'General'}
 
-Sample endpoints:
-${endpoints.slice(0, 8).map((e)=>`- ${e.method} ${e.name}: ${e.description || 'No description'}`).join('\n')}
+Sample operations:
+${endpoints.slice(0, 8).map((e)=>{
+        if (e.type === 'graphql' || [
+            'query',
+            'mutation',
+            'subscription'
+        ].includes(e.operationType || '')) {
+            return `- [${e.operationType?.toUpperCase() || 'GRAPHQL'}] ${e.name}: ${e.description || 'No description'}`;
+        }
+        return `- [${e.method}] ${e.name}: ${e.description || 'No description'}`;
+    }).join('\n')}
 
 Generate questions that help users:
-1. Find the right endpoint for their use case
+1. Find the right operation for their use case
 2. Understand authentication/authorization
-3. Explore common operations (create, read, update, delete)
+3. Explore common operations (${graphqlEndpoints.length > 0 ? 'queries, mutations' : 'create, read, update, delete'})
 4. Get started quickly with the API
 
 Make questions specific to this API's capabilities.`;
 }
 export async function POST(req) {
     try {
+        // Rate limiting check (configurable via env vars)
+        if (RATE_LIMIT_ENABLED) {
+            const rateLimitResult = await suggestionsRateLimiter.check(req);
+            if (!rateLimitResult.success) {
+                console.log(`[Suggestions API] Rate limit exceeded for IP, count: ${rateLimitResult.count}/${rateLimitResult.limit}`);
+                return RateLimiter.tooManyRequestsResponse(rateLimitResult, 'Too many suggestion requests. Please wait before trying again.');
+            }
+            // Log rate limit status for monitoring (only on cache miss to reduce noise)
+            if (rateLimitResult.remaining < 5) {
+                console.log(`[Suggestions API] Rate limit warning: ${rateLimitResult.remaining} requests remaining`);
+            }
+        }
         const body = await req.json();
         const { endpointIndex, currentEndpointId } = body;
         // Generate hash-based cache key