io-complyance-unify-sdk 3.0.0

data/lib/complyance_sdk/models/source.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module ComplyanceSDK
+  module Models
+    # Source type enumeration
+    module SourceType
+      # First-party source
+      FIRST_PARTY = :first_party
+      
+      # Third-party source
+      THIRD_PARTY = :third_party
+      
+      # Marketplace source
+      MARKETPLACE = :marketplace
+      
+      # Get all valid source types
+      #
+      # @return [Array<Symbol>] All valid source types
+      def self.all
+        [FIRST_PARTY, THIRD_PARTY, MARKETPLACE]
+      end
+    end
+    
+    # Source model representing the origin of documents
+    class Source
+      # Source ID
+      attr_accessor :id
+      
+      # Source type
+      attr_accessor :type
+      
+      # Source name
+      attr_accessor :name
+      
+      # Source version
+      attr_accessor :version
+      
+      # Source metadata
+      attr_accessor :metadata
+      
+      # Initialize a new source
+      #
+      # @param options [Hash] Source options
+      # @option options [String] :id Source ID
+      # @option options [Symbol, String] :type Source type
+      # @option options [String] :name Source name
+      # @option options [String] :version Source version
+      # @option options [Hash] :metadata Source metadata
+      def initialize(options = {})
+        @id = options[:id]
+        @type = parse_source_type(options[:type])
+        @name = options[:name]
+        @version = options[:version]
+        @metadata = options[:metadata] || {}
+      end
+      
+      # Convert the source to a hash
+      #
+      # @return [Hash] The source as a hash
+      def to_h
+        {
+          name: @name,
+          version: @version,
+          type: @type.to_s.upcase,
+          identity: "#{@name}:#{@version}",
+          id: "#{@name}:#{@version}"
+        }
+      end
+      
+      # Convert the source to JSON
+      #
+      # @return [String] The source as JSON
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+      
+      # Check if the source is valid
+      #
+      # @return [Boolean] True if valid, false otherwise
+      def valid?
+        !@id.nil? && !@id.empty? &&
+          !@name.nil? && !@name.empty? &&
+          SourceType.all.include?(@type)
+      end
+      
+      private
+      
+      def parse_source_type(type)
+        return SourceType::FIRST_PARTY if type.nil?
+        
+        case type.to_s.downcase
+        when "first_party", "firstparty", "first-party"
+          SourceType::FIRST_PARTY
+        when "third_party", "thirdparty", "third-party"
+          SourceType::THIRD_PARTY
+        when "marketplace"
+          SourceType::MARKETPLACE
+        else
+          SourceType::FIRST_PARTY
+        end
+      end
+    end
+  end
+end

data/lib/complyance_sdk/models/source_ref.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module ComplyanceSDK
+  module Models
+    # Reference to a source using name and version (simplified identity)
+    # This replaces the need for source ID bookkeeping on the client side
+    class SourceRef
+      attr_reader :name, :version, :type
+
+      # Initialize a new source reference
+      #
+      # @param name [String] The source name
+      # @param version [String] The source version
+      # @param type [Symbol, String] The source type (defaults to :first_party)
+      # @raise [ArgumentError] If name or version is blank
+      def initialize(name, version, type = :first_party)
+        # Allow empty values for mapping purposes
+        @name = name.nil? ? '' : name.to_s.strip
+        @version = version.nil? ? '' : version.to_s.strip
+        @type = type
+      end
+
+      # Get the identity string (name:version)
+      #
+      # @return [String] The identity string
+      def identity
+        if @name.empty? && @version.empty?
+          "mapping:unknown"
+        else
+          "#{@name}:#{@version}"
+        end
+      end
+
+      # Convert to hash representation
+      #
+      # @return [Hash] Hash representation of the source reference
+      def to_h
+        {
+          name: @name,
+          version: @version,
+          type: @type.to_s.upcase,
+          identity: identity,
+          id: identity
+        }
+      end
+
+      # Convert to JSON-compatible hash (for API requests)
+      #
+      # @return [Hash] JSON-compatible hash
+      def to_json_hash
+        {
+          'name' => @name,
+          'version' => @version
+        }
+      end
+
+      # Create from hash
+      #
+      # @param hash [Hash] Hash with name and version keys
+      # @return [SourceRef] New source reference instance
+      def self.from_h(hash)
+        new(hash[:name] || hash['name'], hash[:version] || hash['version'])
+      end
+
+      # String representation
+      #
+      # @return [String] String representation
+      def to_s
+        identity
+      end
+
+      # Inspect representation
+      #
+      # @return [String] Inspect representation
+      def inspect
+        "#<#{self.class.name}:#{object_id} name=#{@name.inspect} version=#{@version.inspect}>"
+      end
+
+      # Equality comparison
+      #
+      # @param other [SourceRef] Other source reference to compare
+      # @return [Boolean] True if equal
+      def ==(other)
+        return false unless other.is_a?(SourceRef)
+        
+        @name == other.name && @version == other.version
+      end
+
+      # Hash code for equality
+      #
+      # @return [Integer] Hash code
+      def hash
+        [@name, @version].hash
+      end
+
+      # Alias for equality
+      alias_method :eql?, :==
+
+      # Validate the source reference
+      #
+      # @return [Boolean] True if valid
+      def valid?
+        !@name.empty? && !@version.empty?
+      end
+
+      # Get validation errors
+      #
+      # @return [Array<String>] Array of validation error messages
+      def validation_errors
+        errors = []
+        errors << 'Name cannot be blank' if @name.empty?
+        errors << 'Version cannot be blank' if @version.empty?
+        errors
+      end
+
+      # Check if source reference is valid, raise error if not
+      #
+      # @raise [ComplyanceSDK::Exceptions::ValidationError] If invalid
+      def validate!
+        return true if valid?
+        
+        error_message = validation_errors.join(', ')
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          "Invalid source reference: #{error_message}",
+          context: { name: @name, version: @version }
+        )
+      end
+    end
+  end
+end

