Add new email domain fields to minFraud response

This commit adds support for new email domain outputs from minFraud Insights
and Factors services:

- Added classification field (business, education, government, isp_email)
- Added risk field (score from 0.01 to 99)
- Added volume field (sightings per million)
- Added visit object with status, last_visited_on, and has_redirect fields

New classes:
- EmailDomainVisit record with Status enum

Updated classes:
- EmailDomain record with Classification enum and new fields
- Mapper configured for forward-compatible enum deserialization

Enums use a simple pattern with toString() override and Jackson config to
handle unknown values gracefully (returns null instead of throwing).

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

Co-Authored-By: Claude <noreply@anthropic.com>

Author: oschwald

CHANGELOG.md

@@ -59,6 +59,27 @@ CHANGELOG
 * Added the input `/payment/method`. This is the payment method associated
   with the transaction. You may provide this using the `method` method on
   `Payment.Builder`.
+* Added new email domain fields to the `EmailDomain` response model:
+  * `classification` - A classification of the email domain. Possible values
+    are `BUSINESS`, `EDUCATION`, `GOVERNMENT`, and `ISP_EMAIL`.
+  * `risk` - A risk score associated with the email domain, ranging from 0.01
+    to 99. Higher scores indicate higher risk.
+  * `volume` - The activity on the email domain across the minFraud network,
+    expressed in sightings per million. This value ranges from 0.001 to
+    1,000,000.
+  * `visit` - An `EmailDomainVisit` object containing information about an
+    automated visit to the email domain, including:
+    * `status` - The status of the domain based on the automated visit.
+      Possible values are `LIVE`, `DNS_ERROR`, `NETWORK_ERROR`, `HTTP_ERROR`,
+      `PARKED`, and `PRE_DEVELOPMENT`.
+    * `lastVisitedOn` - The date when the automated visit was last completed.
+    * `hasRedirect` - Whether the domain redirects to another URL.
+* Added support for forward-compatible enum deserialization. Enums in response
+  models will now return `null` for unknown values instead of throwing an
+  exception. This allows the client to handle new enum values added by the
+  server without requiring an immediate client update. This required adding
+  `READ_ENUMS_USING_TO_STRING` and `READ_UNKNOWN_ENUM_VALUES_AS_NULL` to the
+  Jackson `ObjectMapper` configuration.
 
 3.9.0
 ------------------

CLAUDE.md

