solver-sdk 3.1.1 → 3.1.3

package/docs/ERROR_HANDLING.md

@@ -1,613 +0,0 @@
-# Обработка ошибок v2.5.0
-
-Полная документация по обработке ошибок в AI Solver SDK v2.5.0.
-
-## Философия "Fail Fast"
-
-SDK v2.5.0 следует принципу "fail fast" - ошибки возникают сразу при обнаружении проблем, без тихих fallback'ов.
-
-## Обработка HTTP ошибок
-
-### Использование try/catch
-
-Рекомендуемый способ обработки ошибок:
-
-```javascript
-import { CodeSolverSDK } from '@ai-solver/sdk';
-
-try {
-  const projects = await sdk.projects.getAll();
-  console.log('✅ Получено проектов:', projects.total);
-} catch (error) {
-  console.error('❌ Ошибка:', error.message);
-  
-  // Проверка типа ошибки
-  if (error.status === 401) {
-    console.error('🔑 Ошибка аутентификации');
-  } else if (error.status === 404) {
-    console.error('🔍 Ресурс не найден');
-  } else if (error.code === 'NETWORK_ERROR') {
-    console.error('🌐 Проблема сети');
-  }
-}
-```
-
-### Структура ошибок
-
-SDK v2.5.0 возвращает стандартизированные ошибки:
-
-```javascript
-// Пример объекта ошибки
-{
-  name: 'APIError',
-  message: 'Project not found',
-  status: 404,
-  code: 'PROJECT_NOT_FOUND',
-  endpoint: '/api/v1/projects/123',
-  method: 'GET',
-  timestamp: '2025-06-28T12:00:00Z',
-  requestId: 'req_abc123'
-}
-```
-
-## Обработка WebSocket ошибок
-
-### Обработка событий ошибок
-
-```javascript
-// Projects WebSocket ошибки
-await sdk.projects.connectWebSocket();
-
-sdk.projects.onIndexingError((error) => {
-  console.error('❌ Indexing error:', error.message);
-  console.error('📁 Project:', error.projectId);
-  console.error('📄 File:', error.fileName);
-});
-
-// Reasoning WebSocket ошибки
-await sdk.reasoning.connectWebSocket();
-
-sdk.reasoning.onReasoningError((error) => {
-  console.error('❌ Reasoning error:', error.message);
-  console.error('🆔 Reasoning ID:', error.reasoningId);
-});
-
-// Chat WebSocket ошибки
-await sdk.chat.connectWebSocket();
-
-sdk.chat.on('error', (error) => {
-  console.error('❌ Chat error:', error.message);
-});
-```
-
-### Обработка ошибок подключения
-
-```javascript
-try {
-  await sdk.projects.connectWebSocket();
-  console.log('✅ Projects WebSocket connected');
-} catch (error) {
-  console.error('❌ WebSocket connection failed:', error.message);
-  
-  if (error.code === 'WS_CONNECTION_REFUSED') {
-    console.error('🔌 Server unavailable');
-  } else if (error.code === 'WS_AUTH_FAILED') {
-    console.error('🔑 Authentication failed');
-  }
-}
-```
-
-## Диагностика ошибок
-
-### API диагностика
-
-```javascript
-// Полная диагностика всех endpoints
-const diagnostics = await sdk.diagnoseAPI();
-console.log('📊 API Diagnostics:', diagnostics);
-
-/* Пример результата:
-{
-  '/api/v1/projects': { 
-    status: 200, 
-    success: true, 
-    responseTime: 120 
-  },
-  '/api/v1/reasoning': { 
-    status: 401, 
-    success: false, 
-    error: 'Invalid API key' 
-  },
-  '/api/v1/chat': { 
-    status: 500, 
-    success: false, 
-    error: 'Internal server error' 
-  }
-}
-*/
-```
-
-### WebSocket диагностика
-
-```javascript
-// Диагностика WebSocket соединений
-const wsStatus = await sdk.diagnoseWebSocket();
-console.log('🔌 WebSocket status:', wsStatus);
-
-/* Пример результата:
-{
-  projects: { 
-    connected: true, 
-    url: 'ws://localhost:3000/projects' 
-  },
-  reasoning: { 
-    connected: false, 
-    error: 'Connection timeout' 
-  },
-  chat: { 
-    connected: true, 
-    latency: 45 
-  }
-}
-*/
-```
-
-## Типы ошибок
-
-### HTTP ошибки
-
-#### 400 Bad Request
-
-```javascript
-{
-  status: 400,
-  code: 'VALIDATION_ERROR',
-  message: 'Invalid project data',
-  details: {
-    field: 'name',
-    issue: 'Name is required'
-  }
-}
-```
-
-**Решение:** Проверьте корректность входных данных.
-
-#### 401 Unauthorized
-
-```javascript
-{
-  status: 401,
-  code: 'AUTH_INVALID_KEY',
-  message: 'Invalid or missing API key'
-}
-```
-
-**Решение:** Проверьте API ключ в настройках SDK.
-
-#### 403 Forbidden
-
-```javascript
-{
-  status: 403,
-  code: 'AUTH_INSUFFICIENT_SCOPE',
-  message: 'Insufficient permissions',
-  required_scope: 'projects:write'
-}
-```
-
-**Решение:** Используйте API ключ с необходимыми правами.
-
-#### 404 Not Found
-
-```javascript
-{
-  status: 404,
-  code: 'PROJECT_NOT_FOUND',
-  message: 'Project with ID "123" not found'
-}
-```
-
-**Решение:** Проверьте правильность ID ресурса.
-
-#### 429 Too Many Requests
-
-```javascript
-{
-  status: 429,
-  code: 'RATE_LIMIT_EXCEEDED',
-  message: 'Rate limit exceeded',
-  retry_after: 60
-}
-```
-
-**Решение:** Подождите указанное время или используйте Production ключ.
-
-#### 500 Internal Server Error
-
-```javascript
-{
-  status: 500,
-  code: 'INTERNAL_ERROR',
-  message: 'Internal server error',
-  incident_id: 'inc_abc123'
-}
-```
-
-**Решение:** Сообщите о проблеме с указанием incident_id.
-
-### WebSocket ошибки
-
-#### WS_CONNECTION_REFUSED
-
-```javascript
-{
-  code: 'WS_CONNECTION_REFUSED',
-  message: 'WebSocket connection refused',
-  namespace: 'projects'
-}
-```
-
-**Решение:** Проверьте доступность сервера.
-
-#### WS_AUTH_FAILED
-
-```javascript
-{
-  code: 'WS_AUTH_FAILED',
-  message: 'WebSocket authentication failed',
-  namespace: 'reasoning'
-}
-```
-
-**Решение:** Проверьте API ключ.
-
-#### WS_TIMEOUT
-
-```javascript
-{
-  code: 'WS_TIMEOUT',
-  message: 'WebSocket connection timeout',
-  timeout: 30000
-}
-```
-
-**Решение:** Увеличьте timeout или проверьте сеть.
-
-### Network ошибки
-
-#### NETWORK_ERROR
-
-```javascript
-{
-  code: 'NETWORK_ERROR',
-  message: 'Network request failed',
-  cause: 'ECONNREFUSED'
-}
-```
-
-**Решение:** Проверьте подключение к интернету и доступность сервера.
-
-#### TIMEOUT_ERROR
-
-```javascript
-{
-  code: 'TIMEOUT_ERROR',
-  message: 'Request timeout after 30000ms',
-  timeout: 30000
-}
-```
-
-**Решение:** Увеличьте timeout в настройках SDK.
-
-## Стратегии обработки ошибок
-
-### Retry стратегия
-
-```javascript
-async function retryableRequest(operation, maxRetries = 3) {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      return await operation();
-    } catch (error) {
-      console.warn(`⚠️ Attempt ${attempt} failed:`, error.message);
-      
-      // Не повторяем для клиентских ошибок
-      if (error.status >= 400 && error.status < 500) {
-        throw error;
-      }
-      
-      // Последняя попытка
-      if (attempt === maxRetries) {
-        throw error;
-      }
-      
-      // Экспоненциальная задержка
-      const delay = Math.pow(2, attempt) * 1000;
-      await new Promise(resolve => setTimeout(resolve, delay));
-    }
-  }
-}
-
-// Использование
-try {
-  const projects = await retryableRequest(() => sdk.projects.getAll());
-} catch (error) {
-  console.error('❌ All retries failed:', error.message);
-}
-```
-
-### Circuit Breaker
-
-```javascript
-class CircuitBreaker {
-  constructor(threshold = 5, timeout = 60000) {
-    this.threshold = threshold;
-    this.timeout = timeout;
-    this.failures = 0;
-    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
-    this.nextAttempt = Date.now();
-  }
-  
-  async execute(operation) {
-    if (this.state === 'OPEN') {
-      if (Date.now() < this.nextAttempt) {
-        throw new Error('Circuit breaker is OPEN');
-      }
-      this.state = 'HALF_OPEN';
-    }
-    
-    try {
-      const result = await operation();
-      this.onSuccess();
-      return result;
-    } catch (error) {
-      this.onFailure();
-      throw error;
-    }
-  }
-  
-  onSuccess() {
-    this.failures = 0;
-    this.state = 'CLOSED';
-  }
-  
-  onFailure() {
-    this.failures++;
-    if (this.failures >= this.threshold) {
-      this.state = 'OPEN';
-      this.nextAttempt = Date.now() + this.timeout;
-    }
-  }
-}
-
-// Использование
-const breaker = new CircuitBreaker();
-
-try {
-  const result = await breaker.execute(() => sdk.chat.send(messages));
-} catch (error) {
-  console.error('❌ Circuit breaker error:', error.message);
-}
-```
-
-### Graceful degradation
-
-```javascript
-async function robustProjectCreation(projectData) {
-  try {
-    // Основной путь
-    const project = await sdk.projects.create(projectData);
-    console.log('✅ Project created:', project.id);
-    
-    // Запуск индексации
-    try {
-      await sdk.projects.startIndexing(project.id);
-      console.log('✅ Indexing started');
-    } catch (indexError) {
-      console.warn('⚠️ Indexing failed, but project created:', indexError.message);
-    }
-    
-    return project;
-    
-  } catch (error) {
-    console.error('❌ Project creation failed:', error.message);
-    
-    // Fallback: сохраняем локально
-    const localProject = {
-      id: `local_${Date.now()}`,
-      name: projectData.name,
-      path: projectData.path,
-      local: true
-    };
-    
-    localStorage.setItem(`project_${localProject.id}`, JSON.stringify(localProject));
-    console.log('💾 Project saved locally:', localProject.id);
-    
-    return localProject;
-  }
-}
-```
-
-## Мониторинг ошибок
-
-### Логирование ошибок
-
-```javascript
-function logError(error, context = {}) {
-  const errorLog = {
-    timestamp: new Date().toISOString(),
-    error: {
-      name: error.name,
-      message: error.message,
-      status: error.status,
-      code: error.code,
-      stack: error.stack
-    },
-    context: {
-      ...context,
-      userAgent: navigator.userAgent,
-      url: window.location.href,
-      userId: getCurrentUserId()
-    }
-  };
-  
-  // Отправка в систему мониторинга
-  sendToMonitoring(errorLog);
-  
-  // Локальное логирование
-  console.error('🚨 Error logged:', errorLog);
-}
-
-// Использование
-try {
-  await sdk.reasoning.start(reasoningId);
-} catch (error) {
-  logError(error, {
-    operation: 'reasoning_start',
-    reasoningId: reasoningId,
-    projectId: projectId
-  });
-}
-```
-
-### Метрики ошибок
-
-```javascript
-class ErrorMetrics {
-  constructor() {
-    this.errors = new Map();
-  }
-  
-  record(error) {
-    const key = `${error.code || 'UNKNOWN'}_${error.status || 0}`;
-    const count = this.errors.get(key) || 0;
-    this.errors.set(key, count + 1);
-  }
-  
-  getReport() {
-    const report = Array.from(this.errors.entries())
-      .map(([error, count]) => ({ error, count }))
-      .sort((a, b) => b.count - a.count);
-    
-    return {
-      totalErrors: Array.from(this.errors.values()).reduce((a, b) => a + b, 0),
-      topErrors: report.slice(0, 5),
-      allErrors: report
-    };
-  }
-}
-
-// Глобальные метрики
-const errorMetrics = new ErrorMetrics();
-
-// Автоматическая регистрация ошибок
-window.addEventListener('unhandledrejection', (event) => {
-  errorMetrics.record(event.reason);
-});
-```
-
-## Пример комплексной обработки
-
-```javascript
-async function initializeAIWorkflow(projectPath, query) {
-  const sdk = CodeSolverSDK.create({
-    baseURL: 'http://localhost:3000',
-    apiKey: process.env.AI_SOLVER_API_KEY,
-    autoConnect: false
-  });
-  
-  try {
-    // 1. Диагностика API
-    console.log('🔍 Diagnosing API...');
-    const apiStatus = await sdk.diagnoseAPI();
-    
-    const healthyEndpoints = Object.entries(apiStatus)
-      .filter(([_, status]) => status.success)
-      .map(([endpoint]) => endpoint);
-    
-    if (healthyEndpoints.length === 0) {
-      throw new Error('No healthy endpoints available');
-    }
-    
-    console.log('✅ Healthy endpoints:', healthyEndpoints);
-    
-    // 2. Создание проекта
-    console.log('📁 Creating project...');
-    const project = await retryableRequest(() => 
-      sdk.projects.create({
-        name: 'AI Analysis Project',
-        path: projectPath
-      })
-    );
-    
-    // 3. Индексация с WebSocket
-    console.log('📊 Starting indexing...');
-    await sdk.projects.connectWebSocket();
-    
-    let indexingComplete = false;
-    sdk.projects.onIndexingComplete(() => {
-      indexingComplete = true;
-      console.log('✅ Indexing completed');
-      sdk.projects.disconnectWebSocket();
-    });
-    
-    sdk.projects.onIndexingError((error) => {
-      console.error('❌ Indexing failed:', error.message);
-      sdk.projects.disconnectWebSocket();
-    });
-    
-    await sdk.projects.startIndexing(project.id);
-    
-    // Ожидание завершения индексации
-    while (!indexingComplete) {
-      await new Promise(resolve => setTimeout(resolve, 1000));
-    }
-    
-    // 4. AI Reasoning
-    console.log('🧠 Starting reasoning...');
-    await sdk.reasoning.connectWebSocket();
-    
-    const reasoning = await sdk.reasoning.create({
-      projectId: project.id,
-      query: query
-    });
-    
-    await sdk.reasoning.start(reasoning.id);
-    
-    return {
-      project,
-      reasoning,
-      success: true
-    };
-    
-  } catch (error) {
-    console.error('❌ Workflow failed:', error.message);
-    
-    // Очистка ресурсов
-    try {
-      await sdk.projects.disconnectWebSocket();
-      await sdk.reasoning.disconnectWebSocket();
-    } catch (cleanupError) {
-      console.warn('⚠️ Cleanup warning:', cleanupError.message);
-    }
-    
-    // Регистрация ошибки
-    logError(error, {
-      workflow: 'ai_analysis',
-      projectPath,
-      query
-    });
-    
-    return {
-      error: error.message,
-      success: false
-    };
-  }
-}
-```
-
----
-
-**Документация обработки ошибок для SDK v2.5.0**  
-**Принцип:** Fail Fast, явные ошибки, надежная диагностика  
-**Обновлено:** 28 июня 2025 

