@camstack/types 0.1.14 → 0.1.16

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

@@ -0,0 +1,256 @@
+import type { IScopedLogger } from '../interfaces/logging.js';
+import type { IEventBus } from '../interfaces/event-bus.js';
+import type { IDevice } from './device.js';
+import type { CapabilityDefinition, InferNativeProvider } from '../capabilities/capability-definition.js';
+import type { IKernelStreamProbe } from '../interfaces/addon.js';
+import type { AddonApi } from '../generated/addon-api.js';
+import type { DeviceProxy } from '../generated/device-proxy.js';
+import type { DeviceMeta, InitialDeviceMeta } from './device-management.js';
+export interface DeviceContext {
+    /** Progressive, system-wide unique numeric device id. Injected from the
+     *  hub's `device-manager` via `DeviceManagerApi.allocateDeviceId` before
+     *  `BaseDevice` is constructed, so `IDevice.id` is always populated. */
+    readonly id: number;
+    readonly stableId: string;
+    /** Numeric id of the parent device, or null when standalone. Resolved
+     *  by the caller of `DeviceManagerApi.create()` from the parent IDevice. */
+    readonly parentDeviceId: number | null;
+    readonly logger: IScopedLogger;
+    readonly api: AddonApi;
+    readonly eventBus: IEventBus;
+    readonly persistConfig: (data: unknown) => Promise<void>;
+    /**
+     * Snapshot of the persisted runtime-state blob loaded at boot.
+     * `BaseDevice` hands this to `DeviceRuntimeState.fromInitial` so
+     * the device wakes up with the last-known battery / sleep flag
+     * already populated. Empty object on first boot or for ctx
+     * factories that don't wire runtime state (tests).
+     *
+     * Runtime-state WRITES route through `fetchDevice(id).deviceState
+     * .setCapSlice(...)` — the canonical cross-layer entrypoint via the
+     * codegen DeviceProxy. `BaseDevice.runtimeState.setCapState` lazily
+     * resolves the proxy and pre-binds `deviceId`.
+     */
+    readonly initialRuntimeState?: Record<string, unknown>;
+    /**
+     * Snapshot of the persisted device-config blob loaded from the
+     * per-device DB at boot. Symmetric with `initialRuntimeState` —
+     * the kernel pre-loads from disk before the BaseDevice constructor
+     * runs so the in-memory `DeviceConfig` wakes up with operator-
+     * edited values without the addon having to thread `saved.config`
+     * through `kernel.devices.create()`.
+     *
+     * Optional only to support test harnesses that build a bare ctx;
+     * production kernel context factories always populate it.
+     */
+    readonly persistedConfig?: Record<string, unknown>;
+    /**
+     * Read-only snapshot of the operator-organisational meta surface
+     * (name / location / disabled / type / parentDeviceId / addonId).
+     * Loaded by the kernel from the device-meta DB row before the
+     * device class constructor runs — `BaseDevice` reads `name` /
+     * `location` / `disabled` from here so subclass schemas don't
+     * have to duplicate the fields. Mutations go through
+     * `devices.setName / setLocation / setDisabled` — `applySettingsPatch`
+     * is hardware-config only.
+     *
+     * Always populated by the kernel in production. Test fixtures must
+     * supply a non-null value too — `BaseDevice` constructor throws
+     * when missing.
+     */
+    readonly deviceMeta: DeviceMeta;
+    /**
+     * Lazy resolver for a device-scoped facade — same shape as
+     * `AddonContext.fetchDevice(id)`. Returns a `DeviceProxy` with
+     * `deviceId` pre-bound on every cap method, so callers say
+     * `dev.deviceState.setCapSlice({capName, slice})` instead of
+     * `ctx.api.deviceState.setCapSlice.mutate({deviceId: ctx.id, ...})`.
+     * Always wired by the production context factory; test ctx
+     * fixtures supply a stub.
+     */
+    readonly fetchDevice: (deviceId: number) => Promise<DeviceProxy>;
+    /**
+     * Reverse-pointer hook called by `BaseDevice` constructor right
+     * after building its `runtimeState`. The kernel context factory
+     * stashes the reference so that `registerNativeCap`, fired from
+     * inside the same constructor's call chain, can install the cap's
+     * `runtimeState` schema onto the device's state without needing
+     * the device to be registered in `DeviceRegistry` yet (it isn't —
+     * register happens AFTER the constructor returns).
+     *
+     * Optional for tests / backwards compat — caps with `runtimeState`
+     * registered in a context without this hook silently skip schema
+     * installation, falling back to memory-only state.
+     */
+    readonly bindRuntimeState?: (state: import('./device-runtime-state.js').IDeviceRuntimeState) => void;
+    readonly devices: DeviceManagerApi;
+    /**
+     * Kernel stream-probe entrypoint — same typed contract as the
+     * one exposed to addons via `ctx.kernel.streamProbe`. Mirrored
+     * onto the device context so devices that reprobe their inputs
+     * on edit (e.g. RTSP multi-stream reclassification) never need
+     * to branch on transport or reach through `ctx.api`. Optional
+     * only to support test harnesses that build a bare ctx.
+     */
+    readonly streamProbe?: IKernelStreamProbe;
+    /** Register a native provider for `cap` on the device this context belongs to.
+     *  Multiple calls for the same cap throw. */
+    registerNativeCap<TCap extends CapabilityDefinition>(cap: TCap, provider: InferNativeProvider<TCap>): void;
+}
+/** Constructor type for BaseDevice subclasses.
+ *
+ *  Deliberately ONE-ARG: the device class receives only its `ctx`,
+ *  and the kernel pre-loads the persisted config blob into
+ *  `ctx.persistedConfig` BEFORE this constructor runs. This makes
+ *  the device entirely self-managing — no operator-supplied config
+ *  ever bypasses the per-device DB. Providers create new devices by
+ *  passing initial config to `kernel.devices.create()` (or
+ *  `persistInitialConfig` for the advanced flow) which writes to the
+ *  DB FIRST; the constructor then reads that same blob from
+ *  `ctx.persistedConfig`.
+ *
+ *  Subclasses with extra constructor args (e.g. accessory child
+ *  devices that take a `parent` reference) extend this contract by
+ *  having their own concrete signature; the kernel-side `create()`
+ *  uses `DeviceConstructor` only for the standard 1-arg path.
+ *  Custom-arg subclasses go through the lower-level `allocateDeviceId
+ *  + persistInitialConfig + createContext + register` flow.
+ */
+export type DeviceConstructor<T extends IDevice = IDevice> = new (ctx: DeviceContext) => T;
+export interface DeviceManagerApi {
+    /**
+     * Create, register, and persist a device in one call.
+     * Handles: context creation → instantiation → registry + DB persistence.
+     */
+    create<T extends IDevice>(stableId: string, DeviceClass: DeviceConstructor<T>, config: Record<string, unknown>, parentDeviceId?: number | null, 
+    /**
+     * Operator-supplied meta (`name` / `location` / `disabled`) the
+     * kernel writes to the meta row BEFORE the device class
+     * constructor runs. The constructor reads these via
+     * `ctx.deviceMeta`. Mandatory when creating a NEW device — the
+     * placeholder `name = stableId` would otherwise stick. Restore
+     * paths omit it (the persisted row already carries the
+     * operator's edits).
+     */
+    initialMeta?: InitialDeviceMeta): Promise<T>;
+    /**
+     * Reserve (or re-resolve) the progressive numeric id for a given
+     * `(addonId, stableId)` pair. Idempotent: repeated calls for the same
+     * stableId return the same id — allocation only happens the first time.
+     * Callers that bypass `create()` (boot-restore, discovery adoption) call
+     * this first so `createContext` and `BaseDevice` have the id to bind.
+     */
+    allocateDeviceId(stableId: string): Promise<number>;
+    /** Low-level context creation (for hub devices managing children).
+     *  `id` MUST come from `allocateDeviceId` — feeding it here binds
+     *  `DeviceContext.id` so `BaseDevice` exposes it on `IDevice.id`.
+     *
+     *  `persistedConfig` is stuffed into `DeviceContext.persistedConfig`
+     *  so the device's BaseDevice constructor self-hydrates. Pass the
+     *  result of `loadConfig(id)` for the restore path; default `{}` for
+     *  a fresh device. Callers wired through `kernel.devices.create()`
+     *  don't need to think about this — the standard `create()` shortcut
+     *  loads it automatically. */
+    createContext(stableId: string, id: number, parentDeviceId?: number | null, persistedConfig?: Record<string, unknown>): DeviceContext;
+    /** Read the per-device persisted config blob from the DB. Returns
+     *  `{}` for devices that have no persisted row yet (newly allocated
+     *  but not registered). Used by callers going through the manual
+     *  `allocateDeviceId + createContext + register` flow (e.g. accessory
+     *  child devices that need a custom-arg constructor) to self-hydrate
+     *  the child without threading `saved.config` from the addon's
+     *  `onRestoreDevices` boundary. */
+    loadConfig(deviceId: number): Promise<Record<string, unknown>>;
+    /** Pre-persist an initial config blob to the per-device DB BEFORE
+     *  the device class is instantiated. The constructor then reads
+     *  the same blob via `ctx.persistedConfig`. Mandatory when a
+     *  provider needs to seed a NEW device with operator-supplied
+     *  config (form input from the Add-Device modal) — the device
+     *  class never receives the config directly, only via the DB.
+     *  Idempotent: calling for an already-persisted id overwrites the
+     *  blob (used for re-seed flows like "operator re-edits during
+     *  initial wizard"). */
+    persistInitialConfig(stableId: string, config: Record<string, unknown>): Promise<number>;
+    /** Update the device's display name. Surfaces immediately in
+     *  the UI device list + on `IDevice.name` for live consumers. */
+    setName(deviceId: number, name: string): Promise<void>;
+    /** Set the operator-organisational location label
+     *  ("Kitchen" / "Front yard" / …). Pass `null` to clear. */
+    setLocation(deviceId: number, location: string | null): Promise<void>;
+    /** Soft-disable the device. Disabled devices stay in the registry
+     *  + DB so the operator can flip back on without re-adding, but
+     *  BaseDevice gates lifecycle hooks (publishToBroker, alarm-stream
+     *  subscribe, …) to skip work. */
+    setDisabled(deviceId: number, disabled: boolean): Promise<void>;
+    /** Low-level registration (for advanced use cases) */
+    register(device: IDevice): Promise<void>;
+    /** Remove a device and all its children (cascading) */
+    remove(deviceId: number): Promise<void>;
+    /**
+     * Tear a device (and its children) down in-memory WITHOUT touching
+     * the persisted device-meta / config / bindings. Used by addon
+     * shutdown paths (graceful SIGTERM in group-runner, in-process
+     * `restartAddon`) so each device's `removeDevice()` lifecycle hook
+     * fires (closes alarm streams, ISAPI clients, polling timers,
+     * intercom sessions, …) and native caps unregister cleanly. The
+     * persisted index remains intact so the next boot's
+     * `restoreDevices` rehydrates the same set.
+     *
+     * Difference from `remove(id)`: same in-memory teardown, but no
+     * `device-manager.removeDevice` call. Use `remove` when the operator
+     * deletes a device from the UI; use `decommission` for restart /
+     * shutdown lifecycle paths where the device should reappear on
+     * the next boot.
+     */
+    decommission(deviceId: number): Promise<void>;
+    /** List all devices for this addon */
+    getAll(): Promise<ReadonlyArray<IDevice>>;
+    /** List children of a specific device */
+    getChildren(parentDeviceId: number): Promise<ReadonlyArray<IDevice>>;
+}
+/**
+ * Read-only global view of the kernel `DeviceRegistry`, exposed to addons
+ * that need to observe devices across ALL addons (not just their own).
+ *
+ * Typical consumers are infrastructure addons that provide a service
+ * to every device in the system — e.g. `addon-stream-broker` registers
+ * stream sources for every camera regardless of which provider addon
+ * instantiated it, so it needs to enumerate cameras coming from
+ * `addon-provider-rtsp`, `addon-provider-frigate`, etc.
+ *
+ * The interface is deliberately read-only: addons can list / query but
+ * never mutate the registry. Mutations still go through the per-addon
+ * `DeviceManagerApi` (`ctx.devices`) so each addon only creates devices
+ * under its own id.
+ */
+export interface IDeviceRegistryReader {
+    /** Return every device across every addon. Snapshot — does not subscribe. */
+    getAll(): readonly IDevice[];
+    /** Look up any registered device by its progressive numeric id. */
+    getById(id: number): IDevice | null;
+    /** Owning addonId for a registered numeric id, or null if unknown. */
+    getAddonId(id: number): string | null;
+    /** Return every child of a parent device. */
+    getChildren(parentDeviceId: number): readonly IDevice[];
+}
+/**
+ * Full device registry — extends the reader with listing helpers and
+ * mutation methods. Exposed on `AddonContext.deviceRegistry` for
+ * infrastructure addons that manage devices across all providers
+ * (e.g. `device-manager`).
+ *
+ * Hub-only: agents/workers don't have a local device registry.
+ */
+export interface IDeviceRegistry extends IDeviceRegistryReader {
+    /** Return all devices for a specific addon. */
+    getAllForAddon(addonId: string): readonly IDevice[];
+    /** Return every device paired with its owning addon id. */
+    getAllWithAddonId(): readonly {
+        addonId: string;
+        device: IDevice;
+    }[];
+    /** Return all addon ids that have registered devices. */
+    getAddonIds(): readonly string[];
+    /** Remove a device from the registry. */
+    remove(deviceId: number): void;
+}
+//# sourceMappingURL=device-context.d.ts.map

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

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

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

