@juspay/neurolink 6.1.0 → 6.2.1

package/dist/utils/logger.js

@@ -1,25 +1,190 @@
 /**
- * NeuroLink Logger Utility
+ * NeuroLink Unified Logger Utility
  *
- * Provides conditional logging based on NEUROLINK_DEBUG environment variable
+ * Centralized logging for the entire NeuroLink ecosystem
+ * Supports both CLI --debug flag and NEUROLINK_DEBUG environment variable
+ * Migrated from MCP logging with enhanced features
  */
+// Pre-computed uppercase log levels for performance optimization
+const UPPERCASE_LOG_LEVELS = {
+    debug: "DEBUG",
+    info: "INFO",
+    warn: "WARN",
+    error: "ERROR",
+};
+class NeuroLinkLogger {
+    logLevel = "info";
+    logs = [];
+    maxLogs = 1000;
+    isDebugMode;
+    constructor() {
+        // Cache debug mode check to avoid repeated array searches
+        this.isDebugMode =
+            process.argv.includes("--debug") ||
+                process.env.NEUROLINK_DEBUG === "true";
+        // Check NEUROLINK_LOG_LEVEL for consistency with the unified NeuroLink logger
+        let envLevel = process.env.NEUROLINK_LOG_LEVEL?.toLowerCase();
+        // Fallback to MCP_LOG_LEVEL for backward compatibility (if needed)
+        if (!envLevel) {
+            envLevel = process.env.MCP_LOG_LEVEL?.toLowerCase();
+        }
+        if (envLevel && ["debug", "info", "warn", "error"].includes(envLevel)) {
+            this.logLevel = envLevel;
+        }
+    }
+    setLogLevel(level) {
+        this.logLevel = level;
+    }
+    shouldLog(level) {
+        // Hide all logs except errors unless debugging
+        if (!this.isDebugMode && level !== "error") {
+            return false;
+        }
+        const levels = ["debug", "info", "warn", "error"];
+        return levels.indexOf(level) >= levels.indexOf(this.logLevel);
+    }
+    getLogPrefix(timestamp, level) {
+        return `[${timestamp}] [NEUROLINK:${UPPERCASE_LOG_LEVELS[level]}]`;
+    }
+    /**
+     * Outputs a log entry to the console based on the log level.
+     *
+     * @param level - The log level (debug, info, warn, error).
+     * @param prefix - The formatted log prefix.
+     * @param message - The log message.
+     * @param data - Optional additional data to log.
+     */
+    outputToConsole(level, prefix, message, data) {
+        const logMethod = {
+            debug: console.debug,
+            info: console.info,
+            warn: console.warn,
+            error: console.error,
+        }[level];
+        if (data !== undefined && data !== null) {
+            logMethod(prefix, message, data);
+        }
+        else {
+            logMethod(prefix, message);
+        }
+    }
+    log(level, message, data) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+        const entry = {
+            level,
+            message,
+            timestamp: new Date(),
+            data,
+        };
+        // Store log entry
+        this.logs.push(entry);
+        // Trim old logs
+        if (this.logs.length > this.maxLogs) {
+            this.logs = this.logs.slice(-this.maxLogs);
+        }
+        // Console output
+        const timestamp = entry.timestamp.toISOString();
+        const prefix = this.getLogPrefix(timestamp, level);
+        this.outputToConsole(level, prefix, message, data);
+    }
+    debug(message, data) {
+        this.log("debug", message, data);
+    }
+    info(message, data) {
+        this.log("info", message, data);
+    }
+    warn(message, data) {
+        this.log("warn", message, data);
+    }
+    error(message, data) {
+        this.log("error", message, data);
+    }
+    getLogs(level) {
+        if (level) {
+            return this.logs.filter((log) => log.level === level);
+        }
+        return [...this.logs];
+    }
+    clearLogs() {
+        this.logs = [];
+    }
+    /**
+     * Logs messages unconditionally using `console.log`.
+     *
+     * This method is part of a legacy simple logger interface for backward compatibility.
+     * It bypasses the structured logging mechanism and should only be used when
+     * unstructured, unconditional logging is required.
+     *
+     * @param args - The arguments to log. These are passed directly to `console.log`.
+     */
+    always(...args) {
+        console.log(...args);
+    }
+}
+// Export singleton instance
+const neuroLinkLogger = new NeuroLinkLogger();
+// Helper function to process arguments with minimal overhead
+function processLoggerArgs(args, logMethod) {
+    if (args.length === 0) {
+        return;
+    }
+    // Serialize the first argument robustly to handle complex objects
+    const message = (() => {
+        try {
+            return typeof args[0] === "string" ? args[0] : JSON.stringify(args[0]);
+        }
+        catch {
+            return "[Unserializable Object]";
+        }
+    })();
+    const data = args.length === 2 ? args[1] : args.length > 2 ? args.slice(1) : undefined;
+    logMethod(message, data);
+}
+// Main unified logger export
 export const logger = {
     debug: (...args) => {
-        if (process.env.NEUROLINK_DEBUG === "true") {
-            console.log(...args);
+        if (neuroLinkLogger.shouldLog("debug")) {
+            processLoggerArgs(args, (message, data) => neuroLinkLogger.debug(message, data));
         }
     },
     info: (...args) => {
-        // Completely disabled for clean CLI demo output
+        if (neuroLinkLogger.shouldLog("info")) {
+            processLoggerArgs(args, (message, data) => neuroLinkLogger.info(message, data));
+        }
     },
     warn: (...args) => {
-        // Completely disabled for clean CLI demo output
+        if (neuroLinkLogger.shouldLog("warn")) {
+            processLoggerArgs(args, (message, data) => neuroLinkLogger.warn(message, data));
+        }
     },
     error: (...args) => {
-        // Always show errors regardless of debug mode
-        console.error(...args);
+        if (neuroLinkLogger.shouldLog("error")) {
+            processLoggerArgs(args, (message, data) => neuroLinkLogger.error(message, data));
+        }
     },
     always: (...args) => {
-        console.log(...args);
+        neuroLinkLogger.always(...args);
     },
+    // Expose structured logging methods
+    setLogLevel: (level) => neuroLinkLogger.setLogLevel(level),
+    getLogs: (level) => neuroLinkLogger.getLogs(level),
+    clearLogs: () => neuroLinkLogger.clearLogs(),
+};
+// MCP compatibility exports - all use the same unified logger
+export const mcpLogger = neuroLinkLogger;
+export const autoDiscoveryLogger = neuroLinkLogger;
+export const registryLogger = neuroLinkLogger;
+export const unifiedRegistryLogger = neuroLinkLogger;
+// Global log level setter
+export function setGlobalMCPLogLevel(level) {
+    neuroLinkLogger.setLogLevel(level);
+}
+// Export LogLevel enum for runtime use
+export const LogLevels = {
+    debug: "debug",
+    info: "info",
+    warn: "warn",
+    error: "error",
 };

package/dist/utils/providerConfig.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Provider Configuration Utility
+ * Consolidated configuration helpers for all AI providers
+ * Eliminates duplicate error messages and configuration logic
+ * Enhanced with format validation and advanced error classification
+ */
+/**
+ * Configuration options for provider validation
+ */
+export interface ProviderConfigOptions {
+    providerName: string;
+    envVarName: string;
+    setupUrl: string;
+    description: string;
+    instructions: string[];
+    fallbackEnvVars?: string[];
+}
+/**
+ * Enhanced validation result with format checking
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    apiKey: string;
+    formatValid?: boolean;
+    errorType?: "missing" | "format" | "config";
+    error?: string;
+}
+/**
+ * Validates API key format for a specific provider
+ * @param providerKey Provider identifier (e.g., 'openai', 'anthropic')
+ * @param apiKey The API key to validate
+ * @returns True if format is valid
+ */
+export declare function validateApiKeyFormat(providerKey: string, apiKey: string): boolean;
+/**
+ * Enhanced validation with format checking
+ * @param config Provider configuration options
+ * @param enableFormatValidation Whether to validate API key format
+ * @returns Validation result with detailed information
+ */
+export declare function validateApiKeyEnhanced(config: ProviderConfigOptions, enableFormatValidation?: boolean): ValidationResult;
+/**
+ * Validates an API key for a provider and returns it (BACKWARD COMPATIBLE)
+ * Throws detailed error message if validation fails
+ * @param config Provider configuration options
+ * @returns The validated API key
+ */
+export declare function validateApiKey(config: ProviderConfigOptions): string;
+/**
+ * Gets a provider model with fallback to default
+ * @param envVar Environment variable name for the model
+ * @param defaultModel Default model to use if env var not set
+ * @returns The model name to use
+ */
+export declare function getProviderModel(envVar: string, defaultModel: string): string;
+/**
+ * Checks if provider credentials are available
+ * @param envVars Array of environment variable names to check
+ * @returns True if any of the credentials are available
+ */
+export declare function hasProviderCredentials(envVars: string[]): boolean;
+/**
+ * Creates Anthropic provider configuration
+ */
+export declare function createAnthropicConfig(): ProviderConfigOptions;
+/**
+ * Creates OpenAI provider configuration
+ */
+export declare function createOpenAIConfig(): ProviderConfigOptions;
+/**
+ * Creates HuggingFace provider configuration
+ */
+export declare function createHuggingFaceConfig(): ProviderConfigOptions;
+/**
+ * Creates Mistral provider configuration
+ */
+export declare function createMistralConfig(): ProviderConfigOptions;
+/**
+ * Creates AWS Access Key configuration for Bedrock
+ */
+export declare function createAWSAccessKeyConfig(): ProviderConfigOptions;
+/**
+ * Creates AWS Secret Key configuration for Bedrock
+ */
+export declare function createAWSSecretConfig(): ProviderConfigOptions;
+/**
+ * Creates Azure OpenAI API Key configuration
+ */
+export declare function createAzureAPIKeyConfig(): ProviderConfigOptions;
+/**
+ * Creates Azure OpenAI Endpoint configuration
+ */
+export declare function createAzureEndpointConfig(): ProviderConfigOptions;
+/**
+ * Creates Google Vertex Project ID configuration
+ */
+export declare function createVertexProjectConfig(): ProviderConfigOptions;
+/**
+ * Creates Google Cloud Authentication configuration
+ */
+export declare function createGoogleAuthConfig(): ProviderConfigOptions;
+/**
+ * Creates Anthropic Base Provider configuration
+ */
+export declare function createAnthropicBaseConfig(): ProviderConfigOptions;
+/**
+ * Gets AWS Region with default fallback
+ */
+export declare function getAWSRegion(): string;
+/**
+ * Gets AWS Session Token if available
+ */
+export declare function getAWSSessionToken(): string | undefined;
+/**
+ * Checks if HuggingFace credentials are available
+ */
+export declare function hasHuggingFaceCredentials(): boolean;

package/dist/utils/providerConfig.js

@@ -0,0 +1,353 @@
+/**
+ * Provider Configuration Utility
+ * Consolidated configuration helpers for all AI providers
+ * Eliminates duplicate error messages and configuration logic
+ * Enhanced with format validation and advanced error classification
+ */
+/**
+ * API key format validation patterns (extracted from advanced validation system)
+ */
+const API_KEY_FORMATS = {
+    openai: /^sk-[A-Za-z0-9]{48,}$/,
+    anthropic: /^sk-ant-[A-Za-z0-9\-_]{95,}$/,
+    "google-ai": /^AIza[A-Za-z0-9\-_]{35}$/,
+    huggingface: /^hf_[A-Za-z0-9]{37}$/,
+    mistral: /^[A-Za-z0-9]{32}$/,
+    azure: /^[A-Za-z0-9]{32,}$/,
+    aws: /^[A-Z0-9]{20}$/, // Access Key ID format
+    "google-vertex": /^[A-Za-z0-9\-_]{1,}$/, // Project ID format
+};
+/**
+ * Validates API key format for a specific provider
+ * @param providerKey Provider identifier (e.g., 'openai', 'anthropic')
+ * @param apiKey The API key to validate
+ * @returns True if format is valid
+ */
+export function validateApiKeyFormat(providerKey, apiKey) {
+    const format = API_KEY_FORMATS[providerKey.toLowerCase()];
+    if (!format) {
+        // No format validation available, assume valid if not empty
+        return apiKey.length > 0;
+    }
+    return format.test(apiKey);
+}
+/**
+ * Enhanced validation with format checking
+ * @param config Provider configuration options
+ * @param enableFormatValidation Whether to validate API key format
+ * @returns Validation result with detailed information
+ */
+export function validateApiKeyEnhanced(config, enableFormatValidation = false) {
+    // Check primary environment variable
+    let apiKey = process.env[config.envVarName];
+    // Check fallback environment variables if provided
+    if (!apiKey && config.fallbackEnvVars) {
+        for (const fallbackVar of config.fallbackEnvVars) {
+            apiKey = process.env[fallbackVar];
+            if (apiKey) {
+                break;
+            }
+        }
+    }
+    if (!apiKey) {
+        return {
+            isValid: false,
+            apiKey: "",
+            errorType: "missing",
+            error: createConfigErrorMessage(config),
+        };
+    }
+    // Optional format validation
+    if (enableFormatValidation) {
+        const providerKey = config.providerName.toLowerCase().replace(/\s/g, "-");
+        const formatValid = validateApiKeyFormat(providerKey, apiKey);
+        if (!formatValid) {
+            return {
+                isValid: false,
+                apiKey,
+                formatValid: false,
+                errorType: "format",
+                error: `Invalid ${config.providerName} API key format. Please check your API key.`,
+            };
+        }
+    }
+    return {
+        isValid: true,
+        apiKey,
+        formatValid: enableFormatValidation ? true : undefined,
+    };
+}
+/**
+ * Validates an API key for a provider and returns it (BACKWARD COMPATIBLE)
+ * Throws detailed error message if validation fails
+ * @param config Provider configuration options
+ * @returns The validated API key
+ */
+export function validateApiKey(config) {
+    // Check primary environment variable
+    let apiKey = process.env[config.envVarName];
+    // Check fallback environment variables if provided
+    if (!apiKey && config.fallbackEnvVars) {
+        for (const fallbackVar of config.fallbackEnvVars) {
+            apiKey = process.env[fallbackVar];
+            if (apiKey) {
+                break;
+            }
+        }
+    }
+    if (!apiKey) {
+        throw new Error(createConfigErrorMessage(config));
+    }
+    return apiKey;
+}
+/**
+ * Creates a standardized configuration error message
+ * @param config Provider configuration options
+ * @returns Formatted error message with setup instructions
+ */
+function createConfigErrorMessage(config) {
+    const envVarsList = config.fallbackEnvVars
+        ? [config.envVarName, ...config.fallbackEnvVars].join(" or ")
+        : config.envVarName;
+    return `❌ ${config.providerName} Provider Configuration Error
+
+Missing required environment variable: ${envVarsList}
+
+🔧 Step 1: Get ${config.description}
+${config.instructions.join("\n")}
+
+🔧 Step 2: Set Environment Variable
+Add to your .env file:
+${config.envVarName}=your_key_here
+
+🔧 Step 3: Restart Application
+Restart your application to load the new environment variables.`;
+}
+/**
+ * Gets a provider model with fallback to default
+ * @param envVar Environment variable name for the model
+ * @param defaultModel Default model to use if env var not set
+ * @returns The model name to use
+ */
+export function getProviderModel(envVar, defaultModel) {
+    return process.env[envVar] || defaultModel;
+}
+/**
+ * Checks if provider credentials are available
+ * @param envVars Array of environment variable names to check
+ * @returns True if any of the credentials are available
+ */
+export function hasProviderCredentials(envVars) {
+    return envVars.some((envVar) => !!process.env[envVar]);
+}
+// =============================================================================
+// PROVIDER-SPECIFIC CONFIGURATION CREATORS
+// =============================================================================
+/**
+ * Creates Anthropic provider configuration
+ */
+export function createAnthropicConfig() {
+    return {
+        providerName: "Anthropic",
+        envVarName: "ANTHROPIC_API_KEY",
+        setupUrl: "https://console.anthropic.com/",
+        description: "Anthropic API Key",
+        instructions: [
+            "1. Visit: https://console.anthropic.com/",
+            "2. Sign in or create an account",
+            "3. Go to API Keys section",
+            "4. Create a new API key",
+        ],
+    };
+}
+/**
+ * Creates OpenAI provider configuration
+ */
+export function createOpenAIConfig() {
+    return {
+        providerName: "OPENAI",
+        envVarName: "OPENAI_API_KEY",
+        setupUrl: "https://platform.openai.com/api-keys",
+        description: "Credentials",
+        instructions: [
+            "1. Visit: https://platform.openai.com/api-keys",
+            "2. Create new API key",
+            "3. Copy the key",
+        ],
+    };
+}
+/**
+ * Creates HuggingFace provider configuration
+ */
+export function createHuggingFaceConfig() {
+    return {
+        providerName: "HuggingFace",
+        envVarName: "HUGGINGFACE_API_KEY",
+        setupUrl: "https://huggingface.co/settings/tokens",
+        description: "Credentials",
+        instructions: [
+            "1. Visit: https://huggingface.co/settings/tokens",
+            "2. Create new API token",
+            "3. Copy the token",
+        ],
+        fallbackEnvVars: ["HF_TOKEN"],
+    };
+}
+/**
+ * Creates Mistral provider configuration
+ */
+export function createMistralConfig() {
+    return {
+        providerName: "Mistral",
+        envVarName: "MISTRAL_API_KEY",
+        setupUrl: "https://console.mistral.ai/",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://console.mistral.ai/",
+            "2. Create or sign in to your account",
+            "3. Generate a new API key",
+        ],
+    };
+}
+/**
+ * Creates AWS Access Key configuration for Bedrock
+ */
+export function createAWSAccessKeyConfig() {
+    return {
+        providerName: "AWS Bedrock",
+        envVarName: "AWS_ACCESS_KEY_ID",
+        setupUrl: "https://console.aws.amazon.com/iam/",
+        description: "AWS Credentials",
+        instructions: [
+            "1. Visit: https://console.aws.amazon.com/iam/",
+            "2. Create IAM user with Bedrock permissions",
+            "3. Generate access key",
+        ],
+    };
+}
+/**
+ * Creates AWS Secret Key configuration for Bedrock
+ */
+export function createAWSSecretConfig() {
+    return {
+        providerName: "AWS Bedrock",
+        envVarName: "AWS_SECRET_ACCESS_KEY",
+        setupUrl: "https://console.aws.amazon.com/iam/",
+        description: "AWS Credentials",
+        instructions: [
+            "1. Visit: https://console.aws.amazon.com/iam/",
+            "2. Create IAM user with Bedrock permissions",
+            "3. Generate access key",
+        ],
+    };
+}
+/**
+ * Creates Azure OpenAI API Key configuration
+ */
+export function createAzureAPIKeyConfig() {
+    return {
+        providerName: "Azure OpenAI",
+        envVarName: "AZURE_OPENAI_API_KEY",
+        setupUrl: "https://portal.azure.com/",
+        description: "Azure OpenAI API Key",
+        instructions: [
+            "1. Visit: https://portal.azure.com/",
+            "2. Create or access Azure OpenAI resource",
+            "3. Get API key from Keys and Endpoint section",
+        ],
+    };
+}
+/**
+ * Creates Azure OpenAI Endpoint configuration
+ */
+export function createAzureEndpointConfig() {
+    return {
+        providerName: "Azure OpenAI",
+        envVarName: "AZURE_OPENAI_ENDPOINT",
+        setupUrl: "https://portal.azure.com/",
+        description: "Azure OpenAI Endpoint",
+        instructions: [
+            "1. Visit: https://portal.azure.com/",
+            "2. Access your Azure OpenAI resource",
+            "3. Copy endpoint URL from Keys and Endpoint section",
+        ],
+    };
+}
+/**
+ * Creates Google Vertex Project ID configuration
+ */
+export function createVertexProjectConfig() {
+    return {
+        providerName: "Google Vertex AI",
+        envVarName: "GOOGLE_CLOUD_PROJECT_ID",
+        setupUrl: "https://console.cloud.google.com/",
+        description: "Google Cloud Credentials",
+        instructions: [
+            "1. Visit: https://console.cloud.google.com/",
+            "2. Create or select a project",
+            "3. Enable Vertex AI API",
+            "4. Set up authentication",
+        ],
+        fallbackEnvVars: ["VERTEX_PROJECT_ID"],
+    };
+}
+/**
+ * Creates Google Cloud Authentication configuration
+ */
+export function createGoogleAuthConfig() {
+    return {
+        providerName: "Google Vertex AI",
+        envVarName: "GOOGLE_APPLICATION_CREDENTIALS",
+        setupUrl: "https://console.cloud.google.com/",
+        description: "Google Cloud authentication",
+        instructions: [
+            "🔧 Option 1: Service Account Key File",
+            "GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json",
+            "",
+            "🔧 Option 2: Service Account Key (Base64)",
+            "GOOGLE_SERVICE_ACCOUNT_KEY=base64_encoded_key",
+            "",
+            "🔧 Option 3: Individual Credentials",
+            "GOOGLE_AUTH_CLIENT_EMAIL=your-service-account@project.iam.gserviceaccount.com",
+            "GOOGLE_AUTH_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----...",
+        ],
+        fallbackEnvVars: ["GOOGLE_SERVICE_ACCOUNT_KEY", "GOOGLE_AUTH_CLIENT_EMAIL"],
+    };
+}
+/**
+ * Creates Anthropic Base Provider configuration
+ */
+export function createAnthropicBaseConfig() {
+    return {
+        providerName: "ANTHROPIC",
+        envVarName: "ANTHROPIC_API_KEY",
+        setupUrl: "https://console.anthropic.com/",
+        description: "Credentials",
+        instructions: [
+            "Get your API key from https://console.anthropic.com/",
+            "",
+            "💡 Step 2: Add to your .env file (or export in CLI):",
+        ],
+    };
+}
+// =============================================================================
+// HELPER FUNCTIONS FOR SPECIFIC PROVIDER NEEDS
+// =============================================================================
+/**
+ * Gets AWS Region with default fallback
+ */
+export function getAWSRegion() {
+    return process.env.AWS_REGION || "us-east-1";
+}
+/**
+ * Gets AWS Session Token if available
+ */
+export function getAWSSessionToken() {
+    return process.env.AWS_SESSION_TOKEN;
+}
+/**
+ * Checks if HuggingFace credentials are available
+ */
+export function hasHuggingFaceCredentials() {
+    return hasProviderCredentials(["HUGGINGFACE_API_KEY", "HF_TOKEN"]);
+}

package/dist/utils/providerUtils.d.ts

@@ -1,5 +1,6 @@
 /**
- * Get the best available provider based on preferences and availability (async)
+ * Get the best available provider based on real-time availability checks
+ * Enhanced version consolidated from providerUtils-fixed.ts
  * @param requestedProvider - Optional preferred provider name
  * @returns The best provider name to use
  */