feat(configureable-logger): add support of configurable logger

.codeclimate.yml

@@ -38,6 +38,7 @@ checks:
     enabled: true
 exclude_patterns:
 - "scripts/"
+- "**/core/src/logger/"  
 - "**/**/test/"
 - "**/**/rollup.config.js"
 - "**/**/tsconfig.json"

packages/core-interfaces/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@apimatic/core-interfaces",
   "author": "APIMatic Ltd.",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "license": "MIT",
   "sideEffects": false,
   "main": "lib/index.js",

packages/core-interfaces/src/index.ts

@@ -5,3 +5,4 @@ export * from './httpInterceptor';
 export * from './httpRequest';
 export * from './httpResponse';
 export * from './retryConfiguration';
+export * from './logging';

packages/core-interfaces/src/logging.ts

@@ -0,0 +1,131 @@
+import { HttpRequest } from './httpRequest';
+import { HttpResponse } from './httpResponse';
+/**
+ * Represents an interface for logging API requests and responses.
+ */
+export interface ApiLoggerInterface {
+  /**
+   * Logs the details of an HTTP request.
+   * @param request The HTTP request to log.
+   */
+  logRequest(request: HttpRequest): void;
+
+  /**
+   * Logs the details of an HTTP response.
+   * @param response The HTTP response to log.
+   */
+  logResponse(response: HttpResponse): void;
+}
+
+/**
+ * Represents an interface for a generic logger.
+ */
+export interface LoggerInterface {
+  /**
+   * Logs a message with a specified log level and additional parameters.
+   * @param level The log level of the message.
+   * @param message The message to log.
+   * @param params Additional parameters to include in the log message.
+   */
+  log(level: LogLevel, message: string, params: Record<string, any>): void;
+}
+
+/**
+ * Represents options for configuring logging behavior.
+ */
+export interface LoggingOptions {
+  /**
+   * The logger to use for logging messages.
+   */
+  logger: LoggerInterface;
+
+  /**
+   * The log level to determine which messages should be logged.
+   */
+  logLevel: LogLevel;
+
+  /**
+   * Options for logging HTTP requests.
+   */
+  logRequest: HttpRequestLoggingOptions;
+
+  /**
+   * Options for logging HTTP responses.
+   */
+  logResponse: HttpMessageLoggingOptions;
+
+  /**
+   * Indicates whether sensitive headers should be masked in logged messages.
+   */
+  maskSensitiveHeaders: boolean;
+}
+
+/**
+ * Represents options for logging HTTP message details.
+ */
+export interface HttpMessageLoggingOptions {
+  /**
+   * Indicates whether the message body should be logged.
+   */
+  logBody: boolean;
+
+  /**
+   * Indicates whether the message headers should be logged.
+   */
+  logHeaders: boolean;
+
+  /**
+   * Array of headers not to be displayed in logging.
+   */
+  headersToExclude: string[];
+
+  /**
+   * Array of headers to be displayed in logging.
+   */
+  headersToInclude: string[];
+
+  /**
+   * Array of headers which values are non-senstive to display in logging.
+   */
+  headersToWhitelist: string[];
+}
+
+/**
+ * Represents options for logging HTTP request details.
+ */
+export interface HttpRequestLoggingOptions extends HttpMessageLoggingOptions {
+  /**
+   * Indicates whether the request query parameters should be included in the logged URL.
+   */
+  includeQueryInPath: boolean;
+}
+
+/**
+ * Enum representing different log levels.
+ */
+export enum LogLevel {
+  /**
+   * Error log level.
+   */
+  Error = 'error',
+
+  /**
+   * Warning log level.
+   */
+  Warn = 'warn',
+
+  /**
+   * Information log level.
+   */
+  Info = 'info',
+
+  /**
+   * Debug log level.
+   */
+  Debug = 'debug',
+
+  /**
+   * Trace log level.
+   */
+  Trace = 'trace',
+}

packages/core/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@apimatic/core",
   "author": "APIMatic Ltd.",
-  "version": "0.10.5",
+  "version": "0.10.6",
   "license": "MIT",
   "sideEffects": false,
   "main": "lib/index.js",
@@ -45,6 +45,7 @@
     "@size-limit/preset-small-lib": "^7.0.8",
     "@types/detect-node": "^2.0.0",
     "@types/lodash.flatmap": "^4.5.6",
+    "@types/lodash.defaultsdeep": "^4.6.9",
     "abort-controller": "^3.0.0",
     "babel-plugin-annotate-pure-calls": "^0.4.0",
     "jest": "^26.4.2",
@@ -70,6 +71,7 @@
     "form-data": "^3.0.0",
     "json-ptr": "^3.1.0",
     "lodash.flatmap": "^4.5.0",
+    "lodash.defaultsdeep": "^4.6.1",
     "tiny-warning": "^1.0.3",
     "tslib": "^2.1.0"
   },

packages/core/src/http/requestBuilder.ts

@@ -13,6 +13,7 @@ import {
   HttpInterceptorInterface,
   RequestOptions,
   RetryConfiguration,
+  ApiLoggerInterface,
 } from '../coreInterfaces';
 import { ArgumentsValidationError } from '../errors/argumentsValidationError';
 import { ResponseValidationError } from '../errors/responseValidationError';
@@ -90,11 +91,17 @@ export type ApiErrorConstructor = new (
   message: string
 ) => any;
 
+export interface ErrorType<ErrorCtorArgs extends any[]> {
+  statusCode: number | [number, number];
+  errorConstructor: new (response: HttpContext, ...args: ErrorCtorArgs) => any;
+  isTemplate?: boolean;
+  args: ErrorCtorArgs;
+}
+
 export interface ApiErrorFactory {
   apiErrorCtor: ApiErrorConstructor;
   message?: string | undefined;
 }
