sursolver 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e9167fab5ec1966f59855dabc0f071df537b946799aab078770d3a227fbdfe8a
+  data.tar.gz: b10715a8428c6a058dd69c8eae1a35f9e5a3d9d24e77511631126ef0424e4263
+SHA512:
+  metadata.gz: 0c4c3d1f52248e8b32a1eaaaaafd45f5e53ed7f7ca12638ca4b882515601c78fddc9a591c6f0a11aa64973067cd84626413b4fb666425bf9f6c930912cbf6a7a
+  data.tar.gz: a844fbc99266c28f58733257353c3a99017367a6e709618ba5b12c5d1c7df992faee9622191d752b724803cb73d6ec5533cf168553e2b391596426e72dba2a52

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 — unreleased
+
+First release. Tested against the SDK specification revision in `SPEC_VERSION` (catalog of
+2026-11-04).
+
+- `SurSolver::Client` with `create_task`, `get_task_result`, `get_balance`, `list_task_types`,
+  `list_services` and `solve` (3 s polling, 210 s deadline, `on_task_created:`).
+- Typed errors: `AuthenticationError`, `InvalidTaskError` (with `supported_user_agents`),
+  `InsufficientBalanceError`, `NoSlotAvailableError`, `TaskNotFoundError`, `TaskFailedError`,
+  `ApiError`, `TransportError` (with `may_have_created_task?`), `ProtocolError`,
+  `SolveTimeoutError`, `ConfigurationError`, all under `SurSolver::Error`.
+- `SurSolver::TaskTypes` and `SurSolver::ErrorCodes` constants generated from the public catalog.
+- Standard library only (`net/http`, `json`).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SurSolver
+
+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.

data/README.md

