@blackbox_ai/blackbox-cli 0.0.7 → 0.8.1

package/dist/src/services/ReleaseNotesCache.js

@@ -0,0 +1,186 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { getCliVersion } from '../utils/version.js';
+const CACHE_DURATION_MS = 24 * 60 * 60 * 1000; // 24 hours
+/**
+ * Release Notes Cache Service
+ * Caches release notes and automatically invalidates when:
+ * 1. CLI version changes (new release installed)
+ * 2. Cache is older than 24 hours
+ */
+export class ReleaseNotesCache {
+    static instance;
+    cache = null;
+    cacheFilePath = null;
+    initPromise = null;
+    constructor() {
+        // Start initialization but don't wait for it
+        this.initPromise = this.initializeCachePath();
+    }
+    static getInstance() {
+        if (!ReleaseNotesCache.instance) {
+            ReleaseNotesCache.instance = new ReleaseNotesCache();
+        }
+        return ReleaseNotesCache.instance;
+    }
+    async initializeCachePath() {
+        try {
+            const path = await import('node:path');
+            const os = await import('node:os');
+            const fs = await import('node:fs/promises');
+            const cacheDir = path.join(os.homedir(), '.blackboxcli', 'cache');
+            // Ensure cache directory exists
+            try {
+                await fs.mkdir(cacheDir, { recursive: true });
+            }
+            catch {
+                // Directory might already exist
+            }
+            this.cacheFilePath = path.join(cacheDir, 'release-notes.json');
+            console.log(`[ReleaseNotesCache] Cache file path: ${this.cacheFilePath}`);
+        }
+        catch (error) {
+            console.error('[ReleaseNotesCache] Failed to initialize cache path:', error);
+        }
+    }
+    /**
+     * Ensure cache path is initialized before use
+     */
+    async ensureInitialized() {
+        if (this.initPromise) {
+            await this.initPromise;
+            this.initPromise = null;
+        }
+    }
+    /**
+     * Get cached release notes if valid
+     */
+    async get() {
+        // Ensure cache path is initialized
+        await this.ensureInitialized();
+        try {
+            // Try memory cache first
+            if (this.cache && await this.isCacheValid(this.cache)) {
+                console.log('[ReleaseNotesCache] Using memory cache');
+                return {
+                    data: this.cache.data,
+                    changelogData: this.cache.changelogData,
+                };
+            }
+            // Try disk cache
+            if (this.cacheFilePath) {
+                const fs = await import('node:fs/promises');
+                try {
+                    const content = await fs.readFile(this.cacheFilePath, 'utf-8');
+                    const cached = JSON.parse(content);
+                    // Convert plain object back to Map
+                    cached.changelogData = new Map(Object.entries(cached.changelogData || {}));
+                    if (await this.isCacheValid(cached)) {
+                        console.log('[ReleaseNotesCache] Using disk cache');
+                        this.cache = cached;
+                        return {
+                            data: cached.data,
+                            changelogData: cached.changelogData,
+                        };
+                    }
+                    else {
+                        console.log('[ReleaseNotesCache] Cache invalid, will fetch fresh data');
+                    }
+                }
+                catch (_error) {
+                    // Cache file doesn't exist or is corrupted
+                    console.log('[ReleaseNotesCache] No valid cache found');
+                }
+            }
+            return null;
+        }
+        catch (err) {
+            console.error('[ReleaseNotesCache] Error reading cache:', err);
+            return null;
+        }
+    }
+    /**
+     * Save release notes to cache
+     */
+    async set(data, changelogData) {
+        // Ensure cache path is initialized
+        await this.ensureInitialized();
+        try {
+            const cliVersion = await getCliVersion();
+            const cacheData = {
+                version: data[0]?.version || 'unknown',
+                data,
+                changelogData,
+                cachedAt: Date.now(),
+                cliVersion,
+            };
+            // Save to memory
+            this.cache = cacheData;
+            // Save to disk
+            if (this.cacheFilePath) {
+                const fs = await import('node:fs/promises');
+                // Convert Map to plain object for JSON serialization
+                const serializable = {
+                    ...cacheData,
+                    changelogData: Object.fromEntries(cacheData.changelogData),
+                };
+                await fs.writeFile(this.cacheFilePath, JSON.stringify(serializable, null, 2), 'utf-8');
+                console.log('[ReleaseNotesCache] Cache saved successfully');
+            }
+        }
+        catch (err) {
+            console.error('[ReleaseNotesCache] Error saving cache:', err);
+        }
+    }
+    /**
+     * Check if cache is still valid
+     */
+    async isCacheValid(cached) {
+        try {
+            // Check if cache is too old
+            const age = Date.now() - cached.cachedAt;
+            if (age > CACHE_DURATION_MS) {
+                console.log('[ReleaseNotesCache] Cache expired (age: ${Math.round(age / 1000 / 60)} minutes)');
+                return false;
+            }
+            // Check if CLI version has changed (new release installed)
+            const currentVersion = await getCliVersion();
+            if (cached.cliVersion !== currentVersion) {
+                console.log(`[ReleaseNotesCache] CLI version changed: ${cached.cliVersion} -> ${currentVersion}`);
+                return false;
+            }
+            return true;
+        }
+        catch (err) {
+            console.error('[ReleaseNotesCache] Error validating cache:', err);
+            return false;
+        }
+    }
+    /**
+     * Clear the cache
+     */
+    async clear() {
+        // Ensure cache path is initialized
+        await this.ensureInitialized();
+        try {
+            this.cache = null;
+            if (this.cacheFilePath) {
+                const fs = await import('node:fs/promises');
+                try {
+                    await fs.unlink(this.cacheFilePath);
+                    console.log('[ReleaseNotesCache] Cache cleared');
+                }
+                catch (_error) {
+                    // File might not exist
+                }
+            }
+        }
+        catch (error) {
+            console.error('[ReleaseNotesCache] Error clearing cache:', error);
+        }
+    }
+}
+//# sourceMappingURL=ReleaseNotesCache.js.map

