connect-sdk-ruby 1.36.0 → 2.0.0

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

@@ -3,31 +3,9 @@ module Ingenico::Connect::SDK
   # Class that represents the URL request parameters.
   # Contains a method to add a name and value pair to a parameter array as a {Ingenico::Connect::SDK::RequestParam}.
   class ParamRequest
-
-    protected
-
-    # Adds a {Ingenico::Connect::SDK::RequestParam} object to the _request_parameters_ array
-    # where RequestParam.name = name and RequestParam.value = value.
-    # Allows Strings, Integers, booleans and arrays of these to be converted to RequestParams.
-    # If _value_ is an array, one RequestParam instance will be added for each element in the array.
-    # An array containing another array is explicitly disallowed and will raise an error.
-    def add_parameter(request_parameters, name, value)
-      add_param(request_parameters, name, value)
-    end
-
-    private
-
-    def add_param(request_parameters, name, value, allow_collection = true)
-      if value.is_a?(String) || value.is_a?(Integer) || value.class == TrueClass ||
-          value.class == FalseClass
-        request_parameters.push(RequestParam.new(name, value.to_s))
-      elsif allow_collection && value.class == Array
-        value.each { |element|
-          add_param(request_parameters, name, element, false)
-        }
-      elsif !value.nil?
-        raise ArgumentError.new("Unsupported request parameter type: #{value.class}")
-      end
+    # @return [Array<Ingenico::Connect::SDK::RequestParam>]
+    def to_request_parameters
+      raise NotImplementedError
     end
   end
 end

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

@@ -1,18 +1,25 @@
 module Ingenico::Connect::SDK
 
-  # Contains the url, username and password of a proxy.
+  # 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.
-    # Arguments read from the hash are:
-    # host::      Host part of the url to the proxy.
-    # port::      Port the proxy will be accessed through.
-    # scheme::    HTTP scheme used to communicate with the proxy (HTTP or HTTPS).
-    # address::   Full uri to the proxy excluding username and password.
+    #
+    # @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.
-    # username::  Username used in authentication to the proxy.
-    # password::  Password used to authenticate to the proxy.
+    # @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]
@@ -38,22 +45,14 @@ module Ingenico::Connect::SDK
       @scheme = scheme
     end
 
-    # proxy scheme (http or https)
     attr_accessor :scheme
-
-    # proxy hostname
     attr_accessor :host
-
-    # proxy port
     attr_accessor :port
 
-    # proxy authentication username
     attr_accessor :username
-
-    # proxy authentication password
     attr_accessor :password
 
-    # Returns a url string representation of the proxy, excluding authentication.
+    # @return [String] a URL string representation of the proxy, excluding authentication.
     def proxy_uri
        "#{scheme}://#{host}:#{port}"
     end

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

@@ -2,6 +2,9 @@ module Ingenico::Connect::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.
@@ -13,15 +16,31 @@ module Ingenico::Connect::SDK
       @value = normalize_value(value)
     end
 
-    # HTTP header name
     attr_reader :name
-    # HTTP header value
     attr_reader :value
 
     def to_s
       "#{name}:#{value}"
     end
 
+    # Return the {Ingenico::Connect::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 }
+        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 (if header.nil? then nil else header.value end)
+    end
+
     private
 
     def normalize_value(value)
@@ -32,7 +51,7 @@ module Ingenico::Connect::SDK
       # 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 ');
+      value.gsub(/[\s&&[^\r\n]]*(\r?\n)[\s&&[^\r\n]]*/, '\1 ')
     end
   end
 end

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

@@ -2,6 +2,9 @@ module Ingenico::Connect::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)
@@ -12,9 +15,7 @@ module Ingenico::Connect::SDK
       @value = value
     end
 
-    # parameter name
     attr_reader :name
-    # parameter value
     attr_reader :value
 
     def to_s

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

@@ -1,52 +1,49 @@
 module Ingenico::Connect::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:Connect:SDK:ResponseHeader>] headers HTTP headers used in the response from the Ingenico ePayments platform
   class ResponseException < RuntimeError
 
-    def initialize(response)
+    def initialize(status_code, headers, body)
       super('the Ingenico ePayments platform returned an error response')
