Add quiet hours, fix Telegram bugs, and improve cache performance

- Add quiet hours support to queue notifications during configured time windows
- Fix UnboundLocalError when single-item document chunk exceeds max_asset_data_size
- Fix document-only multi-item chunks being silently dropped (missing skip guard)
- Fix notification queue entity lookup by storing entity_id in queued params
- Fix quiet hours using OS timezone instead of HA-configured timezone (dt_util.now)
- Fix chat_action schema rejecting empty string from "Disabled" selector
- Fix stale thumbhash cache entries not being removed on mismatch
- Fix translation descriptions for send_large_photos_as_documents
- Add batch async_set_many() to TelegramFileCache to reduce disk writes
- Add max-entries eviction (2000) for thumbhash cache to prevent unbounded growth
- Eliminate redundant _is_asset_id/get_asset_thumbhash lookups in media group loop

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

custom_components/immich_album_watcher/__init__.py

@@ -4,16 +4,21 @@ from __future__ import annotations
 
 import logging
 from dataclasses import dataclass
+from datetime import datetime
 
 from homeassistant.config_entries import ConfigEntry, ConfigSubentry
 from homeassistant.core import HomeAssistant
 
+from homeassistant.helpers.event import async_track_time_change
+
 from .const import (
     CONF_ALBUM_ID,
     CONF_ALBUM_NAME,
     CONF_API_KEY,
     CONF_HUB_NAME,
     CONF_IMMICH_URL,
+    CONF_QUIET_HOURS_END,
+    CONF_QUIET_HOURS_START,
     CONF_SCAN_INTERVAL,
     CONF_TELEGRAM_CACHE_TTL,
     DEFAULT_SCAN_INTERVAL,
@@ -22,7 +27,7 @@ from .const import (
     PLATFORMS,
 )
 from .coordinator import ImmichAlbumWatcherCoordinator
-from .storage import ImmichAlbumStorage, TelegramFileCache
+from .storage import ImmichAlbumStorage, NotificationQueue, TelegramFileCache
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -36,6 +41,8 @@ class ImmichHubData:
     api_key: str
     scan_interval: int
     telegram_cache_ttl: int
+    quiet_hours_start: str
+    quiet_hours_end: str
 
 
 @dataclass
@@ -59,6 +66,8 @@ async def async_setup_entry(hass: HomeAssistant, entry: ImmichConfigEntry) -> bo
     api_key = entry.data[CONF_API_KEY]
     scan_interval = entry.options.get(CONF_SCAN_INTERVAL, DEFAULT_SCAN_INTERVAL)
     telegram_cache_ttl = entry.options.get(CONF_TELEGRAM_CACHE_TTL, DEFAULT_TELEGRAM_CACHE_TTL)
+    quiet_hours_start = entry.options.get(CONF_QUIET_HOURS_START, "")
+    quiet_hours_end = entry.options.get(CONF_QUIET_HOURS_END, "")
 
     # Store hub data
     entry.runtime_data = ImmichHubData(
@@ -67,6 +76,8 @@ async def async_setup_entry(hass: HomeAssistant, entry: ImmichConfigEntry) -> bo
         api_key=api_key,
         scan_interval=scan_interval,
         telegram_cache_ttl=telegram_cache_ttl,
+        quiet_hours_start=quiet_hours_start,
+        quiet_hours_end=quiet_hours_end,
     )
 
     # Create storage for persisting album state across restarts
@@ -85,6 +96,10 @@ async def async_setup_entry(hass: HomeAssistant, entry: ImmichConfigEntry) -> bo
     )
     await telegram_asset_cache.async_load()
 
+    # Create notification queue for quiet hours
+    notification_queue = NotificationQueue(hass, entry.entry_id)
+    await notification_queue.async_load()
+
     # Store hub reference
     hass.data[DOMAIN][entry.entry_id] = {
         "hub": entry.runtime_data,
@@ -92,6 +107,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ImmichConfigEntry) -> bo
         "storage": storage,
         "telegram_cache": telegram_cache,
         "telegram_asset_cache": telegram_asset_cache,
+        "notification_queue": notification_queue,
     }
 
     # Track loaded subentries to detect changes
@@ -104,6 +120,13 @@ async def async_setup_entry(hass: HomeAssistant, entry: ImmichConfigEntry) -> bo
     # Forward platform setup once - platforms will iterate through subentries
     await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
 
+    # Register quiet hours end timer
+    _register_quiet_hours_timer(hass, entry)
+
+    # Check if there are queued notifications from before restart (outside quiet hours)
+    if notification_queue.has_pending() and not _is_quiet_hours(quiet_hours_start, quiet_hours_end):
+        hass.async_create_task(_process_notification_queue(hass, entry))
+
     # Register update listener for options and subentry changes
     entry.async_on_unload(entry.add_update_listener(_async_update_listener))
 