data/lib/complyance_sdk/models/unify_request.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ComplyanceSDK
+  module Models
+    # UnifyRequest model representing the main API request structure
+    class UnifyRequest
+      # Source of the request
+      attr_accessor :source
+      
+      # Document type
+      attr_accessor :document_type
+      
+      # Country code
+      attr_accessor :country
+      
+      # Operation type
+      attr_accessor :operation
+      
+      # Mode
+      attr_accessor :mode
+      
+      # Purpose
+      attr_accessor :purpose
+      
+      # Request payload
+      attr_accessor :payload
+      
+      # Destinations
+      attr_accessor :destinations
+      
+      # Request metadata
+      attr_accessor :metadata
+
+      # Initialize a new UnifyRequest
+      #
+      # @param options [Hash] Request options
+      # @option options [Source] :source The source of the request
+      # @option options [Symbol, String] :document_type The document type
+      # @option options [String] :country The country code
+      # @option options [Symbol, String] :operation The operation type
+      # @option options [Symbol, String] :mode The mode
+      # @option options [Symbol, String] :purpose The purpose
+      # @option options [Hash] :payload The request payload
+      # @option options [Array] :destinations The destinations
+      # @option options [Hash] :metadata The request metadata
+      def initialize(options = {})
+        @source = options[:source]
+        @document_type = DocumentType.normalize(options[:document_type])
+        @country = options[:country]
+        @operation = Operation.normalize(options[:operation])
+        @mode = Mode.normalize(options[:mode])
+        @purpose = Purpose.normalize(options[:purpose])
+        @payload = options[:payload] || {}
+        @destinations = options[:destinations] || []
+        @metadata = build_metadata(options[:metadata] || {})
+      end
+
+      # Check if the request is valid
+      #
+      # @return [Boolean] True if valid, false otherwise
+      def valid?
+        errors.empty?
+      end
+
+      # Get validation errors
+      #
+      # @return [Array<String>] Array of validation error messages
+      def errors
+        errors = []
+        
+        errors << "Source is required" if @source.nil?
+        errors << "Source must be valid" if @source && !@source.valid?
+        errors << "Document type is required" if @document_type.nil?
+        errors << "Document type must be valid" unless DocumentType.valid?(@document_type)
+        errors << "Country is required" if @country.nil? || @country.empty?
+        errors << "Operation is required" if @operation.nil?
+        errors << "Operation must be valid" unless Operation.valid?(@operation)
+        errors << "Mode is required" if @mode.nil?
+        errors << "Mode must be valid" unless Mode.valid?(@mode)
+        errors << "Purpose is required" if @purpose.nil?
+        errors << "Purpose must be valid" unless Purpose.valid?(@purpose)
+        errors << "Payload is required" if @payload.nil? || @payload.empty?
+        
+        errors
+      end
+
+      # Convert the request to a hash
+      #
+      # @return [Hash] The request as a hash
+      def to_h
+        {
+          source: @source&.to_h,
+          country: @country.to_s.upcase,
+          operation: @operation.to_s.upcase,
+          mode: @mode.to_s.upcase,
+          payload: @payload,
+          apiKey: @metadata[:api_key],
+          requestId: @metadata[:request_id],
+          timestamp: @metadata[:timestamp],
+          env: @metadata[:environment],
+          destinations: format_destinations(@destinations),
+          correlationId: @metadata[:correlation_id],
+          documentType: @document_type.to_s.upcase,
+          purpose: @purpose.to_s.downcase
+        }
+      end
+
+      # Convert the request to JSON
+      #
+      # @return [String] The request as JSON
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      # Create a UnifyRequest from a hash
+      #
+      # @param hash [Hash] The hash to convert
+      # @return [UnifyRequest] The UnifyRequest object
+      def self.from_h(hash)
+        return nil unless hash.is_a?(Hash)
+        
+        options = hash.dup
+        
+        # Convert source hash to Source object if needed
+        if options[:source].is_a?(Hash)
+          options[:source] = Source.new(options[:source])
+        end
+        
+        new(options)
+      end
+
+      # Create a UnifyRequest from JSON
+      #
+      # @param json [String] The JSON string to convert
+      # @return [UnifyRequest] The UnifyRequest object
+      def self.from_json(json)
+        hash = JSON.parse(json, symbolize_names: true)
+        from_h(hash)
+      rescue JSON::ParserError => e
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          "Invalid JSON: #{e.message}",
+          context: { json: json }
+        )
+      end
+
+      private
+
+      def format_destinations(destinations)
+        return [] if destinations.nil? || destinations.empty?
+        
+        destinations.map do |dest|
+          # Handle both symbol and string keys
+          dest = dest.is_a?(Hash) ? dest : dest.to_h
+          
+          # Check if destination has nested details structure or flat structure
+          if dest.key?(:details) || dest.key?("details")
+            # Nested structure: {type: "...", details: {country: "...", authority: "...", document_type: "..."}}
+            details = dest[:details] || dest["details"] || {}
+            document_type = details[:document_type] || details["document_type"]
+          else
+            # Flat structure: {type: "...", country: "...", authority: "...", document_type: "..."}
+            details = dest
+            document_type = dest[:document_type] || dest["document_type"]
+          end
+          
+          # Map document_type to documentType based on the actual document type
+          # Logic: if it contains "credit" -> credit_note, if it contains "debit" -> debit_note, else tax_invoice
+          if document_type&.downcase&.include?("credit")
+            document_type = "credit_note"
+          elsif document_type&.downcase&.include?("debit")
+            document_type = "debit_note"
+          elsif document_type == "tax_invoice"
+            document_type = "tax_invoice"  # Keep as tax_invoice for regular invoices
+          end
+          
+          {
+            type: (dest[:type] || dest["type"])&.to_s&.upcase,
+            details: {
+              country: (details[:country] || details["country"])&.to_s,
+              authority: (details[:authority] || details["authority"])&.to_s,
+              documentType: document_type&.to_s
+            }
+          }
+        end
+      end
+
+      def build_metadata(metadata)
+        default_metadata = {
+          api_key: nil, # Will be set by the HTTP client
+          request_id: generate_request_id,
+          timestamp: Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ'),
+          environment: nil, # Will be set by the HTTP client
+          sdk_version: ComplyanceSDK::VERSION,
+          sdk_language: "ruby"
+        }
+        
+        default_metadata.merge(metadata)
+      end
+
+      def generate_request_id
+        require "securerandom"
+        SecureRandom.uuid
+      end
+    end
+  end
+end