-      @response = response
+      @status_code = status_code
+      @headers = if headers.nil? or headers.empty?
+                   {}
+                 else
+                   headers.inject({}) do |hash, header|
+                     hash[header.name.downcase.to_sym] = header.dup.freeze
+                     hash
+                   end
+                 end.freeze
+      @body = body
     end
 
-    # {Ingenico::Connect::SDK::Response} object that was returned by the Ingenico ePayments platform
-    attr_reader :response
-
-    # HTTP status code that was returned by the Ingenico ePayments platform
-    def status_code
-      @response.status_code
-    end
-
-    # string HTTP message body that was returned by the Ingenico ePayments platform
-    def body
-      @response.body
-    end
-
-    # List of {Ingenico::Connect::SDK::ResponseHeader} that represent the HTTP headers used in the response from the Ingenico ePayments platform
-    def headers
-      @response.headers
-    end
+    attr_reader :status_code
+    attr_reader :body
+    attr_reader :headers
 
     # Returns the {Ingenico::Connect::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)
-      @response.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)
-      @response.get_header_value(header_name)
+      ResponseHeader.get_header_value(@headers, header_name)
     end
 
     def to_s
       str = super.to_s
-      status_code = @response.status_code
-      if status_code > 0
-        str += '; status_code=' + status_code.to_s
+      if @status_code > 0
+        str += '; status_code=' + @status_code.to_s
       end
-      response_body = @response.body
-      if !response_body.nil? && response_body.length > 0
-        str += "; response_body='" + response_body + "'"
+      if !@body.nil? && @body.length > 0
+        str += "; response_body='" + @body + "'"
       end
       str.to_s
     end

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

@@ -2,6 +2,9 @@ module Ingenico::Connect::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.
@@ -11,13 +14,57 @@ module Ingenico::Connect::SDK
       @value = value
     end
 
-    # HTTP header name
     attr_reader :name
-    # HTTP header value
     attr_reader :value
 
     def to_s
       "#{name}:#{value}"
     end
+
+    # Return the {Ingenico::Connect::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 (if header.nil? then nil else header.value end)
+    end
+
+    # Returns the value of the _filename_ parameter of the _Content-Disposition_ header from
+    # parameter _headers_
+    # If this Response does not contain a header with the given name, return _nil_ instead
+    def self.get_disposition_filename(headers)
+      header_value = get_header_value(headers, "Content-Disposition")
+      unless header_value.nil?
+        if header_value =~ /(?:^|;)\s*filename\s*=\s*(.*?)\s*(?:;|$)i/
+          return trim_quotes($2)
+        end
+      end
+
+      return nil
+    end
+
+    private
+
+    # Trims the single or double quotes at the beginning and end of parameter _filename_ if they exist
+    # If they don't exist, it returns the original _filename_ instead
+    def trim_quotes(filename)
+      unless filename.length < 2
+        if ( filename.chars.first == '\'' && filename.chars.last == '\"' ) ||
+            ( filename.chars.first == '"' && filename.chars.last == '"' )
+          return filename[1...-1]
+        end
+      end
+      return filename
+    end
   end
 end

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

@@ -3,14 +3,19 @@ require 'uri'
 module Ingenico::Connect::SDK
 
   # Contains networking and authentication data needed to communicate with the Ingenico ePayments platform
+  #
+  # @attr_reader [URI::HTTP] api_endpoint The base URI to the Ingenico ePayments platform
+  # @attr_reader [Ingenico::Connect::SDK::Connection] connection Used to communicate with the Ingenico ePayments platform
+  # @attr_reader [Ingenico::Connect::SDK::Authenticator] authenticator Used for authenticating messages sent
+  # @attr_reader [Ingenico::Connect::SDK::MetaDataProvider] meta_data_provider Object containing information relevant for sending requests
   class Session
 
     # Construct a new Session.
