open-browser-use-sdk 0.1.23

package/README.md

@@ -0,0 +1,228 @@
+# Open Browser Use JavaScript SDK
+
+JavaScript/TypeScript client for controlling a real Chrome profile through
+Open Browser Use. The SDK keeps the low-level JSON-RPC/CDP surface available and
+also provides higher-level browser/tab helpers for common agent workflows.
+
+## Prerequisites
+
+- The `open-browser-use` CLI and Chrome extension are installed and connected.
+- `open-browser-use ping` returns `"pong"`.
+- The native host has written an active socket registry at
+  `/tmp/open-browser-use/active.json`.
+
+```sh
+open-browser-use ping
+open-browser-use info
+```
+
+## Installation
+
+```sh
+npm install open-browser-use-sdk
+```
+
+## High-Level Browser API
+
+Use `connectOpenBrowserUse` when you want a Playwright-like flow in a normal
+Node runtime.
+
+```js
+import { readFile } from "node:fs/promises";
+import { connectOpenBrowserUse } from "open-browser-use-sdk";
+
+const registry = JSON.parse(
+  await readFile("/tmp/open-browser-use/active.json", "utf8")
+);
+
+const browser = await connectOpenBrowserUse({
+  socketPath: registry.socketPath,
+  sessionId: "github-issue-scan",
+  turnId: `turn-${Date.now()}`,
+  timeoutMs: 20000,
+});
+
+let tab;
+
+try {
+  await browser.client.nameSession("GitHub issue scan - OBU");
+
+  tab = await browser.newTab();
+
+  await tab.goto("https://github.com/iFurySt/open-codex-computer-use/issues", {
+    waitUntil: "domcontentloaded",
+    timeoutMs: 15000,
+  });
+
+  await tab.playwright.waitForLoadState({
+    state: "domcontentloaded",
+    timeoutMs: 15000,
+  });
+
+  const snapshot = await tab.playwright.domSnapshot();
+  const relevant = snapshot
+    .split("\n")
+    .filter((line) =>
+      /Open|Closed|Issues|issue|No results|open-codex-computer-use|Pull requests|Starred/.test(line)
+    );
+
+  console.log(relevant.slice(0, 160).join("\n"));
+} finally {
+  await browser.client.finalizeTabs([]);
+  browser.close();
+}
+```
+
+The same tab helpers are available without the `playwright` alias:
+
+```js
+await tab.goto(url, { waitUntil: "load", timeoutMs: 15000 });
+await tab.waitForLoadState({ state: "domcontentloaded", timeoutMs: 15000 });
+const text = await tab.domSnapshot();
+const value = await tab.evaluate("document.title");
+```
+
+## Multi-Tab Workflows
+
+For multiple pages, create tabs first, then run navigation and extraction in
+parallel. This avoids backend session races while still parallelizing the slow
+page work.
+
+```js
+const targets = [
+  ["repo", "https://github.com/iFurySt/open-codex-computer-use"],
+  ["issues", "https://github.com/iFurySt/open-codex-computer-use/issues"],
+  ["pulls", "https://github.com/iFurySt/open-codex-computer-use/pulls"],
+];
+
+const tabs = [];
+for (const [kind] of targets) {
+  tabs.push([kind, await browser.newTab()]);
+}
+
+await Promise.all(
+  targets.map(([_, url], index) =>
+    tabs[index][1].goto(url, { waitUntil: "load", timeoutMs: 25000 })
+  )
+);
+
+const results = await Promise.all(
+  tabs.map(async ([kind, tab]) => ({
+    kind,
+    tabId: tab.id,
+    text: await tab.playwright.domSnapshot(),
+  }))
+);
+```
+
+## Low-Level Client API
+
+Use `OpenBrowserUseClient` when you need direct Browser Use JSON-RPC methods or
+raw CDP commands.
+
+```js
+import { readFile } from "node:fs/promises";
+import { OpenBrowserUseClient } from "open-browser-use-sdk";
+
+const { socketPath } = JSON.parse(
+  await readFile("/tmp/open-browser-use/active.json", "utf8")
+);
+
+const client = new OpenBrowserUseClient({
+  socketPath,
+  sessionId: "raw-cdp-example",
+});
+
+try {
+  await client.connect();
+  await client.nameSession("Raw CDP example - OBU");
+
+  const tab = await client.createTab();
+  await client.attach(tab.id);
+  await client.executeCdp(tab.id, "Page.navigate", {
+    url: "https://example.com",
+  });
+
+  const title = await client.executeCdp(tab.id, "Runtime.evaluate", {
+    expression: "document.title",
+    returnByValue: true,
+  });
+
+  console.log(title.result.value);
+} finally {
+  await client.finalizeTabs([]);
+  client.close();
+}
+```
+
+The unrestricted escape hatch is `request(method, params)`:
+
+```js
+await client.request("executeCdp", {
+  target: { tabId: 123 },
+  method: "Runtime.evaluate",
+  commandParams: {
+    expression: "document.body.innerText",
+    returnByValue: true,
+  },
+});
+```
+
+## Notifications
+
+The JS SDK can subscribe to JSON-RPC notifications from the native socket. This
+is useful for downloads and CDP events.
+
+```js
+const unsubscribe = client.onNotification((event) => {
+  if (event.method === "onDownloadChange") {
+    console.log("download", event.params);
+  }
+  if (event.method === "onCDPEvent") {
+    console.log("cdp", event.params);
+  }
+});
+
+// Later:
+unsubscribe();
+```
+
+## Common Methods
+
+- Browser/session: `getInfo`, `nameSession`, `turnEnded`
+- Tabs: `createTab`, `getTabs`, `getUserTabs`, `claimUserTab`, `finalizeTabs`
+- CDP: `attach`, `detach`, `executeCdp`, `request`
+- Input: `moveMouse`
+- File chooser: `waitForFileChooser`, `setFileChooserFiles`
+- Downloads: `waitForDownload`, `downloadPath`
+- Clipboard: `readClipboardText`, `writeClipboardText`, `readClipboard`,
+  `writeClipboard`
+
+## Cleanup
+
+Always finish browser work by finalizing tabs and closing the socket:
+
+```js
+try {
+  // Browser work here.
+} finally {
+  await browser.client.finalizeTabs([]);
+  browser.close();
+}
+```
+
+Use `finalizeTabs([])` unless the user explicitly needs a tab left open. To keep
+a tab, pass a keep item such as:
+
+```js
+await browser.client.finalizeTabs([{ tabId: tab.id, status: "handoff" }]);
+```
+
+## Notes
+
+- The browser is the user's real Chrome profile. Do not inspect unrelated data.
+- The SDK does not include Codex-specific site policy or approval prompts; add
+  policy in your own runtime if needed.
+- If connection fails, run `open-browser-use ping` and `open-browser-use info`.
+- If there is no active socket, open Chrome with the extension enabled or rerun
+  setup according to the Open Browser Use installation guide.

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type BrowserUseRequestParams = {
+    [key: string]: JsonValue;
+};
+export type OpenBrowserUseClientOptions = {
+    socketPath: string;
+    sessionId?: string;
+    turnId?: string;
+    timeoutMs?: number;
+};
+export type OpenBrowserUseNotification = {
+    method: string;
+    params?: JsonValue;
+};
+export type NotificationHandler = (notification: OpenBrowserUseNotification) => void;
+export type OpenBrowserUseLoadState = "domcontentloaded" | "load";
+export type OpenBrowserUseGotoOptions = {
+    waitUntil?: OpenBrowserUseLoadState;
+    timeoutMs?: number;
+};
+export type OpenBrowserUseWaitForLoadStateOptions = {
+    state?: OpenBrowserUseLoadState;
+    timeoutMs?: number;
+};
+export type OpenBrowserUseBrowserOptions = OpenBrowserUseClientOptions | {
+    client: OpenBrowserUseClient;
+};
+export declare class OpenBrowserUseClient {
+    #private;
+    readonly socketPath: string;
+    readonly sessionId: string;
+    readonly turnId: string;
+    readonly timeoutMs: number;
+    constructor(options: OpenBrowserUseClientOptions);
+    connect(): Promise<this>;
+    close(): void;
+    onNotification(handler: NotificationHandler): () => void;
+    request(method: string, params?: BrowserUseRequestParams): Promise<JsonValue>;
+    getInfo(): Promise<JsonValue>;
+    createTab(): Promise<JsonValue>;
+    getTabs(): Promise<JsonValue>;
+    getUserTabs(): Promise<JsonValue>;
+    getUserHistory(params?: BrowserUseRequestParams): Promise<JsonValue>;
+    claimUserTab(tabId: number): Promise<JsonValue>;
+    finalizeTabs(keep: JsonValue[]): Promise<JsonValue>;
+    nameSession(name: string): Promise<JsonValue>;
+    attach(tabId: number): Promise<JsonValue>;
+    detach(tabId: number): Promise<JsonValue>;
+    executeCdp(tabId: number, method: string, commandParams?: BrowserUseRequestParams): Promise<JsonValue>;
+    moveMouse(tabId: number, x: number, y: number, waitForArrival?: boolean): Promise<JsonValue>;
+    waitForFileChooser(tabId: number, timeoutMs?: number): Promise<JsonValue>;
+    setFileChooserFiles(fileChooserId: string, files: string[]): Promise<JsonValue>;
+    waitForDownload(tabId: number, timeoutMs?: number): Promise<JsonValue>;
+    downloadPath(downloadId: string, timeoutMs?: number): Promise<JsonValue>;
+    browserUserHistory(params?: BrowserUseRequestParams): Promise<JsonValue>;
+    readClipboardText(tabId: number): Promise<JsonValue>;
+    writeClipboardText(tabId: number, text: string): Promise<JsonValue>;
+    readClipboard(tabId: number): Promise<JsonValue>;
+    writeClipboard(tabId: number, items: JsonValue[]): Promise<JsonValue>;
+    turnEnded(): Promise<JsonValue>;
+}
+export declare function connectOpenBrowserUse(options: OpenBrowserUseBrowserOptions): Promise<OpenBrowserUseBrowser>;
+export declare class OpenBrowserUseBrowser {
+    readonly client: OpenBrowserUseClient;
+    readonly cdp: OpenBrowserUseCdp;
+    constructor(options: OpenBrowserUseBrowserOptions);
+    connect(): Promise<this>;
+    close(): void;
+    newTab(options?: OpenBrowserUseGotoOptions & {
+        url?: string;
+    }): Promise<OpenBrowserUseTab>;
+    tab(tabId: number): OpenBrowserUseTab;
+    getTabs(): Promise<JsonValue>;
+}
+export declare class OpenBrowserUseTab {
+    readonly browser: OpenBrowserUseBrowser;
+    readonly id: number;
+    readonly playwright: OpenBrowserUseTabPlaywright;
+    constructor(browser: OpenBrowserUseBrowser, id: number);
+    goto(url: string, options?: OpenBrowserUseGotoOptions): Promise<JsonValue>;
+    waitForLoadState(options?: OpenBrowserUseWaitForLoadStateOptions): Promise<void>;
+    domSnapshot(): Promise<string>;
+    evaluate(expression: string, options?: {
+        awaitPromise?: boolean;
+    }): Promise<JsonValue>;
+    close(): Promise<JsonValue>;
+}
+export declare class OpenBrowserUseTabPlaywright {
+    readonly tab: OpenBrowserUseTab;
+    constructor(tab: OpenBrowserUseTab);
+    waitForLoadState(options?: OpenBrowserUseWaitForLoadStateOptions): Promise<void>;
+    domSnapshot(): Promise<string>;
+}
+export declare class OpenBrowserUseCdp {
+    #private;
+    readonly client: OpenBrowserUseClient;
+    constructor(client: OpenBrowserUseClient);
+    call(tabId: number, method: string, commandParams?: BrowserUseRequestParams, options?: {
+        timeoutMs?: number;
+    }): Promise<JsonValue>;
+    evaluate(tabId: number, expression: string, options?: {
+        awaitPromise?: boolean;
+    }): Promise<JsonValue>;
+    navigate(tabId: number, url: string, options?: OpenBrowserUseGotoOptions): Promise<JsonValue>;
+    waitForLoadState(tabId: number, options?: OpenBrowserUseWaitForLoadStateOptions): Promise<void>;
+    readDocumentState(tabId: number): Promise<{
+        href?: string;
+        readyState?: string;
+    } | undefined>;
+    waitForEvent(tabId: number, predicate: (notification: OpenBrowserUseNotification) => boolean, options?: {
+        timeoutMs?: number;
+        timeoutMessage?: string;
+    }): Promise<OpenBrowserUseNotification>;
+    waitForLoadEvent(tabId: number, state: OpenBrowserUseLoadState, timeoutMs: number): Promise<void>;
+    ensureAttached(tabId: number): Promise<void>;
+}
+export declare function encodeFrame(value: JsonValue | Record<string, unknown>): Buffer;

