@camera.ui/server 0.0.70 → 0.0.71

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

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from ..manager import CoreManager, DeviceManager, DownloadManager, NotificationManager
+
+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."""
+
+
+class API_EVENT(Enum):
+    """Lifecycle events emitted on the PluginAPI EventEmitter.
+
+    Plugins subscribe with ``api.on(API_EVENT.X, handler)`` to react to
+    host-driven phase changes.
+    """
+
+    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)."""
+
+    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."""
+
+
+@runtime_checkable
+class PluginAPI(Protocol):
+    """The PluginAPI is injected into the plugin at runtime and exposes the
+    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()
+        ```
+    """
+
+    @property
+    def coreManager(self) -> CoreManager:
+        """System-level operations such as 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."""
+        ...
+
+    @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)."""
+        ...
+
+    @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."""
+        ...
+
+    @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."""
+        ...
+
+    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.
+        """
+        ...
+
+    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.
+        """
+        ...
+
+    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.
+        """
+        ...
+
+    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.
+        """
+        ...
+
+    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.
+        """
+        ...

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

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Literal, NotRequired, TypedDict
+
+from ..sensor import SensorType
+
+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
+plugin; Node and Go plugins ignore this field."""
+
+
+class PluginRole(str, Enum):
+    """Role a plugin plays in the system. The role decides which lifecycle
+    hooks the host invokes and which contract validations apply."""
+
+    Hub = "hub"
+    """Cloud-service integration that manages its own cameras end-to-end via
+    a vendor account (e.g. a vendor SDK / cloud API). The hub owns camera
+    creation, streaming and sensors; it cannot expose sensors for cameras
+    owned by other plugins."""
+
+    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."""
+
+    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."""
+
+    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."""
+
+
+class PluginInterface(str, Enum):
+    """Capability flags a plugin advertises in its contract.
+
+    The host uses these to decide which RPC handlers to wire up and which
+    UI affordances to show.
+    """
+
+    MotionDetection = "MotionDetection"
+    """Implements MotionDetectionInterface (video-based motion detection)."""
+
+    ObjectDetection = "ObjectDetection"
+    """Implements ObjectDetectionInterface (e.g. person, vehicle, animal)."""
+
+    AudioDetection = "AudioDetection"
+    """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."""
+
+    LicensePlateDetection = "LicensePlateDetection"
+    """Implements LicensePlateDetectionInterface (plate localisation + OCR)."""
+
+    ClassifierDetection = "ClassifierDetection"
+    """Implements ClassifierDetectionInterface (generic image classification
+    emitting attribute/label pairs)."""
+
+    ClipDetection = "ClipDetection"
+    """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."""
+
+    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."""
+
+    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."""
+
+    OAuthCapable = "OAuthCapable"
+    """Implements the OAuthCapable base interface (getOAuthMetadata,
+    getOAuthState, disconnect) plus at least one flow sub-interface —
+    see camera_ui_sdk/plugin/oauth.py."""
+
+    OAuthDeviceFlow = "OAuthDeviceFlow"
+    """Implements OAuthDeviceFlowCapable (RFC 8628 Device Authorization Grant)."""
+
+    OAuthAuthCodeFlow = "OAuthAuthCodeFlow"
+    """Implements OAuthAuthCodeFlowCapable (Authorization Code Flow + PKCE)."""
+
+    OAuthClientCredentials = "OAuthClientCredentials"
+    """Implements OAuthClientCredentialsCapable (user-supplied client_id + client_secret)."""
+
+
+class PluginCapability(str, Enum):
+    """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."""
+
+    PublishNotifications = "publishNotifications"
+    """Grants the plugin permission to call
+    ``api.notificationManager.publish``. Without this capability the host
+    silently 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."""
+
+    name: str
+    """Stable, unique identifier for the plugin instance — used as the
+    registry key, log prefix and the 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."""
+
+    consumes: list[SensorType]
+    """Sensor types the plugin reads from other plugins (e.g. a face plugin
+    consumes 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."""
+
+    pythonVersion: NotRequired[PythonVersion]
+    """Required Python interpreter version for Python plugins. Ignored by
+    Node / 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)."""
+
+
+class PluginInfo(TypedDict):
+    """Lightweight handle identifying an installed plugin — used in RPC
+    payloads and managers to refer to the plugin without shipping its full
+    state."""
+
+    id: str
+    """Unique runtime ID assigned by the host (stable across restarts)."""
+
+    name: str
+    """Plugin package name (matches PluginContract.name)."""
+
+    contract: PluginContract
+    """Full contract the plugin was loaded with."""

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

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+from ..sensor import (
+    SensorType,
+)
+from .contract import PluginCapability, PluginContract, PluginInterface, PluginRole
+
+
+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.
+
+    Args:
+        contract: Untrusted candidate contract (e.g. parsed manifest JSON).
+
+    Returns:
+        Error messages, empty if the contract is valid.
+
+    Example:
+        ```python
+        errors = get_contract_validation_errors(my_contract)
+        if errors:
+            print(f"Invalid contract: {errors}")
+        ```
+    """
+    errors: list[str] = []
+
+    if not contract or not isinstance(contract, dict):
+        errors.append(
+            f"Contract must be an object. Got: {'null' if contract is None else type(contract).__name__}"
+        )
+        return errors
+
+    c = cast(Any, contract)
+    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):
+        role_value = c.get("role")
+        errors.append(f'Field "role" must be a string. Got: {type(role_value).__name__}')
+    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):
+        errors.append(f'Field "name" must be a string. Got: {type(c["name"]).__name__}')
+    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):
+        errors.append(f'Field "provides" must be an array. Got: {type(c["provides"]).__name__}')
+    else:
+        for sensor_type in c["provides"]:
+            if sensor_type not in valid_sensor_types:
+                errors.append(
+                    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):
+        errors.append(f'Field "consumes" must be an array. Got: {type(c["consumes"]).__name__}')
+    else:
+        for sensor_type in c["consumes"]:
+            if sensor_type not in valid_sensor_types:
+                errors.append(
+                    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"')
+    elif not isinstance(c["interfaces"], list):
+        errors.append(f'Field "interfaces" must be an array. Got: {type(c["interfaces"]).__name__}')
+    else:
+        for iface in c["interfaces"]:
+            if iface not in valid_interfaces:
+                errors.append(
+                    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):
+            errors.append(f'Field "capabilities" must be an array. Got: {type(c["capabilities"]).__name__}')
+        else:
+            for cap in c["capabilities"]:
+                if cap not in valid_capabilities:
+                    errors.append(
+                        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__}')
+
+    return errors
+
+
+def validate_contract_consistency(contract: PluginContract, plugin_name: str | None = None) -> None:
+    """Enforce role-specific consistency rules on top of the structural check
+    (e.g. SensorProvider plugins must declare at least one provided sensor;
+    Hub plugins cannot expose sensors). Raises on the first violation.
+
+    Args:
+        contract: Already-structurally-valid contract.
+        plugin_name: Optional plugin name; used to prefix error messages.
+
+    Raises:
+        ValueError: When the contract violates a role-specific rule.
+
+    Example:
+        ```python
+        validate_contract_consistency(contract, "my-plugin")
+        ```
+    """
+    prefix = f'Plugin "{plugin_name}": ' if plugin_name else ""
+    role = contract["role"]
+    provides = contract["provides"]
+
+    if role == PluginRole.Hub and len(provides) > 0:
+        raise ValueError(f"{prefix}Hub plugins cannot provide sensors.")
+    if role == PluginRole.SensorProvider and len(provides) == 0:
+        raise ValueError(f"{prefix}SensorProvider plugins must provide at least one sensor type.")
+    if role == PluginRole.CameraAndSensorProvider and len(provides) == 0:
+        raise ValueError(f"{prefix}CameraAndSensorProvider plugins must provide at least one sensor type.")
+
+
+def is_hub(contract: PluginContract) -> bool:
+    """Report whether the plugin's role is Hub (vendor cloud integration that
+    manages its own cameras end-to-end).
+
+    Args:
+        contract: Plugin contract to inspect.
+
+    Returns:
+        True if the role is :attr:`PluginRole.Hub`.
+
+    Example:
+        ```python
+        if is_hub(contract):
+            skip_local_discovery()
+        ```
+    """
+    return contract["role"] == PluginRole.Hub
+
+
+def can_create_cameras(contract: PluginContract) -> bool:
+    """Report whether the plugin can create cameras (role is CameraController
+    or CameraAndSensorProvider). Used to gate camera-creating operations such
+    as DiscoveryProvider adoption.
+
+    Args:
+        contract: Plugin contract to inspect.
+
+    Returns:
+        True if the plugin may create cameras.
+
+    Example:
+        ```python
+        if can_create_cameras(contract):
+            enable_adoption()
+        ```
+    """
+    return contract["role"] in (PluginRole.CameraController, PluginRole.CameraAndSensorProvider)
+
+
+def can_provide_sensors_to_any_cameras(contract: PluginContract) -> bool:
+    """Report whether the plugin is allowed to add sensors to cameras owned
+    by other plugins (true for SensorProvider and CameraAndSensorProvider).
+    Hub and pure CameraController plugins only see their own cameras.
+
+    Args:
+        contract: Plugin contract to inspect.
+
+    Returns:
+        True if the plugin may attach sensors to any camera.
+
+    Example:
+        ```python
+        if can_provide_sensors_to_any_cameras(contract):
+            list_all_cameras()
+        ```
+    """
+    return contract["role"] in (PluginRole.SensorProvider, PluginRole.CameraAndSensorProvider)
+
+
+def has_interface(contract: PluginContract, iface: PluginInterface) -> bool:
+    """Report whether the plugin implements the given capability.
+
+    Args:
+        contract: Plugin contract to inspect.
+        iface: Interface to check (e.g. :attr:`PluginInterface.DiscoveryProvider`).
+
+    Returns:
+        True if ``iface`` is listed in the contract's ``interfaces``.
+
+    Example:
+        ```python
+        if has_interface(contract, PluginInterface.DiscoveryProvider):
+            start_scan()
+        ```
+    """
+    return iface in contract["interfaces"]
+
+
+def has_capability(contract: PluginContract, cap: PluginCapability) -> bool:
+    """Report whether the plugin requested the given capability.
+
+    Args:
+        contract: Plugin contract to inspect.
+        cap: Capability to check (e.g. :attr:`PluginCapability.PublishNotifications`).
+
+    Returns:
+        True if ``cap`` is listed in the contract's ``capabilities``.
+
+    Example:
+        ```python
+        if has_capability(contract, PluginCapability.PublishNotifications):
+            allow_publish()
+        ```
+    """
+    return cap in contract.get("capabilities", [])