yoti 1.6.0 → 1.7.0

data/lib/yoti/dynamic_share_service/extension/thirdparty_attribute_extension.rb

@@ -1,58 +1,119 @@
 # frozen_string_literal: true
 
+require 'time'
+
 module Yoti
   module DynamicSharingService
+    class ThirdPartyAttributeDefinition
+      #
+      # @param [String] name
+      #
+      def initialize(name)
+        @name = name
+      end
+
+      def as_json(*_args)
+        { name: @name }
+      end
+
+      def to_json(*_args)
+        as_json.to_json
+      end
+    end
+
     class ThirdPartyAttributeExtensionBuilder
       def initialize
         @expiry_date = nil
         @definitions = []
       end
 
+      #
+      # @param [DateTime,Time] expiry_date
+      #
+      # @return [self]
+      #
       def with_expiry_date(expiry_date)
         @expiry_date = expiry_date
         self
       end
 
+      #
+      # @param [String] names
+      #
+      # @return [self]
+      #
       def with_definitions(*names)
-        names.each do |s|
-          @definitions += [{ name: s }]
+        @definitions += names.map do |name|
+          ThirdPartyAttributeDefinition.new(name)
         end
         self
       end
 
+      #
+      # @return [ThirdPartyAttributeExtension]
+      #
       def build
-        extension = ThirdPartyAttributeExtension.new
-        extension.instance_variable_get(:@content)[:expiry_date] = @expiry_date
-        extension.instance_variable_get(:@content)[:definitions] = @definitions
-        extension
+        content = ThirdPartyAttributeExtensionContent.new(@expiry_date, @definitions)
+        ThirdPartyAttributeExtension.new(content)
       end
     end
 
     class ThirdPartyAttributeExtension
       EXTENSION_TYPE = 'THIRD_PARTY_ATTRIBUTE'
 
+      # @return [ThirdPartyAttributeExtensionContent]
       attr_reader :content
+
+      # @return [String]
       attr_reader :type
 
-      def initialize
-        @content = {}
+      #
+      # @param [ThirdPartyAttributeExtensionContent] content
+      #
+      def initialize(content = nil)
+        @content = content
         @type = EXTENSION_TYPE
       end
 
       def as_json(*_args)
-        {
-          type: @type,
-          content: @content
-        }
+        json = {}
+        json[:type] = @type
+        json[:content] = @content.as_json unless @content.nil?
+        json
       end
 
       def to_json(*_args)
         as_json.to_json
       end
 
+      #
+      # @return [ThirdPartyAttributeExtensionBuilder]
+      #
       def self.builder
         ThirdPartyAttributeExtensionBuilder.new
       end
     end
+
+    class ThirdPartyAttributeExtensionContent
+      #
+      # @param [DateTime,Time] expiry_date
+      # @param [Array<ThirdPartyAttributeDefinition>] definitions
+      #
+      def initialize(expiry_date, definitions)
+        @expiry_date = expiry_date
+        @definitions = definitions
+      end
+
+      def as_json(*_args)
+        json = {}
+        json[:expiry_date] = @expiry_date.to_time.utc.strftime('%FT%T.%3NZ') unless @expiry_date.nil?
+        json[:definitions] = @definitions.map(&:as_json)
+        json
+      end
+
+      def to_json(*_args)
+        as_json.to_json
+      end
+    end
   end
 end

data/lib/yoti/dynamic_share_service/policy/dynamic_policy.rb

@@ -16,8 +16,8 @@ module Yoti
         false
       end
 
-      def to_json(*args)
-        as_json.to_json(*args)
+      def to_json(*_args)
+        as_json.to_json
       end
 
       def as_json(*_args)
@@ -105,19 +105,19 @@ module Yoti
       end
 
       def with_family_name(options = {})
-        with_wanted_attribute_by_name Attribute::FAMILY_NAME, options
+        with_wanted_attribute_by_name Attribute::FAMILY_NAME, **options
       end
 
       def with_given_names(options = {})
-        with_wanted_attribute_by_name Attribute::GIVEN_NAMES, options
+        with_wanted_attribute_by_name Attribute::GIVEN_NAMES, **options
       end
 
       def with_full_name(options = {})
-        with_wanted_attribute_by_name Attribute::FULL_NAME, options
+        with_wanted_attribute_by_name Attribute::FULL_NAME, **options
       end
 
       def with_date_of_birth(options = {})
