Magento USPS AC-15210:
Fix Broken Shipping After Web Tools Retirement

<!-- app/code/YourVendor/UspsV3Fix/etc/di.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

    <!-- Override the stock USPS carrier with v3-aware version -->
    <preference for="Magento\Usps\Model\Carrier"
                type="YourVendor\UspsV3Fix\Model\Carrier" />

    <!-- Inject cached token provider -->
    <type name="YourVendor\UspsV3Fix\Model\Carrier">
        <arguments>
            <argument name="tokenProvider"
                      xsi:type="object">YourVendor\UspsTokenCache\Model\TokenProvider</argument>
        </arguments>
    </type>
</config>

// app/code/YourVendor/UspsV3Fix/Model/Carrier.php
// Overrides Magento\Usps\Model\Carrier to handle v3 JSON responses

namespace YourVendor\UspsV3Fix\Model;

use Magento\Usps\Model\Carrier as MagentoUspsCarrier;

class Carrier extends MagentoUspsCarrier
{
    // Map v3 mailClass codes to human-readable names
    private const SERVICE_MAP = [
        'PRIORITY_MAIL'           => 'Priority Mail',
        'PRIORITY_MAIL_EXPRESS'   => 'Priority Mail Express',
        'FIRST_CLASS_MAIL'        => 'First-Class Mail',
        'USPS_GROUND_ADVANTAGE'   => 'USPS Ground Advantage',
        'PARCEL_SELECT'           => 'Parcel Select Ground',
        'MEDIA_MAIL'              => 'Media Mail',
        'LIBRARY_MAIL'            => 'Library Mail',
    ];

    public function __construct(
        // ... standard Magento DI args ...
        private \YourVendor\UspsTokenCache\Model\TokenProvider \$tokenProvider,
        // ... remaining args ...
    ) {
        parent::__construct(/* ... */);
    }

    /**
     * Override: parse v3 JSON rate response instead of XML
     */
    protected function _parseResponse(\$response): array
    {
        \$data = json_decode(\$response, true);
        if (!\$data || !isset(\$data['rateOptions'])) {
            return [];
        }

        \$rates = [];
        foreach (\$data['rateOptions'] as \$option) {
            \$code = \$option['mailClass'] ?? '';
            \$rates[] = [
                'service' => self::SERVICE_MAP[\$code] ?? \$code,
                'price'   => (float) (\$option['totalBasePrice'] ?? 0),
                'code'    => \$code,
            ];
        }
        return \$rates;
    }

    /**
     * Override: parse v3 JSON tracking response instead of XML
     */
    protected function _parseTrackingResponse(\$trackingValue, \$response)
    {
        \$data = json_decode(\$response, true);
        if (!\$data || isset(\$data['error'])) {
            return false;
        }

        \$result = \$this->_trackFactory->create();
        \$tracking = \$this->_trackStatusFactory->create();
        \$tracking->setCarrier('usps');
        \$tracking->setCarrierTitle('USPS');
        \$tracking->setTracking(\$trackingValue);

        // v3 nests tracking under 'trackingEvents' array
        \$events = \$data['trackingEvents'] ?? [];
        if (!empty(\$events)) {
            \$latest = \$events[0]; // Most recent first
            \$tracking->setStatus(\$latest['eventType'] ?? '');
        }

        \$result->append(\$tracking);
        return \$result;
    }
}

// app/code/YourVendor/RevAddressShipping/Model/Carrier/RevAddress.php
// Clean carrier module — no OAuth, no rate limits, no XML parsing

namespace YourVendor\RevAddressShipping\Model\Carrier;

use Magento\Quote\Model\Quote\Address\RateRequest;
use Magento\Shipping\Model\Carrier\AbstractCarrierOnline;
use Magento\Shipping\Model\Carrier\CarrierInterface;
use Magento\Framework\HTTP\ClientFactory;

class RevAddress extends AbstractCarrierOnline implements CarrierInterface
{
    protected \$_code = 'revaddress';
    private const API_BASE = 'https://api.revaddress.com/v1';

    public function collectRates(RateRequest \$request)
    {
        if (!\$this->getConfigFlag('active')) {
            return false;
        }

        \$apiKey = \$this->getConfigData('api_key');
        \$client = \$this->httpClientFactory->create();
        \$client->setHeaders([
            'Authorization' => 'Bearer ' . \$apiKey,
            'Content-Type'  => 'application/json',
        ]);

        \$client->post(self::API_BASE . '/rates', json_encode([
            'originZIPCode'      => \$request->getPostcode(),
            'destinationZIPCode' => \$request->getDestPostcode(),
            'weight'             => \$request->getPackageWeight(),
            'mailClass'          => 'ALL',
        ]));

        \$rates = json_decode(\$client->getBody(), true);
        \$result = \$this->_rateResultFactory->create();

        foreach (\$rates['rateOptions'] ?? [] as \$option) {
            \$method = \$this->_rateMethodFactory->create();
            \$method->setCarrier(\$this->_code);
            \$method->setCarrierTitle('USPS');
            \$method->setMethod(\$option['mailClass']);
            \$method->setMethodTitle(\$option['description']);
            \$method->setPrice(\$option['totalBasePrice']);
            \$method->setCost(\$option['totalBasePrice']);
            \$result->append(\$method);
        }

        return \$result;
    }

