capskip 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.6.0] - 2026-11-05
+
+### Added
+
+- **hCaptcha support** via `hcaptcha(sitekey, url, options)`, sent as
+  `method=hcaptcha`. The arguments follow 2Captcha's `hcaptcha({ sitekey,
+  pageurl, ... })` in this SDK's usual shape; `pageurl` in `options` is accepted
+  in place of `url`. Checkbox, invisible and hCaptcha Enterprise widgets all use
+  this one method.
+- Optional parameters: `invisible` (`1` or `true` for an invisible widget),
+  `data` (the Enterprise `rqdata`), `userAgent` / `useragent`, and `proxy`.
+- The result carries the token as both `code` and `token`, `respKey` (always
+  present, empty when the widget handed out none) and `userAgent`, the
+  User-Agent the token was earned with. Polled results now carry a `respKey`
+  field whenever the server sends one.
+- TypeScript definitions for `HCaptchaOptions` and the `hcaptcha()` method;
+  `SolveResult.respKey` now documents hCaptcha.
+- `examples/hcaptcha.js`.
+
+### Notes
+
+- Refused locally, before a round-trip: a missing or blank sitekey, a page URL
+  that is missing or not an absolute http(s) address, an `invisible` value other
+  than 0/1/true/false, and any parameter the CapSkip hCaptcha API does not take
+  (2Captcha's `domain` among them).
+- `invisible` is sent as `1`, or left out when off, so a boolean never reaches
+  the server as the string `true` or `false`. An optional passed as `''` is
+  treated as not sent.
+- hCaptcha uses `recaptchaTimeout`: the widget is passed in a real browser.
+
 ## [1.5.0] - 2026-11-02
 
 ### Added

package/README.md

@@ -5,7 +5,7 @@
 [![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)
 
-**Solve reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha, AWS WAF, DataDome and image captchas from Node.js.**
+**Solve reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha, AWS WAF, DataDome, hCaptcha and image captchas from Node.js.**
 
 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.
 
@@ -19,7 +19,7 @@ npm install capskip
 
 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()`, `capy()`, `captchafox()`, `friendlyCaptcha()`, `amazonWaf()`, `dataDome()`. Nothing leaves your network, and there is no credit balance to keep an eye on.
+This SDK is a thin wrapper over that API, with the method names you would expect: `normal()`, `recaptcha()`, `turnstile()`, `geetest()`, `altcha()`, `capy()`, `captchafox()`, `friendlyCaptcha()`, `amazonWaf()`, `dataDome()`, `hcaptcha()`. Nothing leaves your network, and there is no credit balance to keep an eye on.
 
 ## Supported captcha types
 
@@ -41,8 +41,9 @@ This SDK is a thin wrapper over that API, with the method names you would expect
 | **AWS WAF solver** (challenge page) | `solver.amazonWaf(sitekey, url, { iv, context })` |
 | AWS WAF (widget) | `solver.amazonWaf(sitekey, url, { jsapiScript })` |
 | **DataDome solver** (slider and device check) | `solver.dataDome(captchaUrl, url)` |
+| **hCaptcha solver** (checkbox, invisible and Enterprise) | `solver.hcaptcha(sitekey, url)` |
 
