Add Claims service (#320)

* Add Claims service

* address comment

* address feedback

Author: Jack Chen

CHANGELOG.md

@@ -1,6 +1,10 @@
 # CHANGELOG
 
-## v7.3.0 (2024-07-15)
+## Next Release
+
+- Add new `Claim` service for filing claims on EasyPost shipments and insurances
+
+## v7.3.0 (2024-07-16)
 
 - Adds new `shipment.recommendShipDate`, `smartrate.recommendShipDate`, and `smartrate.estimateDeliveryDate` functions
 - Routes `UpsAccount`, `UpsMailInnovationsAccount`, and `UpsSurepostAccount` create/update requests to the new `/ups_oauth_registrations` endpoint

examples

@@ -3,6 +3,7 @@
 import com.easypost.http.HashMapSerializer;
 import com.easypost.model.AddressVerification;
 import com.easypost.model.AddressVerificationDeserializer;
+import com.easypost.model.DateDeserializer;
 import com.easypost.model.Error;
 import com.easypost.model.ErrorDeserializer;
 import com.easypost.model.SmartrateCollection;
@@ -16,6 +17,7 @@
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
 
+import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
 
@@ -83,7 +85,8 @@ public abstract static class Http {
                 .registerTypeAdapter(Error.class, new ErrorDeserializer())
                 .registerTypeAdapter(AddressVerification.class, new AddressVerificationDeserializer())
                 .registerTypeAdapter(StatelessRate[].class, new StatelessRateDeserializer())
-                .registerTypeAdapter(Webhook[].class, new WebhookDeserializer()).create();
+                .registerTypeAdapter(Webhook[].class, new WebhookDeserializer())
+                .registerTypeAdapter(Date.class, new DateDeserializer()).create();
         public static final Gson PRETTY_PRINT_GSON = new GsonBuilder().setPrettyPrinting().serializeNulls()
                 .setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES).create();
     }

src/main/java/com/easypost/Constants.java

@@ -0,0 +1,26 @@
+package com.easypost.model;
+
+import java.util.Date;
+import java.util.List;
+import lombok.Getter;
+
+@Getter
+public class Claim extends EasyPostResource {
+    private Date statusTimestamp;
+    private List<ClaimHistoryEntry> history;
+    private String approvedAmount;
+    private String checkDeliveryAddress;
+    private String contactEmail;
+    private String description;
+    private String insuranceAmount;
+    private String insuranceId;
+    private String paymentMethod;
+    private String recipientName;
+    private String requestedAmount;
+    private String salvageValue;
+    private String shipmentId;
+    private String status;
+    private String statusDetail;
+    private String trackingCode;
+    private String type;
+}

src/main/java/com/easypost/model/Claim.java

@@ -0,0 +1,34 @@
+package com.easypost.model;
+
+import java.util.List;
+import java.util.Map;
+
+import com.easypost.exception.General.EndOfPaginationError;
+import lombok.Getter;
+import lombok.Setter;
+
+@Getter
+public final class ClaimCollection extends PaginatedCollection<Claim> {
+    private List<Claim> claims;
+
+    @Setter
+    private String type;
+    private String status;
+
+    @Override
+    protected Map<String, Object> buildNextPageParameters(List<Claim> claims, Integer pageSize)
+            throws EndOfPaginationError {
+        String lastId = claims.get(claims.size() - 1).getId();
+
+        Map<String, Object> parameters = new java.util.HashMap<>();
+        parameters.put("before_id", lastId);
+        parameters.put("type", type);
+        parameters.put("status", status);
+
+        if (pageSize != null) {
+            parameters.put("page_size", pageSize);
+        }
+
+        return parameters;
+    }
+}

src/main/java/com/easypost/model/ClaimCollection.java

@@ -0,0 +1,11 @@
+package com.easypost.model;
+
+import java.util.Date;
+import lombok.Getter;
+
+@Getter
+public class ClaimHistoryEntry {
+    private String status;
+    private String statusDetail;
+    private Date statusTimestamp;
+}

src/main/java/com/easypost/model/ClaimHistoryEntry.java

@@ -0,0 +1,78 @@
+package com.easypost.model;
+
+import com.google.gson.JsonDeserializationContext;
+import com.google.gson.JsonDeserializer;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonParseException;
+
+import java.lang.reflect.Type;
+import java.text.ParseException;
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import java.util.TimeZone;
+
+public class DateDeserializer implements JsonDeserializer<Date> {
+    private static final String[] DATE_FORMATS = new String[]{
+        // Basic formats
+        "yyyy-MM-dd",
+        "yyyy-MM-dd'T'HH:mm:ss",
+        "yyyy-MM-dd'T'HH:mm:ss'Z'",
+
+        // With milliseconds
+        "yyyy-MM-dd'T'HH:mm:ss.SSS",
+        "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
+
+        // With time zone offset
+        "yyyy-MM-dd'T'HH:mm:ssZ",
+        "yyyy-MM-dd'T'HH:mm:ssXXX",
+
+        // Alternative time formats
+        "yyyy-MM-dd HH:mm:ss",
+        "yyyy-MM-dd HH:mm:ss.SSS",
+
+        // Month and day only
+        "yyyy-MM-dd",
+        "MM/dd/yyyy",
+        "MM-dd-yyyy",
+
+        // Year and week
+        "yyyy-'W'ww",
+        "yyyy-'W'ww-u",
+
+        // Full date and time
+        "EEE, d MMM yyyy HH:mm:ss Z",
+        "EEE, d MMM yyyy HH:mm:ss z",
+        "EEEE, MMMM d, yyyy h:mm:ss a",
+
+        // Short formats
+        "M/d/yy",
+        "M-d-yy",
+        "M.d.yy",
+        "MM/dd/yyyy",
+        "MM-dd-yyyy"
+    };
+    
+    /**
+     * Deserialize the Date format from a JSON object.
+     *
+     * @param json    JSON object to deserialize.
+     * @param type    Type of the object to deserialize.
+     * @param context Deserialization context.
+     * @return Deserialized Date object.
+     * @throws JsonParseException if the JSON object is not a valid SmartrateCollection.
+     */
+    @Override
+    public Date deserialize(JsonElement json, Type type, JsonDeserializationContext context)
+        throws JsonParseException {
+        for (String format : DATE_FORMATS) {
+            try {
+                SimpleDateFormat sdf = new SimpleDateFormat(format);
+                sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
+                return sdf.parse(json.getAsString());
+            } catch (ParseException e) {
+                throw new JsonParseException("Unable to parse this date format");
+            }
+        }
+        throw new JsonParseException("Unparseable date: \"" + json.getAsString() + "\"");
+    }
+}

src/main/java/com/easypost/model/DateDeserializer.java

@@ -0,0 +1,116 @@
+package com.easypost.service;
+
+import java.util.Map;
+import java.util.function.Function;
+
+import com.easypost.exception.EasyPostException;
+import com.easypost.exception.General.EndOfPaginationError;
+import com.easypost.http.Requestor;
+import com.easypost.http.Requestor.RequestMethod;
+import com.easypost.model.Claim;
+import com.easypost.model.ClaimCollection;
+
+import lombok.SneakyThrows;
+
+public class ClaimService {
+    private final EasyPostClient client;
+
+    /**
+     * ClaimService constructor.
+     *
+     * @param client The client object.
+     */
+    ClaimService(EasyPostClient client) {
+        this.client = client;
+    }
+
+    /**
+     * Create a new claim object from a map of parameters.
+     *
+     * @param params Map of parameters.
+     * @return Claim object
+     * @throws EasyPostException when the request fails.
+     */
+    public Claim create(final Map<String, Object> params) throws EasyPostException {
+        String endpoint = "claims";
+
+        return Requestor.request(RequestMethod.POST, endpoint, params, Claim.class, client);
+    }
+
+    /**
+     * Retrieve an Claim from the API.
+     *
+     * @param id The ID of the Claim to retrieve.
+     * @return Claim object
+     * @throws EasyPostException when the request fails.
+     */
+    public Claim retrieve(final String id) throws EasyPostException {
+        String endpoint = "claims/" + id;
+
+        return Requestor.request(RequestMethod.GET, endpoint, null, Claim.class, client);
+    }
+
+    /**
+     * Get a list of Claims.
+     *
+     * @param params a map of parameters
+     * @return ClaimCollection object
+     * @throws EasyPostException when the request fails.
+     */
+    public ClaimCollection all(final Map<String, Object> params) throws EasyPostException {
+        String type = (String) params.get("type");
+        String status = (String) params.get("status");
+        params.remove(type);
+        params.remove(status);
+        String endpoint = "claims";
+
+        ClaimCollection claimCollection = 
+            Requestor.request(RequestMethod.GET, endpoint, params, ClaimCollection.class, client);
+        claimCollection.setType(type);
+        claimCollection.setType(status);
+
+        return claimCollection;
+    }
+
+    /**
+     * Cancel an Claim from the API.
+     *
+     * @param id The ID of the Claim to cancel.
+     * @return Claim object
+     * @throws EasyPostException when the request fails.
+     */
+    public Claim cancel(final String id) throws EasyPostException {
+        String endpoint = String.format("claims/%s/cancel", id);
+
+        return Requestor.request(RequestMethod.POST, endpoint, null, Claim.class, client);
+    }
+
+    /**
+     * Get the next page of an ClaimCollection.
+     *
+     * @param collection ClaimCollection to get next page of.
+     * @return ClaimCollection object.
+     * @throws EndOfPaginationError when there are no more pages to retrieve.
+     */
+    public ClaimCollection getNextPage(ClaimCollection collection) throws EndOfPaginationError {
+        return getNextPage(collection, null);
+    }
+
+    /**
+     * Get the next page of an ClaimCollection.
+     *
+     * @param collection ClaimCollection to get next page of.
+     * @param pageSize   The number of results to return on the next page.
+     * @return ClaimCollection object.
+     * @throws EndOfPaginationError when there are no more pages to retrieve.
+     */
+    public ClaimCollection getNextPage(
+            ClaimCollection collection, Integer pageSize) throws EndOfPaginationError {
+        return collection.getNextPage(new Function<Map<String, Object>, ClaimCollection>() {
+            @Override @SneakyThrows
+            public ClaimCollection apply(Map<String, Object> parameters) {
+                return all(parameters);
+            }
+        }, collection.getClaims(), pageSize);
+    }
+}

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

@@ -26,6 +26,7 @@ public class EasyPostClient {
     public final CarrierAccountService carrierAccount;
     public final CarrierMetadataService carrierMetadata;
     public final CarrierTypeService carrierType;
+    public final ClaimService claim;
     public final CustomsInfoService customsInfo;
     public final CustomsItemService customsItem;
     public final EndShipperService endShipper;
@@ -136,6 +137,7 @@ public EasyPostClient(String apiKey, int connectTimeoutMilliseconds, int readTim
         this.carrierAccount = new CarrierAccountService(this);
         this.carrierMetadata = new CarrierMetadataService(this);
         this.carrierType = new CarrierTypeService(this);
+        this.claim = new ClaimService(this);
         this.customsInfo = new CustomsInfoService(this);
         this.customsItem = new CustomsItemService(this);
         this.endShipper = new EndShipperService(this);