Update CarrierService update and create method to account UPS endpoints (#341)

Author: Jack Chen

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## Next Release
+
+- 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
+
 ## v7.2.0 (2024-04-10)
 
 - Fix payment method funding and deletion failures due to undetermined payment method type

Makefile

@@ -23,8 +23,13 @@ docs:
 	curl -LJs https://github.com/phpDocumentor/phpDocumentor/releases/download/v3.3.1/phpDocumentor.phar -o phpDocumentor.phar
 	php phpDocumentor.phar -d lib -t docs
 
+## init-examples-submodule - Initialize the examples submodule
+init-examples-submodule:
+	git submodule init
+	git submodule update
+
 ## install - Install dependencies
-install: | update-examples-submodule
+install: | init-examples-submodule
 	composer install --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
 
 ## lint - Lint the project

lib/EasyPost/Constant/Constants.php

@@ -17,10 +17,15 @@ abstract class Constants
     // Validation
     const CARRIER_ACCOUNT_TYPES_WITH_CUSTOM_WORKFLOWS = [
         'FedexAccount',
-        'UpsAccount',
         'FedexSmartpostAccount'
     ];
 
+    const UPS_OAUTH_ACCOUNT_TYPES = [
+        'UpsAccount',
+        'UpsMailInnovationsAccount',
+        'UpsSurepostAccount'
+    ];
+
     // Exception messages (many of these are intended to be used with `sprintf()`)
     const ARRAY_REQUIRED_ERROR = 'You must pass an array as the first argument to EasyPost API method calls.';
     const COMMUNICATION_ERROR = 'Unexpected error communicating with %s. If this problem persists please let us know at ' . self::SUPPORT_EMAIL . '. %s'; // phpcs:ignore

lib/EasyPost/Service/CarrierAccountService.php

@@ -43,7 +43,16 @@ public function all(mixed $params = null): mixed
      */
     public function update(string $id, mixed $params): mixed
     {
-        return self::updateResource(self::serviceModelClassName(self::class), $id, $params);
+        $carrierAccount = self::retrieve($id);
+        $carrierAccountType = $carrierAccount['type'];
+        if (in_array($carrierAccountType, Constants::UPS_OAUTH_ACCOUNT_TYPES, true)) {
+            $className = 'UpsOauthRegistration';
+            $params = [self::selectTopLayerKey($carrierAccountType) => $params];
+        } else {
+            $className = 'CarrierAccount';
+            $params = [self::selectTopLayerKey($carrierAccountType) => $params];
+        }
+        return self::updateResource($className, $id, $params);
     }
 
     /**
@@ -67,17 +76,13 @@ public function delete(string $id, mixed $params = null): void
      */
     public function create(mixed $params = null): mixed
     {
-        if (!isset($params['carrier_account']) || !is_array($params['carrier_account'])) {
-            $clone = $params;
-            unset($params);
-            $params['carrier_account'] = $clone;
-        }
-
-        if (!isset($params['carrier_account']['type'])) {
+        if (!isset($params['type'])) {
             throw new MissingParameterException(sprintf(Constants::MISSING_PARAMETER_ERROR, 'type'));
         }
 
-        $url = self::selectCarrierAccountCreationEndpoint($params['carrier_account']['type']);
+        $carrierAccountType = $params['type'];
+        $params = [self::selectTopLayerKey($carrierAccountType) => $params];
+        $url = self::selectCarrierAccountCreationEndpoint($carrierAccountType);
         $response = Requestor::request($this->client, 'post', $url, $params);
 
         return InternalUtil::convertToEasyPostObject($this->client, $response);
@@ -106,8 +111,23 @@ private function selectCarrierAccountCreationEndpoint(string $carrierAccountType
     {
         if (in_array($carrierAccountType, Constants::CARRIER_ACCOUNT_TYPES_WITH_CUSTOM_WORKFLOWS, true)) {
             return '/carrier_accounts/register';
+        } else if (in_array($carrierAccountType, Constants::UPS_OAUTH_ACCOUNT_TYPES, true)) {
+            return '/ups_oauth_registrations';
         }
 
         return '/carrier_accounts';
     }
+
+    /**
+     * Select the top-key layer for creating/updating a carrier account based on the type of carrier account.
+     *
+     * @param string $carrierAccountType The type of carrier account to create.
+     * @return string The top-layer key for creating/updating a carrier account.
+     */
+    private function selectTopLayerKey(string $carrierAccountType): string
+    {
+        return in_array($carrierAccountType, Constants::UPS_OAUTH_ACCOUNT_TYPES, true)
+            ? 'ups_oauth_registrations'
+            : 'carrier_account';
+    }
 }

test/EasyPost/CarrierAccountTest.php

@@ -47,6 +47,28 @@ public function testCreate(): void
         self::$client->carrierAccount->delete($carrierAccount->id);
     }
 
+    /**
+     * Test creating an UPS account.
+     */
+    public function testCreateUps(): void
+    {
+        TestUtil::setupCassette('carrier_accounts/create_ups.yml');
+
+        self::$client = new EasyPostClient(getenv('EASYPOST_PROD_API_KEY'));
+
+        $upsAccount = self::$client->carrierAccount->create([
+            'type' => 'UpsAccount',
+            'account_number' => '123456789'
+        ]);
+
+        $this->assertEquals('UpsAccount', $upsAccount->type);
+        $this->assertInstanceOf(CarrierAccount::class, $upsAccount);
+        $this->assertStringMatchesFormat('ca_%s', $upsAccount->id);
+
+        // Delete the carrier account once it's done being tested.
+        self::$client->carrierAccount->delete($upsAccount->id);
+    }
+
     /**
      * Test creating a carrier account.
      */
@@ -138,6 +160,30 @@ public function testAll(): void
         $this->assertContainsOnlyInstancesOf(CarrierAccount::class, $carrierAccounts);
     }
 
+    /**
+     * Test updating an UPS account.
+     */
+    public function testUpdateUps(): void
+    {
+        TestUtil::setupCassette('carrier_accounts/update_ups.yml');
+
+        self::$client = new EasyPostClient(getenv('EASYPOST_PROD_API_KEY'));
+
+        $upsAccount = self::$client->carrierAccount->create([
+            'type' => 'UpsAccount',
+            'account_number' => '123456789'
+        ]);
+
+        $updatedUpsAccount = self::$client->carrierAccount->update($upsAccount->id, ['account_number' => '987654321']);
+
+        $this->assertInstanceOf(CarrierAccount::class, $updatedUpsAccount);
+        $this->assertStringMatchesFormat('ca_%s', $updatedUpsAccount->id);
+        $this->assertEquals('UpsAccount', $updatedUpsAccount->type);
+
+        // Delete the carrier account once it's done being tested.
+        self::$client->carrierAccount->delete($updatedUpsAccount->id);
+    }
+
     /**
      * Test updating a carrier account.
      */