Merge pull request #177 from maxmind/greg/phone-data

Add new phone outputs

CHANGELOG.md

@@ -8,6 +8,11 @@ CHANGELOG
   parameter optional. Now the `tag` and at least one of the following
   parameters must be supplied: `ipAddress`, `maxmindId`, `minfraudId`,
   `transactionId`.
+* Added `billingPhone` and `shippingPhone` properties to the minFraud Insights
+  and Factors response models. These contain objects with information about
+  the respective phone numbers. Please see [our developer
+  site](https://dev.maxmind.com/minfraud/api-documentation/responses/) for
+  more information.
 
 3.0.1 (2024-05-02)
 ------------------

src/MinFraud/Model/Insights.php

@@ -15,6 +15,12 @@ class Insights implements \JsonSerializable
      */
     public readonly BillingAddress $billingAddress;
 
+    /**
+     * @var Phone an object containing minFraud data related to the billing
+     *            phone used in the transaction
+     */
+    public readonly Phone $billingPhone;
+
     /**
      * @var CreditCard an object containing minFraud data about the credit
      *                 card used in the transaction
@@ -81,6 +87,12 @@ class Insights implements \JsonSerializable
      */
     public readonly ShippingAddress $shippingAddress;
 
+    /**
+     * @var Phone an object containing minFraud data related to the shipping
+     *            phone used in the transaction
+     */
+    public readonly Phone $shippingPhone;
+
     /**
      * @var array This array contains \MaxMind\MinFraud\Model\Warning objects
      *            detailing issues with the request that was sent, such as
@@ -108,11 +120,13 @@ public function __construct(array $response, array $locales = ['en'])
         $this->warnings = $warnings;
 
         $this->billingAddress = new BillingAddress($response['billing_address'] ?? []);
+        $this->billingPhone = new Phone($response['billing_phone'] ?? []);
         $this->creditCard = new CreditCard($response['credit_card'] ?? []);
         $this->device = new Device($response['device'] ?? []);
         $this->email = new Email($response['email'] ?? []);
         $this->ipAddress = new IpAddress($response['ip_address'] ?? [], $locales);
         $this->shippingAddress = new ShippingAddress($response['shipping_address'] ?? []);
+        $this->shippingPhone = new Phone($response['shipping_phone'] ?? []);
     }
 
     public function jsonSerialize(): array
@@ -124,6 +138,11 @@ public function jsonSerialize(): array
             $js['billing_address'] = $billingAddress;
         }
 
+        $billingPhone = $this->billingPhone->jsonSerialize();
+        if (!empty($billingPhone)) {
+            $js['billing_phone'] = $billingPhone;
+        }
+
         $creditCard = $this->creditCard->jsonSerialize();
         if (!empty($creditCard)) {
             $js['credit_card'] = $creditCard;
@@ -163,6 +182,11 @@ public function jsonSerialize(): array
             $js['shipping_address'] = $shippingAddress;
         }
 
+        $shippingPhone = $this->shippingPhone->jsonSerialize();
+        if (!empty($shippingPhone)) {
+            $js['shipping_phone'] = $shippingPhone;
+        }
+
         if (!empty($this->warnings)) {
             $warnings = [];
             foreach ($this->warnings as $warning) {

src/MinFraud/Model/Phone.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MaxMind\MinFraud\Model;
+
+/**
+ * Model containing information about the billing or shipping phone number.
+ */
+class Phone implements \JsonSerializable
+{
+    /**
+     * @var string|null the two-character ISO 3166-1 country code for the
+     *                  country associated with the phone number
+     */
+    public readonly ?string $country;
+
+    /**
+     * @var bool|null This is `true` if the phone number is a Voice over
+     *                Internet Protocol (VoIP) number allocated by a regulator.
+     *                It is `false` if the phone number is not a VoIP number
+     *                allocated by a regulator. It is `null` if a valid number
+     *                was not provided or if we do not have data for the number.
+     */
+    public readonly ?bool $isVoip;
+
+    /**
+     * @var string|null The name of the original network operator associated with
+     *                  the phone number. This property does not reflect phone numbers
+     *                  that have been ported from the original operator to another,
+     *                  nor does it identify mobile virtual network operators.
+     */
+    public readonly ?string $networkOperator;
+
+    /**
+     * @var string|null One of the following values: `fixed` or `mobile`. Additional
+     *                  values may be added in the future.
+     */
+    public readonly ?string $numberType;
+
+    public function __construct(?array $response)
+    {
+        $this->country = $response['country'] ?? null;
+        $this->isVoip = $response['is_voip'] ?? null;
+        $this->networkOperator = $response['network_operator'] ?? null;
+        $this->numberType = $response['number_type'] ?? null;
+    }
+
+    public function jsonSerialize(): array
+    {
+        $js = [];
+
+        if ($this->country !== null) {
+            $js['country'] = $this->country;
+        }
+
+        if ($this->isVoip !== null) {
+            $js['is_voip'] = $this->isVoip;
+        }
+
+        if ($this->networkOperator !== null) {
+            $js['network_operator'] = $this->networkOperator;
+        }
+
+        if ($this->numberType !== null) {
+            $js['number_type'] = $this->numberType;
+        }
+
+        return $js;
+    }
+}

tests/MaxMind/Test/MinFraud/Model/InsightsTest.php

@@ -123,5 +123,17 @@ public function testInsightsProperties(): void
             $insights->ipAddress->traits->mobileNetworkCode,
             'correct mobile network code'
         );
