@camstack/core 0.1.14 → 0.1.16

package/dist/builtins/device-manager/device-manager.addon.d.ts

@@ -0,0 +1,259 @@
+import { ProviderRegistration, BaseAddon, DeviceBindingEntry } from '@camstack/types';
+/**
+ * Wire shape matching `z.infer<typeof SettingsSchemaWithValuesSchema>` —
+ * duplicated as a plain interface because importing the Zod schema across
+ * package boundaries confuses `tsc` when the types package pins a
+ * different `zod` minor than the core package. Keeping the shape local
+ * keeps the addon decoupled from the schema's internal type encoding.
+ */
+interface ContributionShape {
+    tabs?: Array<{
+        id: string;
+        label: string;
+        icon: string;
+        order?: number;
+    }>;
+    sections: Array<{
+        id: string;
+        title: string;
+        description?: string;
+        style?: 'card' | 'accordion';
+        defaultCollapsed?: boolean;
+        columns?: 1 | 2 | 3 | 4;
+        tab?: string;
+        /** Where the section renders. Default 'settings' (Config tab); 'top-tab' hoists into the device-detail tab bar via DeviceDetail discovery. */
+        location?: 'settings' | 'top-tab';
+        order?: number;
+        fields: unknown[];
+    }>;
+}
+export declare class DeviceManagerAddon extends BaseAddon {
+    constructor();
+    /** Shorthand for the kernel-injected capability registry. */
+    private get capabilityRegistry();
+    /**
+     * Parent-chain event propagator. Started in `onInitialize` once the
+     * hub's `deviceRegistry` is available; listens to every device-sourced
+     * event and re-emits a copy on each ancestor scope with `via[]`
+     * populated. Stopped in `onShutdown`.
+     */
+    private propagator;
+    /**
+     * Hub-side mirror of every device's cap-keyed runtime state.
+     * Populated whenever any caller writes via `deviceState.setCapSlice`
+     * (the canonical cross-layer write entrypoint) and on first load
+     * via `loadRuntimeState`. Cross-process consumers reach the mirror
+     * through the `deviceState` cap router; per-cap event subscribers
+     * (e.g. `battery.onStatusChanged`) get the same data via
+     * cap-specific events still emitted by the owning device.
+     *
+     * Key: deviceId. Value: per-cap slice map. Empty by default —
+     * slices show up as `setCapSlice` calls trickle in.
+     */
+    private readonly stateMirror;
+    /**
+     * Per-device disk-write debouncer for runtime-state. `setCapSlice`
+     * updates the in-memory mirror synchronously and emits the change
+     * event immediately, but the disk write is coalesced — frequent
+     * back-to-back writes (motion phase transitions, battery pushes,
+     * etc.) collapse to one `writeDeviceRuntimeState` per
+     * `RUNTIME_STATE_DEBOUNCE_MS` window. `flushRuntimeStateWrites`
+     * awaits any in-flight write + scheduled flush so shutdown is
+     * lossless.
+     */
+    private readonly runtimeStateDebounce;
+    private static readonly RUNTIME_STATE_DEBOUNCE_MS;
+    /**
+     * Cross-process native-provider cache: deviceId (numeric) → capName → { addonId, nodeId }.
+     * Kept in sync with `device.bindings-changed` events emitted by forked
+     * workers. Union'd into `getBindings` so hub-side consumers see every
+     * native cap regardless of which process owns the IDevice. No persistence
+     * — entries re-register when the worker restarts. Purged on
+     * `$node.disconnected` to avoid stale routing after a worker crash.
+     */
+    private remoteNativeCaps;
+    /** Wait for a device-provider by addonId, returning null on timeout. */
+    private waitDeviceProvider;
+    /** Require a device-provider by addonId — throws if not found. */
+    private requireDeviceProvider;
+    private readBindingsStore;
+    private writeBindingsStore;
+    private resolveWrapperNodeId;
+    /**
+     * Active discovery of native caps registered on a worker node.
+     * Called from the `$node.connected` handler to recover from lost
+     * `DeviceBindingsChanged` broadcasts after worker restart.
+     *
+     * Iterates the broker's service registry, picks
+     * `<addonId>.native-provider.<capName>` services owned by the
+     * connected node, calls each service's `$listDeviceIds` action to
+     * fetch the deviceIds the worker has registered that cap on, then
+     * writes entries into `remoteNativeCaps`.
+     *
+     * Best-effort: per-service failures are logged and swallowed so a
+     * single bad service doesn't abort the whole rebuild.
+     */
+    private discoverWorkerNativeCaps;
+    getBindings(input: {
+        deviceId: number;
+    }): Promise<{
+        deviceId: number;
+        entries: DeviceBindingEntry[];
+    }>;
+    /**
+     * Whole-fleet binding dump. Iterates every device known to the
+     * deviceRegistry and reuses the per-device `getBindings` resolver
+     * for each — same routing rules, single round-trip. Used by
+     * `SystemManager.init()` for warm-boot.
+     *
+     * Bindings change rarely (wrapper toggle, device add/remove) so
+     * clients invalidate via the existing
+     * `capability.binding-changed` event rather than re-fetching this
+     * payload periodically.
+     */
+    getAllBindings(): Promise<Array<{
+        deviceId: number;
+        entries: DeviceBindingEntry[];
+    }>>;
+    /**
+     * Resolve a numeric deviceId to a stableId via persisted meta.
+     * Used only by the device-identity section of the device-details
+     * aggregator (see `buildBaseDeviceSection`) to surface the stableId as
+     * a readonly display field. All runtime/registry lookups are keyed by
+     * numeric deviceId; this helper is display-only.
+     */
+    private lookupPersistedStableId;
+    getDeviceAggregate(deviceId: number, kind: 'settings' | 'live'): Promise<ContributionShape | null>;
+    /**
+     * Build the device-manager's own contribution to the aggregator — the
+     * device identity (id, stableId, addonId, type, online) + the
+     * driver-specific config exposed by the device class via
+     * `zodEntriesToConfigUI`.
+     *
+     * Two paths, deliberately symmetric with `getSettingsSchema`:
+     *
+     *  - Hub-local: device's IDevice instance lives in this process'
+     *    DeviceRegistry, we read config + schema directly by reference.
+     *  - Cross-process: device lives in a forked worker (RtspCamera on
+     *    provider-rtsp, ONVIF on provider-onvif, …). We ask the worker's
+     *    `device-ops.getSettingsSchema` native provider for a wire-
+     *    serializable ConfigUISchema and merge it in under the same
+     *    "Driver Config" section, so the UI sees the same shape regardless
+     *    of where the IDevice physically runs.
+     *
+     *  Returns `null` only when the device genuinely doesn't exist anywhere
+     *  (no hub-local, no persisted ownership, no device-ops native). The
+     *  aggregator falls back to contributor sections only in that case.
+     */
+    private buildBaseDeviceSection;
+    /**
+     * Lookup the native owner for `device-ops` on `deviceId` — the native-cap
+     * registry (hub-local and remote) is keyed by numeric id.
+     */
+    private resolveNativeDeviceOwner;
+    /**
+     * Aggregate `status` across every registered cap for a device.
+     *
+     * Walks the supplied cap list (or `CAP_NAMES_WITH_STATUS` when
+     * omitted), looks up a native provider per cap via the capability
+     * registry, calls `provider.getStatus({ deviceId })`, and validates
+     * the return against the cap's own `status.schema`. Validation
+     * failures log a warning and yield `null` for that cap so the
+     * overall aggregate stays usable — a single misbehaving provider
+     * must not blank out a device's entire status view.
+     *
+     * Returned shape is `Record<capName, unknown | null>`; the client-
+     * side hook tightens this to `CapStatusTypeMap` via the generated
+     * `cap-status-types.ts`.
+     */
+    private getDeviceStatusAggregate;
+    /**
+     * Return the driver-specific device-settings contribution. Hub-local
+     * devices call `getSettingsUISchema()` directly; forked-worker devices
+     * go through the `device-ops.getSettingsSchema` cap method on the
+     * numeric-id-keyed native registry.
+     */
+    private resolveDriverConfigSchema;
+    updateDeviceField(input: {
+        deviceId: number;
+        writerCapName: string;
+        writerAddonId: string;
+        key: string;
+        value: unknown;
+    }): Promise<{
+        success: true;
+    }>;
+    /**
+     * Batched counterpart of `updateDeviceField`. Groups changes by
+     * `(writerCapName, writerAddonId)` so each contributor receives a
+     * single `applyDeviceSettingsPatch` with all of its updates merged —
+     * avoids N round-trips for simultaneous edits in the same save.
+     *
+     * Per-provider failures are captured in the `failures[]` output so the
+     * admin UI can highlight which sections didn't persist; a failure on
+     * one provider does NOT abort the others.
+     */
+    updateDeviceFieldsBatch(input: {
+        deviceId: number;
+        changes: ReadonlyArray<{
+            writerCapName: string;
+            writerAddonId: string;
+            key: string;
+            value: unknown;
+        }>;
+    }): Promise<{
+        success: true;
+        failures: {
+            writerCapName: string;
+            writerAddonId: string;
+            error: string;
+        }[];
+    }>;
+    /** Apply a single grouped patch to the appropriate provider. Mirrors
+     * `updateDeviceField` routing (special-case device-manager, else
+     * registry lookup). Used by `updateDeviceFieldsBatch`. */
+    private applyGroupPatch;
+    listWrappersForCap(input: {
+        capName: string;
+    }): Promise<string[]>;
+    listBindableCapsForDeviceType(input: {
+        deviceType: string;
+    }): Promise<Array<{
+        capName: string;
+        wrappers: string[];
+    }>>;
+    setWrapperActive(input: {
+        deviceId: number;
+        capName: string;
+        wrapperAddonId: string;
+        active: boolean;
+    }): Promise<void>;
+    protected onInitialize(): Promise<ProviderRegistration[] | void>;
+    /**
+     * Single-cap mirror update — diff against the current mirror,
+     * persist the new slice in-memory, emit `DeviceStateChanged` for
+     * this cap. No-op on identical writes (both same shape and same
+     * values). Called by `setCapSlice` provider.
+     */
+    private applySingleCapUpdate;
+    /**
+     * Debounced disk writer. Coalesces frequent writes (motion phase
+     * transitions, battery pushes) into one `writeDeviceRuntimeState`
+     * per `RUNTIME_STATE_DEBOUNCE_MS` window. Reads the per-device
+     * blob from the live mirror at flush time so the disk picture is
+     * always the latest state — no risk of writing a stale snapshot.
+     */
+    private scheduleRuntimeStateDiskWrite;
+    /**
+     * One-shot mirror seed used by `loadRuntimeState` at boot so the
+     * hub knows about every persisted slice without waiting for the
+     * first `setCapSlice` call. No events emitted — this is
+     * initial-state population, not a transition.
+     */
+    private seedMirror;
+    private snapshotForDevice;
+    private emitStateChanged;
+    protected onShutdown(): Promise<void>;
+}
+export default DeviceManagerAddon;
+//# sourceMappingURL=device-manager.addon.d.ts.map