-        with_wanted_attribute_by_name Attribute::DATE_OF_BIRTH, options
+        with_wanted_attribute_by_name Attribute::DATE_OF_BIRTH, **options
       end
 
       #
@@ -135,45 +135,45 @@ module Yoti
       end
 
       #
-      # @param [Integer] derivation
+      # @param [Integer] age
       #
       def with_age_over(age, options = {})
-        with_age_derived_attribute(Attribute::AGE_OVER + age.to_s, options)
+        with_age_derived_attribute(Attribute::AGE_OVER + age.to_s, **options)
       end
 
       #
-      # @param [Integer] derivation
+      # @param [Integer] age
       #
       def with_age_under(age, options = {})
-        with_age_derived_attribute(Attribute::AGE_UNDER + age.to_s, options)
+        with_age_derived_attribute(Attribute::AGE_UNDER + age.to_s, **options)
       end
 
       def with_gender(options = {})
-        with_wanted_attribute_by_name Attribute::GENDER, options
+        with_wanted_attribute_by_name Attribute::GENDER, **options
       end
 
       def with_postal_address(options = {})
-        with_wanted_attribute_by_name(Attribute::POSTAL_ADDRESS, options)
+        with_wanted_attribute_by_name(Attribute::POSTAL_ADDRESS, **options)
       end
 
       def with_structured_postal_address(options = {})
-        with_wanted_attribute_by_name(Attribute::STRUCTURED_POSTAL_ADDRESS, options)
+        with_wanted_attribute_by_name(Attribute::STRUCTURED_POSTAL_ADDRESS, **options)
       end
 
       def with_nationality(options = {})
-        with_wanted_attribute_by_name(Attribute::NATIONALITY, options)
+        with_wanted_attribute_by_name(Attribute::NATIONALITY, **options)
       end
 
       def with_phone_number(options = {})
-        with_wanted_attribute_by_name(Attribute::PHONE_NUMBER, options)
+        with_wanted_attribute_by_name(Attribute::PHONE_NUMBER, **options)
       end
 
       def with_selfie(options = {})
-        with_wanted_attribute_by_name(Attribute::SELFIE, options)
+        with_wanted_attribute_by_name(Attribute::SELFIE, **options)
       end
 
       def with_email(options = {})
-        with_wanted_attribute_by_name(Attribute::EMAIL_ADDRESS, options)
+        with_wanted_attribute_by_name(Attribute::EMAIL_ADDRESS, **options)
       end
 
       def with_document_details

data/lib/yoti/dynamic_share_service/share_url.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module Yoti
   module DynamicSharingService
     class Share
@@ -11,50 +13,33 @@ module Yoti
       end
     end
 
-    def self.create_share_url_endpoint
-      "/qrcodes/apps/#{Yoti.configuration.client_sdk_id}"
-    end
-
-    def self.create_share_url_query
-      "?nonce=#{SecureRandom.uuid}&timestamp=#{Time.now.to_i}"
-    end
-
     def self.create_share_url(scenario)
-      endpoint = "#{create_share_url_endpoint}#{create_share_url_query}"
-      uri = URI("#{Yoti.configuration.api_endpoint}#{endpoint}")
-
-      unsigned = Net::HTTP::Post.new uri
-      unsigned.body = scenario.to_json
+      yoti_request = Yoti::Request
+                     .builder
+                     .with_http_method('POST')
+                     .with_base_url(Yoti.configuration.api_endpoint)
+                     .with_endpoint("qrcodes/apps/#{Yoti.configuration.client_sdk_id}")
+                     .with_query_param('appId', Yoti.configuration.client_sdk_id)
+                     .with_payload(scenario)
+                     .build
 
-      signed_request = Yoti::SignedRequest.new(
-        unsigned,
-        endpoint,
-        scenario
-      ).sign
+      begin
+        create_share_url_parse_response yoti_request.execute
+      rescue Yoti::RequestError => e
+        raise if e.response.nil?
 
-      response = Net::HTTP.start(
-        uri.hostname,
-        uri.port,
-        use_ssl: true
-      ) do |http|
-        http.request signed_request
-      end
-
-      create_share_url_parse_response response
-    end
-
-    def self.create_share_url_parse_response(response)
-      if response.code.to_i < 200 || response.code.to_i >= 300
-        case response.code
+        case e.response.code
         when '400'
           raise InvalidDataError
         when '404'
           raise ApplicationNotFoundError
         else
-          raise UnknownHTTPError, response.code
+          raise UnknownHTTPError, e.response.code
         end
       end
+    end
 
