mbt-api-client 1.0.4 → 1.1.1

package/.ai/agent-examples/README.md

@@ -0,0 +1,77 @@
+# Agent Examples
+
+Use these examples when a consumer app needs package-level usage patterns for `mbt-api-client`.
+
+## App Client Setup
+
+```ts
+import { createApiClient } from 'mbt-api-client';
+
+export const apiClient = createApiClient({
+  urls: {
+    authService: 'https://api.example.com/auth',
+    userProgressService: 'https://api.example.com/progress',
+    recommendationService: 'https://api.example.com/recommendations',
+    partnerManager: 'https://api.example.com/partners',
+    adventureManager: 'https://api.example.com/adventures',
+    bff: 'https://api.example.com/bff',
+    puzzleController: 'https://api.example.com/puzzles',
+    micromodeController: 'https://api.example.com/micromodes',
+    userManager: 'https://api.example.com/users',
+    monolith: 'https://api.example.com',
+  },
+  onNavigateToLogin: () => {
+    window.location.href = '#/login';
+  },
+});
+```
+
+## React Provider
+
+```tsx
+import { ApiClientProvider } from 'mbt-api-client';
+
+<ApiClientProvider value={apiClient}>
+  <App />
+</ApiClientProvider>;
+```
+
+## Hook Usage
+
+```tsx
+import { useApiClient } from 'mbt-api-client';
+
+function ProfileScreen() {
+  const { userManager } = useApiClient();
+
+  const loadProfile = async () => {
+    return userManager.get('/me');
+  };
+
+  return <button onClick={() => void loadProfile()}>Load profile</button>;
+}
+```
+
+## Standalone Token Refresh Manager
+
+```ts
+import { createTokenRefreshManager } from 'mbt-api-client';
+
+const tokenManager = createTokenRefreshManager({
+  refreshTokenFn: async () => {
+    const refreshToken = localStorage.getItem('refreshToken');
+
+    if (!refreshToken) {
+      return { ok: false };
+    }
+
+    return {
+      ok: true,
+      accessToken: 'new-access-token',
+      refreshToken,
+    };
+  },
+});
+
+const nextToken = await tokenManager.handle401();
+```

package/.ai/agent-reference/README.md

@@ -0,0 +1,43 @@
+# Agent Reference
+
+This folder holds factual package reference for `mbt-api-client`.
+
+## Public Exports
+
+- `createApiClient`
+- `ApiClientContext`
+- `ApiClientProvider`
+- `useApiClient`
+- `TokenRefreshManager`
+- `createTokenRefreshManager`
+
+## Public Types
+
+- `ApiClient`
+- `ApiClientConfig`
+- `ApiClientUrls`
+- `ApiService`
+- `TokenRefreshConfig`
+- `TokenRefreshResult`
+
+## Required `ApiClientUrls` Keys
+
+- `authService`
+- `userProgressService`
+- `recommendationService`
+- `partnerManager`
+- `adventureManager`
+- `bff`
+- `puzzleController`
+- `micromodeController`
+- `userManager`
+- `monolith`
+
+## Maintainer Sources
+
+- `README.md` - human quick-start
+- `src/api-client.ts` - client, provider, and config truth
+- `src/token-refresh.ts` - token refresh truth
+- `src/index.ts` - public export surface
+
+Reference docs should stay factual. Policy and maintenance rules belong in `.ai/agent-rules/`.

package/.ai/agent-rules/README.md

@@ -0,0 +1,32 @@
+# Agent Rules
+
+These files are the canonical package-owned rules for `mbt-api-client`.
+
+## Rule Map
+
+- `.ai/agent-rules/README.md` - normative setup and usage rules.
+- `.ai/agent-rules/maintenance.md` - required rule for keeping docs in sync with public changes.
+
+## Usage Rules
+
+- Create one configured API client per app shell unless the consumer has a deliberate multi-client design.
+- Wrap React apps with `ApiClientProvider` when component-level access through `useApiClient` is needed.
+- Supply every required `ApiClientUrls` key when creating the client.
+- Keep login redirect behavior explicit through `onNavigateToLogin` when the consumer app has a custom auth flow.
+- Use `createTokenRefreshManager` when a consumer needs standalone 401 retry orchestration outside the built-in client flow.
+- Keep package examples focused on public setup and service usage, not app-specific Redux or router structure.
+- Use kebab-case for file names and folder names across this repo.
+- Use `pnpm` as the package manager for this repo and keep a single lockfile.
+
+## Required URL Keys
+
+- `authService`
+- `userProgressService`
+- `recommendationService`
+- `partnerManager`
+- `adventureManager`
+- `bff`
+- `puzzleController`
+- `micromodeController`
+- `userManager`
+- `monolith`

package/.ai/agent-rules/maintenance.md

