@camstack/types 1.2.179 → 1.2.181

package/dist/index.js

@@ -5,6 +5,124 @@ const require_canonical_hash = require("./canonical-hash-DNV8S5ET.js");
 const require_enums = require("./enums.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 let zod = require("zod");
+//#region src/media/media-owner-key.ts
+/**
+* The one place a media key is built and read.
+*
+* A media key addresses a file by its OWNER, in one grammar:
+*
+* ```
+* <ownerType>:<ownerId>:<fileKind>[:<timestampMs>]
+* ```
+*
+* The owner type is a TABLE. That is already true of every owner on the live
+* hub - `track`, `summary`, `face`, `identity`, `plate` - and the exception was
+* `event`, which covered three tables at once. While event ids were UUIDs the
+* ambiguity cost nothing, because a UUID is unique across tables. D474 made an
+* event id a SQLite rowid alias, so each table numbers from 1 and `event:5`
+* stopped naming one row. Splitting `event` into `motion` / `object` / `audio`
+* restores uniqueness without a fifth segment and without a magic numbering
+* offset, which would have hidden the same invariant somewhere nobody reads.
+*
+* Why this module exists at all, rather than a `split(':')` at each call site:
+* the key is built in the addon, in `ui-library` and in the notification
+* dispatcher, and read positionally in admin-ui (`split(':')[1]` for an owner
+* id). Positional reads are silently wrong the moment a segment moves, and
+* there is no compiler that notices. It lives in `@camstack/types` because both
+* an addon and the UI packages must reach it, and addons may not import each
+* other.
+*
+* `parseMediaOwnerKey` returns `null` for anything it cannot read, and never
+* throws: it sits on the media READ path, where an exception takes out every
+* thumbnail and a guess puts the wrong image on screen. A legacy `event:` key
+* is therefore unreadable BY DESIGN - on this hub the 299 883 resolvable ones
+* are rewritten by the D474 data migration, and the 676 that remain were
+* already orphaned, their event having aged out before it.
+*/
+/**
+* Owner types, i.e. the tables that own media.
+*
+* `motion` / `object` / `audio` are the three event tables; `event` is
+* deliberately absent and must not be re-added - it is the ambiguity this
+* module exists to remove.
+*
+* This list must cover `OWNER_KINDS` in
+* `addon-post-analysis/src/pipeline-analytics/store/media-store.ts`, which is
+* the AUTHORITY on what may own media. I first derived it from the prefixes
+* actually present on the live hub and so omitted `vehicle` and `scene`: both
+* are declared owner kinds with no rows today, and the parser would have
+* rejected their keys the day one appeared. A list derived from data is a list
+* that is correct until the data changes.
+*/
+var MEDIA_OWNER_TYPES = [
+	"track",
+	"summary",
+	"face",
+	"identity",
+	"plate",
+	"vehicle",
+	"scene",
+	"motion",
+	"object",
+	"audio"
+];
+var OWNER_TYPES = new Set(MEDIA_OWNER_TYPES);
+/** Digits only. `Number('')` is 0 and `Number(' ')` is 0, so neither is used. */
+var DIGITS = /^\d+$/;
+function isOwnerType(value) {
+	return OWNER_TYPES.has(value);
+}
+/**
+* Read a media key. `null` when it is not one - an unknown owner type, a legacy
+* `event:` key, a missing segment, or a fourth segment that is not a timestamp.
+*
+* `fileKind` is returned as a plain string rather than validated against
+* `MediaFileKindEnum`: kinds have been RETIRED over time (`crop`,
+* `fullFrameBoxed`) and rows carrying them still exist, so a parser that
+* rejected them would make historical media unreadable while claiming the key
+* was malformed.
+*/
+function parseMediaOwnerKey(key) {
+	const parts = key.split(":");
+	if (parts.length !== 3 && parts.length !== 4) return null;
+	const [ownerType, ownerId, fileKind, timestamp] = parts;
+	if (ownerType === void 0 || !isOwnerType(ownerType)) return null;
+	if (ownerId === void 0 || ownerId.length === 0) return null;
+	if (fileKind === void 0 || fileKind.length === 0) return null;
+	if (timestamp === void 0) return {
+		ownerType,
+		ownerId,
+		fileKind
+	};
+	if (!DIGITS.test(timestamp)) return null;
+	return {
+		ownerType,
+		ownerId,
+		fileKind,
+		timestampMs: Number(timestamp)
+	};
+}
+/** Build a media key. The timestamp segment is omitted when there is none. */
+function formatMediaOwnerKey(key) {
+	const head = `${key.ownerType}:${key.ownerId}:${key.fileKind}`;
+	return key.timestampMs === void 0 ? head : `${head}:${key.timestampMs}`;
+}
+/**
+* The owner types that are event tables, in the order the event-media resolver
+* should consider them. Exported so a consumer asking "is this key an event?"
+* does not re-spell the list and drift from it.
+*/
+var EVENT_OWNER_TYPES = [
+	"motion",
+	"object",
+	"audio"
+];
+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) {
+	return EVENT_OWNER_TYPE_SET.has(ownerType);
+}
+//#endregion
 //#region src/addon/build-addon-route-provider.ts
 /**
 * Build an `IAddonRouteProvider` from a list of routes. Implements
@@ -9723,8 +9841,17 @@ var settingsStoreCapability = {
 		insert: require_sleep.method(zod.z.object({
 			namespace: zod.z.string().optional(),
 			collection: zod.z.string(),
-			record: SettingsRecordSchema
-		}), zod.z.void(), { kind: "mutation" }),
+			record: zod.z.object({
+				id: zod.z.string().optional(),
+				data: zod.z.record(zod.z.string(), zod.z.unknown())
+			})
+		}), zod.z.object({ 
+		/**
+		* The id the row ACTUALLY got (D473): the one supplied, the UUID minted
+		* for an absent one, or the ROWID SQLite assigned on an `INTEGER`
+		* primary key — which is the only place an auto key is knowable.
+		*/
+id: zod.z.union([zod.z.string(), zod.z.number()]) }), { kind: "mutation" }),
 		/**
 		* Insert MANY records in ONE transaction, returning how many landed.
 		*
@@ -9987,8 +10114,17 @@ var dataStoreProviderCapability = {
 		insert: require_sleep.method(zod.z.object({
 			namespace: zod.z.string().optional(),
 			collection: zod.z.string(),
-			record: SettingsRecordSchema
-		}), zod.z.void(), {
+			record: zod.z.object({
+				id: zod.z.string().optional(),
+				data: zod.z.record(zod.z.string(), zod.z.unknown())
+			})
+		}), zod.z.object({ 
+		/**
+		* The id the row ACTUALLY got (D473): the one supplied, the UUID minted
+		* for an absent one, or the ROWID SQLite assigned on an `INTEGER`
+		* primary key — which is the only place an auto key is knowable.
+		*/
+id: zod.z.union([zod.z.string(), zod.z.number()]) }), {
 			kind: "mutation",
 			auth: "admin"
 		}),
