capskip 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,78 @@ 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
+
+- **ALTCHA support** via `altcha(url, options)`. Pass `challengeUrl` for CapSkip
+  to fetch the challenge, or `challengeJson` with the document itself (a JSON
+  string, or an object which is serialized for you). Sending both is allowed —
+  the inline document wins. The result exposes `token` (the value the site's
+  `altcha` form field expects) and `number`, the counter that solved it; `code`
+  keeps the same raw string.
+- Parameter aliases `challengeUrl`/`challengeURL` for `challenge_url` and
+  `challengeJson`/`challengeJSON` for `challenge_json`.
+- `AltchaOptions` and the `token`/`number` result fields in the TypeScript
+  definitions.
+- Both ALTCHA generations are handled: the legacy scheme (SHA-1/256/384/512) and
+  proof-of-work v2 (PBKDF2 or SHA). Their tokens are shaped differently — a v2
+  payload carries no top-level `number`, its counter sitting at
+  `solution.counter` — so the counter is taken from the server's own `solution`
+  object, the one field both report the same way, and dug out of the token only
+  when a poll did not carry it.
+
+### Notes
+
+- ALTCHA is CPU proof-of-work rather than a browser solve, so it uses
+  `defaultTimeout` instead of the longer `recaptchaTimeout` that reCAPTCHA,
+  Turnstile and GeeTest use.
+- A proxy passed to `altcha()` applies only to the `challengeUrl` fetch; a task
+  carrying its challenge inline never touches the network.
+
 ## [1.1.0] - 2026-07-26
 
 ### Added

package/README.md

@@ -1,20 +1,55 @@
-# CapSkip Node.js SDK
+# CapSkip Node.js SDK — Captcha Solver for Node.js
 
