/**
 * @fileoverview Type definitions for the Terabox Scraper Library.
 * This file centralizes all data structures used across the library for strong typing and better maintainability.
 */

/**
 * Interface for the Terabox file information returned by the scraper.
 */
export interface FileInfo {
    /** The original Terabox share link. */
    shareLink: string;
    /** The extracted direct download URL. */
    downloadLink: string;
    /** The name of the file. */
    fileName: string;
    /** The size of the file in bytes. */
    fileSize: number;
    /** The size of the file in a human-readable format (e.g., "1.5 GB"). */
    fileSizeHuman: string;
    /** The URL for the file's thumbnail image. */
    thumbnailUrl: string | null;
    /** The file ID on Terabox. */
    fsId: string;
    /** The time the file was shared (timestamp). */
    shareTime: number;
}

/**
 * Interface for the configuration options of the TeraboxScraper class.
 */
export interface ScraperConfig {
    /** The user's Terabox cookie string (e.g., "lang=en; ndus=..."). Required for most operations. */
    cookie: string;
    /** Optional timeout for HTTP requests in milliseconds. Default is 30000ms. */
    timeout?: number;
    /** Optional user-agent string for requests. Default is a common desktop user-agent. */
    userAgent?: string;
    /** Optional proxy string (e.g., "http://user:pass@host:port") for all requests. */
    proxy?: string;
}

/**
 * Interface for the progress data during a file download.
 */
export interface DownloadProgress {
    /** The total size of the file in bytes. */
    totalSize: number;
    /** The number of bytes downloaded so far. */
    downloaded: number;
    /** The download progress as a percentage (0.0 to 100.0). */
    percentage: number;
    /** The current download speed in bytes per second. */
    speedBps: number;
    /** The estimated time remaining for the download in seconds. */
    etaSeconds: number;
}

/**
 * Type for the download progress callback function.
 */
export type ProgressCallback = (progress: DownloadProgress) => void;

/**
 * Interface for a standardized error object.
 */
export interface ScraperError {
    /** A unique error code (e.g., "E_COOKIE_INVALID", "E_NETWORK_TIMEOUT"). */
    code: string;
    /** A human-readable error message. */
    message: string;
    /** The original error object, if available. */
    originalError?: any;
}

/**
 * Interface for the standardized response object for all core methods.
 */
export interface ScraperResponse<T> {
    /** Whether the operation was successful. */
    success: boolean;
    /** The result data, present if `success` is true. */
    data?: T;
    /** The error details, present if `success` is false. */
    error?: ScraperError;
}

/**
 * Interface for the logger configuration.
 */
export interface LoggerConfig {
    /** The minimum level to log (e.g., 'info', 'warn', 'error'). Default is 'info'. */
    level?: 'silent' | 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
    /** Whether to use pretty printing for console output. Default is true. */
    prettyPrint?: boolean;
}

/**
 * Interface for the download result.
 */
export interface DownloadResult {
    /** The local path where the file was saved. */
    filePath: string;
    /** The total time taken for the download in milliseconds. */
    durationMs: number;
}

/**
 * Interface for the Terabox API response structure (simplified for internal use).
 * This structure is based on observed Terabox API responses.
 */
export interface TeraboxApiFileResponse {
    errno: number;
    errmsg: string;
    list: Array<{
        fs_id: number;
        server_filename: string;
        size: number;
        dlink: string;
        thumbs: {
            url1: string;
        };
        share_time: number;
    }>;
}

/**
 * Utility function to convert bytes to a human-readable string.
 * @param bytes The number of bytes.
 * @returns The human-readable string.
 */
export function bytesToHuman(bytes: number): string {
    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
    let i = 0;
    let size = bytes;
    while (size >= 1024 && i < units.length - 1) {
        size /= 1024;
        i++;
    }
    return `${size.toFixed(2)} ${units[i]}`;
}