@camera.ui/server 2.0.22 → 2.0.23

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/plugin/notifier.py

@@ -1,9 +1,3 @@
-"""Generic notification types — domain-agnostic.
-
-The NotificationManager and notifier plugins talk over RPC and JSON-encode
-these types directly.
-"""
-
 from __future__ import annotations
 
 from enum import StrEnum
@@ -20,17 +14,16 @@ class Severity(StrEnum):
     """
 
     Info = "info"
-    """Standard notification — default delivery (sound + banner)."""
+    """Standard notification, default delivery (sound + banner)."""
 
     Warn = "warn"
-    """Heightened attention; notifiers may use a different sound/colour."""
+    """Heightened attention; notifiers may use a different sound or colour."""
 
     Error = "error"
     """Failure or action-required notification."""
 
     Critical = "critical"
-    """Highest-priority delivery on supporting notifiers; bypasses
-    user-configured Quiet Hours on the host."""
+    """Highest-priority delivery on supporting notifiers; bypasses Quiet Hours."""
 
 
 class NotifierDevice(TypedDict):
@@ -41,64 +34,63 @@ class NotifierDevice(TypedDict):
     """
 
     id: str
+    """Plugin-assigned device id, unique within the notifier."""
+
     ownerUserId: str
+    """User the device belongs to."""
+
     name: str
+    """Display name shown in the UI."""
+
     active: bool
+    """False while the user has muted this device; the manager skips it."""
+
     metadata: NotRequired[dict[str, Any]]
+    """Plugin-specific extras (push tokens, chat ids, platform hints)."""
 
 
 class Notification(TypedDict):
     """Payload published via ``api.notificationManager.publish`` or routed by
     the host. Plugins fill the user-visible fields; the host stamps the
-    message id, timestamp and source identifier on receive — plugins do not
-    set those.
+    message id, timestamp and source identifier on receive.
     """
 
     title: str
     """Headline shown by every notifier."""
 
     subtitle: NotRequired[str]
-    """Optional second bold line between title and body. Honoured natively
-    on iOS (APNs ``alert.subtitle``); other notifiers may fold it into the
-    body or ignore it."""
+    """Optional second bold line, honoured natively on iOS; other notifiers may fold it into the body."""
 
     body: NotRequired[str]
     """Optional secondary text."""
 
     severity: NotRequired[Severity]
-    """Drives DND / Critical-Alerts behaviour and Quiet-Hours bypass.
-    Defaults to :attr:`Severity.Info` if omitted."""
+    """Drives DND / Critical-Alerts behaviour and Quiet-Hours bypass. Defaults to :attr:`Severity.Info`."""
 
     tag: NotRequired[str]
-    """Collapse-key (e.g. ``motion:cam-1``). The host uses it to replace an older
-    entry with the same tag in the in-app notification list. Delivery is not
-    throttled: every publish is sent. Notifiers may map it to a platform
-    collapse-id."""
+    """Collapse-key (e.g. ``motion:cam-1``). The host replaces an older entry
+    with the same tag in the in-app list. Delivery is not throttled: every
+    publish is sent. Notifiers may map it to a platform collapse-id."""
 
     thumbnail: NotRequired[bytes]
     """Optional inline JPEG attached to the notification."""
 
     imageUrl: NotRequired[str]
     """Publicly-fetchable URL to a rich image (e.g. a detection snapshot).
-    Notifier-agnostic: FCM/APNs and other notifiers fetch it to render the
-    image. Preferred over inline ``thumbnail`` bytes when a URL is available;
-    empty renders text-only."""
+    Preferred over inline ``thumbnail`` bytes when a URL is available; empty
+    renders text-only."""
 
     deepLink: NotRequired[str]
-    """Router-relative path consumed by mobile / web tap-handlers (e.g.
-    ``/cameras/cam-1?startTs=...``). No host, no scheme."""
+    """Router-relative path for mobile / web tap-handlers (e.g. ``/cameras/cam-1``). No host, no scheme."""
 
     data: NotRequired[dict[str, str]]
-    """Plugin-specific context (cameraId, eventId, plugin-defined keys).
-    String values keep the wire format predictable across notifier
-    implementations."""
+    """Plugin-specific context (cameraId, eventId, plugin-defined keys), string values only."""
 
     adminOnly: NotRequired[bool]
     """Restricts delivery to users with the master or admin role. Use it for
