capskip 1.0.2

package/src/apiClient.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const fs = require('fs/promises');
+const path = require('path');
+
+const { ApiException, NetworkException } = require('./exceptions');
+const { postForm, postMultipart, get } = require('./http');
+
+/** Low-level HTTP client for the CapSkip in.php / res.php endpoints. */
+class ApiClient {
+  constructor({ host = '127.0.0.1', port = 8080 } = {}) {
+    this.host = host;
+    this.port = port;
+  }
+
+  get baseUrl() {
+    return `http://${this.host}:${this.port}`;
+  }
+
+  /**
+   * Submit a captcha to `in.php`.
+   *
+   * @param {object} options Form fields for the request. A `files` map
+   *   (`{ field: path }`) or a single `file` path triggers a multipart upload;
+   *   otherwise the fields are sent url-encoded.
+   * @returns {Promise<string>} The raw `in.php` response text.
+   */
+  async in_(options = {}) {
+    const { files = {}, ...fields } = options;
+    const url = `${this.baseUrl}/in.php`;
+
+    // File reads happen before the request so a missing file surfaces as a
+    // filesystem error rather than being masked as a NetworkException.
+    let requestPromise;
+    if (Object.keys(files).length > 0) {
+      const parts = [];
+      for (const [name, filePath] of Object.entries(files)) {
+        parts.push({ name, filename: path.basename(filePath), content: await fs.readFile(filePath) });
+      }
+      requestPromise = () => postMultipart(url, fields, parts);
+    } else if (Object.prototype.hasOwnProperty.call(fields, 'file')) {
+      const filePath = fields.file;
+      delete fields.file;
+      const content = await fs.readFile(filePath);
+      requestPromise = () => postMultipart(url, fields, [
+        { name: 'file', filename: path.basename(filePath), content },
+      ]);
+    } else {
+      requestPromise = () => postForm(url, fields);
+    }
+
+    let resp;
+    try {
+      resp = await requestPromise();
+    } catch (err) {
+      throw new NetworkException(err);
+    }
+
+    if (resp.statusCode !== 200) {
+      throw new NetworkException(`bad response: ${resp.statusCode}`);
+    }
+
+    const text = resp.body.toString('utf-8');
+    if (text.includes('ERROR')) {
+      throw new ApiException(text);
+    }
+    return text;
+  }
+
+  /**
+   * Poll a result from `res.php`.
+   *
+   * @param {object} params Query parameters (`key`, `action`, `id`, `json`).
+   * @returns {Promise<string>} The raw `res.php` response text.
+   */
+  async res(params = {}) {
+    let resp;
+    try {
+      resp = await get(`${this.baseUrl}/res.php`, params);
+    } catch (err) {
+      throw new NetworkException(err);
+    }
+
+    if (resp.statusCode !== 200) {
+      throw new NetworkException(`bad response: ${resp.statusCode}`);
+    }
+
+    const text = resp.body.toString('utf-8');
+    if (text.includes('ERROR')) {
+      throw new ApiException(text);
+    }
+    return text;
+  }
+}
+
+module.exports = { ApiClient };

package/src/apiParams.js

