browser-cdp 0.6.1 → 0.6.4

package/README.md

@@ -37,6 +37,23 @@ browser-cdp pick '<message>'
 # Stream browser console output (network errors, exceptions, logs)
 browser-cdp console [--duration=SECONDS]
 
+# Stream network requests/responses
+browser-cdp network [--filter=PATTERN] [--json] [--errors] [--duration=SECONDS]
+
+# Manage cookies (export/import/clear)
+browser-cdp cookies export [--path=FILE]
+browser-cdp cookies import <file>
+browser-cdp cookies clear
+
+# Manage localStorage/sessionStorage
+browser-cdp storage get <key>
+browser-cdp storage set <key> <value>
+browser-cdp storage list
+browser-cdp storage clear
+browser-cdp storage export [--path=FILE]
+browser-cdp storage import <file>
+# Add --session for sessionStorage instead of localStorage
+
 # Show page performance metrics
 browser-cdp insights [--json]
 
@@ -89,6 +106,46 @@ browser-cdp console
 # Stream console for 10 seconds
 browser-cdp console --duration=10
 
+# Stream network traffic
+browser-cdp network
+# Then navigate to see requests
+
+# Filter to API calls only
+browser-cdp network --filter=api
+
+# Only show failed requests (4xx/5xx)
+browser-cdp network --errors
+
+# JSON output for parsing
+browser-cdp network --json --duration=5 | jq '.url'
+
+# Export cookies to JSON file
+browser-cdp cookies export
+# Returns: cookies.json with all cookies
+
+# Export to custom file
+browser-cdp cookies export --path session.json
+
+# Import cookies from file
+browser-cdp cookies import session.json
+
+# Clear all cookies
+browser-cdp cookies clear
+
+# Get/set localStorage values
+browser-cdp storage get authToken
+browser-cdp storage set theme dark
+
+# List all storage keys
+browser-cdp storage list
+
+# Export/import storage
+browser-cdp storage export
+browser-cdp storage import storage.json
+
+# Work with sessionStorage
+browser-cdp storage get tempData --session
+
 # Get page performance insights
 browser-cdp insights
 # Returns: TTFB, First Paint, FCP, DOM loaded, resources, memory
