muaraicaptcha 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1030792ff79fdc91401c0d9b1f0d8e6454526158bb194abdba16709a3620d191
+  data.tar.gz: 6266c3710a1edc4c1d59d0dd66d9dd0cc315df945c30d0600ba303d963436128
+SHA512:
+  metadata.gz: 983ea8895eb487ff6f9e0836e7f635c61ec9a6864bba1f6cac2ee441b6b36060eb8e127e6f96cf17bcc23e4cb67139ea9dcb4ac40603cb96e2d595ec6256a281
+  data.tar.gz: d5cf56bdc2eff3ab4868dbfe13f9d4d680e14f333601079d96d610c4265a0c00780dc2f96b0c38cd9038a7b812e71b71d06e848b691cb042954654e92ba6c789

data/README.md

@@ -0,0 +1,67 @@
+<div align="center">
+
+# MuaraiCaptcha — Ruby SDK
+
+Official Ruby client for the [MuaraiCaptcha](https://muaraicaptcha.com) solving API.
+
+[![Gem](https://img.shields.io/badge/gem-muaraicaptcha-CC342D?style=flat-square)](https://rubygems.org/gems/muaraicaptcha)
+[![License](https://img.shields.io/badge/license-MIT-black?style=flat-square)](../../LICENSE)
+
+</div>
+
+Zero dependencies — standard library only (`net/http`).
+
+## Install
+
+```bash
+gem install muaraicaptcha
+```
+
+## Quick start
+
+```ruby
+require "muaraicaptcha"
+
+client = MuaraiCaptcha::Client.new("YOUR_API_KEY")
+
+solution = client.solve(
+  "type" => "TurnstileTaskProxyless",
+  "websiteURL" => "https://example.com",
+  "websiteKey" => "0x4AAAAAAA..."
+)
+puts solution["token"]
+```
+
+## API
+
+```ruby
+client = MuaraiCaptcha::Client.new(client_key, base_url: "...", timeout: 30)
+
+client.get_balance                       # => Float (USD)
+client.create_task(task)                 # => Integer taskId
+client.get_task_result(task_id)          # => Hash solution, or nil while processing
+client.report_incorrect(task_id)         # auto-refund a bad solve
+client.solve(task, poll_interval: 5, timeout: 180)  # create + poll
+```
+
+## Error handling
+
+```ruby
+begin
+  client.solve(task)
+rescue MuaraiCaptcha::ApiError => e
+  puts "#{e.code}: #{e.description}"   # e.g. ERROR_ZERO_BALANCE
+rescue MuaraiCaptcha::TimeoutError
+  puts "gave up waiting"
+end
+```
+
+## Documentation
+
+- [Task types & parameters](../../docs/task-types.md)
+- [Error codes](../../docs/error-codes.md)
+- [Full API reference](../../docs/api-reference.md)
+
+## License
+
+MIT © MuaraiCaptcha

data/lib/muaraicaptcha.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+# MuaraiCaptcha — official Ruby SDK.
+#
+# Solve reCAPTCHA, hCaptcha, Turnstile, FunCaptcha, image captchas and more
+# through the MuaraiCaptcha API (https://muaraicaptcha.com).
+#
+#   require "muaraicaptcha"
+#   client = MuaraiCaptcha::Client.new("YOUR_API_KEY")
+#   solution = client.solve("type" => "TurnstileTaskProxyless",
+#                           "websiteURL" => "https://example.com",
+#                           "websiteKey" => "0x4AAAAAAA...")
+#   puts solution["token"]
+
+require "json"
+require "net/http"
+require "uri"
+
+module MuaraiCaptcha
+  VERSION = "1.1.0"
+  DEFAULT_BASE_URL = "https://api.muaraicaptcha.com"
+
+  # Base error for the SDK.
+  class Error < StandardError; end
+
+  # Raised when the API returns a non-zero errorId.
+  class ApiError < Error
+    attr_reader :code, :description
+
+    def initialize(code, description)
+      @code = code
+      @description = description
+      super("#{code}: #{description}")
+    end
+  end
+
+  # Raised when a job does not resolve within the timeout.
+  class TimeoutError < Error; end
+
+  class Client
+    # @param client_key [String] API key from console.muaraicaptcha.com
+    # @param base_url [String] override the API base URL
+    # @param timeout [Numeric] per-request timeout in seconds
+    def initialize(client_key, base_url: DEFAULT_BASE_URL, timeout: 30)
+      raise Error, "client_key is required" if client_key.nil? || client_key.empty?
+
+      @client_key = client_key
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+    end
+
+    # @return [Float] account balance in USD
+    def get_balance
+      res = post("/v1/account/balance", "clientKey" => @client_key)
+      res.fetch("balance", 0).to_f
+    end
+
+    # @param task [Hash] task object with "type" + fields
+    # @return [Integer] jobId
+    def create_job(task)
+      res = post("/v1/job/create", "clientKey" => @client_key, "task" => task)
+      res.fetch("jobId").to_i
+    end
+
+    # Poll once. Returns the solution Hash when ready, or nil while processing.
+    # Raises ApiError if the job failed.
+    def get_job_result(job_id)
+      res = post("/v1/job/result", "clientKey" => @client_key, "jobId" => job_id)
+      case res["status"]
+      when "ready"
+        res.fetch("solution", {})
+      when "failed"
+        raise ApiError.new(
+          res.fetch("errorCode", "ERROR_CAPTCHA_UNSOLVABLE"),
+          res.fetch("errorDescription", "Job failed")
+        )
+      end
+    end
+
+    # Report a bad solution — the charge is refunded automatically.
+    def report_incorrect(job_id)
+      post("/v1/job/report", "clientKey" => @client_key, "jobId" => job_id, "correct" => false)
+      nil
+    end
+
+    # Create a job and poll until solved. Returns the solution Hash.
+    def solve(task, poll_interval: 5, timeout: 180)
+      job_id = create_job(task)
+      deadline = monotonic + timeout
+      sleep([poll_interval, 3].min)
+      while monotonic < deadline
+        solution = get_job_result(job_id)
+        return solution if solution
+        sleep(poll_interval)
+      end
+      raise TimeoutError, "job #{job_id} did not resolve within #{timeout}s"
+    end
+
+    # --- backward-compatible aliases (deprecated, kept for 1.0.x users) ---
+    alias create_task create_job
+    alias get_task_result get_job_result
+
+    private
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def post(path, body)
+      uri = URI.parse("#{@base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+
+      req = Net::HTTP::Post.new(uri.request_uri)
+      req["Content-Type"] = "application/json"
+      req["Accept"] = "application/json"
+      req["User-Agent"] = "muaraicaptcha-ruby/#{VERSION}"
+      req.body = JSON.generate(body)
+
+      res = http.request(req)
+      payload = JSON.parse(res.body)
+
+      if payload.is_a?(Hash) && payload["errorId"].to_i != 0
+        raise ApiError.new(
+          payload.fetch("errorCode", "ERROR_UNKNOWN"),
+          payload.fetch("errorDescription", "Unknown error")
+        )
+      end
+      payload
+    rescue JSON::ParserError
+      raise Error, "invalid JSON response (HTTP #{res&.code})"
+    end
+  end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: muaraicaptcha
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- MuaraiCaptcha
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-31 00:00:00.000000000 Z
+dependencies: []
+description: Solve reCAPTCHA, hCaptcha, Turnstile, FunCaptcha, image captchas and
+  more via MuaraiCaptcha.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/muaraicaptcha.rb
+homepage: https://muaraicaptcha.com
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/MuaraiCaptcha/MuaraiCaptcha
+  documentation_uri: https://github.com/MuaraiCaptcha/MuaraiCaptcha/tree/main/docs
+  github_repo: https://github.com/MuaraiCaptcha/MuaraiCaptcha
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the MuaraiCaptcha solving API
+test_files: []