private_captcha 0.0.2 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0681aaa5e68aae1562fbe7fc20c19dc098305f752673f574e50c6c0094fcb95
-  data.tar.gz: 12c1a1692cd0b3d3be4d775fcebf95389a5fc8d40cfa0fec39783e6f8bc4f06d
+  metadata.gz: 70c3d94ed5a3020b3f71df8c50558c2e1a09c5e245374844209d2734bc4d51a8
+  data.tar.gz: 6a3a267b62466abc243069c922af1440f77d6feaeac24c96238d1841aa9d4437
 SHA512:
-  metadata.gz: fc9382338a62a9cb3d5f49ead2b670bcf3967eae7051308c20cbe436fdbf3046f1177df9a1e2b723ea1e8560b5343e04bfd8288b9da1bc20e9c5bf5b38973a5e
-  data.tar.gz: 33e903e9de21aba85e9cb34a12015555ed30fc415118c2923495f75f0373bf64d91b9cda145b9936447a8f17c46d979c150fc01c16f9fd2685cc0d8e4661feed
+  metadata.gz: 88e3e2caef19070d9aba49ceaf62b9a9eb0fb0c80bf56e6c9c90a86d513137248c9a8435b5fb751604c1bd1814f5d771ba9bf021a3278aa6ac964f13e0021716
+  data.tar.gz: 7bb7b45b726e696b3ea57d38c2ad6fbb1a9a7e37ac2ece858f50e43741512c39469f68732894ac0696b70c98c977459f18ebecb2cba12c4e8f294b628d76f4de

data/README.md

@@ -1,6 +1,7 @@
 # private-captcha-ruby
 
