@juspay/neurolink 9.30.0 → 9.31.0

package/dist/types/ragTypes.d.ts

@@ -181,7 +181,6 @@ export type RAGCircuitBreakerStats = {
     averageLatency: number;
     p95Latency: number;
 };
-import type { CircuitState } from "../rag/resilience/CircuitBreaker.js";
 /**
  * Embedding model configuration
  */
@@ -487,3 +486,52 @@ export type DocumentLoader = {
      */
     canHandle(source: string): boolean;
 };
+/** Circuit breaker state. */
+export type CircuitState = "closed" | "open" | "half-open";
+/** Event map for RAG circuit breaker. */
+export type RAGCircuitBreakerEvents = {
+    stateChange: [
+        {
+            oldState: CircuitState;
+            newState: CircuitState;
+            reason: string;
+            timestamp: Date;
+        }
+    ];
+    callSuccess: [{
+        duration: number;
+        timestamp: Date;
+        operationType?: string;
+    }];
+    callFailure: [
+        {
+            error: string;
+            duration: number;
+            timestamp: Date;
+            operationType?: string;
+        }
+    ];
+    circuitOpen: [{
+        failureRate: number;
+        totalCalls: number;
+        timestamp: Date;
+    }];
+    circuitHalfOpen: [{
+        timestamp: Date;
+    }];
+    circuitClosed: [{
+        timestamp: Date;
+    }];
+};
+import type { Tool } from "ai";
+/** Prepared RAG tool ready for injection into generate/stream. */
+export type RAGPreparedTool = {
+    /** The tool to inject into the tools Record */
+    tool: Tool;
+    /** Tool name (key for the tools Record) */
+    toolName: string;
+    /** Number of chunks indexed */
+    chunksIndexed: number;
+    /** Number of files loaded */
+    filesLoaded: number;
+};

package/dist/types/streamTypes.d.ts

