@aluvia/sdk 1.1.0 → 1.4.0

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

@@ -0,0 +1,8 @@
+/**
+ * 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/types/bin/cli.d.ts

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

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

@@ -0,0 +1 @@
+export declare function handleClose(sessionName?: string, closeAll?: boolean): Promise<void>;

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

@@ -0,0 +1 @@
+export declare function handleGeos(): Promise<void>;

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

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+/**
+ * Thrown by output() when in capture mode.
+ * Contains the JSON data and exit code that would have been written to stdout.
+ */
+export declare class MCPOutputCapture {
+    readonly data: Record<string, unknown>;
+    readonly exitCode: number;
+    constructor(data: Record<string, unknown>, exitCode: number);
+}
+export declare function isCapturing(): boolean;
+/**
+ * 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 declare function captureOutput(fn: () => Promise<void> | void): Promise<{
+    data: Record<string, unknown>;
+    isError: boolean;
+}>;

package/dist/types/bin/mcp-server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/bin/mcp-tools.d.ts

@@ -0,0 +1,46 @@
+/**
+ * MCP tool implementations.
+ *
+ * Each tool wraps the corresponding CLI handler via captureOutput(),
+ * converting the handler's JSON output into MCP tool results.
+ */
+type ToolResult = {
+    data: Record<string, unknown>;
+    isError: boolean;
+};
+export declare function sessionStart(args: {
+    url: string;
+    connectionId?: number;
+    headful?: boolean;
+    browserSession?: string;
+    autoUnblock?: boolean;
+    disableBlockDetection?: boolean;
+}): Promise<ToolResult>;
+export declare function sessionClose(args: {
+    browserSession?: string;
+    all?: boolean;
+}): Promise<ToolResult>;
+export declare function sessionList(): Promise<ToolResult>;
+export declare function sessionGet(args: {
+    browserSession?: string;
+}): Promise<ToolResult>;
+export declare function sessionRotateIp(args: {
+    browserSession?: string;
+}): Promise<ToolResult>;
+export declare function sessionSetGeo(args: {
+    geo?: string;
+    clear?: boolean;
+    browserSession?: string;
+}): Promise<ToolResult>;
+export declare function sessionSetRules(args: {
+    rules?: string;
+    remove?: string;
+    browserSession?: string;
+}): Promise<ToolResult>;
+export declare function accountGet(): Promise<ToolResult>;
+export declare function accountUsage(args: {
+    start?: string;
+    end?: string;
+}): Promise<ToolResult>;
+export declare function geosList(): Promise<ToolResult>;
+export {};

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

@@ -0,0 +1,21 @@
+export type OpenOptions = {
+    url: string;
+    connectionId?: number;
+    headless?: boolean;
+    sessionName?: string;
+    autoUnblock?: boolean;
+    disableBlockDetection?: boolean;
+    run?: string;
+};
+/**
+ * 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 declare function handleOpen({ url, connectionId, headless, sessionName, autoUnblock, disableBlockDetection, run }: OpenOptions): Promise<never>;
+/**
+ * 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 declare function handleOpenDaemon({ url, connectionId, headless, sessionName, autoUnblock, disableBlockDetection, run }: OpenOptions): Promise<void>;

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

@@ -0,0 +1,11 @@
+export type ParsedSessionArgs = {
+    url?: string;
+    connectionId?: number;
+    headed: boolean;
+    sessionName?: string;
+    autoUnblock: boolean;
+    disableBlockDetection: boolean;
+    run?: string;
+};
+export declare function parseSessionArgs(args: string[]): ParsedSessionArgs;
+export declare function handleSession(args: string[]): Promise<void>;

package/dist/types/client/AluviaClient.d.ts

@@ -1,5 +1,5 @@
-import type { AluviaClientConnection, AluviaClientOptions } from './types.js';
-import { AluviaApi } from '../api/AluviaApi.js';
+import type { AluviaClientConnection, AluviaClientOptions } from "./types.js";
+import { AluviaApi } from "../api/AluviaApi.js";
 /**
  * AluviaClient is the main entry point for the Aluvia Client.
  *
@@ -14,13 +14,38 @@ export declare class AluviaClient {
     private startPromise;
     private readonly logger;
     readonly api: AluviaApi;
+    private blockDetection;
+    private pageStates;
+    /** Promise-based mutex to serialize handleDetectionResult's critical section. */
+    private _detectionMutex;
+    /** Read-only access to the connection ID from ConfigManager. */
+    get connectionId(): number | undefined;
     constructor(options: AluviaClientOptions);
