@bctrl/sdk 1.0.1

package/dist/drivers/stagehand/generated/page.d.ts

@@ -0,0 +1,377 @@
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * Generated from: packages/automation-spec/src/drivers/stagehand/methods/
+ * Run `pnpm generate:stagehand` to regenerate.
+ */
+import type { SimpleRpcSender } from '../../../internal/transport.js';
+import type { StagehandClickOptions, StagehandDragAndDropOptions, StagehandGotoOptions, StagehandHoverOptions, StagehandLoadState, StagehandReloadOptions, StagehandScreenshotOptions, StagehandSnapshotOptions, StagehandSnapshotResult, StagehandTypeOptions, StagehandViewportOptions, StagehandWaitForSelectorOptions } from '../types.js';
+import { RemoteStagehandLocator } from './locator.js';
+import type { RemoteStagehandResponse } from './response.js';
+/**
+ * RemoteStagehandPage - Remote Puppeteer Page API over RPC.
+ *
+ * @see https://pptr.dev/api/puppeteer.page
+ */
+export declare class RemoteStagehandPage {
+    readonly id: string;
+    protected sendRpc: SimpleRpcSender;
+    constructor(id: string, sendRpc: SimpleRpcSender, createLocator: (selector: string) => RemoteStagehandLocator, createDeepLocator: (selector: string) => RemoteStagehandLocator, createResponse: (data: unknown) => RemoteStagehandResponse);
+    private createLocator;
+    private createDeepLocator;
+    private createResponse;
+    private _url;
+    private _eventListeners;
+    private rpc;
+    /**
+     * Register an event listener.
+     * @see https://docs.stagehand.dev/references/page#events
+     */
+    on(event: string, handler: Function): this;
+    /**
+     * Register a one-time event listener.
+     * @see https://docs.stagehand.dev/references/page#events
+     */
+    once(event: string, handler: Function): this;
+    /**
+     * Remove an event listener.
+     * @see https://docs.stagehand.dev/references/page#events
+     */
+    off(event: string, handler: Function): this;
+    /**
+     * Navigate the page to a URL.
+     * @param url - URL to navigate to.
+     *
+     * @remarks
+     * Options include:
+     * - waitUntil: 'load' | 'domcontentloaded' | 'networkidle'
+     * - timeoutMs: Maximum navigation time in milliseconds
+     *
+     * @example
+     * await page.goto("https://example.com");
+     *
+     * @example
+     * await page.goto("https://example.com", { waitUntil: "networkidle" });
+     *
+     * @see https://docs.stagehand.dev/references/page#goto
+     */
+    goto(url: string, options?: StagehandGotoOptions): Promise<RemoteStagehandResponse | null>;
+    /**
+     * Reload the current page.
+     *
+     * @remarks
+     * Options include:
+     * - waitUntil: 'load' | 'domcontentloaded' | 'networkidle'
+     * - timeoutMs: Maximum reload time in milliseconds
+     * - ignoreCache: Whether to bypass the browser cache
+     *
+     * @example
+     * await page.reload();
+     *
+     * @example
+     * await page.reload({ ignoreCache: true });
+     *
+     * @see https://docs.stagehand.dev/references/page#reload
+     */
+    reload(options?: StagehandReloadOptions): Promise<RemoteStagehandResponse | null>;
+    /**
+     * Navigate to the previous page in history.
+     *
+     * @remarks
+     * Returns null if there is no previous page.
+     *
+     * @example
+     * await page.goBack();
+     *
+     * @see https://docs.stagehand.dev/references/page#goback
+     */
+    goBack(options?: StagehandGotoOptions): Promise<RemoteStagehandResponse | null>;
+    /**
+     * Navigate to the next page in history.
+     *
+     * @remarks
+     * Returns null if there is no next page.
+     *
+     * @example
+     * await page.goForward();
+     *
+     * @see https://docs.stagehand.dev/references/page#goforward
+     */
+    goForward(options?: StagehandGotoOptions): Promise<RemoteStagehandResponse | null>;
+    /**
+     * Get the current URL of the page.
+     *
+     * @remarks
+     * This is a synchronous method that returns the current URL.
+     *
+     * @example
+     * const currentUrl = page.url();
+     *
+     * @see https://docs.stagehand.dev/references/page#url
+     */
+    url(): string;
+    /**
+     * Get the title of the page.
+     *
+     * @example
+     * const title = await page.title();
+     *
+     * @see https://docs.stagehand.dev/references/page#title
+     */
+    title(): Promise<string>;
+    /**
+     * Click at the specified coordinates.
+     * @param x - X coordinate to click.
+     * @param y - Y coordinate to click.
+     *
+     * @remarks
+     * Options include:
+     * - button: 'left' | 'right' | 'middle' (default: 'left')
+     * - clickCount: Number of clicks (default: 1, use 2 for double-click)
+     * - returnXpath: If true, returns the XPath of the clicked element
+     *
+     * @example
+     * await page.click(100, 200);
+     *
+     * @example
+     * await page.click(100, 200, { clickCount: 2 }); // Double click
+     *
+     * @example
+     * const xpath = await page.click(100, 200, { returnXpath: true });
+     *
+     * @see https://docs.stagehand.dev/references/page#click
+     */
+    click(x: number, y: number, options?: StagehandClickOptions): Promise<string | void>;
+    /**
+     * Hover at the specified coordinates.
+     * @param x - X coordinate to hover over.
+     * @param y - Y coordinate to hover over.
+     *
+     * @remarks
+     * If returnXpath is true, returns the XPath of the hovered element.
+     *
+     * @example
+     * await page.hover(300, 150);
+     *
+     * @example
+     * const xpath = await page.hover(300, 150, { returnXpath: true });
+     *
+     * @see https://docs.stagehand.dev/references/page#hover
+     */
+    hover(x: number, y: number, options?: StagehandHoverOptions): Promise<string | void>;
+    /**
+     * Scroll at the specified position by the given delta.
+     * @param x - X coordinate of scroll origin.
+     * @param y - Y coordinate of scroll origin.
+     * @param deltaX - Horizontal scroll amount in pixels.
+     * @param deltaY - Vertical scroll amount in pixels.
+     *
+     * @remarks
+     * Positive deltaY scrolls down, negative scrolls up.
+     *
+     * @example
+     * await page.scroll(400, 300, 0, 200); // Scroll down 200px
+     *
+     * @example
+     * await page.scroll(400, 300, 0, -200); // Scroll up 200px
+     *
+     * @see https://docs.stagehand.dev/references/page#scroll
+     */
+    scroll(x: number, y: number, deltaX: number, deltaY: number): Promise<void>;
+    /**
+     * Drag from one point to another.
+     * @param fromX - Starting X coordinate.
+     * @param fromY - Starting Y coordinate.
+     * @param toX - Ending X coordinate.
+     * @param toY - Ending Y coordinate.
+     *
+     * @remarks
+     * If returnXpath is true, returns [fromXpath, toXpath] of the dragged elements.
+     *
+     * @example
+     * await page.dragAndDrop(100, 100, 300, 300);
+     *
+     * @example
+     * const [from, to] = await page.dragAndDrop(100, 100, 300, 300, { returnXpath: true });
+     *
+     * @see https://docs.stagehand.dev/references/page#draganddrop
+     */
+    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options?: StagehandDragAndDropOptions): Promise<[string, string] | void>;
+    /**
+     * Type text into the currently focused element.
+     * @param text - Text to type.
+     *
+     * @remarks
+     * The delay option adds a pause between keystrokes for realistic typing.
+     *
+     * @example
+     * await page.type("Hello, World!");
+     *
+     * @example
+     * await page.type("Slow typing", { delay: 100 });
+     *
+     * @see https://docs.stagehand.dev/references/page#type
+     */
+    type(text: string, options?: StagehandTypeOptions): Promise<void>;
+    /**
+     * Create a locator for an element using a CSS or XPath selector.
+     * @param selector - CSS or XPath selector.
+     *
+     * @remarks
+     * Locators support automatic shadow DOM traversal.
+     *
+     * @example
+     * const button = page.locator("button.submit");
+     *
+     * @example
+     * const input = page.locator("#email");
+     *
+     * @example
+     * const elem = page.locator("//button[@type=\"submit\"]");
+     *
+     * @see https://docs.stagehand.dev/references/page#locator
+     */
+    locator(selector: string): RemoteStagehandLocator;
+    /**
+     * Create a deep locator that can traverse iframes and shadow roots.
+     * @param selector - Selector with optional hop notation for iframes.
+     *
+     * @remarks
+     * Deep locators use hop notation to navigate through iframes:
+     * - Use >>> to hop into an iframe
+     * - Example: "#outer-frame >>> #inner-frame >>> button"
+     *
+     * @example
+     * const nestedButton = page.deepLocator("button.nested-action");
+     *
+     * @example
+     * const frameElement = page.deepLocator("#frame >>> .inside-frame");
+     *
+     * @see https://docs.stagehand.dev/references/deep-locator
+     */
+    deepLocator(selector: string): RemoteStagehandLocator;
+    /**
+     * Execute JavaScript code within the page context.
+     * @param pageFunction - Function or expression to evaluate in the page context.
+     * @param arg - Argument to pass to the function.
+     *
+     * @remarks
+     * The return value must be JSON-serializable.
+     *
+     * @example
+     * const title = await page.evaluate(() => document.title);
+     *
+     * @example
+     * const text = await page.evaluate((sel) => document.querySelector(sel)?.textContent, "#heading");
+     *
+     * @see https://docs.stagehand.dev/references/page#evaluate
+     */
+    evaluate<R, Arg = unknown>(pageFunction: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
+    /**
+     * Add an initialization script that runs before page scripts.
+     * @param script - The script to inject.
+     * @param arg - Argument to pass to the function.
+     *
+     * @remarks
+     * The script runs on every navigation.
+     *
+     * @example
+     * await page.addInitScript(() => { window.injected = true; });
+     *
+     * @see https://docs.stagehand.dev/references/page#addinitscript
+     */
+    addInitScript<Arg = unknown>(script: string | {
+        path?: string;
+        content?: string;
+    } | ((arg: Arg) => unknown), arg?: Arg): Promise<void>;
+    /**
+     * Capture a screenshot of the page.
+     *
+     * @remarks
+     * Options include:
+     * - path: File path to save the screenshot
+     * - fullPage: Capture the full scrollable page
+     * - type: 'png' | 'jpeg'
+     * - quality: JPEG quality (0-100)
+     * - clip: Specific region to capture
+     *
+     * @example
+     * const buffer = await page.screenshot();
+     *
+     * @example
+     * await page.screenshot({ path: "./screenshot.png", fullPage: true });
+     *
+     * @see https://docs.stagehand.dev/references/page#screenshot
+     */
+    screenshot(options?: StagehandScreenshotOptions): Promise<Buffer>;
+    /**
+     * Get a snapshot of the page DOM.
+     *
+     * @remarks
+     * Returns a structured representation of the page content.
+     *
+     * @example
+     * const snapshot = await page.snapshot();
+     *
+     * @see https://docs.stagehand.dev/references/page#snapshot
+     */
+    snapshot(options?: StagehandSnapshotOptions): Promise<StagehandSnapshotResult>;
+    /**
+     * Set the viewport size of the page.
+     * @param width - Viewport width in pixels.
+     * @param height - Viewport height in pixels.
+     * @param options - Additional viewport options.
+     *
+     * @example
+     * await page.setViewportSize(1280, 720);
+     *
+     * @example
+     * await page.setViewportSize(375, 667, { deviceScaleFactor: 2 });
+     *
+     * @see https://docs.stagehand.dev/references/page#setviewportsize
+     */
+    setViewportSize(width: number, height: number, options?: StagehandViewportOptions): Promise<void>;
+    /**
+     * Wait for the page to reach a specific load state.
+     * @param state - Load state to wait for.
+     *
+     * @remarks
+     * States:
+     * - 'load': Wait for the load event
+     * - 'domcontentloaded': Wait for DOMContentLoaded event
+     * - 'networkidle': Wait until no network connections for 500ms
+     *
+     * @example
+     * await page.waitForLoadState("domcontentloaded");
+     *
+     * @example
+     * await page.waitForLoadState("networkidle");
+     *
+     * @see https://docs.stagehand.dev/references/page#waitforloadstate
+     */
+    waitForLoadState(state?: StagehandLoadState, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Wait for an element matching the selector to appear.
+     * @param selector - Selector to wait for.
+     *
+     * @remarks
+     * Options include:
+     * - state: 'visible' | 'hidden' | 'attached' | 'detached'
+     * - timeout: Maximum wait time in milliseconds
+     * - pierceShadow: Whether to pierce shadow DOM (default: true)
+     *
+     * @example
+     * await page.waitForSelector("#submit-btn");
+     *
+     * @example
+     * await page.waitForSelector(".loading", { state: "hidden" });
+     *
+     * @example
+     * await page.waitForSelector(".modal", { state: "detached" });
+     *
+     * @see https://docs.stagehand.dev/references/page#waitforselector
+     */
+    waitForSelector(selector: string, options?: StagehandWaitForSelectorOptions): Promise<void>;
+}