package/dist/index.js

@@ -0,0 +1,463 @@
+import { createConnection } from "node:net";
+import { endianness } from "node:os";
+const headerBytes = 4;
+const defaultNavigationTimeoutMs = 10_000;
+export class OpenBrowserUseClient {
+    socketPath;
+    sessionId;
+    turnId;
+    timeoutMs;
+    #socket = null;
+    #pendingData = Buffer.alloc(0);
+    #nextId = 1;
+    #pending = new Map();
+    #notificationHandlers = new Set();
+    constructor(options) {
+        this.socketPath = options.socketPath;
+        this.sessionId = options.sessionId ?? "open-browser-use-js";
+        this.turnId = options.turnId ?? `turn-${Date.now()}`;
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+    }
+    async connect() {
+        if (this.#socket) {
+            return this;
+        }
+        const socket = createConnection(this.socketPath);
+        this.#socket = socket;
+        socket.on("data", (chunk) => this.#handleData(Buffer.from(chunk)));
+        socket.on("close", () => this.#rejectAll(new Error("Open Browser Use socket closed")));
+        socket.on("error", (error) => this.#rejectAll(error));
+        await new Promise((resolve, reject) => {
+            socket.once("connect", resolve);
+            socket.once("error", reject);
+        });
+        return this;
+    }
+    close() {
+        this.#socket?.end();
+        this.#socket = null;
+    }
+    onNotification(handler) {
+        this.#notificationHandlers.add(handler);
+        return () => {
+            this.#notificationHandlers.delete(handler);
+        };
+    }
+    async request(method, params = {}) {
+        await this.connect();
+        const socket = this.#socket;
+        if (!socket) {
+            throw new Error("Open Browser Use socket is not connected");
+        }
+        const id = String(this.#nextId++);
+        const mergedParams = {
+            session_id: this.sessionId,
+            turn_id: this.turnId,
+            ...params
+        };
+        const message = {
+            jsonrpc: "2.0",
+            id,
+            method,
+            params: mergedParams
+        };
+        const payload = encodeFrame(message);
+        const promise = new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new Error(`Open Browser Use request timed out: ${method}`));
+            }, this.timeoutMs);
+            this.#pending.set(id, { resolve, reject, timeout });
+        });
+        socket.write(payload);
+        return await promise;
+    }
+    getInfo() {
+        return this.request("getInfo");
+    }
+    createTab() {
+        return this.request("createTab");
+    }
+    getTabs() {
+        return this.request("getTabs");
+    }
+    getUserTabs() {
+        return this.request("getUserTabs");
+    }
+    getUserHistory(params = {}) {
+        return this.request("getUserHistory", params);
+    }
+    claimUserTab(tabId) {
+        return this.request("claimUserTab", { tabId });
+    }
+    finalizeTabs(keep) {
+        return this.request("finalizeTabs", { keep });
+    }
+    nameSession(name) {
+        return this.request("nameSession", { name });
+    }
+    attach(tabId) {
+        return this.request("attach", { tabId });
+    }
+    detach(tabId) {
+        return this.request("detach", { tabId });
+    }
+    executeCdp(tabId, method, commandParams = {}) {
+        return this.request("executeCdp", {
+            target: { tabId },
+            method,
+            commandParams
+        });
+    }
+    moveMouse(tabId, x, y, waitForArrival = true) {
+        return this.request("moveMouse", { tabId, x, y, waitForArrival });
+    }
+    waitForFileChooser(tabId, timeoutMs) {
+        return this.request("waitForFileChooser", {
+            tabId,
+            ...(timeoutMs === undefined ? {} : { timeoutMs })
+        });
+    }
+    setFileChooserFiles(fileChooserId, files) {
+        return this.request("setFileChooserFiles", { fileChooserId, files });
+    }
+    waitForDownload(tabId, timeoutMs) {
+        return this.request("waitForDownload", {
+            tabId,
+            ...(timeoutMs === undefined ? {} : { timeoutMs })
+        });
+    }
+    downloadPath(downloadId, timeoutMs) {
+        return this.request("downloadPath", {
+            downloadId,
+            ...(timeoutMs === undefined ? {} : { timeoutMs })
+        });
+    }
+    browserUserHistory(params = {}) {
+        return this.getUserHistory(params);
+    }
+    readClipboardText(tabId) {
+        return this.request("readClipboardText", { tabId });
+    }
+    writeClipboardText(tabId, text) {
+        return this.request("writeClipboardText", { tabId, text });
+    }
+    readClipboard(tabId) {
+        return this.request("readClipboard", { tabId });
+    }
+    writeClipboard(tabId, items) {
+        return this.request("writeClipboard", { tabId, items });
+    }
+    turnEnded() {
+        return this.request("turnEnded");
+    }
+    #handleData(chunk) {
+        this.#pendingData = Buffer.concat([this.#pendingData, chunk]);
+        while (this.#pendingData.length >= headerBytes) {
+            const length = endianness() === "LE"
+                ? this.#pendingData.readUInt32LE(0)
+                : this.#pendingData.readUInt32BE(0);
+            const total = headerBytes + length;
+            if (this.#pendingData.length < total) {
+                return;
+            }
+            const payload = this.#pendingData.subarray(headerBytes, total);
+            this.#pendingData = this.#pendingData.subarray(total);
+            this.#handleMessage(JSON.parse(payload.toString("utf8")));
+        }
+    }
+    #handleMessage(message) {
+        if (!isObject(message)) {
+            return;
+        }
+        const id = typeof message.id === "string" || typeof message.id === "number" ? String(message.id) : null;
+        if (!id && typeof message.method === "string") {
+            const notification = {
+                method: message.method,
+                params: message.params
+            };
+            for (const handler of this.#notificationHandlers) {
+                handler(notification);
+            }
+            return;
+        }
+        if (!id) {
+            return;
+        }
+        const pending = this.#pending.get(id);
+        if (!pending) {
+            return;
+        }
+        this.#pending.delete(id);
+        clearTimeout(pending.timeout);
+        if (isObject(message.error)) {
+            pending.reject(new Error(String(message.error.message ?? "Open Browser Use request failed")));
+            return;
+        }
+        pending.resolve((message.result ?? null));
+    }
+    #rejectAll(error) {
+        for (const [id, pending] of this.#pending) {
+            this.#pending.delete(id);
+            clearTimeout(pending.timeout);
+            pending.reject(error);
+        }
+    }
+}
+export async function connectOpenBrowserUse(options) {
+    const browser = new OpenBrowserUseBrowser(options);
+    await browser.connect();
+    return browser;
+}
+export class OpenBrowserUseBrowser {
+    client;
+    cdp;
+    constructor(options) {
+        this.client = "client" in options ? options.client : new OpenBrowserUseClient(options);
+        this.cdp = new OpenBrowserUseCdp(this.client);
+    }
+    async connect() {
+        await this.client.connect();
+        return this;
+    }
+    close() {
+        this.client.close();
+    }
+    async newTab(options = {}) {
+        const created = await this.client.createTab();
+        const tabId = tabIdFromValue(created, "createTab response");
+        const tab = this.tab(tabId);
+        if (options.url) {
+            await tab.goto(options.url, options);
+        }
+        return tab;
+    }
+    tab(tabId) {
+        return new OpenBrowserUseTab(this, tabId);
+    }
+    getTabs() {
+        return this.client.getTabs();
+    }
+}
+export class OpenBrowserUseTab {
+    browser;
+    id;
+    playwright;
+    constructor(browser, id) {
+        this.browser = browser;
+        this.id = id;
+        this.playwright = new OpenBrowserUseTabPlaywright(this);
+    }
+    goto(url, options = {}) {
+        return this.browser.cdp.navigate(this.id, url, options);
+    }
+    waitForLoadState(options = {}) {
+        return this.browser.cdp.waitForLoadState(this.id, options);
+    }
+    domSnapshot() {
+        return this.browser.cdp.evaluate(this.id, "document.body?.innerText ?? ''").then((value) => String(value ?? ""));
+    }
+    evaluate(expression, options = {}) {
+        return this.browser.cdp.evaluate(this.id, expression, options);
+    }
+    close() {
+        return this.browser.cdp.call(this.id, "Page.close");
+    }
+}
+export class OpenBrowserUseTabPlaywright {
+    tab;
+    constructor(tab) {
+        this.tab = tab;
+    }
+    waitForLoadState(options = {}) {
+        return this.tab.waitForLoadState(options);
+    }
+    domSnapshot() {
+        return this.tab.domSnapshot();
+    }
+}
+export class OpenBrowserUseCdp {
+    client;
+    #attachedTabIds = new Set();
+    constructor(client) {
+        this.client = client;
+    }
+    async call(tabId, method, commandParams = {}, options = {}) {
+        await this.ensureAttached(tabId);
+        return this.client.request("executeCdp", {
+            target: { tabId },
+            method,
+            commandParams,
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs })
+        });
+    }
+    async evaluate(tabId, expression, options = {}) {
+        const result = await this.call(tabId, "Runtime.evaluate", {
+            expression,
+            returnByValue: true,
+            ...(options.awaitPromise === undefined ? {} : { awaitPromise: options.awaitPromise })
+        });
+        if (isObject(result) && isObject(result.exceptionDetails)) {
+            throw new Error(String(result.exceptionDetails.text ?? "Open Browser Use evaluation failed"));
+        }
+        return isObject(result) && isObject(result.result) ? (result.result.value ?? null) : null;
+    }
+    async navigate(tabId, url, options = {}) {
+        if (!url) {
+            throw new Error("goto requires a URL");
+        }
+        const waitUntil = options.waitUntil ?? "load";
+        assertSupportedLoadState(waitUntil);
+        const timeoutMs = options.timeoutMs ?? defaultNavigationTimeoutMs;
+        await this.call(tabId, "Page.enable");
+        const wait = this.waitForLoadEvent(tabId, waitUntil, timeoutMs);
+        const result = await this.call(tabId, "Page.navigate", { url }, { timeoutMs });
+        if (isObject(result) && typeof result.errorText === "string" && result.errorText) {
+            throw new Error(`Browser failed to navigate tab ${tabId}: ${result.errorText}`);
+        }
+        await wait.catch(async (error) => {
+            const state = await this.readDocumentState(tabId);
+            if (documentStateMatches(state, waitUntil)) {
+                return;
+            }
+            throw error;
+        });
+        return result;
+    }
+    async waitForLoadState(tabId, options = {}) {
+        const state = options.state ?? "load";
+        assertSupportedLoadState(state);
+        await this.call(tabId, "Page.enable");
+        const documentState = await this.readDocumentState(tabId);
+        if (documentStateMatches(documentState, state)) {
+            return;
+        }
+        await this.waitForLoadEvent(tabId, state, options.timeoutMs ?? defaultNavigationTimeoutMs);
+    }
+    async readDocumentState(tabId) {
+        try {
+            const value = await this.evaluate(tabId, "({ href: window.location.href, readyState: document.readyState })");
+            return isObject(value) ? { href: stringValue(value.href), readyState: stringValue(value.readyState) } : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    waitForEvent(tabId, predicate, options = {}) {
+        const timeoutMs = options.timeoutMs ?? defaultNavigationTimeoutMs;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let removeHandler = null;
+            let timer;
+            const finish = () => {
+                if (settled) {
+                    return false;
+                }
+                settled = true;
+                clearTimeout(timer);
+                removeHandler?.();
+                return true;
+            };
+            timer = setTimeout(() => {
+                if (finish()) {
+                    reject(new Error(options.timeoutMessage ?? `Timed out waiting for tab ${tabId} event`));
+                }
+            }, timeoutMs);
+            removeHandler = this.client.onNotification((notification) => {
+                try {
+                    if (predicate(notification)) {
+                        if (finish()) {
+                            resolve(notification);
+                        }
+                    }
+                }
+                catch (error) {
+                    if (finish()) {
+                        reject(error instanceof Error ? error : new Error(String(error)));
+                    }
+                }
+            });
+        });
+    }
+    waitForLoadEvent(tabId, state, timeoutMs) {
+        return this.waitForEvent(tabId, (notification) => {
+            const event = cdpEventForTab(notification, tabId);
+            if (!event) {
+                return false;
+            }
+            if (event.method === "Page.navigationBlocked") {
+                throw new Error(`Navigation was blocked in tab ${tabId}`);
+            }
+            return state === "domcontentloaded"
+                ? event.method === "Page.domContentEventFired"
+                : event.method === "Page.loadEventFired";
+        }, {
+            timeoutMs,
+            timeoutMessage: `Timed out waiting for ${state} in tab ${tabId}`
+        }).then(() => undefined);
+    }
+    async ensureAttached(tabId) {
+        if (this.#attachedTabIds.has(tabId)) {
+            return;
+        }
+        await this.client.attach(tabId);
+        this.#attachedTabIds.add(tabId);
+    }
+}
+export function encodeFrame(value) {
+    const payload = Buffer.from(JSON.stringify(value), "utf8");
+    const frame = Buffer.alloc(headerBytes + payload.length);
+    if (endianness() === "LE") {
+        frame.writeUInt32LE(payload.length, 0);
+    }
+    else {
+        frame.writeUInt32BE(payload.length, 0);
+    }
+    payload.copy(frame, headerBytes);
+    return frame;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function tabIdFromValue(value, label) {
+    if (!isObject(value)) {
+        throw new Error(`${label} did not include a tab object`);
+    }
+    const id = value.id;
+    if (typeof id === "number" && Number.isInteger(id) && id > 0) {
+        return id;
+    }
+    if (typeof id === "string") {
+        const parsed = Number(id);
+        if (Number.isInteger(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    throw new Error(`${label} did not include a numeric tab id`);
+}
+function assertSupportedLoadState(state) {
+    if (state !== "domcontentloaded" && state !== "load") {
+        throw new Error(`Unsupported load state "${state}". Use "domcontentloaded" or "load".`);
+    }
+}
+function documentStateMatches(documentState, state) {
+    if (documentState?.readyState === "complete") {
+        return true;
+    }
+    return state === "domcontentloaded" && documentState?.readyState === "interactive";
+}
+function cdpEventForTab(notification, tabId) {
+    if (notification.method !== "onCDPEvent" || !isObject(notification.params)) {
+        return null;
+    }
+    const source = notification.params.source;
+    if (!isObject(source) || source.tabId !== tabId) {
+        return null;
+    }
+    return {
+        method: stringValue(notification.params.method)
+    };
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "open-browser-use-sdk",
+  "version": "0.1.23",
+  "description": "JavaScript/TypeScript SDK for Open Browser Use.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "pnpm build && node --test test/*.test.mjs"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iFurySt/open-codex-browser-use.git",
+    "directory": "packages/open-browser-use-js"
+  },
+  "bugs": {
+    "url": "https://github.com/iFurySt/open-codex-browser-use/issues"
+  },
+  "homepage": "https://github.com/iFurySt/open-codex-browser-use/tree/main/packages/open-browser-use-js#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}