# YandexMusic.API

Асинхронная библиотека для неофициального API Яндекс Музыки, разработанная на .NET 10.

## Описание

**YandexMusic.API** — это комплексная C# библиотека для взаимодействия с неофициальным API Яндекс Музыки. Библиотека предоставляет полный набор методов для работы с музыкой, альбомами, исполнителями, плейлистами, радио и другими функциями сервиса.

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

- ✅ **Полная поддержка API Яндекс Музыки** - Все основные методы и функции
- ✅ **Асинхронная архитектура** - Основана на async/await для максимальной производительности
- ✅ **Модульная структура** - Отдельные API классы для каждой функциональности
- ✅ **Сериализация JSON** - Использует современный System.Text.Json
- ✅ **Поддержка WebSocket** - Протокол Ynison для real-time функций
- ✅ **Типобезопасность** - Полная поддержка nullable reference types
- ✅ **Документация на русском** - XML документация всех публичных членов

## Поддерживаемые компоненты

### API Методы

- **Album API** - Получение информации об альбомах
- **Artist API** - Работа с данными исполнителей
- **Label API** - Управление лейблами
- **Landing API** - Доступ к рекомендациям главной страницы
- **Library API** - Работа с библиотекой пользователя (лайки, дизлайки)
- **Playlist API** - Управление плейлистами
- **Pins API** - Управление закреплёнными объектами
- **Radio API** - Управление радиостанциями
- **Search API** - Поиск по музыке
- **Track API** - Работа с треками
- **Queue API** - Управление очередью воспроизведения
- **User API** - Управление пользователем и авторизацией
- **UGC API** - Загрузка пользовательского контента
- **Ynison API** - WebSocket протокол для real-time взаимодействия

### Модели данных

- Полные модели для альбомов, треков, исполнителей, плейлистов
- Модели поиска и рекомендаций
- Модели для управления библиотекой
- Модели для радио и станций
- Модели для WebSocket взаимодействия

## Требования

- **.NET 10** или выше
- C# 12 или выше

## Технологический стек

- **Runtime**: .NET 10
- **Язык**: C# 12
- **Сериализация**: System.Text.Json
- **Асинхронность**: async/await
- **WebSocket**: Native .NET WebSocket support

## Архитектура

### Структура проекта

```
YandexMusic.API/
├── API/                    # Основные классы API для каждой функции
├── Models/                 # Модели данных
├── Requests/              # Построители запросов
├── Common/                # Общая функциональность и провайдеры
├── Extensions/            # Расширения для удобства
├── YandexMusicApi.cs      # Главный класс API
└── README.md             # Документация
```

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

#### YandexMusicApi
Главный класс API, предоставляющий доступ ко всем веткам функциональности через свойства.

```csharp
var api = new YandexMusicApi();
```

#### AuthStorage
Управление учётными данными пользователя, токенами и сессией.

#### RequestProvider
Интерфейс для обработки HTTP запросов и ответов. Имеет несколько реализаций:
- `DefaultRequestProvider` - стандартный провайдер
- `CommonRequestProvider` - расширенный провайдер
- `MockRequestProvider` - для тестирования

#### API Classes
Каждый API класс наследуется от `YCommonAPI` и предоставляет синхронные и асинхронные методы.

## Использование

### Базовый пример

```csharp
using YandexMusic.API;

// Создание экземпляра API
var api = new YandexMusicApi();

// Получение информации о треке
var track = await api.Track.GetTrackAsync(trackId);

// Поиск музыки
var searchResults = await api.Search.SearchAsync("Яндекс");

// Работа с плейлистами
var playlists = await api.Playlist.GetPlaylistAsync(playlistId);
```

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

```csharp
var storage = new AuthStorage();

// Авторизация пользователя
// Используйте соответствующие методы AuthStorage
storage.IsAuthorized = true;
storage.Token = "ваш_токен";
```

### Работа с провайдерами

```csharp
var storage = new AuthStorage();

// Использование пользовательского провайдера
var customProvider = new MyCustomRequestProvider();
var storage = new AuthStorage(customProvider);
```

## Особенности .NET 10

Проект полностью использует возможности .NET 10:

- **C# 12 Features** - Last language version
- **Nullable Reference Types** - Полная поддержка nullable context
- **Implicit Usings** - Автоматический импорт стандартных пространств имён
- **Modern async/await** - Асинхронная обработка
- **System.Text.Json** - Встроенная сериализация JSON

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

Все публичные типы и методы имеют XML документацию на русском языке. Документация автоматически обновляется и доступна через IntelliSense в IDE.

### Пример документации

```csharp
/// <summary>Получает информацию о треке по идентификатору.</summary>
/// <param name="trackId">Идентификатор трека</param>
/// <returns>Модель трека</returns>
public async Task<YTrack?> GetTrackAsync(string trackId)
{
    // ...
}
```

## Миграция с предыдущих версий

Если вы переходите с более старой версии:

1. **Обновите .NET версию** до 10.0
2. **System.Text.Json** уже используется везде вместо Newtonsoft.Json
3. **API сигнатуры** остаются совместимы
4. **Regions удалены** - код лучше организован

## Провайдеры и расширяемость

Архитектура позволяет легко расширять функциональность:

```csharp
public interface IRequestProvider
{
    Task<HttpResponseMessage> GetWebResponseAsync(HttpRequestMessage message);
    Task<T?> GetDataFromResponseAsync<T>(YandexMusicApi api, HttpResponseMessage response);
}

// Реализуйте ваш провайдер
public class MyProvider : IRequestProvider
{
    // Ваша реализация
}
```

## Отладка

Проект поддерживает встроенную отладку через `DebugSettings`:

```csharp
var debug = new DebugSettings 
{ 
    ClearDirectory = true 
};

var storage = new AuthStorage(settings: debug);
```

## Производительность

- **Асинхронные операции** - Не блокируют потоки
- **Кэширование** - Встроенная поддержка кэширования ответов
- **Оптимизированная сериализация** - System.Text.Json быстрее Newtonsoft
- **Минимальные зависимости** - Только необходимые пакеты

## Лицензия

Это неофициальная библиотека для API Яндекс Музыки. Используйте на свой риск.

## Автор

**FrigaT** - Разработчик библиотеки

## Поддержка

Для вопросов и предложений свяжитесь с разработчиком или создайте issue в репозитории.

## Благодарности

Спасибо сообществу .NET разработчиков и всем участникам проекта.

---

**Версия**: 0.0.1  
**Платформа**: .NET 10  
**Язык**: C# 12  
**Обновлено**: 2024