solver-sdk 1.7.4 → 1.7.6

package/docs/WEBSOCKET.md

@@ -1,131 +1,83 @@
 # Работа с WebSocket соединениями
 
-В этом разделе описаны возможности SDK для работы с WebSocket соединениями, методы управления сессиями рассуждений, диагностика соединений и дополнительные возможности для обеспечения стабильной работы.
+В этом разделе описаны основные методы для работы с WebSocket соединениями.
 
-## Содержание
-
-- [Основы работы с WebSocket](#основы-работы-с-websocket)
-- [Высокоуровневый API (версия 1.7.2)](#высокоуровневый-api-версия-172)
-- [Потоковая передача мышления](#потоковая-передача-мышления)
-- [Управление сессиями рассуждений](#управление-сессиями-рассуждений)
-- [Диагностика соединений](#диагностика-соединений)
-- [Механизм переподключения](#механизм-переподключения)
-- [Сохранение и восстановление сессий](#сохранение-и-восстановление-сессий)
-- [Проверка здоровья соединений](#проверка-здоровья-соединений)
-- [Работа с ping/pong](#работа-с-pingpong)
-- [Примеры использования](#примеры-использования)
-- [Справочник всех событий WebSocket](#справочник-всех-событий-websocket)
-
-## Основы работы с WebSocket
-
-SDK предоставляет низкоуровневый WebSocket клиент (`CodeSolverWebSocketClient`), который используется для связи с различными пространствами имен сервера:
+## Получение WebSocket клиента
 
 ```javascript
 const { CodeSolverSDK } = require('solver-sdk');
 
 const sdk = new CodeSolverSDK({
   baseURL: 'https://api.example.com',
-  apiKey: 'your-api-key'
+  apiKey: 'your-api-key',
+  websocket: {
+    reconnect: true,
+    reconnectAttempts: 5,
+    reconnectDelay: 3000,
+    rejectUnauthorized: true // false для самоподписанных сертификатов
+  }
 });
 
 // Получение WebSocket клиента
 const wsClient = sdk.getWebSocketClient();
 
-// Подключение к пространству имен рассуждений
-await wsClient.connectToReasoning('reasoning-id');
-
-// Проверка состояния подключения
-const isConnected = wsClient.isConnectedToReasoning();
-console.log('Подключено к рассуждениям:', isConnected);
-
-// Подписка на события
-wsClient.on('thinking_delta', (data) => {
-  console.log('Получен фрагмент мышления:', data.text);
-});
-
-// Отключение
-wsClient.disconnect(WebSocketNamespace.REASONING);
-```
-
-## Высокоуровневый API (версия 1.7.2)
-
-Начиная с версии 1.7.2, SDK предоставляет высокоуровневый API для работы с WebSocket, интегрированный непосредственно в основные классы API:
+// Подключение к namespace рассуждений
+await wsClient.connectToReasoning();
 
-### Работа с чатом и рассуждениями
-
-```javascript
-// Подключение WebSocket для чата
-await sdk.chat.connectWebSocket();
+// Подключение к namespace индексации
+await wsClient.connectToIndexing();
 
-// Подписка на события
-sdk.chat.on('message_start', (data) => {
-  console.log('Начало сообщения:', data);
-});
+// Проверка статуса подключения
+const isConnected = wsClient.isConnected(WebSocketNamespace.REASONING);
 
-sdk.chat.on('thinking_delta', (data) => {
-  console.log('Фрагмент мышления:', data.text);
-});
+// Отключение от определенного namespace
+await wsClient.disconnect(WebSocketNamespace.REASONING);
 
-// Отключение 
-await sdk.chat.disconnectWebSocket();
+// Отключение от всех namespace
+await wsClient.disconnectAll();
 ```
 
-### Работа с зависимостями
+## Мониторинг индексации проектов
 
 ```javascript
-// Подключение к пространству имен зависимостей
-await sdk.dependencies.connectWebSocket(projectId);
-
-// Подписка на события зависимостей
-sdk.dependencies.on('dependency_update', (data) => {
-  console.log('Обновление зависимостей:', data);
-});
-
-// Отключение
-await sdk.dependencies.disconnectWebSocket();
-```
-
-### Работа с проектами и индексацией
-
-```javascript
-// Подключение к пространству имен проектов
+// Подключение к WebSocket для проектов
 await sdk.projects.connectWebSocket();
 
-// Подписка на события индексации
+// Отслеживание прогресса индексации
 sdk.projects.on('indexing_progress', (data) => {
-  console.log('Прогресс индексации:', data.progress);
+  console.log(`Прогресс индексации: ${data.progress}%`);
+  console.log(`Обработано файлов: ${data.processedFiles} из ${data.totalFiles}`);
 });
 
-// Отключение
-await sdk.projects.disconnectWebSocket();
-```
+// Завершение индексации
+sdk.projects.on('indexing_complete', (data) => {
+  console.log('Индексация завершена!', data.success ? 'Успешно' : 'С ошибками');
+  
+  // Отключение после завершения
+  sdk.projects.disconnectWebSocket();
+});
 
-## Потоковая передача мышления
+// Остановка индексации
+await sdk.projects.stopIndexing(projectId);
+```
 
-В версии 1.7.2 добавлена полная поддержка потоковой передачи мышления через метод `streamChatWithThinking`:
+## Потоковый чат с мышлением AI
 
 ```javascript
-// Обработчик событий
+// Обработчик событий для потокового получения ответа и мышления
 const handleEvent = (eventType, data) => {
-  switch(eventType) {
-    case 'thinking_delta':
-      console.log('Мышление:', data.text);
-      break;
-    case 'text_delta':
-      console.log('Ответ:', data.text);
-      break;
-    case 'message_start':
-      console.log('Начало сообщения');
-      break;
-    case 'message_stop':
-      console.log('Завершение ответа');
-      break;
+  if (eventType === 'thinking_delta' && data.thinking) {
+    console.log('Мышление:', data.thinking);
+  } else if (eventType === 'text_delta' && data.text) {
+    process.stdout.write(data.text); // Вывод текста без переноса строки
+  } else if (eventType === 'message_stop') {
+    console.log('\nОтвет завершен');
   }
 };
 
-// Отправка запроса с потоковым мышлением
+// Отправка запроса 
 const messages = [
-  { role: 'user', content: 'Как работает квантовый компьютер?' }
+  { role: 'user', content: 'Расскажи о JavaScript' }
 ];
 
 const options = {
@@ -135,374 +87,213 @@ const options = {
 };
 
 const response = await sdk.chat.streamChatWithThinking(
-  messages,
+  messages, 
   options,
   handleEvent
 );
-```
-
-### Поддерживаемые события мышления
-
-SDK поддерживает следующие ключевые события:
 
-| Событие | Описание | Данные |
-|---------|----------|--------|
-| `message_start` | Начало сообщения | `{ model: string, type: string }` |
-| `content_block_start` | Начало блока контента | `{ index: number, type: string }` |
-| `thinking_delta` | Фрагмент мышления | `{ text: string, index: number }` |
-| `text_delta` | Фрагмент ответа | `{ text: string, index: number }` |
-| `content_block_stop` | Завершение блока контента | `{ index: number, type: string }` |
-| `message_stop` | Завершение сообщения | `{ type: string }` |
-
-## Управление сессиями рассуждений
-
-SDK версии 1.7.0+ предоставляет расширенные возможности для управления сессиями рассуждений:
+console.log(`Socket ID: ${response.socketId}`);
+```
 
-### Установка активной сессии рассуждения
+## Работа с рассуждениями через WebSocket
 
 ```javascript
-// Простая установка активного ID рассуждения
-wsClient.setActiveReasoningId('reasoning-id');
-
-// Расширенный вариант с дополнительными возможностями
-await wsClient.setActiveReasoningIdAsync(
-  'reasoning-id', // ID рассуждения (можно передать null для создания нового)
-  true,           // waitForJoin: ждать результата присоединения
-  true            // createIfNotExists: создать новое, если не существует
-);
-```
+// Создание рассуждения
+const reasoning = await sdk.reasoning.createReasoning({
+  projectId: 'project-id',
+  query: 'Объясни этот проект'
+});
 
-### Создание нового рассуждения
+// Подключение к WebSocket для рассуждений
+await sdk.reasoning.connectWebSocket(reasoning.id);
 
-```javascript
-// Создание нового рассуждения и получение его ID
-const newReasoningId = await wsClient.createNewReasoning();
-console.log('Создано новое рассуждение:', newReasoningId);
-```
+// Подписка на события
+sdk.reasoning.on('thinking', (data) => {
+  console.log('Мышление:', data.content);
+});
 
-### Проверка существования рассуждения
+sdk.reasoning.on('complete', (data) => {
+  console.log('Результат:', data.content);
+  // Отключение после завершения
+  sdk.reasoning.disconnectWebSocket();
+});
 
-```javascript
-// Проверка существования рассуждения на сервере
-const exists = await wsClient.checkReasoningExists('reasoning-id');
-if (exists) {
-  console.log('Рассуждение существует');
-} else {
-  console.log('Рассуждение не найдено');
-}
+// Запуск рассуждения
+await sdk.reasoning.startReasoning(reasoning.id);
 ```
 
-### Получение статуса рассуждения
+## Настройка параметров WebSocket
 
 ```javascript
-// Получение детальной информации о сессии рассуждения
-const status = await wsClient.getReasoningStatus('reasoning-id');
-console.log('Статус:', status.exists, status.isActive);
-console.log('Метаданные:', status.metadata);
+// Настройка параметров WebSocket при создании SDK
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key',
+  websocket: {
+    reconnect: true,                // Автоматическое переподключение
+    reconnectAttempts: 5,           // Максимальное количество попыток
+    reconnectDelay: 3000,           // Задержка между попытками (мс)
+    rejectUnauthorized: true,       // Проверка SSL-сертификатов
+    reconnectStrategy: 'exponential', // Стратегия задержки между попытками
+    enableAutoPing: true,           // Автоматический ping/pong
+    pingInterval: 25000,            // Интервал ping в мс
+    enableSessionPersistence: true  // Сохранение сессии
+  }
+});
 ```
 
-### Присоединение к сессии рассуждения
+## Обработка ошибок в WebSocket
 
 ```javascript
-// Явное присоединение к существующей сессии
-const joined = await wsClient.joinReasoning(
-  'reasoning-id',
-  true // setActive: установить как активное рассуждение
-);
-
-if (joined) {
-  console.log('Успешно присоединились к рассуждению');
-} else {
-  console.log('Не удалось присоединиться к рассуждению');
+try {
+  await sdk.projects.connectWebSocket();
+  
+  // Подписка на события ошибок
+  sdk.projects.on('error', (error) => {
+    console.error('Ошибка WebSocket:', error.message);
+    if (error.type === 'connection_error') {
+      console.error('Проблема с подключением');
+    } else if (error.type === 'authentication_error') {
+      console.error('Ошибка аутентификации');
+    }
+  });
+} catch (error) {
+  console.error('Ошибка при подключении:', error.message);
 }
 ```
 
-## Диагностика соединений
+## Модули с поддержкой WebSocket
 
-SDK предоставляет методы для диагностики состояния соединений и получения подробной информации о них:
+### Чат и рассуждения
 
 ```javascript
-// Диагностика конкретного соединения
-const diagnostics = wsClient.diagnoseConnection(WebSocketNamespace.REASONING);
-console.log('Диагностика соединения:', diagnostics);
-
-// Диагностика всех активных соединений
-const allDiagnostics = wsClient.diagnoseAllConnections();
-console.log('Все соединения:', allDiagnostics);
-```
-
-Результат диагностики содержит следующую информацию:
-
-```typescript
-interface ConnectionDiagnostics {
-  namespace: WebSocketNamespace;  // Пространство имен
-  isConnected: boolean;          // Активно ли соединение
-  socketId: string | null;       // ID сокета
-  lastActivity: number;          // Время последней активности
-  rtt: {                         // Round Trip Time (задержка)
-    current: number;             // Текущая задержка
-    min: number;                 // Минимальная задержка
-    max: number;                 // Максимальная задержка
-    avg: number;                 // Средняя задержка
-  };
-  pingSent: number;              // Отправлено ping-сообщений
-  pongReceived: number;          // Получено pong-ответов
-  missedPongs: number;           // Пропущено pong-ответов
-  timeoutCount: number;          // Количество таймаутов
-  reconnectAttempts: number;     // Количество попыток переподключения
-  lastConnectTime: number;       // Время последнего подключения
-  sessionRecovery: {             // Информация о восстановлении сессии
-    hasSessionToken: boolean;    // Наличие токена сессии
-    tokenLength: number;         // Длина токена сессии
-    wasRecovered: boolean;       // Было ли восстановлено из сессии
-  };
-}
-```
-
-## Механизм переподключения
+// Подключение WebSocket для чата
+await sdk.chat.connectWebSocket();
 
-SDK реализует интеллектуальный механизм переподключения с экспоненциальной задержкой и случайным фактором (jitter) для предотвращения штормов переподключений:
+// Подписка на события
+sdk.chat.on('message_start', (data) => {
+  console.log('Начало сообщения:', data);
+});
 
-```javascript
-// Настройка параметров переподключения при создании SDK
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://api.example.com',
-  apiKey: 'your-api-key',
-  websocket: {
-    reconnect: true,               // Включить автоматическое переподключение
-    reconnectStrategy: 'exponential', // 'linear' или 'exponential'
-    retryDelay: 1000,                // Базовая задержка в миллисекундах
-    maxRetryDelay: 30000,            // Максимальная задержка
-    reconnectAttempts: 5             // Максимальное количество попыток
+sdk.chat.on('content_block_delta', (data) => {
+  if (data.delta?.type === 'thinking_delta') {
+    console.log('Фрагмент мышления:', data.delta.thinking);
   }
 });
 
-// Принудительное переподключение к пространству имен
-await wsClient.reconnectNamespace(
-  WebSocketNamespace.REASONING,
-  true // immediate: переподключиться немедленно, без задержки
-);
+// Отключение 
+await sdk.chat.disconnectWebSocket();
 ```
 
-## Сохранение и восстановление сессий
-
-SDK поддерживает механизм сохранения и восстановления токенов сессий для непрерывной работы при переподключениях:
+### Зависимости
 
 ```javascript
-// Явное сохранение токена сессии
-wsClient.saveSessionToken(WebSocketNamespace.REASONING, 'session-token');
-
-// Получение сохраненного токена
-const token = wsClient.getSessionToken(WebSocketNamespace.REASONING);
-
-// Очистка токена сессии
-wsClient.clearSessionToken(WebSocketNamespace.REASONING);
+// Подключение к пространству имен зависимостей
+await sdk.dependencies.connectWebSocket(projectId);
 
-// Включение/отключение сохранения сессий при создании SDK
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://api.example.com',
-  apiKey: 'your-api-key',
-  websocket: {
-    enableSessionPersistence: true // Включить сохранение токенов сессий
-  }
+// Подписка на события зависимостей
+sdk.dependencies.on('dependency_update', (data) => {
+  console.log('Обновление зависимостей:', data);
 });
-```
 
-## Проверка здоровья соединений
+// Отключение
+await sdk.dependencies.disconnectWebSocket();
+```
 
-SDK предоставляет механизм регулярной проверки здоровья соединений и автоматического переподключения при обнаружении проблем:
+### Проекты и индексация
 
 ```javascript
-// Настройка проверки здоровья соединений
-wsClient.setupConnectionHealthCheck(
-  30000 // Интервал проверки в миллисекундах
-);
-
-// Отключение проверки здоровья
-if (wsClient.healthCheckTimer) {
-  clearInterval(wsClient.healthCheckTimer);
-  wsClient.healthCheckTimer = null;
-}
-```
-
-## Работа с ping/pong
+// Подключение к пространству имен проектов
+await sdk.projects.connectWebSocket();
 
-Для поддержания активных соединений и измерения времени отклика SDK использует механизм ping/pong:
+// Подписка на события индексации
+sdk.projects.on('indexing_progress', (data) => {
+  console.log('Прогресс индексации:', data.progress);
+});
 
-```javascript
-// Включение автоматического ping/pong
-wsClient.enablePingPong(
-  15000, // Интервал между ping-сообщениями (мс)
-  3      // Порог таймаута (количество пропущенных pong)
-);
+// Отключение
+await sdk.projects.disconnectWebSocket();
+```
 
-// Отключение механизма ping/pong
-wsClient.disablePingPong();
+## Поддерживаемые события
 
-// Получение статистики ping/pong
-const stats = wsClient.getPingStats(WebSocketNamespace.REASONING);
-console.log('Статистика ping/pong:', stats);
+Основные события, на которые можно подписаться:
 
-// Подписка на события таймаута соединения
-wsClient.onPingPongEvent('connection_timeout', (data) => {
-  console.log('Таймаут соединения:', data);
-});
-```
+| Событие | Описание | Примечание |
+|---------|----------|------------|
+| `message_start` | Начало сообщения | { id, model, type } |
+| `content_block_start` | Начало блока контента | { content_block: { type }, index } |
+| `content_block_delta` | Дельта блока контента | См. документацию для типов дельт |
+| `content_block_stop` | Конец блока контента | { content_block: { type }, index } |
+| `message_stop` | Конец сообщения | { id, type, stop_reason } |
+| `error` | Ошибка | { message, code, ... } |
 
-## Примеры использования
+## Потоковая передача мышления
 
-### Работа с потоковой передачей мышления
+Самый простой способ получать мышление — использовать метод `streamChatWithThinking`:
 
 ```javascript
-const { CodeSolverSDK } = require('solver-sdk');
-
-async function streamingThinking() {
-  const sdk = new CodeSolverSDK({
-    baseURL: 'https://api.example.com',
-    apiKey: 'ваш-ключ-api',
-    websocket: {
-      reconnect: true,
-      pingInterval: 30000
-    }
-  });
-  
-  // Подключаем WebSocket
-  await sdk.chat.connectWebSocket();
-  
-  // Создаем буферы для накопления контента
-  let thinkingBuffer = '';
-  let responseBuffer = '';
-  
-  // Настраиваем обработчик событий
-  const handleEvent = (eventType, data) => {
-    switch(eventType) {
-      case 'thinking_delta':
-        thinkingBuffer += data.text || '';
-        // Обновляем UI с мышлением
-        updateThinkingUI(thinkingBuffer);
-        break;
-        
-      case 'text_delta':
-        responseBuffer += data.text || '';
-        // Обновляем UI с ответом
-        updateResponseUI(responseBuffer);
-        break;
-        
-      case 'message_stop':
-        console.log('Обработка завершена');
-        break;
-    }
-  };
-  
-  // Отправляем запрос
-  const messages = [
-    { role: 'user', content: 'Объясни принцип работы квантового компьютера' }
-  ];
-  
-  try {
-    const response = await sdk.chat.streamChatWithThinking(
-      messages,
-      {
-        model: 'claude-3-7-sonnet-20240229',
-        thinking: true,
-        temperature: 0.7
-      },
-      handleEvent
-    );
-    
-    console.log('Запрос отправлен, ID сокета:', response.socketId);
-    
-    // После завершения можно отключиться
-    setTimeout(() => {
-      sdk.chat.disconnectWebSocket();
-      console.log('Соединение закрыто');
-    }, 1000);
-    
-    return {
-      thinking: thinkingBuffer,
-      response: responseBuffer
-    };
-  } catch (error) {
-    console.error('Ошибка при отправке запроса:', error);
-    sdk.chat.disconnectWebSocket();
-    throw error;
+// Обработчик событий
+const handleEvent = (eventType, data) => {
+  if (eventType === 'content_block_delta' && data.delta?.type === 'thinking_delta') {
+    console.log('Мышление:', data.delta.thinking);
+  } else if (eventType === 'content_block_delta' && data.delta?.type === 'text_delta') {
+    console.log('Ответ:', data.delta.text);
+  } else if (eventType === 'message_stop') {
+    console.log('Завершение ответа');
   }
-}
+};
 
-// Функции для обновления UI
-function updateThinkingUI(text) {
-  console.log('Обновление блока мышления');
-  // document.getElementById('thinking-container').textContent = text;
-}
+// Отправка запроса с потоковым мышлением
+const messages = [
+  { role: 'user', content: 'Объясни квантовую механику' }
+];
 
-function updateResponseUI(text) {
-  console.log('Обновление блока ответа');
-  // document.getElementById('response-container').textContent = text;
-}
+const options = {
+  model: 'claude-3-7-sonnet-20240229',
+  thinking: true,
+  temperature: 0.7
+};
 
-// Запуск функции
-streamingThinking().catch(console.error);
+const response = await sdk.chat.streamChatWithThinking(
+  messages,
+  options,
+  handleEvent
+);
 ```
 
-### Работа с региональным переключением
+## Обработка ошибок
 
 ```javascript
-const { CodeSolverSDK } = require('solver-sdk');
-
-async function chatWithRegionalFailover() {
-  const sdk = new CodeSolverSDK({
-    baseURL: 'https://api.example.com',
-    apiKey: 'ваш-ключ-api',
-    providers: {
-      anthropic: {
-        region: 'us-east-1' // Базовый регион
-      }
-    }
-  });
-  
-  // Подключаем WebSocket
-  await sdk.chat.connectWebSocket();
-  
-  // Настраиваем обработчик для отображения региона и ошибок
-  sdk.chat.on('region_switch', (data) => {
-    console.log(`Переключение на регион: ${data.region}`);
-  });
-  
-  sdk.chat.on('error', (data) => {
-    console.error('Ошибка:', data);
-  });
-  
-  // Отправляем запрос с автоматическим переключением регионов при ошибках
-  try {
-    const response = await sdk.chat.chatWithRegionFailover(
-      [{ role: 'user', content: 'Расскажи о квантовой физике' }],
-      {
-        model: 'claude-3-7-sonnet-20240229',
-        thinking: true,
-        // Порядок перебора регионов при ошибках
-        regionPreference: ['us-east-1', 'eu-west-1', 'ap-southeast-2']
-      }
-    );
-    
-    console.log('Ответ получен из региона:', response.region);
-    console.log('Ответ:', response.choices[0].message.content);
-    
-    return response;
-  } catch (error) {
-    console.error('Не удалось получить ответ ни из одного региона:', error);
-    throw error;
-  } finally {
-    await sdk.chat.disconnectWebSocket();
+try {
+  await sdk.chat.streamChatWithThinking(
+    messages,
+    options,
+    handleEvent
+  );
+} catch (error) {
+  if (error.code === 'CONNECTION_ERROR') {
+    console.error('Ошибка подключения:', error.message);
+  } else {
+    console.error('Произошла ошибка:', error.message);
   }
 }
-
-chatWithRegionalFailover().catch(console.error);
 ```
 
-## Справочник всех событий WebSocket
-
-Полный список всех поддерживаемых WebSocket событий, их описание, формат данных и примеры использования доступны в отдельном документе:
+## Настройка WebSocket
 
-[Справочник WebSocket событий SDK](./WEBSOCKET_EVENTS.md)
+```javascript
+// Настройка параметров WebSocket при создании SDK
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key',
+  websocket: {
+    reconnect: true,               // Автоматическое переподключение
+    reconnectAttempts: 5,           // Максимальное количество попыток
+    rejectUnauthorized: false       // Для самоподписанных сертификатов
+  }
+});
+```
+## Дополнительная информация
 
-В этом справочнике содержится подробная информация обо всех константах событий, их строковых значениях, форматах данных и рекомендациях по использованию в различных сценариях.
+Для детального описания всех возможностей WebSocket, смотрите [руководство по мышлению](./features/THINKING.md) и примеры в директории [examples/websocket](../examples/websocket).