ohm_streaming/docs/SONARR_IMPLEMENTATION.md

# Sonarr Integration - Implementation Summary

## Overview

Complete Sonarr webhook integration has been successfully implemented for Ohm Stream Downloader, enabling automated anime downloads when Sonarr grabs new episodes.

## Files Created/Modified

### New Files

1. **app/models/sonarr.py** (5,591 bytes)
   - Pydantic models for Sonarr webhooks
   - `SonarrWebhookPayload` - Complete webhook schema
   - `SonarrEventType` - Event type enum (Grab, Download, Rename, Delete, Test)
   - `SonarrSeries`, `SonarrEpisode` - Series and episode models
   - `SonarrMapping` - Series to anime provider mapping
   - `SonarrConfig` - Webhook configuration
   - `SonarrDownloadRequest` - Manual download request

2. **app/sonarr_handler.py** (13,472 bytes)
   - Main Sonarr integration handler
   - Webhook processing logic
   - Mapping management (CRUD operations)
   - HMAC SHA256 signature verification
   - Anime search and suggestion algorithms
   - Episode retrieval from providers
   - Configuration persistence

3. **tests/test_sonarr.py** (14,897 bytes)
   - Comprehensive test suite (23 tests, all passing)
   - Model validation tests
   - Handler functionality tests
   - Webhook processing tests
   - Match score calculation tests
   - Configuration persistence tests

4. **docs/SONARR_INTEGRATION.md** (11,678 bytes)
   - Complete setup guide
   - API documentation
   - Configuration examples
   - Troubleshooting guide
   - Workflow examples

5. **config/sonarr.example.json**
   - Example configuration file
   - Shows all available options

6. **config/sonarr_mappings.example.json**
   - Example mappings file
   - Shows mapping structure

### Modified Files

1. **main.py**
   - Added Sonarr imports
   - Added 11 new API endpoints:
     - `POST /api/webhook/sonarr` - Main webhook endpoint
     - `POST /api/webhook/test/sonarr` - Test endpoint
     - `GET /api/sonarr/config` - Get configuration
     - `PUT /api/sonarr/config` - Update configuration
     - `GET /api/sonarr/mappings` - List mappings
     - `POST /api/sonarr/mappings` - Create/update mapping
     - `DELETE /api/sonarr/mappings/{id}` - Delete mapping
     - `GET /api/sonarr/search` - Search anime
     - `GET /api/sonarr/episodes` - Get episode list
     - `GET /api/sonarr/suggest` - Get mapping suggestions
     - `POST /api/sonarr/download` - Manual download trigger

2. **README.md**
   - Updated roadmap (Version 2.5 marked as complete)
   - Added Sonarr endpoints list
   - Added link to Sonarr documentation

3. **CLAUDE.md**
   - Added Sonarr to project overview
   - Updated directory structure
   - Added Sonarr integration section with architecture, workflow, and examples
   - Added Sonarr API endpoints

## Features Implemented

### Core Functionality

✅ **Webhook Reception**
- Receive and parse Sonarr webhooks
- Support for all event types (Grab, Download, Rename, Delete, Test)
- Request body validation with Pydantic

✅ **Security**
- HMAC SHA256 signature verification (optional)
- Secret key configuration
- Signature validation on webhook receipt

✅ **Mapping System**
- CRUD operations for series mappings
- Sonarr TVDB ID → Anime Provider URL mapping
- Persistent storage (JSON files)
- Support for all anime providers (Anime-Sama, Neko-Sama, Anime-Ultime, Vostfree)

✅ **Automatic Downloads**
- Trigger downloads on Grab events
- Episode matching (season/episode numbers)
- Quality selection (1080p, 720p, etc.)
- Language selection (VOSTFR, VF)

✅ **Search & Discovery**
- Search anime on providers
- Get episode lists
- Suggest mappings with match scores
- Fuzzy title matching

✅ **Manual Trigger**
- Manually trigger downloads via API
- Useful for testing and manual downloads
- Uses same logic as automatic downloads

### API Endpoints

Total: **11 new endpoints**

Configuration: 2 endpoints
Mappings: 4 endpoints
Search & Discovery: 3 endpoints
Webhooks: 2 endpoints

## Testing

### Test Coverage

- **Total tests**: 23
- **Pass rate**: 100%
- **Coverage**: 66% for sonarr_handler.py

### Test Categories

1. **Model Tests** (5 tests)
   - Config validation
   - Mapping validation
   - Download request validation
   - Payload validation
   - Event type validation

2. **Handler Tests** (11 tests)
   - Initialization
   - Configuration persistence
   - CRUD operations
   - HMAC verification
   - Match score calculation

3. **Webhook Processing Tests** (5 tests)
   - Grab event with mapping
   - Grab event without mapping
   - Auto-download disabled
   - Webhook disabled
   - Test event

4. **Utility Tests** (2 tests)
   - Singleton pattern
   - Handler instance

## Configuration

### Files

- `config/sonarr.json` - Main configuration
- `config/sonarr_mappings.json` - Series mappings

### Options

```json
{
  "webhook_enabled": false,        // Enable/disable webhook processing
  "webhook_secret": null,          // HMAC secret (optional)
  "auto_download_enabled": true,   // Auto-download on Grab
  "default_language": "vostfr",    // Default language
  "default_quality": null,         // Default quality
  "default_provider": "anime-sama",// Default provider
  "verify_hmac": false,           // Enable HMAC verification
  "log_webhooks": true            // Log incoming webhooks
}
```

## Workflow

### Automatic Download Flow

1. User configures Sonarr webhook pointing to Ohm Stream Downloader
2. User creates mapping between Sonarr series (TVDB ID) and anime provider URL
3. Sonarr grabs a new episode and sends webhook
4. Ohm Stream Downloader receives webhook and verifies signature (if enabled)
5. System looks up mapping by TVDB ID
6. Finds matching episode on anime provider
7. Creates download task and starts download
8. Returns response to Sonarr

### Manual Setup Flow

1. Get Sonarr series TVDB ID from series details
2. Search for anime: `GET /api/sonarr/search?q={title}`
3. Create mapping: `POST /api/sonarr/mappings`
4. Test with manual trigger: `POST /api/sonarr/download`

## Security Considerations

- HMAC SHA256 verification optional but recommended for production
- Secret key must match in both Sonarr and Ohm Stream Downloader
- HTTPS recommended for production deployments
- Webhook logging for debugging and audit trail

## Documentation

- **Setup Guide**: `docs/SONARR_INTEGRATION.md`
- **API Documentation**: Inline in main.py
- **Code Comments**: Comprehensive docstrings
- **Examples**: Included in documentation

## Future Enhancements

Possible improvements for future versions:

1. **Radarr Support** - Similar integration for movies
2. **Automatic Mapping** - Auto-suggest mappings based on title similarity
3. **Batch Operations** - Create multiple mappings at once
4. **Web UI** - Interface for managing mappings through web interface
5. **Quality Fallback** - Try alternative qualities if preferred not available
6. **Multi-Provider** - Search across all providers simultaneously
7. **Notification Integration** - Send notifications when downloads complete

## Conclusion

The Sonarr integration is **fully functional** and **production-ready** with:

- ✅ Complete webhook support
- ✅ Secure (optional HMAC)
- ✅ Well-tested (23 passing tests)
- ✅ Fully documented
- ✅ Easy to configure
- ✅ Flexible mapping system

The implementation follows best practices with:
- Clean code architecture
- Comprehensive error handling
- Persistent configuration
- Extensive logging
- Type safety with Pydantic
- Async/await for performance