@juspay/neurolink 6.0.0 → 6.2.0

package/dist/lib/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/lib/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/lib/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
  */

package/dist/lib/utils/providerUtils.js

@@ -1,50 +1,33 @@
 /**
  * Utility functions for AI provider management
+ * Consolidated from providerUtils-fixed.ts
  */
+import { AIProviderFactory } from "../core/factory.js";
 import { logger } from "./logger.js";
 /**
- * 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
  */
 export async function getBestProvider(requestedProvider) {
-    // If a specific provider is requested, return it (existing logic)
-    if (requestedProvider && requestedProvider !== "auto") {
-        return requestedProvider;
-    }
     // 🔧 FIX: Check for explicit default provider in env
     if (process.env.DEFAULT_PROVIDER &&
-        isProviderConfigured(process.env.DEFAULT_PROVIDER)) {
+        (await isProviderAvailable(process.env.DEFAULT_PROVIDER))) {
         return process.env.DEFAULT_PROVIDER;
     }
-    // 🔧 FIX: Special case for Ollama when explicitly configured
+    // 🔧 FIX: Special case for Ollama - prioritize local when available
     if (process.env.OLLAMA_BASE_URL && process.env.OLLAMA_MODEL) {
-        // Quick connectivity check for Ollama (non-blocking)
         try {
-            const controller = new AbortController();
-            const timeout = setTimeout(() => controller.abort(), 2000);
-            let res;
-            try {
-                res = await fetch("http://localhost:11434/api/tags", {
-                    method: "GET",
-                    signal: controller.signal,
-                });
-                clearTimeout(timeout);
-                if (res.ok) {
-                    return "ollama"; // Prioritize working local AI
-                }
-            }
-            catch {
-                clearTimeout(timeout);
-                // Fall through to cloud providers
+            if (await isProviderAvailable("ollama")) {
+                logger.debug(`[getBestProvider] Prioritizing working local Ollama`);
+                return "ollama"; // Prioritize working local AI
             }
-            // Removed redundant if (res.ok) block here
         }
         catch {
             // Fall through to cloud providers
         }
     }
-    // Existing provider priority logic...
     const providers = [
         "google-ai",
         "anthropic",
@@ -56,24 +39,58 @@ export async function getBestProvider(requestedProvider) {
         "bedrock",
         "ollama", // Keep as fallback
     ];
-    // Check which providers have their required environment variables
+    if (requestedProvider && requestedProvider !== "auto") {
+        if (await isProviderAvailable(requestedProvider)) {
+            logger.debug(`[getBestProvider] Using requested provider: ${requestedProvider}`);
+            return requestedProvider;
+        }
+        else {
+            logger.warn(`[getBestProvider] Requested provider '${requestedProvider}' is not available. Falling back to auto-selection.`);
+        }
+    }
     for (const provider of providers) {
-        if (isProviderConfigured(provider)) {
+        if (await isProviderAvailable(provider)) {
             logger.debug(`[getBestProvider] Selected provider: ${provider}`);
             return provider;
         }
     }
-    // Default to bedrock if nothing is configured
-    logger.warn("[getBestProvider] No providers configured, defaulting to bedrock");
-    return "bedrock";
+    throw new Error("No available AI providers. Please check your configurations.");
 }
 /**
- * Check if a provider has the minimum required configuration
- * @param provider - Provider name to check
- * @returns True if the provider appears to be configured
+ * Check if a provider is truly available by performing a quick authentication test.
+ * Enhanced function consolidated from providerUtils-fixed.ts
+ * @param providerName - The name of the provider to check.
+ * @returns True if the provider is available and authenticated.
  */
-function isProviderConfigured(provider) {
-    return hasProviderEnvVars(provider);
+async function isProviderAvailable(providerName) {
+    if (!hasProviderEnvVars(providerName) && providerName !== "ollama") {
+        return false;
+    }
+    if (providerName === "ollama") {
+        try {
+            const response = await fetch("http://localhost:11434/api/tags", {
+                method: "GET",
+                signal: AbortSignal.timeout(2000),
+            });
+            if (response.ok) {
+                const { models } = await response.json();
+                const defaultOllamaModel = "llama3.2:latest";
+                return models.some((m) => m.name === defaultOllamaModel);
+            }
+            return false;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    try {
+        const provider = await AIProviderFactory.createProvider(providerName);
+        await provider.generate({ prompt: "test", maxTokens: 1 });
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
 }
 /**
  * Check if a provider has the minimum required environment variables

package/dist/lib/utils/timeout.d.ts

@@ -66,4 +66,75 @@ export declare function getDefaultTimeout(provider: string, operation?: "generat
  * @returns Promise that rejects with TimeoutError
  */
 export declare function createTimeoutPromise(timeout: number | string | undefined, provider: string, operation: "generate" | "stream"): Promise<never> | null;
-export { createTimeoutController } from "../providers/timeout-wrapper.js";
+export interface TimeoutConfig {
+    operation: string;
+    timeout?: number | string;
+    gracefulShutdown?: boolean;
+    retryOnTimeout?: boolean;
+    maxRetries?: number;
+    abortSignal?: AbortSignal;
+}
+export interface TimeoutResult<T> {
+    success: boolean;
+    data?: T;
+    error?: Error;
+    timedOut: boolean;
+    executionTime: number;
+    retriesUsed: number;
+}
+/**
+ * Enhanced timeout manager with proper cleanup and abort controller integration
+ * Consolidated from timeout-manager.ts
+ */
+export declare class TimeoutManager {
+    private activeTimeouts;
+    /**
+     * Execute operation with timeout and proper cleanup
+     */
+    executeWithTimeout<T>(operation: () => Promise<T>, config: TimeoutConfig): Promise<TimeoutResult<T>>;
+    private performSingleOperation;
+    private getTimeoutMs;
+    private generateOperationId;
+    private createTimeoutPromise;
+    private registerTimeout;
+    cleanup(operationId: string): void;
+    gracefulShutdown(): void;
+}
+/**
+ * Wrapper functions consolidated from timeout-wrapper.ts
+ */
+/**
+ * Wrap a promise with timeout
+ * @param promise - The promise to wrap
+ * @param timeout - Timeout duration (number in ms or string with unit)
+ * @param provider - Provider name for error messages
+ * @param operation - Operation type (generate or stream)
+ * @returns The result of the promise or throws TimeoutError
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeout: number | string | undefined, provider: string, operation: "generate" | "stream"): Promise<T>;
+/**
+ * Wrap a streaming async generator with timeout
+ * @param generator - The async generator to wrap
+ * @param timeout - Timeout duration for the entire stream
+ * @param provider - Provider name for error messages
+ * @returns Wrapped async generator that respects timeout
+ */
+export declare function withStreamingTimeout<T>(generator: AsyncGenerator<T>, timeout: number | string | undefined, provider: string): AsyncGenerator<T>;
+/**
+ * Create an abort controller with timeout
+ * @param timeout - Timeout duration
+ * @param provider - Provider name for error messages
+ * @param operation - Operation type
+ * @returns AbortController and cleanup function
+ */
+export declare function createTimeoutController(timeout: number | string | undefined, provider: string, operation: "generate" | "stream"): {
+    controller: AbortController;
+    cleanup: () => void;
+    timeoutMs: number;
+} | null;
+/**
+ * Merge abort signals (for combining user abort with timeout)
+ * @param signals - Array of abort signals to merge
+ * @returns Combined abort controller
+ */
+export declare function mergeAbortSignals(signals: (AbortSignal | undefined)[]): AbortController;