+[![npm](https://img.shields.io/npm/v/capskip.svg)](https://www.npmjs.com/package/capskip)
 [![Node.js 18+](https://img.shields.io/badge/node-18%2B-brightgreen.svg)](https://nodejs.org/)
 [![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)
 
-Official Node.js client for the [CapSkip](https://capskip.com) **local** captcha solver.
+**Solve reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha and image captchas from Node.js.**
 
-CapSkip runs on your machine and exposes a standard captcha-solver HTTP API (the familiar `in.php` / `res.php` endpoints). This SDK wraps that API with clean, familiar method names, so you can solve captchas locally — no per-solve API fees beyond your CapSkip license.
+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.
+
+```bash
+npm install capskip
+```
+
+---
+
+## How it works
+
+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.
+
+## Supported captcha types
+
+| Captcha | Method |
+|---|---|
+| **Image captcha solver** (distorted text / OCR) | `solver.normal(file)` |
+| **reCAPTCHA v2 solver** (checkbox) | `solver.recaptcha(sitekey, url)` |
+| **reCAPTCHA v2 invisible solver** | `solver.recaptcha(sitekey, url, { invisible: 1 })` |
+| **reCAPTCHA Enterprise solver** | `solver.recaptcha(sitekey, url, { enterprise: 1 })` |
+| **reCAPTCHA v3 solver** | `solver.recaptcha(sitekey, url, { version: 'v3', action: 'submit' })` |
+| reCAPTCHA v3 Enterprise | `solver.recaptcha(sitekey, url, { version: 'v3', enterprise: 1 })` |
+| **Cloudflare Turnstile solver** (widget) | `solver.turnstile(sitekey, url)` |
+| 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()`.
+
+Point the SDK at the [live captcha demo pages](https://capskip.com/captcha-demo/) to sanity-check your setup against real widgets.
 
 ---
 
 ## Quick start (5 minutes)
 
-### 1. Install CapSkip
+### 1. Install the CapSkip captcha solver
 
-Download and run the CapSkip desktop app from [capskip.com](https://capskip.com). Leave it running in the background.
+Download and run the CapSkip desktop app — [CapSkipInstaller.msi](https://capskip.com/download/CapSkipInstaller.msi). Leave it running in the background.
 
 In CapSkip settings, note:
 
@@ -58,19 +93,20 @@ Every solve method returns a Promise — use `await` or `.then()`.
 
 ---
 
-## Supported captcha types
+## Why solve captchas locally
 
-| Type | SDK method |
-|---|---|
-| Image CAPTCHA (distorted text) | `solver.normal(file)` |
-| reCAPTCHA v2 (checkbox) | `solver.recaptcha(sitekey, url)` |
-| reCAPTCHA v2 Invisible | `solver.recaptcha(sitekey, url, { invisible: 1 })` |
-| reCAPTCHA v2 Enterprise | `solver.recaptcha(sitekey, url, { enterprise: 1 })` |
-| reCAPTCHA v3 | `solver.recaptcha(sitekey, url, { version: 'v3' })` |
-| reCAPTCHA v3 Enterprise | `solver.recaptcha(sitekey, url, { version: 'v3', enterprise: 1 })` |
-| Cloudflare Turnstile (widget) | `solver.turnstile(sitekey, url)` |
-| Cloudflare Turnstile (challenge page) | `solver.turnstile(sitekey, url, { data, pagedata })` |
-| GeeTest v3 (slide) | `solver.geetest(gt, challenge, url)` |
+Cloud captcha APIs charge per solve, which turns a retry loop into an expense and routes every page URL and sitekey you touch through someone else's queue.
+
+CapSkip flips that around:
+
+- **Unlimited solving** — one license, no per-captcha charge, no balance to top up
+- **Runs on `127.0.0.1`** — the SDK never talks to a third-party server
+- **No per-key rate limit** — throughput is whatever your machine can manage
+- **Fast** — image captchas come back in well under a second; a typical reCAPTCHA v2 lands in 30–45 seconds
+
+### Coming from 2captcha or Anti-Captcha
+
+CapSkip answers on the same `in.php` / `res.php` endpoints, so it works as a **2captcha API alternative**: an existing integration usually needs nothing more than its host pointed at `127.0.0.1:8080`. The [migration notes](https://capskip.com/2captcha-api-alternative/) cover the details, if you would rather keep your current client library than switch to this one.
 
 ---
 
@@ -98,7 +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
+  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)
 });
 ```
@@ -178,7 +216,104 @@ const result = await solver.geetest(
 result.challenge, result.validate, result.seccode;
 ```
 
-### With a proxy (reCAPTCHA, Turnstile & GeeTest only)
+### ALTCHA
+
+ALTCHA is proof-of-work, not recognition — there is nothing to read, so a solve
+is deterministic and takes milliseconds. Give CapSkip the endpoint that serves
+the challenge, or the challenge document itself.
+
+```js
+const result = await solver.altcha('https://example.com/signup', {
+  challengeUrl: 'https://example.com/captcha/api/altcha/challenge',
+});
+
+// Post this back in the form field the widget uses, named `altcha`
+result.token;
+```
+
+Challenges expire fast — some sites inside two minutes — so fetch one
+immediately before solving and submit the token promptly.
+
+### 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
@@ -213,6 +348,53 @@ More examples: [`examples/`](examples/)
 
 ---
 
+## Puppeteer, Playwright and Selenium
+
+The SDK hands back a token; your existing browser tooling does the driving. The shape is the same whichever you use:
+
+1. Read the sitekey off the page (`data-sitekey`, or the widget's config object).
+2. Call the matching solve method with that sitekey and the page URL.
+3. Write the token into the response field and submit.
+
+### Puppeteer
+
+```js
+const sitekey = await page.$eval('[data-sitekey]', el => el.dataset.sitekey);
+const { code } = await solver.recaptcha(sitekey, page.url());
+
+await page.evaluate(t => {
+  document.getElementById('g-recaptcha-response').value = t;
+}, code);
+await page.click('button[type=submit]');
+```
+
+### Playwright
+
+```js
+const sitekey = await page.getAttribute('[data-sitekey]', 'data-sitekey');
+const { code } = await solver.recaptcha(sitekey, page.url());
+
+await page.evaluate(t => {
+  document.getElementById('g-recaptcha-response').value = t;
+}, code);
+```
+
+### Selenium WebDriver
+
+```js
+const el = await driver.findElement(By.css('[data-sitekey]'));
+const sitekey = await el.getAttribute('data-sitekey');
+const { code } = await solver.recaptcha(sitekey, await driver.getCurrentUrl());
+
+await driver.executeScript(
+  'document.getElementById("g-recaptcha-response").value = arguments[0];', code,
+);
+```
+
+Longer walkthroughs: [Puppeteer](https://capskip.com/puppeteer-captcha-solver/), [Playwright](https://capskip.com/playwright-captcha-solver/) and [Selenium](https://capskip.com/selenium-captcha-solver/).
+
+---
+
 ## Return value
 
 Every solve method resolves to:
@@ -226,7 +408,11 @@ Every solve method resolves to:
 ```
 
 GeeTest additionally expands its answer into `challenge`, `validate`, and
-`seccode`, while `code` keeps the raw JSON string.
+`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.
 
 ---
 
@@ -267,6 +453,42 @@ const result: SolveResult = await solver.recaptcha('...', 'https://example.com')
 
 ---
 
+## FAQ
+
+### 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.
+
+### Is this a free captcha solver?
+
+The SDK itself is MIT-licensed and free. Solving needs the CapSkip app, which is bought once rather than metered per captcha, so your cost stops scaling with volume.
+
+### 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.
+
+### Does it work with Puppeteer and Playwright?
+
+Yes — see [above](#puppeteer-playwright-and-selenium). The SDK never touches a browser itself, so it drops into whatever stack you already have, Selenium and plain `fetch` included.
+
+### Why is my reCAPTCHA v3 score low?
+
+Google derives v3 scores from IP reputation, cookies and browsing history. A solver returns a valid token, but it cannot change how Google grades that token — `score` is forwarded as the target you want, not a guarantee. If a site enforces a high threshold, solve through a cleaner IP using the `proxy` option.
+
+### Can I use it as a 2captcha alternative?
+
+Yes. CapSkip serves the same endpoints, so you can either move to this SDK or repoint an existing 2captcha client at `127.0.0.1:8080`.
+
+### Does the captcha have to be on a public page?
+
+For widget captchas, yes — CapSkip loads the URL you pass it. Image captchas only need the image, and that can be a local file.
+
+### Does it work with TypeScript and ESM?
+
+Types ship in the package. The runtime is CommonJS, so `import { CapSkip } from 'capskip'` works from ESM through Node's interop.
+
+---
+
 ## Development
 
 ```bash
@@ -282,10 +504,12 @@ The test suite uses Node's built-in test runner — no extra dependencies. See [
 
 ## Links
 
-- [CapSkip website](https://capskip.com)
-- [CapSkip API docs](https://capskip.com/api-docs/)
-- [Report an issue](https://github.com/capskip/capskip-node/issues)
-- [npm package](https://www.npmjs.com/package/capskip)
+- [CapSkip — local captcha solver](https://capskip.com) · [download the app](https://capskip.com/download/CapSkipInstaller.msi)
+- [Captcha demo pages](https://capskip.com/captcha-demo/) — live reCAPTCHA, Turnstile, GeeTest and image widgets
+- [Node.js captcha solver guide](https://capskip.com/nodejs-captcha-solver/)
+- [HTTP API docs](https://capskip.com/api-docs/)
+- Other clients: [Python](https://github.com/capskip/capskip-python) · [PHP](https://github.com/capskip/capskip-php) · [.NET](https://github.com/capskip/capskip-dotnet) · [MCP server for AI agents](https://github.com/capskip/capskip-mcp)
+- [npm package](https://www.npmjs.com/package/capskip) · [report an issue](https://github.com/capskip/capskip-node/issues)
 
 ---