@camstack/system 1.2.81 → 1.2.82

package/dist/{dist-DZOZtn-0.mjs → dist-DpL4mUA4.mjs}

@@ -3305,8 +3305,31 @@ var AdoptionJobSchema = z.object({
 	error: z.string().nullable()
 });
 /**
-* Per-camera FUNCTION SWITCHES — the one coherent on/off surface over the
-* pipeline functions an operator thinks in terms of.
+* Per-camera FUNCTION SWITCHES.
+*
+* ## The aggregate group is being withdrawn — the BADGE is not (D113)
+*
+* This file shipped as "the one coherent on/off surface over the pipeline
+* functions an operator thinks in terms of". The operator's verdict on
+* 2026-08-12 was that the coherent surface bought complexity and no clarity:
+* every function already had a settings page of its own, and a second place to
+* turn it off is a second place to look. Each switch is going back to its own
+* component's original options — detection to the detection-pipeline wrapper
+* binding, audio analysis to its own, recording to `RecordingConfig.enabled`
+* (which was always first-class; the switch was a veneer over
+* `recording.setDeviceConfig`), notifications to a notification-center
+* per-device setting, the two camera planes to their own components.
+*
+* What survives is {@link composeSwitchedOff}: `CameraStatus.switchedOff`, the
+* thing that lets a status surface say DISABLED instead of BROKEN, recomposed
+* straight from the authorities with no group in the middle. That rule was
+* never about a control panel.
+*
+* Everything else here — {@link CAMERA_SWITCH_CATALOG}, {@link CameraSwitch},
+* {@link deriveCameraSwitches}, the `pipelineOrchestrator.getCameraSwitches` /
+* `setCameraSwitch` pair — is a COMPATIBILITY surface for as long as deployed
+* viewers (v1.0.305) and the admin UI still call it. It is deleted when they
+* stop; nothing new may be built on it.
 *
 * ## This file adds no state
 *
@@ -16538,9 +16561,16 @@ var CameraStatusSchema = z.object({
 	audio: CameraAudioStatusSchema.nullable(),
 	recording: CameraRecordingStatusSchema.nullable(),
 	/**
-	* Per-camera function switches an OPERATOR has turned off
+	* Per-camera functions an OPERATOR has turned off
 	* ([D61](../../../../docs/decisions/adr-0067.md)).
 	*
+	* Composed from the AUTHORITIES themselves — the wrapper bindings,
+	* `RecordingConfig.enabled`, the notification mute, the broker's audio
+	* policy, the camera's own microphone — via `composeSwitchedOff`, not from
+	* the deprecated `getCameraSwitches` group ([D113](../../../../docs/decisions/adr-0113.md)).
+	* The badge outlives the control panel: the panel was a convenience, this is
+	* the difference between a camera being off and a camera being dead.
+	*
 	* This is the difference between DISABLED and BROKEN. A camera whose
 	* `detection` block reports zero fps and whose `switchedOff` contains
 	* `'object-detection'` was switched off by a person; the same camera with an
@@ -16979,6 +17009,10 @@ var pipelineOrchestratorCapability = {
 			agentNodeId: z.string().optional()
 		}), CameraPipelineConfigSchema),
 		/**
+		* @deprecated The aggregate switch group is being withdrawn
+		* ([D113](../../../../docs/decisions/adr-0113.md)). Build nothing new on
+		* this pair; read the authority directly.
+		*
 		* The whole per-camera function switch group, DERIVED — never a stored
 		* list ([D61](../../../../docs/decisions/adr-0067.md)).
 		*
@@ -16992,9 +17026,23 @@ var pipelineOrchestratorCapability = {
 		* `auth: 'view'` deliberately — a NON-admin must be able to see that a
 		* camera is quiet because somebody switched it off. Only the mutation is
 		* admin-gated.
+		*
+		* **Removal plan.** It stays and it KEEPS WORKING while shipped viewers
+		* (v1.0.305) and the admin UI still call it — removing it now is a broken
+		* app on a device nobody can redeploy from here. It is served by a thin
+		* shim over the same authorities (`camera-switch-service.ts`), so the
+		* behaviour of the pair is the behaviour of the authorities by
+		* construction. It is deleted once every surface reaches its own
+		* component's options and the last caller is gone. Nothing on this server
+		* reads it: `CameraStatus.switchedOff` is composed from the authorities
+		* directly via `composeSwitchedOff`.
 		*/
 		getCameraSwitches: method(z.object({ deviceId: z.number() }), CameraSwitchGroupSchema),
 		/**
+		* @deprecated See {@link getCameraSwitches}. Write the authority — the
+		* wrapper binding, `RecordingConfig.enabled`, the notification mute — not
+		* this ([D113](../../../../docs/decisions/adr-0113.md)).
+		*
 		* Flip ONE switch, routed to its existing authority.
 		*
 		* Never writes a parallel map: `recording` patches `RecordingConfig.enabled`
@@ -25240,10 +25288,42 @@ var recordingCapability = {
 */
 /** Playback-speed multiplier for the render (1 = realtime). */
 var ExportSpeedSchema = z.number().min(.25).max(32);
