@juspay/neurolink 9.54.6 → 9.54.8

package/dist/lib/proxy/proxyTracer.d.ts

@@ -14,42 +14,7 @@
  * - TelemetryService for metrics recording
  */
 import { type Span } from "@opentelemetry/api";
-type ProxyRequestContext = {
-    requestId: string;
-    method: string;
-    path: string;
-    model: string;
-    stream: boolean;
-    toolCount: number;
-    sessionId?: string;
-    userAgent?: string;
-    clientApp?: string;
-};
-type AccountSelectionContext = {
-    strategy: string;
-    accountsTotal: number;
-    accountsHealthy: number;
-    selectedAccount: string;
-    accountType: string;
-    rateLimitBefore5h?: number;
-    rateLimitBefore7d?: number;
-};
-type UpstreamAttemptContext = {
-    attempt: number;
-    account: string;
-    polyfillHeaders: boolean;
-    polyfillBody: boolean;
-    upstreamUrl: string;
-};
-type UsageContext = {
-    inputTokens: number;
-    outputTokens: number;
-    cacheCreationTokens: number;
-    cacheReadTokens: number;
-    reasoningTokens?: number;
-    rateLimitAfter5h?: number;
-    rateLimitAfter7d?: number;
-};
+import type { AccountSelectionContext, ProxyRequestContext, UpstreamAttemptContext, UsageContext } from "../types/index.js";
 declare class ProxyTracer {
     private readonly rootSpan;
     private readonly proxyTracer;

package/dist/lib/proxy/proxyTracer.js

@@ -20,6 +20,15 @@ import { calculateCost } from "../utils/pricing.js";
 import { TelemetryService } from "../telemetry/telemetryService.js";
 import { logger } from "../utils/logger.js";
 const LOG_PREFIX = "[ProxyTracer]";
+// ---------------------------------------------------------------------------
+// OTEL Metric Instruments — lazy singleton
+//
+// The MeterProvider is registered in initializeOpenTelemetry() which runs
+// *after* module import time.  @opentelemetry/api v1.x getMeter() returns a
+// NoopMeter if called before a real MeterProvider is set.  We therefore
+// defer instrument creation until the first ProxyTracer.end() call, at which
+// point the MeterProvider is guaranteed to be registered.
+// ---------------------------------------------------------------------------
 let _metrics = null;
 function getProxyMetrics() {
     if (_metrics) {

package/dist/lib/proxy/quietDetector.d.ts

@@ -4,12 +4,7 @@
  * threshold by efficiently reading only the tail of today's debug log file.
  * Used by the auto-update system to find safe windows for restarts.
  */
-/** Result of a traffic-quiet check. */
-type QuietStatus = {
-    isQuiet: boolean;
-    lastActivityAt: Date | null;
-    silenceDurationMs: number;
-};
+import type { QuietStatus } from "../types/index.js";
 /**
  * Check whether proxy traffic has been quiet (no requests) for at least
  * `quietThresholdMs` milliseconds.
@@ -20,4 +15,3 @@ type QuietStatus = {
  * @returns QuietStatus with the idle analysis.
  */
 export declare function checkTrafficQuiet(quietThresholdMs?: number): QuietStatus;
-export {};

package/dist/lib/proxy/rawStreamCapture.d.ts

@@ -1,11 +1,2 @@
-type RawStreamCapture = {
-    totalBytes: number;
-    text: string;
-    truncated: boolean;
-};
-type RawStreamCaptureResult = {
-    stream: TransformStream<Uint8Array, Uint8Array>;
-    capture: Promise<RawStreamCapture>;
-};
+import type { RawStreamCaptureResult } from "../types/index.js";
 export declare function createRawStreamCapture(): RawStreamCaptureResult;
-export {};

package/dist/lib/proxy/requestLogger.d.ts

@@ -5,7 +5,7 @@
  * when a LoggerProvider is configured via OpenTelemetry instrumentation.
  * Useful for debugging and auditing proxy traffic.
  */
-import type { RequestAttemptLogEntry, RequestLogEntry } from "../types/index.js";
+import type { ProxyBodyCaptureEntry, RequestAttemptLogEntry, RequestLogEntry } from "../types/index.js";
 export declare function initRequestLogger(enabled?: boolean, customLogsDir?: string): void;
 export declare function logRequest(entry: RequestLogEntry): Promise<void>;
 /**
@@ -15,25 +15,6 @@ export declare function logRequest(entry: RequestLogEntry): Promise<void>;
  */
 export declare function logRequestAttempt(entry: RequestAttemptLogEntry): Promise<void>;
 export declare function getLogDir(): string | null;
-type ProxyBodyCaptureEntry = {
-    timestamp: string;
-    requestId: string;
-    phase: string;
-    model: string;
-    stream: boolean;
-    headers?: Record<string, string>;
-    body?: unknown;
-    bodySize?: number;
-    contentType?: string;
-    responseStatus?: number;
-    durationMs?: number;
-    account?: string;
-    accountType?: string;
-    attempt?: number;
-    traceId?: string;
-    spanId?: string;
-    metadata?: Record<string, unknown>;
-};
 export declare function logBodyCapture(entry: ProxyBodyCaptureEntry): Promise<void>;
 /**
  * Log the FULL raw request and response for debugging.
@@ -74,4 +55,3 @@ export declare function logStreamError(entry: {
  * Non-fatal — proxy keeps working even if cleanup fails.
  */
 export declare function cleanupLogs(maxAgeDays?: number, maxSizeMb?: number): void;
-export {};

package/dist/lib/proxy/sseInterceptor.d.ts

@@ -15,71 +15,7 @@
  *   upstreamResponse.body.pipeThrough(stream).pipeTo(clientWritable);
  *   const data = await telemetry; // resolves on stream end
  */
-type SSEContentBlock = {
-    index: number;
-    type: "text" | "thinking" | "tool_use" | "tool_result";
-    /** Accumulated text for text blocks. Capped at MAX_BLOCK_CONTENT_BYTES. */
-    text?: string;
-    /** Accumulated thinking content. Capped at MAX_BLOCK_CONTENT_BYTES. */
-    thinking?: string;
-    /** Tool name for tool_use blocks. */
-    toolName?: string;
-    /** Tool call id for tool_use blocks. */
-    toolId?: string;
-    /** Accumulated partial JSON input for tool_use blocks. Capped at MAX_BLOCK_CONTENT_BYTES. */
-    toolInput?: string;
-};
-type SSETelemetry = {
-    /** Message id from message_start. */
-    messageId: string;
-    /** Model string from message_start. */
-    model: string;
-    /** Token usage aggregated from message_start + message_delta. */
-    usage: {
-        inputTokens: number;
-        outputTokens: number;
-        cacheCreationInputTokens: number;
-        cacheReadInputTokens: number;
-        totalTokens: number;
-    };
-    /** All content blocks accumulated during the stream. */
-    contentBlocks: SSEContentBlock[];
-    /** Stop reason from message_delta, e.g. "end_turn". */
-    stopReason: string | null;
-    /** Stop sequence from message_delta, if any. */
-    stopSequence: string | null;
-    /** Total number of SSE events observed. */
-    eventCount: number;
-    /** Wall-clock duration from first byte to stream end (ms). */
-    streamDurationMs: number;
-    /** Total bytes received from upstream (raw SSE stream size). */
-    totalBytesReceived: number;
-    /**
-     * Raw SSE event log. For content_block_delta events only the type is
-     * stored (not the full data payload) to avoid excessive memory use.
-     * All other events store the full data string.
-     */
-    events: Array<{
-        type: string;
-        timestamp: number;
-        data: string;
-    }>;
-    /** Full raw SSE transcript, when captureRawText is enabled. */
-    rawText?: string;
-};
-type SSEInterceptorResult = {
-    /** Pipe the upstream response through this stream. */
-    stream: TransformStream<Uint8Array, Uint8Array>;
-    /**
-     * Resolves with the accumulated telemetry when the stream finishes.
-     * If the stream errors, the promise resolves with whatever telemetry
-     * was gathered up to that point (never rejects).
-     */
-    telemetry: Promise<SSETelemetry>;
-};
-type SSEInterceptorOptions = {
-    captureRawText?: boolean;
-};
+import type { SSEInterceptorOptions, SSEInterceptorResult } from "../types/index.js";
 /**
  * Create an SSE interceptor that extracts telemetry from an Anthropic
  * streaming response while passing all bytes through unmodified.
@@ -95,4 +31,3 @@ type SSEInterceptorOptions = {
  * ```
  */
 export declare function createSSEInterceptor(options?: SSEInterceptorOptions): SSEInterceptorResult;
-export {};

package/dist/lib/proxy/sseInterceptor.js

@@ -69,6 +69,9 @@ function extractSSEEvents(buffer) {
     }
     return { events, remainder: buffer.slice(cursor) };
 }
+// ---------------------------------------------------------------------------
+// Telemetry accumulator
+// ---------------------------------------------------------------------------
 function createAccumulator(captureRawText) {
     return {
         messageId: "",
@@ -338,6 +341,9 @@ function processEvent(acc, event) {
             break;
     }
 }
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
 /**
  * Create an SSE interceptor that extracts telemetry from an Anthropic
  * streaming response while passing all bytes through unmodified.

package/dist/lib/proxy/updateChecker.d.ts

@@ -6,11 +6,7 @@
  * Designed to be non-blocking and failure-tolerant — any error (network,
  * timeout, parse) silently returns `updateAvailable: false`.
  */
-type UpdateCheckResult = {
-    currentVersion: string;
-    latestVersion: string;
-    updateAvailable: boolean;
-};
+import type { UpdateCheckResult } from "../types/index.js";
 /**
  * Query npm for the latest version of `@juspay/neurolink` and compare it
  * against {@link currentVersion}.
@@ -19,4 +15,3 @@ type UpdateCheckResult = {
  * `{ updateAvailable: false, latestVersion: currentVersion }`.
  */
 export declare function checkForUpdate(currentVersion: string): Promise<UpdateCheckResult>;
-export {};

package/dist/lib/proxy/updateState.d.ts

@@ -6,17 +6,7 @@
  * State file location: ~/.neurolink/update-state.json
  * Suppressed versions expire after 24 hours.
  */
-type SuppressedVersion = {
-    suppressedAt: string;
-    reason: string;
-};
-type UpdateState = {
-    lastCheckAt: string;
-    lastCheckVersion: string;
-    suppressedVersions: Record<string, SuppressedVersion>;
-    lastUpdateAt: string | null;
-    lastUpdateVersion: string | null;
-};
+import type { UpdateState } from "../types/index.js";
 /**
  * Return an empty/initial UpdateState.
  */
@@ -65,4 +55,3 @@ export declare function recordSuccessfulUpdate(version: string, stateFilePath?:
  * @param stateFilePath - Override path for testing
  */
 export declare function recordCheck(latestVersion: string, stateFilePath?: string): void;
-export {};

package/dist/lib/rag/chunkers/BaseChunker.js

@@ -6,6 +6,8 @@
  */
 import { v4 as uuidv4 } from "uuid";
 import { ChunkingError, RAGErrorCodes } from "../errors/RAGError.js";
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 /**
  * Default chunker configuration
  */
@@ -64,29 +66,41 @@ export class BaseChunker {
      * Chunk content into smaller pieces
      */
     async chunk(content, config) {
-        const effectiveConfig = { ...this.config, ...config };
-        if (!content || content.trim().length === 0) {
-            throw new ChunkingError("Content is empty", {
-                code: RAGErrorCodes.CHUNKING_EMPTY_CONTENT,
-                strategy: this.strategy,
-                contentLength: 0,
-            });
-        }
-        try {
-            const chunks = await this.doChunk(content, effectiveConfig);
-            return this.filterChunks(chunks, effectiveConfig);
-        }
-        catch (error) {
-            if (error instanceof ChunkingError) {
-                throw error;
+        return withSpan({
+            name: "neurolink.rag.chunk",
+            tracer: tracers.rag,
+            attributes: {
+                "rag.chunker.strategy": this.strategy,
+                "rag.chunker.content_chars": content.length,
+                "rag.chunker.content_bytes": Buffer.byteLength(content, "utf8"),
+            },
+        }, async (span) => {
+            const effectiveConfig = { ...this.config, ...config };
+            if (!content || content.trim().length === 0) {
+                throw new ChunkingError("Content is empty", {
+                    code: RAGErrorCodes.CHUNKING_EMPTY_CONTENT,
+                    strategy: this.strategy,
+                    contentLength: 0,
+                });
             }
-            throw new ChunkingError(`Chunking failed: ${error instanceof Error ? error.message : String(error)}`, {
-                code: RAGErrorCodes.CHUNKING_ERROR,
-                cause: error instanceof Error ? error : undefined,
-                strategy: this.strategy,
-                contentLength: content.length,
-            });
-        }
+            try {
+                const chunks = await this.doChunk(content, effectiveConfig);
+                const result = this.filterChunks(chunks, effectiveConfig);
+                span.setAttribute("rag.chunker.chunk_count", result.length);
+                return result;
+            }
+            catch (error) {
+                if (error instanceof ChunkingError) {
+                    throw error;
+                }
+                throw new ChunkingError(`Chunking failed: ${error instanceof Error ? error.message : String(error)}`, {
+                    code: RAGErrorCodes.CHUNKING_ERROR,
+                    cause: error instanceof Error ? error : undefined,
+                    strategy: this.strategy,
+                    contentLength: content.length,
+                });
+            }
+        }); // end withSpan
     }
     /**
      * Filter chunks based on minimum size

package/dist/lib/rag/chunking/jsonChunker.d.ts

@@ -4,7 +4,7 @@
  * Splits JSON documents based on structure (arrays, objects, keys).
  * Best for API responses, configuration files, and structured data.
  */
-import type { Chunker, Chunk, ChunkerValidationResult, JSONChunkerConfig, BaseChunkerConfig } from "../../types/index.js";
+import type { BaseChunkerConfig, Chunk, Chunker, ChunkerValidationResult, JSONChunkerConfig } from "../../types/index.js";
 /**
  * JSON-aware chunker implementation
  * Splits based on JSON structure

package/dist/lib/rag/errors/RAGError.d.ts

@@ -6,6 +6,7 @@
  * Uses the NeuroLinkFeatureError pattern for consistency.
  */
 import { NeuroLinkFeatureError } from "../../core/infrastructure/index.js";
+import type { RAGErrorCode } from "../../types/index.js";
 /**
  * RAG error codes for all RAG-related operations
  */
@@ -43,7 +44,6 @@ export declare const RAGErrorCodes: {
     readonly RETRY_EXHAUSTED: "RAG_RETRY_EXHAUSTED";
     readonly INVALID_CONFIGURATION: "RAG_INVALID_CONFIGURATION";
 };
-type RAGErrorCode = (typeof RAGErrorCodes)[keyof typeof RAGErrorCodes];
 /**
  * RAG error factory using the infrastructure pattern
  */
@@ -242,4 +242,3 @@ export declare function isRetryableRAGError(error: unknown): boolean;
  * Type guard for partial failure errors
  */
 export declare function isPartialFailure(error: unknown): error is PipelineError;
-export {};

package/dist/lib/rag/ragIntegration.js

@@ -13,6 +13,8 @@ import { SpanSerializer, SpanType, SpanStatus, getMetricsAggregator, } from "../
 import { logger } from "../utils/logger.js";
 import { createChunker } from "./ChunkerFactory.js";
 import { createVectorQueryTool, InMemoryVectorStore, } from "./retrieval/vectorQueryTool.js";
+import { withSpan } from "../telemetry/withSpan.js";
+import { tracers } from "../telemetry/tracers.js";
 /**
  * Maps file extensions to recommended chunking strategies
  */
@@ -272,40 +274,51 @@ async function _prepareRAGToolInner(ragConfig, fallbackProvider) {
                 .describe("The search query to find relevant information"),
         }),
         execute: async ({ query }) => {
-            // For the in-memory store with simple embeddings,
-            // generate a query embedding using the same method
-            const queryEmbedding = generateSimpleEmbedding(query, EMBEDDING_DIMENSION);
-            // Fetch more candidates than needed so diversity can select across files
-            const fetchK = fileContents.length > 1 ? topK * 3 : topK;
-            const rawResults = await vectorStore.query({
-                indexName,
-                queryVector: queryEmbedding,
-                topK: fetchK,
-            });
-            // Apply source-file diversity for multi-file RAG
-            const results = fileContents.length > 1
-                ? diversifyResults(rawResults, topK)
-                : rawResults.slice(0, topK);
-            if (results.length === 0) {
+            return withSpan({
+                name: "neurolink.rag.search",
+                tracer: tracers.rag,
+                attributes: {
+                    "rag.query_length": query ? String(query).length : 0,
+                    "rag.top_k": topK ?? 5,
+                },
+            }, async (span) => {
+                // For the in-memory store with simple embeddings,
+                // generate a query embedding using the same method
+                const queryEmbedding = generateSimpleEmbedding(query, EMBEDDING_DIMENSION);
+                // Fetch more candidates than needed so diversity can select across files
+                const fetchK = fileContents.length > 1 ? topK * 3 : topK;
+                const rawResults = await vectorStore.query({
+                    indexName,
+                    queryVector: queryEmbedding,
+                    topK: fetchK,
+                });
+                // Apply source-file diversity for multi-file RAG
+                const results = fileContents.length > 1
+                    ? diversifyResults(rawResults, topK)
+                    : rawResults.slice(0, topK);
+                if (results.length === 0) {
+                    span.setAttribute("rag.results_count", 0);
+                    return {
+                        relevantContext: "No relevant documents found for the query.",
+                        sources: [],
+                        totalResults: 0,
+                    };
+                }
+                const relevantContext = results
+                    .map((r, i) => `[${i + 1}] ${r.metadata?.text || r.text || ""}`)
+                    .join("\n\n");
+                span.setAttribute("rag.results_count", results.length);
                 return {
-                    relevantContext: "No relevant documents found for the query.",
-                    sources: [],
-                    totalResults: 0,
+                    relevantContext,
+                    sources: results.map((r) => ({
+                        id: r.id,
+                        score: r.score,
+                        source: r.metadata?.source,
+                        text: (r.metadata?.text || r.text || "").slice(0, 200),
+                    })),
+                    totalResults: results.length,
                 };
-            }
-            const relevantContext = results
-                .map((r, i) => `[${i + 1}] ${r.metadata?.text || r.text || ""}`)
-                .join("\n\n");
-            return {
-                relevantContext,
-                sources: results.map((r) => ({
-                    id: r.id,
-                    score: r.score,
-                    source: r.metadata?.source,
-                    text: (r.metadata?.text || r.text || "").slice(0, 200),
-                })),
-                totalResults: results.length,
-            };
+            });
         },
     };
     return {