+    def self.create_share_url_parse_response(response)
       Share.new JSON.parse response.body
     end
 
@@ -76,5 +61,15 @@ module Yoti
         super msg
       end
     end
+
+    # @deprecated no longer used - will be removed in 2.0.0
+    def self.create_share_url_query
+      "?nonce=#{SecureRandom.uuid}&timestamp=#{Time.now.to_i}"
+    end
+
+    # @deprecated no longer used - will be removed in 2.0.0
+    def self.create_share_url_endpoint
+      "/qrcodes/apps/#{Yoti.configuration.client_sdk_id}"
+    end
   end
 end

data/lib/yoti/errors.rb

@@ -3,12 +3,27 @@ module Yoti
   class ProtobufError < StandardError; end
 
   # Raises exceptions related to API requests
-  class RequestError < StandardError; end
+  class RequestError < StandardError
+    attr_reader :response
+
+    def initialize(message, response = nil)
+      super(append_response_message(message, response))
+      @response = response
+    end
+
+    private
+
+    def append_response_message(message, response)
+      return message if response.nil? || response.body.empty?
+
+      "#{message}: #{response.body}"
+    end
+  end
 
   # Raises exceptions related to OpenSSL actions
   class SslError < StandardError; end
 
-  # Raises exceptions realted to an incorrect gem configuration value
+  # Raises exceptions related to an incorrect gem configuration value
   class ConfigurationError < StandardError; end
 
   # Raises exceptions related to AML actions

data/lib/yoti/http/aml_check_request.rb

@@ -1,13 +1,16 @@
 module Yoti
   # Manage the API's AML check requests
   class AmlCheckRequest
+    #
+    # @param [AmlProfile] aml_profile
+    #
     def initialize(aml_profile)
       @aml_profile = aml_profile
       @payload = aml_profile.payload
       @request = request
     end
 
-    # @return [String] a JSON representation of the AML check response
+    # @return [Hash] a JSON representation of the AML check response
     def response
       JSON.parse(@request.body)
     end
@@ -15,11 +18,14 @@ module Yoti
     private
 
     def request
-      yoti_request = Yoti::Request.new
-      yoti_request.http_method = 'POST'
-      yoti_request.endpoint = 'aml-check'
-      yoti_request.payload = @payload
-      yoti_request
+      Yoti::Request
+        .builder
+        .with_http_method('POST')
+        .with_base_url(Yoti.configuration.api_endpoint)
+        .with_endpoint('aml-check')
+        .with_query_param('appId', Yoti.configuration.client_sdk_id)
+        .with_payload(@payload)
+        .build
     end
   end
 end

data/lib/yoti/http/payloads/aml_address.rb

@@ -7,6 +7,10 @@ module Yoti
     # @return [String] the postcode required for USA, optional otherwise
     attr_accessor :post_code
 
+    #
+    # @param [String] country
+    # @param [String] post_code
+    #
     def initialize(country, post_code = nil)
       raise AmlError, 'AmlAddress requires a country.' if country.to_s.empty?
 

data/lib/yoti/http/payloads/aml_profile.rb

@@ -1,6 +1,12 @@
 module Yoti
   # Manages the AML check Profile object
   class AmlProfile
+    #
+    # @param [String] given_names
+    # @param [String] family_name
+    # @param [AmlAddress] aml_address
+    # @param [String] ssn
+    #
     def initialize(given_names, family_name, aml_address, ssn = nil)
       @given_names = given_names
       @family_name = family_name
@@ -11,7 +17,7 @@ module Yoti
       raise AmlError, 'Request for USA require a valid SSN and postcode.' if usa_invalid
     end
 