-
 export interface RequestBuilder<BaseUrlParamType, AuthParams> {
   deprecated(methodName: string, message?: string): void;
   prepareArgs: typeof prepareArgs;
@@ -205,6 +212,7 @@ export class DefaultRequestBuilder<BaseUrlParamType, AuthParams>
   protected _authParams?: AuthParams;
   protected _retryOption: RequestRetryOption;
   protected _apiErrorFactory: ApiErrorFactory;
+  protected _errorTypes: Array<ErrorType<any>>;
   public prepareArgs: typeof prepareArgs;
 
   constructor(
@@ -215,16 +223,21 @@ export class DefaultRequestBuilder<BaseUrlParamType, AuthParams>
     protected _httpMethod: HttpMethod,
     protected _xmlSerializer: XmlSerializerInterface,
     protected _retryConfig: RetryConfiguration,
-    protected _path?: string
+    protected _path?: string,
+    protected _apiLogger?: ApiLoggerInterface
   ) {
     this._headers = {};
     this._query = [];
     this._interceptors = [];
+    this._errorTypes = [];
     this._validateResponse = true;
     this._apiErrorFactory = { apiErrorCtor: _apiErrorCtr };
     this._addResponseValidator();
     this._addAuthentication();
     this._addRetryInterceptor();
+    this._addErrorHandlingInterceptor();
+    this._addApiLoggerInterceptors();
+
     this._retryOption = RequestRetryOption.Default;
     this.prepareArgs = prepareArgs.bind(this);
   }
@@ -427,22 +440,7 @@ export class DefaultRequestBuilder<BaseUrlParamType, AuthParams>
     isTemplate?: boolean,
     ...args: ErrorCtorArgs
   ): void {
-    this.interceptResponse((context) => {
-      const { response } = context;
-      if (isTemplate && args.length > 0) {
-        args[0] = updateErrorMessage(args[0], response);
-      }
-      if (
-        (typeof statusCode === 'number' &&
-          response.statusCode === statusCode) ||
-        (typeof statusCode !== 'number' &&
-          response.statusCode >= statusCode[0] &&
-          response.statusCode <= statusCode[1])
-      ) {
-        throw new errorConstructor(context, ...args);
-      }
-      return context;
-    });
+    this._errorTypes.push({ statusCode, errorConstructor, isTemplate, args });
   }
   public async call(
     requestOptions?: RequestOptions
@@ -582,12 +580,27 @@ export class DefaultRequestBuilder<BaseUrlParamType, AuthParams>
       return context;
     });
   }
+
+  private _addApiLoggerInterceptors(): void {
+    if (this._apiLogger) {
+      const apiLogger = this._apiLogger;
+
+      this.intercept(async (request, options, next) => {
+        apiLogger.logRequest(request);
+        const context = await next(request, options);
+        apiLogger.logResponse(context.response);
+        return context;
+      });
+    }
+  }
+
   private _addAuthentication() {
     this.intercept((...args) => {
       const handler = this._authenticationProvider(this._authParams);
       return handler(...args);
     });
   }
+
   private _addRetryInterceptor() {
     this.intercept(async (request, options, next) => {
       let context: HttpContext | undefined;
@@ -633,6 +646,28 @@ export class DefaultRequestBuilder<BaseUrlParamType, AuthParams>
       return { request, response: context.response };
     });
   }
+
+  private _addErrorHandlingInterceptor() {
+    this.interceptResponse((context) => {
+      const { response } = context;
+      for (const { statusCode, errorConstructor, isTemplate, args } of this
+        ._errorTypes) {
+        if (
+          (typeof statusCode === 'number' &&
+            response.statusCode === statusCode) ||
+          (typeof statusCode !== 'number' &&
+            response.statusCode >= statusCode[0] &&
+            response.statusCode <= statusCode[1])
+        ) {
+          if (isTemplate && args.length > 0) {
+            args[0] = updateErrorMessage(args[0], response);
+          }
+          throw new errorConstructor(context, ...args);
+        }
+      }
+      return context;
+    });
+  }
 }
 
 export function createRequestBuilderFactory<BaseUrlParamType, AuthParams>(
@@ -641,7 +676,8 @@ export function createRequestBuilderFactory<BaseUrlParamType, AuthParams>(
   apiErrorConstructor: ApiErrorConstructor,
   authenticationProvider: AuthenticatorInterface<AuthParams>,
   retryConfig: RetryConfiguration,
-  xmlSerializer: XmlSerializerInterface = new XmlSerialization()
+  xmlSerializer: XmlSerializerInterface = new XmlSerialization(),
+  apiLogger?: ApiLoggerInterface
 ): RequestBuilderFactory<BaseUrlParamType, AuthParams> {
   return (httpMethod, path?) => {
     return new DefaultRequestBuilder(
@@ -652,7 +688,8 @@ export function createRequestBuilderFactory<BaseUrlParamType, AuthParams>(
       httpMethod,
       xmlSerializer,
       retryConfig,
-      path
+      path,
+      apiLogger
     );
   };
 }

packages/core/src/index.ts

@@ -13,6 +13,11 @@ export * from './http/httpInterceptor';
 export * from './http/requestBuilder';
 export * from './http/pathTemplate';
 export { RequestRetryOption } from './http/retryConfiguration';
+export * from './logger/apiLogger';
+export * from './logger/defaultLogger';
+export * from './logger/nullLogger';
+export * from './logger/defaultLoggingConfiguration';
+export * from './logger/loggingOptions';
 export {
   indexedPrefix,
   unindexedPrefix,