onlinepayments-sdk-ruby 3.0.0

data/lib/onlinepayments/sdk/meta_data_provider.rb

@@ -0,0 +1,150 @@
+require 'onlinepayments/sdk/domain/shopping_cart_extension'
+require 'base64'
+
+module OnlinePayments::SDK
+
+  # Manages metadata about the server using the SDK
+  #
+  # @attr_reader [Array<OnlinePayments::SDK::RequestHeader>] meta_data_headers List of headers that should be used in all requests.
+  class MetaDataProvider
+    SDK_VERSION = '0.0.1'.freeze
+    SERVER_META_INFO_HEADER = 'X-GCS-ServerMetaInfo'.freeze
+    PROHIBITED_HEADERS = [SERVER_META_INFO_HEADER,
+                          'X-GCS-Idempotence-Key', 'Date', 'Content-Type', 'Authorization'].sort!.freeze
+    CHARSET = 'utf-8'.freeze
+
+    # Stores metadata about the server so it can be sent to the Online Payments platform
+    class ServerMetaInfo < DataObject
+      @platform_identifier = nil
+      @sdk_identifier = nil
+      @sdk_creator = nil
+      @integrator = nil
+      @shopping_cart_extension = nil
+
+      # String containing system information (Operating system and Ruby version).
+      attr_accessor :platform_identifier
+
+      # String containing this SDK version.
+      attr_accessor :sdk_identifier
+
+      attr_accessor :sdk_creator
+
+      attr_accessor :integrator
+
+      attr_accessor :shopping_cart_extension
+
+      # Returns the values of all attributes as a hash.
+      def to_h
+        hash = super
+        hash['platformIdentifier'] = @platform_identifier if @platform_identifier
+        hash['sdkIdentifier'] = @sdk_identifier if @sdk_identifier
+        hash['sdkCreator'] = @sdk_creator if @sdk_creator
+        hash['integrator'] = @integrator if @integrator
+        hash['shoppingCartExtension'] = @shopping_cart_extension.to_h if @shopping_cart_extension
+        hash
+      end
+
+      # Initializes the ServerMetaInfo object with properties stored in the parameter hash
+      def from_hash(hash)
+        super
+        @platform_identifier = hash['platformIdentifier'] if hash.has_key? 'platformIdentifier'
+        @sdk_identifier = hash['sdkIdentifier'] if hash.has_key? 'sdkIdentifier'
+        @sdk_creator = hash['sdkCreator'] if hash.has_key? 'sdkCreator'
+        @integrator = hash['integrator'] if hash.has_key? 'integrator'
+        @shopping_cart_extension = Domain::ShoppingCartExtension.new_from_hash(hash['shoppingCartExtension']) if hash.has_key? 'shoppingCartExtension'
+      end
+    end
+
+    # Create a new MetaDataProvider instance that can be used to access platform-related information
+    #
+    # @param integrator                 [String] Name of the integrator
+    # @param shopping_cart_extension    [OnlinePayments::SDK::Domain::ShoppingCartExtension] shopping cart-related metadata.
+    # @param additional_request_headers [Array<OnlinePayments::SDK::RequestHeader>] list of additional headers to include in all requests made.
+    #                                   The following headers are not allowed due to conflicts with already added headers:
+    #                                   'X-GCS-Idempotence-Key', 'Date', 'Content-Type', 'Authorization' and 'X-GCS-ServerMetaInfo'
+    def initialize(integrator, shopping_cart_extension: nil, additional_request_headers: [].freeze)
+
+      MetaDataProvider.validate_additional_request_headers(additional_request_headers)
+      server_meta_info = ServerMetaInfo.new
+      server_meta_info.platform_identifier = get_platform_identifier
+      server_meta_info.sdk_identifier = get_sdk_identifier
+      server_meta_info.sdk_creator = 'OnlinePayments'
+      server_meta_info.integrator = integrator
+      server_meta_info.shopping_cart_extension = shopping_cart_extension if shopping_cart_extension
+      server_meta_info_string = DefaultImpl::DefaultMarshaller.INSTANCE.marshal(server_meta_info)
+      server_meta_info_header = RequestHeader.new(
+        SERVER_META_INFO_HEADER,
+        Base64.strict_encode64(server_meta_info_string.force_encoding('iso-8859-1').encode(CHARSET)))
+      if additional_request_headers.nil? || additional_request_headers.empty?
+        @meta_data_headers = [server_meta_info_header].freeze
+      else
+        request_headers = [server_meta_info_header]
+        request_headers += additional_request_headers
+        @meta_data_headers = request_headers.freeze
+      end
+    end
+
+    # Checks that none of the {OnlinePayments::SDK::RequestHeaders} in _additional_request_headers_ is equal to any of the forbidden headers.
+    # The forbidden headers are:
+    #'X-GCS-Idempotence-Key', 'Date', 'Content-Type', 'Authorization' and 'X-GCS-ServerMetaInfo'
+    # If a header is found that is equal to one of the forbidden headers an ArgumentError is raised.
+    def self.validate_additional_request_headers(additional_request_headers)
+      if additional_request_headers
+        additional_request_headers.each { |additional_request_header|
+          validate_additional_request_header(additional_request_header)
+        }
+      end
+    end
+
+    # Checks that the {OnlinePayments::SDK::RequestHeaders} _additional_request_header_ is equal to any of the forbidden headers.
+    # The forbidden headers are:
+    #'X-GCS-Idempotence-Key', 'Date', 'Content-Type', 'Authorization' and 'X-GCS-ServerMetaInfo'
+    # If the header is equal to one of the forbidden headers an ArgumentError is raised.
+    def self.validate_additional_request_header(additional_request_header)
+      if MetaDataProvider.PROHIBITED_HEADERS.include? additional_request_header.name
+        raise ArgumentError, "request header '#{additional_request_header.name}' not allowed"
+      end
+    end
+
+    protected
+
+    # String containing information of the system using the SDK.
+    # It contains data like Operating System version and Ruby version
+    def get_platform_identifier
+      os_host = RbConfig::CONFIG['host_os']
+      if os_host.include? 'mingw'
+        s = 'Windows'
+      elsif os_host.include? 'linux'
+        s = 'Linux'
+      else
+        s = 'Mac OS X'
+      end
+      "#{s}/#{RUBY_DESCRIPTION}"
+    end
+
+    # String describing the version of the SDK being used
+    def get_sdk_identifier
+      "RubyServerSDK/v#{SDK_VERSION}"
+    end
+
+    public
+
+    # Version of this SDK being used
+    def self.SDK_VERSION
+      SDK_VERSION
+    end
+
+    # A {OnlinePayments::SDK::RequestHeader} that contains serialized and encoded {OnlinePayments::SDK::MetaDataProvider::ServerMetaInfo}.
+    def self.SERVER_META_INFO_HEADER
+      SERVER_META_INFO_HEADER
+    end
+
+    # A list of header names that should not be used by any added headers.
+    # These headers are reserved for specific purposes.
+    def self.PROHIBITED_HEADERS
+      PROHIBITED_HEADERS
+    end
+
+    attr_reader :meta_data_headers
+  end
+end

