@juspay/neurolink 3.0.1 → 4.1.0

package/dist/config/configManager.js

@@ -0,0 +1,300 @@
+/**
+ * NeuroLink Config Manager with Backup/Restore System
+ * Industry standard configuration management with safety mechanisms
+ */
+import { promises as fs } from "fs";
+import path from "path";
+import crypto from "crypto";
+const { readFile, writeFile, readdir, mkdir, unlink, access } = fs;
+/**
+ * Enhanced Config Manager with automatic backup/restore capabilities
+ */
+export class NeuroLinkConfigManager {
+    configPath = ".neurolink.config";
+    backupDir = ".neurolink.backups";
+    config = null;
+    configCache = new Map();
+    /**
+     * Load configuration with caching
+     */
+    async loadConfig() {
+        if (!this.config) {
+            this.config = await this.readConfigFile();
+        }
+        return this.config;
+    }
+    /**
+     * Update configuration with automatic backup
+     */
+    async updateConfig(updates, options = {}) {
+        const { createBackup = true, validate = true, merge = true, reason = "update", silent = false, } = options;
+        // ALWAYS create backup before updating (unless explicitly disabled)
+        if (createBackup) {
+            await this.createBackup(reason);
+            if (!silent) {
+                console.log("💾 Backup created before config update");
+            }
+        }
+        const existing = await this.loadConfig();
+        // Merge or replace based on options
+        this.config = merge
+            ? { ...existing, ...updates, lastUpdated: Date.now() }
+            : { ...updates, lastUpdated: Date.now() };
+        // Validate config if requested
+        if (validate) {
+            const validation = await this.validateConfig(this.config);
+            if (!validation.valid) {
+                throw new Error(`Config validation failed: ${validation.errors.join(", ")}`);
+            }
+        }
+        try {
+            await this.persistConfig(this.config);
+            if (!silent) {
+                console.log("✅ Configuration updated successfully");
+            }
+        }
+        catch (error) {
+            // Auto-restore on failure
+            if (createBackup) {
+                await this.restoreLatestBackup();
+                if (!silent) {
+                    console.log("🔄 Auto-restored from backup due to error");
+                }
+            }
+            throw new Error(`Config update failed, restored from backup: ${error.message}`);
+        }
+    }
+    /**
+     * Create a backup with metadata
+     */
+    async createBackup(reason = "manual") {
+        await this.ensureBackupDirectory();
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const backupFilename = `neurolink-config-${timestamp}.js`;
+        const backupPath = path.join(this.backupDir, backupFilename);
+        const currentConfig = await this.loadConfig();
+        const configHash = this.generateConfigHash(currentConfig);
+        const backupMetadata = {
+            reason,
+            timestamp: Date.now(),
+            version: currentConfig.configVersion || "unknown",
+            originalPath: this.configPath,
+            hash: configHash,
+            size: JSON.stringify(currentConfig).length,
+            createdBy: "NeuroLinkConfigManager",
+        };
+        const backupContent = `// NeuroLink Config Backup - ${reason}
+// Created: ${new Date().toISOString()}
+// Reason: ${reason}
+// Hash: ${configHash}
+export const metadata = ${JSON.stringify(backupMetadata, null, 2)};
+export default ${JSON.stringify(currentConfig, null, 2)};`;
+        await writeFile(backupPath, backupContent, "utf-8");
+        return backupPath;
+    }
+    /**
+     * List all available backups
+     */
+    async listBackups() {
+        await this.ensureBackupDirectory();
+        try {
+            const files = await readdir(this.backupDir);
+            const backupFiles = files.filter((f) => f.startsWith("neurolink-config-") && f.endsWith(".js"));
+            const backups = [];
+            for (const file of backupFiles) {
+                try {
+                    const filePath = path.join(this.backupDir, file);
+                    const content = await readFile(filePath, "utf-8");
+                    const metadata = this.extractMetadataFromBackup(content);
+                    const config = this.extractConfigFromBackup(content);
+                    backups.push({
+                        filename: file,
+                        path: filePath,
+                        metadata,
+                        config,
+                    });
+                }
+                catch (error) {
+                    console.warn(`Failed to read backup ${file}:`, error.message);
+                }
+            }
+            return backups.sort((a, b) => b.metadata.timestamp - a.metadata.timestamp);
+        }
+        catch (error) {
+            console.warn("Failed to list backups:", error.message);
+            return [];
+        }
+    }
+    /**
+     * Restore from specific backup
+     */
+    async restoreFromBackup(backupFilename) {
+        const backupPath = path.join(this.backupDir, backupFilename);
+        // Create backup of current config before restore
+        await this.createBackup("pre-restore");
+        try {
+            const content = await readFile(backupPath, "utf-8");
+            const restoredConfig = this.extractConfigFromBackup(content);
+            // Validate restored config
+            const validation = await this.validateConfig(restoredConfig);
+            if (!validation.valid) {
+                throw new Error(`Backup config is invalid: ${validation.errors.join(", ")}`);
+            }
+            this.config = restoredConfig;
+            await this.persistConfig(this.config);
+            console.log(`✅ Config restored from backup: ${backupFilename}`);
+        }
+        catch (error) {
+            throw new Error(`Failed to restore from backup ${backupFilename}: ${error.message}`);
+        }
+    }
+    /**
+     * Restore from latest backup
+     */
+    async restoreLatestBackup() {
+        const backups = await this.listBackups();
+        if (backups.length === 0) {
+            throw new Error("No backups available for restore");
+        }
+        await this.restoreFromBackup(backups[0].filename);
+    }
+    /**
+     * Clean up old backups
+     */
+    async cleanupOldBackups(keepCount = 10) {
+        const backups = await this.listBackups();
+        const toDelete = backups.slice(keepCount);
+        for (const backup of toDelete) {
+            try {
+                await unlink(backup.path);
+                console.log(`🗑️ Deleted old backup: ${backup.filename}`);
+            }
+            catch (error) {
+                console.warn(`Failed to delete backup ${backup.filename}:`, error.message);
+            }
+        }
+    }
+    /**
+     * Update provider status
+     */
+    async updateProviderStatus(providerId, status) {
+        const config = await this.loadConfig();
+        if (!config.providers) {
+            config.providers = {};
+        }
+        config.providers[providerId] = {
+            ...config.providers[providerId],
+            ...status,
+            lastCheck: Date.now(),
+        };
+        await this.updateConfig({ providers: config.providers }, { reason: `provider-${providerId}-update` });
+    }
+    /**
+     * Validate configuration
+     */
+    async validateConfig(config) {
+        const result = {
+            valid: true,
+            errors: [],
+            warnings: [],
+            suggestions: [],
+        };
+        // Basic validation
+        if (!config || typeof config !== "object") {
+            result.errors.push("Config must be a valid object");
+            result.valid = false;
+            return result;
+        }
+        // Version validation
+        if (config.configVersion && typeof config.configVersion !== "string") {
+            result.errors.push("configVersion must be a string");
+            result.valid = false;
+        }
+        // Provider validation
+        if (config.providers) {
+            if (typeof config.providers !== "object") {
+                result.errors.push("providers must be an object");
+                result.valid = false;
+            }
+            else {
+                // Check for default provider
+                if (!config.providers.defaultProvider) {
+                    result.warnings.push("No default provider specified");
+                    result.suggestions.push('Consider setting providers.defaultProvider to "googleAi"');
+                }
+            }
+        }
+        // Performance validation
+        if (config.performance?.cache?.ttlMs) {
+            if (config.performance.cache.ttlMs < 1000) {
+                result.warnings.push("Cache TTL is very low (< 1 second)");
+            }
+        }
+        return result;
+    }
+    /**
+     * Generate default configuration
+     */
+    async generateDefaultConfig() {
+        const { DEFAULT_CONFIG } = await import("./types.js");
+        return {
+            ...DEFAULT_CONFIG,
+            lastUpdated: Date.now(),
+        };
+    }
+    // Private helper methods
+    async ensureBackupDirectory() {
+        try {
+            await mkdir(this.backupDir, { recursive: true });
+        }
+        catch (error) {
+            console.warn("Failed to create backup directory:", error.message);
+        }
+    }
+    async readConfigFile() {
+        try {
+            // Check if config file exists
+            await access(this.configPath);
+            const content = await readFile(this.configPath, "utf-8");
+            // Parse as JavaScript module
+            const configMatch = content.match(/export default ([\s\S]+);?$/);
+            if (configMatch) {
+                const configJson = configMatch[1].trim();
+                return JSON.parse(configJson);
+            }
+            throw new Error("Invalid config file format");
+        }
+        catch (error) {
+            console.log("Config file not found, generating default...");
+            return await this.generateDefaultConfig();
+        }
+    }
+    async persistConfig(config) {
+        const configContent = `export default ${JSON.stringify(config, null, 2)};`;
+        await writeFile(this.configPath, configContent, "utf-8");
+        // Clear cache after persisting
+        this.config = config;
+    }
+    generateConfigHash(config) {
+        const configString = JSON.stringify(config, Object.keys(config).sort());
+        return crypto
+            .createHash("sha256")
+            .update(configString)
+            .digest("hex")
+            .substring(0, 8);
+    }
+    extractMetadataFromBackup(content) {
+        const metadataMatch = content.match(/export const metadata = ([\s\S]+?);/);
+        if (metadataMatch) {
+            return JSON.parse(metadataMatch[1]);
+        }
+        throw new Error("No metadata found in backup file");
+    }
+    extractConfigFromBackup(content) {
+        const configMatch = content.match(/export default ([\s\S]+);$/);
+        if (configMatch) {
+            return JSON.parse(configMatch[1]);
+        }
+        throw new Error("No config found in backup file");
+    }
+}

