@aluvia/sdk 1.1.0 → 1.3.0

package/dist/cjs/api/account.js

@@ -2,75 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAccountApi = createAccountApi;
 const errors_js_1 = require("../errors.js");
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
-function asErrorEnvelope(value) {
-    if (!isRecord(value))
-        return null;
-    if (value['success'] !== false)
-        return null;
-    const error = value['error'];
-    if (!isRecord(error))
-        return null;
-    const code = error['code'];
-    const message = error['message'];
-    if (typeof code !== 'string' || typeof message !== 'string')
-        return null;
-    return { success: false, error: { code, message, details: error['details'] } };
-}
-function unwrapSuccess(value) {
-    if (!isRecord(value))
-        return null;
-    if (value['success'] === true && 'data' in value) {
-        return value.data;
-    }
-    if ('data' in value) {
-        return value.data;
-    }
-    return null;
-}
-function formatErrorDetails(details) {
-    if (details == null)
-        return '';
-    try {
-        const json = JSON.stringify(details);
-        if (!json)
-            return '';
-        return json.length > 500 ? `${json.slice(0, 500)}…` : json;
-    }
-    catch {
-        return String(details);
-    }
-}
-function throwForNon2xx(result) {
-    const status = result.status;
-    if (status === 401 || status === 403) {
-        throw new errors_js_1.InvalidApiKeyError(`Authentication failed (HTTP ${status}). Check token validity and that you are using an account API token for account endpoints.`);
-    }
-    const maybeError = asErrorEnvelope(result.body);
-    if (maybeError) {
-        const details = formatErrorDetails(maybeError.error.details);
-        const detailsSuffix = details ? ` details=${details}` : '';
-        throw new errors_js_1.ApiError(`API request failed (HTTP ${status}) code=${maybeError.error.code} message=${maybeError.error.message}${detailsSuffix}`, status);
-    }
-    throw new errors_js_1.ApiError(`API request failed (HTTP ${status})`, status);
-}
-async function requestAndUnwrap(ctx, args) {
-    const result = await ctx.request(args);
-    if (result.status < 200 || result.status >= 300) {
-        throwForNon2xx(result);
-    }
-    const data = unwrapSuccess(result.body);
-    if (data == null) {
-        throw new errors_js_1.ApiError('API response missing expected success envelope data', result.status);
-    }
-    return { data, etag: result.etag };
-}
+const apiUtils_js_1 = require("./apiUtils.js");
 function createAccountApi(ctx) {
     return {
         get: async () => {
-            const { data } = await requestAndUnwrap(ctx, {
+            const { data } = await (0, apiUtils_js_1.requestAndUnwrap)(ctx, {
                 method: 'GET',
                 path: '/account',
             });
@@ -78,7 +14,7 @@ function createAccountApi(ctx) {
         },
         usage: {
             get: async (params = {}) => {
-                const { data } = await requestAndUnwrap(ctx, {
+                const { data } = await (0, apiUtils_js_1.requestAndUnwrap)(ctx, {
                     method: 'GET',
                     path: '/account/usage',
                     query: {
@@ -91,7 +27,7 @@ function createAccountApi(ctx) {
         },
         payments: {
             list: async (params = {}) => {
-                const { data } = await requestAndUnwrap(ctx, {
+                const { data } = await (0, apiUtils_js_1.requestAndUnwrap)(ctx, {
                     method: 'GET',
                     path: '/account/payments',
                     query: {
@@ -104,14 +40,14 @@ function createAccountApi(ctx) {
         },
         connections: {
             list: async () => {
-                const { data } = await requestAndUnwrap(ctx, {
+                const { data } = await (0, apiUtils_js_1.requestAndUnwrap)(ctx, {
                     method: 'GET',
                     path: '/account/connections',
                 });
                 return data;
             },
             create: async (body) => {
-                const { data } = await requestAndUnwrap(ctx, {
+                const { data } = await (0, apiUtils_js_1.requestAndUnwrap)(ctx, {
                     method: 'POST',
                     path: '/account/connections',
                     body,
@@ -127,16 +63,16 @@ function createAccountApi(ctx) {
                 if (result.status === 304)
                     return null;
                 if (result.status < 200 || result.status >= 300) {
-                    throwForNon2xx(result);
+                    (0, apiUtils_js_1.throwForNon2xx)(result);
                 }
-                const data = unwrapSuccess(result.body);
+                const data = (0, apiUtils_js_1.unwrapSuccess)(result.body);
                 if (data == null) {
                     throw new errors_js_1.ApiError('API response missing expected success envelope data', result.status);
                 }
                 return data;
             },
             patch: async (connectionId, body) => {
-                const { data } = await requestAndUnwrap(ctx, {
+                const { data } = await (0, apiUtils_js_1.requestAndUnwrap)(ctx, {
                     method: 'PATCH',
                     path: `/account/connections/${String(connectionId)}`,
                     body,
@@ -144,7 +80,7 @@ function createAccountApi(ctx) {
                 return data;
             },
             delete: async (connectionId) => {
-                const { data } = await requestAndUnwrap(ctx, {
+                const { data } = await (0, apiUtils_js_1.requestAndUnwrap)(ctx, {
                     method: 'DELETE',
                     path: `/account/connections/${String(connectionId)}`,
                 });

package/dist/cjs/api/apiUtils.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRecord = isRecord;
+exports.asErrorEnvelope = asErrorEnvelope;
+exports.formatErrorDetails = formatErrorDetails;
+exports.throwForNon2xx = throwForNon2xx;
+exports.throwIfAuthError = throwIfAuthError;
+exports.unwrapSuccess = unwrapSuccess;
+exports.requestAndUnwrap = requestAndUnwrap;
+const errors_js_1 = require("../errors.js");
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asErrorEnvelope(value) {
+    if (!isRecord(value))
+        return null;
+    if (value['success'] !== false)
+        return null;
+    const error = value['error'];
+    if (!isRecord(error))
+        return null;
+    const code = error['code'];
+    const message = error['message'];
+    if (typeof code !== 'string' || typeof message !== 'string')
+        return null;
+    return { success: false, error: { code, message, details: error['details'] } };
+}
+function formatErrorDetails(details) {
+    if (details == null)
+        return '';
+    try {
+        const json = JSON.stringify(details);
+        if (!json)
+            return '';
+        return json.length > 500 ? `${json.slice(0, 500)}…` : json;
+    }
+    catch {
+        return String(details);
+    }
+}
+function throwForNon2xx(result) {
+    const status = result.status;
+    if (status === 401 || status === 403) {
+        throw new errors_js_1.InvalidApiKeyError(`Authentication failed (HTTP ${status}). Check token validity and that you are using an account API token for account endpoints.`);
+    }
+    const maybeError = asErrorEnvelope(result.body);
+    if (maybeError) {
+        const details = formatErrorDetails(maybeError.error.details);
+        const detailsSuffix = details ? ` details=${details}` : '';
+        throw new errors_js_1.ApiError(`API request failed (HTTP ${status}) code=${maybeError.error.code} message=${maybeError.error.message}${detailsSuffix}`, status);
+    }
+    throw new errors_js_1.ApiError(`API request failed (HTTP ${status})`, status);
+}
+function throwIfAuthError(status) {
+    if (status === 401 || status === 403) {
+        throw new errors_js_1.InvalidApiKeyError(`Authentication failed with status ${status}`);
+    }
+}
+function unwrapSuccess(value) {
+    if (!isRecord(value))
+        return null;
+    if (value['success'] === true && 'data' in value) {
+        return value.data;
+    }
+    if ('data' in value) {
+        return value.data;
+    }
+    return null;
+}
+async function requestAndUnwrap(ctx, args) {
+    const result = await ctx.request(args);
+    if (result.status < 200 || result.status >= 300) {
+        throwForNon2xx(result);
+    }
+    const data = unwrapSuccess(result.body);
+    if (data == null) {
+        throw new errors_js_1.ApiError('API response missing expected success envelope data', result.status);
+    }
+    return { data, etag: result.etag };
+}

package/dist/cjs/api/geos.js

@@ -1,75 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createGeosApi = createGeosApi;
-const errors_js_1 = require("../errors.js");
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
-function asErrorEnvelope(value) {
-    if (!isRecord(value))
-        return null;
-    if (value['success'] !== false)
-        return null;
-    const error = value['error'];
-    if (!isRecord(error))
-        return null;
-    const code = error['code'];
-    const message = error['message'];
-    if (typeof code !== 'string' || typeof message !== 'string')
-        return null;
-    return { success: false, error: { code, message, details: error['details'] } };
-}
-function formatErrorDetails(details) {
-    if (details == null)
-        return '';
-    try {
-        const json = JSON.stringify(details);
-        if (!json)
-            return '';
-        return json.length > 500 ? `${json.slice(0, 500)}…` : json;
-    }
-    catch {
-        return String(details);
-    }
-}
-function unwrapSuccessArray(value) {
-    if (!isRecord(value))
-        return null;
-    if (value['success'] === true && Array.isArray(value.data)) {
-        return value.data;
-    }
-    if (Array.isArray(value.data)) {
-        return value.data;
-    }
-    return null;
-}
-function throwForNon2xx(result) {
-    const status = result.status;
-    if (status === 401 || status === 403) {
-        throw new errors_js_1.InvalidApiKeyError(`Authentication failed (HTTP ${status}). Check token validity and that you are using an account API token for account endpoints.`);
-    }
-    const maybeError = asErrorEnvelope(result.body);
-    if (maybeError) {
-        const details = formatErrorDetails(maybeError.error.details);
-        const detailsSuffix = details ? ` details=${details}` : '';
-        throw new errors_js_1.ApiError(`API request failed (HTTP ${status}) code=${maybeError.error.code} message=${maybeError.error.message}${detailsSuffix}`, status);
-    }
-    throw new errors_js_1.ApiError(`API request failed (HTTP ${status})`, status);
-}
+const apiUtils_js_1 = require("./apiUtils.js");
 function createGeosApi(ctx) {
     return {
         list: async () => {
-            const result = await ctx.request({
+            const { data } = await (0, apiUtils_js_1.requestAndUnwrap)(ctx, {
                 method: 'GET',
                 path: '/geos',
             });
-            if (result.status < 200 || result.status >= 300) {
-                throwForNon2xx(result);
-            }
-            const data = unwrapSuccessArray(result.body);
-            if (data == null) {
-                throw new errors_js_1.ApiError('API response missing expected success envelope data', result.status);
-            }
             return data;
         },
     };

package/dist/cjs/api/request.js

@@ -63,7 +63,8 @@ async function requestCore(options) {
             if (controller.signal.aborted) {
                 throw new errors_js_1.ApiError(`Request timed out after ${timeoutMs}ms`, 408);
             }
-            throw err;
+            const message = err instanceof Error ? err.message : String(err);
+            throw new errors_js_1.ApiError(`Network request failed: ${message}`);
         }
         const etag = response.headers.get('etag');
         if (response.status === 204 || response.status === 304) {
@@ -76,7 +77,12 @@ async function requestCore(options) {
         const text = await response.text();
         if (!text)
             return { status: response.status, etag, body: null };
-        return { status: response.status, etag, body: JSON.parse(text) };
+        try {
+            return { status: response.status, etag, body: JSON.parse(text) };
+        }
+        catch {
+            return { status: response.status, etag, body: null };
+        }
     }
     finally {
         clearTimeout(timeoutId);

package/dist/cjs/bin/account.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAccount = handleAccount;
+const api_helpers_js_1 = require("./api-helpers.js");
+const cli_js_1 = require("./cli.js");
+async function handleAccount(args) {
+    const subcommand = args[0];
+    if (!subcommand) {
+        const api = (0, api_helpers_js_1.requireApi)();
+        const account = await api.account.get();
+        return (0, cli_js_1.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 = (0, api_helpers_js_1.requireApi)();
+        const usage = await api.account.usage.get({ start, end });
+        return (0, cli_js_1.output)({ usage });
+    }
+    return (0, cli_js_1.output)({ error: `Unknown account subcommand: '${subcommand}'.` }, 1);
+}

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

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireApi = requireApi;
+exports.resolveSession = resolveSession;
+exports.requireConnectionId = requireConnectionId;
+const AluviaApi_js_1 = require("../api/AluviaApi.js");
+const lock_js_1 = require("../session/lock.js");
+const cli_js_1 = require("./cli.js");
+/**
+ * Create an AluviaApi instance from ALUVIA_API_KEY env var.
+ * Calls output() and exits if the key is missing.
+ */
+function requireApi() {
+    const apiKey = (process.env.ALUVIA_API_KEY ?? '').trim();
+    if (!apiKey) {
+        return (0, cli_js_1.output)({ error: 'ALUVIA_API_KEY environment variable is required.' }, 1);
+    }
+    return new AluviaApi_js_1.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).
+ */
+function resolveSession(sessionName) {
+    if (sessionName) {
+        const lock = (0, lock_js_1.readLock)(sessionName);
+        if (!lock) {
+            return (0, cli_js_1.output)({ error: `No session found with name '${sessionName}'.` }, 1);
+        }
+        if (!(0, lock_js_1.isProcessAlive)(lock.pid)) {
+            (0, lock_js_1.removeLock)(sessionName);
+            return (0, cli_js_1.output)({ error: `Session '${sessionName}' is no longer running (stale lock cleaned up).` }, 1);
+        }
+        return { session: sessionName, lock };
+    }
+    const sessions = (0, lock_js_1.listSessions)();
+    if (sessions.length === 0) {
+        return (0, cli_js_1.output)({ error: 'No running browser sessions found.' }, 1);
+    }
+    if (sessions.length > 1) {
+        return (0, cli_js_1.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: (0, lock_js_1.toLockData)(s) };
+}
+/**
+ * Require a connection ID from lock data.
+ * Calls output() and exits if connectionId is missing.
+ */
+function requireConnectionId(lock, session) {
+    if (lock.connectionId == null) {
+        return (0, cli_js_1.output)({ error: `Session '${session}' has no connection ID. It may have been started without API access.` }, 1);
+    }
+    return lock.connectionId;
+}

package/dist/cjs/bin/cli.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.output = output;
+const open_js_1 = require("./open.js");
+const session_js_1 = require("./session.js");
+const account_js_1 = require("./account.js");
+const geos_js_1 = require("./geos.js");
+const lock_js_1 = require("../session/lock.js");
+const mcp_helpers_js_1 = require("./mcp-helpers.js");
+function output(data, exitCode = 0) {
+    if ((0, mcp_helpers_js_1.isCapturing)()) {
+        throw new mcp_helpers_js_1.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 (0, session_js_1.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 && !(0, lock_js_1.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 (0, open_js_1.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 (0, session_js_1.handleSession)(args.slice(1));
+    }
+    else if (command === "account") {
+        if (wantsHelp)
+            printHelpAndExit(args);
+        await (0, account_js_1.handleAccount)(args.slice(1));
+    }
+    else if (command === "geos") {
+        if (wantsHelp)
+            printHelpAndExit(args);
+        await (0, geos_js_1.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);
+    });
+}