@browserbasehq/orca 3.0.9-alpha-3 → 3.1.0-headers

package/dist/cjs/lib/v3/understudy/consoleMessage.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsoleMessage = void 0;
+function formatRemoteObject(obj) {
+    if (!obj)
+        return "";
+    if ("value" in obj) {
+        const value = obj.value;
+        if (value === undefined)
+            return "";
+        if (typeof value === "string")
+            return value;
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    if (obj.unserializableValue)
+        return obj.unserializableValue;
+    if (obj.description)
+        return obj.description;
+    return obj.type ?? "";
+}
+class ConsoleMessage {
+    event;
+    pageRef;
+    constructor(event, pageRef) {
+        this.event = event;
+        this.pageRef = pageRef;
+    }
+    type() {
+        return this.event.type;
+    }
+    text() {
+        const args = this.args();
+        if (!args.length)
+            return "";
+        return args
+            .map((arg) => formatRemoteObject(arg))
+            .filter((chunk) => chunk.length > 0)
+            .join(" ");
+    }
+    args() {
+        return this.event.args ? [...this.event.args] : [];
+    }
+    location() {
+        const frame = this.event.stackTrace?.callFrames?.[0];
+        return {
+            url: frame?.url,
+            lineNumber: frame?.lineNumber,
+            columnNumber: frame?.columnNumber,
+        };
+    }
+    page() {
+        return this.pageRef;
+    }
+    timestamp() {
+        return this.event.timestamp;
+    }
+    raw() {
+        return this.event;
+    }
+    toString() {
+        return this.text();
+    }
+}
+exports.ConsoleMessage = ConsoleMessage;
+//# sourceMappingURL=consoleMessage.js.map

package/dist/cjs/lib/v3/understudy/consoleMessage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consoleMessage.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/consoleMessage.ts"],"names":[],"mappings":";;;AAOA,SAAS,kBAAkB,CAAC,GAA6B;IACvD,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IAEpB,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;QACnB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;QACxB,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACnC,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC5C,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,IAAI,GAAG,CAAC,mBAAmB;QAAE,OAAO,GAAG,CAAC,mBAAmB,CAAC;IAC5D,IAAI,GAAG,CAAC,WAAW;QAAE,OAAO,GAAG,CAAC,WAAW,CAAC;IAE5C,OAAO,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;AACxB,CAAC;AAED,MAAa,cAAc;IAEN;IACA;IAFnB,YACmB,KAA6C,EAC7C,OAAc;QADd,UAAK,GAAL,KAAK,CAAwC;QAC7C,YAAO,GAAP,OAAO,CAAO;IAC9B,CAAC;IAEJ,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,IAAI;QACF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,CAAC;QAC5B,OAAO,IAAI;aACR,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC;aACrC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;aACnC,IAAI,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACrD,CAAC;IAED,QAAQ;QACN,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC;QACrD,OAAO;YACL,GAAG,EAAE,KAAK,EAAE,GAAG;YACf,UAAU,EAAE,KAAK,EAAE,UAAU;YAC7B,YAAY,EAAE,KAAK,EAAE,YAAY;SAClC,CAAC;IACJ,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;IAC9B,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;CACF;AA/CD,wCA+CC","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport type { Page } from \"./page.js\";\n\ntype RemoteObject = Protocol.Runtime.RemoteObject;\n\nexport type ConsoleListener = (message: ConsoleMessage) => void;\n\nfunction formatRemoteObject(obj: RemoteObject | undefined): string {\n  if (!obj) return \"\";\n\n  if (\"value\" in obj) {\n    const value = obj.value;\n    if (value === undefined) return \"\";\n    if (typeof value === \"string\") return value;\n    try {\n      return JSON.stringify(value);\n    } catch {\n      return String(value);\n    }\n  }\n\n  if (obj.unserializableValue) return obj.unserializableValue;\n  if (obj.description) return obj.description;\n\n  return obj.type ?? \"\";\n}\n\nexport class ConsoleMessage {\n  constructor(\n    private readonly event: Protocol.Runtime.ConsoleAPICalledEvent,\n    private readonly pageRef?: Page,\n  ) {}\n\n  type(): Protocol.Runtime.ConsoleAPICalledEvent[\"type\"] {\n    return this.event.type;\n  }\n\n  text(): string {\n    const args = this.args();\n    if (!args.length) return \"\";\n    return args\n      .map((arg) => formatRemoteObject(arg))\n      .filter((chunk) => chunk.length > 0)\n      .join(\" \");\n  }\n\n  args(): RemoteObject[] {\n    return this.event.args ? [...this.event.args] : [];\n  }\n\n  location(): { url?: string; lineNumber?: number; columnNumber?: number } {\n    const frame = this.event.stackTrace?.callFrames?.[0];\n    return {\n      url: frame?.url,\n      lineNumber: frame?.lineNumber,\n      columnNumber: frame?.columnNumber,\n    };\n  }\n\n  page(): Page | undefined {\n    return this.pageRef;\n  }\n\n  timestamp(): number | undefined {\n    return this.event.timestamp;\n  }\n\n  raw(): Protocol.Runtime.ConsoleAPICalledEvent {\n    return this.event;\n  }\n\n  toString(): string {\n    return this.text();\n  }\n}\n"]}

