@camera.ui/sdk 0.0.2 → 0.0.4

package/dist/sensor/battery.js

@@ -1,101 +1,115 @@
-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)
- */
+import { Sensor, SensorType, SensorCategory } from './base.js';
+/** Optional capabilities for battery info sensors */
 export var BatteryCapability;
 (function (BatteryCapability) {
-    /** Supports low battery detection */
+    /** Sensor reports low-battery alerts */
     BatteryCapability["LowBattery"] = "lowBattery";
-    /** Supports charging state detection */
+    /** Sensor reports charging state */
     BatteryCapability["Charging"] = "charging";
 })(BatteryCapability || (BatteryCapability = {}));
 /**
- * Battery info property keys
+ * Properties for battery info sensors
+ *
+ * @internal
  */
 export var BatteryProperty;
 (function (BatteryProperty) {
+    /** Battery level percentage (0–100) */
     BatteryProperty["Level"] = "level";
+    /** Current charging state */
     BatteryProperty["Charging"] = "charging";
+    /** Whether battery is critically low */
     BatteryProperty["Low"] = "low";
 })(BatteryProperty || (BatteryProperty = {}));
+/** Battery charging state */
+export var ChargingState;
+(function (ChargingState) {
+    ChargingState["NotChargeable"] = "NOT_CHARGEABLE";
+    ChargingState["NotCharging"] = "NOT_CHARGING";
+    ChargingState["Charging"] = "CHARGING";
+    ChargingState["Full"] = "FULL";
+})(ChargingState || (ChargingState = {}));
 /**
- * Battery Info
+ * Battery info sensor. Reports battery level, charging state, and low-battery alerts.
  *
- * Read-only hardware status for battery-powered cameras.
+ * Plugin authors call `setLevel(value)`, `setCharging(state)`, and `setLow(value)`
+ * to push updates from the device.
  */
+// prettier-ignore
 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;
