solver-sdk 2.5.0 → 2.6.1

package/docs/README.md

@@ -1,106 +1,291 @@
-23# Code Solver SDK
+# AI Solver SDK v2.5.0 Documentation
 
-JavaScript/TypeScript SDK для взаимодействия с API Code Solver, предназначенного для умной работы с кодом, семантического поиска и AI-ассистентов.
+Полная документация для AI Solver SDK версии 2.5.0.
 
-## Установка
+## 🚀 Быстрый старт
+
+### Установка
 
 ```bash
-npm install @code-solver/sdk
+npm install @ai-solver/sdk
 ```
 
-## Основные возможности
+### Базовое использование
 
-- **Работа с проектами**: создание, индексация и управление проектами
-- **Семантический поиск**: поиск по смыслу в коде проекта
-- **AI-чат с контекстом**: взаимодействие с AI-моделями в контексте проекта
-- **Работа с WebSocket**: потоковая обработка событий и ответов
-- **Мультиплатформенность**: поддержка как браузеров, так и Node.js
+```javascript
+import { CodeSolverSDK } from '@ai-solver/sdk';
 
-## Быстрый старт
+const sdk = CodeSolverSDK.create({
+  baseURL: 'http://localhost:3000',
+  apiKey: 'dev_sk_test_12345678',
+  autoConnect: false
+});
 
-```javascript
-import { CodeSolverSDK } from '@code-solver/sdk';
-
-// Инициализация SDK
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://api.code-solver.com',
-  apiKey: 'ваш-api-ключ',
-  websocket: {
-    reconnect: true,
-    reconnectAttempts: 5
-  }
+// Создание проекта
+const project = await sdk.projects.create({
+  name: 'My AI Project',
+  path: '/path/to/project'
 });
 
-// Проверка доступности API
-const isAvailable = await sdk.checkHealth();
-if (!isAvailable) {
-  console.error('API недоступен');
-  return;
-}
+// AI Chat
+const response = await sdk.chat.send([
+  { role: 'user', content: 'Проанализируй этот код' }
+], {
+  projectId: project.id,
+  thinking: true
+});
+```
 
-// Единое подключение ко всем WebSocket сервисам
-await sdk.connect();
+## 📚 Документация
 
-// Создание проекта
-const project = await sdk.projects.createProject(
-  'Мой проект',
-  '/путь/к/проекту',
-  {
-    excludePatterns: ['node_modules', '.git', 'dist']
-  }
-);
+### Основные руководства
 
-// Индексация проекта
-await sdk.projects.indexProject(project.id);
+| Документ | Описание |
+|----------|----------|
+| **[API Reference](./API_REFERENCE.md)** | Полное описание всех методов SDK |
+| **[Integration Guide v2.5](./INTEGRATION_GUIDE_V2.5.md)** | Пошаговое руководство интеграции |
+| **[WebSocket API](./WEBSOCKET.md)** | WebSocket события и real-time функции |
+| **[Authentication](./AUTHENTICATION.md)** | Аутентификация и API ключи |
+| **[Error Handling](./ERROR_HANDLING.md)** | Обработка ошибок и диагностика |
 
-// Отслеживание прогресса индексации через WebSocket
-sdk.projects.on('indexing_progress', (data) => {
-  console.log(`Прогресс индексации: ${data.progress}%`);
-});
+### Специализированные функции
+
+| Документ | Описание |
+|----------|----------|
+| **[Thinking Features](./features/THINKING.md)** | Claude 4 thinking и tool calling |
+| **[Indexing Guide](./indexing/INDEXING.md)** | Индексация проектов |
 
-sdk.projects.on('indexing_complete', (data) => {
-  console.log('Индексация завершена!');
+## ✨ Новые возможности v2.5.0
+
+### 🔄 Контролируемые подключения
+
+```javascript
+const sdk = CodeSolverSDK.create({
+  autoConnect: false // Ключевая настройка
 });
 
