mbt-api-client 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,879 @@
+import * as react from 'react';
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
+
+/**
+ * Модуль управления обновлением токенов
+ *
+ * Реализует механизм обновления JWT токенов с очередью запросов.
+ * Предотвращает множественные одновременные запросы на обновление токена,
+ * когда несколько параллельных API-запросов получают ошибку 401.
+ *
+ * @example
+ * ```typescript
+ * // Создание менеджера с кастомными функциями
+ * const tokenManager = createTokenRefreshManager({
+ *   refreshTokenFn: async () => {
+ *     const response = await fetch('/api/auth/refresh');
+ *     const data = await response.json();
+ *     return { ok: true, accessToken: data.accessToken };
+ *   },
+ *   onNavigateToLogin: () => router.push('/login'),
+ * });
+ *
+ * // Использование с RTK Query или другими клиентами
+ * if (response.status === 401) {
+ *   const newToken = await tokenManager.handle401();
+ *   // Повторить запрос с новым токеном
+ * }
+ * ```
+ *
+ * @module token-refresh
+ */
+/**
+ * Конфигурация менеджера обновления токенов
+ *
+ * @example
+ * ```typescript
+ * const config: TokenRefreshConfig = {
+ *   refreshTokenFn: async () => {
+ *     // Ваша логика обновления токена
+ *     return { ok: true, accessToken: 'new-token' };
+ *   },
+ *   onNavigateToLogin: () => window.location.href = '/login',
+ *   getAccessToken: () => localStorage.getItem('accessToken'),
+ *   getRefreshToken: () => localStorage.getItem('refreshToken'),
+ *   setTokens: (access, refresh) => {
+ *     localStorage.setItem('accessToken', access);
+ *     if (refresh) localStorage.setItem('refreshToken', refresh);
+ *   },
+ *   clearTokens: () => {
+ *     localStorage.removeItem('accessToken');
+ *     localStorage.removeItem('refreshToken');
+ *   },
+ * };
+ * ```
+ */
+interface TokenRefreshConfig {
+    /**
+     * Функция для выполнения запроса на обновление токена
+     *
+     * Должна вернуть объект с `ok: true` и новым `accessToken` при успехе,
+     * или `ok: false` при ошибке.
+     *
+     * @returns Промис с результатом обновления токена
+     *
+     * @example
+     * ```typescript
+     * refreshTokenFn: async () => {
+     *   try {
+     *     const response = await axios.post('/auth/refresh-token', {}, {
+     *       headers: { Authorization: `Bearer ${refreshToken}` }
+     *     });
+     *     return {
+     *       ok: true,
+     *       accessToken: response.data.accessToken,
+     *       refreshToken: response.data.refreshToken,
+     *     };
+     *   } catch {
+     *     return { ok: false };
+     *   }
+     * }
+     * ```
+     */
+    refreshTokenFn: () => Promise<TokenRefreshResult>;
+    /**
+     * Колбэк для перенаправления на страницу логина
+     *
+     * Вызывается когда:
+     * - Токен невалиден (message: 'Invalid token')
+     * - Обновление токена не удалось
+     * - Refresh token истёк
+     *
+     * @default Очищает localStorage и редиректит на '#/login'
+     *
+     * @example
+     * ```typescript
+     * onNavigateToLogin: () => {
+     *   // Для React Router
+     *   navigate('/login');
+     *   // Или для Next.js
+     *   router.push('/login');
+     * }
+     * ```
+     */
+    onNavigateToLogin?: () => void;
+    /**
+     * Функция получения текущего access токена
+     *
+     * @default () => localStorage.getItem('accessToken')
+     *
+     * @example
+     * ```typescript
+     * // Для хранения в Redux
+     * getAccessToken: () => store.getState().auth.accessToken
+     * ```
+     */
+    getAccessToken?: () => string | null;
+    /**
+     * Функция получения текущего refresh токена
+     *
+     * @default () => localStorage.getItem('refreshToken')
+     */
+    getRefreshToken?: () => string | null;
+    /**
+     * Функция сохранения новых токенов после обновления
+     *
+     * @param accessToken - Новый access токен
+     * @param refreshToken - Новый refresh токен (опционально)
+     *
+     * @default Сохраняет в localStorage
+     *
+     * @example
+     * ```typescript
+     * // Для хранения в Redux
+     * setTokens: (access, refresh) => {
+     *   store.dispatch(setAuthTokens({ accessToken: access, refreshToken: refresh }));
+     * }
+     * ```
+     */
+    setTokens?: (accessToken: string, refreshToken?: string) => void;
+    /**
+     * Функция очистки токенов (при выходе или ошибке авторизации)
+     *
+     * @default Удаляет 'accessToken' и 'refreshToken' из localStorage
+     */
+    clearTokens?: () => void;
+}
+/**
+ * Результат операции обновления токена
+ *
+ * @example
+ * ```typescript
+ * // Успешное обновление
+ * const success: TokenRefreshResult = {
+ *   ok: true,
+ *   accessToken: 'eyJhbGciOiJIUzI1...',
+ *   refreshToken: 'dGhpcyBpcyBhIHJl...',
+ * };
+ *
+ * // Ошибка обновления
+ * const failure: TokenRefreshResult = { ok: false };
+ * ```
+ */
+interface TokenRefreshResult {
+    /**
+     * Успешность операции обновления
+     *
+     * `true` - токен успешно обновлён
+     * `false` - ошибка обновления (пользователь будет перенаправлен на логин)
+     */
+    ok: boolean;
+    /**
+     * Новый access токен (только при `ok: true`)
+     */
+    accessToken?: string;
+    /**
+     * Новый refresh токен (опционально, только при `ok: true`)
+     */
+    refreshToken?: string;
+}
+/**
+ * Менеджер обновления токенов с очередью запросов
+ *
+ * Решает проблему одновременного обновления токена при множественных
+ * параллельных запросах, получивших 401 ошибку.
+ *
+ * **Как это работает:**
+ * 1. Первый запрос с 401 инициирует обновление токена
+ * 2. Последующие запросы с 401 добавляются в очередь ожидания
+ * 3. После успешного обновления все запросы в очереди получают новый токен
+ * 4. При ошибке обновления все запросы получают ошибку
+ *
+ * @example
+ * ```typescript
+ * // Создание менеджера
+ * const tokenManager = new TokenRefreshManager({
+ *   refreshTokenFn: async () => {
+ *     const res = await fetch('/api/refresh');
+ *     const data = await res.json();
+ *     return { ok: true, accessToken: data.token };
+ *   },
+ * });
+ *
+ * // Использование в axios interceptor
+ * axios.interceptors.response.use(
+ *   response => response,
+ *   async error => {
+ *     if (error.response?.status === 401) {
+ *       const newToken = await tokenManager.handle401();
+ *       if (newToken) {
+ *         error.config.headers.Authorization = `Bearer ${newToken}`;
+ *         return axios(error.config);
+ *       }
+ *     }
+ *     return Promise.reject(error);
+ *   }
+ * );
+ * ```
+ */
+declare class TokenRefreshManager {
+    private isRefreshing;
+    private refreshPromise;
+    private queuedRequests;
+    private config;
+    /**
+     * Создаёт новый экземпляр TokenRefreshManager
+     *
+     * @param config - Конфигурация менеджера
+     *
+     * @example
+     * ```typescript
+     * const manager = new TokenRefreshManager({
+     *   refreshTokenFn: myRefreshFunction,
+     *   onNavigateToLogin: () => router.push('/login'),
+     * });
+     * ```
+     */
+    constructor(config: TokenRefreshConfig);
+    /**
+     * Получает текущий access токен
+     *
+     * @returns Access токен или null, если токен отсутствует
+     *
+     * @example
+     * ```typescript
+     * const token = manager.getAccessToken();
+     * if (token) {
+     *   headers.Authorization = `Bearer ${token}`;
+     * }
+     * ```
+     */
+    getAccessToken(): string | null;
+    /**
+     * Получает текущий refresh токен
+     *
+     * @returns Refresh токен или null, если токен отсутствует
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Проверяет, идёт ли в данный момент процесс обновления токена
+     *
+     * Используйте для определения, нужно ли ставить запрос в очередь
+     * или инициировать новое обновление.
+     *
+     * @returns `true` если обновление в процессе, `false` если нет
+     *
+     * @example
+     * ```typescript
+     * if (manager.isRefreshInProgress()) {
+     *   // Ждём завершения текущего обновления
+     *   const newToken = await manager.waitForTokenRefresh();
+     * } else {
+     *   // Инициируем новое обновление
+     *   await manager.refreshToken();
+     * }
+     * ```
+     */
+    isRefreshInProgress(): boolean;
+    /**
+     * Добавляет запрос в очередь ожидания обновления токена
+     *
+     * Возвращает промис, который разрешится с новым токеном после
+     * успешного обновления или будет отклонён при ошибке.
+     *
+     * @returns Промис с новым access токеном
+     *
+     * @example
+     * ```typescript
+     * // В response interceptor при множественных 401
+     * if (manager.isRefreshInProgress()) {
+     *   try {
+     *     const newToken = await manager.waitForTokenRefresh();
+     *     // Повторить запрос с новым токеном
+     *   } catch {
+     *     // Обновление не удалось
+     *   }
+     * }
+     * ```
+     */
+    waitForTokenRefresh(): Promise<string>;
+    /**
+     * Выполняет обновление токена
+     *
+     * Если обновление уже в процессе, вернёт существующий промис.
+     * После обновления уведомляет все запросы в очереди.
+     *
+     * @returns Промис с результатом обновления
+     *
+     * @example
+     * ```typescript
+     * const result = await manager.refreshToken();
+     * if (result.ok) {
+     *   console.log('Новый токен:', result.accessToken);
+     * } else {
+     *   console.log('Ошибка обновления токена');
+     * }
+     * ```
+     */
+    refreshToken(): Promise<TokenRefreshResult>;
+    /**
+     * Обрабатывает ошибку 401 — либо обновляет токен, либо перенаправляет на логин
+     *
+     * Основной метод для использования в interceptors. Автоматически:
+     * - Перенаправляет на логин при невалидном токене
+     * - Ставит запрос в очередь, если обновление уже идёт
+     * - Инициирует обновление, если ещё не запущено
+     *
+     * @param isInvalidToken - Если true, токен считается невалидным и будет выполнен переход на логин
+     * @returns Промис с новым access токеном или null при ошибке
+     *
+     * @example
+     * ```typescript
+     * // В axios response interceptor
+     * if (error.response?.status === 401) {
+     *   const isInvalid = error.response.data?.message === 'Invalid token';
+     *   const newToken = await manager.handle401(isInvalid);
+     *
+     *   if (newToken) {
+     *     // Повторить запрос с новым токеном
+     *     error.config.headers.Authorization = `Bearer ${newToken}`;
+     *     return axios(error.config);
+     *   }
+     *   // newToken === null означает переход на логин
+     * }
+     * ```
+     */
+    handle401(isInvalidToken?: boolean): Promise<string | null>;
+    /**
+     * Принудительно перенаправляет на страницу логина
+     *
+     * Вызывает колбэк onNavigateToLogin из конфигурации.
+     *
+     * @example
+     * ```typescript
+     * // При необходимости принудительного выхода
+     * manager.navigateToLogin();
+     * ```
+     */
+    navigateToLogin(): void;
+    /**
+     * Сбрасывает внутреннее состояние менеджера
+     *
+     * Полезно для тестирования или при необходимости
+     * принудительно сбросить очередь запросов.
+     *
+     * @example
+     * ```typescript
+     * // В тестах
+     * beforeEach(() => {
+     *   manager.reset();
+     * });
+     * ```
+     */
+    reset(): void;
+    private performRefresh;
+    private notifyQueueSuccess;
+    private notifyQueueFailure;
+}
+/**
+ * Создаёт новый экземпляр TokenRefreshManager
+ *
+ * Фабричная функция для создания менеджера обновления токенов.
+ * Предпочтительный способ создания вместо прямого вызова конструктора.
+ *
+ * @param config - Конфигурация менеджера
+ * @returns Новый экземпляр TokenRefreshManager
+ *
+ * @example
+ * ```typescript
+ * import { createTokenRefreshManager } from 'mbt-api-client';
+ *
+ * const tokenManager = createTokenRefreshManager({
+ *   refreshTokenFn: async () => {
+ *     const response = await fetch('/api/auth/refresh', {
+ *       method: 'POST',
+ *       headers: {
+ *         Authorization: `Bearer ${localStorage.getItem('refreshToken')}`,
+ *       },
+ *     });
+ *
+ *     if (!response.ok) {
+ *       return { ok: false };
+ *     }
+ *
+ *     const data = await response.json();
+ *     return {
+ *       ok: true,
+ *       accessToken: data.accessToken,
+ *       refreshToken: data.refreshToken,
+ *     };
+ *   },
+ *   onNavigateToLogin: () => {
+ *     window.location.href = '/login';
+ *   },
+ * });
+ *
+ * // Использование
+ * const newToken = await tokenManager.handle401();
+ * ```
+ */
+declare const createTokenRefreshManager: (config: TokenRefreshConfig) => TokenRefreshManager;
+
+/**
+ * URL-адреса микросервисов API
+ *
+ * @example
+ * ```typescript
+ * const urls: ApiClientUrls = {
+ *   authService: 'https://auth.example.com',
+ *   userProgressService: 'https://progress.example.com',
+ *   recommendationService: 'https://rec.example.com',
+ *   partnerManager: 'https://partners.example.com',
+ *   puzzleController: 'https://puzzles.example.com',
+ *   monolith: 'https://api.example.com',
+ * };
+ * ```
+ */
+interface ApiClientUrls {
+    /** URL сервиса авторизации (логин, регистрация, refresh токенов) */
+    authService: string;
+    /** URL сервиса прогресса пользователя */
+    userProgressService: string;
+    /** URL сервиса рекомендаций */
+    recommendationService: string;
+    /** URL сервиса управления партнёрами */
+    partnerManager: string;
+    /** URL контроллера пазлов/задач */
+    puzzleController: string;
+    /** URL основного монолитного сервиса */
+    monolith: string;
+}
+/**
+ * Конфигурация API клиента
+ *
+ * @example
+ * ```typescript
+ * const config: ApiClientConfig = {
+ *   urls: {
+ *     authService: 'https://auth.example.com',
+ *     userProgressService: 'https://progress.example.com',
+ *     // ... остальные URL
+ *   },
+ *   onNavigateToLogin: () => {
+ *     // Для React Router
+ *     navigate('/login');
+ *   },
+ *   timeout: 15000,
+ *   decodeJwt: (token) => {
+ *     // Кастомный декодер JWT
+ *     return jwtDecode(token);
+ *   },
+ * };
+ * ```
+ */
+interface ApiClientConfig {
+    /**
+     * URL-адреса микросервисов
+     */
+    urls: ApiClientUrls;
+    /**
+     * Колбэк для перенаправления на страницу логина
+     *
+     * Вызывается при:
+     * - Ошибке 401 с невалидным токеном
+     * - Ошибке 403 (доступ запрещён)
+     * - Неудачном обновлении токена
+     *
+     * @default Очищает localStorage и редиректит на '#/login'
+     *
+     * @example
+     * ```typescript
+     * // React Router
+     * onNavigateToLogin: () => navigate('/login')
+     *
+     * // Next.js
+     * onNavigateToLogin: () => router.push('/login')
+     *
+     * // Vanilla JS
+     * onNavigateToLogin: () => { window.location.href = '/login' }
+     * ```
+     */
+    onNavigateToLogin?: () => void;
+    /**
+     * Таймаут запросов в миллисекундах
+     *
+     * @default 10000 (10 секунд)
+     */
+    timeout?: number;
+    /**
+     * Функция декодирования JWT токена для извлечения userId
+     *
+     * Используется для добавления заголовка X-User-Id к запросам.
+     * Если не указана, используется встроенный base64 декодер.
+     *
+     * @param token - JWT токен для декодирования
+     * @returns Объект с userId или null при ошибке декодирования
+     *
+     * @default Встроенный base64 декодер
+     *
+     * @example
+     * ```typescript
+     * // С библиотекой jwt-decode
+     * import { jwtDecode } from 'jwt-decode';
+     *
+     * decodeJwt: (token) => {
+     *   try {
+     *     return jwtDecode<{ userId: string }>(token);
+     *   } catch {
+     *     return null;
+     *   }
+     * }
+     * ```
+     */
+    decodeJwt?: (token: string) => {
+        userId?: string;
+    } | null;
+}
+/**
+ * Обёртка над axios для выполнения HTTP-запросов
+ *
+ * Предоставляет типизированные методы для всех HTTP-операций.
+ * Автоматически извлекает `data` из ответа axios.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: string;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * // GET запрос с типизацией
+ * const user = await apiService.get<User>('/users/me');
+ * console.log(user.name);
+ *
+ * // POST запрос
+ * const newUser = await apiService.post<User>('/users', {
+ *   name: 'John',
+ *   email: 'john@example.com',
+ * });
+ *
+ * // С дополнительными параметрами axios
+ * const data = await apiService.get<Data>('/endpoint', {
+ *   params: { page: 1, limit: 10 },
+ *   headers: { 'X-Custom-Header': 'value' },
+ * });
+ * ```
+ */
+interface ApiService {
+    /**
+     * Выполняет GET-запрос
+     *
+     * Автоматически добавляет cache-buster параметр `_t` для предотвращения кэширования.
+     *
+     * @typeParam T - Тип данных ответа
+     * @param url - URL эндпоинта (относительно baseURL сервиса)
+     * @param config - Дополнительные параметры axios (headers, params и т.д.)
+     * @returns Промис с данными ответа
+     *
+     * @example
+     * ```typescript
+     * // Простой GET
+     * const users = await service.get<User[]>('/users');
+     *
+     * // С query параметрами
+     * const filtered = await service.get<User[]>('/users', {
+     *   params: { role: 'admin', active: true }
+     * });
+     * ```
+     */
+    get: <T>(url: string, config?: AxiosRequestConfig) => Promise<T>;
+    /**
+     * Выполняет POST-запрос
+     *
+     * @typeParam T - Тип данных ответа
+     * @param url - URL эндпоинта (относительно baseURL сервиса)
+     * @param data - Тело запроса (будет сериализовано в JSON)
+     * @param config - Дополнительные параметры axios
+     * @returns Промис с данными ответа
+     *
+     * @example
+     * ```typescript
+     * const newUser = await service.post<User>('/users', {
+     *   name: 'John Doe',
+     *   email: 'john@example.com',
+     * });
+     * ```
+     */
+    post: <T>(url: string, data?: unknown, config?: AxiosRequestConfig) => Promise<T>;
+    /**
+     * Выполняет PUT-запрос
+     *
+     * @typeParam T - Тип данных ответа
+     * @param url - URL эндпоинта
+     * @param data - Тело запроса для обновления
+     * @param config - Дополнительные параметры axios
+     * @returns Промис с данными ответа
+     *
+     * @example
+     * ```typescript
+     * const updated = await service.put<User>('/users/123', {
+     *   name: 'Jane Doe',
+     * });
+     * ```
+     */
+    put: <T>(url: string, data?: unknown, config?: AxiosRequestConfig) => Promise<T>;
+    /**
+     * Выполняет DELETE-запрос
+     *
+     * @typeParam T - Тип данных ответа
+     * @param url - URL эндпоинта
+     * @param config - Дополнительные параметры axios
+     * @returns Промис с данными ответа
+     *
+     * @example
+     * ```typescript
+     * await service.delete<void>('/users/123');
+     * ```
+     */
+    delete: <T>(url: string, config?: AxiosRequestConfig) => Promise<T>;
+    /**
+     * Доступ к нативному экземпляру axios
+     *
+     * Используйте для добавления кастомных interceptors или
+     * выполнения нестандартных запросов.
+     *
+     * @example
+     * ```typescript
+     * // Добавление кастомного interceptor
+     * service.axiosInstance.interceptors.request.use(config => {
+     *   config.headers['X-Request-Id'] = generateId();
+     *   return config;
+     * });
+     *
+     * // Выполнение PATCH запроса
+     * await service.axiosInstance.patch('/users/123', { name: 'New Name' });
+     * ```
+     */
+    axiosInstance: AxiosInstance;
+}
+/**
+ * Главный объект API клиента
+ *
+ * Содержит настроенные сервисы для каждого микросервиса
+ * и менеджер обновления токенов.
+ *
+ * @example
+ * ```typescript
+ * const apiClient = createApiClient({ urls: {...} });
+ *
+ * // Использование сервисов
+ * const user = await apiClient.userProgressService.get('/me');
+ * const puzzles = await apiClient.puzzleController.get('/puzzles');
+ *
+ * // Работа с токенами
+ * const currentToken = apiClient.tokenRefreshManager.getAccessToken();
+ * ```
+ */
+interface ApiClient {
+    /**
+     * Сервис авторизации
+     *
+     * Используется для логина, регистрации, обновления токенов.
+     */
+    authService: ApiService;
+    /**
+     * Сервис прогресса пользователя
+     *
+     * Используется для получения и обновления прогресса обучения.
+     */
+    userProgressService: ApiService;
+    /**
+     * Сервис рекомендаций
+     *
+     * Используется для получения персонализированных рекомендаций.
+     */
+    recommendationService: ApiService;
+    /**
+     * Сервис управления партнёрами
+     */
+    partnerManager: ApiService;
+    /**
+     * Контроллер пазлов/задач
+     *
+     * Используется для работы с учебными задачами и пазлами.
+     */
+    puzzleController: ApiService;
+    /**
+     * Основной монолитный сервис
+     *
+     * Используется для запросов, не выделенных в отдельные микросервисы.
+     */
+    monolith: ApiService;
+    /**
+     * Менеджер обновления токенов
+     *
+     * Предоставляет доступ к функциям работы с токенами.
+     * Можно использовать с RTK Query или другими HTTP-клиентами.
+     *
+     * @example
+     * ```typescript
+     * // Получение текущего токена
+     * const token = apiClient.tokenRefreshManager.getAccessToken();
+     *
+     * // Обработка 401 в кастомном клиенте
+     * if (response.status === 401) {
+     *   const newToken = await apiClient.tokenRefreshManager.handle401();
+     * }
+     * ```
+     */
+    tokenRefreshManager: TokenRefreshManager;
+}
+/**
+ * Создаёт настроенный API клиент
+ *
+ * Фабричная функция, которая создаёт полностью настроенный API клиент
+ * с поддержкой автоматического обновления токенов, обработкой ошибок
+ * авторизации и типизированными методами запросов.
+ *
+ * **Особенности:**
+ * - Автоматическое добавление Authorization заголовка
+ * - Автоматическое обновление токена при 401 ошибке
+ * - Очередь запросов при одновременном обновлении токена
+ * - Добавление X-User-Id заголовка из JWT
+ * - Cache-busting для GET запросов
+ *
+ * @param config - Конфигурация клиента
+ * @returns Настроенный API клиент
+ *
+ * @example
+ * ```typescript
+ * import { createApiClient } from 'mbt-api-client';
+ *
+ * const apiClient = createApiClient({
+ *   urls: {
+ *     authService: 'https://auth.example.com',
+ *     userProgressService: 'https://progress.example.com',
+ *     recommendationService: 'https://rec.example.com',
+ *     partnerManager: 'https://partners.example.com',
+ *     puzzleController: 'https://puzzles.example.com',
+ *     monolith: 'https://api.example.com',
+ *   },
+ *   onNavigateToLogin: () => {
+ *     // Очистка состояния и редирект
+ *     store.dispatch(logout());
+ *     navigate('/login');
+ *   },
+ *   timeout: 15000, // 15 секунд
+ * });
+ *
+ * // Использование
+ * try {
+ *   const user = await apiClient.userProgressService.get<User>('/me');
+ *   console.log('Пользователь:', user);
+ * } catch (error) {
+ *   console.error('Ошибка:', error);
+ * }
+ * ```
+ */
+declare const createApiClient: (config: ApiClientConfig) => ApiClient;
+/**
+ * React Context для API клиента
+ *
+ * Используется внутри ApiClientProvider для передачи клиента
+ * через дерево компонентов.
+ *
+ * @example
+ * ```typescript
+ * // Для кастомных случаев (обычно используйте ApiClientProvider)
+ * <ApiClientContext.Provider value={apiClient}>
+ *   <App />
+ * </ApiClientContext.Provider>
+ * ```
+ */
+declare const ApiClientContext: react.Context<ApiClient | null>;
+/**
+ * React хук для доступа к API клиенту
+ *
+ * Получает API клиент из контекста. Должен использоваться внутри
+ * компонента, обёрнутого в ApiClientProvider.
+ *
+ * @returns API клиент с типизированными сервисами
+ * @throws Error если используется вне ApiClientProvider
+ *
+ * @example
+ * ```typescript
+ * import { useApiClient } from 'mbt-api-client';
+ *
+ * function UserProfile() {
+ *   const { userProgressService } = useApiClient();
+ *   const [user, setUser] = useState<User | null>(null);
+ *
+ *   useEffect(() => {
+ *     userProgressService.get<User>('/me')
+ *       .then(setUser)
+ *       .catch(console.error);
+ *   }, []);
+ *
+ *   return <div>{user?.name}</div>;
+ * }
+ *
+ * // С деструктуризацией нескольких сервисов
+ * function Dashboard() {
+ *   const {
+ *     userProgressService,
+ *     recommendationService,
+ *     puzzleController,
+ *   } = useApiClient();
+ *
+ *   // Параллельные запросы
+ *   const [progress, recommendations, puzzles] = await Promise.all([
+ *     userProgressService.get('/progress'),
+ *     recommendationService.get('/for-me'),
+ *     puzzleController.get('/puzzles'),
+ *   ]);
+ * }
+ * ```
+ */
+declare const useApiClient: () => ApiClient;
+/**
+ * React Provider для API клиента
+ *
+ * Оборачивает приложение для предоставления доступа к API клиенту
+ * через хук useApiClient.
+ *
+ * @example
+ * ```typescript
+ * import { createApiClient, ApiClientProvider } from 'mbt-api-client';
+ *
+ * // Создание клиента (обычно в отдельном файле)
+ * const apiClient = createApiClient({
+ *   urls: { ... },
+ * });
+ *
+ * // В корне приложения
+ * function App() {
+ *   return (
+ *     <ApiClientProvider value={apiClient}>
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </ApiClientProvider>
+ *   );
+ * }
+ *
+ * // С React Query
+ * function App() {
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <ApiClientProvider value={apiClient}>
+ *         <Routes />
+ *       </ApiClientProvider>
+ *     </QueryClientProvider>
+ *   );
+ * }
+ * ```
+ */
+declare const ApiClientProvider: react.Provider<ApiClient | null>;
+
+export { type ApiClient, type ApiClientConfig, ApiClientContext, ApiClientProvider, type ApiClientUrls, type ApiService, type TokenRefreshConfig, TokenRefreshManager, type TokenRefreshResult, createApiClient, createTokenRefreshManager, useApiClient };