douyin-downloader 0.1.0

package/dist/src/utils/error.js

@@ -0,0 +1,334 @@
+"use strict";
+/**
+ * 通用錯誤處理系統
+ * 提供統一的錯誤類型和處理機制
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppError = exports.ErrorCode = void 0;
+exports.parseHttpStatusFromError = parseHttpStatusFromError;
+exports.parseNetworkError = parseNetworkError;
+/**
+ * 錯誤碼枚舉
+ * 用於標識不同類型的錯誤
+ */
+var ErrorCode;
+(function (ErrorCode) {
+    // 通用錯誤
+    ErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+    ErrorCode["INVALID_ARGUMENT"] = "INVALID_ARGUMENT";
+    // 網絡相關錯誤
+    ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    ErrorCode["TIMEOUT_ERROR"] = "TIMEOUT_ERROR";
+    ErrorCode["RATE_LIMIT_ERROR"] = "RATE_LIMIT_ERROR";
+    // 認證相關錯誤
+    ErrorCode["AUTHENTICATION_ERROR"] = "AUTHENTICATION_ERROR";
+    ErrorCode["COOKIE_INVALID"] = "COOKIE_INVALID";
+    ErrorCode["COOKIE_EXPIRED"] = "COOKIE_EXPIRED";
+    ErrorCode["CAPTCHA_REQUIRED"] = "CAPTCHA_REQUIRED";
+    // 解析相關錯誤
+    ErrorCode["PARSING_ERROR"] = "PARSING_ERROR";
+    ErrorCode["INVALID_URL"] = "INVALID_URL";
+    // 資源相關錯誤
+    ErrorCode["RESOURCE_ERROR"] = "RESOURCE_ERROR";
+    ErrorCode["VIDEO_NOT_FOUND"] = "VIDEO_NOT_FOUND";
+    ErrorCode["USER_NOT_FOUND"] = "USER_NOT_FOUND";
+    ErrorCode["CONTENT_RESTRICTED"] = "CONTENT_RESTRICTED";
+    // 下載相關錯誤
+    ErrorCode["DOWNLOAD_ERROR"] = "DOWNLOAD_ERROR";
+    ErrorCode["DOWNLOAD_INTERRUPTED"] = "DOWNLOAD_INTERRUPTED";
+    // 文件系統錯誤
+    ErrorCode["FILE_SYSTEM_ERROR"] = "FILE_SYSTEM_ERROR";
+    ErrorCode["PERMISSION_DENIED"] = "PERMISSION_DENIED";
+    // 瀏覽器相關錯誤
+    ErrorCode["BROWSER_ERROR"] = "BROWSER_ERROR";
+    ErrorCode["BROWSER_LAUNCH_FAILED"] = "BROWSER_LAUNCH_FAILED";
+    // API 相關錯誤
+    ErrorCode["API_ERROR"] = "API_ERROR";
+})(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+/**
+ * 應用程序錯誤類
+ * 統一的錯誤類，包含錯誤碼、原因和其他信息
+ */
+class AppError extends Error {
+    code;
+    cause;
+    details;
+    /**
+     * 創建應用程序錯誤
+     * @param message 錯誤消息
+     * @param code 錯誤碼，默認為 UNKNOWN_ERROR
+     * @param cause 原始錯誤，用於錯誤鏈
+     * @param details 錯誤詳情，可包含任何額外信息
+     */
+    constructor(message, code = ErrorCode.UNKNOWN_ERROR, cause, // Allow unknown cause
+    details) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.details = details;
+        this.name = 'AppError';
+        // 捕獲堆棧跟踪
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, AppError);
+        }
+        // 如果有原因錯誤，附加其堆棧
+        if (this.cause && this.cause instanceof Error && this.cause.stack) {
+            this.stack = `${this.stack}\nCaused by: ${this.cause.stack}`;
+        }
+    }
+    /**
+     * 獲取完整的錯誤消息，包括錯誤碼和詳情
+     */
+    get fullMessage() {
+        let msg = `[${this.code}] ${this.message}`;
+        if (this.cause) {
+            const causeMessage = this.cause instanceof Error ? this.cause.message : String(this.cause);
+            msg += `\nCaused by: ${causeMessage}`;
+        }
+        if (this.details) {
+            try {
+                msg += `\nDetails: ${JSON.stringify(this.details)}`;
+            }
+            catch (e) {
+                msg += `\nDetails: [無法序列化詳情]`;
+            }
+        }
+        return msg;
+    }
+    /**
+     * 判斷錯誤是否可重試
+     * @returns 是否可重試
+     */
+    isRetryable() {
+        const retryableCodes = [
+            ErrorCode.NETWORK_ERROR,
+            ErrorCode.TIMEOUT_ERROR,
+            ErrorCode.RATE_LIMIT_ERROR,
+            ErrorCode.DOWNLOAD_INTERRUPTED,
+            ErrorCode.BROWSER_ERROR,
+            ErrorCode.API_ERROR // Consider if all API errors are retryable
+        ];
+        return retryableCodes.includes(this.code);
+    }
+    /**
+     * 從通用錯誤創建 AppError
+     * @param error 通用錯誤
+     * @param code 錯誤碼，默認為 UNKNOWN_ERROR
+     * @param defaultMessage 默認錯誤消息，如果原錯誤沒有消息
+     * @returns AppError 實例
+     */
+    static from(error, code = ErrorCode.UNKNOWN_ERROR, defaultMessage = '未知錯誤') {
+        if (error instanceof AppError) {
+            return error;
+        }
+        const errorObject = error instanceof Error ? error : new Error(typeof error === 'string' ? error : defaultMessage);
+        return new AppError(errorObject.message, code, errorObject);
+    }
+    /**
+     * 創建網絡錯誤
+     * @param message 錯誤消息
+     * @param cause 原始錯誤
+     * @returns AppError 實例
+     */
+    static network(message, cause) {
+        return new AppError(message, ErrorCode.NETWORK_ERROR, cause);
+    }
+    /**
+     * 創建認證錯誤
+     * @param message 錯誤消息
+     * @param cause 原始錯誤
+     * @returns AppError 實例
+     */
+    static authentication(message, cause) {
+        return new AppError(message, ErrorCode.AUTHENTICATION_ERROR, cause);
+    }
+    /**
+     * 創建解析錯誤
+     * @param message 錯誤消息
+     * @param cause 原始錯誤
+     * @returns AppError 實例
+     */
+    static parsing(message, cause) {
+        return new AppError(message, ErrorCode.PARSING_ERROR, cause);
+    }
+    /**
+     * 創建視頻未找到錯誤
+     * @param message 錯誤消息
+     * @param videoId 視頻ID
+     * @returns AppError 實例
+     */
+    static videoNotFound(message, videoId) {
+        return new AppError(message, ErrorCode.VIDEO_NOT_FOUND, undefined, videoId ? { videoId } : undefined);
+    }
+    /**
+   * 創建用戶未找到錯誤
+   * @param message 錯誤消息
+   * @param userId 用戶ID
+   * @returns AppError 實例
+   */
+    static userNotFound(message, userId) {
+        return new AppError(message, ErrorCode.USER_NOT_FOUND, undefined, userId ? { userId } : undefined);
+    }
+    /**
+     * 創建下載錯誤
+     * @param message 錯誤消息
+     * @param cause 原始錯誤
+     * @param url 下載URL
+     * @returns AppError 實例
+     */
+    static download(message, cause, url) {
+        return new AppError(message, ErrorCode.DOWNLOAD_ERROR, cause, url ? { url } : undefined);
+    }
+    /**
+     * 創建文件系統錯誤
+     * @param message 錯誤消息
+     * @param cause 原始錯誤
+     * @param path 文件路徑
+     * @returns AppError 實例
+     */
+    static fileSystem(message, cause, path) {
+        return new AppError(message, ErrorCode.FILE_SYSTEM_ERROR, cause, path ? { path } : undefined);
+    }
+    /**
+   * 創建權限錯誤
+   * @param message 錯誤消息
+   * @param cause 原始錯誤
+   * @param path 文件路徑
+   * @returns AppError 實例
+   */
+    static permissionDenied(message, cause, path) {
+        return new AppError(message, ErrorCode.PERMISSION_DENIED, cause, path ? { path } : undefined);
+    }
+    /**
+     * 創建瀏覽器錯誤
+     * @param message 錯誤消息
+     * @param cause 原始錯誤
+     * @returns AppError 實例
+     */
+    static browser(message, cause) {
+        return new AppError(message, ErrorCode.BROWSER_ERROR, cause);
+    }
+    /**
+     * 創建API錯誤
+     * @param message 錯誤消息
+     * @param cause 原始錯誤
+     * @param statusCode HTTP狀態碼
+     * @returns AppError 實例
+     */
+    static api(message, cause, statusCode) {
+        return new AppError(message, ErrorCode.API_ERROR, cause, statusCode ? { statusCode } : undefined);
+    }
+    /**
+     * 處理平台API特定錯誤 (需要平台特定實現來覆蓋或擴展)
+     * @param apiResponse API響應
+     * @param platform 平台標識 ('douyin', 'tiktok', etc.)
+     * @returns AppError 實例
+     */
+    static fromApiResponse(apiResponse, platform = 'unknown') {
+        // 這裡提供一個基礎實現，平台特定代碼應提供更詳細的解析
+        console.warn(`[AppError] Platform-specific API error parsing not implemented for platform: ${platform}. Using generic parsing.`);
+        // 嘗試通用解析
+        if (apiResponse && typeof apiResponse.statusCode === 'number') {
+            const { statusCode, statusMsg } = apiResponse;
+            const message = statusMsg || `${platform} API 錯誤`;
+            // 通用狀態碼處理
+            if (statusCode === 401 || statusCode === 403) {
+                return new AppError(message, ErrorCode.AUTHENTICATION_ERROR, undefined, { statusCode });
+            }
+            if (statusCode === 404) {
+                return new AppError(message, ErrorCode.RESOURCE_ERROR, undefined, { statusCode });
+            }
+            if (statusCode === 429) {
+                return new AppError(message, ErrorCode.RATE_LIMIT_ERROR, undefined, { statusCode });
+            }
+            if (statusCode >= 500) {
+                return new AppError(message, ErrorCode.API_ERROR, undefined, { statusCode });
+            }
+            // 其他狀態碼視為通用 API 錯誤
+            return new AppError(message, ErrorCode.API_ERROR, undefined, { statusCode, statusMsg });
+        }
+        // 如果沒有明確的狀態碼，返回通用API錯誤
+        return new AppError(typeof apiResponse === 'string'
+            ? apiResponse
+            : `${platform} API 響應解析失敗`, ErrorCode.API_ERROR);
+    }
+}
+exports.AppError = AppError;
+/**
+ * 解析錯誤消息中的HTTP狀態碼
+ * @param error 錯誤對象
+ * @returns 狀態碼或undefined
+ */
+function parseHttpStatusFromError(error) {
+    // Check AppError details first
+    if (error instanceof AppError && error.details?.statusCode) {
+        return error.details.statusCode;
+    }
+    const message = error.message;
+    // 嘗試從消息中提取HTTP狀態碼
+    const statusMatch = message.match(/(\b[45]\d\d\b)/);
+    if (statusMatch) {
+        return parseInt(statusMatch[1], 10);
+    }
+    // 檢查錯誤對象是否包含狀態碼
+    if ('statusCode' in error && typeof error.statusCode === 'number') {
+        return error.statusCode;
+    }
+    // 檢查錯誤對象是否包含響應對象
+    if ('response' in error && error.response) {
+        const response = error.response;
+        if (typeof response.status === 'number') {
+            return response.status;
+        }
+        if (typeof response.statusCode === 'number') {
+            return response.statusCode;
+        }
+    }
+    // Check cause if it exists
+    if (error instanceof AppError && error.cause instanceof Error) {
+        return parseHttpStatusFromError(error.cause);
+    }
+    return undefined;
+}
+/**
+ * 解析常見的網絡錯誤
+ * @param error 錯誤對象
+ * @returns 標準化的AppError
+ */
+function parseNetworkError(error) {
+    // If it's already an AppError, return it, unless it's UNKNOWN
+    if (error instanceof AppError && error.code !== ErrorCode.UNKNOWN_ERROR) {
+        return error;
+    }
+    const originalError = error instanceof AppError ? error.cause || error : error;
+    const message = originalError instanceof Error ? originalError.message.toLowerCase() : String(originalError).toLowerCase();
+    const statusCode = parseHttpStatusFromError(error); // Parse from original error or AppError wrapper
+    // 處理常見的狀態碼
+    if (statusCode) {
+        if (statusCode === 404) {
+            return AppError.from(originalError, ErrorCode.RESOURCE_ERROR, '資源不存在');
+        }
+        if (statusCode === 401 || statusCode === 403) {
+            return AppError.from(originalError, ErrorCode.AUTHENTICATION_ERROR, '認證失敗或無權訪問');
+        }
+        if (statusCode === 429) {
+            return AppError.from(originalError, ErrorCode.RATE_LIMIT_ERROR, '請求過於頻繁，請稍後再試');
+        }
+        if (statusCode >= 500) {
+            return AppError.from(originalError, ErrorCode.API_ERROR, '服務器錯誤，請稍後再試');
+        }
+    }
+    // 處理常見的錯誤信息
+    if (message.includes('timeout') || message.includes('timed out')) {
+        return AppError.from(originalError, ErrorCode.TIMEOUT_ERROR, '網絡請求超時');
+    }
+    if (message.includes('network') || message.includes('connection') || message.includes('econnrefused') || message.includes('econnreset')) {
+        return AppError.from(originalError, ErrorCode.NETWORK_ERROR, '網絡連接錯誤');
+    }
+    if (message.includes('captcha') || message.includes('人機驗證')) {
+        return AppError.from(originalError, ErrorCode.CAPTCHA_REQUIRED, '需要進行人機驗證');
+    }
+    // 默認為通用網絡錯誤
+    return AppError.network(originalError instanceof Error ? originalError.message : '網絡請求失敗', originalError);
+}
+//# sourceMappingURL=error.js.map

