capskip 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,72 @@ 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
+
+- **DataDome support** via `dataDome(captchaUrl, url, options)`, sent as
+  `method=datadome`, covering both DataDome challenges: the slider
+  (`/captcha/`) and the device check (`/interstitial/`). The arguments follow
+  2Captcha's `datadome(captcha_url, pageurl, userAgent, proxy)`, with
+  `userAgent` and `proxy` as optional options, as on every other method.
+- The result carries the cookie twice: `code` exactly as DataDome set it,
+  attributes included, and `cookie`, the `datadome=...` pair alone for a Cookie
+  header. `userAgent` is the User-Agent the cookie was earned with, the one sent
+  or CapSkip's own browser's.
+- `proxy` in the result: when a task is sent without a proxy and the CapSkip app
+  solves it through its own DataDome proxy list, the result names that proxy as
+  `host:port`. The cookie only works from that address, so it is reported
+  rather than dropped. Polled results now carry a `proxy` field whenever the
+  server sends one.
+- Parameter aliases `captchaUrl` / `captchaURL` for `captcha_url`.
+- TypeScript definitions for `DataDomeOptions`, plus the new `SolveResult`
+  fields `cookie` and `proxy`.
+- `examples/datadome.js`.
+
+### Notes
+
+- Refused locally, before a round-trip: a `captcha_url` that is not an https
+  challenge address on captcha-delivery.com carrying `initialCid`, `hash` and
+  `cid`; a block page that bans the requesting address (`t=bv`); a `pageurl`
+  that is not http(s), or is on captcha-delivery.com; and a `userAgent` that is
+  not stock Chrome for Windows. CapSkip itself checks that the Chrome major
+  version matches its browser and answers `ERROR_WRONG_USERAGENT` when it does
+  not. An optional passed as `''` is treated as not sent.
+- An iframe `src` copied HTML-escaped (`&`) is accepted, as the server
+  decodes it, and is sent unchanged.
+- DataDome uses `recaptchaTimeout`: the challenge is passed in a real browser.
+
 ## [1.4.0] - 2026-11-01
 
 ### 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 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()`. 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
 
@@ -40,8 +40,10 @@ This SDK is a thin wrapper over that API, with the method names you would expect
 | **Friendly Captcha solver** (proof-of-work) | `solver.friendlyCaptcha(sitekey, url, { version })` |
 | **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.
 
@@ -137,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 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)
 });
