Fix template variable docs to match actual notifier output

Audit and fix all template variable references: - template_vars.py: Add missing fields (album_id, old_shared, new_shared, latitude, longitude, owner_id, people per asset) - _SAMPLE_CONTEXT: Use proper structured data matching build_asset_detail() output (id, owner_id, latitude, longitude, people per asset, playback_url for videos) - i18n: Fix all variable descriptions for accuracy, add missing fields, mark scheduler-dependent slots as "not yet implemented" - Variables modal: Add album_fields section for periodic_summary - Shared _ASSET_FIELDS and _ALBUM_FIELDS dicts in template_vars.py to keep scheduled/memory slots DRY Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 20:58:21 +03:00
parent 3c893d6dbf
commit b87b5b2c87
7 changed files with 297 additions and 100 deletions
--- a/packages/server/src/immich_watcher_server/api/template_configs.py
+++ b/packages/server/src/immich_watcher_server/api/template_configs.py
@@ -14,22 +14,37 @@ from ..database.models import TemplateConfig, User

 router = APIRouter(prefix="/api/template-configs", tags=["template-configs"])

-# Sample asset for template preview
+# Sample asset matching what build_asset_detail() actually returns
 _SAMPLE_ASSET = {
+    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "filename": "IMG_001.jpg",
    "type": "IMAGE",
    "created_at": "2026-03-19T10:30:00",
    "owner": "Alice",
+    "owner_id": "user-uuid-1",
    "description": "Family picnic",
-    "url": "https://immich.example.com/photos/abc123",
-    "download_url": "https://immich.example.com/api/assets/abc123/original",
-    "photo_url": "https://immich.example.com/api/assets/abc123/thumbnail",
-    "playback_url": "",
+    "people": ["Alice", "Bob"],
    "is_favorite": True,
    "rating": 5,
+    "latitude": 48.8566,
+    "longitude": 2.3522,
    "city": "Paris",
    "state": "Île-de-France",
    "country": "France",
+    "url": "https://immich.example.com/photos/abc123",
+    "download_url": "https://immich.example.com/api/assets/abc123/original",
+    "photo_url": "https://immich.example.com/api/assets/abc123/thumbnail",
+}
+
+_SAMPLE_VIDEO_ASSET = {
+    **_SAMPLE_ASSET,
+    "id": "d4e5f6a7-b8c9-0123-defg-456789abcdef",
+    "filename": "VID_002.mp4",
+    "type": "VIDEO",
+    "is_favorite": False,
+    "rating": None,
+    "photo_url": None,
+    "playback_url": "https://immich.example.com/api/assets/def456/video",
 }

 _SAMPLE_ALBUM = {
@@ -39,23 +54,26 @@ _SAMPLE_ALBUM = {
    "shared": True,
 }

-# Full context covering all possible template variables
+# Full context covering ALL possible template variables from _build_event_data()
 _SAMPLE_CONTEXT = {
-    # Event variables
+    # Core event fields (always present)
+    "album_id": "b2eeeaa4-bba0-477a-a06f-5cb9e21818e8",
    "album_name": "Family Photos",
    "album_url": "https://immich.example.com/share/abc123",
+    "change_type": "assets_added",
    "added_count": 3,
    "removed_count": 1,
-    "change_type": "assets_added",
-    "people": ["Alice", "Bob"],
-    "added_assets": [_SAMPLE_ASSET, {**_SAMPLE_ASSET, "filename": "VID_002.mp4", "type": "VIDEO", "is_favorite": False, "rating": None, "playback_url": "https://immich.example.com/api/assets/def456/video"}],
+    "added_assets": [_SAMPLE_ASSET, _SAMPLE_VIDEO_ASSET],
    "removed_assets": ["asset-id-1", "asset-id-2"],
+    "people": ["Alice", "Bob"],
    "shared": True,
    "video_warning": "\n\n⚠️ Note: Videos may not be sent due to Telegram's 50 MB file size limit.",
-    # Rename variables
+    # Rename fields (always present, empty for non-rename events)
    "old_name": "Old Album",
    "new_name": "New Album",
-    # Scheduled/periodic variables
+    "old_shared": False,
+    "new_shared": True,
+    # Scheduled/periodic variables (for those templates)
    "albums": [_SAMPLE_ALBUM, {**_SAMPLE_ALBUM, "name": "Vacation 2025", "asset_count": 120}],
    "assets": [_SAMPLE_ASSET, {**_SAMPLE_ASSET, "filename": "IMG_002.jpg", "city": "London", "country": "UK"}],
    "date": "2026-03-19",
--- a/packages/server/src/immich_watcher_server/api/template_vars.py
+++ b/packages/server/src/immich_watcher_server/api/template_vars.py
@@ -1,87 +1,127 @@
-"""Template variable reference for all template slots."""
+"""Template variable reference for all template slots.
+
+This must match what watcher._build_event_data() and
+core.asset_utils.build_asset_detail() actually produce.
+"""
+
+_ASSET_FIELDS = {
+    "id": "Asset ID (UUID)",
+    "filename": "Original filename",
+    "type": "IMAGE or VIDEO",
+    "created_at": "Creation date/time (ISO 8601)",
+    "owner": "Owner display name",
+    "owner_id": "Owner user ID",
+    "description": "User description or EXIF description",
+    "people": "People detected in this asset (list)",
+    "is_favorite": "Whether asset is favorited (boolean)",
+    "rating": "Star rating (1-5 or null)",
+    "latitude": "GPS latitude (float or null)",
+    "longitude": "GPS longitude (float or null)",
+    "city": "City name",
+    "state": "State/region name",
+    "country": "Country name",
+    "url": "Public viewer URL (if shared)",
+    "download_url": "Direct download URL (if shared)",
+    "photo_url": "Preview image URL (images only, if shared)",
+    "playback_url": "Video playback URL (videos only, if shared)",
+}
+
+_ALBUM_FIELDS = {
+    "name": "Album name",
+    "asset_count": "Total number of assets",
+    "url": "Public share URL",
+    "shared": "Whether album is shared",
+}

 TEMPLATE_VARIABLES: dict[str, dict] = {
    "message_assets_added": {
        "description": "Notification when new assets are added to an album",
        "variables": {
+            "album_id": "Album ID (UUID)",
            "album_name": "Album name",
-            "album_url": "Public share URL (if available)",
+            "album_url": "Public share URL (empty if not shared)",
+            "change_type": "Always 'assets_added'",
            "added_count": "Number of assets added",
-            "removed_count": "Number of assets removed",
-            "change_type": "Type of change (assets_added)",
-            "people": "List of detected people names (use {{ people | join(', ') }})",
-            "added_assets": "List of asset dicts (use {% for asset in added_assets %})",
-            "shared": "Whether album is shared (true/false)",
-            "video_warning": "Video size warning text (if videos present)",
-        },
-        "asset_fields": {
-            "filename": "Original filename",
-            "type": "IMAGE or VIDEO",
-            "created_at": "Creation date/time (ISO 8601)",
-            "owner": "Owner display name",
-            "description": "User description or EXIF description",
-            "url": "Public viewer URL",
-            "download_url": "Direct download URL",
-            "photo_url": "Preview image URL (images only)",
-            "playback_url": "Video playback URL (videos only)",
-            "is_favorite": "Whether asset is favorited (boolean)",
-            "rating": "Star rating (1-5 or null)",
-            "city": "City name",
-            "state": "State/region name",
-            "country": "Country name",
-            "people": "People detected in this asset (list)",
+            "removed_count": "Always 0",
+            "added_assets": "List of asset dicts ({% for asset in added_assets %})",
+            "removed_assets": "Always empty list",
+            "people": "Detected people across all added assets (list of strings)",
+            "shared": "Whether album is shared (boolean)",
+            "video_warning": "Video size warning text (set from template config if videos present)",
+            "old_name": "Always empty (for rename events)",
+            "new_name": "Always empty (for rename events)",
        },
+        "asset_fields": _ASSET_FIELDS,
    },
    "message_assets_removed": {
-        "description": "Notification when assets are removed",
+        "description": "Notification when assets are removed from an album",
        "variables": {
+            "album_id": "Album ID (UUID)",
            "album_name": "Album name",
-            "album_url": "Public share URL",
+            "album_url": "Public share URL (empty if not shared)",
+            "change_type": "Always 'assets_removed'",
+            "added_count": "Always 0",
            "removed_count": "Number of assets removed",
-            "removed_assets": "List of removed asset IDs",
-            "change_type": "Type of change (assets_removed)",
+            "added_assets": "Always empty list",
+            "removed_assets": "List of removed asset IDs (strings)",
+            "people": "People in the album (list of strings)",
+            "shared": "Whether album is shared (boolean)",
+            "video_warning": "Always empty",
+            "old_name": "Always empty",
+            "new_name": "Always empty",
        },
    },
    "message_album_renamed": {
-        "description": "Notification when album is renamed",
+        "description": "Notification when an album is renamed",
        "variables": {
+            "album_id": "Album ID (UUID)",
+            "album_name": "Current album name (same as new_name)",
+            "album_url": "Public share URL (empty if not shared)",
+            "change_type": "Always 'album_renamed'",
            "old_name": "Previous album name",
            "new_name": "New album name",
-            "album_url": "Public share URL",
+            "old_shared": "Was album shared before (boolean)",
+            "new_shared": "Is album shared now (boolean)",
+            "shared": "Whether album is currently shared",
+            "people": "People in the album (list)",
+            "added_count": "Always 0",
+            "removed_count": "Always 0",
        },
    },
    "message_album_deleted": {
-        "description": "Notification when album is deleted",
+        "description": "Notification when an album is deleted",
        "variables": {
-            "album_name": "Album name",
+            "album_id": "Album ID (UUID)",
+            "album_name": "Album name (before deletion)",
+            "change_type": "Always 'album_deleted'",
+            "shared": "Whether album was shared",
        },
    },
    "periodic_summary_message": {
-        "description": "Periodic album summary",
+        "description": "Periodic album summary (not yet implemented in scheduler)",
        "variables": {
-            "albums": "List of album dicts (use {% for album in albums %})",
-        },
-        "album_fields": {
-            "name": "Album name",
-            "asset_count": "Number of assets",
-            "url": "Public share URL",
+            "albums": "List of album dicts ({% for album in albums %})",
+            "date": "Current date string",
        },
+        "album_fields": _ALBUM_FIELDS,
    },
    "scheduled_assets_message": {
-        "description": "Scheduled asset delivery",
+        "description": "Scheduled asset delivery (not yet implemented in scheduler)",
        "variables": {
            "album_name": "Album name (empty in combined mode)",
            "album_url": "Public share URL",
-            "assets": "List of asset dicts (use {% for asset in assets %})",
+            "assets": "List of asset dicts ({% for asset in assets %})",
+            "date": "Current date string",
        },
-        "asset_fields": "(same as message_assets_added.asset_fields)",
+        "asset_fields": _ASSET_FIELDS,
    },
    "memory_mode_message": {
-        "description": "On This Day memory notification",
+        "description": "On This Day memory notification (not yet implemented in scheduler)",
        "variables": {
            "album_name": "Album name (empty in combined mode)",
-            "assets": "List of asset dicts (use {% for asset in assets %})",
+            "assets": "List of asset dicts ({% for asset in assets %})",
+            "date": "Current date string",
        },
-        "asset_fields": "(same as message_assets_added.asset_fields)",
+        "asset_fields": _ASSET_FIELDS,
    },
 }