direct-sdk-ruby 1.0.0

data/lib/ingenico/direct/sdk/proxy_configuration.rb

@@ -0,0 +1,74 @@
+module Ingenico::Direct::SDK
+
+  # Contains the URL, username and password of a proxy.
+  #
+  # @attr [String] scheme   Proxy scheme (http or https)
+  # @attr [String] host     Proxy hostname
+  # @attr [Integer] port    Proxy port
+  # @attr [String] username Proxy authentication username
+  # @attr [String] password Proxy authentication password
+  class ProxyConfiguration
+
+    # Initialize a new ProxyConfiguration from the parameter hash.
+    # In order to be complete either host, port and scheme, or an address is required.
+    #
+    # @param args [Hash] the parameters to initialize the proxy configuration with
+    # @option args [String] :host host part of the URL to the proxy.
+    # @option args [Integer] :port port the proxy will be accessed through.
+    # @option args [String] :scheme HTTP scheme used to communicate with the proxy (http or https).
+    # @option args [String] :address full URI to the proxy excluding username and password.
+    #             If given this uri takes precedence over individual host, port and scheme.
+    # @option args [String] :username username used in authentication to the proxy.
+    # @option args [String] :password password used to authenticate to the proxy.
+    def initialize(args)
+
+      host = args[:host]
+      port = args[:port]
+      username = args[:username]
+      password = args[:password]
+      scheme = args[:scheme] || 'http'
+
+      # Don't switch the order, a given address overrides host, port and username
+      address = args[:address]
+      host = address.host if address
+      port = address.port if address
+      scheme = address.scheme if address
+
+      raise ArgumentError, 'scheme is required' unless scheme && !scheme.strip.empty?
+      raise ArgumentError, 'host is required' unless host && !host.strip.empty?
+      raise ArgumentError, 'port is required' unless port&.positive? && port <= 65535
+
+      @host = host
+      @port = port
+      @username = username
+      @password = password
+      @scheme = scheme
+    end
+
+    attr_accessor :scheme
+    attr_accessor :host
+    attr_accessor :port
+
+    attr_accessor :username
+    attr_accessor :password
+
+    # @return [String] a URL string representation of the proxy, excluding authentication.
+    def proxy_uri
+       "#{scheme}://#{host}:#{port}"
+    end
+
+    def to_s
+      proxy_uri
+    end
+
+    private
+
+    def self.get_port(address)
+      port = address.port
+      return port if port != -1
+      return 80 if address.scheme.casecmp('http') == 0
+      return 443 if address.scheme.casecmp('https') == 0
+      raise ArgumentError, "unsupported scheme: #{address.scheme}"
+    end
+  end
+end

data/lib/ingenico/direct/sdk/reference_exception.rb

@@ -0,0 +1,14 @@
+module Ingenico::Direct::SDK
+
+  # This error is raised when the request refers to a resource or object that is not found by the Ingenico ePayments platform.
+  # The object referred to may not exist or it could have been removed recently.
+  class ReferenceException < ApiException
+
+    # Create a new ReferenceException.
+    # @see ApiException#initialize
+    def initialize(status_code, response_body, error_id, errors,
+                   message = 'the Ingenico ePayments platform returned a reference error response')
+      super(status_code, response_body, error_id, errors, message)
+    end
+  end
+end

data/lib/ingenico/direct/sdk/request_header.rb

