nfoguard/CHANGELOG.md

Changelog

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

[Released] - v0.6.0 - 2025-09-11

Added

• 📺 Enhanced TV Show Processing: Comprehensive single season/episode capabilities
  • Single Season Processing: /tv/scan-season endpoint for targeted season updates
  • Single Episode Processing: /tv/scan-episode endpoint for individual episode handling
  • URL-Safe Endpoints: JSON-based API calls avoid URL encoding issues with spaces/special characters
  • Enhanced Path Detection: Automatically detects season directories and episode files
  • Database Integration: Full episode date tracking and retrieval with get_episode_date()
• 🎬 Rich NFO Generation: Full metadata integration from Sonarr API
  • Episode Titles: Real episode names from Sonarr instead of generic S01E01 format
  • Plot Summaries: Episode descriptions for better library browsing experience
  • Runtime Data: Episode duration information for media players
  • Rating Integration: IMDb ratings and vote counts for episodes
  • Backwards Compatible: Existing basic NFOs still work, enhanced when Sonarr API available
• ⏰ NFOGuard Timestamps: All NFO files now include processing timestamps
  • Creation Tracking: Shows when NFOGuard created/updated each NFO file
  • Format: <!-- managed by NFOGuard at 2025-09-11T13:45:22+00:00 -->
  • Audit Trail: Helps track metadata management history
• 🔧 Enhanced TV Manual Scan: Smart path detection for seasons and episodes
  • Season Detection: curl -X POST "manual/scan?path=/media/TV/Series/Season 13"
  • Episode Detection: curl -X POST "manual/scan?path=/media/TV/Series/Season 13/episode.mkv"
  • Automatic Processing: Detects context and processes accordingly
• ⚙️ Configurable TV Webhook Processing: Choose between targeted or comprehensive processing
  • Targeted Mode: TV_WEBHOOK_PROCESSING_MODE=targeted (default) - Only process webhook episodes
  • Series Mode: TV_WEBHOOK_PROCESSING_MODE=series - Process entire series directory
  • Smart Fallback: Automatically falls back to series mode when episode data unavailable
  • Efficiency: Targeted mode reduces unnecessary file operations and notifications
• 🔐 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