@@ -269,7 +269,7 @@ export type StreamOptions = {
      *
      * Enables extended thinking capabilities for supported models.
      *
-     * **Gemini 3 Models** (gemini-3-pro-preview, gemini-3-flash-preview):
+     * **Gemini 3 Models** (gemini-3.1-pro-preview, gemini-3-flash-preview):
      * Use `thinkingLevel` to control reasoning depth:
      * - `minimal` - Near-zero thinking (Flash only)
      * - `low` - Fast reasoning for simple tasks
@@ -284,7 +284,7 @@ export type StreamOptions = {
      * const result = await neurolink.stream({
      *   input: { text: "Solve this complex problem..." },
      *   provider: "google-ai",
-     *   model: "gemini-3-pro-preview",
+     *   model: "gemini-3.1-pro-preview",
      *   thinkingConfig: {
      *     thinkingLevel: "high"
      *   }
@@ -511,28 +511,52 @@ export type EnhancedStreamProvider = {
     isAvailable(): Promise<boolean>;
 };
 /**
- * Stream text result from AI SDK
+ * Stream text result from AI SDK (compatible with both v4 and v6)
+ *
+ * AI SDK v6 changed Promise → PromiseLike and renamed usage fields
+ * (promptTokens → inputTokens, completionTokens → outputTokens).
+ * This type accepts either shape so callers don't need casts.
  */
 export type StreamTextResult = {
     textStream: AsyncIterable<string>;
-    text: Promise<string>;
-    usage: Promise<AISDKUsage | undefined>;
-    response: Promise<{
+    fullStream?: AsyncIterable<unknown>;
+    text: PromiseLike<string>;
+    usage: PromiseLike<AISDKUsage | undefined>;
+    response: PromiseLike<{
         id?: string;
         model?: string;
         timestamp?: number | Date;
     } | undefined>;
-    finishReason: Promise<"stop" | "length" | "content-filter" | "tool-calls" | "error" | "other" | "unknown">;
-    toolResults?: Promise<ToolResult[]>;
-    toolCalls?: Promise<ToolCall[]>;
+    finishReason: PromiseLike<"stop" | "length" | "content-filter" | "tool-calls" | "error" | "other" | "unknown">;
+    /**
+     * Tool results. Accepts both NeuroLink ToolResult[] and AI SDK TypedToolResult[],
+     * since the analytics collector passes them through as `unknown` anyway.
+     */
+    toolResults?: PromiseLike<ToolResult[] | ReadonlyArray<unknown>>;
+    /**
+     * Tool calls. Accepts both NeuroLink ToolCall[] and AI SDK TypedToolCall[].
+     */
+    toolCalls?: PromiseLike<ToolCall[] | ReadonlyArray<unknown>>;
 };
 /**
- * Raw usage data from Vercel AI SDK
+ * Raw usage data from Vercel AI SDK.
+ *
+ * Covers both v4 (promptTokens / completionTokens) and
+ * v6 (inputTokens / outputTokens) field names.
+ * extractTokenUsage() in tokenUtils.ts already handles both shapes.
  */
 export type AISDKUsage = {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
+    /** @deprecated AI SDK v4 name — use inputTokens */
+    promptTokens?: number;
+    /** @deprecated AI SDK v4 name — use outputTokens */
+    completionTokens?: number;
+    /** @deprecated AI SDK v4 name — use totalTokens */
+    totalTokens?: number;
+    /** AI SDK v6 name for prompt / input tokens */
+    inputTokens?: number;
+    /** AI SDK v6 name for completion / output tokens */
+    outputTokens?: number;
+    [key: string]: unknown;
 };
 /**
  * Stream analytics collector type

package/dist/types/subscriptionTypes.d.ts

@@ -4,6 +4,8 @@
  * Type definitions for Claude subscription tiers, authentication methods,
  * and usage tracking for Anthropic API access.
  */
+import type { StoredOAuthTokens } from "./authTypes.js";
+export type { StoredOAuthTokens, TokenRefresher, TokenStorageData, StoredProviderTokens, } from "./authTypes.js";
 /**
  * Claude subscription tier levels
  *
@@ -891,3 +893,78 @@ export interface AnthropicModelMetadata {
     /** Short description of the model */
     description: string;
 }
+/** A single Claude account in the pool */
+export interface ProxyAccount {
+    id: string;
+    label?: string;
+    type: "oauth" | "api_key";
+    tokens?: StoredOAuthTokens;
+    apiKey?: string;
+    status: "healthy" | "cooling" | "disabled";
+    cooldownUntil?: number;
+    consecutiveFailures: number;
+    requestCount: number;
+    lastUsed: number;
+    subscriptionTier?: ClaudeSubscriptionTier;
+}
+/** Configuration for AccountPool */
+export interface AccountPoolConfig {
+    strategy: "round-robin" | "fill-first";
+    defaultCooldownMs?: number;
+    maxCooldownMs?: number;
+    maxRetryAccounts?: number;
+}
+/** A single model mapping entry */
+export interface ModelMapping {
+    from: string;
+    to: string;
+    provider: string;
+}
+/** A fallback chain entry */
+export interface FallbackEntry {
+    provider: string;
+    model: string;
+}
+/** Full proxy routing config */
+export interface ProxyRoutingConfig {
+    strategy: "round-robin" | "fill-first";
+    modelMappings: ModelMapping[];
+    fallbackChain: FallbackEntry[];
+    passthroughModels?: string[];
+}
+/** Cloaking plugin config */
+export interface CloakingConfig {
+    mode: "auto" | "always" | "never";
+    plugins: {
+        headerScrubber?: boolean;
+        sessionIdentity?: boolean;
+        systemPromptInjector?: boolean;
+        wordObfuscator?: {
+            enabled: boolean;
+            words: string[];
+        };
+        tlsFingerprint?: {
+            enabled: boolean;
+        };
+    };
+}
+/** Full proxy config (loaded from YAML) */
+export interface ProxyConfig {
+    host?: string;
+    port?: number;
+    auth?: "none" | "api-key";
+    proxyApiKey?: string;
+    /** Provider-keyed account map matching the YAML structure (e.g. accounts.anthropic[0]) */
+    accounts?: Record<string, Array<{
+        name: string;
+        apiKey?: string;
+        weight?: number;
+        rateLimit?: number;
+        enabled?: boolean;
+        baseUrl?: string;
+        orgId?: string;
+        metadata?: Record<string, unknown>;
+    }>>;
+    routing?: Partial<ProxyRoutingConfig>;
+    cloaking?: CloakingConfig;
+}

package/dist/types/subscriptionTypes.js

@@ -5,3 +5,5 @@
  * and usage tracking for Anthropic API access.
  */
 export {};
+// TokenStorageData and StoredProviderTokens are now in authTypes.ts and
+// re-exported at the top of this file for backward compatibility.

package/dist/types/tools.d.ts

@@ -9,7 +9,7 @@ import type { ValidationError } from "../utils/parameterValidation.js";
 /**
  * Commonly used Zod schema type aliases for cleaner type declarations
  */
-export type { ZodUnknownSchema } from "./typeAliases.js";
+export type { ZodUnknownSchema, ZodToJsonSchemaInput } from "./typeAliases.js";
 export type ZodAnySchema = z.ZodSchema<unknown>;
 export type ZodObjectSchema = z.ZodObject<z.ZodRawShape>;
 export type ZodStringSchema = z.ZodString;
@@ -43,6 +43,7 @@ export type ExecutionContext<T = StandardRecord> = {
     cacheOptions?: CacheOptions;
     fallbackOptions?: FallbackOptions;
     timeoutMs?: number;
+    maxRetries?: number;
     startTime?: number;
 };
 /**
@@ -77,6 +78,9 @@ export type ToolInfo = {
     outputSchema?: StandardRecord;
     /** MCP tool annotations (safety hints, metadata). Auto-inferred when mcp.annotations.autoInfer is enabled. */
     annotations?: import("../mcp/toolAnnotations.js").MCPToolAnnotations;
+    /** Per-tool timeout in milliseconds, set at registration time */
+    timeoutMs?: number;
+    maxRetries?: number;
     [key: string]: unknown;
 };
 /**
@@ -90,19 +94,59 @@ export type ToolImplementation = {
     outputSchema?: unknown;
     category?: string;
     permissions?: string[];
+    /** Per-tool timeout in milliseconds, set at registration time */
+    timeoutMs?: number;
+    maxRetries?: number;
 };
 /**
  * Tool execution options for enhanced control
  * Extracted from toolRegistry.ts for centralized type management
  */
 export type ToolExecutionOptions = {
+    /**
+     * Caller-specified execution timeout in milliseconds.
+     * Used by executeTool() callers to override the default timeout for a
+     * single invocation. Takes precedence over `timeoutMs` when both are set.
+     */
     timeout?: number;
     retries?: number;
     context?: unknown;
     preferredSource?: string;
     fallbackEnabled?: boolean;
     validateBeforeExecution?: boolean;
+    /**
+     * Per-tool timeout in milliseconds, copied from ToolInfo at registration
+     * time. Acts as the tool-level default; overridden by `timeout` when the
+     * caller supplies an explicit value.
+     * @deprecated Prefer using `timeout` for caller-specified overrides.
+     *             This field exists for internal forwarding from ToolInfo and
+     *             may be consolidated in a future release.
+     */
     timeoutMs?: number;
+    maxRetries?: number;
+};
+/**
+ * Options for tool registration via registerTool()
+ *
+ * These options configure per-tool execution behavior. When not provided,
+ * the SDK's global defaults are used (30s timeout, 2 retries), preserving
+ * backward compatibility with existing production systems.
+ *
+ * @example
+ * // Register with custom timeout and no retries
+ * sdk.registerTool("myTool", tool, { timeout: 5000, maxRetries: 0 });
+ *
+ * // Register with defaults (same as before — no behavior change)
+ * sdk.registerTool("myTool", tool);
+ */
+export type ToolRegistrationOptions = {
+    /** Per-tool execution timeout in milliseconds. Only applied when explicitly set.
+     *  When omitted, the SDK's global default (30s) is used. */
+    timeout?: number;
+    /** Maximum retry attempts on failure. Only applied when explicitly set.
+     *  When omitted, the SDK's global default (2 retries) is used.
+     *  Set to 0 to disable retries for this tool. */
+    maxRetries?: number;
 };
 /**
  * Tool execution result

package/dist/types/typeAliases.d.ts

@@ -5,12 +5,20 @@
 import type { ZodTypeAny } from "zod";
 import type { Schema } from "ai";
 import type { JsonValue, JsonObject } from "./common.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
 /**
  * Type alias for complex Zod schema type to improve readability
  * Used across providers and validation systems
  * Using ZodTypeAny to prevent infinite type recursion in zod-to-json-schema
  */
 export type ZodUnknownSchema = ZodTypeAny;
+/**
+ * Bridges Zod 4 schema types to the zod-to-json-schema library which still
+ * types against Zod 3 (`zod/v3`). Zod 4 schemas are structurally compatible
+ * at runtime but not assignable at the type level, so call sites must cast
+ * through `unknown` to this type at the third-party boundary.
+ */
+export type ZodToJsonSchemaInput = Parameters<typeof zodToJsonSchema>[0];
 /**
  * Union type for schema validation (Zod or AI SDK schema)
  * Commonly used in provider interfaces and validation functions

package/dist/types/typeAliases.js

@@ -2,6 +2,7 @@
  * Comprehensive Type Alias Library
  * Centralizes commonly used complex types to improve readability and maintainability
  */
+import { zodToJsonSchema } from "zod-to-json-schema";
 // ============================================================================
 // TYPE GUARDS AND UTILITIES
 // ============================================================================

package/dist/utils/async/retry.d.ts

@@ -3,41 +3,12 @@
  *
  * Provides retry logic with exponential backoff for resilient async operations.
  */
+import type { AsyncRetryOptions } from "../../types/index.js";
 /**
- * Configuration options for retry operations.
+ * Local alias: the canonical type was renamed to AsyncRetryOptions to avoid
+ * collision with other RetryOptions types in the codebase.
  */
-export type RetryOptions = {
-    /**
-     * Maximum number of retry attempts (not including the initial attempt).
-     * @default 3
-     */
-    maxRetries: number;
-    /**
-     * Initial delay between retries in milliseconds.
-     * @default 1000
-     */
-    baseDelayMs: number;
-    /**
-     * Maximum delay cap in milliseconds.
-     * @default 30000
-     */
-    maxDelayMs: number;
-    /**
-     * Multiplier for exponential backoff.
-     * @default 2
-     */
-    backoffMultiplier?: number;
-    /**
-     * Function to determine if a retry should be attempted.
-     * Return false to stop retrying immediately.
-     */
-    shouldRetry?: (error: Error, attempt: number) => boolean;
-    /**
-     * Callback invoked before each retry attempt.
-     * Useful for logging or metrics.
-     */
-    onRetry?: (error: Error, attempt: number, delayMs: number) => void;
-};
+export type RetryOptions = AsyncRetryOptions;
 /**
  * Default retry configuration.
  */

package/dist/utils/asyncMutex.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Promise-based async mutex for serializing concurrent async operations.
+ * No external dependencies — uses a simple FIFO queue of pending resolvers.
+ */
+export declare class AsyncMutex {
+    /** Default timeout for lock-held operations: 30 seconds */
+    private static readonly DEFAULT_TIMEOUT_MS;
+    private _locked;
+    private _queue;
+    isLocked(): boolean;
+    runExclusive<T>(fn: () => Promise<T>, timeoutMs?: number): Promise<T>;
+    private _acquire;
+    private _release;
+}

package/dist/utils/asyncMutex.js

@@ -0,0 +1,60 @@
+/**
+ * Promise-based async mutex for serializing concurrent async operations.
+ * No external dependencies — uses a simple FIFO queue of pending resolvers.
+ */
+export class AsyncMutex {
+    /** Default timeout for lock-held operations: 30 seconds */
+    static DEFAULT_TIMEOUT_MS = 30_000;
+    _locked = false;
+    _queue = [];
+    isLocked() {
+        return this._locked;
+    }
+    async runExclusive(fn, timeoutMs = AsyncMutex.DEFAULT_TIMEOUT_MS) {
+        await this._acquire();
+        let timer;
+        // Store fn()'s promise so we can ensure it settles before releasing the lock,
+        // even when the timeout fires first.
+        const fnPromise = fn();
+        try {
+            return await Promise.race([
+                fnPromise,
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(new Error(`AsyncMutex: lock-held operation timed out after ${timeoutMs}ms`)), timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            // Wait for fn() to settle before releasing the lock.
+            // If the timeout fired, fn() may still be running — we must not
+            // let another caller acquire the lock until fn() completes.
+            await fnPromise.catch((_settleErr) => {
+                // Intentionally swallowed — we only await settlement to keep
+                // the lock held until fn() finishes. The caller already received
+                // the timeout rejection from Promise.race above.
+            });
+            this._release();
+        }
+    }
+    _acquire() {
+        if (!this._locked) {
+            this._locked = true;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this._queue.push(resolve);
+        });
+    }
+    _release() {
+        const next = this._queue.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this._locked = false;
+        }
+    }
+}

package/dist/utils/errorHandling.d.ts

@@ -237,7 +237,8 @@ export declare class CircuitBreaker {
     private failures;
     private lastFailureTime;
     private state;
-    constructor(failureThreshold?: number, resetTimeoutMs?: number);
+    private name;
+    constructor(failureThreshold?: number, resetTimeoutMs?: number, name?: string);
     execute<T>(operation: () => Promise<T>): Promise<T>;
     private onSuccess;
     private onFailure;

package/dist/utils/errorHandling.js

@@ -4,6 +4,7 @@
  */
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { logger } from "./logger.js";
+import { CircuitBreakerOpenError } from "../types/circuitBreakerErrors.js";
 // Error codes for different scenarios
 export const ERROR_CODES = {
     // Tool errors
@@ -779,18 +780,25 @@ export class CircuitBreaker {
     failures = 0;
     lastFailureTime = 0;
     state = "closed";
-    constructor(failureThreshold = 5, resetTimeoutMs = 60000) {
+    name;
+    constructor(failureThreshold = 5, resetTimeoutMs = 60000, name = "tool-execution") {
         this.failureThreshold = failureThreshold;
         this.resetTimeoutMs = resetTimeoutMs;
+        this.name = name;
     }
     async execute(operation) {
         if (this.state === "open") {
-            if (Date.now() - this.lastFailureTime > this.resetTimeoutMs) {
-                this.state = "half-open";
-            }
-            else {
-                throw new Error("Circuit breaker is open - operation not executed");
+            const retryAfterMs = this.resetTimeoutMs - (Date.now() - this.lastFailureTime);
+            if (retryAfterMs > 0) {
+                throw new CircuitBreakerOpenError({
+                    breakerName: this.name,
+                    retryAfter: new Date(this.lastFailureTime + this.resetTimeoutMs),
+                    retryAfterMs,
+                    breakerState: "open",
+                    failureCount: this.failures,
+                });
             }
+            this.state = "half-open";
         }
         try {
             const result = await operation();

package/dist/utils/fileDetector.d.ts

@@ -11,7 +11,7 @@ import type { FileDetectorOptions, FileInput, FileProcessingResult } from "../ty
  * ```typescript
  * // Auto-detect and process any file
  * const result = await FileDetector.detectAndProcess("data.csv");
- * console.log(result.type); // 'csv'
+ * logger.info(result.type); // 'csv'
  * ```
  */
 export declare class FileDetector {
@@ -31,6 +31,18 @@ export declare class FileDetector {
      * @returns Processed file result with type and content
      */
     static detectAndProcess(input: FileInput, options?: FileDetectorOptions): Promise<FileProcessingResult>;
+    /**
+     * Set span attributes and log after file processing completes.
+     */
+    private static setFileResultSpanAttributes;
+    /**
+     * Derive a human-readable filename from FileInput for tracing.
+     */
+    private static deriveInputFilename;
+    /**
+     * Derive byte size from FileInput for tracing.
+     */
+    private static deriveInputSize;
     /**
      * Try fallback parsing for a specific file type
      * Used when file detection returns "unknown" but we want to try parsing anyway