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

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
@@ -36,7 +36,7 @@ await page.click("button[type=submit]", {
36
36
 
37
37
  await page.waitForText("Welcome");
38
38
  const heading = await page.getText("h1");
39
- const count = await page.evaluate("document.querySelectorAll('li').length");
39
+ const count = await page.evaluate("()=>document.querySelectorAll('li').length");
40
40
  ```
41
41
 
42
42
  String targets are CSS selectors. An action resolves only after its result is verified. `click`, `type`, `pressKey`, `submit` and `drag` need an `expect` that describes the result.
@@ -57,11 +57,11 @@ if (challenge) {
57
57
  }
58
58
  ```
59
59
 
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.
60
+ `page.solveTurnstile({ timeoutMs })` is a best-effort helper for interactive Cloudflare challenge pages. The server finds the challenge frame, clicks the checkbox, and waits for the page to leave the challenge state, then resolves with `{ clicks, elapsedMs }` (zero clicks on a normal page). It is not a general CAPTCHA solver.
61
61
 
62
62
  ### Automatic challenge handling
63
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.
64
+ `Browser.launch({ autoSolveCloudflare: true })` (and `Browser.connect`) has the server watch every tab and solve full-page Cloudflare challenges as they appear. It does not click Turnstile widgets embedded in normal forms. The Go SDK, CLI (`--auto-solve-cloudflare`) and MCP server (`EOKA_AUTO_SOLVE_CLOUDFLARE=1`) use the same server watcher.
65
65
 
66
66
  ```js
67
67
  const browser = await Browser.launch({ autoSolveCloudflare: true });
@@ -73,21 +73,7 @@ try {
73
73
  }
74
74
  ```
75
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.
76
+ Tune it with `{ intervalMs, timeoutMs }` (defaults 500 and 30000). The server logs each challenge and result to its stderr. The watcher stops with `browser.close()`.
91
77
 
92
78
  ## Screenshots and recording
93
79
 
package/dist/browser.d.ts CHANGED
@@ -11,7 +11,7 @@ export interface BrowserOptions {
11
11
  signal?: AbortSignal;
12
12
  timeoutMs?: number;
13
13
  shutdownTimeoutMs?: number;
14
- /** Watch every tab and click full-page Cloudflare challenge checkboxes. */
14
+ /** Have the server watch every tab and solve full-page Cloudflare challenges. */
15
15
  autoSolveCloudflare?: boolean | CloudflareOptions;
16
16
  }
17
17
  export interface LaunchOptions extends BrowserOptions {
package/dist/browser.js CHANGED
@@ -8,7 +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
+ import { resolveCloudflareOptions } from './cloudflare.js';
12
12
  import { resolveServerBinary } from './server-binary.js';
13
13
  function validateTimeout(value, name) {
14
14
  if (value !== undefined && (!Number.isFinite(value) || value <= 0 || value > 2_147_483_647)) {
@@ -193,7 +193,6 @@ export class Browser {
193
193
  #capabilities;
194
194
  #shutdownTimeoutMs;
195
195
  #closePromise;
196
- #cloudflare;
197
196
  #pageOwners = new Set();
198
197
  #creationCleanupFailures = [];
199
198
  #runtimeCleanup;
@@ -290,6 +289,12 @@ export class Browser {
290
289
  if (expectedServerVersion !== undefined && transport.hello.serverVersion !== expectedServerVersion) {
291
290
  throw new ProtocolError(`Packaged server version mismatch: expected ${expectedServerVersion}, received ${transport.hello.serverVersion}`, { requestState: 'acknowledged' });
292
291
  }
292
+ const cloudflare = resolveCloudflareOptions(options.autoSolveCloudflare);
293
+ if (cloudflare !== undefined) {
294
+ if (!transport.hasCapability('cloudflareAutoSolve'))
295
+ throw new ConfigurationError('autoSolveCloudflare requires a server with the cloudflareAutoSolve capability');
296
+ params = { ...params, autoSolveCloudflare: cloudflare };
297
+ }
293
298
  const session = await transport.invoke(method, params, localOptions(options, deadline));
294
299
  if (!session || !['owned', 'borrowed'].includes(session.ownership) || typeof session.browserVersion !== 'string' || !session.browserVersion.trim() || (method === 'browser.connect' && session.ownership !== 'borrowed')) {
295
300
  throw new ProtocolError('Invalid browser session ownership or browserVersion', { requestState: 'acknowledged' });
@@ -298,13 +303,7 @@ export class Browser {
298
303
  throw new ProtocolError(`Managed browser version mismatch: expected ${expectedBrowserVersion}, received ${session.browserVersion}`, { requestState: 'acknowledged' });
299
304
  }
300
305
  checkAbort(options.signal, 'acknowledged');
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;
306
+ return new Browser(transport, session, options.shutdownTimeoutMs ?? 45_000, runtimeDir);
308
307
  }
309
308
  catch (primary) {
310
309
  try {
@@ -421,7 +420,6 @@ export class Browser {
421
420
  }
422
421
  close() {
423
422
  this.#closePromise ??= (async () => {
424
- this.#cloudflare?.stop();
425
423
  this.#transport.quiesce();
426
424
  await Promise.all(this.#pageOwners);
427
425
  let transportFailure;
@@ -1,45 +1,12 @@
1
- import type { CallOptions } from './client.js';
2
- import type { Page } from './page.js';
3
- /** Options for the browser-wide Cloudflare challenge watcher. */
1
+ /** Options for the server-side Cloudflare challenge watcher. */
4
2
  export interface CloudflareOptions {
5
3
  /** Poll interval in milliseconds. Defaults to 500. */
6
4
  intervalMs?: number;
7
- /** Deadline for each `solveTurnstile()` attempt. Defaults to 30000. */
5
+ /** Deadline for each challenge solve. Defaults to 30000. */
8
6
  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
7
  }
16
8
  export interface ResolvedCloudflareOptions {
17
9
  intervalMs: number;
18
10
  timeoutMs: number;
19
- onChallenge?: (page: Page) => void;
20
- onSolved?: (page: Page) => void;
21
- onError?: (error: unknown, page?: Page) => void;
22
11
  }
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
12
  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
- }
@@ -1,154 +1,19 @@
1
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
2
  export function resolveCloudflareOptions(value) {
11
3
  if (value === undefined || value === false)
12
4
  return undefined;
13
5
  const options = value === true ? {} : value;
6
+ for (const name of Object.keys(options)) {
7
+ if (name !== 'intervalMs' && name !== 'timeoutMs')
8
+ throw new ConfigurationError(`autoSolveCloudflare.${name} is not supported; the server solves challenges and reports them in its log`);
9
+ }
14
10
  const intervalMs = options.intervalMs ?? 500;
15
11
  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
- }
12
+ if (!Number.isInteger(intervalMs) || intervalMs < 100 || intervalMs > 60_000) {
13
+ throw new ConfigurationError('autoSolveCloudflare.intervalMs must be an integer between 100 and 60000 milliseconds');
142
14
  }
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
- }
15
+ if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000) {
16
+ throw new ConfigurationError('autoSolveCloudflare.timeoutMs must be an integer between 1 and 120000 milliseconds');
153
17
  }
18
+ return { intervalMs, timeoutMs };
154
19
  }