@camera.ui/server 2.0.22 → 2.0.23

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

@@ -5,11 +5,10 @@ from enum import Enum
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
-    from ..manager import CoreManager, DeviceManager, DownloadManager, NotificationManager
+    from ..manager import CoreManager, DeviceManager, DownloadManager, NotificationManager, SensorManager
 
 APIListener = Callable[[], None] | Callable[[], Awaitable[None]]
-"""Listener for plugin lifecycle events. May be a plain callable or a
-coroutine function — the runtime awaits the latter."""
+"""Listener for plugin lifecycle events. Coroutine functions are awaited."""
 
 
 class API_EVENT(Enum):
@@ -20,16 +19,10 @@ class API_EVENT(Enum):
     """
 
     FINISH_LAUNCHING = "finishLaunching"
-    """Emitted exactly once after the plugin has been constructed, all
-    assigned cameras have been wired up, and ``configureCameras()`` has
-    returned. Use this to start background work that must wait until the
-    camera set is stable (timers, model warm-up, outbound connections)."""
+    """Emitted once after every assigned camera is wired up and ``configureCameras()`` returned. Start timers and warm-ups here."""
 
     SHUTDOWN = "shutdown"
-    """Emitted when the host is tearing the plugin down (graceful stop,
-    reload or process exit). Listeners must release resources synchronously
-    enough to finish before the host kills the process — open files,
-    sockets, timers, child processes."""
+    """Emitted when the host tears the plugin down. Release files, sockets, timers and child processes now."""
 
 
 @runtime_checkable
@@ -38,100 +31,60 @@ class PluginAPI(Protocol):
     system services the plugin is allowed to talk to. It also acts as an
     EventEmitter for plugin lifecycle events (see :class:`API_EVENT`).
 
-    The API is passed to the plugin constructor and should be stored for
-    later use.
-
     Example:
         ```python
         class MyPlugin(BasePlugin):
-            def __init__(self, logger, api, storage):
-                super().__init__(logger, api, storage)
-                # Access FFmpeg path
-                ffmpeg = await api.coreManager.getFFmpegPath()
+            async def configureCameras(self, cameras):
+                ffmpeg = await self.api.coreManager.getFFmpegPath()
         ```
     """
 
     @property
     def coreManager(self) -> CoreManager:
-        """System-level operations such as the FFmpeg path and the server
-        addresses used for media URLs (HTTP/RTSP)."""
+        """System-level operations: the FFmpeg path and the server addresses used for media URLs (HTTP/RTSP)."""
         ...
 
     @property
     def deviceManager(self) -> DeviceManager:
-        """Owns the camera devices assigned to this plugin and publishes
-        camera-state changes."""
+        """Owns the camera devices assigned to this plugin and publishes camera-state changes."""
+        ...
+
+    @property
+    def sensorManager(self) -> SensorManager:
+        """Registers standalone sensors: entities of their own, persisted across restarts, assignable to cameras by the user."""
         ...
 
     @property
     def downloadManager(self) -> DownloadManager:
-        """Mints token-protected download URLs for files the plugin wants to
-        expose to the UI (e.g. clip exports, snapshots)."""
+        """Mints token-protected download URLs for files the plugin exposes to the UI (clip exports, snapshots)."""
         ...
 
     @property
     def notificationManager(self) -> NotificationManager:
-        """Publishes notifications into the host so they fan out to every
-        installed Notifier-plugin and the in-app UI. Requires
-        :attr:`PluginCapability.PublishNotifications` in the plugin contract."""
+        """Publishes notifications to every installed notifier and the in-app UI. Requires :attr:`PluginCapability.PublishNotifications`."""
         ...
 
     @property
     def storagePath(self) -> str:
-        """Absolute path to the plugin's writable storage directory.
-        Created and cleaned up by the host. Use it for caches, models,
-        sqlite/bolt files."""
+        """Absolute path to the plugin's writable storage directory, created and cleaned up by the host."""
         ...
 
     def on(self, event: API_EVENT, f: APIListener) -> Any:
-        """Subscribe to a lifecycle event.
-
-        Args:
-            event: Lifecycle event to subscribe to.
-            f: Event listener (sync callable or coroutine function).
-
-        Returns:
-            Self for chaining.
-        """
+        """Subscribe to a lifecycle event. Returns self for chaining."""
         ...
 
     def once(self, event: API_EVENT, f: APIListener) -> Any:
