Skip to content

Add GeeTest v3 support (v1.1.0) - #1

Merged
capskip merged 1 commit into
mainfrom
feat/geetest-v3
Jul 25, 2026
Merged

Add GeeTest v3 support (v1.1.0)#1
capskip merged 1 commit into
mainfrom
feat/geetest-v3

Conversation

@capskip

@capskip capskip commented Jul 25, 2026

Copy link
Copy Markdown
Owner

Adds GeeTest v3 (slide) solving to the Node SDK, matching the GeeTest v3 API docs.

What's new

const result = await solver.geetest(
  '81388ea1fc187e0c335c0a8907ff2625',
  '7cf6a8b1a2c34d5e6f7089abcdef0123',
  'https://example.com/login',
);

result.challenge;   // geetest_challenge
result.validate;    // geetest_validate
result.seccode;     // geetest_seccode

Available on CapSkip and the AsyncCapSkip alias, with TypeScript definitions.

Design notes

  • code keeps the raw JSON string CapSkip returns, so code ported from another solver's API still works. The parsed fields are added alongside it — unlike every other captcha type, code alone is not directly usable for GeeTest. An unparseable payload is passed through untouched rather than masked.
  • Submit params are limited to the documented setgt, challenge, pageurl, api_server, json, proxy, proxytype. All three required fields are checked locally, so a missing value fails before the round-trip instead of returning ERROR_BAD_PARAMETERS / ERROR_PAGEURL.
  • Uses the longer recaptchaTimeout budget rather than defaultTimeout, since GeeTest is a real browser solve with internal retries. A caller-supplied timeout still wins. No new constructor option was added.
  • apiServer / api_subdomain are accepted as aliases for api_server.

Also included

proxytype is now validated against the values CapSkip actually maps — 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. Image captcha is excluded so it keeps its clearer "proxy is not supported" message.

This touches reCAPTCHA and Turnstile as well as GeeTest, since they share the same submit path.

The README intro also drops its "no cloud service" phrasing; the sentence still makes the local / no-per-solve-fee point.

Testing

  • 71 unit tests pass (up from 57), covering the submit payload, api_server and its aliases, proxy handling, solution-field expansion, non-JSON payloads, the required-field checks, and every accepted/rejected proxy type.
  • Verified end-to-end against a live CapSkip instance — 31/31 checks, run against the packed npm tarball installed into a clean project, not the source tree. That also confirms src/ and types/ ship correctly under the files allowlist. 5/5 GeeTest solves, averaging 13.4s.
  • Image captcha, reCAPTCHA v2 and Turnstile all still solve, and the new fields never leak into their results. Reusing a burned challenge surfaces a clear ApiException rather than hanging.

Docs

README, tutorial (new section 8), API reference, getting started, troubleshooting, and changelog all updated. Version bumped to 1.1.0 in both package.json and src/index.js; geetest added to the keywords.

Note

The server also supports GeeTest v4 (method=geetest_v4, captcha_id), which this PR does not add.

Adds geetest(gt, challenge, url, options) to CapSkip (and so the AsyncCapSkip
alias), wrapping CapSkip's method=geetest endpoint.

The answer comes back as a JSON string in `request`. It stays verbatim in
`code`, so code ported from another solver's API keeps working, and is also
expanded into `challenge`, `validate`, and `seccode` for direct use — unlike
every other captcha type, `code` alone is not directly usable here. An
unparseable payload is passed through untouched rather than masked.

Submit params are limited to the documented set (gt, challenge, pageurl,
api_server, json, proxy, proxytype); all three required fields are checked
locally so a missing value fails before the round-trip.

GeeTest uses the longer recaptchaTimeout budget rather than defaultTimeout,
since it is a real browser solve with internal retries. A caller-supplied
timeout still wins.

Also validates proxytype against the values CapSkip actually maps (HTTP,
HTTPS, SOCKS5, SOCKS5H, case-insensitive) for every proxy-capable captcha
type. SOCKS4 and other values previously reached the server and returned
ERROR_BAD_PARAMETERS; they now raise ValidationException locally. Image
captcha is excluded so it keeps its clearer "proxy not supported" message.

TypeScript definitions cover geetest(), GeetestOptions, and the new
SolveResult fields.

Drops the "no cloud service" phrasing from the README intro; the sentence
still makes the local / no-per-solve-fee point.

Verified end-to-end against a live CapSkip instance, both from source and
from the packed npm tarball: 5/5 GeeTest solves, with image captcha,
reCAPTCHA v2, and Turnstile unaffected.
@capskip
capskip merged commit 386a929 into main Jul 25, 2026
10 checks passed
@capskip
capskip deleted the feat/geetest-v3 branch July 25, 2026 19:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant