solver-sdk 1.8.0 → 1.9.0

package/docs/PING_PONG.md

@@ -0,0 +1,212 @@
+# WebSocket Ping/Pong механизм
+
+Данный документ описывает механизм поддержания WebSocket соединений и мониторинга их состояния через ping/pong обмен.
+
+## Обзор функциональности
+
+SDK поддерживает автоматический механизм отправки ping-сообщений и обработки pong-ответов для:
+
+1. **Проверки активности соединения** - обнаружение разрывов соединения даже в отсутствие активности
+2. **Измерения времени отклика (Round Trip Time, RTT)** - мониторинг качества соединения
+3. **Сбора статистики соединения** - для диагностики и отладки
+4. **Автоматического обнаружения проблем** - уведомление о потере соединения
+
+## Включение механизма ping/pong
+
+```typescript
+import { CodeSolverSDK, WebSocketNamespace } from 'solver-sdk';
+
+// Создаем экземпляр SDK
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key'
+});
+
+// Получаем WebSocket клиент
+const wsClient = sdk.getWebSocketClient();
+
+// Подключаемся к пространствам имен
+await wsClient.connectToReasoning();
+await wsClient.connectToDependencies();
+await wsClient.connectToIndexing();
+
+// Включаем автоматический механизм ping/pong
+// параметры: интервал отправки в мс (по умолчанию 30000) и порог таймаута (по умолчанию 3)
+wsClient.enablePingPong(10000, 3);
+
+// Регистрируем обработчик для события таймаута соединения
+wsClient.onPingPongEvent('connection_timeout', (data) => {
+  console.log(`Соединение потеряно для namespace ${data.namespace}`);
+  console.log(`Socket ID: ${data.socketId}`);
+  console.log(`Количество пропущенных pong: ${data.timeouts}`);
+  
+  // Здесь можно добавить логику переподключения или уведомления пользователя
+});
+```
+
+## Отключение механизма ping/pong
+
+```typescript
+// Отключение для всех пространств имен
+wsClient.disablePingPong();
+
+// Отключение для конкретного пространства имен
+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
+
+Хотя SDK обеспечивает автоматический механизм ping/pong, вы также можете вручную отправлять ping-сообщения:
+
+```typescript
+// Отправка ping и получение pong
+wsClient.send(WebSocketNamespace.REASONING, 'connection_ping', { 
+  timestamp: Date.now() 
+});
+
+// Добавление обработчика для 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. **Интервал ping/pong**: Рекомендуемый интервал - 30 секунд для продакшн и 5-10 секунд для отладки.
+
+2. **Порог таймаута**: Значение 2-3 пропущенных ping/pong позволяет избежать ложных срабатываний при временных задержках сети.
+
+3. **Экономия трафика**: При частой передаче данных через WebSocket можно увеличить интервал ping/pong, так как регулярный обмен данными уже поддерживает соединение активным.
+
+4. **Мониторинг RTT**: Используйте statsPingStats для мониторинга задержек сети и раннего обнаружения проблем с соединением.
+
+5. **Отключение перед закрытием приложения**: Вызывайте disablePingPong() и затем disconnectAll() при закрытии приложения для корректного освобождения ресурсов.
+
+## Пример комплексного использования
+
+```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();
+  
+  // Включаем механизм 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);
+``` 

package/docs/README.md

@@ -0,0 +1,102 @@
+23# Code Solver SDK
+
+JavaScript/TypeScript SDK для взаимодействия с API Code Solver, предназначенного для умной работы с кодом, семантического поиска и AI-ассистентов.
+
+## Установка
+
+```bash
+npm install @code-solver/sdk
+```
+
+## Основные возможности
+
+- **Работа с проектами**: создание, индексация и управление проектами
+- **Семантический поиск**: поиск по смыслу в коде проекта
+- **AI-чат с контекстом**: взаимодействие с AI-моделями в контексте проекта
+- **Работа с WebSocket**: потоковая обработка событий и ответов
+- **Мультиплатформенность**: поддержка как браузеров, так и Node.js
+
+## Быстрый старт
+
+```javascript
+import { CodeSolverSDK } from '@code-solver/sdk';
+
+// Инициализация SDK
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.code-solver.com',
+  apiKey: 'ваш-api-ключ',
+  websocket: {
+    reconnect: true,
+    reconnectAttempts: 5
+  }
+});
+
+// Проверка доступности API
+const isAvailable = await sdk.checkHealth();
+if (!isAvailable) {
+  console.error('API недоступен');
+  return;
+}
+
+// Создание проекта
+const project = await sdk.projects.createProject(
+  'Мой проект',
+  '/путь/к/проекту',
+  {
+    excludePatterns: ['node_modules', '.git', 'dist']
+  }
+);
+
+// Индексация проекта
+await sdk.projects.indexProject(project.id);
+
+// Отслеживание прогресса индексации через WebSocket
+sdk.projects.on('indexing_progress', (data) => {
+  console.log(`Прогресс индексации: ${data.progress}%`);
+});
+
+sdk.projects.on('indexing_complete', (data) => {
+  console.log('Индексация завершена!');
+});
+
+// Семантический поиск
+const searchResults = await sdk.search.semanticSearch(project.id, {
+  query: 'функция для обработки HTTP запросов',
+  limit: 10
+});
+
+// Взаимодействие с AI-ассистентом
+const chatResponse = await sdk.chat.chat([
+  {
+    role: 'system',
+    content: 'Ты опытный программист, помогающий разработчику.'
+  },
+  {
+    role: 'user',
+    content: 'Объясни, как работает функция getUserProfile в моем проекте.'
+  }
+], {
+  projectId: project.id,
+  model: 'claude-3-7-sonnet-20240229'
+});
+
+console.log(chatResponse.answer);
+```
+
+## Документация
+
+Подробная документация доступна в следующих файлах:
+
+- [API Reference](./API_REFERENCE.md) - подробное описание всех методов SDK
+- [Authentication](./AUTHENTICATION.md) - информация по аутентификации
+- [Работа с WebSocket](./WEBSOCKET.md) - примеры работы с WebSocket соединениями
+- [Примеры интеграции](./INTEGRATION_EXAMPLES.md) - примеры интеграции с VS Code/Cursor
+
+## Поддерживаемые платформы
+
+- **Браузеры**: Chrome, Firefox, Safari, Edge
+- **Node.js**: 14.x и выше
+
+## Лицензия
+
+MIT 

package/docs/WEBSOCKET.md

@@ -0,0 +1,139 @@
+# Работа с WebSocket в Solver SDK
+
+Эта документация описывает, как использовать WebSocket соединения через Solver SDK для работы в реальном времени.
+
+## Инициализация SDK
+
+```javascript
+const { CodeSolverSDK } = require('solver-sdk');
+
+// Создаем экземпляр SDK с настройками
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key'
+});
+```
+
+## Работа с рассуждениями (Reasoning)
+
+### Создание рассуждения и получение результатов в реальном времени
+
+```javascript
+// Создание рассуждения
+const reasoning = await sdk.reasoning.createReasoning({
+  projectId: 'project-id',
+  query: 'Объясни этот проект'
+});
+
+// Подключение к WebSocket
+await sdk.reasoning.connectWebSocket(reasoning.id);
+
+// Подписка на события
+sdk.reasoning.on('thinking', (data) => {
+  console.log('Мышление:', data.content);
+});
+
+sdk.reasoning.on('complete', (data) => {
+  console.log('Результат:', data.content);
+  // Отключение после завершения
+  sdk.reasoning.disconnectWebSocket();
+});
+
+// Запуск рассуждения
+await sdk.reasoning.startReasoning(reasoning.id);
+```
+
+## Потоковый чат с мышлением AI
+
+```javascript
+// Обработчик событий для потокового получения ответа и мышления
+const handleEvent = (eventType, data) => {
+  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: 'Расскажи о JavaScript' }
+];
+
+const options = {
+  model: 'claude-3-7-sonnet-20240229',
+  thinking: true,
+  temperature: 0.7
+};
+
+// Отправка с потоковым получением ответа
+const response = await sdk.chat.streamChatWithThinking(
+  messages, 
+  options,
+  handleEvent
+);
+```
+
+## Мониторинг индексации проектов
+
+```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
+// Подключение к пространству имен зависимостей
+await sdk.dependencies.connectWebSocket(projectId);
+
+// Подписка на события зависимостей
+sdk.dependencies.on('dependency_update', (data) => {
+  console.log('Обновление зависимостей:', data);
+});
+
+// Отключение
+await sdk.dependencies.disconnectWebSocket();
+```
+
+## Обработка ошибок
+
+```javascript
+try {
+  await sdk.chat.streamChatWithThinking(
+    messages,
+    options,
+    handleEvent
+  );
+} catch (error) {
+  console.error('Произошла ошибка:', error.message);
+}
+```
+
+## Основные события
+
+| Событие | Описание |
+|---------|----------|
+| `message_start` | Начало сообщения |
+| `thinking_delta` | Обновление мышления AI |
+| `text_delta` | Часть текстового ответа |
+| `message_stop` | Конец сообщения |
+| `indexing_progress` | Прогресс индексации |
+| `indexing_complete` | Завершение индексации |
+| `error` | Уведомление об ошибке |

