solver-sdk 5.1.1 → 5.1.4

package/README.md

@@ -1,29 +1,8 @@
-# Code Solver SDK v5.1.0
+# Code Solver SDK
 
-> **🗑️ Ультра-чистый JavaScript/TypeScript SDK для VS Code Extensions**  
-> Без legacy кода, без мертвых методов, только актуальный API
+🚀 **Официальный JavaScript/TypeScript SDK для Code Solver API**
 
-JavaScript/TypeScript SDK для работы с Code Solver API. Предоставляет простой интерфейс для индексации кода, семантического поиска функций, работы с AI чатом и **новую Delta-Chunking архитектуру** для Cursor-подобной синхронизации проектов.
-
-## 🎯 Основные возможности
-
-- **🔄 Delta-Chunking** - Cursor-like инкрементальная синхронизация проектов
-- **💬 Chat API** - взаимодействие с AI моделями (Claude, GPT)
-- **🔍 Code Search** - семантический поиск по коду и функциям
-- **📊 Project Indexing** - индексация и анализ проектов с **богатой информацией**
-- **📝 Context API** - получение контекста для AI
-- **🛠️ Code Modification** - модификация кода через AI
-- **🔇 Настраиваемое логирование** - полный контроль над выводом в консоль
-- **✨ Улучшенная типизация** - полные TypeScript типы с примерами и документацией
-
-## 🚀 Что нового в v5.1.0
-
-> **🔄 Delta-Chunking API** - добавлена полная документация для новой архитектуры синхронизации
-
-- ✨ **Delta-Chunking интеграция** - встроено в основной CodeSolverSDK класс  
-- 📝 **Полная документация** - все методы, типы и примеры использования
-- 🔐 **Шифрование и chunking** - конфигурация encryption и chunking опций
-- 🎯 **Готово к продакшену** - интеграция с backend полностью реализована
+Современный SDK для интеграции с Code Solver - платформой для анализа кода, векторного поиска и AI-ассистента. Поддерживает WebSocket для real-time уведомлений и delta-chunking для эффективной синхронизации.
 
 ## 📦 Установка
 
@@ -31,453 +10,594 @@ JavaScript/TypeScript SDK для работы с Code Solver API. Предост
 npm install solver-sdk
 ```
 
-## ⚙️ Конфигурация
-
-```javascript
-const sdk = await CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000',     // Обязательный  
-  apiKey: 'your-api-key',               // Опционально
-  timeout: 30000,                       // Таймаут запросов (мс)
-  debug: 'error'                        // Уровень логирования
-});
-```
-
-### 📊 Уровни логирования
-- `'silent'` - полное отключение
-- `'error'` - только ошибки (рекомендуется)  
-- `'warn'` - предупреждения и ошибки
-- `'info'` - базовая информация
-- `'debug'` - подробная отладка
-
 ## 🚀 Быстрый старт
 
 ```javascript
 import { CodeSolverSDK } from 'solver-sdk';
 