package/dist/config/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * NeuroLink Configuration Types
+ * Industry standard camelCase interfaces for config management
+ */
+/**
+ * Main NeuroLink configuration interface
+ */
+export interface NeuroLinkConfig {
+    providers?: Record<string, ProviderConfig>;
+    performance?: PerformanceConfig;
+    analytics?: AnalyticsConfig;
+    lastUpdated?: number;
+    configVersion?: string;
+    [key: string]: unknown;
+}
+/**
+ * Provider-specific configuration
+ */
+export interface ProviderConfig {
+    model?: string;
+    available?: boolean;
+    lastCheck?: number;
+    reason?: string;
+    apiKey?: string;
+    endpoint?: string;
+    maxTokens?: number;
+    temperature?: number;
+    timeout?: number;
+    costPerToken?: number;
+    features?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Performance and caching configuration
+ */
+export interface PerformanceConfig {
+    cache?: CacheConfig;
+    fallback?: FallbackConfig;
+    timeoutMs?: number;
+    maxConcurrency?: number;
+    retryConfig?: RetryConfig;
+}
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+    enabled?: boolean;
+    ttlMs?: number;
+    strategy?: "memory" | "writeThrough" | "cacheAside";
+    maxSize?: number;
+    persistToDisk?: boolean;
+    diskPath?: string;
+}
+/**
+ * Fallback configuration
+ */
+export interface FallbackConfig {
+    enabled?: boolean;
+    maxAttempts?: number;
+    delayMs?: number;
+    circuitBreaker?: boolean;
+    commonResponses?: Record<string, string>;
+    localFallbackPath?: string;
+    degradedMode?: boolean;
+}
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+    enabled?: boolean;
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    exponentialBackoff?: boolean;
+    retryConditions?: string[];
+}
+/**
+ * Analytics configuration
+ */
+export interface AnalyticsConfig {
+    enabled?: boolean;
+    trackTokens?: boolean;
+    trackCosts?: boolean;
+    trackPerformance?: boolean;
+    trackErrors?: boolean;
+    exportFormat?: "json" | "csv" | "prometheus";
+    exportPath?: string;
+    retention?: {
+        days?: number;
+        maxEntries?: number;
+    };
+}
+/**
+ * Backup metadata information
+ */
+export interface BackupInfo {
+    filename: string;
+    path: string;
+    metadata: BackupMetadata;
+    config: NeuroLinkConfig;
+}
+/**
+ * Backup metadata
+ */
+export interface BackupMetadata {
+    reason: string;
+    timestamp: number;
+    version: string;
+    originalPath: string;
+    hash?: string;
+    size?: number;
+    createdBy?: string;
+}
+/**
+ * Configuration validation result
+ */
+export interface ConfigValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    suggestions: string[];
+}
+/**
+ * Configuration update options
+ */
+export interface ConfigUpdateOptions {
+    createBackup?: boolean;
+    validate?: boolean;
+    merge?: boolean;
+    reason?: string;
+    silent?: boolean;
+}
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_CONFIG: NeuroLinkConfig;

