@adventurelabs/scout-core 2.0.18 → 2.1.0

package/dist/client/index.d.ts

@@ -5,9 +5,12 @@ export * from "../helpers/bounding_boxes";
 export * from "../helpers/email";
 export * from "../helpers/eventMedia";
 export * from "../helpers/eventUtils";
+export * from "../helpers/galleryMedia";
 export { default as get_gps_center } from "../helpers/gps";
 export * from "../helpers/herd_modules_equal";
 export * from "../helpers/location";
+export * from "../helpers/mediaState";
+export * from "../helpers/product_catalog";
 export * from "../helpers/realtime_topic_access";
 export * from "../helpers/storagePath";
 export * from "../helpers/time";
@@ -45,6 +48,7 @@ export { create_document_template_query as create_document_template, get_documen
 export { search_embeddings_vertex_multimodal_001_query as search_embeddings_vertex_multimodal_001 } from "../helpers/embeddings.queries";
 export { delete_event_query as delete_event, get_event_by_id_query as get_event_by_id, get_total_events_by_herd_query as get_total_events_by_herd, insert_event_query as insert_event, match_events_by_vertex_embedding_query as match_events_by_vertex_embedding, update_event_query as update_event, } from "../helpers/events.queries";
 export { create_battery_cycle_count_query as create_battery_cycle_count, delete_battery_cycle_count_query as delete_battery_cycle_count, get_battery_cycle_counts_by_battery_id_query as get_battery_cycle_counts_by_battery_id, update_battery_cycle_count_query as update_battery_cycle_count, } from "../helpers/battery_cycle_counts.queries";
+export { get_gallery_items_by_ids_query as get_gallery_items_by_ids, type IGalleryItemsByIdsArgs, } from "../helpers/gallery.queries";
 export { get_health_metrics_query as get_health_metrics, get_health_metrics_summary_query as get_health_metrics_summary, } from "../helpers/health_metrics.queries";
 export { get_herd_media_usage_query as get_herd_media_usage, get_latest_herd_media_usage_query as get_latest_herd_media_usage, } from "../helpers/herd_media_usage.queries";
 export { check_device_online_status_query as check_device_online_status, get_heartbeats_by_device_query as get_heartbeats_by_device, get_last_heartbeat_by_device_query as get_last_heartbeat_by_device, } from "../helpers/heartbeats.queries";

package/dist/client/index.js

@@ -8,9 +8,12 @@ export * from "../helpers/bounding_boxes";
 export * from "../helpers/email";
 export * from "../helpers/eventMedia";
 export * from "../helpers/eventUtils";
+export * from "../helpers/galleryMedia";
 export { default as get_gps_center } from "../helpers/gps";
 export * from "../helpers/herd_modules_equal";
 export * from "../helpers/location";
+export * from "../helpers/mediaState";
+export * from "../helpers/product_catalog";
 export * from "../helpers/realtime_topic_access";
 export * from "../helpers/storagePath";
 export * from "../helpers/time";
@@ -50,6 +53,7 @@ export { create_document_template_query as create_document_template, get_documen
 export { search_embeddings_vertex_multimodal_001_query as search_embeddings_vertex_multimodal_001 } from "../helpers/embeddings.queries";
 export { delete_event_query as delete_event, get_event_by_id_query as get_event_by_id, get_total_events_by_herd_query as get_total_events_by_herd, insert_event_query as insert_event, match_events_by_vertex_embedding_query as match_events_by_vertex_embedding, update_event_query as update_event, } from "../helpers/events.queries";
 export { create_battery_cycle_count_query as create_battery_cycle_count, delete_battery_cycle_count_query as delete_battery_cycle_count, get_battery_cycle_counts_by_battery_id_query as get_battery_cycle_counts_by_battery_id, update_battery_cycle_count_query as update_battery_cycle_count, } from "../helpers/battery_cycle_counts.queries";
+export { get_gallery_items_by_ids_query as get_gallery_items_by_ids, } from "../helpers/gallery.queries";
 export { get_health_metrics_query as get_health_metrics, get_health_metrics_summary_query as get_health_metrics_summary, } from "../helpers/health_metrics.queries";
 export { get_herd_media_usage_query as get_herd_media_usage, get_latest_herd_media_usage_query as get_latest_herd_media_usage, } from "../helpers/herd_media_usage.queries";
 export { check_device_online_status_query as check_device_online_status, get_heartbeats_by_device_query as get_heartbeats_by_device, get_last_heartbeat_by_device_query as get_last_heartbeat_by_device, } from "../helpers/heartbeats.queries";

package/dist/helpers/cache.d.ts

@@ -1,4 +1,4 @@
-import { IHerdModule } from "../types/herd_module";
+import { IHerdModulesSnapshot } from "../types/herd_module";
 export type JwtMintCacheKey = "client_abilities" | "pubsub";
 type CachedJwtMint = {
     token: string;
@@ -53,8 +53,8 @@ export declare class ScoutCache {
     private getDatabase;
     private init;
     private validateDatabaseSchema;
-    setHerdModules(herdModules: IHerdModule[], ttlMs?: number, etag?: string, userId?: string): Promise<void>;
-    getHerdModules(userId?: string): Promise<CacheResult<IHerdModule[]>>;
+    setHerdModules(snapshot: IHerdModulesSnapshot, ttlMs?: number, etag?: string, userId?: string): Promise<void>;
+    getHerdModules(userId?: string): Promise<CacheResult<IHerdModulesSnapshot>>;
     setJwtMint<T extends CachedJwtMint>(key: JwtMintCacheKey, mint: T, userId?: string): Promise<void>;
     getJwtMint<T extends CachedJwtMint>(key: JwtMintCacheKey, userId?: string): Promise<CacheResult<T>>;
     clearJwtMint(key: JwtMintCacheKey, userId?: string): Promise<void>;
@@ -67,7 +67,7 @@ export declare class ScoutCache {
         shouldRefresh: boolean;
         reason: string;
     }>;
-    preloadCache(loadFunction: () => Promise<IHerdModule[]>, ttlMs?: number, userId?: string): Promise<void>;
+    preloadCache(loadFunction: () => Promise<IHerdModulesSnapshot>, ttlMs?: number, userId?: string): Promise<void>;
     getDefaultTtl(): number;
     getCurrentDbVersion(): number;
     isCacheVersionCompatible(userId?: string): Promise<boolean>;

package/dist/helpers/cache.js

@@ -1,8 +1,11 @@
+import { EMPTY_PRODUCT_CATALOG } from "./product_catalog";
 const LEGACY_DB_NAME = "ScoutCache";
-const DB_VERSION = 9;
+const DB_VERSION = 10;
 const HERD_MODULES_STORE = "herd_modules";
+const PRODUCT_CATALOG_STORE = "product_catalog";
 const JWT_MINTS_STORE = "jwt_mints";
 const CACHE_METADATA_STORE = "cache_metadata";
+const PRODUCT_CATALOG_KEY = "product_catalog";
 const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
 let legacyDbDeleteStarted = false;
 function getSupabaseProjectRef() {
@@ -118,6 +121,9 @@ export class ScoutCache {
                     herdModulesStore.createIndex("dbVersion", "dbVersion", {
                         unique: false,
                     });
+                    db.createObjectStore(PRODUCT_CATALOG_STORE, {
+                        keyPath: "key",
+                    });
                     const jwtMintsStore = db.createObjectStore(JWT_MINTS_STORE, {
                         keyPath: "key",
                     });
@@ -149,18 +155,20 @@ export class ScoutCache {
     }
     validateDatabaseSchema(db) {
         return (db.objectStoreNames.contains(HERD_MODULES_STORE) &&
+            db.objectStoreNames.contains(PRODUCT_CATALOG_STORE) &&
             db.objectStoreNames.contains(JWT_MINTS_STORE) &&
             db.objectStoreNames.contains(CACHE_METADATA_STORE));
     }
-    async setHerdModules(herdModules, ttlMs = DEFAULT_TTL_MS, etag, userId) {
+    async setHerdModules(snapshot, ttlMs = DEFAULT_TTL_MS, etag, userId) {
         const db = await this.getDatabase(userId);
-        const transaction = db.transaction([HERD_MODULES_STORE, CACHE_METADATA_STORE], "readwrite");
+        const transaction = db.transaction([HERD_MODULES_STORE, PRODUCT_CATALOG_STORE, CACHE_METADATA_STORE], "readwrite");
         const completion = transactionComplete(transaction);
         const herdModulesStore = transaction.objectStore(HERD_MODULES_STORE);
+        const productCatalogStore = transaction.objectStore(PRODUCT_CATALOG_STORE);
         const metadataStore = transaction.objectStore(CACHE_METADATA_STORE);
         const timestamp = Date.now();
         herdModulesStore.clear();
-        herdModules.forEach((herdModule) => {
+        snapshot.herd_modules.forEach((herdModule) => {
             if (herdModule.herd.id == null)
                 return;
             herdModulesStore.put({
@@ -170,6 +178,12 @@ export class ScoutCache {
                 dbVersion: DB_VERSION,
             });
         });
+        productCatalogStore.put({
+            key: PRODUCT_CATALOG_KEY,
+            data: snapshot.product_catalog,
+            timestamp,
+            dbVersion: DB_VERSION,
+        });
         const metadata = {
             key: "herd_modules",
             timestamp,
@@ -185,10 +199,11 @@ export class ScoutCache {
     async getHerdModules(userId) {
         const scopedUserId = userId ?? this.userId ?? undefined;
         const db = await this.getDatabase(scopedUserId);
-        const transaction = db.transaction([HERD_MODULES_STORE, CACHE_METADATA_STORE], "readonly");
+        const transaction = db.transaction([HERD_MODULES_STORE, PRODUCT_CATALOG_STORE, CACHE_METADATA_STORE], "readonly");
         return new Promise((resolve, reject) => {
             transaction.onerror = () => reject(transaction.error);
             const herdModulesStore = transaction.objectStore(HERD_MODULES_STORE);
+            const productCatalogStore = transaction.objectStore(PRODUCT_CATALOG_STORE);
             const metadataStore = transaction.objectStore(CACHE_METADATA_STORE);
             const metadataRequest = metadataStore.get("herd_modules");
             metadataRequest.onsuccess = () => {
@@ -210,10 +225,25 @@ export class ScoutCache {
                 }
                 const age = now - metadata.timestamp;
                 const isStale = age > metadata.ttl;
+                let herdModules = null;
+                let productCatalog = null;
+                const resolveWhenLoaded = () => {
+                    if (herdModules === null || productCatalog === null)
+                        return;
+                    resolve({
+                        data: {
+                            herd_modules: herdModules,
+                            product_catalog: productCatalog,
+                        },
+                        isStale,
+                        age,
+                        metadata,
+                    });
+                };
                 const getAllRequest = herdModulesStore.getAll();
                 getAllRequest.onsuccess = () => {
                     const cacheEntries = getAllRequest.result;
-                    const herdModules = cacheEntries
+                    herdModules = cacheEntries
                         .filter((entry) => entry.data &&
                         entry.data.herd &&
                         entry.data.herd.id != null &&
@@ -226,12 +256,16 @@ export class ScoutCache {
                     else {
                         this.stats.misses++;
                     }
-                    resolve({
-                        data: herdModules,
-                        isStale,
-                        age,
-                        metadata,
-                    });
+                    resolveWhenLoaded();
+                };
+                const catalogRequest = productCatalogStore.get(PRODUCT_CATALOG_KEY);
+                catalogRequest.onsuccess = () => {
+                    const entry = catalogRequest.result;
+                    productCatalog =
+                        entry?.dbVersion === DB_VERSION && entry.data
+                            ? entry.data
+                            : EMPTY_PRODUCT_CATALOG;
+                    resolveWhenLoaded();
                 };
             };
         });
@@ -295,9 +329,10 @@ export class ScoutCache {
         if (!userId && !this.dbName)
             return;
         const db = await this.getDatabase(userId);
-        const transaction = db.transaction([HERD_MODULES_STORE, CACHE_METADATA_STORE], "readwrite");
+        const transaction = db.transaction([HERD_MODULES_STORE, PRODUCT_CATALOG_STORE, CACHE_METADATA_STORE], "readwrite");
         const completion = transactionComplete(transaction);
         transaction.objectStore(HERD_MODULES_STORE).clear();
+        transaction.objectStore(PRODUCT_CATALOG_STORE).clear();
         transaction.objectStore(CACHE_METADATA_STORE).delete("herd_modules");
         await completion;
     }
@@ -308,7 +343,7 @@ export class ScoutCache {
         const result = await this.getHerdModules(userId);
         const totalRequests = this.stats.hits + this.stats.misses;
         const hitRate = totalRequests > 0 ? this.stats.hits / totalRequests : 0;
-        const size = result.data?.length || 0;
+        const size = result.data?.herd_modules.length || 0;
         return {
             size,
             lastUpdated: result.data ? Date.now() - result.age : 0,
@@ -334,7 +369,7 @@ export class ScoutCache {
             return { shouldRefresh: true, reason: "Force refresh requested" };
         }
         const result = await this.getHerdModules(userId);
-        if (!result.data || result.data.length === 0) {
+        if (!result.data || result.data.herd_modules.length === 0) {
             return { shouldRefresh: true, reason: "No cached data" };
         }
         if (!result.metadata ||
@@ -360,8 +395,8 @@ export class ScoutCache {
         try {
             console.log("[ScoutCache] Starting background cache preload...");
             const startTime = Date.now();
-            const herdModules = await loadFunction();
-            await this.setHerdModules(herdModules, ttlMs, undefined, userId);
+            const snapshot = await loadFunction();
+            await this.setHerdModules(snapshot, ttlMs, undefined, userId);
             const duration = Date.now() - startTime;
             console.log(`[ScoutCache] Background preload completed in ${duration}ms`);
         }

package/dist/helpers/eventMedia.d.ts

@@ -1,12 +1,14 @@
-import { ISignedMediaUrls } from "../types/db";
+import type { ISignedMediaUrls } from "../types/db";
 /** Events arrive as table rows and as the event_and_tags composite, so match on shape. */
-export type IEventMediaPaths = {
+export type IMediaPaths = {
     file_path?: string | null;
     thumbnail_file_path?: string | null;
     proxy_file_path?: string | null;
     media_url?: string | null;
 };
-/** Collect unique non-empty storage paths used for event media signing. */
-export declare function collectEventStoragePaths(events: Iterable<IEventMediaPaths | null | undefined>): string[];
+export type IEventMediaPaths = IMediaPaths;
+/** Collect unique non-empty original and derivative storage paths. */
+export declare function collectMediaStoragePaths(rows: Iterable<IMediaPaths | null | undefined>): string[];
+export declare const collectEventStoragePaths: typeof collectMediaStoragePaths;
 /** Attach signed URLs for original, thumbnail, and proxy storage paths. */
 export declare function withEventMediaUrls<T extends IEventMediaPaths>(event: T, urlMap: Map<string, string | null | undefined>): T & ISignedMediaUrls;

package/dist/helpers/eventMedia.js

@@ -1,13 +1,13 @@
 import { isNonEmptyStorageFilePath, signedUrlForPath } from "./storagePath";
-/** Collect unique non-empty storage paths used for event media signing. */
-export function collectEventStoragePaths(events) {
+/** Collect unique non-empty original and derivative storage paths. */
+export function collectMediaStoragePaths(rows) {
     const seen = new Set();
     const paths = [];
-    for (const event of events) {
+    for (const row of rows) {
         for (const path of [
-            event?.file_path,
-            event?.thumbnail_file_path,
-            event?.proxy_file_path,
+            row?.file_path,
+            row?.thumbnail_file_path,
+            row?.proxy_file_path,
         ]) {
             if (isNonEmptyStorageFilePath(path) && !seen.has(path)) {
                 seen.add(path);
@@ -17,6 +17,7 @@ export function collectEventStoragePaths(events) {
     }
     return paths;
 }
+export const collectEventStoragePaths = collectMediaStoragePaths;
 /** Attach signed URLs for original, thumbnail, and proxy storage paths. */
 export function withEventMediaUrls(event, urlMap) {
     return {

package/dist/helpers/gallery.d.ts

@@ -0,0 +1,4 @@
+import type { IGalleryItem } from "../types/db";
+import type { IWebResponseCompatible } from "../types/requests";
+import { type IGalleryItemsByIdsArgs } from "./gallery.queries";
+export declare function server_get_gallery_items_by_ids(args?: IGalleryItemsByIdsArgs): Promise<IWebResponseCompatible<IGalleryItem[]>>;

package/dist/helpers/gallery.js

@@ -0,0 +1,5 @@
+import { newServerClient } from "../supabase/server";
+import { get_gallery_items_by_ids_query, } from "./gallery.queries";
+export async function server_get_gallery_items_by_ids(args = {}) {
+    return get_gallery_items_by_ids_query(await newServerClient(), args);
+}

package/dist/helpers/gallery.queries.d.ts

@@ -0,0 +1,14 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { IGalleryItem } from "../types/db";
+import { type IWebResponseCompatible } from "../types/requests";
+import type { Database } from "../types/supabase";
+import { type GalleryItemKey } from "./galleryMedia";
+/** Missing, inactive, log-only, and pathless rows are omitted from the successful result. */
+export interface IGalleryItemsByIdsArgs {
+    eventIds?: readonly number[];
+    artifactIds?: readonly number[];
+    /** Optional mixed event/artifact confidence order; its ids are fetched automatically. */
+    rankedIds?: readonly GalleryItemKey[];
+}
+/** Hydrates ids into signed gallery items in one read, ordered as asked for. */
+export declare function get_gallery_items_by_ids_query(client: SupabaseClient<Database>, args?: IGalleryItemsByIdsArgs): Promise<IWebResponseCompatible<IGalleryItem[]>>;

package/dist/helpers/gallery.queries.js

@@ -0,0 +1,49 @@
+import { IWebResponse } from "../types/requests";
+import { rankGalleryItems } from "./galleryMedia";
+import { addGalleryMediaUrls } from "./media_urls";
+const normalizedIds = (ids = []) => ids.every((id) => Number.isSafeInteger(id) && id > 0)
+    ? [...new Set(ids)]
+    : null;
+const normalizedRanking = (items = []) => {
+    const unique = new Map();
+    for (const item of items) {
+        if ((item.feedType !== "event" && item.feedType !== "artifact") ||
+            !Number.isSafeInteger(item.id) ||
+            item.id <= 0) {
+            return null;
+        }
+        const key = `${item.feedType}:${item.id}`;
+        if (!unique.has(key))
+            unique.set(key, item);
+    }
+    return [...unique.values()];
+};
+/** Hydrates ids into signed gallery items in one read, ordered as asked for. */
+export async function get_gallery_items_by_ids_query(client, args = {}) {
+    const rankedIds = normalizedRanking(args.rankedIds);
+    const rankedEventIds = [];
+    const rankedArtifactIds = [];
+    rankedIds?.forEach(({ feedType, id }) => {
+        (feedType === "event" ? rankedEventIds : rankedArtifactIds).push(id);
+    });
+    const eventIds = normalizedIds([...(args.eventIds ?? []), ...rankedEventIds]);
+    const artifactIds = normalizedIds([
+        ...(args.artifactIds ?? []),
+        ...rankedArtifactIds,
+    ]);
+    if (!rankedIds || !eventIds || !artifactIds) {
+        return IWebResponse.error("Gallery item IDs must be positive safe integers with valid feed types").to_compatible();
+    }
+    if (eventIds.length === 0 && artifactIds.length === 0) {
+        return IWebResponse.success([]).to_compatible();
+    }
+    const { data, error } = await client.rpc("get_gallery_items_by_ids", {
+        event_ids: eventIds,
+        artifact_ids: artifactIds,
+    });
+    if (error) {
+        return IWebResponse.error(error.message).to_compatible();
+    }
+    const items = await addGalleryMediaUrls(client, data ?? []);
+    return IWebResponse.success(rankGalleryItems(items, eventIds, artifactIds, rankedIds)).to_compatible();
+}

package/dist/helpers/galleryMedia.d.ts

@@ -0,0 +1,9 @@
+import type { IGalleryItem, IGalleryItemRow } from "../types/db";
+export interface GalleryItemKey {
+    feedType: "event" | "artifact";
+    id: number;
+}
+/** Signs media the way events do, then adds the derived kind and readiness a tile renders. */
+export declare function withGalleryMediaUrls(item: IGalleryItemRow, urlMap: Map<string, string | null | undefined>): IGalleryItem;
+/** Uses a mixed ranking when supplied, otherwise each type's list position and then recency. */
+export declare function rankGalleryItems<T extends IGalleryItemRow>(items: T[], eventIds: readonly number[], artifactIds: readonly number[], rankedIds?: readonly GalleryItemKey[]): T[];

package/dist/helpers/galleryMedia.js

@@ -0,0 +1,41 @@
+import { withEventMediaUrls } from "./eventMedia";
+import { classifyMedia, mediaStatus } from "./mediaState";
+/** Signs media the way events do, then adds the derived kind and readiness a tile renders. */
+export function withGalleryMediaUrls(item, urlMap) {
+    const withUrls = withEventMediaUrls(item, urlMap);
+    return {
+        ...withUrls,
+        media_kind: classifyMedia(withUrls),
+        media_status: mediaStatus(withUrls),
+    };
+}
+/** Uses a mixed ranking when supplied, otherwise each type's list position and then recency. */
+export function rankGalleryItems(items, eventIds, artifactIds, rankedIds) {
+    const mixedRanks = new Map();
+    rankedIds?.forEach(({ feedType, id }, index) => {
+        const key = `${feedType}:${id}`;
+        if (!mixedRanks.has(key))
+            mixedRanks.set(key, index);
+    });
+    const rankOf = (ids) => {
+        const ranks = new Map();
+        ids.forEach((id, index) => {
+            if (!ranks.has(id))
+                ranks.set(id, index);
+        });
+        return ranks;
+    };
+    const eventRanks = rankOf(eventIds);
+    const artifactRanks = rankOf(artifactIds);
+    const rank = (item) => {
+        if (mixedRanks.size > 0) {
+            return (mixedRanks.get(`${item.feed_type}:${item.id}`) ??
+                Number.MAX_SAFE_INTEGER);
+        }
+        const ranks = item.feed_type === "artifact" ? artifactRanks : eventRanks;
+        const position = item.id == null ? undefined : ranks.get(item.id);
+        return position ?? Number.MAX_SAFE_INTEGER;
+    };
+    return [...items].sort((left, right) => rank(left) - rank(right) ||
+        (right.sort_ts ?? "").localeCompare(left.sort_ts ?? ""));
+}

package/dist/helpers/herd_modules.queries.js

@@ -5,13 +5,14 @@ import { get_devices_by_herd_query } from "./devices.queries";
 import { get_herds_with_location_query } from "./herds.queries";
 import { get_layers_by_herd_ids_query, get_plans_by_herd_ids_query, get_providers_by_herd_ids_query, } from "./herd_scoped.queries";
 import { get_parts_by_herd_ids } from "./parts";
+import { EMPTY_PRODUCT_CATALOG } from "./product_catalog";
 import { get_session_summaries_query } from "./session_summaries.queries";
 import { get_session_usage_over_time_by_herd_query } from "./sessions.queries";
 import { get_users_with_herd_access_batch_query } from "./users.queries";
 import { get_more_zones_and_actions_for_herd_query } from "./zones.queries";
-async function hashHerdModules(modules) {
+async function hashHerdModules(modules, productCatalog) {
     const stable = modules.map(({ timestamp_last_refreshed: _ts, ...rest }) => rest);
-    const bytes = new TextEncoder().encode(JSON.stringify(stable));
+    const bytes = new TextEncoder().encode(JSON.stringify({ modules: stable, product_catalog: productCatalog }));
     const digest = await crypto.subtle.digest("SHA-1", bytes);
     return Array.from(new Uint8Array(digest))
         .map((byte) => byte.toString(16).padStart(2, "0"))
@@ -25,6 +26,7 @@ export async function load_herd_modules_query(client) {
             status: EnumWebResponse.ERROR,
             msg: herdsResult.msg ?? "Failed to load herds",
             data: null,
+            product_catalog: EMPTY_PRODUCT_CATALOG,
             time_finished: Date.now(),
             time_sent: Date.now(),
             server_processing_time_ms: Date.now() - startTime,
@@ -39,10 +41,11 @@ export async function load_herd_modules_query(client) {
             status: EnumWebResponse.SUCCESS,
             msg: "No herds accessible",
             data: [],
+            product_catalog: EMPTY_PRODUCT_CATALOG,
             time_finished: endTime,
             time_sent: endTime,
             server_processing_time_ms: endTime - startTime,
-            content_hash: await hashHerdModules([]),
+            content_hash: await hashHerdModules([], EMPTY_PRODUCT_CATALOG),
         };
     }
     const herdIds = herds.map((herd) => herd.id);
@@ -53,19 +56,23 @@ export async function load_herd_modules_query(client) {
     }))));
     const grouped = (query) => query.then((response) => response.data ?? {}).catch(() => ({}));
     const unwrap = (response) => response.status === EnumWebResponse.SUCCESS ? response.data : null;
-    const [plansByHerd, layersByHerd, providersByHerd, usersByHerd, partsByDevice, devicesResults, zonesResults, summariesResults, usageResults,] = await Promise.all([
+    const [plansByHerd, layersByHerd, providersByHerd, usersByHerd, partsWithCatalog, devicesResults, zonesResults, summariesResults, usageResults,] = await Promise.all([
         grouped(get_plans_by_herd_ids_query(client, herdIds)),
         grouped(get_layers_by_herd_ids_query(client, herdIds)),
         grouped(get_providers_by_herd_ids_query(client, herdIds)),
         get_users_with_herd_access_batch_query(client, herdIds)
             .then(unwrap)
             .catch(() => null),
-        grouped(get_parts_by_herd_ids(client, herdIds)),
+        get_parts_by_herd_ids(client, herdIds)
+            .then(unwrap)
+            .catch(() => null),
         perHerd((id) => get_devices_by_herd_query(client, id)),
         perHerd((id) => get_more_zones_and_actions_for_herd_query(client, id, 0, 10)),
         perHerd((id) => get_session_summaries_query(client, { herd_id: id })),
         perHerd((id) => get_session_usage_over_time_by_herd_query(client, id)),
     ]);
+    const partsByDevice = partsWithCatalog?.parts_by_device ?? {};
+    const productCatalog = partsWithCatalog?.product_catalog ?? EMPTY_PRODUCT_CATALOG;
     const devicesByHerdIndex = devicesResults.map((response) => unwrap(response) ?? []);
     const allDevices = devicesByHerdIndex.flat();
     let apiKeysByDevice = {};
@@ -101,9 +108,10 @@ export async function load_herd_modules_query(client) {
         status: EnumWebResponse.SUCCESS,
         msg: "Herd modules loaded successfully",
         data: serialized_herd_modules,
+        product_catalog: productCatalog,
         time_finished: endTime,
         time_sent: endTime,
         server_processing_time_ms: endTime - startTime,
-        content_hash: await hashHerdModules(serialized_herd_modules),
+        content_hash: await hashHerdModules(serialized_herd_modules, productCatalog),
     };
 }

package/dist/helpers/mediaRows.d.ts

@@ -0,0 +1,12 @@
+export declare const normalizePageLimit: (limit: number | undefined) => number;
+/** Splits a page fetched with `limit + 1` rows; the extra row is the only proof of a next page. */
+export declare function splitOverFetchedPage<TRow>(rows: TRow[], limit: number): {
+    rows: TRow[];
+    hasMore: boolean;
+};
+/** Fields re-minted on every fetch, so they never indicate a changed row. */
+export declare const SIGNED_URL_FIELDS: readonly ["media_url", "thumbnail_url", "proxy_url"];
+/** Structural equality ignoring re-minted URLs and the readiness read off them. */
+export declare function rowsEqualIgnoringSignedUrls(left: unknown, right: unknown): boolean;
+/** Reuses `previous` — keeping identity for memoized consumers — with the URLs from `next`. */
+export declare function withRefreshedSignedUrls<TRow>(previous: TRow, next: TRow): TRow;

package/dist/helpers/mediaRows.js

@@ -0,0 +1,80 @@
+import { dequal } from "dequal";
+import { mediaStatus } from "./mediaState";
+export const normalizePageLimit = (limit) => {
+    if (limit !== undefined && Number.isSafeInteger(limit) && limit > 0) {
+        return limit;
+    }
+    return 20;
+};
+/** Splits a page fetched with `limit + 1` rows; the extra row is the only proof of a next page. */
+export function splitOverFetchedPage(rows, limit) {
+    const hasMore = rows.length > limit;
+    return { rows: hasMore ? rows.slice(0, limit) : rows, hasMore };
+}
+/** Fields re-minted on every fetch, so they never indicate a changed row. */
+export const SIGNED_URL_FIELDS = [
+    "media_url",
+    "thumbnail_url",
+    "proxy_url",
+];
+/** Feed rows nest their media under these keys. */
+const NESTED_MEDIA_FIELDS = ["event_data", "artifact_data"];
+/** Read off the signed URLs, so it is recomputed with them rather than compared. */
+const DERIVED_MEDIA_FIELD = "media_status";
+const REMINTED_FIELD_SET = new Set([
+    ...SIGNED_URL_FIELDS,
+    DERIVED_MEDIA_FIELD,
+]);
+const NESTED_MEDIA_FIELD_SET = new Set(NESTED_MEDIA_FIELDS);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const comparedKeys = (row) => Object.keys(row).filter((key) => !REMINTED_FIELD_SET.has(key));
+/** Structural equality ignoring re-minted URLs and the readiness read off them. */
+export function rowsEqualIgnoringSignedUrls(left, right) {
+    if (left === right)
+        return true;
+    if (!isRecord(left) || !isRecord(right))
+        return dequal(left, right);
+    const keys = comparedKeys(left);
+    if (keys.length !== comparedKeys(right).length)
+        return false;
+    // Only the nested media rows hold re-minted fields of their own; the rest compares whole.
+    return keys.every((key) => NESTED_MEDIA_FIELD_SET.has(key)
+        ? rowsEqualIgnoringSignedUrls(left[key], right[key])
+        : dequal(left[key], right[key]));
+}
+/** A failed re-mint reports null, which never displaces a link that still works. */
+const refreshedUrl = (previous, next) => next ?? previous;
+function signedUrlsDiffer(previous, next) {
+    return (SIGNED_URL_FIELDS.some((field) => refreshedUrl(previous[field], next[field]) !== previous[field]) ||
+        NESTED_MEDIA_FIELDS.some((field) => {
+            const previousNested = previous[field];
+            const nextNested = next[field];
+            return (isRecord(previousNested) &&
+                isRecord(nextNested) &&
+                signedUrlsDiffer(previousNested, nextNested));
+        }));
+}
+/** Reuses `previous` — keeping identity for memoized consumers — with the URLs from `next`. */
+export function withRefreshedSignedUrls(previous, next) {
+    if (!isRecord(previous) || !isRecord(next))
+        return previous;
+    if (!signedUrlsDiffer(previous, next))
+        return previous;
+    const merged = { ...previous };
+    for (const field of SIGNED_URL_FIELDS) {
+        if (field in previous || field in next) {
+            merged[field] = refreshedUrl(previous[field], next[field]);
+        }
+    }
+    for (const field of NESTED_MEDIA_FIELDS) {
+        const previousNested = previous[field];
+        const nextNested = next[field];
+        if (isRecord(previousNested) && isRecord(nextNested)) {
+            merged[field] = withRefreshedSignedUrls(previousNested, nextNested);
+        }
+    }
+    if (DERIVED_MEDIA_FIELD in merged) {
+        merged[DERIVED_MEDIA_FIELD] = mediaStatus(merged);
+    }
+    return merged;
+}

package/dist/helpers/mediaState.d.ts

@@ -0,0 +1,33 @@
+import { MediaKind, MediaStatus, MediaType } from "../types/db";
+/** Extensions classified by the client; image/video lists mirror the queue predicates. */
+export declare const VIDEO_FILE_EXTENSIONS: readonly ["mp4", "m4v", "webm", "mov", "mkv", "avi"];
+export declare const IMAGE_FILE_EXTENSIONS: readonly ["jpg", "jpeg", "png", "gif", "webp", "bmp"];
+export declare const AUDIO_FILE_EXTENSIONS: readonly ["wav", "mp3", "m4a", "aac", "flac", "ogg"];
+/** Lowercased extension of a storage path or URL, or null when there is none. */
+export declare function mediaFileExtension(filePath: string | null | undefined): string | null;
+export interface MediaClassificationInput {
+    /** Storage path, or a legacy absolute media URL. */
+    file_path?: string | null;
+    media_url?: string | null;
+    /** Events carry the media_type enum. */
+    media_type?: MediaType | null;
+    /** Artifacts carry a modality, which is `video` for video captures and `sys_logs` etc. for logs. */
+    modality?: string | null;
+}
+/** One classifier for events and artifacts; a recognized extension wins over the stored type. */
+export declare function classifyMedia(row: MediaClassificationInput): MediaKind;
+export declare const isVideoMedia: (row: MediaClassificationInput) => boolean;
+export interface MediaStatusInput extends MediaClassificationInput {
+    thumbnail_file_path?: string | null;
+    thumbnail_generated_at?: string | null;
+    proxy_file_path?: string | null;
+    proxy_generated_at?: string | null;
+    processing_blocked_at?: string | null;
+    /** Signed URLs, as attached by the media helpers. */
+    thumbnail_url?: string | null;
+    proxy_url?: string | null;
+}
+/** Readiness of image/video derivatives or the original for media without derivatives. */
+export declare function mediaStatus(row: MediaStatusInput): MediaStatus;
+/** Readiness of the original media itself, ignoring derivatives. */
+export declare function originalMediaStatus(row: Pick<MediaStatusInput, "file_path" | "media_url" | "processing_blocked_at">): MediaStatus;