@juspay/neurolink 9.54.5 → 9.54.7

package/dist/rag/retrieval/vectorQueryTool.js

@@ -7,6 +7,8 @@
 import { randomUUID } from "crypto";
 import { z } from "zod";
 import { ProviderFactory } from "../../factories/providerFactory.js";
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 import { logger } from "../../utils/logger.js";
 import { rerank } from "../reranker/reranker.js";
 /**
@@ -46,75 +48,87 @@ export function createVectorQueryTool(config, vectorStore) {
          * @returns Query results with relevant context
          */
         execute: async (params, context) => {
-            const startTime = Date.now();
-            try {
-                // Resolve vector store if it's a function
-                const store = typeof vectorStore === "function"
-                    ? vectorStore(context || {})
-                    : vectorStore;
-                // Generate query embedding
-                const embeddingProvider = await ProviderFactory.createProvider(embeddingModel.provider, embeddingModel.modelName);
-                // Check if provider has embed method
-                if (typeof embeddingProvider.embed !==
-                    "function") {
-                    throw new Error(`Provider ${embeddingModel.provider} does not support embeddings`);
-                }
-                const queryEmbedding = await embeddingProvider.embed(params.query);
-                // Query the vector store
-                let results = await store.query({
-                    indexName,
-                    queryVector: queryEmbedding,
-                    topK: params.topK || topK,
-                    filter: params.filter,
-                    includeVectors,
-                    ...providerOptions,
-                });
-                let reranked = false;
-                // Apply reranking if configured
-                if (rerankerConfig && results.length > 0) {
-                    const rerankerModel = await ProviderFactory.createProvider(typeof rerankerConfig.model === "object"
-                        ? rerankerConfig.model.provider
-                        : rerankerConfig.model, typeof rerankerConfig.model === "object"
-                        ? rerankerConfig.model.modelName
-                        : rerankerConfig.model);
-                    const rerankedResults = await rerank(results, params.query, rerankerModel, {
-                        weights: rerankerConfig.weights,
-                        topK: rerankerConfig.topK,
-                        queryEmbedding,
+            return withSpan({
+                name: "neurolink.rag.vectorQuery",
+                tracer: tracers.rag,
+                attributes: {
+                    "rag.vector.index": indexName,
+                    "rag.vector.top_k": params.topK ?? topK,
+                    "rag.vector.query_length": params.query.length,
+                },
+            }, async (span) => {
+                const startTime = Date.now();
+                try {
+                    // Resolve vector store if it's a function
+                    const store = typeof vectorStore === "function"
+                        ? vectorStore(context || {})
+                        : vectorStore;
+                    // Generate query embedding
+                    const embeddingProvider = await ProviderFactory.createProvider(embeddingModel.provider, embeddingModel.modelName);
+                    // Check if provider has embed method
+                    if (typeof embeddingProvider
+                        .embed !== "function") {
+                        throw new Error(`Provider ${embeddingModel.provider} does not support embeddings`);
+                    }
+                    const queryEmbedding = await embeddingProvider.embed(params.query);
+                    // Query the vector store
+                    let results = await store.query({
+                        indexName,
+                        queryVector: queryEmbedding,
+                        topK: params.topK || topK,
+                        filter: params.filter,
+                        includeVectors,
+                        ...providerOptions,
                     });
-                    results = rerankedResults.map((r) => r.result);
-                    reranked = true;
-                }
-                // Format results
-                const relevantContext = results
-                    .map((r, i) => `[${i + 1}] ${r.metadata?.text || r.text || ""}`)
-                    .join("\n\n");
-                const queryTime = Date.now() - startTime;
-                logger.info("[VectorQueryTool] Query completed", {
-                    query: params.query.slice(0, 50),
-                    resultsCount: results.length,
-                    queryTime,
-                    reranked,
-                    filtered: !!params.filter,
-                });
-                return {
-                    relevantContext,
-                    sources: includeSources ? results : [],
-                    totalResults: results.length,
-                    metadata: {
+                    let reranked = false;
+                    // Apply reranking if configured
+                    if (rerankerConfig && results.length > 0) {
+                        const rerankerModel = await ProviderFactory.createProvider(typeof rerankerConfig.model === "object"
+                            ? rerankerConfig.model.provider
+                            : rerankerConfig.model, typeof rerankerConfig.model === "object"
+                            ? rerankerConfig.model.modelName
+                            : rerankerConfig.model);
+                        const rerankedResults = await rerank(results, params.query, rerankerModel, {
+                            weights: rerankerConfig.weights,
+                            topK: rerankerConfig.topK,
+                            queryEmbedding,
+                        });
+                        results = rerankedResults.map((r) => r.result);
+                        reranked = true;
+                    }
+                    // Format results
+                    const relevantContext = results
+                        .map((r, i) => `[${i + 1}] ${r.metadata?.text || r.text || ""}`)
+                        .join("\n\n");
+                    const queryTime = Date.now() - startTime;
+                    logger.info("[VectorQueryTool] Query completed", {
+                        query: params.query.slice(0, 50),
+                        resultsCount: results.length,
                         queryTime,
                         reranked,
                         filtered: !!params.filter,
-                    },
-                };
-            }
-            catch (error) {
-                logger.error("[VectorQueryTool] Query failed", {
-                    query: params.query.slice(0, 50),
-                    error: error instanceof Error ? error.message : String(error),
-                });
-                throw error;
-            }
+                    });
+                    span.setAttribute("rag.vector.result_count", results.length);
+                    span.setAttribute("rag.vector.reranked", reranked);
+                    return {
+                        relevantContext,
+                        sources: includeSources ? results : [],
+                        totalResults: results.length,
+                        metadata: {
+                            queryTime,
+                            reranked,
+                            filtered: !!params.filter,
+                        },
+                    };
+                }
+                catch (error) {
+                    logger.error("[VectorQueryTool] Query failed", {
+                        query: params.query.slice(0, 50),
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    throw error;
+                }
+            }); // end withSpan
         },
     };
 }

package/dist/sdk/toolRegistration.d.ts

@@ -3,7 +3,7 @@
  * Simple interface for developers to register custom tools
  */
 import { z } from "zod";
-import type { MCPServerInfo, MCPServerCategory, JsonValue, ToolArgs, SimpleTool as CoreSimpleTool, ZodUnknownSchema, SDKToolContext } from "../types/index.js";
+import type { JsonValue, MCPServerCategory, MCPServerInfo, SDKToolContext, SdkSimpleTool, ZodUnknownSchema } from "../types/index.js";
 /**
  * Enhanced validation configuration
  */
@@ -16,44 +16,10 @@ declare const VALIDATION_CONFIG: {
     readonly RECOMMENDED_PATTERNS: readonly ["get_data", "fetch_info", "calculate_value", "send_message", "create_item", "update_record", "delete_file", "validate_input"];
     readonly COMPILED_PATTERN_REGEXES: RegExp[];
 };
-/**
- * Context provided to tools during execution
- * Type alias for backward compatibility
- */
-type ToolContext = SDKToolContext;
-/**
- * Simple tool interface for SDK users
- * Extends the core SimpleTool with specific types
- */
-type SimpleTool<TArgs = ToolArgs, TResult = JsonValue> = Omit<CoreSimpleTool<TArgs, TResult>, "execute"> & {
-    /**
-     * Tool description that helps AI understand when to use it
-     */
-    description: string;
-    /**
-     * Parameters schema using Zod (optional)
-     */
-    parameters?: ZodUnknownSchema;
-    /**
-     * Tool execution function
-     */
-    execute: (params: TArgs, context?: ToolContext) => Promise<TResult>;
-    /**
-     * Optional metadata
-     */
-    metadata?: {
-        category?: string;
-        version?: string;
-        author?: string;
-        tags?: string[];
-        documentation?: string;
-        [key: string]: JsonValue | undefined;
-    };
-};
 /**
  * Creates a MCPServerInfo from a set of tools
  */
-export declare function createMCPServerFromTools(serverId: string, tools: Record<string, SimpleTool>, metadata?: {
+export declare function createMCPServerFromTools(serverId: string, tools: Record<string, SdkSimpleTool>, metadata?: {
     title?: string;
     description?: string;
     category?: MCPServerCategory;
@@ -64,29 +30,29 @@ export declare function createMCPServerFromTools(serverId: string, tools: Record
 /**
  * Helper to create a tool with type safety
  */
-export declare function createTool(config: SimpleTool): SimpleTool;
+export declare function createTool(config: SdkSimpleTool): SdkSimpleTool;
 /**
  * Helper to create a validated tool with suggested improvements
  */
-export declare function createValidatedTool(name: string, config: SimpleTool, options?: {
+export declare function createValidatedTool(name: string, config: SdkSimpleTool, options?: {
     strict?: boolean;
     suggestions?: boolean;
-}): SimpleTool;
+}): SdkSimpleTool;
 /**
  * Helper to create a tool with typed parameters
  */
-export declare function createTypedTool<TParams extends ZodUnknownSchema>(config: Omit<SimpleTool, "execute"> & {
+export declare function createTypedTool<TParams extends ZodUnknownSchema>(config: Omit<SdkSimpleTool, "execute"> & {
     parameters: TParams;
-    execute: (params: z.infer<TParams>, context?: ToolContext) => Promise<JsonValue> | JsonValue;
-}): SimpleTool;
+    execute: (params: z.infer<TParams>, context?: SDKToolContext) => Promise<JsonValue> | JsonValue;
+}): SdkSimpleTool;
 /**
  * Validate tool configuration with detailed error messages
  */
-export declare function validateTool(name: string, tool: SimpleTool): void;
+export declare function validateTool(name: string, tool: SdkSimpleTool): void;
 /**
  * Utility to validate multiple tools at once
  */
-export declare function validateTools(tools: Record<string, SimpleTool>): {
+export declare function validateTools(tools: Record<string, SdkSimpleTool>): {
     valid: string[];
     invalid: Array<{
         name: string;

package/dist/sdk/toolRegistration.js

@@ -168,7 +168,7 @@ function provideToolSuggestions(name, tool) {
  * Helper to create a tool with typed parameters
  */
 export function createTypedTool(config) {
-    // Wrap the typed execute to match SimpleTool's signature.
+    // Wrap the typed execute to match SdkSimpleTool's signature.
     // The Zod schema validates params at runtime, so the cast within the wrapper is safe.
     const wrappedExecute = async (params, context) => {
         const result = await config.execute(params, context);

package/dist/server/middleware/abortSignal.d.ts

@@ -2,16 +2,7 @@
  * Abort Signal Middleware
  * Provides client disconnection handling for long-running requests
  */
-import type { MiddlewareDefinition, ServerContext } from "../../types/index.js";
-/**
- * Abort signal middleware options
- */
-type AbortSignalMiddlewareOptions = {
-    /** Callback when abort is triggered */
-    onAbort?: (ctx: ServerContext) => void;
-    /** Request timeout in milliseconds */
-    timeout?: number;
-};
+import type { AbortSignalMiddlewareOptions, MiddlewareDefinition } from "../../types/index.js";
 /**
  * Create abort signal middleware for handling client disconnections.
  *
@@ -59,4 +50,3 @@ export declare function createExpressAbortMiddleware(options?: AbortSignalMiddle
     writableFinished?: boolean;
     locals: Record<string, unknown>;
 }, next: () => void) => void;
-export {};

package/dist/server/middleware/auth.d.ts

@@ -2,8 +2,7 @@
  * Authentication Middleware
  * Provides flexible authentication support for server adapters
  */
-import type { MiddlewareDefinition, AuthenticatedUser, ServerServerAuthConfig } from "../../types/index.js";
-import type { AuthResult } from "../../types/index.js";
+import type { ApiKeyAuthOptions, AuthResult, AuthenticatedUser, BearerAuthOptions, MiddlewareDefinition, ServerServerAuthConfig, TokenValidator } from "../../types/index.js";
 /**
  * Check if request is from development playground.
  * Detects playground requests via special headers for development mode.
@@ -111,18 +110,6 @@ export declare class ApiKeyStore {
 /**
  * Options for bearer auth middleware
  */
-type BearerAuthOptions = {
-    /** Whether authentication is required (default: true) */
-    required?: boolean;
-    /** Header name (default: "authorization") */
-    headerName?: string;
-    /** Paths to skip authentication */
-    skipPaths?: string[];
-};
-/**
- * Token validation function type
- */
-type TokenValidator = (token: string) => Promise<AuthenticatedUser | null> | AuthenticatedUser | null;
 /**
  * Create bearer token authentication middleware
  *
@@ -141,12 +128,6 @@ export declare function createBearerAuthMiddleware(validate: TokenValidator, opt
 /**
  * Options for API key auth middleware
  */
-type ApiKeyAuthOptions = {
-    /** Header name (default: "x-api-key") */
-    headerName?: string;
-    /** Paths to skip authentication */
-    skipPaths?: string[];
-};
 /**
  * Create API key authentication middleware
  *
@@ -183,4 +164,3 @@ export declare function createRoleAuthMiddleware(requiredRoles: string[], option
 export declare function createPermissionAuthMiddleware(requiredPermissions: string[], options?: {
     requireAll?: boolean;
 }): MiddlewareDefinition;
-export {};

package/dist/server/middleware/auth.js

@@ -246,6 +246,12 @@ export class ApiKeyStore {
         return this.keys.size;
     }
 }
+// ============================================
+// Bearer Token Authentication
+// ============================================
+/**
+ * Options for bearer auth middleware
+ */
 /**
  * Create bearer token authentication middleware
  *
@@ -292,6 +298,12 @@ export function createBearerAuthMiddleware(validate, options = {}) {
         },
     };
 }
+// ============================================
+// API Key Authentication
+// ============================================
+/**
+ * Options for API key auth middleware
+ */
 /**
  * Create API key authentication middleware
  *

package/dist/server/middleware/common.js

@@ -3,6 +3,8 @@
  * Utility middleware for common server operations
  */
 import { getMetricsAggregator, SpanSerializer, SpanStatus, SpanType, } from "../../observability/index.js";
+import { SpanStatusCode } from "@opentelemetry/api";
+import { tracers } from "../../telemetry/tracers.js";
 import { logger } from "../../utils/logger.js";
 /**
  * Create request timing middleware
@@ -18,38 +20,52 @@ export function createTimingMiddleware() {
         name: "timing",
         order: 0, // Run first
         handler: async (ctx, next) => {
-            const startTime = Date.now();
-            const startHrTime = process.hrtime.bigint();
-            // Store start time in metadata
-            ctx.metadata.requestStartTime = startTime;
-            const span = SpanSerializer.createSpan(SpanType.SERVER_REQUEST, "server.middleware.timing", {
-                "server.operation": "middleware",
-                "server.middleware": "timing",
-            });
-            try {
-                const result = await next();
-                // Calculate duration
-                const endHrTime = process.hrtime.bigint();
-                const durationNs = Number(endHrTime - startHrTime);
-                const durationMs = durationNs / 1_000_000;
-                // Add timing headers to responseHeaders (adapters read from here)
-                ctx.responseHeaders = ctx.responseHeaders || {};
-                ctx.responseHeaders["X-Response-Time"] = `${durationMs.toFixed(2)}ms`;
-                ctx.responseHeaders["Server-Timing"] =
-                    `total;dur=${durationMs.toFixed(2)}`;
-                span.durationMs = Date.now() - startTime;
-                const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
-                getMetricsAggregator().recordSpan(endedSpan);
-                return result;
-            }
-            catch (error) {
-                span.durationMs = Date.now() - startTime;
-                const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
-                endedSpan.statusMessage =
-                    error instanceof Error ? error.message : String(error);
-                getMetricsAggregator().recordSpan(endedSpan);
-                throw error;
-            }
+            return tracers.middleware.startActiveSpan("neurolink.middleware.timing", async (otelSpan) => {
+                try {
+                    const startTime = Date.now();
+                    const startHrTime = process.hrtime.bigint();
+                    // Store start time in metadata
+                    ctx.metadata.requestStartTime = startTime;
+                    const span = SpanSerializer.createSpan(SpanType.SERVER_REQUEST, "server.middleware.timing", {
+                        "server.operation": "middleware",
+                        "server.middleware": "timing",
+                    });
+                    try {
+                        const result = await next();
+                        // Calculate duration
+                        const endHrTime = process.hrtime.bigint();
+                        const durationNs = Number(endHrTime - startHrTime);
+                        const durationMs = durationNs / 1_000_000;
+                        // Add timing headers to responseHeaders (adapters read from here)
+                        ctx.responseHeaders = ctx.responseHeaders || {};
+                        ctx.responseHeaders["X-Response-Time"] =
+                            `${durationMs.toFixed(2)}ms`;
+                        ctx.responseHeaders["Server-Timing"] =
+                            `total;dur=${durationMs.toFixed(2)}`;
+                        span.durationMs = Date.now() - startTime;
+                        const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+                        getMetricsAggregator().recordSpan(endedSpan);
+                        return result;
+                    }
+                    catch (error) {
+                        // Propagate error to OTel span so traces show ERROR status
+                        otelSpan.recordException(error instanceof Error ? error : new Error(String(error)));
+                        otelSpan.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                        span.durationMs = Date.now() - startTime;
+                        const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+                        endedSpan.statusMessage =
+                            error instanceof Error ? error.message : String(error);
+                        getMetricsAggregator().recordSpan(endedSpan);
+                        throw error;
+                    }
+                }
+                finally {
+                    otelSpan.end();
+                }
+            }); // end startActiveSpan
         },
     };
 }

package/dist/server/middleware/deprecation.d.ts

@@ -4,25 +4,7 @@
  *
  * @see https://datatracker.ietf.org/doc/html/rfc8594 - The 'Deprecation' HTTP Header Field
  */
-import type { MiddlewareDefinition, RouteDefinition } from "../../types/index.js";
-/**
- * Deprecation middleware configuration
- */
-type DeprecationConfig = {
-    /**
-     * Array of route definitions to check for deprecation
-     * Routes with `deprecated.enabled: true` will have deprecation headers added
-     */
-    routes: RouteDefinition[];
-    /**
-     * Custom header name for deprecation notice (default: "X-Deprecation-Notice")
-     */
-    noticeHeader?: string;
-    /**
-     * Whether to include Link header for alternative routes (default: true)
-     */
-    includeLink?: boolean;
-};
+import type { DeprecationConfig, MiddlewareDefinition } from "../../types/index.js";
 /**
  * Create deprecation middleware
  *
@@ -56,4 +38,3 @@ type DeprecationConfig = {
  * ```
  */
 export declare function createDeprecationMiddleware(config: DeprecationConfig): MiddlewareDefinition;
-export {};

package/dist/server/middleware/rateLimit.d.ts

@@ -2,64 +2,7 @@
  * Rate Limiting Middleware
  * Provides configurable rate limiting for server adapters
  */
-import type { MiddlewareDefinition, ServerContext } from "../../types/index.js";
-/**
- * Rate limit middleware configuration
- */
-type RateLimitMiddlewareConfig = {
-    /** Maximum requests per window */
-    maxRequests: number;
-    /** Time window in milliseconds */
-    windowMs: number;
-    /** Custom error message */
-    message?: string;
-    /** Skip rate limiting for certain paths */
-    skipPaths?: string[];
-    /**
-     * Custom key generator for identifying clients
-     * Default: IP address
-     */
-    keyGenerator?: (ctx: ServerContext) => string;
-    /**
-     * Custom response handler for rate limit exceeded
-     */
-    onRateLimitExceeded?: (ctx: ServerContext, retryAfter: number) => unknown;
-    /**
-     * Custom rate limit store
-     * Default: in-memory store
-     */
-    store?: RateLimitStore;
-};
-/**
- * Rate limit entry
- */
-type RateLimitEntry = {
-    count: number;
-    resetAt: number;
-};
-/**
- * Rate limit store interface
- * Implement this for custom storage (Redis, etc.)
- */
-type RateLimitStore = {
-    /**
-     * Get the current entry for a key
-     */
-    get(key: string): Promise<RateLimitEntry | undefined>;
-    /**
-     * Set an entry for a key
-     */
-    set(key: string, entry: RateLimitEntry): Promise<void>;
-    /**
-     * Increment the counter for a key
-     * Returns the current count and reset time
-     */
-    increment(key: string, windowMs: number): Promise<RateLimitEntry>;
-    /**
-     * Reset the counter for a key
-     */
-    reset(key: string): Promise<void>;
-};
+import type { FixedWindowRateLimitConfig, MiddlewareDefinition, RateLimitEntry, RateLimitMiddlewareConfig, RateLimitStore } from "../../types/index.js";
 /**
  * In-memory rate limit store
  */
@@ -113,23 +56,6 @@ export declare function createSlidingWindowRateLimitMiddleware(config: RateLimit
  * Alias for InMemoryRateLimitStore for compatibility
  */
 export { InMemoryRateLimitStore as MemoryRateLimitStore };
-/**
- * Fixed window rate limit configuration (for standalone signature)
- */
-type FixedWindowRateLimitConfig = {
-    /** Maximum requests per window */
-    maxRequests: number;
-    /** Time window in milliseconds */
-    windowMs: number;
-    /** Custom error message */
-    message?: string;
-    /** Skip rate limiting for certain paths */
-    skipPaths?: string[];
-    /** Custom key generator */
-    keyGenerator?: (ctx: ServerContext) => string;
-    /** Custom rate limit exceeded handler */
-    onRateLimitExceeded?: (ctx: ServerContext, retryAfter: number) => unknown;
-};
 /**
  * Create fixed window rate limit middleware
  *