Add new smartrate endpoints functions

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Next Release
 
+- 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
   - Starting `2024-08-05`, UPS accounts will require a new payload to register or update. See [UPS OAuth 2.0 Update](https://support.easypost.com/hc/en-us/articles/26635027512717-UPS-OAuth-2-0-Update?utm_medium=email&_hsenc=p2ANqtz-96MmFtWICOzy9sKRbbcZSiMovZSrY3MSX1_bgY9N3f9yLVfWQdLhjAGq-SmNcOnDIS6GYhZ0OApjDBrGkKyLLMx1z6_TFOVp6-wllhEFQINrkuRuc&_hsmi=313130292&utm_content=313130292&utm_source=hs_email) for more details
 

lib/EasyPost/EasyPostClient.php

@@ -29,6 +29,7 @@
 use EasyPost\Service\ReportService;
 use EasyPost\Service\ScanFormService;
 use EasyPost\Service\ShipmentService;
+use EasyPost\Service\SmartRateService;
 use EasyPost\Service\TrackerService;
 use EasyPost\Service\UserService;
 use EasyPost\Service\WebhookService;
@@ -60,6 +61,7 @@
  * @property ReportService $report
  * @property ScanFormService $scanForm
  * @property ShipmentService $shipment
+ * @property SmartRateService $smartRate
  * @property TrackerService $tracker
  * @property UserService $user
  * @property WebhookService $webhook
@@ -131,6 +133,7 @@ public function __get(string $serviceName)
             'report' => ReportService::class,
             'scanForm' => ScanFormService::class,
             'shipment' => ShipmentService::class,
+            'smartRate' => SmartRateService::class,
             'tracker' => TrackerService::class,
             'user' => UserService::class,
             'webhook' => WebhookService::class,

lib/EasyPost/Service/ShipmentService.php

@@ -234,4 +234,24 @@ public function retrieveEstimatedDeliveryDate(string $id, string $plannedShipDat
 
         return InternalUtil::convertToEasyPostObject($this->client, $response['rates'] ?? []);
     }
+
+    /**
+     * Retrieve a recommended ship date for an existing Shipment via the Precision Shipping API,
+     * based on a specific desired delivery date.
+     *
+     * @param string $id
+     * @param string $desiredDeliveryDate
+     * @return mixed
+     */
+    public function recommendShipDate(string $id, string $desiredDeliveryDate): mixed
+    {
+        $params = [
+            'desired_delivery_date' => $desiredDeliveryDate,
+        ];
+
+        $url = $this->instanceUrl(self::serviceModelClassName(self::class), $id) . '/smartrate/precision_shipping';
+        $response = Requestor::request($this->client, 'get', $url, $params);
+
+        return InternalUtil::convertToEasyPostObject($this->client, $response['rates'] ?? []);
+    }
 }

lib/EasyPost/Service/SmartRateService.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace EasyPost\Service;
+
+use EasyPost\Exception\General\EndOfPaginationException;
+use EasyPost\Http\Requestor;
+use EasyPost\Util\InternalUtil;
+
+/**
+ * SmartRate service containing all the details of SmartRate requests.
+ */
+class SmartRateService extends BaseService
+{
+    /**
+     * Retrieve a recommended ship date for each carrier-service level combination via the
+     * Smart Deliver On API, based on a specific delivery date and origin-destination postal code pair.
+     *
+     * @param mixed $params
+     * @return mixed
+     */
+    public function recommendShipDate(mixed $params = null): mixed
+    {
+        $response = Requestor::request($this->client, 'post', '/smartrate/deliver_on', $params);
+
+        return InternalUtil::convertToEasyPostObject($this->client, $response);
+    }
+
+    /**
+     * Retrieve the estimated delivery date of each carrier-service level combination via the
+     * Smart Deliver By API, based on a specific ship date and origin-destination postal code pair.
+     *
+     * @param mixed $params
+     * @return mixed
+     */
+    public function estimateDeliveryDate(mixed $params = null): mixed
+    {
+        $response = Requestor::request($this->client, 'post', '/smartrate/deliver_by', $params);
+
+        return InternalUtil::convertToEasyPostObject($this->client, $response);
+    }
+}

