browserscale-ts 1.2.1 → 1.4.0

package/dist/options.d.ts

@@ -1,3 +1,4 @@
+import type { Locator } from "./locator.ts";
 /** Mouse button used by {@link CloudBrowser.click}. */
 export type Button = "left" | "right" | "middle";
 /** Mouse phase performed by {@link CloudBrowser.click}. */
@@ -24,6 +25,25 @@ export interface ClickOpts {
      */
     action?: ClickAction;
 }
+/**
+ * Optional customization for {@link CloudBrowser.addReaction}. All fields are
+ * optional; missing or zero values mean "use the server default".
+ */
+export interface ReactionOpts {
+    /**
+     * Override the click target. Omit to click the matched element itself.
+     * Provide a `css()`/`js()` {@link Locator} to click a different element,
+     * resolved in the matched element's frame (e.g. a modal's close "X").
+     * `node()`/`at()` locators are rejected.
+     */
+    on?: Locator;
+    /** Mouse button for the click. Default `"left"`. */
+    button?: Button;
+    /** `1` = single click (default), `2` = double-click. */
+    clickCount?: number;
+    /** Poll cadence in milliseconds for the shared page loop. Default 300. */
+    intervalMs?: number;
+}
 /**
  * Optional customization for {@link CloudBrowser.fill}. All fields are
  * optional; missing values mean "use the server default".
@@ -41,6 +61,17 @@ export interface FillOpts {
      * in the field.
      */
     clearFirst?: boolean;
