[feat] Add claims API service (#576)

- Add new Claim service, functions
- Add new Claim and ClaimHistoryEntry models
- Add unit tests, fixtures, cassettes as needed
- Bump examples submodule

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## Next Release
+
+- Add new `Claim` service for filing claims on EasyPost shipments and insurances
+
 ## v6.6.0 (2024-07-16)
 
 - Add new `SmartRate` service for interacting with the SmartRate API

EasyPost.Integration/Basics.cs

@@ -29,6 +29,9 @@ public void UserCanLocallyConstructResponseObject()
         var carrierFields = new CarrierFields();
         var carrierMetadata = new CarrierMetadata();
         var carrierType = new CarrierType();
+        var claim = new Claim();
+        var claimCollection = new ClaimCollection();
+        var claimHistoryEntry = new ClaimHistoryEntry();
         var customsInfo = new CustomsInfo();
         var customsItem = new CustomsItem();
         var endShipper = new EndShipper();
@@ -109,6 +112,8 @@ public void UserCanConstructParameterSets()
         var carrierAccountCreateUpsParameters = new EasyPost.Parameters.CarrierAccount.CreateUps();
         var carrierAccountUpdateParameters = new EasyPost.Parameters.CarrierAccount.Update();
         var carrierMetadataRetrieveParameters = new EasyPost.Parameters.CarrierMetadata.Retrieve();
+        var claimCreateParameters = new EasyPost.Parameters.Claim.Create();
+        var claimAllParameters = new EasyPost.Parameters.Claim.All();
         var customsInfoCreateParameters = new EasyPost.Parameters.CustomsInfo.Create();
         var customsItemCreateParameters = new EasyPost.Parameters.CustomsItem.Create();
         var endShipperCreateParameters = new EasyPost.Parameters.EndShipper.Create();

EasyPost.Tests/Fixture.cs

@@ -44,6 +44,8 @@ public static byte[] EventBody
 
         internal static Dictionary<string, object> BasicInsurance => GetFixtureStructure().Insurances.Basic;
 
+        internal static Dictionary<string, object> BasicClaim => GetFixtureStructure().Claims.Basic;
+
         internal static Dictionary<string, object> BasicOrder => GetFixtureStructure().Orders.Basic;
 
         internal static Dictionary<string, object> BasicParcel => GetFixtureStructure().Parcels.Basic;
@@ -274,6 +276,42 @@ internal static ParameterSets.CarrierAccount.CreateUps CreateUps(Dictionary<stri
                 }
             }
 
+            internal static class Claims
+            {
+                internal static ParameterSets.Claim.Create Create(Dictionary<string, object>? fixture)
+                {
+                    fixture ??= new Dictionary<string, object>();
+
+                    return new ParameterSets.Claim.Create
+                    {
+                        Type = fixture.GetOrNullEnum<ClaimType>("type"),
+                        Amount = fixture.GetOrNullDouble("amount"),
+                        TrackingCode = fixture.GetOrNull<string>("tracking_code"),
+                        EmailEvidenceAttachments = fixture.GetOrNull<string[]>("email_evidence_attachments"),
+                        InvoiceAttachments = fixture.GetOrNull<string[]>("invoice_attachments"),
+                        SupportingDocumentationAttachments = fixture.GetOrNull<string[]>("supporting_documentation_attachments"),
+                        Description = fixture.GetOrNull<string>("description"),
+                        ContactEmail = fixture.GetOrNull<string>("contact_email"),
+                        PaymentMethod = fixture.GetOrNullEnum<ClaimPaymentMethod>("payment_method"),
+                        RecipientName = fixture.GetOrNull<string>("recipient_name"),
+                    };
+                }
+
+                internal static ParameterSets.Claim.All All(Dictionary<string, object>? fixture)
+                {
+                    fixture ??= new Dictionary<string, object>();
+
+                    return new ParameterSets.Claim.All
+                    {
+                        PageSize = fixture.GetOrNullInt("page_size"),
+                        BeforeId = fixture.GetOrNull<string>("before_id"),
+                        AfterId = fixture.GetOrNull<string>("after_id"),
+                        StartDatetime = fixture.GetOrNull<string>("start_datetime"),
+                        EndDatetime = fixture.GetOrNull<string>("end_datetime"),
+                    };
+                }
+            }
+
             internal static class CustomsInfo
             {
                 internal static ParameterSets.CustomsInfo.Create Create(Dictionary<string, object>? fixture)

EasyPost.Tests/FixtureData.cs

@@ -19,6 +19,9 @@ public class FixtureStructure
         [JsonProperty("carrier_strings")]
         public CarrierStrings CarrierStrings { get; set; }
 
+        [JsonProperty("claims")]
+        public Claims Claims { get; set; }
+
         [JsonProperty("credit_cards")]
         public CreditCards CreditCards { get; set; }
 
@@ -103,6 +106,16 @@ public class CarrierStrings
         #endregion
     }
 
+    public class Claims
+    {
+        #region JSON Properties
+
+        [JsonProperty("basic")]
+        public Dictionary<string, object> Basic { get; set; }
+
+        #endregion
+    }
+
     public class CreditCards
     {
         #region JSON Properties

EasyPost.Tests/ServicesTests/InsuranceServiceTest.cs

@@ -115,7 +115,7 @@ public async Task TestRefund()
             Insurance insurance = await Client.Insurance.Create(parameters);
             Insurance cancelledInsurance = await Client.Insurance.Refund(insurance.Id);
 
-            Assert.IsType<Insurance>(insurance);
+            Assert.IsType<Insurance>(cancelledInsurance);
             Assert.StartsWith("ins_", cancelledInsurance.Id);
             Assert.Equal("cancelled", cancelledInsurance.Status);
             Assert.Equal("Insurance was cancelled by the user.", cancelledInsurance.Messages[0]);

EasyPost.Tests/ServicesTests/WithParameters/ClaimServiceTest.cs

@@ -0,0 +1,164 @@
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using EasyPost.Exceptions.General;
+using EasyPost.Models.API;
+using EasyPost.Tests._Utilities;
+using EasyPost.Tests._Utilities.Attributes;
+using EasyPost.Utilities.Internal.Attributes;
+using Xunit;
+
+namespace EasyPost.Tests.ServicesTests.WithParameters
+{
+    public class ClaimServiceTests : UnitTest
+    {
+        public ClaimServiceTests() : base("claim_service_with_parameters")
+        {
+        }
+
+        #region Tests
+
+        private static async Task<Shipment> PrepareInsuredShipment(Client client, Parameters.Shipment.Create createShipmentParameters, double claimAmount)
+        {
+            Shipment shipment = await client.Shipment.Create(createShipmentParameters);
+            Rate rate = shipment.LowestRate();
+            Shipment purchaseShipment = await client.Shipment.Buy(shipment.Id, rate.Id);
+            Shipment _ = await client.Shipment.Insure(purchaseShipment.Id, claimAmount);
+
+            return purchaseShipment;
+        }
+
+        #region Test CRUD Operations
+
+        [Fact]
+        [CrudOperations.Create]
+        [Testing.Function]
+        public async Task TestCreate()
+        {
+            UseVCR("create");
+
+            const double claimAmount = 100.00;
+            Parameters.Shipment.Create createShipmentParameters = Fixtures.Parameters.Shipments.Create(Fixtures.FullShipment);
+            Shipment insuredShipment = await PrepareInsuredShipment(Client, createShipmentParameters, claimAmount);
+
+            Dictionary<string, object> claimData = Fixtures.BasicClaim;
+            Parameters.Claim.Create claimParameters = Fixtures.Parameters.Claims.Create(claimData);
+
+            claimParameters.TrackingCode = insuredShipment.TrackingCode;
+            claimParameters.Amount = claimAmount;
+
+            Claim claim = await Client.Claim.Create(claimParameters);
+
+            Assert.IsType<Claim>(claim);
+            Assert.StartsWith("clm_", claim.Id);
+            Assert.Equal(claimParameters.TrackingCode, claim.TrackingCode);
+            Assert.Equal(claimParameters.Amount, claim.RequestedAmount);
+            Assert.Equal(claimParameters.Type, claim.Type);
+            Assert.Equal(claim.PaymentMethod, ClaimPaymentMethod.EasyPostWallet);
+        }
+
+        [Fact]
+        [CrudOperations.Read]
+        [Testing.Function]
+        public async Task TestAll()
+        {
+            UseVCR("all");
+
+            Dictionary<string, object> data = new Dictionary<string, object>() { { "page_size", Fixtures.PageSize } };
+            Parameters.Claim.All parameters = Fixtures.Parameters.Claims.All(data);
+
+            ClaimCollection claimCollection = await Client.Claim.All(parameters);
+
+            List<Claim> claims = claimCollection.Claims;
+
+            Assert.True(claims.Count <= Fixtures.PageSize);
+            foreach (Claim item in claims)
+            {
+                Assert.IsType<Claim>(item);
+            }
+        }
+
+        [Fact]
+        [CrudOperations.Read]
+        [Testing.Function]
+        public async Task TestGetNextPage()
+        {
+            UseVCR("get_next_page");
+
+            Dictionary<string, object> data = new Dictionary<string, object>() { { "page_size", Fixtures.PageSize } };
+            Parameters.Claim.All parameters = Fixtures.Parameters.Claims.All(data);
+
+            ClaimCollection collection = await Client.Claim.All(parameters);
+
+            try
+            {
+                ClaimCollection nextPageCollection = await Client.Claim.GetNextPage(collection);
+
+                // If the first ID in the next page is the same as the first ID in the current page, then we didn't get the next page
+                Assert.NotEqual(collection.Claims[0].Id, nextPageCollection.Claims[0].Id);
+            }
+            catch (EndOfPaginationError) // There's no second page, that's not a failure
+            {
+                Assert.True(true);
+            }
+            catch // Any other exception is a failure
+            {
+                Assert.True(false);
+            }
+        }
+
+        [Fact]
+        [CrudOperations.Read]
+        [Testing.Function]
+        public async Task TestRetrieve()
+        {
+            UseVCR("retrieve");
+
+            const double claimAmount = 100.00;
+            Parameters.Shipment.Create createShipmentParameters = Fixtures.Parameters.Shipments.Create(Fixtures.FullShipment);
+            Shipment insuredShipment = await PrepareInsuredShipment(Client, createShipmentParameters, claimAmount);
+
+            Dictionary<string, object> claimData = Fixtures.BasicClaim;
+            Parameters.Claim.Create claimParameters = Fixtures.Parameters.Claims.Create(claimData);
+
+            claimParameters.TrackingCode = insuredShipment.TrackingCode;
+            claimParameters.Amount = claimAmount;
+
+            Claim claim = await Client.Claim.Create(claimParameters);
+
+            Claim retrievedClaim = await Client.Claim.Retrieve(claim.Id);
+
+            Assert.IsType<Claim>(retrievedClaim);
+            // Must compare IDs since other elements of object may be different
+            Assert.Equal(claim.Id, retrievedClaim.Id);
+        }
+
+        [Fact]
+        [CrudOperations.Create]
+        [Testing.Function]
+        public async Task TestCancel()
+        {
+            UseVCR("cancel");
+
+            const double claimAmount = 100.00;
+            Parameters.Shipment.Create createShipmentParameters = Fixtures.Parameters.Shipments.Create(Fixtures.FullShipment);
+            Shipment insuredShipment = await PrepareInsuredShipment(Client, createShipmentParameters, claimAmount);
+
+            Dictionary<string, object> claimData = Fixtures.BasicClaim;
+            Parameters.Claim.Create claimParameters = Fixtures.Parameters.Claims.Create(claimData);
+
+            claimParameters.TrackingCode = insuredShipment.TrackingCode;
+            claimParameters.Amount = claimAmount;
+
+            Claim claim = await Client.Claim.Create(claimParameters);
+            Claim cancelledClaim = await Client.Claim.Cancel(claim.Id);
+
+            Assert.IsType<Claim>(cancelledClaim);
+            Assert.StartsWith("clm_", cancelledClaim.Id);
+            Assert.Equal("cancelled", cancelledClaim.Status);
+        }
+
+        #endregion
+
+        #endregion
+    }
+}