tuna-agent 0.1.0 → 0.1.2

package/dist/browser/browser.d.ts

@@ -0,0 +1,722 @@
+import { type FrameEvalResult } from './actions/evaluate.js';
+import type { LaunchOptions, ConnectOptions, SnapshotResult, SnapshotOptions, AriaSnapshotResult, BrowserTab, FormField, ClickOptions, TypeOptions, WaitOptions, ScreenshotOptions, ConsoleMessage, PageError, NetworkRequest, CookieData, StorageKind, SsrfPolicy, DownloadResult, DialogOptions, ResponseBodyResult, TraceStartOptions, ColorScheme, GeolocationOptions, HttpCredentials } from './types.js';
+/**
+ * Represents a single browser page/tab with ref-based automation.
+ *
+ * The workflow is: **snapshot → read refs → act on refs**.
+ *
+ * @example
+ * ```ts
+ * const page = await browser.open('https://example.com');
+ *
+ * // 1. Take a snapshot to get refs
+ * const { snapshot, refs } = await page.snapshot();
+ * // snapshot: AI-readable text tree
+ * // refs: { "e1": { role: "link", name: "More info" }, ... }
+ *
+ * // 2. Act on refs
+ * await page.click('e1');
+ * await page.type('e3', 'hello');
+ * ```
+ */
+export declare class CrawlPage {
+    private readonly cdpUrl;
+    private readonly targetId;
+    private readonly ssrfPolicy;
+    /** @internal */
+    constructor(cdpUrl: string, targetId: string, ssrfPolicy?: SsrfPolicy);
+    /** The CDP target ID for this page. Use this to identify the page in multi-tab scenarios. */
+    get id(): string;
+    /**
+     * Take an AI-readable snapshot of the page.
+     *
+     * Returns a text tree with numbered refs (`e1`, `e2`, ...) that map to
+     * interactive elements. Use these refs with actions like `click()` and `type()`.
+     *
+     * @param opts - Snapshot options (mode, filtering, depth limits)
+     * @returns Snapshot text, ref map, and statistics
+     *
+     * @example
+     * ```ts
+     * // Default snapshot (aria mode)
+     * const { snapshot, refs } = await page.snapshot();
+     *
+     * // Interactive elements only, compact
+     * const result = await page.snapshot({ interactive: true, compact: true });
+     *
+     * // Role-based mode (uses getByRole resolution)
+     * const result = await page.snapshot({ mode: 'role' });
+     * ```
+     */
+    snapshot(opts?: SnapshotOptions): Promise<SnapshotResult>;
+    /**
+     * Take a raw ARIA accessibility tree snapshot via CDP.
+     *
+     * Unlike `snapshot()`, this returns structured node data rather than
+     * an AI-readable text tree. Useful for programmatic accessibility analysis.
+     *
+     * @param opts - Options (limit: max nodes to return, default 500)
+     * @returns Array of accessibility tree nodes
+     */
+    ariaSnapshot(opts?: {
+        limit?: number;
+    }): Promise<AriaSnapshotResult>;
+    /**
+     * Click an element by ref.
+     *
+     * @param ref - Ref ID from a snapshot (e.g. `'e1'`)
+     * @param opts - Click options (double-click, button, modifiers)
+     *
+     * @example
+     * ```ts
+     * await page.click('e1');
+     * await page.click('e2', { doubleClick: true });
+     * await page.click('e3', { button: 'right' });
+     * await page.click('e4', { modifiers: ['Control'] });
+     * ```
+     */
+    click(ref: string, opts?: ClickOptions): Promise<void>;
+    /**
+     * Type text into an input element by ref.
+     *
+     * By default, uses Playwright's `fill()` for instant input. Use `slowly: true`
+     * to simulate real keystroke typing with a 75ms delay per character.
+     *
+     * @param ref - Ref ID of the input element (e.g. `'e3'`)
+     * @param text - Text to type
+     * @param opts - Type options (submit, slowly)
+     *
+     * @example
+     * ```ts
+     * await page.type('e3', 'hello world');
+     * await page.type('e3', 'slow typing', { slowly: true });
+     * await page.type('e3', 'search query', { submit: true }); // press Enter after
+     * ```
+     */
+    type(ref: string, text: string, opts?: TypeOptions): Promise<void>;
+    /**
+     * Hover over an element by ref.
+     *
+     * @param ref - Ref ID from a snapshot
+     * @param opts - Timeout options
+     */
+    hover(ref: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Select option(s) in a `<select>` dropdown by ref.
+     *
+     * @param ref - Ref ID of the select element
+     * @param values - One or more option labels/values to select
+     *
+     * @example
+     * ```ts
+     * await page.select('e5', 'Option A');
+     * await page.select('e5', 'Option A', 'Option B'); // multi-select
+     * ```
+     */
+    select(ref: string, ...values: string[]): Promise<void>;
+    /**
+     * Drag one element to another.
+     *
+     * @param startRef - Ref ID of the element to drag
+     * @param endRef - Ref ID of the drop target
+     * @param opts - Timeout options
+     */
+    drag(startRef: string, endRef: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Fill multiple form fields at once.
+     *
+     * Supports text inputs, checkboxes, and radio buttons.
+     *
+     * @param fields - Array of form fields to fill
+     *
+     * @example
+     * ```ts
+     * await page.fill([
+     *   { ref: 'e2', type: 'text', value: 'Jane Doe' },
+     *   { ref: 'e4', type: 'text', value: 'jane@example.com' },
+     *   { ref: 'e6', type: 'checkbox', value: true },
+     * ]);
+     * ```
+     */
+    fill(fields: FormField[]): Promise<void>;
+    /**
+     * Scroll an element into the visible viewport.
+     *
+     * @param ref - Ref ID of the element to scroll to
+     * @param opts - Timeout options
+     */
+    scrollIntoView(ref: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Highlight an element in the browser (Playwright built-in highlight).
+     *
+     * @param ref - Ref ID of the element to highlight
+     */
+    highlight(ref: string): Promise<void>;
+    /**
+     * Set files on an `<input type="file">` element.
+     *
+     * @param ref - Ref ID of the file input element
+     * @param paths - Array of file paths to upload
+     */
+    uploadFile(ref: string, paths: string[]): Promise<void>;
+    /**
+     * Arm a one-shot dialog handler (alert, confirm, prompt).
+     *
+     * Returns a promise — store it (don't await), trigger the dialog, then await it.
+     *
+     * @param opts - Dialog options (accept/dismiss, prompt text, timeout)
+     *
+     * @example
+     * ```ts
+     * const dialogDone = page.armDialog({ accept: true }); // don't await here
+     * await page.click('e5'); // triggers confirm()
+     * await dialogDone;       // wait for dialog to be handled
+     * ```
+     */
+    armDialog(opts: DialogOptions): Promise<void>;
+    /**
+     * Arm a one-shot file chooser handler.
+     *
+     * Returns a promise — store it (don't await), trigger the file picker, then await it.
+     *
+     * @param paths - File paths to set when the chooser appears (empty to clear)
+     * @param opts - Timeout options
+     *
+     * @example
+     * ```ts
+     * const uploadDone = page.armFileUpload(['/path/to/file.pdf']); // don't await here
+     * await page.click('e3'); // triggers file picker
+     * await uploadDone;       // wait for files to be set
+     * ```
+     */
+    armFileUpload(paths?: string[], opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Press a keyboard key or key combination.
+     *
+     * Uses Playwright's key names. Supports combinations with `+`.
+     *
+     * @param key - Key to press (e.g. `'Enter'`, `'Tab'`, `'Control+a'`, `'Meta+c'`)
+     * @param opts - Options (delayMs: hold time between keydown and keyup)
+     *
+     * @example
+     * ```ts
+     * await page.press('Enter');
+     * await page.press('Control+a');
+     * await page.press('Meta+Shift+p');
+     * ```
+     */
+    press(key: string, opts?: {
+        delayMs?: number;
+    }): Promise<void>;
+    /**
+     * Get the current URL of the page.
+     */
+    url(): Promise<string>;
+    /**
+     * Get the page title.
+     */
+    title(): Promise<string>;
+    /**
+     * Navigate to a URL.
+     *
+     * @param url - The URL to navigate to
+     * @param opts - Timeout options
+     * @returns The final URL after navigation (may differ due to redirects)
+     */
+    goto(url: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        url: string;
+    }>;
+    /**
+     * Reload the current page.
+     *
+     * @param opts - Timeout options
+     */
+    reload(opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Navigate back in browser history.
+     *
+     * @param opts - Timeout options
+     */
+    goBack(opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Navigate forward in browser history.
+     *
+     * @param opts - Timeout options
+     */
+    goForward(opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Wait for various conditions on the page.
+     *
+     * Multiple conditions can be specified — they are checked in order.
+     *
+     * @param opts - Wait conditions (text, URL, load state, selector, etc.)
+     *
+     * @example
+     * ```ts
+     * await page.waitFor({ loadState: 'networkidle' });
+     * await page.waitFor({ text: 'Welcome back' });
+     * await page.waitFor({ url: '**\/dashboard' });
+     * await page.waitFor({ timeMs: 1000 }); // sleep
+     * ```
+     */
+    waitFor(opts: WaitOptions): Promise<void>;
+    /**
+     * Run JavaScript in the browser page context.
+     *
+     * The function string is evaluated in the browser's sandbox, not in Node.js.
+     * Pass a `ref` to receive the element as the first argument.
+     *
+     * @param fn - JavaScript function body as a string
+     * @param opts - Options (ref: scope evaluation to a specific element)
+     * @returns The return value of the evaluated function
+     *
+     * @example
+     * ```ts
+     * const title = await page.evaluate('() => document.title');
+     * const text = await page.evaluate('(el) => el.textContent', { ref: 'e1' });
+     * const count = await page.evaluate('() => document.querySelectorAll("img").length');
+     * ```
+     */
+    evaluate(fn: string, opts?: {
+        ref?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    /**
+     * Run JavaScript in ALL frames on the page (including cross-origin iframes).
+     *
+     * Playwright can access cross-origin frames via CDP, bypassing the same-origin policy.
+     * This is essential for filling payment iframes (Stripe, etc.).
+     *
+     * @param fn - JavaScript function body as a string
+     * @returns Array of results from each frame where evaluation succeeded
+     *
+     * @example
+     * ```ts
+     * const results = await page.evaluateInAllFrames(`() => {
+     *   const el = document.querySelector('input[name="cardnumber"]');
+     *   return el ? 'found' : null;
+     * }`);
+     * ```
+     */
+    evaluateInAllFrames(fn: string): Promise<FrameEvalResult[]>;
+    /**
+     * Take a screenshot of the page or a specific element.
+     *
+     * @param opts - Screenshot options (fullPage, ref, element, type)
+     * @returns PNG or JPEG image as a Buffer
+     *
+     * @example
+     * ```ts
+     * const screenshot = await page.screenshot();
+     * const fullPage = await page.screenshot({ fullPage: true });
+     * const element = await page.screenshot({ ref: 'e1' });
+     * ```
+     */
+    screenshot(opts?: ScreenshotOptions): Promise<Buffer>;
+    /**
+     * Export the page as a PDF.
+     *
+     * Only works in headless mode.
+     *
+     * @returns PDF document as a Buffer
+     */
+    pdf(): Promise<Buffer>;
+    /**
+     * Take a screenshot with numbered labels overlaid on referenced elements.
+     *
+     * Useful for visual debugging — each ref gets a numbered badge and border.
+     *
+     * @param refs - Array of ref IDs to label
+     * @param opts - Options (maxLabels: limit, type: image format)
+     * @returns Screenshot buffer, label positions, and any skipped refs
+     *
+     * @example
+     * ```ts
+     * const { buffer, labels, skipped } = await page.screenshotWithLabels(['e1', 'e2', 'e3']);
+     * fs.writeFileSync('labeled.png', buffer);
+     * ```
+     */
+    screenshotWithLabels(refs: string[], opts?: {
+        maxLabels?: number;
+        type?: 'png' | 'jpeg';
+    }): Promise<{
+        buffer: Buffer;
+        labels: Array<{
+            ref: string;
+            index: number;
+            box: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            };
+        }>;
+        skipped: string[];
+    }>;
+    /**
+     * Start recording a Playwright trace.
+     *
+     * Traces capture screenshots, DOM snapshots, and network activity.
+     * Stop with `traceStop()` to save the trace file.
+     *
+     * @param opts - Trace options (screenshots, snapshots, sources)
+     */
+    traceStart(opts?: TraceStartOptions): Promise<void>;
+    /**
+     * Stop recording a trace and save it to a file.
+     *
+     * @param path - File path to save the trace (e.g. `'trace.zip'`)
+     * @param opts - Options (allowedOutputRoots: constrain output to specific directories)
+     */
+    traceStop(path: string, opts?: {
+        allowedOutputRoots?: string[];
+    }): Promise<void>;
+    /**
+     * Wait for a network response matching a URL pattern and return its body.
+     *
+     * @param url - URL string or pattern to match
+     * @param opts - Options (timeoutMs, maxChars)
+     * @returns Response body, status, headers, and truncation info
+     *
+     * @example
+     * ```ts
+     * const resp = await page.responseBody('/api/data');
+     * console.log(resp.status, resp.body);
+     * ```
+     */
+    responseBody(url: string, opts?: {
+        timeoutMs?: number;
+        maxChars?: number;
+    }): Promise<ResponseBodyResult>;
+    /**
+     * Get console messages captured from the page.
+     *
+     * Messages are buffered automatically. Use `level` to filter by minimum severity.
+     *
+     * @param opts - Filter options (level, clear)
+     * @returns Array of captured console messages
+     */
+    consoleLogs(opts?: {
+        level?: string;
+        clear?: boolean;
+    }): Promise<ConsoleMessage[]>;
+    /**
+     * Get uncaught errors from the page.
+     *
+     * @param opts - Options (clear: reset the error buffer after reading)
+     * @returns Array of captured page errors
+     */
+    pageErrors(opts?: {
+        clear?: boolean;
+    }): Promise<PageError[]>;
+    /**
+     * Get network requests captured from the page.
+     *
+     * @param opts - Options (filter: URL substring match, clear: reset the buffer)
+     * @returns Array of captured network requests
+     *
+     * @example
+     * ```ts
+     * const all = await page.networkRequests();
+     * const apiCalls = await page.networkRequests({ filter: '/api/' });
+     * const fresh = await page.networkRequests({ clear: true }); // read and clear
+     * ```
+     */
+    networkRequests(opts?: {
+        filter?: string;
+        clear?: boolean;
+    }): Promise<NetworkRequest[]>;
+    /**
+     * Resize the browser viewport.
+     *
+     * @param width - Viewport width in pixels
+     * @param height - Viewport height in pixels
+     */
+    resize(width: number, height: number): Promise<void>;
+    /**
+     * Get all cookies for the current browser context.
+     *
+     * @returns Array of cookie objects
+     */
+    cookies(): Promise<Awaited<ReturnType<import('playwright-core').BrowserContext['cookies']>>>;
+    /**
+     * Set a cookie in the browser context.
+     *
+     * @param cookie - Cookie data (must include `name`, `value`, and either `url` or `domain`+`path`)
+     *
+     * @example
+     * ```ts
+     * await page.setCookie({
+     *   name: 'token',
+     *   value: 'abc123',
+     *   url: 'https://example.com',
+     * });
+     * ```
+     */
+    setCookie(cookie: CookieData): Promise<void>;
+    /** Clear all cookies in the browser context. */
+    clearCookies(): Promise<void>;
+    /**
+     * Get values from localStorage or sessionStorage.
+     *
+     * @param kind - `'local'` for localStorage, `'session'` for sessionStorage
+     * @param key - Optional specific key to retrieve (returns all if omitted)
+     * @returns Key-value map of storage entries
+     */
+    storageGet(kind: StorageKind, key?: string): Promise<Record<string, string>>;
+    /**
+     * Set a value in localStorage or sessionStorage.
+     *
+     * @param kind - `'local'` for localStorage, `'session'` for sessionStorage
+     * @param key - Storage key
+     * @param value - Storage value
+     */
+    storageSet(kind: StorageKind, key: string, value: string): Promise<void>;
+    /**
+     * Clear all entries in localStorage or sessionStorage.
+     *
+     * @param kind - `'local'` for localStorage, `'session'` for sessionStorage
+     */
+    storageClear(kind: StorageKind): Promise<void>;
+    /**
+     * Click a ref and save the resulting file download.
+     *
+     * @param ref - Ref ID of the element that triggers the download
+     * @param path - Local file path to save the download to
+     * @param opts - Timeout options
+     * @returns Download result with URL, suggested filename, and saved path
+     *
+     * @example
+     * ```ts
+     * const result = await page.download('e7', '/tmp/report.pdf');
+     * console.log(result.suggestedFilename); // 'report.pdf'
+     * ```
+     */
+    download(ref: string, path: string, opts?: {
+        timeoutMs?: number;
+        allowedOutputRoots?: string[];
+    }): Promise<DownloadResult>;
+    /**
+     * Wait for the next download event (without clicking).
+     *
+     * Returns a promise — store it (don't await), trigger the download, then await it.
+     *
+     * @param opts - Options (path: save location, timeoutMs)
+     * @returns Download result with URL, suggested filename, and saved path
+     */
+    waitForDownload(opts?: {
+        path?: string;
+        timeoutMs?: number;
+        allowedOutputRoots?: string[];
+    }): Promise<DownloadResult>;
+    /**
+     * Set the browser to offline or online mode.
+     *
+     * @param offline - `true` to go offline, `false` to go online
+     */
+    setOffline(offline: boolean): Promise<void>;
+    /**
+     * Set extra HTTP headers for all requests.
+     *
+     * @param headers - Headers to add to every request
+     *
+     * @example
+     * ```ts
+     * await page.setExtraHeaders({ 'X-Custom': 'value' });
+     * ```
+     */
+    setExtraHeaders(headers: Record<string, string>): Promise<void>;
+    /**
+     * Set HTTP authentication credentials.
+     *
+     * @param opts - Credentials (username, password) or `{ clear: true }` to remove
+     */
+    setHttpCredentials(opts: HttpCredentials): Promise<void>;
+    /**
+     * Emulate a geolocation.
+     *
+     * @param opts - Geolocation coordinates or `{ clear: true }` to clear
+     *
+     * @example
+     * ```ts
+     * await page.setGeolocation({ latitude: 48.8566, longitude: 2.3522 }); // Paris
+     * await page.setGeolocation({ clear: true }); // reset
+     * ```
+     */
+    setGeolocation(opts: GeolocationOptions): Promise<void>;
+    /**
+     * Emulate a preferred color scheme.
+     *
+     * @param opts - Color scheme options
+     *
+     * @example
+     * ```ts
+     * await page.emulateMedia({ colorScheme: 'dark' });
+     * ```
+     */
+    emulateMedia(opts: {
+        colorScheme: ColorScheme;
+    }): Promise<void>;
+    /**
+     * Override the browser locale.
+     *
+     * @param locale - BCP-47 locale string (e.g. `'fr-FR'`, `'ja-JP'`)
+     */
+    setLocale(locale: string): Promise<void>;
+    /**
+     * Override the browser timezone.
+     *
+     * @param timezoneId - IANA timezone ID (e.g. `'America/New_York'`, `'Asia/Tokyo'`)
+     */
+    setTimezone(timezoneId: string): Promise<void>;
+    /**
+     * Emulate a specific device (viewport + user agent).
+     *
+     * @param name - Playwright device name (e.g. `'iPhone 13'`, `'Pixel 5'`)
+     *
+     * @example
+     * ```ts
+     * await page.setDevice('iPhone 13');
+     * ```
+     */
+    setDevice(name: string): Promise<void>;
+}
+/**
+ * Main entry point for browserclaw.
+ *
+ * Launch or connect to a browser, then open pages and automate them
+ * using the snapshot + ref pattern.
+ *
+ * @example
+ * ```ts
+ * import { BrowserClaw } from 'browserclaw';
+ *
+ * const browser = await BrowserClaw.launch({ headless: false });
+ * const page = await browser.open('https://example.com');
+ *
+ * const { snapshot, refs } = await page.snapshot();
+ * console.log(snapshot); // AI-readable page tree
+ * console.log(refs);     // { "e1": { role: "link", name: "More info" }, ... }
+ *
+ * await page.click('e1');
+ * await browser.stop();
+ * ```
+ */
+export declare class BrowserClaw {
+    private readonly cdpUrl;
+    private readonly ssrfPolicy;
+    private chrome;
+    private constructor();
+    /**
+     * Launch a new Chrome instance and connect to it.
+     *
+     * Automatically detects Chrome, Brave, Edge, or Chromium on the system.
+     * Creates a dedicated browser profile to avoid conflicts with your daily browser.
+     *
+     * @param opts - Launch options (headless, executablePath, cdpPort, etc.)
+     * @returns A connected BrowserClaw instance
+     *
+     * @example
+     * ```ts
+     * // Default: visible Chrome window
+     * const browser = await BrowserClaw.launch();
+     *
+     * // Headless mode
+     * const browser = await BrowserClaw.launch({ headless: true });
+     *
+     * // Specific browser
+     * const browser = await BrowserClaw.launch({
+     *   executablePath: '/usr/bin/google-chrome',
+     * });
+     * ```
+     */
+    static launch(opts?: LaunchOptions): Promise<BrowserClaw>;
+    /**
+     * Connect to an already-running Chrome instance via its CDP endpoint.
+     *
+     * The Chrome instance must have been started with `--remote-debugging-port`.
+     *
+     * @param cdpUrl - CDP endpoint URL (e.g. `'http://localhost:9222'`)
+     * @returns A connected BrowserClaw instance
+     *
+     * @example
+     * ```ts
+     * // Chrome started with: chrome --remote-debugging-port=9222
+     * const browser = await BrowserClaw.connect('http://localhost:9222');
+     * ```
+     */
+    static connect(cdpUrl: string, opts?: ConnectOptions): Promise<BrowserClaw>;
+    /**
+     * Open a URL in a new tab and return the page handle.
+     *
+     * @param url - URL to navigate to
+     * @returns A CrawlPage for the new tab
+     *
+     * @example
+     * ```ts
+     * const page = await browser.open('https://example.com');
+     * const { snapshot, refs } = await page.snapshot();
+     * ```
+     */
+    open(url: string): Promise<CrawlPage>;
+    /**
+     * Get a CrawlPage handle for the currently active tab.
+     *
+     * @returns CrawlPage for the first/active page
+     */
+    currentPage(): Promise<CrawlPage>;
+    /**
+     * List all open tabs.
+     *
+     * @returns Array of tab information objects
+     */
+    tabs(): Promise<BrowserTab[]>;
+    /**
+     * Bring a tab to the foreground.
+     *
+     * @param targetId - CDP target ID of the tab (from `tabs()` or `page.id`)
+     */
+    focus(targetId: string): Promise<void>;
+    /**
+     * Close a tab.
+     *
+     * @param targetId - CDP target ID of the tab to close
+     */
+    close(targetId: string): Promise<void>;
+    /**
+     * Get a CrawlPage handle for a specific tab by its target ID.
+     *
+     * Unlike `open()`, this doesn't create a new tab — it wraps an existing one.
+     *
+     * @param targetId - CDP target ID of the tab
+     * @returns CrawlPage for the specified tab
+     */
+    page(targetId: string): CrawlPage;
+    /** The CDP endpoint URL for this browser connection. */
+    get url(): string;
+    /**
+     * Stop the browser and clean up all resources.
+     *
+     * If the browser was launched by `BrowserClaw.launch()`, the Chrome process
+     * will be terminated. If connected via `BrowserClaw.connect()`, only the
+     * Playwright connection is closed.
+     */
+    stop(): Promise<void>;
+}