connect-sdk-ruby 1.0.0

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

@@ -0,0 +1,15 @@
+module Ingenico::Connect::SDK
+
+  # Abstract class that is responsible for authenticating requests sent to the GlobalCollect platform.
+  class Authenticator
+
+    # Creates a signature to authenticate a request.
+    # Uses the following parameters:
+    # http_method::     'GET', 'PUT', 'POST' or 'DELETE' indicating which HTTP method will be used with the request
+    # resource_uri::    URI object that includes #path and #query of the url that will be used, #query may be *nil*
+    # request_headers:: {Ingenico::Connect::SDK::RequestHeader} list that contains all headers used by the request
+    def create_simple_authentication_signature(http_method, resource_uri, request_headers)
+      raise NotImplementedError
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Ingenico::Connect::SDK
+
+  # This exception is thrown when a request sent to the GlobalCollect 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 GlobalCollect platform returned an authorization error response')
+      super(status_code, response_body, error_id, errors, message)
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Ingenico::Connect::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.
+  class CallContext
+    @idempotence_request_timestamp = nil
+    @idempotence_key = nil
+
+    def initialize(idempotence_key=nil)
+      @idempotence_key = idempotence_key
+    end
+
+    # 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_reader :idempotence_key
+
+    # If two or more requests arrive at the GlobalCollect platform with the same _idempotence_key_,
+    # the _idempotence_request_timestamp_ will be set to the arrival time of the first of these requests.
+    attr_accessor :idempotence_request_timestamp
+  end
+end

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

