minfraud 1.2.0 → 1.3.0

data/lib/minfraud/components/payment.rb

@@ -2,10 +2,19 @@
 
 module Minfraud
   module Components
+    # Payment corresponds to the payment object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/#Payment_(/payment)
     class Payment < Base
       include ::Minfraud::Enum
-      # @attribute processor
-      # @return [String] The payment processor used for the transaction
+      include Minfraud::Validates
+
+      # The payment processor used for the transaction. The value is one
+      # listed as a valid value, as a symbol.
+      #
+      # @!attribute processor
+      #
+      # @return [Symbol, nil]
       enum_accessor :processor, [
         :adyen,
         :affirm,
@@ -139,25 +148,36 @@ module Minfraud
         :worldpay
       ]
 
-      # @attribute was_authorized
-      # @return [Boolean] The authorization outcome from the payment processor.
-      #   If the transaction has not yet been approved or denied, do not include
-      #   this field
+      # The authorization outcome from the payment processor. If the
+      # transaction has not yet been approved or denied, do not include this
+      # field.
+      #
+      # @return [Boolean, nil]
       attr_accessor :was_authorized
 
-      # @attribute decline_code
-      # @return [String] The decline code as provided by your payment
-      #   processor. If the transaction was not declined, do not include this
-      #   field
+      # The decline code as provided by your payment processor. If the
+      # transaction was not declined, do not include this field.
+      #
+      # @return [String, nil]
       attr_accessor :decline_code
 
-      # Creates Minfraud::Components::Payment instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::Payment] Payment instance
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
         @was_authorized = params[:was_authorized]
         @decline_code   = params[:decline_code]
         self.processor  = params[:processor]
+
+        validate
+      end
+
+      private
+
+      def validate
+        return if !Minfraud.enable_validation
+
+        validate_boolean('was_authorized', @was_authorized)
+        validate_string('decline_code', 255, @decline_code)
       end
     end
   end

data/lib/minfraud/components/report/transaction.rb

@@ -3,57 +3,68 @@
 module Minfraud
   module Components
     module Report
-      # Contains all of the fields which are used in the report transaction API
+      # Contains the fields used in the Report Transaction API.
+      #
+      # @see https://dev.maxmind.com/minfraud/report-transaction/
       class Transaction < Base
         include ::Minfraud::Enum
 
-        # @!attribute ip_address
-        # @return [String, nil] The IP address of the customer placing the order. This
-        #   should be passed as a string like "44.55.66.77" or "2001:db8::2:1".
+        # The IP address of the customer placing the order. This should be
+        # passed as a string like "152.216.7.110".
+        #
+        # @return [String, nil]
         attr_accessor :ip_address
 
+        # A symbol indicating the likelihood that a transaction may be
+        # fraudulent.
+        #
+        # This may be one of +:chargeback+, +:not_fraud+, +:spam_or_abuse+, or
+        # +:suspected_fraud+.
+        #
         # @!attribute tag
-        # This may be one of +:chargeback+, +:not_fraud+, +:spam_or_abuse+ or +:suspected_fraud+
-        # @return [Symbol, nil] A symbol indicating the likelihood that a transaction
-        #   may be fraudulent.
+        #
+        # @return [Symbol, nil]
         enum_accessor :tag, [:chargeback, :not_fraud, :spam_or_abuse, :suspected_fraud]
 
-        # @attribute chargeback_code
-        # @return [String, nil] A string which is provided by your payment processor
-        #   indicating the reason for the chargeback.
+        # A string which is provided by your payment processor indicating the
+        # reason for the chargeback.
+        #
+        # @return [String, nil]
         attr_accessor :chargeback_code
 
-        # @attribute maxmind_id
-        # @return [String, nil] A unique eight character string identifying a minFraud
-        #   Standard or Premium request. These IDs are returned in the maxmindID
-        #   field of a response for a successful minFraud request. This field is
-        #   not required, but you are encouraged to provide it, if possible.
+        # A unique eight character string identifying a minFraud Standard or
+        # Premium request. These IDs are returned in the maxmindID field of a
+        # response for a successful minFraud request. This field is not
+        # required, but you are encouraged to provide it, if possible.
+        #
+        # @return [String, nil]
         attr_accessor :maxmind_id
 
-        # @attribute minfraud_id
-        # @return [String, nil] A UUID that identifies a minFraud Score, minFraud
-        #   Insights, or minFraud Factors request. This ID is returned at /id in
-        #   the response. This field is not required, but you are encouraged to
-        #   provide it if the request was made to one of these services.
+        # A UUID that identifies a minFraud Score, minFraud Insights, or
+        # minFraud Factors request. This ID is returned at /id in the response.
+        # This field is not required, but you are encouraged to provide it if
+        # the request was made to one of these services.
+        #
+        # @return [String, nil]
         attr_accessor :minfraud_id
 
-        # @attribute notes
-        # @return [String, nil] Your notes on the fraud tag associated with the
-        #   transaction. We manually review many reported transactions to improve
-        #   our scoring for you so any additional details to help us understand
-        #   context are helpful.
+        # Your notes on the fraud tag associated with the transaction. We
+        # manually review many reported transactions to improve our scoring for
+        # you so any additional details to help us understand context are
+        # helpful.
+        #
+        # @return [String, nil]
         attr_accessor :notes
 
