@pushwoosh/http-client 1.0.0

package/README.md

@@ -0,0 +1,201 @@
+# Pushwoosh / Micro Frontends / Http Client
+Этот пакет является частью микрофронтендовой архитектуры.
+Предназначен для выполнения запросов к 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) - сервер, выдающий токены доступа клиенту после успешной аутентификации владельца ресурса и получение авторизации
+
+## Установка
+0.  Установить переменную окружения "NPM_TOKEN" в терминале (токен можно получить у администраторов)
+1.  Выполнить `npm ci` для установки зависимостей
+
+## Запуск разработки
+0. Скопировать файл `.env.example` в `.env`. Удалить из него комментарии к переменным
+1. Выполнить `npm start`
+
+## Работа с библиотекой
+### Создание экземпляра HttpClient
+При создании экземпляра класса HttpClient необходимо указать следующие параметры:
+
+```typescript
+import { HttpClient } from './http-client';
+
+const httpClient = new HttpClient({
+  urls: {
+      authorize: 'https://sso.pushwoosh.com/authorize', // адрес старта сеанса
+      token: 'https://sso.pushwoosh.com/token', // адрес для получения или обновления пары токенов для авторизации в приватных API
+      logout: 'https://sso.pushwoosh.com/logout', // адрес для завершения сеанса
+  },
+  clientId: 'APP_FRONT', // уникальный идентификатор клиента (связан с доменом)
+})
+```
+
+### Инициализация экземпляра HttpClient
+Экземпляр класса HttpClient необходимо инициализировать, для получения информации аутентифицирован ли пользователь на клиенте
+
+```typescript
+const introspect = await httpClient.initialize(authorizationCode, authorizationState);
+```
+
+`authorizationCode` - это код авторизации переданный со стороны `сервера авторизации`
+
+`authorizationState` - это случайная строка, сгенерированная и сохраненная клиентом перед началом сеанса, возвращается вместе с `authorizationCode`
+
+`introspect` - это данные о текущем сеансе (идентификатор пользователя, идентификатор аккаунта и т.п.), которые зашиты в `accessToken`
+
+### Начать сеанс
+Выполнить аутентификацию пользователя на клиенте
+
+```typescript
+await httpClient.login();
+```
+
+### Завершить сеанс
+Завершить сеанс клиента
+
+```typescript
+await httpClient.logout();
+```
+
+### Выполнение запросов
+
+#### Базовая конфигурация:
+
+Запрос:
+```
+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}' \
+```
+Можно выполнить следующей конструкцией:
+```
+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
+  }
+```
+
+`method` - тип запроса (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`)
+
+`params` - параметры, которые будут подставлены в шаблон `URL`
+
+`query` - параметры, которые будут преобразованы к `Query String`
+
+`body` - параметры, которые будут преобразованы к `Request Payload` (недоступен для `GET`)
+
+`withAuthorization` - передавать заголовок `Authorization` в заголовке
+
+`withCredentials` - передавать идентификационные данные в кросс доменных запросах
+
+`response` - ответ от сервера:
+```typescript
+type Response<R extends Result> = {
+  readonly result: R;
+  readonly status: number;
+  readonly message: string;
+};
+```
+
+#### GET, POST, PUT, UPDATE, DELETE запросы
+Все запросы имеют упрощенную структуру с указанием типа запроса:
+
+```
+curl 'https://app.pushwoosh.com/entrypoint' \
+  -H 'accept: application/json, text/plain, */*' \
+  -H 'authorization: Bearer SOME-ACCESS-TOKEN' \
+```
+Можно выполнить следующей конструкцией:
+```typescript
+try {
+  const result = httpClient.get<never, never, never>('/entrypoint', {
+    withAuthorization: true,
+    withCredentials: false,
+  });
+} catch (error: unknown) {
+  // TODO: error capture
+}
+```
+В данном примере приходит сразу `result`, а если http запрос вернул `response.status` >= `400`, то произойдет выброс исключения.
+
+## Обработка ошибок:
+
+```typescript
+import { ForbiddenError, HttpClient, NotFoundError, UnauthorizedError } from './http-client.errors';
+
+try {
+  const result = httpClient.get<never, never, never>('/entrypoint', {
+    withAuthorization: true,
+    withCredentials: false,
+  });
+} catch (error: unknown) {
+  if (error instanceof UnauthorizedError) {
+    // TODO: Если пользователь не авторизован...
+  }
+
+  if (error instanceof ForbiddenError) {
+    // TODO: Если пользователю запрещено выполнять запрос...
+  }
+
+  if (error instanceof NotFoundError) {
+    // TODO: Если сервер ничего не нашел...
+  }
+
+  // записываем ошибку в sentry
+  captureException(error);
+}
+```
+
+Каждая ошибка имеет свой класс:
+
+#### Ошибки связанные с самим модулем:
+`HttpClientError (extends Error)` - Класс описывает ошибку связанную с HttpClient
+
+`InternalError (extends HttpClientError)` - Класс описывающий внутреннюю ошибку HttpClient
+
+#### Ошибки связанные со всеми запросами:
+`UnknownError (extends HttpClientError)` - Неизвестная ошибка HttpClient
+
+#### Ошибки связанные с запросами:
+`BadRequestError (extends HttpClientError)` - Класс описывающий ошибку "Плохой запрос"
+
+`UnauthorizedError (extends HttpClientError)` - Класс описывающий ошибку "Не авторизовано"
+
+`ForbiddenError (extends HttpClientError)` - Класс описывающий ошибку "Запрещено"
+
+`NotFoundError (extends HttpClientError)` - Класс описывающий ошибку "Не найден"
+
+`MethodNotAllowedError (extends HttpClientError)` - Класс описывающий ошибку "Метод не доступен"
+
+`UnsupportedMediaTypeError (extends HttpClientError)` - Класс описывающий ошибку "Медиа формат не поддерживается сервером"
+
+`UnprocessableEntityError (extends HttpClientError)` - Класс описывающий ошибку "Сервер не может обработать запрос"
+
+#### Ошибки связанные с работой сервера:
+`InternalServerError (extends HttpClientError)` - Класс описывающий ошибку "Внутренняя ошибка сервера"
+
+`BadGatewayError (extends HttpClientError)` - Класс описывающий ошибку "Плохой шлюз"
+
+`ServiceUnavailableError (extends HttpClientError)` - Класс описывающий ошибку "Сервис недоступен"
+
+`GatewayTimeoutError (extends HttpClientError)` - Класс описывающий ошибку "Вышло время ожидания ответа"

package/lib/http-client.d.ts

@@ -0,0 +1,169 @@
+import { Body, Config, CookieOptions, DeleteOptions, GetOptions, Introspect, Method, Options, Params, PatchOptions, PostOptions, PutOptions, Query, Response, Result } from './http-client.types';
+export declare class HttpClient<I extends Introspect = Introspect> {
+    /**
+     * Имя куки в которой будет сохранена случайная строка для проверки ответа авторизации
+     */
+    private static STORIED_AUTHORIZATION_STATE_COOKIE_NAME;
+    /**
+     * Имя куки в которой будет сохранен текущий адрес страницы
+     */
+    private static STORIED_URL_COOKIE_NAME;
+    /**
+     * Параметры конфигурации
+     */
+    private readonly config;
+    /**
+     * Параметры куки
+     */
+    private readonly cookieOptions;
+    /**
+     * Токен доступа
+     */
+    private accessToken;
+    /**
+     * Токен обновления
+     */
+    private refreshToken;
+    /**
+     * Происходит ли сейчас обновление токенов
+     */
+    private isRefreshing;
+    /**
+     * Был ли установлен токен доступа вручную
+     */
+    private isAccessTokenSetManual;
+    constructor(config: Config, cookieOptions?: CookieOptions);
+    /**
+     * Разобрать ответ от сервера и вернуть результат выполнения запроса
+     *
+     * @param { Response<*> } response - ответ от сервера в формате Axios
+     */
+    static parseResponse<R extends Result>(response: Response<R>): R;
+    /**
+     * Проверить наличие авторизации
+     */
+    private guardAuthorization;
+    /**
+     * Обновить токены
+     * Для более подробной информации: RFC 6749 https://www.rfc-editor.org/rfc/rfc6749.html
+     *
+     * @param { UpdateTokensPairQuery } query - параметры запроса для обновления токенов
+     */
+    private updateTokensPair;
+    /**
+     * Обновить токены с помощью кода авторизации
+     * Для более подробной информации: RFC 6749 https://www.rfc-editor.org/rfc/rfc6749.html#section-4.1.3
+     *
+     * @param { string } authorizationCode - код авторизации, полученный от сервера авторизации
+     */
+    private updateTokensPairByAuthorizationCode;
+    /**
+     * Обновить токены с помощью токена обновления
+     * Для более подробной информации: RFC 6749 https://www.rfc-editor.org/rfc/rfc6749.html#section-6
+     *
+     * @param { string } refreshToken - токен обновления, полученный от сервера авторизации
+     * @param { Introspect } introspect - содержимое токена доступа
+     */
+    private updateTokensPairByRefreshToken;
+    /**
+     * Инициализировать модуль, если передан authorizationCode и authorizationState будет выполнена попытка обновить токены
+     *
+     * @param { string } authorizationCode - код авторизации, полученный от сервера авторизации
+     * @param { string } authorizationState - уникальная строка, переданная клиентом серверу при авторизации, полученная от сервера авторизации
+     */
+    initialize(authorizationCode: string | null, authorizationState: string | null): Promise<I | null>;
+    /**
+     * Выполнить аутентификацию пользователя
+     */
+    login(): Promise<void>;
+    /**
+     * Завершить сессию
+     */
+    logout(): Promise<void>;
+    /**
+     * Временный костыль, чтобы установить токен доступа из сессии
+     */
+    setAccessToken(accessToken: string): void;
+    /**
+     * Получить токен доступа, если время жизни токена закончилось, будет осуществлена попытка обновить токен
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Выполнить запрос на сервер
+     *
+     * Дженерик:
+     * Method - тип запроса
+     * Placeholders - параметры, которые будут подставлены в шаблон пути
+     * Query - параметры, которые будут преобразованы в строку запроса
+     * Body - тело запроса (never для GET)
+     * Result - ожидаемый результат выполнения запроса
+     *
+     * @param { string } url - адрес запроса
+     * @param { Options<Method, Params, Query, Body> } options - параметры запроса
+     */
+    request<M extends Method, P extends Params, Q extends Query, B extends Body, R extends Result>(url: string, options: Options<M, P, Q, B>): Promise<Response<R>>;
+    /**
+     * Выполнить GET запрос на сервер
+     *
+     * Дженерик:
+     * Params - параметры, которые будут подставлены в шаблон пути
+     * Query - параметры, которые будут преобразованы в строку запроса
+     * Result - ожидаемый результат выполнения запроса
+     *
+     * @param { string } url - адрес запроса
+     * @param { GetOptions<Params, Query> } options - параметры GET запроса
+     */
+    get<P extends Params, Q extends Query, R extends Result>(url: string, options: GetOptions<P, Q>): Promise<R>;
+    /**
+     * Выполнить POST запрос на сервер
+     *
+     * Дженерик:
+     * Params - параметры, которые будут подставлены в шаблон пути
+     * Query - параметры, которые будут преобразованы в строку запроса
+     * Body - тело запроса
+     * Result - ожидаемый результат выполнения запроса
+     *
+     * @param { string } url - адрес запроса
+     * @param { PostOptions<Params, Query, Body> } options - параметры POST запроса
+     */
+    post<P extends Params, Q extends Query, B extends Body, R extends Result>(url: string, options: PostOptions<P, Q, B>): Promise<R>;
+    /**
+     * Выполнить PUT запрос на сервер
+     *
+     * Дженерик:
+     * Params - параметры, которые будут подставлены в шаблон пути
+     * Query - параметры, которые будут преобразованы в строку запроса
+     * Body - тело запроса
+     * Result - ожидаемый результат выполнения запроса
+     *
+     * @param { string } url - адрес запроса
+     * @param { PutOptions<Params, Query, Body> } options - параметры PUT запроса
+     */
+    put<P extends Params, Q extends Query, B extends Body, R extends Result>(url: string, options: PutOptions<P, Q, B>): Promise<R>;
+    /**
+     * Выполнить PATCH запрос на сервер
+     *
+     * Дженерик:
+     * Params - параметры, которые будут подставлены в шаблон пути
+     * Query - параметры, которые будут преобразованы в строку запроса
+     * Body - тело запроса
+     * Result - ожидаемый результат выполнения запроса
+     *
+     * @param { string } url - адрес запроса
+     * @param { PatchOptions<Params, Query, Body> } options - параметры PATCH запроса
+     */
+    patch<P extends Params, Q extends Query, B extends Body, R extends Result>(url: string, options: PatchOptions<P, Q, B>): Promise<R>;
+    /**
+     * Выполнить DELETE запрос на сервер
+     *
+     * Дженерик:
+     * Params - параметры, которые будут подставлены в шаблон пути
+     * Query - параметры, которые будут преобразованы в строку запроса
+     * Body - тело запроса
+     * Result - ожидаемый результат выполнения запроса
+     *
+     * @param { string } url - адрес запроса
+     * @param { DeleteOptions<Params, Query, Body> } options - параметры DELETE запроса
+     */
+    delete<P extends Params, Q extends Query, B extends Body, R extends Result>(url: string, options: DeleteOptions<P, Q, B>): Promise<R>;
+}

package/lib/http-client.errors.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Класс описывающий ошибку связанную с модулем HttpClient
+ */
+export declare class HttpClientError extends Error {
+    readonly name: string;
+    /**
+     * Статус ошибки
+     */
+    readonly status: number;
+    /**
+     * Детали ошибки
+     */
+    readonly details: string | null;
+    constructor(message: string, status: number, details: string | null);
+}
+/**
+ * Класс описывающий внутреннюю ошибку связанную с модулем HttpClient
+ */
+export declare class InternalError extends HttpClientError {
+    readonly name: string;
+    constructor(message: string, details: string | null);
+}
+/**
+ * Класс описывающий неизвестную ошибку
+ */
+export declare class UnknownError extends HttpClientError {
+    constructor(code: number, details: string);
+}
+/**
+ * Класс описывающий ошибку "Плохой запрос"
+ * Это означает, что сервер не понимает запрос из-за неверного синтаксиса
+ */
+export declare class BadRequestError extends HttpClientError {
+    constructor(details: string);
+}
+/**
+ * Класс описывающий ошибку "Не авторизовано"
+ * Это означает. что для получения запрашиваемого ответа нужна аутентификация
+ */
+export declare class UnauthorizedError extends HttpClientError {
+    constructor(details: string);
+}
+/**
+ * Класс описывающий ошибку "Запрещено"
+ * Это означает, что у клиента нет прав доступа к содержимому
+ */
+export declare class ForbiddenError extends HttpClientError {
+    constructor(details: string);
+}
+/**
+ * Класс описывающий ошибку "Не найден"
+ * Это означает, что сервер не может найти запрашиваемый ресурс
+ */
+export declare class NotFoundError extends HttpClientError {
+    constructor(details: string);
+}
+/**
+ * Класс описывающий ошибку "Метод не доступен"
+ * Это означает, что серверу известен запрос, но он был отключен и не может быть использован
+ */
+export declare class MethodNotAllowedError extends HttpClientError {
+    constructor(details: string);
+}
+/**
+ * Класс описывающий ошибку "Медиа формат не поддерживается сервером"
+ * Это означает, что сервер не поддерживает медиа формат запрашиваемых данных
+ */
+export declare class UnsupportedMediaTypeError extends HttpClientError {
+    constructor(details: string);
+}
+/**
+ * Класс описывающий ошибку "Сервер не может обработать запрос"
+ * Это означает, что сервер понимает тип содержимого в теле запроса
+ * и синтаксис запроса является корректным, но серверу не удалось обработать инструкции содержимого
+ */
+export declare class UnprocessableEntityError extends HttpClientError {
+    constructor(details: string);
+}
+/**
+ * Класс описывающий ошибку "Внутренняя ошибка сервера"
+ * Это означает, что сервер столкнулся с ситуацией, которую он не знает как обработать
+ */
+export declare class InternalServerError extends HttpClientError {
+    constructor(details: string);
+}
+/**
+ * Класс описывающий ошибку "Плохой шлюз"
+ * Это означает, что сервер действует как шлюз шлюз и получил недопустимый ответ
+ */
+export declare class BadGatewayError extends HttpClientError {
+    constructor(details: string);
+}
+/**
+ * Класс описывающий ошибку "Сервис недоступен"
+ * Это означает, что сервер не готов обрабатывать запрос
+ */
+export declare class ServiceUnavailableError extends HttpClientError {
+    constructor(details: string);
+}
+/**
+ * Класс описывающий ошибку "Вышло время ожидания ответа"
+ * Это означает, что сервер действует как шлюз и не может получить ответ вовремя
+ */
+export declare class GatewayTimeoutError extends HttpClientError {
+    constructor(details: string);
+}

package/lib/http-client.types.d.ts

@@ -0,0 +1,71 @@
+import { CookieAttributes } from 'js-cookie';
+declare type Primitives = string | number | boolean | null | undefined;
+export declare type Config = {
+    readonly clientId: string;
+    readonly urls: {
+        readonly authorize: string;
+        readonly token: string;
+        readonly logout: string;
+    };
+};
+export declare type CookieOptions = CookieAttributes;
+export declare type GetMethod = 'GET';
+export declare type PostMethod = 'POST';
+export declare type PutMethod = 'PUT';
+export declare type PatchMethod = 'PATCH';
+export declare type DeleteMethod = 'DELETE';
+export declare type Method = GetMethod | PutMethod | PostMethod | PatchMethod | DeleteMethod;
+export declare type Params = Record<string, string | number> | never;
+export declare type Query = Record<string, Primitives> | URLSearchParams | string | never;
+export declare type Body = Record<string, unknown> | FormData | never;
+export declare type Result = unknown | void;
+declare type BaseRequestOptions<M extends Method> = {
+    readonly method: M;
+    readonly headers?: Record<string, string>;
+    readonly withAuthorization: boolean;
+    readonly withCredentials?: boolean;
+};
+export declare type Options<M extends Method, P extends Params, Q extends Query, B extends Body> = M extends GetMethod ? [P] extends [never] ? [Q] extends [never] ? BaseRequestOptions<GetMethod> : BaseRequestOptions<GetMethod> & {
+    query: Q;
+} : [Q] extends [never] ? BaseRequestOptions<GetMethod> & {
+    params: P;
+} : BaseRequestOptions<GetMethod> & {
+    params: P;
+    query: Q;
+} : [P] extends [never] ? [Q] extends [never] ? [B] extends [never] ? BaseRequestOptions<Method> : BaseRequestOptions<Method> & {
+    body: B;
+} : [B] extends [never] ? BaseRequestOptions<Method> & {
+    query: Q;
+} : BaseRequestOptions<Method> & {
+    params: P;
+    body: B;
+} : [Q] extends [never] ? [B] extends [never] ? BaseRequestOptions<Method> & {
+    params: P;
+} : BaseRequestOptions<Method> & {
+    params: P;
+    body: B;
+} : [B] extends [never] ? BaseRequestOptions<Method> & {
+    params: P;
+    query: Q;
+} : BaseRequestOptions<Method> & {
+    params: P;
+    query: Q;
+    body: B;
+};
+export declare type GetOptions<P extends Params, Q extends Query> = Omit<Options<GetMethod, P, Q, never>, 'method'>;
+export declare type PostOptions<P extends Params, Q extends Query, B extends Body> = Omit<Options<PostMethod, P, Q, B>, 'method'>;
+export declare type PutOptions<P extends Params, Q extends Query, B extends Body> = Omit<Options<PutMethod, P, Q, B>, 'method'>;
+export declare type PatchOptions<P extends Params, Q extends Query, B extends Body> = Omit<Options<PatchMethod, P, Q, B>, 'method'>;
+export declare type DeleteOptions<P extends Params, Q extends Query, B extends Body> = Omit<Options<DeleteMethod, P, Q, B>, 'method'>;
+export declare type Response<R extends Result> = {
+    readonly result: R;
+    readonly status: number;
+    readonly message: string;
+};
+export declare type Introspect = {
+    readonly user_id: string | number;
+    readonly username: string | number;
+    readonly account_id: string | number;
+    readonly expired_at: number;
+};
+export {};

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './http-client';
+export * from './http-client.errors';
+export * from './http-client.types';