@camstack/addon-provider-reolink 1.2.183 → 1.2.184

package/dist/addon.js

@@ -11,6 +11,7 @@ let crypto$1 = require("crypto");
 crypto$1 = require_chunk.__toESM(crypto$1, 1);
 let child_process = require("child_process");
 let node_http = require("node:http");
+require("node:zlib");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path, 1);
@@ -32,10 +33,10 @@ http = require_chunk.__toESM(http, 1);
 let url = require("url");
 let node_child_process = require("node:child_process");
 let node_os = require("node:os");
-node_os = require_chunk.__toESM(node_os);
+node_os = require_chunk.__toESM(node_os, 1);
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs, 1);
-//#region ../types/dist/event-category-DaIZi00R.mjs
+//#region ../types/dist/event-category-C4hVnRo8.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -254,7 +255,17 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["RecordingStopped"] = "recording.stopped";
 	EventCategory["RecordingError"] = "recording.error";
 	EventCategory["RecordingHealthDegraded"] = "recording.health.degraded";
+	/** Recording enabled but no segment finalized for the NC stall window. */
+	EventCategory["RecordingHealthStalled"] = "recording.health.stalled";
+	/** Recovery from {@link RecordingHealthStalled}. */
+	EventCategory["RecordingHealthOk"] = "recording.health.ok";
 	EventCategory["RecordingStorageCritical"] = "recording.storage.critical";
+	/** Free space on a storage location crossed the warn bar. */
+	EventCategory["StorageLocationLow"] = "storage.location.low";
+	/** Free space at/under the critical bar, or capacity probe failed (`null`). */
+	EventCategory["StorageLocationCritical"] = "storage.location.critical";
+	/** Recovery from low/critical on a storage location. */
+	EventCategory["StorageLocationOk"] = "storage.location.ok";
 	EventCategory["RecordingSegmentWritten"] = "recording.segment.written";
 	EventCategory["RecordingPolicyFallback"] = "recording.policy.fallback";
 	EventCategory["RecordingRetentionCompleted"] = "recording.retention.completed";
@@ -5413,7 +5424,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-DwAQ9sqX.mjs
+//#region ../types/dist/sleep-vWTnHq9G.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -8018,6 +8029,21 @@ var ProfileRtspEntrySchema = object({
 	codec: string().optional(),
 	resolution: CamStreamResolutionSchema.optional()
 });