-    # The session object stores the following:
-    # api_endpoint::        The base url to the Ingenico ePayments platform, given as a string and converted to a {URI} object
-    # connection::          An instance of the {Ingenico::Connect::SDK::Connection} class used to communicate with
-    # authenticator::       An instance of the {Ingenico::Connect::SDK::Authenticator} class used for authenticating messages sent
-    # meta_data_provider::  An instance of the {Ingenico::Connect::SDK::MetaDataProvider} class containing information relevant for sending requests
+    #
+    # @param api_endpoint       [String] the base URL to the Ingenico ePayments platform
+    # @param connection         [Ingenico::Connect::SDK::Connection] used to communicate with the Ingenico ePayments platform
+    # @param authenticator      [Ingenico::Connect::SDK::Authenticator] used for authenticating messages sent
+    # @param meta_data_provider [Ingenico::Connect::SDK::MetaDataProvider] object containing information relevant for sending requests
     def initialize(api_endpoint, connection, authenticator, meta_data_provider)
       raise ArgumentError.new('api_endpoint is required') unless api_endpoint
       raise ArgumentError.new('connection is required') unless connection
@@ -19,7 +24,7 @@ module Ingenico::Connect::SDK
 
       uri = URI(api_endpoint)
       if uri.path.length > 0 || uri.query || uri.fragment
-        raise ArgumentError.new("Base url should not contain a path, query or fragment #{uri.to_s}")
+        raise ArgumentError.new("Base URL should not contain a path, query or fragment #{uri.to_s}")
       end
       @api_endpoint = uri
       @connection = connection
@@ -27,13 +32,9 @@ module Ingenico::Connect::SDK
       @meta_data_provider = meta_data_provider
     end
 
-    # The base URI to the Ingenico ePayments platform as a {URI} object
     attr_reader :api_endpoint
-    # An instance of the {Ingenico::Connect::SDK::Connection} class used to communicate with
     attr_reader :connection
-    # An instance of the {Ingenico::Connect::SDK::Authenticator} class used for authenticating messages sent
     attr_reader :authenticator
-    # An instance of the {Ingenico::Connect::SDK::MetaDataProvider} class containing information relevant for sending requests
     attr_reader :meta_data_provider
   end
 end

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

@@ -0,0 +1,30 @@
+module Ingenico::Connect::SDK
+
+    # A file that can be uploaded
+    #
+    # The allowed forms of content are defined by the Connection implementation
+    # The default implementation supports file paths and IO objects.
+    #
+    # @attr_reader [String] file_name       The name of the file.
+    # @attr_reader [String, IO] content     The file's content.
+    # @attr_reader [String] content_type    The file's content type.
+    # @attr_reader [Integer] content_length The file's content length, or -1 if not known.
+    class UploadableFile
+
+        def initialize(file_name, content, content_type, content_length=-1)
+            raise ArgumentError.new("file_name is required") if file_name.nil? or !file_name.strip
+            raise ArgumentError.new("content is required") if content.nil?
+            raise ArgumentError.new("content_type is required") if content_type.nil? or !content_type.strip
+
+            @file_name = file_name
+            @content = content
+            @content_type = content_type
+            @content_length = [content_length, -1].max
+        end
+
+        attr_reader :file_name
+        attr_reader :content
+        attr_reader :content_type
+        attr_reader :content_length
+    end
+end

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

@@ -2,6 +2,9 @@ module Ingenico::Connect::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)
@@ -10,10 +13,7 @@ module Ingenico::Connect::SDK
         @sdk_api_version = sdk_api_version
       end
 
-      # The API version from the webhooks event.
       attr_reader :event_api_version
-
-      # The API version that this version of the SDK supports.
       attr_reader :sdk_api_version
     end
   end

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

@@ -20,8 +20,8 @@ module Ingenico::Connect::SDK
 
       # Retrieves the secret key corresponding to the given key id
       #
-      # key_id:: key id of the secret key
-      # Raises {Ingenico::Connect::SDK::Webhooks::SecretKeyNotAvailableException} if the secret key for the given key id is not available.
+      # @param key_id [String] key id of the secret key
+      # @raise [Ingenico::Connect::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)).nil?
           msg = "could not find secret key for key id " + key_id
@@ -32,8 +32,8 @@ module Ingenico::Connect::SDK
 
       # Stores the given secret key for the given key id.
       #
-      # key_id:: key id of the secret key
-      # secret_id:: the secret key to be stored
+      # @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? or key_id.strip.empty?
         raise ArgumentError if secret_key.nil? or secret_key.strip.empty?
@@ -42,7 +42,7 @@ module Ingenico::Connect::SDK
 
       # Removes the secret key for the given key id.
       #
-      # key_id:: the key id whose corresponding secret should be removed from the store
+      # @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

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

@@ -1,6 +1,8 @@
 module Ingenico::Connect::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)