jimpex 7.0.2 → 8.0.0

package/src/services/http/apiClient.ts

@@ -0,0 +1,221 @@
+import {
+  APIClient as APIClientBase,
+  type ErrorResponse,
+  type APIClientOptions,
+  type FetchClient,
+} from '@homer0/api-utils';
+import { deepAssignWithOverwrite } from '@homer0/deep-assign';
+import { providerCreator } from '../../utils';
+import type { HTTP } from './http';
+import type { HTTPErrorClass } from '../common';
+
+export type { ErrorResponse };
+/**
+ * The required settings needed to create the an API client.
+ *
+ * @group Services/APIClient
+ */
+export type APIClientConfig = Pick<APIClientOptions, 'url' | 'endpoints'>;
+/**
+ * A dictionary of endpoints for the API client.
+ * This is declared as standalone because it needs to reference them multiple times.
+ *
+ * @group Services/APIClient
+ */
+export type EndpointsType = APIClientOptions['endpoints'];
+/**
+ * The format the settings needs to have in the application configuration in order to
+ * create a valid API client.
+ * The settings may include the endpoints dictionary in the `endpoints` property, or the
+ * gateway `property`, with `endpoints` always having priority if both exists.
+ * The reason for the `gateway` property to be valid, is in case the application also
+ * implements a {@link GatewayController}, using the same property for both things will
+ * help reduce the amount of duplicated definitions.
+ *
+ * @group Services/APIClient
+ */
+export type APIClientSettings = Omit<APIClientConfig, 'endpoints'> &
+  (
+    | {
+        endpoints: EndpointsType;
+        gateway?: EndpointsType;
+      }
+    | {
+        endpoints?: EndpointsType;
+        gateway: EndpointsType;
+      }
+  );
+/**
+ * The options to construct a {@link APIClient}.
+ *
+ * @group Services/APIClient
+ */
+export type APIClientConstructorOptions = APIClientSettings & {
+  /**
+   * A dictionary with the dependencies to inject.
+   */
+  inject: {
+    http: HTTP;
+    HTTPError: HTTPErrorClass;
+  };
+};
+/**
+ * An API client for the application to use. What makes this service special is that it
+ * formats received errors using the {@link _HTTPError} class, and as fetch client, it
+ * uses the {@link HTTP} service, allowing the application to to internally handle all the
+ * requests and responses.
+ *
+ * The only reason to use the class directly is if you want to subclass it, as you would
+ * normally just register the {@link apiClientProvider}.
+ *
+ * @group Services
+ * @group Services/APIClient
+ */
+export class APIClient extends APIClientBase {
+  /**
+   * The service that makes the requests to the API.
+   */
+  protected readonly _http: HTTP;
+  /**
+   * The class to generate possible errors in the requests.
+   */
+  protected readonly _HTTPError: HTTPErrorClass;
+  /**
+   * The configuration of the API it uses.
+   */
+  protected readonly _apiConfig: APIClientConfig;
+  /**
+   * @param options  The options to construct the class.
+   */
+  constructor({ inject: { http, HTTPError }, ...rest }: APIClientConstructorOptions) {
+    const { endpoints, gateway, url } = rest;
+    const useEndpoints = (endpoints || gateway)!;
+    const apiConfig = {
+      url,
+      endpoints: useEndpoints,
+    };
+    super({
+      ...apiConfig,
+      fetchClient: http.fetch as unknown as FetchClient,
+    });
+
+    this._http = http;
+    this._HTTPError = HTTPError;
+    this._apiConfig = deepAssignWithOverwrite({}, apiConfig);
+  }
+  /**
+   * The configuration for the API.
+   */
+  get apiConfig(): Readonly<APIClientConfig> {
+    return deepAssignWithOverwrite({}, this._apiConfig);
+  }
+  /**
+   * Tries to obtain a message from an error caused on a failed request.
+   *
+   * @param response  The response from the failed request.
+   */
+  protected _getErrorMessageFromResponse(response: unknown) {
+    const res = response as {
+      error?: string;
+      data?: {
+        message?: string;
+        error?: string;
+      };
+    };
+    if (res.error) return res.error;
+    if (res.data) {
+      if (res.data.message) return res.data.message;
+      if (res.data.error) return res.data.error;
+    }
+
+    return 'Unexpected error';
+  }
+  /**
+   * Generates an {@link _HTTPError} from the response of a failed request.
+   *
+   * @param response  The response from the failed request.
+   * @param status    The status code of the response.
+   */
+  protected override formatError<ResponseType extends ErrorResponse>(
+    response: ResponseType,
+    status: number,
+  ): Error {
+    return new this._HTTPError(this._getErrorMessageFromResponse(response), status);
+  }
+}
+/**
+ * The options for the provider creator that registers an {@link APIClient} in the
+ * container.
+ * These options allow the application to register multiple instances for different APIs.
+ *
+ * @group Services/APIClient
+ */
+export type APIClientProviderOptions = {
+  /**
+   * The name of the service that will be registered into the app.
+   *
+   * @default 'apiClient'
+   */
+  serviceName?: string;
+  /**
+   * The name of the configuration setting that has the API information.
+   *
+   * @default 'api'
+   */
+  configSetting?: string;
+  /**
+   * The class the service will instantiate. It has to extend {@link APIClient}.
+   *
+   * @default APIClient
+   */
+  clientClass?: typeof APIClient;
+};
+/**
+ * The provider creator to register an instance of {@link APIClient} on the container.
+ *
+ * @example
+ *
+ * <caption>Basic usage</caption>
+ *
+ *   // Register it on the container
+ *   container.register(apiClientProvider);
+ *   // Getting access to the service instance
+ *   const apiClient = container.get<APIClient>('apiClient');
+ *
+ * @example
+ *
+ * <caption>With custom options</caption>
+ *
+ *   container.register(
+ *     apiClientProvider({
+ *       serviceName: 'myApiClient',
+ *       configSetting: 'myApi',
+ *     }),
+ *   );
+ *
+ * @group Providers
+ * @group Services/APIClient
+ */
+export const apiClientProvider = providerCreator(
+  (options: APIClientProviderOptions = {}) =>
+    (app) => {
+      const defaultName = 'apiClient';
+      const { serviceName = defaultName, clientClass: ClientClass = APIClient } = options;
+      let { configSetting } = options;
+      if (!configSetting) {
+        configSetting = serviceName === defaultName ? 'api' : serviceName;
+      }
+
+      app.set(
+        serviceName,
+        () =>
+          new ClientClass({
+            inject: {
+              http: app.get('http'),
+              HTTPError: app.get('HTTPError'),
+            },
+            ...app.getConfig<APIClientSettings>(configSetting!),
+          }),
+      );
+    },
+);