+/**
+* One dense interval, in SECONDS FROM THE EXPORT'S OWN `fromMs`.
+*
+* Relative and not absolute epoch on purpose: the renderer's frame-select
+* expression sees ffmpeg's `t`, which starts at 0 for the export's source
+* playlist. Handing it absolute epochs would make every call site responsible
+* for the same subtraction, and the one that forgot would emit a filter that
+* selects nothing — silently, as a uniform timelapse.
+*/
+var ExportDenseRangeSchema = z.object({
+	fromSec: z.number().nonnegative(),
+	toSec: z.number().nonnegative()
+}).refine((r) => r.toSec > r.fromSec, { message: "dense range must have toSec > fromSec" });
+/**
+* Dense-interval overlay for a timelapse: sample at `dense.everyMs` INSIDE the
+* listed ranges and at the base `everyMs` everywhere else.
+*
+* `everyMs` must be strictly smaller than the base cadence — a dense rate that
+* is not denser renders a uniform timelapse the operator believes is two-rate.
+*/
+var ExportDenseSchema = z.object({
+	everyMs: z.number().int().positive(),
+	ranges: z.array(ExportDenseRangeSchema).min(1).max(200)
+});
 /** Timelapse cadence — sample one source frame per `everyMs`, output at `outputFps`. */
 var ExportTimelapseSchema = z.object({
 	everyMs: z.number().int().positive(),
-	outputFps: z.number().int().min(1).max(60).optional()
+	outputFps: z.number().int().min(1).max(60).optional(),
+	/** Optional second, FASTER rate over the intervals that matter. */
+	dense: ExportDenseSchema.optional()
+}).superRefine((v, ctx) => {
+	if (v.dense !== void 0 && v.dense.everyMs >= v.everyMs) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		message: "dense.everyMs must be strictly smaller than the base everyMs",
+		path: ["dense", "everyMs"]
+	});
 });
 /**
 * Render options. `speed` and `timelapse` are mutually exclusive. `includeAudio`
@@ -25301,6 +25381,19 @@ var ExportDownloadSchema = z.object({
 	url: z.string(),
 	endpoints: z.array(z.string())
 });
+/**
+* A finished export's bytes, inline.
+*
+* `bytes` is the DECODED length — the number the caller bounds and logs
+* against, so nobody has to infer it from the base64 length.
+*/
+var ExportBytesSchema = z.object({
+	base64: z.string(),
+	contentType: z.string(),
+	/** Suggested filename, extension included. */
+	name: z.string(),
+	bytes: z.number().int().nonnegative()
+});
 var recordingExportCapability = {
 	name: "recordingExport",
 	scope: "system",
@@ -25340,6 +25433,27 @@ var recordingExportCapability = {
 		getDownloadUrl: method(z.object({ exportId: z.string() }), ExportDownloadSchema, {
 			kind: "query",
 			auth: "protected"
+		}),
+		/**
+		* The finished file's BYTES, base64, for a caller that must republish them
+		* somewhere a session-less fetcher can reach.
+		*
+		* `getDownloadUrl` is the right answer for a human: the download route is
+		* served `access: 'authenticated'`, which a browser satisfies and a
+		* notifier BACKEND does not. It answers a RELATIVE path, so it is not even
+		* a URL an outside fetcher could try. This method exists for the one case
+		* that needs the other thing — a scheduled timelapse whose video has to
+		* become a public attachment on the notification artifact plane.
+		*
+		* Deliberately narrow: `ready` only (a queued, rendering, failed, expired
+		* or deleted export has no file, and answering "0 bytes" for one is how a
+		* caller ships an empty attachment), still inside its lifetime, and under
+		* {@link RECORDING_EXPORT_MAX_READ_BYTES}. Every refusal throws with the
+		* reason — none of them is silent.
+		*/
+		readExportBytes: method(z.object({ exportId: z.string() }), ExportBytesSchema, {
+			kind: "query",
+			auth: "protected"
 		})
 	}
 };
