solver-sdk 2.6.2 → 2.7.0

package/docs/INTEGRATION_GUIDE_V2.5.md

@@ -1,516 +0,0 @@
-# 🚀 Полное руководство по интеграции SDK v2.5.0
-
-Это руководство показывает, как правильно интегрировать Code Solver SDK v2.5.0 в production проект.
-
-## 📋 Содержание
-
-- [Быстрый старт](#быстрый-старт)
-- [Инициализация](#инициализация)
-- [WebSocket управление](#websocket-управление)
-- [API диагностика](#api-диагностика)
-- [Работа с проектами](#работа-с-проектами)
-- [Рассуждения и мышление](#рассуждения-и-мышление)
-- [Обработка ошибок](#обработка-ошибок)
-- [Best practices](#best-practices)
-
-## 🚀 Быстрый старт
-
-### Установка
-
-```bash
-npm install solver-sdk
-```
-
-### Минимальный рабочий пример
-
-```javascript
-import { CodeSolverSDK } from 'solver-sdk';
-
-// ✅ Рекомендуемый способ (с валидацией)
-const sdk = await CodeSolverSDK.create({
-  baseURL: 'http://localhost:3000',
-  apiKey: 'your-api-key',
-  websocket: { autoConnect: false }
-});
-
-// Проверка API
-const diagnosis = await sdk.diagnoseAPI();
-if (diagnosis.healthy) {
-  console.log('✅ SDK готов к работе');
-} else {
-  console.log('❌ Проблемы:', diagnosis.errors);
-}
-```
-
-## 🎮 Инициализация
-
-### Способ 1: С валидацией API (рекомендуется)
-
-```javascript
-try {
-  const sdk = await CodeSolverSDK.create({
-    baseURL: 'http://localhost:3000',
-    apiKey: 'your-api-key',
-    websocket: {
-      autoConnect: false,    // Контролируем WebSocket вручную
-      reconnect: true,       // Автоматическое переподключение
-      reconnectAttempts: 3,  // Максимум 3 попытки
-      reconnectDelay: 1000   // Задержка между попытками
-    },
-    timeout: 30000,          // Таймаут HTTP запросов
-    debug: true              // Включить отладочные логи
-  });
-
-  console.log('✅ SDK инициализирован с валидацией API');
-} catch (error) {
-  console.error('❌ Ошибка инициализации:', error.message);
-  // API недоступен или неправильные настройки
-}
-```
-
-### Способ 2: Быстрая инициализация
-
-```javascript
-// Без проверки API - для быстрого старта
-const sdk = new CodeSolverSDK({
-  baseURL: 'http://localhost:3000',
-  apiKey: 'your-api-key',
-  websocket: { autoConnect: false }
-});
-
-// Проверка отдельно
-const isHealthy = await sdk.checkHealth();
-console.log(`API статус: ${isHealthy ? 'OK' : 'недоступен'}`);
-```
-
-## 🔌 WebSocket управление
-
-### Контролируемое подключение
-
-```javascript
-// ❌ СТАРЫЙ способ (автоматическое подключение)
-// const sdk = new CodeSolverSDK(); // WebSocket подключался сразу
-
-// ✅ НОВЫЙ способ v2.5.0 (ручное управление)
-const sdk = new CodeSolverSDK({
-  websocket: { autoConnect: false }  // Важно!
-});
-
-// Подключение только когда нужно
-if (needIndexing) {
-  const indexingClient = sdk.getIndexingClient();
-  const connected = await indexingClient.connectToIndexing();
-  
-  if (connected) {
-    console.log('✅ WebSocket для индексации подключен');
-    
-    // Подписка на события
-    sdk.projects.on('indexing_progress', (data) => {
-      console.log(`Прогресс: ${data.progress}%`);
-    });
-  }
-}
-
-if (needReasoning) {
-  await sdk.reasoning.connectWebSocket();
-  console.log('✅ WebSocket для рассуждений подключен');
-}
-```
-
-### Обработка ошибок WebSocket
-
-```javascript
-// ✅ Честные ошибки v2.5.0 (без fallback'ов)
-try {
-  sdk.projects.on('indexing_complete', callback);
-} catch (error) {
-  console.error('❌ WebSocket не подключен:', error.message);
-  // Нужно подключиться перед использованием
-  await sdk.projects.connectWebSocket();
-}
-
-// ✅ Проверка перед использованием
-if (sdk.projects.isWebSocketConnected()) {
-  sdk.projects.emitSocketEvent('custom_event', data);
-} else {
-  console.log('WebSocket не подключен, подключаемся...');
-  await sdk.projects.connectWebSocket();
-}
-```
-
-## 🔍 API диагностика
-
-### Полная диагностика
-
-```javascript
-const diagnosis = await sdk.diagnoseAPI();
-
-console.log(`API здоровье: ${diagnosis.healthy ? 'OK' : 'Проблемы'}`);
-console.log(`Проверено endpoints: ${diagnosis.total}`);
-console.log(`Работающих: ${diagnosis.working}`);
-console.log(`Проблемных: ${diagnosis.failed}`);
-
-if (!diagnosis.healthy) {
-  console.log('\nПроблемные endpoints:');
-  diagnosis.errors.forEach(error => {
-    console.log(`❌ ${error}`);
-  });
-  
-  console.log('\nРабочие endpoints:');
-  diagnosis.working.forEach(endpoint => {
-    console.log(`✅ ${endpoint}`);
-  });
-}
-```
-
-### Диагностика WebSocket
-
-```javascript
-// Проверка состояния всех WebSocket соединений
-const wsStatus = {
-  projects: sdk.projects.isWebSocketConnected(),
-  reasoning: sdk.reasoning.isWebSocketConnected(),
-  dependencies: sdk.dependencies.isWebSocketConnected()
-};
-
-console.log('WebSocket статус:', wsStatus);
-
-// Подключение только нужных сервисов
-for (const [service, connected] of Object.entries(wsStatus)) {
-  if (!connected && needService[service]) {
-    await sdk[service].connectWebSocket();
-  }
-}
-```
-
-## 📁 Работа с проектами
-
-### Создание и индексация
-
-```javascript
-try {
-  // Создание проекта
-  const project = await sdk.projects.createProject(
-    'My Project',
-    '/path/to/project',
-    {
-      excludePatterns: ['node_modules', '.git', 'dist']
-    }
-  );
-
-  console.log('✅ Проект создан:', project.id);
-
-  // Индексация с WebSocket мониторингом
-  await sdk.projects.connectWebSocket();
-  
-  sdk.projects.on('indexing_progress', (data) => {
-    console.log(`📊 Прогресс: ${data.progress}% (${data.processedFiles}/${data.totalFiles})`);
-  });
-
-  sdk.projects.on('indexing_complete', (data) => {
-    console.log(`✅ Индексация завершена: ${data.success ? 'успешно' : 'с ошибками'}`);
-  });
-
-  // Запуск индексации
-  const indexResult = await sdk.projects.indexProject(project.id, {
-    indexingMode: 'auto',  // auto, full, incremental
-    forceFull: false
-  });
-
-  console.log('✅ Индексация запущена:', indexResult);
-
-} catch (error) {
-  console.error('❌ Ошибка работы с проектом:', error.message);
-}
-```
-
-## 🧠 Рассуждения и мышление
-
-### Новые алиасы методов v2.5.0
-
-```javascript
-// ✅ Короткие алиасы (новое в v2.5.0)
-const reasoning = await sdk.reasoning.create({
-  projectId: project.id,
-  query: 'Объясни архитектуру проекта'
-});
-
-await sdk.reasoning.start(reasoning.id);
-const result = await sdk.reasoning.getReasoning(reasoning.id);
-await sdk.reasoning.stop(reasoning.id);
-
-// ✅ Полные названия (совместимость)
-const reasoning2 = await sdk.reasoning.createReasoning({
-  projectId: project.id,
-  query: 'Как улучшить производительность?'
-});
-
-await sdk.reasoning.startReasoning(reasoning2.id);
-await sdk.reasoning.stopReasoning(reasoning2.id);
-```
-
-### Потоковое мышление с Anthropic
-
-```javascript
-// Настройка для Anthropic Claude thinking
-const stream = await sdk.chat.streamChatWithThinking([
-  {
-    role: 'user',
-    content: [
-      {
-        type: 'text',
-        text: 'Объясни, как работает этот код:'
-      },
-      {
-        type: 'text', 
-        text: codeContent
-      }
-    ]
-  }
-], {
-  model: 'claude-3-5-sonnet-20241022',
-  thinking: true,          // Включаем мышление
-  preserveSignature: true  // Сохраняем подписи
-});
-
-// Обработка потока
-for await (const chunk of stream) {
-  if (chunk.type === 'thinking') {
-    console.log('🤔 Мышление:', chunk.thinking);
-  } else if (chunk.type === 'content') {
-    process.stdout.write(chunk.content);
-  } else if (chunk.type === 'signature') {
-    console.log('🔐 Подпись сохранена');
-  }
-}
-```
-
-## ❌ Обработка ошибок
-
-### "Fail Fast" подход v2.5.0
-
-```javascript
-// ✅ Честные ошибки (без fallback'ов)
-try {
-  // WebSocket методы сразу бросают ошибку
-  sdk.projects.on('event', callback);
-} catch (error) {
-  console.error('❌ WebSocket не подключен');
-  // Решение: подключиться перед использованием
-  await sdk.projects.connectWebSocket();
-  sdk.projects.on('event', callback);
-}
-
-try {
-  // API методы честно сообщают о проблемах
-  const projects = await sdk.projects.getAllProjects();
-} catch (error) {
-  console.error('❌ API ошибка:', error.message);
-  
-  // Диагностика проблемы
-  const diagnosis = await sdk.diagnoseAPI();
-  if (!diagnosis.healthy) {
-    console.log('Проблема с API endpoints:', diagnosis.errors);
-  }
-}
-```
-
-### Retry логика
-
-```javascript
-async function withRetry(operation, maxAttempts = 3) {
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      return await operation();
-    } catch (error) {
-      console.log(`Попытка ${attempt}/${maxAttempts} неудачна:`, error.message);
-      
-      if (attempt === maxAttempts) {
-        throw error; // Последняя попытка - бросаем ошибку
-      }
-      
-      // Экспоненциальная задержка
-      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
-    }
-  }
-}
-
-// Использование
-const projects = await withRetry(() => sdk.projects.getAllProjects());
-```
-
-## 💡 Best Practices
-
-### 1. Инициализация в production
-
-```javascript
-class SolverSDKManager {
-  constructor(config) {
-    this.config = config;
-    this.sdk = null;
-    this.isReady = false;
-  }
-
-  async initialize() {
-    try {
-      // Валидация с таймаутом
-      this.sdk = await Promise.race([
-        CodeSolverSDK.create({
-          ...this.config,
-          websocket: { autoConnect: false }
-        }),
-        new Promise((_, reject) => 
-          setTimeout(() => reject(new Error('Timeout')), 10000)
-        )
-      ]);
-
-      // Диагностика
-      const diagnosis = await this.sdk.diagnoseAPI();
-      if (!diagnosis.healthy) {
-        throw new Error(`API проблемы: ${diagnosis.errors.join(', ')}`);
-      }
-
-      this.isReady = true;
-      console.log('✅ SDK готов к production использованию');
-
-    } catch (error) {
-      console.error('❌ Не удалось инициализировать SDK:', error.message);
-      throw error;
-    }
-  }
-
-  ensureReady() {
-    if (!this.isReady) {
-      throw new Error('SDK не инициализирован. Вызовите initialize() сначала.');
-    }
-  }
-
-  async getProjects() {
-    this.ensureReady();
-    return this.sdk.projects.getAllProjects();
-  }
-}
-
-// Использование
-const sdkManager = new SolverSDKManager({
-  baseURL: process.env.SOLVER_API_URL,
-  apiKey: process.env.SOLVER_API_KEY
-});
-
-await sdkManager.initialize();
-```
-
-### 2. WebSocket lifecycle управление
-
-```javascript
-class WebSocketManager {
-  constructor(sdk) {
-    this.sdk = sdk;
-    this.connections = new Set();
-  }
-
-  async connectService(serviceName) {
-    if (this.connections.has(serviceName)) {
-      return; // Уже подключен
-    }
-
-    const service = this.sdk[serviceName];
-    const connected = await service.connectWebSocket();
-    
-    if (connected) {
-      this.connections.add(serviceName);
-      console.log(`✅ ${serviceName} WebSocket подключен`);
-    }
-  }
-
-  async disconnectAll() {
-    for (const serviceName of this.connections) {
-      await this.sdk[serviceName].disconnectWebSocket();
-    }
-    this.connections.clear();
-    console.log('✅ Все WebSocket соединения закрыты');
-  }
-
-  isServiceConnected(serviceName) {
-    return this.connections.has(serviceName);
-  }
-}
-
-// Использование
-const wsManager = new WebSocketManager(sdk);
-
-// Подключение по требованию
-if (needIndexing) await wsManager.connectService('projects');
-if (needReasoning) await wsManager.connectService('reasoning');
-
-// Cleanup при завершении работы
-process.on('SIGINT', () => {
-  wsManager.disconnectAll();
-  process.exit(0);
-});
-```
-
-### 3. Error boundary для React
-
-```jsx
-import React, { Component } from 'react';
-
-class SDKErrorBoundary extends Component {
-  constructor(props) {
-    super(props);
-    this.state = { hasError: false, error: null };
-  }
-
-  static getDerivedStateFromError(error) {
-    return { hasError: true, error };
-  }
-
-  componentDidCatch(error, errorInfo) {
-    // Логируем ошибки SDK
-    console.error('SDK Error:', error);
-    
-    // Диагностика при ошибке
-    if (this.props.sdk) {
-      this.props.sdk.diagnoseAPI().then(diagnosis => {
-        if (!diagnosis.healthy) {
-          console.error('API проблемы:', diagnosis.errors);
-        }
-      });
-    }
-  }
-
-  render() {
-    if (this.state.hasError) {
-      return (
-        <div className="error-boundary">
-          <h2>⚠️ Ошибка SDK</h2>
-          <p>{this.state.error?.message}</p>
-          <button onClick={() => this.setState({ hasError: false })}>
-            Попробовать снова
-          </button>
-        </div>
-      );
-    }
-
-    return this.props.children;
-  }
-}
-
-// Использование
-<SDKErrorBoundary sdk={sdk}>
-  <YourApp />
-</SDKErrorBoundary>
-```
-
-## 🎯 Заключение
-
-SDK v2.5.0 готов к production использованию с полным контролем над инициализацией, WebSocket соединениями и честной обработкой ошибок.
-
-**Ключевые принципы:**
-- ✅ Используйте `autoConnect: false` для контроля WebSocket
-- ✅ Применяйте `diagnoseAPI()` для проверки endpoints
-- ✅ Обрабатывайте честные ошибки без fallback'ов
-- ✅ Подключайте WebSocket только когда нужно
-- ✅ Используйте алиасы методов для удобства
-
-**Результат:** Стабильная работа в production без скрытых проблем!