+    /**
+     * Attaches per-page listeners for two-pass detection and SPA navigation.
+     */
+    private attachPageListeners;
+    /**
+     * Attaches page listeners to all existing and future pages in a context.
+     */
+    private attachBlockDetectionListener;
+    /**
+     * Handle a detection result: fire callback, check persistent block, reload if needed.
+     *
+     * The auto-unblock critical section (persistent-block checks, rule updates, page reload)
+     * is serialized via a promise-based mutex to prevent concurrent calls from reading stale
+     * state and producing duplicate rule additions or missed persistent-block escalation.
+     */
+    private handleDetectionResult;
+    /**
+     * Auto-unblock critical section. Must only be called under _detectionMutex.
+     */
+    private _handleAutoUnblock;
     /**
      * Start the Aluvia Client connection:
      * - Fetch initial account connection config from Aluvia.
      * - Start polling for config updates.
-     * - If localProxy is enabled (default): start a local HTTP proxy on 127.0.0.1:<localPort or free port>.
-     * - If localProxy is disabled: do NOT start a local proxy; adapters use gateway proxy settings.
+     * - Start a local HTTP proxy on 127.0.0.1:<localPort or free port>.
      *
      * Returns the active connection with host/port/url and a stop() method.
      */
@@ -47,4 +72,26 @@ export declare class AluviaClient {
      * Pass null to clear geo targeting.
      */
     updateTargetGeo(targetGeo: string | null): Promise<void>;
+    /**
+     * Get a list of hostnames that have been detected as blocked.
+     *
+     * This list is maintained in-memory and cleared when the client is stopped.
+     * Only available when block detection is enabled.
+     */
+    getBlockedHostnames(): string[];
+    /**
+     * Clear the list of blocked hostnames and retried URLs.
+     *
+     * Only available when block detection is enabled.
+     */
+    clearBlockedHostnames(): void;
+    /**
+     * Import Playwright, auto-installing if necessary.
+     * Returns the chromium browser type for launching.
+     */
+    private _initPlaywright;
+    /**
+     * Find a free TCP port by briefly binding to port 0.
+     */
+    private static findFreePort;
 }

package/dist/types/client/BlockDetection.d.ts

@@ -0,0 +1,96 @@
+import type { Logger } from "./logger.js";
+/**
+ * Detection block status based on scoring
+ */
+export type DetectionBlockStatus = "blocked" | "suspected" | "clear";
+/**
+ * A single detection signal with weight
+ */
+export type DetectionSignal = {
+    name: string;
+    weight: number;
+    details: string;
+    source: "fast" | "full";
+};
+/**
+ * A single hop in a redirect chain
+ */
+export type RedirectHop = {
+    url: string;
+    statusCode: number;
+};
+/**
+ * Result of block detection analysis
+ */
+export type BlockDetectionResult = {
+    url: string;
+    hostname: string;
+    blockStatus: DetectionBlockStatus;
+    score: number;
+    signals: DetectionSignal[];
+    pass: "fast" | "full";
+    persistentBlock: boolean;
+    redirectChain: RedirectHop[];
+};
+/**
+ * Configuration for block detection
+ */
+export type BlockDetectionConfig = {
+    enabled?: boolean;
+    challengeSelectors?: string[];
+    extraKeywords?: string[];
+    extraStatusCodes?: number[];
+    networkIdleTimeoutMs?: number;
+    autoUnblock?: boolean;
+    autoUnblockOnSuspected?: boolean;
+    onDetection?: (result: BlockDetectionResult, page: any) => void | Promise<void>;
+};
+/**
+ * BlockDetection handles detection of website blocks, CAPTCHAs, and WAF challenges
+ * using a weighted scoring system across multiple signal types.
+ */
+export declare class BlockDetection {
+    private config;
+    private logger;
+    retriedUrls: Set<string>;
+    persistentHostnames: Set<string>;
+    private statusCodeSet;
+    private allTitleKeywords;
+    constructor(config: BlockDetectionConfig, logger: Logger);
+    getNetworkIdleTimeoutMs(): number;
+    isEnabled(): boolean;
+    getOnDetection(): ((result: BlockDetectionResult, page: any) => void | Promise<void>) | undefined;
+    isAutoUnblock(): boolean;
+    isAutoUnblockOnSuspected(): boolean;
+    private computeScore;
+    private detectHttpStatus;
+    private detectResponseHeaders;
+    private detectTitleKeywords;
+    private detectChallengeSelectors;
+    private detectVisibleText;
+    private detectTextToHtmlRatio;
+    private detectRedirectChain;
+    private detectMetaRefresh;
+    /**
+     * Fast pass - runs at domcontentloaded. Only HTTP status + response headers.
+     * If score >= 0.9, caller should trigger remediation immediately.
+     */
+    analyzeFast(page: any, response: any): Promise<BlockDetectionResult>;
+    /**
+     * Run all content-based detectors in parallel.
+     * Shared by analyzeFull and analyzeSpa.
+     */
+    private runContentDetectors;
+    /**
+     * Full pass - runs after networkidle. Runs all detectors and merges with fast pass.
+     */
+    analyzeFull(page: any, response: any, fastResult?: BlockDetectionResult): Promise<BlockDetectionResult>;
+    /**
+     * SPA navigation analysis - content-based detectors only, no HTTP signals.
+     */
+    analyzeSpa(page: any): Promise<BlockDetectionResult>;
+    private reEvaluateIfSuspected;
+    private makeResult;
+    private logResult;
+    private extractHostname;
+}

