minfraud 1.0.4 → 2.4.0

data/lib/minfraud/components/shopping_cart.rb

@@ -1,27 +1,34 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
+    # ShoppingCart corresponds to the shopping_cart object of a minFraud
+    # request.
+    #
+    # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart
     class ShoppingCart < Base
-      # @attribute items
-      # @return [Array] An array of Minfraud::Components::ShoppingCartItem instances
-
+      # An array of Minfraud::Components::ShoppingCartItem instances.
+      #
+      # @return [Array<Minfraud::Components::ShoppingCartItem>]
       attr_accessor :items
-      # Creates Minfraud::Components::ShoppingCart instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::ShoppingCart] ShoppingCart instance
-      def initialize(params = {})
+
+      # @param params [Array] Array of shopping cart items. You may provide
+      #   each item as either a Hash where each key is a symbol corresponding
+      #   to an item's field, or as a Minfraud:::Components::ShoppingCartItem
+      #   object.
+      def initialize(params = [])
         @items = params.map(&method(:resolve))
       end
 
-      # @return [Array] a JSON representation of Minfraud::Components::ShoppingCart items
-      def to_json
+      # A JSON representation of Minfraud::Components::ShoppingCart items.
+      #
+      # @return [Array]
+      def to_json(*_args)
         @items.map(&:to_json)
       end
 
       private
 
-      # @param  [Hash] params hash of parameters for Minfraud::Components::ShoppingCartItem
-      # or Minfraud::Components::ShoppingCartItem instance
-      # @return [Minfraud::Components::ShoppingCart] ShoppingCart instance
       def resolve(params)
         params.is_a?(ShoppingCartItem) ? params : ShoppingCartItem.new(params)
       end

data/lib/minfraud/components/shopping_cart_item.rb

@@ -1,33 +1,62 @@
+# frozen_string_literal: true
+
 module Minfraud
   module Components
+    # ShoppingCartItem corresponds to objects in the shopping_cart object
+    # of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart--item
     class ShoppingCartItem < Base
-      # @attribute category
-      # @return [String] The category of the item
+      include Minfraud::Validates
+
+      # The category of the item. This can also be a hashed value; see link.
+      #
+      # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart--item__category
+      #
+      # @return [String, nil]
       attr_accessor :category
 
-      # @attribute item_id
-      # @return [String] The internal ID of the item
+      # The internal ID of the item. This can also be a hashed value; see link.
+      #
+      # @see https://dev.maxmind.com/minfraud/api-documentation/requests?lang=en#schema--request--shopping-cart--item__item_id
+      #
+      # @return [String, nil]
       attr_accessor :item_id
 
-      # @attribute quantity
-      # @return [Integer] The quantity of the item in the shopping cart
+      # The quantity of the item in the shopping cart. The value must be at
+      # least 0, at most 10^13-1, and have no fractional part.
+      #
+      # @return [Integer, nil]
       attr_accessor :quantity
 
-      # @attribute price
-      # @return [Float] The per-unit price of this item in the shopping cart. This should use the same currency as the order currency
+      # The per-unit price of this item in the shopping cart. This should use
+      # the same currency as the order currency. The value must be at least 0
+      # and at most 1e14 - 1.
+      #
+      # @return [Float, nil]
       attr_accessor :price
 
-      # Creates Minfraud::Components::ShoppingCartItem instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::ShoppingCartItem] ShoppingCartItem instance
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
         @category = params[:category]
         @item_id  = params[:item_id]
         @quantity = params[:quantity]
         @price    = params[:price]
+
+        validate
+      end
+
+      private
+
+      def validate
+        return if !Minfraud.enable_validation
+
+        validate_string('category', 255, @category)
+        validate_string('item_id', 255, @item_id)
+        validate_nonnegative_integer('quantity', @quantity)
+        validate_nonnegative_number('price', @price)
       end
     end
   end
 end
-
-

data/lib/minfraud/enum.rb

@@ -1,19 +1,30 @@
+# frozen_string_literal: true
+
 module Minfraud
+  # Enum provides helpers for working with attributes with enumerated types.
   module Enum
     def self.included(base)
       base.extend(ClassMethods)
     end
 
+    # ClassMethods provides helpers for working with attributes with enumerated
+    # types.
     module ClassMethods
-      # Returns a hash with in the following format: attribute_name => permitted_values
-      # @return [Hash] mapping
+      # Returns a hash in the following format: attribute_name =>
+      # permitted_values
+      #
+      # @return [Hash]
       def mapping
         @mapping ||= {}
       end
 