-    # @return [Object] the AML check request body
+    # @return [Hash] the AML check request body
     def payload
       {
         given_names: @given_names,

data/lib/yoti/http/profile_request.rb

@@ -1,6 +1,9 @@
 module Yoti
   # Manage the API's profile requests
   class ProfileRequest
+    #
+    # @param [String] encrypted_connect_token
+    #
     def initialize(encrypted_connect_token)
       @encrypted_connect_token = encrypted_connect_token
       @request = request
@@ -14,12 +17,14 @@ module Yoti
     private
 
     def request
-      yoti_request = Yoti::Request.new
-      yoti_request.add_header('X-Yoti-Auth-Key', Yoti::SSL.auth_key_from_pem)
-      yoti_request.encrypted_connect_token = @encrypted_connect_token
-      yoti_request.http_method = 'GET'
-      yoti_request.endpoint = 'profile'
-      yoti_request
+      Yoti::Request
+        .builder
+        .with_http_method('GET')
+        .with_base_url(Yoti.configuration.api_endpoint)
+        .with_endpoint("profile/#{Yoti::SSL.decrypt_token(@encrypted_connect_token)}")
+        .with_query_param('appId', Yoti.configuration.client_sdk_id)
+        .with_header('X-Yoti-Auth-Key', Yoti::SSL.auth_key_from_pem)
+        .build
     end
   end
 end

data/lib/yoti/http/request.rb

@@ -1,9 +1,18 @@
+require 'securerandom'
+
 module Yoti
   # Manage the API's HTTPS requests
   class Request
+    # @deprecated will be removed in 2.0.0 - token is now provided with the endpoint
     # @return [String] the URL token received from Yoti Connect
     attr_accessor :encrypted_connect_token
 
+    # @return [String] the base URL
+    attr_writer :base_url
+
+    # @return [Hash] query params to add to the request
+    attr_accessor :query_params
+
     # @return [String] the HTTP method used for the request
     # The allowed methods are: GET, DELETE, POST, PUT, PATCH
     attr_accessor :http_method
@@ -11,36 +20,93 @@ module Yoti
     # @return [String] the API endpoint for the request
     attr_accessor :endpoint
 
-    # @return [Hash] the body sent with the request
+    # @return [#to_json,String] the body sent with the request
     attr_accessor :payload
 
     def initialize
       @headers = {}
     end
 
+    #
+    # @return [RequestBuilder]
+    #
+    def self.builder
+      RequestBuilder.new
+    end
+
+    #
     # Adds a HTTP header to the request
+    #
+    # @param [String] header
+    # @param [String] value
+    #
     def add_header(header, value)
       @headers[header] = value
     end
 
+    #
     # Makes a HTTP request after signing the headers
-    # @return [Hash] the body from the HTTP request
-    def body
+    #
+    # @return [HTTPResponse]
+    #
+    def execute
       raise RequestError, 'The request requires a HTTP method.' unless @http_method
-      raise RequestError, 'The payload needs to be a hash.' unless @payload.to_s.empty? || @payload.is_a?(Hash)
 
-      res = Net::HTTP.start(uri.hostname, Yoti.configuration.api_port, use_ssl: https_uri?) do |http|
+      http_res = Net::HTTP.start(uri.hostname, Yoti.configuration.api_port, use_ssl: https_uri?) do |http|
         signed_request = SignedRequest.new(unsigned_request, path, @payload).sign
         http.request(signed_request)
       end
 
-      raise RequestError, "Unsuccessful Yoti API call: #{res.message}" unless res.code == '200'
+      raise RequestError.new("Unsuccessful Yoti API call: #{http_res.message}", http_res) unless response_is_success(http_res)
 
-      res.body
+      http_res
+    end
+
+    #
+    # Makes a HTTP request and returns the body after signing the headers
+    #
+    # @return [String]
+    #
+    def body
+      execute.body
+    end
+
+    #
+    # @return [String] the base URL
+    #
+    def base_url
+      @base_url ||= Yoti.configuration.api_endpoint
     end
 
     private
 
+    #
+    # @param [Net::HTTPResponse] http_res
+    #
+    # @return [Boolean]
+    #
+    def response_is_success(http_res)
+      http_res.code.to_i >= 200 && http_res.code.to_i < 300
+    end
+
+    #
+    # Adds payload to provided HTTP request
+    #
+    # @param [Net::HTTPRequest] http_req
+    #
+    def add_payload(http_req)
+      return if @payload.to_s.empty?
+
+      if @payload.is_a?(String)
+        http_req.body = @payload
+      elsif @payload.respond_to?(:to_json)
+        http_req.body = @payload.to_json
+      end
+    end
+
+    #
+    # @return [Net::HTTPRequest] the unsigned HTTP request
+    #
     def unsigned_request
       case @http_method
       when 'GET'
@@ -49,13 +115,13 @@ module Yoti
         http_req = Net::HTTP::Delete.new(uri)
       when 'POST'
         http_req = Net::HTTP::Post.new(uri)
-        http_req.body = @payload.to_json unless @payload.to_s.empty?
+        add_payload(http_req)
       when 'PUT'
         http_req = Net::HTTP::Put.new(uri)
-        http_req.body = @payload.to_json unless @payload.to_s.empty?
+        add_payload(http_req)
       when 'PATCH'
         http_req = Net::HTTP::Patch.new(uri)
-        http_req.body = @payload.to_json unless @payload.to_s.empty?
+        add_payload(http_req)
       else
         raise RequestError, "Request method not allowed: #{@http_method}"
       end
@@ -67,22 +133,27 @@ module Yoti
       http_req
     end
 
+    #
+    # @return [URI] the full request URI
+    #
     def uri
-      @uri ||= URI(Yoti.configuration.api_endpoint + path)
+      @uri ||= URI(base_url + path)
     end
 
+    #
+    # @return [String] the path with query string
+    #
     def path
       @path ||= begin
-        nonce = SecureRandom.uuid
-        timestamp = Time.now.to_i
-
-        "/#{@endpoint}/#{token}"\
-        "?nonce=#{nonce}"\
-        "&timestamp=#{timestamp}"\
-        "&appId=#{Yoti.configuration.client_sdk_id}"
+        "/#{@endpoint}/#{token}".chomp('/') + "?#{query_string}"
       end
     end
 
+    #
+    # @deprecated will be removed in 2.0.0 - token is now provided with the endpoint
+    #
+    # @return [String] the decrypted connect token
+    #
     def token
       return '' unless @encrypted_connect_token
 
@@ -92,5 +163,136 @@ module Yoti
     def https_uri?
       uri.scheme == 'https'
     end
+
+    #
+    # Builds query string including nonce and timestamp
+    #
+    # @return [String]
+    #
+    def query_string
+      params = {
+        nonce: SecureRandom.uuid,
+        timestamp: Time.now.to_i
+      }
+
+      if @query_params.nil?
+        # @deprecated this default will be removed in 2.0.0
+        # Append appId when no custom query params are provided.
+        params.merge!(appId: Yoti.configuration.client_sdk_id)
+      else
+        Validation.assert_is_a(Hash, @query_params, 'query_params')
+        params.merge!(@query_params)
+      end
+
+      params.map do |k, v|
+        CGI.escape(k.to_s) + '=' + CGI.escape(v.to_s)
+      end.join('&')
+    end
+  end
+
+  #
+  # Builder for {Request}
+  #
+  class RequestBuilder
+    def initialize
+      @headers = {}
+      @query_params = {}
+    end
+
+    #
+    # Sets the base URL
+    #
+    # @param [String] base_url
+    #
+    # @return [self]
+    #
+    def with_base_url(base_url)
+      Validation.assert_is_a(String, base_url, 'base_url')
+      @base_url = base_url
+      self
+    end
+
+    #
+    # Adds a HTTP header to the request
+    #
+    # @param [String] header
+    # @param [String] value
+    #
+    # @return [self]
+    #
+    def with_header(header, value)
+      Validation.assert_is_a(String, header, 'header')
+      Validation.assert_is_a(String, value, 'value')
+      @headers[header] = value
+      self
+    end
+
+    #
+    # Adds a query parameter to the request
+    #
+    # @param [String] key
+    # @param [String] value
+    #
+    # @return [self]
+    #
+    def with_query_param(key, value)
+      Validation.assert_is_a(String, key, 'key')
+      Validation.assert_is_a(String, value, 'value')
+      @query_params[key] = value
+      self
+    end
+
+    #
+    # Sets the HTTP method
+    #
+    # @param [String] http_method
+    #
+    # @return [self]
+    #
+    def with_http_method(http_method)
+      Validation.assert_is_a(String, http_method, 'http_method')
+      @http_method = http_method
+      self
+    end
+
+    #
+    # Sets the API endpoint for the request
+    #
+    # @param [String] endpoint
+    #
+    # @return [self]
+    #
+    def with_endpoint(endpoint)
+      Validation.assert_is_a(String, endpoint, 'endpoint')
+      @endpoint = endpoint
+      self
+    end
+
+    #
+    # Sets the body sent with the request
+    #
+    # @param [#to_json,String] payload
+    #
+    # @return [self]
+    #
+    def with_payload(payload)
+      Validation.assert_respond_to(:to_json, payload, 'payload') unless payload.is_a?(String)
+      @payload = payload
+      self
+    end
+
+    #
+    # @return [Request]
+    #
+    def build
+      request = Request.new
+      request.base_url = @base_url
+      request.endpoint = @endpoint
+      request.query_params = @query_params
+      request.http_method = @http_method
+      request.payload = @payload
+      @headers.map { |k, v| request.add_header(k, v) }
+      request
+    end
   end
 end