browserscale-ts 1.4.0 → 1.7.0

package/dist/client.d.ts

@@ -1,10 +1,14 @@
 import type { Transport } from "@connectrpc/connect";
 import type { Locator } from "./locator.ts";
-import type { DOMResult, DragResult, ElementResult, EvaluateResult, InterceptedRequest, InterceptedResponse, InspectResult, NavigateResult, PageInfo, ScreenshotResult, ReadCanvasResult, SelectOptionResult, WaitResult, IceServer, ReactionInfo } from "./types.ts";
+import type { DOMResult, DragResult, ElementResult, EvaluateResult, InterceptedRequest, InterceptedResponse, InspectResult, NavigateResult, NetworkCaptureOptions, PageInfo, ScreenshotResult, ReadCanvasResult, SelectOptionResult, WaitResult, IceServer, StreamAnswer, ReactionInfo } from "./types.ts";
 import type { ClickOpts, FillOpts, GetDOMOpts, GetObservationOpts, LoadHTMLOpts, NavigateOpts, ReactionOpts, ScreenshotOpts, ReadCanvasOpts, SelectOpts, WaitOpts } from "./options.ts";
 import type { HeaderModification, RequestPattern } from "./network.ts";
+import { NetworkCapture, type NetworkExchangeHandler } from "./network-capture.ts";
+import { ScriptFollow, ScriptRun, type ScriptEventHandler, type ScriptResult, type ScriptRunInfo } from "./scripts.ts";
+import { DomMirror, type DomChangeHandler, type DomMirrorOptions, type DomResyncHandler, type DomSnapshot } from "./dom-mirror.ts";
 import type { CookieParam } from "./cookies.ts";
 import type { StorageOriginEntry } from "./storage.ts";
