/// <reference types="node" preserve="true" />
/**
 * @license
 * Copyright 2017 Google Inc.
 * SPDX-License-Identifier: Apache-2.0
 */
import type { ChildProcess } from 'node:child_process';
import type { Protocol } from 'devtools-protocol';
import type { ProtocolType } from '../common/ConnectOptions.js';
import type { Cookie, CookieData, DeleteCookiesRequest } from '../common/Cookie.js';
import { type Logger } from '../common/Debug.js';
import type { DownloadBehavior } from '../common/DownloadBehavior.js';
import { EventEmitter, type EventType } from '../common/EventEmitter.js';
import { asyncDisposeSymbol, disposeSymbol } from '../util/disposable.js';
import type { BrowserContext } from './BrowserContext.js';
import type { Extension } from './Extension.js';
import type { Page } from './Page.js';
import type { Target } from './Target.js';
/**
 * @public
 */
export interface BrowserContextOptions {
    /**
     * Proxy server with optional port to use for all requests.
     * Username and password can be set in `Page.authenticate`.
     */
    proxyServer?: string;
    /**
     * Bypass the proxy for the given list of hosts.
     */
    proxyBypassList?: string[];
    /**
     * Behavior definition for when downloading a file.
     *
     * @remarks
     * If not set, the default behavior will be used.
     */
    downloadBehavior?: DownloadBehavior;
}
/**
 * @internal
 */
export type BrowserCloseCallback = () => Promise<void> | void;
/**
 * @public
 */
export type TargetFilterCallback = (target: Target) => boolean;
/**
 * @internal
 */
export type IsPageTargetCallback = (target: Target) => boolean;
/**
 * @internal
 */
export declare const WEB_PERMISSION_TO_PROTOCOL_PERMISSION: Map<Permission, Protocol.Browser.PermissionType>;
/**
 * @public
 * @deprecated in favor of {@link PermissionDescriptor}.
 */
export type Permission = 'accelerometer' | 'ambient-light-sensor' | 'background-sync' | 'camera' | 'clipboard-read' | 'clipboard-sanitized-write' | 'clipboard-write' | 'geolocation' | 'gyroscope' | 'idle-detection' | 'keyboard-lock' | 'magnetometer' | 'microphone' | 'midi-sysex' | 'midi' | 'notifications' | 'payment-handler' | 'persistent-storage' | 'pointer-lock';
/**
 * @public
 */
export interface PermissionDescriptor {
    name: string;
    userVisibleOnly?: boolean;
    sysex?: boolean;
    panTiltZoom?: boolean;
    allowWithoutSanitization?: boolean;
}
/**
 * @public
 */
export type PermissionState = 'granted' | 'denied' | 'prompt';
/**
 * @public
 */
export interface WaitForTargetOptions {
    /**
     * Maximum wait time in milliseconds. Pass `0` to disable the timeout.
     *
     * @defaultValue `30_000`
     */
    timeout?: number;
    /**
     * A signal object that allows you to cancel a waitFor call.
     */
    signal?: AbortSignal;
}
/**
 * All the events a {@link Browser | browser instance} may emit.
 *
 * @public
 */
export declare const enum BrowserEvent {
    /**
     * Emitted when Puppeteer gets disconnected from the browser instance. This
     * might happen because either:
     *
     * - The browser closes/crashes or
     * - {@link Browser.disconnect} was called.
     */
    Disconnected = "disconnected",
    /**
     * Emitted when the URL of a target changes. Contains a {@link Target}
     * instance.
     *
     * @remarks Note that this includes target changes in all browser
     * contexts.
     */
    TargetChanged = "targetchanged",
    /**
     * Emitted when a target is created, for example when a new page is opened by
     * {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/open | window.open}
     * or by {@link Browser.newPage | browser.newPage}
     *
     * Contains a {@link Target} instance.
     *
     * @remarks Note that this includes target creations in all browser
     * contexts.
     */
    TargetCreated = "targetcreated",
    /**
     * Emitted when a target is destroyed, for example when a page is closed.
     * Contains a {@link Target} instance.
     *
     * @remarks Note that this includes target destructions in all browser
     * contexts.
     */
    TargetDestroyed = "targetdestroyed",
    /**
     * @internal
     */
    TargetDiscovered = "targetdiscovered"
}
/**
 * @public
 */