-      # Creates a set of methods for enum-like behaviour of the attribute
-      # @param [Symbol] attribute attribute name
-      # @param [Array] assignable_values a set of values which are permitted
+      # Create a set of methods for enum-like behavior of the attribute.
+      #
+      # @param attribute [Symbol] The attribute name.
+      #
+      # @param assignable_values [Array] The set of permitted values.
+      #
+      # @return [nil]
       def enum_accessor(attribute, assignable_values)
         mapping[attribute] = assignable_values.map(&:intern)
 
@@ -21,13 +32,16 @@ module Minfraud
           define_method("#{attribute}_values") { mapping[attribute] }
         end
 
-        self.class_eval do
-          define_method("#{attribute}") { instance_variable_get("@#{attribute}") }
+        class_eval do
+          define_method(attribute.to_s) { instance_variable_get("@#{attribute}") }
           define_method "#{attribute}=" do |value|
-            raise NotEnumValueError,  'Value is not permitted' if value && !self.class.mapping[attribute].include?(value.intern)
+            raise NotEnumValueError, 'Value is not permitted' if value && !self.class.mapping[attribute].include?(value.intern)
+
             instance_variable_set("@#{attribute}", value ? value.intern : nil)
           end
         end
+
+        nil
       end
     end
   end

data/lib/minfraud/error_handler.rb

@@ -1,37 +1,64 @@
+# frozen_string_literal: true
+
 module Minfraud
+  # ErrorHandler provides a method to raise exceptions on errors.
   module ErrorHandler
     class << self
-      # Returns a response if status code is 200, rises an error otherwise
-      # @param [Minfraud::HTTPService::Response] response
-      # @return [Minfraud::HTTPService::Response] if status code is 200
-      def inspect(response)
-        return response if response.status == 200
+      # Return the response if the HTTP status code is 2xx. Otherwise raise
+      # an error.
+      #
+      # @param response [Minfraud::HTTPService::Response]
+      #
+      # @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 examine(response)
+        return response if response.status > 199 && response.status < 300
 
-        raise *STATUS_CODES.fetch(response.code, [ServerError, 'Server error'])
+        raise(*STATUS_CODES.fetch(response.code, [ServerError, 'Server error']))
       end
 