+import type { AuthSession } from "./auth-session.ts";
 /**
  * CloudBrowser is the SDK-side handle for an active browserscale browser session.
  *
@@ -680,6 +684,180 @@ export declare class CloudBrowser {
         modifications?: HeaderModification[];
         timeoutMs?: number;
     }): Promise<InterceptedRequest | null>;
+    /**
+     * Starts capturing the session's network traffic and returns a live view of
+     * it.
+     *
+     * Every request matching `opts.patterns` is reported once it completes, and
+     * "every request" is literal: capture sits in the browser process rather than
+     * in a page, so cross-process iframes, workers and service workers are
+     * included, the headers are the ones actually put on the wire (Cookie and
+     * Sec-* included), and each hop of a redirect chain arrives as its own
+     * exchange. Requests are never paused, so the page loads at full speed.
+     *
+     * This resolves as soon as the capture is running; onExchange then fires in
+     * the background while you drive the browser. The capture is armed only after
+     * the subscription exists, so nothing that happens after this resolves is
+     * missed. Call {@link NetworkCapture.stop} when done — it disarms the capture
+     * server-side, which an aborted transport alone does not.
+     *
+     * @param opts - which requests to capture and whether to keep bodies
+     * @param onExchange - called per exchange; see {@link NetworkExchangeHandler}
+     *   for the ordering and blocking rules
+     *
+     * @returns NetworkCapture handle for stopping the capture and inspecting how
+     *   it ended
+     *
+     * @throws UNKNOWN_ERROR - the capture could not be started
+     *
+     * @example
+     * const capture = await browser.captureNetwork(
+     *   { patterns: ["*\/api/*"], bodies: "text" },
+     *   (ex) => console.log(ex.statusCode, ex.method, ex.url),
+     * );
+     * try {
+     *   await browser.navigate("https://example.com");
+     * } finally {
+     *   await capture.stop();
+     * }
+     */
+    captureNetwork(opts: NetworkCaptureOptions, onExchange: NetworkExchangeHandler): Promise<NetworkCapture>;
+    /**
+     * Arms a capture without subscribing to it.
+     *
+     * Use it when the reader lives somewhere else — another tab, or a later
+     * {@link createWebSocketBrowser} against the same session. Most callers want
+     * {@link CloudBrowser.captureNetwork} instead, which arms and subscribes
+     * together. Calling this again replaces the running capture.
+     *
+     * @param opts - which requests to capture and whether to keep bodies
+     *
+     * @throws UNKNOWN_ERROR - the capture could not be started
+     */
+    startNetworkCapture(opts: NetworkCaptureOptions): Promise<void>;
+    /**
+     * Disarms the session's capture.
+     *
+     * @returns whether a capture was running
+     *
+     * @throws UNKNOWN_ERROR - the capture could not be stopped
+     */
+    stopNetworkCapture(): Promise<boolean>;
+    /**
+     * Subscribes to the session's capture without arming one, for reading a
+     * capture that {@link CloudBrowser.startNetworkCapture} armed elsewhere.
+     * Several readers can watch the same capture, each with its own buffer.
+     *
+     * Stopping the returned view detaches this reader and leaves the capture
+     * running, since other readers may still be attached.
+     *
+     * @param onExchange - called per exchange; see {@link NetworkExchangeHandler}
+     *   for the ordering and blocking rules
+     *
+     * @returns NetworkCapture attached to whatever capture is running; onExchange
+     *   simply never fires when none is
+     *
+     * @throws UNKNOWN_ERROR - the subscription could not be opened
+     */
+    streamNetworkExchanges(onExchange: NetworkExchangeHandler): Promise<NetworkCapture>;
+    /**
+     * Opens the stream and waits for the server to acknowledge the subscription
+     * before resolving.
+     *
+     * Merely calling the streaming method does not wait for the server to start
+     * handling it, so arming a capture straight after could outrun the
+     * subscription and lose the first exchanges. The response headers arrive once
+     * the handler is subscribed, and onHeader reports exactly that — over native
+     * gRPC as well as over the WebSocket transport, which forwards the event as
+     * its own frame.
+     */
+    private subscribeNetworkExchanges;
+    /**
+     * Starts a live copy of a frame's DOM and keeps it up to date.
+     *
+     * The browser sends the top of the tree once, then reports only what changed
+     * in the part you expanded. Everything else costs a child count per batch, no
+     * matter how much churns inside it — which is what makes this usable on a
+     * page that rewrites a list sixty times a second, where re-fetching the
+     * document on a timer is not.
+     *
+     * Expand and collapse as the user opens and closes nodes; that is what moves
+     * the boundary of what gets reported. The returned {@link DomMirror} holds
+     * the tree and exposes `expand`, `collapse` and `reveal`.
+     *
+     * The handler runs after each applied batch. `mirror.root` is a new object
+     * whenever anything under it changed and the untouched parts keep their
+     * identity, so rendering straight from it with memoized components is cheap.
+     *
+     * One mirror covers the whole page as ONE tree. An `<iframe>` is an
+     * ordinary element whose single child is the document it hosts; expanding it
+     * fetches that document and starts mirroring the frame, however deeply
+     * nested and whether or not it is cross-origin. Unlike the inlining
+     * {@link CloudBrowser.getDOM} does, these regions stay live — and frames
+     * nobody opened cost nothing.
+     *
+     * ```ts
+     * const mirror = await browser.mirrorDom({ pierce: true }, () => {
+     *   render(mirror.root);
+     * });
+     * await mirror.expand(bodyNode);
+     * // ...
+     * await mirror.stop();
+     * ```
+     *
+     * @param opts initial depth and whether to pierce shadow roots
+     * @param onChange called after every change, including the first snapshot
+     * @param onResync called when the copy had to be rebuilt, after the new tree
+     *   is in place. Rebuilding is automatic; this is for telling the user why
+     *   their expanded nodes collapsed.
+     * @throws UNKNOWN_ERROR - the mirror could not be started
+     */
+    mirrorDom(opts: DomMirrorOptions, onChange: DomChangeHandler, onResync?: DomResyncHandler): Promise<DomMirror>;
+    /**
+     * Starts (or restarts) the page's mirror and returns the main document,
+     * without subscribing to changes. {@link CloudBrowser.mirrorDom} is what you
+     * normally want; this is the raw command.
+     */
+    startDomMirror(opts?: DomMirrorOptions): Promise<DomSnapshot>;
+    /** Stops the page's mirror, every frame of it. Idempotent. */
+    stopDomMirror(): Promise<void>;
+    /**
+     * Fetches a node's children and starts reporting changes inside them.
+     * {@link DomMirror.expand} calls this and folds the result into the tree.
+     *
+     * On an `<iframe>` the one child is the document it hosts, and this call is
+     * what starts mirroring that frame.
+     */
+    getDomChildren(backendNodeId: number, frameId?: string, depth?: number): Promise<{
+        children: string;
+        seq: number;
+    }>;
+    /**
+     * Stops reporting changes inside a node, and inside any frame below it.
+     * {@link DomMirror.collapse} calls this.
+     */
+    releaseDomSubtree(backendNodeId: number, frameId?: string): Promise<void>;
+    /**
+     * Returns the chain from the main document down to a node, each ancestor
+     * with its own children, crossing into frames where it has to and starting
+     * the ones it passes through. {@link DomMirror.reveal} calls this and
+     * splices it in.
+     */
+    revealDomNode(backendNodeId: number, frameId?: string): Promise<{
+        path: string;
+        seq: number;
+    }>;
+    /**
+     * A frame's mutation counter, incremented on every change the document sees.
+     * O(1) in the browser and the change detector to poll if you are not
+     * consuming mirror events.
+     *
+     * Prefer this over {@link CloudBrowser.getDOMHash}, which serializes the
+     * whole tree just to hash it. The two answer different questions: a hash
+     * compares content, a revision only says whether this document moved since
+     * you last asked.
+     */
+    getDomRevision(frameId?: string): Promise<number>;
     /**
      * Returns all cookies currently stored in this session's browser context.
      *
@@ -780,6 +958,39 @@ export declare class CloudBrowser {
      * await browser.clearStorage();
      */
     clearStorage(origin?: string): Promise<void>;
