@camstack/types 1.2.233 → 1.2.234

package/dist/index.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-D7DPSeiv.js");
+const require_sleep = require("./sleep-DImve4HM.js");
 const require_event_category = require("./event-category-BVfsrBYA.js");
 const require_canonical_hash = require("./canonical-hash-CSE4ioRi.js");
 const require_enums = require("./enums.js");
@@ -9762,6 +9762,29 @@ var cameraStreamsCapability = {
 };
 //#endregion
 //#region src/capabilities/cap-router-predicates.ts
+/**
+* True when a cap's generated router carries the COLLECTION `addonId`
+* selector — "which provider of this collection answers".
+*
+* `resolveCapMount` is the authority, not `mode`: since D554 a device-scoped
+* wrapper that is a collection (`videoclips`) keeps the PER-DEVICE mount, and
+* its sources are resolved from the device, never picked by an addonId the
+* caller supplies. Emitting the selector for it would advertise a routing key
+* the runtime builder does not read — the exact type/runtime disagreement
+* D552 removed from `generate-cap-mounts.ts`.
+*
+* The one exception is preserved deliberately, and it is the same one
+* `generate-cap-mounts.ts` documents: a cap declaring `mount: { kind: 'skip' }`
+* keeps its mode-derived shape. The builder never mounts it, so the emitted
+* value is never called — four inert caps (`log-channels`, `login-method`,
+* `load-contribution`, `failure-contribution`) that would otherwise change
+* shape inside a slice that is about something else.
+*/
+function emitsCollectionSelector(def) {
+	const kind = require_sleep.resolveCapMount(def).kind;
+	if (kind === "collection") return true;
+	return kind === "skip" && def.mode === "collection";
+}
 /** `z.void()` — input carries no data. */
 function isVoidInput(schema) {
 	const def = schema._def;
@@ -9871,6 +9894,33 @@ function objectInputDeclaresAddonId(schema) {
 	const shape = direct !== void 0 && direct !== null ? direct : resolveDefShape(schema._def?.shape);
 	return shape !== void 0 && shape !== null && typeof shape === "object" && Object.prototype.hasOwnProperty.call(shape, "addonId");
 }
+/**
+* True when an OBJECT input schema declares a top-level, REQUIRED, numeric
+* `deviceId` — i.e. the method names exactly one device on every call.
+*
+* This is the question the per-device dispatcher asks at runtime
+* (`requireDeviceScoped`: `typeof input.deviceId !== 'number'` → BAD_REQUEST),
+* asked once at build time instead. A `device-scoped` cap's method that cannot
+* answer it has no device to resolve for and therefore resolves through the
+* cap's SYSTEM provider (`cap-router-builder.ts`) — the same destination
+* `systemOnly` names explicitly. Without this, flipping the mount would 400
+* every batch (`deviceIds`), fleet-wide (`z.void()`) and job-keyed method on
+* the eight device-scoped wrapper caps.
+*
+* Structural, never a name heuristic over source text: the field must resolve
+* to `z.number()` and must NOT be wrapped in `optional` / `nullable` /
+* `default` — an absent value is exactly the input the dispatcher rejects.
+*/
+function objectInputDeclaresRequiredDeviceId(schema) {
+	if (schema === null || typeof schema !== "object" && typeof schema !== "function") return false;
+	const direct = schema.shape;
+	const shape = direct !== void 0 && direct !== null ? direct : resolveDefShape(schema._def?.shape);
+	if (shape === void 0 || shape === null || typeof shape !== "object") return false;
+	const field = shape["deviceId"];
+	if (field === void 0 || field === null) return false;
+	const def = field._def;
+	return field.constructor?.name === "ZodNumber" || def?.type === "number" || def?.typeName === "ZodNumber";
+}
 /** `_def.shape` may be a thunk (Zod defers object-shape evaluation) or a plain record. */
 function resolveDefShape(defShape) {
 	return typeof defShape === "function" ? defShape() : defShape;
@@ -12889,14 +12939,30 @@ var deviceManagerCapability = {
 		*/
 		getAllBindings: require_sleep.method(zod.z.object({}), zod.z.array(DeviceBindingsForDeviceSchema)),
 		/**
-		* Activate (or deactivate) a wrapper addon for a (device, cap) pair.
-		* Persists the binding via ctx.settings. active=false clears the wrapper
-		* (falls back to native if registered).
+		* Activate (or deactivate) a wrapper addon — or ONE of its sources — for a
+		* (device, cap) pair.
+		*
+		* Persists the binding via ctx.settings; `active: false` on a SINGLETON cap
+		* clears the wrapper (falling back to native if one is registered). On a
+		* COLLECTION cap it adds to the per-device DENY set instead, and the
+		* wrapper binding is left exactly as it was — a cap with several sources
+		* has no "which one" for `getBindings` to answer (D556).
+		*
+		* `sourceId` is what makes the switch match its label. One addon can serve
+		* several of a device's sources (`addon-provider-reolink` answers a hub
+		* child with `native:reolink:onboard` AND `native:reolink:hub`), so a
+		* toggle keyed by addon would turn off both while saying it turned off one
+		* — the D62 defect with the polarity reversed (D557). Naming the source
+		* denies exactly that source. OMITTING it keeps the cap-wide meaning
+		* D556 shipped: every source this addon serves for this device, which is
+		* also how a deny entry persisted before the re-key is still read.
 		*/
 		setWrapperActive: require_sleep.method(zod.z.object({
 			deviceId: zod.z.number(),
 			capName: zod.z.string(),
 			wrapperAddonId: zod.z.string(),
+			/** The `ClipSource.source` id to toggle. Absent = all of the addon's. */
+			sourceId: zod.z.string().optional(),
 			active: zod.z.boolean()
 		}), zod.z.void(), {
 			kind: "mutation",
@@ -27053,13 +27119,24 @@ var vectorStoreCapability = {
 /**
 * `videoclips` — the unified, navigable-clip surface for a camera.
 *
-* A device-scoped WRAPPER cap (like `pipeline-analytics`): exactly one active
-* provider per device, substitutable. The DEFAULT provider (registered by
+* A device-scoped wrapper COLLECTION (D549 decision 2, D554): every provider a
+* camera has is a SOURCE, and they are listed beside each other — never one
+* substituted for another. The DEFAULT provider (registered by
 * `addon-post-analysis`, `defaultActive: true`) composes the analytics event
 * log (markers + thumbnails) with the recorder's `getPlaybackManifest` — a clip
 * is a time-WINDOW over existing footage, never a separate file. A camera that
-* exposes NATIVE onboard clips (Reolink/Hikvision NVR) can later substitute the
-* wrapper provider for its device and serve its own clip catalog + URLs.
+* exposes NATIVE onboard clips (Reolink SD card, a hub's storage, HKSV) adds
+* its own catalog ALONGSIDE that one.
+*
+* The mount stays per-device (`resolveCapMount` → `device-scoped`): the fan-out
+* is over the DEVICE's sources, resolved from the registry's per-device
+* collection, never over every provider in the cluster. `listClips` is the
+* union of those sources, in newest-first order, with NO dedup and no
+* best-source pick — a clip held in two storages appears twice, once per
+* source, and every row's {@link ClipSchema.source} says which. That is the
+* operator's decision, stated so it is not "fixed" later.
+* {@link videoclipsCapability.methods.getClipPlayback} dispatches by the
+* source namespace inside the clip id, which is why ids are self-contained.
 *
 * A `Clip` is purely time-based (subtree-blind): playback resolves segments by
 * temporal overlap, so the API never decides `continuous` vs `events`.
@@ -27147,41 +27224,299 @@ var ClipSchema = zod.z.object({
 	holes: zod.z.array(zod.z.object({
 		startMs: zod.z.number(),
 		endMs: zod.z.number()
-	})).optional()
+	})).optional(),
+	/**
+	* A URL that MAY produce this clip's still, asked only for rows actually on
+	* screen. The opposite of {@link ClipSchema.thumbnail}: that one is VOUCHED
+	* (a JPEG is already on disk), this one is an offer. The route answers 200
+	* with the image, or 204 with `x-camstack-reason` when it could not mint one
+	* — a surface latches that refusal to the instant rather than retrying.
+	*
+	* Never both: a clip with a vouched `thumbnail` needs no mint.
+	*/
+	thumbnailMint: zod.z.string().optional(),
+	/**
+	* Why no still will be produced for this clip RIGHT NOW — set when the
+	* provider already knows, so the surface draws the glyph and the reason
+	* instead of firing a mint that cannot succeed.
+	*
+	* `sleeping` — a standalone battery camera; a read would be a wake (D549 4).
+	* `camera-refused` — the camera answered the CoverPreview with a refusal.
+	* `no-keyframe` — the window holds no decodable I-frame (an event that sits
+	*   inside no file is the measured case).
+	* `unsupported` — this source cannot mint stills at all.
+	*/
+	thumbnailUnavailable: zod.z.object({ reason: zod.z.enum([
+		"sleeping",
+		"camera-refused",
+		"no-keyframe",
+		"unsupported"
+	]) }).optional(),
+	/**
+	* When the catalog this row came from was last CONFIRMED against the device.
+	* Absent means "this row was read live". A persisted catalog served while a
+	* camera sleeps carries the age it really has — a cached list is never drawn
+	* as current (D549 13).
+	*/
+	catalogAsOf: zod.z.number().optional(),
+	/**
+	* The camera's OWN type strings for this clip, all of them, unmapped
+	* (`md`, `people`, `dog_cat`, `sched`, …). Kept beside {@link labels}
+	* because a firmware inventing a type must not vanish: the mapping into our
+	* filter vocabulary is lossy on purpose and this is the lossless copy
+	* (D549 20).
+	*/
+	nativeTypes: zod.z.array(zod.z.string()).optional(),
+	/**
+	* What the subject DID — `crossline`, `intrude`, `loitering`. A behaviour
+	* travels BESIDE a class, never instead of one, and the class filter ignores
+	* it: "a person crossed a line" is still a person (D549 20).
+	*/
+	behaviours: zod.z.array(zod.z.string()).optional(),
+	/**
+	* The same recording as two files — the sub twin (what the row and its
+	* thumbnail are) and its main twin, matched at listing time so a quality
+	* change never re-searches the camera (D549 15). `getClipPlayback`'s
+	* `profile` picks between them: `low | mid` → sub, `high` → main.
+	*/
+	streams: zod.z.object({
+		sub: zod.z.object({
+			id: zod.z.string(),
+			bytes: zod.z.number().optional()
+		}).optional(),
+		main: zod.z.object({
+			id: zod.z.string(),
+			bytes: zod.z.number().optional()
+		}).optional()
+	}).optional(),
+	/** The camera says it holds a sub-stream copy of this recording. */
+	supportSub: zod.z.boolean().optional(),
+	/**
+	* Whether this row has bytes behind it. ABSENT means yes — every clip that
+	* IS a file is playable, and only a source that lists EVENTS can produce a
+	* row with nothing to play (the measured case: 1 of 29 hub events on 3628
+	* fell inside no file). Such a row is shown, never dropped and never offered
+	* as playable-then-failing (D549 19).
+	*/
+	playable: zod.z.boolean().optional(),
+	/** Why {@link playable} is false, verbatim (`no-file-for-window`). */
+	unplayableReason: zod.z.string().optional()
 });
 var ClipPlaybackSchema = zod.z.object({
-	/** HLS master URL through the hub data-plane (Range + token in path). */
+	/**
+	* A media URL through the hub data-plane. {@link ClipPlaybackSchema.format}
+	* says what kind — an HLS master playlist for a recording-derived clip, a
+	* progressive MP4 for a native file the vendor addon muxed and serves with
+	* `Range`. The URL is NOT a credential: both planes are registered
+	* `access: 'authenticated'` and the hub's `/addon/<id>/<prefix>` proxy takes
+	* the session cookie, so nothing is appended to it (D549 22).
+	*/
 	playbackUrl: zod.z.string(),
+	/**
+	* How to play {@link playbackUrl}. Absent means `hls` — the shape every
+	* existing consumer already assumes. A player that branches on this is the
+	* one change a native clip needs; a player that ignores it will hand an MP4
+	* to hls.js and fail parsing it as a manifest.
+	*/
+	format: zod.z.enum(["hls", "mp4"]).optional(),
+	/**
+	* Which twin was actually served. A clip that holds only one stream answers
+	* with the one it has, and the surface SAYS so — a missing main twin is
+	* never served silently as if it were the asked-for quality (D549 15).
+	*/
+	served: require_sleep.CamProfileSchema.optional(),
 	/** Optional LAN/remote alternates for the same clip. */
 	playbackEndpoints: zod.z.array(zod.z.string()).optional(),
 	token: zod.z.string().optional()
 });
+/**
+* Why a source cannot answer right now — per SOURCE, never fleet-wide.
+*
+* `ok` is the only state whose clip list may be read as complete. The other
+* three exist because an empty list from a sleeping camera reads as "this
+* camera has no recordings", which is the defect this whole line of work is
+* about: a battery camera nobody woke (`sleeping`), a camera that could not be
+* reached at all (`unreachable`, also what a provider that THREW reports), a
+* camera whose SD card is not mounted (`no-storage`, measured on 640 —
+* `HddInfo mount 0`, honestly nothing to list rather than "no clips"), and a
+* camera whose OWN index disagrees with its OWN calendar (`index-empty`,
+* measured on 618: the calendar marks 3–20 September, days 6–20 list zero
+* files on both streams and both filters, with 177 GB free). That last one is
+* a defect ON THE CAMERA, and the only honest thing a provider can do is say
+* which days it asked for and got nothing — "no clips" would be a lie about a
+* card that is full of them.
+*/
+var ClipSourceAvailabilitySchema = zod.z.object({
+	state: zod.z.enum([
+		"ok",
+		"sleeping",
+		"unreachable",
+		"no-storage",
+		"index-empty"
+	]),
+	/** Free text, shown verbatim. Names the camera's own refusal when there is one. */
+	reason: zod.z.string().optional(),
+	/** When this source's catalog was last CONFIRMED. A cached list is never
+	*  drawn as current: the surface shows the age whenever it is older than the
+	*  refresh interval. */
+	catalogAsOf: zod.z.number().optional()
+});
+/**
+* One SOURCE of clips for a camera — a row of the picker, and the namespace
+* every clip id from it is prefixed with (`analytics`,
+* `native:reolink:onboard`, `hksv`, …).
+*
+* A provider lists the sources IT serves for that device, and answers for each
+* of them whether it can answer at all. A provider with nothing to offer on a
+* camera returns `[]` — it is not that camera's business.
+*/
+var ClipSourceSchema = zod.z.object({
+	/** The value this source stamps on {@link ClipSchema.source}, and the prefix
+	*  of every clip id it mints. `getClipPlayback` routes on it. */
+	source: zod.z.string(),
+	/** Operator-facing name of the source ("CamStack recordings", "SD card"). */
+	label: zod.z.string(),
+	/**
+	* The addon that SERVES this row.
+	*
+	* A surface cannot otherwise resolve a source to who answers it, and the
+	* alternative — a `native:reolink:* → provider-reolink` table inside the
+	* widget — is a second authority on provider identity living in the one
+	* package with no business knowing it, wrong the day a third source appears
+	* (D557). One addon may serve SEVERAL sources: `addon-provider-reolink`
+	* answers a hub child with both `native:reolink:onboard` and
+	* `native:reolink:hub`, which is why the per-device switch is keyed by
+	* SOURCE and not by this (D555).
+	*
+	* Optional for version skew only. The collection dispatcher stamps it from
+	* the registry, so a row that travelled through the fan-out carries the
+	* authoritative id whatever the provider filled in.
+	*/
+	addonId: zod.z.string().optional(),
+	/**
+	* Which API this source resolved to FOR THIS CAMERA, when it has a choice.
+	*
+	* A source may cover one store through more than one surface — the Reolink
+	* provider reads a hub child through the parent's event log and a standalone
+	* through its own file list, because that is what each camera answers. The
+	* CHOICE is the provider's, made from what the camera is, and is never a row
+	* the operator has to understand; but it is REPORTED, because a source that
+	* silently reads a different API on two cameras and then behaves differently
+	* is the thing nobody can debug later. Absent when the source has only one
+	* way to read its store.
+	*/
+	via: zod.z.string().optional(),
+	availability: ClipSourceAvailabilitySchema,
+	/**
+	* The operator switched this source OFF for this camera.
+	*
+	* Deliberately NOT a member of {@link ClipSourceAvailabilitySchema}'s
+	* vocabulary. That enum models what the source CAN do — a sleeping camera, an
+	* unmounted card, an index that disagrees with its own calendar — and a
+	* switched-off source could answer perfectly well; the operator decided it
+	* should not. Folding the choice in is how `disabled` and `broken` stop being
+	* distinguishable, which is the D62 rule this repo has already paid for twice:
+	* an off switch is REPORTED off (`CameraStatus.switchedOff`, the same word),
+	* and disabled must never look like broken. It is also what lets every
+	* exhaustive consumer of the availability enum keep compiling.
+	*
+	* A switched-off source contributes NO clips (`listClips` never calls it) and
+	* its row carries no `catalogAsOf`: nothing confirms a catalog it is not
+	* allowed to serve, and a frozen age that can only grow draws a stalling
+	* source rather than an off switch.
+	*
+	* The row survives BECAUSE it is the control the operator switches the source
+	* back on from — D554 decision 4's rule ("a source that cannot answer
+	* produces a ROW, not an absence") applied to the one case D556 carved out of
+	* it, and D557's own kept property ("a source is never hidden, only its
+	* rows"). Absent means on.
+	*
+	* A provider never sets this — like {@link ClipSourceSchema.addonId} it is
+	* stamped by the collection dispatcher, which holds the registry's projection
+	* of the persisted authority (D556) and is the only place that knows it.
+	*/
+	switchedOff: zod.z.boolean().optional()
+});
 var videoclipsCapability = {
 	name: "videoclips",
 	scope: "device",
-	mode: "singleton",
+	mode: "collection",
 	kind: "wrapper",
 	defaultActive: true,
 	/** A clip is a window over a camera's footage — the cap is meaningless on a
 	*  sensor, a button or an event emitter, and the `defaultActive` auto-bind
 	*  reads this to decide which devices it may claim. */
 	deviceTypes: [require_sleep.DeviceType.Camera],
+	/**
+	* The Clips section of a camera's device details is FRAMEWORK-DERIVED (D14):
+	* the aggregator turns this declaration into the `type:'widget'` section and
+	* `DeviceDetail.tsx` is never edited. `videoclips` is the first WRAPPER cap
+	* to declare one — every previous `host/` widget cap is `deviceNative` — so
+	* `device-config-widget-wrapped-binding.spec.ts` pins that a `kind:'wrapped'`
+	* binding entry derives the same section a native one does.
+	*
+	* `topTab` because the browser owns the whole pane (a day's clips, a source
+	* list and a player), exactly as `ptz` does; the widget itself is
+	* `host/clips-browser` in ui-library's `HOST_WIDGETS`.
+	*/
+	deviceConfig: { ui: {
+		kind: "widget",
+		widgetId: "host/clips-browser",
+		tab: "clips",
+		topTab: true,
+		label: "Clips",
+		order: 0
+	} },
 	methods: {
 		listClips: require_sleep.method(zod.z.object({
 			deviceId: zod.z.number(),
 			since: zod.z.number(),
 			until: zod.z.number(),
-			limit: zod.z.number().int().positive().optional()
+			limit: zod.z.number().int().positive().optional(),
+			/**
+			* View filter over {@link ClipSourceSchema.source} values — the
+			* picker's selection, forwarded so a provider need not list what
+			* nobody is looking at. ABSENT means every source this camera has,
+			* which is the honest default for a surface whose whole point is that
+			* nothing is hidden (D554 3). A provider with one source ignores it.
+			*/
+			sources: zod.z.array(zod.z.string()).optional()
 		}), zod.z.array(ClipSchema).readonly(), {
 			kind: "query",
-			auth: "admin"
+			auth: "protected"
+		}),
+		/**
+		* The sources this camera has, WITH the reason any of them cannot answer.
+		*
+		* Asked separately from `listClips` because an empty clip list is
+		* ambiguous and this is the only place the ambiguity is resolved: every
+		* bound provider contributes its own rows, and a provider that could not
+		* be reached at all still produces one row saying so. A surface that draws
+		* "no clips" without reading this is drawing a guess.
+		*/
+		listSources: require_sleep.method(zod.z.object({ deviceId: zod.z.number() }), zod.z.array(ClipSourceSchema).readonly(), {
+			kind: "query",
+			auth: "protected"
 		}),
 		getClipPlayback: require_sleep.method(zod.z.object({
 			deviceId: zod.z.number(),
-			clipId: zod.z.string()
+			clipId: zod.z.string(),
+			/**
+			* Which twin to serve, on the ONE quality scale the system already has
+			* (`CamProfileSchema`). `low | mid` → the sub file, `high` → the main
+			* twin; both ids are already on the row so this never re-searches the
+			* camera. Absent means the provider's own default (the sub file, which
+			* every source is measured to hold).
+			*
+			* `auto` is deliberately NOT accepted here: a stored file has no
+			* broker session, so the adaptive tier cannot be resolved for it. The
+			* viewer resolves `auto` to a profile the same way live does, before
+			* it calls (D549 15).
+			*/
+			profile: require_sleep.CamProfileSchema.optional()
 		}), ClipPlaybackSchema, {
 			kind: "query",
-			auth: "admin"
+			auth: "protected"
 		})
 	}
 };
@@ -50660,6 +50995,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.listSources": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"viewerUi.getStaticDir": {
 		capName: "viewer-ui",
 		capScope: "system",
@@ -52941,6 +53282,11 @@ var METHOD_DEVICE_SELECTORS = Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.listSources": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"waterHeater.setAway": [{
 		name: "deviceId",
 		form: "single",
@@ -58604,6 +58950,8 @@ exports.ClientNetworkStatsSchema = ClientNetworkStatsSchema;
 exports.ClimateControlStatusSchema = ClimateControlStatusSchema;
 exports.ClipPlaybackSchema = ClipPlaybackSchema;
 exports.ClipSchema = ClipSchema;
+exports.ClipSourceAvailabilitySchema = ClipSourceAvailabilitySchema;
+exports.ClipSourceSchema = ClipSourceSchema;
 exports.ClusterAddonNodeDeploymentSchema = ClusterAddonNodeDeploymentSchema;
 exports.ClusterAddonStatusEntrySchema = ClusterAddonStatusEntrySchema;
 exports.CollectionColumnSchema = CollectionColumnSchema;
@@ -59695,6 +60043,7 @@ exports.egressTransportFromRequest = egressTransportFromRequest;
 exports.embeddingEncoderCapability = embeddingEncoderCapability;
 exports.emitDownForOwnedCaps = require_sleep.emitDownForOwnedCaps;
 exports.emitReadiness = require_sleep.emitReadiness;
+exports.emitsCollectionSelector = emitsCollectionSelector;
 exports.encodeProfileFromStreamShape = encodeProfileFromStreamShape;
 exports.encodeVectorBase64 = encodeVectorBase64;
 exports.enumSensorCapability = enumSensorCapability;
@@ -59846,6 +60195,7 @@ exports.notifierCapability = notifierCapability;
 exports.numericSensorCapability = numericSensorCapability;
 exports.oauthIntegrationCapability = oauthIntegrationCapability;
 exports.objectInputDeclaresAddonId = objectInputDeclaresAddonId;
+exports.objectInputDeclaresRequiredDeviceId = objectInputDeclaresRequiredDeviceId;
 exports.occupancyScope = occupancyScope;
 exports.osdCapability = osdCapability;
 exports.osdManagerCapability = osdManagerCapability;