@@ -157,6 +157,46 @@ public record ScoreResponse(...) {
 
 This ensures users can safely call methods without null checks: `response.disposition().action()`.
 
+#### Enum Pattern for Response Models
+
+Response model enums use a simple, forward-compatible pattern that gracefully handles unknown values from the server.
+
+**Pattern:**
+```java
+public enum Status {
+    LIVE,
+    PARKED,
+    DNS_ERROR;
+
+    @Override
+    public String toString() {
+        return name().toLowerCase();
+    }
+}
+```
+
+**How it works:**
+- Enum constants use `UPPER_SNAKE_CASE` (e.g., `DNS_ERROR`, `ISP_EMAIL`)
+- Override `toString()` to return `name().toLowerCase()` for JSON serialization
+- The `Mapper` class configures Jackson with:
+  - `READ_ENUMS_USING_TO_STRING` - Deserializes using `toString()`
+  - `READ_UNKNOWN_ENUM_VALUES_AS_NULL` - Unknown values become `null` instead of throwing exceptions
+
+**Example:**
+```java
+// Serialization: DNS_ERROR → "dns_error"
+Status status = Status.DNS_ERROR;
+System.out.println(status);  // "dns_error"
+
+// Deserialization: "dns_error" → DNS_ERROR
+// Unknown: "future_value" → null (no exception!)
+```
+
+**When to use:**
+- Use enums for response fields with fixed/enumerated values
+- Use String for open-ended text fields
+- Request enums use the same pattern but don't need forward compatibility concerns
+
 ### Deprecation Strategy
 
 **Do NOT add deprecated getter methods for new fields.** Deprecated getters only exist for backward compatibility with fields that had JavaBeans-style getters before the record migration in version 4.0.0.

src/main/java/com/maxmind/minfraud/Mapper.java

@@ -14,6 +14,8 @@ class Mapper {
         .addModule(new JavaTimeModule())
         .defaultDateFormat(new StdDateFormat().withColonInTimeZone(true))
         .enable(SerializationFeature.WRITE_ENUMS_USING_TO_STRING)
+        .enable(DeserializationFeature.READ_ENUMS_USING_TO_STRING)
+        .enable(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_AS_NULL)
         .disable(MapperFeature.CAN_OVERRIDE_ACCESS_MODIFIERS)
         .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
         .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)

src/main/java/com/maxmind/minfraud/response/EmailDomain.java

@@ -7,18 +7,78 @@
 /**
  * This class contains minFraud response data related to the email domain.
  *
- * @param firstSeen A date to identify the date an email domain was first seen by MaxMind.
+ * @param classification A classification of the email domain. Possible values are: business,
+ *                       education, government, isp_email.
+ * @param firstSeen      The date an email domain was first seen by MaxMind.
+ * @param risk           A risk score associated with the email domain, ranging from 0.01 to 99.
+ *                       Higher scores indicate higher risk.
+ * @param visit          An {@code EmailDomainVisit} object containing information about an
+ *                       automated visit to the email domain.
+ * @param volume         The activity on the email domain across the minFraud network, expressed in
+ *                       sightings per million. This value ranges from 0.001 to 1,000,000.
  */
 public record EmailDomain(
+    @JsonProperty("classification")
+    Classification classification,
+
     @JsonProperty("first_seen")
-    LocalDate firstSeen
+    LocalDate firstSeen,
+
+    @JsonProperty("risk")
+    Double risk,
+
+    @JsonProperty("visit")
+    EmailDomainVisit visit,
+
+    @JsonProperty("volume")
+    Double volume
 ) implements JsonSerializable {
 
+    /**
+     * The classification of an email domain.
+     */
+    public enum Classification {
+        /**
+         * A business email domain.
+         */
+        BUSINESS,
+
+        /**
+         * An educational institution email domain.
+         */
+        EDUCATION,
+
+        /**
+         * A government email domain.
+         */
+        GOVERNMENT,
+
+        /**
+         * An ISP-provided email domain (e.g., gmail.com, yahoo.com).
+         */
+        ISP_EMAIL;
+
+        /**
+         * @return a string representation of the classification in lowercase with underscores.
+         */
+        @Override
+        public String toString() {
+            return name().toLowerCase();
+        }
+    }
+
+    /**
+     * Compact canonical constructor that sets defaults for null values.
+     */
+    public EmailDomain {
+        visit = visit != null ? visit : new EmailDomainVisit();
+    }
+
     /**
      * Constructs an instance of {@code EmailDomain} with no data.
      */
     public EmailDomain() {
-        this(null);
+        this(null, null, null, null, null);
     }
 
     /**

src/main/java/com/maxmind/minfraud/response/EmailDomainVisit.java

@@ -0,0 +1,76 @@
+package com.maxmind.minfraud.response;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.maxmind.minfraud.JsonSerializable;
+import java.time.LocalDate;
+
+/**
+ * This class contains information about an automated visit to the email domain.
+ *
+ * @param hasRedirect   Whether the domain redirects to another URL. This field is only present if
+ *                      the value is true.
+ * @param lastVisitedOn The date when the automated visit was last completed.
+ * @param status        The status of the domain based on the automated visit. Possible values are:
+ *                      live, dns_error, network_error, http_error, parked, pre_development.
+ */
+public record EmailDomainVisit(
+    @JsonProperty("has_redirect")
+    Boolean hasRedirect,
+
+    @JsonProperty("last_visited_on")
+    LocalDate lastVisitedOn,
+
+    @JsonProperty("status")
+    Status status
+) implements JsonSerializable {
+
+    /**
+     * The status of an email domain based on an automated visit.
+     */
+    public enum Status {
+        /**
+         * The domain is live and responding normally.
+         */
+        LIVE,
+
+        /**
+         * A DNS error occurred when attempting to visit the domain.
+         */
+        DNS_ERROR,
+
+        /**
+         * A network error occurred when attempting to visit the domain.
+         */
+        NETWORK_ERROR,
+
+        /**
+         * An HTTP error occurred when attempting to visit the domain.
+         */
+        HTTP_ERROR,
+
+        /**
+         * The domain is parked.
+         */
+        PARKED,
+
+        /**
+         * The domain is in pre-development.
+         */
+        PRE_DEVELOPMENT;
+
+        /**
+         * @return a string representation of the status in lowercase with underscores.
+         */
+        @Override
+        public String toString() {
+            return name().toLowerCase();
+        }
+    }
+
+    /**
+     * Constructs an instance of {@code EmailDomainVisit} with no data.
+     */
+    public EmailDomainVisit() {
+        this(null, null, null);
+    }
+}

src/test/java/com/maxmind/minfraud/WebServiceClientTest.java

@@ -18,6 +18,7 @@
 import static org.hamcrest.core.StringStartsWith.startsWith;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
@@ -28,6 +29,9 @@
 import com.maxmind.minfraud.exception.InsufficientFundsException;
 import com.maxmind.minfraud.exception.InvalidRequestException;
 import com.maxmind.minfraud.exception.MinFraudException;
+import com.maxmind.minfraud.response.EmailDomain;
+import com.maxmind.minfraud.response.EmailDomainVisit;
+import java.time.LocalDate;
 import com.maxmind.minfraud.exception.PermissionRequiredException;
 import com.maxmind.minfraud.request.Device;
 import com.maxmind.minfraud.request.Shipping;
@@ -118,6 +122,15 @@ public void testFullInsightsTransaction() throws Exception {
 
         assertTrue(response.creditCard().isVirtual());
 
+        // Test email domain fields
+        assertEquals(EmailDomain.Classification.EDUCATION, response.email().domain().classification());
+        assertEquals(15.5, response.email().domain().risk());
+        assertEquals(630000.0, response.email().domain().volume());
+        assertNotNull(response.email().domain().visit());
+        assertEquals(EmailDomainVisit.Status.LIVE, response.email().domain().visit().status());
+        assertTrue(response.email().domain().visit().hasRedirect());
+        assertEquals(LocalDate.parse("2024-11-15"), response.email().domain().visit().lastVisitedOn());
+
         var reasons = response.ipAddress().riskReasons();
 
         assertEquals(2, reasons.size(), "two IP risk reasons");
@@ -153,6 +166,14 @@ public void testFullFactorsTransaction() throws Exception {
             "response.ipAddress().representedCountry().isInEuropeanUnion() does not return false"
         );
 
+        // Test email domain fields
+        assertEquals(EmailDomain.Classification.ISP_EMAIL, response.email().domain().classification());
+        assertEquals(25.0, response.email().domain().risk());
+        assertEquals(500000.5, response.email().domain().volume());
+        assertNotNull(response.email().domain().visit());
+        assertEquals(EmailDomainVisit.Status.PARKED, response.email().domain().visit().status());
+        assertFalse(response.email().domain().visit().hasRedirect());
+        assertEquals(LocalDate.parse("2024-10-20"), response.email().domain().visit().lastVisitedOn());
 
         assertEquals("152.216.7.110", response.ipAddress().traits().ipAddress().getHostAddress());
         assertEquals("81.2.69.0/24",

src/test/java/com/maxmind/minfraud/response/AbstractOutputTest.java

@@ -20,6 +20,8 @@ <T> T deserialize(Class<T> cls, String json) throws IOException {
             .addModule(new JavaTimeModule())
             .defaultDateFormat(new StdDateFormat().withColonInTimeZone(true))
             .enable(SerializationFeature.WRITE_ENUMS_USING_TO_STRING)
+            .enable(DeserializationFeature.READ_ENUMS_USING_TO_STRING)
+            .enable(DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_AS_NULL)
             .disable(MapperFeature.CAN_OVERRIDE_ACCESS_MODIFIERS)
             .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
             .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)