-// Семантический поиск
-const searchResults = await sdk.search.semanticSearch(project.id, {
-  query: 'функция для обработки HTTP запросов',
-  limit: 10
+// Подключение только когда нужно
+await sdk.projects.connectWebSocket();
+await sdk.reasoning.connectWebSocket();
+```
+
+### 🧠 Claude 4 Thinking Support
+
+```javascript
+await sdk.chat.stream(messages, {
+  thinking: true,
+  tool_choice: { type: 'auto' }
+}, (eventType, data) => {
+  if (eventType === 'thinking_delta') {
+    console.log('Thinking:', data.thinking);
+  }
 });
+```
+
+### 📊 Расширенная диагностика
+
+```javascript
+// Проверка всех endpoints
+const apiStatus = await sdk.diagnoseAPI();
+
+// Статус WebSocket соединений
+const wsStatus = await sdk.diagnoseWebSocket();
+```
+
+### 🔧 Helper функции
+
+```javascript
+import { 
+  createStandardDevelopmentTools,
+  createComplexAssistantMessage,
+  extractThinkingBlocks
+} from '@ai-solver/sdk';
+```
+
+## 🎯 API Endpoints
+
+### Projects API
+- `POST /api/v1/projects` - Создание проекта
+- `GET /api/v1/projects` - Список проектов
+- `POST /api/v1/projects/:id/index` - Запуск индексации
+
+### Reasoning API
+- `POST /api/v1/reasoning` - Создание reasoning
+- `POST /api/v1/reasoning/start/:id` - Запуск reasoning
+- `GET /api/v1/reasoning/project/:id` - Reasoning проекта
+
+### Chat API
+- `POST /api/v1/chat` - Обычный чат
+- `POST /api/v1/chat/stream` - Потоковый чат
+
+### Search API
+- `GET /api/v1/search/project/:id` - Поиск в проекте
 
-// Взаимодействие с AI-ассистентом
-const chatResponse = await sdk.chat.chat([
-  {
-    role: 'system',
-    content: 'Ты опытный программист, помогающий разработчику.'
-  },
-  {
-    role: 'user',
-    content: 'Объясни, как работает функция getUserProfile в моем проекте.'
+## 🔌 WebSocket Namespaces
+
+| Namespace | URL | События |
+|-----------|-----|---------|
+| **Projects** | `/projects` | `indexing_progress`, `indexing_complete` |
+| **Reasoning** | `/reasoning` | `reasoning_started`, `reasoning_completed` |
+| **Chat** | `/chat` | `text_delta`, `thinking_delta`, `tool_use` |
+
+## 🔑 Аутентификация
+
+### Development
+
+```bash
+export AI_SOLVER_API_KEY=dev_sk_test_12345678
+```
+
+### Production
+
+```bash
+export AI_SOLVER_API_KEY=sk_prod_1234567890abcd
+```
+
+## 🚨 Миграция с предыдущих версий
+
+### Основные изменения
+
+1. **Новый способ создания SDK**
+   ```javascript
+   // Старый способ
+   const sdk = new CodeSolverSDK(options);
+   
+   // Новый способ (v2.5.0)
+   const sdk = CodeSolverSDK.create(options);
+   ```
+
+2. **Контролируемые WebSocket**
+   ```javascript
+   // Обязательно добавить
+   autoConnect: false
+   ```
+
+3. **Новые алиасы методов**
+   ```javascript
+   // Reasoning API
+   await sdk.reasoning.create(data);   // вместо createReasoning()
+   await sdk.reasoning.start(id);      // вместо startReasoning()
+   
+   // Projects API
+   await sdk.projects.create(data);    // вместо createProject()
+   await sdk.projects.getAll();        // вместо getAllProjects()
+   ```
+
+## 📝 Примеры использования
+
+### Полный workflow
+
+```javascript
+async function completeWorkflow() {
+  // Создание SDK
+  const sdk = CodeSolverSDK.create({
+    baseURL: 'http://localhost:3000',
+    apiKey: process.env.AI_SOLVER_API_KEY,
+    autoConnect: false
+  });
+  
+  // Диагностика
+  const status = await sdk.diagnoseAPI();
+  console.log('API status:', status);
+  
+  // Создание проекта
+  const project = await sdk.projects.create({
+    name: 'AI Analysis',
+    path: '/path/to/code'
+  });
+  
+  // Индексация с WebSocket
+  await sdk.projects.connectWebSocket();
+  sdk.projects.onIndexingComplete(() => {
+    console.log('Indexing done!');
+  });
+  await sdk.projects.startIndexing(project.id);
+  
+  // AI Reasoning
+  await sdk.reasoning.connectWebSocket();
+  const reasoning = await sdk.reasoning.create({
+    projectId: project.id,
+    query: 'Анализируй архитектуру'
+  });
+  await sdk.reasoning.start(reasoning.id);
+  
+  // Chat с thinking
+  await sdk.chat.connectWebSocket();
+  await sdk.chat.stream([
+    { role: 'user', content: 'Объясни результаты' }
+  ], {
+    projectId: project.id,
+    thinking: true
+  });
+}
+```
+
+## 🛠️ Разработка и отладка
+
+### Debug режим
+
+```javascript
+const sdk = CodeSolverSDK.create({
+  baseURL: 'http://localhost:3000',
+  apiKey: 'dev_sk_test_12345678',
+  autoConnect: false,
+  headers: {
+    'X-Debug': 'true'
   }
-], {
-  projectId: project.id,
-  model: 'claude-3-7-sonnet-20240229'
 });
+```
+
+### Логирование
 
-console.log(chatResponse.answer);
+```javascript
+// Включение детального логирования
+localStorage.setItem('ai-solver-debug', 'true');
 ```
 
-## Документация
+## 📊 Производительность
+
+### Рекомендации
+
+1. **Используйте autoConnect: false** для контроля ресурсов
+2. **Подключайтесь только к нужным WebSocket** namespace
+3. **Отключайтесь после завершения** операций
+4. **Используйте диагностику** для мониторинга
+
+### Monitoring
+
+```javascript
+// Мониторинг ошибок
+window.addEventListener('unhandledrejection', (event) => {
+  console.error('Unhandled SDK error:', event.reason);
+});
+
+// Метрики производительности
+const start = performance.now();
+await sdk.projects.create(data);
+const duration = performance.now() - start;
+console.log(`Operation took ${duration}ms`);
+```
 
-Подробная документация доступна в следующих файлах:
+## 🔗 Полезные ссылки
 
-- [API Reference](./API_REFERENCE.md) - подробное описание всех методов SDK
-- [WebSocket](./WEBSOCKET.md) - примеры работы с WebSocket соединениями
-- [Примеры интеграции](./INTEGRATION_EXAMPLES.md) - примеры интеграции с VS Code/Cursor и другими приложениями
-- [Аутентификация](./AUTHENTICATION.md) - информация по процессу аутентификации
-- [Обработка ошибок](./ERROR_HANDLING.md) - руководство по обработке ошибок
+- **[GitHub Repository](https://github.com/ai-solver/sdk)**
+- **[NPM Package](https://www.npmjs.com/package/@ai-solver/sdk)**
+- **[Release Notes](../CHANGELOG.md)**
+- **[Issues & Support](https://github.com/ai-solver/sdk/issues)**
 
-## Поддерживаемые платформы
+## 📋 Совместимость
 
-- **Браузеры**: Chrome, Firefox, Safari, Edge
-- **Node.js**: 14.x и выше
+| Компонент | Версия |
+|-----------|--------|
+| **Node.js** | 16.x+ |
+| **TypeScript** | 4.5+ |
+| **Browser** | Chrome 90+, Firefox 88+, Safari 14+ |
+| **Backend** | AI Solver Backend v1.0.0 |
 
-## Лицензия
+---
 
-MIT 
+**AI Solver SDK v2.5.0 Documentation**  
+**Последнее обновление:** 28 июня 2025  
+**Статус:** Stable Release 

package/docs/README_V2.5.md

@@ -0,0 +1,266 @@
+# AI Solver SDK v2.5.0
+
+JavaScript/TypeScript SDK для взаимодействия с AI Solver Backend API - умной системой работы с кодом, reasoning и AI-ассистентами.
+
+## Установка
+
+```bash
+npm install @ai-solver/sdk
+```
+
+## Основные возможности
+
+- **🚀 Проекты**: создание, индексация и управление
+- **🧠 AI Reasoning**: умное рассуждение в контексте кода  
+- **💬 AI Chat**: взаимодействие с Claude 4 thinking + tools
+- **🔍 Поиск**: семантический поиск по коду
+- **⚡ WebSocket**: real-time события и streaming
+- **🌐 Мультиплатформенность**: Browser + Node.js
+
+## Быстрый старт v2.5.0
+
+```javascript
+import { CodeSolverSDK } from '@ai-solver/sdk';
+
+// Рекомендуемый способ инициализации
+const sdk = CodeSolverSDK.create({
+  baseURL: 'http://localhost:3000',
+  apiKey: 'dev_sk_test_12345678',
+  autoConnect: false // Контролируемые WebSocket подключения
+});
+
+// Проверка всех endpoints
+const results = await sdk.diagnoseAPI();
+console.log('API статус:', results);
+
+// Создание проекта
+const project = await sdk.projects.create({
+  name: 'My AI Project',
+  path: '/path/to/project',
+  description: 'Test project for AI Solver'
+});
+
+// Запуск индексации
+await sdk.projects.startIndexing(project.id);
+
+// WebSocket события (подключение по требованию)
+await sdk.projects.connectWebSocket();
+sdk.projects.onIndexingProgress((progress) => {
+  console.log(`Прогресс: ${progress.percentage}%`);
+});
+
+// AI Reasoning процесс
+const reasoning = await sdk.reasoning.create({
+  projectId: project.id,
+  query: 'Проанализируй архитектуру этого проекта'
+});
+
+await sdk.reasoning.start(reasoning.id);
+
+// Chat с Claude 4 thinking
+const response = await sdk.chat.stream([
+  {
+    role: 'user', 
+    content: 'Объясни как работает эта функция',
+    tools: createStandardDevelopmentTools()
+  }
+], {
+  projectId: project.id,
+  model: 'claude-3-5-sonnet-20241022',
+  thinking: true
+});
+```
+
+## Новые возможности v2.5.0
+
+### ✨ **Complex Content Support**
+```javascript
+// Поддержка сложного контента
+const message = {
+  role: 'user',
+  content: [
+    { type: 'text', text: 'Анализируй этот код:' },
+    { type: 'text', text: 'function example() { return 42; }' },
+    { type: 'tool_use', id: 'tool_1', name: 'code_analyzer' }
+  ]
+};
+```
+
+### 🔧 **Tool Choice Validation**
+```javascript
+// Только auto/none с thinking
+const response = await sdk.chat.stream(messages, {
+  thinking: true,
+  tool_choice: { type: 'auto' } // ✅ Работает
+  // tool_choice: { type: 'any' } // ❌ Ошибка с thinking
+});
+```
+
+### 🔐 **Signature Preservation**
+```javascript
+// Автоматическое сохранение криптографических подписей
+sdk.chat.onThinkingSignature((signature) => {
+  console.log('Подпись thinking блока:', signature);
+});
+```
+
+### 🌊 **Streaming Events**
+```javascript
+// Новые события streaming
+sdk.chat.onTextDelta((text) => console.log('Текст:', text));
+sdk.chat.onThinkingDelta((thinking) => console.log('Мышление:', thinking));
+sdk.chat.onSignatureDelta((sig) => console.log('Подпись:', sig));
+```
+
+## Контролируемые WebSocket
+
+```javascript
+// v2.5.0 - полный контроль подключений
+const sdk = CodeSolverSDK.create({
+  autoConnect: false // Важно!
+});
+
+// Подключение только когда нужно
+await sdk.projects.connectWebSocket();
+await sdk.reasoning.connectWebSocket();
+await sdk.chat.connectWebSocket();
+
+// Отключение когда не нужно
+await sdk.projects.disconnectWebSocket();
+```
+
+## API Алиасы для совместимости
+
+```javascript
+// Полные названия (рекомендуемые)
+await sdk.reasoning.createReasoning(data);
+await sdk.reasoning.startReasoning(id);
+await sdk.reasoning.stopReasoning(id);
+
+// Короткие алиасы
+await sdk.reasoning.create(data);
+await sdk.reasoning.start(id);  
+await sdk.reasoning.stop(id);
+```
+
+## Helper функции
+
+```javascript
+import { 
+  createStandardDevelopmentTools,
+  extractThinkingBlocks,
+  extractToolUseBlocks,
+  createToolResultMessage,
+  createComplexAssistantMessage
+} from '@ai-solver/sdk';
+
+// 8 стандартных инструментов как в Cursor
+const tools = createStandardDevelopmentTools();
+
+// Извлечение thinking блоков
+const thinkingBlocks = extractThinkingBlocks(response);
+
+// Создание сложных сообщений
+const complexMessage = createComplexAssistantMessage(
+  'Результат анализа:',
+  thinkingBlocks,
+  toolUseBlocks
+);
+```
+
+## Диагностика и debugging
+
+```javascript
+// Проверка всех endpoints
+const results = await sdk.diagnoseAPI();
+console.log('Доступные endpoints:', results);
+
+// Детальная диагностика
+const detailed = await sdk.diagnoseFull();
+console.log('Статус backend:', detailed);
+
+// Проверка WebSocket
+const wsStatus = await sdk.diagnoseWebSocket();
+console.log('WebSocket статус:', wsStatus);
+```
+
+## Обработка ошибок
+
+```javascript
+try {
+  const project = await sdk.projects.create(projectData);
+} catch (error) {
+  if (error.status === 404) {
+    console.error('Backend недоступен');
+  } else if (error.status === 400) {
+    console.error('Некорректные данные:', error.message);
+  } else {
+    console.error('Неожиданная ошибка:', error);
+  }
+}
+```
+
+## Environment Configuration
+
+```javascript
+// Production
+const sdk = CodeSolverSDK.create({
+  baseURL: 'https://api.ai-solver.com',
+  apiKey: process.env.AI_SOLVER_API_KEY,
+  autoConnect: false
+});
+
+// Development  
+const sdk = CodeSolverSDK.create({
+  baseURL: 'http://localhost:3000',
+  apiKey: 'dev_sk_test_12345678',
+  autoConnect: false
+});
+```
+
+## Миграция с v2.4.x
+
+### Изменения инициализации:
+```javascript
+// ❌ v2.4.x (deprecated):
+const sdk = new CodeSolverSDK(options);
+await sdk.initialize();
+
+// ✅ v2.5.0:
+const sdk = CodeSolverSDK.create(options);
+// initialize() больше не нужен
+```
+
+### Изменения методов:
+```javascript
+// ❌ v2.4.x:
+await sdk.projects.createProject(name, path, options);
+
+// ✅ v2.5.0:  
+await sdk.projects.create({ name, path, description });
+```
+
+### WebSocket изменения:
+```javascript
+// ❌ v2.4.x (автоподключение):
+const sdk = new CodeSolverSDK(options); // Автоматически подключался
+
+// ✅ v2.5.0 (контролируемое):
+const sdk = CodeSolverSDK.create({ autoConnect: false });
+await sdk.projects.connectWebSocket(); // Явное подключение
+```
+
+## Поддерживаемые платформы
+
+- **Node.js**: 16.x и выше
+- **Browsers**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
+- **TypeScript**: 4.5+ (опционально)
+
+## Лицензия
+
+MIT
+
+---
+
+**Обновлено для AI Solver SDK v2.5.0**  
+**Совместимо с AI Solver Backend v1.0.0**