capskip 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+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.0.2] - 2026-07-15
+
+### Fixed
+
+- Submitting with `json=1` no longer fails with `ApiException: cannot recognize
+  response`. With `json=1` CapSkip's `in.php` returns `{"status":1,"request":"<id>"}`
+  instead of `OK|<id>`; `send()` now parses both forms, so `normal(file, { json: 1 })`
+  and the equivalent reCAPTCHA/Turnstile calls submit and solve correctly.
+
+## [1.0.1] - 2026-07-14
+
+### Fixed
+
+- Polling no longer crashes with `ApiException: cannot recognize response` when
+  CapSkip returns an empty response body. CapSkip returns an empty body while no
+  result is available yet — briefly right after a captcha is submitted (before it
+  reports `CAPCHA_NOT_READY`), for an unknown id, and after a solved token has
+  already been read. The SDK now treats an empty body as "not ready" and keeps
+  polling, so `recaptcha()`, `turnstile()`, and `normal()` solve reliably instead
+  of failing on the first poll.
+
+## [1.0.0] - 2026-07-14
+
+### Added
+
+- Initial release of the CapSkip Node.js SDK
+- `CapSkip` client for the local CapSkip API — every method returns a Promise
+- `AsyncCapSkip` / `AsyncApiClient` exported as aliases for cross-SDK parity
+- Image CAPTCHA solving via `normal()` (file, URL, base64, or data-URI)
+- reCAPTCHA v2 / v3 solving via `recaptcha()` (invisible, enterprise, proxy)
+- Cloudflare Turnstile solving via `turnstile()` (widget and challenge page)
+- Turnstile automatically polls with `json=1` and returns `userAgent` when provided
+- Manual workflow: `send()`, `getResult()`, `solve()`
+- Adaptive result polling — starts at 0.25s and backs off (doubling) up to the
+  configured `pollingInterval`, so fast solves (e.g. image captchas) return in a
+  fraction of a second; `pollingInterval` also accepts sub-second values
+- Familiar parameter aliases (`url`→`pageurl`, `score`→`min_score`, etc.)
+- Proxy support via object format `{ type: '...', uri: '...' }`
+- Strict per-captcha parameter validation — only documented parameters are accepted
+- Error hierarchy: `ValidationException`, `NetworkException`, `ApiException`, `TimeoutException`
+- Bundled TypeScript type definitions
+- Example scripts for every supported captcha type
+- Unit and integration tests using Node's built-in test runner — no runtime dependencies
+- Documentation: Tutorial, Getting Started, API Reference, Troubleshooting
+
+[1.0.2]: https://github.com/capskip/capskip-node/releases/tag/v1.0.2
+[1.0.1]: https://github.com/capskip/capskip-node/releases/tag/v1.0.1
+[1.0.0]: https://github.com/capskip/capskip-node/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CapSkip
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+# CapSkip Node.js SDK
+
+[![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.
+
+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 cloud service and no per-solve API fees beyond your CapSkip license.
+
+---
+
+## Quick start (5 minutes)
+
+### 1. Install CapSkip
+
+Download and run the CapSkip desktop app from [capskip.com](https://capskip.com). Leave it running in the background.
+
+In CapSkip settings, note:
+
+- **API port** (default: `8080`)
+- **API key** (optional — if validation is disabled, any string works)
+
+### 2. Install the SDK
+
+```bash
+npm install capskip
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/capskip/capskip-node.git
+cd capskip-node
+npm install
+```
+
+### 3. Solve your first captcha
+
+```js
+const { CapSkip } = require('capskip');
+
+const solver = new CapSkip({ host: '127.0.0.1', port: 8080 });
+
+(async () => {
+  const result = await solver.recaptcha(
+    'YOUR_SITEKEY',
+    'https://example.com/page-with-recaptcha',
+  );
+
+  console.log(result.code); // g-recaptcha-response token
+})();
+```
+
+> **Prerequisite:** CapSkip must be running before you call the SDK. If you see a connection error, see [Troubleshooting](docs/TROUBLESHOOTING.md).
+
+Every solve method returns a Promise — use `await` or `.then()`.
+
+---
+
+## Supported captcha types
+
+| 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 })` |
+
+---
+
+## Documentation
+
+| Guide | Description |
+|---|---|
+| [Tutorial](docs/TUTORIAL.md) | Complete walkthrough of every captcha type |
+| [Getting Started](docs/GETTING_STARTED.md) | Full setup: CapSkip app, SDK install, first script |
+| [API Reference](docs/API_REFERENCE.md) | All classes, methods, parameters, and return values |
+| [Examples](examples/) | Ready-to-run scripts for every captcha type |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Connection errors, timeouts, proxy issues |
+| [Contributing](CONTRIBUTING.md) | Development setup, tests, pull requests |
+| [Changelog](CHANGELOG.md) | Release history |
+
+---
+
+## Configuration
+
+```js
+const { CapSkip } = require('capskip');
+
+const solver = new CapSkip({
+  apiKey: 'capskip',        // your CapSkip API key (or any string if validation is off)
+  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 polling timeout
+  pollingInterval: 5,       // max seconds between res.php polls (starts at 0.25s, backs off to this)
+});
+```
+
+Use environment variables in production:
+
+```bash
+# Linux / macOS
+export CAPSKIP_API_KEY="your-key"
+export CAPSKIP_HOST="127.0.0.1"
+export CAPSKIP_PORT="8080"
+```
+
+```powershell
+# Windows PowerShell
+$env:CAPSKIP_API_KEY = "your-key"
+$env:CAPSKIP_HOST = "127.0.0.1"
+$env:CAPSKIP_PORT = "8080"
+```
+
+```js
+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: parseInt(process.env.CAPSKIP_PORT || '8080', 10),
+});
+```
+
+---
+
+## Usage examples
+
+### Image captcha
+
+```js
+await solver.normal('captcha.png');
+await solver.normal('https://example.com/captcha.jpg');
+await solver.normal('data:image/png;base64,iVBORw0KGgo...');
+// result.code holds the recognized text
+```
+
+### reCAPTCHA v2 / v3
+
+```js
+// reCAPTCHA v2
+const v2 = await solver.recaptcha('...', 'https://example.com');
+
+// reCAPTCHA v3
+const v3 = await solver.recaptcha('...', 'https://example.com', {
+  version: 'v3',
+  action: 'submit',
+  score: 0.7,
+});
+```
+
+### Cloudflare Turnstile
+
+```js
+const result = await solver.turnstile('0x4AAAAAAA...', 'https://example.com');
+```
+
+### With a proxy (reCAPTCHA & Turnstile only)
+
+```js
+// Proxy is not supported for image captcha
+await solver.recaptcha('...', 'https://example.com', {
+  proxy: { type: 'HTTPS', uri: 'user:pass@1.2.3.4:3128' },
+});
+await solver.turnstile('...', 'https://example.com', {
+  proxy: { type: 'HTTP', uri: '1.2.3.4:3128' },
+});
+```
+
+### Parallel solving
+
+```js
+const { CapSkip } = require('capskip');
+
+async function main() {
+  const solver = new CapSkip();
+  const [r1, r2] = await Promise.all([
+    solver.recaptcha('...', 'https://a.com'),
+    solver.turnstile('...', 'https://b.com'),
+  ]);
+  console.log(r1.code, r2.code);
+}
+
+main();
+```
+
+> `AsyncCapSkip` is exported as an alias of `CapSkip` — Node I/O is asynchronous by nature, so every method already returns a Promise.
+
+More examples: [`examples/`](examples/)
+
+---
+
+## Return value
+
+Every solve method resolves to:
+
+```js
+{
+  captchaId: '12345',    // internal ID from CapSkip
+  code: 'TOKEN_OR_TEXT', // solution — text for image, token for reCAPTCHA/Turnstile
+  userAgent: '...',      // Turnstile only — use when submitting challenge-page tokens
+}
+```
+
+---
+
+## Error handling
+
+```js
+const {
+  CapSkip, ValidationException, NetworkException, ApiException, TimeoutException,
+} = require('capskip');
+
+try {
+  const result = await solver.recaptcha('...', '...');
+} catch (err) {
+  if (err instanceof ValidationException) {
+    // invalid parameters
+  } else if (err instanceof NetworkException) {
+    // CapSkip not running, or captcha not ready (manual polling)
+  } else if (err instanceof ApiException) {
+    // API returned an error code
+  } else if (err instanceof TimeoutException) {
+    // polling timeout exceeded
+  }
+}
+```
+
+---
+
+## TypeScript
+
+Type definitions ship with the package — no `@types` install required.
+
+```ts
+import { CapSkip, SolveResult } from 'capskip';
+
+const solver = new CapSkip({ host: '127.0.0.1', port: 8080 });
+const result: SolveResult = await solver.recaptcha('...', 'https://example.com');
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/capskip/capskip-node.git
+cd capskip-node
+npm install
+npm test
+```
+
+The test suite uses Node's built-in test runner — no extra dependencies. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow.
+
+---
+
+## 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)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 1.0.x | Yes |
+
+## Reporting a vulnerability
+
+If you discover a security vulnerability in the CapSkip Node.js SDK, please report it responsibly.
+
+**Do not** open a public GitHub issue for security vulnerabilities.
+
+Instead, email **support@capskip.com** with:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+We aim to acknowledge reports within 48 hours and provide a status update within 7 days.
+
+## Scope
+
+This policy covers the `capskip` npm package in this repository.
+
+The CapSkip desktop application itself is maintained separately — report app-level issues to CapSkip support.
+
+## Best practices for SDK users
+
+- Do not commit API keys or captcha tokens to version control
+- Use environment variables for `CAPSKIP_API_KEY`
+- CapSkip runs locally — ensure your firewall rules match your security requirements
+- When using proxies, avoid logging credentials in application logs

package/docs/API_REFERENCE.md

@@ -0,0 +1,292 @@
+# CapSkip API Reference
+
+Complete reference aligned with the [official CapSkip API](https://capskip.com/api-docs/).
+
+CapSkip exposes a standard captcha-solver HTTP API on your local machine:
+
+```
+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
+method returns a `Promise`.
+
+---
+
+## Supported captcha types
+
+| Type | SDK method | `method` (POST) |
+|---|---|---|
+| Image captcha | `normal()` | `post` or `base64` |
+| reCAPTCHA v2 | `recaptcha(sitekey, url)` | `userrecaptcha` |
+| reCAPTCHA v3 | `recaptcha(sitekey, url, { version: 'v3' })` | `userrecaptcha` + `version=v3` |
+| Cloudflare Turnstile | `turnstile()` | `turnstile` |
+
+**Proxy** is supported for reCAPTCHA and Turnstile only — not for image captcha.
+
+---
+
+## CapSkip
+
+```js
+const { CapSkip } = require('capskip');
+
+const solver = new CapSkip({
+  apiKey: 'capskip',
+  host: '127.0.0.1',
+  port: 8080,
+  defaultTimeout: 120,
+  recaptchaTimeout: 300,
+  pollingInterval: 5,       // max seconds between polls; starts at 0.25s and backs off to this
+});
+```
+
+`AsyncCapSkip` is exported as an alias of `CapSkip`.
+
+---
+
+## 1. Image captcha — `normal(file, { json })`
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `method` | string | Yes | `post` (multipart file) or `base64` |
+| `file` | file | Yes* | Image file when `method=post` |
+| `body` | string | Yes* | Base64 image when `method=base64` |
+| `json` | int | No | `0` plain text (default), `1` JSON |
+
+### GET `/res.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `action` | string | Yes | `get` |
+| `id` | int | Yes | Captcha ID from `in.php` |
+| `json` | int | No | `0` plain text (default), `1` JSON |
+
+### SDK usage
+
+```js
+await solver.normal('captcha.png');
+await solver.normal('https://example.com/captcha.jpg');
+const result = await solver.normal('data:image/png;base64,iVBORw0KGgo...', { json: 1 });
+console.log(result.code);
+```
+
+Only `json` is accepted as an extra parameter. Proxy is **not** supported.
+
+---
+
+## 2. reCAPTCHA v2 — `recaptcha(sitekey, url, { ... })`
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `key` | string | Yes | — | CapSkip API key |
+| `method` | string | Yes | — | `userrecaptcha` |
+| `googlekey` | string | Yes | — | Site key (`data-sitekey` / `k`) |
+| `pageurl` | string | Yes | — | Full page URL |
+| `enterprise` | int | No | `0` | `1` = Enterprise v2 |
+| `invisible` | int | No | `0` | `1` = Invisible reCAPTCHA |
+| `data-s` | string | No | — | Google Search / services `data-s` value |
+| `json` | int | No | `0` | `1` = JSON response |
+| `proxy` | string | No | — | `IP:PORT` or `login:pass@IP:PORT` |
+| `proxytype` | string | No | `HTTP` | `HTTP`, `HTTPS`, `SOCKS5`, `SOCKS5H` |
+
+Do **not** send `version`, `action`, or `min_score` for v2.
+
+### GET `/res.php`
+
+Same as image captcha poll parameters.
+
+### SDK usage
+
+```js
+// Standard v2
+await solver.recaptcha('...', 'https://example.com');
+
+// Invisible v2
+await solver.recaptcha('...', '...', { invisible: 1 });
+
+// Enterprise v2
+await solver.recaptcha('...', '...', { enterprise: 1 });
+
+// Enterprise v2 with data-s (SDK alias: datas)
+await solver.recaptcha('...', '...', { enterprise: 1, datas: '...' });
+
+// With proxy
+await solver.recaptcha('...', '...', {
+  proxy: { type: 'HTTPS', uri: 'user:pass@1.2.3.4:3128' },
+});
+```
+
+---
+
+## 3. reCAPTCHA v3 — `recaptcha(sitekey, url, { version: 'v3', ... })`
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `key` | string | Yes | — | CapSkip API key |
+| `method` | string | Yes | — | `userrecaptcha` |
+| `version` | string | Yes | — | `v3` |
+| `googlekey` | string | Yes | — | Site key |
+| `pageurl` | string | Yes | — | Full page URL |
+| `enterprise` | int | No | `0` | `1` = Enterprise v3 |
+| `action` | string | No | `verify` | Action from `grecaptcha.execute()` |
+| `min_score` | float | No | `0.4` | Minimum acceptable score |
+| `json` | int | No | `0` | `1` = JSON response |
+| `proxy` | string | No | — | Proxy address |
+| `proxytype` | string | No | `HTTP` | Proxy type |
+
+Do **not** send `invisible` for v3.
+
+### SDK usage
+
+```js
+await solver.recaptcha('...', 'https://example.com', {
+  version: 'v3',
+  action: 'submit',
+  min_score: 0.7,          // or SDK alias: score: 0.7
+  enterprise: 0,
+});
+```
+
+---
+
+## 4. Cloudflare Turnstile — `turnstile(sitekey, url, { ... })`
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `method` | string | Yes | `turnstile` |
+| `sitekey` | string | Yes | Turnstile sitekey |
+| `pageurl` | string | Yes | Full page URL |
+| `action` | string | No | From `data-action` or `turnstile.render()` |
+| `data` | string | No | `cData` / `data-cdata` |
+| `pagedata` | string | No | `chlPageData` (challenge pages) |
+| `json` | int | No | `0` plain text, `1` JSON |
+| `proxy` | string | No | Proxy address |
+| `proxytype` | string | No | Proxy type |
+
+### GET `/res.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `action` | string | Yes | `get` |
+| `id` | int | Yes | Captcha ID |
+| `json` | int | **Yes** | Must be `1` to receive User-Agent |
+
+The SDK **automatically** polls Turnstile results with `json=1` and includes `userAgent` in the result when CapSkip returns it.
+
+### SDK usage
+
+```js
+// Standalone widget
+const result = await solver.turnstile('0x4AAAAAAA...', 'https://example.com');
+console.log(result.code);
+console.log(result.userAgent); // present when CapSkip returns it
+
+// Challenge page
+const challenge = await solver.turnstile('0x4AAAAAAA...', 'https://example.com', {
+  action: 'managed',
+  data: 'cData_value',
+  pagedata: 'chlPageData_value',
+});
+// Use challenge.userAgent when submitting the token
+```
+
+---
+
+## Return value
+
+Every solve method resolves to:
+
+```js
+{
+  captchaId: '12345',
+  code: 'TOKEN_OR_TEXT',
+  userAgent: '...',   // Turnstile only, when json=1 poll includes it
+}
+```
+
+---
+
+## SDK parameter aliases
+
+Convenience aliases mapped before sending to CapSkip:
+
+| SDK alias | CapSkip API param |
+|---|---|
+| `url` | `pageurl` |
+| `score` | `min_score` |
+| `minScore` | `min_score` |
+| `datas` | `data-s` |
+| `data_s` | `data-s` |
+| `proxy` object | `proxy` + `proxytype` strings |
+
+```js
+const proxy = { type: 'HTTPS', uri: 'login:password@1.2.3.4:3128' };
+```
+
+Unsupported parameters (e.g. `numeric` on image captcha, `action` on v2) throw `ValidationException`.
+
+---
+
+## Manual workflow
+
+### `send(params)`
+
+Submit without polling. Resolves to the captcha ID string.
+
+```js
+const captchaId = await solver.send({
+  method: 'userrecaptcha',
+  googlekey: '...',
+  pageurl: 'https://example.com',
+});
+```
+
+### `getResult(id, json = 0)`
+
+Poll once. Rejects with `NetworkException` while `CAPCHA_NOT_READY`.
+
+```js
+const { NetworkException } = require('capskip');
+
+const code = await solver.getResult(captchaId);          // plain text
+const data = await solver.getResult(captchaId, 1);       // object when json=1
+```
+
+---
+
+## Low-level HTTP (ApiClient)
+
+```js
+const { ApiClient } = require('capskip');
+
+const client = new ApiClient({ host: '127.0.0.1', port: 8080 });
+await client.in_({ method: 'turnstile', key: 'capskip', sitekey: '...', pageurl: '...' });
+await client.res({ key: 'capskip', action: 'get', id: '12345', json: 1 });
+```
+
+---
+
+## Exceptions
+
+| Exception | When |
+|---|---|
+| `ValidationException` | Invalid/unsupported parameters |
+| `NetworkException` | Connection error, or captcha not ready |
+| `ApiException` | CapSkip API error response |
+| `TimeoutException` | Polling timeout exceeded |
+
+All extend `CapSkipError`, so `catch (err) { if (err instanceof CapSkipError) ... }` catches them all.