mastercard_core_sdk 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eb6b59bd4a75a56d7b91cae232074730af2f6c7c
-  data.tar.gz: 6c91654b4b2a27b6cc02b9c9a40717976b4d1226
+  metadata.gz: 70baa13d8f8b4684d46d10f1447d213c1b4f79a9
+  data.tar.gz: 536119e0d246a3e11b01ee4fd1bae3440c42a12c
 SHA512:
-  metadata.gz: dc1476806427da0fb09cd120393b035509f819f21a496f9241fcf6ba67e5791a73f45d34b8bde6d3de043faacc4293128db41d2764aff4e4087fc641785206ca
-  data.tar.gz: 8d51ea7648a7eb4f98d037c300293a1922b8d193744e5ae1f12eb8555245fa40933c18c31efa098f03096c8d1e0f732e70b34f6222ac8811cc614a4a6af1c017
+  metadata.gz: 5564f83d9186449a34d4a5ae88ee6f3b565e46a26c81182c8a8d0be2e4b7279265036fbd83df813b46eff66921738f9f2f3defaaf4b8f4aac22280cf74008463
+  data.tar.gz: 952f07b940667b6bf92bdf58617cc0207535aafbc76388f9cf9c3a593ba909470bcae7994af374936b39a69edfee22e8576b6f4a404533ccbbd1433ef490cd1f

data/README.md

@@ -1,10 +1,18 @@
 # MastercardCoreSdk