-// Создание SDK
-const sdk = await CodeSolverSDK.create({
+const sdk = new CodeSolverSDK({
   baseURL: 'http://localhost:3000',
-  debug: 'error' // Рекомендуемый уровень для production
+  apiKey: 'your-api-key',
+  webSocket: { enabled: true } // Включить WebSocket для real-time уведомлений
 });
 
-// 1. Создание проекта (с автоматической дедупликацией)
-const project = await sdk.projects.createProject(
-  'My Project',
-  '/path/to/project'
-);
+// Подключение к WebSocket
+await sdk.connectWebSocket();
 
-// 2. Запуск индексации
-await sdk.projects.startIndexing(project.id);
+// Создание проекта
+const project = await sdk.projects.createProject('My Project', '/path/to/project');
+
+// Запуск индексации с real-time статусом
+const indexResult = await sdk.indexing.indexProject('/path', 'My Project');
 
-// 3. Проверка статуса
-const status = await sdk.projects.getIndexingStatus(project.id);
-console.log(`Статус: ${status.status}, прогресс: ${status.progress}%`);
+// Подписка на real-time уведомления
+sdk.projectSync.on('sync-status-update', (status) => {
+  console.log(`Индексация: ${status.progress}%`);
+});
 
-// 4. Поиск в коде
+// Поиск по коду
 const results = await sdk.search.searchCode(project.id, {
-  query: 'function calculateSum',
+  query: 'function authenticate',
   limit: 10
 });
+```
+
+## 📖 API Reference
+
+### 🏗️ Инициализация SDK
 
-// 5. Чат с AI
-const response = await sdk.chat.chat([
-  { role: 'user', content: 'Объясни найденный код' }
-], { projectId: project.id });
+#### `new CodeSolverSDK(options)`
 
-console.log(response.content);
+```typescript
+interface CodeSolverSDKOptions {
+  baseURL: string;           // URL API сервера
+  apiKey?: string;           // API ключ для авторизации
+  timeout?: number;          // Таймаут запросов (по умолчанию 45000ms)
+  headers?: Record<string, string>; // Дополнительные HTTP заголовки
+  
+  // WebSocket настройки
+  webSocket?: {
+    enabled?: boolean;       // Включить WebSocket (по умолчанию true)
+    connectionTimeout?: number; // Таймаут подключения (10000ms)
+    maxRetries?: number;     // Максимум попыток переподключения (3)
+    retryDelay?: number;     // Задержка между попытками (2000ms)
+    debug?: boolean;         // Отладочные логи (false)
+  };
+  
+  // Delta-Chunking настройки
+  deltaChunking?: {
+    enabled?: boolean;       // Включить delta-chunking (по умолчанию true)
+    chunkSize?: number;      // Размер чанка (4096 байт)
+    maxConcurrentChunks?: number; // Максимум параллельных чанков (5)
+  };
+}
 ```
 
-## 📋 API Методы
+### 📁 Projects API (`sdk.projects`)
 
-### 📁 Projects API
-```javascript
+#### Управление проектами
+
+```typescript
 // Создание проекта
-await sdk.projects.createProject('Project Name', '/project/path');
-await sdk.projects.createProject('Project Name', '/project/path', { description: 'Optional' });
+createProject(name: string, path: string, data?: any): Promise<Project>
+
+// Получение всех проектов
+getAllProjects(): Promise<Project[]>
+getProjects(): Promise<Project[]> // Псевдоним
 
-// Получение проектов
-await sdk.projects.getAllProjects();       // Все проекты
-await sdk.projects.getReadyProjects();     // Только готовые к работе
-await sdk.projects.getProject(projectId);  // Конкретный проект с полной информацией
+// Получение проекта по ID
+getProject(projectId: string): Promise<Project | null>
+
+// Поиск или создание проекта
+findOrCreateProject(projectPath: string, projectName: string, description?: string): Promise<Project>
+
+// Удаление проекта
+deleteProject(projectId: string): Promise<void>
+
+// Получение статуса индексации проекта
+getIndexingStatus(projectId: string): Promise<any>
 ```
 
-### ⚙️ Indexing API  
+#### Примеры использования
+
 ```javascript
-// Управление индексацией
-await sdk.projects.startIndexing(projectId);
-await sdk.projects.cancelIndexing(projectId);
+// Создание нового проекта
+const project = await sdk.projects.createProject(
+  'My Web App',
+  '/Users/dev/my-web-app',
+  { description: 'React приложение' }
+);
 
-// Статус индексации
-const status = await sdk.projects.getIndexingStatus(projectId);
-console.log(`${status.status}: ${status.progress}%`);
+// Получение всех проектов пользователя
+const projects = await sdk.projects.getAllProjects();
+console.log(`У вас ${projects.length} проектов`);
+
+// Поиск существующего или создание нового
+const project = await sdk.projects.findOrCreateProject(
+  '/path/to/project',
+  'My Project',
+  'Описание проекта'
+);
+```
+
+### 🚀 Indexing API (`sdk.indexing`)
+
+#### Управление индексацией
+
+```typescript
+// Создание проекта и запуск индексации
+indexProject(projectPath: string, projectName: string, description?: string): Promise<IndexProjectResult>
+
+// Получение статуса индексации (с кэшированием)
+getStatus(projectId: string): Promise<IndexingStatus>
+
+// Ожидание завершения индексации (DEPRECATED - используйте WebSocket)
+waitForCompletion(projectId: string, timeout?: number): Promise<IndexingStatus>
+
+// Отмена индексации
+cancelIndexing(projectId: string): Promise<void>
+
+// Перезапуск индексации
+restartIndexing(projectId: string): Promise<IndexingStatus>
+```
+
+#### Типы данных
+
+```typescript
+interface IndexingStatus {
+  status: string;           // 'pending' | 'processing' | 'completed' | 'failed'
+  progress: number;         // Прогресс 0-100
+  totalFiles?: number;      // Общее количество файлов
+  processedFiles?: number;  // Обработано файлов
+  currentFile?: string;     // Текущий обрабатываемый файл
+  error?: string;          // Сообщение об ошибке
+  updatedAt?: string;      // Время последнего обновления
+}
 ```
 
-### 🔍 Search API
+#### Примеры использования
+
 ```javascript
-// Поиск в коде
-const results = await sdk.search.searchCode(projectId, {
-  query: 'function name',
-  limit: 20
+// Запуск индексации
+const result = await sdk.indexing.indexProject(
+  '/Users/dev/my-project',
+  'My Project'
+);
+console.log('Project ID:', result.projectId);
+
+// Получение статуса (единичный запрос)
+const status = await sdk.indexing.getStatus(result.projectId);
+console.log(`Прогресс: ${status.progress}%`);
+
+// ⚠️ ВАЖНО: Для real-time статуса используйте WebSocket!
+sdk.projectSync.on('sync-status-update', (status) => {
+  console.log(`Статус обновлен: ${status.status}, прогресс: ${status.progress}%`);
 });
+```
+
+### 🔍 Search API (`sdk.search`)
+
+#### Поиск по коду
+
+```typescript
+// Основной поиск по коду
+searchCode(projectId: string, params: SearchCodeParams): Promise<SearchResult[]>
+searchCode(params: SearchCodeParams): Promise<SearchResult[]> // Альтернативная сигнатура
+
+// Семантический поиск
+semanticSearch(projectId: string, params: Omit<SearchCodeParams, 'projectId'>): Promise<SearchResult[]>
 
 // Поиск функций
-const functions = await sdk.search.searchFunctions(projectId, {
-  query: 'calculateSum', 
-  limit: 10
-});
+searchFunctions(projectId: string, params: SearchFunctionsParams): Promise<FunctionSearchResult>
+```
 
-// Статистика
-const stats = await sdk.search.getFunctionStats(projectId);
+#### Параметры поиска
+
+```typescript
+interface SearchCodeParams {
+  projectId?: string;       // ID проекта (если не передан отдельно)
+  query: string;           // Поисковый запрос
+  limit?: number;          // Максимум результатов (по умолчанию 10)
+  maxResults?: number;     // Альтернативное название для limit
+  semantic?: boolean;      // Флаг семантического поиска
+}
+
+interface SearchResult {
+  id: string;              // Уникальный ID результата
+  score: number;           // Оценка релевантности (0-1)
+  filePath: string;        // Путь к файлу
+  fileName: string;        // Имя файла
+  language: string;        // Язык программирования
+  snippet: string;         // Фрагмент кода
+  line: number;           // Номер строки
+  size: number;           // Размер фрагмента
+  indexedAt?: string;     // Время индексации
+}
 ```
 
-### 💬 Chat API
+#### Примеры использования
+
 ```javascript
-// Обычный чат
-const response = await sdk.chat.chat([
-  { role: 'user', content: 'Explain this code' }
-], { projectId });
-
-// Потоковый чат  
-for await (const chunk of sdk.chat.streamChat(messages, { projectId })) {
-  console.log(chunk.text);
-}
+// Обычный поиск
+const results = await sdk.search.searchCode('project-id', {
+  query: 'function authenticate',
+  limit: 20
+});
 
-// С thinking (мышление Claude)
-const response = await sdk.chat.chat(messages, { 
-  projectId,
-  thinking: { type: 'enabled', budget_tokens: 5000 }
+results.forEach(result => {
+  console.log(`${result.fileName}:${result.line} - ${result.snippet}`);
+});
+
+// Семантический поиск
+const semanticResults = await sdk.search.semanticSearch('project-id', {
+  query: 'user authentication logic'
+});
+
+// Альтернативная сигнатура
+const results = await sdk.search.searchCode({
+  projectId: 'project-id',
+  query: 'error handling',
+  limit: 5
 });
 ```
 
-## 🔄 Delta-Chunking API
+### 🔌 WebSocket API (`sdk.projectSync`)
 
-> **🚀 Новый Cursor-подобный подход к синхронизации проектов**  
-> Инкрементальные обновления, шифрование, real-time статус
+#### Real-time уведомления
 
-### Создание SDK с Delta-Chunking
+```typescript
+// Подключение к WebSocket
+connectWebSocket(): Promise<void>
 
-```javascript
-import { CodeSolverSDK } from 'solver-sdk';
+// Отключение от WebSocket
+disconnectWebSocket(): void
 
-// Создание SDK с включенным delta-chunking
-const sdk = await CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000',
-  apiKey: 'your-api-key',
-  deltaChunking: {                          // ✨ Опциональная секция
-    enabled: true,                          // Включить delta-chunking
-    encryption: {
-      enabled: true,
-      key: 'your-32-char-encryption-key-here!'  // 32 символа
-    },
-    chunking: {
-      maxTokens: 400,                       // Максимальный размер чанка
-      minTokens: 100,                       // Минимальный размер чанка  
-      useTreeSitter: false,                 // Пока простая разбивка
-      preserveContext: true                 // Сохранять контекст между чанками
-    },
-    fileWatching: {
-      enabled: false,                       // Автоматическое наблюдение (в разработке)
-      pollInterval: 1000,                   // Интервал проверки изменений
-      ignorePatterns: ['node_modules/**']   // Игнорируемые файлы
-    }
-  },
-  debug: 'error'
-});
+// Проверка статуса подключения
+isWebSocketConnected: boolean
+
+// Подписка на проект
+projectSync.subscribeToProject(projectId: string): void
+
+// Отписка от проекта
+projectSync.unsubscribeFromProject(projectId: string): void
 