package/dist/src/utils/error.js.map

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

package/dist/src/utils/fetch.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 通用網絡請求工具
+ * 提供封裝的 fetch API，包含重試和超時處理
+ */
+/**
+ * 請求選項接口
+ */
+export interface FetchOptions extends RequestInit {
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+}
+/**
+ * 延遲函數
+ * @param ms 延遲毫秒數
+ * @returns Promise<void>
+ */
+export declare const delay: (ms: number) => Promise<void>;
+/**
+ * 增強的 fetch 函數
+ * 支持超時、重試和錯誤處理
+ * @param url 請求 URL
+ * @param options 請求選項
+ * @returns Promise<Response>
+ */
+export declare function enhancedFetch(url: string, options?: FetchOptions): Promise<Response>;
+/**
+ * GET 請求，返回 JSON
+ * @param url 請求 URL
+ * @param options 請求選項
+ * @returns Promise<T> 返回 JSON 響應
+ */
+export declare function getJson<T = any>(url: string, options?: FetchOptions): Promise<T>;
+/**
+ * POST 請求，發送 JSON，返回 JSON
+ * @param url 請求 URL
+ * @param data 請求數據
+ * @param options 請求選項
+ * @returns Promise<T> 返回 JSON 響應
+ */
+export declare function postJson<T = any>(url: string, data: any, options?: FetchOptions): Promise<T>;

