capskip 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.3.0] - 2026-09-22
+
+### Added
+
+- **Capy Puzzle support** via `capy(sitekey, url, options)`. The site key
+  (conventionally prefixed `PUZZLE_`) is sent as the `captchakey` the API
+  documents. Optional `api_server` selects the Capy API the key lives behind,
+  defaulting to `https://jp.api.capy.me`.
+  A Capy answer is **not a token**: the result expands into `captchakey`,
+  `challengekey` and `answer`, which go into the target form's `capy_captchakey`,
+  `capy_challengekey` and `capy_answer` fields. `code` keeps the raw answer.
+- **CaptchaFox support** via `captchafox(sitekey, url, options)`. The result
+  exposes `token` (for the form's `cf-captcha-response` field) and, when the
+  solve reported one, `userAgent` — the UA the browser actually minted the token
+  under, which is not the one you sent. Optional `api_server` selects the widget
+  source; the MAM package returns a `MAM_` prefixed token.
+- **Friendly Captcha support** via `friendlyCaptcha(sitekey, url, options)`.
+  Pass `version` (`v1`/`v2`, or a bare `1`/`2`), or `moduleScript` /
+  `nomoduleScript` with the widget script URLs and let CapSkip read the version
+  off the build the site actually loads. Optional `api_server` accepts `global`
+  (the default), `eu`, or a full URL for the data-residency tenant. The result
+  exposes `token`, for `frc-captcha-solution` on v1 or `frc-captcha-response` on
+  v2.
+- Parameter aliases `userAgent`/`user_agent` for `useragent`, `captchaKey` for
+  `captchakey`, and `moduleScript`/`nomoduleScript` for `module_script` /
+  `nomodule_script`.
+- TypeScript definitions for `CapyOptions`, `CaptchaFoxOptions` and
+  `FriendlyCaptchaOptions`, plus the new `SolveResult` fields.
+
+### Notes
+
+- `version: 'avatar'` is refused locally for Capy. CapSkip solves the puzzle
+  family only, and answering an avatar request with a puzzle answer would bill
+  for a solve the target site rejects, indistinguishably from a broken solver.
+- An unknown Friendly Captcha `version` is refused locally too. The two versions
+  are different protocols sharing one sitekey namespace, so solving the wrong one
+  returns a well-formed token the site rejects with nothing to indicate why.
+- CaptchaFox and Friendly Captcha use `recaptchaTimeout`: the first is a real
+  browser solve, and the second has its difficulty set per request by the service
+  (and always solves in a browser on v2). Capy uses `defaultTimeout` — it is one
+  HTTP fetch plus pixel math, held back to roughly two seconds because Capy
+  refuses answers that arrive faster than a human could have produced them.
+
 ## [1.2.0] - 2026-09-12
 
 ### 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 and image captchas from Node.js.**
+**Solve reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha 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()`. 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()`. Nothing leaves your network, and there is no credit balance to keep an eye on.
 
 ## Supported captcha types
 
@@ -35,6 +35,9 @@ This SDK is a thin wrapper over that API, with the method names you would expect
 | Cloudflare Turnstile (challenge page) | `solver.turnstile(sitekey, url, { data, pagedata })` |
 | **GeeTest v3 solver** (slide puzzle) | `solver.geetest(gt, challenge, url)` |
 | **ALTCHA solver** (proof-of-work) | `solver.altcha(url, { challengeUrl })` |
+| **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 })` |
 
 **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()`.
 