package/dist/cjs/lib/v3/understudy/context.d.ts

@@ -0,0 +1,166 @@
+import type { Protocol } from "devtools-protocol";
+import { CdpConnection } from "./cdp.js";
+import { Page } from "./page.js";
+import type { StagehandAPIClient } from "../api.js";
+import { LocalBrowserLaunchOptions } from "../types/public/index.js";
+import { InitScriptSource } from "../types/private/index.js";
+import { Cookie, ClearCookieOptions, CookieParam } from "../types/public/context.js";
+/**
+ * V3Context
+ *
+ * Owns the root CDP connection and wires Target/Page events into Page.
+ * Maintains one Page per top-level target, adopts OOPIF child sessions into the owner Page,
+ * and tracks target→page and (root) frame→target mappings for lookups.
+ *
+ * IMPORTANT: FrameId → session ownership is managed inside Page (via its FrameRegistry).
+ * Context never “guesses” owners; it simply forwards events (with the emitting session)
+ * so Page can record the correct owner at event time.
+ */
+export declare class V3Context {
+    readonly conn: CdpConnection;
+    private readonly env;
+    private readonly apiClient;
+    private readonly localBrowserLaunchOptions;
+    private constructor();
+    private readonly _piercerInstalled;
+    private _lastPopupSignalAt;
+    private readonly _targetSessionListeners;
+    private readonly _sessionInit;
+    private pagesByTarget;
+    private mainFrameToTarget;
+    private sessionOwnerPage;
+    private frameOwnerPage;
+    private pendingOopifByMainFrame;
+    private createdAtByTarget;
+    private typeByTarget;
+    private _pageOrder;
+    private pendingCreatedTargetUrl;
+    private readonly initScripts;
+    private extraHttpHeaders;
+    private installTargetSessionListeners;
+    /**
+     * Create a Context for a given CDP websocket URL and bootstrap target wiring.
+     */
+    static create(wsUrl: string, opts?: {
+        env?: "LOCAL" | "BROWSERBASE";
+        apiClient?: StagehandAPIClient | null;
+        localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null;
+        cdpHeaders?: Record<string, string>;
+    }): Promise<V3Context>;
+    private hasTopLevelPage;
+    private ensureFirstTopLevelPage;
+    /**
+     * Wait until at least one top-level Page has been created and registered.
+     * We poll internal maps that bootstrap/onAttachedToTarget populate.
+     */
+    private waitForFirstTopLevelPage;
+    private waitForInitialTopLevelTargets;
+    private ensurePiercer;
+    /** Mark a page target as the most-recent one (active). */
+    private _pushActive;
+    /** Remove a page target from the recency list (used on close). */
+    private _removeFromOrder;
+    /** Return the current active Page (most-recent page that still exists). */
+    activePage(): Page | undefined;
+    /** Explicitly mark a known Page as the most-recent active page (and focus it). */
+    setActivePage(page: Page): void;
+    addInitScript<Arg>(script: InitScriptSource<Arg>, arg?: Arg): Promise<void>;
+    setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
+    /**
+     * Return top-level `Page`s (oldest → newest). OOPIF targets are not included.
+     */
+    pages(): Page[];
+    private applyInitScriptsToPage;
+    /**
+     * Resolve an owning `Page` by the **top-level main frame id**.
+     * Note: child (OOPIF) roots are intentionally not present in this mapping.
+     */
+    resolvePageByMainFrameId(frameId: string): Page | undefined;
+    /**
+     * Serialize the full frame tree for a given top-level main frame id.
+     */
+    getFullFrameTreeByMainFrameId(rootMainFrameId: string): Promise<Protocol.Page.FrameTree>;
+    /**
+     * Create a new top-level page (tab) with the given URL and return its Page object.
+     * Waits until the target is attached and registered.
+     */
+    newPage(url?: string): Promise<Page>;
+    /**
+     * Close CDP and clear all mappings. Best-effort cleanup.
+     */
+    close(): Promise<void>;
+    /**
+     * Bootstrap target lifecycle:
+     * - Attach to existing targets.
+     * - Handle auto-attach events.
+     * - Clean up on detach/destroy.
+     */
+    private bootstrap;
+    /**
+     * Handle a newly attached target (top-level or potential OOPIF):
+     * - Enable Page domain and lifecycle events.
+     * - If top-level → create Page, wire listeners, resume.
+     * - Else → probe child root frame id via `Page.getFrameTree` and adopt immediately
+     *   if the parent is known; otherwise stage until parent `frameAttached`.
+     * - Resume the target only after listeners are wired.
+     */
+    private onAttachedToTarget;
+    /**
+     * Detach handler:
+     * - Remove child session ownership and prune its subtree.
+     * - If a top-level target, cleanup its `Page` and mappings.
+     * - Drop any staged child for this session.
+     */
+    private onDetachedFromTarget;
+    /**
+     * Cleanup a top-level Page by target id, removing its root and staged children.
+     */
+    private cleanupByTarget;
+    /**
+     * Wire Page-domain frame events for a session into the owning Page & mappings.
+     * We forward the *emitting session* with every event so Page can stamp ownership precisely.
+     */
+    private installFrameEventBridges;
+    /**
+     * Register that a session belongs to a Page (used by event routing).
+     */
+    private wireSessionToOwnerPage;
+    /**
+     * Utility: reverse-lookup the top-level target id that owns a given Page.
+     */
+    private findTargetIdByPage;
+    private _notePopupSignal;
+    /**
+     * Await the current active page, waiting briefly if a popup/open was just triggered.
+     * Normal path returns immediately; popup path waits up to timeoutMs for the new page.
+     */
+    awaitActivePage(timeoutMs?: number): Promise<Page>;
+    /**
+     * Get all browser cookies, optionally filtered by URL(s).
+     *
+     * When `urls` is omitted or empty every cookie in the browser context is
+     * returned. When one or more URLs are supplied only cookies whose
+     * domain/path/secure attributes match are included.
+     */
+    cookies(urls?: string | string[]): Promise<Cookie[]>;
+    /**
+     * Add one or more cookies to the browser context.
+     *
+     * Each cookie must specify either a `url` (from which domain/path/secure are
+     * derived) or an explicit `domain` + `path` pair.
+     *
+     * We surface CDP errors if the browser rejects a cookie.
+     */
+    addCookies(cookies: CookieParam[]): Promise<void>;
+    /**
+     * Clear cookies from the browser context.
+     *
+     * - Called with no arguments: clears **all** cookies atomically via
+     *   `Storage.clearCookies`.
+     * - Called with filter options: fetches all cookies, clears everything,
+     *   then re-adds only the cookies that do NOT match the filter via
+     *   `Storage.setCookies`. This is necessary on the browser endpoint because
+     *   the Storage domain does not support targeted deletes.
+     */
+    clearCookies(options?: ClearCookieOptions): Promise<void>;
+}