solver-sdk 1.8.0 → 1.8.1

package/docs/API_REFERENCE.md

@@ -0,0 +1,432 @@
+# API Reference
+
+В этом документе описаны основные классы и методы SDK.
+
+## Содержание
+
+- [CodeSolverSDK](#codesolversdk)
+- [ChatApi](#chatapi)
+- [ProjectsApi](#projectsapi)
+- [SearchApi](#searchapi)
+- [ReasoningApi](#reasoningapi)
+- [WebSocketClient](#websocketclient)
+
+## CodeSolverSDK
+
+Основной класс SDK, предоставляющий доступ ко всем API.
+
+### Конструктор
+
+```javascript
+const sdk = new CodeSolverSDK(options);
+```
+
+### Параметры
+
+| Параметр | Тип | Описание | Обязательно |
+|----------|-----|----------|-------------|
+| `baseURL` | string | Базовый URL API | Да |
+| `apiKey` | string | API ключ для авторизации | Нет |
+| `wsURL` | string | URL для WebSocket соединений (если отличается от baseURL) | Нет |
+| `timeout` | number | Таймаут для HTTP запросов (мс) | Нет |
+| `headers` | object | Дополнительные HTTP заголовки | Нет |
+| `websocket` | object | Настройки WebSocket соединений | Нет |
+| `mode` | string | Режим работы SDK ('browser', 'node', 'auto') | Нет |
+
+### Методы
+
+#### `getWebSocketClient()`
+
+Возвращает экземпляр WebSocket клиента для работы с соединениями.
+
+```javascript
+const wsClient = sdk.getWebSocketClient();
+```
+
+#### `checkHealth()`
+
+Проверяет доступность API сервера.
+
+```javascript
+const isHealthy = await sdk.checkHealth();
+```
+
+#### `connect()`
+
+Подключается к WebSocket серверу.
+
+```javascript
+await sdk.connect();
+```
+
+#### `disconnect()`
+
+Отключается от WebSocket сервера.
+
+```javascript
+await sdk.disconnect();
+```
+
+#### `dispose()`
+
+Освобождает ресурсы, включая WebSocket соединения.
+
+```javascript
+sdk.dispose();
+```
+
+#### `setApiKey(apiKey)`
+
+Устанавливает новый API ключ для SDK.
+
+```javascript
+sdk.setApiKey('новый-api-ключ');
+```
+
+## ChatApi
+
+API для работы с чатом и AI-моделями.
+
+### Методы
+
+#### `chat(messages, options)`
+
+Отправляет запрос чата и возвращает полный ответ.
+
+```javascript
+const response = await sdk.chat.chat(
+  messages,
+  options
+);
+```
+
+##### Параметры
+
+| Параметр | Тип | Описание | Обязательно |
+|----------|-----|----------|-------------|
+| `messages` | Array | Массив сообщений для отправки модели | Да |
+| `options` | Object | Параметры запроса (модель, temperature и т.д.) | Нет |
+
+#### `streamChatWithThinking(messages, options, onEvent)`
+
+Отправляет запрос чата в потоковом режиме с получением "мышления" модели.
+
+```javascript
+const response = await sdk.chat.streamChatWithThinking(
+  messages,
+  { 
+    model: 'claude-3-7-sonnet-20240229',
+    thinking: true,
+    temperature: 0.7 
+  },
+  (eventType, data) => {
+    if (eventType === 'thinking_delta') {
+      console.log('Мышление:', data.thinking);
+    } else if (eventType === 'text_delta') {
+      console.log('Ответ:', data.text);
+    }
+  }
+);
+```
+
+#### `connectWebSocket()`
+
+Создает новое WebSocket соединение для потокового чата.
+
+```javascript
+await sdk.chat.connectWebSocket();
+```
+
+#### `getModels()`
+
+Получает список доступных моделей.
+
+```javascript
+const models = await sdk.chat.getModels();
+```
+
+## ProjectsApi
+
+API для работы с проектами.
+
+### Методы
+
+#### `getAllProjects()`
+
+Получает список всех проектов.
+
+```javascript
+const projects = await sdk.projects.getAllProjects();
+```
+
+#### `getProject(projectId)`
+
+Получает информацию о проекте по ID.
+
+```javascript
+const project = await sdk.projects.getProject('project-id');
+```
+
+#### `createProject(name, path, options)`
+
+Создаёт новый проект.
+
+```javascript
+const project = await sdk.projects.createProject('Мой проект', '/path/to/project', {
+  excludePatterns: ['node_modules', '.git']
+});
+```
+
+#### `updateProject(projectId, data)`
+
+Обновляет проект.
+
+```javascript
+await sdk.projects.updateProject('project-id', { name: 'Новое имя' });
+```
+
+#### `deleteProject(projectId)`
+
+Удаляет проект.
+
+```javascript
+await sdk.projects.deleteProject('project-id');
+```
+
+#### `indexProject(projectId)`
+
+Запускает индексацию проекта.
+
+```javascript
+await sdk.projects.indexProject('project-id');
+```
+
+#### `getOrCreateProject(path, name)`
+
+Получает существующий проект по пути или создает новый, если проект не найден.
+
+```javascript
+const project = await sdk.projects.getOrCreateProject('/path/to/project', 'Название проекта');
+```
+
+#### `indexProjectByPath(path, options)`
+
+Индексирует проект по указанному пути. Если проект не существует, он будет создан автоматически.
+
+```javascript
+const result = await sdk.projects.indexProjectByPath('/path/to/project', {
+  name: 'Название проекта',
+  forceFull: true, // принудительная полная индексация
+  excludePatterns: ['node_modules', '.git'] // паттерны для исключения
+});
+```
+
+#### `createAndIndexProject(path, options)`
+
+Комбинированный метод для создания (если не существует) и индексации проекта в одной операции.
+
+```javascript
+const result = await sdk.projects.createAndIndexProject('/path/to/project', {
+  name: 'Название проекта',
+  forceFull: false,
+  excludePatterns: ['node_modules', '.git']
+});
+```
+
+#### `connectWebSocket()`
+
+Подключается к WebSocket для отслеживания индексации.
+
+```javascript
+await sdk.projects.connectWebSocket();
+```
+
+#### `disconnectWebSocket()`
+
+Отключается от WebSocket индексации.
+
+```javascript
+await sdk.projects.disconnectWebSocket();
+```
+
+#### `on(event, callback)`
+
+Добавляет обработчик события для индексации.
+
+```javascript
+sdk.projects.on('indexing_progress', (data) => {
+  console.log(`Прогресс: ${data.progress}%`);
+});
+```
+
+#### `stopIndexing(projectId)`
+
+Останавливает индексацию проекта.
+
+```javascript
+await sdk.projects.stopIndexing('project-id');
+```
+
+#### `getIndexingStatus(projectId)`
+
+Получает статус индексации проекта.
+
+```javascript
+const status = await sdk.projects.getIndexingStatus('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,
+  includeContent: true
+});
+```
+
+## 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');
+```
+
+#### `connectWebSocket(reasoningId)`
+
+Подключается к WebSocket для отслеживания рассуждений.
+
+```javascript
+await sdk.reasoning.connectWebSocket('reasoning-id');
+```
+
+#### `startReasoning(reasoningId)`
+
+Запускает процесс рассуждения.
+
+```javascript
+await sdk.reasoning.startReasoning('reasoning-id');
+```
+
+#### `on(event, callback)`
+
+Добавляет обработчик события для рассуждений.
+
+```javascript
+sdk.reasoning.on('thinking', (data) => {
+  console.log('Мышление:', data.content);
+});
+
+sdk.reasoning.on('complete', (data) => {
+  console.log('Результат:', data.content);
+});
+```
+
+## WebSocketClient
+
+Клиент для работы с WebSocket соединениями. Получается через `sdk.getWebSocketClient()`.
+
+### Методы
+
+#### `connectToReasoning(reasoningId)`
+
+Подключается к namespace рассуждений.
+
+```javascript
+await wsClient.connectToReasoning('reasoning-id');
+```
+
+#### `connectToIndexing(projectId)`
+
+Подключается к namespace индексации.
+
+```javascript
+await wsClient.connectToIndexing('project-id');
+```
+
+#### `disconnect(namespace)`
+
+Отключается от определенного namespace.
+
+```javascript
+await wsClient.disconnect(WebSocketNamespace.REASONING);
+```
+
+#### `disconnectAll()`
+
+Отключается от всех namespace.
+
+```javascript
+await wsClient.disconnectAll();
+```
+
+#### `isConnected(namespace)`
+
+Проверяет подключение к определенному namespace.
+
+```javascript
+const isConnected = wsClient.isConnected(WebSocketNamespace.REASONING);
+```
+
+#### `isConnectedToReasoning()`
+
+Проверяет подключение к namespace рассуждений.
+
+```javascript
+const isConnected = wsClient.isConnectedToReasoning();
+```
+
+#### `isConnectedToIndexing()`
+
+Проверяет подключение к namespace индексации.
+
+```javascript
+const isConnected = wsClient.isConnectedToIndexing();
+```
+
+#### `on(event, callback, namespace)`
+
+Добавляет обработчик события для определенного namespace.
+
+```javascript
+wsClient.on('thinking', (data) => {
+  console.log('Мышление:', data);
+}, WebSocketNamespace.REASONING);
+```

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