@@ -131,8 +134,9 @@ const solver = new CapSkip({
   host: '127.0.0.1',        // CapSkip host
   port: 8080,               // CapSkip port from app settings
   defaultTimeout: 120,      // seconds — image captcha polling timeout
-  recaptchaTimeout: 300,    // seconds — reCAPTCHA / Turnstile / GeeTest polling timeout
-                            // (ALTCHA uses defaultTimeout — CPU work, not a browser solve)
+  recaptchaTimeout: 300,    // seconds — reCAPTCHA / Turnstile / GeeTest / CaptchaFox /
+                            // Friendly Captcha 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)
 });
 ```
@@ -230,7 +234,86 @@ result.token;
 Challenges expire fast — some sites inside two minutes — so fetch one
 immediately before solving and submit the token promptly.
 
-### With a proxy (reCAPTCHA, Turnstile, GeeTest & ALTCHA only)
+### Capy Puzzle
+
+A Capy solution is not a token. It is three values that together go into the
+target form, so post all three back exactly as returned.
+
+```js
+const result = await solver.capy(
+  'PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v',
+  'https://example.com/login',
+);
+
+// capy_captchakey, capy_challengekey and capy_answer respectively
+result.captchakey, result.challengekey, result.answer;
+```
+
+`answer` is the drag path the widget would have recorded — submit it verbatim,
+without trimming or re-encoding it. The challenge key is single-use and
+short-lived, so submit promptly rather than caching the three values.
+
+Pass `api_server` when the widget script points somewhere other than
+`https://jp.api.capy.me`. Only the `puzzle` family is solved; `version: 'avatar'`
+is refused rather than answered with a puzzle answer the site would reject.
+
+### CaptchaFox
+
+```js
+const result = await solver.captchafox(
+  'sk_xtNxpk6fCdFbxh1_xJeGflSdCE9tn99G',
+  'https://example.com/signup',
+);
+
+// Post this back in the form field the widget uses, named `cf-captcha-response`
+result.token;
+
+// The UA the token was minted under — submit under this one, not your own
+result.userAgent;
+```
+
+`url` has to be the page the widget actually runs on: CaptchaFox checks it
+against the domains the key is registered for and refuses a mismatch
+permanently, not intermittently.
+
+Pass `api_server` only when the page does not load the default widget. A page
+loading the MAM package expects a `MAM_` prefixed token, and sending the wrong
+source still succeeds — it just returns a token the site will not accept, which
+reads as a silent verification failure rather than an error.
+
+### Friendly Captcha
+
+Two different protocols ship under this name and a sitekey does not tell you
+which one a site uses, so say which — or send the widget script and let CapSkip
+read it off the build the site actually loads.
+
+```js
+const result = await solver.friendlyCaptcha(
+  'FCMGEMUD2M567T8G',
+  'https://example.com/signup',
+  { version: 'v2' },
+);
+
+// v1 → frc-captcha-solution, v2 → frc-captcha-response
+result.token;
+```
+
+```js
+// Or let the script URL decide the version
+const result = await solver.friendlyCaptcha(
+  'FCMGEMUD2M567T8G',
+  'https://example.com/signup',
+  { moduleScript: 'https://cdn.example.com/@friendlycaptcha/sdk@0.1.6/site.min.js' },
+);
+```
+
+Solving the wrong version returns a well-formed token the target site rejects,
+with nothing to indicate the version was the problem. With neither `version` nor
+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.
+
+### With a proxy (every method except image captcha)
 
 ```js
 // Proxy is not supported for image captcha
@@ -325,7 +408,10 @@ Every solve method resolves to:
 ```
 
 GeeTest additionally expands its answer into `challenge`, `validate`, and