+    /**
+     * Exports the signed-in primary account and DBSC sessions of this
+     * browser context.
+     *
+     * State is read in the browser process, so no page needs to be open.
+     * Returns undefined when the context has neither a signed-in account
+     * nor DBSC sessions.
+     *
+     * @returns AuthSession, or undefined when there is nothing to export
+     *
+     * @throws UNKNOWN_ERROR - the auth session could not be read
+     *
+     * @example
+     * const auth = await browser.getAuthSession();
+     * if (auth) await fs.writeFile("auth.json", JSON.stringify(auth));
+     */
+    getAuthSession(): Promise<AuthSession | undefined>;
+    /**
+     * Imports an auth session so the context comes up signed in (and syncing
+     * if syncConsent) with its DBSC sessions restored.
+     *
+     * Call it before navigating. Pair with setCookies() / setStorage() to
+     * restore a full persona.
+     *
+     * @param session - session as returned by getAuthSession()
+     *
+     * @throws UNKNOWN_ERROR - the auth session could not be written
+     *
+     * @example
+     * await browser.setAuthSession(saved);
+     * await browser.navigate("https://mail.google.com");
+     */
+    setAuthSession(session: AuthSession): Promise<void>;
     /**
      * Hit-tests at the viewport-relative (x, y) and returns the topmost
      * element under that point.
@@ -967,22 +1178,22 @@ export declare class CloudBrowser {
     getStreamConfig(): Promise<IceServer[]>;
     /**
      * Answers your WebRTC SDP offer and starts streaming the page as a video
-     * track, returning the SDP answer to set as your peer's remote description.
-     * The browser is the answerer; you are the offerer (see
+     * track. The browser is the answerer; you are the offerer (see
      * {@link getStreamConfig} for the credentials to build the offer).
      *
      * @param offerSdp - your `RTCPeerConnection`'s SDP offer
      *
-     * @returns the SDP answer to apply as the remote description
+     * @returns the SDP answer to apply as the remote description, plus the
+     *   viewport to map input coordinates into
      *
      * @throws UNKNOWN_ERROR - the offer was empty, TURN is unconfigured, or the
      *   browser could not negotiate the stream
      *
      * @example
-     * const answer = await browser.startStream(offer.sdp);
-     * await pc.setRemoteDescription({ type: "answer", sdp: answer });
+     * const { answerSdp, viewport } = await browser.startStream(offer.sdp);
+     * await pc.setRemoteDescription({ type: "answer", sdp: answerSdp });
      */
-    startStream(offerSdp: string): Promise<string>;
+    startStream(offerSdp: string): Promise<StreamAnswer>;
     /**
      * Tears down the live video stream for the session's page. Safe to call even
      * if no stream is running.
@@ -1051,6 +1262,138 @@ export declare class CloudBrowser {
      * for (const r of pending) console.log(r.reactionId, r.matchSelector);
      */
     listReactions(): Promise<ReactionInfo[]>;
