@aluvia/sdk 1.4.0 → 2.0.0

package/dist/cjs/client/PageLoadDetection.js

@@ -1,175 +0,0 @@
-"use strict";
-// PageLoadDetection - Enhanced page load and blocking detection
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PageLoadDetection = void 0;
-const DEFAULT_BLOCKING_KEYWORDS = [
-    "captcha",
-    "blocked",
-    "access denied",
-    "forbidden",
-    "cloudflare",
-    "please verify",
-    "recaptcha",
-    "hcaptcha",
-    "bot detection",
-    "automated access",
-    "unusual activity",
-    "verify you are human",
-    "security check",
-    "access restricted",
-];
-const DEFAULT_BLOCKING_STATUS_CODES = [403, 429, 503];
-const DEFAULT_MIN_CONTENT_LENGTH = 100;
-/**
- * PageLoadDetection handles enhanced detection of page load failures and blocking
- */
-class PageLoadDetection {
-    constructor(config, logger) {
-        this.blockedHostnames = new Set();
-        this.logger = logger;
-        this.config = {
-            enabled: config.enabled ?? true,
-            blockingKeywords: config.blockingKeywords ?? DEFAULT_BLOCKING_KEYWORDS,
-            blockingStatusCodes: config.blockingStatusCodes ?? DEFAULT_BLOCKING_STATUS_CODES,
-            minContentLength: config.minContentLength ?? DEFAULT_MIN_CONTENT_LENGTH,
-            autoAddRules: config.autoAddRules ?? false,
-            onBlockingDetected: config.onBlockingDetected,
-        };
-    }
-    /**
-     * Update detection configuration
-     */
-    updateConfig(config) {
-        if (config.enabled !== undefined) {
-            this.config.enabled = config.enabled;
-        }
-        if (config.blockingKeywords !== undefined) {
-            this.config.blockingKeywords = config.blockingKeywords;
-        }
-        if (config.blockingStatusCodes !== undefined) {
-            this.config.blockingStatusCodes = config.blockingStatusCodes;
-        }
-        if (config.minContentLength !== undefined) {
-            this.config.minContentLength = config.minContentLength;
-        }
-        if (config.autoAddRules !== undefined) {
-            this.config.autoAddRules = config.autoAddRules;
-        }
-        if (config.onBlockingDetected !== undefined) {
-            this.config.onBlockingDetected = config.onBlockingDetected;
-        }
-    }
-    /**
-     * Check if a hostname is already marked as blocked
-     */
-    isHostnameBlocked(hostname) {
-        return this.blockedHostnames.has(hostname);
-    }
-    /**
-     * Get all blocked hostnames
-     */
-    getBlockedHostnames() {
-        return Array.from(this.blockedHostnames);
-    }
-    /**
-     * Clear blocked hostnames cache
-     */
-    clearBlockedHostnames() {
-        this.blockedHostnames.clear();
-    }
-    /**
-     * Analyze a page load and detect if it was blocked
-     */
-    async analyzePage(page, response) {
-        if (!this.config.enabled) {
-            return {
-                url: page.url(),
-                hostname: this.extractHostname(page.url()),
-                success: true,
-                blocked: false,
-            };
-        }
-        this.logger.debug("Analyzing page load for URL: " + page.url());
-        const url = page.url();
-        const hostname = this.extractHostname(url);
-        try {
-            // Check HTTP status code
-            const statusCode = response?.status?.() ?? 0;
-            if (statusCode > 0 &&
-                this.config.blockingStatusCodes.includes(statusCode)) {
-                const reason = {
-                    type: "status_code",
-                    details: `HTTP status code ${statusCode} indicates blocking`,
-                    statusCode,
-                };
-                await this.handleBlocking(hostname, reason, page);
-                return { url, hostname, success: false, blocked: true, reason };
-            }
-            // Get page content
-            const content = await page.content().catch(() => "");
-            // Check for blocking keywords first (more specific than content length)
-            const contentLower = content.toLowerCase();
-            const title = (await page.title().catch(() => "")).toLowerCase();
-            const combinedText = `${contentLower} ${title}`;
-            for (const keyword of this.config.blockingKeywords) {
-                if (combinedText.includes(keyword.toLowerCase())) {
-                    const reason = {
-                        type: "keyword",
-                        details: `Blocking keyword detected: "${keyword}"`,
-                        keyword,
-                    };
-                    await this.handleBlocking(hostname, reason, page);
-                    return { url, hostname, success: false, blocked: true, reason };
-                }
-            }
-            // Check content length (less critical than keywords)
-            if (!content || content.length < this.config.minContentLength) {
-                const reason = {
-                    type: "content_length",
-                    details: `Page content too short (${content.length} < ${this.config.minContentLength})`,
-                };
-                this.logger.warn(`Page may have failed to load: ${url} (${reason.details})`);
-                return { url, hostname, success: false, blocked: false, reason };
-            }
-            // Page loaded successfully
-            return { url, hostname, success: true, blocked: false };
-        }
-        catch (error) {
-            const reason = {
-                type: "error",
-                details: `Error analyzing page: ${error.message}`,
-            };
-            this.logger.warn(`Error checking page load status for ${url}: ${error.message}`);
-            return { url, hostname, success: false, blocked: false, reason };
-        }
-    }
-    /**
-     * Handle detected blocking
-     */
-    async handleBlocking(hostname, reason, page) {
-        this.blockedHostnames.add(hostname);
-        this.logger.warn(`Blocking detected for ${hostname}: ${reason.details}`);
-        // Trigger callback if provided
-        if (this.config.onBlockingDetected) {
-            try {
-                await this.config.onBlockingDetected(hostname, reason, page);
-            }
-            catch (error) {
-                this.logger.warn(`Error in onBlockingDetected callback: ${error.message}`);
-            }
-        }
-    }
-    /**
-     * Extract hostname from URL
-     */
-    extractHostname(url) {
-        try {
-            const parsed = new URL(url);
-            return parsed.hostname;
-        }
-        catch {
-            return url;
-        }
-    }
-}
-exports.PageLoadDetection = PageLoadDetection;

