@camstack/sdk 0.1.23 → 0.1.24

package/dist/sdk/src/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/sdk/src/backend-client.d.ts

@@ -0,0 +1,306 @@
+/**
+ * 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";
+    }[]>;
+    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<{
+        id: string;
+        packageName: string;
+        slot: import("@camstack/types").PipelineSlot | null;
+    }[]>;
+    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/sdk/src/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/sdk/src/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/sdk/src/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/sdk/src/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/sdk/src/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[];