-        # @attribute transaction_id
-        # @return [String, nil] The transaction ID you originally passed to minFraud.
-        #   This field is not required, but you are encouraged to provide it or
-        #   the transaction's maxmind_id or minfraud_id
+        # The transaction ID you originally passed to minFraud. This field is
+        # not required, but you are encouraged to provide it or the
+        # transaction's maxmind_id or minfraud_id.
+        #
+        # @return [String, nil]
         attr_accessor :transaction_id
 
-        # Creates Minfraud::Components::Report::Transaction instance
-        # @param  [Hash] params hash of parameters
-        # @return [Minfraud::Components::Report::Transaction] a Report::Transaction
-        #   instance
+        # @param params [Hash] Hash of parameters. Each key/value should
+        #   correspond to one of the available attributes.
         def initialize(params = {})
           @ip_address      = params[:ip_address]
           @chargeback_code = params[:chargeback_code]

data/lib/minfraud/components/shipping.rb

@@ -2,15 +2,22 @@
 
 module Minfraud
   module Components
+    # Shipping corresponds to the shipping object of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/#Shipping_(/shipping)
     class Shipping < Addressable
       include ::Minfraud::Enum
-      # @attribute delivery_speed
-      # @return [String] The shipping delivery speed for the order. The valid values are:
+
+      # The shipping delivery speed for the order. Must be one of +:same_day+,
+      # +:overnight+, +:expedited+, or +:standard+.
+      #
+      # @!attribute delivery_speed
+      #
+      # @return [Symbol, nil]
       enum_accessor :delivery_speed, [:same_day, :overnight, :expedited, :standard]
 
-      # Creates Minfraud::Components::Shipping instance
-      # @param  [Hash] params hash of parameters
-      # @return [Minfraud::Components::Shipping] Shipping instance
+      # @param params [Hash] Hash of parameters. Each key/value should
+      #   correspond to one of the available attributes.
       def initialize(params = {})
         self.delivery_speed = params[:delivery_speed]
         super

data/lib/minfraud/components/shopping_cart.rb

@@ -2,29 +2,33 @@
 
 module Minfraud
   module Components
+    # ShoppingCart corresponds to the shopping_cart object of a minFraud
+    # request.
+    #
+    # @see https://dev.maxmind.com/minfraud/#Shopping_Cart_(/shoppingcart)
     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 as 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
+      # 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

@@ -2,31 +2,60 @@
 
 module Minfraud
   module Components
+    # ShoppingCartItem corresponds to objects in the shopping_cart object
+    # of a minFraud request.
+    #
+    # @see https://dev.maxmind.com/minfraud/#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/#cart-hashing
+      #
+      # @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/#cart-hashing
+      #
+      # @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

data/lib/minfraud/enum.rb

@@ -1,21 +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)
 
@@ -31,6 +40,8 @@ module Minfraud
             instance_variable_set("@#{attribute}", value ? value.intern : nil)
           end
         end
+
+        nil
       end
     end
   end

data/lib/minfraud/error_handler.rb

@@ -1,18 +1,31 @@
 # 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 2xx, raises an error otherwise
-      # @param [Minfraud::HTTPService::Response] response
-      # @return [Minfraud::HTTPService::Response] if status code is 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']))
       end
 
-      # A hash that maps status codes returned by minFraud with errors & messages
+      # @!visibility private
       STATUS_CODES = {
         IP_ADDRESS_INVALID:    [
           ClientError, 'You have not supplied a valid IPv4 or IPv6 address'

data/lib/minfraud/errors.rb

@@ -1,12 +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.rb

@@ -4,13 +4,16 @@ require 'faraday'
 require 'faraday_middleware'
 
 module Minfraud
+  # HTTPService holds the HTTP client configuration.
   module HTTPService
     class << self
-      # @return [Hash] default HTTPService configuration
+      # The default HTTPService configuration.
+      #
+      # @return [Hash]
       def configuration
         server = DEFAULT_SERVER
         if !Minfraud.host.nil?
-          server = 'https://' + Minfraud.host + '/minfraud/v2.0'
+          server = "https://#{Minfraud.host}/minfraud/v2.0"
         end
 
         {
@@ -20,7 +23,7 @@ module Minfraud
       end
     end
 
-    # Minfraud default middleware stack
+    # @!visibility private
     DEFAULT_MIDDLEWARE = proc do |builder|
       builder.request    :json
 
@@ -31,10 +34,12 @@ module Minfraud
 
       builder.response   :json, content_type: /\bjson$/
 
-      builder.adapter    Faraday.default_adapter
+      builder.adapter :net_http_persistent, pool_size: 5 do |http|
+        http.idle_timeout = 30
+      end
     end
 
-    # Minfraud default server
+    # Default base URL for minFraud.
     DEFAULT_SERVER = 'https://minfraud.maxmind.com/minfraud/v2.0'
   end
 end