capskip 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,83 @@ 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
+
+- **AWS WAF support** via `amazonWaf(sitekey, url, options)`, sent as
+  `method=amazon_waf`. Only `sitekey` and `url` are required.
+  On a challenge page (the HTTP 405 page with `window.gokuProps`), `sitekey`,
+  `iv` and `context` are `gokuProps.key`, `.iv` and `.context`, and
+  `challenge_script` / `captcha_script` are the page's challenge.js and
+  captcha.js. On a widget page (`AwsWafCaptcha.renderCaptcha`), `sitekey` is the
+  widget's `apiKey` and `jsapiScript` the URL of jsapi.js.
+  An AWS WAF answer is **not a token**: the result expands into
+  `captcha_voucher` and `existing_token`, which the site's `voucher` endpoint
+  (beside challenge.js) trades for the `aws-waf-token` cookie. `code` keeps the
+  raw answer.
+- Parameter aliases `challengeScript` for `challenge_script`, `captchaScript`
+  for `captcha_script`, and `jsapi_script` for `jsapiScript`.
+- TypeScript definitions for `AmazonWafOptions`, plus the new `SolveResult`
+  fields.
+- `examples/amazon_waf.js`.
+
+### Changed
+
+- The Capy answer expansion is now a shared helper, used by Capy and AWS WAF
+  alike. Capy results are unchanged.
+- The exported `version` constant now reports the package version; it had been
+  left at `1.1.0`.
+
+### Notes
+
+- `iv` and `context` are optional but travel together: one without the other is
+  refused locally, as the server would refuse it. Left out, CapSkip reads both
+  from the page at solve time. An optional passed as `''` is treated as not
+  sent, the way the server reads it.
+- Every script URL must be `https` on an `awswaf.com` host, with no credentials,
+  no port other than 443, and a path ending in `challenge.js`, `captcha.js` or
+  `jsapi.js`. CapSkip posts the solution to the host the script names, so any
+  other script is refused before the request is made.
+- AWS WAF uses `recaptchaTimeout`: a real browser mints the token the voucher is
+  issued for.
+
 ## [1.3.0] - 2026-09-22
 
 ### 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 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()`. 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
 
@@ -38,6 +38,9 @@ This SDK is a thin wrapper over that API, with the method names you would expect
 | **Capy Puzzle solver** (slide puzzle) | `solver.capy(sitekey, url)` |
 | **CaptchaFox solver** (widget) | `solver.captchafox(sitekey, url)` |
 | **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()`.
 
@@ -135,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 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)
 });
@@ -313,6 +316,110 @@ a script URL, v1 is assumed. Pass `api_server: 'eu'` for a sitekey on the EU
 data-residency tenant. A v2 token is roughly six kilobytes, so size whatever
 carries it accordingly.
 
+### AWS WAF
+
+AWS WAF puts its CAPTCHA either on a **challenge page** — the HTTP 405
+interstitial that sets `window.gokuProps` — or in a **widget** an ordinary page
+renders with `AwsWafCaptcha.renderCaptcha`. Only `sitekey` and `url` are required.
+
+```js
+// Challenge page: sitekey, iv and context are gokuProps.key, .iv and .context
+const result = await solver.amazonWaf(
+  'AQIDAHjcYuEXAMPLEghicBgQ/7bFaQZ+m5FKCMDnO+vTbNg96AHDh0IR5vgzHNceHYqZR+GOAAAAfjB8',
+  'https://example.com/protected',
+  {
+    iv: 'CgAFRDIjfgAAA5yY',
+    context: 'Rbp3r8fvbuhmrCqpUe8Mh1TLvs8OSKJZiSs2vCF4dt9rxVZI7xYJa2n5k/9r+XaXe7KUIu2I8nXTDHHkDvIOTDc2',
+    challenge_script: 'https://3f2a9c7d41b0.edge.sdk.awswaf.com/3f2a9c7d41b0/8e51d0c7a2f4/challenge.js',
+  },
+);
+
+// Widget page: sitekey is the widget's apiKey, plus the jsapi.js it loads
+const result = await solver.amazonWaf(
+  'Xr9kEXAMPLE2bWQx1vTq8LmZ0aYc4dHs7nFp3gJt6uKw5eRi9AbCdEfGh=_0_1',
+  'https://example.com/protected',
+  { jsapiScript: 'https://5b7e0a19c3d8.us-east-1.captcha-sdk.awswaf.com/5b7e0a19c3d8/jsapi.js' },
+);
+
+result.captcha_voucher, result.existing_token;
+```
+
+`iv` and `context` are optional and travel together: send both or neither. Left
+out, CapSkip reads them from the page at solve time, which is the safer choice
+when your copy of the page is more than a few minutes old.
+
+The answer is not a token. POST `captcha_voucher` and `existing_token` as JSON
+to the `voucher` endpoint beside the page's `challenge.js`; the response's
+`token` is the `aws-waf-token` cookie. The pair is short-lived, so exchange it
+immediately rather than storing it.
+
+Every script URL (`challenge_script`, `captcha_script`, `jsapiScript`) must be an
+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
@@ -411,8 +518,12 @@ GeeTest additionally expands its answer into `challenge`, `validate`, and
 `seccode`, while `code` keeps the raw JSON string. CaptchaFox and Friendly
 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. ALTCHA adds `token` (the same
-string as `code`) and `number`, the counter that solved it.
+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. 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.
 
 ---
 
@@ -457,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()` 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?
 
