feat: adds luma functions

CHANGELOG.md

@@ -1,5 +1,12 @@
 # CHANGELOG
 
+## v8.2.0 (2025-06-18)
+
+- Adds the following functions
+  - `shipment.createAndBuyLuma`
+  - `shipment.buyLuma`
+  - `luma.getPromise`
+
 ## v8.1.0 (2025-05-29)
 
 - Adds `reference` to Claims

README.md

@@ -16,7 +16,7 @@ Add this to your project's POM:
 <dependency>
   <groupId>com.easypost</groupId>
   <artifactId>easypost-api-client</artifactId>
-  <version>8.1.0</version>
+  <version>8.2.0</version>
 </dependency>
 ```
 
@@ -25,7 +25,7 @@ Add this to your project's POM:
 Add this to your project's build file:
 
 ```groovy
-implementation "com.easypost:easypost-api-client:8.1.0"
+implementation "com.easypost:easypost-api-client:8.2.0"
 ```
 
 **NOTE:** [Google Gson](http://code.google.com/p/google-gson/) is required.

VERSION

@@ -1 +1 @@
-8.1.0
+8.2.0

pom.xml

@@ -6,7 +6,7 @@
     <groupId>com.easypost</groupId>
     <artifactId>easypost-api-client</artifactId>
 
-    <version>8.1.0</version>
+    <version>8.2.0</version>
     <packaging>jar</packaging>
 
     <name>com.easypost:easypost-api-client</name>

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

@@ -0,0 +1,14 @@
+package com.easypost.model;
+
+import lombok.Getter;
+
+@Getter
+public final class AiResults {
+    private String carrier;
+    private Boolean meetsRulesetRequirements;
+    private String predictedDeliverByDate;
+    private Integer predictedDeliverDays;
+    private String rateId;
+    private String rateUsd;
+    private String service;
+}

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

@@ -0,0 +1,12 @@
+package com.easypost.model;
+
+import java.util.List;
+import lombok.Getter;
+
+@Getter
+public final class LumaInfo {
+    private List<AiResults> aiResults;
+    private Integer matchingRuleIdx;
+    private String rulesetDescription;
+    private Rate lumaSelectedRate;
+}

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

@@ -0,0 +1,8 @@
+package com.easypost.model;
+
+import lombok.Getter;
+
+@Getter
+public class LumaPromiseResponse {
+    private LumaInfo lumaInfo;
+}

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

@@ -32,6 +32,7 @@ public class EasyPostClient {
     public final EndShipperService endShipper;
     public final EventService event;
     public final InsuranceService insurance;
+    public final LumaService luma;
     public final OrderService order;
     public final ParcelService parcel;
     public final PaymentMethodService paymentMethod;
@@ -143,6 +144,7 @@ public EasyPostClient(String apiKey, int connectTimeoutMilliseconds, int readTim
         this.endShipper = new EndShipperService(this);
         this.event = new EventService(this);
         this.insurance = new InsuranceService(this);
+        this.luma = new LumaService(this);
         this.order = new OrderService(this);
         this.parcel = new ParcelService(this);
         this.paymentMethod = new PaymentMethodService(this);

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

@@ -0,0 +1,41 @@
+package com.easypost.service;
+
+import com.easypost.exception.EasyPostException;
+import com.easypost.http.Requestor;
+import com.easypost.http.Requestor.RequestMethod;
+import com.easypost.model.LumaPromiseResponse;
+import com.easypost.model.LumaInfo;
+
+import java.util.HashMap;
+import java.util.Map;
+
+public class LumaService {
+    private final EasyPostClient client;
+
+    /**
+     * LumaService constructor.
+     *
+     * @param client The client object.
+     */
+    LumaService(EasyPostClient client) {
+        this.client = client;
+    }
+
+    /**
+     * Get service recommendations from Luma that meet the criteria of your ruleset.
+     *
+     * @param params The map of parameters.
+     * @return LumaInfo object.
+     * @throws EasyPostException When the request fails.
+     */
+    public LumaInfo getPromise(final Map<String, Object> params)
+            throws EasyPostException {
+        Map<String, Object> wrappedParams = new HashMap<>();
+        wrappedParams.put("shipment", params);
+        String endpoint = "luma/promise";
+
+        LumaPromiseResponse response = Requestor.request(RequestMethod.POST, endpoint, wrappedParams,
+                LumaPromiseResponse.class, client);
+        return response.getLumaInfo();
+    }
+}

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

@@ -375,7 +375,7 @@ public Shipment generateForm(final String id, final String formType, final Map<S
      * 
      * @param id              The id of the shipment.
      * @param plannedShipDate The planned shipment date.
-     * @return EstimatedDeliveryDate object.
+     * @return List of EstimatedDeliveryDate objects.
      * @throws EasyPostException When the request fails.
      */
     public List<EstimatedDeliveryDate> retrieveEstimatedDeliveryDate(final String id, final String plannedShipDate)
@@ -396,7 +396,7 @@ public List<EstimatedDeliveryDate> retrieveEstimatedDeliveryDate(final String id
      *
      * @param id                  The id of the shipment.
      * @param desiredDeliveryDate The desired delivery date.
-     * @return EstimatedDeliveryDate object.
+     * @return List of RecommendShipDateForShipmentResult objects.
      * @throws EasyPostException When the request fails.
      */
     public List<RecommendShipDateForShipmentResult> recommendShipDate(final String id, final String desiredDeliveryDate)
@@ -409,4 +409,39 @@ public List<RecommendShipDateForShipmentResult> recommendShipDate(final String i
                 RecommendShipDateResponse.class, client);
         return response.getRates();
     }
+
+    /**
+     * Create and buy a Luma Shipment in one call.
+     *
+     * @param params The map of parameters.
+     * @return Shipment object.
+     * @throws EasyPostException When the request fails.
+     */
+    public Shipment createAndBuyLuma(final Map<String, Object> params)
+            throws EasyPostException {
+        Map<String, Object> wrappedParams = new HashMap<>();
+        wrappedParams.put("shipment", params);
+        String endpoint = "shipments/luma";
+
+        Shipment response = Requestor.request(RequestMethod.POST, endpoint, wrappedParams,
+                Shipment.class, client);
+        return response;
+    }
+
+    /**
+     * Buy a Shipment with Luma.
+     *
+     * @param id     The ID of shipment.
+     * @param params The map of parameters.
+     * @return Shipment object.
+     * @throws EasyPostException When the request fails.
+     */
+    public Shipment buyLuma(final String id, final Map<String, Object> params)
+            throws EasyPostException {
+        String endpoint = "shipments/" + id + "/luma";
+
+        Shipment response = Requestor.request(RequestMethod.POST, endpoint, params,
+                Shipment.class, client);
+        return response;
+    }
 }