@camstack/sdk 0.1.35 → 0.1.37

package/dist/nvr.d.ts

@@ -4,20 +4,8 @@
  * 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;
-}
+import type { StreamSourceEntry } from '@camstack/types';
+export type { StreamSourceEntry };
 export interface NvrCamera {
     name: string;
     /** Display label (may differ from internal name). */
@@ -27,8 +15,8 @@ export interface NvrCamera {
     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[];
+    /** Available streaming options. */
+    streamOptions: StreamSourceEntry[];
     /** Accessories/actions available on this camera (siren, floodlight, PTZ, etc.). */
     accessories?: CameraAccessory[];
 }
@@ -282,4 +270,3 @@ export interface ProviderConfigs {
     }>;
     enabledDetectionSources?: string[];
 }
-export {};

package/dist/system.d.ts

@@ -0,0 +1,297 @@
+/**
+ * System — single, unified entry point for the camstack client API.
+ *
+ * Devices are returned as typed `DeviceProxy` objects (auto-injecting
+ * `deviceId` + `nodeId`), system caps are exposed as typed namespaces
+ * (`system.userManagement`, `system.storage`, etc.), and live events
+ * flow through a single `subscribeEvent` helper.
+ *
+ * The escape hatches (`trpcClient`, `wsClient`) are still public so the
+ * ui-library Provider can seed React Query with the same WS connection
+ * — a future phase will narrow the surface further.
+ */
+import { createWSClient, type TRPCClient } from '@trpc/client';
+import type { DeviceProxy, DeviceQueryFilters, DeviceLifecycleListener, SystemProxy } from '@camstack/types';
+import type { BackendAppRouter } from './backend-router.js';
+import type { BackendConnectionState } from './types.js';
+/**
+ * Canonical user-info shape returned by `getMe()`. Mirrors the server's
+ * `auth.me` output — kept narrow so SDK consumers don't need the full
+ * tRPC inference chain to type a login flow.
+ */
+export interface UserInfo {
+    readonly id: string;
+    readonly username: string;
+    readonly role: string;
+    readonly permissions?: {
+        readonly allowedAddons?: ReadonlyArray<string> | '*';
+        readonly allowedDevices?: Readonly<Record<string, ReadonlyArray<string> | '*'>>;
+    };
+}
+export interface SystemConfig {
+    /** Backend server URL (e.g. "http://localhost:4443"). */
+    readonly serverUrl: string;
+    /** JWT token for authentication. */
+    readonly token?: string;
+    /** Use WebSocket transport (default: true in browser, false in Node). */
+    readonly useWebSocket?: boolean;
+    /** Optional per-event connection-state callback. */
+    readonly onConnectionChange?: (state: BackendConnectionState) => void;
+    /** Initial WS reconnect delay in ms (default 2000, capped via maxRetryDelayMs). */
+    readonly retryDelayMs?: number;
+    /** Max WS reconnect delay in ms (default 30_000). */
+    readonly maxRetryDelayMs?: number;
+}
+type ConnectionListener = (state: BackendConnectionState, version: number) => void;
+export interface SystemLiveEvent<TData = unknown> {
+    readonly id: string;
+    readonly timestamp: Date | string;
+    readonly source: {
+        readonly type: string;
+        readonly id: string | number;
+    };
+    readonly category: string;
+    readonly data: TData;
+}
+export type SystemLiveEventListener<TData = unknown> = (event: SystemLiveEvent<TData>) => void;
+type TrpcClient = TRPCClient<BackendAppRouter>;
+type TrpcWsClient = ReturnType<typeof createWSClient>;
+export declare class System {
+    /** Active server base URL. Mutable via `switchServerUrl()` so the
+     *  endpoint-race helper can pivot the transport onto a LAN candidate
+     *  after the initial public-URL bootstrap. */
+    private _serverUrl;
+    private readonly useWs;
+    private readonly baseRetryMs;
+    private readonly maxRetryMs;
+    private readonly onConnectionChange;
+    private token;
+    private _trpcClient;
+    private _wsClient;
+    private mirror;
+    private mirrorInit;
+    private connected;
+    private connectedPromise;
+    private _systemProxy;
+    private _connectionVersion;
+    private readonly connectionListeners;
+    constructor(config: SystemConfig);
+    /** Active server base URL (no trailing slash). */
+    get serverUrl(): string;
+    get connectionVersion(): number;
+    /**
+     * Subscribe to connection-state transitions. Called with `('connected'
+     * | 'disconnected' | 'connecting', version)` whenever the SDK opens,
+     * closes, or starts a manual reconnect. Listener errors are swallowed
+     * so a misbehaving consumer cannot break the SDK's event loop.
+     */
+    subscribeConnectionEvents(cb: ConnectionListener): () => void;
+    private emitConnectionEvent;
+    /**
+     * Wait until the underlying tRPC transport is connected AND the
+     * server has responded to a cheap auth round-trip (`auth.me`). This
+     * is the canonical "ready to issue queries" gate.
+     *
+     * Why a probe, not just `ws.readyState === OPEN`?
+     *   The WS handshake completes asynchronously: tRPC's `wsLink`
+     *   queues outgoing messages and only flushes them after `open()`
+     *   resolves (post `connectionParams` send). On the server, the
+     *   tRPC context is created lazily once the connectionParams
+     *   message is received. A query fired between WS-open and
+     *   connection-params-processed is technically queued by tRPC, but
+     *   the auth context for that query is only resolved once the
+     *   handshake message is decoded server-side. A probe round-trip is
+     *   the safest way to confirm both sides have agreed on the auth
+     *   identity before the React tree starts firing parallel queries
+     *   (which can otherwise land before any addon-side service
+     *   discovery has settled, returning empty results that get cached).
+     *
+     * Idempotent — concurrent callers await the same in-flight Promise.
+     * Bounded by `timeoutMs` (default 15s) — beyond which a
+     * `Error('System.awaitConnected: probe timed out after Xms')` is
+     * thrown so the host can render a clear error state instead of
+     * hanging on a bricked socket.
+     */
+    awaitConnected(timeoutMs?: number): Promise<void>;
+    /**
+     * Warm-boot the device mirror. Awaits the transport probe first
+     * (`awaitConnected`) so the three mirror round-trips
+     * (`getAllBindings` + `getAllSnapshots` + `listAll`) cannot race
+     * against the WS auth handshake. Subsequent `getDevice(id)` calls
+     * are sync; live `device.*` event subscriptions keep the caches
+     * fresh.
+     *
+     * Idempotent — concurrent callers await the same in-flight Promise.
+     */
+    init(timeoutMs?: number): Promise<void>;
+    /** Promise that resolves once `init()` has completed. */
+    awaitReady(): Promise<void>;
+    /** True after `init()` resolves. */
+    isReady(): boolean;
+    /** True after the transport probe has succeeded at least once. */
+    isConnected(): boolean;
+    /**
+     * Force a fresh WebSocket handshake. Tears down the wsClient + tRPC
+     * client + mirror (the mirror captures the tRPC reference at
+     * construction time and would otherwise dispatch through a closed
+     * client) and rebuilds them. No-op for HTTP transport.
+     */
+    reconnect(): void;
+    /**
+     * Pivot the underlying tRPC transport onto a different base URL.
+     * Used by the endpoint-race flow: the SDK opens against the public
+     * URL the operator provided, calls `localNetwork.getConnectionEndpoints`
+     * to discover LAN candidates, races them, and (when a faster one wins)
+     * calls `switchServerUrl(winner)` to migrate every subsequent query
+     * onto the LAN path without losing auth state.
+     *
+     * Keeps the auth token. Tears down the WS + mirror and rebuilds them
+     * against the new URL — same machinery as `reconnect()` but with a
+     * different target.
+     */
+    switchServerUrl(nextUrl: string): void;
+    /**
+     * Race the candidate base URLs reported by the hub's `local-network`
+     * cap, pick the fastest one that responds, and (if it's different
+     * from the current URL) pivot the transport onto it.
+     *
+     * Flow:
+     *   1. Query `localNetwork.getConnectionEndpoints({ port })` over the
+     *      already-authenticated tRPC channel — the cap is auth-gated,
+     *      so the LAN IPs never leak to anonymous callers.
+     *   2. For each candidate, fire a HEAD on `{baseUrl}/trpc/health`
+     *      with a short timeout (default 1500ms). The first 2xx wins.
+     *   3. If the winner differs from `this.serverUrl`, call
+     *      `switchServerUrl(winner)` and return it. Otherwise return
+     *      the current URL unchanged.
+     *
+     * Bounded — if every candidate times out we keep the current URL.
+     * Idempotent — safe to call on every connect / reconnect / network
+     * change event.
+     */
+    raceConnectionEndpoints(options?: {
+        /** Per-candidate probe timeout. Default 1500ms. */
+        readonly perCandidateTimeoutMs?: number;
+        /** Skip IPv6 candidates. Default `false`. */
+        readonly ipv4Only?: boolean;
+    }): Promise<{
+        winner: string;
+        switched: boolean;
+    }>;
+    /** Tear down WS connection + mirror. The instance is unusable afterwards. */
+    close(): void;
+    private disposeMirror;
+    login(username: string, password: string): Promise<{
+        token: string;
+    }>;
+    logout(): Promise<void>;
+    getMe(): Promise<UserInfo>;
+    /** Update the auth token (e.g. after login or token refresh). */
+    setToken(token: string): void;
+    /**
+     * Synchronous snapshot of every device matching the optional filters.
+     * Backed by the `SystemMirror` warm-boot cache — call `init()` first
+     * (or `awaitReady()`) before invoking. Returns an empty array if the
+     * mirror has not yet been booted.
+     *
+     * Each returned proxy has `binding` populated from the mirror's
+     * binding cache (Phase 5 dedup), so consumers no longer need to
+     * make a separate `deviceManager.getBindings` round-trip.
+     */
+    listDevices(filters?: DeviceQueryFilters): readonly DeviceProxy[];
+    /**
+     * Sync lookup by numeric id. `null` if the mirror has not been booted
+     * or the device is unknown.
+     */
+    getDevice(deviceId: number): DeviceProxy | null;
+    /** Sync lookup by display name (exact match). */
+    getDeviceByName(name: string): DeviceProxy | null;
+    /** Sync lookup by stableId. */
+    getDeviceByStableId(stableId: string): DeviceProxy | null;
+    /**
+     * Resolve when a device with `deviceId` becomes available. Resolves
+     * immediately if already known; rejects with a timeout error
+     * otherwise (default 30s).
+     */
+    waitForDevice(deviceId: number, timeoutMs?: number): Promise<DeviceProxy>;
+    /** Subscribe to `device.registered` events. */
+    onDeviceAdded(cb: DeviceLifecycleListener): () => void;
+    /** Subscribe to `device.unregistered` events. */
+    onDeviceRemoved(cb: DeviceLifecycleListener): () => void;
+    /**
+     * Patch the proxy's `binding` field from the mirror's cache. The
+     * generated `createDeviceProxy()` already sets `binding` to the
+     * binding it was constructed with — this is a defensive overwrite
+     * that uses the latest cached entry in case a `binding-changed`
+     * event landed between proxy creation and access.
+     */
+    private attachBinding;
+    /** Fetch the latest cached binding from the mirror, or `null`. */
+    private lookupBinding;
+    get addonPages(): SystemProxy['addonPages'];
+    get addonSettings(): SystemProxy['addonSettings'];
+    get alerts(): SystemProxy['alerts'];
+    get audioAnalyzer(): SystemProxy['audioAnalyzer'];
+    get audioCodec(): SystemProxy['audioCodec'];
+    get backup(): SystemProxy['backup'];
+    get decoder(): SystemProxy['decoder'];
+    get deviceManager(): SystemProxy['deviceManager'];
+    get deviceProvider(): SystemProxy['deviceProvider'];
+    get deviceState(): SystemProxy['deviceState'];
+    get metricsProvider(): SystemProxy['metricsProvider'];
+    get notificationOutput(): SystemProxy['notificationOutput'];
+    get pipelineExecutor(): SystemProxy['pipelineExecutor'];
+    get pipelineOrchestrator(): SystemProxy['pipelineOrchestrator'];
+    get pipelineRunner(): SystemProxy['pipelineRunner'];
+    get platformProbe(): SystemProxy['platformProbe'];
+    get recordingEngine(): SystemProxy['recordingEngine'];
+    get settingsStore(): SystemProxy['settingsStore'];
+    get storage(): SystemProxy['storage'];
+    get streamBroker(): SystemProxy['streamBroker'];
+    get turnProvider(): SystemProxy['turnProvider'];
+    get userManagement(): SystemProxy['userManagement'];
+    /**
+     * Subscribe to a single event category. Returns an unsubscribe
+     * handle. Errors thrown by the listener are swallowed so a single
+     * misbehaving consumer cannot tear down the WS subscription.
+     *
+     * Categories should be values from the `EventCategory` enum
+     * (`@camstack/types`) — passing a raw string works for forward-compat
+     * but loses type safety. The SDK forwards the value verbatim to the
+     * server's `live.onEvent` subscription.
+     */
+    subscribeEvent<TData = unknown>(category: string, cb: SystemLiveEventListener<TData>): () => void;
+    /** Direct tRPC client. Read once per call; rebuilt on `reconnect()`. */
+    get trpcClient(): TrpcClient;
+    /**
+     * Underlying WSClient (or `null` for HTTP transport). Used by
+     * advanced consumers that need direct access to the WebSocket
+     * (e.g. for keep-alive metrics). Rebuilt on `reconnect()`.
+     */
+    get wsClient(): TrpcWsClient | null;
+    private buildTrpcClient;
+}
+/** Create a `System` instance. Convenience factory. */
+export declare function createSystem(config: SystemConfig): System;
+/**
+ * Race a list of candidate base URLs and return the first one that
+ * responds to `GET {baseUrl}/trpc/health` with a 2xx within
+ * `timeoutMs`. Returns `null` if every candidate fails / times out.
+ *
+ * Implementation notes:
+ *   - Uses `fetch` with `AbortController` for per-candidate cutoff so a
+ *     stalled candidate doesn't pin the wallclock for the whole race.
+ *   - Cancels every still-pending probe as soon as the first one
+ *     succeeds — no wasted bandwidth on the loser candidates.
+ *   - `/trpc/health` is the only endpoint guaranteed to respond on every
+ *     CamStack deployment (registered alongside the tRPC plugin). It is
+ *     intentionally NOT auth-gated since it's used by load balancers /
+ *     uptime probes — same surface every reverse proxy already monitors.
+ *   - HEAD would be nicer but Cloudflare Tunnel + some browsers
+ *     mishandle HEAD on the ingress path; GET is safer.
+ *
+ * Exported so non-System callers (CLI helpers, tests) can race their
+ * own candidate lists without instantiating a full System.
+ */
+export declare function raceFastestEndpoint(candidates: ReadonlyArray<string>, timeoutMs: number): Promise<string | null>;
+export {};

package/dist/timeline.d.ts

@@ -167,11 +167,3 @@ 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

@@ -32,13 +32,6 @@ export interface DirectClientConfig {
     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 BackendConnectionState = 'connected' | 'disconnected' | 'connecting';
 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.35",
+  "version": "0.1.37",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup && tsc -p tsconfig.build.json",
+    "build": "vite build && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "publish": "npm publish --access public"
   },
@@ -32,6 +32,7 @@
     "@trpc/server": "^11.16.0",
     "@types/node": "^22.19.13",
     "tsup": "^8.5.1",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "zod": "^4.3.6"
   }
 }