captchakraken 2.9.0 → 3.1.0

package/AGENTS.md

@@ -0,0 +1,112 @@
+# captchakraken (npm)
+
+The TypeScript **browser driver**. You hand it a Playwright-compatible `Page`;
+it finds the captcha, has a vision model read it, and clicks, drags, slides or
+types through to a token.
+
+It is not a browser and it is not the model. It installs no browser — bring your
+own launcher — and every inference goes to a model endpoint you point it at.
+
+Repo, guides and the full agent guide:
+<https://github.com/JWriter20/CaptchaKraken>
+
+---
+
+## 1. Point it at a model, first
+
+Nothing solves until the driver knows where inference goes. Two ways:
+
+| You have | Do this |
+|---|---|
+| No GPU | Use the hosted API — add the account MCP server, `npx -y captchakraken-mcp`, call `sign_in` then `create_api_key` |
+| Your own vLLM server | `export VLLM_BASE_URL=…/v1` and `export CAPTCHA_KRAKEN_API_KEY=…` |
+
+`create_api_key` writes the key and endpoint to `~/.captchakraken/credentials`
+(mode 0600) and the driver reads that file by itself, so the MCP path needs **no
+environment variables at all**. The key is never printed into the conversation.
+
+## 2. Install
+
+```bash
+npm install captchakraken
+```
+
+The install runs a `postinstall` that creates a venv inside the package and
+installs the bundled Python engine the driver shells out to. It needs a Python
+3.10+ interpreter on `PATH`.
+
+| Variable | Effect |
+|---|---|
+| `CAPTCHA_KRAKEN_SKIP_PYTHON_SETUP=1` | Skip the bootstrap (you will supply the engine yourself) |
+| `CAPTCHA_KRAKEN_PYTHON=/path/to/python3` | Use this interpreter instead of probing `python3` then `python` |
+
+## 3. Solve
+
+```typescript
+import { chromium } from 'playwright';
+import { CaptchaKrakenSolver } from 'captchakraken';
+
+const page = await (await (await chromium.launch()).newContext()).newPage();
+await page.goto('https://www.google.com/recaptcha/api2/demo');
+
+await new CaptchaKrakenSolver().solve(page);   // detect → solve → click → verify
+```
+
+Any Playwright-compatible launcher works with no adapter (`playwright`,
+`patchright`, `camoufox-js`). Puppeteer needs one wrap:
+
+```typescript
+import { CaptchaKrakenSolver, fromPuppeteer } from 'captchakraken';
+await new CaptchaKrakenSolver().solve(fromPuppeteer(page));
+```
+
+Do not know when a captcha will appear? Install the watcher instead of calling
+`solve()`:
+
+```typescript
+const watcher = solver.watch(page);
+// ... your automation ...
+await watcher.stop();
+```
+
+Touch devices: `new CaptchaKrakenSolver({ humanization: 'mobile' })` emits real
+touch events (needs `hasTouch` on the context, or an Appium/WebdriverIO driver
+via `touchDriver`). `'none'` skips humanisation entirely.
+
+## 4. Errors
+
+`solve()` resolves to a `SolveResult` (`isSolved`), and throws when it cannot
+drive the widget at all — no captcha on the page, a puzzle this build does not
+handle, or the round budget exhausted. Only one error class is exported.
+
+Refusals from the hosted API arrive as `CaptchaKrakenAPIError`. **Branch on
+`e.code`, never on the message** — the codes are the contract, the wording is
+not. `insufficient_credits`, `missing_api_key`, `invalid_api_key`,
+`rate_limited`, `request_too_large`, `account_suspended` and
+`upstream_unavailable` each name their own fix; `e.resolutionUrl` carries a link
+where one exists. Retrying a `403` that means "no licence" will never succeed.
+
+## Rules for agents
+
+- **Never invent a number.** Every accuracy, latency and price figure we publish
+  is on one page —
+  [docs/benchmarks.md](https://github.com/JWriter20/CaptchaKraken/blob/main/docs/benchmarks.md).
+  Quote it as written; do not derive, round, or convert anything, and do not
+  read a static-image rate as a promise about a browser run.
+- **Never print an API key** into a transcript, a log, or a commit. Use
+  `create_api_key`, which writes it to disk instead. `captchakraken.env` and
+  `.env` hold keys and are never committed.
+- **Abyss is what our hosted API serves, and it is never downloadable.** The
+  current client names an Abyss expert on every request to our endpoint and is
+  answered by Abyss; an older client, or a request that names no model, gets
+  Twilight v1.2, because its prompts belong to that generation. Nothing about it
+  is gated on the account. Do not suggest weights, a download or a workaround
+  for it, and do not quote accuracy figures for it — none are published. Verify
+  what is serving with `GET /v1/models`.
+- **Respect the licence.** Building automation with this is fine; selling the
+  solve, or shipping it inside a browser or automation product, is not. See
+  [LICENSE](./LICENSE) and
+  [docs/licensing.md](https://github.com/JWriter20/CaptchaKraken/blob/main/docs/licensing.md).
+- **Changing this package's own code?** Its rules are in
+  [CONTRIBUTING.md](https://github.com/JWriter20/CaptchaKraken/blob/main/CONTRIBUTING.md),
+  not here.

package/NOTICE

@@ -0,0 +1,36 @@
+CaptchaKraken
+Copyright (c) 2026 CaptchaKraken LLC. All rights reserved.
+
+This product includes third-party software. The notices below are required by
+those components' licences and do not change the terms of the CaptchaKraken
+Source-Available License, which governs everything in this repository that is
+not listed here.
+
+────────────────────────────────────────────────────────────────────────────
+Cursory  —  mouse trajectory generation
+────────────────────────────────────────────────────────────────────────────
+
+  cursory      https://github.com/Vinyzu/cursory      (Python, PyPI: cursory)
+  cursory-js   https://github.com/JWriter20/cursory-js  (TypeScript, npm: cursory-js)
+
+  Copyright (c) Vinyzu and the cursory-js contributors.
+  Licensed under the GNU Lesser General Public License, version 3 or later
+  (LGPL-3.0-or-later). A copy is available at https://www.gnu.org/licenses/lgpl-3.0.html
+
+  HOW WE USE IT, AND WHY THAT MATTERS. Both are ORDINARY INSTALLED
+  DEPENDENCIES — `cursory` is declared in python/pyproject.toml and `cursory-js`
+  in js/package.json, and each is resolved by the user's own package manager at
+  install time. Neither is vendored into this repository, copied into our
+  sources, or bundled into a build artifact: the TypeScript build is `tsc`, which
+  leaves `require('cursory-js')` as a runtime import rather than inlining it, and
+  `js/scripts/copy-python.mjs` copies only our own `python/` tree.
+
+  That arrangement is the one the LGPL is written for, and it is what lets this
+  product remain under its own licence. It also means a user may replace either
+  library with a modified version of their own — reinstall the package, and the
+  driver picks it up — which is the freedom section 4 of the LGPL requires be
+  preserved. Do not vendor, inline, or bundle either one without taking legal
+  advice first; doing so is the change that would put this obligation somewhere
+  other than where it now sits.
+
+  We have not modified either library.

package/dist/cli-invocation.d.ts

@@ -1,46 +1,17 @@
-/**
- * How the JS client hands a solve request to the bundled Python CLI.
- *
- * Two rules govern this module, and both exist because the alternative is
- * unsafe rather than merely untidy:
- *
- * 1. The API key travels in the ENVIRONMENT, never in argv and never to stdout.
- *    Argv is world-readable on Linux — any local user can read
- *    `/proc/<pid>/cmdline` while a solve runs, and `ps` shows it — and anything
- *    printed alongside the command lands in CI logs and terminal scrollback.
- *    An environment block is per-process and not world-readable.
- *
- * 2. The command is built as an ARGV ARRAY for `execFile`, not a joined string
- *    for a shell, so a screenshot path containing a space or a quote cannot
- *    reshape the command.
- */
-/** Env var the CLI reads the bearer token from. */
+import type { PromptFamily, RetryMode, Vendor } from './kinds.js';
 export declare const API_KEY_ENV = "CAPTCHA_KRAKEN_API_KEY";
-/** Env var carrying the re-ask level for a board the vendor already refused. */
 export declare const RESAMPLE_LEVEL_ENV = "CAPTCHA_RESAMPLE_LEVEL";
-/** Positional placeholder the CLI still accepts in this slot. */
 export declare const API_PROVIDER = "captchaKrakenApi";
 export interface SolveInvocation {
     imagePath: string;
-    model: string;
-    puzzleSource: string;
-    retryMode?: string | null;
+    model?: string;
+    puzzleSource: Vendor;
+    retryMode?: RetryMode | null;
     textMode?: boolean;
-    /** One expert of a routed model, or undefined to route by prompt family. */
-    expert?: string | null;
+    expert?: PromptFamily | null;
 }
-/**
- * The argv for one solve. No shell, no quoting, and NO CREDENTIAL — the key is
- * supplied by `solveEnv` instead.
- */
+/** An argv array for execFile, never a shell string. */
 export declare function buildSolveArgs(invocation: SolveInvocation): string[];
-/** Base env plus the credential, when there is one. */
+/** The resample LEVEL travels, not a temperature: the schedule lives once in planner.RESAMPLE_TEMPERATURES, and a fresh CLI process cannot know the round count. */
 export declare function solveEnv(base: NodeJS.ProcessEnv, apiKey?: string, resampleLevel?: number): NodeJS.ProcessEnv;
-/**
- * A log line for a solve invocation, with any credential removed.
- *
- * Belt and braces: `buildSolveArgs` no longer carries the key, but this is the
- * function that prints to stdout, so it redacts anything key-shaped regardless
- * of how it got into the array.
- */
 export declare function redactCommand(command: string, apiKey?: string): string;

package/dist/cli-invocation.js

@@ -1,78 +1,37 @@
 "use strict";
-/**
- * How the JS client hands a solve request to the bundled Python CLI.
- *
- * Two rules govern this module, and both exist because the alternative is
- * unsafe rather than merely untidy:
- *
- * 1. The API key travels in the ENVIRONMENT, never in argv and never to stdout.
- *    Argv is world-readable on Linux — any local user can read
- *    `/proc/<pid>/cmdline` while a solve runs, and `ps` shows it — and anything
- *    printed alongside the command lands in CI logs and terminal scrollback.
- *    An environment block is per-process and not world-readable.
- *
- * 2. The command is built as an ARGV ARRAY for `execFile`, not a joined string
- *    for a shell, so a screenshot path containing a space or a quote cannot
- *    reshape the command.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.API_PROVIDER = exports.RESAMPLE_LEVEL_ENV = exports.API_KEY_ENV = void 0;
 exports.buildSolveArgs = buildSolveArgs;
 exports.solveEnv = solveEnv;
 exports.redactCommand = redactCommand;
-/** Env var the CLI reads the bearer token from. */
+// The key travels in env, never argv: argv is world-readable on Linux via /proc/<pid>/cmdline and `ps`. See TRIBAL_KNOWLEDGE.md.
 exports.API_KEY_ENV = 'CAPTCHA_KRAKEN_API_KEY';
-/** Env var carrying the re-ask level for a board the vendor already refused. */
 exports.RESAMPLE_LEVEL_ENV = 'CAPTCHA_RESAMPLE_LEVEL';
-/** Positional placeholder the CLI still accepts in this slot. */
 exports.API_PROVIDER = 'captchaKrakenApi';
-/**
- * The argv for one solve. No shell, no quoting, and NO CREDENTIAL — the key is
- * supplied by `solveEnv` instead.
- */
+/** An argv array for execFile, never a shell string. */
 function buildSolveArgs(invocation) {
     const { imagePath, model, puzzleSource, retryMode, textMode, expert } = invocation;
-    const args = [
-        '-m',
-        'captchakraken.cli',
-        imagePath,
-        model,
-        exports.API_PROVIDER,
-        `--puzzle-source=${puzzleSource}`,
-    ];
+    const args = ['-m', 'captchakraken.cli', imagePath];
+    // Both positionals or neither: the provider passed alone would bind to `model`.
+    if (model)
+        args.push(model, exports.API_PROVIDER);
+    args.push(`--puzzle-source=${puzzleSource}`);
     if (retryMode)
         args.push(`--retry-mode=${retryMode}`);
     if (textMode)
         args.push('--text-mode');
-    // Only when set. An absent flag is what lets the Python side route by prompt
-    // family, and passing `--expert=` would be an empty choice rather than none.
     if (expert)
         args.push(`--expert=${expert}`);
     return args;
 }
-/** Base env plus the credential, when there is one. */
+/** The resample LEVEL travels, not a temperature: the schedule lives once in planner.RESAMPLE_TEMPERATURES, and a fresh CLI process cannot know the round count. */
 function solveEnv(base, apiKey, resampleLevel) {
     const out = apiKey ? { ...base, [exports.API_KEY_ENV]: apiKey } : { ...base };
-    // How many times THIS board has already been read and refused. The CLI is a
-    // fresh process per round, so it cannot know; and without it a re-ask is the
-    // same greedy arithmetic on the same pixels and returns the same answer,
-    // which is the whole of the "same answer 3 times running" failure.
-    //
-    // The LEVEL travels, not the temperature: the schedule lives once, in
-    // `planner.RESAMPLE_TEMPERATURES`, so the two ports cannot drift apart on a
-    // number Tier 3 would then average.
     if (resampleLevel && resampleLevel > 0) {
         out[exports.RESAMPLE_LEVEL_ENV] = String(resampleLevel);
     }
     return out;
 }
-/**
- * A log line for a solve invocation, with any credential removed.
- *
- * Belt and braces: `buildSolveArgs` no longer carries the key, but this is the
- * function that prints to stdout, so it redacts anything key-shaped regardless
- * of how it got into the array.
- */
 function redactCommand(command, apiKey) {
     if (!apiKey)
         return command;

package/dist/errors.d.ts

@@ -1,28 +1,15 @@
+import { ErrorCode } from './kinds.js';
+/** Open on purpose: a code the server adds tomorrow must arrive intact, not be coerced to undefined. */
+export type CaptchaKrakenErrorCode = ErrorCode | (string & {});
 /**
- * Hosted-API refusals, carried across the Python subprocess boundary.
- *
- * The TypeScript driver does not talk to the model; it shells out to the Python
- * CLI, which does. So every hosted-API error arrives here as text on stderr and
- * would, without this, be flattened into
- * `Failed to execute captcha solver CLI: Command failed with exit code 3` —
- * a sentence that tells a camoufox user nothing about the fact that their
- * account is out of credits.
- *
- * The CLI exits 3 and prints `{"error": "...", "ck_error": {...}}`, so the
- * wording is decided once, in Python (`captchakraken/errors.py`), and merely
- * relayed here. Deliberately NOT re-worded on this side: two copies of the same
- * message drift, and the Python one is also what a direct CLI user sees.
+ * The Python port words every message once and this side repeats it verbatim: two copies of the same
+ * sentence drift. Before this class a customer out of credits read `vLLM 402 Payment Required at ...`.
  */
-/** The machine-readable half. Mirrors the gateway's `GatewayErrorCode`. */
-export type CaptchaKrakenErrorCode = 'missing_api_key' | 'invalid_api_key' | 'account_suspended' | 'insufficient_credits' | 'rate_limited' | 'solve_abandoned' | 'unrecognized_prompt' | 'invalid_request' | 'request_too_large' | 'upstream_unavailable' | 'model_not_licensed' | 'model_not_serving' | (string & {});
 export declare class CaptchaKrakenAPIError extends Error {
     readonly status: number | undefined;
     readonly code: CaptchaKrakenErrorCode | undefined;
-    /** Where to send the user to fix it, when the server named somewhere. */
     readonly resolutionUrl: string | undefined;
-    /** Seconds to wait, on `rate_limited`. */
     readonly retryAfterSeconds: number | undefined;
-    /** Lets `catch` blocks branch without `instanceof` across module copies. */
     readonly isCaptchaKrakenAPIError = true;
     constructor(message: string, fields?: {
         status?: number;
@@ -32,14 +19,7 @@ export declare class CaptchaKrakenAPIError extends Error {
     });
 }
 /**
- * Pull a hosted-API error out of the CLI's stderr, or return null.
- *
- * Scans line by line rather than parsing the whole buffer: stderr also carries
- * timing records and any warning the Python side emitted, so the JSON payload
- * is one line among several and `JSON.parse(stderr)` would simply fail.
- *
- * Returns null for anything that is not recognisably ours, which leaves the
- * caller's existing generic handling in place — an unparseable stderr must not
- * become a confident but wrong billing message.
+ * Line by line, because stderr also carries timing records. Anything unrecognised is null, never a guess:
+ * an unparseable stderr must not become a confident but wrong billing message.
  */
 export declare function parseApiError(stderr: string): CaptchaKrakenAPIError | null;

package/dist/errors.js

@@ -1,26 +1,14 @@
 "use strict";
-/**
- * Hosted-API refusals, carried across the Python subprocess boundary.
- *
- * The TypeScript driver does not talk to the model; it shells out to the Python
- * CLI, which does. So every hosted-API error arrives here as text on stderr and
- * would, without this, be flattened into
- * `Failed to execute captcha solver CLI: Command failed with exit code 3` —
- * a sentence that tells a camoufox user nothing about the fact that their
- * account is out of credits.
- *
- * The CLI exits 3 and prints `{"error": "...", "ck_error": {...}}`, so the
- * wording is decided once, in Python (`captchakraken/errors.py`), and merely
- * relayed here. Deliberately NOT re-worded on this side: two copies of the same
- * message drift, and the Python one is also what a direct CLI user sees.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CaptchaKrakenAPIError = void 0;
 exports.parseApiError = parseApiError;
+/**
+ * The Python port words every message once and this side repeats it verbatim: two copies of the same
+ * sentence drift. Before this class a customer out of credits read `vLLM 402 Payment Required at ...`.
+ */
 class CaptchaKrakenAPIError extends Error {
     constructor(message, fields = {}) {
         super(message);
-        /** Lets `catch` blocks branch without `instanceof` across module copies. */
         this.isCaptchaKrakenAPIError = true;
         this.name = 'CaptchaKrakenAPIError';
         this.status = fields.status;
@@ -31,15 +19,8 @@ class CaptchaKrakenAPIError extends Error {
 }
 exports.CaptchaKrakenAPIError = CaptchaKrakenAPIError;
 /**
- * Pull a hosted-API error out of the CLI's stderr, or return null.
- *
- * Scans line by line rather than parsing the whole buffer: stderr also carries
- * timing records and any warning the Python side emitted, so the JSON payload
- * is one line among several and `JSON.parse(stderr)` would simply fail.
- *
- * Returns null for anything that is not recognisably ours, which leaves the
- * caller's existing generic handling in place — an unparseable stderr must not
- * become a confident but wrong billing message.
+ * Line by line, because stderr also carries timing records. Anything unrecognised is null, never a guess:
+ * an unparseable stderr must not become a confident but wrong billing message.
  */
 function parseApiError(stderr) {
     if (!stderr || !stderr.includes('ck_error'))