@juspay/neurolink 7.24.0 → 7.25.0

package/dist/lib/middleware/registry.js

@@ -0,0 +1,283 @@
+import { logger } from "../utils/logger.js";
+/**
+ * Global middleware registry for NeuroLink
+ * Manages registration, configuration, and execution of middleware
+ */
+export class MiddlewareRegistry {
+    middleware = new Map();
+    globalConfigs = new Map();
+    executionStats = new Map();
+    /**
+     * Register a middleware
+     */
+    register(middleware, options = {}) {
+        const { replace = false, defaultEnabled = false, globalConfig } = options;
+        // Check if middleware already exists
+        if (this.middleware.has(middleware.metadata.id) && !replace) {
+            throw new Error(`Middleware with ID '${middleware.metadata.id}' already exists. Use replace: true to override.`);
+        }
+        // Set default enabled state
+        if (middleware.metadata.defaultEnabled === undefined) {
+            middleware.metadata.defaultEnabled = defaultEnabled;
+        }
+        // Store middleware
+        this.middleware.set(middleware.metadata.id, middleware);
+        // Store global configuration if provided
+        if (globalConfig) {
+            this.globalConfigs.set(middleware.metadata.id, globalConfig);
+        }
+        logger.debug(`Middleware registered: ${middleware.metadata.id}`, {
+            name: middleware.metadata.name,
+            priority: middleware.metadata.priority || 0,
+            defaultEnabled: middleware.metadata.defaultEnabled,
+        });
+    }
+    /**
+     * Unregister a middleware
+     */
+    unregister(middlewareId) {
+        const removed = this.middleware.delete(middlewareId);
+        this.globalConfigs.delete(middlewareId);
+        this.executionStats.delete(middlewareId);
+        if (removed) {
+            logger.debug(`Middleware unregistered: ${middlewareId}`);
+        }
+        return removed;
+    }
+    /**
+     * Get a registered middleware
+     */
+    get(middlewareId) {
+        return this.middleware.get(middlewareId);
+    }
+    /**
+     * List all registered middleware
+     */
+    list() {
+        return Array.from(this.middleware.values());
+    }
+    /**
+     * Get middleware IDs sorted by priority
+     */
+    getSortedIds() {
+        return Array.from(this.middleware.values())
+            .sort((a, b) => (b.metadata.priority || 0) - (a.metadata.priority || 0))
+            .map((m) => m.metadata.id);
+    }
+    /**
+     * Build middleware chain based on configuration
+     */
+    buildChain(context, config = {}) {
+        const chain = [];
+        const sortedIds = this.getSortedIds();
+        for (const middlewareId of sortedIds) {
+            const middleware = this.middleware.get(middlewareId);
+            if (!middleware) {
+                continue;
+            }
+            const middlewareConfig = config[middlewareId];
+            const globalConfig = this.globalConfigs.get(middlewareId);
+            // Determine if middleware should be applied
+            const shouldApply = this.shouldApplyMiddleware(middleware, middlewareConfig, context);
+            if (shouldApply) {
+                // Create configured middleware instance
+                const configuredMiddleware = this.configureMiddleware(middleware, middlewareConfig, globalConfig, context);
+                chain.push(configuredMiddleware);
+                logger.debug(`Added middleware to chain: ${middlewareId}`, {
+                    priority: middleware.metadata.priority || 0,
+                    chainLength: chain.length,
+                });
+            }
+        }
+        return chain;
+    }
+    /**
+     * Determine if middleware should be applied based on conditions
+     */
+    shouldApplyMiddleware(middleware, config, context) {
+        // Check if explicitly disabled
+        if (config?.enabled === false) {
+            return false;
+        }
+        // Check if explicitly enabled or default enabled
+        const isEnabled = config?.enabled === true ||
+            (config?.enabled === undefined && middleware.metadata.defaultEnabled);
+        if (!isEnabled) {
+            return false;
+        }
+        // Check conditions
+        const conditions = config?.conditions;
+        if (!conditions) {
+            return true;
+        }
+        // Check provider conditions
+        if (conditions.providers &&
+            !conditions.providers.includes(context.provider)) {
+            return false;
+        }
+        // Check model conditions
+        if (conditions.models && !conditions.models.includes(context.model)) {
+            return false;
+        }
+        // Check option conditions
+        if (conditions.options) {
+            for (const [key, value] of Object.entries(conditions.options)) {
+                if (context.options[key] !== value) {
+                    return false;
+                }
+            }
+        }
+        // Check custom condition
+        if (conditions.custom && !conditions.custom(context)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Configure middleware with runtime configuration
+     */
+    configureMiddleware(middleware, config, globalConfig, context) {
+        // Merge configurations: global < middleware config < runtime config
+        const mergedConfig = {
+            ...globalConfig,
+            ...config?.config,
+        };
+        // Create wrapper that tracks execution
+        const wrappedMiddleware = {};
+        if (middleware.transformParams) {
+            wrappedMiddleware.transformParams = async (args) => {
+                const startTime = Date.now();
+                try {
+                    const result = await middleware.transformParams(args);
+                    this.recordExecution(middleware.metadata.id, startTime, true);
+                    return result;
+                }
+                catch (error) {
+                    this.recordExecution(middleware.metadata.id, startTime, false, error);
+                    throw error;
+                }
+            };
+        }
+        if (middleware.wrapGenerate) {
+            wrappedMiddleware.wrapGenerate = async (args) => {
+                const startTime = Date.now();
+                try {
+                    const result = await middleware.wrapGenerate(args);
+                    this.recordExecution(middleware.metadata.id, startTime, true);
+                    return result;
+                }
+                catch (error) {
+                    this.recordExecution(middleware.metadata.id, startTime, false, error);
+                    throw error;
+                }
+            };
+        }
+        if (middleware.wrapStream) {
+            wrappedMiddleware.wrapStream = async (args) => {
+                const startTime = Date.now();
+                try {
+                    const result = await middleware.wrapStream(args);
+                    this.recordExecution(middleware.metadata.id, startTime, true);
+                    return result;
+                }
+                catch (error) {
+                    this.recordExecution(middleware.metadata.id, startTime, false, error);
+                    throw error;
+                }
+            };
+        }
+        return wrappedMiddleware;
+    }
+    /**
+     * Record middleware execution statistics
+     */
+    recordExecution(middlewareId, startTime, success, error) {
+        const executionTime = Date.now() - startTime;
+        const result = {
+            applied: true,
+            executionTime,
+            error,
+        };
+        if (!this.executionStats.has(middlewareId)) {
+            this.executionStats.set(middlewareId, []);
+        }
+        const stats = this.executionStats.get(middlewareId) || [];
+        stats.push(result);
+        // Keep only last 100 executions per middleware
+        if (stats.length > 100) {
+            stats.shift();
+        }
+        if (error) {
+            logger.warn(`Middleware execution failed: ${middlewareId}`, {
+                executionTime,
+                error: error.message,
+            });
+        }
+        else {
+            logger.debug(`Middleware executed: ${middlewareId}`, {
+                executionTime,
+                success,
+            });
+        }
+    }
+    /**
+     * Get execution statistics for a middleware
+     */
+    getExecutionStats(middlewareId) {
+        return this.executionStats.get(middlewareId) || [];
+    }
+    /**
+     * Get aggregated statistics for all middleware
+     */
+    getAggregatedStats() {
+        const stats = {};
+        for (const [middlewareId, executions] of this.executionStats.entries()) {
+            const successful = executions.filter((e) => !e.error).length;
+            const failed = executions.filter((e) => e.error).length;
+            const totalTime = executions.reduce((sum, e) => sum + e.executionTime, 0);
+            const lastExecution = executions[executions.length - 1];
+            stats[middlewareId] = {
+                totalExecutions: executions.length,
+                successfulExecutions: successful,
+                failedExecutions: failed,
+                averageExecutionTime: executions.length > 0 ? totalTime / executions.length : 0,
+                lastExecutionTime: lastExecution?.executionTime || 0,
+            };
+        }
+        return stats;
+    }
+    /**
+     * Clear execution statistics
+     */
+    clearStats(middlewareId) {
+        if (middlewareId) {
+            this.executionStats.delete(middlewareId);
+        }
+        else {
+            this.executionStats.clear();
+        }
+    }
+    /**
+     * Check if a middleware is registered
+     */
+    has(middlewareId) {
+        return this.middleware.has(middlewareId);
+    }
+    /**
+     * Get the number of registered middleware
+     */
+    size() {
+        return this.middleware.size;
+    }
+    /**
+     * Clear all registered middleware
+     */
+    clear() {
+        this.middleware.clear();
+        this.globalConfigs.clear();
+        this.executionStats.clear();
+        logger.debug("All middleware cleared from registry");
+    }
+}
+// Global middleware registry instance
+export const middlewareRegistry = new MiddlewareRegistry();

package/dist/lib/middleware/types.d.ts

@@ -0,0 +1,144 @@
+import type { LanguageModelV1Middleware } from "ai";
+import type { JsonValue } from "../types/common.js";
+/**
+ * Metadata interface for NeuroLink middleware
+ * Provides additional information about middleware without affecting execution
+ */
+export interface NeuroLinkMiddlewareMetadata {
+    /** Unique identifier for the middleware */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what the middleware does */
+    description?: string;
+    /** Priority for ordering (higher = earlier in chain) */
+    priority?: number;
+    /** Whether this middleware is enabled by default */
+    defaultEnabled?: boolean;
+    /** Configuration schema for the middleware */
+    configSchema?: Record<string, unknown>;
+}
+/**
+ * NeuroLink middleware with metadata
+ * Combines standard AI SDK middleware with NeuroLink-specific metadata
+ */
+export interface NeuroLinkMiddleware extends LanguageModelV1Middleware {
+    /** Middleware metadata */
+    readonly metadata: NeuroLinkMiddlewareMetadata;
+}
+/**
+ * Middleware configuration options
+ */
+export interface MiddlewareConfig {
+    /** Whether the middleware is enabled */
+    enabled?: boolean;
+    /** Middleware-specific configuration */
+    config?: Record<string, JsonValue>;
+    /** Conditions under which to apply this middleware */
+    conditions?: MiddlewareConditions;
+}
+/**
+ * Conditions for applying middleware
+ */
+export interface MiddlewareConditions {
+    /** Apply only to specific providers */
+    providers?: string[];
+    /** Apply only to specific models */
+    models?: string[];
+    /** Apply only when certain options are present */
+    options?: Record<string, unknown>;
+    /** Custom condition function */
+    custom?: (context: MiddlewareContext) => boolean;
+}
+/**
+ * Context passed to middleware for decision making
+ */
+export interface MiddlewareContext {
+    /** Provider name */
+    provider: string;
+    /** Model name */
+    model: string;
+    /** Request options */
+    options: Record<string, unknown>;
+    /** Session information */
+    session?: {
+        sessionId?: string;
+        userId?: string;
+    };
+    /** Additional metadata */
+    metadata?: Record<string, JsonValue>;
+}
+/**
+ * Middleware registration options
+ */
+export interface MiddlewareRegistrationOptions {
+    /** Whether to replace existing middleware with same ID */
+    replace?: boolean;
+    /** Whether to enable the middleware by default */
+    defaultEnabled?: boolean;
+    /** Global configuration for the middleware */
+    globalConfig?: Record<string, JsonValue>;
+}
+/**
+ * Middleware execution result
+ */
+export interface MiddlewareExecutionResult {
+    /** Whether the middleware was applied */
+    applied: boolean;
+    /** Execution time in milliseconds */
+    executionTime: number;
+    /** Any errors that occurred */
+    error?: Error;
+    /** Additional metadata from the middleware */
+    metadata?: Record<string, JsonValue>;
+}
+/**
+ * Middleware chain execution statistics
+ */
+export interface MiddlewareChainStats {
+    /** Total number of middleware in the chain */
+    totalMiddleware: number;
+    /** Number of middleware that were applied */
+    appliedMiddleware: number;
+    /** Total execution time for the chain */
+    totalExecutionTime: number;
+    /** Individual middleware execution results */
+    results: Record<string, MiddlewareExecutionResult>;
+}
+/**
+ * Built-in middleware types
+ */
+export type BuiltInMiddlewareType = "analytics" | "guardrails" | "logging" | "caching" | "rateLimit" | "retry" | "timeout";
+/**
+ * Middleware preset configurations
+ */
+export interface MiddlewarePreset {
+    /** Preset name */
+    name: string;
+    /** Description of the preset */
+    description: string;
+    /** Middleware configurations in the preset */
+    middleware: Record<string, MiddlewareConfig>;
+}
+/**
+ * Factory options for middleware
+ */
+export interface MiddlewareFactoryOptions {
+    /** Enable specific middleware */
+    enabledMiddleware?: string[];
+    /** Disable specific middleware */
+    disabledMiddleware?: string[];
+    /** Middleware configurations */
+    middlewareConfig?: Record<string, MiddlewareConfig>;
+    /** Use a preset configuration */
+    preset?: string;
+    /** Global middleware settings */
+    global?: {
+        /** Maximum execution time for middleware chain */
+        maxExecutionTime?: number;
+        /** Whether to continue on middleware errors */
+        continueOnError?: boolean;
+        /** Whether to collect execution statistics */
+        collectStats?: boolean;
+    };
+}

package/dist/lib/middleware/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/providers/anthropic.js

@@ -3,6 +3,7 @@ import { streamText } from "ai";
 import { BaseProvider } from "../core/baseProvider.js";
 import { logger } from "../utils/logger.js";
 import { createTimeoutController, TimeoutError, } from "../utils/timeout.js";
+import { AuthenticationError, NetworkError, ProviderError, RateLimitError, } from "../types/errors.js";
 import { DEFAULT_MAX_TOKENS, DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { validateApiKey, createAnthropicConfig, getProviderModel, } from "../utils/providerConfig.js";
 import { buildMessagesArray } from "../utils/messageBuilder.js";
@@ -50,45 +51,36 @@ export class AnthropicProvider extends BaseProvider {
     }
     handleProviderError(error) {
         if (error instanceof TimeoutError) {
-            return new Error(`Anthropic request timed out after ${error.timeout}ms: ${error.message}`);
+            throw new NetworkError(`Request timed out after ${error.timeout}ms`, this.providerName);
         }
         const errorRecord = error;
-        // Handle API key errors
-        if ((typeof errorRecord?.message === "string" &&
-            errorRecord.message.includes("API_KEY_INVALID")) ||
-            (typeof errorRecord?.message === "string" &&
-                errorRecord.message.includes("Invalid API key"))) {
-            return new Error("Invalid Anthropic API key. Please check your ANTHROPIC_API_KEY environment variable.");
+        const message = typeof errorRecord?.message === "string"
+            ? errorRecord.message
+            : "Unknown error";
+        if (message.includes("API_KEY_INVALID") ||
+            message.includes("Invalid API key")) {
+            throw new AuthenticationError("Invalid Anthropic API key. Please check your ANTHROPIC_API_KEY environment variable.", this.providerName);
         }
-        // Handle rate limiting errors
-        if (typeof errorRecord?.message === "string" &&
-            (errorRecord.message.includes("rate limit") ||
-                errorRecord.message.includes("too_many_requests") ||
-                errorRecord.message.includes("429"))) {
-            return new Error("Anthropic rate limit exceeded. Please try again later.");
+        if (message.includes("rate limit") ||
+            message.includes("too_many_requests") ||
+            message.includes("429")) {
+            throw new RateLimitError("Anthropic rate limit exceeded. Please try again later.", this.providerName);
         }
-        // Handle connection errors
-        if (typeof errorRecord?.message === "string" &&
-            (errorRecord.message.includes("ECONNRESET") ||
-                errorRecord.message.includes("ENOTFOUND") ||
-                errorRecord.message.includes("ECONNREFUSED") ||
-                errorRecord.message.includes("network") ||
-                errorRecord.message.includes("connection"))) {
-            return new Error("Anthropic API connection error. Please check your internet connection and try again.");
+        if (message.includes("ECONNRESET") ||
+            message.includes("ENOTFOUND") ||
+            message.includes("ECONNREFUSED") ||
+            message.includes("network") ||
+            message.includes("connection")) {
+            throw new NetworkError(`Connection error: ${message}`, this.providerName);
         }
-        // Handle server errors
-        if (typeof errorRecord?.message === "string" &&
-            (errorRecord.message.includes("500") ||
-                errorRecord.message.includes("502") ||
-                errorRecord.message.includes("503") ||
-                errorRecord.message.includes("504") ||
-                errorRecord.message.includes("server error"))) {
-            return new Error("Anthropic API server error. Please try again in a few moments.");
+        if (message.includes("500") ||
+            message.includes("502") ||
+            message.includes("503") ||
+            message.includes("504") ||
+            message.includes("server error")) {
+            throw new ProviderError(`Server error: ${message}`, this.providerName);
         }
-        const message = typeof errorRecord?.message === "string"
-            ? errorRecord.message
-            : "Unknown error";
-        return new Error(`Anthropic error: ${message}`);
+        throw new ProviderError(`Anthropic error: ${message}`, this.providerName);
     }
     // executeGenerate removed - BaseProvider handles all generation with tools
     async executeStream(options, analysisSchema) {

package/dist/lib/providers/googleAiStudio.js

@@ -4,6 +4,7 @@ import { GoogleAIModels } from "../core/types.js";
 import { BaseProvider } from "../core/baseProvider.js";
 import { logger } from "../utils/logger.js";
 import { createTimeoutController, TimeoutError, } from "../utils/timeout.js";
+import { AuthenticationError, NetworkError, ProviderError, RateLimitError, } from "../types/errors.js";
 import { DEFAULT_MAX_TOKENS, DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
 import { buildMessagesArray } from "../utils/messageBuilder.js";
@@ -44,21 +45,19 @@ export class GoogleAIStudioProvider extends BaseProvider {
     }
     handleProviderError(error) {
         if (error instanceof TimeoutError) {
-            return new Error(`Google AI request timed out: ${error.message}`);
+            throw new NetworkError(error.message, this.providerName);
         }
         const errorRecord = error;
-        if (typeof errorRecord?.message === "string" &&
-            errorRecord.message.includes("API_KEY_INVALID")) {
-            return new Error("Invalid Google AI API key. Please check your GOOGLE_AI_API_KEY environment variable.");
-        }
-        if (typeof errorRecord?.message === "string" &&
-            errorRecord.message.includes("RATE_LIMIT_EXCEEDED")) {
-            return new Error("Google AI rate limit exceeded. Please try again later.");
-        }
         const message = typeof errorRecord?.message === "string"
             ? errorRecord.message
             : "Unknown error";
-        return new Error(`Google AI error: ${message}`);
+        if (message.includes("API_KEY_INVALID")) {
+            throw new AuthenticationError("Invalid Google AI API key. Please check your GOOGLE_AI_API_KEY environment variable.", this.providerName);
+        }
+        if (message.includes("RATE_LIMIT_EXCEEDED")) {
+            throw new RateLimitError("Google AI rate limit exceeded. Please try again later.", this.providerName);
+        }
+        throw new ProviderError(`Google AI error: ${message}`, this.providerName);
     }
     // executeGenerate removed - BaseProvider handles all generation with tools
     async executeStream(options, analysisSchema) {
@@ -119,7 +118,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
     getApiKey() {
         const apiKey = process.env.GOOGLE_AI_API_KEY || process.env.GOOGLE_GENERATIVE_AI_API_KEY;
         if (!apiKey) {
-            throw new Error("GOOGLE_AI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY environment variable is not set");
+            throw new AuthenticationError("GOOGLE_AI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY environment variable is not set", this.providerName);
         }
         return apiKey;
     }

package/dist/lib/providers/openAI.js

@@ -4,6 +4,7 @@ import { AIProviderName } from "../core/types.js";
 import { BaseProvider } from "../core/baseProvider.js";
 import { logger } from "../utils/logger.js";
 import { createTimeoutController, TimeoutError, } from "../utils/timeout.js";
+import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/errors.js";
 import { DEFAULT_MAX_TOKENS, DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { validateApiKey, createOpenAIConfig, getProviderModel, } from "../utils/providerConfig.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
@@ -53,20 +54,28 @@ export class OpenAIProvider extends BaseProvider {
     }
     handleProviderError(error) {
         if (error instanceof TimeoutError) {
-            return new Error(`OpenAI request timed out: ${error.message}`);
+            throw new NetworkError(error.message, this.providerName);
         }
         const errorObj = error;
         const message = errorObj?.message && typeof errorObj.message === "string"
             ? errorObj.message
             : "Unknown error";
+        const errorType = errorObj?.type && typeof errorObj.type === "string"
+            ? errorObj.type
+            : undefined;
         if (message.includes("API_KEY_INVALID") ||
-            message.includes("Invalid API key")) {
-            return new Error("Invalid OpenAI API key. Please check your OPENAI_API_KEY environment variable.");
+            message.includes("Invalid API key") ||
+            errorType === "invalid_api_key") {
+            throw new AuthenticationError("Invalid OpenAI API key. Please check your OPENAI_API_KEY environment variable.", this.providerName);
         }
-        if (message.includes("rate limit")) {
-            return new Error("OpenAI rate limit exceeded. Please try again later.");
+        if (message.includes("rate limit") || errorType === "rate_limit_error") {
+            throw new RateLimitError("OpenAI rate limit exceeded. Please try again later.", this.providerName);
         }
-        return new Error(`OpenAI error: ${message}`);
+        if (message.includes("model_not_found")) {
+            throw new InvalidModelError(`Model not found: ${this.modelName}`, this.providerName);
+        }
+        // Generic provider error
+        throw new ProviderError(`OpenAI error: ${message}`, this.providerName);
     }
     /**
      * executeGenerate method removed - generation is now handled by BaseProvider.

package/dist/lib/types/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Base error class for all NeuroLink-specific errors.
+ * This allows for easy identification of errors thrown by the SDK.
+ */
+export declare class BaseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a provider encounters a generic error.
+ */
+export declare class ProviderError extends BaseError {
+    provider?: string | undefined;
+    constructor(message: string, provider?: string | undefined);
+}
+/**
+ * Thrown for authentication-related errors, such as invalid or missing API keys.
+ */
+export declare class AuthenticationError extends ProviderError {
+    constructor(message: string, provider?: string);
+}
+/**
+ * Thrown for authorization errors, where the user does not have permission.
+ */
+export declare class AuthorizationError extends ProviderError {
+    constructor(message: string, provider?: string);
+}
+/**
+ * Thrown for network-related issues, such as connectivity problems or timeouts.
+ */
+export declare class NetworkError extends ProviderError {
+    constructor(message: string, provider?: string);
+}
+/**
+ * Thrown when an API rate limit has been exceeded.
+ */
+export declare class RateLimitError extends ProviderError {
+    constructor(message: string, provider?: string);
+}
+/**
+ * Thrown when a specified model is not found or is invalid for the provider.
+ */
+export declare class InvalidModelError extends ProviderError {
+    constructor(message: string, provider?: string);
+}