@camera.ui/sdk 0.0.1

package/dist/sensor/base.js

@@ -0,0 +1,460 @@
+/**
+ * Abstract Sensor Base Class
+ *
+ * Properties are intercepted via Proxy and automatically synchronized via RPC.
+ * Plugin developers can simply write `sensor.detected = true` and the update
+ * is automatically propagated.
+ *
+ * @template TProperties - The properties interface for this sensor
+ * @template TStorage - The storage values interface for this sensor
+ * @template TCapability - The capability enum type for this sensor (default: string)
+ */
+export class Sensor {
+    /** Unique sensor ID */
+    id;
+    /** Camera ID this sensor belongs to (set by addSensor) */
+    _cameraId;
+    /** Plugin ID that provides this sensor (set by addSensor) */
+    _pluginId;
+    /** Whether this sensor is online/available */
+    _online = true;
+    /** Internal properties storage */
+    _propertiesStore;
+    /** Proxied properties for intercepting writes */
+    _propertiesProxy;
+    /** Update function for RPC propagation */
+    _updateFn;
+    /** Property change listeners */
+    _listeners = new Set();
+    /** Simple property change listeners (for SensorLike interface) */
+    _simpleListeners = new Set();
+    /** Capability change listeners (for SensorLike interface) */
+    _capabilityListeners = new Set();
+    /** Storage instance for sensor-type-specific configuration (set by system) */
+    _storage;
+    /** Sensor capabilities */
+    _capabilities = [];
+    /** Capability update function for RPC propagation */
+    _capabilitiesUpdateFn;
+    /** Whether this sensor is assigned to be the active provider for its type */
+    _isAssigned = false;
+    /** Assignment change listeners */
+    _assignmentListeners = new Set();
+    /**
+     * Get schemas for sensor-type-specific configuration
+     *
+     * @returns An array of JsonSchema objects for configuration
+     */
+    schema;
+    /**
+     * Display name for UI, HomeKit, logs etc.
+     * Initially equals name, can be changed by user via UI.
+     * Persisted in sensor storage under '_displayName'.
+     */
+    displayName = '';
+    /**
+     * Whether this sensor requires video frames for detection.
+     * - true: Frame-based detection (e.g., rust-motion, ML object detection)
+     * - false: External detection (e.g., Ring, ONVIF events, SMTP)
+     *
+     * Override in subclass to specify behavior.
+     * DetectorSensor subclasses set this to true.
+     */
+    _requiresFrames;
+    /**
+     * Create a new sensor instance.
+     *
+     * Note: The id is a random UUID used for RPC namespaces.
+     * The storage key is based on the stable 'name' property.
+     */
+    constructor() {
+        this.id = crypto.randomUUID();
+        // Initialize empty storage
+        this._propertiesStore = {};
+        // Create Proxy for property interception
+        this._propertiesProxy = new Proxy(this._propertiesStore, {
+            set: (target, prop, value) => {
+                const key = prop;
+                const previousValue = target[key];
+                // Only update if value changed
+                if (previousValue !== value) {
+                    target[key] = value;
+                    // Fire-and-forget RPC update
+                    this._updateFn?.(prop, value);
+                    // Notify local listeners (prop is always a valid property enum value)
+                    this._notifyListeners(prop, value, previousValue);
+                }
+                return true;
+            },
+            get: (target, prop) => target[prop],
+        });
+    }
+    /**
+     * Initialize sensor with update function (called by backend)
+     *
+     * @param updateFn - The property update function
+     *
+     * @internal
+     */
+    _init(updateFn) {
+        this._updateFn = updateFn;
+    }
+    /**
+     * Set property value from external source (e.g., RPC)
+     * This bypasses the proxy to avoid re-broadcasting
+     *
+     * @param property - The property name
+     *
+     * @param value - The new property value
+     *
+     * @internal
+     */
+    _setPropertyInternal(property, value) {
+        const previousValue = this._propertiesStore[property];
+        if (previousValue !== value) {
+            this._propertiesStore[property] = value;
+            // property is always a valid property enum value (K extends keyof TProperties)
+            this._notifyListeners(property, value, previousValue);
+        }
+    }
+    /**
+     * Get all current property values
+     *
+     * @internal
+     *
+     * @returns The current properties
+     */
+    _getProperties() {
+        return { ...this._propertiesStore };
+    }
+    /**
+     * Access to proxied properties for derived classes
+     */
+    get props() {
+        return this._propertiesProxy;
+    }
+    /**
+     * Read-only access to raw properties (no proxy)
+     */
+    get rawProps() {
+        return this._propertiesStore;
+    }
+    /**
+     * Whether this sensor is online/available
+     */
+    get online() {
+        return this._online;
+    }
+    /**
+     * Set online state
+     *
+     * @param online - The new online state
+     *
+     * @internal
+     */
+    _setOnline(online) {
+        this._online = online;
+    }
+    /**
+     * Camera ID this sensor belongs to
+     * Set automatically by CameraDevice.addSensor()
+     */
+    get cameraId() {
+        if (!this._cameraId) {
+            throw new Error('Sensor not attached to camera. Call camera.addSensor() first.');
+        }
+        return this._cameraId;
+    }
+    /**
+     * Set camera ID (called by CameraDeviceProxy.addSensor)
+     *
+     * @param cameraId - The camera ID
+     *
+     * @internal
+     */
+    _setCameraId(cameraId) {
+        this._cameraId = cameraId;
+    }
+    /**
+     * Plugin ID that provides this sensor
+     * Set automatically by CameraDevice.addSensor()
+     */
+    get pluginId() {
+        return this._pluginId;
+    }
+    /**
+     * Set plugin ID (called by CameraDeviceProxy.addSensor)
+     *
+     * @param pluginId - The plugin ID
+     *
+     * @internal
+     */
+    _setPluginId(pluginId) {
+        this._pluginId = pluginId;
+    }
+    /**
+     * Storage for sensor-type-specific configuration
+     * Available after sensor is added via CameraDevice.addSensor()
+     * Only available if schemas returns non-empty array
+     */
+    get storage() {
+        return this._storage;
+    }
+    /**
+     * Set storage instance (called by CameraDeviceProxy after addSensor)
+     *
+     * @param storage - The storage instance
+     *
+     * @internal
+     */
+    _setStorage(storage) {
+        this._storage = storage;
+    }
+    /**
+     * Get sensor capabilities
+     * Returns a type-safe array of capabilities for this sensor type.
+     */
+    get capabilities() {
+        return this._capabilities;
+    }
+    /**
+     * Set sensor capabilities
+     * Updates the capabilities and broadcasts to consumers via RPC.
+     * Capabilities are automatically deduplicated.
+     *
+     * @param value - The new capabilities array
+     */
+    set capabilities(value) {
+        // Deduplicate capabilities
+        this._capabilities = [...new Set(value)];
+        // Broadcast to SensorController (for RPC propagation)
+        this._capabilitiesUpdateFn?.(this._capabilities);
+        // Notify local listeners
+        this._notifyCapabilityListeners();
+    }
+    /**
+     * Check if sensor has a specific capability
+     *
+     * @param capability - The capability to check
+     *
+     * @returns True if the sensor has the capability
+     */
+    hasCapability(capability) {
+        return this._capabilities.includes(capability);
+    }
+    /**
+     * Initialize capabilities update function (called by backend)
+     *
+     * @param updateFn - The capability update function
+     *
+     * @internal
+     */
+    _initCapabilities(updateFn) {
+        this._capabilitiesUpdateFn = updateFn;
+    }
+    // ========== Assignment Status ==========
+    /**
+     * Whether this sensor is assigned to be the active provider
+     * for its sensor type on this camera.
+     *
+     * A sensor is "assigned" when the user has selected this plugin
+     * to provide this sensor type for the camera. Unassigned sensors
+     * are still registered but their events are filtered out.
+     *
+     * Use this to conditionally initialize resources:
+     * - Only start ONVIF event subscriptions if assigned
+     * - Only connect to external services if needed
+     */
+    get isAssigned() {
+        return this._isAssigned;
+    }
+    /**
+     * Subscribe to assignment changes.
+     *
+     * Called when the user changes which plugin provides this sensor type.
+     * Use this to react dynamically:
+     * - Start/stop event loops
+     * - Connect/disconnect from external services
+     *
+     * @param callback - Called with true when assigned, false when unassigned
+     *
+     * @returns A function to unsubscribe
+     *
+     * @example
+     * ```typescript
+     * sensor.onAssignmentChanged((assigned) => {
+     *   if (assigned) {
+     *     this.startEventLoop();
+     *   } else {
+     *     this.stopEventLoop();
+     *   }
+     * });
+     * ```
+     */
+    onAssignmentChanged(callback) {
+        this._assignmentListeners.add(callback);
+        return () => this._assignmentListeners.delete(callback);
+    }
+    /**
+     * Set assignment status (called by system)
+     *
+     * @param assigned - Whether this sensor is now assigned
+     *
+     * @internal
+     */
+    _setAssigned(assigned) {
+        if (this._isAssigned !== assigned) {
+            this._isAssigned = assigned;
+            for (const listener of this._assignmentListeners) {
+                try {
+                    listener(assigned);
+                }
+                catch {
+                    // Ignore listener errors
+                }
+            }
+        }
+    }
+    // ========== SensorLike Interface Methods ==========
+    /**
+     * Get a property value by name (SensorLike interface)
+     *
+     * @param property - The property name
+     *
+     * @returns The property value or undefined if not found
+     */
+    getPropertyValue(property) {
+        return this._propertiesStore[property];
+    }
+    /**
+     * Get all property values (SensorLike interface)
+     *
+     * @returns All property values as a record
+     */
+    getAllPropertyValues() {
+        return { ...this._propertiesStore };
+    }
+    /**
+     * Set a property value (SensorLike interface)
+     * For Control sensors, this triggers the property setter through the proxy.
+     *
+     * @param property - The property name
+     *
+     * @param value - The new property value
+     */
+    async setPropertyValue(property, value) {
+        this._propertiesProxy[property] = value;
+    }
+    /**
+     * Add a simple property change listener (SensorLike interface)
+     * This is for consumers who just want property/value pairs.
+     *
+     * @param callback - The callback function to invoke on property changes
+     *
+     * @returns A function to remove the listener
+     */
+    onPropertyChanged(callback) {
+        this._simpleListeners.add(callback);
+        return () => this._simpleListeners.delete(callback);
+    }
+    /**
+     * Add a detailed property change listener
+     * This includes full event details like previous value, timestamps, etc.
+     *
+     * @param callback - The callback function to invoke on detailed property changes
+     *
+     * @returns A function to remove the listener
+     */
+    onPropertyChangedDetailed(callback) {
+        this._listeners.add(callback);
+        return () => this._listeners.delete(callback);
+    }
+    /**
+     * Add a capability change listener (SensorLike interface)
+     * Called when the sensor's capabilities are updated at runtime.
+     *
+     * @param callback - The callback function to invoke on capability changes
+     *
+     * @returns A function to remove the listener
+     */
+    onCapabilitiesChanged(callback) {
+        this._capabilityListeners.add(callback);
+        return () => this._capabilityListeners.delete(callback);
+    }
+    /**
+     * Notify all capability listeners of a capability change
+     */
+    _notifyCapabilityListeners() {
+        for (const listener of this._capabilityListeners) {
+            try {
+                listener(this._capabilities);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+    /**
+     * Notify all listeners of a property change
+     *
+     * @param property - The property name (must be a valid SensorPropertyType)
+     *
+     * @param value - The new property value
+     *
+     * @param previousValue - The previous property value
+     */
+    _notifyListeners(property, value, previousValue) {
+        // Skip notification if sensor not yet attached to camera
+        // (e.g., during constructor initialization)
+        if (!this._cameraId) {
+            return;
+        }
+        const event = {
+            cameraId: this._cameraId,
+            sensorId: this.id,
+            sensorType: this.type,
+            property,
+            value,
+            previousValue,
+            timestamp: Date.now(),
+        };
+        // Notify detailed listeners
+        for (const listener of this._listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+        // Notify simple listeners
+        for (const listener of this._simpleListeners) {
+            try {
+                listener(property, value);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+    /**
+     * Serialize sensor for transport
+     *
+     * @returns The serialized sensor representation
+     */
+    toJSON() {
+        return {
+            id: this.id,
+            type: this.type,
+            name: this.name,
+            displayName: this.displayName || this.name,
+            category: this.category,
+            cameraId: this.cameraId,
+            pluginId: this.pluginId,
+            online: this._online,
+            properties: this._getProperties(),
+            capabilities: this._capabilities,
+            requiresFrames: this._requiresFrames,
+        };
+    }
+}

package/dist/sensor/battery.js

@@ -0,0 +1,101 @@
+import { Sensor } from './base.js';
+import { ChargingState, SensorCategory, SensorType } from './types.js';
+/**
+ * Battery Capability enum
+ * Describes what Battery features this sensor supports
+ * Note: "level" property is always available (standard)
+ */
+export var BatteryCapability;
+(function (BatteryCapability) {
+    /** Supports low battery detection */
+    BatteryCapability["LowBattery"] = "lowBattery";
+    /** Supports charging state detection */
+    BatteryCapability["Charging"] = "charging";
+})(BatteryCapability || (BatteryCapability = {}));
+/**
+ * Battery info property keys
+ */
+export var BatteryProperty;
+(function (BatteryProperty) {
+    BatteryProperty["Level"] = "level";
+    BatteryProperty["Charging"] = "charging";
+    BatteryProperty["Low"] = "low";
+})(BatteryProperty || (BatteryProperty = {}));
+/**
+ * Battery Info
+ *
+ * Read-only hardware status for battery-powered cameras.
+ */
+export class BatteryInfo extends Sensor {
+    type = SensorType.Battery;
+    category = SensorCategory.Info;
+    name;
+    /** Threshold for low battery warning (default: 20%) */
+    lowBatteryThreshold = 20;
+    constructor(name = 'Battery') {
+        super();
+        this.name = name;
+        // Initialize defaults
+        this.props.level = 100;
+        this.props.charging = ChargingState.NotCharging;
+        this.props.low = false;
+    }
+    // ========== Properties (Getter/Setter Pairs) ==========
+    /** Battery level (0-100) */
+    get level() {
+        return this.rawProps.level;
+    }
+    /** Set battery level (0-100) */
+    set level(value) {
+        const clampedValue = Math.max(0, Math.min(100, value));
+        this.props.level = clampedValue;
+        // Auto-update low battery state
+        this.props.low = clampedValue <= this.lowBatteryThreshold;
+    }
+    /** Charging state */
+    get charging() {
+        return this.rawProps.charging;
+    }
+    /** Set charging state */
+    set charging(value) {
+        this.props.charging = value;
+    }
+    /** Whether battery is low */
+    get low() {
+        return this.rawProps.low;
+    }
+    /** Set low battery state */
+    set low(value) {
+        this.props.low = value;
+    }
+    // ========== Convenience Methods ==========
+    /**
+     * Update battery state
+     *
+     * @param level - Battery level (0-100)
+     *
+     * @param charging - Charging state
+     */
+    setBattery(level, charging) {
+        this.level = level;
+        if (charging !== undefined) {
+            this.props.charging = charging;
+        }
+    }
+    /**
+     * Check if battery is charging
+     *
+     * @returns True if battery is charging, false otherwise
+     */
+    isCharging() {
+        return this.charging === ChargingState.Charging;
+    }
+    /**
+     * Check if battery is fully charged
+     *
+     * @returns True if battery is fully charged, false otherwise
+     */
+    isFullyCharged() {
+        return this.charging === ChargingState.Full || this.level === 100;
+    }
+}

package/dist/sensor/contact.js

@@ -0,0 +1,33 @@
+import { Sensor } from './base.js';
+import { SensorCategory, SensorType } from './types.js';
+/**
+ * Contact sensor property keys
+ */
+export var ContactProperty;
+(function (ContactProperty) {
+    ContactProperty["Detected"] = "detected";
+})(ContactProperty || (ContactProperty = {}));
+/**
+ * Contact Sensor
+ *
+ * Detects contact state (open/closed) for doors, windows, etc.
+ */
+export class ContactSensor extends Sensor {
+    type = SensorType.Contact;
+    category = SensorCategory.Sensor;
+    name;
+    constructor(name = 'Contact Sensor') {
+        super();
+        this.name = name;
+        // Initialize defaults
+        this.props.detected = false;
+    }
+    /** Whether contact is detected (closed) */
+    get detected() {
+        return this.rawProps.detected;
+    }
+    /** Set contact detected state */
+    set detected(value) {
+        this.props.detected = value;
+    }
+}

package/dist/sensor/doorbell.js

@@ -0,0 +1,63 @@
+import { Sensor } from './base.js';
+import { SensorCategory, SensorType } from './types.js';
+/**
+ * Doorbell trigger property keys
+ */
+export var DoorbellProperty;
+(function (DoorbellProperty) {
+    DoorbellProperty["Ring"] = "ring";
+})(DoorbellProperty || (DoorbellProperty = {}));
+/**
+ * Doorbell Trigger
+ *
+ * Event-based trigger for doorbell rings.
+ * Ring property auto-resets after a short delay.
+ */
+export class DoorbellTrigger extends Sensor {
+    type = SensorType.Doorbell;
+    category = SensorCategory.Trigger;
+    name;
+    _resetTimeout;
+    constructor(name = 'Doorbell') {
+        super();
+        this.name = name;
+        // Initialize defaults
+        this.props.ring = false;
+    }
+    // ========== Properties (Getter/Setter Pairs) ==========
+    /** Whether doorbell is currently ringing */
+    get ring() {
+        return this.rawProps.ring;
+    }
+    /** Set ring state */
+    set ring(value) {
+        this.props.ring = value;
+    }
+    // ========== Convenience Methods ==========
+    /**
+     * Trigger doorbell ring
+     * Auto-resets after duration (default: 1000ms)
+     *
+     * @param resetAfterMs - Duration in milliseconds to auto-reset ring state
+     */
+    triggerRing(resetAfterMs = 1000) {
+        // Clear any existing reset timeout
+        if (this._resetTimeout) {
+            clearTimeout(this._resetTimeout);
+        }
+        this.props.ring = true;
+        // Auto-reset after duration
+        this._resetTimeout = setTimeout(() => {
+            this.props.ring = false;
+            this._resetTimeout = undefined;
+        }, resetAfterMs);
+    }
+    /** Reset ring state immediately */
+    resetRing() {
+        if (this._resetTimeout) {
+            clearTimeout(this._resetTimeout);
+            this._resetTimeout = undefined;
+        }
+        this.props.ring = false;
+    }
+}