@camstack/system 1.2.390 → 1.2.391

package/dist/builtins/alerts/alerts.addon.d.ts

@@ -1,92 +1,93 @@
-import { Alert, BaseAddon, ProviderRegistration } from '@camstack/types';
+import type { Alert, ConfigUISchema } from "@camstack/types";
+import { BaseAddon, type ProviderRegistration } from "@camstack/types";
 interface AlertCenterConfig {
-    readonly maxAlerts: number;
-    readonly retentionDays: number;
+	readonly maxAlerts: number;
+	readonly retentionDays: number;
 }
 export declare class AlertCenterAddon extends BaseAddon<AlertCenterConfig> {
-    private unsubscribers;
-    constructor();
-    /**
-     * Per `(category, source.id)` counter used to rate-limit chatty
-     * events. Entries are pruned lazily when they age out of
-     * `RATE_LIMIT_WINDOW_MS`; see `shouldSuppressByRate()` below.
-     */
-    private readonly rateLimitCounters;
-    protected onInitialize(): Promise<ProviderRegistration[]>;
-    protected onShutdown(): Promise<void>;
-    protected globalSettingsSchema(): import('@camstack/types').ConfigUISchema;
-    listAlerts(filter?: {
-        unreadOnly?: boolean;
-        limit?: number;
-    }): Promise<readonly Alert[]>;
-    getUnreadCount(): Promise<number>;
-    markRead(alertId: string): Promise<void>;
-    markAllRead(): Promise<void>;
-    dismiss(alertId: string): Promise<void>;
-    private handleEvent;
-    private handleModelDownload;
-    /**
-     * `[ALERT-CENTER-EVENTS]` — rate limit a `(category, source.id)`
-     * tuple. Returns `true` when the caller should DROP this event
-     * without persisting an alert, and `false` when the alert should
-     * proceed normally.
-     *
-     * Heuristic: the first `RATE_LIMIT_MAX_PER_SOURCE` events within a
-     * `RATE_LIMIT_WINDOW_MS` window go through. Once the threshold is
-     * crossed, subsequent events are suppressed until the window rolls
-     * over. When the threshold is first crossed, the suppression is
-     * logged once so operators know why they're not seeing the follow-
-     * up alerts; after the window rolls over the next event is
-     * un-suppressed and starts a new window.
-     */
-    private shouldSuppressByRate;
-    /**
-     * AddonLoadFailed — kernel's AddonHealthMonitor has post-grace
-     * failed an addon load/init. Upsert a stable-id alert keyed by
-     * `addon-load-failed:<packageName>` so the recovery path can
-     * dismiss it. Severity=error, persistent until dismissed or
-     * auto-resolved.
-     *
-     * The action `retry` carries the package name so the admin UI can
-     * dispatch `addons.retryLoad(packageName)` directly from the alert
-     * card without the operator opening the Addons page.
-     */
-    private handleAddonLoadFailed;
-    /**
-     * AddonLoadRecovered — addon previously alerting is back to healthy.
-     * Dismiss the matching alert so the operator's badge count drops.
-     */
-    private handleAddonLoadRecovered;
-    /**
-     * SystemLivenessFailed — a liveness invariant of this node is false.
-     *
-     * `findingId` is already stable across ticks (`liveness:no-devices`,
-     * `liveness:no-footage:<deviceId>`, …), so it IS the alert id: an ongoing
-     * fault updates one alert instead of producing one every five minutes.
-     */
-    private handleLivenessFailed;
-    /** SystemLivenessRecovered — the invariant holds again; drop the alert. */
-    private handleLivenessRecovered;
-    /**
-     * Stream offline — ONLY `stale-timeout` is an outage. Suspend / destroy /
-     * idle dial are deliberate and must not ring the bell (same gate NC uses).
-     */
-    private handleStreamOffline;
-    /** Stream online after an outage — drop the matching offline card. */
-    private handleStreamOnline;
-    private resolveDeviceName;
-    private buildMessage;
-    private emitAlert;
-    private updateAlert;
-    /**
-     * Read-merge-write: SettingsBackend.update() replaces the entire `data` blob,
-     * so we must read the existing record, merge the patch, and write back.
-     */
-    private mergeUpdate;
-    private persistAlert;
-    private emitAlertCreatedEvent;
-    private emitAlertUpdatedEvent;
-    private enforceMaxAlerts;
-    private enforceRetention;
+	private unsubscribers;
+	constructor();
+	/**
+	* Per `(category, source.id)` counter used to rate-limit chatty
+	* events. Entries are pruned lazily when they age out of
+	* `RATE_LIMIT_WINDOW_MS`; see `shouldSuppressByRate()` below.
+	*/
+	private readonly rateLimitCounters;
+	protected onInitialize(): Promise<ProviderRegistration[]>;
+	protected onShutdown(): Promise<void>;
+	protected globalSettingsSchema(): ConfigUISchema;
+	listAlerts(filter?: {
+		unreadOnly?: boolean;
+		limit?: number;
+	}): Promise<readonly Alert[]>;
+	getUnreadCount(): Promise<number>;
+	markRead(alertId: string): Promise<void>;
+	markAllRead(): Promise<void>;
+	dismiss(alertId: string): Promise<void>;
+	private handleEvent;
+	private handleModelDownload;
+	/**
+	* `[ALERT-CENTER-EVENTS]` — rate limit a `(category, source.id)`
+	* tuple. Returns `true` when the caller should DROP this event
+	* without persisting an alert, and `false` when the alert should
+	* proceed normally.
+	*
+	* Heuristic: the first `RATE_LIMIT_MAX_PER_SOURCE` events within a
+	* `RATE_LIMIT_WINDOW_MS` window go through. Once the threshold is
+	* crossed, subsequent events are suppressed until the window rolls
+	* over. When the threshold is first crossed, the suppression is
+	* logged once so operators know why they're not seeing the follow-
+	* up alerts; after the window rolls over the next event is
+	* un-suppressed and starts a new window.
+	*/
+	private shouldSuppressByRate;
+	/**
+	* AddonLoadFailed — kernel's AddonHealthMonitor has post-grace
+	* failed an addon load/init. Upsert a stable-id alert keyed by
+	* `addon-load-failed:<packageName>` so the recovery path can
+	* dismiss it. Severity=error, persistent until dismissed or
+	* auto-resolved.
+	*
+	* The action `retry` carries the package name so the admin UI can
+	* dispatch `addons.retryLoad(packageName)` directly from the alert
+	* card without the operator opening the Addons page.
+	*/
+	private handleAddonLoadFailed;
+	/**
+	* AddonLoadRecovered — addon previously alerting is back to healthy.
+	* Dismiss the matching alert so the operator's badge count drops.
+	*/
+	private handleAddonLoadRecovered;
+	/**
+	* SystemLivenessFailed — a liveness invariant of this node is false.
+	*
+	* `findingId` is already stable across ticks (`liveness:no-devices`,
+	* `liveness:no-footage:<deviceId>`, …), so it IS the alert id: an ongoing
+	* fault updates one alert instead of producing one every five minutes.
+	*/
+	private handleLivenessFailed;
+	/** SystemLivenessRecovered — the invariant holds again; drop the alert. */
+	private handleLivenessRecovered;
+	/**
+	* Stream offline — ONLY `stale-timeout` is an outage. Suspend / destroy /
+	* idle dial are deliberate and must not ring the bell (same gate NC uses).
+	*/
+	private handleStreamOffline;
+	/** Stream online after an outage — drop the matching offline card. */
+	private handleStreamOnline;
+	private resolveDeviceName;
+	private buildMessage;
+	private emitAlert;
+	private updateAlert;
+	/**
+	* Read-merge-write: SettingsBackend.update() replaces the entire `data` blob,
+	* so we must read the existing record, merge the patch, and write back.
+	*/
+	private mergeUpdate;
+	private persistAlert;
+	private emitAlertCreatedEvent;
+	private emitAlertUpdatedEvent;
+	private enforceMaxAlerts;
+	private enforceRetention;
 }
 export default AlertCenterAddon;

