{"_id":"@agmod/runbrowser-relay","_rev":"2-36eec7d26ad190756f6abb3c5cc31148","name":"@agmod/runbrowser-relay","dist-tags":{"latest":"0.0.3"},"versions":{"0.0.2":{"name":"@agmod/runbrowser-relay","version":"0.0.2","keywords":["cdp","chrome-devtools-protocol","relay","websocket","playwright","browser","runbrowser"],"license":"MIT","_id":"@agmod/runbrowser-relay@0.0.2","maintainers":[{"name":"agmod","email":"jiwei@agmod.com"}],"homepage":"https://github.com/yuanjiwei/runbrowser","bugs":{"url":"https://github.com/yuanjiwei/runbrowser/issues"},"bin":{"runbrowser-relay":"bin.js"},"dist":{"shasum":"b9ae93aebd5d57cb975d6244dadb1e09ac1dd9c8","tarball":"https://registry.npmjs.org/@agmod/runbrowser-relay/-/runbrowser-relay-0.0.2.tgz","fileCount":95,"integrity":"sha512-Ew6dnrI29GDtTVPZ2snyD1lGbtVegeErLuXS0LJSDqMlqXRecDHFI5mo+VsocQMD8c5mXRRP7pEP+GTNmSGUhA==","signatures":[{"sig":"MEUCIGGfdFmBbiPllPf1KQlRMpmLyOcgUmos5VNXZDzgjeglAiEAjmg0XjJRDG2ZS2U8Ku1gHGseyxqUWmpCHnG6FdZPAQs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":614946},"main":"dist/index.js","type":"module","_from":"file:agmod-runbrowser-relay-0.0.2.tgz","types":"dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./api":{"types":"./dist/api-client.d.ts","import":"./dist/api-client.js"},"./start":{"types":"./dist/start.d.ts","import":"./dist/start.js"},"./types":{"types":"./dist/cdp-types.d.ts","import":"./dist/cdp-types.js"},"./utils":{"types":"./dist/utils.d.ts","import":"./dist/utils.js"},"./client":{"types":"./dist/client.d.ts","import":"./dist/client.js"},"./logger":{"types":"./dist/create-logger.d.ts","import":"./dist/create-logger.js"},"./protocol":{"types":"./dist/protocol.d.ts","import":"./dist/protocol.js"},"./package.json":"./package.json"},"scripts":{"test":"vitest run -u","build":"tsc","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"agmod","email":"jiwei@agmod.com"},"_resolved":"/private/var/folders/6q/n5pt_9hx3mbcbk1_wj92_r_r0000gn/T/408adf58ee827eb5a409b41b1e6c8487/agmod-runbrowser-relay-0.0.2.tgz","_integrity":"sha512-Ew6dnrI29GDtTVPZ2snyD1lGbtVegeErLuXS0LJSDqMlqXRecDHFI5mo+VsocQMD8c5mXRRP7pEP+GTNmSGUhA==","repository":{"url":"git+https://github.com/yuanjiwei/runbrowser.git","type":"git","directory":"packages/relay"},"_npmVersion":"11.9.0","description":"CDP relay for RunBrowser — bridges Chrome extension WebSocket to Playwright CDP clients","directories":{},"_nodeVersion":"25.6.1","dependencies":{"ws":"^8.18.3","hono":"^4.10.6","zustand":"^5.0.8","picocolors":"^1.1.1","strip-ansi":"^7.1.2","@hono/node-ws":"^1.2.0","@hono/node-server":"^1.19.6"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.8","@types/ws":"^8.18.1","typescript":"^5.9.3","@types/node":"^24.10.1","devtools-protocol":"^0.0.1568893"},"_npmOperationalInternal":{"tmp":"tmp/runbrowser-relay_0.0.2_1772664440959_0.30996994882822126","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@agmod/runbrowser-relay","version":"0.0.3","description":"CDP relay for RunBrowser — bridges Chrome extension WebSocket to Playwright CDP clients","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./client":{"types":"./dist/client.d.ts","import":"./dist/client.js"},"./api":{"types":"./dist/api-client.d.ts","import":"./dist/api-client.js"},"./types":{"types":"./dist/cdp-types.d.ts","import":"./dist/cdp-types.js"},"./protocol":{"types":"./dist/protocol.d.ts","import":"./dist/protocol.js"},"./utils":{"types":"./dist/utils.d.ts","import":"./dist/utils.js"},"./logger":{"types":"./dist/create-logger.d.ts","import":"./dist/create-logger.js"},"./start":{"types":"./dist/start.d.ts","import":"./dist/start.js"},"./package.json":"./package.json"},"bin":{"runbrowser-relay":"bin.js"},"keywords":["cdp","chrome-devtools-protocol","relay","websocket","playwright","browser","runbrowser"],"repository":{"type":"git","url":"git+https://github.com/yuanjiwei/runbrowser.git","directory":"packages/relay"},"homepage":"https://github.com/yuanjiwei/runbrowser","license":"MIT","publishConfig":{"access":"public"},"engines":{"node":">=18"},"dependencies":{"@hono/node-server":"^1.19.6","@hono/node-ws":"^1.2.0","hono":"^4.10.6","picocolors":"^1.1.1","strip-ansi":"^7.1.2","ws":"^8.18.3","zustand":"^5.0.8"},"devDependencies":{"@types/node":"^24.10.1","@types/ws":"^8.18.1","devtools-protocol":"^0.0.1568893","typescript":"^5.9.3","vitest":"^4.0.8"},"scripts":{"build":"tsc","typecheck":"tsc --noEmit","test":"vitest run -u","test:watch":"vitest"},"_id":"@agmod/runbrowser-relay@0.0.3","bugs":{"url":"https://github.com/yuanjiwei/runbrowser/issues"},"_integrity":"sha512-bEpkPeC29VpX6xu6rma0k30Aqrfi1RZgZIhTkF7y2gXsiqIfPkVsY0z7gVj6tvG37eRK074PzWE5dcAYrBwA/w==","_resolved":"/private/var/folders/6q/n5pt_9hx3mbcbk1_wj92_r_r0000gn/T/8f61259dc2d13171a7c29350ae13d46e/agmod-runbrowser-relay-0.0.3.tgz","_from":"file:agmod-runbrowser-relay-0.0.3.tgz","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-bEpkPeC29VpX6xu6rma0k30Aqrfi1RZgZIhTkF7y2gXsiqIfPkVsY0z7gVj6tvG37eRK074PzWE5dcAYrBwA/w==","shasum":"4122f1f471a636135ad35d378269a2a1e3a2f35b","tarball":"https://registry.npmjs.org/@agmod/runbrowser-relay/-/runbrowser-relay-0.0.3.tgz","fileCount":95,"unpackedSize":617542,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGaLUPcslPUC4lg9Ph+CPJT+KAlAPZXfAdeuTXliSIL6AiAW5SMDuuCSr8xtx48dmzVI/Uo84dTmYKRu/TMQlrjCsw=="}]},"_npmUser":{"name":"agmod","email":"jiwei@agmod.com"},"directories":{},"maintainers":[{"name":"agmod","email":"jiwei@agmod.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/runbrowser-relay_0.0.3_1772666444045_0.6807611711354251"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-04T22:47:20.905Z","modified":"2026-03-04T23:20:44.597Z","0.0.2":"2026-03-04T22:47:21.100Z","0.0.3":"2026-03-04T23:20:44.207Z"},"bugs":{"url":"https://github.com/yuanjiwei/runbrowser/issues"},"license":"MIT","homepage":"https://github.com/yuanjiwei/runbrowser","keywords":["cdp","chrome-devtools-protocol","relay","websocket","playwright","browser","runbrowser"],"repository":{"type":"git","url":"git+https://github.com/yuanjiwei/runbrowser.git","directory":"packages/relay"},"description":"CDP relay for RunBrowser — bridges Chrome extension WebSocket to Playwright CDP clients","maintainers":[{"name":"agmod","email":"jiwei@agmod.com"}],"readme":"# @agmod/runbrowser-relay\n\nCDP (Chrome DevTools Protocol) relay server for [RunBrowser](https://github.com/yuanjiwei/runbrowser). This package bridges Chrome extension WebSocket connections to Playwright CDP clients, enabling browser automation over your running Chrome browser.\n\n## Architecture\n\n```\n┌──────────────┐     WebSocket      ┌─────────────────┐     WebSocket      ┌────────────────┐\n│   Chrome     │ ◄─────────────────►│  Relay Server   │ ◄─────────────────►│   Playwright   │\n│  Extension   │    /extension      │  (this package)  │    /cdp/:clientId  │  CDP Client    │\n└──────────────┘                    └─────────────────┘                    └────────────────┘\n                                          │\n                                          │  HTTP API\n                                          │  /version, /json, /extension/status\n                                          │  /cli/*, /recording/*\n                                          ▼\n```\n\nThe relay server:\n- Accepts WebSocket connections from the RunBrowser Chrome extension\n- Accepts WebSocket connections from Playwright CDP clients\n- Routes CDP commands/events between them\n- Manages extension connections, target tracking, and session state\n- Provides HTTP endpoints for discovery, status, CLI execution, and recording\n\n## Installation\n\n```bash\nnpm install @agmod/runbrowser-relay\n```\n\n## Usage\n\n### Programmatic\n\n```ts\nimport { startRunBrowserCDPRelayServer } from '@agmod/runbrowser-relay'\n\nconst server = await startRunBrowserCDPRelayServer({\n  port: 19988,\n  host: '127.0.0.1',\n  logger: console,\n})\n\n// Later...\nserver.close()\n```\n\n### With CLI Execute Endpoints\n\nTo enable `/cli/*` endpoints, provide an executor manager factory:\n\n```ts\nimport { startRunBrowserCDPRelayServer } from '@agmod/runbrowser-relay'\n\nconst server = await startRunBrowserCDPRelayServer({\n  port: 19988,\n  executorManagerFactory: async ({ cdpConfig, logger }) => {\n    const { ExecutorManager } = await import('runbrowser/executor')\n    return new ExecutorManager({ cdpConfig, logger })\n  },\n})\n```\n\n### Standalone Binary\n\n```bash\nnpx @agmod/runbrowser-relay\n```\n\n## Client Utilities\n\nThe package also provides client-side utilities for connecting to the relay server:\n\n```ts\nimport { ensureRelayServer, RELAY_PORT, waitForConnectedExtensions } from '@agmod/runbrowser-relay/client'\n\n// Start relay server if not running\nawait ensureRelayServer({ logger: console })\n\n// Wait for Chrome extension to connect\nconst extensions = await waitForConnectedExtensions({\n  timeoutMs: 10000,\n  logger: console,\n})\n```\n\n## Exports\n\n| Subpath | Description |\n|---------|-------------|\n| `@agmod/runbrowser-relay` | Core server, state management, types, utilities |\n| `@agmod/runbrowser-relay/client` | Client utilities (ensureRelayServer, version checks) |\n| `@agmod/runbrowser-relay/types` | CDP protocol types |\n| `@agmod/runbrowser-relay/protocol` | Extension message protocol types |\n| `@agmod/runbrowser-relay/utils` | Shared utilities (EXTENSION_IDS, VERSION, log paths) |\n| `@agmod/runbrowser-relay/logger` | File logger |\n\n## Key Types\n\n```ts\n// Server configuration\ninterface RelayServer {\n  close(): void\n  on<K extends keyof RelayServerEvents>(event: K, listener: RelayServerEvents[K]): void\n  off<K extends keyof RelayServerEvents>(event: K, listener: RelayServerEvents[K]): void\n}\n\n// Executor dependency injection (for CLI endpoints)\ninterface ExecutorManagerLike { ... }\ninterface ExecutorLike { ... }\ntype ExecutorManagerFactory = (config: { cdpConfig, logger }) => Promise<ExecutorManagerLike>\n\n// Relay state\ninterface ExtensionEntry { id, info, stableKey, connectedTargets, ws, ... }\ninterface PlaywrightClient { id, extensionId, ws }\ninterface RelayState { extensions, playwrightClients }\n```\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `RUNBROWSER_PORT` | Relay server port (default: 19988) |\n| `RUNBROWSER_AUTO_ENABLE` | Auto-create initial tab for Playwright |\n| `RUNBROWSER_LOG_FILE_PATH` | Custom relay server log path |\n| `RUNBROWSER_CDP_LOG_FILE_PATH` | Custom CDP log path |\n\n## License\n\nMIT\n","readmeFilename":"README.md"}