    public function getAllowedMethods(): array
    {
        return [
            'PRIORITY_MAIL'         => 'Priority Mail',
            'PRIORITY_MAIL_EXPRESS' => 'Priority Mail Express',
            'USPS_GROUND_ADVANTAGE' => 'USPS Ground Advantage',
            'FIRST_CLASS_MAIL'      => 'First-Class Mail',
        ];
    }
}

<!-- app/code/YourVendor/RevAddressShipping/etc/adminhtml/system.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
  <system>
    <section id="carriers">
      <group id="revaddress" translate="label" sortOrder="25" showInDefault="1">
        <label>RevAddress (USPS)</label>
        <field id="active" translate="label" type="select" sortOrder="10"
               showInDefault="1" showInWebsite="1">
          <label>Enabled</label>
          <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
        </field>
        <field id="api_key" translate="label" type="obscure" sortOrder="20"
               showInDefault="1" showInWebsite="1">
          <label>RevAddress API Key</label>
          <backend_model>Magento\Config\Model\Config\Backend\Encrypted</backend_model>
        </field>
        <field id="title" translate="label" type="text" sortOrder="30"
               showInDefault="1" showInWebsite="1">
          <label>Title</label>
        </field>
      </group>
    </section>
  </system>
</config>

// Magento store: 100 orders/day
// Each customer journey triggers multiple USPS API calls:

Cart page:        rate check    ×1     // estimate shipping
Checkout step 1:  address validate ×1  // verify address
Checkout step 2:  rate check    ×1     // final rate with exact address
Order placed:     label create  ×1     // generate shipping label
Post-purchase:    tracking poll ×3     // status updates over 3 days
─────────────────────────────────────────────────
Total per order:                 7 API calls

100 orders/day × 7 calls = 700 calls/day
USPS limit: 60/hr × 24hr  = 1,440 calls/day  ← looks fine daily

But peak hour (2-5 PM): 40 orders × 4 calls = 160 calls
USPS limit per hour:                           60 calls
Result: 429 errors starting at order #15

// Plus: AC-15210 requests a NEW OAuth token per request
// That doubles your call count. 160 → 320 calls/hr.

// app/code/YourVendor/UspsTokenCache/Model/TokenProvider.php

namespace YourVendor\UspsTokenCache\Model;

use Magento\Framework\Cache\FrontendInterface;
use Magento\Framework\HTTP\ClientFactory;
use Magento\Framework\App\Config\ScopeConfigInterface;

class TokenProvider
{
    private const CACHE_KEY = 'usps_oauth_v3_token';
    private const TOKEN_URL = 'https://apis.usps.com/oauth2/v3/token';
    private const REFRESH_BUFFER = 1800; // 30 min before expiry

    public function __construct(
        private FrontendInterface \$cache,
        private ClientFactory \$httpClientFactory,
        private ScopeConfigInterface \$scopeConfig,
    ) {}

    public function getToken(): string
    {
        \$cached = \$this->cache->load(self::CACHE_KEY);
        if (\$cached) {
            return \$cached; // Cache hit — no HTTP call
        }

        return \$this->refreshToken();
    }

    private function refreshToken(): string
    {
        \$clientId = \$this->scopeConfig->getValue('carriers/usps/client_id');
        \$clientSecret = \$this->scopeConfig->getValue('carriers/usps/client_secret');

        \$client = \$this->httpClientFactory->create();
        \$client->setHeaders(['Content-Type' => 'application/x-www-form-urlencoded']);
        \$client->post(self::TOKEN_URL, [
            'grant_type'    => 'client_credentials',
            'client_id'     => \$clientId,
            'client_secret' => \$clientSecret,
        ]);

        \$data = json_decode(\$client->getBody(), true);
        \$token = \$data['access_token'];
        \$ttl = (\$data['expires_in'] ?? 28800) - self::REFRESH_BUFFER;

        // Cache for (expires_in - 30 min) = ~7.5 hours
        \$this->cache->save(\$token, self::CACHE_KEY, [], \$ttl);

        return \$token;
    }
}