donobu/dist/esm/utils/BrowserUtils.d.ts

Create browser automations with an LLM agent and replay them as Playwright scripts.

import type { BrowserContext } from 'playwright';
import type { BrowserConfig } from '../models/BrowserConfig';
import type { BrowserDevice } from '../models/BrowserDevice';
import type { BrowserStorageState } from '../models/BrowserStorageState';
export type BROWSER_TYPE_NAME = 'firefox' | 'chromium' | 'chrome' | 'webkit' | 'ios';
/**
 * Utility class for managing browser instances and contexts across different browser types and configurations.
 *
 * Provides comprehensive browser automation capabilities including:
 * - Device emulation with pre-configured browser/device combinations
 * - Remote browser instance connection via Chrome DevTools Protocol (CDP)
 * - BrowserBase cloud browser integration
 * - Complete storage state management (cookies, localStorage, sessionStorage)
 * - Proxy configuration and environment variable integration
 * - Native Chrome installation support via CDP for "Desktop Chrome" device
 *
 * Supports multiple browser engines: Chromium, Chrome, Firefox, WebKit, and iOS Safari.
 *
 * @example
 * ```typescript
 * // Create a browser context with device emulation
 * const config: BrowserConfig = {
 *   using: { type: 'device', deviceName: 'iPhone 13' }
 * };
 * const context = await BrowserUtils.create(config, './output');
 *
 * // Use native Chrome installation (special case)
 * const chromeConfig: BrowserConfig = {
 *   using: { type: 'device', deviceName: 'Desktop Chrome' }
 * };
 * const chromeContext = await BrowserUtils.create(chromeConfig, './output');
 *
 * // Get supported devices
 * const devices = BrowserUtils.getSupportedDevices();
 *
 * // Extract storage state
 * const storageState = await BrowserUtils.getBrowserStorageState(context);
 * ```
 *
 * @see {@link BrowserConfig} for configuration options
 * @see {@link BrowserStorageState} for storage state structure
 * @see {@link BrowserDevice} for device configuration format
 */
