sfiledl 2.1.1 → 2.2.1

package/build/lib.mjs

@@ -1,62 +1,96 @@
-import path from 'path';
-import * as fs from 'fs/promises';
-import fs__default from 'fs/promises';
+import * as path from 'path';
+import path__default from 'path';
+import { createWriteStream, promises } from 'fs';
+import { randomUUID } from 'crypto';
 import { chromium } from 'playwright';
+import * as fs from 'fs/promises';
 import os from 'os';
 
 class AppError extends Error {
-    code;
-    retryable;
     timestamp;
     context;
+    code;
+    retryable;
     constructor(message, code, retryable = false, context) {
         super(message);
+        this.name = this.constructor.name;
         this.code = code;
         this.retryable = retryable;
-        this.name = this.constructor.name;
         this.timestamp = new Date().toISOString();
-        this.context = context ? { ...context } : undefined;
-        Error.captureStackTrace?.(this, this.constructor);
+        this.context = context ? Object.freeze({ ...context }) : Object.freeze({});
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+        Object.freeze(this);
     }
     toJSON() {
         return {
             name: this.name,
-            message: this.message,
             code: this.code,
+            message: this.message,
             retryable: this.retryable,
             timestamp: this.timestamp,
             context: this.context,
+            stack: process.env['NODE_ENV'] === 'development' ? this.stack : undefined,
         };
     }
+    toString() {
+        return `${this.name} [${this.code}]: ${this.message}`;
+    }
+    isCode(code) {
+        return this.code === code;
+    }
+    isRetryable() {
+        return this.retryable;
+    }
 }
 
 class ValidationError extends AppError {
     constructor(message, context) {
         super(message, 'VALIDATION_ERROR', false, context);
+        Object.freeze(this);
     }
 }
 class NetworkError extends AppError {
     constructor(message, context) {
         super(message, 'NETWORK_ERROR', true, context);
+        Object.freeze(this);
     }
 }
 class FileError extends AppError {
     constructor(message, context) {
         super(message, 'FILE_ERROR', false, context);
+        Object.freeze(this);
     }
 }
 class BrowserError extends AppError {
     constructor(message, context) {
         super(message, 'BROWSER_ERROR', true, context);
+        Object.freeze(this);
     }
 }
