@camera.ui/sdk 0.0.3 → 0.0.5

package/dist/sensor/light.js

@@ -1,66 +1,110 @@
-import { Sensor } from './base.js';
-import { SensorCategory, SensorType } from './types.js';
-/**
- * Light Capability enum
- * Describes what Light features this sensor supports
- * Note: "on" property is always available (standard)
- */
+import { Sensor, SensorType, SensorCategory } from './base.js';
+/** Optional capabilities for light controls */
 export var LightCapability;
 (function (LightCapability) {
-    /** Supports brightness control */
+    /** Light supports brightness adjustment (0–100) */
     LightCapability["Brightness"] = "brightness";
 })(LightCapability || (LightCapability = {}));
 /**
- * Light control property keys
+ * Properties for light controls
+ *
+ * @internal
  */
 export var LightProperty;
 (function (LightProperty) {
+    /** Whether the light is on */
     LightProperty["On"] = "on";
+    /** Brightness level (0–100) */
     LightProperty["Brightness"] = "brightness";
 })(LightProperty || (LightProperty = {}));
 /**
- * Light Control
+ * Light control sensor. Override `setOn()`/`setOff()` to drive your hardware,
+ * then `await super.setOn()` / `await super.setOff()` to sync the SDK state.
  *
- * Bidirectional control for camera spotlight/floodlight.
- * Properties can be set directly: `light.on = true`
+ * Plugins that have no hardware-action use case can leave the methods unoverridden —
+ * the base implementation just updates the state.
+ *
+ * For hardware-pushed updates (someone manually flipped the switch), call
+ * `super.setOn()` / `super.setOff()` from your event handler — that bypasses
+ * any plugin override and only syncs state.
  */
 export class LightControl extends Sensor {
     type = SensorType.Light;
     category = SensorCategory.Control;
-    name;
     constructor(name = 'Light') {
-        super();
-        this.name = name;
-        // Initialize defaults
-        this.props.on = false;
-        this.props.brightness = 100;
+        super(name);
+        this._writeState({
+            [LightProperty.On]: false,
+            [LightProperty.Brightness]: 100,
+        });
     }
-    /** Whether light is on */
     get on() {
-        return this.rawProps.on;
-    }
-    /** Turn light on/off */
-    set on(value) {
-        this.props.on = value;
+        return this.props.on;
     }
-    /** Brightness level (0-100) */
     get brightness() {
-        return this.rawProps.brightness;
+        return this.props.brightness;
     }
-    /** Set brightness level (0-100) */
-    set brightness(value) {
-        this.props.brightness = Math.max(0, Math.min(100, value));
+    /**
+     * Turn the light on. Override to drive hardware and call `await super.setOn()`
+     * after the hardware call succeeds to sync the SDK state.
+     *
+     * @example
+     * ```ts
+     * await light.setOn();
+     * ```
+     */
+    async setOn() {
+        this._writeState({ [LightProperty.On]: true });
     }
-    /** Turn light on */
-    turnOn() {
-        this.props.on = true;
+    /**
+     * Turn the light off. Override to drive hardware and call `await super.setOff()`
+     * after the hardware call succeeds to sync the SDK state.
+     *
+     * @example
+     * ```ts
+     * await light.setOff();
+     * ```
+     */
+    async setOff() {
+        this._writeState({ [LightProperty.On]: false });
     }
-    /** Turn light off */
-    turnOff() {
-        this.props.on = false;
+    /**
+     * Set brightness. Override to drive hardware and call `await super.setBrightness(value)`
+     * after the hardware call succeeds. The default implementation clamps the value to [0, 100].
+     *
+     * @param value - Brightness level in the range 0–100.
+     *
+     * @example
+     * ```ts
+     * await light.setBrightness(75);
+     * ```
+     */
+    async setBrightness(value) {
+        this._writeState({ [LightProperty.Brightness]: Math.max(0, Math.min(100, value)) });
     }
-    /** Toggle light state */
-    toggle() {
-        this.props.on = !this.on;
+    /**
+     * Cross-process consumer entry point. Dispatches writable properties
+     * to semantic methods so plugin overrides (hardware actions) are honored.
+     * Unknown properties are ignored — only `On` and `Brightness` are externally writable.
+     *
+     * @param property - Property name to write.
+     *
+     * @param value - New value for the property.
+     *
+     * @internal
+     */
+    async updateValue(property, value) {
+        switch (property) {
+            case LightProperty.On:
+                if (value)
+                    await this.setOn();
+                else
+                    await this.setOff();
+                return;
+            case LightProperty.Brightness:
+                await this.setBrightness(value);
+                return;
+        }
+        // Unknown / non-writable property — ignored.
     }
 }

package/dist/sensor/lock.js

@@ -0,0 +1,99 @@
+import { Sensor, SensorType, SensorCategory } from './base.js';
+/** Lock states (HomeKit-compatible values) */
+export var LockState;
+(function (LockState) {
+    LockState[LockState["Secured"] = 0] = "Secured";
+    LockState[LockState["Unsecured"] = 1] = "Unsecured";
+    LockState[LockState["Unknown"] = 2] = "Unknown";
+})(LockState || (LockState = {}));
+/**
+ * Properties for lock controls
+ *
+ * @internal
+ */
+export var LockProperty;
+(function (LockProperty) {
+    /** The actual current state of the lock */
+    LockProperty["CurrentState"] = "currentState";
+    /** The desired target state (set by user, transitions to currentState) */
+    LockProperty["TargetState"] = "targetState";
+})(LockProperty || (LockProperty = {}));
+/**
+ * Lock control. Override `setTargetState()` to drive hardware and call
+ * `await super.setTargetState(value)` once the hardware confirms — the base
+ * implementation updates both `targetState` and `currentState` to the new value.
+ *
+ * For asymmetric flows (long-running unlock with intermediate state) override
+ * `setTargetState` and write `currentState` separately when transitions complete.
+ */
+export class LockControl extends Sensor {
+    type = SensorType.Lock;
+    category = SensorCategory.Control;
+    constructor(name = 'Lock') {
+        super(name);
+        this._writeState({
+            [LockProperty.CurrentState]: LockState.Secured,
+            [LockProperty.TargetState]: LockState.Secured,
+        });
+    }
+    get currentState() {
+        return this.props.currentState;
+    }
+    get targetState() {
+        return this.props.targetState;
+    }
+    /**
+     * Set the target state. Override to drive hardware and call
+     * `await super.setTargetState(value)` after success — the base implementation
+     * syncs both `targetState` and `currentState` to the new value.
+     *
+     * @param value - Desired lock state from the {@link LockState} enum.
+     *
+     * @example
+     * ```ts
+     * import { LockState } from '@camera.ui/sdk';
+     * await lock.setTargetState(LockState.Secured);
+     * ```
+     */
+    async setTargetState(value) {
+        this._writeState({
+            [LockProperty.TargetState]: value,
+            [LockProperty.CurrentState]: value,
+        });
+    }
+    /**
+     * Publish the actual lock state. Use this to drive transitions where the
+     * physical state diverges from the user-requested target — e.g. motorized
+     * smart locks that take time to rotate (publish `Unknown` while moving),
+     * or hardware reporting an out-of-band state change. Read-only from
+     * cross-process consumers (`updateValue` ignores it).
+     *
+     * @param value - Current physical lock state from the {@link LockState} enum.
+     *
+     * @example
+     * ```ts
+     * import { LockState } from '@camera.ui/sdk';
+     * lock.setCurrentState(LockState.Unknown);
+     * ```
+     */
+    setCurrentState(value) {
+        this._writeState({ [LockProperty.CurrentState]: value });
+    }
+    /**
+     * Cross-process consumer entry point. Dispatches writable properties
+     * to semantic methods so plugin overrides (hardware actions) are honored.
+     * `currentState` is observed-only and not externally writable; only `targetState` may be set.
+     *
+     * @param property - Property name to write.
+     *
+     * @param value - New value for the property.
+     *
+     * @internal
+     */
+    async updateValue(property, value) {
+        if (property === LockProperty.TargetState) {
+            await this.setTargetState(value);
+        }
+        // Unknown / non-writable property (incl. currentState) — ignored.
+    }
+}

package/dist/sensor/motion.js

@@ -1,103 +1,118 @@
-import { Sensor } from './base.js';
-import { SensorCategory, SensorType } from './types.js';
+import { Sensor, SensorType, SensorCategory } from './base.js';
 /**
- * Motion sensor property keys
+ * Property names of a motion sensor.
+ *
+ * @internal
  */
 export var MotionProperty;
 (function (MotionProperty) {
+    /** Whether motion is currently detected. */
     MotionProperty["Detected"] = "detected";
+    /** List of detection results with bounding boxes. */
     MotionProperty["Detections"] = "detections";
+    /** When true, detection updates are suppressed (set by the backend dwell logic). */
+    MotionProperty["Blocked"] = "blocked";
+    /** Timestamp in milliseconds of the last detection trigger, set by the backend. */
+    MotionProperty["LastTriggered"] = "lastTriggered";
 })(MotionProperty || (MotionProperty = {}));
 /**
- * Motion Sensor
- *
- * Base class for external motion detection (Ring, ONVIF events, SMTP, etc.)
- * Properties can be set directly: `sensor.detected = true`
+ * Motion sensor that reports motion state and detection results.
  *
- * For frame-based motion detection, use `MotionDetectorSensor` instead.
+ * Plugin authors call `reportDetections(list)` to push detection results.
+ * `detected` is auto-derived from the detection list. `blocked` is read-only
+ * and is set by the backend (dwell logic) — `reportDetections()` becomes a
+ * no-op while the sensor is blocked.
  */
 export class MotionSensor extends Sensor {
     type = SensorType.Motion;
     category = SensorCategory.Sensor;
-    name;
-    /**
-     * External motion sensors don't require video frames.
-     * They receive motion events from external sources (SMTP, ONVIF, Ring API, etc.)
-     */
     _requiresFrames = false;
     constructor(name = 'Motion Sensor') {
-        super();
-        this.name = name;
-        // Initialize defaults
-        this.props.detected = false;
-        this.props.detections = [];
+        super(name);
+        this._writeState({
+            [MotionProperty.Detected]: false,
+            [MotionProperty.Detections]: [],
+            [MotionProperty.Blocked]: false,
+        });
     }
-    /** Whether motion is currently detected */
+    /** Whether motion is currently detected. */
     get detected() {
-        return this.rawProps.detected;
-    }
-    /** Set motion detected state */
-    set detected(value) {
-        this.props.detected = value;
+        return this.props.detected;
     }
-    /** Current motion detections */
+    /** Current detection list. */
     get detections() {
-        return this.rawProps.detections;
+        return this.props.detections;
     }
-    /** Set motion detections */
-    set detections(value) {
-        this.props.detections = value;
+    /** Whether the sensor is currently blocked. Read-only — set by the backend dwell logic, not by plugin code. */
+    get blocked() {
+        return this.props.blocked;
     }
     /**
-     * Update both detected state and detections at once
+     * Report a motion detection result.
+     *
+     * - `reportDetections(true)` — motion detected without bbox (e.g. Ring camera).
+     *   The SDK synthesizes a single full-frame `'motion'` detection.
+     * - `reportDetections(true, [...])` — motion detected with explicit detections.
+     * - `reportDetections(false)` — no motion (clears detections).
      *
-     * @param detected - Whether motion is detected
+     * No-op while the sensor is blocked by backend dwell logic.
+     *
+     * @param detected - Whether motion is currently detected.
+     *
+     * @param detections - Optional explicit detections produced for this frame.
+     *
+     * @example
+     * ```ts
+     * import type { Detection } from '@camera.ui/sdk';
+     * sensor.reportDetections(true, [
+     *   { label: 'motion', confidence: 0.85, box: { x: 0.1, y: 0.2, width: 0.3, height: 0.4 } } satisfies Detection,
+     * ]);
+     * sensor.reportDetections(false);
+     * ```
+     */
+    reportDetections(detected, detections) {
+        if (this.blocked)
+            return;
+        const list = this._normalizeReportedDetections(detected, detections, 'motion');
+        this._writeState({
+            [MotionProperty.Detected]: detected,
+            [MotionProperty.Detections]: list,
+        });
+    }
+    /**
+     * Explicitly clear motion state (detected = false, detections = []).
      *
-     * @param detections - Array of motion detections
+     * @example
+     * ```ts
+     * sensor.clearDetections();
+     * ```
      */
-    setMotion(detected, detections = []) {
-        this.props.detected = detected;
-        this.props.detections = detections;
+    clearDetections() {
+        this.reportDetections(false);
     }
-    /** Clear motion state */
-    clearMotion() {
-        this.props.detected = false;
-        this.props.detections = [];
+    /**
+     * Read-only sensor: external writes are ignored. State is reported via `reportDetections`.
+     *
+     * Called by the cross-process plugin host when a generic property write is received.
+     * Motion sensors have no externally writable properties, so the parameters are
+     * unused (underscore-prefixed) and the call is a no-op.
+     *
+     * @param _property - Unused — motion sensors expose no writable properties.
+     *
+     * @param _value - Unused — motion sensors expose no writable properties.
+     *
+     * @internal
+     */
+    updateValue(_property, _value) {
+        // No-op — motion state is reported by the plugin, not set externally.
     }
 }
 /**
- * Motion Detector Sensor (Active Detection)
- *
- * Use this class for frame-based motion detection (rust-motion, OpenCV, etc.)
- * The `inputProperties` getter specifies the required input format.
- *
- * For external motion events (Ring, ONVIF, SMTP), use the base `MotionSensor` class instead.
- *
- * @example
- * ```typescript
- * class RustMotionDetector extends MotionDetectorSensor {
- *   get inputProperties(): VideoInputProperties {
- *     return { width: 320, height: 240, format: 'gray' };
- *   }
- *
- *   async detectMotion(frame: VideoFrameData): Promise<MotionResult> {
- *     const result = await this.rustDetector.process(frame.data);
- *     return {
- *       detected: result.motionDetected,
- *       detections: result.regions.map(r => ({
- *         label: 'motion',
- *         confidence: r.intensity,
- *         box: r.boundingBox,
- *       })),
- *     };
- *   }
- * }
- * ```
+ * Motion detector that receives video frames from the backend pipeline.
+ * Extend this class and implement {@link detectMotion} to analyze frames
+ * for motion. The backend calls `detectMotion()` at the configured frame
+ * interval and applies the returned result to the sensor.
  */
 export class MotionDetectorSensor extends MotionSensor {
-    /**
-     * Indicates this sensor requires video frames for detection.
-     * Used by the backend to determine streaming requirements.
-     */
     _requiresFrames = true;
 }

package/dist/sensor/object.js

@@ -1,137 +1,116 @@
-import { Sensor } from './base.js';
-import { SensorCategory, SensorType } from './types.js';
+import { Sensor, SensorType, SensorCategory } from './base.js';
 /**
- * Object sensor property keys
+ * Property names of an object detection sensor.
+ *
+ * @internal
  */
 export var ObjectProperty;
 (function (ObjectProperty) {
+    /** Whether any object is currently detected. */
     ObjectProperty["Detected"] = "detected";
+    /** List of detected objects with labels and bounding boxes. */
     ObjectProperty["Detections"] = "detections";
+    /** Unique labels of the current detections (auto-derived when reporting detections). */
     ObjectProperty["Labels"] = "labels";
 })(ObjectProperty || (ObjectProperty = {}));
 /**
- * Object Sensor
- *
- * Base class for external object detection (Ring, ONVIF events, Eufy, etc.)
- * Properties can be set directly: `sensor.detected = true`
+ * Object detection sensor that reports detected objects (person, vehicle, animal, etc.).
  *
- * For frame-based object detection, use `ObjectDetectorSensor` instead.
+ * Plugin authors call `reportDetections(list)` to push detection results.
+ * `detected` and `labels` are auto-derived from the detection list.
  */
 export class ObjectSensor extends Sensor {
     type = SensorType.Object;
     category = SensorCategory.Sensor;
-    name;
-    /**
-     * External object sensors don't require video frames.
-     * They receive detection events from external sources (APIs, ONVIF, etc.)
-     */
     _requiresFrames = false;
     constructor(name = 'Object Sensor') {
-        super();
-        this.name = name;
-        // Initialize defaults
-        this.props.detected = false;
-        this.props.detections = [];
-        this.props.labels = [];
+        super(name);
+        this._writeState({
+            [ObjectProperty.Detected]: false,
+            [ObjectProperty.Detections]: [],
+            [ObjectProperty.Labels]: [],
+        });
     }
-    /** Whether objects are currently detected */
+    /** Whether any object is currently detected. */
     get detected() {
-        return this.rawProps.detected;
-    }
-    /** Set object detected state */
-    set detected(value) {
-        this.props.detected = value;
+        return this.props.detected;
     }
-    /** Current object detections */
+    /** Current detection list. */
     get detections() {
-        return this.rawProps.detections;
+        return this.props.detections;
     }
-    /** Set object detections */
-    set detections(value) {
-        this.props.detections = value;
-    }
-    /** Labels currently being detected */
+    /** Unique labels of the current detections. */
     get labels() {
-        return this.rawProps.labels;
-    }
-    /** Set detected labels */
-    set labels(value) {
-        this.props.labels = value;
+        return this.props.labels;
     }
     /**
-     * Update object detection state
+     * Report detected objects. Auto-derives `detected` and `labels` from the list.
+     *
+     * - `reportDetections(true)` — something detected without specific data. The SDK
+     *   synthesizes a single full-frame `'motion'` detection as a generic fallback.
+     * - `reportDetections(true, [...])` — explicit detections (typical case).
+     * - `reportDetections(false)` — clear.
      *
-     * @param detected - Whether objects are detected
+     * @param detected - Whether any object is currently detected.
      *
-     * @param detections - Array of object detections
+     * @param detections - Optional explicit object detections (with optional tracking metadata).
+     *
+     * @example
+     * ```ts
+     * import type { TrackedDetection } from '@camera.ui/sdk';
+     * sensor.reportDetections(true, [
+     *   {
+     *     label: 'person',
+     *     confidence: 0.92,
+     *     box: { x: 0.1, y: 0.2, width: 0.3, height: 0.4 },
+     *   } satisfies TrackedDetection,
+     * ]);
+     * sensor.reportDetections(false);
+     * ```
      */
-    setObjects(detected, detections = []) {
-        this.props.detected = detected;
-        this.props.detections = detections;
-        // Extract unique labels from detections
-        const labelSet = new Set(detections.map((d) => d.label));
-        this.props.labels = Array.from(labelSet);
-    }
-    /** Clear object detection state */
-    clearObjects() {
-        this.props.detected = false;
-        this.props.detections = [];
-        this.props.labels = [];
+    reportDetections(detected, detections) {
+        const list = this._normalizeReportedDetections(detected, detections, 'motion');
+        const labels = Array.from(new Set(list.map((d) => d.label)));
+        this._writeState({
+            [ObjectProperty.Detected]: detected,
+            [ObjectProperty.Detections]: list,
+            [ObjectProperty.Labels]: labels,
+        });
     }
     /**
-     * Get detections filtered by label
+     * Explicitly clear detection state (detected = false, detections = [], labels = []).
      *
-     * @param label - The label to filter detections by
-     *
-     * @returns Array of detections matching the label
+     * @example
+     * ```ts
+     * sensor.clearDetections();
+     * ```
      */
-    getDetectionsByLabel(label) {
-        return this.detections.filter((d) => d.label === label);
+    clearDetections() {
+        this.reportDetections(false);
     }
     /**
-     * Check if specific label is detected
+     * Read-only sensor: external writes are ignored. State is reported via `reportDetections`.
+     *
+     * Called by the cross-process plugin host when a generic property write is received.
+     * Object detection sensors have no externally writable properties, so the parameters are
+     * unused (underscore-prefixed) and the call is a no-op.
+     *
+     * @param _property - Unused — object detection sensors expose no writable properties.
      *
-     * @param label - Label to check
+     * @param _value - Unused — object detection sensors expose no writable properties.
      *
-     * @returns True if label is detected, false otherwise
+     * @internal
      */
-    hasLabel(label) {
-        return this.labels.includes(label);
+    updateValue(_property, _value) {
+        // No-op — object detection state is reported by the plugin, not set externally.
     }
 }
 /**
- * Object Detector Sensor (Active Detection)
- *
- * Use this class for frame-based object detection (TensorFlow, YOLO, etc.)
- * The `inputProperties` getter specifies the required input format.
- *
- * For external object events, use the base `ObjectSensor` class instead.
- *
- * @example
- * ```typescript
- * class TensorFlowObjectDetector extends ObjectDetectorSensor {
- *   get inputProperties(): VideoInputProperties {
- *     return { width: 640, height: 640, format: 'rgb' };
- *   }
- *
- *   async detectObjects(frame: VideoFrameData): Promise<ObjectResult> {
- *     const predictions = await this.model.detect(frame.data);
- *     return {
- *       detected: predictions.length > 0,
- *       detections: predictions.map(p => ({
- *         label: p.class,
- *         confidence: p.score,
- *         box: p.bbox,
- *       })),
- *     };
- *   }
- * }
- * ```
+ * Object detector that receives video frames from the backend pipeline.
+ * Extend this class and implement {@link detectObjects} and {@link modelSpec}.
+ * The backend scales frames to match `modelSpec.input` dimensions before
+ * each call.
  */
 export class ObjectDetectorSensor extends ObjectSensor {
-    /**
-     * Indicates this sensor requires video frames for detection.
-     * Used by the backend to determine streaming requirements.
-     */
     _requiresFrames = true;
 }