@@ -357,6 +359,118 @@ https URL on an `awswaf.com` host. CapSkip posts the solution to the host the
 script names, so anything else is refused before the request is made. See the
 [AWS WAF API docs](https://capskip.com/api-docs/#aws-waf).
 
+### DataDome
+
+DataDome answers a request it doubts with a block page (status 403, sometimes
+401) instead of the site. CapSkip passes the challenge on that page, a slider
+or a device check, and returns the `datadome` cookie that lets your requests
+through. The arguments follow 2Captcha's `datadome(captcha_url, pageurl,
+userAgent, proxy)`, with `userAgent` and `proxy` as optional options.
+
+```js
+const result = await solver.dataDome(
+  'https://geo.captcha-delivery.com/captcha/?initialCid=...&hash=...&cid=...&t=fe&referer=...&s=45225&e=...&dm=cd',
+  'https://www.example.com/', // the page that returned the block page
+  {
+    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 '
+      + '(KHTML, like Gecko) Chrome/156.0.0.0 Safari/537.36',
+    proxy: { type: 'HTTP', uri: 'login:password@203.0.113.10:8080' },
+  },
+);
+
+result.cookie;    // "datadome=..." -- send it as the Cookie header
+result.code;      // the cookie exactly as DataDome set it: Max-Age, Domain, Path...
+result.userAgent; // the User-Agent the cookie was earned with
+result.proxy;     // set only when CapSkip picked the proxy, see below
+```
+
+`captchaUrl` is the address of the challenge iframe on
+`geo.captcha-delivery.com`: `/captcha/` for a slider, `/interstitial/` for a
+device check. Take the iframe's `src` when the block page has one; most build it
+with a script instead, so assemble it from the page's `var dd={...}` object as
+the [API docs](https://capskip.com/api-docs/#datadome) show. Each block page is
+a fresh challenge, so submit it soon and fetch the page again for the next task.
+
+**The cookie belongs to one IP address and one browser.** DataDome refuses it
+from any other address, or with any other User-Agent, so:
+
+- **Send the User-Agent you will use**, or none. It must be Chrome for Windows,
+  with the same major version as the browser CapSkip solves with; anything else
+  (Firefox, Safari, Edge, mobile, macOS) would earn a cookie the site rejects,
+  so it is refused before the request is sent, and a different Chrome major is
+  refused by CapSkip with `ERROR_WRONG_USERAGENT`. Send none and CapSkip uses
+  its own browser's: copy `result.userAgent` into your requests as it is.
+- **Solve from the address you will use the cookie from.** If your requests go
+  out through a proxy, pass that proxy with the task. If they come from the
+  machine running CapSkip, pass none.
+- **When CapSkip picks the proxy, it tells you which.** The CapSkip app has a
+  DataDome proxy list of its own (Settings, Captcha types, DataDome, Configure
+  Proxies). A task sent without a proxy is solved through that list, and the
+  result then carries `proxy` as `host:port`: send the cookie through that
+  proxy, or it will be refused. A proxy you send always takes priority over
+  the list, and then no `proxy` comes back.
+
+```js
+const headers = { 'User-Agent': result.userAgent, Cookie: result.cookie };
+// When result.proxy is set, route this request through it (it is named without
+// its login: add your credentials if it has one), e.g. with undici's ProxyAgent.
+const page = await fetch('https://www.example.com/', { headers });
+```
+
+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
@@ -457,7 +571,11 @@ Captcha add `token`, the same string as `code`. Capy expands its answer into
 `captchakey`, `challengekey` and `answer` — it returns an object rather than a
 token, and `code` keeps the raw answer. AWS WAF likewise returns an object,
 expanded into `captcha_voucher` and `existing_token`. ALTCHA adds `token` (the same
-string as `code`) and `number`, the counter that solved it.
+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. hCaptcha adds `token`, the same string as `code`, `respKey` (always
+present, empty when the widget handed out none) and `userAgent`.
 
 ---
 
@@ -502,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()` 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.
+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?
 
@@ -510,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, 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

@@ -28,6 +28,8 @@ method returns a `Promise`.
 | CaptchaFox (widget) | `captchafox()` | `captchafox` |
 | 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
@@ -713,6 +715,217 @@ for, and the puzzle rounds go through AWS on top of that.
 
 ---
 
