import type { ReadStagedResult, FillExcelResult } from './xlsx-template'; export declare const BROWSER_BATCH_MAX_STEPS = 20; /** Settle delay between steps so UI frameworks observe each event. */ export declare const BATCH_STEP_SETTLE_MS = 120; export interface BatchStep { action: string; url?: string; x?: number; y?: number; elementIndex?: number; /** * Element ref from getRefs / snapshot refs:true (2026-10). Preferred over * selector/elementIndex: resolved against the live node, with a REF_STALE * refusal instead of a silent miss. */ ref?: string; /** * click: dispatch the full in-page pointer sequence instead of a CDP click * (2026-10). The explicit rescue for a control that ignores a normal click. */ pointer?: boolean; text?: string; key?: string; delta?: number; expression?: string; format?: 'jpeg' | 'png' | 'pdf'; quality?: number; maxChars?: number; /** login step: credentials (opt-in credential entry on the debug browser). */ username?: string; password?: string; /** * login step: the test-account label this login is for (2026-11). A window * tagged for one account refuses another account's login — including here, * or the guarantee could be bypassed by batching the login step. */ actor?: string; /** One-time code for the OTP challenge (a resumed ask_human answer). */ otp?: string; /** fillOtp step: the code + optional digit count + submit mode. */ code?: string; digits?: number; submit?: boolean; stepTimeoutMs?: number; allowCredentials?: boolean; /** attachFile step: the staged file path + an optional CSS selector. */ filePath?: string; /** Generator form (QA): stage bytes first (html/text/data + fileName). */ fileName?: string; html?: string; data?: string; pdf?: boolean; selector?: string; /** The run whose staging directory the file must live in. */ runId?: string; /** downloadFile: direct link (else waits for a triggered download). */ timeoutMs?: number; /** readStagedFile: which sheet + row cap. */ sheet?: string; maxRows?: number; /** fillExcel: template path + writes. */ templatePath?: string; cells?: Record; rows?: Array>; /** type: clear the field (verified) before inserting. */ clearFirst?: boolean; /** waitFor: the condition and its arguments. */ waitFor?: string; urlIncludes?: string; state?: 'open' | 'closed'; loginPhase?: 'username' | 'password' | 'otp' | 'done'; /** Pagination actions. */ page?: number; size?: number; maxPages?: number; /** events: how many + clear after reading. */ since?: number; /** snapshot: include the page text + cap. */ includeText?: boolean; /** dialog: accept/dismiss + prompt text. */ accept?: boolean; promptText?: string; /** snapshot: also return a screenshot. */ screenshot?: boolean; [key: string]: unknown; } export interface BatchStepResult { ok: boolean; action: string; error?: string; [key: string]: unknown; } export interface BatchSummary { results: BatchStepResult[]; count: number; okCount: number; failedCount: number; } /** * Structural minimum of BrowserSession that a batch needs. The real session * satisfies this; tests pass a stub. Deliberately NOT importing the session * class — this module must stay free of CDP imports so it is unit-testable. */ export interface BatchCapableSession { click(x: number, y: number): Promise; /** * Ref-based interaction (2026-10). Optional so a test stub may omit it; the * real BrowserSession always has it. `ref` wins over selector/elementIndex. */ clickRef?(ref: { ref?: string; elementIndex?: number; selector?: string; }): Promise<{ x: number; y: number; refreshedFrom?: string; }>; hover?(x: number, y: number): Promise; /** In-page pointer-sequence click (the rescue for stubborn activators). */ clickPointerRef?(ref: string): Promise<{ x: number; y: number; }>; hoverRef?(ref: { ref?: string; selector?: string; }): Promise<{ x: number; y: number; refreshedFrom?: string; }>; focusRef?(ref: string): Promise<{ ok: boolean; alive: boolean; tag?: string; contentEditable?: boolean; }>; closePopup?(): Promise<{ closed: boolean; popoversLeft: number; }>; getRefs?(): Promise<{ at: number; count: number; refs: unknown[]; lines: string[]; }>; /** Verified typing: resolves with the observed field state, throws when the insert does not land. */ type(text: string, opts?: { clearFirst?: boolean; }): Promise<{ ok: boolean; beforeLength: number | null; afterLength: number | null; focused: string | null; contentEditable: boolean; }>; /** Deterministic login (opt-in credential entry). */ login(opts: { username?: string; password?: string; otp?: string; submit?: boolean; stepTimeoutMs?: number; }): Promise; /** Enable credential entry for the session (opt-in). */ setAllowCredentials?(allow: boolean): void; /** * The test-account label this window is tagged for (2026-11, one window per * identity). Optional so a test stub may omit it; the real BrowserSession * always has it. */ readonly actor?: string | null; /** Tag an untagged window (a tagged window never changes hands). */ setActor?(actor: string | null | undefined): void; press(key: string): Promise; scroll(delta: number): Promise; /** * Set the browser viewport (2026-11, design verification). Optional so a * test stub may omit it; the real BrowserSession always has it. */ setViewport?(width: number, height: number, deviceScaleFactor?: number): Promise<{ width: number; height: number; deviceScaleFactor: number; }>; navigate(url: string): Promise; evaluate(expression: string): Promise; getElements(): Promise>; pageInfo(): Promise; getText(maxChars: number): Promise; getLinks(): Promise; readPage(maxChars: number): Promise; screenshot(format: 'jpeg' | 'png', quality: number): Promise; /** * Attach a staged file to a file input. Optional so a test stub can omit * it - but the real session always has it. */ attachFile?(runId: string, filePath: string, selector?: string, generate?: { fileName?: string; html?: string; pdf?: boolean; text?: string; data?: string; }): Promise<{ ok: boolean; path?: string; error?: string; }>; /** Submit the form on the page. */ submit?(selector?: string): Promise<{ ok: boolean; error?: string; }>; /** * Reset the browser session between test accounts (2026-11): clears cookies * + storage so the next login starts signed out. Same session, no reconnect. */ clearSession?(): Promise<{ ok: boolean; error?: string; }>; /** Segmented OTP fill (2026-10): one digit per cell with auto-submit sense. */ fillOtp?(opts: { code: string; digits?: number; submit?: 'auto' | 'always' | 'never'; }): Promise; /** Manufacture a file in the run's staging dir (QA). */ stageFile?(opts: { runId: string; fileName?: string; html?: string; pdf?: boolean; text?: string; data?: string; }): Promise<{ ok: boolean; path?: string; fileName?: string; bytes?: number; error?: string; }>; /** Download a template into the run's staging dir (QA). */ downloadFile?(opts: { runId: string; url?: string; timeoutMs?: number; }): Promise<{ ok: boolean; path?: string; fileName?: string; bytes?: number; error?: string; }>; /** Read a staged file back (QA). */ readStagedFile?(opts: { runId: string; filePath: string; sheet?: string; maxRows?: number; }): Promise; /** Fill a copy of a staged spreadsheet template (QA). */ fillExcel?(opts: { runId: string; templatePath: string; fileName?: string; cells?: Record; rows?: Array>; sheet?: string; }): Promise; /** * Optional liveness hooks (the real BrowserSession has them; stubs may * omit them, in which case the batch runs unprobed). Kept optional so this * module never needs a CDP import. */ probeAlive?(): Promise; reconnect?(): Promise; /** Rich page state (2026-10): dialogs, toasts, errors, fields. */ snapshot?(opts?: { includeText?: boolean; maxTextChars?: number; maxFields?: number; }): Promise; /** Wait for a page condition, returning the resulting state. */ waitFor?(opts: { for: string; selector?: string; text?: string; urlIncludes?: string; state?: 'open' | 'closed'; loginPhase?: 'username' | 'password' | 'otp' | 'done'; timeoutMs?: number; }): Promise; /** Poll a Cloudflare/CAPTCHA challenge (never clicks unless attempt). */ waitForChallenge?(opts?: { timeoutMs?: number; attempt?: boolean; }): Promise; /** Recent page events (toasts/alerts/dialogs). */ events?(opts?: { limit?: number; clear?: boolean; since?: number; }): Promise; /** Accept/dismiss a native JS dialog. */ dialogAction?(opts: { accept?: boolean; promptText?: string; }): Promise; /** Pagination (2026-10). */ nextPage?(timeoutMs?: number): Promise; prevPage?(timeoutMs?: number): Promise; gotoPage?(page: number, timeoutMs?: number): Promise; setPageSize?(size: number): Promise; collectTable?(opts: { selector?: string; maxPages?: number; maxRows?: number; pageSize?: number; }): Promise; } /** * Run steps sequentially on one session. NEVER throws for step failures — * each is recorded with `ok: false`. Throws only for a malformed envelope. */ export declare function executeBatch(session: BatchCapableSession, steps: BatchStep[], opts?: { settleMs?: number; }): Promise;