io-complyance-unify-sdk 3.0.0

data/lib/complyance_sdk/generators/config_generator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module ComplyanceSDK
+  module Generators
+    # Generator for creating ComplyanceSDK configuration files
+    class ConfigGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      
+      desc "Creates ComplyanceSDK configuration files"
+      
+      class_option :format, type: :string, default: "initializer", 
+                   desc: "Configuration format (initializer, yaml, credentials)"
+      
+      def create_config
+        case options[:format]
+        when "yaml"
+          create_yaml_config
+        when "credentials"
+          create_credentials_config
+        else
+          create_initializer_config
+        end
+      end
+      
+      private
+      
+      def create_initializer_config
+        template "complyance_initializer.rb", "config/initializers/complyance_sdk.rb"
+      end
+      
+      def create_yaml_config
+        template "complyance_config.yml", "config/complyance_sdk.yml"
+        create_file "config/initializers/complyance_sdk.rb", <<~RUBY
+          # frozen_string_literal: true
+          
+          # Load ComplyanceSDK configuration from YAML file
+          ComplyanceSDK.configure(
+            ComplyanceSDK::Config::SDKConfig.from_file(
+              Rails.root.join("config", "complyance_sdk.yml")
+            )
+          )
+        RUBY
+      end
+      
+      def create_credentials_config
+        say "To use Rails credentials for ComplyanceSDK configuration:"
+        say ""
+        say "1. Run: rails credentials:edit"
+        say "2. Add the following structure:"
+        say ""
+        say "complyance:"
+        say "  api_key: your_api_key_here"
+        say "  environment: sandbox"
+        say ""
+        
+        create_file "config/initializers/complyance_sdk.rb", <<~RUBY
+          # frozen_string_literal: true
+          
+          # Configure ComplyanceSDK from Rails credentials
+          ComplyanceSDK.configure_from_rails
+        RUBY
+      end
+    end
+  end
+end

data/lib/complyance_sdk/generators/install_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module ComplyanceSDK
+  module Generators
+    # Generator for installing ComplyanceSDK in a Rails application
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      
+      desc "Creates a ComplyanceSDK initializer for your Rails application"
+      
+      def copy_initializer
+        template "complyance_initializer.rb", "config/initializers/complyance_sdk.rb"
+      end
+      
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/complyance_sdk/generators/templates/complyance_initializer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# ComplyanceSDK configuration
+ComplyanceSDK.configure do |config|
+  # API key for authentication
+  # You can set this using Rails credentials:
+  # config.api_key = Rails.application.credentials.dig(:complyance, :api_key)
+  # Or using environment variables:
+  config.api_key = ENV["COMPLYANCE_API_KEY"]
+  
+  # Environment (sandbox, production)
+  # Default: :sandbox
+  config.environment = ENV.fetch("COMPLYANCE_ENVIRONMENT", "sandbox").to_sym
+  
+  # Add sources
+  # config.add_source(
+  #   ComplyanceSDK::Models::Source.new(
+  #     id: "my-erp-system",
+  #     type: :first_party,
+  #     name: "My ERP System",
+  #     version: "1.0"
+  #   )
+  # )
+  
+  # Configure retry behavior
+  # Default: RetryConfig.default
+  # config.retry_config = ComplyanceSDK::Config::RetryConfig.aggressive
+  
+  # Enable or disable logging
+  # Default: true
+  config.logging_enabled = true
+  
+  # Set log level (:debug, :info, :warn, :error)
+  # Default: :info
+  config.log_level = :info
+end

