connect-sdk-ruby 1.0.0

data/lib/ingenico/connect/sdk/exceptions.rb

@@ -0,0 +1,8 @@
+prefix = 'ingenico/connect/sdk/'
+suffix = '_exception'
+exception_types = %w[api authorization communication declined_transaction
+                    declined_payment declined_payout declined_refund
+                    global_collect idempotence marshaller_syntax not_found
+                    reference response validation]
+
+exception_types.each { |type| require prefix + type + suffix }

data/lib/ingenico/connect/sdk/factory.rb

@@ -0,0 +1,200 @@
+require 'yaml'
+
+module Ingenico::Connect::SDK
+
+  # Convenience class that constructs instances of several other classes in the SDK.
+  # Provides methods to construct
+  # {Ingenico::Connect::SDK::CommunicatorConfiguration}, {Ingenico::Connect::SDK::Session}, {Ingenico::Connect::SDK::Communicator} and {Ingenico::Connect::SDK::Client} instances.
+  class Factory
+
+    # Creates and returns a {Ingenico::Connect::SDK::CommunicatorConfiguration} based on the configuration in the file
+    # located at _configuration_file_name_.
+    #
+    # configuration_file_name:: Path to the configuration file to use, should be in YAML format.
+    # api_key_id::              Key id for the GlobalCollect service.
+    # secret_api_key::          Secret key used for authentication to the GlobalCollect service.
+    def self.create_configuration(configuration_file_name, api_key_id, secret_api_key)
+        properties = YAML::load_file(configuration_file_name)
+        CommunicatorConfiguration.new(properties: properties,
+                                             api_key_id: api_key_id,
+                                             secret_api_key: secret_api_key)
+    end
+
+    # Creates and returns a {Ingenico::Connect::SDK::Session} from an {Ingenico::Connect::SDK::CommunicatorConfiguration}, an {Ingenico::Connect::SDK::MetaDataProvider},
+    # an {Ingenico::Connect::SDK::Connection} and an {Ingenico::Connect::SDK::Authenticator}.
+    # If an authenticator is not given, a {Ingenico::Connect::SDK::DefaultImpl::DefaultAuthenticator} is created
+    # using the _api_key_id_ and _secret_api_key_ in the CommunicatorConfiguration.
+    #
+    # configuration::           {Ingenico::Connect::SDK::CommunicatorConfiguration} that contains configuration settings
+    #                           to be used by the client.
+    # meta_data_provider::      {Ingenico::Connect::SDK::MetaDataProvider} that stores the metadata for the communicating client.
+    # connection::              Implementation of {Ingenico::Connect::SDK::Connection} that can be used to communicate
+    #                           with the GlobalCollect Platform.
+    # authenticator::           Implementation of {Ingenico::Connect::SDK::Authenticator} that can authenticate messages
+    #                           sent to the GlobalCollect platform.
+    def self.create_session_from_configuration(configuration, meta_data_provider: nil,
+                                               connection: nil, authenticator: nil)
+      unless meta_data_provider
+        meta_data_provider = MetaDataProvider.new(configuration.integrator,
+                                                  shopping_cart_extension: configuration.shopping_cart_extension)
+      end
+      unless connection
+        connection = DefaultImpl::DefaultConnection.new({connect_timeout: configuration.connect_timeout,
+                                                        socket_timeout: configuration.socket_timeout,
+                                                        max_connections: configuration.max_connections,
+                                                        proxy_configuration: configuration.proxy_configuration})
+      end
+      unless authenticator
+        authenticator = DefaultImpl::DefaultAuthenticator.new(configuration.authorization_type,
+                                                 configuration.api_key_id, configuration.secret_api_key)
+      end
+      Session.new(configuration.api_endpoint, connection, authenticator, meta_data_provider)
+    end
+
+    # Creates and returns a {Ingenico::Connect::SDK::Session} from a file containing the communicator configuration, api_key_id, secret_api_key,
+    # an {Ingenico::Connect::SDK::MetaDataProvider}, an {Ingenico::Connect::SDK::Connection} and an {Ingenico::Connect::SDK::Authenticator}.
+    # If an authenticator is not given, a {Ingenico::Connect::SDK::DefaultImpl::DefaultAuthenticator} is created
+    # using the _api_key_id_ and _secret_api_key_ in the CommunicatorConfiguration.
+    #
+    # configuration_file_name:: Path to the configuration file to use, should be in YAML format.
+    # api_key_id::              Key id for the GlobalCollect service.
+    # secret_api_key::          Secret key used for authentication to the GlobalCollect service.
+    # meta_data_provider::      {Ingenico::Connect::SDK::MetaDataProvider} that stores the metadata for the communicating client.
+    # connection::              Implementation of {Ingenico::Connect::SDK::Connection} that can be used to communicate
+    #                           with the GlobalCollect Platform.
+    # authenticator::           Implementation of {Ingenico::Connect::SDK::Authenticator} that can authenticate messages
+    #                           sent to the GlobalCollect platform.
+    def self.create_session_from_file(configuration_file_name, api_key_id, secret_api_key,
+                                      meta_data_provider: nil, connection: nil, authenticator: nil)
+      configuration = create_configuration(configuration_file_name, api_key_id, secret_api_key)
+      create_session_from_configuration(configuration, meta_data_provider: meta_data_provider, connection: connection,
+                                        authenticator: authenticator)
+    end
+
+    # Creates and returns an {Ingenico::Connect::SDK::Communicator} that is used for communication with the GlobalCollect service.
+    #
+    # session::                 {Ingenico::Connect::SDK::Session} that the communicator will utilize for communication.
+    def self.create_communicator_from_session(session)
+      Communicator.new(session, DefaultImpl::DefaultMarshaller.INSTANCE)
+    end
+
+    # Creates and returns an {Ingenico::Connect::SDK::Communicator} that can be used for communication with the GlobalCollect service.
+    #
+    # configuration::           {Ingenico::Connect::SDK::CommunicatorConfiguration} that contains configuration settings
+    #                           to be used by the client.
+    def self.create_communicator_from_configuration(configuration)
+      session = create_session_from_configuration(configuration)
+      Communicator.new(session, DefaultImpl::DefaultMarshaller.INSTANCE)
+    end
+
+    # Creates and returns an {Ingenico::Connect::SDK::Communicator} that is used for communication with the GlobalCollect service.
+    #
+    # configuration_file_name:: Path to the configuration file to use, should be in YAML format.
+    # api_key_id::              Key id for the GlobalCollect service.
+    # secret_api_key::          Secret key used for authentication to the GlobalCollect service.
+    def self.create_communicator_from_file(configuration_file_name, api_key_id, secret_api_key)
+      configuration = create_configuration(configuration_file_name, api_key_id, secret_api_key)
+      session = create_session_from_configuration(configuration)
+      Communicator.new(session, DefaultImpl::DefaultMarshaller.INSTANCE)
+    end
+
+    # Creates and returns an {Ingenico::Connect::SDK::Client} that provides the a high-level interface with the GlobalCollect service.
+    # If a code block is given, the created client is returned to the code block and closed afterwards.
+    #
+    # @example Providing a code block
+    #           Factory.create_client_from_configuration(configuration) do |client|
+    #             client.merchant(merchant_id).services.testconnection
+    #           end
+    #           # client is closed here
+    #
+    # configuration::           {Ingenico::Connect::SDK::CommunicatorConfiguration} that contains configuration settings
+    #                           to be used by the client.
+    def self.create_client_from_configuration(configuration)
+      communicator = create_communicator_from_configuration(configuration)
+      client = Client.new(communicator)
+      if block_given?
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      else
+        return client
+      end
+    end
+
+    # Creates and returns an {Ingenico::Connect::SDK::Client} that provides the a high-level interface with the GlobalCollect service.
+    # If a code block is given, the created client is returned to the code block and closed afterwards.
+    #
+    # @example Providing a code block
+    #           Factory.create_client_from_communicator(communicator) do |client|
+    #             client.merchant(merchant_id).services.testconnection
+    #           end
+    #           # client is closed here
+    #
+    # communicator::            {Ingenico::Connect::SDK::Communicator} that provides network communication service for the Client
+    def self.create_client_from_communicator(communicator)
+      client = Client.new(communicator)
+      if block_given?
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      else
+        return client
+      end
+    end
+
+    # Creates and returns an {Ingenico::Connect::SDK::Client} that provides the a high-level interface with the GlobalCollect service.
+    # If a code block is given, the created client is returned to the code block and closed afterwards.
+    #
+    # @example Providing a code block
+    #           Factory.create_client_from_session(session) do |client|
+    #             client.merchant(merchant_id).services.testconnection
+    #           end
+    #           # client is closed here
+    #
+    # session::                 {Ingenico::Connect::SDK::Session} that the Client will utilize for communication.
+    def self.create_client_from_session(session)
+      communicator = create_communicator_from_session(session)
+      client = Client.new(communicator)
+      if block_given?
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      else
+        return client
+      end
+    end
+
+    # Creates and returns an {Ingenico::Connect::SDK::Client} that provides the a high-level interface with the GlobalCollect service.
+    # If a code block is given, the created client is returned to the code block and closed afterwards.
+    #
+    # @example Providing a code block
+    #           Factory.create_client_from_file(configuration_file_name, api_key_id, secret_api_key) do |client|
+    #             client.merchant(merchant_id).services.testconnection
+    #           end
+    #           # client is closed here
+    #
+    # configuration_file_name:: Path to the configuration file to use for configuring the Client,
+    #                           should be in YAML format.
+    # api_key_id::              Key id for the GlobalCollect service.
+    # secret_api_key::          Secret key used for authentication to the GlobalCollect service.
+    def self.create_client_from_file(configuration_file_name, api_key_id, secret_api_key)
+      communicator = create_communicator_from_file(configuration_file_name, api_key_id, secret_api_key)
+      client = Client.new(communicator)
+      if block_given?
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      else
+        return client
+      end
+    end
+  end
+end