lib/easypost.php

@@ -110,6 +110,7 @@
 require_once(dirname(__FILE__) . '/EasyPost/Service/ReportService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/ScanFormService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/ShipmentService.php');
+require_once(dirname(__FILE__) . '/EasyPost/Service/SmartRateService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/TrackerService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/UserService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/WebhookService.php');

test/EasyPost/Fixture.php

@@ -231,6 +231,11 @@ public static function rmaFormOtions(): array
 
     public static function plannedShipDate(): string
     {
-        return '2023-11-24';
+        return '2024-07-16';
+    }
+
+    public static function desiredDeliveryDate(): string
+    {
+        return '2024-07-16';
     }
 }

test/EasyPost/ShipmentTest.php

@@ -516,4 +516,23 @@ public function testRetrieveEstimatedDeliveryDate(): void
             $this->assertNotNull($entry->easypost_time_in_transit_data);
         }
     }
+
+    /**
+     * Tests that we retrieve the recommend ship date of a Shipment.
+     */
+    public function testRetrieveRecommendDate(): void
+    {
+        TestUtil::setupCassette('shipments/recommendShipDate.yml');
+
+        $shipment = self::$client->shipment->create(Fixture::basicShipment());
+
+        $rates = self::$client->shipment->recommendShipDate(
+            $shipment->id,
+            Fixture::desiredDeliveryDate(),
+        );
+
+        foreach ($rates as $entry) {
+            $this->assertNotNull($entry->easypost_time_in_transit_data);
+        }
+    }
 }

test/EasyPost/SmartRateTest.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace EasyPost\Test;
+
+use EasyPost\EasyPostClient;
+use EasyPost\Exception\General\EndOfPaginationException;
+use Exception;
+
+class SmartRateTest extends \PHPUnit\Framework\TestCase
+{
+    private static EasyPostClient $client;
+
+    /**
+     * Setup the testing environment for this file.
+     */
+    public static function setUpBeforeClass(): void
+    {
+        TestUtil::setupVcrTests();
+        self::$client = new EasyPostClient(getenv('EASYPOST_TEST_API_KEY'));
+    }
+
+    /**
+     * Cleanup the testing environment once finished.
+     */
+    public static function tearDownAfterClass(): void
+    {
+        TestUtil::teardownVcrTests();
+    }
+
+    /**
+     * Test that we retrieve SmartRates when provided a from/to zip and planned ship date.
+     */
+    public function testRetrieveRecommendDate(): void
+    {
+        TestUtil::setupCassette('smartrate/recommendShipDate.yml');
+
+        $params = [
+            'from_zip' => Fixture::caAddress1()['zip'],
+            'to_zip' => Fixture::caAddress2()['zip'],
+            'desired_delivery_date' => Fixture::desiredDeliveryDate(),
+            'carriers' => [Fixture::usps()],
+        ];
+
+        $rates = self::$client->smartRate->recommendShipDate($params);
+
+        foreach ($rates['results'] as $entry) {
+            $this->assertTrue(
+                isset($entry['easypost_time_in_transit_data']),
+                'Assertion failed: easypost_time_in_transit_data is not set.'
+            );
+        }
+    }
+
+    /**
+     * Test that we retrieve SmartRates when provided a from/to zip and planned ship date.
+     */
+    public function testRetrieveEstimatedDeliveryDate(): void
+    {
+        TestUtil::setupCassette('smartrate/estimatedDeliveryDate.yml');
+
+        $params = [
+            'from_zip' => Fixture::caAddress1()['zip'],
+            'to_zip' => Fixture::caAddress2()['zip'],
+            'planned_ship_date' => Fixture::plannedShipDate(),
+            'carriers' => [Fixture::usps()],
+        ];
+
+        $rates = self::$client->smartRate->estimateDeliveryDate($params);
+
+        foreach ($rates['results'] as $entry) {
+            $this->assertTrue(
+                isset($entry['easypost_time_in_transit_data']),
+                'Assertion failed: easypost_time_in_transit_data is not set.'
+            );
+        }
+    }
+}