package/dist/esm/bin/account.js

@@ -1,28 +0,0 @@
-import { requireApi } from './api-helpers.js';
-import { output } from './cli.js';
-export async function handleAccount(args) {
-    const subcommand = args[0];
-    if (!subcommand) {
-        const api = requireApi();
-        const account = await api.account.get();
-        return output({ account });
-    }
-    if (subcommand === 'usage') {
-        let start;
-        let end;
-        for (let i = 1; i < args.length; i++) {
-            if (args[i] === '--start' && args[i + 1]) {
-                start = args[i + 1];
-                i++;
-            }
-            else if (args[i] === '--end' && args[i + 1]) {
-                end = args[i + 1];
-                i++;
-            }
-        }
-        const api = requireApi();
-        const usage = await api.account.usage.get({ start, end });
-        return output({ usage });
-    }
-    return output({ error: `Unknown account subcommand: '${subcommand}'.` }, 1);
-}

package/dist/esm/bin/api-helpers.js

@@ -1,53 +0,0 @@
-import { AluviaApi } from '../api/AluviaApi.js';
-import { readLock, listSessions, isProcessAlive, removeLock, toLockData } from '../session/lock.js';
-import { output } from './cli.js';
-/**
- * Create an AluviaApi instance from ALUVIA_API_KEY env var.
- * Calls output() and exits if the key is missing.
- */
-export function requireApi() {
-    const apiKey = (process.env.ALUVIA_API_KEY ?? '').trim();
-    if (!apiKey) {
-        return output({ error: 'ALUVIA_API_KEY environment variable is required.' }, 1);
-    }
-    return new AluviaApi({ apiKey });
-}
-/**
- * Resolve a session by name or auto-select when only one is running.
- * Calls output() and exits on error (no sessions, ambiguous sessions, stale lock).
- */
-export function resolveSession(sessionName) {
-    if (sessionName) {
-        const lock = readLock(sessionName);
-        if (!lock) {
-            return output({ error: `No session found with name '${sessionName}'.` }, 1);
-        }
-        if (!isProcessAlive(lock.pid)) {
-            removeLock(sessionName);
-            return output({ error: `Session '${sessionName}' is no longer running (stale lock cleaned up).` }, 1);
-        }
-        return { session: sessionName, lock };
-    }
-    const sessions = listSessions();
-    if (sessions.length === 0) {
-        return output({ error: 'No running browser sessions found.' }, 1);
-    }
-    if (sessions.length > 1) {
-        return output({
-            error: 'Multiple sessions running. Specify --browser-session <name>.',
-            browserSessions: sessions.map((s) => s.session),
-        }, 1);
-    }
-    const s = sessions[0];
-    return { session: s.session, lock: toLockData(s) };
-}
-/**
- * Require a connection ID from lock data.
- * Calls output() and exits if connectionId is missing.
- */
-export function requireConnectionId(lock, session) {
-    if (lock.connectionId == null) {
-        return output({ error: `Session '${session}' has no connection ID. It may have been started without API access.` }, 1);
-    }
-    return lock.connectionId;
-}