@@ -465,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, 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

@@ -9,7 +9,7 @@ POST http://<host>:<port>/in.php   → submit captcha
 GET  http://<host>:<port>/res.php  → poll result
 ```
 
-The SDK only supports the four captcha types documented by CapSkip. Every solve
+The SDK only supports the captcha types documented by CapSkip. Every solve
 method returns a `Promise`.
 
 ---
@@ -27,6 +27,8 @@ method returns a `Promise`.
 | Capy Puzzle (slide) | `capy()` | `capy` |
 | 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
@@ -612,6 +614,238 @@ browser.
 
 ---
 
+## 10. AWS WAF — `amazonWaf(sitekey, url, { ... })`
+
+AWS WAF puts its CAPTCHA either on a challenge page — the HTTP 405 interstitial
+that sets `window.gokuProps` — or in a widget an ordinary page renders with
+`AwsWafCaptcha.renderCaptcha`. CapSkip solves both in a real browser. See the
+[CapSkip API docs](https://capskip.com/api-docs/#aws-waf).
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `method` | string | Yes | `amazon_waf` |
+| `sitekey` | string | Yes | Challenge page: `gokuProps.key`. Widget page: the widget's `apiKey` |
+| `pageurl` | string | Yes | Full http or https URL of the protected page |
+| `iv` | string | No | Challenge page: `gokuProps.iv`. Send together with `context` |
+| `context` | string | No | Challenge page: `gokuProps.context`. Send together with `iv` |
+| `challenge_script` | string | No | Full URL of the page's `challenge.js` |
+| `captcha_script` | string | No | Full URL of the page's `captcha.js` |
+| `jsapiScript` | string | No | Widget page: full URL of `jsapi.js` |
+| `json` | int | No | `0` plain text, `1` JSON |
+| `proxy` | string | No | Proxy address |
+| `proxytype` | string | No | Proxy type |
+
+The SDK also accepts `challengeScript`, `captchaScript` and `jsapi_script`, and
+sends the documented spelling of each. An optional left `undefined`, `null` or
+`''` is not sent — the server reads an empty value as absent.
+
+### Challenge page or widget page
+
+| | Challenge page | Widget page |
+|---|---|---|
+| Recognized by | HTTP 405 with `window.gokuProps` in an inline script | `AwsWafCaptcha.renderCaptcha(container, { apiKey, … })` |
+| `sitekey` | `gokuProps.key` | the widget's `apiKey` |
+| `iv` / `context` | `gokuProps.iv` / `gokuProps.context`, or neither | not sent |
+| Scripts | `challenge_script`, `captcha_script` | `jsapiScript` |
+
+`iv` and `context` come off the same page and only work as a pair, so the SDK
+refuses one without the other. Both are optional: left out, CapSkip reads them
+from `pageurl` at solve time, which is the safer choice when your copy of the
+page is more than a few minutes old.
+
+### Script URLs
+
+CapSkip posts the solution to the host a script URL names, so it refuses any
+script that is not on AWS WAF. The SDK applies the server's rule before the
+request is made: the URL must be `https`, its host must end in `.awswaf.com`, it
+must carry no credentials and no port other than 443, and its path must be one
+or more segments followed by `challenge.js`, `captcha.js` or `jsapi.js`. A query
+string is allowed. Anything else throws `ValidationException`, because CapSkip is
+not an AWS WAF integration for scripts hosted elsewhere.
+
+### GET `/res.php`
+
+The answer is **not a token**. With `json=1` it is an object in `request`:
+
+```json
+{"status":1,"request":{"captcha_voucher":"…","existing_token":"…"}}
+```
+
+and in plain text the same object as one line of JSON after `OK|`. The SDK
+expands it into `captcha_voucher` and `existing_token`; see
+[Return value](#return-value).
+
+### Exchanging the voucher
+
+The two values only work as a pair. POST them as JSON to the `voucher` endpoint
+beside the page's `challenge.js` (the same directory, with `voucher` in place of
+`challenge.js`). The response's `token` is the `aws-waf-token` cookie. Exchange
+them immediately rather than storing them for later.
+
+### SDK usage
+
+```js
+// Challenge page
+const result = await solver.amazonWaf(
+  'AQIDAHjcYuEXAMPLEghicBgQ/7bFaQZ+m5FKCMDnO+vTbNg96AHDh0IR5vgzHNceHYqZR+GOAAAAfjB8',
+  'https://example.com/protected',
+  {
+    iv: 'CgAFRDIjfgAAA5yY',
+    context: 'Rbp3r8fvbuhmrCqpUe8Mh1TLvs8OSKJZiSs2vCF4dt9rxVZI7xYJa2n5k/9r+XaXe7KUIu2I8nXTDHHkDvIOTDc2',
+    challenge_script: 'https://3f2a9c7d41b0.edge.sdk.awswaf.com/3f2a9c7d41b0/8e51d0c7a2f4/challenge.js',
+  },
+);
+
+// Widget page
+const result = await solver.amazonWaf(
+  'Xr9kEXAMPLE2bWQx1vTq8LmZ0aYc4dHs7nFp3gJt6uKw5eRi9AbCdEfGh=_0_1',
+  'https://example.com/protected',
+  { jsapiScript: 'https://5b7e0a19c3d8.us-east-1.captcha-sdk.awswaf.com/5b7e0a19c3d8/jsapi.js' },
+);
+
+result.captcha_voucher, result.existing_token;
+```
+
+Uses `recaptchaTimeout`: a real browser mints the token the voucher is issued
+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:
@@ -663,6 +897,34 @@ target form takes (`code` keeps the raw answer):
 }
 ```
 
