solver-sdk 1.7.2 → 1.7.4

package/docs/ERROR_HANDLING.md

@@ -0,0 +1,240 @@
+# Обработка ошибок в Solver SDK
+
+Документация по системе обработки ошибок в Solver SDK, включая общие ошибки, ошибки WebSocket и географические ограничения.
+
+## Содержание
+
+- [Общие принципы](#общие-принципы)
+- [Типы ошибок](#типы-ошибок)
+- [HTTP ошибки](#http-ошибки)
+- [WebSocket ошибки](#websocket-ошибки)
+- [Ошибки географических ограничений](#ошибки-географических-ограничений)
+- [Примеры обработки ошибок](#примеры-обработки-ошибок)
+
+## Общие принципы
+
+Solver SDK использует следующие принципы при работе с ошибками:
+
+1. **Унифицированный формат** — все ошибки имеют единую структуру
+2. **Информативные сообщения** — ошибки содержат детальное описание проблемы
+3. **Коды ошибок** — каждая ошибка имеет уникальный код для идентификации
+4. **Типизация** — ошибки классифицируются по типам для удобной обработки
+
+## Типы ошибок
+
+Основные типы ошибок в SDK:
+
+| Тип ошибки | Описание |
+|------------|----------|
+| `http_error` | Ошибки HTTP запросов |
+| `websocket_error` | Ошибки WebSocket соединений |
+| `validation_error` | Ошибки валидации входных данных |
+| `authentication_error` | Ошибки аутентификации |
+| `rate_limit_error` | Ошибки превышения лимита запросов |
+| `provider_error` | Ошибки провайдеров API (Anthropic, OpenAI) |
+| `geo_restriction` | Ошибки географических ограничений |
+
+## HTTP ошибки
+
+HTTP ошибки возникают при проблемах с HTTP запросами:
+
+```javascript
+try {
+  const result = await sdk.chat.chat([{ role: 'user', content: 'Hello' }]);
+} catch (error) {
+  console.error(`Код ошибки: ${error.code}`);
+  console.error(`Сообщение: ${error.message}`);
+  
+  // Проверка типа ошибки
+  if (error.code === 401) {
+    console.error('Ошибка аутентификации: проверьте API ключ');
+  } else if (error.code === 429) {
+    console.error('Превышен лимит запросов: повторите позже');
+  }
+}
+```
+
+## WebSocket ошибки
+
+WebSocket ошибки обрабатываются через обработчики событий:
+
+```javascript
+const handleEvent = (eventType, data) => {
+  if (eventType === 'error') {
+    console.error(`WebSocket ошибка: ${data.message} (код: ${data.code})`);
+    
+    // Обработка конкретных типов ошибок
+    switch (data.type) {
+      case 'connection_error':
+        console.error('Проблема с подключением, пробуем переподключиться...');
+        break;
+      case 'authentication_error':
+        console.error('Проблема аутентификации, запрашиваем новый токен...');
+        break;
+      case 'timeout_error':
+        console.error('Превышен таймаут ожидания ответа');
+        break;
+    }
+  }
+};
+
+// Передаем обработчик событий
+await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
+```
+
+## Ошибки географических ограничений
+
+> **Добавлено в версии 1.7.4**
+
+Начиная с версии 1.7.4 SDK поддерживает специальную обработку ошибок географических ограничений API Anthropic. Эти ошибки возникают, когда запросы отправляются из регионов, не поддерживаемых API Anthropic:
+
+```javascript
+try {
+  const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
+} catch (error) {
+  // Проверка наличия ошибки географических ограничений
+  if (error.type === 'geo_restriction') {
+    console.error('==============================================');
+    console.error('⚠️  ОШИБКА ГЕОГРАФИЧЕСКОГО ОГРАНИЧЕНИЯ API ANTHROPIC');
+    console.error('⚠️  Для работы с API Anthropic требуется VPN или прокси');
+    console.error('⚠️  Anthropic API доступен только из определенных регионов');
+    console.error('==============================================');
+    
+    // Возможные действия:
+    // 1. Предложить пользователю включить VPN
+    // 2. Переключиться на другой провайдер API
+    // 3. Использовать прокси-сервер
+  }
+}
+```
+
+Через обработчик WebSocket событий:
+
+```javascript
+const handleEvent = (eventType, data) => {
+  if (eventType === 'error' && data.type === 'geo_restriction') {
+    console.error('Необходимо включить VPN для доступа к API Anthropic из вашего региона');
+    
+    // Выполнить действия по настройке VPN или показать инструкции пользователю
+  }
+};
+```
+
+### Причины ошибок географических ограничений
+
+Основные причины возникновения ошибок географических ограничений:
+
+1. **Региональные ограничения API Anthropic** — API доступен только из определенных регионов (США, Европа и некоторые другие)
+2. **Регуляторные требования** — законодательство некоторых стран ограничивает доступ к определенным API
+3. **IP-блокировка** — некоторые IP-адреса могут быть заблокированы провайдером API
+
+### Решение проблемы
+
+Для решения проблемы географических ограничений:
+
+1. **Использование VPN** — подключитесь через VPN к поддерживаемому региону (США, Европа)
+2. **Прокси-сервер** — настройте прокси для запросов к API
+3. **Альтернативные провайдеры** — используйте альтернативных провайдеров, доступных в вашем регионе
+
+## Примеры обработки ошибок
+
+### Комплексная обработка ошибок
+
+```javascript
+async function exampleWithErrorHandling() {
+  const sdk = new CodeSolverSDK({
+    baseURL: 'https://api.example.com',
+    apiKey: 'your-api-key'
+  });
+  
+  const messages = [
+    { role: 'user', content: 'Explain quantum computing' }
+  ];
+  
+  const options = {
+    model: 'claude-3-7-sonnet-20240229',
+    thinking: true,
+    authToken: 'your-auth-token'
+  };
+  
+  // Обработчик WebSocket событий
+  const handleEvent = (eventType, data) => {
+    // Обработка ошибок
+    if (eventType === 'error') {
+      console.error(`Ошибка: ${data.message}`);
+      
+      // Проверка типа ошибки
+      switch (data.type) {
+        case 'geo_restriction':
+          console.error('Географическое ограничение: требуется VPN');
+          break;
+        case 'authentication_error':
+          console.error('Ошибка аутентификации: неверный токен');
+          break;
+        case 'rate_limit_error':
+          console.error('Превышен лимит запросов');
+          break;
+        default:
+          console.error(`Неизвестная ошибка типа: ${data.type}`);
+          break;
+      }
+    }
+  };
+  
+  try {
+    const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
+    console.log(`Успешно отправлен запрос, Socket ID: ${response.socketId}`);
+  } catch (error) {
+    console.error(`Критическая ошибка: ${error.message}`);
+    
+    // Обработка специфических типов ошибок
+    if (error.type === 'geo_restriction') {
+      showVpnInstructions(); // Показать инструкции по настройке VPN
+    } else if (error.status === 429) {
+      scheduleRetry(5000); // Запланировать повторную попытку через 5 секунд
+    } else {
+      reportError(error); // Отправить отчет об ошибке
+    }
+  }
+}
+```
+
+### Обработка ошибок при работе с рассуждениями
+
+```javascript
+try {
+  // Создание рассуждения
+  const reasoning = await sdk.reasoning.createReasoning({
+    projectId: 'project-123',
+    query: 'Analyze this codebase'
+  });
+  
+  // Подключение WebSocket
+  await sdk.reasoning.connectWebSocket({
+    reasoningId: reasoning.id,
+    authToken: 'your-auth-token',
+    onError: (error) => {
+      console.error(`WebSocket ошибка: ${error.message}`);
+      
+      if (error.type === 'geo_restriction') {
+        // Показать сообщение о необходимости VPN
+        showVpnAlert();
+      }
+    }
+  });
+  
+  // Запуск рассуждения
+  await sdk.reasoning.startReasoning(reasoning.id);
+} catch (error) {
+  console.error(`HTTP ошибка: ${error.message}`);
+  
+  // Обработка HTTP ошибок
+  if (error.status === 401) {
+    // Перенаправить на страницу входа
+    redirectToLogin();
+  } else if (error.status === 403) {
+    // Показать сообщение об отсутствии доступа
+    showAccessDeniedMessage();
+  }
+}
+``` 

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,77 @@
+# Документация Solver SDK
+
+Эта директория содержит подробную документацию по Solver SDK версии 1.7.2.
+
+## Содержание
+
+### Основная документация
+
+- [Потоковая передача мышления (Thinking Architecture)](./THINKING_ARCHITECTURE.md) - Архитектура системы потоковой передачи мышления
+- [Руководство по потоковой передаче мышления](./streaming-thinking-guide.md) - Практическое руководство по использованию потоковой передачи мышления
+- [Работа с региональными эндпоинтами](./REGIONS.md) - Информация о работе с региональными эндпоинтами Anthropic API
+- [Расширенные возможности SDK](./ADVANCED.md) - Продвинутые функции и конфигурация SDK
+- [WebSocket API](./WEBSOCKET.md) - Подробное руководство по работе с WebSocket
+- [Справочник WebSocket событий](./WEBSOCKET_EVENTS.md) - Полный список всех WebSocket событий SDK
+- [Механизм Ping/Pong](./PING_PONG.md) - Документация по мониторингу состояния WebSocket соединений
+- [Индексация проектов](./INDEXING.md) - Руководство по индексации и обновлению индекса проектов
+
+### Дополнительные материалы
+
+- [Режим мышления](./thinking/thinking-mode.md) - Основная информация о режиме мышления
+
+## Основные возможности SDK 1.7.2
+
+### Потоковая передача мышления (Streaming Thinking)
+
+В версии 1.7.2 добавлена полная поддержка потоковой передачи мышления с помощью метода `streamChatWithThinking()`. Это позволяет получать события мышления модели в реальном времени через WebSocket.
+
+```javascript
+const response = await sdk.chat.streamChatWithThinking(
+  messages,
+  { model: 'claude-3-7-sonnet-20240229', thinking: true },
+  handleEvent
+);
+```
+
+### Региональные эндпоинты
+
+SDK поддерживает работу с различными региональными эндпоинтами Anthropic API:
+
+```javascript
+const sdk = new CodeSolverSDK({
+  providers: {
+    anthropic: {
+      region: 'eu-west-1'  // Использовать европейский регион
+    }
+  }
+});
+
+// Автоматическое переключение между регионами при ошибках
+const response = await sdk.chat.chatWithRegionFailover([...], options);
+```
+
+### WebSocket улучшения
+
+Улучшена надежность и диагностика WebSocket соединений:
+
+```javascript
+// Диагностика соединения
+const diagnostics = sdk.getWebSocketClient().diagnoseConnection(namespace);
+console.log(diagnostics);
+
+// Мониторинг здоровья
+sdk.getWebSocketClient().setupConnectionHealthCheck(interval);
+```
+
+## Примеры кода
+
+Примеры использования SDK доступны в директории `examples` корневого каталога проекта:
+
+- `example:check-api` - Проверка соединения с API
+- `example:indexing` - Индексация проектов
+- `example:dependencies` - Работа с зависимостями
+- `example:regions` - Проверка доступности регионов
+
+## Обратная связь
+
+Если вы обнаружили ошибки в документации или у вас есть предложения по улучшению, пожалуйста, создайте issue в репозитории проекта. 

package/docs/REGIONS.md

@@ -0,0 +1,140 @@
+# Работа с региональными эндпоинтами Anthropic API
+
+SDK поддерживает работу с различными региональными эндпоинтами Anthropic API, что позволяет:
+- Улучшить производительность для пользователей в разных регионах
+- Обеспечить отказоустойчивость при перегрузке одного из регионов
+- Соблюдать законодательные требования по обработке данных в конкретных регионах
+
+## Содержание
+
+- [Поддерживаемые регионы](#поддерживаемые-регионы)
+- [Настройка региона](#настройка-региона)
+- [Автоматическое переключение между регионами](#автоматическое-переключение-между-регионами)
+- [Примеры использования](#примеры-использования)
+- [Ограничения](#ограничения)
+
+## Поддерживаемые регионы
+
+SDK поддерживает следующие регионы Anthropic API:
+
+| Регион | Код | Расположение | Доступность |
+|--------|-----|--------------|-------------|
+| US East (N. Virginia) | `us-east-1` | США | Основной регион |
+| EU West (Ireland) | `eu-west-1` | Евросоюз | Соответствует GDPR |
+| Asia Pacific (Sydney) | `ap-southeast-2` | Австралия | Для пользователей в APAC |
+
+Каждый регион имеет собственный эндпоинт и характеристики производительности.
+
+## Настройка региона
+
+Регион для запросов можно настроить несколькими способами:
+
+### 1. В глобальных настройках SDK
+
+```javascript
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key',
+  providers: {
+    anthropic: {
+      region: 'eu-west-1' // Использовать европейский регион для всех запросов
+    }
+  }
+});
+```
+
+### 2. В параметрах конкретного запроса
+
+```javascript
+// Для чата
+const response = await sdk.chat.chat([
+  { role: 'user', content: 'Привет! Как дела?' }
+], {
+  model: 'claude-3-sonnet-20240229',
+  region: 'ap-southeast-2' // Использовать азиатско-тихоокеанский регион для этого запроса
+});
+
+// Для рассуждений
+const reasoning = await sdk.reasoning.createReasoning({
+  projectId: 'my-project',
+  query: 'Как оптимизировать этот код?',
+  options: {
+    region: 'us-east-1' // Использовать американский регион для этого рассуждения
+  }
+});
+```
+
+## Автоматическое переключение между регионами
+
+SDK (версия 1.7.1+) поддерживает автоматическое переключение между регионами при получении ошибки перегрузки (код 529) от Anthropic API.
+
+### Для чата
+
+```javascript
+// Использует автоматическое переключение между регионами
+const response = await sdk.chat.chatWithRegionFailover([
+  { role: 'user', content: 'Привет! Как дела?' }
+], {
+  model: 'claude-3-sonnet-20240229',
+  region: 'us-east-1' // Начинаем с этого региона, но можем переключиться на другие
+});
+```
+
+### Для рассуждений
+
+```javascript
+// Использует автоматическое переключение между регионами
+const reasoning = await sdk.reasoning.createReasoningWithRegionFailover({
+  projectId: 'my-project',
+  query: 'Как оптимизировать этот код?',
+  options: {
+    region: 'eu-west-1' // Начинаем с этого региона, но можем переключиться на другие
+  }
+});
+```
+
+### Как работает переключение между регионами
+
+1. Запрос отправляется в указанный регион
+2. Если регион возвращает ошибку перегрузки (код 529), SDK автоматически пробует следующий доступный регион
+3. Если все регионы перегружены, возвращается ошибка
+
+Порядок переключения: регионы проверяются в порядке, начиная с указанного в параметрах, затем по кругу.
+
+## Примеры использования
+
+### Базовый пример переключения регионов
+
+```javascript
+try {
+  const response = await sdk.chat.chatWithRegionFailover([
+    { role: 'user', content: 'Привет! Расскажи о переключении регионов Anthropic API.' }
+  ], {
+    model: 'claude-3-sonnet-20240229'
+  });
+  
+  console.log('Ответ:', response.choices[0].message.content);
+} catch (error) {
+  console.error('Все регионы недоступны:', error);
+}
+```
+
+### Пример с настройкой порядка регионов
+
+```javascript
+// Запрос с указанием предпочтительного региона 
+// (остальные будут проверены в порядке следования после него)
+const response = await sdk.chat.chatWithRegionFailover([
+  { role: 'user', content: 'Привет!' }
+], {
+  model: 'claude-3-sonnet-20240229',
+  region: 'ap-southeast-2' // Сначала пробуем AP регион, затем US и EU
+});
+```
+
+## Ограничения
+
+- Переключение работает только для ошибки перегрузки (код 529)
+- Другие ошибки (аутентификация, формат запроса и т.д.) не вызывают переключение
+- При переключении между регионами может быть заметная задержка
+- Цены и квоты могут отличаться в разных регионах