Migrate to using enums for Smartrate delivery accuracy choices (#152)

- New SmartrateAccuracy enum (similar to C# library)
- New functions to use SmartrateAccuracy when dealing with smartrates
- Deprecate old smartrate functions using strings

Author: nwithan8

src/main/java/com/easypost/model/Shipment.java

@@ -3,9 +3,7 @@
 import com.easypost.exception.EasyPostException;
 import com.easypost.net.EasyPostResource;
 
-import java.util.Arrays;
 import java.util.HashMap;
-import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 
@@ -1035,8 +1033,22 @@ public Shipment insure(final String apiKey) throws EasyPostException {
      * @param deliveryAccuracy Delivery days accuracy restriction to use when filtering.
      * @return lowest Smartrate object
      * @throws EasyPostException when the request fails.
+     * @deprecated use {@link #lowestSmartRate(int, SmartrateAccuracy)} instead.
      */
+    @Deprecated
     public Smartrate lowestSmartRate(int deliveryDay, String deliveryAccuracy) throws EasyPostException {
+        return this.lowestSmartRate(deliveryDay, SmartrateAccuracy.getByKeyName(deliveryAccuracy));
+    }
+
+    /**
+     * Get the lowest smartrate for this Shipment.
+     *
+     * @param deliveryDay      Delivery days restriction to use when filtering.
+     * @param deliveryAccuracy Delivery days accuracy restriction to use when filtering.
+     * @return lowest Smartrate object
+     * @throws EasyPostException when the request fails.
+     */
+    public Smartrate lowestSmartRate(int deliveryDay, SmartrateAccuracy deliveryAccuracy) throws EasyPostException {
         List<Smartrate> smartrates = this.getSmartrates();
 
         Smartrate lowestSmartrate = findLowestSmartrate(smartrates, deliveryDay, deliveryAccuracy);
@@ -1074,12 +1086,12 @@ public List<Smartrate> smartrates() throws EasyPostException {
      * @param deliveryAccuracy Delivery days accuracy restriction to use when filtering.
      * @return lowest Smartrate object
      * @throws EasyPostException when the request fails.
-     * @deprecated Use {@link #findLowestSmartrate(List, int, String)} instead.
+     * @deprecated Use {@link #findLowestSmartrate(List, int, SmartrateAccuracy)} instead.
      */
     @Deprecated
     public static Smartrate getLowestSmartRate(final List<Smartrate> smartrates, int deliveryDay,
                                                String deliveryAccuracy) throws EasyPostException {
-        return findLowestSmartrate(smartrates, deliveryDay, deliveryAccuracy);
+        return findLowestSmartrate(smartrates, deliveryDay, SmartrateAccuracy.getByKeyName(deliveryAccuracy));
     }
 
     /**
@@ -1092,19 +1104,11 @@ public static Smartrate getLowestSmartRate(final List<Smartrate> smartrates, int
      * @throws EasyPostException when the request fails.
      */
     public static Smartrate findLowestSmartrate(final List<Smartrate> smartrates, int deliveryDay,
-                                                String deliveryAccuracy) throws EasyPostException {
+                                                SmartrateAccuracy deliveryAccuracy) throws EasyPostException {
         Smartrate lowestSmartrate = null;
 
-        HashSet<String> validDeliveryAccuracies = new HashSet<String>(
-                Arrays.asList("percentile_50", "percentile_75", "percentile_85", "percentile_90", "percentile_95",
-                        "percentile_97", "percentile_99"));
-
-        if (!validDeliveryAccuracies.contains(deliveryAccuracy.toLowerCase())) {
-            throw new EasyPostException("Invalid delivery_accuracy value, must be one of: " + validDeliveryAccuracies);
-        }
-
         for (Smartrate rate : smartrates) {
-            int smartrateDeliveryDay = rate.getTimeInTransit().getSmartRateAccuracy(deliveryAccuracy);
+            int smartrateDeliveryDay = rate.getTimeInTransit().getBySmartrateAccuracy(deliveryAccuracy);
 
             if (smartrateDeliveryDay > deliveryDay) {
                 continue;

src/main/java/com/easypost/model/SmartrateAccuracy.java

@@ -0,0 +1,47 @@
+package com.easypost.model;
+
+public enum SmartrateAccuracy {
+    Percentile50("percentile_50"),
+    Percentile75("percentile_75"),
+    Percentile85("percentile_85"),
+    Percentile90("percentile_90"),
+    Percentile95("percentile_95"),
+    Percentile97("percentile_97"),
+    Percentile99("percentile_99");
+
+    private final String keyName;
+
+    /**
+     * Constructor.
+     *
+     * @param keyName the internal key name
+     */
+    SmartrateAccuracy(String keyName) {
+        this.keyName = keyName;
+    }
+
+    /**
+     * Get the internal key name for this enum value.
+     *
+     * @return the internal key name
+     */
+    public String getKeyName() {
+        return keyName;
+    }
+
+    /**
+     * Get the enum value for a given internal key name.
+     *
+     * @param keyName the internal key name
+     * @return the enum value
+     * @throws IllegalArgumentException if the key name is not found
+     */
+    public static SmartrateAccuracy getByKeyName(String keyName) throws IllegalArgumentException {
+        for (SmartrateAccuracy smartrateAccuracy : values()) {
+            if (smartrateAccuracy.getKeyName().equals(keyName)) {
+                return smartrateAccuracy;
+            }
+        }
+        throw new IllegalArgumentException("Invalid SmartrateAccuracy key name.");
+    }
+}

src/main/java/com/easypost/model/TimeInTransit.java

@@ -152,7 +152,9 @@ public void setPercentile99(final Integer percentile99) {
      * @param percentile the percentile to find the corresponding accuracy for
      * @return the delivery accuracy of the specified percentile
      * @throws EasyPostException when the percentile is not valid
+     * @deprecated Use {@link #getBySmartrateAccuracy(SmartrateAccuracy)} instead.
      */
+    @Deprecated
     public int getSmartRateAccuracy(final String percentile) throws EasyPostException {
         switch (percentile) {
             case "percentile_50":
@@ -173,4 +175,33 @@ public int getSmartRateAccuracy(final String percentile) throws EasyPostExceptio
                 throw new EasyPostException("Invalid percentile value");
         }
     }
+
+    /**
+     * Get the delivery accuracy of a specific percentile of this TimeInTransit.
+     *
+     * @param accuracy the SmartrateAccuracy to find the corresponding accuracy for
+     * @return the delivery accuracy of the specified percentile
+     * @throws EasyPostException when the percentile is not valid
+     */
+    public int getBySmartrateAccuracy(SmartrateAccuracy accuracy) throws EasyPostException {
+        switch (accuracy) {
+            case Percentile50:
+                return this.percentile50;
+            case Percentile75:
+                return this.percentile75;
+            case Percentile85:
+                return this.percentile85;
+            case Percentile90:
+                return this.percentile90;
+            case Percentile95:
+                return this.percentile95;
+            case Percentile97:
+                return this.percentile97;
+            case Percentile99:
+                return this.percentile99;
+            default:
+                throw new EasyPostException("Invalid SmartrateAccuracy enum value.");
+        }
+    }
+
 }

src/test/java/com/easypost/ShipmentTest.java

@@ -7,6 +7,7 @@
 import com.easypost.model.Shipment;
 import com.easypost.model.ShipmentCollection;
 import com.easypost.model.Smartrate;
+import com.easypost.model.SmartrateAccuracy;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
@@ -384,7 +385,7 @@ public void testInstanceLowestSmartRate() throws EasyPostException {
         vcr.setUpTest("lowest_smartrate");
 
         Shipment shipment = createBasicShipment();
-        Smartrate lowestSmartRateFilters = shipment.lowestSmartRate(1, "percentile_90");
+        Smartrate lowestSmartRateFilters = shipment.lowestSmartRate(1, SmartrateAccuracy.Percentile90);
 
         // Test lowest smartrate with valid filters
         assertEquals("First", lowestSmartRateFilters.getService());
@@ -393,12 +394,7 @@ public void testInstanceLowestSmartRate() throws EasyPostException {
 
         // Test lowest smartrate with invalid filters (should error due to strict delivery days)
         assertThrows(EasyPostException.class, () -> {
-            shipment.lowestSmartRate(0, "percentile_90");
-        });
-
-        // Test lowest smartrate with invalid filters (should error due to invalid delivery accuracy)
-        assertThrows(EasyPostException.class, () -> {
-            shipment.lowestSmartRate(1, "BAD ACCURACY");
+            shipment.lowestSmartRate(0, SmartrateAccuracy.Percentile90);
         });
     }
 
@@ -415,19 +411,14 @@ public void testStaticLowestSmartRates() throws EasyPostException {
         List<Smartrate> smartrates = shipment.smartrates();
 
         // Test lowest smartrate with valid filters
-        Smartrate lowestSmartRate = Shipment.findLowestSmartrate(smartrates, 1, "percentile_90");
+        Smartrate lowestSmartRate = Shipment.findLowestSmartrate(smartrates, 1, SmartrateAccuracy.Percentile90);
         assertEquals("First", lowestSmartRate.getService());
         assertEquals(5.49, lowestSmartRate.getRate(), 0.01);
         assertEquals("USPS", lowestSmartRate.getCarrier());
 
         // Test lowest smartrate with invalid filters (should error due to strict delivery days)
         assertThrows(EasyPostException.class, () -> {
-            Shipment.findLowestSmartrate(smartrates, 0, "percentile_90");
-        });
-
-        // Test lowest smartrate with invalid filters (should error due to bad delivery accuracy)
-        assertThrows(EasyPostException.class, () -> {
-            Shipment.findLowestSmartrate(smartrates, 1, "BAD ACCURACY");
+            Shipment.findLowestSmartrate(smartrates, 0, SmartrateAccuracy.Percentile90);
         });
     }
 }