feat: add retrieve_stateless_rates function

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## Next Release
+
+- Adds `retrieve_stateless_rates` function to pull stateless rates when shipment data is provided
+- Adds `get_lowest_stateless_rate` function to filter the lowest stateless rate
+
 ## v7.9.0 (2023-01-18)
 
 - Adds `all` function to `Pickup` to retrieve all pickups

easypost/beta/__init__.py

@@ -1,2 +1,3 @@
 # flake8: noqa
+from easypost.beta.rate import Rate
 from easypost.beta.referral import Referral

easypost/beta/rate.py

@@ -0,0 +1,26 @@
+from typing import (
+    Any,
+    Dict,
+    Optional,
+)
+
+from easypost.easypost_object import convert_to_easypost_object
+from easypost.requestor import (
+    RequestMethod,
+    Requestor,
+)
+from easypost.resource import Resource
+
+
+class Rate(Resource):
+    @classmethod
+    def retrieve_stateless_rates(cls, api_key: Optional[str] = None, **params) -> Dict[str, Any]:
+        """Retrieves stateless rates by passing shipment data."""
+        requestor = Requestor(local_api_key=api_key)
+        url = cls.class_url()
+        wrapped_params = {
+            "shipment": params,
+        }
+        response, api_key = requestor.request(method=RequestMethod.POST, url=url, params=wrapped_params, beta=True)
+
+        return convert_to_easypost_object(response=response.get("rates", None), api_key=api_key)

easypost/util.py

@@ -1,4 +1,8 @@
-from typing import List
+from typing import (
+    Any,
+    Dict,
+    List,
+)
 
 from easypost.easypost_object import EasyPostObject
 from easypost.error import Error
@@ -29,3 +33,29 @@ def get_lowest_object_rate(
         raise Error(message="No rates found.")
 
     return lowest_rate
+
+
+def get_lowest_stateless_rate(
+    stateless_rates: List[Dict[str, Any]], carriers: List[str] = None, services: List[str] = None
+) -> Dict[str, Any]:
+    """Get the lowest stateless rate."""
+    carriers = carriers or []
+    services = services or []
+    lowest_rate = None
+
+    carriers = [carrier.lower() for carrier in carriers]
+    services = [service.lower() for service in services]
+
+    for rate in stateless_rates:
+        if (carriers and rate["carrier"].lower() not in carriers) or (
+            services and rate["service"].lower() not in services
+        ):
+            continue
+
+        if lowest_rate is None or float(rate.rate) < float(lowest_rate.rate):
+            lowest_rate = rate
+
+    if lowest_rate is None:
+        raise Error(message="No rates found.")
+
+    return lowest_rate

tests/test_beta_rate.py

@@ -0,0 +1,22 @@
+import pytest
+
+import easypost
+from easypost.util import get_lowest_stateless_rate
+
+
+@pytest.mark.vcr()
+def test_beta_retrieve_stateless_rates(basic_shipment):
+    """Tests that we can retrieve stateless rates when basic shipment data."""
+    stateless_rates = easypost.beta.Rate.retrieve_stateless_rates(**basic_shipment)
+
+    assert all(rate["object"] == "Rate" for rate in stateless_rates)
+
+
+@pytest.mark.vcr()
+def test_beta_get_lowest_stateless_rate(basic_shipment):
+    """Tests that we can return the lowest stateless rate from a list of stateless rates."""
+    stateless_rates = easypost.beta.Rate.retrieve_stateless_rates(**basic_shipment)
+
+    lowest_stateless_rate = get_lowest_stateless_rate(stateless_rates)
+
+    assert lowest_stateless_rate["service"] == "First"