captchakraken 2.1.0

package/README.md

@@ -0,0 +1,54 @@
+# captchakraken
+
+The TypeScript browser driver for [CaptchaKraken](https://github.com/JWriter20/CaptchaKraken).
+Hand it a Playwright/Puppeteer `Page`; it finds the captcha, reads the grid with
+a fine-tuned **Qwen3.5-9B** vision model on **vLLM**, clicks human-like, and
+verifies through to a token.
+
+> Full docs — demo videos, accuracy, self-hosting — live in the main repo
+> **[CaptchaKraken](https://github.com/JWriter20/CaptchaKraken)**.
+
+## Install
+
+```bash
+npm install captchakraken
+```
+
+The package bundles the Python engine (`captchakraken`) and, on `postinstall`,
+creates a local venv with its lightweight core deps so grid detection + the vLLM
+planner work out of the box. It ships **no browser** — bring your own
+Playwright-compatible launcher.
+
+- Skip the Python bootstrap: `CAPTCHA_KRAKEN_SKIP_PYTHON_SETUP=1`
+- To **self-host** the model, run the repo's `setup.sh` (installs vLLM + weights).
+  Otherwise point `VLLM_BASE_URL` at a server you already run.
+
+## Usage
+
+```typescript
+import { chromium } from 'playwright';            // or patchright / camoufox-js
+import { CaptchaKrakenSolver } from 'captchakraken';
+
+const browser = await chromium.launch({ headless: false });
+const page = await (await browser.newContext()).newPage();
+await page.goto('https://www.google.com/recaptcha/api2/demo');
+
+// Reads VLLM_BASE_URL + CAPTCHA_KRAKEN_API_KEY from the environment.
+const solver = new CaptchaKrakenSolver();
+await solver.solve(page);            // detect → solve grid → click → verify
+
+await browser.close();
+```
+
+Puppeteer users wrap the page once with `fromPuppeteer(page)`.
+
+## Configuration
+
+| Variable | Meaning |
+|---|---|
+| `VLLM_BASE_URL` | Inference endpoint (local vLLM, or a server you run) |
+| `CAPTCHA_KRAKEN_API_KEY` | Bearer token (`VLLM_API_KEY` also accepted) |
+
+## License
+
+GPL-3.0-or-later.

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+export * from './types';
+export { CaptchaKrakenSolver } from './solver';
+/**
+ * Adapter for driving the solver with **Puppeteer** instead of a Playwright
+ * launcher. Puppeteer's `Page` is API-compatible with Playwright's except for a
+ * few method names/options; `fromPuppeteer(page)` wraps it so `solve()` accepts
+ * it. Playwright-family launchers (vanilla `playwright`, `patchright`,
+ * `camoufox-js`) need no adapter — pass their `Page` directly.
+ *
+ * @example
+ * ```typescript
+ * import puppeteer from 'puppeteer';
+ * import { CaptchaKrakenSolver, fromPuppeteer } from 'captchakraken';
+ *
+ * const browser = await puppeteer.launch({ headless: false });
+ * const page = await browser.newPage();
+ * await page.goto('https://www.google.com/recaptcha/api2/demo');
+ *
+ * const solver = new CaptchaKrakenSolver();
+ * await solver.solve(fromPuppeteer(page));
+ * await browser.close();
+ * ```
+ */
+export { fromPuppeteer } from './puppeteer-adapter';
+/**
+ * The Playwright `Page` type the solver operates on.
+ *
+ * This is an implementation-neutral, structurally-typed Playwright `Page` — a
+ * duck-typed surface defined by this package, NOT imported from any browser
+ * library. The package depends on no concrete browser implementation, so you
+ * can drive the solver with ANY Playwright-compatible launcher: vanilla
+ * `playwright`, `patchright`, `camoufox-js`, or anything else that hands back a
+ * standard Playwright `Page`. They all structurally satisfy this type — pass
+ * yours directly, no cast needed.
+ *
+ * @example
+ * ```typescript
+ * // Pick whichever Playwright-compatible launcher you want — install it
+ * // yourself; this package does not bundle a browser:
+ * import { chromium } from 'playwright';          // vanilla
+ * // import { chromium } from 'patchright';       // stealth-patched
+ * // import { Camoufox } from 'camoufox-js';      // Firefox stealth
+ * import { CaptchaKrakenSolver } from 'captchakraken';
+ *
+ * const browser = await chromium.launch({ headless: false });
+ * const page = await (await browser.newContext()).newPage();
+ * await page.goto('https://www.google.com/recaptcha/api2/demo');
+ *
+ * // Reads VLLM_BASE_URL + CAPTCHA_KRAKEN_API_KEY from the environment.
+ * const solver = new CaptchaKrakenSolver();
+ * await solver.solve(page);   // detect → solve grid → click → verify
+ *
+ * await browser.close();
+ * ```
+ */
+export type { Page, PlaywrightPage, PlaywrightFrame, PlaywrightElementHandle } from './playwright-types';

package/dist/index.js

@@ -0,0 +1,43 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromPuppeteer = exports.CaptchaKrakenSolver = void 0;
+__exportStar(require("./types"), exports);
+var solver_1 = require("./solver");
+Object.defineProperty(exports, "CaptchaKrakenSolver", { enumerable: true, get: function () { return solver_1.CaptchaKrakenSolver; } });
+/**
+ * Adapter for driving the solver with **Puppeteer** instead of a Playwright
+ * launcher. Puppeteer's `Page` is API-compatible with Playwright's except for a
+ * few method names/options; `fromPuppeteer(page)` wraps it so `solve()` accepts
+ * it. Playwright-family launchers (vanilla `playwright`, `patchright`,
+ * `camoufox-js`) need no adapter — pass their `Page` directly.
+ *
+ * @example
+ * ```typescript
+ * import puppeteer from 'puppeteer';
+ * import { CaptchaKrakenSolver, fromPuppeteer } from 'captchakraken';
+ *
+ * const browser = await puppeteer.launch({ headless: false });
+ * const page = await browser.newPage();
+ * await page.goto('https://www.google.com/recaptcha/api2/demo');
+ *
+ * const solver = new CaptchaKrakenSolver();
+ * await solver.solve(fromPuppeteer(page));
+ * await browser.close();
+ * ```
+ */
+var puppeteer_adapter_1 = require("./puppeteer-adapter");
+Object.defineProperty(exports, "fromPuppeteer", { enumerable: true, get: function () { return puppeteer_adapter_1.fromPuppeteer; } });

package/dist/playwright-types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Minimal, implementation-neutral structural types for the slice of the
+ * Playwright API the solver actually uses.
+ *
+ * **Why these exist.** CaptchaKraken never launches a browser — you bring your
+ * own Playwright-compatible launcher and hand `solve()` a `Page`. To stay truly
+ * browser-agnostic the package depends on NO concrete browser implementation
+ * (not `playwright`, not `patchright`, not `camoufox-js`). Typing the public API
+ * against any one of those packages' `Page` would (a) force that package into
+ * consumers' trees and (b) break across version skew — e.g. `patchright` pins
+ * its own forked, older core whose `Page` is missing the newest `playwright-core`
+ * methods, so a `patchright` page won't structurally match a `playwright-core`
+ * page and vice-versa.
+ *
+ * Instead we declare a duck-typed surface covering only what the solver calls.
+ * Every real Playwright `Page` / `Frame` / `ElementHandle` — from vanilla
+ * `playwright`, `patchright`, `camoufox-js`, or anything else — structurally
+ * satisfies these, regardless of which Playwright version it was built against.
+ *
+ * Keep these in sync with `solver.ts`: if the solver starts calling a new
+ * Playwright method, add it here. The set is intentionally small and stable —
+ * these are long-standing Playwright primitives, not bleeding-edge additions.
+ */
+/** `{ x, y, width, height }` in CSS pixels — the shape `boundingBox()` returns. */
+export interface BoundingBoxRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** `{ width, height }` — the shape `viewportSize()` returns. */
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+/**
+ * Structural subset of Playwright's `ElementHandle`. Returned by `Page.$` /
+ * `Frame.$` / `Page.waitForSelector` and accepted by the solver as the captcha
+ * element / verify button / iframe handle.
+ */
+export interface PlaywrightElementHandle {
+    /** Screenshot just this element to a PNG file (the only option the solver passes). */
+    screenshot(options?: {
+        path?: string;
+    }): Promise<Buffer>;
+    /** The content document of an `<iframe>` element handle, or null if not a frame. */
+    contentFrame(): Promise<PlaywrightFrame | null>;
+    /** Element box in page CSS pixels, or null if not rendered. */
+    boundingBox(): Promise<BoundingBoxRect | null>;
+    /** Scroll the element into view if it isn't already. */
+    scrollIntoViewIfNeeded(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /** Read an attribute, or null if absent. */
+    getAttribute(name: string): Promise<string | null>;
+    /** Whether the element is visible. */
+    isVisible(): Promise<boolean>;
+    /** The element's text content, or null. */
+    textContent(): Promise<string | null>;
+}
+/**
+ * Structural subset of Playwright's `Frame` (an iframe's content document).
+ */
+export interface PlaywrightFrame {
+    /** First matching element handle, or null. */
+    $(selector: string): Promise<PlaywrightElementHandle | null>;
+    /** Wait for a selector to reach the given state; resolves to the handle (or null). */
+    waitForSelector(selector: string, options?: {
+        state?: 'attached' | 'detached' | 'visible' | 'hidden';
+        timeout?: number;
+    }): Promise<PlaywrightElementHandle | null>;
+    /** Poll a predicate evaluated in the page until it returns truthy. */
+    waitForFunction(pageFunction: Function | string, arg?: any, options?: {
+        timeout?: number;
+        polling?: number | 'raf';
+    }): Promise<unknown>;
+}
+/**
+ * Structural subset of Playwright's `Page` — exactly the members `solve()` and
+ * its helpers call. Any real Playwright `Page` satisfies this.
+ */
+export interface PlaywrightPage {
+    /** Low-level mouse control used to drive human-like trajectories and clicks. */
+    mouse: {
+        move(x: number, y: number, options?: {
+            steps?: number;
+        }): Promise<void>;
+        down(options?: {
+            button?: 'left' | 'right' | 'middle';
+            clickCount?: number;
+        }): Promise<void>;
+        up(options?: {
+            button?: 'left' | 'right' | 'middle';
+            clickCount?: number;
+        }): Promise<void>;
+    };
+    /** Sleep `timeout` ms (Playwright's own timer). */
+    waitForTimeout(timeout: number): Promise<void>;
+    /** Wait for a selector to reach the given state; resolves to the handle (or null). */
+    waitForSelector(selector: string, options?: {
+        state?: 'attached' | 'detached' | 'visible' | 'hidden';
+        timeout?: number;
+    }): Promise<PlaywrightElementHandle | null>;
+    /** Current viewport size, or null if not set. */
+    viewportSize(): ViewportSize | null;
+    /** First matching element handle, or null. */
+    $(selector: string): Promise<PlaywrightElementHandle | null>;
+    /** All matching element handles. */
+    $$(selector: string): Promise<PlaywrightElementHandle[]>;
+    /** Run `pageFunction` against the first matching element, in the page context. */
+    $eval<R>(selector: string, pageFunction: (element: Element) => R, arg?: any): Promise<R>;
+}
+/**
+ * Public alias. This is the type the solver's `solve(page)` accepts — kept under
+ * a friendly name so consumers can annotate against it. It is the
+ * implementation-neutral Playwright `Page`; pass a page from whichever
+ * Playwright-compatible launcher you prefer.
+ */
+export type Page = PlaywrightPage;

package/dist/playwright-types.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Minimal, implementation-neutral structural types for the slice of the
+ * Playwright API the solver actually uses.
+ *
+ * **Why these exist.** CaptchaKraken never launches a browser — you bring your
+ * own Playwright-compatible launcher and hand `solve()` a `Page`. To stay truly
+ * browser-agnostic the package depends on NO concrete browser implementation
+ * (not `playwright`, not `patchright`, not `camoufox-js`). Typing the public API
+ * against any one of those packages' `Page` would (a) force that package into
+ * consumers' trees and (b) break across version skew — e.g. `patchright` pins
+ * its own forked, older core whose `Page` is missing the newest `playwright-core`
+ * methods, so a `patchright` page won't structurally match a `playwright-core`
+ * page and vice-versa.
+ *
+ * Instead we declare a duck-typed surface covering only what the solver calls.
+ * Every real Playwright `Page` / `Frame` / `ElementHandle` — from vanilla
+ * `playwright`, `patchright`, `camoufox-js`, or anything else — structurally
+ * satisfies these, regardless of which Playwright version it was built against.
+ *
+ * Keep these in sync with `solver.ts`: if the solver starts calling a new
+ * Playwright method, add it here. The set is intentionally small and stable —
+ * these are long-standing Playwright primitives, not bleeding-edge additions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/puppeteer-adapter.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Puppeteer → CaptchaKraken adapter.
+ *
+ * The solver speaks the Playwright API surface (see playwright-types.ts). Puppeteer
+ * is ~95% the same shape but differs in a handful of method names/options. Rather
+ * than couple the solver to either library, this thin adapter wraps a Puppeteer
+ * `Page` (and, lazily, the `Frame`/`ElementHandle` objects it hands back) so it
+ * satisfies the structural `PlaywrightPage` interface the solver consumes.
+ *
+ * The deltas it bridges (verified against Puppeteer 24.x):
+ *   - `page.viewportSize()`            → `page.viewport()`  (same `{width,height}` shape)
+ *   - `page.waitForTimeout(ms)`        → removed in modern Puppeteer; use a timer
+ *   - `*.waitForSelector(sel, {state}) → Puppeteer uses `{visible}/{hidden}`
+ *   - `handle.getAttribute(name)`      → `handle.evaluate((el,n)=>el.getAttribute(n), name)`
+ *   - `handle.textContent()`           → `handle.evaluate(el=>el.textContent)`
+ *   - `handle.scrollIntoViewIfNeeded()`→ `handle.scrollIntoView()`
+ * Everything else (`$`, `$$`, `$eval`, `waitForFunction`, `mouse.*`,
+ * `screenshot({path})`, `boundingBox`, `contentFrame`, `isVisible`) is
+ * call-compatible and passed straight through.
+ *
+ * Usage:
+ * ```typescript
+ * import puppeteer from 'puppeteer';
+ * import { CaptchaKrakenSolver, fromPuppeteer } from 'captchakraken';
+ *
+ * const browser = await puppeteer.launch({ headless: false });
+ * const page = await browser.newPage();
+ * await page.goto('https://www.google.com/recaptcha/api2/demo');
+ *
+ * const solver = new CaptchaKrakenSolver();
+ * await solver.solve(fromPuppeteer(page));
+ * await browser.close();
+ * ```
+ */
+import { PlaywrightPage, BoundingBoxRect, ViewportSize } from './playwright-types';
+interface PuppeteerElementHandle {
+    screenshot(options?: {
+        path?: string;
+    }): Promise<unknown>;
+    contentFrame(): Promise<PuppeteerFrame | null>;
+    boundingBox(): Promise<BoundingBoxRect | null>;
+    scrollIntoView(): Promise<void>;
+    isVisible(): Promise<boolean>;
+    evaluate(pageFunction: (el: any, ...args: any[]) => any, ...args: any[]): Promise<any>;
+}
+interface PuppeteerFrame {
+    $(selector: string): Promise<PuppeteerElementHandle | null>;
+    waitForSelector(selector: string, options?: any): Promise<PuppeteerElementHandle | null>;
+    waitForFunction(pageFunction: Function | string, options?: any, ...args: any[]): Promise<unknown>;
+}
+interface PuppeteerPage {
+    mouse: {
+        move(x: number, y: number, options?: {
+            steps?: number;
+        }): Promise<void>;
+        down(options?: any): Promise<void>;
+        up(options?: any): Promise<void>;
+    };
+    waitForSelector(selector: string, options?: any): Promise<PuppeteerElementHandle | null>;
+    viewport(): ViewportSize | null;
+    $(selector: string): Promise<PuppeteerElementHandle | null>;
+    $$(selector: string): Promise<PuppeteerElementHandle[]>;
+    $eval(selector: string, pageFunction: (element: Element) => any, ...args: any[]): Promise<any>;
+}
+/**
+ * Wrap a Puppeteer `Page` so it satisfies the solver's structural Playwright
+ * `Page`. Pass the result to `solver.solve(...)`.
+ */
+export declare function fromPuppeteer(page: PuppeteerPage): PlaywrightPage;
+export {};

package/dist/puppeteer-adapter.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Puppeteer → CaptchaKraken adapter.
+ *
+ * The solver speaks the Playwright API surface (see playwright-types.ts). Puppeteer
+ * is ~95% the same shape but differs in a handful of method names/options. Rather
+ * than couple the solver to either library, this thin adapter wraps a Puppeteer
+ * `Page` (and, lazily, the `Frame`/`ElementHandle` objects it hands back) so it
+ * satisfies the structural `PlaywrightPage` interface the solver consumes.
+ *
+ * The deltas it bridges (verified against Puppeteer 24.x):
+ *   - `page.viewportSize()`            → `page.viewport()`  (same `{width,height}` shape)
+ *   - `page.waitForTimeout(ms)`        → removed in modern Puppeteer; use a timer
+ *   - `*.waitForSelector(sel, {state}) → Puppeteer uses `{visible}/{hidden}`
+ *   - `handle.getAttribute(name)`      → `handle.evaluate((el,n)=>el.getAttribute(n), name)`
+ *   - `handle.textContent()`           → `handle.evaluate(el=>el.textContent)`
+ *   - `handle.scrollIntoViewIfNeeded()`→ `handle.scrollIntoView()`
+ * Everything else (`$`, `$$`, `$eval`, `waitForFunction`, `mouse.*`,
+ * `screenshot({path})`, `boundingBox`, `contentFrame`, `isVisible`) is
+ * call-compatible and passed straight through.
+ *
+ * Usage:
+ * ```typescript
+ * import puppeteer from 'puppeteer';
+ * import { CaptchaKrakenSolver, fromPuppeteer } from 'captchakraken';
+ *
+ * const browser = await puppeteer.launch({ headless: false });
+ * const page = await browser.newPage();
+ * await page.goto('https://www.google.com/recaptcha/api2/demo');
+ *
+ * const solver = new CaptchaKrakenSolver();
+ * await solver.solve(fromPuppeteer(page));
+ * await browser.close();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromPuppeteer = fromPuppeteer;
+/** Translate Playwright `{state}` selector options to Puppeteer `{visible}/{hidden}`. */
+function toPuppeteerSelectorOptions(options) {
+    if (!options)
+        return undefined;
+    const { state, timeout } = options;
+    const out = {};
+    if (timeout !== undefined)
+        out.timeout = timeout;
+    if (state === 'visible')
+        out.visible = true;
+    else if (state === 'hidden')
+        out.hidden = true;
+    // 'attached'/'detached' have no direct Puppeteer flag — default wait (attached)
+    // is the closest match, so we pass no visibility flag.
+    return out;
+}
+function wrapHandle(h) {
+    if (!h)
+        return null;
+    return {
+        screenshot: (options) => h.screenshot(options),
+        contentFrame: async () => wrapFrame(await h.contentFrame()),
+        boundingBox: () => h.boundingBox(),
+        scrollIntoViewIfNeeded: () => h.scrollIntoView(),
+        getAttribute: (name) => h.evaluate((el, n) => el.getAttribute(n), name),
+        isVisible: () => h.isVisible(),
+        textContent: () => h.evaluate((el) => el.textContent),
+    };
+}
+function wrapFrame(f) {
+    if (!f)
+        return null;
+    return {
+        $: async (selector) => wrapHandle(await f.$(selector)),
+        waitForSelector: async (selector, options) => wrapHandle(await f.waitForSelector(selector, toPuppeteerSelectorOptions(options))),
+        waitForFunction: (pageFunction, arg, options) => 
+        // Playwright: (fn, arg, {timeout,polling}); Puppeteer: (fn, {timeout,polling}, ...args).
+        f.waitForFunction(pageFunction, options, arg),
+    };
+}
+/**
+ * Wrap a Puppeteer `Page` so it satisfies the solver's structural Playwright
+ * `Page`. Pass the result to `solver.solve(...)`.
+ */
+function fromPuppeteer(page) {
+    return {
+        mouse: {
+            move: (x, y, options) => page.mouse.move(x, y, options),
+            down: (options) => page.mouse.down(options),
+            up: (options) => page.mouse.up(options),
+        },
+        waitForTimeout: (timeout) => new Promise((resolve) => setTimeout(resolve, timeout)),
+        waitForSelector: async (selector, options) => wrapHandle(await page.waitForSelector(selector, toPuppeteerSelectorOptions(options))),
+        viewportSize: () => page.viewport(),
+        $: async (selector) => wrapHandle(await page.$(selector)),
+        $$: async (selector) => (await page.$$(selector)).map((h) => wrapHandle(h)).filter(Boolean),
+        $eval: (selector, pageFunction, arg) => page.$eval(selector, pageFunction, arg),
+    };
+}