package/dist/types/client/ConfigManager.d.ts

@@ -1,4 +1,5 @@
 import type { GatewayProtocol, LogLevel } from './types.js';
+import type { NormalizedRules } from './rules.js';
 /**
  * Raw proxy configuration derived from the account-connection response and client options.
  */
@@ -15,6 +16,8 @@ export type RawProxyConfig = {
 export type ConnectionNetworkConfig = {
     rawProxy: RawProxyConfig;
     rules: string[];
+    /** Pre-normalized rules for efficient per-request matching. */
+    normalizedRules: NormalizedRules;
     sessionId: string | null;
     targetGeo: string | null;
     /**
@@ -63,6 +66,8 @@ export declare class ConfigManager {
     private readonly strict;
     private accountConnectionId;
     private pollInFlight;
+    /** Public read-only access to the account connection ID. */
+    get connectionId(): number | undefined;
     constructor(options: ConfigManagerOptions);
     /**
      * Fetch initial configuration from the account connections API.
@@ -86,7 +91,7 @@ export declare class ConfigManager {
      * Returns null if init() hasn't been called or failed.
      */
     getConfig(): ConnectionNetworkConfig | null;
-    setConfig(body: Object): Promise<ConnectionNetworkConfig | null>;
+    setConfig(body: Record<string, unknown>): Promise<ConnectionNetworkConfig | null>;
     /**
      * Perform a single poll iteration.
      * Called by the polling timer.

package/dist/types/client/PageLoadDetection.d.ts

@@ -0,0 +1,93 @@
+import type { Logger } from "./logger.js";
+/**
+ * Configuration for page load detection
+ */
+export type PageLoadDetectionConfig = {
+    /**
+     * Enable automatic detection of blocking/captchas
+     * Default: true
+     */
+    enabled?: boolean;
+    /**
+     * Keywords to search for in page content that indicate blocking
+     * Default: ['captcha', 'blocked', 'access denied', 'forbidden', 'cloudflare', 'please verify', 'recaptcha']
+     */
+    blockingKeywords?: string[];
+    /**
+     * HTTP status codes that indicate blocking
+     * Default: [403, 429, 503]
+     */
+    blockingStatusCodes?: number[];
+    /**
+     * Minimum content length for a successful page load
+     * Pages with less content may have failed to load
+     * Default: 100
+     */
+    minContentLength?: number;
+    /**
+     * Automatically add hostname to rules when blocking is detected
+     * Default: false (user must opt-in)
+     */
+    autoAddRules?: boolean;
+    /**
+     * Callback when blocking is detected
+     * Receives the hostname, detection reason, and the page object
+     */
+    onBlockingDetected?: (hostname: string, reason: BlockingReason, page: any) => void | Promise<void>;
+};
+/**
+ * Reason why blocking was detected
+ */
+export type BlockingReason = {
+    type: "status_code" | "keyword" | "content_length" | "error";
+    details: string;
+    statusCode?: number;
+    keyword?: string;
+};
+/**
+ * Result of page load detection
+ */
+export type PageLoadDetectionResult = {
+    url: string;
+    hostname: string;
+    success: boolean;
+    blocked: boolean;
+    reason?: BlockingReason;
+};
+/**
+ * PageLoadDetection handles enhanced detection of page load failures and blocking
+ */
+export declare class PageLoadDetection {
+    private config;
+    private logger;
+    private blockedHostnames;
+    constructor(config: PageLoadDetectionConfig, logger: Logger);
+    /**
+     * Update detection configuration
+     */
+    updateConfig(config: Partial<PageLoadDetectionConfig>): void;
+    /**
+     * Check if a hostname is already marked as blocked
+     */
+    isHostnameBlocked(hostname: string): boolean;
+    /**
+     * Get all blocked hostnames
+     */
+    getBlockedHostnames(): string[];
+    /**
+     * Clear blocked hostnames cache
+     */
+    clearBlockedHostnames(): void;
+    /**
+     * Analyze a page load and detect if it was blocked
+     */
+    analyzePage(page: any, response: any): Promise<PageLoadDetectionResult>;
+    /**
+     * Handle detected blocking
+     */
+    private handleBlocking;
+    /**
+     * Extract hostname from URL
+     */
+    private extractHostname;
+}

package/dist/types/client/logger.d.ts

@@ -20,6 +20,8 @@ export declare class Logger {
      * Logs only when level is 'debug'.
      */
     debug(...args: unknown[]): void;
+    /** Check if debug logging is enabled. */
+    get isDebug(): boolean;
     /**
      * Log warning messages.
      * Logs when level is not 'silent'.

package/dist/types/client/rules.d.ts

@@ -31,4 +31,22 @@ export declare function matchPattern(hostname: string, pattern: string): boolean
  * @param rules - Array of rule patterns
  * @returns true if the hostname should be proxied
  */
+/**
+ * Pre-normalized rules for efficient per-request matching.
+ */
+export type NormalizedRules = {
+    positiveRules: string[];
+    negativeRules: string[];
+    hasCatchAll: boolean;
+    empty: boolean;
+};
+/**
+ * Pre-process raw rule strings into a NormalizedRules structure.
+ * Call once when config is loaded, then use shouldProxyNormalized() per request.
+ */
+export declare function normalizeRules(rules: string[]): NormalizedRules;
+/**
+ * Fast proxy decision using pre-normalized rules.
+ */
+export declare function shouldProxyNormalized(hostname: string, rules: NormalizedRules): boolean;
 export declare function shouldProxy(hostname: string, rules: string[]): boolean;

package/dist/types/client/types.d.ts

@@ -1,11 +1,12 @@
+import type { BlockDetectionConfig } from "./BlockDetection.js";
 /**
  * Protocol used to connect to the Aluvia gateway.
  */
-export type GatewayProtocol = 'http' | 'https';
+export type GatewayProtocol = "http" | "https";
 /**
  * Log level for the client.
  */
-export type LogLevel = 'silent' | 'info' | 'debug';
+export type LogLevel = "silent" | "info" | "debug";
 export type PlaywrightProxySettings = {
     server: string;
     username?: string;
@@ -72,14 +73,6 @@ export type AluviaClientOptions = {
      *   POST /account/connections
      */
     connectionId?: number;
-    /**
-     * Optional: enable local proxy mode (client proxy mode).
-     *
-     * If true (default): start the local proxy (127.0.0.1:<port>) and route traffic dynamically.
-     * If false: do NOT start a local proxy; adapters return gateway proxy settings
-     * from the account connection API response for direct use by Playwright/Axios/etc.
-     */
-    localProxy?: boolean;
     /**
      * Optional: strict startup behavior.
      *
@@ -87,8 +80,8 @@ export type AluviaClientOptions = {
      * an account connection config (proxy credentials + rules). This prevents
      * "silent direct routing" where the local proxy starts but bypasses Aluvia.
      *
-     * If false: in client proxy mode, the SDK may still start a local proxy and
-     * route traffic directly when config is unavailable.
+     * If false: the SDK may still start a local proxy and route traffic directly
+     * when config is unavailable.
      */
     strict?: boolean;
     /**
@@ -103,42 +96,40 @@ export type AluviaClientOptions = {
      * Note: Playwright must be installed as a dependency for this option to work.
      */
     startPlaywright?: boolean;
+    /**
+     * Optional: configuration for website block detection.
+     *
+     * When enabled (default), the SDK monitors pages using a weighted scoring
+     * system across multiple signal types (HTTP status, WAF headers, DOM
+     * selectors, visible text, redirect chains) with two-pass analysis.
+     */
+    blockDetection?: BlockDetectionConfig;
+    /**
+     * Optional: run the Playwright browser in headless or headed mode.
+     *
+     * If true (default): the browser runs without a visible window.
+     * If false: the browser opens a visible window.
+     *
+     * Only applies when `startPlaywright` is true.
+     */
+    headless?: boolean;
 };
 /**
  * Represents an active Aluvia Client connection.
  */
 export type AluviaClientConnection = {
     /**
-     * Proxy host to configure in your client.
-     *
-     * - In client proxy mode (localProxy: true): this is the local proxy host ('127.0.0.1').
-     * - In gateway mode: this is the Aluvia gateway host (typically 'gateway.aluvia.io').
+     * Proxy host: `'127.0.0.1'` (the local proxy).
      */
     host: string;
     /**
-     * Proxy port to configure in your client.
-     *
-     * - In client proxy mode (localProxy: true): this is the local proxy port.
-     * - In gateway mode: this is the Aluvia gateway port (typically 8080 or 8443).
+     * The local proxy port.
      */
     port: number;
     /**
-     * Convenience URL for the proxy server endpoint (without embedding credentials).
-     *
-     * - In client proxy mode (localProxy: true): 'http://127.0.0.1:<port>'
-     * - In gateway mode: '<protocol>://gateway.aluvia.io:<port>'
-     *
-     * (The local proxy itself is always HTTP; it may tunnel to an HTTP or HTTPS
-     * gateway upstream based on gatewayProtocol/gatewayPort.)
+     * Proxy URL: `'http://127.0.0.1:<port>'`.
      */
     url: string;
-    /**
-     * Returns a credential-embedded proxy URL intended for clients that require auth in the URL.
-     *
-     * Note: This value contains secrets (proxy username/password). Avoid logging it or putting it
-     * in places that may be exposed (e.g., process args).
-     */
-    getUrl(): string;
     /**
      * Playwright adapter for chromium/firefox/webkit launch options.
      */
@@ -157,8 +148,8 @@ export type AluviaClientConnection = {
      * Useful for: Axios, got, node-fetch (legacy).
      */
     asNodeAgents(): {
-        http: import('node:http').Agent;
-        https: import('node:http').Agent;
+        http: import("node:http").Agent;
+        https: import("node:http").Agent;
     };
     /**
      * Axios adapter config.
@@ -168,8 +159,8 @@ export type AluviaClientConnection = {
      */
     asAxiosConfig(): {
         proxy: false;
-        httpAgent: import('node:http').Agent;
-        httpsAgent: import('node:http').Agent;
+        httpAgent: import("node:http").Agent;
+        httpsAgent: import("node:http").Agent;
     };
     /**
      * got adapter options.
@@ -178,14 +169,14 @@ export type AluviaClientConnection = {
      */
     asGotOptions(): {
         agent: {
-            http: import('node:http').Agent;
-            https: import('node:http').Agent;
+            http: import("node:http").Agent;
+            https: import("node:http").Agent;
         };
     };
     /**
      * undici proxy dispatcher (for undici fetch / undici clients).
      */
-    asUndiciDispatcher(): import('undici').Dispatcher;
+    asUndiciDispatcher(): import("undici").Dispatcher;
     /**
      * Returns a `fetch` function powered by undici that uses the proxy dispatcher per request.
      *
@@ -202,15 +193,25 @@ export type AluviaClientConnection = {
      * The browser is already configured to use the Aluvia proxy, so you can use it directly.
      */
     browser?: any;
+    browserContext?: any;
     /**
-     * Stop this proxy instance:
-     * - Close the local proxy server.
-     * - Close the browser (if started).
-     * - Stop using it for new connections.
+     * Chrome DevTools Protocol HTTP endpoint URL (for example: http://127.0.0.1:<port>).
+     *
+     * Only available if `startPlaywright: true` was passed to AluviaClientOptions.
+     * Intended for use by external tools that connect to the browser via CDP.
+     * Tools that require a WebSocket debugger URL should derive it from this HTTP
+     * endpoint (for example, by fetching `${cdpUrl}/json/version` and using the
+     * `webSocketDebuggerUrl` field from the response).
      */
-    stop(): Promise<void>;
+    cdpUrl?: string;
     /**
-     * Alias for stop().
+     * Close this proxy instance:
+     * - Close the local proxy server.
+     * - Close the browser (if started).
+     * - Stop config polling.
      */
     close(): Promise<void>;
+    /** @deprecated Use `close()` instead. */
+    stop(): Promise<void>;
 };
+export type { BlockDetectionConfig, BlockDetectionResult, DetectionBlockStatus, DetectionSignal, RedirectHop, } from "./BlockDetection.js";

package/dist/types/connect.d.ts

@@ -0,0 +1,18 @@
+export type ConnectResult = {
+    browser: any;
+    context: any;
+    page: any;
+    sessionName: string;
+    cdpUrl: string;
+    connectionId: number | undefined;
+    disconnect: () => Promise<void>;
+};
+/**
+ * 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 declare function connect(sessionName?: string): Promise<ConnectResult>;

package/dist/types/errors.d.ts

@@ -23,3 +23,9 @@ export declare class ApiError extends Error {
 export declare class ProxyStartError extends Error {
     constructor(message?: string);
 }
+/**
+ * Thrown by connect() when it cannot establish a CDP connection to a running session.
+ */
+export declare class ConnectError extends Error {
+    constructor(message: string);
+}