@@ -0,0 +1,50 @@
+module Ingenico::Direct::SDK
+
+  # Represents HTTP request headers
+  # Each header is immutable has a #name and #value attribute
+  #
+  # @attr_reader [String] name  HTTP header name
+  # @attr_reader [String] value HTTP header value
+  class RequestHeader
+
+    # Create a new header using the name and value given as parameters.
+    def initialize(name, value)
+      raise ArgumentError, 'name is required' if name.nil? || name.strip.empty?
+      @name = name
+      @value = normalize_value(value)
+    end
+
+    attr_reader :name
+    attr_reader :value
+
+    def to_s
+      "#{name}:#{value}"
+    end
+
+    # Return the {Ingenico::Direct::SDK::ResponseHeader} that goes by the given _header_name_,
+    # If this Response does not contain a header with the given name, return _nil_ instead
+    def self.get_header(headers, header_name)
+        selected_headers = headers.select { |h| h.name == header_name }
+        return selected_headers&.length.positive? ?
+                   selected_headers[0] :
+                   nil
+    end
+
+    # Returns the header value of the header that goes by the given _header_name_,
+    # If this response does not contain a header with the given name, return _nil_ instead
+    def self.get_header_value(headers, header_name)
+        return get_header(headers, header_name)&.value
+    end
+
+    private
+
+    def normalize_value(value)
+      return value if value.nil? || value.empty?
+      # Replace all sequences of whitespace*-linebreak-whitespace* into a single linebreak-space
+      # This will ensure that:
+      # - no line ends with whitespace, because this causes authentication failures
+      # - each line starts with a single whitespace, so it is a valid header value
+      value.gsub(/[\s&&[^\r\n]]*(\r?\n)[\s&&[^\r\n]]*/, '\1 ')
+    end
+  end
+end

data/lib/ingenico/direct/sdk/request_param.rb

@@ -0,0 +1,23 @@
+module Ingenico::Direct::SDK
+
+  # Represents a URL request parameter.
+  # Each parameter is immutable and has a #name and #value attribute.
+  #
+  # @attr_reader [String] name  Parameter name
+  # @attr_reader [String] value Parameter value
+  class RequestParam
+
+    def initialize(name, value)
+      raise ArgumentError, 'name is required' if name.nil? || name.strip.empty?
+      @name = name
+      @value = value
+    end
+
+    attr_reader :name
+    attr_reader :value
+
+    def to_s
+      "#{name}=#{value}"
+    end
+  end
+end

data/lib/ingenico/direct/sdk/response_exception.rb

@@ -0,0 +1,47 @@
+module Ingenico::Direct::SDK
+
+  # Exception used internally in the SDK to indicate an error response was received from the Ingenico ePayments platform.
+  #
+  # @attr_reader [Integer] status_code HTTP status code that was returned by the Ingenico ePayments platform
+  # @attr_reader [String] body         HTTP message body that was returned by the Ingenico ePayments platform
+  # @attr_reader [Array<Ingenico:Direct:SDK:ResponseHeader>] headers HTTP headers used in the response from the Ingenico ePayments platform
+  class ResponseException < RuntimeError
+
+    def initialize(status_code, headers, body)
+      super('the Ingenico ePayments platform returned an error response')
+      @status_code = status_code
+      @headers = if headers.nil? || headers.empty?
+                   {}
+                 else
+                   headers.inject({}) do |hash, header|
+                     hash[header.name.downcase.to_sym] = header.dup.freeze
+                     hash
+                   end
+                 end.freeze
+      @body = body
+    end
+
+    attr_reader :status_code
+    attr_reader :body
+    attr_reader :headers
+
+    # Returns the {Ingenico::Direct::SDK::ResponseHeader} that corresponds to the given _header_name_
+    # used in the HTTP response from the Ingenico ePayments platform, or *nil* if the header was not present in the response.
+    def get_header(header_name)
+      ResponseHeader.get_header(@headers, header_name)
+    end
+
+    # Returns the header value received that corresponds to the header named by _header_name_,
+    # or *nil* if _header_name_ was not a header present in the HTTP response.
+    def get_header_value(header_name)
+      ResponseHeader.get_header_value(@headers, header_name)
+    end
+
+    def to_s
+      str = super.to_s
+      str += "; status_code=#{@status_code}" if @status_code.positive?
+      str += "; response_body='#{@body}'" if @body&.length.positive?
+      str.to_s
+    end
+  end
+end

data/lib/ingenico/direct/sdk/response_header.rb