export interface BrowserEvents extends Record<EventType, unknown> {
    [BrowserEvent.Disconnected]: undefined;
    [BrowserEvent.TargetCreated]: Target;
    [BrowserEvent.TargetDestroyed]: Target;
    [BrowserEvent.TargetChanged]: Target;
    /**
     * @internal
     */
    [BrowserEvent.TargetDiscovered]: Protocol.Target.TargetInfo;
}
/**
 * @public
 * @experimental
 */
export interface DebugInfo {
    pendingProtocolErrors: Error[];
}
/**
 * @public
 */
export type WindowState = 'normal' | 'minimized' | 'maximized' | 'fullscreen';
/**
 * @public
 */
export interface WindowBounds {
    left?: number;
    top?: number;
    width?: number;
    height?: number;
    windowState?: WindowState;
}
/**
 * @public
 */
export type WindowId = string;
/**
 * @public
 */
export type CreatePageOptions = ({
    type?: 'tab';
} | {
    type: 'window';
    windowBounds?: WindowBounds;
}) & {
    /**
     * Whether to create the page in the background.
     *
     * @defaultValue `false`
     */
    background?: boolean;
};
/**
 * @public
 */
export interface ScreenOrientation {
    angle: number;
    type: string;
}
/**
 * @public
 */
export interface ScreenInfo {
    left: number;
    top: number;
    width: number;
    height: number;
    availLeft: number;
    availTop: number;
    availWidth: number;
    availHeight: number;
    devicePixelRatio: number;
    colorDepth: number;
    orientation: ScreenOrientation;
    isExtended: boolean;
    isInternal: boolean;
    isPrimary: boolean;
    label: string;
    id: string;
}
/**
 * @public
 */
export interface WorkAreaInsets {
    top?: number;
    left?: number;
    bottom?: number;
    right?: number;
}
/**
 * @public
 */
export interface AddScreenParams {
    left: number;
    top: number;
    width: number;
    height: number;
    workAreaInsets?: WorkAreaInsets;
    devicePixelRatio?: number;
    rotation?: number;
    colorDepth?: number;
    label?: string;
    isInternal?: boolean;
}
/**
 * @public
 */
export interface ExtensionInstallOptions {
    /**
     * Whether to enable the extension in Incognito or OTR profiles in Chrome.
     */
    enabledInIncognito: boolean;
}
/**
 * If the user prefers opening an installed web app in a standalone window or in
 * a browser tab.
 *
 * @public
 */
export type PWADisplayMode = 'standalone' | 'browser';
/**
 * Options for {@link Browser.installPWA}.
 *
 * @public
 */
export interface InstallPWAOptions {
    /**
     * The id from the web app's manifest file, commonly the URL of the site
     * installing the web app. See
     * {@link https://web.dev/learn/pwa/web-app-manifest | Web app manifest}.
     */
    manifestId: string;
    /**
     * The URL used to install the app, or the URL of its signed web bundle.
     *
     * This is required because the browser-scoped CDP session has no associated
     * page from which Chromium could derive an install URL.
     */
    installUrlOrBundleUrl: string;
    /**
     * Whether the app should open in a standalone window or a browser tab.
     *
     * @remarks
     *
     * `PWA.install` alone leaves the app at Chromium's default display mode
     * (`browser`); setting this chains a `PWA.changeAppUserSettings` call to apply
     * the preference.
     */
    displayMode?: PWADisplayMode;
}
/**
 * Options for {@link Browser.uninstallPWA}.
 *
 * @public
 */
export interface UninstallPWAOptions {
    /**
     * The id from the web app's manifest file.
     */
    manifestId: string;
}
/**
 * Options for {@link Browser.launchPWA}.
 *
 * @public
 */
export interface LaunchPWAOptions {
    /**
     * The id from the web app's manifest file.
     */
    manifestId: string;
    /**
     * An optional URL within the app's scope to launch. Defaults to the app's
     * start URL.
     */
    url?: string;
    /**
     * Maximum time in milliseconds to wait for the app's page target to appear.
     * Defaults to 30 seconds. Pass `0` to disable the timeout.
     */
    timeout?: number;
}
/**
 * Options for {@link Browser.getPWAState}.
 *
 * @public
 */
