direct-sdk-ruby 1.0.0

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

@@ -0,0 +1,13 @@
+module Ingenico::Direct::SDK
+
+  # This exception is thrown when a request sent to the Ingenico ePayments platform is not correctly authenticated.
+  # Corresponds to a HTTP status code of 403.
+  # @see ApiException#initialize
+  class AuthorizationException < ApiException
+
+    def initialize(status_code, response_body, error_id, errors,
+                   message = 'the Ingenico ePayments platform returned an authorization error response')
+      super(status_code, response_body, error_id, errors, message)
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Ingenico::Direct::SDK
+
+  # A CallContext is used to identify requests and manage idempotent requests.
+  # A CallContext contains the following:
+  #
+  # idempotence_key::               A randomly generated key used to identify requests
+  # idempotence_request_timestamp:: If a previous request arrived with the same idempotence key,
+  #                                 this value will be set to a timestamp of that request.
+  #
+  # @attr_reader [String] idempotence_key The idempotence key used to identify this request.
+  #              If two requests share the same _idempotence_key_, they are considered to be the same request
+  #              and only the first request will be processed.
+  # @attr        [Integer] idempotence_request_timestamp If two or more requests arrive at the Ingenico ePayments platform with the same _idempotence_key_,
+  #              the _idempotence_request_timestamp_ will be set to the arrival time of the first of these requests.
+  class CallContext
+    @idempotence_request_timestamp = nil
+    @idempotence_key = nil
+
+    def initialize(idempotence_key = nil)
+      @idempotence_key = idempotence_key
+    end
+
+    attr_reader :idempotence_key
+    attr_accessor :idempotence_request_timestamp
+  end
+end

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

@@ -0,0 +1,85 @@
+#
+# This class was auto-generated from the API references found at
+# https://support.direct.ingenico.com/documentation/api/reference/
+#
+require 'ingenico/direct/sdk/api_resource'
+require 'ingenico/direct/sdk/data_object'
+require 'ingenico/direct/sdk/logging/logging_capable'
+require 'ingenico/direct/sdk/merchant/merchant_client'
+require 'base64'
+
+module Ingenico
+  module Direct
+    module SDK
+      # Ingenico ePayments platform client.
+      #
+      # This client and all its child clients are bound to one specific value for the X-GCS-ClientMetaInfo header.
+      #
+      # To get a new client with a different header value, use with_client_meta_info.
+      #
+      # Thread safe.
+      class Client < ApiResource
+        include Logging::LoggingCapable
+
+        # @return [String]
+        def self.API_VERSION
+          'v2'
+        end
+
+        # @param communicator     [Ingenico::Direct::SDK::Communicator]
+        # @param client_meta_info [String, nil]
+        def initialize(communicator, client_meta_info = nil)
+          super(communicator, nil, client_meta_info)
+        end
+
+        # @param client_meta_info [String, nil] JSON string containing the meta data for the client
+        # @return [Ingenico::Direct::SDK::Client] a Client which uses the passed meta data for the X-GCS-ClientMetaInfo header.
+        # @raise [Ingenico::Direct::SDK::MarshallerSyntaxException] if the given clientMetaInfo is not a valid JSON string
+        def with_client_meta_info(client_meta_info)
+          if client_meta_info
+            # Checking to see if this is valid JSON (no JSON parse exceptions)
+            @communicator.marshaller.unmarshal(client_meta_info, DataObject)
+            client_meta_info = Base64.strict_encode64(client_meta_info)
+            return @client_meta_info == client_meta_info ? self : Client.new(@communicator, client_meta_info)
+          end
+          @client_meta_info ? Client.new(@communicator) : self
+        end
+
+        # Utility method that delegates the call to this client's communicator.
+        def close_idle_connections(idle_time)
+          @communicator.close_idle_connections(idle_time)
+        end
+
+        # Utility method that delegates the call to this client's communicator.
+        def close_expired_connections
+          @communicator.close_expired_connections
+        end
+
+        # Turns on logging using the given communicator logger.
+        # @param communicator_logger [Ingenico::Direct::SDK::Logging::CommunicatorLogger]
+        def enable_logging(communicator_logger)
+          @communicator.enable_logging(communicator_logger)
+        end
+
+        # Turns off logging.
+        def disable_logging
+          @communicator.disable_logging
+        end
+
+        # Releases any system resources associated with this object.
+        def close
+          @communicator.close
+        end
+
+        # Resource /v2/!{merchantId}
+        # @param merchant_id [String]
+        # @return [Ingenico::Direct::SDK::Merchant::MerchantClient]
+        def merchant(merchant_id)
+          Ingenico::Direct::SDK::Merchant::MerchantClient.new(self, {
+            'merchantId'.freeze => merchant_id
+          })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Ingenico::Direct::SDK
+
+  # This exception is used when an error occurs during network communication with the Ingenico ePayments platform.
+  # A common cause is a timeout while connecting or when receiving or sending data.
+  #
+  # @attr [Exception] cause The error that is the cause of this error.
+  class CommunicationException < RuntimeError
+
+    def initialize(cause)
+      super()
+      @cause = cause
+    end
+
+    attr_accessor :cause
+  end
+end

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

