@camstack/system 1.1.52 → 1.1.54

package/dist/builtins/device-manager/device-store-sections.d.ts

@@ -0,0 +1,26 @@
+import { ProviderContext } from './device-provider-context.js';
+/** One device-store-backed section: the keys it owns + how to persist them. */
+export interface DeviceStoreSection {
+    /** Reserved config keys this section owns (must not reach the driver). */
+    readonly keys: readonly string[];
+    /** Persist this section's slice of a save into the device-store blob. */
+    apply(pctx: Pick<ProviderContext, 'settings'>, deviceId: number, patch: Record<string, unknown>): Promise<unknown>;
+}
+/** The device-manager's device-store-backed sections. Add an entry to extend. */
+export declare const DEVICE_STORE_SECTIONS: readonly DeviceStoreSection[];
+/** Result of splitting a `device-manager`-writer patch by persistence target. */
+export interface DeviceStoreSplit {
+    /** Per-section slices that persist to the device-store blob. */
+    readonly storeGroups: ReadonlyArray<{
+        section: DeviceStoreSection;
+        patch: Record<string, unknown>;
+    }>;
+    /** The remaining keys, destined for the device driver's own config. */
+    readonly driverPatch: Record<string, unknown>;
+}
+/**
+ * Split a `writerCapName: 'device-manager'` patch into device-store slices
+ * (one per matching registered section) and the leftover driver patch.
+ * Generic — consults {@link DEVICE_STORE_SECTIONS}, no hardcoded key list.
+ */
+export declare function splitDeviceStoreKeys(patch: Record<string, unknown>): DeviceStoreSplit;

package/dist/builtins/doorbell/doorbell-settings.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pure per-camera settings parsing/normalization for the virtual-doorbell
+ * builtin. Kept separate from the addon class (and the runtime trigger
+ * engine) so the persisted-shape handling — including tolerant migration of
+ * the legacy single-source blob — is unit-testable in isolation.
+ *
+ * PERSISTED SHAPE (extensible by design):
+ *   doorbellSources: Array<{ deviceId: number }>
+ *
+ * The source is an OBJECT rather than a bare id so future per-source options
+ * (a custom trigger override, an event-type match, a per-source debounce)
+ * can be added without another migration. Today only `deviceId` is stored;
+ * the reaction is DERIVED at runtime from the source device's cap (see
+ * `trigger-engine.ts`).
+ */
+/** Device-store key holding the source list. */
+export declare const KEY_SOURCES = "doorbellSources";
+/**
+ * Legacy device-store keys from the pre-simplification shape (single source
+ * device + explicit trigger + event type). Retained ONLY for tolerant
+ * migration on read and cleanup on write — never written afresh.
+ */
+export declare const LEGACY_KEY_SOURCE = "doorbellSourceDeviceId";
+export declare const LEGACY_KEY_TRIGGER = "doorbellTrigger";
+export declare const LEGACY_KEY_EVENT_TYPE = "doorbellEventType";
+/**
+ * One source device driving a camera's virtual doorbell. Intentionally an
+ * object so it can grow (custom trigger, event type) without a migration.
+ */
+export interface DoorbellSource {
+    readonly deviceId: number;
+}
+/** Coerce a persisted / form-supplied id (number or numeric string) to a
+ *  positive integer device id, or null when it is not a usable id. */
+export declare function coerceDeviceId(value: unknown): number | null;
+/**
+ * Parse the persisted doorbell sources for one camera. Tolerant of BOTH:
+ *   - the new `doorbellSources: [{deviceId}]` shape (ids may arrive as
+ *     numbers, numeric strings, or `{deviceId}` records); and
+ *   - the legacy single `doorbellSourceDeviceId` scalar, mapped onto one
+ *     source (the old trigger/eventType are dropped — the reaction is now
+ *     derived at runtime).
+ *
+ * Never throws on malformed data — unknown entries are skipped.
+ */
+export declare function parseDoorbellSources(blob: Record<string, unknown>): readonly DoorbellSource[];
+/**
+ * Normalize a settings-patch value for the `doorbellSources` multiselect
+ * (a `string[]` of device ids from the form, or an already-shaped
+ * `{deviceId}[]` / `number[]`) into the persisted extensible shape.
+ */
+export declare function normalizeDoorbellSources(value: unknown): DoorbellSource[];
+/**
+ * Produce the next device-store blob after applying a doorbell-sources
+ * patch: writes the normalized new shape and strips every legacy key so a
+ * migrated camera never carries stale single-source fields.
+ */
+export declare function applyDoorbellSourcesPatch(current: Record<string, unknown>, patchValue: unknown): Record<string, unknown>;

package/dist/builtins/doorbell/trigger-engine.d.ts