@@ -0,0 +1,42 @@
+module Ingenico::Direct::SDK
+
+  # Represents HTTP response headers
+  # Each header is immutable has a #name and #value attribute
+  #
+  # @attr_reader [String] name  HTTP header name
+  # @attr_reader [String] value HTTP header value
+  class ResponseHeader
+
+    # Create a new header using the name and value given as parameters.
+    def initialize(name, value)
+      raise ArgumentError, 'name is required' if name.nil? || name.strip.empty?
+      @name = name
+      @value = value
+    end
+
+    attr_reader :name
+    attr_reader :value
+
+    def to_s
+      "#{name}:#{value}"
+    end
+
+    # Return the {Ingenico::Direct::SDK::ResponseHeader} that goes by the given _header_name_,
+    # If this Response does not contain a header with the given name, return _nil_ instead
+    def self.get_header(headers, header_name)
+      selected_headers = headers.select { |h| h.name.casecmp(header_name) == 0 }
+      if selected_headers.nil? || selected_headers.length == 0
+        return nil
+      else
+        return selected_headers[0]
+      end
+    end
+
+    # Returns the header value of the header that goes by the given _header_name_,
+    # If this response does not contain a header with the given name, return _nil_ instead
+    def self.get_header_value(headers, header_name)
+      header = get_header(headers, header_name)
+      return header&.value
+    end
+  end
+end

data/lib/ingenico/direct/sdk/validation_exception.rb

@@ -0,0 +1,14 @@
+module Ingenico::Direct::SDK
+
+  # Raised when the request sent to the Ingenico ePayments platform returned a HTTP response with status code 400.
+  # This indicates the request received by the Ingenico ePayments platform was malformed.
+  class ValidationException < ApiException
+
+    # Create a new ValidationException
+    # @see ApiException#initialize
+    def initialize(status_code, response_body, error_id, errors,
+                   message = 'the Ingenico ePayments platform returned an incorrect request error response')
+      super(status_code, response_body, error_id, errors, message)
+    end
+  end
+end

data/lib/ingenico/direct/sdk/webhooks.rb

@@ -0,0 +1,11 @@
+prefix = 'ingenico/direct/sdk/webhooks'
+
+require "#{prefix}/api_version_mismatch_exception"
+require "#{prefix}/signature_validation_exception"
+require "#{prefix}/secret_key_not_available_exception"
+require "#{prefix}/secret_key_store"
+require "#{prefix}/in_memory_secret_key_store"
+require "#{prefix}/webhooks_event"
+require "#{prefix}/webhooks_helper"
+require "#{prefix}/webhooks_helper_builder"
+require "#{prefix}/webhooks"

data/lib/ingenico/direct/sdk/webhooks/api_version_mismatch_exception.rb

@@ -0,0 +1,20 @@
+module Ingenico::Direct::SDK
+  module Webhooks
+    # Raised when a webhooks event has an API version that is not supported by current version
+    # of SDK.
+    #
+    # @attr_reader [String] event_api_version The API version from the webhooks event.
+    # @attr_reader [String] sdk_api_version   The API version that this version of the SDK supports.
+    class ApiVersionMismatchException < RuntimeError
+
+      def initialize(event_api_version, sdk_api_version)
+        super("event API version '#{event_api_version}' is not compatible with SDK API version '#{sdk_api_version}'")
+        @event_api_version = event_api_version
+        @sdk_api_version = sdk_api_version
+      end
+
+      attr_reader :event_api_version
+      attr_reader :sdk_api_version
+    end
+  end
+end

data/lib/ingenico/direct/sdk/webhooks/in_memory_secret_key_store.rb

