@juspay/neurolink 9.54.6 → 9.54.8

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
  *

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

@@ -2,69 +2,7 @@
  * Request Validation Middleware
  * Provides schema-based request validation for server adapters
  */
-import type { MiddlewareDefinition, ServerContext } from "../../types/index.js";
-import { ValidationError as ServerValidationError } from "../errors.js";
-/**
- * Validation configuration
- */
-type ValidationConfig = {
-    /** Schema for validating request body */
-    bodySchema?: ValidationSchema;
-    /** Schema for validating query parameters */
-    querySchema?: ValidationSchema;
-    /** Schema for validating path parameters */
-    paramsSchema?: ValidationSchema;
-    /** Schema for validating headers */
-    headersSchema?: ValidationSchema;
-    /**
-     * Custom validation function
-     * Throw ValidationError for invalid requests
-     */
-    customValidator?: (ctx: ServerContext) => Promise<void>;
-    /** Skip validation for certain paths */
-    skipPaths?: string[];
-    /** Custom error formatter */
-    errorFormatter?: (errors: ServerValidationError[]) => unknown;
-};
-/**
- * Simple validation schema
- * Can be extended with JSON Schema or Zod integration
- */
-type ValidationSchema = {
-    /** Required fields */
-    required?: string[];
-    /** Field type definitions */
-    properties?: Record<string, PropertySchema>;
-    /** Allow additional properties */
-    additionalProperties?: boolean;
-};
-/**
- * Property schema definition
- */
-type PropertySchema = {
-    /** Property type */
-    type: "string" | "number" | "boolean" | "object" | "array";
-    /** Minimum value (for numbers) or length (for strings/arrays) */
-    minimum?: number;
-    /** Maximum value (for numbers) or length (for strings/arrays) */
-    maximum?: number;
-    /** Minimum length for strings (alias for minimum) */
-    minLength?: number;
-    /** Maximum length for strings (alias for maximum) */
-    maxLength?: number;
-    /** Minimum items for arrays */
-    minItems?: number;
-    /** Maximum items for arrays */
-    maxItems?: number;
-    /** Pattern for string validation (regex) */
-    pattern?: string;
-    /** Enum of allowed values */
-    enum?: unknown[];
-    /** Default value */
-    default?: unknown;
-    /** Custom validation function */
-    validate?: (value: unknown) => boolean | string;
-};
+import type { ExtendedValidationSchema, MiddlewareDefinition, MiddlewareRequestSchema, PropertySchema, ValidationConfig } from "../../types/index.js";
 /**
  * Re-export ValidationError from errors for convenience
  */
@@ -105,7 +43,7 @@ export declare function createFieldValidator(fieldName: string, rules: PropertyS
  * });
  * ```
  */
-export declare function createBodyValidationMiddleware(schema: ValidationSchema): MiddlewareDefinition;
+export declare function createBodyValidationMiddleware(schema: MiddlewareRequestSchema): MiddlewareDefinition;
 /**
  * Create query-only validation middleware
  *
@@ -119,28 +57,12 @@ export declare function createBodyValidationMiddleware(schema: ValidationSchema)
  * });
  * ```
  */
-export declare function createQueryValidationMiddleware(schema: ValidationSchema): MiddlewareDefinition;
+export declare function createQueryValidationMiddleware(schema: MiddlewareRequestSchema): MiddlewareDefinition;
 /**
  * Create a combined validation middleware with full config support
  * Alias for createRequestValidationMiddleware for compatibility
  */
 export declare const createValidationMiddleware: typeof createRequestValidationMiddleware;
-/**
- * Extended property schema for common schemas
- */
-type ExtendedPropertySchema = PropertySchema & {
-    format?: string;
-};
-/**
- * Extended validation schema for common schemas
- */
-type ExtendedValidationSchema = {
-    type?: string;
-    format?: string;
-    required?: string[];
-    properties?: Record<string, ExtendedPropertySchema>;
-    additionalProperties?: boolean;
-};
 /**
  * Common validation schemas for reuse
  */

