@juspay/neurolink 9.54.5 → 9.54.7

package/dist/server/routes/healthRoutes.js

@@ -2,6 +2,22 @@
  * Health Routes
  * Endpoints for health checks and system status
  */
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
+/**
+ * Wrap a health-route handler with an OTel span that records the route,
+ * request id, and overall health status.
+ */
+function tracedHealthHandler(name, route, fn) {
+    return (ctx) => withSpan({
+        name,
+        tracer: tracers.http,
+        attributes: {
+            "http.route": route,
+            "http.request.id": ctx.requestId ?? "",
+        },
+    }, () => fn(ctx));
+}
 /**
  * Create health check routes
  */
@@ -12,34 +28,41 @@ export function createHealthRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/health`,
-                handler: async () => {
+                handler: tracedHealthHandler("neurolink.http.health.check", `${basePath}/health`, async () => {
                     return {
                         status: "ok",
                         timestamp: new Date().toISOString(),
                         uptime: process.uptime() * 1000,
                         version: process.env.npm_package_version || "unknown",
                     };
-                },
+                }),
                 description: "Basic health check",
                 tags: ["health"],
             },
             {
                 method: "GET",
                 path: `${basePath}/health/live`,
-                handler: async () => {
+                handler: tracedHealthHandler("neurolink.http.health.live", `${basePath}/health/live`, async () => {
                     // Liveness probe - just checks if the server is running
                     return {
                         status: "alive",
                         timestamp: new Date().toISOString(),
                     };
-                },
+                }),
                 description: "Kubernetes liveness probe",
                 tags: ["health"],
             },
             {
                 method: "GET",
                 path: `${basePath}/health/ready`,
-                handler: async (ctx) => {
+                handler: (ctx) => withSpan({
+                    name: "neurolink.http.health.ready",
+                    tracer: tracers.http,
+                    attributes: {
+                        "http.route": `${basePath}/health/ready`,
+                        "http.request.id": ctx.requestId ?? "",
+                    },
+                }, async (span) => {
                     // Readiness probe - checks if all dependencies are ready
                     const tools = await ctx.toolRegistry.listTools();
                     const hasTools = tools.length > 0;
@@ -56,6 +79,9 @@ export function createHealthRoutes(basePath = "/api") {
                         }
                     }
                     const isReady = hasTools || !hasExternalManager || externalServersReady;
+                    span.setAttribute("health.ready", isReady);
+                    span.setAttribute("health.tools_count", tools.length);
+                    span.setAttribute("health.external_servers_ready", externalServersReady);
                     return {
                         ready: isReady,
                         timestamp: new Date().toISOString(),
@@ -65,16 +91,24 @@ export function createHealthRoutes(basePath = "/api") {
                             externalServers: externalServersReady,
                         },
                     };
-                },
+                }),
                 description: "Kubernetes readiness probe",
                 tags: ["health"],
             },
             {
                 method: "GET",
                 path: `${basePath}/health/startup`,
-                handler: async (ctx) => {
+                handler: (ctx) => withSpan({
+                    name: "neurolink.http.health.startup",
+                    tracer: tracers.http,
+                    attributes: {
+                        "http.route": `${basePath}/health/startup`,
+                        "http.request.id": ctx.requestId ?? "",
+                    },
+                }, async (span) => {
                     // Startup probe - checks if the application has started successfully
                     const tools = await ctx.toolRegistry.listTools();
+                    span.setAttribute("health.tools_count", tools.length);
                     return {
                         started: true,
                         timestamp: new Date().toISOString(),
@@ -84,14 +118,21 @@ export function createHealthRoutes(basePath = "/api") {
                             externalServerManager: !!ctx.externalServerManager,
                         },
                     };
-                },
+                }),
                 description: "Kubernetes startup probe",
                 tags: ["health"],
             },
             {
                 method: "GET",
                 path: `${basePath}/health/detailed`,
-                handler: async (ctx) => {
+                handler: (ctx) => withSpan({
+                    name: "neurolink.http.health.detailed",
+                    tracer: tracers.http,
+                    attributes: {
+                        "http.route": `${basePath}/health/detailed`,
+                        "http.request.id": ctx.requestId ?? "",
+                    },
+                }, async (span) => {
                     const tools = await ctx.toolRegistry.listTools();
                     // Group tools by source
                     const toolsBySource = {};
@@ -162,23 +203,28 @@ export function createHealthRoutes(basePath = "/api") {
                             healthyCount: pool.getHealthyCount(),
                             strategy: pool.getStrategy(),
                         };
+                        span.setAttribute("health.proxy.accounts", allAccounts.length);
+                        span.setAttribute("health.proxy.healthy", pool.getHealthyCount());
                     }
+                    span.setAttribute("health.tools_count", tools.length);
+                    span.setAttribute("health.external_servers_count", externalServers.length);
+                    span.setAttribute("health.memory.heap_mb", Math.round(process.memoryUsage().heapUsed / 1024 / 1024));
                     return healthResponse;
-                },
+                }),
                 description: "Detailed health information",
                 tags: ["health"],
             },
             {
                 method: "GET",
                 path: `${basePath}/version`,
-                handler: async () => {
+                handler: tracedHealthHandler("neurolink.http.version", `${basePath}/version`, async () => {
                     return {
                         name: "@juspay/neurolink",
                         version: process.env.npm_package_version || "unknown",
                         node: process.version,
                         timestamp: new Date().toISOString(),
                     };
-                },
+                }),
                 description: "Get version information",
                 tags: ["health", "version"],
             },

package/dist/server/routes/index.d.ts

@@ -2,7 +2,7 @@
  * Route Builders
  * Pre-built route definitions for common NeuroLink endpoints
  */
-import type { RouteDefinition, RouteGroup } from "../../types/index.js";
+import type { CreateRoutesOptions, RouteDefinition, RouteGroup } from "../../types/index.js";
 export { createAgentRoutes } from "./agentRoutes.js";
 export { createClaudeProxyRoutes } from "./claudeProxyRoutes.js";
 export { createHealthRoutes } from "./healthRoutes.js";
@@ -10,31 +10,6 @@ export { createMCPRoutes } from "./mcpRoutes.js";
 export { createMemoryRoutes } from "./memoryRoutes.js";
 export { createOpenApiRoutes } from "./openApiRoutes.js";
 export { createToolRoutes } from "./toolRoutes.js";
-/**
- * Options for creating routes
- */
-type CreateRoutesOptions = {
-    /** Enable OpenAPI/Swagger documentation endpoints (default: false) */
-    enableSwagger?: boolean;
-    /**
-     * Callback to get registered routes for OpenAPI spec generation.
-     * This callback is invoked at request time when the OpenAPI spec is accessed,
-     * allowing it to reflect all routes registered with the adapter.
-     *
-     * When using `registerAllRoutes`, this is automatically bound to `adapter.listRoutes()`
-     * if the adapter supports it and no custom callback is provided.
-     *
-     * If not provided (and adapter doesn't have listRoutes), the spec will use
-     * default endpoint definitions.
-     */
-    getRoutes?: () => RouteDefinition[];
-    /**
-     * Enable or disable the Claude-compatible proxy routes.
-     * When true, registers /v1/messages, /v1/models, and /v1/messages/count_tokens
-     * endpoints that accept Anthropic API format requests.
-     */
-    claudeProxy?: boolean;
-};
 /**
  * Create all standard routes
  * Convenience method that combines all route groups

package/dist/server/routes/mcpRoutes.js

@@ -2,8 +2,41 @@
  * MCP Routes
  * Endpoints for MCP server management
  */
+import { SpanStatusCode } from "@opentelemetry/api";
 import { z } from "zod";
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 import { createErrorResponse, ServerNameParamSchema, ToolArgumentsSchema, validateParams, validateRequest, } from "../utils/validation.js";
+/**
+ * Wrap a route handler with an OTel span for HTTP observability.
+ */
+function tracedMcpHandler(name, route, fn) {
+    return (ctx) => withSpan({
+        name,
+        tracer: tracers.http,
+        attributes: {
+            "http.route": route,
+            "http.request.id": ctx.requestId,
+        },
+    }, async (otelSpan) => {
+        const result = await fn(ctx);
+        // Detect returned error responses (not thrown) and mark span as failed.
+        // Only flag when the error value is truthy to avoid false positives
+        // from handlers that always include an `error` key (e.g. handleGetServer).
+        if (result && typeof result === "object") {
+            const errVal = result.error;
+            if (errVal !== undefined && errVal !== null) {
+                const errMsg = typeof errVal === "string"
+                    ? errVal
+                    : typeof errVal?.message === "string"
+                        ? errVal.message
+                        : "MCP handler error";
+                otelSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
+            }
+        }
+        return result;
+    });
+}
 /**
  * MCP tool execution params schema
  */
@@ -291,49 +324,49 @@ export function createMCPRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/mcp/servers`,
-                handler: handleListServers,
+                handler: tracedMcpHandler("neurolink.http.mcp.listServers", `${basePath}/mcp/servers`, handleListServers),
                 description: "List all MCP servers",
                 tags: ["mcp"],
             },
             {
                 method: "GET",
                 path: `${basePath}/mcp/servers/:name`,
-                handler: handleGetServer,
+                handler: tracedMcpHandler("neurolink.http.mcp.getServer", `${basePath}/mcp/servers/:name`, handleGetServer),
                 description: "Get MCP server status",
                 tags: ["mcp"],
             },
             {
                 method: "POST",
                 path: `${basePath}/mcp/servers/:name/reconnect`,
-                handler: handleReconnectServer,
+                handler: tracedMcpHandler("neurolink.http.mcp.reconnectServer", `${basePath}/mcp/servers/:name/reconnect`, handleReconnectServer),
                 description: "Reconnect to an MCP server",
                 tags: ["mcp"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/mcp/servers/:name`,
-                handler: handleRemoveServer,
+                handler: tracedMcpHandler("neurolink.http.mcp.removeServer", `${basePath}/mcp/servers/:name`, handleRemoveServer),
                 description: "Remove an MCP server",
                 tags: ["mcp"],
             },
             {
                 method: "GET",
                 path: `${basePath}/mcp/servers/:name/tools`,
-                handler: handleListServerTools,
+                handler: tracedMcpHandler("neurolink.http.mcp.listServerTools", `${basePath}/mcp/servers/:name/tools`, handleListServerTools),
                 description: "List tools from a specific MCP server",
                 tags: ["mcp", "tools"],
             },
             {
                 method: "POST",
                 path: `${basePath}/mcp/servers/:name/tools/:toolName/execute`,
-                handler: handleExecuteTool,
+                handler: tracedMcpHandler("neurolink.http.mcp.executeTool", `${basePath}/mcp/servers/:name/tools/:toolName/execute`, handleExecuteTool),
                 description: "Execute a tool from a specific MCP server",
                 tags: ["mcp", "tools"],
             },
             {
                 method: "GET",
                 path: `${basePath}/mcp/health`,
-                handler: handleMCPHealth,
+                handler: tracedMcpHandler("neurolink.http.mcp.health", `${basePath}/mcp/health`, handleMCPHealth),
                 description: "Health check for all MCP servers",
                 tags: ["mcp", "health"],
             },

package/dist/server/routes/memoryRoutes.js

@@ -2,7 +2,22 @@
  * Memory Routes
  * Endpoints for conversation memory management
  */
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 import { createErrorResponse, IdParamSchema, SessionIdParamSchema, validateParams, } from "../utils/validation.js";
+/**
+ * Wrap a route handler with an OTel span for HTTP observability.
+ */
+function tracedMemoryHandler(name, route, fn) {
+    return (ctx) => withSpan({
+        name,
+        tracer: tracers.http,
+        attributes: {
+            "http.route": route,
+            "http.request.id": ctx.requestId,
+        },
+    }, () => fn(ctx));
+}
 /**
  * Handler: Get messages for a session
  */
@@ -297,7 +312,7 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions/:id/messages`,
-                handler: handleGetSessionMessages,
+                handler: tracedMemoryHandler("neurolink.http.memory.getSessionMessages", `${basePath}/memory/sessions/:id/messages`, handleGetSessionMessages),
                 description: "Get messages for a session",
                 tags: ["memory"],
             },
@@ -305,7 +320,7 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions/:id`,
-                handler: handleGetSession,
+                handler: tracedMemoryHandler("neurolink.http.memory.getSession", `${basePath}/memory/sessions/:id`, handleGetSession),
                 description: "Get session by ID",
                 tags: ["memory"],
             },
@@ -313,35 +328,35 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions`,
-                handler: handleListSessions,
+                handler: tracedMemoryHandler("neurolink.http.memory.listSessions", `${basePath}/memory/sessions`, handleListSessions),
                 description: "List all conversation sessions",
                 tags: ["memory"],
             },
             {
                 method: "GET",
                 path: `${basePath}/memory/stats`,
-                handler: handleGetStats,
+                handler: tracedMemoryHandler("neurolink.http.memory.stats", `${basePath}/memory/stats`, handleGetStats),
                 description: "Get memory statistics",
                 tags: ["memory"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/memory/sessions/:sessionId`,
-                handler: handleClearSession,
+                handler: tracedMemoryHandler("neurolink.http.memory.clearSession", `${basePath}/memory/sessions/:sessionId`, handleClearSession),
                 description: "Clear a conversation session",
                 tags: ["memory"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/memory/sessions`,
-                handler: handleClearAllSessions,
+                handler: tracedMemoryHandler("neurolink.http.memory.clearAllSessions", `${basePath}/memory/sessions`, handleClearAllSessions),
                 description: "Clear all conversation sessions",
                 tags: ["memory"],
             },
             {
                 method: "GET",
                 path: `${basePath}/memory/health`,
-                handler: handleMemoryHealth,
+                handler: tracedMemoryHandler("neurolink.http.memory.health", `${basePath}/memory/health`, handleMemoryHealth),
                 description: "Check memory system health",
                 tags: ["memory", "health"],
             },

package/dist/server/routes/openApiRoutes.js

@@ -4,6 +4,8 @@
  */
 import { logger } from "../../utils/logger.js";
 import { OpenAPIGenerator } from "../openapi/generator.js";
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 /**
  * Create OpenAPI documentation routes
  *
@@ -44,7 +46,14 @@ export function createOpenApiRoutes(basePath = "/api", getRoutes) {
             {
                 method: "GET",
                 path: `${basePath}/openapi.json`,
-                handler: async () => {
+                handler: async () => withSpan({
+                    name: "neurolink.http.openapi.json",
+                    tracer: tracers.http,
+                    attributes: {
+                        "http.route": `${basePath}/openapi.json`,
+                        "openapi.format": "json",
+                    },
+                }, async (span) => {
                     const routes = getRoutes?.() ?? [];
                     if (!getRoutes) {
                         logger.warn("[OpenAPI] No getRoutes callback provided. OpenAPI spec will use default endpoint definitions. " +
@@ -53,19 +62,27 @@ export function createOpenApiRoutes(basePath = "/api", getRoutes) {
                     else if (routes.length === 0) {
                         logger.debug("[OpenAPI] getRoutes returned empty array. No custom routes will be documented.");
                     }
+                    span.setAttribute("openapi.route_count", routes.length);
                     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 () => {
+                handler: async () => withSpan({
+                    name: "neurolink.http.openapi.yaml",
+                    tracer: tracers.http,
+                    attributes: {
+                        "http.route": `${basePath}/openapi.yaml`,
+                        "openapi.format": "yaml",
+                    },
+                }, async (span) => {
                     const routes = getRoutes?.() ?? [];
                     if (!getRoutes) {
                         logger.warn("[OpenAPI] No getRoutes callback provided. OpenAPI spec will use default endpoint definitions. " +
@@ -74,6 +91,7 @@ export function createOpenApiRoutes(basePath = "/api", getRoutes) {
                     else if (routes.length === 0) {
                         logger.debug("[OpenAPI] getRoutes returned empty array. No custom routes will be documented.");
                     }
+                    span.setAttribute("openapi.route_count", routes.length);
                     const generator = new OpenAPIGenerator({
                         basePath,
                         routes,
@@ -83,14 +101,20 @@ export function createOpenApiRoutes(basePath = "/api", getRoutes) {
                         contentType: "text/yaml",
                         body: generator.toYAML(),
                     };
-                },
+                }),
                 description: "Get OpenAPI specification as YAML",
                 tags: ["openapi", "documentation"],
             },
             {
                 method: "GET",
                 path: `${basePath}/docs`,
-                handler: async () => {
+                handler: async () => withSpan({
+                    name: "neurolink.http.openapi.docs",
+                    tracer: tracers.http,
+                    attributes: {
+                        "http.route": `${basePath}/docs`,
+                    },
+                }, async () => {
                     const html = `<!DOCTYPE html>
 <html>
 <head>
@@ -117,7 +141,7 @@ export function createOpenApiRoutes(basePath = "/api", getRoutes) {
                         contentType: "text/html",
                         body: html,
                     };
-                },
+                }),
                 description: "Swagger UI documentation page",
                 tags: ["openapi", "documentation"],
             },