data/lib/ingenico/connect/sdk/global_collect_exception.rb

@@ -0,0 +1,15 @@
+module Ingenico::Connect::SDK
+
+  # This exception is thrown when a response from the GlobalCollect platform indicates that an error occurred
+  # on the GlobalCollect platform while processing the request.
+  # This corresponds to a HTTP status code of 500 or 502.
+  class GlobalCollectException < ApiException
+
+    # Create a new GlobalCollectException
+    # @see ApiException#initialize
+    def initialize(status_code, response_body, error_id, errors,
+                   message='the GlobalCollect platform returned an error response')
+      super(status_code, response_body, error_id, errors, message)
+    end
+  end
+end

data/lib/ingenico/connect/sdk/idempotence_exception.rb

@@ -0,0 +1,24 @@
+module Ingenico::Connect::SDK
+
+  # This exception is thrown when a response from the GlobalCollect platform indicates
+  # a request with the same _idempotence_key_ was received earlier.
+  # The _idempotence_request_timestamp_ indicates the time when the first request with this _idempotence_key_ arrived.
+  class IdempotenceException < ApiException
+
+    # Create a new IdempotenceException
+    # @see ApiException#initialize
+    def initialize(status_code, response_body, error_id, errors, idempotence_key,
+                   idempotence_request_timestamp,
+                   message='the GlobalCollect platform returned a duplicate request error response')
+      super(status_code, response_body, error_id, errors, message)
+      @idempotence_key = idempotence_key
+      @idempotence_request_timestamp = idempotence_request_timestamp
+    end
+
+    # The idempotence key used in the request.
+    attr_reader :idempotence_key
+
+    # A timestamp indicating the arrival time of the request that conflicts with the request just sent.
+    attr_reader :idempotence_request_timestamp
+  end
+end

