feat: portal and embeddable sessions

CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## Next Release
+
+- Adds the following functions:
+  - `embeddable.createSession`
+  - `customerPortal.createAccountLink`
+
 ## v8.3.0 (2025-11-10)
 
 - Adds support for `UspsShipAccount`

lib/EasyPost/EasyPostClient.php

@@ -16,8 +16,10 @@
 use EasyPost\Service\CarrierAccountService;
 use EasyPost\Service\CarrierMetadataService;
 use EasyPost\Service\ClaimService;
+use EasyPost\Service\CustomerPortalService;
 use EasyPost\Service\CustomsInfoService;
 use EasyPost\Service\CustomsItemService;
+use EasyPost\Service\EmbeddableService;
 use EasyPost\Service\EndShipperService;
 use EasyPost\Service\EventService;
 use EasyPost\Service\InsuranceService;
@@ -50,8 +52,10 @@
  * @property CarrierAccountService $carrierAccount
  * @property CarrierMetadataService $carrierMetadata
  * @property ClaimService $claim
+ * @property CustomerPortalService $customerPortal
  * @property CustomsInfoService $customsInfo
  * @property CustomsItemService $customsItem
+ * @property EmbeddableService $embeddable
  * @property EndShipperService $endShipper
  * @property EventService $event
  * @property InsuranceService $insurance
@@ -124,8 +128,10 @@ public function __get(string $serviceName)
             'carrierAccount' => CarrierAccountService::class,
             'carrierMetadata' => CarrierMetadataService::class,
             'claim' => ClaimService::class,
+            'customerPortal' => CustomerPortalService::class,
             'customsInfo' => CustomsInfoService::class,
             'customsItem' => CustomsItemService::class,
+            'embeddable' => EmbeddableService::class,
             'endShipper' => EndShipperService::class,
             'event' => EventService::class,
             'insurance' => InsuranceService::class,

lib/EasyPost/Service/CustomerPortalService.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace EasyPost\Service;
+
+use EasyPost\Http\Requestor;
+use EasyPost\Util\InternalUtil;
+
+/**
+ * CustomerPortal service containing all the logic to make API calls.
+ */
+class CustomerPortalService extends BaseService
+{
+    /**
+     * Create a Portal Session.
+     *
+     * @param mixed $params
+     * @return mixed
+     */
+    public function createAccountLink(mixed $params = null): mixed
+    {
+        $response = Requestor::request($this->client, 'post', '/customer_portal/account_link', $params);
+
+        return InternalUtil::convertToEasyPostObject($this->client, $response);
+    }
+}

lib/EasyPost/Service/EmbeddableService.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace EasyPost\Service;
+
+use EasyPost\Http\Requestor;
+use EasyPost\Util\InternalUtil;
+
+/**
+ * Embeddable service containing all the logic to make API calls.
+ */
+class EmbeddableService extends BaseService
+{
+    /**
+     * Create an Embeddable Session.
+     *
+     * @param mixed $params
+     * @return mixed
+     */
+    public function createSession(mixed $params = null): mixed
+    {
+        $response = Requestor::request($this->client, 'post', '/embeddables/session', $params);
+
+        return InternalUtil::convertToEasyPostObject($this->client, $response);
+    }
+}

lib/EasyPost/Util/InternalUtil.php

