solver-sdk 2.0.2 → 2.1.0

package/docs/ERROR_HANDLING.md

@@ -1,240 +1,173 @@
-# Обработка ошибок в Solver SDK
+# Обработка ошибок в SDK
 
-Документация по системе обработки ошибок в Solver SDK, включая общие ошибки, ошибки WebSocket и географические ограничения.
+SDK предоставляет различные механизмы обработки ошибок для HTTP запросов и WebSocket соединений.
 
-## Содержание
+## Обработка HTTP ошибок
 
-- [Общие принципы](#общие-принципы)
-- [Типы ошибок](#типы-ошибок)
-- [HTTP ошибки](#http-ошибки)
-- [WebSocket ошибки](#websocket-ошибки)
-- [Ошибки географических ограничений](#ошибки-географических-ограничений)
-- [Примеры обработки ошибок](#примеры-обработки-ошибок)
+### Использование try/catch
 
-## Общие принципы
-
-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 запросами:
+Рекомендуемый способ обработки ошибок - использование конструкции `try/catch`:
 
 ```javascript
 try {
-  const result = await sdk.chat.chat([{ role: 'user', content: 'Hello' }]);
+  // Выполнение запроса
+  const projects = await sdk.projects.getAllProjects();
+  console.log('Получено проектов:', projects.length);
 } catch (error) {
-  console.error(`Код ошибки: ${error.code}`);
-  console.error(`Сообщение: ${error.message}`);
+  console.error('Ошибка при получении проектов:', error);
   
-  // Проверка типа ошибки
-  if (error.code === 401) {
-    console.error('Ошибка аутентификации: проверьте API ключ');
-  } else if (error.code === 429) {
-    console.error('Превышен лимит запросов: повторите позже');
+  // Можно проверить тип ошибки
+  if (error.status === 401) {
+    console.error('Ошибка авторизации. Проверьте API ключ.');
+  } else if (error.status === 404) {
+    console.error('Ресурс не найден.');
+  } else if (error.code === 'NETWORK_ERROR') {
+    console.error('Проблема с сетевым соединением.');
   }
 }
 ```
 
-## WebSocket ошибки
+### Глобальный обработчик ошибок
 
-WebSocket ошибки обрабатываются через обработчики событий:
+Можно установить глобальный обработчик ошибок SDK:
 
 ```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);
+// Установка глобального обработчика
+CodeSolverSDK.setErrorHandler((error) => {
+  console.error('Глобальная ошибка SDK:', error);
+  // Отправка информации об ошибке в мониторинг
+  sendToMonitoring(error);
+});
+
+// После этого необработанные ошибки SDK будут передаваться в этот обработчик
 ```
 
-## Ошибки географических ограничений
+## Обработка ошибок WebSocket
+
+### Обработка событий ошибок
+
+SDK позволяет подписаться на события ошибок для различных API:
+
+```javascript
+// Для индексации проектов
+sdk.projects.on('error', (error) => {
+  console.error('Ошибка индексации:', error);
+});
+
+// Для рассуждений
+sdk.reasoning.on('error', (error) => {
+  console.error('Ошибка рассуждения:', error);
+});
+```
 
-> **Добавлено в версии 1.7.4**
+### Обработка ошибок соединения
 
-Начиная с версии 1.7.4 SDK поддерживает специальную обработку ошибок географических ограничений API Anthropic. Эти ошибки возникают, когда запросы отправляются из регионов, не поддерживаемых API Anthropic:
+При использовании высокоуровневых методов подключения можно обрабатывать ошибки соединения:
 
 ```javascript
 try {
-  const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
+  // Попытка подключения к WebSocket
+  await sdk.connect();
+  console.log('Подключение установлено');
 } 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. Использовать прокси-сервер
-  }
+  console.error('Ошибка подключения:', error);
 }
 ```
 
-Через обработчик WebSocket событий:
+### Автоматическое переподключение
+
+SDK поддерживает автоматическое переподключение в случае разрыва соединения:
 
 ```javascript
-const handleEvent = (eventType, data) => {
-  if (eventType === 'error' && data.type === 'geo_restriction') {
-    console.error('Необходимо включить VPN для доступа к API Anthropic из вашего региона');
-    
-    // Выполнить действия по настройке VPN или показать инструкции пользователю
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key',
+  websocket: {
+    reconnect: true,                 // Включить автоматическое переподключение
+    reconnectAttempts: 5,            // Максимальное число попыток
+    reconnectDelay: 3000             // Задержка между попытками (мс)
   }
-};
+});
 ```
 
-### Причины ошибок географических ограничений
+## Типичные ошибки и их решения
 
-Основные причины возникновения ошибок географических ограничений:
+### Ошибки подключения
 
-1. **Региональные ограничения API Anthropic** — API доступен только из определенных регионов (США, Европа и некоторые другие)
-2. **Регуляторные требования** — законодательство некоторых стран ограничивает доступ к определенным API
-3. **IP-блокировка** — некоторые IP-адреса могут быть заблокированы провайдером API
+| Код ошибки | Описание | Решение |
+|------------|----------|---------|
+| `NETWORK_ERROR` | Ошибка сети | Проверьте подключение к Интернету |
+| `ETIMEDOUT` | Таймаут соединения | Увеличьте значение `timeout` в настройках SDK |
+| `CONNECTION_REFUSED` | Соединение отклонено | Проверьте правильность URL и доступность сервера |
+| `CERT_ERROR` | Ошибка сертификата | Используйте параметр `rejectUnauthorized: false` для локальной разработки |
 
-### Решение проблемы
+### Ошибки аутентификации
 
-Для решения проблемы географических ограничений:
+| Код ошибки | Описание | Решение |
+|------------|----------|---------|
+| `401 Unauthorized` | Неверный API ключ | Проверьте правильность API ключа |
+| `403 Forbidden` | Недостаточно прав | Проверьте права доступа для API ключа |
+| `AUTH_EXPIRED` | Срок действия токена истек | Обновите API ключ |
 
-1. **Использование VPN** — подключитесь через VPN к поддерживаемому региону (США, Европа)
-2. **Прокси-сервер** — настройте прокси для запросов к API
-3. **Альтернативные провайдеры** — используйте альтернативных провайдеров, доступных в вашем регионе
+### Ошибки индексации
 
-## Примеры обработки ошибок
+| Код ошибки | Описание | Решение |
+|------------|----------|---------|
+| `PROJECT_NOT_FOUND` | Проект не найден | Проверьте ID проекта |
+| `INDEXING_IN_PROGRESS` | Индексация уже выполняется | Дождитесь завершения текущей индексации |
+| `INDEXING_ERROR` | Ошибка во время индексации | Проверьте лог ошибок на сервере |
 
-### Комплексная обработка ошибок
+## Пример комплексной обработки ошибок
 
 ```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;
-      }
-    }
-  };
-  
+async function initializeSDK() {
   try {
-    const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
-    console.log(`Успешно отправлен запрос, Socket ID: ${response.socketId}`);
+    // Проверка доступности API
+    const isHealthy = await sdk.checkHealth();
+    
+    if (!isHealthy) {
+      console.error('API недоступен, пробуем резервный сервер');
+      // Создаем новый экземпляр SDK с резервным URL
+      return new CodeSolverSDK({
+        baseURL: 'https://backup-api.example.com',
+        apiKey: 'your-api-key'
+      });
+    }
+    
+    // Подключение к WebSocket
+    await sdk.connect();
+    console.log('SDK успешно инициализирован');
+    
+    return sdk;
   } catch (error) {
-    console.error(`Критическая ошибка: ${error.message}`);
+    console.error('Ошибка при инициализации SDK:', error);
+    
+    // Логирование ошибки для отладки
+    logError('SDK_INIT_ERROR', error);
     
-    // Обработка специфических типов ошибок
-    if (error.type === 'geo_restriction') {
-      showVpnInstructions(); // Показать инструкции по настройке VPN
-    } else if (error.status === 429) {
-      scheduleRetry(5000); // Запланировать повторную попытку через 5 секунд
-    } else {
-      reportError(error); // Отправить отчет об ошибке
+    // В зависимости от ошибки предпринимаем разные действия
+    if (error.code === 'CONNECTION_ERROR') {
+      console.warn('Продолжаем работу без WebSocket подключения');
+      return sdk; // Возвращаем SDK, но без WebSocket функциональности
     }
+    
+    // Для критических ошибок выбрасываем исключение
+    throw new Error(`Не удалось инициализировать SDK: ${error.message}`);
   }
 }
-```
 
-### Обработка ошибок при работе с рассуждениями
-
-```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();
-      }
-    }
-  });
+// Использование
+const sdk = await initializeSDK().catch(error => {
+  console.error('Критическая ошибка:', error);
+  // Показываем пользователю сообщение об ошибке
+  showErrorMessage('Не удалось подключиться к серверу');
   
-  // Запуск рассуждения
-  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();
-  }
-}
-``` 
+  // Возвращаем отключенную версию SDK или null
+  return null;
+});
+
+if (sdk) {
+  // Продолжаем работу с SDK
+} else {
+  // Работаем в режиме ограниченной функциональности
+} 

package/docs/INTEGRATION_EXAMPLES.md

@@ -1,6 +1,6 @@
-# Примеры интеграции с VS Code/Cursor
+# Примеры интеграции SDK
 
-В этом документе приведены примеры использования SDK с VS Code или Cursor расширениями.
+В этом документе приведены примеры использования SDK с расширениями VS Code/Cursor или другими приложениями.
 
 ## Содержание
 - [Инициализация SDK](#инициализация-sdk)
@@ -179,6 +179,18 @@ context.subscriptions.push(
           <div class="thinking" id="thinking"></div>
           <h4>Ответ:</h4>
           <div class="answer" id="answer"></div>
+          
+          <script>
+            const vscode = acquireVsCodeApi();
+            window.addEventListener('message', event => {
+              const message = event.data;
+              if (message.command === 'appendThinking') {
+                document.getElementById('thinking').textContent += message.content;
+              } else if (message.command === 'appendAnswer') {
+                document.getElementById('answer').textContent += message.content;
+              }
+            });
+          </script>
         </body>
         </html>
       `;
@@ -219,18 +231,6 @@ context.subscriptions.push(
         handleEvent
       );
       
-      // Настраиваем обработку сообщений в WebView
-      panel.webview.onDidReceiveMessage(message => {
-        const thinkingElement = document.getElementById('thinking');
-        const answerElement = document.getElementById('answer');
-        
-        if (message.command === 'appendThinking') {
-          thinkingElement.textContent += message.content;
-        } else if (message.command === 'appendAnswer') {
-          answerElement.textContent += message.content;
-        }
-      });
-      
     } catch (error) {
       vscode.window.showErrorMessage(`Ошибка чата: ${error.message}`);
     }
@@ -273,6 +273,16 @@ async function searchInProject(projectId, query) {
       );
       
       // Формируем HTML для отображения результатов
+      let resultsHtml = '';
+      results.results.forEach((result, index) => {
+        resultsHtml += `
+          <div class="result">
+            <div class="path" data-path="${result.path}">${result.path}</div>
+            <div class="snippet">${result.content || 'Содержимое недоступно'}</div>
+          </div>
+        `;
+      });
+      
       panel.webview.html = `
         <!DOCTYPE html>
         <html>
@@ -286,25 +296,15 @@ async function searchInProject(projectId, query) {
         </head>
         <body>
           <h3>Результаты для: ${query}</h3>
-          ${results.results.map((result, index) => `
-            <div class="result">
-              <div class="path" data-path="${result.filePath}" data-start="${result.startLine}" data-end="${result.endLine}">
-                ${result.filePath}:${result.startLine}-${result.endLine}
-              </div>
-              <div class="snippet">${result.snippet || result.content || ''}</div>
-            </div>
-          `).join('')}
+          ${resultsHtml}
           
           <script>
-            // Добавляем обработчик для открытия файлов
-            document.querySelectorAll('.path').forEach(elem => {
-              elem.addEventListener('click', () => {
-                const vscode = acquireVsCodeApi();
+            const vscode = acquireVsCodeApi();
+            document.querySelectorAll('.path').forEach(element => {
+              element.addEventListener('click', () => {
                 vscode.postMessage({
                   command: 'openFile',
-                  filePath: elem.dataset.path,
-                  startLine: parseInt(elem.dataset.start),
-                  endLine: parseInt(elem.dataset.end)
+                  path: element.getAttribute('data-path')
                 });
               });
             });
@@ -313,30 +313,16 @@ async function searchInProject(projectId, query) {
         </html>
       `;
       
-      // Обработка сообщений от WebView
-      panel.webview.onDidReceiveMessage(
-        message => {
-          if (message.command === 'openFile') {
-            const uri = vscode.Uri.file(message.filePath);
-            vscode.workspace.openTextDocument(uri).then(doc => {
-              vscode.window.showTextDocument(doc).then(editor => {
-                const range = new vscode.Range(
-                  new vscode.Position(message.startLine - 1, 0),
-                  new vscode.Position(message.endLine - 1, 0)
-                );
-                editor.revealRange(range);
-              });
-            });
-          }
-        },
-        undefined,
-        context.subscriptions
-      );
-      
-      return results;
+      // Обработчик сообщений от WebView
+      panel.webview.onDidReceiveMessage(message => {
+        if (message.command === 'openFile') {
+          const filePath = message.path;
+          vscode.workspace.openTextDocument(filePath)
+            .then(doc => vscode.window.showTextDocument(doc));
+        }
+      });
     });
   } catch (error) {
     vscode.window.showErrorMessage(`Ошибка поиска: ${error.message}`);
   }
-}
-``` 
+}