@@ -19459,7 +19595,20 @@ var TrackSchema = zod.z.object({
 	...TrackRetrainFields
 });
 var BaseEventFields = {
-	id: zod.z.string(),
+	/**
+	* A SQLite ROWID, assigned by the database (D474).
+	*
+	* Was a 36-character UUID and cost 263 MB of a 1 117 MB database — paid
+	* TWICE per row, in the row and in the primary-key index, across 2.1 million
+	* motion, audio and object events. An `INTEGER PRIMARY KEY` in SQLite **is**
+	* the rowid: the table itself is that B-tree, so the index stops existing
+	* rather than getting smaller. No shorter string does that.
+	*
+	* Defined once here for all three event kinds, which is why they move
+	* together: a per-table migration would have forked this and
+	* `COMMON_BASE_COLUMNS` and reunited them two stages later.
+	*/
+	id: zod.z.number().int(),
 	deviceId: zod.z.number(),
 	timestamp: zod.z.number()
 };
@@ -19478,7 +19627,34 @@ var MotionEventSchema = zod.z.object({
 	/** Omitted in slim projection. */
 	frameHeight: zod.z.number().optional(),
 	/** Populated by B5 (recording playback URL for this event). */
-	mediaUrl: zod.z.string().optional()
+	mediaUrl: zod.z.string().optional(),
+	/**
+	* One row per motion EPISODE, not one per push (D475). `null` while the
+	* episode is still open — a further rising edge extends it in place rather
+	* than inserting a new row. Set once, at close, to `lastOnAt - startedAt`
+	* (the span from the first rising edge to the LAST one, deliberately NOT
+	* `closedAt - startedAt` — the close delay is a quiet CONFIRMATION, not
+	* movement, and folding it in would report `MOTION_CLOSE_AFTER_MS` of
+	* motion for an instantaneous trigger).
+	*
+	* **Absent** (not merely `null`) on a row written before D475 — that means
+	* "closed the old way, before this column existed", never "still open".
+	* Nothing in this codebase may read an absent `durationMs` as an open
+	* episode; only `null` means open.
+	*/
+	durationMs: zod.z.number().nullable().optional(),
+	/**
+	* Ms offsets from `timestamp` (the episode's own first rising edge, so the
+	* first entry is always `0`) of every genuine off→on transition the
+	* episode saw — "ogni evento on si deve salvare" (D475). NOT one entry per
+	* push: a firmware source that keepalives at ~1 Hz for the whole burst
+	* (Reolink, Hikvision) produces exactly one edge; a source that reports an
+	* explicit `false` mid-episode and then resumes before the quiet window
+	* elapses produces another. Stored compactly — see `motion-edge-codec.ts`
+	* — and decoded back to this shape on read. Absent/empty on a legacy row,
+	* which must never be read as "no episode happened here".
+	*/
+	edges: zod.z.array(zod.z.number()).readonly().optional()
 });
 /**
 * Which detection SOURCE produced an object event. `pipeline` = the ML
@@ -19541,6 +19717,23 @@ var ObjectEventSchema = zod.z.object({
 	* includes it (it is light). Absent on rows written before this field.
 	*/
 	frameId: zod.z.string().optional(),
