solver-sdk 1.7.3 → 1.7.5

package/docs/API_REFERENCE.md

@@ -0,0 +1,168 @@
+# API Reference
+
+В этом документе описаны основные классы и методы SDK.
+
+## Содержание
+
+- [CodeSolverSDK](#codesolversdk)
+- [ChatApi](#chatapi)
+- [ReasoningApi](#reasoningapi)
+- [ProjectsApi](#projectsapi)
+- [SearchApi](#searchapi)
+
+## CodeSolverSDK
+
+Основной класс SDK, предоставляющий доступ ко всем API.
+
+### Конструктор
+
+```javascript
+const sdk = new CodeSolverSDK(options);
+```
+
+### Параметры
+
+| Параметр | Тип | Описание | Обязательно |
+|----------|-----|----------|-------------|
+| `baseURL` | string | Базовый URL API | Да |
+| `apiKey` | string | API ключ для авторизации | Нет |
+| `timeout` | number | Таймаут для HTTP запросов (мс) | Нет |
+| `websocket` | object | Настройки WebSocket | Нет |
+
+### Методы
+
+#### `getWebSocketClient()`
+
+Возвращает экземпляр WebSocket клиента для работы с соединениями.
+
+```javascript
+const wsClient = sdk.getWebSocketClient();
+```
+
+#### `checkHealth()`
+
+Проверяет доступность API сервера.
+
+```javascript
+const isHealthy = await sdk.checkHealth();
+```
+
+## ChatApi
+
+API для работы с чатом и потоковой передачей мышления.
+
+### Методы
+
+#### `streamChatWithThinking(messages, options, callback)`
+
+Отправляет запрос чата с потоковой передачей мышления через WebSocket.
+
+```javascript
+const response = await sdk.chat.streamChatWithThinking(
+  messages,
+  options,
+  callback
+);
+```
+
+##### Параметры
+
+| Параметр | Тип | Описание | Обязательно |
+|----------|-----|----------|-------------|
+| `messages` | Array | Массив сообщений для отправки модели | Да |
+| `options` | Object | Параметры запроса (модель, thinking: true) | Да |
+| `callback` | Function | Обработчик событий | Да |
+
+#### `chat(messages, options)`
+
+Отправляет запрос чата и возвращает полный ответ.
+
+```javascript
+const response = await sdk.chat.chat(
+  messages,
+  options
+);
+```
+
+#### `getModels()`
+
+Получает список доступных моделей.
+
+```javascript
+const models = await sdk.chat.getModels();
+```
+
+## ReasoningApi
+
+API для работы с рассуждениями.
+
+### Методы
+
+#### `createReasoning(options)`
+
+Создаёт новое рассуждение.
+
+```javascript
+const reasoning = await sdk.reasoning.createReasoning({
+  projectId: 'project-id',
+  query: 'Объясни этот проект'
+});
+```
+
+#### `getReasoning(reasoningId)`
+
+Получает информацию о рассуждении.
+
+```javascript
+const reasoning = await sdk.reasoning.getReasoning('reasoning-id');
+```
+
+## ProjectsApi
+
+API для работы с проектами.
+
+### Методы
+
+#### `createProject(name, path)`
+
+Создаёт новый проект.
+
+```javascript
+const project = await sdk.projects.createProject('Мой проект', '/path/to/project');
+```
+
+#### `indexProject(projectId)`
+
+Запускает индексацию проекта.
+
+```javascript
+await sdk.projects.indexProject('project-id');
+```
+
+## SearchApi
+
+API для поиска кода.
+
+### Методы
+
+#### `searchCode(projectId, options)`
+
+Выполняет поиск кода в проекте.
+
+```javascript
+const results = await sdk.search.searchCode('project-id', {
+  query: 'function example',
+  limit: 10
+});
+```
+
+#### `semanticSearch(projectId, options)`
+
+Выполняет семантический поиск в проекте.
+
+```javascript
+const results = await sdk.search.semanticSearch('project-id', {
+  query: 'функция для обработки HTTP запросов',
+  limit: 10
+});
+```

package/docs/AUTHENTICATION.md

@@ -0,0 +1,179 @@
+# Аутентификация в Solver SDK
+
+В этом документе описаны методы аутентификации в Solver SDK для различных API и WebSocket соединений.
+
+## Содержание
+
+- [HTTP API аутентификация](#http-api-аутентификация)
+- [WebSocket аутентификация](#websocket-аутентификация)
+- [Тестовая аутентификация](#тестовая-аутентификация)
+- [Обработка ошибок аутентификации](#обработка-ошибок-аутентификации)
+
+## HTTP API аутентификация
+
+SDK поддерживает два основных метода аутентификации для HTTP запросов:
+
+### 1. API ключ
+
+```javascript
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key'
+});
+```
+
+API ключ автоматически добавляется в заголовок `X-API-Key` для всех HTTP запросов.
+
+### 2. Пользовательские заголовки
+
+```javascript
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  headers: {
+    'Authorization': 'Bearer your-jwt-token',
+    'X-Custom-Header': 'Custom-Value'
+  }
+});
+```
+
+## WebSocket аутентификация
+
+Для WebSocket соединений SDK использует отдельный механизм аутентификации через специальное событие `authenticate`.
+
+### Стандартная аутентификация WebSocket
+
+```javascript
+// 1. Создаем экземпляр SDK
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key'
+});
+
+// 2. Опции для streamChatWithThinking
+const options = {
+  model: 'claude-3-7-sonnet-20240229',
+  thinking: true,
+  authToken: 'your-auth-token' // ← Токен для WebSocket аутентификации
+};
+
+// 3. Отправка запроса
+const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
+```
+
+Параметр `authToken` используется для аутентификации WebSocket соединений и передается в событии `authenticate`.
+
+### Низкоуровневая WebSocket аутентификация
+
+Если вы работаете напрямую с WebSocket клиентом, вы можете настроить аутентификацию следующим образом:
+
+```javascript
+// Получаем WebSocket клиент
+const wsClient = sdk.getWebSocketClient();
+
+// Настраиваем опции подключения с аутентификацией
+const connectionOptions = {
+  namespace: 'reasoning',
+  authToken: 'your-auth-token',
+  query: {
+    reasoningId: 'reasoning-123'
+  }
+};
+
+// Подключаемся к WebSocket серверу
+await wsClient.connect(connectionOptions);
+
+// Проверяем статус аутентификации
+const isAuthenticated = wsClient.isAuthenticated();
+console.log('Аутентификация WebSocket:', isAuthenticated);
+```
+
+## Тестовая аутентификация
+
+Для тестовых сред SDK поддерживает упрощенную аутентификацию:
+
+```javascript
+const options = {
+  // Другие параметры...
+  authToken: 'test-token'
+};
+
+const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
+```
+
+> **Важно**: Начиная с версии 1.7.4, устаревший параметр `testToken` удален в пользу унифицированного параметра `authToken`.
+
+## Обработка ошибок аутентификации
+
+SDK предоставляет механизм обработки ошибок аутентификации:
+
+```javascript
+// Обработчик событий WebSocket
+const handleEvent = (eventType, data) => {
+  if (eventType === 'authentication_error') {
+    console.error('Ошибка аутентификации:', data.message);
+    
+    // Возможная реакция на ошибку (переподключение, запрос нового токена и т.д.)
+    switch (data.code) {
+      case 'TOKEN_EXPIRED':
+        // Запросить новый токен
+        break;
+      case 'INVALID_TOKEN':
+        // Перенаправить на страницу входа
+        break;
+      default:
+        // Общая обработка ошибок
+        break;
+    }
+  }
+};
+```
+
+### Коды ошибок аутентификации
+
+| Код ошибки | Описание |
+|------------|----------|
+| `TOKEN_EXPIRED` | Истек срок действия токена |
+| `INVALID_TOKEN` | Недействительный токен |
+| `MISSING_TOKEN` | Отсутствует токен |
+| `AUTH_ERROR` | Общая ошибка аутентификации |
+| `FORBIDDEN` | Доступ запрещен |
+
+## Примеры
+
+### Полный пример аутентификации для рассуждений
+
+```javascript
+const { CodeSolverSDK, WebSocketNamespace } = require('solver-sdk');
+
+async function exampleWithAuthentication() {
+  // 1. Создаем экземпляр SDK
+  const sdk = new CodeSolverSDK({
+    baseURL: 'https://api.example.com',
+    apiKey: 'your-api-key'
+  });
+  
+  // 2. Создаем рассуждение
+  const reasoning = await sdk.reasoning.createReasoning({
+    projectId: 'project-id',
+    query: 'Объясни этот проект'
+  });
+  
+  // 3. Подключаемся через WebSocket с аутентификацией
+  await sdk.reasoning.connectWebSocket({
+    reasoningId: reasoning.id,
+    authToken: 'your-auth-token'
+  });
+  
+  // 4. Настраиваем обработчики событий
+  sdk.reasoning.on('authentication_error', (data) => {
+    console.error('Ошибка аутентификации:', data);
+  });
+  
+  sdk.reasoning.on('authenticated', (data) => {
+    console.log('Успешная аутентификация:', data);
+  });
+  
+  // 5. Отправляем запрос
+  await sdk.reasoning.startReasoning(reasoning.id);
+}
+``` 

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();
+  }
+}
+```