nfoguard/SUMMARY.md

# NFOGuard Development Summary

## Current Status: v1.6.0 - NFO-Based Identification! 📄

### Latest Updates (v1.6.0) - September 16, 2025
- **📄 NFO IDENTIFICATION**: Added support for identifying movies/TV shows from NFO files
- **🔄 DUAL METHOD**: Directory name IMDb IDs (primary) + NFO file IMDb IDs (fallback)
- **📋 NFO FORMATS**: Supports `<uniqueid type="imdb">`, `<imdbid>`, and `<imdb>` XML tags
- **🎬 MOVIE SUPPORT**: Reads movie.nfo files for IMDb ID extraction
- **📺 TV SUPPORT**: Reads tvshow.nfo files for series identification
- **✅ SMART FALLBACK**: Only checks NFO files when directory name lacks IMDb ID
- **📝 DOCUMENTATION**: Updated README with NFO identification examples and formats
- **🔄 NFO RENAMING**: Added smart episode NFO file renaming to standardized `S##E##.nfo` format
- **🎯 SONARR INTEGRATION**: Detects existing NFO files created by Sonarr/other tools, extracts metadata, and renames to standard format
- **📁 METADATA PRESERVATION**: Preserves all existing metadata when renaming non-standard NFO files
- **🧹 CLEANUP**: Removes old non-standard NFO files after successful rename to prevent duplicates

### Previous Updates (v1.5.5) - September 15, 2025
- **🔧 DATABASE BUG FIX**: Fixed `upsert_movie_dates` to be a proper upsert operation
- **💾 DATA INTEGRITY**: Manual scans now properly save `dateadded` to database  
- **🎯 ROOT CAUSE**: Fixed UPDATE-only operation that was leaving `dateadded` fields NULL
- **✅ WEBHOOK FIX**: Webhooks now find existing database entries correctly
- **📺 TV SHOWS**: NOT affected - already using proper `INSERT OR REPLACE` operations

### Previous Updates (v1.5.4) - September 15, 2025
- **🎯 WEBHOOK DATE FIX**: Fixed webhook processing to use proper date decision logic
- **🔍 SMART FALLBACK**: Webhooks now check database → Radarr import dates → release dates → timestamp
- **❌ ISSUE RESOLVED**: Upgrade webhooks no longer incorrectly use current timestamp when database exists
- **✅ PROPER FLOW**: Webhook mode now uses same date logic as manual scans for missing entries

### Previous Updates (v1.5.3) - September 15, 2025
- **🔧 RADARR RENAME FIX**: Added missing event type filtering to Radarr webhooks
- **✅ CONSISTENCY**: Radarr now matches Sonarr's event handling (Download, Upgrade, Rename)
- **🎯 FIXED ISSUE**: Radarr rename events now properly trigger NFO updates with correct dates
- **🔄 WORKFLOW**: Both Sonarr and Radarr now follow identical webhook processing flows

### Previous Updates (v1.5.2)
- **🔇 TVDB WARNINGS**: Added SUPPRESS_TVDB_WARNINGS configuration option
- **✅ CLEAN LOGS**: Can now suppress non-critical TVDB API failure warnings
- **🧹 PRODUCTION**: Cleaner logs for production monitoring
- **🎯 FUNCTIONAL**: System works perfectly without TVDB (uses IMDb/Sonarr data)

### TVDB Warning Suppression
**Added new environment variable:**
```bash
# Suppress TVDB API warnings (true/false) - TVDB failures are common and non-critical
SUPPRESS_TVDB_WARNINGS=true
```

### Why Suppress TVDB Warnings?
- **❌ Common Failures**: Many series don't exist in TVDB database
- **✅ Non-Critical**: NFOGuard works perfectly without TVDB data
- **📊 Primary Data**: Uses IMDb IDs and Sonarr metadata (more reliable)
- **🧹 Log Noise**: Reduces repetitive warning messages

### Before vs After

**Before (noisy):**
```
INFO: All episodes found in cache
WARNING: GET https://api4.thetvdb.com/v4/search/remoteid?remoteId=tt0804484&type=series failed: HTTP Error 400: Bad Request
INFO: Completed processing TV series: Foundation (2021) [imdb-tt0804484]
WARNING: GET https://api4.thetvdb.com/v4/search/remoteid?remoteId=tt9737326&type=series failed: HTTP Error 400: Bad Request
```

**After (clean):**
```
INFO: All episodes found in cache
INFO: Completed processing TV series: Foundation (2021) [imdb-tt0804484]
INFO: Completed processing TV series: Invasion (2021) [imdb-tt9737326]
```

### Your Configuration
```bash
DEBUG=false                    # Clean production logging
PATH_DEBUG=false              # No path mapping debug
SUPPRESS_TVDB_WARNINGS=true   # Hide non-critical TVDB failures
```

### System Status
- ✅ **Processing**: All TV series processing successfully
- ✅ **Episodes**: All episodes found and processed
- ✅ **NFO Files**: Being created/updated with proper metadata
- ✅ **Functionality**: TVDB failures don't affect operation

