@koloss777/nokk 0.1.28-alpha → 0.1.29-alpha

package/README.md

@@ -53,7 +53,7 @@ const { chromium } = require("playwright");
 Starts the CDP server on a free port and resolves to a `NokkServer`. Options
 (all optional): `host`, `port`, `workers`, `maxContexts`, `proxy`,
 `sessionStore`, `rotateFingerprint`, `geoipTimezone`, `allowTrackers`,
-`chromeVersion`, `args`, `env`, `timeout`.
+`chromeVersion`, `autoSolve`, `args`, `env`, `timeout`.
 
 ```js
 // Each browser context looks like a different machine, timezone matched to its proxy:
@@ -63,6 +63,33 @@ const server = await nokk.launch({ rotateFingerprint: true, geoipTimezone: true
 `server.wsEndpoint` → hand to `puppeteer.connect` / `chromium.connectOverCDP`.
 `server.close()` stops it; it's also killed when the Node process exits.
 
+## Cloudflare challenges
+
+With `autoSolve`, a navigation that lands on Cloudflare's "Just a moment…" page
+or a Turnstile widget returns only once it is through: `page.goto()` resolves
+on the real page. `true` gives each challenge 30 s; a number sets the budget in
+seconds.
+
+```js
+const server = await nokk.launch({ autoSolve: true });
+// …
+await page.goto("https://www.scrapingcourse.com/cloudflare-challenge");
+console.log(await page.title()); // the page behind the challenge
+```
+
+Or on demand, for a Puppeteer page, a Playwright page or a raw CDP session:
+
+```js
+const state = await nokk.challengeState(page);
+// { kind: "cloudflare-interstitial" | "turnstile-widget" | "datadome" | "none", solvable, … }
+if (state.solvable) {
+  const r = await nokk.solveChallenge(page, { timeout: 30000 });
+  // { status: "cleared" | "token-issued" | "cleared-but-stuck" | "timeout", solved, presses, remaining, … }
+}
+```
+
+Nobody passes selectors: the engine finds and presses the checkbox itself.
+
 ## CLI
 
 ```bash

package/index.d.ts

