JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 14
  • Score
    100M100P100Q82171F
  • 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 } // Включить WebSocket для real-time уведомлений
});

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

// Создание проекта
const project = await sdk.projects.createProject('My Project', '/path/to/project');

// Запуск индексации с real-time статусом
const indexResult = await sdk.indexing.indexProject('/path', 'My Project');

// Подписка на real-time уведомления
sdk.projectSync.on('sync-status-update', (status) => {
  console.log(`Индексация: ${status.progress}%`);
});

// Поиск по коду
const results = await sdk.search.searchCode(project.id, {
  query: 'function authenticate',
  limit: 10
});

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

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

// Создание нового проекта
const project = await sdk.projects.createProject(
  'My Web App',
  '/Users/dev/my-web-app',
  { description: 'React приложение' }
);

// Получение всех проектов пользователя
const projects = await sdk.projects.getAllProjects();
console.log(`У вас ${projects.length} проектов`);

// Поиск существующего или создание нового
const project = await sdk.projects.findOrCreateProject(
  '/path/to/project',
  'My Project',
  'Описание проекта'
);

🚀 Indexing API (sdk.indexing)

Управление индексацией

// Создание проекта и запуск индексации
indexProject(projectPath: string, projectName: string, description?: string): Promise<IndexProjectResult>

// Получение статуса индексации
getStatus(projectId: string): Promise<IndexingStatus>

// ❌ ОТКЛЮЧЕН: waitForCompletion() - используйте WebSocket!

// Отмена индексации
cancelIndexing(projectId: string): Promise<void>

// Перезапуск индексации
restartIndexing(projectId: string): Promise<IndexingStatus>

Типы данных

interface IndexingStatus {
  status: string;           // 'pending' | 'processing' | 'completed' | 'failed'
  progress: number;         // Прогресс 0-100
  totalFiles?: number;      // Общее количество файлов
  processedFiles?: number;  // Обработано файлов
  currentFile?: string;     // Текущий обрабатываемый файл
  error?: string;          // Сообщение об ошибке
  updatedAt?: string;      // Время последнего обновления
}

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

// Запуск индексации
const result = await sdk.indexing.indexProject(
  '/Users/dev/my-project',
  'My Project'
);
console.log('Project ID:', result.projectId);

// Получение статуса (единичный запрос)
const status = await sdk.indexing.getStatus(result.projectId);
console.log(`Прогресс: ${status.progress}%`);

// ⚠️ ВАЖНО: Для real-time статуса используйте WebSocket!
sdk.projectSync.on('sync-status-update', (status) => {
  console.log(`Статус обновлен: ${status.status}, прогресс: ${status.progress}%`);
});

🔍 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();

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

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

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 для эффективной синхронизации
  • 🛡️ Автоматическая обработка лимитов сервера

📞 Поддержка

📄 Лицензия

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

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