haos-hacs-immich-album-watcher/plans/phase-2-haos-refactor.md

Phase 2: Wire Core Library into HAOS Integration

Status: In progress Parent: primary-plan.md

---

Goal

Refactor the HAOS integration to delegate to immich-watcher-core for all HA-independent logic, reducing duplication and preparing for the standalone server.

---

Important: HACS Compatibility

HACS requires custom_components/<domain>/ at the repository root. We cannot move it to packages/haos/. Instead:

• custom_components/ stays at repo root
• The integration imports from immich_watcher_core (the core library)
• manifest.json lists immich-watcher-core in requirements (for future PyPI publish)
• During development, pip install -e packages/core makes imports work
• For HACS distribution, we'll publish the core to PyPI

---

Tasks

1. Update manifest.json [ ]

• Add immich-watcher-core to requirements list
• Do NOT bump version (only plans/core changed, not integration content yet)

2. Refactor const.py [ ]

• Import shared constants from immich_watcher_core.constants
• Keep HA-specific constants (DOMAIN, CONF_, PLATFORMS, SERVICE_) local
• Re-export shared constants for backward compatibility with other integration files

3. Refactor storage.py [ ]

• Create HAStorageBackend adapter wrapping homeassistant.helpers.storage.Store that satisfies StorageBackend protocol from core
• Replace TelegramFileCache with core's version using HAStorageBackend
• Replace NotificationQueue with core's version using HAStorageBackend
• Keep ImmichAlbumStorage as-is (HA-specific album state management)

4. Refactor coordinator.py [ ]

• Remove dataclass definitions (SharedLinkInfo, AssetInfo, AlbumData, AlbumChange) — import from core
• Replace Immich API methods with ImmichClient from core
• Replace _detect_change() with detect_album_changes() from core
• Replace _build_asset_detail() and URL helpers with asset_utils from core
• Replace async_get_assets() filtering/sorting with filter_assets() + sort_assets() from core
• Keep HA-specific: DataUpdateCoordinator subclass, _fire_events(), async_get_clientsession()

5. Refactor sensor.py [ ]

• Remove Telegram constants, helper functions, and all _send_telegram_* methods
• Replace with TelegramClient from core in _execute_telegram_notification()
• Keep HA-specific: entity classes, service registration, platform setup

6. Update init.py [ ]

• Update imports for new storage classes (HAStorageBackend adapter)
• Create TelegramFileCache instances using core class + HA adapter

7. Verify [ ]

• All existing entities, services, and events work identically
• Telegram notifications work with caching
• Quiet hours queueing works
• No HA import in core library (verify with grep)

---

Acceptance Criteria

• Integration imports and delegates to immich_watcher_core
• Zero behavior changes for end users
• No duplicated logic between core and integration
• Core library has no HA imports (verified)
• ImmichAlbumStorage is the only storage class still HA-native