data/lib/onlinepayments/sdk/modules.rb

@@ -0,0 +1,62 @@
+# Main module of this SDK. All non-data classes that are used at multiple places in the SDK are placed in this module.
+module OnlinePayments::SDK
+end
+
+# Contains provided implementations for abstract functionality in this SDK.
+# These implementations can be replaced or adapted if desired to suit specific needs.
+module OnlinePayments::SDK::DefaultImpl
+end
+
+# Container for all data-containing modules.
+# The data-classes contained within can be serialized and communicated with the Online Payments platform.
+# These classes generally contain data used in processing requests or responses.
+module OnlinePayments::SDK::Domain
+end
+
+# Contains all logging-related classes.
+module OnlinePayments::SDK::Logging
+end
+
+# Contains interfaces to all Online Payments services. These services are accessed through a *OnlinePayments::SDK::Client* instance.
+module OnlinePayments::SDK::Merchant
+end
+
+# Contains the client used to access the Hosted Checkout service.
+module OnlinePayments::SDK::Merchant::HostedCheckout
+end
+
+# Contains the client used to access the Hosted Tokenization service.
+module OnlinePayments::SDK::Merchant::HostedTokenization
+end
+
+# Contains the client used to access the Payment service.
+module OnlinePayments::SDK::Merchant::Payments
+end
+
+# Contains the client used to access the Payout service.
+module OnlinePayments::SDK::Merchant::Payouts
+end
+
+# Contains the client used to access the Product Groups service.
+module OnlinePayments::SDK::Merchant::ProductGroups
+end
+
+# Contains the client used to access the Products service.
+module OnlinePayments::SDK::Merchant::Products
+end
+
+# Contains the client to access miscellaneous services.
+module OnlinePayments::SDK::Merchant::Services
+end
+
+# Contains the client used to access the Sessions service.
+module OnlinePayments::SDK::Merchant::Sessions
+end
+
+# Contains the client used to access the Tokens service.
+module OnlinePayments::SDK::Merchant::Tokens
+end
+
+# Contains data classes related to Webhooks functionality.
+module OnlinePayments::SDK::Webhooks
+end

