feat: qqq-qbit-carrier-usps -- USPS REST API integration

[KofTwentyTwo]

Summary

USPS carrier implementation for the carrier QBit hierarchy. Implements CarrierServiceProvider with two-token OAuth2 auth and USPS REST API calls.

Parent: #389

Scope

UspsCarrierServiceProvider

Implements all CarrierServiceProvider methods with getCarrierName() returning "usps". Registers itself with CarrierServiceRegistry during UspsQBitProducer.produce().

UspsOAuth2TokenManager (Two-Token System)

1. Access Token: POST /oauth2/v3/token with client_credentials
2. Payment Token: POST /payments/v3/payment-authorization (requires CRID/MID/permit)
   • Sent as X-Payment-Authorization-Token header on label requests

Both tokens cached with TTL-based refresh. OAuth creds from env vars: USPS_API_URL, USPS_CONSUMER_KEY, USPS_CONSUMER_SECRET. Account details (CRID, MID, permit) passed per-request via CarrierShipperInfo.

Method Implementations

Interface Method	USPS Endpoint	Notes
validateAddress()	GET /addresses/v3/address	Single address, returns ZIP+4
generateLabel()	POST /labels/v3/label	Multipart MIME response (JSON + base64 ZPL)
voidLabel()	DELETE /labels/v3/label/{trackingNumber}	Cancel by tracking number
trackPackage()	GET /tracking/v3/tracking/{trackingNumber}	Single tracking, normalize to TrackingStatus enum
getRates()	POST /prices/v3/base-rates/search	Per-mailclass pricing
generateReturnLabel()	POST /labels/v3/return-label	Domestic return label
getTransitTime()	GET /service-standards/v3/standards	Delivery standards by mail class
getAvailableServices()	Shipping Options API	Available services for origin-dest

Packaging Logic

double volume = length * width * height;
if (volume > 864) // > 864 cubic inches (144 * 12 * 0.5)
   packagingType = "VARIABLE";
else
   packagingType = "CUBIC_PARCELS";

QBit Integration

• UspsQBitConfig with env var configuration
• UspsQBitProducer registers provider with CarrierServiceRegistry
• Account-specific values (CRID, MID, manifest MID, permit number/zip) passed per-request

Dependencies

• qqq-qbit-carrier-api (feat: carrier service QBit hierarchy (qqq-qbits-carrier) #389)
• qqq-backend-core
• org.apache.httpcomponents.client5:httpclient5
• com.fasterxml.jackson.core:jackson-databind

Acceptance Criteria

• Two-token OAuth2 management (access + payment authorization)
• Address validation with USPS API
• Label generation with cubic/variable packaging logic
• Multipart MIME response parsing
• Label voiding/cancellation
• Package tracking with TrackingStatus normalization
• Rate quotes with normalized CarrierRateResult
• Return label generation
• Transit time estimation
• Available services lookup
• WireMock unit tests for all API interactions
• Integration test profile (-Pcarrier-integration) for sandbox testing