minfraud 1.0.4 → 2.4.0

data/README.md

@@ -1,12 +1,14 @@
-# Simple Ruby Wrapper to the MaxMind minFraud API
+# Ruby API for MaxMind minFraud Services
 
-[![Code Climate](https://codeclimate.com/github/kushniryb/minfraud-api-v2/badges/gpa.svg)](https://codeclimate.com/github/kushniryb/minfraud-api-v2)
-[![Coverage Status](https://coveralls.io/repos/github/kushniryb/minfraud-api-v2/badge.svg?branch=master)](https://coveralls.io/github/kushniryb/minfraud-api-v2?branch=master)
-[![Build Status](https://travis-ci.org/kushniryb/minfraud-api-v2.svg?branch=master)](https://travis-ci.org/kushniryb/minfraud-api-v2)
+## Description
 
-Compatible with version minFraud API v2.0
+This package provides an API for the [MaxMind minFraud web
+services](https://dev.maxmind.com/minfraud?lang=en). This includes minFraud Score,
+Insights, and Factors. It also includes our [minFraud Report Transaction
+API](https://dev.maxmind.com/minfraud/report-a-transaction?lang=en).
 
-[minFraud API documentation](http://dev.maxmind.com/minfraud/)
+The legacy minFraud Standard and Premium services are not supported by this
+API.
 
 ## Installation
 
@@ -18,90 +20,285 @@ gem 'minfraud'
 
 And then execute:
 
-```ruby
+```
 $ bundle
 ```
 
 Or install it yourself as:
+
 ```
 $ gem install minfraud
 ```
 
-## Configuration
+## API Documentation
+
+See the [API documentation](https://www.rubydoc.info/gems/minfraud) for
+more details.
+
+## Usage
+
+### Configuration
+
+An account ID and license key are required to work with the web services.
+Configure these before making a request:
+
+```ruby
+Minfraud.configure do |c|
+  c.account_id  = 12345
+  c.license_key = 'your_license_key'
+  c.enable_validation = true
+end
+````
 
-User Id and License Key are required to work with minFraud API
+To use the Sandbox web service instead of the production web service, you can provide the host:
 
 ```ruby
 Minfraud.configure do |c|
+  c.account_id  = 12345
   c.license_key = 'your_license_key'
-  c.user_id     = 'your_user_id'
+  c.host = 'sandbox.maxmind.com'
 end
 ```
 
-## Usage
+### Making a minFraud Score, Insights, or Factors Request
+
+To use the minFraud API, create a `Minfraud::Assessments` object. The
+constructor takes a hash of symbols corresponding to each component of the
+minFraud request. You can also set components by their attribute after
+creating the object.
+
+After populating the object, call the method for the minFraud endpoint you
+want to use: `#score`, `#insights`, or `#factors`. The returned value is a
+`MinFraud::Response` object. You can access the response model through its
+`#body` attribute.
+
+An exception will be thrown for critical errors. You should check for
+`warnings` related to your inputs after a request.
+
 ```ruby
-# You can either provide a hash of params to initializer
+# Prepare the request.
 assessment = Minfraud::Assessments.new(
   device: {
-    ip_address: '1.2.3.4.5'
-  }
+    ip_address:      '152.216.7.110',
+    accept_language: 'en-US,en;q=0.8',
+    session_age:     3600.5,
+    session_id:      'foo',
+    user_agent:      'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36',
+  },
+  event: {
+    transaction_id: 'txn3134133',
+    shop_id:        's2123',
+    time:           '2012-04-12T23:20:50+00:00',
+    type:           :purchase,
+  },
+  account: {
+    user_id:      '3132',
+    username_md5: '4f9726678c438914fa04bdb8c1a24088',
+  },
+  email: {
+    address: 'test@maxmind.com',
+    domain:  'maxmind.com',
+  },
+  billing: {
+    first_name:         'First',
+    last_name:          'Last',
+    company:            'Company',
+    address:            '101 Address Rd.',
+    address_2:          'Unit 5',
+    city:               'New Haven',
+    region:             'CT',
+    country:            'US',
+    postal:             '06510',
+    phone_number:       '123-456-7890',
+    phone_country_code: '1',
+  },
+  shipping: {
+    first_name:         'ShipFirst',
+    last_name:          'ShipLast',
+    company:            'ShipCo',
+    address:            '322 Ship Addr. Ln.',
+    address_2:          'St. 43',
+    city:               'Nowhere',
+    region:             'OK',
+    country:            'US',
+    postal:             '73003',
+    phone_number:       '123-456-0000',
+    phone_country_code: '1',
+    delivery_speed:     :same_day,
+  },
+  payment: {
+    processor:      :stripe,
+    was_authorized: false,
+    decline_code:   'invalid number',
+  },
+  credit_card: {
+    issuer_id_number:         '411111',
+    last_digits:              '7643',
+    bank_name:                'Bank of No Hope',
+    bank_phone_country_code:  '1',
+    bank_phone_number:        '123-456-1234',
+    token:                    'abcd',
+    avs_result:               'Y',
+    cvv_result:               'N',
+    was_3d_secure_successful: true,
+  },
+  order: {
+    amount:           323.21,
+    currency:         'USD',
+    discount_code:    'FIRST',
+    is_gift:          true,
+    has_gift_message: false,
+    affiliate_id:     'af12',
+    subaffiliate_id:  'saf42',
+    referrer_uri:     'http://www.amazon.com/',
+  },
+  shopping_cart: [
+    {
+      category: 'pets',
+      item_id:  'leash-0231',
+      quantity: 2,
+      price:    20.43,
+    },
+    {
+      category: 'beauty',
+      item_id:  'msc-1232',
+      quantity: 1,
+      price:    100.00,
+    },
+  ],
+  custom_inputs: {
+    section:            'news',
+    previous_purchases: 19,
+    discount:           3.2,
+    previous_user:      true,
+  },
 )
-# or create a component and assign them to assessments object directly, e.g
-device = Minfraud::Components::Device.new(ip_address: '1.2.3.4.5')
-assessment = Minfraud::Assessments.new(device: device)
-# or
-assessment = Minfraud::Assessments.new
-assessment.device = device
-# There are multiple components that reflect minFraud request top level keys
-
-# Some components will raise an error if provided with the wrong values for attributes, e.g
-event = Minfraud::Components::Event.new(type: 'foobar') # => Minfraud::NotEnumValueError
-# You can check the list of permitted values for the attribute by calling a class method
-Minfraud::Components::Event.type_values # => ["account_creation", "account_login", ....]
-
-# You can now call 3 different minFraud endpoints: score, insights, factors
-assessment.insights
-assessment.factors
-
-result = assessment.score # => Minfraud::Response instance
-
-result.status  # => Response status code
-result.code    # => minFraud specific response code
-result.body    # => Mashified body
-result.headers # => Response headers
-
-# You can also change data inbetween requests
-first_request = assessment.insights
-assessment.device.ip_address = '22.22.22.33'
-second_request = assessment.insights
+
+# To get the Factors response model, use #factors.
+factors_model = assessment.factors.body
+
+factors_model.warnings.each { |w| puts w.warning }
+
+p factors_model.subscores.email_address
+p factors_model.risk_score
+
+# To get the Insights response model, use #insights.
+insights_model = assessment.insights.body
+
+insights_model.warnings.each { |w| puts w.warning }
+
+p insights_model.credit_card.issuer.name
+p insights_model.risk_score
+
+# To get the Score response model, use #score.
+score_model = assessment.score.body
+
+score_model.warnings.each { |w| puts w.warning }
+
+p score_model.risk_score
 ```
 
-### Exception handling
+See the [API documentation](https://www.rubydoc.info/gems/minfraud) for
+more details.
 
-Gem is supplied with four different types of exceptions:
-```ruby
-# Raised if unpermitted key is provided to Minfraud::Assessments initializer
-class RequestFormatError < BaseError; end
+### Reporting a Transaction to MaxMind
 
-# Raised if IP address is absent / it is reserved / JSON body can not be decoded
-class ClientError < BaseError; end
+MaxMind encourages the use of this API, as data received through this
+channel is used to improve the accuracy of their fraud detection
+algorithms.
 
-# Raised if there are some problems with the user id and / or license key
-class AuthorizationError < BaseError; end
+To use the Report Transaction API, create a
+`Minfraud::Components::Report::Transaction` object. An IP address and a
+valid tag are required arguments for this API. Additional parameters may be
+set, as shown below.
 
-# Raised if minFraud returns an error, or if there is an HTTP error
-class ServerError < BaseError; end
+If the report is successful, nothing is returned. If the report fails, an
+exception will be thrown.
 
-# Raised if an attribute value doesn't belong to the predefined set of values
-class NotEnumValueError < BaseError; end
+```ruby
+# The report_transaction method only makes use of a transaction component:
+txn = Minfraud::Components::Report::Transaction.new(
+  ip_address:     '152.216.7.110',
+  tag:            :suspected_fraud,
+  maxmind_id:     '12345678',
+  minfraud_id:    '58fa38d8-4b87-458b-a22b-f00eda1aa20d',
+  notes:          'notes go here',
+  transaction_id: '1FA254yZ'
+)
+reporter = Minfraud::Report.new(transaction: txn)
+reporter.report_transaction
 ```
 
+See the [API documentation](https://www.rubydoc.info/gems/minfraud) for
+more details.
+
+### Persistent HTTP Connections
+
+This gem supports persistent HTTP connections, allowing you to avoid the
+overhead of creating a new HTTP connection for each minFraud request if you
+plan to perform more than one. You do not need to do anything to enable
+this functionality.
+
+### Exceptions
+
+The gem supplies several distinct exception-types:
+
+* `RequestFormatError` - Raised if an unknown key is provided to the
+  `Minfraud::Assessments` constructor
+* `ClientError` - Raised if the IP address is absent, reserved, or the JSON
+  body cannot be decoded
+* `AuthorizationError` - Raised if there are problems with the account ID
+  and/or license key
+* `ServerError` - Raised if minFraud returns an error or if there is an
+  HTTP error
+* `NotEnumValueError` - Raised if an attribute value doesn't belong to the
+  predefined set of values
+
+### Thread Safety
+
+This gem is safe for use from multiple threads.
+
+`Minfraud::Assessments` and `Minfraud::Report` objects must not be shared
+across threads.
+
+Please note that you must run `Minfraud.configure` before calling any
+functionality using multiple threads.
+
+## Support
+
+Please report all issues with this code using the
+[GitHub issue tracker](https://github.com/maxmind/minfraud-api-ruby/issues).
+
+If you are having an issue with the minFraud service that is not specific
+to the client API, please see
+[our support page](https://www.maxmind.com/en/support).
+
+## Requirements
+
+This gem works with Ruby 2.7 and above.
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub [here](https://github.com/kushniryb/minfraud-api-v2). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/maxmind/minfraud-api-ruby). This project is
+intended to be a safe, welcoming space for collaboration, and contributors
+are expected to adhere to the [Contributor
+Covenant](https://contributor-covenant.org) code of conduct.
+
+## Versioning
+
+This API uses [Semantic Versioning](https://semver.org/).
+
+## Copyright and License
+
+Copyright (c) 2016-2020 kushnir.yb.
 
+Copyright (c) 2020-2024 MaxMind, Inc.
 
-## License
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+## Thank You
 
+This gem is the work of the creator and original maintainer kushnir.yb
+(@kushniryb).

data/Rakefile

@@ -1,6 +1,12 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+RuboCop::RakeTask.new
+
+task default: :spec
+task default: :rubocop

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "minfraud"
+require 'bundler/setup'
+require 'minfraud'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "minfraud"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start

data/dev-bin/release.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+set -eu -o pipefail
+
+changelog=$(cat CHANGELOG.md)
+
+regex='
+## v([0-9]+\.[0-9]+\.[0-9]+) \(([0-9]{4}-[0-9]{2}-[0-9]{2})\)
+
+((.|
+)*)
+'
+
+if [[ ! $changelog =~ $regex ]]; then
+      echo "Could not find date line in change log!"
+      exit 1
+fi
+
+version="${BASH_REMATCH[1]}"
+date="${BASH_REMATCH[2]}"
+notes="$(echo "${BASH_REMATCH[3]}" | sed -n -E '/^## v[0-9]+\.[0-9]+\.[0-9]+/,$!p')"
+
+echo "$notes"
+if [[ "$date" != "$(date +"%Y-%m-%d")" ]]; then
+    echo "$date is not today!"
+    exit 1
+fi
+
+tag="v$version"
+
+if [ -n "$(git status --porcelain)" ]; then
+    echo ". is not clean." >&2
+    exit 1
+fi
+
+perl -pi -e "s/(?<=VERSION = \').+?(?=\')/$version/g" lib/minfraud/version.rb
+
+echo $"Test results:"
+
+rake
+
+echo $'\nDiff:'
+git diff
+
+echo $'\nRelease notes:'
+echo "$notes"
+
+read -e -p "Commit changes and push to origin? " should_push
+
+if [ "$should_push" != "y" ]; then
+    echo "Aborting"
+    exit 1
+fi
+
+git commit -m "Update for $tag" -a
+
+git push
+
+gh release create --target "$(git branch --show-current)" -t "$version" -n "$notes" "$tag"

data/lib/minfraud/assessments.rb

@@ -1,92 +1,166 @@
+# frozen_string_literal: true
+
 module Minfraud
+  # Assessments is used to perform minFraud Score, Insights, and Factors
+  # requests.
+  #
+  # @see https://dev.maxmind.com/minfraud?lang=en
   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 device
-    # @return [Minfraud::Components::Device] Device component
+    # The CustomInputs component.
+    #
+    # @return [Minfraud::Components::CustomInputs, nil]
+    attr_accessor :custom_inputs
+
+    # 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::ShoppingCarat] 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?
+
       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(
-          status:  raw.status.to_i,
-          body:    raw.body,
-          headers: raw.headers
-        )
+    # Perform a minFraud Factors request.
+    #
+    # @return [Minfraud::HTTPService::Response]
+    #
+    # @raise [JSON::ParserError] if there was invalid JSON in the 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
 
-        ::Minfraud::ErrorHandler.inspect(response)
-      end
+    # Perform a minFraud Insights request.
+    #
+    # @return [Minfraud::HTTPService::Response]
+    #
+    # @raise [JSON::ParserError] if there was invalid JSON in the 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 [JSON::ParserError] if there was invalid JSON in the 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 request_body
-      MAPPING.keys.inject({}) do |mem, e|
-        next mem unless value = send(e)
-        mem.merge!(e.to_s => value.to_json)
+
+    def perform_request(endpoint)
+      response = nil
+      body     = nil
+      Minfraud.connection_pool.with do |client|
+        response = client.post(
+          "/minfraud/v2.0/#{endpoint}",
+          json: request_body,
+        )
+
+        body = response.to_s
       end
+
+      response = ::Minfraud::HTTPService::Response.new(
+        endpoint,
+        @locales,
+        response,
+        body,
+      )
+
+      ::Minfraud::ErrorHandler.examine(response)
     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)
+    def request_body
+      MAPPING.keys.reduce({}) do |mem, e|
+        next mem unless (value = send(e))
+
+        mem.merge!(e.to_s => value.to_json)
+      end
     end
   end
 end