JSPM

  • Created
  • Published
  • Downloads 11
  • Score
    100M100P100Q82320F
  • License MIT

SDK for API integration (Pure Cloud-First - Delta Chunking only)

Package Exports

  • solver-sdk

Readme

Code Solver SDK v6.2.2

Backend SDK для интеграции с Code Solver API

📦 Установка

npm install solver-sdk

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

Локальная разработка

import { CodeSolverSDK } from 'solver-sdk';

const sdk = await CodeSolverSDK.create({
  baseURL: 'http://localhost:3000',
  apiKey: 'your-api-key'
});

Production с OAuth

const sdk = await CodeSolverSDK.create({
  baseURL: 'https://workai.su/api/v1',
  headers: { Authorization: `Bearer ${oauth_token}` },
  webSocket: { enabled: true }
});

🔑 Динамическое обновление токена (v6.1.4+)

const sdk = await CodeSolverSDK.create({
  baseURL: 'https://workai.su/api/v1',
  getAuthToken: async () => {
    if (authManager.isTokenExpired()) {
      await authManager.refreshAccessToken();
    }
    return authManager.getAccessToken();
  }
});

📖 API Reference

Projects API (sdk.projects)

// Управление проектами
getAllProjects(): Promise<Project[]>
getProject(projectId: string): Promise<Project>
createProject(name: string, data?: any): Promise<Project>
findOrCreateProject(projectName: string): Promise<Project>
deleteProject(projectId: string): Promise<void>

// Состояние и синхронизация
getProjectState(projectId: string, clientRootHash?: string): Promise<ProjectState>
getIndexingStatus(projectId: string): Promise<any>
cancelIndexing(projectId: string): Promise<boolean>
resetIndexing(projectId: string): Promise<any>
restartIndexing(projectId: string): Promise<any>
clearIndexingError(projectId: string): Promise<boolean>

// 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>

// Диагностика
getFilePathMapping(projectId: string): Promise<any>

Delta Manager API (sdk.deltaManager)

// Синхронизация чанков (автоматическая инициализация + батчинг + финализация)
// ✨ v6.2.2+: автоматически передает totalFiles для user-friendly прогресса
syncEncryptedChunks(
  projectId: string, 
  encryptedChunks: any[], 
  rootHash: string, 
  options?: { batchSize?: number; onProgress?: (current, total) => void }
): Promise<any>

getSyncStatus(projectId: string): Promise<SyncStatus>
cancelSync(projectId: string): Promise<boolean>
cleanupDeletedFiles(projectId: string, activeFiles: any[]): Promise<any>

Chat API (sdk.chat)

// Основные методы
chat(messages: ChatMessage[], options?: ChatOptions): Promise<ChatResponse>
chatCompletion(messages: ChatMessage[], options?: ChatOptions): Promise<ChatResponse>
streamChat(messages: ChatMessage[], options?: ChatStreamOptions): AsyncGenerator<ChatStreamChunk>
streamPrompt(prompt: string, options?: ChatStreamOptions): AsyncGenerator<ChatStreamChunk>
sendContinuation(messages: ChatMessage[], options?: ChatStreamOptions): AsyncGenerator<ChatStreamChunk>

// Failover
chatWithRegionFailover(messages: ChatMessage[], options?: ChatOptions): Promise<ChatResponse>
sendPromptWithRegionFailover(prompt: string, options?: ChatOptions): Promise<string>
checkAvailability(): Promise<boolean>

Search API (sdk.search)

searchCode(projectId: string, query: string, options?: any): Promise<any[]>
searchFunctions(projectId: string, query: string, options?: any): Promise<any[]>
getFunctionStats(projectId: string): Promise<{stats: {totalFunctions: number}}>
semanticSearch(projectId: string, query: string, options?: any): Promise<any[]>

Models API (sdk.models)

getAllModels(): Promise<any[]>
getProviderModels(providerId: string): Promise<any>
getAvailableModels(): Promise<any[]>
getModelInfo(modelId: string): Promise<any>

Updates API (sdk.updates)

checkForUpdates(options: UpdateCheckOptions): Promise<UpdateResponse>
getChangelog(version: string, locale: string): Promise<string>
getLatestVersion(channel?: string): Promise<LatestVersionInfo>
sendStats(event: UpdateStatsEvent): Promise<void>
checkAvailability(): Promise<boolean>

WebSocket API (sdk.projectSync)

// Подключение
await sdk.connectWebSocket()
sdk.disconnectWebSocket()
sdk.isWebSocketConnected

// Подписка
sdk.projectSync.subscribeToProject(projectId)
sdk.projectSync.unsubscribeFromProject(projectId)

// События
sdk.projectSync.on('sync-status-update', callback)  // {projectId, status, timestamp}
sdk.projectSync.on('sync-progress', callback)       // {projectId, progress, stage, currentChunk, totalChunks}
sdk.projectSync.on('sync-completed', callback)      // {projectId, processedChunks, embeddingsCreated}
sdk.projectSync.on('sync-error', callback)          // {projectId, error, timestamp}

