trustcaptcha 2.0.0 → 3.0.0.pre.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaf5bcc1921b15eec296ccaf839ecbbc4527c356f9822314f4beaa3ec09be86c
-  data.tar.gz: 35461f0e254f3ad67307ff161967325f01459fc08b9f83fc398854821ac9b1f8
+  metadata.gz: 10be47df90f618cc6611a61abc1a854103de387ab11485d5441792cb9020ef2b
+  data.tar.gz: d07f749734370f5389306497b494a0c4174a62a589a96642f12e5bff70ca9a56
 SHA512:
-  metadata.gz: df6669410e73265ef5352099d9df24c0f7d4b540ed44f8721f908b4e3632021640a562d689ee32d8a5926434eaf24f294a14d33dce92e43ebe82f1949c43b7b9
-  data.tar.gz: 51234139b348fec209f8e9e5e383c1fe29abd15b304485fc2b0706250cac5251385139e4e6403c7d108fa36c8b17bcfe8dd89d82485273a72044a324426ae983
+  metadata.gz: 9124e75c419119f80641dd7c4a7740359872e01ffc771c840caae4cb7be8035818d3cc158663b47787d889052567d92048fa8433872f1576d8f4e455262c0a8d
+  data.tar.gz: 5be40a6a066b02c720969460754a7a322f6beb31de61f3be9b4b133ded5e4a3a15279c6135b458eeb948586704f948b1accae85102d85c16b75c47456d774d89

data/lib/trustcaptcha/model/verification_result.rb

@@ -1,25 +1,35 @@
 require 'json'
 
 class VerificationResult
-  attr_reader :captcha_id, :verification_id, :score, :reason, :mode, :origin, :ip_address,
-              :device_family, :operating_system, :browser, :creation_timestamp,
-              :release_timestamp, :retrieval_timestamp, :verification_passed
+  attr_reader :captcha_id, :verification_id, :verification_passed, :score,
+              :decision_type, :decision_action, :gateway_failover_active,
+              :risk_scoring_enabled, :minimal_data_mode_enabled,
+              :origin, :ip_address, :country_code,
+              :device_family, :operating_system, :browser,
+              :verification_started_at, :verification_finished_at,
+              :result_expires_at, :result_first_fetched_at, :result_last_fetched_at
 
   def initialize(data)
     @captcha_id = data['captchaId']
     @verification_id = data['verificationId']
+    @verification_passed = data['verificationPassed']
     @score = data['score']
-    @reason = data['reason']
-    @mode = data['mode']
+    @decision_type = data['decisionType']
+    @decision_action = data['decisionAction']
+    @gateway_failover_active = data['gatewayFailoverActive']
+    @risk_scoring_enabled = data['riskScoringEnabled']
+    @minimal_data_mode_enabled = data['minimalDataModeEnabled']
     @origin = data['origin']
     @ip_address = data['ipAddress']
+    @country_code = data['countryCode']
     @device_family = data['deviceFamily']
     @operating_system = data['operatingSystem']
     @browser = data['browser']
-    @creation_timestamp = data['creationTimestamp']
-    @release_timestamp = data['releaseTimestamp']
-    @retrieval_timestamp = data['retrievalTimestamp']
-    @verification_passed = data['verificationPassed']
+    @verification_started_at = data['verificationStartedAt']
+    @verification_finished_at = data['verificationFinishedAt']
+    @result_expires_at = data['resultExpiresAt']
+    @result_first_fetched_at = data['resultFirstFetchedAt']
+    @result_last_fetched_at = data['resultLastFetchedAt']
   end
 
   def self.from_json(json_data)
