@juspay/neurolink 9.81.3 → 9.83.0

package/dist/cli/commands/proxy.js

@@ -17,6 +17,7 @@ import ora from "ora";
 import { buildProxyHealthResponse, createProxyReadinessState, markProxyReady, waitForProxyReadiness, } from "../../lib/proxy/proxyHealth.js";
 import { logger } from "../../lib/utils/logger.js";
 import { formatUptime, isProcessRunning, StateFileManager, } from "../utils/serverUtils.js";
+import { configureProxyKeepAliveDispatcher } from "../../lib/proxy/proxyDispatcher.js";
 import { loadProxyEnvFile, resolveProxyEnvFile, } from "../../lib/proxy/proxyEnv.js";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
@@ -1285,6 +1286,10 @@ async function startProxyCommandHandler(argv) {
             await ensureProxyStartAllowed(spinner);
         }
         const loadedEnvFile = await loadProxyStartEnv(argv, spinner);
+        // Reuse upstream TCP connections (longer keep-alive + bounded pool) instead
+        // of opening a new flow per request — cuts outbound flow churn through host
+        // content-filters. Runs once, after env load so it can be tuned via env.
+        configureProxyKeepAliveDispatcher();
         const { neurolink, cleanupLogs } = await createProxyNeurolinkRuntime(devPaths?.logsDir);
         const { proxyConfig, strategy, modelRouter, passthrough, primaryAccountKey, } = await loadProxyStartConfiguration(argv, spinner);
         if (spinner) {

package/dist/cli/factories/commandFactory.d.ts

@@ -35,8 +35,9 @@ export declare class CLICommandFactory {
     private static validateAnthropicSubscriptionOptions;
     private static handleOutput;
     /**
-     * Helper method to handle TTS audio file output
+     * Helper method to handle TTS audio file output and playback
      * Saves audio to file when --tts-output flag is provided
+     * Plays audio when --tts-play flag is provided
      */
     private static handleTTSOutput;
     /**

package/dist/cli/factories/commandFactory.js

@@ -20,6 +20,7 @@ import { handleError } from "../errorHandler.js";
 import { LoopSession } from "../loop/session.js";
 import { initializeCliParser } from "../parser.js";
 import { formatFileSize, saveAudioToFile } from "../utils/audioFileUtils.js";
+import { playAudio } from "../utils/audioPlayer.js";
 import { resolveFilePaths } from "../utils/pathResolver.js";
 import { animatedWrite } from "../utils/typewriter.js";
 import { createStreamAbortHandler } from "../utils/abortHandler.js";
@@ -1040,13 +1041,15 @@ export class CLICommandFactory {
         }
     }
     /**
-     * Helper method to handle TTS audio file output
+     * Helper method to handle TTS audio file output and playback
      * Saves audio to file when --tts-output flag is provided
+     * Plays audio when --tts-play flag is provided
      */
     static async handleTTSOutput(result, options) {
-        // Check if --tts-output flag is provided
         const ttsOutputPath = options.ttsOutput;
-        if (!ttsOutputPath) {
+        const shouldPlay = options.ttsPlay;
+        // Nothing to do if neither save nor play is requested
+        if (!ttsOutputPath && !shouldPlay) {
             return;
         }
         // Extract audio from result with proper type checking
@@ -1061,20 +1064,36 @@ export class CLICommandFactory {
             }
             return;
         }
-        try {
-            // Save audio to file
-            const saveResult = await saveAudioToFile(audio, ttsOutputPath);
-            if (saveResult.success) {
-                if (!options.quiet) {
-                    logger.always(chalk.green(`🔊 Audio saved to: ${saveResult.path} (${formatFileSize(saveResult.size)})`));
+        // Save audio to file if --tts-output is provided
+        if (ttsOutputPath) {
+            try {
+                const saveResult = await saveAudioToFile(audio, ttsOutputPath);
+                if (saveResult.success) {
+                    if (!options.quiet) {
+                        logger.always(chalk.green(`🔊 Audio saved to: ${saveResult.path} (${formatFileSize(saveResult.size)})`));
+                    }
+                }
+                else {
+                    handleError(new Error(saveResult.error || "Failed to save audio file"), "TTS Output");
                 }
             }
-            else {
-                handleError(new Error(saveResult.error || "Failed to save audio file"), "TTS Output");
+            catch (error) {
+                handleError(error, "TTS Output");
             }
         }
-        catch (error) {
-            handleError(error, "TTS Output");
+        // Play audio if --tts-play is provided
+        if (shouldPlay) {
+            try {
+                if (!options.quiet) {
+                    logger.always(chalk.blue("Playing audio..."));
+                }
+                await playAudio(audio.buffer, audio.format);
+            }
+            catch (err) {
+                // Non-fatal: warn but don't crash
+                logger.always(chalk.yellow(`Audio playback failed: ${err.message}`));
+                logger.always(chalk.yellow("   Tip: Save the audio with --tts-output <file> and play manually."));
+            }
         }
     }
     /**
@@ -2898,15 +2917,16 @@ export class CLICommandFactory {
                 logger.always(`\nOutput saved to ${options.output}`);
             }
         }
-        // Handle TTS audio output if --tts-output is provided
+        // Handle TTS audio output/playback if --tts-output or --tts-play is provided
         // Note: For streaming, TTS audio is collected during the stream
         // and saved at the end if available
         const ttsOutputPath = options.ttsOutput;
-        if (ttsOutputPath) {
+        const shouldPlay = options.ttsPlay;
+        if (ttsOutputPath || shouldPlay) {
             // For now, streaming TTS output is not yet available
             // This will be enabled when the TTS streaming infrastructure is complete
             if (!options.quiet) {
-                logger.always(chalk.yellow("⚠️  TTS audio output for streaming is not yet available. Use 'generate' command for TTS output."));
+                logger.always(chalk.yellow("TTS audio for streaming is not yet available. Use 'generate' command for TTS output."));
             }
         }
         // Debug output for streaming

package/dist/cli/utils/audioPlayer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Audio playback utilities for CLI
+ *
+ * Provides functionality for playing TTS audio using platform-specific
+ * CLI tools with proper cleanup and error handling.
+ *
+ * @module cli/utils/audioPlayer
+ */
+import type { AudioFormat } from "../../lib/types/index.js";
+/**
+ * Get the file extension for an audio format
+ *
+ * @param format - Audio format
+ * @returns File extension string (e.g., "mp3", "wav")
+ */
+export declare function getAudioExtension(format: AudioFormat): string;
+/**
+ * Play audio from a buffer using platform-specific CLI tools
+ *
+ * Writes the buffer to a temporary file, plays it using the appropriate
+ * system audio player, and cleans up the temp file afterward.
+ *
+ * Supported platforms:
+ * - macOS: uses `afplay` (built-in, supports mp3/wav/aac/flac)
+ * - Linux: uses `paplay` for non-wav, `aplay` for wav
+ * - Windows: uses PowerShell SoundPlayer (wav) or WMPlayer.OCX (mp3)
+ *
+ * @param buffer - Audio data buffer
+ * @param format - Audio format (mp3, wav, ogg, opus)
+ * @throws Error if playback fails or platform is unsupported
+ *
+ * @example
+ * ```typescript
+ * await playAudio(audioBuffer, "mp3");
+ * ```
+ */
+export declare function playAudio(buffer: Buffer, format: AudioFormat): Promise<void>;

package/dist/cli/utils/audioPlayer.js

@@ -0,0 +1,138 @@
+/**
+ * Audio playback utilities for CLI
+ *
+ * Provides functionality for playing TTS audio using platform-specific
+ * CLI tools with proper cleanup and error handling.
+ *
+ * @module cli/utils/audioPlayer
+ */
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * Get the file extension for an audio format
+ *
+ * @param format - Audio format
+ * @returns File extension string (e.g., "mp3", "wav")
+ */
+export function getAudioExtension(format) {
+    switch (format) {
+        case "mp3":
+            return "mp3";
+        case "wav":
+            return "wav";
+        case "ogg":
+            return "ogg";
+        case "opus":
+            return "opus";
+        default:
+            return "mp3";
+    }
+}
+/**
+ * Get the platform-specific audio player command and arguments
+ *
+ * @param filePath - Path to the audio file
+ * @param format - Audio format
+ * @returns Object with command and args for execFile
+ */
+function getPlayerCommand(filePath, format) {
+    const platform = process.platform;
+    switch (platform) {
+        case "darwin":
+            return { command: "afplay", args: [filePath] };
+        case "linux":
+            if (format === "wav") {
+                return { command: "aplay", args: [filePath] };
+            }
+            return { command: "paplay", args: [filePath] };
+        case "win32":
+            if (format === "wav") {
+                return {
+                    command: "powershell",
+                    args: [
+                        "-NoProfile",
+                        "-Command",
+                        `(New-Object System.Media.SoundPlayer '${filePath}').PlaySync()`,
+                    ],
+                };
+            }
+            return {
+                command: "powershell",
+                args: [
+                    "-NoProfile",
+                    "-Command",
+                    `$player = New-Object -ComObject WMPlayer.OCX; $player.URL = '${filePath}'; $player.controls.play(); Start-Sleep -Seconds 1; while ($player.playState -eq 3) { Start-Sleep -Milliseconds 100 }; $player.close()`,
+                ],
+            };
+        default:
+            throw new Error(`Unsupported platform: ${platform}. Audio playback is supported on macOS, Linux, and Windows.`);
+    }
+}
+/**
+ * Play audio from a buffer using platform-specific CLI tools
+ *
+ * Writes the buffer to a temporary file, plays it using the appropriate
+ * system audio player, and cleans up the temp file afterward.
+ *
+ * Supported platforms:
+ * - macOS: uses `afplay` (built-in, supports mp3/wav/aac/flac)
+ * - Linux: uses `paplay` for non-wav, `aplay` for wav
+ * - Windows: uses PowerShell SoundPlayer (wav) or WMPlayer.OCX (mp3)
+ *
+ * @param buffer - Audio data buffer
+ * @param format - Audio format (mp3, wav, ogg, opus)
+ * @throws Error if playback fails or platform is unsupported
+ *
+ * @example
+ * ```typescript
+ * await playAudio(audioBuffer, "mp3");
+ * ```
+ */
+export async function playAudio(buffer, format) {
+    const ext = getAudioExtension(format);
+    const tempFile = path.join(os.tmpdir(), `nl-tts-${Date.now()}.${ext}`);
+    try {
+        // Write audio buffer to temp file
+        await fs.promises.writeFile(tempFile, buffer);
+        const { command, args } = getPlayerCommand(tempFile, format);
+        try {
+            await execFileAsync(command, args);
+        }
+        catch (execError) {
+            const err = execError;
+            // Handle binary not found
+            if (err.code === "ENOENT") {
+                if (process.platform === "linux" && command === "paplay") {
+                    // Fallback to aplay on Linux
+                    try {
+                        await execFileAsync("aplay", [tempFile]);
+                        return;
+                    }
+                    catch (fallbackError) {
+                        const fbErr = fallbackError;
+                        if (fbErr.code === "ENOENT") {
+                            throw new Error("Neither paplay nor aplay found. Install PulseAudio (paplay) or ALSA (aplay) for audio playback.", { cause: fallbackError });
+                        }
+                        throw fallbackError;
+                    }
+                }
+                throw new Error(`Audio player '${command}' not found. Ensure it is installed and available in PATH.`, { cause: execError });
+            }
+            throw execError;
+        }
+    }
+    finally {
+        // Always clean up temp file
+        try {
+            await fs.promises.unlink(tempFile);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+}
+//# sourceMappingURL=audioPlayer.js.map

package/dist/core/modules/GenerationHandler.js

@@ -26,6 +26,7 @@ import { coerceJsonToSchema } from "../../utils/json/coerce.js";
 import { NoObjectGeneratedError } from "../../utils/generationErrors.js";
 import { Output, stepCountIs } from "../../utils/tool.js";
 import { generateText } from "../../utils/generation.js";
+import { extractSystemMessages } from "../../utils/systemMessages.js";
 const genTracer = tracers.generation;
 /**
  * Safely preview-serialize a value for debug logging.
@@ -105,9 +106,14 @@ export class GenerationHandler {
             }
         }
         const prepareStep = options.prepareStep;
+        // Hoist system-role messages into generateText's top-level `system` option
+        // rather than passing them inside `messages` (deprecated by the AI SDK,
+        // rejected in v7). See extractSystemMessages for the rationale. (#1024)
+        const { system, messages: nonSystemMessages } = extractSystemMessages(messages);
         return await generateText({
             model,
-            messages,
+            ...(system && { system }),
+            messages: nonSystemMessages,
             ...(shouldUseTools &&
                 Object.keys(toolsWithCache).length > 0 && { tools: toolsWithCache }),
             stopWhen: stepCountIs(options.maxSteps ?? DEFAULT_MAX_STEPS),

package/dist/index.d.ts

@@ -35,7 +35,12 @@ import { AIProviderFactory } from "./core/factory.js";
 export { AIProviderFactory };
 export { NeuroLinkConfigManager as ConfigManager } from "./config/configManager.js";
 export { BaseFactory, BaseRegistry, NeuroLinkFeatureError, createErrorFactory, withRetry, TypedEventEmitter, } from "./core/infrastructure/index.js";
-export { NeuroLinkClient, createClient, NeuroLinkApiError, NeuroLinkLanguageModel, NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/index.js";
+export { NeuroLinkClient, createClient, NeuroLinkApiError, } from "./client/httpClient.js";
+export { NeuroLinkLanguageModel, NeuroLinkProvider as NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, } from "./client/aiSdkAdapter.js";
+export { createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, } from "./client/interceptors.js";
+export { SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, } from "./client/streamingClient.js";
+export { OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthenticationError as OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, } from "./client/auth.js";
+export { ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/errors.js";
 export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./constants/enums.js";
 export { dynamicModelProvider } from "./core/dynamicModels.js";
 export { validateTool } from "./sdk/toolRegistration.js";

package/dist/index.js

@@ -41,20 +41,28 @@ export { BaseFactory, BaseRegistry, NeuroLinkFeatureError, createErrorFactory, w
 // ============================================================================
 // CLIENT SDK EXPORTS - Type-safe API access for browser and Node.js
 // Note: React hooks are NOT re-exported here. Import from '@juspay/neurolink/client'.
+// These re-exports intentionally bypass ./client/index.js: that barrel statically
+// re-exports ./reactHooks.js, so routing through it makes the ROOT import require
+// `react` (an optional peer dep) and crash react-less installs at import time.
 // ============================================================================
 export { 
 // HTTP Client
-NeuroLinkClient, createClient, NeuroLinkApiError, 
+NeuroLinkClient, createClient, NeuroLinkApiError, } from "./client/httpClient.js";
+export { 
 // AI SDK Adapter
-NeuroLinkLanguageModel, NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, 
+NeuroLinkLanguageModel, NeuroLinkProvider as NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, } from "./client/aiSdkAdapter.js";
+export { 
 // Interceptors
-createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, 
+createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, } from "./client/interceptors.js";
+export { 
 // Streaming Client
-SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, 
+SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, } from "./client/streamingClient.js";
+export { 
 // Authentication
-OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, 
+OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthenticationError as OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, } from "./client/auth.js";
+export { 
 // Errors
-ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/index.js";
+ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/errors.js";
 export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./constants/enums.js";
 // Dynamic Models exports
 export { dynamicModelProvider } from "./core/dynamicModels.js";

package/dist/lib/core/modules/GenerationHandler.js

@@ -26,6 +26,7 @@ import { coerceJsonToSchema } from "../../utils/json/coerce.js";
 import { NoObjectGeneratedError } from "../../utils/generationErrors.js";
 import { Output, stepCountIs } from "../../utils/tool.js";
 import { generateText } from "../../utils/generation.js";
+import { extractSystemMessages } from "../../utils/systemMessages.js";
 const genTracer = tracers.generation;
 /**
  * Safely preview-serialize a value for debug logging.
@@ -105,9 +106,14 @@ export class GenerationHandler {
             }
         }
         const prepareStep = options.prepareStep;
+        // Hoist system-role messages into generateText's top-level `system` option
+        // rather than passing them inside `messages` (deprecated by the AI SDK,
+        // rejected in v7). See extractSystemMessages for the rationale. (#1024)
+        const { system, messages: nonSystemMessages } = extractSystemMessages(messages);
         return await generateText({
             model,
-            messages,
+            ...(system && { system }),
+            messages: nonSystemMessages,
             ...(shouldUseTools &&
                 Object.keys(toolsWithCache).length > 0 && { tools: toolsWithCache }),
             stopWhen: stepCountIs(options.maxSteps ?? DEFAULT_MAX_STEPS),

package/dist/lib/index.d.ts

@@ -35,7 +35,12 @@ import { AIProviderFactory } from "./core/factory.js";
 export { AIProviderFactory };
 export { NeuroLinkConfigManager as ConfigManager } from "./config/configManager.js";
 export { BaseFactory, BaseRegistry, NeuroLinkFeatureError, createErrorFactory, withRetry, TypedEventEmitter, } from "./core/infrastructure/index.js";
-export { NeuroLinkClient, createClient, NeuroLinkApiError, NeuroLinkLanguageModel, NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/index.js";
+export { NeuroLinkClient, createClient, NeuroLinkApiError, } from "./client/httpClient.js";
+export { NeuroLinkLanguageModel, NeuroLinkProvider as NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, } from "./client/aiSdkAdapter.js";
+export { createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, } from "./client/interceptors.js";
+export { SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, } from "./client/streamingClient.js";
+export { OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthenticationError as OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, } from "./client/auth.js";
+export { ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/errors.js";
 export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./constants/enums.js";
 export { dynamicModelProvider } from "./core/dynamicModels.js";
 export { validateTool } from "./sdk/toolRegistration.js";

package/dist/lib/index.js

@@ -41,20 +41,28 @@ export { BaseFactory, BaseRegistry, NeuroLinkFeatureError, createErrorFactory, w
 // ============================================================================
 // CLIENT SDK EXPORTS - Type-safe API access for browser and Node.js
 // Note: React hooks are NOT re-exported here. Import from '@juspay/neurolink/client'.
+// These re-exports intentionally bypass ./client/index.js: that barrel statically
+// re-exports ./reactHooks.js, so routing through it makes the ROOT import require
+// `react` (an optional peer dep) and crash react-less installs at import time.
 // ============================================================================
 export { 
 // HTTP Client
-NeuroLinkClient, createClient, NeuroLinkApiError, 
+NeuroLinkClient, createClient, NeuroLinkApiError, } from "./client/httpClient.js";
+export { 
 // AI SDK Adapter
-NeuroLinkLanguageModel, NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, 
+NeuroLinkLanguageModel, NeuroLinkProvider as NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, } from "./client/aiSdkAdapter.js";
+export { 
 // Interceptors
-createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, 
+createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, } from "./client/interceptors.js";
+export { 
 // Streaming Client
-SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, 
+SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, } from "./client/streamingClient.js";
+export { 
 // Authentication
-OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, 
+OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthenticationError as OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, } from "./client/auth.js";
+export { 
 // Errors
-ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/index.js";
+ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/errors.js";
 export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./constants/enums.js";
 // Dynamic Models exports
 export { dynamicModelProvider } from "./core/dynamicModels.js";

package/dist/lib/providers/googleAiStudio.js

@@ -584,6 +584,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     let lastStepText = "";
                     let totalInputTokens = 0;
                     let totalOutputTokens = 0;
+                    let totalCacheReadTokens = 0;
                     let step = 0;
                     let completedWithFinalAnswer = false;
                     const failedTools = new Map();
@@ -614,6 +615,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                                 const chunkResult = await collectStreamChunksIncremental(rawStream, channel);
                                 totalInputTokens += chunkResult.inputTokens;
                                 totalOutputTokens += chunkResult.outputTokens;
+                                totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                                 const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                                 // If no function calls, this was the final step — channel
                                 // already received all text parts incrementally.
@@ -698,13 +700,23 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         span.setAttribute(ATTR.GEN_AI_INPUT_TOKENS, totalInputTokens);
                         span.setAttribute(ATTR.GEN_AI_OUTPUT_TOKENS, totalOutputTokens);
                         span.setAttribute(ATTR.GEN_AI_FINISH_REASON, hitStepLimitWithoutFinalAnswer ? "max_steps" : "stop");
+                        // Gemini promptTokenCount is OVERLAPPING: it already includes
+                        // cachedContentTokenCount. Subtract once here so calculateCost
+                        // bills the cached portion at the cheaper cacheRead rate without
+                        // double-counting. Total billable tokens are conserved.
+                        const adjustedInputTokens = Math.max(0, totalInputTokens - totalCacheReadTokens);
                         analyticsResolve({
                             provider: this.providerName,
                             model: modelName,
                             tokenUsage: {
-                                input: totalInputTokens,
+                                input: adjustedInputTokens,
                                 output: totalOutputTokens,
-                                total: totalInputTokens + totalOutputTokens,
+                                total: adjustedInputTokens +
+                                    totalCacheReadTokens +
+                                    totalOutputTokens,
+                                ...(totalCacheReadTokens > 0
+                                    ? { cacheReadTokens: totalCacheReadTokens }
+                                    : {}),
                             },
                             requestDuration: responseTime,
                             timestamp: new Date().toISOString(),
@@ -831,6 +843,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 let lastStepText = "";
                 let totalInputTokens = 0;
                 let totalOutputTokens = 0;
+                let totalCacheReadTokens = 0;
                 const allToolCalls = [];
                 const toolExecutions = [];
                 let step = 0;
@@ -856,6 +869,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         const chunkResult = await collectStreamChunks(stream);
                         totalInputTokens += chunkResult.inputTokens;
                         totalOutputTokens += chunkResult.outputTokens;
+                        totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                         const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                         // If no function calls, we're done
                         if (chunkResult.stepFunctionCalls.length === 0) {
@@ -927,14 +941,21 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 // analytics / evaluation / tracing stay attached. The native AI
                 // Studio generate path bypasses BaseProvider.generate(), so
                 // skipping enhanceResult would silently drop those features.
+                // Gemini promptTokenCount is OVERLAPPING (already includes
+                // cachedContentTokenCount). Subtract once so the cached portion is
+                // billed at the cheaper cacheRead rate without double-counting.
+                const adjustedInputTokens = Math.max(0, totalInputTokens - totalCacheReadTokens);
                 const baseResult = {
                     content: finalText,
                     provider: this.providerName,
                     model: modelName,
                     usage: {
-                        input: totalInputTokens,
+                        input: adjustedInputTokens,
                         output: totalOutputTokens,
-                        total: totalInputTokens + totalOutputTokens,
+                        total: adjustedInputTokens + totalCacheReadTokens + totalOutputTokens,
+                        ...(totalCacheReadTokens > 0
+                            ? { cacheReadTokens: totalCacheReadTokens }
+                            : {}),
                     },
                     responseTime,
                     toolsUsed: allToolCalls.map((tc) => tc.toolName),

package/dist/lib/providers/googleNativeGemini3.js

@@ -514,6 +514,7 @@ export async function collectStreamChunks(stream) {
     const stepFunctionCalls = [];
     let inputTokens = 0;
     let outputTokens = 0;
+    let cacheReadTokens = 0;
     for await (const chunk of stream) {
         // Extract raw parts from candidates FIRST
         // This avoids using chunk.text which triggers SDK warning when
@@ -533,9 +534,18 @@ export async function collectStreamChunks(stream) {
         if (usage) {
             inputTokens = Math.max(inputTokens, usage.promptTokenCount || 0);
             outputTokens = Math.max(outputTokens, usage.candidatesTokenCount || 0);
+            // cachedContentTokenCount is OVERLAPPING (a subset already inside
+            // promptTokenCount). Surface it so the call site subtracts once.
+            cacheReadTokens = Math.max(cacheReadTokens, usage.cachedContentTokenCount || 0);
         }
     }
-    return { rawResponseParts, stepFunctionCalls, inputTokens, outputTokens };
+    return {
+        rawResponseParts,
+        stepFunctionCalls,
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+    };
 }
 /**
  * Create a push-based text channel that bridges a background producer
@@ -627,6 +637,7 @@ export async function collectStreamChunksIncremental(stream, channel) {
     const stepFunctionCalls = [];
     let inputTokens = 0;
     let outputTokens = 0;
+    let cacheReadTokens = 0;
     for await (const chunk of stream) {
         const chunkRecord = chunk;
         const candidates = chunkRecord.candidates;
@@ -648,9 +659,18 @@ export async function collectStreamChunksIncremental(stream, channel) {
         if (usage) {
             inputTokens = Math.max(inputTokens, usage.promptTokenCount || 0);
             outputTokens = Math.max(outputTokens, usage.candidatesTokenCount || 0);
+            // cachedContentTokenCount is OVERLAPPING (a subset already inside
+            // promptTokenCount). Surface it so the call site subtracts once.
+            cacheReadTokens = Math.max(cacheReadTokens, usage.cachedContentTokenCount || 0);
         }
     }
-    return { rawResponseParts, stepFunctionCalls, inputTokens, outputTokens };
+    return {
+        rawResponseParts,
+        stepFunctionCalls,
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+    };
 }
 /**
  * Extract the thoughtSignature token from raw response parts.