@camstack/types 1.2.59 → 1.2.61

package/dist/index.js

@@ -695,8 +695,31 @@ var DEFAULT_RETENTION = {
 //#endregion
 //#region src/interfaces/camera-switches.ts
 /**
-* 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
 *
@@ -1120,6 +1143,42 @@ function deriveCameraSwitches(input) {
 function switchedOffIds(switches) {
 	return switches.filter((s) => CAMERA_SWITCH_CATALOG[s.id].countsAsSwitchedOff && s.available && !s.enabled).map((s) => s.id);
 }
+/**
+* Compose the `switchedOff` badge STRAIGHT from the authorities (D113).
+*
+* This is the half of this file that outlives the switch group.
+* {@link deriveCameraSwitches} exists to paint a control panel — labels, cost
+* lines, `available`/`unavailableReason` — and that panel is being dismantled:
+* each function is going back to its own component's settings. The BADGE is
+* not: "a switched-off camera must read as DISABLED, not broken" is a rule
+* about status, not about a control group, and it survives every surface change
+* underneath it.
+*
+* So the badge gets its own entry point over the same authority reads, and the
+* caller that only needs the badge never builds eight labelled rows to throw
+* seven of them away.
+*
+* `privacy-mask` appears in NEITHER list, whichever way it is sitting and
+* whether or not it could be read — its ON means "the mask is obscuring video",
+* not "this function works" ({@link CameraSwitchDescriptor.countsAsSwitchedOff}).
+* Counting it unreadable would be its own bug: the mask cannot contribute to
+* the badge, so failing to read it cannot make the badge incomplete.
+*/
+function composeSwitchedOff(input) {
+	const switchedOff = [];
+	const unreadable = [];
+	for (const id of CAMERA_SWITCH_ORDER) {
+		const descriptor = CAMERA_SWITCH_CATALOG[id];
+		if (!descriptor.countsAsSwitchedOff) continue;
+		const state = resolveState(descriptor, input);
+		if (state.unavailableReason === "source-unreachable") unreadable.push(id);
+		else if (state.available && !state.enabled) switchedOff.push(id);
+	}
+	return {
+		switchedOff,
+		unreadable
+	};
+}
 //#endregion
 //#region src/interfaces/device-capabilities/camera.ts
 /** Friendly display labels for stream quality IDs. */
@@ -16813,9 +16872,16 @@ var CameraStatusSchema = zod.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
@@ -17254,6 +17320,10 @@ var pipelineOrchestratorCapability = {
 			agentNodeId: zod.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)).
 		*