-        """Subscribe to a lifecycle event for one delivery only.
-
-        Args:
-            event: Lifecycle event to subscribe to.
-            f: Event listener (sync callable or coroutine function).
-
-        Returns:
-            Self for chaining.
-        """
+        """Subscribe to a lifecycle event for one delivery only. Returns self for chaining."""
         ...
 
     def off(self, event: API_EVENT, f: APIListener) -> None:
-        """Remove a previously registered listener (alias of
-        :meth:`removeListener`).
-
-        Args:
-            event: Lifecycle event the listener was registered for.
-            f: Listener to remove.
-        """
+        """Remove a previously registered listener (alias of :meth:`removeListener`)."""
         ...
 
     def removeListener(self, event: API_EVENT, f: APIListener) -> None:
-        """Remove a previously registered listener.
-
-        Args:
-            event: Lifecycle event the listener was registered for.
-            f: Listener to remove.
-        """
+        """Remove a previously registered listener."""
         ...
 
     def removeAllListeners(self, event: API_EVENT | None = None) -> None:
-        """Remove every listener for ``event``, or every listener entirely if
-        no event is given.
-
-        Args:
-            event: Lifecycle event whose listeners should be removed, or
-                ``None`` to clear all listeners.
-        """
+        """Remove every listener for ``event``, or every listener when no event is given."""
         ...

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

@@ -5,6 +5,14 @@ from typing import Literal, NotRequired, TypedDict
 
 from ..sensor import SensorType
 
+PROTOCOL_LEVEL = 1
+"""Compatibility level of the plugin surface: the plugin-facing API and the
+plugin wire protocol. Bumped only on breaking changes, never for additive
+features. The CLI stamps the level a plugin was built against into its
+bundle (``cameraui.protocolLevel`` in the bundle package.json); the server
+compares that stamp with its own level and refuses to start plugins outside
+its supported range."""
+
 PythonVersion = Literal["3.11", "3.12"]
 """Python interpreter major.minor version a Python plugin requires. The host
 ensures a matching interpreter exists in its venv pool before launching the
@@ -16,29 +24,16 @@ class PluginRole(StrEnum):
     hooks the host invokes and which contract validations apply."""
 
     Hub = "hub"
-    """System-wide aggregator that attaches to cameras owned by *other* plugins
-    to provide a cross-camera service (e.g. bridging cameras and sensors into a
-    smart-home platform, or recording and notifications). A hub creates no
-    cameras of its own and provides no sensors (`provides` must be empty); it
-    attaches to cameras via the `hub` assignment and typically reads camera and
-    sensor state through `consumes`."""
+    """Cross-camera aggregator (smart-home bridge, recorder). Owns no cameras and provides no sensors."""
 
     SensorProvider = "sensorProvider"
-    """Adds sensors to existing cameras without owning the camera itself.
-    Typical use: a detection plugin that consumes another plugin's video
-    frames and emits motion / object / face detections back into the
-    system."""
+    """Adds sensors to cameras owned by other plugins, for example a detector running on foreign video frames."""
 
     CameraController = "cameraController"
-    """Manages cameras and their media streams (ONVIF, RTSP, generic IP, ...).
-    The plugin is responsible for stream URLs, PTZ, snapshots, and the
-    lifecycle hooks in BasePlugin. It does not produce sensors for foreign
-    cameras."""
+    """Manages cameras and their media streams: stream URLs, PTZ, snapshots. Provides no sensors for foreign cameras."""
 
     CameraAndSensorProvider = "cameraAndSensorProvider"
-    """Combined role: plugin both manages cameras and exposes sensors (its
-    own cameras and, when ``consumes`` is set, also foreign cameras). Used
-    by integrations that ship a complete camera + detection stack."""
+    """Manages cameras and exposes sensors, on its own cameras and, with ``consumes`` set, on foreign ones."""
 
 
 class PluginInterface(StrEnum):
@@ -58,39 +53,28 @@ class PluginInterface(StrEnum):
     """Implements AudioDetectionInterface (event/keyword audio detection)."""
 
     FaceDetection = "FaceDetection"
-    """Implements FaceDetectionInterface (face localisation + embeddings).
-    The NVR owns matching against enrolled faces; the plugin only emits
-    detections + embeddings."""
+    """Implements FaceDetectionInterface (face localisation + embeddings). Matching against enrolled faces happens in the NVR."""
 
     LicensePlateDetection = "LicensePlateDetection"
     """Implements LicensePlateDetectionInterface (plate localisation + OCR)."""
 
     ClassifierDetection = "ClassifierDetection"
