@camstack/addon-osd-manager 0.1.126 → 0.1.128

package/dist/index.js

@@ -5363,7 +5363,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).
@@ -6934,6 +6934,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
+	};
+}
 /** Shorthand to define an event schema */
 function event(data) {
 	return { data };
@@ -29217,6 +29229,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",
@@ -29318,22 +29383,40 @@ var videoclipsCapability = {
 			limit: number().int().positive().optional(),
 			/**
 			* WHICH provider to ask — the `addonId` a {@link ClipSourceSchema} row
-			* carries, never a source id and never a list.
+			* 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`.
 			*
-			* 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).
+			* 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"
@@ -29370,6 +29453,68 @@ var videoclipsCapability = {
 		}), ClipPlaybackSchema, {
 			kind: "query",
 			auth: "protected"
+		}),
+		/**
+		* This clip's BYTES, base64, bounded — the by-handle read a clip EXPORT
+		* pulls once (D558).
+		*
+		* `getClipPlayback` is the right answer for a player: it hands back a URL
+		* on a plane the hub serves `access:'authenticated'`, which a browser and a
+		* viewer session satisfy. It is the wrong answer for another ADDON. There
+		* is no addon→addon byte transport in this framework — `AddonDataPlane`
+		* only lets an addon SERVE, on `127.0.0.1` behind a per-listener secret
+		* only the hub may present — so a recorder that wants a camera's clip
+		* cannot fetch that URL. This method is the one seam that exists for it,
+		* and it is deliberately the same shape (and the same bound) as
+		* `recordingExport.readExportBytes`, which exists for the mirror-image
+		* reason.
+		*
+		* Routing needs no `provider` pin: the id is source-prefixed and
+		* self-contained, so `device-collection-dispatch.ts` rule 3 hands the call
+		* to the source that claims it — and an id nobody claims is REFUSED rather
+		* than answered by another source.
+		*
+		* The producer reuses the fetch path it already has, completion rules
+		* included: a clip is taken by cmd 5 and finished on a short idle window
+		* whose result is PROVED against the catalog row's own span, retried once
+		* when it comes up materially short, and served-and-named when it is still
+		* short (D568). A second fetch with different completion rules is exactly
+		* the second authority D558 refuses to create.
+		*
+		* Every refusal THROWS with its reason and none of them is silent — the
+		* sleep gate (decided before `getApi()`, liftable only by
+		* {@link ClipWakeSchema}), a catalog row nobody claims, a clip with no
+		* bytes behind it, a mux that failed, and the size bound. The caller turns
+		* that reason into an operator-facing one; a truncated file is never an
+		* answer.
+		*/
+		readClipBytes: 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"
 		})
 	}
 };
@@ -38306,13 +38451,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. */
@@ -38329,6 +38562,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(),
@@ -38347,24 +38592,77 @@ 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 [];
+}
 var recordingExportCapability = {
 	name: "recording-export",
 	scope: "system",
 	mode: "singleton",
 	methods: {
-		/** Queue a render of `[fromMs,toMs)` for `deviceId`/`profiles` (legacy
-		*  singular `profile` still accepted). Fails fast when no footage covers
-		*  the range. One job per profile; returns the first queued record. */
+		/**
+		* Queue an export of {@link ExportSubjectSchema}.
+		*
+		* `kind:'footage'` — a render of `[fromMs,toMs)` for `deviceId`/`profiles`
+		* (legacy flat input, singular `profile` included, still accepted and
+		* rewritten). Fails fast when no footage covers the range. One job per
+		* profile; **returns the first queued record and the others are reachable
+		* only through `listExports`** — a defect named in D558 § 6.3 and the
+		* reason a clip subject carries exactly ONE profile.
+		*
+		* `kind:'clip'` — a finished file the camera holds, validated against the
+		* device's clip CATALOG (`videoclips.listClips`, at the subject's
+		* `provider`) instead of the recording index, and fetched once by handle
+		* under a bound. Its `fromMs`/`toMs` come from the catalog row and from
+		* nowhere else; a caller supplying a range is refused.
+		*
+		* A clip export reuses the six {@link ExportStateSchema} members and adds
+		* none: the viewer maps an unknown state string to `failed`, so a seventh
+		* member renders every live export — of both kinds — as FAILED on every
+		* installed app (D558 § 6.1, pinned by `export-state-members.spec.ts`).
+		* `subject.kind` is what tells a surface what `rendering` means.
+		*/
 		createExport: 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"]
@@ -47475,6 +47773,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.readClipBytes": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"viewerUi.getStaticDir": {
 		capName: "viewer-ui",
 		capScope: "system",
@@ -49493,6 +49797,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.readClipBytes": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"waterHeater.setAway": [{
 		name: "deviceId",
 		form: "single",