@@ -17267,9 +17337,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: require_sleep.method(zod.z.object({ deviceId: zod.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`
@@ -17815,24 +17899,28 @@ var snapshotCapability = {
 		*
 		* `getSnapshotOverview` is cache-only by contract: it answers from whatever
 		* the wrapper happens to hold and never captures. Under D93 the client
-		* versions its image URL on that answer, and an image REQUEST is what enrols
-		* a camera in the keep-warm loop. Both of those are satisfiable by the
-		* client's own image cache — `expo-image` is URL-keyed and never revalidates
-		* — so a URL painted in a previous session comes off disk with no network,
-		* no enrolment, and nothing warming. Measured on the live hub: reopening
-		* after two minutes idle painted 15 of 16 tiles at **168 s old** with zero
-		* HTTP requests, and the fleet only recovered because a later poll happened
-		* to observe a different identity.
+		* versions its image URL on that answer, and an image REQUEST was the only
+		* demand signal. Both of those are satisfiable by the client's own image
+		* cache — `expo-image` is URL-keyed and never revalidates — so a URL painted
+		* in a previous session comes off disk with no network, no demand, and no
+		* capture. Measured on the live hub: reopening after two minutes idle
+		* painted 15 of 16 tiles at **168 s old** with zero HTTP requests, and the
+		* fleet only recovered because a later poll happened to observe a different
+		* identity.
 		*
 		* ## The two properties that fix it
 		*
 		* **It is an RPC, so no client cache can answer it.** The demand signal
-		* always reaches the wrapper. This method therefore MAY create keep-warm
-		* subscriptions, where `getSnapshotOverview` must never (D93) — the
-		* distinction is not "one is newer" but that the overview poll is app-wide
-		* (a creating overview would warm every camera on the install) while this is
-		* called by a rendered surface naming the tiles it is actually painting, at
-		* the width it is painting them.
+		* always reaches the wrapper. This method therefore CAPTURES, where
+		* `getSnapshotOverview` must never (D93) — the distinction is not "one is
+		* newer" but that the overview poll is app-wide (a capturing overview would
+		* dial every camera on the install) while this is called by a rendered
+		* surface naming the tiles it is actually painting, at the width it is
+		* painting them.
+		*
+		* Since 2026-08-11 this is the ONLY thing that refreshes a snapshot: the
+		* server-side keep-warm loop was removed (operator directive — on-demand,
+		* always), so a camera nobody is looking at costs nothing at all.
 		*
 		* **It waits, briefly and boundedly, for the capture it triggered.** The
 		* returned `capturedAt` is the frame the link will serve, not the frame the
@@ -25809,10 +25897,52 @@ var recordingCapability = {
 */
 /** Playback-speed multiplier for the render (1 = realtime). */
 var ExportSpeedSchema = zod.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 = zod.z.object({
+	fromSec: zod.z.number().nonnegative(),
+	toSec: zod.z.number().nonnegative()
+}).refine((r) => r.toSec > r.fromSec, { message: "dense range must have toSec > fromSec" });
+/**
+* Hard ceiling on dense ranges in ONE render.
+*
+* The ranges become terms of a single ffmpeg `select` expression, so the count
+* is the length of a command-line argument. The producer (the timelapse
+* scheduler) coalesces and then falls back to the base cadence alone rather
+* than trimming — a truncated range list is a video that quietly omits the
+* evening.
+*/
+var EXPORT_DENSE_MAX_RANGES = 200;
+/**
+* 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 = zod.z.object({
+	everyMs: zod.z.number().int().positive(),
+	ranges: zod.z.array(ExportDenseRangeSchema).min(1).max(200)
+});
 /** Timelapse cadence — sample one source frame per `everyMs`, output at `outputFps`. */
 var ExportTimelapseSchema = zod.z.object({
 	everyMs: zod.z.number().int().positive(),
-	outputFps: zod.z.number().int().min(1).max(60).optional()
+	outputFps: zod.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: zod.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`
@@ -25870,6 +26000,38 @@ var ExportDownloadSchema = zod.z.object({
 	url: zod.z.string(),
 	endpoints: zod.z.array(zod.z.string())
 });
+/**
+* Hard ceiling on ONE {@link recordingExportCapability} byte read — 50 MiB.
+*
+* Two independent reasons land on the same number, which is why it is this one
+* and not a rounder guess:
+*
+*  - **Nobody would accept more.** The roomiest byte cap any notifier backend
+*    declares is telegram's 50 MiB, and the degrade engine DROPS an over-cap
+*    attachment outright rather than degrading it to a link. Bytes above this
+*    are read, encoded and moved to be thrown away at the last step.
+*  - **The envelope is unary.** A base64 payload is held whole, ~1.33× its
+*    size, in the provider AND in the caller — on a hub this repo has already
+*    OOM'd once (D9/D18). A bounded on-demand read at human speed is the shape
+*    those records permit; an unbounded one is the shape they forbid.
+*
+* Above it the provider REFUSES with a log line rather than truncating: half a
+* video is worse than a notification that says there is no attachment.
+*/
+var RECORDING_EXPORT_MAX_READ_BYTES = 50 * 1024 * 1024;
+/**
+* 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 = zod.z.object({
+	base64: zod.z.string(),
+	contentType: zod.z.string(),
+	/** Suggested filename, extension included. */
+	name: zod.z.string(),
+	bytes: zod.z.number().int().nonnegative()
+});
 var recordingExportCapability = {
 	name: "recordingExport",
 	scope: "system",
@@ -25909,6 +26071,27 @@ var recordingExportCapability = {
 		getDownloadUrl: require_sleep.method(zod.z.object({ exportId: zod.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: require_sleep.method(zod.z.object({ exportId: zod.z.string() }), ExportBytesSchema, {
+			kind: "query",
+			auth: "protected"
 		})
 	}
 };
@@ -29148,9 +29331,10 @@ var DeclaredDevices = class {
 		}
 		const integrationId = spec.integrationId ?? await this.ensureIntegration(spec.integrationName);
 		const index = await this.readIndex();
+		const live = await this.readLiveByStableId();
 		const outcomes = [];
 		for (const declaration of spec.devices) {
-			const outcome = await this.applyDeclaration(declaration, integrationId, index);
+			const outcome = await this.applyDeclaration(declaration, integrationId, index, live);
 			if (outcome !== null) outcomes.push(outcome);
 		}
 		return {
@@ -29196,6 +29380,26 @@ var DeclaredDevices = class {
 		return new Map(rows.map((row) => [row.stableId, row]));
 	}
 	/**
+	* Devices this kernel already has CONSTRUCTED, by stableId.
+	*
+	* Distinct from {@link readIndex}, and the distinction is the bug: the index
+	* is persisted rows, this is live objects. A row without an object must be
+	* adopted; an object must be left exactly as it is.
+	*
+	* Failure is non-fatal and deliberately so — an empty map degrades to the
+	* previous behaviour (attempt the adopt) rather than skipping a device that
+	* genuinely needs bringing up.
+	*/
+	async readLiveByStableId() {
+		try {
+			const devices = await this.ports.devices.getAll();
+			return new Map(devices.map((device) => [device.stableId, device]));
+		} catch (err) {
+			this.ports.logger.warn("could not read live devices — falling back to adopt-by-row", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return /* @__PURE__ */ new Map();
+		}
+	}
+	/**
 	* One declaration: adopt what exists, create what does not.
 	*
 	* The create branch is the destructive one — it seeds `initialMeta`, and
@@ -29204,8 +29408,15 @@ var DeclaredDevices = class {
 	* the declared name over the operator's rename. D49: that branch needs a
 	* second read to agree.
 	*/
-	async applyDeclaration(declaration, integrationId, index) {
+	async applyDeclaration(declaration, integrationId, index, live) {
 		try {
+			const alreadyLive = live.get(declaration.stableId);
+			if (alreadyLive !== void 0) return {
+				stableId: declaration.stableId,
+				deviceId: alreadyLive.id,
+				device: alreadyLive,
+				created: false
+			};
 			let existing = index.get(declaration.stableId);
 			if (existing === void 0) {
 				existing = (await this.readIndex()).get(declaration.stableId);
@@ -35774,6 +35985,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",
@@ -37905,7 +38122,8 @@ function createSystemProxy(api) {
 			getExport: (input) => dispatch("recordingExport", "getExport", "query", input),
 			cancelExport: (input) => dispatch("recordingExport", "cancelExport", "mutation", input),
 			deleteExport: (input) => dispatch("recordingExport", "deleteExport", "mutation", input),
-			getDownloadUrl: (input) => dispatch("recordingExport", "getDownloadUrl", "query", input)
+			getDownloadUrl: (input) => dispatch("recordingExport", "getDownloadUrl", "query", input),
+			readExportBytes: (input) => dispatch("recordingExport", "readExportBytes", "query", input)
 		},
 		serverManagement: {
 			getServerPackageStatus: (input) => dispatch("serverManagement", "getServerPackageStatus", "query", input),
@@ -38522,15 +38740,50 @@ var TimelapseRuleSchema = TimelapseRuleInputSchema.extend({
 	*/
 	ownerUserId: zod.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: zod.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: zod.z.record(zod.z.string(), zod.z.number()).optional(),
 	/** userId of the caller who created the rule (server-stamped). */
 	createdBy: zod.z.string(),
 	createdAt: zod.z.number(),
 	updatedAt: zod.z.number()
 });
+/**
+* The last successful generation for ONE camera of a rule, epoch-ms.
+*
+* The per-device map wins; a rule with no map falls back to the rule-wide
+* `lastGeneratedAt` (the compatible-migration path — see
+* {@link TimelapseRuleSchema}); a rule with neither returns 0, which every
+* guard reads as "never generated".
+*
+* Read through this helper and never off the field directly: the fallback is
+* the whole migration, and a call site that forgot it would re-render an
+* entire rule set once.
+*/
+function readTimelapseGeneratedAt(rule, deviceId) {
+	const map = rule.generatedByDevice;
+	if (map !== void 0) return map[String(deviceId)] ?? 0;
+	return rule.lastGeneratedAt ?? 0;
+}
 //#endregion
 //#region src/pipeline/detail-crop.ts
 /**
@@ -40534,6 +40787,7 @@ exports.EVENTFUL_CAP_NAMES = EVENTFUL_CAP_NAMES;
 exports.EVENT_KIND_BY_CAP = EVENT_KIND_BY_CAP;
 exports.EVENT_PAD_MS = EVENT_PAD_MS;
 exports.EVENT_TAXONOMY = EVENT_TAXONOMY;
+exports.EXPORT_DENSE_MAX_RANGES = EXPORT_DENSE_MAX_RANGES;
 exports.EXPRESSION_BUILTINS = EXPRESSION_BUILTINS;
 exports.EXPRESSION_BUILTIN_NAMES = EXPRESSION_BUILTIN_NAMES;
 exports.EXPRESSION_COMPILE_CACHE_CAPACITY = EXPRESSION_COMPILE_CACHE_CAPACITY;
@@ -40565,6 +40819,9 @@ exports.EventMediaCoverageSchema = EventMediaCoverageSchema;
 exports.EventMediaKindSchema = EventMediaKindSchema;
 exports.EventMediaProductionSchema = EventMediaProductionSchema;
 exports.EventSourceType = require_enums.EventSourceType$1;
+exports.ExportBytesSchema = ExportBytesSchema;
+exports.ExportDenseRangeSchema = ExportDenseRangeSchema;
+exports.ExportDenseSchema = ExportDenseSchema;
 exports.ExportDownloadSchema = ExportDownloadSchema;
 exports.ExportOptionsSchema = ExportOptionsSchema;
 exports.ExportRecordSchema = ExportRecordSchema;
@@ -40863,6 +41120,7 @@ exports.REACHABILITY_FAILURES_TO_OFFLINE = REACHABILITY_FAILURES_TO_OFFLINE;
 exports.REACHABILITY_POLL_INTERVAL_MS = REACHABILITY_POLL_INTERVAL_MS;
 exports.REACHABILITY_PROBE_TIMEOUT_MS = REACHABILITY_PROBE_TIMEOUT_MS;
 exports.RECOGNITION_TYPES = RECOGNITION_TYPES;
+exports.RECORDING_EXPORT_MAX_READ_BYTES = RECORDING_EXPORT_MAX_READ_BYTES;
 exports.RESERVED_BINDING_NAMES = RESERVED_BINDING_NAMES;
 exports.RUNTIME_DEFAULTS = RUNTIME_DEFAULTS;
 exports.RUNTIME_TO_FORMAT = RUNTIME_TO_FORMAT;
@@ -41169,6 +41427,7 @@ exports.colorCapability = colorCapability;
 exports.colorForKind = colorForKind;
 exports.compileExpression = compileExpression;
 exports.compileExpressionSafe = compileExpressionSafe;
+exports.composeSwitchedOff = composeSwitchedOff;
 exports.conditionDepth = conditionDepth;
 exports.connectionTestCapability = connectionTestCapability;
 exports.connectivityCapability = connectivityCapability;
@@ -41365,6 +41624,7 @@ exports.readDetailCropConvention = readDetailCropConvention;
 exports.readDeviceStateFrom = readDeviceStateFrom;
 exports.readNativeLeaseOverride = readNativeLeaseOverride;
 exports.readNodePin = require_sleep.readNodePin;
+exports.readTimelapseGeneratedAt = readTimelapseGeneratedAt;
 exports.readinessKey = require_sleep.readinessKey;
 exports.rebootCapability = rebootCapability;
 exports.recordingCapability = recordingCapability;