-    """Implements ClassifierDetectionInterface (generic image classification
-    emitting attribute/label pairs)."""
+    """Implements ClassifierDetectionInterface (generic image classification emitting attribute/label pairs)."""
 
     ClipDetection = "ClipDetection"
-    """Implements ClipDetectionInterface (CLIP image and text embeddings used
-    for semantic search)."""
+    """Implements ClipDetectionInterface (CLIP image and text embeddings used for semantic search)."""
 
     DiscoveryProvider = "DiscoveryProvider"
-    """Implements DiscoveryProvider — plugin can scan the network for new
-    cameras and adopt them. Only valid for camera-controlling roles."""
+    """Implements DiscoveryProvider (network scan + adoption). Only valid for camera-controlling roles."""
 
     NVR = "NVR"
-    """Implements NVRInterface — persists events and recordings, and serves
-    them back to the UI / mobile clients. Exactly one plugin per host fills
-    this role at runtime."""
+    """Implements NVRInterface (events and recordings). Exactly one plugin per host fills this role at runtime."""
 
     Notifier = "Notifier"
-    """Implements NotifierInterface (get_devices, send_notification, ...).
-    Lets the central NotificationManager dispatch notifications to this
-    plugin regardless of role — see camera_ui_sdk/plugin/notifier.py."""
+    """Implements NotifierInterface, so the NotificationManager can dispatch notifications to this plugin."""
 
     OAuthCapable = "OAuthCapable"
-    """Implements the OAuthCapable base interface (getOAuthMetadata,
-    getOAuthState, disconnect) plus at least one flow sub-interface —
-    see camera_ui_sdk/plugin/oauth.py."""
+    """Implements the OAuthCapable base interface plus at least one of the flow sub-interfaces below."""
 
     OAuthDeviceFlow = "OAuthDeviceFlow"
     """Implements OAuthDeviceFlowCapable (RFC 8628 Device Authorization Grant)."""
@@ -104,55 +88,44 @@ class PluginInterface(StrEnum):
 
 class PluginCapability(StrEnum):
     """Permission a plugin requests so it can call a host-provided system
-    feature. Each capability gates one outgoing SDK call — calls without
-    the matching capability are rejected by the host."""
+    feature. Each capability gates one outgoing SDK call. Calls without the
+    matching capability are rejected by the host."""
 
     PublishNotifications = "publishNotifications"
-    """Grants the plugin permission to call
-    ``api.notificationManager.publish``. Without this capability the host
-    silently drops published notifications and logs an error."""
+    """Allows ``api.notificationManager.publish``. Without it the host drops published notifications and logs an error."""
 
 
 class PluginContract(TypedDict):
-    """Manifest contract a plugin declares so the host knows what it does
-    and what it needs at load time. Validated by ``helper.py`` before the
-    plugin is started."""
+    """Manifest contract a plugin declares so the host knows what it does and
+    what it needs at load time. Validated before the plugin is started."""
 
     name: str
-    """Stable, unique identifier for the plugin instance — used as the
-    registry key, log prefix and the storage namespace."""
+    """Stable, unique identifier: registry key, log prefix and storage namespace."""
 
     role: PluginRole
     """Role of the plugin (see :class:`PluginRole`)."""
 
     provides: list[SensorType]
-    """Sensor types the plugin produces. Empty for hubs and pure
-    camera-controllers; required for sensor providers."""
+    """Sensor types the plugin produces. Empty for hubs and pure camera-controllers, required for sensor providers."""
 
     consumes: list[SensorType]
-    """Sensor types the plugin reads from other plugins (e.g. a face plugin
-    consumes camera video frames)."""
+    """Sensor types the plugin reads from other plugins (e.g. a face plugin consuming camera video frames)."""
 
     interfaces: list[PluginInterface]
     """Capability flags the plugin implements (see :class:`PluginInterface`)."""
 
     capabilities: NotRequired[list[PluginCapability]]
-    """Permissions the plugin requests to call host system features (see
-    :class:`PluginCapability`). The host enforces these — calls without a
-    matching capability are rejected."""
+    """Permissions the plugin requests to call host system features (see :class:`PluginCapability`)."""
 
     pythonVersion: NotRequired[PythonVersion]
-    """Required Python interpreter version for Python plugins. Ignored by
-    Node / Go plugins."""
+    """Required Python interpreter version for Python plugins. Ignored by Node and Go plugins."""
 
     dependencies: NotRequired[list[str]]
-    """Extra package dependencies installed into the plugin's runtime (Go
-    module paths for Go plugins; PyPI / npm names for Python and Node
-    plugins)."""
+    """Extra dependencies installed into the plugin's runtime (Go module paths, PyPI or npm names)."""
 
 
 class PluginInfo(TypedDict):
