@camstack/types 1.2.179 → 1.2.181

package/dist/media/media-owner-key.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ */
+export declare const MEDIA_OWNER_TYPES: readonly ["track", "summary", "face", "identity", "plate", "vehicle", "scene", "motion", "object", "audio"];
+export type MediaOwnerType = (typeof MEDIA_OWNER_TYPES)[number];
+/** A parsed media key. `timestampMs` is absent for the three-segment form. */
+export interface MediaOwnerKey {
+    readonly ownerType: MediaOwnerType;
+    readonly ownerId: string;
+    readonly fileKind: string;
+    readonly timestampMs?: number;
+}
+/**
+ * What a caller may hand `formatMediaOwnerKey`. `ownerId` widens to `number`
+ * because an event id IS a number now (D474) and stringifying at every call
+ * site is how the old `String(id)` sprawl started.
+ */
+export interface MediaOwnerKeyInput {
+    readonly ownerType: MediaOwnerType;
+    readonly ownerId: string | number;
+    readonly fileKind: string;
+    readonly timestampMs?: number;
+}
+/**
+ * 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.
+ */
+export declare function parseMediaOwnerKey(key: string): MediaOwnerKey | null;
+/** Build a media key. The timestamp segment is omitted when there is none. */
+export declare function formatMediaOwnerKey(key: MediaOwnerKeyInput): string;
+/**
+ * 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.
+ */
+export declare const EVENT_OWNER_TYPES: readonly ["motion", "object", "audio"];
+export type EventOwnerType = (typeof EVENT_OWNER_TYPES)[number];
+/** True when this key's owner is one of the three event tables. */
+export declare function isEventOwnerType(ownerType: MediaOwnerType): ownerType is EventOwnerType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.179",
+  "version": "1.2.181",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",