@camstack/sdk 0.1.23 → 0.1.25

package/dist/sdk/src/index.d.ts

@@ -0,0 +1,15 @@
+export { BackendClient, createBackendClient } from "./backend-client.js";
+export type { BackendAppRouter } from "./backend-router.js";
+export type { BackendAppRouter as AppRouter } from "./backend-router.js";
+export type { BackendClientConfig } from "./types.js";
+export { DetectionClass, animalClasses, personClasses, vehicleClasses, faceClasses, licensePlateClasses, motionClasses, packageClasses, audioClasses, audioLabelClasses, doorbellClasses, sensorLabelClasses, detectionClassesDefaultMap, isFaceClassname, isPlateClassname, isAnimalClassname, isPersonClassname, isVehicleClassname, isMotionClassname, isDoorbellClassname, isPackageClassname, isAudioClassname, isSensorLabelClassname, isLabelDetection, getParentClass, getParentDetectionClass, defaultDetectionClasses, DEFAULT_ENABLED_CLASSES, TIMELINE_PRESET_CRITICAL, TIMELINE_PRESET_IMPORTANT, TIMELINE_PRESET_ALL, getClassesForTimelinePreset, } from "./detection.js";
+export type { TimelineEventPreset } from "./detection.js";
+export { RAW_TO_CANONICAL, HA_DOMAIN_TYPE_MAP, SCRYPTED_TYPE_TO_CANONICAL, getCanonicalDeviceType, ELIGIBLE_SCRYPTED_DEVICE_TYPES, ELIGIBLE_SCRYPTED_DEVICE_TYPES_SET, ELIGIBLE_HA_DOMAINS, ELIGIBLE_HA_DOMAINS_SET, } from "./devices.js";
+export type { CanonicalDeviceType, DeviceCommandAction, AssociatedDeviceState, Device, DeviceAction, DeviceActionParam, DeviceCommand, CommandResult, AssociatedDeviceSource, EligibleDevice, } from "./devices.js";
+export type { TimelineEventSeverity, MotionFragmentType, DetectionEvent, MotionItem, TimelineArtifact, AudioLevelSegment, TimelineRecordingSegment, CameraDayDataResponse, ClusteredDayDataResponse, TimelineCluster, DetectionGroup, ClusteredDayDataQuery, GroupedEventsQuery, GroupedEventsResult, ClusterEventsQuery, ClusterEventsResult, ReelEvent, ReelEventsQuery, ReelEventsResult, TimelineDetectionEvent, TimelineMotionItem, TimelineArtifactItem, TimelineClusterFromServer, } from "./timeline.js";
+export type { CameraSourceType, StreamMethod, PanTiltZoomCommand, PanTiltZoomCapabilities, CameraAccessorySwitchKind, CameraStatusEntry, CamerasStatusResult, } from "./camera.js";
+export { FEATURE_MATRIX, isFeatureAvailable, getSourceFeatures, getBackendRequiredFeatures, } from "./features.js";
+export type { FeatureId, PlatformId, SourceType, FeatureEntry, } from "./features.js";
+export { selectOptimalStream, getNextEvalInterval, } from "./adaptive-stream.js";
+export type { StreamConstraints, StreamAssignment, StreamSelectionRequest, StreamSelectionResponse, } from "./adaptive-stream.js";
+export type { StreamOption, NvrCamera, CameraAccessory, StreamInfo, NormalizedBoundingBox, DetectionData, EventSnapshotData, NvrEvent, RecordingSegment, MotionBucket, LiveDetection, LiveMotionData, LiveDetectionData, LiveAudioData, LiveMotionEvent, LiveDetectionEvent, LiveAudioEvent, LiveGenericEvent, LiveReviewEvent, LiveEvent, LiveEventType, VideoClipsQuery, NvrVideoClip, VideoClipsResult, VideoClipUrlResult, CameraDayData, CameraStatus, EventsQuery, MotionQuery, RecordingsQuery, NvrConfig, ProviderConfigs, } from "./nvr.js";

package/dist/sdk/src/nvr.d.ts