@@ -0,0 +1,20 @@
+# Maintenance Rule
+
+Agents working in `mbt-api` must review and update package guidance whenever a change affects public behavior.
+
+## Update The Docs When
+
+- exported functions, types, or providers change
+- required URL keys change
+- token refresh behavior or config changes
+- setup expectations change
+- canonical examples need to change to stay correct
+
+## Required Files To Review
+
+- `AGENTS.md`
+- `.ai/agent-rules/README.md`
+- `.ai/agent-reference/README.md`
+- `.ai/agent-examples/README.md`
+
+Do not finish public package work without reviewing these files.

package/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+## Purpose
+
+- This repo owns the canonical agent guidance for the MBT API client package.
+- Repo name: `mbt-api`
+- npm package name: `mbt-api-client`
+- Consumer apps should read the installed package docs from `node_modules/mbt-api-client/...`.
+
+## Read This First
+
+1. `.ai/agent-rules/README.md`
+2. `.ai/agent-rules/maintenance.md`
+3. `.ai/agent-reference/README.md`
+4. `.ai/agent-examples/README.md`
+
+## Guidance Map
+
+- `.ai/agent-rules/README.md` - package-owned setup and usage rules.
+- `.ai/agent-rules/maintenance.md` - required doc-sync rule.
+- `.ai/agent-reference/README.md` - exported surfaces and required config map.
+- `.ai/agent-examples/README.md` - package-safe examples for app setup and usage.
+
+## Maintenance Rule
+
+- If a change affects public exports, required URLs, provider setup, token refresh behavior, or example usage, update the guidance docs before considering the work complete.
+
+## Guardrails
+
+- Keep docs aligned with the actual `ApiClientUrls` contract.
+- Keep examples focused on public package setup, not one consumer app's internal architecture.
+- Use kebab-case for file names and folder names across this repo.
+- Use `pnpm` as the package manager for this repo.
+- Keep package guidance canonical in `AGENTS.md` and `.ai/` rather than tool-specific wrapper folders.

package/README.md

@@ -0,0 +1,83 @@
+# MBT API Client
+
+Typed MBT API client with React context integration and token refresh helpers.
+
+## Installation
+
+```bash
+pnpm add mbt-api-client
+```
+
+## Package Surfaces
+
+- `mbt-api-client` - API client factory, React provider, hooks, and token refresh helpers
+
+## Agent Guidance
+
+- `AGENTS.md` is the package entrypoint for coding agents.
+- Canonical rules live in `.ai/agent-rules/`.
+- Factual reference lives in `.ai/agent-reference/`.
+- Canonical usage examples live in `.ai/agent-examples/`.
+
+## Quick Start
+
+```tsx
+import { ApiClientProvider, createApiClient } from 'mbt-api-client';
+
+const apiClient = createApiClient({
+  urls: {
+    authService: 'https://api.example.com/auth',
+    userProgressService: 'https://api.example.com/progress',
+    recommendationService: 'https://api.example.com/recommendations',
+    partnerManager: 'https://api.example.com/partners',
+    adventureManager: 'https://api.example.com/adventures',
+    bff: 'https://api.example.com/bff',
+    puzzleController: 'https://api.example.com/puzzles',
+    micromodeController: 'https://api.example.com/micromodes',
+    userManager: 'https://api.example.com/users',
+    monolith: 'https://api.example.com',
+  },
+});
+
+<ApiClientProvider value={apiClient}>
+  <App />
+</ApiClientProvider>;
+```
+
+## Public Exports
+
+- `createApiClient`
+- `ApiClientContext`
+- `ApiClientProvider`
+- `useApiClient`
+- `TokenRefreshManager`
+- `createTokenRefreshManager`
+
+## Required URL Keys
+
+- `authService`
+- `userProgressService`
+- `recommendationService`
+- `partnerManager`
+- `adventureManager`
+- `bff`
+- `puzzleController`
+- `micromodeController`
+- `userManager`
+- `monolith`
+
+## Development
+
+```bash
+pnpm install
+pnpm lint
+pnpm format
+pnpm build
+```
+
+This repo standardizes on `pnpm` only.
+
+## Notes
+
+- Package-owned agent guidance is versioned with the library and published with the package.
+- The consumer app should read the installed package docs from `node_modules/mbt-api-client/...`.

package/dist/index.cjs

