# yarr-api

A Rust client library for the Sonarr API.

## Overview

`yarr-api` provides a strongly-typed, async Rust client for interacting with Sonarr instances. It handles authentication, request/response serialization, and provides convenient methods for all major Sonarr API endpoints.

## Features

- **Async/await support** - Built on `tokio` and `reqwest`
- **Type-safe API** - All API responses are strongly typed with `serde`
- **Error handling** - Comprehensive error types with detailed error information
- **Easy to use** - Simple client interface with intuitive method names
- **Download after search** - Search for releases and automatically download the best quality
- **Release management** - Full support for searching, filtering, and downloading releases
- **Well documented** - Extensive documentation and examples

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
yarr-api = "0.1.0"
```

## Quick Start

```rust
use yarr_api::{SonarrClient, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Create a client
    let client = SonarrClient::new(
        "http://localhost:8989".to_string(),
        "your-api-key".to_string()
    );

    // Get system status
    let status = client.get_system_status().await?;
    println!("Sonarr version: {}", status.version.unwrap_or_default());

    // Get all series
    let series = client.get_series().await?;
    println!("Total series: {}", series.len());

    // Get download queue
    let queue = client.get_queue().await?;
    println!("Items in queue: {}", queue.records.len());

    // Search and download the best release for a series
    let downloaded = client.search_and_download_best(Some(1), None, None).await?;
    if let Some(release) = downloaded {
        println!("Downloaded: {}", release.title.unwrap_or_default());
    }

    Ok(())
}
```

## API Coverage

### System
- ✅ System status
- ✅ Health check

### Series Management
- ✅ List all series
- ✅ Get series by ID
- ✅ Search for series
- ✅ Add new series

### Episodes
- ✅ Get episodes for series/season
- ✅ Get calendar (upcoming episodes)
- ✅ Get missing episodes

### Downloads
- ✅ Get download queue
- ✅ Get download history

### Releases
- ✅ Search for releases by series/episode/season
- ✅ Download specific releases
- ✅ Automatic best quality selection
- ✅ Advanced filtering and sorting

## Examples

See the `examples/` directory for more comprehensive usage examples:

```bash
# Run the basic usage example
cargo run --example basic_usage

# Run the download after search example
cargo run --example download_after_search

# Make sure to set your Sonarr URL and API key first:
export SONARR_URL="http://localhost:8989"
export SONARR_API_KEY="your-api-key-here"
```

### Download After Search

The library provides powerful functionality for searching and automatically downloading releases:

```rust
use yarr_api::SonarrClient;

let client = SonarrClient::new(url, api_key);

// Search and download the first available release
let success = client.search_and_download(Some(series_id), None, None).await?;

// Search and download the best quality release
let best_release = client.search_and_download_best(Some(series_id), None, Some(season)).await?;

// Manual search with custom filtering
let releases = client.search_releases(Some(series_id), Some(episode_id), None).await?;
for release in releases {
    if release.download_allowed.unwrap_or(false) && !release.rejected.unwrap_or(true) {
        client.download_release(&release).await?;
        break;
    }
}
```

## Error Handling

The library uses a custom `ApiError` type that provides detailed error information:

```rust
use yarr_api::{SonarrClient, ApiError};

let client = SonarrClient::new(url, api_key);

match client.get_series().await {
    Ok(series) => println!("Found {} series", series.len()),
    Err(ApiError::Authentication) => println!("Invalid API key"),
    Err(ApiError::NotFound) => println!("Endpoint not found"),
    Err(ApiError::ServerError) => println!("Sonarr server error"),
    Err(e) => println!("Other error: {}", e),
}
```

## Configuration

The client requires two pieces of information:

1. **Base URL** - The URL of your Sonarr instance (e.g., `http://localhost:8989`)
2. **API Key** - Your Sonarr API key (found in Settings > General > Security)

## Data Types

All Sonarr API responses are represented as strongly-typed Rust structs:

- `SystemStatus` - System information and status
- `Series` - TV series information
- `Episode` - Episode details
- `QueueItem` - Download queue items
- `HistoryItem` - Download history
- `HealthResource` - Health check results
- `ReleaseResource` - Release/torrent information with download metadata
- `QualityModel` - Quality information and settings
- `CustomFormatResource` - Custom format definitions

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Related Projects

- [yarr](../yarr-cli) - TUI client for Sonarr built using this library