solver-sdk/docs/API_REFERENCE.md

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

# API Reference

В этом документе описаны основные классы и методы SDK.

## Содержание

- [CodeSolverSDK](#codesolversdk)
- [ChatApi](#chatapi)
- [ProjectsApi](#projectsapi)
- [SearchApi](#searchapi)
- [ReasoningApi](#reasoningapi)
- [WebSocketClient](#websocketclient)

## CodeSolverSDK

Основной класс SDK, предоставляющий доступ ко всем API.

### Конструктор

```javascript
const sdk = new CodeSolverSDK(options);
```

### Параметры

| Параметр | Тип | Описание | Обязательно |
|----------|-----|----------|-------------|
| `baseURL` | string | Базовый URL API | Да |
| `apiKey` | string | API ключ для авторизации | Нет |
| `wsURL` | string | URL для WebSocket соединений (если отличается от baseURL) | Нет |
| `timeout` | number | Таймаут для HTTP запросов (мс) | Нет |
| `headers` | object | Дополнительные HTTP заголовки | Нет |
| `websocket` | object | Настройки WebSocket соединений | Нет |
| `mode` | string | Режим работы SDK ('browser', 'node', 'auto') | Нет |

### Методы

#### `getWebSocketClient()`

Возвращает экземпляр WebSocket клиента для работы с соединениями.

```javascript
const wsClient = sdk.getWebSocketClient();
```

#### `checkHealth()`

Проверяет доступность API сервера.

```javascript
const isHealthy = await sdk.checkHealth();
```

#### `connect()`

Подключается к WebSocket серверу.

```javascript
await sdk.connect();
```

#### `disconnect()`

Отключается от WebSocket сервера.

```javascript
await sdk.disconnect();
```

#### `dispose()`

Освобождает ресурсы, включая WebSocket соединения.

```javascript
sdk.dispose();
```

#### `setApiKey(apiKey)`

Устанавливает новый API ключ для SDK.

```javascript
sdk.setApiKey('новый-api-ключ');
```

## ChatApi

API для работы с чатом и AI-моделями.

### Методы

#### `chat(messages, options)`

Отправляет запрос чата и возвращает полный ответ.

```javascript
const response = await sdk.chat.chat(
  messages,
  options
);
```

##### Параметры

| Параметр | Тип | Описание | Обязательно |
|----------|-----|----------|-------------|
| `messages` | Array | Массив сообщений для отправки модели | Да |
| `options` | Object | Параметры запроса (модель, temperature и т.д.) | Нет |

#### `streamChatWithThinking(messages, options, onEvent)`

Отправляет запрос чата в потоковом режиме с получением "мышления" модели.

```javascript
const response = await sdk.chat.streamChatWithThinking(
  messages,
  { 
    model: 'claude-3-7-sonnet-20240229',
    thinking: true,
    temperature: 0.7 
  },
  (eventType, data) => {
    if (eventType === 'thinking_delta') {
      console.log('Мышление:', data.thinking);
    } else if (eventType === 'text_delta') {
      console.log('Ответ:', data.text);
    }
  }
);
```

#### `connectWebSocket()`

Создает новое WebSocket соединение для потокового чата.

```javascript
await sdk.chat.connectWebSocket();
```

#### `getModels()`

Получает список доступных моделей.

```javascript
const models = await sdk.chat.getModels();
```

## ProjectsApi

API для работы с проектами.

### Методы

#### `getAllProjects()`

Получает список всех проектов.

```javascript
const projects = await sdk.projects.getAllProjects();
```

#### `getProject(projectId)`

Получает информацию о проекте по ID.

```javascript
const project = await sdk.projects.getProject('project-id');
```

#### `createProject(name, path, options)`

Создаёт новый проект.

```javascript
const project = await sdk.projects.createProject('Мой проект', '/path/to/project', {
  excludePatterns: ['node_modules', '.git']
});
```

#### `updateProject(projectId, data)`

Обновляет проект.

```javascript
await sdk.projects.updateProject('project-id', { name: 'Новое имя' });
```

#### `deleteProject(projectId)`

Удаляет проект.

```javascript
await sdk.projects.deleteProject('project-id');
```

#### `indexProject(projectId)`

Запускает индексацию проекта.

```javascript
await sdk.projects.indexProject('project-id');
```

#### `getOrCreateProject(path, name)`

Получает существующий проект по пути или создает новый, если проект не найден.

```javascript
const project = await sdk.projects.getOrCreateProject('/path/to/project', 'Название проекта');
```

#### `indexProjectByPath(path, options)`

Индексирует проект по указанному пути. Если проект не существует, он будет создан автоматически.

```javascript
const result = await sdk.projects.indexProjectByPath('/path/to/project', {
  name: 'Название проекта',
  forceFull: true, // принудительная полная индексация
  excludePatterns: ['node_modules', '.git'] // паттерны для исключения
});
```

#### `createAndIndexProject(path, options)`

Комбинированный метод для создания (если не существует) и индексации проекта в одной операции.

```javascript
const result = await sdk.projects.createAndIndexProject('/path/to/project', {
  name: 'Название проекта',
  forceFull: false,
  excludePatterns: ['node_modules', '.git']
});
```

#### `connectWebSocket()`

Подключается к WebSocket для отслеживания индексации.

```javascript
await sdk.projects.connectWebSocket();
```

#### `disconnectWebSocket()`

Отключается от WebSocket индексации.

```javascript
await sdk.projects.disconnectWebSocket();
```

#### `on(event, callback)`

Добавляет обработчик события для индексации.

```javascript
sdk.projects.on('indexing_progress', (data) => {
  console.log(`Прогресс: ${data.progress}%`);
});
```

#### `stopIndexing(projectId)`

Останавливает индексацию проекта.

```javascript
await sdk.projects.stopIndexing('project-id');
```

#### `getIndexingStatus(projectId)`

Получает статус индексации проекта.

```javascript
const status = await sdk.projects.getIndexingStatus('project-id');
```

## SearchApi

API для поиска кода.

### Методы

#### `searchCode(projectId, options)`

Выполняет поиск кода в проекте.

```javascript
const results = await sdk.search.searchCode('project-id', {
  query: 'function example',
  limit: 10
});
```

#### `semanticSearch(projectId, options)`

Выполняет семантический поиск в проекте.

```javascript
const results = await sdk.search.semanticSearch('project-id', {
  query: 'функция для обработки HTTP запросов',
  limit: 10,
  includeContent: true
});
```

## ReasoningApi

API для работы с рассуждениями.

### Методы

#### `createReasoning(options)`

Создаёт новое рассуждение.

```javascript
const reasoning = await sdk.reasoning.createReasoning({
  projectId: 'project-id',
  query: 'Объясни этот проект'
});
```

#### `getReasoning(reasoningId)`

Получает информацию о рассуждении.

```javascript
const reasoning = await sdk.reasoning.getReasoning('reasoning-id');
```

#### `connectWebSocket(reasoningId)`

Подключается к WebSocket для отслеживания рассуждений.

```javascript
await sdk.reasoning.connectWebSocket('reasoning-id');
```

#### `startReasoning(reasoningId)`

Запускает процесс рассуждения.

```javascript
await sdk.reasoning.startReasoning('reasoning-id');
```

#### `on(event, callback)`

Добавляет обработчик события для рассуждений.

```javascript
sdk.reasoning.on('thinking', (data) => {
  console.log('Мышление:', data.content);
});

sdk.reasoning.on('complete', (data) => {
  console.log('Результат:', data.content);
});
```

## WebSocketClient

Клиент для работы с WebSocket соединениями. Получается через `sdk.getWebSocketClient()`.

### Методы

#### `connectToReasoning(reasoningId)`

Подключается к namespace рассуждений.

```javascript
await wsClient.connectToReasoning('reasoning-id');
```

#### `connectToIndexing(projectId)`

Подключается к namespace индексации.

```javascript
await wsClient.connectToIndexing('project-id');
```

#### `disconnect(namespace)`

Отключается от определенного namespace.

```javascript
await wsClient.disconnect(WebSocketNamespace.REASONING);
```

#### `disconnectAll()`

Отключается от всех namespace.

```javascript
await wsClient.disconnectAll();
```

#### `isConnected(namespace)`

Проверяет подключение к определенному namespace.

```javascript
const isConnected = wsClient.isConnected(WebSocketNamespace.REASONING);
```

#### `isConnectedToReasoning()`

Проверяет подключение к namespace рассуждений.

```javascript
const isConnected = wsClient.isConnectedToReasoning();
```

#### `isConnectedToIndexing()`

Проверяет подключение к namespace индексации.

```javascript
const isConnected = wsClient.isConnectedToIndexing();
```

#### `on(event, callback, namespace)`

Добавляет обработчик события для определенного namespace.

```javascript
wsClient.on('thinking', (data) => {
  console.log('Мышление:', data);
}, WebSocketNamespace.REASONING);
```