minfraud 1.2.0 → 1.3.0

data/lib/minfraud/assessments.rb

@@ -1,58 +1,76 @@
 # frozen_string_literal: true
 
 module Minfraud
+  # Assessments is used to perform minFraud Score, Insights, and Factors
+  # requests.
+  #
+  # @see https://dev.maxmind.com/minfraud/
   class Assessments
     include ::Minfraud::HTTPService
     include ::Minfraud::Resolver
 
-    # @attribute account
-    # @return [Minfraud::Components::Account] Account component
+    # The Account component.
+    #
+    # @return [Minfraud::Components::Account, nil]
     attr_accessor :account
 
-    # @attribute billing
-    # @return [Minfraud::Components::Billing] Billing component
+    # The Billing component.
+    #
+    # @return [Minfraud::Components::Billing, nil]
     attr_accessor :billing
 
-    # @attribute credit_card
-    # @return [Minfraud::Components::CreditCard] CreditCard component
+    # The CreditCard component.
+    #
+    # @return [Minfraud::Components::CreditCard, nil]
     attr_accessor :credit_card
 
-    # @attribute custom_inputs
-    # @return [Minfraud::Components::CustomInputs] CustomInputs component
+    # The CustomInputs component.
+    #
+    # @return [Minfraud::Components::CustomInputs, nil]
     attr_accessor :custom_inputs
 
-    # @attribute device
-    # @return [Minfraud::Components::Device] Device component
+    # The Device component.
+    #
+    # @return [Minfraud::Components::Device, nil]
     attr_accessor :device
 
-    # @attribute email
-    # @return [Minfraud::Components::Email] Email component
+    # The Email component.
+    #
+    # @return [Minfraud::Components::Email, nil]
     attr_accessor :email
 
-    # @attribute event
-    # @return [Minfraud::Components::Event] Event component
+    # The Event component.
+    #
+    # @return [Minfraud::Components::Event, nil]
     attr_accessor :event
 
-    # @attribute order
-    # @return [Minfraud::Components::Order] Order component
+    # The Order component.
+    #
+    # @return [Minfraud::Components::Order, nil]
     attr_accessor :order
 
-    # @attribute payment
-    # @return [Minfraud::Components::Payment] Payment component
+    # The Payment component.
+    #
+    # @return [Minfraud::Components::Payment, nil]
     attr_accessor :payment
 
-    # @!attribute shipping
-    # @return [Minfraud::Components::Shipping] Shipping component
+    # The Shipping component.
+    #
+    # @return [Minfraud::Components::Shipping, nil]
     attr_accessor :shipping
 
-    # @!attribute shopping_cart
-    # @return [Minfraud::Components::ShoppingCart] ShoppingCart component
+    # The ShoppingCart component.
+    #
+    # @return [Minfraud::Components::ShoppingCart, nil]
     attr_accessor :shopping_cart
 
-    # @param  [Hash] params hash of parameters
-    # @param  [Minfraud::Resolver] resolver resolver that maps params to components
-    # @note In case when params is a Hash of components it just assigns them to the corresponding instance variables
-    # @return [Minfraud::Assessments] Assessments instance
+    # @param params [Hash] Hash of parameters. Each key is a symbol
+    #   corresponding to one of the available component attributes. Values may
+    #   be component objects or hashes that will be provided to the component
+    #   constructors.
+    #
+    # @param resolver [Minfraud::Resolver] Resolver that maps parameters to
+    #   components.
     def initialize(params = {}, resolver = ::Minfraud::Resolver)
       @locales = params.delete('locales')
       @locales = ['en'] if @locales.nil?
@@ -60,34 +78,74 @@ module Minfraud
       resolver.assign(self, params)
     end
 
-    # @!macro [attach] define
-    #   @method $1
-    #   Makes a request to minFraud $1 endpoint.
-    #   Raises an error in case of invalid response
-    #   @return [Minfraud::HTTPService::Response] Wrapped minFraud response
-    def self.define(endpoint)
-      define_method(endpoint) do
-        raw       = request.perform(verb: :post, endpoint: endpoint.to_s, body: request_body)
-        response  = ::Minfraud::HTTPService::Response.new(
-          endpoint: endpoint,
-          locales:  @locales,
-          status:   raw.status.to_i,
-          body:     raw.body,
-          headers:  raw.headers
-        )
-
-        ::Minfraud::ErrorHandler.examine(response)
-      end
+    # Perform a minFraud Factors request.
+    #
+    # @return [Minfraud::HTTPService::Response]
+    #
+    # @raise [Minfraud::AuthorizationError] If there was an authentication
+    #   problem.
+    #
+    # @raise [Minfraud::ClientError] If there was a critical problem with one
+    #   of your inputs.
+    #
+    # @raise [Minfraud::ServerError] If the server reported an error of some
+    #   kind.
+    def factors
+      perform_request(:factors)
+    end
+
+    # Perform a minFraud Insights request.
+    #
+    # @return [Minfraud::HTTPService::Response]
+    #
+    # @raise [Minfraud::AuthorizationError] If there was an authentication
+    #   problem.
+    #
+    # @raise [Minfraud::ClientError] If there was a critical problem with one
+    #   of your inputs.
+    #
+    # @raise [Minfraud::ServerError] If the server reported an error of some
+    #   kind.
+    def insights
+      perform_request(:insights)
     end
 
-    define :score
-    define :insights
-    define :factors
+    # Perform a minFraud Score request.
+    #
+    # @return [Minfraud::HTTPService::Response]
+    #
+    # @raise [Minfraud::AuthorizationError] If there was an authentication
+    #   problem.
+    #
+    # @raise [Minfraud::ClientError] If there was a critical problem with one
+    #   of your inputs.
+    #
+    # @raise [Minfraud::ServerError] If the server reported an error of some
+    #   kind.
+    def score
+      perform_request(:score)
+    end
 
     private
 
-    # Creates a unified request body from components converted to JSON
-    # @return [Hash] Request body
+    def perform_request(endpoint)
+      raw = request.perform(
+        verb:     :post,
+        endpoint: endpoint.to_s,
+        body:     request_body,
+      )
+
+      response = ::Minfraud::HTTPService::Response.new(
+        endpoint: endpoint,
+        locales:  @locales,
+        status:   raw.status.to_i,
+        body:     raw.body,
+        headers:  raw.headers
+      )
+
+      ::Minfraud::ErrorHandler.examine(response)
+    end
+
     def request_body
       MAPPING.keys.reduce({}) do |mem, e|
         next mem unless (value = send(e))
@@ -96,8 +154,6 @@ module Minfraud
       end
     end
 
-    # Creates memoized Minfraud::HTTPService::Request instance
-    # @return [Minfraud::HTTPService::Request] Request instance based on configuration params
     def request
       @request ||= Request.new(::Minfraud::HTTPService.configuration)
     end

data/lib/minfraud/components/account.rb

@@ -2,23 +2,43 @@
 
 module Minfraud
   module Components
+    # Account corresponds to the account object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/#Account_(/account)
     class Account < Base
-      # @attribute user_id
-      # @return [String] A unique user ID associated with the end-user in your system.
-      # If your system allows the login name for the account to be changed, this should not be the login name for the account,
-      # but rather should be an internal ID that does not change. This is not your MaxMind user ID.
+      include Minfraud::Validates
+
+      # A unique user ID associated with the end-user in your system. If your
+      # system allows the login name for the account to be changed, this should
+      # not be the login name for the account, but rather should be an internal
+      # ID that does not change. This is not your MaxMind account ID. No
+      # specific format is required.
+      #
+      # @return [String, nil]
       attr_accessor :user_id
 
-      # @attribute username_md5
-      # @return [String] An MD5 hash as a hexadecimal string of the username or login name associated with the account
+      # An MD5 hash as a hexadecimal string of the username or login name
+      # associated with the account.
+      #
+      # @return [String, nil]
       attr_accessor :username_md5
 
-      # Creates Minfraud::Components::Account instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::Account] an Account instance
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
         @user_id      = params[:user_id]
         @username_md5 = params[:username_md5]
+
+        validate
+      end
+
+      private
+
+      def validate
+        return if !Minfraud.enable_validation
+
+        validate_string('user_id', 255, @user_id)
+        validate_md5('username_md5', @username_md5)
       end
     end
   end

data/lib/minfraud/components/addressable.rb

@@ -2,55 +2,80 @@
 
 module Minfraud
   module Components
+    # This is a parent class for the Billing and Shipping components.
     class Addressable < Base
-      # @attribute first_name
-      # @return [String] The first name of the end user as provided in their billing / shipping information
+      include Minfraud::Validates
+
+      # The first name of the end user as provided in their billing / shipping
+      # information.
+      #
+      # @return [String, nil]
       attr_accessor :first_name
 
-      # @attribute last_name
-      # @return [String] The last name of the end user as provided in their billing / shipping information
+      # The last name of the end user as provided in their billing / shipping
+      # information.
+      #
+      # @return [String, nil]
       attr_accessor :last_name
 
-      # @attribute company
-      # @return [String] The company of the end user as provided in their billing / shipping information
+      # The company of the end user as provided in their billing / shipping
+      # information.
+      #
+      # @return [String, nil]
       attr_accessor :company
 
-      # @attribute address
-      # @return [String] The first line of the user's billing / shipping address
+      # The first line of the user's billing / shipping address.
+      #
+      # @return [String, nil]
       attr_accessor :address
 
-      # @attribute address_2
-      # @return [String] The second line of the user's billing / shipping address
+      # The second line of the user's billing / shipping address.
+      #
+      # @return [String, nil]
       attr_accessor :address_2
 
