browserscale-ts 1.7.1 → 1.9.0

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import { CloudBrowser } from "./client.ts";
 import { BrowserConfig } from "./config.ts";
-import type { BrowserInfo } from "./types.ts";
+import type { BrowserInfo, SessionUsage } from "./types.ts";
 export { CloudBrowser } from "./client.ts";
 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, NetworkExchange, NetworkResourceType, NetworkServedFrom, NetworkBodies, NetworkCaptureOptions, WaitResult, WaitConditionStatus, OccluderInfo, ElementRef, NavigateResult, EvaluateResult, ElementResult, DragResult, SelectOptionResult, ScreenshotResult, ReadCanvasResult, DOMResult, InspectResult, RentResponse, BrowserInfo, IceServer, StreamAnswer, ReactionInfo, } from "./types.ts";
+export { BrowserScaleError, CommandError, ClickError, FillError, DragError, ScrollError, MoveError, SelectOptionError, WaitError, } from "./errors.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, SessionUsage, IceServer, StreamAnswer, ReactionInfo, } from "./types.ts";
 export type { Button, ClickAction, ClickOpts, FillOpts, ReactionOpts, 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";
@@ -40,8 +40,9 @@ export declare function setApiEndpoint(endpoint: string): void;
  *
  * @returns CloudBrowser ready to drive the rented session
  *
- * @throws UNKNOWN_ERROR - the rent API rejected the request or the gRPC
- *   connection could not be established
+ * Rejects when the rent API refuses the request or the connection cannot be
+ * established. These are session-lifecycle failures rather than browser outcomes,
+ * so they carry no code.
  *
  * @example
  * const cfg = new BrowserConfig("sk_…", 600, "", 0, "", "");
@@ -87,12 +88,16 @@ export declare function connectSession(grpcUrl: string, apiKey: string, sessionI
  * @param apiKey - API key the session was rented with
  * @param sessionId - id of the session to release
  *
- * @throws UNKNOWN_ERROR - the stop API rejected the request
+ * @returns SessionUsage what the session consumed over its whole life;
+ *   undefined when the server could not report it
+ *
+ * Rejects when the stop API refuses the request. Stopping a session that is
+ * already gone is a no-op rather than a failure.
  *
  * @example
- * await stopBrowser(apiKey, sessionId);
+ * const usage = await stopBrowser(apiKey, sessionId);
  */
-export declare function stopBrowser(apiKey: string, sessionId: string): Promise<void>;
+export declare function stopBrowser(apiKey: string, sessionId: string): Promise<SessionUsage | undefined>;
 /**
  * Reports the sessions an API key currently holds.
  *
@@ -109,7 +114,8 @@ export declare function stopBrowser(apiKey: string, sessionId: string): Promise<
  *
  * @returns the running sessions, oldest first; empty when the key holds none
  *
- * @throws UNKNOWN_ERROR - the list API rejected the request
+ * Rejects when the list API refuses the request. An account with no running
+ * sessions is an empty list, not a failure.
  *
  * @example
  * const browsers = await listBrowsers(apiKey);

package/dist/index.js

@@ -1,5 +1,6 @@
 import { createGrpcTransport } from "@connectrpc/connect-node";
 import { CloudBrowser } from "./client.js";
+import { sessionUsageFromJson } from "./internal/convert.js";
 // Public API ──────────────────────────────────────────────────────────
 export { CloudBrowser } from "./client.js";
 export { BrowserConfig } from "./config.js";
@@ -8,7 +9,7 @@ export { Locator, css, js, node, at, AllFrames } from "./locator.js";
 // Defaults the SDK applies before sending a request
 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";
+export { BrowserScaleError, CommandError, 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)
@@ -43,8 +44,9 @@ export function setApiEndpoint(endpoint) {
  *
  * @returns CloudBrowser ready to drive the rented session
  *
- * @throws UNKNOWN_ERROR - the rent API rejected the request or the gRPC
- *   connection could not be established
+ * Rejects when the rent API refuses the request or the connection cannot be
+ * established. These are session-lifecycle failures rather than browser outcomes,
+ * so they carry no code.
  *
  * @example
  * const cfg = new BrowserConfig("sk_…", 600, "", 0, "", "");
@@ -60,9 +62,7 @@ export async function rentBrowser(config) {
     const transport = createGrpcTransport({
         baseUrl: grpcBaseUrl(rentResp.grpcUrl),
     });
-    return new CloudBrowser(transport, rentResp.sessionId, config.apiKey, rentResp.fingerprint, async () => {
-        await callStopApi(config.apiKey, rentResp.sessionId);
-    });
+    return new CloudBrowser(transport, rentResp.sessionId, config.apiKey, rentResp.fingerprint, () => callStopApi(config.apiKey, rentResp.sessionId));
 }
 /**
  * Attaches to an already-rented session over a fresh gRPC connection.
@@ -89,9 +89,7 @@ export async function rentBrowser(config) {
  */
 export function connectSession(grpcUrl, apiKey, sessionId) {
     const transport = createGrpcTransport({ baseUrl: grpcBaseUrl(grpcUrl) });
-    return new CloudBrowser(transport, sessionId, apiKey, "", async () => {
-        await callStopApi(apiKey, sessionId);
-    });
+    return new CloudBrowser(transport, sessionId, apiKey, "", () => callStopApi(apiKey, sessionId));
 }
 /**
  * Releases a session without needing a {@link CloudBrowser} handle.
@@ -103,13 +101,17 @@ export function connectSession(grpcUrl, apiKey, sessionId) {
  * @param apiKey - API key the session was rented with
  * @param sessionId - id of the session to release
  *
- * @throws UNKNOWN_ERROR - the stop API rejected the request
+ * @returns SessionUsage what the session consumed over its whole life;
+ *   undefined when the server could not report it
+ *
+ * Rejects when the stop API refuses the request. Stopping a session that is
+ * already gone is a no-op rather than a failure.
  *
  * @example
- * await stopBrowser(apiKey, sessionId);
+ * const usage = await stopBrowser(apiKey, sessionId);
  */
 export async function stopBrowser(apiKey, sessionId) {
-    await callStopApi(apiKey, sessionId);
+    return await callStopApi(apiKey, sessionId);
 }
 /**
  * Reports the sessions an API key currently holds.
@@ -127,7 +129,8 @@ export async function stopBrowser(apiKey, sessionId) {
  *
  * @returns the running sessions, oldest first; empty when the key holds none
  *
- * @throws UNKNOWN_ERROR - the list API rejected the request
+ * Rejects when the list API refuses the request. An account with no running
+ * sessions is an empty list, not a failure.
  *
  * @example
  * const browsers = await listBrowsers(apiKey);
@@ -221,4 +224,5 @@ async function callStopApi(apiKey, sessionId) {
     if (!resp.ok || !data.success) {
         throw new Error(`stop failed: ${data.error ?? resp.statusText}`);
     }
+    return sessionUsageFromJson(data.usage);
 }

package/dist/internal/convert.d.ts

@@ -1,5 +1,5 @@
-import { type Rect as ProtoRect, type ClickResult as ProtoClickResult, type FillResult as ProtoFillResult, type MoveResult as ProtoMoveResult, type ScrollResult as ProtoScrollResult, type DragResult as ProtoDragResult, type SelectOptionResult as ProtoSelectOptionResult, type WaitResult as ProtoWaitResult, type FrameInfo as ProtoFrameInfo, type PageInfo as ProtoPageInfo, type Header as ProtoHeader, type InterceptedRequest as ProtoInterceptedRequest, type InterceptedResponse as ProtoInterceptedResponse, type NetworkExchange as ProtoNetworkExchange, type HeaderModification as ProtoHeaderModification, type CookieParam as ProtoCookieParam, type StorageOriginEntry as ProtoStorageOriginEntry, type AuthSession as ProtoAuthSession } from "../gen/wrc_pb.ts";
-import type { DragResult, ElementResult, FrameInfo, Header, InterceptedRequest, InterceptedResponse, NetworkExchange, PageInfo, Rect, SelectOptionResult, WaitResult } from "../types.ts";
+import { type Rect as ProtoRect, type ClickResult as ProtoClickResult, type FillResult as ProtoFillResult, type MoveResult as ProtoMoveResult, type ScrollResult as ProtoScrollResult, type DragResult as ProtoDragResult, type SelectOptionResult as ProtoSelectOptionResult, type WaitResult as ProtoWaitResult, type FrameInfo as ProtoFrameInfo, type PageInfo as ProtoPageInfo, type SessionUsage as ProtoSessionUsage, type Header as ProtoHeader, type InterceptedRequest as ProtoInterceptedRequest, type InterceptedResponse as ProtoInterceptedResponse, type NetworkExchange as ProtoNetworkExchange, type HeaderModification as ProtoHeaderModification, type CookieParam as ProtoCookieParam, type StorageOriginEntry as ProtoStorageOriginEntry, type AuthSession as ProtoAuthSession } from "../gen/wrc_pb.ts";
+import type { DragResult, ElementResult, FrameInfo, Header, InterceptedRequest, InterceptedResponse, NetworkExchange, PageInfo, Rect, SelectOptionResult, SessionUsage, WaitResult } from "../types.ts";
 import type { CookieParam } from "../cookies.ts";
 import type { StorageOriginEntry } from "../storage.ts";
 import type { AuthSession } from "../auth-session.ts";
@@ -36,6 +36,8 @@ export declare function unwrapSelect(r: ProtoSelectOptionResult): SelectOptionRe
 export declare function unwrapWait(r: ProtoWaitResult): WaitResult;
 export declare function frameInfoFromProto(f: ProtoFrameInfo): FrameInfo;
 export declare function pageInfoFromProto(p: ProtoPageInfo): PageInfo;
+export declare function sessionUsageFromProto(u: ProtoSessionUsage): SessionUsage;
+export declare function sessionUsageFromJson(v: unknown): SessionUsage | undefined;
 export declare function headerFromProto(h: ProtoHeader): Header;
 export declare function headersToProto(headers: Header[] | undefined): ProtoHeader[];
 export declare function interceptedRequestFromProto(r: ProtoInterceptedRequest | undefined): InterceptedRequest | null;

package/dist/internal/convert.js

@@ -183,6 +183,7 @@ function waitConditionStatusFromProto(c) {
 /** Maps a WaitResult; throws {@link WaitError} when no condition matched before the deadline. */
 export function unwrapWait(r) {
     const res = {
+        success: r.success,
         index: r.index,
         frameId: r.frameId,
         backendNodeId: r.backendNodeId,
@@ -227,6 +228,33 @@ export function pageInfoFromProto(p) {
             : {},
     };
 }
+export function sessionUsageFromProto(u) {
+    return {
+        wallTime: u.wallTime,
+        cpuTime: u.cpuTime,
+        minMemory: u.minMemory,
+        averageMemory: u.averageMemory,
+        peakMemory: u.peakMemory,
+        renderersUsed: u.renderersUsed,
+        framesCreated: u.framesCreated,
+    };
+}
+// The stop endpoint answers in JSON, with the same field names as SessionUsage.
+export function sessionUsageFromJson(v) {
+    if (!v || typeof v !== "object")
+        return undefined;
+    const u = v;
+    const num = (x) => (typeof x === "number" ? x : 0);
+    return {
+        wallTime: num(u.wallTime),
+        cpuTime: num(u.cpuTime),
+        minMemory: num(u.minMemory),
+        averageMemory: num(u.averageMemory),
+        peakMemory: num(u.peakMemory),
+        renderersUsed: num(u.renderersUsed),
+        framesCreated: num(u.framesCreated),
+    };
+}
 // ──────────────────────────────────────────────────────────────────────
 // Headers
 // ──────────────────────────────────────────────────────────────────────

package/dist/locator.d.ts

@@ -40,9 +40,9 @@ export declare class Locator {
      * Enforces or disables the visibility check for this Locator's wait
      * condition.
      *
-     * Pass `false` to opt out of the default `DefaultVisible` (true). Has
-     * no effect when used as an action target — actions never check
-     * visibility before dispatching.
+     * Visibility is required by default, so pass `false` to wait for DOM
+     * presence alone. Has no effect when used as an action target — actions
+     * never check visibility before dispatching.
      *
      * @param v - true to require visibility, false to skip the check
      *
@@ -56,9 +56,9 @@ export declare class Locator {
      * Requires the element to keep a stable position and size for at least
      * `ms` milliseconds before the wait matches.
      *
-     * Pass 0 to disable the default `DefaultSteadyMs` (500). Has no effect
-     * for js() expressions that return a non-Element value, nor when used
-     * as an action target.
+     * Settling defaults to 500ms, so pass 0 to match the instant the element
+     * is found. Has no effect for js() expressions that return a non-Element
+     * value, nor when used as an action target.
      *
      * @param ms - steady-state duration in milliseconds; 0 disables
      *
@@ -112,9 +112,10 @@ export declare class Locator {
  * css waits for / targets an element matching the given CSS selector.
  *
  * When used in {@link CloudBrowser.wait}/{@link CloudBrowser.waitAny}, the
- * returned Locator carries the SDK defaults `DefaultVisible` (true) and
- * `DefaultSteadyMs` (500). Override per call with `.visible(false)` /
- * `.steady(ms)` (use `.steady(0)` to disable the steady check).
+ * condition requires the element to be visible and to hold still for 500ms
+ * before it matches — the API's defaults for a condition that does not set
+ * them. Override per call with `.visible(false)` / `.steady(ms)` (use
+ * `.steady(0)` to disable the steady check).
  *
  * When used as an action target (click, fill, …) the visible/steady
  * fields are ignored — there are no corresponding fields on the action
@@ -134,8 +135,8 @@ export declare function css(selector: string): Locator;
 /**
  * js waits for / targets the result of a JavaScript expression.
  *
- * Same wait defaults as {@link css} (`DefaultVisible`=true,
- * `DefaultSteadyMs`=500); these only apply when the expression returns a
+ * Same wait defaults as {@link css} (visible, 500ms steady); these only
+ * apply when the expression returns a
  * DOM Element. For non-Element truthy values (boolean, string, number,
  * plain object) both fields are no-ops and the condition matches as soon
  * as the value is truthy. Use `.visible(false)` / `.steady(0)` to opt out.

package/dist/locator.js

@@ -1,4 +1,3 @@
-import { DefaultSteadyMs, DefaultVisible } from "./defaults.js";
 import { BrowserScaleError } from "./errors.js";
 /**
  * AllFrames is the sentinel for "match in every frame on the page".
@@ -53,9 +52,9 @@ export class Locator {
      * Enforces or disables the visibility check for this Locator's wait
      * condition.
      *
-     * Pass `false` to opt out of the default `DefaultVisible` (true). Has
-     * no effect when used as an action target — actions never check
-     * visibility before dispatching.
+     * Visibility is required by default, so pass `false` to wait for DOM
+     * presence alone. Has no effect when used as an action target — actions
+     * never check visibility before dispatching.
      *
      * @param v - true to require visibility, false to skip the check
      *
@@ -71,9 +70,9 @@ export class Locator {
      * Requires the element to keep a stable position and size for at least
      * `ms` milliseconds before the wait matches.
      *
-     * Pass 0 to disable the default `DefaultSteadyMs` (500). Has no effect
-     * for js() expressions that return a non-Element value, nor when used
-     * as an action target.
+     * Settling defaults to 500ms, so pass 0 to match the instant the element
+     * is found. Has no effect for js() expressions that return a non-Element
+     * value, nor when used as an action target.
      *
      * @param ms - steady-state duration in milliseconds; 0 disables
      *
@@ -132,19 +131,11 @@ export class Locator {
     // ── Constructors (top-level functions re-export these) ──────────────
     /** @internal */
     static _css(selector) {
-        return new Locator({
-            selector,
-            visibleFlag: DefaultVisible,
-            steadyMs: DefaultSteadyMs,
-        });
+        return new Locator({ selector });
     }
     /** @internal */
     static _js(expression) {
-        return new Locator({
-            jsExpression: expression,
-            visibleFlag: DefaultVisible,
-            steadyMs: DefaultSteadyMs,
-        });
+        return new Locator({ jsExpression: expression });
     }
     /** @internal */
     static _node(backendNodeId) {
@@ -162,9 +153,10 @@ export class Locator {
  * css waits for / targets an element matching the given CSS selector.
  *
  * When used in {@link CloudBrowser.wait}/{@link CloudBrowser.waitAny}, the
- * returned Locator carries the SDK defaults `DefaultVisible` (true) and
- * `DefaultSteadyMs` (500). Override per call with `.visible(false)` /
- * `.steady(ms)` (use `.steady(0)` to disable the steady check).
+ * condition requires the element to be visible and to hold still for 500ms
+ * before it matches — the API's defaults for a condition that does not set
+ * them. Override per call with `.visible(false)` / `.steady(ms)` (use
+ * `.steady(0)` to disable the steady check).
  *
  * When used as an action target (click, fill, …) the visible/steady
  * fields are ignored — there are no corresponding fields on the action
@@ -186,8 +178,8 @@ export function css(selector) {
 /**
  * js waits for / targets the result of a JavaScript expression.
  *
- * Same wait defaults as {@link css} (`DefaultVisible`=true,
- * `DefaultSteadyMs`=500); these only apply when the expression returns a
+ * Same wait defaults as {@link css} (visible, 500ms steady); these only
+ * apply when the expression returns a
  * DOM Element. For non-Element truthy values (boolean, string, number,
  * plain object) both fields are no-ops and the condition matches as soon
  * as the value is truthy. Use `.visible(false)` / `.steady(0)` to opt out.

package/dist/network-capture.d.ts

@@ -77,8 +77,9 @@ export declare class NetworkCapture {
      * {@link CloudBrowser.stopNetworkCapture} instead: stop awaits the reader,
      * which cannot finish while the handler it called is still running.
      *
-     * @throws UNKNOWN_ERROR - the capture could not be disarmed; the local reader
-     *   is shut down regardless
+     * Rejects only on a transport failure, and the local reader is shut down
+     * regardless. Disarming a capture that is not running is a no-op rather than a
+     * failure, so there are no error codes to branch on.
      */
     stop(): Promise<void>;
 }

package/dist/network-capture.js

@@ -88,8 +88,9 @@ export class NetworkCapture {
      * {@link CloudBrowser.stopNetworkCapture} instead: stop awaits the reader,
      * which cannot finish while the handler it called is still running.
      *
-     * @throws UNKNOWN_ERROR - the capture could not be disarmed; the local reader
-     *   is shut down regardless
+     * Rejects only on a transport failure, and the local reader is shut down
+     * regardless. Disarming a capture that is not running is a no-op rather than a
+     * failure, so there are no error codes to branch on.
      */
     async stop() {
         if (this.stopped)

package/dist/options.d.ts

@@ -92,7 +92,7 @@ export interface SelectOpts {
 }
 /** Optional customization for {@link CloudBrowser.wait} / {@link CloudBrowser.waitForAny}. */
 export interface WaitOpts {
-    /** Default `DefaultWaitTimeoutMs` (30 000 ms). */
+    /** Omitted leaves it to the API, which defaults to 30 000 ms. */
     timeoutMs?: number;
 }
 /** Lifecycle event {@link CloudBrowser.navigate} waits for before returning. */

package/dist/scripts.d.ts

@@ -144,7 +144,8 @@ export declare class ScriptRun {
      *
      * @returns how the script ended
      *
-     * @throws UNKNOWN_ERROR - the outcome could not be observed
+     * Rejects only on a transport failure - the connection dying, or the run being
+     * abandoned. A script that threw is a normal outcome and arrives in the result.
      */
     wait(): Promise<ScriptFinished>;
     /**
@@ -155,8 +156,8 @@ export declare class ScriptRun {
      * at its next operation in the page. Either way the handler sees a `finished`
      * with `stopped` set, unless the local reader is torn down first.
      *
-     * @throws UNKNOWN_ERROR - the run could not be cancelled server-side; the
-     *   local reader is detached regardless
+     * Rejects only on a transport failure, and the local reader is detached
+     * regardless. Cancelling a run that has already finished is a no-op.
      */
     stop(): Promise<void>;
     /**

package/dist/scripts.js

@@ -122,7 +122,8 @@ export class ScriptRun {
      *
      * @returns how the script ended
      *
-     * @throws UNKNOWN_ERROR - the outcome could not be observed
+     * Rejects only on a transport failure - the connection dying, or the run being
+     * abandoned. A script that threw is a normal outcome and arrives in the result.
      */
     async wait() {
         await this.endedPromise;
@@ -140,8 +141,8 @@ export class ScriptRun {
      * at its next operation in the page. Either way the handler sees a `finished`
      * with `stopped` set, unless the local reader is torn down first.
      *
-     * @throws UNKNOWN_ERROR - the run could not be cancelled server-side; the
-     *   local reader is detached regardless
+     * Rejects only on a transport failure, and the local reader is detached
+     * regardless. Cancelling a run that has already finished is a no-op.
      */
     async stop() {
         if (this.detached)

package/dist/types.d.ts

@@ -26,6 +26,46 @@ export interface PageInfo {
     viewport: Rect;
     frameTree: FrameInfo;
 }
+/**
+ * SessionUsage is what a session's browser has consumed since the session
+ * started: the CPU time and memory of every process that rendered its pages —
+ * main frames, cross-site iframes and the workers they host — including
+ * processes that have since exited. Work done on the session's behalf in
+ * processes it shares with other sessions is not included.
+ *
+ * {@link CloudBrowser.getUsage} reports it while the session runs, and
+ * {@link CloudBrowser.stopBrowser} resolves with the final figures, so there is
+ * no need to read it right before stopping.
+ */
+export interface SessionUsage {
+    /** Real time since the session's browser was created, in seconds. */
+    wallTime: number;
+    /**
+     * User plus kernel CPU time in seconds. Only time a thread actually ran on a
+     * core counts; waiting and idling do not.
+     */
+    cpuTime: number;
+    /**
+     * The least memory the session held once its browser was ready, in bytes.
+     * Sampled about once a second.
+     */
+    minMemory: number;
+    /**
+     * The memory held, averaged over wallTime, in bytes; averageMemory * wallTime
+     * is the memory-time used. Sampled about once a second, so short spikes count
+     * toward the peak but barely toward the average.
+     */
+    averageMemory: number;
+    /** The most memory held at any one moment, in bytes. */
+    peakMemory: number;
+    /**
+     * Renderer processes that hosted at least one of the session's frames: one
+     * per site its pages and cross-site iframes needed.
+     */
+    renderersUsed: number;
+    /** Child frames created in the session's pages, whether or not they got a process of their own. */
+    framesCreated: number;
+}
 /** Header is a single HTTP header (name/value pair) on an intercepted request or response. */
 export interface Header {
     name: string;
@@ -167,6 +207,11 @@ export interface NetworkCaptureOptions {
  * argument order) and where the matched element lives.
  */
 export interface WaitResult {
+    /**
+     * False iff nothing matched before the deadline. Redundant with `index` being
+     * -1, and carried so every command answers the same question the same way.
+     */
+    success: boolean;
     index: number;
     frameId: string;
     backendNodeId: number;
@@ -283,6 +328,13 @@ export interface NavigateResult {
  * purely a TS hint, not a runtime guarantee.
  */
 export interface EvaluateResult<T = unknown> {
+    /**
+     * False only when the expression never produced a value, which rejects the
+     * call — so a resolved result always has this true. An expression that answers
+     * falsy is a successful evaluation, so this does not mean "the answer was
+     * false".
+     */
+    success: boolean;
     value: T;
     backendNodeId: number;
     isVisible: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browserscale-ts",
-  "version": "1.7.1",
+  "version": "1.9.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",