package/dist/config/types.js

@@ -0,0 +1,43 @@
+/**
+ * NeuroLink Configuration Types
+ * Industry standard camelCase interfaces for config management
+ */
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG = {
+    providers: {
+        googleAi: {
+            model: "gemini-2.5-pro",
+            available: true,
+            features: ["streaming", "functionCalling"],
+        },
+    },
+    performance: {
+        cache: {
+            enabled: true,
+            ttlMs: 300000, // 5 minutes
+            strategy: "memory",
+            maxSize: 1000,
+        },
+        fallback: {
+            enabled: true,
+            maxAttempts: 3,
+            delayMs: 1000,
+            circuitBreaker: true,
+        },
+        timeoutMs: 30000, // 30 seconds
+        maxConcurrency: 5,
+    },
+    analytics: {
+        enabled: true,
+        trackTokens: true,
+        trackCosts: true,
+        trackPerformance: true,
+        retention: {
+            days: 30,
+            maxEntries: 10000,
+        },
+    },
+    configVersion: "3.0.1",
+};

package/dist/core/analytics.d.ts

@@ -0,0 +1,23 @@
+/**
+ * NeuroLink Analytics System
+ *
+ * Provides lightweight analytics tracking for AI provider usage,
+ * including tokens, costs, performance metrics, and custom context.
+ */
+export interface AnalyticsData {
+    provider: string;
+    model: string;
+    tokens: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    cost?: number;
+    responseTime: number;
+    context?: Record<string, any>;
+    timestamp: string;
+}
+/**
+ * Create analytics data structure from AI response
+ */
+export declare function createAnalytics(provider: string, model: string, result: any, responseTime: number, context?: Record<string, any>): AnalyticsData;