+## 11. DataDome — `dataDome(captchaUrl, url, { ... })`
+
+DataDome is the bot protection behind many large shops, news sites and
+marketplaces. When it doubts a visitor, the site answers with a block page
+(status 403, sometimes 401) holding a slider or a short device check. CapSkip
+passes that challenge and returns the `datadome` cookie; requests that carry it
+are let through. Public docs: <https://capskip.com/api-docs/#datadome>.
+
+The arguments follow 2Captcha's `datadome(captcha_url, pageurl, userAgent,
+proxy)`, so code written against it ports directly; `userAgent` and `proxy` go
+in the options object and are optional here.
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `method` | string | Yes | `datadome` |
+| `captcha_url` | string | Yes | Address of the challenge iframe on `geo.captcha-delivery.com` |
+| `pageurl` | string | Yes | Full http or https URL of the page that returned the block page |
+| `userAgent` | string | No | The User-Agent you will send with the cookie: Chrome for Windows, same major version as CapSkip's browser. Sent as `useragent` |
+| `json` | int | No | `0` plain text, `1` JSON |
+| `proxy` | string | No | The proxy your later requests go through |
+| `proxytype` | string | No | `HTTP`, `HTTPS`, `SOCKS5` or `SOCKS5H` |
+
+The SDK also accepts `captchaUrl` / `captchaURL` for `captcha_url`. An optional
+left `undefined`, `null` or `''` is not sent — the server reads an empty value
+as absent. The `captcha_url` is sent exactly as given.
+
+Refused by the SDK before the request is made, as the server would refuse them
+(`ValidationException`):
+
+- a missing `captcha_url` or `pageurl`;
+- a `captcha_url` that is not https on captcha-delivery.com (or a subdomain),
+  under `/captcha/` or `/interstitial/`, carrying `initialCid`, `hash` and
+  `cid` (server: `ERROR_BAD_PARAMETERS`);
+- a `captcha_url` with `t=bv`: the block page bans the address that fetched it,
+  so nothing sent from there can pass (server: `ERROR_PROXY_BANNED`);
+- a `pageurl` that is not http(s), or that points at captcha-delivery.com
+  (server: `ERROR_PAGEURL`);
+- a `userAgent` that is not stock Chrome for Windows: Firefox, Safari, Edge,
+  Opera, macOS, Linux, Android and iOS all fail (server:
+  `ERROR_WRONG_USERAGENT`).
+
+The Chrome **major version** is checked by CapSkip itself, against the browser
+it solves with, and a mismatch comes back as `ApiException('ERROR_WRONG_USERAGENT')`.
+
+### Building the `captchaUrl`
+
+If the block page already contains the challenge iframe, take its `src` as it
+is (an HTML-escaped `&amp;` is fine). Most block pages build it with a script
+from a `var dd={...}` object instead:
+
+```js
+const dd = JSON.parse(html.match(/var dd=(\{[^}]*\})/)[1].replace(/'/g, '"'));
+const path = dd.rt === 'i' ? 'interstitial' : 'captcha';
+const q = new URLSearchParams({ initialCid: dd.cid, hash: dd.hsh, cid: dd.cookie });
+if (dd.t) q.set('t', dd.t);
+q.set('referer', pageUrl);
+q.set('s', String(dd.s));
+for (const k of ['e', 'b']) {
+  if (dd[k]) q.set(k, String(dd[k]));
+}
+q.set('dm', 'cd');
+const captchaUrl = `https://${dd.host || 'geo.captcha-delivery.com'}/${path}/?${q}`;
+```
+
+Each block page is a fresh challenge: submit it soon, and request the page again
+for the next task rather than reusing an old `captchaUrl`.
+
+### The cookie belongs to one IP and one User-Agent
+
+DataDome refuses the cookie from any other address, or with any other
+User-Agent:
+
+- **Solve from the address you will use the cookie from.** Pass the proxy your
+  requests go through; pass none if they come from the machine running CapSkip.
+- **Send the User-Agent you will use, or none.** With none, CapSkip uses its
+  browser's own, and the result names it.
+- **CapSkip's own DataDome proxy list.** The app can hold a list of proxies for
+  DataDome (Settings, Captcha types, DataDome, Configure Proxies). A task sent
+  without a proxy is solved through that list, and the result then carries
+  `proxy`: that proxy as `host:port`, without its login. The cookie only works
+  through it. A proxy sent with the task always takes priority, and then no
+  `proxy` comes back.
+
+### GET `/res.php`
+
+The SDK polls with `json=1`, where CapSkip returns the cookie in `request` with
+`userAgent` and, when its list supplied the proxy, `proxy` next to it:
+
+```json
+{
+  "status": 1,
+  "request": "datadome=FAPPpli4...; Max-Age=31536000; Domain=.example.com; Path=/; Secure; SameSite=Lax",
+  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/156.0.0.0 Safari/537.36",
+  "proxy": "203.0.113.10:8080"
+}
+```
+
+(In plain-text mode the same two values arrive in the `X-DataDome-User-Agent`
+and `X-DataDome-Proxy` response headers.) See [Return value](#return-value).
+
+### SDK usage
+
+```js
+// 2Captcha's argument order, with userAgent and proxy as options
+const result = await solver.dataDome(captchaUrl, 'https://www.example.com/', {
+  userAgent,
+  proxy: { type: 'HTTP', uri: 'login:password@203.0.113.10:8080' },
+});
+
+// No proxy, no User-Agent: CapSkip's browser, and its proxy list if it has one
+const result = await solver.dataDome(captchaUrl, 'https://www.example.com/');
+
+const headers = {
+  'User-Agent': result.userAgent,
+  Cookie: result.cookie, // "datadome=..."
+};
+if (result.proxy) {
+  // send this request through result.proxy
+}
+```
+
+DataDome may send a replacement `datadome` cookie on later responses; keep the
+newest one, as a browser would. When the block page comes back anyway, build a
+new `captchaUrl` from it and submit a new task.
+
+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:
@@ -777,6 +990,35 @@ answer):
 }
 ```
 
+DataDome returns a cookie. `code` keeps it exactly as DataDome set it, for a
+cookie jar; `cookie` is the `datadome=...` pair alone, for a Cookie header.
+`userAgent` is the User-Agent the cookie was earned with, and `proxy` appears
+only when the task sent no proxy and CapSkip used its own DataDome proxy list:
+
+```js
+{
+  captchaId: '12345',
+  code: 'datadome=FAPPpli4...; Max-Age=31536000; Domain=.example.com; Path=/; Secure; SameSite=Lax',
+  cookie: 'datadome=FAPPpli4...',
+  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/156.0.0.0 Safari/537.36',
+  proxy: '203.0.113.10:8080',
+}
+```
+
+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):
 
