@aluvia/sdk 1.1.0 → 1.3.0

package/dist/esm/client/PageLoadDetection.js

@@ -0,0 +1,171 @@
+// PageLoadDetection - Enhanced page load and blocking detection
+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
+ */
+export 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;
+        }
+    }
+}

package/dist/esm/client/ProxyServer.js

@@ -2,7 +2,7 @@
 import { Server as ProxyChainServer } from 'proxy-chain';
 import { Logger } from './logger.js';
 import { ProxyStartError } from '../errors.js';
-import { shouldProxy } from './rules.js';
+import { shouldProxy, shouldProxyNormalized } from './rules.js';
 /**
  * ProxyServer manages the local HTTP(S) proxy that routes traffic
  * through Aluvia or directly based on rules.
@@ -94,8 +94,10 @@ export class ProxyServer {
             this.logger.debug('Could not extract hostname, going direct');
             return undefined;
         }
-        // Check if we should proxy this hostname
-        const useProxy = shouldProxy(hostname, config.rules);
+        // Check if we should proxy this hostname (use pre-normalized rules if available)
+        const useProxy = config.normalizedRules
+            ? shouldProxyNormalized(hostname, config.normalizedRules)
+            : shouldProxy(hostname, config.rules);
         if (!useProxy) {
             this.logger.debug(`Hostname ${hostname} bypassing proxy (direct)`);
             return undefined;

package/dist/esm/client/logger.js

@@ -29,6 +29,10 @@ export class Logger {
             console.debug('[aluvia][debug]', ...args);
         }
     }
+    /** Check if debug logging is enabled. */
+    get isDebug() {
+        return this.level === 'debug';
+    }
     /**
      * Log warning messages.
      * Logs when level is not 'silent'.

package/dist/esm/client/rules.js

@@ -51,48 +51,26 @@ export function matchPattern(hostname, pattern) {
     return false;
 }
 /**
- * Determine if a hostname should be proxied based on rules.
- *
- * Rules semantics:
- * - [] (empty) → no proxy (return false)
- * - ['*'] → proxy everything
- * - ['example.com'] → proxy only example.com
- * - ['*.google.com'] → proxy subdomains of google.com
- * - ['*', '-example.com'] → proxy everything except example.com
- * - ['AUTO', 'example.com'] → AUTO is placeholder (ignored), proxy example.com
- *
- * Negative patterns (prefixed with '-') exclude hosts from proxying.
- * If '*' is in rules, default is to proxy unless excluded.
- * Without '*', only explicitly matched patterns are proxied.
- *
- * @param hostname - The hostname to check
- * @param rules - Array of rule patterns
- * @returns true if the hostname should be proxied
+ * Pre-process raw rule strings into a NormalizedRules structure.
+ * Call once when config is loaded, then use shouldProxyNormalized() per request.
  */