@@ -31,18 +41,24 @@ class VerificationResult
     {
       captchaId: @captcha_id,
       verificationId: @verification_id,
+      verificationPassed: @verification_passed,
       score: @score,
-      reason: @reason,
-      mode: @mode,
+      decisionType: @decision_type,
+      decisionAction: @decision_action,
+      gatewayFailoverActive: @gateway_failover_active,
+      riskScoringEnabled: @risk_scoring_enabled,
+      minimalDataModeEnabled: @minimal_data_mode_enabled,
       origin: @origin,
       ipAddress: @ip_address,
+      countryCode: @country_code,
       deviceFamily: @device_family,
       operatingSystem: @operating_system,
       browser: @browser,
-      creationTimestamp: @creation_timestamp,
-      releaseTimestamp: @release_timestamp,
-      retrievalTimestamp: @retrieval_timestamp,
-      verificationPassed: @verification_passed
+      verificationStartedAt: @verification_started_at,
+      verificationFinishedAt: @verification_finished_at,
+      resultExpiresAt: @result_expires_at,
+      resultFirstFetchedAt: @result_first_fetched_at,
+      resultLastFetchedAt: @result_last_fetched_at
     }.to_json
   end
 end

data/lib/trustcaptcha/model/verification_token.rb

@@ -1,18 +1,20 @@
 require 'json'
-require 'securerandom'
 require 'base64'
 
 class VerificationToken
-  attr_reader :api_endpoint, :verification_id
+  attr_reader :verification_id, :client_failover
 
-  def initialize(api_endpoint, verification_id)
-    @api_endpoint = api_endpoint
+  def initialize(verification_id, client_failover = false)
     @verification_id = verification_id
+    @client_failover = client_failover
   end
 
   def self.from_base64(base64_string)
     json_string = Base64.decode64(base64_string)
     data = JSON.parse(json_string)
-    new(data['apiEndpoint'], data['verificationId'])
+    raise StandardError, 'Missing verificationId' if data['verificationId'].nil?
+    new(data['verificationId'], data['clientFailover'] == true)
+  rescue StandardError => e
+    raise e
   end
 end

data/lib/trustcaptcha/trust_captcha.rb

@@ -0,0 +1,98 @@
+require 'net/http'
+require 'uri'
+require 'json'
+require 'base64'
+require_relative 'model/verification_token'
+require_relative 'model/verification_result'
+
+class TrustCaptcha
+
+  LIBRARY_VERSION = '3.0.0'.freeze
+  LIBRARY_LANGUAGE = 'ruby'.freeze
+  DEFAULT_API_HOST = 'https://api.trustcomponent.com'.freeze
+  DEFAULT_CONNECT_TIMEOUT_S = 3
+  DEFAULT_READ_TIMEOUT_S = 5
+
+  class ApiKeyInvalidException < StandardError; end
+  class VerificationTokenInvalidException < StandardError; end
+  class VerificationNotFoundException < StandardError; end
+  class VerificationNotFinishedException < StandardError; end
+  class VerificationResultExpiredException < StandardError; end
+  class VerificationResultRetrievalLimitReachedException < StandardError; end
+  class FailoverException < StandardError; end
+  class ServerUnreachableException < FailoverException; end
+  class ClientReportedServerUnreachableException < FailoverException; end
+
+  def initialize(api_key,
+                 api_host: DEFAULT_API_HOST,
+                 connect_timeout_s: DEFAULT_CONNECT_TIMEOUT_S,
+                 read_timeout_s: DEFAULT_READ_TIMEOUT_S,
+                 proxy: nil)
+    raise ArgumentError, 'api_key must not be empty' if api_key.nil? || api_key.empty?
+    @api_key = api_key
+    @api_host = api_host
+    @connect_timeout_s = connect_timeout_s
+    @read_timeout_s = read_timeout_s
+    @proxy = proxy  # Either a URI string ("http://host:port[/]") or nil.
+  end
+
+  def get_verification_result(base64_verification_token)
+    verification_token = parse_verification_token(base64_verification_token)
+    query = verification_token.client_failover ? '?clientFailover=true' : ''
+    url = URI("#{@api_host}/v2/verifications/#{verification_token.verification_id}/results#{query}")
+    headers = {
+      'Authorization' => "Bearer #{@api_key}",
+      'User-Agent' => self.class.build_user_agent,
+    }
+
+    http = if @proxy
+             p = URI.parse(@proxy)
+             Net::HTTP.new(url.host, url.port, p.host, p.port, p.user, p.password)
+           else
+             Net::HTTP.new(url.host, url.port)
+           end
+    http.use_ssl = url.scheme == 'https'
+    http.open_timeout = @connect_timeout_s
+    http.read_timeout = @read_timeout_s
+
+    response = begin
+      request = Net::HTTP::Get.new(url.request_uri, headers)
+      http.request(request)
+    rescue SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Net::OpenTimeout, Net::ReadTimeout, Errno::ETIMEDOUT
+      raise ServerUnreachableException, 'Could not reach the TrustCaptcha server. This is a high-trust failover signal — your backend was unable to contact our servers.'
+    end
+
+    case response.code.to_i
+    when 403
+      raise ApiKeyInvalidException, 'The provided api key is invalid. Please verify the api key from your captcha settings.'
+    when 404
+      raise VerificationNotFoundException, 'No verification could be found for the given verification token.'
+    when 423
+      raise VerificationNotFinishedException, 'The verification is not yet completed. Please wait until the user has finished solving the captcha before requesting the result.'
+    when 410
+      raise VerificationResultExpiredException, 'The verification result has expired and can no longer be retrieved.'
+    when 412
+      raise ClientReportedServerUnreachableException, 'The client reported it could not reach the TrustCaptcha server, but the gateway has no record of a recent outage.'
+    when 429
+      raise VerificationResultRetrievalLimitReachedException, 'The verification result has reached its maximum retrieval count and can no longer be retrieved.'
+    else
+      raise "Failed to retrieve verification result: HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+    end
+
+    VerificationResult.from_json(response.body)
+  end
+
+  private
+
+  def parse_verification_token(base64_verification_token)
+    VerificationToken.from_base64(base64_verification_token)
+  rescue StandardError => e
+    raise VerificationTokenInvalidException, "The verification token is malformed or could not be parsed: #{e.message}"
+  end
+
+  def self.build_user_agent
+    payload = { 'language' => LIBRARY_LANGUAGE, 'version' => LIBRARY_VERSION }
+    encoded = Base64.strict_encode64(JSON.generate(payload))
+    "Trustcaptcha/#{encoded}"
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trustcaptcha
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0.pre.beta.1
 platform: ruby
 authors:
 - TrustComponent
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-06-17 00:00:00.000000000 Z
+date: 2026-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -46,9 +46,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/trustcaptcha/captcha_manager.rb
 - lib/trustcaptcha/model/verification_result.rb
 - lib/trustcaptcha/model/verification_token.rb