@@ -0,0 +1,301 @@
+require 'uri'
+
+module Ingenico::Direct::SDK
+  # Class responsible for facilitating communication with the Ingenico ePayments platform.
+  # It combines the following classes to provide communication functionality:
+  #
+  # api_endpoint::       The base URI ({URI::HTTP}) to the Ingenico ePayments platform
+  # connection::         {Ingenico::Direct::SDK::Connection} used to communicate with the Ingenico ePayments platform
+  # authenticator::      {Ingenico::Direct::SDK::Authenticator} used for authenticating messages sent
+  # meta_data_provider:: {Ingenico::Direct::SDK::MetaDataProvider} object containing information relevant for sending requests
+  # marshaller::         {Ingenico::Direct::SDK::Marshaller} that is used to marshal and unmarshal data to and from JSON format
+  #
+  # @attr_reader [Ingenico::Direct::SDK::Marshaller] marshaller A Marshaller instance used by the communicator for serializing/deserializing to/from JSON
+  #
+  class Communicator
+    include Logging::LoggingCapable
+
+    # Creates a new Communicator based on the given arguments.
+    #
+    # @param api_endpoint       [String] the base URL to the Ingenico ePayments platform
+    # @param connection         [Ingenico::Direct::SDK::Connection] used to communicate with the Ingenico ePayments platform
+    # @param authenticator      [Ingenico::Direct::SDK::Authenticator] used for authenticating messages sent
+    # @param meta_data_provider [Ingenico::Direct::SDK::MetaDataProvider] object containing information relevant for sending requests
+    # @param marshaller [Ingenico::Direct::SDK::Marshaller] used to marshal and unmarshal data to and from JSON format
+    #
+    def initialize(api_endpoint, connection, authenticator, meta_data_provider, marshaller)
+      raise ArgumentError, 'api_endpoint is required' unless api_endpoint
+      raise ArgumentError, 'connection is required' unless connection
+      raise ArgumentError, 'authenticator is required' unless authenticator
+      raise ArgumentError, 'meta_data_provider is required' unless meta_data_provider
+      raise ArgumentError('marshaller is required') unless marshaller
+
+      @api_endpoint = URI(api_endpoint)
+      if @api_endpoint.path.length.positive? || @api_endpoint.query || @api_endpoint.fragment
+        raise ArgumentError, "Base URL should not contain a path, query or fragment #{@api_endpoint}"
+      end
+      @connection = connection
+      @authenticator = authenticator
+      @meta_data_provider = meta_data_provider
+      @marshaller = marshaller
+    end
+
+    # Performs a GET request to the Ingenico ePayments platform and returns the response as the given response type.
+    #
+    # @param relative_path      [String] path relative to the API endpoint
+    # @param request_headers    [Array<Ingenico::Direct::SDK::RequestHeader>, nil] optional array of request headers
+    # @param request_parameters [Ingenico::Direct::SDK::ParamRequest, nil] optional request parameters
+    # @param response_type      [Type] the response type.
+    # @param context            [Ingenico::Direct::SDK::CallContext, nil] optional call context.
+    # @return the response of the GET request as the given response type
+    # @raise [Ingenico::Direct::SDK::ResponseException] if the request could not be fulfilled successfully.
+    #        This occurs for example if the request is not authenticated correctly
+    # @raise [Ingenico::Direct::SDK::NotFoundException] if the requested resource is not found
+    # @raise [Ingenico::Direct::SDK::CommunicationException] if there is an error in communicating with the Ingenico ePayments platform.
+    #        This occurs for example if a timeout occurs.
+    def get(relative_path, request_headers, request_parameters, response_type, context)
+      connection = @connection
+      request_parameter_list = request_parameters&.to_request_parameters
+      uri = to_absolute_uri(relative_path, request_parameter_list)
+
+      request_headers ||= []
+      add_generic_headers('GET', uri, request_headers, context)
+
+      response_status_code, response_headers, response_body = nil
+      connection.get(uri, request_headers) do |status_code, headers, content|
+        response_status_code = status_code
+        response_headers = headers
+        response_body = content.read.force_encoding('UTF-8')
+      end
+      process_response(response_body, response_status_code, response_headers, response_type, relative_path, context)
+    end
+
+    # Performs a DELETE request to the Ingenico ePayments platform and returns the response as the given response type.
+    #
+    # @param relative_path      [String] Path relative to the API endpoint
+    # @param request_headers    [Array<Ingenico::Direct::SDK::RequestHeader>, nil] Optional array of request headers
+    # @param request_parameters [Ingenico::Direct::SDK::ParamRequest, nil] Optional request parameters
+    # @param response_type      [Type] The response type.
+    # @param context            [Ingenico::Direct::SDK::CallContext, nil] Optional call context.
+    # @return The response of the DELETE request as the given response type
+    # @raise [Ingenico::Direct::SDK::ResponseException] if the request could not be fulfilled successfully.
+    #        This occurs for example if the request is not authenticated correctly
+    # @raise [Ingenico::Direct::SDK::NotFoundException] if the requested resource is not found
+    # @raise [Ingenico::Direct::SDK::CommunicationException] if there is an error in communicating with the Ingenico ePayments platform.
+    #        This occurs for example if a timeout occurs.
+    def delete(relative_path, request_headers, request_parameters, response_type, context)
+      connection = @connection
+      request_parameter_list = request_parameters&.to_request_parameters
+      uri = to_absolute_uri(relative_path, request_parameter_list)
+      request_headers ||= []
+      add_generic_headers('DELETE', uri, request_headers, context)
+
+      response_status_code, response_headers, response_body = nil
+      connection.delete(uri, request_headers) do |status_code, headers, content|
+        response_status_code = status_code
+        response_headers = headers
+        response_body = content.read.force_encoding('UTF-8')
+      end
+      process_response(response_body, response_status_code, response_headers, response_type, relative_path, context)
+    end
+
+    # Performs a POST request to the Ingenico ePayments platform and returns the response as the given response type.
+    #
+    # @param relative_path      [String] Path relative to the API endpoint
+    # @param request_headers    [Array<Ingenico::Direct::SDK::RequestHeader>, nil] Optional array of request headers
+    # @param request_parameters [Ingenico::Direct::SDK::ParamRequest, nil] Optional request parameters
+    # @param request_body       [Ingenico::Direct::SDK::DataObject] The optional request body
+    # @param response_type      [Type] The response type.
+    # @param context            [Ingenico::Direct::SDK::CallContext, nil] Optional call context.
+    # @return The response of the POST request as the given response type
+    # @raise [Ingenico::Direct::SDK::ResponseException] if the request could not be fulfilled successfully.
+    #        This occurs for example if the request is not authenticated correctly
+    # @raise [Ingenico::Direct::SDK::NotFoundException] if the requested resource is not found
+    # @raise [Ingenico::Direct::SDK::CommunicationException] if there is an error in communicating with the Ingenico ePayments platform.
+    #        This occurs for example if a timeout occurs.
+    def post(relative_path, request_headers, request_parameters, request_body, response_type, context)
+      request_parameter_list = request_parameters&.to_request_parameters
+      uri = to_absolute_uri(relative_path, request_parameter_list)
+      request_headers ||= []
+
+      body = nil
+      if request_body
+        request_headers.push(RequestHeader.new('Content-Type', 'application/json'))
+        body = @marshaller.marshal(request_body)
+      else
+        # Set the content-type, even though there is no body, to prevent the httpClient from
+        # adding a content-type header after authentication has been generated.
+        request_headers.push(RequestHeader.new('Content-Type', 'text/plain'))
+      end
+
+      add_generic_headers('POST', uri, request_headers, context)
+
+      response_status_code, response_headers, response_body = nil
+      @connection.post(uri, request_headers, body) do |status_code, headers, content|
+        response_status_code = status_code
+        response_headers = headers
+        response_body = content.read.force_encoding('UTF-8')
+      end
+      process_response(response_body, response_status_code, response_headers, response_type, relative_path, context)
+    end
+
+    # Performs a PUT request to the Ingenico ePayments platform and returns the response as the given response type.
+    #
+    # @param relative_path      [String] Path relative to the API endpoint
+    # @param request_headers    [Array<Ingenico::Direct::SDK::RequestHeader>, nil] Optional array of request headers
+    # @param request_parameters [Ingenico::Direct::SDK::ParamRequest, nil] Optional request parameters
+    # @param request_body       [Ingenico::Direct::SDK::DataObject]
+    #                           The optional request body
+    # @param response_type      [Type] The response type.
+    # @param context            [Ingenico::Direct::SDK::CallContext, nil] Optional call context.
+    # @return The response of the PUT request as the given response type
+    # @raise [Ingenico::Direct::SDK::ResponseException] if the request could not be fulfilled successfully.
+    #        This occurs for example if the request is not authenticated correctly
+    # @raise [Ingenico::Direct::SDK::NotFoundException] if the requested resource is not found
+    # @raise [Ingenico::Direct::SDK::CommunicationException] if there is an error in communicating with the Ingenico ePayments platform.
+    #        This occurs for example if a timeout occurs.
+    def put(relative_path, request_headers, request_parameters, request_body, response_type, context)
+      request_parameter_list = request_parameters&.to_request_parameters
+      uri = to_absolute_uri(relative_path, request_parameter_list)
+      request_headers ||= []
+
+      body = nil
+      if request_body
+        request_headers.push(RequestHeader.new('Content-Type', 'application/json'))
+        body = @marshaller.marshal(request_body)
+      else
+        # Set the content-type, even though there is no body, to prevent the httpClient from
+        # adding a content-type header after authentication has been generated.
+        request_headers.push(RequestHeader.new('Content-Type', 'text/plain'))
+      end
+      add_generic_headers('PUT', uri, request_headers, context)
+
+      response_status_code, response_headers, response_body = nil
+      @connection.put(uri, request_headers, body) do |status_code, headers, content|
+        response_status_code = status_code
+        response_headers = headers
+        response_body = content.read.force_encoding('UTF-8')
+      end
+      process_response(response_body, response_status_code, response_headers, response_type, relative_path, context)
+    end
+
+    # Closes any connections idle for more than _idle_time_ seconds.
+    # Will not have any effect if the connection is not a pooled connection (an instance of {Ingenico::Direct::SDK::PooledConnection}).
+    def close_idle_connections(idle_time)
+      @connection.close_idle_connections(idle_time) if connection.is_a? PooledConnection
+    end
+
+    # Closes any connections that have expired.
+    # Will not have any effect if the connection is not a pooled connection (an instance of {Ingenico::Direct::SDK::PooledConnection}).
+    def close_expired_connections
+      @connection.close_expired_connections if connection.is_a? PooledConnection
+    end
+
+    # Enables logging outgoing requests and incoming responses by registering the _communicator_logger_.
+    # Note that only one logger can be registered at a time and calling _enable_logging_
+    # a second time will override the old logger instance with the new one.
+    #
+    # @param communicator_logger [Ingenico::Direct::SDK::Logging::CommunicatorLogger] The communicator logger the requests and responses are logged to
+    def enable_logging(communicator_logger)
+      @connection.enable_logging(communicator_logger)
+    end
+
+    # Disables logging by unregistering any previous logger that might be registered.
+    def disable_logging
+      @connection.disable_logging
+    end
+
+    # Frees networking resources by closing the underlying network connections.
+    # After calling _close_, any use of the _get_, _delete_, _post_ and _put_ methods will not function
+    # and likely result in an error.
+    def close
+      @connection.close
+    end
+
+
+    attr_reader :api_endpoint
+    attr_reader :connection
+    attr_reader :authenticator
+    attr_reader :meta_data_provider
+    attr_reader :marshaller
+
+    protected
+
+    # Constructs a full URL using the base URL and the given relative path and request_parameters.
+    # The returned URL is a *URI* object.
+    #
+    # @param relative_path      [String] The relative path of the URL.
+    # @param request_parameters [Array<Ingenico::Direct::SDK::RequestParam>, nil] A list of request parameters that each have #name and #value
+    #                           which represent the parameter name and value respectively.
+    def to_absolute_uri(relative_path, request_parameters)
+      raise RuntimeError('api_endpoint should not contain a path') unless @api_endpoint.path.nil? || @api_endpoint.path.empty?
+
+      if @api_endpoint.userinfo || @api_endpoint.query || @api_endpoint.fragment
+        raise RuntimeError, 'api_endpoint should not contain user info, query or fragment'
+      end
+      absolute_path = relative_path.start_with?('/') ? relative_path : "/#{relative_path}"
+      uri = URI::HTTP.new(@api_endpoint.scheme, nil, @api_endpoint.host,
+                          @api_endpoint.port, nil, absolute_path, nil, nil, nil)
+      request_parameters&.each do |nvp|
+        parameters = URI.decode_www_form(uri.query || '') << [nvp.name, nvp.value]
+        uri.query = URI.encode_www_form(parameters)
+      end
+      uri
+    end
+
+    # Adds several standard headers to the http headers.
+    # This method will add the 'Date' and 'Authorization' header;
+    # the 'X-GCS-Idempotence-Key' header will also be added if an idempotence context is given
+    #
+    # @param http_method     [String] 'GET', 'DELETE', 'POST' or 'PUT' depending on the HTTP method being used
+    # @param uri             [URI::HTTP] The full URI to the Ingenico ePayments platform,
+    #                        including the relative path and request parameters.
+    # @param request_headers [Array<Ingenico::Direct::SDK::RequestHeader>] List of request headers in which which new headers will be added
+    # @param context         [Ingenico::Direct::SDK::CallContext, nil] object that will be used to produce
+    #   an Idempotence header to prevent accidental request duplication.
+    def add_generic_headers(http_method, uri, request_headers, context = nil)
+      request_headers.concat(meta_data_provider.meta_data_headers)
+      request_headers.push(RequestHeader.new('Date', get_header_date_string))
+      if context&.idempotence_key
+        request_headers.push(RequestHeader.new('X-GCS-Idempotence-Key', context.idempotence_key))
+      end
+      authentication_signature = @authenticator.create_simple_authentication_signature(http_method, uri, request_headers)
+      request_headers.push(RequestHeader.new('Authorization', authentication_signature))
+    end
+
+    def get_header_date_string
+      Time.now.utc.strftime('%a, %d %b %Y %H:%M:%S GMT')
+    end
+
+    def process_response(body, status, headers, response_type, request_path, context)
+      update_context(headers, context) if context
+
+      throw_exception_if_necessary(body, status, headers, request_path)
+      @marshaller.unmarshal(body, response_type)
+    end
+
+    def update_context(headers, context)
+      context.idempotence_request_timestamp = ResponseHeader.get_header_value(headers, 'X-GCS-Idempotence-Request-Timestamp')
+    end
+
+    def throw_exception_if_necessary(body, status_code, headers, request_path)
+      return if status_code >= 200 && status_code < 300
+      raise ResponseException.new status_code, headers, body unless body && !is_json(headers)
+
+      cause = ResponseException.new(status_code, headers, body)
+      if status_code == 404
+        raise NotFoundException, cause, "The requested resource was not found; invalid path: #{request_path}"
+      end
+
+      raise CommunicationException, cause
+    end
+
+    private
+
+    def is_json(headers)
+      content_type = ResponseHeader.get_header_value(headers, 'Content-Type')
+      content_type.nil? || 'application/json'.casecmp(content_type).zero? ||
+        content_type.downcase.start_with?('application/json')
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+module Ingenico::Direct::SDK
+
+  # A CommunicatorConfiguration stores all data used to initialize an {Ingenico::Direct::SDK::Communicator}.
+  #
+  # @attr [String] api_endpoint       Base URL to the Ingenico ePayments platform
+  # @attr [String] api_key_id         Identifier of the _secret_api_key_ used in authentication.
+  # @attr [String] secret_api_key     Secret key used in authentication
+  # @attr [String] authorization_type String representing the authentication algorithm used
+  class CommunicatorConfiguration < EndpointConfiguration
+
+    # Creates a new CommunicatorConfiguration instance.
+    #
+    # If a _properties_ object is given, it will be parsed like a hash in order to read these attributes.
+    # If a value is given in both the _properties_ hash and as a separate parameter,
+    # the separate parameter will take precedence over the value in the properties.
+    #
+    # @param properties              [Hash] hash that may contain any of the other parameters.
+    # @param api_endpoint            [String] the base URL to the Ingenico ePayments platform.
+    # @param api_key_id              [String] the identifier of the _secret_api_key_ used to authenticate requests.
+    # @param secret_api_key          [String] the key used to authenticate requests sent to the Ingenico ePayments platform.
+    # @param authorization_type      [String] string describing the authorization protocol to follow.
+    # @param connect_timeout         [Integer] the number of seconds before a connection attempt with the Ingenico ePayments platform times out.
+    # @param socket_timeout          [Integer] the number of seconds before a timeout occurs when transmitting data to or from the Ingenico ePayments platform.
+    # @param max_connections         [Integer] the number of connections with the Ingenico ePayments platform that are kept alive in the connection pool.
+    #                                These connections will be reused when possible.
+    # @param proxy_configuration     [Ingenico::Direct::SDK::ProxyConfiguration] stores the URL to a proxy to be used in all communication,
+    #                                or nil if no proxy should be used.
+    # @param integrator              [String] name of the integrator
+    # @param shopping_cart_extension [Ingenico::Direct::SDK::Domain::ShoppingCartExtension] stores shopping cart-related metadata.
+    # @see EndpointConfiguration#initialize
+    def initialize(properties: nil, api_endpoint: nil, api_key_id: nil,
+                   secret_api_key: nil, authorization_type: nil,
+                   connect_timeout: nil, socket_timeout: nil,
+                   max_connections: nil, proxy_configuration: nil,
+                   integrator: nil, shopping_cart_extension: nil)
+      if properties
+        super(properties, 'direct.api')
+        @authorization_type = properties['direct.api.authorizationType'] ?
+                                  DefaultImpl::AuthorizationType.get_authorization(properties['direct.api.authorizationType']) :
+                                  DefaultImpl::AuthorizationType::V1HMAC
+      end
+      @api_endpoint = api_endpoint if api_endpoint
+      @api_key_id = api_key_id if api_key_id
+      @secret_api_key = secret_api_key if secret_api_key
+      @authorization_type = DefaultImpl::AuthorizationType.get_authorization(authorization_type) if authorization_type
+      @connect_timeout = connect_timeout if connect_timeout
+      @socket_timeout = socket_timeout if socket_timeout
+      @max_connections = max_connections if max_connections
+      @proxy_configuration = proxy_configuration if proxy_configuration
+      @integrator = integrator if integrator
+      @shopping_cart_extension = shopping_cart_extension if shopping_cart_extension
+    end
+
+    attr_accessor :api_endpoint
+    attr_accessor :api_key_id
+    attr_accessor :secret_api_key
+    attr_accessor :authorization_type
+  end
+end