data/lib/ingenico/connect/sdk/logging.rb

@@ -0,0 +1,10 @@
+prefix = 'ingenico/connect/sdk/logging/'
+
+require prefix + 'logging_capable'
+require prefix + 'log_message_builder'
+require prefix + 'request_log_message_builder'
+require prefix + 'response_log_message_builder'
+require prefix + 'logging_util'
+require prefix + 'communicator_logger'
+require prefix + 'ruby_communicator_logger'
+require prefix + 'stdout_communicator_logger'

data/lib/ingenico/connect/sdk/logging/communicator_logger.rb

@@ -0,0 +1,19 @@
+module Ingenico::Connect::SDK
+  module Logging
+
+    # Base logger class used in this SDK. This class is an interface and cannot be instantiated.
+    class CommunicatorLogger
+      # interface, no instantiation
+      # @see Ingenico::Connect::SDK::Logging::StdoutCommunicatorLogger
+      # @see Ingenico::Connect::SDK::Logging::RubyCommunicatorLogger
+      def initialize
+        raise NotImplementedError("#{self.class.name} is not implemented.")
+      end
+
+      # logs a message with or without exception
+      def log(message, thrown=false)
+        raise NotImplementedError("#{self.class.name}#log() is not implemented.")
+      end
+    end
+  end
+end

