mcp-prompt-optimizer 1.3.2 → 1.3.3

package/lib/api-key-manager.js

@@ -1,21 +1,40 @@
 /**
  * Cloud API Key Manager for MCP Prompt Optimizer
- * Mirrors the patterns from the local license-manager.js for consistency
+ * Production-grade with enhanced network resilience and development mode
+ * ALIGNED with backend API requirements
  */
 
 const fs = require('fs').promises;
 const path = require('path');
 const https = require('https');
+const http = require('http');
 const os = require('os');
 
+const packageJson = require('../package.json');
+
 class CloudApiKeyManager {
     constructor(apiKey, options = {}) {
         this.apiKey = apiKey;
-        this.backendUrl = options.backendUrl || 'https://p01--project-optimizer--fvrdk8m9k9j.code.run';
+        this.backendUrl = options.backendUrl || process.env.OPTIMIZER_BACKEND_URL || 'https://p01--project-optimizer--fvrdk8m9k9j.code.run';
         this.cacheFile = path.join(os.homedir(), '.mcp-cloud-api-cache.json');
+        this.healthFile = path.join(os.homedir(), '.mcp-cloud-health.json');
         this.cacheExpiry = options.cacheExpiry || 24 * 60 * 60 * 1000; // 24 hours
+        this.fallbackCacheExpiry = options.fallbackCacheExpiry || 7 * 24 * 60 * 60 * 1000; // 7 days
         this.logPrefix = '[CloudApiKeyManager]';
         this.offlineMode = options.offlineMode || false;
+        this.developmentMode = options.developmentMode || process.env.NODE_ENV === 'development' || process.env.OPTIMIZER_DEV_MODE === 'true';
+        this.maxRetries = options.maxRetries || 5; // Increased for production
+        this.baseRetryDelay = options.baseRetryDelay || 1000;
+        this.maxRetryDelay = options.maxRetryDelay || 30000;
+        this.requestTimeout = options.requestTimeout || 15000;
+        
+        // Network health tracking
+        this.networkHealth = {
+            consecutiveFailures: 0,
+            lastSuccessful: null,
+            avgResponseTime: null,
+            lastErrorType: null
+        };
     }
 
     log(message, level = 'info') {
@@ -33,50 +52,243 @@ class CloudApiKeyManager {
         }
     }
 
+    // Production-grade exponential backoff with jitter
+    calculateRetryDelay(attempt) {
+        const exponentialDelay = Math.min(
+            this.baseRetryDelay * Math.pow(2, attempt - 1),
+            this.maxRetryDelay
+        );
+        
+        // Add jitter to prevent thundering herd
+        const jitter = Math.random() * 0.3 * exponentialDelay;
+        return Math.floor(exponentialDelay + jitter);
+    }
+
+    // Enhanced API key format validation
+    validateApiKeyFormat(apiKey) {
+        if (!apiKey || typeof apiKey !== 'string') {
+            return { valid: false, error: 'API key must be a string' };
+        }
+
+        // Support development keys
+        const validPrefixes = ['sk-opt-', 'sk-team-', 'sk-local-', 'sk-dev-'];
+        const hasValidPrefix = validPrefixes.some(prefix => apiKey.startsWith(prefix));
+        
+        if (!hasValidPrefix) {
+            return { 
+                valid: false, 
+                error: 'Invalid API key format. Must start with "sk-opt-" (individual), "sk-team-" (team), "sk-local-" (development), or "sk-dev-" (testing)' 
+            };
+        }
+
+        // Check minimum length for security
+        if (apiKey.length < 20) {
+            return { 
+                valid: false, 
+                error: 'API key too short' 
+            };
+        }
+
+        // Determine type
+        let keyType = 'unknown';
+        if (apiKey.startsWith('sk-opt-')) {
+            keyType = 'individual';
+        } else if (apiKey.startsWith('sk-team-')) {
+            keyType = 'team';
+        } else if (apiKey.startsWith('sk-local-')) {
+            keyType = 'development';
+        } else if (apiKey.startsWith('sk-dev-')) {
+            keyType = 'testing';
+        }
+
+        return { 
+            valid: true, 
+            keyType: keyType
+        };
+    }
+
+    // Development mode mock responses
+    generateMockValidation(keyType) {
+        const mockResponses = {
+            individual: {
+                valid: true,
+                tier: 'explorer',
+                api_key_type: 'individual',
+                quota: {
+                    limit: 5000,
+                    used: Math.floor(Math.random() * 1000),
+                    unlimited: false
+                },
+                features: {
+                    ai_context_detection: true,
+                    template_management: true,
+                    optimization_insights: true
+                }
+            },
+            team: {
+                valid: true,
+                tier: 'creator',
+                api_key_type: 'team',
+                quota: {
+                    limit: 18000,
+                    used: Math.floor(Math.random() * 3000),
+                    unlimited: false
+                },
+                features: {
+                    ai_context_detection: true,
+                    template_management: true,
+                    team_collaboration: true,
+                    optimization_insights: true
+                }
+            },
+            development: {
+                valid: true,
+                tier: 'development',
+                api_key_type: 'development',
+                quota: {
+                    unlimited: true
+                },
+                features: {
+                    ai_context_detection: true,
+                    template_management: true,
+                    optimization_insights: true,
+                    development_mode: true
+                }
+            },
+            testing: {
+                valid: true,
+                tier: 'testing',
+                api_key_type: 'testing',
+                quota: {
+                    limit: 1000,
+                    used: Math.floor(Math.random() * 100),
+                    unlimited: false
+                },
+                features: {
+                    ai_context_detection: true,
+                    template_management: true,
+                    optimization_insights: true,
+                    testing_mode: true
+                }
+            }
+        };
+
+        const response = mockResponses[keyType] || mockResponses.development;
+        response.mock_mode = true;
+        response.backend_url = 'mock://development-mode';
+        
+        return response;
+    }
+
+    // Enhanced API key validation with production resilience
     async validateApiKey() {
-        this.log('Validating API key...');
+        this.log('Starting comprehensive API key validation...');
 
         if (!this.apiKey) {
             throw new Error('API key is required. Set OPTIMIZER_API_KEY environment variable or provide key directly.');
         }
 
-        if (!this.apiKey.startsWith('sk-opt-') && !this.apiKey.startsWith('sk-team-')) {
-            throw new Error('Invalid API key format. Must be a cloud API key (sk-opt-* or sk-team-*)');
+        // Step 1: Format validation
+        const formatCheck = this.validateApiKeyFormat(this.apiKey);
+        if (!formatCheck.valid) {
+            throw new Error(formatCheck.error);
+        }
+
+        this.log(`API key format valid: ${formatCheck.keyType}`);
+
+        // Step 2: Development mode handling
+        if (this.developmentMode || formatCheck.keyType === 'development' || formatCheck.keyType === 'testing') {
+            this.log('Development/testing mode detected, using mock validation', 'warn');
+            const mockValidation = this.generateMockValidation(formatCheck.keyType);
+            await this.cacheValidation(mockValidation);
+            return mockValidation;
         }
 
         try {
-            // Try to validate with backend first
-            const validation = await this.validateWithBackend();
+            // Step 3: Backend validation with enhanced retry logic
+            const validation = await this.validateWithBackendRetry();
             
-            // Cache valid results
-            if (validation.valid) {
+            // Step 4: Validate response structure
+            if (validation && validation.valid) {
                 await this.cacheValidation(validation);
+                await this.updateNetworkHealth(true);
                 this.log(`API key validated successfully: ${validation.tier}`, 'success');
                 return validation;
             } else {
-                throw new Error(validation.error || 'API key validation failed');
+                throw new Error(validation?.detail || validation?.error || 'API key validation failed');
             }
 
         } catch (error) {
             this.log(`Backend validation failed: ${error.message}`, 'warn');
+            await this.updateNetworkHealth(false, error.message);
             
-            // Try cached validation as fallback
+            // Enhanced fallback strategy
             const cachedValidation = await this.getCachedValidation();
+            
             if (cachedValidation && !this.isCacheExpired(cachedValidation)) {
                 this.log('Using cached API key validation', 'warn');
                 return cachedValidation.data;
             }
+            
+            // Extended fallback for network issues
+            if (cachedValidation && !this.isFallbackCacheExpired(cachedValidation)) {
+                this.log('Using extended fallback cache due to network issues', 'warn');
+                const fallbackData = cachedValidation.data;
+                fallbackData.fallback_mode = true;
+                fallbackData.network_issue = error.message;
+                return fallbackData;
+            }
 
             // If we're in explicit offline mode and have any cache, use it
             if (this.offlineMode && cachedValidation) {
                 this.log('Offline mode: using cached validation despite expiry', 'warn');
-                return cachedValidation.data;
+                const offlineData = cachedValidation.data;
+                offlineData.offline_mode = true;
+                return offlineData;
             }
 
             throw new Error(`API key validation failed: ${error.message}`);
         }
     }
 
+    // Production-grade retry logic with exponential backoff
+    async validateWithBackendRetry() {
+        let lastError;
+        
+        for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+            try {
+                this.log(`Validation attempt ${attempt}/${this.maxRetries}...`);
+                const startTime = Date.now();
+                
+                const result = await this.validateWithBackend();
+                
+                // Track response time for health monitoring
+                const responseTime = Date.now() - startTime;
+                if (this.networkHealth.avgResponseTime === null) {
+                    this.networkHealth.avgResponseTime = responseTime;
+                } else {
+                    this.networkHealth.avgResponseTime = (this.networkHealth.avgResponseTime + responseTime) / 2;
+                }
+                
+                return result;
+            } catch (error) {
+                lastError = error;
+                this.log(`Attempt ${attempt} failed: ${error.message}`, 'warn');
+                
+                if (attempt < this.maxRetries) {
+                    const delay = this.calculateRetryDelay(attempt);
+                    this.log(`Retrying in ${delay}ms...`);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                } else {
+                    this.log('All retry attempts exhausted', 'error');
+                }
+            }
+        }
+        
+        throw lastError;
+    }
+
+    // Enhanced backend validation with better error handling
     async validateWithBackend() {
         return new Promise((resolve, reject) => {
             const url = `${this.backendUrl}/api/v1/mcp/validate-key`;
@@ -84,17 +296,20 @@ class CloudApiKeyManager {
             const options = {
                 method: 'POST',
                 headers: {
-                    // Use lowercase header to match backend expectations
                     'x-api-key': this.apiKey,
                     'Content-Type': 'application/json',
-                    'User-Agent': 'mcp-prompt-optimizer/1.2.0'
+                    'User-Agent': `mcp-prompt-optimizer/${packageJson.version}`,
+                    'Accept': 'application/json',
+                    'Connection': 'close' // Ensure connection cleanup
                 },
-                timeout: 10000 // 10 second timeout
+                timeout: this.requestTimeout
             };
 
-            this.log(`Making request with header: x-api-key = ${this.apiKey.substring(0, 16)}...`);
+            this.log(`Making request to: ${url}`);
+            this.log(`Using API key: ${this.apiKey.substring(0, 16)}...`);
 
-            const req = https.request(url, options, (res) => {
+            const client = this.backendUrl.startsWith('https://') ? https : http;
+            const req = client.request(url, options, (res) => {
                 let data = '';
                 
                 res.on('data', (chunk) => {
@@ -103,42 +318,87 @@ class CloudApiKeyManager {
                 
                 res.on('end', () => {
                     this.log(`Response status: ${res.statusCode}`);
-                    this.log(`Response body: ${data.substring(0, 200)}...`);
                     
                     try {
                         if (res.statusCode === 200) {
                             const validation = JSON.parse(data);
+                            this.log(`Validation successful: ${JSON.stringify(validation, null, 2)}`);
                             resolve(validation);
+                        } else if (res.statusCode === 401) {
+                            reject(new Error('Invalid API key or unauthorized access'));
+                        } else if (res.statusCode === 403) {
+                            reject(new Error('API key expired or quota exceeded'));
+                        } else if (res.statusCode === 429) {
+                            reject(new Error('Rate limit exceeded. Please try again later.'));
+                        } else if (res.statusCode === 500) {
+                            reject(new Error('Backend server error. Please try again later.'));
+                        } else if (res.statusCode === 503) {
+                            reject(new Error('Backend service temporarily unavailable. Please try again later.'));
                         } else {
                             let errorMessage;
                             try {
                                 const error = JSON.parse(data);
-                                errorMessage = error.detail || `HTTP ${res.statusCode}`;
+                                errorMessage = error.detail || error.message || `HTTP ${res.statusCode}`;
                             } catch {
                                 errorMessage = `HTTP ${res.statusCode}: ${data}`;
                             }
                             reject(new Error(errorMessage));
                         }
                     } catch (parseError) {
-                        reject(new Error(`Invalid response: ${parseError.message}`));
+                        this.log(`Parse error: ${parseError.message}`, 'error');
+                        this.log(`Raw response: ${data}`, 'error');
+                        reject(new Error(`Invalid response format: ${parseError.message}`));
                     }
                 });
             });
 
             req.on('error', (error) => {
-                reject(new Error(`Network error: ${error.message}`));
+                this.log(`Network error: ${error.message}`, 'error');
+                
+                // Enhanced error classification
+                if (error.code === 'ENOTFOUND') {
+                    reject(new Error(`DNS resolution failed: Cannot resolve ${this.backendUrl.replace(/^https?:\/\//, '')}`));
+                } else if (error.code === 'ECONNREFUSED') {
+                    reject(new Error(`Connection refused: Backend server may be down`));
+                } else if (error.code === 'ETIMEDOUT') {
+                    reject(new Error(`Connection timeout: Backend server is not responding`));
+                } else if (error.code === 'ECONNRESET') {
+                    reject(new Error(`Connection reset: Network instability detected`));
+                } else {
+                    reject(new Error(`Network error: ${error.message}`));
+                }
             });
 
             req.on('timeout', () => {
                 req.destroy();
-                reject(new Error('Request timeout'));
+                reject(new Error('Request timeout - backend may be unavailable'));
             });
 
-            req.setTimeout(10000);
+            req.setTimeout(this.requestTimeout);
             req.end();
         });
     }
 
+    // Network health tracking
+    async updateNetworkHealth(success, errorMessage = null) {
+        try {
+            if (success) {
+                this.networkHealth.consecutiveFailures = 0;
+                this.networkHealth.lastSuccessful = Date.now();
+                this.networkHealth.lastErrorType = null;
+            } else {
+                this.networkHealth.consecutiveFailures++;
+                this.networkHealth.lastErrorType = errorMessage;
+            }
+
+            // Save health metrics
+            await fs.writeFile(this.healthFile, JSON.stringify(this.networkHealth, null, 2));
+        } catch (error) {
+            this.log(`Failed to update network health: ${error.message}`, 'warn');
+        }
+    }
+
+    // Enhanced quota status checking
     async checkQuotaStatus(validation) {
         const quota = validation.quota || {};
         
@@ -152,9 +412,12 @@ class CloudApiKeyManager {
 
         if (quotaUsed >= quotaLimit) {
             const tier = validation.tier || 'explorer';
+            const upgradeMessage = tier === 'explorer' 
+                ? 'Upgrade to Creator ($25.99/mo) for 18,000 optimizations: https://promptoptimizer-blog.vercel.app/pricing'
+                : 'Quota will reset on your next billing cycle.';
+            
             throw new Error(
-                `Monthly quota exceeded (${quotaUsed}/${quotaLimit}). ` +
-                `${tier === 'explorer' ? 'Upgrade to Creator ($25.99/mo) for 18,000 optimizations: https://promptoptimizer-blog.vercel.app/pricing' : 'Quota will reset on your next billing cycle.'}`
+                `Monthly quota exceeded (${quotaUsed}/${quotaLimit}). ${upgradeMessage}`
             );
         }
 
@@ -163,10 +426,12 @@ class CloudApiKeyManager {
             unlimited: false,
             used: quotaUsed,
             limit: quotaLimit,
-            remaining: quotaRemaining
+            remaining: quotaRemaining,
+            usage_percentage: (quotaUsed / quotaLimit) * 100
         };
     }
 
+    // Enhanced quota status retrieval
     async getQuotaStatus() {
         try {
             const url = `${this.backendUrl}/api/v1/mcp/quota-status`;
@@ -175,13 +440,15 @@ class CloudApiKeyManager {
                 method: 'GET',
                 headers: {
                     'x-api-key': this.apiKey,
-                    'User-Agent': 'mcp-prompt-optimizer/1.2.0'
+                    'User-Agent': `mcp-prompt-optimizer/${packageJson.version}`,
+                    'Connection': 'close'
                 },
-                timeout: 10000
+                timeout: this.requestTimeout
             };
 
             return new Promise((resolve, reject) => {
-                const req = https.request(url, options, (res) => {
+                const client = this.backendUrl.startsWith('https://') ? https : http;
+                const req = client.request(url, options, (res) => {
                     let data = '';
                     
                     res.on('data', (chunk) => {
@@ -218,7 +485,7 @@ class CloudApiKeyManager {
                     reject(new Error('Request timeout'));
                 });
 
-                req.setTimeout(10000);
+                req.setTimeout(this.requestTimeout);
                 req.end();
             });
 
@@ -228,15 +495,20 @@ class CloudApiKeyManager {
         }
     }
 
+    // Enhanced caching with metadata
     async cacheValidation(validation) {
         try {
             const cacheData = {
                 timestamp: Date.now(),
-                data: validation
+                apiKeyPrefix: this.apiKey.substring(0, 20) + '...', // Safe prefix only
+                data: validation,
+                backendUrl: this.backendUrl,
+                packageVersion: packageJson.version,
+                networkHealth: { ...this.networkHealth }
             };
             
             await fs.writeFile(this.cacheFile, JSON.stringify(cacheData, null, 2));
-            this.log('API key validation cached');
+            this.log('API key validation cached successfully');
         } catch (error) {
             this.log(`Failed to cache validation: ${error.message}`, 'warn');
         }
@@ -245,47 +517,112 @@ class CloudApiKeyManager {
     async getCachedValidation() {
         try {
             const cacheContent = await fs.readFile(this.cacheFile, 'utf8');
-            return JSON.parse(cacheContent);
+            const cached = JSON.parse(cacheContent);
+            
+            // Validate cache structure
+            if (!cached.timestamp || !cached.data) {
+                this.log('Invalid cache structure, ignoring', 'warn');
+                return null;
+            }
+            
+            return cached;
         } catch (error) {
-            return null; // No cache file or invalid cache
+            if (error.code !== 'ENOENT') {
+                this.log(`Cache read error: ${error.message}`, 'warn');
+            }
+            return null;
         }
     }
 
     isCacheExpired(cachedData) {
-        return (Date.now() - cachedData.timestamp) > this.cacheExpiry;
+        if (!cachedData || !cachedData.timestamp) {
+            return true;
+        }
+        
+        const age = Date.now() - cachedData.timestamp;
+        const expired = age > this.cacheExpiry;
+        
+        if (expired) {
+            this.log(`Cache expired: ${Math.round(age / 1000 / 60)} minutes old`);
+        }
+        
+        return expired;
+    }
+
+    // Extended fallback cache for network issues
+    isFallbackCacheExpired(cachedData) {
+        if (!cachedData || !cachedData.timestamp) {
+            return true;
+        }
+        
+        const age = Date.now() - cachedData.timestamp;
+        const expired = age > this.fallbackCacheExpiry;
+        
+        if (expired) {
+            this.log(`Fallback cache expired: ${Math.round(age / 1000 / 60 / 60)} hours old`);
+        }
+        
+        return expired;
     }
 
     async clearCache() {
         try {
             await fs.unlink(this.cacheFile);
-            this.log('API key cache cleared');
+            this.log('API key cache cleared successfully');
         } catch (error) {
-            // File might not exist, that's fine
+            if (error.code !== 'ENOENT') {
+                this.log(`Cache clear error: ${error.message}`, 'warn');
+            }
+        }
+
+        try {
+            await fs.unlink(this.healthFile);
+            this.log('Network health cache cleared successfully');
+        } catch (error) {
+            if (error.code !== 'ENOENT') {
+                this.log(`Health cache clear error: ${error.message}`, 'warn');
+            }
         }
     }
 
+    // Enhanced validation and preparation
     async validateAndPrepare() {
-        this.log('Starting API key validation and preparation...');
+        this.log('Starting comprehensive API key validation and preparation...');
 
         try {
             // Step 1: Validate API key
             const validation = await this.validateApiKey();
             
-            // Step 2: Check quota
-            const quotaStatus = await this.checkQuotaStatus(validation);
+            // Step 2: Check quota (skip for development/mock modes)
+            let quotaStatus;
+            if (validation.mock_mode || validation.fallback_mode || validation.offline_mode) {
+                quotaStatus = validation.quota || { allowed: true, unlimited: true };
+            } else {
+                quotaStatus = await this.checkQuotaStatus(validation);
+            }
             
             // Step 3: Log success
+            const mode = validation.mock_mode ? '(mock)' : 
+                        validation.fallback_mode ? '(fallback)' : 
+                        validation.offline_mode ? '(offline)' : '';
+            
             if (quotaStatus.unlimited) {
-                this.log(`API key valid: ${validation.tier} (unlimited usage)`, 'success');
+                this.log(`API key valid: ${validation.tier} ${mode} (unlimited usage)`, 'success');
             } else {
-                this.log(`API key valid: ${validation.tier} (${quotaStatus.remaining}/${quotaStatus.limit} remaining this month)`, 'success');
+                this.log(`API key valid: ${validation.tier} ${mode} (${quotaStatus.remaining}/${quotaStatus.limit} remaining this month)`, 'success');
             }
 
             return {
                 validation,
                 quotaStatus,
                 tier: validation.tier,
-                features: validation.features || {}
+                features: validation.features || {},
+                mode: {
+                    development: this.developmentMode,
+                    mock: validation.mock_mode || false,
+                    fallback: validation.fallback_mode || false,
+                    offline: validation.offline_mode || false
+                }
             };
 
         } catch (error) {
@@ -294,7 +631,150 @@ class CloudApiKeyManager {
         }
     }
 
-    // Helper method to get API key info for display
+    // Enhanced testing with network health
+    async testIntegration() {
+        const results = {
+            formatValidation: { passed: false },
+            backendConnectivity: { passed: false },
+            cacheOperations: { passed: false },
+            fullValidation: { passed: false },
+            networkHealth: { ...this.networkHealth }
+        };
+
+        try {
+            // Test 1: Format validation
+            const formatCheck = this.validateApiKeyFormat(this.apiKey);
+            results.formatValidation = {
+                passed: formatCheck.valid,
+                keyType: formatCheck.keyType,
+                error: formatCheck.error
+            };
+
+            // Test 2: Backend connectivity (with timeout)
+            try {
+                const connectivityTimeout = 10000; // 10 seconds for testing
+                const originalTimeout = this.requestTimeout;
+                this.requestTimeout = connectivityTimeout;
+                
+                const backendResponse = await this.validateWithBackend();
+                results.backendConnectivity = {
+                    passed: true,
+                    responseStructure: Object.keys(backendResponse),
+                    avgResponseTime: this.networkHealth.avgResponseTime
+                };
+                
+                this.requestTimeout = originalTimeout;
+            } catch (error) {
+                results.backendConnectivity = {
+                    passed: false,
+                    error: error.message,
+                    consecutiveFailures: this.networkHealth.consecutiveFailures
+                };
+            }
+
+            // Test 3: Cache operations
+            try {
+                const testData = { test: true, timestamp: Date.now() };
+                await this.cacheValidation(testData);
+                const retrieved = await this.getCachedValidation();
+                
+                results.cacheOperations = {
+                    passed: retrieved && retrieved.data.test === true,
+                    cacheAge: retrieved ? Math.round((Date.now() - retrieved.timestamp) / 1000) : null
+                };
+                
+                await this.clearCache();
+            } catch (error) {
+                results.cacheOperations = {
+                    passed: false,
+                    error: error.message
+                };
+            }
+
+            // Test 4: Full validation flow
+            try {
+                const validation = await this.validateAndPrepare();
+                results.fullValidation = {
+                    passed: true,
+                    tier: validation.tier,
+                    mode: validation.mode
+                };
+            } catch (error) {
+                results.fullValidation = {
+                    passed: false,
+                    error: error.message
+                };
+            }
+
+        } catch (error) {
+            results.generalError = error.message;
+        }
+
+        return results;
+    }
+
+    // Enhanced diagnostic information
+    async getDiagnosticInfo() {
+        const info = {
+            apiKey: this.apiKey ? `${this.apiKey.substring(0, 20)}...` : 'not provided',
+            backendUrl: this.backendUrl,
+            cacheFile: this.cacheFile,
+            healthFile: this.healthFile,
+            cacheExpiry: this.cacheExpiry,
+            fallbackCacheExpiry: this.fallbackCacheExpiry,
+            offlineMode: this.offlineMode,
+            developmentMode: this.developmentMode,
+            maxRetries: this.maxRetries,
+            requestTimeout: this.requestTimeout,
+            nodeEnv: process.env.NODE_ENV,
+            packageVersion: packageJson.version,
+            timestamp: new Date().toISOString(),
+            networkHealth: { ...this.networkHealth }
+        };
+
+        // Check cache status
+        try {
+            const cached = await this.getCachedValidation();
+            info.cache = {
+                exists: !!cached,
+                expired: cached ? this.isCacheExpired(cached) : null,
+                fallbackExpired: cached ? this.isFallbackCacheExpired(cached) : null,
+                age: cached ? Math.round((Date.now() - cached.timestamp) / 1000 / 60) : null,
+                backendUrl: cached ? cached.backendUrl : null,
+                packageVersion: cached ? cached.packageVersion : null
+            };
+        } catch (error) {
+            info.cache = { error: error.message };
+        }
+
+        // Check API key format
+        info.keyFormat = this.validateApiKeyFormat(this.apiKey);
+
+        // Test backend connectivity
+        try {
+            const startTime = Date.now();
+            await this.validateWithBackend();
+            const responseTime = Date.now() - startTime;
+            
+            info.backendConnectivity = { 
+                status: 'success',
+                responseTime: responseTime
+            };
+        } catch (error) {
+            info.backendConnectivity = { 
+                status: 'failed', 
+                error: error.message,
+                timeout: error.message.includes('timeout'),
+                network: error.message.includes('Network') || error.message.includes('DNS'),
+                dns: error.message.includes('DNS') || error.message.includes('ENOTFOUND'),
+                connection: error.message.includes('ECONNREFUSED') || error.message.includes('ECONNRESET')
+            };
+        }
+
+        return info;
+    }
+
+    // Enhanced API key info with mode detection
     async getApiKeyInfo() {
         try {
             const validation = await this.validateApiKey();
@@ -305,7 +785,13 @@ class CloudApiKeyManager {
                 features: validation.features || {},
                 quota: quotaStatus,
                 isValid: true,
-                keyType: validation.api_key_type || (this.apiKey.startsWith('sk-team-') ? 'team' : 'individual')
+                keyType: validation.api_key_type || this.validateApiKeyFormat(this.apiKey).keyType,
+                mode: {
+                    mock: validation.mock_mode || false,
+                    fallback: validation.fallback_mode || false,
+                    offline: validation.offline_mode || false,
+                    development: this.developmentMode
+                }
             };
         } catch (error) {
             return {
@@ -314,7 +800,13 @@ class CloudApiKeyManager {
                 quota: { allowed: false },
                 isValid: false,
                 error: error.message,
-                keyType: 'unknown'
+                keyType: 'unknown',
+                mode: {
+                    mock: false,
+                    fallback: false,
+                    offline: false,
+                    development: this.developmentMode
+                }
             };
         }
     }