@@ -0,0 +1,92 @@
+#
+# This class was auto-generated from the API references found at
+# https://developer.globalcollect.com/documentation/api/server/
+#
+require 'ingenico/connect/sdk/api_resource'
+require 'ingenico/connect/sdk/data_object'
+require 'ingenico/connect/sdk/logging/logging_capable'
+require 'ingenico/connect/sdk/merchant/merchant_client'
+require 'base64'
+
+module Ingenico
+  module Connect
+    module SDK
+
+      # GlobalCollect 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
+
+        def self.API_VERSION
+          'v1'
+        end
+
+        # communicator::     Ingenico::Connect::SDK::Communicator
+        # client_meta_info:: String
+        def initialize(communicator, client_meta_info=nil)
+          super(communicator, {'apiVersion' => Client.API_VERSION}, client_meta_info)
+        end
+
+        # client_meta_info:: JSON string containing the meta data for the client
+        # Returns:: A Client which uses the passed meta data for the X-GCS-ClientMetaInfo header.
+        # Raises:: Ingenico::Connect::SDK::MarshallerSyntaxException if the given clientMetaInfo is not a valid JSON string
+        def with_client_meta_info(client_meta_info)
+          if @client_meta_info.nil? && client_meta_info.nil?
+            self
+          elsif client_meta_info.nil?
+            return Client.new(@communicator, nil)
+          else
+            # 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)
+            if @client_meta_info == client_meta_info
+              self
+            else
+              return Client.new(@communicator, client_meta_info)
+            end
+          end
+        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.
+        # communicator_logger:: Ingenico::Connect::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 /{{merchantId}}
+        # merchant_id:: String
+        # Returns:: {Ingenico::Connect::SDK::Merchant::MerchantClient}
+        def merchant(merchant_id)
+          Ingenico::Connect::SDK::Merchant::MerchantClient.new(self, {
+            'merchantId' => merchant_id,
+          })
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,277 @@
+require 'uri'
+
+module Ingenico::Connect::SDK
+
+  # Class responsible for facilitating communication with the GlobalCollect platform.
+  # It combines the following classes to provide communication functionality:
+  #
+  # session::     {Ingenico::Connect::SDK::Session} that stores data for network communication and facilitates network communication
+  # marshaller::  {Ingenico::Connect::SDK::Marshaller} that is used to marshal and unmarshal data to and from JSON format
+  #
+  class Communicator
+    include Logging::LoggingCapable
+
+    # Creates a new Communicator based on a session and marshaller.
+    #
+    # session::     {Ingenico::Connect::SDK::Session} that stores data for network communication and facilitates network communication
+    # marshaller::  {Ingenico::Connect::SDK::Marshaller} that is used to marshal and unmarshal data to and from JSON format
+    #
+    def initialize(session, marshaller)
+      if session.nil?
+        raise ArgumentError('session is required')
+      end
+      if marshaller.nil?
+        raise ArgumentError('marshaller is required')
+      end
+      @session = session
+      @marshaller = marshaller
+    end
+
+    # Performs a GET request to the GlobalCollect platform and returns the response as a {Ingenico::Connect::SDK::Response} object.
+    #
+    # Throws:
+    # ResponseException::       Thrown if the request could not be fulfilled successfully.
+    #                           This occurs for example if the request is not authenticated correctly
+    # NotFoundException::       Thrown if the requested resource is not found
+    # CommunicationException::  Thrown if there is an error in communicating with the GlobalCollect platform.
+    #                           This occurs for example if a timeout occurs.
+    def get(relative_path, request_headers, request_parameters, response_type, context)
+      connection = @session.connection
+      if request_parameters.nil?
+        request_parameter_list = nil
+      else
+        request_parameter_list = request_parameters.to_request_parameters
+      end
+      uri = to_absolute_uri(relative_path, request_parameter_list)
+      if request_headers.nil?
+        request_headers = []
+      end
+      add_generic_headers('GET', uri, request_headers, context)
+      response = connection.get(uri, request_headers)
+      process_response(response, response_type, relative_path, context)
+    end
+
+    # Performs a DELETE request to the GlobalCollect platform and returns the response as a {Ingenico::Connect::SDK::Response} object.
+    #
+    # Throws:
+    # ResponseException::       Thrown if the request could not be fulfilled successfully.
+    #                           This occurs for example if the request is not authenticated correctly.
+    # NotFoundException::       Thrown if the referred resource is not found.
+    # CommunicationException::  Thrown if there is an error in communicating with the GlobalCollect platform.
+    #                           This occurs for example if a timeout occurs.
+    def delete(relative_path, request_headers, request_parameters, response_type, context)
+      connection = @session.connection
+      if request_parameters.nil?
+        request_parameter_list = nil
+      else
+        request_parameter_list = request_parameters.to_request_parameters
+      end
+      uri = to_absolute_uri(relative_path, request_parameter_list)
+      if request_headers.nil?
+        request_headers = []
+      end
+      add_generic_headers('DELETE', uri, request_headers, context)
+      response = connection.delete(uri, request_headers)
+      process_response(response, response_type, relative_path, context)
+    end
+
+    # Performs a POST request to the GlobalCollect platform and returns the response as a {Ingenico::Connect::SDK::Response} object.
+    #
+    # Throws:
+    # ResponseException::       Thrown if the request could not be fulfilled successfully.
+    #                           This occurs for example if the request is not authenticated correctly.
+    # NotFoundException::       Thrown if the referred resource is not found.
+    # CommunicationException::  Thrown if there is an error in communicating with the GlobalCollect platform.
+    #                           This occurs for example if a timeout occurs.
+    def post(relative_path, request_headers, request_parameters, request_body,
+             response_type, context)
+      connection = @session.connection
+      if request_parameters.nil?
+        request_parameter_list = nil
+      else
+        request_parameter_list = request_parameters.to_request_parameters
+      end
+      uri = to_absolute_uri(relative_path, request_parameter_list)
+      if request_headers.nil?
+        request_headers = []
+      end
+      request_json = nil
+      unless request_body.nil?
+        request_headers.push(RequestHeader.new('Content-Type', 'application/json'))
+        request_json = @marshaller.marshal(request_body)
+      end
+      add_generic_headers('POST', uri, request_headers, context)
+      response = connection.post(uri, request_headers, request_json)
+      process_response(response, response_type, relative_path, context)
+    end
+
+    # Performs a PUT request to the GlobalCollect platform and returns the response as a {Ingenico::Connect::SDK::Response} object.
+    #
+    # Throws:
+    # ResponseException::       Thrown if the request could not be fulfilled successfully.
+    #                           This occurs for example if the request is not authenticated correctly.
+    # NotFoundException::       Thrown if the referred resource is not found.
+    # CommunicationException::  Thrown if there is an error in communicating with the GlobalCollect platform.
+    #                           This occurs for example if a timeout occurs.
+    def put(relative_path, request_headers, request_parameters, request_body,
+            response_type, context)
+      connection = @session.connection
+      if request_parameters.nil?
+        request_parameter_list = nil
+      else
+        request_parameter_list = request_parameters.to_request_parameters
+      end
+      uri = to_absolute_uri(relative_path, request_parameter_list)
+      if request_headers.nil?
+        request_headers = []
+      end
+      request_json = nil
+      unless request_body.nil?
+        request_headers.push(RequestHeader.new('Content-Type', 'application/json'))
+        request_json = @marshaller.marshal(request_body)
+      end
+      add_generic_headers('PUT', uri, request_headers, context)
+      response = connection.put(uri, request_headers, request_json)
+      process_response(response, 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::Connect::SDK::PooledConnection}).
+    def close_idle_connections(idle_time)
+      connection = @session.connection
+      if connection.is_a? PooledConnection
+        connection.close_idle_connections(idle_time)
+      end
+    end
+
+    # Closes any connections that have expired.
+    # Will not have any effect if the connection is not a pooled connection (an instance of {Ingenico::Connect::SDK::PooledConnection}).
+    def close_expired_connections
+      connection = @session.connection
+      if connection.is_a? PooledConnection
+        connection.close_expired_connections
+      end
+    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.
+    #
+    # communicator_logger:: The {Ingenico::Connect::SDK::Logging::CommunicatorLogger} the requests and responses are logged to
+    #
+    def enable_logging(communicator_logger)
+      @session.connection.enable_logging(communicator_logger)
+    end
+
+    # Disables logging by unregistering any previous logger that might be registered.
+    def disable_logging
+      @session.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
+      @session.connection.close
+    end
+
+    # A {Ingenico::Connect::SDK::Marshaller} instance used by the communicator for serializing/deserializing to/from JSON
+    attr_reader :marshaller
+
+    protected
+
+    # Constructs a full url using the base url stored in the {Ingenico::Connect::SDK::Session} and the given relative path and request_parameters.
+    # The returned url is a *URI* object.
+    #
+    # relative_path::       The relative path of the url in string form.
+    # request_parameters::  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)
+      api_endpoint = @session.api_endpoint
+      unless api_endpoint.path.nil? || api_endpoint.path.empty?
+        raise RuntimeError('api_endpoint should not contain a path')
+      end
+      unless api_endpoint.userinfo.nil? && api_endpoint.query.nil? && api_endpoint.fragment.nil?
+        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)
+      unless request_parameters.nil?
+        for nvp in request_parameters
+          parameters = URI.decode_www_form(uri.query || '') << [nvp.name, nvp.value]
+          uri.query = URI.encode_www_form(parameters)
+        end
+      end
+      uri
+    end
+
+    # Adds several standard headers to the http headers.
+    #
+    # http_method::     'GET', 'DELETE', 'POST' or 'PUT' depending on the HTTP method being used
+    # uri::             The full URI as a URI object to the GlobalCollect platform,
+    #                   including the relative path and request parameters.
+    # request_headers:: List of {Ingenico::Connect::SDK::RequestHeader} in which which new headers will be added
+    # context::         {Ingenico::Connect::SDK::CallContext} object that will be used to produce
+    #                   an Idempotence header to prevent accidental request duplication.
+    #
+    # 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
+    def add_generic_headers(http_method, uri, request_headers, context = nil)
+      request_headers.concat(@session.meta_data_provider.meta_data_headers)
+      request_headers.push(RequestHeader.new('Date', get_header_date_string))
+      if !context.nil? && !context.idempotence_key.nil?
+        request_headers.push(RequestHeader.new('X-GCS-Idempotence-Key', context.idempotence_key))
+      end
+      authenticator = @session.authenticator
+      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(response, response_type, request_path, context)
+      update_context(response, context) unless context.nil?
+
+      throw_exception_if_necessary(response, request_path)
+      @marshaller.unmarshal(response.body, response_type)
+    end
+
+    def update_context(response, context)
+      idempotence_request_timestamp_value = response.get_header_value('X-GCS-Idempotence-Request-Timestamp')
+      if idempotence_request_timestamp_value.nil?
+        context.idempotence_request_timestamp = nil
+      else
+        context.idempotence_request_timestamp = idempotence_request_timestamp_value
+      end
+    end
+
+    def throw_exception_if_necessary(response, request_path)
+      status_code = response.status_code
+      if status_code < 200 || status_code >= 300
+        body = response.body
+        if !body.nil? && !is_json(response)
+          cause = ResponseException.new(response)
+          if status_code == 404
+            raise NotFoundException.new(cause, 'The requested resource was not found; invalid path: ' +
+                request_path)
+          else
+            raise CommunicationException.new(cause)
+          end
+        else
+          raise ResponseException.new(response)
+        end
+      end
+    end
+
+    private
+
+    def is_json(response)
+      content_type = response.get_header_value('Content-Type')
+      content_type.nil? || 'application/json'.casecmp(content_type) == 0 ||
+          content_type.downcase.start_with?('application/json')
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+module Ingenico::Connect::SDK
+
+  # A CommunicatorConfiguration stores all data used to initialize an {Ingenico::Connect::SDK::Communicator}. It stores the following:
+  #
+  # api_endpoint::            The base url to the GlobalCollect platform.
+  # api_key_id::              The identifier of the _secret_api_key_ used to authenticate requests.
+  # secret_api_key::          The key used to authenticate requests sent to the GlobalCollect platform.
+  # authorization_type::      String describing the authorization protocol to follow.
+  # connect_timeout::         The number of seconds before a connection attempt with the GlobalCollect platform times out.
+  # socket_timeout::          The number of seconds before a timeout occurs
+  #                           when transmitting data to or from the GlobalCollect platform.
+  # max_connections::         The number of connections with the GlobalCollect platform
+  #                           that are kept alive in the connection pool. These connections will be reused when possible.
+  # proxy_configuration::     {Ingenico::Connect::SDK::ProxyConfiguration} instance that stores the url to a proxy to be used in all communication,
+  #                           or nil if no proxy should be used.
+  # integrator::              String
+  # shopping_cart_extension:: {Ingenico::Connect::SDK::Domain::Metadata::ShoppingCartExtension} that stores shopping cart-related metadata.
+  class CommunicatorConfiguration < EndpointConfiguration
+
+    # Creates a new CommunicatorConfiguration instance, it accepts the following arguments:
+    #
+    # properties::              A hash that may contain any of the other parameters.
+    #                           If a parameter is given in both the _properties_ and separately,
+    #                           the separate value takes precedence.
+    # api_endpoint::            The base url to the GlobalCollect platform.
+    # api_key_id::              The identifier of the _secret_api_key_ used to authenticate requests.
+    # secret_api_key::          The key used to authenticate requests sent to the GlobalCollect platform.
+    # authorization_type::      String describing the authorization protocol to follow.
+    # connect_timeout::         The number of seconds before a connection attempt with the GlobalCollect platform times out.
+    # socket_timeout::          The number of seconds before a timeout occurs
+    #                           when transmitting data to or from the GlobalCollect platform.
+    # max_connections::         The number of connections with the GlobalCollect platform
+    #                           that are kept alive in the connection pool. These connections will be reused when possible.
+    # proxy_configuration::     {Ingenico::Connect::SDK::ProxyConfiguration} instance that stores the url to a proxy to be used in all communication,
+    #                           or nil if no proxy should be used.
+    # integrator::              String
+    # shopping_cart_extension:: {Ingenico::Connect::SDK::Domain::Metadata::ShoppingCartExtension} that stores shopping cart-related metadata.
+    #
+    # 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.
+    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, 'connect.api')
+        unless properties.nil?
+          @authorization_type = DefaultImpl::AuthorizationType.get_authorization(
+              properties['connect.api.authorizationType'])
+        end
+      end
+      if api_endpoint
+        @api_endpoint = api_endpoint
+      end
+      if api_key_id
+        @api_key_id = api_key_id
+      end
+      if secret_api_key
+        @secret_api_key = secret_api_key
+      end
+      if authorization_type
+        @authorization_type = authorization_type
+      end
+      if connect_timeout
+        @connect_timeout = connect_timeout
+      end
+      if socket_timeout
+        @socket_timeout = socket_timeout
+      end
+      if max_connections
+        @max_connections = max_connections
+      end
+      if proxy_configuration
+        @proxy_configuration = proxy_configuration
+      end
+      if integrator
+        @integrator = integrator
+      end
+      if shopping_cart_extension
+        @shopping_cart_extension = shopping_cart_extension
+      end
+    end
+
+    # Base URL to the GlobalCollect platform
+    attr_accessor :api_endpoint
+
+    # Identifier of the _secret_api_key_ used in authentication.
+    attr_accessor :api_key_id
+
+    # Secret key used in authentication
+    attr_accessor :secret_api_key
+
+    # String representing the authentication algorithm used
+    attr_accessor :authorization_type
+  end
+end