@@ -32063,6 +32177,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"recordingExport.readExportBytes": {
+		capName: "recordingExport",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"sceneMonitor.captureReference": {
 		capName: "scene-monitor",
 		capScope: "device",
@@ -33480,10 +33600,28 @@ TimelapseRuleInputSchema.extend({
 	*/
 	ownerUserId: z.string().optional(),
 	/**
-	* Epoch-ms of the last successful generation — the 1-hour re-generation
-	* guard's durable state (predecessor parity). Absent = never generated.
+	* Epoch-ms of the NEWEST successful generation across every camera of this
+	* rule. What a UI shows, and the compatibility floor for
+	* {@link readTimelapseGeneratedAt}. Absent = never generated.
 	*/
 	lastGeneratedAt: z.number().optional(),
+	/**
+	* PER-CAMERA generation state, keyed by `String(deviceId)` — the
+	* re-generation guard's real durable state.
+	*
+	* One rule covers several cameras and each renders its own video, so a rule
+	* -wide stamp is wrong in the direction that DESTROYS work: camera A
+	* succeeding at 06:05 tells camera B, whose render failed, that it is
+	* already done — and B's night is gone for good, because the window will not
+	* come back.
+	*
+	* ADDITIVE, so the migration is free: a row written before this field simply
+	* has no map, and {@link readTimelapseGeneratedAt} falls back to
+	* {@link TimelapseRuleSchema.shape.lastGeneratedAt}. Reading an old row as
+	* "never generated" would re-render and re-notify every camera of every rule
+	* once, on the deploy that shipped the map.
+	*/
+	generatedByDevice: z.record(z.string(), z.number()).optional(),
 	/** userId of the caller who created the rule (server-stamped). */
 	createdBy: z.string(),
 	createdAt: z.number(),

package/dist/index.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_dist = require("./dist-CA2mim74.js");
+const require_dist = require("./dist-DUDXaubL.js");
 const require_builtins_alerts_alerts_addon = require("./builtins/alerts/alerts.addon.js");
 require("./builtins/alerts/index.js");
 const require_formatter = require("./formatter-DqAKDlvN.js");
@@ -3072,6 +3072,74 @@ function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
+* How far up from the entry file to look for the owning `package.json`
+* (`<pkg>/dist/chunks/x.js` → 3 hops). Bounded so a loose module outside a
+* package can't walk to the filesystem root.
+*/
+var PACKAGE_JSON_LOOKUP_DEPTH = 4;
+/** Version from the `package.json` that owns `entryPath`, or null. */
+function readOwningPackageVersion(entryPath) {
+	let dir = node_path.dirname(entryPath);
+	for (let hop = 0; hop < PACKAGE_JSON_LOOKUP_DEPTH; hop++) {
+		try {
+			const version = require_dist.asJsonObject(require_dist.parseJsonUnknown(node_fs.readFileSync(node_path.join(dir, "package.json"), "utf-8")))?.["version"];
+			if (typeof version === "string" && version.length > 0) return version;
+		} catch {}
+		const parent = node_path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+/**
+* Cache-bust key for an addon entry module: the `?v=` query that makes each
+* on-disk REVISION of `entryPath` a distinct ESM module URL. Returns null when
+* the entry cannot be stat'd — the caller then does a plain import.
+*
+* The key is `<version>-<content hash>`, and BOTH halves are load-bearing
+* because each on its own has a documented way of not changing across a real
+* redeploy:
+*
+*  - **mtime does not change.** `npm pack` normalises every file's mtime in the
+*    tarball to 499162500000 (1985-10-26); every install path here extracts
+*    such a tarball, so the entry file of v1.0.0 and of v1.0.99 carry the same
+*    mtime. An mtime-only key (what this used to be) is a NO-OP — it produced
+*    one byte-identical URL for every version of every addon ever installed.
+*  - **the version does not change** on a `camstack deploy` of an unbumped
+*    workspace package — the whole dev loop.
+*  - **the entry hash does not change** when a multi-chunk dist alters a chunk
+*    the entry only re-exports; the version bump covers that case.
+*
+* Hashing the entry costs one extra read of an already-read file (~1.5 MB for
+* the largest addon bundle, single-digit ms) once per addon load. Cheap against
+* what a stale key costs: hub-main keeps validating `addons.custom` input
+* against the OLD `customActions` schema — silently STRIPPING newly-added
+* fields — and, worse, Node caches a load that THREW as a rejected module and
+* replays that rejection for every later retry at the same URL. On 2026-08-12
+* `@camstack/addon-export-hap` burned 126 identical failed load retries over
+* 10.5h, none of which could have succeeded: the fixed bytes on disk were never
+* read.
+*
+* Never throws: an unreadable version degrades to the mtime, an unreadable body
+* to mtime+size.
+*/
+function addonModuleCacheKey(entryPath) {
+	let stat;
+	try {
+		stat = node_fs.statSync(entryPath);
+	} catch {
+		return null;
+	}
+	const version = readOwningPackageVersion(entryPath) ?? `m${stat.mtimeMs}`;
+	let content;
+	try {
+		content = (0, node_crypto.createHash)("sha1").update(node_fs.readFileSync(entryPath)).digest("hex").slice(0, 16);
+	} catch {
+		content = `m${stat.mtimeMs}s${stat.size}`;
+	}
+	return `${version}-${content}`;
+}
+/**
 * Import an addon entry module FRESH on every load, defeating Node's
 * per-URL ESM module cache.
 *
@@ -3080,23 +3148,15 @@ function isRecord$1(value) {
 * redeploy returns the STALE previously-cached module. The addon RUNNER child
 * is a fresh process so it reloads correctly — but hub-main also imports the
 * module to read its static catalog (`customActions` Zod schemas, addon class)
-* for the `addons.custom` "validate on the way in" guard. Without cache-busting
-* that guard keeps validating against the OLD schema, silently STRIPPING any
-* newly-added custom-action input field until a full hub restart (observed:
-* benchmark `deviceKey`/multi-device fan-out fields dropped after redeploy).
+* for the `addons.custom` "validate on the way in" guard.
 *
-* Appending a `?v=<mtimeMs>` query makes each on-disk version a distinct module
-* URL, so a redeploy (new mtime) loads the fresh module. Falls back to a plain
-* import if the file can't be stat'd.
+* The distinguishing key is {@link addonModuleCacheKey}; a plain import is the
+* fallback when the entry cannot be stat'd.
 */
 async function importAddonModuleFresh(entryPath) {
-	let bust;
-	try {
-		bust = node_fs.statSync(entryPath).mtimeMs;
-	} catch {
-		return import(entryPath);
-	}
-	return import(`${(0, node_url.pathToFileURL)(entryPath).href}?v=${bust}`);
+	const bust = addonModuleCacheKey(entryPath);
+	if (bust === null) return import(entryPath);
+	return import(`${(0, node_url.pathToFileURL)(entryPath).href}?v=${encodeURIComponent(bust)}`);
 }
 /**
 * Package.json manifest boundary: the `camstack` field is authored by third-party
@@ -4518,6 +4578,79 @@ var AddonInstaller = class AddonInstaller {
 			force: true
 		}).catch(() => void 0)));
 	}
+	/**
+	* Make `pkgDir` (an addon tree that has NOT been swapped in yet) runnable:
+	* strip the host-provided deps from its manifest, then `npm install` whatever
+	* survives.
+	*
+	* ONE implementation for every path that materialises an addon tree —
+	* `installFromTgz` (deploy/upload) and `applyUpdateFromStaged` (OTA). The OTA
+	* path did not have it, and that is a whole outage class: an addon declaring
+	* `camstack.runtimeDependencies` was broken by its FIRST OTA update, its dist
+	* landing without `node_modules`. Every load then threw `Cannot find module`
+	* and the retry loop replayed it — `@camstack/addon-export-hap`, 126 failed
+	* load retries over 10.5h on 2026-08-12; `@camstack/addon-remote-storage`
+	* (`@aws-sdk/*`, `webdav`) is the same landmine.
+	*
+	* **Strip.** `@camstack/*` are host-provided system packages that resolve via
+	* the host's node_modules (Node walks up from the installed addon dir). Left
+	* in, this `npm install` pulls the LAST PUBLISHED `@camstack/types` (etc.)
+	* into the addon's OWN node_modules where it SHADOWS the host's fresh copy —
+	* local additions to a system package silently never reach the deployed
+	* addon. Addon dists are self-contained besides, so `stripBundledDeps` keeps
+	* only what the manifest explicitly declares in
+	* `camstack.runtimeDependencies` (see fs-utils / ADR-0027). Nothing left to
+	* install is the COMMON case: skip npm rather than pay an empty round-trip.
+	*
+	* **Failure is FATAL.** This used to warn-and-continue on the tgz path ("the
+	* addon may still load if imports are lazy") — live cost: a host with no npm
+	* (packaged Electron Mac agent) installed every runtime-dep addon WITHOUT its
+	* node_modules for DAYS; each reported "running" while its entry failed at
+	* import (`Cannot find module 'sharp'`), the detection group ran 1/3 members,
+	* and the node silently dropped out of the balancer. Throwing here is what
+	* keeps the PREVIOUS install intact: every caller builds the tree before it
+	* swaps, so an abort simply means the swap never happens.
+	*
+	* A missing/unreadable manifest is NOT fatal — it is logged and skipped. The
+	* callers validate the tree themselves, and a tree with no readable
+	* package.json has no declared deps to install (the loader will skip the
+	* package entirely).
+	*/
+	async installRuntimeDependencies(pkgDir, packageName) {
+		const pkgJsonPath = node_path.join(pkgDir, "package.json");
+		const pkgView = readPackageJson(pkgJsonPath);
+		if (pkgView == null) {
+			this.logger.error(`${packageName} — no readable package.json in the prepared tree; runtime dependencies NOT installed`, { meta: { pkgJsonPath } });
+			return;
+		}
+		const strippedManifest = stripBundledDeps(pkgView.raw);
+		await node_fs.promises.writeFile(pkgJsonPath, JSON.stringify(strippedManifest, null, 2));
+		const deps = require_dist.asJsonObject(strippedManifest["dependencies"]);
+		const depNames = deps ? Object.keys(deps) : [];
+		if (depNames.length === 0) return;
+		this.logger.info(`${packageName} — installing runtime dependencies`, { meta: {
+			stagingDir: pkgDir,
+			dependencies: depNames
+		} });
+		try {
+			await require_manifest_python_deps.runNpm([
+				"install",
+				"--omit=dev",
+				"--omit=peer",
+				"--no-audit",
+				"--no-fund",
+				"--no-package-lock",
+				...this.registry ? ["--registry", this.registry] : []
+			], this.npmRunOptions(pkgDir, 24e4));
+		} catch (err) {
+			this.logger.error(`${packageName} — runtime dependency install FAILED; update ABORTED (a swapped-in copy would fail every load with "Cannot find module")`, { meta: {
+				pkgDir,
+				dependencies: depNames,
+				error: require_dist.errMsg(err)
+			} });
+			throw new Error(`${packageName} — runtime dependency install failed: ${require_dist.errMsg(err)}`, { cause: err });
+		}
+	}
 	/** Install addon from a tgz file (uploaded or downloaded) */
 	async installFromTgz(tgzPath) {
 		const stagingRoot = node_path.join(this.addonsDir, ".staging");
@@ -4541,25 +4674,7 @@ var AddonInstaller = class AddonInstaller {
 			if (!pkgView) throw new Error(`Invalid package.json at ${pkgJsonPath}`);
 			if (!pkgView.camstackAddons) throw new Error(`Package ${pkgView.name} has no camstack.addons manifest`);
 			const targetDir = node_path.join(this.addonsDir, pkgView.name);
-			const strippedManifest = stripBundledDeps(pkgView.raw);
-			await node_fs.promises.writeFile(pkgJsonPath, JSON.stringify(strippedManifest, null, 2));
-			const strippedRuntimeDeps = strippedManifest["dependencies"];
-			if (strippedRuntimeDeps != null && typeof strippedRuntimeDeps === "object" && Object.keys(strippedRuntimeDeps).length > 0) {
-				this.logger.info(`${pkgView.name} — installing runtime dependencies`, { meta: { stagingDir: pkgDir } });
-				try {
-					await require_manifest_python_deps.runNpm([
-						"install",
-						"--omit=dev",
-						"--omit=peer",
-						"--no-audit",
-						"--no-fund",
-						"--no-package-lock",
-						...this.registry ? ["--registry", this.registry] : []
-					], this.npmRunOptions(pkgDir, 24e4));
-				} catch (err) {
-					throw new Error(`${pkgView.name} — runtime dependency install failed: ${require_dist.errMsg(err)}`, { cause: err });
-				}
-			}
+			await this.installRuntimeDependencies(pkgDir, pkgView.name);
 			try {
 				await require_manifest_python_deps.installManifestNativeDeps(pkgDir, pkgView.raw, this.logger, this.registry, this.npmCacheDir);
 			} catch (nativeErr) {
@@ -4671,18 +4786,32 @@ var AddonInstaller = class AddonInstaller {
 	* replaces step 2 ("install new version") with an atomic directory
 	* move of `stagedPath` into `addonDir`.
 	*
+	* "Skips npm entirely" is true only of the REGISTRY round-trip: the staged
+	* tree is the raw unpacked tarball, so the addon's own
+	* `camstack.runtimeDependencies` still have to be installed into it, exactly
+	* as `installFromTgz` does. Skipping that is what broke every runtime-dep
+	* addon on its first OTA update — see {@link installRuntimeDependencies}.
+	*
+	* Order matters and is `installFromTgz`'s: the tree is COMPLETED FIRST, and
+	* the live install is only then backed up and replaced. So the addon keeps
+	* serving the old version for the whole (minutes-long) npm install, the swap
+	* window stays two renames wide, and a dependency failure aborts with the
+	* previous version untouched instead of leaving a dependency-less copy live.
+	*
 	* On cross-device move (EXDEV) falls back to a recursive copy followed
 	* by removal of the staged directory. On any swap failure the backup is
 	* restored and the error is rethrown — identical recovery to `applyUpdate`.
 	*
-	* Throws if the package is not tracked in the manifest or if `addonDir`
-	* is missing (same preconditions as `applyUpdate`).
+	* Throws if the package is not tracked in the manifest, if `addonDir`
+	* is missing (same preconditions as `applyUpdate`), or if the runtime-dep
+	* install fails.
 	*/
 	async applyUpdateFromStaged(packageName, version, stagedPath) {
 		const current = this.manifest.get(packageName);
 		if (current == null) throw new Error(`Cannot update ${packageName}: not currently tracked in manifest`);
 		const addonDir = node_path.join(this.addonsDir, packageName);
 		if (!node_fs.existsSync(addonDir)) throw new Error(`Cannot update ${packageName}: install dir ${addonDir} missing`);
+		await this.installRuntimeDependencies(stagedPath, packageName);
 		const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 		const backupRoot = node_path.join(this.addonsDir, ".backups", packageName);
 		ensureDir(backupRoot);