data/lib/complyance_sdk/http/authentication_middleware.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ComplyanceSDK
+  module HTTP
+    # Faraday middleware for API key authentication
+    class AuthenticationMiddleware < Faraday::Middleware
+      # Initialize the middleware
+      #
+      # @param app [Object] The Faraday app
+      # @param api_key [String] The API key
+      def initialize(app, api_key)
+        super(app)
+        @api_key = api_key
+      end
+
+      # Process the request
+      #
+      # @param env [Hash] The request environment
+      def call(env)
+        # Add API key to headers
+        env[:request_headers]["Authorization"] = "Bearer #{@api_key}"
+        env[:request_headers]["X-API-Key"] = @api_key
+        
+        # Add SDK identification headers
+        env[:request_headers]["User-Agent"] = "ComplyanceSDK-Ruby/#{ComplyanceSDK::VERSION}"
+        env[:request_headers]["X-SDK-Version"] = ComplyanceSDK::VERSION
+        env[:request_headers]["X-SDK-Language"] = "ruby"
+        
+        # Add request ID for tracing
+        env[:request_headers]["X-Request-ID"] = generate_request_id
+        
+        @app.call(env)
+      end
+
+      private
+
+      def generate_request_id
+        require "securerandom"
+        SecureRandom.uuid
+      end
+    end
+  end
+end

