feat: adds get_lowest_stateless_rate function

Author: Justintime50

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 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)
 

easypost/beta/rate.py

@@ -1,10 +1,12 @@
 from typing import (
     Any,
     Dict,
+    List,
     Optional,
 )
 
 from easypost.easypost_object import convert_to_easypost_object
+from easypost.error import Error
 from easypost.requestor import (
     RequestMethod,
     Requestor,
@@ -23,4 +25,30 @@ def retrieve_stateless_rates(cls, api_key: Optional[str] = None, **params) -> Di
         }
         response, api_key = requestor.request(method=RequestMethod.POST, url=url, params=wrapped_params, beta=True)
 
-        return convert_to_easypost_object(response=response, api_key=api_key)
+        return convert_to_easypost_object(response=response.get("rates", None), api_key=api_key)
+
+    @classmethod
+    def get_lowest_stateless_rate(
+        cls, 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/cassettes/test_beta_get_lowest_stateless_rate.yaml

@@ -4,9 +4,18 @@
 
 
 @pytest.mark.vcr()
-def test_retrieve_stateless_rates(basic_shipment):
-    response = easypost.beta.Rate.retrieve_stateless_rates(**basic_shipment)
-
-    stateless_rates = response["rates"]
+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 = easypost.beta.Rate.get_lowest_stateless_rate(stateless_rates)
+
+    assert lowest_stateless_rate["service"] == "First"