package/dist/src/utils/fetch.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * 通用網絡請求工具
+ * 提供封裝的 fetch API，包含重試和超時處理
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delay = void 0;
+exports.enhancedFetch = enhancedFetch;
+exports.getJson = getJson;
+exports.postJson = postJson;
+const logger_1 = require("./logger"); // Use the utils logger
+/**
+ * 默認請求選項
+ */
+const DEFAULT_FETCH_OPTIONS = {
+    timeout: 10000, // 默認超時時間為 10 秒
+    retries: 3, // 默認重試 3 次
+    retryDelay: 1000, // 默認重試間隔 1 秒
+    headers: {
+        // Keep a generic User-Agent, platform-specific headers can be added in options
+        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36',
+        'Accept': 'application/json, text/plain, */*',
+        'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
+        'Connection': 'keep-alive',
+        'Pragma': 'no-cache',
+        'Cache-Control': 'no-cache',
+    }
+};
+/**
+ * 延遲函數
+ * @param ms 延遲毫秒數
+ * @returns Promise<void>
+ */
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+exports.delay = delay;
+/**
+ * 增強的 fetch 函數
+ * 支持超時、重試和錯誤處理
+ * @param url 請求 URL
+ * @param options 請求選項
+ * @returns Promise<Response>
+ */
+async function enhancedFetch(url, options = {}) {
+    // Merge default options with provided options, ensuring headers are merged correctly
+    const mergedOptions = {
+        ...DEFAULT_FETCH_OPTIONS,
+        ...options,
+        headers: {
+            ...(DEFAULT_FETCH_OPTIONS.headers || {}),
+            ...(options.headers || {}),
+        },
+    };
+    const { timeout, retries, retryDelay, ...fetchOptions } = mergedOptions;
+    let attempt = 0;
+    while (attempt <= retries) {
+        attempt++;
+        let timeoutId = null;
+        try {
+            const controller = new AbortController();
+            if (timeout) {
+                timeoutId = setTimeout(() => controller.abort(), timeout);
+            }
+            fetchOptions.signal = controller.signal;
+            logger_1.utilsLogger.debug(`發起請求: ${fetchOptions.method || 'GET'} ${url} (嘗試 ${attempt})`);
+            const response = await fetch(url, fetchOptions);
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            if (!response.ok) {
+                // 處理非 2xx 狀態碼
+                let errorText = '';
+                try {
+                    errorText = await response.text();
+                }
+                catch (textError) {
+                    logger_1.utilsLogger.warn(`無法讀取錯誤響應體: ${textError}`);
+                }
+                const errorMessage = `HTTP 錯誤 ${response.status} (${response.statusText}) for ${url}: ${errorText.slice(0, 200)}`; // Limit error text length
+                logger_1.utilsLogger.warn(`請求失敗: ${errorMessage}`);
+                // Throw an error that includes the status code for better handling
+                const httpError = new Error(errorMessage);
+                httpError.statusCode = response.status;
+                throw httpError;
+            }
+            logger_1.utilsLogger.debug(`請求成功: ${url}`);
+            return response;
+        }
+        catch (error) {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            const err = error instanceof Error ? error : new Error(String(error));
+            logger_1.utilsLogger.warn(`請求失敗 (嘗試 ${attempt}/${retries + 1}): ${err.message}`);
+            // Check if the error is an abort error due to timeout
+            if (err.name === 'AbortError') {
+                logger_1.utilsLogger.error(`請求 ${url} 超時 (超時時間: ${timeout}ms)`);
+                // Optionally rethrow a specific timeout error
+                // throw new Error(`Request timed out after ${timeout}ms: ${url}`);
+            }
+            if (attempt > retries) {
+                logger_1.utilsLogger.error(`請求 ${url} 最終失敗: ${err.message}`);
+                throw err; // 達到最大重試次數後拋出錯誤
+            }
+            // 等待一段時間後重試
+            const delayTime = retryDelay * Math.pow(2, attempt - 1); // Exponential backoff
+            logger_1.utilsLogger.debug(`等待 ${delayTime}ms 後重試...`);
+            await (0, exports.delay)(delayTime);
+        }
+    }
+    // 如果循環結束仍未成功（理論上不應發生，除非 retries < 0）
+    throw new Error('請求失敗，達到最大重試次數');
+}
+/**
+ * GET 請求，返回 JSON
+ * @param url 請求 URL
+ * @param options 請求選項
+ * @returns Promise<T> 返回 JSON 響應
+ */
+async function getJson(url, options = {}) {
+    const response = await enhancedFetch(url, { ...options, method: 'GET' });
+    try {
+        return await response.json();
+    }
+    catch (e) {
+        logger_1.utilsLogger.error(`解析 JSON 失敗 from ${url}:`, e);
+        throw new Error(`Failed to parse JSON response from ${url}`);
+    }
+}
+/**
+ * POST 請求，發送 JSON，返回 JSON
+ * @param url 請求 URL
+ * @param data 請求數據
+ * @param options 請求選項
+ * @returns Promise<T> 返回 JSON 響應
+ */
+async function postJson(url, data, options = {}) {
+    const response = await enhancedFetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            // User-defined headers should override defaults if specified in options
+            ...(options.headers || {}),
+        },
+        body: JSON.stringify(data),
+        ...options, // Spread other options like timeout, retries
+    });
+    try {
+        return await response.json();
+    }
+    catch (e) {
+        logger_1.utilsLogger.error(`解析 JSON 失敗 from ${url}:`, e);
+        throw new Error(`Failed to parse JSON response from ${url}`);
+    }
+}
+//# sourceMappingURL=fetch.js.map

