solver-sdk 2.5.0 → 2.6.1

package/docs/API_REFERENCE.md

@@ -1,77 +1,76 @@
-# API Reference
+# API Reference v2.5.0
 
-В этом документе описаны основные классы и методы SDK.
+В этом документе описаны основные классы и методы AI Solver SDK v2.5.0.
 
 ## Содержание
 
 - [CodeSolverSDK](#codesolversdk)
-- [ChatApi](#chatapi)
 - [ProjectsApi](#projectsapi)
-- [SearchApi](#searchapi)
 - [ReasoningApi](#reasoningapi)
+- [ChatApi](#chatapi)
+- [SearchApi](#searchapi)
+- [Helper Functions](#helper-functions)
 
 ## CodeSolverSDK
 
 Основной класс SDK, предоставляющий доступ ко всем API.
 
-### Конструктор
+### Статический создатель (Рекомендуемый)
 
 ```javascript
-const sdk = new CodeSolverSDK(options);
+const sdk = CodeSolverSDK.create(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') | Нет |
+| Параметр | Тип | Описание | Обязательно | По умолчанию |
+|----------|-----|----------|-------------|--------------|
+| `baseURL` | string | Базовый URL API | Да | - |
+| `apiKey` | string | API ключ для авторизации | Да | - |
+| `autoConnect` | boolean | Автоматическое подключение WebSocket | Нет | false |
+| `timeout` | number | Таймаут для HTTP запросов (мс) | Нет | 30000 |
+| `headers` | object | Дополнительные HTTP заголовки | Нет | {} |
+| `wsURL` | string | URL для WebSocket (если отличается) | Нет | baseURL |
 
 ### Методы
 
-#### `checkHealth()`
-
-Проверяет доступность API сервера.
-
-```javascript
-const isHealthy = await sdk.checkHealth();
-```
-
-#### `connect()`
+#### `diagnoseAPI()`
 
-Подключается ко всем WebSocket сервисам одновременно.
+Проверяет доступность всех API endpoints.
 
 ```javascript
-await sdk.connect();
+const results = await sdk.diagnoseAPI();
+console.log('Endpoints status:', results);
+// Возвращает объект с результатами проверки каждого endpoint
 ```
 
-#### `disconnect()`
+#### `diagnoseFull()`
 
-Отключается от всех WebSocket серверов.
+Детальная диагностика API и WebSocket.
 
 ```javascript
-await sdk.disconnect();
+const detailed = await sdk.diagnoseFull();
+console.log('Full diagnostics:', detailed);
 ```
 
-#### `dispose()`
+#### `diagnoseWebSocket()`
 
-Освобождает ресурсы, включая WebSocket соединения.
+Проверяет статус WebSocket соединений.
 
 ```javascript
-sdk.dispose();
+const wsStatus = await sdk.diagnoseWebSocket();
+console.log('WebSocket status:', wsStatus);
 ```
 
-#### `setApiKey(apiKey)`
+#### `updateOptions(newOptions)`
 
-Устанавливает новый API ключ для SDK.
+Обновляет настройки SDK.
 
 ```javascript
-sdk.setApiKey('новый-api-ключ');
+sdk.updateOptions({
+  apiKey: 'new-api-key',
+  timeout: 60000
+});
 ```
 
 ## ChatApi
@@ -135,51 +134,64 @@ await sdk.chat.connectWebSocket();
 
 ## ProjectsApi
 
-API для работы с проектами.
+API для работы с проектами. Доступен через `sdk.projects`.
 
 ### Методы
 
-#### `createProject(name, path, options)`
+#### `create(projectData)`
 
 Создает новый проект.
 
 ```javascript
-const project = await sdk.projects.createProject(
-  'Мой проект',
-  '/path/to/project',
-  { excludePatterns: ['node_modules', '.git'] }
-);
+const project = await sdk.projects.create({
+  name: 'My Project',
+  path: '/path/to/project',
+  description: 'Optional description'
+});
+
+// Возвращает объект проекта с id, name, path, статусами и метаданными
 ```
 
-#### `getProject(projectId)`
+#### `get(projectId)`
 
-Получает информацию о проекте.
+Получает информацию о проекте по ID.
 
 ```javascript
-const project = await sdk.projects.getProject('project-id');
+const project = await sdk.projects.get('project-id');
 ```
 
-#### `getAllProjects()`
+#### `getAll()`
 
 Получает список всех проектов.
 
 ```javascript
-const projects = await sdk.projects.getAllProjects();
+const projects = await sdk.projects.getAll();
+// Возвращает { projects: Array, total: number }
 ```
 
-#### `indexProject(projectId, options)`
+#### `startIndexing(projectId)`
 
 Запускает индексацию проекта.
 
 ```javascript
-await sdk.projects.indexProject('project-id', {
-  indexingMode: 'full' // или 'incremental', 'auto'
-});
+await sdk.projects.startIndexing('project-id');
+// Возвращает { message: 'Индексация запущена', projectId, status: 'accepted' }
 ```
 
+#### `getIndexingStatus(projectId)`
+
+Получает статус индексации проекта.
+
+```javascript
+const status = await sdk.projects.getIndexingStatus('project-id');
+// Возвращает { projectId, indexStatus, indexingProgress, filesIndexed, lastUpdated }
+```
+
+### WebSocket методы
+
 #### `connectWebSocket()`
 
-Подключается к WebSocket для отслеживания индексации.
+Подключается к WebSocket для отслеживания событий проектов.
 
 ```javascript
 await sdk.projects.connectWebSocket();
@@ -187,118 +199,505 @@ await sdk.projects.connectWebSocket();
 
 #### `disconnectWebSocket()`
 
-Отключается от WebSocket индексации.
+Отключается от WebSocket.
 
 ```javascript
 await sdk.projects.disconnectWebSocket();
 ```
 
-#### `on(event, callback)`
+### Event методы
+
+#### `onIndexingProgress(callback)`
 
-Добавляет обработчик события для индексации.
+Отслеживает прогресс индексации.
 
 ```javascript
-sdk.projects.on('indexing_progress', (data) => {
-  console.log(`Прогресс: ${data.progress}%`);
+sdk.projects.onIndexingProgress((data) => {
+  console.log(`Progress: ${data.percentage}%`);
+  console.log(`Files: ${data.processedFiles}/${data.totalFiles}`);
 });
 ```
 
-#### `stopIndexing(projectId)`
+#### `onIndexingComplete(callback)`
 
-Останавливает индексацию проекта.
+Событие завершения индексации.
 
 ```javascript
-await sdk.projects.stopIndexing('project-id');
+sdk.projects.onIndexingComplete((data) => {
+  console.log('Indexing completed:', data.projectId);
+  console.log('Total files:', data.totalFiles);
+});
 ```
 
-#### `getIndexingStatus(projectId)`
+#### `onIndexingError(callback)`
 
-Получает статус индексации проекта.
+Событие ошибки индексации.
 
 ```javascript
-const status = await sdk.projects.getIndexingStatus('project-id');
+sdk.projects.onIndexingError((error) => {
+  console.error('Indexing error:', error.message);
+});
+```
+
+### Алиасы для совместимости
+
+```javascript
+// Старые методы (deprecated, но работают)
+await sdk.projects.createProject(name, path, options); // → create()
+await sdk.projects.indexProject(projectId);            // → startIndexing()
+await sdk.projects.getProject(projectId);              // → get()
+await sdk.projects.getAllProjects();                   // → getAll()
 ```
 
 ## SearchApi
 
-API для поиска кода.
+API для семантического поиска кода. Доступен через `sdk.search`.
 
 ### Методы
 
-#### `searchCode(projectId, options)`
+#### `searchProject(projectId, options)`
 
-Выполняет поиск кода в проекте.
+Выполняет семантический поиск в проекте (POST запрос).
 
 ```javascript
-const results = await sdk.search.searchCode('project-id', {
-  query: 'function example',
-  limit: 10
+const results = await sdk.search.searchProject('project-id', {
+  query: 'функция для обработки HTTP запросов',
+  limit: 10,
+  minScore: 0.7
 });
+
+// Возвращает массив результатов с релевантностью и фрагментами кода
 ```
 
-#### `semanticSearch(projectId, options)`
+#### `searchProjectGet(projectId, query, options)`
 
-Выполняет семантический поиск в проекте.
+Выполняет поиск через GET запрос с параметрами URL.
 
 ```javascript
-const results = await sdk.search.semanticSearch('project-id', {
-  query: 'функция для обработки HTTP запросов',
-  limit: 10,
-  includeContent: true
+const results = await sdk.search.searchProjectGet(
+  'project-id',
+  'поиск по коду',
+  { limit: 10 }
+);
+```
+
+### Алиасы для совместимости
+
+```javascript
+// Старые методы (deprecated, но работают)
+await sdk.search.searchCode(projectId, options);     // → searchProject()
+await sdk.search.semanticSearch(projectId, options); // → searchProject()
+```
+
+## ChatApi
+
+API для взаимодействия с AI чатом и Claude 4 thinking. Доступен через `sdk.chat`.
+
+### Методы
+
+#### `send(messages, options)`
+
+Отправляет сообщения в чат и получает ответ.
+
+```javascript
+const response = await sdk.chat.send([
+  {
+    role: 'user',
+    content: 'Объясни как работает эта функция'
+  }
+], {
+  projectId: 'project-id',
+  model: 'claude-3-5-sonnet-20241022'
+});
+
+console.log(response.content);
+```
+
+#### `stream(messages, options, onChunk)`
+
+Отправляет сообщения с потоковой передачей ответа.
+
+```javascript
+await sdk.chat.stream(
+  messages,
+  {
+    projectId: 'project-id',
+    model: 'claude-3-5-sonnet-20241022',
+    thinking: true
+  },
+  (chunk) => {
+    console.log('Chunk received:', chunk);
+  }
+);
+```
+
+### Thinking Support (Claude 4)
+
+#### С thinking блоками
+
+```javascript
+await sdk.chat.stream(
+  messages,
+  {
+    thinking: true,
+    tool_choice: { type: 'auto' } // Только auto/none с thinking
+  },
+  (eventType, data) => {
+    switch (eventType) {
+      case 'thinking_delta':
+        console.log('Thinking:', data.thinking);
+        break;
+      case 'text_delta':
+        console.log('Text:', data.text);
+        break;
+      case 'tool_use':
+        console.log('Tool:', data.tool_name);
+        break;
+    }
+  }
+);
+```
+
+### Complex Content Support
+
+```javascript
+const complexMessage = {
+  role: 'user',
+  content: [
+    { type: 'text', text: 'Анализируй этот код:' },
+    { type: 'text', text: 'function example() { return 42; }' }
+  ]
+};
+
+const response = await sdk.chat.send([complexMessage], options);
+```
+
+### WebSocket методы
+
+#### `connectWebSocket()`
+
+Подключается к WebSocket для потокового чата.
+
+```javascript
+await sdk.chat.connectWebSocket();
+```
+
+#### `disconnectWebSocket()`
+
+Отключается от chat WebSocket.
+
+```javascript
+await sdk.chat.disconnectWebSocket();
+```
+
+### Event методы
+
+#### `onTextDelta(callback)`
+
+Событие получения текстового фрагмента.
+
+```javascript
+sdk.chat.onTextDelta((text) => {
+  console.log('Text delta:', text);
 });
 ```
 
+#### `onThinkingDelta(callback)`
+
+Событие получения thinking фрагмента.
+
+```javascript
+sdk.chat.onThinkingDelta((thinking) => {
+  console.log('Thinking delta:', thinking);
+});
+```
+
+#### `onToolUse(callback)`
+
+Событие использования инструмента.
+
+```javascript
+sdk.chat.onToolUse((tool) => {
+  console.log('Tool used:', tool.name, tool.input);
+});
+```
+
+#### `onMessageComplete(callback)`
+
+Событие завершения сообщения.
+
+```javascript
+sdk.chat.onMessageComplete((message) => {
+  console.log('Message completed:', message);
+});
+```
+
+### Поддерживаемые модели
+
+```javascript
+const models = [
+  'claude-3-5-sonnet-20241022',
+  'claude-3-5-haiku-20241022',
+  'claude-3-opus-20240229'
+];
+```
+
 ## ReasoningApi
 
-API для работы с рассуждениями.
+API для работы с AI reasoning процессами. Доступен через `sdk.reasoning`.
 
 ### Методы
 
-#### `createReasoning(options)`
+#### `create(reasoningData)`
 
-Создаёт новое рассуждение.
+Создаёт новый reasoning процесс.
 
 ```javascript
-const reasoning = await sdk.reasoning.createReasoning({
+const reasoning = await sdk.reasoning.create({
   projectId: 'project-id',
-  query: 'Объясни этот проект'
+  query: 'Проанализируй архитектуру этого проекта'
 });
+
+// Возвращает объект reasoning с id, projectId, query, status
+```
+
+#### `get(reasoningId)`
+
+Получает информацию о reasoning процессе.
+
+```javascript
+const reasoning = await sdk.reasoning.get('reasoning-id');
+```
+
+#### `getByProject(projectId)`
+
+Получает все reasoning процессы проекта.
+
+```javascript
+const reasonings = await sdk.reasoning.getByProject('project-id');
+// Возвращает массив всех reasoning процессов проекта
+```
+
+#### `start(reasoningId)`
+
+Запускает reasoning процесс.
+
+```javascript
+await sdk.reasoning.start('reasoning-id');
+// Возвращает { message: 'Reasoning процесс запущен', id: reasoningId }
+```
+
+#### `stop(reasoningId)`
+
+Останавливает reasoning процесс.
+
+```javascript
+await sdk.reasoning.stop('reasoning-id');
+// Возвращает { message: 'Reasoning процесс остановлен', id: reasoningId }
+```
+
+### WebSocket методы
+
+#### `connectWebSocket()`
+
+Подключается к WebSocket для отслеживания reasoning событий.
+
+```javascript
+await sdk.reasoning.connectWebSocket();
 ```
 
-#### `getReasoning(reasoningId)`
+#### `disconnectWebSocket()`
+
+Отключается от reasoning WebSocket.
+
+```javascript
+await sdk.reasoning.disconnectWebSocket();
+```
+
+### Event методы
+
+#### `onReasoningStarted(callback)`
 
-Получает информацию о рассуждении.
+Событие начала reasoning процесса.
 
 ```javascript
-const reasoning = await sdk.reasoning.getReasoning('reasoning-id');
+sdk.reasoning.onReasoningStarted((data) => {
+  console.log('Reasoning started:', data.id);
+  console.log('Query:', data.query);
+});
 ```
 
-#### `connectWebSocket(reasoningId)`
+#### `onReasoningProgress(callback)`
 
-Подключается к WebSocket для отслеживания рассуждений.
+Отслеживает прогресс reasoning.
 
 ```javascript
-await sdk.reasoning.connectWebSocket('reasoning-id');
+sdk.reasoning.onReasoningProgress((data) => {
+  console.log('Progress:', data.progress);
+  console.log('Current step:', data.currentStep);
+});
 ```
 
-#### `startReasoning(reasoningId)`
+#### `onReasoningCompleted(callback)`
 
-Запускает процесс рассуждения.
+Событие завершения reasoning.
 
 ```javascript
-await sdk.reasoning.startReasoning('reasoning-id');
+sdk.reasoning.onReasoningCompleted((data) => {
+  console.log('Reasoning completed:', data.id);
+  console.log('Results:', data.results);
+});
 ```
 
-#### `on(event, callback)`
+#### `onReasoningError(callback)`
 
-Добавляет обработчик события для рассуждений.
+Событие ошибки reasoning.
 
 ```javascript
-sdk.reasoning.on('thinking', (data) => {
-  console.log('Мышление:', data.content);
+sdk.reasoning.onReasoningError((error) => {
+  console.error('Reasoning error:', error.message);
 });
+```
+
+### Алиасы для совместимости
+
+```javascript
+// Новые алиасы методов (v2.5.0)
+await sdk.reasoning.create(data);      // основной метод
+await sdk.reasoning.start(id);         // основной метод
+await sdk.reasoning.stop(id);          // основной метод
+
+// Старые методы (deprecated, но работают)
+await sdk.reasoning.createReasoning(data);  // → create()
+await sdk.reasoning.startReasoning(id);     // → start()
+await sdk.reasoning.stopReasoning(id);      // → stop()
+```
+
+## Helper Functions
+
+Вспомогательные функции для работы с сообщениями и инструментами.
+
+### Message Helpers
+
+#### `createComplexAssistantMessage(textContent, thinkingBlocks, toolUseBlocks)`
+
+Создает сложное assistant сообщение с thinking и tool blocks.
+
+```javascript
+import { createComplexAssistantMessage } from '@ai-solver/sdk';
+
+const message = createComplexAssistantMessage(
+  'Вот анализ кода:',
+  ['thinking block 1', 'thinking block 2'],
+  [{ type: 'tool_use', name: 'read_file', input: { path: 'app.js' } }]
+);
+```
+
+#### `createToolResultMessage(toolUseId, isError, content)`
+
+Создает сообщение с результатом выполнения инструмента.
+
+```javascript
+import { createToolResultMessage } from '@ai-solver/sdk';
+
+const resultMessage = createToolResultMessage(
+  'tool_use_123',
+  false,
+  'File contents: console.log("Hello");'
+);
+```
+
+#### `extractThinkingBlocks(message)`
 
-sdk.reasoning.on('complete', (data) => {
-  console.log('Результат:', data.content);
+Извлекает thinking блоки из сообщения.
+
+```javascript
+import { extractThinkingBlocks } from '@ai-solver/sdk';
+
+const thinkingBlocks = extractThinkingBlocks(assistantMessage);
+console.log('Thinking blocks:', thinkingBlocks);
+```
+
+#### `extractToolUseBlocks(message)`
+
+Извлекает tool_use блоки из сообщения.
+
+```javascript
+import { extractToolUseBlocks } from '@ai-solver/sdk';
+
+const toolBlocks = extractToolUseBlocks(assistantMessage);
+console.log('Tool blocks:', toolBlocks);
+```
+
+### Tool Helpers
+
+#### `createStandardDevelopmentTools()`
+
+Создает стандартный набор инструментов для разработки (8 инструментов как в Cursor).
+
+```javascript
+import { createStandardDevelopmentTools } from '@ai-solver/sdk';
+
+const tools = createStandardDevelopmentTools();
+// Возвращает массив с инструментами:
+// - read_file
+// - edit_file
+// - create_file
+// - list_directory
+// - search_files
+// - run_command
+// - analyze_code
+// - explain_code
+
+const response = await sdk.chat.stream(messages, {
+  tools: tools,
+  tool_choice: { type: 'auto' }
 });
-```
+```
+
+### Type Definitions
+
+#### `ChatMessage`
+
+```typescript
+interface ChatMessage {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string | ContentBlock[];
+  name?: string;
+  tool_call_id?: string;
+}
+```
+
+#### `ContentBlock`
+
+```typescript
+interface ContentBlock {
+  type: 'text' | 'tool_use' | 'tool_result' | 'thinking';
+  text?: string;
+  id?: string;
+  name?: string;
+  input?: any;
+  content?: any;
+  is_error?: boolean;
+}
+```
+
+#### `ChatOptions`
+
+```typescript
+interface ChatOptions {
+  projectId?: string;
+  model?: string;
+  thinking?: boolean;
+  tools?: Tool[];
+  tool_choice?: ToolChoice;
+  max_tokens?: number;
+  temperature?: number;
+  stream?: boolean;
+}
+```
+
+---
+
+**Документация обновлена для SDK v2.5.0**  
+**Дата обновления:** 28 июня 2025