package/dist/core/analytics.js

@@ -0,0 +1,131 @@
+/**
+ * NeuroLink Analytics System
+ *
+ * Provides lightweight analytics tracking for AI provider usage,
+ * including tokens, costs, performance metrics, and custom context.
+ */
+import { logger } from "../utils/logger.js";
+/**
+ * Create analytics data structure from AI response
+ */
+export function createAnalytics(provider, model, result, responseTime, context) {
+    const functionTag = "createAnalytics";
+    try {
+        // Extract token usage from different result formats
+        const tokens = extractTokenUsage(result);
+        // Estimate cost based on provider and tokens
+        const cost = estimateCost(provider, model, tokens);
+        const analytics = {
+            provider,
+            model,
+            tokens,
+            cost,
+            responseTime,
+            context,
+            timestamp: new Date().toISOString(),
+        };
+        logger.debug(`[${functionTag}] Analytics created`, {
+            provider,
+            model,
+            tokens: tokens.total,
+            responseTime,
+            cost,
+        });
+        return analytics;
+    }
+    catch (error) {
+        logger.error(`[${functionTag}] Failed to create analytics`, { error });
+        // Return minimal analytics on error
+        return {
+            provider,
+            model,
+            tokens: { input: 0, output: 0, total: 0 },
+            responseTime,
+            context,
+            timestamp: new Date().toISOString(),
+        };
+    }
+}
+/**
+ * Extract token usage from various AI result formats
+ */
+function extractTokenUsage(result) {
+    // Handle different response formats
+    if (result.usage) {
+        const usage = result.usage;
+        // Standard format
+        if (usage.promptTokens !== undefined &&
+            usage.completionTokens !== undefined) {
+            return {
+                input: usage.promptTokens || 0,
+                output: usage.completionTokens || 0,
+                total: usage.totalTokens || usage.promptTokens + usage.completionTokens,
+            };
+        }
+        // Alternative formats
+        if (usage.input_tokens !== undefined && usage.output_tokens !== undefined) {
+            return {
+                input: usage.input_tokens || 0,
+                output: usage.output_tokens || 0,
+                total: usage.total_tokens || usage.input_tokens + usage.output_tokens,
+            };
+        }
+        // Generic tokens field
+        if (typeof usage.tokens === "number") {
+            return {
+                input: 0,
+                output: 0,
+                total: usage.tokens,
+            };
+        }
+    }
+    // Fallback: estimate from text length
+    const textLength = result.text?.length || result.content?.length || 0;
+    const estimatedTokens = Math.ceil(textLength / 4); // ~4 chars per token
+    return {
+        input: 0,
+        output: estimatedTokens,
+        total: estimatedTokens,
+    };
+}
+/**
+ * Estimate cost based on provider, model, and token usage
+ */
+function estimateCost(provider, model, tokens) {
+    try {
+        // Cost per 1K tokens (USD) - approximate rates as of 2024
+        const costMap = {
+            openai: {
+                "gpt-4": { input: 0.03, output: 0.06 },
+                "gpt-4-turbo": { input: 0.01, output: 0.03 },
+                "gpt-3.5-turbo": { input: 0.0015, output: 0.002 },
+            },
+            anthropic: {
+                "claude-3-opus": { input: 0.015, output: 0.075 },
+                "claude-3-sonnet": { input: 0.003, output: 0.015 },
+                "claude-3-haiku": { input: 0.00025, output: 0.00125 },
+            },
+            "google-ai": {
+                "gemini-pro": { input: 0.00035, output: 0.00105 },
+                "gemini-2.5-flash": { input: 0.000075, output: 0.0003 },
+            },
+        };
+        const providerCosts = costMap[provider.toLowerCase()];
+        if (!providerCosts) {
+            return undefined;
+        }
+        // Find best matching model
+        const modelKey = Object.keys(providerCosts).find((key) => model.toLowerCase().includes(key) || key.includes(model.toLowerCase()));
+        if (!modelKey) {
+            return undefined;
+        }
+        const rates = providerCosts[modelKey];
+        const inputCost = (tokens.input / 1000) * rates.input;
+        const outputCost = (tokens.output / 1000) * rates.output;
+        return Math.round((inputCost + outputCost) * 100000) / 100000; // Round to 5 decimal places
+    }
+    catch (error) {
+        logger.debug("Cost estimation failed", { provider, model, error });
+        return undefined;
+    }
+}

package/dist/core/constants.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Central configuration constants for NeuroLink
+ * Single source of truth for all default values
+ */
+export declare const DEFAULT_MAX_TOKENS = 10000;
+export declare const DEFAULT_TEMPERATURE = 0.7;
+export declare const DEFAULT_TIMEOUT = 30000;
+export declare const DEFAULT_EVALUATION_MAX_TOKENS = 500;
+export declare const DEFAULT_ANALYSIS_MAX_TOKENS = 800;
+export declare const DEFAULT_DOCUMENTATION_MAX_TOKENS = 12000;
+export declare const PROVIDER_CONFIG: {
+    evaluation: {
+        maxTokens: number;
+        model: string;
+        temperature: number;
+    };
+    analysis: {
+        maxTokens: number;
+        temperature: number;
+    };
+    documentation: {
+        maxTokens: number;
+        temperature: number;
+    };
+};
+export declare const CLI_LIMITS: {
+    maxTokens: {
+        min: number;
+        max: number;
+        default: number;
+    };
+    temperature: {
+        min: number;
+        max: number;
+        default: number;
+    };
+};
+export declare const ENV_DEFAULTS: {
+    maxTokens: number;
+    temperature: number;
+};