export interface GetPWAStateOptions {
    /**
     * The id from the web app's manifest file.
     */
    manifestId: string;
}
/**
 * The OS-integration state of an installed web app, returned by
 * {@link Browser.getPWAState}.
 *
 * @public
 */
export interface PWAState {
    /**
     * The current badge count shown on the app icon.
     */
    badgeCount: number;
    /**
     * The file handlers registered by the app with the OS.
     */
    fileHandlers: Protocol.PWA.FileHandler[];
}
/**
 * {@link Browser} represents a browser instance that is either:
 *
 * - connected to via {@link Puppeteer.connect} or
 * - launched by {@link PuppeteerNode.launch}.
 *
 * {@link Browser} {@link EventEmitter.emit | emits} various events which are
 * documented in the {@link BrowserEvent} enum.
 *
 * @example Using a {@link Browser} to create a {@link Page}:
 *
 * ```ts
 * import puppeteer from 'puppeteer';
 *
 * const browser = await puppeteer.launch();
 * const page = await browser.newPage();
 * await page.goto('https://example.com');
 * await browser.close();
 * ```
 *
 * @example Disconnecting from and reconnecting to a {@link Browser}:
 *
 * ```ts
 * import puppeteer from 'puppeteer';
 *
 * const browser = await puppeteer.launch();
 * // Store the endpoint to be able to reconnect to the browser.
 * const browserWSEndpoint = browser.wsEndpoint();
 * // Disconnect puppeteer from the browser.
 * await browser.disconnect();
 *
 * // Use the endpoint to reestablish a connection
 * const browser2 = await puppeteer.connect({browserWSEndpoint});
 * // Close the browser.
 * await browser2.close();
 * ```
 *
 * @public
 */
