solver-sdk 2.0.2 → 2.0.3

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

@@ -47,6 +47,9 @@ const project = await sdk.projects.createProject(
   }
 );
 
+// Единое подключение ко всем WebSocket сервисам с указанием ID проекта
+await sdk.connect(project.id);
+
 // Индексация проекта
 await sdk.projects.indexProject(project.id);
 
@@ -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,65 @@ 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  // Задержка между попытками (мс)
+  }
 });
+
+// Общее подключение к базовым WebSocket сервисам
+await sdk.connect();
 ```
 
-## Работа с рассуждениями (Reasoning)
+## Работа с файловой системой
+
+```javascript
+// Обязательно: для файловой системы projectId всегда необходим
+const projectId = 'your-project-id';
+
+// Метод 1: Подключение через файловую систему 
+await sdk.filesystem.connectWebSocket(projectId);
+
+// Метод 2: Альтернативный способ подключения
+await sdk.filesystem.connectToProject(projectId);
 
-### Создание рассуждения и получение результатов в реальном времени
+// Чтение файла через REST API (предпочтительный метод)
+const content = await sdk.context.getFileContent(projectId, 'src/index.js');
+
+// Отключение
+await sdk.filesystem.disconnectWebSocket();
+```
+
+## Работа с индексацией проектов
+
+```javascript
+// Подключение к WebSocket для проектов без указания projectId
+await sdk.projects.connectWebSocket();
+
+// Или можно сразу указать проект (projectId опциональный)
+await sdk.projects.connectWebSocket('project-id');
+
+// Отслеживание прогресса индексации
+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,8 +77,12 @@ const reasoning = await sdk.reasoning.createReasoning({
   query: 'Объясни этот проект'
 });
 