package/dist/src/utils/fetch.js.map

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

package/dist/src/utils/file.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 通用檔案操作工具
+ * 提供檔案系統操作功能，如下載檔案、獲取安全檔案名等
+ */
+/**
+ * 下載檔案
+ * @param url 檔案 URL
+ * @param destPath 目標路徑
+ * @param options 下載選項
+ * @returns Promise<string> 下載完成的檔案路徑
+ */
+export declare function downloadFile(url: string, destPath: string, options?: {
+    headers?: Record<string, string>;
+    timeout?: number;
+    /**
+     * 進度回調函數
+     * @param downloaded 已下載的字節數
+     * @param total 總字節數 (如果可用)
+     */
+    onProgress?: (downloaded: number, total?: number) => void;
+}): Promise<string>;
+/**
+ * 獲取安全的檔案名（替換非法字符）
+ * @param filename 原始檔案名
+ * @returns 安全的檔案名
+ */
+export declare function getSafeFilename(filename: string): string;
+/**
+ * 建立帶有時間戳的檔案名
+ * @param name 檔案名（不含副檔名）
+ * @param ext 副檔名（不含句點）
+ * @returns 格式化的檔案名
+ */
+export declare function getTimestampedFilename(name: string, ext: string): string;
+/**
+ * 確保目錄存在，如果不存在則創建
+ * @param dirPath 目錄路徑
+ */
+export declare function ensureDirectoryExists(dirPath: string): Promise<void>;
+/**
+ * 獲取應用數據目錄
+ * 根據作業系統選擇適當的目錄
+ * @param appName 應用程式名稱，用於創建子目錄
+ * @returns 資料目錄路徑
+ */
+export declare function getAppDataDir(appName?: string): string;