## 🔇 NFOGuard v1.5.2 - Ultra-clean production logs! 🔇

### Copy SUPPRESS_TVDB_WARNINGS=true to your server .env file and restart!

---

## 🔧 FIXED: Database Upsert Bug (September 15, 2025) - **CRITICAL**

### Issue Discovery
**The Real Root Cause**: Manual scans were NOT actually saving `dateadded` to database due to faulty upsert operation!

### Problem Details
**Database Method Bug** in `core/database.py:173-182`:
- `upsert_movie_dates()` was doing UPDATE-only, not proper upsert
- If movie row didn't exist properly, UPDATE would affect 0 rows  
- `dateadded` field remained NULL even after manual scan
- Webhooks found database entries but with NULL `dateadded` → fell back to current timestamp

### 🔧 **Fix Applied**
- **Location**: `core/database.py:173-186`
- **Changed**: UPDATE-only → proper `INSERT OR REPLACE` upsert
- **Result**: Manual scans now properly save `dateadded` to database
- **Webhook Impact**: Now finds existing dates correctly, no more false timestamps

### Before vs After Database Operations
**Before (BROKEN):**
```sql
UPDATE movies SET dateadded = '2025-06-15...' WHERE imdb_id = 'tt123';
-- If row doesn't exist properly: 0 rows affected, dateadded stays NULL
```

**After (FIXED):**
```sql
INSERT OR REPLACE INTO movies (...) VALUES (...);
-- Always works: Creates row OR replaces with all data including dateadded
```

---

## 🎯 FIXED: Webhook Date Logic Issue (September 15, 2025)

### Issue Discovery  
Upgrade webhooks were incorrectly using current timestamp (`webhook:first_seen`) instead of checking Radarr for proper import dates when no database entry existed.

**Example Problem:**
- Database populated via manual scan: `2025-06-15T11:10:31-04:00` (radarr:db.history.import)
- Upgrade webhook comes in: `2025-09-15T12:04:23-04:00` (webhook:first_seen) ❌ **WRONG!**

### Root Cause
Webhook mode was bypassing the full date decision logic (`_decide_movie_dates`) and jumping straight to current timestamp as fallback.

### ✅ **Fix Applied**
- **Location**: `nfoguard.py:975-990`
- **Logic**: Webhook mode now uses same date priority as manual scans:
  1. **Database first** (if exists)
  2. **Full date logic** (Radarr import → release dates → fallbacks)  
  3. **Current timestamp** (only as absolute last resort)

### Result
Webhook upgrades now properly find and use existing Radarr import dates instead of creating false "first seen" timestamps.

---

## 🔧 FIXED: Radarr Rename Event Issue (September 15, 2025)

### Issue Resolution
**COMPLETED**: Fixed missing Radarr rename event handling by adding proper event type filtering.

### ✅ **Both Sonarr & Radarr Webhook Handling** - **NOW WORKING CORRECTLY**
- **Sonarr Location**: `nfoguard.py:1429`
- **Radarr Location**: `nfoguard.py:1479` **(FIXED)**
- **Event Filtering**: `if event_type not in ["Download", "Upgrade", "Rename"]:`
- **✅ STATUS**: **Rename events ARE processed for both systems**
- **✅ BEHAVIOR**: Both systems now update NFO files with proper date metadata on rename

### What Was Fixed
1. **Added Event Type Filtering**: Radarr webhooks now explicitly filter for supported events
2. **Consistent Processing**: Both Sonarr and Radarr now follow identical webhook workflows
3. **Proper Rename Handling**: Rename events trigger full NFO processing pipeline

---

## 📋 NFOGuard Webhook Workflow Documentation

### 🎬 **Radarr Webhook Workflow**
1. **Import Event**: 
   - Check database - if not seen before, current timestamp = truth of first import
   - Update movie.nfo with proper date metadata
   
2. **Rename Event**: 
   - Check database - if we have the date, use existing date
   - Update movie.nfo file as always (preserving original import date)
   
3. **Rename Event (No Database Entry)**: 
   - Check Radarr database for earliest import date
   - If found, use earliest import date → update database + movie.nfo
   - If no import date found, use digital/theatrical release date (fallback logic)

### 📺 **Sonarr Webhook Workflow**  
1. **Import Event**:
   - Check database - if not seen before, current timestamp = truth of first import
   - Update episode.nfo with proper date metadata
   
2. **Rename Event**:
   - Check database - if we have the date, use existing date  
   - Update episode.nfo file as always (preserving original import date)
   
3. **Rename Event (No Database Entry)**:
   - Check Sonarr API for earliest import date
   - If found, use earliest import date → update database + episode.nfo
   - If no import date found, use air date (fallback logic)

### 🔄 **Key Processing Logic**
- **Database First**: Always check NFOGuard database for existing dates
- **Import Truth**: Webhook import events establish "source of truth" timestamps
- **Date Preservation**: Rename events preserve original import dates, never overwrite
- **Smart Fallbacks**: API queries → Release dates → Air dates → File dates (configurable)
- **Batch Processing**: All webhooks go through batching system with configurable delays