solver-sdk 1.7.5 → 1.7.6

package/docs/indexing/INDEXING.md

@@ -5,20 +5,87 @@
 ## Содержание
 
 - [Введение](#введение)
+- [Быстрый старт](#быстрый-старт)
 - [API для индексации](#api-для-индексации)
-- [Инкрементальная индексация](#инкрементальная-индексация)
+  - [Работа с проектами по ID](#работа-с-проектами-по-id)
+  - [Работа с проектами по пути](#работа-с-проектами-по-пути)
+  - [Инкрементальная индексация](#инкрементальная-индексация)
 - [Отслеживание процесса индексации](#отслеживание-процесса-индексации)
-- [События WebSocket](#события-websocket)
+  - [Подключение к WebSocket](#подключение-к-websocket)
+  - [События WebSocket](#события-websocket)
+- [Сценарии использования](#сценарии-использования)
+  - [Индексация существующего проекта](#индексация-существующего-проекта)
+  - [Создание и индексация проекта по пути](#создание-и-индексация-проекта-по-пути)
+  - [Интеграция с IDE](#интеграция-с-ide)
+  - [Наблюдение за файловой системой](#наблюдение-за-файловой-системой)
 - [Обработка ошибок](#обработка-ошибок)
-- [Примеры использования](#примеры-использования)
 
 ## Введение
 
-Индексация проекта - это процесс сканирования и анализа файлов проекта для дальнейшего поиска и обработки информации. Solver SDK предоставляет набор методов для управления индексацией проектов и отслеживания этого процесса.
+Индексация проекта - это процесс сканирования и анализа файлов проекта для дальнейшего поиска и обработки информации. Solver SDK предоставляет набор методов для создания проектов, управления индексацией и отслеживания этого процесса в реальном времени через WebSocket соединения.
+
+## Быстрый старт
+
+Вот простой пример, как создать и проиндексировать проект, используя SDK:
+
+```javascript
+import { CodeSolverSDK } from 'solver-sdk';
+import path from 'path';
+
+// 1. Инициализация SDK
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key'
+});
+
+// 2. Создание и индексация проекта
+async function indexMyProject() {
+  try {
+    // Путь к проекту
+    const projectPath = '/path/to/your/project';
+    
+    // Создание и индексация в одной операции
+    const result = await sdk.projects.createAndIndexProject(
+      projectPath,
+      {
+        name: path.basename(projectPath),
+        excludePatterns: ['node_modules', '.git', 'dist']
+      }
+    );
+    
+    console.log(`Проект создан и индексация начата. ID проекта: ${result.projectId}`);
+    
+    // 3. Мониторинг прогресса индексации (опционально)
+    await sdk.projects.connectWebSocket();
+    
+    sdk.projects.on('indexing_progress', (data) => {
+      console.log(`Прогресс индексации: ${data.progress}%`);
+    });
+    
+    sdk.projects.on('indexing_complete', () => {
+      console.log('Индексация успешно завершена!');
+      sdk.projects.disconnectWebSocket();
+    });
+    
+    return result.projectId;
+  } catch (error) {
+    console.error(`Ошибка: ${error.message}`);
+    sdk.projects.disconnectWebSocket();
+    throw error;
+  }
+}
+
+// Запуск индексации
+indexMyProject().then(projectId => {
+  console.log(`Готово! Используйте ID проекта ${projectId} для поиска`);
+});
+```
 
 ## API для индексации
 
-### Основные методы
+SDK предоставляет два способа работы с проектами: по ID проекта и по пути к проекту на диске.
+
+### Работа с проектами по ID
 
 | Метод | Описание |
 |-------|----------|
@@ -27,10 +94,10 @@
 | `sdk.projects.getIndexingStatus(projectId)` | Получает текущий статус индексации |
 | `sdk.projects.updateFileIndex(projectId, filePath, options)` | Обновляет индекс конкретного файла |
 
-### Пример использования API
+#### Запуск и остановка индексации
 
 ```javascript
-// Запуск индексации
+// Запуск индексации по ID проекта
 const result = await sdk.projects.indexProject(projectId, {
   forceFull: false, // true для принудительной полной переиндексации
   includePatterns: ['**/*.js', '**/*.ts'], // glob паттерны для включения файлов
@@ -47,11 +114,44 @@ await sdk.projects.stopIndexing(projectId);
 console.log('Индексация остановлена');
 ```
 
-## Инкрементальная индексация
+### Работа с проектами по пути
+
+| Метод | Описание |
+|-------|----------|
+| `sdk.projects.getOrCreateProject(path, name?)` | Получает существующий или создает новый проект по пути |
+| `sdk.projects.indexProjectByPath(path, options)` | Запускает индексацию проекта по указанному пути |
+| `sdk.projects.createAndIndexProject(path, options)` | Создает проект и сразу запускает его индексацию |
+| `sdk.projects.ensureProjectExists(projectId, options)` | Проверяет существование проекта и при необходимости создает резервную копию |
+
+#### Создание и индексация
+
+```javascript
+// Получить проект по пути (создать, если не существует)
+const project = await sdk.projects.getOrCreateProject(
+  '/path/to/project',
+  'Название проекта' // опционально
+);
+console.log(`Проект ID: ${project.id}`);
+
+// Индексация проекта по пути
+const indexResult = await sdk.projects.indexProjectByPath('/path/to/project', {
+  forceFull: true,  // принудительная полная индексация
+  excludePatterns: ['node_modules', '.git']
+});
+console.log(`Индексация запущена для проекта ${indexResult.projectId}`);
+
+// Создание и индексация в одной операции
+const result = await sdk.projects.createAndIndexProject('/path/to/project', {
+  name: 'Мой проект',
+  forceFull: false, 
+  excludePatterns: ['node_modules', '.git']
+});
+console.log(`Проект ${result.projectId} создан и индексируется`);
+```
 
-В SDK версии 1.7.2 добавлена поддержка инкрементальной индексации отдельных файлов, что позволяет обновлять только изменившиеся файлы без необходимости переиндексации всего проекта.
+### Инкрементальная индексация
 
-### Обновление индекса отдельного файла
+SDK поддерживает инкрементальную индексацию, позволяющую обновлять только изменившиеся файлы.
 
 ```javascript
 // Обновление индекса файла с передачей содержимого
@@ -64,29 +164,15 @@ const result = await sdk.projects.updateFileIndex(
   }
 );
 
-console.log(`Файл ${result.filePath} успешно проиндексирован`);
+console.log(`Файл ${result.filePath} проиндексирован`);
 console.log(`Метаданные файла:`, result.fileIndex);
 
-// Альтернативный вариант через ContextApi
-await sdk.context.updateFileIndex(
-  projectId,
-  'src/components/App.js',
-  'console.log("Hello World");',
-  false // force flag
-);
-```
-
-### Инкрементальная индексация из файловой системы
-
-```javascript
 // Обновление индекса без передачи содержимого
 // SDK прочитает файл с диска
-const result = await sdk.projects.updateFileIndex(projectId, 'src/components/App.js');
-
-console.log(`Файл ${result.filePath} успешно проиндексирован`);
+const result2 = await sdk.projects.updateFileIndex(projectId, 'src/utils/helper.js');
 ```
 
-### Пакетное обновление нескольких файлов
+#### Пакетное обновление
 
 ```javascript
 // Обновление нескольких файлов
@@ -106,25 +192,21 @@ console.log(`Обновлено ${results.length} файлов`);
 
 ## Отслеживание процесса индексации
 
-Для отслеживания процесса индексации в реальном времени используется WebSocket соединение. SDK предоставляет методы для подключения к серверу и получения событий о ходе индексации.
+SDK предоставляет мощный механизм отслеживания процесса индексации в реальном времени через WebSocket соединения.
 
-### Подключение к WebSocket (версия 1.7.2)
+### Подключение к WebSocket
 
 ```javascript
-// Прямое подключение к пространству имен индексации
+// Подключение к WebSocket для событий индексации
 await sdk.projects.connectWebSocket();
 
-// Проверка подключения
+// Проверка успешного подключения
 if (sdk.projects.isWebSocketConnected()) {
-  console.log('Успешно подключено к WebSocket серверу');
+  console.log('Успешно подключено к WebSocket');
 } else {
-  console.error('Не удалось подключиться к WebSocket серверу');
+  console.error('Не удалось подключиться к WebSocket');
 }
-```
 
-### Установка обработчиков событий
-
-```javascript
 // Установка обработчиков событий
 sdk.projects.on('indexing_start', (data) => {
   console.log(`Индексация началась для проекта: ${data.projectId}`);
@@ -136,266 +218,408 @@ sdk.projects.on('indexing_progress', (data) => {
 
 sdk.projects.on('indexing_complete', (data) => {
   console.log(`Индексация завершена! Проиндексировано ${data.indexedFiles} файлов`);
+  sdk.projects.disconnectWebSocket(); // Отключение от WebSocket
 });
 
 sdk.projects.on('indexing_error', (data) => {
   console.error(`Ошибка индексации: ${data.message}`);
-});
-
-sdk.projects.on('file_indexed', (data) => {
-  console.log(`Файл проиндексирован: ${data.filePath}`);
-});
-
-sdk.projects.on('error', (error) => {
-  console.error(`Ошибка WebSocket: ${error.message}`);
+  sdk.projects.disconnectWebSocket();
 });
 ```
 
-### Отключение от WebSocket
-
-```javascript
-// Отключение от пространства имен индексации
-await sdk.projects.disconnectWebSocket();
-
-// Или через WebSocketClient
-const wsClient = sdk.getWebSocketClient();
-await wsClient.disconnect(WebSocketNamespace.INDEXING);
-
-// Отключение от всех пространств имен
-await wsClient.disconnectAll();
-```
-
-## События WebSocket
-
-При индексации проектов сервер отправляет следующие типы событий:
+### События WebSocket
 
 | Событие | Описание | Данные |
 |---------|----------|--------|
 | `indexing_start` | Начало процесса индексации | `{ projectId: string }` |
-| `indexing_progress` | Обновление прогресса индексации | `{ projectId: string, totalFiles: number, indexedFiles: number, progress: number, startTime: string, elapsedTime: number, estimatedTimeRemaining?: number }` |
+| `indexing_progress` | Обновление прогресса | `{ projectId: string, totalFiles: number, indexedFiles: number, progress: number, startTime: string, elapsedTime: number, estimatedTimeRemaining?: number }` |
 | `indexing_complete` | Завершение индексации | `{ projectId: string, totalFiles: number, indexedFiles: number, skippedFiles: number, startTime: string, endTime: string, totalTime: number }` |
-| `indexing_error` | Ошибка при индексации | `{ projectId: string, message: string, code?: string, details?: any }` |
-| `file_indexed` | Отдельный файл проиндексирован | `{ projectId: string, filePath: string, fileIndex: object }` |
-| `file_index_error` | Ошибка при индексации файла | `{ projectId: string, filePath: string, message: string }` |
+| `indexing_error` | Ошибка индексации | `{ projectId: string, message: string, code?: string, details?: any }` |
+| `file_indexed` | Файл проиндексирован | `{ projectId: string, filePath: string, fileIndex: object }` |
+| `file_index_error` | Ошибка индексации файла | `{ projectId: string, filePath: string, message: string }` |
 
-## Обработка ошибок
-
-При работе с индексацией могут возникать различные ошибки. Вот типичные ошибки и способы их обработки:
-
-### Ошибки HTTP API
+## Сценарии использования
 
-```javascript
-try {
-  await sdk.projects.indexProject(projectId);
-} catch (error) {
-  if (error.status === 404) {
-    console.error('Проект не найден');
-  } else if (error.status === 409) {
-    console.error('Индексация уже запущена для этого проекта');
-  } else {
-    console.error('Неизвестная ошибка:', error.message);
-  }
-}
-```
+### Индексация существующего проекта
 
-### Ошибки WebSocket
+Пример полного процесса индексации с использованием Promise:
 
 ```javascript
-// Подключение с обработкой ошибок
-try {
-  await sdk.projects.connectWebSocket();
-} catch (error) {
-  console.error('Ошибка подключения WebSocket:', error);
-}
-
-// Обработчик ошибок WebSocket
-sdk.projects.on('error', (error) => {
-  console.error('Ошибка WebSocket:', error);
-});
-
-// Обработка отключения
-sdk.projects.on('disconnect', () => {
-  console.log('WebSocket соединение прервано');
-  
-  // Автоматическое переподключение
-  setTimeout(async () => {
+async function indexProject(projectId) {
+  return new Promise(async (resolve, reject) => {
     try {
+      // Подключение к WebSocket
       await sdk.projects.connectWebSocket();
-      console.log('Переподключено к WebSocket');
+      
+      // Создаем объект для отслеживания прогресса
+      const progress = {
+        started: false,
+        percentage: 0,
+        filesIndexed: 0,
+        totalFiles: 0
+      };
+      
+      // Установка обработчиков
+      sdk.projects.on('indexing_start', () => {
+        progress.started = true;
+        console.log('Индексация началась');
+      });
+      
+      sdk.projects.on('indexing_progress', (data) => {
+        progress.percentage = data.progress;
+        progress.filesIndexed = data.indexedFiles;
+        progress.totalFiles = data.totalFiles;
+        console.log(`Прогресс: ${data.progress}%`);
+      });
+      
+      sdk.projects.on('indexing_complete', (data) => {
+        console.log('Индексация завершена!');
+        sdk.projects.disconnectWebSocket();
+        resolve({
+          success: true,
+          projectId,
+          stats: {
+            totalFiles: data.totalFiles,
+            indexedFiles: data.indexedFiles,
+            totalTime: data.totalTime
+          }
+        });
+      });
+      
+      sdk.projects.on('indexing_error', (error) => {
+        console.error(`Ошибка: ${error.message}`);
+        sdk.projects.disconnectWebSocket();
+        reject(new Error(error.message));
+      });
+      
+      // Запуск индексации
+      await sdk.projects.indexProject(projectId);
+      console.log('Запрос на индексацию отправлен');
+      
+      // Таймаут для защиты от зависания
+      setTimeout(() => {
+        if (!progress.started || progress.percentage < 100) {
+          sdk.projects.disconnectWebSocket();
+          reject(new Error('Таймаут индексации'));
+        }
+      }, 300000); // 5 минут
     } catch (error) {
-      console.error('Не удалось переподключиться:', error);
+      sdk.projects.disconnectWebSocket();
+      reject(error);
     }
-  }, 3000);
-});
-```
+  });
+}
 
-## Примеры использования
+// Использование
+indexProject('your-project-id')
+  .then(result => console.log('Результат:', result))
+  .catch(error => console.error('Ошибка:', error));
+```
 
-### Базовый пример индексации
+### Создание и индексация проекта по пути
 
 ```javascript
-// Инициализация SDK
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://localhost:3000',
-  apiKey: 'your-api-key',
-  websocket: {
-    reconnect: true // Автоматическое переподключение
-  }
-});
-
-// Запуск индексации
-async function indexProject(projectId) {
+async function createAndIndexProjectByPath(projectPath, options = {}) {
   try {
-    // Подключаемся к WebSocket пространству имен индексации
+    // Подключение к WebSocket
     await sdk.projects.connectWebSocket();
     
-    // Устанавливаем обработчики событий
+    // Установка обработчиков
+    const cleanup = () => sdk.projects.disconnectWebSocket();
+    
     sdk.projects.on('indexing_progress', (data) => {
       console.log(`Прогресс: ${data.progress}%`);
     });
     
-    sdk.projects.on('indexing_complete', (data) => {
-      console.log('Индексация завершена!');
+    sdk.projects.on('indexing_error', (error) => {
+      console.error(`Ошибка: ${error.message}`);
+      cleanup();
     });
     
-    // Запускаем индексацию
-    const result = await sdk.projects.indexProject(projectId);
-    console.log('Индексация запущена:', result);
+    // Создание и индексация проекта
+    const result = await sdk.projects.createAndIndexProject(
+      projectPath,
+      {
+        name: options.name || path.basename(projectPath),
+        forceFull: options.forceFull || false,
+        excludePatterns: options.excludePatterns || ['node_modules', '.git']
+      }
+    );
     
-    // Ждем завершения индексации
+    console.log(`Проект создан, ID: ${result.projectId}`);
+    
+    // Ожидание завершения индексации
     return new Promise((resolve, reject) => {
       sdk.projects.on('indexing_complete', (data) => {
-        sdk.projects.disconnectWebSocket();
-        resolve(data);
+        console.log('Индексация завершена успешно!');
+        cleanup();
+        resolve({
+          projectId: result.projectId,
+          indexingStats: data
+        });
       });
       
-      sdk.projects.on('indexing_error', (error) => {
-        sdk.projects.disconnectWebSocket();
-        reject(new Error(error.message));
-      });
-      
-      // Таймаут на случай, если что-то пойдет не так
+      // Таймаут
       setTimeout(() => {
-        sdk.projects.disconnectWebSocket();
-        reject(new Error('Таймаут индексации'));
-      }, 120000); // 2 минуты
+        cleanup();
+        reject(new Error('Таймаут ожидания индексации'));
+      }, 300000); // 5 минут
     });
   } catch (error) {
-    console.error('Ошибка индексации:', error);
+    sdk.projects.disconnectWebSocket();
     throw error;
   }
 }
+
+// Использование
+createAndIndexProjectByPath('/path/to/project')
+  .then(result => console.log(`Проект ${result.projectId} успешно создан и проиндексирован`))
+  .catch(error => console.error(`Ошибка: ${error.message}`));
 ```
 
-### Пример с отображением прогресс-бара
+### Интеграция с IDE
+
+Пример интеграции в расширение VS Code/Cursor:
 
 ```javascript
-const progressBar = require('progress');
+// Инициализация SDK в расширении
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: vscode.workspace.getConfiguration('mySolverExtension').get('apiKey'),
+  timeout: 15000
+});
 
-async function indexWithProgressBar(projectId) {
-  // Создаем прогресс-бар
-  let bar = null;
-  
-  // Подключаемся к WebSocket
-  await sdk.projects.connectWebSocket();
-  
-  // Устанавливаем обработчики событий
-  sdk.projects.on('indexing_start', () => {
-    console.log('Индексация началась...');
-  });
-  
-  sdk.projects.on('indexing_progress', (data) => {
-    if (!bar) {
-      bar = new progressBar('Индексация [:bar] :percent :etas', {
-        complete: '=',
-        incomplete: ' ',
-        width: 50,
-        total: 100
-      });
-    }
-    
-    bar.update(data.progress / 100);
-  });
-  
-  sdk.projects.on('indexing_complete', (data) => {
-    if (bar) {
-      bar.update(1.0); // Заполняем прогресс-бар
-    }
-    console.log(`\nИндексация завершена! Обработано ${data.indexedFiles} файлов за ${data.totalTime.toFixed(2)} секунд`);
-  });
+// Функция для индексации активного рабочего пространства
+async function indexCurrentWorkspace() {
+  // Получаем текущую рабочую директорию
+  const workspaceFolders = vscode.workspace.workspaceFolders;
+  if (!workspaceFolders || workspaceFolders.length === 0) {
+    vscode.window.showErrorMessage('Откройте папку проекта для индексации');
+    return;
+  }
   
-  // Запускаем индексацию
-  await sdk.projects.indexProject(projectId);
+  const workspacePath = workspaceFolders[0].uri.fsPath;
+  const workspaceName = path.basename(workspacePath);
   
-  // Возвращаем Promise, который разрешится при завершении индексации
-  return new Promise((resolve, reject) => {
-    sdk.projects.on('indexing_complete', (data) => {
+  // Показываем индикатор прогресса в VS Code
+  vscode.window.withProgress({
+    location: vscode.ProgressLocation.Notification,
+    title: 'Индексация проекта',
+    cancellable: true
+  }, async (progress, token) => {
+    // Обработчик отмены
+    token.onCancellationRequested(() => {
       sdk.projects.disconnectWebSocket();
-      resolve(data);
+      vscode.window.showInformationMessage('Индексация отменена');
     });
     
-    sdk.projects.on('indexing_error', (error) => {
+    try {
+      // Подключаем WebSocket
+      await sdk.projects.connectWebSocket();
+      
+      // Начинаем индексацию
+      const result = await sdk.projects.createAndIndexProject(
+        workspacePath,
+        {
+          name: workspaceName,
+          excludePatterns: [
+            'node_modules', '.git', 'dist', 'build', 
+            ...vscode.workspace.getConfiguration('search').get('exclude')
+          ]
+        }
+      );
+      
+      // Сохраняем ID проекта в настройках VS Code
+      await vscode.workspace.getConfiguration().update(
+        'mySolverExtension.projectId',
+        result.projectId,
+        vscode.ConfigurationTarget.Workspace
+      );
+      
+      progress.report({ message: 'Индексация началась...', increment: 5 });
+      
+      // Мониторинг прогресса
+      sdk.projects.on('indexing_progress', (data) => {
+        progress.report({ 
+          message: `${data.progress}% (${data.indexedFiles}/${data.totalFiles})`,
+          increment: data.progress / 20 // для плавного обновления
+        });
+      });
+      
+      // Возвращаем Promise, который разрешится при завершении
+      return new Promise((resolve) => {
+        sdk.projects.on('indexing_complete', () => {
+          sdk.projects.disconnectWebSocket();
+          vscode.window.showInformationMessage('Индексация успешно завершена!');
+          resolve();
+        });
+        
+        sdk.projects.on('indexing_error', (error) => {
+          sdk.projects.disconnectWebSocket();
+          vscode.window.showErrorMessage(`Ошибка индексации: ${error.message}`);
+          resolve();
+        });
+      });
+    } catch (error) {
       sdk.projects.disconnectWebSocket();
-      reject(new Error(error.message));
-    });
+      vscode.window.showErrorMessage(`Ошибка: ${error.message}`);
+    }
   });
 }
+
+// Регистрация команды в VS Code
+context.subscriptions.push(
+  vscode.commands.registerCommand('mySolverExtension.indexProject', indexCurrentWorkspace)
+);
 ```
 
-### Инкрементальное обновление файлов при изменении
+### Наблюдение за файловой системой
+
+Пример автоматического обновления индекса при изменении файлов:
 
 ```javascript
-const fs = require('fs');
-const path = require('path');
 const chokidar = require('chokidar');
+const path = require('path');
 
-// Функция для наблюдения за изменениями в директории и инкрементальной индексации
-async function watchAndIndex(projectId, dirPath) {
-  // Подключение WebSocket для получения уведомлений о индексации
+async function watchAndIndex(projectId, projectPath) {
+  // Подключение WebSocket
   await sdk.projects.connectWebSocket();
   
-  // Устанавливаем обработчики для отдельных файлов
+  // Установка обработчиков
   sdk.projects.on('file_indexed', (data) => {
     console.log(`Файл проиндексирован: ${data.filePath}`);
   });
   
-  sdk.projects.on('file_index_error', (data) => {
-    console.error(`Ошибка индексации файла ${data.filePath}: ${data.message}`);
-  });
-  
-  // Создаем наблюдателя за файловой системой
-  const watcher = chokidar.watch(dirPath, {
-    ignored: /(^|[\/\\])\../, // Игнорировать скрытые файлы
+  // Настройка наблюдателя за файловой системой
+  const watcher = chokidar.watch(projectPath, {
+    ignored: [
+      /(^|[\/\\])\../, // скрытые файлы
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/.git/**'
+    ],
     persistent: true,
     ignoreInitial: true
   });
   
-  // При изменении файла, обновляем его индекс
+  // Обработка изменений файлов
   watcher.on('change', async (filePath) => {
     try {
-      // Получаем путь относительно корня проекта
-      const relPath = path.relative(dirPath, filePath);
+      // Получаем относительный путь
+      const relPath = path.relative(projectPath, filePath);
       
-      console.log(`Файл изменился: ${relPath}`);
+      console.log(`Обнаружено изменение файла: ${relPath}`);
       
-      // Обновляем индекс файла
+      // Обновляем индекс для измененного файла
       await sdk.projects.updateFileIndex(projectId, relPath);
-      
-      console.log(`Отправлен запрос на обновление индекса файла: ${relPath}`);
     } catch (error) {
-      console.error(`Ошибка обновления индекса: ${error.message}`);
+      console.error(`Ошибка при обновлении индекса: ${error.message}`);
     }
   });
   
-  console.log(`Наблюдение за директорией ${dirPath} началось`);
+  console.log(`Наблюдение за директорией ${projectPath} для проекта ${projectId} запущено`);
   
   // Возвращаем функцию для остановки наблюдения
-  return () => {
-    watcher.close();
-    sdk.projects.disconnectWebSocket();
-    console.log('Наблюдение остановлено');
+  return {
+    stop: () => {
+      watcher.close();
+      sdk.projects.disconnectWebSocket();
+      console.log(`Наблюдение за директорией ${projectPath} остановлено`);
+    }
   };
 }
+
+// Использование
+const projectId = 'your-project-id';
+const projectPath = '/path/to/project';
+
+const watcher = await watchAndIndex(projectId, projectPath);
+
+// Позже можно остановить наблюдение
+// watcher.stop();
+```
+
+## Обработка ошибок
+
+При интеграции с SDK рекомендуется использовать надежную обработку ошибок.
+
+### Ошибки HTTP API
+
+```javascript
+try {
+  await sdk.projects.indexProject(projectId);
+} catch (error) {
+  // Проверка статус-кодов
+  if (error.status === 404) {
+    console.error('Проект не найден');
+    // Возможное создание нового проекта
+    const newProject = await sdk.projects.createProject('Новый проект', projectPath);
+    await sdk.projects.indexProject(newProject.id);
+  } 
+  else if (error.status === 409) {
+    console.error('Индексация уже запущена');
+    // Можно проверить текущий статус
+    const status = await sdk.projects.getIndexingStatus(projectId);
+    console.log(`Текущий прогресс: ${status.progress}%`);
+  }
+  else if (error.status === 401 || error.status === 403) {
+    console.error('Ошибка авторизации. Проверьте API ключ');
+  }
+  else {
+    console.error('Неизвестная ошибка:', error.message);
+  }
+}
+```
+
+### Надежное подключение к WebSocket
+
+```javascript
+// Функция для надежного подключения с автоматическим переподключением
+async function establishReliableConnection(projectId, maxRetries = 3) {
+  let retries = 0;
+  let connected = false;
+  
+  while (!connected && retries < maxRetries) {
+    try {
+      await sdk.projects.connectWebSocket();
+      connected = sdk.projects.isWebSocketConnected();
+      
+      if (connected) {
+        console.log('Подключение к WebSocket установлено');
+        
+        // Обработка отключений
+        sdk.projects.on('disconnect', () => {
+          console.log('WebSocket соединение прервано, переподключение...');
+          setTimeout(() => {
+            sdk.projects.connectWebSocket().catch(e => {
+              console.error('Ошибка переподключения:', e.message);
+            });
+          }, 2000);
+        });
+        
+        return true;
+      }
+      
+      retries++;
+      console.log(`Не удалось подключиться, попытка ${retries}/${maxRetries}...`);
+      await new Promise(resolve => setTimeout(resolve, 1000 * retries));
+    } catch (error) {
+      retries++;
+      console.error(`Ошибка подключения: ${error.message}`);
+      await new Promise(resolve => setTimeout(resolve, 1000 * retries));
+    }
+  }
+  
+  if (!connected) {
+    console.error('Не удалось установить WebSocket соединение после нескольких попыток');
+    return false;
+  }
+  
+  return connected;
+}
+
+// Использование
+await establishReliableConnection(projectId);
 ```
 
 Дополнительные примеры использования API индексации можно найти в файле `solver-sdk/examples/indexing-example.js`.