Merge pull request #5 from maxmind/rafl/new-outputs

Add new minFraud outputs

Author: oschwald

HISTORY.rst

@@ -3,6 +3,16 @@
 History
 -------
 
+* Added support for new minFraud Insights outputs. These are:
+     * ``/credit_card/brand``
+     * ``/credit_card/type``
+     * ``/device/id``
+     * ``/email/is_free``
+     * ``/email/is_high_risk``
+* ``input`` on the ``Warning`` response model has been replaced with
+  ``input_pointer``. The latter is a JSON pointer to the input that
+  caused the warning.
+
 0.2.0 (2015-08-10)
 ++++++++++++++++++
 

minfraud/models.py

@@ -247,6 +247,56 @@ class Issuer(object):
     }
 
 
+@_inflate_to_namedtuple
+class Device(object):
+    """
+    Information about the device associated with the IP address
+
+    .. attribute:: id
+
+      A UUID that MaxMind uses for the device associated with this IP address.
+      Note that many devices cannot be uniquely identified because they are too
+      common (for example, all iPhones of a given model and OS release). In
+      these cases, the minFraud service will simply not return a UUID for that
+      device.
+
+      :type: str
+
+    """
+    __slots__ = ()
+    _fields = {
+        'id': None
+    }
+
+
+@_inflate_to_namedtuple
+class Email(object):
+    """
+    Information about the email address passed in the request
+
+    .. attribute:: is_free
+
+      This field is true if MaxMind believes that this email is hosted by a
+      free email provider such as Gmail or Yahoo! Mail.
+
+      :type: bool | None
+
+    .. attribute:: is_high_risk
+
+      This field is true if MaxMind believes that this email is likely to be
+      used for fraud. Note that this is also factored into the overall
+      `risk_score` in the response as well.
+
+      :type: bool | None
+
+    """
+    __slots__ = ()
+    _fields = {
+        'is_free': None,
+        'is_high_risk': None
+    }
+
+
 @_inflate_to_namedtuple
 class CreditCard(object):
     """
@@ -263,6 +313,12 @@ class CreditCard(object):
 
       :type: str | None
 
+    .. attribute:: brand
+
+      The card brand, such as "Visa", "Discover", "American Express", etc.
+
+      :type: str | None
+
     .. attribute:: is_issued_in_billing_address_country
 
       This property is true if the country of the billing address matches the
@@ -278,6 +334,14 @@ class CreditCard(object):
 
       :type: bool | None
 
+    .. attribute:: type
+
+      The card's type. The valid values are "charge", "credit", and "debit".
+      See Wikipedia for an explanation of the difference between charge and
+      credit cards.
+
+      :type: str | None
+
     .. attribute:: issuer
 
       An object containing information about the credit card issuer.
@@ -289,8 +353,10 @@ class CreditCard(object):
     _fields = {
         'issuer': Issuer,
         'country': None,
+        'brand': None,
         'is_issued_in_billing_address_country': None,
-        'is_prepaid': None
+        'is_prepaid': None,
+        'type': None
     }
 
 
@@ -441,21 +507,20 @@ class ServiceWarning(object):
 
       :type: str
 
-    .. attribute:: input
+    .. attribute:: input_pointer
 
-      This is a tuple of keys representing the path to the input that
+      This is a string representing the path to the input that
       the warning is associated with. For instance, if the warning was about
-      the billing city, the tuple would be ``("billing", "city")``. The key is
-      used for an object and the index number for an array.
+      the billing city, the string would be ``"/billing/city"``.
 
-      :type: tuple[str|int]
+      :type: str
 
     """
     __slots__ = ()
     _fields = {
         'code': None,
         'warning': None,
-        'input': lambda x: tuple(x) if x else ()
+        'input_pointer': None
     }
 
 
@@ -505,6 +570,20 @@ class Insights(object):
 
       :type: CreditCard
 
+    .. attribute:: device
+
+      A :class:`.Device` object containing information about the device that
+      MaxMind believes is associated with the IP address passed in the request.
+
+      :type: Device
+
+    .. attribute:: email
+
+      A :class:`.Email` object containing information about the email address
+      passed in the request.
+
+      :type: Email
+
     .. attribute:: ip_address
 
       A :class:`.IPAddress` object containing GeoIP2 and
@@ -532,6 +611,8 @@ class Insights(object):
         'credits_remaining': None,
         'ip_address': IPAddress,
         'credit_card': CreditCard,
+        'device': Device,
+        'email': Email,
         'shipping_address': ShippingAddress,
         'billing_address': BillingAddress
     }

minfraud/webservice.py

@@ -105,9 +105,8 @@ def _response_for(self, path, model_class, request, validate):
             uri,
             json=cleaned_request,
             auth=(self._user_id, self._license_key),
-            headers=
-            {'Accept': 'application/json',
-             'User-Agent': self._user_agent()},
+            headers={'Accept': 'application/json',
+                     'User-Agent': self._user_agent()},
             timeout=self._timeout)
         if response.status_code == 200:
             return self._handle_success(response, uri, model_class)

tests/__init__.py

@@ -1 +0,0 @@
-

tests/data/insights-response.json

@@ -103,9 +103,18 @@
       "phone_number": "8003421232",
       "matches_provided_phone_number": true
     },
+    "brand": "Visa",
     "country": "US",
     "is_issued_in_billing_address_country": true,
