@cbxss/eoka 0.1.0-beta.4 → 0.1.0-beta.5

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.
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  Node.js SDK for eoka, a stealth Chrome automation sidecar.
4
4
 
5
5
  ```sh
6
- npm install @cbxss/eoka@next
6
+ npm install @cbxss/eoka@latest
7
7
  ```
8
8
 
9
9
  Requires Node.js 24.21+ (ESM only). Supported platforms: Linux x64/arm64 (glibc 2.35+), macOS x64/arm64, Windows x64.
@@ -59,6 +59,36 @@ if (challenge) {
59
59
 
60
60
  `page.solveTurnstile({ timeoutMs })` is a best-effort helper for interactive Cloudflare challenge pages. It finds the challenge frame, clicks the checkbox, and waits for the page to leave the challenge state. It is not a general CAPTCHA solver.
61
61
 
62
+ ### Automatic challenge handling
63
+
64
+ `Browser.launch({ autoSolveCloudflare: true })` (and `Browser.connect`) watches every tab and calls `solveTurnstile()` when a full-page Cloudflare challenge appears. It does not click Turnstile widgets embedded in normal forms.
65
+
66
+ ```js
67
+ const browser = await Browser.launch({ autoSolveCloudflare: true });
68
+ try {
69
+ const page = await browser.newPage("https://1337x.to/");
70
+ console.log(await page.title()); // Torrent Search Engine | 1337x.to
71
+ } finally {
72
+ await browser.close();
73
+ }
74
+ ```
75
+
76
+ Tune the watcher or observe it:
77
+
78
+ ```js
79
+ const browser = await Browser.launch({
80
+ autoSolveCloudflare: {
81
+ intervalMs: 500, // tab poll interval
82
+ timeoutMs: 45_000, // deadline per challenge
83
+ onChallenge: page => console.log("cloudflare challenge", page.id),
84
+ onSolved: page => console.log("cloudflare solved", page.id),
85
+ onError: (error, page) => console.warn("cloudflare", error, page?.id),
86
+ },
87
+ });
88
+ ```
89
+
90
+ The watcher polls; it is not an event hook. It stops on `browser.close()` and never keeps the Node process alive by itself.
91
+
62
92
  ## Screenshots and recording
63
93
 
64
94
  ```js
package/dist/browser.d.ts CHANGED
@@ -4,12 +4,15 @@ import { Operation } from './operations.js';
4
4
  import { Page, type PerformOptions } from './page.js';
5
5
  import { Recording } from './recording.js';
6
6
  import { type InstallProgress } from './browser-install.js';
7
+ import { type CloudflareOptions } from './cloudflare.js';
7
8
  export interface BrowserOptions {
8
9
  serverPath?: string;
9
10
  serverEnv?: NodeJS.ProcessEnv;
10
11
  signal?: AbortSignal;
11
12
  timeoutMs?: number;
12
13
  shutdownTimeoutMs?: number;
14
+ /** Watch every tab and click full-page Cloudflare challenge checkboxes. */
15
+ autoSolveCloudflare?: boolean | CloudflareOptions;
13
16
  }
14
17
  export interface LaunchOptions extends BrowserOptions {
15
18
  executablePath?: string;
package/dist/browser.js CHANGED
@@ -8,6 +8,7 @@ import { Page } from './page.js';
8
8
  import { Recording } from './recording.js';
9
9
  import { SidecarTransport } from './transport.js';
10
10
  import { installBrowser } from './browser-install.js';
11
+ import { CloudflareWatcher, resolveCloudflareOptions } from './cloudflare.js';
11
12
  import { resolveServerBinary } from './server-binary.js';
12
13
  function validateTimeout(value, name) {
13
14
  if (value !== undefined && (!Number.isFinite(value) || value <= 0 || value > 2_147_483_647)) {
@@ -192,6 +193,7 @@ export class Browser {
192
193
  #capabilities;
193
194
  #shutdownTimeoutMs;
194
195
  #closePromise;
196
+ #cloudflare;
195
197
  #pageOwners = new Set();
196
198
  #creationCleanupFailures = [];
197
199
  #runtimeCleanup;
@@ -296,7 +298,13 @@ export class Browser {
296
298
  throw new ProtocolError(`Managed browser version mismatch: expected ${expectedBrowserVersion}, received ${session.browserVersion}`, { requestState: 'acknowledged' });
297
299
  }
298
300
  checkAbort(options.signal, 'acknowledged');
299
- return new Browser(transport, session, options.shutdownTimeoutMs ?? 45_000, runtimeDir);
301
+ const browser = new Browser(transport, session, options.shutdownTimeoutMs ?? 45_000, runtimeDir);
302
+ const cloudflare = resolveCloudflareOptions(options.autoSolveCloudflare);
303
+ if (cloudflare !== undefined) {
304
+ browser.#cloudflare = new CloudflareWatcher(browser, cloudflare);
305
+ browser.#cloudflare.start();
306
+ }
307
+ return browser;
300
308
  }
301
309
  catch (primary) {
302
310
  try {
@@ -413,6 +421,7 @@ export class Browser {
413
421
  }
414
422
  close() {
415
423
  this.#closePromise ??= (async () => {
424
+ this.#cloudflare?.stop();
416
425
  this.#transport.quiesce();
417
426
  await Promise.all(this.#pageOwners);
418
427
  let transportFailure;
@@ -0,0 +1,45 @@
1
+ import type { CallOptions } from './client.js';
2
+ import type { Page } from './page.js';
3
+ /** Options for the browser-wide Cloudflare challenge watcher. */
4
+ export interface CloudflareOptions {
5
+ /** Poll interval in milliseconds. Defaults to 500. */
6
+ intervalMs?: number;
7
+ /** Deadline for each `solveTurnstile()` attempt. Defaults to 30000. */
8
+ timeoutMs?: number;
9
+ /** Called when a full-page challenge is detected, before the click. */
10
+ onChallenge?: (page: Page) => void;
11
+ /** Called after the challenge page has been left. */
12
+ onSolved?: (page: Page) => void;
13
+ /** Called for watcher or solve failures. A page is omitted when listing tabs fails. */
14
+ onError?: (error: unknown, page?: Page) => void;
15
+ }
16
+ export interface ResolvedCloudflareOptions {
17
+ intervalMs: number;
18
+ timeoutMs: number;
19
+ onChallenge?: (page: Page) => void;
20
+ onSolved?: (page: Page) => void;
21
+ onError?: (error: unknown, page?: Page) => void;
22
+ }
23
+ export interface CloudflareBrowser {
24
+ tabs(options?: CallOptions): Promise<readonly {
25
+ id: string;
26
+ }[]>;
27
+ page(id: string): Page;
28
+ }
29
+ /**
30
+ * Full-page Cloudflare challenge titles. A Turnstile widget embedded in a
31
+ * normal form has the same frame URL, so the title is the discriminator.
32
+ */
33
+ export declare function isCloudflareChallengeTitle(title: string): boolean;
34
+ export declare function resolveCloudflareOptions(value: boolean | CloudflareOptions | undefined): ResolvedCloudflareOptions | undefined;
35
+ /**
36
+ * Polls every tab for a full-page Cloudflare challenge and clicks its
37
+ * checkbox through `Page.solveTurnstile()`. The timer is unref'd, so it does
38
+ * not keep the Node process alive. `stop()` aborts an in-flight attempt.
39
+ */
40
+ export declare class CloudflareWatcher {
41
+ #private;
42
+ constructor(browser: CloudflareBrowser, options: ResolvedCloudflareOptions);
43
+ start(): void;
44
+ stop(): void;
45
+ }
@@ -0,0 +1,154 @@
1
+ import { ConfigurationError } from './errors.js';
2
+ const challengeTitle = /just a moment|attention required|checking your browser|verify you are human|please wait.*cloudflare/i;
3
+ /**
4
+ * Full-page Cloudflare challenge titles. A Turnstile widget embedded in a
5
+ * normal form has the same frame URL, so the title is the discriminator.
6
+ */
7
+ export function isCloudflareChallengeTitle(title) {
8
+ return challengeTitle.test(title);
9
+ }
10
+ export function resolveCloudflareOptions(value) {
11
+ if (value === undefined || value === false)
12
+ return undefined;
13
+ const options = value === true ? {} : value;
14
+ const intervalMs = options.intervalMs ?? 500;
15
+ const timeoutMs = options.timeoutMs ?? 30_000;
16
+ if (!Number.isFinite(intervalMs) || intervalMs < 100 || intervalMs > 60_000) {
17
+ throw new ConfigurationError('autoSolveCloudflare.intervalMs must be between 100 and 60000 milliseconds');
18
+ }
19
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
20
+ throw new ConfigurationError('autoSolveCloudflare.timeoutMs must be finite, positive and at most 2147483647 milliseconds');
21
+ }
22
+ for (const name of ['onChallenge', 'onSolved', 'onError']) {
23
+ if (options[name] !== undefined && typeof options[name] !== 'function') {
24
+ throw new ConfigurationError(`autoSolveCloudflare.${name} must be a function`);
25
+ }
26
+ }
27
+ const resolved = { intervalMs, timeoutMs };
28
+ if (options.onChallenge !== undefined)
29
+ resolved.onChallenge = options.onChallenge;
30
+ if (options.onSolved !== undefined)
31
+ resolved.onSolved = options.onSolved;
32
+ if (options.onError !== undefined)
33
+ resolved.onError = options.onError;
34
+ return resolved;
35
+ }
36
+ /**
37
+ * Polls every tab for a full-page Cloudflare challenge and clicks its
38
+ * checkbox through `Page.solveTurnstile()`. The timer is unref'd, so it does
39
+ * not keep the Node process alive. `stop()` aborts an in-flight attempt.
40
+ */
41
+ export class CloudflareWatcher {
42
+ #browser;
43
+ #options;
44
+ #controller = new AbortController();
45
+ #pages = new Map();
46
+ #solving = new Set();
47
+ #timer;
48
+ #running = false;
49
+ #stopped = false;
50
+ constructor(browser, options) {
51
+ this.#browser = browser;
52
+ this.#options = options;
53
+ }
54
+ start() {
55
+ if (this.#stopped || this.#timer !== undefined)
56
+ return;
57
+ this.#timer = setInterval(() => { void this.#tick(); }, this.#options.intervalMs);
58
+ this.#timer.unref();
59
+ void this.#tick();
60
+ }
61
+ stop() {
62
+ if (this.#stopped)
63
+ return;
64
+ this.#stopped = true;
65
+ this.#controller.abort();
66
+ if (this.#timer !== undefined) {
67
+ clearInterval(this.#timer);
68
+ this.#timer = undefined;
69
+ }
70
+ }
71
+ async #tick() {
72
+ if (this.#running || this.#stopped)
73
+ return;
74
+ this.#running = true;
75
+ try {
76
+ const tabs = await this.#browser.tabs({ signal: this.#controller.signal });
77
+ const ids = new Set(tabs.map(tab => tab.id));
78
+ for (const id of this.#pages.keys()) {
79
+ if (!ids.has(id)) {
80
+ this.#pages.delete(id);
81
+ this.#solving.delete(id);
82
+ }
83
+ }
84
+ for (const id of ids) {
85
+ if (this.#stopped)
86
+ break;
87
+ await this.#check(id);
88
+ }
89
+ }
90
+ catch (error) {
91
+ if (!this.#stopped)
92
+ this.#notifyError(error);
93
+ }
94
+ finally {
95
+ this.#running = false;
96
+ }
97
+ }
98
+ async #check(id) {
99
+ if (this.#solving.has(id))
100
+ return;
101
+ let page = this.#pages.get(id);
102
+ if (page === undefined) {
103
+ page = this.#browser.page(id);
104
+ this.#pages.set(id, page);
105
+ }
106
+ let title;
107
+ try {
108
+ title = await page.title({ signal: this.#controller.signal });
109
+ }
110
+ catch (error) {
111
+ if (!this.#stopped)
112
+ this.#notifyError(error, page);
113
+ return;
114
+ }
115
+ if (this.#stopped || !isCloudflareChallengeTitle(title))
116
+ return;
117
+ this.#solving.add(id);
118
+ this.#notify('onChallenge', page);
119
+ try {
120
+ await page.solveTurnstile({ timeoutMs: this.#options.timeoutMs, signal: this.#controller.signal });
121
+ if (!this.#stopped)
122
+ this.#notify('onSolved', page);
123
+ }
124
+ catch (error) {
125
+ if (!this.#stopped)
126
+ this.#notifyError(error, page);
127
+ }
128
+ finally {
129
+ this.#solving.delete(id);
130
+ }
131
+ }
132
+ #notify(name, page) {
133
+ const callback = this.#options[name];
134
+ if (callback === undefined)
135
+ return;
136
+ try {
137
+ callback(page);
138
+ }
139
+ catch (error) {
140
+ this.#notifyError(error, page);
141
+ }
142
+ }
143
+ #notifyError(error, page) {
144
+ const callback = this.#options.onError;
145
+ if (callback === undefined)
146
+ return;
147
+ try {
148
+ callback(error, page);
149
+ }
150
+ catch {
151
+ // A failing observer must not stop the watcher.
152
+ }
153
+ }
154
+ }
package/dist/index.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  export { Browser } from "./browser.js";
2
2
  export type { BrowserOptions, LaunchOptions, ConnectOptions } from "./browser.js";
3
+ export type { CloudflareOptions } from "./cloudflare.js";
3
4
  export { installBrowser } from "./browser-install.js";
4
5
  export type { InstallBrowserOptions, InstallProgress, BrowserInstallation } from "./browser-install.js";
5
6
  export { InstallationError } from "./install-errors.js";
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "sdkVersion": "0.1.0-beta.4",
3
+ "sdkVersion": "0.1.0-beta.5",
4
4
  "installerVersion": "3.2.4",
5
5
  "server": {
6
6
  "version": "0.6.2",
@@ -8,7 +8,7 @@
8
8
  "platforms": {
9
9
  "linux-x64-gnu": {
10
10
  "packageName": "@cbxss/eoka-server-linux-x64-gnu",
11
- "packageVersion": "0.1.0-beta.4",
11
+ "packageVersion": "0.1.0-beta.5",
12
12
  "target": "x86_64-unknown-linux-gnu",
13
13
  "asset": "eoka-server-linux-amd64",
14
14
  "executablePath": "bin/eoka-server",
@@ -19,7 +19,7 @@
19
19
  },
20
20
  "linux-arm64-gnu": {
21
21
  "packageName": "@cbxss/eoka-server-linux-arm64-gnu",
22
- "packageVersion": "0.1.0-beta.4",
22
+ "packageVersion": "0.1.0-beta.5",
23
23
  "target": "aarch64-unknown-linux-gnu",
24
24
  "asset": "eoka-server-linux-arm64",
25
25
  "executablePath": "bin/eoka-server",
@@ -30,7 +30,7 @@
30
30
  },
31
31
  "darwin-x64": {
32
32
  "packageName": "@cbxss/eoka-server-darwin-x64",
33
- "packageVersion": "0.1.0-beta.4",
33
+ "packageVersion": "0.1.0-beta.5",
34
34
  "target": "x86_64-apple-darwin",
35
35
  "asset": "eoka-server-darwin-amd64",
36
36
  "executablePath": "bin/eoka-server",
@@ -41,7 +41,7 @@
41
41
  },
42
42
  "darwin-arm64": {
43
43
  "packageName": "@cbxss/eoka-server-darwin-arm64",
44
- "packageVersion": "0.1.0-beta.4",
44
+ "packageVersion": "0.1.0-beta.5",
45
45
  "target": "aarch64-apple-darwin",
46
46
  "asset": "eoka-server-darwin-arm64",
47
47
  "executablePath": "bin/eoka-server",
@@ -52,11 +52,11 @@
52
52
  },
53
53
  "win32-x64": {
54
54
  "packageName": "@cbxss/eoka-server-win32-x64",
55
- "packageVersion": "0.1.0-beta.4",
55
+ "packageVersion": "0.1.0-beta.5",
56
56
  "target": "x86_64-pc-windows-msvc",
57
57
  "asset": "eoka-server-windows-amd64.exe",
58
58
  "executablePath": "bin/eoka-server.exe",
59
- "sha256": "f153941879b49f905278628947f330605cef037a3201b93ac0d7fe467dbbc8c7",
59
+ "sha256": "b78d479a72de095041091c4017126c1b8b9edf6ed5106e26ba10cb53e86e238c",
60
60
  "size": 14304256,
61
61
  "minimumGlibc": null,
62
62
  "development": false
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cbxss/eoka",
3
- "version": "0.1.0-beta.4",
3
+ "version": "0.1.0-beta.5",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Node.js SDK with pinned Chrome installation and verified eoka sidecar resolution",
@@ -58,11 +58,11 @@
58
58
  "typescript": "5.9.3"
59
59
  },
60
60
  "optionalDependencies": {
61
- "@cbxss/eoka-server-linux-x64-gnu": "0.1.0-beta.4",
62
- "@cbxss/eoka-server-linux-arm64-gnu": "0.1.0-beta.4",
63
- "@cbxss/eoka-server-darwin-x64": "0.1.0-beta.4",
64
- "@cbxss/eoka-server-darwin-arm64": "0.1.0-beta.4",
65
- "@cbxss/eoka-server-win32-x64": "0.1.0-beta.4"
61
+ "@cbxss/eoka-server-linux-x64-gnu": "0.1.0-beta.5",
62
+ "@cbxss/eoka-server-linux-arm64-gnu": "0.1.0-beta.5",
63
+ "@cbxss/eoka-server-darwin-x64": "0.1.0-beta.5",
64
+ "@cbxss/eoka-server-darwin-arm64": "0.1.0-beta.5",
65
+ "@cbxss/eoka-server-win32-x64": "0.1.0-beta.5"
66
66
  },
67
67
  "repository": {
68
68
  "type": "git",