package/dist/esm/bin/cli-adapter.js

@@ -1,8 +0,0 @@
-/**
- * Re-exports for @aluvia/mcp. MCP package imports from @aluvia/sdk/cli.
- */
-export { handleSession } from "./session.js";
-export { handleAccount } from "./account.js";
-export { handleGeos } from "./geos.js";
-export { handleOpen } from "./open.js";
-export { captureOutput } from "./mcp-helpers.js";

package/dist/esm/bin/cli.js

@@ -1,242 +0,0 @@
-#!/usr/bin/env node
-import { handleOpenDaemon } from "./open.js";
-import { handleSession, parseSessionArgs } from "./session.js";
-import { handleAccount } from "./account.js";
-import { handleGeos } from "./geos.js";
-import { validateSessionName } from "../session/lock.js";
-import { isCapturing, MCPOutputCapture } from "./mcp-helpers.js";
-export function output(data, exitCode = 0) {
-    if (isCapturing()) {
-        throw new MCPOutputCapture(data, exitCode);
-    }
-    console.log(JSON.stringify(data));
-    process.exit(exitCode);
-}
-function printHelp(toStderr = false) {
-    const log = toStderr ? console.error : console.log;
-    log("Aluvia CLI\n");
-    log("Usage:");
-    log("  aluvia session start <url> [options]       Start a browser session");
-    log("  aluvia session close [options]              Stop a browser session");
-    log("  aluvia session list                         List active browser sessions");
-    log("  aluvia session get [options]                Get session details and proxy URLs");
-    log("  aluvia session rotate-ip [options]          Rotate IP on a running session");
-    log("  aluvia session set-geo <geo> [options]      Set target geo on a running session");
-    log("  aluvia session set-rules <rules> [options]  Set routing rules on a running session\n");
-    log("  aluvia account                              Show account info");
-    log("  aluvia account usage [options]              Show usage stats");
-    log("  aluvia geos                                 List available geos");
-    log("  aluvia help [--json]                        Show this help\n");
-    log("Session start options:");
-    log("  --connection-id <id>       Use a specific connection ID");
-    log("  --headful                  Run browser in headful mode");
-    log("  --browser-session <name>   Name for this session (auto-generated if omitted)");
-    log("  --auto-unblock             Auto-detect blocks and reload through Aluvia");
-    log("  --disable-block-detection  Disable block detection entirely");
-    log("  --run <script>             Run a script with page, browser, context injected\n");
-    log("Session close options:");
-    log("  --browser-session <name>   Close a specific session");
-    log("  --all                      Close all sessions\n");
-    log("Session targeting (get, rotate-ip, set-geo, set-rules):");
-    log("  --browser-session <name>   Target a specific session (auto-selects if only one)\n");
-    log("Session set-rules:");
-    log('  <rules>                    Comma-separated rules to append (e.g. "a.com,b.com")');
-    log("  --remove <rules>           Remove specific rules instead of appending\n");
-    log("Session set-geo:");
-    log('  <geo>                      Geo code to set (e.g. "US")');
-    log("  --clear                    Clear target geo\n");
-    log("Account usage options:");
-    log("  --start <ISO8601>          Start date filter");
-    log("  --end <ISO8601>            End date filter\n");
-    log("Environment:");
-    log("  ALUVIA_API_KEY   Required. Your Aluvia API key.\n");
-    log("Output:");
-    log("  All commands output JSON to stdout.");
-}
-function printHelpJson() {
-    return output({
-        commands: [
-            {
-                command: "session start <url>",
-                description: "Start a browser session",
-                options: [
-                    {
-                        flag: "--connection-id <id>",
-                        description: "Use a specific connection ID",
-                    },
-                    { flag: "--headful", description: "Run browser in headful mode" },
-                    {
-                        flag: "--browser-session <name>",
-                        description: "Name for this session (auto-generated if omitted)",
-                    },
-                    {
-                        flag: "--auto-unblock",
-                        description: "Auto-detect blocks and reload through Aluvia",
-                    },
-                    {
-                        flag: "--disable-block-detection",
-                        description: "Disable block detection entirely",
-                    },
-                    {
-                        flag: "--run <script>",
-                        description: "Run a script with page, browser, context injected",
-                    },
-                ],
-            },
-            {
-                command: "session close",
-                description: "Stop a browser session",
-                options: [
-                    {
-                        flag: "--browser-session <name>",
-                        description: "Close a specific session",
-                    },
-                    { flag: "--all", description: "Close all sessions" },
-                ],
-            },
-            {
-                command: "session list",
-                description: "List active browser sessions",
-                options: [],
-            },
-            {
-                command: "session get",
-                description: "Get session details and proxy URLs",
-                options: [
-                    {
-                        flag: "--browser-session <name>",
-                        description: "Target a specific session (auto-selects if only one)",
-                    },
-                ],
-            },
-            {
-                command: "session rotate-ip",
-                description: "Rotate IP on a running session",
-                options: [
-                    {
-                        flag: "--browser-session <name>",
-                        description: "Target a specific session (auto-selects if only one)",
-                    },
-                ],
-            },
-            {
-                command: "session set-geo <geo>",
-                description: "Set target geo on a running session",
-                options: [
-                    {
-                        flag: "--browser-session <name>",
-                        description: "Target a specific session (auto-selects if only one)",
-                    },
-                    { flag: "--clear", description: "Clear target geo" },
-                ],
-            },
-            {
-                command: "session set-rules <rules>",
-                description: "Set routing rules on a running session",
-                options: [
-                    {
-                        flag: "--browser-session <name>",
-                        description: "Target a specific session (auto-selects if only one)",
-                    },
-                    {
-                        flag: "--remove <rules>",
-                        description: "Remove specific rules instead of appending",
-                    },
-                ],
-            },
-            {
-                command: "account",
-                description: "Show account info",
-                options: [],
-            },
-            {
-                command: "account usage",
-                description: "Show usage stats",
-                options: [
-                    { flag: "--start <ISO8601>", description: "Start date filter" },
-                    { flag: "--end <ISO8601>", description: "End date filter" },
-                ],
-            },
-            {
-                command: "geos",
-                description: "List available geos",
-                options: [],
-            },
-            {
-                command: "help",
-                description: "Show this help",
-                options: [{ flag: "--json", description: "Output help as JSON" }],
-            },
-        ],
-    });
-}
-function printHelpAndExit(args) {
-    if (args.includes("--json")) {
-        return printHelpJson();
-    }
-    printHelp();
-    process.exit(0);
-}
-function parseDaemonArgs(args) {
-    return parseSessionArgs(args);
-}
-async function main() {
-    const args = process.argv.slice(2);
-    const command = args[0] ?? "";
-    // Internal: --daemon mode (spawned by `session start` in detached child)
-    if (command === "--daemon") {
-        const parsed = parseDaemonArgs(args.slice(1));
-        if (parsed.sessionName && !validateSessionName(parsed.sessionName)) {
-            output({
-                error: "Invalid session name. Use only letters, numbers, hyphens, and underscores.",
-            }, 1);
-        }
-        if (!parsed.url) {
-            return output({ error: "URL is required for daemon mode." }, 1);
-        }
-        await handleOpenDaemon({
-            url: parsed.url,
-            connectionId: parsed.connectionId,
-            headless: !parsed.headed,
-            sessionName: parsed.sessionName,
-            autoUnblock: parsed.autoUnblock,
-            disableBlockDetection: parsed.disableBlockDetection,
-            run: parsed.run,
-        });
-        return;
-    }
-    // Check for --help / -h anywhere in args (subcommand help)
-    const wantsHelp = args.includes("--help") || args.includes("-h");
-    if (command === "session") {
-        if (wantsHelp)
-            printHelpAndExit(args);
-        await handleSession(args.slice(1));
-    }
-    else if (command === "account") {
-        if (wantsHelp)
-            printHelpAndExit(args);
-        await handleAccount(args.slice(1));
-    }
-    else if (command === "geos") {
-        if (wantsHelp)
-            printHelpAndExit(args);
-        await handleGeos();
-    }
-    else if (command === "help" ||
-        command === "--help" ||
-        command === "-h" ||
-        command === "") {
-        printHelpAndExit(args);
-    }
-    else {
-        output({ error: `Unknown command: '${command}'. Run "aluvia help" for usage.` }, 1);
-    }
-}
-// Only run CLI when this file is the direct entry point (not when imported by MCP server).
-// Check if process.argv[1] resolves to this CLI file rather than another entry point.
-const isCli = process.argv[1]?.match(/(?:cli)\.[jt]s$/);
-if (isCli) {
-    main().catch((err) => {
-        output({ error: err.message }, 1);
-    });
-}

