douyin-downloader 0.1.0

package/dist/src/utils/file.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * 通用檔案操作工具
+ * 提供檔案系統操作功能，如下載檔案、獲取安全檔案名等
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadFile = downloadFile;
+exports.getSafeFilename = getSafeFilename;
+exports.getTimestampedFilename = getTimestampedFilename;
+exports.ensureDirectoryExists = ensureDirectoryExists;
+exports.getAppDataDir = getAppDataDir;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os")); // Import os module
+const logger_1 = require("./logger"); // Use the utils logger
+const fetch_1 = require("./fetch"); // Use the shared fetch
+/**
+ * 下載檔案
+ * @param url 檔案 URL
+ * @param destPath 目標路徑
+ * @param options 下載選項
+ * @returns Promise<string> 下載完成的檔案路徑
+ */
+async function downloadFile(url, destPath, options = {}) {
+    let writer = null;
+    try {
+        // 確保目錄存在
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(destPath));
+        // 創建寫入流
+        writer = fs_extra_1.default.createWriteStream(destPath);
+        // 發送請求
+        const response = await (0, fetch_1.enhancedFetch)(url, {
+            headers: options.headers,
+            timeout: options.timeout
+        });
+        if (!response.ok) {
+            throw new Error(`下載失敗: ${response.status} ${response.statusText}`);
+        }
+        // 獲取總大小
+        const contentLength = response.headers.get('content-length');
+        const totalSize = contentLength ? parseInt(contentLength, 10) : undefined;
+        let downloaded = 0;
+        // 如果響應體不是可讀流，則直接寫入
+        if (!response.body) {
+            const buffer = await response.arrayBuffer();
+            writer.write(Buffer.from(buffer));
+            writer.end();
+            if (options.onProgress && totalSize !== undefined) {
+                options.onProgress(totalSize, totalSize);
+            }
+            return destPath;
+        }
+        // 創建讀取流
+        const reader = response.body.getReader();
+        // 處理進度
+        const processChunk = async () => {
+            const { done, value } = await reader.read();
+            if (done) {
+                // Ensure writer is closed before resolving
+                return new Promise((resolve) => {
+                    if (writer) {
+                        writer.end(resolve);
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+            }
+            if (value) {
+                downloaded += value.length;
+                // Wait for the write to complete to handle backpressure
+                await new Promise((resolve, reject) => {
+                    if (writer) {
+                        writer.write(Buffer.from(value), (err) => {
+                            if (err)
+                                reject(err);
+                            else
+                                resolve();
+                        });
+                    }
+                    else {
+                        reject(new Error("Writer is not available"));
+                    }
+                });
+                if (options.onProgress) {
+                    options.onProgress(downloaded, totalSize);
+                }
+            }
+            return processChunk();
+        };
+        await processChunk();
+        logger_1.utilsLogger.debug(`檔案已下載至 ${destPath}`);
+        return destPath;
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        logger_1.utilsLogger.error(`下載檔案 ${url} 至 ${destPath} 失敗:`, err);
+        // 確保關閉寫入流
+        if (writer && !writer.closed) {
+            writer.close();
+        }
+        // 如果檔案已經創建但下載失敗，則刪除它
+        try {
+            if (await fs_extra_1.default.pathExists(destPath)) {
+                await fs_extra_1.default.unlink(destPath);
+                logger_1.utilsLogger.debug(`刪除不完整的下載檔案: ${destPath}`);
+            }
+        }
+        catch (unlinkError) {
+            const unlinkErr = unlinkError instanceof Error ? unlinkError : new Error(String(unlinkError));
+            logger_1.utilsLogger.error(`刪除不完整的下載檔案 ${destPath} 失敗:`, unlinkErr);
+        }
+        throw new Error(`下載檔案失敗: ${err.message}`);
+    }
+}
+/**
+ * 獲取安全的檔案名（替換非法字符）
+ * @param filename 原始檔案名
+ * @returns 安全的檔案名
+ */
+function getSafeFilename(filename) {
+    if (!filename)
+        return 'untitled';
+    // 替換非法字符
+    return filename
+        .replace(/[\\/:*?"<>|]/g, '_') // 替換 Windows/Unix 不允許的字符
+        .replace(/\s+/g, ' ') // 將連續空白字符替換為單個空格
+        .trim() // 去除首尾空白字符
+        .slice(0, 200); // Limit filename length to avoid issues
+}
+/**
+ * 建立帶有時間戳的檔案名
+ * @param name 檔案名（不含副檔名）
+ * @param ext 副檔名（不含句點）
+ * @returns 格式化的檔案名
+ */
+function getTimestampedFilename(name, ext) {
+    const timestamp = new Date().toISOString().replace(/[:-]/g, '').split('.')[0];
+    const safeName = getSafeFilename(name);
+    const safeExt = ext.replace(/[^a-zA-Z0-9]/g, ''); // Sanitize extension
+    return `${timestamp}-${safeName}.${safeExt}`;
+}
+/**
+ * 確保目錄存在，如果不存在則創建
+ * @param dirPath 目錄路徑
+ */
+async function ensureDirectoryExists(dirPath) {
+    try {
+        await fs_extra_1.default.ensureDir(dirPath);
+        logger_1.utilsLogger.debug(`目錄已確保存在: ${dirPath}`);
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        logger_1.utilsLogger.error(`創建目錄 ${dirPath} 失敗:`, err);
+        // Consider throwing a specific AppError here
+        throw new Error(`無法創建目錄 ${dirPath}: ${err.message}`);
+    }
+}
+/**
+ * 獲取應用數據目錄
+ * 根據作業系統選擇適當的目錄
+ * @param appName 應用程式名稱，用於創建子目錄
+ * @returns 資料目錄路徑
+ */
+function getAppDataDir(appName = 'douyin-downloader') {
+    let dir;
+    const homedir = os_1.default.homedir();
+    switch (process.platform) {
+        case 'win32':
+            // Windows: %APPDATA%\[appName]
+            dir = path_1.default.join(process.env.APPDATA || path_1.default.join(homedir, 'AppData', 'Roaming'), appName);
+            break;
+        case 'darwin':
+            // macOS: ~/Library/Application Support/[appName]
+            dir = path_1.default.join(homedir, 'Library', 'Application Support', appName);
+            break;
+        default:
+            // Linux/其他: ~/.config/[appName] or ~/.local/share/[appName]
+            dir = path_1.default.join(process.env.XDG_CONFIG_HOME || path_1.default.join(homedir, '.config'), appName);
+            // Fallback to .local/share if .config doesn't exist or isn't standard?
+            // Or just stick to .config as a common practice.
+            break;
+    }
+    return dir;
+}
+//# sourceMappingURL=file.js.map

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

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

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

@@ -0,0 +1,11 @@
+/**
+ * 通用工具模組入口
+ * 重新導出所有共享的工具函數和類
+ */
+export * from './logger';
+export * from './error';
+export * from './fetch';
+export * from './file';
+export * from './retry';
+export * from './browser';
+export * from './performance';

package/dist/src/utils/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * 通用工具模組入口
+ * 重新導出所有共享的工具函數和類
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./logger"), exports);
+__exportStar(require("./error"), exports);
+__exportStar(require("./fetch"), exports);
+__exportStar(require("./file"), exports); // Includes downloadFile, getSafeFilename, getTimestampedFilename, ensureDirectoryExists, getAppDataDir
+__exportStar(require("./retry"), exports);
+__exportStar(require("./browser"), exports);
+__exportStar(require("./performance"), exports);
+// Add other shared utils here if created later
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,2CAAyB;AACzB,0CAAwB;AACxB,0CAAwB;AACxB,yCAAuB,CAAC,uGAAuG;AAC/H,0CAAwB;AACxB,4CAA0B;AAC1B,gDAA8B;AAC9B,+CAA+C"}

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

@@ -0,0 +1,161 @@
+/**
+ * 通用日誌工具
+ * 提供統一的日誌輸出功能，支持不同的日誌級別、格式化和範圍
+ */
+/**
+ * 日誌級別枚舉
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+/**
+ * 日誌級別名稱映射
+ */
+export declare const LOG_LEVEL_NAMES: Record<LogLevel, string>;
+/**
+ * 日誌選項接口
+ */
+export interface LoggerOptions {
+    scope?: string;
+    level?: LogLevel;
+    formatter?: LogFormatter;
+    transports?: LogTransport[];
+    metadata?: Record<string, any>;
+}
+/**
+ * 日誌記錄接口
+ */
+export interface LogEntry {
+    timestamp: Date;
+    level: LogLevel;
+    levelName: string;
+    scope: string;
+    message: string;
+    data: any[];
+    metadata?: Record<string, any>;
+}
+/**
+ * 日誌格式化器類型
+ */
+export type LogFormatter = (entry: LogEntry) => string;
+/**
+ * 日誌輸出目標接口
+ */
+export interface LogTransport {
+    log(entry: LogEntry): void;
+}
+/**
+ * 控制台日誌輸出目標
+ */
+export declare class ConsoleTransport implements LogTransport {
+    /**
+     * 輸出日誌到控制台
+     * @param entry 日誌記錄
+     */
+    log(entry: LogEntry): void;
+    /**
+     * 根據日誌級別獲取相應的控制台方法
+     * @param level 日誌級別
+     * @returns 控制台方法
+     */
+    private getConsoleMethod;
+}
+/**
+ * 默認日誌格式化器
+ * @param entry 日誌記錄
+ * @returns 格式化後的日誌字符串
+ */
+export declare const defaultFormatter: LogFormatter;
+/**
+ * Logger 類
+ * 日誌工具類，用於統一管理和格式化日誌輸出
+ */
+export declare class Logger {
+    private scope;
+    private level;
+    private formatter;
+    private transports;
+    private metadata?;
+    /**
+     * 創建 Logger 實例
+     * @param options 日誌選項
+     */
+    constructor(options?: LoggerOptions);
+    /**
+     * 創建日誌記錄
+     * @param level 日誌級別
+     * @param message 日誌消息
+     * @param data 附加數據
+     * @returns 日誌記錄
+     */
+    private createLogEntry;
+    /**
+     * 輸出日誌
+     * @param level 日誌級別
+     * @param message 日誌消息
+     * @param data 附加數據
+     */
+    private log;
+    /**
+     * 輸出調試日誌
+     * @param message 日誌消息
+     * @param data 附加數據
+     */
+    debug(message: string, ...data: any[]): void;
+    /**
+     * 輸出信息日誌
+     * @param message 日誌消息
+     * @param data 附加數據
+     */
+    info(message: string, ...data: any[]): void;
+    /**
+     * 輸出警告日誌
+     * @param message 日誌消息
+     * @param data 附加數據
+     */
+    warn(message: string, ...data: any[]): void;
+    /**
+     * 輸出錯誤日誌
+     * @param message 錯誤消息
+     * @param error 錯誤對象
+     * @param data 附加數據
+     */
+    error(message: string, error?: Error | unknown, ...data: any[]): void;
+    /**
+     * 設置日誌級別
+     * @param level 日誌級別
+     * @returns 當前 Logger 實例 (用於鏈式調用)
+     */
+    setLevel(level: LogLevel): Logger;
+    /**
+     * 添加元數據
+     * @param metadata 元數據對象
+     * @returns 當前 Logger 實例 (用於鏈式調用)
+     */
+    addMetadata(metadata: Record<string, any>): Logger;
+    /**
+     * 創建一個子日誌記錄器，繼承父日誌記錄器的配置
+     * @param subScope 子日誌範圍
+     * @param metadata 附加元數據
+     * @returns 子日誌記錄器實例
+     */
+    createSubLogger(subScope: string, metadata?: Record<string, any>): Logger;
+}
+/**
+ * 創建一個日誌記錄器
+ * @param scope 日誌範圍
+ * @param options 日誌選項
+ * @returns Logger 實例
+ */
+export declare function createLogger(scope: string, options?: LoggerOptions): Logger;
+export declare const rootLogger: Logger;
+export declare const authLogger: Logger;
+export declare const parserLogger: Logger;
+export declare const infoLogger: Logger;
+export declare const downloadLogger: Logger;
+export declare const cliLogger: Logger;
+export declare const utilsLogger: Logger;

package/dist/src/utils/logger.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * 通用日誌工具
+ * 提供統一的日誌輸出功能，支持不同的日誌級別、格式化和範圍
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.utilsLogger = exports.cliLogger = exports.downloadLogger = exports.infoLogger = exports.parserLogger = exports.authLogger = exports.rootLogger = exports.Logger = exports.defaultFormatter = exports.ConsoleTransport = exports.LOG_LEVEL_NAMES = exports.LogLevel = void 0;
+exports.createLogger = createLogger;
+/**
+ * 日誌級別枚舉
+ */
+var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+    LogLevel[LogLevel["NONE"] = 4] = "NONE"; // 用於完全禁用日誌
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
+/**
+ * 日誌級別名稱映射
+ */
+exports.LOG_LEVEL_NAMES = {
+    [LogLevel.DEBUG]: 'DEBUG',
+    [LogLevel.INFO]: 'INFO',
+    [LogLevel.WARN]: 'WARN',
+    [LogLevel.ERROR]: 'ERROR',
+    [LogLevel.NONE]: 'NONE'
+};
+/**
+ * 控制台日誌輸出目標
+ */
+class ConsoleTransport {
+    /**
+     * 輸出日誌到控制台
+     * @param entry 日誌記錄
+     */
+    log(entry) {
+        const method = this.getConsoleMethod(entry.level);
+        // 確保傳遞給控制台方法的是字符串，避免類型錯誤
+        method(entry.message);
+    }
+    /**
+     * 根據日誌級別獲取相應的控制台方法
+     * @param level 日誌級別
+     * @returns 控制台方法
+     */
+    getConsoleMethod(level) {
+        switch (level) {
+            case LogLevel.DEBUG:
+                return console.debug;
+            case LogLevel.INFO:
+                return console.info;
+            case LogLevel.WARN:
+                return console.warn;
+            case LogLevel.ERROR:
+                return console.error;
+            default:
+                return console.log;
+        }
+    }
+}
+exports.ConsoleTransport = ConsoleTransport;
+/**
+ * 默認日誌格式化器
+ * @param entry 日誌記錄
+ * @returns 格式化後的日誌字符串
+ */
+const defaultFormatter = (entry) => {
+    const timestamp = entry.timestamp.toISOString();
+    const scope = entry.scope ? `[${entry.scope}]` : '';
+    const level = `[${exports.LOG_LEVEL_NAMES[entry.level]}]`;
+    let message = `${timestamp} ${level} ${scope}: ${entry.message}`;
+    // 格式化附加數據
+    if (entry.data && entry.data.length > 0) {
+        try {
+            const dataStr = entry.data.map(item => {
+                if (item instanceof Error) {
+                    return item.stack || item.message;
+                }
+                if (typeof item === 'object' && item !== null) {
+                    // Handle circular references safely
+                    try {
+                        return JSON.stringify(item, null, 2);
+                    }
+                    catch (jsonError) {
+                        return `[無法序列化對象: ${jsonError}]`;
+                    }
+                }
+                return String(item);
+            }).join(' ');
+            if (dataStr.trim()) {
+                message += ` ${dataStr}`;
+            }
+        }
+        catch (e) {
+            message += ` [無法格式化附加數據: ${e}]`;
+        }
+    }
+    // 添加元數據
+    if (entry.metadata && Object.keys(entry.metadata).length > 0) {
+        try {
+            message += ` (metadata: ${JSON.stringify(entry.metadata)})`;
+        }
+        catch (e) {
+            message += ` [無法格式化元數據: ${e}]`;
+        }
+    }
+    return message;
+};
+exports.defaultFormatter = defaultFormatter;
+/**
+ * Logger 類
+ * 日誌工具類，用於統一管理和格式化日誌輸出
+ */
+class Logger {
+    scope;
+    level;
+    formatter;
+    transports;
+    metadata;
+    /**
+     * 創建 Logger 實例
+     * @param options 日誌選項
+     */
+    constructor(options = {}) {
+        this.scope = options.scope || '';
+        // Determine default level first
+        let defaultLevel = options.level ?? (process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG);
+        // --- Check args for silent mode override ---
+        // This check runs when the logger instance (including rootLogger) is created
+        const args = process.argv;
+        const commandIndex = args.findIndex(arg => ['info', 'list'].includes(arg));
+        const hasOutputFileOption = args.includes('-f') || args.includes('--file');
+        if (commandIndex !== -1 && ['info', 'list'].includes(args[commandIndex]) && !hasOutputFileOption) {
+            // Override default level if silent mode is detected
+            defaultLevel = LogLevel.NONE;
+            // We could potentially override console here too, but let's try logger level first
+        }
+        // ---
+        this.level = defaultLevel;
+        this.formatter = options.formatter || exports.defaultFormatter;
+        this.transports = options.transports || [new ConsoleTransport()];
+        this.metadata = options.metadata;
+    }
+    /**
+     * 創建日誌記錄
+     * @param level 日誌級別
+     * @param message 日誌消息
+     * @param data 附加數據
+     * @returns 日誌記錄
+     */
+    createLogEntry(level, message, data) {
+        return {
+            timestamp: new Date(),
+            level,
+            levelName: exports.LOG_LEVEL_NAMES[level],
+            scope: this.scope,
+            message,
+            data,
+            metadata: this.metadata
+        };
+    }
+    /**
+     * 輸出日誌
+     * @param level 日誌級別
+     * @param message 日誌消息
+     * @param data 附加數據
+     */
+    log(level, message, ...data) {
+        // 檢查日誌級別
+        if (level < this.level) {
+            return;
+        }
+        // 創建日誌記錄
+        const entry = this.createLogEntry(level, message, data);
+        // 格式化日誌
+        const formattedMessage = this.formatter(entry);
+        // 更新日誌記錄中的消息
+        entry.message = formattedMessage;
+        // 輸出到所有目標
+        for (const transport of this.transports) {
+            try {
+                transport.log(entry);
+            }
+            catch (error) {
+                // 避免日誌輸出錯誤破壞程序流程
+                console.error('日誌輸出失敗:', error);
+            }
+        }
+    }
+    /**
+     * 輸出調試日誌
+     * @param message 日誌消息
+     * @param data 附加數據
+     */
+    debug(message, ...data) {
+        this.log(LogLevel.DEBUG, message, ...data);
+    }
+    /**
+     * 輸出信息日誌
+     * @param message 日誌消息
+     * @param data 附加數據
+     */
+    info(message, ...data) {
+        this.log(LogLevel.INFO, message, ...data);
+    }
+    /**
+     * 輸出警告日誌
+     * @param message 日誌消息
+     * @param data 附加數據
+     */
+    warn(message, ...data) {
+        this.log(LogLevel.WARN, message, ...data);
+    }
+    /**
+     * 輸出錯誤日誌
+     * @param message 錯誤消息
+     * @param error 錯誤對象
+     * @param data 附加數據
+     */
+    error(message, error, ...data) {
+        const errorObj = error instanceof Error ? error : undefined;
+        const additionalData = error instanceof Error ? data : [error, ...data];
+        if (errorObj) {
+            this.log(LogLevel.ERROR, message, errorObj, ...additionalData);
+        }
+        else {
+            this.log(LogLevel.ERROR, message, ...additionalData);
+        }
+    }
+    /**
+     * 設置日誌級別
+     * @param level 日誌級別
+     * @returns 當前 Logger 實例 (用於鏈式調用)
+     */
+    setLevel(level) {
+        this.level = level;
+        return this;
+    }
+    /**
+     * 添加元數據
+     * @param metadata 元數據對象
+     * @returns 當前 Logger 實例 (用於鏈式調用)
+     */
+    addMetadata(metadata) {
+        this.metadata = { ...this.metadata, ...metadata };
+        return this;
+    }
+    /**
+     * 創建一個子日誌記錄器，繼承父日誌記錄器的配置
+     * @param subScope 子日誌範圍
+     * @param metadata 附加元數據
+     * @returns 子日誌記錄器實例
+     */
+    createSubLogger(subScope, metadata) {
+        const newScope = this.scope ? `${this.scope}:${subScope}` : subScope;
+        return new Logger({
+            scope: newScope,
+            level: this.level,
+            formatter: this.formatter,
+            transports: this.transports,
+            metadata: { ...this.metadata, ...metadata }
+        });
+    }
+}
+exports.Logger = Logger;
+/**
+ * 創建一個日誌記錄器
+ * @param scope 日誌範圍
+ * @param options 日誌選項
+ * @returns Logger 實例
+ */
+function createLogger(scope, options = {}) {
+    return new Logger({ ...options, scope });
+}
+// 創建默認的根日誌記錄器
+exports.rootLogger = createLogger('app'); // Changed default scope name
+// 導出特定模組的日誌記錄器 (可以根據需要調整或移除)
+exports.authLogger = exports.rootLogger.createSubLogger('auth');
+exports.parserLogger = exports.rootLogger.createSubLogger('parser');
+exports.infoLogger = exports.rootLogger.createSubLogger('info');
+exports.downloadLogger = exports.rootLogger.createSubLogger('download');
+exports.cliLogger = exports.rootLogger.createSubLogger('cli');
+exports.utilsLogger = exports.rootLogger.createSubLogger('utils'); // Added utils logger
+//# sourceMappingURL=logger.js.map