solver-sdk 6.0.2 → 6.0.3

package/README.md

@@ -23,58 +23,82 @@ const sdk = new CodeSolverSDK({
 
 ### Projects API (`sdk.projects`)
 ```typescript
+// Базовое управление проектами
 createProject(name: string, data?: any): Promise<Project>
 getAllProjects(): Promise<Project[]>
 getProject(projectId: string): Promise<Project>
-findOrCreateProject(projectName: string): Promise<Project>
+findOrCreateProject(projectName: string): Promise<Project>  // Найти существующий или создать новый
 deleteProject(projectId: string): Promise<void>
 
-getProjectState(projectId: string, clientRootHash?: string): Promise<ProjectState>
+// Проверка состояния синхронизации
+getProjectState(projectId: string, clientRootHash?: string): Promise<ProjectState>  // Передать clientRootHash для проверки нужна ли синхронизация
 getIndexingStatus(projectId: string): Promise<any>
 startIndexing(projectId: string, options?: any): Promise<any>
 cancelIndexing(projectId: string): Promise<boolean>
-resetIndexing(projectId: string): Promise<any>
-restartIndexing(projectId: string): Promise<any>
-
-getRecoveryStatus(projectId: string): Promise<any>
-resumeSync(projectId: string, options?: any): Promise<any>
-cancelRecovery(projectId: string): Promise<any>
-initializeDeltaSync(projectId: string, clientRootHash: string): Promise<any>
-
-sendInitialSync(projectId: string, request: any): Promise<any>
-sendDeltaSync(projectId: string, batchRequest: any): Promise<any>
-getDeltaSyncStatus(projectId: string): Promise<any>
-finalizeDeltaSync(projectId: string): Promise<any>
+resetIndexing(projectId: string): Promise<any>        // Очистить индекс, проект остается
+restartIndexing(projectId: string): Promise<any>      // Очистить + подготовить к новой индексации
+
+// Session Recovery - восстановление прерванных синхронизаций
+getRecoveryStatus(projectId: string): Promise<any>    // Проверить есть ли прерванные сессии при старте
+resumeSync(projectId: string, options?: any): Promise<any>  // Продолжить прерванную синхронизацию
+cancelRecovery(projectId: string): Promise<any>       // Отменить восстановление, начать заново
+initializeDeltaSync(projectId: string, clientRootHash: string): Promise<any>  // ОБЯЗАТЕЛЬНО вызвать перед отправкой chunks
+
+// Delta Sync API - отправка готовых chunks
+sendInitialSync(projectId: string, request: any): Promise<any>      // Инициализация с clientRootHash
+sendDeltaSync(projectId: string, batchRequest: any): Promise<any>    // Отправка батча зашифрованных chunks
+getDeltaSyncStatus(projectId: string): Promise<any>                  // Статус текущей синхронизации
+finalizeDeltaSync(projectId: string): Promise<any>                   // ОБЯЗАТЕЛЬНО вызвать после всех batches
 cancelDeltaSync(projectId: string): Promise<any>
 
-getFilePathMapping(projectId: string): Promise<any>
+// Диагностика
+getFilePathMapping(projectId: string): Promise<any>   // Получить маппинг обфусцированных путей с сервера
 ```
 
 ### Delta Manager API (`sdk.deltaManager`)
 ```typescript
-syncEncryptedChunks(projectId: string, encryptedChunks: any[], rootHash: string, options?: any): Promise<any>
-getSyncStatus(projectId: string): Promise<any>
+// Отправка готовых зашифрованных chunks (Client Extension уже подготовил)
+syncEncryptedChunks(projectId: string, encryptedChunks: any[], rootHash: string, options?: any): Promise<any>  // Chunks должны быть ready-to-send
+getSyncStatus(projectId: string): Promise<any>      // Статус delta-chunking процесса
 cancelSync(projectId: string): Promise<boolean>
 ```
 
 ### Chat API (`sdk.chat`)
 ```typescript
-chat(messages: any[], options?: any): Promise<any>
-chatStream(messages: any[], options?: any): Promise<AsyncIterable<any>>
-cancelCurrentRequest(): void
+chat(messages: any[], options?: any): Promise<any>                              // Обычный запрос-ответ
+chatStream(messages: any[], options?: any): Promise<AsyncIterable<any>>         // Потоковый чат (streaming)
+cancelCurrentRequest(): void                                                    // Прервать активный запрос
 ```
 
 ### Search API (`sdk.search`)
 ```typescript
-search(query: string, options?: any): Promise<any[]>
-searchThenFetch(query: string, options?: any): Promise<any>
+search(query: string, options?: any): Promise<any[]>                           // Векторный поиск по индексу
+searchThenFetch(query: string, options?: any): Promise<any>                    // Поиск + загрузка полного контекста
 ```
 
 ### WebSocket API (`sdk.projectSync`)
 ```typescript
-connectProjectSync(projectId: string): Promise<void>
-onSyncProgress(callback: Function): void
-onSyncCompleted(callback: Function): void
-onSyncError(callback: Function): void
-disconnectWebSocket(): void
-```
+// Real-time уведомления о синхронизации
+connectProjectSync(projectId: string): Promise<void>         // Подключиться к конкретному проекту
+onSyncProgress(callback: Function): void                      // Событие: прогресс индексации (%)
+onSyncCompleted(callback: Function): void                     // Событие: синхронизация завершена
+onSyncError(callback: Function): void                         // Событие: ошибка синхронизации
+disconnectWebSocket(): void                                   // Отключить WebSocket
+```
+
+## ⚠️ Важные особенности
+
+### Архитектурные принципы:
+- **Backend SDK** = только HTTP API клиент, НЕ работает с файловой системой
+- **Client Extension** сканирует файлы, вычисляет hashes, создает chunks
+- **Обязательная последовательность**: `initializeDeltaSync()` → `sendDeltaSync()` → `finalizeDeltaSync()`
+
+### Session Recovery:
+- Всегда проверяйте `getRecoveryStatus()` при старте проекта
+- Показывайте пользователю диалог "Continue (67%) | Start Fresh"
+- `resumeSync()` продолжит с последнего batch, `cancelRecovery()` начнет заново
+
+### WebSocket для real-time:
+- Используйте WebSocket вместо polling для статуса
+- `connectProjectSync(projectId)` подключает к конкретному проекту
+- Все события автоматически фильтруются по projectId

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solver-sdk",
-  "version": "6.0.2",
+  "version": "6.0.3",
   "description": "SDK for API integration",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",