+
+        $this->assertSame(
+            $array['billing_phone']['country'],
+            $insights->billingPhone->country,
+            'correct billing phone country'
+        );
+
+        $this->assertSame(
+            $array['shipping_phone']['country'],
+            $insights->shippingPhone->country,
+            'correct shipping phone country'
+        );
     }
 }

tests/MaxMind/Test/MinFraud/Model/PhoneTest.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MaxMind\Test\MinFraud\Model;
+
+use MaxMind\MinFraud\Model\Phone;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @coversNothing
+ *
+ * @internal
+ */
+class PhoneTest extends TestCase
+{
+    public function testPhone(): void
+    {
+        $array = [
+            'country' => 'US',
+            'is_voip' => true,
+            'network_operator' => 'Verizon/1',
+            'number_type' => 'fixed',
+        ];
+        $phone = new Phone($array);
+
+        $this->assertSame(
+            $array['country'],
+            $phone->country,
+            'country'
+        );
+
+        $this->assertSame(
+            $array['is_voip'],
+            $phone->isVoip,
+            'isVoip'
+        );
+
+        $this->assertSame(
+            $array['network_operator'],
+            $phone->networkOperator,
+            'networkOperator'
+        );
+
+        $this->assertSame(
+            $array['number_type'],
+            $phone->numberType,
+            'numberType'
+        );
+
+        $this->assertSame(
+            $array,
+            $phone->jsonSerialize(),
+            'correctly implements JsonSerializable'
+        );
+    }
+}

tests/MaxMind/Test/MinFraud/ReportTransaction/ReportTransactionTest.php

@@ -64,8 +64,6 @@ public function testRequestsWithNulls(): void
 
     public function testRequiredFields(): void
     {
-        $this->expectNotToPerformAssertions();
-
         $req = [
             'ip_address' => '1.1.1.1',
             'tag' => 'not_fraud',

tests/data/minfraud/factors-response.json

@@ -120,6 +120,12 @@
     "distance_to_ip_location": 5465,
     "is_in_ip_country": false
   },
+  "billing_phone": {
+    "country": "US",
+    "is_voip": true,
+    "network_operator": "Verizon/1",
+    "number_type": "fixed"
+  },
   "credit_card": {
     "issuer": {
       "name": "Bank of No Hope",
@@ -157,6 +163,12 @@
     "latitude": 35.704729,
     "longitude": -97.568619
   },
+  "shipping_phone": {
+    "country": "CA",
+    "is_voip": true,
+    "network_operator": "Telus Mobility-SVR/2",
+    "number_type": "mobile"
+  },
   "subscores": {
     "avs_result": 0.01,
     "billing_address": 0.02,
@@ -189,4 +201,4 @@
       "warning": "Encountered value at /account/username_md5 that does meet the required constraints"
     }
   ]
-}
+}

tests/data/minfraud/insights-response.json

@@ -120,6 +120,12 @@
     "distance_to_ip_location": 5465,
     "is_in_ip_country": false
   },
+  "billing_phone": {
+    "country": "US",
+    "is_voip": true,
+    "network_operator": "Verizon/1",
+    "number_type": "fixed"
+  },
   "credit_card": {
     "issuer": {
       "name": "Bank of No Hope",
@@ -157,6 +163,12 @@
     "latitude": 35.704729,
     "longitude": -97.568619
   },
+  "shipping_phone": {
+    "country": "CA",
+    "is_voip": true,
+    "network_operator": "Telus Mobility-SVR/2",
+    "number_type": "mobile"
+  },
   "warnings": [
     {
       "code": "INPUT_INVALID",
@@ -169,4 +181,4 @@
       "warning": "Encountered value at /account/username_md5 that does meet the required constraints"
     }
   ]
-}
+}