package/dist/src/services/ReleaseNotesCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReleaseNotesCache.js","sourceRoot":"","sources":["../../../src/services/ReleaseNotesCache.ts"],"names":[],"mappings":"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"}

package/dist/src/services/elevenLabsErrors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * ElevenLabs API error codes and types based on official documentation
+ * https://elevenlabs.io/docs/api-reference/error-messages
+ */
+/**
+ * Error codes returned by ElevenLabs API
+ */
+export declare enum ElevenLabsErrorCode {
+    MAX_CHARACTER_LIMIT_EXCEEDED = "max_character_limit_exceeded",
+    INVALID_API_KEY = "invalid_api_key",
+    QUOTA_EXCEEDED = "quota_exceeded",
+    VOICE_NOT_FOUND = "voice_not_found",
+    ONLY_FOR_CREATOR_PLUS = "only_for_creator+",
+    TOO_MANY_CONCURRENT_REQUESTS = "too_many_concurrent_requests",
+    SYSTEM_BUSY = "system_busy",
+    UNKNOWN = "unknown"
+}
+/**
+ * Error type categories for easier handling
+ */
+export declare enum ElevenLabsErrorType {
+    AUTHENTICATION = "authentication",
+    PERMISSION = "permission",
+    QUOTA = "quota",
+    RATE_LIMIT = "rate_limit",
+    VALIDATION = "validation",
+    NETWORK = "network",
+    UNKNOWN = "unknown"
+}
+/**
+ * Detailed error information with user-friendly messages and solutions
+ */
+export interface ElevenLabsErrorInfo {
+    code: ElevenLabsErrorCode;
+    type: ElevenLabsErrorType;
+    httpStatus: number;
+    message: string;
+    solution: string;
+    documentationUrl?: string;
+}
+/**
+ * Map of error codes to detailed error information
+ */
+export declare const ELEVENLABS_ERROR_MAP: Record<ElevenLabsErrorCode, ElevenLabsErrorInfo>;
+/**
+ * Parse ElevenLabs API error response and return detailed error information
+ */
+export declare function parseElevenLabsError(statusCode: number, responseBody: string): ElevenLabsErrorInfo;
+/**
+ * Format error information into a user-friendly message
+ */
+export declare function formatElevenLabsError(errorInfo: ElevenLabsErrorInfo): string;
+/**
+ * Check if an error is retryable (rate limit errors)
+ */
+export declare function isRetryableError(errorInfo: ElevenLabsErrorInfo): boolean;
+/**
+ * Get recommended retry delay in milliseconds for retryable errors
+ */
+export declare function getRetryDelay(errorInfo: ElevenLabsErrorInfo, attemptNumber: number): number;

package/dist/src/services/elevenLabsErrors.js

