[feat] Add new SmartRate "recommend ship date", "estimate delivery date" functions (#457)

- Add new `SmartRate` service
- Add `Shipment.recommendShipDate`, `SmartRate.recommendShipDate`, and `SmartRate.estimateDeliveryDate` functions
- Update/add unit tests, cassettes as needed
- Update TypeScript types for new functions and class

Author: nwithan8

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Next Release
 
+- Adds new `Shipment.recommendShipDate`, `SmartRate.recommendShipDate`, and `SmartRate.estimateDeliveryDate` functions
 - Routes `UpsAccount`, `UpsMailInnovationsAccount`, and `UpsSurepostAccount` create/update requests to the new `/ups_oauth_registrations` endpoint
   - Starting `2024-08-05`, UPS accounts will require a new payload to register or update. See [UPS OAuth 2.0 Update](https://support.easypost.com/hc/en-us/articles/26635027512717-UPS-OAuth-2-0-Update) for more details
 

src/easypost.js

@@ -29,6 +29,7 @@ import RefundService from './services/refund_service';
 import ReportService from './services/report_service';
 import ScanFormService from './services/scan_form_service';
 import ShipmentService from './services/shipment_service';
+import SmartRateService from './services/smart_rate_service';
 import TrackerService from './services/tracker_service';
 import UserService from './services/user_service';
 import WebhookService from './services/webhook_service';
@@ -106,6 +107,7 @@ export const SERVICES = {
   Report: ReportService,
   ScanForm: ScanFormService,
   Shipment: ShipmentService,
+  SmartRate: SmartRateService,
   Tracker: TrackerService,
   User: UserService,
   Webhook: WebhookService,

src/services/shipment_service.js

@@ -238,9 +238,9 @@ export default (easypostClient) =>
     }
 
     /**
-     * Retrieves the estimated delivery date of each Rate via SmartRate.
-     * @param {string} id
-     * @param {string} plannedShipDate
+     * Retrieve the estimated delivery date of each Rate via SmartRate.
+     * @param {string} id - The ID of the shipment to retrieve the estimated delivery date for.
+     * @param {string} plannedShipDate - The planned ship date of the shipment.
      * @returns {Array} - An array of the estimated delivery date and rates.
      */
     static async retrieveEstimatedDeliveryDate(id, plannedShipDate) {
@@ -258,4 +258,26 @@ export default (easypostClient) =>
         return Promise.reject(e);
       }
     }
+
+    /**
+     * Retrieve a recommended ship date for a {@link Shipment shipment} via the Precision Shipping API, based on a specific desired delivery date.
+     * @param id - The ID of the shipment to retrieve the recommended ship date for.
+     * @param desiredDeliveryDate - The desired delivery date for the shipment.
+     * @returns {Array} - An array of the recommended ship date and rates.
+     */
+    static async recommendShipDate(id, desiredDeliveryDate) {
+      const url = `shipments/${id}/smartrate/precision_shipping`;
+
+      const params = {
+        desired_delivery_date: desiredDeliveryDate,
+      };
+
+      try {
+        const response = await easypostClient._get(url, params);
+
+        return this._convertToEasyPostObject(response.body.rates ?? [], params);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    }
   };

src/services/smart_rate_service.js

@@ -0,0 +1,42 @@
+import baseService from './base_service';
+
+export default (easypostClient) =>
+  /**
+   * The SmartRateService class provides methods for interacting with EasyPost SmartRate APIs.
+   * @param {EasyPostClient} easypostClient - The pre-configured EasyPostClient instance to use for API requests with this service.
+   */
+  class SmartRateService extends baseService(easypostClient) {
+    /**
+     * Retrieve the estimated delivery date of each carrier-service level combination via the Smart Deliver By API, based on a specific ship date and origin-destination postal code pair.
+     * @param params - The parameters to estimate the delivery date with.
+     * @returns {Object} - Estimates and related metadata.
+     */
+    static async estimateDeliveryDate(params) {
+      const url = 'smartrate/deliver_by';
+
+      try {
+        const response = await easypostClient._post(url, params);
+
+        return this._convertToEasyPostObject(response.body, params);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    }
+
+    /**
+     * Retrieve a recommended ship date for each carrier-service level combination via the Smart Deliver On API, based on a specific delivery date and origin-destination postal code pair.
+     * @param params - The parameters to recommend the ship date with.
+     * @returns {Object} - Recommendation and related metadata.
+     */
+    static async recommendShipDate(params) {
+      const url = 'smartrate/deliver_on';
+
+      try {
+        const response = await easypostClient._post(url, params);
+
+        return this._convertToEasyPostObject(response.body, params);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    }
+  };