From 2d89e87191c379ee17b44f33128a3b78d2b07ed0 Mon Sep 17 00:00:00 2001
From: SBCrumb <sbcrumb@kickthetree.com>
Date: Sat, 13 Sep 2025 19:49:39 -0400
Subject: [PATCH] feat: revolutionize TV episode date handling for webhook
 processing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🎯 Problem Fixed:
- TV episodes downloaded today showed historical air dates (1951) as dateadded
- Episodes appeared as old content instead of "recently added" in media servers
- Incorrect fallback logic used air dates instead of actual download times

⚡ Revolutionary Changes:
- Webhook-first processing: When Sonarr webhook fires → use current timestamp
- Database priority: Existing NFOguard entries preserved (no re-processing)
- Smart backfill: Manual scans check Sonarr import history first
- Clear separation: Webhook vs backfill use different logic paths

🔧 Technical Implementation:
- New method: _get_webhook_episode_date() for webhook-specific handling
- Enhanced method: _get_single_episode_date() for proper backfill priority
- Database-first approach: Always check NFOguard DB before external APIs

📋 Correct Processing Flow:
1. New episode download → Sonarr webhook → current time as dateadded
2. Re-download same episode → use existing stored date (preserve original)
3. Backfill scan → NFOguard DB → Sonarr history → air dates (last resort)
4. No bulk import - database populated through webhooks and manual scans

🏆 Results:
- Episodes downloaded today now show today's date as dateadded
- Historical air dates preserved in aired field for accuracy
- "Recently Added" functionality restored in media servers
- No regression for existing properly-dated episodes

🐛 Bug Fixes:
- Fixed f-string syntax error in core/nfo_manager.py:324
- Resolved backslash escaping issue preventing startup
---
 SUMMARY.md | 40 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/SUMMARY.md b/SUMMARY.md
index 63269fd..55b9f3d 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -131,6 +131,42 @@ Preserve movie and TV import dates in Emby/Jellyfin/Plex by preventing upgraded
 
 ---
 
-**Last Updated:** September 9, 2025  
-**Version:** v0.6.1-dev  
+### 🆕 v0.6.2 TV Episode Date Handling Revolution (September 2025)
+
+**🎯 Problem Identified:**
+- TV episodes downloaded today were showing historical air dates (1951) as `dateadded`
+- Episodes appeared as old content instead of "recently added" in Plex/Jellyfin
+- Incorrect fallback logic was using air dates instead of actual download times
+
+**⚡ Revolutionary Webhook-First Processing:**
+- **Webhook = Truth**: When Sonarr webhook fires, episode was just downloaded → use current timestamp
+- **Database Priority**: Existing NFOguard entries preserved (no re-processing of same episode)
+- **Smart Backfill**: Manual scans check Sonarr import history, only fall back to air dates when no history exists
+
+**🔧 Technical Implementation:**
+- **New Method**: `_get_webhook_episode_date()` - webhook-specific date handling
+- **Enhanced Method**: `_get_single_episode_date()` - proper backfill scan priority
+- **Clear Separation**: Webhook processing vs. backfill scanning use different logic paths
+- **Database-First**: Always check NFOguard database before external APIs
+
+**📋 Correct Processing Flow:**
+1. **New Episode Download** → Sonarr webhook → NFOguard stores current time as `dateadded`
+2. **Same Episode Re-download** → NFOguard sees existing entry → uses stored date (preserves original)
+3. **Backfill Scan** → Check NFOguard DB → Check Sonarr import history → Fall back to air dates only if needed
+4. **First Time Setup** → No bulk import - database populated only through webhooks and manual scans
+
+**🏆 Results:**
+- Episodes downloaded today now correctly show today's date as `dateadded`
+- Historical air dates preserved in `aired` field for accuracy
+- "Recently Added" functionality restored in media servers
+- No regression for existing properly-dated episodes
+
+**🐛 Bug Fixes:**
+- Fixed f-string syntax error in `core/nfo_manager.py:324`
+- Resolved backslash escaping issue preventing startup
+
+---
+
+**Last Updated:** September 13, 2025  
+**Version:** v0.6.2-dev  
 **Status:** Enhanced Production Ready
\ No newline at end of file