@@ -0,0 +1,233 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * ElevenLabs API error codes and types based on official documentation
+ * https://elevenlabs.io/docs/api-reference/error-messages
+ */
+/**
+ * Error codes returned by ElevenLabs API
+ */
+export var ElevenLabsErrorCode;
+(function (ElevenLabsErrorCode) {
+    // 400/401 errors
+    ElevenLabsErrorCode["MAX_CHARACTER_LIMIT_EXCEEDED"] = "max_character_limit_exceeded";
+    ElevenLabsErrorCode["INVALID_API_KEY"] = "invalid_api_key";
+    ElevenLabsErrorCode["QUOTA_EXCEEDED"] = "quota_exceeded";
+    ElevenLabsErrorCode["VOICE_NOT_FOUND"] = "voice_not_found";
+    // 403 errors
+    ElevenLabsErrorCode["ONLY_FOR_CREATOR_PLUS"] = "only_for_creator+";
+    // 429 errors
+    ElevenLabsErrorCode["TOO_MANY_CONCURRENT_REQUESTS"] = "too_many_concurrent_requests";
+    ElevenLabsErrorCode["SYSTEM_BUSY"] = "system_busy";
+    // Generic/Unknown
+    ElevenLabsErrorCode["UNKNOWN"] = "unknown";
+})(ElevenLabsErrorCode || (ElevenLabsErrorCode = {}));
+/**
+ * Error type categories for easier handling
+ */
+export var ElevenLabsErrorType;
+(function (ElevenLabsErrorType) {
+    ElevenLabsErrorType["AUTHENTICATION"] = "authentication";
+    ElevenLabsErrorType["PERMISSION"] = "permission";
+    ElevenLabsErrorType["QUOTA"] = "quota";
+    ElevenLabsErrorType["RATE_LIMIT"] = "rate_limit";
+    ElevenLabsErrorType["VALIDATION"] = "validation";
+    ElevenLabsErrorType["NETWORK"] = "network";
+    ElevenLabsErrorType["UNKNOWN"] = "unknown";
+})(ElevenLabsErrorType || (ElevenLabsErrorType = {}));
+/**
+ * Map of error codes to detailed error information
+ */
+export const ELEVENLABS_ERROR_MAP = {
+    [ElevenLabsErrorCode.MAX_CHARACTER_LIMIT_EXCEEDED]: {
+        code: ElevenLabsErrorCode.MAX_CHARACTER_LIMIT_EXCEEDED,
+        type: ElevenLabsErrorType.VALIDATION,
+        httpStatus: 400,
+        message: 'You are sending too many characters in a single request.',
+        solution: 'Split the request into smaller chunks. Check the character limits for your model at https://elevenlabs.io/docs/api-reference/text-to-speech#character-limits',
+        documentationUrl: 'https://elevenlabs.io/docs/api-reference/text-to-speech#character-limits',
+    },
+    [ElevenLabsErrorCode.INVALID_API_KEY]: {
+        code: ElevenLabsErrorCode.INVALID_API_KEY,
+        type: ElevenLabsErrorType.AUTHENTICATION,
+        httpStatus: 401,
+        message: 'Your API key is invalid or has not been set correctly.',
+        solution: 'Ensure the request is correctly authenticated. Check your API key at https://elevenlabs.io/app/settings/api-keys and run: blackbox voice configure',
+        documentationUrl: 'https://elevenlabs.io/docs/api-reference/authentication',
+    },
+    [ElevenLabsErrorCode.QUOTA_EXCEEDED]: {
+        code: ElevenLabsErrorCode.QUOTA_EXCEEDED,
+        type: ElevenLabsErrorType.QUOTA,
+        httpStatus: 401,
+        message: 'You have insufficient quota to complete the request.',
+        solution: 'On the Creator plan and above, you can enable usage-based billing from your Subscription page at https://elevenlabs.io/app/subscription',
+        documentationUrl: 'https://elevenlabs.io/app/subscription',
+    },
+    [ElevenLabsErrorCode.VOICE_NOT_FOUND]: {
+        code: ElevenLabsErrorCode.VOICE_NOT_FOUND,
+        type: ElevenLabsErrorType.VALIDATION,
+        httpStatus: 400,
+        message: 'The voice_id you entered is incorrect.',
+        solution: 'Check that you are using the correct voice_id for the voice you want to use. You can verify this in My Voices at https://elevenlabs.io/app/voice-library',
+        documentationUrl: 'https://elevenlabs.io/app/voice-library',
+    },
+    [ElevenLabsErrorCode.ONLY_FOR_CREATOR_PLUS]: {
+        code: ElevenLabsErrorCode.ONLY_FOR_CREATOR_PLUS,
+        type: ElevenLabsErrorType.PERMISSION,
+        httpStatus: 403,
+        message: 'You are trying to use professional voices on a free or basic subscription.',
+        solution: 'Upgrade to Creator tier or higher to access professional voices at https://elevenlabs.io/pricing',
+        documentationUrl: 'https://elevenlabs.io/pricing',
+    },
+    [ElevenLabsErrorCode.TOO_MANY_CONCURRENT_REQUESTS]: {
+        code: ElevenLabsErrorCode.TOO_MANY_CONCURRENT_REQUESTS,
+        type: ElevenLabsErrorType.RATE_LIMIT,
+        httpStatus: 429,
+        message: 'You have exceeded the concurrency limit for your subscription.',
+        solution: 'Wait for existing requests to complete before making new ones. Consider upgrading your subscription for higher concurrency limits at https://elevenlabs.io/docs/api-reference/concurrency-and-priority',
+        documentationUrl: 'https://elevenlabs.io/docs/api-reference/concurrency-and-priority',
+    },
+    [ElevenLabsErrorCode.SYSTEM_BUSY]: {
+        code: ElevenLabsErrorCode.SYSTEM_BUSY,
+        type: ElevenLabsErrorType.RATE_LIMIT,
+        httpStatus: 429,
+        message: 'Our services are experiencing high levels of traffic and your request could not be processed.',
+        solution: 'Retry the request later with exponential backoff. Consider upgrading your subscription to get higher priority at https://elevenlabs.io/docs/api-reference/concurrency-and-priority',
+        documentationUrl: 'https://elevenlabs.io/docs/api-reference/concurrency-and-priority',
+    },
+    [ElevenLabsErrorCode.UNKNOWN]: {
+        code: ElevenLabsErrorCode.UNKNOWN,
+        type: ElevenLabsErrorType.UNKNOWN,
+        httpStatus: 500,
+        message: 'An unknown error occurred.',
+        solution: 'Please try again. If the problem persists, contact ElevenLabs support at https://help.elevenlabs.io/hc/en-us/requests/new',
+        documentationUrl: 'https://help.elevenlabs.io/hc/en-us/requests/new',
+    },
+};
+/**
+ * Parse ElevenLabs API error response and return detailed error information
+ */
+export function parseElevenLabsError(statusCode, responseBody) {
+    try {
+        // Try to parse as JSON
+        const json = JSON.parse(responseBody);
+        // Extract error code from various possible locations
+        const errorCode = json.detail?.code ||
+            json.code ||
+            json.detail?.status ||
+            json.status;
+        // Check if we have a known error code
+        if (errorCode && errorCode in ELEVENLABS_ERROR_MAP) {
+            return ELEVENLABS_ERROR_MAP[errorCode];
+        }
+        // Fall back to HTTP status code mapping
+        return mapHttpStatusToError(statusCode, responseBody);
+    }
+    catch {
+        // If JSON parsing fails, map by HTTP status code
+        return mapHttpStatusToError(statusCode, responseBody);
+    }
+}
+/**
+ * Map HTTP status code to error information when specific error code is not available
+ */
+function mapHttpStatusToError(statusCode, responseBody) {
+    switch (statusCode) {
+        case 400:
+            // Could be various validation errors
+            if (responseBody.toLowerCase().includes('character')) {
+                return ELEVENLABS_ERROR_MAP[ElevenLabsErrorCode.MAX_CHARACTER_LIMIT_EXCEEDED];
+            }
+            if (responseBody.toLowerCase().includes('voice')) {
+                return ELEVENLABS_ERROR_MAP[ElevenLabsErrorCode.VOICE_NOT_FOUND];
+            }
+            return {
+                code: ElevenLabsErrorCode.UNKNOWN,
+                type: ElevenLabsErrorType.VALIDATION,
+                httpStatus: 400,
+                message: `Bad request: ${responseBody}`,
+                solution: 'Check your request parameters and try again.',
+            };
+        case 401:
+            // Authentication errors
+            if (responseBody.toLowerCase().includes('quota')) {
+                return ELEVENLABS_ERROR_MAP[ElevenLabsErrorCode.QUOTA_EXCEEDED];
+            }
+            return ELEVENLABS_ERROR_MAP[ElevenLabsErrorCode.INVALID_API_KEY];
+        case 403:
+            // Permission errors
+            if (responseBody.toLowerCase().includes('creator') ||
+                responseBody.toLowerCase().includes('professional')) {
+                return ELEVENLABS_ERROR_MAP[ElevenLabsErrorCode.ONLY_FOR_CREATOR_PLUS];
+            }
+            return {
+                code: ElevenLabsErrorCode.UNKNOWN,
+                type: ElevenLabsErrorType.PERMISSION,
+                httpStatus: 403,
+                message: `Permission denied: ${responseBody}`,
+                solution: 'Ensure your API key has the required permissions at https://elevenlabs.io/app/settings/api-keys',
+                documentationUrl: 'https://elevenlabs.io/app/settings/api-keys',
+            };
+        case 429:
+            // Rate limit errors
+            if (responseBody.toLowerCase().includes('concurrent')) {
+                return ELEVENLABS_ERROR_MAP[ElevenLabsErrorCode.TOO_MANY_CONCURRENT_REQUESTS];
+            }
+            if (responseBody.toLowerCase().includes('busy') ||
+                responseBody.toLowerCase().includes('traffic')) {
+                return ELEVENLABS_ERROR_MAP[ElevenLabsErrorCode.SYSTEM_BUSY];
+            }
+            return {
+                code: ElevenLabsErrorCode.UNKNOWN,
+                type: ElevenLabsErrorType.RATE_LIMIT,
+                httpStatus: 429,
+                message: `Rate limit exceeded: ${responseBody}`,
+                solution: 'Wait a moment and try again. Consider implementing exponential backoff for retries.',
+            };
+        default:
+            return {
+                code: ElevenLabsErrorCode.UNKNOWN,
+                type: ElevenLabsErrorType.UNKNOWN,
+                httpStatus: statusCode,
+                message: responseBody || 'An unknown error occurred',
+                solution: 'Please try again. If the problem persists, contact ElevenLabs support at https://help.elevenlabs.io/hc/en-us/requests/new',
+                documentationUrl: 'https://help.elevenlabs.io/hc/en-us/requests/new',
+            };
+    }
+}
+/**
+ * Format error information into a user-friendly message
+ */
+export function formatElevenLabsError(errorInfo) {
+    let message = `${errorInfo.message}\n\n`;
+    message += `Solution: ${errorInfo.solution}`;
+    if (errorInfo.documentationUrl) {
+        message += `\n\nFor more information, visit: ${errorInfo.documentationUrl}`;
+    }
+    return message;
+}
+/**
+ * Check if an error is retryable (rate limit errors)
+ */
+export function isRetryableError(errorInfo) {
+    return errorInfo.type === ElevenLabsErrorType.RATE_LIMIT;
+}
+/**
+ * Get recommended retry delay in milliseconds for retryable errors
+ */
+export function getRetryDelay(errorInfo, attemptNumber) {
+    if (!isRetryableError(errorInfo)) {
+        return 0;
+    }
+    // Exponential backoff: 1s, 2s, 4s, 8s, 16s
+    const baseDelay = 1000;
+    const maxDelay = 16000;
+    const delay = Math.min(baseDelay * Math.pow(2, attemptNumber - 1), maxDelay);
+    // Add jitter to prevent thundering herd
+    const jitter = Math.random() * 0.3 * delay;
+    return Math.floor(delay + jitter);
+}
+//# sourceMappingURL=elevenLabsErrors.js.map

