capskip 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-09-12
+
+### Added
+
+- **ALTCHA support** via `altcha(url, options)`. Pass `challengeUrl` for CapSkip
+  to fetch the challenge, or `challengeJson` with the document itself (a JSON
+  string, or an object which is serialized for you). Sending both is allowed —
+  the inline document wins. The result exposes `token` (the value the site's
+  `altcha` form field expects) and `number`, the counter that solved it; `code`
+  keeps the same raw string.
+- Parameter aliases `challengeUrl`/`challengeURL` for `challenge_url` and
+  `challengeJson`/`challengeJSON` for `challenge_json`.
+- `AltchaOptions` and the `token`/`number` result fields in the TypeScript
+  definitions.
+- Both ALTCHA generations are handled: the legacy scheme (SHA-1/256/384/512) and
+  proof-of-work v2 (PBKDF2 or SHA). Their tokens are shaped differently — a v2
+  payload carries no top-level `number`, its counter sitting at
+  `solution.counter` — so the counter is taken from the server's own `solution`
+  object, the one field both report the same way, and dug out of the token only
+  when a poll did not carry it.
+
+### Notes
+
+- ALTCHA is CPU proof-of-work rather than a browser solve, so it uses
+  `defaultTimeout` instead of the longer `recaptchaTimeout` that reCAPTCHA,
+  Turnstile and GeeTest use.
+- A proxy passed to `altcha()` applies only to the `challengeUrl` fetch; a task
+  carrying its challenge inline never touches the network.
+
+## [1.1.0] - 2026-07-26
+
+### Added
+
+- **GeeTest v3 (slide) support** via `geetest(gt, challenge, url, options)`.
+  Accepts the optional `api_server` domain override and the usual `proxy`
+  option. The result exposes the answer as the parsed `challenge`, `validate`,
+  and `seccode` fields, while `code` keeps the raw JSON string CapSkip returns.
+- Parameter aliases `apiServer` and `api_subdomain` for `api_server`.
+- TypeScript definitions for `geetest()`, `GeetestOptions`, and the new
+  `SolveResult` fields.
+- `proxytype` is now validated against the values CapSkip accepts (`HTTP`,
+  `HTTPS`, `SOCKS5`, `SOCKS5H`, case-insensitive) for every proxy-capable captcha
+  type. `SOCKS4` and other values previously reached the server and came back as
+  `ERROR_BAD_PARAMETERS`; they now raise `ValidationException` locally.
+
 ## [1.0.2] - 2026-07-15
 
 ### Fixed

package/README.md

@@ -1,20 +1,52 @@
-# CapSkip Node.js SDK
+# CapSkip Node.js SDK — Captcha Solver for Node.js
 
