STF-1906: Add phone verification inputs

CHANGELOG.md

@@ -1,9 +1,22 @@
 CHANGELOG
 =========
 
-9.1.1
-------------------
-
+9.2.0
+------------------
+
+* Added the inputs `/billing/phone_verification_method`,
+  `/billing/phone_was_verification_successful`,
+  `/billing/phone_verification_time`,
+  `/shipping/phone_verification_method`,
+  `/shipping/phone_was_verification_successful`, and
+  `/shipping/phone_verification_time`. They describe the most recent
+  verification of the billing or shipping phone number. You may provide them
+  by providing `phoneVerificationMethod`, `phoneWasVerificationSuccessful`,
+  and `phoneVerificationTime` to `Billing` or `Shipping`. The
+  `PhoneVerificationMethod` enum lists the valid methods.
+* `Event` now throws an `ArgumentError` if `time` is not a valid `Date`.
+  Before, the client sent an invalid `Date` as `null` and did not report an
+  error.
 * Added `maxmind` as a direct dependency. The `IpAddressWebRecord` type extends
   `CityResponse` from that package, so it is part of this package's published
   type surface. It was previously resolved only as a transitive dependency of

README.md

@@ -217,6 +217,9 @@ try {
       lastName: 'Bar',
       phoneCountryCode: '1',
       phoneNumber: '123-456-1234',
+      phoneVerificationMethod: minFraud.Constants.PhoneVerificationMethod.DeliveredCode,
+      phoneVerificationTime: new Date('2026-10-01T14:30:00Z'),
+      phoneWasVerificationSuccessful: true,
       postal: '12345',
       region: 'MA',
     }),
@@ -231,6 +234,9 @@ try {
       lastName: 'Bar',
       phoneCountryCode: '1',
       phoneNumber: '123-456-0000',
+      phoneVerificationMethod: minFraud.Constants.PhoneVerificationMethod.DeliveredCode,
+      phoneVerificationTime: new Date('2026-10-01T14:30:00Z'),
+      phoneWasVerificationSuccessful: true,
       postal: '12345',
       region: 'MA',
     }),

src/constants.ts

@@ -25,6 +25,24 @@ export enum DeliverySpeed {
   Standard = 'standard',
 }
 
