solver-sdk 2.0.2 → 2.1.0

package/docs/PING_PONG.md

@@ -1,212 +1,113 @@
-# WebSocket Ping/Pong механизм
+# Механизм Ping/Pong для WebSocket
 
-Данный документ описывает механизм поддержания WebSocket соединений и мониторинга их состояния через ping/pong обмен.
+Для поддержания активных WebSocket соединений и проверки их состояния SDK использует механизм ping/pong.
 
-## Обзор функциональности
+## Что такое ping/pong?
 
-SDK поддерживает автоматический механизм отправки ping-сообщений и обработки pong-ответов для:
+Ping/pong - это механизм отправки специальных сообщений между клиентом и сервером для проверки активности соединения. 
+Клиент периодически отправляет сообщение "ping", на которое сервер должен ответить сообщением "pong".
+Если ответа нет в течение определенного времени, соединение считается разорванным.
 
-1. **Проверки активности соединения** - обнаружение разрывов соединения даже в отсутствие активности
-2. **Измерения времени отклика (Round Trip Time, RTT)** - мониторинг качества соединения
-3. **Сбора статистики соединения** - для диагностики и отладки
-4. **Автоматического обнаружения проблем** - уведомление о потере соединения
+## Как это работает в SDK?
 
-## Включение механизма ping/pong
+SDK автоматически настраивает и управляет ping/pong механизмом, когда вы используете следующие высокоуровневые методы:
 
-```typescript
-import { CodeSolverSDK, WebSocketNamespace } from 'solver-sdk';
+```javascript
+// Подключение к WebSocket пространствам имен
+await sdk.connect(); // Подключается ко всем пространствам имен
 
-// Создаем экземпляр SDK
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://api.example.com',
-  apiKey: 'your-api-key'
-});
+// Или более специфичные подключения
+await sdk.reasoning.connectWebSocket(reasoningId);
+await sdk.dependencies.connectWebSocket(projectId);
+await sdk.projects.connectWebSocket();
+```
 
-// Получаем WebSocket клиент
-const wsClient = sdk.getWebSocketClient();
+### Настройка ping/pong
 
-// Подключаемся к пространствам имен
-await wsClient.connectToReasoning();
-await wsClient.connectToDependencies();
-await wsClient.connectToIndexing();
+По умолчанию SDK использует следующие настройки:
+- Интервал ping: 25 секунд
+- Таймаут ожидания pong: 60 секунд
 
-// Включаем автоматический механизм ping/pong
-// параметры: интервал отправки в мс (по умолчанию 30000) и порог таймаута (по умолчанию 3)
-wsClient.enablePingPong(10000, 3);
+Эти настройки можно изменить при инициализации SDK:
 
-// Регистрируем обработчик для события таймаута соединения
-wsClient.onPingPongEvent('connection_timeout', (data) => {
-  console.log(`Соединение потеряно для namespace ${data.namespace}`);
-  console.log(`Socket ID: ${data.socketId}`);
-  console.log(`Количество пропущенных pong: ${data.timeouts}`);
-  
-  // Здесь можно добавить логику переподключения или уведомления пользователя
+```javascript
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key',
+  websocket: {
+    pingInterval: 30000,  // 30 секунд
+    pingTimeout: 90000    // 90 секунд
+  }
 });
 ```
 
-## Отключение механизма ping/pong
+### Преимущества автоматического ping/pong
 
-```typescript
-// Отключение для всех пространств имен
-wsClient.disablePingPong();
+1. **Обнаружение разрывов соединения**: Если сервер не отвечает на ping, SDK обнаружит разрыв соединения.
+2. **Предотвращение тайм-аутов**: Регулярные ping/pong сообщения поддерживают соединение активным и предотвращают тайм-ауты на промежуточных серверах и брандмауэрах.
+3. **Автоматическое переподключение**: SDK может автоматически переподключаться при обнаружении разрыва соединения.
 
