browserclaw 0.12.3 → 0.12.5

package/dist/index.d.cts

@@ -2,135 +2,6 @@ import { BrowserContext, Page, Locator, CDPSession } from 'playwright-core';
 import { lookup } from 'node:dns';
 import { lookup as lookup$1 } from 'node:dns/promises';
 
-/** A single action within a batch. */
-type BatchAction = {
-    kind: 'click';
-    ref?: string;
-    selector?: string;
-    targetId?: string;
-    doubleClick?: boolean;
-    button?: string;
-    modifiers?: string[];
-    delayMs?: number;
-    timeoutMs?: number;
-} | {
-    kind: 'type';
-    ref?: string;
-    selector?: string;
-    text: string;
-    targetId?: string;
-    submit?: boolean;
-    slowly?: boolean;
-    timeoutMs?: number;
-} | {
-    kind: 'press';
-    key: string;
-    targetId?: string;
-    delayMs?: number;
-} | {
-    kind: 'hover';
-    ref?: string;
-    selector?: string;
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'scrollIntoView';
-    ref?: string;
-    selector?: string;
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'drag';
-    startRef?: string;
-    startSelector?: string;
-    endRef?: string;
-    endSelector?: string;
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'select';
-    ref?: string;
-    selector?: string;
-    values: string[];
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'fill';
-    fields: {
-        ref: string;
-        type?: string;
-        value?: string | number | boolean;
-    }[];
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'resize';
-    width: number;
-    height: number;
-    targetId?: string;
-} | {
-    kind: 'wait';
-    timeMs?: number;
-    text?: string;
-    textGone?: string;
-    selector?: string;
-    url?: string;
-    loadState?: 'load' | 'domcontentloaded' | 'networkidle';
-    fn?: string;
-    arg?: unknown;
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'evaluate';
-    fn: string;
-    ref?: string;
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'close';
-    targetId?: string;
-} | {
-    kind: 'batch';
-    actions: BatchAction[];
-    targetId?: string;
-    stopOnError?: boolean;
-};
-/** Result of a single action within a batch. */
-type BatchActionResult = {
-    ok: true;
-} | {
-    ok: false;
-    error: string;
-};
-/**
- * Execute a single batch action.
- */
-declare function executeSingleAction(action: BatchAction, cdpUrl: string, targetId: string | undefined, evaluateEnabled: boolean, depth?: number): Promise<void>;
-/**
- * Execute multiple browser actions in sequence.
- *
- * @param opts.actions - Array of actions to execute
- * @param opts.stopOnError - Stop on first error (default: true)
- * @param opts.evaluateEnabled - Whether evaluate/wait:fn actions are permitted
- * @param opts.depth - Internal recursion depth (do not set manually)
- */
-declare function batchViaPlaywright(opts: {
-    cdpUrl: string;
-    targetId?: string;
-    actions: BatchAction[];
-    stopOnError?: boolean;
-    evaluateEnabled?: boolean;
-    depth?: number;
-}): Promise<{
-    results: BatchActionResult[];
-}>;
-
-interface FrameEvalResult {
-    frameUrl: string;
-    frameName: string;
-    result: unknown;
-}
-
 /**
  * Policy for controlling which URLs browser navigation is allowed to reach.
  * Defaults to trusted-network mode (private/internal addresses allowed).
@@ -701,6 +572,136 @@ interface PinnedHostname {
     lookup: typeof lookup;
 }
 
+/** A single action within a batch. */
+type BatchAction = {
+    kind: 'click';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    doubleClick?: boolean;
+    button?: string;
+    modifiers?: string[];
+    delayMs?: number;
+    timeoutMs?: number;
+} | {
+    kind: 'type';
+    ref?: string;
+    selector?: string;
+    text: string;
+    targetId?: string;
+    submit?: boolean;
+    slowly?: boolean;
+    timeoutMs?: number;
+} | {
+    kind: 'press';
+    key: string;
+    targetId?: string;
+    delayMs?: number;
+} | {
+    kind: 'hover';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'scrollIntoView';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'drag';
+    startRef?: string;
+    startSelector?: string;
+    endRef?: string;
+    endSelector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'select';
+    ref?: string;
+    selector?: string;
+    values: string[];
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'fill';
+    fields: {
+        ref: string;
+        type?: string;
+        value?: string | number | boolean;
+    }[];
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'resize';
+    width: number;
+    height: number;
+    targetId?: string;
+} | {
+    kind: 'wait';
+    timeMs?: number;
+    text?: string;
+    textGone?: string;
+    selector?: string;
+    url?: string;
+    loadState?: 'load' | 'domcontentloaded' | 'networkidle';
+    fn?: string;
+    arg?: unknown;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'evaluate';
+    fn: string;
+    ref?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'close';
+    targetId?: string;
+} | {
+    kind: 'batch';
+    actions: BatchAction[];
+    targetId?: string;
+    stopOnError?: boolean;
+};
+/** Result of a single action within a batch. */
+type BatchActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Execute a single batch action.
+ */
+declare function executeSingleAction(action: BatchAction, cdpUrl: string, targetId: string | undefined, evaluateEnabled: boolean, depth?: number, ssrfPolicy?: SsrfPolicy): Promise<void>;
+/**
+ * Execute multiple browser actions in sequence.
+ *
+ * @param opts.actions - Array of actions to execute
+ * @param opts.stopOnError - Stop on first error (default: true)
+ * @param opts.evaluateEnabled - Whether evaluate/wait:fn actions are permitted
+ * @param opts.depth - Internal recursion depth (do not set manually)
+ */
+declare function batchViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    actions: BatchAction[];
+    stopOnError?: boolean;
+    evaluateEnabled?: boolean;
+    depth?: number;
+    ssrfPolicy?: SsrfPolicy;
+}): Promise<{
+    results: BatchActionResult[];
+}>;
+
+interface FrameEvalResult {
+    frameUrl: string;
+    frameName: string;
+    result: unknown;
+}
+
 /**
  * Represents a single browser page/tab with ref-based automation.
  *
@@ -1775,9 +1776,9 @@ declare class BrowserClaw {
  * Convert a WebSocket CDP URL to an HTTP base URL for `/json/*` endpoints.
  */
 declare function normalizeCdpHttpBaseForJsonEndpoints(cdpUrl: string): string;
