feat: Add optional transportConfig to Transporter

- Introduced `transportConfig` option to the Transporter class to allow customization of the HTTP client layer.
- Set native fetch as the default transport in Transporter, while providing a smooth fallback mechanism.
- Enhanced JSDoc comments to document the new `transportConfig` option.
- Added two example files to demonstrate the flexibility of the new feature:
  - One showing integration with the deprecated `request` library.
  - Another leveraging the `axios` library for HTTP requests.

This change provides users with the flexibility to switch between different HTTP libraries, catering to various needs and preferences.

Author: blakmatrix

examples/optional-axios-transport.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+const process = require('node:process');
+const dotenv = require('dotenv');
+const axios = require('axios');
+const zd = require('../src/index.js');
+
+dotenv.config();
+
+const transportConfigUsingAxios = {
+  async transportFn(uri, options) {
+    // Convert the options to be compatible with axios
+    const requestOptions = {
+      ...options,
+      url: uri,
+      method: options.method || 'GET', // Axios uses 'method', not just 'GET' or 'POST' as direct options
+      data: options.body, // Axios uses 'data' instead of 'body'
+    };
+
+    try {
+      const response = await axios(requestOptions);
+      return response;
+    } catch (error) {
+      // If axios throws an error, it usually encapsulates the actual server response within error.response.
+      // This is to ensure that even for error HTTP statuses, the response can be adapted consistently.
+      if (error.response) {
+        return error.response;
+      }
+
+      throw error; // If there's no error.response, then throw the error as is.
+    }
+  },
+
+  responseAdapter(response) {
+    return {
+      json: () => Promise.resolve(response.data),
+      status: response.status,
+      headers: {
+        get: (headerName) => response.headers[headerName.toLowerCase()],
+      },
+      statusText: response.statusText,
+    };
+  },
+};
+
+const setupClient = (config) => {
+  return zd.createClient({
+    username: process.env.ZENDESK_USERNAME,
+    subdomain: process.env.ZENDESK_SUBDOMAIN,
+    token: process.env.ZENDESK_TOKEN,
+    transportConfig: transportConfigUsingAxios,
+    ...config,
+  });
+};
+
+async function foo() {
+  try {
+    const client = setupClient({debug: false});
+    const result = await client.users.list();
+
+    console.dir(result);
+  } catch (error) {
+    console.error(`Failed: ${error.message}`);
+  }
+}
+
+foo();

examples/optional-deprecated-request-transport.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+const process = require('node:process');
+const dotenv = require('dotenv');
+const request = require('request');
+const zd = require('../src/index.js');
+
+dotenv.config();
+
+const transportConfigUsingRequest = {
+  transportFn(uri, options) {
+    // Convert the options to be compatible with the request library
+    const requestOptions = {
+      ...options,
+      uri,
+      headers: options.headers,
+      json: true, // Automatically stringifies the body to JSON
+    };
+
+    return new Promise((resolve, reject) => {
+      request(requestOptions, (error, response) => {
+        if (error) {
+          reject(error);
+        } else {
+          resolve(response);
+        }
+      });
+    });
+  },
+
+  responseAdapter(response) {
+    return {
+      json: () => Promise.resolve(response.body),
+      status: response.statusCode,
+      headers: {
+        get: (headerName) => response.headers[headerName.toLowerCase()],
+      },
+      statusText: response.statusMessage,
+    };
+  },
+};
+
+const setupClient = (config) => {
+  return zd.createClient({
+    username: process.env.ZENDESK_USERNAME,
+    subdomain: process.env.ZENDESK_SUBDOMAIN,
+    token: process.env.ZENDESK_TOKEN,
+    transportConfig: transportConfigUsingRequest,
+    ...config,
+  });
+};
+
+async function foo() {
+  try {
+    const client = setupClient({debug: false});
+    const result = await client.users.list();
+
+    console.dir(result);
+  } catch (error) {
+    console.error(`Failed: ${error.message}`);
+  }
+}
+
+foo();

src/client/transporter.js

@@ -5,12 +5,33 @@ const {CustomEventTarget} = require('./custom-event-target');
 const {EndpointChecker} = require('./endpoint-checker');
 const {assembleUrl} = require('./helpers');
 
+// Default transport config using fetch
+const defaultTransportConfig = {
+  transportFn(uri, options) {
+    return fetch(uri, options);
+  },
+
+  responseAdapter(response) {
+    return {
+      json: () => response.json(),
+      status: response.status,
+      headers: {
+        get: (headerName) => response.headers.get(headerName),
+      },
+      statusText: response.statusText,
+    };
+  },
+};
 class Transporter {
   constructor(options) {
     this.options = options;
     this.authHandler = new AuthorizationHandler(this.options);
     this.eventTarget = new CustomEventTarget();
     this.endpointChecker = new EndpointChecker();
+    const transportConfig =
+      this.options.transportConfig || defaultTransportConfig;
+    this.transportFn = transportConfig.transportFn;
+    this.responseAdapter = transportConfig.responseAdapter;
   }
 
   // Transporter methods
@@ -49,7 +70,10 @@ class Transporter {
 
   async sendRequest(options) {
     this.emit('debug::request', options); // Emit before the request
-    const response = await this.fetchWithOptions(options.uri, options);
+
+    const rawResponse = await this.transportFn(options.uri, options);
+    const response = this.responseAdapter(rawResponse);
+
     this.emit('debug::response', response); // Emit after the request
     let result = {};
     if (
@@ -81,10 +105,6 @@ class Transporter {
     };
   }
 
-  fetchWithOptions(uri, options) {
-    return fetch(options.uri, options);
-  }
-
   getHeadersForRequest() {
     const headers = {
       Authorization: this.authHandler.createAuthorizationHeader(),

src/index.js

@@ -24,6 +24,9 @@ const {MODULES, ENDPOINTS} = require('./constants');
  * @property {boolean} [options.throttle] - Flag to enable throttling of requests.
  * @property {boolean} [options.debug=false] - Flag to enable or disable debug logging.
  * @property {object} [options.logger=ConsoleLogger] - Optional logger for logging. Should have methods like `info`, `error`, etc. Defaults to a basic console logger.
+ * @property {object} [options.transportConfig] - Configuration for custom transport functionality.
+ * @property {function} [options.transportConfig.transportFn] - Custom function to perform the request. By default, it uses `fetch`. It should return a response object.
+ * @property {function} [options.transportConfig.responseAdapter] - Custom function to adapt the response from `transportFn` into a consistent format. By default, it adapts for `fetch` response.
  *
  * @example
  * const zendeskOptions = {