@@ -0,0 +1,56 @@
+require 'concurrent'
+require 'singleton'
+
+module Ingenico::Direct::SDK
+  module Webhooks
+    # An in-memory secret key store. This implementation can be used
+    # in applications where secret keys are specified at application
+    # startup. Thread-safe.
+    class InMemorySecretKeyStore
+
+      include Singleton
+      include SecretKeyStore
+
+      # Creates new InMemorySecretKeyStore
+      def initialize
+        # NOTE: use Map instead of Hash to provide better performance
+        # under high concurrency.
+        @store = Concurrent::Map.new
+      end
+
+      # Retrieves the secret key corresponding to the given key id
+      #
+      # @param key_id [String] key id of the secret key
+      # @raise [Ingenico::Direct::SDK::Webhooks::SecretKeyNotAvailableException] if the secret key for the given key id is not available.
+      def get_secret_key(key_id)
+        if (secret_key = @store.get(key_id))
+          return secret_key
+        end
+        msg = "could not find secret key for key id #{key_id}"
+        raise SecretKeyNotAvailableException, message: msg, key_id: key_id
+      end
+
+      # Stores the given secret key for the given key id.
+      #
+      # @param key_id     [String] key id of the secret key
+      # @param secret_key [String] the secret key to be stored
+      def store_secret_key(key_id, secret_key)
+        raise ArgumentError if key_id.nil? || key_id.strip.empty?
+        raise ArgumentError if secret_key.nil? || secret_key.strip.empty?
+        @store.put(key_id, secret_key)
+      end
+
+      # Removes the secret key for the given key id.
+      #
+      # @param key_id [String] the key id whose corresponding secret should be removed from the store
+      def remove_secret_key(key_id)
+        @store.delete(key_id)
+      end
+
+      # Removes all stored secret keys from the store
+      def clear
+        @store.clear
+      end
+    end
+  end
+end

data/lib/ingenico/direct/sdk/webhooks/secret_key_not_available_exception.rb

@@ -0,0 +1,17 @@
+module Ingenico::Direct::SDK
+  module Webhooks
+    # Raised when an error caused a secret to become not available.
+    #
+    # @attr_reader [String] key_id
+    class SecretKeyNotAvailableException < SignatureValidationException
+
+      def initialize(args)
+        raise ArgumentError if (key_id = args.delete(:key_id)).nil? # key_id is mandatory
+        super(args)
+        @key_id = key_id
+      end
+
+      attr_reader :key_id
+    end
+  end
+end

data/lib/ingenico/direct/sdk/webhooks/secret_key_store.rb

@@ -0,0 +1,16 @@
+module Ingenico::Direct::SDK
+  module Webhooks
+    # An abstract store of secret keys. Implementation can store secret keys in a database,
+    # on disk, etc. Should be Thread-safe.
+    module SecretKeyStore
+
+      # Retrieve secret key for given key id
+      #
+      # @param key_id [String] key id of the secret key
+      # @raise [Ingenico::Direct::SDK::Webhooks::SecretKeyNotAvailableException] if the secret key for the given key id is not available.
+      def get_secret_key(key_id)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/ingenico/direct/sdk/webhooks/signature_validation_exception.rb

@@ -0,0 +1,19 @@
+module Ingenico::Direct::SDK
+  module Webhooks
+
+    # Raised when an error occurred when validating Webhooks signatures
+    class SignatureValidationException < RuntimeError
+
+      # Creates a new SignatureValidationException
+      #
+      # @param [Hash] args the options to create the Exception with
+      # @option args [String] :message the error message
+      # @option args [RuntimeError] :cause an Error object that causes the Exception
+      def initialize(args)
+        super(args[:message]) # NOTE: can be nil
+        # store backtrace info if exception given
+        set_backtrace(args[:cause].backtrace) if args[:cause]
+      end
+    end
+  end
+end

data/lib/ingenico/direct/sdk/webhooks/webhooks.rb

@@ -0,0 +1,22 @@
+module Ingenico::Direct::SDK
+  module Webhooks
+    # Ingenico ePayments platform factory for several webhooks components
+    module Webhooks
+      DefaultMarshaller ||= Ingenico::Direct::SDK::DefaultImpl::DefaultMarshaller
+
+      # Creates a WebhooksHelperBuilder that uses the
+      # given SecretkeyStore
+      def self.create_helper_builder(secret_key_store)
+        WebhooksHelperBuilder.new
+                             .with_marshaller(DefaultMarshaller.INSTANCE)
+                             .with_secret_key_store(secret_key_store)
+      end
+
+      # Creates a WebhooksHelper that uses the given
+      # SecretkeyStore.
+      def self.create_helper(secret_key_store)
+        create_helper_builder(secret_key_store).build
+      end
+    end
+  end
+end