+AWS WAF returns an object too, expanded into the voucher pair the site's
+`voucher` endpoint trades for the `aws-waf-token` cookie (`code` keeps the raw
+answer):
+
+```js
+{
+  captchaId: '12345',
+  code: { captcha_voucher: '…', existing_token: '…' },
+  captcha_voucher: 'eyJ2b3VjaGVyIjoiRVhBTVBMRSJ9.9QwZcEXAMPLEvoucherJk4LmN0pQ',
+  existing_token: '7d4c2a91-EXAMPLE-4f0b-9e6d-3a1b5c8e2f70:EQoAeXAMPLEtokenAAAA:Wm9wc2E=',
+}
+```
+
+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):
 
@@ -697,6 +959,10 @@ Convenience aliases mapped before sending to CapSkip:
 | `captchaKey` | `captchakey` |
 | `moduleScript` | `module_script` |
 | `nomoduleScript` / `noModuleScript` | `nomodule_script` |
+| `challengeScript` | `challenge_script` |
+| `captchaScript` | `captcha_script` |
+| `jsapi_script` | `jsapiScript` |
+| `captchaUrl` / `captchaURL` | `captcha_url` |
 | `proxy` object | `proxy` + `proxytype` strings |
 
 ```js

package/examples/amazon_waf.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * Solve an AWS WAF CAPTCHA.
+ *
+ * AWS WAF shows up in two forms, and the values you need depend on which one
+ * the target page uses:
+ *
+ *   * A challenge page -- the HTTP 405 interstitial that sets `window.gokuProps`
+ *     in an inline script. `sitekey` is `gokuProps.key`; `iv` and `context` are
+ *     `gokuProps.iv` and `gokuProps.context`. `challenge_script` and
+ *     `captcha_script` are the full URLs of the page's challenge.js and
+ *     captcha.js.
+ *   * A widget page -- an ordinary page that calls
+ *     `AwsWafCaptcha.renderCaptcha(container, { apiKey, ... })`. `sitekey` is
+ *     that `apiKey`, and `jsapiScript` is the full URL of jsapi.js.
+ *
+ * Only `sitekey` and the page URL are required. `iv` and `context` travel
+ * together: send both or neither. Left out, CapSkip reads them from the page
+ * at solve time, which is the safer choice when your copy of the page is more
+ * than a few minutes old.
+ *
+ * Every script URL must be an https URL on an awswaf.com host. CapSkip posts
+ * the solution to the host the script names, so it refuses anything else
+ * before the request is made.
+ *
+ * Unlike reCAPTCHA or Turnstile, the answer is NOT a token you put in a form.
+ * It is a voucher pair that AWS trades for the `aws-waf-token` cookie.
+ */
+
+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 = 'https://example.com/protected';
+
+// From the challenge page's window.gokuProps.
+const SITEKEY = 'AQIDAHjcYuEXAMPLEghicBgQ/7bFaQZ+m5FKCMDnO+vTbNg96AHDh0IR5vgzHNceHYqZR+GOAAAAfjB8';
+const IV = 'CgAFRDIjfgAAA5yY';
+const CONTEXT = 'Rbp3r8fvbuhmrCqpUe8Mh1TLvs8OSKJZiSs2vCF4dt9rxVZI7xYJa2n5k/9r+XaXe7KUIu2I8nXTDHHkDvIOTDc2';
+const CHALLENGE_JS = 'https://3f2a9c7d41b0.edge.sdk.awswaf.com/3f2a9c7d41b0/8e51d0c7a2f4/challenge.js';
+
+async function main() {
+  const result = await solver.amazonWaf(SITEKEY, PAGE_URL, {
+    iv: IV,
+    context: CONTEXT,
+    challenge_script: CHALLENGE_JS,
+  });
+
+  console.log('Captcha ID:    ', result.captchaId);
+  console.log('Voucher:       ', `${result.captcha_voucher.slice(0, 32)}...`);
+  console.log('Existing token:', `${result.existing_token.slice(0, 32)}...`);
+
+  // --- A widget page -------------------------------------------------------
+  // The widget's apiKey as the sitekey, and the jsapi.js it loads. No iv or
+  // context: a widget page has none.
+  //
+  //   await solver.amazonWaf(
+  //     'Xr9kEXAMPLE2bWQx1vTq8LmZ0aYc4dHs7nFp3gJt6uKw5eRi9AbCdEfGh=_0_1',
+  //     PAGE_URL,
+  //     { jsapiScript: 'https://5b7e0a19c3d8.us-east-1.captcha-sdk.awswaf.com/5b7e0a19c3d8/jsapi.js' },
+  //   );
+  //
+  // --- With a per-request proxy --------------------------------------------
+  //   await solver.amazonWaf(SITEKEY, PAGE_URL, {
+  //     proxy: { type: 'HTTP', uri: 'login:password@1.2.3.4:8080' },
+  //   });
+
+  // Exchange the pair for the aws-waf-token cookie: POST both values as JSON
+  // to the `voucher` endpoint that sits beside the page's challenge.js. The
+  // response's `token` is the cookie value. Do this immediately -- the voucher
+  // is short-lived, so do not store the pair for a later request.
+  const voucherUrl = new URL('voucher', CHALLENGE_JS).href;
+  console.log('Voucher URL:   ', voucherUrl);
+  //
+  //   const response = await fetch(voucherUrl, {
+  //     method: 'POST',
+  //     headers: { 'Content-Type': 'application/json' },
+  //     body: JSON.stringify({
+  //       captcha_voucher: result.captcha_voucher,
+  //       existing_token: result.existing_token,
+  //     }),
+  //   });
+  //   const { token } = await response.json();
+  //
+  //   // Then request the protected page with the cookie:
+  //   await fetch(PAGE_URL, { headers: { Cookie: `aws-waf-token=${token}` } });
+}
+
+main().catch((error) => {
+  console.error(`${error.name}: ${error.message}`);
+  process.exitCode = 1;
+});