data/lib/complyance_sdk/http/client.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require_relative "authentication_middleware"
+require_relative "logging_middleware"
+
+module ComplyanceSDK
+  module HTTP
+    # HTTP client for making requests to the Complyance API
+    class Client
+      # Default timeout in seconds
+      DEFAULT_TIMEOUT = 30
+
+      # Initialize a new HTTP client
+      #
+      # @param config [ComplyanceSDK::Config::SDKConfig] The SDK configuration
+      def initialize(config)
+        @config = config
+        @connection = build_connection
+      end
+
+      # Make a POST request to the API
+      #
+      # @param path [String] The API path
+      # @param payload [Hash] The request payload
+      # @param headers [Hash] Additional headers
+      # @return [Hash] The response data
+      def post(path, payload = {}, headers = {})
+        # Get the full URL
+        base_url = ComplyanceSDK::Models::Environment.base_url(@config.environment)
+        full_url = "#{base_url}#{path}"
+        
+        # Log request details
+        puts "\n🌐 === API REQUEST ==="
+        puts "📍 URL: #{full_url}"
+        puts "📋 Headers: #{headers.merge('Content-Type' => 'application/json')}"
+        puts "📦 Payload:"
+        puts JSON.pretty_generate(payload)
+        puts "========================\n"
+        
+        response = @connection.post(path) do |req|
+          req.headers.merge!(headers)
+          req.headers["Content-Type"] = "application/json"
+          req.body = payload.to_json
+        end
+
+        # Log response details
+        puts "\n📥 === API RESPONSE ==="
+        puts "📊 Status: #{response.status}"
+        puts "📋 Headers: #{response.headers}"
+        puts "📦 Body:"
+        puts JSON.pretty_generate(response.body) if response.body
+        puts "========================\n"
+
+        handle_response(response)
+      rescue Faraday::Error => e
+        puts "\n❌ === API ERROR ==="
+        puts "🚨 Error: #{e.class.name}"
+        puts "📝 Message: #{e.message}"
+        puts "===================\n"
+        handle_faraday_error(e)
+      end
+
+      # Make a GET request to the API
+      #
+      # @param path [String] The API path
+      # @param params [Hash] Query parameters
+      # @param headers [Hash] Additional headers
+      # @return [Hash] The response data
+      def get(path, params = {}, headers = {})
+        response = @connection.get(path) do |req|
+          req.headers.merge!(headers)
+          req.params.merge!(params)
+        end
+
+        handle_response(response)
+      rescue Faraday::Error => e
+        handle_faraday_error(e)
+      end
+
+      private
+
+      def parse_response_body(body)
+        return body if body.is_a?(Hash)
+        return nil if body.nil? || body.empty?
+        
+        begin
+          JSON.parse(body, symbolize_names: true)
+        rescue JSON::ParserError
+          # If JSON parsing fails, return the original body
+          body
+        end
+      end
+
+      def build_connection
+        base_url = ComplyanceSDK::Models::Environment.base_url(@config.environment)
+        
+        Faraday.new(url: base_url) do |conn|
+          # Request middleware
+          conn.request :json
+          conn.request :retry, retry_options
+
+          # Authentication middleware
+          conn.use AuthenticationMiddleware, @config.api_key
+
+          # Logging middleware
+          if @config.logging_enabled
+            conn.use LoggingMiddleware, @config.log_level
+          end
+
+          # Response middleware
+          conn.response :json, content_type: /\bjson$/
+
+          # HTTP adapter
+          conn.adapter Faraday.default_adapter
+
+          # Timeouts
+          conn.options.timeout = DEFAULT_TIMEOUT
+          conn.options.open_timeout = DEFAULT_TIMEOUT / 2
+        end
+      end
+
+      def retry_options
+        {
+          max: @config.retry_config.max_attempts - 1, # Faraday counts retries, not total attempts
+          interval: @config.retry_config.base_delay,
+          max_interval: @config.retry_config.max_delay,
+          backoff_factor: @config.retry_config.backoff_multiplier,
+          retry_statuses: @config.retry_config.retryable_http_codes,
+          methods: [:get, :post, :put, :patch, :delete],
+          exceptions: [
+            Faraday::ConnectionFailed,
+            Faraday::TimeoutError,
+            Faraday::SSLError
+          ]
+        }
+      end
+
+      def handle_response(response)
+        # Parse response body if it's a JSON string
+        parsed_body = parse_response_body(response.body)
+        
+        case response.status
+        when 200..299
+          parsed_body || {}
+        when 400..499
+          error_message = parsed_body&.dig('message') || parsed_body&.dig('error_msg') || response.reason_phrase
+          raise ComplyanceSDK::Exceptions::APIError.new(
+            "Client error: #{error_message}",
+            status_code: response.status,
+            context: { response_body: parsed_body }
+          )
+        when 500..599
+          error_message = parsed_body&.dig('message') || parsed_body&.dig('error_msg') || response.reason_phrase
+          raise ComplyanceSDK::Exceptions::APIError.new(
+            "Server error: #{error_message}",
+            status_code: response.status,
+            context: { response_body: parsed_body }
+          )
+        else
+          error_message = parsed_body&.dig('message') || parsed_body&.dig('error_msg') || "Unexpected response"
+          raise ComplyanceSDK::Exceptions::APIError.new(
+            "#{error_message}: #{response.status}",
+            status_code: response.status,
+            context: { response_body: parsed_body }
+          )
+        end
+      end
+
+      def handle_faraday_error(error)
+        case error
+        when Faraday::ConnectionFailed
+          raise ComplyanceSDK::Exceptions::NetworkError.new(
+            "Connection failed: #{error.message}",
+            context: { original_error: error.class.name }
+          )
+        when Faraday::TimeoutError
+          raise ComplyanceSDK::Exceptions::NetworkError.new(
+            "Request timeout: #{error.message}",
+            context: { original_error: error.class.name }
+          )
+        when Faraday::SSLError
+          raise ComplyanceSDK::Exceptions::NetworkError.new(
+            "SSL error: #{error.message}",
+            context: { original_error: error.class.name }
+          )
+        else
+          # Handle Faraday::RetriableResponse (when retries are exhausted)
+          if error.class.name == "Faraday::RetriableResponse"
+            response = error.response
+            if response
+              # Check if this is a retryable error (5xx status codes) - matching Java SDK logic
+              # Access status code correctly from Faraday response object
+              status_code = response.respond_to?(:status) ? response.status : response[:status]
+              is_retryable = status_code && (status_code >= 500 || status_code == 429)
+              
+              # Get response body correctly
+              response_body = response.respond_to?(:body) ? response.body : response[:body]
+              reason_phrase = response.respond_to?(:reason_phrase) ? response.reason_phrase : response[:reason_phrase]
+              
+              raise ComplyanceSDK::Exceptions::APIError.new(
+                "Request failed after retries: #{response_body&.dig('message') || reason_phrase}",
+                status_code: status_code,
+                context: { 
+                  response_body: response_body, 
+                  retries_exhausted: true,
+                  retryable: is_retryable
+                }
+              )
+            end
+          end
+          
+          raise ComplyanceSDK::Exceptions::NetworkError.new(
+            "Network error: #{error.message}",
+            context: { original_error: error.class.name }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/complyance_sdk/http/logging_middleware.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module ComplyanceSDK
+  module HTTP
+    # Faraday middleware for request/response logging
+    class LoggingMiddleware < Faraday::Middleware
+      # Initialize the middleware
+      #
+      # @param app [Object] The Faraday app
+      # @param log_level [Symbol] The log level (:debug, :info, :warn, :error)
+      def initialize(app, log_level = :info)
+        super(app)
+        @log_level = log_level
+        @logger = Logger.new($stdout)
+        @logger.level = logger_level_constant(log_level)
+      end
+
+      # Process the request
+      #
+      # @param env [Hash] The request environment
+      def call(env)
+        start_time = Time.now
+        
+        log_request(env)
+        
+        @app.call(env).on_complete do |response_env|
+          end_time = Time.now
+          duration = ((end_time - start_time) * 1000).round(2)
+          
+          log_response(response_env, duration)
+        end
+      end
+
+      private
+
+      def log_request(env)
+        return unless should_log?(:info)
+
+        method = env[:method].to_s.upcase
+        url = env[:url].to_s
+        headers = sanitize_headers(env[:request_headers])
+        
+        @logger.info("ComplyanceSDK HTTP Request: #{method} #{url}")
+        @logger.debug("Request Headers: #{headers}") if should_log?(:debug)
+        
+        if env[:body] && should_log?(:debug)
+          body = sanitize_body(env[:body])
+          @logger.debug("Request Body: #{body}")
+        end
+      end
+
+      def log_response(env, duration)
+        return unless should_log?(:info)
+
+        status = env[:status]
+        url = env[:url].to_s
+        
+        @logger.info("ComplyanceSDK HTTP Response: #{status} #{url} (#{duration}ms)")
+        
+        if should_log?(:debug)
+          headers = sanitize_headers(env[:response_headers])
+          @logger.debug("Response Headers: #{headers}")
+          
+          if env[:body]
+            body = sanitize_body(env[:body])
+            @logger.debug("Response Body: #{body}")
+          end
+        end
+        
+        # Log errors at warn level
+        if status >= 400 && should_log?(:warn)
+          @logger.warn("ComplyanceSDK HTTP Error: #{status} #{url}")
+        end
+      end
+
+      def sanitize_headers(headers)
+        return {} unless headers
+
+        sanitized = headers.dup
+        
+        # Remove sensitive headers
+        %w[authorization x-api-key].each do |header|
+          if sanitized[header]
+            sanitized[header] = "[REDACTED]"
+          end
+        end
+        
+        sanitized
+      end
+
+      def sanitize_body(body)
+        return body unless body.is_a?(String)
+        
+        # Try to parse as JSON and sanitize
+        begin
+          parsed = JSON.parse(body)
+          sanitize_json_body(parsed).to_json
+        rescue JSON::ParserError
+          # If not JSON, return truncated body
+          body.length > 1000 ? "#{body[0..1000]}..." : body
+        end
+      end
+
+      def sanitize_json_body(data)
+        case data
+        when Hash
+          data.transform_values { |v| sanitize_json_body(v) }
+        when Array
+          data.map { |v| sanitize_json_body(v) }
+        when String
+          # Sanitize potential sensitive data
+          if data.match?(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/)
+            "[EMAIL_REDACTED]"
+          elsif data.match?(/\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/)
+            "[CARD_REDACTED]"
+          else
+            data
+          end
+        else
+          data
+        end
+      end
+
+      def should_log?(level)
+        level_value = logger_level_value(level)
+        current_level_value = logger_level_value(@log_level)
+        level_value >= current_level_value
+      end
+
+      def logger_level_value(level)
+        case level
+        when :debug then 0
+        when :info then 1
+        when :warn then 2
+        when :error then 3
+        else 1
+        end
+      end
+
+      def logger_level_constant(level)
+        case level
+        when :debug then Logger::DEBUG
+        when :info then Logger::INFO
+        when :warn then Logger::WARN
+        when :error then Logger::ERROR
+        else Logger::INFO
+        end
+      end
+    end
+  end
+end

data/lib/complyance_sdk/jobs/base_job.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module ComplyanceSDK
+  module Jobs
+    # Base job class for ComplyanceSDK background jobs
+    class BaseJob
+      # Include ActiveJob if available
+      if defined?(ActiveJob)
+        include ActiveJob::Base
+        
+        # Set default queue
+        queue_as :complyance_sdk
+        
+        # Configure retry behavior
+        retry_on ComplyanceSDK::Exceptions::NetworkError, wait: :exponentially_longer, attempts: 3
+        retry_on ComplyanceSDK::Exceptions::APIError, wait: :exponentially_longer, attempts: 2 do |job, error|
+          # Only retry certain API errors
+          error.status_code && [429, 500, 502, 503, 504].include?(error.status_code)
+        end
+        
+        # Don't retry configuration or validation errors
+        discard_on ComplyanceSDK::Exceptions::ConfigurationError
+        discard_on ComplyanceSDK::Exceptions::ValidationError
+      end
+
+      # Perform the job (to be overridden by subclasses)
+      #
+      # @param args [Array] Job arguments
+      def perform(*args)
+        raise NotImplementedError, "Subclasses must implement #perform"
+      end
+
+      private
+
+      # Get the configured SDK client
+      #
+      # @return [ComplyanceSDK::HTTP::Client] The HTTP client
+      def sdk_client
+        unless ComplyanceSDK.configured?
+          raise ComplyanceSDK::Exceptions::ConfigurationError.new(
+            "ComplyanceSDK is not configured for background jobs"
+          )
+        end
+
+        @sdk_client ||= ComplyanceSDK::HTTP::Client.new(ComplyanceSDK.configuration)
+      end
+
+      # Log job execution
+      #
+      # @param message [String] The log message
+      # @param level [Symbol] The log level
+      # @param context [Hash] Additional context
+      def log_job(message, level: :info, context: {})
+        return unless defined?(Rails) && Rails.logger
+
+        full_message = "ComplyanceSDK Job [#{self.class.name}]: #{message}"
+        full_message += " Context: #{context}" unless context.empty?
+
+        Rails.logger.send(level, full_message)
+      end
+    end
+  end
+end

data/lib/complyance_sdk/jobs/process_document_job.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "base_job"
+
+module ComplyanceSDK
+  module Jobs
+    # Background job for processing documents asynchronously
+    class ProcessDocumentJob < BaseJob
+      # Process a document in the background
+      #
+      # @param request_data [Hash] The UnifyRequest data
+      # @param callback_url [String, nil] Optional callback URL for results
+      # @param callback_headers [Hash] Optional headers for callback
+      def perform(request_data, callback_url = nil, callback_headers = {})
+        log_job("Starting document processing", context: { 
+          document_type: request_data["document_type"],
+          country: request_data["country"]
+        })
+
+        begin
+          # Process the document
+          response = sdk_client.post("/api/v1/unify", request_data)
+          
+          log_job("Document processed successfully", context: {
+            response_status: response["status"],
+            submission_id: response.dig("data", "submission_id")
+          })
+
+          # Send callback if provided
+          if callback_url
+            send_callback(callback_url, callback_headers, {
+              status: "success",
+              data: response,
+              request_id: request_data["metadata"]&.dig("request_id")
+            })
+          end
+
+          response
+        rescue => error
+          log_job("Document processing failed", level: :error, context: {
+            error_class: error.class.name,
+            error_message: error.message
+          })
+
+          # Send error callback if provided
+          if callback_url
+            send_callback(callback_url, callback_headers, {
+              status: "error",
+              error: {
+                code: error.respond_to?(:code) ? error.code : "unknown_error",
+                message: error.message
+              },
+              request_id: request_data["metadata"]&.dig("request_id")
+            })
+          end
+
+          raise error
+        end
+      end
+
+      private
+
+      def send_callback(url, headers, payload)
+        require "net/http"
+        require "uri"
+        require "json"
+
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        headers.each { |key, value| request[key] = value }
+        request.body = payload.to_json
+
+        response = http.request(request)
+        
+        log_job("Callback sent", context: {
+          callback_url: url,
+          callback_status: response.code,
+          payload_status: payload[:status]
+        })
+      rescue => error
+        log_job("Callback failed", level: :warn, context: {
+          callback_url: url,
+          error: error.message
+        })
+      end
+    end
+  end
+end