@camstack/addon-export-alexa 1.2.133 → 1.2.134

package/dist/export-alexa.addon.js

@@ -49844,6 +49844,9 @@ function parseNonNegativeInt(s) {
 /**
 * Shared Alexa `Alexa/ErrorResponse` envelope builder.
 *
+* Certification checks the shape: `correlationToken` (set here) and
+* `endpoint` (set by `withErrorEndpoint` in the router) are both required.
+*
 * Lives in its own module so every handler (and the directive router)
 * can emit its own namespace-appropriate error without circular imports.
 */
@@ -49852,8 +49855,10 @@ object({ event: object({
 		namespace: literal("Alexa"),
 		name: literal("ErrorResponse"),
 		messageId: string(),
+		correlationToken: string().optional(),
 		payloadVersion: literal("3")
 	}),
+	endpoint: object({ endpointId: string() }).optional(),
 	payload: object({
 		type: string(),
 		message: string()
@@ -49865,6 +49870,7 @@ function errorEnvelope(header, type, message) {
 			namespace: "Alexa",
 			name: "ErrorResponse",
 			messageId: header.messageId,
+			...header.correlationToken !== void 0 ? { correlationToken: header.correlationToken } : {},
 			payloadVersion: "3"
 		},
 		payload: {
@@ -50225,18 +50231,43 @@ async function handleSessionDisconnected(header, endpointRaw, payloadRaw, deps,
 		},
 		meta: { endpointId: endpoint.endpointId }
 	});
+	return sessionEvent("SessionDisconnected", header, endpoint.endpointId, parsed.data.payload.sessionId);
+}
+/**
+* The response to `SessionConnected` / `SessionDisconnected` is the event of
+* the same name with the session id (alexa-rtcsessioncontroller) — not a
+* generic `Alexa.Response`.
+*/
+function sessionEvent(name, header, endpointId, sessionId) {
 	return { event: {
 		header: {
-			namespace: "Alexa",
-			name: "Response",
+			namespace: "Alexa.RTCSessionController",
+			name,
 			messageId: header.messageId,
 			correlationToken: header.correlationToken,
 			payloadVersion: "3"
 		},
-		endpoint: { endpointId: endpoint.endpointId },
-		payload: {}
+		endpoint: { endpointId },
+		payload: { sessionId }
 	} };
 }
+/**
+* `SessionConnected` — Alexa reports the media path is up. Nothing to do
+* hub-side (the session already exists from the offer); acknowledge it. Amazon
+* notes it is not always sent, so nothing may depend on it.
+*/
+function handleSessionConnected(header, endpointRaw, payloadRaw, deps) {
+	const parsed = SessionDisconnectedDirectiveSchema.safeParse({
+		endpoint: endpointRaw,
+		payload: payloadRaw ?? {}
+	});
+	if (!parsed.success) return errorEnvelope(header, "INVALID_DIRECTIVE", `payload validation failed: ${parsed.error.message}`);
+	deps.logger.info("alexa rtc-session: SessionConnected", {
+		tags: { sessionId: parsed.data.payload.sessionId },
+		meta: { endpointId: parsed.data.endpoint.endpointId }
+	});
+	return sessionEvent("SessionConnected", header, parsed.data.endpoint.endpointId, parsed.data.payload.sessionId);
+}
 //#endregion
 //#region src/broker-client.ts
 /**
@@ -50442,6 +50473,24 @@ var CAMERA_STREAM_CONTROLLER = {
 		audioCodecs: ["AAC"]
 	}]
 };
+/**
+* `Alexa.EndpointHealth` — REQUIRED on a sensor endpoint (alexa-endpointhealth;
+* alexa-motionsensor: "Must also implement `Alexa.EndpointHealth`"), and every
+* camera endpoint may carry `Alexa.MotionSensor`. Declared on every camera so
+* Alexa can tell an offline camera from a broken one: `connectivity` comes
+* from the `device-status` cap in ReportState and is pushed as a ChangeReport
+* on `DeviceOnline` / `DeviceOffline` by the Event Gateway.
+*/
+var ENDPOINT_HEALTH = {
+	type: "AlexaInterface",
+	interface: "Alexa.EndpointHealth",
+	version: "3",
+	properties: {
+		supported: [{ name: "connectivity" }],
+		proactivelyReported: true,
+		retrievable: true
+	}
+};
 var DOORBELL_EVENT_SOURCE = {
 	type: "AlexaInterface",
 	interface: "Alexa.DoorbellEventSource",
@@ -50643,7 +50692,8 @@ function buildParentCameraEndpoint(input) {
 	const capabilities = [
 		ALEXA_BASE_CAPABILITY,
 		CAMERA_STREAM_CONTROLLER,
-		rtcSessionController(input.hasIntercom)
+		rtcSessionController(input.hasIntercom),
+		ENDPOINT_HEALTH
 	];
 	if (input.isDoorbell) capabilities.push(DOORBELL_EVENT_SOURCE);
 	if (input.hasMotion) capabilities.push(MOTION_SENSOR);
@@ -51467,6 +51517,20 @@ async function collectCameraProperties(api, deviceId, properties, timeOfSample,
 		timeOfSample,
 		uncertaintyInMilliseconds: 0
 	});
+	const online = boolField(await api.deviceStatus.getStatus.query({ deviceId }).catch((err) => {
+		logger.warn("alexa report-state: deviceStatus.getStatus failed — connectivity omitted", {
+			tags: { deviceId },
+			meta: { error: err instanceof Error ? err.message : String(err) }
+		});
+		return null;
+	}), "online");
+	if (online !== null) properties.push({
+		namespace: "Alexa.EndpointHealth",
+		name: "connectivity",
+		value: { value: online ? "OK" : "UNREACHABLE" },
+		timeOfSample,
+		uncertaintyInMilliseconds: 0
+	});
 	const detected = boolField(await api.motion.getStatus.query({ deviceId }).catch((err) => {
 		logger.info("alexa report-state: motion.getStatus skipped", { meta: {
 			deviceId,
@@ -51849,7 +51913,37 @@ function assertDeviceScope(scopes) {
 function requireDeviceScope(scopes, access) {
 	if (!scopesAllowDeviceCap(scopes, access)) throw new Error(`directive token not authorized for device ${access}`);
 }
+/**
+* Give an `Alexa.ErrorResponse` the directive's endpoint when it lacks one.
+* Amazon requires `endpoint` on every ErrorResponse to an endpoint directive
+* (alexa-errorresponse); the handlers build their errors from the header
+* alone, so the router — which holds the endpoint for every path — adds it.
+*/
+function withErrorEndpoint(body, endpoint) {
+	const endpointId = typeof endpoint === "object" && endpoint !== null && typeof endpoint.endpointId === "string" ? endpoint.endpointId : null;
+	if (endpointId === null || typeof body !== "object" || body === null) return body;
+	const event = body.event;
+	if (typeof event !== "object" || event === null) return body;
+	const ev = event;
+	if (ev.header?.namespace !== "Alexa" || ev.header?.name !== "ErrorResponse") return body;
+	if (ev.endpoint !== void 0) return body;
+	return {
+		...body,
+		event: {
+			...ev,
+			endpoint: { endpointId }
+		}
+	};
+}
 async function dispatchDirective(rawBody, deps, callerIdentity) {
+	const result = await dispatchParsedDirective(rawBody, deps, callerIdentity);
+	const endpoint = rawBody?.directive?.endpoint;
+	return {
+		status: result.status,
+		body: withErrorEndpoint(result.body, endpoint)
+	};
+}
+async function dispatchParsedDirective(rawBody, deps, callerIdentity) {
 	const parsed = DirectiveRequestSchema.safeParse(rawBody);
 	if (!parsed.success) return {
 		status: 400,
@@ -51871,6 +51965,7 @@ async function dispatchDirective(rawBody, deps, callerIdentity) {
 		"Alexa.Discovery/Discover": "view",
 		"Alexa.CameraStreamController/InitializeCameraStreams": "view",
 		"Alexa.RTCSessionController/InitiateSessionWithOffer": "view",
+		"Alexa.RTCSessionController/SessionConnected": "view",
 		"Alexa.RTCSessionController/SessionDisconnected": "view",
 		"Alexa.PowerController/TurnOn": "create",
 		"Alexa.PowerController/TurnOff": "create",
@@ -51905,6 +52000,10 @@ async function dispatchDirective(rawBody, deps, callerIdentity) {
 			status: 200,
 			body: await handleInitiateSessionWithOffer(header, endpoint, payload, deps.rtcSession, callerIdentity)
 		};
+		if (key === "Alexa.RTCSessionController/SessionConnected") return {
+			status: 200,
+			body: handleSessionConnected(header, endpoint, payload, deps.rtcSession)
+		};
 		if (key === "Alexa.RTCSessionController/SessionDisconnected") return {
 			status: 200,
 			body: await handleSessionDisconnected(header, endpoint, payload, deps.rtcSession, callerIdentity)
@@ -52411,10 +52510,12 @@ var DEFAULT_MOTION_CLEAR_HOLD_MS = 5e3;
 var MotionClearHold = class {
 	entries = /* @__PURE__ */ new Map();
 	holdMs;
+	minDetectedMs;
 	setTimer;
 	clearTimer;
 	constructor(options) {
 		this.holdMs = options.holdMs;
+		this.minDetectedMs = options.minDetectedMs ?? 3e4;
 		this.setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
 		this.clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
 	}
@@ -52432,13 +52533,15 @@ var MotionClearHold = class {
 			if (entry.timer !== null) this.clearTimer(entry.timer);
 			this.entries.set(key, {
 				state: "detected",
-				timer: null
+				timer: null,
+				detectedAt: entry.detectedAt
 			});
 			return false;
 		}
 		this.entries.set(key, {
 			state: "detected",
-			timer: null
+			timer: null,
+			detectedAt: Date.now()
 		});
 		return true;
 	}
@@ -52459,16 +52562,21 @@ var MotionClearHold = class {
 	onCleared(key, release) {
 		const entry = this.entries.get(key);
 		if (entry !== void 0 && entry.state !== "detected") return;
+		const detectedAt = entry?.detectedAt ?? null;
+		const sinceDetected = detectedAt === null ? 0 : Date.now() - detectedAt;
+		const delay = Math.max(this.holdMs, this.minDetectedMs - sinceDetected);
 		const timer = this.setTimer(() => {
 			this.entries.set(key, {
 				state: "idle",
-				timer: null
+				timer: null,
+				detectedAt: null
 			});
 			release();
-		}, this.holdMs);
+		}, delay);
 		this.entries.set(key, {
 			state: "holding",
-			timer
+			timer,
+			detectedAt
 		});
 	}
 	/** What Alexa currently believes for this key — for logs and assertions. */
@@ -52522,6 +52630,9 @@ var REFRESH_PROACTIVE_WINDOW_MS = 300 * 1e3;
 var REFRESH_SCAN_INTERVAL_MS = 60 * 1e3;
 /** After a failed legacy-grant migration, wait this long before trying again. */
 var MIGRATION_RETRY_MS = 300 * 1e3;
+/** The interface a camera endpoint must declare for a connectivity
+*  ChangeReport to mean anything to the Alexa cloud. */
+var ENDPOINT_HEALTH_INTERFACE = "Alexa.EndpointHealth";
 /** The interface an endpoint must advertise for a `DoorbellPress` to survive
 *  the Alexa cloud. */
 var DOORBELL_INTERFACE = "Alexa.DoorbellEventSource";
@@ -52553,6 +52664,10 @@ var LwaEventGateway = class {
 	unsubscribe = null;
 	unsubscribeMotion = null;
 	unsubscribeBattery = null;
+	unsubscribeConnectivity = [];
+	/** Last connectivity reported per `userId|endpointId` — a camera that
+	*  re-announces the same state must not become a ChangeReport stream. */
+	lastConnectivity = /* @__PURE__ */ new Map();
 	refreshTimer = null;
 	lastSentAt = /* @__PURE__ */ new Map();
 	/**
@@ -52601,6 +52716,11 @@ var LwaEventGateway = class {
 				this.deps.logger.warn("alexa lwa-gateway: battery handler crashed", { meta: { error: err instanceof Error ? err.message : String(err) } });
 			});
 		});
+		this.unsubscribeConnectivity = [[EventCategory.DeviceOnline, "OK"], [EventCategory.DeviceOffline, "UNREACHABLE"]].map(([category, connectivity]) => this.deps.ctx.eventBus.subscribe({ category }, (event) => {
+			this.onConnectivityChanged(event.data, connectivity).catch((err) => {
+				this.deps.logger.warn("alexa lwa-gateway: connectivity handler crashed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			});
+		}));
 		this.refreshTimer = setInterval(() => {
 			this.refreshExpiringTokens().catch((err) => {
 				this.deps.logger.warn("alexa lwa-gateway: token refresh scan crashed", { meta: { error: err instanceof Error ? err.message : String(err) } });
@@ -52615,6 +52735,9 @@ var LwaEventGateway = class {
 		this.unsubscribeMotion = null;
 		if (this.unsubscribeBattery) this.unsubscribeBattery();
 		this.unsubscribeBattery = null;
+		for (const off of this.unsubscribeConnectivity) off();
+		this.unsubscribeConnectivity = [];
+		this.lastConnectivity.clear();
 		if (this.refreshTimer) clearInterval(this.refreshTimer);
 		this.refreshTimer = null;
 		this.lastSentAt.clear();
@@ -52819,6 +52942,33 @@ var LwaEventGateway = class {
 		}
 	}
 	/**
+	* A camera went offline or came back. Amazon requires the `connectivity`
+	* ChangeReport within 3 s of the change (alexa-endpointhealth). Deduped per
+	* account and endpoint, and skipped for an endpoint Alexa is known to hold
+	* WITHOUT `Alexa.EndpointHealth` — the cloud would drop it (D76).
+	*/
+	async onConnectivityChanged(data, connectivity) {
+		if (typeof data?.deviceId !== "number") return;
+		if (!this.deps.listExposed().some((e) => e.deviceId === data.deviceId)) return;
+		const signature = this.deps.getExportedSignature(data.deviceId);
+		if (signature !== null && !signature.includes(ENDPOINT_HEALTH_INTERFACE)) return;
+		const linked = this.deps.listLinkedAccounts();
+		if (linked.length === 0) return;
+		if (!this.hasProactiveCredentials()) return;
+		const endpointId = String(data.deviceId);
+		for (const account of linked) {
+			const key = `${account.userId}|${endpointId}`;
+			if (this.lastConnectivity.get(key) === connectivity) continue;
+			this.lastConnectivity.set(key, connectivity);
+			await this.postEventBody(account.userId, endpointId, (accessToken) => buildConnectivityChangeReportPayload({
+				endpointId,
+				connectivity,
+				timestamp: Date.now(),
+				accessToken
+			}), `connectivity ${connectivity}`);
+		}
+	}
+	/**
 	* Send a one-shot `DeleteReport` for arbitrary endpoint ids per linked
 	* account. Used to clean up stale entries Alexa still shows from prior
 	* syncs (different addon version, different account, or an aborted
@@ -53139,6 +53289,36 @@ function buildBatteryChangeReportPayload(opts) {
 		context: { properties: [] }
 	};
 }
+function buildConnectivityChangeReportPayload(opts) {
+	return {
+		event: {
+			header: {
+				namespace: "Alexa",
+				name: "ChangeReport",
+				messageId: (0, node_crypto.randomUUID)(),
+				payloadVersion: "3"
+			},
+			endpoint: {
+				scope: {
+					type: "BearerToken",
+					token: opts.accessToken
+				},
+				endpointId: opts.endpointId
+			},
+			payload: { change: {
+				cause: { type: "PERIODIC_POLL" },
+				properties: [{
+					namespace: "Alexa.EndpointHealth",
+					name: "connectivity",
+					value: { value: opts.connectivity },
+					timeOfSample: new Date(opts.timestamp).toISOString(),
+					uncertaintyInMilliseconds: 0
+				}]
+			} }
+		},
+		context: { properties: [] }
+	};
+}
 function buildSmartVisionObjectDetectionEvent(opts) {
 	const timeOfSample = new Date(opts.timestamp).toISOString();
 	return { event: {

package/dist/export-alexa.addon.mjs

@@ -1,4 +1,5 @@
 import * as crypto$1 from "node:crypto";
+import { randomUUID } from "node:crypto";
 //#region ../types/dist/event-category-BGmz_oxW.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
@@ -49817,6 +49818,9 @@ function parseNonNegativeInt(s) {
 /**
 * Shared Alexa `Alexa/ErrorResponse` envelope builder.
 *
+* Certification checks the shape: `correlationToken` (set here) and
+* `endpoint` (set by `withErrorEndpoint` in the router) are both required.
+*
 * Lives in its own module so every handler (and the directive router)
 * can emit its own namespace-appropriate error without circular imports.
 */
@@ -49825,8 +49829,10 @@ object({ event: object({
 		namespace: literal("Alexa"),
 		name: literal("ErrorResponse"),
 		messageId: string(),
+		correlationToken: string().optional(),
 		payloadVersion: literal("3")
 	}),
+	endpoint: object({ endpointId: string() }).optional(),
 	payload: object({
 		type: string(),
 		message: string()
@@ -49838,6 +49844,7 @@ function errorEnvelope(header, type, message) {
 			namespace: "Alexa",
 			name: "ErrorResponse",
 			messageId: header.messageId,
+			...header.correlationToken !== void 0 ? { correlationToken: header.correlationToken } : {},
 			payloadVersion: "3"
 		},
 		payload: {
@@ -50198,18 +50205,43 @@ async function handleSessionDisconnected(header, endpointRaw, payloadRaw, deps,
 		},
 		meta: { endpointId: endpoint.endpointId }
 	});
+	return sessionEvent("SessionDisconnected", header, endpoint.endpointId, parsed.data.payload.sessionId);
+}
+/**
+* The response to `SessionConnected` / `SessionDisconnected` is the event of
+* the same name with the session id (alexa-rtcsessioncontroller) — not a
+* generic `Alexa.Response`.
+*/
+function sessionEvent(name, header, endpointId, sessionId) {
 	return { event: {
 		header: {
-			namespace: "Alexa",
-			name: "Response",
+			namespace: "Alexa.RTCSessionController",
+			name,
 			messageId: header.messageId,
 			correlationToken: header.correlationToken,
 			payloadVersion: "3"
 		},
-		endpoint: { endpointId: endpoint.endpointId },
-		payload: {}
+		endpoint: { endpointId },
+		payload: { sessionId }
 	} };
 }
+/**
+* `SessionConnected` — Alexa reports the media path is up. Nothing to do
+* hub-side (the session already exists from the offer); acknowledge it. Amazon
+* notes it is not always sent, so nothing may depend on it.
+*/
+function handleSessionConnected(header, endpointRaw, payloadRaw, deps) {
+	const parsed = SessionDisconnectedDirectiveSchema.safeParse({
+		endpoint: endpointRaw,
+		payload: payloadRaw ?? {}
+	});
+	if (!parsed.success) return errorEnvelope(header, "INVALID_DIRECTIVE", `payload validation failed: ${parsed.error.message}`);
+	deps.logger.info("alexa rtc-session: SessionConnected", {
+		tags: { sessionId: parsed.data.payload.sessionId },
+		meta: { endpointId: parsed.data.endpoint.endpointId }
+	});
+	return sessionEvent("SessionConnected", header, parsed.data.endpoint.endpointId, parsed.data.payload.sessionId);
+}
 //#endregion
 //#region src/broker-client.ts
 /**
@@ -50415,6 +50447,24 @@ var CAMERA_STREAM_CONTROLLER = {
 		audioCodecs: ["AAC"]
 	}]
 };
+/**
+* `Alexa.EndpointHealth` — REQUIRED on a sensor endpoint (alexa-endpointhealth;
+* alexa-motionsensor: "Must also implement `Alexa.EndpointHealth`"), and every
+* camera endpoint may carry `Alexa.MotionSensor`. Declared on every camera so
+* Alexa can tell an offline camera from a broken one: `connectivity` comes
+* from the `device-status` cap in ReportState and is pushed as a ChangeReport
+* on `DeviceOnline` / `DeviceOffline` by the Event Gateway.
+*/
+var ENDPOINT_HEALTH = {
+	type: "AlexaInterface",
+	interface: "Alexa.EndpointHealth",
+	version: "3",
+	properties: {
+		supported: [{ name: "connectivity" }],
+		proactivelyReported: true,
+		retrievable: true
+	}
+};
 var DOORBELL_EVENT_SOURCE = {
 	type: "AlexaInterface",
 	interface: "Alexa.DoorbellEventSource",
@@ -50616,7 +50666,8 @@ function buildParentCameraEndpoint(input) {
 	const capabilities = [
 		ALEXA_BASE_CAPABILITY,
 		CAMERA_STREAM_CONTROLLER,
-		rtcSessionController(input.hasIntercom)
+		rtcSessionController(input.hasIntercom),
+		ENDPOINT_HEALTH
 	];
 	if (input.isDoorbell) capabilities.push(DOORBELL_EVENT_SOURCE);
 	if (input.hasMotion) capabilities.push(MOTION_SENSOR);
@@ -51440,6 +51491,20 @@ async function collectCameraProperties(api, deviceId, properties, timeOfSample,
 		timeOfSample,
 		uncertaintyInMilliseconds: 0
 	});
+	const online = boolField(await api.deviceStatus.getStatus.query({ deviceId }).catch((err) => {
+		logger.warn("alexa report-state: deviceStatus.getStatus failed — connectivity omitted", {
+			tags: { deviceId },
+			meta: { error: err instanceof Error ? err.message : String(err) }
+		});
+		return null;
+	}), "online");
+	if (online !== null) properties.push({
+		namespace: "Alexa.EndpointHealth",
+		name: "connectivity",
+		value: { value: online ? "OK" : "UNREACHABLE" },
+		timeOfSample,
+		uncertaintyInMilliseconds: 0
+	});
 	const detected = boolField(await api.motion.getStatus.query({ deviceId }).catch((err) => {
 		logger.info("alexa report-state: motion.getStatus skipped", { meta: {
 			deviceId,
@@ -51822,7 +51887,37 @@ function assertDeviceScope(scopes) {
 function requireDeviceScope(scopes, access) {
 	if (!scopesAllowDeviceCap(scopes, access)) throw new Error(`directive token not authorized for device ${access}`);
 }
+/**
+* Give an `Alexa.ErrorResponse` the directive's endpoint when it lacks one.
+* Amazon requires `endpoint` on every ErrorResponse to an endpoint directive
+* (alexa-errorresponse); the handlers build their errors from the header
+* alone, so the router — which holds the endpoint for every path — adds it.
+*/
+function withErrorEndpoint(body, endpoint) {
+	const endpointId = typeof endpoint === "object" && endpoint !== null && typeof endpoint.endpointId === "string" ? endpoint.endpointId : null;
+	if (endpointId === null || typeof body !== "object" || body === null) return body;
+	const event = body.event;
+	if (typeof event !== "object" || event === null) return body;
+	const ev = event;
+	if (ev.header?.namespace !== "Alexa" || ev.header?.name !== "ErrorResponse") return body;
+	if (ev.endpoint !== void 0) return body;
+	return {
+		...body,
+		event: {
+			...ev,
+			endpoint: { endpointId }
+		}
+	};
+}
 async function dispatchDirective(rawBody, deps, callerIdentity) {
+	const result = await dispatchParsedDirective(rawBody, deps, callerIdentity);
+	const endpoint = rawBody?.directive?.endpoint;
+	return {
+		status: result.status,
+		body: withErrorEndpoint(result.body, endpoint)
+	};
+}
+async function dispatchParsedDirective(rawBody, deps, callerIdentity) {
 	const parsed = DirectiveRequestSchema.safeParse(rawBody);
 	if (!parsed.success) return {
 		status: 400,
@@ -51844,6 +51939,7 @@ async function dispatchDirective(rawBody, deps, callerIdentity) {
 		"Alexa.Discovery/Discover": "view",
 		"Alexa.CameraStreamController/InitializeCameraStreams": "view",
 		"Alexa.RTCSessionController/InitiateSessionWithOffer": "view",
+		"Alexa.RTCSessionController/SessionConnected": "view",
 		"Alexa.RTCSessionController/SessionDisconnected": "view",
 		"Alexa.PowerController/TurnOn": "create",
 		"Alexa.PowerController/TurnOff": "create",
@@ -51878,6 +51974,10 @@ async function dispatchDirective(rawBody, deps, callerIdentity) {
 			status: 200,
 			body: await handleInitiateSessionWithOffer(header, endpoint, payload, deps.rtcSession, callerIdentity)
 		};
+		if (key === "Alexa.RTCSessionController/SessionConnected") return {
+			status: 200,
+			body: handleSessionConnected(header, endpoint, payload, deps.rtcSession)
+		};
 		if (key === "Alexa.RTCSessionController/SessionDisconnected") return {
 			status: 200,
 			body: await handleSessionDisconnected(header, endpoint, payload, deps.rtcSession, callerIdentity)
@@ -52384,10 +52484,12 @@ var DEFAULT_MOTION_CLEAR_HOLD_MS = 5e3;
 var MotionClearHold = class {
 	entries = /* @__PURE__ */ new Map();
 	holdMs;
+	minDetectedMs;
 	setTimer;
 	clearTimer;
 	constructor(options) {
 		this.holdMs = options.holdMs;
+		this.minDetectedMs = options.minDetectedMs ?? 3e4;
 		this.setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
 		this.clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
 	}
@@ -52405,13 +52507,15 @@ var MotionClearHold = class {
 			if (entry.timer !== null) this.clearTimer(entry.timer);
 			this.entries.set(key, {
 				state: "detected",
-				timer: null
+				timer: null,
+				detectedAt: entry.detectedAt
 			});
 			return false;
 		}
 		this.entries.set(key, {
 			state: "detected",
-			timer: null
+			timer: null,
+			detectedAt: Date.now()
 		});
 		return true;
 	}
@@ -52432,16 +52536,21 @@ var MotionClearHold = class {
 	onCleared(key, release) {
 		const entry = this.entries.get(key);
 		if (entry !== void 0 && entry.state !== "detected") return;
+		const detectedAt = entry?.detectedAt ?? null;
+		const sinceDetected = detectedAt === null ? 0 : Date.now() - detectedAt;
+		const delay = Math.max(this.holdMs, this.minDetectedMs - sinceDetected);
 		const timer = this.setTimer(() => {
 			this.entries.set(key, {
 				state: "idle",
-				timer: null
+				timer: null,
+				detectedAt: null
 			});
 			release();
-		}, this.holdMs);
+		}, delay);
 		this.entries.set(key, {
 			state: "holding",
-			timer
+			timer,
+			detectedAt
 		});
 	}
 	/** What Alexa currently believes for this key — for logs and assertions. */
@@ -52495,6 +52604,9 @@ var REFRESH_PROACTIVE_WINDOW_MS = 300 * 1e3;
 var REFRESH_SCAN_INTERVAL_MS = 60 * 1e3;
 /** After a failed legacy-grant migration, wait this long before trying again. */
 var MIGRATION_RETRY_MS = 300 * 1e3;
+/** The interface a camera endpoint must declare for a connectivity
+*  ChangeReport to mean anything to the Alexa cloud. */
+var ENDPOINT_HEALTH_INTERFACE = "Alexa.EndpointHealth";
 /** The interface an endpoint must advertise for a `DoorbellPress` to survive
 *  the Alexa cloud. */
 var DOORBELL_INTERFACE = "Alexa.DoorbellEventSource";
@@ -52526,6 +52638,10 @@ var LwaEventGateway = class {
 	unsubscribe = null;
 	unsubscribeMotion = null;
 	unsubscribeBattery = null;
+	unsubscribeConnectivity = [];
+	/** Last connectivity reported per `userId|endpointId` — a camera that
+	*  re-announces the same state must not become a ChangeReport stream. */
+	lastConnectivity = /* @__PURE__ */ new Map();
 	refreshTimer = null;
 	lastSentAt = /* @__PURE__ */ new Map();
 	/**
@@ -52574,6 +52690,11 @@ var LwaEventGateway = class {
 				this.deps.logger.warn("alexa lwa-gateway: battery handler crashed", { meta: { error: err instanceof Error ? err.message : String(err) } });
 			});
 		});
+		this.unsubscribeConnectivity = [[EventCategory.DeviceOnline, "OK"], [EventCategory.DeviceOffline, "UNREACHABLE"]].map(([category, connectivity]) => this.deps.ctx.eventBus.subscribe({ category }, (event) => {
+			this.onConnectivityChanged(event.data, connectivity).catch((err) => {
+				this.deps.logger.warn("alexa lwa-gateway: connectivity handler crashed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			});
+		}));
 		this.refreshTimer = setInterval(() => {
 			this.refreshExpiringTokens().catch((err) => {
 				this.deps.logger.warn("alexa lwa-gateway: token refresh scan crashed", { meta: { error: err instanceof Error ? err.message : String(err) } });
@@ -52588,6 +52709,9 @@ var LwaEventGateway = class {
 		this.unsubscribeMotion = null;
 		if (this.unsubscribeBattery) this.unsubscribeBattery();
 		this.unsubscribeBattery = null;
+		for (const off of this.unsubscribeConnectivity) off();
+		this.unsubscribeConnectivity = [];
+		this.lastConnectivity.clear();
 		if (this.refreshTimer) clearInterval(this.refreshTimer);
 		this.refreshTimer = null;
 		this.lastSentAt.clear();
@@ -52792,6 +52916,33 @@ var LwaEventGateway = class {
 		}
 	}
 	/**
+	* A camera went offline or came back. Amazon requires the `connectivity`
+	* ChangeReport within 3 s of the change (alexa-endpointhealth). Deduped per
+	* account and endpoint, and skipped for an endpoint Alexa is known to hold
+	* WITHOUT `Alexa.EndpointHealth` — the cloud would drop it (D76).
+	*/
+	async onConnectivityChanged(data, connectivity) {
+		if (typeof data?.deviceId !== "number") return;
+		if (!this.deps.listExposed().some((e) => e.deviceId === data.deviceId)) return;
+		const signature = this.deps.getExportedSignature(data.deviceId);
+		if (signature !== null && !signature.includes(ENDPOINT_HEALTH_INTERFACE)) return;
+		const linked = this.deps.listLinkedAccounts();
+		if (linked.length === 0) return;
+		if (!this.hasProactiveCredentials()) return;
+		const endpointId = String(data.deviceId);
+		for (const account of linked) {
+			const key = `${account.userId}|${endpointId}`;
+			if (this.lastConnectivity.get(key) === connectivity) continue;
+			this.lastConnectivity.set(key, connectivity);
+			await this.postEventBody(account.userId, endpointId, (accessToken) => buildConnectivityChangeReportPayload({
+				endpointId,
+				connectivity,
+				timestamp: Date.now(),
+				accessToken
+			}), `connectivity ${connectivity}`);
+		}
+	}
+	/**
 	* Send a one-shot `DeleteReport` for arbitrary endpoint ids per linked
 	* account. Used to clean up stale entries Alexa still shows from prior
 	* syncs (different addon version, different account, or an aborted
@@ -53112,6 +53263,36 @@ function buildBatteryChangeReportPayload(opts) {
 		context: { properties: [] }
 	};
 }
+function buildConnectivityChangeReportPayload(opts) {
+	return {
+		event: {
+			header: {
+				namespace: "Alexa",
+				name: "ChangeReport",
+				messageId: randomUUID(),
+				payloadVersion: "3"
+			},
+			endpoint: {
+				scope: {
+					type: "BearerToken",
+					token: opts.accessToken
+				},
+				endpointId: opts.endpointId
+			},
+			payload: { change: {
+				cause: { type: "PERIODIC_POLL" },
+				properties: [{
+					namespace: "Alexa.EndpointHealth",
+					name: "connectivity",
+					value: { value: opts.connectivity },
+					timeOfSample: new Date(opts.timestamp).toISOString(),
+					uncertaintyInMilliseconds: 0
+				}]
+			} }
+		},
+		context: { properties: [] }
+	};
+}
 function buildSmartVisionObjectDetectionEvent(opts) {
 	const timeOfSample = new Date(opts.timestamp).toISOString();
 	return { event: {

package/lambda-template/README.md

@@ -22,6 +22,14 @@ The same code runs the built-in CamStack skill and any operator's own
 | `POST <FUNCTION_URL>/broker/rotate` | `Bearer <credential>` → `{ brokerCredential }`; the old one stops working. |
 | `POST <FUNCTION_URL>/broker/revoke` | `Bearer <credential>` → deletes the link (and the refresh token). |
 
+Errors Alexa receives follow the Smart Home contract: every `Alexa.ErrorResponse`
+carries the directive's `correlationToken` and `endpoint`; a hub that cannot be
+reached (network error, or a tunnel's 502–504 / 52x page) is
+`BRIDGE_UNREACHABLE`; a hub reply that is not an Alexa event becomes
+`INTERNAL_ERROR`; AcceptGrant failures are `Alexa.Authorization` /
+`ACCEPT_GRANT_FAILED`. The `/authorize` page accepts only an `https://` hub URL
+and shows its error on the page.
+
 ### The two credential pairs
 
 | Pair | Secrets Manager id | Authenticates | Who else holds it |

package/lambda-template/index.js

@@ -55,6 +55,8 @@ const { createSecretSource } = require('./secrets.js')
 const { createDynamoTokenStore } = require('./token-store.js')
 const {
   decodeBody,
+  acceptGrantErrorEnvelope,
+  completeErrorResponse,
   decodeJwtPayload,
   describe,
   encodeFormUrlEncoded,
@@ -121,7 +123,12 @@ function createHandler(overrides) {
     } catch (err) {
       deps.log.error('camstack-alexa: unhandled error', describe(err))
       if (event && event.directive && event.directive.header) {
-        return errorEnvelope(event.directive.header, 'INTERNAL_ERROR', describe(err))
+        return errorEnvelope(
+          event.directive.header,
+          'INTERNAL_ERROR',
+          describe(err),
+          event.directive.endpoint,
+        )
       }
       return jsonResponse(500, { error: 'internal_error', message: describe(err) })
     }
@@ -164,25 +171,36 @@ function handleAuthorizePage(event) {
     button { margin-top: 1rem; width: 100%; padding: 0.7rem; font-size: 0.95rem; font-weight: 500; background: #2563eb; color: white; border: none; border-radius: 0.375rem; cursor: pointer; }
     button:hover { background: #1d4ed8; }
     .hint { font-size: 0.8rem; color: #6b7280; margin-top: 0.5rem; }
+    .err { font-size: 0.85rem; color: #b91c1c; margin: 0.75rem 0 0; }
   </style>
 </head>
 <body>
   <div class="card">
     <h1>Link CamStack to Alexa</h1>
     <p>Enter the public HTTPS URL of your CamStack hub. Alexa will then ask the hub to authorize this Echo.</p>
-    <form id="f">
+    <form id="f" novalidate>
       <label for="hubUrl">Hub URL</label>
       <input id="hubUrl" name="hubUrl" type="url" placeholder="https://camstack.example.com" required autofocus>
       <p class="hint">Must be reachable from the public internet (Cloudflare Tunnel, Tailscale Funnel, etc.).</p>
+      <p id="err" class="err" role="alert" hidden></p>
       <button type="submit">Continue</button>
     </form>
   </div>
   <script>
     document.getElementById('f').addEventListener('submit', function (ev) {
       ev.preventDefault()
-      var hubUrl = document.getElementById('hubUrl').value.trim().replace(/\\/$/, '')
-      if (!hubUrl) return
-      var qs = ${JSON.stringify(qs)}
+      var err = document.getElementById('err')
+      var hubUrl = document.getElementById('hubUrl').value.trim().replace(/\\/+$/, '')
+      var parsed = null
+      try { parsed = new URL(hubUrl) } catch (e) { parsed = null }
+      if (!parsed || parsed.protocol !== 'https:' || !parsed.hostname) {
+        err.textContent = 'Enter the full address of your hub, starting with https:// (for example https://camstack.example.com).'
+        err.hidden = false
+        return
+      }
+      err.hidden = true
+      hubUrl = parsed.origin + parsed.pathname.replace(/\\/+$/, '')
+      var qs = ${jsonForScript(qs)}
       var url = hubUrl + '/api/oauth2/authorize' + '?' + (qs ? qs + '&' : '') + 'integration=export-alexa'
       window.location.href = url
     })
@@ -196,6 +214,11 @@ function handleAuthorizePage(event) {
   }
 }
 
+/** JSON for an inline <script>: `<` escaped so the value cannot close the tag. */
+function jsonForScript(value) {
+  return JSON.stringify(value).replace(/</g, '\\u003c')
+}
+
 /** Constant-time string equality that does not leak length via timing. */
 function safeEqual(a, b) {
   const ab = Buffer.from(String(a), 'utf8')
@@ -310,22 +333,22 @@ async function handleAcceptGrant(event, deps) {
   const grantCode = payload.grant && payload.grant.code
   const granteeToken = payload.grantee && payload.grantee.token
   if (!grantCode || !granteeToken) {
-    return errorEnvelope(header, 'ACCEPT_GRANT_FAILED', 'payload missing grant.code or grantee.token')
+    return acceptGrantErrorEnvelope(header, 'payload missing grant.code or grantee.token')
   }
   const claims = decodeJwtPayload(granteeToken)
   if (!claims || typeof claims.hubUrl !== 'string' || claims.hubUrl.length === 0) {
-    return errorEnvelope(header, 'ACCEPT_GRANT_FAILED', 'grantee token has no hubUrl claim')
+    return acceptGrantErrorEnvelope(header, 'grantee token has no hubUrl claim')
   }
   const redirectUri = deps.env.LAMBDA_REDIRECT_URI
   if (!redirectUri) {
-    return errorEnvelope(header, 'ACCEPT_GRANT_FAILED', 'LAMBDA_REDIRECT_URI not set on the Lambda')
+    return acceptGrantErrorEnvelope(header, 'LAMBDA_REDIRECT_URI not set on the Lambda')
   }
 
   let tokens
   try {
     tokens = await exchangeGrantCode(deps, grantCode, redirectUri)
   } catch (err) {
-    return errorEnvelope(header, 'ACCEPT_GRANT_FAILED', describe(err))
+    return acceptGrantErrorEnvelope(header, describe(err))
   }
   const hubUrl = normaliseHubUrl(claims.hubUrl)
 
@@ -333,9 +356,11 @@ async function handleAcceptGrant(event, deps) {
     const outcome = await linkViaBroker(deps, { hubUrl, granteeToken, tokens })
     if (outcome.kind === 'linked') return acceptGrantResponse(header)
     if (outcome.kind !== 'hub-without-broker' || deps.env.LEGACY_HUB_FALLBACK === '0') {
-      return errorEnvelope(header, 'ACCEPT_GRANT_FAILED', outcome.message)
+      return acceptGrantErrorEnvelope(header, outcome.message)
     }
-    deps.log.warn('accept_grant: hub has no broker route; falling back to the legacy token hand-off')
+    deps.log.warn(
+      'accept_grant: hub has no broker route; falling back to the legacy token hand-off',
+    )
   }
   return deliverTokensToLegacyHub(deps, header, { hubUrl, granteeToken, tokens })
 }
@@ -392,43 +417,82 @@ async function deliverTokensToLegacyHub(deps, header, input) {
   })
   if (!callbackResp.ok) {
     const text = await callbackResp.text().catch(() => '')
-    return errorEnvelope(
+    return acceptGrantErrorEnvelope(
       header,
-      'ACCEPT_GRANT_FAILED',
       `hub callback ${callbackResp.status}: ${text.slice(0, 200)}`,
     )
   }
   return acceptGrantResponse(header)
 }
 
+/** HTTP statuses that mean the hub itself is down or unreachable behind its tunnel. */
+function isBridgeDownStatus(status) {
+  return status === 502 || status === 503 || status === 504 || (status >= 520 && status <= 530)
+}
+
 async function forwardDirective(event, deps) {
-  const header = event.directive.header
-  const bearer = extractBearer(event.directive)
+  const directive = event.directive
+  const header = directive.header
+  const endpoint = directive.endpoint
+  const bearer = extractBearer(directive)
   if (!bearer) {
-    return errorEnvelope(header, 'INVALID_AUTHORIZATION_CREDENTIAL', 'directive has no bearer token')
+    return errorEnvelope(
+      header,
+      'INVALID_AUTHORIZATION_CREDENTIAL',
+      'directive has no bearer token',
+      endpoint,
+    )
   }
   const claims = decodeJwtPayload(bearer)
   if (!claims || typeof claims.hubUrl !== 'string' || claims.hubUrl.length === 0) {
-    return errorEnvelope(header, 'INVALID_AUTHORIZATION_CREDENTIAL', 'bearer has no hubUrl claim')
+    return errorEnvelope(
+      header,
+      'INVALID_AUTHORIZATION_CREDENTIAL',
+      'bearer has no hubUrl claim',
+      endpoint,
+    )
   }
   const target = `${normaliseHubUrl(claims.hubUrl)}/addon/export-alexa/directive`
-  const resp = await deps.fetch(target, {
-    method: 'POST',
-    headers: {
-      ...hubHeaders(deps, bearer),
-      // Where this skill's broker lives. A hub linked before D753 uses it to
-      // migrate its refresh token here (zero-touch); the hub only believes it
-      // on a directive whose bearer it verified.
-      ...(brokerAvailable(deps) ? { [BROKER_HEADER]: deps.publicUrl } : {}),
-    },
-    body: JSON.stringify(event),
-  })
+  let resp
+  try {
+    resp = await deps.fetch(target, {
+      method: 'POST',
+      headers: {
+        ...hubHeaders(deps, bearer),
+        // Where this skill's broker lives. A hub linked before D753 uses it to
+        // migrate its refresh token here (zero-touch); the hub only believes it
+        // on a directive whose bearer it verified.
+        ...(brokerAvailable(deps) ? { [BROKER_HEADER]: deps.publicUrl } : {}),
+      },
+      body: JSON.stringify(event),
+    })
+  } catch (err) {
+    // The hub is the bridge every endpoint sits behind (alexa-errorresponse).
+    return errorEnvelope(
+      header,
+      'BRIDGE_UNREACHABLE',
+      `hub unreachable: ${describe(err)}`,
+      endpoint,
+    )
+  }
   const text = await resp.text()
+  let parsed
   try {
-    return JSON.parse(text)
+    parsed = JSON.parse(text)
   } catch {
-    return errorEnvelope(header, 'INTERNAL_ERROR', `hub returned non-JSON: ${text.slice(0, 256)}`)
+    const type = isBridgeDownStatus(resp.status) ? 'BRIDGE_UNREACHABLE' : 'INTERNAL_ERROR'
+    return errorEnvelope(header, type, `hub returned ${resp.status}, non-JSON`, endpoint)
+  }
+  if (!parsed || typeof parsed !== 'object' || !parsed.event || !parsed.event.header) {
+    // e.g. `{ error: 'invalid_ingress_token' }` — never hand Alexa a non-event.
+    return errorEnvelope(
+      header,
+      'INTERNAL_ERROR',
+      `hub returned ${resp.status} without an Alexa event`,
+      endpoint,
+    )
   }
+  return completeErrorResponse(parsed, directive)
 }
 
 function extractBearer(directive) {

package/lambda-template/util.js

@@ -94,20 +94,71 @@ function jsonResponse(statusCode, body) {
   }
 }
 
-function errorEnvelope(header, type, message) {
+/**
+ * `Alexa.ErrorResponse` for a directive. Amazon requires the directive's
+ * `correlationToken` and the target `endpoint` on it (alexa-errorresponse);
+ * both are copied when the directive carried them.
+ */
+function errorEnvelope(header, type, message, endpoint) {
+  const endpointId =
+    endpoint && typeof endpoint.endpointId === 'string' ? endpoint.endpointId : null
   return {
     event: {
       header: {
         namespace: 'Alexa',
         name: 'ErrorResponse',
         messageId: header.messageId,
+        ...(typeof header.correlationToken === 'string'
+          ? { correlationToken: header.correlationToken }
+          : {}),
         payloadVersion: '3',
       },
+      ...(endpointId !== null ? { endpoint: { endpointId } } : {}),
       payload: { type, message },
     },
   }
 }
 
+/** AcceptGrant's own error: `Alexa.Authorization/ErrorResponse` (alexa-authorization). */
+function acceptGrantErrorEnvelope(header, message) {
+  return {
+    event: {
+      header: {
+        namespace: 'Alexa.Authorization',
+        name: 'ErrorResponse',
+        messageId: header.messageId,
+        payloadVersion: '3',
+      },
+      payload: { type: 'ACCEPT_GRANT_FAILED', message },
+    },
+  }
+}
+
+/**
+ * Fill in what an `Alexa.ErrorResponse` from a hub may lack — a hub running an
+ * older addon omits `correlationToken` and `endpoint`. Any other body is
+ * returned as it is.
+ */
+function completeErrorResponse(body, directive) {
+  const ev = body && body.event
+  if (!ev || !ev.header || ev.header.name !== 'ErrorResponse' || ev.header.namespace !== 'Alexa') {
+    return body
+  }
+  const header = { ...ev.header }
+  if (
+    header.correlationToken === undefined &&
+    typeof directive.header.correlationToken === 'string'
+  ) {
+    header.correlationToken = directive.header.correlationToken
+  }
+  const endpointId =
+    directive.endpoint && typeof directive.endpoint.endpointId === 'string'
+      ? directive.endpoint.endpointId
+      : null
+  const endpoint = ev.endpoint || (endpointId !== null ? { endpointId } : undefined)
+  return { ...body, event: { ...ev, header, ...(endpoint ? { endpoint } : {}) } }
+}
+
 function describe(err) {
   if (err instanceof Error) return err.message
   return String(err)
@@ -124,5 +175,7 @@ module.exports = {
   resolveBrokerPublicUrl,
   jsonResponse,
   errorEnvelope,
+  acceptGrantErrorEnvelope,
+  completeErrorResponse,
   describe,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-export-alexa",
-  "version": "1.2.133",
+  "version": "1.2.134",
   "description": "Alexa Smart Home Skill export — hub-side OAuth provider + directive handler. The companion AWS Lambda forwards Alexa directives to this addon's /addon/export-alexa/directive endpoint.",
   "keywords": [
     "camstack",