capskip 1.0.2

package/docs/GETTING_STARTED.md

@@ -0,0 +1,167 @@
+# Getting Started
+
+This guide walks you through installing CapSkip, installing the Node.js SDK, and running your first captcha solve.
+
+---
+
+## Prerequisites
+
+| Requirement | Details |
+|---|---|
+| **CapSkip app** | Windows desktop app from [capskip.com](https://capskip.com) |
+| **Node.js** | 18 or newer |
+| **Network** | SDK talks to CapSkip on `localhost` — no internet required for the API itself |
+
+---
+
+## Step 1 — Install and configure CapSkip
+
+1. Download CapSkip from [capskip.com](https://capskip.com).
+2. Install and launch the application.
+3. Open **Settings** and confirm:
+   - **Port** — default is `8080` (remember this value)
+   - **API key validation** — if enabled, copy your API key; if disabled, any string (e.g. `capskip`) is accepted
+
+CapSkip exposes a standard captcha-solver API:
+
+```
+POST http://127.0.0.1:<port>/in.php   → submit captcha, returns OK|<id>
+GET  http://127.0.0.1:<port>/res.php  → poll result, returns OK|<answer>
+```
+
+### Verify CapSkip is running
+
+**Windows (PowerShell):**
+
+```powershell
+Invoke-WebRequest "http://127.0.0.1:8080/res.php?key=capskip&action=get&id=0" -UseBasicParsing
+```
+
+You should get a response (even an error like `ERROR_WRONG_CAPTCHA_ID` confirms the server is up).
+
+**Linux / macOS:**
+
+```bash
+curl "http://127.0.0.1:8080/res.php?key=capskip&action=get&id=0"
+```
+
+---
+
+## Step 2 — Install the Node.js SDK
+
+### From npm (recommended)
+
+```bash
+npm install capskip
+```
+
+### From source (development)
+
+```bash
+git clone https://github.com/capskip/capskip-node.git
+cd capskip-node
+npm install
+```
+
+### Verify installation
+
+```bash
+node -e "console.log(require('capskip').version)"
+```
+
+Expected output: `1.0.2` (or your installed version).
+
+### Verify CapSkip connectivity
+
+```bash
+node examples/verify_connection.js
+```
+
+If CapSkip is running, you should see `Status: OK — CapSkip is reachable`.
+
+---
+
+## Step 3 — Your first script
+
+Create `solve_recaptcha.js`:
+
+```js
+const { CapSkip, NetworkException, TimeoutException } = 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),
+});
+
+const SITEKEY = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-'; // replace with your target page sitekey
+const PAGE_URL = 'https://example.com/login';                // replace with your target page URL
+
+(async () => {
+  try {
+    const result = await solver.recaptcha(SITEKEY, PAGE_URL);
+    console.log('Captcha ID:', result.captchaId);
+    console.log('Token:     ', result.code.slice(0, 80), '...');
+  } catch (err) {
+    if (err instanceof NetworkException) {
+      console.log('Cannot reach CapSkip — is the app running?', err.message);
+    } else if (err instanceof TimeoutException) {
+      console.log('Timed out:', err.message);
+    } else {
+      throw err;
+    }
+  }
+})();
+```
+
+Run it:
+
+```bash
+node solve_recaptcha.js
+```
+
+---
+
+## Step 4 — Run the bundled examples
+
+Clone the repository (if you haven't already) and run an example:
+
+```bash
+cd capskip-node
+node examples/recaptcha.js
+```
+
+| Example | What it demonstrates |
+|---|---|
+| `image_captcha.js` | Image captcha from file, URL, or base64 |
+| `recaptcha.js` | reCAPTCHA v2, v3, invisible, enterprise, proxy |
+| `turnstile.js` | Cloudflare Turnstile widget and challenge page |
+| `async_example.js` | Parallel solving |
+| `verify_connection.js` | Check CapSkip is running |
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `CAPSKIP_API_KEY` | `capskip` | API key sent with every request |
+| `CAPSKIP_HOST` | `127.0.0.1` | CapSkip host |
+| `CAPSKIP_PORT` | `8080` | CapSkip port |
+
+Example `.env` file (load with [dotenv](https://www.npmjs.com/package/dotenv) if you use it):
+
+```env
+CAPSKIP_API_KEY=capskip
+CAPSKIP_HOST=127.0.0.1
+CAPSKIP_PORT=8080
+```
+
+---
+
+## Next steps
+
+- [Tutorial](TUTORIAL.md) — complete walkthrough of every captcha type
+- [API Reference](API_REFERENCE.md) — all methods and parameters
+- [Troubleshooting](TROUBLESHOOTING.md) — fix common errors
+- [CapSkip API docs](https://capskip.com/api-docs/) — raw HTTP API reference

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,206 @@
+# Troubleshooting
+
+Common issues when using the CapSkip Node.js SDK and how to fix them.
+
+---
+
+## Connection refused / CapSkip not reachable
+
+**Symptom**
+
+```
+NetworkException: connect ECONNREFUSED 127.0.0.1:8080
+```
+
+**Cause:** CapSkip desktop app is not running, or the port is wrong.
+
+**Fix**
+
+1. Launch the CapSkip application.
+2. Confirm the API server is enabled in Settings.
+3. Match the port in your SDK config:
+
+```js
+const solver = new CapSkip({ host: '127.0.0.1', port: 8080 }); // use your actual port
+```
+
+4. Test with curl:
+
+```bash
+curl "http://127.0.0.1:8080/res.php?key=capskip&action=get&id=0"
+```
+
+---
+
+## TimeoutException — captcha not solved in time
+
+**Symptom**
+
+```
+TimeoutException: timeout 300 exceeded
+```
+
+**Cause:** CapSkip needs more time, or the captcha failed silently.
+
+**Fix**
+
+1. Increase the timeout:
+
+```js
+const solver = new CapSkip({ recaptchaTimeout: 600, defaultTimeout: 180 });
+```
+
+2. Increase poll interval slightly (CapSkip docs recommend ~5 s for reCAPTCHA):
+
+```js
+const solver = new CapSkip({ pollingInterval: 5 });
+```
+
+3. Check CapSkip app logs for solve errors on that captcha type.
+
+---
+
+## ApiException — ERROR_WRONG_USER_KEY
+
+**Symptom**
+
+```
+ApiException: ERROR_WRONG_USER_KEY
+```
+
+**Cause:** API key validation is enabled in CapSkip but the key is wrong.
+
+**Fix**
+
+1. Copy the exact API key from CapSkip Settings.
+2. Pass it to the SDK:
+
+```js
+const solver = new CapSkip({ apiKey: 'your-actual-key' });
+```
+
+Or disable API key validation in CapSkip Settings (development only).
+
+---
+
+## ApiException — ERROR_BAD_PARAMETERS
+
+**Symptom**
+
+```
+ApiException: ERROR_BAD_PARAMETERS
+```
+
+**Cause:** Missing or invalid API parameters.
+
+**Fix**
+
+- **reCAPTCHA:** ensure `sitekey` and `url` are correct.
+- **Turnstile challenge page:** include `data` and `pagedata` if required.
+- **Image captcha:** ensure the file exists or the base64 string is valid.
+
+---
+
+## ValidationException — File not found
+
+**Symptom**
+
+```
+ValidationException: File not found: captcha.png
+```
+
+**Fix**
+
+- Use an absolute path or verify the working directory.
+- For base64, pass a string with no file extension and length > 50, or use a data-URI:
+
+```js
+await solver.normal('data:image/png;base64,iVBORw0KGgo...');
+```
+
+---
+
+## reCAPTCHA token rejected by target site
+
+**Symptom:** SDK returns a token, but the website rejects it.
+
+**Possible causes & fixes**
+
+| Cause | Fix |
+|---|---|
+| Wrong `sitekey` or `pageurl` | Must match the exact page where the widget loads |
+| IP mismatch | Use the same proxy for solving and submitting the form |
+| Enterprise / invisible flag wrong | Set `enterprise: 1` or `invisible: 1` if the page uses them |
+| v3 action mismatch | Pass the correct `action` from `grecaptcha.execute()` |
+| Token expired | Use the token immediately after receiving it |
+
+**Proxy example (same IP for solve and submit):**
+
+```js
+const proxy = { type: 'HTTP', uri: '1.2.3.4:3128' };
+const result = await solver.recaptcha('...', '...', { proxy });
+// submit form using the same proxy
+```
+
+---
+
+## Turnstile challenge page — token works but page still blocks
+
+**Symptom:** Token received but Cloudflare still challenges.
+
+**Fix:** For challenge pages, CapSkip returns a User-Agent that must be used when submitting the token. The SDK returns it as `result.userAgent` — set it as the `User-Agent` header when you submit the `cf-turnstile-response` token.
+
+---
+
+## NetworkException during manual polling
+
+**Symptom:** `getResult()` keeps rejecting with `NetworkException`.
+
+**This is expected** while the captcha is still processing. Catch it and retry:
+
+```js
+const { NetworkException } = require('capskip');
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+let code;
+while (true) {
+  try {
+    code = await solver.getResult(captchaId);
+    break;
+  } catch (err) {
+    if (!(err instanceof NetworkException)) throw err;
+    await sleep(5000);
+  }
+}
+```
+
+---
+
+## Import errors after install
+
+```bash
+npm install capskip@latest
+node -e "console.log(require('capskip').version)"
+```
+
+Make sure you are on Node.js 18 or newer:
+
+```bash
+node --version
+```
+
+---
+
+## Still stuck?
+
+1. [CapSkip API docs](https://capskip.com/api-docs/)
+2. [GitHub Issues](https://github.com/capskip/capskip-node/issues)
+3. CapSkip support: support@capskip.com
+
+When opening an issue, include:
+
+- Node.js version (`node --version`)
+- SDK version (`node -e "console.log(require('capskip').version)"`)
+- CapSkip port and captcha type
+- Full error / stack trace (redact sitekeys/tokens)