# Solver SDK

SDK для интеграции с Code Solver Backend API. Поддерживает работу как в браузере, так и в Node.js.

<p align="center">
  <a href="https://www.npmjs.com/package/solver-sdk"><img src="https://img.shields.io/npm/v/solver-sdk.svg" alt="NPM Version" /></a>
  <a href="https://www.npmjs.com/package/solver-sdk"><img src="https://img.shields.io/npm/dm/solver-sdk.svg" alt="NPM Downloads" /></a>
  <a href="https://github.com/code-solver/browser-sdk/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/solver-sdk.svg" alt="License" /></a>
</p>

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

- [Основные возможности](#основные-возможности)
- [Установка](#установка)
- [Быстрый старт](#быстрый-старт)
  - [CommonJS (Node.js)](#в-среде-commonjs-nodejs)
  - [ESM (Node.js)](#в-среде-esm-nodejs)
  - [Браузер](#в-браузере)
- [API](#api)
  - [Основные компоненты](#основные-компоненты)
  - [Опции SDK](#опции-sdk)
- [Продвинутые функции](#продвинутые-функции)
  - [Проекты и индексация](#работа-с-проектами)
  - [Поиск кода](#поиск-кода)
  - [WebSocket и подписки](#работа-с-рассуждениями-через-websocket)
  - [Работа с зависимостями](#api-для-работы-с-зависимостями)
  - [Потоковая передача мышления](#потоковая-передача-мышления)
  - [Региональные эндпоинты](#работа-с-региональными-эндпоинтами)
- [Примеры](#примеры)
- [Совместимость](#совместимость)
- [Разработка и тестирование](#разработка-и-тестирование)
- [Документация](#документация)
- [Лицензия](#лицензия)

## Основные возможности

- **Кросс-платформенность**: совместимость с ESM, CommonJS, браузером и Node.js
- **Типизация**: полная поддержка TypeScript
- **Расширенная работа с WebSocket**:
  - Автоматический ping/pong механизм для мониторинга соединений
  - Сбор статистики времени отклика (RTT) и состояния соединений
  - Интеллектуальный механизм переподключения с экспоненциальной задержкой
  - Настраиваемый мониторинг здоровья соединения
- **Потоковая передача мышления**:
  - Метод `streamChatWithThinking()` для потоковой передачи процесса мышления модели
  - Полная поддержка официального Anthropic API со всеми типами блоков контента
  - Единый стандартизированный формат событий
- **Работа с регионами**:
  - Поддержка региональных эндпоинтов Anthropic API
  - Автоматическое переключение между регионами при ошибках
  - Поддержка регионов: 'us-east-1', 'eu-west-1', 'ap-southeast-2'
- **Индексация и поиск**:
  - Инкрементальная индексация отдельных файлов
  - Семантический поиск кода
- **Обработка ошибок**:
  - Интеллектуальные повторные попытки
  - Обширная диагностика соединений

## Установка

```bash
npm install solver-sdk
```

## Быстрый старт

### В среде CommonJS (Node.js)

```javascript
const { CodeSolverSDK } = require('solver-sdk');

// Создание экземпляра SDK
const sdk = new CodeSolverSDK({
  baseURL: 'https://localhost:3000',
  apiKey: 'your-api-key'
});

// Использование SDK
async function example() {
  // Проверка соединения с сервером
  const isHealthy = await sdk.checkHealth();
  console.log('Сервер доступен:', isHealthy);
  
  // Получение списка моделей
  const models = await sdk.reasoning.getModels();
  console.log('Доступные модели:', models);
}

example().catch(console.error);
```

### В среде ESM (Node.js)

```javascript
import { CodeSolverSDK } from 'solver-sdk';

// Создание экземпляра SDK
const sdk = new CodeSolverSDK({
  baseURL: 'https://localhost:3000',
  apiKey: 'your-api-key'
});

// Пример использования
async function example() {
  const isHealthy = await sdk.checkHealth();
  console.log('Сервер доступен:', isHealthy);
}

example().catch(console.error);
```

### В браузере

```html
<script src="node_modules/solver-sdk/dist/umd/code-solver-sdk.min.js"></script>
<script>
  // SDK доступен глобально как CodeSolverSDK
  const sdk = new CodeSolverSDK.default({
    baseURL: 'https://localhost:3000',
    apiKey: 'your-api-key'
  });
  
  // Пример использования
  sdk.checkHealth()
    .then(isHealthy => console.log('Сервер доступен:', isHealthy))
    .catch(console.error);
</script>
```

## API

### Основные компоненты

- `CodeSolverSDK` - Основной класс SDK
- `ReasoningApi` - API для работы с рассуждениями
- `ProjectsApi` - API для работы с проектами
- `SearchApi` - API для поиска кода
- `AgentsApi` - API для работы с агентами
- `ContextApi` - API для работы с контекстом кода
- `DependenciesApi` - API для работы с зависимостями
- `ChatApi` - API для работы с чатом и потоковой передачей мышления

### Опции SDK

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

## Продвинутые функции

### Работа с проектами

```javascript
// Получение списка проектов
const projects = await sdk.projects.getAllProjects();
console.log('Проекты:', projects);

// Создание нового проекта
const newProject = await sdk.projects.createProject('Мой проект', '/path/to/project');
console.log('Новый проект:', newProject);

// Запуск индексации
await sdk.projects.indexProject(newProject.id);
```

### Поиск кода

```javascript
// Поиск кода
const searchResults = await sdk.search.searchCode(projectId, {
  query: 'function example',
  limit: 10
});
console.log('Результаты поиска:', searchResults);

// Семантический поиск кода
const semanticResults = await sdk.search.semanticSearch(projectId, {
  query: 'функция для обработки HTTP запросов',
  limit: 10
});
console.log('Семантические результаты:', semanticResults);
```

### Работа с рассуждениями через WebSocket

```javascript
// Создание рассуждения
const reasoning = await sdk.reasoning.createReasoning({
  projectId: projectId,
  query: 'Объясни, как работает этот проект'
});

// Подключение через WebSocket
const wsClient = sdk.getWebSocketClient();
await wsClient.connectToReasoning(reasoning.id);

// Включение механизма ping/pong для мониторинга состояния соединения
wsClient.enablePingPong(30000, 3);

// Обработка событий мышления
wsClient.on('content_block_delta', (data) => {
  if (data.delta?.type === 'thinking_delta') {
    console.log('Фрагмент размышления:', data.delta.thinking);
  } else if (data.delta?.type === 'text_delta') {
    console.log('Фрагмент ответа:', data.delta.text);
  }
});

wsClient.on('message_stop', (data) => {
  console.log('Завершено:', data);
  
  // Отключаем механизм ping/pong и закрываем соединение
  wsClient.disablePingPong();
  wsClient.disconnectAll();
});

// Мониторинг качества соединения
const diagnostics = wsClient.diagnoseConnection(WebSocketNamespace.REASONING);
console.log(`Состояние соединения:`, diagnostics);
```

### API для работы с зависимостями

```javascript
// Получение зависимостей конкретного файла
const fileDependencies = await sdk.dependencies.getFileDependencies(projectId, {
  filePath: 'src/app.js'
});

console.log('Импорты:', fileDependencies.imports);
console.log('Импортируется в:', fileDependencies.importedBy);

// Получение полного графа зависимостей проекта
const dependencyGraph = await sdk.dependencies.getDependencyGraph(projectId);

// Анализ графа зависимостей и поиск циклов
const analysis = await sdk.dependencies.analyzeDependencyGraph(projectId);
console.log('Циклические зависимости:', analysis.cycles);

// Подключение к WebSocket для зависимостей
await sdk.dependencies.connectWebSocket(projectId);
sdk.dependencies.on('dependency_update', (data) => {
  console.log('Обновление зависимостей:', data);
});
```

### Потоковая передача мышления

Версия 1.7.4 включает полную поддержку потоковой передачи мышления через Anthropic API, а также улучшенную обработку ошибок:

```javascript
const { CodeSolverSDK } = require('solver-sdk');

async function streamThinking() {
  const sdk = new CodeSolverSDK({
    baseURL: 'https://api.example.com',
    apiKey: 'ваш-ключ-api'
  });
  
  // Сообщения для отправки
  const messages = [
    { role: 'user', content: 'Объясни, как работает blockchain' }
  ];
  
  // Опции запроса
  const options = {
    model: 'claude-3-7-sonnet-20240229',
    temperature: 0.7,
    thinking: true,
    authToken: 'your-auth-token' // Унифицированный параметр для аутентификации WebSocket
  };
  
  // Обработчик событий WebSocket
  const handleEvent = (eventType, data) => {
    switch(eventType) {
      case 'content_block_start':
        if (data.content_block && data.content_block.type === 'thinking') {
          console.log('Начало размышлений:');
        }
        break;
        
      case 'content_block_delta':
        if (data.delta && data.delta.type === 'thinking_delta') {
          process.stdout.write(data.delta.thinking); // Потоковый вывод размышлений
        } else if (data.delta && data.delta.type === 'text_delta') {
          process.stdout.write(data.delta.text); // Потоковый вывод итогового текста
        }
        break;
        
      case 'error':
        console.error('Ошибка:', data.message);
        
        // Обработка ошибки географических ограничений
        if (data.type === 'geo_restriction') {
          console.error('Необходимо включить VPN для доступа к API Anthropic из вашего региона');
        }
        break;
    }
  };
  
  try {
    // Отправляем запрос с потоковым мышлением
    const response = await sdk.chat.streamChatWithThinking(
      messages,
      options,
      handleEvent
    );
    
    console.log(`Запрос успешно отправлен. Socket ID: ${response.socketId}`);
  } catch (error) {
    console.error('Ошибка:', error);
    
    // Проверка наличия ошибки географических ограничений
    if (error.type === 'geo_restriction') {
      console.error('Необходимо включить VPN для доступа к API Anthropic из вашего региона');
    }
  }
}

streamThinking();
```

#### Поддерживаемые события WebSocket для мышления

- `message_start` - начало сообщения от модели
- `content_block_start` - начало блока контента (текст или thinking)
- `content_block_delta` - дельта блока контента со следующими типами:
  - `delta.type === 'thinking_delta'` - фрагмент размышления модели
  - `delta.type === 'text_delta'` - фрагмент текстового ответа
  - `delta.type === 'input_json_delta'` - фрагмент JSON для инструментов
  - `delta.type === 'signature_delta'` - подпись блока мышления
- `content_block_stop` - завершение блока контента
- `message_delta` - дельта сообщения
- `message_stop` - завершение сообщения

## Примеры

В директории [`examples`](./examples) доступны примеры использования SDK:

```bash
# Проверка подключения к API
npm run example:check-api

# Индексация проектов
npm run example:indexing

# Работа с зависимостями
npm run example:dependencies
```

## Совместимость

SDK тщательно протестирован в различных средах и поддерживает:

- **Браузеры**: Chrome 80+, Firefox 72+, Safari 14+, Edge 80+
- **Node.js**: Версии 14.x и выше (как CommonJS, так и ESM)
- **VS Code**: Desktop и Web версии

## Разработка и тестирование

```bash
# Установка зависимостей
npm install

# Сборка SDK
npm run build

# Запуск всех тестов
npm test

# Тесты для рассуждений и WebSocket
npm run test:reasoning:all

# Запуск примеров
npm run example:check-api
```

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

```javascript
const sdk = new CodeSolverSDK({
  baseURL: 'https://localhost:3000',
  apiKey: 'test-api-key',
  httpsAgent: new https.Agent({
    rejectUnauthorized: false // Для самоподписанных сертификатов
  }),
  websocket: {
    reconnect: true,
    rejectUnauthorized: false
  }
});
```

## Документация

Подробная документация доступна в директории [`docs`](./docs):

- [Начало работы](./docs/GETTING_STARTED.md)
- [Работа с проектами](./docs/PROJECTS.md)
- [Индексация проектов](./docs/INDEXING.md)
- [Потоковая передача мышления](./docs/THINKING_ARCHITECTURE.md)
- [Работа с регионами](./docs/ADVANCED.md)
- [Полное API](./docs/API.md)

## Лицензия

[MIT](./LICENSE)