-declare function isChromeReachable(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<boolean>;
-declare function getChromeWebSocketUrl(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<string | null>;
-declare function isChromeCdpReady(cdpUrl: string, timeoutMs?: number, handshakeTimeoutMs?: number): Promise<boolean>;
+declare function isChromeReachable(cdpUrl: string, timeoutMs?: number, authToken?: string, ssrfPolicy?: SsrfPolicy): Promise<boolean>;
+declare function getChromeWebSocketUrl(cdpUrl: string, timeoutMs?: number, authToken?: string, ssrfPolicy?: SsrfPolicy): Promise<string | null>;
+declare function isChromeCdpReady(cdpUrl: string, timeoutMs?: number, handshakeTimeoutMs?: number, ssrfPolicy?: SsrfPolicy): Promise<boolean>;
 
 type LookupFn = typeof lookup$1;
 /**
@@ -1971,6 +1972,7 @@ declare const forceDisconnectPlaywrightForTarget: typeof forceDisconnectPlaywrig
 declare function resolvePageByTargetIdOrThrow(opts: {
     cdpUrl: string;
     targetId: string;
+    ssrfPolicy?: SsrfPolicy;
 }): Promise<Page>;
 /**
  * Get a page for a target, ensuring page state is initialized.
@@ -1978,6 +1980,7 @@ declare function resolvePageByTargetIdOrThrow(opts: {
 declare function getRestoredPageForTarget(opts: {
     cdpUrl: string;
     targetId?: string;
+    ssrfPolicy?: SsrfPolicy;
 }): Promise<Page>;
 
 declare function pressAndHoldViaCdp(opts: {
@@ -1987,6 +1990,7 @@ declare function pressAndHoldViaCdp(opts: {
     y: number;
     delay?: number;
     holdMs?: number;
+    ssrfPolicy?: SsrfPolicy;
 }): Promise<void>;
 
 /**

package/dist/index.d.ts

@@ -2,135 +2,6 @@ import { BrowserContext, Page, Locator, CDPSession } from 'playwright-core';
 import { lookup } from 'node:dns';
 import { lookup as lookup$1 } from 'node:dns/promises';
 
-/** A single action within a batch. */
-type BatchAction = {
-    kind: 'click';
-    ref?: string;
-    selector?: string;
-    targetId?: string;
-    doubleClick?: boolean;
-    button?: string;
-    modifiers?: string[];
-    delayMs?: number;
-    timeoutMs?: number;
-} | {
-    kind: 'type';
-    ref?: string;
-    selector?: string;
-    text: string;
-    targetId?: string;
-    submit?: boolean;
-    slowly?: boolean;
-    timeoutMs?: number;
-} | {
-    kind: 'press';
-    key: string;
-    targetId?: string;
-    delayMs?: number;
-} | {
-    kind: 'hover';
-    ref?: string;
-    selector?: string;
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'scrollIntoView';
-    ref?: string;
-    selector?: string;
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'drag';
-    startRef?: string;
-    startSelector?: string;
-    endRef?: string;
-    endSelector?: string;
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'select';
-    ref?: string;
-    selector?: string;
-    values: string[];
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'fill';
-    fields: {
-        ref: string;
-        type?: string;
-        value?: string | number | boolean;
-    }[];
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'resize';
-    width: number;
-    height: number;
-    targetId?: string;
-} | {
-    kind: 'wait';
-    timeMs?: number;
-    text?: string;
-    textGone?: string;
-    selector?: string;
-    url?: string;
-    loadState?: 'load' | 'domcontentloaded' | 'networkidle';
-    fn?: string;
-    arg?: unknown;
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'evaluate';
-    fn: string;
-    ref?: string;
-    targetId?: string;
-    timeoutMs?: number;
-} | {
-    kind: 'close';
-    targetId?: string;
-} | {
-    kind: 'batch';
-    actions: BatchAction[];
-    targetId?: string;
-    stopOnError?: boolean;
-};
-/** Result of a single action within a batch. */
-type BatchActionResult = {
-    ok: true;
-} | {
-    ok: false;
-    error: string;
-};
-/**
- * Execute a single batch action.
- */
-declare function executeSingleAction(action: BatchAction, cdpUrl: string, targetId: string | undefined, evaluateEnabled: boolean, depth?: number): Promise<void>;
-/**
- * Execute multiple browser actions in sequence.
- *
- * @param opts.actions - Array of actions to execute
- * @param opts.stopOnError - Stop on first error (default: true)
- * @param opts.evaluateEnabled - Whether evaluate/wait:fn actions are permitted
- * @param opts.depth - Internal recursion depth (do not set manually)
- */
-declare function batchViaPlaywright(opts: {
-    cdpUrl: string;
-    targetId?: string;
-    actions: BatchAction[];
-    stopOnError?: boolean;
-    evaluateEnabled?: boolean;
-    depth?: number;
-}): Promise<{
-    results: BatchActionResult[];
-}>;
-
-interface FrameEvalResult {
-    frameUrl: string;
-    frameName: string;
-    result: unknown;
-}
-
 /**
  * Policy for controlling which URLs browser navigation is allowed to reach.
  * Defaults to trusted-network mode (private/internal addresses allowed).
@@ -701,6 +572,136 @@ interface PinnedHostname {
     lookup: typeof lookup;
 }
 
+/** A single action within a batch. */
+type BatchAction = {
+    kind: 'click';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    doubleClick?: boolean;
+    button?: string;
+    modifiers?: string[];
+    delayMs?: number;
+    timeoutMs?: number;
+} | {
+    kind: 'type';
+    ref?: string;
+    selector?: string;
+    text: string;
+    targetId?: string;
+    submit?: boolean;
+    slowly?: boolean;
+    timeoutMs?: number;
+} | {
+    kind: 'press';
+    key: string;
+    targetId?: string;
+    delayMs?: number;
+} | {
+    kind: 'hover';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'scrollIntoView';
+    ref?: string;
+    selector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'drag';
+    startRef?: string;
+    startSelector?: string;
+    endRef?: string;
+    endSelector?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'select';
+    ref?: string;
+    selector?: string;
+    values: string[];
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'fill';
+    fields: {
+        ref: string;
+        type?: string;
+        value?: string | number | boolean;
+    }[];
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'resize';
+    width: number;
+    height: number;
+    targetId?: string;
+} | {
+    kind: 'wait';
+    timeMs?: number;
+    text?: string;
+    textGone?: string;
+    selector?: string;
+    url?: string;
+    loadState?: 'load' | 'domcontentloaded' | 'networkidle';
+    fn?: string;
+    arg?: unknown;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'evaluate';
+    fn: string;
+    ref?: string;
+    targetId?: string;
+    timeoutMs?: number;
+} | {
+    kind: 'close';
+    targetId?: string;
+} | {
+    kind: 'batch';
+    actions: BatchAction[];
+    targetId?: string;
+    stopOnError?: boolean;
+};
+/** Result of a single action within a batch. */
+type BatchActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Execute a single batch action.
+ */
+declare function executeSingleAction(action: BatchAction, cdpUrl: string, targetId: string | undefined, evaluateEnabled: boolean, depth?: number, ssrfPolicy?: SsrfPolicy): Promise<void>;
+/**
+ * Execute multiple browser actions in sequence.
+ *
+ * @param opts.actions - Array of actions to execute
+ * @param opts.stopOnError - Stop on first error (default: true)
+ * @param opts.evaluateEnabled - Whether evaluate/wait:fn actions are permitted
+ * @param opts.depth - Internal recursion depth (do not set manually)
+ */
+declare function batchViaPlaywright(opts: {
+    cdpUrl: string;
+    targetId?: string;
+    actions: BatchAction[];
+    stopOnError?: boolean;
+    evaluateEnabled?: boolean;
+    depth?: number;
+    ssrfPolicy?: SsrfPolicy;
+}): Promise<{
+    results: BatchActionResult[];
+}>;
+
+interface FrameEvalResult {
+    frameUrl: string;
+    frameName: string;
+    result: unknown;
+}
+
 /**
  * Represents a single browser page/tab with ref-based automation.
  *
@@ -1775,9 +1776,9 @@ declare class BrowserClaw {
  * Convert a WebSocket CDP URL to an HTTP base URL for `/json/*` endpoints.
  */
 declare function normalizeCdpHttpBaseForJsonEndpoints(cdpUrl: string): string;
-declare function isChromeReachable(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<boolean>;
-declare function getChromeWebSocketUrl(cdpUrl: string, timeoutMs?: number, authToken?: string): Promise<string | null>;
-declare function isChromeCdpReady(cdpUrl: string, timeoutMs?: number, handshakeTimeoutMs?: number): Promise<boolean>;
+declare function isChromeReachable(cdpUrl: string, timeoutMs?: number, authToken?: string, ssrfPolicy?: SsrfPolicy): Promise<boolean>;
+declare function getChromeWebSocketUrl(cdpUrl: string, timeoutMs?: number, authToken?: string, ssrfPolicy?: SsrfPolicy): Promise<string | null>;
+declare function isChromeCdpReady(cdpUrl: string, timeoutMs?: number, handshakeTimeoutMs?: number, ssrfPolicy?: SsrfPolicy): Promise<boolean>;
 
 type LookupFn = typeof lookup$1;
 /**
@@ -1971,6 +1972,7 @@ declare const forceDisconnectPlaywrightForTarget: typeof forceDisconnectPlaywrig
 declare function resolvePageByTargetIdOrThrow(opts: {
     cdpUrl: string;
     targetId: string;
+    ssrfPolicy?: SsrfPolicy;
 }): Promise<Page>;
 /**
  * Get a page for a target, ensuring page state is initialized.
@@ -1978,6 +1980,7 @@ declare function resolvePageByTargetIdOrThrow(opts: {
 declare function getRestoredPageForTarget(opts: {
     cdpUrl: string;
     targetId?: string;
+    ssrfPolicy?: SsrfPolicy;
 }): Promise<Page>;
 
 declare function pressAndHoldViaCdp(opts: {
@@ -1987,6 +1990,7 @@ declare function pressAndHoldViaCdp(opts: {
     y: number;
     delay?: number;
     holdMs?: number;
+    ssrfPolicy?: SsrfPolicy;
 }): Promise<void>;
 
 /**