-// Проверяем что delta-chunking включен
-console.log('Delta-chunking доступен:', sdk.isDeltaChunkingEnabled);
+// Обработчики событий
+projectSync.on(eventName: string, handler: Function): void
+projectSync.off(eventName: string, handler: Function): void
 ```
 
-### Синхронизация проекта
+#### События WebSocket
+
+```typescript
+// Обновление статуса синхронизации
+'sync-status-update': (data: SyncStatusUpdate) => void
+
+// Прогресс синхронизации
+'sync-progress': (data: SyncProgressEvent) => void  
+
+// Завершение синхронизации
+'sync-completed': (data: SyncCompletedEvent) => void
+
+// Ошибки
+'error': (data: ErrorEvent) => void
+
+// Подключение/отключение
+'connected': (data: { socketId: string }) => void
+'disconnected': (data: { reason: string }) => void
+```
+
+#### Примеры использования
 
 ```javascript
-// Основной метод синхронизации (только если deltaChunking.enabled = true)
-const result = await sdk.syncProject('project-id', '/path/to/project', {
-  forceFull: false,           // Инкрементальная синхронизация 
-  batchSize: 50,             // Чанков за раз
-  ignorePatterns: [          // Игнорировать файлы/папки
-    'node_modules/**', 
-    '*.log',
-    '.git/**'
-  ],
-  includeExtensions: ['.ts', '.js', '.py'],  // Только эти расширения
-  maxFileSizeKB: 1024,       // Максимальный размер файла 1MB
-  onProgress: (current, total) => {          // Callback прогресса
-    console.log(`Прогресс: ${current}/${total} (${Math.round(current/total*100)}%)`);
+// Подключение и подписка на проект
+await sdk.connectWebSocket();
+sdk.projectSync.subscribeToProject('project-id');
+
+// Обработка событий
+sdk.projectSync.on('sync-status-update', (status) => {
+  console.log(`Проект ${status.projectId}: ${status.status} (${status.progress}%)`);
+});
+
+sdk.projectSync.on('sync-completed', (data) => {
+  if (data.success) {
+    console.log(`Синхронизация завершена за ${data.duration}мс`);
+  } else {
+    console.error(`Ошибка синхронизации: ${data.error}`);
   }
 });
 
-console.log(`✅ Синхронизация завершена: ${result.processedChunks} чанков`);
+sdk.projectSync.on('error', (error) => {
+  console.error(`WebSocket ошибка: ${error.error}`);
+});
+
+// Отключение
+sdk.disconnectWebSocket();
+```
+
+### 🔄 Delta-Chunking API (`sdk.deltaSync`)
+
+#### Синхронизация с delta-chunking
+
+```typescript
+// Инициализация синхронизации
+initializeSync(projectId: string, options?: SyncOptions): Promise<SyncResult>
+
+// Отправка delta чанков
+sendDeltaChunks(projectId: string, chunks: EncryptedChunk[]): Promise<void>
+
+// Финализация синхронизации
+finalizeDeltaSync(projectId: string): Promise<SyncResult>
+
+// Отмена синхронизации
+cancelDeltaSync(projectId: string): Promise<void>
+
+// Получение статуса синхронизации
+getSyncStatus(projectId: string): Promise<SyncStatus>
 ```
 
-### Синхронизация файлов (для браузера)
+#### Типы данных
+
+```typescript
+interface SyncOptions {
+  incremental?: boolean;    // Инкрементальная синхронизация
+  compression?: boolean;    // Сжатие чанков
+  encryption?: boolean;     // Шифрование чанков
+}
+
+interface EncryptedChunk {
+  id: string;              // ID чанка
+  data: string;            // Зашифрованные данные (base64)
+  hash: string;            // SHA-256 хэш
+  size: number;            // Размер оригинальных данных
+  metadata?: any;          // Дополнительные метаданные
+}
+
+interface SyncResult {
+  sessionId: string;       // ID сессии синхронизации
+  status: string;          // Статус операции
+  message?: string;        // Сообщение о результате
+  chunksProcessed?: number; // Количество обработанных чанков
+}
+```
+
+#### Примеры использования
 
 ```javascript
-// Для web/браузерных приложений без доступа к файловой системе
-const files = [
-  {
-    path: 'src/index.ts',
-    content: 'console.log("Hello World");',
-    size: 28
-  },
+// Полный цикл delta-chunking синхронизации
+const syncResult = await sdk.deltaSync.initializeSync('project-id', {
+  incremental: true,
+  compression: true
+});
+
+console.log('Сессия синхронизации:', syncResult.sessionId);
+
+// Подготовка и отправка чанков
+const chunks = [
   {
-    path: 'src/utils.ts', 
-    content: 'export const sum = (a, b) => a + b;',
-    size: 37
+    id: 'chunk-1',
+    data: btoa('console.log("Hello World");'), // base64
+    hash: 'sha256-hash',
+    size: 26
   }
 ];
 
-const result = await sdk.syncFiles('project-id', files, {
-  batchSize: 20,
-  onProgress: (current, total) => {
-    console.log(`📤 Загружено: ${current}/${total}`);
-  }
+await sdk.deltaSync.sendDeltaChunks('project-id', chunks);
+
+// Финализация
+const finalResult = await sdk.deltaSync.finalizeDeltaSync('project-id');
+console.log('Синхронизация завершена:', finalResult.status);
+
+// Мониторинг через WebSocket
+sdk.projectSync.on('sync-progress', (progress) => {
+  console.log(`Обработано ${progress.currentChunk}/${progress.totalChunks} чанков`);
 });
 ```
 
-### Автоматическое наблюдение за изменениями
+### 💬 Chat API (`sdk.chat`)
 
-```javascript
-// Запуск file watcher (в разработке)
-const watcher = await sdk.startAutoSync('project-id', '/path/to/watch');
+#### AI-ассистент
 
-// Проверка активности
-console.log(`👀 Auto-sync активен: ${watcher.isActive}`);
+```typescript
+// Отправка сообщения
+sendMessage(messages: Message[], options?: ChatOptions): Promise<ChatResponse>
+
+// Потоковый чат
+streamChat(messages: Message[], options?: StreamChatOptions): AsyncGenerator<ChatChunk>
 
-// Остановка наблюдения
-await watcher.stop();
-console.log('🔴 File watcher остановлен');
+// Чат с контекстом проекта
+chatWithContext(projectId: string, message: string, options?: ChatOptions): Promise<ChatResponse>
 ```
 
-### Статус и управление
+#### Примеры использования
 
 ```javascript
-// Проверка статуса синхронизации
-const status = await sdk.getSyncStatus('project-id');
-console.log(`📊 Статус: ${status.status}, прогресс: ${status.progress || 0}%`);
-
-// Отмена активной синхронизации
-const cancelled = await sdk.cancelSync('project-id');
-if (cancelled) {
-  console.log('❌ Синхронизация отменена');
+// Простой чат
+const response = await sdk.chat.sendMessage([
+  { role: 'user', content: 'Объясни что такое async/await' }
+]);
+
+console.log(response.choices[0].message.content);
+
+// Потоковый чат
+const stream = sdk.chat.streamChat([
+  { role: 'user', content: 'Напиши функцию сортировки' }
+]);
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
 }
+
+// Чат с контекстом проекта
+const contextResponse = await sdk.chat.chatWithContext(
+  'project-id',
+  'Найди баги в моем коде'
+);
 ```
 
-### Полный пример workflow
+## 🛡️ Безопасность и Лимиты
+
+SDK автоматически обрабатывает rate limiting и кэширование:
+
+### Rate Limits
+- **Indexing Status**: 5 запросов/минуту (используйте WebSocket для real-time)
+- **Projects**: 30 запросов/минуту  
+- **Global**: 10/сек, 100/мин, 1000/час
 
+### Кэширование
+- **Indexing Status**: 10 секунд TTL
+- **Projects**: 30 секунд TTL
+
+### Рекомендации
 ```javascript
-import { CodeSolverSDK } from 'solver-sdk';
+// ✅ Правильно: WebSocket для real-time статуса
+sdk.projectSync.on('sync-status-update', callback);
 
-async function syncProject() {
-  // 1. Создание SDK
-  const sdk = await CodeSolverSDK.create({
-    baseURL: 'http://localhost:3000',
-    deltaChunking: {
-      enabled: true,
-      encryption: { enabled: true, key: 'my-secret-key-32-characters-long!' }
-    },
-    debug: 'info'
-  });
-
-  try {
-    // 2. Синхронизация с прогрессом
-    const result = await sdk.syncProject('my-project-id', './my-project', {
-      onProgress: (current, total) => {
-        const percent = Math.round((current / total) * 100);
-        console.log(`🔄 Синхронизация: ${percent}% (${current}/${total} чанков)`);
-      },
-      ignorePatterns: ['node_modules/**', 'dist/**', '*.log']
-    });
-
-    // 3. Результат
-    console.log('🎉 Синхронизация завершена:', {
-      success: result.success,
-      processedChunks: result.processedChunks,
-      duration: result.duration + 'ms',
-      newFiles: result.details?.newFiles,
-      changedFiles: result.details?.changedFiles
-    });
-
-    // 4. Проверка финального статуса
-    const status = await sdk.getSyncStatus('my-project-id');
-    console.log(`✅ Финальный статус: ${status.status}`);
-
-  } catch (error) {
-    console.error('❌ Ошибка синхронизации:', error.message);
-    
-    // Отменяем если что-то пошло не так
-    await sdk.cancelSync('my-project-id');
+// ❌ Неправильно: Polling статуса
+// setInterval(() => sdk.indexing.getStatus(id), 2000);
+```
+
+## 🔧 Обработка ошибок
+
+```javascript
+try {
+  const project = await sdk.projects.createProject('Test', '/path');
+} catch (error) {
+  if (error.status === 401) {
+    console.error('Неверный API ключ');
+  } else if (error.status === 429) {
+    console.error('Превышен rate limit');
+  } else {
+    console.error('Ошибка API:', error.message);
   }
 }
 
-// Запуск
-syncProject();
+// WebSocket ошибки
+sdk.projectSync.on('error', (error) => {
+  if (error.recoverable) {
+    console.warn('Временная ошибка WebSocket:', error.error);
+  } else {
+    console.error('Критическая ошибка WebSocket:', error.error);
+  }
+});
 ```
 
-## 💡 Типы данных
+## 🚀 Продвинутое использование
 
-### Project
-```typescript
-interface Project {
-  id: string;
-  name: string; 
-  path: string;
-  ready: boolean;              // Готов к работе
-  fileCount: number;           // Количество файлов
-  indexStatus: 'pending' | 'indexing' | 'indexed' | 'failed' | 'cancelled';
-  indexingProgress?: number;   // 0-100%
-  languageStats?: {[lang: string]: number};  // Статистика языков
-  indexingErrors?: any[];      // Ошибки индексации
-  // ... и еще 10+ полей
-}
+### Настройка HTTP клиента
+
+```javascript
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.codesolver.dev',
+  apiKey: process.env.CODESOLVER_API_KEY,
+  timeout: 60000,
+  headers: {
+    'User-Agent': 'MyApp/1.0.0',
+    'X-Custom-Header': 'value'
+  }
+});
 ```
 
-### Delta-Chunking Types
+### WebSocket с переподключением
 
-```typescript
-// Расширенная конфигурация CodeSolverSDK с delta-chunking
-interface CodeSolverSDKOptions {
-  baseURL: string;
-  apiKey?: string;
-  deltaChunking?: {                        // ✨ Опциональная секция
-    enabled: boolean;                      // Включение delta-chunking функциональности
-    
-    encryption?: {
-      enabled: boolean;                    // Включить шифрование чанков
-      key: string;                         // 32-символьный ключ для AES-256
-    };
-    
-    chunking?: {
-      maxTokens?: number;                  // Максимальный размер чанка (по умолчанию: 400)
-      minTokens?: number;                  // Минимальный размер чанка (по умолчанию: 100)
-      useTreeSitter?: boolean;             // Использовать tree-sitter парсер (в разработке)
-      preserveContext?: boolean;           // Сохранять контекст между чанками
-    };
-    
-    fileWatching?: {
-      enabled: boolean;                    // Включить автоматическое наблюдение за изменениями
-      pollInterval?: number;               // Интервал проверки изменений в мс (по умолчанию: 1000)
-      ignorePatterns?: string[];           // Паттерны для игнорирования файлов
-    };
-  };
-  timeout?: number;                        // Таймаут запросов (мс)
-  debug?: 'silent' | 'error' | 'warn' | 'info' | 'debug';
-}
+```javascript
+const sdk = new CodeSolverSDK({
+  baseURL: 'wss://api.codesolver.dev',
+  webSocket: {
+    enabled: true,
+    maxRetries: 5,
+    retryDelay: 3000,
+    debug: true
+  }
+});
 
-// Опции синхронизации
-interface SyncOptions {
-  forceFull?: boolean;         // Принудительная полная синхронизация
-  batchSize?: number;          // Размер батча для загрузки чанков (по умолчанию: 50)
-  ignorePatterns?: string[];   // Паттерны для игнорирования файлов
-  includeExtensions?: string[]; // Включать только определенные расширения
-  maxFileSizeKB?: number;      // Максимальный размер файла для обработки (KB)
-  onProgress?: (current: number, total: number) => void; // Callback прогресса
-  timeoutMs?: number;          // Таймаут для операций
-}
+sdk.projectSync.on('connected', () => {
+  console.log('WebSocket подключен');
+});
 
-// Результат синхронизации
-interface SyncResult {
-  success: boolean;
-  projectId: string;
-  sessionId?: string;
-  processedChunks: number;
-  totalChunks: number;
-  duration: number;            // Время выполнения в мс
-  error?: string;
-  details?: {
-    newFiles: number;
-    changedFiles: number;
-    deletedFiles: number;
-    failedChunks: number;
-  };
-}
+sdk.projectSync.on('disconnected', (data) => {
+  console.log('WebSocket отключен:', data.reason);
+});
+```
 
-// Статус синхронизации
-interface SyncStatus {
-  status: 'inactive' | 'initializing' | 'active' | 'finalizing' | 'completed' | 'failed';
-  progress?: number;           // 0-100%
-  chunksReceived?: number;
-  chunksProcessed?: number;
-  sessionId?: string;
-  errors?: string[];
-  startTime?: Date;
-  estimatedCompletion?: Date;
-}
+### Delta-Chunking с шифрованием
 
-// File watcher для автоматической синхронизации
-interface FileWatcher {
-  projectId: string;
-  watchPath: string;
-  isActive: boolean;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-}
+```javascript
+const syncResult = await sdk.deltaSync.initializeSync('project-id', {
+  incremental: true,
+  compression: true,
+  encryption: true
+});
 
-// Контент файла
-interface FileContent {
-  path: string;                // Относительный путь файла
-  content: string;             // Содержимое файла
-  size: number;                // Размер в байтах
-}
+// Шифрование чанков на клиенте
+const encryptedChunks = chunks.map(chunk => ({
+  ...chunk,
+  data: encrypt(chunk.data), // Ваша функция шифрования
+  hash: sha256(chunk.data)
+}));
+
+await sdk.deltaSync.sendDeltaChunks('project-id', encryptedChunks);
 ```
 
-## 📚 Пример использования
+## 📊 Мониторинг и диагностика
 
 ```javascript
-import { CodeSolverSDK } from 'solver-sdk';
+// Диагностика API
+const diagnosis = await sdk.diagnoseAPI();
+console.log('Статус API:', diagnosis);
 
-const sdk = await CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000'
-});
+// Health check
+const health = await sdk.httpClient.get('/health');
+console.log('Здоровье сервера:', health);
 
-// Работа с проектом
-const project = await sdk.projects.createProject('My App', '/path/to/app');
-await sdk.projects.startIndexing(project.id);
-
-// Ожидание индексации
-let status;
-do {
-  status = await sdk.projects.getIndexingStatus(project.id);
-  console.log(`${status.status}: ${status.progress}%`);
-  await new Promise(r => setTimeout(r, 2000));
-} while (status.status === 'indexing');
-
-// Поиск и чат
-const results = await sdk.search.searchCode(project.id, { 
-  query: 'function main', 
-  limit: 5 
-});
-
-const response = await sdk.chat.chat([
-  { role: 'user', content: 'Explain this code' }
-], { projectId: project.id });
+// Детальная информация о системе
+const info = await sdk.httpClient.get('/health/info');
+console.log('Информация о системе:', info);
 ```
 
-## 🔧 Устранение неполадок
+## 🔄 Миграция с предыдущих версий
+
+### С версии 4.x на 5.x
 
 ```javascript
-// Проверка подключения
-const response = await fetch('http://localhost:3000/health');
-console.log('Backend доступен:', response.ok);
+// Старый способ (4.x)
+const status = await sdk.projects.getIndexingStatus(projectId);
 
-// Увеличение таймаута для больших проектов  
-const sdk = await CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000',
-  timeout: 120000  // 2 минуты
-});
+// Новый способ (5.x)
+const status = await sdk.indexing.getStatus(projectId);
 
-// Отладка с подробными логами
-const sdk = await CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000', 
-  debug: 'debug'
+// Или лучше - WebSocket
+sdk.projectSync.on('sync-status-update', (status) => {
+  // Real-time статус
 });
 ```
 
+## 📝 Changelog
+
+### v5.1.3 (Latest)
+- ✅ Добавлен `IndexingApi` для управления индексацией
+- ✅ Добавлен `ProjectSyncClient` для WebSocket уведомлений  
+- ✅ Исправлена генерация URL в `SearchApi`
+- ✅ Добавлен метод `semanticSearch`
+- ✅ Добавлен метод `findOrCreateProject`
+- ✅ Улучшена обработка ошибок WebSocket
+- ✅ Обновлена документация и примеры
+
+### v5.0.0
+- 🚀 Полная переработка архитектуры
+- 🔌 WebSocket поддержка для real-time уведомлений
+- 🔄 Delta-chunking для эффективной синхронизации
+- 🛡️ Встроенное rate limiting и кэширование
+
+## 📞 Поддержка
+
+- **GitHub**: [Issues](https://github.com/codesolver/solver-sdk/issues)
+- **Email**: support@codesolver.dev
+- **Документация**: [docs.codesolver.dev](https://docs.codesolver.dev)
+
 ## 📄 Лицензия
 
-MIT License
+MIT License - см. [LICENSE](LICENSE) файл.
 
 ---
 
-> **Документация актуальна для v5.0.0**  
-> История изменений: [CHANGELOG.md](CHANGELOG.md)
+**🚀 Code Solver SDK v5.1.3** - Создано с ❤️ для разработчиков