@camera.ui/server 2.0.22 → 2.0.24

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

@@ -1,12 +1,21 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Literal, NotRequired, Protocol, TypedDict, runtime_checkable
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    NotRequired,
+    Protocol,
+    TypedDict,
+    runtime_checkable,
+)
 
 if TYPE_CHECKING:
     from ..camera import CameraDevice
     from ..observable import Observable
     from ..plugin import BasePlugin, PluginInfo, PluginInterface
     from ..plugin.notifier import Notification
+    from ..sensor.base import Sensor
 
 
 class CoreManagerEvent(TypedDict):
@@ -50,6 +59,18 @@ class CoreManager(Protocol):
         ```
     """
 
+    @property
+    def onEvent(self) -> Observable[CoreManagerEvent]:
+        """
+        Observable for core manager events (e.g. cloud account changes).
+
+        Example:
+            ```python
+            api.coreManager.onEvent.subscribe(lambda e: print(e["type"], e["data"]))
+            ```
+        """
+        ...
+
     async def connectToPlugin(self, pluginName: str) -> BasePlugin | None:
         """
         Connect to another plugin by name.
@@ -107,15 +128,57 @@ class CoreManager(Protocol):
         """
         ...
 
-    @property
-    def onEvent(self) -> Observable[CoreManagerEvent]:
+
+@runtime_checkable
+class SensorManager(Protocol):
+    """
+    Sensor manager for standalone sensors: devices that are not part of a
+    camera's hardware (smart plugs, imported smart-home devices, hubs).
+
+    The host persists each sensor as its own entity: the user assigns it to
+    cameras, renames it and decides whether it is exported or not.
+    Sensors that belong to a camera's hardware are registered via
+    ``camera.addSensor()`` instead.
+
+    Accessed via `api.sensorManager` in plugins.
+
+    Example:
+        ```python
+        lock = LockControl("Front Door", native_id="lock.front_door")
+        await api.sensorManager.addSensor(lock)
+        ```
+    """
+
+    async def addSensor(self, sensor: Sensor[Any, Any, Any]) -> None:
         """
-        Observable for core manager events (e.g. cloud account changes).
+        Register a standalone sensor with the host.
 
-        Example:
-            ```python
-            api.coreManager.onEvent.subscribe(lambda e: print(e["type"], e["data"]))
-            ```
+        The host reconciles it against the persisted entity by
+        ``(pluginId, nativeId)``, or by ``(type, name)`` when no native_id is
+        set, and replaces the sensor's provisional ``id`` with the persistent
+        entity id. Camera assignment is the user's decision and happens in the UI.
+
+        Args:
+            sensor: Sensor instance to register
+        """
+        ...
+
+    async def removeSensor(self, sensor: Sensor[Any, Any, Any]) -> None:
+        """
+        Unregister a sensor. The persisted entity stays (shows disconnected)
+        unless the user deletes it in the UI.
+
+        Args:
+            sensor: Sensor instance to unregister
+        """
+        ...
+
+    def getSensors(self) -> list[Sensor[Any, Any, Any]]:
+        """
+        Get all sensors this plugin has registered in this session.
+
+        Returns:
+            Sensor instances owned by this plugin
         """
         ...
 
@@ -124,7 +187,7 @@ class CoreManager(Protocol):
 class DeviceManager(Protocol):
     """
     Device manager interface for camera operations.
-    Provides methods to get cameras and push discovered cameras.
+    Provides methods to push discovered cameras and get camera devices.
 
     Accessed via `api.deviceManager` in plugins.
 
@@ -143,7 +206,8 @@ class DeviceManager(Protocol):
         """
         Push discovered cameras to the backend.
         Use this when cameras are discovered asynchronously (e.g., after cloud login).
-        Cameras will be immediately visible in the UI for adoption.
+        Cameras become visible in the UI without waiting for the next poll.
+        Only available for CameraController and CameraAndSensorProvider plugins.
 
         Args:
             cameras: List of discovered cameras to push
@@ -196,21 +260,21 @@ class CreateDownloadOptions(TypedDict):
     """Absolute path to the file on disk."""
 
     filename: NotRequired[str]
-    """Filename for Content-Disposition header."""
+    """Filename for Content-Disposition header (defaults to basename of filePath)."""
 
     mimeType: NotRequired[str]
-    """MIME type for Content-Type header."""
+    """MIME type for Content-Type header (defaults to application/octet-stream)."""
 
     ttlMs: NotRequired[int]
-    """Time-to-live in milliseconds."""
+    """Time-to-live in milliseconds (defaults to 10 minutes)."""
 
     cleanup: NotRequired[Literal["never", "on-expiry", "on-download"]]
     """When the file on disk is deleted (registry always expires at TTL).
 
     - ``never`` (default): file persists; caller manages it.
     - ``on-expiry``: deleted at TTL. Can be fetched N times during the
-      window — correct mode for notification images that fan out to
-      multiple devices/recipients.
+      window, the right mode for notification images that fan out to
+      multiple devices or recipients.
     - ``on-download``: deleted after first successful download OR on TTL,
       whichever first. One-shot mode for things like backup exports."""
 
@@ -235,10 +299,10 @@ class DownloadToken(TypedDict):
     publicUrl: str
     """Externally-reachable, session-less URL the server publishes for
     out-of-band fetchers (push-notification image attachments, FCM / APNs
-    payloads, share recipients). Shape: ``<externalUrl>/api/download/<token>``
-    — the token in the URL is the auth. Empty string when the server has
-    no external URL configured (LAN-only deployments); fall back to
-    ``url`` for in-app callers."""
+    payloads, share recipients). Shape: ``<externalUrl>/api/download/<token>``,
+    where the token is the auth. Empty string when the server has no external
+    URL configured (LAN-only deployments); fall back to ``url`` for in-app
+    callers."""
 
     expiresAt: int
     """Unix timestamp (ms) when the token expires."""
@@ -249,8 +313,8 @@ class DownloadManager(Protocol):
     """
     Download manager interface for token-based file downloads.
 
-    Allows plugins to register files for HTTP download via a token URL.
-    No JWT authentication is needed — the token itself is the auth.
+    Plugins register a file and get back a token URL. No JWT is involved, the
+    token itself is the auth.
 
     Accessed via ``api.downloadManager`` in plugins.
 
@@ -310,11 +374,10 @@ class NotificationManager(Protocol):
     """
     Notification manager interface for publishing notifications into the host.
 
-    Plugins call ``publish`` to ask the host to fan a Notification out to
-    every installed Notifier-plugin and the
-    in-app UI. The host applies user settings (master toggle, per-source
-    toggle, quiet hours) and the publishing plugin's declared capabilities;
-    calls from plugins without
+    Plugins call ``publish`` to ask the host to fan a Notification out to every
+    installed Notifier-plugin and the in-app UI. The host applies user settings
+    (master toggle, per-source toggle, quiet hours) and the publishing plugin's
+    declared capabilities; calls from plugins without
     :attr:`PluginCapability.PublishNotifications` are silently dropped.
 
     Accessed via ``api.notificationManager`` in plugins.
@@ -339,8 +402,7 @@ class NotificationManager(Protocol):
         Notifier-plugin and the in-app UI.
 
         Resolves once the publish was handed to the transport. Downstream
-        delivery is async and failures there never
-        propagate back here.
+        delivery is async and failures there never propagate back here.
 
         Args:
             notification: Notification payload to publish.
@@ -355,7 +417,7 @@ __all__ = [
     "DeviceManager",
     "DownloadManager",
     "NotificationManager",
-    # Signed request
+    "SensorManager",
     # Download types
     "CreateDownloadOptions",
     "CreateStreamDownloadOptions",

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

@@ -1,10 +1,3 @@
-"""Lightweight reactive primitives for camera.ui.
-
-Provides cold Observables, multicast Subjects (Subject, BehaviorSubject,
-ReplaySubject) and a small set of composable operators for building
-property-change notifications and event streams throughout the SDK.
-"""
-
 from __future__ import annotations
 
 import asyncio
@@ -36,15 +29,25 @@ class Disposable:
 
     @property
     def closed(self) -> bool:
+        """Whether the subscription has already been disposed."""
         return self._closed
 
     def dispose(self) -> None:
+        """Detach the listener and run the producer teardown. Disposing twice is a no-op.
+
+        Example:
+            ```python
+            sub = sensor.onPropertyChanged.subscribe(handle)
+            sub.dispose()
+            ```
+        """
         if self._closed:
             return
         self._closed = True
         self._teardown()
 
     def unsubscribe(self) -> None:
+        """Alias for :meth:`dispose`, for rxjs-shaped call sites."""
         self.dispose()
 
 
@@ -61,10 +64,38 @@ class Observable(Generic[T]):
         self._subscribe_fn = subscribe_fn
 
     def subscribe(self, callback: Callable[[T], None]) -> Disposable:
-        """Start the producer for this subscriber and route emitted values to ``callback``. Returns a :class:`Disposable` for stopping the stream."""
+        """Start the producer for this subscriber and route emitted values to ``callback``.
+
+        Args:
+            callback: Receiver invoked once per emitted value.
+
+        Returns:
+            Disposable that stops the stream and runs the producer teardown.
+
+        Example:
+            ```python
+            sub = sensor.onPropertyChanged.subscribe(handle)
+            ```
+        """
         return self._subscribe_fn(callback)
 
     def pipe(self, *operators: OperatorFn) -> Observable[Any]:
+        """Chain operators into a new Observable, each one fed by the previous.
+
+        Args:
+            operators: Operators applied left to right.
+
+        Returns:
+            Observable emitting the transformed values.
+
+        Example:
+            ```python
+            sensor.onPropertyChanged.pipe(
+                filter_op(lambda e: e["property"] == "detected"),
+                map_op(lambda e: e["value"]),
+            ).subscribe(handle)
+            ```
+        """
         result: Observable[Any] = self
         for op in operators:
             result = op(result)
@@ -75,7 +106,23 @@ class Observable(Generic[T]):
         on_next: Callable[[T], Awaitable[Any]] | None = None,
         on_error: Callable[[Exception], Awaitable[Any]] | None = None,
     ) -> Disposable:
-        """Subscribe asynchronously to the observable sequence."""
+        """Subscribe with coroutine handlers. Each value spawns a task running ``on_next``.
+
+        A failing ``on_next`` disposes the subscription and hands the exception to
+        ``on_error``.
+
+        Args:
+            on_next: Coroutine invoked per emitted value.
+            on_error: Coroutine invoked once with the first exception raised.
+
+        Returns:
+            Disposable that cancels the pending tasks and the subscription.
+
+        Example:
+            ```python
+            sub = camera.onDetection.asubscribe(handle_detection)
+            ```
+        """
         error_future: asyncio.Future[Exception] = asyncio.Future()
         next_task: asyncio.Task[Any] | None = None
         error_task: asyncio.Task[Any] | None = None
@@ -113,7 +160,7 @@ class Observable(Generic[T]):
         return Disposable(cancel_subscription)
 
     async def __aiter__(self) -> AsyncIterator[T]:
-        """Async iterator implementation."""
+        """Iterate emitted values. Values are buffered in a queue of 100; overflow is dropped."""
         queue: asyncio.Queue[T | None] = asyncio.Queue(maxsize=100)
         done = False
 
@@ -152,15 +199,27 @@ class Subject(Generic[T]):
 
     @property
     def closed(self) -> bool:
+        """Whether :meth:`complete` has already run."""
         return self._completed
 
     def next(self, value: T) -> None:
+        """Dispatch a value to every current subscriber, synchronously. No-op once completed.
+
+        Args:
+            value: Value to multicast.
+
+        Example:
+            ```python
+            subject.next("armed")
+            ```
+        """
         if self._completed:
             return
         for cb in list(self._subscribers):
             cb(value)
 
     def complete(self) -> None:
+        """Release every subscriber and lock the Subject. Later :meth:`next` calls are ignored."""
         if self._completed:
             return
         self._completed = True
@@ -170,29 +229,53 @@ class Subject(Generic[T]):
         for handler in handlers:
             handler()
 
-    def _on_complete(self, handler: Callable[[], None]) -> Disposable:
-        """Register a handler invoked once when this Subject completes. Runs
-        immediately if already completed. Used by :func:`first_value_from`.
-        """
-        if self._completed:
-            handler()
-            return Disposable(lambda: None)
-        self._complete_handlers.add(handler)
-        return Disposable(lambda: self._complete_handlers.discard(handler))
-
     def subscribe(self, callback: Callable[[T], None]) -> Disposable:
+        """Register ``callback`` for every following value.
+
+        Args:
+            callback: Receiver invoked once per emitted value.
+
+        Returns:
+            Disposable that unregisters the callback.
+        """
         if self._completed:
             return Disposable(lambda: None)
         self._subscribers.add(callback)
         return Disposable(lambda: self._subscribers.discard(callback))
 
     def pipe(self, *operators: OperatorFn) -> Observable[Any]:
+        """Chain operators onto this Subject's read-only view.
+
+        Args:
+            operators: Operators applied left to right.
+
+        Returns:
+            Observable emitting the transformed values.
+        """
         return self.as_observable().pipe(*operators)
 
     def as_observable(self) -> Observable[T]:
-        """Return a read-only :class:`Observable` that mirrors this Subject without exposing :meth:`next` or :meth:`complete`."""
+        """Return a read-only :class:`Observable` that mirrors this Subject without exposing :meth:`next` or :meth:`complete`.
+
+        Returns:
+            Read-only view of this Subject.
+
+        Example:
+            ```python
+            def on_event(self) -> Observable[Event]:
+                return self._events.as_observable()
+            ```
+        """
         return Observable(lambda cb: self.subscribe(cb))
 
+    def _on_complete(self, handler: Callable[[], None]) -> Disposable:
+        """Register a handler run once on completion, immediately if already completed."""
+        if self._completed:
+            handler()
+            return Disposable(lambda: None)
+        self._complete_handlers.add(handler)
+        return Disposable(lambda: self._complete_handlers.discard(handler))
+
 
 class BehaviorSubject(Subject[T]):
     """Subject seeded with an initial value that always remembers the latest emission.
@@ -207,18 +290,37 @@ class BehaviorSubject(Subject[T]):
         super().__init__()
         self._value = initial_value
 
+    @property
+    def value(self) -> T:
+        """The most recently emitted value."""
+        return self._value
+
     def next(self, value: T) -> None:
+        """Store ``value`` as the current one and dispatch it to every subscriber.
+
+        Args:
+            value: New current value.
+        """
         self._value = value
         super().next(value)
 
     def get_value(self) -> T:
-        return self._value
+        """Read the current value without subscribing.
 
-    @property
-    def value(self) -> T:
+        Returns:
+            The most recently emitted value.
+        """
         return self._value
 
     def subscribe(self, callback: Callable[[T], None]) -> Disposable:
+        """Register ``callback`` and invoke it immediately with the current value.
+
+        Args:
+            callback: Receiver invoked once per emitted value.
+
+        Returns:
+            Disposable that unregisters the callback.
+        """
         disposable = super().subscribe(callback)
         if not self.closed:
             callback(self._value)
@@ -226,11 +328,10 @@ class BehaviorSubject(Subject[T]):
 
 
 class ReplaySubject(Subject[T]):
-    """Subject that buffers up to the last ``buffer_size`` values
-    (configurable, defaults to ``1``).
+    """Subject that buffers the last ``buffer_size`` values, 1 by default.
 
-    New subscribers immediately receive every buffered value in order
-    before continuing with live emissions.
+    New subscribers immediately receive every buffered value in order before
+    continuing with live emissions.
     """
 
     def __init__(self, buffer_size: int = 1) -> None:
@@ -239,6 +340,11 @@ class ReplaySubject(Subject[T]):
         self._buffer_size = buffer_size
 
     def next(self, value: T) -> None:
+        """Append ``value`` to the buffer, dropping the oldest entry past ``buffer_size``, then dispatch it.
+
+        Args:
+            value: Value to buffer and multicast.
+        """
         if self.closed:
             return
         self._buffer.append(value)
@@ -247,14 +353,19 @@ class ReplaySubject(Subject[T]):
         super().next(value)
 
     def subscribe(self, callback: Callable[[T], None]) -> Disposable:
+        """Replay the buffered values in order, then register ``callback`` for live emissions.
+
+        Args:
+            callback: Receiver invoked once per emitted value.
+
+        Returns:
+            Disposable that unregisters the callback.
+        """
         for value in self._buffer:
             callback(value)
         return super().subscribe(callback)
 
 
-# ── Operators ──────────────────────────────────────────────────────
-
-
 def _default_comparator(a: Any, b: Any) -> bool:
     return cast(bool, a == b)
 
@@ -479,17 +590,14 @@ def merge_map(project: Callable[[Any, int], list[Any]]) -> OperatorFn:
     return operator
 
 
-# ── Utilities ──────────────────────────────────────────────────────
-
-
 async def first_value_from(observable: Observable[T] | Subject[T]) -> T:
     """Subscribe to the source and return its first emitted value as a
     coroutine, then dispose the subscription.
 
     Raises ``RuntimeError`` if the source completes before emitting (Subject,
     BehaviorSubject, ReplaySubject). A bare :class:`Observable` has no
-    completion signal, so the coroutine stays pending until it emits — guard
-    such calls with :func:`asyncio.wait_for` (or a timeout).
+    completion signal, so the coroutine stays pending until it emits; guard
+    such calls with :func:`asyncio.wait_for` or another timeout.
 
     Args:
         observable: Source observable or subject to read once.
@@ -530,7 +638,7 @@ async def first_value_from(observable: Observable[T] | Subject[T]) -> T:
 
     sub = observable.subscribe(on_next)
 
-    # Already resolved synchronously (BehaviorSubject / ReplaySubject)
+    # already resolved synchronously (BehaviorSubject / ReplaySubject)
     if future.done():
         cleanup()
         return await future

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

@@ -1,7 +1,15 @@
 from __future__ import annotations
 
 from .api import API_EVENT, APIListener, PluginAPI
-from .contract import PluginCapability, PluginContract, PluginInfo, PluginInterface, PluginRole, PythonVersion
+from .contract import (
+    PROTOCOL_LEVEL,
+    PluginCapability,
+    PluginContract,
+    PluginInfo,
+    PluginInterface,
+    PluginRole,
+    PythonVersion,
+)
 from .helper import (
     can_create_cameras,
     can_provide_sensors_to_any_cameras,
@@ -52,6 +60,7 @@ from .oauth import (
 )
 
 __all__ = [
+    "PROTOCOL_LEVEL",
     "PythonVersion",
     "PluginInfo",
     "APIListener",