+    /**
+     * Budget in ms to make the field focusable+clickable (locate, scroll,
+     * settle, un-occlude), mirroring the click timeout. Omit for the server
+     * default (5000). `0` makes fill one-shot (no retry).
+     */
+    timeoutMs?: number;
+    /**
+     * Settle window in ms before the focus click, mirroring the click
+     * steady-time. Omit for the server default (750). `0` skips settling.
+     */
+    steadyMs?: number;
 }
 /**
  * Optional customization for {@link CloudBrowser.selectByIndex},
@@ -89,10 +120,58 @@ export interface GetDOMOpts {
 }
 /** Optional customization for {@link CloudBrowser.getObservation}. */
 export interface GetObservationOpts {
-    /** Default 200. */
+    /**
+     * `"text"` (default) for the compact line format meant to be handed to a
+     * model as-is, or `"json"` for the structured form. Only the requested
+     * representation is built, so asking for one does not cost the other.
+     */
+    format?: "text" | "json";
+    /**
+     * Cap on emitted elements per frame. Default 800 — a safety net against
+     * runaway documents; `maxTotalTokens` is the limit that normally binds.
+     */
     maxElementsPerFrame?: number;
-    /** Default 200. */
+    /**
+     * Cap on human-readable strings (labels, text, values) in characters.
+     * Default 300. Identifier-like attributes (type, name, role) have their own
+     * fixed, shorter cap and are unaffected.
+     */
     maxTextLength?: number;
+    /**
+     * Budget across ALL frames, in estimated tokens rather than characters —
+     * the same character count is worth roughly four times as many tokens in
+     * CJK text as in ASCII. Default 8000. Frames are visited in tree order and
+     * each gets whatever is left.
+     */
+    maxTotalTokens?: number;
+    /**
+     * Include element bounds as `bounds="x,y,w,h"`. Off by default; bounds cost
+     * about as much as the rest of a row and are rarely needed, since elements
+     * are addressed by backendNodeId.
+     */
+    includeBounds?: boolean;
+    /** Only emit elements intersecting the frame's current viewport. */
+    viewportOnly?: boolean;
+    /**
+     * Subtree scope — set exactly one of `backendNodeId`, `selector` or
+     * `jsExpression` to observe only that element's subtree (follow-up looks at
+     * a form then cost the form, not the ads around it). Omit all three for the
+     * whole page. Child iframes reached inside the scope are still visited.
+     */
+    backendNodeId?: number;
+    /** Scope root by CSS selector. */
+    selector?: string;
+    /**
+     * Scope root by JS expression that evaluates to a DOM Element (including
+     * `__wrc.shadow(...)` for closed shadow roots).
+     */
+    jsExpression?: string;
+    /**
+     * Where to look up the scope root: a specific `frameId`, omit for the main
+     * frame, or {@link AllFrames} to search every frame until found. Ignored when
+     * observing the whole page.
+     */
+    frameId?: string;
 }
 /** Optional customization for {@link CloudBrowser.screenshot}. */
 export interface ScreenshotOpts {

package/dist/types.d.ts

@@ -100,6 +100,38 @@ export interface OccluderInfo {
      * invisible, a real click would fall through.
      */
     hittableWhileInvisible: boolean;
+    /**
+     * Computed position keyword. `"fixed"`/`"sticky"` means the blocker is pinned
+     * (by itself or an ancestor) and stays put no matter where the pointer goes —
+     * clear it by scrolling the target out from under it; ordinary overlays often
+     * collapse once the pointer leaves.
+     */
+    position: string;
+}
+/**
+ * ElementRef is a lightweight descriptor of an element — enough to identify it
+ * (and decide what to do) without another DOM round-trip. It names the element
+ * that stole focus in a {@link FillError} focus-loss failure.
+ */
+export interface ElementRef {
+    backendNodeId: number;
+    /** Upper-case tag name, e.g. "INPUT", "BUTTON", "DIV". */
+    tagName: string;
+    /** id attribute, if present. */
+    id?: string;
+    /** name attribute, if present. */
+    name?: string;
+    /** class attribute, if present. */
+    className?: string;
+    /** `<input>` type, if the element is an `<input>`. */
+    inputType?: string;
+    /** Whitespace-collapsed textContent/value snippet (max 120 chars). */
+    text?: string;
+    /**
+     * Whether this element is itself an editable text sink (input / textarea /
+     * contenteditable).
+     */
+    editable: boolean;
 }
 /**
  * WaitConditionStatus is the per-condition diagnostic carried by
@@ -181,15 +213,6 @@ export interface SelectOptionResult {
     selectedValue: string;
     selectedText: string;
 }
-/**
- * ObservationResult is the compact page snapshot returned by
- * {@link CloudBrowser.getObservation} — the visible, interactive elements
- * rendered as prompt-friendly text and as JSON.
- */
-export interface ObservationResult {
-    text: string;
-    json: string;
-}
 /**
  * ScreenshotResult is a single captured image of the page, returned by
  * {@link CloudBrowser.screenshot}. `dataBase64` holds the encoded image bytes
@@ -246,3 +269,37 @@ export interface RentResponse {
     acceptLanguage: string;
     fingerprint: string;
 }
+/**
+ * IceServer is one entry for a WebRTC `RTCPeerConnection`'s `iceServers`
+ * config: a TURN (or STUN) URL plus the short-lived credentials to
+ * authenticate with it. Pass these to your peer before creating the offer.
+ */
+export interface IceServer {
+    /** ICE server URLs (e.g. `turn:relay.example.com:3478?transport=udp`). */
+    urls: string[];
+    /** Short-lived TURN REST username (empty for plain STUN). */
+    username: string;
+    /** Short-lived TURN REST credential (empty for plain STUN). */
+    credential: string;
+}
+/**
+ * ReactionInfo describes a still-pending reaction, as returned by
+ * {@link CloudBrowser.listReactions}. One-shot reactions that have already
+ * fired are gone and never appear here.
+ */
+export interface ReactionInfo {
+    /** Stable id assigned by {@link CloudBrowser.addReaction} (pass to removeReaction). */
+    reactionId: string;
+    /** Set if the reaction matches by CSS selector. */
+    matchSelector: string;
+    /** Set if the reaction matches by JS expression. */
+    matchJsExpression: string;
+    /** Set if the click target differs from the matched element. */
+    actionSelector: string;
+    /** Set if the click target differs from the matched element. */
+    actionJsExpression: string;
+    /** Frame scope: `""` for the main frame, a specific frameId, or `AllFrames`. */
+    frameId: string;
+    /** Whether the match additionally requires the element to be visible. */
+    visible: boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browserscale-ts",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Official SDK for browserscale — undetected stealth browsers in the cloud. Rent real Chromium sessions with unique fingerprints, built-in proxies, captcha solving, human-like input and live video — scale web scraping and automation without running a single browser yourself.",
   "main": "dist/index.js",
   "type": "module",