@generativereality/browser-automation 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "browser-automation",
3
3
  "description": "Daemonless, per-tab-isolated browser automation for Claude Code via the `browser-automation` CLI. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
4
- "version": "0.3.0",
4
+ "version": "0.3.2",
5
5
  "author": {
6
6
  "name": "generativereality"
7
7
  },
package/README.md CHANGED
@@ -95,6 +95,7 @@ browser-automation bind -s bank -m nordnet # …or adopt it into a session
95
95
  | `read (-s\|-m\|-t) [selector]` | Print page text (or a CSS selector's text) |
96
96
  | `eval (-s\|-m\|-t) <js>` | Evaluate a JS expression in the tab (escape hatch) |
97
97
  | `download (-s\|-m\|-t) (--click <ref>\|--url <href>)` | Capture a file/CSV download, wait for completion, print the path |
98
+ | `network (-s\|-m\|-t) [--reload\|--click\|--nav] [--filter --headers --body]` | Capture network requests (find the API, headers, response bodies) |
98
99
  | `close (-s\|-m\|-t) [--tab]` | Forget the session (tab stays open); `--tab` also closes the browser tab |
99
100
 
100
101
  ## How refs work
package/dist/index.js CHANGED
@@ -7,7 +7,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, s
7
7
  import { spawnSync } from "node:child_process";
8
8
  import { fileURLToPath } from "node:url";
9
9
  //#region package.json
10
- var version = "0.3.0";
10
+ var version = "0.3.2";
11
11
  var description = "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.";
12
12
  //#endregion
13
13
  //#region src/core/session.ts
@@ -697,6 +697,143 @@ const downloadCommand = define({
697
697
  }
698
698
  });
699
699
  //#endregion
700
+ //#region src/core/network.ts
701
+ const INTERESTING = new Set([
702
+ "XHR",
703
+ "Fetch",
704
+ "Document",
705
+ "WebSocket",
706
+ "EventSource"
707
+ ]);
708
+ async function captureNetwork(targetId, opts) {
709
+ const { durationMs = 6e3, filter, all = false, wantBody = false } = opts;
710
+ const wsUrl = await targetWsUrl(targetId);
711
+ if (!wsUrl) throw new TargetGoneError(targetId);
712
+ const s = await connect(wsUrl);
713
+ try {
714
+ try {
715
+ await s.send("Network.enable", {}, 8e3);
716
+ } catch {
717
+ throw new Error("Network.enable stalled — the page renderer is busy. Let the page finish loading and retry, and prefer --click over --reload on heavy SPAs.");
718
+ }
719
+ const byId = /* @__PURE__ */ new Map();
720
+ s.on("Network.requestWillBeSent", (p) => {
721
+ byId.set(p.requestId, {
722
+ requestId: p.requestId,
723
+ url: p.request?.url,
724
+ method: p.request?.method,
725
+ type: p.type,
726
+ requestHeaders: p.request?.headers,
727
+ postData: p.request?.postData
728
+ });
729
+ });
730
+ s.on("Network.responseReceived", (p) => {
731
+ const e = byId.get(p.requestId);
732
+ if (e) {
733
+ e.status = p.response?.status;
734
+ e.mimeType = p.response?.mimeType;
735
+ e.responseHeaders = p.response?.headers;
736
+ if (p.type) e.type = p.type;
737
+ }
738
+ });
739
+ if (opts.reload) {
740
+ await s.send("Page.enable");
741
+ await s.send("Page.reload", {});
742
+ } else if (opts.gotoUrl) {
743
+ await s.send("Page.enable");
744
+ await s.send("Page.navigate", { url: opts.gotoUrl });
745
+ } else if (opts.clickRef) await evaluate(targetId, clickExpr(opts.clickRef), { userGesture: true });
746
+ await new Promise((r) => setTimeout(r, durationMs));
747
+ let entries = [...byId.values()].filter((e) => e.url && !e.url.startsWith("data:"));
748
+ if (!all) entries = entries.filter((e) => INTERESTING.has(e.type));
749
+ if (filter) {
750
+ const f = filter.toLowerCase();
751
+ entries = entries.filter((e) => e.url.toLowerCase().includes(f));
752
+ }
753
+ if (wantBody) for (const e of entries) try {
754
+ const b = await s.send("Network.getResponseBody", { requestId: e.requestId });
755
+ e.body = b.base64Encoded ? Buffer.from(b.body, "base64").toString("utf8") : b.body;
756
+ } catch {}
757
+ return entries;
758
+ } finally {
759
+ s.close();
760
+ }
761
+ }
762
+ //#endregion
763
+ //#region src/commands/network.ts
764
+ const networkCommand = define({
765
+ name: "network",
766
+ description: "Capture network requests in a tab (find the API behind a page, headers, bodies)",
767
+ args: {
768
+ ...targetArgs,
769
+ filter: {
770
+ type: "string",
771
+ description: "Only show requests whose URL contains this substring"
772
+ },
773
+ duration: {
774
+ type: "number",
775
+ description: "Capture window in ms (default 6000)"
776
+ },
777
+ reload: {
778
+ type: "boolean",
779
+ description: "Reload the page to capture its requests"
780
+ },
781
+ click: {
782
+ type: "string",
783
+ description: "Click this ref to trigger, then capture"
784
+ },
785
+ nav: {
786
+ type: "string",
787
+ description: "Navigate to this URL to trigger, then capture"
788
+ },
789
+ all: {
790
+ type: "boolean",
791
+ description: "Include all resource types (default: XHR/Fetch/Document/WS only)"
792
+ },
793
+ body: {
794
+ type: "boolean",
795
+ description: "Fetch response bodies for the shown requests"
796
+ },
797
+ headers: {
798
+ type: "boolean",
799
+ description: "Show request + response headers for the shown requests"
800
+ },
801
+ json: {
802
+ type: "boolean",
803
+ description: "Output raw JSON"
804
+ }
805
+ },
806
+ async run(ctx) {
807
+ const click = ctx.values.click;
808
+ if (click && !isValidRef(click)) {
809
+ consola.error("--click expects a ref like e42");
810
+ process.exit(1);
811
+ }
812
+ const entries = await captureNetwork(await resolveExistingTargetId(targetOpts(ctx.values)), {
813
+ durationMs: ctx.values.duration ?? 6e3,
814
+ filter: ctx.values.filter,
815
+ all: ctx.values.all,
816
+ wantBody: ctx.values.body || void 0,
817
+ reload: ctx.values.reload,
818
+ clickRef: click,
819
+ gotoUrl: ctx.values.nav ? normalizeUrl(ctx.values.nav) : void 0
820
+ });
821
+ if (ctx.values.json) {
822
+ process.stdout.write(JSON.stringify(entries, null, 2) + "\n");
823
+ return;
824
+ }
825
+ consola.log(`# ${entries.length} requests`);
826
+ for (const e of entries) {
827
+ consola.log(`${(e.method ?? "").padEnd(5)} ${String(e.status ?? "—").padEnd(4)} ${(e.type ?? "").padEnd(9)} ${e.url.slice(0, 100)}`);
828
+ if (ctx.values.headers) {
829
+ if (e.postData) consola.log(` ↑ body: ${e.postData.slice(0, 200)}`);
830
+ for (const [k, v] of Object.entries(e.requestHeaders ?? {})) if (/^(authorization|cookie|x-|content-type)/i.test(k)) consola.log(` ↑ ${k}: ${String(v).slice(0, 120)}`);
831
+ }
832
+ if (ctx.values.body && e.body) consola.log(` ↓ ${e.body.replace(/\s+/g, " ").slice(0, 300)}`);
833
+ }
834
+ }
835
+ });
836
+ //#endregion
700
837
  //#region src/commands/list.ts
