@camstack/types 0.1.14 → 0.1.16

package/dist/device/device-runtime-state.d.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+/**
+ * Per-device runtime state — cap-keyed. Mutable signals discovered
+ * after boot live here, separate from `DeviceConfig` (operator
+ * intent) and from `deviceCache` (immutable autodetect / abilities).
+ *
+ * Shape: `Record<capName, capStateSlice>`. Each slice's schema is
+ * declared by the capability itself (`CapabilityDefinition.runtimeState`)
+ * so that any provider implementing the cap inherits the same shape —
+ * the BatteryStatus shape a Reolink cam emits is the same a Frigate or
+ * ONVIF cam emits, no driver-specific re-declaration.
+ *
+ * Schemas are registered DYNAMICALLY as the device's caps are
+ * installed (see `BaseDevice.registerNativeCap`). A slice without a
+ * registered schema is rejected on write — the cap must be wired
+ * first. Reads return `undefined` for unknown slices.
+ *
+ * Persistence: only registered slices round-trip to disk. The kernel
+ * layer debounces writes; explicit `flush()` awaits in-flight saves
+ * (used by the shutdown hook).
+ */
+export interface IDeviceRuntimeState {
+    /**
+     * Read the slice for `capName`. Three overloads, picked by
+     * argument shape:
+     *
+     *   1. Pass a known cap-name literal (`'battery'`, `'motion'`, …)
+     *      → return type is auto-inferred from
+     *      `CapNameToRuntimeStateMap` (codegen output). No generic
+     *      argument, no `as`-cast.
+     *   2. Pass a cap-name with an explicit generic
+     *      (`getCapState<MyShape>('custom-cap')`) → return that
+     *      shape. Used for caps the codegen doesn't see (test-only,
+     *      addon-private).
+     *   3. Pass a cap-name with no generic (default `Record<string,
+     *      unknown>`) → permissive untyped fallback.
+     *
+     * Returns `undefined` if no slice has been written yet.
+     */
+    getCapState<K extends keyof import('../generated/device-local-state.js').CapNameToRuntimeStateMap>(capName: K): Readonly<import('../generated/device-local-state.js').CapNameToRuntimeStateMap[K]> | undefined;
+    getCapState<T extends Record<string, unknown> = Record<string, unknown>>(capName: string): Readonly<T> | undefined;
+    /** Read a single key inside a slice. Convenience for the common
+     *  case of reading a primitive (`battery.percentage`). */
+    getCapField(capName: string, key: string): unknown;
+    /**
+     * Replace the slice for `capName`. The schema bound to `capName`
+     * (via `installCapSchema`) validates `value`; throws on mismatch.
+     * Listeners fire synchronously after the write applies.
+     */
+    setCapState(capName: string, value: Record<string, unknown>): void;
+    /**
+     * Shallow-merge `partial` into the current slice for `capName`.
+     * Re-validates the merged result against the cap's schema.
+     */
+    patchCapState(capName: string, partial: Record<string, unknown>): void;
+    /** Subscribe to ALL state changes. Receives the cap names whose
+     *  slices changed and the full snapshot. */
+    subscribe(cb: (changedCaps: ReadonlyArray<string>, snapshot: Snapshot) => void): () => void;
+    /** Subscribe to a single cap's slice changes. Fires only when that
+     *  cap's slice is touched; ignores writes against other caps. */
+    subscribeCap<T extends Record<string, unknown> = Record<string, unknown>>(capName: string, cb: (slice: Readonly<T> | undefined) => void): () => void;
+    /** Frozen snapshot of every cap's slice. Cap names without a
+     *  written slice are omitted (sparse). */
+    snapshot(): Snapshot;
+    /** Flush any pending debounced disk writes. */
+    flush(): Promise<void>;
+    /**
+     * Register a cap's runtime-state schema. Called by the kernel
+     * when `ctx.registerNativeCap(cap, …)` runs and `cap.runtimeState`
+     * is defined. Idempotent — repeat installs with the same schema
+     * are no-ops; mismatched schemas throw to surface a config bug.
+     *
+     * Lazily validates any existing in-memory slice for `capName` so
+     * a slice loaded from disk before the cap was wired is checked
+     * the moment the cap shows up.
+     */
+    installCapSchema(capName: string, schema: z.ZodObject<z.core.$ZodLooseShape>): void;
+}
+export type Snapshot = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+/**
+ * Concrete implementation. Routes every successful write through
+ * `writer(capName, slice)` — the kernel hooks this up to
+ * `device-state.setCapSlice`, the canonical cross-layer write
+ * entrypoint, which handles disk persistence (debounced on the hub)
+ * and mirror updates.
+ *
+ * Schema validation runs in-process before the writer is called —
+ * the round-trip should never carry an invalid slice. `flush()`
+ * awaits any in-flight writer promises so shutdown is lossless.
+ *
+ * `initial` is the persisted blob loaded at boot. Slices for caps
+ * whose schema hasn't been installed yet are kept in-memory verbatim
+ * and validated when the cap registers later.
+ */
+export declare class DeviceRuntimeState implements IDeviceRuntimeState {
+    private readonly writer;
+    /** In-flight writer promises tracked so `flush()` can await them. */
+    private readonly pendingWrites;
+    /** Per-cap committed slice — after schema validation when known. */
+    private slices;
+    /** Per-cap registered schema (set by `installCapSchema`). */
+    private readonly schemas;
+    private readonly listeners;
+    private readonly capListeners;
+    private constructor();
+    static fromInitial(initial: Record<string, unknown>, writer: (capName: string, slice: Record<string, unknown>) => Promise<void>): DeviceRuntimeState;
+    installCapSchema(capName: string, schema: z.ZodObject<z.core.$ZodLooseShape>): void;
+    getCapState<T extends Record<string, unknown> = Record<string, unknown>>(capName: string): Readonly<T> | undefined;
+    getCapField(capName: string, key: string): unknown;
+    setCapState(capName: string, value: Record<string, unknown>): void;
+    patchCapState(capName: string, partial: Record<string, unknown>): void;
+    /**
+     * Internal worker. `merge` controls whether `value` replaces or
+     * shallow-merges into the existing slice. Schema validation runs
+     * on the FINAL composed object regardless.
+     */
+    private applyCapWrite;
+    private fireListeners;
+    subscribe(cb: (changed: ReadonlyArray<string>, snap: Snapshot) => void): () => void;
+    subscribeCap<T extends Record<string, unknown> = Record<string, unknown>>(capName: string, cb: (slice: Readonly<T> | undefined) => void): () => void;
+    snapshot(): Snapshot;
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=device-runtime-state.d.ts.map

package/dist/device/device-runtime-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-runtime-state.d.ts","sourceRoot":"","sources":["../../src/device/device-runtime-state.ts"],"names":[],"mappings":"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"}

package/dist/device/device-state-handle.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Reactive read handle for one cap-keyed slice of a device's
+ * runtime state. Returned by `createDeviceProxy(...).state[capName]`.
+ *
+ * Three pieces:
+ *   - `value`: last-known slice. `undefined` until something has
+ *     populated it (an active subscription, an explicit `refresh()`,
+ *     or — in the case of the SystemManager mirror source — a
+ *     warm-boot `getAllSnapshots` payload). Read sync.
+ *   - `refresh()`: one-shot pull from the underlying source. For
+ *     the lazy tRPC source this is `deviceState.getCapSlice`; for
+ *     the SystemManager mirror it's a no-op (the mirror is push-only).
+ *   - `subscribe(cb)`: hooks into the source's notification channel,
+ *     filtered by `(deviceId, capName)`. Refcounted — the underlying
+ *     subscription closes when the last caller unsubscribes.
+ *
+ * Cross-environment: the same API works in browser (admin-ui via the
+ * tRPC client) and on the server (in-process AddonApi). The transport
+ * is whatever the supplied source exposes.
+ */
+export interface SliceHandle<T> {
+    /** Latest cached slice. Reflects the most recent `refresh()` or
+     *  push event. `undefined` if neither has happened. */
+    readonly value: T | undefined;
+    /** Force a re-fetch from the hub mirror. Updates `value` + notifies
+     *  every active subscriber. No-op for the SystemManager mirror
+     *  source (it's already push-driven). */
+    refresh(): Promise<void>;
+    /** Subscribe to slice changes. Returns the unsubscribe fn.
+     *  Auto-fires the callback once with the current value (or
+     *  `undefined`) so the caller sees a snapshot immediately. */
+    subscribe(cb: (slice: T | undefined) => void): () => void;
+    /**
+     * Replace the slice on the hub. Routes through
+     * `device-state.setCapSlice` — the canonical cross-layer write
+     * entrypoint. The local mirror updates via the `onChanged` event
+     * (round-trip), so callers should treat the write as eventually
+     * consistent and read the new value via `subscribe` rather than
+     * synchronously after `await`.
+     */
+    set(slice: T): Promise<void>;
+    /**
+     * Shallow-merge `partial` into the current slice on the hub.
+     * Implemented as read-modify-write client-side: pulls `value`
+     * (or refreshes), merges, calls `set()`. Single-writer
+     * conventions on each cap make atomic-merge semantics
+     * unnecessary — concurrent patches on the same slice from
+     * different processes are undefined and should be avoided.
+     */
+    patch(partial: Partial<T>): Promise<void>;
+}
+/**
+ * Minimal tRPC API surface used by the lazy source. Both `AddonApi`
+ * (server) and the tRPC client proxy (browser) satisfy it structurally
+ * — we don't import either to avoid pulling them in from a leaf type
+ * module.
+ */
+export interface SliceHandleApi {
+    readonly deviceState: {
+        readonly getCapSlice: {
+            query(input: {
+                deviceId: number;
+                capName: string;
+            }): Promise<Record<string, unknown> | null>;
+        };
+        readonly setCapSlice: {
+            mutate(input: {
+                deviceId: number;
+                capName: string;
+                slice: Record<string, unknown>;
+            }): Promise<void>;
+        };
+    };
+    readonly live?: {
+        readonly onEvent: {
+            subscribe(input: {
+                category: string;
+            }, opts: {
+                onData: (evt: {
+                    data: unknown;
+                }) => void;
+                onError?: (err: unknown) => void;
+            }): {
+                unsubscribe: () => void;
+            };
+        };
+    };
+}
+/**
+ * Pluggable state-source contract. `createSliceHandle` is now a thin
+ * adapter over this interface — every implementation produces an
+ * identical `SliceHandle<T>` shape. Two impls today:
+ *
+ *   - `createLazyTrpcSource(api)`: per-handle local cache, refresh
+ *     via `deviceState.getCapSlice`, subscribe via `live.onEvent`.
+ *     Default behavior, used by `createDeviceProxy(api, binding)`
+ *     when no source is passed.
+ *   - `createMirrorSource(mirror, listeners)`: reads from a shared
+ *     `Map<deviceId, Map<capName, slice>>` populated by a
+ *     `SystemManager` warm-boot. Refresh is a no-op; subscribe
+ *     registers in a shared listener set that the SystemManager
+ *     fans out to on every push event.
+ *
+ * Both produce the same `SliceHandle<T>` API; consumers don't see
+ * which source is behind the handle.
+ */
+export interface SliceHandleSource {
+    /** Sync read of the last-known slice for `(deviceId, capName)`. */
+    read(deviceId: number, capName: string): unknown | undefined;
+    /** Force a re-fetch (where applicable). No-op when the source is
+     *  push-only (e.g. the SystemManager mirror). */
+    refresh(deviceId: number, capName: string): Promise<void>;
+    /** Register a listener for slice changes. Returns the unsubscribe
+     *  fn. Implementations should fan out the latest cached slice to
+     *  the callback synchronously when seeding is desired (the handle
+     *  always seeds via a separate `cb(read(...))` call). */
+    watch(deviceId: number, capName: string, cb: (slice: unknown | undefined) => void): () => void;
+    /** Write the slice for `(deviceId, capName)` to the hub via the
+     *  canonical `device-state.setCapSlice` entrypoint. Throws if the
+     *  source has no write transport (e.g. a mirror source built
+     *  without an api reference). */
+    write(deviceId: number, capName: string, slice: Record<string, unknown>): Promise<void>;
+}
+/**
+ * Lazy tRPC source — the default behavior. Maintains a per-key local
+ * cache (`{deviceId}:{capName}` → last slice), one shared
+ * `live.onEvent` bridge that fans out into the listener map, and
+ * `refresh` round-trips through `deviceState.getCapSlice`.
+ *
+ * The bridge is opened on first `watch()` and closed when the last
+ * watcher unsubscribes — keeps idle handles cheap.
+ */
+export declare function createLazyTrpcSource(api: SliceHandleApi): SliceHandleSource;
+/**
+ * Mirror source — reads from a shared map populated by a
+ * `SystemManager` warm-boot + push event handler. Refresh is a no-op
+ * (the SystemManager owns the update loop). `watch()` registers in a
+ * shared listener set — the SystemManager calls these from its single
+ * `device.state-changed` subscription.
+ *
+ * The mirror map and listener map are passed in by reference so the
+ * SystemManager can mutate both as events arrive.
+ */
+export declare function createMirrorSource(mirror: ReadonlyMap<number, ReadonlyMap<string, unknown>>, listeners: Map<string, Set<(slice: unknown | undefined) => void>>, api?: SliceHandleApi): SliceHandleSource;
+/**
+ * Build a `SliceHandle<T>` bound to `(deviceId, capName)`. Caller
+ * provides the type parameter — codegen passes
+ * `InferRuntimeState<typeof <cap>>` so consumers see the cap's typed
+ * shape:
+ *
+ *   const dev = createDeviceProxy(api, binding)
+ *   dev.state.battery.value           // BatteryStatus | undefined
+ *   dev.state.battery.value?.percentage
+ *
+ * Two-arg form (deprecated path, kept for spec compatibility):
+ * passes the api directly, builds a per-handle lazy source. New
+ * code should pre-build a single source and reuse it across handles
+ * via the explicit `source` form.
+ */
+export declare function createSliceHandle<T>(source: SliceHandleSource | SliceHandleApi, deviceId: number, capName: string): SliceHandle<T>;
+//# sourceMappingURL=device-state-handle.d.ts.map

package/dist/device/device-state-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-state-handle.d.ts","sourceRoot":"","sources":["../../src/device/device-state-handle.ts"],"names":[],"mappings":"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"}

package/dist/device/device-type.d.ts

@@ -0,0 +1,68 @@
+export declare enum DeviceType {
+    Camera = "camera",
+    Hub = "hub",
+    Light = "light",
+    Siren = "siren",
+    Switch = "switch",
+    Sensor = "sensor",
+    Thermostat = "thermostat",
+    Button = "button",
+    Generic = "generic"
+}
+export declare enum DeviceFeature {
+    BatteryOperated = "battery-operated",
+    Rebootable = "rebootable",
+    NativeSnapshot = "native-snapshot",
+    DoorbellButton = "doorbell-button",
+    TwoWayAudio = "two-way-audio",
+    PanTiltZoom = "pan-tilt-zoom",
+    /**
+     * Camera supports the on-firmware autotrack subsystem (subject-
+     * following). Distinct from `PanTiltZoom` because not every PTZ
+     * camera ships autotrack — the admin UI uses this flag to gate
+     * the autotrack toggle / settings card without re-deriving from
+     * the cap registry. Mirrors `ptz-autotrack` cap registration:
+     * driver sets this feature when probe confirms the firmware
+     * surface, and registers the cap in the same code path.
+     */
+    PtzAutotrack = "ptz-autotrack",
+    /**
+     * Accessory exposes a "trigger on motion" toggle — the parent camera's
+     * motion detection automatically activates this device. Mirrors
+     * `motion-trigger` cap registration: drivers set this feature in the
+     * same code path that calls `ctx.registerNativeCap(motionTriggerCapability, ...)`.
+     *
+     * Used by admin UI (gate the in-hero `MotionTriggerToggle` against a
+     * fast scalar without binding fetch), notifier rules, and `listAll`
+     * filters that want "all devices with on-motion behaviour".
+     */
+    MotionTrigger = "motion-trigger"
+}
+export declare enum ChargingStatus {
+    ChargingDC = "charging-dc",
+    ChargingSolar = "charging-solar",
+    NotCharging = "not-charging"
+}
+/**
+ * Semantic role a device plays within its parent. Populated by driver
+ * addons when creating accessory devices (Reolink siren/floodlight/
+ * PIR/chime/autotrack/doorbell, ONVIF relay outputs, …). Used by the
+ * admin UI to pick icons, labels, and widgets — a `Switch` with
+ * `role: Floodlight` renders as a bulb with a brightness slider,
+ * whereas a `Switch` with `role: Siren` renders as a klaxon.
+ *
+ * Undefined for top-level devices (cameras, NVRs, hubs). Persisted in
+ * sqlite as a nullable TEXT column — old rows keep working unchanged.
+ */
+export declare enum DeviceRole {
+    Siren = "siren",
+    Floodlight = "floodlight",
+    Spotlight = "spotlight",
+    PirSensor = "pir-sensor",
+    Chime = "chime",
+    Autotrack = "autotrack",
+    Nightvision = "nightvision",
+    PrivacyMask = "privacy-mask",
+    Doorbell = "doorbell"
+}
+//# sourceMappingURL=device-type.d.ts.map

package/dist/device/device-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-type.d.ts","sourceRoot":"","sources":["../../src/device/device-type.ts"],"names":[],"mappings":"AAAA,oBAAY,UAAU;IACpB,MAAM,WAAW;IACjB,GAAG,QAAQ;IACX,KAAK,UAAU;IACf,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,UAAU,eAAe;IACzB,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AAED,oBAAY,aAAa;IACvB,eAAe,qBAAqB;IACpC,UAAU,eAAe;IACzB,cAAc,oBAAoB;IAClC,cAAc,oBAAoB;IAClC,WAAW,kBAAkB;IAC7B,WAAW,kBAAkB;IAC7B;;;;;;;;OAQG;IACH,YAAY,kBAAkB;IAC9B;;;;;;;;;OASG;IACH,aAAa,mBAAmB;CACjC;AAED,oBAAY,cAAc;IACxB,UAAU,gBAAgB;IAC1B,aAAa,mBAAmB;IAChC,WAAW,iBAAiB;CAC7B;AAED;;;;;;;;;;GAUG;AACH,oBAAY,UAAU;IAEpB,KAAK,UAAiB;IACtB,UAAU,eAAiB;IAC3B,SAAS,cAAiB;IAC1B,SAAS,eAAkB;IAC3B,KAAK,UAAiB;IACtB,SAAS,cAAiB;IAC1B,WAAW,gBAAiB;IAC5B,WAAW,iBAAkB;IAG7B,QAAQ,aAAiB;CAC1B"}

package/dist/device/device.d.ts

@@ -0,0 +1,87 @@
+import type { z } from 'zod';
+import type { DeviceType, DeviceFeature, DeviceRole } from './device-type.js';
+import type { DeviceConfig } from './device-config.js';
+import type { DeviceContext } from './device-context.js';
+import type { ConfigUISchemaWithValues } from '../interfaces/config-ui.js';
+export interface IDevice {
+    /** Progressive, system-wide unique numeric id. Assigned by the hub's
+     *  `device-manager` at `allocateDeviceId` time, injected through
+     *  `DeviceContext.id` and read verbatim by `BaseDevice`. Distinct from
+     *  `stableId`, which is unique per owning addon. Non-nullable — every
+     *  live IDevice has one (the hub allocates before the device is
+     *  constructed). Persists across removals: ids are never reissued. */
+    readonly id: number;
+    readonly stableId: string;
+    readonly type: DeviceType;
+    readonly name: string;
+    /**
+     * Operator-organisational location label (room / area / zone).
+     * `null` when unset. Free-text — providers don't interpret it; the
+     * UI groups devices by this for filters like "show me all cameras
+     * in Kitchen". Mutated via `kernel.devices.setLocation(id, value)`.
+     */
+    readonly location: string | null;
+    /**
+     * Soft-disabled flag. When `true`, the device class is still
+     * instantiated and visible in the UI (so the operator can flip
+     * back on without re-adding) but lifecycle hooks (publishToBroker,
+     * alarm-stream subscribe, …) MUST be gated by the driver to skip
+     * work. The `BaseDevice` exposes the flag; it doesn't mutate cap
+     * behaviour automatically — drivers consult `this.disabled` at
+     * the top of their lifecycle methods. Mutated via
+     * `kernel.devices.setDisabled(id, value)`.
+     */
+    readonly disabled: boolean;
+    /** Numeric id of this device's parent, or null when standalone. The
+     *  hub resolves the parent's `stableId` to its numeric id at
+     *  registration time so child devices reference parents by numeric id
+     *  internally — `stableId` stays at the external boundary. */
+    readonly parentDeviceId: number | null;
+    /**
+     * Optional semantic role this device plays within its parent.
+     * Driver addons set this when they create accessory devices (siren,
+     * floodlight, PIR, chime, doorbell). The admin UI uses it to pick
+     * icons, labels, and widgets. Undefined for top-level devices.
+     */
+    readonly role?: DeviceRole;
+    /**
+     * Device liveness flag. On `BaseDevice` this is a getter+setter pair
+     * proxying through the `device-status` runtime-state slice — both
+     * `device.online` reads and `device.online = true` writes route
+     * through the cap-keyed slice. `markOnline()` is the explicit
+     * method form for callers that prefer the imperative shape.
+     */
+    online: boolean;
+    readonly features: readonly DeviceFeature[];
+    readonly config: DeviceConfig<z.ZodObject<z.core.$ZodLooseShape>>;
+    readonly ctx: DeviceContext;
+    removeDevice(): Promise<void>;
+    /**
+     * Set the device's online flag. Called by `BaseDeviceProvider` after
+     * aggregating per-profile stream-broker health (or by drivers that have
+     * provider-side liveness signals). Mutates the `online` field; the
+     * field is `readonly` to consumers but writable through this method.
+     */
+    markOnline(online: boolean): void;
+    /**
+     * Device-authored settings UI. Returns the fully-hydrated schema (fields
+     * carry their current values inline) rendered by the admin UI under the
+     * device-details Config tab. Drivers with no settings to expose return
+     * `{ sections: [] }` — the aggregator drops empty contributions.
+     *
+     * This is the SINGLE source of truth for device settings UI. There is no
+     * auto-generation fallback: if a driver wants its config editable, it
+     * declares the shape here. `BaseDevice` provides the empty default so
+     * drivers opt in when they have something to show.
+     */
+    getSettingsUISchema(): ConfigUISchemaWithValues;
+    /**
+     * Write a flat patch coming from the UI (keyed by the `ConfigField.key`
+     * the driver emitted in `getSettingsUISchema`) back into storage.
+     * Drivers whose UI shape differs from the storage shape reshape the
+     * patch here before `config.setAll`. `BaseDevice` defaults to a direct
+     * `config.setAll(patch)` so drivers opt in only when they need reshape.
+     */
+    applySettingsPatch(patch: Record<string, unknown>): Promise<void>;
+}
+//# sourceMappingURL=device.d.ts.map

package/dist/device/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../../src/device/device.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AAE1E,MAAM,WAAW,OAAO;IACtB;;;;;0EAKsE;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B;;;kEAG8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAA;IAC1B;;;;;;OAMG;IACH,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAA;IAC3C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAA;IACjE,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;IAE3B,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7B;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;IAEjC;;;;;;;;;;OAUG;IACH,mBAAmB,IAAI,wBAAwB,CAAA;IAE/C;;;;;;OAMG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClE"}

package/dist/device/features.d.ts

@@ -0,0 +1,29 @@
+import type { ChargingStatus } from './device-type.js';
+export interface IBatteryOperated {
+    readonly batteryLevel: number;
+    readonly sleeping: boolean;
+    readonly chargingStatus: ChargingStatus;
+}
+export interface IRebootable {
+    reboot(): Promise<void>;
+}
+export interface INativeSnapshot {
+    getSnapshot(): Promise<Buffer>;
+}
+export interface IDoorbellButton {
+    /** Subscribe to doorbell press events. Returns unsubscribe function. */
+    onDoorbellPressed(callback: (timestamp: number) => void): () => void;
+}
+export interface ITwoWayAudio {
+    /** Start two-way audio session */
+    startAudio(): Promise<void>;
+    /** Stop two-way audio session */
+    stopAudio(): Promise<void>;
+}
+export interface IPanTiltZoom {
+    pan(direction: 'left' | 'right', speed?: number): Promise<void>;
+    tilt(direction: 'up' | 'down', speed?: number): Promise<void>;
+    zoom(direction: 'in' | 'out', speed?: number): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=features.d.ts.map

package/dist/device/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../../src/device/features.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAA;CACxC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,iBAAiB,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CACrE;AAED,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3B,iCAAiC;IACjC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7D,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB"}

package/dist/device/index.d.ts

@@ -0,0 +1,20 @@
+export { DeviceType, DeviceFeature, ChargingStatus, DeviceRole } from './device-type.js';
+export { AccessoryKind, ACCESSORY_LABEL, accessoryStableId, type AccessoryKindValue, } from './accessory.js';
+export type { IBatteryOperated, IRebootable, INativeSnapshot, IDoorbellButton, ITwoWayAudio, IPanTiltZoom } from './features.js';
+export { DeviceConfig } from './device-config.js';
+export type { DeviceContext, DeviceManagerApi, DeviceConstructor, IDeviceRegistryReader, IDeviceRegistry } from './device-context.js';
+export { BaseDevice } from './base-device.js';
+export type { AccessoryChildSpec } from './base-device.js';
+export { BaseDeviceProvider, toDeviceSummary } from './base-device-provider.js';
+export type { DiscoveryCandidate, DeviceSummary, ProviderStatus, FieldProbeResult } from './base-device-provider.js';
+export type { IDevice } from './device.js';
+export { DEVICE_PROFILES, BATTERY_DEVICE_PROFILE, deviceMatchesProfile, resolveDeviceProfile, } from './device-profile.js';
+export type { DeviceProfile, DeviceProfileMatch, DeviceProfileDefaults, PipelinePhaseMode, } from './device-profile.js';
+export type { ICameraDevice, StreamSourceEntry } from './camera-device.js';
+export type { DeviceManualCreation, DeviceDiscovery, DiscoveredDevice, SavedDevice, DeviceMeta, InitialDeviceMeta, CreateDeviceSpec } from './device-management.js';
+export { zodEntriesToConfigUI } from './zod-to-config-ui.js';
+export type { DeviceConfigEntry } from './zod-to-config-ui.js';
+export { createRuntimeStateBridge } from './runtime-state-helpers.js';
+export type { RuntimeStateBridge } from './runtime-state-helpers.js';
+export type { IDeviceRuntimeState, Snapshot as RuntimeStateSnapshot } from './device-runtime-state.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/device/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/device/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACxF,OAAO,EACL,aAAa,EAAE,eAAe,EAAE,iBAAiB,EACjD,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAChI,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrI,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAC/E,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AACpH,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EACL,eAAe,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,oBAAoB,GACpF,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,aAAa,EAAE,kBAAkB,EAAE,qBAAqB,EACxD,iBAAiB,GAClB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC1E,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACnK,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAC5D,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AACrE,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACpE,YAAY,EAAE,mBAAmB,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,2BAA2B,CAAA"}

package/dist/device/runtime-state-helpers.d.ts

@@ -0,0 +1,69 @@
+import type { z } from 'zod';
+import type { CapabilityDefinition } from '../capabilities/capability-definition.js';
+import type { IDeviceRuntimeState } from './device-runtime-state.js';
+/**
+ * Bridge a cap's `runtimeState` slice to its read-side methods.
+ *
+ * Pattern: provider keeps the camera fetch / write path, but delegates
+ * stale-check + slice read + cold-start fallback to this helper. Cuts
+ * the boilerplate that every provider would otherwise repeat across
+ * `getStatus`, `getSettings`, and any other read-side cap method.
+ *
+ * Convention: the cap's `runtimeState` schema must include a numeric
+ * `lastFetchedAt` field (ms epoch) so the helper can drive the
+ * stale-check. The field is stripped from the value returned by
+ * `getStatus` so the cap's status schema (which doesn't carry it)
+ * still parses cleanly.
+ *
+ * Usage in a provider:
+ * ```ts
+ * const bridge = createRuntimeStateBridge({
+ *   runtimeState: this.runtimeState,
+ *   cap: ptzAutotrackCapability,
+ *   ownDeviceId: this.id,
+ *   refresh: () => this.refreshAutotrackFromCamera(),
+ *   staleMs: 10_000,
+ *   empty: () => emptyAutotrackStatus(),
+ * })
+ *
+ * const provider: InferNativeProvider<typeof ptzAutotrackCapability> = {
+ *   getStatus: bridge.getStatus,
+ *   getSettings: async ({ deviceId }) => {
+ *     if (deviceId !== this.id) return null
+ *     await bridge.ensureFresh()
+ *     return this.runtimeState.getCapState<...>(...)?.currentSettings ?? null
+ *   },
+ *   setEnabled: async (...) => { ... ; await this.refreshAutotrackFromCamera() },
+ *   setSettings: async (...) => { ... ; await this.refreshAutotrackFromCamera() },
+ * }
+ * ```
+ *
+ * Single-flight (collapsing concurrent `refresh()` invocations) lives
+ * INSIDE `refresh` — the camera client owns its own promise slot. This
+ * helper stays thin so a single provider can host multiple cap-bridged
+ * readers without fighting over a shared promise.
+ */
+export interface RuntimeStateBridge<TStatus> {
+    /** Run a stale-check; if the slice is missing or older than
+     *  `staleMs`, await `refresh()`. Idempotent within the freshness
+     *  window — back-to-back calls touch zero camera I/O. */
+    readonly ensureFresh: () => Promise<void>;
+    /** Drop-in `getStatus` provider method. Includes the cross-device
+     *  guard + freshness check + status projection from the slice. */
+    readonly getStatus: (input: {
+        readonly deviceId: number;
+    }) => Promise<TStatus>;
+}
+export declare function createRuntimeStateBridge<TCap extends CapabilityDefinition & {
+    status: {
+        schema: z.ZodType;
+    };
+}>(params: {
+    readonly runtimeState: IDeviceRuntimeState;
+    readonly cap: TCap;
+    readonly ownDeviceId: number;
+    readonly refresh: () => Promise<void>;
+    readonly staleMs: number;
+    readonly empty: () => z.infer<TCap['status']['schema']>;
+}): RuntimeStateBridge<z.infer<TCap['status']['schema']>>;
+//# sourceMappingURL=runtime-state-helpers.d.ts.map

package/dist/device/runtime-state-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-state-helpers.d.ts","sourceRoot":"","sources":["../../src/device/runtime-state-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0CAA0C,CAAA;AACpF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAIpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,kBAAkB,CAAC,OAAO;IACzC;;6DAEyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC;sEACkE;IAClE,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAC/E;AAED,wBAAgB,wBAAwB,CACtC,IAAI,SAAS,oBAAoB,GAAG;IAAE,MAAM,EAAE;QAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAA;KAAE,CAAA;CAAE,EACrE,MAAM,EAAE;IACR,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAA;IAC1C,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAA;IAClB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;CACxD,GAAG,kBAAkB,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CA8BxD"}