data/lib/ingenico/connect/sdk/logging/log_message_builder.rb

@@ -0,0 +1,61 @@
+module Ingenico::Connect::SDK
+  module Logging
+
+    # Abstract class used to construct a message describing a request or response.
+    class LogMessageBuilder
+
+      # An identifier assigned to the request and response
+      attr_reader :request_id
+
+      # Request or response headers in string form
+      attr_reader :headers
+
+      # Request or response body as a string
+      attr_reader :body
+
+      # Content type of the body, generally 'application/json' or 'text/html'
+      attr_reader :content_type
+
+      # Create a new LogMessageBuilder
+      def initialize(requestId)
+        raise ArgumentError if requestId.nil? or requestId.empty?
+        @request_id = requestId
+        @headers = ''
+      end
+
+      # Adds a single header to the #headers string
+      def add_headers(name, value)
+        @headers += ', ' if @headers.length > 0
+        @headers += name + '="'
+        @headers += LoggingUtil.obfuscate_header(name, value) unless value.nil?
+        @headers += '"'
+      end
+
+      # Sets the body of this message to the parameter body.
+      # body::          The message body
+      # content_type::  The content type of the body
+      def set_body(body, content_type)
+        @body = LoggingUtil.obfuscate_body(body)
+        @content_type = content_type
+      end
+
+      # Constructs and returns the log message as a string.
+      def get_message
+        raise NotImplementedError("#{self.class.name}#get_message() is not implemented.")
+      end
+
+      def to_s
+        if self.class == LogMessageBuilder
+          return super.to_s
+        else
+          return get_message
+        end
+      end
+
+      # Returns an empty string if the parameter is nil, and returns the parameter itself otherwise
+      protected def empty_if_null(value)
+        value.nil? ? '' : value
+      end
+    end
+  end
+end

data/lib/ingenico/connect/sdk/logging/logging_capable.rb

@@ -0,0 +1,19 @@
+module Ingenico
+  module Connect
+    module SDK
+      module Logging
+
+        # Abstract mixin module that allows loggers to be registered to an object.
+        module LoggingCapable
+          def enable_logging(communicator_logger)
+            raise NotImplementedError
+          end
+
+          def disable_logging
+            raise NotImplementedError
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ingenico/connect/sdk/logging/logging_util.rb