package/dist/builtins/device-manager/device-manager.addon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-manager.addon.d.ts","sourceRoot":"","sources":["../../../src/builtins/device-manager/device-manager.addon.ts"],"names":[],"mappings":"AAyBA,OAAO,EACL,oBAAoB,EACpB,SAAS,EAIV,MAAM,iBAAiB,CAAA;AAYxB;;;;;;GAMG;AACH,UAAU,iBAAiB;IACzB,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACzE,QAAQ,EAAE,KAAK,CAAC;QACd,EAAE,EAAE,MAAM,CAAA;QACV,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAAA;QAC5B,gBAAgB,CAAC,EAAE,OAAO,CAAA;QAC1B,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACvB,GAAG,CAAC,EAAE,MAAM,CAAA;QACZ,8IAA8I;QAC9I,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,CAAA;QACjC,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,OAAO,EAAE,CAAA;KAClB,CAAC,CAAA;CACH;AAID,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAsWzD,qBAAa,kBAAmB,SAAQ,SAAS;;IAG/C,6DAA6D;IAC7D,OAAO,KAAK,kBAAkB,GAE7B;IAED;;;;;OAKG;IACH,OAAO,CAAC,UAAU,CAAqC;IACvD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0D;IAEtF;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAGjC;IACJ,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,yBAAyB,CAAO;IAExD;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB,CAA2E;IAEnG,wEAAwE;YAC1D,kBAAkB;IAKhC,kEAAkE;YACpD,qBAAqB;YAerB,iBAAiB;YAKjB,kBAAkB;IAIhC,OAAO,CAAC,oBAAoB;IAM5B;;;;;;;;;;;;;OAaG;YACW,wBAAwB;IAoDhC,WAAW,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,kBAAkB,EAAE,CAAA;KAAE,CAAC;IAgH5G;;;;;;;;;;OAUG;IACG,cAAc,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,kBAAkB,EAAE,CAAA;KAAE,CAAC,CAAC;IAU3F;;;;;;OAMG;YACW,uBAAuB;IA0B/B,kBAAkB,CACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,GAAG,MAAM,GACxB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IA4FpC;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,sBAAsB;IAkGpC;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAOhC;;;;;;;;;;;;;;OAcG;YACW,wBAAwB;IAoDtC;;;;;OAKG;YACW,yBAAyB;IAsBjC,iBAAiB,CAAC,KAAK,EAAE;QAC7B,QAAQ,EAAE,MAAM,CAAA;QAChB,aAAa,EAAE,MAAM,CAAA;QACrB,aAAa,EAAE,MAAM,CAAA;QACrB,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,OAAO,CAAA;KACf,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,CAAC;IAmD9B;;;;;;;;;OASG;IACG,uBAAuB,CAAC,KAAK,EAAE;QACnC,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,aAAa,CAAC;YACrB,aAAa,EAAE,MAAM,CAAA;YACrB,aAAa,EAAE,MAAM,CAAA;YACrB,GAAG,EAAE,MAAM,CAAA;YACX,KAAK,EAAE,OAAO,CAAA;SACf,CAAC,CAAA;KACH,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,QAAQ,EAAE;YAAE,aAAa,EAAE,MAAM,CAAC;YAAC,aAAa,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IAiC3G;;8DAE0D;YAC5C,eAAe;IAmCvB,kBAAkB,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIjE,6BAA6B,CAAC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAUrH,gBAAgB,CAAC,KAAK,EAAE;QAC5B,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,MAAM,CAAA;QACf,cAAc,EAAE,MAAM,CAAA;QACtB,MAAM,EAAE,OAAO,CAAA;KAChB,GAAG,OAAO,CAAC,IAAI,CAAC;cAkCD,YAAY,IAAI,OAAO,CAAC,oBAAoB,EAAE,GAAG,IAAI,CAAC;IAo8CtE;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;;;;;OAMG;IACH,OAAO,CAAC,6BAA6B;IA6BrC;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,gBAAgB;cAUR,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CA0B5C;AAED,eAAe,kBAAkB,CAAA"}