+/**
+* The model weight formats a catalog entry can ship. Schema-free on purpose:
+* `types/models.ts` builds Zod schemas from it, but a runner-closure consumer
+* (the model downloader in `@camstack/system`) needs only the list and must
+* reach it through `@camstack/types/addon` without building the cap schema
+* graph (D28).
+*/
+var MODEL_FORMATS = [
+	"onnx",
+	"coreml",
+	"openvino",
+	"tflite",
+	"pt",
+	"gguf"
+];
 object({
 	field: string().min(1),
 	on: literal("advance")
@@ -8616,7 +8642,7 @@ var DeviceRole = /* @__PURE__ */ function(DeviceRole) {
 	return DeviceRole;
 }({});
 //#endregion
-//#region ../types/dist/composition-Bzr7GwgP.mjs
+//#region ../types/dist/composition-C-WpVYTX.mjs
 /**
 * The ffmpeg build every CamStack node downloads, per platform and arch.
 *
@@ -8668,7 +8694,7 @@ var BASE = `https://github.com/jellyfin/jellyfin-ffmpeg/releases/download/v${FFM
 function portable(target) {
 	return `${BASE}/jellyfin-ffmpeg_${FFMPEG_RELEASE}_portable_${target}-gpl.tar.xz`;
 }
-portable("linux64"), portable("linuxarm64"), portable("macarm64"), portable("mac64");
+portable("linux64"), portable("linuxarm64"), portable("macarm64"), portable("mac64"), `${BASE}${FFMPEG_RELEASE}`;
 /**
 * THE table "which boolean of this device type counts as HIGH", and the
 * pure evaluator of its EDGE.
@@ -12412,14 +12438,6 @@ var MASK_SUPPLY_STEP_IDS = ["segmentation"];
 	...CROP_SUPPLY_STEP_IDS,
 	...MASK_SUPPLY_STEP_IDS
 ];
-var MODEL_FORMATS = [
-	"onnx",
-	"coreml",
-	"openvino",
-	"tflite",
-	"pt",
-	"gguf"
-];
 /**
 * Multi-file format payload.
 *
@@ -14243,7 +14261,14 @@ var BrokerProviderInfoSchema = object({
 	/** Broker kinds this provider can create, with a display label. */
 	kinds: array(object({
 		kind: string(),
-		label: string()
+		label: string(),
+		/**
+		* Relative hub path to start an interactive account link (OAuth popup).
+		* May include `{{brokerId}}`; admin-ui substitutes and appends `?popup=1`.
+		*/
+		interactiveConnectPath: string().min(1).optional(),
+		/** Relative hub path to disconnect the linked account (same popup pattern). */
+		interactiveDisconnectPath: string().min(1).optional()
 	}))
 });
 var ListInputSchema = object({ 
@@ -21337,6 +21362,12 @@ var NcSystemEventKindSchema = _enum([
 	"node-updating",
 	"node-inference-unavailable",
 	"detection-blind",
+	"recording-stalled",
+	"recording-healthy",
+	"recording-degraded",
+	"storage-location-low",
+	"storage-location-critical",
+	"storage-location-ok",
 	"addon-crash-loop",
 	"addon-update-available",
 	"server-update-available",
@@ -33436,6 +33467,17 @@ var BatteryStatusSchema = object({
 	*/
 	lastContactAt: number().optional(),
 	/**
+	* Ms epoch of the last COMPLETE scheduled refresh — every fact the provider
+	* holds for the device (level, charging, link, device info, state slices) and
+	* its cached snapshot, read together. Absent = never since this slice was
+	* born. Unlike `lastUpdated` (any write, even a push of one field) this is
+	* the staleness an operator can trust: the provider owns the device fact and
+	* so owns the window on its age (D224, D847). Not a clock in the
+	* runtime-state-durability sense: it moves once per window and must survive
+	* a restart, or every restart would owe the camera a wake.
+	*/
+	lastFullRefreshAt: number().optional(),
+	/**
 	* True when the source is a BINARY low-battery indicator (HA
 	* `binary_sensor` device_class=battery / `LOW_BAT`) that has no real
 	* charge level — `percentage` is then a coarse stand-in (100 = normal,
@@ -46470,17 +46512,6 @@ var BaseDeviceProvider = class extends BaseAddon {
 		return toDeviceSummary(device, this.addonId);
 	}
 };
-/**
-* Default silence budget before a sleeping battery camera is called gone.
-*
-* Sized off the mechanism that produces contact, not off taste: a battery cam
-* on this deployment surfaces a firmware push (battery level, sleep/wake, or a
-* motion email) on the order of hours even with no visitors, and the snapshot
-* wrapper's own battery window is 1 hour. Six hours is therefore several
-* missed opportunities, not one — so a single quiet night does not raise a
-* fault, and a genuinely flat camera is named well inside a day.
-*/
-var BATTERY_UNREACHABLE_AFTER_MS = 360 * 6e4;
 DeviceType.Cover, DeviceType.Valve, DeviceType.Humidifier, DeviceType.WaterHeater, DeviceType.Camera, DeviceType.Hub, DeviceType.Switch, DeviceType.Siren, DeviceType.Light, DeviceType.Fan, DeviceType.Sensor, DeviceType.Thermostat, DeviceType.Climate, DeviceType.Button, DeviceType.EventEmitter, DeviceType.Update, DeviceType.Generic, DeviceType.Notifier, DeviceType.Script, DeviceType.Automation, DeviceType.Lock, DeviceType.MediaPlayer, DeviceType.AlarmPanel, DeviceType.Control, DeviceType.Presence, DeviceType.Weather, DeviceType.Vacuum, DeviceType.LawnMower, DeviceType.Container, DeviceType.Image, DeviceType.PetFeeder;
 new Set(Object.values(DeviceType));
 Object.freeze({
@@ -58488,6 +58519,9 @@ new Map(Object.entries({
 	"stream-online": "device-events",
 	"stream-offline": "device-events",
 	"detection-blind": "device-events",
+	"recording-stalled": "device-events",
+	"recording-healthy": "device-events",
+	"recording-degraded": "device-events",
 	"node-online": "system",
 	"node-offline": "system",
 	"node-restarting": "system",
@@ -58501,6 +58535,9 @@ new Map(Object.entries({
 	"wrapper-update-available": "system",
 	"backup-completed": "system",
 	"export-completed": "system",
+	"storage-location-low": "system",
+	"storage-location-critical": "system",
+	"storage-location-ok": "system",
 	"alarm-triggered": "alarm",
 	"alarm-armed": "alarm",
 	"alarm-disarmed": "alarm",
@@ -58562,6 +58599,16 @@ var NC_SYSTEM_EVENT_KIND_GROUP_SPECS = [
 		label: "Detecting nothing",
 		kinds: ["detection-blind"]
 	},
+	{
+		id: "recording",
+		family: "device-events",
+		label: "Recording",
+		kinds: [
+			"recording-stalled",
+			"recording-healthy",
+			"recording-degraded"
+		]
+	},
 	{
 		id: "nodes",
 		family: "system",
@@ -58602,6 +58649,16 @@ var NC_SYSTEM_EVENT_KIND_GROUP_SPECS = [
 		label: "Backups & exports",
 		kinds: ["backup-completed", "export-completed"]
 	},
+	{
+		id: "storage",
+		family: "system",
+		label: "Storage locations",
+		kinds: [
+			"storage-location-low",
+			"storage-location-critical",
+			"storage-location-ok"
+		]
+	},
 	{
 		id: "alarm",
 		family: "alarm",
@@ -58684,6 +58741,9 @@ var DEVICE_EVENTS = [
 	"stream-online",
 	"stream-offline",
 	"detection-blind",
+	"recording-stalled",
+	"recording-healthy",
+	"recording-degraded",
 	...ALARM
 ];
 /** Every kind a summary may speak about — the two summarisable families. */
@@ -58851,6 +58911,11 @@ var STATE_SUMMARY_VARS = [
 	[...RULE_TEXT],
 	[...RULE_TEXT],
 	[...RULE_TEXT],
+	[...RULE_TEXT],
+	[...RULE_TEXT],
+	[...RULE_TEXT],
+	[...RULE_TEXT],
+	[...RULE_TEXT],
 	([...RULE_TEXT], [...UPDATES]),
 	([...RULE_TEXT], [...PACKAGE_UPDATES]),
 	([...RULE_TEXT], [...PACKAGE_UPDATES]),
@@ -71522,7 +71587,7 @@ var require_snapshot_utils = /* @__PURE__ */ require_chunk.__commonJSMin(((expor
 //#region ../../node_modules/undici/lib/mock/snapshot-recorder.js
 var require_snapshot_recorder = /* @__PURE__ */ require_chunk.__commonJSMin(((exports, module) => {
 	var { writeFile: writeFile$2, readFile: readFile$3, mkdir: mkdir$2 } = require("node:fs/promises");
-	var { dirname: dirname$1, resolve } = require("node:path");
+	var { dirname: dirname$2, resolve: resolve$1 } = require("node:path");
 	var { setTimeout: setTimeout$1, clearTimeout: clearTimeout$1 } = require("node:timers");
 	var { InvalidArgumentError, UndiciError } = require_errors$1();
 	var { hashId, isUrlExcludedFactory, normalizeHeaders, createHeaderFilters } = require_snapshot_utils();
@@ -71787,7 +71852,7 @@ var require_snapshot_recorder = /* @__PURE__ */ require_chunk.__commonJSMin(((ex
 			const path = filePath || this.#snapshotPath;
 			if (!path) throw new InvalidArgumentError("Snapshot path is required");
 			try {
-				const data = await readFile$3(resolve(path), "utf8");
+				const data = await readFile$3(resolve$1(path), "utf8");
 				const parsed = JSON.parse(data);
 				if (Array.isArray(parsed)) {
 					this.#snapshots.clear();
@@ -71807,8 +71872,8 @@ var require_snapshot_recorder = /* @__PURE__ */ require_chunk.__commonJSMin(((ex
 		async saveSnapshots(filePath) {
 			const path = filePath || this.#snapshotPath;
 			if (!path) throw new InvalidArgumentError("Snapshot path is required");
-			const resolvedPath = resolve(path);
-			await mkdir$2(dirname$1(resolvedPath), { recursive: true });
+			const resolvedPath = resolve$1(path);
+			await mkdir$2(dirname$2(resolvedPath), { recursive: true });
 			const data = Array.from(this.#snapshots.entries()).map(([hash, snapshot]) => ({
 				hash,
 				snapshot
@@ -160445,6 +160510,7 @@ function buildInitialStatus2(config, enabled) {
 		lastErrorMessage: void 0
 	};
 }
+process.platform, process.env["SystemRoot"];
 /**
 * The spawn a one-shot ffmpeg site uses: the spec's seam when one is injected,
 * else the node's PINNED binary (D540), else `null` — and the site refuses by
@@ -161017,6 +161083,13 @@ var reolinkCameraSchema = object({
 	*/
 	clipCatalogForcedWake: boolean().optional(),
 	/**
+	* Battery cameras only: the window, in minutes, in which the camera refreshes
+	* ALL its metadata and its cached snapshot exactly once (D847). Absent means
+	* the default (60); `0` turns the scheduled refresh off for this camera; a
+	* value is clamped to 15..240 (below the 6 h presence budget).
+	*/
+	batteryRefreshMinutes: number().int().min(0).max(240).optional(),
+	/**
 	* Per-AI-class sensitivity overrides — pushed via
 	* `setAiDetection(aiType, sensitivity)` (cmdId=343). Reolink
 	* range 0..100 — same scale the reolink_aio CGI exposes
@@ -167274,14 +167347,266 @@ function deriveChargingSource(adapterStatus, chargeStatus) {
 function reportsPowerSource(info) {
 	return info.adapterStatus !== void 0 || info.chargeStatus !== void 0;
 }
+/** The settings key, per device. */
+var BATTERY_REFRESH_MINUTES_KEY = "batteryRefreshMinutes";
+/** How often the in-memory check runs. Costs nothing: no I/O unless it fires. */
+var BATTERY_REFRESH_TICK_MS = 6e4;
+/** The least time between two attempts in one window. */
+var RETRY_BACKOFF_MS = 10 * 6e4;
+var MAX_WAKE_LEAD_MS = 5 * 6e4;
+var STAGGER_SLOTS = 60;
+/** The operator's window in ms, or `0` for off. Out-of-range values clamp. */
+function resolveBatteryRefreshIntervalMs(configured) {
+	if (typeof configured !== "number" || !Number.isFinite(configured)) return 60 * 6e4;
+	if (configured <= 0) return 0;
+	return Math.min(240, Math.max(15, Math.round(configured))) * 6e4;
+}
+/** Deterministic per-device offset so a fleet's windows do not align. */
+function staggerOffsetMs(deviceId, intervalMs) {
+	const slot = Math.abs(Math.trunc(deviceId)) % STAGGER_SLOTS;
+	return Math.floor(intervalMs / STAGGER_SLOTS * slot);
+}
+/** Which window a wall-clock instant falls in. */
+function windowIndex(at, intervalMs, offsetMs) {
+	return Math.floor((at - offsetMs) / intervalMs);
+}
+/** How long before a window's end the wake is allowed to fire. */
+function wakeLeadMs(intervalMs) {
+	return Math.min(MAX_WAKE_LEAD_MS, Math.floor(intervalMs / 10));
+}
+function decideBatteryRefresh(input) {
+	if (input.intervalMs <= 0) return {
+		kind: "skip",
+		reason: "off"
+	};
+	const current = windowIndex(input.nowMs, input.intervalMs, input.offsetMs);
+	if ((typeof input.lastFullRefreshAt === "number" && input.lastFullRefreshAt > 0 ? windowIndex(input.lastFullRefreshAt, input.intervalMs, input.offsetMs) : Number.NEGATIVE_INFINITY) >= current) return {
+		kind: "skip",
+		reason: "done"
+	};
+	if (input.attemptsInWindow >= 2) return {
+		kind: "skip",
+		reason: "attempts-exhausted"
+	};
+	if (input.lastAttemptAt !== void 0 && input.attemptsInWindow > 0 && input.nowMs - input.lastAttemptAt < 6e5) return {
+		kind: "skip",
+		reason: "backoff"
+	};
+	if (input.awake) return { kind: "refresh-awake" };
+	const windowEnd = input.offsetMs + (current + 1) * input.intervalMs;
+	if (input.nowMs < windowEnd - wakeLeadMs(input.intervalMs)) return {
+		kind: "skip",
+		reason: "asleep-before-deadline"
+	};
+	return { kind: "wake-then-refresh" };
+}
+var BatteryHourlyRefresh = class {
+	deps;
+	inFlight = null;
+	attemptWindow = Number.NEGATIVE_INFINITY;
+	attempts = 0;
+	lastAttemptAt;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* The periodic check. Resolves `true` when a refresh landed in this call.
+	* Never throws.
+	*/
+	async tick() {
+		return this.consider("tick");
+	}
+	/**
+	* The camera was just observed coming up (event, sleep poll, hub summary, a
+	* confirmed wake). Resolves `true` when this call refreshed everything, so
+	* the caller can skip the parts of its own fan-out the refresh already did.
+	*/
+	async noteAwake() {
+		return this.consider("wake-transition");
+	}
+	async consider(trigger) {
+		if (this.inFlight !== null) return this.inFlight;
+		const nowMs = this.deps.now();
+		const intervalMs = this.deps.intervalMs();
+		const offsetMs = intervalMs > 0 ? staggerOffsetMs(this.deps.deviceId, intervalMs) : 0;
+		const window = intervalMs > 0 ? windowIndex(nowMs, intervalMs, offsetMs) : 0;
+		if (window !== this.attemptWindow) {
+			this.attemptWindow = window;
+			this.attempts = 0;
+			this.lastAttemptAt = void 0;
+		}
+		const decision = decideBatteryRefresh({
+			nowMs,
+			intervalMs,
+			offsetMs,
+			lastFullRefreshAt: this.deps.lastFullRefreshAt(),
+			awake: trigger === "wake-transition" || this.deps.isAwake(),
+			attemptsInWindow: this.attempts,
+			lastAttemptAt: this.lastAttemptAt
+		});
+		if (decision.kind === "skip") {
+			this.logSkip(decision.reason, trigger);
+			return false;
+		}
+		this.attempts += 1;
+		this.lastAttemptAt = nowMs;
+		const run = this.run(decision.kind, trigger).finally(() => {
+			this.inFlight = null;
+		});
+		this.inFlight = run;
+		return run;
+	}
+	async run(kind, trigger) {
+		const { logger, deviceId } = this.deps;
+		try {
+			if (kind === "wake-then-refresh") {
+				logger.info("battery hourly refresh: not awake in the window — waking once", {
+					tags: { deviceId },
+					meta: { attempt: this.attempts }
+				});
+				if (!await this.deps.wake()) {
+					logger.warn("battery hourly refresh: the wake did not bring the camera up", {
+						tags: { deviceId },
+						meta: {
+							attempt: this.attempts,
+							retryAfterMs: RETRY_BACKOFF_MS
+						}
+					});
+					return false;
+				}
+				if (this.windowSatisfied()) return true;
+			} else logger.info("battery hourly refresh: camera is awake — refreshing now, no wake", {
+				tags: { deviceId },
+				meta: {
+					trigger,
+					attempt: this.attempts
+				}
+			});
+			const outcome = await this.deps.refreshAll();
+			if (outcome.failed.length > 0) {
+				logger.warn("battery hourly refresh incomplete — not stamped, retried at the next chance", {
+					tags: { deviceId },
+					meta: {
+						failed: outcome.failed,
+						attempt: this.attempts,
+						retryAfterMs: RETRY_BACKOFF_MS
+					}
+				});
+				return false;
+			}
+			const at = this.deps.now();
+			this.deps.stamp(at);
+			logger.info("battery hourly refresh complete", {
+				tags: { deviceId },
+				meta: {
+					kind,
+					trigger,
+					at
+				}
+			});
+			return true;
+		} catch (err) {
+			logger.warn("battery hourly refresh failed — retried at the next chance", {
+				tags: { deviceId },
+				meta: {
+					error: err instanceof Error ? err.message : String(err),
+					attempt: this.attempts,
+					retryAfterMs: RETRY_BACKOFF_MS
+				}
+			});
+			return false;
+		}
+	}
+	windowSatisfied() {
+		const intervalMs = this.deps.intervalMs();
+		if (intervalMs <= 0) return false;
+		const offsetMs = staggerOffsetMs(this.deps.deviceId, intervalMs);
+		const last = this.deps.lastFullRefreshAt();
+		if (typeof last !== "number" || last <= 0) return false;
+		return windowIndex(last, intervalMs, offsetMs) >= windowIndex(this.deps.now(), intervalMs, offsetMs);
+	}
+	logSkip(reason, trigger) {
+		if (reason === "backoff" || reason === "attempts-exhausted") {
+			this.deps.logger.info("battery hourly refresh skipped", {
+				tags: { deviceId: this.deps.deviceId },
+				meta: {
+					reason,
+					trigger,
+					attempts: this.attempts
+				}
+			});
+			return;
+		}
+		this.deps.logger.debug("battery hourly refresh not due", {
+			tags: { deviceId: this.deps.deviceId },
+			meta: {
+				reason,
+				trigger
+			}
+		});
+	}
+};
+//#endregion
+//#region src/battery-refresh-settings.ts
+var BATTERY_REFRESH_SECTION_ID = "battery-refresh";
+var BATTERY_REFRESH_MINUTES_DESCRIPTION = `Once per window this camera refreshes everything CamStack knows about it — battery level and charging, signal, device info, every state panel and the cached snapshot. If the camera is awake at some point in the window (a motion event, a live view, anything that woke it) it is refreshed then and not woken again; if the whole window passes with the camera asleep, it is woken ONCE near the end of the window, refreshed, and left to go back to sleep. A camera that does not answer is retried at most twice per window. 15–240 minutes, default 60; 0 turns the scheduled refresh off (the battery level then ages until the camera next wakes by itself).`;
+/** Battery cameras only: a mains camera keeps its facts fresh on its own socket. */
+function buildBatteryRefreshDeviceSection(input) {
+	if (!input.isBattery) return [];
+	return [{
+		id: BATTERY_REFRESH_SECTION_ID,
+		tab: "general",
+		title: "Scheduled refresh",
+		description: "How often this battery camera is guaranteed to have been read, so a battery level never goes stale unseen.",
+		columns: 1,
+		fields: [{
+			type: "number",
+			key: BATTERY_REFRESH_MINUTES_KEY,
+			label: "Refresh window (min)",
+			description: BATTERY_REFRESH_MINUTES_DESCRIPTION,
+			default: 60,
+			min: 0,
+			max: 240,
+			step: 5
+		}]
+	}];
+}
 //#endregion
-//#region src/battery-contact-expiry.ts
-function shouldWakeForContact(input) {
-	if (input.hubChild) return false;
-	if (!input.sleeping) return false;
-	const last = input.lastContactAt;
-	if (typeof last !== "number" || last <= 0) return false;
-	return input.nowMs - last + input.tickMs >= input.unreachableAfterMs;
+//#region src/battery-snapshot-refresh.ts
+/** The wrapper may run on another node; a stale frame is hours old, skew is seconds. */
+var CLOCK_SKEW_TOLERANCE_MS = 6e4;
+async function refreshSnapshotCacheOnce(input) {
+	const { deviceId, api, logger } = input;
+	const startedAt = input.now();
+	if (await api.getSnapshot({
+		deviceId,
+		force: true
+	}) === null) {
+		logger.warn("battery hourly refresh: the snapshot came back empty", { tags: { deviceId } });
+		return false;
+	}
+	let rows;
+	try {
+		rows = await api.getSnapshotOverview({ deviceIds: [deviceId] });
+	} catch (err) {
+		logger.debug("battery hourly refresh: snapshot overview unreadable — counting the image", {
+			tags: { deviceId },
+			meta: { error: err instanceof Error ? err.message : String(err) }
+		});
+		return true;
+	}
+	const capturedAt = rows.find((row) => row.deviceId === deviceId)?.lastCapturedAt ?? null;
+	if (capturedAt === null || capturedAt < startedAt - CLOCK_SKEW_TOLERANCE_MS) {
+		logger.warn("battery hourly refresh: the snapshot cache did not move (a stale frame was served)", {
+			tags: { deviceId },
+			meta: {
+				capturedAt,
+				startedAt
+			}
+		});
+		return false;
+	}
+	return true;
 }
 //#endregion
 //#region src/log-channels.ts
@@ -171284,7 +171609,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	*  passively checks sleep state, and short-circuits if sleeping. */
 	batteryUpdateTimer = null;
 	/** Single-flight gate so two interval fires can't overlap. */
-	batteryUpdateInFlight = null;
 	/** Aux accessory references registered by spawned children
 	*  (siren / floodlight / pir). The parent's centralised align
 	*  method iterates these to refresh their slices on a single
@@ -171622,7 +171946,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	* snapshot also drives the dispatch's known-good baseline.
 	*/
 	async refreshParentSettingsSnapshot(slices, reason = "background") {
-		if (this.isBattery && this.sleeping && reason !== "post-write") {
+		if (this.isBattery && this.sleeping && reason !== "post-write" && reason !== "scheduled") {
 			this.ctx.logger.info("refreshParentSettingsSnapshot skipped — battery cam is sleeping", { tags: {
 				deviceId: this.id,
 				reason
@@ -172568,7 +172892,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				tags: { deviceId: this.id },
 				meta: { reason }
 			});
-			return;
+			return false;
 		}
 		let api;
 		try {
@@ -172578,17 +172902,19 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				tags: { deviceId: this.id },
 				meta: { error: err instanceof Error ? err.message : String(err) }
 			});
-			return;
+			return false;
 		}
 		try {
 			const info = await api.getBatteryInfo(this.getChannel());
 			this.updateBatteryCache(info);
 			await this.refreshNetworkLinkFromApi(api, "battery");
+			return true;
 		} catch (err) {
 			this.ctx.logger.debug("battery refresh failed", {
 				tags: { deviceId: this.id },
 				meta: { error: err instanceof Error ? err.message : String(err) }
 			});
+			return false;
 		}
 	}
 	/**
@@ -173834,6 +174160,18 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	* proactive gate lets it through because `sleeping` is false here.
 	* Mirrors the reference's `updateBatteryAndSnapshot`.
 	*/
+	/** The scheduled refresh's snapshot step: true only when the cache really moved. */
+	refreshSnapshotCache() {
+		return refreshSnapshotCacheOnce({
+			deviceId: this.id,
+			logger: this.ctx.logger,
+			now: () => Date.now(),
+			api: {
+				getSnapshot: (input) => this.ctx.api.snapshot.getSnapshot.query(input),
+				getSnapshotOverview: (input) => this.ctx.api.snapshot.getSnapshotOverview.query({ deviceIds: [...input.deviceIds] })
+			}
+		});
+	}
 	async warmSnapshotOnWake() {
 		try {
 			await this.ctx.api.snapshot.getSnapshot.query({
@@ -176269,119 +176607,84 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 			this.alignAuxTimer = null;
 		}
 	}
-	/** Run one cycle of the battery-cam periodic refresh. Single-flight
-	*  via `batteryUpdateInFlight`. Never throws. */
-	async runBatteryUpdate() {
-		if (this.batteryUpdateInFlight) return this.batteryUpdateInFlight;
-		const cycle = (async () => {
+	batteryRefresh = null;
+	getBatteryRefresh() {
+		if (this.batteryRefresh === null) this.batteryRefresh = new BatteryHourlyRefresh({
+			deviceId: this.id,
+			logger: this.ctx.logger,
+			now: () => Date.now(),
+			isAwake: () => !this.sleeping,
+			intervalMs: () => resolveBatteryRefreshIntervalMs(this.config.get("batteryRefreshMinutes")),
+			lastFullRefreshAt: () => this.state.battery.lastFullRefreshAt,
+			wake: async () => {
+				if (!this.canProactivelyWake("scheduled-refresh")) return false;
+				this.markWakeIssued();
+				return this.wakeIfSleeping();
+			},
+			refreshAll: () => this.refreshEverythingNow(),
+			stamp: (at) => {
+				this.state.battery.lastFullRefreshAt = at;
+			}
+		});
+		return this.batteryRefresh;
+	}
+	/**
+	* Every fact and the snapshot, read while the camera is up. SERIALIZED (one
+	* Baichuan round-trip at a time on the single BCUDP stream), and each step
+	* names itself in `failed` instead of throwing, so one dead read neither
+	* hides the others nor stamps the window as done.
+	*/
+	async refreshEverythingNow() {
+		const failed = [];
+		const step = async (name, run) => {
 			try {
-				if (this.isBattery && this.sleeping) {
-					if (shouldWakeForContact({
-						nowMs: Date.now(),
-						lastContactAt: this.state.battery.lastContactAt,
-						sleeping: true,
-						hubChild: this.isHubChild(),
-						unreachableAfterMs: 216e5,
-						tickMs: ReolinkCamera.BATTERY_UPDATE_INTERVAL_MS
-					})) {
-						await this.wakeForContactRefresh();
-						return;
-					}
-					this.ctx.logger.debug("battery-update: cam sleeping — skipping cycle without connecting", { tags: { deviceId: this.id } });
-					return;
-				}
-				let api;
-				try {
-					api = await this.ensureApi();
-				} catch (err) {
-					this.ctx.logger.debug("battery-update: ensureApi failed — skipping cycle", {
-						tags: { deviceId: this.id },
-						meta: { error: err instanceof Error ? err.message : String(err) }
-					});
-					return;
-				}
-				let sleeping = false;
-				try {
-					sleeping = api.getSleepStatus({ channel: this.getChannel() }).state === "sleeping";
-				} catch (err) {
-					this.ctx.logger.debug("battery-update: getSleepStatus threw — skipping cycle", {
-						tags: { deviceId: this.id },
-						meta: { error: err instanceof Error ? err.message : String(err) }
-					});
-					return;
-				}
-				if (sleeping) {
-					this.ctx.logger.debug("battery-update: cam sleeping — skipping periodic refresh", { tags: { deviceId: this.id } });
-					return;
-				}
-				this.ctx.logger.info("battery-update: cam awake — running periodic refresh", {
+				if (await run() === false) failed.push(name);
+			} catch (err) {
+				failed.push(name);
+				this.ctx.logger.debug("battery hourly refresh: step threw", {
 					tags: { deviceId: this.id },
 					meta: {
-						isHubChild: this.isHubChild(),
-						auxAccessoryCount: this.auxAccessoryRefs.size
+						step: name,
+						error: err instanceof Error ? err.message : String(err)
 					}
 				});
-				await this.refreshBatteryFromApi("periodic").catch(() => {});
-				await this.alignAuxDevicesState("periodic").catch(() => {});
-				await this.refreshParentSettingsSnapshot().catch(() => {});
-			} finally {
-				this.batteryUpdateInFlight = null;
 			}
-		})();
-		this.batteryUpdateInFlight = cycle;
-		return cycle;
+		};
+		await step("battery", () => this.refreshBatteryFromApi("demand"));
+		await step("device-info", async () => {
+			await this.populateMetadataFromFirmware(await this.ensureApi());
+		});
+		await step("cap-slices", async () => {
+			await this.warmCapSlicesOnWake({ force: true });
+		});
+		await step("aux-accessories", () => this.alignAuxDevicesState("wake"));
+		await step("settings-snapshot", () => this.refreshParentSettingsSnapshot(void 0, "scheduled"));
+		await step("snapshot", () => this.refreshSnapshotCache());
+		return { failed };
 	}
 	/**
-	* D355: wake a standalone battery camera ONCE because its last passive
-	* contact is about to expire, and refresh every slice while it is up.
-	* Bounded by `canProactivelyWake` (the shared cooldown) and by the fact
-	* that a wake that answers resets the silence. A wake that fails is left
-	* alone: the silence then reaches the budget and `deriveBatteryPresence`
-	* says `unreachable` — for the first time on evidence.
+	* Run one scheduled-refresh check. Never throws; costs nothing unless a
+	* refresh is due (see {@link decideBatteryRefresh}).
 	*/
-	async wakeForContactRefresh() {
-		if (!this.canProactivelyWake("contact-expiry")) return;
-		this.markWakeIssued();
-		const lastContactAt = this.state.battery.lastContactAt ?? 0;
-		const silenceMs = Date.now() - lastContactAt;
-		this.ctx.logger.info("battery contact expiring — waking once to refresh every slice (D355)", {
-			tags: { deviceId: this.id },
-			meta: {
-				silenceMs,
-				budgetMs: BATTERY_UNREACHABLE_AFTER_MS
-			}
-		});
-		try {
-			await this.ensureApi();
-		} catch (err) {
-			this.ctx.logger.warn("battery contact wake FAILED — silence continues and the camera will read unreachable at the budget", {
-				tags: { deviceId: this.id },
-				meta: {
-					silenceMs,
-					error: err instanceof Error ? err.message : String(err)
-				}
-			});
-			return;
-		}
-		await this.refreshBatteryFromApi("demand").catch(() => {});
-		await this.warmCapSlicesOnWake().catch(() => {});
-		await this.alignAuxDevicesState("wake").catch(() => {});
-		await this.warmSnapshotOnWake().catch(() => {});
+	async runBatteryUpdate() {
+		if (!this.isBattery) return;
+		await this.getBatteryRefresh().tick();
 	}
-	/** Arm the periodic battery-cam refresh timer. No-op for wired cams
-	*  (their state is kept fresh by the 10 s aux-align poll and push
-	*  events). Idempotent. */
+	/** Arm the scheduled-refresh check. No-op for wired cams (their state is
+	*  kept fresh by the 10 s aux-align poll and push events). Idempotent. */
 	startBatteryUpdatePolling() {
 		if (this.batteryUpdateTimer) return;
 		if (!this.isBattery) return;
 		this.batteryUpdateTimer = setInterval(() => {
 			this.runBatteryUpdate().catch(() => {});
-		}, ReolinkCamera.BATTERY_UPDATE_INTERVAL_MS);
+		}, BATTERY_REFRESH_TICK_MS);
 		if (typeof this.batteryUpdateTimer.unref === "function") this.batteryUpdateTimer.unref();
-		this.ctx.logger.info("battery-update: periodic refresh armed", {
+		this.ctx.logger.info("battery-update: scheduled full refresh armed", {
 			tags: { deviceId: this.id },
 			meta: {
-				intervalMs: ReolinkCamera.BATTERY_UPDATE_INTERVAL_MS,
+				tickMs: BATTERY_REFRESH_TICK_MS,
+				intervalMs: resolveBatteryRefreshIntervalMs(this.config.get("batteryRefreshMinutes")),
+				lastFullRefreshAt: this.state.battery.lastFullRefreshAt ?? null,
 				isHubChild: this.isHubChild()
 			}
 		});
@@ -176477,22 +176780,18 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				meta: { error: err instanceof Error ? err.message : String(err) }
 			});
 		}
-		await this.warmCapSlicesOnWake();
-		await this.warmSnapshotOnWake();
-		await this.alignAuxDevicesState("wake");
-		await this.refreshParentSettingsSnapshot();
+		if (!(this.isBattery ? await this.getBatteryRefresh().noteAwake().catch(() => false) : false)) {
+			await this.warmCapSlicesOnWake();
+			await this.warmSnapshotOnWake();
+			await this.alignAuxDevicesState("wake");
+			await this.refreshParentSettingsSnapshot();
+		}
 		await this.refreshClipCatalogOnWake();
 	}
 	static PING_INTERVAL_MS = 3e4;
 	static PING_MAX_FAILURES = 3;
 	static EVENT_CHECK_INTERVAL_MS = 6e4;
 	static EVENT_STALE_THRESHOLD_MS = 10 * 6e4;
-	/** Battery-cam periodic refresh cadence. The timer fires on this
-	*  interval, passively checks sleep state, and only runs the
-	*  refresh when the cam is already awake — so it never forces a
-	*  wake. Mirrors the reference's `batteryUpdateIntervalMinutes`
-	*  default (60 minutes). */
-	static BATTERY_UPDATE_INTERVAL_MS = 60 * 6e4;
 	/**
 	* Arm the connection-liveness ping watchdog and the event-watchdog.
 	* Battery cams skip the ping watchdog — they keep `setIdleDisconnect=true`
@@ -177676,7 +177975,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				...buildClipRefreshDeviceSection({
 					isHubChild: this.isHubChild(),
 					isBattery: this.isBattery
-				})
+				}),
+				...buildBatteryRefreshDeviceSection({ isBattery: this.isBattery })
 			]
 		};
 		const emailSnap = cache?.emailConfigSnapshot;
@@ -177697,6 +177997,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 			emailScheduleEnabled: emailSnap?.taskEnabled ?? false,
 			clipCatalogRefreshMinutes: this.config.get("clipCatalogRefreshMinutes"),
 			clipCatalogForcedWake: this.config.get("clipCatalogForcedWake") ?? false,
+			batteryRefreshMinutes: this.config.get("batteryRefreshMinutes"),
 			debugGeneral: this.config.get("debugGeneral") ?? false,
 			debugSocketLogs: this.config.get("debugSocketLogs") ?? [],
 			motionEnabled: this.config.get("motionEnabled") ?? motionSnap.enabled ?? true,