@camstack/types 1.2.427 → 1.2.429

package/dist/index.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-edKiOXLo.js");
+const require_sleep = require("./sleep-hRhTSDlN.js");
 const require_event_category = require("./event-category-Ave2VSxY.js");
 const require_composition = require("./composition-CpAc0YfQ.js");
 const require_node_color = require("./node-color.js");
@@ -289,6 +289,254 @@ function buildCapturingReply(envelope) {
 	return wrapper;
 }
 //#endregion
+//#region src/addon/session-health.ts
+var SESSION_LOST_ALERT_CATEGORY = "integration.session-lost";
+var SESSION_EPISODE_KEY = "session-lost";
+/** A transient reconnect is quiet for this long before it is worth an alert. */
+var DEFAULT_SESSION_LOST_DEBOUNCE_MS = 2 * 6e4;
+var REASON_TEXT = {
+	kicked: "the account was signed in on another device, which ended this session",
+	"auth-rejected": "the cloud rejected the sign-in (check the credentials)",
+	"token-expired": "the session token expired and could not be renewed",
+	"connection-lost": "the connection to the cloud was lost"
+};
+function sessionLostAlertId(kind, integrationId) {
+	return `session:${kind}:${integrationId}`;
+}
+/** Pure builder, exported so an addon with its own flow can still emit the standard shape. */
+function buildSessionLostAlert(input) {
+	const now = input.now ?? Date.now();
+	return {
+		id: sessionLostAlertId(input.kind, input.integrationId),
+		category: SESSION_LOST_ALERT_CATEGORY,
+		severity: input.severity ?? "error",
+		title: `${input.providerName} connection lost`,
+		message: `${input.integrationName} lost its ${input.providerName} session: ${REASON_TEXT[input.reason]}.`,
+		action: input.action ?? {
+			label: "Open integration",
+			href: `/integrations/${encodeURIComponent(input.integrationId)}`
+		},
+		status: "active",
+		read: false,
+		createdAt: now,
+		updatedAt: now,
+		source: {
+			type: input.kind,
+			id: input.integrationId
+		},
+		metadata: {
+			episodeKey: SESSION_EPISODE_KEY,
+			reason: input.reason
+		}
+	};
+}
+var SessionHealthTracker = class {
+	#opts;
+	#debounceMs;
+	#entries = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.#opts = opts;
+		this.#debounceMs = opts.debounceMs ?? 12e4;
+	}
+	/** The session is gone. Idempotent: call it on every failed poll. */
+	lost(integrationId, info) {
+		const tags = { integrationId };
+		const entry = this.#entries.get(integrationId);
+		if (entry === void 0 || entry.phase === "ok") {
+			const timer = setTimeout(() => void this.#fire(integrationId), this.#debounceMs);
+			this.#entries.set(integrationId, {
+				phase: "pending",
+				info,
+				timer
+			});
+			this.#opts.logger.info(`${this.#opts.providerName} session lost — alert after ${this.#debounceMs}ms unless it recovers`, {
+				tags,
+				meta: { reason: info.reason }
+			});
+			return;
+		}
+		entry.info = info;
+		if (entry.phase === "pending") {
+			this.#opts.logger.debug(`${this.#opts.providerName} session still lost — alert pending`, {
+				tags,
+				meta: { reason: info.reason }
+			});
+			return;
+		}
+		if (entry.phase === "unsent") {
+			this.#emit(integrationId, entry);
+			return;
+		}
+		this.#opts.logger.debug(`${this.#opts.providerName} session still lost — alert already active`, {
+			tags,
+			meta: { reason: info.reason }
+		});
+	}
+	/** A call went through. Idempotent: call it on every successful poll. */
+	async restored(integrationId) {
+		const tags = { integrationId };
+		const entry = this.#entries.get(integrationId);
+		if (entry === void 0) {
+			this.#entries.set(integrationId, {
+				phase: "ok",
+				info: EMPTY_INFO,
+				timer: null
+			});
+			if (!await this.#resolve(integrationId, "startup reconcile")) this.#entries.delete(integrationId);
+			return;
+		}
+		if (entry.phase === "ok") return;
+		this.#clearTimer(entry);
+		const previous = entry.phase;
+		entry.phase = "ok";
+		if (previous === "pending" || previous === "unsent") {
+			this.#opts.logger.info(`${this.#opts.providerName} session recovered inside the debounce — no alert`, { tags });
+			return;
+		}
+		await this.#resolve(integrationId, "session restored");
+	}
+	/** The integration is gone (deleted / disabled): drop its state and its alert. */
+	async forget(integrationId) {
+		const entry = this.#entries.get(integrationId);
+		if (entry === void 0) return;
+		this.#clearTimer(entry);
+		this.#entries.delete(integrationId);
+		if (entry.phase === "alerted") await this.#resolve(integrationId, "integration removed");
+	}
+	/** Stop every pending timer (addon shutdown). */
+	dispose() {
+		for (const entry of this.#entries.values()) this.#clearTimer(entry);
+		this.#entries.clear();
+	}
+	#clearTimer(entry) {
+		if (entry.timer !== null) clearTimeout(entry.timer);
+		entry.timer = null;
+	}
+	async #fire(integrationId) {
+		const entry = this.#entries.get(integrationId);
+		if (entry === void 0 || entry.phase !== "pending") return;
+		entry.timer = null;
+		await this.#emit(integrationId, entry);
+	}
+	async #emit(integrationId, entry) {
+		const tags = { integrationId };
+		const emit = this.#opts.getAlerts()?.emit;
+		if (emit === void 0) {
+			entry.phase = "unsent";
+			this.#opts.logger.warn(`${this.#opts.providerName} session alert skipped — alerts capability missing`, { tags });
+			return;
+		}
+		try {
+			await emit.mutate(buildSessionLostAlert({
+				kind: this.#opts.kind,
+				providerName: this.#opts.providerName,
+				integrationId,
+				integrationName: entry.info.integrationName,
+				reason: entry.info.reason,
+				...entry.info.action !== void 0 ? { action: entry.info.action } : {}
+			}));
+			entry.phase = "alerted";
+			this.#opts.logger.warn(`${this.#opts.providerName} session lost — alert raised`, {
+				tags,
+				meta: { reason: entry.info.reason }
+			});
+		} catch (err) {
+			entry.phase = "unsent";
+			this.#opts.logger.warn(`${this.#opts.providerName} session alert emit failed`, {
+				tags,
+				meta: { error: err instanceof Error ? err.message : String(err) }
+			});
+		}
+	}
+	async #resolve(integrationId, why) {
+		const tags = { integrationId };
+		const update = this.#opts.getAlerts()?.update;
+		if (update === void 0) {
+			this.#opts.logger.debug(`${this.#opts.providerName} session alert not resolved — no alerts cap`, { tags });
+			return false;
+		}
+		try {
+			await update.mutate({
+				alertId: sessionLostAlertId(this.#opts.kind, integrationId),
+				patch: {
+					status: "completed",
+					read: true
+				}
+			});
+			this.#opts.logger.info(`${this.#opts.providerName} session alert resolved`, {
+				tags,
+				meta: { why }
+			});
+		} catch (err) {
+			this.#opts.logger.debug(`${this.#opts.providerName} session alert resolve skipped`, {
+				tags,
+				meta: {
+					why,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+		}
+		return true;
+	}
+};
+var EMPTY_INFO = {
+	integrationName: "",
+	reason: "connection-lost"
+};
+/**
+* The addon-facing face of {@link SessionHealthTracker}: a process-wide object an
+* integration manager AND its device classes can reach (the kernel builds a
+* device from a `DeviceContext` alone, so neither can be handed a tracker).
+* The addon `bind()`s it in `onInitialize`, `unbind()`s it on shutdown and
+* `forget()`s an integration that vanished; everything before `bind` is a no-op.
+*/
+var IntegrationSessionReporter = class {
+	#opts;
+	#tracker = null;
+	#names = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.#opts = opts;
+	}
+	bind(binding) {
+		this.#tracker?.dispose();
+		this.#tracker = new SessionHealthTracker({
+			kind: this.#opts.kind,
+			providerName: this.#opts.providerName,
+			logger: binding.logger,
+			getAlerts: binding.getAlerts,
+			...binding.debounceMs !== void 0 ? { debounceMs: binding.debounceMs } : {}
+		});
+	}
+	unbind() {
+		this.#tracker?.dispose();
+		this.#tracker = null;
+	}
+	/** The manager tells us the display name once, so a device can report by id alone. */
+	register(integrationId, integrationName) {
+		this.#names.set(integrationId, integrationName);
+	}
+	/** A call failed. Only a session-ending failure counts; anything else is ignored. */
+	failure(integrationId, err) {
+		const reason = this.#opts.classify(err);
+		if (reason === null) return;
+		const action = this.#opts.action?.(integrationId);
+		this.#tracker?.lost(integrationId, {
+			integrationName: this.#names.get(integrationId) ?? integrationId,
+			reason,
+			...action !== void 0 ? { action } : {}
+		});
+	}
+	/** A call went through. */
+	async ok(integrationId) {
+		await this.#tracker?.restored(integrationId);
+	}
+	/** The integration was removed. */
+	async forget(integrationId) {
+		this.#names.delete(integrationId);
+		await this.#tracker?.forget(integrationId);
+	}
+};
+//#endregion
 //#region src/encode-profile.ts
 /**
 * Shared video / audio encode profile schemas used by every consumer
@@ -13871,7 +14119,7 @@ async function runFanOut(calls, invoke) {
 //#region src/generated/history-catalog.ts
 /**
 * Cap history catalog, projected from every `*.cap.ts` `history` block.
-* 42 caps with series (76 series), 33 caps answered `'none'`.
+* 42 caps with series (77 series), 33 caps answered `'none'`.
 * Field keys are `runtimeState` paths (`a.b` into fixed objects only).
 */
 var HISTORY_CATALOG = {
@@ -14098,6 +14346,7 @@ var HISTORY_CATALOG = {
 	} },
 	"pet-feeder": {
 		"foodLevel": { kind: "gauge" },
+		"bowlFood": { kind: "gauge" },
 		"food1": { kind: "gauge" },
 		"food2": { kind: "gauge" },
 		"batteryPower": {
@@ -43856,7 +44105,7 @@ var NetworkAccessStatusSchema = zod.z.object({
 });
 /**
 * Optional, richer endpoint shape returned by providers that expose
-* MORE than one ingress concurrently (Tailscale Ingress with mixed
+* MORE than one ingress concurrently (Tailscale Funnel with mixed
 * serve+funnel rules, future ngrok multi-tunnel, …). Each entry carries
 * the originating provider config (mode + sourcePort) so the
 * orchestrator UI can label rows distinctly. Providers that expose only
@@ -70222,10 +70471,20 @@ var PetFeederDeviceStatusSchema = zod.z.enum([
 ]);
 var gramsPortion = zod.z.number().int().min(4).max(200);
 var PetFeederStatusSchema = zod.z.object({
-	/** Food currently in the bowl (grams). Null when the device has not
-	*  reported a reading yet. On dual-hopper models this is the combined
-	*  bowl reading; per-hopper levels live in `food1`/`food2`. */
+	/** Food in the TANK (hopper), as the feeder's own sensor reports it
+	*  (`state.food`). A coarse level code, not grams — `0` is empty. The
+	*  amount in the bowl is `bowlFood`. On dual-hopper models this is the
+	*  combined reading; per-hopper levels live in `food1`/`food2`. Null when
+	*  the device has not reported yet. */
 	foodLevel: zod.z.number().nullable().meta(require_sleep.readingMeta("none")),
+	/** Food in the BOWL as the feeder reports it (`state.bowl`), in the
+	*  feeder's own units. Null when the model reports none. */
+	bowlFood: zod.z.number().nullable().meta(require_sleep.readingMeta("none")),
+	/** True while the pet is eating (`state.eating`). */
+	eating: zod.z.boolean(),
+	/** Whether `markFoodReplenished` does anything on this model. When false
+	*  the client must not offer it. */
+	supportsMarkRefilled: zod.z.boolean(),
 	/** Hopper-1 food level (grams) on dual-hopper feeders; null on
 	*  single-hopper models. */
 	food1: zod.z.number().nullable().meta(require_sleep.readingMeta("none")),
@@ -70233,8 +70492,8 @@ var PetFeederStatusSchema = zod.z.object({
 	*  single-hopper models. */
 	food2: zod.z.number().nullable().meta(require_sleep.readingMeta("none")),
 	/** Derived low-food flag — mirrors the HA `food_level` binary_sensor
-	*  (`device_class: problem`, on = low). True when the bowl is empty /
-	*  below the feeder's low threshold. */
+	*  (`device_class: problem`, on = low). True when the tank reports empty,
+	*  or, on a dual-hopper model, when EITHER hopper is empty. */
 	lowFood: zod.z.boolean(),
 	/** Battery charge 0..100 (%). Null on mains-powered models or when the
 	*  device has no battery reading. */
@@ -70302,7 +70561,9 @@ var petFeederCapability = {
 			kind: "mutation",
 			auth: "protected"
 		}),
-		/** Mark a hopper as refilled (D4H/D4S/D4SH). */
+		/** Tell the PetKit cloud a hopper was refilled so it stops its low-food
+		*  reminders (D4H/D4S/D4SH only — see `supportsMarkRefilled`). It does not
+		*  change any sensor reading. */
 		markFoodReplenished: require_sleep.method(zod.z.object({ deviceId: zod.z.number().int().nonnegative() }), zod.z.void(), {
 			kind: "mutation",
 			auth: "protected"
@@ -70375,6 +70636,7 @@ var petFeederCapability = {
 	*/
 	history: { fields: {
 		foodLevel: { kind: "gauge" },
+		bowlFood: { kind: "gauge" },
 		food1: { kind: "gauge" },
 		food2: { kind: "gauge" },
 		batteryPower: {
@@ -117307,6 +117569,7 @@ exports.DEFAULT_POOL_MEMORY_POLICY = DEFAULT_POOL_MEMORY_POLICY;
 exports.DEFAULT_RECORDING_PROFILES = DEFAULT_RECORDING_PROFILES;
 exports.DEFAULT_RETENTION = DEFAULT_RETENTION;
 exports.DEFAULT_RUNTIME_STATE_DURABILITY = require_sleep.DEFAULT_RUNTIME_STATE_DURABILITY;
+exports.DEFAULT_SESSION_LOST_DEBOUNCE_MS = DEFAULT_SESSION_LOST_DEBOUNCE_MS;
 exports.DEFAULT_SESSION_PLACEMENT_POLICY = DEFAULT_SESSION_PLACEMENT_POLICY;
 exports.DEFAULT_SHARE_SOURCE = DEFAULT_SHARE_SOURCE;
 exports.DEFAULT_TIMELAPSE_PREVIEW_TEXT = DEFAULT_TIMELAPSE_PREVIEW_TEXT;
@@ -117652,6 +117915,7 @@ exports.IngestOwnerSchema = IngestOwnerSchema;
 exports.InstalledPackageSchema = InstalledPackageSchema;
 exports.IntegralHelperSpecSchema = require_composition.IntegralHelperSpecSchema;
 exports.IntegrationLiteSchema = IntegrationLiteSchema;
+exports.IntegrationSessionReporter = IntegrationSessionReporter;
 exports.IntegrationWithStateSchema = IntegrationWithStateSchema;
 exports.IntercomAbilitySchema = IntercomAbilitySchema;
 exports.IntercomStatusSchema = IntercomStatusSchema;
@@ -118556,6 +118820,7 @@ exports.SERIAL_CAPACITY_CAMERA_FPS = SERIAL_CAPACITY_CAMERA_FPS;
 exports.SERIES_KINDS = require_composition.SERIES_KINDS;
 exports.SERVER_NAME_MAX_LENGTH = SERVER_NAME_MAX_LENGTH;
 exports.SERVER_NAME_SETTING_KEY = SERVER_NAME_SETTING_KEY;
+exports.SESSION_LOST_ALERT_CATEGORY = SESSION_LOST_ALERT_CATEGORY;
 exports.SESSION_PLACEMENT_SETTING_KEY = SESSION_PLACEMENT_SETTING_KEY;
 exports.SHARE_AFFINITY_TOLERANCE_SESSIONS = SHARE_AFFINITY_TOLERANCE_SESSIONS;
 exports.SHARE_SOURCE_SETTING_KEY = SHARE_SOURCE_SETTING_KEY;
@@ -118612,6 +118877,7 @@ exports.ServerUpdateActionResultSchema = ServerUpdateActionResultSchema;
 exports.ServerUpdateCheckResultSchema = ServerUpdateCheckResultSchema;
 exports.ServerUpdateOutcomeSchema = ServerUpdateOutcomeSchema;
 exports.ServerUpdateStateSchema = ServerUpdateStateSchema;
+exports.SessionHealthTracker = SessionHealthTracker;
 exports.SessionPlacementPolicySchema = SessionPlacementPolicySchema;
 exports.SessionTriggerSchema = SessionTriggerSchema;
 exports.SetCameraSensorsInputSchema = SetCameraSensorsInputSchema;
@@ -118995,6 +119261,7 @@ exports.buildNcTaxonomy = buildNcTaxonomy;
 exports.buildPlusCatalogClassMap = buildPlusCatalogClassMap;
 exports.buildRoleScopes = buildRoleScopes;
 exports.buildSecretRef = require_sleep.buildSecretRef;
+exports.buildSessionLostAlert = buildSessionLostAlert;
 exports.buildStreamParamsConfigSchema = buildStreamParamsConfigSchema;
 exports.buildSubjectPath = buildSubjectPath;
 exports.buildVideoArgs = require_composition.buildVideoArgs;
@@ -119795,6 +120062,7 @@ exports.sensorTransitionNeverFires = sensorTransitionNeverFires;
 exports.sensorTransitionOffered = sensorTransitionOffered;
 exports.servedTemplateVars = servedTemplateVars;
 exports.serverManagementCapability = serverManagementCapability;
+exports.sessionLostAlertId = sessionLostAlertId;
 exports.sessionsOfDeviceCell = sessionsOfDeviceCell;
 exports.setByPath = setByPath;
 exports.setFormulaExpr = setFormulaExpr;