-// Подключение к WebSocket
-await sdk.reasoning.connectWebSocket(reasoning.id);
+// Подключение к WebSocket для рассуждений
+// Не требует projectId в методе connectWebSocket
+await sdk.reasoning.connectWebSocket();
+
+// Присоединение к конкретному рассуждению
+await sdk.reasoning.joinReasoning(reasoning.id);
 
 // Подписка на события
 sdk.reasoning.on('thinking', (data) => {
@@ -43,6 +99,36 @@ sdk.reasoning.on('complete', (data) => {
 await sdk.reasoning.startReasoning(reasoning.id);
 ```
 
+## Работа с зависимостями
+
+```javascript
+// Подключение к WebSocket для зависимостей без указания projectId
+await sdk.dependencies.connectWebSocket();
+
+// Затем необходимо присоединиться к конкретному проекту
+await sdk.dependencies.joinProject('your-project-id');
+
+// Подписка на события зависимостей
+sdk.dependencies.on('dependency_update', (data) => {
+  console.log('Обновление зависимостей:', data);
+});
+
+// Отключение
+await sdk.dependencies.disconnectWebSocket();
+```
+
+## Смена активного проекта
+
+SDK поддерживает концепцию "активного проекта", что позволяет переключаться между проектами без полного переподключения:
+
+```javascript
+// Установка активного проекта
+sdk.setActiveProject('new-project-id');
+
+// После этого вызова SDK автоматически переподключит 
+// filesystem-namespace к новому проекту
+```
+
 ## Потоковый чат с мышлением AI
 
 ```javascript
@@ -65,7 +151,8 @@ const messages = [
 const options = {
   model: 'claude-3-7-sonnet-20240229',
   thinking: true,
-  temperature: 0.7
+  temperature: 0.7,
+  projectId: 'project-id' // Указываем projectId для контекста проекта
 };
 
 // Отправка с потоковым получением ответа
@@ -76,57 +163,116 @@ const response = await sdk.chat.streamChatWithThinking(
 );
 ```
 
-## Мониторинг индексации проектов
+## Автоматический ping/pong и reconnect
 
-```javascript
-// Подключение к WebSocket для проектов
-await sdk.projects.connectWebSocket();
+WebSocket клиенты в SDK автоматически обрабатывают ping/pong сообщения и reconnect:
 
-// Отслеживание прогресса индексации
-sdk.projects.on('indexing_progress', (data) => {
-  console.log(`Прогресс индексации: ${data.progress}%`);
-  console.log(`Обработано файлов: ${data.processedFiles} из ${data.totalFiles}`);
+```javascript
+// Все WebSocket клиенты имеют автоматический ping/pong
+// с настраиваемыми таймаутами
+const sdk = new CodeSolverSDK({
+  websocket: {
+    pingInterval: 25000,  // Интервал отправки ping (мс)
+    pingTimeout: 10000,   // Таймаут ожидания pong (мс)
+    reconnect: true,      // Автоматическое переподключение
+    reconnectAttempts: 5  // Макс. количество попыток
+  }
 });
 
-// Завершение индексации
-sdk.projects.on('indexing_complete', (data) => {
-  console.log('Индексация завершена!', data.success ? 'Успешно' : 'С ошибками');
-  
-  // Отключение после завершения
-  sdk.projects.disconnectWebSocket();
-});
+// При разрыве соединения SDK попытается автоматически переподключиться
+// Вам не нужно писать свой код для обработки reconnect
 ```
 
-## Работа с зависимостями
+## Метод connect в SDK и пространства имен
+
+Метод `sdk.connect()` подключает только базовые пространства имен и не устанавливает подключение ко всем сервисам:
 
 ```javascript
-// Подключение к пространству имен зависимостей
-await sdk.dependencies.connectWebSocket(projectId);
+// Общее подключение не передает projectId для файловой системы
+await sdk.connect();
 
-// Подписка на события зависимостей
-sdk.dependencies.on('dependency_update', (data) => {
-  console.log('Обновление зависимостей:', data);
-});
+// Поэтому для работы с файловой системой нужно явно подключиться
+await sdk.filesystem.connectWebSocket('your-project-id');
 
-// Отключение
-await sdk.dependencies.disconnectWebSocket();
+// Или можно при подключении сразу указать projectId, который будет использован для подключения к файловой системе
+await sdk.connect('your-project-id');
 ```
 
-## Обработка ошибок
+## Сравнение сигнатур методов connectWebSocket
+
+| API | Метод | Требуется projectId? |
+|-----|-------|---------------------|
+| `sdk.filesystem` | `connectWebSocket(projectId)` | **Обязательно** |
+| `sdk.filesystem` | `connectToProject(projectId)` | **Обязательно** |
+| `sdk.projects` | `connectWebSocket([projectId])` | **Опционально** |
+| `sdk.reasoning` | `connectWebSocket()` | **Нет** |
+| `sdk.reasoning` | `joinReasoning(reasoningId)` | **Обязательно** |
+| `sdk.dependencies` | `connectWebSocket()` | **Нет** |
+| `sdk.dependencies` | `joinProject(projectId)` | **Обязательно** |
+
+## Обработка ошибок и переподключение
+
+Используйте параметры `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;
+}
+
+// Подключение к WebSocket серверу
+const connected = await sdk.connect();
+if (!connected) {
+  console.warn('WebSocket соединение не установлено, работа будет ограничена');
 }
+
+// Для работы с файловой системой необходимо отдельное подключение с projectId
+const projectId = 'your-project-id';
+await sdk.filesystem.connectWebSocket(projectId);
+```
+
+## Использование в Cursor
+
+В Cursor клиенте projectId обычно получается через API проектов:
+
+```javascript
+// Получаем projectId для текущей рабочей области
+const workspacePath = '/path/to/project';
+const project = await sdk.projects.getOrCreateProjectByPath(workspacePath);
+const projectId = project.id;
+
+// Используем полученный projectId для подключения к файловой системе
+await sdk.filesystem.connectWebSocket(projectId);
 ```
 
-## Основные события
+## Статус реализации функций
+
+| Функция | Статус | Примечание |
+|---------|--------|------------|
+| `sdk.connect()` | ✅ Реализовано | Включает базовое подключение ко всем namespace |
+| `sdk.setActiveProject()` | ✅ Реализовано | Работает в связке с filesystem-клиентом |
+| `sdk.filesystem.connectWebSocket()` | ✅ Реализовано | Подключение к WebSocket для файловой системы |
+| `sdk.filesystem.connectToProject()` | ✅ Реализовано | Альтернативный синтаксис для connectWebSocket |
+| `sdk.context.getFileContent()` | ✅ Реализовано | Рекомендуемый метод для чтения файлов (через REST) |
+| `sdk.projects.connectWebSocket()` | ✅ Реализовано | Подключение к namespace индексации |
+| `sdk.reasoning.connectWebSocket()` | ✅ Реализовано | Требует последующего `joinReasoning()` |
+| `sdk.dependencies.connectWebSocket()` | ✅ Реализовано | Требует последующего `joinProject()` |
+| `sdk.chat.streamChatWithThinking()` | ✅ Реализовано | Потоковое получение ответов с мышлением |
+
+## Основные события WebSocket
 
 | Событие | Описание |
 |---------|----------|
@@ -136,4 +282,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.0.3",
   "description": "SDK для интеграции с Code Solver Backend API",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",