+    /**
+     * Runs `source` in the session's browser and waits for it to finish.
+     *
+     * The script executes in a V8 isolate inside the browser process, not in the
+     * page, and reaches the same operations this SDK exposes through a `browser`
+     * object it is handed. The difference is cost: each call is a function call in
+     * the browser rather than a network round trip, so work that is chatty by
+     * nature — polling for a selector, walking a list, following pagination —
+     * runs in microseconds per step instead of tens of milliseconds.
+     *
+     * This waits for as long as the script runs, and cannot be bounded: the run
+     * id needed to cancel only arrives with the reply. Use
+     * {@link CloudBrowser.startScript} when the script may outlive the caller's
+     * patience, or {@link CloudBrowser.stopScripts} to abandon what this session
+     * is running.
+     *
+     * @param source - JavaScript to execute; its return value comes back as JSON
+     *
+     * @returns the return value and the script's whole console output. A script
+     *   that threw is reported as `success: false`, not as a rejection
+     *
+     * @throws UNKNOWN_ERROR - the script could not be delivered to the browser
+     *
+     * @example
+     * const result = await browser.runScript(`
+     *   await browser.navigate("https://example.com");
+     *   const items = [];
+     *   for (const el of await browser.getDOM().querySelectorAll("h1")) {
+     *     items.push(el.textContent);
+     *   }
+     *   return items;
+     * `);
+     * console.log(result.success, result.result);
+     */
+    runScript(source: string): Promise<ScriptResult>;
+    /**
+     * Launches `source` in the session's browser and resolves as soon as the run
+     * is under way.
+     *
+     * The counterpart to {@link CloudBrowser.runScript}, for scripts that are not
+     * worth waiting on: a watcher that runs for the life of the session, work
+     * that should survive this page. Output arrives at `onEvent` while the caller
+     * gets on with something else, and {@link ScriptRun.wait} collects the
+     * outcome if it is wanted.
+     *
+     * Subscribing has to happen before the launch, because a detached run's
+     * output is not kept anywhere — the browser rejects a start with nobody
+     * listening rather than discard the script's log and result. This call does
+     * both in that order, so nothing the script prints is missed.
+     *
+     * @param source - JavaScript to execute
+     * @param onEvent - called per log line and once for the outcome; see
+     *   {@link ScriptEventHandler} for the ordering and blocking rules
+     *
+     * @returns ScriptRun handle for awaiting or cancelling the run
+     *
+     * @throws UNKNOWN_ERROR - the run could not be started
+     *
+     * @example
+     * const run = await browser.startScript(source, (ev) => {
+     *   if (ev.log) console.log(ev.log.level, ev.log.message);
+     * });
+     * const outcome = await run.wait();
+     */
+    startScript(source: string, onEvent: ScriptEventHandler): Promise<ScriptRun>;
+    /**
+     * Watches script output in this session without starting anything.
+     *
+     * For the case {@link CloudBrowser.startScript} cannot cover: a run somebody
+     * else launched, or one this page started before it reloaded. Several readers
+     * can watch the same session, each with its own buffer.
+     *
+     * Only output produced from now on arrives — lines printed before the
+     * subscription existed are not kept. A run that has already finished is
+     * therefore invisible here; {@link CloudBrowser.listScriptRuns} is how you
+     * tell that apart from a run that is merely quiet.
+     *
+     * @param runId - run to follow, or `""` to follow every run in the session
+     * @param onEvent - called per event; see {@link ScriptEventHandler} for the
+     *   ordering and blocking rules
+     *
+     * @returns ScriptFollow handle for stopping the subscription
+     *
+     * @throws UNKNOWN_ERROR - the subscription could not be opened
+     *
+     * @example
+     * const follow = await browser.followScript(runId, (ev) => {
+     *   if (ev.log) console.log(ev.log.message);
+     * });
+     * try {
+     *   await follow.wait();
+     * } finally {
+     *   await follow.stop();
+     * }
+     */
+    followScript(runId: string, onEvent: ScriptEventHandler): Promise<ScriptFollow>;
+    /**
+     * Cancels runs in this session and reports how many it ended.
+     *
+     * An empty `runId` cancels every run in the session, which is the only form
+     * available to a caller that never learned an id — notably one abandoning a
+     * {@link CloudBrowser.runScript}.
+     *
+     * @param runId - run to cancel, or `""` for all of them
+     *
+     * @returns how many runs were cancelled; 0 when the id named nothing in
+     *   flight
+     *
+     * @throws UNKNOWN_ERROR - the cancel could not be delivered
+     *
+     * @example
+     * await browser.stopScripts(""); // abandon everything running
+     */
+    stopScripts(runId: string): Promise<number>;
+    /**
+     * Reports the scripts still running in this session.
+     *
+     * Only runs in flight — a finished run is reported once on the event stream
+     * and then forgotten, so this is not a history. Its use is finding work this
+     * caller did not start: a script a previous page left behind, which
+     * {@link CloudBrowser.stopScripts} needs an id to name.
+     *
+     * @returns one entry per run still executing
+     *
+     * @throws UNKNOWN_ERROR - the session could not be queried
+     *
+     * @example
+     * for (const run of await browser.listScriptRuns()) {
+     *   console.log(run.runId, run.runningMs);
+     * }
+     */
+    listScriptRuns(): Promise<ScriptRunInfo[]>;
     /**
      * @internal — a reaction match/action must be a css()/js() locator: node()
      * and at() are rejected (a reaction watches for a condition, like a wait).