package/dist/builtins/alerts/device-label.d.ts

@@ -1,8 +1,8 @@
 /**
- * Operator-facing device label for alert messages.
- *
- * Prefer a real name; fall back to `Camera <id>` only when nothing else is
- * known. Never prefer the bare id when a name is present — "Camera 618"
- * next to a named "Cucina" is how the Recording-stopped alerts used to read.
- */
+* Operator-facing device label for alert messages.
+*
+* Prefer a real name; fall back to `Camera <id>` only when nothing else is
+* known. Never prefer the bare id when a name is present — "Camera 618"
+* next to a named "Cucina" is how the Recording-stopped alerts used to read.
+*/
 export declare function deviceLabelFromEventData(data: Readonly<Record<string, unknown>>): string;

package/dist/builtins/alerts/index.d.ts

@@ -1 +1 @@
-export { AlertCenterAddon } from './alerts.addon.js';
+export { AlertCenterAddon } from "./alerts.addon.js";

package/dist/builtins/alerts/prune-policy.d.ts

@@ -1,44 +1,44 @@
 /**
- * prune-policy — which alerts get deleted, as a pure decision.
- *
- * ## The bug this exists to prevent
- *
- * Both prune paths filtered `where: { read: true }`. On a live hub every one of
- * 2,288 rows was UNREAD, so neither path had ever deleted anything — at roughly
- * 128 new alerts a day, with `maxAlerts` and `retentionDays` both configured and
- * both inert. A cap that only bounds rows a human has clicked is not a cap, and
- * "retention (days)" that ignores age is not retention.
- *
- * The decision is extracted here because both callers were private methods
- * inside the addon, reachable only through a running store — so the rule nobody
- * could test is exactly the rule that was wrong.
- *
- * ## The two rules, and why they differ
- *
- *  - **Age** ignores read state entirely. An alert past the retention window is
- *    expired whether or not anyone looked at it; that is what the operator set
- *    the number for.
- *  - **The cap** still PREFERS read alerts — an unread alert is more likely to
- *    matter, so it should be the last to go — but it must not stop there. Once
- *    the read ones are exhausted it keeps taking the oldest, or the cap silently
- *    is not one.
- */
+* prune-policy — which alerts get deleted, as a pure decision.
+*
+* ## The bug this exists to prevent
+*
+* Both prune paths filtered `where: { read: true }`. On a live hub every one of
+* 2,288 rows was UNREAD, so neither path had ever deleted anything — at roughly
+* 128 new alerts a day, with `maxAlerts` and `retentionDays` both configured and
+* both inert. A cap that only bounds rows a human has clicked is not a cap, and
+* "retention (days)" that ignores age is not retention.
+*
+* The decision is extracted here because both callers were private methods
+* inside the addon, reachable only through a running store — so the rule nobody
+* could test is exactly the rule that was wrong.
+*
+* ## The two rules, and why they differ
+*
+*  - **Age** ignores read state entirely. An alert past the retention window is
+*    expired whether or not anyone looked at it; that is what the operator set
+*    the number for.
+*  - **The cap** still PREFERS read alerts — an unread alert is more likely to
+*    matter, so it should be the last to go — but it must not stop there. Once
+*    the read ones are exhausted it keeps taking the oldest, or the cap silently
+*    is not one.
+*/
 /** The fields the policy needs. Anything else on the record is irrelevant. */
 export interface PrunableAlert {
-    readonly id: string;
-    readonly createdAt: number;
-    readonly read: boolean;
+	readonly id: string;
+	readonly createdAt: number;
+	readonly read: boolean;
 }
 /**
- * Ids older than `cutoffMs`, oldest first.
- *
- * Read state is deliberately NOT consulted — that filter is the defect.
- */
+* Ids older than `cutoffMs`, oldest first.
+*
+* Read state is deliberately NOT consulted — that filter is the defect.
+*/
 export declare function selectExpired(alerts: readonly PrunableAlert[], cutoffMs: number): readonly string[];
 /**
- * Ids to drop so at most `maxAlerts` remain: read ones first (oldest first),
- * then unread ones (oldest first) if that was not enough.
- *
- * Returns empty when already within the cap, and never more than the excess.
- */
+* Ids to drop so at most `maxAlerts` remain: read ones first (oldest first),
+* then unread ones (oldest first) if that was not enough.
+*
+* Returns empty when already within the cap, and never more than the excess.
+*/
 export declare function selectOverflow(alerts: readonly PrunableAlert[], maxAlerts: number): readonly string[];

