@camstack/addon-agent-ui 1.2.134 → 1.2.136

package/dist/addon.js

@@ -5361,7 +5361,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-CaB_hL5g.mjs
+//#region ../types/dist/sleep-BVhJDJka.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -6932,6 +6932,18 @@ function systemMethod(input, output, options) {
 		systemOnly: true
 	};
 }
+/**
+* A method a SOURCE of a collection cap may legitimately not serve — OPTIONAL
+* on `InferProvider`. The `providerOptional: true` literal is what
+* `InferProvider` keys on; see {@link CapabilityMethodSchema.providerOptional}
+* for when this is the honest answer and when it is a soft stub.
+*/
+function optionalMethod(input, output, options) {
+	return {
+		...method(input, output, options),
+		providerOptional: true
+	};
+}
 var StaticDirOutputSchema$1 = object({ staticDir: string() });
 var VersionOutputSchema$1 = object({ version: string() });
 var adminUiCapability = {
@@ -24194,6 +24206,59 @@ var ClipPlaybackSchema = object({
 * which days it asked for and got nothing — "no clips" would be a lie about a
 * card that is full of them.
 */
+/**
+* The operator's authorisation to WAKE a sleeping camera for one clip read.
+*
+* ONE value, absent by default, and it is a `force`-shaped operator signal in
+* exactly the sense `snapshot-wake-gate.ts` uses the word: *"`snapshot.getSnapshot`'s
+* `force` flag, and nothing else… a background caller must never set it…
+* Stale but honest beats woken"*. A scheduler, a retry, a reconcile and a
+* prefetch never set it; a surface sets it only behind the same confirm the
+* "Wake and refresh" gesture uses, and it is refused below 15 % battery
+* exactly as that gesture is.
+*
+* The gate is decided BEFORE `getApi()`, because on UDP the login IS the wake
+* (D549) — a read that opened a session and then checked would have woken the
+* camera to find out it was not allowed to.
+*
+* **One authorised yes is one wake.** `next-natural` — take the clip the next
+* time the camera is awake for its own reasons — is deliberately not a member:
+* it was proposed, it is free on the battery, and the operator declined it on
+* 2026-09-20 (*"Quando un export viene richiesto si sveglia la camera."*,
+* D558 "Considered and not taken").
+*/
+var ClipWakeSchema = _enum(["authorised"]);
+/**
+* A clip's finished bytes, inline — the twin of `recordingExport.readExportBytes`.
+*
+* `bytes` is the DECODED length, so nobody infers it from the base64 length,
+* and `served` says which twin the caller actually got.
+*/
+var ClipBytesSchema = object({
+	base64: string(),
+	contentType: string(),
+	/** Suggested filename, extension included. */
+	name: string(),
+	bytes: number().int().nonnegative(),
+	/**
+	* Which twin was actually served — the same contract
+	* {@link ClipPlaybackSchema.served} carries, and REQUIRED here because the
+	* export record persists it: a row read a week later must say the same thing
+	* the panel said at the moment of the tap. A missing main twin is never
+	* served silently as if it were the asked-for quality (D549 15).
+	*/
+	served: CamProfileSchema,
+	/**
+	* The DECODED duration of the delivered file, when the fetch measured one.
+	*
+	* A clip fetch verifies its own completion against the catalog row and
+	* retries a materially short pass (D568); this is that measurement, carried
+	* so a consumer can say the same thing rather than re-deriving it. Absent
+	* when the producer did not measure — never zero, which would say the file
+	* is empty.
+	*/
+	durationMs: number().positive().optional()
+});
 var ClipSourceAvailabilitySchema = object({
 	state: _enum([
 		"ok",
@@ -24250,22 +24315,40 @@ DeviceType.Camera, method(object({
 	limit: number().int().positive().optional(),
 	/**
 	* WHICH provider to ask — the `addonId` a {@link ClipSourceSchema} row
-	* carries, never a source id and never a list.
-	*
-	* Absent means the device's BOUND provider, which is CamStack on every
-	* camera today because that is what `deviceManager.getBindings`
-	* answers with. A provider the device is not bound to is refused by
-	* name rather than answered by another one (D552's
-	* `rejectUnresolvedAddonPin` rule).
+	* carries, never a source id and never a list. **Required** (D554 amended).
+	*
+	* A provider the device is not bound to is refused by name rather than
+	* answered by another one (D552's `rejectUnresolvedAddonPin` rule).
+	*
+	* It was optional, documented as "absent means the device's BOUND
+	* provider, which is CamStack on every camera". No code implemented
+	* that. Measured on the live hub 2026-09-20 — device 592, bound to
+	* `recorder` AND `provider-reolink` — a bare call with `limit: 3`
+	* answered SIX rows, three from each source, merged newest-first:
+	* `device-collection-dispatch.ts` simply left the fan-out un-narrowed,
+	* so absence bought the union this method exists not to be, and
+	* `limit` meant `limit × sources`.
+	*
+	* There is nothing to restore the default to. `getBindings` answers a
+	* collection cap with a DERIVED, PLURAL set (D554 amended, step 0);
+	* `setWrapperActive` — the singleton authority that could name one —
+	* throws for a collection cap by design. Naming CamStack here instead
+	* would privilege one addon by id inside a surface whose premise is
+	* that sources are peers, and would be wrong on the first camera with
+	* no recorder binding. So absence is REFUSED, in the schema, where the
+	* generated types make it unomittable rather than merely discouraged.
+	*
+	* The default belongs to the SURFACE, which has the `listSources` rows
+	* and can say which one it picked (D569 § 1–3; the viewer already
+	* always sends this).
 	*
 	* It replaced `sources?: string[]`, a VIEW filter over source ids that
 	* assumed the answer was a fan-out over everything a camera has. The
-	* operator settled otherwise on 2026-09-20 — *"il get videoclips
-	* prendere un provider opzionale, di default va su camstack"*,
-	* *"l'utilizzatore è uno solo"* — so the list is asked of one provider
-	* at a time and there is nothing to filter out of it.
+	* operator settled otherwise on 2026-09-20 — *"l'utilizzatore è uno
+	* solo"* — so the list is asked of one provider at a time and there is
+	* nothing to filter out of it.
 	*/
-	provider: string().optional()
+	provider: string().min(1)
 }), array(ClipSchema).readonly(), {
 	kind: "query",
 	auth: "protected"
@@ -24291,6 +24374,33 @@ DeviceType.Camera, method(object({
 }), ClipPlaybackSchema, {
 	kind: "query",
 	auth: "protected"
+}), optionalMethod(object({
+	deviceId: number(),
+	clipId: string().min(1),
+	/**
+	* Which twin to fetch, on the mapping D549 15 already fixed:
+	* `low | mid` → the sub file, `high` → the main twin. `auto` is not
+	* accepted here for the same reason it is not accepted by
+	* `getClipPlayback` — a stored file has no broker session, so the
+	* adaptive tier cannot be resolved for it.
+	*/
+	profile: CamProfileSchema.optional(),
+	/**
+	* The CALLER's byte bound, so an over-size clip is refused before it is
+	* read and encoded rather than after. Capped by
+	* {@link VIDEOCLIPS_MAX_READ_BYTES} whatever is passed; absent means
+	* that ceiling.
+	*/
+	maxBytes: number().int().positive().optional(),
+	/**
+	* The operator's authorisation to wake a sleeping camera for this
+	* read. Absent — the default — means a sleeping standalone battery
+	* camera is REFUSED by name, before any session is opened.
+	*/
+	wake: ClipWakeSchema.optional()
+}), ClipBytesSchema, {
+	kind: "query",
+	auth: "protected"
 });
 /**
 * Optional client-side hints sent at session creation to help the provider
@@ -30223,13 +30333,101 @@ var ExportStateSchema = _enum([
 	"expired",
 	"deleted"
 ]);
-/** One export job / history row. */
+/**
+* WHAT an export is — the authority, as opposed to the four top-level fields
+* the Library sorts and labels on (D558 § 2.2).
+*
+* Read it through {@link exportSubjectOf}, never off the record directly: the
+* field is optional for the history rows written before it existed, and that
+* absence has exactly one interpreter.
+*/
+var ExportSubjectSchema = discriminatedUnion("kind", [object({
+	kind: literal("footage"),
+	deviceId: number(),
+	profiles: array(string()).min(1),
+	fromMs: number(),
+	toMs: number()
+}), object({
+	kind: literal("clip"),
+	deviceId: number(),
+	provider: string().min(1),
+	source: string().min(1),
+	sourceLabel: string().min(1),
+	clipId: string().min(1),
+	/**
+	* WHERE IN THE CATALOG to confirm this clip — the day window the surface was
+	* already listing when the operator picked the segment.
+	*
+	* It is **not** a time range control and it never becomes one: the record's
+	* `fromMs`/`toMs` come from the catalog ROW and from nothing a caller
+	* supplied (D558 § 5.4.3), and a window that does not contain the clip is a
+	* `catalog-miss`, not a silently wider search. It exists because
+	* `videoclips.listClips` takes `since`/`until` and has no by-handle twin:
+	* the catalog check D558 asks for is literally that call, and a call needs a
+	* window. The surface has one — `ClipsBrowser`'s `dayWindow`, one local
+	* wall-clock day, which is also the only width measured to be cheap (one
+	* day on 592 lists 171 clips in 712 ms, a busy day 546 in 2.0 s; twenty days
+	* of one child's events took 3.6–5.4 s).
+	*/
+	catalogWindow: object({
+		sinceMs: number(),
+		untilMs: number()
+	}),
+	profile: _enum([
+		"high",
+		"mid",
+		"low"
+	]),
+	/**
+	* The operator's authorisation to wake a sleeping camera for this export.
+	* ONE definition, in the cap that owns the clip read ({@link ClipWakeSchema}),
+	* because the gate that honours it is the clip provider's sleep gate — a
+	* second enum here would be a second contract. Absent by default; never
+	* settable by a scheduler or a retry.
+	*
+	* **One authorised yes is ONE wake.** A failed clip export is retried only by
+	* an operator act that asks again; a queued job that outlived its wake fails
+	* with a reason rather than waking on its turn; and this subject carries
+	* exactly one profile precisely so one tap is never two fetches (D558 § 5.2).
+	*/
+	wake: ClipWakeSchema.optional()
+})]);
+/**
+* One export job / history row.
+*
+* **`subject` is the AUTHORITY on what was exported. `deviceId`, `profile`,
+* `fromMs` and `toMs` are its PROJECTION** — kept top-level because the whole
+* Library sorts and labels on them (`library-items.ts` orders an export by
+* `fromMs`; `export-format.ts` draws `rangeLabel` from the pair), and a row
+* that did not fill them would sort under the epoch and render a blank range.
+* Write to the subject and read from the projection and the two will disagree;
+* the projection is derived at creation and never edited afterwards.
+*
+* And they mean DIFFERENT FACTS for the two kinds, which is the part a reader
+* who knows only the recording export will get wrong:
+*
+* | field | `kind:'footage'` | `kind:'clip'` |
+* | --- | --- | --- |
+* | `fromMs`/`toMs` | the stretch the operator ASKED for | the camera's own boundaries, always `clip.timeRange`, never anything a caller supplied |
+* | `profile` | the stream rendered | the twin actually SERVED (`subject.profile` is the one asked for) |
+*
+* Same type, different fact — the shape this repo keeps getting wrong (D385's
+* two authorities, D224's second copy).
+*/
 var ExportRecordSchema = object({
 	id: string(),
 	deviceId: number(),
 	profile: string(),
 	fromMs: number(),
 	toMs: number(),
+	/**
+	* What this export IS. Optional ONLY for the rows written before D558: the
+	* store parses every row through this schema on every read, so a required
+	* field would make the export AUDIT — which is the whole reason rows survive
+	* file deletion — unreadable in one release. Absence means `footage`, and
+	* {@link exportSubjectOf} is the one place that says so.
+	*/
+	subject: ExportSubjectSchema.optional(),
 	options: ExportOptionsSchema,
 	state: ExportStateSchema,
 	/** 0–100 while rendering; null otherwise. */
@@ -30246,6 +30444,18 @@ var ExportRecordSchema = object({
 	/** Failure reason when state is 'failed'; null otherwise. */
 	error: string().nullable()
 });
+_enum([
+	"catalog-miss",
+	"catalog-unreachable",
+	"no-file-for-window",
+	"clip-in-progress",
+	"unsupported-option",
+	"sleeping",
+	"camera-refused",
+	"fetch-failed",
+	"too-large-to-transfer",
+	"wake-expired"
+]);
 /** Candidate download URLs (LAN first, then operator extra hosts). */
 var ExportDownloadSchema = object({
 	url: string(),
@@ -30264,16 +30474,50 @@ var ExportBytesSchema = object({
 	name: string(),
 	bytes: number().int().nonnegative()
 });
+/** Canonical `profiles[]`, falling back to the legacy singular `profile`. */
+function resolveExportProfiles(input) {
+	if (input.profiles !== void 0 && input.profiles.length > 0) return [...input.profiles];
+	if (typeof input.profile === "string" && input.profile.length > 0) return [input.profile];
+	return [];
+}
 method(object({
 	deviceId: number(),
 	/** @deprecated Prefer `profiles`. Kept so timelapse/notifiers keep working. */
 	profile: string().optional(),
 	profiles: array(string()).min(1).optional(),
-	fromMs: number(),
-	toMs: number(),
+	/** Footage only — a clip's boundaries are the camera's. */
+	fromMs: number().optional(),
+	toMs: number().optional(),
+	/** What to export. Absent means the legacy flat footage request. */
+	subject: ExportSubjectSchema.optional(),
 	options: ExportOptionsSchema
 }).superRefine((v, ctx) => {
-	if ((v.profiles !== void 0 && v.profiles.length > 0 ? v.profiles : v.profile !== void 0 ? [v.profile] : []).length < 1) ctx.addIssue({
+	if (v.subject?.kind === "clip") {
+		if (v.subject.deviceId !== v.deviceId) ctx.addIssue({
+			code: ZodIssueCode.custom,
+			message: `subject.deviceId (${v.subject.deviceId}) must equal deviceId (${v.deviceId}) — the top-level field is what per-device scope enforcement reads`,
+			path: ["subject", "deviceId"]
+		});
+		if (v.fromMs !== void 0 || v.toMs !== void 0) ctx.addIssue({
+			code: ZodIssueCode.custom,
+			message: "a clip export asks for no time range: the camera chose the boundaries and they are read from the catalog row",
+			path: ["fromMs"]
+		});
+		return;
+	}
+	if (v.subject?.kind === "footage" && v.subject.deviceId !== v.deviceId) ctx.addIssue({
+		code: ZodIssueCode.custom,
+		message: `subject.deviceId (${v.subject.deviceId}) must equal deviceId (${v.deviceId})`,
+		path: ["subject", "deviceId"]
+	});
+	const fromMs = v.subject?.kind === "footage" ? v.subject.fromMs : v.fromMs;
+	const toMs = v.subject?.kind === "footage" ? v.subject.toMs : v.toMs;
+	if (typeof fromMs !== "number" || typeof toMs !== "number") ctx.addIssue({
+		code: ZodIssueCode.custom,
+		message: "a footage export needs fromMs and toMs",
+		path: ["fromMs"]
+	});
+	if ((v.subject?.kind === "footage" ? [...v.subject.profiles] : resolveExportProfiles(v)).length < 1) ctx.addIssue({
 		code: ZodIssueCode.custom,
 		message: "pass profiles[] (min 1) or legacy profile",
 		path: ["profiles"]
@@ -38273,6 +38517,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.readClipBytes": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"viewerUi.getStaticDir": {
 		capName: "viewer-ui",
 		capScope: "system",
@@ -40291,6 +40541,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.readClipBytes": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"waterHeater.setAway": [{
 		name: "deviceId",
 		form: "single",
@@ -40970,7 +41225,7 @@ var AgentUIAddon = class extends BaseAddon {
 			capability: adminUiCapability,
 			provider: {
 				getStaticDir: async () => ({ staticDir: path.resolve(__dirname) }),
-				getVersion: async () => ({ version: "1.2.134" })
+				getVersion: async () => ({ version: "1.2.136" })
 			}
 		}];
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-agent-ui",
-  "version": "1.2.134",
+  "version": "1.2.136",
   "description": "Agent UI — lightweight status dashboard served by every agent node",
   "keywords": [
     "camstack",