plyxen

Small, dependency-light helpers for driving a Chromium-based browser over the Chrome DevTools Protocol. Two independent pieces:

• plyxen — page/session helpers: list pages, connect, run a function against a page or the browser endpoint, and an optional Session that remembers the current page and can start the browser on demand.
• plyxen/netlog — a background network recorder that writes JSON Lines and redacts sensitive headers/fields by default.

Built on chrome-remote-interface.

Install

npm install plyxen

Start a browser with remote debugging enabled, for example:

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/cdp-profile about:blank

Sessions

import { listPages, withPage, Session } from "plyxen";

// Stateless helpers (default endpoint 127.0.0.1:9222)
const pages = await listPages();
await withPage(pages[0].id, async (client) => {
  await client.Page.enable();
  await client.Page.navigate({ url: "https://example.com" });
});

// A Session remembers the current page and can launch on demand
const session = new Session({
  endpoint: { port: 9222 },
  onLaunch: () => {
    // start your browser here (spawn the binary with --remote-debugging-port)
  },
});

await session.withPage(undefined, async (client, pageId) => {
  const title = (await client.Runtime.evaluate({ expression: "document.title" })).result?.value;
  return title;
});

API

• listPages(endpoint?), listTargets(endpoint?), version(endpoint?)
• isReachable(endpoint?), hasOpenPage(endpoint?)
• connectPage(id, endpoint?) — you close it
• withPage(id, fn, { endpoint?, autoDismissDialogs? }) — auto-closes; dialogs auto-accepted by default
• withBrowser(fn, endpoint?) — connects to the browser-level endpoint
• new Session({ endpoint?, onLaunch?, launchTimeoutMs?, autoDismissDialogs? }) with setCurrent / current / forget / listPages / connectPage / ensure / resolve / withPage / withBrowser

Endpoint defaults to 127.0.0.1:9222, overridable per call or via the CDP_HOST / CDP_PORT environment variables.

Network recording

Pass an already-connected page client; it records into a stream or file.

import { connectPage } from "plyxen";
import { NetworkRecorder } from "plyxen/netlog";

const client = await connectPage(pageId);
const rec = new NetworkRecorder(client);

await rec.start({ filter: "api", out: "./network.log" }); // JSON Lines, sensitive values masked
// ... drive the page ...
const { count } = await rec.stop();
await client.close();

Options: filter, failOnly, failStatus, successContains, failContains, redact (default true), sensitiveHeaders, and out (a writable stream or a file path to append to).

Redaction helpers are exported for reuse: redactHeaders, redactUrl, redactBody, and DEFAULT_SENSITIVE_HEADERS.

Even with redaction on, recorded traffic can contain private data. Treat the output as sensitive and keep it out of version control.

License

MIT