package/dist/esm/bin/close.js

@@ -1,117 +0,0 @@
-import { removeLock, isProcessAlive, listSessions, toLockData } from '../session/lock.js';
-import { output } from './cli.js';
-export async function handleClose(sessionName, closeAll) {
-    if (closeAll) {
-        const sessions = listSessions();
-        if (sessions.length === 0) {
-            return output({ error: 'No running browser sessions found.', closed: [], count: 0 }, 1);
-        }
-        // Send SIGTERM to all sessions
-        for (const s of sessions) {
-            try {
-                process.kill(s.pid, 'SIGTERM');
-            }
-            catch {
-                // ignore
-            }
-        }
-        // Wait up to 10 seconds for all processes to exit
-        const maxWait = 40;
-        const alive = new Set(sessions.map((s) => s.pid));
-        for (let i = 0; i < maxWait && alive.size > 0; i++) {
-            await new Promise((r) => setTimeout(r, 250));
-            for (const pid of alive) {
-                if (!isProcessAlive(pid)) {
-                    alive.delete(pid);
-                }
-            }
-        }
-        // Force-kill any survivors
-        for (const pid of alive) {
-            try {
-                process.kill(pid, 'SIGKILL');
-            }
-            catch {
-                // ignore
-            }
-        }
-        // Now remove all locks
-        const closed = [];
-        for (const s of sessions) {
-            removeLock(s.session);
-            closed.push(s.session);
-        }
-        return output({ message: 'All browser sessions closed.', closed, count: closed.length });
-    }
-    // If no session name specified, figure out what to close
-    if (!sessionName) {
-        const sessions = listSessions();
-        if (sessions.length === 0) {
-            return output({ error: 'No running browser sessions found.' }, 1);
-        }
-        if (sessions.length > 1) {
-            return output({
-                error: 'Multiple sessions running. Specify --browser-session <name> or --all.',
-                browserSessions: sessions.map((s) => s.session),
-            }, 1);
-        }
-        // Single session — use its data directly instead of re-reading the lock file
-        const session = sessions[0];
-        sessionName = session.session;
-        return closeSession(sessionName, toLockData(session));
-    }
-    // Session name provided — need to verify it's alive
-    const sessions = listSessions();
-    const match = sessions.find((s) => s.session === sessionName);
-    if (!match) {
-        return output({ browserSession: sessionName, error: 'No running browser session found.' }, 1);
-    }
-    return closeSession(sessionName, toLockData(match));
-}
-async function closeSession(sessionName, lock) {
-    if (!isProcessAlive(lock.pid)) {
-        removeLock(sessionName);
-        return output({
-            browserSession: sessionName,
-            message: 'Browser process was not running. Lock file cleaned up.',
-        });
-    }
-    try {
-        process.kill(lock.pid, 'SIGTERM');
-    }
-    catch (err) {
-        return output({ browserSession: sessionName, error: `Failed to stop process: ${err.message}` }, 1);
-    }
-    // Wait for the process to exit (up to 10 seconds)
-    const maxWait = 40;
-    for (let i = 0; i < maxWait; i++) {
-        await new Promise((r) => setTimeout(r, 250));
-        if (!isProcessAlive(lock.pid)) {
-            removeLock(sessionName);
-            return output({
-                browserSession: sessionName,
-                pid: lock.pid,
-                message: 'Browser session closed.',
-                startUrl: lock.url ?? null,
-                cdpUrl: lock.cdpUrl ?? null,
-                connectionId: lock.connectionId ?? null,
-            });
-        }
-    }
-    // Force kill if still alive
-    try {
-        process.kill(lock.pid, 'SIGKILL');
-    }
-    catch {
-        // ignore
-    }
-    removeLock(sessionName);
-    return output({
-        browserSession: sessionName,
-        pid: lock.pid,
-        message: 'Browser session force-killed.',
-        startUrl: lock.url ?? null,
-        cdpUrl: lock.cdpUrl ?? null,
-        connectionId: lock.connectionId ?? null,
-    });
-}

