@camstack/addon-pipeline-analytics 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,190 @@
+import * as _camstack_types from '@camstack/types';
+import { TrackState, ObjectEvent, TrackedDetection, BaseAddon, IPipelineAnalyticsProvider, ProviderRegistration, Track, MotionEvent, AudioEvent, MediaFile, ConfigUISchemaWithValues } from '@camstack/types';
+
+/**
+ * FrameProcessor — per-device pipeline stage runner.
+ *
+ * Consumes a raw `PipelineInferenceResult` payload and runs:
+ *   1. Flatten first-level detections
+ *   2. Zone filter (ZoneEngine)
+ *   3. Tracking (SortTracker)
+ *   4. State analysis (StateAnalyzer)
+ *   5. Event emission (DetectionEventEmitter)
+ *
+ * Returns a structured result the addon uses to:
+ *   - upsert TrackStore
+ *   - insert ObjectEvent rows into the declared collection
+ *   - emit onFrameTracked / onDetectionEvent on the bus
+ *
+ * One FrameProcessor per device — lifecycle managed by DeviceRegistry.
+ */
+
+interface TrackedDetectionOut {
+    readonly trackId: string;
+    readonly className: string;
+    readonly confidence: number;
+    readonly bbox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    readonly zones: readonly string[];
+    readonly state: TrackState;
+}
+interface FrameProcessorResult {
+    readonly deviceId: number;
+    readonly timestamp: number;
+    readonly frameWidth: number;
+    readonly frameHeight: number;
+    readonly tracked: readonly TrackedDetectionOut[];
+    readonly objectEvents: readonly ObjectEvent[];
+    /** Raw TrackedDetection array — consumed by TrackStore for position
+     *  history updates. Kept separate from `tracked` which is the
+     *  lightweight shape consumed by the bus emit. */
+    readonly rawTrackedDetections: readonly TrackedDetection[];
+}
+
+declare class PipelineAnalyticsAddon extends BaseAddon implements IPipelineAnalyticsProvider {
+    private processors;
+    private trackStore;
+    private mediaStore;
+    private eventStore;
+    private bindingCache;
+    private zoneAnalytics;
+    private audioMetrics;
+    /**
+     * Per-device {@link DeviceProxy} used to read live zones +
+     * detection rules off the kernel runtime-state mirror. Replaces
+     * the manual DeviceStateChanged subscription + per-cap-name caches
+     * — `proxy.state.zones.value` and `proxy.state.zoneRules.value`
+     * stay warm as long as the slice handles are subscribed.
+     */
+    private readonly proxies;
+    /** Slice subscription pins for cache warmth + pushed updates into
+     *  the per-device FrameProcessor. */
+    private readonly proxyUnsubs;
+    private unsubInference;
+    private unsubAudio;
+    private unsubMotion;
+    private unsubMotionOnboard;
+    private unsubBindings;
+    private unsubDeviceUnreg;
+    private ttlSweepTimer;
+    private retentionSweepTimer;
+    private readonly lastActiveTrackIds;
+    private readonly lastAudioInsertByDevice;
+    private readonly lastMotionInsertByDevice;
+    private shuttingDown;
+    constructor();
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
+    private handleInferenceResult;
+    private handleAudioResult;
+    /**
+     * Persist motion-analysis bus events. Mirrors `handleAudioResult`'s
+     * coalescing strategy: emit one row on off→on transition, then one
+     * per `MOTION_EVENT_HEARTBEAT_MS` while motion stays detected. No
+     * row on off→off (silence) or while heartbeat hasn't elapsed.
+     *
+     * Gated on the same `pipeline-analytics` wrapper binding as the
+     * inference + audio handlers so toggling the wrapper off for a
+     * camera stops every kind of event persistence at once.
+     */
+    private handleMotionAnalysis;
+    /**
+     * Persist firmware-driven (onboard) motion events. Mirrors
+     * {@link handleMotionAnalysis}'s coalescing — one row on off→on
+     * transition, then one per `MOTION_EVENT_HEARTBEAT_MS` while motion
+     * stays detected — but reads from the {@link MotionOnMotionChangedPayload}
+     * shape which lacks frame dimensions and pixel-level region details
+     * (firmware reports a binary detected flag plus, on rare devices, a
+     * coarse bbox via the optional `regions` field).
+     *
+     * The same `lastMotionInsertByDevice` map is shared with the analyzer
+     * path so a camera that briefly switches `motionSources` between
+     * `onboard` and `analyzer` gets consistent throttling — both paths
+     * are mutually exclusive at the event-emit layer (the runner only
+     * fires `MotionAnalysis` when its analyzer runs; onboard providers
+     * never fire `MotionAnalysis`), so there's no double-count risk.
+     */
+    private handleOnboardMotion;
+    private sweepExpiredTracks;
+    private sweepRetention;
+    private getOrCreateProcessor;
+    /**
+     * Resolve and cache a {@link DeviceProxy} for a device. Pins the
+     * `state.zones` + `state.zoneRules` slice handles so `.value` stays
+     * warm via the kernel runtime-state mirror. Slice subscribers also
+     * forward updates to the per-device FrameProcessor so a rule change
+     * applies to the very next frame even when frames stop briefly
+     * (e.g. during binding flips).
+     */
+    private ensureProxy;
+    private releaseProxy;
+    getActiveTracks(input: {
+        deviceId: number;
+    }): Promise<readonly Track[]>;
+    getTrack(input: {
+        deviceId: number;
+        trackId: string;
+    }): Promise<Track | null>;
+    listTracks(input: {
+        deviceId: number;
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): Promise<readonly Track[]>;
+    clearTracks(input: {
+        deviceId: number;
+    }): Promise<void>;
+    getMotionEvents(input: {
+        deviceId: number;
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): Promise<readonly MotionEvent[]>;
+    getObjectEvents(input: {
+        deviceId: number;
+        since?: number;
+        until?: number;
+        classFilter?: string;
+        limit?: number;
+    }): Promise<readonly ObjectEvent[]>;
+    getAudioEvents(input: {
+        deviceId: number;
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): Promise<readonly AudioEvent[]>;
+    getEventMedia(input: {
+        eventId: string;
+    }): Promise<readonly MediaFile[]>;
+    getTrackMedia(input: {
+        trackId: string;
+    }): Promise<readonly MediaFile[]>;
+    protected globalSettingsSchema(): _camstack_types.ConfigUISchema;
+    getDeviceSettingsContribution(input: {
+        deviceId: number;
+    }): Promise<ConfigUISchemaWithValues | null>;
+    getDeviceLiveContribution(_input: {
+        deviceId: number;
+    }): Promise<ConfigUISchemaWithValues | null>;
+    applyDeviceSettingsPatch(input: {
+        deviceId: number;
+        patch: Record<string, unknown>;
+    }): Promise<{
+        success: true;
+    }>;
+    /**
+     * Best-effort camera-type check. Used to short-circuit the settings
+     * contribution on non-camera devices. Returns `true` on lookup
+     * failure so a transient device-manager hiccup never silently hides
+     * legitimate camera sections.
+     */
+    private isCameraDevice;
+}
+
+type _TrackedDetectionBridge = TrackedDetection;
+
+export { type FrameProcessorResult, type TrackedDetectionOut, type _TrackedDetectionBridge, PipelineAnalyticsAddon as default };

package/dist/index.d.ts

@@ -0,0 +1,190 @@
+import * as _camstack_types from '@camstack/types';
+import { TrackState, ObjectEvent, TrackedDetection, BaseAddon, IPipelineAnalyticsProvider, ProviderRegistration, Track, MotionEvent, AudioEvent, MediaFile, ConfigUISchemaWithValues } from '@camstack/types';
+
+/**
+ * FrameProcessor — per-device pipeline stage runner.
+ *
+ * Consumes a raw `PipelineInferenceResult` payload and runs:
+ *   1. Flatten first-level detections
+ *   2. Zone filter (ZoneEngine)
+ *   3. Tracking (SortTracker)
+ *   4. State analysis (StateAnalyzer)
+ *   5. Event emission (DetectionEventEmitter)
+ *
+ * Returns a structured result the addon uses to:
+ *   - upsert TrackStore
+ *   - insert ObjectEvent rows into the declared collection
+ *   - emit onFrameTracked / onDetectionEvent on the bus
+ *
+ * One FrameProcessor per device — lifecycle managed by DeviceRegistry.
+ */
+
+interface TrackedDetectionOut {
+    readonly trackId: string;
+    readonly className: string;
+    readonly confidence: number;
+    readonly bbox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    readonly zones: readonly string[];
+    readonly state: TrackState;
+}
+interface FrameProcessorResult {
+    readonly deviceId: number;
+    readonly timestamp: number;
+    readonly frameWidth: number;
+    readonly frameHeight: number;
+    readonly tracked: readonly TrackedDetectionOut[];
+    readonly objectEvents: readonly ObjectEvent[];
+    /** Raw TrackedDetection array — consumed by TrackStore for position
+     *  history updates. Kept separate from `tracked` which is the
+     *  lightweight shape consumed by the bus emit. */
+    readonly rawTrackedDetections: readonly TrackedDetection[];
+}
+
+declare class PipelineAnalyticsAddon extends BaseAddon implements IPipelineAnalyticsProvider {
+    private processors;
+    private trackStore;
+    private mediaStore;
+    private eventStore;
+    private bindingCache;
+    private zoneAnalytics;
+    private audioMetrics;
+    /**
+     * Per-device {@link DeviceProxy} used to read live zones +
+     * detection rules off the kernel runtime-state mirror. Replaces
+     * the manual DeviceStateChanged subscription + per-cap-name caches
+     * — `proxy.state.zones.value` and `proxy.state.zoneRules.value`
+     * stay warm as long as the slice handles are subscribed.
+     */
+    private readonly proxies;
+    /** Slice subscription pins for cache warmth + pushed updates into
+     *  the per-device FrameProcessor. */
+    private readonly proxyUnsubs;
+    private unsubInference;
+    private unsubAudio;
+    private unsubMotion;
+    private unsubMotionOnboard;
+    private unsubBindings;
+    private unsubDeviceUnreg;
+    private ttlSweepTimer;
+    private retentionSweepTimer;
+    private readonly lastActiveTrackIds;
+    private readonly lastAudioInsertByDevice;
+    private readonly lastMotionInsertByDevice;
+    private shuttingDown;
+    constructor();
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
+    private handleInferenceResult;
+    private handleAudioResult;
+    /**
+     * Persist motion-analysis bus events. Mirrors `handleAudioResult`'s
+     * coalescing strategy: emit one row on off→on transition, then one
+     * per `MOTION_EVENT_HEARTBEAT_MS` while motion stays detected. No
+     * row on off→off (silence) or while heartbeat hasn't elapsed.
+     *
+     * Gated on the same `pipeline-analytics` wrapper binding as the
+     * inference + audio handlers so toggling the wrapper off for a
+     * camera stops every kind of event persistence at once.
+     */
+    private handleMotionAnalysis;
+    /**
+     * Persist firmware-driven (onboard) motion events. Mirrors
+     * {@link handleMotionAnalysis}'s coalescing — one row on off→on
+     * transition, then one per `MOTION_EVENT_HEARTBEAT_MS` while motion
+     * stays detected — but reads from the {@link MotionOnMotionChangedPayload}
+     * shape which lacks frame dimensions and pixel-level region details
+     * (firmware reports a binary detected flag plus, on rare devices, a
+     * coarse bbox via the optional `regions` field).
+     *
+     * The same `lastMotionInsertByDevice` map is shared with the analyzer
+     * path so a camera that briefly switches `motionSources` between
+     * `onboard` and `analyzer` gets consistent throttling — both paths
+     * are mutually exclusive at the event-emit layer (the runner only
+     * fires `MotionAnalysis` when its analyzer runs; onboard providers
+     * never fire `MotionAnalysis`), so there's no double-count risk.
+     */
+    private handleOnboardMotion;
+    private sweepExpiredTracks;
+    private sweepRetention;
+    private getOrCreateProcessor;
+    /**
+     * Resolve and cache a {@link DeviceProxy} for a device. Pins the
+     * `state.zones` + `state.zoneRules` slice handles so `.value` stays
+     * warm via the kernel runtime-state mirror. Slice subscribers also
+     * forward updates to the per-device FrameProcessor so a rule change
+     * applies to the very next frame even when frames stop briefly
+     * (e.g. during binding flips).
+     */
+    private ensureProxy;
+    private releaseProxy;
+    getActiveTracks(input: {
+        deviceId: number;
+    }): Promise<readonly Track[]>;
+    getTrack(input: {
+        deviceId: number;
+        trackId: string;
+    }): Promise<Track | null>;
+    listTracks(input: {
+        deviceId: number;
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): Promise<readonly Track[]>;
+    clearTracks(input: {
+        deviceId: number;
+    }): Promise<void>;
+    getMotionEvents(input: {
+        deviceId: number;
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): Promise<readonly MotionEvent[]>;
+    getObjectEvents(input: {
+        deviceId: number;
+        since?: number;
+        until?: number;
+        classFilter?: string;
+        limit?: number;
+    }): Promise<readonly ObjectEvent[]>;
+    getAudioEvents(input: {
+        deviceId: number;
+        since?: number;
+        until?: number;
+        limit?: number;
+    }): Promise<readonly AudioEvent[]>;
+    getEventMedia(input: {
+        eventId: string;
+    }): Promise<readonly MediaFile[]>;
+    getTrackMedia(input: {
+        trackId: string;
+    }): Promise<readonly MediaFile[]>;
+    protected globalSettingsSchema(): _camstack_types.ConfigUISchema;
+    getDeviceSettingsContribution(input: {
+        deviceId: number;
+    }): Promise<ConfigUISchemaWithValues | null>;
+    getDeviceLiveContribution(_input: {
+        deviceId: number;
+    }): Promise<ConfigUISchemaWithValues | null>;
+    applyDeviceSettingsPatch(input: {
+        deviceId: number;
+        patch: Record<string, unknown>;
+    }): Promise<{
+        success: true;
+    }>;
+    /**
+     * Best-effort camera-type check. Used to short-circuit the settings
+     * contribution on non-camera devices. Returns `true` on lookup
+     * failure so a transient device-manager hiccup never silently hides
+     * legitimate camera sections.
+     */
+    private isCameraDevice;
+}
+
+type _TrackedDetectionBridge = TrackedDetection;
+
+export { type FrameProcessorResult, type TrackedDetectionOut, type _TrackedDetectionBridge, PipelineAnalyticsAddon as default };