verifyo 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac05704ce88ba45eb262a5d4f80fa8ce3de8570a031590ec2fe23db8cb5d7099
+  data.tar.gz: f624b01558f456ee7ab2dbe8eb1fec3969d6bcdd50dc56e832685d1b4b20ca5e
+SHA512:
+  metadata.gz: 912764228a110380dfebc7584733845b04e33dd25d3fdef548f8ea16c4bd24b69769ae4790cdbc3de95006a6da76f9eb957e2a0a2deeb62ab93d6f44e36a74c1
+  data.tar.gz: de0db4d12fe9a280c5551317677e4d1c3600a5af6e34d2d7002bceea45ef17ece8daf08896da89895fc50107cda7751d3fd573a7e16c8121b141d0384e7d1511

data/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to the Verifyo Ruby SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-01-12
+
+### Added
+- Initial release of Verifyo Ruby SDK
+- Support for Ruby 2.7.0 and higher
+- `Verifyo::Client` class with `check_address` method
+- Comprehensive error handling with specific exception types:
+  - `AuthenticationError` for invalid API keys
+  - `RateLimitError` with usage metrics
+  - `ApiError` for general API errors
+  - `NetworkError` for connectivity issues
+- Ruby-idiomatic models with `?` methods:
+  - `CheckResponse` - Main response wrapper
+  - `VerificationResult` - Individual verification with convenience methods
+  - `WalletInfo` - Wallet risk assessment
+  - `AmlScreening` - AML compliance results
+  - `RateLimitInfo` - Rate limit tracking
+- Configuration management with global settings support
+- Computed properties for common compliance checks:
+  - `verified?` - Check if user has completed KYC
+  - `meets_basic_requirements?` - Verify user meets all compliance requirements
+  - `suitable_for_age_restricted_services?` - Check for 21+ services
+  - `passes_aml_screening?` - Verify AML compliance
+  - `safe_to_interact?` - Check wallet safety
+- Example applications and usage patterns
+- Comprehensive documentation
+
+### Features
+- Zero-Knowledge KYC verification
+- Multi-chain wallet support
+- AML/PEP screening results
+- Age verification (18+ and 21+)
+- Wallet risk assessment
+- Document country verification
+- Debug mode for development
+- Rate limit monitoring and warnings
+- Rails-ready integration
+
+[1.0.0]: https://github.com/verifyo-dot-com/verifyo-ruby-sdk/releases/tag/v1.0.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Verifyo.com
+
+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,402 @@
+# Verifyo Ruby SDK
+
+[![Gem Version](https://badge.fury.io/rb/verifyo.svg)](https://badge.fury.io/rb/verifyo)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Ruby SDK for the [Verifyo](https://verifyo.com) Zero-Knowledge KYC API. Verify wallet addresses for KYC compliance without exposing user personal data.
+
+## Features
+
+- ✅ **Zero-Knowledge Verification** - Check KYC status without accessing personal data
+- 🔒 **Type-Safe** - Comprehensive error handling with specific exception types
+- ⚡ **Lightweight** - Minimal dependencies, uses Faraday for HTTP
+- 📊 **Rate Limit Monitoring** - Built-in rate limit tracking and warnings
+- 🎯 **Ruby Idioms** - Follows Ruby conventions with `?` methods and snake_case
+- 🚀 **Rails Ready** - Easy integration with Ruby on Rails applications
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'verifyo'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install verifyo
+```
+
+## Quick Start
+
+```ruby
+require 'verifyo'
+
+# Initialize the client
+client = Verifyo::Client.new('vfy_sk_your_api_key')
+
+# Check a wallet address
+response = client.check_address('0x742d35...', network: 'ethereum')
+
+if response.has_results?
+  verification = response.first_result
+  
+  if verification.meets_basic_requirements?
+    puts "✅ User is KYC verified"
+    puts "KYC Level: #{verification.kyc_level}"
+    puts "Country: #{verification.document_country}"
+  end
+end
+```
+
+## Configuration
+
+### Direct Initialization
+
+```ruby
+client = Verifyo::Client.new(
+  'vfy_sk_your_api_key',
+  base_url: 'https://api.verifyo.com',  # Optional
+  timeout: 30,                          # Optional (seconds)
+  debug: true                            # Optional
+)
+```
+
+### Global Configuration
+
+```ruby
+# config/initializers/verifyo.rb (Rails)
+Verifyo.configure do |config|
+  config.api_key = ENV['VERIFYO_API_KEY']
+  config.timeout = 30
+  config.debug = Rails.env.development?
+end
+
+# Then use without API key
+client = Verifyo::Client.new(nil)  # Uses global config
+```
+
+## API Methods
+
+### check_address
+
+Check KYC verification status for a wallet address:
+
+```ruby
+# Check with network specification
+response = client.check_address(
+  '0x742d35...',
+  network: 'ethereum'  # Optional
+)
+
+# Check without network (auto-detection)
+response = client.check_address('3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy')
+```
+
+## Response Structure
+
+### CheckResponse
+
+The main response wrapper:
+
+```ruby
+if response.has_results?
+  puts "Found #{response.result_count} verification(s)"
+  
+  response.results.each do |result|
+    # Process each verification
+  end
+end
+
+# Check rate limits
+if response.rate_limit_info
+  rate_limit = response.rate_limit_info
+  puts "API Usage: #{rate_limit.used}/#{rate_limit.limit}"
+  
+  if rate_limit.near_limit?
+    puts "⚠️ Approaching rate limit!"
+  end
+end
+```
+
+### VerificationResult
+
+Individual verification details:
+
+```ruby
+verification = response.first_result
+
+# Basic properties
+puts "Status: #{verification.kyc_status}"
+puts "Level: #{verification.kyc_level}"
+puts "Country: #{verification.document_country || 'Not provided'}"
+
+# Age verification (Ruby style with ? methods)
+puts "Over 18: #{verification.age_over_18?}"
+puts "Over 21: #{verification.age_over_21?}"
+
+# Convenience methods
+if verification.verified?
+  puts "User has completed KYC"
+end
+
+if verification.meets_basic_requirements?
+  # User is verified, 18+, passes AML, and wallet is safe
+  puts "User meets all basic compliance requirements"
+end
+
+if verification.suitable_for_age_restricted_services?
+  # User is 21+ and not barred
+  puts "Suitable for gambling/alcohol services"
+end
+```
+
+### Wallet Information
+
+```ruby
+wallet = verification.wallet
+
+puts "Address: #{wallet.address}"
+puts "Ownership: #{wallet.ownership_status}"
+puts "Sanctioned: #{wallet.sanctioned?}"
+puts "High Risk: #{wallet.high_risk?}"
+
+if wallet.safe_to_interact?
+  puts "✅ Wallet is safe for transactions"
+end
+```
+
+### AML Screening
+
+```ruby
+aml = verification.aml
+
+puts "Sanctioned: #{aml.sanctioned?}"
+puts "PEP: #{aml.pep?}"
+puts "Criminal: #{aml.criminal?}"
+puts "Adverse Media: #{aml.adverse_media?}"
+
+if aml.passes_aml_screening?
+  puts "✅ Passes all AML checks"
+end
+
+if aml.clean?
+  puts "✅ No flags at all"
+end
+```
+
+## Error Handling
+
+The SDK provides specific exception types for different error scenarios:
+
+```ruby
+begin
+  response = client.check_address(address)
+  
+rescue Verifyo::AuthenticationError => e
+  # Invalid API key or authentication failure
+  puts "Authentication failed: #{e.message}"
+  
+rescue Verifyo::RateLimitError => e
+  # Rate limit exceeded
+  puts "Rate limit exceeded. Usage: #{e.used}/#{e.limit}"
+  puts "Tier: #{e.tier}"
+  puts "Resets at: #{e.resets_at}" if e.resets_at
+  
+rescue Verifyo::ApiError => e
+  # General API error
+  puts "API error (HTTP #{e.status_code}): #{e.message}"
+  
+rescue Verifyo::NetworkError => e
+  # Network connectivity issues
+  puts "Network error: #{e.message}"
+end
+```
+
+## Examples
+
+### Exchange Integration
+
+```ruby
+def can_user_trade?(wallet_address)
+  response = @verifyo_client.check_address(wallet_address)
+  
+  return false unless response.has_results?
+  
+  verification = response.first_result
+  
+  # Check trading requirements
+  verification.verified? &&
+    verification.age_over_18? &&
+    verification.aml.passes_aml_screening? &&
+    verification.wallet.safe_to_interact?
+    
+rescue Verifyo::Error => e
+  Rails.logger.error "Verifyo error: #{e.message}"
+  false  # Fail-safe: deny access on error
+end
+```
+
+### Age-Restricted Services
+
+```ruby
+def can_access_gambling?(wallet_address)
+  response = @verifyo_client.check_address(wallet_address)
+  
+  return false unless response.has_results?
+  
+  verification = response.first_result
+  
+  # Most gambling services require 21+
+  verification.verified? &&
+    verification.age_over_21? &&
+    !verification.aml.barred?
+end
+```
+
+### Batch Verification
+
+```ruby
+def verify_multiple_wallets(addresses)
+  results = {}
+  
+  addresses.each do |address|
+    begin
+      response = @verifyo_client.check_address(address)
+      results[address] = {
+        verified: response.has_verified_result?,
+        level: response.first_result&.kyc_level || 0,
+        country: response.first_result&.document_country
+      }
+      
+    rescue Verifyo::RateLimitError
+      # Handle rate limiting gracefully
+      sleep 10
+      retry
+      
+    rescue Verifyo::Error => e
+      results[address] = { error: e.message }
+    end
+  end
+  
+  results
+end
+```
+
+### Rails Controller Integration
+
+```ruby
+class VerificationController < ApplicationController
+  before_action :initialize_verifyo_client
+  
+  def check
+    response = @client.check_address(params[:address])
+    
+    if response.has_results?
+      verification = response.first_result
+      
+      render json: {
+        verified: verification.verified?,
+        kyc_level: verification.kyc_level,
+        meets_requirements: verification.meets_basic_requirements?,
+        country: verification.document_country
+      }
+    else
+      render json: { 
+        verified: false,
+        message: 'No KYC verification found' 
+      }, status: :not_found
+    end
+    
+  rescue Verifyo::AuthenticationError
+    render json: { error: 'Invalid API credentials' }, status: :unauthorized
+    
+  rescue Verifyo::RateLimitError => e
+    response.headers['X-RateLimit-Limit'] = e.limit.to_s
+    response.headers['X-RateLimit-Remaining'] = e.remaining.to_s
+    render json: { error: 'Rate limit exceeded' }, status: :too_many_requests
+    
+  rescue Verifyo::Error => e
+    render json: { error: e.message }, status: :bad_request
+  end
+  
+  private
+  
+  def initialize_verifyo_client
+    @client = Verifyo::Client.new(Rails.application.credentials.verifyo_api_key)
+  end
+end
+```
+
+### Background Job Processing
+
+```ruby
+class KycVerificationJob < ApplicationJob
+  queue_as :default
+  
+  def perform(wallet_address)
+    client = Verifyo::Client.new(ENV['VERIFYO_API_KEY'])
+    response = client.check_address(wallet_address)
+    
+    if response.has_results?
+      verification = response.first_result
+      
+      # Update user record
+      user = User.find_by(wallet_address: wallet_address)
+      user.update!(
+        kyc_verified: verification.verified?,
+        kyc_level: verification.kyc_level,
+        kyc_country: verification.document_country,
+        age_verified_18: verification.age_over_18?,
+        age_verified_21: verification.age_over_21?,
+        aml_passed: verification.aml.passes_aml_screening?
+      )
+    end
+    
+  rescue Verifyo::Error => e
+    Rails.logger.error "KYC verification failed for #{wallet_address}: #{e.message}"
+    raise  # Retry the job
+  end
+end
+```
+
+## Rails Generator (Coming Soon)
+
+Generate an initializer:
+
+```bash
+rails generate verifyo:install
+```
+
+This will create `config/initializers/verifyo.rb` with configuration template.
+
+## Best Practices
+
+1. **Use Environment Variables**: Store API keys in environment variables
+2. **Handle Rate Limits**: Implement exponential backoff when hitting rate limits
+3. **Fail-Safe**: Always deny access when verification fails or errors occur
+4. **Monitor Usage**: Check `rate_limit_info` to avoid hitting limits
+5. **Cache Results**: Consider caching verification results to reduce API calls
+6. **Log Errors**: Log all exceptions for debugging and monitoring
+
+## Requirements
+
+- Ruby 2.7.0 or higher
+- Valid Verifyo API key (starting with `vfy_sk_`)
+
+## Support
+
+- Documentation: https://verifyo.com/docs
+- Email: support@verifyo.com
+- GitHub Issues: https://github.com/verifyo-dot-com/verifyo-ruby-sdk/issues
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/verifyo/client.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Verifyo
+  # Main Verifyo SDK client for KYC verification checks
+  class Client
+    SDK_VERSION = VERSION
+
+    attr_reader :api_key, :base_url, :timeout, :debug
+
+    # Initialize a new Verifyo client
+    #
+    # @param api_key [String] Your Verifyo secret API key (must start with 'vfy_sk_')
+    # @param base_url [String] API base URL (defaults to https://api.verifyo.com)
+    # @param timeout [Integer] Request timeout in seconds (defaults to 30)
+    # @param debug [Boolean] Enable debug logging
+    #
+    # @raise [ArgumentError] if API key is invalid
+    def initialize(api_key, base_url: nil, timeout: nil, debug: false)
+      # Support configuration from global settings
+      config = Verifyo.configuration
+      
+      @api_key = api_key || config&.api_key
+      @base_url = base_url || config&.base_url || Configuration::DEFAULT_BASE_URL
+      @timeout = timeout || config&.timeout || Configuration::DEFAULT_TIMEOUT
+      @debug = debug || config&.debug || false
+
+      validate_api_key!
+      setup_connection
+    end
+
+    # Check KYC verification status for a wallet address
+    #
+    # @param address [String] Wallet address to check
+    # @param network [String, nil] Optional blockchain network (e.g., 'ethereum', 'bitcoin')
+    #
+    # @return [Models::CheckResponse] verification results and rate limit info
+    #
+    # @raise [AuthenticationError] if API key is invalid (401)
+    # @raise [RateLimitError] if rate limit is exceeded (429)
+    # @raise [ApiError] for other API errors
+    # @raise [NetworkError] for connectivity issues
+    #
+    # @example Check a Bitcoin address
+    #   response = client.check_address('3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy', network: 'bitcoin')
+    #   if response.has_results?
+    #     verification = response.first_result
+    #     puts "KYC Level: #{verification.kyc_level}" if verification.verified?
+    #   end
+    def check_address(address, network: nil)
+      raise ArgumentError, 'Address is required' if address.nil? || address.empty?
+
+      params = { address: address }
+      params[:network] = network if network
+
+      log_debug "Checking address: #{address} on network: #{network || 'auto-detect'}"
+
+      response = connection.get('/v1/check', params) do |req|
+        req.headers['Authorization'] = "Bearer #{api_key}"
+      end
+
+      log_debug "Response: #{response.status} - #{response.body}"
+
+      handle_response(response)
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+      raise NetworkError.new("Network error: #{e.message}", error: e.class.name)
+    rescue StandardError => e
+      raise unless e.is_a?(Verifyo::Error)
+      raise e
+    end
+
+    private
+
+    def validate_api_key!
+      raise ArgumentError, 'API key is required' if api_key.nil? || api_key.empty?
+      
+      unless api_key.start_with?('vfy_sk_')
+        raise ArgumentError, 'Invalid API key format. API key must start with "vfy_sk_"'
+      end
+    end
+
+    def setup_connection
+      @connection = Faraday.new(url: base_url) do |faraday|
+        faraday.request :json
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+        
+        faraday.options.timeout = timeout
+        faraday.options.open_timeout = timeout
+        
+        faraday.headers['User-Agent'] = "verifyo-ruby-sdk/#{SDK_VERSION} (Ruby #{RUBY_VERSION})"
+        faraday.headers['Accept'] = 'application/json'
+        faraday.headers['Content-Type'] = 'application/json'
+      end
+    end
+
+    def connection
+      @connection
+    end
+
+    def handle_response(response)
+      # Extract rate limit info from headers
+      rate_limit_info = extract_rate_limit_info(response.headers)
+
+      case response.status
+      when 200
+        Models::CheckResponse.new(response.body, rate_limit_info)
+      when 401
+        raise AuthenticationError.new(
+          extract_error_message(response.body),
+          status_code: response.status
+        )
+      when 429
+        handle_rate_limit_error(response.body, rate_limit_info)
+      when 400..499
+        raise ApiError.new(
+          extract_error_message(response.body),
+          response.status,
+          response_body: response.body
+        )
+      when 500..599
+        raise ApiError.new(
+          "Server error: #{extract_error_message(response.body)}",
+          response.status,
+          response_body: response.body
+        )
+      else
+        raise ApiError.new(
+          "Unexpected response: #{response.status}",
+          response.status,
+          response_body: response.body
+        )
+      end
+    end
+
+    def extract_rate_limit_info(headers)
+      return nil unless headers['x-ratelimit-limit']
+
+      Models::RateLimitInfo.new(
+        limit: headers['x-ratelimit-limit'].to_i,
+        used: headers['x-ratelimit-used'].to_i,
+        remaining: headers['x-ratelimit-remaining'].to_i,
+        tier: headers['x-ratelimit-tier'] || 'unknown'
+      )
+    end
+
+    def handle_rate_limit_error(body, rate_limit_info)
+      message = extract_error_message(body)
+      
+      if rate_limit_info
+        raise RateLimitError.new(
+          message,
+          limit: rate_limit_info.limit,
+          used: rate_limit_info.used,
+          remaining: rate_limit_info.remaining,
+          tier: rate_limit_info.tier,
+          resets_at: body.dig('resets_at'),
+          context: { response_body: body }
+        )
+      else
+        # Fallback if headers are missing
+        raise RateLimitError.new(
+          message,
+          limit: body.dig('limit') || 0,
+          used: body.dig('used') || 0,
+          remaining: body.dig('remaining') || 0,
+          tier: body.dig('tier') || 'unknown',
+          resets_at: body.dig('resets_at'),
+          context: { response_body: body }
+        )
+      end
+    end
+
+    def extract_error_message(body)
+      return 'Unknown error' unless body.is_a?(Hash)
+      
+      body.dig('error', 'message') || body['message'] || 'API error occurred'
+    end
+
+    def log_debug(message)
+      return unless debug
+      
+      puts "[Verifyo SDK] #{message}"
+    end
+  end
+end

data/lib/verifyo/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Verifyo
+  # Configuration class for SDK settings
+  class Configuration
+    DEFAULT_BASE_URL = 'https://api.verifyo.com'
+    DEFAULT_TIMEOUT = 30
+
+    attr_accessor :api_key, :base_url, :timeout, :debug
+
+    def initialize
+      @api_key = nil
+      @base_url = DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @debug = false
+    end
+
+    # Validate configuration
+    def validate!
+      raise ArgumentError, 'API key is required' if api_key.nil? || api_key.empty?
+      
+      unless api_key.start_with?('vfy_sk_')
+        raise ArgumentError, 'Invalid API key format. API key must start with "vfy_sk_"'
+      end
+    end
+  end
+end

data/lib/verifyo/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Verifyo
+  # Base error class for all Verifyo SDK errors
+  class Error < StandardError
+    attr_reader :context
+
+    def initialize(message = nil, context = {})
+      super(message)
+      @context = context
+    end
+  end
+
+  # Raised when authentication fails (401)
+  class AuthenticationError < Error
+    def initialize(message = 'Authentication failed. Please check your API key', context = {})
+      super(message, context)
+    end
+  end
+
+  # Raised when rate limit is exceeded (429)
+  class RateLimitError < Error
+    attr_reader :limit, :used, :remaining, :tier, :resets_at
+
+    def initialize(message, limit:, used:, remaining:, tier:, resets_at: nil, context: {})
+      super(message, context)
+      @limit = limit
+      @used = used
+      @remaining = remaining
+      @tier = tier
+      @resets_at = resets_at
+    end
+  end
+
+  # Raised for general API errors
+  class ApiError < Error
+    attr_reader :status_code
+
+    def initialize(message, status_code, context = {})
+      super(message, context)
+      @status_code = status_code
+    end
+  end
+
+  # Raised for network connectivity issues
+  class NetworkError < Error
+    def initialize(message = 'Network error occurred', context = {})
+      super(message, context)
+    end
+  end
+end

data/lib/verifyo/models/aml_screening.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Verifyo
+  module Models
+    # AML (Anti-Money Laundering) screening results
+    class AmlScreening
+      attr_reader :sanctioned, :pep, :criminal, :barred, :military, :adverse_media
+
+      def initialize(data)
+        @sanctioned = data['sanctioned'] || false
+        @pep = data['pep'] || false
+        @criminal = data['criminal'] || false
+        @barred = data['barred'] || false
+        @military = data['military'] || false
+        @adverse_media = data['adverse_media'] || false
+      end
+
+      # Check if user passes all AML screening checks
+      def passes_aml_screening?
+        !sanctioned && !criminal && !barred
+      end
+
+      # Check if user has any high-risk flags
+      def high_risk?
+        sanctioned || criminal || barred
+      end
+
+      # Check if user has any flags at all
+      def clean?
+        !sanctioned && !pep && !criminal && !barred && !military && !adverse_media
+      end
+
+      # Alias methods for Ruby convention
+      alias sanctioned? sanctioned
+      alias pep? pep
+      alias criminal? criminal
+      alias barred? barred
+      alias military? military
+      alias adverse_media? adverse_media
+
+      def to_h
+        {
+          sanctioned: sanctioned,
+          pep: pep,
+          criminal: criminal,
+          barred: barred,
+          military: military,
+          adverse_media: adverse_media
+        }
+      end
+    end
+  end
+end

data/lib/verifyo/models/check_response.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Verifyo
+  module Models
+    # Main response wrapper for KYC verification check
+    class CheckResponse
+      attr_reader :results, :rate_limit_info
+
+      def initialize(data, rate_limit_info = nil)
+        @results = (data['results'] || []).map { |result| VerificationResult.new(result) }
+        @rate_limit_info = rate_limit_info
+      end
+
+      # Check if any verification results were found
+      def has_results?
+        !results.empty?
+      end
+
+      # Get the first verification result
+      def first_result
+        results.first
+      end
+
+      # Get the number of verification results
+      def result_count
+        results.length
+      end
+
+      # Check if any result is verified
+      def has_verified_result?
+        results.any?(&:verified?)
+      end
+
+      # Get only verified results
+      def verified_results
+        results.select(&:verified?)
+      end
+
+      # Check if approaching rate limit
+      def approaching_rate_limit?
+        rate_limit_info&.near_limit? || false
+      end
+
+      def to_h
+        {
+          results: results.map(&:to_h),
+          rate_limit_info: rate_limit_info&.to_h
+        }
+      end
+    end
+  end
+end

data/lib/verifyo/models/rate_limit_info.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Verifyo
+  module Models
+    # Rate limit information from API response headers
+    class RateLimitInfo
+      attr_reader :limit, :used, :remaining, :tier
+
+      def initialize(limit:, used:, remaining:, tier:)
+        @limit = limit
+        @used = used
+        @remaining = remaining
+        @tier = tier
+      end
+
+      # Check if approaching rate limit (within 10%)
+      def near_limit?
+        return false if limit.zero?
+        
+        (used.to_f / limit) > 0.9
+      end
+
+      # Percentage of rate limit used
+      def usage_percentage
+        return 0.0 if limit.zero?
+        
+        (used.to_f / limit * 100).round(2)
+      end
+
+      def to_h
+        {
+          limit: limit,
+          used: used,
+          remaining: remaining,
+          tier: tier
+        }
+      end
+
+      def to_s
+        "#{used}/#{limit} (#{tier} tier)"
+      end
+    end
+  end
+end

data/lib/verifyo/models/verification_result.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Verifyo
+  module Models
+    # Individual KYC verification result for a wallet address
+    class VerificationResult
+      attr_reader :zk_kyc_token, :identity, :kyc_level, :kyc_status,
+                  :document_country, :residence_country,
+                  :age_over_18, :age_over_21, :wallet, :aml
+
+      def initialize(data)
+        @zk_kyc_token = data['zk_kyc_token'] || ''
+        @identity = data['identity'] || ''
+        @kyc_level = data['kyc_level'] || 0
+        @kyc_status = data['kyc_status'] || 'not_verified'
+        @document_country = data['document_country']
+        @residence_country = data['residence_country']
+        @age_over_18 = data['age_over_18'] || false
+        @age_over_21 = data['age_over_21'] || false
+        @wallet = WalletInfo.new(data['wallet'] || {})
+        @aml = AmlScreening.new(data['aml'] || {})
+      end
+
+      # Check if user is KYC verified
+      def verified?
+        kyc_status == 'verified'
+      end
+
+      # Check if user meets basic compliance requirements
+      # Returns true if user is:
+      # - KYC verified
+      # - Over 18 years old  
+      # - Passes AML screening
+      # - Has safe wallet (not sanctioned, not high risk)
+      def meets_basic_requirements?
+        verified? && age_over_18? && aml.passes_aml_screening? && wallet.safe_to_interact?
+      end
+
+      # Check if suitable for age-restricted services (21+)
+      def suitable_for_age_restricted_services?
+        verified? && age_over_21? && !aml.barred?
+      end
+
+      # Check if user has enhanced KYC (Level 2+)
+      def enhanced_kyc?
+        kyc_level >= 2
+      end
+
+      # Check if user has full KYC (Level 3)
+      def full_kyc?
+        kyc_level >= 3
+      end
+
+      # Alias methods for Ruby convention
+      alias age_over_18? age_over_18
+      alias age_over_21? age_over_21
+
+      def to_h
+        {
+          zk_kyc_token: zk_kyc_token,
+          identity: identity,
+          kyc_level: kyc_level,
+          kyc_status: kyc_status,
+          document_country: document_country,
+          residence_country: residence_country,
+          age_over_18: age_over_18,
+          age_over_21: age_over_21,
+          wallet: wallet.to_h,
+          aml: aml.to_h
+        }
+      end
+    end
+  end
+end

data/lib/verifyo/models/wallet_info.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Verifyo
+  module Models
+    # Wallet information and risk assessment
+    class WalletInfo
+      attr_reader :address, :ownership_status, :sanctioned, :high_risk
+
+      def initialize(data)
+        @address = data['address'] || ''
+        @ownership_status = data['ownership_status'] || 'unknown'
+        @sanctioned = data['sanctioned'] || false
+        @high_risk = data['high_risk'] || false
+      end
+
+      # Check if wallet is safe for transactions
+      def safe_to_interact?
+        !sanctioned && !high_risk
+      end
+
+      # Check if wallet ownership is verified
+      def ownership_verified?
+        ownership_status == 'verified'
+      end
+
+      # Check if wallet is self-declared
+      def self_declared?
+        ownership_status == 'self_declared'
+      end
+
+      # Alias methods for Ruby convention
+      alias sanctioned? sanctioned
+      alias high_risk? high_risk
+
+      def to_h
+        {
+          address: address,
+          ownership_status: ownership_status,
+          sanctioned: sanctioned,
+          high_risk: high_risk
+        }
+      end
+    end
+  end
+end

data/lib/verifyo/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Verifyo
+  VERSION = '1.0.0'
+end

data/lib/verifyo.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+require_relative 'verifyo/version'
+require_relative 'verifyo/configuration'
+require_relative 'verifyo/errors'
+require_relative 'verifyo/models/rate_limit_info'
+require_relative 'verifyo/models/aml_screening'
+require_relative 'verifyo/models/wallet_info'
+require_relative 'verifyo/models/verification_result'
+require_relative 'verifyo/models/check_response'
+require_relative 'verifyo/client'
+
+# Main module for Verifyo SDK
+module Verifyo
+  class << self
+    attr_accessor :configuration
+
+    # Configure the SDK
+    #
+    # @yield [Configuration] configuration object
+    # @example
+    #   Verifyo.configure do |config|
+    #     config.api_key = 'vfy_sk_your_api_key'
+    #     config.timeout = 30
+    #   end
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    # Reset configuration to defaults
+    def reset_configuration!
+      self.configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,187 @@
+--- !ruby/object:Gem::Specification
+name: verifyo
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Verifyo Team
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-09-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Verify wallet addresses for KYC compliance without exposing user personal
+  data. Check age verification, AML screening, and document verification status.
+email:
+- support@verifyo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/verifyo.rb
+- lib/verifyo/client.rb
+- lib/verifyo/configuration.rb
+- lib/verifyo/errors.rb
+- lib/verifyo/models/aml_screening.rb
+- lib/verifyo/models/check_response.rb
+- lib/verifyo/models/rate_limit_info.rb
+- lib/verifyo/models/verification_result.rb
+- lib/verifyo/models/wallet_info.rb
+- lib/verifyo/version.rb
+homepage: https://github.com/verifyo-dot-com/verifyo-ruby-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/verifyo-dot-com/verifyo-ruby-sdk
+  source_code_uri: https://github.com/verifyo-dot-com/verifyo-ruby-sdk
+  changelog_uri: https://github.com/verifyo-dot-com/verifyo-ruby-sdk/blob/main/CHANGELOG.md
+  documentation_uri: https://verifyo.com/docs
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for Verifyo Zero-Knowledge KYC API
+test_files: []