+        super(name);
+        this._writeState({
+            [BatteryProperty.Level]: 100,
+            [BatteryProperty.Charging]: ChargingState.NotCharging,
+            [BatteryProperty.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;
+        return this.props.level;
     }
-    /** Charging state */
     get charging() {
-        return this.rawProps.charging;
+        return this.props.charging;
     }
-    /** Set charging state */
-    set charging(value) {
-        this.props.charging = value;
-    }
-    /** Whether battery is low */
     get low() {
-        return this.rawProps.low;
+        return this.props.low;
     }
-    /** Set low battery state */
-    set low(value) {
-        this.props.low = value;
+    /**
+     * Report a new battery level (percentage). Clamped to [0, 100].
+     *
+     * @param value - Battery level percentage in the range 0–100.
+     *
+     * @example
+     * ```ts
+     * battery.setLevel(87);
+     * ```
+     */
+    setLevel(value) {
+        this._writeState({ [BatteryProperty.Level]: Math.max(0, Math.min(100, value)) });
     }
-    // ========== Convenience Methods ==========
     /**
-     * Update battery state
+     * Report the current charging state.
      *
-     * @param level - Battery level (0-100)
+     * @param value - Current charging state from the {@link ChargingState} enum.
      *
-     * @param charging - Charging state
+     * @example
+     * ```ts
+     * import { ChargingState } from '@camera.ui/sdk';
+     * battery.setCharging(ChargingState.Charging);
+     * ```
      */
-    setBattery(level, charging) {
-        this.level = level;
-        if (charging !== undefined) {
-            this.props.charging = charging;
-        }
+    setCharging(value) {
+        this._writeState({ [BatteryProperty.Charging]: value });
     }
     /**
-     * Check if battery is charging
+     * Report whether the battery is critically low.
+     *
+     * @param value - True when the battery has crossed the low-battery threshold.
      *
-     * @returns True if battery is charging, false otherwise
+     * @example
+     * ```ts
+     * battery.setLow(true);
+     * ```
      */
-    isCharging() {
-        return this.charging === ChargingState.Charging;
+    setLow(value) {
+        this._writeState({ [BatteryProperty.Low]: value });
     }
     /**
-     * Check if battery is fully charged
+     * Read-only sensor: external writes are ignored. State is reported via `setLevel`/`setCharging`/`setLow`.
+     *
+     * Called by the cross-process plugin host when a generic property write is received.
+     * Battery sensors have no externally writable properties, so the parameters are
+     * unused (underscore-prefixed) and the call is a no-op.
+     *
+     * @param _property - Unused — battery sensors expose no writable properties.
+     *
+     * @param _value - Unused — battery sensors expose no writable properties.
      *
-     * @returns True if battery is fully charged, false otherwise
+     * @internal
      */
-    isFullyCharged() {
-        return this.charging === ChargingState.Full || this.level === 100;
+    updateValue(_property, _value) {
+        // No-op — battery state is reported by the plugin, not set externally.
     }
 }

package/dist/sensor/classifier.js

@@ -0,0 +1,117 @@
+import { Sensor, SensorType, SensorCategory } from './base.js';
+/**
+ * Property names of a classifier sensor.
+ *
+ * @internal
+ */
+export var ClassifierProperty;
+(function (ClassifierProperty) {
+    /** Whether any classification result is active. */
+    ClassifierProperty["Detected"] = "detected";
+    /** List of classification results with labels and confidence. */
+    ClassifierProperty["Detections"] = "detections";
+    /** Unique labels of the current detections (auto-derived when reporting detections). */
+    ClassifierProperty["Labels"] = "labels";
+})(ClassifierProperty || (ClassifierProperty = {}));
+/**
+ * General-purpose image classifier sensor.
+ *
+ * Plugin authors call `reportDetections(list)` to push classification results.
+ * `detected` and `labels` are auto-derived from the detection list.
+ */
+export class ClassifierSensor extends Sensor {
+    type = SensorType.Classifier;
+    category = SensorCategory.Sensor;
+    _requiresFrames = false;
+    constructor(name = 'Classifier') {
+        super(name);
+        this._writeState({
+            [ClassifierProperty.Detected]: false,
+            [ClassifierProperty.Detections]: [],
+            [ClassifierProperty.Labels]: [],
+        });
+    }
+    /** Whether any classification result is active. */
+    get detected() {
+        return this.props.detected;
+    }
+    /** Current detection list. */
+    get detections() {
+        return this.props.detections;
+    }
+    /** Unique labels of the current detections. */
+    get labels() {
+        return this.props.labels;
+    }
+    /**
+     * Report classification results. Auto-derives `detected` and `labels` from the list.
+     *
+     * - `reportDetections(true)` — generic classification trigger. The SDK
+     *   synthesizes a single full-frame detection with empty attribute/subAttribute.
+     * - `reportDetections(true, [...])` — explicit classifier detections.
+     * - `reportDetections(false)` — clear.
+     *
+     * @param detected - Whether any classification result is active.
+     *
+     * @param detections - Optional explicit classifier detections to publish.
+     *
+     * @example
+     * ```ts
+     * import type { ClassifierDetection } from '@camera.ui/sdk';
+     * sensor.reportDetections(true, [
+     *   {
+     *     label: 'animal',
+     *     confidence: 0.88,
+     *     box: { x: 0.1, y: 0.2, width: 0.3, height: 0.4 },
+     *     attribute: 'bird',
+     *     subAttribute: 'woodpecker',
+     *   } satisfies ClassifierDetection,
+     * ]);
+     * sensor.reportDetections(false);
+     * ```
+     */
+    reportDetections(detected, detections) {
+        const list = this._normalizeReportedDetections(detected, detections, 'motion', { attribute: '', subAttribute: '' });
+        const labels = Array.from(new Set(list.map((d) => d.label)));
+        this._writeState({
+            [ClassifierProperty.Detected]: detected,
+            [ClassifierProperty.Detections]: list,
+            [ClassifierProperty.Labels]: labels,
+        });
+    }
+    /**
+     * Explicitly clear classifier state (detected = false, detections = [], labels = []).
+     *
+     * @example
+     * ```ts
+     * sensor.clearDetections();
+     * ```
+     */
+    clearDetections() {
+        this.reportDetections(false);
+    }
+    /**
+     * 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.
+     * Classifier sensors have no externally writable properties, so the parameters are
+     * unused (underscore-prefixed) and the call is a no-op.
+     *
+     * @param _property - Unused — classifier sensors expose no writable properties.
+     *
+     * @param _value - Unused — classifier sensors expose no writable properties.
+     *
+     * @internal
+     */
+    updateValue(_property, _value) {
+        // No-op — classifier state is reported by the plugin, not set externally.
+    }
+}
+/**
+ * Classifier detector that receives video frames from the backend pipeline.
+ * Extend this class and implement {@link detectClassifications} to run image
+ * classification models against trigger regions.
+ */
+export class ClassifierDetectorSensor extends ClassifierSensor {
+    _requiresFrames = true;
+}

package/dist/sensor/clip.js

@@ -0,0 +1,30 @@
+import { Sensor, SensorType, SensorCategory } from './base.js';
+/**
+ * CLIP detector sensor that receives video frames and generates semantic
+ * embeddings. Extend this class and implement {@link detectEmbeddings} to
+ * produce CLIP embeddings for downstream semantic search.
+ */
+export class ClipDetectorSensor extends Sensor {
+    type = SensorType.Clip;
+    category = SensorCategory.Sensor;
+    _requiresFrames = true;
+    constructor(name = 'CLIP Sensor') {
+        super(name);
+    }
+    /**
+     * Frame-only sensor: no externally writable properties.
+     *
+     * Called by the cross-process plugin host when a generic property write is received.
+     * CLIP detectors have no writable properties, so the parameters are unused
+     * (underscore-prefixed) and the call is a no-op.
+     *
+     * @param _property - Unused — CLIP detectors expose no writable properties.
+     *
+     * @param _value - Unused — CLIP detectors expose no writable properties.
+     *
+     * @internal
+     */
+    updateValue(_property, _value) {
+        // No-op — clip detector has no state.
+    }
+}

package/dist/sensor/contact.js

@@ -1,33 +1,52 @@
-import { Sensor } from './base.js';
-import { SensorCategory, SensorType } from './types.js';
+import { Sensor, SensorType, SensorCategory } from './base.js';
 /**
- * Contact sensor property keys
+ * Properties for contact sensors
+ *
+ * @internal
  */
 export var ContactProperty;
 (function (ContactProperty) {
+    /** Whether the contact is open (true = open, false = closed) */
     ContactProperty["Detected"] = "detected";
 })(ContactProperty || (ContactProperty = {}));
-/**
- * Contact Sensor
- *
- * Detects contact state (open/closed) for doors, windows, etc.
- */
+/** Contact sensor for door/window open-close state */
 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;
+        super(name);
+        this._writeState({ [ContactProperty.Detected]: false });
     }
-    /** Whether contact is detected (closed) */
     get detected() {
-        return this.rawProps.detected;
+        return this.props.detected;
+    }
+    /**
+     * Report contact state (true = open, false = closed).
+     *
+     * @param value - True when the contact is open, false when closed.
+     *
+     * @example
+     * ```ts
+     * contact.setDetected(true);
+     * ```
+     */
+    setDetected(value) {
+        this._writeState({ [ContactProperty.Detected]: value });
     }
-    /** Set contact detected state */
-    set detected(value) {
-        this.props.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.
+     * Contact sensors have no externally writable properties, so the parameters are
+     * unused (underscore-prefixed) and the call is a no-op.
+     *
+     * @param _property - Unused — contact sensors expose no writable properties.
+     *
+     * @param _value - Unused — contact sensors expose no writable properties.
+     *
+     * @internal
+     */
+    updateValue(_property, _value) {
+        // No-op — contact state is reported by the plugin, not set externally.
     }
 }

package/dist/sensor/detection.js

@@ -0,0 +1,4 @@
+/** Built-in detection label types recognized across the system. */
+export const DETECTION_LABELS = ['motion', 'person', 'vehicle', 'animal', 'package', 'audio'];
+/** Detection attribute types used to mark sub-detections (face, license plate, ...). */
+export const DETECTION_ATTRIBUTES = ['face', 'license_plate'];

package/dist/sensor/doorbell.js

@@ -1,63 +1,77 @@
-import { Sensor } from './base.js';
-import { SensorCategory, SensorType } from './types.js';
+import { Sensor, SensorType, SensorCategory } from './base.js';
 /**
- * Doorbell trigger property keys
+ * Properties for doorbell triggers
+ *
+ * @internal
  */
 export var DoorbellProperty;
 (function (DoorbellProperty) {
+    /** Whether the doorbell is currently ringing */
     DoorbellProperty["Ring"] = "ring";
 })(DoorbellProperty || (DoorbellProperty = {}));
+/** Auto-reset duration after `trigger()` is called (ms). */
+export const RING_AUTO_RESET_MS = 2000;
 /**
- * Doorbell Trigger
+ * Doorbell trigger sensor.
  *
- * Event-based trigger for doorbell rings.
- * Ring property auto-resets after a short delay.
+ * Plugin authors call `trigger()` to fire a doorbell event. The `ring` property
+ * is set to true and automatically reset to false after a short delay
+ * ({@link RING_AUTO_RESET_MS}). Calling `trigger()` again while still ringing
+ * resets the timer (extends the ring phase).
  */
 export class DoorbellTrigger extends Sensor {
     type = SensorType.Doorbell;
     category = SensorCategory.Trigger;
-    name;
-    _resetTimeout;
+    _ringResetTimer;
     constructor(name = 'Doorbell') {
-        super();
-        this.name = name;
-        // Initialize defaults
-        this.props.ring = false;
+        super(name);
+        this._writeState({ [DoorbellProperty.Ring]: false });
     }
-    // ========== Properties (Getter/Setter Pairs) ==========
-    /** Whether doorbell is currently ringing */
     get ring() {
-        return this.rawProps.ring;
+        return this.props.ring;
     }
-    /** Set ring state */
-    set ring(value) {
-        this.props.ring = value;
+    /**
+     * Trigger a doorbell ring. Sets `ring = true` and auto-resets after a
+     * short delay. Re-triggering while still ringing extends the ring phase.
+     *
+     * @example
+     * ```ts
+     * doorbell.trigger();
+     * ```
+     */
+    trigger() {
+        if (this._ringResetTimer) {
+            clearTimeout(this._ringResetTimer);
+        }
+        this._writeState({ [DoorbellProperty.Ring]: true });
+        this._ringResetTimer = setTimeout(() => {
+            this._ringResetTimer = undefined;
+            this._writeState({ [DoorbellProperty.Ring]: false });
+        }, RING_AUTO_RESET_MS);
     }
-    // ========== Convenience Methods ==========
     /**
-     * Trigger doorbell ring
-     * Auto-resets after duration (default: 1000ms)
+     * Cross-process consumer entry point. Writing `ring=true` (any truthy value)
+     * dispatches to `trigger()` so a UI test button or external automation can
+     * fire the doorbell using the same flow as a real hardware ring (auto-reset
+     * included). Writing `ring=false` is ignored — the auto-reset timer owns
+     * the off transition.
+     *
+     * @param property - Property name to write.
+     *
+     * @param value - New value for the property.
      *
-     * @param resetAfterMs - Duration in milliseconds to auto-reset ring state
+     * @internal
      */
-    triggerRing(resetAfterMs = 1000) {
-        // Clear any existing reset timeout
-        if (this._resetTimeout) {
-            clearTimeout(this._resetTimeout);
+    updateValue(property, value) {
+        if (property === DoorbellProperty.Ring && value) {
+            this.trigger();
         }
-        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;
+    _cleanup() {
+        if (this._ringResetTimer) {
+            clearTimeout(this._ringResetTimer);
+            this._ringResetTimer = undefined;
         }
-        this.props.ring = false;
+        super._cleanup();
     }
 }