-    "is_prepaid": true
+    "is_prepaid": true,
+    "type": "credit"
+  },
+  "device": {
+    "id": "7835b099-d385-4e5b-969e-7df26181d73b"
+  },
+  "email": {
+    "is_free": true,
+    "is_high_risk": true
   },
   "shipping_address": {
     "distance_to_billing_address": 2227,
@@ -119,19 +128,13 @@
   "warnings": [
     {
       "code": "INPUT_INVALID",
-      "input": [
-        "account",
-        "user_id"
-      ],
+      "input_pointer": "/account/user_id",
       "warning": "Encountered value at \/account\/user_id that does meet the required constraints"
     },
     {
       "code": "INPUT_INVALID",
-      "input": [
-        "account",
-        "username_md5"
-      ],
+      "input_pointer": "/account/username_md5",
       "warning": "Encountered value at \/account\/username_md5 that does meet the required constraints"
     }
   ]
-}
+}

tests/data/score-response.json

@@ -5,19 +5,13 @@
   "warnings": [
     {
       "code": "INPUT_INVALID",
-      "input": [
-        "account",
-        "user_id"
-      ],
+      "input_pointer": "/account/user_id",
       "warning": "Encountered value at \/account\/user_id that does meet the required constraints"
     },
     {
       "code": "INPUT_INVALID",
-      "input": [
-        "account",
-        "username_md5"
-      ],
+      "input_pointer": "/account/username_md5",
       "warning": "Encountered value at \/account\/username_md5 that does meet the required constraints"
     }
   ]
-}
+}

tests/test_models.py

@@ -18,15 +18,16 @@ def test_model_immutability(self):
         T = namedtuple('T', ['obj', 'attr'], {})
         models = [T(GeoIP2Country(), 'iso_code'),
                   T(GeoIP2Location(), 'latitude'), T(Issuer(), 'name'),
-                  T(CreditCard(), 'country'), T(BillingAddress(), 'latitude'),
-                  T(ShippingAddress(), 'latitude'), T(
-                      ServiceWarning(), 'code'), T(Insights(), 'id'),
+                  T(CreditCard(), 'country'), T(Device(), 'id'),
+                  T(Email(), 'is_free'), T(BillingAddress(), 'latitude'),
+                  T(ShippingAddress(), 'latitude'),
+                  T(ServiceWarning(), 'code'), T(Insights(), 'id'),
                   T(Score(), 'id'), T(IPAddress({}), 'city')]
         for model in models:
             for attr in (model.attr, 'does_not_exist'):
                 with self.assertRaises(
-                    AttributeError,
-                    msg='{0!s} - {0}'.format(model.obj, attr)):
+                        AttributeError,
+                        msg='{0!s} - {0}'.format(model.obj, attr)):
                     setattr(model.obj, attr, 5)
 
     def test_billing_address(self):
@@ -63,15 +64,34 @@ def check_address(self, address):
     def test_credit_card(self):
         cc = CreditCard({
             'issuer': {'name': 'Bank'},
+            'brand': 'Visa',
             'country': 'US',
             'is_issued_in_billing_address_country': True,
-            'is_prepaid': True
+            'is_prepaid': True,
+            'type': 'credit'
         })
 
         self.assertEqual('Bank', cc.issuer.name)
+        self.assertEqual('Visa', cc.brand)
         self.assertEqual('US', cc.country)
         self.assertEqual(True, cc.is_prepaid)
         self.assertEqual(True, cc.is_issued_in_billing_address_country)
+        self.assertEqual('credit', cc.type)
+
+    def test_device(self):
+        id = 'b643d445-18b2-4b9d-bad4-c9c4366e402a'
+        device = Device({'id': id})
+
+        self.assertEqual(id, device.id)
+
+    def test_email(self):
+        email = Email({
+            'is_free': True,
+            'is_high_risk': False
+        })
+
+        self.assertEqual(True, email.is_free)
+        self.assertEqual(False, email.is_high_risk)
 
     def test_geoip2_country(self):
         country = GeoIP2Country(is_high_risk=True, iso_code='US')
@@ -112,7 +132,13 @@ def test_insights(self):
         insights = Insights({
             'id': id,
             'ip_address': {'country': {'iso_code': 'US'}},
-            'credit_card': {'is_prepaid': True},
+            'credit_card': {
+                'is_prepaid': True,
+                'brand': 'Visa',
+                'type': 'debit'
+            },
+            'device': {'id': id},
+            'email': {'is_free': True},
             'shipping_address': {'is_in_ip_country': True},
             'billing_address': {'is_in_ip_country': True},
             'credits_remaining': 123,
@@ -122,6 +148,10 @@ def test_insights(self):
 
         self.assertEqual('US', insights.ip_address.country.iso_code)
         self.assertEqual(True, insights.credit_card.is_prepaid)
+        self.assertEqual('Visa', insights.credit_card.brand)
+        self.assertEqual('debit', insights.credit_card.type)
+        self.assertEqual(id, insights.device.id)
+        self.assertEqual(True, insights.email.is_free)
         self.assertEqual(True, insights.shipping_address.is_in_ip_country)
         self.assertEqual(True, insights.billing_address.is_in_ip_country)
         self.assertEqual(id, insights.id)
@@ -167,8 +197,8 @@ def test_warning(self):
         warning = ServiceWarning(
             {'code': code,
              'warning': msg,
-             'input': ["first", "second"]})
+             'input_pointer': "/first/second"})
 
         self.assertEqual(code, warning.code)
         self.assertEqual(msg, warning.warning)
-        self.assertEqual(('first', 'second'), warning.input)
+        self.assertEqual('/first/second', warning.input_pointer)