🔧 Основные принципы

Архитектура (Pure Cloud-First)

  • Backend SDK — только HTTP API клиент, НЕ работает с файловой системой
  • Client Extension — сканирует файлы, создает chunks, вычисляет hashes
  • Только Delta-Chunking — filesystem индексация удалена

✅ Индексация проекта

// ✅ ЕДИНСТВЕННЫЙ способ индексации (v6.2.2+):
await sdk.deltaManager.syncEncryptedChunks(projectId, chunks, rootHash, {
  batchSize: 50,
  onProgress: (current, total) => console.log(`${current}/${total}`)
});

// ❌ УДАЛЕНО: sdk.projects.startIndexing() - больше не существует
// ❌ УДАЛЕНО: filesystem индексация на сервере

Важно: Client Extension создает chunks → SDK отправляет на сервер → Сервер индексирует

Session Recovery

// Всегда проверять при старте проекта
const recovery = await sdk.projects.getRecoveryStatus(projectId);
if (recovery.needsRecovery) {
  // ✨ v6.2.2+: показывает "480 из 642 файлов" вместо "0 из 0"
  // Показать диалог: Continue (67%) — 480/642 files | Start Fresh
  await sdk.projects.resumeSync(projectId);  // или cancelRecovery()
}

WebSocket

  • Требуется OAuth токен в production
  • Автоматическое переподключение при разрыве
  • События фильтруются по projectId
  • Fallback на HTTP polling если недоступен

Авторизация

  • Локально: apiKey для HTTP API
  • Production: OAuth access_token для HTTP + WebSocket
  • v6.1.4+: getAuthToken() для автоматического обновления токенов

📝 Примеры

Базовый workflow

const sdk = await CodeSolverSDK.create({
  baseURL: 'https://workai.su/api/v1',
  getAuthToken: () => authManager.getAccessToken()
});

// 1. Найти/создать проект
const project = await sdk.projects.findOrCreateProject('/path/to/project');

// 2. Проверить recovery
const recovery = await sdk.projects.getRecoveryStatus(project.id);
if (recovery.needsRecovery) {
  await sdk.projects.resumeSync(project.id);
  return;
}

// 3. Проверить нужна ли синхронизация
const state = await sdk.projects.getProjectState(project.id, clientRootHash);
if (!state.syncRequired) {
  console.log('Проект синхронизирован');
  return;
}

// 4. Подключить WebSocket для прогресса
await sdk.connectWebSocket();
sdk.projectSync.subscribeToProject(project.id);
sdk.projectSync.on('sync-progress', (data) => {
  console.log(`Прогресс: ${data.progress}%`);
});

// 5. Синхронизировать
await sdk.deltaManager.syncEncryptedChunks(project.id, chunks, rootHash);

// 6. Поиск по проекту
const results = await sdk.search.searchCode(project.id, 'function handleClick');

Chat с streaming

for await (const chunk of sdk.chat.streamChat(messages, { model: 'claude-3-5-sonnet' })) {
  if (chunk.type === 'content_block_delta') {
    process.stdout.write(chunk.delta.text);
  }
}

🔄 Миграция на v6.2.2+

Что изменилось

BREAKING CHANGES:

  • ❌ Удален sdk.projects.startIndexing() - использовался для filesystem индексации
  • ❌ Удален sdk.indexing.* API - был удален в v5.x
  • ✅ Используйте только sdk.deltaManager.syncEncryptedChunks()

Как мигрировать

// ❌ СТАРЫЙ КОД (НЕ РАБОТАЕТ):
// await sdk.projects.startIndexing(projectId, { force: true });

// ✅ НОВЫЙ КОД:
// Client Extension создает chunks
const chunks = await clientExtension.scanAndCreateChunks();
const rootHash = clientExtension.calculateMerkleRoot();

// SDK отправляет на сервер
await sdk.deltaManager.syncEncryptedChunks(projectId, chunks, rootHash);

Почему: Pure Cloud-First архитектура. Сервер не сканирует файлы - данные приходят от клиента.

📚 Дополнительно

TypeScript типы

SDK полностью типизирован. Импортируйте интерфейсы:

import { ChatMessage, ChatOptions, Project, ProjectState } from 'solver-sdk';

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

try {
  await sdk.projects.getProject(projectId);
} catch (error) {
  console.error(`[HTTP ${error.status}] ${error.message}`);
  // v6.1.3+: читаемые сообщения ошибок вместо [object Object]
}

Debug режим

const sdk = await CodeSolverSDK.create({
  baseURL: 'https://workai.su/api/v1',
  debug: 'verbose',  // silent | error | warn | info | debug | verbose
  webSocket: { debug: true }
});

📄 License

MIT