180 lines
5.0 KiB
Markdown
180 lines
5.0 KiB
Markdown
# 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 |