TSM-06: convert Group A services to TypeScript

audit-ci.jsonc

@@ -4,6 +4,7 @@
   "critical": true,
   // Can't update ESLint yet because we must support Node 16
   "allowlist": [
+    "GHSA-2v37-7h3g-55p8",
     "GHSA-3ppc-4f35-3m26",
     "GHSA-23c5-xmqv-rm74",
     "GHSA-7r86-cg39-jmmj",

package.json

@@ -25,18 +25,19 @@
   "scripts": {
     "build": "vite build",
     "clean": "rm -rf ./dist ./nyc_output ./node_modules/.cache ./coverage",
-    "coverage": "cross-env NODE_ENV=test vitest run --coverage",
+    "coverage": "npm run typescript:test && cross-env NODE_ENV=test vitest run --coverage",
     "docs": "jsdoc src/models src/services src/errors src/utils -d docs",
     "format": "prettier --write .",
     "formatCheck": "prettier --check .",
     "lint": "eslint --ext .js,.ts --ignore-pattern 'examples/**' .",
     "lintFix": "eslint --ext .js,.ts --ignore-pattern 'examples/**' --fix .",
     "prepublishOnly": "npm run clean && npm run build && npm run test && npm run lint && npm run formatCheck",
     "scan": "npx audit-ci -m --config ./audit-ci.jsonc",
-    "test": "cross-env NODE_ENV=test vitest run",
+    "test": "npm run typescript:test && cross-env NODE_ENV=test vitest run",
     "test:node-compatibility": "cross-env NODE_ENV=test node ./test/node_compatibility",
     "typescript": "npm run typescript:declarations && npm run typescript:source && npm run typescript:compat",
     "typescript:declarations": "npx tsc -p tsconfig.json",
+    "typescript:test": "npx tsc -p tsconfig.test-services.json",
     "typescript:source": "npx tsc -p tsconfig.build.json",
     "typescript:compat": "npx tsc -p tsconfig.type-tests.json",
     "watch": "vite build --watch"

src/easypost.ts

@@ -59,8 +59,24 @@ interface HttpMiddleware {
   (httpClient: HttpClient): HttpClient;
 }
 
+type MiddlewareResponse = {
+  statusCode: number;
+  body: unknown;
+  headers?: Record<string, string>;
+};
+
+interface MiddlewareRequest {
+  method?: string;
+  url?: string;
+  _data?: unknown;
+  set?(headersToSet?: RequestHeaders): CompatibilityRequest;
+  auth?(key: string): unknown;
+  query?(queryParams?: Record<string, unknown>): CompatibilityRequest | MiddlewareResponse;
+  send?(body?: unknown): CompatibilityRequest | MiddlewareResponse;
+}
+
 interface RequestMiddleware {
-  (request: CompatibilityRequest): CompatibilityRequest | undefined;
+  (request: CompatibilityRequest): MiddlewareRequest | undefined;
 }
 /* eslint-enable no-unused-vars */
 
@@ -436,7 +452,7 @@ export default class EasyPostClient {
       },
     };
 
-    let middlewareRequest = compatibilityRequest;
+    let middlewareRequest: MiddlewareRequest = compatibilityRequest;
 
     if (this.requestMiddleware) {
       middlewareRequest = this.requestMiddleware(compatibilityRequest) || compatibilityRequest;

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

@@ -1,4 +1,27 @@
 import baseService from './base_service';
+import Address from '../models/address';
+
+type AddressCreateParameters = Record<string, unknown> & {
+  name?: string | null;
+  company?: string | null;
+  street1?: string | null;
+  street2?: string | null;
+  city?: string | null;
+  state?: string | null;
+  zip?: string | null;
+  country?: string | null;
+  phone?: string | null;
+  email?: string | null;
+  residential?: boolean | null;
+  federal_tax_id?: string | null;
+  state_tax_id?: string | null;
+  verify?: boolean | string | Array<boolean | string> | null;
+  verify_strict?: boolean | string | Array<boolean | string> | null;
+  verify_carrier?: string | null;
+};
+
+type PaginationCollection = Record<string, unknown>;
+type AddressCollection = { addresses: Address[]; has_more: boolean };
 
 export default (easypostClient) =>
   /**
@@ -12,10 +35,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: AddressCreateParameters): Promise<Address> {
       const url = 'addresses';
 
-      const wrappedParams = {};
+      const wrappedParams: Record<string, unknown> = {};
 
       if (params.verify) {
         wrappedParams.verify = params.verify;
@@ -43,10 +66,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: AddressCreateParameters): Promise<Address> {
       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 +93,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<AddressCollection> {
       const url = 'addresses';
 
       return this._all(url, params);
@@ -82,7 +105,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<AddressCollection> {
       const url = 'addresses';
       return this._getNextPage(url, 'addresses', addresses, pageSize);
     }
@@ -93,7 +119,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<Address> {
       const url = `addresses/${id}`;
 
       return this._retrieve(url);
@@ -105,12 +131,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<Address> {
       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

@@ -207,7 +207,7 @@ 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: any, params: any = {}): any {
       const modelResponse = this._buildEasyPostObject(response, params);
 
       return this._toPlainEasyPostObject(modelResponse);
@@ -274,7 +274,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: any,
+      pageSize: number | null = null,
+      optionalParams: any = {},
+    ): Promise<any> {
       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,4 +1,20 @@
 import baseService from './base_service';
+import CustomsInfo from '../models/customs_info';
+
+type CustomsItemInput = Record<string, unknown>;
+
+type CustomsInfoCreateParameters = Record<string, unknown> & {
+  eel_pfc?: string | null;
+  contents_type?: string | null;
+  contents_explanation?: string | null;
+  customs_certify?: boolean | null;
+  customs_signer?: string | null;
+  non_delivery_option?: 'abandon' | 'return' | null;
+  restriction_type?: 'none' | 'other' | 'quarantine' | 'sanitary_phytosanitary_inspection' | null;
+  restriction_comments?: string | null;
+  customs_items?: CustomsItemInput[] | null;
+  declaration?: string | null;
+};
 
 export default (easypostClient) =>
   /**
@@ -12,7 +28,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: CustomsInfoCreateParameters): Promise<CustomsInfo> {
       const url = 'customs_infos';
 
       const wrappedParams = {
@@ -28,7 +44,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<CustomsInfo> {
       const url = `customs_infos/${id}`;
 
       return this._retrieve(url);

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

@@ -1,4 +1,16 @@
 import baseService from './base_service';
+import CustomsItem from '../models/customs_item';
+
+type CustomsItemCreateParameters = Record<string, unknown> & {
+  description?: string | null;
+  quantity?: number | null;
+  value?: number | null;
+  weight?: number | null;
+  hs_tariff_number?: string | null;
+  code?: string | null;
+  origin_country?: string | null;
+  currency?: string | null;
+};
 
 export default (easypostClient) =>
   /**
@@ -12,7 +24,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: CustomsItemCreateParameters): Promise<CustomsItem> {
       const url = 'customs_items';
 
       const wrappedParams = {
@@ -28,7 +40,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<CustomsItem> {
       const url = `customs_items/${id}`;
 
       return this._retrieve(url);

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

@@ -1,4 +1,13 @@
 import baseService from './base_service';
+import Parcel from '../models/parcel';
+
+type ParcelCreateParameters = Record<string, unknown> & {
+  length?: number | null;
+  width?: number | null;
+  height?: number | null;
+  weight?: number | null;
+  predefined_package?: string | null;
+};
 
 export default (easypostClient) =>
   /**
@@ -12,7 +21,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: ParcelCreateParameters): Promise<Parcel> {
       const url = 'parcels';
 
       const wrappedParams = {
@@ -28,7 +37,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<Parcel> {
       const url = `parcels/${id}`;
 
       return this._retrieve(url);