-**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()`.
+**FunCaptcha/Arkose is not supported.** hCaptcha and reCAPTCHA both put a `data-sitekey` on the widget, so tell them apart before choosing a method: `class="h-captcha"` or a `js.hcaptcha.com` script means `hcaptcha()`, `class="g-recaptcha"` means `recaptcha()`.
 
 Point the SDK at the [live captcha demo pages](https://capskip.com/captcha-demo/) to sanity-check your setup against real widgets.
 
@@ -138,7 +139,7 @@ const solver = new CapSkip({
   port: 8080,               // CapSkip port from app settings
   defaultTimeout: 120,      // seconds — image captcha polling timeout
   recaptchaTimeout: 300,    // seconds — reCAPTCHA / Turnstile / GeeTest / CaptchaFox /
-                            // Friendly Captcha / AWS WAF / DataDome polling timeout
+                            // Friendly Captcha / AWS WAF / DataDome / hCaptcha polling timeout
                             // (ALTCHA and Capy use defaultTimeout — neither is a browser solve)
   pollingInterval: 5,       // max seconds between res.php polls (starts at 0.25s, backs off to this)
 });
@@ -420,6 +421,56 @@ A block page whose `dd` object carries `'t':'bv'` means DataDome has banned the
 address that fetched it; no solve from there can pass, so it is refused before
 the request is sent. Change the address and request the page again.
 
+### hCaptcha
+
+hCaptcha is the checkbox widget behind many sign-up, login and checkout forms.
+CapSkip passes the widget for the sitekey and page you send and returns the
+token. The arguments follow 2Captcha's `hcaptcha({ sitekey, pageurl, ... })` in
+this SDK's usual shape, `hcaptcha(sitekey, url, options)`, and invisible and
+Enterprise widgets use the same method.
+
+```js
+const result = await solver.hcaptcha(
+  'a5f74b19-9e45-40e0-b45d-47ff91b7a6c2', // data-sitekey of the widget
+  'https://accounts.hcaptcha.com/demo',   // the page the widget is on
+  {
+    // invisible: 1,                // for a widget with data-size="invisible"
+    // data: '...',                 // hCaptcha Enterprise: the rqdata the page passes to hcaptcha.setData()
+    // userAgent: 'Mozilla/5.0 ...',// the User-Agent you will submit the form with
+    // proxy: { type: 'HTTP', uri: 'login:password@203.0.113.10:8080' },
+  },
+);
+
+result.token;     // put it in h-captcha-response (and g-recaptcha-response, if present)
+result.respKey;   // the second value hCaptcha hands the widget; usually empty or unused
+result.userAgent; // the User-Agent the token was earned with
+```
+
+The sitekey is on the widget container as `data-sitekey`, in the `sitekey`
+option of `hcaptcha.render()`, or in the `sitekey=` parameter of the hCaptcha
+iframe's address. An Enterprise `rqdata` value is issued for one challenge and
+expires quickly, so read a fresh one for every task.
+
+Put the token in the form's `h-captcha-response` field (and `g-recaptcha-response`,
+if the form has one), or pass it to the widget's `data-callback`, and submit with
+the User-Agent from the result. Tokens are single use and expire about two
+minutes after they are issued, so submit each one soon.
+
+```js
+await page.evaluate((token) => {
+  document.querySelector('[name="h-captcha-response"]').value = token;
+  const g = document.querySelector('[name="g-recaptcha-response"]');
+  if (g) g.value = token;
+}, result.token);
+```
+
+A `userAgent` you send is used only when it matches the browser CapSkip solves
+with; the result always names the one the token was actually earned with. At
+volume, hCaptcha scores the network a token comes from as well as the browser,
+so send a proxy with each task or configure a pool in the CapSkip app (Settings,
+Captcha types, hCaptcha, Configure Proxies). If a strict site still refuses the
+tokens, turn on High score mode for hCaptcha in the same settings page.
+
 ### With a proxy (every method except image captcha)
 
 ```js
@@ -523,7 +574,8 @@ expanded into `captcha_voucher` and `existing_token`. ALTCHA adds `token` (the s
 string as `code`) and `number`, the counter that solved it. DataDome adds
 `cookie`, the `datadome=...` pair alone, while `code` keeps the cookie with its
 attributes; it also carries `userAgent`, and `proxy` when CapSkip chose the
-proxy.
+proxy. hCaptcha adds `token`, the same string as `code`, `respKey` (always
+present, empty when the widget handed out none) and `userAgent`.
 
 ---
 
@@ -568,7 +620,7 @@ const result: SolveResult = await solver.recaptcha('...', 'https://example.com')
 
 ### 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()`, `capy()`, `captchafox()`, `friendlyCaptcha()`, `amazonWaf()`, `dataDome()` or `normal()`. Each returns a Promise that resolves once CapSkip has an answer, giving you a token (a cookie for DataDome), or the recognized text in the case of an image captcha.
+Install the CapSkip desktop app, `npm install capskip`, then call the method that matches the widget — `recaptcha()`, `turnstile()`, `geetest()`, `altcha()`, `capy()`, `captchafox()`, `friendlyCaptcha()`, `amazonWaf()`, `dataDome()`, `hcaptcha()` or `normal()`. Each returns a Promise that resolves once CapSkip has an answer, giving you a token (a cookie for DataDome), or the recognized text in the case of an image captcha.
 
 ### Is this a free captcha solver?
 
@@ -576,7 +628,7 @@ The SDK itself is MIT-licensed and free. Solving needs the CapSkip app, which is
 
 ### Which captchas can it solve?
 