package/dist/esm/bin/geos.js

@@ -1,7 +0,0 @@
-import { requireApi } from './api-helpers.js';
-import { output } from './cli.js';
-export async function handleGeos() {
-    const api = requireApi();
-    const geos = await api.geos.list();
-    return output({ geos, count: geos.length });
-}

package/dist/esm/bin/mcp-helpers.js

@@ -1,51 +0,0 @@
-/**
- * MCP output capture helpers.
- *
- * The CLI handlers call `output()` which normally does `console.log` + `process.exit()`.
- * In MCP mode, we switch `output()` to throw an MCPOutputCapture instead,
- * allowing us to catch and return the data without exiting the process.
- *
- * Uses AsyncLocalStorage so concurrent MCP tool calls don't interfere.
- */
-import { AsyncLocalStorage } from "node:async_hooks";
-/**
- * Thrown by output() when in capture mode.
- * Contains the JSON data and exit code that would have been written to stdout.
- */
-export class MCPOutputCapture {
-    constructor(data, exitCode) {
-        this.data = data;
-        this.exitCode = exitCode;
-    }
-}
-const captureContext = new AsyncLocalStorage();
-export function isCapturing() {
-    return captureContext.getStore() ?? false;
-}
-/**
- * Run a CLI handler function in capture mode.
- * Returns the data that output() would have written to stdout.
- * Safe for concurrent use — each call gets its own async context.
- */
-export async function captureOutput(fn) {
-    return captureContext.run(true, async () => {
-        try {
-            await fn();
-            // Handler completed without calling output() — shouldn't happen for CLI handlers
-            return { data: { error: "Handler did not produce output" }, isError: true };
-        }
-        catch (err) {
-            if (err instanceof MCPOutputCapture) {
-                return {
-                    data: err.data,
-                    isError: err.exitCode !== 0,
-                };
-            }
-            // Unexpected error (not from output())
-            return {
-                data: { error: err instanceof Error ? err.message : String(err) },
-                isError: true,
-            };
-        }
-    });
-}