package/docs/README.md

@@ -1,53 +0,0 @@
-# Code Solver SDK - Документация
-
-> **JavaScript/TypeScript SDK для VS Code Extensions**  
-> Подключение к AI бэкенду для индексации, поиска и работы с кодом
-
-## 📚 Основная документация
-
-### [📊 Индексация проектов](indexing/INDEXING.md)
-**Подробное руководство по индексации:**
-- Создание и поиск проектов
-- Запуск и мониторинг индексации
-- Workflow с обработкой ошибок
-- Практические примеры
-
-### [🔧 Интеграция с VS Code](VSCODE_INTEGRATION.md)
-**Готовые примеры для Extensions:**
-- Базовая настройка SDK
-- Индексация с прогресс-баром
-- Поиск функций с навигацией
-- AI Chat интеграция
-- Конфигурация package.json
-
-### [🚨 Обработка ошибок](ERROR_HANDLING.md)
-**Как правильно обрабатывать ошибки:**
-- Сетевые ошибки
-- Ошибки индексации
-- Retry логика
-- Graceful degradation
-
-## 🚀 Быстрый старт
-
-```javascript
-import { CodeSolverSDK } from 'solver-sdk';
-
-// 1. Инициализация
-const sdk = await CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000'
-});
-
-// 2. Создание проекта
-const project = await sdk.projects.findOrCreateProject('/path/to/project', 'My Project');
-
-// 3. Индексация
-await sdk.projects.startIndexing(project.id);
-
-// 4. Поиск функций
-const results = await sdk.search.searchFunctions(project.id, {
-  query: 'user authentication',
-  limit: 10
-});
-```
-
-SDK готов к продакшену! ��