website-api 1.1.3 → 1.1.6

package/README.md

@@ -1,3 +1,143 @@
 # website-api
 
-CLI and library to fetch website API data
+Query websites' private APIs with your **real logged-in Chrome session** — as a CLI or a Node.js library.
+
+One site definition describes *what* to fetch; the runtime assembles *how*: plain HTTP with your decrypted
+Chrome cookies injected, or a real fingerprinted Chrome tab over CDP, with login, downloads, and in-page
+scripts available as composable capabilities. See [DESIGN.md](DESIGN.md) for the architecture.
+
+> macOS-focused: cookie/credential decryption uses [chrome-tools](https://www.npmjs.com/package/chrome-tools),
+> which reads Chrome's local encrypted storage via the macOS keychain.
+
+## Install
+
+```sh
+npm install -g website-api        # CLI
+npm install website-api           # library
+```
+
+Requires Node ≥ 22. `playwright-core` is an **optional** dependency — HTTP-only sites work without it;
+browser-transport sites (`[p]` in `list`) will tell you to install it if it's missing.
+
+Browser-transport sites no longer need you to start Chrome by hand:
+[chrome-cdp-manager](https://www.npmjs.com/package/chrome-cdp-manager) launches (or attaches to) a
+dedicated, isolated CDP browser automatically on first use. It runs **headless by default**, but if a
+CDP session is already open it reuses that one as-is. Pass `--headed` to force a visible window (e.g. to
+solve a captcha that needs a real press-and-hold). To attach to a Chrome you manage yourself, set
+`CDP_ENDPOINT` (e.g. `http://localhost:9222`) and that endpoint is used directly.
+
+## CLI quickstart
+
+```sh
+website-api list                          # all bundled + installed sites
+website-api codex-usage                   # ChatGPT/Codex usage via your session
+website-api perplexity "what is pnpm?"    # positional args
+website-api claude-usage --org my-org     # site-specific flags
+website-api chatgpt.com --help            # per-site help
+website-api example.com                   # no definition? universal cookie-aware GET
+```
+
+Useful global flags: `--profile <name>` (Chrome profile), `--debug` (full request/response dump),
+`--keep-open` (leave the browser tab open), `--headed` (show the managed Chrome window; default headless),
+`--out <file>`.
+
+### Installing more sites
+
+Sites can be installed from a public registry (a GitHub repo of prebuilt site modules):
+
+```sh
+website-api ext search zillow
+website-api ext install zillow
+website-api ext list / remove / update
+```
+
+**Security note:** an installed site is code that runs with access to your Chrome cookies for its domain.
+Installs are SHA256-verified against the registry catalog and require confirmation — only install sites
+from registries you trust.
+
+## Library usage
+
+Everything the CLI does is available programmatically:
+
+```ts
+import { queryWebsite } from "website-api";
+
+// By site id — same resolution as the CLI
+const usage = await queryWebsite("codex-usage", { profile: "Default" });
+```
+
+Import a bundled site directly and run it — handy for other packages that want
+one site's features without the registry:
+
+```ts
+import { runSite } from "website-api";
+import zillow from "website-api/sites/zillow.com";
+
+const homes = await runSite(zillow, { query: "Seattle, WA" });
+```
+
+Or bring your own definition — `runSite` accepts a plain object:
+
+```ts
+import { runSite } from "website-api";
+
+const result = await runSite({
+  id: "example",
+  name: "Example",
+  domain: "example.com",
+  description: "JSON endpoint with my session cookies",
+  endpoints: [{ url: "https://example.com/api/me" }],
+});
+```
+
+Tests and embedders can inject fakes for every capability (fetch, browser, cookie store, fs) via the
+third `providers` argument — see `ContextProviders`.
+
+## Writing your own site
+
+Drop a folder in `~/.config/website-api/extensions/` — no imports, no build step:
+
+```js
+// ~/.config/website-api/extensions/example.com/index.mjs
+export default {
+  id: "example",
+  name: "Example",
+  domain: "example.com",
+  description: "Example data",
+  endpoints: [{ url: "https://example.com/api/data" }],
+};
+```
+
+It shows up in `website-api list` immediately (marked `[x]`). Sites needing a real browser set
+`transport: "browser"` and use `ctx.browser()` / `ctx.eval()` inside a `run(ctx)` function; login flows,
+downloads, and SSE parsing are provided by the context. Develop iteratively with
+`website-api ext test ./my-site` (runs a local file without installing). Full authoring guide:
+[DESIGN.md](DESIGN.md).
+
+## OpenAPI specs
+
+Every bundled site ships a generated `openapi.yaml` next to its module (`dist/src/sites/<site>/openapi.yaml`
+in the published package) describing its endpoints and CLI surface, including the `x-website-api` extension
+block. Regenerate with `pnpm generate:openapi` after a build.
+
+## Security model
+
+- Cookies and credentials are read from Chrome's local encrypted storage and **only sent to the target
+  site's own domain**. They are never written to disk or sent anywhere else.
+- `--debug` prints raw requests/responses (including cookie headers) to your terminal — don't paste that
+  output into bug reports.
+- Registry installs run third-party code; they are integrity-checked (SHA256) and gated behind an explicit
+  confirmation that names the source repo.
+
+## Development
+
+```sh
+pnpm install        # local dev links chrome-tools from ../chrome_tools (pnpm-workspace.yaml)
+pnpm build          # tsc → dist (readable, unminified)
+pnpm test           # node:test — offline, no Chrome needed
+pnpm lint           # biome
+pnpm typecheck
+pnpm generate:openapi
+```
+
+MIT © guocity

package/dist/bin/cli.js

@@ -1,2 +1,210 @@
 #!/usr/bin/env node
-import{readFileSync as e,writeFileSync as o}from"node:fs";import{dirname as n,join as s}from"node:path";import{fileURLToPath as t}from"node:url";import{program as r}from"commander";import i from"chalk";import l from"cli-table3";import{getDefaultChromeDir as a}from"chrome-tools";import{queryWebsite as c,sites as p,loadSites as d,getSite as u}from"../src/website-api.js";import{registerExtCommands as g}from"../src/cli/ext.js";import{parseArgsForWebsite as f}from"../src/util/args-parser.js";const m=s(n(t(import.meta.url)),"..","..","package.json"),{version:b}=JSON.parse(e(m,"utf8"));process.on("unhandledRejection",e=>{console.error(e instanceof Error?e.message:"command not found"),process.exit(1)}),async function(){const e=process.argv.slice(2),n=e.find(e=>!e.startsWith("-"));if(n&&"list"!==n){await d();const s=u(n);if(s){const t=e.filter((o,s)=>s!==e.indexOf(n));let r;try{r=f(s.positionals,s.parameters,t)}catch(e){console.error(i.red(`Error: ${e instanceof Error?e.message:String(e)}`)),console.log(`Run ${i.cyan(`npx website-api ${s.id} --help`)} for usage details.`),process.exit(1)}if(r.helpRequested)return void function(e){console.log(i.bold.green(`\n🌐 Website API: ${i.white(e.name)} (${i.yellow(e.id)})\n`)),console.log(`  ${i.italic(e.description)}\n`);let o=`npx website-api ${e.id}`;if(e.positionals&&e.positionals.length>0)for(const n of e.positionals)o+=n.required?` <${n.name}>`:` [${n.name}]`;if(o+=" [options]",console.log(`${i.bold("Usage:")} ${i.cyan(o)}\n`),e.positionals&&e.positionals.length>0){console.log(i.bold("Positional Arguments:"));for(const o of e.positionals)console.log(`  ${i.cyan(o.name.padEnd(15))} ${o.description}`);console.log()}console.log(i.bold("Options:"));const n=[...e.parameters||[],{name:"profile",type:"string",description:"specific Chrome profile directory (e.g., 'Default')"},{name:"user-agent",type:"string",description:"custom User-Agent header for HTTP requests",short:"u"},{name:"debug",type:"boolean",description:"Print full HTTP request and response bodies for debugging"},{name:"keep-open",type:"boolean",description:"Leave the browser tab open after running (preserve the logged-in session)"},{name:"help",type:"boolean",description:"Show help for this website site",short:"h"}];for(const e of n){let o=`--${e.name}`;"boolean"!==e.type&&(o+=" <value>"),o=e.short?`-${e.short}, ${o}`:`    ${o}`;const n=void 0!==e.default?` (default: ${e.default})`:"";console.log(`  ${i.yellow(o.padEnd(28))} ${e.description}${i.gray(n)}`)}console.log()}(s);try{const e=await c(s.id,r.options);let n;if(r.options.text&&e&&"object"==typeof e){const o=e.answer||e.text;n=void 0!==o?String(o):JSON.stringify(e,null,2)}else n="string"==typeof e?e:JSON.stringify(e,null,2);r.options.out?(o(r.options.out,n+"\n","utf8"),console.log(i.green(`Success! Decoded response written to ${r.options.out}`))):console.log(n)}catch(e){console.error(i.red(e instanceof Error?e.message:"command not found")),process.exit(1)}return}}r.name("website-api").description("CLI to query website APIs using decrypted Chrome cookies on macOS").version(b),r.option("--profile <name>","specific Chrome profile directory (e.g., 'Default', 'Profile 1')").option("--current-profile","Show the currently resolved/selected Chrome profile directory and name").option("-u, --user-agent <string>","custom User-Agent header for HTTP requests"),r.option("--debug","Print full HTTP request and response bodies for debugging"),r.command("list").description("List all supported website API sites").action(async()=>{await d(),console.log(i.bold.green("\n🌐 Supported Website APIs:\n"));const e=new l({head:[i.bold.cyan("ID"),i.bold.cyan("Name"),i.bold.cyan("Domain"),i.bold.cyan("Description")],colWidths:[18,25,20,50],wordWrap:!0,style:{head:[],border:[]}});for(const o of p){const n=[];"browser"===o.transport&&n.push(i.magenta("[p]")),o.auth&&n.push(i.red("[l]")),"extension"===o.origin&&n.push(i.blue("[x]"));const s=n.length?`${o.name} ${n.join(" ")}`:o.name;e.push([i.yellow(o.id),s,i.underline(o.domain),o.description])}console.log(e.toString()),console.log(`\n${i.magenta("[p]")} requires a running Chrome (Playwright)   ${i.red("[l]")} requires login   ${i.blue("[x]")} user extension`),console.log(`\nTo run an API query, execute: ${i.bold.cyan("npx website-api <id>")}\n`)}),g(r),r.argument("[website]","website ID or domain to query (e.g. 'chatgpt.com')").action(async e=>{const o=r.opts();if(o.currentProfile){const e=process.env.PROFILE_PATH||process.env.CHROME_PROFILE_PATH||a(),n=o.profile||process.env.PROFILE_NAME||"Default";return console.log(i.bold.green("\n👤 Currently Resolved Profile:\n")),console.log(`  ${i.bold("Path:")}  ${e}`),void console.log(`  ${i.bold("Name:")}  ${n}\n`)}e?(console.error(i.red(`Error: website adapter "${e}" not found.`)),console.log(`Run ${i.cyan("npx website-api list")} to see all supported adapters.`),process.exit(1)):r.outputHelp()}),r.parse(process.argv)}().catch(e=>{console.error(e instanceof Error?e.message:"command not found"),process.exit(1)});
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import chalk from "chalk";
+import { getDefaultChromeDir } from "chrome-tools";
+import Table from "cli-table3";
+import { program } from "commander";
+import { registerExtCommands } from "../src/cli/ext.js";
+import { parseArgsForWebsite } from "../src/util/args-parser.js";
+import { getSite, loadSites, queryWebsite, sites } from "../src/website-api.js";
+const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+const { version: packageVersion } = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+// Handle unhandled promise rejections cleanly
+process.on("unhandledRejection", (reason) => {
+    console.error(reason instanceof Error ? reason.message : "command not found");
+    process.exit(1);
+});
+/**
+ * Renders a premium, comprehensive help page for a specific website adapter.
+ */
+function printWebsiteHelp(adapter) {
+    console.log(chalk.bold.green(`\n🌐 Website API: ${chalk.white(adapter.name)} (${chalk.yellow(adapter.id)})\n`));
+    console.log(`  ${chalk.italic(adapter.description)}\n`);
+    let usageStr = `npx website-api ${adapter.id}`;
+    if (adapter.positionals && adapter.positionals.length > 0) {
+        for (const pos of adapter.positionals) {
+            usageStr += pos.required ? ` <${pos.name}>` : ` [${pos.name}]`;
+        }
+    }
+    usageStr += " [options]";
+    console.log(`${chalk.bold("Usage:")} ${chalk.cyan(usageStr)}\n`);
+    if (adapter.positionals && adapter.positionals.length > 0) {
+        console.log(chalk.bold("Positional Arguments:"));
+        for (const pos of adapter.positionals) {
+            console.log(`  ${chalk.cyan(pos.name.padEnd(15))} ${pos.description}`);
+        }
+        console.log();
+    }
+    console.log(chalk.bold("Options:"));
+    const allParams = [
+        ...(adapter.parameters || []),
+        { name: "profile", type: "string", description: "specific Chrome profile directory (e.g., 'Default')" },
+        {
+            name: "user-agent",
+            type: "string",
+            description: "custom User-Agent header for HTTP requests",
+            short: "u",
+        },
+        {
+            name: "debug",
+            type: "boolean",
+            description: "Print full HTTP request and response bodies for debugging",
+        },
+        {
+            name: "keep-open",
+            type: "boolean",
+            description: "Leave the browser tab open after running (preserve the logged-in session)",
+        },
+        {
+            name: "headed",
+            type: "boolean",
+            description: "Show the managed Chrome window (default headless; reuses an already-open session)",
+        },
+        {
+            name: "proxy",
+            type: "string",
+            description: 'Route the managed browser through a proxy: "default", a port, host:port, or scheme://host:port',
+        },
+        { name: "help", type: "boolean", description: "Show help for this website site", short: "h" },
+    ];
+    for (const param of allParams) {
+        let flag = `--${param.name}`;
+        if (param.type !== "boolean") {
+            flag += ` <value>`;
+        }
+        if (param.short) {
+            flag = `-${param.short}, ${flag}`;
+        }
+        else {
+            flag = `    ${flag}`;
+        }
+        const defStr = param.default !== undefined ? ` (default: ${param.default})` : "";
+        console.log(`  ${chalk.yellow(flag.padEnd(28))} ${param.description}${chalk.gray(defStr)}`);
+    }
+    console.log();
+}
+async function runCli() {
+    const argv = process.argv.slice(2);
+    // Check if first positional is a website adapter (avoiding commands and global flags)
+    const firstPositional = argv.find((arg) => !arg.startsWith("-"));
+    if (firstPositional && firstPositional !== "list") {
+        await loadSites();
+        const adapter = getSite(firstPositional);
+        if (adapter) {
+            // Bypasses standard commander parser to allow website-specific options
+            const websiteArgs = argv.filter((_, i) => i !== argv.indexOf(firstPositional));
+            let parsed;
+            try {
+                parsed = parseArgsForWebsite(adapter.positionals, adapter.parameters, websiteArgs);
+            }
+            catch (err) {
+                console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+                console.log(`Run ${chalk.cyan(`npx website-api ${adapter.id} --help`)} for usage details.`);
+                process.exit(1);
+            }
+            if (parsed.helpRequested) {
+                printWebsiteHelp(adapter);
+                return;
+            }
+            try {
+                const data = await queryWebsite(adapter.id, parsed.options);
+                let output;
+                if (parsed.options.text && data && typeof data === "object") {
+                    const ans = data.answer || data.text;
+                    output = ans !== undefined ? String(ans) : JSON.stringify(data, null, 2);
+                }
+                else {
+                    output = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+                }
+                if (parsed.options.out) {
+                    writeFileSync(parsed.options.out, output + "\n", "utf8");
+                    console.log(chalk.green(`Success! Decoded response written to ${parsed.options.out}`));
+                }
+                else {
+                    console.log(output);
+                }
+            }
+            catch (err) {
+                console.error(chalk.red(err instanceof Error ? err.message : "command not found"));
+                process.exit(1);
+            }
+            return;
+        }
+    }
+    // Fallback to Commander for global commands and options
+    program
+        .name("website-api")
+        .description("CLI to query website APIs using decrypted Chrome cookies on macOS")
+        .version(packageVersion);
+    // Global options
+    program
+        .option("--profile <name>", "specific Chrome profile directory (e.g., 'Default', 'Profile 1')")
+        .option("--current-profile", "Show the currently resolved/selected Chrome profile directory and name")
+        .option("-u, --user-agent <string>", "custom User-Agent header for HTTP requests");
+    program.option("--debug", "Print full HTTP request and response bodies for debugging");
+    program.option("--headed", "Show the managed Chrome window (default headless; reuses an already-open session)");
+    // List command
+    program
+        .command("list")
+        .description("List all supported website API sites")
+        .action(async () => {
+        await loadSites();
+        console.log(chalk.bold.green("\n🌐 Supported Website APIs:\n"));
+        const table = new Table({
+            head: [
+                chalk.bold.cyan("ID"),
+                chalk.bold.cyan("Name"),
+                chalk.bold.cyan("Domain"),
+                chalk.bold.cyan("Description"),
+            ],
+            colWidths: [18, 25, 20, 50],
+            wordWrap: true,
+            style: { head: [], border: [] },
+        });
+        for (const web of sites) {
+            const markers = [];
+            if (web.transport === "browser")
+                markers.push(chalk.magenta("[p]"));
+            if (web.auth)
+                markers.push(chalk.red("[l]"));
+            if (web.origin === "extension")
+                markers.push(chalk.blue("[x]"));
+            const nameCell = markers.length ? `${web.name} ${markers.join(" ")}` : web.name;
+            table.push([chalk.yellow(web.id), nameCell, chalk.underline(web.domain), web.description]);
+        }
+        console.log(table.toString());
+        console.log(`\n${chalk.magenta("[p]")} requires a running Chrome (Playwright)   ${chalk.red("[l]")} requires login   ${chalk.blue("[x]")} user extension`);
+        console.log(`\nTo run an API query, execute: ${chalk.bold.cyan("npx website-api <id>")}\n`);
+    });
+    // Extension registry commands: `ext search|info|install|list|remove|update|registry`
+    registerExtCommands(program);
+    // Default command: fallback error or help
+    program
+        .argument("[website]", "website ID or domain to query (e.g. 'chatgpt.com')")
+        .action(async (website) => {
+        const globalOpts = program.opts();
+        if (globalOpts.currentProfile) {
+            const profilePath = process.env.PROFILE_PATH || process.env.CHROME_PROFILE_PATH || getDefaultChromeDir();
+            const profileName = globalOpts.profile || process.env.PROFILE_NAME || "Default";
+            console.log(chalk.bold.green("\n👤 Currently Resolved Profile:\n"));
+            console.log(`  ${chalk.bold("Path:")}  ${profilePath}`);
+            console.log(`  ${chalk.bold("Name:")}  ${profileName}\n`);
+            return;
+        }
+        if (!website) {
+            program.outputHelp();
+            return;
+        }
+        // If website not found
+        console.error(chalk.red(`Error: website adapter "${website}" not found.`));
+        console.log(`Run ${chalk.cyan("npx website-api list")} to see all supported adapters.`);
+        process.exit(1);
+    });
+    program.parse(process.argv);
+}
+runCli().catch((err) => {
+    console.error(err instanceof Error ? err.message : "command not found");
+    process.exit(1);
+});

package/dist/src/capabilities/browser.d.ts

@@ -1,7 +1,21 @@
-import { type Browser, type Page } from "playwright-core";
+import type { Browser, Page } from "playwright-core";
 export interface BrowserOptions {
-    /** CDP endpoint of a running Chrome. Defaults to env or localhost:9222. */
+    /**
+     * CDP endpoint of an already-running Chrome. When set (or via the
+     * `CDP_ENDPOINT` env var), we attach to it directly and skip launching. When
+     * unset, chrome-cdp-manager launches/attaches a managed browser for us.
+     */
     cdpEndpoint?: string;
+    /** Launch the managed browser headless. Ignored when `cdpEndpoint` is set. */
+    headless?: boolean;
+    /**
+     * Route the managed browser through a proxy. `true` / "default" → the default
+     * SOCKS5 proxy (socks5://127.0.0.1:1080); a port ("1080"), "host:port", or
+     * full "scheme://host:port" is accepted. Forwarded to chrome-cdp-manager's
+     * `launch({ proxy })`, so it applies only on a fresh launch (an already-running
+     * browser or an explicit `cdpEndpoint` is used as-is). Ignored when falsy.
+     */
+    proxy?: string | boolean;
     /** Close a tab opened by this session on dispose. Defaults to true. */
     close?: boolean;
     debug?: boolean;

package/dist/src/capabilities/browser.js

@@ -1 +1,158 @@
-import{chromium as t}from"playwright-core";export const connectChrome=async(e,o={})=>{const n=o.cdpEndpoint||process.env.CDP_ENDPOINT||"http://localhost:9222",r=!!o.debug,a=await t.connectOverCDP(n),c=a.contexts()[0];if(!c)throw new Error("No active browser context found. Is Chrome running with remote debugging enabled?");let s=!1,i=c.pages().find(t=>{try{const o=new URL(e).hostname.replace("www.","");return new URL(t.url()).hostname.endsWith(o)||t.url().startsWith(e)}catch{return t.url().startsWith(e)}});return i?r&&console.log(`Reusing existing tab for ${e}`):(r&&console.log(`Opening a new tab for ${e}`),i=await c.newPage(),await i.goto(e,{waitUntil:"domcontentloaded"}),s=!0),{page:i,browser:a,opened:s,async dispose(){if(s&&!1!==o.close)try{await i.close()}catch{}try{await a.close()}catch{}}}};
+/**
+ * playwright-core is an optional dependency: HTTP-only installs work without
+ * it, and it's loaded here on the first browser connection.
+ */
+async function loadChromium() {
+    try {
+        return (await import("playwright-core")).chromium;
+    }
+    catch {
+        throw new Error('This site needs a browser, which requires the optional "playwright-core" dependency. ' +
+            "Install it with: npm install playwright-core");
+    }
+}
+/**
+ * chrome-cdp-manager launches (or attaches to) a launcher-managed CDP browser
+ * so the user never has to start Chrome with `--remote-debugging-port` by hand.
+ * Loaded lazily — HTTP-only runs never pay for it, and the os-restricted package
+ * surfaces a clear error if it's missing on an unsupported platform.
+ */
+async function loadCdpManager() {
+    try {
+        return await import("chrome-cdp-manager");
+    }
+    catch {
+        throw new Error('This site needs a browser, which is managed by the "chrome-cdp-manager" dependency. ' +
+            "Install it with: npm install chrome-cdp-manager (macOS/Windows only).");
+    }
+}
+/**
+ * Resolves the CDP endpoint to connect to. An explicit endpoint (option or
+ * `CDP_ENDPOINT`) wins and is used as-is, so users can still point at a Chrome
+ * they manage themselves. Otherwise chrome-cdp-manager ensures a managed
+ * browser is running (launching it if needed) and returns its endpoint.
+ *
+ * When a proxy is requested, chrome-cdp-manager probes it: an unreachable proxy
+ * is dropped and the browser launches direct (we surface a "connecting directly"
+ * notice). A reachable proxy forces a fresh launch so it actually takes effect.
+ */
+async function resolveEndpoint(options) {
+    const explicit = options.cdpEndpoint || process.env.CDP_ENDPOINT;
+    if (explicit)
+        return { endpoint: explicit, managed: false, proxyApplied: false, cdpPort: 0 };
+    const { launch } = await loadCdpManager();
+    const { endpoint, launched, config, proxyRequested, proxyReachable } = (await launch({
+        headless: !!options.headless,
+        proxy: options.proxy || undefined,
+    }));
+    const proxyApplied = !!config?.proxy;
+    // Situation 1: a proxy was asked for but nothing was listening — we fell back
+    // to a direct connection. Surface it (stderr, so JSON stdout stays clean).
+    if (proxyRequested && !proxyReachable) {
+        console.error(`Proxy ${options.proxy} not reachable — connecting directly (no proxy).`);
+    }
+    if (options.debug) {
+        const mode = options.headless ? "headless" : "headed";
+        const via = proxyApplied ? ` via proxy ${config.proxy}` : "";
+        console.log(launched
+            ? `Launched managed Chrome (${mode})${via} at ${endpoint}`
+            : `Attached to managed Chrome at ${endpoint} (already running)`);
+    }
+    return { endpoint, managed: true, proxyApplied, cdpPort: config?.cdpPort ?? 9222 };
+}
+/**
+ * Connects to an existing Chrome over CDP and reuses (or opens) a tab for the
+ * target URL. Returns a session with an explicit `dispose()` the runtime calls
+ * during teardown — sites never manage the connection themselves.
+ */
+export const connectChrome = async (targetUrl, options = {}) => {
+    const debug = !!options.debug;
+    const { endpoint, managed, proxyApplied, cdpPort } = await resolveEndpoint(options);
+    const chromium = await loadChromium();
+    const browser = await chromium.connectOverCDP(endpoint);
+    const context = browser.contexts()[0];
+    if (!context) {
+        throw new Error("No active browser context found. Is Chrome running with remote debugging enabled?");
+    }
+    let opened = false;
+    let page = context.pages().find((p) => {
+        try {
+            const targetHost = new URL(targetUrl).hostname.replace("www.", "");
+            const pHost = new URL(p.url()).hostname;
+            return pHost.endsWith(targetHost) || p.url().startsWith(targetUrl);
+        }
+        catch {
+            return p.url().startsWith(targetUrl);
+        }
+    });
+    if (page) {
+        if (debug)
+            console.log(`Reusing existing tab for ${targetUrl}`);
+    }
+    else {
+        if (debug)
+            console.log(`Opening a new tab for ${targetUrl}`);
+        page = await context.newPage();
+        opened = true;
+    }
+    // Headless Chrome leaks "HeadlessChrome" in its network User-Agent header (the
+    // JS-level fingerprint init script only changes navigator.userAgent, not the
+    // request header). Some sites — e.g. Micro Center — serve a blank/blocked page
+    // to it, so the product grid never appears. Mirror what
+    // chrome-cdp-manager/playwright's connect() does and override the network UA to
+    // a de-headlessed value, before any navigation.
+    if (options.headless) {
+        try {
+            const liveUa = await page.evaluate(() => navigator.userAgent);
+            const ua = liveUa.replace(/HeadlessChrome/g, "Chrome");
+            if (ua && ua !== liveUa) {
+                await context.setExtraHTTPHeaders({ "user-agent": ua });
+                const cdp = await context.newCDPSession(page);
+                await cdp.send("Network.setUserAgentOverride", { userAgent: ua });
+                if (debug)
+                    console.log(`De-headlessed network User-Agent → ${ua}`);
+            }
+        }
+        catch {
+            // best-effort; ignore
+        }
+    }
+    if (opened) {
+        await page.goto(targetUrl, { waitUntil: "domcontentloaded" });
+    }
+    return {
+        page,
+        browser,
+        opened,
+        async dispose() {
+            if (opened && options.close !== false) {
+                try {
+                    await page.close();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            try {
+                await browser.close();
+            }
+            catch {
+                // ignore
+            }
+            // Situation 3: a proxy only takes effect at launch, so a proxied run owns
+            // an ephemeral browser — fully stop it once the request completes, leaving
+            // a clean slate for the next (possibly differently-proxied) run.
+            if (managed && proxyApplied) {
+                try {
+                    const { closeBrowser } = await loadCdpManager();
+                    await closeBrowser(cdpPort);
+                    if (debug)
+                        console.log(`Stopped managed Chrome on :${cdpPort} (proxied run complete)`);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        },
+    };
+};

package/dist/src/capabilities/cookies.d.ts

@@ -1,4 +1,4 @@
-import { getCookies as realGetCookies, getPasswords as realGetPasswords, type CookieEntry } from "chrome-tools";
+import { type CookieEntry, getCookies as realGetCookies, getPasswords as realGetPasswords } from "chrome-tools";
 import type { Credentials, QueryOptions } from "../types.js";
 export declare const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36";
 /**
@@ -20,5 +20,11 @@ export declare function resolveCredentials(domain: string, options: QueryOptions
 /**
  * Resolves decrypted Chrome cookies for a domain. When `required` is false a
  * missing login yields an empty array instead of throwing.
+ *
+ * For required sites the two failure modes are reported distinctly:
+ *   - `getCookies` throws → Chrome's cookie store couldn't be read at all
+ *     (e.g. keychain access denied, missing/locked profile). → "No login found".
+ *   - it returns no rows → the store was read fine but holds no cookies for the
+ *     domain: the user simply isn't signed in there. → "No cookies found".
  */
 export declare function resolveCookies(domain: string, options: QueryOptions, required: boolean, providers?: CookieProviders): CookieEntry[];

package/dist/src/capabilities/cookies.js

@@ -1 +1,68 @@
-import{getCookies as e,getPasswords as r}from"chrome-tools";export const DEFAULT_USER_AGENT="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36";function o(e,r){return e.profilePath||r.PROFILE_PATH||r.CHROME_PROFILE_PATH||void 0}function n(e,r){return e.profile||r.PROFILE_NAME||void 0}export function resolveUserAgent(e,r=process.env){return e.userAgent||r.userAgent||r.USER_AGENT||DEFAULT_USER_AGENT}export function buildCookieString(e){return e.map(e=>`${e.name}=${e.value}`).join("; ")}export function resolveCredentials(e,t,s={}){const i=s.env??process.env,a=s.getPasswords??r,c=o(t,i),l=n(t,i);let p=a({chromeDir:c,profile:l,search:e});if(!p||0===p.length){const r=e.split(".");p=a({chromeDir:c,profile:l,search:r[r.length-2]||e})}if(!p||0===p.length)throw new Error(`No saved passwords found in Chrome for '${e}'`);const{username:u,password:f}=p[0];if(!u||!f)throw new Error(`Found credentials for '${e}' but username or password was empty`);return{username:u,password:f}}export function resolveCookies(r,t,s,i={}){const a=i.env??process.env,c=i.getCookies??e,l=o(t,a),p=n(t,a);let u=[];try{u=c({chromeDir:l,profile:p,domain:r,decrypt:!0})}catch{if(s)throw new Error("No login found in browser")}if((!u||0===u.length)&&s)throw new Error("No login found in browser");return u??[]}
+import { getCookies as realGetCookies, getPasswords as realGetPasswords, } from "chrome-tools";
+export const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36";
+function resolveChromeDir(options, env) {
+    return options.profilePath || env.PROFILE_PATH || env.CHROME_PROFILE_PATH || undefined;
+}
+function resolveProfile(options, env) {
+    return options.profile || env.PROFILE_NAME || undefined;
+}
+export function resolveUserAgent(options, env = process.env) {
+    return options.userAgent || env.userAgent || env.USER_AGENT || DEFAULT_USER_AGENT;
+}
+export function buildCookieString(cookies) {
+    return cookies.map((c) => `${c.name}=${c.value}`).join("; ");
+}
+/**
+ * Resolves saved Chrome credentials for a domain. Searches the full domain
+ * first, then falls back to the registrable name (e.g. "pseg" from "pseg.com").
+ */
+export function resolveCredentials(domain, options, providers = {}) {
+    const env = providers.env ?? process.env;
+    const getPasswords = providers.getPasswords ?? realGetPasswords;
+    const chromeDir = resolveChromeDir(options, env);
+    const profile = resolveProfile(options, env);
+    let credentials = getPasswords({ chromeDir, profile, search: domain });
+    if (!credentials || credentials.length === 0) {
+        const parts = domain.split(".");
+        const name = parts[parts.length - 2] || domain;
+        credentials = getPasswords({ chromeDir, profile, search: name });
+    }
+    if (!credentials || credentials.length === 0) {
+        throw new Error(`No saved passwords found in Chrome for '${domain}'`);
+    }
+    const { username, password } = credentials[0];
+    if (!username || !password) {
+        throw new Error(`Found credentials for '${domain}' but username or password was empty`);
+    }
+    return { username, password };
+}
+/**
+ * Resolves decrypted Chrome cookies for a domain. When `required` is false a
+ * missing login yields an empty array instead of throwing.
+ *
+ * For required sites the two failure modes are reported distinctly:
+ *   - `getCookies` throws → Chrome's cookie store couldn't be read at all
+ *     (e.g. keychain access denied, missing/locked profile). → "No login found".
+ *   - it returns no rows → the store was read fine but holds no cookies for the
+ *     domain: the user simply isn't signed in there. → "No cookies found".
+ */
+export function resolveCookies(domain, options, required, providers = {}) {
+    const env = providers.env ?? process.env;
+    const getCookies = providers.getCookies ?? realGetCookies;
+    const chromeDir = resolveChromeDir(options, env);
+    const profile = resolveProfile(options, env);
+    let cookies;
+    try {
+        cookies = getCookies({ chromeDir, profile, domain, decrypt: true });
+    }
+    catch (err) {
+        if (!required)
+            return [];
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`No login found in browser: could not read Chrome cookies for ${domain} (${detail})`);
+    }
+    if ((!cookies || cookies.length === 0) && required) {
+        throw new Error(`No cookies found in browser for ${domain}. Sign in to ${domain} in Chrome and try again.`);
+    }
+    return cookies ?? [];
+}