package/dist/builtins/autotrack/autotrack-cameras.d.ts

@@ -1,102 +1,125 @@
-import { FirstLevelMacroClass, PtzAutotrackSettings, PtzAutotrackStatus } from '@camstack/types';
-import { AutotrackLoopConfig } from './autotrack-config.js';
 /**
- * How much of the frame the subject SHOULD occupy, and nothing else about zoom.
- *
- * Hidden on purpose (operator, 2026-09-18: *"rendiamo lo zoom configurabile,
- * nascosto per ora, ci lavoriamo poi quando ne vedo il bisogno"* [let us make the zoom configurable, hidden for now, we will work on it later when I see the need]). It is not in
- * `PtzAutotrackSettings` — that schema is the cross-vendor surface the device
- * page renders, and putting it there would SHOW a control nothing implements.
- * It lives in this addon's own record instead: settable, persisted, invisible.
- *
- * `null` means the loop does not touch zoom at all, which is what every camera
- * gets until somebody decides otherwise.
- */
+* What this addon persists per camera, and how the cap's cross-vendor settings
+* become this loop's tuning.
+*
+* ## Why the record lives here and not in the cap's runtime state
+*
+* `ptz-autotrack` declares `durability: 'session'` — its slice MIRRORS a
+* camera's own autotrack config and is re-read on connect. For a native
+* provider that is right: the firmware is the record. For the emulated
+* implementation there is no firmware to re-read, so the slice would come back
+* empty on every restart and a camera the operator armed would come up
+* disarmed, silently. The record is therefore ours, in the addon's own
+* settings, and the cap's `getStatus` reads it.
+*
+* ## One switch, not two (D62, D520)
+*
+* Binding this wrapper to a camera chooses the IMPLEMENTATION.
+* `setEnabled` is the switch for the function, and
+* it is the cap's own switch: a camera with firmware autotrack uses its native
+* provider for exactly the same method, so the operator never sees two
+* controls that can disagree.
+*/
+import { type FirstLevelMacroClass } from "@camstack/types";
+import type { PtzAutotrackSettings, PtzAutotrackStatus } from "@camstack/types";
+import { type AutotrackLoopConfig } from "./autotrack-config.js";
+/**
+* How much of the frame the subject SHOULD occupy, and nothing else about zoom.
+*
+* Hidden on purpose (operator, 2026-09-18: *"rendiamo lo zoom configurabile,
+* nascosto per ora, ci lavoriamo poi quando ne vedo il bisogno"* [let us make the zoom configurable, hidden for now, we will work on it later when I see the need]). It is not in
+* `PtzAutotrackSettings` — that schema is the cross-vendor surface the device
+* page renders, and putting it there would SHOW a control nothing implements.
+* It lives in this addon's own record instead: settable, persisted, invisible.
+*
+* `null` means the loop does not touch zoom at all, which is what every camera
+* gets until somebody decides otherwise.
+*/
 export interface AutotrackZoomSetting {
-    /**
-     * Target share of the frame for the tracked subject's box, `0..1`.
-     *
-     * The operator's original ask was "keep the target at about 50% of frame",
-     * so 0.5 is the number this exists to hold. It is a FRACTION OF AREA on the
-     * frame the loop measures in, not a zoom level: the loop is declaredly
-     * visual and never learns where the optics are (D520).
-     */
-    readonly targetSubjectFraction: number | null;
+	/**
+	* Target share of the frame for the tracked subject's box, `0..1`.
+	*
+	* The operator's original ask was "keep the target at about 50% of frame",
+	* so 0.5 is the number this exists to hold. It is a FRACTION OF AREA on the
+	* frame the loop measures in, not a zoom level: the loop is declaredly
+	* visual and never learns where the optics are (D520).
+	*/
+	readonly targetSubjectFraction: number | null;
 }
 /** One camera's record. */
 export interface AutotrackCameraRecord {
-    readonly enabled: boolean;
-    readonly settings: PtzAutotrackSettings;
-    readonly zoom: AutotrackZoomSetting;
+	readonly enabled: boolean;
+	readonly settings: PtzAutotrackSettings;
+	readonly zoom: AutotrackZoomSetting;
 }
 /** deviceId → record. */
 export type AutotrackCameraRecords = Readonly<Record<number, AutotrackCameraRecord>>;
 /**
- * The defaults a camera starts from.
- *
- * `disappearDelaySeconds` matches the loop's own default so the two cannot
- * disagree on the day nobody has opened the form. `stopDelaySeconds` is
- * persisted and NOT honoured — see {@link loopConfigFor}.
- */
+* The defaults a camera starts from.
+*
+* `disappearDelaySeconds` matches the loop's own default so the two cannot
+* disagree on the day nobody has opened the form. `stopDelaySeconds` is
+* persisted and NOT honoured — see {@link loopConfigFor}.
+*/
 export declare const DEFAULT_CAMERA_RECORD: AutotrackCameraRecord;
 /**
- * What this implementation can follow, as the cap's target options.
- *
- * A vendor list would be a lie here: the emulated loop follows what the
- * DETECTOR emits, and the detector's first-level macro classes are these
- * three. Reolink's `people` and Hikvision's `human` are vendor words for the
- * same thing and are normalised in {@link targetClassFor} rather than offered.
- */
-export declare const EMULATED_TARGET_OPTIONS: PtzAutotrackStatus['supportedTargetTypes'];
+* What this implementation can follow, as the cap's target options.
+*
+* A vendor list would be a lie here: the emulated loop follows what the
+* DETECTOR emits, and the detector's first-level macro classes are these
+* three. Reolink's `people` and Hikvision's `human` are vendor words for the
+* same thing and are normalised in {@link targetClassFor} rather than offered.
+*/
+export declare const EMULATED_TARGET_OPTIONS: PtzAutotrackStatus["supportedTargetTypes"];
 /**
- * Why this camera's zoom request is not being honoured, or `null` when it asked
- * for nothing.
- *
- * A setting that is read and ignored in silence is indistinguishable from a
- * broken one, and this one WILL be read by a loop that cannot act on it yet.
- * So asking for it produces a sentence naming the number and what is missing.
- */
+* Why this camera's zoom request is not being honoured, or `null` when it asked
+* for nothing.
+*
+* A setting that is read and ignored in silence is indistinguishable from a
+* broken one, and this one WILL be read by a loop that cannot act on it yet.
+* So asking for it produces a sentence naming the number and what is missing.
+*/
 export declare function zoomRefusalFor(record: AutotrackCameraRecord): string | null;
 export declare function parseCameraRecords(raw: unknown): AutotrackCameraRecords;
 /** Immutable per-camera patch — a NEW map, the previous one untouched. */
 export declare function withCameraPatch(records: AutotrackCameraRecords, deviceId: number, patch: {
-    enabled?: boolean;
-    settings?: Partial<PtzAutotrackSettings>;
-    zoom?: Partial<AutotrackZoomSetting>;
+	enabled?: boolean;
+	settings?: Partial<PtzAutotrackSettings>;
+	zoom?: Partial<AutotrackZoomSetting>;
 }): AutotrackCameraRecords;
 /**
- * The detection macro class this camera follows.
- *
- * `''` is the cap's "camera default" and means PERSON here — the class an
- * autotrack is asked for in almost every case, and the one the measurement
- * slice used. A vendor string (`people`, `human`) normalises to the macro it
- * names; anything else falls back to person rather than following nothing,
- * because a loop that silently follows nothing is indistinguishable from one
- * that is broken.
- */
+* The detection macro class this camera follows.
+*
+* `''` is the cap's "camera default" and means PERSON here — the class an
+* autotrack is asked for in almost every case, and the one the measurement
+* slice used. A vendor string (`people`, `human`) normalises to the macro it
+* names; anything else falls back to person rather than following nothing,
+* because a loop that silently follows nothing is indistinguishable from one
+* that is broken.
+*/
 export declare function targetClassFor(settings: PtzAutotrackSettings): FirstLevelMacroClass;
 /**
- * The loop's config for this camera.
- *
- * Only ONE of the cap's three settings reaches the loop:
- *
- * - `disappearDelaySeconds` → {@link AutotrackLoopConfig.disappearDelayMs}. Same
- *   meaning on both sides: how long a target that stopped appearing is held
- *   before it is released and the head goes home.
- * - `targetType` → the detection class, through {@link targetClassFor}.
- * - `stopDelaySeconds` is persisted and NOT honoured. It means "keep tracking a
- *   STATIONARY target for this long before stopping", and a pulse-based loop
- *   already does nothing while the subject is inside the dead zone — there is
- *   no motion to stop. Storing it and ignoring it is deliberate: the cap is
- *   cross-vendor, a native provider honours it, and dropping it from the
- *   payload would make a camera that switches from native to emulated lose a
- *   setting it had. It is reported back by `getStatus` verbatim, never as a
- *   number this loop acted on.
- *
- * Everything else in the loop config is a TUNING CONSTANT that D520 kept out of
- * the operator surface on purpose (dead zone, settle zone, command ceiling,
- * pulse dead time). They stay constants.
- */
+* The loop's config for this camera.
+*
+* Only ONE of the cap's three settings reaches the loop:
+*
+* - `disappearDelaySeconds` → {@link AutotrackLoopConfig.disappearDelayMs}. Same
+*   meaning on both sides: how long a target that stopped appearing is held
+*   before it is released and the head goes home.
+* - `targetType` → the detection class, through {@link targetClassFor}.
+* - `stopDelaySeconds` is persisted and NOT honoured. It means "keep tracking a
+*   STATIONARY target for this long before stopping", and a pulse-based loop
+*   already does nothing while the subject is inside the dead zone — there is
+*   no motion to stop. Storing it and ignoring it is deliberate: the cap is
+*   cross-vendor, a native provider honours it, and dropping it from the
+*   payload would make a camera that switches from native to emulated lose a
+*   setting it had. It is reported back by `getStatus` verbatim, never as a
+*   number this loop acted on.
+*
+* Everything else in the loop config is a TUNING CONSTANT that D520 kept out of
+* the operator surface on purpose (dead zone, settle zone, command ceiling,
+* pulse dead time). They stay constants.
+*/
 export declare function loopConfigFor(settings: PtzAutotrackSettings): AutotrackLoopConfig;
 /** The cap's status for one camera. */
 export declare function statusFor(record: AutotrackCameraRecord, lastChangedAt: number): PtzAutotrackStatus;