@@ -814,6 +1056,7 @@ Convenience aliases mapped before sending to CapSkip:
 | `challengeScript` | `challenge_script` |
 | `captchaScript` | `captcha_script` |
 | `jsapi_script` | `jsapiScript` |
+| `captchaUrl` / `captchaURL` | `captcha_url` |
 | `proxy` object | `proxy` + `proxytype` strings |
 
 ```js

package/examples/datadome.js

@@ -0,0 +1,142 @@
+'use strict';
+
+/**
+ * Pass a DataDome challenge and fetch the page with the cookie.
+ *
+ * DataDome answers a request it doubts with a block page (status 403, sometimes
+ * 401) instead of the site. That page carries a `var dd={...}` object and loads
+ * the challenge in an iframe from geo.captcha-delivery.com: a slider under
+ * /captcha/, or a few-second device check under /interstitial/. CapSkip passes
+ * either and returns the `datadome` cookie.
+ *
+ * The cookie belongs to one IP address and one User-Agent, so:
+ *
+ *   * solve through the proxy your requests use (or none, if they leave from
+ *     the machine running CapSkip), and
+ *   * send the User-Agent CapSkip reports back with every request.
+ *
+ * When you send no proxy and the CapSkip app has its own DataDome proxy list,
+ * it solves through one of those and the result names it as `proxy`
+ * (host:port): the cookie then only works through that proxy.
+ *
+ * Requests go out with Node's built-in fetch. Sending them through a proxy
+ * needs undici's ProxyAgent (`npm install undici`); without it, the example
+ * prints what to do instead of re-fetching through the proxy.
+ *
+ * Environment:
+ *   TARGET_URL         a page behind DataDome (default: https://www.example.com/)
+ *   DATADOME_PROXY     optional, e.g. http://login:password@203.0.113.10:8080
+ *   CAPSKIP_API_KEY / CAPSKIP_HOST / CAPSKIP_PORT
+ */
+
+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),
+});
+
+const PAGE_URL = process.env.TARGET_URL || 'https://www.example.com/';
+const PROXY = process.env.DATADOME_PROXY; // scheme://[login:password@]host:port, or unset
+
+let ProxyAgent;
+try {
+  ({ ProxyAgent } = require('undici'));
+} catch (error) {
+  ProxyAgent = undefined;
+}
+
+/** The challenge iframe address, as the block page's own script builds it. */
+function captchaUrlFromBlockPage(html, pageUrl) {
+  const iframe = html.match(/<iframe[^>]+src="(https:\/\/[^"]*captcha-delivery\.com\/[^"]+)"/);
+  if (iframe) {
+    return iframe[1]; // HTML-escaped &amp; is fine, CapSkip decodes it
+  }
+  const match = html.match(/var dd=(\{[^}]*\})/);
+  if (!match) {
+    return null;
+  }
+  const dd = JSON.parse(match[1].replace(/'/g, '"'));
+  const path = dd.rt === 'i' ? 'interstitial' : 'captcha';
+  const query = new URLSearchParams({ initialCid: dd.cid, hash: dd.hsh, cid: dd.cookie });
+  if (dd.t) {
+    query.set('t', dd.t);
+  }
+  query.set('referer', pageUrl);
+  query.set('s', String(dd.s));
+  for (const key of ['e', 'b']) {
+    if (dd[key]) {
+      query.set(key, String(dd[key]));
+    }
+  }
+  query.set('dm', 'cd');
+  return `https://${dd.host || 'geo.captcha-delivery.com'}/${path}/?${query}`;
+}
+
+/** fetch, through `proxyUrl` when one is given and undici is installed. */
+function get(url, { proxyUrl, headers } = {}) {
+  const options = { headers, redirect: 'follow' };
+  if (proxyUrl) {
+    options.dispatcher = new ProxyAgent(proxyUrl);
+  }
+  return fetch(url, options);
+}
+
+async function main() {
+  if (PROXY && !ProxyAgent) {
+    console.log('DATADOME_PROXY is set: run `npm install undici` so the requests use it.');
+    return;
+  }
+
+  // 1. Request the page. A 403/401 with a dd object is DataDome's block page.
+  const response = await get(PAGE_URL, { proxyUrl: PROXY });
+  const html = await response.text();
+  const captchaUrl = captchaUrlFromBlockPage(html, PAGE_URL);
+  if (![401, 403].includes(response.status) || !captchaUrl) {
+    console.log(`No DataDome block page at ${PAGE_URL} (HTTP ${response.status}).`);
+    return;
+  }
+  console.log('Block page:', `${captchaUrl.slice(0, 90)}...`);
+
+  // 2. Solve it. 2Captcha's argument order: datadome(captcha_url, pageurl,
+  //    userAgent, proxy), with userAgent and proxy as options. No userAgent:
+  //    CapSkip uses its own browser's and reports it. With one, it must be
+  //    Chrome for Windows with the same major version as that browser.
+  const options = {};
+  if (PROXY) {
+    const scheme = PROXY.includes('://') ? PROXY.split('://', 1)[0] : 'http';
+    options.proxy = { type: scheme.toUpperCase(), uri: PROXY.split('://').pop() };
+  }
+  const result = await solver.dataDome(captchaUrl, PAGE_URL, options);
+
+  console.log('Captcha ID:', result.captchaId);
+  console.log('Cookie:    ', `${result.cookie.slice(0, 60)}...`);
+  console.log('User-Agent:', result.userAgent);
+  if (result.proxy) {
+    console.log('Proxy:     ', result.proxy, '(from the CapSkip app DataDome list; the cookie only works through it)');
+  }
+
+  // 3. Repeat the request with the cookie, the same User-Agent and the same IP.
+  let proxyUrl = PROXY;
+  if (result.proxy && !PROXY) {
+    // Named without its login: add yours if that list entry has one.
+    if (!ProxyAgent) {
+      console.log(`Send the cookie through http://${result.proxy}: run \`npm install undici\` to do it here.`);
+      return;
+    }
+    proxyUrl = `http://${result.proxy}`;
+  }
+  // `cookie` is the datadome=... pair, ready for the Cookie header; `code`
+  // keeps the attributes (Domain, Max-Age...) for a cookie jar.
+  const again = await get(PAGE_URL, {
+    proxyUrl,
+    headers: { 'User-Agent': result.userAgent, Cookie: result.cookie },
+  });
+  console.log('With the cookie: HTTP', again.status);
+}
+
+main().catch((error) => {
+  console.error(`${error.name}: ${error.message}`);
+  process.exitCode = 1;
+});