@@ -159,6 +182,118 @@ async def _async_setup_subentry_coordinator(
     _LOGGER.info("Coordinator for album '%s' set up successfully", album_name)
 
 
+def _is_quiet_hours(start_str: str, end_str: str, hass: HomeAssistant | None = None) -> bool:
+    """Check if current time is within quiet hours."""
+    from datetime import time as dt_time
+    from homeassistant.util import dt as dt_util
+
+    if not start_str or not end_str:
+        return False
+
+    try:
+        now = dt_util.now().time()
+        start_time = dt_time.fromisoformat(start_str)
+        end_time = dt_time.fromisoformat(end_str)
+    except ValueError:
+        return False
+
+    if start_time <= end_time:
+        return start_time <= now < end_time
+    else:
+        # Crosses midnight (e.g., 22:00 - 08:00)
+        return now >= start_time or now < end_time
+
+
+def _register_quiet_hours_timer(hass: HomeAssistant, entry: ImmichConfigEntry) -> None:
+    """Register a timer to process the notification queue when quiet hours end."""
+    entry_data = hass.data[DOMAIN][entry.entry_id]
+
+    # Cancel existing timer if any
+    unsub = entry_data.pop("quiet_hours_unsub", None)
+    if unsub:
+        unsub()
+
+    end_str = entry.options.get(CONF_QUIET_HOURS_END, "")
+    start_str = entry.options.get(CONF_QUIET_HOURS_START, "")
+    if not end_str or not start_str:
+        return
+
+    try:
+        from datetime import time as dt_time
+        end_time = dt_time.fromisoformat(end_str)
+    except ValueError:
+        _LOGGER.warning("Invalid quiet hours end time: %s", end_str)
+        return
+
+    async def _on_quiet_hours_end(_now: datetime) -> None:
+        """Handle quiet hours end — process queued notifications."""
+        queue: NotificationQueue = entry_data["notification_queue"]
+        if queue.has_pending():
+            _LOGGER.info("Quiet hours ended, processing queued notifications")
+            await _process_notification_queue(hass, entry)
+
+    unsub = async_track_time_change(
+        hass, _on_quiet_hours_end, hour=end_time.hour, minute=end_time.minute, second=0
+    )
+    entry_data["quiet_hours_unsub"] = unsub
+    entry.async_on_unload(unsub)
+
+    _LOGGER.debug("Registered quiet hours timer for %s", end_str)
+
+
+async def _process_notification_queue(
+    hass: HomeAssistant, entry: ImmichConfigEntry
+) -> None:
+    """Process all queued notifications via the HA service call."""
+    import asyncio
+    from homeassistant.helpers import entity_registry as er
+
+    entry_data = hass.data[DOMAIN].get(entry.entry_id)
+    if not entry_data:
+        return
+
+    queue: NotificationQueue = entry_data["notification_queue"]
+    items = queue.get_all()
+    if not items:
+        return
+
+    # Find a fallback sensor entity for items that don't have entity_id stored
+    ent_reg = er.async_get(hass)
+    fallback_entity_id = None
+    for ent in er.async_entries_for_config_entry(ent_reg, entry.entry_id):
+        if ent.domain == "sensor":
+            fallback_entity_id = ent.entity_id
+            break
+
+    if not fallback_entity_id:
+        _LOGGER.warning("No sensor entity found to process notification queue")
+        return
+
+    _LOGGER.info("Processing %d queued notifications", len(items))
+    for i, item in enumerate(items):
+        params = item.get("params", {})
+        try:
+            # Use stored entity_id from the original call, fall back to discovered one
+            target_entity_id = params.pop("entity_id", None) or fallback_entity_id
+            # Call the service with ignore_quiet_hours=True to prevent re-queuing
+            await hass.services.async_call(
+                DOMAIN,
+                "send_telegram_notification",
+                {**params, "ignore_quiet_hours": True},
+                target={"entity_id": target_entity_id},
+                blocking=True,
+            )
+        except Exception:
+            _LOGGER.exception("Failed to send queued notification %d/%d", i + 1, len(items))
+
+        # Small delay between notifications to avoid rate limiting
+        if i < len(items) - 1:
+            await asyncio.sleep(1)
+
+    await queue.async_clear()
+    _LOGGER.info("Processed %d queued notifications", len(items))
+
+
 async def _async_update_listener(
     hass: HomeAssistant, entry: ImmichConfigEntry
 ) -> None:
@@ -177,18 +312,26 @@ async def _async_update_listener(
         await hass.config_entries.async_reload(entry.entry_id)
         return
 
-    # Handle options-only update (scan interval change)
+    # Handle options-only update
     new_interval = entry.options.get(CONF_SCAN_INTERVAL, DEFAULT_SCAN_INTERVAL)
+    new_quiet_start = entry.options.get(CONF_QUIET_HOURS_START, "")
+    new_quiet_end = entry.options.get(CONF_QUIET_HOURS_END, "")
 
     # Update hub data
     entry.runtime_data.scan_interval = new_interval
+    entry.runtime_data.quiet_hours_start = new_quiet_start
+    entry.runtime_data.quiet_hours_end = new_quiet_end
 
     # Update all subentry coordinators
     subentries_data = entry_data["subentries"]
     for subentry_data in subentries_data.values():
         subentry_data.coordinator.update_scan_interval(new_interval)
 
-    _LOGGER.info("Updated scan interval to %d seconds", new_interval)
+    # Re-register quiet hours timer
+    _register_quiet_hours_timer(hass, entry)
+
+    _LOGGER.info("Updated hub options (scan_interval=%d, quiet_hours=%s-%s)",
+                 new_interval, new_quiet_start or "disabled", new_quiet_end or "disabled")
 
 
 async def async_unload_entry(hass: HomeAssistant, entry: ImmichConfigEntry) -> bool: