Add email domain outputs for Insights and Factors

Adds support for new email domain fields:
- classification, risk, and volume
- visit sub-object with status, lastVisitedOn, and hasRedirect

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: oschwald

CHANGELOG.md

@@ -12,6 +12,17 @@ CHANGELOG
 * Added the input `/payment/method`. This is the payment method associated
   with the transaction. You may provide this by providing `method` to
   `Payment`.
+* Added new `response.email.domain` outputs:
+  * `classification` - The domain type (business, education, government,
+    isp_email).
+  * `risk` - A risk score from 0.01 to 99 associated with the email domain.
+  * `volume` - Activity level for the domain across the minFraud network,
+    expressed in sightings per million.
+* Added new `response.email.domain.visit` outputs for low-volume domains:
+  * `status` - Domain status from automated visit (live, dns_error,
+    network_error, http_error, parked, pre_development).
+  * `lastVisitedOn` - The date the automated visit was completed.
+  * `hasRedirect` - Whether the domain redirects to another URL.
 
 8.1.0 (2025-05-23)
 ------------------

fixtures/insights.json

@@ -177,7 +177,15 @@
 
       "email": {
         "domain": {
-          "first_seen": "2016-01-23"
+          "classification": "business",
+          "first_seen": "2016-01-23",
+          "risk": 15.5,
+          "visit": {
+            "has_redirect": false,
+            "last_visited_on": "2024-11-15",
+            "status": "live"
+          },
+          "volume": 6300
         },
         "first_seen": "2016-02-03",
         "is_disposable": false,

src/response/models/insights.spec.ts

@@ -33,4 +33,34 @@ describe('Insights()', () => {
     const model = new Insights(response as InsightsResponse);
     expect(model.email?.domain?.firstSeen).toBe('2016-01-23');
   });
+
+  it('allows /email/domain/classification to be accessed', () => {
+    const model = new Insights(response as InsightsResponse);
+    expect(model.email?.domain?.classification).toBe('business');
+  });
+
+  it('allows /email/domain/risk to be accessed', () => {
+    const model = new Insights(response as InsightsResponse);
+    expect(model.email?.domain?.risk).toBe(15.5);
+  });
+
+  it('allows /email/domain/volume to be accessed', () => {
+    const model = new Insights(response as InsightsResponse);
+    expect(model.email?.domain?.volume).toBe(6300);
+  });
+
+  it('allows /email/domain/visit/status to be accessed', () => {
+    const model = new Insights(response as InsightsResponse);
+    expect(model.email?.domain?.visit?.status).toBe('live');
+  });
+
+  it('allows /email/domain/visit/last_visited_on to be accessed', () => {
+    const model = new Insights(response as InsightsResponse);
+    expect(model.email?.domain?.visit?.lastVisitedOn).toBe('2024-11-15');
+  });
+
+  it('allows /email/domain/visit/has_redirect to be accessed', () => {
+    const model = new Insights(response as InsightsResponse);
+    expect(model.email?.domain?.visit?.hasRedirect).toBe(false);
+  });
 });

src/response/records.ts

