feat: qqq-qbit-carrier-fedex -- FedEx REST API integration

[KofTwentyTwo]

Summary

FedEx carrier implementation for the carrier QBit hierarchy. Implements CarrierServiceProvider with OAuth2 auth and FedEx REST API calls.

Parent: #389

Scope

FedExCarrierServiceProvider

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

FedExOAuth2TokenManager

• POST /oauth/token with client_credentials grant
• Thread-safe token cache with TTL-based refresh
• Credentials from env vars: FEDEX_API_URL, FEDEX_CLIENT_ID, FEDEX_CLIENT_SECRET

Method Implementations

Interface Method	FedEx Endpoint	Notes
validateAddress()	POST /address/v1/addresses/resolve	Batch-capable (up to 100)
generateLabel()	POST /ship/v1/shipments	Returns ZPL/PDF/PNG label + tracking
voidLabel()	PUT /ship/v1/shipments/cancel	Cancel by tracking number
trackPackage()	POST /track/v1/trackingnumbers	Batch-capable (up to 30), normalize to TrackingStatus enum
getRates()	POST /rate/v1/rates/quotes	Multi-service rate comparison
generateReturnLabel()	POST /ship/v1/shipments/tag	FedEx "return tag"
getTransitTime()	POST /availability/v1/transittimes	Estimated delivery date by service
getAvailableServices()	POST /availability/v1/packageandserviceoptions	Services + packaging for origin-dest

Service Types

Code	Use Case	Packaging	Special Config
SMART_POST	SmartPost (FedEx to USPS last mile)	YOUR_PACKAGING	smartPostInfoDetail.hubId + indicia: PARCEL_SELECT
FEDEX_2_DAY	OneRate 2-Day	FEDEX_PAK or FEDEX_LARGE_BOX	specialServiceTypes: FEDEX_ONE_RATE
FEDEX_EXPRESS_SAVER	OneRate 3-Day	Same	Same

Barcode Extraction

• SmartPost: trackingIdType === 'USPS' -- 22-digit USPS tracking, 8-digit barcode prefix
• FedEx Express: trackingIdType === 'FEDEX' -- 12-digit FedEx tracking, no prefix

QBit Integration

• FedExQBitConfig with env var configuration
• FedExQBitProducer registers provider with CarrierServiceRegistry
• Account-specific values (account number, hub IDs) passed per-request via CarrierShipperInfo

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

• OAuth2 token management with thread-safe caching
• Address validation with FedEx API
• Label generation for SmartPost, 2-Day, Express Saver
• 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