-![CI](https://github.com/PrivateCaptcha/private-captcha-ruby/actions/workflows/ci.yaml/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/private_captcha.svg)](https://badge.fury.io/rb/private_captcha)
+ ![CI](https://github.com/PrivateCaptcha/private-captcha-ruby/actions/workflows/ci.yaml/badge.svg)
 
 Ruby client for server-side verification of Private Captcha solutions.
 
@@ -37,7 +38,7 @@ end
 # Verify a captcha solution
 begin
   result = client.verify('user-solution-from-frontend')
-  if result.success
+  if result.ok?
     puts 'Captcha verified successfully!'
   else
     puts "Verification failed: #{result.error_message}"

data/lib/private_captcha/client.rb

@@ -25,7 +25,7 @@ module PrivateCaptcha
     end
 
     # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
-    def verify(solution, max_backoff_seconds: nil, attempts: nil)
+    def verify(solution, max_backoff_seconds: nil, attempts: nil, sitekey: nil)
       raise EmptySolutionError if solution.nil? || solution.empty?
 
       max_backoff = max_backoff_seconds || @config.max_backoff_seconds
@@ -38,6 +38,7 @@ module PrivateCaptcha
       response = nil
       error = nil
       attempt = 0
+      trace_id = nil
 
       max_attempts.times do |i|
         attempt = i + 1
@@ -51,11 +52,12 @@ module PrivateCaptcha
         end
 
         begin
-          response = do_verify(solution)
+          response = do_verify(solution, sitekey: sitekey)
           error = nil
           break
         rescue RetriableError => e
           error = e.original_error
+          trace_id = e.trace_id if e.trace_id
         end
       end
 
@@ -65,7 +67,8 @@ module PrivateCaptcha
 
       if error
         @logger.error("Failed to verify solution after #{attempt} attempts")
-        raise VerificationFailedError.new("Failed to verify solution after #{attempt} attempts", attempt)
+        raise VerificationFailedError.new("Failed to verify solution after #{attempt} attempts", attempt,
+                                          trace_id: trace_id)
       end
 
       response
@@ -78,7 +81,10 @@ module PrivateCaptcha
 
       output = verify(solution)
 
-      raise Error, "captcha verification failed: #{output.error_message}" unless output.success
+      unless output.ok?
+        raise Error.new("captcha verification failed: #{output.error_message}",
+                        trace_id: output.trace_id)
+      end
 
       output
     end
@@ -94,20 +100,23 @@ module PrivateCaptcha
     end
 
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-    def do_verify(solution)
+    def do_verify(solution, sitekey: nil)
       request = Net::HTTP::Post.new(@endpoint)
       request['X-Api-Key'] = @config.api_key
       request['User-Agent'] = "private-captcha-ruby/#{VERSION}"
       request['Content-Type'] = 'text/plain'
+      request['X-PC-Sitekey'] = sitekey if sitekey
       request.body = solution
 
       @logger.debug('Sending HTTP request') { "path=#{@endpoint.path} method=POST" }
 
       response = nil
+      trace_id = nil
       begin
         response = Net::HTTP.start(@endpoint.hostname, @endpoint.port, use_ssl: true) do |http|
           http.request(request)
         end
+        trace_id = response['X-Trace-ID']
       rescue SocketError, IOError, Timeout::Error, SystemCallError => e
         @logger.debug('Failed to send HTTP request') { "error=#{e.message}" }
         raise RetriableError, e
@@ -118,7 +127,6 @@ module PrivateCaptcha
       end
 
       status_code = response.code.to_i
-      request_id = response['X-Trace-ID']
 
       case status_code
       when 429
@@ -126,16 +134,16 @@ module PrivateCaptcha
         @logger.debug('Rate limited') do
           "retryAfter=#{retry_after} rateLimit=#{response['X-RateLimit-Limit']}"
         end
-        raise RetriableError, HTTPError.new(status_code, retry_after)
+        raise RetriableError, HTTPError.new(status_code, retry_after, trace_id: trace_id)
       when 500, 502, 503, 504, 408, 425
-        raise RetriableError, HTTPError.new(status_code)
+        raise RetriableError, HTTPError.new(status_code, trace_id: trace_id)
       when 300..599
-        raise HTTPError, status_code
+        raise HTTPError.new(status_code, trace_id: trace_id)
       end
 
       begin
         json_data = JSON.parse(response.body)
-        VerifyOutput.from_json(json_data, request_id: request_id)
+        VerifyOutput.from_json(json_data, trace_id: trace_id)
       rescue JSON::ParserError => e
         @logger.debug('Failed to parse response') { "error=#{e.message}" }
         raise RetriableError, e

data/lib/private_captcha/errors.rb

@@ -1,18 +1,26 @@
 # frozen_string_literal: true
 
 module PrivateCaptcha
-  class Error < StandardError; end
+  # Error is the base class for Private Captcha errors
+  class Error < StandardError
+    attr_reader :trace_id
+
+    def initialize(msg = nil, trace_id: nil)
+      @trace_id = trace_id
+      super(msg)
+    end
+  end
 
   # EmptyAPIKeyError is raised when the API key is not provided or is empty
   class EmptyAPIKeyError < Error
-    def initialize(msg = 'API key is empty')
+    def initialize(msg = 'API key is empty', trace_id: nil)
       super
     end
   end
 
   # EmptySolutionError is raised when the solution is not provided or is empty
   class EmptySolutionError < Error
-    def initialize(msg = 'solution is empty')
+    def initialize(msg = 'solution is empty', trace_id: nil)
       super
     end
   end
@@ -21,10 +29,10 @@ module PrivateCaptcha
   class HTTPError < Error
     attr_reader :status_code, :seconds
 
-    def initialize(status_code, seconds = nil)
+    def initialize(status_code, seconds = nil, trace_id: nil)
       @status_code = status_code
       @seconds = seconds
-      super("HTTP error #{status_code}")
+      super("HTTP error #{status_code}", trace_id: trace_id)
     end
   end
 
@@ -36,15 +44,19 @@ module PrivateCaptcha
       @original_error = error
       super(error.message)
     end
+
+    def trace_id
+      @original_error.respond_to?(:trace_id) ? @original_error.trace_id : nil
+    end
   end
 
   # VerificationFailedError is raised when verification fails after all retry attempts
   class VerificationFailedError < Error
     attr_reader :attempts
 
-    def initialize(message, attempts)
+    def initialize(message, attempts, trace_id: nil)
       @attempts = attempts
-      super(message)
+      super(message, trace_id: trace_id)
     end
   end
 end

data/lib/private_captcha/verify_output.rb

@@ -33,28 +33,32 @@ module PrivateCaptcha
     }.freeze
 
     attr_accessor :success, :code, :origin, :timestamp
-    attr_reader :request_id, :attempt
+    attr_reader :trace_id, :attempt
 
-    def initialize(success: false, code: VERIFY_NO_ERROR, origin: nil, timestamp: nil, request_id: nil, attempt: 0)
+    def initialize(success: false, code: VERIFY_NO_ERROR, origin: nil, timestamp: nil, trace_id: nil, attempt: 0)
       @success = success
       @code = code
       @origin = origin
       @timestamp = timestamp
-      @request_id = request_id
+      @trace_id = trace_id
       @attempt = attempt
     end
 
+    def ok?
+      @success == true && @code == VERIFY_NO_ERROR
+    end
+
     def error_message
       ERROR_MESSAGES.fetch(@code, 'error')
     end
 
-    def self.from_json(json_data, request_id: nil, attempt: 0)
+    def self.from_json(json_data, trace_id: nil, attempt: 0)
       new(
         success: json_data['success'],
         code: json_data['code'] || VERIFY_NO_ERROR,
         origin: json_data['origin'],
         timestamp: json_data['timestamp'],
-        request_id: request_id,
+        trace_id: trace_id,
         attempt: attempt
       )
     end

data/lib/private_captcha/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PrivateCaptcha
-  VERSION = '0.0.2'
+  VERSION = '0.0.5'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: private_captcha
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.5
 platform: ruby
 authors:
 - Taras Kushnir
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-26 00:00:00.000000000 Z
+date: 2025-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -46,6 +46,7 @@ licenses:
 metadata:
   homepage_uri: https://privatecaptcha.com
   source_code_uri: https://github.com/PrivateCaptcha/private-captcha-ruby
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -61,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Ruby client for server-side Private Captcha API