-    operational alerts that concern whoever runs the instance — camera
-    offline, disk full, plugin failures — so they don't reach guests the
-    instance is merely shared with. Defaults to ``False`` (every user of the
-    instance receives it, subject to their own notification settings)."""
+    operational alerts (camera offline, disk full, plugin failures) so they
+    don't reach guests the instance is merely shared with. Defaults to
+    ``False``."""
 
 
 @runtime_checkable
@@ -106,14 +98,13 @@ class NotifierInterface(Protocol):
     """Implemented by plugins that deliver notifications.
 
     The NotificationManager invokes these methods over RPC. Plugins own their
-    device storage — the manager never persists devices itself.
+    device storage, the manager never persists devices itself.
     """
 
     async def get_devices(self, owner_user_ids: list[str]) -> list[NotifierDevice]:
-        """Return every device this notifier knows about for the given users.
-        Each device carries its ``ownerUserId`` so the caller can map results
-        back. May return [] when the notifier is unavailable (e.g. license
-        invalid). Called frequently — keep cheap."""
+        """Return the devices this notifier knows for the given users, each
+        carrying its ``ownerUserId``. Return [] when the notifier is
+        unavailable (e.g. invalid license). Called often, keep it cheap."""
         ...
 
     async def get_device(self, device_id: str) -> NotifierDevice | None:
@@ -121,30 +112,21 @@ class NotifierInterface(Protocol):
         ...
 
     async def send_notification(self, device_ids: list[str], n: Notification) -> None:
-        """Deliver a notification to the given devices in one call. Errors are
-        logged; the manager never aborts a fan-out because one notifier
-        failed."""
+        """Deliver a notification to the given devices in one call. Errors are logged, a failing notifier never aborts the fan-out."""
         ...
 
     async def register_device(self, owner_user_id: str, input: dict[str, Any]) -> NotifierDevice:
-        """Create a new device on this notifier. ``input`` is plugin-specific
-        JSON whose schema the notifier defines; the NotificationManager
-        forwards it opaquely."""
+        """Create a new device. ``input`` is plugin-specific JSON the manager forwards opaquely."""
         ...
 
     async def revoke_device(self, device_id: str) -> None:
-        """Permanently remove a device. Called when the user revokes the
-        device through their notifier-specific UI."""
+        """Permanently remove a device. Called when the user revokes it through their notifier-specific UI."""
         ...
 
     async def update_device(self, device_id: str, patch: dict[str, Any]) -> NotifierDevice | None:
-        """Mutate a subset of fields on an existing device. ``patch`` is
-        plugin-agnostic (``name``, ``active``); plugins ignore unknown keys.
-        Returns the updated device, or None if the id isn't ours so the
-        manager can probe the next plugin."""
+        """Mutate ``name`` / ``active`` on an existing device. Return None if the id isn't ours so the manager can probe the next plugin."""
         ...
 
     async def notificationSettings(self) -> list[JsonSchema] | None:
-        """Return the JSON schema used to render the notifier's settings form
-        in the UI. Return None for no schema."""
+        """Return the JSON schema used to render the notifier's settings form in the UI, or None for no schema."""
         ...

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/plugin/oauth.py

@@ -22,7 +22,7 @@ class OAuthState(TypedDict):
     verificationUri: NotRequired[str]
     """Device-flow verification URI the user opens (set while ``awaiting_user``)."""
     verificationUriComplete: NotRequired[str]
-    """Verification URI with the user code embedded — rendered as a QR code."""
+    """Verification URI with the user code embedded, rendered as a QR code."""
     authUrl: NotRequired[str]
     """Authorization-code-flow URL the browser must open (set while ``awaiting_user``)."""
     userEmail: NotRequired[str]
@@ -84,9 +84,9 @@ class OAuthProviderDeclaration(TypedDict):
 
 @runtime_checkable
 class OAuthCapable(Protocol):