-reCAPTCHA v2 (checkbox and invisible), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, GeeTest v3, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha, AWS WAF, DataDome, and image/text captchas. Not hCaptcha, and not FunCaptcha/Arkose.
+reCAPTCHA v2 (checkbox and invisible), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, GeeTest v3, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha, AWS WAF, DataDome, hCaptcha (including invisible and Enterprise), and image/text captchas. Not FunCaptcha/Arkose.
 
 ### Does it work with Puppeteer and Playwright?
 

package/docs/API_REFERENCE.md

@@ -29,6 +29,7 @@ method returns a `Promise`.
 | Friendly Captcha (proof-of-work) | `friendlyCaptcha()` | `friendly_captcha` |
 | AWS WAF (challenge page or widget) | `amazonWaf()` | `amazon_waf` |
 | DataDome (slider and device check) | `dataDome()` | `datadome` |
+| hCaptcha (checkbox, invisible, Enterprise) | `hcaptcha()` | `hcaptcha` |
 
 **Proxy** is supported for every method except image captcha. For ALTCHA the
 proxy is used only for the `challengeUrl` fetch; for Capy, only for the
@@ -846,6 +847,85 @@ Uses `recaptchaTimeout`: the challenge is passed in a real browser.
 
 ---
 
+## 12. hCaptcha — `hcaptcha(sitekey, url, { ... })`
+
+hCaptcha is the checkbox widget behind many sign-up, login and checkout forms.
+CapSkip passes the widget for the sitekey and page you send and returns the
+token, ready to submit with the form. Invisible widgets and hCaptcha Enterprise
+use the same method. Public docs: <https://capskip.com/api-docs/#hcaptcha>.
+
+The arguments follow 2Captcha's `hcaptcha({ sitekey, pageurl, ... })` in this
+SDK's usual shape, so code written against it ports directly. `pageurl` in the
+options object is accepted in place of `url`.
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `method` | string | Yes | `hcaptcha` |
+| `sitekey` | string | Yes | The widget's sitekey (`data-sitekey`) |
+| `pageurl` | string | Yes | Full http or https URL of the page the widget is on |
+| `invisible` | int | No | `1` for an invisible widget (`data-size="invisible"`). The SDK takes `1`/`0`, `true`/`false` or `'1'`/`'0'`/`'true'`/`'false'`, sends `1`, and leaves it out when off |
+| `data` | string | No | hCaptcha Enterprise: the `rqdata` value the page passes to `hcaptcha.setData()`. Single use; fetch a fresh one per task |
+| `userAgent` | string | No | The User-Agent you will submit the form with. Used only when it matches CapSkip's browser. Sent as `useragent` |
+| `json` | int | No | `0` plain text, `1` JSON |
+| `proxy` | string | No | Proxy address |
+| `proxytype` | string | No | `HTTP`, `HTTPS`, `SOCKS5` or `SOCKS5H` |
+
+An optional left `undefined`, `null` or `''` is not sent.
+
+Refused locally with `ValidationException`, as CapSkip would refuse them: a
+missing or blank sitekey (`ERROR_RECAPTCHA_INVALID_SITEKEY`), a `pageurl` that
+is missing or not an absolute http(s) address (`ERROR_PAGEURL`), an `invisible`
+value other than 0/1/true/false, and any parameter not in the table, 2Captcha's
+`domain` among them.
+
+### GET `/res.php`
+
+The SDK polls with `json=1`, where CapSkip returns the token in `request` with
+`respKey` and the User-Agent the token was earned with:
+
+```json
+{
+  "status": 1,
+  "request": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.hadwYXNza2V5xQZ2...f3Kq8nV2",
+  "respKey": "E0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6IjA0...9wB1",
+  "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/156.0.0.0 Safari/537.36"
+}
+```
+
+(In plain-text mode the User-Agent arrives in the `X-HCaptcha-User-Agent`
+response header.) A task that hCaptcha refused the sitekey for fails with
+`ERROR_RECAPTCHA_INVALID_SITEKEY`, one whose proxy could not be reached with
+`ERROR_PROXY_CONNECT_REFUSED`; resubmitting the same task would fail again.
+
+### SDK usage
+
+```js
+const result = await solver.hcaptcha(
+  'a5f74b19-9e45-40e0-b45d-47ff91b7a6c2',
+  'https://accounts.hcaptcha.com/demo',
+);
+
+// Invisible Enterprise widget, through a proxy
+const result = await solver.hcaptcha(sitekey, pageUrl, {
+  invisible: 1,
+  data: rqdata,
+  proxy: { type: 'HTTP', uri: 'login:password@203.0.113.10:8080' },
+});
+
+form['h-captcha-response'] = result.token;
+form['g-recaptcha-response'] = result.token; // if the form has one
+headers['User-Agent'] = result.userAgent;
+```
+
+Tokens are single use and expire about two minutes after they are issued.
+
+Uses `recaptchaTimeout`: the widget is passed in a real browser.
+
+---
+
 ## Return value
 
 Every solve method resolves to:
@@ -925,6 +1005,20 @@ only when the task sent no proxy and CapSkip used its own DataDome proxy list:
 }
 ```
 
+hCaptcha exposes `token`, the same string as `code`, plus `respKey` and the
+User-Agent the token was earned with. `respKey` is always present, and empty
+when the widget handed out none:
+
+```js
+{
+  captchaId: '12345',
+  code: 'P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9…',
+  token: 'P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9…',
+  respKey: 'E0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9…',
+  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) …',
+}
+```
+
 GeeTest additionally expands its answer into `challenge`, `validate`, and
 `seccode` (`code` keeps the raw JSON string):
 

package/examples/hcaptcha.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * Solve an hCaptcha widget.
+ *
+ * hCaptcha is the checkbox widget behind many sign-up, login and checkout
+ * forms. CapSkip passes the widget in a real browser for the sitekey and page
+ * you send and returns the token the widget would have put in the form.
+ * Invisible widgets and hCaptcha Enterprise use the same method.
+ *
+ * You need two values, both read off the target page:
+ *
+ *   * sitekey - the public identifier of the widget, the same for every
+ *     visitor. Most pages carry it on the container as `data-sitekey`:
+ *     `<div class="h-captcha" data-sitekey="...">`. When a page builds the
+ *     widget with a script, look for the `sitekey` option of
+ *     `hcaptcha.render()`, or the `sitekey=` parameter in the address of the
+ *     hCaptcha iframe.
+ *   * url - the full URL of the page the widget is on.
+ *
+ * A widget with `data-size="invisible"` is invisible: pass `invisible: 1`.
+ * Some hCaptcha Enterprise sites pass an `rqdata` value to the widget through
+ * `hcaptcha.setData()` before it runs; send it as `data`. It is issued for one
+ * challenge and expires quickly, so read a fresh one for every task.
+ */
+
+const assert = require('node:assert');
+const { CapSkip } = require('capskip');
+
+const solver = new CapSkip({
+  apiKey: process.env.CAPSKIP_API_KEY || 'capskip',
+  host: process.env.CAPSKIP_HOST || '127.0.0.1',
+  port: Number(process.env.CAPSKIP_PORT || 8080),
+});
+
+// hCaptcha's own public demo page and its sitekey.
+const SITEKEY = 'a5f74b19-9e45-40e0-b45d-47ff91b7a6c2';
+const PAGE_URL = 'https://accounts.hcaptcha.com/demo';
+
+async function main() {
+  const result = await solver.hcaptcha(SITEKEY, PAGE_URL);
+
+  console.log('Captcha ID:', result.captchaId);
+  console.log('Token:     ', `${result.token.slice(0, 60)}...`);
+  console.log('respKey:   ', result.respKey ? `${result.respKey.slice(0, 40)}...` : '(empty)');
+  console.log('User-Agent:', result.userAgent || '(none reported)');
+
+  // --- Invisible and Enterprise widgets ------------------------------------
+  //
+  //   const result = await solver.hcaptcha(SITEKEY, PAGE_URL, {
+  //     invisible: 1,   // data-size="invisible"
+  //     data: rqdata,   // the rqdata the page passed to hcaptcha.setData()
+  //   });
+  //
+  // --- With a per-request proxy --------------------------------------------
+  // CapSkip does not force a proxy. At volume, though, hCaptcha scores the
+  // network a token comes from as well as the browser, so send a proxy with
+  // each task (or configure a pool in the app: Settings, Captcha types,
+  // hCaptcha, Configure Proxies). A proxy sent with a task always takes
+  // priority over the pool.
+  //
+  //   const result = await solver.hcaptcha(SITEKEY, PAGE_URL, {
+  //     proxy: { type: 'HTTP', uri: 'login:password@1.2.3.4:8080' },
+  //   });
+
+  // --- Submitting the token ------------------------------------------------
+  // The widget writes its token into a hidden textarea named
+  // h-captcha-response (and a copy named g-recaptcha-response). Put the token
+  // in both and submit the form, or call the widget's data-callback with it.
+  // Without a browser, post it as those form fields with the User-Agent from
+  // the result:
+  //
+  //   await fetch(FORM_URL, {
+  //     method: 'POST',
+  //     headers: { 'User-Agent': result.userAgent },
+  //     body: new URLSearchParams({
+  //       email: 'someone@example.com',
+  //       'h-captcha-response': result.token,
+  //       'g-recaptcha-response': result.token,
+  //     }),
+  //   });
+  //
+  // Tokens are single use and expire about two minutes after they are issued,
+  // so submit each one soon and solve again for the next form submission.
+  console.log('Form fields:', {
+    'h-captcha-response': `${result.token.slice(0, 40)}...`,
+    'g-recaptcha-response': `${result.token.slice(0, 40)}...`,
+  });
+
+  // `code` holds the same string as `token`, which is what you forward if you
+  // are porting code written against another solver's API.
+  assert.strictEqual(result.code, result.token);
+}
+
+main().catch((error) => {
+  console.error(`${error.name}: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "capskip",
-  "version": "1.5.0",
-  "description": "Captcha solver for Node.js: solve reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest, AWS WAF, DataDome and image captchas with CapSkip, a local unlimited captcha solver with no per-solve fees.",
+  "version": "1.6.0",
+  "description": "Captcha solver for Node.js: solve reCAPTCHA v2/v3, Cloudflare Turnstile, hCaptcha, GeeTest, AWS WAF, DataDome and image captchas with CapSkip, a local unlimited captcha solver with no per-solve fees.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
   "exports": {
@@ -33,6 +33,9 @@
     "recaptcha-v2",
     "recaptcha-v3",
     "recaptcha-enterprise",
+    "hcaptcha",
+    "hcaptcha-solver",
+    "hcaptcha-enterprise",
     "cloudflare",
     "turnstile",
     "turnstile-solver",

package/src/apiParams.js

@@ -59,6 +59,18 @@ const AMAZON_WAF_SCRIPTS = ['challenge_script', 'captcha_script', 'jsapiScript']
 // the three AWS WAF script files.
 const AMAZON_WAF_SCRIPT_PATH = /^(\/[A-Za-z0-9_-]+)+\/(challenge|captcha|jsapi)\.js$/;
 
+const HCAPTCHA_SUBMIT = new Set([
+  'method', 'sitekey', 'pageurl', 'invisible', 'data', 'useragent', 'json',
+  'proxy', 'proxytype',
+]);
+
+// What the server reads as "invisible widget" ("1" or "true") and as its
+// default. Strings are matched case-insensitively. A boolean would otherwise
+// reach the form body as 'true' or 'false', and the server reads 'false' as
+// neither, so every accepted form is normalized to the 1 the server reads.
+const HCAPTCHA_INVISIBLE_ON = [true, 1, '1', 'true'];
+const HCAPTCHA_INVISIBLE_OFF = [false, 0, '0', 'false'];
+
 const DATADOME_SUBMIT = new Set([
   'method', 'captcha_url', 'pageurl', 'useragent', 'json', 'proxy', 'proxytype',
 ]);
@@ -648,6 +660,75 @@ function validateDataDomeSubmit(params) {
   }
 }
 
