browserscale-ts 1.4.0 → 1.7.0

package/README.md

@@ -23,7 +23,7 @@ Rent an isolated browser session in seconds, automate it with human-like input,
   pages, frames, cookies, storage and network state. No local binary.
 - **Parallel isolated contexts** — each task gets its own session, fingerprint
   and lifecycle; large queues never share browser state. Sessions are browser
-  contexts, not VMs or processes, so they spin up in under 50 ms and fan out to
+  contexts, not VMs or processes, so they spin up in under 250 ms and fan out to
   thousands in parallel.
 - **Fingerprint & proxy handling** — pinnable server-side fingerprints,
   native Chrome control without CDP/Playwright/Puppeteer leaks, bring your own
@@ -60,11 +60,37 @@ Rent an isolated browser session in seconds, automate it with human-like input,
   through. Wait for, block, mock or modify requests and responses without
   leaving the SDK; mark repeated assets as static with `setStaticPaths` to
   serve them from a server-side cache and cut proxy bandwidth on repeat runs.
+- **Streaming network capture** — `captureNetwork` reports every request the
+  session completes as it happens, 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, and each hop of a redirect chain arrives as its own exchange.
+  Requests are never paused, so the page loads at full speed.
+- **Live DOM mirror** — `mirrorDom` holds the page as one incrementally updated
+  tree: the browser sends the top once and from then on only what changed in the
+  part you expanded, so a page churning inside a collapsed subtree costs one
+  number per batch instead of a re-serialized document. An `<iframe>` is an
+  ordinary element whose one child is the document it hosts, however deeply
+  nested or cross-origin, and `getDomRevision` is the O(1) change detector to
+  poll when you are not consuming events.
 - **Agent-friendly observation** — `getObservation` returns one line per visible
   element across every frame, under headers carrying the URL, title and scroll
   offset, with live form state (typed values, checkbox state, `<select>`
   options) and a node handle to act on. A model reasons over what matters
   instead of raw HTML, and doesn't need a JS round-trip to ask where it is.