@@ -0,0 +1,118 @@
+import type { z } from 'zod';
+import type { DeviceType } from './device-type.js';
+import type { IDevice } from './device.js';
+export interface DeviceManualCreation {
+    getChildCreationSchema(type: DeviceType): z.ZodObject<z.core.$ZodLooseShape>;
+    createDevice(type: DeviceType, config: unknown): Promise<IDevice>;
+}
+export interface DeviceDiscovery {
+    discoverDevices(): Promise<readonly DiscoveredDevice[]>;
+    adoptDiscoveredDevice(candidate: DiscoveredDevice): Promise<IDevice>;
+}
+export interface DiscoveredDevice {
+    readonly stableId: string;
+    readonly type: DeviceType;
+    readonly suggestedName: string;
+    readonly prefilledConfig: Record<string, unknown>;
+}
+export interface SavedDevice {
+    /** Numeric id reserved at allocateDeviceId time. */
+    readonly id: number;
+    /** External-system identifier — passed to `kernel.devices.create()`. */
+    readonly stableId: string;
+    readonly type: DeviceType;
+    readonly name: string;
+    /**
+     * Operator-organisational label (room / location / area). `null`
+     * when unset. Free-text — providers don't interpret it; the UI
+     * groups devices by this field for "show me all cameras in
+     * Kitchen" filters.
+     */
+    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 it
+     * back on without re-adding) but lifecycle hooks
+     * (publishToBroker, alarm-stream subscribe, …) are gated off by
+     * BaseDevice. Used for "this camera is in maintenance" without
+     * destroying its persisted config + bindings + per-device settings.
+     */
+    readonly disabled: boolean;
+    readonly parentDeviceId: number | null;
+    readonly config: Record<string, unknown>;
+}
+/**
+ * Read-only snapshot of the device-meta surface, exposed on
+ * `DeviceContext.deviceMeta`. The kernel populates it before the
+ * device class constructor runs so `BaseDevice` can resolve
+ * `name` / `location` / `disabled` without each subclass
+ * duplicating those fields in its config schema.
+ *
+ * Mutations go through `kernel.devices.{setName,setLocation,
+ * setDisabled}` — never through `applySettingsPatch`. The two
+ * surfaces are deliberately disjoint: `meta` is operator-organisational
+ * (free-text labels, on/off toggle), `config` is hardware-specific
+ * (host, port, credentials, debug flags, deviceCache).
+ */
+/**
+ * Free-form device metadata — hardware identity + driver-populated
+ * facts the operator can both read and edit. Mirrors Scrypted's
+ * `info: { manufacturer, model, serialNumber, ... }` device-level
+ * surface but stored as a single JSON blob so future fields (HA
+ * matter id, ONVIF profile token, …) don't require schema changes.
+ *
+ * Conventional keys (drivers should populate when known):
+ *   - `manufacturer`  e.g. 'Reolink'
+ *   - `model`         e.g. 'Argus PT Ultra'
+ *   - `serialNumber`
+ *   - `firmware`      software version
+ *   - `hardware`      hardware revision
+ *   - `mac`           MAC address
+ *   - `uid`           vendor-specific globally-unique id (Reolink, etc.)
+ *
+ * Anything else the driver knows can land alongside (`onvifProfile`,
+ * `ipAddress`, `apiPort`, …). All values must be JSON-serializable.
+ */
+export type DeviceMetadata = Record<string, unknown>;
+export interface DeviceMeta {
+    readonly id: number;
+    readonly stableId: string;
+    readonly addonId: string;
+    readonly type: DeviceType;
+    readonly name: string;
+    readonly location: string | null;
+    readonly disabled: boolean;
+    readonly parentDeviceId: number | null;
+    /** Hardware + identity blob; null when nothing has been populated yet. */
+    readonly metadata: DeviceMetadata | null;
+}
+/**
+ * Initial meta a provider supplies on `onCreateDevice`. Differs
+ * from `DeviceMeta` in that `id` / `stableId` / `addonId` are
+ * kernel-allocated, not operator-supplied.
+ */
+export interface InitialDeviceMeta {
+    readonly type: DeviceType;
+    readonly name: string;
+    readonly location?: string | null;
+}
+/**
+ * Single-call payload returned by `BaseDeviceProvider.onCreateDevice`.
+ * Splits operator-organisational labels (`meta`) from hardware-
+ * specific config (`config`) — kernel handles the rest:
+ * stableId allocation, persistence, instantiation, register.
+ *
+ * `onAfterCreate` is the escape hatch for providers that need to
+ * inject creation-time-only state into the freshly-built device
+ * (e.g. Reolink's autodetect handshake hands a live Baichuan API
+ * instance; adoption skips a second login). Fires AFTER `register`
+ * + `device.onCreated` + accessory auto-spawn complete — the
+ * device is fully alive when the callback runs. Best-effort:
+ * failures log but don't unwind the already-registered device.
+ */
+export interface CreateDeviceSpec {
+    readonly meta: InitialDeviceMeta;
+    readonly config: Record<string, unknown>;
+    readonly onAfterCreate?: (device: IDevice) => Promise<void> | void;
+}
+//# sourceMappingURL=device-management.d.ts.map

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

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

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