@@ -0,0 +1,175 @@
+'use strict';
+
+// CapSkip API parameter validation (https://capskip.com/api-docs/).
+
+const { ValidationException } = require('./exceptions');
+
+const NORMAL_SUBMIT = new Set(['method', 'body', 'json', 'file']);
+
+const RECAPTCHA_V2_SUBMIT = new Set([
+  'method', 'googlekey', 'pageurl', 'enterprise', 'invisible', 'data-s', 'json',
+  'proxy', 'proxytype',
+]);
+
+const RECAPTCHA_V3_SUBMIT = new Set([
+  'method', 'version', 'googlekey', 'pageurl', 'enterprise', 'action', 'min_score',
+  'json', 'proxy', 'proxytype',
+]);
+
+const TURNSTILE_SUBMIT = new Set([
+  'method', 'sitekey', 'pageurl', 'action', 'data', 'pagedata', 'json',
+  'proxy', 'proxytype',
+]);
+
+const PARAM_ALIASES = {
+  url: 'pageurl',
+  score: 'min_score',
+  minScore: 'min_score',
+  datas: 'data-s',
+  data_s: 'data-s',
+};
+
+function has(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+/** Format a list the way Python's `sorted(...)` repr does, for message parity. */
+function reprList(values) {
+  return `[${values.map((value) => `'${value}'`).join(', ')}]`;
+}
+
+function applyParamAliases(params) {
+  const out = { ...params };
+  for (const [alias, apiName] of Object.entries(PARAM_ALIASES)) {
+    if (has(out, alias)) {
+      if (has(out, apiName) && out[alias] !== out[apiName]) {
+        throw new ValidationException(`Conflicting parameters: '${alias}' and '${apiName}'`);
+      }
+      out[apiName] = out[alias];
+      delete out[alias];
+    }
+  }
+  return out;
+}
+
+function isEmptyProxy(proxy) {
+  if (proxy === null || proxy === undefined || proxy === '' || proxy === false || proxy === 0) {
+    return true;
+  }
+  if (typeof proxy === 'object' && !Array.isArray(proxy) && Object.keys(proxy).length === 0) {
+    return true;
+  }
+  return false;
+}
+
+function applyProxy(params) {
+  const out = { ...params };
+  const proxy = out.proxy;
+  delete out.proxy;
+
+  if (isEmptyProxy(proxy)) {
+    return out;
+  }
+
+  if (typeof proxy === 'object' && !Array.isArray(proxy)) {
+    if (!has(proxy, 'uri') || !has(proxy, 'type')) {
+      throw new ValidationException("proxy dict must contain 'type' and 'uri' keys");
+    }
+    out.proxy = proxy.uri;
+    out.proxytype = proxy.type;
+  } else {
+    out.proxy = proxy;
+    if (!has(out, 'proxytype')) {
+      out.proxytype = 'HTTP';
+    }
+  }
+  return out;
+}
+
+function unknownKeys(params, allowed) {
+  const excluded = new Set([...allowed, 'key', 'file', 'files']);
+  return Object.keys(params).filter((key) => !excluded.has(key)).sort();
+}
+
+function validateNormalSubmit(params) {
+  const unknown = unknownKeys(params, NORMAL_SUBMIT);
+  if (unknown.length > 0) {
+    throw new ValidationException(
+      `Unsupported parameters for image captcha: ${reprList(unknown)}. `
+      + 'CapSkip only supports: method, file/body, json.',
+    );
+  }
+  if (has(params, 'proxy') || has(params, 'proxytype')) {
+    throw new ValidationException(
+      'Proxy is not supported for image captcha. '
+      + 'Use proxy only with reCAPTCHA or Turnstile.',
+    );
+  }
+}
+
+function validateRecaptchaSubmit(params, version) {
+  const normalized = String(version || 'v2').toLowerCase();
+  let allowed;
+
+  if (normalized === 'v3') {
+    allowed = RECAPTCHA_V3_SUBMIT;
+    if (params.invisible) {
+      throw new ValidationException('invisible is only supported for reCAPTCHA v2.');
+    }
+  } else {
+    allowed = RECAPTCHA_V2_SUBMIT;
+    if (params.version === 'v3') {
+      throw new ValidationException("Use version='v3' for reCAPTCHA v3.");
+    }
+    for (const key of ['action', 'min_score']) {
+      if (has(params, key)) {
+        throw new ValidationException(`'${key}' is only supported for reCAPTCHA v3.`);
+      }
+    }
+  }
+
+  const unknown = unknownKeys(params, allowed);
+  if (unknown.length > 0) {
+    throw new ValidationException(
+      `Unsupported parameters for reCAPTCHA ${normalized}: ${reprList(unknown)}.`,
+    );
+  }
+}
+
+function validateTurnstileSubmit(params) {
+  const unknown = unknownKeys(params, TURNSTILE_SUBMIT);
+  if (unknown.length > 0) {
+    throw new ValidationException(
+      `Unsupported parameters for Turnstile: ${reprList(unknown)}.`,
+    );
+  }
+}
+
+function prepareSubmitParams(params, captchaType, version = 'v2') {
+  let prepared = applyParamAliases(params);
+  prepared = applyProxy(prepared);
+
+  if (captchaType === 'normal') {
+    validateNormalSubmit(prepared);
+  } else if (captchaType === 'recaptcha') {
+    validateRecaptchaSubmit(prepared, version);
+  } else if (captchaType === 'turnstile') {
+    validateTurnstileSubmit(prepared);
+  }
+
+  return prepared;
+}
+
+module.exports = {
+  NORMAL_SUBMIT,
+  RECAPTCHA_V2_SUBMIT,
+  RECAPTCHA_V3_SUBMIT,
+  TURNSTILE_SUBMIT,
+  PARAM_ALIASES,
+  applyParamAliases,
+  applyProxy,
+  validateNormalSubmit,
+  validateRecaptchaSubmit,
+  validateTurnstileSubmit,
+  prepareSubmitParams,
+};

package/src/exceptions.js

@@ -0,0 +1,37 @@
+'use strict';
+
+/** Base error for all CapSkip SDK failures. */
+class CapSkipError extends Error {
+  constructor(message) {
+    if (message instanceof Error) {
+      super(message.message, { cause: message });
+    } else {
+      super(message);
+    }
+    this.name = this.constructor.name;
+  }
+}
+
+/** Alias kept for API parity with the CapSkip clients (`solver.exceptions`). */
+const SolverExceptions = CapSkipError;
+
+/** Invalid or unsupported parameters. */
+class ValidationException extends CapSkipError {}
+
+/** Connection failure or captcha not ready. */
+class NetworkException extends CapSkipError {}
+
+/** CapSkip API returned an error. */
+class ApiException extends CapSkipError {}
+
+/** Polling exceeded the configured timeout. */
+class TimeoutException extends CapSkipError {}
+
+module.exports = {
+  CapSkipError,
+  SolverExceptions,
+  ValidationException,
+  NetworkException,
+  ApiException,
+  TimeoutException,
+};

package/src/http.js

@@ -0,0 +1,158 @@
+'use strict';
+
+const http = require('http');
+const https = require('https');
+const crypto = require('crypto');
+const { URL } = require('url');
+
+// Zero-dependency HTTP layer built on Node's core http/https modules. CapSkip
+// only ever talks to a local endpoint (in.php / res.php) plus the occasional
+// image download, so a small request helper is all the SDK needs.
+
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+function stringifyValue(value) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+  return String(value);
+}
+
+/** Encode an object as an application/x-www-form-urlencoded body / query string. */
+function encodeParams(params) {
+  return Object.entries(params)
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(stringifyValue(value))}`)
+    .join('&');
+}
+
+/** Build a `?a=b&c=d` query string (empty string when there are no params). */
+function buildQuery(params) {
+  const query = encodeParams(params);
+  return query ? `?${query}` : '';
+}
+
+/** Encode form fields plus file parts as a multipart/form-data body. */
+function encodeMultipart(fields, files) {
+  const boundary = `----CapSkipFormBoundary${crypto.randomBytes(16).toString('hex')}`;
+  const parts = [];
+
+  for (const [name, value] of Object.entries(fields)) {
+    parts.push(Buffer.from(
+      `--${boundary}\r\n`
+      + `Content-Disposition: form-data; name="${name}"\r\n\r\n`
+      + `${stringifyValue(value)}\r\n`,
+      'utf-8',
+    ));
+  }
+
+  for (const file of files) {
+    const contentType = file.contentType || 'application/octet-stream';
+    parts.push(Buffer.from(
+      `--${boundary}\r\n`
+      + `Content-Disposition: form-data; name="${file.name}"; filename="${file.filename}"\r\n`
+      + `Content-Type: ${contentType}\r\n\r\n`,
+      'utf-8',
+    ));
+    parts.push(file.content);
+    parts.push(Buffer.from('\r\n', 'utf-8'));
+  }
+
+  parts.push(Buffer.from(`--${boundary}--\r\n`, 'utf-8'));
+
+  return {
+    body: Buffer.concat(parts),
+    contentType: `multipart/form-data; boundary=${boundary}`,
+  };
+}
+
+/**
+ * Perform a single HTTP request, following redirects for safe methods.
+ * Resolves with `{ statusCode, headers, body }` where `body` is a Buffer.
+ */
+function request(method, urlString, { headers = {}, body = null, maxRedirects = 5 } = {}) {
+  return new Promise((resolve, reject) => {
+    let url;
+    try {
+      url = new URL(urlString);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+
+    const lib = url.protocol === 'https:' ? https : http;
+    const options = {
+      method,
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'https:' ? 443 : 80),
+      path: `${url.pathname}${url.search}`,
+      headers,
+    };
+
+    const req = lib.request(options, (res) => {
+      if (REDIRECT_STATUSES.has(res.statusCode) && res.headers.location && maxRedirects > 0) {
+        res.resume();
+        const nextUrl = new URL(res.headers.location, url).toString();
+        const nextMethod = res.statusCode === 303 ? 'GET' : method;
+        request(nextMethod, nextUrl, {
+          headers,
+          body: nextMethod === 'GET' ? null : body,
+          maxRedirects: maxRedirects - 1,
+        }).then(resolve, reject);
+        return;
+      }
+
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => resolve({
+        statusCode: res.statusCode,
+        headers: res.headers,
+        body: Buffer.concat(chunks),
+      }));
+    });
+
+    req.on('error', reject);
+    if (body !== null && body !== undefined) {
+      req.write(body);
+    }
+    req.end();
+  });
+}
+
+/** POST an application/x-www-form-urlencoded body. */
+function postForm(url, fields) {
+  const body = encodeParams(fields);
+  return request('POST', url, {
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      'Content-Length': Buffer.byteLength(body),
+    },
+    body,
+  });
+}
+
+/** POST a multipart/form-data body carrying one or more file parts. */
+function postMultipart(url, fields, files) {
+  const { body, contentType } = encodeMultipart(fields, files);
+  return request('POST', url, {
+    headers: {
+      'Content-Type': contentType,
+      'Content-Length': body.length,
+    },
+    body,
+  });
+}
+
+/** GET with an object of query parameters. */
+function get(url, params = {}) {
+  return request('GET', `${url}${buildQuery(params)}`);
+}
+
+module.exports = {
+  request,
+  postForm,
+  postMultipart,
+  get,
+  encodeParams,
+  buildQuery,
+  encodeMultipart,
+};

package/src/index.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// CapSkip Node.js SDK — local captcha solver client.
+
+const { CapSkip } = require('./solver');
+const { ApiClient } = require('./apiClient');
+const {
+  CapSkipError,
+  SolverExceptions,
+  ValidationException,
+  NetworkException,
+  ApiException,
+  TimeoutException,
+} = require('./exceptions');
+
+// Node I/O is asynchronous by nature, so every CapSkip method already returns a
+// Promise. `AsyncCapSkip` / `AsyncApiClient` are exported as aliases so code
+// ported from other CapSkip SDKs keeps working unchanged.
+module.exports = {
+  CapSkip,
+  AsyncCapSkip: CapSkip,
+  ApiClient,
+  AsyncApiClient: ApiClient,
+  CapSkipError,
+  SolverExceptions,
+  ValidationException,
+  NetworkException,
+  ApiException,
+  TimeoutException,
+  version: '1.0.2',
+};