JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 11
  • Score
    100M100P100Q82331F
  • License MIT

SDK for API integration

Package Exports

  • solver-sdk

Readme

Code Solver SDK

🚀 Официальный JavaScript/TypeScript SDK для Code Solver API

Современный SDK для интеграции с Code Solver - платформой для анализа кода, векторного поиска и AI-ассистента. Поддерживает WebSocket для real-time уведомлений и delta-chunking для эффективной синхронизации.

📦 Установка

npm install solver-sdk

🚀 Быстрый старт

import { CodeSolverSDK } from 'solver-sdk';

const sdk = new CodeSolverSDK({
  baseURL: 'http://localhost:3000',
  apiKey: 'your-api-key',
  webSocket: { enabled: true }
});

// 🔄 Cursor-like workflow для VS Code расширения
async function openProject(projectPath: string) {
  // 1. Создать/найти проект
  const project = await sdk.projects.findOrCreateProject(projectPath, projectName);
  
  // 2. Проверить прерванные сессии
  const recovery = await sdk.projects.getRecoveryStatus(project.id);
  if (recovery.hasInterruptedSession) {
    // Показать диалог: "Continue indexing (67%)" или "Start fresh"
    const choice = await showRecoveryDialog(recovery.recoveryInfo);
    if (choice === 'continue') {
      await sdk.projects.resumeSync(project.id);
    } else {
      await sdk.projects.cancelRecovery(project.id);
    }
  }
  
  // 3. Smart Sync - проверить нужна ли синхронизация
  const hash = await computeMerkleRootHash(projectPath);
  const state = await sdk.projects.getProjectState(project.id, hash);
  
  if (state.syncRequired) {
    await sdk.projects.initializeDeltaSync(project.id, hash);
  }
}

📖 API Reference

🏗️ Инициализация SDK

new CodeSolverSDK(options)

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)
  };
}

📁 Projects API (sdk.projects)

🏗️ Управление проектами

// Создание проекта
createProject(name: string, path: string, data?: any): Promise<Project>

// Получение всех проектов
getAllProjects(): Promise<Project[]>
getProjects(): Promise<Project[]> // Псевдоним

// Получение проекта по ID
getProject(projectId: string): Promise<Project | null>

// Поиск или создание проекта
findOrCreateProject(projectPath: string, projectName: string, description?: string): Promise<Project>

📊 Управление состоянием и индексацией

// Получение статуса индексации проекта
getIndexingStatus(projectId: string): Promise<any>

// 🔍 Проверка состояния проекта (новое в v5.3.2+)
getProjectState(projectId: string, clientRootHash?: string): Promise<ProjectState>

// 🔄 Проверка прерванных сессий (новое в v5.5.0+)
getRecoveryStatus(projectId: string): Promise<{
  hasInterruptedSession: boolean;
  recoveryInfo?: RecoveryInfo;
}>

// 🔄 Возобновление прерванной синхронизации (новое в v5.5.0+)
resumeSync(projectId: string, options?: ResumeOptions): Promise<{
  success: boolean;
  message: string;
  sessionId?: string;
  continueFromBatch?: number;
  resumeEndpoint?: string;
}>

// 🗑️ Отмена прерванной сессии (новое в v5.5.0+)
cancelRecovery(projectId: string): Promise<{
  success: boolean;
  message: string;
}>

🧹 Управление данными проекта

// 🧹 Очистка удаленных файлов (новое в v5.4.0+)
cleanupDeletedFiles(projectId: string, activeFiles: ActiveFile[]): Promise<FileCleanupResult>

// 🔍 Получение mapping обфусцированных путей (новое в v5.4.0+)
getFilePathMapping(projectId: string): Promise<{
  success: boolean;
  files: FilePathMapping[];
}>

🔍 Search API (sdk.search)

Поиск по коду

// Основной поиск по коду
searchCode(projectId: string, params: SearchCodeParams): Promise<SearchResult[]>
searchCode(params: SearchCodeParams): Promise<SearchResult[]> // Альтернативная сигнатура

// Семантический поиск
semanticSearch(projectId: string, params: Omit<SearchCodeParams, 'projectId'>): Promise<SearchResult[]>

// Поиск функций
searchFunctions(projectId: string, params: SearchFunctionsParams): Promise<FunctionSearchResult>

Параметры поиска

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;     // Время индексации
}

Примеры использования

// Обычный поиск
const results = await sdk.search.searchCode('project-id', {
  query: 'function authenticate',
  limit: 20
});

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
});

