browser-use 0.2.0 → 0.3.0

package/dist/browser/cloud/cloud.d.ts

@@ -0,0 +1,20 @@
+import { CloudBrowserResponse, type CreateBrowserRequest } from './views.js';
+export interface CloudBrowserClientOptions {
+    api_base_url?: string;
+    api_key?: string | null;
+    fetch_impl?: typeof fetch;
+}
+export declare class CloudBrowserClient {
+    private readonly api_base_url;
+    private readonly explicit_api_key;
+    private readonly fetch_impl;
+    current_session_id: string | null;
+    constructor(options?: CloudBrowserClientOptions);
+    private _resolve_api_key;
+    private _auth_headers;
+    private _create_request_body;
+    private _request_json;
+    create_browser(request: CreateBrowserRequest, extra_headers?: Record<string, string>): Promise<CloudBrowserResponse>;
+    stop_browser(session_id?: string | null, extra_headers?: Record<string, string>): Promise<CloudBrowserResponse>;
+    close(): Promise<void>;
+}

package/dist/browser/cloud/cloud.js

@@ -0,0 +1,129 @@
+import { CONFIG } from '../../config.js';
+import { createLogger } from '../../logging-config.js';
+import { DeviceAuthClient } from '../../sync/auth.js';
+import { CloudBrowserAuthError, CloudBrowserError, CloudBrowserResponse, MAX_PAID_USER_SESSION_TIMEOUT, } from './views.js';
+const logger = createLogger('browser_use.browser.cloud');
+const stripTrailingSlash = (input) => input.replace(/\/+$/, '');
+const normalizeTimeout = (timeout) => {
+    if (timeout == null) {
+        return null;
+    }
+    const integerTimeout = Math.floor(timeout);
+    if (!Number.isFinite(integerTimeout) || integerTimeout < 1) {
+        return null;
+    }
+    return Math.min(integerTimeout, MAX_PAID_USER_SESSION_TIMEOUT);
+};
+export class CloudBrowserClient {
+    api_base_url;
+    explicit_api_key;
+    fetch_impl;
+    current_session_id = null;
+    constructor(options = {}) {
+        this.api_base_url = stripTrailingSlash(options.api_base_url ?? CONFIG.BROWSER_USE_CLOUD_API_URL);
+        this.explicit_api_key = options.api_key ?? null;
+        this.fetch_impl = options.fetch_impl ?? fetch;
+    }
+    _resolve_api_key() {
+        if (this.explicit_api_key && this.explicit_api_key.trim()) {
+            return this.explicit_api_key.trim();
+        }
+        const fromEnv = process.env.BROWSER_USE_API_KEY?.trim();
+        if (fromEnv) {
+            return fromEnv;
+        }
+        const authClient = new DeviceAuthClient(this.api_base_url);
+        const fromAuthConfig = authClient.api_token?.trim();
+        if (fromAuthConfig) {
+            return fromAuthConfig;
+        }
+        return null;
+    }
+    _auth_headers(extra_headers = {}) {
+        const api_key = this._resolve_api_key();
+        if (!api_key) {
+            throw new CloudBrowserAuthError('No authentication token found. Set BROWSER_USE_API_KEY to use cloud browser.');
+        }
+        return {
+            'X-Browser-Use-API-Key': api_key,
+            'Content-Type': 'application/json',
+            ...extra_headers,
+        };
+    }
+    _create_request_body(request) {
+        const profile_id = request.profile_id ?? request.cloud_profile_id ?? null;
+        const proxy_country_code = request.proxy_country_code ?? request.cloud_proxy_country_code ?? null;
+        const timeout = normalizeTimeout(request.timeout ?? request.cloud_timeout ?? null);
+        return {
+            ...(profile_id ? { profile_id: String(profile_id) } : {}),
+            ...(proxy_country_code
+                ? { proxy_country_code: String(proxy_country_code) }
+                : {}),
+            ...(timeout ? { timeout } : {}),
+        };
+    }
+    async _request_json(path, init, extra_headers = {}) {
+        const response = await this.fetch_impl(`${this.api_base_url}${path}`, {
+            ...init,
+            headers: this._auth_headers(extra_headers),
+        });
+        const text = await response.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                payload = text;
+            }
+        }
+        if (!response.ok) {
+            const errorDetails = payload && typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload ?? '');
+            if (response.status === 401 || response.status === 403) {
+                throw new CloudBrowserAuthError(`Cloud browser authentication failed (${response.status})`);
+            }
+            throw new CloudBrowserError(`Cloud browser request failed (${response.status}): ${errorDetails}`);
+        }
+        return payload;
+    }
+    async create_browser(request, extra_headers = {}) {
+        logger.info('🌤️ Creating cloud browser instance...');
+        const payload = await this._request_json('/api/v2/browsers', {
+            method: 'POST',
+            body: JSON.stringify(this._create_request_body(request)),
+        }, extra_headers);
+        const browser_response = new CloudBrowserResponse(payload);
+        this.current_session_id = browser_response.id;
+        logger.info(`🌤️ Cloud browser created: ${browser_response.id}`);
+        return browser_response;
+    }
+    async stop_browser(session_id = null, extra_headers = {}) {
+        const target_session_id = session_id ?? this.current_session_id;
+        if (!target_session_id) {
+            throw new CloudBrowserError('No session ID provided and no active cloud browser session found');
+        }
+        const payload = await this._request_json(`/api/v2/browsers/${encodeURIComponent(target_session_id)}`, {
+            method: 'PATCH',
+            body: JSON.stringify({ action: 'stop' }),
+        }, extra_headers);
+        const browser_response = new CloudBrowserResponse(payload);
+        if (browser_response.id === this.current_session_id) {
+            this.current_session_id = null;
+        }
+        logger.info(`🌤️ Cloud browser stopped: ${browser_response.id}`);
+        return browser_response;
+    }
+    async close() {
+        if (!this.current_session_id) {
+            return;
+        }
+        try {
+            await this.stop_browser(this.current_session_id);
+        }
+        catch (error) {
+            logger.debug(`Failed to stop cloud browser during close: ${error.message}`);
+        }
+    }
+}