-    """Base interface every OAuth-capable plugin implements, alongside at least
-    one flow sub-interface. IdP-agnostic — the plugin brings its own endpoint
-    config and knows nothing about the host's internals.
+    """Base interface every OAuth-capable plugin implements, alongside at
+    least one flow sub-interface. IdP-agnostic: the plugin brings its own
+    endpoint config and knows nothing about the host's internals.
     """
 
     async def getOAuthMetadata(self) -> OAuthMetadata:

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/__init__.py

@@ -16,10 +16,6 @@ from .base import (
     SensorPropertyChangeData,
     SensorType,
 )
-
-if TYPE_CHECKING:
-    from ..internal.sensor_rpc import SensorCapability, SensorPropertyType  # noqa: F401
-
 from .battery import (
     BatteryCapability,
     BatteryInfo,
@@ -129,6 +125,9 @@ from .temperature import (
     TemperatureInfo,
 )
 
+if TYPE_CHECKING:
+    from ..internal.sensor_rpc import SensorCapability, SensorPropertyType  # noqa: F401
+
 __all__ = [
     "Sensor",
     "SensorLike",

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/audio.py

@@ -44,23 +44,25 @@ BaseAudioLabel = Literal[
     "smoke_alarm",
 ]
 
-#: Audio label — one of the built-in labels or any custom string emitted by an audio detector.
+#: Audio label: one of the built-in labels, or any custom string emitted by an audio detector.
 AudioLabel = BaseAudioLabel | str
 
 
 class AudioProperty(StrEnum):
-    """Property names of an audio detection sensor."""
+    """Property names of an audio sensor."""
 
-    Detected = "detected"  # Whether an audio event is currently detected
-    Detections = "detections"  # List of detected audio events (e.g. glass break, scream)
-    Decibels = "decibels"  # Current audio level in decibels
-    LastTriggered = (
-        "lastTriggered"  # Timestamp in milliseconds of the last detection trigger, set by the backend
-    )
+    Detected = "detected"
+    """Whether an audio event is currently detected."""
+    Detections = "detections"
+    """List of detected audio events (e.g. glass break, scream)."""
+    Decibels = "decibels"
+    """Current audio level in decibels."""
+    LastTriggered = "lastTriggered"
+    """Timestamp in milliseconds of the last detection trigger, set by the backend."""
 
 
 class AudioSensorProperties(TypedDict):
-    """Property shape carried by an AudioSensor."""
+    """Property values of an audio sensor."""
 
     detected: bool
     detections: list[Detection]
@@ -70,8 +72,10 @@ class AudioSensorProperties(TypedDict):
 class AudioPropertyChangeData(TypedDict):
     """Property change payload emitted on AudioSensorLike.onPropertyChanged."""
 
-    property: str  # AudioProperty value
+    property: str
+    """Name of the changed property, an AudioProperty value."""
     value: bool | list[Detection] | float
+    """New value of the property."""
 
 
 TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
@@ -85,6 +89,9 @@ class AudioSensorLike(SensorLike, Protocol):
     def type(self) -> SensorType:
         return SensorType.Audio
 
+    @property
+    def onPropertyChanged(self) -> Observable[AudioPropertyChangeData]: ...
+
     @overload
     def getValue(self, property: Literal[AudioProperty.Detected]) -> bool | None: ...
     @overload
@@ -94,21 +101,18 @@ class AudioSensorLike(SensorLike, Protocol):
     @overload
     def getValue(self, property: str) -> object | None: ...
 
-    @property
-    def onPropertyChanged(self) -> Observable[AudioPropertyChangeData]: ...
-
 
 class AudioSensor(Sensor[AudioSensorProperties, TStorage, str], Generic[TStorage]):
     """Audio sensor that reports audio events and decibel levels.
 
