JSPM

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

SDK for API integration

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 gateway
  • sdk.projectSync.subscribeToProject(projectId) подписывается на события проекта
  • Все события автоматически фильтруются по projectId
  • Fallback на HTTP polling если WebSocket недоступен

Авторизация:

  • Локальная разработка: apiKey достаточно для HTTP API
  • Production: OAuth access_token обязателен для WebSocket
  • Токен передается в Authorization header и автоматически используется для WebSocket
  • WebSocket передает токен через query параметр ?token=xxx