data/lib/complyance_sdk/models/unify_response.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ComplyanceSDK
+  module Models
+    # UnifyResponse model representing the API response structure
+    class UnifyResponse
+      # Response status
+      attr_reader :status
+      
+      # Response message
+      attr_reader :message
+      
+      # Response data
+      attr_reader :data
+      
+      # Error details
+      attr_reader :error
+      
+      # Response metadata
+      attr_reader :metadata
+
+      # Initialize a new UnifyResponse
+      #
+      # @param options [Hash] Response options
+      # @option options [String] :status The response status
+      # @option options [String] :message The response message
+      # @option options [Hash] :data The response data
+      # @option options [Hash] :error The error details
+      # @option options [Hash] :metadata The response metadata
+      def initialize(options = {})
+        @status = options[:status]
+        @message = options[:message]
+        @data = options[:data]
+        @error = options[:error]
+        @metadata = options[:metadata] || {}
+      end
+
+      # Check if the response indicates success
+      #
+      # @return [Boolean] True if successful, false otherwise
+      def success?
+        (@status == "success" || @status == "completed") && !has_validation_errors?
+      end
+
+      # Check if the response indicates an error
+      #
+      # @return [Boolean] True if error, false otherwise
+      def error?
+        !success?
+      end
+
+      # Check if the response has validation errors
+      #
+      # @return [Boolean] True if validation errors exist, false otherwise
+      def has_validation_errors?
+        return false unless @data.is_a?(Hash)
+
+        validation_errors = @data.dig("validation", "errors") || @data.dig(:validation, :errors)
+        validation_errors.is_a?(Array) && !validation_errors.empty?
+      end
+
+      # Get validation errors from the response
+      #
+      # @return [Array] Array of validation error hashes
+      def validation_errors
+        return [] unless @data.is_a?(Hash)
+
+        validation_errors = @data.dig("validation", "errors") || @data.dig(:validation, :errors)
+        return [] unless validation_errors.is_a?(Array)
+
+        validation_errors
+      end
+
+      # Get the request ID from metadata
+      #
+      # @return [String, nil] The request ID
+      def request_id
+        @metadata[:request_id] || @metadata["request_id"]
+      end
+
+      # Get the processing time from metadata
+      #
+      # @return [Numeric, nil] The processing time in milliseconds
+      def processing_time
+        @metadata[:processing_time] || @metadata["processing_time"]
+      end
+
+      # Get the trace ID from metadata
+      #
+      # @return [String, nil] The trace ID
+      def trace_id
+        @metadata[:trace_id] || @metadata["trace_id"]
+      end
+
+      # Get the submission ID from data
+      # Checks multiple possible locations: data.submission_id, data.submission.submissionId, data.submission.submission_id
+      #
+      # @return [String, nil] The submission ID
+      def submission_id
+        return nil unless @data.is_a?(Hash)
+        
+        # Check direct submission_id
+        submission_id = @data[:submission_id] || @data["submission_id"]
+        return submission_id if submission_id
+        
+        # Check nested submission.submissionId or submission.submission_id
+        submission = @data[:submission] || @data["submission"]
+        return nil unless submission.is_a?(Hash)
+        
+        submission[:submissionId] || submission["submissionId"] || 
+        submission[:submission_id] || submission["submission_id"]
+      end
+
+      # Convert the response to a hash
+      #
+      # @return [Hash] The response as a hash
+      def to_h
+        {
+          status: @status,
+          message: @message,
+          data: @data,
+          error: @error,
+          metadata: @metadata
+        }
+      end
+
+      # Convert the response to JSON
+      #
+      # @return [String] The response as JSON
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      # Create a UnifyResponse from a hash
+      #
+      # @param hash [Hash] The hash to convert
+      # @return [UnifyResponse] The UnifyResponse object
+      def self.from_h(hash)
+        return nil unless hash.is_a?(Hash)
+        
+        # Convert string keys to symbol keys for consistency
+        normalized_hash = {}
+        hash.each do |key, value|
+          symbol_key = key.is_a?(String) ? key.to_sym : key
+          normalized_hash[symbol_key] = value
+        end
+        
+        new(normalized_hash)
+      end
+
+      # Create a UnifyResponse from JSON
+      #
+      # @param json [String] The JSON string to convert
+      # @return [UnifyResponse] The UnifyResponse object
+      def self.from_json(json)
+        hash = JSON.parse(json, symbolize_names: true)
+        from_h(hash)
+      rescue JSON::ParserError => e
+        raise ComplyanceSDK::Exceptions::ValidationError.new(
+          "Invalid JSON: #{e.message}",
+          context: { json: json }
+        )
+      end
+
+      # Create a success response
+      #
+      # @param data [Hash] The response data
+      # @param message [String] The success message
+      # @param metadata [Hash] The response metadata
+      # @return [UnifyResponse] The success response
+      def self.success(data = {}, message = "Success", metadata = {})
+        new(
+          status: "success",
+          message: message,
+          data: data,
+          metadata: metadata
+        )
+      end
+
+      # Create an error response
+      #
+      # @param error [Hash] The error details
+      # @param message [String] The error message
+      # @param metadata [Hash] The response metadata
+      # @return [UnifyResponse] The error response
+      def self.error(error = {}, message = "Error", metadata = {})
+        new(
+          status: "error",
+          message: message,
+          error: error,
+          metadata: metadata
+        )
+      end
+    end
+  end
+end