-    Plugin authors call `reportDetections(list)` to push detected audio events
-    (auto-derives `detected`) and `setDecibels(value)` to update the audio level.
+    Plugin authors call ``reportDetections(list)`` to push detected audio events
+    (auto-derives ``detected``) and ``setDecibels(value)`` to update the audio level.
     """
 
     _requires_frames = False
 
-    def __init__(self, name: str = "Audio Sensor") -> None:
-        super().__init__(name)
+    def __init__(self, name: str = "Audio Sensor", *, native_id: str | None = None) -> None:
+        super().__init__(name, native_id=native_id)
         self._write_state(
             {
                 AudioProperty.Detected.value: False,
@@ -127,26 +131,23 @@ class AudioSensor(Sensor[AudioSensorProperties, TStorage, str], Generic[TStorage
 
     @property
     def detected(self) -> bool:
-        """Whether an audio event is currently detected."""
         return bool(self.props.detected)
 
     @property
     def detections(self) -> list[Detection]:
-        """Current detection list."""
         return self.props.detections or []
 
     @property
     def decibels(self) -> float:
-        """Current audio level in decibels."""
         return float(self.props.decibels or 0.0)
 
     def reportDetections(self, detected: bool, detections: list[Detection] | None = None) -> None:
         """Report detected audio events.
 
-        - ``reportDetections(True)`` — audio detected without specifics. The SDK
+        - ``reportDetections(True)``: audio detected without specifics. The SDK
           synthesizes a single full-frame ``'audio'`` detection.
-        - ``reportDetections(True, [...])`` — audio detected with explicit detections.
-        - ``reportDetections(False)`` — clear.
+        - ``reportDetections(True, [...])``: audio detected with explicit detections.
+        - ``reportDetections(False)``: clear.
 
         Args:
             detected: Whether an audio event is currently detected.
@@ -194,29 +195,36 @@ class AudioSensor(Sensor[AudioSensorProperties, TStorage, str], Generic[TStorage
 
     async def updateValue(self, property: str, value: Any) -> None:
         """Read-only sensor: external writes are ignored."""
-        # No-op — audio state is reported by the plugin, not set externally.
 
 
 class AudioFrameData(TypedDict):
     """Audio frame data delivered to audio detector sensors by the backend pipeline."""
 
-    cameraId: NotRequired[str]  # Camera the frame originated from
-    data: bytes  # Raw audio sample buffer
-    sampleRate: int  # Sample rate of the buffer in Hz
-    channels: int  # Channel count of the buffer (typically 1 = mono)
-    format: Literal[
-        "pcm16", "float32"
-    ]  # Sample format: pcm16=16-bit signed integer PCM, float32=32-bit float
-    decibels: NotRequired[float]  # Pre-computed decibel level for this frame, if available
-    timestamp: NotRequired[int]  # Capture timestamp in milliseconds since epoch
+    cameraId: NotRequired[str]
+    """Camera the frame originated from."""
+    data: bytes
+    """Raw audio sample buffer."""
+    sampleRate: int
+    """Sample rate of the buffer in Hz."""
+    channels: int
+    """Channel count of the buffer (typically 1 = mono)."""
+    format: Literal["pcm16", "float32"]
+    """Sample format: pcm16 = 16-bit signed integer PCM, float32 = 32-bit float."""
+    decibels: NotRequired[float]
+    """Pre-computed decibel level for this frame, if available."""
+    timestamp: NotRequired[int]
+    """Capture timestamp in milliseconds since epoch."""
 
 
 class AudioResult(TypedDict):
     """Return type for AudioDetectorSensor.detectAudio()."""
 
-    detected: bool  # Whether an audio event is detected in this frame
-    detections: list[Detection]  # Detections emitted for this frame
-    decibels: NotRequired[float]  # Optional decibel level computed for this frame
+    detected: bool
+    """Whether an audio event is detected in this frame."""
+    detections: list[Detection]
+    """Detections emitted for this frame."""
+    decibels: NotRequired[float]
+    """Optional decibel level computed for this frame."""
 
 
 class AudioDetectorSensor(AudioSensor[TStorage], Generic[TStorage]):
@@ -231,9 +239,7 @@ class AudioDetectorSensor(AudioSensor[TStorage], Generic[TStorage]):
 
     @property
     @abstractmethod
-    def modelSpec(self) -> AudioModelSpec:
-        """Declares the expected audio input format. The backend resamples to match."""
-        ...
+    def modelSpec(self) -> AudioModelSpec: ...
 
     @abstractmethod
     async def detectAudio(self, audio: AudioFrameData) -> AudioResult: