/** * Network + console evidence for QA (2026-10). * * The rendered DOM can look perfect while the API behind it is wrong: a 200 * with an empty body, a field the form sent that the server ignored, a * duplicated submit, a CORS failure surfaced as a generic toast. None of that * is visible to a screenshot, so the QA agent needs the request/response * stream and the console. * * This collector is bounded (it lives for a whole browser session) and keeps * no request bodies larger than a readable excerpt. It NEVER stores an * Authorization/Cookie header value — headers are reduced to an allow-list of * non-secret names plus the content type. */ import { type CdpPage } from './cdp'; export interface NetworkEntry { id: string; method: string; url: string; status?: number; mimeType?: string; resourceType?: string; failed?: string; /** CDP blocked reason (e.g. `aborted`, `blocked-by-client`) — never a secret. */ blockedReason?: string; /** CORS error status when the failure is a CORS rejection. */ corsErrorStatus?: string; /** Redirect target when the response is a 3xx with a location. */ redirectUrl?: string; /** Request payload excerpt (form/JSON body), when CDP exposes it. */ requestBody?: string; /** Response body excerpt for JSON/text responses. */ responseBody?: string; startedAt: number; durationMs?: number; } export interface ConsoleEntry { level: 'error' | 'warning' | 'log' | 'info'; text: string; url?: string; at: number; } /** One WebSocket frame captured from the page (text only, bounded). */ export interface WebSocketFrame { direction: 'sent' | 'received'; payload: string; at: number; } /** * Collector health, surfaced to the agent and written into the QA evidence * (2026-10). A silent empty `requests` list was indistinguishable from "the * page made no API calls"; this says which it is. */ export interface NetworkLogStatus { enabled: boolean; domainError?: string; requests: number; responses: number; failures: number; websockets: number; lastEventAt: number | null; } /** * HARD ceiling for ONE snapshot's body text (2026-10-25). * * A caller may legally ask for 300 requests × 20 000 chars, which is ~12 MB of * bodies on a single socket.io frame. Engine.io closes the transport above its * `maxHttpBufferSize`, and the caller sees that as `Bridge disconnected` - the * same symptom as a dead bridge, with the evidence lost. The gateway now allows * 4 MB, and this budget keeps a snapshot comfortably below it by lowering the * per-body cap (and, as a last resort, dropping bodies) instead of failing. * `truncated` tells the caller what happened, so the evidence document can say * it was trimmed rather than silently showing less. */ export declare const SNAPSHOT_BODY_BUDGET_CHARS = 1500000; /** * Static-asset test for tiered retention (2026-10): pages, scripts, styles, * images, fonts and Next.js chunks must never evict API traffic. API = * everything that is not a page load or a static asset. */ export declare function isStaticAssetUrl(url: string, resourceType?: string): boolean; /** * Preserve a finished redirect hop (2026-10). * * CDP reuses one request id across a whole redirect chain: every hop after * the first arrives as `requestWillBeSent` carrying `redirectResponse`, and a * naive `requests.set(id, entry)` overwrites the original POST (method + URL * + request body) with the follow-up GET. For login/signup flows (POST → * 302 → GET) that deletes exactly the request the test made, so the evidence * shows what the server returned but never what the agent sent. * * Pure (maps in, maps mutated) so the policy is pinned by a unit test rather * than discovered behind a live browser. */ export declare function preserveRedirectHop(requests: Map, order: string[], id: string): void; /** * Fit a snapshot's bodies into ONE frame (2026-10-25). * * Halves the per-body cap until the total body text fits `budget`; if even the * floor does not fit, drops bodies entirely (URLs, statuses and timings stay). * Pure so the policy is pinned by a test rather than discovered by a transport * closing in production. */ export declare function capSnapshotBodies(entries: T[], bodyCap: number, budget?: number): { entries: T[]; bodyCap: number; truncated: boolean; }; /** * Collects Network.* / Runtime.consoleAPICalled / Log.entryAdded events for one * attached page. `attach` is idempotent per page (connect + connect-to-tab both * call it). */ export declare class NetworkLog { private requests; private order; private console; private webSockets; private attached; /** Read cursor used by `clear` — the evidence buffer is NEVER deleted. */ private requestCursor; private consoleCursor; private enabled; private domainError; private lastEventAt; attach(page: CdpPage): Promise; private pushConsole; /** * Read the collected evidence. Bodies are fetched on demand (CDP keeps them * only until navigation), so the caller gets real request/response excerpts * instead of just URLs. Response bodies were already captured eagerly on * `loadingFinished`; request bodies get the same second chance here when the * event-time read raced or was never inline — otherwise the evidence shows * what the server returned but not what the agent sent. */ snapshot(page: CdpPage | null, opts?: { limit?: number; clear?: boolean; onlyProblems?: boolean; /** Per-body cap for THIS read (capture itself keeps up to 20 000). */ maxBodyChars?: number; /** Skip the first N entries AFTER all other filters (paging). */ offset?: number; /** Only entries started at/after this epoch ms (per-action deltas). */ since?: number; /** Only entries AFTER this request id in session order (paging). */ afterId?: string; }): Promise<{ requests: NetworkEntry[]; console: ConsoleEntry[]; websockets: WebSocketFrame[]; status: NetworkLogStatus; /** True when the frame budget forced a smaller body cap (or none). */ truncated?: boolean; /** The per-body cap actually used, when it differs from the request. */ bodyCap?: number; }>; /** Collector health + counts, written into every network read/evidence doc. */ status(): NetworkLogStatus; /** `Network.getResponseBody` wired through the pending-map CDP client. */ protected getResponseBody(page: CdpPage, requestId: string): Promise<{ body?: string; base64?: boolean; } | null>; /** * `Network.getRequestPostData` wired through the pending-map CDP client. * Unlike the response call there is no base64 flag — CDP returns post data * as text (form/JSON/multipart); binary uploads simply come back absent. */ protected getRequestPostData(page: CdpPage, requestId: string): Promise; reset(): void; /** * Requests still in flight (no response and no failure yet), used by the * debug browser's `waitFor { for: "networkIdle" }` and its page state. A * request older than 30s is ignored so a vanished navigation cannot keep the * page "busy" forever. */ pendingCount(): number; /** Most recent console errors (bounded), for the page state summary. */ recentErrors(limit?: number): ConsoleEntry[]; }