Add HAOS-Server sync for optional centralized management (Phase 5)

Enable the HAOS integration to optionally connect to the standalone
Immich Watcher server for config sync and event reporting.

Server-side:
- New /api/sync/* endpoints: GET trackers, POST template render,
  POST event report
- API key auth via X-API-Key header (accepts JWT access tokens)

Integration-side:
- New sync.py: ServerSyncClient with graceful error handling
  (all methods return defaults on connection failure)
- Options flow: optional server_url and server_api_key fields
  with connection validation
- Coordinator: fire-and-forget event reporting to server when
  album changes are detected
- Translations: en.json and ru.json updated with new fields

The connection is fully additive -- the integration works identically
without a server URL configured. Server failures never break HA.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

custom_components/immich_album_watcher/__init__.py

@@ -18,6 +18,8 @@ from .const import (
     CONF_HUB_NAME,
     CONF_IMMICH_URL,
     CONF_SCAN_INTERVAL,
+    CONF_SERVER_API_KEY,
+    CONF_SERVER_URL,
     CONF_TELEGRAM_CACHE_TTL,
     DEFAULT_SCAN_INTERVAL,
     DEFAULT_TELEGRAM_CACHE_TTL,
@@ -98,6 +100,15 @@ async def async_setup_entry(hass: HomeAssistant, entry: ImmichConfigEntry) -> bo
     notification_queue = create_notification_queue(hass, entry.entry_id)
     await notification_queue.async_load()
 
+    # Create optional server sync client
+    server_url = entry.options.get(CONF_SERVER_URL, "")
+    server_api_key = entry.options.get(CONF_SERVER_API_KEY, "")
+    sync_client = None
+    if server_url and server_api_key:
+        from .sync import ServerSyncClient
+        sync_client = ServerSyncClient(hass, server_url, server_api_key)
+        _LOGGER.info("Server sync enabled: %s", server_url)
+
     # Store hub reference
     hass.data[DOMAIN][entry.entry_id] = {
         "hub": entry.runtime_data,
@@ -106,6 +117,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ImmichConfigEntry) -> bo
         "telegram_cache": telegram_cache,
         "telegram_asset_cache": telegram_asset_cache,
         "notification_queue": notification_queue,
+        "sync_client": sync_client,
         "quiet_hours_unsubs": {},  # keyed by "HH:MM" end time
     }
 
@@ -161,6 +173,7 @@ async def _async_setup_subentry_coordinator(
         storage=storage,
         telegram_cache=telegram_cache,
         telegram_asset_cache=telegram_asset_cache,
+        sync_client=hass.data[DOMAIN][entry.entry_id].get("sync_client"),
     )
 
     # Load persisted state before first refresh to detect changes during downtime

custom_components/immich_album_watcher/config_flow.py

@@ -26,6 +26,8 @@ from .const import (
     CONF_HUB_NAME,
     CONF_IMMICH_URL,
     CONF_SCAN_INTERVAL,
+    CONF_SERVER_API_KEY,
+    CONF_SERVER_URL,
     CONF_TELEGRAM_BOT_TOKEN,
     CONF_TELEGRAM_CACHE_TTL,
     DEFAULT_SCAN_INTERVAL,
@@ -244,21 +246,40 @@ class ImmichAlbumWatcherOptionsFlow(OptionsFlow):
         self, user_input: dict[str, Any] | None = None
     ) -> ConfigFlowResult:
         """Manage the options."""
+        errors: dict[str, str] = {}
+
         if user_input is not None:
-            return self.async_create_entry(
-                title="",
-                data={
-                    CONF_SCAN_INTERVAL: user_input.get(
-                        CONF_SCAN_INTERVAL, DEFAULT_SCAN_INTERVAL
-                    ),
-                    CONF_TELEGRAM_BOT_TOKEN: user_input.get(
-                        CONF_TELEGRAM_BOT_TOKEN, ""
-                    ),
-                    CONF_TELEGRAM_CACHE_TTL: user_input.get(
-                        CONF_TELEGRAM_CACHE_TTL, DEFAULT_TELEGRAM_CACHE_TTL
-                    ),
-                },
-            )
+            # Validate server connection if URL is provided
+            server_url = user_input.get(CONF_SERVER_URL, "").strip()
+            server_api_key = user_input.get(CONF_SERVER_API_KEY, "").strip()
+            if server_url and server_api_key:
+                try:
+                    session = async_get_clientsession(self.hass)
+                    async with session.get(
+                        f"{server_url.rstrip('/')}/api/health"
+                    ) as response:
+                        if response.status != 200:
+                            errors["base"] = "server_connect_failed"
+                except Exception:
+                    errors["base"] = "server_connect_failed"
+
+            if not errors:
+                return self.async_create_entry(
+                    title="",
+                    data={
+                        CONF_SCAN_INTERVAL: user_input.get(
+                            CONF_SCAN_INTERVAL, DEFAULT_SCAN_INTERVAL
+                        ),
+                        CONF_TELEGRAM_BOT_TOKEN: user_input.get(
+                            CONF_TELEGRAM_BOT_TOKEN, ""
+                        ),
+                        CONF_TELEGRAM_CACHE_TTL: user_input.get(
+                            CONF_TELEGRAM_CACHE_TTL, DEFAULT_TELEGRAM_CACHE_TTL
+                        ),
+                        CONF_SERVER_URL: server_url,
+                        CONF_SERVER_API_KEY: server_api_key,
+                    },
+                )
 
         return self.async_show_form(
             step_id="init",
@@ -276,6 +297,12 @@ class ImmichAlbumWatcherOptionsFlow(OptionsFlow):
         current_cache_ttl = self._config_entry.options.get(
             CONF_TELEGRAM_CACHE_TTL, DEFAULT_TELEGRAM_CACHE_TTL
         )
+        current_server_url = self._config_entry.options.get(
+            CONF_SERVER_URL, ""
+        )
+        current_server_api_key = self._config_entry.options.get(
+            CONF_SERVER_API_KEY, ""
+        )
 
         return vol.Schema(
             {
@@ -288,6 +315,13 @@ class ImmichAlbumWatcherOptionsFlow(OptionsFlow):
                 vol.Optional(
                     CONF_TELEGRAM_CACHE_TTL, default=current_cache_ttl
                 ): vol.All(vol.Coerce(int), vol.Range(min=1, max=168)),
+                vol.Optional(
+                    CONF_SERVER_URL, default=current_server_url,
+                    description={"suggested_value": current_server_url},
+                ): str,
+                vol.Optional(
+                    CONF_SERVER_API_KEY, default=current_server_api_key,
+                ): str,
             }
         )
 

custom_components/immich_album_watcher/const.py

@@ -66,6 +66,8 @@ CONF_ALBUM_NAME: Final = "album_name"
 CONF_SCAN_INTERVAL: Final = "scan_interval"
 CONF_TELEGRAM_BOT_TOKEN: Final = "telegram_bot_token"
 CONF_TELEGRAM_CACHE_TTL: Final = "telegram_cache_ttl"
+CONF_SERVER_URL: Final = "server_url"
+CONF_SERVER_API_KEY: Final = "server_api_key"
 
 # Subentry type
 SUBENTRY_TYPE_ALBUM: Final = "album"

custom_components/immich_album_watcher/coordinator.py

@@ -95,6 +95,7 @@ class ImmichAlbumWatcherCoordinator(DataUpdateCoordinator[AlbumData | None]):
         storage: ImmichAlbumStorage | None = None,
         telegram_cache: TelegramFileCache | None = None,
         telegram_asset_cache: TelegramFileCache | None = None,
+        sync_client: Any | None = None,
     ) -> None:
         """Initialize the coordinator."""
         super().__init__(
@@ -110,6 +111,7 @@ class ImmichAlbumWatcherCoordinator(DataUpdateCoordinator[AlbumData | None]):
         self._storage = storage
         self._telegram_cache = telegram_cache
         self._telegram_asset_cache = telegram_asset_cache
+        self._sync_client = sync_client
         self._persisted_asset_ids: set[str] | None = None
         self._pending_asset_ids: set[str] = set()
 
@@ -523,3 +525,18 @@ class ImmichAlbumWatcherCoordinator(DataUpdateCoordinator[AlbumData | None]):
                 change.old_shared,
                 change.new_shared,
             )
+
+        # Report event to standalone server (fire-and-forget)
+        if self._sync_client:
+            self.hass.async_create_task(
+                self._sync_client.async_report_event(
+                    tracker_name=self._hub_name,
+                    event_type=change.change_type,
+                    album_id=change.album_id,
+                    album_name=change.album_name,
+                    details={
+                        "added_count": change.added_count,
+                        "removed_count": change.removed_count,
+                    },
+                )
+            )

custom_components/immich_album_watcher/sync.py

@@ -0,0 +1,123 @@
+"""Optional sync with the standalone Immich Watcher server."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import aiohttp
+
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.aiohttp_client import async_get_clientsession
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class ServerSyncClient:
+    """Client for communicating with the standalone Immich Watcher server.
+
+    All methods are safe to call even if the server is unreachable --
+    they log warnings and return empty/default values. The HA integration
+    must never break due to server connectivity issues.
+    """
+
+    def __init__(self, hass: HomeAssistant, server_url: str, api_key: str) -> None:
+        self._hass = hass
+        self._base_url = server_url.rstrip("/")
+        self._api_key = api_key
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {"X-API-Key": self._api_key, "Content-Type": "application/json"}
+
+    async def async_get_trackers(self) -> list[dict[str, Any]]:
+        """Fetch tracker configurations from the server.
+
+        Returns empty list on any error.
+        """
+        try:
+            session = async_get_clientsession(self._hass)
+            async with session.get(
+                f"{self._base_url}/api/sync/trackers",
+                headers=self._headers,
+            ) as response:
+                if response.status == 200:
+                    return await response.json()
+                _LOGGER.warning(
+                    "Server sync: failed to fetch trackers (HTTP %d)", response.status
+                )
+        except aiohttp.ClientError as err:
+            _LOGGER.warning("Server sync: connection failed: %s", err)
+        return []
+
+    async def async_render_template(
+        self, template_id: int, context: dict[str, Any]
+    ) -> str | None:
+        """Render a server-managed template with context.
+
+        Returns None on any error.
+        """
+        try:
+            session = async_get_clientsession(self._hass)
+            async with session.post(
+                f"{self._base_url}/api/sync/templates/{template_id}/render",
+                headers=self._headers,
+                json={"context": context},
+            ) as response:
+                if response.status == 200:
+                    data = await response.json()
+                    return data.get("rendered")
+                _LOGGER.warning(
+                    "Server sync: template render failed (HTTP %d)", response.status
+                )
+        except aiohttp.ClientError as err:
+            _LOGGER.warning("Server sync: template render connection failed: %s", err)
+        return None
+
+    async def async_report_event(
+        self,
+        tracker_name: str,
+        event_type: str,
+        album_id: str,
+        album_name: str,
+        details: dict[str, Any] | None = None,
+    ) -> bool:
+        """Report a detected event to the server for logging.
+
+        Returns True if successfully reported, False on any error.
+        Fire-and-forget -- failures are logged but don't affect HA operation.
+        """
+        try:
+            session = async_get_clientsession(self._hass)
+            payload = {
+                "tracker_name": tracker_name,
+                "event_type": event_type,
+                "album_id": album_id,
+                "album_name": album_name,
+                "details": details or {},
+            }
+            async with session.post(
+                f"{self._base_url}/api/sync/events",
+                headers=self._headers,
+                json=payload,
+            ) as response:
+                if response.status == 200:
+                    _LOGGER.debug("Server sync: event reported for album '%s'", album_name)
+                    return True
+                _LOGGER.debug(
+                    "Server sync: event report failed (HTTP %d)", response.status
+                )
+        except aiohttp.ClientError as err:
+            _LOGGER.debug("Server sync: event report connection failed: %s", err)
+        return False
+
+    async def async_check_connection(self) -> bool:
+        """Check if the server is reachable."""
+        try:
+            session = async_get_clientsession(self._hass)
+            async with session.get(
+                f"{self._base_url}/api/health",
+            ) as response:
+                return response.status == 200
+        except aiohttp.ClientError:
+            return False

custom_components/immich_album_watcher/translations/en.json

@@ -80,7 +80,8 @@
             "cannot_connect": "Failed to connect to Immich server",
             "invalid_auth": "Invalid API key",
             "no_albums": "No albums found on the server",
-            "unknown": "Unexpected error occurred"
+            "unknown": "Unexpected error occurred",
+            "server_connect_failed": "Failed to connect to Immich Watcher server"
         },
         "abort": {
             "already_configured": "This Immich server is already configured"
@@ -120,12 +121,16 @@
                 "data": {
                     "scan_interval": "Scan interval (seconds)",
                     "telegram_bot_token": "Telegram Bot Token",
-                    "telegram_cache_ttl": "Telegram Cache TTL (hours)"
+                    "telegram_cache_ttl": "Telegram Cache TTL (hours)",
+                    "server_url": "Watcher Server URL (optional)",
+                    "server_api_key": "Watcher Server API Key (optional)"
                 },
                 "data_description": {
                     "scan_interval": "How often to check for album changes (10-3600 seconds)",
                     "telegram_bot_token": "Bot token for sending notifications to Telegram",
-                    "telegram_cache_ttl": "How long to cache uploaded file IDs to avoid re-uploading (1-168 hours, default: 48)"
+                    "telegram_cache_ttl": "How long to cache uploaded file IDs to avoid re-uploading (1-168 hours, default: 48)",
+                    "server_url": "URL of the standalone Immich Watcher server for config sync and event reporting (leave empty to disable)",
+                    "server_api_key": "API key (JWT access token) for authenticating with the Watcher server"
                 }
             }
         }

custom_components/immich_album_watcher/translations/ru.json

@@ -120,12 +120,16 @@
                 "data": {
                     "scan_interval": "Интервал сканирования (секунды)",
                     "telegram_bot_token": "Токен Telegram бота",
-                    "telegram_cache_ttl": "Время жизни кэша Telegram (часы)"
+                    "telegram_cache_ttl": "Время жизни кэша Telegram (часы)",
+                    "server_url": "URL сервера Watcher (необязательно)",
+                    "server_api_key": "API ключ сервера Watcher (необязательно)"
                 },
                 "data_description": {
                     "scan_interval": "Как часто проверять изменения в альбомах (10-3600 секунд)",
                     "telegram_bot_token": "Токен бота для отправки уведомлений в Telegram",
-                    "telegram_cache_ttl": "Сколько хранить ID загруженных файлов для повторной отправки без загрузки (1-168 часов, по умолчанию: 48)"
+                    "telegram_cache_ttl": "Сколько хранить ID загруженных файлов для повторной отправки без загрузки (1-168 часов, по умолчанию: 48)",
+                    "server_url": "URL автономного сервера Immich Watcher для синхронизации конфигурации и отчётов о событиях (оставьте пустым для отключения)",
+                    "server_api_key": "API ключ (JWT токен) для аутентификации на сервере Watcher"
                 }
             }
         }