# 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
- **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());

    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

## Examples

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

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

# 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"
```

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

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