Merge pull request #1362 from maxmind/greg/phone-ouputs

Add new phone outputs

Author: ugexe

CHANGELOG.md

@@ -7,6 +7,11 @@ CHANGELOG
 * **Breaking** Updated `TransactionReport` to make the `ipAddress` parameter
   optional. Now the `tag` and at least one of the following paramters 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.
 
 6.1.0 (2024-04-16)
 ------------------

fixtures/insights.json

@@ -195,6 +195,13 @@
         "is_in_ip_country": true
       },
 
+      "shipping_phone": {
+        "country": "CA",
+        "is_voip": true,
+        "network_operator": "Telus Mobility-SVR/2",
+        "number_type": "mobile"
+      },
+
       "billing_address": {
         "is_postal_in_city": true,
         "latitude": 37.545,
@@ -203,6 +210,13 @@
         "is_in_ip_country": true
       },
 
+      "billing_phone": {
+        "country": "US",
+        "is_voip": false,
+        "network_operator": "Verizon/1",
+        "number_type": "fixed"
+      },
+
       "disposition": {
         "action": "accept",
         "reason": "default",

src/response/models/insights.ts

@@ -10,6 +10,11 @@ export default class Insights extends Score {
    * the transaction.
    */
   public readonly billingAddress?: records.BillingAddress;
+  /**
+   * An object containing minFraud data related to the billing phone used in
+   * the transaction.
+   */
+  public readonly billingPhone?: records.Phone;
   /**
    * An object containing minFraud data about the credit card used in the
    * transaction.
@@ -33,6 +38,11 @@ export default class Insights extends Score {
    * An object containing minFraud data related to the shipping address used in the transaction.
    */
   public readonly shippingAddress?: records.ShippingAddress;
+  /**
+   * An object containing minFraud data related to the shipping phone used in
+   * the transaction.
+   */
+  public readonly shippingPhone?: records.Phone;
 
   public constructor(response: webRecords.InsightsResponse) {
     super(response);
@@ -41,6 +51,7 @@ export default class Insights extends Score {
       response,
       'billing_address'
     );
+    this.billingPhone = this.maybeGet<records.Phone>(response, 'billing_phone');
     this.creditCard = this.maybeGet<records.CreditCardRecord>(
       response,
       'credit_card'
@@ -52,6 +63,10 @@ export default class Insights extends Score {
       response,
       'shipping_address'
     );
+    this.shippingPhone = this.maybeGet<records.Phone>(
+      response,
+      'shipping_phone'
+    );
   }
 
   private maybeGet<T>(

src/response/records.ts

@@ -234,6 +234,37 @@ export interface Email {
   readonly isHighRisk?: boolean;
 }
 
+/**
+ * This object contains information about the billing or shipping phone passed
+ * in the request.
+ */
+export interface Phone {
+  /**
+   * A two-character ISO 3166-1 country code for the country associated with
+   * the phone number.
+   */
+  readonly country: string;
+  /**
+   * 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. The property is `null` if a valid
+   * number has not been provided or we do not have data for it.
+   */
+  readonly isVoip?: boolean;
+  /**
+   * 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.
+   */
+  readonly networkOperator: string;
+  /**
+   * One of the following values: `fixed` or `mobile`. Additional values may
+   * be added in the future.
+   */
+  readonly numberType: string;
+}
+
 /**
  * Information about the shipping address.
  */

src/response/web-records.ts

@@ -114,6 +114,13 @@ export interface DispositionWebRecord {
   readonly rule_label?: string;
 }
 
+export interface PhoneWebRecord {
+  readonly country?: string;
+  readonly is_voip?: boolean;
+  readonly network_operator?: string;
+  readonly number_type?: string;
+}
+
 export interface SubscoresWebRecord {
   readonly avs_result?: number;
   readonly billing_address?: number;
@@ -159,7 +166,9 @@ export interface InsightsResponse extends ScoreResponse {
   readonly device: DeviceWebRecord;
   readonly email?: EmailWebRecord;
   readonly shipping_address?: ShippingAddressWebRecord;
+  readonly shipping_phone?: PhoneWebRecord;
   readonly billing_address?: BillingAddressWebRecord;
+  readonly billing_phone?: PhoneWebRecord;
 }
 
 export interface FactorsResponse extends InsightsResponse {

src/webServiceClient.spec.ts

@@ -36,7 +36,7 @@ describe('WebServiceClient', () => {
     });
 
     it('handles "full" responses', async () => {
-      expect.assertions(159);
+      expect.assertions(167);
 
       nockInstance
         .post(fullPath('factors'), factors.request.basic)
@@ -223,12 +223,24 @@ describe('WebServiceClient', () => {
       expect(got.shippingAddress?.distanceToBillingAddress).toEqual(22);
       expect(got.shippingAddress?.isInIpCountry).toEqual(true);
 
+      expect(got.shippingPhone?.country).toEqual('CA');
+      expect(got.shippingPhone?.isVoip).toEqual(true);
+      expect(got.shippingPhone?.networkOperator).toEqual(
+        'Telus Mobility-SVR/2'
+      );
+      expect(got.shippingPhone?.numberType).toEqual('mobile');
+
       expect(got.billingAddress?.isPostalInCity).toEqual(true);
       expect(got.billingAddress?.latitude).toEqual(37.545);
       expect(got.billingAddress?.longitude).toEqual(-122.421);
       expect(got.billingAddress?.distanceToIpLocation).toEqual(100);
       expect(got.billingAddress?.isInIpCountry).toEqual(true);
 
+      expect(got.billingPhone?.country).toEqual('US');
+      expect(got.billingPhone?.isVoip).toEqual(false);
+      expect(got.billingPhone?.networkOperator).toEqual('Verizon/1');
+      expect(got.billingPhone?.numberType).toEqual('fixed');
+
       expect(got.disposition?.action).toEqual('accept');
       expect(got.disposition?.reason).toEqual('default');
       expect(got.disposition?.ruleLabel).toEqual('the label');
@@ -270,7 +282,7 @@ describe('WebServiceClient', () => {
     });
 
     it('handles "full" responses', async () => {
-      expect.assertions(139);
+      expect.assertions(147);
 
       nockInstance
         .post(fullPath('insights'), insights.request.basic)
@@ -457,12 +469,24 @@ describe('WebServiceClient', () => {
       expect(got.shippingAddress?.distanceToBillingAddress).toEqual(22);
       expect(got.shippingAddress?.isInIpCountry).toEqual(true);
 
+      expect(got.shippingPhone?.country).toEqual('CA');
+      expect(got.shippingPhone?.isVoip).toEqual(true);
+      expect(got.shippingPhone?.networkOperator).toEqual(
+        'Telus Mobility-SVR/2'
+      );
+      expect(got.shippingPhone?.numberType).toEqual('mobile');
+
       expect(got.billingAddress?.isPostalInCity).toEqual(true);
       expect(got.billingAddress?.latitude).toEqual(37.545);
       expect(got.billingAddress?.longitude).toEqual(-122.421);
       expect(got.billingAddress?.distanceToIpLocation).toEqual(100);
       expect(got.billingAddress?.isInIpCountry).toEqual(true);
 
+      expect(got.billingPhone?.country).toEqual('US');
+      expect(got.billingPhone?.isVoip).toEqual(false);
+      expect(got.billingPhone?.networkOperator).toEqual('Verizon/1');
+      expect(got.billingPhone?.numberType).toEqual('fixed');
+
       expect(got.disposition?.action).toEqual('accept');
       expect(got.disposition?.reason).toEqual('default');
       expect(got.disposition?.ruleLabel).toEqual('the label');