+function isAppError(err) {
+    return err instanceof AppError;
+}
+function isRetryableError(err) {
+    return isAppError(err) && err.retryable;
+}
+function isErrorWithCode(err, code) {
+    return isAppError(err) && err.code === code;
+}
 
 const DEFAULTS = {
     userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36',
     headless: true,
-    timeout: 100000,
-    downloadButtonTimeout: 100000,
-    fallbackWaitMs: 5000,
+    timeout: 60000,
+    downloadButtonTimeout: 30000,
+    fallbackWaitMs: 3000,
+    retries: 3,
+    retryDelay: 1000,
+    maxRetryDelay: 30000,
+    saveDebugArtifacts: true,
+    maxFilenameLength: 255,
+    sanitizeReplacement: '_',
 };
 
 class SfilePageInteractions {
@@ -67,46 +101,110 @@ class SfilePageInteractions {
         this.logger = logger;
     }
     async waitForDownloadButton(timeout) {
-        this.logger.debug('Waiting for #download button to be visible');
+        this.logger.debug('Waiting for #download button', { timeout });
         const button = this.page.locator('#download');
         await button.waitFor({ state: 'visible', timeout });
-        this.logger.debug('Waiting for button to become active (href != "#" and pointerEvents != "none")');
+        this.logger.debug('Button is visible, checking if active');
         await this.page.waitForFunction(() => {
             const btn = document.querySelector('#download');
             if (!btn)
                 return false;
             const href = btn.getAttribute('href');
             const style = window.getComputedStyle(btn);
-            return href && href !== '#' && style.pointerEvents !== 'none';
+            const isDisabled = btn.hasAttribute('disabled') ||
+                btn.getAttribute('aria-disabled') === 'true' ||
+                btn.classList.contains('disabled');
+            return !!(href &&
+                href !== '#' &&
+                href.trim() !== '' &&
+                style.pointerEvents !== 'none' &&
+                !isDisabled);
         }, { timeout });
+        this.logger.debug('Download button is active and ready');
     }
     async extractIntermediateUrl() {
-        this.logger.debug('Extracting href from #download');
-        const href = await this.page.$eval('#download', (el) => el.href);
-        if (!href || href === '#') {
-            throw new NetworkError('Download button href is invalid', { href });
+        this.logger.debug('Extracting href from #download button');
+        try {
+            const href = await this.page.$eval('#download', (el) => {
+                const anchor = el;
+                return anchor.href;
+            });
+            if (!href || href === '#' || href.trim() === '') {
+                throw new NetworkError('Download button href is empty or invalid', { href });
+            }
+            return href;
+        }
+        catch (err) {
+            if (err instanceof Error && err.message?.includes('Element not found')) {
+                throw new NetworkError('Download button (#download) not found in page', {
+                    selector: '#download',
+                    originalError: err.message,
+                });
+            }
+            throw err;
         }
-        return href;
     }
 }
 
 function sanitizeFilename(name, replacement = '_') {
-    const sanitized = name
+    const safeName = name.replace(/\.\.[\\/]/g, '');
+    const sanitized = safeName
         .replace(/[<>:"/\\|?*\x00-\x1F]/g, replacement)
         .replace(new RegExp(`${replacement}+`, 'g'), replacement)
-        .trim()
-        .slice(0, 255);
-    return sanitized || 'file.bin';
+        .trim();
+    const maxLength = 255;
+    const trimmed = sanitized.slice(0, maxLength);
+    return trimmed || `file${replacement}bin`;
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-function safeStringify(value) {
+function safeStringify(value, indent = 0) {
     try {
-        return JSON.stringify(value);
+        const seen = new WeakSet();
+        return JSON.stringify(value, (_key, val) => {
+            if (typeof val === 'object' && val !== null) {
+                if (seen.has(val))
+                    return '[Circular]';
+                seen.add(val);
+            }
+            if (typeof val === 'bigint')
+                return val.toString() + 'n';
+            if (val instanceof Error) {
+                return { name: val.name, message: val.message, stack: val.stack };
+            }
+            return val;
+        }, indent);
     }
     catch {
         return '[unserializable]';
     }
 }
+function extractFilenameFromContentDisposition(header) {
+    if (!header)
+        return null;
+    const encodedMatch = header.match(/filename\*=UTF-8''([^;\n"]+)/i);
+    if (encodedMatch?.[1]) {
+        try {
+            return decodeURIComponent(encodedMatch[1]);
+        }
+        catch { }
+    }
+    const quotedMatch = header.match(/filename\s*=\s*"([^"]+)"/i);
+    if (quotedMatch?.[1])
+        return quotedMatch[1];
+    const plainMatch = header.match(/filename\s*=\s*([^;,\n"]+)/i);
+    if (plainMatch?.[1])
+        return plainMatch[1].trim();
+    return null;
+}
+function calculateRetryDelay(attempt, baseDelayMs, maxDelayMs = 30000) {
+    const exponential = baseDelayMs * Math.pow(2, attempt - 1);
+    const jitter = Math.random() * 0.3 * exponential;
+    return Math.min(exponential + jitter, maxDelayMs);
+}
+function isError(value) {
+    return (value instanceof Error ||
+        (typeof value === 'object' && value !== null && 'message' in value));
+}
 
 class BrowserManager {
     logger;
@@ -116,21 +214,36 @@ class BrowserManager {
     page = null;
     interactions = null;
     debugDir = null;
+    stageHistory = [];
     constructor(logger, opts) {
         this.logger = logger;
         this.opts = opts;
     }
+    trackStage(stage) {
+        this.stageHistory.push({ stage, ts: Date.now() });
+    }
     async launch() {
+        const stage = 'launch';
+        this.trackStage(stage);
         try {
             this.logger.info('Launching browser', { headless: this.opts.headless });
             this.browser = await chromium.launch({
                 headless: this.opts.headless,
-                args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+                args: [
+                    '--no-sandbox',
+                    '--disable-setuid-sandbox',
+                    '--disable-dev-shm-usage',
+                    '--disable-accelerated-2d-canvas',
+                    '--no-first-run',
+                    '--no-zygote',
+                ],
             });
             this.context = await this.browser.newContext({
                 userAgent: this.opts.userAgent,
                 acceptDownloads: true,
                 locale: 'en-US',
+                timezoneId: 'UTC',
+                viewport: { width: 1280, height: 720 },
             });
             await this.context.addCookies([
                 {
@@ -144,211 +257,644 @@ class BrowserManager {
             this.page = await this.context.newPage();
             this.interactions = new SfilePageInteractions(this.page, this.logger);
             if (this.opts.debug) {
-                this.page.on('console', (msg) => {
-                    if (msg.type() === 'error')
-                        this.logger.error(`[console] ${msg.text()}`);
-                    else if (msg.type() === 'warning')
-                        this.logger.warn(`[console] ${msg.text()}`);
-                });
-                this.page.on('pageerror', (err) => this.logger.error(`[pageerror] ${err.message}`));
+                this.setupDebugListeners();
             }
             this.logger.info('Browser ready');
         }
         catch (err) {
-            throw new BrowserError(`Failed to launch browser: ${err.message}`);
+            await this.handleStageError(stage, err);
+            throw new BrowserError(`Failed to launch browser: ${err.message}`, {
+                stage,
+                originalError: err.message,
+                userAgent: this.opts.userAgent,
+            });
         }
     }
-    async goto(url, waitUntil = 'networkidle') {
+    setupDebugListeners() {
         if (!this.page)
-            throw new BrowserError('Page not initialized');
+            return;
+        this.page.on('console', (msg) => {
+            const type = msg.type();
+            const text = msg.text();
+            if (type === 'error') {
+                this.logger.error(`[console] ${text}`, { location: msg.location() });
+            }
+            else if (type === 'warning') {
+                this.logger.warn(`[console] ${text}`);
+            }
+            else if (type === 'debug') {
+                this.logger.debug(`[console] ${text}`);
+            }
+        });
+        this.page.on('pageerror', (err) => {
+            this.logger.error('[pageerror]', undefined, err);
+        });
+        this.page.on('requestfailed', (req) => {
+            const failure = req.failure();
+            this.logger.warn('[requestfailed]', {
+                url: req.url(),
+                method: req.method(),
+                error: failure?.errorText,
+            });
+        });
+    }
+    async goto(url, waitUntil = 'networkidle') {
+        const stage = 'navigation';
+        this.trackStage(stage);
+        if (!this.page) {
+            throw new BrowserError('Page not initialized', { stage });
+        }
         try {
-            this.logger.debug(`Navigating to ${url} (waitUntil=${waitUntil})`);
+            this.logger.debug(`Navigating to ${url}`, { waitUntil, timeout: this.opts.timeout });
             await this.page.goto(url, { waitUntil, timeout: this.opts.timeout });
         }
         catch (err) {
-            throw new NetworkError(`Navigation failed: ${err.message}`, { url });
+            await this.handleStageError(stage, err);
+            throw new NetworkError(`Navigation failed: ${err.message}`, {
+                url,
+                stage,
+                waitUntil,
+                timeout: this.opts.timeout,
+                originalError: err.message,
+            });
         }
     }
     async waitForDownloadButton() {
-        if (!this.interactions)
-            throw new BrowserError('Interactions not ready');
-        await this.interactions.waitForDownloadButton(DEFAULTS.downloadButtonTimeout);
+        const stage = 'waitForButton';
+        this.trackStage(stage);
+        if (!this.interactions) {
+            throw new BrowserError('Interactions not ready', { stage });
+        }
+        const timeout = this.opts.downloadButtonTimeout ?? DEFAULTS.downloadButtonTimeout;
+        try {
+            await this.interactions.waitForDownloadButton(timeout);
+        }
+        catch (err) {
+            await this.handleStageError(stage, err);
+            throw new NetworkError(`Failed to wait for download button: ${err.message}`, {
+                stage,
+                timeout,
+                originalError: err.message,
+            });
+        }
     }
     async getIntermediateUrl() {
-        if (!this.interactions)
-            throw new BrowserError('Interactions not ready');
-        return this.interactions.extractIntermediateUrl();
+        const stage = 'extractUrl';
+        this.trackStage(stage);
+        if (!this.interactions) {
+            throw new BrowserError('Interactions not ready', { stage });
+        }
+        try {
+            const url = await this.interactions.extractIntermediateUrl();
+            this.logger.debug('Intermediate URL extracted', { url });
+            return url;
+        }
+        catch (err) {
+            await this.handleStageError(stage, err);
+            throw new NetworkError(`Failed to extract intermediate URL: ${err.message}`, {
+                stage,
+                originalError: err.message,
+            });
+        }
     }
     async startDownloadAndWait(autoUrl) {
-        if (!this.page)
-            throw new BrowserError('Page not initialized');
+        const stage = 'downloadWait';
+        this.trackStage(stage);
+        if (!this.page) {
+            throw new BrowserError('Page not initialized', { stage });
+        }
         const downloadPromise = this.page
             .waitForEvent('download', { timeout: this.opts.timeout })
             .catch((err) => {
-            this.logger.warn(`Download event wait failed: ${err.message}`);
+            this.logger.debug('Download event timeout', {
+                timeout: this.opts.timeout,
+                error: err.message,
+            });
             return null;
         });
-        this.logger.debug(`Navigating to auto URL: ${autoUrl}`);
-        await this.page.goto(autoUrl, { waitUntil: 'commit', timeout: this.opts.timeout });
+        this.logger.debug('Navigating to auto download URL', { url: autoUrl });
+        await this.page
+            .goto(autoUrl, { waitUntil: 'commit', timeout: this.opts.timeout })
+            .catch((err) => {
+            this.logger.warn('Navigation to auto URL failed, continuing anyway', {
+                error: err.message,
+            });
+        });
         const download = await downloadPromise;
         if (download) {
             this.logger.info('Download event captured');
             return download;
         }
+        this.logger.debug('No download event captured within timeout');
         return null;
     }
     async fallbackCollectFileResponse() {
-        if (!this.page)
-            throw new BrowserError('Page not initialized');
-        this.logger.warn('Falling back to response interception');
+        const stage = 'fallbackIntercept';
+        this.trackStage(stage);
+        if (!this.page) {
+            throw new BrowserError('Page not initialized', { stage });
+        }
+        this.logger.info('Falling back to response interception');
         const responses = [];
         const handler = (res) => responses.push(res);
         this.page.on('response', handler);
         await sleep(DEFAULTS.fallbackWaitMs);
         this.page.off('response', handler);
         const fileResponse = [...responses].reverse().find((r) => {
-            const disposition = r.headers()['content-disposition'];
+            const headers = r.headers();
+            const disposition = headers['content-disposition'];
+            const contentType = headers['content-type'];
+            const url = r.url();
             return ((disposition && disposition.includes('attachment')) ||
-                r.url().includes('/downloadfile/'));
+                url.includes('/downloadfile/') ||
+                (contentType &&
+                    !contentType.startsWith('text/html') &&
+                    !contentType.startsWith('application/json')));
         });
-        if (!fileResponse)
+        if (!fileResponse) {
+            this.logger.debug('No suitable file response found in fallback', {
+                responseCount: responses.length,
+                sampleUrls: responses.slice(0, 3).map((r) => r.url()),
+            });
+            return null;
+        }
+        try {
+            const buffer = await fileResponse.body();
+            let filename = extractFilenameFromContentDisposition(fileResponse.headers()['content-disposition']);
+            if (!filename) {
+                const urlParts = fileResponse.url().split('/');
+                filename = urlParts[urlParts.length - 1]?.split('?')[0] || 'file.bin';
+            }
+            filename = filename.replace(/[<>:"/\\|?*]/g, '_');
+            this.logger.info('Fallback response captured', {
+                filename,
+                size: buffer.length,
+                contentType: fileResponse.headers()['content-type'],
+            });
+            return { buffer, filename };
+        }
+        catch (err) {
+            this.logger.error('Failed to read fallback response body', { error: err.message });
             return null;
-        const buffer = await fileResponse.body();
-        let filename = fileResponse.url().split('/').pop()?.split('?')[0] || 'file.bin';
-        filename = filename.replace(/[<>:"/\\|?*]/g, '_');
-        return { buffer, filename };
+        }
     }
     async saveDebugArtifacts(errorMessage) {
-        if (!this.page)
-            return;
+        if (!this.opts.debug || !this.page)
+            return null;
         try {
-            this.debugDir = path.join(os.tmpdir(), `sfile_debug_${Date.now()}`);
+            this.debugDir = path__default.join(os.tmpdir(), `sfile_debug_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`);
             await fs.mkdir(this.debugDir, { recursive: true });
-            await Promise.all([
-                this.page.screenshot({
-                    path: path.join(this.debugDir, 'error.png'),
+            const tasks = [
+                this.page
+                    .screenshot({
+                    path: path__default.join(this.debugDir, 'error.png'),
                     fullPage: true,
-                }),
-                fs.writeFile(path.join(this.debugDir, 'error.html'), await this.page.content()),
-                fs.writeFile(path.join(this.debugDir, 'error.txt'), errorMessage),
-            ]);
-            this.logger.info(`Debug artifacts saved to ${this.debugDir}`);
+                })
+                    .then(() => { }),
+                fs.writeFile(path__default.join(this.debugDir, 'error.html'), await this.page.content()),
+                fs.writeFile(path__default.join(this.debugDir, 'error.txt'), errorMessage),
+                fs.writeFile(path__default.join(this.debugDir, 'stages.json'), JSON.stringify(this.stageHistory, null, 2)),
+            ];
+            await Promise.all(tasks);
+            this.logger.info('Debug artifacts saved', { debugDir: this.debugDir });
+            return this.debugDir;
         }
         catch (e) {
-            this.logger.error(`Failed to save debug artifacts: ${e.message}`);
+            this.logger.error('Failed to save debug artifacts', { error: e.message });
+            return null;
+        }
+    }
+    async handleStageError(stage, error) {
+        if (this.opts.debug) {
+            await this.saveDebugArtifacts(`Error at stage "${stage}": ${error?.message || 'Unknown error'}`);
         }
     }
     async close() {
-        if (this.page)
-            await this.page.close().catch(() => { });
-        if (this.context)
-            await this.context.close().catch(() => { });
-        if (this.browser)
-            await this.browser.close().catch(() => { });
-        this.logger.debug('Browser closed');
+        const closePromises = [
+            this.page?.close().catch(() => { }),
+            this.context?.close().catch(() => { }),
+            this.browser?.close().catch(() => { }),
+        ].filter(Boolean);
+        await Promise.all(closePromises);
+        this.logger.debug('Browser closed', { stages: this.stageHistory.length });
+    }
+    async getPage() {
+        return this.page;
+    }
+    getDebugDir() {
+        return this.debugDir;
+    }
+    getStageHistory() {
+        return [...this.stageHistory];
     }
 }
 
 class Logger {
     minLevel;
-    constructor(debugMode = false) {
-        this.minLevel = debugMode ? 'debug' : 'info';
+    correlationId;
+    fileStream = null;
+    prefix;
+    constructor(options = {}) {
+        this.minLevel = options.debugMode ? 'debug' : 'info';
+        this.correlationId = options.correlationId;
+        this.prefix = options.prefix || '';
+        if (options.logFile) {
+            this.fileStream = createWriteStream(options.logFile, { flags: 'a' });
+        }
+    }
+    setCorrelationId(id) {
+        this.correlationId = id;
     }
     setDebug(enabled) {
         this.minLevel = enabled ? 'debug' : 'info';
     }
+    levelPriority(level) {
+        return { debug: 0, info: 1, warn: 2, error: 3 }[level];
+    }
     shouldLog(level) {
-        const levels = { debug: 0, info: 1, warn: 2, error: 3 };
-        return levels[level] >= levels[this.minLevel];
+        return this.levelPriority(level) >= this.levelPriority(this.minLevel);
     }
-    log(level, message, context) {
+    format(level, message, context) {
+        const ts = new Date().toISOString();
+        const corr = this.correlationId ? ` [${this.correlationId}]` : '';
+        const prefix = this.prefix ? ` [${this.prefix}]` : '';
+        const ctx = context ? ` | ${safeStringify(context)}` : '';
+        return `[${ts}]${corr}${prefix} ${level.toUpperCase()}: ${message}${ctx}`;
+    }
+    write(level, message, context) {
         if (!this.shouldLog(level))
             return;
-        const ts = new Date().toISOString();
-        const ctx = context ? ` ${safeStringify(context)}` : '';
-        console.log(`[${ts}] ${level.toUpperCase()}: ${message}${ctx}`);
+        const formatted = this.format(level, message, context);
+        const consoleMethod = level === 'error' ? 'error' : level === 'warn' ? 'warn' : 'log';
+        console[consoleMethod](formatted);
+        if (this.fileStream?.writable) {
+            this.fileStream.write(formatted + '\n');
+        }
     }
     debug(msg, ctx) {
-        this.log('debug', msg, ctx);
+        this.write('debug', msg, ctx);
     }
     info(msg, ctx) {
-        this.log('info', msg, ctx);
+        this.write('info', msg, ctx);
     }
     warn(msg, ctx) {
-        this.log('warn', msg, ctx);
+        this.write('warn', msg, ctx);
+    }
+    error(msg, ctx, err) {
+        let errorCtx;
+        if (err) {
+            const baseObj = ctx && typeof ctx === 'object' && ctx !== null
+                ? { ...ctx }
+                : {};
+            errorCtx = {
+                ...baseObj,
+                error: { name: err.name, message: err.message },
+            };
+        }
+        else {
+            errorCtx = ctx;
+        }
+        this.write('error', msg, errorCtx);
+    }
+    child(prefix) {
+        const childOptions = {
+            debugMode: this.minLevel === 'debug',
+            ...(this.correlationId !== undefined && { correlationId: this.correlationId }),
+            prefix: this.prefix ? `${this.prefix}:${prefix}` : prefix,
+        };
+        const child = new Logger(childOptions);
+        if (this.fileStream) {
+            child.fileStream = this.fileStream;
+        }
+        return child;
     }
-    error(msg, ctx) {
-        this.log('error', msg, ctx);
+    async close() {
+        if (this.fileStream && !this.fileStream.closed) {
+            return new Promise((resolve) => this.fileStream?.end(resolve));
+        }
     }
 }
 
 function normalizeOptions(opts) {
-    return {
+    const base = {
         headless: opts?.headless ?? DEFAULTS.headless,
-        debug: opts?.debug ?? false,
         userAgent: opts?.userAgent ?? DEFAULTS.userAgent,
         timeout: opts?.timeout ?? DEFAULTS.timeout,
+        downloadButtonTimeout: opts?.downloadButtonTimeout ?? DEFAULTS.downloadButtonTimeout,
+        retries: opts?.retries ?? DEFAULTS.retries,
+        retryDelay: opts?.retryDelay ?? DEFAULTS.retryDelay,
+        debug: opts?.debug ?? false,
+        saveDebugArtifacts: opts?.saveDebugArtifacts ?? DEFAULTS.saveDebugArtifacts,
+    };
+    const optional = {
+        ...(opts?.onProgress !== undefined && { onProgress: opts.onProgress }),
+        ...(opts?.correlationId !== undefined && { correlationId: opts.correlationId }),
+        ...(opts?._internal !== undefined && { _internal: opts._internal }),
+        ...(opts?.logFile !== undefined && { logFile: opts.logFile }),
     };
+    return { ...base, ...optional };
 }
 
-async function downloadSfile(url, saveDir, options) {
-    const opts = normalizeOptions(options);
-    const logger = new Logger(opts.debug);
-    if (!url || !url.includes('sfile.co')) {
-        throw new ValidationError('URL must contain sfile.co', { url });
+class InputValidator {
+    static validateUrl(url, allowedDomains = ['sfile.co', 'sfile.mobi']) {
+        if (!url || typeof url !== 'string') {
+            throw new ValidationError('URL must be a non-empty string', {
+                received: typeof url,
+                url,
+            });
+        }
+        const hasAllowedDomain = allowedDomains.some((domain) => url.includes(domain));
+        if (!hasAllowedDomain) {
+            throw new ValidationError(`URL must contain one of: ${allowedDomains.join(', ')}`, {
+                url,
+                allowedDomains,
+            });
+        }
+        try {
+            const parsed = new URL(url);
+            if (!['http:', 'https:'].includes(parsed.protocol)) {
+                throw new ValidationError('URL must use http or https protocol', {
+                    url,
+                    protocol: parsed.protocol,
+                });
+            }
+        }
+        catch (parseErr) {
+            throw new ValidationError('Invalid URL format', {
+                url,
+                parseError: parseErr instanceof Error ? parseErr.message : String(parseErr),
+            });
+        }
+    }
+    static validateSaveDir(dir) {
+        if (!dir || typeof dir !== 'string') {
+            throw new ValidationError('Save directory must be a non-empty string', {
+                received: typeof dir,
+                dir,
+            });
+        }
+    }
+    static sanitizeFilename(name) {
+        const replacement = DEFAULTS.sanitizeReplacement;
+        const maxLength = DEFAULTS.maxFilenameLength;
+        const sanitized = sanitizeFilename(name, replacement);
+        if (!sanitized || sanitized.length === 0) {
+            const ext = name.includes('.') ? name.split('.').pop() : 'bin';
+            return `downloaded_file${ext ? '.' + ext : ''}`.slice(0, maxLength);
+        }
+        return sanitized.slice(0, maxLength);
+    }
+    static validateOptions(options) {
+        if (options && typeof options !== 'object') {
+            throw new ValidationError('Options must be an object or undefined', {
+                received: typeof options,
+            });
+        }
+        const opts = options;
+        const numericFields = ['timeout', 'retries', 'retryDelay', 'downloadButtonTimeout'];
+        for (const field of numericFields) {
+            if (field in opts && typeof opts[field] !== 'number') {
+                throw new ValidationError(`Option '${field}' must be a number`, {
+                    field,
+                    received: typeof opts[field],
+                    value: opts[field],
+                });
+            }
+        }
+        const booleanFields = ['headless', 'debug', 'saveDebugArtifacts'];
+        for (const field of booleanFields) {
+            if (field in opts && typeof opts[field] !== 'boolean') {
+                throw new ValidationError(`Option '${field}' must be a boolean`, {
+                    field,
+                    received: typeof opts[field],
+                    value: opts[field],
+                });
+            }
+        }
     }
-    await fs__default.mkdir(saveDir, { recursive: true });
-    const browserMgr = new BrowserManager(logger, {
+}
+
+function stripUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+function safeProgress(onProgress, percent, total, meta) {
+    if (typeof onProgress === 'function') {
+        try {
+            onProgress(percent, total, meta);
+        }
+        catch (err) {
+            console.warn('Progress callback error:', err);
+        }
+    }
+}
+async function executeDownload(url, saveDir, opts, logger) {
+    const startTime = Date.now();
+    const browserMgr = new BrowserManager(logger.child('BrowserManager'), {
         headless: opts.headless,
         userAgent: opts.userAgent,
         timeout: opts.timeout,
         debug: opts.debug,
+        downloadButtonTimeout: opts.downloadButtonTimeout,
     });
+    let finalPath;
+    let fileSize;
+    let method;
     try {
+        logger.info('Starting download workflow', { url });
+        safeProgress(opts.onProgress, 10, 100, {
+            stage: 'launch',
+            message: 'Launching browser',
+            attempt: 1,
+        });
         await browserMgr.launch();
         await browserMgr.goto(url, 'networkidle');
+        safeProgress(opts.onProgress, 30, 100, { stage: 'navigation', message: 'Page loaded' });
         await browserMgr.waitForDownloadButton();
+        safeProgress(opts.onProgress, 50, 100, {
+            stage: 'button',
+            message: 'Download button ready',
+        });
         const intermediateUrl = await browserMgr.getIntermediateUrl();
         const autoUrl = intermediateUrl.includes('?')
             ? `${intermediateUrl}&auto=1`
             : `${intermediateUrl}?auto=1`;
+        logger.debug('Triggering download', { autoUrl });
+        safeProgress(opts.onProgress, 70, 100, { stage: 'trigger', message: 'Download triggered' });
         let download = await browserMgr.startDownloadAndWait(autoUrl);
-        let finalPath;
-        let fileSize;
-        let method;
         if (download) {
             const suggested = download.suggestedFilename() || 'file.bin';
-            const filename = sanitizeFilename(suggested);
+            const filename = InputValidator.sanitizeFilename(suggested);
             finalPath = path.join(saveDir, filename);
             await download.saveAs(finalPath);
-            const stat = await fs__default.stat(finalPath);
+            const stat = await promises.stat(finalPath);
             fileSize = stat.size;
             method = 'direct';
-            logger.info(`Saved via direct download: ${finalPath} (${fileSize} bytes)`);
+            logger.info('Saved via direct download', { path: finalPath, size: fileSize });
         }
         else {
+            logger.warn('Direct download not captured, trying fallback');
             const fallback = await browserMgr.fallbackCollectFileResponse();
             if (!fallback) {
-                throw new NetworkError('No download event and no file response found');
+                throw new NetworkError('No download event and no file response found', {
+                    url,
+                    intermediateUrl,
+                    autoUrl,
+                    stage: 'fallbackFailed',
+                });
             }
             const { buffer, filename: rawName } = fallback;
-            const filename = sanitizeFilename(rawName);
+            const filename = InputValidator.sanitizeFilename(rawName);
             finalPath = path.join(saveDir, filename);
-            await fs__default.writeFile(finalPath, buffer);
+            await promises.writeFile(finalPath, buffer);
             fileSize = buffer.length;
             method = 'fallback';
-            logger.info(`Saved via fallback: ${finalPath} (${fileSize} bytes)`);
+            logger.info('Saved via fallback', { path: finalPath, size: fileSize });
+        }
+        safeProgress(opts.onProgress, 100, 100, { stage: 'complete', message: 'Download finished' });
+        const result = {
+            filePath: finalPath,
+            size: fileSize,
+            method,
+            durationMs: Date.now() - startTime,
+            attempts: 1,
+        };
+        if (opts.correlationId !== undefined) {
+            result.correlationId = opts.correlationId;
         }
-        return { filePath: finalPath, size: fileSize, method };
+        return result;
     }
     catch (err) {
-        await browserMgr.saveDebugArtifacts(err.message);
-        throw err;
+        const error = err instanceof Error ? err : new Error(String(err));
+        const appError = error instanceof AppError
+            ? error
+            : new NetworkError(error.message, {
+                url,
+                saveDir,
+                correlationId: opts.correlationId,
+                originalError: error.message,
+                errorName: error.name,
+            });
+        if (opts.saveDebugArtifacts) {
+            const debugPath = await browserMgr.saveDebugArtifacts(appError.message);
+            if (debugPath) {
+                appError.debugPath = debugPath;
+                if (appError.context && typeof appError.context === 'object') {
+                    appError.context.debugPath = debugPath;
+                }
+            }
+        }
+        throw appError;
     }
     finally {
-        await browserMgr.close();
+        await browserMgr
+            .close()
+            .catch((e) => logger.error('Failed to close browser', { error: e.message }));
+        await logger.close().catch((e) => console.error('Failed to close logger', e));
+    }
+}
+async function downloadSfile(url, saveDir, options) {
+    const opts = normalizeOptions(options);
+    const correlationId = opts.correlationId || randomUUID();
+    const loggerOptions = {
+        debugMode: opts.debug,
+        correlationId,
+        prefix: 'downloadSfile',
+    };
+    if (opts.logFile !== undefined) {
+        loggerOptions.logFile = opts.logFile;
+    }
+    const logger = new Logger(loggerOptions);
+    InputValidator.validateUrl(url);
+    InputValidator.validateSaveDir(saveDir);
+    InputValidator.validateOptions(options);
+    await promises.mkdir(saveDir, { recursive: true });
+    let lastError;
+    let attempt = 0;
+    while (attempt < opts.retries) {
+        attempt++;
+        try {
+            logger.info(`Download attempt ${attempt}/${opts.retries}`, { url });
+            const result = await executeDownload(url, saveDir, opts, logger);
+            logger.info(`Download succeeded`, {
+                duration: result.durationMs,
+                attempts: attempt,
+                method: result.method,
+            });
+            return {
+                ...result,
+                attempts: attempt,
+                correlationId,
+            };
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            const isRetryable = lastError instanceof AppError && lastError.retryable;
+            const isLastAttempt = attempt >= opts.retries;
+            if (!isRetryable || isLastAttempt) {
+                logger.error(`Download failed permanently`, {
+                    error: lastError.message,
+                    attempt,
+                    retryable: isRetryable,
+                    lastAttempt: isLastAttempt,
+                });
+                throw lastError;
+            }
+            const delay = calculateRetryDelay(attempt, opts.retryDelay, DEFAULTS.maxRetryDelay);
+            logger.warn(`Retrying download`, {
+                attempt,
+                maxAttempts: opts.retries,
+                delayMs: Math.round(delay),
+                error: lastError.message,
+            });
+            safeProgress(opts.onProgress, 0, 100, {
+                stage: 'retry',
+                message: `Retry ${attempt}/${opts.retries}`,
+                attempt,
+            });
+            await sleep(delay);
+        }
+    }
+    throw lastError || new Error('Download failed after all retries');
+}
+async function downloadSfileSafe(url, saveDir, options) {
+    try {
+        const result = await downloadSfile(url, saveDir, options);
+        return { success: true, value: result };
+    }
+    catch (error) {
+        return { success: false, error: error };
+    }
+}
+function createDownloader(defaultOptions) {
+    const defaults = normalizeOptions(defaultOptions);
+    return {
+        async download(url, saveDir, callOptions) {
+            const merged = stripUndefined({ ...defaults, ...callOptions });
+            return downloadSfile(url, saveDir, merged);
+        },
+        async downloadSafe(url, saveDir, callOptions) {
+            const merged = stripUndefined({ ...defaults, ...callOptions });
+            return downloadSfileSafe(url, saveDir, merged);
+        },
+        withOptions(newDefaults) {
+            const merged = stripUndefined({ ...defaults, ...newDefaults });
+            return createDownloader(merged);
+        },
+    };
+}
+
+function isSuccess(result) {
+    return result.success === true;
+}
+function isFailure(result) {
+    return result.success === false;
+}
+function mapError(result, fn) {
+    if (!result.success) {
+        return { success: false, error: fn(result.error) };
     }
+    return result;
 }
 
-export { AppError, BrowserError, FileError, NetworkError, ValidationError, downloadSfile };
+export { AppError, BrowserError, DEFAULTS, FileError, InputValidator, Logger, NetworkError, ValidationError, calculateRetryDelay, createDownloader, downloadSfile, downloadSfileSafe, extractFilenameFromContentDisposition, isAppError, isFailure as isErr, isError, isErrorWithCode, isSuccess as isOk, isRetryableError, mapError as mapErr, normalizeOptions, safeStringify, sanitizeFilename, sleep };
 //# sourceMappingURL=lib.mjs.map