solver-sdk/docs/AUTHENTICATION.md

SDK для интеграции с Code Solver Backend API

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

В этом документе описаны методы аутентификации в Solver SDK для различных API и WebSocket соединений.

## Содержание

- [HTTP API аутентификация](#http-api-аутентификация)
- [WebSocket аутентификация](#websocket-аутентификация)
- [Тестовая аутентификация](#тестовая-аутентификация)
- [Обработка ошибок аутентификации](#обработка-ошибок-аутентификации)

## HTTP API аутентификация

SDK поддерживает два основных метода аутентификации для HTTP запросов:

### 1. API ключ

```javascript
const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  apiKey: 'your-api-key'
});
```

API ключ автоматически добавляется в заголовок `X-API-Key` для всех HTTP запросов.

### 2. Пользовательские заголовки

```javascript
const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  headers: {
    'Authorization': 'Bearer your-jwt-token',
    'X-Custom-Header': 'Custom-Value'
  }
});
```

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

Для WebSocket соединений SDK использует отдельный механизм аутентификации через специальное событие `authenticate`.

### Стандартная аутентификация WebSocket

```javascript
// 1. Создаем экземпляр SDK
const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  apiKey: 'your-api-key'
});

// 2. Опции для streamChatWithThinking
const options = {
  model: 'claude-3-7-sonnet-20240229',
  thinking: true,
  authToken: 'your-auth-token' // ← Токен для WebSocket аутентификации
};

// 3. Отправка запроса
const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
```

Параметр `authToken` используется для аутентификации WebSocket соединений и передается в событии `authenticate`.

### Низкоуровневая WebSocket аутентификация

Если вы работаете напрямую с WebSocket клиентом, вы можете настроить аутентификацию следующим образом:

```javascript
// Получаем WebSocket клиент
const wsClient = sdk.getWebSocketClient();

// Настраиваем опции подключения с аутентификацией
const connectionOptions = {
  namespace: 'reasoning',
  authToken: 'your-auth-token',
  query: {
    reasoningId: 'reasoning-123'
  }
};

// Подключаемся к WebSocket серверу
await wsClient.connect(connectionOptions);

// Проверяем статус аутентификации
const isAuthenticated = wsClient.isAuthenticated();
console.log('Аутентификация WebSocket:', isAuthenticated);
```

## Тестовая аутентификация

Для тестовых сред SDK поддерживает упрощенную аутентификацию:

```javascript
const options = {
  // Другие параметры...
  authToken: 'test-token'
};

const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
```

> **Важно**: Начиная с версии 1.7.4, устаревший параметр `testToken` удален в пользу унифицированного параметра `authToken`.

## Обработка ошибок аутентификации

SDK предоставляет механизм обработки ошибок аутентификации:

```javascript
// Обработчик событий WebSocket
const handleEvent = (eventType, data) => {
  if (eventType === 'authentication_error') {
    console.error('Ошибка аутентификации:', data.message);
    
    // Возможная реакция на ошибку (переподключение, запрос нового токена и т.д.)
    switch (data.code) {
      case 'TOKEN_EXPIRED':
        // Запросить новый токен
        break;
      case 'INVALID_TOKEN':
        // Перенаправить на страницу входа
        break;
      default:
        // Общая обработка ошибок
        break;
    }
  }
};
```

### Коды ошибок аутентификации

| Код ошибки | Описание |
|------------|----------|
| `TOKEN_EXPIRED` | Истек срок действия токена |
| `INVALID_TOKEN` | Недействительный токен |
| `MISSING_TOKEN` | Отсутствует токен |
| `AUTH_ERROR` | Общая ошибка аутентификации |
| `FORBIDDEN` | Доступ запрещен |

## Примеры

### Полный пример аутентификации для рассуждений

```javascript
const { CodeSolverSDK, WebSocketNamespace } = require('solver-sdk');

async function exampleWithAuthentication() {
  // 1. Создаем экземпляр SDK
  const sdk = new CodeSolverSDK({
    baseURL: 'https://api.example.com',
    apiKey: 'your-api-key'
  });
  
  // 2. Создаем рассуждение
  const reasoning = await sdk.reasoning.createReasoning({
    projectId: 'project-id',
    query: 'Объясни этот проект'
  });
  
  // 3. Подключаемся через WebSocket с аутентификацией
  await sdk.reasoning.connectWebSocket({
    reasoningId: reasoning.id,
    authToken: 'your-auth-token'
  });
  
  // 4. Настраиваем обработчики событий
  sdk.reasoning.on('authentication_error', (data) => {
    console.error('Ошибка аутентификации:', data);
  });
  
  sdk.reasoning.on('authenticated', (data) => {
    console.log('Успешная аутентификация:', data);
  });
  
  // 5. Отправляем запрос
  await sdk.reasoning.startReasoning(reasoning.id);
}
```