+	/**
+	* A PRODUCER-chosen key that makes a synthetic event's emission idempotent
+	* (D474).
+	*
+	* Only the package detector writes it, and it exists because the event id
+	* stopped being choosable: the delivery and pick-up rows used to BE their
+	* dedupe key (`pa-pkg-<entryId>-delivered`), which is how "never emit a
+	* second delivery for this entry" survived a restart. An `INTEGER` rowid is
+	* assigned by SQLite, so that key had to move off the primary key rather
+	* than be dropped — a detector that cannot recognise its own row re-delivers
+	* every parcel on every boot.
+	*
+	* Absent on every other object event, and on every row written before this
+	* field. Never a substitute for `id`: it is unique per (producer, occasion),
+	* not per row, and nothing addresses a row by it.
+	*/
+	idempotencyKey: zod.z.string().optional(),
 	/** Omitted in slim projection. */
 	trackId: zod.z.string().optional(),
 	className: zod.z.string(),
@@ -21271,6 +21464,14 @@ var NativeCropResultSchema = zod.z.object({
 	* set `encodeJpeg: true`; `bytes` is then absent.
 	*/
 	jpeg: zod.z.string().optional(),
+	/**
+	* The SAME compressed JPEG as `jpeg`, as bytes (D462). Present instead of
+	* `jpeg` when the request set `acceptJpegBytes`; a request that did not gets
+	* `jpeg` exactly as before. MsgPack and the mesh leg both carry binary —
+	* `bytes` above has crossed this boundary as a `Uint8Array` all along — so
+	* base64 was buying nothing but a multi-megabyte string in the relay's heap.
+	*/
+	jpegBytes: zod.z.instanceof(Uint8Array).optional(),
 	width: zod.z.number().int().positive(),
 	height: zod.z.number().int().positive(),
 	/**
@@ -21337,7 +21538,14 @@ var ParkTrackFrameResultSchema = zod.z.discriminatedUnion("parked", [zod.z.objec
 })]);
 /** A retrieved parcel — the runner's own JPEG, base64 for the wire. */
 var ParkedTrackFrameSchema = zod.z.object({
-	jpeg: zod.z.string(),
+	/**
+	* Base64 JPEG — the pre-D462 wire. OPTIONAL since D462: a request that set
+	* `acceptJpegBytes` is answered in `jpegBytes` and this is then absent.
+	* Exactly one of the two is present.
+	*/
+	jpeg: zod.z.string().optional(),
+	/** The same JPEG as bytes, for a caller that declared it reads them (D462). */
+	jpegBytes: zod.z.instanceof(Uint8Array).optional(),
 	width: zod.z.number().int().positive(),
 	height: zod.z.number().int().positive(),
 	/** The frame instant the parcel shows (the caller's clock, echoed back). */
@@ -22176,6 +22384,13 @@ var pipelineRunnerCapability = {
 			bbox: NativeCropBboxSchema,
 			maxWidth: zod.z.number().int().positive().optional(),
 			/**
+			* The caller reads a `Uint8Array` (D462). When set, a JPEG answer comes
+			* back in `jpegBytes` instead of base64 `jpeg`. Absent means the old
+			* wire — never assume consent: a pre-D462 caller parses the field as
+			* base64 and bytes would decode to garbage rather than fail.
+			*/
+			acceptJpegBytes: zod.z.boolean().optional(),
+			/**
 			* When `true`, the runner encodes the resolved crop to JPEG ON THE
 			* OWNING NODE and returns it in `jpeg` (base64) INSTEAD of raw `bytes`.
 			* Callers set this for CROSS-NODE fetches (`handle.nodeId` is a remote
@@ -22348,7 +22563,14 @@ var pipelineRunnerCapability = {
 		getParkedTrackFrame: require_sleep.method(zod.z.object({
 			deviceId: zod.z.number(),
 			trackId: zod.z.string(),
-			kind: ParkedFrameKindSchema
+			kind: ParkedFrameKindSchema,
+			/**
+			* The caller reads a `Uint8Array` (D462). When set, a JPEG answer comes
+			* back in `jpegBytes` instead of base64 `jpeg`. Absent means the old
+			* wire — never assume consent: a pre-D462 caller parses the field as
+			* base64 and bytes would decode to garbage rather than fail.
+			*/
+			acceptJpegBytes: zod.z.boolean().optional()
 		}), ParkedTrackFrameSchema.nullable()),
 		/**
 		* Drop every parcel of a track — the hub closed it. Idempotent. A track
@@ -30644,14 +30866,72 @@ authKey: zod.z.string().optional() }), zod.z.object({
 * (alert-center, advanced-notifier) can subscribe once and receive
 * motion from every camera.
 */
+/**
+* How long after a camera's last rising edge `pipeline-analytics` closes the
+* motion EPISODE row it kept open for it (D475) — "il delay della cap", in
+* the operator's words. One authority for the whole system: every provider
+* that seeds `autoClearAfterMs` on a `Camera` device writes this SAME
+* constant while `detected: true` (never its own number — Hikvision used to
+* seed its internal 3 s inactivity timer here, which is a different clock for
+* a different purpose), and `MotionEpisodeTracker` imports it directly rather
+* than reading the live cap value on the hot path. A `Sensor` device (HA
+* binary sensor, Homematic) gets a genuine push both ways and has no episode
+* to close on a timer, so it writes `null`, never this constant.
+*/
+var MOTION_CLOSE_AFTER_MS = 15e3;
 var MotionStatusSchema = zod.z.object({
 	detected: zod.z.boolean(),
 	/** Ms epoch of the last detected-true observation. Null if never detected. */
 	lastDetectedAt: zod.z.number().nullable(),
 	/**
-	* Ms after which `detected` auto-reverts to false if no fresh push
-	* arrives. Null means the provider leaves detected state until a
-	* native "clear" event.
+	* `MOTION_CLOSE_AFTER_MS` while `detected: true` on a `Camera` device,
+	* `null` while false and on every `Sensor` device (D475) — see that
+	* constant's doc for the one-authority rule.
+	*
+	* ## Reading this field still arms nothing
+	*
+	* It reads like an instruction to the consumer ("revert after N ms if
+	* no fresh push arrives") and it is not one: nothing in this repo reads
+	* the LIVE cap value to drive a timer. `pipeline-analytics`'s motion-episode
+	* close DOES now use the same number — `MOTION_CLOSE_AFTER_MS` — but as an
+	* imported constant, not as a read of `device.state.motion.value`, so this
+	* field stays what it always was: DESCRIPTIVE output, mirroring an answer
+	* computed elsewhere. Building a self-clear timer out of a READ of this
+	* field would add a second falling-edge authority beside whichever one
+	* already owns the device, and two that can disagree are worse than one.
+	* Consumers that need a falling edge SHAPED differently — held open across
+	* a flapping source — debounce on their own side and say so, as
+	* `addon-export-alexa/src/motion-clear-hold.ts` and
+	* `addon-export-hap`'s `RESET_DEBOUNCE_MS` both do.
+	*
+	* ## Who writes it
+	*
+	* - **Cameras** — the runner's phase machine, `active → watching` on
+	*   `cooldown_expired`, which then writes this slice with
+	*   `detected: false` (`handlePhaseChanged` in
+	*   `pipeline-runner/index.ts`). It produces the FALLING edge, which
+	*   matters most for the sources that only ever push a rising one:
+	*   Reolink emits `MotionOnMotionChanged { detected: true }` and never
+	*   a false.
+	* - **Sensors** (Home Assistant binary sensors, Homematic) — the
+	*   provider pushes the false itself, from the upstream system's own
+	*   state change. No phase machine is involved.
+	*
+	* ### The phase machine is CANONICAL, not sole — and that is a defect
+	*
+	* An earlier revision of this docblock (mine, 2026-09-12) claimed the
+	* phase machine is the sole writer for a camera. It is not.
+	* `hikvision-camera.ts:3464` and `amcrest-camera.ts:445` both call
+	* `setCapSlice(motionCapability, …)` on their own rising edge, and
+	* Hikvision's comment says why: it read THIS docblock, agreed the
+	* runner is canonical, and wrote anyway to avoid per-tick churn. So
+	* two authorities can disagree about one slice, which this repo
+	* forbids, and the doc said otherwise — which is worse than saying
+	* nothing, because it reads as verification.
+	*
+	* This predates D475 and is not fixed there: the fix touches every
+	* camera provider. Recorded in D475's Consequences. Do not restore the
+	* "sole writer" wording without also removing the other writers.
 	*/
 	autoClearAfterMs: zod.z.number().nullable()
 });
@@ -30721,7 +31001,11 @@ onMotionChanged: { data: MotionOnMotionChangedDataSchema } },
 	*/
 	runtimeState: MotionStatusSchema,
 	/**
-	* Runtime-state durability: **session** — self-clearing by construction (`autoClearAfterMs`); a restored `detected: true` is a frozen event, and the next frame re-publishes the real one.
+	* Runtime-state durability: **session** — every writer of this slice
+	* writes only on an EDGE, so a restored `detected: true` would stay
+	* frozen until the next one instead of being corrected. The next edge
+	* re-publishes the real state. (On who the writers are, and why there
+	* is more than one, see `autoClearAfterMs` above.)
 	*
 	* See `RuntimeStateDurability`. Enforced by
 	* `scripts/check-runtime-state-durability.ts`.
@@ -56003,6 +56287,7 @@ exports.DoorbellStatusSchema = DoorbellStatusSchema;
 exports.EVENTFUL_CAP_NAMES = EVENTFUL_CAP_NAMES;
 exports.EVENT_DENSITY_BATCH_MAX = EVENT_DENSITY_BATCH_MAX;
 exports.EVENT_KIND_BY_CAP = EVENT_KIND_BY_CAP;
+exports.EVENT_OWNER_TYPES = EVENT_OWNER_TYPES;
 exports.EVENT_PAD_MS = EVENT_PAD_MS;
 exports.EVENT_TAXONOMY = EVENT_TAXONOMY;
 exports.EXPORT_DENSE_MAX_RANGES = EXPORT_DENSE_MAX_RANGES;
@@ -56193,10 +56478,12 @@ exports.MAX_KEYS = MAX_KEYS;
 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.METHOD_ACCESS_MAP = METHOD_ACCESS_MAP;
 exports.METHOD_DEVICE_SELECTORS = METHOD_DEVICE_SELECTORS;
 exports.MODEL_FORMATS = MODEL_FORMATS;
 exports.MODEL_PROVIDER_IDS = MODEL_PROVIDER_IDS;
+exports.MOTION_CLOSE_AFTER_MS = MOTION_CLOSE_AFTER_MS;
 exports.MOTION_TRIGGER_FEATURE = MOTION_TRIGGER_FEATURE;
 exports.ManagedModelCatalogEntrySchema = ManagedModelCatalogEntrySchema;
 exports.ManagedModelExtraFileSchema = ManagedModelExtraFileSchema;
@@ -56968,6 +57255,7 @@ exports.floodCapability = floodCapability;
 exports.foldSnapshotByFunction = foldSnapshotByFunction;
 exports.formatForBackend = formatForBackend;
 exports.formatForRuntime = formatForRuntime;
+exports.formatMediaOwnerKey = formatMediaOwnerKey;
 exports.gasCapability = gasCapability;
 exports.gbToBytes = gbToBytes;
 exports.generateAutomationBlock = generateAutomationBlock;
@@ -57003,6 +57291,7 @@ exports.isDetectionMacroClass = isDetectionMacroClass;
 exports.isDeviceConfigCap = require_sleep.isDeviceConfigCap;
 exports.isDeviceScopedCap = require_sleep.isDeviceScopedCap;
 exports.isEvent = require_sleep.isEvent;
+exports.isEventOwnerType = isEventOwnerType;
 exports.isFirstLevelMacroClass = isFirstLevelMacroClass;
 exports.isIsolatedBuiltin = isIsolatedBuiltin;
 exports.isLocationEnabled = isLocationEnabled;
@@ -57090,6 +57379,7 @@ exports.parseExpression = parseExpression;
 exports.parseJsonArray = require_sleep.parseJsonArray;
 exports.parseJsonObject = require_sleep.parseJsonObject;
 exports.parseJsonUnknown = require_sleep.parseJsonUnknown;
+exports.parseMediaOwnerKey = parseMediaOwnerKey;
 exports.parseProcStatus = parseProcStatus;
 exports.parseProfileBrokerId = require_sleep.parseProfileBrokerId;
 exports.parseRuleSection = parseRuleSection;