W-List API Client

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

Установка

npm install @w-list/api

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

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

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

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

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. Вход в систему

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

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

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

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 Методы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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);
  }
}

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

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. Очищает токены при неудаче

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

Типы

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

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

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

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

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

Настройка Orval

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

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

Разработка

Генерация API

# Получение 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