package/dist/browser/cloud/index.d.ts

@@ -0,0 +1,2 @@
+export * from './views.js';
+export * from './cloud.js';

package/dist/browser/cloud/index.js

@@ -0,0 +1,2 @@
+export * from './views.js';
+export * from './cloud.js';

package/dist/browser/cloud/views.d.ts

@@ -0,0 +1,41 @@
+export type ProxyCountryCode = 'us' | 'uk' | 'fr' | 'it' | 'jp' | 'au' | 'de' | 'fi' | 'ca' | 'in' | string;
+export declare const MAX_FREE_USER_SESSION_TIMEOUT = 15;
+export declare const MAX_PAID_USER_SESSION_TIMEOUT = 240;
+export interface CreateBrowserRequest {
+    cloud_profile_id?: string | null;
+    cloud_proxy_country_code?: ProxyCountryCode | null;
+    cloud_timeout?: number | null;
+    profile_id?: string | null;
+    proxy_country_code?: ProxyCountryCode | null;
+    timeout?: number | null;
+}
+export interface CloudBrowserResponsePayload {
+    id: string;
+    status: string;
+    liveUrl?: string;
+    live_url?: string;
+    cdpUrl?: string;
+    cdp_url?: string;
+    timeoutAt?: string;
+    timeout_at?: string;
+    startedAt?: string;
+    started_at?: string;
+    finishedAt?: string | null;
+    finished_at?: string | null;
+}
+export declare class CloudBrowserResponse {
+    id: string;
+    status: string;
+    liveUrl: string;
+    cdpUrl: string;
+    timeoutAt: string;
+    startedAt: string;
+    finishedAt: string | null;
+    constructor(payload: CloudBrowserResponsePayload);
+}
+export declare class CloudBrowserError extends Error {
+    constructor(message: string);
+}
+export declare class CloudBrowserAuthError extends CloudBrowserError {
+    constructor(message: string);
+}

package/dist/browser/cloud/views.js

@@ -0,0 +1,35 @@
+export const MAX_FREE_USER_SESSION_TIMEOUT = 15;
+export const MAX_PAID_USER_SESSION_TIMEOUT = 240;
+export class CloudBrowserResponse {
+    id;
+    status;
+    liveUrl;
+    cdpUrl;
+    timeoutAt;
+    startedAt;
+    finishedAt;
+    constructor(payload) {
+        if (!payload?.id || !payload?.status) {
+            throw new CloudBrowserError('Invalid cloud browser response: missing id or status');
+        }
+        this.id = String(payload.id);
+        this.status = String(payload.status);
+        this.liveUrl = String(payload.liveUrl ?? payload.live_url ?? '');
+        this.cdpUrl = String(payload.cdpUrl ?? payload.cdp_url ?? '');
+        this.timeoutAt = String(payload.timeoutAt ?? payload.timeout_at ?? '');
+        this.startedAt = String(payload.startedAt ?? payload.started_at ?? '');
+        this.finishedAt = payload.finishedAt ?? payload.finished_at ?? null;
+    }
+}
+export class CloudBrowserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CloudBrowserError';
+    }
+}
+export class CloudBrowserAuthError extends CloudBrowserError {
+    constructor(message) {
+        super(message);
+        this.name = 'CloudBrowserAuthError';
+    }
+}

