nfoguard/CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased] - v0.6.0

### Added
- **🔐 Secure Configuration System**: Two-file configuration with automatic API key masking
  - **Main `.env`**: Paths and preferences (safe to share for debugging)
  - **Separate `.env.secrets`**: API keys and passwords (never committed to git)
  - **Automatic Loading**: Both files loaded at startup with python-dotenv
  - **Log Security**: API keys automatically masked in all log output
  - **Git Protection**: Updated .gitignore prevents accidental commits of sensitive data
- **🧠 Smart Date Validation**: Intelligent release date selection with configurable gap detection
  - **Automatic Detection**: Prefers theatrical dates when digital/physical are unreasonably late
  - **Configurable**: `MAX_RELEASE_DATE_GAP_YEARS=10` (default: 10 years maximum gap)
  - **Example**: "The Craft (1996)" prefers 1996 theatrical over 2022 physical release
  - **Toggle**: `ENABLE_SMART_DATE_VALIDATION=true` to enable/disable feature
- **🧹 Repository Cleanup**: Removed legacy and duplicate files
  - **Removed**: `media_date_cache.py`, `webhook_server.py` (replaced by nfoguard.py)
  - **Removed**: Outdated documentation files (`API_ENDPOINTS.md`, `MIGRATION.md`, `STRUCTURE.md`)
  - **Streamlined**: Cleaner codebase with only essential files