data/lib/onlinepayments/sdk/not_found_exception.rb

@@ -0,0 +1,16 @@
+module OnlinePayments::SDK
+
+  # Raised when a resource is not found on the Online Payments platform.
+  # This error corresponds to a 404 HTTP response.
+  #
+  # @attr [Exception] cause The error that is the cause of this error.
+  class NotFoundException < RuntimeError
+
+    def initialize(cause, message = nil)
+      super(message)
+      @cause = cause
+    end
+
+    attr_accessor :cause
+  end
+end

data/lib/onlinepayments/sdk/param_request.rb

@@ -0,0 +1,11 @@
+module OnlinePayments::SDK
+
+  # Class that represents the URL request parameters.
+  # Contains a method to add a name and value pair to a parameter array as a {OnlinePayments::SDK::RequestParam}.
+  class ParamRequest
+    # @return [Array<OnlinePayments::SDK::RequestParam>]
+    def to_request_parameters
+      raise NotImplementedError
+    end
+  end
+end

data/lib/onlinepayments/sdk/payment_platform_exception.rb

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

data/lib/onlinepayments/sdk/pooled_connection.rb

@@ -0,0 +1,21 @@
+module OnlinePayments::SDK
+
+  # {OnlinePayments::SDK::Connection} that supports connection pooling. This is used to more efficiently communicate using HTTP.
+  # Connection pooling means that a number of connections are kept alive after use so they can possibly be reused.
+  # If the Connection does not do so automatically,
+  # the methods _close_idle_connections_ and _close_expired_connections_ can be used to drop connections
+  # that are idle for a specified amount of time or that have expired.
+  # @see OnlinePayments::SDK::DefaultImpl::DefaultConnection
+  class PooledConnection < Connection
+
+    # Closes all connections that have not been used for _idle_time_ seconds.
+    def close_idle_connections(idle_time)
+      raise NotImplementedError
+    end
+
+    # Closes all connections that have expired.
+    def close_expired_connections
+      raise NotImplementedError
+    end
+  end
+end

data/lib/onlinepayments/sdk/proxy_configuration.rb

@@ -0,0 +1,74 @@
+module OnlinePayments::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/onlinepayments/sdk/reference_exception.rb

@@ -0,0 +1,14 @@
+module OnlinePayments::SDK
+
+  # This error is raised when the request refers to a resource or object that is not found by the Online Payments 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 Online Payments platform returned a reference error response')
+      super(status_code, response_body, error_id, errors, message)
+    end
+  end
+end

data/lib/onlinepayments/sdk/request_header.rb

@@ -0,0 +1,50 @@
+module OnlinePayments::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 {OnlinePayments::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/onlinepayments/sdk/request_param.rb

@@ -0,0 +1,23 @@
+module OnlinePayments::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/onlinepayments/sdk/response_exception.rb

@@ -0,0 +1,47 @@
+module OnlinePayments::SDK
+
+  # Exception used internally in the SDK to indicate an error response was received from the Online Payments platform.
+  #
+  # @attr_reader [Integer] status_code HTTP status code that was returned by the Online Payments platform
+  # @attr_reader [String] body         HTTP message body that was returned by the Online Payments platform
+  # @attr_reader [Array<OnlinePayments:SDK:ResponseHeader>] headers HTTP headers used in the response from the Online Payments platform
+  class ResponseException < RuntimeError
+
+    def initialize(status_code, headers, body)
+      super('the Online Payments 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 {OnlinePayments::SDK::ResponseHeader} that corresponds to the given _header_name_
+    # used in the HTTP response from the Online Payments 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/onlinepayments/sdk/response_header.rb

@@ -0,0 +1,42 @@
+module OnlinePayments::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 {OnlinePayments::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/onlinepayments/sdk/validation_exception.rb

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

data/lib/onlinepayments/sdk/webhooks/api_version_mismatch_exception.rb

@@ -0,0 +1,20 @@
+module OnlinePayments::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/onlinepayments/sdk/webhooks/in_memory_secret_key_store.rb

@@ -0,0 +1,56 @@
+require 'concurrent'
+require 'singleton'
+
+module OnlinePayments::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 [OnlinePayments::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/onlinepayments/sdk/webhooks/secret_key_not_available_exception.rb

@@ -0,0 +1,17 @@
+module OnlinePayments::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/onlinepayments/sdk/webhooks/secret_key_store.rb

@@ -0,0 +1,16 @@
+module OnlinePayments::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 [OnlinePayments::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