package/dist/browser/events.d.ts

@@ -0,0 +1,345 @@
+import type { DOMElementNode } from '../dom/views.js';
+import { EventBusEvent, type EventBusEventInit } from '../event-bus.js';
+import { BrowserStateSummary } from './views.js';
+export type TargetID = string;
+export type WaitUntilState = 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+export type MouseButton = 'left' | 'right' | 'middle';
+export declare abstract class BrowserEvent<TResult = unknown> extends EventBusEvent<TResult> {
+    protected constructor(eventType: string, init?: EventBusEventInit<TResult>);
+}
+export declare class ElementSelectedEvent<TResult = unknown, TNode = DOMElementNode> extends BrowserEvent<TResult> {
+    node: TNode;
+    constructor(eventType: string, init: EventBusEventInit<TResult> & {
+        node: TNode;
+    });
+}
+export declare class NavigateToUrlEvent extends BrowserEvent<void> {
+    url: string;
+    wait_until: WaitUntilState;
+    timeout_ms: number | null;
+    new_tab: boolean;
+    constructor(init: EventBusEventInit<void> & {
+        url: string;
+        wait_until?: WaitUntilState;
+        timeout_ms?: number | null;
+        new_tab?: boolean;
+    });
+}
+export declare class ClickElementEvent extends ElementSelectedEvent<Record<string, unknown> | null> {
+    button: MouseButton;
+    constructor(init: EventBusEventInit<Record<string, unknown> | null> & {
+        node: DOMElementNode;
+        button?: MouseButton;
+    });
+}
+export declare class ClickCoordinateEvent extends BrowserEvent<Record<string, unknown>> {
+    coordinate_x: number;
+    coordinate_y: number;
+    button: MouseButton;
+    force: boolean;
+    constructor(init: EventBusEventInit<Record<string, unknown>> & {
+        coordinate_x: number;
+        coordinate_y: number;
+        button?: MouseButton;
+        force?: boolean;
+    });
+}
+export declare class TypeTextEvent extends ElementSelectedEvent<Record<string, unknown> | null> {
+    text: string;
+    clear: boolean;
+    is_sensitive: boolean;
+    sensitive_key_name: string | null;
+    constructor(init: EventBusEventInit<Record<string, unknown> | null> & {
+        node: DOMElementNode;
+        text: string;
+        clear?: boolean;
+        is_sensitive?: boolean;
+        sensitive_key_name?: string | null;
+    });
+}
+export declare class ScrollEvent extends ElementSelectedEvent<void, DOMElementNode | null> {
+    direction: 'up' | 'down' | 'left' | 'right';
+    amount: number;
+    constructor(init: EventBusEventInit<void> & {
+        direction: 'up' | 'down' | 'left' | 'right';
+        amount: number;
+        node?: DOMElementNode | null;
+    });
+}
+export declare class SwitchTabEvent extends BrowserEvent<TargetID> {
+    target_id: TargetID | null;
+    constructor(init?: EventBusEventInit<TargetID> & {
+        target_id?: TargetID | null;
+    });
+}
+export declare class CloseTabEvent extends BrowserEvent<void> {
+    target_id: TargetID;
+    constructor(init: EventBusEventInit<void> & {
+        target_id: TargetID;
+    });
+}
+export declare class ScreenshotEvent extends BrowserEvent<string> {
+    full_page: boolean;
+    clip: Record<string, number> | null;
+    constructor(init?: EventBusEventInit<string> & {
+        full_page?: boolean;
+        clip?: Record<string, number> | null;
+    });
+}
+export declare class BrowserStateRequestEvent extends BrowserEvent<BrowserStateSummary> {
+    include_dom: boolean;
+    include_screenshot: boolean;
+    include_recent_events: boolean;
+    constructor(init?: EventBusEventInit<BrowserStateSummary> & {
+        include_dom?: boolean;
+        include_screenshot?: boolean;
+        include_recent_events?: boolean;
+    });
+}
+export declare class GoBackEvent extends BrowserEvent<void> {
+    constructor(init?: EventBusEventInit<void>);
+}
+export declare class GoForwardEvent extends BrowserEvent<void> {
+    constructor(init?: EventBusEventInit<void>);
+}
+export declare class RefreshEvent extends BrowserEvent<void> {
+    constructor(init?: EventBusEventInit<void>);
+}
+export declare class WaitEvent extends BrowserEvent<void> {
+    seconds: number;
+    max_seconds: number;
+    constructor(init?: EventBusEventInit<void> & {
+        seconds?: number;
+        max_seconds?: number;
+    });
+}
+export declare class SendKeysEvent extends BrowserEvent<void> {
+    keys: string;
+    constructor(init: EventBusEventInit<void> & {
+        keys: string;
+    });
+}
+export declare class UploadFileEvent extends ElementSelectedEvent<void> {
+    file_path: string;
+    constructor(init: EventBusEventInit<void> & {
+        node: DOMElementNode;
+        file_path: string;
+    });
+}
+export declare class GetDropdownOptionsEvent extends ElementSelectedEvent<Record<string, string>> {
+    constructor(init: EventBusEventInit<Record<string, string>> & {
+        node: DOMElementNode;
+    });
+}
+export declare class SelectDropdownOptionEvent extends ElementSelectedEvent<Record<string, string>> {
+    text: string;
+    constructor(init: EventBusEventInit<Record<string, string>> & {
+        node: DOMElementNode;
+        text: string;
+    });
+}
+export declare class ScrollToTextEvent extends BrowserEvent<void> {
+    text: string;
+    direction: 'up' | 'down';
+    constructor(init: EventBusEventInit<void> & {
+        text: string;
+        direction?: 'up' | 'down';
+    });
+}
+export declare class BrowserStartEvent extends BrowserEvent<void> {
+    cdp_url: string | null;
+    launch_options: Record<string, unknown>;
+    constructor(init?: EventBusEventInit<void> & {
+        cdp_url?: string | null;
+        launch_options?: Record<string, unknown>;
+    });
+}
+export declare class BrowserStopEvent extends BrowserEvent<void> {
+    force: boolean;
+    constructor(init?: EventBusEventInit<void> & {
+        force?: boolean;
+    });
+}
+export interface BrowserLaunchResult {
+    cdp_url: string;
+}
+export declare class BrowserLaunchEvent extends BrowserEvent<BrowserLaunchResult> {
+    constructor(init?: EventBusEventInit<BrowserLaunchResult>);
+}
+export declare class BrowserKillEvent extends BrowserEvent<void> {
+    constructor(init?: EventBusEventInit<void>);
+}
+export declare class BrowserConnectedEvent extends BrowserEvent<void> {
+    cdp_url: string;
+    constructor(init: EventBusEventInit<void> & {
+        cdp_url: string;
+    });
+}
+export declare class BrowserStoppedEvent extends BrowserEvent<void> {
+    reason: string | null;
+    constructor(init?: EventBusEventInit<void> & {
+        reason?: string | null;
+    });
+}
+export declare class TabCreatedEvent extends BrowserEvent<void> {
+    target_id: TargetID;
+    url: string;
+    constructor(init: EventBusEventInit<void> & {
+        target_id: TargetID;
+        url: string;
+    });
+}
+export declare class TabClosedEvent extends BrowserEvent<void> {
+    target_id: TargetID;
+    constructor(init: EventBusEventInit<void> & {
+        target_id: TargetID;
+    });
+}
+export declare class AgentFocusChangedEvent extends BrowserEvent<void> {
+    target_id: TargetID;
+    url: string;
+    constructor(init: EventBusEventInit<void> & {
+        target_id: TargetID;
+        url: string;
+    });
+}
+export declare class TargetCrashedEvent extends BrowserEvent<void> {
+    target_id: TargetID;
+    error: string;
+    constructor(init: EventBusEventInit<void> & {
+        target_id: TargetID;
+        error: string;
+    });
+}
+export declare class NavigationStartedEvent extends BrowserEvent<void> {
+    target_id: TargetID;
+    url: string;
+    constructor(init: EventBusEventInit<void> & {
+        target_id: TargetID;
+        url: string;
+    });
+}
+export declare class NavigationCompleteEvent extends BrowserEvent<void> {
+    target_id: TargetID;
+    url: string;
+    status: number | null;
+    error_message: string | null;
+    loading_status: string | null;
+    constructor(init: EventBusEventInit<void> & {
+        target_id: TargetID;
+        url: string;
+        status?: number | null;
+        error_message?: string | null;
+        loading_status?: string | null;
+    });
+}
+export declare class BrowserErrorEvent extends BrowserEvent<void> {
+    error_type: string;
+    message: string;
+    details: Record<string, unknown>;
+    constructor(init: EventBusEventInit<void> & {
+        error_type: string;
+        message: string;
+        details?: Record<string, unknown>;
+    });
+}
+export declare class SaveStorageStateEvent extends BrowserEvent<void> {
+    path: string | null;
+    constructor(init?: EventBusEventInit<void> & {
+        path?: string | null;
+    });
+}
+export declare class StorageStateSavedEvent extends BrowserEvent<void> {
+    path: string;
+    cookies_count: number;
+    origins_count: number;
+    constructor(init: EventBusEventInit<void> & {
+        path: string;
+        cookies_count: number;
+        origins_count: number;
+    });
+}
+export declare class LoadStorageStateEvent extends BrowserEvent<void> {
+    path: string | null;
+    constructor(init?: EventBusEventInit<void> & {
+        path?: string | null;
+    });
+}
+export declare class StorageStateLoadedEvent extends BrowserEvent<void> {
+    path: string;
+    cookies_count: number;
+    origins_count: number;
+    constructor(init: EventBusEventInit<void> & {
+        path: string;
+        cookies_count: number;
+        origins_count: number;
+    });
+}
+export declare class DownloadStartedEvent extends BrowserEvent<void> {
+    guid: string;
+    url: string;
+    suggested_filename: string;
+    auto_download: boolean;
+    constructor(init: EventBusEventInit<void> & {
+        guid: string;
+        url: string;
+        suggested_filename: string;
+        auto_download?: boolean;
+    });
+}
+export declare class DownloadProgressEvent extends BrowserEvent<void> {
+    guid: string;
+    received_bytes: number;
+    total_bytes: number;
+    state: string;
+    constructor(init: EventBusEventInit<void> & {
+        guid: string;
+        received_bytes: number;
+        total_bytes: number;
+        state: string;
+    });
+}
+export declare class FileDownloadedEvent extends BrowserEvent<void> {
+    guid: string | null;
+    url: string;
+    path: string;
+    file_name: string;
+    file_size: number;
+    file_type: string | null;
+    mime_type: string | null;
+    from_cache: boolean;
+    auto_download: boolean;
+    constructor(init: EventBusEventInit<void> & {
+        guid?: string | null;
+        url: string;
+        path: string;
+        file_name: string;
+        file_size: number;
+        file_type?: string | null;
+        mime_type?: string | null;
+        from_cache?: boolean;
+        auto_download?: boolean;
+    });
+}
+export declare class AboutBlankDVDScreensaverShownEvent extends BrowserEvent<void> {
+    target_id: TargetID;
+    error: string | null;
+    constructor(init: EventBusEventInit<void> & {
+        target_id: TargetID;
+        error?: string | null;
+    });
+}
+export declare class DialogOpenedEvent extends BrowserEvent<void> {
+    dialog_type: string;
+    message: string;
+    url: string;
+    frame_id: string | null;
+    constructor(init: EventBusEventInit<void> & {
+        dialog_type: string;
+        message: string;
+        url: string;
+        frame_id?: string | null;
+    });
+}
+export declare const BROWSER_EVENT_CLASSES: readonly [typeof ElementSelectedEvent, typeof NavigateToUrlEvent, typeof ClickElementEvent, typeof ClickCoordinateEvent, typeof TypeTextEvent, typeof ScrollEvent, typeof SwitchTabEvent, typeof CloseTabEvent, typeof ScreenshotEvent, typeof BrowserStateRequestEvent, typeof GoBackEvent, typeof GoForwardEvent, typeof RefreshEvent, typeof WaitEvent, typeof SendKeysEvent, typeof UploadFileEvent, typeof GetDropdownOptionsEvent, typeof SelectDropdownOptionEvent, typeof ScrollToTextEvent, typeof BrowserStartEvent, typeof BrowserStopEvent, typeof BrowserLaunchEvent, typeof BrowserKillEvent, typeof BrowserConnectedEvent, typeof BrowserStoppedEvent, typeof TabCreatedEvent, typeof TabClosedEvent, typeof AgentFocusChangedEvent, typeof TargetCrashedEvent, typeof NavigationStartedEvent, typeof NavigationCompleteEvent, typeof BrowserErrorEvent, typeof SaveStorageStateEvent, typeof StorageStateSavedEvent, typeof LoadStorageStateEvent, typeof StorageStateLoadedEvent, typeof DownloadStartedEvent, typeof DownloadProgressEvent, typeof FileDownloadedEvent, typeof AboutBlankDVDScreensaverShownEvent, typeof DialogOpenedEvent];
+export declare const BROWSER_EVENT_NAMES: string[];