@camstack/sdk 0.1.29 → 0.1.31

package/dist/adaptive-stream.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Adaptive Stream Session — negotiates optimal stream quality with the proxy.
+ *
+ * The client reports viewport size and network conditions periodically.
+ * The proxy selects the best stream from the provider's available streams
+ * and instructs the client to switch via go2rtc stream renegotiation.
+ *
+ * Flow:
+ * 1. Client opens session → sends initial constraints (viewport, network)
+ * 2. Server evaluates available streams → picks optimal → responds with stream assignment
+ * 3. Client connects to assigned go2rtc stream via WebRTC WHEP
+ * 4. Periodically, client reports updated stats → server may switch stream
+ * 5. On switch: client tears down old PC, creates new PC to new go2rtc stream
+ */
+/** Client-reported constraints for stream selection. */
+export interface StreamConstraints {
+    /** Viewport width in CSS pixels. */
+    viewportWidth: number;
+    /** Viewport height in CSS pixels. */
+    viewportHeight: number;
+    /** Device pixel ratio (retina = 2+). */
+    pixelRatio?: number;
+    /** Estimated downlink bandwidth in Mbps (from navigator.connection or WebRTC stats). */
+    bandwidthMbps?: number;
+    /** Round-trip time in ms (from WebRTC stats). */
+    rttMs?: number;
+    /** Packet loss ratio 0-1 (from WebRTC stats). */
+    packetLoss?: number;
+    /** Whether the client is on a cellular network. */
+    isCellular?: boolean;
+    /** Whether the client prefers low latency over quality. */
+    preferLowLatency?: boolean;
+    /** Maximum resolution the client wants (e.g., from a user setting). */
+    maxResolution?: "auto" | "high" | "medium" | "low";
+}
+/** Server-assigned stream for the client. */
+export interface StreamAssignment {
+    /** go2rtc stream name to connect to. */
+    streamName: string;
+    /** Stream profile (main/sub/ext). */
+    profile: string;
+    /** Transport type (native/rtsp/rtmp). */
+    transport: string;
+    /** Human-readable label. */
+    label: string;
+    /** Stream metadata (if known). */
+    metadata?: {
+        width?: number;
+        height?: number;
+        fps?: number;
+        bitrate?: number;
+        codec?: string;
+    };
+    /** Reason for this selection. */
+    reason: string;
+}
+/** Stream selection request from client → server. */
+export interface StreamSelectionRequest {
+    providerId: string;
+    camera: string;
+    constraints: StreamConstraints;
+    /** Current stream (for comparison — only switch if significantly better). */
+    currentStreamName?: string;
+}
+/** Stream selection response from server → client. */
+export interface StreamSelectionResponse {
+    assignment: StreamAssignment;
+    /** Available alternatives the client can manually pick. */
+    alternatives: StreamAssignment[];
+    /** Seconds until next automatic re-evaluation. */
+    nextEvalSeconds: number;
+}
+/**
+ * Select the optimal stream from available options based on client constraints.
+ * This is a pure function — no side effects.
+ */
+export declare function selectOptimalStream(streams: Array<{
+    streamName: string;
+    profile: string;
+    transport: string;
+    label: string;
+    metadata?: {
+        width?: number;
+        height?: number;
+        fps?: number;
+        bitrate?: number;
+        codec?: string;
+    };
+}>, constraints: StreamConstraints, defaultTransport?: string): StreamAssignment | null;
+/** Determine seconds until next re-evaluation based on stability. */
+export declare function getNextEvalInterval(constraints: StreamConstraints, wasSwitch: boolean): number;