@@ -61,19 +61,6 @@ var defaultNavigateToLogin = () => {
   window.location.href = "#/login";
 };
 var TokenRefreshManager = class {
-  /**
-   * Создаёт новый экземпляр TokenRefreshManager
-   *
-   * @param config - Конфигурация менеджера
-   *
-   * @example
-   * ```typescript
-   * const manager = new TokenRefreshManager({
-   *   refreshTokenFn: myRefreshFunction,
-   *   onNavigateToLogin: () => router.push('/login'),
-   * });
-   * ```
-   */
   constructor(config) {
     this.isRefreshing = false;
     this.refreshPromise = null;
@@ -87,96 +74,20 @@ var TokenRefreshManager = class {
       clearTokens: config.clearTokens ?? defaultClearTokens
     };
   }
-  /**
-   * Получает текущий access токен
-   *
-   * @returns Access токен или null, если токен отсутствует
-   *
-   * @example
-   * ```typescript
-   * const token = manager.getAccessToken();
-   * if (token) {
-   *   headers.Authorization = `Bearer ${token}`;
-   * }
-   * ```
-   */
   getAccessToken() {
     return this.config.getAccessToken();
   }
-  /**
-   * Получает текущий refresh токен
-   *
-   * @returns Refresh токен или null, если токен отсутствует
-   */
   getRefreshToken() {
     return this.config.getRefreshToken();
   }
-  /**
-   * Проверяет, идёт ли в данный момент процесс обновления токена
-   *
-   * Используйте для определения, нужно ли ставить запрос в очередь
-   * или инициировать новое обновление.
-   *
-   * @returns `true` если обновление в процессе, `false` если нет
-   *
-   * @example
-   * ```typescript
-   * if (manager.isRefreshInProgress()) {
-   *   // Ждём завершения текущего обновления
-   *   const newToken = await manager.waitForTokenRefresh();
-   * } else {
-   *   // Инициируем новое обновление
-   *   await manager.refreshToken();
-   * }
-   * ```
-   */
   isRefreshInProgress() {
     return this.isRefreshing;
   }
-  /**
-   * Добавляет запрос в очередь ожидания обновления токена
-   *
-   * Возвращает промис, который разрешится с новым токеном после
-   * успешного обновления или будет отклонён при ошибке.
-   *
-   * @returns Промис с новым access токеном
-   *
-   * @example
-   * ```typescript
-   * // В response interceptor при множественных 401
-   * if (manager.isRefreshInProgress()) {
-   *   try {
-   *     const newToken = await manager.waitForTokenRefresh();
-   *     // Повторить запрос с новым токеном
-   *   } catch {
-   *     // Обновление не удалось
-   *   }
-   * }
-   * ```
-   */
   waitForTokenRefresh() {
     return new Promise((resolve, reject) => {
       this.queuedRequests.push({ resolve, reject });
     });
   }
-  /**
-   * Выполняет обновление токена
-   *
-   * Если обновление уже в процессе, вернёт существующий промис.
-   * После обновления уведомляет все запросы в очереди.
-   *
-   * @returns Промис с результатом обновления
-   *
-   * @example
-   * ```typescript
-   * const result = await manager.refreshToken();
-   * if (result.ok) {
-   *   console.log('Новый токен:', result.accessToken);
-   * } else {
-   *   console.log('Ошибка обновления токена');
-   * }
-   * ```
-   */
   async refreshToken() {
     if (this.refreshPromise) {
       return this.refreshPromise;
@@ -189,33 +100,6 @@ var TokenRefreshManager = class {
     });
     return this.refreshPromise;
   }
-  /**
-   * Обрабатывает ошибку 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 означает переход на логин
-   * }
-   * ```
-   */
   async handle401(isInvalidToken = false) {
     if (isInvalidToken) {
       this.config.onNavigateToLogin();
@@ -231,34 +115,9 @@ var TokenRefreshManager = class {
     }
     return result.accessToken || this.config.getAccessToken();
   }
-  /**
-   * Принудительно перенаправляет на страницу логина
-   *
-   * Вызывает колбэк onNavigateToLogin из конфигурации.
-   *
-   * @example
-   * ```typescript
-   * // При необходимости принудительного выхода
-   * manager.navigateToLogin();
-   * ```
-   */
   navigateToLogin() {
     this.config.onNavigateToLogin();
   }
-  /**
-   * Сбрасывает внутреннее состояние менеджера
-   *
-   * Полезно для тестирования или при необходимости
-   * принудительно сбросить очередь запросов.
-   *
-   * @example
-   * ```typescript
-   * // В тестах
-   * beforeEach(() => {
-   *   manager.reset();
-   * });
-   * ```
-   */
   reset() {
     this.isRefreshing = false;
     this.refreshPromise = null;
@@ -306,7 +165,7 @@ var defaultDecodeJwt = (token) => {
     const base64Url = token.split(".")[1];
     const base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
     const jsonPayload = decodeURIComponent(
-      atob(base64).split("").map((c) => "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2)).join("")
+      atob(base64).split("").map((c) => `%${`00${c.charCodeAt(0).toString(16)}`.slice(-2)}`).join("")
     );
     return JSON.parse(jsonPayload);
   } catch {