@bctrl/sdk 1.0.1

package/dist/drivers/stagehand/generated/page.js

@@ -0,0 +1,439 @@
+/**
+ * AUTO-GENERATED FILE - DO NOT EDIT
+ *
+ * Generated from: packages/automation-spec/src/drivers/stagehand/methods/
+ * Run `pnpm generate:stagehand` to regenerate.
+ */
+import { serializeFunctionSource } from '../../../internal/transport.js';
+/**
+ * RemoteStagehandPage - Remote Puppeteer Page API over RPC.
+ *
+ * @see https://pptr.dev/api/puppeteer.page
+ */
+export class RemoteStagehandPage {
+    id;
+    sendRpc;
+    constructor(id, sendRpc, createLocator, createDeepLocator, createResponse) {
+        this.id = id;
+        this.sendRpc = sendRpc;
+        this.createLocator = createLocator;
+        this.createDeepLocator = createDeepLocator;
+        this.createResponse = createResponse;
+        this._url = "";
+    }
+    createLocator;
+    createDeepLocator;
+    createResponse;
+    _url;
+    _eventListeners = new Map();
+    rpc(method, args) {
+        return this.sendRpc(method, args);
+    }
+    /**
+     * Register an event listener.
+     * @see https://docs.stagehand.dev/references/page#events
+     */
+    on(event, handler) {
+        if (!this._eventListeners.has(event)) {
+            this._eventListeners.set(event, new Set());
+        }
+        this._eventListeners.get(event).add(handler);
+        return this;
+    }
+    /**
+     * Register a one-time event listener.
+     * @see https://docs.stagehand.dev/references/page#events
+     */
+    once(event, handler) {
+        const wrapper = (...args) => {
+            this.off(event, wrapper);
+            handler(...args);
+        };
+        return this.on(event, wrapper);
+    }
+    /**
+     * Remove an event listener.
+     * @see https://docs.stagehand.dev/references/page#events
+     */
+    off(event, handler) {
+        const handlers = this._eventListeners.get(event);
+        if (handlers) {
+            handlers.delete(handler);
+        }
+        return 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
+     */
+    async goto(url, options) {
+        return this.rpc('goto', [url, options]);
+    }
+    /**
+     * 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
+     */
+    async reload(options) {
+        return this.rpc('reload', [options]);
+    }
+    /**
+     * 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
+     */
+    async goBack(options) {
+        return this.rpc('goBack', [options]);
+    }
+    /**
+     * 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
+     */
+    async goForward(options) {
+        return this.rpc('goForward', [options]);
+    }
+    /**
+     * 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() {
+        return this._url;
+    }
+    /**
+     * Get the title of the page.
+     *
+     * @example
+     * const title = await page.title();
+     *
+     * @see https://docs.stagehand.dev/references/page#title
+     */
+    async title() {
+        return this.rpc('title', []);
+    }
+    /**
+     * 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
+     */
+    async click(x, y, options) {
+        return this.rpc('click', [x, y, options]);
+    }
+    /**
+     * 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
+     */
+    async hover(x, y, options) {
+        return this.rpc('hover', [x, y, options]);
+    }
+    /**
+     * 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
+     */
+    async scroll(x, y, deltaX, deltaY) {
+        await this.rpc('scroll', [x, y, deltaX, deltaY]);
+    }
+    /**
+     * 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
+     */
+    async dragAndDrop(fromX, fromY, toX, toY, options) {
+        return this.rpc('dragAndDrop', [fromX, fromY, toX, toY, options]);
+    }
+    /**
+     * 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
+     */
+    async type(text, options) {
+        await this.rpc('type', [text, options]);
+    }
+    /**
+     * 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) {
+        return this.createLocator(selector);
+    }
+    /**
+     * 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) {
+        return this.createDeepLocator(selector);
+    }
+    /**
+     * 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
+     */
+    async evaluate(pageFunction, arg) {
+        const _pageFunction = serializeFunctionSource(pageFunction);
+        return this.rpc('evaluate', [_pageFunction, arg]);
+    }
+    /**
+     * 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
+     */
+    async addInitScript(script, arg) {
+        const _script = serializeFunctionSource(script);
+        await this.rpc('addInitScript', [_script, arg]);
+    }
+    /**
+     * 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
+     */
+    async screenshot(options) {
+        const result = await this.rpc('screenshot', [options]);
+        return Buffer.from(result, 'base64');
+    }
+    /**
+     * 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
+     */
+    async snapshot(options) {
+        return this.rpc('snapshot', [options]);
+    }
+    /**
+     * 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
+     */
+    async setViewportSize(width, height, options) {
+        await this.rpc('setViewportSize', [width, height, options]);
+    }
+    /**
+     * 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
+     */
+    async waitForLoadState(state, options) {
+        await this.rpc('waitForLoadState', [state, options]);
+    }
+    /**
+     * 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
+     */
+    async waitForSelector(selector, options) {
+        await this.rpc('waitForSelector', [selector, options]);
+    }
+}

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

@@ -0,0 +1,197 @@
+/**
+ * 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 { StagehandHeaderEntry, StagehandSecurityDetails, StagehandServerAddr } from '../types.js';
+export interface StagehandResponseData {
+    id: string;
+    url: string;
+    status: number;
+    statusText: string;
+    ok: boolean;
+    headers: Record<string, string>;
+    fromServiceWorker: boolean;
+}
+/**
+ * RemoteStagehandResponse - Remote Puppeteer Response API over RPC.
+ *
+ * @see https://pptr.dev/api/puppeteer.response
+ */
+export declare class RemoteStagehandResponse {
+    private sendRpc;
+    private readonly _id;
+    private readonly _url;
+    private readonly _status;
+    private readonly _statusText;
+    private readonly _ok;
+    private readonly _headers;
+    private readonly _fromServiceWorker;
+    constructor(sendRpc: SimpleRpcSender, data: StagehandResponseData);
+    private rpc;
+    /**
+     * Get the frame that initiated this response (synchronous version).
+     * Note: Not fully supported in remote SDK.
+     */
+    frame(): unknown;
+    /**
+     * Get the URL of the response.
+     *
+     * @example
+     * const url = response.url();
+     *
+     * @see https://docs.stagehand.dev/references/response#url
+     */
+    url(): string;
+    /**
+     * Get the HTTP status code of the response.
+     *
+     * @example
+     * const statusCode = response.status();
+     *
+     * @see https://docs.stagehand.dev/references/response#status
+     */
+    status(): number;
+    /**
+     * Get the HTTP status text of the response.
+     *
+     * @example
+     * const text = response.statusText();
+     *
+     * @see https://docs.stagehand.dev/references/response#statustext
+     */
+    statusText(): string;
+    /**
+     * Check if the response status is in the 200-299 range.
+     *
+     * @example
+     * if (response.ok()) { console.log("success"); }
+     *
+     * @see https://docs.stagehand.dev/references/response#ok
+     */
+    ok(): boolean;
+    /**
+     * Check if the response was served from a service worker.
+     *
+     * @example
+     * const fromSW = response.fromServiceWorker();
+     *
+     * @see https://docs.stagehand.dev/references/response#fromserviceworker
+     */
+    fromServiceWorker(): boolean;
+    /**
+     * Get the security details of the response (for HTTPS).
+     *
+     * @remarks
+     * Returns null for non-HTTPS responses.
+     *
+     * @example
+     * const security = await response.securityDetails();
+     *
+     * @see https://docs.stagehand.dev/references/response#securitydetails
+     */
+    securityDetails(): Promise<StagehandSecurityDetails | null>;
+    /**
+     * Get the server address (IP and port) that served the response.
+     *
+     * @example
+     * const addr = await response.serverAddr();
+     *
+     * @see https://docs.stagehand.dev/references/response#serveraddr
+     */
+    serverAddr(): Promise<StagehandServerAddr | null>;
+    /**
+     * Get all response headers as an object.
+     *
+     * @remarks
+     * Header names are lower-cased. Multiple values for the same header are joined with ", ".
+     *
+     * @example
+     * const headers = response.headers();
+     *
+     * @see https://docs.stagehand.dev/references/response#headers
+     */
+    headers(): Record<string, string>;
+    /**
+     * Get all response headers including those not exposed by the standard API.
+     *
+     * @example
+     * const allHeaders = await response.allHeaders();
+     *
+     * @see https://docs.stagehand.dev/references/response#allheaders
+     */
+    allHeaders(): Promise<Record<string, string>>;
+    /**
+     * Get the value of a specific header.
+     * @param name - Header name (case-insensitive).
+     *
+     * @example
+     * const contentType = await response.headerValue("content-type");
+     *
+     * @see https://docs.stagehand.dev/references/response#headervalue
+     */
+    headerValue(name: string): Promise<string | null>;
+    /**
+     * Get all values of a specific header (for headers with multiple values).
+     * @param name - Header name (case-insensitive).
+     *
+     * @example
+     * const cookies = await response.headerValues("set-cookie");
+     *
+     * @see https://docs.stagehand.dev/references/response#headervalues
+     */
+    headerValues(name: string): Promise<string[]>;
+    /**
+     * Get all response headers as an array of { name, value } objects.
+     *
+     * @remarks
+     * Preserves multiple values for the same header as separate entries.
+     *
+     * @example
+     * const headersArray = await response.headersArray();
+     *
+     * @see https://docs.stagehand.dev/references/response#headersarray
+     */
+    headersArray(): Promise<StagehandHeaderEntry[]>;
+    /**
+     * Get the response body as a Buffer.
+     *
+     * @example
+     * const buffer = await response.body();
+     *
+     * @see https://docs.stagehand.dev/references/response#body
+     */
+    body(): Promise<Buffer>;
+    /**
+     * Get the response body as text.
+     *
+     * @example
+     * const text = await response.text();
+     *
+     * @see https://docs.stagehand.dev/references/response#text
+     */
+    text(): Promise<string>;
+    /**
+     * Get the response body parsed as JSON.
+     *
+     * @example
+     * const data = await response.json();
+     *
+     * @see https://docs.stagehand.dev/references/response#json
+     */
+    json(): Promise<unknown>;
+    /**
+     * Wait for the response to finish and get any error message.
+     *
+     * @remarks
+     * Returns null if the response was successful, or an error message if it failed.
+     *
+     * @example
+     * const error = await response.finished();
+     *
+     * @see https://docs.stagehand.dev/references/response#finished
+     */
+    finished(): Promise<string | null>;
+}