@@ -0,0 +1,161 @@
+/**
+ * Bindings × Modes contract
+ * ─────────────────────────
+ *
+ * Two independent layers gate every analyzer phase (detection / audio):
+ *
+ *   1. **Bindings** (low-level wiring, escape hatch)
+ *      The cap-router decides whether the addon is MOUNTED for a
+ *      device at all. `setWrapperActive(deviceId, capName, false)`
+ *      fully dismounts the cap; nothing the cap exposes (provider
+ *      methods, runtime-state, events) is reachable. The operator
+ *      rarely touches this from the UI — it's the "uninstall this
+ *      addon for this device" button. Default: every wrapper bound.
+ *
+ *   2. **Modes** (operator-facing scheduling)
+ *      The `detectionMode` / `audioMode` selectors decide WHEN the
+ *      mounted cap actually fires. `'disabled'` is the runtime-level
+ *      off switch — the cap stays mounted, schema present, RPCs
+ *      callable, but the runner / orchestrator skip the substream
+ *      subscriber. The other 2 modes (`'always-on'`, `'on-motion'`)
+ *      drive when the subscribe + analyze cycle runs.
+ *
+ * **AND-gate semantics**: a phase fires iff `(binding bound) AND
+ * (mode != 'disabled')`. Either layer disables → cap inactive.
+ * Neither layer overrides the other; the operator picks whichever
+ * lever maps to their intent.
+ *
+ *   - "I never want SW detection on this camera" → unbind via
+ *     bindings UI (extreme — also disables the cap surface).
+ *   - "Pause detection for now, keep wired" → set
+ *     `detectionMode = 'disabled'`. Settings still surface; no
+ *     substream demand.
+ *   - "Detection only when motion fires" → `detectionMode = 'on-motion'`,
+ *     binding stays bound.
+ *
+ * Profile defaults populate modes when the operator hasn't picked.
+ * Bindings are bound by their wrappers' `defaultActive: true` flag,
+ * unaffected by the profile.
+ *
+ * ─────────────────────────
+ *
+ * DeviceProfile — declarative defaults applied to devices that match a
+ * feature predicate.
+ *
+ * Solves the "battery cams shouldn't run continuous analyzers" problem
+ * (and adjacent policy questions like low-bandwidth fallback) by
+ * centralising the operator-facing defaults in ONE place. The profile
+ * does NOT touch capability bindings — those stay as the low-level
+ * wiring escape hatch. Instead the profile drives the per-device
+ * pipeline behaviour through three operator-visible "mode" knobs that
+ * the runner / orchestrator interpret directly.
+ *
+ *   - `motionSources` — already a per-device setting today; the profile
+ *     just supplies a sensible default (`['onboard']` when firmware
+ *     motion is available; `[]` otherwise so a battery cam with no PIR
+ *     and no firmware push gates everything off until the operator opts
+ *     into `'analyzer'` SW motion).
+ *
+ *   - `audioMode` (NEW) — selects when the audio classifier runs:
+ *     `'disabled'`, `'always-on'`, `'on-motion'`. Replaces the implicit
+ *     "audio runs when wrapper bound" behaviour. Wrappers stay bound;
+ *     the addon reads this mode at runtime to decide whether to
+ *     subscribe to the audio decoded stream.
+ *
+ *   - `detectionMode` (NEW) — selects when object detection runs:
+ *     `'disabled'`, `'always-on'`, `'on-motion'`. Mirrors `audioMode`
+ *     and replaces the legacy `priority: 'default'|'always-on'` toggle
+ *     with explicit semantics.
+ *
+ * ─── Sticky-by-construction ───────────────────────────────────────────
+ *
+ * Nothing in the runtime re-applies a profile. Operator changes always
+ * win because the persistence layer captures them as concrete entries
+ * (config blob value); the profile is consulted only when no entry
+ * exists yet. If a setting is absent from the blob the resolver falls
+ * back to the profile's default, then the schema's static default.
+ */
+import type { DeviceFeature } from './device-type.js';
+/**
+ * Match clause: the profile applies to a device iff its `features`
+ * array contains `hasFeature`. Single-feature gate keeps matching
+ * cheap; the profile-stack iterates in order and the first match wins.
+ */
+export interface DeviceProfileMatch {
+    readonly hasFeature: DeviceFeature;
+}
+/**
+ * When-mode selector for analyzer phases (audio classification, object
+ * detection). `'disabled'` keeps the addon idle; `'always-on'` runs
+ * continuously; `'on-motion'` activates only when the motion-gate is
+ * open (firmware motion event OR analyzer-derived motion).
+ */
+export type PipelinePhaseMode = 'disabled' | 'always-on' | 'on-motion';
+/**
+ * Operator-facing settings the profile populates at creation time +
+ * resolver fallback time. These are NOT tightly bound to a single
+ * config schema field — the resolver (in pipeline-orchestrator) reads
+ * them when computing the runner config, and persists operator changes
+ * back to the same keys via the existing per-device store.
+ */
+export interface DeviceProfileDefaults {
+    /** Default `motionSources` array when the operator hasn't picked
+     *  one. Empty array means "no motion source" — useful for battery
+     *  cams without firmware motion (operator opts into `'analyzer'`
+     *  explicitly to enable SW motion). PIR-sourced motion currently
+     *  flows through `'onboard'` because Reolink's accessory PIRs feed
+     *  the parent camera's firmware motion event channel. */
+    readonly motionSources?: readonly ('onboard' | 'analyzer')[];
+    readonly audioMode?: PipelinePhaseMode;
+    readonly detectionMode?: PipelinePhaseMode;
+}
+export interface DeviceProfile {
+    readonly id: string;
+    readonly label: string;
+    readonly when: DeviceProfileMatch;
+    /**
+     * Default phase modes + motion-source pick. Resolver reads these
+     * when no operator value is persisted; profile never overrides a
+     * concrete operator choice.
+     */
+    readonly defaults: DeviceProfileDefaults;
+    /**
+     * Generic settings overrides (snapshot interval, pre-buffer flag,
+     * etc.). Same sticky semantics as defaults — applied on first read,
+     * operator override wins. Keys are dot-paths interpreted by the
+     * per-driver / per-addon config schema.
+     */
+    readonly settings: Readonly<Record<string, unknown>>;
+}
+/**
+ * Heuristic check — `device.features?.includes(profile.when.hasFeature)`.
+ */
+export declare function deviceMatchesProfile(features: readonly string[] | undefined, profile: DeviceProfile): boolean;
+/**
+ * Battery-operated cameras default policy. The substream stays dialed
+ * only when there's something for the runner to actually process —
+ * audio is off, detection only runs on motion.
+ *
+ * `motionSources` is NOT in the profile defaults: the orchestrator's
+ * resolver already prefers `'onboard'` whenever the device exposes a
+ * native motion cap (firmware-driven motion), independent of profile.
+ * Battery cams without firmware motion fall back to `[]` (no source) —
+ * the operator must opt into `'analyzer'` SW motion explicitly.
+ *
+ * Object detection on motion: when motion fires, the runner attaches
+ * the substream + runs detection until the motion gate closes, then
+ * releases. Firmware idle-disconnect fires shortly after, the camera
+ * goes back to sleep.
+ */
+export declare const BATTERY_DEVICE_PROFILE: DeviceProfile;
+/**
+ * Profile registry — order matters when multiple profiles match the
+ * same device (first match wins). Today there's only one entry.
+ */
+export declare const DEVICE_PROFILES: readonly DeviceProfile[];
+/**
+ * Resolve the profile that matches a device's features, or `null` when
+ * no profile matches. First-match-wins.
+ */
+export declare function resolveDeviceProfile(features: readonly string[] | undefined): DeviceProfile | null;
+//# sourceMappingURL=device-profile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"device-profile.d.ts","sourceRoot":"","sources":["../../src/device/device-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAGrD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAA;CACnC;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,WAAW,GACX,WAAW,CAAA;AAEf;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;6DAKyD;IACzD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC,SAAS,GAAG,UAAU,CAAC,EAAE,CAAA;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAA;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAA;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACrD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACvC,OAAO,EAAE,aAAa,GACrB,OAAO,CAGT;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAYpC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAEnD,CAAA;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACtC,aAAa,GAAG,IAAI,CAKtB"}