feat(fedex): add FedEx Multi-Factor Authentication endpoints

[lanej]

Summary

Adds native support for FedEx 2FA registration endpoints, eliminating the need for customers to use curl commands. This implementation enables automated FedEx registration workflows through the Java client library.

Changes

• Add FedexRegistrationService with 4 endpoint methods (register address, request PIN, validate PIN, submit invoice)
• Add FedexRegistration model class for API responses
• Integrate service into EasyPostClient as client.fedexRegistration
• Auto-generate UUID for required name parameter when not provided (matches web UI behavior)
• Add comprehensive test suite with VCR cassettes for all endpoints
• Parameters properly wrapped to match official FedEx MFA API structure

API Usage

The FedEx MFA API requires parameters to be wrapped in specific keys. All endpoints support an optional easypost_details object with carrier_account_id.

Step 1: Register Address

Map<String, Object> addressValidation = new HashMap<>();
addressValidation.put("name", "Account Name");
addressValidation.put("street1", "179 N Harbor Dr");
addressValidation.put("city", "Redondo Beach");
addressValidation.put("state", "CA");
addressValidation.put("postal_code", "90277");
addressValidation.put("country_code", "US");

Map<String, Object> easypostDetails = new HashMap<>();
easypostDetails.put("carrier_account_id", "ca_123456778");

Map<String, Object> params = new HashMap<>();
params.put("address_validation", addressValidation);
params.put("easypost_details", easypostDetails);

FedexRegistration registration = client.fedexRegistration.registerAddress("123456789", params);

Step 2: Request PIN

Map<String, Object> pinMethod = new HashMap<>();
pinMethod.put("option", "SMS"); // or "CALL", "EMAIL"

Map<String, Object> params = new HashMap<>();
params.put("pin_method", pinMethod);

FedexRegistration registration = client.fedexRegistration.requestPin("123456789", params);

Step 3: Validate PIN

Map<String, Object> pinValidation = new HashMap<>();
pinValidation.put("pin_code", "123456");
pinValidation.put("name", "Account Name"); // optional - auto-generated if not provided

Map<String, Object> easypostDetails = new HashMap<>();
easypostDetails.put("carrier_account_id", "ca_123456778");

Map<String, Object> params = new HashMap<>();
params.put("pin_validation", pinValidation);
params.put("easypost_details", easypostDetails);

FedexRegistration registration = client.fedexRegistration.validatePin("123456789", params);

Step 4: Submit Invoice (Alternative to PIN)

Map<String, Object> invoiceValidation = new HashMap<>();
invoiceValidation.put("name", "Account Name");
invoiceValidation.put("invoice_number", "INV-12345");
invoiceValidation.put("invoice_date", "2025-01-01");
invoiceValidation.put("invoice_amount", "100.00");
invoiceValidation.put("invoice_currency", "USD");

Map<String, Object> easypostDetails = new HashMap<>();
easypostDetails.put("carrier_account_id", "ca_123456778");

Map<String, Object> params = new HashMap<>();
params.put("invoice_validation", invoiceValidation);
params.put("easypost_details", easypostDetails);

FedexRegistration registration = client.fedexRegistration.submitInvoice("123456789", params);

Testing

• Mocks calls to difficult to test endpoints ensuring deserialization works as expected
• Passes CheckStyle linting
• Successful compilation with Java 8 target

Implementation Notes

• The name parameter is required by the FedEx API and must be unique per registration
• When not explicitly provided in the wrapped validation objects, the service auto-generates a UUID (hyphens removed) to match the behavior of the EasyPost web UI
• All parameters follow the structure defined in the official FedEx MFA support documentation
• The service handles parameter wrapping internally - users provide structured maps that get wrapped appropriately for each endpoint