@@ -3,6 +3,8 @@ import {
   CreditCardType,
   DispositionAction,
   DispositionReason,
+  EmailDomainClassification,
+  EmailDomainVisitStatus,
 } from './web-records';
 
 /**
@@ -191,15 +193,60 @@ export interface Device {
   readonly localTime: string;
 }
 
+/**
+ * Status of an automated visit to the email domain. This object is only
+ * available for low-volume domains. High-volume domains (email providers,
+ * large businesses) will not include visit data.
+ */
+export interface EmailDomainVisit {
+  /**
+   * Indicates if the domain redirects to another URL.
+   */
+  readonly hasRedirect: boolean;
+  /**
+   * The date the automated visit was completed, in ISO 8601 format (YYYY-MM-DD).
+   */
+  readonly lastVisitedOn: string;
+  /**
+   * Classification of the domain based on the automated visit.
+   * Possible values include: `live`, `dns_error`, `network_error`,
+   * `http_error`, `parked`, `pre_development`.
+   */
+  readonly status: EmailDomainVisitStatus;
+}
+
 /**
  * This object contains information about the email address domain passed in the
  * request.
  */
 export interface EmailDomain {
+  /**
+   * Classification of the email domain type. Possible values include:
+   * `business`, `education`, `government`, `isp_email`.
+   * Additional values may be added in the future.
+   */
+  readonly classification?: EmailDomainClassification;
   /**
    * The date the email address domain was first seen by MaxMind.
    */
   readonly firstSeen: string;
+  /**
+   * A risk score from 0.01 to 99 associated with the email domain.
+   * Higher scores indicate higher risk.
+   */
+  readonly risk?: number;
+  /**
+   * Information from an automated visit to the email domain. This is only
+   * available for low-volume domains and may be initially unavailable for
+   * newly-sighted domains, populating later after automated visits occur.
+   */
+  readonly visit?: EmailDomainVisit;
+  /**
+   * Activity indicator for the email domain across the minFraud network,
+   * expressed in sightings per million. Values range from 0.001 to 1,000,000
+   * and are rounded to 2 significant figures.
+   */
+  readonly volume?: number;
 }
 
 /**

src/response/web-records.ts

@@ -74,8 +74,32 @@ export interface DeviceWebRecord {
   readonly local_time: string;
 }
 
+export type EmailDomainClassification =
+  | 'business'
+  | 'education'
+  | 'government'
+  | 'isp_email';
+
+export type EmailDomainVisitStatus =
+  | 'live'
+  | 'dns_error'
+  | 'network_error'
+  | 'http_error'
+  | 'parked'
+  | 'pre_development';
+
+export interface EmailDomainVisitWebRecord {
+  readonly has_redirect: boolean;
+  readonly last_visited_on: string;
+  readonly status: EmailDomainVisitStatus;
+}
+
 export interface EmailDomainWebRecord {
+  readonly classification?: EmailDomainClassification;
   readonly first_seen: string;
+  readonly risk?: number;
+  readonly visit?: EmailDomainVisitWebRecord;
+  readonly volume?: number;
 }
 
 export interface EmailWebRecord {

src/webServiceClient.spec.ts

@@ -37,7 +37,7 @@ describe('WebServiceClient', () => {
     });
 
     it('handles "full" responses', async () => {
-      expect.assertions(174);
+      expect.assertions(180);
 
       nockInstance
         .post(fullPath('factors'), factors.request.basic)
@@ -211,6 +211,12 @@ describe('WebServiceClient', () => {
       expect(got.device?.localTime).toEqual('2018-01-02T10:40:11-08:00');
 
       expect(got.email?.domain?.firstSeen).toEqual('2016-01-23');
+      expect(got.email?.domain?.classification).toEqual('business');
+      expect(got.email?.domain?.risk).toEqual(15.5);
+      expect(got.email?.domain?.volume).toEqual(6300);
+      expect(got.email?.domain?.visit?.status).toEqual('live');
+      expect(got.email?.domain?.visit?.lastVisitedOn).toEqual('2024-11-15');
+      expect(got.email?.domain?.visit?.hasRedirect).toEqual(false);
       expect(got.email?.firstSeen).toEqual('2016-02-03');
       expect(got.email?.isDisposable).toEqual(false);
       expect(got.email?.isFree).toEqual(false);
@@ -293,7 +299,7 @@ describe('WebServiceClient', () => {
     });
 
     it('handles "full" responses', async () => {
-      expect.assertions(149);
+      expect.assertions(155);
 
       nockInstance
         .post(fullPath('insights'), insights.request.basic)
@@ -467,6 +473,12 @@ describe('WebServiceClient', () => {
       expect(got.device?.localTime).toEqual('2018-01-02T10:40:11-08:00');
 
       expect(got.email?.domain?.firstSeen).toEqual('2016-01-23');
+      expect(got.email?.domain?.classification).toEqual('business');
+      expect(got.email?.domain?.risk).toEqual(15.5);
+      expect(got.email?.domain?.volume).toEqual(6300);
+      expect(got.email?.domain?.visit?.status).toEqual('live');
+      expect(got.email?.domain?.visit?.lastVisitedOn).toEqual('2024-11-15');
+      expect(got.email?.domain?.visit?.hasRedirect).toEqual(false);
       expect(got.email?.firstSeen).toEqual('2016-02-03');
       expect(got.email?.isDisposable).toEqual(false);
       expect(got.email?.isFree).toEqual(false);
@@ -530,16 +542,16 @@ describe('WebServiceClient', () => {
 
       switch (property) {
         case 'billing_address':
-          expect.assertions(134);
+          expect.assertions(140);
           break;
         case 'credit_card':
-          expect.assertions(128);
+          expect.assertions(134);
           break;
         case 'email':
           expect.assertions(134);
           break;
         case 'shipping_address':
-          expect.assertions(132);
+          expect.assertions(138);
           break;
       }
 
@@ -569,6 +581,12 @@ describe('WebServiceClient', () => {
 
       if (property != 'email') {
         expect(got.email?.domain?.firstSeen).toEqual('2016-01-23');
+        expect(got.email?.domain?.classification).toEqual('business');
+        expect(got.email?.domain?.risk).toEqual(15.5);
+        expect(got.email?.domain?.volume).toEqual(6300);
+        expect(got.email?.domain?.visit?.status).toEqual('live');
+        expect(got.email?.domain?.visit?.lastVisitedOn).toEqual('2024-11-15');
+        expect(got.email?.domain?.visit?.hasRedirect).toEqual(false);
         expect(got.email?.firstSeen).toEqual('2016-02-03');
         expect(got.email?.isDisposable).toEqual(false);
         expect(got.email?.isFree).toEqual(false);