@aluvia/sdk 1.1.0 → 1.3.0

package/dist/cjs/client/AluviaClient.js

@@ -41,30 +41,42 @@ const errors_js_1 = require("../errors.js");
 const adapters_js_1 = require("./adapters.js");
 const logger_js_1 = require("./logger.js");
 const AluviaApi_js_1 = require("../api/AluviaApi.js");
+const BlockDetection_js_1 = require("./BlockDetection.js");
+const net = __importStar(require("node:net"));
 /**
  * AluviaClient is the main entry point for the Aluvia Client.
  *
  * It manages the local proxy server and configuration polling.
  */
 class AluviaClient {
+    /** Read-only access to the connection ID from ConfigManager. */
+    get connectionId() {
+        return this.configManager.connectionId;
+    }
     constructor(options) {
         this.connection = null;
         this.started = false;
         this.startPromise = null;
-        const apiKey = String(options.apiKey ?? '').trim();
+        this.blockDetection = null;
+        this.pageStates = new WeakMap();
+        /** Promise-based mutex to serialize handleDetectionResult's critical section. */
+        this._detectionMutex = Promise.resolve();
+        const apiKey = String(options.apiKey ?? "").trim();
         if (!apiKey) {
-            throw new errors_js_1.MissingApiKeyError('Aluvia apiKey is required');
+            throw new errors_js_1.MissingApiKeyError("Aluvia apiKey is required");
         }
-        const localProxy = options.localProxy ?? true;
         const strict = options.strict ?? true;
-        this.options = { ...options, apiKey, localProxy, strict };
-        const connectionId = Number(options.connectionId) ?? null;
-        const apiBaseUrl = options.apiBaseUrl ?? 'https://api.aluvia.io/v1';
-        const pollIntervalMs = options.pollIntervalMs ?? 5000;
+        this.options = { ...options, apiKey, strict };
+        const connectionId = options.connectionId != null ? Number(options.connectionId) : undefined;
+        if (connectionId !== undefined && !Number.isFinite(connectionId)) {
+            throw new Error('connectionId must be a finite number');
+        }
+        const apiBaseUrl = options.apiBaseUrl ?? "https://api.aluvia.io/v1";
+        const pollIntervalMs = Math.max(options.pollIntervalMs ?? 5000, 1000);
         const timeoutMs = options.timeoutMs;
-        const gatewayProtocol = options.gatewayProtocol ?? 'http';
-        const gatewayPort = options.gatewayPort ?? (gatewayProtocol === 'https' ? 8443 : 8080);
-        const logLevel = options.logLevel ?? 'info';
+        const gatewayProtocol = options.gatewayProtocol ?? "http";
+        const gatewayPort = options.gatewayPort ?? (gatewayProtocol === "https" ? 8443 : 8080);
+        const logLevel = options.logLevel ?? "info";
         this.logger = new logger_js_1.Logger(logLevel);
         // Create ConfigManager
         this.configManager = new ConfigManager_js_1.ConfigManager({
@@ -84,13 +96,233 @@ class AluviaClient {
             apiBaseUrl,
             timeoutMs,
         });
+        // Initialize block detection if configured
+        if (options.blockDetection !== undefined || options.startPlaywright) {
+            this.logger.debug("Initializing block detection");
+            const detectionConfig = options.blockDetection ?? { enabled: true };
+            this.blockDetection = new BlockDetection_js_1.BlockDetection(detectionConfig, this.logger);
+        }
+    }
+    /**
+     * Attaches per-page listeners for two-pass detection and SPA navigation.
+     */
+    attachPageListeners(page) {
+        const pageState = {
+            lastResponse: null,
+            lastAnalysisTs: 0,
+            skipFullPass: false,
+            fastResult: null,
+        };
+        this.pageStates.set(page, pageState);
+        // Capture navigation responses on main frame
+        page.on("response", (response) => {
+            try {
+                if (response.request().isNavigationRequest() &&
+                    response.request().frame() === page.mainFrame()) {
+                    pageState.lastResponse = response;
+                    pageState.skipFullPass = false;
+                    pageState.fastResult = null;
+                }
+            }
+            catch {
+                // Ignore errors
+            }
+        });
+        // Fast pass at domcontentloaded
+        page.on("domcontentloaded", async () => {
+            if (!this.blockDetection)
+                return;
+            try {
+                const result = await this.blockDetection.analyzeFast(page, pageState.lastResponse);
+                pageState.fastResult = result;
+                pageState.lastAnalysisTs = Date.now();
+                if (result.score >= 0.9) {
+                    pageState.skipFullPass = true;
+                    await this.handleDetectionResult(result, page);
+                }
+            }
+            catch (error) {
+                this.logger.warn(`Error in fast-pass detection: ${error.message}`);
+            }
+        });
+        // Full pass at load
+        page.on("load", async () => {
+            if (!this.blockDetection || pageState.skipFullPass)
+                return;
+            try {
+                // Wait for networkidle with timeout cap
+                try {
+                    await page.waitForLoadState("networkidle", {
+                        timeout: this.blockDetection.getNetworkIdleTimeoutMs(),
+                    });
+                }
+                catch {
+                    // Timeout is ok, proceed anyway
+                }
+                const result = await this.blockDetection.analyzeFull(page, pageState.lastResponse, pageState.fastResult ?? undefined);
+                pageState.lastAnalysisTs = Date.now();
+                await this.handleDetectionResult(result, page);
+            }
+            catch (error) {
+                this.logger.warn(`Error in full-pass detection: ${error.message}`);
+            }
+        });
+        // SPA detection via framenavigated
+        page.on("framenavigated", async (frame) => {
+            if (!this.blockDetection)
+                return;
+            try {
+                // Only handle main frame
+                if (frame !== page.mainFrame())
+                    return;
+                // Debounce per-page
+                const now = Date.now();
+                if (now - pageState.lastAnalysisTs < 200)
+                    return;
+                // Wait 50ms and check if a new response arrived
+                const responseBefore = pageState.lastResponse;
+                await new Promise((resolve) => setTimeout(resolve, 50));
+                if (pageState.lastResponse !== responseBefore)
+                    return; // Not SPA
+                const result = await this.blockDetection.analyzeSpa(page);
+                pageState.lastAnalysisTs = Date.now();
+                await this.handleDetectionResult(result, page);
+            }
+            catch (error) {
+                this.logger.warn(`Error in SPA detection: ${error.message}`);
+            }
+        });
+    }
+    /**
+     * Attaches page listeners to all existing and future pages in a context.
+     */
+    attachBlockDetectionListener(context) {
+        this.logger.debug("Attaching block detection listener to context");
+        // Attach to existing pages
+        try {
+            const existingPages = context.pages();
+            for (const page of existingPages) {
+                this.attachPageListeners(page);
+                // Check if page has already loaded (not about:blank)
+                if (page.url() !== "about:blank" && this.blockDetection) {
+                    this.blockDetection
+                        .analyzeFull(page, null)
+                        .then((result) => {
+                        return this.handleDetectionResult(result, page);
+                    })
+                        .catch((error) => {
+                        this.logger.warn(`Error analyzing existing page: ${error.message}`);
+                    });
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        // Attach to future pages
+        context.on("page", (page) => {
+            this.logger.debug(`New page detected: ${page.url()}`);
+            this.attachPageListeners(page);
+        });
+    }
+    /**
+     * Handle a detection result: fire callback, check persistent block, reload if needed.
+     *
+     * The auto-unblock critical section (persistent-block checks, rule updates, page reload)
+     * is serialized via a promise-based mutex to prevent concurrent calls from reading stale
+     * state and producing duplicate rule additions or missed persistent-block escalation.
+     */
+    async handleDetectionResult(result, page) {
+        if (!this.blockDetection)
+            return;
+        // Fire user's onDetection callback for all tiers (including clear).
+        // Pass a shallow clone so later internal mutations (e.g. persistentBlock)
+        // don't affect the object the user received.
+        // This runs outside the mutex so user code can execute concurrently
+        // without risk of deadlock if it triggers navigation.
+        const onDetection = this.blockDetection.getOnDetection();
+        if (onDetection) {
+            try {
+                const snapshot = { ...result, signals: [...result.signals] };
+                await onDetection(snapshot, page);
+            }
+            catch (error) {
+                this.logger.warn(`Error in onDetection callback: ${error.message}`);
+            }
+        }
+        // If auto-reload is disabled, stop here (detection-only mode)
+        if (!this.blockDetection.isAutoUnblock())
+            return;
+        // Check if auto-reload should fire for this blockStatus
+        const shouldReload = result.blockStatus === "blocked" ||
+            (result.blockStatus === "suspected" &&
+                this.blockDetection.isAutoUnblockOnSuspected());
+        if (!shouldReload)
+            return;
+        // Serialize the critical section: persistent-block state, rule updates, reload.
+        // This prevents concurrent handlers from reading stale retriedUrls/persistentHostnames.
+        let release;
+        const gate = new Promise((resolve) => { release = resolve; });
+        const acquired = this._detectionMutex;
+        this._detectionMutex = this._detectionMutex.then(() => gate);
+        await acquired;
+        try {
+            await this._handleAutoUnblock(result, page);
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Auto-unblock critical section. Must only be called under _detectionMutex.
+     */
+    async _handleAutoUnblock(result, page) {
+        const url = result.url;
+        const hostname = result.hostname;
+        // Check persistent block escalation
+        if (this.blockDetection.persistentHostnames.has(hostname)) {
+            result.persistentBlock = true;
+            this.logger.warn(`Persistent block on ${hostname}, skipping reload`);
+            return;
+        }
+        if (this.blockDetection.retriedUrls.has(url)) {
+            // Second block for this URL - mark hostname as persistent
+            result.persistentBlock = true;
+            this.blockDetection.persistentHostnames.add(hostname);
+            this.logger.warn(`Persistent block detected for ${hostname} after retry of ${url}`);
+            return;
+        }
+        // First block for this URL — cap set size to prevent unbounded growth
+        if (this.blockDetection.retriedUrls.size >= 10000) {
+            this.blockDetection.retriedUrls.clear();
+        }
+        this.blockDetection.retriedUrls.add(url);
+        // Add hostname to proxy routing rules
+        try {
+            const config = this.configManager.getConfig();
+            const currentRules = config?.rules ?? [];
+            if (!currentRules.includes(hostname)) {
+                this.logger.info(`Auto-adding ${hostname} to routing rules due to detection (blockStatus: ${result.blockStatus})`);
+                await this.updateRules([...currentRules, hostname]);
+            }
+        }
+        catch (error) {
+            this.logger.warn(`Failed to auto-add rule for ${hostname}: ${error.message}`);
+        }
+        // Reload page
+        try {
+            this.logger.info(`Reloading page after adding ${hostname} to rules`);
+            await page.reload();
+        }
+        catch (error) {
+            this.logger.warn(`Failed to reload page for ${hostname}: ${error.message}`);
+        }
     }
     /**
      * Start the Aluvia Client connection:
      * - Fetch initial account connection config from Aluvia.
      * - Start polling for config updates.
-     * - If localProxy is enabled (default): start a local HTTP proxy on 127.0.0.1:<localPort or free port>.
-     * - If localProxy is disabled: do NOT start a local proxy; adapters use gateway proxy settings.
+     * - Start a local HTTP proxy on 127.0.0.1:<localPort or free port>.
      *
      * Returns the active connection with host/port/url and a stop() method.
      */
@@ -104,55 +336,27 @@ class AluviaClient {
             return this.startPromise;
         }
         this.startPromise = (async () => {
-            const localProxyEnabled = this.options.localProxy === true;
             // Fetch initial configuration (may throw InvalidApiKeyError or ApiError)
             await this.configManager.init();
-            // Initialize Playwright if requested
-            let browserInstance = undefined;
-            if (this.options.startPlaywright) {
-                try {
-                    // @ts-expect-error - playwright is an optional peer dependency
-                    const pw = await Promise.resolve().then(() => __importStar(require('playwright')));
-                    // We need to launch the browser after we have proxy configuration
-                    // Store the chromium module for now, will launch after proxy is ready
-                    browserInstance = pw.chromium;
-                }
-                catch (error) {
-                    throw new errors_js_1.ApiError(`Failed to load Playwright. Make sure 'playwright' is installed: ${error.message}`, 500);
-                }
-            }
-            // Gateway mode cannot function without proxy credentials/config, so fail fast.
-            if (!localProxyEnabled && !this.configManager.getConfig()) {
-                throw new errors_js_1.ApiError('Failed to load account connection config; cannot start in gateway mode without proxy credentials', 500);
-            }
-            if (!localProxyEnabled) {
-                this.logger.debug('localProxy disabled — local proxy will not start');
+            const browserInstance = this.options.startPlaywright
+                ? await this._initPlaywright()
+                : undefined;
+            // Keep config fresh so routing decisions update without restarting.
+            this.configManager.startPolling();
+            try {
+                const { host, port, url } = await this.proxyServer.start(this.options.localPort);
                 let nodeAgents = null;
                 let undiciDispatcher = null;
                 let undiciFetchFn = null;
-                const cfgAtStart = this.configManager.getConfig();
-                const serverUrlAtStart = (() => {
-                    if (!cfgAtStart)
-                        return '';
-                    const { protocol, host, port } = cfgAtStart.rawProxy;
-                    return `${protocol}://${host}:${port}`;
-                })();
-                const getProxyUrlForHttpClients = () => {
-                    const cfg = this.configManager.getConfig();
-                    if (!cfg)
-                        return 'http://127.0.0.1';
-                    const { protocol, host, port, username, password } = cfg.rawProxy;
-                    return `${protocol}://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${host}:${port}`;
-                };
                 const getNodeAgents = () => {
                     if (!nodeAgents) {
-                        nodeAgents = (0, adapters_js_1.createNodeProxyAgents)(getProxyUrlForHttpClients());
+                        nodeAgents = (0, adapters_js_1.createNodeProxyAgents)(url);
                     }
                     return nodeAgents;
                 };
                 const getUndiciDispatcher = () => {
                     if (!undiciDispatcher) {
-                        undiciDispatcher = (0, adapters_js_1.createUndiciDispatcher)(getProxyUrlForHttpClients());
+                        undiciDispatcher = (0, adapters_js_1.createUndiciDispatcher)(url);
                     }
                     return undiciDispatcher;
                 };
@@ -161,10 +365,10 @@ class AluviaClient {
                     if (!d)
                         return;
                     try {
-                        if (typeof d.close === 'function') {
+                        if (typeof d.close === "function") {
                             await d.close();
                         }
-                        else if (typeof d.destroy === 'function') {
+                        else if (typeof d.destroy === "function") {
                             d.destroy();
                         }
                     }
@@ -173,6 +377,7 @@ class AluviaClient {
                     }
                 };
                 const stop = async () => {
+                    await this.proxyServer.stop();
                     this.configManager.stopPolling();
                     nodeAgents?.http?.destroy?.();
                     nodeAgents?.https?.destroy?.();
@@ -184,63 +389,44 @@ class AluviaClient {
                 };
                 // Launch browser if Playwright was requested
                 let launchedBrowser = undefined;
+                let launchedBrowserContext = undefined;
+                let browserCdpUrl;
                 if (browserInstance) {
-                    const cfg = this.configManager.getConfig();
-                    if (cfg) {
-                        const { protocol, host, port, username, password } = cfg.rawProxy;
-                        const proxySettings = {
-                            ...(0, adapters_js_1.toPlaywrightProxySettings)(`${protocol}://${host}:${port}`),
-                            username,
-                            password,
-                        };
-                        launchedBrowser = await browserInstance.launch({
-                            proxy: proxySettings,
-                        });
+                    const proxySettings = (0, adapters_js_1.toPlaywrightProxySettings)(url);
+                    for (let attempt = 0; attempt < 3; attempt++) {
+                        const cdpPort = await AluviaClient.findFreePort();
+                        try {
+                            launchedBrowser = await browserInstance.launch({
+                                proxy: proxySettings,
+                                headless: this.options.headless !== false,
+                                args: [`--remote-debugging-port=${cdpPort}`],
+                            });
+                            browserCdpUrl = `http://127.0.0.1:${cdpPort}`;
+                            break;
+                        }
+                        catch (err) {
+                            if (attempt === 2 || !err.message?.includes('EADDRINUSE'))
+                                throw err;
+                            this.logger.debug(`Port ${cdpPort} taken, retrying browser launch`);
+                        }
                     }
+                    launchedBrowserContext = await launchedBrowser.newContext();
+                    // Attach block detection
+                    this.attachBlockDetectionListener(launchedBrowserContext);
                 }
                 const stopWithBrowser = async () => {
-                    if (launchedBrowser) {
+                    if (launchedBrowser)
                         await launchedBrowser.close();
-                    }
                     await stop();
                 };
                 // Build connection object
                 const connection = {
-                    host: cfgAtStart?.rawProxy.host ?? '127.0.0.1',
-                    port: cfgAtStart?.rawProxy.port ?? 0,
-                    url: serverUrlAtStart,
-                    getUrl: () => {
-                        const cfg = this.configManager.getConfig();
-                        if (!cfg)
-                            return '';
-                        const { protocol, host, port, username, password } = cfg.rawProxy;
-                        return `${protocol}://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${host}:${port}`;
-                    },
-                    asPlaywright: () => {
-                        const cfg = this.configManager.getConfig();
-                        if (!cfg)
-                            return { server: '' };
-                        const { protocol, host, port, username, password } = cfg.rawProxy;
-                        return {
-                            ...(0, adapters_js_1.toPlaywrightProxySettings)(`${protocol}://${host}:${port}`),
-                            username,
-                            password,
-                        };
-                    },
-                    asPuppeteer: () => {
-                        const cfg = this.configManager.getConfig();
-                        if (!cfg)
-                            return [];
-                        const { protocol, host, port } = cfg.rawProxy;
-                        return (0, adapters_js_1.toPuppeteerArgs)(`${protocol}://${host}:${port}`);
-                    },
-                    asSelenium: () => {
-                        const cfg = this.configManager.getConfig();
-                        if (!cfg)
-                            return "";
-                        const { protocol, host, port } = cfg.rawProxy;
-                        return (0, adapters_js_1.toSeleniumArgs)(`${protocol}://${host}:${port}`);
-                    },
+                    host,
+                    port,
+                    url,
+                    asPlaywright: () => (0, adapters_js_1.toPlaywrightProxySettings)(url),
+                    asPuppeteer: () => (0, adapters_js_1.toPuppeteerArgs)(url),
+                    asSelenium: () => (0, adapters_js_1.toSeleniumArgs)(url),
                     asNodeAgents: () => getNodeAgents(),
                     asAxiosConfig: () => (0, adapters_js_1.toAxiosConfig)(getNodeAgents()),
                     asGotOptions: () => (0, adapters_js_1.toGotOptions)(getNodeAgents()),
@@ -252,6 +438,8 @@ class AluviaClient {
                         return undiciFetchFn;
                     },
                     browser: launchedBrowser,
+                    browserContext: launchedBrowserContext,
+                    cdpUrl: browserCdpUrl,
                     stop: stopWithBrowser,
                     close: stopWithBrowser,
                 };
@@ -259,92 +447,10 @@ class AluviaClient {
                 this.started = true;
                 return connection;
             }
-            // In client proxy mode, keep config fresh so routing decisions update without restarting.
-            this.configManager.startPolling();
-            // localProxy === true
-            const { host, port, url } = await this.proxyServer.start(this.options.localPort);
-            let nodeAgents = null;
-            let undiciDispatcher = null;
-            let undiciFetchFn = null;
-            const getNodeAgents = () => {
-                if (!nodeAgents) {
-                    nodeAgents = (0, adapters_js_1.createNodeProxyAgents)(url);
-                }
-                return nodeAgents;
-            };
-            const getUndiciDispatcher = () => {
-                if (!undiciDispatcher) {
-                    undiciDispatcher = (0, adapters_js_1.createUndiciDispatcher)(url);
-                }
-                return undiciDispatcher;
-            };
-            const closeUndiciDispatcher = async () => {
-                const d = undiciDispatcher;
-                if (!d)
-                    return;
-                try {
-                    if (typeof d.close === 'function') {
-                        await d.close();
-                    }
-                    else if (typeof d.destroy === 'function') {
-                        d.destroy();
-                    }
-                }
-                finally {
-                    undiciDispatcher = null;
-                }
-            };
-            const stop = async () => {
-                await this.proxyServer.stop();
+            catch (err) {
                 this.configManager.stopPolling();
-                nodeAgents?.http?.destroy?.();
-                nodeAgents?.https?.destroy?.();
-                nodeAgents = null;
-                await closeUndiciDispatcher();
-                undiciFetchFn = null;
-                this.connection = null;
-                this.started = false;
-            };
-            // Launch browser if Playwright was requested
-            let launchedBrowser = undefined;
-            if (browserInstance) {
-                const proxySettings = (0, adapters_js_1.toPlaywrightProxySettings)(url);
-                launchedBrowser = await browserInstance.launch({
-                    proxy: proxySettings,
-                });
+                throw err;
             }
-            const stopWithBrowser = async () => {
-                if (launchedBrowser) {
-                    await launchedBrowser.close();
-                }
-                await stop();
-            };
-            // Build connection object
-            const connection = {
-                host,
-                port,
-                url,
-                getUrl: () => url,
-                asPlaywright: () => (0, adapters_js_1.toPlaywrightProxySettings)(url),
-                asPuppeteer: () => (0, adapters_js_1.toPuppeteerArgs)(url),
-                asSelenium: () => (0, adapters_js_1.toSeleniumArgs)(url),
-                asNodeAgents: () => getNodeAgents(),
-                asAxiosConfig: () => (0, adapters_js_1.toAxiosConfig)(getNodeAgents()),
-                asGotOptions: () => (0, adapters_js_1.toGotOptions)(getNodeAgents()),
-                asUndiciDispatcher: () => getUndiciDispatcher(),
-                asUndiciFetch: () => {
-                    if (!undiciFetchFn) {
-                        undiciFetchFn = (0, adapters_js_1.createUndiciFetch)(getUndiciDispatcher());
-                    }
-                    return undiciFetchFn;
-                },
-                browser: launchedBrowser,
-                stop: stopWithBrowser,
-                close: stopWithBrowser,
-            };
-            this.connection = connection;
-            this.started = true;
-            return connection;
         })();
         try {
             return await this.startPromise;
@@ -371,13 +477,16 @@ class AluviaClient {
         if (!this.started) {
             return;
         }
-        // Only stop proxy if it was potentially started.
-        if (this.options.localProxy) {
+        if (this.connection) {
+            await this.connection.close();
+            // connection.close() sets this.connection = null and this.started = false
+        }
+        else {
             await this.proxyServer.stop();
+            this.configManager.stopPolling();
+            this.connection = null;
+            this.started = false;
         }
-        this.configManager.stopPolling();
-        this.connection = null;
-        this.started = false;
     }
     /**
      * Update the filtering rules used by the proxy.
@@ -404,7 +513,74 @@ class AluviaClient {
             return;
         }
         const trimmed = targetGeo.trim();
-        await this.configManager.setConfig({ target_geo: trimmed.length > 0 ? trimmed : null });
+        await this.configManager.setConfig({
+            target_geo: trimmed.length > 0 ? trimmed : null,
+        });
+    }
+    /**
+     * Get a list of hostnames that have been detected as blocked.
+     *
+     * This list is maintained in-memory and cleared when the client is stopped.
+     * Only available when block detection is enabled.
+     */
+    getBlockedHostnames() {
+        if (!this.blockDetection) {
+            return [];
+        }
+        return Array.from(this.blockDetection.persistentHostnames);
+    }
+    /**
+     * Clear the list of blocked hostnames and retried URLs.
+     *
+     * Only available when block detection is enabled.
+     */
+    clearBlockedHostnames() {
+        if (this.blockDetection) {
+            this.blockDetection.persistentHostnames.clear();
+            this.blockDetection.retriedUrls.clear();
+        }
+    }
+    /**
+     * Import Playwright, auto-installing if necessary.
+     * Returns the chromium browser type for launching.
+     */
+    async _initPlaywright() {
+        try {
+            const pw = await Promise.resolve().then(() => __importStar(require("playwright")));
+            // @ts-ignore
+            return pw.chromium;
+        }
+        catch {
+            // Playwright not installed — attempt auto-install
+            this.logger.info("Playwright not found. Installing playwright...");
+            const { execSync } = await Promise.resolve().then(() => __importStar(require("node:child_process")));
+            try {
+                execSync("npm install playwright", {
+                    stdio: "inherit",
+                    cwd: process.cwd(),
+                });
+                const pw = await Promise.resolve().then(() => __importStar(require("playwright")));
+                // @ts-ignore
+                return pw.chromium;
+            }
+            catch (installError) {
+                throw new errors_js_1.ApiError(`Failed to auto-install Playwright. Install it manually: npm install playwright\n${installError.message}`, 500);
+            }
+        }
+    }
+    /**
+     * Find a free TCP port by briefly binding to port 0.
+     */
+    static findFreePort() {
+        return new Promise((resolve, reject) => {
+            const server = net.createServer();
+            server.listen(0, '127.0.0.1', () => {
+                const addr = server.address();
+                const port = typeof addr === 'object' && addr ? addr.port : 0;
+                server.close(() => resolve(port));
+            });
+            server.on('error', reject);
+        });
     }
 }
 exports.AluviaClient = AluviaClient;