+[![npm](https://img.shields.io/npm/v/capskip.svg)](https://www.npmjs.com/package/capskip)
 [![Node.js 18+](https://img.shields.io/badge/node-18%2B-brightgreen.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Tests](https://github.com/capskip/capskip-node/actions/workflows/ci.yml/badge.svg)](https://github.com/capskip/capskip-node/actions/workflows/ci.yml)
 
-Official Node.js client for the [CapSkip](https://capskip.com) **local** captcha solver.
+**Solve reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest, ALTCHA and image captchas from Node.js.**
 
-CapSkip runs on your machine and exposes a standard captcha-solver HTTP API (the familiar `in.php` / `res.php` endpoints). This SDK wraps that API with clean, familiar method names, so you can solve captchas locally — no cloud service and no per-solve API fees beyond your CapSkip license.
+Official Node.js client for [CapSkip](https://capskip.com), a **local captcha solver** that runs on your own machine. Licensed once, not billed per solve. TypeScript definitions included.
+
+```bash
+npm install capskip
+```
+
+---
+
+## How it works
+
+CapSkip is a desktop app. It does the solving on your machine and exposes the standard captcha-solver HTTP API — the same `in.php` / `res.php` endpoints every 2captcha-compatible client already speaks — on `127.0.0.1:8080`.
+
+This SDK is a thin wrapper over that API, with the method names you would expect: `normal()`, `recaptcha()`, `turnstile()`, `geetest()`, `altcha()`. Nothing leaves your network, and there is no credit balance to keep an eye on.
+
+## Supported captcha types
+
+| Captcha | Method |
+|---|---|
+| **Image captcha solver** (distorted text / OCR) | `solver.normal(file)` |
+| **reCAPTCHA v2 solver** (checkbox) | `solver.recaptcha(sitekey, url)` |
+| **reCAPTCHA v2 invisible solver** | `solver.recaptcha(sitekey, url, { invisible: 1 })` |
+| **reCAPTCHA Enterprise solver** | `solver.recaptcha(sitekey, url, { enterprise: 1 })` |
+| **reCAPTCHA v3 solver** | `solver.recaptcha(sitekey, url, { version: 'v3', action: 'submit' })` |
+| reCAPTCHA v3 Enterprise | `solver.recaptcha(sitekey, url, { version: 'v3', enterprise: 1 })` |
+| **Cloudflare Turnstile solver** (widget) | `solver.turnstile(sitekey, url)` |
+| Cloudflare Turnstile (challenge page) | `solver.turnstile(sitekey, url, { data, pagedata })` |
+| **GeeTest v3 solver** (slide puzzle) | `solver.geetest(gt, challenge, url)` |
+| **ALTCHA solver** (proof-of-work) | `solver.altcha(url, { challengeUrl })` |
+
+**hCaptcha and FunCaptcha/Arkose are not supported.** hCaptcha is the one people misidentify most often, since it also puts a `data-sitekey` on the widget — check for `class="h-captcha"` or a `js.hcaptcha.com` script before reaching for `recaptcha()`.
+
+Point the SDK at the [live captcha demo pages](https://capskip.com/captcha-demo/) to sanity-check your setup against real widgets.
 
 ---
 
 ## Quick start (5 minutes)
 
-### 1. Install CapSkip
+### 1. Install the CapSkip captcha solver
 
-Download and run the CapSkip desktop app from [capskip.com](https://capskip.com). Leave it running in the background.
+Download and run the CapSkip desktop app — [CapSkipInstaller.msi](https://capskip.com/download/CapSkipInstaller.msi). Leave it running in the background.
 
 In CapSkip settings, note:
 
@@ -58,18 +90,20 @@ Every solve method returns a Promise — use `await` or `.then()`.
 
 ---
 
-## Supported captcha types
+## Why solve captchas locally
 
-| Type | SDK method |
-|---|---|
-| Image CAPTCHA (distorted text) | `solver.normal(file)` |
-| reCAPTCHA v2 (checkbox) | `solver.recaptcha(sitekey, url)` |
-| reCAPTCHA v2 Invisible | `solver.recaptcha(sitekey, url, { invisible: 1 })` |
-| reCAPTCHA v2 Enterprise | `solver.recaptcha(sitekey, url, { enterprise: 1 })` |
-| reCAPTCHA v3 | `solver.recaptcha(sitekey, url, { version: 'v3' })` |
-| reCAPTCHA v3 Enterprise | `solver.recaptcha(sitekey, url, { version: 'v3', enterprise: 1 })` |
-| Cloudflare Turnstile (widget) | `solver.turnstile(sitekey, url)` |
-| Cloudflare Turnstile (challenge page) | `solver.turnstile(sitekey, url, { data, pagedata })` |
+Cloud captcha APIs charge per solve, which turns a retry loop into an expense and routes every page URL and sitekey you touch through someone else's queue.
+
+CapSkip flips that around:
+
+- **Unlimited solving** — one license, no per-captcha charge, no balance to top up
+- **Runs on `127.0.0.1`** — the SDK never talks to a third-party server
+- **No per-key rate limit** — throughput is whatever your machine can manage
+- **Fast** — image captchas come back in well under a second; a typical reCAPTCHA v2 lands in 30–45 seconds
+
+### Coming from 2captcha or Anti-Captcha
+
+CapSkip answers on the same `in.php` / `res.php` endpoints, so it works as a **2captcha API alternative**: an existing integration usually needs nothing more than its host pointed at `127.0.0.1:8080`. The [migration notes](https://capskip.com/2captcha-api-alternative/) cover the details, if you would rather keep your current client library than switch to this one.
 
 ---
 
@@ -97,7 +131,8 @@ const solver = new CapSkip({
   host: '127.0.0.1',        // CapSkip host
   port: 8080,               // CapSkip port from app settings
   defaultTimeout: 120,      // seconds — image captcha polling timeout
-  recaptchaTimeout: 300,    // seconds — reCAPTCHA / Turnstile polling timeout
+  recaptchaTimeout: 300,    // seconds — reCAPTCHA / Turnstile / GeeTest polling timeout
+                            // (ALTCHA uses defaultTimeout — CPU work, not a browser solve)
   pollingInterval: 5,       // max seconds between res.php polls (starts at 0.25s, backs off to this)
 });
 ```
@@ -161,7 +196,41 @@ const v3 = await solver.recaptcha('...', 'https://example.com', {
 const result = await solver.turnstile('0x4AAAAAAA...', 'https://example.com');
 ```
 
-### With a proxy (reCAPTCHA & Turnstile only)
+### GeeTest v3
+
+`gt` is static per site, but `challenge` is single-use and expires in about a
+minute — fetch a fresh pair right before solving.
+
+```js
+const result = await solver.geetest(
+  '81388ea1fc187e0c335c0a8907ff2625',
+  '7cf6a8b1a2c34d5e6f7089abcdef0123',
+  'https://example.com/login',
+);
+
+// Post these back exactly as the site's own front-end would
+result.challenge, result.validate, result.seccode;
+```
+
+### ALTCHA
+
+ALTCHA is proof-of-work, not recognition — there is nothing to read, so a solve
+is deterministic and takes milliseconds. Give CapSkip the endpoint that serves
+the challenge, or the challenge document itself.
+
+```js
+const result = await solver.altcha('https://example.com/signup', {
+  challengeUrl: 'https://example.com/captcha/api/altcha/challenge',
+});
+
+// Post this back in the form field the widget uses, named `altcha`
+result.token;
+```
+
+Challenges expire fast — some sites inside two minutes — so fetch one
+immediately before solving and submit the token promptly.
+
+### With a proxy (reCAPTCHA, Turnstile, GeeTest & ALTCHA only)
 
 ```js
 // Proxy is not supported for image captcha
@@ -196,6 +265,53 @@ More examples: [`examples/`](examples/)
 
 ---
 
+## Puppeteer, Playwright and Selenium
+
+The SDK hands back a token; your existing browser tooling does the driving. The shape is the same whichever you use:
+
+1. Read the sitekey off the page (`data-sitekey`, or the widget's config object).
+2. Call the matching solve method with that sitekey and the page URL.
+3. Write the token into the response field and submit.
+
+### Puppeteer
+
+```js
+const sitekey = await page.$eval('[data-sitekey]', el => el.dataset.sitekey);
+const { code } = await solver.recaptcha(sitekey, page.url());
+
+await page.evaluate(t => {
+  document.getElementById('g-recaptcha-response').value = t;
+}, code);
+await page.click('button[type=submit]');
+```
+
+### Playwright
+
+```js
+const sitekey = await page.getAttribute('[data-sitekey]', 'data-sitekey');
+const { code } = await solver.recaptcha(sitekey, page.url());
+
+await page.evaluate(t => {
+  document.getElementById('g-recaptcha-response').value = t;
+}, code);
+```
+
+### Selenium WebDriver
+
+```js
+const el = await driver.findElement(By.css('[data-sitekey]'));
+const sitekey = await el.getAttribute('data-sitekey');
+const { code } = await solver.recaptcha(sitekey, await driver.getCurrentUrl());
+
+await driver.executeScript(
+  'document.getElementById("g-recaptcha-response").value = arguments[0];', code,
+);
+```
+
+Longer walkthroughs: [Puppeteer](https://capskip.com/puppeteer-captcha-solver/), [Playwright](https://capskip.com/playwright-captcha-solver/) and [Selenium](https://capskip.com/selenium-captcha-solver/).
+
+---
+
 ## Return value
 
 Every solve method resolves to:
@@ -208,6 +324,10 @@ Every solve method resolves to:
 }
 ```
 
+GeeTest additionally expands its answer into `challenge`, `validate`, and
+`seccode`, while `code` keeps the raw JSON string. ALTCHA adds `token` (the same
+string as `code`) and `number`, the counter that solved it.
+
 ---
 
 ## Error handling
@@ -247,6 +367,42 @@ const result: SolveResult = await solver.recaptcha('...', 'https://example.com')
 
 ---
 
+## FAQ
+
+### How do I solve a captcha in Node.js?
+
+Install the CapSkip desktop app, `npm install capskip`, then call the method that matches the widget — `recaptcha()`, `turnstile()`, `geetest()`, `altcha()` or `normal()`. Each returns a Promise that resolves once CapSkip has an answer, giving you a token, or the recognized text in the case of an image captcha.
+
+### Is this a free captcha solver?
+
+The SDK itself is MIT-licensed and free. Solving needs the CapSkip app, which is bought once rather than metered per captcha, so your cost stops scaling with volume.
+
+### Which captchas can it solve?
+
+reCAPTCHA v2 (checkbox and invisible), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, GeeTest v3, ALTCHA, and image/text captchas. Not hCaptcha, and not FunCaptcha/Arkose.
+
+### Does it work with Puppeteer and Playwright?
+
+Yes — see [above](#puppeteer-playwright-and-selenium). The SDK never touches a browser itself, so it drops into whatever stack you already have, Selenium and plain `fetch` included.
+
+### Why is my reCAPTCHA v3 score low?
+
+Google derives v3 scores from IP reputation, cookies and browsing history. A solver returns a valid token, but it cannot change how Google grades that token — `score` is forwarded as the target you want, not a guarantee. If a site enforces a high threshold, solve through a cleaner IP using the `proxy` option.
+
+### Can I use it as a 2captcha alternative?
+
+Yes. CapSkip serves the same endpoints, so you can either move to this SDK or repoint an existing 2captcha client at `127.0.0.1:8080`.
+
+### Does the captcha have to be on a public page?
+
+For widget captchas, yes — CapSkip loads the URL you pass it. Image captchas only need the image, and that can be a local file.
+
+### Does it work with TypeScript and ESM?
+
+Types ship in the package. The runtime is CommonJS, so `import { CapSkip } from 'capskip'` works from ESM through Node's interop.
+
+---
+
 ## Development
 
 ```bash
@@ -262,10 +418,12 @@ The test suite uses Node's built-in test runner — no extra dependencies. See [
 
 ## Links
 
-- [CapSkip website](https://capskip.com)
-- [CapSkip API docs](https://capskip.com/api-docs/)
-- [Report an issue](https://github.com/capskip/capskip-node/issues)
-- [npm package](https://www.npmjs.com/package/capskip)
+- [CapSkip — local captcha solver](https://capskip.com) · [download the app](https://capskip.com/download/CapSkipInstaller.msi)
+- [Captcha demo pages](https://capskip.com/captcha-demo/) — live reCAPTCHA, Turnstile, GeeTest and image widgets
+- [Node.js captcha solver guide](https://capskip.com/nodejs-captcha-solver/)
+- [HTTP API docs](https://capskip.com/api-docs/)
+- Other clients: [Python](https://github.com/capskip/capskip-python) · [PHP](https://github.com/capskip/capskip-php) · [.NET](https://github.com/capskip/capskip-dotnet) · [MCP server for AI agents](https://github.com/capskip/capskip-mcp)
+- [npm package](https://www.npmjs.com/package/capskip) · [report an issue](https://github.com/capskip/capskip-node/issues)
 
 ---
 

package/docs/API_REFERENCE.md

@@ -22,8 +22,11 @@ method returns a `Promise`.
 | reCAPTCHA v2 | `recaptcha(sitekey, url)` | `userrecaptcha` |
 | reCAPTCHA v3 | `recaptcha(sitekey, url, { version: 'v3' })` | `userrecaptcha` + `version=v3` |
 | Cloudflare Turnstile | `turnstile()` | `turnstile` |
+| GeeTest v3 (slide) | `geetest()` | `geetest` |
+| ALTCHA (proof-of-work) | `altcha()` | `altcha` |
 
-**Proxy** is supported for reCAPTCHA and Turnstile only — not for image captcha.
+**Proxy** is supported for reCAPTCHA, Turnstile, GeeTest, and ALTCHA — not for image
+captcha. For ALTCHA the proxy is used only for the `challengeUrl` fetch.
 
 ---
 
@@ -206,6 +209,174 @@ const challenge = await solver.turnstile('0x4AAAAAAA...', 'https://example.com',
 
 ---
 
+## 5. GeeTest v3 — `geetest(gt, challenge, url, { ... })`
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `method` | string | Yes | `geetest` |
+| `gt` | string | Yes | Static per-site GeeTest id |
+| `challenge` | string | Yes | Single-use challenge token |
+| `pageurl` | string | Yes | Full page URL |
+| `api_server` | string | No | GeeTest API server domain, e.g. `api-na.geetest.com` |
+| `json` | int | No | `0` plain text, `1` JSON |
+| `proxy` | string | No | Proxy address |
+| `proxytype` | string | No | Proxy type |
+
+### Getting `gt` and `challenge`
+
+Both come from the target site, which fetches them from an endpoint returning
+`{"gt": "...", "challenge": "..."}` (often `.../register.php` or a `gettype`/`get.php`
+request). Find it in DevTools → Network, or read them out of the
+`initGeetest({ gt, challenge })` call in the page scripts.
+
+> **`challenge` is single-use and expires in about a minute.** Fetch a fresh pair
+> immediately before each solve. If a solve comes back with a bad-challenge error,
+> request a new pair and retry — reusing one never succeeds.
+
+### SDK usage
+
+```js
+const result = await solver.geetest(
+  '81388ea1fc187e0c335c0a8907ff2625',
+  '7cf6a8b1a2c34d5e6f7089abcdef0123',
+  'https://example.com/login',
+);
+
+result.challenge;   // geetest_challenge
+result.validate;    // geetest_validate
+result.seccode;     // geetest_seccode
+result.code;        // the same answer as a raw JSON string
+```
+
+Post the three fields back exactly as the site's own front-end would:
+
+```js
+await fetch(LOGIN_URL, {
+  method: 'POST',
+  body: new URLSearchParams({
+    geetest_challenge: result.challenge,
+    geetest_validate: result.validate,
+    geetest_seccode: result.seccode,
+  }),
+});
+```
+
+GeeTest is a real browser solve, so it uses the longer `recaptchaTimeout` budget
+rather than `defaultTimeout`.
+
+---
+
+## 6. ALTCHA — `altcha(url, { ... })`
+
+ALTCHA is not a recognition captcha. There is no image, audio or text to read:
+the site issues a proof-of-work challenge and the client must brute-force a
+number that satisfies it. A solve is therefore deterministic and cheap —
+typically milliseconds.
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `method` | string | Yes | `altcha` |
+| `pageurl` | string | Yes | Full URL of the page the challenge came from |
+| `challenge_url` | string | One of the two | Endpoint CapSkip fetches the challenge from |
+| `challenge_json` | string | One of the two | The challenge document itself, as a JSON string |
+| `json` | int | No | `0` plain text, `1` JSON |
+| `proxy` | string | No | Proxy address — used **only** for the `challenge_url` fetch |
+| `proxytype` | string | No | Proxy type |
+
+Sending both challenge parameters is allowed: the inline `challengeJson` wins,
+because fetching would only re-obtain what you already supplied.
+
+### Getting the challenge
+
+Open DevTools → Network on the target page and look for the request the
+`<altcha-widget>` makes for its challenge (often something like
+`/altcha/challenge`). The request URL is your `challengeUrl`; its JSON response
+is your `challengeJson`.
+
+The widget attribute that names that endpoint depends on the widget version, so
+read the page source rather than assuming:
+
+| Widget | Attribute |
+|---|---|
+| v1 / v2 | `challengeurl="…"`, with a separate `challengejson="…"` for an inline challenge |
+| v3+ | `challenge="…"` — the same attribute takes either a URL or the challenge data |
+
+> **Challenges expire, and the window is short** — some sites inside two minutes.
+> Once expired, the site refuses the solution with a bare "verification failed"
+> that looks exactly like a wrong answer. Fetch the challenge immediately before
+> solving and submit the token promptly; do not fetch a batch in advance, and do
+> not hold a token while a user fills in a form.
+>
+> CapSkip refuses an already-expired inline challenge immediately rather than
+> burning CPU on a token that cannot work. If you passed `challengeUrl` and the
+> challenge expired while the job queued, it fetches a fresh one automatically.
+
+### SDK usage
+
+```js
+// CapSkip fetches the challenge for you
+const result = await solver.altcha('https://example.com/signup', {
+  challengeUrl: 'https://example.com/captcha/api/altcha/challenge',
+});
+
+// …or hand it the document you already have. No network request at all.
+const inline = await solver.altcha('https://example.com/signup', {
+  challengeJson: {
+    algorithm: 'SHA-256', challenge: '…', salt: '…',
+    signature: '…', maxnumber: 1000000,
+  },
+});
+
+result.token;    // the base64 payload to post back
+result.number;   // the counter that solved it
+result.code;     // the same string as token
+```
+
+`challengeJson` accepts an object (serialized for you) or a JSON string.
+
+`number` is reported for both ALTCHA generations. Their tokens differ — a legacy
+payload carries it as a top-level `number`, while a proof-of-work v2 payload has
+none, its counter sitting at `solution.counter` — so it is read from the server's
+own `solution` object, which reports both the same way.
+
+Post the token back in the form field the widget uses, named `altcha`:
+
+```js
+await fetch(SIGNUP_URL, {
+  method: 'POST',
+  body: new URLSearchParams({
+    email: 'someone@example.com',
+    altcha: result.token,
+  }),
+});
+```
+
+Do not re-encode, trim or re-order the token: it is base64 of a JSON document
+whose fields are covered by the server's HMAC signature, so any modification
+invalidates it. Some integrations read the payload from a JSON body field
+instead — check what the page's own submit sends and mirror it.
+
+Unlike GeeTest and reCAPTCHA this is CPU proof-of-work rather than a browser
+solve, so it uses `defaultTimeout`, not `recaptchaTimeout`.
+
+### Algorithms
+
+CapSkip supports the legacy scheme (SHA-1/256/384/512) and PoW v2 with PBKDF2 or
+SHA. **Argon2id and scrypt are refused**, not attempted: a task using one returns
+`ERROR_CAPTCHA_UNSOLVABLE` and is never retried. ALTCHA itself recommends PBKDF2
+as the default, so this affects a minority of sites.
+
+All three widget types (`native`, `checkbox`, `switch`) work — the distinction is
+purely visual and never reaches CapSkip.
+
+---
+
 ## Return value
 
 Every solve method resolves to:
@@ -218,6 +389,31 @@ Every solve method resolves to:
 }
 ```
 
+ALTCHA additionally exposes `token` (the same string as `code`, named for the
+form field it goes in) and `number`, the counter that solved it:
+
+```js
+{
+  captchaId: '12345',
+  code: 'eyJhbGdvcml0aG0iOiJTSEEtMjU2Iiwi…',
+  token: 'eyJhbGdvcml0aG0iOiJTSEEtMjU2Iiwi…',
+  number: 9661,
+}
+```
+
+GeeTest additionally expands its answer into `challenge`, `validate`, and
+`seccode` (`code` keeps the raw JSON string):
+
+```js
+{
+  captchaId: '12345',
+  code: '{"geetest_challenge":"...","geetest_validate":"...","geetest_seccode":"..."}',
+  challenge: '...',
+  validate: '...',
+  seccode: '...',
+}
+```
+
 ---
 
 ## SDK parameter aliases
@@ -231,6 +427,10 @@ Convenience aliases mapped before sending to CapSkip:
 | `minScore` | `min_score` |
 | `datas` | `data-s` |
 | `data_s` | `data-s` |
+| `apiServer` | `api_server` |
+| `api_subdomain` | `api_server` |
+| `challengeUrl` / `challengeURL` | `challenge_url` |
+| `challengeJson` / `challengeJSON` | `challenge_json` |
 | `proxy` object | `proxy` + `proxytype` strings |
 
 ```js

package/docs/GETTING_STARTED.md

@@ -136,6 +136,7 @@ node examples/recaptcha.js
 | `image_captcha.js` | Image captcha from file, URL, or base64 |
 | `recaptcha.js` | reCAPTCHA v2, v3, invisible, enterprise, proxy |
 | `turnstile.js` | Cloudflare Turnstile widget and challenge page |
+| `geetest.js` | GeeTest v3 slider, including fetching a fresh `gt`/`challenge` pair |
 | `async_example.js` | Parallel solving |
 | `verify_connection.js` | Check CapSkip is running |
 

package/docs/TROUBLESHOOTING.md

@@ -152,6 +152,48 @@ const result = await solver.recaptcha('...', '...', { proxy });
 
 ---
 
+## GeeTest keeps failing with a bad-challenge error
+
+**Symptom:** `geetest()` rejects with `ApiException` (or times out) even though
+`gt` and `challenge` were copied correctly from the page.
+
+**Cause:** The `challenge` value is **single-use and expires in about a minute**.
+A pair copied out of DevTools minutes earlier, cached in a config file, or reused
+across two solves is already dead.
+
+**Fix:** Fetch a fresh pair programmatically immediately before each solve, and on
+failure request a *new* pair rather than retrying the old one:
+
+```js
+const { gt, challenge } = await (await fetch(REGISTER_URL)).json();
+const result = await solver.geetest(gt, challenge, PAGE_URL);
+```
+
+If the site loads GeeTest from a non-default API server domain, pass it through as well:
+
+```js
+await solver.geetest(gt, challenge, url, { api_server: 'api-na.geetest.com' });
+```
+
+---
+
+## GeeTest result — where are challenge/validate/seccode?
+
+`result.code` holds the raw JSON string CapSkip returns. The SDK also parses it
+for you, so prefer the individual fields:
+
+```js
+result.challenge;   // geetest_challenge
+result.validate;    // geetest_validate
+result.seccode;     // geetest_seccode
+```
+
+Submit all three under their `geetest_`-prefixed names, exactly as the site's own
+front-end does. Sending only `validate` is the most common reason a correct solve
+is rejected.
+
+---
+
 ## NetworkException during manual polling
 
 **Symptom:** `getResult()` keeps rejecting with `NetworkException`.