feat: add FedEx multi-factor authentication registration support

src/easypost.js

@@ -23,6 +23,7 @@ import CustomsItemService from './services/customs_item_service';
 import EmbeddableService from './services/embeddable_service';
 import EndShipperService from './services/end_shipper_service';
 import EventService from './services/event_service';
+import FedExRegistrationService from './services/fedex_registration_service';
 import InsuranceService from './services/insurance_service';
 import LumaService from './services/luma_service';
 import OrderService from './services/order_service';
@@ -375,6 +376,7 @@ EasyPostClient.SERVICES = {
   Embeddable: EmbeddableService,
   EndShipper: EndShipperService,
   Event: EventService,
+  FedExRegistration: FedExRegistrationService,
   Insurance: InsuranceService,
   Luma: LumaService,
   Order: OrderService,

src/services/fedex_registration_service.js

@@ -0,0 +1,169 @@
+import { v4 as uuid } from 'uuid';
+
+import baseService from './base_service';
+
+export default (easypostClient) =>
+  /**
+   * The FedExRegistrationService class provides methods for registering FedEx carrier accounts with MFA.
+   * @param {EasyPostClient} easypostClient - The pre-configured EasyPostClient instance to use for API requests with this service.
+   */
+  class FedExRegistrationService extends baseService(easypostClient) {
+    /**
+     * Register the billing address for a FedEx account.
+     * @param {string} fedexAccountNumber - The FedEx account number.
+     * @param {Object} params - Map of parameters.
+     * @returns {Object}
+     */
+    static async registerAddress(fedexAccountNumber, params) {
+      const wrappedParams = this._wrapAddressValidation(params);
+      const endpoint = `fedex_registrations/${fedexAccountNumber}/address`;
+
+      try {
+        const response = await easypostClient._post(endpoint, wrappedParams);
+        return this._convertToEasyPostObject(response.body, params);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    }
+
+    /**
+     * Request a PIN for FedEx account verification.
+     * @param {string} fedexAccountNumber - The FedEx account number.
+     * @param {string} pinMethodOption - The PIN delivery method: "SMS", "CALL", or "EMAIL".
+     * @returns {Object}
+     */
+    static async requestPin(fedexAccountNumber, pinMethodOption) {
+      const wrappedParams = {
+        pin_method: {
+          option: pinMethodOption,
+        },
+      };
+      const endpoint = `fedex_registrations/${fedexAccountNumber}/pin`;
+
+      try {
+        const response = await easypostClient._post(endpoint, wrappedParams);
+        return this._convertToEasyPostObject(response.body, wrappedParams);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    }
+
+    /**
+     * Validate the PIN entered by the user for FedEx account verification.
+     * @param {string} fedexAccountNumber - The FedEx account number.
+     * @param {Object} params - Map of parameters.
+     * @returns {Object}
+     */
+    static async validatePin(fedexAccountNumber, params) {
+      const wrappedParams = this._wrapPinValidation(params);
+      const endpoint = `fedex_registrations/${fedexAccountNumber}/pin/validate`;
+
+      try {
+        const response = await easypostClient._post(endpoint, wrappedParams);
+        return this._convertToEasyPostObject(response.body, params);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    }
+
+    /**
+     * Submit invoice information to complete FedEx account registration.
+     * @param {string} fedexAccountNumber - The FedEx account number.
+     * @param {Object} params - Map of parameters.
+     * @returns {Object}
+     */
+    static async submitInvoice(fedexAccountNumber, params) {
+      const wrappedParams = this._wrapInvoiceValidation(params);
+      const endpoint = `fedex_registrations/${fedexAccountNumber}/invoice`;
+
+      try {
+        const response = await easypostClient._post(endpoint, wrappedParams);
+        return this._convertToEasyPostObject(response.body, params);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    }
+
+    /**
+     * Wraps address validation parameters and ensures the "name" field exists.
+     * If not present, generates a UUID (with hyphens removed) as the name.
+     * @private
+     * @param {Object} params - The original parameters map.
+     * @returns {Object} - A new map with properly wrapped address_validation and easypost_details.
+     */
+    static _wrapAddressValidation(params) {
+      const wrappedParams = {};
+
+      if (params.address_validation) {
+        const addressValidation = { ...params.address_validation };
+        this._ensureNameField(addressValidation);
+        wrappedParams.address_validation = addressValidation;
+      }
+
+      if (params.easypost_details) {
+        wrappedParams.easypost_details = params.easypost_details;
+      }
+
+      return wrappedParams;
+    }
+
+    /**
+     * Wraps PIN validation parameters and ensures the "name" field exists.
+     * If not present, generates a UUID (with hyphens removed) as the name.
+     * @private
+     * @param {Object} params - The original parameters map.
+     * @returns {Object} - A new map with properly wrapped pin_validation and easypost_details.
+     */
+    static _wrapPinValidation(params) {
+      const wrappedParams = {};
+
+      if (params.pin_validation) {
+        const pinValidation = { ...params.pin_validation };
+        this._ensureNameField(pinValidation);
+        wrappedParams.pin_validation = pinValidation;
+      }
+
+      if (params.easypost_details) {
+        wrappedParams.easypost_details = params.easypost_details;
+      }
+
+      return wrappedParams;
+    }
+
+    /**
+     * Wraps invoice validation parameters and ensures the "name" field exists.
+     * If not present, generates a UUID (with hyphens removed) as the name.
+     * @private
+     * @param {Object} params - The original parameters map.
+     * @returns {Object} - A new map with properly wrapped invoice_validation and easypost_details.
+     */
+    static _wrapInvoiceValidation(params) {
+      const wrappedParams = {};
+
+      if (params.invoice_validation) {
+        const invoiceValidation = { ...params.invoice_validation };
+        this._ensureNameField(invoiceValidation);
+        wrappedParams.invoice_validation = invoiceValidation;
+      }
+
+      if (params.easypost_details) {
+        wrappedParams.easypost_details = params.easypost_details;
+      }
+
+      return wrappedParams;
+    }
+
+    /**
+     * Ensures the "name" field exists in the provided map.
+     * If not present, generates a UUID (with hyphens removed) as the name.
+     * This follows the pattern used in the web UI implementation.
+     * @private
+     * @param {Object} map - The map to ensure the "name" field in.
+     */
+    static _ensureNameField(map) {
+      if (!map.name || map.name === null) {
+        const uuidValue = uuid().replace(/-/g, '');
+        map.name = uuidValue;
+      }
+    }
+  };

test/services/fedex_registration.test.js

@@ -0,0 +1,196 @@
+import { expect } from 'chai';
+
+import EasyPostClient from '../../src/easypost';
+import {
+  MockMiddleware,
+  MockRequest,
+  MockRequestMatchRule,
+  MockRequestResponseInfo,
+} from '../helpers/mocking';
+
+/* eslint-disable func-names */
+describe('FedExRegistrationService', function () {
+  it('registers a billing address', async function () {
+    const fedexAccountNumber = '123456789';
+    const addressValidation = {
+      name: 'BILLING NAME',
+      street1: '1234 BILLING STREET',
+      city: 'BILLINGCITY',
+      state: 'ST',
+      postal_code: '12345',
+      country_code: 'US',
+    };
+
+    const easypostDetails = {
+      carrier_account_id: 'ca_123',
+    };
+
+    const params = {
+      address_validation: addressValidation,
+      easypost_details: easypostDetails,
+    };
+
+    const mockResponse = {
+      email_address: null,
+      options: ['SMS', 'CALL', 'INVOICE'],
+      phone_number: '***-***-9721',
+    };
+
+    const middleware = (request) => {
+      return new MockMiddleware(request, [
+        new MockRequest(
+          new MockRequestMatchRule(
+            'POST',
+            `v2\\/fedex_registrations\\/${fedexAccountNumber}\\/address`,
+          ),
+          new MockRequestResponseInfo(200, mockResponse),
+        ),
+      ]);
+    };
+
+    const client = new EasyPostClient('test_api_key', {
+      requestMiddleware: middleware,
+    });
+
+    const response = await client.FedExRegistration.registerAddress(fedexAccountNumber, params);
+
+    expect(response.email_address).to.be.null;
+    expect(response.options).to.include('SMS');
+    expect(response.options).to.include('CALL');
+    expect(response.options).to.include('INVOICE');
+    expect(response.phone_number).to.equal('***-***-9721');
+  });
+
+  it('requests a pin', async function () {
+    const fedexAccountNumber = '123456789';
+
+    const mockResponse = {
+      message: 'sent secured Pin',
+    };
+
+    const middleware = (request) => {
+      return new MockMiddleware(request, [
+        new MockRequest(
+          new MockRequestMatchRule(
+            'POST',
+            `v2\\/fedex_registrations\\/${fedexAccountNumber}\\/pin`,
+          ),
+          new MockRequestResponseInfo(200, mockResponse),
+        ),
+      ]);
+    };
+
+    const client = new EasyPostClient('test_api_key', {
+      requestMiddleware: middleware,
+    });
+
+    const response = await client.FedExRegistration.requestPin(fedexAccountNumber, 'SMS');
+
+    expect(response.message).to.equal('sent secured Pin');
+  });
+
+  it('validates a pin', async function () {
+    const fedexAccountNumber = '123456789';
+    const pinValidation = {
+      pin_code: '123456',
+      name: 'BILLING NAME',
+    };
+
+    const easypostDetails = {
+      carrier_account_id: 'ca_123',
+    };
+
+    const params = {
+      pin_validation: pinValidation,
+      easypost_details: easypostDetails,
+    };
+
+    const mockResponse = {
+      id: 'ca_123',
+      object: 'CarrierAccount',
+      type: 'FedexAccount',
+      credentials: {
+        account_number: '123456789',
+        mfa_key: '123456789-XXXXX',
+      },
+    };
+
+    const middleware = (request) => {
+      return new MockMiddleware(request, [
+        new MockRequest(
+          new MockRequestMatchRule(
+            'POST',
+            `v2\\/fedex_registrations\\/${fedexAccountNumber}\\/pin\\/validate`,
+          ),
+          new MockRequestResponseInfo(200, mockResponse),
+        ),
+      ]);
+    };
+
+    const client = new EasyPostClient('test_api_key', {
+      requestMiddleware: middleware,
+    });
+
+    const response = await client.FedExRegistration.validatePin(fedexAccountNumber, params);
+
+    expect(response.id).to.equal('ca_123');
+    expect(response.object).to.equal('CarrierAccount');
+    expect(response.type).to.equal('FedexAccount');
+    expect(response.credentials.account_number).to.equal('123456789');
+    expect(response.credentials.mfa_key).to.equal('123456789-XXXXX');
+  });
+
+  it('submits details about an invoice', async function () {
+    const fedexAccountNumber = '123456789';
+    const invoiceValidation = {
+      name: 'BILLING NAME',
+      invoice_number: 'INV-12345',
+      invoice_date: '2025-12-08',
+      invoice_amount: '100.00',
+      invoice_currency: 'USD',
+    };
+
+    const easypostDetails = {
+      carrier_account_id: 'ca_123',
+    };
+
+    const params = {
+      invoice_validation: invoiceValidation,
+      easypost_details: easypostDetails,
+    };
+
+    const mockResponse = {
+      id: 'ca_123',
+      object: 'CarrierAccount',
+      type: 'FedexAccount',
+      credentials: {
+        account_number: '123456789',
+        mfa_key: '123456789-XXXXX',
+      },
+    };
+
+    const middleware = (request) => {
+      return new MockMiddleware(request, [
+        new MockRequest(
+          new MockRequestMatchRule(
+            'POST',
+            `v2\\/fedex_registrations\\/${fedexAccountNumber}\\/invoice`,
+          ),
+          new MockRequestResponseInfo(200, mockResponse),
+        ),
+      ]);
+    };
+
+    const client = new EasyPostClient('test_api_key', {
+      requestMiddleware: middleware,
+    });
+
+    const response = await client.FedExRegistration.submitInvoice(fedexAccountNumber, params);
+
+    expect(response.id).to.equal('ca_123');
+    expect(response.object).to.equal('CarrierAccount');
+    expect(response.type).to.equal('FedexAccount');
+    expect(response.credentials.account_number).to.equal('123456789');
+    expect(response.credentials.mfa_key).to.equal('123456789-XXXXX');
+  });
+});