@@ -0,0 +1,298 @@
+module Ingenico::Connect::SDK
+  module Logging
+
+    # Class responsible for obfuscating sensitive data in a message body.
+    class ValueObfuscator
+
+      private
+
+      # Creates a new ValueObfuscator.
+      # fixed_length::      If greater than 0, all values that will be obfuscated
+      #                     will be replaced with that number of asterisks.
+      # keep_start_count::  The number of characters to not obfuscate at the end of any value.
+      #                     This parameter is only used if _fixed_length_ = 0.
+      # keep_end_count::    The number of characters to not obfuscate at the start of any value.
+      #                     This parameter is only used if _fixed_length_ = 0.
+      def initialize(fixed_length, keep_start_count, keep_end_count)
+        @mask_character = '*'
+        @fixed_length = fixed_length
+        @keep_start_count = keep_start_count
+        @keep_end_count = keep_end_count
+      end
+
+      public
+
+      @@ALL = ValueObfuscator.new(0, 0, 0)
+
+      def self.ALL
+        @@ALL
+      end
+
+      # Creates a new ValueObfuscator that replaces any sensitive data with a _fixed_length_ line of asterisks.
+      def self.fixed_length(fixed_length)
+        ValueObfuscator.new(fixed_length, 0, 0)
+      end
+
+      # Creates a new ValueObfuscator that retains only the first _count_ characters of any value to obfuscate
+      # and replaces the rest with asterisks.
+      def self.keep_start_count(count)
+        ValueObfuscator.new(0, count, 0)
+      end
+
+      # Creates a new ValueObfuscator that retains only the last _count_ characters of any value to obfuscate
+      # and replaces the rest with asterisks.
+      def self.keep_end_count(count)
+        ValueObfuscator.new(0, 0, count)
+      end
+
+      # Obfuscates the parameter value.
+      def obfuscate_value(value)
+        return value if value.nil? or value.empty?
+        return repeat_mask(@fixed_length) if @fixed_length > 0
+        return repeat_mask(value.length) if @keep_start_count == 0 and @keep_end_count == 0
+        return value if value.length < (@keep_start_count + @keep_end_count)
+
+        # range describes the range of characters to replace with asterisks
+        range = @keep_start_count...(value.length - @keep_end_count)
+        value[range] = @mask_character * range.size
+        value
+      end
+
+      private
+
+      def repeat_mask(count)
+        @mask_character * count
+      end
+    end # end of ValueObfuscator
+
+    class Obfuscator
+      def initialize(obfuscators, case_insensitive)
+        raise ArgumentError unless obfuscators.is_a? Hash
+        @obfuscators = copy(obfuscators, case_insensitive)
+      end
+
+      private
+
+      # case insensitive hash
+      # @private
+      class HashClod < Hash
+
+        def initialize(other)
+          other.each { |k, v| self.[]=(k, v) }
+        end
+
+        def [](key)
+          super _insensitive(key)
+        end
+
+        def []=(key, value)
+          super _insensitive(key), value
+        end
+
+        protected
+
+        def _insensitive(key)
+          key.respond_to?(:upcase) ? key.upcase : key
+        end
+      end # end of HashClod
+
+      def copy(obfuscators, case_insensitive)
+        cp = case_insensitive ? HashClod.new(obfuscators) : obfuscators
+        Marshal.load(Marshal.dump(cp)) # deep copy
+      end
+
+      public
+
+      def obfuscate_value(key, value)
+        obfuscator = @obfuscators[key]
+        obfuscator.nil? ? value : obfuscator.obfuscate_value(value)
+      end
+
+      # A convenient wrapper to build obfuscators
+      class Builder
+        attr_accessor :obfuscators
+
+        def initialize
+          raise NotImplementedError.new("#{self.class.name} is not implemented.")
+        end
+
+        def with_all(key)
+          @obfuscators[key] = ValueObfuscator.ALL
+          self
+        end
+
+        def with_fixed_length(key, fixed_length)
+          @obfuscators[key] = ValueObfuscator.fixed_length(fixed_length)
+          self
+        end
+
+        def with_keep_start_count(key, count)
+          @obfuscators[key] = ValueObfuscator.keep_start_count(count)
+          self
+        end
+
+        def with_keep_end_count(key, count)
+          @obfuscators[key] = ValueObfuscator.keep_end_count(count)
+          self
+        end
+
+        def build
+          raise NotImplementedError.new("#{self.class.name}#build() is not implemented.")
+        end
+      end # Builder
+    end # Obfuscator
+
+    # Class that obfuscates headers of a message
+    class HeaderObfuscator < Obfuscator
+      def initialize(obfuscators)
+        # case insensitive
+        super(obfuscators, true)
+      end
+
+      def self.builder
+        Builder.new
+      end
+
+      class Builder < Obfuscator::Builder
+        def initialize
+          @obfuscators = {}
+        end
+
+        def with_all(name)
+          raise ArgumentError unless name.is_a? String
+          super(name)
+        end
+
+        def with_fixed_length(name, fixedLength)
+          raise ArgumentError unless name.is_a? String
+          super(name, fixedLength)
+        end
+
+        # with_keep_start_count and with_keep_end_count are the same
+        # no need to override
+        
+        def build
+          HeaderObfuscator.new(obfuscators)
+        end
+      end
+    end # end of HeadObfuscator
+
+    # Class that obfuscates properties in the JSON body of a message
+    class PropertyObfuscator < Obfuscator
+      def initialize(obfuscators)
+        # case sensitive
+        super(obfuscators, false)
+        @propertyPattern = build_property_pattern(obfuscators.keys)
+      end
+
+      private
+
+      def build_property_pattern(pn)
+        return /$^/ if pn.empty? # no possible match
+        # Regex to create:
+        # (["'])(X|Y|Z)\1\s*:\s*(?:(["'])(.*?)(?<!\\)\3|([^"'\s]\S*))
+        # Groups:
+        # 1: opening " or ' for the property name
+        # 2: property name
+        # 3: opening " or ' for the value
+        # 4: quoted value
+        # 5: non-quoted-value
+        # The negative lookbehind is to allow escaped quotes to be part of
+        # the value. What this does not allow currently is having values end
+        # with a \ (which would be escaped to \\).
+        regex = pn.inject("([\"'])(") { |r, p| r += Regexp.quote(p) + '|'}.chop +
+          ")\\1\\s*:\\s*(?:([\"'])(.*?)(?<!\\\\)\\3|([^\"'\\s]\\S*))"
+        /#{regex}/m # dotall mode
+      end
+
+      public
+
+      def obfuscate(body)
+        return nil if body.nil?
+        return '' if body.empty?
+
+        body.gsub(@propertyPattern) do
+          m = Regexp.last_match
+          propertyName = m[2]
+          value = m[4] || m[5]
+          # copy value 'cause it's part of m[0]
+          m[0].sub(value, obfuscate_value(propertyName, value.dup))
+        end
+      end
+
+      def self.builder
+        Builder.new
+      end
+
+      class Builder < Obfuscator::Builder
+        def initialize
+          # implement the class
+          @obfuscators = {}
+        end
+
+        def with_all(property)
+          raise ArgumentError unless property.is_a? String
+          super(property)
+        end
+
+        def with_fixed_length(property, fixedLength)
+          raise ArgumentError unless property.is_a? String
+          super(property, fixedLength)
+        end
+
+        def with_keep_start_count(key, count)
+          raise ArgumentError unless key.is_a? String
+          super(key, count)
+        end
+
+        def with_keep_end_count(property, count)
+          raise ArgumentError unless property.is_a? String
+          super(property, count)
+        end
+
+        def build
+          PropertyObfuscator.new(obfuscators)
+        end
+      end
+    end # end of property obfuscator
+
+    class LoggingUtil
+      @@PROPERTY_OBFUSCATOR = PropertyObfuscator.builder
+        .with_keep_end_count("cardNumber", 4)
+        .with_keep_end_count("expiryDate", 2)
+        .with_all("cvv")
+        .with_keep_end_count("iban", 4)
+        .with_keep_end_count("accountNumber", 4)
+        .with_keep_end_count("reformattedAccountNumber", 4)
+        .with_keep_start_count("bin", 6)
+        .with_all("value")
+        .with_fixed_length("keyId", 8)
+        .with_fixed_length("secretKey", 8)
+        .with_fixed_length("publicKey", 8)
+        .with_fixed_length("userAuthenticationToken", 8)
+        .with_fixed_length("encryptedPayload", 8)
+        .with_fixed_length("decryptedPayload", 8)
+        .with_fixed_length("encryptedCustomerInput", 8)
+        .build
+
+      @@HEADER_OBFUSCATOR = HeaderObfuscator.builder
+        .with_fixed_length("Authorization", 8)
+        .with_fixed_length("WWW-Authenticate", 8)
+        .with_fixed_length("Proxy-Authenticate", 8)
+        .with_fixed_length("Proxy-Authorization", 8)
+        .with_fixed_length("X-GCS-Authentication-Token", 8)
+        .with_fixed_length("X-GCS-CallerPassword", 8)
+        .build
+
+      private_class_method :new
+
+      def self.obfuscate_body(body)
+        @@PROPERTY_OBFUSCATOR.obfuscate(body)
+      end
+
+      def self.obfuscate_header(name, value)
+        @@HEADER_OBFUSCATOR.obfuscate_value(name, value)
+      end
+    end # end of LoggingUtil
+  end
+end