package/dist/backend-client.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Backend client — connects directly to the CamStack NestJS backend via tRPC.
+ *
+ * Use this when the client needs to talk to the backend server directly
+ * (admin UI, local agent, embedded mode) rather than going through the proxy.
+ *
+ * Features: full typed access to all backend tRPC routes (auth, devices, providers,
+ * pipeline, agents, addons, bridge pipeline, recording, events, live subscriptions).
+ */
+import { createTRPCClient } from "@trpc/client";
+import type { BackendAppRouter } from "./backend-router.js";
+export type SettingsSection = 'server' | 'auth' | 'features' | 'storage' | 'logging' | 'addons' | 'recording' | 'streaming' | 'ffmpeg' | 'detection' | 'backup' | 'retention';
+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;
+    /** Use WebSocket for all queries/mutations (default: true in browser, false in Node) */
+    readonly useWebSocket?: boolean;
+}
+export declare class BackendClient {
+    /** Raw tRPC client — for advanced usage / direct path access */
+    readonly trpc: ReturnType<typeof createTRPCClient<BackendAppRouter>>;
+    readonly serverUrl: string;
+    private token;
+    private wsClient;
+    constructor(config: BackendClientConfig);
+    /** Update the auth token (e.g. after login) */
+    setToken(token: string): void;
+    /** Close the WebSocket connection (if using WS transport) */
+    close(): void;
+    login(username: string, password: string): Promise<{
+        token: string;
+        user: {
+            id: string;
+            username: string;
+            role: import("@camstack/types").UserRole;
+        };
+    }>;
+    getMe(): Promise<import("@camstack/types").AuthenticatedUser>;
+    logout(): Promise<{
+        success: boolean;
+    }>;
+    getSystemInfo(): Promise<{
+        version: string;
+        uptime: number;
+        nodeVersion: string;
+        platform: NodeJS.Platform;
+        features: import("@camstack/types").FeatureManifest;
+    }>;
+    getFeatureFlags(): Promise<import("@camstack/types").FeatureManifest>;
+    listProviders(): Promise<readonly import("@camstack/types").ProviderListItem[]>;
+    getProvider(providerId: string): Promise<{
+        id: string;
+        type: string;
+        name: string;
+        discoveryMode: "auto" | "manual" | "both";
+        status: import("@camstack/types").ProviderStatus;
+        deviceCount: number;
+    }>;
+    startProvider(providerId: string): Promise<{
+        success: boolean;
+    }>;
+    stopProvider(providerId: string): Promise<{
+        success: boolean;
+    }>;
+    listProviderTypes(): Promise<{
+        addonId: string;
+        name: string;
+        description: string;
+        iconUrl: string | null;
+        color: string;
+        instanceMode: "unique" | "multiple";
+        discoveryMode: "auto" | "manual" | "both";
+        existingInstances: {
+            id: string;
+            name: string;
+        }[];
+        canAdd: boolean;
+    }[]>;
+    listDevices(): Promise<{
+        id: string;
+        name: string;
+        providerId: string;
+        type: import("@camstack/types").DeviceType;
+        capabilities: import("@camstack/types").DeviceCapabilityName[];
+        state: import("@camstack/types").DeviceState;
+    }[]>;
+    getDevice(deviceId: string): Promise<{
+        id: string;
+        name: string;
+        providerId: string;
+        type: import("@camstack/types").DeviceType;
+        capabilities: import("@camstack/types").DeviceCapabilityName[];
+        state: import("@camstack/types").DeviceState;
+        metadata: import("@camstack/types").DeviceMetadata;
+    }>;
+    discoverDevices(providerId: string): Promise<import("@camstack/types").DiscoveredDevice[]>;
+    adoptDevice(providerId: string, externalId: string): Promise<import("@camstack/types").IDevice>;
+    createDevice(providerId: string, config: Record<string, unknown>): Promise<import("@camstack/types").IDevice>;
+    /** Returns the URL path for a static asset served by an addon. */
+    getAddonAssetUrl(addonId: string, assetPath: string): string;
+    listAddons(): Promise<{
+        manifest: import("@camstack/types").AddonManifest & {
+            packageName: string;
+            packageVersion: string;
+            packageDisplayName?: string;
+            protected?: boolean;
+            removable?: boolean;
+        };
+        declaration?: import("@camstack/types").AddonDeclaration;
+        hasConfigSchema: boolean;
+        source: "core" | "installed" | "workspace";
+        installSource?: "npm" | "workspace";
+    }[]>;
+    getAddonConfigSchema(addonId: string): Promise<import("@camstack/types").ConfigUISchema | null>;
+    getAddonConfig(addonId: string): Promise<Record<string, unknown>>;
+    updateAddonConfig(addonId: string, config: Record<string, unknown>): Promise<{
+        success: boolean;
+    }>;
+    getAddonLogs(addonId: string, options?: {
+        limit?: number;
+        level?: 'debug' | 'info' | 'warn' | 'error';
+    }): Promise<import("@camstack/types").LogEntry[]>;
+    listKnownFaces(): Promise<{
+        id: string;
+        label: string;
+        group?: string;
+        cropBase64: string;
+        createdAt: number;
+        updatedAt: number;
+        source?: string;
+        metadata?: Readonly<Record<string, unknown>>;
+    }[]>;
+    registerFace(label: string, cropBase64: string, group?: string): Promise<never>;
+    listPipelines(): Promise<{
+        id: string;
+        packageName: string;
+        slot: import("@camstack/types").PipelineSlot | null;
+    }[]>;
+    getPipelineStatus(deviceId: string): Promise<import("@camstack/types").PipelineConfig | null>;
+    listAgents(): Promise<readonly import("@camstack/types").AgentListItem[]>;
+    dispatchTask(agentId: string, task: Record<string, unknown>): Promise<import("@camstack/types").AgentTaskResult>;
+    getProcessTree(): Promise<{
+        id: string;
+        name: string;
+        pid: number;
+        state: "running";
+        cpuPercent: number;
+        memoryPercent: number;
+        memoryMB: number;
+        isHub: boolean;
+        platform: string;
+        arch: string;
+        host: string;
+        capabilities: string[];
+        installedAddons: string[];
+        pythonRuntimes: string[];
+        connectedSince: number;
+        subProcesses: unknown[];
+    }[]>;
+    bridgeListAddons(): Promise<{
+        id: string;
+        packageName: string;
+        slot: import("@camstack/types").PipelineSlot | null;
+    }[]>;
+    bridgeGetPipeline(deviceId: string): Promise<import("@camstack/types").PipelineConfig | null>;
+    bridgeSetPipeline(deviceId: string, config: {
+        video: unknown[];
+        audio?: unknown;
+    }): Promise<{
+        success: boolean;
+    }>;
+    bridgeValidatePipeline(config: {
+        video: unknown[];
+        audio?: unknown;
+    }): Promise<import("@camstack/types").ValidationResult>;
+    bridgeGetAddonConfig(addonId: string): Promise<Record<string, unknown>>;
+    bridgeSetAddonConfig(addonId: string, config: Record<string, unknown>): Promise<{
+        success: boolean;
+    }>;
+    bridgeListPackages(): Promise<import("@camstack/types").InstalledPackage[]>;
+    bridgeListAddonsPackages(): Promise<{
+        manifest: import("@camstack/types").AddonManifest & {
+            packageName: string;
+            packageVersion: string;
+            packageDisplayName?: string;
+            protected?: boolean;
+            removable?: boolean;
+        };
+        declaration?: import("@camstack/types").AddonDeclaration;
+        hasConfigSchema: boolean;
+        source: "core" | "installed" | "workspace";
+        installSource?: "npm" | "workspace";
+    }[]>;
+    bridgeInstallPackage(packageName: string, version?: string): Promise<{
+        success: boolean;
+        loaded: string[];
+        failed: string[];
+    }>;
+    bridgeUninstallPackage(packageName: string): Promise<{
+        success: boolean;
+    }>;
+    getRecordingConfig(deviceId: string): Promise<unknown>;
+    getRecordingPolicy(deviceId: string): Promise<unknown>;
+    getRecordingPolicyStatus(deviceId: string): Promise<{
+        deviceId: string;
+        policyExists: boolean;
+        enabled: any;
+        mode: any;
+        isRecording: boolean;
+    }>;
+    getRecordingSegments(deviceId: string, streamId: string, startTime: number, endTime: number): Promise<unknown>;
+    getEvents(deviceId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<import("@camstack/types").EventQueryResult>;
+    getLogs(options?: {
+        level?: 'debug' | 'info' | 'warn' | 'error';
+        limit?: number;
+        since?: number;
+        until?: number;
+        scope?: string[];
+    }): Promise<import("@camstack/types").LogEntry[]>;
+    replEval(code: string, scope?: {
+        type: 'system';
+    } | {
+        type: 'device';
+        deviceId: string;
+    } | {
+        type: 'provider';
+        providerId: string;
+    } | {
+        type: 'addon';
+        addonId: string;
+    }): Promise<import("@camstack/types").ReplResult>;
+    listUsers(): Promise<Omit<import("@camstack/types").UserRecord, "passwordHash">[]>;
+    createUser(username: string, password: string, role: 'super_admin' | 'admin' | 'viewer'): Promise<{
+        id: string;
+        username: string;
+        role: import("@camstack/types").UserRole;
+        allowedProviders: string[] | "*";
+        allowedDevices: Record<string, string[] | "*">;
+        createdAt: number;
+        updatedAt: number;
+    }>;
+    getTrackingSessions(deviceId?: string): Promise<{
+        trackId: string;
+        deviceId: string;
+        className: string;
+        label: string | undefined;
+        firstSeen: number;
+        lastSeen: number;
+        totalFrames: number;
+        state: string;
+        globalId: string | undefined;
+        positions: readonly {
+            readonly x: number;
+            readonly y: number;
+            readonly t: number;
+        }[];
+        hasEmbedding: boolean;
+        hasCrop: boolean;
+    }[]>;
+    listProcesses(): Promise<(import("@camstack/types").ManagedProcessStatus | {
+        id: string;
+        label: string;
+        state: "running" | "stopped" | "crashed" | "starting";
+        pid?: number;
+        stats?: {
+            pid: number;
+            cpu: number;
+            memory: number;
+            uptime: number;
+            restartCount: number;
+        };
+        restartCount: number;
+        mode: "forked" | "in-process";
+    })[]>;
+    enableProvider(providerId: string): Promise<{
+        success: boolean;
+    }>;
+    disableProvider(providerId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Fetch the UI schema for a single section, or all sections if omitted. */
+    getSettingsSchema(section?: SettingsSection): Promise<{
+        section: "auth" | "features" | "server" | "storage" | "logging" | "addons" | "recording" | "streaming" | "ffmpeg" | "detection" | "backup" | "retention";
+        schema: import("@camstack/types").ConfigUISchema | null;
+        readOnly: boolean;
+        tabs?: undefined;
+        schemas?: undefined;
+    } | {
+        tabs: readonly import("@camstack/types").SettingsTabDef[];
+        schemas: Record<string, unknown>;
+        section?: undefined;
+        schema?: undefined;
+        readOnly?: undefined;
+    }>;
+    getSettings(section: SettingsSection): Promise<{
+        section: "auth" | "features" | "server" | "storage" | "logging" | "addons" | "recording" | "streaming" | "ffmpeg" | "detection" | "backup" | "retention";
+        data: Record<string, unknown>;
+    }>;
+    updateSettings(section: SettingsSection, data: Record<string, unknown>): Promise<{
+        success: boolean;
+        section: "auth" | "features" | "server" | "storage" | "logging" | "addons" | "recording" | "streaming" | "ffmpeg" | "detection" | "backup" | "retention";
+    }>;
+}
+/**
+ * Create a BackendClient instance with the given config.
+ * Convenience factory function.
+ */
+export declare function createBackendClient(config: BackendClientConfig): BackendClient;

package/dist/backend-router.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-export AppRouter type from @camstack/types (pre-generated from server router).
+ * Type-only — no runtime dependency on the backend package.
+ */
+export type { AppRouter as BackendAppRouter } from "@camstack/types";

package/dist/camera.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Camera & PTZ types — shared between CamStack app and proxy.
+ */
+/** Camera source type discriminator. */
+export type CameraSourceType = "scrypted" | "frigate" | "onvif" | "rtsp" | "camstack";
+/** Streaming method. */
+export type StreamMethod = "webrtc" | "mjpeg";
+/** Scrypted-compatible PTZ command. */
+export interface PanTiltZoomCommand {
+    movement?: "Relative" | "Absolute" | "Continuous" | "Home" | "Preset";
+    pan?: number;
+    tilt?: number;
+    zoom?: number;
+    preset?: string;
+    timeout?: number;
+}
+/** PTZ capabilities reported by the device. */
+export interface PanTiltZoomCapabilities {
+    pan?: boolean;
+    tilt?: boolean;
+    zoom?: boolean;
+    presets?: Record<string, string>;
+}
+/** Accessory switch kinds exposed by the Advanced Notifier plugin. */
+export type CameraAccessorySwitchKind = "siren_on_motion" | "siren" | "light_on_motion" | "light" | "pir" | "autotracking";
+/** Extended camera status with accessory switches (from AN plugin). */
+export interface CameraStatusEntry {
+    notificationsEnabled: boolean;
+    isRecording: boolean;
+    isSnapshotsEnabled: boolean;
+    isRebroadcastEnabled: boolean;
+    accessorySwitchStates: Partial<Record<CameraAccessorySwitchKind, boolean>>;
+}
+/** Batch camera status response. */
+export interface CamerasStatusResult {
+    cameras: Record<string, CameraStatusEntry>;
+}

package/dist/detection.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Detection classes — shared between CamStack app and proxy.
+ * Aligned with scrypted-advanced-notifier/src/detectionClasses.ts.
+ */
+export declare enum DetectionClass {
+    Motion = "motion",
+    Person = "person",
+    Vehicle = "vehicle",
+    Animal = "animal",
+    Audio = "audio",
+    Face = "face",
+    Plate = "plate",
+    Package = "package",
+    Doorbell = "doorbell",
+    Sensor = "sensor"
+}
+export declare const animalClasses: string[];
+export declare const personClasses: string[];
+export declare const vehicleClasses: string[];
+export declare const faceClasses: string[];
+export declare const licensePlateClasses: string[];
+export declare const motionClasses: string[];
+export declare const packageClasses: string[];
+export declare const audioClasses: string[];
+/** Common YAMNet audio labels (advanced-notifier). Parent: Audio. */
+export declare const audioLabelClasses: string[];
+export declare const doorbellClasses: string[];
+/** Sensor types (advanced-notifier SupportedSensorType). Parent: Sensor. */
+export declare const sensorLabelClasses: string[];
+export declare const detectionClassesDefaultMap: Record<string, DetectionClass>;
+export declare const isFaceClassname: (c: string) => boolean;
+export declare const isPlateClassname: (c: string) => boolean;
+export declare const isAnimalClassname: (c: string) => boolean;
+export declare const isPersonClassname: (c: string) => boolean;
+export declare const isVehicleClassname: (c: string) => boolean;
+export declare const isMotionClassname: (c: string) => boolean;
+export declare const isDoorbellClassname: (c: string) => boolean;
+export declare const isPackageClassname: (c: string) => boolean;
+export declare const isAudioClassname: (c: string) => boolean;
+export declare const isSensorLabelClassname: (c: string) => boolean;
+export declare const isLabelDetection: (c: string) => boolean;
+export declare const getParentClass: (className: string) => DetectionClass | undefined;
+export declare const getParentDetectionClass: (det: {
+    label?: string;
+    className: string;
+}) => DetectionClass | undefined;
+export declare const defaultDetectionClasses: DetectionClass[];
+/** Default enabled classes: all except Motion. */
+export declare const DEFAULT_ENABLED_CLASSES: (DetectionClass.Person | DetectionClass.Vehicle | DetectionClass.Animal | DetectionClass.Audio | DetectionClass.Face | DetectionClass.Plate | DetectionClass.Package | DetectionClass.Doorbell | DetectionClass.Sensor)[];
+export type TimelineEventPreset = "all" | "important" | "critical" | "custom";
+/** Classes for "critical" preset: security-relevant only (person, doorbell, package). */
+export declare const TIMELINE_PRESET_CRITICAL: string[];
+/** Classes for "important" preset: critical + vehicle, animal, audio, face, plate. */
+export declare const TIMELINE_PRESET_IMPORTANT: string[];
+/** Classes for "all" preset: same as DEFAULT_ENABLED_CLASSES. */
+export declare const TIMELINE_PRESET_ALL: string[];
+/** Get enabled classes for a preset. For "custom", pass customClasses. */
+export declare function getClassesForTimelinePreset(preset: TimelineEventPreset, customClasses?: string[]): string[];

package/dist/devices.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Device types, mappings, and filtering constants — shared between CamStack app and proxy.
+ *
+ * Covers:
+ * - Canonical device type normalization (Scrypted PascalCase + HA domains → canonical)
+ * - Eligible device type lists for Scrypted and Home Assistant
+ * - Unified Device / DeviceCommand / CommandResult interfaces
+ * - AssociatedDeviceState shape
+ */
+export type CanonicalDeviceType = "light" | "switch" | "cover" | "lock" | "alarm" | "button" | "select" | "siren" | "sensor" | "entry" | "media_player" | "script";
+/**
+ * Maps raw device types from Scrypted (PascalCase) and Home Assistant (lowercase domains)
+ * to canonical CamStack device types.
+ */
+export declare const RAW_TO_CANONICAL: Record<string, CanonicalDeviceType>;
+/**
+ * Extended HA domain → type map (includes non-eligible domains for display/categorization).
+ * Superset of RAW_TO_CANONICAL for HA-specific domains.
+ */
+export declare const HA_DOMAIN_TYPE_MAP: Record<string, string>;
+/**
+ * Extended Scrypted type → canonical map (includes non-eligible types for display).
+ * Superset of RAW_TO_CANONICAL for Scrypted-specific types.
+ */
+export declare const SCRYPTED_TYPE_TO_CANONICAL: Record<string, string>;
+/** Normalize raw type (Scrypted or HA) to canonical key for filtering and display. */
+export declare function getCanonicalDeviceType(rawType: string): CanonicalDeviceType | null;
+/** Scrypted device types eligible for device control in CamStack. PascalCase. */
+export declare const ELIGIBLE_SCRYPTED_DEVICE_TYPES: readonly ["Entry", "Light", "Switch", "Lock", "SecuritySystem", "Buttons", "WindowCovering", "Siren", "Sensor", "Select", "Program"];
+/** Set version for O(1) lookup. */
+export declare const ELIGIBLE_SCRYPTED_DEVICE_TYPES_SET: Set<string>;
+/** Home Assistant domains eligible for device control in CamStack. */
+export declare const ELIGIBLE_HA_DOMAINS: readonly ["light", "switch", "input_boolean", "cover", "lock", "alarm_control_panel", "input_button", "button", "input_select", "select", "siren", "media_player", "script"];
+/** Set version for O(1) lookup. */
+export declare const ELIGIBLE_HA_DOMAINS_SET: Set<string>;
+/** All device command actions supported by CamStack. */
+export type DeviceCommandAction = "turnOn" | "turnOff" | "openEntry" | "closeEntry" | "stopEntry" | "lock" | "unlock" | "disarm" | "arm" | "pressButton" | "selectOption" | "volumeUp" | "volumeDown" | "volumeMute";
+/**
+ * State snapshot shape for an associated device.
+ * Used by both app (AssociatedDeviceStateSnapshot) and proxy (Device.state).
+ */
+export interface AssociatedDeviceState {
+    name?: string;
+    type?: string;
+    interfaces?: string[];
+    on?: boolean;
+    hasBrightnessControl?: boolean;
+    brightness?: number;
+    lockState?: string;
+    securitySystemState?: {
+        mode?: string;
+        supportedModes?: string[];
+    };
+    buttons?: string[];
+    entryOpen?: boolean | "jammed";
+    value?: string;
+    options?: string[];
+    volumeLevel?: number;
+    isVolumeMuted?: boolean;
+    coverSupportsStop?: boolean;
+    coverPosition?: number;
+}
+/** A device from an automation system (Scrypted, Home Assistant, etc.). */
+export interface Device {
+    id: string;
+    name: string;
+    /**
+     * Canonical device type (lowercase): "light", "switch", "cover", "lock",
+     * "alarm", "button", "select", "siren", "sensor", "entry", "media_player",
+     * "script", "camera", "nvr".
+     */
+    type: string;
+    /** Original type from the source system (e.g. Scrypted "WindowCovering", HA domain "cover"). */
+    rawType?: string;
+    /** Provider that owns this device. */
+    providerId?: string;
+    model?: string;
+    manufacturer?: string;
+    firmware?: string;
+    online: boolean;
+    interfaces: string[];
+    /** Current state (key-value pairs, device-type-dependent). See AssociatedDeviceState. */
+    state: Record<string, unknown>;
+    /** Available actions for this device (defined by the provider). */
+    actions?: DeviceAction[];
+    /** Child devices (e.g. NVR → camera channels). */
+    children?: Device[];
+}
+/** A command to send to a device. */
+export interface DeviceCommand {
+    deviceId: string;
+    command: string;
+    params?: Record<string, unknown>;
+}
+/** Result of a command execution. */
+export interface CommandResult {
+    success: boolean;
+    error?: string;
+    state?: Record<string, unknown>;
+}
+/** Device source type (integration that provides the device). */
+export type AssociatedDeviceSource = "scrypted" | "ha";
+/** Eligible device summary (for device picker UI). */
+export interface EligibleDevice {
+    id: string;
+    name: string;
+    type: string;
+    source: AssociatedDeviceSource;
+}
+/**
+ * An action that can be performed on a device.
+ * Actions are declared by the provider and rendered dynamically in the UI.
+ */
+export interface DeviceAction {
+    /** Unique action ID (e.g. "toggle", "setBrightness", "ptzMove", "reboot"). */
+    id: string;
+    /** Display label (e.g. "Toggle", "Set Brightness", "Move Camera"). */
+    label: string;
+    /** Action category for UI grouping. */
+    category?: "power" | "control" | "ptz" | "media" | "system" | "custom";
+    /** Icon hint (lucide icon name or emoji). */
+    icon?: string;
+    /** Parameters this action accepts. */
+    params?: DeviceActionParam[];
+    /** Whether this action is destructive (shown with warning). */
+    destructive?: boolean;
+}
+/** A parameter for a device action. */
+export interface DeviceActionParam {
+    /** Parameter key. */
+    key: string;
+    /** Display label. */
+    label: string;
+    /** Type for UI rendering. */
+    type: "boolean" | "number" | "string" | "select" | "slider";
+    /** Default value. */
+    default?: unknown;
+    /** For select type: available options. */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    /** For slider/number: min/max/step. */
+    min?: number;
+    max?: number;
+    step?: number;
+}

package/dist/features.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Feature capability matrix — shared between CamStack app and proxy.
+ *
+ * Maps each app feature to:
+ * - Which source types (Frigate, Scrypted, RTSP) support it
+ * - Which platforms (iOS, Android, Web, Scrypted embed) it works on
+ * - Whether the camstack-server backend is required
+ * - The ICameraSource method that enables the feature
+ */
+export type FeatureId = "liveStream" | "multiResolution" | "motion" | "objectDetection" | "audioVolume" | "audioVolumes" | "ptz" | "intercom" | "deviceStatus" | "timeline" | "clusteredTimeline" | "detectionClasses" | "videoClips" | "nvrPlayback" | "nvrScrub" | "recordingThumbnail" | "nvrSeekToLive";
+export type PlatformId = "ios" | "android" | "web" | "scryptedEmbed";
+export type SourceType = "frigate" | "scrypted" | "rtsp";
+export interface FeatureEntry {
+    id: FeatureId;
+    label: string;
+    /** Which source types support this feature. */
+    sources: Partial<Record<SourceType, boolean>>;
+    /** Platform availability overrides. When omitted, all platforms are supported. */
+    platforms?: Partial<Record<PlatformId, boolean>>;
+    /** True when this feature needs the camstack-server backend. */
+    requiresBackend?: boolean;
+    /** The ICameraSource method name that enables this feature at runtime. */
+    adapterMethod?: string;
+}
+export declare const FEATURE_MATRIX: FeatureEntry[];
+/** Check if a feature is available for a given source type and platform. */
+export declare function isFeatureAvailable(featureId: FeatureId, source: SourceType, platform: PlatformId): boolean;
+/** Get all features supported by a source type. */
+export declare function getSourceFeatures(source: SourceType): FeatureEntry[];
+/** Get all features that require the backend proxy. */
+export declare function getBackendRequiredFeatures(): FeatureEntry[];

package/dist/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/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/sdk",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -23,7 +23,11 @@
   "dependencies": {
     "superjson": "^2.2.6"
   },
+  "peerDependencies": {
+    "@camstack/types": "^0.1.0"
+  },
   "devDependencies": {
+    "@camstack/types": "*",
     "@trpc/client": "^11.16.0",
     "@trpc/server": "^11.16.0",
     "@types/node": "^22.19.13",