@@ -19,6 +19,12 @@ export interface LaunchOptions {
   allowTrackers?: boolean;
   /** Chrome major version to emulate (TLS + JS together), e.g. 148. */
   chromeVersion?: number;
+  /**
+   * Solve Cloudflare challenges (interstitial or Turnstile widget) on every
+   * navigation before it reports the load. `true` = 30 s budget; a number =
+   * seconds. A browser context created with `autoSolve: false` opts out.
+   */
+  autoSolve?: boolean | number;
   /** Extra raw CLI arguments passed to the binary. */
   args?: string[];
   /** Extra environment variables for the server process. */
@@ -45,3 +51,56 @@ export declare function launch(options?: LaunchOptions): Promise<NokkServer>;
 
 /** Absolute path to the bundled `nokk` binary (override with NOKK_BINARY). */
 export declare function binaryPath(): string;
+
+/** The gate a page shows. Only the Cloudflare kinds are solvable. */
+export type ChallengeKind =
+  | "none"
+  | "cloudflare-interstitial"
+  | "turnstile-widget"
+  | "datadome";
+
+export type ChallengeStatus = "cleared" | "token-issued" | "cleared-but-stuck" | "timeout";
+
+export interface ChallengeState {
+  kind: ChallengeKind;
+  title: string;
+  url: string;
+  /** A `cf_clearance` cookie is in the jar for this site. */
+  cleared: boolean;
+  /** A Turnstile widget on the page has issued its token. */
+  token: boolean;
+  solvable: boolean;
+}
+
+export interface ChallengeOutcome {
+  status: ChallengeStatus;
+  /** `status` is "cleared" or "token-issued". */
+  solved: boolean;
+  /** Checkbox presses it took (0 for a non-interactive challenge). */
+  presses: number;
+  elapsedMs: number;
+  /** The gate still on the page afterwards ("none" when through). */
+  remaining: ChallengeKind;
+  title: string;
+  url: string;
+  cleared: boolean;
+  token: boolean;
+}
+
+/** Anything the helpers can reach a page's CDP session through. */
+export type PageLike =
+  | { createCDPSession(): Promise<{ send(method: string, params?: object): Promise<any> }> }
+  | { context(): { newCDPSession(page: any): Promise<{ send(method: string, params?: object): Promise<any> }> } }
+  | { send(method: string, params?: object): Promise<any> };
+
+/**
+ * Solve the challenge the page shows now, pressing its checkbox if it puts
+ * one up. Accepts a Puppeteer Page, a Playwright Page or a raw CDP session.
+ */
+export declare function solveChallenge(
+  page: PageLike,
+  options?: { /** Budget in ms (default: the server's, else 30000). */ timeout?: number }
+): Promise<ChallengeOutcome>;
+
+/** What gate the page shows right now. */
+export declare function challengeState(page: PageLike): Promise<ChallengeState>;

package/index.js

@@ -2,9 +2,11 @@
 //
 //   const nokk = require("nokk");
 //   const puppeteer = require("puppeteer");
-//   const server = await nokk.launch({ rotateFingerprint: true });
+//   const server = await nokk.launch({ autoSolve: true });
 //   const browser = await puppeteer.connect({ browserWSEndpoint: server.wsEndpoint });
-//   ...
+//   const page = await browser.newPage();
+//   await page.goto("https://www.scrapingcourse.com/cloudflare-challenge");
+//   // a Cloudflare challenge on the way was solved before goto resolved
 //   await server.close();
 "use strict";
 
@@ -109,6 +111,9 @@ class NokkServer {
  * @param {boolean} [opts.geoipTimezone]
  * @param {boolean} [opts.allowTrackers]
  * @param {number}  [opts.chromeVersion]          e.g. 148
+ * @param {boolean|number} [opts.autoSolve]       solve Cloudflare challenges on every
+ *                                                 navigation before it reports the load;
+ *                                                 `true` = 30 s budget, a number = seconds
  * @param {string[]}[opts.args]                    extra raw CLI args
  * @param {object}  [opts.env]
  * @param {number}  [opts.timeout=30000]          ms to wait for readiness
@@ -125,6 +130,8 @@ async function launch(opts = {}) {
   if (opts.geoipTimezone) args.push("--geoip-timezone");
   if (opts.allowTrackers) args.push("--allow-trackers");
   if (opts.chromeVersion != null) args.push("--chrome-version", String(opts.chromeVersion));
+  if (opts.autoSolve === true) args.push("--auto-solve");
+  else if (typeof opts.autoSolve === "number") args.push("--auto-solve", String(opts.autoSolve));
   if (opts.args) args.push(...opts.args);
 
   const proc = spawn(binaryPath(), args, {
@@ -154,4 +161,55 @@ async function launch(opts = {}) {
   throw new Error(`nokk did not become ready within ${timeout}ms`);
 }
 
-module.exports = { launch, binaryPath, NokkServer };
+// ---------------------------------------------------------------------------
+// Challenges. nokk answers two non-standard CDP commands on a page's session —
+// `Nokk.solveChallenge` and `Nokk.challengeState` — and sends a `Nokk.challenge`
+// event when a navigation lands on a gate. These helpers take whatever the
+// caller has: a Puppeteer Page, a Playwright Page, or a raw CDP session.
+
+const _sessions = new WeakMap();
+
+/** A CDP session bound to `target`'s page (cached per page). */
+async function _session(target) {
+  if (!target) throw new TypeError("expected a Puppeteer/Playwright Page or a CDP session");
+  if (_sessions.has(target)) return _sessions.get(target);
+  let s;
+  if (typeof target.createCDPSession === "function") {
+    s = await target.createCDPSession(); // Puppeteer Page
+  } else if (typeof target.context === "function" && typeof target.context().newCDPSession === "function") {
+    s = await target.context().newCDPSession(target); // Playwright Page
+  } else if (typeof target.send === "function") {
+    s = target; // already a CDP session
+  } else {
+    throw new TypeError("expected a Puppeteer/Playwright Page or a CDP session");
+  }
+  _sessions.set(target, s);
+  return s;
+}
+
+/**
+ * Solve the challenge the page shows now — a Cloudflare interstitial or a
+ * Turnstile widget — pressing its checkbox if it puts one up. Resolves to
+ * `{ status, solved, presses, elapsedMs, remaining, title, url, cleared, token }`.
+ *
+ * @param {object} page              Puppeteer Page, Playwright Page or CDP session
+ * @param {object} [opts]
+ * @param {number} [opts.timeout]    budget in ms (default: the server's, else 30000)
+ */
+async function solveChallenge(page, opts = {}) {
+  const s = await _session(page);
+  const params = opts.timeout != null ? { timeoutMs: opts.timeout } : {};
+  return s.send("Nokk.solveChallenge", params);
+}
+
+/**
+ * What gate the page shows: `{ kind, title, url, cleared, token, solvable }`, where
+ * `kind` is "none", "cloudflare-interstitial", "turnstile-widget" or another
+ * vendor's gate that nokk recognises but does not solve.
+ */
+async function challengeState(page) {
+  const s = await _session(page);
+  return s.send("Nokk.challengeState");
+}
+
+module.exports = { launch, binaryPath, NokkServer, solveChallenge, challengeState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koloss777/nokk",
-  "version": "0.1.28-alpha",
+  "version": "0.1.29-alpha",
   "description": "Undetectable headless-browser engine — a lightweight, Chrome-fingerprinted CDP server for Puppeteer/Playwright scraping. npm install and connect, no browser download.",
   "keywords": [
     "scraping",