@@ -103,6 +160,107 @@ browser-cdp lighthouse
 browser-cdp close
 ```
 
+## Cookies Command
+
+The `cookies` command provides session persistence for authenticated workflows:
+
+### Export Cookies
+
+Save your browser cookies to a JSON file for later use:
+
+```bash
+browser-cdp cookies export                    # Saves to cookies.json
+browser-cdp cookies export --path auth.json   # Save to specific file
+```
+
+Output format:
+```json
+[
+  {
+    "name": "session_id",
+    "value": "abc123...",
+    "domain": "example.com",
+    "path": "/",
+    "httpOnly": true,
+    "secure": true,
+    "sameSite": "Strict",
+    "expires": 1735689600
+  }
+]
+```
+
+### Import Cookies
+
+Load previously exported cookies into the browser:
+
+```bash
+browser-cdp cookies import auth.json
+```
+
+Useful for:
+- Resuming authenticated sessions across browser restarts
+- Sharing sessions across team members
+- Preserving login state for automation workflows
+
+### Clear Cookies
+
+Delete all cookies from the browser:
+
+```bash
+browser-cdp cookies clear
+```
+
+## Storage Command
+
+The `storage` command provides localStorage and sessionStorage management:
+
+### Get/Set Values
+
+```bash
+browser-cdp storage get authToken                 # Get from localStorage
+browser-cdp storage set theme dark                # Set in localStorage
+browser-cdp storage set tempData "session" --session  # Set in sessionStorage
+```
+
+### List Keys
+
+```bash
+browser-cdp storage list                          # List localStorage keys
+browser-cdp storage list --session                # List sessionStorage keys
+```
+
+### Export/Import
+
+Save storage to a JSON file for backup or restore:
+
+```bash
+browser-cdp storage export                        # Saves to storage.json
+browser-cdp storage export --path app-state.json  # Save to specific file
+browser-cdp storage import app-state.json         # Restore from file
+```
+
+Output format:
+```json
+{
+  "authToken": "eyJhbGciOiJIUzI1NiIs...",
+  "theme": "dark"
+}
+```
+
+### Clear Storage
+
+```bash
+browser-cdp storage clear                         # Clear localStorage
+browser-cdp storage clear --session               # Clear sessionStorage
+```
+
+### localStorage vs sessionStorage
+
+| Storage Type | Lifetime | Scope | Flag |
+|--------------|----------|-------|------|
+| localStorage | Permanent | Per origin | (default) |
+| sessionStorage | Tab session | Per tab | `--session` |
+
 ## Pre-started Browser
 
 If you already have a browser running with CDP enabled, the CLI will connect to it:

package/cli.js

@@ -20,6 +20,9 @@ const commands = {
   pdf: "./src/pdf.js",
   pick: "./src/pick.js",
   console: "./src/console.js",
+  network: "./src/network.js",
+  cookies: "./src/cookies.js",
+  storage: "./src/storage.js",
   insights: "./src/insights.js",
   lighthouse: "./src/lighthouse.js",
 };
@@ -39,6 +42,9 @@ function printUsage() {
   console.log("  pdf                 Export current page as PDF");
   console.log("  pick '<message>'    Interactive element picker");
   console.log("  console             Stream browser console output");
+  console.log("  network             Stream network requests/responses");
+  console.log("  cookies             Export/import/clear browser cookies");
+  console.log("  storage             Manage localStorage/sessionStorage");
   console.log("  insights            Show page performance metrics");
   console.log("  lighthouse          Run Lighthouse audit");
   console.log("");
@@ -53,6 +59,8 @@ function printUsage() {
   console.log("  browser-cdp eval 'document.title'");
   console.log("  browser-cdp dom > page.html");
   console.log("  browser-cdp console --duration=10");
+  console.log("  browser-cdp network --filter=api");
+  console.log("  browser-cdp cookies export --path session.json");
   console.log("  browser-cdp insights --json");
   process.exit(0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-cdp",
-  "version": "0.6.1",
+  "version": "0.6.4",
   "description": "Browser automation via Chrome DevTools Protocol - control Chrome, Brave, Edge with real browser profiles",
   "type": "module",
   "bin": {

package/src/cookies.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { chromium } from "playwright";
+import { DEFAULT_PORT, getActivePage } from "./utils.js";
+
+const args = process.argv.slice(2);
+const subcommand = args[0];
+const showHelp = args.includes("--help") || args.includes("-h");
+
+function printUsage() {
+  console.log("Usage: cookies <subcommand> [options]");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  export                Export cookies to JSON file");
+  console.log("  import <file>         Import cookies from JSON file");
+  console.log("  clear                 Clear all cookies from browser");
+  console.log("");
+  console.log("Options:");
+  console.log("  --path <file>         Output file path for export (default: cookies.json)");
+  console.log("");
+  console.log("Examples:");
+  console.log("  cookies export");
+  console.log("  cookies export --path session.json");
+  console.log("  cookies import session.json");
+  console.log("  cookies clear");
+  process.exit(0);
+}
+
+if (!subcommand || showHelp) {
+  printUsage();
+}
+
+if (!["export", "import", "clear"].includes(subcommand)) {
+  console.error(`Unknown subcommand: ${subcommand}`);
+  console.log("Available: export, import, clear");
+  process.exit(1);
+}
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0];
+
+if (!context) {
+  console.error("No browser context found");
+  process.exit(1);
+}
+
+const pages = context.pages();
+const page = getActivePage(pages);
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+const cdp = await page.context().newCDPSession(page);
+
+if (subcommand === "export") {
+  const pathIdx = args.findIndex((a) => a === "--path");
+  const outputFile = pathIdx !== -1 ? args[pathIdx + 1] : "cookies.json";
+
+  const { cookies } = await cdp.send("Network.getCookies");
+  writeFileSync(outputFile, JSON.stringify(cookies, null, 2));
+  console.log(`Exported ${cookies.length} cookie(s) to ${outputFile}`);
+} else if (subcommand === "import") {
+  const importFile = args[1];
+
+  if (!importFile) {
+    console.error("Error: import requires a file path");
+    process.exit(1);
+  }
+
+  const cookies = JSON.parse(readFileSync(importFile, "utf8"));
+
+  if (!Array.isArray(cookies)) {
+    console.error("Error: Cookie file must contain a JSON array");
+    process.exit(1);
+  }
+
+  await cdp.send("Network.setCookies", { cookies });
+  console.log(`Imported ${cookies.length} cookie(s) from ${importFile}`);
+} else if (subcommand === "clear") {
+  await cdp.send("Network.clearBrowserCookies");
+  console.log("Cleared all cookies");
+}
+
+await browser.close();

package/src/network.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+import { chromium } from "playwright";
+import { DEFAULT_PORT, getActivePage, formatTime, resetColor } from "./utils.js";
+
+const args = process.argv.slice(2);
+const filterPattern = args.find((a) => a.startsWith("--filter="))?.split("=")[1];
+const jsonOutput = args.includes("--json");
+const errorsOnly = args.includes("--errors");
+const duration = args.find((a) => a.startsWith("--duration="));
+const durationMs = duration ? parseInt(duration.split("=")[1]) * 1000 : null;
+const showHelp = args.includes("--help") || args.includes("-h");
+
+if (showHelp) {
+  console.log("Usage: network.js [options]");
+  console.log("\nStream network requests and responses in real-time.");
+  console.log("\nOptions:");
+  console.log("  --filter=PATTERN  Filter URLs by regex pattern");
+  console.log("  --json            Output as JSON for piping");
+  console.log("  --errors          Only show failed requests (4xx/5xx)");
+  console.log("  --duration=N      Stop after N seconds (default: run until Ctrl+C)");
+  console.log("\nExamples:");
+  console.log("  network.js                      # Stream all network traffic");
+  console.log("  network.js --filter=api         # Only show URLs containing 'api'");
+  console.log("  network.js --errors             # Only show failed requests");
+  console.log("  network.js --json               # JSON output for jq/parsing");
+  console.log("  network.js --duration=10        # Capture for 10 seconds");
+  process.exit(0);
+}
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0];
+
+if (!context) {
+  console.error("No browser context found");
+  process.exit(1);
+}
+
+const pages = context.pages();
+const page = getActivePage(pages);
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+console.error(`Connected to: ${page.url()}`);
+
+const cdp = await page.context().newCDPSession(page);
+await cdp.send("Network.enable");
+
+const requests = new Map();
+
+const statusColors = {
+  success: "\x1b[32m", // green for 2xx
+  redirect: "\x1b[33m", // yellow for 3xx
+  error: "\x1b[31m", // red for 4xx/5xx
+  request: "\x1b[36m", // cyan for requests
+};
+
+function matchesFilter(url) {
+  if (!filterPattern) return true;
+  try {
+    return new RegExp(filterPattern).test(url);
+  } catch {
+    return url.includes(filterPattern);
+  }
+}
+
+cdp.on("Network.requestWillBeSent", ({ requestId, request, timestamp }) => {
+  requests.set(requestId, { method: request.method, url: request.url, timestamp });
+
+  if (!matchesFilter(request.url)) return;
+  if (errorsOnly) return;
+
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify({
+        type: "request",
+        timestamp: new Date(timestamp * 1000).toISOString(),
+        method: request.method,
+        url: request.url,
+        requestId,
+      })
+    );
+  } else {
+    console.log(`${statusColors.request}[${formatTime()}] → ${request.method} ${request.url}${resetColor}`);
+  }
+});
+
+cdp.on("Network.responseReceived", ({ requestId, response, timestamp, type }) => {
+  const req = requests.get(requestId);
+
+  if (!matchesFilter(response.url)) return;
+  if (errorsOnly && response.status < 400) return;
+
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify({
+        type: "response",
+        timestamp: new Date(timestamp * 1000).toISOString(),
+        status: response.status,
+        statusText: response.statusText,
+        url: response.url,
+        mimeType: response.mimeType,
+        resourceType: type,
+        requestId,
+        method: req?.method,
+      })
+    );
+  } else {
+    let color = statusColors.success;
+    if (response.status >= 400) {
+      color = statusColors.error;
+    } else if (response.status >= 300) {
+      color = statusColors.redirect;
+    }
+
+    const method = req ? `${req.method} ` : "";
+    console.log(`${color}[${formatTime()}] ← ${response.status} ${method}${response.url}${resetColor}`);
+  }
+});
+
+cdp.on("Network.loadingFailed", ({ requestId, errorText, blockedReason, canceled }) => {
+  const req = requests.get(requestId);
+
+  if (req && !matchesFilter(req.url)) return;
+
+  if (jsonOutput) {
+    console.log(
+      JSON.stringify({
+        type: "failed",
+        timestamp: new Date().toISOString(),
+        url: req?.url,
+        method: req?.method,
+        error: errorText,
+        blockedReason,
+        canceled,
+        requestId,
+      })
+    );
+  } else {
+    const reason = blockedReason ? ` (${blockedReason})` : "";
+    const canceledStr = canceled ? " [CANCELED]" : "";
+    console.log(
+      `${statusColors.error}[${formatTime()}] ✗ ${errorText}${reason}${canceledStr} - ${req?.url || "unknown"}${resetColor}`
+    );
+  }
+
+  if (requestId) {
+    requests.delete(requestId);
+  }
+});
+
+console.error(`Listening for network activity... (Ctrl+C to stop)`);
+
+if (durationMs) {
+  await new Promise((r) => setTimeout(r, durationMs));
+  await browser.close();
+} else {
+  // Keep running until interrupted
+  process.on("SIGINT", async () => {
+    console.error("\nStopping...");
+    await browser.close();
+    process.exit(0);
+  });
+
+  // Keep the process alive
+  await new Promise(() => {});
+}

package/src/storage.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { chromium } from "playwright";
+import { DEFAULT_PORT, getActivePage } from "./utils.js";
+
+const args = process.argv.slice(2);
+const subcommand = args[0];
+const showHelp = args.includes("--help") || args.includes("-h");
+const useSessionStorage = args.includes("--session");
+const storageType = useSessionStorage ? "sessionStorage" : "localStorage";
+
+function printUsage() {
+  console.log("Usage: storage <subcommand> [options]");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  get <key>             Get value for key");
+  console.log("  set <key> <value>     Set key to value");
+  console.log("  list                  List all keys");
+  console.log("  clear                 Clear all storage");
+  console.log("  export                Export storage to JSON file");
+  console.log("  import <file>         Import storage from JSON file");
+  console.log("");
+  console.log("Options:");
+  console.log("  --session             Use sessionStorage instead of localStorage");
+  console.log("  --path <file>         Output file path for export (default: storage.json)");
+  console.log("");
+  console.log("Examples:");
+  console.log("  storage get token");
+  console.log("  storage set theme dark");
+  console.log("  storage list");
+  console.log("  storage export");
+  console.log("  storage export --path session.json --session");
+  console.log("  storage import session.json");
+  console.log("  storage clear");
+  process.exit(0);
+}
+
+if (!subcommand || showHelp) {
+  printUsage();
+}
+
+if (!["get", "set", "list", "clear", "export", "import"].includes(subcommand)) {
+  console.error(`Unknown subcommand: ${subcommand}`);
+  console.log("Available: get, set, list, clear, export, import");
+  process.exit(1);
+}
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0];
+
+if (!context) {
+  console.error("No browser context found");
+  process.exit(1);
+}
+
+const pages = context.pages();
+const page = getActivePage(pages);
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+const positionalArgs = args.filter((a) => !a.startsWith("--"));
+
+if (subcommand === "get") {
+  const key = positionalArgs[1];
+
+  if (!key) {
+    console.error("Error: get requires a key");
+    process.exit(1);
+  }
+
+  const result = await page.evaluate(
+    ([storageType, key]) => window[storageType].getItem(key),
+    [storageType, key]
+  );
+
+  if (result === null) {
+    console.error(`Key "${key}" not found in ${storageType}`);
+    process.exit(1);
+  }
+
+  console.log(result);
+} else if (subcommand === "set") {
+  const key = positionalArgs[1];
+  const value = positionalArgs.slice(2).join(" ");
+
+  if (!key || value === "") {
+    console.error("Error: set requires <key> <value>");
+    process.exit(1);
+  }
+
+  await page.evaluate(
+    ([storageType, key, value]) => window[storageType].setItem(key, value),
+    [storageType, key, value]
+  );
+
+  console.log(`Set ${key} in ${storageType}`);
+} else if (subcommand === "list") {
+  const keys = await page.evaluate(
+    (storageType) => Object.keys(window[storageType]),
+    storageType
+  );
+
+  if (keys.length === 0) {
+    console.log(`No keys found in ${storageType}`);
+  } else {
+    console.log(`Keys in ${storageType}:`);
+    keys.forEach((key) => console.log(`  ${key}`));
+  }
+} else if (subcommand === "clear") {
+  await page.evaluate((storageType) => window[storageType].clear(), storageType);
+
+  console.log(`Cleared all ${storageType}`);
+} else if (subcommand === "export") {
+  const pathIdx = args.findIndex((a) => a === "--path");
+  const outputFile = pathIdx !== -1 ? args[pathIdx + 1] : "storage.json";
+
+  const data = await page.evaluate((storageType) => {
+    const storage = window[storageType];
+    const result = {};
+    for (let i = 0; i < storage.length; i++) {
+      const key = storage.key(i);
+      result[key] = storage.getItem(key);
+    }
+    return result;
+  }, storageType);
+
+  writeFileSync(outputFile, JSON.stringify(data, null, 2));
+  const count = Object.keys(data).length;
+  console.log(`Exported ${count} item(s) from ${storageType} to ${outputFile}`);
+} else if (subcommand === "import") {
+  const importFile = positionalArgs[1];
+
+  if (!importFile) {
+    console.error("Error: import requires a file path");
+    process.exit(1);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(readFileSync(importFile, "utf8"));
+  } catch (error) {
+    console.error(`Error reading file: ${error.message}`);
+    process.exit(1);
+  }
+
+  if (typeof data !== "object" || Array.isArray(data)) {
+    console.error("Error: Storage file must contain a JSON object");
+    process.exit(1);
+  }
+
+  await page.evaluate(
+    ([storageType, data]) => {
+      const storage = window[storageType];
+      for (const [key, value] of Object.entries(data)) {
+        storage.setItem(key, value);
+      }
+    },
+    [storageType, data]
+  );
+
+  const count = Object.keys(data).length;
+  console.log(`Imported ${count} item(s) to ${storageType} from ${importFile}`);
+}
+
+await browser.close();