@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/server/routes/memoryRoutes.js

@@ -0,0 +1,350 @@
+/**
+ * Memory Routes
+ * Endpoints for conversation memory management
+ */
+import { createErrorResponse, IdParamSchema, SessionIdParamSchema, validateParams, } from "../utils/validation.js";
+/**
+ * Handler: Get messages for a session
+ */
+async function handleGetSessionMessages(ctx) {
+    // Validate path params
+    const paramValidation = validateParams(IdParamSchema, ctx.params, ctx.requestId);
+    if (!paramValidation.success) {
+        return paramValidation.error;
+    }
+    const { id: sessionId } = paramValidation.data;
+    // Parse query params for pagination
+    const limitParam = ctx.query.limit ? parseInt(ctx.query.limit, 10) : 50;
+    const offsetParam = ctx.query.offset ? parseInt(ctx.query.offset, 10) : 0;
+    // Validate pagination params
+    const limit = isNaN(limitParam) || limitParam < 1 ? 50 : Math.min(limitParam, 100);
+    const offset = isNaN(offsetParam) || offsetParam < 0 ? 0 : offsetParam;
+    const memory = ctx.neurolink.conversationMemory;
+    if (!memory) {
+        return createErrorResponse("MEMORY_UNAVAILABLE", "Conversation memory not available", undefined, ctx.requestId);
+    }
+    try {
+        let messages = [];
+        // Handle Redis memory manager (has getUserSessionHistory)
+        if ("getUserSessionHistory" in memory) {
+            // For Redis, we need a userId - check query params or use a default
+            const userId = ctx.query.userId || "default";
+            const sessionMessages = await memory.getUserSessionHistory(userId, sessionId);
+            if (sessionMessages === null) {
+                return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
+            }
+            messages = sessionMessages;
+        }
+        // Handle in-memory manager (has getSession)
+        else if ("getSession" in memory) {
+            const session = memory.getSession(sessionId);
+            if (!session) {
+                return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
+            }
+            messages = session.messages;
+        }
+        // Fallback: try buildContextMessages if available
+        else if ("buildContextMessages" in memory) {
+            messages = await memory.buildContextMessages(sessionId);
+            // If no messages, session might not exist
+            if (messages.length === 0) {
+                return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found or has no messages`, undefined, ctx.requestId);
+            }
+        }
+        const total = messages.length;
+        const paginatedMessages = messages.slice(offset, offset + limit);
+        return {
+            sessionId,
+            messages: paginatedMessages,
+            total,
+            limit,
+            offset,
+            metadata: {
+                timestamp: new Date().toISOString(),
+                requestId: ctx.requestId,
+            },
+        };
+    }
+    catch (error) {
+        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to get session messages", undefined, ctx.requestId);
+    }
+}
+/**
+ * Handler: Get session by ID
+ */
+async function handleGetSession(ctx) {
+    // Validate path params
+    const paramValidation = validateParams(IdParamSchema, ctx.params, ctx.requestId);
+    if (!paramValidation.success) {
+        return paramValidation.error;
+    }
+    const { id: sessionId } = paramValidation.data;
+    const memory = ctx.neurolink.conversationMemory;
+    if (!memory) {
+        return createErrorResponse("MEMORY_UNAVAILABLE", "Conversation memory not available", undefined, ctx.requestId);
+    }
+    try {
+        // Handle Redis memory manager (has getUserSessionObject or getUserSessionMetadata)
+        if ("getUserSessionObject" in memory) {
+            // For Redis, we need a userId - check query params or use a default
+            const userId = ctx.query.userId || "default";
+            const sessionObject = await memory.getUserSessionObject(userId, sessionId);
+            if (sessionObject === null) {
+                return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
+            }
+            return {
+                session: sessionObject,
+                metadata: {
+                    timestamp: new Date().toISOString(),
+                    requestId: ctx.requestId,
+                },
+            };
+        }
+        // Handle in-memory manager (has getSession)
+        else if ("getSession" in memory) {
+            const session = memory.getSession(sessionId);
+            if (!session) {
+                return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
+            }
+            return {
+                session,
+                metadata: {
+                    timestamp: new Date().toISOString(),
+                    requestId: ctx.requestId,
+                },
+            };
+        }
+        return createErrorResponse("MEMORY_ERROR", "Session retrieval not supported for this memory type", undefined, ctx.requestId);
+    }
+    catch (error) {
+        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to get session", undefined, ctx.requestId);
+    }
+}
+/**
+ * Handler: List all conversation sessions
+ */
+async function handleListSessions(ctx) {
+    // Parse query params
+    const userId = ctx.query.userId;
+    const limitParam = ctx.query.limit ? parseInt(ctx.query.limit, 10) : 50;
+    const offsetParam = ctx.query.offset ? parseInt(ctx.query.offset, 10) : 0;
+    // Validate pagination params
+    const limit = isNaN(limitParam) || limitParam < 1 ? 50 : Math.min(limitParam, 100);
+    const offset = isNaN(offsetParam) || offsetParam < 0 ? 0 : offsetParam;
+    const memory = ctx.neurolink.conversationMemory;
+    if (!memory) {
+        return createErrorResponse("MEMORY_UNAVAILABLE", "Conversation memory not available", undefined, ctx.requestId);
+    }
+    try {
+        let sessions = [];
+        // Handle Redis memory manager (has getUserAllSessionsHistory or getUserSessions)
+        if ("getUserAllSessionsHistory" in memory && userId) {
+            sessions = await memory.getUserAllSessionsHistory(userId);
+        }
+        else if ("getUserSessions" in memory && userId) {
+            // Get session IDs and then fetch metadata for each
+            const sessionIds = await memory.getUserSessions(userId);
+            // If we can get metadata, do so
+            if ("getUserSessionMetadata" in memory) {
+                const metadataPromises = sessionIds.map((id) => memory.getUserSessionMetadata(userId, id));
+                const metadataResults = await Promise.all(metadataPromises);
+                sessions = metadataResults.filter((m) => m !== null);
+            }
+            else {
+                // Just return session IDs as basic objects
+                sessions = sessionIds.map((id) => ({ id }));
+            }
+        }
+        // Handle in-memory manager - iterate over internal sessions Map
+        else if ("getStats" in memory) {
+            // For in-memory, we can use getSession to check if sessions exist
+            // but we need to know the session IDs first. The in-memory manager
+            // doesn't expose a listSessions method, so we return stats info instead.
+            const stats = await memory.getStats?.();
+            return {
+                sessions: [],
+                total: stats?.totalSessions || 0,
+                limit,
+                offset,
+                message: "Session listing not fully supported for in-memory storage. Use /stats endpoint for session counts.",
+                metadata: {
+                    timestamp: new Date().toISOString(),
+                    requestId: ctx.requestId,
+                },
+            };
+        }
+        const total = sessions.length;
+        const paginatedSessions = sessions.slice(offset, offset + limit);
+        return {
+            sessions: paginatedSessions,
+            total,
+            limit,
+            offset,
+            metadata: {
+                timestamp: new Date().toISOString(),
+                requestId: ctx.requestId,
+            },
+        };
+    }
+    catch (error) {
+        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to list sessions", undefined, ctx.requestId);
+    }
+}
+/**
+ * Handler: Get memory statistics
+ */
+async function handleGetStats(ctx) {
+    const memory = ctx.neurolink.conversationMemory;
+    if (!memory) {
+        return createErrorResponse("MEMORY_UNAVAILABLE", "Conversation memory not available", undefined, ctx.requestId);
+    }
+    try {
+        // Get memory statistics if available
+        const stats = await memory.getStats?.();
+        return {
+            available: true,
+            type: memory.constructor.name,
+            stats: stats || {
+                message: "Statistics not available for this memory type",
+            },
+            timestamp: new Date().toISOString(),
+        };
+    }
+    catch (error) {
+        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to get statistics", undefined, ctx.requestId);
+    }
+}
+/**
+ * Handler: Clear a conversation session
+ */
+async function handleClearSession(ctx) {
+    // Validate params
+    const paramValidation = validateParams(SessionIdParamSchema, ctx.params, ctx.requestId);
+    if (!paramValidation.success) {
+        return paramValidation.error;
+    }
+    const { sessionId } = paramValidation.data;
+    const memory = ctx.neurolink.conversationMemory;
+    if (!memory) {
+        return createErrorResponse("MEMORY_UNAVAILABLE", "Conversation memory not available", undefined, ctx.requestId);
+    }
+    try {
+        // Use clearSession for ConversationMemoryManager
+        const cleared = await memory.clearSession?.(sessionId);
+        if (cleared === false) {
+            return createErrorResponse("SESSION_NOT_FOUND", `Session '${sessionId}' not found`, undefined, ctx.requestId);
+        }
+        return {
+            success: true,
+            sessionId,
+            message: "Session cleared successfully",
+            metadata: {
+                timestamp: new Date().toISOString(),
+                requestId: ctx.requestId,
+            },
+        };
+    }
+    catch (error) {
+        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to clear session", undefined, ctx.requestId);
+    }
+}
+/**
+ * Handler: Clear all conversation sessions
+ */
+async function handleClearAllSessions(ctx) {
+    const memory = ctx.neurolink.conversationMemory;
+    if (!memory) {
+        return createErrorResponse("MEMORY_UNAVAILABLE", "Conversation memory not available", undefined, ctx.requestId);
+    }
+    try {
+        // Use clearAllSessions for ConversationMemoryManager
+        await memory.clearAllSessions?.();
+        return {
+            success: true,
+            message: "All sessions cleared successfully",
+            metadata: {
+                timestamp: new Date().toISOString(),
+                requestId: ctx.requestId,
+            },
+        };
+    }
+    catch (error) {
+        return createErrorResponse("MEMORY_ERROR", error instanceof Error ? error.message : "Failed to clear sessions", undefined, ctx.requestId);
+    }
+}
+/**
+ * Handler: Check memory system health
+ */
+async function handleMemoryHealth(ctx) {
+    const memory = ctx.neurolink.conversationMemory;
+    return {
+        available: !!memory,
+        type: memory?.constructor.name || "none",
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Create memory management routes
+ * Note: These routes provide a simplified interface to conversation memory.
+ * The actual implementation depends on the memory manager type (ConversationMemoryManager or RedisConversationMemoryManager).
+ */
+export function createMemoryRoutes(basePath = "/api") {
+    return {
+        prefix: `${basePath}/memory`,
+        routes: [
+            // Route order matters - most specific routes first
+            // GET /api/memory/sessions/:id/messages - Get messages for a session (most specific)
+            {
+                method: "GET",
+                path: `${basePath}/memory/sessions/:id/messages`,
+                handler: handleGetSessionMessages,
+                description: "Get messages for a session",
+                tags: ["memory"],
+            },
+            // GET /api/memory/sessions/:id - Get session by ID
+            {
+                method: "GET",
+                path: `${basePath}/memory/sessions/:id`,
+                handler: handleGetSession,
+                description: "Get session by ID",
+                tags: ["memory"],
+            },
+            // GET /api/memory/sessions - List all conversation sessions
+            {
+                method: "GET",
+                path: `${basePath}/memory/sessions`,
+                handler: handleListSessions,
+                description: "List all conversation sessions",
+                tags: ["memory"],
+            },
+            {
+                method: "GET",
+                path: `${basePath}/memory/stats`,
+                handler: handleGetStats,
+                description: "Get memory statistics",
+                tags: ["memory"],
+            },
+            {
+                method: "DELETE",
+                path: `${basePath}/memory/sessions/:sessionId`,
+                handler: handleClearSession,
+                description: "Clear a conversation session",
+                tags: ["memory"],
+            },
+            {
+                method: "DELETE",
+                path: `${basePath}/memory/sessions`,
+                handler: handleClearAllSessions,
+                description: "Clear all conversation sessions",
+                tags: ["memory"],
+            },
+            {
+                method: "GET",
+                path: `${basePath}/memory/health`,
+                handler: handleMemoryHealth,
+                description: "Check memory system health",
+                tags: ["memory", "health"],
+            },
+        ],
+    };
+}

package/dist/client/server/routes/openApiRoutes.js

@@ -0,0 +1,126 @@
+/**
+ * OpenAPI Routes
+ * Endpoints for OpenAPI specification and documentation
+ */
+import { logger } from "../../utils/logger.js";
+import { OpenAPIGenerator } from "../openapi/generator.js";
+/**
+ * Create OpenAPI documentation routes
+ *
+ * Generates three endpoints for API documentation:
+ * - GET /api/openapi.json - OpenAPI 3.1 specification in JSON format
+ * - GET /api/openapi.yaml - OpenAPI 3.1 specification in YAML format
+ * - GET /api/docs - Interactive Swagger UI documentation
+ *
+ * IMPORTANT: The `getRoutes` callback is required to document your custom routes.
+ * If not provided, the OpenAPI spec will only include default endpoint definitions.
+ *
+ * @param basePath - Base path for API routes (default: "/api")
+ * @param getRoutes - Callback to get registered routes for the OpenAPI spec.
+ *                    This callback is invoked at request time, so routes registered
+ *                    after creating the OpenAPI route group will be included.
+ *                    If not provided, the generator will use default endpoint definitions.
+ * @returns RouteGroup containing OpenAPI documentation endpoints
+ *
+ * @example
+ * ```typescript
+ * // RECOMMENDED: Use registerAllRoutes which automatically binds getRoutes
+ * registerAllRoutes(server, "/api", { enableSwagger: true });
+ *
+ * // Or manually provide the routes callback
+ * const openApiRoutes = createOpenApiRoutes("/api", () => server.listRoutes());
+ * server.registerRouteGroup(openApiRoutes);
+ * ```
+ */
+export function createOpenApiRoutes(basePath = "/api", getRoutes) {
+    // Log a warning if getRoutes is not provided at creation time
+    if (!getRoutes) {
+        logger.debug("[OpenAPI] createOpenApiRoutes called without getRoutes callback. " +
+            "Custom routes will not be documented in the OpenAPI spec.");
+    }
+    return {
+        prefix: `${basePath}/openapi`,
+        routes: [
+            {
+                method: "GET",
+                path: `${basePath}/openapi.json`,
+                handler: async () => {
+                    const routes = getRoutes?.() ?? [];
+                    if (!getRoutes) {
+                        logger.warn("[OpenAPI] No getRoutes callback provided. OpenAPI spec will use default endpoint definitions. " +
+                            "Use registerAllRoutes(server, basePath, { enableSwagger: true }) to automatically include your routes.");
+                    }
+                    else if (routes.length === 0) {
+                        logger.debug("[OpenAPI] getRoutes returned empty array. No custom routes will be documented.");
+                    }
+                    const generator = new OpenAPIGenerator({
+                        basePath,
+                        routes,
+                    });
+                    return generator.generate();
+                },
+                description: "Get OpenAPI specification as JSON",
+                tags: ["openapi", "documentation"],
+            },
+            {
+                method: "GET",
+                path: `${basePath}/openapi.yaml`,
+                handler: async () => {
+                    const routes = getRoutes?.() ?? [];
+                    if (!getRoutes) {
+                        logger.warn("[OpenAPI] No getRoutes callback provided. OpenAPI spec will use default endpoint definitions. " +
+                            "Use registerAllRoutes(server, basePath, { enableSwagger: true }) to automatically include your routes.");
+                    }
+                    else if (routes.length === 0) {
+                        logger.debug("[OpenAPI] getRoutes returned empty array. No custom routes will be documented.");
+                    }
+                    const generator = new OpenAPIGenerator({
+                        basePath,
+                        routes,
+                    });
+                    return {
+                        _raw: true,
+                        contentType: "text/yaml",
+                        body: generator.toYAML(),
+                    };
+                },
+                description: "Get OpenAPI specification as YAML",
+                tags: ["openapi", "documentation"],
+            },
+            {
+                method: "GET",
+                path: `${basePath}/docs`,
+                handler: async () => {
+                    const html = `<!DOCTYPE html>
+<html>
+<head>
+  <title>NeuroLink API Documentation</title>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css">
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    SwaggerUIBundle({
+      url: "${basePath}/openapi.json",
+      dom_id: '#swagger-ui',
+      presets: [SwaggerUIBundle.presets.apis],
+      layout: "BaseLayout"
+    });
+  </script>
+</body>
+</html>`;
+                    return {
+                        _raw: true,
+                        contentType: "text/html",
+                        body: html,
+                    };
+                },
+                description: "Swagger UI documentation page",
+                tags: ["openapi", "documentation"],
+            },
+        ],
+    };
+}

package/dist/client/server/routes/toolRoutes.js

@@ -0,0 +1,199 @@
+/**
+ * Tool Routes
+ * Endpoints for tool listing, discovery, and execution
+ */
+import { createErrorResponse, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, validateParams, validateRequest, } from "../utils/validation.js";
+/**
+ * Create tool routes
+ */
+export function createToolRoutes(basePath = "/api") {
+    return {
+        prefix: `${basePath}/tools`,
+        // IMPORTANT: Route ordering matters for proper matching!
+        // Routes are matched in order, so literal/exact paths MUST come before
+        // parameterized paths (e.g., :name) to prevent the parameter from
+        // matching literal path segments like "search" or "execute".
+        // Order: exact paths first, then paths with nested segments, then parameterized paths last.
+        routes: [
+            // 1. GET /api/tools - List all tools (exact match, must be first)
+            {
+                method: "GET",
+                path: `${basePath}/tools`,
+                handler: async (ctx) => {
+                    const tools = await ctx.toolRegistry.listTools();
+                    return {
+                        tools: tools.map((tool) => ({
+                            name: tool.name,
+                            description: tool.description,
+                            inputSchema: tool.inputSchema,
+                            source: tool.source || "built-in",
+                        })),
+                        total: tools.length,
+                    };
+                },
+                description: "List all available tools",
+                tags: ["tools"],
+            },
+            // 2. GET /api/tools/search - Search tools (literal path segment)
+            {
+                method: "GET",
+                path: `${basePath}/tools/search`,
+                handler: async (ctx) => {
+                    const { q, source, limit } = ctx.query;
+                    const tools = await ctx.toolRegistry.listTools();
+                    let filtered = tools;
+                    // Filter by search query
+                    if (q) {
+                        const query = q.toLowerCase();
+                        filtered = filtered.filter((tool) => tool.name.toLowerCase().includes(query) ||
+                            (tool.description &&
+                                tool.description.toLowerCase().includes(query)));
+                    }
+                    // Filter by source
+                    if (source) {
+                        filtered = filtered.filter((tool) => (tool.source || "built-in") === source);
+                    }
+                    // Apply limit
+                    const maxResults = limit ? parseInt(limit, 10) : 50;
+                    filtered = filtered.slice(0, maxResults);
+                    return {
+                        tools: filtered.map((tool) => ({
+                            name: tool.name,
+                            description: tool.description,
+                            source: tool.source || "built-in",
+                        })),
+                        total: filtered.length,
+                        query: q || null,
+                    };
+                },
+                description: "Search tools by name or description",
+                tags: ["tools"],
+            },
+            // 3. POST /api/tools/execute - Execute tool by name in body (literal path segment)
+            {
+                method: "POST",
+                path: `${basePath}/tools/execute`,
+                handler: async (ctx) => {
+                    // Validate request body
+                    const validation = validateRequest(ToolExecuteRequestSchema, ctx.body, ctx.requestId);
+                    if (!validation.success) {
+                        return validation.error;
+                    }
+                    const request = validation.data;
+                    const startTime = Date.now();
+                    try {
+                        // Get tool from registry
+                        const tools = await ctx.toolRegistry.listTools();
+                        const tool = tools.find((t) => t.name === request.name);
+                        if (!tool) {
+                            return {
+                                success: false,
+                                error: `Tool '${request.name}' not found`,
+                                duration: Date.now() - startTime,
+                            };
+                        }
+                        // Execute the tool
+                        const result = await ctx.toolRegistry.executeTool(request.name, request.arguments);
+                        return {
+                            success: true,
+                            data: result,
+                            duration: Date.now() - startTime,
+                            metadata: {
+                                toolName: request.name,
+                                sessionId: request.sessionId || null,
+                            },
+                        };
+                    }
+                    catch (error) {
+                        const errorMessage = error instanceof Error ? error.message : String(error);
+                        return {
+                            success: false,
+                            error: errorMessage,
+                            duration: Date.now() - startTime,
+                        };
+                    }
+                },
+                description: "Execute a tool with arguments",
+                tags: ["tools"],
+            },
+            // 4. POST /api/tools/:name/execute - Execute specific tool (parameterized with nested segment)
+            {
+                method: "POST",
+                path: `${basePath}/tools/:name/execute`,
+                handler: async (ctx) => {
+                    // Validate params
+                    const paramValidation = validateParams(ToolNameParamSchema, ctx.params, ctx.requestId);
+                    if (!paramValidation.success) {
+                        return paramValidation.error;
+                    }
+                    const { name } = paramValidation.data;
+                    // Validate body (tool arguments)
+                    const bodyValidation = validateRequest(ToolArgumentsSchema, ctx.body || {}, ctx.requestId);
+                    if (!bodyValidation.success) {
+                        return bodyValidation.error;
+                    }
+                    const args = bodyValidation.data;
+                    const startTime = Date.now();
+                    try {
+                        // Get tool from registry
+                        const tools = await ctx.toolRegistry.listTools();
+                        const tool = tools.find((t) => t.name === name);
+                        if (!tool) {
+                            return {
+                                success: false,
+                                error: `Tool '${name}' not found`,
+                                duration: Date.now() - startTime,
+                            };
+                        }
+                        // Execute the tool
+                        const result = await ctx.toolRegistry.executeTool(name, args);
+                        return {
+                            success: true,
+                            data: result,
+                            duration: Date.now() - startTime,
+                            metadata: {
+                                toolName: name,
+                            },
+                        };
+                    }
+                    catch (error) {
+                        const errorMessage = error instanceof Error ? error.message : String(error);
+                        return {
+                            success: false,
+                            error: errorMessage,
+                            duration: Date.now() - startTime,
+                        };
+                    }
+                },
+                description: "Execute a specific tool by name",
+                tags: ["tools"],
+            },
+            // 5. GET /api/tools/:name - Get tool details (parameterized, MUST BE LAST)
+            {
+                method: "GET",
+                path: `${basePath}/tools/:name`,
+                handler: async (ctx) => {
+                    // Validate params
+                    const paramValidation = validateParams(ToolNameParamSchema, ctx.params, ctx.requestId);
+                    if (!paramValidation.success) {
+                        return paramValidation.error;
+                    }
+                    const { name } = paramValidation.data;
+                    const tools = await ctx.toolRegistry.listTools();
+                    const tool = tools.find((t) => t.name === name);
+                    if (!tool) {
+                        return createErrorResponse("TOOL_NOT_FOUND", `Tool '${name}' not found`, undefined, ctx.requestId);
+                    }
+                    return {
+                        name: tool.name,
+                        description: tool.description,
+                        inputSchema: tool.inputSchema,
+                        source: tool.source || "built-in",
+                    };
+                },
+                description: "Get tool details by name",
+                tags: ["tools"],
+            },
+        ],
+    };
+}