package/dist/src/services/elevenLabsErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"elevenLabsErrors.js","sourceRoot":"","sources":["../../../src/services/elevenLabsErrors.ts"],"names":[],"mappings":"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"}

package/dist/src/services/elevenLabsService.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type ElevenLabsErrorInfo } from './elevenLabsErrors.js';
+export interface ElevenLabsConfig {
+    apiKey: string;
+    agentId?: string;
+    model?: string;
+    language?: string;
+}
+export interface TranscriptionResult {
+    text: string;
+    language?: string;
+    duration?: number;
+}
+export interface ApiKeyValidationResult {
+    valid: boolean;
+    error?: string;
+    errorType?: 'missing' | 'invalid' | 'permission' | 'network' | 'unknown';
+    errorInfo?: ElevenLabsErrorInfo;
+}
+export interface ElevenLabsError {
+    detail?: {
+        status?: string;
+        message?: string;
+    };
+    message?: string;
+    status?: string;
+}
+/**
+ * Service for interacting with ElevenLabs Speech-to-Text API
+ */
+export declare class ElevenLabsService {
+    private readonly apiKey;
+    private readonly model;
+    private readonly language;
+    private readonly baseUrl;
+    constructor(config: ElevenLabsConfig);
+    /**
+     * Transcribe audio file to text using ElevenLabs API
+     * @param audioFilePath Path to the audio file
+     * @returns Transcription result
+     */
+    transcribe(audioFilePath: string): Promise<TranscriptionResult>;
+    /**
+     * Validate API key by making a test request
+     * @returns true if API key is valid
+     */
+    validateApiKey(): Promise<boolean>;
+    /**
+     * Validate API key with detailed error information
+     * @returns Validation result with error details
+     */
+    validateApiKeyDetailed(): Promise<ApiKeyValidationResult>;
+    /**
+     * Get available models for speech-to-text
+     * @returns List of available models
+     */
+    getAvailableModels(): Promise<string[]>;
+}