-    """Lightweight handle identifying an installed plugin — used in RPC
+    """Lightweight handle identifying an installed plugin, used in RPC
     payloads and managers to refer to the plugin without shipping its full
     state."""
 

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

@@ -9,10 +9,9 @@ from .contract import PluginCapability, PluginContract, PluginInterface, PluginR
 
 
 def get_contract_validation_errors(contract: object) -> list[str]:
-    """Check the structural validity of an unknown contract object —
-    required fields present, enum values inside the accepted sets — and
-    return one human-readable error per problem found. Returns an empty list
-    when the contract is valid.
+    """Check the structural validity of an unknown contract object: required
+    fields present, enum values inside the accepted sets. Returns one
+    human-readable error per problem found, empty when the contract is valid.
 
     Args:
         contract: Untrusted candidate contract (e.g. parsed manifest JSON).
@@ -39,7 +38,6 @@ def get_contract_validation_errors(contract: object) -> list[str]:
     valid_roles = [r.value for r in PluginRole]
     valid_sensor_types = [s.value for s in SensorType]
 
-    # Check role
     if "role" not in c:
         errors.append('Missing required field: "role"')
     elif not isinstance(c.get("role"), str):
@@ -48,7 +46,6 @@ def get_contract_validation_errors(contract: object) -> list[str]:
     elif c["role"] not in valid_roles:
         errors.append(f'Invalid role "{c["role"]}". Valid roles: {", ".join(valid_roles)}')
 
-    # Check name
     if "name" not in c:
         errors.append('Missing required field: "name"')
     elif not isinstance(c["name"], str):
@@ -56,7 +53,6 @@ def get_contract_validation_errors(contract: object) -> list[str]:
     elif len(c["name"]) == 0:
         errors.append('Field "name" cannot be empty')
 
-    # Check provides
     if "provides" not in c:
         errors.append('Missing required field: "provides"')
     elif not isinstance(c["provides"], list):
@@ -68,7 +64,6 @@ def get_contract_validation_errors(contract: object) -> list[str]:
                     f'Invalid sensor type in "provides": "{sensor_type}". Valid types: {", ".join(valid_sensor_types)}'
                 )
 
-    # Check consumes
     if "consumes" not in c:
         errors.append('Missing required field: "consumes"')
     elif not isinstance(c["consumes"], list):
@@ -80,7 +75,6 @@ def get_contract_validation_errors(contract: object) -> list[str]:
                     f'Invalid sensor type in "consumes": "{sensor_type}". Valid types: {", ".join(valid_sensor_types)}'
                 )
 
-    # Check interfaces
     valid_interfaces = [i.value for i in PluginInterface]
     if "interfaces" not in c:
         errors.append('Missing required field: "interfaces"')
@@ -93,7 +87,6 @@ def get_contract_validation_errors(contract: object) -> list[str]:
                     f'Invalid interface in "interfaces": "{iface}". Valid interfaces: {", ".join(valid_interfaces)}'
                 )
 
-    # Check optional capabilities
     valid_capabilities = [cap.value for cap in PluginCapability]
     if "capabilities" in c:
         if not isinstance(c["capabilities"], list):
@@ -105,11 +98,9 @@ def get_contract_validation_errors(contract: object) -> list[str]:
                         f'Invalid capability in "capabilities": "{cap}". Valid capabilities: {", ".join(valid_capabilities)}'
                     )
 
-    # Check optional pythonVersion
     if "pythonVersion" in c and c["pythonVersion"] not in ["3.11", "3.12"]:
         errors.append(f'Invalid pythonVersion "{c["pythonVersion"]}". Valid versions: 3.11, 3.12')
 
-    # Check optional dependencies
     if "dependencies" in c and not isinstance(c["dependencies"], list):
         errors.append(f'Field "dependencies" must be an array. Got: {type(c["dependencies"]).__name__}')