@camstack/types 1.2.234 → 1.2.236

package/dist/index.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-DImve4HM.js");
+const require_sleep = require("./sleep-Cqxm5OIN.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");
@@ -146,6 +146,20 @@ var EVENT_OWNER_TYPES = [
 * nothing failing until a caller asked.
 */
 var EventOwnerTypeSchema = zod.z.enum(EVENT_OWNER_TYPES);
+/**
+* The owner kinds a media-PRESENCE probe may ask about: the three event tables
+* plus `track`.
+*
+* `videoclips` resolves a clip's still the way `resolveDefaultEventMedia` does
+* — the event's OWN media when it has any, else its owning TRACK's — so the
+* probe needs exactly this union and no more of {@link MediaOwnerType}. Built
+* FROM {@link EVENT_OWNER_TYPES} so a fourth event table reaches the probe the
+* day it is declared, rather than being accepted by one side and refused by the
+* other.
+*/
+var MEDIA_PRESENCE_OWNER_KINDS = [...EVENT_OWNER_TYPES, "track"];
+/** The same list as a Zod enum, for the cap input that carries it. */
+var MediaPresenceOwnerKindSchema = zod.z.enum(MEDIA_PRESENCE_OWNER_KINDS);
 var EVENT_OWNER_TYPE_SET = new Set(EVENT_OWNER_TYPES);
 /** True when this key's owner is one of the three event tables. */
 function isEventOwnerType(ownerType) {
@@ -12939,30 +12953,30 @@ var deviceManagerCapability = {
 		*/
 		getAllBindings: require_sleep.method(zod.z.object({}), zod.z.array(DeviceBindingsForDeviceSchema)),
 		/**
-		* 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.
+		* Activate (or deactivate) a wrapper addon for a (device, cap) pair — the
+		* per-camera function switch's ONE authority (D62).
+		*
+		* SINGLETON capabilities only. Persists the binding via ctx.settings;
+		* `active: false` clears the wrapper (falling back to native if one is
+		* registered) by persisting the explicit `{ wrapperAddonId: null }` marker,
+		* which is what stops `getBindings` re-binding a `defaultActive` wrapper.
+		*
+		* **A COLLECTION capability is REFUSED by name.** It briefly took a
+		* `sourceId` and wrote a per-device DENY set, so one of an addon's several
+		* sources could be switched off without switching off the rest (D556, then
+		* D555's re-key by source). The operator removed the whole idea the same
+		* day: *"tutti i providers funzionano sempre, non serve
+		* disattivarli/attivarli … loro vivono lì"* (D557 amended, third). A
+		* collection cap's providers are a DERIVED set — every addon that provides
+		* the cap for this device type, computed on every read and persisted
+		* nowhere — so there is nothing here to activate, and a verb that accepted
+		* the call could only write a field the enumeration does not read. That is
+		* the D62 shape, and this repo has shipped it four times.
 		*/
 		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",
@@ -22683,6 +22697,35 @@ var pipelineAnalyticsCapability = {
 			deviceId: zod.z.number()
 		}), zod.z.array(MediaFileInfoSchema).readonly()),
 		/**
+		* Which of `ownerIds` hold at least ONE media row — an INDEX read, never a
+		* blob read, and the LICENCE `videoclips` needs to publish a `thumbnail`.
+		*
+		* The event-media URL is stamped from a template for every event in the
+		* system, so "the plane is up" was being served as "there are bytes": 64 of
+		* one camera's 179 clips pointed at a 404 (device 3836, 2026-08-17). This
+		* is the question that turns the stamp into a claim.
+		*
+		* It is on the WIRE because the clip source is registered by the addon that
+		* owns the FOOTAGE, not by this one (D560) — the probe used to be an
+		* in-process `MediaStore` read. One call per OWNER KIND, never one per
+		* owner: that N+1 is what `MediaStore.ownersWithMedia` was written to
+		* prevent, and crossing a process boundary makes it worse, not better.
+		* `ownerIds` is bounded at the same 5 000 the annotation fetch is bounded
+		* at, so one pathological camera-day cannot mint an unbounded request.
+		*
+		* THROWS rather than answering partially. A probe that quietly
+		* under-reports reads as "these owners have nothing" and the caller drops
+		* thumbnails that exist — the opposite failure to the one above, and
+		* equally invisible.
+		*
+		* `deviceId` is the authorization subject, exactly as on `getEventMedia`.
+		*/
+		ownersWithMedia: require_sleep.method(zod.z.object({
+			deviceId: zod.z.number(),
+			ownerKind: MediaPresenceOwnerKindSchema,
+			ownerIds: zod.z.array(zod.z.string()).max(5e3)
+		}), zod.z.array(zod.z.string()).readonly()),
+		/**
 		* Search object events by text query using CLIP cosine similarity.
 		* Encodes `text` via the `embedding-encoder` cap, queries the
 		* `ObjectEmbeddingStore` with optional prefilters, ranks all matching
@@ -27121,20 +27164,26 @@ var vectorStoreCapability = {
 *
 * 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 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.
+* substituted for another. The DEFAULT provider (`analytics`, registered by
+* the RECORDER — the addon that owns the footage, D560 — `defaultActive: true`)
+* composes the analytics event log (markers + thumbnails, read over `ctx.api`)
+* with the recorder's own `getPlaybackManifest` — a clip is a time-WINDOW over
+* existing footage, never a separate file. A camera that 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`), and a
+* device's SOURCES are its BINDINGS: `deviceManager.getBindings(deviceId)` is
+* what says a provider serves this camera, never the set of addons that
+* happen to have registered the capability somewhere in the cluster. That is
+* what stopped one addon appearing three times on 592 — as the device's
+* native provider, as the hub-local registration and as an
+* `<addonId>@<nodeId>` one (D554 amended 2026-09-20).
+*
+* `listClips` is asked of ONE provider at a time
+* ({@link videoclipsCapability.methods.listClips} `provider`), defaulting to
+* the bound one, which is CamStack on every camera today. It is NOT a union
+* over everything a camera has: *"l'utilizzatore è uno solo"*.
 * {@link videoclipsCapability.methods.getClipPlayback} dispatches by the
 * source namespace inside the clip id, which is why ids are self-contained.
 *
@@ -27150,6 +27199,47 @@ var vectorStoreCapability = {
 var MAX_CLIP_EVENT_IDS = 24;
 /** Cap on {@link ClipSchema.labels} — the ribbon row has space for ~3 words. */
 var MAX_CLIP_LABELS = 3;
+/**
+* Every reason a still-mint route may refuse, as a TOKEN — never prose.
+*
+* The route also sends the prose (`x-camstack-reason`), because a firmware's
+* own words are the only thing that explains a `camera-refused`. But the token
+* is what a surface may key a table on, and the code and the prose are
+* separate headers precisely because they had been the same one: the route
+* sent `queue-full: 16 thumbnail mints already waiting for host …` and the
+* surface's table was keyed by `queue-full`, so every refusal on this fleet
+* rendered as `Refused: <prose>`.
+*/
+var ClipStillRefusalCodeSchema = zod.z.enum([
+	"queue-full",
+	"camera-backoff",
+	"sleeping",
+	"camera-refused",
+	"no-keyframe",
+	"no-catalog-row",
+	"unsupported",
+	"unknown-device",
+	"uid-missing"
+]);
+/**
+* Whether a refusal is "not yet" or "never" — decided by the BRANCH that
+* refused and carried on the wire, never inferred by the client from the code.
+*
+* `deferred` means the work is queued or the host is resting: the surface
+* shows LOADING and comes back, under a bound. `final` means no retry can
+* change the answer: the surface shows the reason and stops.
+*
+* A response that carries no disposition is read as `final`, which is exactly
+* how every build before this one behaved — an old provider under a new
+* surface keeps the old, safe behaviour rather than gaining a retry loop.
+*/
+var ClipStillDispositionSchema = zod.z.enum(["deferred", "final"]);
+/** The camera's / provider's own words. Kept verbatim, never parsed. */
+var CLIP_STILL_REASON_HEADER = "x-camstack-reason";
+/** One {@link ClipStillRefusalCodeSchema} token, alone. */
+var CLIP_STILL_REASON_CODE_HEADER = "x-camstack-reason-code";
+/** One {@link ClipStillDispositionSchema} token, alone. */
+var CLIP_STILL_DISPOSITION_HEADER = "x-camstack-disposition";
 var ClipSchema = zod.z.object({
 	/** Opaque, provider-namespaced id. The default provider encodes the time
 	*  window so `getClipPlayback` is self-contained (no event re-query). */
@@ -27300,7 +27390,25 @@ var ClipSchema = zod.z.object({
 	*/
 	playable: zod.z.boolean().optional(),
 	/** Why {@link playable} is false, verbatim (`no-file-for-window`). */
-	unplayableReason: zod.z.string().optional()
+	unplayableReason: zod.z.string().optional(),
+	/**
+	* This clip is STILL BEING WRITTEN, so {@link ClipSchema.timeRange}`.endMs`
+	* is not its end.
+	*
+	* Absent — the common case — means the row is closed and its `endMs` is the
+	* end of the recording. Present and `true` means the source told us the file
+	* has no end yet, and the `endMs` we carry is whatever the camera's index
+	* entry happened to hold: on a Reolink E1 Outdoor PoE (592, measured
+	* 2026-09-20) the newest file `…_192927_000000_…_0.mp4` reported an `endTime`
+	* of 19:29:56 and STILL reported it eight minutes later, while the file went
+	* on growing. A surface that drew 29 s there was lying about a clip that
+	* plays for minutes, on the one row the operator looks at first.
+	*
+	* `endMs` is deliberately still a number: it is the best bound anything has
+	* for a mint window or a byte fetch, and every consumer already requires it.
+	* This flag says what it is WORTH, and a duration is not drawn from it.
+	*/
+	inProgress: zod.z.boolean().optional()
 });
 var ClipPlaybackSchema = zod.z.object({
 	/**
@@ -27383,59 +27491,17 @@ var ClipSourceSchema = zod.z.object({
 	* 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).
+	* (D557). One addon may serve SEVERAL sources, which is why the per-device
+	* switch is keyed by SOURCE and not by this (D555) — `addon-provider-reolink`
+	* served a hub child two of them until the two views were measured to be one
+	* store read twice (D555) and then read ONE way (D565).
 	*
 	* 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()
+	availability: ClipSourceAvailabilitySchema
 });
 var videoclipsCapability = {
 	name: "videoclips",
@@ -27455,17 +27521,31 @@ var videoclipsCapability = {
 	* `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`.
+	* **It is a SECTION of the Recording tab, at the end of it — not a tab of
+	* its own.** It shipped as a `clips` top-tab and the operator rejected the
+	* placement: *"utilizzerei la stessa tab recordings, lì abbiamo già tutto il
+	* necessario, una nuova sezione alla fine per le clips"*. The Recording tab
+	* already holds the recorder's panel, the schedule bands and the unified
+	* retention policy; footage the camera itself holds is the same question,
+	* asked of a different store. `order: 100` puts it after all of them with
+	* room left in front. The `clips` entry in `WELL_KNOWN_TABS` went with it —
+	* a well-known id nobody declares is an invitation to mint the tab again.
+	*
+	* `topTab` stays: the browser owns a pane (a day's tiles, a source list and
+	* a player) and the Config tab's inner bar has no room for one. The widget
+	* itself is `host/clips-browser` in ui-library's `HOST_WIDGETS`, and because
+	* the admin Recordings page renders every `location:'top-tab'` +
+	* `tab:'recording'` section behind its camera picker
+	* (`CameraRecordingSettingsSection`), this declaration lands the section on
+	* BOTH surfaces with no second wiring.
 	*/
 	deviceConfig: { ui: {
 		kind: "widget",
 		widgetId: "host/clips-browser",
-		tab: "clips",
+		tab: "recording",
 		topTab: true,
 		label: "Clips",
-		order: 0
+		order: 100
 	} },
 	methods: {
 		listClips: require_sleep.method(zod.z.object({
@@ -27474,13 +27554,23 @@ var videoclipsCapability = {
 			until: zod.z.number(),
 			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.
+			* 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).
+			*
+			* 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.
 			*/
-			sources: zod.z.array(zod.z.string()).optional()
+			provider: zod.z.string().optional()
 		}), zod.z.array(ClipSchema).readonly(), {
 			kind: "query",
 			auth: "protected"
@@ -48403,6 +48493,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.ownersWithMedia": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.pauseForStorageMigration": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -52576,6 +52672,11 @@ var METHOD_DEVICE_SELECTORS = Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"pipelineAnalytics.ownersWithMedia": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"pipelineAnalytics.proposeRetrainAnnotations": [{
 		name: "deviceId",
 		form: "single",
@@ -58898,6 +58999,9 @@ exports.CAP_NAMES_WITH_STATUS = CAP_NAMES_WITH_STATUS;
 exports.CAP_NODE_PIN_CONTEXT_KEY = require_sleep.CAP_NODE_PIN_CONTEXT_KEY;
 exports.CAP_PROVIDER_KIND_MAP = CAP_PROVIDER_KIND_MAP;
 exports.CLASS_MAP_MACRO_TARGETS = CLASS_MAP_MACRO_TARGETS;
+exports.CLIP_STILL_DISPOSITION_HEADER = CLIP_STILL_DISPOSITION_HEADER;
+exports.CLIP_STILL_REASON_CODE_HEADER = CLIP_STILL_REASON_CODE_HEADER;
+exports.CLIP_STILL_REASON_HEADER = CLIP_STILL_REASON_HEADER;
 exports.CLUSTER_MODEL_SCOPED_STEPS = CLUSTER_MODEL_SCOPED_STEPS;
 exports.CLUSTER_MODEL_SECTION_ID = CLUSTER_MODEL_SECTION_ID;
 exports.CLUSTER_STEP_SETTING_FIELDS = CLUSTER_STEP_SETTING_FIELDS;
@@ -58952,6 +59056,8 @@ exports.ClipPlaybackSchema = ClipPlaybackSchema;
 exports.ClipSchema = ClipSchema;
 exports.ClipSourceAvailabilitySchema = ClipSourceAvailabilitySchema;
 exports.ClipSourceSchema = ClipSourceSchema;
+exports.ClipStillDispositionSchema = ClipStillDispositionSchema;
+exports.ClipStillRefusalCodeSchema = ClipStillRefusalCodeSchema;
 exports.ClusterAddonNodeDeploymentSchema = ClusterAddonNodeDeploymentSchema;
 exports.ClusterAddonStatusEntrySchema = ClusterAddonStatusEntrySchema;
 exports.CollectionColumnSchema = CollectionColumnSchema;
@@ -59275,6 +59381,7 @@ exports.MAX_REASONS_PER_KEY = MAX_REASONS_PER_KEY;
 exports.MAX_SENSOR_TRIGGER_DEVICES = MAX_SENSOR_TRIGGER_DEVICES;
 exports.MAX_TRACK_DEBUG_NOTE_LEN = MAX_TRACK_DEBUG_NOTE_LEN;
 exports.MEDIA_OWNER_TYPES = MEDIA_OWNER_TYPES;
+exports.MEDIA_PRESENCE_OWNER_KINDS = MEDIA_PRESENCE_OWNER_KINDS;
 exports.METHOD_ACCESS_MAP = METHOD_ACCESS_MAP;
 exports.METHOD_DEVICE_SELECTORS = METHOD_DEVICE_SELECTORS;
 exports.MODEL_FORMATS = MODEL_FORMATS;
@@ -59301,6 +59408,7 @@ exports.MediaFileSchema = MediaFileSchema;
 exports.MediaPlayerRepeatSchema = MediaPlayerRepeatSchema;
 exports.MediaPlayerStateSchema = MediaPlayerStateSchema;
 exports.MediaPlayerStatusSchema = MediaPlayerStatusSchema;
+exports.MediaPresenceOwnerKindSchema = MediaPresenceOwnerKindSchema;
 exports.MediaRelocateModeSchema = MediaRelocateModeSchema;
 exports.MeshPeerSchema = MeshPeerSchema;
 exports.MeshStatusSchema = MeshStatusSchema;