@@ -181,15 +181,15 @@ public static function convertToEasyPostObject(EasyPostClient|null $client, mixe
      * @param array<string> $carriers
      * @param array<string> $services
      * @param string|null $ratesKey
-     * @return Rate|PickupRate
+     * @return object
      * @throws EasyPostException
      */
     public static function getLowestObjectRate(
         ?EasyPostObject $easypostObject,
         ?array $carriers = [],
         ?array $services = [],
         ?string $ratesKey = 'rates'
-    ): Rate|PickupRate {
+    ): object {
         $lowestRate = false;
         $carriersInclude = [];
         $carriersExclude = [];
@@ -235,8 +235,11 @@ public static function getLowestObjectRate(
                 continue;
             }
 
-            if (!$lowestRate || floatval($easypostObject->$ratesKey[$i]->rate) < floatval($lowestRate->rate)) {
-                $lowestRate = clone ($easypostObject->$ratesKey[$i]);
+            if (
+                !$lowestRate ||
+                floatval($easypostObject->$ratesKey[$i]->rate) < floatval($lowestRate->rate) // @phpstan-ignore-line
+            ) {
+                $lowestRate = clone($easypostObject->$ratesKey[$i]);
             }
         }
 

lib/easypost.php

@@ -98,8 +98,10 @@
 require_once(dirname(__FILE__) . '/EasyPost/Service/BillingService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/CarrierAccountService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/ClaimService.php');
+require_once(dirname(__FILE__) . '/EasyPost/Service/CustomerPortalService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/CustomsInfoService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/CustomsItemService.php');
+require_once(dirname(__FILE__) . '/EasyPost/Service/EmbeddableService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/EndShipperService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/EventService.php');
 require_once(dirname(__FILE__) . '/EasyPost/Service/InsuranceService.php');

test/EasyPost/CustomerPortalTest.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace EasyPost\Test;
+
+use EasyPost\EasyPostClient;
+use PHPUnit\Framework\TestCase;
+
+class CustomerPortalTest extends TestCase
+{
+    private static EasyPostClient $client;
+
+    /**
+     * Setup the testing environment for this file.
+     */
+    public static function setUpBeforeClass(): void
+    {
+        TestUtil::setupVcrTests();
+        self::$client = new EasyPostClient((string)getenv('EASYPOST_PROD_API_KEY'));
+    }
+
+    /**
+     * Cleanup the testing environment once finished.
+     */
+    public static function tearDownAfterClass(): void
+    {
+        TestUtil::teardownVcrTests();
+    }
+
+    /**
+     * Test creating an account link
+     */
+    public function testCreateAccountLink(): void
+    {
+        TestUtil::setupCassette('customer_portal/createAccountLink.yml');
+
+        $user = self::$client->user->allChildren()['children'][0];
+
+        $accountLink = self::$client->customerPortal->createAccountLink(
+            [
+                'session_type' => 'account_onboarding',
+                'user_id' => $user->id,
+                'refresh_url' => 'https://example.com/refresh',
+                'return_url' => 'https://example.com/return',
+            ]
+        );
+
+        $this->assertEquals('CustomerPortalAccountLink', $accountLink->object);
+    }
+}

test/EasyPost/EmbeddableTest.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace EasyPost\Test;
+
+use EasyPost\EasyPostClient;
+use PHPUnit\Framework\TestCase;
+
+class EmbeddableTest extends TestCase
+{
+    private static EasyPostClient $client;
+
+    /**
+     * Setup the testing environment for this file.
+     */
+    public static function setUpBeforeClass(): void
+    {
+        TestUtil::setupVcrTests();
+        self::$client = new EasyPostClient((string)getenv('EASYPOST_PROD_API_KEY'));
+    }
+
+    /**
+     * Cleanup the testing environment once finished.
+     */
+    public static function tearDownAfterClass(): void
+    {
+        TestUtil::teardownVcrTests();
+    }
+
+    /**
+     * Test creating an account link
+     */
+    public function testCreateSession(): void
+    {
+        TestUtil::setupCassette('embeddables/createSession.yml');
+
+        $user = self::$client->user->allChildren()['children'][0];
+
+        $accountLink = self::$client->embeddable->createSession(
+            [
+                'origin_host' => 'https://example.com',
+                'user_id' => $user->id,
+            ]
+        );
+
+        $this->assertEquals('EmbeddablesSession', $accountLink->object);
+    }
+}

test/EasyPost/Fixture.php

@@ -296,4 +296,12 @@ public static function lumaPlannedShipDate(): string
     {
         return '2025-06-12';
     }
+
+    /**
+     * @return array<mixed>
+     */
+    public static function referralUser(): array
+    {
+        return self::readFixtureData()['users']['referral'];
+    }
 }

test/EasyPost/ReferralCustomerTest.php

@@ -43,9 +43,9 @@ public function testCreate(): void
         TestUtil::setupCassette('referral_customers/create.yml');
 
         $referral = self::$client->referralCustomer->create([
-            'name' => 'Test Referral',
-            'email' => 'test@test.com',
-            'phone' => '8888888888'
+            'name' => Fixture::referralUser()['name'],
+            'email' => Fixture::referralUser()['email'],
+            'phone' => Fixture::referralUser()['phone'],
         ]);
 
         $this->assertInstanceOf(User::class, $referral);

test/EasyPost/ScanFormTest.php

@@ -34,7 +34,7 @@ public static function tearDownAfterClass(): void
      */
     public function testCreate(): void
     {
-        TestUtil::setupCassette('scanForms/create.yml');
+        TestUtil::setupCassette('scan_forms/create.yml');
 
         $shipment = self::$client->shipment->create(Fixture::oneCallBuyShipment());
 
@@ -51,7 +51,7 @@ public function testCreate(): void
      */
     public function testRetrieve(): void
     {
-        TestUtil::setupCassette('scanForms/retrieve.yml');
+        TestUtil::setupCassette('scan_forms/retrieve.yml');
 
         $shipment = self::$client->shipment->create(Fixture::oneCallBuyShipment());
 
@@ -70,7 +70,7 @@ public function testRetrieve(): void
      */
     public function testAll(): void
     {
-        TestUtil::setupCassette('scanForms/all.yml');
+        TestUtil::setupCassette('scan_forms/all.yml');
 
         $scanForms = self::$client->scanForm->all([
             'page_size' => Fixture::pageSize(),
@@ -88,7 +88,7 @@ public function testAll(): void
      */
     public function testGetNextPage(): void
     {
-        TestUtil::setupCassette('scanForms/getNextPage.yml');
+        TestUtil::setupCassette('scan_forms/getNextPage.yml');
 
         try {
             $scanforms = self::$client->scanForm->all([