@aluvia/sdk 1.1.0 → 1.3.0

package/dist/esm/bin/geos.js

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,51 @@
+/**
+ * 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,
+            };
+        }
+    });
+}

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

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import * as tools from "./mcp-tools.js";
+const server = new McpServer({
+    name: "aluvia",
+    version: "1.2.0",
+});
+// --- Session tools ---
+server.tool("session_start", "Start a browser session with Aluvia smart proxy. Spawns a headless browser connected through Aluvia gateway. Returns session details including CDP URL for remote debugging.", {
+    url: z.string().describe("URL to open in the browser"),
+    connectionId: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Use a specific Aluvia connection ID"),
+    headful: z
+        .boolean()
+        .optional()
+        .describe("Run browser in headful mode (default: headless)"),
+    browserSession: z
+        .string()
+        .optional()
+        .describe("Custom session name (auto-generated if omitted)"),
+    autoUnblock: z
+        .boolean()
+        .optional()
+        .describe("Auto-detect blocks and reload through Aluvia proxy"),
+    disableBlockDetection: z
+        .boolean()
+        .optional()
+        .describe("Disable block detection entirely"),
+}, async (args) => {
+    const result = await tools.sessionStart(args);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+        ],
+        isError: result.isError,
+    };
+});
+server.tool("session_close", "Close one or all running browser sessions. Sends SIGTERM for graceful shutdown, then SIGKILL if needed.", {
+    browserSession: z
+        .string()
+        .optional()
+        .describe("Name of session to close (auto-selects if only one)"),
+    all: z.boolean().optional().describe("Close all sessions"),
+}, async (args) => {
+    const result = await tools.sessionClose(args);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+        ],
+        isError: result.isError,
+    };
+});
+server.tool("session_list", "List all active browser sessions with their PIDs, URLs, and proxy configuration.", async () => {
+    const result = await tools.sessionList();
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+        ],
+        isError: result.isError,
+    };
+});
+server.tool("session_get", "Get detailed information about a running session including proxy URLs, connection data, and block detection state.", {
+    browserSession: z
+        .string()
+        .optional()
+        .describe("Name of session (auto-selects if only one)"),
+}, async (args) => {
+    const result = await tools.sessionGet(args);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+        ],
+        isError: result.isError,
+    };
+});
+server.tool("session_rotate_ip", "Rotate the IP address for a running session by generating a new session ID on the Aluvia connection.", {
+    browserSession: z
+        .string()
+        .optional()
+        .describe("Name of session (auto-selects if only one)"),
+}, async (args) => {
+    const result = await tools.sessionRotateIp(args);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+        ],
+        isError: result.isError,
+    };
+});
+server.tool("session_set_geo", "Set or clear the target geographic region for a running session. Affects which mobile IP pool is used.", {
+    geo: z.string().optional().describe('Geo code to set (e.g. "US", "GB")'),
+    clear: z
+        .boolean()
+        .optional()
+        .describe("Clear the target geo instead of setting one"),
+    browserSession: z
+        .string()
+        .optional()
+        .describe("Name of session (auto-selects if only one)"),
+}, async (args) => {
+    const result = await tools.sessionSetGeo(args);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+        ],
+        isError: result.isError,
+    };
+});
+server.tool("session_set_rules", 'Append or remove proxy routing rules for a running session. Rules are hostname patterns (e.g. "example.com", "*.google.com").', {
+    rules: z
+        .string()
+        .optional()
+        .describe('Comma-separated rules to append (e.g. "a.com,b.com")'),
+    remove: z
+        .string()
+        .optional()
+        .describe("Comma-separated rules to remove instead of appending"),
+    browserSession: z
+        .string()
+        .optional()
+        .describe("Name of session (auto-selects if only one)"),
+}, async (args) => {
+    const result = await tools.sessionSetRules(args);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+        ],
+        isError: result.isError,
+    };
+});
+// --- Account tools ---
+server.tool("account_get", "Get Aluvia account information including plan details and current balance.", async () => {
+    const result = await tools.accountGet();
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+        ],
+        isError: result.isError,
+    };
+});
+server.tool("account_usage", "Get Aluvia account usage statistics for a date range.", {
+    start: z
+        .string()
+        .optional()
+        .describe('Start date filter (ISO8601 format, e.g. "2024-01-01T00:00:00Z")'),
+    end: z.string().optional().describe("End date filter (ISO8601 format)"),
+}, async (args) => {
+    const result = await tools.accountUsage(args);
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+        ],
+        isError: result.isError,
+    };
+});
+// --- Geo tools ---
+server.tool("geos_list", "List all available geographic regions for proxy targeting.", async () => {
+    const result = await tools.geosList();
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+        ],
+        isError: result.isError,
+    };
+});
+// --- Start server ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Aluvia MCP server running on stdio");
+}
+// Only run when executed directly (not when imported for testing)
+const isMcpServer = process.argv[1]?.match(/(?:mcp-server)\.[jt]s$/);
+if (isMcpServer) {
+    main().catch((err) => {
+        console.error("Fatal error in MCP server:", err);
+        process.exit(1);
+    });
+}

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

@@ -0,0 +1,78 @@
+/**
+ * MCP tool implementations.
+ *
+ * Each tool wraps the corresponding CLI handler via captureOutput(),
+ * converting the handler's JSON output into MCP tool results.
+ */
+import { handleSession } from "./session.js";
+import { handleAccount } from "./account.js";
+import { handleGeos } from "./geos.js";
+import { handleOpen } from "./open.js";
+import { captureOutput } from "./mcp-helpers.js";
+export async function sessionStart(args) {
+    return captureOutput(() => handleOpen({
+        url: args.url,
+        connectionId: args.connectionId,
+        headless: !args.headful,
+        sessionName: args.browserSession,
+        autoUnblock: args.autoUnblock,
+        disableBlockDetection: args.disableBlockDetection,
+    }));
+}
+export async function sessionClose(args) {
+    const cliArgs = ["close"];
+    if (args.browserSession)
+        cliArgs.push("--browser-session", args.browserSession);
+    if (args.all)
+        cliArgs.push("--all");
+    return captureOutput(() => handleSession(cliArgs));
+}
+export async function sessionList() {
+    return captureOutput(() => handleSession(["list"]));
+}
+export async function sessionGet(args) {
+    const cliArgs = ["get"];
+    if (args.browserSession)
+        cliArgs.push("--browser-session", args.browserSession);
+    return captureOutput(() => handleSession(cliArgs));
+}
+export async function sessionRotateIp(args) {
+    const cliArgs = ["rotate-ip"];
+    if (args.browserSession)
+        cliArgs.push("--browser-session", args.browserSession);
+    return captureOutput(() => handleSession(cliArgs));
+}
+export async function sessionSetGeo(args) {
+    const cliArgs = ["set-geo"];
+    if (args.geo)
+        cliArgs.push(args.geo);
+    if (args.clear)
+        cliArgs.push("--clear");
+    if (args.browserSession)
+        cliArgs.push("--browser-session", args.browserSession);
+    return captureOutput(() => handleSession(cliArgs));
+}
+export async function sessionSetRules(args) {
+    const cliArgs = ["set-rules"];
+    if (args.rules)
+        cliArgs.push(args.rules);
+    if (args.remove)
+        cliArgs.push("--remove", args.remove);
+    if (args.browserSession)
+        cliArgs.push("--browser-session", args.browserSession);
+    return captureOutput(() => handleSession(cliArgs));
+}
+export async function accountGet() {
+    return captureOutput(() => handleAccount([]));
+}
+export async function accountUsage(args) {
+    const cliArgs = ["usage"];
+    if (args.start)
+        cliArgs.push("--start", args.start);
+    if (args.end)
+        cliArgs.push("--end", args.end);
+    return captureOutput(() => handleAccount(cliArgs));
+}
+export async function geosList() {
+    return captureOutput(() => handleGeos());
+}