@@ -1,26 +1,35 @@
 /**
- * Pure trigger logic for the virtual-doorbell builtin — edge detection
- * over runtime-state slices, event-emitter matching, and per-camera
- * debounce. Extracted from the addon class (mirrors the
- * `snapshot-coalescing.ts` split) so the behaviour is unit-testable
- * without instantiating the addon or mocking the event bus.
+ * Pure trigger logic for the virtual-doorbell builtin — edge detection over
+ * runtime-state slices with per-camera debounce. Extracted from the addon
+ * class so the behaviour is unit-testable without instantiating the addon or
+ * mocking the event bus.
+ *
+ * REACTION MODEL (simplified — operator picks a source, the system reacts
+ * with a sensible default): a source device rings a camera's doorbell when a
+ * known binary / switch cap on it RISES to its active state (false→true) — a
+ * contact opening, a switch turning on, an alarm sensor firing. There is no
+ * per-source trigger configuration today; the shape stays extensible for a
+ * future custom-trigger override (see `doorbell-settings.ts`).
+ */
+/**
+ * Known binary / switch source caps → the boolean slice field whose
+ * false→true rise rings the doorbell. Every entry is "ring on active".
+ * Sensors whose "active" reading is not a plain boolean (presence's string
+ * state, connectivity's connected flag) are deliberately excluded — a
+ * reconnect is not a doorbell press.
  */
-/** Trigger kinds an operator can configure per camera. */
-export type DoorbellTrigger = 'contact-open' | 'contact-close' | 'switch-on' | 'event';
-export declare const DOORBELL_TRIGGERS: readonly DoorbellTrigger[];
-/** Type guard for {@link DoorbellTrigger}. */
-export declare function isDoorbellTrigger(value: unknown): value is DoorbellTrigger;
+export declare const SOURCE_CAP_ACTIVE_FIELD: Readonly<Record<string, string>>;
+/** Cap names whose presence in a device's bindings qualify it as a source. */
+export declare const SOURCE_CAPS: readonly string[];
+/** True when a cap is a recognised binary/switch doorbell source. */
+export declare function isSourceCap(capName: string): boolean;
 /**
- * One camera's virtual-doorbell wiring: which source device drives it,
- * on which trigger, and (for `trigger: 'event'`) which event type.
+ * One camera's virtual-doorbell wiring: a source device that rings it. A
+ * camera with several sources produces several assignments (one per source).
  */
 export interface DoorbellAssignment {
     readonly cameraId: number;
     readonly sourceDeviceId: number;
-    readonly trigger: DoorbellTrigger;
-    /** Only meaningful when `trigger === 'event'` — matched verbatim
-     *  against the event-emitter `onEvent` payload `eventType`. */
-    readonly eventType: string | null;
 }
 /** Debounce window guarding against sensor chatter (reed-switch bounce,
  *  duplicate HA state pushes). One ring per camera per window. */
@@ -29,10 +38,10 @@ export declare const DEFAULT_DEBOUNCE_MS = 2000;
  * Stateful (but side-effect-free towards the outside) trigger engine.
  *
  * Tracks the last observed binary value per (sourceDevice, cap) so a
