Package Exports
- solver-sdk
Readme
Code Solver SDK v6.0.3
Backend SDK для интеграции с Code Solver API
📦 Установка
npm install solver-sdk🚀 Инициализация
Базовая инициализация (локальная разработка)
import { CodeSolverSDK } from 'solver-sdk';
const sdk = new CodeSolverSDK({
baseURL: 'http://localhost:3000',
apiKey: 'your-api-key'
});Production инициализация с OAuth (для WebSocket)
import { CodeSolverSDK } from 'solver-sdk';
// ✅ OAuth токен требуется для WebSocket в production
const sdk = await CodeSolverSDK.create({
baseURL: 'https://workai.su/api/v1',
headers: {
Authorization: 'Bearer your_oauth_access_token' // OAuth токен
},
webSocket: {
enabled: true, // Включить WebSocket для real-time уведомлений
debug: false, // Отключить debug логи в production
connectionTimeout: 10000,
maxRetries: 3
}
});
// Проверка здоровья API
const isHealthy = await sdk.checkHealth();
console.log('API доступен:', isHealthy);Получение OAuth токена
// 1. Получение access token через OAuth flow
const response = await fetch('https://workai.su/api/v1/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
grant_type: 'authorization_code',
code: 'authorization_code_from_oauth_flow',
client_id: 'your_client_id',
client_secret: 'your_client_secret'
})
});
const { access_token, refresh_token } = await response.json();
// 2. Использование токена в SDK
const sdk = await CodeSolverSDK.create({
baseURL: 'https://workai.su/api/v1',
headers: {
Authorization: `Bearer ${access_token}`
}
});📖 API Reference
Projects API (sdk.projects)
// Базовое управление проектами
createProject(name: string, data?: any): Promise<Project>
getAllProjects(): Promise<Project[]>
getProject(projectId: string): Promise<Project>
findOrCreateProject(projectName: string): Promise<Project> // Найти существующий или создать новый
deleteProject(projectId: string): Promise<void>
// Проверка состояния синхронизации
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> // Очистить + подготовить к новой индексации
// 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
// Статус и управление
clearIndexingError(projectId: string): Promise<boolean> // Очистить ошибку индексации
// Диагностика
getFilePathMapping(projectId: string): Promise<any> // Получить маппинг обфусцированных путей с сервераDelta Manager API (sdk.deltaManager)
// 🚀 ЕДИНСТВЕННЫЙ ПОДХОД: один вызов делает всё автоматически
syncEncryptedChunks(projectId: string, encryptedChunks: any[], rootHash: string, options?: any): Promise<any> // Автоматическая инициализация + батчинг + финализация
getSyncStatus(projectId: string): Promise<any> // Статус delta-chunking процесса
cancelSync(projectId: string): Promise<boolean>
cleanupDeletedFiles(projectId: string, activeFiles: any[]): Promise<any> // Очистить удаленные файлы из индексаChat API (sdk.chat)
// Основные методы
chat(messages: any[], options?: any): Promise<any> // Обычный запрос-ответ
chatCompletion(messages: any[], options?: any): Promise<any> // Алиас для chat()
streamChat(messages: any[], options?: any): Promise<AsyncIterable<any>> // Потоковый чат (streaming)
streamPrompt(prompt: string, options?: any): Promise<AsyncIterable<any>> // Потоковый промпт
sendContinuation(messages: any[], options?: any): Promise<AsyncIterable<any>> // Continuation для interleaved thinking
// Failover и проверки
chatWithRegionFailover(messages: any[], options?: any): Promise<any> // Чат с переключением регионов
sendPromptWithRegionFailover(prompt: string, options?: any): Promise<string> // Промпт с переключением регионов
checkAvailability(): Promise<boolean> // Проверить доступность сервисаSearch API (sdk.search)
search(query: string, options?: any): Promise<any[]> // Векторный поиск по индексу
searchThenFetch(query: string, options?: any): Promise<any> // Поиск + загрузка полного контекстаWebSocket API (sdk.projectSync)
// Real-time уведомления о синхронизации проектов
// Подключение к WebSocket (требуется OAuth токен)
await sdk.connectWebSocket(); // Подключиться к WebSocket gateway
sdk.projectSync.subscribeToProject(projectId); // Подписаться на события проекта
// События синхронизации
sdk.projectSync.on('sync-status-update', callback); // Обновление статуса (initializing/processing/completed)
sdk.projectSync.on('sync-progress', callback); // Детальный прогресс (%, stage)
sdk.projectSync.on('sync-completed', callback); // Завершение синхронизации
sdk.projectSync.on('sync-error', callback); // Ошибка синхронизации
// Управление подключением
sdk.disconnectWebSocket(); // Отключить WebSocket
sdk.isWebSocketConnected; // Проверка статуса подключенияПример использования WebSocket:
import { CodeSolverSDK } from 'solver-sdk';
// Инициализация с OAuth токеном
const sdk = await CodeSolverSDK.create({
baseURL: 'https://workai.su/api/v1',
headers: {
Authorization: 'Bearer your_oauth_access_token' // ✅ OAuth токен обязателен
},
webSocket: {
enabled: true, // Включить WebSocket (по умолчанию true)
debug: true // Логи для отладки
}
});
// Подключение к WebSocket
await sdk.connectWebSocket();
// Подписка на события проекта
sdk.projectSync.on('sync-progress', (data) => {
console.log(`Прогресс: ${data.progress}% - ${data.stage}`);
console.log(`Чанки: ${data.currentChunk}/${data.totalChunks}`);
});
sdk.projectSync.on('sync-completed', (data) => {
console.log('✅ Синхронизация завершена!');
console.log(`Обработано чанков: ${data.processedChunks}`);
console.log(`Создано эмбеддингов: ${data.embeddingsCreated}`);
});
sdk.projectSync.on('sync-error', (error) => {
console.error(`❌ Ошибка: ${error.error}`);
});
// Подписаться на проект
sdk.projectSync.subscribeToProject(projectId);
// Начать синхронизацию (WebSocket автоматически получит уведомления)
await sdk.deltaManager.syncEncryptedChunks(projectId, chunks, rootHash);
// Отключение
sdk.disconnectWebSocket();⚠️ Важные особенности
Архитектурные принципы:
- Backend SDK = только HTTP API клиент, НЕ работает с файловой системой
- Client Extension сканирует файлы, вычисляет hashes, создает chunks
Единственный способ синхронизации:
// ✅ ПРОСТОЙ И ЕДИНСТВЕННЫЙ ПОДХОД:
const result = await sdk.deltaManager.syncEncryptedChunks(
projectId,
chunks,
rootHash,
{
batchSize: 50, // Размер батчей (по умолчанию 50)
onProgress: (current, total) => {...} // Колбэк прогресса
}
);Session Recovery:
- Всегда проверяйте
getRecoveryStatus()при старте проекта - Показывайте пользователю диалог "Continue (67%) | Start Fresh"
resumeSync()продолжит с последнего batch,cancelRecovery()начнет заново
WebSocket для real-time:
- Требуется OAuth токен в production для авторизации WebSocket
- Используйте WebSocket вместо polling для статуса индексации
sdk.connectWebSocket()подключает к WebSocket gatewaysdk.projectSync.subscribeToProject(projectId)подписывается на события проекта- Все события автоматически фильтруются по projectId
- Fallback на HTTP polling если WebSocket недоступен
Авторизация:
- Локальная разработка:
apiKeyдостаточно для HTTP API - Production: OAuth
access_tokenобязателен для WebSocket - Токен передается в
Authorizationheader и автоматически используется для WebSocket - WebSocket передает токен через query параметр
?token=xxx