JavaScript SDK

The SDK is one module, sdk/index.ts, built to dist/sdk.mjs by pnpm run build. It is an ESM module for Node.js 24 and later. It reads config.json from the configuration directory and sends actions to POST /command.

connect returns a task object bound to one session name. The extension opens that session's tabs and tab group on demand, as it does for omw call.

import { connect } from "./dist/sdk.mjs";

const task = await connect("research");
await task.navigate("https://example.com/");
const page = await task.evaluate("({title:document.title,url:location.href})");
console.log(page.title);
await task.close();

connect(session, options)Copy Anchor Link

const task = await connect("research", { browser: "firefox" });

connect rejects when:

• config.json is missing or unreadable. Run omw start first; it creates the file.
• address in the file is not 127.0.0.1:17373; the message is unsupported daemon address.
• browser is another string; the message is unsupported browser: safari.

The returned object has session, browser (undefined when no browser was given), and the methods below.

Task methodsCopy Anchor Link

evaluate runs a JavaScript expression in the page. Wrap asynchronous code in an IIFE:

const count = await task.evaluate("(async () => (await fetch('/api/count')).text())()");

const links = await task.evaluate("document.querySelectorAll('a').length");

Selectors accept the forms listed in the action reference, including CSS, @e references from a snapshot, role=, text= and xpath=.

call(action, args, options)Copy Anchor Link

const result = await task.call(
  "get",
  { selector: "#price", property: "text" },
  { timeoutMs: 5000 },
);

The request is aborted locally 5 seconds after the daemon deadline. That gives the daemon time to answer with outcome_unknown when the page did not finish. A request aborted through signal rejects with an AbortError; a request aborted by the internal timeout rejects with a TimeoutError.

const controller = new AbortController();
setTimeout(() => controller.abort(), 2000);
try {
  await task.call("wait", { selector: "#done", state: "visible" }, { signal: controller.signal });
} catch (error) {
  console.log(error.name);
}

ErrorsCopy Anchor Link

A rejected call is an Error with a code property. When the daemon answers with a command error, code and message are the daemon's error.code and error.message.

try {
  await task.click("@e12");
} catch (error) {
  if (error.code === "stale_ref") {
    await task.snapshot();
  } else {
    throw error;
  }
}

The request never reached the command handler when the reply has no JSON content type. Causes: a rejected token, a non-loopback Host, a web Origin, or another service on port 17373.

An aborted request rejects with an AbortError, or a TimeoutError after the internal timeout, and no daemon fault code. A refused connection rejects with the fetch TypeError.

The full list of codes and recovery steps is in the action reference.

Parallel tasksCopy Anchor Link

Each session owns its tabs. Give every task its own session name, then start them together with Promise.all. The daemon runs the commands concurrently, up to 128 in flight per browser.

import { connect } from "./dist/sdk.mjs";

const tasks = [
  { session: "chrome-docs", url: "https://developer.chrome.com/docs/extensions/" },
  { session: "go-docs", url: "https://go.dev/doc/" },
];

const results = await Promise.all(
  tasks.map(async ({ session, url }) => {
    const task = await connect(session);
    try {
      await task.navigate(url);
      const page = await task.evaluate("({title:document.title,url:location.href})");
      return { session, ...page };
    } finally {
      await task.close();
    }
  }),
);

console.log(JSON.stringify(results, null, 2));

[
  {
    "session": "chrome-docs",
    "title": "Chrome Extensions documentation",
    "url": "https://developer.chrome.com/docs/extensions/"
  },
  {
    "session": "go-docs",
    "title": "The Go Programming Language",
    "url": "https://go.dev/doc/"
  }
]

Two tasks with the same session name share their tabs and CDP state, so give independent work distinct names.

Closing a task closes the tabs the session opened, releases borrowed tabs and deletes the session binding. When close is not called, the tabs stay open and the binding is kept, so a later connect with the same name resumes the session.

TypesCopy Anchor Link

sdk/index.ts imports Args, Browser, Json and Fault from the extension protocol. call accepts a type parameter for the result:

const box = await task.call<{ x: number; y: number }>("get", {
  selector: "#cart",
  property: "box",
});