@pushwoosh/http-client 1.4.0 → 1.4.1

package/README.md

@@ -1,6 +1,9 @@
 # Pushwoosh / Micro Frontends / Http Client
-Этот пакет является частью микрофронтендовой архитектуры.
-Предназначен для выполнения запросов к API.
+Этот пакет является частью микрофронтендовой архитектуры
+<br/>
+За основу взят проект [Single SPA](https://single-spa.js.org)
+<br/>
+Предназначен для выполнения запросов к API
 
 ## Термины
 [Аутентификация](https://auth0.com/docs/authentication) - процесс подтверждения личности пользователя
@@ -12,19 +15,23 @@
 [Сервер авторизации](https://www.rfc-editor.org/rfc/rfc6749.html#section-1.1) - сервер, выдающий токены доступа клиенту после успешной аутентификации владельца ресурса и получение авторизации
 
 ## Установка
-0.  Установить переменную окружения "NPM_TOKEN" в терминале (токен можно получить у администраторов)
-1.  Выполнить `npm ci` для установки зависимостей
+1. Сгенерировать ключи для запуска сервера в режиме HTTPS. ([Confluence](https://confluence.corp.pushwoosh.com/display/FD/HTTPS+on+localhost))
+2. Выполнить `npm ci`
 
 ## Запуск разработки
-0. Скопировать файл `.env.example` в `.env`. Удалить из него комментарии к переменным
-1. Выполнить `npm start`
+1. Скопировать файл `.env.example` в `.env`. Удалить из него комментарии к переменным
+2. Выполнить `npm start`
 
 ## Работа с библиотекой
+Библиотека собирается в формате UMD.
+<br/>
+В первую очередь предназначена для загрузки с помощью SystemJS.
+
 ### Создание экземпляра HttpClient
 При создании экземпляра класса HttpClient необходимо указать следующие параметры:
 
 ```typescript
-import { HttpClient } from './http-client';
+import { HttpClient } from '@pushwoosh/http-client';
 
 const httpClient = new HttpClient({
   errorMiddleware: (error: unknown): Promise<never> | never => {
@@ -53,7 +60,7 @@ const introspect = await httpClient.initialize(authorizationCode, authorizationS
 
 `authorizationState` - это случайная строка, сгенерированная и сохраненная клиентом перед началом сеанса, возвращается вместе с `authorizationCode`
 
-`introspect` - это данные о текущем сеансе (идентификатор пользователя, идентификатор аккаунта и т.п.), которые зашиты в `accessToken`
+`introspect` - это данные о текущем сеансе (идентификатор пользователя, идентификатор аккаунта и т.п.), которые зашиты в `access token`
 
 ### Начать сеанс
 Выполнить аутентификацию пользователя на клиенте
@@ -133,11 +140,26 @@ curl 'https://app.pushwoosh.com/entrypoint' \
 try {
   const result = httpClient.get<never, never, { some: string }>('/entrypoint', {
     withAuthorization: true,
-    withCredentials: false,
-    responseMiddleware: (response: Response): { some: string } => { // если стандартный middleware для разбора ответа от сервера не подходит
-        const jsonResponse = httpClient.baseResponseMiddleware(response);
-        const result = httpClient.baseResponseMiddleware(jsonResponse);
-        return result;
+    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) {
@@ -154,56 +176,59 @@ import { ForbiddenError, HttpClient, NotFoundError, UnauthorizedError } from './
 try {
   const result = httpClient.get<never, never, never>('/entrypoint', {
     withAuthorization: true,
-    withCredentials: false,
   });
 } catch (error: unknown) {
   if (error instanceof UnauthorizedError) {
-    // TODO: Если пользователь не авторизован...
+    // TODO: Если не авторизован...
   }
 
   if (error instanceof ForbiddenError) {
-    // TODO: Если пользователю запрещено выполнять запрос...
+    // TODO: Если запрещено выполнять запрос...
   }
 
   if (error instanceof NotFoundError) {
     // TODO: Если сервер ничего не нашел...
   }
 
-  // записываем ошибку в sentry
-  captureException(error);
+  // TODO: error capture
 }
 ```
 
+### Родительский класс для ошибок
+`HttpClientError` - Класс описывает ошибку связанную с HttpClient.
+<br/>
+HttpClientError класс является наследником Error.
+<br/>
+<b>Никогда не выбрасывается как исключение. От нее наследуются все остальные ошибки!</b>
+
 Каждая ошибка имеет свой класс:
 
 #### Ошибки связанные с самим модулем:
-`HttpClientError (extends Error)` - Класс описывает ошибку связанную с HttpClient
+`InternalError` - Класс описывающий внутреннюю ошибку HttpClient
 
-`InternalError (extends HttpClientError)` - Класс описывающий внутреннюю ошибку HttpClient
+#### Ошибки связанные с ответами от сервера:
+`BadRequestError` - Класс описывающий ошибку "Плохой запрос"
 
-#### Ошибки связанные со всеми запросами:
-`UnknownError (extends HttpClientError)` - Неизвестная ошибка HttpClient
+`UnauthorizedError` - Класс описывающий ошибку "Не авторизовано"
 
-#### Ошибки связанные с запросами:
-`BadRequestError (extends HttpClientError)` - Класс описывающий ошибку "Плохой запрос"
+`ForbiddenError` - Класс описывающий ошибку "Запрещено"
 
-`UnauthorizedError (extends HttpClientError)` - Класс описывающий ошибку "Не авторизовано"
+`NotFoundError` - Класс описывающий ошибку "Не найден"
 
-`ForbiddenError (extends HttpClientError)` - Класс описывающий ошибку "Запрещено"
+`MethodNotAllowedError` - Класс описывающий ошибку "Метод не доступен"
 
-`NotFoundError (extends HttpClientError)` - Класс описывающий ошибку "Не найден"
+`UnsupportedMediaTypeError` - Класс описывающий ошибку "Медиа формат не поддерживается сервером"
 
-`MethodNotAllowedError (extends HttpClientError)` - Класс описывающий ошибку "Метод не доступен"
-
-`UnsupportedMediaTypeError (extends HttpClientError)` - Класс описывающий ошибку "Медиа формат не поддерживается сервером"
-
-`UnprocessableEntityError (extends HttpClientError)` - Класс описывающий ошибку "Сервер не может обработать запрос"
+`UnprocessableEntityError` - Класс описывающий ошибку "Сервер не может обработать запрос"
 
 #### Ошибки связанные с работой сервера:
-`InternalServerError (extends HttpClientError)` - Класс описывающий ошибку "Внутренняя ошибка сервера"
+`InternalServerError` - Класс описывающий ошибку "Внутренняя ошибка сервера"
+
+`BadGatewayError` - Класс описывающий ошибку "Плохой шлюз"
 
-`BadGatewayError (extends HttpClientError)` - Класс описывающий ошибку "Плохой шлюз"
+`ServiceUnavailableError` - Класс описывающий ошибку "Сервис недоступен"
 
-`ServiceUnavailableError (extends HttpClientError)` - Класс описывающий ошибку "Сервис недоступен"
+`GatewayTimeoutError` - Класс описывающий ошибку "Вышло время ожидания ответа"
 
-`GatewayTimeoutError (extends HttpClientError)` - Класс описывающий ошибку "Вышло время ожидания ответа"
+#### Остальные:
+`UnknownServerError` - Класс описывает ошибку связанную с запросами к серверу, но для которой не подходит ни один из вариантов выше.