export declare abstract class Browser extends EventEmitter<BrowserEvents> {
    #private;
    /**
     * @internal
     */
    constructor(logger: Logger);
    /**
     * @internal
     */
    protected get logger(): Logger;
    /**
     * Gets the associated
     * {@link https://nodejs.org/api/child_process.html#class-childprocess | ChildProcess}.
     *
     * @returns `null` if this instance was connected to via
     * {@link Puppeteer.connect}.
     */
    abstract process(): ChildProcess | null;
    /**
     * Creates a new {@link BrowserContext | browser context}.
     *
     * This won't share cookies/cache with other {@link BrowserContext | browser contexts}.
     *
     * @example
     *
     * ```ts
     * import puppeteer from 'puppeteer';
     *
     * const browser = await puppeteer.launch();
     * // Create a new browser context.
     * const context = await browser.createBrowserContext();
     * // Create a new page in a pristine context.
     * const page = await context.newPage();
     * // Do stuff
     * await page.goto('https://example.com');
     * ```
     */
    abstract createBrowserContext(options?: BrowserContextOptions): Promise<BrowserContext>;
    /**
     * Gets a list of open {@link BrowserContext | browser contexts}.
     *
     * In a newly-created {@link Browser | browser}, this will return a single
     * instance of {@link BrowserContext}.
     */
    abstract browserContexts(): BrowserContext[];
    /**
     * Gets the default {@link BrowserContext | browser context}.
     *
     * @remarks The default {@link BrowserContext | browser context} cannot be
     * closed.
     */
    abstract defaultBrowserContext(): BrowserContext;
    /**
     * Gets the WebSocket URL to connect to this {@link Browser | browser}.
     *
     * This is usually used with {@link Puppeteer.connect}.
     *
     * You can find the debugger URL (`webSocketDebuggerUrl`) from
     * `http://HOST:PORT/json/version`.
     *
     * See {@link https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target | browser endpoint}
     * for more information.
     *
     * @remarks The format is always `ws://HOST:PORT/devtools/browser/<id>`.
     */
    abstract wsEndpoint(): string;
    /**
     * Creates a new {@link Page | page} in the
     * {@link Browser.defaultBrowserContext | default browser context}.
     */
    abstract newPage(options?: CreatePageOptions): Promise<Page>;
    /**
     * Gets the specified window {@link WindowBounds | bounds}.
     */
    abstract getWindowBounds(windowId: WindowId): Promise<WindowBounds>;
    /**
     * Sets the specified window {@link WindowBounds | bounds}.
     */
    abstract setWindowBounds(windowId: WindowId, windowBounds: WindowBounds): Promise<void>;
    /**
     * Gets all active {@link Target | targets}.
     *
     * In case of multiple {@link BrowserContext | browser contexts}, this returns
     * all {@link Target | targets} in all
     * {@link BrowserContext | browser contexts}.
     */
    abstract targets(): Target[];
    /**
     * Gets the {@link Target | target} associated with the
     * {@link Browser.defaultBrowserContext | default browser context}).
     */
    abstract target(): Target;
    /**
     * Waits until a {@link Target | target} matching the given `predicate`
     * appears and returns it.
     *
     * This will look all open {@link BrowserContext | browser contexts}.
     *
     * @example Finding a target for a page opened via `window.open`:
     *
     * ```ts
     * await page.evaluate(() => window.open('https://www.example.com/'));
     * const newWindowTarget = await browser.waitForTarget(
     *   target => target.url() === 'https://www.example.com/',
     * );
     * ```
     */
    waitForTarget(predicate: (x: Target) => boolean | Promise<boolean>, options?: WaitForTargetOptions): Promise<Target>;
    /**
     * Gets a list of all open {@link Page | pages} inside this {@link Browser}.
     *
     * If there are multiple {@link BrowserContext | browser contexts}, this
     * returns all {@link Page | pages} in all
     * {@link BrowserContext | browser contexts}.
     *
     * @param includeAll - experimental, setting to true includes all kinds of pages.
     *
     * @remarks Non-visible {@link Page | pages}, such as `"background_page"`,
     * will not be listed here. You can find them using {@link Target.page}.
     */
    pages(includeAll?: boolean): Promise<Page[]>;
    /**
     * Gets a string representing this {@link Browser | browser's} name and
     * version.
     *
     * For headless browser, this is similar to `"HeadlessChrome/61.0.3153.0"`. For
     * non-headless or new-headless, this is similar to `"Chrome/61.0.3153.0"`. For
     * Firefox, it is similar to `"Firefox/116.0a1"`.
     *
     * The format of {@link Browser.version} might change with future releases of
     * browsers.
     */
    abstract version(): Promise<string>;
    /**
     * Gets this {@link Browser | browser's} original user agent.
     *
     * {@link Page | Pages} can override the user agent with
     * {@link Page.(setUserAgent:2) }.
     *
     */
    abstract userAgent(): Promise<string>;
    /**
     * Closes this {@link Browser | browser} and all associated
     * {@link Page | pages}.
     */
    abstract close(): Promise<void>;
    /**
     * Disconnects Puppeteer from this {@link Browser | browser}, but leaves the
     * process running.
     */
    abstract disconnect(): Promise<void>;
    /**
     * Returns all cookies in the default {@link BrowserContext}.
     *
     * @remarks
     *
     * Shortcut for
     * {@link BrowserContext.cookies | browser.defaultBrowserContext().cookies()}.
     */
    cookies(): Promise<Cookie[]>;
    /**
     * Sets cookies in the default {@link BrowserContext}.
     *
     * @remarks
     *
     * Shortcut for
     * {@link BrowserContext.setCookie | browser.defaultBrowserContext().setCookie()}.
     */
    setCookie(...cookies: CookieData[]): Promise<void>;
    /**
     * Removes cookies from the default {@link BrowserContext}.
     *
     * @remarks
     *
     * Shortcut for
     * {@link BrowserContext.deleteCookie | browser.defaultBrowserContext().deleteCookie()}.
     */
    deleteCookie(...cookies: Cookie[]): Promise<void>;
    /**
     * Deletes cookies matching the provided filters from the default
     * {@link BrowserContext}.
     *
     * @remarks
     *
     * Shortcut for
     * {@link BrowserContext.deleteMatchingCookies |
     * browser.defaultBrowserContext().deleteMatchingCookies()}.
     */
    deleteMatchingCookies(...filters: DeleteCookiesRequest[]): Promise<void>;
    /**
     * Sets the permission for a specific origin in the default
     * {@link BrowserContext}.
     *
     * @remarks
     *
     * Shortcut for
     * {@link BrowserContext.setPermission |
     * browser.defaultBrowserContext().setPermission()}.
     *
     * @param origin - The origin to set the permission for.
     * @param permission - The permission descriptor.
     * @param state - The state of the permission.
     *
     * @public
     */
    setPermission(origin: string, ...permissions: Array<{
        permission: PermissionDescriptor;
        state: PermissionState;
    }>): Promise<void>;
    /**
     * Installs an extension and returns the ID.
     */
    abstract installExtension(path: string, options?: ExtensionInstallOptions): Promise<string>;
    /**
     * Uninstalls an extension.
     */
    abstract uninstallExtension(id: string): Promise<void>;
    /**
     * Installs a Progressive Web App (PWA) and returns its manifest id.
     *
     * @remarks
     *
     * Only available when connected to the browser over a pipe connection. Set
     * `pipe: true` in {@link PuppeteerNode.launch | puppeteer.launch}; the launch
     * option defaults to `false`. The underlying `PWA` CDP domain is not exposed
     * over a WebSocket connection.
     *
     * The returned manifest id echoes {@link InstallPWAOptions.manifestId}, so it
     * can be passed directly to {@link Browser.launchPWA},
     * {@link Browser.getPWAState}, or {@link Browser.uninstallPWA}.
     */
    abstract installPWA(options: InstallPWAOptions): Promise<string>;
    /**
     * Uninstalls a previously installed Progressive Web App (PWA).
     *
     * @remarks
     *
     * Only available over a pipe connection. See {@link Browser.installPWA}.
     */
    abstract uninstallPWA(options: UninstallPWAOptions): Promise<void>;
    /**
     * Launches an installed Progressive Web App (PWA) and resolves with the
     * {@link Page | page} backing the app window.
     *
     * @remarks
     *
     * Only available over a pipe connection. See {@link Browser.installPWA}.
     *
     * `PWA.launch` resolves with the id of the launched _tab_ target. Puppeteer
     * does not expose tab targets through {@link Browser.targets}; this method
     * instead resolves with the tab's child page target (the app's web contents).
     * If Chromium focuses an existing app window, this returns that window's
     * existing page.
     */
    abstract launchPWA(options: LaunchPWAOptions): Promise<Page>;
    /**
     * Returns the OS-integration state of an installed Progressive Web App (PWA),
     * such as its badge count and registered file handlers.
     *
     * @remarks
     *
     * Only available over a pipe connection. See {@link Browser.installPWA}.
     * Meaningful only for an app that is currently installed; querying an
     * unknown manifest id rejects.
     */
    abstract getPWAState(options: GetPWAStateOptions): Promise<PWAState>;
    /**
     * Gets a list of {@link ScreenInfo | screen information objects}.
     */
    abstract screens(): Promise<ScreenInfo[]>;
    /**
     * Adds a new screen, returns the added {@link ScreenInfo | screen information object}.
     *
     * @remarks
     *
     * Only supported in headless mode.
     */
    abstract addScreen(params: AddScreenParams): Promise<ScreenInfo>;
    /**
     * Removes a screen.
     *
     * @remarks
     *
     * Only supported in headless mode. Fails if the primary screen id is specified.
     */
    abstract removeScreen(screenId: string): Promise<void>;
    /**
     * Whether Puppeteer is connected to this {@link Browser | browser}.
     */
    abstract get connected(): boolean;
    [disposeSymbol](): void;
    [asyncDisposeSymbol](): Promise<void>;
    /**
     * @internal
     */
    abstract get protocol(): ProtocolType;
    /**
     * Get debug information from Puppeteer.
     *
     * @remarks
     *
     * Currently, includes pending protocol calls. In the future, we might add more info.
     *
     * @public
     * @experimental
     */
    abstract get debugInfo(): DebugInfo;
    /**
     * @internal
     */
    abstract isNetworkEnabled(): boolean;
    /**
     * Retrieves a map of all extensions installed in the browser, where the keys
     * are extension IDs and the values are the corresponding {@link Extension} instances.
     *
     * @public
     */
    abstract extensions(): Promise<Map<string, Extension>>;
    /**
     * @internal
     */
    abstract isIssuesEnabled(): boolean;
}
//# sourceMappingURL=Browser.d.ts.map