TSM-06: convert Group A services to TypeScript

src/services/address_service.js → src/services/address_service.ts

@@ -1,5 +1,13 @@
 import baseService from './base_service';
 
+type AddressParams = Record<string, unknown> & {
+  verify?: unknown;
+  verify_strict?: unknown;
+  verify_carrier?: unknown;
+};
+
+type PaginationCollection = Record<string, unknown>;
+
 export default (easypostClient) =>
   /**
    * The AddressService class provides methods for interacting with EasyPost {@link Address} objects.
@@ -12,10 +20,10 @@ export default (easypostClient) =>
      * @param {Object} params - Parameters for the address to be created.
      * @returns {Address} - The created address.
      */
-    static async create(params) {
+    static async create(params: AddressParams): Promise<unknown> {
       const url = 'addresses';
 
-      const wrappedParams = {};
+      const wrappedParams: Record<string, unknown> = {};
 
       if (params.verify) {
         wrappedParams.verify = params.verify;
@@ -43,10 +51,10 @@ export default (easypostClient) =>
      * @param {Object} params - Parameters for the address to be created.
      * @returns {Address} - The created and verified address.
      */
-    static async createAndVerify(params) {
+    static async createAndVerify(params: AddressParams): Promise<unknown> {
       const url = `addresses/create_and_verify`;
 
-      const wrappedParams = {};
+      const wrappedParams: Record<string, unknown> = {};
 
       if (params.verify_carrier) {
         wrappedParams.verify_carrier = params.verify_carrier;
@@ -70,7 +78,7 @@ export default (easypostClient) =>
      * @param {Object} [params] - Parameters to filter the list of addresses.
      * @returns {Object} - An object containing a list of {@link Address addresses} and pagination information.
      */
-    static async all(params = {}) {
+    static async all(params: Record<string, unknown> = {}): Promise<unknown> {
       const url = 'addresses';
 
       return this._all(url, params);
@@ -82,7 +90,10 @@ export default (easypostClient) =>
      * @param {Number} pageSize The number of records to return on each page
      * @returns {EasyPostObject|Promise<never>} The retrieved {@link EasyPostObject}-based class instance, or a `Promise` that rejects with an error.
      */
-    static async getNextPage(addresses, pageSize = null) {
+    static async getNextPage(
+      addresses: PaginationCollection,
+      pageSize?: number,
+    ): Promise<unknown> {
       const url = 'addresses';
       return this._getNextPage(url, 'addresses', addresses, pageSize);
     }
@@ -93,7 +104,7 @@ export default (easypostClient) =>
      * @param {string} id - The ID of the address to retrieve.
      * @returns {Address} - The retrieved address.
      */
-    static async retrieve(id) {
+    static async retrieve(id: string): Promise<unknown> {
       const url = `addresses/${id}`;
 
       return this._retrieve(url);
@@ -105,12 +116,12 @@ export default (easypostClient) =>
      * @param {string} id - The ID of the address to verify.
      * @returns {Address} - The verified address.
      */
-    static async verifyAddress(id) {
+    static async verifyAddress(id: string): Promise<unknown> {
       try {
         const url = `addresses/${id}/verify`;
         const response = await easypostClient._get(url);
 
-        return this._convertToEasyPostObject(response.body.address);
+        return this._convertToEasyPostObject(response.body.address, {});
       } catch (e) {
         return Promise.reject(e);
       }

src/services/base_service.ts

@@ -208,7 +208,10 @@ export default (easypostClient) =>
      * @param {*} params The parameters passed when fetching the response.
      * @returns {*} A plain object or array suitable for JSON serialization.
      */
-    static _convertToEasyPostObject(response, params) {
+    static _convertToEasyPostObject(
+      response: unknown,
+      params: Record<string, unknown> = {},
+    ): unknown {
       const modelResponse = this._buildEasyPostObject(response, params);
 
       return this._toPlainEasyPostObject(modelResponse);
@@ -275,7 +278,13 @@ export default (easypostClient) =>
      * @returns {EasyPostObject|Promise<never>} The retrieved {@link EasyPostObject}-based class instance, or a `Promise` that rejects with an error.
      * TODO: Implement this function in EndShippers and Batches once the API supports them properly.
      */
-    static async _getNextPage(url, key, collection, pageSize = null, optionalParams = {}) {
+    static async _getNextPage(
+      url: string,
+      key: string,
+      collection: Record<string, unknown>,
+      pageSize: number | null = null,
+      optionalParams: Record<string, unknown> = {},
+    ): Promise<unknown> {
       const collectionArray = collection[key];
       if (collectionArray == undefined || collectionArray.length == 0 || !collection.has_more) {
         throw new EndOfPaginationError();

src/services/customs_info_service.js → src/services/customs_info_service.ts

@@ -1,5 +1,7 @@
 import baseService from './base_service';
 
+type CustomsInfoParams = Record<string, unknown>;
+
 export default (easypostClient) =>
   /**
    * The CustomsInfoService class provides methods for interacting with EasyPost {@link CustomsInfo} objects.
@@ -12,7 +14,7 @@ export default (easypostClient) =>
      * @param {Object} params - Parameters for the customs info to be created.
      * @returns {CustomsInfo} - The created customs info.
      */
-    static async create(params) {
+    static async create(params: CustomsInfoParams): Promise<unknown> {
       const url = 'customs_infos';
 
       const wrappedParams = {
@@ -28,7 +30,7 @@ export default (easypostClient) =>
      * @param {string} id - The ID of the customs info to retrieve.
      * @returns {CustomsInfo} - The retrieved customs info.
      */
-    static async retrieve(id) {
+    static async retrieve(id: string): Promise<unknown> {
       const url = `customs_infos/${id}`;
 
       return this._retrieve(url);

src/services/customs_item_service.js → src/services/customs_item_service.ts

@@ -1,5 +1,7 @@
 import baseService from './base_service';
 
+type CustomsItemParams = Record<string, unknown>;
+
 export default (easypostClient) =>
   /**
    * The CustomsItemService class provides methods for interacting with EasyPost {@link CustomsItem} objects.
@@ -12,7 +14,7 @@ export default (easypostClient) =>
      * @param {Object} params - Parameters for the customs item to be created.
      * @returns {CustomsItem} - The created customs item.
      */
-    static async create(params) {
+    static async create(params: CustomsItemParams): Promise<unknown> {
       const url = 'customs_items';
 
       const wrappedParams = {
@@ -28,7 +30,7 @@ export default (easypostClient) =>
      * @param {string} id - The ID of the customs item to retrieve.
      * @returns {CustomsItem} - The retrieved customs item.
      */
-    static async retrieve(id) {
+    static async retrieve(id: string): Promise<unknown> {
       const url = `customs_items/${id}`;
 
       return this._retrieve(url);

src/services/parcel_service.js → src/services/parcel_service.ts

@@ -1,5 +1,7 @@
 import baseService from './base_service';
 
+type ParcelParams = Record<string, unknown>;
+
 export default (easypostClient) =>
   /**
    * The ParcelService class provides methods for interacting with EasyPost {@link Parcel} objects.
@@ -12,7 +14,7 @@ export default (easypostClient) =>
      * @param {Object} params - The parameters to create a parcel with.
      * @returns {Parcel} - The created parcel.
      */
-    static async create(params) {
+    static async create(params: ParcelParams): Promise<unknown> {
       const url = 'parcels';
 
       const wrappedParams = {
@@ -28,7 +30,7 @@ export default (easypostClient) =>
      * @param {string} id - The ID of the parcel to retrieve.
      * @returns {Parcel} - The retrieved parcel.
      */
-    static async retrieve(id) {
+    static async retrieve(id: string): Promise<unknown> {
       const url = `parcels/${id}`;
 
       return this._retrieve(url);

src/services/shipment_service.js → src/services/shipment_service.ts

@@ -1,6 +1,10 @@
 import Constants from '../constants';
 import baseService from './base_service';
 
+type ShipmentParams = Record<string, unknown>;
+type ShipmentRateInput = string | { id: string };
+type ShipmentCollection = Record<string, unknown>;
+
 export default (easypostClient) =>
   /**
    * The ShipmentService class provides methods for interacting with EasyPost {@link Shipment} objects.
@@ -13,7 +17,7 @@ export default (easypostClient) =>
      * @param {Object} params - The parameters to create a shipment with.
      * @returns {Shipment} - The created shipment.
      */
-    static async create(params) {
+    static async create(params: ShipmentParams): Promise<unknown> {
       const url = 'shipments';
 
       const wrappedParams = {
@@ -32,7 +36,12 @@ export default (easypostClient) =>
      * @param {string|null} [endShipperId] - The ID of the end shipper to purchase the shipment with.
      * @returns {Shipment} - The purchased shipment.
      */
-    static async buy(id, rate, insuranceAmount = null, endShipperId = null) {
+    static async buy(
+      id: string,
+      rate: ShipmentRateInput,
+      insuranceAmount: number | null = null,
+      endShipperId: string | null = null,
+    ): Promise<unknown> {
       let rateId = rate;
 
       if (typeof rate === 'object') {
@@ -41,7 +50,7 @@ export default (easypostClient) =>
 
       const url = `shipments/${id}/buy`;
 
-      const wrappedParams = {
+      const wrappedParams: Record<string, unknown> = {
         rate: {
           id: rateId,
         },
@@ -71,7 +80,7 @@ export default (easypostClient) =>
      * @param {string} format - The format to convert the label to.
      * @returns {Shipment} - The shipment with the converted label format.
      */
-    static async convertLabelFormat(id, format) {
+    static async convertLabelFormat(id: string, format: string): Promise<unknown> {
       const url = `shipments/${id}/label`;
       const wrappedParams = { file_format: format };
 
@@ -90,7 +99,7 @@ export default (easypostClient) =>
      * @param {string} id - The ID of the shipment to regenerate rates for.
      * @returns {Shipment} - The shipment with regenerated rates.
      */
-    static async regenerateRates(id) {
+    static async regenerateRates(id: string): Promise<unknown> {
       const url = `shipments/${id}/rerate`;
       const wrappedParams = {};
 
@@ -109,13 +118,13 @@ export default (easypostClient) =>
      * @param {string} id - The ID of the shipment to get SmartRates for.
      * @returns {Rate[]} - The SmartRates for the shipment.
      */
-    static async getSmartRates(id) {
+    static async getSmartRates(id: string): Promise<unknown> {
       const url = `shipments/${id}/smartrate`;
 
       try {
         const response = await easypostClient._get(url);
 
-        return this._convertToEasyPostObject(response.body.result);
+        return this._convertToEasyPostObject(response.body.result, {});
       } catch (e) {
         return Promise.reject(e);
       }
@@ -128,7 +137,7 @@ export default (easypostClient) =>
      * @param {number|string} amount - The amount to insure the shipment for.
      * @returns {Shipment} - The insured shipment.
      */
-    static async insure(id, amount) {
+    static async insure(id: string, amount: number | string): Promise<unknown> {
       const url = `shipments/${id}/insure`;
       const wrappedParams = { amount };
 
@@ -149,7 +158,11 @@ export default (easypostClient) =>
      * @param {Map} [formOptions] - Options for the form.
      * @returns {Shipment} - The shipment with the generated form attached.
      */
-    static async generateForm(id, formType, formOptions = {}) {
+    static async generateForm(
+      id: string,
+      formType: string,
+      formOptions: Record<string, unknown> = {},
+    ): Promise<unknown> {
       const url = `shipments/${id}/forms`;
       const wrappedParams = {
         form: {
@@ -173,13 +186,13 @@ export default (easypostClient) =>
      * @param {string} id - The ID of the shipment to refund.
      * @returns {Shipment} - The refunded shipment.
      */
-    static async refund(id) {
+    static async refund(id: string): Promise<unknown> {
       const url = `shipments/${id}/refund`;
 
       try {
         const response = await easypostClient._post(url);
 
-        return this._convertToEasyPostObject(response.body);
+        return this._convertToEasyPostObject(response.body, {});
       } catch (e) {
         return Promise.reject(e);
       }
@@ -192,7 +205,11 @@ export default (easypostClient) =>
      * @param {string} deliveryAccuracy - The accuracy of the delivery days.
      * @returns {Rate} - The lowest SmartRate of the shipment.
      */
-    static async lowestSmartRate(id, deliveryDays, deliveryAccuracy) {
+    static async lowestSmartRate(
+      id: string,
+      deliveryDays: number,
+      deliveryAccuracy: string,
+    ): Promise<unknown> {
       const smartRates = await this.getSmartRates(id);
       return Constants.Utils.getLowestSmartRate(
         smartRates,
@@ -207,7 +224,7 @@ export default (easypostClient) =>
      * @param {Object} [params] - Parameters to filter the shipments by.
      * @returns {Object} - An object containing a list of {@link Shipment shipments} and pagination information.
      */
-    static async all(params = {}) {
+    static async all(params: Record<string, unknown> = {}): Promise<unknown> {
       const url = 'shipments';
 
       return this._all(url, params);
@@ -219,7 +236,10 @@ export default (easypostClient) =>
      * @param {Number} pageSize The number of records to return on each page
      * @returns {EasyPostObject|Promise<never>} The retrieved {@link EasyPostObject}-based class instance, or a `Promise` that rejects with an error.
      */
-    static async getNextPage(shipments, pageSize = null) {
+    static async getNextPage(
+      shipments: ShipmentCollection,
+      pageSize?: number,
+    ): Promise<unknown> {
       const url = 'shipments';
 
       return this._getNextPage(url, 'shipments', shipments, pageSize);
@@ -231,7 +251,7 @@ export default (easypostClient) =>
      * @param {string} id - The ID of the shipment to retrieve.
      * @returns {Shipment} - The shipment with the given ID.
      */
-    static async retrieve(id) {
+    static async retrieve(id: string): Promise<unknown> {
       const url = `shipments/${id}`;
 
       return this._retrieve(url);
@@ -243,7 +263,10 @@ export default (easypostClient) =>
      * @param {string} plannedShipDate - The planned ship date of the shipment.
      * @returns {Array} - An array of the estimated delivery date and rates.
      */
-    static async retrieveEstimatedDeliveryDate(id, plannedShipDate) {
+    static async retrieveEstimatedDeliveryDate(
+      id: string,
+      plannedShipDate: string,
+    ): Promise<unknown> {
       const url = `shipments/${id}/smartrate/delivery_date`;
 
       const wrappedParams = {
@@ -265,7 +288,7 @@ export default (easypostClient) =>
      * @param desiredDeliveryDate - The desired delivery date for the shipment.
      * @returns {Array} - An array of the recommended ship date and rates.
      */
-    static async recommendShipDate(id, desiredDeliveryDate) {
+    static async recommendShipDate(id: string, desiredDeliveryDate: string): Promise<unknown> {
       const url = `shipments/${id}/smartrate/precision_shipping`;
 
       const wrappedParams = {
@@ -286,7 +309,7 @@ export default (easypostClient) =>
      * @param {Object} params - The parameters to create and buy a Shipment with Luma.
      * @returns {Shipment} - The shipment with the given ID.
      */
-    static async createAndBuyLuma(params) {
+    static async createAndBuyLuma(params: ShipmentParams): Promise<unknown> {
       const url = `shipments/luma`;
 
       const wrappedParams = {
@@ -308,7 +331,7 @@ export default (easypostClient) =>
      * @param {Object} params - The parameters to buy a Shipment with Luma.
      * @returns {Shipment} - The shipment with the given ID.
      */
-    static async buyLuma(id, params) {
+    static async buyLuma(id: string, params: Record<string, unknown>): Promise<unknown> {
       const url = `shipments/${id}/luma`;
 
       try {