uiprotect 3.8.0__py3-none-any.whl → 7.32.0__py3-none-any.whl

uiprotect/data/nvr.py

@@ -15,11 +15,12 @@ from uuid import UUID
 
 import aiofiles
 import orjson
-from aiofiles import os as aos
-from pydantic.v1.fields import PrivateAttr
+from convertertools import pop_dict_set_if_none, pop_dict_tuple
+from pydantic import ConfigDict
+from pydantic.fields import PrivateAttr
 
 from ..exceptions import BadRequest, NotAuthorized
-from ..utils import RELEASE_CACHE, convert_to_datetime
+from ..utils import convert_to_datetime
 from .base import (
     ProtectBaseObject,
     ProtectDeviceModel,
@@ -45,7 +46,6 @@ from .types import (
     ModelType,
     MountType,
     PercentFloat,
-    PercentInt,
     PermissionNode,
     ProgressCallback,
     RecordingMode,
@@ -60,7 +60,7 @@ from .types import (
 from .user import User, UserLocation
 
 if TYPE_CHECKING:
-    from pydantic.v1.typing import SetStr
+    from pydantic.typing import SetStr
 
 
 _LOGGER = logging.getLogger(__name__)
@@ -70,27 +70,46 @@ DELETE_KEYS_THUMB = {"color", "vehicleType"}
 DELETE_KEYS_EVENT = {"deletedAt", "category", "subCategory"}
 
 
+class MetaInfo(ProtectBaseObject):
+    applicationVersion: str
+
+
 class NVRLocation(UserLocation):
     is_geofencing_enabled: bool
     radius: int
     model: ModelType | None = None
 
 
+class SmartDetectItemAttribute(ProtectBaseObject):
+    """Attribute value with confidence for smart detect items (e.g., color, vehicle type)."""
+
+    val: str
+    confidence: int
+
+
 class SmartDetectItem(ProtectBaseObject):
     id: str
     timestamp: datetime
-    level: PercentInt
     coord: tuple[int, int, int, int]
     object_type: SmartDetectObjectType
     zone_ids: list[int]
     duration: timedelta
+    confidence: int
+    first_shown_time_ms: int
+    idle_since_time_ms: int
+    stationary: bool
+    license_plate: str | None = None  # only populated for vehicle object_type
+    depth: float | None = None
+    speed: float | None = None
+    attributes: dict[str, SmartDetectItemAttribute] | None = None
+    lines: list[int] | None = None
 
     @classmethod
     @cache
     def _get_unifi_remaps(cls) -> dict[str, str]:
         return {
             **super()._get_unifi_remaps(),
-            "zones": "zoneIds",
+            "zones": "zone_ids",
         }
 
     @classmethod
@@ -125,9 +144,22 @@ class SmartDetectTrack(ProtectBaseObject):
         return self._api.bootstrap.events.get(self.event_id)
 
 
-class LicensePlateMetadata(ProtectBaseObject):
-    name: str
-    confidence_level: int
+class EventThumbnailGroup(ProtectBaseObject):
+    """Group information for detected thumbnails (e.g., license plate recognition)."""
+
+    id: str
+    name: str | None = None
+    matched_name: str | None = None
+    confidence: int
+
+    def unifi_dict(
+        self,
+        data: dict[str, Any] | None = None,
+        exclude: set[str] | None = None,
+    ) -> dict[str, Any]:
+        data = super().unifi_dict(data=data, exclude=exclude)
+        pop_dict_set_if_none(data, {"matchedName", "name"})
+        return data
 
 
 class EventThumbnailAttribute(ProtectBaseObject):
@@ -135,9 +167,75 @@ class EventThumbnailAttribute(ProtectBaseObject):
     val: str
 
 
+class NfcMetadata(ProtectBaseObject):
+    nfc_id: str
+    user_id: str
+
+    @classmethod
+    @cache
+    def _get_unifi_remaps(cls) -> dict[str, str]:
+        return {
+            **super()._get_unifi_remaps(),
+            "nfcId": "nfc_id",
+            "userId": "user_id",
+        }
+
+
+class FingerprintMetadata(ProtectBaseObject):
+    ulp_id: str | None = None
+
+    @classmethod
+    @cache
+    def _get_unifi_remaps(cls) -> dict[str, str]:
+        return {
+            **super()._get_unifi_remaps(),
+            "ulpId": "ulp_id",
+        }
+
+
 class EventThumbnailAttributes(ProtectBaseObject):
-    color: EventThumbnailAttribute | None = None
-    vehicle_type: EventThumbnailAttribute | None = None
+    """
+    Dynamic attributes for detected thumbnails.
+
+    All attributes are stored as extra fields for full flexibility.
+
+    Common attribute types:
+    - color, vehicleType, faceMask: EventThumbnailAttribute (with val and confidence)
+    - zone: list[int] - Zone IDs where detection occurred
+    - trackerId: int - Unique tracker ID for this detection
+
+    Allows any attributes for forward compatibility with new UFP features.
+
+    Example usage:
+        >>> attrs = thumbnail.attributes
+        >>> if attrs:
+        ...     # Access EventThumbnailAttribute objects
+        ...     color = attrs.color  # EventThumbnailAttribute
+        ...     if color:
+        ...         print(f"Color: {color.val} (confidence: {color.confidence})")
+        ...     # Access primitive types
+        ...     zones = attrs.zone  # list[int] | None
+        ...     tracker = attrs.trackerId  # int | None
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    def get_value(self, key: str) -> str | None:
+        """Get the string value from an EventThumbnailAttribute field, if it exists."""
+        attr = getattr(self, key, None)
+        if isinstance(attr, EventThumbnailAttribute):
+            return attr.val
+        return None
+
+    @classmethod
+    def unifi_dict_to_dict(cls, data: dict[str, Any]) -> dict[str, Any]:
+        # Convert nested attribute objects to EventThumbnailAttribute instances
+        return {
+            key: EventThumbnailAttribute.from_unifi_dict(**value)
+            if isinstance(value, dict) and "val" in value and "confidence" in value
+            else value
+            for key, value in data.items()
+        }
 
     def unifi_dict(
         self,
@@ -146,11 +244,8 @@ class EventThumbnailAttributes(ProtectBaseObject):
     ) -> dict[str, Any]:
         data = super().unifi_dict(data=data, exclude=exclude)
 
-        for key in DELETE_KEYS_THUMB.intersection(data):
-            if data[key] is None:
-                del data[key]
-
-        return data
+        # Remove None values from extra fields
+        return {k: v for k, v in data.items() if v is not None}
 
 
 class EventDetectedThumbnail(ProtectBaseObject):
@@ -158,7 +253,12 @@ class EventDetectedThumbnail(ProtectBaseObject):
     type: str
     cropped_id: str
     attributes: EventThumbnailAttributes | None = None
-    name: str | None
+    name: str | None = None
+    coord: list[int] | None = None
+    confidence: int | None = None
+    # requires 6.0.0+
+    group: EventThumbnailGroup | None = None
+    object_id: str | None = None
 
     @classmethod
     @cache
@@ -171,36 +271,34 @@ class EventDetectedThumbnail(ProtectBaseObject):
         exclude: set[str] | None = None,
     ) -> dict[str, Any]:
         data = super().unifi_dict(data=data, exclude=exclude)
-
-        if "name" in data and data["name"] is None:
-            del data["name"]
-
+        pop_dict_set_if_none(data, {"name", "group", "objectId", "coord", "confidence"})
         return data
 
 
 class EventMetadata(ProtectBaseObject):
-    client_platform: str | None
-    reason: str | None
-    app_update: str | None
-    light_id: str | None
-    light_name: str | None
-    type: str | None
-    sensor_id: str | None
-    sensor_name: str | None
-    sensor_type: SensorType | None
-    doorlock_id: str | None
-    doorlock_name: str | None
-    from_value: str | None
-    to_value: str | None
-    mount_type: MountType | None
-    status: SensorStatusType | None
-    alarm_type: str | None
-    device_id: str | None
-    mac: str | None
-    # require 2.7.5+
-    license_plate: LicensePlateMetadata | None = None
+    client_platform: str | None = None
+    reason: str | None = None
+    app_update: str | None = None
+    light_id: str | None = None
+    light_name: str | None = None
+    type: str | None = None
+    sensor_id: str | None = None
+    sensor_name: str | None = None
+    sensor_type: SensorType | None = None
+    doorlock_id: str | None = None
+    doorlock_name: str | None = None
+    from_value: str | None = None
+    to_value: str | None = None
+    mount_type: MountType | None = None
+    status: SensorStatusType | None = None
+    alarm_type: str | None = None
+    device_id: str | None = None
+    mac: str | None = None
     # requires 2.11.13+
     detected_thumbnails: list[EventDetectedThumbnail] | None = None
+    # requires 5.1.34+
+    nfc: NfcMetadata | None = None
+    fingerprint: FingerprintMetadata | None = None
 
     _collapse_keys: ClassVar[SetStr] = {
         "lightId",
@@ -258,22 +356,25 @@ class EventMetadata(ProtectBaseObject):
 class Event(ProtectModelWithId):
     type: EventType
     start: datetime
-    end: datetime | None
+    end: datetime | None = None
     score: int
-    heatmap_id: str | None
-    camera_id: str | None
+    heatmap_id: str | None = None
+    camera_id: str | None = None
     smart_detect_types: list[SmartDetectObjectType]
     smart_detect_event_ids: list[str]
-    thumbnail_id: str | None
-    user_id: str | None
-    timestamp: datetime | None
-    metadata: EventMetadata | None
+    thumbnail_id: str | None = None
+    user_id: str | None = None
+    timestamp: datetime | None = None
+    metadata: EventMetadata | None = None
     # requires 2.7.5+
     deleted_at: datetime | None = None
     deletion_type: Literal["manual", "automatic"] | None = None
     # only appears if `get_events` is called with category
     category: EventCategories | None = None
     sub_category: str | None = None
+    # requires 6.0.0+
+    is_favorite: bool | None = None
+    favorite_object_ids: list[str] | None = None
 
     # TODO:
     # partition
@@ -298,10 +399,12 @@ class Event(ProtectModelWithId):
     @classmethod
     @cache
     def unifi_dict_conversions(cls) -> dict[str, object | Callable[[Any], Any]]:
-        return {
-            key: convert_to_datetime
-            for key in ("start", "end", "timestamp", "deletedAt")
-        } | super().unifi_dict_conversions()
+        return (
+            dict.fromkeys(
+                ("start", "end", "timestamp", "deletedAt"), convert_to_datetime
+            )
+            | super().unifi_dict_conversions()
+        )
 
     def unifi_dict(
         self,
@@ -309,11 +412,7 @@ class Event(ProtectModelWithId):
         exclude: set[str] | None = None,
     ) -> dict[str, Any]:
         data = super().unifi_dict(data=data, exclude=exclude)
-
-        for key in DELETE_KEYS_EVENT.intersection(data):
-            if data[key] is None:
-                del data[key]
-
+        pop_dict_set_if_none(data, DELETE_KEYS_EVENT)
         return data
 
     @property
@@ -356,6 +455,45 @@ class Event(ProtectModelWithId):
         ]
         return self._smart_detect_events
 
+    def get_detected_thumbnail(self) -> EventDetectedThumbnail | None:
+        """
+        Gets best detected thumbnail for event (UFP 6.x+).
+
+        Returns the thumbnail marked with clockBestWall, which indicates
+        the optimal frame for this detection (highest confidence, best angle, etc.).
+
+        Returns:
+            EventDetectedThumbnail with the best detection frame, or None if:
+            - Event has no metadata
+            - No detected thumbnails available
+            - No thumbnail has clockBestWall set
+
+        Example usage:
+            >>> # License Plate Recognition
+            >>> thumbnail = event.get_detected_thumbnail()
+            >>> if thumbnail and thumbnail.group:
+            ...     plate = thumbnail.group.matched_name  # "ABC123"
+            ...     confidence = thumbnail.group.confidence  # 95
+            ...     if thumbnail.attributes:
+            ...         color = thumbnail.attributes.get_value("color")  # "white"
+            ...         vehicle = thumbnail.attributes.get_value("vehicleType")  # "sedan"
+
+            >>> # Face Detection
+            >>> thumbnail = event.get_detected_thumbnail()
+            >>> if thumbnail and thumbnail.group:
+            ...     face_name = thumbnail.group.matched_name  # "John Doe"
+            ...     confidence = thumbnail.group.confidence  # 87
+
+        """
+        if not self.metadata or not self.metadata.detected_thumbnails:
+            return None
+
+        for thumbnail in self.metadata.detected_thumbnails:
+            if thumbnail.clock_best_wall:
+                return thumbnail
+
+        return None
+
     async def get_thumbnail(
         self,
         width: int | None = None,
@@ -532,9 +670,9 @@ class CPUInfo(ProtectBaseObject):
 
 
 class MemoryInfo(ProtectBaseObject):
-    available: int | None
-    free: int | None
-    total: int | None
+    available: int | None = None
+    free: int | None = None
+    total: int | None = None
 
 
 class StorageDevice(ProtectBaseObject):
@@ -632,30 +770,29 @@ class UOSDisk(ProtectBaseObject):
             data["estimate"] /= 1000
 
         if "state" in data and data["state"] == "nodisk":
-            delete_keys = [
-                "action",
-                "ata",
-                "bad_sector",
-                "estimate",
-                "firmware",
-                "healthy",
-                "life_span",
-                "model",
-                "poweronhrs",
-                "progress",
-                "reason",
-                "rpm",
-                "sata",
-                "serial",
-                "tempature",
-                "temperature",
-                "threshold",
-                "type",
-            ]
-            for key in delete_keys:
-                if key in data:
-                    del data[key]
-
+            pop_dict_tuple(
+                data,
+                (
+                    "action",
+                    "ata",
+                    "bad_sector",
+                    "estimate",
+                    "firmware",
+                    "healthy",
+                    "life_span",
+                    "model",
+                    "poweronhrs",
+                    "progress",
+                    "reason",
+                    "rpm",
+                    "sata",
+                    "serial",
+                    "tempature",
+                    "temperature",
+                    "threshold",
+                    "type",
+                ),
+            )
         return data
 
     @property
@@ -739,10 +876,7 @@ class SystemInfo(ProtectBaseObject):
         exclude: set[str] | None = None,
     ) -> dict[str, Any]:
         data = super().unifi_dict(data=data, exclude=exclude)
-
-        if data is not None and "ustorage" in data and data["ustorage"] is None:
-            del data["ustorage"]
-
+        pop_dict_set_if_none(data, {"ustorage"})
         return data
 
 
@@ -853,8 +987,8 @@ class StorageDistribution(ProtectBaseObject):
 
 class StorageStats(ProtectBaseObject):
     utilization: float
-    capacity: timedelta | None
-    remaining_capacity: timedelta | None
+    capacity: timedelta | None = None
+    remaining_capacity: timedelta | None = None
     recording_space: StorageSpace
     storage_distribution: StorageDistribution
 
@@ -901,7 +1035,7 @@ class NVR(ProtectDeviceModel):
     ucore_version: str
     hardware_platform: str
     ports: PortConfig
-    last_update_at: datetime | None
+    last_update_at: datetime | None = None
     is_station: bool
     enable_automatic_backups: bool
     enable_stats_reporting: bool
@@ -912,14 +1046,14 @@ class NVR(ProtectDeviceModel):
     host_type: int
     host_shortname: str
     is_hardware: bool
-    is_wireless_uplink_enabled: bool | None
+    is_wireless_uplink_enabled: bool | None = None
     time_format: Literal["12h", "24h"]
     temperature_unit: Literal["C", "F"]
-    recording_retention_duration: timedelta | None
+    recording_retention_duration: timedelta | None = None
     enable_crash_reporting: bool
     disable_audio: bool
     analytics_data: AnalyticsOption
-    anonymous_device_id: UUID | None
+    anonymous_device_id: UUID | None = None
     camera_utilization: int
     is_recycling: bool
     disable_auto_link: bool
@@ -1196,29 +1330,8 @@ class NVR(ProtectDeviceModel):
         return versions
 
     async def get_is_prerelease(self) -> bool:
-        """Get if current version of Protect is a prerelease version."""
-        # only EA versions have `-beta` in versions
-        if self.version.is_prerelease:
-            return True
-
-        # 2.6.14 is an EA version that looks like a release version
-        cache_file_path = self._api.cache_dir / "release_cache.json"
-        versions = await self._read_cache_file(
-            cache_file_path,
-        ) or await self._read_cache_file(RELEASE_CACHE)
-        if versions is None or self.version not in versions:
-            versions = await self._api.get_release_versions()
-            try:
-                _LOGGER.debug("Fetching releases from APT repos...")
-                tmp = self._api.cache_dir / "release_cache.tmp.json"
-                await aos.makedirs(self._api.cache_dir, exist_ok=True)
-                async with aiofiles.open(tmp, "wb") as cache_file:
-                    await cache_file.write(orjson.dumps([str(v) for v in versions]))
-                await aos.rename(tmp, cache_file_path)
-            except Exception:
-                _LOGGER.warning("Failed write cache file.")
-
-        return self.version not in versions
+        """[DEPRECATED] Always returns False. Will be removed after HA 2025.8.0."""
+        return False
 
     async def set_smart_detections(self, value: bool) -> None:
         """Set if smart detections are enabled."""
@@ -1344,6 +1457,11 @@ class NVR(ProtectDeviceModel):
         """
         return self._is_smart_enabled(SmartDetectObjectType.VEHICLE)
 
+    @property
+    def is_global_face_detection_on(self) -> bool:
+        """Is Face Detection available and enabled?"""
+        return self._is_smart_enabled(SmartDetectObjectType.FACE)
+
     @property
     def is_global_license_plate_detection_on(self) -> bool:
         """