Merge pull request #338 from EasyPost/smartrate_service

feat: adds new recommend_ship_date and estimate_delivery_date functions

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Next Release
 
+- Adds new `shipment.recommend_ship_date`, `smartrate.recommend_ship_date`, and `smartrate.estimate_delivery_date` 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?utm_medium=email&_hsenc=p2ANqtz-96MmFtWICOzy9sKRbbcZSiMovZSrY3MSX1_bgY9N3f9yLVfWQdLhjAGq-SmNcOnDIS6GYhZ0OApjDBrGkKyLLMx1z6_TFOVp6-wllhEFQINrkuRuc&_hsmi=313130292&utm_content=313130292&utm_source=hs_email) for more details
 

easypost/easypost_client.py

@@ -32,6 +32,7 @@
     ReportService,
     ScanFormService,
     ShipmentService,
+    SmartRateService,
     TrackerService,
     UserService,
     WebhookService,
@@ -75,6 +76,7 @@ def __init__(
         self.report = ReportService(self)
         self.scan_form = ScanFormService(self)
         self.shipment = ShipmentService(self)
+        self.smartrate = SmartRateService(self)
         self.tracker = TrackerService(self)
         self.user = UserService(self)
         self.webhook = WebhookService(self)

easypost/services/__init__.py

@@ -21,6 +21,7 @@
 from easypost.services.report_service import ReportService
 from easypost.services.scan_form_service import ScanFormService
 from easypost.services.shipment_service import ShipmentService
+from easypost.services.smartrate_service import SmartRateService
 from easypost.services.tracker_service import TrackerService
 from easypost.services.user_service import UserService
 from easypost.services.webhook_service import WebhookService

easypost/services/shipment_service.py

@@ -153,3 +153,13 @@ def retrieve_estimated_delivery_date(self, id: str, planned_ship_date: str) -> L
         response = Requestor(self._client).request(method=RequestMethod.GET, url=url, params=wrapped_params)
 
         return convert_to_easypost_object(response=response.get("rates", []))
+
+    def recommend_ship_date(self, id: str, **params) -> List[Dict[str, Any]]:
+        """Retrieve a recommended ship date for an existing Shipment via the Precision Shipping API,
+        based on a specific desired delivery date.
+        """
+        url = f"{self._instance_url(self._model_class, id)}/smartrate/precision_shipping"
+
+        response = Requestor(self._client).request(method=RequestMethod.GET, url=url, params=params)
+
+        return convert_to_easypost_object(response=response.get("rates", []))

easypost/services/smartrate_service.py

@@ -0,0 +1,38 @@
+from typing import (
+    Any,
+    Dict,
+    List,
+)
+
+from easypost.easypost_object import convert_to_easypost_object
+from easypost.requestor import (
+    RequestMethod,
+    Requestor,
+)
+from easypost.services.base_service import BaseService
+
+
+class SmartRateService(BaseService):
+    def __init__(self, client):
+        self._client = client
+        self._model_class = "Smartrate"
+
+    def estimate_delivery_date(self, **params) -> List[Dict[str, Any]]:
+        """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.
+        """
+        url = "/smartrate/deliver_by"
+
+        response = Requestor(self._client).request(method=RequestMethod.POST, url=url, params=params)
+
+        return convert_to_easypost_object(response=response)
+
+    def recommend_ship_date(self, **params) -> List[Dict[str, Any]]:
+        """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.
+        """
+        url = "/smartrate/deliver_on"
+
+        response = Requestor(self._client).request(method=RequestMethod.POST, url=url, params=params)
+
+        return convert_to_easypost_object(response=response)

tests/conftest.py

@@ -344,4 +344,9 @@ def rma_form_options():
 
 @pytest.fixture
 def planned_ship_date():
-    return "2023-12-28"
+    return "2024-07-11"
+
+
+@pytest.fixture
+def desired_delivery_date():
+    return "2024-07-16"

tests/test_shipment.py

@@ -319,3 +319,13 @@ def test_retrieve_estimated_delivery_date(basic_shipment, planned_ship_date, tes
     rates = test_client.shipment.retrieve_estimated_delivery_date(shipment.id, planned_ship_date=planned_ship_date)
 
     assert all(entry.get("easypost_time_in_transit_data") for entry in rates)
+
+
+@pytest.mark.vcr()
+def test_shipment_recommend_ship_date(basic_shipment, desired_delivery_date, test_client):
+    """Test that we retrieve SmartRates when providing a shipment and desired delivery date."""
+    shipment = test_client.shipment.create(**basic_shipment)
+
+    rates = test_client.shipment.recommend_ship_date(shipment.id, desired_delivery_date=desired_delivery_date)
+
+    assert all(entry.get("easypost_time_in_transit_data") for entry in rates)

tests/test_smartrate.py

@@ -0,0 +1,45 @@
+import pytest
+
+
+@pytest.mark.vcr()
+def test_smartrate_estimate_delivery_date(
+    basic_shipment,
+    ca_address_1,
+    ca_address_2,
+    planned_ship_date,
+    usps,
+    test_client,
+):
+    """Test that we retrieve SmartRates when provided a from/to zip and planned ship date."""
+    params = {
+        "from_zip": ca_address_1["zip"],
+        "to_zip": ca_address_2["zip"],
+        "planned_ship_date": planned_ship_date,
+        "carriers": [usps],
+    }
+
+    rates = test_client.smartrate.estimate_delivery_date(**params)
+
+    assert all(entry.get("easypost_time_in_transit_data") for entry in rates["results"])
+
+
+@pytest.mark.vcr()
+def test_smartrate_recommend_ship_date(
+    basic_shipment,
+    ca_address_1,
+    ca_address_2,
+    desired_delivery_date,
+    usps,
+    test_client,
+):
+    """Test that we retrieve SmartRates when provided a from/to zip and desired delivery date."""
+    params = {
+        "from_zip": ca_address_1["zip"],
+        "to_zip": ca_address_2["zip"],
+        "desired_delivery_date": desired_delivery_date,
+        "carriers": [usps],
+    }
+
+    rates = test_client.smartrate.recommend_ship_date(**params)
+
+    assert all(entry.get("easypost_time_in_transit_data") for entry in rates["results"])