- **🎯 Configurable Release Date Priority System**: Revolutionary smart fallback for manual imports
  - **Configurable Priority Order**: `RELEASE_DATE_PRIORITY=digital,physical,theatrical` (customizable)
  - **Digital Releases**: VOD/streaming dates (Netflix, iTunes, etc.) - TMDB type 4
  - **Physical Releases**: DVD/Blu-ray dates - TMDB type 5  
  - **Theatrical Releases**: Cinema release dates - TMDB type 3
  - **Smart Comparison Logic**: Prevents unrealistic dates (won't use 2000 digital for 1983 movie)
  - **Per-Movie Intelligence**: "The Craft (1996)" gets 1996 theatrical, "Top Gun Maverick (2022)" gets digital
  - **Configuration**: `PREFER_RELEASE_DATES_OVER_FILE_DATES=true` replaces old digital-only setting
- **🔇 File Date Fallback Control**: New option to completely disable file date usage
  - **Configuration**: `ALLOW_FILE_DATE_FALLBACK=false` (default: false)
  - **Behavior**: Movies with no release dates get skipped instead of using file dates
  - **Clean Logs**: Eliminates "Using file dateAdded as fallback" warnings
- **Enhanced Debug Endpoints**:
  - `/debug/movie/{imdb_id}/priority` - Shows date selection logic and available sources
  - Detailed analysis of file date vs digital date decisions
- **Complete API Documentation**: Updated README with all curl commands and response examples
- **Testing Infrastructure**: 
  - `test_bulk_update.py` - Database connection validation
  - `test_movie_scan.py` - Directory scanning logic testing  
  - `test_end_to_end.py` - Complete workflow validation
- **External API Integration**:
  - TMDB API for digital release dates
  - OMDb API for DVD/digital release dates
  - Jellyseerr integration for additional digital release data
- **Deployment Documentation**:
  - `SETUP.md` - Secure configuration setup guide
  - `DEPLOYMENT.md` - Complete Docker deployment guide  
  - `TESTING.md` - Testing strategy and troubleshooting
  - `.env.template` - Clean main configuration template
  - `.env.secrets.template` - Secure secrets configuration template
  - `docker-compose.yml` - Production-ready deployment with volume mounts

### Changed
- **Configuration Management**: Secure two-file system replaces single .env approach
  - **Separated Concerns**: Main config (.env) vs sensitive data (.env.secrets)
  - **Enhanced Security**: API key masking and git protection built-in
  - **Docker Integration**: Updated docker-compose.yml with proper volume mounts
- **Movie Priority Logic**: Enhanced `import_then_digital` to intelligently handle file date fallbacks
- **README.md**: Complete rewrite with secure configuration examples and curl commands

### Fixed
- **Manual Import Handling**: Movies manually imported to Radarr now use digital release dates instead of file modification dates
- **Path Configuration**: Fixed hardcoded media paths, now fully configurable via environment variables
- **Debug History Endpoint**: Fixed endpoint showing wrong movie events (still needs database-only implementation)

### Technical Details
- Maintains full backward compatibility with existing configurations
- Smart date comparison algorithm considers theatrical release dates when available
- Environment variable validation and fallback to sensible defaults

# Changelog

## [0.5.1] - 2025-09-08

### Changed
- **BREAKING**: RadarrClient now operates in DATABASE ONLY mode
- Completely eliminated Radarr API usage for movie lookups and import date detection
- All movie operations now use direct database queries exclusively
- Debug endpoints updated to use database-only methods
- Enhanced error messaging when database access is not configured

### Fixed
- Fixed debug endpoint still calling API methods despite database availability
- Removed all API fallback mechanisms for true database-only operation

## [0.5.0] - 2025-09-08

### Added
- **Major Performance Enhancement**: Direct Radarr database access
  - New `RadarrDbClient` class for high-performance database queries
  - Support for both SQLite and PostgreSQL Radarr databases
  - Eliminates API pagination overhead for import date lookups
  - Up to 10x faster movie import date detection
- **Bulk Operations**: Added bulk import date queries for multiple movies
- **Database Configuration**: New environment variables for database connection
  - `RADARR_DB_TYPE` (sqlite/postgresql)
  - `RADARR_DB_HOST`, `RADARR_DB_PORT`, `RADARR_DB_NAME` for PostgreSQL
  - `RADARR_DB_USER`, `RADARR_DB_PASSWORD` for PostgreSQL authentication
  - `RADARR_DB_PATH` for SQLite databases
  - `RADARR_DB_URL` connection string support
- **Testing Suite**: Added performance comparison test script (`test_db_performance.py`)

### Changed
- **RadarrClient Enhanced**: Automatic database client initialization with API fallback
- **Movie Lookup Optimization**: Database-first approach for movie IMDb ID resolution
- **Import Date Detection**: Optimized SQL queries replace complex API event parsing
- **Dependencies**: Added `psycopg2-binary` for PostgreSQL support

### Technical Details
- Database queries use proper SQL joins for efficient data retrieval
- Maintains full backward compatibility with API-only installations
- Graceful fallback to API methods when database access is unavailable
- Support for both connection strings and individual parameter configuration

## [0.4.1] - 2025-01-09

### Fixed
- **Radarr Client**: Fixed event type parsing for string-based event types (grabbed, downloadFolderImported, etc.)
- **Radarr Client**: Improved grab event detection to filter out library addition events and only count actual download grabs
- **Radarr Client**: Fixed JSON parsing errors when handling event data that's already a dictionary
- **Radarr Client**: Enhanced validation of grab events to require download metadata (sourceTitle or indexer)

### Improved
- **Radarr Client**: Better chronological event processing to find earliest actual download dates
- **Radarr Client**: More accurate import date detection by validating grab events have real download information

## [0.4.0] - 2025-01-08
### Changed
- Switched to using Radarr's numeric event types for more reliable import detection
  - Added constants for EVENT_TYPE_GRABBED (1), IMPORTED (3), etc.
  - Removed legacy string-based event type checks
  - Improved event type parsing and validation
### Changed
- Added documentation for Radarr API event types (1=grabbed, 3=imported)
- Improved event type detection using Radarr's internal event type IDs
- Removed old string-based event type checks in favor of numeric IDs

## [0.3.8] - 2025-09-08
### Changed
- Use Radarr's numeric EventType (3="Imported") for more accurate import date detection
- Simplified history processing logic

## [0.3.7] - 2025-09-08
### Changed
- Improved import date detection by tracking grab dates as fallback
- Added warning when falling back to grab date

## [0.3.6] - 2025-09-08
### Changed
- Improved import detection filtering
- Reduced debug noise for non-import events
- Enhanced logging clarity for import matches
- Added more context to import event messages

## [0.3.5] - 2025-09-08
### Changed
- Improved Radarr import detection to handle more cases
- Added support for downloadFolderImported events
- Enhanced path matching with better character cleaning
- Added fuzzy title matching by removing articles
- Reduced debug noise by only logging relevant matches

## [0.3.4] - 2025-09-08
### Changed
- Added downloadFolderImported event support
- Improved path matching flexibility

## [0.3.3] - 2025-09-08
### Changed
- Added flexible path matching
- Added sourcePath support
- Initial support for title/year matching