-      # A hash that maps status codes returned by minFraud with errors & messages
+      # @!visibility private
       STATUS_CODES = {
-        IP_ADDRESS_INVALID:    [
-          ClientError, 'You have no supplied a valid IPv4 or IPv6 address'
+        JSON_INVALID:          [
+          ClientError, 'JSON body cannot be decoded'
         ],
-        IP_ADDRESS_REQUIRED:   [
-          ClientError,  'You have not supplied an IP address which is required filed'
+        MAXMIND_ID_INVALID:    [
+          ClientError, 'You have not supplied a valid maxmind_id'
         ],
-        IP_ADDRESS_RESERVED:   [
-          ClientError, 'You have supplied an IP address which is reserved'
+        MINFRAUD_ID_INVALID:   [
+          ClientError, 'You have not supplied a valid minfraud_id'
         ],
-        JSON_INVALID:          [
-          ClientError, 'JSON body cannot be decoded'
+        PARAMETER_UNKNOWN:     [
+          ClientError, 'You have supplied an unknown parameter'
+        ],
+        REQUEST_INVALID:       [
+          ClientError, 'The request did not contain any valid input values.'
+        ],
+        TAG_REQUIRED:          [
+          ClientError, 'You have not supplied a tag, which is a required field'
+        ],
+        TAG_INVALID:           [
+          ClientError, 'You have not supplied a valid tag'
+        ],
+        ACCOUNT_ID_REQUIRED:   [
+          AuthorizationError, 'You have not supplied a account ID'
         ],
         AUTHORIZATION_INVALID: [
-          AuthorizationError, 'Invalid license key and / or user id'
+          AuthorizationError, 'Invalid license key and / or account ID'
         ],
         LICENSE_KEY_REQUIRED:  [
           AuthorizationError, 'You have not supplied a license key'
         ],
         USER_ID_REQUIRED:      [
-          AuthorizationError, 'You have not supplied a user id'
+          AuthorizationError, 'You have not supplied a account id'
         ],
         INSUFFICIENT_FUNDS:    [
           ClientError, 'The license key you have provided does not have a sufficient funds to use this service'
@@ -39,7 +66,7 @@ module Minfraud
         PERMISSION_REQUIRED:   [
           ClientError, 'You do not have permission to use this service'
         ]
-      }
+      }.freeze
     end
   end
 end

data/lib/minfraud/errors.rb

@@ -1,10 +1,30 @@
+# frozen_string_literal: true
+
 module Minfraud
-  # A list of Minfraud custom errors
-  class BaseError          < StandardError; end
+  # The base error class for Minfraud exceptions.
+  class BaseError < StandardError; end
+
+  # An error indicating the input value is not valid.
+  class InvalidInputError < BaseError; end
 
+  # An error indicating the value is not valid for the enumerated type.
   class NotEnumValueError  < BaseError; end
+
+  # An error indicating the field is not recognized.
   class RequestFormatError < BaseError; end
+
+  # An error indicating minFraud cannot serve your request as there is a
+  # problem on the client side.
+  #
+  # For example, this may happen if there is a problem with the format or
+  # contents of your request, if you lack funds to use the service, or if you
+  # don't have permission to use the service.
   class ClientError        < BaseError; end
+
+  # An error indicating there is a problem with authorization or
+  # authentication.
   class AuthorizationError < BaseError; end
+
+  # An error indicating the server had an error handling the request.
   class ServerError        < BaseError; end
 end

data/lib/minfraud/http_service/response.rb

@@ -1,32 +1,76 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'minfraud/model/error'
+require 'minfraud/model/factors'
+require 'minfraud/model/insights'
+require 'minfraud/model/score'
+
 module Minfraud
   module HTTPService
+    # Response class for HTTP requests.
     class Response
-      # @attribute status
-      # @return [Integer] HTTP response status
+      # Response HTTP status code.
+      #
+      # @return [Fixnum, nil]
       attr_reader :status
 
-      # @attribute body
-      # @return [Hash] HTTP response body
+      # Response model.
+      #
+      # @return [Minfraud::Model::Score, Minfraud::Model::Insights,
+      #   Minfraud::Model::Factors, nil]
       attr_reader :body
 
-      # @attribute headers
-      # @return [Hash] HTTP response headers
-      attr_reader :headers
-
-      # Creates Minfraud::HTTPService::Response instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::HTTPService::Response] Response instance
-      def initialize(params = {})
-        @status  = params[:status]
-        @body    = params[:body]
-        @headers = params[:headers]
+      # @param endpoint [Symbol, nil] endpoint name, like :score.
+      #
+      # @param locales [Array<String>, nil] locales, like ["en"].
+      #
+      # @param response [HTTP::Response] the response object.
+      #
+      # @param body [String] the response body.
+      #
+      # @raise [JSON::ParserError] if there was invalid JSON in the response.
+      def initialize(endpoint, locales, response, body)
+        @status = response.code
+
+        @body = make_body(
+          endpoint,
+          locales,
+          response,
+          body,
+        )
       end
 
-      # Returns minFraud specific response code
-      # @return [Symbol] minFraud specific request code
+      # Return the minFraud-specific response code.
+      #
+      # @return [Symbol, nil]
       def code
+        return nil if body.nil?
+
         body.code.intern if body.respond_to?(:code) && body.code
       end
+
+      private
+
+      def make_body(endpoint, locales, response, body)
+        if !response.mime_type || !response.mime_type.match(/json/i)
+          return nil
+        end
+
+        h = JSON.parse(body)
+
+        if @status != 200
+          return Minfraud::Model::Error.new(h)
+        end
+
+        ENDPOINT_TO_CLASS[endpoint].new(h, locales)
+      end
+
+      ENDPOINT_TO_CLASS = {
+        factors:  Minfraud::Model::Factors,
+        insights: Minfraud::Model::Insights,
+        score:    Minfraud::Model::Score
+      }.freeze
     end
   end
 end

data/lib/minfraud/model/abstract.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Minfraud
+  module Model
+    # @!visibility private
+    class Abstract
+      def initialize(record)
+        @record = record
+      end
+
+      protected
+
+      def get(key)
+        return nil if @record.nil? || !@record.key?(key)
+
+        @record[key]
+      end
+    end
+  end
+end

data/lib/minfraud/model/address.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Abstract model for a postal address.
+    class Address < Abstract
+      # The distance in kilometers from the address to the IP location.
+      #
+      # @return [Integer, nil]
+      attr_reader :distance_to_ip_location
+
+      # This property is true if the address is in the IP country. The property
+      # is false when the address is not in the IP country. If the address
+      # could not be parsed or was not provided or if the IP address could not
+      # be geolocated, the property will be nil.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_in_ip_country
+
+      # This property is true if the postal code provided with the address is
+      # in the city for the address. The property is false when the postal code
+      # is not in the city. If the address was not provided or could not be
+      # parsed, the property will be nil.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_postal_in_city
+
+      # The latitude associated with the address.
+      #
+      # @return [Float, nil]
+      attr_reader :latitude
+
+      # The longitude associated with the address.
+      #
+      # @return [Float, nil]
+      attr_reader :longitude
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @distance_to_ip_location = get('distance_to_ip_location')
+        @is_in_ip_country        = get('is_in_ip_country')
+        @is_postal_in_city       = get('is_postal_in_city')
+        @latitude                = get('latitude')
+        @longitude               = get('longitude')
+      end
+    end
+  end
+end

data/lib/minfraud/model/billing_address.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/address'
+
+module Minfraud
+  module Model
+    # Model containing information about the billing address.
+    class BillingAddress < Address
+    end
+  end
+end

data/lib/minfraud/model/credit_card.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+require 'minfraud/model/issuer'
+
+module Minfraud
+  module Model
+    # Model with details about the credit card used.
+    class CreditCard < Abstract
+      # The card brand, such as "Visa", "Discover", "American Express", etc.
+      #
+      # @return [String, nil]
+      attr_reader :brand
+
+      # This property contains the two letter ISO 3166-1 alpha-2 country code
+      # (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) associated with the
+      # location of the majority of customers using this credit card as
+      # determined by their billing address. In cases where the location of
+      # customers is highly mixed, this defaults to the country of the bank
+      # issuing the card.
+      #
+      # @return [String, nil]
+      attr_reader :country
+
+      # This property is true if the card is a business card.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_business
+
+      # This property is true if the country of the billing address matches the
+      # country of the majority of customers using this credit card. In cases
+      # where the location of customers is highly mixed, the match is to the
+      # country of the bank issuing the card.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_issued_in_billing_address_country
+
+      # This property is true if the card is a prepaid card.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_prepaid
+
+      # This property is true if the card is a virtual card.
+      #
+      # @return [Boolean, nil]
+      attr_reader :is_virtual
+
+      # An object containing information about the credit card issuer.
+      #
+      # @return [Minfraud::Model::Issuer]
+      attr_reader :issuer
+
+      # The card's type. The valid values are: charge, credit, debit.
+      #
+      # @return [String, nil]
+      attr_reader :type
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @brand                                = get('brand')
+        @country                              = get('country')
+        @is_business                          = get('is_business')
+        @is_issued_in_billing_address_country = get(
+          'is_issued_in_billing_address_country'
+        )
+        @is_prepaid                           = get('is_prepaid')
+        @is_virtual                           = get('is_virtual')
+        @issuer                               = Minfraud::Model::Issuer.new(get('issuer'))
+        @type                                 = get('type')
+      end
+    end
+  end
+end

data/lib/minfraud/model/device.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Model with information about the device.
+    #
+    # In order to receive device output from minFraud Insights or minFraud
+    # Factors, you must be using the Device Tracking Add-on
+    # (https://dev.maxmind.com/minfraud/track-devices?lang=en).
+    class Device < Abstract
+      # This number represents our confidence that the device_id refers to a
+      # unique device as opposed to a cluster of similar devices. A confidence
+      # of 0.01 indicates very low confidence that the device is unique,
+      # whereas 99 indicates very high confidence.
+      #
+      # @return [Float, nil]
+      attr_reader :confidence
+
+      # A UUID that MaxMind uses for the device associated with this IP
+      # address.
+      #
+      # @return [String, nil]
+      attr_reader :id
+
+      # This is the date and time of the last sighting of the device. This is
+      # an RFC 3339 date-time.
+      #
+      # @return [String, nil]
+      attr_reader :last_seen
+
+      # This is the local date and time of the transaction in the time zone of
+      # the device. This is determined by using the UTC offset associated with
+      # the device. This is an RFC 3339 date-time
+      #
+      # @return [String, nil]
+      attr_reader :local_time
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @confidence = get('confidence')
+        @id         = get('id')
+        @last_seen  = get('last_seen')
+        @local_time = get('local_time')
+      end
+    end
+  end
+end

data/lib/minfraud/model/disposition.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'minfraud/model/abstract'
+
+module Minfraud
+  module Model
+    # Model with the disposition set by custom rules.
+    #
+    # In order to receive a disposition, you must be using minFraud custom
+    # rules.
+    class Disposition < Abstract
+      # The action to take on the transaction as defined by your custom rules.
+      # The current set of values are "accept", "manual_review", "reject", and
+      # "test". If you do not have custom rules set up, this will be nil.
+      #
+      # @return [String, nil]
+      attr_reader :action
+
+      # The reason for the action. The current possible values are
+      # "custom_rule" and "default". If you do not have custom rules set up,
+      # this will be nil.
+      #
+      # @return [String, nil]
+      attr_reader :reason
+
+      # The label of the custom rule that was triggered. If you do not have
+      # custom rules set up, the triggered custom rule does not have a label,
+      # or no custom rule was triggered, this will be nil.
+      # @return [String, nil]
+      attr_reader :rule_label
+
+      # @!visibility private
+      def initialize(record)
+        super(record)
+
+        @action     = get('action')
+        @reason     = get('reason')
+        @rule_label = get('rule_label')
+      end
+    end
+  end
+end