package/dist/server/middleware/validation.js

@@ -287,6 +287,9 @@ export function createQueryValidationMiddleware(schema) {
  * Alias for createRequestValidationMiddleware for compatibility
  */
 export const createValidationMiddleware = createRequestValidationMiddleware;
+// ============================================
+// Common Schemas
+// ============================================
 /**
  * Common validation schemas for reuse
  */

package/dist/server/openapi/generator.d.ts

@@ -2,52 +2,7 @@
  * OpenAPI 3.1 Specification Generator
  * Generates OpenAPI documentation from NeuroLink server routes
  */
-import type { JsonObject, RouteDefinition, ServerAdapterConfig } from "../../types/index.js";
-/**
- * OpenAPI generator configuration
- */
-type OpenAPIGeneratorConfig = {
-    /** API info override */
-    info?: {
-        title?: string;
-        version?: string;
-        description?: string;
-    };
-    /** Server configuration */
-    servers?: Array<{
-        url: string;
-        description?: string;
-    }>;
-    /** Include security schemes */
-    includeSecurity?: boolean;
-    /** Base path for all routes */
-    basePath?: string;
-    /** Additional tags */
-    additionalTags?: Array<{
-        name: string;
-        description: string;
-    }>;
-    /** Custom schemas to add */
-    customSchemas?: Record<string, JsonObject>;
-    /** Routes to document in the OpenAPI spec */
-    routes?: RouteDefinition[];
-};
-/**
- * Generated OpenAPI specification
- */
-type OpenAPISpec = {
-    openapi: "3.1.0";
-    info: JsonObject;
-    servers: JsonObject[];
-    tags: JsonObject[];
-    paths: Record<string, JsonObject>;
-    components: {
-        schemas: Record<string, JsonObject>;
-        securitySchemes?: Record<string, JsonObject>;
-        parameters?: Record<string, JsonObject>;
-    };
-    security?: JsonObject[];
-};
+import type { OpenAPIGeneratorConfig, OpenAPISpec, RouteDefinition, ServerAdapterConfig } from "../../types/index.js";
 /**
  * OpenAPI specification generator
  * Generates OpenAPI 3.1 compliant documentation from route definitions
@@ -104,4 +59,3 @@ export declare function generateOpenAPISpec(routes: RouteDefinition[], config?:
  * Generate OpenAPI spec from server adapter configuration
  */
 export declare function generateOpenAPIFromConfig(serverConfig: ServerAdapterConfig, routes?: RouteDefinition[]): OpenAPISpec;
-export {};

package/dist/server/routes/agentRoutes.js

@@ -2,7 +2,10 @@
  * Agent Routes
  * Endpoints for agent execution and streaming
  */
+import { SpanStatusCode } from "@opentelemetry/api";
 import { ProviderFactory } from "../../factories/providerFactory.js";
+import { withSpan } from "../../telemetry/withSpan.js";
+import { tracers } from "../../telemetry/tracers.js";
 import { createStreamRedactor } from "../utils/redaction.js";
 import { AgentExecuteRequestSchema, createErrorResponse as createError, EmbedManyRequestSchema, EmbedRequestSchema, validateRequest, } from "../utils/validation.js";
 /**
@@ -22,43 +25,53 @@ export function createAgentRoutes(basePath = "/api") {
                         return validation.error;
                     }
                     const request = validation.data;
-                    // Normalize input
-                    const input = typeof request.input === "string"
-                        ? { text: request.input }
-                        : request.input;
-                    const result = await ctx.neurolink.generate({
-                        input,
-                        provider: request.provider,
-                        model: request.model,
-                        systemPrompt: request.systemPrompt,
-                        temperature: request.temperature,
-                        maxTokens: request.maxTokens,
-                        // Note: tools should be passed as Record<string, Tool> in generate options
-                        // If request.tools is an array of tool names, we skip them
-                        context: {
-                            // When an authenticated user context exists (set by auth middleware),
-                            // always use its IDs to prevent caller-supplied impersonation.
-                            sessionId: ctx.user
-                                ? ctx.session?.id
-                                : (ctx.session?.id ?? request.sessionId),
-                            userId: ctx.user ? ctx.user.id : request.userId,
-                            userEmail: ctx.user?.email,
-                            userRoles: ctx.user?.roles,
-                            requestId: ctx.requestId,
+                    return withSpan({
+                        name: "neurolink.http.execute",
+                        tracer: tracers.http,
+                        attributes: {
+                            "http.route": "/api/agent/execute",
+                            "ai.provider": request.provider || "default",
+                            "ai.model": request.model || "default",
                         },
-                    });
-                    // Map tool calls from SDK format to API format
-                    const toolCalls = result.toolCalls?.map((tc) => ({
-                        name: tc.toolName,
-                        arguments: tc.args,
-                    }));
-                    return {
-                        content: result.content || "",
-                        provider: result.provider || request.provider || "unknown",
-                        model: result.model || request.model || "unknown",
-                        usage: result.usage,
-                        toolCalls,
-                    };
+                    }, async () => {
+                        // Normalize input
+                        const input = typeof request.input === "string"
+                            ? { text: request.input }
+                            : request.input;
+                        const result = await ctx.neurolink.generate({
+                            input,
+                            provider: request.provider,
+                            model: request.model,
+                            systemPrompt: request.systemPrompt,
+                            temperature: request.temperature,
+                            maxTokens: request.maxTokens,
+                            // Note: tools should be passed as Record<string, Tool> in generate options
+                            // If request.tools is an array of tool names, we skip them
+                            context: {
+                                // When an authenticated user context exists (set by auth middleware),
+                                // always use its IDs to prevent caller-supplied impersonation.
+                                sessionId: ctx.user
+                                    ? ctx.session?.id
+                                    : (ctx.session?.id ?? request.sessionId),
+                                userId: ctx.user ? ctx.user.id : request.userId,
+                                userEmail: ctx.user?.email,
+                                userRoles: ctx.user?.roles,
+                                requestId: ctx.requestId,
+                            },
+                        });
+                        // Map tool calls from SDK format to API format
+                        const toolCalls = result.toolCalls?.map((tc) => ({
+                            name: tc.toolName,
+                            arguments: tc.args,
+                        }));
+                        return {
+                            content: result.content || "",
+                            provider: result.provider || request.provider || "unknown",
+                            model: result.model || request.model || "unknown",
+                            usage: result.usage,
+                            toolCalls,
+                        };
+                    }); // end withSpan
                 },
                 description: "Execute agent with prompt",
                 tags: ["agent"],
@@ -99,11 +112,32 @@ export function createAgentRoutes(basePath = "/api") {
                     });
                     // Create redactor (no-op if redaction is not enabled)
                     const redactor = createStreamRedactor(ctx.redaction);
-                    // Wrap stream to apply redaction to each chunk
+                    // Wrap stream with a span that stays open for the full consumption
+                    // lifetime, not just the generator creation.
                     async function* redactedStream() {
-                        for await (const chunk of result.stream) {
-                            // Apply redaction to chunk (returns unchanged if redaction disabled)
-                            yield redactor(chunk);
+                        const streamSpan = tracers.http.startSpan("neurolink.http.stream", {
+                            attributes: {
+                                "http.route": "/api/agent/stream",
+                                "ai.provider": request.provider || "default",
+                                "ai.model": request.model || "default",
+                            },
+                        });
+                        try {
+                            for await (const chunk of result.stream) {
+                                yield redactor(chunk);
+                            }
+                            streamSpan.setStatus({ code: SpanStatusCode.OK });
+                        }
+                        catch (err) {
+                            streamSpan.recordException(err instanceof Error ? err : new Error(String(err)));
+                            streamSpan.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: err instanceof Error ? err.message : String(err),
+                            });
+                            throw err;
+                        }
+                        finally {
+                            streamSpan.end();
                         }
                     }
                     return redactedStream();
@@ -136,14 +170,24 @@ export function createAgentRoutes(basePath = "/api") {
                     const request = validation.data;
                     try {
                         const providerName = request.provider || "openai";
-                        const provider = await ProviderFactory.createProvider(providerName, request.model);
-                        const embedding = await provider.embed(request.text, request.model);
-                        return {
-                            embedding,
-                            provider: providerName,
-                            model: request.model || "default",
-                            dimension: embedding.length,
-                        };
+                        return await withSpan({
+                            name: "neurolink.http.embed",
+                            tracer: tracers.http,
+                            attributes: {
+                                "http.route": "/api/agent/embed",
+                                "ai.provider": providerName,
+                                "ai.model": request.model || "default",
+                            },
+                        }, async () => {
+                            const provider = await ProviderFactory.createProvider(providerName, request.model);
+                            const embedding = await provider.embed(request.text, request.model);
+                            return {
+                                embedding,
+                                provider: providerName,
+                                model: request.model || "default",
+                                dimension: embedding.length,
+                            };
+                        });
                     }
                     catch (error) {
                         return createError("EXECUTION_FAILED", error instanceof Error
@@ -165,15 +209,26 @@ export function createAgentRoutes(basePath = "/api") {
                     const request = validation.data;
                     try {
                         const providerName = request.provider || "openai";
-                        const provider = await ProviderFactory.createProvider(providerName, request.model);
-                        const embeddings = await provider.embedMany(request.texts, request.model);
-                        return {
-                            embeddings,
-                            provider: providerName,
-                            model: request.model || "default",
-                            count: embeddings.length,
-                            dimension: embeddings[0]?.length ?? 0,
-                        };
+                        return await withSpan({
+                            name: "neurolink.http.embedMany",
+                            tracer: tracers.http,
+                            attributes: {
+                                "http.route": "/api/agent/embed-many",
+                                "ai.provider": providerName,
+                                "ai.model": request.model || "default",
+                                "ai.embed.count": request.texts.length,
+                            },
+                        }, async () => {
+                            const provider = await ProviderFactory.createProvider(providerName, request.model);
+                            const embeddings = await provider.embedMany(request.texts, request.model);
+                            return {
+                                embeddings,
+                                provider: providerName,
+                                model: request.model || "default",
+                                count: embeddings.length,
+                                dimension: embeddings[0]?.length ?? 0,
+                            };
+                        });
                     }
                     catch (error) {
                         return createError("EXECUTION_FAILED", error instanceof Error

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

@@ -10,7 +10,7 @@
  * Without a router, models are passed through to the Anthropic provider.
  */
 import type { ModelRouter } from "../../proxy/modelRouter.js";
-import type { ParsedClaudeRequest, RouteGroup } from "../../types/index.js";
+import type { ParsedClaudeError, ParsedClaudeRequest, RouteGroup } from "../../types/index.js";
 /**
  * Create Claude-compatible proxy routes.
  *
@@ -23,10 +23,6 @@ import type { ParsedClaudeRequest, RouteGroup } from "../../types/index.js";
  */
 export declare function createClaudeProxyRoutes(modelRouter?: ModelRouter, basePath?: string, accountStrategy?: "round-robin" | "fill-first", passthroughMode?: boolean): RouteGroup;
 export declare function getTransientSameAccountRetryDelayMs(retryNumber: number): number;
-type ParsedClaudeError = {
-    errorType?: string;
-    message?: string;
-};
 /**
  * Parse a Claude error payload when available.
  */
@@ -46,4 +42,3 @@ export declare function buildProxyFallbackOptions(parsed: ParsedClaudeRequest, o
  * carry transient HTML responses (e.g. 520 pages) inside `error.message`.
  */
 export declare function isTransientHttpFailure(status: number, errBody: string): boolean;
-export {};