@@ -0,0 +1,285 @@
+/**
+ * NVR types — system-agnostic types used by providers and the SDK client.
+ *
+ * These are the canonical types from the proxy's providers/types.ts,
+ * now owned by the SDK so both app and proxy can share them.
+ */
+export interface StreamOption {
+    /** Unique identifier for this option (e.g. "auto", "cam_main", "mjpeg"). */
+    id: string;
+    /** Display label (e.g. "Auto", "High (WebRTC)", "MJPEG"). */
+    label: string;
+    /** Streaming technology. */
+    method: "webrtc" | "mjpeg" | "hls" | "rtsp";
+    /** go2rtc stream name (required for WebRTC). */
+    streamName?: string;
+    /** Raw source URL (RTSP, etc.) — for display/copy in admin UI. */
+    sourceUrl?: string;
+    /** Group label for UI separators (e.g. "go2rtc", "Frigate", "Scrypted"). */
+    group?: string;
+}
+export interface NvrCamera {
+    name: string;
+    /** Display label (may differ from internal name). */
+    label?: string;
+    enabled: boolean;
+    hasAudio: boolean;
+    hasPtz: boolean;
+    /** Available stream names for this camera (e.g. ["cam_main", "cam_sub"]). */
+    streams: string[];
+    /** Available streaming options with method and quality info. Always includes "Auto". */
+    streamOptions: StreamOption[];
+    /** Accessories/actions available on this camera (siren, floodlight, PTZ, etc.). */
+    accessories?: CameraAccessory[];
+}
+/**
+ * A camera accessory — a controllable feature attached to a camera.
+ * Declared by the provider, rendered dynamically in the UI.
+ */
+export interface CameraAccessory {
+    /** Unique accessory ID (e.g. "siren", "floodlight", "ptz", "ir_led"). */
+    id: string;
+    /** Display label (e.g. "Siren", "Floodlight"). */
+    label: string;
+    /** Accessory type determines UI rendering. */
+    type: "toggle" | "button" | "ptz" | "slider";
+    /** Lucide icon name (e.g. "siren", "lightbulb", "move", "sun"). */
+    icon: string;
+    /** Current state (for toggles: boolean, for sliders: number). */
+    state?: unknown;
+    /** For slider type: min/max/step. */
+    min?: number;
+    max?: number;
+    step?: number;
+}
+export interface StreamInfo {
+    name: string;
+    /** Camera this stream belongs to (if determinable). */
+    camera?: string;
+}
+/** Normalized bounding box in 0–1 range (provider-agnostic). */
+export interface NormalizedBoundingBox {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** Detection data attached to an event. */
+export interface DetectionData {
+    label: string;
+    subLabel?: string;
+    /** Confidence score 0–1. */
+    score: number;
+    /** Best confidence score observed during the event. */
+    topScore?: number;
+    /** Bounding box of the detected object, normalized 0–1. */
+    boundingBox?: NormalizedBoundingBox;
+    /** Detection region, normalized 0–1. */
+    region?: NormalizedBoundingBox;
+    /** Area as fraction of frame area (0–1). */
+    area?: number;
+    /** Named zones the object is currently in. */
+    currentZones?: string[];
+    /** Named zones the object has entered during this event. */
+    enteredZones?: string[];
+    /** Attributes detected (e.g., { face: 0.64, glasses: 0.82 }). */
+    attributes?: Record<string, number>;
+    /** Current estimated speed. */
+    currentSpeed?: number;
+    /** Average estimated speed over the event. */
+    averageSpeed?: number;
+    /** Velocity angle in degrees. */
+    velocityAngle?: number;
+    /** License plate recognition result. */
+    licensePlate?: {
+        text: string;
+        score: number;
+    };
+}
+/** Snapshot metadata associated with an event. */
+export interface EventSnapshotData {
+    boundingBox?: NormalizedBoundingBox;
+    score?: number;
+    /** Area as fraction of frame area (0–1). */
+    area?: number;
+    attributes?: Record<string, number>;
+}
+export interface NvrEvent {
+    id: string;
+    camera: string;
+    label: string;
+    startTime: number;
+    endTime: number | null;
+    severity?: string;
+    hasClip: boolean;
+    hasSnapshot: boolean;
+    thumbnailPath?: string;
+    snapshotPath?: string;
+    clipPath?: string;
+    detection?: DetectionData;
+    snapshot?: EventSnapshotData;
+    falsePositive?: boolean;
+    retainIndefinitely?: boolean;
+    raw?: Record<string, unknown>;
+}
+export interface RecordingSegment {
+    id: string;
+    camera: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    motion?: number;
+    objects?: number;
+    dBFS?: number;
+}
+export interface MotionBucket {
+    camera: string;
+    startTime: number;
+    motion?: number;
+    audio?: number;
+}
+/** Single object detection from a live frame. */
+export interface LiveDetection {
+    /** Detection class — the object type (person, car, dog, face, plate, etc.) */
+    className: string;
+    /** Recognized identity — face name, license plate text, sub-label. */
+    label?: string;
+    /** Detection confidence 0–1. */
+    score: number;
+    /** Label/recognition confidence 0–1 — takes precedence over score when available. */
+    labelScore?: number;
+    /** Named zones where the object currently is. */
+    zones?: string[];
+    /** Tracking/correlation ID across frames. */
+    id?: string;
+    /** Bounding box as fractions 0–1 of frame dimensions. */
+    boundingBox?: [number, number, number, number] | {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+export interface LiveMotionData {
+    active: boolean;
+}
+export interface LiveDetectionData {
+    detections: LiveDetection[];
+    /** Input frame dimensions [width, height] in pixels (for reference). */
+    inputDimensions?: [number, number];
+    /** Event ID from the NVR (e.g. Frigate event ID). */
+    eventId?: string;
+    /** Provider-specific extra data. */
+    [key: string]: unknown;
+}
+export interface LiveAudioData {
+    /** Audio metric type (e.g. "dBFS", "rms", "audioDetected", "audioLevel"). */
+    metric: string;
+    /** Numeric value. */
+    value?: number;
+    /** dBFS level. */
+    dBFS?: number;
+    /** RMS level. */
+    rms?: number;
+}
+export type LiveEventType = "motion" | "detection" | "audio" | "event" | "review";
+interface LiveEventBase {
+    camera: string;
+    timestamp: number;
+    /** Provider info — populated by onAllEvents subscription. */
+    provider?: {
+        id: string;
+        name: string;
+        type: string;
+    };
+}
+export interface LiveMotionEvent extends LiveEventBase {
+    type: "motion";
+    data: LiveMotionData;
+}
+export interface LiveDetectionEvent extends LiveEventBase {
+    type: "detection";
+    data: LiveDetectionData;
+}
+export interface LiveAudioEvent extends LiveEventBase {
+    type: "audio";
+    data: LiveAudioData;
+}
+export interface LiveGenericEvent extends LiveEventBase {
+    type: "event";
+    data: Record<string, unknown>;
+}
+export interface LiveReviewEvent extends LiveEventBase {
+    type: "review";
+    data: Record<string, unknown>;
+}
+export type LiveEvent = LiveMotionEvent | LiveDetectionEvent | LiveAudioEvent | LiveGenericEvent | LiveReviewEvent;
+export interface VideoClipsQuery {
+    camera: string;
+    after: number;
+    before: number;
+    limit?: number;
+    offset?: number;
+}
+export interface NvrVideoClip {
+    id: string;
+    camera: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    label?: string;
+    hasClip: boolean;
+    hasSnapshot: boolean;
+    source: "event" | "recording";
+}
+export interface VideoClipsResult {
+    clips: NvrVideoClip[];
+    total: number;
+}
+export interface VideoClipUrlResult {
+    url: string;
+    mimeType: string;
+}
+export interface CameraDayData {
+    events: NvrEvent[];
+    motion: MotionBucket[];
+    recordings: RecordingSegment[];
+}
+export interface CameraStatus {
+    camera: string;
+    online: boolean;
+    recording: boolean;
+    detecting: boolean;
+    motionActive: boolean;
+}
+export interface EventsQuery {
+    after?: number;
+    before?: number;
+    cameras?: string[];
+    limit?: number;
+    labels?: string[];
+}
+export interface MotionQuery {
+    after: number;
+    before: number;
+    scale?: number;
+    cameras?: string[];
+}
+export interface RecordingsQuery {
+    camera: string;
+    after: number;
+    before: number;
+}
+export interface NvrConfig {
+    type: string;
+    version?: string;
+    raw?: unknown;
+}
+export interface ProviderConfigs {
+    cameras: Array<{
+        id: string;
+        name: string;
+    }>;
+    enabledDetectionSources?: string[];
+}
+export {};

package/dist/sdk/src/timeline.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Timeline & event types — shared between CamStack app and proxy.
+ *
+ * Names are unified: the proxy's naming convention is canonical.
+ * The app re-exports aliases for backward compatibility where needed.
+ */
+/** Frigate severity: alert = notable, detection = regular. */
+export type TimelineEventSeverity = "alert" | "detection";
+/** Motion fragment type: start/end from event boundaries, update from motion API. */
+export type MotionFragmentType = "start" | "end" | "update";
+/**
+ * A detection event for timeline display and grouping.
+ * Unified from app's TimelineDetectionEvent and proxy's DetectionEvent.
+ */
+export interface DetectionEvent {
+    id?: string;
+    timestamp: number;
+    source?: string;
+    classes?: string[];
+    /** @deprecated Use `classes` instead. Kept for backward compat with some app code. */
+    detectionClasses?: string[];
+    label?: string;
+    thumbnailUrl?: string;
+    imageUrl?: string;
+    videoUrl?: string;
+    gifUrl?: string;
+    severity?: TimelineEventSeverity;
+    deviceName?: string;
+    deviceId?: string;
+    ruleType?: string;
+    croppedThumbnailUrl?: string;
+    [key: string]: unknown;
+}
+/**
+ * Motion on/off item for timeline bar.
+ * Unified from app's TimelineMotionItem and proxy's MotionItem.
+ */
+export interface MotionItem {
+    timestamp: number;
+    deviceId?: string;
+    motion: "on" | "off";
+    /** Fragment type or "motion" | "audio" (AN audio thresholds). */
+    type?: MotionFragmentType | "motion" | "audio" | string;
+    /** For type "audio": level 1–5 (threshold crossed). */
+    level?: number;
+    /** For type "audio": dBFS at threshold crossing. */
+    dBFS?: number;
+}
+/**
+ * Rule artifact for timeline (from Scrypted AN plugin rules).
+ * Unified from app's TimelineArtifactItem and proxy's TimelineArtifact.
+ */
+export interface TimelineArtifact {
+    ruleName: string;
+    ruleType?: string;
+    timestamp: number;
+    imageUrl?: string;
+    gifUrl?: string;
+    videoUrl?: string;
+}
+/** Audio level segment for timeline bar. */
+export interface AudioLevelSegment {
+    start: number;
+    end: number;
+    level: number;
+    dBFS?: number;
+}
+/** Recording segment for timeline bar (where recording exists). */
+export interface TimelineRecordingSegment {
+    start: number;
+    end: number;
+}
+/** Day data for timeline (events, motion, artifacts). */
+export interface CameraDayDataResponse {
+    events: DetectionEvent[];
+    motion: MotionItem[];
+    artifacts: TimelineArtifact[];
+    recordings?: TimelineRecordingSegment[];
+}
+/** Clustered day data response (server-side bucketing). */
+export interface ClusteredDayDataResponse {
+    clusters: TimelineCluster[];
+    motion: MotionItem[];
+    artifacts: TimelineArtifact[];
+    motionSegments?: TimelineRecordingSegment[];
+    audioLevelSegments?: AudioLevelSegment[];
+    recordings?: TimelineRecordingSegment[];
+}
+/** A time-bucketed cluster of detection events. */
+export interface TimelineCluster {
+    events: DetectionEvent[];
+    representative: DetectionEvent;
+    classes: string[];
+    labels: string[];
+    startMs: number;
+    endMs: number;
+}
+/** A group of related detection events with a representative. */
+export interface DetectionGroup {
+    events: DetectionEvent[];
+    representative: DetectionEvent;
+    classes: string[];
+    labels: string[];
+}
+/** Query for clustered day data. */
+export interface ClusteredDayDataQuery {
+    camera: string;
+    days: string[];
+    bucketMs?: number;
+    enabledClasses?: string[];
+    classFilter?: string;
+}
+/** Query for grouped events. */
+export interface GroupedEventsQuery {
+    after?: number;
+    before?: number;
+    limit?: number;
+    offset?: number;
+    cameras?: string[];
+    detectionClasses?: string[];
+    eventSource?: string;
+    filter?: string;
+    groupingRange?: number;
+}
+/** Result of grouped events query. */
+export interface GroupedEventsResult {
+    groups: DetectionGroup[];
+    total: number;
+    ruleArtifacts?: DetectionGroup[];
+}
+/** Query for events within a cluster time range. */
+export interface ClusterEventsQuery {
+    camera: string;
+    startMs: number;
+    endMs: number;
+}
+/** Result of cluster events query. */
+export interface ClusterEventsResult {
+    events: DetectionEvent[];
+}
+/** A reel event (carousel-friendly). All timestamps are in **seconds** (Unix epoch). */
+export interface ReelEvent {
+    id: string;
+    camera: string;
+    cameraName: string;
+    label: string;
+    /** Unix timestamp in **seconds** (not milliseconds). */
+    startTime: number;
+    thumbnail?: string;
+    croppedThumbnailUrl?: string;
+    hasClip?: boolean;
+    gifUrl?: string;
+    videoUrl?: string;
+    imageUrl?: string;
+    classes?: string[];
+}
+/** Query for reel events. */
+export interface ReelEventsQuery {
+    limit?: number;
+    offset?: number;
+    cameras?: string[];
+    eventSource?: string;
+    detectionClasses?: string[];
+}
+/** Result of reel events query. */
+export interface ReelEventsResult {
+    events: ReelEvent[];
+    total: number;
+}
+/** @deprecated Use DetectionEvent instead. */
+export type TimelineDetectionEvent = DetectionEvent;
+/** @deprecated Use MotionItem instead. */
+export type TimelineMotionItem = MotionItem;
+/** @deprecated Use TimelineArtifact instead. */
+export type TimelineArtifactItem = TimelineArtifact;
+/** @deprecated Use TimelineCluster instead. */
+export type TimelineClusterFromServer = TimelineCluster;

package/dist/sdk/src/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SDK client configuration types.
+ *
+ * NVR types are now in nvr.ts (shared across app and proxy).
+ */
+export interface HlsInfo {
+    hlsUrl: string;
+}
+/** Public provider info (returned by providers.list). */
+export interface ProviderInfo {
+    id: string;
+    type: string;
+    name: string;
+}
+export interface ProxyClientConfig {
+    /**
+     * Primary proxy URL (e.g. "http://192.168.1.100:4000").
+     * Can also be an array of URLs to race (like Scrypted SDK).
+     * The first successful connection wins.
+     */
+    proxyUrl: string | string[];
+    /** Optional auth token for admin endpoints. */
+    token?: string;
+    /** Transport: "websocket" (default, like Scrypted SDK) or "http" (REST fallback). */
+    transport?: "websocket" | "http";
+    /** Connection timeout per URL in ms (default: 10000). */
+    connectTimeoutMs?: number;
+}
+export interface DirectClientConfig {
+    directUrl: string;
+    type: "frigate";
+    username?: string;
+    password?: string;
+}
+export interface BackendClientConfig {
+    /** Backend server URL (e.g. "http://localhost:4443") */
+    readonly serverUrl: string;
+    /** JWT token for authentication */
+    readonly token?: string;
+    /** Connection timeout in ms (default: 10000) */
+    readonly connectTimeoutMs?: number;
+}
+export type CamStackClientConfig = ProxyClientConfig | DirectClientConfig;
+export declare function isProxyConfig(config: CamStackClientConfig): config is ProxyClientConfig;

package/dist/types/src/catalogs/coco-classmap.d.ts

@@ -0,0 +1,4 @@
+import type { LabelDefinition, ClassMapDefinition } from '../types/labels.js';
+export declare const COCO_80_LABELS: readonly LabelDefinition[];
+export declare const MACRO_LABELS: readonly LabelDefinition[];
+export declare const COCO_TO_MACRO: ClassMapDefinition;

package/dist/types/src/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const HF_REPO = "camstack/camstack-models";
+export declare const HF_BASE_URL = "https://huggingface.co/camstack/camstack-models/resolve/main";