@camstack/types 1.2.140 → 1.2.142

package/dist/index.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_event_category = require("./event-category-BaEgqJNv.js");
-const require_sleep = require("./sleep-BwGJ_wL_.js");
+const require_sleep = require("./sleep-BDmIj1HV.js");
 const require_canonical_hash = require("./canonical-hash-DNV8S5ET.js");
 const require_enums = require("./enums.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
@@ -6616,6 +6616,89 @@ var LocationStatSchema = zod.z.object({
 	fileCount: zod.z.number(),
 	present: zod.z.boolean()
 });
+/** Lifecycle of a backup run. Terminal states: succeeded / failed / cancelled. */
+var BackupRunStateSchema = zod.z.enum([
+	"queued",
+	"running",
+	"succeeded",
+	"failed",
+	"cancelled"
+]);
+/**
+* Where a running backup currently is. `queued` before it starts,
+* `building` while the tar.gz is being staged, `uploading` during the
+* per-destination fan-out, `done` once terminal.
+*/
+var BackupRunPhaseSchema = zod.z.enum([
+	"queued",
+	"building",
+	"uploading",
+	"done"
+]);
+/**
+* Observable state of one backup run — readable WHILE it runs via
+* `backup.listRuns`. This is what makes the execution queue and
+* `backup.cancel` usable: the 2026-09-04 incident (two concurrent
+* multi-GB builds, staging 5.1 GB → 18 GB, load 62) was only
+* diagnosable with `du` because nothing reported that runs existed or
+* how large the staged archive had grown.
+*/
+var BackupRunSchema = zod.z.object({
+	/** Stable run id — the handle `backup.cancel` takes. */
+	id: zod.z.string(),
+	state: BackupRunStateSchema,
+	phase: BackupRunPhaseSchema,
+	/**
+	* Resolved destination location ids. Empty while queued (targets are
+	* resolved when the run starts, against the then-current policies).
+	*/
+	destinationIds: zod.z.array(zod.z.string()).readonly(),
+	label: zod.z.string().optional(),
+	/** ms-epoch when the run was submitted (trigger call / schedule fire). */
+	requestedAt: zod.z.number(),
+	/** ms-epoch when the run left the queue and started building. */
+	startedAt: zod.z.number().optional(),
+	/** ms-epoch when the run reached a terminal state. */
+	finishedAt: zod.z.number().optional(),
+	/** Compressed bytes of the staging archive written so far. */
+	stagedBytes: zod.z.number(),
+	/** Final staged archive size, once the build phase completes. */
+	archiveSizeBytes: zod.z.number().optional(),
+	/** Bytes pushed to the destination currently uploading. */
+	uploadedBytes: zod.z.number(),
+	/** Destinations where the archive fully landed (uploaded + indexed). */
+	completedDestinationIds: zod.z.array(zod.z.string()).readonly(),
+	/** Destinations that failed during the fan-out. */
+	failedDestinationIds: zod.z.array(zod.z.string()).readonly(),
+	/** Failure message when `state === 'failed'`. */
+	error: zod.z.string().optional(),
+	/**
+	* 1-based place in the execution queue — 1 = runs next. Present only
+	* while `state === 'queued'`. Stamped by the orchestrator from the
+	* queue's OWN pending order, never derived from timestamps, so the
+	* UI cannot show an order the executor will not honour.
+	*/
+	queuePosition: zod.z.number().int().min(1).optional()
+});
+/**
+* Result of `backup.trigger`. The call still resolves when the run
+* terminates (compat with schedule-driven runs and the admin UI), but
+* it now names the run and says whether it had to WAIT: a trigger that
+* arrives while another run is in flight is enqueued (or joined onto
+* an identical already-queued run), never started concurrently.
+*/
+var BackupTriggerResultSchema = zod.z.object({
+	/** The run this trigger mapped to — poll it via `listRuns`, stop it via `cancel`. */
+	runId: zod.z.string(),
+	/** True when the run waited behind an in-flight run instead of starting immediately. */
+	queued: zod.z.boolean(),
+	/** True when this trigger was coalesced onto an identical already-queued run. */
+	joined: zod.z.boolean(),
+	/** True when the run was cancelled before completing every destination. */
+	cancelled: zod.z.boolean(),
+	/** One entry per destination the archive landed at (partial on cancel). */
+	entries: zod.z.array(BackupEntrySchema).readonly()
+});
 /**
 * A backup schedule — the N:M "entry" that binds one cron cadence to a
 * SET of destination locations. Supersedes the per-location cron on
@@ -6673,6 +6756,11 @@ var backupCapability = {
 		* Trigger a backup. Without `destinations` the orchestrator fans
 		* out to every destination flagged as enabled in the routing
 		* config; with it, only the listed addons receive the archive.
+		*
+		* At most ONE backup run executes at a time — the source tree and
+		* the staging disk are shared by every run, so a second trigger
+		* while one is in flight is enqueued (or joined onto an identical
+		* queued run) and the result says so. See D342.
 		*/
 		trigger: require_sleep.method(zod.z.object({
 			/** Subset of registered `backup-destination` addon ids to write to. */
@@ -6686,7 +6774,30 @@ var backupCapability = {
 			* retention (manual runs).
 			*/
 			retentionCount: zod.z.number().int().min(1).max(1e3).optional()
-		}).optional(), zod.z.array(BackupEntrySchema).readonly(), {
+		}).optional(), BackupTriggerResultSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Every run the orchestrator knows about, in EXECUTION order: the
+		* running run first, then queued runs in the exact order they will
+		* execute (each with `queuePosition`, 1 = next), then the bounded
+		* finished history newest-first. Only one run executes at a time
+		* (D342) — the queued section IS the line. Each run carries live
+		* phase + byte counters so a runaway build is visible in seconds,
+		* not via `du`.
+		*/
+		listRuns: require_sleep.method(zod.z.void(), zod.z.array(BackupRunSchema).readonly(), { auth: "admin" }),
+		/**
+		* Stop a backup run. Mirrors `storage-migration.cancel` semantics:
+		* id in, `{ cancelled }` out — `false` when the run is unknown or
+		* already terminal. A QUEUED run is removed before it ever starts;
+		* the RUNNING run has its tar/upload stream actually aborted, the
+		* half-written staging archive is deleted, and the in-flight
+		* destination upload is aborted server-side (partial discarded).
+		* Destinations that already completed keep their archive.
+		*/
+		cancel: require_sleep.method(zod.z.object({ runId: zod.z.string() }), zod.z.object({ cancelled: zod.z.boolean() }), {
 			kind: "mutation",
 			auth: "admin"
 		}),
@@ -7570,6 +7681,38 @@ var streamBrokerCapability = {
 			auth: "admin"
 		}),
 		/**
+		* The HARDWARE behind a device number was replaced
+		* (`deviceManager.migrateDevice`). Forget every piece of broker state that
+		* described the old box, so the next catalog pull derives everything from
+		* the camera that is actually there:
+		*
+		*  - every `derived:*` stream definition — a derived is authored against a
+		*    specific profile layout, and against the wrong hardware its feeder
+		*    respawns forever (observed at attempt 2732 on the live hub,
+		*    2026-09-01);
+		*  - the profile-slot assignment entry, PURGED (not unassigned — unassign
+		*    marks the slot manual, which would pin the stale choice instead of
+		*    letting `computeInitialAssignment` re-derive it);
+		*  - the probe snapshots (`<deviceId>/…` — probed codec/resolution of the
+		*    old hardware);
+		*  - the persisted RTSP token rows for the device's brokers (keyed
+		*    `<deviceId>/<camStreamId>`; the stream ids change with the hardware,
+		*    so the rows are dead URLs).
+		*
+		* An RPC, deliberately — an event is telemetry and may be dropped (D8),
+		* and a dropped forget leaves a feeder respawning against a stream that
+		* does not exist.
+		*/
+		forgetDeviceHardware: require_sleep.method(zod.z.object({ deviceId: zod.z.number().int().nonnegative() }), zod.z.object({
+			derivedStreamsDeleted: zod.z.array(zod.z.string()).readonly(),
+			assignmentsPurged: zod.z.boolean(),
+			probeSnapshotsDropped: zod.z.number().int().nonnegative(),
+			rtspTokenRowsDeleted: zod.z.number().int().nonnegative()
+		}), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
 		* Render a short GIF or MP4 from the broker's PRE-BUFFER around an instant.
 		*
 		* The pre-buffer is the only source that already holds the seconds BEFORE
@@ -18783,7 +18926,20 @@ var RecentTracksQueryInput = zod.z.object({
 	projection: TrackProjectionSchema.optional(),
 	/** Include stationary-promoted rows (parked objects). Default false: the
 	*  feed lists passages; parking records live on the stationary registry. */
-	includeStationary: zod.z.boolean().optional()
+	includeStationary: zod.z.boolean().optional(),
+	/**
+	* Restrict to these track classes. ABSENT or EMPTY means no filter.
+	*
+	* The same filter `listTracks` takes, because the timeline's class chips must
+	* mean the same thing whether the scope is one camera or twelve. Until this
+	* existed the scoped feed downloaded a page and narrowed it on the phone
+	* while the single-camera path narrowed the read — one filter, two costs.
+	*
+	* A SUPERSET prefilter on `classes[]`, like its single-camera twin: rows
+	* whose class list is unreadable are kept, and the client's rule stays the
+	* exact one.
+	*/
+	classes: zod.z.array(zod.z.string()).optional()
 });
 var RecentTracksPageSchema = zod.z.object({
 	/** Merged page, ordered by (`lastSeen` DESC, `trackId` DESC). */
@@ -25123,8 +25279,22 @@ var automationControlCapability = {
 * threshold.
 */
 var BatteryStatusSchema = zod.z.object({
-	/** 0..100 inclusive. Firmware-reported. */
-	percentage: zod.z.number().min(0).max(100),
+	/**
+	* 0..100 inclusive, firmware-reported. **`null` means NOT YET KNOWN** — the
+	* provider has registered the capability but no reading has landed.
+	*
+	* It is nullable because it was not, and the only value a provider could
+	* seed with was `0`. A battery camera behind an NVR therefore announced
+	* itself at 0% on every start and corrected itself a moment later, which is
+	* indistinguishable from a real flat battery: it fires the low-battery alert
+	* every time the hub restarts. Unknown is not empty (D315), and on a battery
+	* reading the difference is an alarm.
+	*
+	* `vacuum-control` and `lawn-mower-control` already model it this way.
+	* Consumers must SKIP a null rather than coerce it — `battery-band` already
+	* declines to band a non-finite reading, which is the correct shape.
+	*/
+	percentage: zod.z.number().min(0).max(100).nullable(),
 	/**
 	* Charging source. `'dc'` covers wall/USB adapters; `'solar'` is
 	* Reolink-specific for the Solar Panel 2 accessory (will become
@@ -35273,6 +35443,15 @@ var RUNTIME_DEFAULTS = {
 * Each carried the same list and a comment asking the others to stay in sync.
 * This is that list, in the one package all of them already depend on.
 *
+* `ui-library` and the server's linked-devices expansion IMPORT it. Two
+* consumers cannot, and keep a checked copy instead: the viewer resolves
+* `@camstack/types` from its own `node_modules` (an installed release, where a
+* newly added export simply is not there), and the Home Assistant provider
+* expresses the same precedence over the `DeviceType` enum because it answers
+* a different question from the same ordering. `scripts/check-container-
+* priority-in-sync.ts` fails the build when either drifts — the comment that
+* used to ask for this could not.
+*
 * The rule has two halves and the ORDER matters: an operator's explicit pick
 * wins outright, and only in its absence does type priority decide. The pick is
 * keyed on the child's re-sync-stable `entityId`, not its numeric id, so it
@@ -35328,7 +35507,7 @@ function rank(type) {
 */
 function resolveContainerPrimaryChild(children, overrideEntityId) {
 	if (overrideEntityId !== void 0 && overrideEntityId !== null) {
-		const picked = children.find((c) => c.entityId === overrideEntityId);
+		const picked = children.find((c) => c.stableId === overrideEntityId) ?? children.find((c) => c.entityId !== void 0 && c.entityId === overrideEntityId);
 		if (picked !== void 0) return picked;
 	}
 	return [...children].toSorted((a, b) => rank(a.type) - rank(b.type))[0] ?? null;
@@ -39600,6 +39779,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"backup.cancel": {
+		capName: "backup",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"backup.delete": {
 		capName: "backup",
 		capScope: "system",
@@ -39642,6 +39827,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"backup.listRuns": {
+		capName: "backup",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"backup.listSchedules": {
 		capName: "backup",
 		capScope: "system",
@@ -44208,6 +44399,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.forgetDeviceHardware": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "delete"
+	},
 	"streamBroker.getAllRtspEntries": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -46929,6 +47126,11 @@ var METHOD_DEVICE_SELECTORS = Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"streamBroker.forgetDeviceHardware": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"streamBroker.getDeviceAudioMute": [{
 		name: "deviceId",
 		form: "single",
@@ -47302,6 +47504,7 @@ var SYSTEM_SCOPE_DEVICE_METHODS = [
 	"recordingExport.listExports",
 	"streamBroker.acquireEgressTranscode",
 	"streamBroker.assignProfile",
+	"streamBroker.forgetDeviceHardware",
 	"streamBroker.getDeviceAudioMute",
 	"streamBroker.getStreamWithCodec",
 	"streamBroker.produceEventMedia",
@@ -47845,6 +48048,8 @@ function createSystemProxy(api) {
 		backup: {
 			listDestinations: (input) => dispatch("backup", "listDestinations", "query", input),
 			trigger: (input) => dispatch("backup", "trigger", "mutation", input),
+			listRuns: (input) => dispatch("backup", "listRuns", "query", input),
+			cancel: (input) => dispatch("backup", "cancel", "mutation", input),
 			list: (input) => dispatch("backup", "list", "query", input),
 			listLocations: (input) => dispatch("backup", "listLocations", "query", input),
 			getEntries: (input) => dispatch("backup", "getEntries", "query", input),
@@ -52414,6 +52619,10 @@ exports.BOOT_RECOVERY_BACKOFF_MS = require_sleep.BOOT_RECOVERY_BACKOFF_MS;
 exports.BacklightModeSchema = BacklightModeSchema;
 exports.BackupDestinationInfoSchema = BackupDestinationInfoSchema;
 exports.BackupEntrySchema = BackupEntrySchema;
+exports.BackupRunPhaseSchema = BackupRunPhaseSchema;
+exports.BackupRunSchema = BackupRunSchema;
+exports.BackupRunStateSchema = BackupRunStateSchema;
+exports.BackupTriggerResultSchema = BackupTriggerResultSchema;
 exports.BaseAddon = require_sleep.BaseAddon;
 exports.BaseDevice = BaseDevice;
 exports.BaseDeviceProvider = BaseDeviceProvider;