@pushwoosh/http-client 1.4.2 → 1.5.0

package/README.md

@@ -1,234 +1,304 @@
 # Pushwoosh / Micro Frontends / Http Client
 Этот пакет является частью микрофронтендовой архитектуры
 <br/>
-За основу взят проект [Single SPA](https://single-spa.js.org)
-<br/>
-Предназначен для выполнения запросов к API
-
-## Термины
-[Аутентификация](https://auth0.com/docs/authentication) - процесс подтверждения личности пользователя
-
-[Авторизация](https://auth0.com/docs/authorization) - процесс проверки доступа к защищенным ресурсам
-
-[Клиент](https://www.rfc-editor.org/rfc/rfc6749.html#section-1.1) - приложение запрашивающее защищенные ресурсы от имени пользователя
-
-[Сервер авторизации](https://www.rfc-editor.org/rfc/rfc6749.html#section-1.1) - сервер, выдающий токены доступа клиенту после успешной аутентификации владельца ресурса и получение авторизации
+Предназначен для выполнения запросов к API с использованием OAuth2 протокола
 
 ## Установка
-1. Сгенерировать ключи для запуска сервера в режиме HTTPS. ([Confluence](https://confluence.corp.pushwoosh.com/display/FD/HTTPS+on+localhost))
+1. Сгенерировать ключи для запуска сервера в режиме
+   HTTPS ([Confluence](https://confluence.corp.pushwoosh.com/display/FD/HTTPS+on+localhost))
 2. Выполнить `npm ci`
 
 ## Запуск разработки
-1. Скопировать файл `.env.example` в `.env`. Удалить из него комментарии к переменным
+1. Скопировать файл `.env.example` в `.env`
 2. Выполнить `npm start`
 
-## Работа с библиотекой
-Библиотека собирается в формате UMD.
-<br/>
-В первую очередь предназначена для загрузки с помощью SystemJS.
+## Использование
+Работу с Http Client можно разделить на несколько условных частей:
+
+1. Создание экземпляра
+2. Авторизация (этот шаг может быть пропущен)
+3. Выполнение запросов
+4. Обработка ответов
+5. Обработка ошибок
 
-### Создание экземпляра HttpClient
-При создании экземпляра класса HttpClient необходимо указать следующие параметры:
+### Создание экземпляра
+Первым делом нужно создать экземпляр HttpClient
 
 ```typescript
-import { HttpClient } from '@pushwoosh/http-client';
+const httpClient = new HttpClient(history, config);
+```
 
-const httpClient = new HttpClient({
-  errorMiddleware: (error: unknown): Promise<never> | never => {
-      // какие-то действия над ошибками
-  },
+Где:
+<br/>
+<strong>history</strong> - API для работы с навигацией
+<br/>
+<strong>config</strong> - конфигурация Http Client
+<br/>
+<strong>config.defaultResponseMiddleware</strong> - обработчик ответа от сервера по умолчанию (см. раздел обработка ответов от сервера)
+<br/>
+<strong>config.defaultErrorMiddleware</strong> - обработчик ошибок по умолчанию (см. раздел обработка ошибок)
+
+```typescript
+import { createBrowserHistory } from 'history';
+import { defaultErrorMiddleware, defaultResponseMiddleware, HttpClient } from '@pushwoosh/http-client';
+
+// создаем API для работы с навигацией
+const history = createBrowserHistory();
+
+// формируем конфигурацию Http Client
+const config = {
+  // обязательное поле: описывает адреса для выполнения внутренних запросов HttpClient к серверу авторизации
+  // для более подробной инфорации смотри https://www.rfc-editor.org/rfc/rfc6749.html#section-1.1 - authorization server
   urls: {
-      authorize: 'https://sso.pushwoosh.com/authorize', // адрес старта сеанса
-      token: 'https://sso.pushwoosh.com/token', // адрес для получения или обновления пары токенов для авторизации в приватных API
-      logout: 'https://sso.pushwoosh.com/logout', // адрес для завершения сеанса
+    // обязательное поле: адрес для получения authorization code и authorization state
+    // для более подробноей информации смотри https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1.1 
+    authorize: 'https://sso.pushwoosh.com/authorize',
+    // обязательное поле: адрес для получения access token и refresh token
+    token: 'https://sso.pushwoosh.com/token',
+    // обязательное поле: адрес для завершения сессии
+    logout: 'https://sso.pushwoosh.com/logout',
   },
-  clientId: 'APP_FRONT', // уникальный идентификатор клиента (связан с доменом)
+  // обязательное поле: идентификатор клиента, свзязан с сервером SSO, зависит от домена на котором работает HttpClient
+  // для более подробной инфорации смотри https://www.rfc-editor.org/rfc/rfc6749.html#section-1.1 - client
+  clientId: 'APP_FRONT',
+  // обязательное поле: область ограничений на работу с защищенными ресурсами
+  // для более подробной инфорации смотри https://www.rfc-editor.org/rfc/rfc6749.html#section-1.1 - resource server
+  scope: 'cp-pushwoosh customer-journey',
+  // обязательное поле: параметры куки для сохранения authorization state и url before authorize
   cookie: {
-    domain: '.pushwoosh.com', // на какой домен будут выписываться cookies
+    // обязательное поле: определяет домен на котором будут доступны куки
+    domain: '.pushwoosh.com',
+    // определяет время жизни кук
+    expires: 300,
+    // определяет путь, где будут доступны куки
+    path: '/',
+    // определяет будут ли передаваться куки только по https протоколу
+    secure: true,
+    // определяет при каких условиях куки будут отправлятся на сервер при выполнении кроссдоменных запросов 
+    sameSite: 'none',
   },
-})
+  // обязательное поле: бызовый обработчик ответов от сервера
+  basicResponseMiddleware: defaultResponseMiddleware,
+  // обязательное поле: базовый обработчик ошибкок при выполнении запросов
+  basicErrorMiddleware: defaultErrorMiddleware,
+};
 ```
 
-### Инициализация экземпляра HttpClient
-Экземпляр класса HttpClient необходимо инициализировать, для получения информации аутентифицирован ли пользователь на клиенте
+### Авторизация
+Этот шаг может быть пропущен, если access token получается другим способом.
+<br/>
+Если требуется произвести авторизацию клиента с помощью SSO, то нам нужно выполнить 2 действия:
+<br/>
+
+1. Получить Basic Authorization путем перехода на сервер авторизации и возвращения обратно с authorization code и authorization state
+   ```typescript
+   await httpClient.login();
+   ```
+2. Получить Bearer Authorization путем выполнения запроса к серверу авторизации и получения access token и refresh token с помощью authorization code
+   ```typescript
+   const introspect = await httpClient.authorize(authorization);
+   ```
 
+Полный пример выполнения авторизации клиента:
 ```typescript
-const introspect = await httpClient.initialize(authorizationCode, authorizationState);
+// получаем authorization code и authorization state из строки браузера
+const query = parse(window.location.search.slice(1));
+const authorizationCode = typeof query.code === 'string' ? query.code : null;
+const authorizationState = typeof query.state === 'string' ? query.state : null;
+const authorization = authorizationCode && authorizationState
+  ? { code: authorizationCode, state: authorizationState }
+  : null;
+
+// выполняем авторизацию
+if (authorization) {
+  const introspect = await httpClient.authorize(authorization);
+  if (!introspect) {
+    await httpClient.login();
+    return;
+  }
+}
 ```
 
-`authorizationCode` - это код авторизации переданный со стороны `сервера авторизации`
-
-`authorizationState` - это случайная строка, сгенерированная и сохраненная клиентом перед началом сеанса, возвращается вместе с `authorizationCode`
-
-`introspect` - это данные о текущем сеансе (идентификатор пользователя, идентификатор аккаунта и т.п.), которые зашиты в `access token`
-
-### Начать сеанс
-Выполнить аутентификацию пользователя на клиенте
-
+### Выполнение запросов:
+Для выполнения запросов можно использовать следующий метод:
 ```typescript
-await httpClient.login();
-```
+import { defaultErrorMiddleware } from './http-client.utilities';
 
-### Завершить сеанс
-Завершить сеанс клиента
+type Result = {
+  readonly data1: string;
+  readonly data2: number;
+};
 
-```typescript
-await httpClient.logout();
-```
+type Params = {
+  readonly param1: string;
+  readonly param2: number;
+}
 
-### Выполнение запросов
+type Query = {
+  readonly query1: string;
+  readonly query2: number;
+}
 
-#### Базовая конфигурация:
+type Body = {
+  readonly body1: string;
+  readonly body2: number;
+}
 
-Запрос:
-```
-curl 'https://app.pushwoosh.com/entrypoint/XXXXX-XXXXX?query1=0' \
-  -H 'accept: application/json, text/plain, */*' \
-  -H 'content-type: application/json' \
-  --data-raw '{"body1":true}' \
+const url = '/entrypoint/:param1/:param2';
+const method = Method.POST;
+const options = {
+  // определяет заголовки, которые будут отправлены вместе с запросом
+  headers: {
+    'Some-Header': 'Some-Value',
+  },
+  // параметры для заполнения адреса запроса
+  params: {
+    param1: 'value-param',
+    param2: 1,
+  },
+  // параметры запроса
+  query: {
+    query1: 'value-query',
+    query2: 2,
+  },
+  // тело запроса
+  body: {
+    body1: 'value-body',
+    body2: 3,
+  },
+  // обязательное поле: определяет требуется ли передавать данные об авторизации
+  withAuthorization: true,
+  // определяет требуется ли отправлять заголовки в кроссдоменных запросах
+  withCredentials: false,
+  // определяет какой обработчик ответа будет использован (см. разедл обработка ответа от сервера)
+  responseMiddleware: defaultResponseMiddleware,
+  // определяет какой обработчик ошибок будет использован (см. разедл обработка ошибок)
+  errorMiddleware: defaultErrorMiddleware,
+};
+
+const { data1, data2 } = await httpClient.request<Method.POST, Result, Params, Query, Body>(url, method, options);
 ```
-Можно выполнить следующей конструкцией:
+
+Он эквивалентен следующему запросу:
 ```
-try {
-    const response = httpClient.request<'POST', { param1: string }, { query1: number }, { body1: boolean }, { result1: string, result2: number, result3: boolean }>('/entrypoint/:param1', {
-      method: 'POST',
-      params: {
-        param1: 'XXXXX-XXXXX',
-      },
-      query: {
-        query1: 0,
-      },
-      body: {
-        body1: true,
-      },
-      withAuthorization: false,
-      withCredentials: false,
-    });
-  } catch (error: unknown) {
-    // TODO: error capture
-  }
+curl -XPOST 'https://pushwoosh.com/entrypoint/value-param/1?query1=value-query&query2=2' -H "Some-Header: Some-Value" -H "Authorization: Bearer ..." -d '{
+  "body1": "value-body",
+  "body2": 3
+}'
 ```
 
-`method` - тип запроса (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`)
-
-`params` - параметры, которые будут подставлены в шаблон `URL`
-
-`query` - параметры, которые будут преобразованы к `Query String`
-
-`body` - параметры, которые будут преобразованы к `Request Payload` (недоступен для `GET`)
-
-`withAuthorization` - передавать заголовок `Authorization` в заголовке
-
-`withCredentials` - передавать идентификационные данные в кросс доменных запросах
-
-`response` - ответ от сервера:
+Также существуют упрощенные варианты запросов:
 
+##### GET
 ```typescript
-type Response<R extends Result> = | ResponseFailure | ResponseSuccess<R>;
+const result = httpClient.get<Result, Params, Query>(url, options);
 ```
 
-#### GET, POST, PUT, UPDATE, DELETE запросы
-Все запросы имеют упрощенную структуру с указанием типа запроса:
-
-```
-curl 'https://app.pushwoosh.com/entrypoint' \
-  -H 'accept: application/json, text/plain, */*' \
-  -H 'authorization: Bearer SOME-ACCESS-TOKEN' \
-```
-Можно выполнить следующей конструкцией:
+##### POST
 ```typescript
-try {
-  const result = httpClient.get<never, never, { some: string }>('/entrypoint', {
-    withAuthorization: true,
-    responseMiddleware: (response: Response<{some: string}>): { some: string } => {
-      // если стандартный middleware для разбора ответа от сервера не подходит
-      // например когда ответ от сервера всегда 200, а коды ошибок зашиты в самом ответе.
-      // {
-      //   status: 200,
-      //   message: 'Ok',
-      //   result: {
-      //     status: 200,
-      //     message: 'Ok',
-      //     response: {
-      //       some: 'some-string',
-      //     },
-      //   },
-      // }
-      const jsonResponse = httpClient.baseResponseMiddleware(response);
-      if (jsonResponse.status !== 200) {
-        // map jsonResponse error to HttpClient error and throw it.
-      }
-
-      return jsonResponse.result;
-    },
-  });
-} catch (error: unknown) {
-  // TODO: error capture
-}
+const result = httpClient.post<Result, Params, Query, Body>(url, options);
 ```
-В данном примере приходит сразу `result`, а если http запрос вернул `response.status` >= `400`, то произойдет выброс исключения.
-
-## Обработка ошибок:
 
+##### PUT
 ```typescript
-import { ForbiddenError, HttpClient, NotFoundError, UnauthorizedError } from './http-client.errors';
-
-try {
-  const result = httpClient.get<never, never, never>('/entrypoint', {
-    withAuthorization: true,
-  });
-} catch (error: unknown) {
-  if (error instanceof UnauthorizedError) {
-    // TODO: Если не авторизован...
-  }
-
-  if (error instanceof ForbiddenError) {
-    // TODO: Если запрещено выполнять запрос...
-  }
+const result = httpClient.put<Result, Params, Query, Body>(url, options);
+```
 
-  if (error instanceof NotFoundError) {
-    // TODO: Если сервер ничего не нашел...
-  }
+##### PATCH
+```typescript
+const result = httpClient.patch<Result, Params, Query, Body>(url, options);
+```
 
-  // TODO: error capture
-}
+##### DELETE
+```typescript
+const result = httpClient.delete<Result, Params, Query, Body>(url, options);
 ```
 
-### Родительский класс для ошибок
-`HttpClientError` - Класс описывает ошибку связанную с HttpClient.
+### Обработка ответов от сервера
+Так как ответ от сервера не стандартизирован, то при обращении к разным эндпоинтам может потребоваться своя валидация и парсинг.
 <br/>
-HttpClientError класс является наследником Error.
+Для этого в каждом запросе можно указать свой обработчик запроса.
 <br/>
-<b>Никогда не выбрасывается как исключение. От нее наследуются все остальные ошибки!</b>
-
-Каждая ошибка имеет свой класс:
-
-#### Ошибки связанные с самим модулем:
-`InternalError` - Класс описывающий внутреннюю ошибку HttpClient
-
-#### Ошибки связанные с ответами от сервера:
-`BadRequestError` - Класс описывающий ошибку "Плохой запрос"
-
-`UnauthorizedError` - Класс описывающий ошибку "Не авторизовано"
-
-`ForbiddenError` - Класс описывающий ошибку "Запрещено"
-
-`NotFoundError` - Класс описывающий ошибку "Не найден"
-
-`MethodNotAllowedError` - Класс описывающий ошибку "Метод не доступен"
-
-`UnsupportedMediaTypeError` - Класс описывающий ошибку "Медиа формат не поддерживается сервером"
+Например, если ответ от сервера всегда 200, а внутри него лежит JSON с данными, то можно поступить следующим образом:
 
-`UnprocessableEntityError` - Класс описывающий ошибку "Сервер не может обработать запрос"
-
-#### Ошибки связанные с работой сервера:
-`InternalServerError` - Класс описывающий ошибку "Внутренняя ошибка сервера"
+```typescript
+type Result = {
+  readonly data1: string;
+  readonly data2: number;
+};
+
+type JSONResponse = {
+  readonly result: Result;
+  readonly code: number;
+  readonly message: string;
+};
+
+const { data1, data2 } = await httpClient.post<Result, never, never, never>('/entrypoint', {
+  withAuthorization: true,
+  responseMiddleware: (response) => {
+    const jsonResponse = defaultResponseMiddleware<JSONResponse>(response);
+    if (jsonResponse.code !== 200) {
+      switch (jsonResponse.code) {
+        case 210:
+        case 401:
+          throw new UnauthorizedError(jsonResponse.message, response.details);
+        default:
+          throw new UntiledError(jsonResponse.message, jsonResponse.code, response.details);
+      }
+    }
 
-`BadGatewayError` - Класс описывающий ошибку "Плохой шлюз"
+    return jsonResponse.result;
+  },
+});
+```
 
-`ServiceUnavailableError` - Класс описывающий ошибку "Сервис недоступен"
+При обработке ответа от сервера очень важно корректно указывать ошибки, так как:
+1. Если при обработке ответа от сервера будет кинуто исключение UnauthorizedError, то HttpClient попробует обновить access token м выполнить запрос повторно
+2. Настраивается глобальный обработчик ошибок, который при возникновении тех или иных ситуаций их обрабатывает
 
-`GatewayTimeoutError` - Класс описывающий ошибку "Вышло время ожидания ответа"
+### Обработка ошибок
+Если в момент выполнения запроса происходит ошибка, то в первую очередь ее пробует обработать basicErrorMiddleware (если для конкретного запроса он не заменен на свой обработчик ошибок)
+```typescript
+import { ForbiddenError, HttpClientError, UnauthorizedError } from './http-client.errors';
+
+const httpClient = new HttpClient(history, {
+  basicErrorMiddleware: async (error: unknown): Promise<never> => {
+    // если клиент не авторизован и пытается выполнить запрос к приватным данным, то пробуем его авторизовать
+    if (error instanceof UnauthorizedError) {
+      await httpClient.logout();
+      await httpClient.login();
+    }
+    
+    throw error;
+  },
+});
+```
 
-#### Остальные:
-`UnknownServerError` - Класс описывает ошибку связанную с запросами к серверу, но для которой не подходит ни один из вариантов выше.
+Если ошибка попадает под список обрабатываемых, то Http Client ее обработает сам, если нет, она продолжит всплытие и ее можно будет обработать на месте.
+
+#### Ошибки:
+
+Все ошибки наследуются от родительского класса HttpClientError. Существуют следующие ошибки:
+
+1. HttpClientError:
+   1. LogicError - ошибка в логике самого Http Client
+   2. ClassifiedError - категоризированная ошибка, никогда не используется как отдельный экземпляр, от нее наследуются все остальные ошибки.
+       1. UntiledError - ошибка не попавшая ни под одну из категорий ниже
+       2. BadRequestError - некорректный запрос (сервер не может обработать запрос из-за некорректного синтаксиса)
+       3. UnauthorizedError - не авторизован / некорректная авторизация
+       4. ForbiddenError - запрещено для выполнения (permissions)
+       5. NotFoundError - не найдено
+       6. MethodNotAllowedError - не доступно для выполнения (restrictions)
+       7. PayloadTooLargeError - слишком большой запрос
+       8. UnsupportedMediaTypeError - неподдерживаемое тип медиа
+       9. UnprocessableEntityError - сервер понял запрос, но не смог его обработать из-за логических ошибок
+       10. TooManyRequestsError - слишком много запросов
+       11. InternalServerError
+       12. NotImplementedError
+       13. BadGatewayError
+       14. ServiceUnavailableError
+       15. GatewayTimeoutError
+
+Нужно понимать, что API поддерживают не все из приведенных выше ошибок или наоборот ошибок может не хватать
+<br/>
+Тут нужно придерживаться именно логики вызова этих ошибок и приводить разношерстный API к единому виду обработки

package/babel.config.js

@@ -0,0 +1,24 @@
+module.exports = (api) => {
+  api.cache.using(() => process.env.NODE_ENV);
+
+  return {
+    presets: [
+      [
+        '@babel/preset-env',
+        {
+          modules: false,
+          corejs: 3,
+          useBuiltIns: 'entry',
+        },
+      ],
+    ],
+    plugins: [
+      [
+        '@babel/plugin-transform-runtime',
+        {
+          corejs: 3,
+        },
+      ],
+    ],
+  };
+};

package/jest.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  preset: 'ts-jest',
+};

package/package.json

@@ -1,74 +1,68 @@
 {
   "name": "@pushwoosh/http-client",
-  "version": "1.4.2",
-  "license": "MIT",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
   "scripts": {
     "start": "npm run development",
     "build": "npm run production",
     "development": "cross-env NODE_ENV=development webpack-dev-server --config webpack.development.config.js",
     "production": "cross-env NODE_ENV=production webpack --config webpack.production.config.js",
-    "check": "npm run check:lint && npm run check:types && npm run check:tests",
-    "check:lint": "echo \"Run check:lint\" && eslint .",
+    "check": "npm run check:lint && npm run check:tests && npm run check:types",
+    "check:lint": "echo \"Run check:lint\" && eslint",
     "check:tests": "echo \"Run check:tests\" && jest --passWithNoTests",
     "check:types": "echo \"Run check:types\" && tsc --project tsconfig.json --noEmit"
   },
   "pre-commit": "check",
   "dependencies": {
-    "@babel/runtime-corejs3": "^7.16.5",
-    "core-js": "^3.20.0",
+    "@babel/runtime-corejs3": "^7.17.2",
+    "axios": "^0.25.0",
+    "core-js": "^3.21.0",
     "js-cookie": "^3.0.1",
     "jwt-decode": "^3.1.2",
     "path-to-regexp": "^6.2.0",
     "qs": "^6.10.3"
   },
   "devDependencies": {
-    "@babel/core": "^7.16.5",
-    "@babel/plugin-transform-runtime": "^7.16.5",
-    "@babel/preset-env": "^7.16.5",
-    "@types/jest": "^26.0.24",
+    "@babel/core": "^7.17.2",
+    "@babel/plugin-transform-runtime": "^7.17.0",
+    "@babel/preset-env": "^7.16.11",
+    "@types/jest": "^27.4.0",
     "@types/webpack-env": "^1.16.3",
-    "@typescript-eslint/eslint-plugin": "^4.33.0",
-    "@typescript-eslint/parser": "^4.33.0",
+    "@typescript-eslint/eslint-plugin": "^5.11.0",
+    "@typescript-eslint/parser": "^5.11.0",
     "babel-loader": "^8.2.3",
-    "clean-webpack-plugin": "^3.0.0",
+    "clean-webpack-plugin": "^4.0.0",
     "cross-env": "^7.0.3",
-    "dotenv": "^10.0.0",
-    "eslint": "^7.32.0",
-    "eslint-config-airbnb": "^18.2.1",
-    "eslint-config-airbnb-typescript": "^14.0.2",
-    "eslint-import-resolver-alias": "^1.1.2",
-    "eslint-plugin-compat": "^4.0.0",
-    "eslint-plugin-import": "^2.25.3",
+    "dotenv": "^16.0.0",
+    "eslint": "^8.8.0",
+    "eslint-config-airbnb": "^19.0.4",
+    "eslint-config-airbnb-typescript": "^16.1.0",
+    "eslint-plugin-compat": "^4.0.2",
+    "eslint-plugin-import": "^2.25.4",
     "eslint-plugin-jsx-a11y": "^6.5.1",
-    "eslint-plugin-react": "^7.27.1",
+    "eslint-plugin-react": "^7.28.0",
     "eslint-plugin-react-hooks": "^4.3.0",
-    "jest": "^26.6.3",
+    "jest": "^27.5.1",
     "pre-commit": "^1.2.2",
-    "terser-webpack-plugin": "^4.2.3",
-    "ts-jest": "^26.5.6",
-    "ts-loader": "^8.3.0",
-    "typescript": "^4.5.4",
-    "unused-files-webpack-plugin": "^3.4.0",
-    "webpack": "^4.46.0",
-    "webpack-cli": "^3.3.12",
-    "webpack-dev-server": "^3.11.3",
+    "terser-webpack-plugin": "^5.3.1",
+    "ts-jest": "^27.1.3",
+    "ts-loader": "^9.2.6",
+    "typescript": "^4.5.5",
+    "webpack": "^5.68.0",
+    "webpack-cli": "^4.9.2",
+    "webpack-dev-server": "^4.7.4",
     "webpack-merge": "^5.8.0"
   },
   "peerDependencies": {
-    "@types/history": "^4.7.10",
+    "@types/history": "^4.7.11",
     "@types/js-cookie": "^3.0.1",
     "@types/qs": "^6.9.7",
-    "axios": "^0.24.0",
     "history": "^4.10.1",
     "tslib": "^2.3.1"
   },
   "engines": {
-    "node": ">= 16",
-    "npm": ">= 7"
-  }
+    "node": ">=16.0.0",
+    "npm": ">=7.0.0"
+  },
+  "version": "1.5.0"
 }