🔌 WebSocket API (sdk.projectSync)

Real-time уведомления

// Подключение к WebSocket
connectWebSocket(): Promise<void>

// Отключение от WebSocket
disconnectWebSocket(): void

// Проверка статуса подключения
isWebSocketConnected: boolean

// Подписка на проект
projectSync.subscribeToProject(projectId: string): void

// Отписка от проекта
projectSync.unsubscribeFromProject(projectId: string): void

// Обработчики событий
projectSync.on(eventName: string, handler: Function): void
projectSync.off(eventName: string, handler: Function): void

События WebSocket

// Обновление статуса синхронизации
'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

Примеры использования

// Подключение и подписка на проект
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}`);
  }
});

sdk.projectSync.on('error', (error) => {
  console.error(`WebSocket ошибка: ${error.error}`);
});

// Отключение
sdk.disconnectWebSocket();

🎯 ПОЛНОЕ РУКОВОДСТВО ПО УПРАВЛЕНИЮ ИНДЕКСАЦИЕЙ

🔄 Cursor-like Workflow - Рекомендуемый подход

import { CodeSolverSDK } from 'solver-sdk';

/**
 * 🎯 ОСНОВНОЙ WORKFLOW - используйте этот паттерн в вашем VS Code расширении
 */
async function handleProjectIndexing(projectPath: string) {
  const sdk = new CodeSolverSDK({ 
    baseURL: 'http://localhost:3000',
    apiKey: 'your-api-key' 
  });

  // 1. 🔍 Получить или создать проект
  const project = await sdk.projects.findOrCreateProject(
    projectPath, 
    path.basename(projectPath)
  );
  const projectId = project.id;

  // 2. 🔄 КРИТИЧЕСКИ ВАЖНО: Проверить прерванные сессии
  const recoveryStatus = await sdk.projects.getRecoveryStatus(projectId);

  if (recoveryStatus.hasInterruptedSession) {
    // 🎨 Cursor-like UX: Показать диалог восстановления
    const info = recoveryStatus.recoveryInfo!;
    const choice = await showUserChoice({
      title: 'Indexing was interrupted',
      message: `Indexing was interrupted at ${info.progress.percentage}%. Continue from where you left off?`,
      buttons: [
        { text: '🔄 Continue Indexing', value: 'continue' },
        { text: '🆕 Start Fresh', value: 'fresh' }
      ]
    });

    if (choice === 'continue') {
      return await continueInterruptedIndexing(projectId);
    } else {
      return await startFreshIndexing(projectId);
    }
  }

  // 3. 🔍 Проверить нужна ли синхронизация (Smart Sync)
  const clientHash = await computeMerkleRootHash(projectPath);
  const state = await sdk.projects.getProjectState(projectId, clientHash);

  if (!state.syncRequired) {
    console.log('✅ Проект актуален, синхронизация не нужна');
    return { success: true, message: 'Project is up to date' };
  }

  // 4. 🚀 Начать новую синхронизацию
  return await startFreshIndexing(projectId, clientHash);
}

/**
 * 🔄 Продолжение прерванной индексации
 */
async function continueInterruptedIndexing(projectId: string) {
  const resumed = await sdk.projects.resumeSync(projectId, {
    skipDuplicates: true,
    continueFromLastBatch: true
  });

  if (!resumed.success) {
    console.error('Failed to resume:', resumed.message);
    return await startFreshIndexing(projectId); // Fallback
  }

  console.log(`✅ Resumed from batch ${resumed.continueFromBatch || 0}`);
  
  // Продолжить обычную синхронизацию
  const merkleHash = await computeMerkleRootHash(workspacePath);
  return await performDeltaSync(projectId, merkleHash, {
    resumeFromSession: resumed.sessionId
  });
}

/**
 * 🆕 Начать новую индексацию (с очисткой прерванных сессий)
 */
async function startFreshIndexing(projectId: string, clientHash?: string) {
  // Отменить прерванные сессии если есть
  await sdk.projects.cancelRecovery(projectId);
  
  // Вычислить hash если не передан
  if (!clientHash) {
    clientHash = await computeMerkleRootHash(workspacePath);
  }

  // Начать новую синхронизацию
  return await performDeltaSync(projectId, clientHash);
}

/**
 * 🧹 Полная очистка проекта (удаление всех данных)
 */
async function clearProjectData(projectId: string) {
  // ВНИМАНИЕ: Это удалит ВСЕ проиндексированные данные!
  
  // Способ 1: Удалить проект полностью
  await sdk.projects.deleteProject(projectId);
  console.log('✅ Проект и все данные удалены полностью');
  
  // Способ 2: Очистить только файлы (оставить проект)
  const result = await sdk.cleanupDeletedFiles(projectId, []); // Пустой список = удалить все
  console.log(`✅ Очищено: ${result.deletedFromQdrant} векторов, ${result.deletedFromPostgres} записей`);
}

📊 Мониторинг прогресса индексации

// Real-time мониторинг через WebSocket
await sdk.connectWebSocket();

sdk.projectSync.on('sync-progress', (progress) => {
  updateProgressBar({
    percentage: progress.progress,
    stage: progress.stage,
    currentFile: progress.currentChunk,
    totalFiles: progress.totalChunks,
    eta: calculateETA(progress)
  });
});

sdk.projectSync.on('sync-completed', (result) => {
  if (result.success) {
    showSuccessMessage(`✅ Indexing completed: ${result.totalProcessed} files processed`);
  } else {
    showErrorMessage(`❌ Indexing failed: ${result.errors.join(', ')}`);
  }
});

// Периодическая проверка статуса (альтернатива WebSocket)
const interval = setInterval(async () => {
  const status = await sdk.projects.getDeltaSyncStatus(projectId);
  
  updateProgressUI({
    progress: status.progress,
    chunksProcessed: status.chunksProcessed,
    totalChunks: status.totalChunks,
    errors: status.errors
  });
  
  if (status.status === 'completed' || status.status === 'failed') {
    clearInterval(interval);
  }
}, 2000);

🔄 Delta-Chunking API (sdk.deltaSync)

Синхронизация с delta-chunking

// Инициализация синхронизации
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>

Типы данных

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; // Количество обработанных чанков
}

Примеры использования

// Полный цикл delta-chunking синхронизации
const syncResult = await sdk.deltaSync.initializeSync('project-id', {
  incremental: true,
  compression: true
});

console.log('Сессия синхронизации:', syncResult.sessionId);

// Подготовка и отправка чанков
const chunks = [
  {
    id: 'chunk-1',
    data: btoa('console.log("Hello World");'), // base64
    hash: 'sha256-hash',
    size: 26
  }
];

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)

AI-ассистент

// Отправка сообщения
sendMessage(messages: Message[], options?: ChatOptions): Promise<ChatResponse>

// Потоковый чат  
streamChat(messages: Message[], options?: StreamChatOptions): AsyncGenerator<ChatChunk>

Примеры использования

// Простой чат
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 || '');
}

🛠️ УПРАВЛЕНИЕ ДАННЫМИ ПРОЕКТА

🧹 Очистка и управление файлами

/**
 * 🧹 Очистка удаленных файлов (рекомендуется вызывать регулярно)
 */
async function cleanupDeletedFiles(projectId: string, workspacePath: string) {
  // Получить список активных файлов в workspace
  const activeFiles = await getWorkspaceFiles(workspacePath);
  
  // Очистить удаленные файлы из индекса
  const result = await sdk.cleanupDeletedFiles(projectId, activeFiles.map(file => ({
    filePath: file.path,
    fileHash: file.hash,
    lastModified: file.lastModified
  })));

  console.log(`🧹 Cleanup completed:`);
  console.log(`  - Removed from Qdrant: ${result.deletedFromQdrant} vectors`);
  console.log(`  - Removed from PostgreSQL: ${result.deletedFromPostgres} records`);
  console.log(`  - Active files: ${result.activeFiles}`);
}

/**
 * 🔄 Управление индексацией проекта
 */
async function manageProjectIndexing(projectId: string) {
  // Вариант 1: Сбросить индексацию (проект остается)
  const reset = await sdk.projects.resetIndexing(projectId);
  console.log(`✅ Индексация сброшена: ${reset.clearedData.vectorsDeleted} векторов очищено`);
  
  // Вариант 2: Перезапустить индексацию (сброс + подготовка)
  const restart = await sdk.projects.restartIndexing(projectId);
  if (restart.readyForNewSync) {
    console.log('✅ Готов к новой индексации');
    // Начать новую синхронизацию
    const hash = await computeMerkleRootHash(workspacePath);
    await sdk.projects.initializeDeltaSync(projectId, hash);
  }
  
  // Вариант 3: Очистить только удаленные файлы
  const result = await sdk.cleanupDeletedFiles(projectId, []); // Пустой список = удалить все
  console.log(`✅ Файлы очищены: ${result.deletedFromQdrant + result.deletedFromPostgres} записей`);
  
  // Вариант 4: Удалить проект полностью
  await sdk.projects.deleteProject(projectId);
  console.log('✅ Проект полностью удален из системы');
}

/**
 * 🔍 Диагностика состояния проекта
 */
async function diagnoseProject(projectId: string) {
  // Получить детальное состояние
  const state = await sdk.projects.getProjectState(projectId);
  console.log(`📊 Project State:`);
  console.log(`  - Name: ${state.projectName}`);
  console.log(`  - Total chunks: ${state.totalChunks}`);
  console.log(`  - Status: ${state.indexingStatus}`);
  console.log(`  - Last indexed: ${state.lastIndexedAt}`);
  console.log(`  - Merkle hash: ${state.merkleRootHash?.substring(0, 8)}...`);

  // Проверить прерванные сессии
  const recovery = await sdk.projects.getRecoveryStatus(projectId);
  if (recovery.hasInterruptedSession) {
    const info = recovery.recoveryInfo!;
    console.log(`⚠️ Interrupted session found:`);
    console.log(`  - Progress: ${info.progress.percentage}% (${info.progress.processed}/${info.progress.total})`);
    console.log(`  - Interrupted: ${info.interruptedAt}`);
    console.log(`  - Can resume: ${info.canResume}`);
    console.log(`  - Reason: ${info.resumeReason}`);
  }

  // Получить file mapping для отладки
  const mapping = await sdk.projects.getFilePathMapping(projectId);
  console.log(`📁 File mapping: ${mapping.files.length} files indexed`);
}

⚠️ Troubleshooting и восстановление

/**
 * 🚨 Экстренное восстановление при проблемах
 */
async function emergencyRecovery(projectId: string) {
  try {
    console.log('🚨 Starting emergency recovery...');
    
    // 1. Проверить состояние проекта
    const state = await sdk.projects.getProjectState(projectId);
    console.log(`Current state: ${state.indexingStatus}`);
    
    // 2. Отменить все прерванные сессии
    const cancelled = await sdk.projects.cancelRecovery(projectId);
    if (cancelled.success) {
      console.log('✅ Cancelled interrupted sessions');
    }
    
    // 3. Очистить поврежденные данные (если нужно)
    const cleaned = await sdk.cleanupDeletedFiles(projectId, []);
    console.log(`🧹 Cleaned ${cleaned.deletedFromQdrant + cleaned.deletedFromPostgres} corrupted records`);
    
    // 4. Начать полную ресинхронизацию
    const merkleHash = await computeMerkleRootHash(workspacePath);
    await sdk.projects.initializeDeltaSync(projectId, merkleHash);
    
    console.log('✅ Emergency recovery completed, full resync started');
    
  } catch (error) {
    console.error('❌ Emergency recovery failed:', error);
    
    // Последний шанс: удалить и пересоздать проект
    await sdk.projects.deleteProject(projectId);
    const newProject = await sdk.projects.createProject(projectName, projectPath);
    console.log(`🆕 Created new project: ${newProject.id}`);
  }
}

/**
 * 🔄 Принудительное возобновление (для сложных случаев)
 */
async function forceResumeSync(projectId: string) {
  const resumed = await sdk.projects.resumeSync(projectId, {
    forceResume: true,          // Игнорировать canResume=false
    skipDuplicates: true,       // Пропустить дубликаты
    continueFromLastBatch: false // Начать сначала, но с сохраненным прогрессом
  });

  if (resumed.success) {
    console.log('✅ Force resume successful');
    return resumed;
  } else {
    console.error('❌ Force resume failed, falling back to fresh sync');
    return await startFreshIndexing(projectId);
  }
}

💡 Рекомендации по использованию

Real-time уведомления

Для получения актуальных данных в реальном времени используйте WebSocket:

// ✅ Правильно: WebSocket для real-time статуса
await sdk.connectWebSocket();
sdk.projectSync.on('sync-status-update', (status) => {
  console.log(`Статус: ${status.status}, прогресс: ${status.progress}%`);
});

// ❌ Избегайте частых REST запросов
// setInterval(() => sdk.indexing.getStatus(id), 2000);

Обработка лимитов

SDK автоматически обрабатывает ограничения сервера. При превышении лимитов возвращается ошибка 429.

🔧 Обработка ошибок

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('Слишком много запросов, попробуйте позже');
  } else {
    console.error('Ошибка API:', error.message);
  }
}

// WebSocket ошибки
sdk.projectSync.on('error', (error) => {
  if (error.recoverable) {
    console.warn('Временная ошибка WebSocket:', error.error);
  } else {
    console.error('Критическая ошибка WebSocket:', error.error);
  }
});

🚀 Продвинутое использование

Настройка HTTP клиента

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'
  }
});

WebSocket с переподключением

const sdk = new CodeSolverSDK({
  baseURL: 'wss://api.codesolver.dev',
  webSocket: {
    enabled: true,
    maxRetries: 5,
    retryDelay: 3000,
    debug: true
  }
});

sdk.projectSync.on('connected', () => {
  console.log('WebSocket подключен');
});

sdk.projectSync.on('disconnected', (data) => {
  console.log('WebSocket отключен:', data.reason);
});

Delta-Chunking с шифрованием

const syncResult = await sdk.deltaSync.initializeSync('project-id', {
  incremental: true,
  compression: true,
  encryption: true
});

// Шифрование чанков на клиенте
const encryptedChunks = chunks.map(chunk => ({
  ...chunk,
  data: encrypt(chunk.data), // Ваша функция шифрования
  hash: sha256(chunk.data)
}));

await sdk.deltaSync.sendDeltaChunks('project-id', encryptedChunks);

📊 Мониторинг и диагностика

// Диагностика API
const diagnosis = await sdk.diagnoseAPI();
console.log('Статус API:', diagnosis);

// Health check
const health = await sdk.httpClient.get('/health');
console.log('Здоровье сервера:', health);

// Детальная информация о системе
const info = await sdk.httpClient.get('/health/info');
console.log('Информация о системе:', info);

🔄 Миграция с предыдущих версий

С версии 4.x на 5.x

// Старый способ (4.x)
const status = await sdk.projects.getIndexingStatus(projectId);

// Новый способ (5.x)
const status = await sdk.indexing.getStatus(projectId);

// Или лучше - WebSocket
sdk.projectSync.on('sync-status-update', (status) => {
  // Real-time статус
});

📝 Changelog

v5.2.0 (Latest) - КРИТИЧЕСКИЕ ИСПРАВЛЕНИЯ

  • 🚨 ОТКЛЮЧЕН waitForCompletion() - предотвращение polling
  • 🛡️ Усилен rate limiting статуса (2 запроса/минуту)
  • ✅ Принудительное использование WebSocket для real-time уведомлений
  • 📖 Обновлена документация с четкими инструкциями

v5.1.5

  • ✅ Исправлена документация - убраны детали внутренней реализации
  • ✅ Удалены несуществующие методы из документации
  • ✅ Сосредоточено только на пользовательском API

v5.1.4

  • ✅ Полная документация всех API методов
  • ✅ Добавлен IndexingApi для управления индексацией
  • ✅ Добавлен ProjectSyncClient для WebSocket уведомлений
  • ✅ Исправлена генерация URL в SearchApi
  • ✅ Добавлен метод semanticSearch
  • ✅ Добавлен метод findOrCreateProject
  • ✅ Улучшена обработка ошибок WebSocket
  • ✅ Обновлена документация и примеры

v5.0.0

  • 🚀 Полная переработка архитектуры
  • 🔌 WebSocket поддержка для real-time уведомлений
  • 🔄 Delta-chunking для эффективной синхронизации
  • 🛡️ Автоматическая обработка лимитов сервера

📋 QUICK REFERENCE - Управление индексацией

🔄 Основные методы (обязательные для VS Code расширения)

Метод Описание Когда использовать
getRecoveryStatus(projectId) Проверка прерванных сессий При открытии проекта
getProjectState(projectId, hash?) Проверка актуальности Перед синхронизацией
resumeSync(projectId, options?) Продолжить прерванную синхронизацию Кнопка "Continue"
cancelRecovery(projectId) Отменить прерванную сессию Кнопка "Start Fresh"
initializeDeltaSync(projectId, hash) Начать новую синхронизацию Новая индексация
finalizeDeltaSync(projectId) Завершить синхронизацию После отправки всех батчей
cleanupDeletedFiles(projectId, files) Очистить удаленные файлы При изменении файлов
resetIndexing(projectId) Сброс индексации Очистить данные, сохранить проект
restartIndexing(projectId) Перезапуск индексации Сброс + подготовка к новой
deleteProject(projectId) Полное удаление проекта Удалить проект и все данные

🎯 Полный список методов управления индексацией

// 🔍 ПРОВЕРКА СОСТОЯНИЯ
await sdk.projects.getProjectState(projectId, clientHash)     // Нужна ли синхронизация?
await sdk.projects.getRecoveryStatus(projectId)              // Есть ли прерванные сессии?
await sdk.projects.getDeltaSyncStatus(projectId)             // Текущий статус синхронизации

// 🚀 УПРАВЛЕНИЕ СИНХРОНИЗАЦИЕЙ  
await sdk.projects.initializeDeltaSync(projectId, hash)      // Начать новую синхронизацию
await sdk.projects.resumeSync(projectId, options)           // Продолжить прерванную
await sdk.projects.finalizeDeltaSync(projectId)             // Завершить синхронизацию
await sdk.projects.cancelDeltaSync(projectId)               // Отменить активную синхронизацию

// 🔄 УПРАВЛЕНИЕ ПРЕРЫВАНИЯМИ
await sdk.projects.cancelRecovery(projectId)                // Отменить восстановление

// 🧹 УПРАВЛЕНИЕ ДАННЫМИ
await sdk.cleanupDeletedFiles(projectId, activeFiles)       // Очистить удаленные файлы  
await sdk.projects.getFilePathMapping(projectId)           // Получить mapping файлов
await sdk.projects.resetIndexing(projectId)                // Сброс индексации (проект остается)
await sdk.projects.restartIndexing(projectId)              // Перезапуск индексации
await sdk.projects.deleteProject(projectId)                // ПОЛНОЕ удаление проекта

// 📊 МОНИТОРИНГ (WebSocket)
sdk.projectSync.on('sync-progress', callback)              // Real-time прогресс
sdk.projectSync.on('sync-completed', callback)             // Завершение синхронизации
sdk.projectSync.on('sync-status-update', callback)         // Обновления статуса

🎯 Cursor-like UX Pattern

// Главный workflow для VS Code расширения
async function openProject(projectPath: string) {
  // 1. Создать/найти проект
  const project = await sdk.projects.findOrCreateProject(projectPath, projectName);
  
  // 2. Проверить прерванные сессии
  const recovery = await sdk.projects.getRecoveryStatus(project.id);
  
  if (recovery.hasInterruptedSession) {
    // Показать диалог: "Continue indexing (67%)" или "Start fresh"
    const choice = await vscode.window.showInformationMessage(
      `Indexing was interrupted at ${recovery.recoveryInfo.progress.percentage}%. Continue?`,
      'Continue', 'Start Fresh'
    );
    
    if (choice === 'Continue') {
      await sdk.projects.resumeSync(project.id);
    } else {
      await sdk.projects.cancelRecovery(project.id);
    }
  }
  
  // 3. Проверить нужна ли синхронизация
  const hash = await computeMerkleRootHash(projectPath);
  const state = await sdk.projects.getProjectState(project.id, hash);
  
  if (state.syncRequired) {
    await sdk.projects.initializeDeltaSync(project.id, hash);
  }
}

🚨 Error Handling Best Practices

// Обработка всех возможных ошибок
try {
  await performDeltaSync(projectId, merkleHash);
  await sdk.projects.finalizeDeltaSync(projectId); // ОБЯЗАТЕЛЬНО!
} catch (error) {
  console.error('Sync failed:', error);
  
  // Система автоматически пометит сессию для восстановления
  // При следующем открытии пользователь увидит "Continue indexing"
}

📞 Поддержка

📄 Лицензия

MIT License - см. LICENSE файл.

🚀 Code Solver SDK v5.6.0 - Создано с ❤️ для разработчиков

🎯 НОВОЕ В v5.6.0: Advanced Indexing Management

  • 🔄 resetIndexing() - сброс индексации (проект остается)
  • 🚀 restartIndexing() - перезапуск индексации + подготовка
  • 🎯 Гибкий контроль - точное управление без удаления проекта
  • 📖 Enhanced UX - готовые паттерны для VS Code

🎯 v5.5.0: Resilient Sync System

  • 🔄 Cursor-like Recovery - восстановление прерванных сессий
  • 📊 Детальный прогресс - процент завершения и ETA
  • 🛡️ Автоматическая обработка прерываний - сеть, падения, ошибки
  • 🧹 Smart Cleanup - точная очистка удаленных файлов
  • 🎨 Production UX - готовые паттерны для VS Code расширений