+- **Scripts that run inside the browser** — `runScript` sends JavaScript to the
+  session and runs it in the browser process itself, with a `browser` object
+  giving it the same operations this SDK exposes — but as local calls rather than
+  network round trips, so a loop that polls or walks a list costs microseconds
+  per step instead of tens of milliseconds. The log streams back as the script
+  produces it. `startScript` leaves a script running without the caller, which is
+  how work outlives the process that started it, and `followScript` attaches to
+  one already under way.
+- **Sessions you can find again** — `listBrowsers` reports what an API key is
+  paying for: ids, proxy, egress address and remaining rental. A session
+  therefore outlives the process that rented it — recover it after a restart, or
+  from another machine entirely, and hand the `grpcUrl` it reports straight to
+  `connectSession`.
 - **Flow-optimized TypeScript** — fully typed promise-based API, `wait` races
   multiple outcomes, JS locators target elements by page logic when CSS is
   not enough. Runs in Node.js (native gRPC) and the browser (WebSocket via
@@ -120,18 +146,23 @@ reports the element that occluded the click.
 | --- | --- |
 | `rentBrowser(cfg)` | Rent a fresh session (`new BrowserConfig(key, secs, host, port, user, pass)`). |
 | `connectSession(grpcUrl, apiKey, sessionId)` | Attach to an existing session by id (from a prior rent). |
+| `listBrowsers(apiKey)` | The sessions a key currently holds, each with the `grpcUrl` to hand to `connectSession`. |
 | `browser.navigate(url, opts?)` | Load a URL. |
 | `browser.wait(condition, opts?)` | Wait for a locator condition; returns the matched `frameId`. |
 | `browser.click(target, opts?)` | Human-like click; throws a rich `ClickError` on failure. |
 | `browser.fill(target, text, opts?)` | Per-key typing that fires real input events; `insertText` for bulk commit. |
 | `browser.evaluate(expr)` | Run JS in the page/frame and get a typed value back. |
+| `browser.runScript(source)` | Run JavaScript in the browser process, where every operation is a local call; `startScript` leaves it running, `followScript` watches one already going. |
 | `browser.getObservation(opts?)` | Compact, node-handle-tagged view of the visible page across frames; `opts` tunes budgets and format. |
+| `browser.captureNetwork(opts, onExchange)` | Stream every request the session completes, optionally with response bodies. |
+| `browser.mirrorDom(opts, onChange, onResync?)` | Live, incrementally updated copy of the page's DOM across every frame. |
 | `browser.solveCaptcha(opts?)` | Solve an interactive challenge in the live browser. |
 | `browser.stopBrowser()` | Release the rental. |
 
 Locators: `css(...)`, `js(...)` (target by page logic when CSS can't). Plus
-cookies, storage, network interception, mouse/scroll/drag/select/key events, and
-canvas reads — see the full reference below.
+cookies, storage, auth/DBSC (`getAuthSession`/`setAuthSession`), network
+interception, mouse/scroll/drag/select/key events, and canvas reads — see the
+full reference below.
 
 ## Documentation
 

package/dist/auth-session.d.ts

@@ -0,0 +1,37 @@
+/** DbscSession is one Device Bound Session Credentials entry. */
+export interface DbscSession {
+    /** Serialized schemeful site key, e.g. "https://google.com". */
+    site: string;
+    /**
+     * Base64 of the serialized DBSC Session proto. It includes the wrapped
+     * binding key, which is portable under WRC's software key provider.
+     */
+    session: string;
+}
+/**
+ * AuthSession is a portable snapshot of a context's signed-in Google account
+ * and/or DBSC sessions. Every field is optional, so a context that only has
+ * DBSC sessions (no primary account) or only a sign-in (no DBSC) round-trips.
+ *
+ * Pair it with getCookies()/setCookies() and getStorage()/setStorage() to move
+ * a whole persona between fresh contexts.
+ */
+export interface AuthSession {
+    /** Gaia obfuscated account id. */
+    gaiaId?: string;
+    /** Account email. */
+    email?: string;
+    /** OAuth refresh token (persistent). */
+    refreshToken?: string;
+    /**
+     * Base64 of the wrapped device-binding key for the refresh token. Absent
+     * means the token is unbound.
+     */
+    wrappedBindingKey?: string;
+    /** Signin-scoped device id; must travel with the token. */
+    signinScopedDeviceId?: string;
+    /** True if the account should be restored at Sync consent. */
+    syncConsent?: boolean;
+    /** Device Bound Session Credentials for this context (all bound sites). */
+    dbscSessions?: DbscSession[];
+}

package/dist/auth-session.js

@@ -0,0 +1 @@
+export {};

package/dist/browser.d.ts

@@ -5,11 +5,15 @@ export { BrowserConfig } from "./config.ts";
 export { Locator, css, js, node, at, AllFrames } from "./locator.ts";
 export { DefaultWaitTimeoutMs, DefaultVisible, DefaultSteadyMs, } from "./defaults.ts";
 export { BrowserScaleError, ClickError, FillError, DragError, ScrollError, MoveError, SelectOptionError, WaitError, } from "./errors.ts";
-export type { Rect, FrameInfo, PageInfo, Header, InterceptedRequest, InterceptedResponse, WaitResult, WaitConditionStatus, OccluderInfo, ElementRef, NavigateResult, EvaluateResult, ElementResult, DragResult, SelectOptionResult, ScreenshotResult, ReadCanvasResult, DOMResult, InspectResult, RentResponse, } from "./types.ts";
+export type { Rect, FrameInfo, PageInfo, Header, InterceptedRequest, InterceptedResponse, NetworkExchange, NetworkResourceType, NetworkServedFrom, NetworkBodies, NetworkCaptureOptions, WaitResult, WaitConditionStatus, OccluderInfo, ElementRef, NavigateResult, EvaluateResult, ElementResult, DragResult, SelectOptionResult, ScreenshotResult, ReadCanvasResult, DOMResult, InspectResult, RentResponse, BrowserInfo, } from "./types.ts";
 export type { Button, ClickAction, ClickOpts, FillOpts, SelectOpts, WaitOpts, WaitUntil, NavigateOpts, LoadHTMLOpts, GetDOMOpts, GetObservationOpts, ScreenshotOpts, ReadCanvasOpts, } from "./options.ts";
 export { type RequestPattern, type HeaderModification, type HeaderModificationAction, } from "./network.ts";
+export { ScriptRun, ScriptFollow, type ScriptEvent, type ScriptEventHandler, type ScriptFinished, type ScriptLogEntry, type ScriptResult, type ScriptRunInfo, } from "./scripts.ts";
+export { NetworkCapture, type NetworkExchangeHandler } from "./network-capture.ts";
+export { DomMirror, type DomNode, type DomSnapshot, type DomMirrorOptions, type DomChangeHandler, type DomResyncHandler, type DomResyncReason, } from "./dom-mirror.ts";
 export type { CookieParam } from "./cookies.ts";
 export type { StorageItem, StorageOriginEntry } from "./storage.ts";
+export type { AuthSession, DbscSession } from "./auth-session.ts";
 /**
  * Attaches a {@link CloudBrowser} to an existing session over a raw
  * WebSocket transport.

package/dist/browser.js

@@ -10,6 +10,11 @@ export { Locator, css, js, node, at, AllFrames } from "./locator.js";
 export { DefaultWaitTimeoutMs, DefaultVisible, DefaultSteadyMs, } from "./defaults.js";
 // Errors — base class plus the typed semantic-failure subclasses
 export { BrowserScaleError, ClickError, FillError, DragError, ScrollError, MoveError, SelectOptionError, WaitError, } from "./errors.js";
+// Scripts (automation running inside the browser process)
+export { ScriptRun, ScriptFollow, } from "./scripts.js";
+// Network capture (traffic log)
+export { NetworkCapture } from "./network-capture.js";
+export { DomMirror, } from "./dom-mirror.js";
 // Browser-side factory functions ───────────────────────────────────────
 /**
  * Attaches a {@link CloudBrowser} to an existing session over a raw