Merge pull request #431 from EasyPost/metadata

feat: Add carrier metadata endpoint (beta)

Author: Justintime50

Diff for: EasyPost.Tests/ServicesTests/Beta/CarrierMetadataServiceTest.cs

@@ -0,0 +1,76 @@
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using EasyPost.Models.API.Beta;
+using EasyPost.Tests._Utilities;
+using EasyPost.Tests._Utilities.Attributes;
+using EasyPost.Utilities.Internal.Attributes;
+using Xunit;
+using CustomAssertions = EasyPost.Tests._Utilities.Assertions.Assert;
+
+namespace EasyPost.Tests.ServicesTests.Beta
+{
+    public class CarrierMetadataServiceTests : UnitTest
+    {
+        public CarrierMetadataServiceTests() : base("beta_carrier_metadata")
+        {
+        }
+
+        #region Tests
+
+        #region Test CRUD Operations
+
+        /// <summary>
+        ///     Test that we can retrieve all carriers and all metadata from the API when no params are provided.
+        /// </summary>
+        [Fact]
+        [CrudOperations.Read]
+        [Testing.Function]
+        public async Task TestRetrieve()
+        {
+            UseVCR("retrieve");
+
+            List<Carrier> carriers = await Client.Beta.CarrierMetadata.RetrieveCarrierMetadata();
+
+            Assert.IsType<List<Carrier>>(carriers);
+
+            // Assert we get multiple carriers
+            CustomAssertions.Any(carriers, carrier => Assert.Equal("usps", carrier.Name));
+            CustomAssertions.Any(carriers, carrier => Assert.Equal("fedex", carrier.Name));
+        }
+
+        /// <summary>
+        ///     Test that we can retrieve all carriers and all metadata from the API when no params are provided.
+        /// </summary>
+        [Fact]
+        [CrudOperations.Read]
+        [Testing.Parameters]
+        public async Task TestRetrieveWithFilters()
+        {
+            UseVCR("retrieve_with_filters");
+
+            const string carrierName = "usps";
+
+            BetaFeatures.Parameters.Beta.CarrierMetadata.Retrieve parameters = new()
+            {
+                Carriers = new List<string> { carrierName },
+                Types = new List<CarrierMetadataType> { CarrierMetadataType.ServiceLevels, CarrierMetadataType.PredefinedPackages },
+            };
+
+            List<Carrier> carriers = await Client.Beta.CarrierMetadata.RetrieveCarrierMetadata(parameters);
+
+            // Assert we get the single carrier we asked for
+            Assert.True(carriers.Count == 1);
+            Assert.All(carriers, carrier => Assert.Equal(carrierName, carrier.Name));
+
+            // Assert we get service levels and predefined packages as we asked for, but not supported features or shipment options
+            Assert.All(carriers, carrier => Assert.True(carrier.ServiceLevels != null));
+            Assert.All(carriers, carrier => Assert.True(carrier.PredefinedPackages != null));
+            Assert.All(carriers, carrier => Assert.True(carrier.SupportedFeatures == null));
+            Assert.All(carriers, carrier => Assert.True(carrier.ShipmentOptions == null));
+        }
+
+        #endregion
+
+        #endregion
+    }
+}

Diff for: EasyPost.Tests/_Utilities/Assertions/AnyException.cs

@@ -0,0 +1,18 @@
+using Xunit.Sdk;
+
+namespace EasyPost.Tests._Utilities.Assertions
+{
+    /// <summary>
+    /// Exception thrown when an Any assertion has one or more items fail an assertion.
+    /// </summary>
+    public class AnyException : XunitException
+    {
+        /// <summary>
+        /// Creates a new instance of the <see cref="AnyException"/> class.
+        /// </summary>
+        public AnyException()
+            : base("Assert.Any() Failure")
+        {
+        }
+    }
+}

Diff for: EasyPost.Tests/_Utilities/Assertions/CollectionAsserts.cs

@@ -0,0 +1,67 @@
+using System;
+using System.Collections.Generic;
+
+namespace EasyPost.Tests._Utilities.Assertions
+{
+    public abstract partial class Assert
+    {
+        private static void GuardArgumentNotNull(string argName, object argValue)
+        {
+            if (argValue == null)
+                throw new ArgumentNullException(argName);
+        }
+
+        /// <summary>
+        /// Verifies that any items in the collection pass when executed against
+        /// action.
+        /// </summary>
+        /// <typeparam name="T">The type of the object to be verified</typeparam>
+        /// <param name="collection">The collection</param>
+        /// <param name="action">The action to test each item against</param>
+        /// <exception cref="AnyException">Thrown when the collection contains no matching element</exception>
+        public static void Any<T>(IEnumerable<T> collection, Action<T> action)
+        {
+            GuardArgumentNotNull(nameof(collection), collection);
+            GuardArgumentNotNull(nameof(action), action);
+
+            Any(collection, (item, index) => action(item));
+        }
+
+        /// <summary>
+        /// Verifies that any items in the collection pass when executed against
+        /// action. The item index is provided to the action, in addition to the item.
+        /// </summary>
+        /// <typeparam name="T">The type of the object to be verified</typeparam>
+        /// <param name="collection">The collection</param>
+        /// <param name="action">The action to test each item against</param>
+        /// <exception cref="AnyException">Thrown when the collection contains no matching element</exception>
+        public static void Any<T>(IEnumerable<T> collection, Action<T, int> action)
+        {
+            GuardArgumentNotNull(nameof(collection), collection);
+            GuardArgumentNotNull(nameof(action), action);
+
+            int idx = 0;
+
+            bool passed = false;
+
+            foreach (var item in collection)
+            {
+                try
+                {
+                    action(item, idx);
+                    passed = true;
+                    break; // if we get here, we passed, so we can stop iterating
+                }
+                catch (Exception ex)
+                {
+                    // we don't care about the exception, we just want to keep iterating
+                }
+
+                ++idx;
+            }
+
+            if (!passed)
+                throw new AnyException();
+        }
+    }
+}

Diff for: EasyPost.Tests/cassettes/net/beta_carrier_metadata/retrieve.json

@@ -26,6 +26,8 @@ public class BetaClient : EasyPostClient
 
         public RateService Rate { get; }
 
+        public CarrierMetadataService CarrierMetadata { get; }
+
         /// <summary>
         ///     Initializes a new instance of the <see cref="BetaClient"/> class.
         ///     Constructor for the EasyPost beta client.
@@ -38,6 +40,7 @@ internal BetaClient(string apiKey, string? baseUrl = null, HttpClient? customHtt
         {
             Referral = new ReferralService(this);
             Rate = new RateService(this);
+            CarrierMetadata = new CarrierMetadataService(this);
         }
     }
 }