@juspay/neurolink 9.54.6 → 9.54.8

package/dist/lib/client/httpClient.js

@@ -8,6 +8,8 @@
  */
 import { HttpError, ClientNetworkError, ClientTimeoutError } from "./errors.js";
 import { logger } from "../utils/logger.js";
+import { tracers } from "../telemetry/tracers.js";
+import { withClientSpan } from "../telemetry/withSpan.js";
 // =============================================================================
 // Shared Utilities
 // =============================================================================
@@ -184,6 +186,17 @@ export class NeuroLinkClient {
      * Execute HTTP request with middleware and retry logic
      */
     async request(method, path, body, options) {
+        return withClientSpan({
+            name: "neurolink.client.http.request",
+            tracer: tracers.http,
+            attributes: {
+                "http.method": method,
+                "http.route": path,
+                "http.url": `${this.config.baseUrl}${path}`,
+            },
+        }, async () => this._doRequest(method, path, body, options));
+    }
+    async _doRequest(method, path, body, options) {
         const url = `${this.config.baseUrl}${path}`;
         const requestId = this.generateRequestId();
         const { retry } = this.config;

package/dist/lib/client/sseClient.d.ts

@@ -49,6 +49,7 @@ export declare class NeuroLinkSSE {
      * Stream from an endpoint using SSE
      */
     stream(path: string, options?: SSERequestOptions, callbacks?: ClientStreamCallbacks): Promise<void>;
+    private _streamInternal;
     /**
      * Abort the current stream
      */

package/dist/lib/client/sseClient.js

@@ -7,7 +7,10 @@
  *
  * @module @neurolink/client/sseClient
  */
+import { SpanStatusCode } from "@opentelemetry/api";
 import { logger } from "../utils/logger.js";
+import { withClientSpan } from "../telemetry/withSpan.js";
+import { tracers } from "../telemetry/tracers.js";
 // =============================================================================
 // SSE Client Implementation
 // =============================================================================
@@ -69,6 +72,32 @@ export class NeuroLinkSSE {
      * Stream from an endpoint using SSE
      */
     async stream(path, options = {}, callbacks = {}) {
+        return withClientSpan({
+            name: "neurolink.client.sse.stream",
+            tracer: tracers.http,
+            attributes: {
+                "http.method": options.body ? "POST" : "GET",
+                "http.route": path,
+                "http.url": this.buildUrl(path),
+                "sse.auto_reconnect": this.config.autoReconnect,
+                "sse.native_event_source": this.config.useNativeEventSource,
+            },
+        }, async (span) => {
+            // Wrap onError callback so the span is marked failed on stream errors
+            const wrappedCallbacks = {
+                ...callbacks,
+                onError: (error) => {
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: error?.message ?? "SSE stream error",
+                    });
+                    callbacks.onError?.(error);
+                },
+            };
+            return this._streamInternal(path, options, wrappedCallbacks);
+        });
+    }
+    async _streamInternal(path, options = {}, callbacks = {}) {
         const url = this.buildUrl(path);
         const isGetRequest = !options.body;
         // Use native EventSource for GET requests when configured and available

package/dist/lib/client/streamingClient.d.ts

@@ -49,6 +49,7 @@ export declare class SSEClient {
         body?: unknown;
         headers?: Record<string, string>;
     }): Promise<void>;
+    private _connectSSE;
     /**
      * Disconnect from SSE endpoint
      */
@@ -131,6 +132,7 @@ export declare class WebSocketStreamingClient {
      * Connect to WebSocket server
      */
     connect(): Promise<void>;
+    private _connectWS;
     /**
      * Disconnect from WebSocket server
      */

package/dist/lib/client/streamingClient.js

@@ -8,6 +8,8 @@
  */
 import { logger } from "../utils/logger.js";
 import { combineSignals, sleep } from "./httpClient.js";
+import { withClientSpan } from "../telemetry/withSpan.js";
+import { tracers } from "../telemetry/tracers.js";
 // =============================================================================
 // Types
 // =============================================================================
@@ -61,6 +63,16 @@ export class SSEClient {
      * Connect to SSE endpoint
      */
     async connect(requestOptions = {}) {
+        return withClientSpan({
+            name: "neurolink.client.streaming.sse.connect",
+            tracer: tracers.http,
+            attributes: {
+                "http.url": this.url,
+                "http.method": requestOptions.body ? "POST" : "GET",
+            },
+        }, async () => this._connectSSE(requestOptions));
+    }
+    async _connectSSE(requestOptions = {}) {
         if (this.state === "connected" || this.state === "connecting") {
             return;
         }
@@ -393,6 +405,13 @@ export class WebSocketStreamingClient {
      * Connect to WebSocket server
      */
     async connect() {
+        return withClientSpan({
+            name: "neurolink.client.streaming.ws.connect",
+            tracer: tracers.http,
+            attributes: { "http.url": this.options.url },
+        }, async () => this._connectWS());
+    }
+    async _connectWS() {
         if (typeof WebSocket === "undefined") {
             throw new Error("WebSocket is not available. Please use a polyfill for non-browser environments.");
         }

package/dist/lib/client/wsClient.d.ts

@@ -43,6 +43,12 @@ export declare class NeuroLinkWebSocket {
     private eventHandlers;
     private subscriptions;
     private pendingAuth;
+    /**
+     * Active OTel span for the current WebSocket connection lifecycle.
+     * Created at connect() and ended on close/error so we capture connection
+     * lifetime, reconnect counts, and error attribution in Langfuse.
+     */
+    private connectionSpan;
     /**
      * Local flag to suppress reconnection during an explicit disconnect().
      * Unlike mutating config.autoReconnect, this preserves the user's

package/dist/lib/client/wsClient.js

@@ -7,6 +7,8 @@
  *
  * @module @neurolink/client/wsClient
  */
+import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { tracers } from "../telemetry/tracers.js";
 // =============================================================================
 // WebSocket Client
 // =============================================================================
@@ -45,6 +47,12 @@ export class NeuroLinkWebSocket {
     eventHandlers = {};
     subscriptions = new Map();
     pendingAuth = false;
+    /**
+     * Active OTel span for the current WebSocket connection lifecycle.
+     * Created at connect() and ended on close/error so we capture connection
+     * lifetime, reconnect counts, and error attribution in Langfuse.
+     */
+    connectionSpan = null;
     /**
      * Local flag to suppress reconnection during an explicit disconnect().
      * Unlike mutating config.autoReconnect, this preserves the user's
@@ -89,6 +97,28 @@ export class NeuroLinkWebSocket {
         this.disconnectRequested = false;
         this.eventHandlers = handlers ?? {};
         this.setState("connecting");
+        // End any orphaned span from a prior connect() attempt (e.g., re-entrant call
+        // while a previous attempt was still connecting).
+        if (this.connectionSpan) {
+            this.connectionSpan.setAttribute("ws.superseded", true);
+            this.connectionSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: "Connection attempt superseded by new connect() call",
+            });
+            this.connectionSpan.end();
+            this.connectionSpan = null;
+        }
+        // Start an OTel span that tracks the lifetime of this connection attempt.
+        // Ended in onclose/onerror/disconnect so metrics capture connection
+        // duration and error attribution.
+        this.connectionSpan = tracers.http.startSpan("neurolink.client.ws.connect", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "http.url": this.config.baseUrl,
+                "ws.auto_reconnect": this.config.autoReconnect,
+                "ws.reconnect_attempt": this.reconnectAttempts,
+            },
+        });
         // Build WebSocket URL (credentials are sent via headers, not query params,
         // to avoid leaking secrets in server logs, browser history, and HTTP referers)
         const url = new URL(this.config.baseUrl);
@@ -107,15 +137,25 @@ export class NeuroLinkWebSocket {
         // credentials are sent as the first message after the connection opens.
         const isNode = typeof globalThis.process !== "undefined" &&
             typeof globalThis.process.versions?.node === "string";
-        if (isNode && Object.keys(authHeaders).length > 0) {
-            // The `ws` npm package accepts a second `options` object with a `headers`
-            // property.  The DOM WebSocket type does not model this, so we cast
-            // through `unknown` to satisfy TypeScript while remaining correct at
-            // runtime under Node.js.
-            this.ws = new WebSocket(url.toString(), { headers: authHeaders });
+        try {
+            if (isNode && Object.keys(authHeaders).length > 0) {
+                this.ws = new WebSocket(url.toString(), { headers: authHeaders });
+            }
+            else {
+                this.ws = new WebSocket(url.toString());
+            }
         }
-        else {
-            this.ws = new WebSocket(url.toString());
+        catch (error) {
+            if (this.connectionSpan) {
+                this.connectionSpan.recordException(error instanceof Error ? error : new Error(String(error)));
+                this.connectionSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                this.connectionSpan.end();
+                this.connectionSpan = null;
+            }
+            throw error;
         }
         this.pendingAuth = !isNode && (!!this.config.apiKey || !!this.config.token);
         this.setupEventListeners();
@@ -134,6 +174,15 @@ export class NeuroLinkWebSocket {
             this.ws = null;
         }
         this.setState("disconnected");
+        // Let onclose finalize the span — it fires from ws.close(1000,...) and
+        // has the close code context.  We only end here if ws is already null
+        // (e.g. connect was never called) to avoid leaking.
+        if (this.connectionSpan && !this.ws) {
+            this.connectionSpan.setAttribute("ws.close_reason", "client_disconnect");
+            this.connectionSpan.setStatus({ code: SpanStatusCode.OK });
+            this.connectionSpan.end();
+            this.connectionSpan = null;
+        }
     }
     /**
      * Send a message through WebSocket
@@ -144,7 +193,7 @@ export class NeuroLinkWebSocket {
         }
         else {
             // Queue message for when connected
-            if (this.messageQueue.length < this.config.queueSize) {
+            if (this.messageQueue.length < (this.config.queueSize ?? 100)) {
                 this.messageQueue.push(message);
             }
         }
@@ -199,6 +248,9 @@ export class NeuroLinkWebSocket {
         this.ws.onopen = () => {
             this.setState("connected");
             this.reconnectAttempts = 0;
+            if (this.connectionSpan) {
+                this.connectionSpan.setAttribute("ws.connected", true);
+            }
             // In browser environments, send credentials as the first message
             // since the browser WebSocket API does not support custom headers.
             if (this.pendingAuth && this.ws) {
@@ -223,6 +275,24 @@ export class NeuroLinkWebSocket {
             this.setState("disconnected");
             this.stopHeartbeat();
             this.eventHandlers.onClose?.(event.code, event.reason);
+            if (this.connectionSpan) {
+                this.connectionSpan.setAttribute("ws.close_code", event.code);
+                if (event.reason) {
+                    this.connectionSpan.setAttribute("ws.close_reason", event.reason);
+                }
+                // 1000 = normal closure; other codes are abnormal.
+                if (event.code === 1000) {
+                    this.connectionSpan.setStatus({ code: SpanStatusCode.OK });
+                }
+                else {
+                    this.connectionSpan.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: `WebSocket closed with code ${event.code}${event.reason ? `: ${event.reason}` : ""}`,
+                    });
+                }
+                this.connectionSpan.end();
+                this.connectionSpan = null;
+            }
             // Only attempt reconnection when auto-reconnect is enabled AND this
             // was not an intentional disconnect (code 1000 or explicit call).
             if (this.config.autoReconnect &&
@@ -235,6 +305,16 @@ export class NeuroLinkWebSocket {
             this.setState("error");
             const error = new Error("WebSocket connection error");
             this.eventHandlers.onError?.(error);
+            if (this.connectionSpan) {
+                this.connectionSpan.recordException(error);
+                this.connectionSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error.message,
+                });
+                // Do not end here — onclose will fire next and end the span with
+                // the precise close code. Keeping the span open until close gives
+                // us the full connection lifetime on Langfuse.
+            }
         };
         this.ws.onmessage = (event) => {
             try {
@@ -303,7 +383,7 @@ export class NeuroLinkWebSocket {
             if (this.isConnected()) {
                 this.send({ type: "ping" });
             }
-        }, this.config.heartbeatInterval);
+        }, this.config.heartbeatInterval ?? 30000);
     }
     stopHeartbeat() {
         if (this.heartbeatTimer) {

package/dist/lib/context/budgetChecker.js

@@ -9,6 +9,7 @@
 import { getAvailableInputTokens } from "../constants/contextWindows.js";
 import { estimateMessagesTokens, estimateTokens, TOKENS_PER_MESSAGE, } from "../utils/tokenEstimation.js";
 import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../observability/index.js";
+import { getActiveTraceContext } from "../telemetry/traceContext.js";
 /** Default compaction threshold (80% of available input) */
 const DEFAULT_COMPACTION_THRESHOLD = 0.8;
 /** Estimated tokens per tool definition */
@@ -21,9 +22,10 @@ const TOKENS_PER_TOOL_DEFINITION = 200;
  * against available input space.
  */
 export function checkContextBudget(params) {
+    const { traceId, parentSpanId } = getActiveTraceContext();
     const span = SpanSerializer.createSpan(SpanType.CONTEXT_COMPACTION, "context.budgetCheck", {
         "context.operation": "budgetCheck",
-    });
+    }, parentSpanId, traceId);
     const startTime = Date.now();
     try {
         const { provider, model, maxTokens, systemPrompt, conversationMessages, currentPrompt, toolDefinitions, fileAttachments, compactionThreshold = DEFAULT_COMPACTION_THRESHOLD, } = params;