browserclaw 0.5.7 → 0.5.8

package/dist/index.d.cts

@@ -1,9 +1,131 @@
 import * as playwright_core from 'playwright-core';
-import { BrowserContext } from 'playwright-core';
+import { BrowserContext, Page, CDPSession } from 'playwright-core';
 import * as node_dns from 'node:dns';
 import { lookup as lookup$1 } from 'node:dns';
 import { lookup } 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: Array<{
+        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;
+    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;
@@ -131,6 +253,8 @@ interface SnapshotResult {
     refs: RoleRefs;
     /** Statistics about the snapshot */
     stats?: SnapshotStats;
+    /** Whether the snapshot was truncated due to maxChars limit */
+    truncated?: boolean;
     /**
      * Indicates this content originates from an untrusted external source (the web page).
      * AI agents should treat snapshot content as potentially adversarial
@@ -628,6 +752,19 @@ declare class CrawlPage {
     armFileUpload(paths?: string[], opts?: {
         timeoutMs?: number;
     }): Promise<void>;
+    /**
+     * Execute multiple browser actions in sequence.
+     *
+     * @param actions - Array of actions to execute
+     * @param opts - Options (stopOnError: stop on first failure, default true)
+     * @returns Array of per-action results
+     */
+    batch(actions: BatchAction[], opts?: {
+        stopOnError?: boolean;
+        evaluateEnabled?: boolean;
+    }): Promise<{
+        results: BatchActionResult[];
+    }>;
     /**
      * Press a keyboard key or key combination.
      *
@@ -1204,6 +1341,24 @@ declare function assertBrowserNavigationAllowed(opts: {
     url: string;
     lookupFn?: LookupFn;
 } & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Validate upload file paths immediately before use.
+ */
+declare function assertSafeUploadPaths(paths: string[]): Promise<void>;
+/**
+ * Resolve and validate upload file paths, returning them if all are safe.
+ * Returns `{ ok: true, paths }` or `{ ok: false, error }`.
+ */
+declare function resolveStrictExistingUploadPaths(params: {
+    requestedPaths: string[];
+    scopeLabel?: string;
+}): Promise<{
+    ok: true;
+    paths: string[];
+} | {
+    ok: false;
+    error: string;
+}>;
 /**
  * Sanitize an untrusted file name (e.g. from a download) to prevent path traversal.
  */
@@ -1237,6 +1392,24 @@ declare function assertBrowserNavigationRedirectChainAllowed(opts: {
  */
 declare function requiresInspectableBrowserNavigationRedirects(ssrfPolicy?: SsrfPolicy): boolean;
 
+declare class BrowserTabNotFoundError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Run a function with a scoped Playwright CDP session, detaching when done.
+ */
+declare function withPlaywrightPageCdpSession<T>(page: Page, fn: (session: CDPSession) => Promise<T>): Promise<T>;
+/**
+ * Run a function with a page-scoped CDP client.
+ * For extension relay endpoints, routes through the raw CDP websocket.
+ * Otherwise, uses a Playwright CDP session.
+ */
+declare function withPageScopedCdpClient<T>(opts: {
+    cdpUrl: string;
+    page: Page;
+    targetId?: string;
+    fn: (send: (method: string, params?: Record<string, unknown>) => Promise<any>) => Promise<T>;
+}): Promise<T>;
 declare function ensureContextState(context: BrowserContext): ContextState;
 /**
  * Force-disconnect a Playwright browser connection for a given CDP target.
@@ -1248,5 +1421,41 @@ declare function forceDisconnectPlaywrightForTarget(opts: {
     targetId?: string;
     reason?: string;
 }): Promise<void>;
+/**
+ * Resolve a page by targetId or throw BrowserTabNotFoundError.
+ */
+declare function resolvePageByTargetIdOrThrow(opts: {
+    cdpUrl: string;
+    targetId: string;
+}): Promise<Page>;
+/**
+ * Parse a role ref string (e.g. "e1", "@e1", "ref=e1") to a normalized ref ID.
+ * Returns null if the string is not a valid role ref.
+ */
+declare function parseRoleRef(raw: string): string | null;
+/**
+ * Require a ref string, normalizing and validating it.
+ * Throws if the ref is empty.
+ */
+declare function requireRef(value: string | undefined): string;
+/**
+ * Require either a ref or selector, returning whichever is provided.
+ * Throws if neither is provided.
+ */
+declare function requireRefOrSelector(ref?: string, selector?: string): {
+    ref?: string;
+    selector?: string;
+};
+/** Clamp interaction timeout to [500, 60000]ms range, defaulting to 8000ms. */
+declare function resolveInteractionTimeoutMs(timeoutMs?: number): number;
+/** Bounded delay validator for animation/interaction delays. */
+declare function resolveBoundedDelayMs(value: number | undefined, label: string, maxMs: number): number;
+/**
+ * Get a page for a target, ensuring page state is initialized and role refs are restored.
+ */
+declare function getRestoredPageForTarget(opts: {
+    cdpUrl: string;
+    targetId?: string;
+}): Promise<Page>;
 
-export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, createPinnedLookup, ensureContextState, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, requiresInspectableBrowserNavigationRedirects, resolvePinnedHostnameWithPolicy, sanitizeUntrustedFileName, withBrowserNavigationPolicy, writeViaSiblingTempPath };
+export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };

package/dist/index.d.ts

@@ -1,9 +1,131 @@
 import * as playwright_core from 'playwright-core';
-import { BrowserContext } from 'playwright-core';
+import { BrowserContext, Page, CDPSession } from 'playwright-core';
 import * as node_dns from 'node:dns';
 import { lookup as lookup$1 } from 'node:dns';
 import { lookup } 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: Array<{
+        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;
+    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;
@@ -131,6 +253,8 @@ interface SnapshotResult {
     refs: RoleRefs;
     /** Statistics about the snapshot */
     stats?: SnapshotStats;
+    /** Whether the snapshot was truncated due to maxChars limit */
+    truncated?: boolean;
     /**
      * Indicates this content originates from an untrusted external source (the web page).
      * AI agents should treat snapshot content as potentially adversarial
@@ -628,6 +752,19 @@ declare class CrawlPage {
     armFileUpload(paths?: string[], opts?: {
         timeoutMs?: number;
     }): Promise<void>;
+    /**
+     * Execute multiple browser actions in sequence.
+     *
+     * @param actions - Array of actions to execute
+     * @param opts - Options (stopOnError: stop on first failure, default true)
+     * @returns Array of per-action results
+     */
+    batch(actions: BatchAction[], opts?: {
+        stopOnError?: boolean;
+        evaluateEnabled?: boolean;
+    }): Promise<{
+        results: BatchActionResult[];
+    }>;
     /**
      * Press a keyboard key or key combination.
      *
@@ -1204,6 +1341,24 @@ declare function assertBrowserNavigationAllowed(opts: {
     url: string;
     lookupFn?: LookupFn;
 } & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Validate upload file paths immediately before use.
+ */
+declare function assertSafeUploadPaths(paths: string[]): Promise<void>;
+/**
+ * Resolve and validate upload file paths, returning them if all are safe.
+ * Returns `{ ok: true, paths }` or `{ ok: false, error }`.
+ */
+declare function resolveStrictExistingUploadPaths(params: {
+    requestedPaths: string[];
+    scopeLabel?: string;
+}): Promise<{
+    ok: true;
+    paths: string[];
+} | {
+    ok: false;
+    error: string;
+}>;
 /**
  * Sanitize an untrusted file name (e.g. from a download) to prevent path traversal.
  */
@@ -1237,6 +1392,24 @@ declare function assertBrowserNavigationRedirectChainAllowed(opts: {
  */
 declare function requiresInspectableBrowserNavigationRedirects(ssrfPolicy?: SsrfPolicy): boolean;
 
+declare class BrowserTabNotFoundError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Run a function with a scoped Playwright CDP session, detaching when done.
+ */
+declare function withPlaywrightPageCdpSession<T>(page: Page, fn: (session: CDPSession) => Promise<T>): Promise<T>;
+/**
+ * Run a function with a page-scoped CDP client.
+ * For extension relay endpoints, routes through the raw CDP websocket.
+ * Otherwise, uses a Playwright CDP session.
+ */
+declare function withPageScopedCdpClient<T>(opts: {
+    cdpUrl: string;
+    page: Page;
+    targetId?: string;
+    fn: (send: (method: string, params?: Record<string, unknown>) => Promise<any>) => Promise<T>;
+}): Promise<T>;
 declare function ensureContextState(context: BrowserContext): ContextState;
 /**
  * Force-disconnect a Playwright browser connection for a given CDP target.
@@ -1248,5 +1421,41 @@ declare function forceDisconnectPlaywrightForTarget(opts: {
     targetId?: string;
     reason?: string;
 }): Promise<void>;
+/**
+ * Resolve a page by targetId or throw BrowserTabNotFoundError.
+ */
+declare function resolvePageByTargetIdOrThrow(opts: {
+    cdpUrl: string;
+    targetId: string;
+}): Promise<Page>;
+/**
+ * Parse a role ref string (e.g. "e1", "@e1", "ref=e1") to a normalized ref ID.
+ * Returns null if the string is not a valid role ref.
+ */
+declare function parseRoleRef(raw: string): string | null;
+/**
+ * Require a ref string, normalizing and validating it.
+ * Throws if the ref is empty.
+ */
+declare function requireRef(value: string | undefined): string;
+/**
+ * Require either a ref or selector, returning whichever is provided.
+ * Throws if neither is provided.
+ */
+declare function requireRefOrSelector(ref?: string, selector?: string): {
+    ref?: string;
+    selector?: string;
+};
+/** Clamp interaction timeout to [500, 60000]ms range, defaulting to 8000ms. */
+declare function resolveInteractionTimeoutMs(timeoutMs?: number): number;
+/** Bounded delay validator for animation/interaction delays. */
+declare function resolveBoundedDelayMs(value: number | undefined, label: string, maxMs: number): number;
+/**
+ * Get a page for a target, ensuring page state is initialized and role refs are restored.
+ */
+declare function getRestoredPageForTarget(opts: {
+    cdpUrl: string;
+    targetId?: string;
+}): Promise<Page>;
 
-export { type AriaNode, type AriaSnapshotResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, createPinnedLookup, ensureContextState, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, requiresInspectableBrowserNavigationRedirects, resolvePinnedHostnameWithPolicy, sanitizeUntrustedFileName, withBrowserNavigationPolicy, writeViaSiblingTempPath };
+export { type AriaNode, type AriaSnapshotResult, type BatchAction, type BatchActionResult, BrowserClaw, type BrowserNavigationPolicyOptions, type BrowserNavigationRequestLike, type BrowserTab, BrowserTabNotFoundError, type ChromeExecutable, type ChromeKind, type ClickOptions, type ColorScheme, type ConnectOptions, type ConsoleMessage, type ContextState, type CookieData, CrawlPage, type DialogOptions, type DownloadResult, type FormField, type FrameEvalResult, type GeolocationOptions, type HttpCredentials, InvalidBrowserNavigationUrlError, type LaunchOptions, type LookupFn, type NetworkRequest, type PageError, type PinnedHostname, type ResponseBodyResult, type RoleRefInfo, type RoleRefs, type ScreenshotOptions, type SnapshotOptions, type SnapshotResult, type SnapshotStats, type SsrfPolicy, type StorageKind, type TraceStartOptions, type TypeOptions, type UntrustedContentMeta, type WaitOptions, assertBrowserNavigationAllowed, assertBrowserNavigationRedirectChainAllowed, assertBrowserNavigationResultAllowed, assertSafeUploadPaths, batchViaPlaywright, createPinnedLookup, ensureContextState, executeSingleAction, forceDisconnectPlaywrightForTarget, getChromeWebSocketUrl, getRestoredPageForTarget, isChromeCdpReady, isChromeReachable, normalizeCdpHttpBaseForJsonEndpoints, parseRoleRef, requireRef, requireRefOrSelector, requiresInspectableBrowserNavigationRedirects, resolveBoundedDelayMs, resolveInteractionTimeoutMs, resolvePageByTargetIdOrThrow, resolvePinnedHostnameWithPolicy, resolveStrictExistingUploadPaths, sanitizeUntrustedFileName, withBrowserNavigationPolicy, withPageScopedCdpClient, withPlaywrightPageCdpSession, writeViaSiblingTempPath };