@@ -0,0 +1,186 @@
+# SurSolver for Ruby — captcha solver API client
+
+Solve **reCAPTCHA v3**, **Cloudflare Turnstile**, **Cloudflare Challenge**, **GeeTest**,
+**DataDome**, **AWS WAF**, **Akamai**, **Kasada** and image captchas from Ruby with the official
+[SurSolver](https://sursolver.com) gem. One call submits the captcha and returns the token or
+cookie. Ruby 3.4+, standard library only.
+
+```powershell
+gem install sursolver
+```
+
+## Quick start
+
+```ruby
+require "sursolver"
+
+API_KEY = "YOUR_API_KEY"
+USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
+
+client = SurSolver::Client.new(API_KEY)
+result = client.solve(
+  "type" => SurSolver::TaskTypes::TURNSTILE_TOKEN_PROXY_LESS,
+  "websiteURL" => "https://example.com/login",
+  "websiteKey" => "0x4AAAAAAA...",
+  "userAgent" => USER_AGENT
+)
+puts result.solution["token"]
+```
+
+Send the same `userAgent` with the request that uses the result. Tokens and cookies are
+single-use, so use them right away. The examples below reuse `client` and `USER_AGENT`.
+
+## Examples
+
+### Solve reCAPTCHA v3 in Ruby
+
+```ruby
+result = client.solve(
+  "type" => SurSolver::TaskTypes::RE_CAPTCHA_V3_TOKEN_PROXY_LESS,
+  "websiteURL" => "https://example.com/login",
+  "websiteKey" => "6Le-wvkS...",
+  "pageAction" => "login",
+  "userAgent" => USER_AGENT
+)
+puts result.solution["gRecaptchaResponse"]
+```
+
+For reCAPTCHA v3 Enterprise use `SurSolver::TaskTypes::RE_CAPTCHA_V3_ENTERPRISE_TOKEN_PROXY_LESS`.
+
+### Solve Cloudflare Turnstile
+
+```ruby
+result = client.solve(
+  "type" => SurSolver::TaskTypes::TURNSTILE_TOKEN_PROXY_LESS,
+  "websiteURL" => "https://example.com/signup",
+  "websiteKey" => "0x4AAAAAAA...",
+  "userAgent" => USER_AGENT
+)
+# Submit the token as the cf-turnstile-response form field.
+puts result.solution["token"]
+```
+
+### Bypass the Cloudflare Challenge page (cf_clearance)
+
+```ruby
+result = client.solve(
+  "type" => SurSolver::TaskTypes::CLOUDFLARE_CHALLENGE_COOKIE,
+  "websiteURL" => "https://example.com/protected",
+  "proxy" => "http://user:password@203.0.113.10:8000",
+  "userAgent" => USER_AGENT
+)
+puts result.solution["cf_clearance"]
+```
+
+Replay the cookie through the same proxy and with the same `userAgent`.
+
+### Solve GeeTest v4
+
+```ruby
+result = client.solve(
+  "type" => SurSolver::TaskTypes::GEE_TEST_TOKEN_PROXY_LESS,
+  "websiteURL" => "https://example.com/login",
+  "captchaId" => "e392e1d7fd421dc63325744d5a2b9c73",
+  "userAgent" => USER_AGENT
+)
+puts result.solution["lot_number"], result.solution["pass_token"]
+```
+
+GeeTest v3: send `gt` and a fresh `challenge` instead of `captchaId`.
+
+### Solve the DataDome slider
+
+```ruby
+result = client.solve(
+  "type" => SurSolver::TaskTypes::DATA_DOME_SLIDER_COOKIE,
+  "websiteURL" => "https://example.com/",
+  "captchaUrl" => "https://geo.captcha-delivery.com/captcha/?initialCid=...",
+  "proxy" => "http://user:password@203.0.113.10:8000",
+  "userAgent" => USER_AGENT
+)
+puts result.solution["datadome"]
+```
+
+### Get an AWS WAF token (silent challenge)
+
+```ruby
+result = client.solve(
+  "type" => SurSolver::TaskTypes::AWS_CHALLENGE_COOKIE,
+  "websiteURL" => "https://example.com/",
+  "scriptUrl" => "https://example.token.awswaf.com/example/challenge.js",
+  "userAgent" => USER_AGENT
+)
+puts result.solution["aws-waf-token"]
+```
+
+The visual AWS WAF CAPTCHA is `SurSolver::TaskTypes::AWS_CAPTCHA_COOKIE` and needs your proxy.
+
+### Solve an image captcha (image to text)
+
+```ruby
+require "base64"
+
+result = client.solve(
+  "type" => SurSolver::TaskTypes::IMAGE_TO_TEXT_TASK,
+  "module" => "1",
+  "body" => Base64.strict_encode64(File.binread("captcha.png"))
+)
+puts result.solution["answer"]
+```
+
+## Supported captchas
+
+| Captcha | `task.type` | Guide |
+|---|---|---|
+| reCAPTCHA v3 | `ReCaptchaV3TokenProxyLess` | [recaptcha-v3](https://sursolver.com/solvers/recaptcha-v3) |
+| reCAPTCHA v3 Enterprise | `ReCaptchaV3EnterpriseTokenProxyLess` | [recaptcha-v3-enterprise](https://sursolver.com/solvers/recaptcha-v3-enterprise) |
+| Cloudflare Turnstile | `TurnstileTokenProxyLess` | [turnstile](https://sursolver.com/solvers/turnstile) |
+| Cloudflare Challenge | `CloudflareChallengeCookie` | [cloudflare-challenge](https://sursolver.com/solvers/cloudflare-challenge) |
+| GeeTest v3 / v4 | `GeeTestTokenProxyLess` | [geetest](https://sursolver.com/solvers/geetest) |
+| DataDome | `DataDomeSliderCookie` | [datadome](https://sursolver.com/solvers/datadome) |
+| AWS WAF Challenge | `AwsChallengeCookie` | [aws-challenge](https://sursolver.com/solvers/aws-challenge) |
+| AWS WAF CAPTCHA | `AwsCaptchaCookie` | [aws-captcha](https://sursolver.com/solvers/aws-captcha) |
+| Akamai (`_abck`) | `AkamaiCookieProxyLess` | [akamai](https://sursolver.com/solvers/akamai) |
+| Akamai SBSD | `AkamaiSbsdCookie` | [akamai-sbsd](https://sursolver.com/solvers/akamai-sbsd) |
+| Akamai BMP (Android) | `AkamaiBmpTask` | [akamai-bmp](https://sursolver.com/solvers/akamai-bmp) |
+| Kasada | `KasadaTokenProxyLess` | [kasada](https://sursolver.com/solvers/kasada) |
+| Shape | `ShapeCookieProxyLess` | [shape](https://sursolver.com/solvers/shape) |
+| Imperva (reese84 / utmvc) | `ImpervaCookie`, `ImpervaUtmvcCookie` | [imperva](https://sursolver.com/solvers/imperva) |
+| Vercel Security Checkpoint | `VercelCookie` | [vercel](https://sursolver.com/solvers/vercel) |
+| FriendlyCaptcha | `FriendlyCaptchaTokenProxyLess` | [friendlycaptcha](https://sursolver.com/solvers/friendlycaptcha) |
+| MTCaptcha | `MtCaptchaTokenProxyLess` | [mtcaptcha](https://sursolver.com/solvers/mtcaptcha) |
+| Prosopo | `ProsopoTokenProxyLess` | [prosopo](https://sursolver.com/solvers/prosopo) |
+| CaptchaFox | `CaptchaFoxToken` | [captchafox](https://sursolver.com/solvers/captchafox) |
+| Altcha | `AltchaTokenProxyLess` | [altcha](https://sursolver.com/solvers/altcha) |
+| Lemin | `LeminTokenProxyLess` | [lemin](https://sursolver.com/solvers/lemin) |
+| Castle (Android) | `CastleAndroidToken` | [castle-android](https://sursolver.com/solvers/castle-android) |
+| Image to Text | `ImageToTextTask` | [image-to-text](https://sursolver.com/solvers/image-to-text) |
+
+Each guide lists the fields to send and where to find them on the page. The live list is
+`client.list_task_types`; prices are `client.list_services`.
+
+## Errors
+
+```ruby
+begin
+  result = client.solve(task)
+rescue SurSolver::NoSlotAvailableError
+  # all your threads are busy: try again in a moment
+rescue SurSolver::TaskFailedError
+  # this captcha could not be solved; its charge is refunded
+end
+```
+
+Other errors: `SurSolver::AuthenticationError` (wrong API key), `SurSolver::InvalidTaskError` (a
+field is missing or wrong), `SurSolver::InsufficientBalanceError` (top up),
+`SurSolver::SolveTimeoutError` (no result in time). All inherit from `SurSolver::Error`.
+
+## Links
+
+- [Documentation](https://sursolver.com/docs) and [API reference](https://sursolver.com/docs/api)
+- [Proxies guide](https://sursolver.com/docs/guides/proxies) and [error codes](https://sursolver.com/docs/guides/errors)
+- [Pricing](https://sursolver.com/pricing)
+
+## License
+
+MIT

data/lib/sursolver/client.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "timeout"
+require "uri"
+
+module SurSolver
+  # Client of the SurSolver captcha-solving API. Durations are in seconds.
+  #
+  # The API key travels only in request bodies and never appears in errors or #inspect.
+  class Client
+    DEFAULT_BASE_URL = "https://api.sursolver.com"
+    DEFAULT_REQUEST_TIMEOUT = 30
+    DEFAULT_POLL_INTERVAL = 3
+    DEFAULT_SOLVE_TIMEOUT = 210
+    DEFAULT_MAX_SUBMIT_RETRIES = 1
+    # Upper bound of the random delay added to a submit retry, in seconds.
+    SUBMIT_RETRY_JITTER = 1
+
+    LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+    NO_RESPONSE_ERRORS = [IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError, Net::ProtocolError].freeze
+    private_constant :LOOPBACK_HOSTS, :NO_RESPONSE_ERRORS
+
+    # Builds a client; raises ConfigurationError for an unusable option (nothing is sent).
+    #
+    # transport: object with #call(Request) -> Response (default NetHttpTransport).
+    # clock: object with #now and #sleep(seconds) (tests). random: callable returning [0, 1).
+    def initialize(api_key, base_url: DEFAULT_BASE_URL, request_timeout: DEFAULT_REQUEST_TIMEOUT,
+                   poll_interval: DEFAULT_POLL_INTERVAL, solve_timeout: DEFAULT_SOLVE_TIMEOUT,
+                   max_submit_retries: DEFAULT_MAX_SUBMIT_RETRIES, app_id: nil, user_agent_suffix: nil,
+                   transport: nil, clock: nil, random: nil)
+      raise ConfigurationError, "api_key must be a non-empty string" if !api_key.is_a?(String) || api_key.strip.empty?
+      raise ConfigurationError, "api_key has leading or trailing whitespace" if api_key.strip != api_key
+
+      @base_url = normalize_base_url(base_url)
+      { request_timeout: request_timeout, poll_interval: poll_interval, solve_timeout: solve_timeout }.each do |name, value|
+        require_positive(name, value)
+      end
+      unless max_submit_retries.is_a?(Integer) && max_submit_retries >= 0
+        raise ConfigurationError, "max_submit_retries must be a non-negative integer"
+      end
+
+      @user_agent = "sursolver-ruby/#{VERSION}"
+      unless user_agent_suffix.nil?
+        unless user_agent_suffix.is_a?(String) && user_agent_suffix.match?(/\A[\x20-\x7e]+\z/)
+          raise ConfigurationError, "user_agent_suffix must be non-empty printable ASCII"
+        end
+
+        @user_agent += " #{user_agent_suffix}"
+      end
+      @api_key = api_key
+      @request_timeout = request_timeout
+      @poll_interval = poll_interval
+      @solve_timeout = solve_timeout
+      @max_submit_retries = max_submit_retries
+      @app_id = app_id&.strip
+      @app_id = nil if @app_id&.empty?
+      @transport = transport || NetHttpTransport.new
+      @clock = clock || SystemClock.new
+      @random = random || -> { Random.rand }
+    end
+
+    # Never reveals the API key.
+    def inspect
+      "#<SurSolver::Client base_url=#{@base_url}>"
+    end
+    alias to_s inspect
+
+    # Submits a task and returns its id. The task is charged from this point. It is never retried:
+    # after a TransportError the task may exist (check get_balance before submitting again).
+    #
+    # task: Hash with "type" plus that type's fields, sent verbatim. Browser types require "userAgent".
+    def create_task(task)
+      payload = { "clientKey" => @api_key, "task" => task }
+      payload["appId"] = @app_id if @app_id
+      body = solver_call("createTask", "/createTask", payload)
+      task_id = body["taskId"]
+      raise ProtocolError.new("createTask", "errorId 0 without a taskId") unless task_id.is_a?(String) && !task_id.empty?
+
+      task_id
+    end
+
+    # Reads a task's state once. A terminal failure raises TaskFailedError.
+    def get_task_result(task_id)
+      body = solver_call("getTaskResult", "/getTaskResult", { "clientKey" => @api_key, "taskId" => task_id }, task_id)
+      case body["status"]
+      when "processing" then TaskResult.new(status: "processing", solution: nil)
+      when "ready"
+        solution = body["solution"]
+        raise ProtocolError.new("getTaskResult", "status ready without a solution object") unless solution.is_a?(Hash)
+
+        TaskResult.new(status: "ready", solution: solution)
+      else
+        raise ProtocolError.new("getTaskResult", "unknown status #{JSON.generate(body["status"])}")
+      end
+    end
+
+    # The cash balance in USD as the JSON number the API sends. Display it; do not do money
+    # arithmetic on it (the dashboard's GET /v1/balance has the exact decimal).
+    def get_balance # rubocop:disable Naming/AccessorMethodName
+      balance = solver_call("getBalance", "/getBalance", { "clientKey" => @api_key })["balance"]
+      raise ProtocolError.new("getBalance", "errorId 0 without a numeric balance") unless balance.is_a?(Numeric) && balance.finite?
+
+      balance.to_f
+    end
+
+    # Creates a task and polls it until it is ready, failed, or the deadline passes.
+    #
+    # createTask is resubmitted only after ERROR_NO_SLOT_AVAILABLE (nothing was created), at most
+    # max_submit_retries times; any other submit failure is raised at once. Polls that fail with a
+    # TransportError or ERROR_INTERNAL_ERROR are retried until the deadline; any other error ends the
+    # call and carries the task id. On the deadline SolveTimeoutError is raised; the task may still
+    # finish. on_task_created is called once with the task id as soon as the task is accepted.
+    def solve(task, poll_interval: nil, solve_timeout: nil, on_task_created: nil)
+      interval = poll_interval || @poll_interval
+      timeout = solve_timeout || @solve_timeout
+      require_positive(:poll_interval, interval)
+      require_positive(:solve_timeout, timeout)
+      deadline = @clock.now + timeout
+
+      retries = 0
+      begin
+        task_id = create_task(task)
+      rescue NoSlotAvailableError
+        raise if retries >= @max_submit_retries
+
+        retries += 1
+        jitter_ms = (@random.call * SUBMIT_RETRY_JITTER * 1000).floor
+        @clock.sleep(interval + (jitter_ms / 1000.0))
+        retry
+      end
+      on_task_created&.call(task_id)
+
+      loop do
+        last_error = nil
+        begin
+          result = get_task_result(task_id)
+          return SolveResult.new(task_id: task_id, solution: result.solution) if result.ready?
+        rescue TransportError => e
+          last_error = e
+        rescue ApiError => e
+          raise unless e.code == ErrorCodes::ERROR_INTERNAL_ERROR
+
+          last_error = e
+        end
+        @clock.sleep(interval)
+        raise SolveTimeoutError.new(task_id, timeout, last_error) if @clock.now >= deadline
+      end
+    end
+
+    # The public task-type catalog: accepted names, fields, proxy modes and result keys.
+    def list_task_types
+      data = catalog_call("listTaskTypes", "/v1/task-types")
+      task_types = data["task_types"]
+      error_codes = data["error_codes"]
+      unless task_types.is_a?(Array) && error_codes.is_a?(Array)
+        raise ProtocolError.new("listTaskTypes", "data without task_types and error_codes arrays")
+      end
+
+      read = EntryReader.new("listTaskTypes")
+      TaskTypeCatalog.new(
+        task_types: task_types.map do |raw|
+          entry = read.object(raw)
+          TaskTypeInfo.new(
+            page_slug: read.optional_text(entry, "page_slug"),
+            display_name: read.text(entry, "display_name"),
+            task_type: read.text(entry, "task_type"),
+            task_type_proxyless: read.optional_text(entry, "task_type_proxyless"),
+            aliases: read.texts(entry["aliases"], "aliases"),
+            proxy: read.text(entry, "proxy"),
+            required: read.groups(entry, "required"),
+            any_of: read.groups(entry, "any_of"),
+            optional: read.texts(entry["optional"], "optional"),
+            solution_keys: read.texts(entry["solution_keys"], "solution_keys")
+          )
+        end,
+        error_codes: read.texts(error_codes, "error_codes")
+      )
+    end
+
+    # Active services with their current USD price per task (decimal strings).
+    def list_services
+      services = catalog_call("listServices", "/v1/services")["services"]
+      raise ProtocolError.new("listServices", "data without a services array") unless services.is_a?(Array)
+
+      read = EntryReader.new("listServices")
+      services.map do |raw|
+        entry = read.object(raw)
+        ServiceInfo.new(
+          id: read.integer(entry, "id"),
+          slug: read.text(entry, "slug"),
+          display_name: read.text(entry, "display_name"),
+          price_per_request: read.text(entry, "price_per_request"),
+          status: read.text(entry, "status"),
+          avg_latency_ms: entry.key?("avg_latency_ms") && entry["avg_latency_ms"].nil? ? nil : read.integer(entry, "avg_latency_ms")
+        )
+      end
+    end
+
+    private
+
+    def require_positive(name, value)
+      raise ConfigurationError, "#{name} must be a positive number of seconds" unless value.is_a?(Numeric) && value.positive?
+    end
+
+    def normalize_base_url(raw)
+      uri = begin
+        URI.parse(raw.to_s)
+      rescue URI::InvalidURIError
+        nil
+      end
+      raise ConfigurationError, "base_url is not a valid absolute URL" if uri.nil? || uri.host.nil? || uri.host.empty?
+
+      host = uri.host.downcase.delete_prefix("[").delete_suffix("]")
+      loopback_http = uri.scheme == "http" && LOOPBACK_HOSTS.include?(host)
+      unless uri.scheme == "https" || loopback_http
+        raise ConfigurationError, "base_url must use https:// (plain http:// only for localhost)"
+      end
+      if uri.userinfo || uri.query || uri.fragment || raw.include?("?") || raw.include?("#")
+        raise ConfigurationError, "base_url must not carry credentials, a query or a fragment"
+      end
+
+      port = uri.port == uri.default_port ? "" : ":#{uri.port}"
+      "#{uri.scheme}://#{uri.host.downcase}#{port}#{uri.path.sub(%r{/+\z}, "")}"
+    end
+
+    def request(method, path, body)
+      headers = { "Accept" => "application/json", "User-Agent" => @user_agent }
+      headers["Content-Type"] = "application/json" if body
+      Request.new(method: method, url: @base_url + path, headers: headers, body: body, timeout: @request_timeout)
+    end
+
+    def send_request(operation, request)
+      response = begin
+        @transport.call(request)
+      rescue Timeout::Error
+        raise TransportError.new(operation, "request timed out after #{(request.timeout * 1000).round} ms")
+      rescue *NO_RESPONSE_ERRORS
+        raise TransportError.new(operation, "connection failed")
+      end
+      return response if response.status == 200
+
+      detail = parse(response.body)
+      detail = detail.is_a?(Hash) ? detail["error"] : nil
+      server_code = detail.is_a?(Hash) && detail["code"].is_a?(String) ? detail["code"] : nil
+      retry_after = detail.is_a?(Hash) && detail["retry_after_seconds"].is_a?(Numeric) ? detail["retry_after_seconds"].to_i : nil
+      reason = server_code ? "HTTP #{response.status} (#{server_code})" : "HTTP #{response.status}"
+      raise TransportError.new(operation, reason, status: response.status, server_code: server_code,
+                                                  retry_after_seconds: retry_after)
+    end
+
+    NOT_JSON = Object.new.freeze
+    private_constant :NOT_JSON
+
+    def parse(body)
+      JSON.parse(body.to_s)
+    rescue JSON::ParserError
+      NOT_JSON
+    end
+
+    # POSTs to a solver endpoint; returns the errorId 0 body or raises the classified error.
+    def solver_call(operation, path, payload, task_id = nil)
+      response = send_request(operation, request("POST", path, JSON.generate(payload)))
+      body = parse(response.body)
+      error_id = body.is_a?(Hash) ? body["errorId"] : nil
+      unless error_id.is_a?(Integer) || (error_id.is_a?(Float) && error_id.finite? && error_id == error_id.floor)
+        what = body.equal?(NOT_JSON) ? "not JSON" : "not the solver envelope"
+        raise TransportError.new(operation, "HTTP 200 body is #{what}", status: 200)
+      end
+      return body if error_id.zero?
+      raise ProtocolError.new(operation, "errorId #{error_id}") unless error_id == 1
+
+      code = body["errorCode"]
+      raise ProtocolError.new(operation, "errorId 1 without a string errorCode") unless code.is_a?(String)
+
+      description = body["errorDescription"].is_a?(String) ? body["errorDescription"] : ""
+      supported = body["supportedUserAgents"].is_a?(Array) ? body["supportedUserAgents"].grep(String) : []
+      raise ApiError.for(operation, code, description, task_id, supported)
+    end
+
+    # GETs a public catalog endpoint and returns its data object.
+    def catalog_call(operation, path)
+      envelope = parse(send_request(operation, request("GET", path, nil)).body)
+      return envelope["data"] if envelope.is_a?(Hash) && envelope["success"] == true && envelope["data"].is_a?(Hash)
+
+      raise TransportError.new(operation, "HTTP 200 body is not the API envelope", status: 200)
+    end
+
+    # Typed reads of catalog entries; a missing or mistyped field is a ProtocolError.
+    class EntryReader
+      def initialize(operation)
+        @operation = operation
+      end
+
+      def object(raw)
+        raise ProtocolError.new(@operation, "a catalog entry is not an object") unless raw.is_a?(Hash)
+
+        raw
+      end
+
+      def text(entry, key)
+        value = entry[key]
+        raise fail(key, "a string") unless value.is_a?(String)
+
+        value
+      end
+
+      def optional_text(entry, key)
+        value = entry[key]
+        raise fail(key, "a string or null") unless value.nil? || value.is_a?(String)
+
+        value
+      end
+
+      def integer(entry, key)
+        value = entry[key]
+        raise fail(key, "an integer") unless value.is_a?(Integer)
+
+        value
+      end
+
+      def texts(raw, key)
+        raise fail(key, "a list of strings") unless raw.is_a?(Array) && raw.all?(String)
+
+        raw
+      end
+
+      def groups(entry, key)
+        value = entry[key]
+        raise fail(key, "a list of string lists") unless value.is_a?(Array) && value.all? { |g| g.is_a?(Array) && g.all?(String) }
+
+        value
+      end
+
+      private
+
+      def fail(key, expected)
+        ProtocolError.new(@operation, "catalog field #{key} is not #{expected}")
+      end
+    end
+    private_constant :EntryReader
+  end
+end

data/lib/sursolver/errors.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module SurSolver
+  # Base of every error the client raises. Messages never contain the API key.
+  class Error < StandardError
+    # The call that failed ("createTask", "getTaskResult", "getBalance", "listTaskTypes",
+    # "listServices"); nil for ConfigurationError and SolveTimeoutError.
+    attr_reader :operation
+
+    def initialize(message, operation: nil)
+      super(message)
+      @operation = operation
+    end
+  end
+
+  # The client was built with an unusable option. Nothing was sent.
+  class ConfigurationError < Error; end
+
+  # No usable answer: a connection failure, a timeout, a non-200 status, or a body that is not the
+  # API's envelope. It says nothing about the task.
+  class TransportError < Error
+    # The HTTP status when a response arrived, otherwise nil.
+    attr_reader :status
+    # error.code of the API's internal envelope, or nil.
+    attr_reader :server_code
+    # error.retry_after_seconds of the internal envelope, or nil.
+    attr_reader :retry_after_seconds
+
+    def initialize(operation, reason, status: nil, server_code: nil, retry_after_seconds: nil)
+      note = operation == "createTask" ? " The task may have been created and charged; check get_balance before submitting again." : ""
+      super("#{operation} failed: #{reason}.#{note}", operation: operation)
+      @status = status
+      @server_code = server_code
+      @retry_after_seconds = retry_after_seconds
+    end
+
+    # True for createTask: the request may have been accepted and charged before the answer was
+    # lost. Check get_balance before submitting again.
+    def may_have_created_task?
+      operation == "createTask"
+    end
+  end
+
+  # HTTP 200 JSON whose shape the API contract does not allow.
+  class ProtocolError < Error
+    def initialize(operation, detail)
+      super("#{operation} returned an unexpected response: #{detail}", operation: operation)
+    end
+  end
+
+  # solve reached its deadline. The task may still finish and stays charged; poll it with
+  # get_task_result(task_id) if you still need the result.
+  class SolveTimeoutError < Error
+    attr_reader :task_id, :timeout, :last_error
+
+    def initialize(task_id, timeout, last_error)
+      super("task #{task_id} was not ready within #{timeout} s; it may still finish and stays charged")
+      @task_id = task_id
+      @timeout = timeout
+      @last_error = last_error
+    end
+  end
+
+  # The API answered errorId 1. Rescue the subclasses for the codes you handle; ApiError itself
+  # means ERROR_INTERNAL_ERROR, ERROR_FAILED on create, or a code newer than this gem.
+  class ApiError < Error
+    # The errorCode exactly as sent, including codes newer than this gem.
+    attr_reader :code
+    # The errorDescription as sent.
+    attr_reader :description
+    # The task for get_task_result and for solve after acceptance, otherwise nil.
+    attr_reader :task_id
+    # The list sent with ERROR_WRONG_USERAGENT; empty otherwise.
+    attr_reader :supported_user_agents
+
+    def initialize(operation, code, description, task_id: nil, supported_user_agents: [])
+      super("#{code}: #{description}#{task_id ? " (task #{task_id})" : ""}", operation: operation)
+      @code = code
+      @description = description
+      @task_id = task_id
+      @supported_user_agents = supported_user_agents.freeze
+    end
+
+    # True only for ERROR_NO_SLOT_AVAILABLE.
+    def retryable?
+      code == ErrorCodes::ERROR_NO_SLOT_AVAILABLE
+    end
+  end
+
+  # ERROR_WRONG_CLIENT_KEY or ERROR_KEY_DOES_NOT_EXIST: fix the API key.
+  class AuthenticationError < ApiError; end
+
+  # ERROR_INVALID_REQUEST, ERROR_TYPE_NOT_SUPPORTED, or ERROR_WRONG_USERAGENT on create (see
+  # supported_user_agents). Nothing was created or charged.
+  class InvalidTaskError < ApiError; end
+
+  # ERROR_ZERO_BALANCE: top up. Nothing was charged.
+  class InsufficientBalanceError < ApiError; end
+
+  # ERROR_NO_SLOT_AVAILABLE: all your threads are busy. Nothing was created; submitting later is safe.
+  class NoSlotAvailableError < ApiError; end
+
+  # ERROR_TASK_NOT_FOUND.
+  class TaskNotFoundError < ApiError; end
+
+  # The task ended without a result (ERROR_FAILED, ERROR_TASK_TIMEOUT, ERROR_TASK_EXPIRED, or
+  # ERROR_WRONG_USERAGENT after acceptance). Its charge is returned once.
+  class TaskFailedError < ApiError; end
+
+  class ApiError
+    TASK_FAILURE_CODES = [
+      ErrorCodes::ERROR_FAILED, ErrorCodes::ERROR_TASK_TIMEOUT, ErrorCodes::ERROR_TASK_EXPIRED,
+      ErrorCodes::ERROR_WRONG_USERAGENT
+    ].freeze
+
+    CLASS_BY_CODE = {
+      ErrorCodes::ERROR_WRONG_CLIENT_KEY => AuthenticationError,
+      ErrorCodes::ERROR_KEY_DOES_NOT_EXIST => AuthenticationError,
+      ErrorCodes::ERROR_INVALID_REQUEST => InvalidTaskError,
+      ErrorCodes::ERROR_TYPE_NOT_SUPPORTED => InvalidTaskError,
+      ErrorCodes::ERROR_WRONG_USERAGENT => InvalidTaskError,
+      ErrorCodes::ERROR_ZERO_BALANCE => InsufficientBalanceError,
+      ErrorCodes::ERROR_NO_SLOT_AVAILABLE => NoSlotAvailableError,
+      ErrorCodes::ERROR_TASK_NOT_FOUND => TaskNotFoundError
+    }.freeze
+
+    # The error for a code; the class depends on the operation and the code.
+    def self.for(operation, code, description, task_id, supported)
+      klass = if operation == "getTaskResult" && TASK_FAILURE_CODES.include?(code)
+                TaskFailedError
+              else
+                CLASS_BY_CODE.fetch(code, ApiError)
+              end
+      klass.new(operation, code, description, task_id: task_id, supported_user_agents: supported)
+    end
+  end
+end

data/lib/sursolver/task_types.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Generated from the SurSolver catalog (GET /v1/task-types) by the spec repository
+# tools/templates/rubygems.ts. Catalog fetched at 2026-11-03T21:16:22.334Z. DO NOT EDIT.
+
+module SurSolver
+  # Every accepted task.type spelling: canonical names, ProxyLess twins and aliases.
+  module TaskTypes
+    AKAMAI_BMP_TASK = "AkamaiBmpTask"
+    AKAMAI_COOKIE = "AkamaiCookie"
+    AKAMAI_COOKIE_PROXY_LESS = "AkamaiCookieProxyLess"
+    AKAMAI_SBSD_COOKIE = "AkamaiSbsdCookie"
+    ALTCHA_TOKEN = "AltchaToken"
+    ALTCHA_TOKEN_PROXY_LESS = "AltchaTokenProxyLess"
+    AWS_CAPTCHA_COOKIE = "AwsCaptchaCookie"
+    AWS_CHALLENGE_COOKIE = "AwsChallengeCookie"
+    CAPTCHA_FOX_TOKEN = "CaptchaFoxToken"
+    CASTLE_ANDROID_TOKEN = "CastleAndroidToken"
+    CASTLE_TOKEN = "CastleToken"
+    CASTLE_WEB_TOKEN = "CastleWebToken"
+    CLOUDFLARE_CHALLENGE_COOKIE = "CloudflareChallengeCookie"
+    DATA_DOME_SLIDER_COOKIE = "DataDomeSliderCookie"
+    FRIENDLY_CAPTCHA_TOKEN = "FriendlyCaptchaToken"
+    FRIENDLY_CAPTCHA_TOKEN_PROXY_LESS = "FriendlyCaptchaTokenProxyLess"
+    GEE_TEST_TOKEN = "GeeTestToken"
+    GEE_TEST_TOKEN_PROXY_LESS = "GeeTestTokenProxyLess"
+    GEE_TEST_V3_TOKEN = "GeeTestV3Token"
+    GEE_TEST_V4_TOKEN = "GeeTestV4Token"
+    IMAGE_TO_TEXT = "ImageToText"
+    IMAGE_TO_TEXT_TASK = "ImageToTextTask"
+    IMPERVA_COOKIE = "ImpervaCookie"
+    IMPERVA_UTMVC_COOKIE = "ImpervaUtmvcCookie"
+    KASADA_TOKEN = "KasadaToken"
+    KASADA_TOKEN_PROXY_LESS = "KasadaTokenProxyLess"
+    LEMIN_TOKEN = "LeminToken"
+    LEMIN_TOKEN_PROXY_LESS = "LeminTokenProxyLess"
+    MT_CAPTCHA_TOKEN = "MtCaptchaToken"
+    MT_CAPTCHA_TOKEN_PROXY_LESS = "MtCaptchaTokenProxyLess"
+    PERIMETER_X_COOKIE = "PerimeterXCookie"
+    PROSOPO_TOKEN = "ProsopoToken"
+    PROSOPO_TOKEN_PROXY_LESS = "ProsopoTokenProxyLess"
+    RE_CAPTCHA_V2_ENTERPRISE_TOKEN = "ReCaptchaV2EnterpriseToken"
+    RE_CAPTCHA_V2_ENTERPRISE_TOKEN_PROXY_LESS = "ReCaptchaV2EnterpriseTokenProxyLess"
+    RE_CAPTCHA_V2_TOKEN = "ReCaptchaV2Token"
+    RE_CAPTCHA_V2_TOKEN_PROXY_LESS = "ReCaptchaV2TokenProxyLess"
+    RE_CAPTCHA_V3_ENTERPRISE_TOKEN = "ReCaptchaV3EnterpriseToken"
+    RE_CAPTCHA_V3_ENTERPRISE_TOKEN_PROXY_LESS = "ReCaptchaV3EnterpriseTokenProxyLess"
+    RE_CAPTCHA_V3_TOKEN = "ReCaptchaV3Token"
+    RE_CAPTCHA_V3_TOKEN_PROXY_LESS = "ReCaptchaV3TokenProxyLess"
+    SHAPE_COOKIE = "ShapeCookie"
+    SHAPE_COOKIE_PROXY_LESS = "ShapeCookieProxyLess"
+    TURNSTILE_TOKEN = "TurnstileToken"
+    TURNSTILE_TOKEN_PROXY_LESS = "TurnstileTokenProxyLess"
+    VERCEL_COOKIE = "VercelCookie"
+  end
+
+  # The complete errorCode vocabulary of the solver endpoints.
+  module ErrorCodes
+    ERROR_KEY_DOES_NOT_EXIST = "ERROR_KEY_DOES_NOT_EXIST"
+    ERROR_WRONG_CLIENT_KEY = "ERROR_WRONG_CLIENT_KEY"
+    ERROR_ZERO_BALANCE = "ERROR_ZERO_BALANCE"
+    ERROR_NO_SLOT_AVAILABLE = "ERROR_NO_SLOT_AVAILABLE"
+    ERROR_TYPE_NOT_SUPPORTED = "ERROR_TYPE_NOT_SUPPORTED"
+    ERROR_TASK_NOT_FOUND = "ERROR_TASK_NOT_FOUND"
+    ERROR_TASK_EXPIRED = "ERROR_TASK_EXPIRED"
+    ERROR_TASK_TIMEOUT = "ERROR_TASK_TIMEOUT"
+    ERROR_FAILED = "ERROR_FAILED"
+    ERROR_INVALID_REQUEST = "ERROR_INVALID_REQUEST"
+    ERROR_WRONG_USERAGENT = "ERROR_WRONG_USERAGENT"
+    ERROR_INTERNAL_ERROR = "ERROR_INTERNAL_ERROR"
+
+    # All codes in catalog order.
+    ALL = [ERROR_KEY_DOES_NOT_EXIST, ERROR_WRONG_CLIENT_KEY, ERROR_ZERO_BALANCE, ERROR_NO_SLOT_AVAILABLE, ERROR_TYPE_NOT_SUPPORTED, ERROR_TASK_NOT_FOUND, ERROR_TASK_EXPIRED, ERROR_TASK_TIMEOUT, ERROR_FAILED, ERROR_INVALID_REQUEST, ERROR_WRONG_USERAGENT, ERROR_INTERNAL_ERROR].freeze
+  end
+end

data/lib/sursolver/transport.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module SurSolver
+  # One HTTP request handed to a transport. timeout is in seconds.
+  Request = Struct.new(:method, :url, :headers, :body, :timeout, keyword_init: true)
+
+  # What a transport returns for any HTTP status.
+  Response = Struct.new(:status, :body, keyword_init: true)
+
+  # The default transport: Net::HTTP, which never follows redirects, so a request body carrying the
+  # API key is not replayed to another location.
+  #
+  # A transport is any object with #call(request) returning a Response for every HTTP status. Raise
+  # Timeout::Error when request.timeout passes, and an IOError, SystemCallError or SocketError when
+  # no response arrived.
+  class NetHttpTransport
+    # proxy: optional URI of an HTTP proxy for the connection to the API.
+    def initialize(proxy: nil)
+      @proxy = proxy && URI(proxy)
+    end
+
+    def call(request)
+      uri = URI(request.url)
+      http = Net::HTTP.new(uri.host, uri.port, @proxy&.host, @proxy&.port, @proxy&.user, @proxy&.password)
+      http.use_ssl = uri.scheme == "https"
+      # Net::HTTP bounds each phase (connect, write, every read) by the request timeout.
+      http.open_timeout = http.read_timeout = http.write_timeout = http.ssl_timeout = request.timeout
+      http.max_retries = 0
+      message = (request.method == "POST" ? Net::HTTP::Post : Net::HTTP::Get).new(uri.request_uri, request.headers)
+      message.body = request.body if request.body
+      response = http.start { |connection| connection.request(message) }
+      Response.new(status: response.code.to_i, body: response.body || "")
+    end
+  end
+
+  # The real clock: monotonic seconds and Kernel#sleep.
+  class SystemClock
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def sleep(seconds)
+      Kernel.sleep(seconds)
+    end
+  end
+end

data/lib/sursolver/types.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SurSolver
+  # One getTaskResult answer: status is "processing" or "ready" (with solution). Solution keys
+  # differ per type ("token", "gRecaptchaResponse", "cf_clearance", "cookies", ...) and are passed
+  # through untouched. Tokens are single-use.
+  TaskResult = Struct.new(:status, :solution, keyword_init: true) do
+    def ready?
+      status == "ready"
+    end
+
+    def processing?
+      status == "processing"
+    end
+  end
+
+  # What solve returns.
+  SolveResult = Struct.new(:task_id, :solution, keyword_init: true)
+
+  # One entry of GET /v1/task-types. proxy is "none", "optional" or "required"; required lists
+  # groups of accepted spellings (one name per group); any_of lists alternatives.
+  TaskTypeInfo = Struct.new(
+    :page_slug, :display_name, :task_type, :task_type_proxyless, :aliases, :proxy, :required,
+    :any_of, :optional, :solution_keys, keyword_init: true
+  )
+
+  # The public task-type catalog.
+  TaskTypeCatalog = Struct.new(:task_types, :error_codes, keyword_init: true)
+
+  # One entry of GET /v1/services. price_per_request is the USD price per task as a decimal string.
+  ServiceInfo = Struct.new(:id, :slug, :display_name, :price_per_request, :status, :avg_latency_ms, keyword_init: true)
+end

data/lib/sursolver/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SurSolver
+  VERSION = "0.1.0"
+end

data/lib/sursolver.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "sursolver/version"
+require_relative "sursolver/task_types"
+require_relative "sursolver/errors"
+require_relative "sursolver/types"
+require_relative "sursolver/transport"
+require_relative "sursolver/client"
+
+# Official Ruby client for the SurSolver captcha-solving API (https://sursolver.com).
+#
+#   client = SurSolver::Client.new("YOUR_API_KEY")
+#   result = client.solve(
+#     "type" => SurSolver::TaskTypes::TURNSTILE_TOKEN_PROXY_LESS,
+#     "websiteURL" => "https://example.com/login",
+#     "websiteKey" => "0x4AAAAAAA...",
+#     "userAgent" => USER_AGENT
+#   )
+#   result.solution["token"]
+#
+# The API key travels only in request bodies and never appears in errors or #inspect.
+module SurSolver
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: sursolver
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SurSolver
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: Solve reCAPTCHA v3, Cloudflare Turnstile, Cloudflare Challenge (cf_clearance),
+  GeeTest, DataDome, AWS WAF, Akamai, Kasada and image captchas from Ruby with one
+  call. Standard library only.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/sursolver.rb
+- lib/sursolver/client.rb
+- lib/sursolver/errors.rb
+- lib/sursolver/task_types.rb
+- lib/sursolver/transport.rb
+- lib/sursolver/types.rb
+- lib/sursolver/version.rb
+homepage: https://sursolver.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://sursolver.com
+  documentation_uri: https://sursolver.com/docs
+  source_code_uri: https://github.com/sursolver/sursolver-ruby
+  changelog_uri: https://github.com/sursolver/sursolver-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby client for the SurSolver captcha solver API.
+test_files: []