@camera.ui/sdk 0.0.3 → 0.0.4

package/dist/internal/index.d.ts

@@ -0,0 +1,915 @@
+import type { Disposable } from '@camera.ui/sdk';
+/**
+ * Subscription handle returned by `subscribe()`.
+ *
+ * Call `dispose()` (or its alias `unsubscribe()`) to detach the listener
+ * and run any teardown logic registered by the producer. Disposing twice
+ * is a no-op.
+ */
+
+/** Built-in detection label types recognized across the system. */
+declare const DETECTION_LABELS: readonly ["motion", "person", "vehicle", "animal", "package", "audio"];
+/** Union of the built-in detection label strings. */
+type DetectionLabel = (typeof DETECTION_LABELS)[number];
+/**
+ * Bounding box of a detection. All coordinates are normalized to 0–1
+ * (fraction of frame dimensions), so they are independent of resolution.
+ */
+interface BoundingBox {
+    /** X coordinate of the top-left corner (0–1). */
+    x: number;
+    /** Y coordinate of the top-left corner (0–1). */
+    y: number;
+    /** Width as a fraction of frame width (0–1). */
+    width: number;
+    /** Height as a fraction of frame height (0–1). */
+    height: number;
+}
+
+/** Expected video input dimensions and pixel format for a detector model. */
+interface VideoInputSpec {
+    /** Expected frame width in pixels. */
+    width: number;
+    /** Expected frame height in pixels. */
+    height: number;
+    /** Pixel format: `'rgb'` = 3 bytes/pixel, `'gray'` = 1 byte/pixel, `'nv12'` = YUV semi-planar. */
+    format: 'rgb' | 'nv12' | 'gray';
+}
+/**
+ * Model spec for detectors with fixed output labels (face, classifier, license plate).
+ * Declares the input shape the backend should produce and the trigger labels
+ * that should activate this detector.
+ */
+interface ModelSpec {
+    /** Required input frame dimensions and pixel format. */
+    input: VideoInputSpec;
+    /** Labels emitted by an upstream object detector that activate this detector (e.g. `['person']` for face detection). */
+    triggerLabels: DetectionLabel[];
+    /** Embedding model identifier for face recognition. */
+    embeddingModel?: string;
+}
+
+/**
+ * Property names of an audio detection sensor.
+ *
+ * @internal
+ */
+declare enum AudioProperty {
+    /** Whether an audio event is currently detected. */
+    Detected = "detected",
+    /** List of detected audio events (e.g. glass break, scream). */
+    Detections = "detections",
+    /** Current audio level in decibels. */
+    Decibels = "decibels",
+    /** Timestamp in milliseconds of the last detection trigger, set by the backend. */
+    LastTriggered = "lastTriggered"
+}
+
+/**
+ * Properties for battery info sensors
+ *
+ * @internal
+ */
+declare enum BatteryProperty {
+    /** Battery level percentage (0–100) */
+    Level = "level",
+    /** Current charging state */
+    Charging = "charging",
+    /** Whether battery is critically low */
+    Low = "low"
+}
+
+/**
+ * Properties for contact sensors
+ *
+ * @internal
+ */
+declare enum ContactProperty {
+    /** Whether the contact is open (true = open, false = closed) */
+    Detected = "detected"
+}
+
+/**
+ * Properties for doorbell triggers
+ *
+ * @internal
+ */
+declare enum DoorbellProperty {
+    /** Whether the doorbell is currently ringing */
+    Ring = "ring"
+}
+
+/**
+ * Property names of a face detection sensor.
+ *
+ * @internal
+ */
+declare enum FaceProperty {
+    /** Whether any face is currently detected. */
+    Detected = "detected",
+    /** List of detected faces with optional identity, embedding, and thumbnail. */
+    Detections = "detections"
+}
+
+/**
+ * Properties for garage controls
+ *
+ * @internal
+ */
+declare enum GarageProperty {
+    /** The actual current state of the garage door */
+    CurrentState = "currentState",
+    /** The desired target state (set by user, transitions to currentState) */
+    TargetState = "targetState",
+    /** Whether an obstruction is detected */
+    ObstructionDetected = "obstructionDetected"
+}
+
+/**
+ * Properties for humidity sensors
+ *
+ * @internal
+ */
+declare enum HumidityProperty {
+    /** Current relative humidity (0–100%) */
+    Current = "current"
+}
+
+/**
+ * Properties for leak sensors
+ *
+ * @internal
+ */
+declare enum LeakProperty {
+    /** Whether a leak is detected */
+    Detected = "detected"
+}
+
+/**
+ * Property names of a license plate detection sensor.
+ *
+ * @internal
+ */
+declare enum LicensePlateProperty {
+    /** Whether any license plate is currently detected. */
+    Detected = "detected",
+    /** List of detected plates with OCR text. */
+    Detections = "detections"
+}
+
+/**
+ * Properties for light controls
+ *
+ * @internal
+ */
+declare enum LightProperty {
+    /** Whether the light is on */
+    On = "on",
+    /** Brightness level (0–100) */
+    Brightness = "brightness"
+}
+
+/**
+ * Properties for lock controls
+ *
+ * @internal
+ */
+declare enum LockProperty {
+    /** The actual current state of the lock */
+    CurrentState = "currentState",
+    /** The desired target state (set by user, transitions to currentState) */
+    TargetState = "targetState"
+}
+
+/**
+ * Property names of a motion sensor.
+ *
+ * @internal
+ */
+declare enum MotionProperty {
+    /** Whether motion is currently detected. */
+    Detected = "detected",
+    /** List of detection results with bounding boxes. */
+    Detections = "detections",
+    /** When true, detection updates are suppressed (set by the backend dwell logic). */
+    Blocked = "blocked",
+    /** Timestamp in milliseconds of the last detection trigger, set by the backend. */
+    LastTriggered = "lastTriggered"
+}
+
+/**
+ * Property names of an object detection sensor.
+ *
+ * @internal
+ */
+declare enum ObjectProperty {
+    /** Whether any object is currently detected. */
+    Detected = "detected",
+    /** List of detected objects with labels and bounding boxes. */
+    Detections = "detections",
+    /** Unique labels of the current detections (auto-derived when reporting detections). */
+    Labels = "labels"
+}
+
+/**
+ * Properties for occupancy sensors
+ *
+ * @internal
+ */
+declare enum OccupancyProperty {
+    /** Whether occupancy is detected (true = occupied) */
+    Detected = "detected"
+}
+
+/**
+ * Properties for PTZ controls
+ *
+ * @internal
+ */
+declare enum PTZProperty {
+    /** Current pan/tilt/zoom position */
+    Position = "position",
+    /** Whether the camera is currently moving */
+    Moving = "moving",
+    /** List of available preset names */
+    Presets = "presets",
+    /** Current movement velocity (continuous move) */
+    Velocity = "velocity",
+    /** Target preset to move to */
+    TargetPreset = "targetPreset"
+}
+
+/**
+ * Properties for security system controls
+ *
+ * @internal
+ */
+declare enum SecuritySystemProperty {
+    /** The actual current state of the security system */
+    CurrentState = "currentState",
+    /** The desired target state (set by user, transitions to currentState) */
+    TargetState = "targetState"
+}
+
+/**
+ * Properties for siren controls
+ *
+ * @internal
+ */
+declare enum SirenProperty {
+    /** Whether the siren is currently active */
+    Active = "active",
+    /** Volume level (0–100) */
+    Volume = "volume"
+}
+
+/**
+ * Properties for smoke sensors
+ *
+ * @internal
+ */
+declare enum SmokeProperty {
+    /** Whether smoke is detected */
+    Detected = "detected"
+}
+
+/**
+ * Properties for switch controls
+ *
+ * @internal
+ */
+declare enum SwitchProperty {
+    /** Whether the switch is on */
+    On = "on"
+}
+
+/**
+ * Properties for temperature sensors
+ *
+ * @internal
+ */
+declare enum TemperatureProperty {
+    /** Current temperature in degrees Celsius */
+    Current = "current"
+}
+
+/** Emitted when a sensor property value changes */
+interface PropertyChangedEvent {
+    cameraId: string;
+    sensorId: string;
+    sensorType: SensorType;
+    /** The property enum value that changed */
+    property: SensorPropertyType;
+    value: unknown;
+    previousValue?: unknown;
+    timestamp: number;
+}
+/**
+ * Receives a partial-state delta (only properties that actually changed). One callback
+ * invocation per `_writeState` call — atomic from the receiver's perspective.
+ *
+ * @internal
+ */
+type PropertyUpdateFn = (properties: Record<string, unknown>) => void;
+/** Callback for detailed property change events */
+type PropertyChangeListener = (event: PropertyChangedEvent) => void;
+/**
+ * @internal
+ */
+type CapabilityUpdateFn = (capabilities: string[]) => void;
+/** JSON-serializable representation of a sensor for RPC transport */
+interface SensorJSON {
+    id: string;
+    type: SensorType;
+    name: string;
+    displayName: string;
+    category: SensorCategory;
+    cameraId: string;
+    pluginId?: string;
+    properties: Record<string, unknown>;
+    capabilities?: string[];
+    /** True if this sensor needs video/audio frames from the backend pipeline */
+    requiresFrames?: boolean;
+    modelSpec?: ModelSpec;
+}
+
+/** Union of all sensor-specific property enums */
+type SensorPropertyType = AudioProperty | BatteryProperty | ContactProperty | DoorbellProperty | FaceProperty | GarageProperty | HumidityProperty | LeakProperty | LicensePlateProperty | LightProperty | LockProperty | MotionProperty | ObjectProperty | OccupancyProperty | PTZProperty | SecuritySystemProperty | SirenProperty | SmokeProperty | SwitchProperty | TemperatureProperty;
+/**
+ * Type of sensor. Each maps to a smart-home concept (HomeKit service).
+ * Plugins create sensors of these types and attach them to cameras.
+ */
+declare enum SensorType {
+    /** Video-based motion detection */
+    Motion = "motion",
+    /** Object detection (person, vehicle, animal, etc.) */
+    Object = "object",
+    /** Audio event detection (glass break, scream, etc.) */
+    Audio = "audio",
+    /** Face detection and recognition */
+    Face = "face",
+    /** License plate detection and OCR */
+    LicensePlate = "licensePlate",
+    /** General-purpose image classifier */
+    Classifier = "classifier",
+    /** CLIP embedding generation for semantic search */
+    Clip = "clip",
+    /** Contact/open-close sensor (door, window) */
+    Contact = "contact",
+    /** Temperature sensor (°C) */
+    Temperature = "temperature",
+    /** Humidity sensor (0–100%) */
+    Humidity = "humidity",
+    /** Occupancy/presence sensor */
+    Occupancy = "occupancy",
+    /** Smoke detector */
+    Smoke = "smoke",
+    /** Water leak detector */
+    Leak = "leak",
+    /** Light on/off and brightness control */
+    Light = "light",
+    /** Siren on/off and volume control */
+    Siren = "siren",
+    /** Generic on/off switch */
+    Switch = "switch",
+    /** Lock/unlock control */
+    Lock = "lock",
+    /** Pan-tilt-zoom camera control */
+    PTZ = "ptz",
+    /** Security system arm/disarm control */
+    SecuritySystem = "securitySystem",
+    /** Garage door opener */
+    Garage = "garage",
+    /** Doorbell ring trigger */
+    Doorbell = "doorbell",
+    /** Battery level and charging state */
+    Battery = "battery"
+}
+/**
+ * Categorizes a sensor's role in the system.
+ * Determines how the backend treats the sensor (read-only vs. controllable).
+ */
+declare enum SensorCategory {
+    /** Read-only detection sensor (motion, object, audio, etc.) */
+    Sensor = "sensor",
+    /** Controllable sensor with set methods (light, siren, PTZ, etc.) */
+    Control = "control",
+    /** Event trigger (doorbell ring) */
+    Trigger = "trigger",
+    /** Informational read-only state (battery level) */
+    Info = "info"
+}
+
+/**
+ * Python interpreter major.minor version a Python plugin requires. The host
+ *  ensures a matching interpreter exists in its venv pool before launching
+ *  the plugin; Node and Go plugins ignore this field.
+ */
+type PythonVersion = '3.11' | '3.12';
+/**
+ * Role a plugin plays in the system. The role decides which lifecycle hooks
+ * the host invokes and which contract validations apply (see helper.ts).
+ */
+declare enum PluginRole {
+    /**
+     * Cloud-service integration that manages its own cameras end-to-end via a
+     * vendor account (e.g. a vendor SDK / cloud API). The hub owns camera
+     * creation, streaming and sensors; it cannot expose sensors for cameras
+     * owned by other plugins.
+     */
+    Hub = "hub",
+    /**
+     * Adds sensors to existing cameras without owning the camera itself.
+     * Typical use: a detection plugin that consumes another plugin's video
+     * frames and emits motion / object / face detections back into the system.
+     */
+    SensorProvider = "sensorProvider",
+    /**
+     * Manages cameras and their media streams (ONVIF, RTSP, generic IP, ...).
+     * The plugin is responsible for stream URLs, PTZ, snapshots, and the
+     * lifecycle hooks in BasePlugin. It does not produce sensors for foreign
+     * cameras.
+     */
+    CameraController = "cameraController",
+    /**
+     * Combined role: plugin both manages cameras and exposes sensors (its own
+     * cameras and, when consumes is set, also foreign cameras). Used by
+     * integrations that ship a complete camera + detection stack.
+     */
+    CameraAndSensorProvider = "cameraAndSensorProvider"
+}
+/**
+ * Capability flags a plugin advertises in its contract. The host uses these
+ *  to decide which RPC handlers to wire up and which UI affordances to show.
+ */
+declare enum PluginInterface {
+    /** Implements MotionDetectionInterface (video-based motion detection). */
+    MotionDetection = "MotionDetection",
+    /** Implements ObjectDetectionInterface (e.g. person, vehicle, animal). */
+    ObjectDetection = "ObjectDetection",
+    /** Implements AudioDetectionInterface (event/keyword audio detection). */
+    AudioDetection = "AudioDetection",
+    /**
+     * Implements FaceDetectionInterface (face localisation + embeddings). The
+     *  NVR owns matching against enrolled faces; the plugin only emits
+     *  detections + embeddings.
+     */
+    FaceDetection = "FaceDetection",
+    /** Implements LicensePlateDetectionInterface (plate localisation + OCR). */
+    LicensePlateDetection = "LicensePlateDetection",
+    /**
+     * Implements ClassifierDetectionInterface (generic image classification
+     *  emitting attribute/label pairs).
+     */
+    ClassifierDetection = "ClassifierDetection",
+    /**
+     * Implements ClipDetectionInterface (CLIP image and text embeddings used
+     *  for semantic search).
+     */
+    ClipDetection = "ClipDetection",
+    /**
+     * Implements DiscoveryProvider — plugin can scan the network for new
+     *  cameras and adopt them. Only valid for camera-controlling roles.
+     */
+    DiscoveryProvider = "DiscoveryProvider",
+    /**
+     * Implements NVRInterface — persists events and recordings, and serves
+     *  them back to the UI / mobile clients. Exactly one plugin per host
+     *  fills this role at runtime.
+     */
+    NVR = "NVR",
+    /**
+     * Implements NotifierInterface (getDevices, sendNotification, ...). Lets
+     * the central NotificationManager dispatch notifications to this plugin
+     * regardless of role — see notifier.ts.
+     */
+    Notifier = "Notifier",
+    /**
+     * Implements the OAuthCapable base interface (getOAuthMetadata,
+     * getOAuthState, disconnect) plus at least one flow sub-interface below —
+     * see oauth.ts.
+     */
+    OAuthCapable = "OAuthCapable",
+    /** Implements OAuthDeviceFlowCapable (RFC 8628 Device Authorization Grant). */
+    OAuthDeviceFlow = "OAuthDeviceFlow",
+    /** Implements OAuthAuthCodeFlowCapable (Authorization Code Flow + PKCE). */
+    OAuthAuthCodeFlow = "OAuthAuthCodeFlow",
+    /** Implements OAuthClientCredentialsCapable (user-supplied client_id + client_secret). */
+    OAuthClientCredentials = "OAuthClientCredentials"
+}
+/**
+ * Permission a plugin requests so it can call a host-provided system feature.
+ * Each capability gates one outgoing SDK call — calls without the matching
+ * capability are rejected by the host.
+ */
+declare enum PluginCapability {
+    /**
+     * Grants the plugin permission to call `api.notificationManager.publish`.
+     * Without this capability the host silently drops published notifications
+     * and logs an error.
+     */
+    PublishNotifications = "publishNotifications"
+}
+/**
+ * Manifest contract a plugin declares so the host knows what it does and
+ * what it needs at load time. Validated by helper.ts before the plugin is
+ * started.
+ */
+interface PluginContract {
+    /**
+     * Stable, unique identifier for the plugin instance — used as the
+     *  registry key, log prefix and the storage namespace.
+     */
+    name: string;
+    /** Role of the plugin (see {@link PluginRole}). */
+    role: PluginRole;
+    /**
+     * Sensor types the plugin produces. Empty for hubs and pure
+     *  camera-controllers; required for sensor providers.
+     */
+    provides: SensorType[];
+    /**
+     * Sensor types the plugin reads from other plugins (e.g. a face plugin
+     *  consumes camera video frames).
+     */
+    consumes: SensorType[];
+    /** Capability flags the plugin implements (see {@link PluginInterface}). */
+    interfaces: PluginInterface[];
+    /**
+     * Permissions the plugin requests to call host system features (see
+     *  {@link PluginCapability}). The host enforces these — calls without a
+     *  matching capability are rejected.
+     */
+    capabilities?: PluginCapability[];
+    /**
+     * Required Python interpreter version for Python plugins. Ignored by
+     *  Node / Go plugins.
+     */
+    pythonVersion?: PythonVersion;
+    /**
+     * Extra package dependencies installed into the plugin's runtime (PyPI
+     *  for Python plugins, npm for Node plugins).
+     */
+    dependencies?: string[];
+}
+
+/**
+ * Reports whether the plugin can be queried for camera discovery — it must
+ * both implement the DiscoveryProvider interface and have a camera-owning
+ * role.
+ *
+ * @param contract - Plugin contract to inspect.
+ *
+ * @returns `true` if the plugin is a usable discovery provider.
+ *
+ * @example
+ * ```ts
+ * import { isDiscoveryProvider } from '@camera.ui/sdk/internal';
+ *
+ * if (isDiscoveryProvider(contract)) await runDiscovery(contract);
+ * ```
+ */
+declare function isDiscoveryProvider(contract: PluginContract): boolean;
+
+/**
+ * Camera stream resolution role.
+ * Used to identify different quality streams from the same camera.
+ */
+type CameraRole = 'high-resolution' | 'mid-resolution' | 'low-resolution' | 'snapshot';
+/**
+ * Detection event message type (lifecycle phase).
+ */
+type DetectionEventType = 'start' | 'end' | 'update' | 'segment-start' | 'segment-update' | 'segment-end';
+/**
+ * Event lifecycle state.
+ */
+type DetectionEventState = 'active' | 'ended';
+/**
+ * Event trigger type.
+ */
+type EventTriggerType = 'motion' | 'audio' | 'contact' | 'doorbell' | 'switch' | 'light' | 'siren' | 'security_system' | 'line-crossing';
+
+/**
+ * Camera input settings (user configuration).
+ */
+interface CameraInputSettings {
+    /** Unique source ID */
+    readonly _id: string;
+    /** Source display name */
+    name: string;
+    /** Resolution role */
+    role: CameraRole;
+    /** Use this source for snapshots */
+    useForSnapshot: boolean;
+    /** Keep connection always active */
+    hotMode: boolean;
+    /** Preload stream on startup */
+    preload: boolean;
+    /** Enable stream prebuffering */
+    prebuffer: boolean;
+    /** User-provided stream URLs */
+    urls: string[];
+    /** Child source ID (for snapshot fallback) */
+    childSourceId?: string;
+}
+/**
+ * Camera configuration subset for partial updates.
+ */
+type CameraConfigPartial = Partial<BaseCameraConfig> & {
+    sources?: Partial<CameraConfigInputSettings>[];
+};
+
+/**
+ * WebRTC ICE server configuration.
+ */
+interface IceServer {
+    /** STUN/TURN server URLs */
+    urls: string[];
+    /** Authentication username */
+    username?: string;
+    /** Authentication credential */
+    credential?: string;
+}
+/**
+ * Subscription management interface for sessions.
+ */
+interface Subscribed {
+    /** Add subscriptions to be cleaned up on unsubscribe */
+    addSubscriptions(...subscriptions: Disposable[]): void;
+    /** Add additional subscriptions (separate cleanup) */
+    addAdditionalSubscriptions(...subscriptions: Disposable[]): void;
+    /** Unsubscribe all main subscriptions */
+    unsubscribe(): void;
+    /** Unsubscribe additional subscriptions only */
+    unsubscribeAdditional(): void;
+}
+
+/**
+ * Camera input settings for config.
+ */
+interface CameraConfigInputSettings extends Omit<CameraInputSettings, '_id' | 'urls'> {
+    urls?: string[];
+}
+/**
+ * Base camera configuration (shared fields).
+ */
+interface BaseCameraConfig {
+    /** Camera display name */
+    name: string;
+    /** Native device ID from plugin */
+    nativeId?: string;
+    /** Whether camera streams from cloud */
+    isCloud?: boolean;
+    /** Disable this camera */
+    disabled?: boolean;
+    /** Camera hardware information */
+    info?: Partial<CameraInformation>;
+}
+/**
+ * Camera hardware/firmware information.
+ */
+interface CameraInformation {
+    /** Camera model name */
+    model?: string;
+    /** Manufacturer name */
+    manufacturer?: string;
+    /** Hardware version/revision */
+    hardware?: string;
+    /** Device serial number */
+    serialNumber?: string;
+    /** Current firmware version */
+    firmwareVersion?: string;
+    /** Manufacturer support URL */
+    supportUrl?: string;
+}
+
+/** AI-generated event description. */
+interface EventDescription {
+    /** Brief title of what occurred */
+    title: string;
+    /** Chronological narrative of the scene */
+    description: string;
+    /** Two-sentence notification-friendly summary */
+    summary: string;
+    /** Threat level: 0 = normal, 1 = suspicious, 2 = threat */
+    threatLevel: number;
+}
+/**
+ * Event trigger (motion, audio, sensor, or line-crossing).
+ */
+interface EventTrigger {
+    /** Trigger type */
+    type: EventTriggerType;
+    /** Audio label (e.g. "doorbell", "glass_break") */
+    label?: string;
+    /** Best confidence score */
+    score?: number;
+    /** First detection time (Unix ms) */
+    firstSeen: number;
+    /** Last detection time (Unix ms) */
+    lastSeen: number;
+    /** Name of the crossed line (only for line-crossing triggers) */
+    lineName?: string;
+    /** Crossing direction (only for line-crossing triggers) */
+    crossingDirection?: 'a-to-b' | 'b-to-a';
+    /** Track ID of the object that crossed (only for line-crossing triggers) */
+    trackId?: number;
+}
+/**
+ * Aggregated object detection within a segment.
+ */
+interface EventDetection {
+    /** Detection label (e.g. "person", "car") */
+    label: string;
+    /** Best confidence score */
+    score: number;
+    /** Maximum simultaneous count in a single frame */
+    maxCount: number;
+    /** Bounding box of the highest-confidence detection (normalized 0–1) */
+    box?: BoundingBox;
+    /** Best-selected JPEG thumbnail crop. Only present on 'end' events. */
+    thumbnail?: Uint8Array;
+    /** Object tracker ID (links this detection across frames) */
+    trackId?: number;
+    /** Whether the object was moving (true) or stationary (false) */
+    moving?: boolean;
+}
+/**
+ * Unified attribute within a segment (face identity, license plate, classifier result).
+ */
+interface EventAttribute {
+    /** Attribute type ('face', 'license_plate', or classifier-specific like 'bird') */
+    type: string;
+    /** Identity name, plate text, or classification label */
+    label: string;
+    /** Detection confidence (0-1) */
+    confidence?: number;
+    /** Best-selected JPEG thumbnail crop. Only present on 'end' events. */
+    thumbnail?: Uint8Array;
+    /** Face embedding vector for unknown face persistence. Only present for face attributes. */
+    embedding?: number[];
+    /** Embedding model identifier. Only present for face attributes with embedding. */
+    embeddingModel?: string;
+    /** CLIP embedding vector for semantic search. Only present for clip attributes. */
+    clipEmbedding?: number[];
+    /** CLIP embedding model identifier. Only present for clip attributes with embedding. */
+    clipEmbeddingModel?: string;
+    /** Parent object's tracker ID (links this attribute to its parent detection) */
+    parentTrackId?: number;
+}
+/**
+ * A contiguous object detection phase within an event.
+ */
+interface EventSegment {
+    /** Segment start time (Unix ms) */
+    firstSeen: number;
+    /** Segment end time (Unix ms) */
+    lastSeen: number;
+    /** Best-selected JPEG scene thumbnail for this segment. Only present on 'end' events. */
+    thumbnail?: Uint8Array;
+    /** Object detections in this segment */
+    detections: EventDetection[];
+    /** Unified attributes (faces, plates, classifications) */
+    attributes: EventAttribute[];
+    /** Names of detection zones any detection in this segment overlapped (deduplicated) */
+    zones?: string[];
+    /** AI-generated description for this segment */
+    description?: EventDescription;
+}
+/**
+ * Aggregated detection event with lifecycle (start → update → end).
+ * Groups individual sensor detections into structured events.
+ */
+interface DetectionEvent {
+    /** Unique event ID */
+    id: string;
+    /** Camera that produced this event */
+    cameraId: string;
+    /** Event lifecycle state */
+    state: DetectionEventState;
+    /** Event start time (Unix ms) */
+    startTime: number;
+    /** Event end time (Unix ms, only when ended) */
+    endTime?: number;
+    /** Last activity timestamp (Unix ms) */
+    lastUpdate: number;
+    /** Detection types present in this event (for filtering) */
+    types: string[];
+    /** Event triggers (motion/audio) */
+    triggers: EventTrigger[];
+    /**
+     * Detection segments (object detection phases).
+     *  For segment-* messages: contains only the current segment.
+     *  For start/end messages: empty.
+     */
+    segments: EventSegment[];
+    /** Index of the segment in segments[0] for segment-* messages. */
+    segmentIndex?: number;
+    /**
+     * Expected event end time (Unix ms) — the latest dwell expiry across all
+     *  currently-active triggers. Monotonically non-decreasing during the event
+     *  lifetime. Updated on each `update` / `segment-*` message.
+     */
+    expectedEndTime?: number;
+    /**
+     * Full-frame downscaled JPEG captured at event start. Inline only on the
+     *  first message that delivers it (`start` or the first `update`); the NVR
+     *  plugin persists it and clients fetch it on demand via getEventThumbnails.
+     */
+    thumbnail?: Buffer;
+}
+
+/**
+ * Discovered camera from a discovery provider.
+ *
+ * Represents a camera found during network scanning or cloud lookup that
+ * can be adopted into the system. Push these via
+ * `deviceManager.pushDiscoveredCameras` so the user can pick them in the
+ * UI without waiting for the next discovery poll.
+ */
+interface DiscoveredCamera {
+    /** Unique, stable identifier for this discovered camera (used for deduplication). */
+    id: string;
+    /** Display name shown in the UI adoption list. */
+    name: string;
+    /** Camera manufacturer label (optional). */
+    manufacturer?: string;
+    /** Camera model label (optional). */
+    model?: string;
+}
+
+/**
+ * Connection status for discovered cameras.
+ */
+type ConnectionStatus = 'idle' | 'connecting' | 'connected' | 'error';
+/**
+ * Discovered camera with provider and connection state.
+ *
+ * Extended version of `DiscoveredCamera` used by the UI to render the
+ * adoption list — adds the provider plugin name and a live connection
+ * status so users see whether the camera is currently reachable.
+ */
+interface DiscoveredCameraWithState extends DiscoveredCamera {
+    /** Name of the provider plugin that discovered this camera. */
+    provider: string;
+    /** Current connection status reported by the provider. */
+    connectionStatus: ConnectionStatus;
+    /** Last error message when `connectionStatus` is `'error'`. */
+    errorMessage?: string;
+}
+
+/**
+ * Deep equality check for arbitrary values.
+ *
+ * Recursively compares primitives, arrays, and plain objects. Object
+ * comparison ignores property declaration order (only key/value pairs
+ * matter). Set `ignoreOrder` to `true` to compare arrays as multisets,
+ * i.e. ignoring element order.
+ *
+ * Typically used for property-change detection on sensors: a property
+ * update is only emitted when the new value is not deeply equal to the
+ * previous value, which avoids redundant events for unchanged data.
+ *
+ * @param first - First value to compare.
+ *
+ * @param second - Second value to compare.
+ *
+ * @param ignoreOrder - If `true`, arrays are compared ignoring element order.
+ *
+ * @returns `true` if the values are deeply equal.
+ *
+ * @example
+ * ```ts
+ * import { isEqual } from '@camera.ui/sdk/internal';
+ *
+ * isEqual({ a: 1, b: 2 }, { b: 2, a: 1 }); // true
+ * isEqual([1, 2, 3], [3, 2, 1], true);     // true (ignoreOrder)
+ * ```
+ */
+declare function isEqual(first: unknown, second: unknown, ignoreOrder?: boolean): boolean;
+
+/**
+ * Detection event message published via NATS.
+ */
+interface DetectionEventMessage {
+    /** Event lifecycle type */
+    type: DetectionEventType;
+    /** Full event data */
+    data: DetectionEvent;
+}
+
+/** Sensor trigger types — the subset of trigger types that originate from configurable sensors (excludes motion/audio). */
+declare const SENSOR_TRIGGER_TYPES: readonly ["contact", "doorbell", "switch", "light", "siren", "security_system"];
+type SensorTriggerType = (typeof SENSOR_TRIGGER_TYPES)[number];
+
+/**
+ * Frame type identifier for frame workers.
+ */
+type FrameType = 'stream' | 'motion';
+/**
+ * Frame worker decoder implementation.
+ */
+type CameraFrameWorkerDecoder = 'wasm' | 'rust';
+
+export { SENSOR_TRIGGER_TYPES, isDiscoveryProvider, isEqual };
+export type { CameraConfigPartial, CameraFrameWorkerDecoder, CameraInputSettings, CapabilityUpdateFn, ConnectionStatus, DetectionEventMessage, DiscoveredCameraWithState, FrameType, IceServer, PropertyChangeListener, PropertyChangedEvent, PropertyUpdateFn, SensorJSON, SensorTriggerType, Subscribed };