Merge pull request #271 from EasyPost/carrier_metadata_ga

feat: carrier metadata GA

Author: Justintime50

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Next Release
 
+- Retrieving carrier metadata is now generally available via `client.carrierMetadata.retrieve`
 - Bump all dependencies
 
 ## v6.6.1 (2023-05-09)

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

@@ -25,6 +25,7 @@ public class BetaCarrierMetadataService {
      *
      * @return CarrierMetadata object
      * @throws EasyPostException
+     * @deprecated Use carrierMetadata.retrieve instead
      */
     public CarrierMetadata retrieveCarrierMetadata() throws EasyPostException {
         return retrieveCarrierMetadata(null);
@@ -36,6 +37,7 @@ public CarrierMetadata retrieveCarrierMetadata() throws EasyPostException {
      * @param carriers The list of carriers in string.
      * @return CarrierMetadata object
      * @throws EasyPostException
+     * @deprecated Use carrierMetadata.retrieve instead
      */
     public CarrierMetadata retrieveCarrierMetadata(List<String> carriers) throws EasyPostException {
         return retrieveCarrierMetadata(carriers, null);
@@ -48,6 +50,7 @@ public CarrierMetadata retrieveCarrierMetadata(List<String> carriers) throws Eas
      * @param types    The list of types in string.
      * @return CarrierMetadata object
      * @throws EasyPostException
+     * @deprecated Use carrierMetadata.retrieve instead
      */
     public CarrierMetadata retrieveCarrierMetadata(List<String> carriers, List<String> types) throws EasyPostException {
         HashMap<String, Object> params = new HashMap<>();

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

@@ -0,0 +1,66 @@
+package com.easypost.service;
+
+import java.util.HashMap;
+import java.util.List;
+
+import com.easypost.exception.EasyPostException;
+import com.easypost.http.Requestor;
+import com.easypost.http.Requestor.RequestMethod;
+import com.easypost.model.CarrierMetadata;
+
+public class CarrierMetadataService {
+    private final EasyPostClient client;
+
+    /**
+     * CarrierMetadataService constructor.
+     *
+     * @param client The client object.
+     */
+    CarrierMetadataService(EasyPostClient client) {
+        this.client = client;
+    }
+
+    /**
+     * Retrieves all carrier metadata.
+     *
+     * @return CarrierMetadata object
+     * @throws EasyPostException
+     */
+    public CarrierMetadata retrieve() throws EasyPostException {
+        return retrieve(null);
+    }
+
+    /**
+     * Retrieves carrier metadata for given carriers.
+     *
+     * @param carriers The list of carriers in string.
+     * @return CarrierMetadata object
+     * @throws EasyPostException
+     */
+    public CarrierMetadata retrieve(List<String> carriers) throws EasyPostException {
+        return retrieve(carriers, null);
+    }
+
+    /**
+     * Retrieves carrier metadata for given carriers and types.
+     *
+     * @param carriers The list of carriers in string.
+     * @param types    The list of types in string.
+     * @return CarrierMetadata object
+     * @throws EasyPostException
+     */
+    public CarrierMetadata retrieve(List<String> carriers, List<String> types) throws EasyPostException {
+        HashMap<String, Object> params = new HashMap<>();
+
+        if (carriers != null && !carriers.isEmpty()) {
+            params.put("carriers", String.join(",", carriers));
+        }
+
+        if (types != null && !types.isEmpty()) {
+            params.put("types", String.join(",", types));
+        }
+
+        return Requestor.request(RequestMethod.GET, "metadata/carriers", params,
+                CarrierMetadata.class, client);
+    }
+}

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

@@ -17,6 +17,7 @@ public class EasyPostClient {
     public final BetaRateService betaRate;
     public final BillingService billing;
     public final CarrierAccountService carrierAccount;
+    public final CarrierMetadataService carrierMetadata;
     public final CarrierTypeService carrierType;
     public final CustomsInfoService customsInfo;
     public final CustomsItemService customsItem;
@@ -122,6 +123,7 @@ public EasyPostClient(String apiKey, int connectTimeoutMilliseconds, int readTim
         this.betaRate = new BetaRateService(this);
         this.billing = new BillingService(this);
         this.carrierAccount = new CarrierAccountService(this);
+        this.carrierMetadata = new CarrierMetadataService(this);
         this.carrierType = new CarrierTypeService(this);
         this.customsInfo = new CustomsInfoService(this);
         this.customsItem = new CustomsItemService(this);

src/test/cassettes/carrier_metadata/retrieve_carrier_metadata.json

@@ -32,7 +32,7 @@ public static void setup() throws EasyPostException {
      * @throws EasyPostException when the request fails.
      */
     @Test
-    public void testRetrieveStatelessRates() throws EasyPostException {
+    public void testRetrieveBetaCarrierMetadata() throws EasyPostException {
         vcr.setUpTest("retrieve_carrier_metadata");
 
         CarrierMetadata carrierMetadata = vcr.client.betaCarrierMetadata.retrieveCarrierMetadata();
@@ -47,7 +47,7 @@ public void testRetrieveStatelessRates() throws EasyPostException {
      * @throws EasyPostException when the request fails.
      */
     @Test
-    public void testRetrieveStatelessRatesWithFilter() throws EasyPostException {
+    public void testRetrieveBetaCarrierMetadataWithFilter() throws EasyPostException {
         vcr.setUpTest("retrieve_carrier_metadata_with_filter");
         List<String> carriers = Arrays.asList("usps");
         List<String> types = Arrays.asList("service_levels", "predefined_packages");

src/test/cassettes/carrier_metadata/retrieve_carrier_metadata_with_filter.json

@@ -0,0 +1,63 @@
+package com.easypost;
+
+import com.easypost.exception.EasyPostException;
+import com.easypost.model.CarrierMetadata;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+public class CarrierMetadataTest {
+    private static TestUtils.VCR vcr;
+
+    /**
+     * Set up the testing environment for this file.
+     *
+     * @throws EasyPostException when the request fails.
+     */
+    @BeforeAll
+    public static void setup() throws EasyPostException {
+        vcr = new TestUtils.VCR("carrier_metadata", TestUtils.ApiKey.TEST);
+    }
+
+    /**
+     * Test retrieving all carrier metadata.
+     *
+     * @throws EasyPostException when the request fails.
+     */
+    @Test
+    public void testRetrieveCarrierMetadata() throws EasyPostException {
+        vcr.setUpTest("retrieve_carrier_metadata");
+
+        CarrierMetadata carrierMetadata = vcr.client.carrierMetadata.retrieve();
+
+        assertTrue(carrierMetadata.getCarriers().stream().anyMatch(carrier -> carrier.getName().equals("usps")));
+        assertTrue(carrierMetadata.getCarriers().stream().anyMatch(carrier -> carrier.getName().equals("fedex")));
+    }
+
+    /**
+     * Test retrieving carrier metadata for a specific carrier.
+     *
+     * @throws EasyPostException when the request fails.
+     */
+    @Test
+    public void testRetrieveCarrierMetadataWithFilter() throws EasyPostException {
+        vcr.setUpTest("retrieve_carrier_metadata_with_filter");
+        List<String> carriers = Arrays.asList("usps");
+        List<String> types = Arrays.asList("service_levels", "predefined_packages");
+        CarrierMetadata carrierMetadata = vcr.client.carrierMetadata.retrieve(carriers, types);
+
+        assertTrue(carrierMetadata.getCarriers().stream()
+                .allMatch(carrier -> carrier.getName().equals("usps")));
+        assertEquals(1, carrierMetadata.getCarriers().size());
+        assertNotNull(carrierMetadata.getCarriers().get(0).getServiceLevels());
+        assertNotNull(carrierMetadata.getCarriers().get(0).getPredefinedPackages());
+        assertNull(carrierMetadata.getCarriers().get(0).getSupportedFeatures());
+    }
+}