browserscale-ts 1.7.0 → 1.8.0

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

@@ -167,6 +167,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 +288,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.0",
+  "version": "1.8.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",