-`seccode`, while `code` keeps the raw JSON string. ALTCHA adds `token` (the same
+`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.
 
 ---
@@ -371,7 +457,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()` 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()` 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.
 
 ### Is this a free captcha solver?
 
@@ -379,7 +465,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, 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, and image/text captchas. Not hCaptcha, and not FunCaptcha/Arkose.
 
 ### Does it work with Puppeteer and Playwright?
 

package/docs/API_REFERENCE.md

@@ -24,9 +24,13 @@ method returns a `Promise`.
 | Cloudflare Turnstile | `turnstile()` | `turnstile` |
 | GeeTest v3 (slide) | `geetest()` | `geetest` |
 | ALTCHA (proof-of-work) | `altcha()` | `altcha` |
+| Capy Puzzle (slide) | `capy()` | `capy` |
+| CaptchaFox (widget) | `captchafox()` | `captchafox` |
+| Friendly Captcha (proof-of-work) | `friendlyCaptcha()` | `friendly_captcha` |
 
-**Proxy** is supported for reCAPTCHA, Turnstile, GeeTest, and ALTCHA — not for image
-captcha. For ALTCHA the proxy is used only for the `challengeUrl` fetch.
+**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
+puzzle-image fetch, which is the only request a Capy solve makes.
 
 ---
 
@@ -377,6 +381,237 @@ purely visual and never reaches CapSkip.
 
 ---
 
+## 7. Capy Puzzle — `capy(sitekey, url, { ... })`
+
+Capy is a slide puzzle: a piece has to be dragged into the hole cut out of a
+photograph. CapSkip locates the hole and produces the drag path — one HTTP fetch
+plus pixel math, no browser.
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `method` | string | Yes | `capy` |
+| `captchakey` | string | Yes | The site's public Capy key, conventionally prefixed `PUZZLE_`. The SDK sends its `sitekey` argument here. |
+| `pageurl` | string | Yes | Full URL of the page the captcha is on |
+| `api_server` | string | No | Root of the Capy API the key lives behind. Default `https://jp.api.capy.me` |
+| `version` | string | No | `puzzle` (the default). Only the puzzle family is solved |
+| `useragent` | string | No | User-Agent to send with the puzzle request |
+| `json` | int | No | `0` plain text, `1` JSON |
+| `proxy` | string | No | Proxy address |
+| `proxytype` | string | No | Proxy type |
+
+`sitekey` and `websiteKey` are accepted by the server as aliases for
+`captchakey`; the SDK sends the documented name.
+
+`version: 'avatar'` is refused by the SDK before the request is made. Avatar is a
+different challenge behind a different endpoint, and answering it with a puzzle
+answer would bill for a solve the target site rejects, indistinguishably from a
+broken solver.
+
+> `api.capy.me` no longer resolves, although several solver services still
+> document it. The live host is `jp.api.capy.me`; if a site's widget points
+> somewhere else, pass that as `api_server`.
+
+### Getting the captcha key
+
+It is in the page source as `capy_captchakey`, or in the widget script URL:
+`<script src="https://jp.api.capy.me/puzzle/get_js/?k=PUZZLE_XXXX">`.
+
+### GET `/res.php`
+
+The answer is **not a token**. It is an object, which the SDK expands into three
+result fields. See [Return value](#return-value).
+
+### SDK usage
+
+```js
+const result = await solver.capy(
+  'PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v',
+  'https://example.com/login',
+);
+
+// With a non-default API server
+const result = await solver.capy(
+  'PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v',
+  'https://example.com/login',
+  { api_server: 'https://jp.api.capy.me/' },
+);
+
+// capy_captchakey, capy_challengekey, capy_answer
+result.captchakey, result.challengekey, result.answer;
+```
+
+### Timing
+
+Capy grades the wall-clock gap between issuing the puzzle and verifying the
+answer, and refuses anything superhuman with `CAPTCHA verification failed` — the
+same message a wrong answer gets. CapSkip therefore holds every result until two
+seconds have elapsed since it drew the puzzle. This is invisible if you poll: the
+task simply takes about two seconds instead of a fifth of one. Nothing to
+configure.
+
+The challenge key is single-use and short-lived, so submit the three values
+promptly rather than caching them.
+
+---
+
+## 8. CaptchaFox — `captchafox(sitekey, url, { ... })`
+
+CaptchaFox scores the browser itself rather than asking the visitor to read
+anything; most visitors never see a puzzle. CapSkip drives the real widget in a
+real browser and returns the verification token.
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `method` | string | Yes | `captchafox` |
+| `sitekey` | string | Yes | The public key the widget renders with, conventionally prefixed `sk_` |
+| `pageurl` | string | Yes | Full URL of the page the widget appears on |
+| `api_server` | string | No | Widget entry point. Default `https://cdn.captchafox.com/` |
+| `useragent` | string | No | Accepted for compatibility and not applied — CapSkip uses its own browser's identity |
+| `json` | int | No | `0` plain text, `1` JSON |
+| `proxy` | string | No | Proxy address |
+| `proxytype` | string | No | Proxy type |
+
+### Choosing the widget source
+
+| `api_server` | Token | Default |
+|---|---|---|
+| `https://cdn.captchafox.com/` | Plain | Yes |
+| `https://s.uicdn.com/mampkg/…` | `MAM_` prefixed | No |
+
+Read the value from the `<script>` tag that loads the widget. If you send the
+wrong one the solve still succeeds, but the token comes back in a format the
+target site will not accept — a silent verification failure rather than an error.
+
+### The page URL has to match the key
+
+CaptchaFox keys are registered against a list of allowed domains and the service
+checks the host before issuing anything. A correct key used on a page outside
+that list is refused permanently, not intermittently. CapSkip reports that case
+rather than retrying it, because retrying cannot help.
+
+### Challenge types
+
+| Challenge | Frequency | Supported |
+|---|---|---|
+| Invisible | Usually | Yes |
+| Slide | Sometimes | Yes |
+| Image select | Rarely | No |
+| Audio | Rarely | No |
+
+The two unsupported ones are uncommon and a retry usually draws a different
+challenge, so treat an unsolvable result as a signal to resubmit rather than a
+permanent failure of the key.
+
+### SDK usage
+
+```js
+const result = await solver.captchafox(
+  'sk_xtNxpk6fCdFbxh1_xJeGflSdCE9tn99G',
+  'https://example.com/signup',
+);
+
+// Post in the form field named cf-captcha-response
+result.token;
+
+// Submit under the UA that minted the token, not your own
+result.userAgent;
+```
+
+Uses `recaptchaTimeout` — it is a real browser session, and longer again when an
+interactive challenge is drawn.
+
+---
+
+## 9. Friendly Captcha — `friendlyCaptcha(sitekey, url, { ... })`
+
+Proof-of-work, with nothing shown on screen. The widget searches for values that
+hash below a difficulty the service sets per request.
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `method` | string | Yes | `friendly_captcha` |
+| `sitekey` | string | Yes | The `data-sitekey` of the element carrying `class="frc-captcha"` |
+| `pageurl` | string | Yes | Full URL of the page the widget appears on |
+| `version` | string | No | `v1` (default) or `v2`; a bare `1` or `2` is accepted |
+| `module_script` | string | No | `src` of the widget script tag carrying `type="module"` |
+| `nomodule_script` | string | No | `src` of the widget script tag carrying `nomodule` |
+| `api_server` | string | No | Data residency endpoint: `global` (default), `eu`, or a full URL |
+| `useragent` | string | No | User-Agent to send with the request |
+| `json` | int | No | `0` plain text, `1` JSON |
+| `proxy` | string | No | Proxy address |
+| `proxytype` | string | No | Proxy type |
+
+### Version 1 and version 2
+
+Two entirely different protocols ship under this one name, and a sitekey does not
+tell you which one a site uses — they share a brand and a sitekey namespace and
+nothing else. Both are live. Solve the wrong one and you get a well-formed token
+the target site rejects, with no indication that the version was the problem.
+
+| `version` | Widget package | Script |
+|---|---|---|
+| `v1` | `friendly-challenge` | `widget.module.min.js` / `widget.min.js` |
+| `v2` | `@friendlycaptcha/sdk` | `site.min.js` |
+
+CapSkip decides in this order, stopping at the first answer: the `version`
+parameter; then the script URL from `moduleScript` or `nomoduleScript`, which is
+the most reliable signal because it is the build the site actually loads; then
+v1. The SDK refuses any other `version` value locally.
+
+### Submitting the token
+
+| `version` | Form field |
+|---|---|
+| `v1` | `frc-captcha-solution` |
+| `v2` | `frc-captcha-response` |
+
+The field names differ, which is what catches an integration moved from one to
+the other. A v1 token is four dot-separated parts and runs to a few hundred
+characters; a v2 token is a single opaque string beginning `AQQA.` and is roughly
+six kilobytes, so size whatever carries it accordingly.
+
+### SDK usage
+
+```js
+// Say which version
+const result = await solver.friendlyCaptcha(
+  'FCMGEMUD2M567T8G',
+  'https://example.com/signup',
+  { version: 'v2' },
+);
+
+// …or let the script URL decide it
+const result = await solver.friendlyCaptcha(
+  'FCMGEMUD2M567T8G',
+  'https://example.com/signup',
+  { moduleScript: 'https://cdn.example.com/@friendlycaptcha/sdk@0.1.6/site.min.js' },
+);
+
+// EU data-residency tenant
+const result = await solver.friendlyCaptcha(
+  'FCMGEMUD2M567T8G',
+  'https://example.com/signup',
+  { version: 'v2', api_server: 'eu' },
+);
+
+result.token;
+```
+
+Uses `recaptchaTimeout`: the service decides how much work a request is worth at
+the moment it is made, so solve time is not a constant, and v2 always solves in a
+browser.
+
+---
+
 ## Return value
 
 Every solve method resolves to:
@@ -401,6 +636,33 @@ form field it goes in) and `number`, the counter that solved it:
 }
 ```
 
+CaptchaFox and Friendly Captcha expose `token`, the same string as `code`, named
+for the form field it goes in. CaptchaFox adds `userAgent` when the solve
+reported one — the UA the browser minted the token under, not one you sent:
+
+```js
+{
+  captchaId: '12345',
+  code: '177f50c25b845601e5c779cdb51b040d…',
+  token: '177f50c25b845601e5c779cdb51b040d…',
+  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) …',
+}
+```
+
+Capy returns an object rather than a token, expanded into the three fields the
+target form takes (`code` keeps the raw answer):
+
+```js
+{
+  captchaId: '12345',
+  code: { captchakey: 'PUZZLE_…', challengekey: '…', answer: '…', respKey: '' },
+  captchakey: 'PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v',
+  challengekey: 'BalY2gJaI8uA2SGVOZhqBQ3V0CYSNNGP',
+  answer: '0xax8ex0xax84x0xkx7qx0x18x76x…',
+  respKey: '',
+}
+```
+
 GeeTest additionally expands its answer into `challenge`, `validate`, and
 `seccode` (`code` keeps the raw JSON string):
 
@@ -431,6 +693,10 @@ Convenience aliases mapped before sending to CapSkip:
 | `api_subdomain` | `api_server` |
 | `challengeUrl` / `challengeURL` | `challenge_url` |
 | `challengeJson` / `challengeJSON` | `challenge_json` |
+| `userAgent` / `user_agent` | `useragent` |
+| `captchaKey` | `captchakey` |
+| `moduleScript` | `module_script` |
+| `nomoduleScript` / `noModuleScript` | `nomodule_script` |
 | `proxy` object | `proxy` + `proxytype` strings |
 
 ```js

package/examples/captchafox.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * Solve a CaptchaFox challenge.
+ *
+ * CaptchaFox scores the browser itself rather than asking the visitor to read
+ * anything, so most solves draw no puzzle at all. CapSkip drives the real widget
+ * in a real browser and returns the verification token it would have produced.
+ *
+ * You need two values, both read off the target page:
+ *
+ *   * sitekey - the public key the widget renders with, conventionally prefixed
+ *     `sk_`. It is on the widget container as `data-sitekey`, or in the
+ *     `captchafox.render(...)` call. If the page builds the widget at runtime,
+ *     open DevTools -> Network and find the request to api.captchafox.com: the
+ *     key is the path segment after /captcha/.
+ *   * pageurl - the full URL of the page the widget appears on
+ *
+ * The page URL has to match: CaptchaFox keys are registered against a list of
+ * allowed domains and the service checks the host before it issues anything. A
+ * key that is correct but used on a page outside that list is refused
+ * permanently, not intermittently -- so if a sitekey fails immediately and
+ * consistently, check that you are sending the page the widget actually runs on
+ * rather than a search page, a redirect or a shortened link.
+ */
+
+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 SITEKEY = 'sk_xtNxpk6fCdFbxh1_xJeGflSdCE9tn99G';
+const PAGE_URL = 'https://example.com/signup';
+
+async function main() {
+  const result = await solver.captchafox(SITEKEY, PAGE_URL);
+
+  console.log('Captcha ID:', result.captchaId);
+  console.log('Token:     ', `${result.token.slice(0, 60)}...`);
+  console.log('User-Agent:', result.userAgent || '(none reported)');
+
+  // --- Choosing the widget source ------------------------------------------
+  // CaptchaFox publishes its widget from two places, and which one a site loads
+  // decides the shape of the token it expects back. Send api_server only when
+  // the target page does not use the default (https://cdn.captchafox.com/).
+  //
+  //   await solver.captchafox(SITEKEY, PAGE_URL, {
+  //     api_server: 'https://s.uicdn.com/mampkg/@mamdev/core.frontend.libs.captchafox/',
+  //   });
+  //
+  // That one returns a MAM_ prefixed token. Read the value from the <script>
+  // tag on the target page: if you send the wrong one the solve still succeeds,
+  // but the token comes back in a format the site will not accept, which looks
+  // like a silent verification failure rather than an error.
+  //
+  // --- With a per-request proxy --------------------------------------------
+  // CapSkip does not force a proxy, but CaptchaFox scores the network a widget
+  // runs on as well as the browser, so repeated solves from one address push
+  // that address toward the interactive challenges and then toward refusals.
+  //
+  //   await solver.captchafox(SITEKEY, PAGE_URL, {
+  //     proxy: { type: 'HTTP', uri: 'login:password@1.2.3.4:8080' },
+  //   });
+
+  // Post the token back in the form field the widget uses, named
+  // `cf-captcha-response`. Treat it as opaque and pass it through unchanged --
+  // it is verified server side against the session that produced it, so any
+  // edit invalidates it.
+  //
+  //   await fetch(SIGNUP_URL, {
+  //     method: 'POST',
+  //     headers: { 'User-Agent': result.userAgent },
+  //     body: new URLSearchParams({
+  //       email: 'someone@example.com',
+  //       'cf-captcha-response': result.token,
+  //     }),
+  //   });
+  //
+  // Some integrations read the token from a JSON body field instead, so check
+  // what the page's own submit sends and mirror it.
+  console.log('Form field:', { 'cf-captcha-response': `${result.token.slice(0, 40)}...` });
+
+  // Submit under the User-Agent the token was minted with, not your own.
+  // CapSkip solves in a real browser and uses that browser's identity, so the
+  // UA it reports is the one the token is bound to.
+  //
+  // Tokens are short lived: submit promptly rather than holding one while a
+  // user fills in a form, and solve again if the form is abandoned and resumed.
+
+  // Two of CaptchaFox's challenge types are not solvable -- image-select and
+  // the audio fallback, both rare. They are reported as unsolvable rather than
+  // waited out, so treat a failure as a signal to resubmit into a fresh
+  // challenge rather than as a permanent failure of the key.
+}
+
+main().catch((error) => {
+  console.error(`${error.name}: ${error.message}`);
+  process.exitCode = 1;
+});