+/**
+ * Drop unset and empty optionals, and send `invisible` as the 1 the server
+ * reads. `invisible: 0` is the server's default, so it is not sent at all.
+ */
+function normalizeHCaptchaSubmit(params) {
+  const out = {};
+  for (const [key, value] of Object.entries(dropUnset(params))) {
+    if (value !== '') {
+      out[key] = value;
+    }
+  }
+  if (has(out, 'invisible')) {
+    const raw = out.invisible;
+    const key = typeof raw === 'string' ? raw.toLowerCase() : raw;
+    if (HCAPTCHA_INVISIBLE_ON.includes(key)) {
+      out.invisible = 1;
+    } else if (HCAPTCHA_INVISIBLE_OFF.includes(key)) {
+      delete out.invisible;
+    } else {
+      const shown = typeof raw === 'string' ? `'${raw}'` : String(raw);
+      throw new ValidationException(
+        `invisible must be 0 or 1 (or a boolean) for hCaptcha, not ${shown}.`,
+      );
+    }
+  }
+  return out;
+}
+
+/** An absolute http(s) URL with a host. */
+function isHttpUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (error) {
+    return false;
+  }
+  return (parsed.protocol === 'http:' || parsed.protocol === 'https:')
+    && parsed.hostname !== '';
+}
+
+function validateHCaptchaSubmit(params) {
+  // The server answers ERROR_RECAPTCHA_INVALID_SITEKEY for a missing sitekey
+  // and ERROR_PAGEURL for a page URL that is missing or not http(s). Fail
+  // locally so neither costs a round-trip.
+  const sitekey = params.sitekey;
+  if (sitekey === undefined || sitekey === null || !String(sitekey).trim()) {
+    throw new ValidationException("'sitekey' is required for hCaptcha.");
+  }
+  const rawPageurl = params.pageurl;
+  const pageurl = rawPageurl === undefined || rawPageurl === null
+    ? ''
+    : String(rawPageurl).trim();
+  if (!pageurl) {
+    throw new ValidationException("'pageurl' is required for hCaptcha.");
+  }
+  if (!isHttpUrl(pageurl)) {
+    throw new ValidationException(
+      `pageurl must be an absolute http or https URL for hCaptcha, not '${pageurl}'.`,
+    );
+  }
+
+  const unknown = unknownKeys(params, HCAPTCHA_SUBMIT);
+  if (unknown.length > 0) {
+    throw new ValidationException(
+      `Unsupported parameters for hCaptcha: ${reprList(unknown)}.`,
+    );
+  }
+}
+
 function validateProxyType(params) {
   const proxytype = params.proxytype;
   if (proxytype === undefined || proxytype === null || proxytype === '') {
@@ -691,6 +772,9 @@ function prepareSubmitParams(params, captchaType, version = 'v2') {
   } else if (captchaType === 'datadome') {
     prepared = normalizeDataDomeSubmit(prepared);
     validateDataDomeSubmit(prepared);
+  } else if (captchaType === 'hcaptcha') {
+    prepared = normalizeHCaptchaSubmit(prepared);
+    validateHCaptchaSubmit(prepared);
   }
 
   // Skipped for 'normal', which rejects proxy outright with a clearer message.
@@ -716,6 +800,7 @@ module.exports = {
   DATADOME_SUBMIT,
   DATADOME_CHALLENGE_DOMAIN,
   DATADOME_CHALLENGE_PATHS,
+  HCAPTCHA_SUBMIT,
   CAPY_VERSIONS,
   FRIENDLY_CAPTCHA_VERSIONS,
   PROXY_TYPES,
@@ -740,6 +825,8 @@ module.exports = {
   isDataDomeUserAgent,
   normalizeDataDomeSubmit,
   validateDataDomeSubmit,
+  normalizeHCaptchaSubmit,
+  validateHCaptchaSubmit,
   validateProxyType,
   prepareSubmitParams,
 };

package/src/index.js

@@ -27,5 +27,5 @@ module.exports = {
   NetworkException,
   ApiException,
   TimeoutException,
-  version: '1.5.0',
+  version: '1.6.0',
 };

package/src/solver.js

@@ -89,6 +89,11 @@ function applyPollResult(result, polled) {
     if (polled.proxy) {
       result.proxy = polled.proxy;
     }
+    // hCaptcha hands the widget a second value next to the token. It is
+    // carried even when empty, which is how the server reports "none".
+    if (Object.prototype.hasOwnProperty.call(polled, 'respKey')) {
+      result.respKey = polled.respKey;
+    }
     // ALTCHA's createTask-shaped `solution` object. Carried through so
     // applyAltchaSolution can read the counter the server already worked out,
     // which is the only reliable source for a proof-of-work v2 answer; that
@@ -325,6 +330,20 @@ function applyTokenSolution(result) {
   return result;
 }
 
+/**
+ * Expose the hCaptcha token as `token`, next to its `respKey`.
+ *
+ * `code` keeps the token as the server sent it and `token` is the same string,
+ * for the `h-captcha-response` field. `respKey` is always present, empty when
+ * the widget handed out none, so callers can read it without a key check.
+ */
+function applyHCaptchaSolution(result) {
+  applyTokenSolution(result);
+  const { respKey } = result;
+  result.respKey = typeof respKey === 'string' ? respKey : '';
+  return result;
+}
+
 // CapSkip's in.php returns OK|<id> by default, or {"status":1,"request":"<id>"}
 // when the submit carried json=1. Accept both so submitting with json=1 works.
 function parseSubmitResponse(response) {
@@ -351,7 +370,7 @@ function parseSubmitResponse(response) {
 /**
  * Client for the CapSkip local captcha solver (image, reCAPTCHA, Turnstile,
  * GeeTest v3, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha, AWS WAF,
- * DataDome).
+ * DataDome, hCaptcha).
  */
 class CapSkip {
   constructor({
@@ -700,6 +719,61 @@ class CapSkip {
     return applyDataDomeSolution(result);
   }
 
+  /**
+   * Solve an hCaptcha widget and return its token.
+   *
+   * `sitekey` and `url` are required; everything else goes in `options`:
+   *
+   * - `sitekey` is the widget's `data-sitekey` (or the `sitekey` option of
+   *   `hcaptcha.render()`).
+   * - `url` is the full address of the page the widget is on. `pageurl` in
+   *   `options` is accepted in its place.
+   * - `options.invisible` is `1` (or `true`) for a `data-size="invisible"`
+   *   widget.
+   * - `options.data` is the `rqdata` value an hCaptcha Enterprise site passes
+   *   to `hcaptcha.setData()`. It is single use and expires quickly, so fetch
+   *   a fresh one for every task.
+   * - `options.userAgent` is the User-Agent you will submit the form with.
+   *   CapSkip uses it only when it matches the browser it solves with.
+   * - `options.proxy` is a URI string or
+   *   `{ type: 'HTTP', uri: 'login:password@IP:PORT' }`.
+   *
+   * hCaptcha Enterprise and invisible widgets use this same method.
+   *
+   * The result carries the token as both `code` and `token` (for the
+   * `h-captcha-response` and `g-recaptcha-response` fields), `respKey` (the
+   * second value hCaptcha hands the widget; most sites never read it, and it
+   * can be empty), and `userAgent`, the User-Agent the token was earned with.
+   * Submit the token with that User-Agent, soon: hCaptcha tokens are single
+   * use and expire about two minutes after they are issued.
+   */
+  async hcaptcha(sitekey, url, options = {}) {
+    // An unset value is dropped rather than sent as undefined, so
+    // `hcaptcha(sitekey, undefined, { pageurl })` reaches the alias without
+    // tripping the conflict check; an empty one is dropped during validation.
+    const given = {};
+    const add = (key, value) => {
+      if (value !== undefined && value !== null) {
+        given[key] = value;
+      }
+    };
+    add('sitekey', sitekey);
+    add('url', url);
+    for (const [key, value] of Object.entries(options)) {
+      add(key, value);
+    }
+
+    // A real browser session, like reCAPTCHA, so it gets the longer of the
+    // two timeouts unless the caller asked for a specific one.
+    const result = await this.solve({
+      timeout: this.recaptchaTimeout,
+      ...given,
+      method: 'hcaptcha',
+      poll_json: 1,
+    });
+    return applyHCaptchaSolution(result);
+  }
+
   async solve(options = {}) {
     const {
       timeout = 0,
@@ -806,6 +880,9 @@ class CapSkip {
     if (method === 'datadome') {
       return prepareSubmitParams(params, 'datadome');
     }
+    if (method === 'hcaptcha') {
+      return prepareSubmitParams(params, 'hcaptcha');
+    }
     return applyProxy(applyParamAliases(params));
   }
 }
@@ -822,6 +899,7 @@ module.exports = {
   applyCapySolution,
   applyAmazonWafSolution,
   applyDataDomeSolution,
+  applyHCaptchaSolution,
   expandObjectAnswer,
   applyTokenSolution,
 };

package/types/index.d.ts

@@ -20,7 +20,7 @@ export interface CapSkipOptions {
   defaultTimeout?: number;
   /**
    * Seconds to poll reCAPTCHA / Turnstile / GeeTest / CaptchaFox / Friendly
-   * Captcha / AWS WAF / DataDome before timing out. Default `300`. ALTCHA and Capy use
+   * Captcha / AWS WAF / DataDome / hCaptcha before timing out. Default `300`. ALTCHA and Capy use
    * `defaultTimeout` instead — neither is a browser solve.
    */
   recaptchaTimeout?: number;
@@ -42,9 +42,9 @@ export interface SolveResult {
    */
   code: string | Record<string, unknown>;
   /**
-   * Turnstile, CaptchaFox and DataDome — the User-Agent to use when submitting
-   * the token. For CaptchaFox this is the browser's own, not one you sent, and
-   * it is absent when the solve captured none rather than guessed. For DataDome
+   * Turnstile, CaptchaFox, hCaptcha and DataDome — the User-Agent to use when
+   * submitting the token. For CaptchaFox and hCaptcha this is the browser's own,
+   * not one you sent, and it is absent when the solve reported none. For DataDome
    * it is the User-Agent the cookie was earned with — the one you sent, or
    * CapSkip's own browser's — and every request carrying the cookie must send it.
    */
@@ -72,7 +72,12 @@ export interface SolveResult {
    */
   answer?: string;
   /**
-   * Capy only — empty for a puzzle solve. Present for shape compatibility with
+   * hCaptcha — the second value hCaptcha hands the widget next to the token.
+   * Always present on an `hcaptcha()` result, `''` when the widget handed out
+   * none; most sites never read it. Other polled results carry it only when
+   * the server sent one.
+   *
+   * Capy — empty for a puzzle solve. Present for shape compatibility with
    * 2Captcha's documented response; it carries nothing.
    */
   respKey?: string;
@@ -324,6 +329,43 @@ export interface DataDomeOptions {
   [key: string]: unknown;
 }
 
+/** Extra options for {@link CapSkip.hcaptcha}. */
+export interface HCaptchaOptions {
+  /** The page URL (alias for the `url` argument). */
+  pageurl?: string;
+  /** The page URL (alias for the `url` argument). */
+  url?: string;
+  /**
+   * `1` / `true` for a `data-size="invisible"` widget; `0` / `false` (the
+   * default) is not sent. The strings `"1"`, `"0"`, `"true"` and `"false"`
+   * are accepted too; anything else is refused.
+   */
+  invisible?: boolean | 0 | 1 | '0' | '1' | 'true' | 'false';
+  /**
+   * hCaptcha Enterprise `rqdata`, the value the site passes to
+   * `hcaptcha.setData()`. Single use and short-lived: fetch a fresh one per task.
+   */
+  data?: string;
+  /**
+   * The User-Agent you will submit the form with. CapSkip uses it only when it
+   * matches the browser it solves with.
+   */
+  userAgent?: string;
+  /** Alias for `userAgent`. */
+  useragent?: string;
+  /** Proxy used for solving. */
+  proxy?: Proxy | string;
+  /** Proxy type when `proxy` is a bare string. Default `HTTP`. */
+  proxytype?: string;
+  /** Poll timeout in seconds. Default: the client's `recaptchaTimeout`. */
+  timeout?: number;
+  /** Max seconds between polls for this solve. */
+  polling_interval?: number;
+  /** `1` to request the raw JSON response from CapSkip. */
+  json?: number;
+  [key: string]: unknown;
+}
+
 /** Options for the {@link CapSkip.solve} manual workflow. */
 export interface SolveOptions {
   /** Poll timeout in seconds (falls back to the configured default). */
@@ -436,6 +478,22 @@ export class CapSkip {
     url: string,
     options?: DataDomeOptions,
   ): Promise<SolveResult>;
+  /**
+   * Solve an hCaptcha widget (checkbox, invisible or Enterprise) and return
+   * its token.
+   *
+   * `sitekey` is the widget's `data-sitekey`, `url` the page it is on
+   * (`options.pageurl` is accepted in its place). The result carries the token
+   * as `code` and `token` (for `h-captcha-response` and
+   * `g-recaptcha-response`), `respKey` (always present, `''` when none) and
+   * `userAgent`, the User-Agent the token was earned with. Tokens are single
+   * use and expire about two minutes after they are issued.
+   */
+  hcaptcha(
+    sitekey: string,
+    url: string | undefined,
+    options?: HCaptchaOptions,
+  ): Promise<SolveResult>;
   /** Submit then poll to completion. Used by the higher-level solve methods. */
   solve(options?: SolveOptions): Promise<SolveResult>;
   /** Submit a captcha without polling; resolves to the captcha id. */