Merge pull request #364 from EasyPost/luma

feat: add luma functions

Author: Justintime50

CHANGELOG.md

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

examples

@@ -21,6 +21,7 @@
 use EasyPost\Service\EndShipperService;
 use EasyPost\Service\EventService;
 use EasyPost\Service\InsuranceService;
+use EasyPost\Service\LumaService;
 use EasyPost\Service\OrderService;
 use EasyPost\Service\ParcelService;
 use EasyPost\Service\PickupService;
@@ -54,6 +55,7 @@
  * @property EndShipperService $endShipper
  * @property EventService $event
  * @property InsuranceService $insurance
+ * @property LumaService $luma
  * @property OrderService $order
  * @property ParcelService $parcel
  * @property PickupService $pickup
@@ -127,6 +129,7 @@ public function __get(string $serviceName)
             'endShipper' => EndShipperService::class,
             'event' => EventService::class,
             'insurance' => InsuranceService::class,
+            'luma' => LumaService::class,
             'order' => OrderService::class,
             'parcel' => ParcelService::class,
             'pickup' => PickupService::class,

lib/EasyPost/EasyPostClient.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace EasyPost\Service;
+
+use EasyPost\Http\Requestor;
+use EasyPost\Util\InternalUtil;
+
+/**
+ * Luma service containing all the logic to make API calls.
+ */
+class LumaService extends BaseService
+{
+    /**
+     * Get service recommendations from Luma that meet the criteria of your ruleset.
+     *
+     * @param array<mixed> $params
+     * @return mixed
+     */
+    public function getPromise(array $params): mixed
+    {
+        if (!isset($params['shipment']) || !is_array($params['shipment'])) {
+            $clone = $params;
+            unset($params);
+            $params['shipment'] = $clone;
+        }
+
+        $url = '/luma/promise';
+        $response = Requestor::request($this->client, 'post', $url, $params);
+
+        return InternalUtil::convertToEasyPostObject($this->client, $response['luma_info']);
+    }
+}

lib/EasyPost/Service/LumaService.php

@@ -254,4 +254,39 @@ public function recommendShipDate(string $id, string $desiredDeliveryDate): mixe
 
         return InternalUtil::convertToEasyPostObject($this->client, $response['rates'] ?? []);
     }
+
+    /**
+     * Create and buy a Luma Shipment in one call.
+     *
+     * @param array<mixed> $params
+     * @return mixed
+     */
+    public function createAndBuyLuma(array $params): mixed
+    {
+        if (!isset($params['shipment']) || !is_array($params['shipment'])) {
+            $clone = $params;
+            unset($params);
+            $params['shipment'] = $clone;
+        }
+
+        $url = self::classUrl(self::serviceModelClassName(self::class)) . '/luma';
+        $response = Requestor::request($this->client, 'post', $url, $params);
+
+        return InternalUtil::convertToEasyPostObject($this->client, $response);
+    }
+
+    /**
+     * Buy a Shipment with Luma.
+     *
+     * @param string $id
+     * @param array<mixed> $params
+     * @return mixed
+     */
+    public function buyLuma(string $id, array $params): mixed
+    {
+        $url = $this->instanceUrl(self::serviceModelClassName(self::class), $id) . '/luma';
+        $response = Requestor::request($this->client, 'post', $url, $params);
+
+        return InternalUtil::convertToEasyPostObject($this->client, $response);
+    }
 }

lib/EasyPost/Service/ShipmentService.php

@@ -7,8 +7,9 @@
 use EasyPost\Exception\Api\ApiException;
 use EasyPost\Exception\General\EndOfPaginationException;
 use Exception;
+use PHPUnit\Framework\TestCase;
 
-class AddressTest extends \PHPUnit\Framework\TestCase
+class AddressTest extends TestCase
 {
     private static EasyPostClient $client;
 

test/EasyPost/AddressTest.php

@@ -4,8 +4,9 @@
 
 use EasyPost\ApiKey;
 use EasyPost\EasyPostClient;
+use PHPUnit\Framework\TestCase;
 
-class ApiKeyTest extends \PHPUnit\Framework\TestCase
+class ApiKeyTest extends TestCase
 {
     private static EasyPostClient $client;
 

test/EasyPost/ApiKeyTest.php

@@ -4,8 +4,9 @@
 
 use EasyPost\Batch;
 use EasyPost\EasyPostClient;
+use PHPUnit\Framework\TestCase;
 
-class BatchTest extends \PHPUnit\Framework\TestCase
+class BatchTest extends TestCase
 {
     private static EasyPostClient $client;
 

test/EasyPost/BatchTest.php

@@ -6,8 +6,9 @@
 use EasyPost\Exception\General\EasyPostException;
 use EasyPost\Rate;
 use EasyPost\Util\Util;
+use PHPUnit\Framework\TestCase;
 
-class BetaRateTest extends \PHPUnit\Framework\TestCase
+class BetaRateTest extends TestCase
 {
     private static EasyPostClient $client;
 

test/EasyPost/BetaRateTest.php

@@ -4,8 +4,9 @@
 
 use EasyPost\EasyPostClient;
 use EasyPost\Exception\Api\ApiException;
+use PHPUnit\Framework\TestCase;
 
-class BetaReferralCustomerTest extends \PHPUnit\Framework\TestCase
+class BetaReferralCustomerTest extends TestCase
 {
     private static EasyPostClient $client;