package/docs/advanced/PING_PONG.md

@@ -0,0 +1,212 @@
+# WebSocket Ping/Pong механизм
+
+Данный документ описывает механизм поддержания WebSocket соединений и мониторинга их состояния через ping/pong обмен.
+
+## Обзор функциональности
+
+SDK поддерживает автоматический механизм отправки ping-сообщений и обработки pong-ответов для:
+
+1. **Проверки активности соединения** - обнаружение разрывов соединения даже в отсутствие активности
+2. **Измерения времени отклика (Round Trip Time, RTT)** - мониторинг качества соединения
+3. **Сбора статистики соединения** - для диагностики и отладки
+4. **Автоматического обнаружения проблем** - уведомление о потере соединения
+
+## Включение механизма ping/pong
+
+```typescript
+import { CodeSolverSDK, WebSocketNamespace } from 'solver-sdk';
+
+// Создаем экземпляр SDK
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key'
+});
+
+// Получаем WebSocket клиент
+const wsClient = sdk.getWebSocketClient();
+
+// Подключаемся к пространствам имен
+await wsClient.connectToReasoning();
+await wsClient.connectToDependencies();
+await wsClient.connectToIndexing();
+
+// Включаем автоматический механизм ping/pong
+// параметры: интервал отправки в мс (по умолчанию 30000) и порог таймаута (по умолчанию 3)
+wsClient.enablePingPong(10000, 3);
+
+// Регистрируем обработчик для события таймаута соединения
+wsClient.onPingPongEvent('connection_timeout', (data) => {
+  console.log(`Соединение потеряно для namespace ${data.namespace}`);
+  console.log(`Socket ID: ${data.socketId}`);
+  console.log(`Количество пропущенных pong: ${data.timeouts}`);
+  
+  // Здесь можно добавить логику переподключения или уведомления пользователя
+});
+```
+
+## Отключение механизма ping/pong
+
+```typescript
+// Отключение для всех пространств имен
+wsClient.disablePingPong();
+
+// Отключение для конкретного пространства имен
+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
+
+Хотя SDK обеспечивает автоматический механизм ping/pong, вы также можете вручную отправлять ping-сообщения:
+
+```typescript
+// Отправка ping и получение pong
+wsClient.send(WebSocketNamespace.REASONING, 'connection_ping', { 
+  timestamp: Date.now() 
+});
+
+// Добавление обработчика для 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. **Интервал ping/pong**: Рекомендуемый интервал - 30 секунд для продакшн и 5-10 секунд для отладки.
+
+2. **Порог таймаута**: Значение 2-3 пропущенных ping/pong позволяет избежать ложных срабатываний при временных задержках сети.
+
+3. **Экономия трафика**: При частой передаче данных через WebSocket можно увеличить интервал ping/pong, так как регулярный обмен данными уже поддерживает соединение активным.
+
+4. **Мониторинг RTT**: Используйте statsPingStats для мониторинга задержек сети и раннего обнаружения проблем с соединением.
+
+5. **Отключение перед закрытием приложения**: Вызывайте disablePingPong() и затем disconnectAll() при закрытии приложения для корректного освобождения ресурсов.
+
+## Пример комплексного использования
+
+```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();
+  
+  // Включаем механизм 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);
+```