+- lib/trustcaptcha/trust_captcha.rb
 homepage: https://www.trustcomponent.com/en/products/captcha/integrations/ruby-captcha
 licenses:
 - Apache-2.0
@@ -65,9 +65,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.3.7
 signing_key: 

data/lib/trustcaptcha/captcha_manager.rb

@@ -1,49 +0,0 @@
-require 'net/http'
-require 'uri'
-require 'json'
-require_relative 'model/verification_token'
-require_relative 'model/verification_result'
-
-class CaptchaManager
-
-  class SecretKeyInvalidException < StandardError; end
-  class VerificationTokenInvalidException < StandardError; end
-  class VerificationNotFoundException < StandardError; end
-  class VerificationNotFinishedException < StandardError; end
-
-  def self.get_verification_result(secret_key, base64_verification_token)
-    verification_token = get_verification_token(base64_verification_token)
-    fetch_verification_result(verification_token, secret_key)
-  end
-
-  private
-
-  def self.get_verification_token(base64_verification_token)
-    VerificationToken.from_base64(base64_verification_token)
-  rescue StandardError => e
-    raise VerificationTokenInvalidException, "Invalid verification token: #{e.message}"
-  end
-
-  def self.fetch_verification_result(verification_token, access_token)
-    url = URI("#{verification_token.api_endpoint}/verifications/#{verification_token.verification_id}/assessments")
-    headers = {
-      "tc-authorization" => access_token,
-      "tc-library-language" => "ruby",
-      "tc-library-version" => "2.0"
-    }
-    response = Net::HTTP.get_response(url, headers)
-
-    case response.code.to_i
-    when 403
-      raise SecretKeyInvalidException, "Secret key is invalid"
-    when 404
-      raise VerificationNotFoundException, "Verification not found"
-    when 423
-      raise VerificationNotFinishedException, "Verification not finished"
-    else
-      raise "Failed to retrieve verification result: HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
-    end
-
-    VerificationResult.from_json(response.body)
-  end
-end