npm package: @slavahawk/wlist-api
Description: Typed API client for W-List (admin/customer/root/common)
Latest version: 1.0.11

# W-List API Client

Типизированный API клиент для W-List с поддержкой аутентификации и автоматического обновления токенов.

## Установка

```bash
npm install @w-list/api
```

## Основные возможности

- 🔐 **Безопасная аутентификация** с использованием cookies
- 🔄 **Автоматическое обновление токенов**
- 📝 **Полная типизация** всех API методов
- 🛡️ **Защита от CSRF** атак
- ⚡ **Очередь запросов** при обновлении токенов

## Быстрый старт

### 1. Инициализация аутентификации

```typescript
import { initializeAuth, AuthService } from '@w-list/api';

// Инициализируем систему аутентификации с расширенной конфигурацией
initializeAuth({
  apiUrl: 'https://api.w-list.ru',
  router, // опционально
  maxRetries: 3,           // Максимум 3 попытки обновления токена
  retryDelay: 1000,        // Задержка 1 секунда между попытками
  refreshThreshold: 5 * 60 * 1000, // Обновлять за 5 минут до истечения
});

// Теперь можно использовать AuthService
```

### 2. Вход в систему

```typescript
import { AuthService } from '@w-list/api';

try {
  const response = await AuthService.login({
    email: 'user@example.com',
    password: 'password123'
  });
  
  console.log('Успешный вход:', response);
} catch (error) {
  console.error('Ошибка входа:', error);
}
```

### 3. Использование API

```typescript
import { Admin, Customer, Common } from '@w-list/api';

// Получение списка вин (требует аутентификации)
const wines = await Admin.getWineById(123);

// Получение профиля пользователя
const profile = await AuthService.getMe();

// Выход из системы
await AuthService.logout();
```

## Безопасность

### Cookies vs LocalStorage

Система использует cookies вместо localStorage для большей безопасности:

- ✅ **HttpOnly** (для серверной части)
- ✅ **Secure** (только HTTPS)
- ✅ **SameSite=Strict** (защита от CSRF)
- ✅ **Автоматическое истечение** токенов

### Настройки токенов

- **Access Token**: 1 час жизни
- **Refresh Token**: 7 дней жизни
- **Автоматическое обновление**: за 5 минут до истечения

## API Методы

### Аутентификация

```typescript
// Вход
AuthService.login(credentials)

// Регистрация
AuthService.register(userData)

// Обновление токена
AuthService.refresh(refreshToken)

// Выход
AuthService.logout()

// Проверка аутентификации
AuthService.isAuthenticated()

// Получение времени истечения токена
AuthService.getTokenExpiration()

// Автоматическое обновление при необходимости
AuthService.refreshIfNeeded()
```

### Управление токенами

```typescript
import { getToken, setToken, clearTokens, hasValidToken } from '@w-list/api';

// Получение токена
const token = getToken('accessToken');

// Установка токена
setToken('accessToken', 'new-token-value');

// Очистка всех токенов
clearTokens();

// Проверка валидности токена
const isValid = hasValidToken();
```

## Обработка ошибок

```typescript
import { ApiError } from '@w-list/api';

try {
  await AuthService.login(credentials);
} catch (error) {
  if (error instanceof ApiError) {
    console.error('API ошибка:', error.message);
    console.error('Статус:', error.status);
    console.error('Детали:', error.details);
  }
}
```

## Интеграция с роутером

```typescript
import { initializeAuth } from '@w-list/api';

// Vue Router
const router = {
  replace: (path: string) => router.push(path)
};

// React Router
const router = {
  replace: (path: string) => navigate(path)
};

// Инициализация
initializeAuth(router, 'https://api.w-list.ru');
```

## Автоматическое обновление токенов

Система автоматически:

1. Перехватывает 401 ошибки
2. Пытается обновить токен
3. Повторяет исходный запрос
4. Очищает токены при неудаче

```typescript
// Запрос будет автоматически повторен после обновления токена
const wines = await Admin.getAll({ request: filter });
```

## Типы

Все API методы полностью типизированы. Импортируйте типы напрямую из generated файлов:

```typescript
import type { 
  AuthRequest, 
  AuthResponse, 
  GetMeResponse 
} from '@w-list/api/generated/common/common.gen';
```

## Конфигурация

### Переменные окружения

```env
# URL API
VITE_API_URL=https://api.w-list.ru
API_URL=https://api.w-list.ru
```

### Настройка Orval

Конфигурация для генерации типов находится в `orval.config.ts`:

```typescript
export default defineConfig({
  common: {
    input: { target: './openapi/wlist.openapi.json', filters: { tags: ['Auth'] } },
    // ...
  },
  // ...
});
```

## Разработка

### Генерация API

```bash
# Получение OpenAPI спецификации
npm run api:fetch

# Генерация типов и методов
npm run api:gen

# Сборка
npm run build
```

### Структура проекта

```
src/
├── api/
│   ├── http.ts          # HTTP клиент с интерцепторами
│   ├── token.ts         # Работа с токенами
│   ├── helpers.ts       # Вспомогательные функции
│   └── types.ts         # Типы для роутера
├── generated/           # Сгенерированные API методы
│   ├── admin/
│   ├── customer/
│   ├── common/
│   └── root/
├── services/
│   └── auth.service.ts  # Сервис аутентификации
└── types.ts            # Общие типы
```

## Лицензия

MIT