-export function shouldProxy(hostname, rules) {
-    const normalizedHostname = hostname.trim();
-    if (!normalizedHostname)
-        return false;
-    // Empty rules means no proxy
+export function normalizeRules(rules) {
     if (!rules || rules.length === 0) {
-        return false;
+        return { positiveRules: [], negativeRules: [], hasCatchAll: false, empty: true };
     }
-    const normalizedRules = rules
+    const trimmed = rules
         .filter((r) => typeof r === 'string')
-        .map((r) => r.trim())
-        .filter((r) => r.length > 0);
-    // Filter out AUTO placeholder
-    const effectiveRules = normalizedRules.filter((r) => r.toUpperCase() !== 'AUTO');
-    // If no effective rules after filtering, no proxy
-    if (effectiveRules.length === 0) {
-        return false;
+        .map((r) => r.trim().toLowerCase())
+        .filter((r) => r.length > 0)
+        .filter((r) => r !== 'auto');
+    if (trimmed.length === 0) {
+        return { positiveRules: [], negativeRules: [], hasCatchAll: false, empty: true };
     }
-    // Separate positive and negative rules
     const negativeRules = [];
     const positiveRules = [];
-    for (const rule of effectiveRules) {
+    for (const rule of trimmed) {
         if (rule.startsWith('-')) {
-            const neg = rule.slice(1).trim(); // Remove the '-' prefix
+            const neg = rule.slice(1).trim();
             if (neg.length > 0)
                 negativeRules.push(neg);
         }
@@ -100,25 +78,34 @@ export function shouldProxy(hostname, rules) {
             positiveRules.push(rule);
         }
     }
-    // Check if hostname matches any negative rule
-    for (const negRule of negativeRules) {
-        if (matchPattern(normalizedHostname, negRule)) {
-            // Excluded by negative rule
+    return {
+        positiveRules,
+        negativeRules,
+        hasCatchAll: positiveRules.includes('*'),
+        empty: false,
+    };
+}
+/**
+ * Fast proxy decision using pre-normalized rules.
+ */
+export function shouldProxyNormalized(hostname, rules) {
+    const normalizedHostname = hostname.trim().toLowerCase();
+    if (!normalizedHostname)
+        return false;
+    if (rules.empty)
+        return false;
+    for (const negRule of rules.negativeRules) {
+        if (matchPattern(normalizedHostname, negRule))
             return false;
-        }
     }
-    // Check if we have a catch-all '*'
-    const hasCatchAll = positiveRules.includes('*');
-    if (hasCatchAll) {
-        // With catch-all, proxy everything not excluded by negative rules
+    if (rules.hasCatchAll)
         return true;
-    }
-    // Without catch-all, check if hostname matches any positive rule
-    for (const posRule of positiveRules) {
-        if (matchPattern(normalizedHostname, posRule)) {
+    for (const posRule of rules.positiveRules) {
+        if (matchPattern(normalizedHostname, posRule))
             return true;
-        }
     }
-    // No match found
     return false;
 }
+export function shouldProxy(hostname, rules) {
+    return shouldProxyNormalized(hostname, normalizeRules(rules));
+}

package/dist/esm/connect.js

@@ -0,0 +1,81 @@
+import { readLock, listSessions, isProcessAlive, removeLock } from './session/lock.js';
+import { ConnectError } from './errors.js';
+/**
+ * Connect to a running Aluvia browser session via CDP.
+ *
+ * - No args: auto-discovers a single running session.
+ * - With session name: connects to that specific session.
+ *
+ * Requires `playwright` as a peer dependency.
+ */
+export async function connect(sessionName) {
+    // 1. Import Playwright
+    let pw;
+    try {
+        pw = await import('playwright');
+    }
+    catch {
+        throw new ConnectError('Playwright is required for connect(). Install it: npm install playwright');
+    }
+    // 2. Resolve session
+    let resolvedName;
+    if (sessionName) {
+        resolvedName = sessionName;
+    }
+    else {
+        const sessions = listSessions();
+        if (sessions.length === 0) {
+            throw new ConnectError('No running Aluvia sessions found. Start one with: npx aluvia-sdk session start <url>');
+        }
+        if (sessions.length > 1) {
+            const names = sessions.map((s) => s.session).join(', ');
+            throw new ConnectError(`Multiple Aluvia sessions running (${names}). Specify which one: connect('${sessions[0].session}')`);
+        }
+        resolvedName = sessions[0].session;
+    }
+    // 3. Validate session state
+    const lock = readLock(resolvedName);
+    if (!lock) {
+        throw new ConnectError(`No Aluvia session found named '${resolvedName}'. Run 'npx aluvia-sdk session list' to list sessions.`);
+    }
+    if (!isProcessAlive(lock.pid)) {
+        removeLock(resolvedName);
+        throw new ConnectError(`Session '${resolvedName}' is no longer running. Stale lock file removed.`);
+    }
+    if (!lock.ready) {
+        throw new ConnectError(`Session '${resolvedName}' is still starting up. Try again shortly.`);
+    }
+    if (!lock.cdpUrl) {
+        throw new ConnectError(`Session '${resolvedName}' has no CDP URL.`);
+    }
+    // 4. Connect over CDP
+    let browser;
+    try {
+        browser = await pw.chromium.connectOverCDP(lock.cdpUrl);
+    }
+    catch (err) {
+        throw new ConnectError(`Failed to connect to session '${resolvedName}' at ${lock.cdpUrl}: ${err.message}`);
+    }
+    // 5. Get context and page
+    let context;
+    let page;
+    try {
+        context = browser.contexts()[0] ?? await browser.newContext();
+        page = context.pages()[0] ?? await context.newPage();
+    }
+    catch (err) {
+        await browser.close().catch(() => { });
+        throw new ConnectError(`Connected but failed to get page: ${err.message}`);
+    }
+    return {
+        browser,
+        context,
+        page,
+        sessionName: resolvedName,
+        cdpUrl: lock.cdpUrl,
+        connectionId: lock.connectionId,
+        disconnect: async () => {
+            await browser.close();
+        },
+    };
+}

package/dist/esm/errors.js

@@ -40,3 +40,13 @@ export class ProxyStartError extends Error {
         Object.setPrototypeOf(this, ProxyStartError.prototype);
     }
 }
+/**
+ * Thrown by connect() when it cannot establish a CDP connection to a running session.
+ */
+export class ConnectError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConnectError';
+        Object.setPrototypeOf(this, ConnectError.prototype);
+    }
+}

package/dist/esm/index.js

@@ -1,7 +1,9 @@
 // Aluvia Client Node
 // Main entry point
 // Public class
-export { AluviaClient } from './client/AluviaClient.js';
-export { AluviaApi } from './api/AluviaApi.js';
+export { AluviaClient } from "./client/AluviaClient.js";
+export { AluviaApi } from "./api/AluviaApi.js";
+// Connect helper
+export { connect } from "./connect.js";
 // Public error classes
-export { MissingApiKeyError, InvalidApiKeyError, ApiError, ProxyStartError, } from './errors.js';
+export { MissingApiKeyError, InvalidApiKeyError, ApiError, ProxyStartError, ConnectError, } from "./errors.js";

package/dist/esm/session/lock.js

@@ -0,0 +1,142 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+const LOCK_DIR = path.join(os.tmpdir(), 'aluvia-sdk');
+const ADJECTIVES = [
+    'swift', 'bold', 'calm', 'keen', 'warm', 'bright', 'silent', 'rapid', 'steady', 'clever',
+    'vivid', 'agile', 'noble', 'lucid', 'crisp', 'gentle', 'fierce', 'nimble', 'sturdy', 'witty',
+];
+const NOUNS = [
+    'falcon', 'tiger', 'river', 'maple', 'coral', 'cedar', 'orbit', 'prism', 'flint', 'spark',
+    'ridge', 'ember', 'crane', 'grove', 'stone', 'brook', 'drift', 'crest', 'sage', 'lynx',
+];
+function lockFileName(sessionName) {
+    return `cli-${sessionName ?? 'default'}.lock`;
+}
+function logFileName(sessionName) {
+    return `cli-${sessionName ?? 'default'}.log`;
+}
+export function writeLock(data, sessionName) {
+    fs.mkdirSync(LOCK_DIR, { recursive: true });
+    const filePath = path.join(LOCK_DIR, lockFileName(sessionName));
+    const tmpPath = filePath + '.tmp';
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(data), 'utf-8');
+        try {
+            // On Windows, rename may fail to overwrite an existing file; remove it first.
+            fs.rmSync(filePath, { force: true });
+        }
+        catch {
+            // Ignore errors removing the existing lock file.
+        }
+        fs.renameSync(tmpPath, filePath);
+    }
+    finally {
+        try {
+            // Ensure no leftover temp file remains if rename fails.
+            fs.rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // Ignore cleanup errors.
+        }
+    }
+}
+export function readLock(sessionName) {
+    try {
+        const filePath = path.join(LOCK_DIR, lockFileName(sessionName));
+        const raw = fs.readFileSync(filePath, 'utf-8').trim();
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid === 'number' && Number.isFinite(parsed.pid)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function removeLock(sessionName) {
+    try {
+        const filePath = path.join(LOCK_DIR, lockFileName(sessionName));
+        fs.unlinkSync(filePath);
+    }
+    catch {
+        // ignore
+    }
+}
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0); // signal 0 = check existence
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function getLogFilePath(sessionName) {
+    fs.mkdirSync(LOCK_DIR, { recursive: true });
+    return path.join(LOCK_DIR, logFileName(sessionName));
+}
+export function validateSessionName(name) {
+    return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+export function generateSessionName() {
+    const maxAttempts = 10;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+        const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+        const name = attempt === 0 ? `${adj}-${noun}` : `${adj}-${noun}-${attempt}`;
+        const filePath = path.join(LOCK_DIR, lockFileName(name));
+        if (!fs.existsSync(filePath)) {
+            return name;
+        }
+        // Lock file exists — check if the process is still alive
+        const lock = readLock(name);
+        if (!lock || !isProcessAlive(lock.pid)) {
+            // Stale lock, we can reuse this name
+            removeLock(name);
+            return name;
+        }
+    }
+    // Fallback: use timestamp
+    return `session-${Date.now()}`;
+}
+export function toLockData(info) {
+    const { session: _session, ...lock } = info;
+    return lock;
+}
+export function listSessions() {
+    fs.mkdirSync(LOCK_DIR, { recursive: true });
+    const files = fs.readdirSync(LOCK_DIR);
+    const sessions = [];
+    for (const file of files) {
+        const match = file.match(/^cli-(.+)\.lock$/);
+        if (!match)
+            continue;
+        const sessionName = match[1];
+        const lock = readLock(sessionName);
+        if (!lock) {
+            // Corrupt lock file, clean up
+            removeLock(sessionName);
+            continue;
+        }
+        if (!isProcessAlive(lock.pid)) {
+            // Stale lock, clean up
+            removeLock(sessionName);
+            continue;
+        }
+        sessions.push({
+            session: sessionName,
+            pid: lock.pid,
+            connectionId: lock.connectionId,
+            cdpUrl: lock.cdpUrl,
+            proxyUrl: lock.proxyUrl,
+            url: lock.url,
+            ready: lock.ready,
+            blockDetection: lock.blockDetection,
+            autoUnblock: lock.autoUnblock,
+            lastDetection: lock.lastDetection,
+        });
+    }
+    return sessions;
+}

package/dist/types/api/AluviaApi.d.ts

@@ -1,18 +1,13 @@
 import { createAccountApi } from './account.js';
 import { createGeosApi } from './geos.js';
+import type { AluviaApiRequestArgs } from './apiUtils.js';
+export type { AluviaApiRequestArgs };
 export type AluviaApiOptions = {
     apiKey: string;
     apiBaseUrl?: string;
     timeoutMs?: number;
     fetch?: typeof fetch;
 };
-export type AluviaApiRequestArgs = {
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
-    path: string;
-    query?: Record<string, string | number | boolean | null | undefined>;
-    body?: unknown;
-    headers?: Record<string, string>;
-};
 export declare class AluviaApi {
     private readonly apiKey;
     private readonly apiBaseUrl;

package/dist/types/api/account.d.ts

@@ -1,20 +1,5 @@
 import type { Account, AccountConnection, AccountConnectionDeleteResult, AccountPayment, AccountUsage } from './types.js';
-export type ApiRequestArgs = {
-    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
-    path: string;
-    query?: Record<string, string | number | boolean | null | undefined>;
-    body?: unknown;
-    headers?: Record<string, string>;
-    etag?: string | null;
-};
-export type ApiRequestResult = {
-    status: number;
-    etag: string | null;
-    body: unknown | null;
-};
-export type ApiContext = {
-    request: (args: ApiRequestArgs) => Promise<ApiRequestResult>;
-};
+import type { ApiContext } from './apiUtils.js';
 export declare function createAccountApi(ctx: ApiContext): {
     get: () => Promise<Account>;
     usage: {

package/dist/types/api/apiUtils.d.ts

@@ -0,0 +1,28 @@
+import type { ErrorEnvelope } from './types.js';
+export type ApiRequestArgs = {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    etag?: string | null;
+};
+export type ApiRequestResult = {
+    status: number;
+    etag: string | null;
+    body: unknown | null;
+};
+export type ApiContext = {
+    request: (args: ApiRequestArgs) => Promise<ApiRequestResult>;
+};
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function asErrorEnvelope(value: unknown): ErrorEnvelope | null;
+export declare function formatErrorDetails(details: unknown): string;
+export declare function throwForNon2xx(result: ApiRequestResult): never;
+export type AluviaApiRequestArgs = Omit<ApiRequestArgs, 'etag'>;
+export declare function throwIfAuthError(status: number): void;
+export declare function unwrapSuccess<T>(value: unknown): T | null;
+export declare function requestAndUnwrap<T>(ctx: ApiContext, args: ApiRequestArgs): Promise<{
+    data: T;
+    etag: string | null;
+}>;

package/dist/types/api/geos.d.ts

@@ -1,5 +1,5 @@
 import type { Geo } from './types.js';
-import type { ApiContext } from './account.js';
+import type { ApiContext } from './apiUtils.js';
 export declare function createGeosApi(ctx: ApiContext): {
     list: () => Promise<Array<Geo>>;
 };

package/dist/types/bin/account.d.ts

@@ -0,0 +1 @@
+export declare function handleAccount(args: string[]): Promise<void>;

package/dist/types/bin/api-helpers.d.ts

@@ -0,0 +1,20 @@
+import { AluviaApi } from '../api/AluviaApi.js';
+import type { LockData } from '../session/lock.js';
+/**
+ * Create an AluviaApi instance from ALUVIA_API_KEY env var.
+ * Calls output() and exits if the key is missing.
+ */
+export declare function requireApi(): AluviaApi;
+/**
+ * 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 declare function resolveSession(sessionName?: string): {
+    session: string;
+    lock: LockData;
+};
+/**
+ * Require a connection ID from lock data.
+ * Calls output() and exits if connectionId is missing.
+ */
+export declare function requireConnectionId(lock: LockData, session: string): number;

package/dist/types/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function output(data: Record<string, unknown>, exitCode?: number): never;