capskip 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.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 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()`. Nothing leaves your network, and there is no credit balance to keep an eye on.
 
 ## Supported captcha types
 
@@ -40,6 +40,7 @@ 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 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()`.
 
@@ -137,7 +138,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 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 +358,68 @@ 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.
+
 ### With a proxy (every method except image captcha)
 
 ```js
@@ -457,7 +520,10 @@ 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.
 
 ---
 
@@ -502,7 +568,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()` 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 +576,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, and image/text captchas. Not hCaptcha, and not FunCaptcha/Arkose.
 
 ### Does it work with Puppeteer and Playwright?
 

package/docs/API_REFERENCE.md

@@ -28,6 +28,7 @@ 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` |
 
 **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 +714,138 @@ 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.
+
+---
+
 ## Return value
 
 Every solve method resolves to:
@@ -777,6 +910,21 @@ 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',
+}
+```
+
 GeeTest additionally expands its answer into `challenge`, `validate`, and
 `seccode` (`code` keeps the raw JSON string):
 
@@ -814,6 +962,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;
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "capskip",
-  "version": "1.4.0",
-  "description": "Captcha solver for Node.js: solve reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest, AWS WAF and image captchas with CapSkip, a local unlimited captcha solver with no per-solve fees.",
+  "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.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
   "exports": {
@@ -41,6 +41,8 @@
     "geetest-solver",
     "aws-waf",
     "aws-waf-captcha",
+    "datadome",
+    "datadome-solver",
     "image-captcha",
     "ocr",
     "2captcha-alternative",

package/src/apiParams.js

@@ -59,6 +59,29 @@ 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 DATADOME_SUBMIT = new Set([
+  'method', 'captcha_url', 'pageurl', 'useragent', 'json', 'proxy', 'proxytype',
+]);
+
+// Every DataDome challenge is served from this domain or a subdomain of it
+// (geo.captcha-delivery.com in practice). CapSkip refuses any other host.
+const DATADOME_CHALLENGE_DOMAIN = 'captcha-delivery.com';
+
+// The two challenge pages: /captcha/ draws the slider, /interstitial/ runs the
+// device check. Any other path renders nothing to solve.
+const DATADOME_CHALLENGE_PATHS = ['/captcha', '/interstitial'];
+
+// A Chrome version as Chrome writes it in its User-Agent: four dotted numbers.
+const CHROME_VERSION = /\bChrome\/(\d+)\.\d+\.\d+\.\d+\b/;
+
+// Chrome-derived browsers and non-desktop builds. A User-Agent carrying any of
+// these is not stock Windows Chrome, so a cookie earned under it would be
+// refused on replay; the server answers ERROR_WRONG_USERAGENT for each.
+const NOT_STOCK_WINDOWS_CHROME = [
+  'Edg/', 'EdgA/', 'OPR/', 'YaBrowser/', 'SamsungBrowser/', 'Vivaldi/',
+  'HeadlessChrome/', 'CriOS/', 'Mobile', 'Android',
+];
+
 // CapSkip solves the puzzle family only. `avatar` is a different challenge
 // behind a different endpoint; the server refuses it at submit time rather than
 // answering it with a puzzle answer, which would bill for a solve the target
@@ -100,6 +123,10 @@ const PARAM_ALIASES = {
   challengeScript: 'challenge_script',
   captchaScript: 'captcha_script',
   jsapi_script: 'jsapiScript',
+  // DataDome: 2Captcha and the API document captcha_url; createTask-style
+  // callers arrive with captchaUrl.
+  captchaUrl: 'captcha_url',
+  captchaURL: 'captcha_url',
 };
 
 function has(obj, key) {
@@ -456,6 +483,171 @@ function validateAmazonWafSubmit(params) {
   }
 }
 
+const HTML_NAMED_ENTITIES = {
+  amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ',
+};
+
+/**
+ * Decode HTML character references, as the server does before it parses a
+ * DataDome captcha_url: an iframe src copied out of the page source carries
+ * &amp; between its query parameters.
+ */
+function htmlUnescape(text) {
+  return text.replace(/&(#[0-9]+|#[xX][0-9a-fA-F]+|[A-Za-z]+);/g, (match, ref) => {
+    if (ref[0] === '#') {
+      const code = ref[1] === 'x' || ref[1] === 'X'
+        ? parseInt(ref.slice(2), 16)
+        : parseInt(ref.slice(1), 10);
+      try {
+        return String.fromCodePoint(code);
+      } catch (error) {
+        return match;
+      }
+    }
+    const named = HTML_NAMED_ENTITIES[ref.toLowerCase()];
+    return named === undefined ? match : named;
+  });
+}
+
+function isDataDomeHost(host) {
+  const lowered = String(host || '').toLowerCase();
+  return lowered === DATADOME_CHALLENGE_DOMAIN
+    || lowered.endsWith(`.${DATADOME_CHALLENGE_DOMAIN}`);
+}
+
+/**
+ * The query of a DataDome challenge URL as a URLSearchParams, or null if it is
+ * not one.
+ *
+ * Mirrors the server: an https URL on captcha-delivery.com (or a subdomain),
+ * path /captcha/ or /interstitial/, carrying initialCid, hash and cid. An
+ * iframe src copied HTML-escaped (&amp;) and a scheme-relative //geo... URL
+ * are both read the way the server reads them.
+ */
+function parseDataDomeCaptchaUrl(url) {
+  let text = htmlUnescape(String(url === undefined || url === null ? '' : url).trim());
+  if (text.startsWith('//')) {
+    text = `https:${text}`;
+  }
+  let parsed;
+  try {
+    parsed = new URL(text);
+  } catch (error) {
+    return null;
+  }
+  if (parsed.protocol !== 'https:' || !isDataDomeHost(parsed.hostname)) {
+    return null;
+  }
+  const pathname = parsed.pathname.replace(/\/+$/, '').toLowerCase();
+  if (!DATADOME_CHALLENGE_PATHS.includes(pathname)) {
+    return null;
+  }
+  const query = parsed.searchParams;
+  if (!['initialCid', 'hash', 'cid'].every((key) => query.get(key))) {
+    return null;
+  }
+  return query;
+}
+
+/**
+ * True for a stock Chrome-for-Windows User-Agent, the only kind CapSkip takes.
+ *
+ * DataDome ties the cookie to the browser that earned it, and CapSkip solves
+ * in Chrome on Windows, so a cookie for any other User-Agent would be refused
+ * on replay. The server also requires the same Chrome major version as its
+ * own browser; that part can only be checked there.
+ */
+function isDataDomeUserAgent(userAgent) {
+  const ua = String(userAgent === undefined || userAgent === null ? '' : userAgent);
+  return ua.includes('Windows NT ')
+    && CHROME_VERSION.test(ua)
+    && !NOT_STOCK_WINDOWS_CHROME.some((token) => ua.includes(token));
+}
+
+/**
+ * Drop unset optionals, and the empty ones too: a DataDome optional left as ''
+ * means "not sent" to the server, exactly like an absent one.
+ */
+function normalizeDataDomeSubmit(params) {
+  const out = {};
+  for (const [key, value] of Object.entries(dropUnset(params))) {
+    if (value !== '') {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/** An absolute http(s) URL with a host that is not DataDome's own. */
+function isDataDomePageUrl(pageurl) {
+  let parsed;
+  try {
+    parsed = new URL(pageurl);
+  } catch (error) {
+    return false;
+  }
+  return (parsed.protocol === 'http:' || parsed.protocol === 'https:')
+    && parsed.hostname !== ''
+    && !isDataDomeHost(parsed.hostname);
+}
+
+function validateDataDomeSubmit(params) {
+  // Without captcha_url the server answers ERROR_BAD_PARAMETERS and without
+  // pageurl ERROR_PAGEURL. Fail locally so a missing value costs no round-trip.
+  for (const key of ['captcha_url', 'pageurl']) {
+    if (!params[key]) {
+      throw new ValidationException(`'${key}' is required for DataDome.`);
+    }
+  }
+
+  const query = parseDataDomeCaptchaUrl(params.captcha_url);
+  if (query === null) {
+    throw new ValidationException(
+      "'captcha_url' must be the https address of a DataDome challenge on "
+      + 'captcha-delivery.com, under /captcha/ or /interstitial/ and carrying '
+      + `initialCid, hash and cid, got '${params.captcha_url}'. Take it from `
+      + "the block page's iframe src, or build it from the page's `var dd` object.",
+    );
+  }
+  // t=bv is DataDome saying the address that fetched the block page is
+  // banned. Nothing sent from it can pass, and the server refuses the task
+  // with ERROR_PROXY_BANNED, so say so before the round-trip.
+  if (query.get('t') === 'bv') {
+    throw new ValidationException(
+      'This DataDome block page bans the IP address that requested it '
+      + '(t=bv), so no solve from that address can pass. Change the address '
+      + '(proxy), request the page again and submit the new captcha_url.',
+    );
+  }
+
+  const pageurl = String(params.pageurl).trim();
+  if (!isDataDomePageUrl(pageurl)) {
+    throw new ValidationException(
+      "'pageurl' must be the full http or https URL of the page that "
+      + `returned the DataDome block page, got '${pageurl}'.`,
+    );
+  }
+
+  const userAgent = params.useragent;
+  if (userAgent !== undefined && userAgent !== null && userAgent !== ''
+      && !isDataDomeUserAgent(userAgent)) {
+    throw new ValidationException(
+      "DataDome 'userAgent' must be a stock Chrome for Windows User-Agent "
+      + 'with the same major version as the browser CapSkip solves with, got '
+      + `'${userAgent}'. The cookie only works with the User-Agent that `
+      + "earned it. Leave it out and CapSkip uses its own browser's, which "
+      + 'the result reports as `userAgent`.',
+    );
+  }
+
+  const unknown = unknownKeys(params, DATADOME_SUBMIT);
+  if (unknown.length > 0) {
+    throw new ValidationException(
+      `Unsupported parameters for DataDome: ${reprList(unknown)}.`,
+    );
+  }
+}
+
 function validateProxyType(params) {
   const proxytype = params.proxytype;
   if (proxytype === undefined || proxytype === null || proxytype === '') {
@@ -496,6 +688,9 @@ function prepareSubmitParams(params, captchaType, version = 'v2') {
   } else if (captchaType === 'amazon_waf') {
     prepared = normalizeAmazonWafSubmit(prepared);
     validateAmazonWafSubmit(prepared);
+  } else if (captchaType === 'datadome') {
+    prepared = normalizeDataDomeSubmit(prepared);
+    validateDataDomeSubmit(prepared);
   }
 
   // Skipped for 'normal', which rejects proxy outright with a clearer message.
@@ -518,6 +713,9 @@ module.exports = {
   FRIENDLY_CAPTCHA_SUBMIT,
   AMAZON_WAF_SUBMIT,
   AMAZON_WAF_SCRIPTS,
+  DATADOME_SUBMIT,
+  DATADOME_CHALLENGE_DOMAIN,
+  DATADOME_CHALLENGE_PATHS,
   CAPY_VERSIONS,
   FRIENDLY_CAPTCHA_VERSIONS,
   PROXY_TYPES,
@@ -537,6 +735,11 @@ module.exports = {
   isAmazonWafScriptUrl,
   normalizeAmazonWafSubmit,
   validateAmazonWafSubmit,
+  htmlUnescape,
+  parseDataDomeCaptchaUrl,
+  isDataDomeUserAgent,
+  normalizeDataDomeSubmit,
+  validateDataDomeSubmit,
   validateProxyType,
   prepareSubmitParams,
 };

package/src/index.js

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

package/src/solver.js

@@ -83,6 +83,12 @@ function applyPollResult(result, polled) {
     if (userAgent) {
       result.userAgent = userAgent;
     }
+    // DataDome names the proxy a task was solved through when the task sent
+    // none and CapSkip took one from its own DataDome proxy list. The cookie
+    // only works from that address, so it is reported rather than dropped.
+    if (polled.proxy) {
+      result.proxy = polled.proxy;
+    }
     // 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
@@ -277,6 +283,24 @@ function applyAmazonWafSolution(result) {
   return expandObjectAnswer(result, AMAZON_WAF_FIELDS);
 }
 
+/**
+ * Expose the DataDome cookie as `cookie`, ready for a Cookie header.
+ *
+ * `code` keeps the cookie exactly as DataDome set it, attributes included
+ * (`datadome=...; Max-Age=...; Domain=...; Path=/; Secure; SameSite=Lax`),
+ * for a cookie jar. `cookie` is the part before the first semicolon, the
+ * `datadome=...` pair a request sends back. `userAgent` and, when CapSkip
+ * picked the proxy, `proxy` are carried through from the poll as they are.
+ * An answer that is not a string is left untouched.
+ */
+function applyDataDomeSolution(result) {
+  const { code } = result;
+  if (typeof code === 'string' && code) {
+    result.cookie = code.split(';', 1)[0].trim();
+  }
+  return result;
+}
+
 /**
  * Expose a single-token answer as `token`, named for the form field it fills.
  *
@@ -326,7 +350,8 @@ function parseSubmitResponse(response) {
 
 /**
  * Client for the CapSkip local captcha solver (image, reCAPTCHA, Turnstile,
- * GeeTest v3, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha, AWS WAF).
+ * GeeTest v3, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha, AWS WAF,
+ * DataDome).
  */
 class CapSkip {
   constructor({
@@ -620,6 +645,61 @@ class CapSkip {
     return applyAmazonWafSolution(result);
   }
 
+  /**
+   * Solve a DataDome challenge and return the `datadome` cookie.
+   *
+   * `captchaUrl` and `url` are required; everything else goes in `options`:
+   *
+   * - `captchaUrl` is the address of the challenge iframe on
+   *   geo.captcha-delivery.com, under /captcha/ (slider) or /interstitial/
+   *   (device check). Take the iframe's src from the block page, or build it
+   *   from the page's `var dd` object as the API docs show.
+   * - `url` is the page that returned the block page.
+   * - `options.userAgent` is the one you will send with the cookie. It must be
+   *   Chrome for Windows with the same major version as the browser CapSkip
+   *   solves with; leave it out and CapSkip uses that browser's own.
+   * - `options.proxy` is the proxy your later requests go through, as a URI
+   *   string or `{ type: 'HTTP', uri: 'login:password@IP:PORT' }`.
+   *
+   * DataDome ties the cookie to the IP address and User-Agent that earned it.
+   * The result carries:
+   *
+   * - `code` -- the cookie exactly as DataDome set it, attributes included;
+   * - `cookie` -- just the `datadome=...` pair, for a Cookie header;
+   * - `userAgent` -- the User-Agent the cookie was earned with. Send it with
+   *   every request that carries the cookie;
+   * - `proxy` -- present only when you sent no proxy and CapSkip solved
+   *   through its own DataDome proxy list: that proxy as `host:port`. The
+   *   cookie works only through it.
+   */
+  async dataDome(captchaUrl, url, options = {}) {
+    // An unset value is dropped rather than sent as undefined, so
+    // `dataDome(undefined, url, { captchaUrl })` reaches the alias without
+    // tripping the conflict check; an empty one is dropped during validation,
+    // since the server reads '' as "not sent".
+    const given = {};
+    const add = (key, value) => {
+      if (value !== undefined && value !== null) {
+        given[key] = value;
+      }
+    };
+    add('captcha_url', captchaUrl);
+    add('url', url);
+    for (const [key, value] of Object.entries(options)) {
+      add(key, value);
+    }
+
+    // A real browser session, slider or device check, 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: 'datadome',
+      poll_json: 1,
+    });
+    return applyDataDomeSolution(result);
+  }
+
   async solve(options = {}) {
     const {
       timeout = 0,
@@ -723,6 +803,9 @@ class CapSkip {
     if (method === 'amazon_waf') {
       return prepareSubmitParams(params, 'amazon_waf');
     }
+    if (method === 'datadome') {
+      return prepareSubmitParams(params, 'datadome');
+    }
     return applyProxy(applyParamAliases(params));
   }
 }
@@ -738,6 +821,7 @@ module.exports = {
   applyAltchaSolution,
   applyCapySolution,
   applyAmazonWafSolution,
+  applyDataDomeSolution,
   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 before timing out. Default `300`. ALTCHA and Capy use
+   * Captcha / AWS WAF / DataDome before timing out. Default `300`. ALTCHA and Capy use
    * `defaultTimeout` instead — neither is a browser solve.
    */
   recaptchaTimeout?: number;
@@ -37,13 +37,16 @@ export interface SolveResult {
    * this is the raw JSON string CapSkip returns — prefer the parsed
    * `challenge` / `validate` / `seccode` fields below. For ALTCHA it is the
    * base64 token, also exposed as `token`. For Capy and AWS WAF it is the raw
-   * answer object, expanded into the fields below.
+   * answer object, expanded into the fields below. For DataDome it is the
+   * `datadome` cookie exactly as DataDome set it, attributes included.
    */
   code: string | Record<string, unknown>;
   /**
-   * Turnstile and CaptchaFox — 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.
+   * 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
+   * 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.
    */
   userAgent?: string;
   /** GeeTest only — the `geetest_challenge` value to post back. */
@@ -82,6 +85,17 @@ export interface SolveResult {
   captcha_voucher?: string;
   /** AWS WAF only — the token the voucher was issued for. Pair with `captcha_voucher`. */
   existing_token?: string;
+  /**
+   * DataDome only — the `datadome=...` pair alone (`code` up to its first
+   * `;`), ready for a `Cookie` header.
+   */
+  cookie?: string;
+  /**
+   * DataDome only — present only when the task sent no proxy and CapSkip solved
+   * through its own DataDome proxy list: that proxy as `host:port`. The cookie
+   * works only through it.
+   */
+  proxy?: string;
 }
 
 /** Extra options for {@link CapSkip.normal}. */
@@ -280,6 +294,36 @@ export interface AmazonWafOptions {
   [key: string]: unknown;
 }
 
+/** Extra options for {@link CapSkip.dataDome}. */
+export interface DataDomeOptions {
+  /**
+   * The User-Agent you will send with the cookie. Must be stock Chrome for
+   * Windows with the same major version as the browser CapSkip solves with.
+   * Leave it out and CapSkip uses its own browser's, reported as `userAgent`.
+   */
+  userAgent?: string;
+  /** Alias for `userAgent`. */
+  useragent?: string;
+  /** The challenge iframe URL (alias for the `captchaUrl` argument). */
+  captcha_url?: string;
+  /** The challenge iframe URL (alias for the `captchaUrl` argument). */
+  captchaUrl?: string;
+  /**
+   * The proxy your later requests go through. Left out, CapSkip solves through
+   * its own DataDome proxy list and the result names that proxy as `proxy`.
+   */
+  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). */
@@ -376,6 +420,22 @@ export class CapSkip {
     url: string,
     options?: AmazonWafOptions,
   ): Promise<SolveResult>;
+  /**
+   * Solve a DataDome challenge (slider or device check) and return the
+   * `datadome` cookie.
+   *
+   * `captchaUrl` is the challenge iframe's address on captcha-delivery.com
+   * (`/captcha/` or `/interstitial/`), `url` the page that returned the block
+   * page. The result carries `code` (the cookie as set), `cookie` (the
+   * `datadome=...` pair), `userAgent` (send it with the cookie) and, only when
+   * no proxy was passed and CapSkip used its own DataDome proxy list, `proxy`
+   * — the cookie works only through that address.
+   */
+  dataDome(
+    captchaUrl: string | undefined,
+    url: string,
+    options?: DataDomeOptions,
+  ): 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. */