export declare class BrowserUtils {
    private static readonly SUPPORTED_DEVICES;
    private static readonly DEFAULT_DEVICE_NAME;
    private static readonly DESKTOP_CHROME_DEVICE_NAME;
    /**
     * Loads browser device configurations from Playwright's built-in devices
     * plus the local `assets/devices.json` overrides.
     *
     * The returned map keys the devices by their name (ex: 'Desktop Firefox').
     *
     * See `assets/devices.json` for details.
     *
     * @returns A Map containing device configurations keyed by device name
     * @throws {Error} When the devices configuration file cannot be loaded
     */
    static getSupportedDevices(): Map<string, BrowserDevice>;
    /**
     * Creates a browser context based on the provided configuration.
     * Supports different browser types including device emulation, remote instances, and BrowserBase.
     *
     * Special case: When deviceName is "Desktop Chrome", launches the user's native Chrome
     * installation and connects via CDP instead of using Playwright's bundled browser.
     *
     * @param browserConfig - Configuration object specifying browser type and settings.
     * @param videoDir - If present, record video and store the artifacts in this directory.
     * @param storageState - Optional browser storage state to restore (cookies, localStorage, sessionStorage).
     * @returns A promise that resolves to a configured BrowserContext.
     * @throws {InvalidParamValueException} When an invalid browser type is specified.
     */
    static create(browserConfig: BrowserConfig, videoDir?: string, storageState?: BrowserStorageState, environ?: import("env-struct").Env<{
        BROWSERBASE_API_KEY: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
        PROXY_SERVER: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
        PROXY_USERNAME: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
        PROXY_PASSWORD: import("zod/v4").ZodOptional<import("zod/v4").ZodString>;
    }, {
        BROWSERBASE_API_KEY?: string | undefined;
        PROXY_SERVER?: string | undefined;
        PROXY_USERNAME?: string | undefined;
        PROXY_PASSWORD?: string | undefined;
    }>): Promise<BrowserContext>;
    /**
     * Gets the browser storage state including cookies, localStorage, and sessionStorage.
     *
     * @param browserContext - The browser context to extract storage state from
     * @returns A promise that resolves to the complete browser storage state
     */
    static getBrowserStorageState(browserContext: BrowserContext): Promise<BrowserStorageState>;
    /**
     * Launches the user's native Chrome installation and connects to it via CDP.
     * This provides access to the user's real Chrome profile, extensions, and settings.
     *
     * @param headless - Whether to run Chrome in headless mode
     * @param storageState - Optional browser storage state to restore
     * @param proxy - Optional proxy configuration for the browser
     * @throws {Error} When Chrome cannot be launched or CDP connection fails
     */
    private static forNativeChrome;
    /**
     * Launches the native Chrome browser with the specified arguments.
     * Attempts to find Chrome in common installation locations across different platforms.
     *
     * @param args - Command line arguments to pass to Chrome
     * @returns The spawned Chrome process
     * @throws {Error} When Chrome executable cannot be found or launched
     */
    private static launchNativeChrome;
    /**
     * Returns an array of possible Chrome executable paths for the current platform.
     *
     * @returns Array of potential Chrome executable paths
     */
    private static getChromePaths;
    /**
     * Connects to an existing Chromium browser using the Chrome DevTools Protocol (CDP) at the given URL.
     *
     * @param remoteBrowserInstanceUrl - The CDP endpoint URL of the remote browser instancevideoDir
     * @param storageState - Optional browser storage state to restore
     * @throws {InvalidParamValueException} When the remote browser URL is invalid or connection fails
     * @private
     */
    private static forRemoteBrowser;
    /**
     * Creates a browser and context for a specific device configuration.
     * If {@link storageState} is present, must be an object conforming to what is returned by
     * {@link BrowserContext.storageState()}.
     *
     * @param deviceName - Name of the device configuration to use
     * @param headless - Whether to run the browser in headless mode
     * @param videoDir - If present, record video and store the artifacts in this directory.
     * @param storageState - Optional browser storage state to restore
     * @param proxy - Optional proxy configuration for the browser
     * @throws {InvalidParamValueException} When the device name is not found in supported devices
     */
    private static forDevice;
    /**
     * Builds browser context options for a specific device configuration.
     *
     * @param deviceName - Name of the device configuration to use.
     * @param videoDir - If present, record video and store the artifacts in this directory.
     * @returns An object containing the browser type name and context options.
     * @throws {InvalidParamValueException} When the device name is not found in supported devices.
     */
    private static browserContextOptionsForDevice;
    /**
     * Returns the Playwright browser engine ('chromium', 'firefox', or 'webkit')
     * required to run the given device name.
     *
     * 'chrome' and 'ios' (used internally by Playwright devices) are normalised
     * to 'chromium' and 'webkit' respectively, so callers always receive one of
     * the three canonical engine names.
     *
     * @throws {InvalidParamValueException} When deviceName is not in the supported device list.
     */
    static getBrowserTypeForDeviceName(deviceName: string): 'chromium' | 'firefox' | 'webkit';
    /**
     * Expands proxy configuration by merging provided proxy settings with environment variables.
     * Environment variables serve as fallbacks for missing proxy configuration values.
     *
     * @param proxy - Optional proxy configuration object
     * @returns Expanded proxy configuration or undefined if no proxy is configured
     */
    private static expandProxyConfiguration;
    /**
     * Creates a new browser instance of the specified type with given launch and context options.
     * Handles cleanup by closing the browser if context creation fails.
     *
     * @param browserTypeName - The type of browser to launch
     * @param launchOptions - Options for launching the browser
     * @param browserContextOptions - Options for creating the browser context
     * @throws {InvalidParamValueException} When an unsupported browser type is specified
     */
    private static newBrowser;
    /**
     * Creates a BrowserBase session. Using this method requires the
     * BROWSERBASE_API_KEY environment variable to be set.
     *
     * The returned browserBaseData object conforms to the response of the session
     * creation API endpoint. See...
     * https://docs.browserbase.com/reference/api/create-a-session#response-id
     *
     * @param sessionArgs - Arguments for creating the BrowserBase session.
     * @param videoDir - If present, record video and store the artifacts in this directory.
     * @param storageState - Optional browser storage state to restore.
     * @returns A promise that resolves to an object containing the browser, context, and session data.
     * @throws {InvalidParamValueException} When BrowserBase API key is missing or session creation fails.
     */
    private static forBrowserBase;
    /**
     * Establishes a BrowserBase session. The returned structure matches the
     * response structure from the BrowserBase session API. See...
     * https://docs.browserbase.com/reference/api/create-a-session#response-id
     *
     * @param sessionArgs - Arguments for creating the BrowserBase session
     * @returns A promise that resolves to the BrowserBase session data
     * @throws {InvalidParamValueException} When the API key is missing or the API returns an error
     */
    private static establishBrowserBaseSession;
    /**
     * Attaches sessionStorage data to a browser context by adding an initialization script.
     * The script will restore sessionStorage items for each origin when pages are loaded.
     *
     * @param browserContext - The browser context to attach sessionStorage to
     * @param storageState - Optional browser storage state containing sessionStorage data
     */
    static attachSessionStorageToBrowserContext(browserContext: BrowserContext, storageState?: BrowserStorageState): Promise<void>;
}
//# sourceMappingURL=BrowserUtils.d.ts.map