io-complyance-unify-sdk 3.0.0

data/lib/complyance_sdk.rb

@@ -0,0 +1,935 @@
+# frozen_string_literal: true
+
+require "complyance_sdk/version"
+require "complyance_sdk/config/sdk_config"
+require "complyance_sdk/models/source"
+require "complyance_sdk/models/source_ref"
+require "complyance_sdk/models/environment"
+require "complyance_sdk/models/document_type"
+require "complyance_sdk/models/logical_doc_type"
+require "complyance_sdk/models/country"
+require "complyance_sdk/models/policy_result"
+require "complyance_sdk/models/country_policy_registry"
+require "complyance_sdk/models/operation"
+require "complyance_sdk/models/mode"
+require "complyance_sdk/models/purpose"
+require "complyance_sdk/models/unify_request"
+require "complyance_sdk/models/unify_response"
+require "complyance_sdk/config/retry_config"
+require "complyance_sdk/exceptions/sdk_exception"
+require "complyance_sdk/exceptions/circuit_breaker_open_error"
+# require "complyance_sdk/middleware/rack_middleware" # Removed - not needed
+require "complyance_sdk/http/client"
+# require "complyance_sdk/retry/retry_manager" # Removed - not needed
+require "complyance_sdk/retry/circuit_breaker"
+require "complyance_sdk/retry/retry_strategy"
+require "complyance_sdk/queue/persistent_queue_manager"
+
+# Main module for the Complyance SDK
+module ComplyanceSDK
+  class << self
+    attr_accessor :configuration
+
+    # Configure the SDK with the provided configuration
+    #
+    # @param config [ComplyanceSDK::Config::SDKConfig] The configuration object
+    # @yield [config] Yields the configuration object for block-style configuration
+    # @return [ComplyanceSDK::Config::SDKConfig] The configuration object
+    def configure(config = nil)
+      self.configuration = config if config.is_a?(ComplyanceSDK::Config::SDKConfig)
+      
+      if block_given?
+        self.configuration ||= ComplyanceSDK::Config::SDKConfig.new
+        yield(configuration)
+      end
+      
+      configuration
+    end
+
+    # Configure the SDK from environment variables
+    #
+    # @return [ComplyanceSDK::Config::SDKConfig] The configuration object
+    def configure_from_env
+      self.configuration = ComplyanceSDK::Config::SDKConfig.from_env
+    end
+
+    # Configure the SDK from Rails credentials
+    #
+    # @param environment [Symbol] The Rails environment (:development, :production, etc.)
+    # @return [ComplyanceSDK::Config::SDKConfig] The configuration object
+    def configure_from_rails(environment = nil)
+      self.configuration = ComplyanceSDK::Config::SDKConfig.from_rails(environment)
+    end
+    
+    # Check if the SDK is configured
+    #
+    # @return [Boolean] True if the SDK is configured, false otherwise
+    def configured?
+      !configuration.nil? && configuration.valid?
+    end
+
+    # Get the retry manager instance
+    #
+    # @param redis_config [Hash] Optional Redis configuration
+    # @return [ComplyanceSDK::Retry::RetryManager] The retry manager
+    def retry_manager(redis_config = {})
+      @retry_manager ||= ComplyanceSDK::Retry::RetryManager.new(configuration, redis_config)
+    end
+
+    # Execute an operation with retry logic
+    #
+    # @param operation_name [String] Name of the operation
+    # @param context [Hash] Context information
+    # @yield The block to execute
+    # @return The result of the block
+    def with_retry(operation_name, context = {})
+      unless configured?
+        raise ComplyanceSDK::Exceptions::ConfigurationError.new(
+          "SDK must be configured before using retry functionality"
+        )
+      end
+
+      retry_manager.execute(operation_name, context) { yield }
+    end
+
+    # Main API method for document processing (Java-style signature)
+    #
+    # @param source_name [String] The source name
+    # @param source_version [String] The source version
+    # @param logical_doc_type [Symbol] The logical document type
+    # @param country [Symbol] The country code
+    # @param operation [Symbol] The operation type
+    # @param mode [Symbol] The mode
+    # @param purpose [Symbol] The purpose
+    # @param payload [Hash] The business data payload
+    # @param destinations [Array, nil] Optional destinations (auto-generated if nil)
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response object
+    def push_to_unify(source_name, source_version, logical_doc_type, country, operation, mode, purpose, payload, destinations = nil)
+      unless configured?
+        raise ComplyanceSDK::Exceptions::ConfigurationError.new(
+          "SDK must be configured before making API calls"
+        )
+      end
+
+      # Process queued submissions first before handling new requests
+      process_queued_submissions_first
+
+      # Validate required parameters
+      validate_required_parameter(source_name, :source_name, "Source name is required")
+      validate_required_parameter(source_version, :source_version, "Source version is required")
+      validate_required_parameter(logical_doc_type, :logical_doc_type, "Logical document type is required")
+      validate_required_parameter(country, :country, "Country is required")
+      validate_required_parameter(operation, :operation, "Operation is required")
+      validate_required_parameter(mode, :mode, "Mode is required")
+      validate_required_parameter(purpose, :purpose, "Purpose is required")
+      validate_required_parameter(payload, :payload, "Payload is required")
+
+      # Validate country restrictions for current environment
+      validate_country_for_environment(country, configuration.environment)
+
+      # Evaluate country policy to get base document type and meta.config flags
+      policy = ComplyanceSDK::Models::CountryPolicyRegistry.evaluate(country, logical_doc_type)
+
+      # Merge meta.config flags into payload
+      merged_payload = deep_merge_into_meta_config(payload, policy.get_meta_config_flags)
+
+      # Auto-set invoice_data.document_type based on LogicalDocType
+      set_invoice_data_document_type(merged_payload, logical_doc_type)
+
+      # Create source reference with type from configuration
+      source_type = find_source_type(source_name, source_version)
+      source_ref = ComplyanceSDK::Models::SourceRef.new(source_name, source_version, source_type)
+
+      # Auto-generate destinations if none provided and auto-generation is enabled
+      final_destinations = destinations || (configuration.auto_generate_tax_destination? ? 
+                                          generate_default_destinations(country, policy.get_document_type) : [])
+      
+      # Extract destinations from payload if they exist there
+      if final_destinations.empty? && merged_payload.is_a?(Hash) && merged_payload['destinations']
+        final_destinations = merged_payload['destinations']
+        # Remove destinations from payload to avoid duplication
+        merged_payload = merged_payload.dup
+        merged_payload.delete('destinations')
+      end
+
+      # Build and send request using the resolved base document type
+      push_to_unify_internal_with_document_type(
+        source_ref,
+        policy.base_document_type,
+        ComplyanceSDK::Models::LogicalDocType.meta_config_document_type(logical_doc_type),
+        country,
+        operation,
+        mode,
+        purpose,
+        merged_payload,
+        final_destinations
+      )
+    end
+
+    # Push to Unify API with logical document types using JSON string payload
+    #
+    # @param source_name [String] The source name
+    # @param source_version [String] The source version
+    # @param logical_doc_type [Symbol] The logical document type
+    # @param country [Symbol] The country code
+    # @param operation [Symbol] The operation type
+    # @param mode [Symbol] The mode
+    # @param purpose [Symbol] The purpose
+    # @param json_payload [String] The JSON string payload
+    # @param destinations [Array, nil] Optional destinations (auto-generated if nil)
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response object
+    def push_to_unify_from_json(source_name, source_version, logical_doc_type, country, operation, mode, purpose, json_payload, destinations = nil)
+      if json_payload.nil? || json_payload.to_s.strip.empty?
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          "Payload is required but was null or empty",
+          context: { 
+            suggestion: 'Provide a non-empty JSON payload string. Example: \'{"invoiceNumber":"INV-123","amount":1000}\''
+          }
+        )
+      end
+
+      begin
+        require 'json'
+        payload_hash = JSON.parse(json_payload)
+        
+        unless payload_hash.is_a?(Hash)
+          raise ComplyanceSDK::Exceptions::ValidationError.new(
+            "Failed to parse JSON payload: parsed result is not a hash",
+            context: { 
+              suggestion: 'Ensure the payload is valid JSON and represents an object structure. Example: \'{"invoiceNumber":"INV-123"}\''
+            }
+          )
+        end
+
+        push_to_unify(source_name, source_version, logical_doc_type, country, operation, mode, purpose, payload_hash, destinations)
+      rescue JSON::ParserError => parse_error
+        payload_snippet = json_payload.length > 100 ? json_payload[0..99] + '...' : json_payload
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          "Failed to parse JSON payload: #{parse_error.message}",
+          context: { 
+            suggestion: 'Ensure the payload is valid JSON. Example: \'{"invoiceNumber":"INV-123","amount":1000}\'',
+            payload_snippet: payload_snippet,
+            parse_error: parse_error.message
+          }
+        )
+      rescue ComplyanceSDK::Exceptions::ValidationError
+        raise
+      rescue StandardError => conversion_error
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          "Failed to parse JSON payload: #{conversion_error.message}",
+          context: { 
+            suggestion: 'Ensure the payload is valid JSON. Example: \'{"invoiceNumber":"INV-123","amount":1000}\'',
+            conversion_error: conversion_error.message
+          }
+        )
+      end
+    end
+
+    # Push to Unify API with logical document types using object payload
+    #
+    # @param source_name [String] The source name
+    # @param source_version [String] The source version
+    # @param logical_doc_type [Symbol] The logical document type
+    # @param country [Symbol] The country code
+    # @param operation [Symbol] The operation type
+    # @param mode [Symbol] The mode
+    # @param purpose [Symbol] The purpose
+    # @param payload_object [Object] The object payload (any object that responds to to_h or has instance variables)
+    # @param destinations [Array, nil] Optional destinations (auto-generated if nil)
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response object
+    def push_to_unify_from_object(source_name, source_version, logical_doc_type, country, operation, mode, purpose, payload_object, destinations = nil)
+      if payload_object.nil?
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          "Payload object is required but was nil",
+          context: { 
+            suggestion: "Provide a valid payload object. Example: {invoice_number: 'INV-123', amount: 1000}"
+          }
+        )
+      end
+
+      begin
+        # Convert object to hash
+        payload_hash = if payload_object.is_a?(Hash)
+                         payload_object
+                       elsif payload_object.respond_to?(:to_h)
+                         payload_object.to_h
+                       elsif payload_object.respond_to?(:instance_variables)
+                         # Convert object instance variables to hash
+                         hash = {}
+                         payload_object.instance_variables.each do |var|
+                           key = var.to_s.delete('@')
+                           hash[key] = payload_object.instance_variable_get(var)
+                         end
+                         hash
+                       else
+                         # Try JSON serialization for other objects
+                         require 'json'
+                         json_str = payload_object.to_json
+                         JSON.parse(json_str)
+                       end
+
+        unless payload_hash.is_a?(Hash)
+          raise ComplyanceSDK::Exceptions::ValidationError.new(
+            "Failed to convert payload object to hash: conversion returned invalid result",
+            context: { 
+              suggestion: "Ensure the object structure is compatible with the SDK payload format. " +
+                         "The object should be convertible to a hash structure."
+            }
+          )
+        end
+
+        push_to_unify(source_name, source_version, logical_doc_type, country, operation, mode, purpose, payload_hash, destinations)
+      rescue ComplyanceSDK::Exceptions::ValidationError
+        raise
+      rescue StandardError => conversion_error
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          "Failed to convert payload object to hash: #{conversion_error.message}",
+          context: { 
+            suggestion: "Ensure the object structure is compatible with the SDK payload format. " +
+                       "The object should be convertible to a hash. " +
+                       "Example: {invoice_number: 'INV-123', amount: 1000} or a class with public attributes.",
+            object_type: payload_object.class.name,
+            conversion_error: conversion_error.message
+          }
+        )
+      end
+    end
+
+    # Main API method for document processing (UnifyRequest object)
+    #
+    # @param request [ComplyanceSDK::Models::UnifyRequest, Hash] The request object or hash
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response object
+    def push_to_unify_request(request)
+      unless configured?
+        raise ComplyanceSDK::Exceptions::ConfigurationError.new(
+          "SDK must be configured before making API calls"
+        )
+      end
+
+      # Convert hash to UnifyRequest if needed
+      if request.is_a?(Hash)
+        request = ComplyanceSDK::Models::UnifyRequest.from_h(request)
+      end
+
+      # Validate the request
+      unless request.valid?
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          "Invalid request: #{request.errors.join(', ')}",
+          context: { errors: request.errors }
+        )
+      end
+
+      # Make the API call with retry logic
+      response_data = with_retry("push_to_unify", { request_id: request.metadata[:request_id] }) do
+        http_client.post("", request.to_h)
+      end
+
+      # Convert response to UnifyResponse object
+      ComplyanceSDK::Models::UnifyResponse.from_h(response_data)
+    end
+
+    # Convenience method for submitting invoices
+    #
+    # @param options [Hash] Invoice submission options
+    # @option options [String] :country Country code
+    # @option options [Hash] :payload Invoice payload
+    # @option options [ComplyanceSDK::Models::Source] :source Source information
+    # @option options [Symbol] :document_type Document type (default: :tax_invoice)
+    # @option options [Symbol] :purpose Purpose (default: :invoicing)
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response object
+    def submit_invoice(options = {})
+      request = ComplyanceSDK::Models::UnifyRequest.new(
+        source: options[:source] || default_source,
+        document_type: options[:document_type] || :tax_invoice,
+        country: options[:country],
+        operation: :single,
+        mode: :documents,
+        purpose: options[:purpose] || :invoicing,
+        payload: options[:payload]
+      )
+
+      push_to_unify(request)
+    end
+
+    # Convenience method for creating field mappings
+    #
+    # @param options [Hash] Mapping options
+    # @option options [String] :country Country code
+    # @option options [Hash] :payload Sample payload for mapping
+    # @option options [ComplyanceSDK::Models::Source] :source Source information
+    # @option options [Symbol] :document_type Document type (default: :tax_invoice)
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response object
+    def create_mapping(options = {})
+      request = ComplyanceSDK::Models::UnifyRequest.new(
+        source: options[:source] || default_source,
+        document_type: options[:document_type] || :tax_invoice,
+        country: options[:country],
+        operation: :single,
+        mode: :documents,
+        purpose: :mapping,
+        payload: options[:payload]
+      )
+
+      push_to_unify(request)
+    end
+
+    # Get the status of a submission
+    #
+    # @param submission_id [String] The submission ID
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response object
+    def get_status(submission_id)
+      unless configured?
+        raise ComplyanceSDK::Exceptions::ConfigurationError.new(
+          "SDK must be configured before making API calls"
+        )
+      end
+
+      response_data = with_retry("get_status", { submission_id: submission_id }) do
+        http_client.get("/api/v1/submissions/#{submission_id}")
+      end
+
+      ComplyanceSDK::Models::UnifyResponse.from_h(response_data)
+    end
+
+    # Process a document asynchronously using background jobs
+    #
+    # @param request [ComplyanceSDK::Models::UnifyRequest, Hash] The request object or hash
+    # @param options [Hash] Background job options
+    # @option options [Symbol] :job_type Job type (:active_job or :sidekiq)
+    # @option options [String] :callback_url Optional callback URL
+    # @option options [Hash] :callback_headers Optional callback headers
+    # @return [String, Object] Job ID or job object
+    def push_to_unify_async(request, options = {})
+      unless configured?
+        raise ComplyanceSDK::Exceptions::ConfigurationError.new(
+          "SDK must be configured before making API calls"
+        )
+      end
+
+      # Convert hash to UnifyRequest if needed
+      if request.is_a?(Hash)
+        request = ComplyanceSDK::Models::UnifyRequest.from_h(request)
+      end
+
+      # Validate the request
+      unless request.valid?
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          "Invalid request: #{request.errors.join(', ')}",
+          context: { errors: request.errors }
+        )
+      end
+
+      retry_manager.execute_async(
+        request.to_h,
+        job_type: options[:job_type] || :active_job,
+        callback_url: options[:callback_url],
+        callback_headers: options[:callback_headers] || {}
+      )
+    end
+
+    # Push to Unify API with logical document types but full control over operation, mode, and purpose
+    # This is the primary method for all workflows with logical document types
+    #
+    # @param source_name [String] The source name
+    # @param source_version [String] The source version
+    # @param logical_type [Symbol] The logical document type
+    # @param country [Symbol] The country code
+    # @param operation [Symbol] The operation type
+    # @param mode [Symbol] The mode
+    # @param purpose [Symbol] The purpose
+    # @param payload [Hash] The business data payload
+    # @param destinations [Array, nil] Optional destinations (auto-generated if nil)
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response object
+    def push_to_unify_logical(source_name, source_version, logical_type, country, operation, mode, purpose, payload, destinations = nil)
+      unless configured?
+        raise ComplyanceSDK::Exceptions::ConfigurationError.new(
+          "SDK must be configured before making API calls"
+        )
+      end
+
+      # Process queued submissions first before handling new requests
+      process_queued_submissions_first
+
+      # Validate required parameters
+      # Handle source_name and source_version based on purpose
+      final_source_name = if purpose == :mapping
+                            # For MAPPING purpose, source_name and source_version are optional
+                            source_name || ""
+                          else
+                            # For all other purposes, source_name is mandatory
+                            if source_name.nil? || source_name.to_s.strip.empty?
+                              raise ComplyanceSDK::Exceptions::ValidationError.new(
+                                "Source name is required",
+                                context: { field: :source_name }
+                              )
+                            end
+                            source_name
+                          end
+
+      final_source_version = if purpose == :mapping
+                               # For MAPPING purpose, source_version is optional
+                               source_version || ""
+                             else
+                               # For all other purposes, source_version is mandatory
+                               if source_version.nil? || source_version.to_s.strip.empty?
+                                 raise ComplyanceSDK::Exceptions::ValidationError.new(
+                                   "Source version is required",
+                                   context: { field: :source_version }
+                                 )
+                               end
+                               source_version
+                             end
+
+      # Validate other required parameters
+      validate_required_parameter(logical_type, :logical_type, "Logical document type is required")
+      validate_required_parameter(country, :country, "Country is required")
+      validate_required_parameter(operation, :operation, "Operation is required")
+      validate_required_parameter(mode, :mode, "Mode is required")
+      validate_required_parameter(purpose, :purpose, "Purpose is required")
+      validate_required_parameter(payload, :payload, "Payload is required")
+
+      # Validate country restrictions for current environment
+      validate_country_for_environment(country, configuration.environment)
+
+      # Evaluate country policy to get base document type and meta.config flags
+      policy = ComplyanceSDK::Models::CountryPolicyRegistry.evaluate(country, logical_type)
+
+      # Merge meta.config flags into payload
+      merged_payload = deep_merge_into_meta_config(payload, policy.get_meta_config_flags)
+
+      # Auto-set invoice_data.document_type based on LogicalDocType
+      set_invoice_data_document_type(merged_payload, logical_type)
+
+      # Create source reference with type from configuration
+      source_type = find_source_type(final_source_name, final_source_version)
+      source_ref = ComplyanceSDK::Models::SourceRef.new(final_source_name, final_source_version, source_type)
+
+      # Auto-generate destinations if none provided and auto-generation is enabled
+      final_destinations = destinations || (configuration.auto_generate_tax_destination? ? 
+                                          generate_default_destinations(country, policy.get_document_type) : [])
+
+      # Build and send request using the resolved base document type
+      push_to_unify_internal_with_document_type(
+        source_ref,
+        policy.base_document_type,
+        ComplyanceSDK::Models::LogicalDocType.meta_config_document_type(logical_type),
+        country,
+        operation,
+        mode,
+        purpose,
+        merged_payload,
+        final_destinations
+      )
+    end
+
+    # Push to Unify API with logical document types using SourceRef
+    #
+    # @param source_ref [ComplyanceSDK::Models::SourceRef] The source reference
+    # @param logical_type [Symbol] The logical document type
+    # @param country [Symbol] The country code
+    # @param operation [Symbol] The operation type
+    # @param mode [Symbol] The mode
+    # @param purpose [Symbol] The purpose
+    # @param payload [Hash] The business data payload
+    # @param destinations [Array, nil] Optional destinations
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response object
+    def push_to_unify_with_source_ref(source_ref, logical_type, country, operation, mode, purpose, payload, destinations = nil)
+      push_to_unify_logical(
+        source_ref.name,
+        source_ref.version,
+        logical_type,
+        country,
+        operation,
+        mode,
+        purpose,
+        payload,
+        destinations
+      )
+    end
+
+    # Convenience method to submit invoices with logical document types
+    #
+    # @param source_name [String] The source name
+    # @param source_version [String] The source version
+    # @param country [Symbol] The country code
+    # @param logical_type [Symbol] The logical document type
+    # @param payload [Hash] The business data payload
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response object
+    def submit_invoice_logical(source_name, source_version, country, logical_type, payload)
+      push_to_unify_logical(
+        source_name,
+        source_version,
+        logical_type,
+        country,
+        :single,
+        :documents,
+        :invoicing,
+        payload
+      )
+    end
+
+    # Convenience method to create mappings with logical document types
+    #
+    # @param source_name [String] The source name
+    # @param source_version [String] The source version
+    # @param country [Symbol] The country code
+    # @param logical_type [Symbol] The logical document type
+    # @param payload [Hash] The business data payload
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response object
+    def create_mapping_logical(source_name, source_version, country, logical_type, payload)
+      push_to_unify_logical(
+        source_name,
+        source_version,
+        logical_type,
+        country,
+        :single,
+        :documents,
+        :mapping,
+        payload
+      )
+    end
+
+    # Get queue status and statistics
+    #
+    # @return [Hash] Queue status information
+    def queue_status
+      if queue_manager
+        queue_manager.queue_status
+      else
+        { error: "Queue Manager is not initialized" }
+      end
+    end
+
+    # Get detailed queue status
+    #
+    # @return [Hash] Detailed queue status information
+    def detailed_queue_status
+      queue_status
+    end
+
+    # Retry failed submissions
+    def retry_failed_submissions
+      queue_manager&.retry_failed_submissions
+    end
+
+    # Clean up old success files
+    #
+    # @param days_to_keep [Integer] Number of days to keep success files
+    def cleanup_old_success_files(days_to_keep)
+      queue_manager&.cleanup_old_success_files(days_to_keep)
+    end
+
+    # Clear all files from the queue (emergency cleanup)
+    def clear_all_queues
+      if queue_manager
+        queue_manager.clear_all_queues
+      else
+        raise ComplyanceSDK::Exceptions::ConfigurationError.new("Queue Manager is not initialized")
+      end
+    end
+
+    # Clean up duplicate files across queue directories
+    def cleanup_duplicate_files
+      if queue_manager
+        queue_manager.cleanup_duplicate_files
+      else
+        raise ComplyanceSDK::Exceptions::ConfigurationError.new("Queue Manager is not initialized")
+      end
+    end
+
+    # Process pending submissions now
+    def process_pending_submissions
+      queue_manager&.process_pending_submissions_now
+    end
+
+    # Process queued submissions before handling new requests
+    def process_queued_submissions_first
+      if queue_manager
+        puts "🔥 QUEUE: Processing queued submissions first"
+        queue_manager.process_pending_submissions_now
+      end
+    end
+
+    private
+
+    # Get the HTTP client instance
+    #
+    # @return [ComplyanceSDK::HTTP::Client] The HTTP client
+    def http_client
+      @http_client ||= ComplyanceSDK::HTTP::Client.new(configuration)
+    end
+
+    # Get the default source from configuration
+    #
+    # @return [ComplyanceSDK::Models::Source, nil] The default source
+    def default_source
+      configuration.sources.first
+    end
+
+    # Find source type by name and version from configuration
+    #
+    # @param name [String] The source name
+    # @param version [String] The source version
+    # @return [Symbol] The source type (defaults to :first_party)
+    def find_source_type(name, version)
+      configured_source = configuration.sources.find do |source|
+        source.name == name && source.version == version
+      end
+      
+      configured_source&.type || :first_party
+    end
+
+    # Get the queue manager instance
+    #
+    # @return [ComplyanceSDK::Queue::PersistentQueueManager, nil] The queue manager
+    def queue_manager
+      return nil unless configuration
+
+      @queue_manager ||= ComplyanceSDK::Queue::PersistentQueueManager.new(
+        configuration.api_key,
+        configuration.environment == ComplyanceSDK::Models::Environment::LOCAL
+      )
+    end
+
+    # Validate required parameter
+    #
+    # @param value [Object] The value to validate
+    # @param field [Symbol] The field name
+    # @param message [String] The error message
+    def validate_required_parameter(value, field, message)
+      if value.nil?
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          message,
+          context: { field: field }
+        )
+      end
+    end
+
+    # Validate country restrictions based on current environment
+    #
+    # @param country [Symbol] The country
+    # @param environment [Symbol] The environment
+    def validate_country_for_environment(country, environment)
+      unless ComplyanceSDK::Models::Country.allowed_for_environment?(country, environment)
+        error_message = ComplyanceSDK::Models::Country.validation_error_message(country, environment)
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          "Country not allowed for environment: #{error_message}",
+          context: { country: country, environment: environment }
+        )
+      end
+    end
+
+    # Deep merge meta.config flags into payload
+    # User values take precedence over policy defaults
+    #
+    # @param payload [Hash] The original payload
+    # @param config_flags [Hash] The config flags to merge
+    # @return [Hash] The merged payload
+    def deep_merge_into_meta_config(payload, config_flags)
+      merged = payload.dup
+      
+      meta = merged[:meta] || merged['meta'] || {}
+      config = meta[:config] || meta['config'] || {}
+      
+      # Merge config flags (user values take precedence)
+      merged_config = config_flags.merge(config)
+      
+      meta[:config] = merged_config
+      merged[:meta] = meta
+      
+      merged
+    end
+
+    # Auto-set invoice_data.document_type based on LogicalDocType
+    #
+    # @param payload [Hash] The payload to modify
+    # @param logical_type [Symbol] The logical document type
+    def set_invoice_data_document_type(payload, logical_type)
+      return unless payload
+
+      invoice_data = payload[:invoice_data] || payload['invoice_data']
+      return unless invoice_data
+
+      # Determine document type string based on LogicalDocType
+      document_type = ComplyanceSDK::Models::LogicalDocType.invoice_data_document_type(logical_type)
+
+      # Set the document_type field (use string key for consistency)
+      invoice_data['document_type'] = document_type
+    end
+
+    # Generate default destinations for a country and document type
+    #
+    # @param country [Symbol] The country
+    # @param document_type [String] The document type
+    # @return [Array] Array of destinations
+    def generate_default_destinations(country, document_type)
+      destinations = []
+
+      # Auto-generate tax authority destination
+      authority = ComplyanceSDK::Models::Country.default_tax_authority(country)
+      if authority
+        destinations << {
+          type: :tax_authority,
+          country: country.to_s.upcase,
+          authority: authority,
+          document_type: document_type
+        }
+      end
+
+      destinations
+    end
+
+    # Internal method to push to Unify API with custom document type string
+    #
+    # @param source_ref [ComplyanceSDK::Models::SourceRef] The source reference
+    # @param base_document_type [Symbol] The base document type
+    # @param document_type_string [String] The custom document type string
+    # @param country [Symbol] The country
+    # @param operation [Symbol] The operation
+    # @param mode [Symbol] The mode
+    # @param purpose [Symbol] The purpose
+    # @param payload [Hash] The payload
+    # @param destinations [Array] The destinations
+    # @return [ComplyanceSDK::Models::UnifyResponse] The response
+    def push_to_unify_internal_with_document_type(source_ref, base_document_type, document_type_string, country, operation, mode, purpose, payload, destinations)
+      # Create UnifyRequest using the model
+      request = ComplyanceSDK::Models::UnifyRequest.new(
+        source: source_ref,
+        document_type: base_document_type,
+        country: country,
+        operation: operation,
+        mode: mode,
+        purpose: purpose,
+        payload: payload,
+        destinations: destinations,
+        metadata: {
+          api_key: configuration.api_key,
+          request_id: "req_#{Time.now.to_i}_#{rand}",
+          timestamp: Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ'),
+          environment: ComplyanceSDK::Models::Environment.to_api_value(configuration.environment),
+          correlation_id: configuration.correlation_id
+        }
+      )
+
+      # Convert to hash for API call
+      request_data = request.to_h
+
+      begin
+        # Use circuit breaker if configured
+        if configuration.retry_config&.circuit_breaker_enabled?
+          circuit_breaker = ComplyanceSDK::Retry::CircuitBreaker.new(
+            configuration.retry_config.circuit_breaker_config
+          )
+          
+          return circuit_breaker.execute do
+            http_client.post('', request_data)
+          end
+        else
+          return http_client.post('', request_data)
+        end
+      rescue ComplyanceSDK::Exceptions::CircuitBreakerOpenError => e
+        # Circuit breaker is open - queue the request
+        puts "🚫 Circuit breaker is OPEN - queuing request for retry"
+        
+        if queue_manager
+          complete_request_json = JSON.generate(request_data)
+          submission = {
+            payload: complete_request_json,
+            source: { id: source_ref.identity },
+            country: country,
+            document_type: base_document_type
+          }
+          
+          queue_manager.enqueue(submission)
+          
+          return {
+            status: 'queued',
+            message: "Circuit breaker is open - request queued for retry. Submission ID: #{request_data[:request_id]}",
+            data: {
+              submission: {
+                submission_id: request_data[:request_id]
+              }
+            }
+          }
+        else
+          raise e
+        end
+      rescue ComplyanceSDK::Exceptions::SDKException => e
+        puts "🔥 QUEUE: SDKException caught - Error: #{e.message}, ServerError: #{server_error?(e)}, QueueManager: #{!queue_manager.nil?}"
+
+        # Check if the error is a 500-range server error and queue is enabled
+        if server_error?(e) && queue_manager
+          # Store the complete UnifyRequest as JSON to maintain exact API format
+          complete_request_json = JSON.generate(request_data)
+          puts "🔥 QUEUE: Successfully converted complete UnifyRequest to JSON with length: #{complete_request_json.length}"
+          puts "🔥 QUEUE: Complete request JSON preview: #{complete_request_json[0..199]}"
+
+          # Create a submission for the queue
+          submission = {
+            payload: complete_request_json,
+            source: { id: source_ref.identity },
+            country: country,
+            document_type: base_document_type
+          }
+
+          puts "🔥 QUEUE: Created submission with complete request length: #{submission[:payload].length}"
+
+          # Enqueue the failed submission for background retry
+          queue_manager.enqueue(submission)
+
+          # Return a response indicating the submission was queued
+          return {
+            status: 'queued',
+            message: "Request failed but has been queued for retry. Submission ID: #{request_data[:request_id]}",
+            data: {
+              submission: {
+                submission_id: request_data[:request_id]
+              }
+            }
+          }
+        end
+
+        # If not a server error or queue not available, re-throw the exception
+        raise e
+      end
+    end
+
+    # Determines if an SDK exception represents a server error (500-range HTTP status codes).
+    # Only 500-range errors (500-599) should trigger queue access.
+    #
+    # @param exception [ComplyanceSDK::Exceptions::SDKException] The SDK exception
+    # @return [Boolean] True if it's a 500-range HTTP error; otherwise, false
+    def server_error?(exception)
+      return false unless exception.context
+
+      # Check HTTP status code in context
+      http_status_obj = exception.context[:http_status] || exception.context['httpStatus']
+      if http_status_obj
+        begin
+          status_code = http_status_obj.to_i
+          
+          # Only 500-range errors (500-599) should trigger queue access
+          is_server_status = status_code >= 500 && status_code < 600
+          if !is_server_status
+            puts "HTTP status #{status_code} detected (non 500-range) - skipping queue"
+          else
+            puts "Server error detected from HTTP status: #{status_code}"
+          end
+          return is_server_status
+        rescue StandardError => ex
+          puts "Invalid HTTP status format: #{http_status_obj}"
+          # Ignore invalid status
+        end
+      else
+        puts "No httpStatus in exception context, not counting as server error"
+      end
+
+      # Fallback: use error codes only when HTTP status is unavailable
+      error_code = exception.context[:error_code] || exception.context['error_code']
+      return error_code == 'INTERNAL_SERVER_ERROR' || error_code == 'SERVICE_UNAVAILABLE'
+    end
+  end
+end
+
+# Rails integration - removed railtie
+# require "complyance_sdk/railtie" if defined?(Rails)