+export enum PhoneVerificationMethod {
+  /**
+   * A one-time code delivered to the phone number by SMS, an automated voice
+   * call, or a messaging app, and entered by the user.
+   */
+  DeliveredCode = 'delivered_code',
+  /**
+   * Carrier or SIM-based silent network authentication. No code is sent to
+   * the device.
+   */
+  Network = 'network',
+  /**
+   * A method not listed above, such as flash or missed call verification, or
+   * a method you do not know because a third party performed the check.
+   */
+  Other = 'other',
+}
+
 export enum PaymentMethod {
   BankDebit = 'bank_debit',
   BankRedirect = 'bank_redirect',

src/request/event.spec.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
 import Event from './event.js';
 import { EventParty, EventType } from '../constants.js';
+import { ArgumentError } from '../errors.js';
 
 describe('Event()', () => {
   it('sets `time` to now by default', () => {
@@ -17,6 +18,22 @@ describe('Event()', () => {
     expect(event.time).toEqual(mockDate);
   });
 
+  it('keeps a valid `time`', () => {
+    const time = new Date('2026-10-01T14:30:00Z');
+    const event = new Event({ time });
+
+    expect(event.time).toEqual(time);
+  });
+
+  it.each([
+    ['an invalid Date', new Date('not a date')],
+    ['a string', '2026-10-01T14:30:00Z'],
+  ])('throws an ArgumentError if `time` is %s', (_, value) => {
+    const test = () => new Event({ time: value as unknown as Date });
+    expect(test).toThrow(ArgumentError);
+    expect(test).toThrow('event.time');
+  });
+
   it('accepts credit_application event type', () => {
     const event = new Event({
       type: EventType.CreditApplication,

src/request/event.ts

@@ -1,4 +1,5 @@
 import { EventParty, EventType } from '../constants.js';
+import { assertValidDate } from '../utils.js';
 
 interface EventProps {
   /**
@@ -43,6 +44,10 @@ export default class Event implements EventProps {
   public type?: EventType;
 
   public constructor(minfraudEvent: EventProps) {
+    if (minfraudEvent.time != null) {
+      assertValidDate(minfraudEvent.time, 'event.time');
+    }
+
     Object.assign(this, minfraudEvent);
 
     if (!this.time) {

src/request/location.spec.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
+import { PhoneVerificationMethod } from '../constants.js';
 import { ArgumentError } from '../errors.js';
-import Location from './location.js';
+import Location, { LocationProps } from './location.js';
 
 describe('Location()', () => {
   it('throws an error if country is not valid', () => {
@@ -20,4 +21,78 @@ describe('Location()', () => {
       });
     }).not.toThrow();
   });
+
+  it('stores the phone verification properties', () => {
+    const time = new Date('2026-10-01T14:30:00Z');
+    const location = new Location({
+      country: 'CA',
+      phoneVerificationMethod: PhoneVerificationMethod.Network,
+      phoneVerificationTime: time,
+      phoneWasVerificationSuccessful: false,
+    });
+
+    expect(location.country).toBe('CA');
+    expect(location.phoneVerificationMethod).toBe('network');
+    expect(location.phoneVerificationTime).toEqual(time);
+    expect(location.phoneWasVerificationSuccessful).toBe(false);
+  });
+
+  it('copies `phoneVerificationTime`', () => {
+    const time = new Date('2026-10-01T14:30:00Z');
+    const location = new Location({ phoneVerificationTime: time });
+
+    time.setTime(0);
+
+    expect(location.phoneVerificationTime).toEqual(
+      new Date('2026-10-01T14:30:00Z')
+    );
+  });
+
+  it('accepts null phone verification properties', () => {
+    expect(
+      () =>
+        new Location({
+          phoneVerificationMethod: null,
+          phoneVerificationTime: null,
+          phoneWasVerificationSuccessful: null,
+        } as unknown as LocationProps)
+    ).not.toThrow();
+  });
+
+  it.each(['sms', 'Network', ''])(
+    'throws an ArgumentError for phoneVerificationMethod %j',
+    (value) => {
+      const test = () =>
+        new Location({
+          phoneVerificationMethod: value as PhoneVerificationMethod,
+        });
+      expect(test).toThrow(ArgumentError);
+      expect(test).toThrow('phoneVerificationMethod');
+    }
+  );
+
+  it.each(['true', 1, 0])(
+    'throws an ArgumentError for phoneWasVerificationSuccessful %j',
+    (value) => {
+      const test = () =>
+        new Location({
+          phoneWasVerificationSuccessful: value as unknown as boolean,
+        });
+      expect(test).toThrow(ArgumentError);
+      expect(test).toThrow('phoneWasVerificationSuccessful');
+    }
+  );
+
+  it.each([
+    ['an invalid Date', new Date('not a date')],
+    ['a string', '2026-10-01T14:30:00Z'],
+    ['a number', 1790000000000],
+  ])('throws an ArgumentError if phoneVerificationTime is %s', (_, value) => {
+    const test = () =>
+      new Location({
+        phoneVerificationTime: value as unknown as Date,
+      });
+    expect(test).toThrow(ArgumentError);
+    expect(test).toThrow('phoneVerificationTime');
+  });
 });

src/request/location.ts

@@ -1,4 +1,6 @@
+import { PhoneVerificationMethod } from '../constants.js';
 import { ArgumentError } from '../errors.js';
+import { assertValidDate } from '../utils.js';
 
 export interface LocationProps {
   /**
@@ -39,13 +41,29 @@ export interface LocationProps {
    */
   postal?: string;
   /**
-   * The phone country code for the phone number associated with the address.
+   * The phone number, without the country code, associated with the address.
    */
   phoneNumber?: string;
   /**
-   * The phone number, without the country code, associated with the address.
+   * The phone country code for the phone number associated with the address.
    */
   phoneCountryCode?: string;
+  /**
+   * The most recent method used to verify the phone number.
+   */
+  phoneVerificationMethod?: PhoneVerificationMethod;
+  /**
+   * The date and time of the most recent verification of the phone number.
+   * The time must not be before 1970-01-01T00:00:00Z or more than two days in
+   * the future. The web service ignores a time outside this range and returns
+   * a warning.
+   */
+  phoneVerificationTime?: Date;
+  /**
+   * Whether the most recent verification of the phone number succeeded. Omit
+   * this if no verification was attempted.
+   */
+  phoneWasVerificationSuccessful?: boolean;
 }
 
 const countryRegex = /^[A-Z]{2}$/;
@@ -76,6 +94,12 @@ export default class Location implements LocationProps {
   public phoneNumber?: string;
   /** @inheritDoc LocationProps.phoneCountryCode */
   public phoneCountryCode?: string;
+  /** @inheritDoc LocationProps.phoneVerificationMethod */
+  public phoneVerificationMethod?: PhoneVerificationMethod;
+  /** @inheritDoc LocationProps.phoneVerificationTime */
+  public phoneVerificationTime?: Date;
+  /** @inheritDoc LocationProps.phoneWasVerificationSuccessful */
+  public phoneWasVerificationSuccessful?: boolean;
 
   public constructor(location: LocationProps) {
     if (location.country != null && !countryRegex.test(location.country)) {
@@ -84,6 +108,38 @@ export default class Location implements LocationProps {
       );
     }
 
+    if (
+      location.phoneVerificationMethod != null &&
+      !Object.values(PhoneVerificationMethod).includes(
+        location.phoneVerificationMethod
+      )
+    ) {
+      throw new ArgumentError(
+        `"${location.phoneVerificationMethod}" is an invalid value for "phoneVerificationMethod"`
+      );
+    }
+
+    if (
+      location.phoneWasVerificationSuccessful != null &&
+      typeof location.phoneWasVerificationSuccessful !== 'boolean'
+    ) {
+      throw new ArgumentError(
+        '`phoneWasVerificationSuccessful` must be a boolean'
+      );
+    }
+
+    if (location.phoneVerificationTime != null) {
+      assertValidDate(location.phoneVerificationTime, 'phoneVerificationTime');
+    }
+
     Object.assign(this, location);
+
+    // Copy the Date so that a later change to the caller's object does not
+    // change the request.
+    if (location.phoneVerificationTime != null) {
+      this.phoneVerificationTime = new Date(
+        location.phoneVerificationTime.getTime()
+      );
+    }
   }
 }

src/request/transaction.spec.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, test } from 'vitest';
+import { PhoneVerificationMethod } from '../constants.js';
 import { ArgumentError } from '../errors.js';
 import Account from './account.js';
 import Billing from './billing.js';
@@ -267,6 +268,28 @@ describe('Transaction()', () => {
       expect(test.toString()).toContain('"billing":{"address_2":"foo"}');
     });
 
+    it.each([
+      ['billing', Billing],
+      ['shipping', Shipping],
+    ] as const)('it handles %s phone verification fields', (name, Cls) => {
+      const test = new Transaction({
+        [name]: new Cls({
+          phoneVerificationMethod: PhoneVerificationMethod.DeliveredCode,
+          phoneVerificationTime: new Date('2026-10-01T14:30:00Z'),
+          phoneWasVerificationSuccessful: false,
+        }),
+        device: new Device({
+          ipAddress: '1.1.1.1',
+        }),
+      });
+
+      expect(JSON.parse(test.toString())[name]).toEqual({
+        phone_verification_method: 'delivered_code',
+        phone_verification_time: '2026-10-01T14:30:00.000Z',
+        phone_was_verification_successful: false,
+      });
+    });
+
     it('does not mutate the caller’s input objects when serializing', () => {
       const billing = new Billing({ address2: 'foo' });
       const shipping = new Shipping({ address2: 'bar' });

src/utils.ts

@@ -1,3 +1,5 @@
+import { ArgumentError } from './errors.js';
+
 /**
  * Converts snake_case to camelCase
  * @param {string} input - snake_case string
@@ -85,3 +87,18 @@ export function snakecaseKeys(input: unknown): unknown {
     {} as Record<string, unknown>
   );
 }
+
+/**
+ * Throws an `ArgumentError` if `value` is not a valid `Date`.
+ *
+ * @param value - the value to check
+ * @param name - the property name to use in the error message
+ */
+export function assertValidDate(
+  value: unknown,
+  name: string
+): asserts value is Date {
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new ArgumentError(`\`${name}\` must be a valid Date`);
+  }
+}