Add new matchesPostal phone attribute

Author: oschwald

CHANGELOG.md

@@ -4,6 +4,10 @@ CHANGELOG
 8.1.0
 ------------------
 
+* Added support for the `/billing_phone/matches_postal` and
+  `/shipping_phone/matches_postal` outputs. These are available as the
+  `matchesPostal` attributes on `response.billingPhone` and
+  `response.shippingPhone`.
 * Added `Cryptomus` to the `Processor` enum.
 
 8.0.0 (2025-02-10)

fixtures/insights.json

@@ -198,6 +198,7 @@
       "shipping_phone": {
         "country": "CA",
         "is_voip": true,
+        "matches_postal": true,
         "network_operator": "Telus Mobility-SVR/2",
         "number_type": "mobile"
       },
@@ -213,6 +214,7 @@
       "billing_phone": {
         "country": "US",
         "is_voip": false,
+        "matches_postal": true,
         "network_operator": "Verizon/1",
         "number_type": "fixed"
       },

src/response/records.ts

@@ -251,6 +251,14 @@ export interface Phone {
    * number has not been provided or we do not have data for it.
    */
   readonly isVoip?: boolean;
+  /**
+   * This is `true` if the phone number’s area code is commonly associated with
+   * the corresponding postal code. It is `false` if the area code is not
+   * associated with the postal code. It is only non-`null` when the phone
+   * number is in the US and the postal code and country are provided in the
+   * request.
+   */
+  readonly matchesPostal?: boolean;
   /**
    * The name of the original network operator associated with the phone
    * number. This property does not reflect phone numbers that have been ported

src/response/web-records.ts

@@ -117,6 +117,7 @@ export interface DispositionWebRecord {
 export interface PhoneWebRecord {
   readonly country?: string;
   readonly is_voip?: boolean;
+  readonly matches_postal?: boolean;
   readonly network_operator?: string;
   readonly number_type?: string;
 }

src/webServiceClient.spec.ts

@@ -37,7 +37,7 @@ describe('WebServiceClient', () => {
     });
 
     it('handles "full" responses', async () => {
-      expect.assertions(172);
+      expect.assertions(174);
 
       nockInstance
         .post(fullPath('factors'), factors.request.basic)
@@ -226,6 +226,7 @@ describe('WebServiceClient', () => {
 
       expect(got.shippingPhone?.country).toEqual('CA');
       expect(got.shippingPhone?.isVoip).toEqual(true);
+      expect(got.shippingPhone?.matchesPostal).toEqual(true);
       expect(got.shippingPhone?.networkOperator).toEqual(
         'Telus Mobility-SVR/2'
       );
@@ -239,6 +240,7 @@ describe('WebServiceClient', () => {
 
       expect(got.billingPhone?.country).toEqual('US');
       expect(got.billingPhone?.isVoip).toEqual(false);
+      expect(got.billingPhone?.matchesPostal).toEqual(true);
       expect(got.billingPhone?.networkOperator).toEqual('Verizon/1');
       expect(got.billingPhone?.numberType).toEqual('fixed');
 
@@ -291,7 +293,7 @@ describe('WebServiceClient', () => {
     });
 
     it('handles "full" responses', async () => {
-      expect.assertions(147);
+      expect.assertions(149);
 
       nockInstance
         .post(fullPath('insights'), insights.request.basic)
@@ -480,6 +482,7 @@ describe('WebServiceClient', () => {
 
       expect(got.shippingPhone?.country).toEqual('CA');
       expect(got.shippingPhone?.isVoip).toEqual(true);
+      expect(got.shippingPhone?.matchesPostal).toEqual(true);
       expect(got.shippingPhone?.networkOperator).toEqual(
         'Telus Mobility-SVR/2'
       );
@@ -493,6 +496,7 @@ describe('WebServiceClient', () => {
 
       expect(got.billingPhone?.country).toEqual('US');
       expect(got.billingPhone?.isVoip).toEqual(false);
+      expect(got.billingPhone?.matchesPostal).toEqual(true);
       expect(got.billingPhone?.networkOperator).toEqual('Verizon/1');
       expect(got.billingPhone?.numberType).toEqual('fixed');