-	This is core SDK containing the configuration part for checkout SDK.
-	The merchant checkout SDK - MastercardMasterpassMerchant requires this MastercardCoreSdk as dependency for calling the checkout API services. 
-	Features include :
-	• Exception Handler - Exception handling features help you deal with any unexpected or exceptional situations that occur while calling the API services. 
-	• Serializers - Serializer handles the request and responses for the API services. 
-	• ApiTracker - ApiTracker tracks the details of SDK from which API services are called. 
+
+This is core SDK containing the configuration part for checkout SDK.
+
+The merchant checkout SDK - MastercardMasterpassMerchant requires this MastercardCoreSdk as dependency for calling the checkout API services. 
+
+Features include : 
+
+• Exception Handler - Exception handling features help you deal with any unexpected or exceptional situations that occur while calling the API services. 
+
+• Serializers - Serializer handles the request and responses for the API services. 
+
+• ApiTracker - ApiTracker tracks the details of SDK from which API services are called. 
+
+For more information, refer [mastercard's developer site](https://developer.mastercard.com). 
 
 ## Installation
 
@@ -23,11 +31,21 @@ Or install it yourself as:
     $ gem install mastercard_core_sdk
 
 ## Usage
-Set MasterCard Configuration using Consumer Key & Private Key from developer's site and call API: 
+
+Customize default settings for the SDK through Configuration class using block :
 
 ```
 require 'mastercard_core_sdk'
 
+MastercardCoreSdk.configure do |config|
+   # Since version 1.3.0, verify_ssl is set default to true.
+   config.ssl_ca_cert = <path to the certificate file to verify the peer>
+end
+```
+
+Set configurations for private key and consumer key to call API: 
+
+```
 MasterCardApiConfiguration.consumer_key = <Consumer Key>
 MasterCardApiConfiguration.private_key = OpenSSL::PKCS12.new(File.open(<Path to P12 file>), <Password>).key
 MasterCardApiConfiguration.sandbox = false  #By default SANDBOX environment is set, Set sandbox to false to use Production environment
@@ -35,7 +53,6 @@ MasterCardApiConfiguration.sandbox = false  #By default SANDBOX environment is s
 request_token_response = RequestTokenApi.create(<URL>)
 ```
 
-
 ## Copyright
 Copyright (c) 2016, MasterCard International Incorporated. See LICENSE for details.
 

data/lib/mastercard_core_sdk/api/access_token_api.rb

@@ -5,12 +5,19 @@ require_relative '../models/access_token_response'
 
 module MastercardCoreSdk
   module Api
+   # Invokes AccessTokenApi.
    class AccessTokenApi
       include MastercardCoreSdk::Core, MastercardCoreSdk::Client, MastercardCoreSdk::Exceptions, MastercardCoreSdk::Tracker
       
-      # Access Token Api service
-      # @param oauth_token
-      # @param oauth_verifier
+      # This API call is used to exchange a request token for a long access token from the Masterpass service. 
+      # For Pairing during checkout, this service will need to be called twice: 
+      # 1. To request the checkout access token, which is used to retrieve checkout data.
+      # 2. To request the long access token, which is used to retrieve precheckout data.
+      # You will need the Request Token (oauth_token) and Verifier (oauth_verifier) from the merchant callback to get an access token.
+      #
+      # @note Since version 1.2.0, the method signature for {create} has changed.
+      # @param oauth_token the oauth token, which is used to retrieve checkout data.
+      # @param oauth_verifier the oauth verifier.
       # @param api_config Optional ApiConfig object.
       # @return [AccessTokenResponse]
       def self.create(oauth_token, oauth_verifier, api_config = nil)

data/lib/mastercard_core_sdk/api/request_token_api.rb

@@ -5,11 +5,14 @@ require_relative '../models/request_token_response'
 
 module MastercardCoreSdk
   module Api
+    # Invokes RequestTokenApi.
     class RequestTokenApi
       include MastercardCoreSdk::Core, MastercardCoreSdk::Client, MastercardCoreSdk::Exceptions, MastercardCoreSdk::Tracker
       
-      # Request Token Api service
-      # @param oauth_callback_url Callback URL.
+      # This api call used to get the request token.This must be executed when a
+      # consumer clicks Buy with MasterPass or Connect with MasterPass buttons on your site/app.
+      #
+      # @param oauth_callback_url the oauth callback URL.
       # @param api_config Optional ApiConfig object.
       # @return [RequestTokenResponse]
       def self.create(oauth_callback_url, api_config = nil)

data/lib/mastercard_core_sdk/client/api_client.rb

@@ -14,6 +14,7 @@ require_relative '../converters/sdk_converter_factory'
 
 module MastercardCoreSdk
   module Client
+    # ApiClient is the base class to invoke the API. It is responsible for to convert all request and response according to the content type.
     class ApiClient
       include MastercardCoreSdk::Core, MastercardCoreSdk::Interceptors, MastercardCoreSdk::Converters, MastercardCoreSdk::Tracker
 
@@ -38,6 +39,7 @@ module MastercardCoreSdk
       # Defines the object that would handle error for all the requests.
       attr_accessor :error_handler
       
+      # Adds the authorization header, tracking headers and also logs the request/response.
       attr_accessor :mastercard_authenticator
       
       # Initializing Api Client with user-agent, configuration and default headers.
@@ -61,7 +63,7 @@ module MastercardCoreSdk
       # @param service_request Service Request object
       # @param http_method Specifies HTTP method
       # @param return_type Specifies response return type model
-      # @return [String]
+      # @return [String] Response body
       def call(path, service_request, http_method, return_type)
         request = build_request(http_method, path, service_request, @api_config)
         response_body, response_code, response_headers = call_api(request, return_type)
@@ -97,7 +99,14 @@ module MastercardCoreSdk
 
         return data, response.code, response.headers
       end
-
+      
+      # Builds the HTTP request
+      #
+      # @param [String] http_method HTTP method/verb (e.g. POST)
+      # @param [String] path URL path (e.g. /account/new)
+      # @param [Object] request ServiceRequest object
+      # @param [Object] api_config ApiConfig object
+      # @return [Typhoeus::Request] A Typhoeus Request
       def build_request(http_method, path, request, api_config)
         url = build_request_url(path, request, api_config)
         http_method = http_method.to_sym.downcase
@@ -106,14 +115,21 @@ module MastercardCoreSdk
         header_params = @default_headers.merge(content_type_header || {}).merge(request.headers || {}).merge(api_config_header)
         query_params = request.query_params || {}
 
+        # set ssl_verifyhosts option based on @config.verify_ssl_host (true/false)
+        _verify_ssl_host = @config.verify_ssl_host ? 2 : 0
+        
         req_opts = {
           :method => http_method,
           :headers => header_params,
           :params => query_params,
           :timeout => @config.timeout,
-          :ssl_verifypeer => @config.verify_ssl
+          :ssl_verifypeer => @config.verify_ssl,
+          :ssl_verifyhost => _verify_ssl_host,
+          :sslcert => @config.cert_file,
+          :sslkey => @config.key_file
         }
-
+        req_opts[:cainfo] = @config.ssl_ca_cert if @config.ssl_ca_cert
+     
         if [:post, :patch, :put, :delete].include?(http_method)
           req_body = build_request_body(request)
           req_opts.update :body => req_body

data/lib/mastercard_core_sdk/core/api_config.rb

@@ -1,11 +1,16 @@
 module MastercardCoreSdk
   module Core
-    # Defines consumer key, private key from developer's site and name, host URL for environment other than sandbox/production.
+    # Set environment details require to call mastercard api.  
     class ApiConfig
       
        CONFIG_NAME_HEADER = "__config_name__"
        attr_accessor :name, :consumer_key, :private_key, :host_url
        
+       # Constructs ApiConfig object.
+       # @param name the environment name. e.g. "SANDBOX"
+       # @param consumer_key the consumer key (Generated from mastercard developer zone). 
+       # @param private_key the private key, to be fetched from the certificate.
+       # @param host_url the environment host url. e.g. "https://sandbox.api.mastercard.com" 
        def initialize(name, consumer_key, private_key, host_url)
          @name = name
          @consumer_key = consumer_key

data/lib/mastercard_core_sdk/core/api_config_builder.rb

@@ -1,18 +1,18 @@
 module MastercardCoreSdk
   module Core
-    # To be defined by application developer : environment name, consumer key, private key and host URL. 
+    # Set environment details require to call mastercard api.
     class ApiConfigBuilder
       
       # Sets environment name
-      # @param name Environment.
+      # @param name the environment name. e.g. SANDBOX.
       # @return [ApiConfigBuilder]
       def name(name)
         @name = name
         return self
       end
       
-      # Sets consumer key
-      # @param consumer_key Consumer key from developer's site.
+      # Set the consumer key generated from mastercard developer zone.
+      # @param consumer_key the consumer key (Generated from mastercard developer zone).
       # @return [ApiConfigBuilder]
       def consumer_key(consumer_key)
         @consumer_key = consumer_key
@@ -20,22 +20,22 @@ module MastercardCoreSdk
       end
       
       # Sets private key
-      # @param private_key Private key from developer's site.
+      # @param private_key the private key, to be fetched from the certificate.
       # @return [ApiConfigBuilder]
       def private_key(private_key)
         @private_key = private_key
         return self
       end
       
-      # Sets host URL as per environment(Sandbox/Production)
-      # @param host_url Host URL for the environment.
+      # Sets host URL for the environment(Sandbox/Production)
+      # @param host_url the environment host url. e.g. sandbox - "https://sandbox.api.mastercard.com"
       # @return [ApiConfigBuilder]
       def host_url(host_url)
         @host_url = host_url
         return self
       end
       
-      # Register the ApiConfig with MasterCardApiConfiguration.
+      # Build and register the ApiConfig object.
       # @return [ApiConfig]
       def build
         api_config = ApiConfig.new(@name, @consumer_key, @private_key, @host_url)

data/lib/mastercard_core_sdk/core/configuration.rb

@@ -2,16 +2,9 @@ require 'uri'
 
 module MastercardCoreSdk
   module Core
+      # Represents a set of configuration settings.
       class Configuration
-        # Defines url scheme
-        attr_accessor :scheme
-    
-        # Defines url host
-        attr_accessor :host
-    
-        # Defines url base path
-        attr_accessor :base_path
-    
+        
         # The time limit for HTTP request in seconds.
         # Default to 0 (never times out).
         attr_accessor :timeout
@@ -20,29 +13,47 @@ module MastercardCoreSdk
         # Set this to false to skip verifying SSL certificate when calling API from https server.
         # Default to true.
         #
-        # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.
-        #
+        # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks. Since version 1.3.0, it is default to true.
+        # 
         # @return [true, false]
         attr_accessor :verify_ssl
+        
+        ### TLS/SSL setting
+        # Set this to false to skip verifying SSL host name.
+        # Default to true.
+        #
+        # @return [true, false]
+        # @since 1.3.0
+        attr_accessor :verify_ssl_host
+        
+        # Set this to customize the certificate file to verify the peer.
+        #
+        # @return [String] the path to the certificate file
+        #
+        # @see The `cainfo` option of Typhoeus, `--cert` option of libcurl. Related source code:
+        # https://github.com/typhoeus/typhoeus/blob/master/lib/typhoeus/easy_factory.rb#L145
+        # @since 1.3.0
+        attr_accessor :ssl_ca_cert
+        
+        # Client certificate file (for client certificate)
+        # @since 1.3.0
+        attr_accessor :cert_file
     
-        attr_accessor :inject_format
-    
-        attr_accessor :force_ending_format
+        # Client private key file (for client certificate)
+        # @since 1.3.0
+        attr_accessor :key_file
     
         attr_accessor :format, :user_agent, :default_headers
         
-         
         def initialize
-          @scheme = 'https'
-          @host = 'api.mastercard.com'
-          @base_path = ''
           @timeout = 0
-          @verify_ssl = false #To be set to true for production
-          @inject_format = false
-          @force_ending_format = false
+          @verify_ssl = true
+          @verify_ssl_host = true
+          @cert_file = nil
+          @key_file = nil
           @format = ""
           @default_headers = {}
-    
+      
           yield(self) if block_given?
         end
     
@@ -55,27 +66,6 @@ module MastercardCoreSdk
           yield(self) if block_given?
         end
     
-        def scheme=(scheme)
-          # remove :// from scheme
-          @scheme = scheme.sub(/:\/\//, '')
-        end
-    
-        def host=(host)
-          # remove http(s):// and anything after a slash
-          @host = host.sub(/https?:\/\//, '').split('/').first
-        end
-    
-        def base_path=(base_path)
-          # Add leading and trailing slashes to base_path
-          @base_path = "/#{base_path}".gsub(/\/+/, '/')
-          @base_path = "" if @base_path == "/"
-        end
-    
-        def base_url
-          url = "#{scheme}://#{[host, base_path].join('/').gsub(/\/+/, '/')}".sub(/\/+\z/, '')
-          URI.encode(url)
-        end
-    
       end
    end
 end

data/lib/mastercard_core_sdk/core/mastercard_api_configuration.rb

@@ -4,7 +4,7 @@ require_relative 'api_config_builder'
 
 module MastercardCoreSdk
   module Core
-    # Setting MasterCard API configuration parameters for API calls
+    # Setting MasterCard API configuration parameters for API calls.
     class MasterCardApiConfiguration
 
       @@logger = Logging.logger[self]
@@ -52,8 +52,8 @@ module MastercardCoreSdk
           end
         end
 
-        # Registers the API configuration.
-        # @param api_config The API configuration.
+        # Register the ApiConfig object.
+        # @param api_config the ApiConfig object.
         def register_config(api_config)
           self.configs.merge!({ api_config.name => api_config })
         end

data/lib/mastercard_core_sdk/core/mastercard_authenticator.rb

@@ -13,6 +13,9 @@ module MastercardCoreSdk
       
       attr_accessor :api_tracker
       
+      # Hook into before a request runs.
+      #
+      # Adds the Authorization, API tracking and user-agent information to request header and logs the request/response information.
       def authenticate
         Typhoeus.before do |request|
           SignatureBuilder.build(request)

data/lib/mastercard_core_sdk/core/query_params.rb

@@ -1,5 +1,6 @@
 module MastercardCoreSdk
   module Core
+    # Container for query string data used to make service request url.
     class QueryParams
 
       attr_reader :params
@@ -8,12 +9,20 @@ module MastercardCoreSdk
         @params = {}
       end
 
+      # Merge query string parameters as key,value pair into params hash.
+      # 
+      # @param key the params key.
+      # @param value the params value.
+      # @return [Object] the QueryParams object.
       def add(key, value)
         key = key.to_sym if key.is_a?(String)
         @params.merge!({ key => value })
         return self
       end
 
+      # Gets the query string parameters.
+      #
+      # @return [Hash] the params hash containing key value pair.
       def params
         @params
       end

data/lib/mastercard_core_sdk/core/request_response_logger.rb

@@ -4,14 +4,15 @@ require_relative  '../exceptions/sdk_validation_error'
 
 module MastercardCoreSdk
   module Core
-    # Class for defining log statements; it is called by logging interceptor for logging.
+    # Logs the request and response content.
     class RequestResponseLogger
       include MastercardCoreSdk::Exceptions
 
       NEWLINE = "\n"
       @@logger = Logging.logger[self]
       
-      # Method called by interceptor to log request
+      # Log the request content.
+      # @param request the typhoeus request content to be logged.
       def self.log_request(request)
         if request
 
@@ -41,7 +42,8 @@ module MastercardCoreSdk
         end
       end
 
-      # Method called by interceptor to log response
+      # Log the response content.
+      # @param response the typhoeus response content to be logged.
       def self.log_response(response)
         if response
 
@@ -85,7 +87,7 @@ module MastercardCoreSdk
         end
       end
 	  
-	  private
+	    private
       
       def self.mask_data(response_body)
         xmldoc = Nokogiri::XML(response_body)

data/lib/mastercard_core_sdk/core/service_request.rb

@@ -1,5 +1,6 @@
 module MastercardCoreSdk
   module Core
+    # Set all required request parameters and pass it to the API client.
     class ServiceRequest
 
       attr_accessor :headers, :path_params, :query_params, :body, :content_type

data/lib/mastercard_core_sdk/exceptions/error_handler.rb

@@ -26,6 +26,7 @@ module MastercardCoreSdk
       ERR_INTERNAL = "INTERNAL_PROCESSING_ERROR"
       SEP_COLON = "]: "
       ERR_MSG_RES_PARSE = "Exception occurred during response parsing."
+      ERR_SRC_UNREACHABLE = "Unreachable"
       
       # Raise custom error as per response error object.
       # @param error_response The Typheous::Response object containing error details.
@@ -36,9 +37,16 @@ module MastercardCoreSdk
         response_status_code = error_response.response_code
 
         if response_body.empty?
-          errors = get_errors_object(ERR_DESC_EMPTY_RES, ERR_REASON_EMPTY_BODY_RES, ERR_SRC_UNKN)
-          @@logger.error "400 #{ERR_SRC_UNKN}"
-          raise SDKResponseError.new(:errors_object => errors, :status_code => 400)
+          if response_status_code == 0
+            response = error_response.response
+            errors = get_errors_object(response.return_message, response.return_code.to_s.upcase, ERR_SRC_UNREACHABLE) if response.return_message && response.return_code
+            @@logger.error "0 #{ERR_SRC_UNREACHABLE}"
+            raise SDKResponseError.new(:errors_object => errors, :status_code => 0)
+          else
+            errors = get_errors_object(ERR_DESC_EMPTY_RES, ERR_REASON_EMPTY_BODY_RES, ERR_SRC_UNKN)
+            @@logger.error "400 #{ERR_SRC_UNKN}"
+            raise SDKResponseError.new(:errors_object => errors, :status_code => 400)
+          end
           
         elsif response_status_code == 200
           # In some cases, response code is 200 and response body is empty.
@@ -82,6 +90,12 @@ module MastercardCoreSdk
 
       private
 
+      # Return new Errors object with error description, reason code, source.
+      #  
+      # @param description the error description.
+      # @param reason_code the error reason code.
+      # @param source the error source.
+      # @return [Errors] the Errors object.
       def get_errors_object(description, reason_code, source)
         error = Error.new(:description => description, :reason_code => reason_code, :source => source, :recoverable => false)
         return Errors.new(:error => [error])

data/lib/mastercard_core_sdk/interceptors/api_tracker_builder.rb

@@ -3,7 +3,7 @@ require_relative '../exceptions/sdk_validation_error'
 
 module MastercardCoreSdk
   module Interceptors
-    # Intercepts request for modifying headers for API calls tracking
+    # Interceptor to set SDK tracking information in each request header.
     class ApiTrackerBuilder
       include MastercardCoreSdk::Core, MastercardCoreSdk::Exceptions
 

data/lib/mastercard_core_sdk/version.rb

@@ -1,3 +1,3 @@
 module MastercardCoreSdk
-   VERSION = "1.2.0"
+   VERSION = "1.3.0"
 end

data/lib/mastercard_core_sdk.rb

@@ -61,5 +61,20 @@ require_relative 'mastercard_core_sdk/core/api_config_builder'
 
 
 module MastercardCoreSdk
-   # Base Sdk
+   # Core Sdk
+   class << self
+      # Customize default settings for the SDK using block.
+      #   MastercardCoreSdk.configure do |config|
+      #     config.ssl_ca_cert = <path to the certificate file to verify the peer>
+      #   end
+      # If no block given, return the default Configuration object.
+      # @since 1.3.0      
+      def configure
+        if block_given?
+          yield(Core::Configuration.default)
+        else
+          Core::Configuration.default
+        end
+      end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mastercard_core_sdk
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - MasterCard
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-23 00:00:00.000000000 Z
+date: 2017-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler