/** 浏览器连接模式。 */
export type BrowserMode = "extension" | "cdp";
/** 路由模式：强制扩展 / 强制 CDP。无 auto——显式二选一,不猜。 */
export type RouteMode = "extension" | "cdp";
/**
 * 浏览器句柄。由 open() 返回。
 * 标识一个已打开的浏览器实例（extension 模式或 CDP 直连）。
 * 不可变，没有“切当前 tab”的操作。
 */
export interface BrowserHandle {
    /** 连接模式：extension（浏览器扩展）或 cdp（Playwright CDP）。 */
    mode: BrowserMode;
    /** 启动通知信息，如 profile 路径、建议等。 */
    notice?: {
        level?: "info" | "warn" | "error";
        message: string;
    } | string | null;
    /** 所有者标识。 */
    ownerId: string;
    /** CDP 模式的 WebSocket 端点。 */
    wsEndpoint?: string;
}
/**
 * 标签页句柄。由 newTab()/listTabs() 返回，在 operate() 中作为 pageHandle 传入。
 * pageId 是 browserd 维护的 page registry key（如 "p1"、"p2"），是 operate 的必备字段。
 */
export interface PageHandle {
    /** 连接模式。 */
    mode: BrowserMode;
    /** 内部 pageId，browserd 维护的 page registry key。格式如 "p1"、"p2"。 */
    pageId: string;
    /** 标签页 URL。 */
    url?: string;
    /** 浏览器 tabId（仅 extension 模式）。 */
    tabId?: string;
    /** 所有者标识。 */
    ownerId?: string;
}
/** browser.open() 选项。 */
export interface BrowserOpenOptions {
    /** 是否无头启动（仅 CDP 模式生效，扩展模式忽略）。默认 false。 */
    headless?: boolean;
    /** 路由模式：auto（自动）/ extension / cdp。默认 auto。 */
    routeMode?: RouteMode;
    /** Chrome 可执行文件路径。不传则自动查找。 */
    executablePath?: string;
    /**
     * 浏览器归属。
     * - "browserd"（默认）：browserd 自己启动/关闭 Chrome。
     * - "external"：Chrome 由外部进程管理，browserd 只启动 extension WS server 并等待扩展连接。
     *   适用于 CI/E2E（测试 harness 用 Playwright 启动 CFT + --load-extension），
     *   也适用于"Chrome 已在跑、只想接入 extension 通道"的集成场景。
     */
    browserOwner?: "browserd" | "external";
    /** external extension 模式下等待扩展 hello/ping 的超时毫秒。默认 30000。 */
    extensionConnectTimeoutMs?: number;
}
/** 标签页信息（newTab/listTabs/reuseTab 统一返回）。包含 pageHandle（operate 传它）+ 元信息。 */
export interface TabInfo {
    /** 标签页句柄（必有 pageId，operate 传它）。 */
    pageHandle: PageHandle;
    /** 标签页 URL。 */
    url?: string;
    /** 标签页标题。 */
    title?: string;
    /** 是否活动标签。 */
    active?: boolean;
    /** reuseTab 返回：是否复用了已有 tab。 */
    reused?: boolean;
}
/** browser.newTab() 选项。 */
export interface BrowserNewTabOptions {
    /** 新标签页打开的 URL。 */
    url?: string;
    /** 强制开新 tab（默认同 host 复用已有 tab）。 */
    force?: boolean;
}
/**
 * operate 动作参数。
 * 不同 action 接受的 params 字段不同；常见动作见 browserd 的 rpcOperate（40+ 个动作）。
 */
export interface BrowserOperateParams {
    /** 标签页句柄（由 newTab()/listTabs() 获取，传 tab.pageHandle）。 */
    pageHandle: PageHandle;
    /** 动作名。常见：click / fill / type / press / hover / goto / screenshot / snapshot / evaluate 等。 */
    action: string;
    /** 动作参数。具体字段因 action 而异。 */
    params?: Record<string, unknown>;
}
/** Cookie 筛选条件。透传到 browserd。 */
export interface CookieFilter {
    /** Cookie name 筛选。 */
    name?: string;
    /** Cookie domain 筛选。 */
    domain?: string;
    /** Cookie path 筛选。 */
    path?: string;
    /** 其他筛选条件透传到 browserd。 */
    [key: string]: unknown;
}
/** reuseTab() 选项。 */
export interface ReuseTabOptions {
    /** URL 匹配正则。找到第一个 url 匹配的 tab 复用（切过去）；找不到则 newTab。 */
    urlMatch: RegExp;
    /** 未匹配时 newTab 打开的 URL。 */
    url?: string;
}
/** waitForDownload() 选项。基于当前路由的浏览器下载状态监听。 */
export interface WaitForDownloadOptions {
    /** 下载 id。提供时优先按 id 等待。 */
    id?: number;
    /** 文件名匹配正则源串（如 "每日数据_.*\\.xlsx$"）。 */
    filenameRegex?: string;
    /** 只看 startTime > sinceMs 的下载（下载前时间戳，防止命中旧下载）。 */
    sinceMs?: number;
    /** 轮询超时（毫秒）。默认 60000。 */
    timeoutMs?: number;
    /** 轮询间隔（毫秒）。默认 2000。 */
    intervalMs?: number;
}
/** downloadUrl() 选项。由当前路由触发真实浏览器下载。 */
export interface DownloadUrlOptions {
    /** 要下载的 URL。使用 Chrome 网络栈，继承当前 profile/cookie。 */
    url: string;
    /** 建议保存文件名。应为相对路径/文件名，不应是绝对路径。 */
    filename?: string;
    /** 冲突处理。默认 uniquify。 */
    conflictAction?: "uniquify" | "overwrite" | "prompt";
    /** 是否弹出另存为对话框。自动化默认 false。 */
    saveAs?: boolean;
}
/** 单个下载状态摘要。 */
export interface DownloadSummary {
    /** 下载 id。 */
    id: number;
    /** 本地文件名（绝对路径）。 */
    filename: string;
    /** 下载源 URL。 */
    url: string;
    /** 下载状态：进行中/中断/完成。 */
    state: "in_progress" | "interrupted" | "complete";
    /** 已接收字节。 */
    bytesReceived: number;
    /** 总字节（-1 = 未知）。 */
    totalBytes: number;
    /** 文件是否仍存在于磁盘。 */
    exists: boolean;
}
/** Chrome automatic downloads content setting. */
export type AutomaticDownloadsSetting = "allow" | "block" | "ask";
/** allowAutomaticDownloads() 选项。 */
export interface AllowAutomaticDownloadsOptions {
    /** Chrome contentSettings pattern, e.g. "https://one.alimama.com/*". */
    primaryPattern: string;
    /** Secondary pattern, defaults to "<all_urls>". */
    secondaryPattern?: string;
    /** Incognito scope. */
    scope?: "regular" | "incognito_session_only";
}
/** get/reset automatic downloads setting options. */
export interface AutomaticDownloadsSettingOptions {
    /** Concrete URL used for querying current setting, e.g. "https://one.alimama.com/". */
    primaryUrl?: string;
    /** Pattern used for reset, e.g. "https://one.alimama.com/*". */
    primaryPattern?: string;
    /** Secondary URL or pattern. Defaults depend on API. */
    secondaryUrl?: string;
    secondaryPattern?: string;
    /** Incognito flag/scope. */
    incognito?: boolean;
    scope?: "regular" | "incognito_session_only";
}
/** automatic downloads content setting result. */
export interface AutomaticDownloadsSettingResult {
    setting: AutomaticDownloadsSetting;
    source?: string;
    primaryUrl?: string;
    primaryPattern?: string;
    secondaryPattern?: string;
}
/** waitFor() 的 URL 匹配。字符串按包含关系匹配，RegExp 按正则匹配。 */
export type WaitForUrlPattern = string | RegExp;
export interface WaitForTabTarget {
    /** 同时提供多个字段时全部满足。 */
    pageId?: string;
    tabId?: string;
    url?: WaitForUrlPattern;
    /** 默认 present；absent 用于等待本次任务 Tab 消失。 */
    state?: "present" | "absent";
}
export interface WaitForFrameTarget {
    /** 同时提供多个字段时全部满足。 */
    frameId?: number;
    parentFrameId?: number;
    url?: WaitForUrlPattern;
    /** 默认 present；absent 用于等待验证 Frame 被移除。 */
    state?: "present" | "absent";
}
export interface WaitForConditionContext {
    attempt: number;
    elapsedMs: number;
}
/** waitFor() 选项。统一等待 DOM、Tab、Frame 或调用方组合状态。 */
export interface WaitForOptions {
    /** DOM/Frame 检测和显式刷新使用的标签页句柄。 */
    tab?: PageHandle;
    /** 目标所在的 frameId（跨域 iframe 内的元素必须传，顶层元素不传）。 */
    frameId?: number;
    /** CSS selector 等待出现（与 text 二选一或都传，任一满足即返回）。 */
    selector?: string;
    /** 等待页面出现的文本（innerText 含此子串即满足）。 */
    text?: string;
    /** 通过 listTabs 等待指定 Tab 出现或消失。 */
    tabTarget?: WaitForTabTarget;
    /** 通过 listFrames 等待指定 Frame 出现或消失；必须同时提供 tab。 */
    frameTarget?: WaitForFrameTarget;
    /**
     * 复杂业务状态读取器。返回 truthy 即满足，返回值原样进入 WaitForResult.value。
     * 可与其他目标组合，任意一个满足即返回。
     */
    condition?: (context: WaitForConditionContext) => unknown | Promise<unknown>;
    /** 用于错误信息和日志辨识等待目标。 */
    description?: string;
    /** 单次轮询总超时（毫秒），到了若未满足触发一次刷新。默认 10000。 */
    pollTimeoutMs?: number;
    /** 轮询间隔（毫秒）。默认 1000。 */
    intervalMs?: number;
    /**
     * 连续检测不到时刷新页面的最大次数。
     * 旧 DOM selector/text 等待默认 2；Tab/Frame/condition 等状态等待默认 0，防止刷新破坏状态机。
     */
    maxRefresh?: number;
    /** 刷新后等待页面就绪的时间（毫秒）。默认 5000。 */
    refreshSettleMs?: number;
    /** 读取异常时立即抛出，避免把连接、句柄和 Frame 错误伪装成超时。默认 false。 */
    failFastOnError?: boolean;
}
/** waitFor() 结果。 */
export interface WaitForResult {
    /** 是否等到任一目标状态。 */
    ok: boolean;
    /** 实际满足的条件。 */
    matched: "selector" | "text" | "tab" | "frame" | "condition" | null;
    /** condition 的返回值，或命中的 Tab / Frame。absent 目标命中时为 null。 */
    value?: unknown;
    /** 总检测次数。 */
    attempts: number;
    /** 未启用 failFastOnError 时最后一次读取错误。 */
    lastError?: string;
    /** 刷新了几次才等到（0 = 未刷新直接等到）。 */
    refreshCount: number;
    /** 总耗时（毫秒）。 */
    elapsedMs: number;
}
/** 待设置的 Cookie。字段对齐 CDP Cookie 协议。 */
export interface CookieSet {
    /** Cookie 名称。 */
    name: string;
    /** Cookie 值。 */
    value: string;
    /** Cookie 作用 URL（CDP 路由需要 url 或 domain）。 */
    url?: string;
    /** Cookie 作用 domain。 */
    domain?: string;
    /** Cookie 作用 path。默认 "/"。 */
    path?: string;
    /** 是否仅 HTTPS。 */
    secure?: boolean;
    /** 是否仅 HTTP（不可被 JS 读取）。 */
    httpOnly?: boolean;
}
/** browserd RPC 方法名（与 browserd.cjs 的 switch 一一对应）。 */
export type RpcMethod = "open" | "newTab" | "listTabs" | "operate" | "getCookies" | "setCookies" | "clearCookies" | "closeBrowser" | "close" | "reuseTab" | "listDownloads" | "downloadUrl" | "getDownload" | "waitForDownload" | "allowAutomaticDownloads" | "getAutomaticDownloadsSetting" | "resetAutomaticDownloadsSetting";
/** RPC 请求信封。 */
export interface RpcRequest {
    id: number;
    method: RpcMethod;
    params?: Record<string, unknown>;
}
/** RPC 成功响应。 */
export interface RpcOkResponse {
    id: number;
    ok: true;
    result: unknown;
}
/** RPC 失败响应。 */
export interface RpcErrorResponse {
    id?: number;
    ok: false;
    error: string;
}
/** RPC 响应（成功或失败）。 */
export type RpcResponse = RpcOkResponse | RpcErrorResponse;
//# sourceMappingURL=protocol.d.ts.map