- * `DeviceStateChanged` re-emission (the slice's `lastChangedAt` moves
- * while the binary value does not) never double-fires, and the FIRST
- * observation after boot only seeds the baseline — a state hydration
- * at startup must not ring anybody's doorbell.
+ * `DeviceStateChanged` re-emission (the slice's `lastChangedAt` moves while
+ * the binary value does not) never double-fires, and the FIRST observation
+ * after boot only seeds the baseline — a state hydration at startup must not
+ * ring anybody's doorbell.
  */
 export declare class DoorbellTriggerEngine {
     private assignments;
@@ -53,17 +62,10 @@ export declare class DoorbellTriggerEngine {
     hasSource(deviceId: number): boolean;
     /**
      * Feed one `DeviceStateChanged` slice. Returns the camera ids whose
-     * doorbell should ring (already debounced). Baseline-only sightings
-     * and non-transitions return an empty array.
+     * doorbell should ring (already debounced). Only a false→true rise on a
+     * recognised source cap fires; baseline-only sightings, re-emissions, and
+     * the falling edge return an empty array.
      */
     onStateSlice(deviceId: number, capName: string, slice: Record<string, unknown>): number[];
-    /**
-     * Feed one event-emitter `onEvent` firing. Returns the camera ids to
-     * ring — assignments with `trigger: 'event'`, a matching source and a
-     * verbatim `eventType` match. An assignment with no configured
-     * eventType never matches (misconfiguration must not ring on every
-     * event the device emits).
-     */
-    onEmitterEvent(deviceId: number, eventType: string): number[];
     private matchAndDebounce;
 }

package/dist/builtins/doorbell/virtual-doorbell.addon.d.ts

@@ -6,26 +6,29 @@ interface VirtualDoorbellAddonConfig {
 /**
  * VirtualDoorbellAddon — WRAPPER over the `doorbell` capability.
  *
- * Turns any binary-ish device (contact sensor, switch, event emitter,
- * flood/gas/CO sensor) into a doorbell for a camera:
+ * Turns any binary sensor or switch (contact, motion, flood/gas/CO/smoke,
+ * vibration, tamper, generic binary, or a switch) into a doorbell for a
+ * camera:
  *
  *   1. The operator binds the wrapper to a camera in the bindings UI
  *      (`defaultActive: false` — never auto-bound).
- *   2. Per-camera settings pick the SOURCE device + trigger
- *      (`contact-open` / `contact-close` / `switch-on` / `event`
- *      with an event-type match).
+ *   2. In the camera's GENERAL settings (next to "Linked devices") the
+ *      operator picks one or more SOURCE devices from a searchable list —
+ *      that is the ONLY choice. The reaction is derived automatically per
+ *      device type: a binary sensor rings when it goes active, a switch
+ *      rings when it turns on (see `trigger-engine.ts`). The persisted
+ *      shape (`doorbellSources: [{deviceId}]`) stays extensible for a
+ *      future custom-trigger override.
  *   3. At runtime the addon watches `EventCategory.DeviceStateChanged`
- *      (contact/switch slice transitions — EDGE detected per trigger)
- *      and `EventCategory.EventEmitted` (event-emitter firings). On a
- *      matching, debounced trigger it emits
- *      `EventCategory.DoorbellOnPressed` with the CAMERA as source
- *      (`{deviceId: cameraId, timestamp}` — the same shape Reolink's
- *      native `emitDoorbellPressed` produces) and bumps the camera's
- *      `doorbell` runtime-state counters via the standard
- *      `deviceState.setCapSlice` plumbing.
+ *      (binary/switch slice transitions — false→true edge detected). On a
+ *      matching, debounced rise it emits `EventCategory.DoorbellOnPressed`
+ *      with the CAMERA as source (`{deviceId: cameraId, timestamp}` — the
+ *      same shape Reolink's native `emitDoorbellPressed` produces) and
+ *      bumps the camera's `doorbell` runtime-state counters via the
+ *      standard `deviceState.setCapSlice` plumbing.
  *
  * Fires ONLY for cameras where the wrapper is BOUND (checked against
- * `deviceManager.getBindings`) and a source device is configured.
+ * `deviceManager.getBindings`) and at least one source device is configured.
  */
 export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddonConfig> {
     private readonly engine;
@@ -35,7 +38,6 @@ export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddon
     constructor();
     protected onInitialize(): Promise<ProviderRegistration[]>;
     private handleStateChanged;
-    private handleEmitterEvent;
     /**
      * Ring the camera's virtual doorbell: verify the wrapper is BOUND to
      * the camera, bump the `doorbell` runtime-state counters through the
@@ -62,7 +64,11 @@ export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddon
      * single source of truth, persisted across restarts).
      */
     private getStatus;
-    private readDeviceSettings;
+    /**
+     * The camera's configured doorbell sources, parsed tolerantly (new
+     * `doorbellSources` shape + legacy single-source migration).
+     */
+    private readDeviceSources;
     /**
      * Single-trip, non-throwing device lookup (mirrors snapshot's
      * `lookupDeviceMeta`). Null on any failure — callers fall back to
@@ -71,15 +77,26 @@ export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddon
      */
     private lookupDevice;
     /**
-     * Settings section for the device-detail page. Camera-only — the
-     * doorbell cap also applies to Button accessories (native providers),
-     * where a virtual-source picker is meaningless.
+     * Settings section for the device-detail page — contributed into the
+     * GENERAL settings surface (no `tab`, so it lands in the same tab as
+     * "Linked devices", ordered just after it). Camera-only: the doorbell
+     * cap also applies to Button accessories (native providers) where a
+     * virtual-source picker is meaningless.
+     *
+     * A SINGLE `multiselect` field lists every eligible binary/switch
+     * device; at ≥8 options the admin-ui form-builder auto-swaps it for the
+     * searchable multi-select (same idiom as "Linked devices"). The reaction
+     * is derived automatically per device type — no trigger/eventType
+     * controls.
      */
     private buildDeviceSettingsContribution;
     /**
-     * Cluster-wide picker options: every device whose BINDINGS expose one
-     * of the binary-ish source caps. Binding-sourced (not feature-flag
-     * sourced) because cap names are exactly what the runtime consumes.
+     * Cluster-wide picker options: every device whose BINDINGS expose one of
+     * the recognised binary/switch source caps. Binding-sourced (not
+     * feature-flag sourced) because cap names are exactly what the runtime
+     * consumes. Labelled `Name (Location)` (id carried in the option value)
+     * so the searchable multi-select matches on name, location, or id — the
+     * same shape "Linked devices" uses.
      */
     private listSourceDeviceOptions;
     private saveDeviceSettingsPatch;