package/dist/esm/bin/open.js

@@ -0,0 +1,256 @@
+import { AluviaClient } from '../client/AluviaClient.js';
+import { writeLock, readLock, removeLock, isProcessAlive, getLogFilePath, generateSessionName, validateSessionName } from '../session/lock.js';
+import { output } from './cli.js';
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Called from cli.ts when running `session start <url>`.
+ * Spawns the actual browser in a detached child and polls until ready.
+ * Returns a Promise that resolves via process.exit() (never returns normally).
+ */
+export function handleOpen({ url, connectionId, headless, sessionName, autoUnblock, disableBlockDetection, run }) {
+    // Generate session name if not provided
+    const session = sessionName ?? generateSessionName();
+    // Validate session name early (before spawning daemon)
+    if (sessionName && !validateSessionName(sessionName)) {
+        output({ error: 'Invalid session name. Use only letters, numbers, hyphens, and underscores.' }, 1);
+    }
+    // Check for existing instance with this session name
+    const existing = readLock(session);
+    if (existing !== null && isProcessAlive(existing.pid)) {
+        output({
+            error: `A browser session named '${session}' is already running.`,
+            browserSession: session,
+            startUrl: existing.url ?? null,
+            cdpUrl: existing.cdpUrl ?? null,
+            connectionId: existing.connectionId ?? null,
+            pid: existing.pid,
+        }, 1);
+    }
+    // Clean up stale lock if process is dead
+    if (existing !== null) {
+        removeLock(session);
+    }
+    // Require API key
+    const apiKey = process.env.ALUVIA_API_KEY;
+    if (!apiKey) {
+        output({ error: 'ALUVIA_API_KEY environment variable is required.' }, 1);
+    }
+    // Spawn a detached child process that runs the daemon
+    const logFile = getLogFilePath(session);
+    const out = fs.openSync(logFile, 'a');
+    const args = ['--daemon', url, '--browser-session', session];
+    if (connectionId != null) {
+        args.push('--connection-id', String(connectionId));
+    }
+    if (!headless) {
+        args.push('--headful');
+    }
+    if (autoUnblock) {
+        args.push('--auto-unblock');
+    }
+    if (disableBlockDetection) {
+        args.push('--disable-block-detection');
+    }
+    if (run) {
+        args.push('--run', run);
+    }
+    let child;
+    try {
+        child = spawn(process.execPath, [process.argv[1], ...args], {
+            detached: true,
+            stdio: ['ignore', out, out],
+            env: { ...process.env, ALUVIA_API_KEY: apiKey },
+        });
+        child.unref();
+    }
+    catch (err) {
+        fs.closeSync(out);
+        return output({ browserSession: session, error: `Failed to spawn browser process: ${err.message}` }, 1);
+    }
+    fs.closeSync(out);
+    // Wait for the daemon to be fully ready (lock file with ready: true)
+    return new Promise(() => {
+        let attempts = 0;
+        const maxAttempts = 240; // 60 seconds max
+        const poll = setInterval(() => {
+            attempts++;
+            // Early exit if daemon process died
+            if (child.pid && !isProcessAlive(child.pid)) {
+                clearInterval(poll);
+                removeLock(session);
+                output({
+                    browserSession: session,
+                    error: 'Browser process exited unexpectedly.',
+                    logFile,
+                }, 1);
+            }
+            const lock = readLock(session);
+            if (lock && lock.ready) {
+                clearInterval(poll);
+                output({
+                    browserSession: session,
+                    pid: lock.pid,
+                    startUrl: lock.url ?? null,
+                    cdpUrl: lock.cdpUrl ?? null,
+                    connectionId: lock.connectionId ?? null,
+                    blockDetection: lock.blockDetection ?? false,
+                    autoUnblock: lock.autoUnblock ?? false,
+                });
+            }
+            if (attempts >= maxAttempts) {
+                clearInterval(poll);
+                const alive = child.pid ? isProcessAlive(child.pid) : false;
+                output({
+                    browserSession: session,
+                    error: alive ? 'Browser is still initializing (timeout).' : 'Browser process exited unexpectedly.',
+                    logFile,
+                }, 1);
+            }
+        }, 250);
+    });
+}
+/**
+ * Daemon entry point — runs in the detached child process.
+ * Starts the proxy + browser, writes lock, and stays alive.
+ * Logs go to the daemon log file (stdout is redirected), not to the user.
+ */
+export async function handleOpenDaemon({ url, connectionId, headless, sessionName, autoUnblock, disableBlockDetection, run }) {
+    const apiKey = process.env.ALUVIA_API_KEY;
+    const blockDetectionEnabled = !disableBlockDetection;
+    const updateLockWithDetection = (result) => {
+        const lock = readLock(sessionName);
+        if (!lock)
+            return;
+        const lastDetection = {
+            hostname: result.hostname,
+            lastUrl: result.url,
+            blockStatus: result.blockStatus,
+            score: result.score,
+            signals: result.signals.map((s) => s.name),
+            pass: result.pass,
+            persistentBlock: result.persistentBlock,
+            timestamp: Date.now(),
+        };
+        writeLock({ ...lock, lastDetection }, sessionName);
+    };
+    const client = new AluviaClient({
+        apiKey,
+        startPlaywright: true,
+        ...(connectionId != null ? { connectionId } : {}),
+        headless: headless ?? true,
+        blockDetection: blockDetectionEnabled
+            ? autoUnblock
+                ? { enabled: true, autoUnblock: true, onDetection: updateLockWithDetection }
+                : { enabled: true, onDetection: updateLockWithDetection }
+            : { enabled: false },
+    });
+    const connection = await client.start();
+    // Write early lock so parent knows daemon is alive
+    writeLock({ pid: process.pid, session: sessionName, url, proxyUrl: connection.url, blockDetection: blockDetectionEnabled, autoUnblock: blockDetectionEnabled && !!autoUnblock }, sessionName);
+    if (autoUnblock)
+        console.log('[daemon] Auto-unblock enabled');
+    console.log(`[daemon] Browser initialized — proxy: ${connection.url}`);
+    if (connection.cdpUrl)
+        console.log(`[daemon] CDP URL: ${connection.cdpUrl}`);
+    if (connectionId != null)
+        console.log(`[daemon] Connection ID: ${connectionId}`);
+    if (sessionName)
+        console.log(`[daemon] Session: ${sessionName}`);
+    console.log(`[daemon] Opening ${url}`);
+    // Navigate to URL in the browser
+    const page = await connection.browserContext.newPage();
+    await page.goto(url, { waitUntil: 'domcontentloaded' });
+    // Gather session info
+    const pageTitle = await page.title().catch(() => '');
+    const cdpUrl = connection.cdpUrl ?? '';
+    // Get connection ID: use the one passed in, or read from ConfigManager
+    const connId = connectionId ?? client.connectionId;
+    // Write lock file with full session metadata (marks session as ready)
+    // Read existing lock first to preserve lastDetection written by the onDetection callback
+    const existingLock = readLock(sessionName);
+    writeLock({
+        pid: process.pid,
+        session: sessionName,
+        connectionId: connId,
+        cdpUrl,
+        proxyUrl: connection.url,
+        url,
+        ready: true,
+        blockDetection: blockDetectionEnabled,
+        autoUnblock: blockDetectionEnabled && !!autoUnblock,
+        lastDetection: existingLock?.lastDetection,
+    }, sessionName);
+    console.log(`[daemon] Session ready — session: ${sessionName ?? 'default'}, url: ${url}, cdpUrl: ${cdpUrl}, connectionId: ${connId ?? 'unknown'}, pid: ${process.pid}`);
+    if (pageTitle)
+        console.log(`[daemon] Page title: ${pageTitle}`);
+    // If --run was provided, execute the script and then shut down
+    if (run) {
+        const scriptPath = path.resolve(run);
+        if (!fs.existsSync(scriptPath)) {
+            console.error(`[daemon] Script not found: ${scriptPath}`);
+            removeLock(sessionName);
+            await connection.close();
+            process.exit(1);
+        }
+        console.log(`[daemon] Running script: ${scriptPath}`);
+        // Inject page, browser, context as globals so the script can use them directly
+        const browser = connection.browser;
+        const context = connection.browserContext;
+        globalThis.page = page;
+        globalThis.browser = browser;
+        globalThis.context = context;
+        let exitCode = 0;
+        try {
+            await import(pathToFileURL(scriptPath).href);
+        }
+        catch (err) {
+            console.error(`[daemon] Script error: ${err.message}`);
+            if (err.stack)
+                console.error(err.stack);
+            exitCode = 1;
+        }
+        // Clean up globals
+        delete globalThis.page;
+        delete globalThis.browser;
+        delete globalThis.context;
+        console.log(`[daemon] Script finished.`);
+        removeLock(sessionName);
+        await connection.close();
+        process.exit(exitCode);
+    }
+    // Graceful shutdown handler
+    let stopping = false;
+    const shutdown = async () => {
+        if (stopping)
+            return;
+        stopping = true;
+        console.log('[daemon] Shutting down...');
+        try {
+            await connection.close();
+        }
+        catch {
+            // ignore
+        }
+        removeLock(sessionName);
+        console.log('[daemon] Stopped.');
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    // Detect when the browser is closed by the user
+    if (connection.browser) {
+        connection.browser.on('disconnected', () => {
+            if (!stopping) {
+                console.log('[daemon] Browser closed by user.');
+                removeLock(sessionName);
+                client
+                    .stop()
+                    .catch(() => { })
+                    .finally(() => process.exit(0));
+            }
+        });
+    }
+}