@camera.ui/sdk 0.0.2 → 0.0.4

package/dist/sensor/face.js

@@ -1,124 +1,109 @@
-import { Sensor } from './base.js';
-import { SensorCategory, SensorType } from './types.js';
+import { Sensor, SensorType, SensorCategory } from './base.js';
 /**
- * Face sensor property keys
+ * Property names of a face detection sensor.
+ *
+ * @internal
  */
 export var FaceProperty;
 (function (FaceProperty) {
+    /** Whether any face is currently detected. */
     FaceProperty["Detected"] = "detected";
-    FaceProperty["Faces"] = "faces";
+    /** List of detected faces with optional identity, embedding, and thumbnail. */
+    FaceProperty["Detections"] = "detections";
 })(FaceProperty || (FaceProperty = {}));
 /**
- * Face Sensor (Specialized)
+ * Face sensor that reports detected faces and optional identity matches.
  *
- * Detects and recognizes faces in camera frames.
- * Can optionally receive person regions from ObjectSensor for focused detection.
+ * Plugin authors call `reportDetections(list)` to push detected faces.
+ * `detected` is auto-derived from the detection list.
  */
 export class FaceSensor extends Sensor {
     type = SensorType.Face;
     category = SensorCategory.Sensor;
-    name;
     constructor(name = 'Face Sensor') {
-        super();
-        this.name = name;
-        // Initialize defaults
-        this.props.detected = false;
-        this.props.faces = [];
+        super(name);
+        this._writeState({
+            [FaceProperty.Detected]: false,
+            [FaceProperty.Detections]: [],
+        });
     }
-    // ========== Properties (Getter/Setter Pairs) ==========
-    /** Whether faces are currently detected */
+    /** Whether any face is currently detected. */
     get detected() {
-        return this.rawProps.detected;
-    }
-    /** Set face detected state */
-    set detected(value) {
-        this.props.detected = value;
+        return this.props.detected;
     }
-    /** Current face detections */
-    get faces() {
-        return this.rawProps.faces;
-    }
-    /** Set face detections */
-    set faces(value) {
-        this.props.faces = value;
+    /** Current detection list. */
+    get detections() {
+        return this.props.detections;
     }
     /**
-     * Update face detection state
+     * Report detected faces.
      *
-     * @param detected - Whether faces are detected
+     * - `reportDetections(true)` — face detected without specifics (e.g. a
+     *   bare face-event from a discovery provider). The SDK synthesizes a
+     *   single full-frame face detection without identity.
+     * - `reportDetections(true, [...])` — explicit face detections with
+     *   identity, embedding, and/or thumbnail.
+     * - `reportDetections(false)` — clear.
      *
-     * @param faces - Array of face detections
-     */
-    setFaces(detected, faces = []) {
-        this.props.detected = detected;
-        this.props.faces = faces;
-    }
-    /** Clear face detection state */
-    clearFaces() {
-        this.props.detected = false;
-        this.props.faces = [];
-    }
-    /**
-     * Get faces with known identity
+     * @param detected - Whether any face is currently detected.
+     *
+     * @param detections - Optional explicit face detections to publish.
      *
-     * @returns Array of recognized faces
+     * @example
+     * ```ts
+     * import type { FaceDetection } from '@camera.ui/sdk';
+     * sensor.reportDetections(true, [
+     *   {
+     *     label: 'person',
+     *     confidence: 0.94,
+     *     box: { x: 0.4, y: 0.2, width: 0.15, height: 0.25 },
+     *     attribute: 'face',
+     *     identity: 'Alice',
+     *   } satisfies FaceDetection,
+     * ]);
+     * sensor.reportDetections(false);
+     * ```
      */
-    getKnownFaces() {
-        return this.faces.filter((f) => f.identity !== undefined);
+    reportDetections(detected, detections) {
+        const list = this._normalizeReportedDetections(detected, detections, 'person', { attribute: 'face' });
+        this._writeState({
+            [FaceProperty.Detected]: detected,
+            [FaceProperty.Detections]: list,
+        });
     }
     /**
-     * Get faces without known identity
+     * Explicitly clear face detection state (detected = false, detections = []).
      *
-     * @returns Array of unrecognized faces
+     * @example
+     * ```ts
+     * sensor.clearDetections();
+     * ```
      */
-    getUnknownFaces() {
-        return this.faces.filter((f) => f.identity === undefined);
+    clearDetections() {
+        this.reportDetections(false);
     }
     /**
-     * Check if specific identity is detected
+     * Read-only sensor: external writes are ignored. State is reported via `reportDetections`.
      *
-     * @param identity - Identity label to check
+     * Called by the cross-process plugin host when a generic property write is received.
+     * Face sensors have no externally writable properties, so the parameters are
+     * unused (underscore-prefixed) and the call is a no-op.
      *
-     * @returns True if identity is detected, false otherwise
+     * @param _property - Unused — face sensors expose no writable properties.
+     *
+     * @param _value - Unused — face sensors expose no writable properties.
+     *
+     * @internal
      */
-    hasIdentity(identity) {
-        return this.faces.some((f) => f.identity === identity);
+    updateValue(_property, _value) {
+        // No-op — face detection state is reported by the plugin, not set externally.
     }
 }
 /**
- * Face Detector Sensor (Active Detection)
- *
- * Use this class for frame-based face detection (face-api.js, DeepFace, etc.)
- * The `inputProperties` getter specifies the required input format.
- *
- * Receives cropped person regions from ObjectDetectorSensor for efficient processing.
- *
- * @example
- * ```typescript
- * class FaceAPIDetector extends FaceDetectorSensor {
- *   get inputProperties(): VideoInputProperties {
- *     return { width: 160, height: 160, format: 'rgb' };
- *   }
- *
- *   async detectFaces(frame: VideoFrameData, personRegions?: Detection[]): Promise<FaceResult> {
- *     const detections = await faceapi.detectAllFaces(frame.data);
- *     return {
- *       detected: detections.length > 0,
- *       faces: detections.map(d => ({
- *         label: 'face',
- *         confidence: d.score,
- *         box: d.box,
- *         identity: d.identity,
- *       })),
- *     };
- *   }
- * }
- * ```
+ * Face detector that receives video frames from the backend pipeline.
+ * Extend this class and implement {@link detectFaces} for face detection
+ * and recognition.
  */
 export class FaceDetectorSensor extends FaceSensor {
-    /**
-     * Indicates this sensor requires video frames for detection.
-     * Used by the backend to determine streaming requirements.
-     */
     _requiresFrames = true;
 }

package/dist/sensor/garage.js

@@ -0,0 +1,121 @@
+import { Sensor, SensorType, SensorCategory } from './base.js';
+/** Garage door states (HomeKit-compatible values) */
+export var GarageState;
+(function (GarageState) {
+    GarageState[GarageState["Open"] = 0] = "Open";
+    GarageState[GarageState["Closed"] = 1] = "Closed";
+    GarageState[GarageState["Opening"] = 2] = "Opening";
+    GarageState[GarageState["Closing"] = 3] = "Closing";
+    GarageState[GarageState["Stopped"] = 4] = "Stopped";
+})(GarageState || (GarageState = {}));
+/**
+ * Properties for garage controls
+ *
+ * @internal
+ */
+export var GarageProperty;
+(function (GarageProperty) {
+    /** The actual current state of the garage door */
+    GarageProperty["CurrentState"] = "currentState";
+    /** The desired target state (set by user, transitions to currentState) */
+    GarageProperty["TargetState"] = "targetState";
+    /** Whether an obstruction is detected */
+    GarageProperty["ObstructionDetected"] = "obstructionDetected";
+})(GarageProperty || (GarageProperty = {}));
+/**
+ * Garage door control. Override `setTargetState()` to drive hardware and call
+ * `await super.setTargetState(value)` once the hardware confirms — the base
+ * implementation updates both `targetState` and `currentState`.
+ *
+ * For long-running transitions (Opening/Closing intermediate states), override
+ * `setTargetState` and write `currentState` separately as the door moves.
+ */
+export class GarageControl extends Sensor {
+    type = SensorType.Garage;
+    category = SensorCategory.Control;
+    constructor(name = 'Garage') {
+        super(name);
+        this._writeState({
+            [GarageProperty.CurrentState]: GarageState.Closed,
+            [GarageProperty.TargetState]: GarageState.Closed,
+            [GarageProperty.ObstructionDetected]: false,
+        });
+    }
+    get currentState() {
+        return this.props.currentState;
+    }
+    get targetState() {
+        return this.props.targetState;
+    }
+    get obstructionDetected() {
+        return this.props.obstructionDetected;
+    }
+    /**
+     * 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 target state from the {@link GarageState} enum.
+     *
+     * @example
+     * ```ts
+     * import { GarageState } from '@camera.ui/sdk';
+     * await garage.setTargetState(GarageState.Open);
+     * ```
+     */
+    async setTargetState(value) {
+        this._writeState({
+            [GarageProperty.TargetState]: value,
+            [GarageProperty.CurrentState]: value,
+        });
+    }
+    /**
+     * Publish the actual door state. Use this to drive long-running transitions
+     * (e.g. Open → Closing → Closed) independently of the user-requested target
+     * state. Read-only from cross-process consumers (`updateValue` ignores it).
+     *
+     * @param value - Current physical door state from the {@link GarageState} enum.
+     *
+     * @example
+     * ```ts
+     * import { GarageState } from '@camera.ui/sdk';
+     * garage.setCurrentState(GarageState.Closing);
+     * ```
+     */
+    setCurrentState(value) {
+        this._writeState({ [GarageProperty.CurrentState]: value });
+    }
+    /**
+     * Publish the obstruction-detected state. Read-only from the consumer side
+     * (`updateValue` ignores it) — plugin code calls this when its hardware
+     * reports an obstruction sensor change.
+     *
+     * @param value - True when an obstruction is currently detected.
+     *
+     * @example
+     * ```ts
+     * garage.setObstructionDetected(true);
+     * ```
+     */
+    setObstructionDetected(value) {
+        this._writeState({ [GarageProperty.ObstructionDetected]: value });
+    }
+    /**
+     * Cross-process consumer entry point. Dispatches writable properties
+     * to semantic methods so plugin overrides (hardware actions) are honored.
+     * `currentState` and `obstructionDetected` are 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 === GarageProperty.TargetState) {
+            await this.setTargetState(value);
+        }
+        // Unknown / non-writable property (incl. currentState, obstructionDetected) — ignored.
+    }
+}

package/dist/sensor/humidity.js

@@ -0,0 +1,52 @@
+import { Sensor, SensorType, SensorCategory } from './base.js';
+/**
+ * Properties for humidity sensors
+ *
+ * @internal
+ */
+export var HumidityProperty;
+(function (HumidityProperty) {
+    /** Current relative humidity (0–100%) */
+    HumidityProperty["Current"] = "current";
+})(HumidityProperty || (HumidityProperty = {}));
+/** Humidity info sensor. Reports current relative humidity in %. */
+export class HumidityInfo extends Sensor {
+    type = SensorType.Humidity;
+    category = SensorCategory.Info;
+    constructor(name = 'Humidity') {
+        super(name);
+        this._writeState({ [HumidityProperty.Current]: 50 });
+    }
+    get current() {
+        return this.props.current;
+    }
+    /**
+     * Report a new humidity reading. Clamped to [0, 100] %.
+     *
+     * @param value - Relative humidity percentage in the range 0–100.
+     *
+     * @example
+     * ```ts
+     * humidity.setCurrent(63);
+     * ```
+     */
+    setCurrent(value) {
+        this._writeState({ [HumidityProperty.Current]: Math.max(0, Math.min(100, value)) });
+    }
+    /**
+     * Read-only sensor: external writes are ignored. Reading via `setCurrent` is plugin-only.
+     *
+     * Called by the cross-process plugin host when a generic property write is received.
+     * Humidity sensors have no externally writable properties, so the parameters are
+     * unused (underscore-prefixed) and the call is a no-op.
+     *
+     * @param _property - Unused — humidity sensors expose no writable properties.
+     *
+     * @param _value - Unused — humidity sensors expose no writable properties.
+     *
+     * @internal
+     */
+    updateValue(_property, _value) {
+        // No-op — humidity is reported by the plugin, not set externally.
+    }
+}

package/dist/sensor/index.js

@@ -1,19 +1,25 @@
-// Base
-export * from './base.js';
-export * from './types.js';
-export * from './guards.js';
-// Detection Sensors
 export * from './audio.js';
+export * from './base.js';
+export * from './battery.js';
+export * from './classifier.js';
+export * from './clip.js';
 export * from './contact.js';
+export * from './detection.js';
+export * from './doorbell.js';
 export * from './face.js';
+export * from './garage.js';
+export * from './humidity.js';
+export * from './leak.js';
 export * from './licensePlate.js';
+export * from './light.js';
+export * from './lock.js';
 export * from './motion.js';
 export * from './object.js';
-// Controls
-export * from './light.js';
+export * from './occupancy.js';
 export * from './ptz.js';
+export * from './securitySystem.js';
 export * from './siren.js';
-// Triggers
-export * from './doorbell.js';
-// Info
-export * from './battery.js';
+export * from './smoke.js';
+export * from './spec.js';
+export * from './switch.js';
+export * from './temperature.js';

package/dist/sensor/leak.js

@@ -0,0 +1,52 @@
+import { Sensor, SensorType, SensorCategory } from './base.js';
+/**
+ * Properties for leak sensors
+ *
+ * @internal
+ */
+export var LeakProperty;
+(function (LeakProperty) {
+    /** Whether a leak is detected */
+    LeakProperty["Detected"] = "detected";
+})(LeakProperty || (LeakProperty = {}));
+/** Water leak detector sensor */
+export class LeakSensor extends Sensor {
+    type = SensorType.Leak;
+    category = SensorCategory.Sensor;
+    constructor(name = 'Leak Sensor') {
+        super(name);
+        this._writeState({ [LeakProperty.Detected]: false });
+    }
+    get detected() {
+        return this.props.detected;
+    }
+    /**
+     * Report leak detection state.
+     *
+     * @param value - True when a leak is currently detected.
+     *
+     * @example
+     * ```ts
+     * leak.setDetected(true);
+     * ```
+     */
+    setDetected(value) {
+        this._writeState({ [LeakProperty.Detected]: value });
+    }
+    /**
+     * Read-only sensor: external writes are ignored. State is reported via `setDetected`.
+     *
+     * Called by the cross-process plugin host when a generic property write is received.
+     * Leak sensors have no externally writable properties, so the parameters are
+     * unused (underscore-prefixed) and the call is a no-op.
+     *
+     * @param _property - Unused — leak sensors expose no writable properties.
+     *
+     * @param _value - Unused — leak sensors expose no writable properties.
+     *
+     * @internal
+     */
+    updateValue(_property, _value) {
+        // No-op — leak state is reported by the plugin, not set externally.
+    }
+}

package/dist/sensor/licensePlate.js

@@ -1,116 +1,107 @@
-import { Sensor } from './base.js';
-import { SensorCategory, SensorType } from './types.js';
+import { Sensor, SensorType, SensorCategory } from './base.js';
 /**
- * License plate sensor property keys
+ * Property names of a license plate detection sensor.
+ *
+ * @internal
  */
 export var LicensePlateProperty;
 (function (LicensePlateProperty) {
+    /** Whether any license plate is currently detected. */
     LicensePlateProperty["Detected"] = "detected";
-    LicensePlateProperty["Plates"] = "plates";
+    /** List of detected plates with OCR text. */
+    LicensePlateProperty["Detections"] = "detections";
 })(LicensePlateProperty || (LicensePlateProperty = {}));
 /**
- * License Plate Sensor (Specialized)
+ * License plate sensor that reports detected plates with OCR text.
  *
- * Detects and reads license plates in camera frames.
- * Can optionally receive vehicle regions from ObjectSensor for focused detection.
+ * Plugin authors call `reportDetections(list)` to push detected plates.
+ * `detected` is auto-derived from the detection list.
  */
 export class LicensePlateSensor extends Sensor {
     type = SensorType.LicensePlate;
     category = SensorCategory.Sensor;
-    name;
     constructor(name = 'License Plate Sensor') {
-        super();
-        this.name = name;
-        // Initialize defaults
-        this.props.detected = false;
-        this.props.plates = [];
+        super(name);
+        this._writeState({
+            [LicensePlateProperty.Detected]: false,
+            [LicensePlateProperty.Detections]: [],
+        });
     }
-    /** Whether license plates are currently detected */
+    /** Whether any license plate is currently detected. */
     get detected() {
-        return this.rawProps.detected;
-    }
-    /** Set license plate detected state */
-    set detected(value) {
-        this.props.detected = value;
+        return this.props.detected;
     }
-    /** Current license plate detections */
-    get plates() {
-        return this.rawProps.plates;
-    }
-    /** Set license plate detections */
-    set plates(value) {
-        this.props.plates = value;
+    /** Current detection list. */
+    get detections() {
+        return this.props.detections;
     }
     /**
-     * Update license plate detection state
+     * Report detected license plates.
+     *
+     * - `reportDetections(true)` — plate detected without specifics. The SDK
+     *   synthesizes a single full-frame detection with empty plateText.
+     * - `reportDetections(true, [...])` — explicit plate detections with OCR text.
+     * - `reportDetections(false)` — clear.
      *
-     * @param detected - Whether license plates are detected
+     * @param detected - Whether any license plate is currently detected.
      *
-     * @param plates - Array of license plate detections
+     * @param detections - Optional explicit plate detections to publish.
+     *
+     * @example
+     * ```ts
+     * import type { LicensePlateDetection } from '@camera.ui/sdk';
+     * sensor.reportDetections(true, [
+     *   {
+     *     label: 'vehicle',
+     *     confidence: 0.93,
+     *     box: { x: 0.2, y: 0.5, width: 0.2, height: 0.08 },
+     *     attribute: 'license_plate',
+     *     plateText: 'ABC 1234',
+     *   } satisfies LicensePlateDetection,
+     * ]);
+     * sensor.reportDetections(false);
+     * ```
      */
-    setPlates(detected, plates = []) {
-        this.props.detected = detected;
-        this.props.plates = plates;
-    }
-    /** Clear license plate detection state */
-    clearPlates() {
-        this.props.detected = false;
-        this.props.plates = [];
+    reportDetections(detected, detections) {
+        const list = this._normalizeReportedDetections(detected, detections, 'vehicle', { attribute: 'license_plate', plateText: '' });
+        this._writeState({
+            [LicensePlateProperty.Detected]: detected,
+            [LicensePlateProperty.Detections]: list,
+        });
     }
     /**
-     * Get plate texts
+     * Explicitly clear license plate state (detected = false, detections = []).
      *
-     * @returns Array of detected plate texts
+     * @example
+     * ```ts
+     * sensor.clearDetections();
+     * ```
      */
-    getPlateTexts() {
-        return this.plates.map((p) => p.plateText);
+    clearDetections() {
+        this.reportDetections(false);
     }
     /**
-     * Check if specific plate 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.
+     * License plate sensors have no externally writable properties, so the parameters are
+     * unused (underscore-prefixed) and the call is a no-op.
      *
-     * @param plateText - Plate text to check
+     * @param _property - Unused — license plate sensors expose no writable properties.
      *
-     * @returns True if plate is detected, false otherwise
+     * @param _value - Unused — license plate sensors expose no writable properties.
+     *
+     * @internal
      */
-    hasPlate(plateText) {
-        return this.plates.some((p) => p.plateText === plateText);
+    updateValue(_property, _value) {
+        // No-op — license plate state is reported by the plugin, not set externally.
     }
 }
 /**
- * License Plate Detector Sensor (Active Detection)
- *
- * Use this class for frame-based license plate detection (OpenALPR, etc.)
- * The `inputProperties` getter specifies the required input format.
- *
- * Receives cropped vehicle regions from ObjectDetectorSensor for efficient processing.
- *
- * @example
- * ```typescript
- * class OpenALPRDetector extends LicensePlateDetectorSensor {
- *   get inputProperties(): VideoInputProperties {
- *     return { width: 320, height: 160, format: 'rgb' };
- *   }
- *
- *   async detectLicensePlates(frame: VideoFrameData, vehicleRegions?: Detection[]): Promise<LicensePlateResult> {
- *     const plates = await this.alpr.recognize(frame.data);
- *     return {
- *       detected: plates.length > 0,
- *       plates: plates.map(p => ({
- *         label: 'license_plate',
- *         confidence: p.confidence,
- *         box: p.box,
- *         plateText: p.text,
- *         plateConfidence: p.textConfidence,
- *       })),
- *     };
- *   }
- * }
- * ```
+ * License plate detector that receives video frames from the backend pipeline.
+ * Extend this class and implement {@link detectLicensePlates} for plate
+ * detection and OCR.
  */
 export class LicensePlateDetectorSensor extends LicensePlateSensor {
-    /**
-     * Indicates this sensor requires video frames for detection.
-     * Used by the backend to determine streaming requirements.
-     */
     _requiresFrames = true;
 }