browserscale-ts 1.0.1 → 1.2.0

package/dist/internal/convert.js

@@ -2,6 +2,7 @@
 // implementation detail and is NOT exported from the package entrypoints.
 import { create } from "@bufbuild/protobuf";
 import { HeaderModificationSchema, CookiePartitionKeySchema, CookieParamSchema, HeaderSchema, StorageItemSchema, StorageOriginEntrySchema, } from "../gen/wrc_pb.js";
+import { ClickError, DragError, FillError, MoveError, ScrollError, SelectOptionError, WaitError, } from "../errors.js";
 import { pickFrame } from "../locator.js";
 export function elementFields(target, optsInFrame) {
     const out = {};
@@ -28,22 +29,95 @@ export function rectFromProto(r) {
         return { x: 0, y: 0, width: 0, height: 0 };
     return { x: r.x, y: r.y, width: r.width, height: r.height };
 }
-// ──────────────────────────────────────────────────────────────────────
-// Element / Drag / Wait results
-// ──────────────────────────────────────────────────────────────────────
-export function elementResultFromProto(r) {
+function elementResult(r, isVisible, bounds, rootX, rootY) {
     return {
         success: r.success,
         frameId: r.frameId,
         backendNodeId: r.backendNodeId,
-        isVisible: r.isVisible,
-        bounds: rectFromProto(r.bounds),
-        rootX: r.rootX,
-        rootY: r.rootY,
+        isVisible,
+        bounds,
+        rootX,
+        rootY,
     };
 }
-export function dragResultFromProto(r) {
+function occluderFromProto(o) {
+    if (!o)
+        return undefined;
     return {
+        backendNodeId: o.backendNodeId,
+        frameId: o.frameId,
+        tagName: o.tagName,
+        id: o.id ?? "",
+        className: o.className ?? "",
+        text: o.text ?? "",
+        bounds: rectFromProto(o.bounds),
+        pointerEvents: o.pointerEvents ?? "",
+        visibility: o.visibility ?? "",
+        opacity: o.opacity ?? 0,
+        zIndex: o.zIndex ?? "",
+        hittableWhileInvisible: o.hittableWhileInvisible ?? false,
+    };
+}
+// Nested click-core detail (no standalone result) surfaced inside a FillError
+// or DragError as the underlying click failure that blocked the action.
+function clickDetailFromProto(e) {
+    if (!e)
+        return undefined;
+    return new ClickError({
+        code: e.code,
+        message: e.message,
+        occluder: occluderFromProto(e.occluder),
+        evadeAttempted: e.evadeAttempted ?? false,
+    });
+}
+/** Maps a ClickResult to ElementResult; throws {@link ClickError} when the click did not land. */
+export function unwrapClick(r) {
+    const res = elementResult(r, r.isVisible, rectFromProto(r.bounds), r.rootX, r.rootY);
+    if (!r.success && r.error) {
+        throw new ClickError({
+            code: r.error.code,
+            message: r.error.message,
+            occluder: occluderFromProto(r.error.occluder),
+            evadeAttempted: r.error.evadeAttempted ?? false,
+            result: res,
+        });
+    }
+    return res;
+}
+/** Maps a FillResult to ElementResult; throws {@link FillError} when the fill failed. */
+export function unwrapFill(r) {
+    // Fill omits is_visible/bounds from its contract; they stay zero.
+    const res = elementResult(r, false, rectFromProto(undefined), r.rootX, r.rootY);
+    if (!r.success && r.error) {
+        throw new FillError({
+            code: r.error.code,
+            message: r.error.message,
+            clickError: clickDetailFromProto(r.error.clickError),
+            result: res,
+        });
+    }
+    return res;
+}
+/** Maps a MoveResult to ElementResult; throws {@link MoveError} when the target was not found. */
+export function unwrapMove(r) {
+    const res = elementResult(r, r.isVisible, rectFromProto(r.bounds), r.rootX, r.rootY);
+    if (!r.success && r.error) {
+        throw new MoveError({ code: r.error.code, message: r.error.message, result: res });
+    }
+    return res;
+}
+/** Maps a ScrollResult to ElementResult; throws {@link ScrollError} when the target could not be scrolled. */
+export function unwrapScroll(r) {
+    // scrollTo returns no root_x/root_y; they stay zero.
+    const res = elementResult(r, r.isVisible, rectFromProto(r.bounds), 0, 0);
+    if (!r.success && r.error) {
+        throw new ScrollError({ code: r.error.code, message: r.error.message, result: res });
+    }
+    return res;
+}
+/** Maps a DragResult; throws {@link DragError} when the source pickup failed. */
+export function unwrapDrag(r) {
+    const res = {
         success: r.success,
         frameId: r.frameId,
         backendNodeId: r.backendNodeId,
@@ -52,15 +126,57 @@ export function dragResultFromProto(r) {
         endX: r.endX,
         endY: r.endY,
     };
+    if (!r.success && r.error) {
+        throw new DragError({
+            code: r.error.code,
+            message: r.error.message,
+            clickError: clickDetailFromProto(r.error.clickError),
+            result: res,
+        });
+    }
+    return res;
 }
-export function waitResultFromProto(r) {
+/** Maps a SelectOptionResult; throws {@link SelectOptionError} when no option was selected. */
+export function unwrapSelect(r) {
+    const res = {
+        selectedIndex: r.selectedIndex,
+        selectedValue: r.selectedValue,
+        selectedText: r.selectedText,
+    };
+    if (!r.success && r.error) {
+        throw new SelectOptionError({ code: r.error.code, message: r.error.message, result: res });
+    }
+    return res;
+}
+function waitConditionStatusFromProto(c) {
     return {
+        index: c.index,
+        state: c.state,
+        backendNodeId: c.backendNodeId,
+        frameId: c.frameId,
+        isVisible: c.isVisible,
+        bounds: c.bounds ? rectFromProto(c.bounds) : undefined,
+        occluder: occluderFromProto(c.occluder),
+    };
+}
+/** Maps a WaitResult; throws {@link WaitError} when no condition matched before the deadline. */
+export function unwrapWait(r) {
+    const res = {
         index: r.index,
         frameId: r.frameId,
         backendNodeId: r.backendNodeId,
         isVisible: r.isVisible,
         bounds: rectFromProto(r.bounds),
     };
+    if (r.error) {
+        throw new WaitError({
+            code: r.error.code,
+            message: r.error.message,
+            conditions: r.error.conditions.map(waitConditionStatusFromProto),
+            result: res,
+        });
+    }
+    return res;
 }
 // ──────────────────────────────────────────────────────────────────────
 // FrameInfo / PageInfo

package/dist/options.d.ts

@@ -101,3 +101,28 @@ export interface ScreenshotOpts {
     /** Encode quality 0-100 for "jpeg"/"webp" (ignored for "png"). Default 90. */
     quality?: number;
 }
+/** Optional customization for {@link CloudBrowser.readCanvas}. */
+export interface ReadCanvasOpts {
+    /**
+     * Override the locator's frame. Omit to use the locator's own
+     * {@link Locator.inFrame} (or the main frame). Pass a specific
+     * `frameId` or {@link AllFrames} to search elsewhere.
+     */
+    inFrame?: string;
+    /**
+     * Output encoding: `"png"` (default), `"jpeg"`, `"webp"`, or `"rgba"` for
+     * the raw unpremultiplied RGBA pixel buffer.
+     */
+    format?: "png" | "jpeg" | "webp" | "rgba";
+    /** Encode quality 0-100 for "jpeg"/"webp" (ignored otherwise). Default 90. */
+    quality?: number;
+    /**
+     * Optional sub-rectangle in canvas pixels (mirrors
+     * `getImageData(sx, sy, sw, sh)`). The full canvas is read when `sw`/`sh`
+     * are omitted or <= 0.
+     */
+    sx?: number;
+    sy?: number;
+    sw?: number;
+    sh?: number;
+}

package/dist/types.d.ts

@@ -64,6 +64,67 @@ export interface WaitResult {
     isVisible: boolean;
     bounds: Rect;
 }
+/**
+ * OccluderInfo describes the element that intercepted a click — the element
+ * sitting on top of the target at the intended click point. Coordinates are in
+ * root-viewport CSS pixels. Populated on {@link ClickError} for occlusion
+ * failures so the caller can locate and clear the blocker (e.g. find its close
+ * button).
+ */
+export interface OccluderInfo {
+    backendNodeId: number;
+    frameId: string;
+    tagName: string;
+    id: string;
+    className: string;
+    text: string;
+    bounds: Rect;
+    /**
+     * Computed pointer-events keyword (e.g. "auto", "none", "all"). Lets you tell
+     * an invisible pass-through layer from one that genuinely swallows the click.
+     */
+    pointerEvents: string;
+    /** Computed visibility keyword ("visible", "hidden", "collapse"). */
+    visibility: string;
+    /**
+     * Computed opacity (0..1). 0 means visually invisible but it may still
+     * intercept clicks depending on pointerEvents.
+     */
+    opacity: number;
+    /** Computed effective z-index as a string ("0" when auto / not stacked). */
+    zIndex: string;
+    /**
+     * True when the blocker intercepts clicks even while invisible (computed
+     * pointer-events in {all, painted, fill, stroke}): a real click is swallowed
+     * even at visibility:hidden / opacity:0. When false and the element is
+     * invisible, a real click would fall through.
+     */
+    hittableWhileInvisible: boolean;
+}
+/**
+ * WaitConditionStatus is the per-condition diagnostic carried by
+ * {@link WaitError} when a {@link CloudBrowser.wait} times out: one entry per
+ * condition (in the order they were passed) explaining why it never matched.
+ */
+export interface WaitConditionStatus {
+    /** Index into the condition list this entry describes. */
+    index: number;
+    /**
+     * Last observed state: `"not_found"`, `"found_hidden"`, `"found_occluded"`
+     * (only when the condition required visibility), or `"pending_steady"`.
+     */
+    state: string;
+    /** backendNodeId last seen for this condition (0 if never found). */
+    backendNodeId: number;
+    /** frameId where it was last seen (empty if never found). */
+    frameId: string;
+    /** Whether it was CSS-visible at the last observation. */
+    isVisible: boolean;
+    /** Last known rect in root-viewport coordinates (undefined if never found). */
+    bounds?: Rect;
+    /** The intercepting element, present iff state === `"found_occluded"`. */
+    occluder?: OccluderInfo;
+}
 /** NavigateResult reports where a {@link CloudBrowser.navigate} call ended up after redirects. */
 export interface NavigateResult {
     frameId: string;
@@ -139,6 +200,22 @@ export interface ScreenshotResult {
     width: number;
     height: number;
 }
+/**
+ * ReadCanvasResult is the pixel readback of a <canvas>, returned by
+ * {@link CloudBrowser.readCanvas}. `dataBase64` holds the encoded image bytes
+ * (PNG by default) or the raw RGBA buffer when `format` is `"rgba"`.
+ * `originClean` reports whether the canvas was untainted (informational — the
+ * read succeeds either way).
+ */
+export interface ReadCanvasResult {
+    success: boolean;
+    frameId: string;
+    backendNodeId: number;
+    dataBase64: string;
+    width: number;
+    height: number;
+    originClean: boolean;
+}
 /**
  * DOMResult is the full-tree DOM snapshot returned by
  * {@link CloudBrowser.getDOM}, plus its sha256[:8] hash for cheap

package/package.json

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