701
838
  const listCommand = define({
702
839
  name: "list",
@@ -886,6 +1023,7 @@ const subCommands = new Map([
886
1023
  ["read", readCommand],
887
1024
  ["eval", evalCommand],
888
1025
  ["download", downloadCommand],
1026
+ ["network", networkCommand],
889
1027
  ["list", listCommand],
890
1028
  ["ls", listCommand],
891
1029
  ["close", closeCommand],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -83,6 +83,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
83
83
  | Read page text (or a selector) | `browser-automation read -m op.fi ['.balance']` |
84
84
  | Evaluate JS in the tab (escape hatch) | `browser-automation eval -m op.fi 'document.title'` |
85
85
  | Download a file / CSV export | `browser-automation download -m bank --click e42` (or `--url <href>`) |
86
+ | Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
86
87
  | Forget a session (tab stays open) | `browser-automation close -s work` |
87
88
  | Forget **and** close the browser tab | `browser-automation close -s work --tab` |
88
89
 
@@ -151,6 +152,23 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
151
152
  setups, start Chrome manually with `--remote-debugging-port=9223
152
153
  --user-data-dir="<profile>"`.
153
154
 
155
+ ## Network insights — find the API behind a page
156
+
157
+ `network` captures requests during a window (and an optional trigger), so you
158
+ can discover the JSON API a dashboard calls, capture the auth headers it uses,
159
+ and read response bodies — then scrape via that API instead of the DOM (more
160
+ robust). Triggers: `--reload`, `--click <ref>`, `--nav <url>`, or passive.
161
+
162
+ ```bash
163
+ browser-automation network -m bank --reload --filter api --headers --body
164
+ browser-automation network -m app --click e12 --filter graphql --body
165
+ ```
166
+
167
+ `--headers` surfaces `authorization` / `cookie` / `x-*` / `content-type` (e.g.
168
+ Revolut's `x-registered-identity` / `x-device-id` for statement replay).
169
+ **Caveat:** `--reload` on a *bank* tab can re-trigger its login challenge — for
170
+ banks prefer a `--click` on an in-app element that fetches data, not a reload.
171
+
154
172
  ## Escape hatch — raw per-page CDP for pure scraping
155
173
 
156
174
  When you just need to read a value out of a specific tab (no clicks), a raw