-      # @attribute city
-      # @return [String] The city of the user's billing / shipping address
+      # The city of the user's billing / shipping address.
+      #
+      # @return [String, nil]
       attr_accessor :city
 
-      # @attribute region
-      # @return [String] The ISO 3166-2 subdivision code for the user's billing / shipping address
+      # The ISO 3166-2 subdivision code for the user's billing / shipping
+      # address.
+      #
+      # @see https://en.wikipedia.org/wiki/ISO_3166-2
+      #
+      # @return [String, nil]
       attr_accessor :region
 
-      # @attribute country
-      # @return [String] The two character ISO 3166-1 alpha-2 country code of the user's billing / shipping address
+      # The two character ISO 3166-1 alpha-2 country code of the user's billing
+      # / shipping address.
+      #
+      # @see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+      #
+      # @return [String, nil]
       attr_accessor :country
 
-      # @attribute postal
-      # @return [String] The postal code of the user's billing / shipping address
+      # The postal code of the user's billing / shipping address.
+      #
+      # @return [String, nil]
       attr_accessor :postal
 
-      # @attribute phone_number
-      # @return [String] The phone number without the country code for the user's billing / shipping address
+      # The phone number without the country code for the user's billing /
+      # shipping address. Punctuation characters will be stripped. After
+      # stripping punctuation characters, the number must contain only digits.
+      #
+      # @return [String, nil]
       attr_accessor :phone_number
 
-      # @attribute phone_country_code
-      # @return [String] The country code for phone number associated with the user's billing / shipping address
+      # The country code for the phone number associated with the user's
+      # billing / shipping address. If you provide this information then you
+      # must provide at least one digit.
+      #
+      # @return [String, nil]
       attr_accessor :phone_country_code
 
-      # Creates Minfraud::Components::Addressable instance
-      # @note This class is used as a parent class for Billing and Shipping components
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::Addressable] an Addressable instance
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
         @first_name         = params[:first_name]
         @last_name          = params[:last_name]
@@ -63,6 +88,26 @@ module Minfraud
         @postal             = params[:postal]
         @phone_number       = params[:phone_number]
         @phone_country_code = params[:phone_country_code]
+
+        validate
+      end
+
+      private
+
+      def validate
+        return if !Minfraud.enable_validation
+
+        validate_string('first_name', 255, @first_name)
+        validate_string('last_name', 255, @last_name)
+        validate_string('company', 255, @company)
+        validate_string('address', 255, @address)
+        validate_string('address_2', 255, @address_2)
+        validate_string('city', 255, @city)
+        validate_subdivision_code('region', @region)
+        validate_country_code('country', @country)
+        validate_string('postal', 255, @postal)
+        validate_string('phone_number', 255, @phone_number)
+        validate_telephone_country_code('phone_country_code', @phone_country_code)
       end
     end
   end

data/lib/minfraud/components/base.rb

@@ -2,20 +2,26 @@
 
 module Minfraud
   module Components
-    # @note This class is used as a parent class for all other components
-    # @note It defines a method which is used for basic JSON representation of PORO objects
+    # This is a parent class for all components. It defines a method which is
+    # used for basic JSON representation of the component objects.
     class Base
-      # @return [Hash] a JSON representation of component attributes
+      # A JSON representation of component attributes.
+      #
+      # @return [Hash]
       def to_json(*_args)
         instance_variables.reduce({}) { |mem, e| populate!(mem, e) }
       end
 
       private
 
-      # @note   This method may modify passed hash. Non-existing instance variables are ignored
-      # @param  [Hash] hash an accumulator
-      # @param  [Symbol] v_sym an instance variable symbol
-      # @return [Hash] a hash containing a JSON representation of instance variable name and it's value
+      # Create a hash containing a JSON representation of instance variable
+      # name and its value.
+      #
+      # @param hash [Hash] An accumulator.
+      #
+      # @param v_sym [Symbol] An instance variable symbol.
+      #
+      # @return [Hash]
       def populate!(hash, v_sym)
         return hash unless (value = instance_variable_get(v_sym))
 
@@ -23,9 +29,13 @@ module Minfraud
         hash.merge!(key => represent(key, value))
       end
 
-      # param [Symbol] key instance variable symbol
-      # param [Object] value instance variable value
-      # @return [Object] value representation according to the request format
+      # Return the value according to the request format.
+      #
+      # @param key [Symbol] An instance variable symbol.
+      #
+      # @param value [Object] An instance variable value.
+      #
+      # @return [Object]
       def represent(key, value)
         BOOLS.include?(key) ? value : value.to_s
       end

data/lib/minfraud/components/billing.rb

@@ -2,6 +2,9 @@
 
 module Minfraud
   module Components
+    # Billing corresponds to the billing object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/#Billing_(/billing)
     class Billing < Addressable; end
   end
 end