-// Отключение для конкретного пространства имен
-wsClient.disablePingPong(WebSocketNamespace.REASONING);
-```
-
-## Получение статистики ping/pong
-
-```typescript
-// Получение статистики для всех пространств имен
-const allStats = wsClient.getPingStats();
-console.log('Статистика для всех соединений:', allStats);
-
-// Получение статистики для конкретного пространства имен
-const reasoningStats = wsClient.getPingStats(WebSocketNamespace.REASONING);
-console.log('Статистика для reasoning:', reasoningStats);
-
-// Пример содержимого статистики:
-// {
-//   namespace: '/reasoning',
-//   socketId: 'socket-id-123',
-//   pingSent: 10,           // Количество отправленных ping
-//   pongReceived: 10,       // Количество полученных pong
-//   averageRtt: 15.5,       // Среднее время отклика (мс)
-//   minRtt: 5,              // Минимальное время отклика (мс)
-//   maxRtt: 45,             // Максимальное время отклика (мс)
-//   lastRtt: 12,            // Последнее измеренное время отклика (мс)
-//   lastPongTimestamp: 1712345678901, // Timestamp последнего полученного pong
-//   isConnected: true       // Текущий статус соединения
-// }
-```
-
-## Ручная отправка ping/pong
+### События ping/pong
 
-Хотя SDK обеспечивает автоматический механизм ping/pong, вы также можете вручную отправлять ping-сообщения:
+SDK предоставляет события для отслеживания состояния ping/pong:
 
-```typescript
-// Отправка ping и получение pong
-wsClient.send(WebSocketNamespace.REASONING, 'connection_ping', { 
-  timestamp: Date.now() 
+```javascript
+// Настройка обработчиков для всех WebSocket соединений
+sdk.on('connection_timeout', async (data) => {
+  console.warn(`Соединение с ${data.namespace} истекло по тайм-ауту`);
+  // Автоматически SDK попытается переподключиться
 });
-
-// Добавление обработчика для pong-ответов
-wsClient.on('connection_pong', (data) => {
-  const rtt = Date.now() - data.echo;
-  console.log(`Получен pong, RTT: ${rtt}ms`);
-});
-
-// Альтернативно, можно использовать готовый обработчик
-wsClient.on('connection_pong', wsClient.getPongHandler());
 ```
 
-## Обработка отключений и переподключение
+## Рекомендуемые практики
 
-```typescript
-// Обработка события таймаута соединения
-wsClient.onPingPongEvent('connection_timeout', async (data) => {
-  console.log(`Соединение потеряно для ${data.namespace}`);
-  
-  // Попытка переподключения
-  try {
-    // Отключаемся от проблемного пространства имен
-    wsClient.disconnect(data.namespace);
-    
-    // Пауза перед повторным подключением
-    await new Promise(resolve => setTimeout(resolve, 1000));
-    
-    // Переподключаемся
-    switch (data.namespace) {
-      case WebSocketNamespace.REASONING:
-        await wsClient.connectToReasoning();
-        break;
-      case WebSocketNamespace.DEPENDENCIES:
-        await wsClient.connectToDependencies();
-        break;
-      case WebSocketNamespace.INDEXING:
-        await wsClient.connectToIndexing();
-        break;
-    }
-    
-    console.log(`Успешно переподключились к ${data.namespace}`);
-  } catch (error) {
-    console.error(`Ошибка при переподключении к ${data.namespace}:`, error);
-  }
-});
-```
+1. **Используйте высокоуровневые методы подключения**: Самый простой способ обеспечить надежное соединение - использовать встроенные высокоуровневые методы SDK.
 
-## Рекомендации по использованию
+2. **Включите автоматическое переподключение**: При инициализации SDK установите параметры:
+   ```javascript
+   const sdk = new CodeSolverSDK({
+     baseURL: 'https://api.example.com',
+     apiKey: 'your-api-key',
+     websocket: {
+       reconnect: true,
+       reconnectAttempts: 5,
+       reconnectDelay: 2000
+     }
+   });
+   ```
 
-1. **Интервал ping/pong**: Рекомендуемый интервал - 30 секунд для продакшн и 5-10 секунд для отладки.
+3. **Обрабатывайте события тайм-аута**: Регистрируйте обработчики событий, чтобы знать, когда соединение было потеряно.
 
-2. **Порог таймаута**: Значение 2-3 пропущенных ping/pong позволяет избежать ложных срабатываний при временных задержках сети.
+4. **Правильно завершайте соединения**: Перед закрытием приложения вызывайте метод для отключения:
+   ```javascript
+   // Отключение перед закрытием приложения
+   await sdk.disconnect();
+   ```
 
-3. **Экономия трафика**: При частой передаче данных через WebSocket можно увеличить интервал ping/pong, так как регулярный обмен данными уже поддерживает соединение активным.
+## Пример обработки тайм-аутов
 
-4. **Мониторинг RTT**: Используйте statsPingStats для мониторинга задержек сети и раннего обнаружения проблем с соединением.
+```javascript
+// Инициализация SDK
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key'
+});
 
-5. **Отключение перед закрытием приложения**: Вызывайте disablePingPong() и затем disconnectAll() при закрытии приложения для корректного освобождения ресурсов.
+// Подключение к WebSocket
+await sdk.connect();
 
-## Пример комплексного использования
+// Обработка события тайм-аута
+sdk.on('connection_timeout', handleConnectionTimeout);
 
-```typescript
-async function setupWebSocketWithHealthMonitoring() {
-  const sdk = new CodeSolverSDK({
-    baseURL: 'https://api.example.com',
-    apiKey: 'your-api-key',
-    websocket: {
-      reconnect: true,
-      reconnectAttempts: 5,
-      reconnectDelay: 2000
-    }
-  });
-  
-  const wsClient = sdk.getWebSocketClient();
-  
-  // Подключаемся ко всем пространствам имен
-  await wsClient.connectToReasoning();
-  await wsClient.connectToDependencies();
-  await wsClient.connectToIndexing();
+// Функция обработки тайм-аута
+async function handleConnectionTimeout(data) {
+  console.warn(`Соединение с ${data.namespace} прервано по тайм-ауту`);
   
-  // Включаем механизм ping/pong для всех соединений
-  wsClient.enablePingPong(20000, 3);
-  
-  // Регистрируем обработчик для события таймаута
-  wsClient.onPingPongEvent('connection_timeout', handleConnectionTimeout);
-  
-  // Периодически проверяем статистику соединений
-  const statsInterval = setInterval(() => {
-    const stats = wsClient.getPingStats();
-    
-    // Анализируем статистику
-    for (const stat of stats) {
-      if (stat.averageRtt > 500) {
-        console.warn(`Высокая задержка для ${stat.namespace}: ${stat.averageRtt}ms`);
-      }
-    }
-  }, 60000); // Проверка каждую минуту
-  
-  // Функция для обработки таймаута соединения
-  async function handleConnectionTimeout(data) {
-    console.error(`Соединение потеряно для ${data.namespace}`);
-    
-    // Логика переподключения...
-  }
-  
-  // Функция для корректного закрытия соединений
-  function cleanup() {
-    clearInterval(statsInterval);
-    wsClient.disablePingPong();
-    wsClient.disconnectAll();
-  }
-  
-  // Возвращаем функцию очистки
-  return cleanup;
+  // Вы можете добавить свою логику обработки
+  // Например, уведомить пользователя или попытаться переподключиться
 }
 
-// Использование
-const cleanup = await setupWebSocketWithHealthMonitoring();
-
-// При закрытии приложения
-window.addEventListener('beforeunload', cleanup);
+// Перед закрытием приложения
+// Корректно отключаемся
+await sdk.disconnect();
 ``` 

package/docs/README.md

@@ -38,6 +38,9 @@ if (!isAvailable) {
   return;
 }
 
+// Единое подключение ко всем WebSocket сервисам
+await sdk.connect();
+
 // Создание проекта
 const project = await sdk.projects.createProject(
   'Мой проект',
@@ -88,9 +91,10 @@ console.log(chatResponse.answer);
 Подробная документация доступна в следующих файлах:
 
 - [API Reference](./API_REFERENCE.md) - подробное описание всех методов SDK
-- [Authentication](./AUTHENTICATION.md) - информация по аутентификации
-- [Работа с WebSocket](./WEBSOCKET.md) - примеры работы с WebSocket соединениями
-- [Примеры интеграции](./INTEGRATION_EXAMPLES.md) - примеры интеграции с VS Code/Cursor
+- [WebSocket](./WEBSOCKET.md) - примеры работы с WebSocket соединениями
+- [Примеры интеграции](./INTEGRATION_EXAMPLES.md) - примеры интеграции с VS Code/Cursor и другими приложениями
+- [Аутентификация](./AUTHENTICATION.md) - информация по процессу аутентификации
+- [Обработка ошибок](./ERROR_HANDLING.md) - руководство по обработке ошибок
 
 ## Поддерживаемые платформы
 

package/docs/WEBSOCKET.md

@@ -1,6 +1,6 @@
 # Работа с WebSocket в Solver SDK
 
-Эта документация описывает, как использовать WebSocket соединения через Solver SDK для работы в реальном времени.
+Эта документация описывает, как использовать WebSocket соединения через высокоуровневые методы Solver SDK для работы в реальном времени.
 
 ## Инициализация SDK
 
@@ -10,13 +10,43 @@ const { CodeSolverSDK } = require('solver-sdk');
 // Создаем экземпляр 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  // Задержка между попытками (мс)
+  }
 });
+
+// Единое подключение ко всем сервисам
+await sdk.connect();
 ```
 
-## Работа с рассуждениями (Reasoning)
+## Работа с индексацией проектов
+
+```javascript
+// Подключение к WebSocket для проектов
+await sdk.projects.connectWebSocket();
 
-### Создание рассуждения и получение результатов в реальном времени
+// Отслеживание прогресса индексации
+sdk.projects.on('indexing_progress', (data) => {
+  console.log(`Прогресс индексации: ${data.progress}%`);
+  console.log(`Обработано файлов: ${data.processedFiles} из ${data.totalFiles}`);
+});
+
+// Завершение индексации
+sdk.projects.on('indexing_complete', (data) => {
+  console.log('Индексация завершена!', data.success ? 'Успешно' : 'С ошибками');
+  
+  // Отключение после завершения
+  sdk.projects.disconnectWebSocket();
+});
+
+// Запуск индексации проекта
+await sdk.projects.indexProject('project-id');
+```
+
+## Работа с рассуждениями (Reasoning)
 
 ```javascript
 // Создание рассуждения
@@ -25,7 +55,7 @@ const reasoning = await sdk.reasoning.createReasoning({
   query: 'Объясни этот проект'
 });
 
-// Подключение к WebSocket
+// Подключение к WebSocket для рассуждений
 await sdk.reasoning.connectWebSocket(reasoning.id);
 
 // Подписка на события
@@ -76,27 +106,6 @@ const response = await sdk.chat.streamChatWithThinking(
 );
 ```
 
-## Мониторинг индексации проектов
-
-```javascript
-// Подключение к WebSocket для проектов
-await sdk.projects.connectWebSocket();
-
-// Отслеживание прогресса индексации
-sdk.projects.on('indexing_progress', (data) => {
-  console.log(`Прогресс индексации: ${data.progress}%`);
-  console.log(`Обработано файлов: ${data.processedFiles} из ${data.totalFiles}`);
-});
-
-// Завершение индексации
-sdk.projects.on('indexing_complete', (data) => {
-  console.log('Индексация завершена!', data.success ? 'Успешно' : 'С ошибками');
-  
-  // Отключение после завершения
-  sdk.projects.disconnectWebSocket();
-});
-```
-
 ## Работа с зависимостями
 
 ```javascript
@@ -112,21 +121,41 @@ sdk.dependencies.on('dependency_update', (data) => {
 await sdk.dependencies.disconnectWebSocket();
 ```
 
-## Обработка ошибок
+## Автоматическая авторизация
+
+**Важно:** Авторизация происходит автоматически, если указан `apiKey` при инициализации SDK. Отдельных действий для авторизации не требуется.
+
+## Обработка ошибок и переподключение
+
+Используйте параметры `reconnect` и `reconnectAttempts` для автоматического переподключения при разрыве соединения:
 
 ```javascript
-try {
-  await sdk.chat.streamChatWithThinking(
-    messages,
-    options,
-    handleEvent
-  );
-} catch (error) {
-  console.error('Произошла ошибка:', error.message);
+// Инициализация SDK с настройками переподключения
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key',
+  websocket: {
+    reconnect: true,
+    reconnectAttempts: 5,
+    reconnectDelay: 3000
+  }
+});
+
+// Проверка доступности сервера перед началом работы
+const isHealthy = await sdk.checkHealth();
+if (!isHealthy) {
+  console.error('API недоступен');
+  return;
+}
+
+// Попытка подключения
+const connected = await sdk.connect();
+if (!connected) {
+  console.warn('WebSocket соединение не установлено, работа будет ограничена');
 }
 ```
 
-## Основные события
+## Основные события WebSocket
 
 | Событие | Описание |
 |---------|----------|
@@ -136,4 +165,4 @@ try {
 | `message_stop` | Конец сообщения |
 | `indexing_progress` | Прогресс индексации |
 | `indexing_complete` | Завершение индексации |
-| `error` | Уведомление об ошибке |
+| `error` | Уведомление об ошибке |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solver-sdk",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "SDK для интеграции с Code Solver Backend API",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -34,6 +34,11 @@
     "build:esm": "tsc -p tsconfig.esm.json",
     "build:types": "tsc -p tsconfig.types.json",
     "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest",
+    "test:quick": "node quick-test.js",
+    "test:unit": "npx jest sdk-test/unit/ --testMatch=\"**/sdk-test/unit/**/*.test.js\"",
+    "test:mock": "./sdk-test/run-integration-tests.sh mock-only",
+    "test:integration": "./sdk-test/run-integration-tests.sh without-backend",
+    "test:integration:full": "./sdk-test/run-integration-tests.sh with-backend",
     "test:node": "cross-env NODE_OPTIONS=--experimental-vm-modules jest tests/node",
     "test:browser": "cross-env NODE_OPTIONS=--experimental-vm-modules jest tests/browser",
     "test:indexing": "NODE_TLS_REJECT_UNAUTHORIZED=0 node --experimental-vm-modules node_modules/.bin/jest tests/unit/indexing",
@@ -97,7 +102,7 @@
     "jest-junit": "^16.0.0",
     "rollup": "^4.12.0",
     "rollup-plugin-dts": "^6.1.1",
-    "rollup-plugin-terser": "^7.0.2",
+    "@rollup/plugin-terser": "^0.4.4",
     "ts-jest": "^29.1.2",
     "typescript": "^5.7.3",
     "ws": "^8.18.1"