add retrieveEstimatedDeliveryDate function in Shipment class (#262)

Author: jchen293

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## Next release
+
+- Adds `retrieveEstimatedDeliveryDate` function to the Shipment class
+
 ## v6.5.0 (2023-04-18)
 
 - Adds beta `retrieveCarrierMetadata` function

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

@@ -0,0 +1,16 @@
+package com.easypost.model;
+
+import lombok.Getter;
+
+@Getter
+public class EstimatedDeliveryDate {
+    private EasyPostTimeInTransitData easypostTimeInTransitData;
+    private Rate rate;
+}
+
+@Getter
+class EasyPostTimeInTransitData {
+    private TimeInTransit daysInTransit;
+    private String easypostEstimatedDeliveryDate;
+    private String plannedShipDate;
+}

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

@@ -0,0 +1,9 @@
+package com.easypost.model;
+
+import java.util.List;
+import lombok.Getter;
+
+@Getter
+public class EstimatedDeliveryDateResponse {
+    private List<EstimatedDeliveryDate> rates;
+}

src/main/java/com/easypost/service/ShipmentService.java

@@ -7,6 +7,8 @@
 import com.easypost.http.Requestor;
 import com.easypost.http.Requestor.RequestMethod;
 import com.easypost.model.ShipmentCollection;
+import com.easypost.model.EstimatedDeliveryDate;
+import com.easypost.model.EstimatedDeliveryDateResponse;
 import com.easypost.model.Rate;
 import com.easypost.model.Shipment;
 import com.easypost.model.SmartRate;
@@ -85,8 +87,8 @@ public Shipment retrieve(final String id) throws EasyPostException {
     public ShipmentCollection all(final Map<String, Object> params) throws EasyPostException {
         String endpoint = "shipments";
 
-        ShipmentCollection shipmentCollection =
-                Requestor.request(RequestMethod.GET, endpoint, params, ShipmentCollection.class, client);
+        ShipmentCollection shipmentCollection = Requestor.request(RequestMethod.GET, endpoint, params,
+                ShipmentCollection.class, client);
         // we store the params in the collection so that we can use them to get the next page
         shipmentCollection.setPurchased(InternalUtilities.getOrDefault(params, "purchased", null));
         shipmentCollection.setIncludeChildren(InternalUtilities.getOrDefault(params, "include_children", null));
@@ -214,9 +216,8 @@ public List<SmartRate> smartrates(final String id) throws EasyPostException {
     public List<SmartRate> smartrates(final String id, final Map<String, Object> params) throws EasyPostException {
         String endpoint = "shipments/" + id + "/smartrate";
 
-        SmartrateCollection smartrateCollection =
-                Requestor.request(RequestMethod.GET, endpoint, params,
-                        SmartrateCollection.class, client);
+        SmartrateCollection smartrateCollection = Requestor.request(RequestMethod.GET, endpoint, params,
+                SmartrateCollection.class, client);
 
         return smartrateCollection.getSmartrates();
     }
@@ -322,7 +323,7 @@ public Shipment buy(final String id, final Map<String, Object> params, final boo
      * @throws EasyPostException when the request fails.
      */
     public Shipment buy(final String id, final Map<String, Object> params, final boolean withCarbonOffset,
-                        final String endShipperId) throws EasyPostException {
+            final String endShipperId) throws EasyPostException {
         params.put("carbon_offset", withCarbonOffset);
 
         if (endShipperId != null && !endShipperId.isEmpty()) {
@@ -469,7 +470,7 @@ public SmartRate getLowestSmartRate(final List<SmartRate> smartRates, int delive
      * @throws EasyPostException when the request fails.
      */
     public SmartRate findLowestSmartrate(final List<SmartRate> smartRates, int deliveryDay,
-                                         SmartrateAccuracy deliveryAccuracy) throws EasyPostException {
+            SmartrateAccuracy deliveryAccuracy) throws EasyPostException {
         SmartRate lowestSmartrate = null;
 
         for (SmartRate rate : smartRates) {
@@ -524,4 +525,23 @@ public Shipment generateForm(final String id, final String formType, final Map<S
         return Requestor.request(RequestMethod.POST, endpoint, wrappedParams, Shipment.class,
                 client);
     }
+
+    /**
+     * Retrieves the estimated delivery date of each Rate via SmartRate.
+     * 
+     * @param id              The id of the shipment.
+     * @param plannedShipDate The planned shipment date.
+     * @return EstimatedDeliveryDate object.
+     * @throws EasyPostException
+     */
+    public List<EstimatedDeliveryDate> retrieveEstimatedDeliveryDate(final String id, final String plannedShipDate)
+            throws EasyPostException {
+        HashMap<String, Object> params = new HashMap<>();
+        params.put("planned_ship_date", plannedShipDate);
+        String endpoint = "shipments/" + id + "/smartrate/delivery_date";
+
+        EstimatedDeliveryDateResponse response = Requestor.request(RequestMethod.GET, endpoint, params,
+                EstimatedDeliveryDateResponse.class, client);
+        return response.getRates();
+    }
 }

src/test/cassettes/shipment/retrieve_estimated_delivery_date.json

@@ -318,4 +318,13 @@ public static HashMap<String, Object> rmaFormOptions() {
     public static HashMap<String, Object> referralUser() {
         return Objects.requireNonNull(getFixtureData()).users.referral;
     }
+
+    /**
+     * Get the default planned ship date.
+     *
+     * @return The default planned ship date
+     */
+    public static String plannedShipDate() {
+        return "2023-04-28";
+    }
 }

src/test/java/com/easypost/Fixtures.java

@@ -5,6 +5,7 @@
 import com.easypost.exception.General.InvalidParameterError;
 import com.easypost.model.Address;
 import com.easypost.model.EndShipper;
+import com.easypost.model.EstimatedDeliveryDate;
 import com.easypost.model.Fee;
 import com.easypost.model.Form;
 import com.easypost.model.Parcel;
@@ -522,8 +523,8 @@ public void testInstanceLowestSmartRate() throws EasyPostException {
         vcr.setUpTest("lowest_smartrate");
 
         Shipment shipment = createBasicShipment();
-        SmartRate lowestSmartRateFilters =
-                vcr.client.shipment.lowestSmartRate(shipment.getId(), 2, SmartrateAccuracy.Percentile90);
+        SmartRate lowestSmartRateFilters = vcr.client.shipment.lowestSmartRate(shipment.getId(), 2,
+                SmartrateAccuracy.Percentile90);
 
         // Test lowest smartrate with valid filters
         assertEquals("Priority", lowestSmartRateFilters.getService());
@@ -536,8 +537,8 @@ public void testInstanceLowestSmartRate() throws EasyPostException {
             vcr.client.shipment.lowestSmartRate(shipment.getId(), 0, SmartrateAccuracy.Percentile90);
         });
 
-        SmartRate deprecatedLowestSmartRateFilters =
-                vcr.client.shipment.lowestSmartRate(shipment.getId(), 2, "percentile_90");
+        SmartRate deprecatedLowestSmartRateFilters = vcr.client.shipment.lowestSmartRate(shipment.getId(), 2,
+                "percentile_90");
 
         // Test lowest smartrate with valid filters
         assertEquals("Priority", deprecatedLowestSmartRateFilters.getService());
@@ -649,8 +650,8 @@ public void testGenerateFormWithOption() throws EasyPostException {
         Shipment shipment = createOneCallBuyShipment();
         String formType = "return_packing_slip";
 
-        Shipment shipmentWithForm =
-                vcr.client.shipment.generateForm(shipment.getId(), formType, Fixtures.rmaFormOptions());
+        Shipment shipmentWithForm = vcr.client.shipment.generateForm(shipment.getId(), formType,
+                Fixtures.rmaFormOptions());
 
         assertTrue(shipmentWithForm.getForms().size() > 0);
 
@@ -794,4 +795,22 @@ public void testBuyShipmentWithEndShipperId() throws EasyPostException {
 
         assertNotNull(boughtShipment.getPostageLabel());
     }
+
+    /**
+     * Tests that we retrieve time-in-transit data for each of the Rates of a Shipment.
+     *
+     * @throws EasyPostException when the request fails.
+     */
+    @Test
+    public void testRetrieveEstimatedDeliveryDate() throws EasyPostException {
+        vcr.setUpTest("retrieve_estimated_delivery_date");
+
+        Shipment shipment = vcr.client.shipment.create(Fixtures.basicShipment());
+
+        List<EstimatedDeliveryDate> estimatedDeliveryDates = vcr.client.shipment
+                .retrieveEstimatedDeliveryDate(shipment.getId(), Fixtures.plannedShipDate());
+        for (EstimatedDeliveryDate estimatedDeliveryDate : estimatedDeliveryDates) {
+            assertNotNull(estimatedDeliveryDate.getEasypostTimeInTransitData());
+        }
+    }
 }