package/src/services/http/http.ts

@@ -0,0 +1,286 @@
+import fetch, { type RequestInit, type BodyInit } from 'node-fetch';
+import urijs from 'urijs';
+import { deepAssignWithOverwrite } from '@homer0/deep-assign';
+import { provider } from '../../utils';
+import { Logger, Request, HTTPResponse } from '../../types';
+/**
+ * The options to customize the service.
+ *
+ * @group Services/HTTP
+ */
+export type HTTPOptions = {
+  /**
+   * Whether or not the service should log the requests and their responses.
+   */
+  logRequests?: boolean;
+};
+/**
+ * The options to construct a {@link HTTP}.
+ *
+ * @group Services/HTTP
+ */
+export type HTTPContructorOptions = Partial<HTTPOptions> & {
+  /**
+   * A dictionary with the dependencies to inject.
+   */
+  inject: {
+    logger: Logger;
+  };
+};
+/**
+ * The allowed formats for the body of a request.
+ *
+ * @group Services/HTTP
+ */
+export type HTTPFetchBody = string | Record<string | number, unknown> | BodyInit;
+/**
+ * The options for a request.
+ *
+ * @group Services/HTTP
+ */
+export type HTTPFetchOptions = {
+  /**
+   * The HTTP method.
+   *
+   * @default 'GET'
+   */
+  method?: string;
+  /**
+   * The headers dictionary.
+   */
+  headers?: Record<string, string>;
+  /**
+   * The body of the request.
+   */
+  body?: HTTPFetchBody;
+  /**
+   * A dictionary of query string parameters.
+   */
+  qs?: Record<string, unknown>;
+  /**
+   * A request object generated by the application. This can be used to copy information
+   * like custom headers or the IP (for the X-Forwarded-For header).
+   */
+  req?: Request;
+};
+/**
+ * The options for the method that extracts custom headers from a request.
+ *
+ * @group Services/HTTP
+ */
+export type GetCustomHeadersFromRequestOptions = {
+  /**
+   * Since the method considers all headers that start with `x-` as custom headers,
+   * setting this to `false` is the only way to exclude `x-forwarded-` headers from the
+   * list.
+   *
+   * @default false
+   */
+  includeXForwardedHeaders?: boolean;
+};
+/**
+ * A set of utilities to work with HTTP requests and responses.
+ *
+ * @group Services
+ * @group Services/HTTP
+ */
+export class HTTP {
+  /**
+   * The service used to log information in the terminal.
+   */
+  protected readonly _logger: Logger;
+  /**
+   * The service customization options.
+   */
+  protected readonly _options: HTTPOptions;
+  /**
+   * @param options  The options to construct the class.
+   */
+  constructor({ inject: { logger }, ...options }: HTTPContructorOptions) {
+    this._logger = logger;
+    this._options = deepAssignWithOverwrite(
+      {
+        logRequests: false,
+      },
+      options,
+    );
+
+    this.fetch = this.fetch.bind(this);
+  }
+  /**
+   * Makes a fetch request.
+   *
+   * @param url      The URL to fetch.
+   * @param options  The custom options for the request.
+   */
+  async fetch(url: string, options: HTTPFetchOptions = {}): Promise<HTTPResponse> {
+    let useURL = url;
+    if (options.qs) {
+      useURL = urijs(url).query(options.qs).toString();
+    }
+
+    const fetchOptions: RequestInit = {
+      method: (options.method || 'get').toUpperCase(),
+      body: options.body as BodyInit,
+    };
+
+    let defaultHeaders: Record<string, string> | undefined;
+    if (options.req) {
+      defaultHeaders = this.getCustomHeadersFromRequest(options.req);
+      const ip = this.getIPFromRequest(options.req);
+      if (ip) {
+        defaultHeaders['x-forwarded-for'] = ip;
+      }
+    }
+    const headers = {
+      ...defaultHeaders,
+      ...options.headers,
+    };
+
+    if (Object.keys(headers).length) {
+      fetchOptions.headers = this.normalizeHeaders(headers);
+    }
+
+    const { logRequests } = this._options;
+    if (logRequests) {
+      this._logRequest(useURL, fetchOptions);
+    }
+
+    const response = await fetch(useURL, fetchOptions);
+    if (logRequests) {
+      this._logResponse(response);
+    }
+
+    return response;
+  }
+  /**
+   * Tries to get the IP address from a given request.
+   *
+   * @param req  The request from which it will try to obtain the IP address.
+   */
+  getIPFromRequest(req: Request): string | undefined {
+    const headerValue = req.headers['x-forwarded-for'];
+    if (headerValue) {
+      return String(headerValue);
+    }
+
+    return req?.connection?.remoteAddress || req?.socket?.remoteAddress;
+  }
+  /**
+   * Creates a dictionary with all the custom headers a request has. By custom header it
+   * means all the headers which name start with `x-`.
+   *
+   * @param req      The request from which it will try to get the headers.
+   * @param options  The options to customize the behavior with certain headers.
+   */
+  getCustomHeadersFromRequest(
+    req: Request,
+    options: GetCustomHeadersFromRequestOptions = {},
+  ): Record<string, string> {
+    const { includeXForwardedHeaders = false } = options;
+    return Object.keys(req.headers).reduce<Record<string, string>>((acc, headerName) => {
+      if (
+        headerName.startsWith('x-') &&
+        (includeXForwardedHeaders || !headerName.startsWith('x-forwarded-'))
+      ) {
+        acc[headerName] = req.headers[headerName] as string;
+      }
+      return acc;
+    }, {});
+  }
+  /**
+   * It takes a dictionary of headers and normalize the names so each word will start with
+   * an upper case character. This is helpful in case you added custom headers and didn't
+   * care about the casing, or when copying headers from a server request, as they all
+   * come tranformed into lower case.
+   *
+   * @param headers  The dictionary of headers to normalize.
+   */
+  normalizeHeaders(headers: Record<string, string>): Record<string, string> {
+    return Object.keys(headers).reduce<Record<string, string>>((acc, name) => {
+      const newName = name
+        .split('-')
+        .map((part) => part.replace(/^(\w)/, (_, letter) => letter.toUpperCase()))
+        .join('-');
+
+      acc[newName] = headers[name]!;
+      return acc;
+    }, {});
+  }
+  /**
+   * The customization options.
+   */
+  get options(): Readonly<HTTPOptions> {
+    return deepAssignWithOverwrite({}, this._options);
+  }
+  /**
+   * Logs a request information into the terminal.
+   *
+   * @param url      The request URL.
+   * @param options  The options for the request.
+   */
+  protected _logRequest(url: string, options: RequestInit): void {
+    const { method, headers } = options;
+    const prefix = 'REQUEST> ';
+    const lines = ['--->>', `${prefix}${method} ${url}`];
+    if (headers) {
+      Object.keys(headers).forEach((header) => {
+        const value = headers[header as keyof typeof headers];
+        lines.push(`${prefix}${header}: ${value}`);
+      });
+    }
+
+    if (options.body) {
+      lines.push(`${prefix}body: "${options.body}"`);
+    }
+
+    this._logger.info(lines);
+  }
+  /**
+   * Logs a response information into the terminal.
+   *
+   * @param response  The response to log.
+   */
+  protected _logResponse(response: HTTPResponse) {
+    const prefix = 'RESPONSE> ';
+    const lines = [
+      '<<---',
+      `${prefix}${response.url}`,
+      `${prefix}status: ${response.status}`,
+    ];
+
+    response.headers.forEach((value, header) => {
+      lines.push(`${prefix}${header}: ${value}`);
+    });
+
+    this._logger.info(lines);
+  }
+}
+/**
+ * The service provider that once registered on the container will set an instance of
+ * {@link HTTP} as the `http` service. The provider also checks the `debug.logRequests`
+ * setting on the application configuration in order to enable or not the logging of
+ * requests/responses.
+ *
+ * @example
+ *
+ *   // Register it on the container
+ *   container.register(httpProvider);
+ *   // Getting access to the service instance
+ *   const http = container.get<HTTP>('http');
+ *
+ * @group Providers
+ * @group Services/HTTP
+ */
+export const httpProvider = provider((app) => {
+  app.set('http', () => {
+    const config = app.getConfig();
+    const logRequests = config.get<boolean | undefined>('debug.logRequests') === true;
+    return new HTTP({
+      inject: {
+        logger: app.get('logger'),
+      },
+      logRequests,
+    });
+  });
+});

package/src/services/http/index.ts

@@ -0,0 +1,29 @@
+import { providers } from '../../utils';
+import { apiClientProvider } from './apiClient';
+import { httpProvider } from './http';
+import { responsesBuilderProvider } from './responsesBuilder';
+/**
+ * Registers all the HTTP services on the container.
+ *
+ * - {@link APIClient | apiClient}
+ * - {@link HTTP | http}
+ * - {@link ResponsesBuilder | responsesBuilder}
+ *
+ * @example
+ *
+ *   // Register the collection on the container
+ *   container.register(httpServicesProvider);
+ *   // Getting access to one the services instance
+ *   const apiClient = container.get<APIClient>('apiClient');
+ *
+ * @group Providers
+ */
+export const httpServicesProvider = providers({
+  apiClientProvider,
+  httpProvider,
+  responsesBuilderProvider,
+});
+
+export * from './apiClient';
+export * from './http';
+export * from './responsesBuilder';