@adventurelabs/scout-core 2.0.18 → 2.1.0

package/dist/hooks/useScoutRealtimeBroadcast.js

@@ -10,18 +10,27 @@ const OPERATIONS = {
 };
 const DEFAULT_BACKOFF_INITIAL_MS = 1000;
 const DEFAULT_BACKOFF_MAX_MS = 60000;
+/** A channel still joining reports its own outcome, so only a dead one needs a rejoin. */
+const HEALTHY_CHANNEL_STATES = new Set([
+    "joined",
+    "joining",
+]);
 function isRealtimeAuthError(error) {
     const message = error?.message ?? "";
     return /unauthorized|permission/i.test(message);
 }
+/** Jittered, so a server blip does not bring every topic and every client back in lockstep. */
 function backoffDelayMs(attempt, initialMs, maxMs) {
-    return Math.min(maxMs, initialMs * 2 ** Math.max(0, attempt));
+    const ceiling = Math.min(maxMs, initialMs * 2 ** Math.max(0, attempt));
+    return ceiling * (0.5 + Math.random() * 0.5);
 }
 export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, rowFilter) {
-    const { authErrorRetry = "stop", backoffInitialMs = DEFAULT_BACKOFF_INITIAL_MS, backoffMaxMs = DEFAULT_BACKOFF_MAX_MS, backoffMaxAttempts = Number.POSITIVE_INFINITY, } = options;
+    const { authErrorRetry = "stop", backoffInitialMs = DEFAULT_BACKOFF_INITIAL_MS, backoffMaxMs = DEFAULT_BACKOFF_MAX_MS, backoffMaxAttempts = Number.POSITIVE_INFINITY, onMissedUpdates, recoverOnFocus = true, } = options;
     const [latestUpdate, setLatestUpdate] = useState(null);
     const rowFilterRef = useRef(rowFilter);
     rowFilterRef.current = rowFilter;
+    const onMissedUpdatesRef = useRef(onMissedUpdates);
+    onMissedUpdatesRef.current = onMissedUpdates;
     const subscribedTopics = useAuthorizedRealtimeTopics(topics);
     const clearLatestUpdate = useCallback(() => setLatestUpdate(null), []);
     useEffect(() => {
@@ -31,7 +40,12 @@ export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, r
         let cancelled = false;
         const channels = new Map();
         const authAttempts = new Map();
+        const dropAttempts = new Map();
         const blockedTopics = new Set();
+        /** Topics being rejoined after a drop, so their next join reports missed updates. */
+        const droppedTopics = new Set();
+        /** Topics a channel already exists for, which is what tells a drop from a first join. */
+        const startedTopics = new Set();
         const retryTimers = new Map();
         const removeTopicChannel = (topic) => {
             const channel = channels.get(topic);
@@ -40,13 +54,13 @@ export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, r
             channels.delete(topic);
             void scoutSupabase.removeChannel(channel);
         };
-        const scheduleRetry = (topic) => {
-            if (authErrorRetry !== "backoff" || cancelled)
+        const scheduleRejoin = (topic, attempts) => {
+            if (cancelled)
                 return;
-            const attempt = authAttempts.get(topic) ?? 0;
+            const attempt = attempts.get(topic) ?? 0;
             if (attempt >= backoffMaxAttempts)
                 return;
-            authAttempts.set(topic, attempt + 1);
+            attempts.set(topic, attempt + 1);
             const existing = retryTimers.get(topic);
             if (existing)
                 clearTimeout(existing);
@@ -71,20 +85,39 @@ export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, r
                 setLatestUpdate({ data: row, operation, table: change.table });
             });
             channels.set(topic, channel);
+            startedTopics.add(topic);
             channel.subscribe((status, error) => {
                 if (status === "SUBSCRIBED") {
                     authAttempts.delete(topic);
+                    dropAttempts.delete(topic);
                     blockedTopics.delete(topic);
+                    if (droppedTopics.delete(topic))
+                        onMissedUpdatesRef.current?.();
                     return;
                 }
-                if (status !== "CHANNEL_ERROR")
+                // A status for a channel we replaced or tore down says nothing about the topic now.
+                if (cancelled || channels.get(topic) !== channel)
                     return;
-                console.warn(`[scout-core realtime] 🟡 ${topic} unavailable`, error?.message ?? "");
-                if (!isRealtimeAuthError(error) || cancelled)
+                if (status === "CHANNEL_ERROR" && isRealtimeAuthError(error)) {
+                    console.warn(`[scout-core realtime] 🟡 ${topic} unavailable`, error?.message ?? "");
+                    blockedTopics.add(topic);
+                    removeTopicChannel(topic);
+                    // Rows published while unauthorized are gone, so a rejoin still owes a refetch.
+                    droppedTopics.add(topic);
+                    if (authErrorRetry === "backoff")
+                        scheduleRejoin(topic, authAttempts);
                     return;
-                blockedTopics.add(topic);
+                }
+                if (status !== "CHANNEL_ERROR" &&
+                    status !== "CLOSED" &&
+                    status !== "TIMED_OUT") {
+                    return;
+                }
+                // Rejoining is the only way to see rows published during a transport drop.
+                console.warn(`[scout-core realtime] 🟡 ${topic} dropped (${status})`, error?.message ?? "");
                 removeTopicChannel(topic);
-                scheduleRetry(topic);
+                droppedTopics.add(topic);
+                scheduleRejoin(topic, dropAttempts);
             });
         };
         async function authenticateAndJoin(topicsToJoin) {
@@ -116,10 +149,41 @@ export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, r
                 retryBlockedTopics();
             }
         });
+        /** A socket that died while hidden reports nothing, so returning rejoins dead topics. */
+        const recoverDroppedTopics = () => {
+            const offline = typeof navigator !== "undefined" && !navigator.onLine;
+            if (cancelled || offline)
+                return;
+            const toRejoin = subscribedTopics.filter((topic) => startedTopics.has(topic) &&
+                !blockedTopics.has(topic) &&
+                !HEALTHY_CHANNEL_STATES.has(channels.get(topic)?.state ?? "") &&
+                !retryTimers.has(topic));
+            if (toRejoin.length === 0)
+                return;
+            toRejoin.forEach((topic) => {
+                removeTopicChannel(topic);
+                droppedTopics.add(topic);
+                dropAttempts.delete(topic);
+            });
+            void authenticateAndJoin(toRejoin);
+        };
+        const handleVisibilityChange = () => {
+            if (document.visibilityState === "visible")
+                recoverDroppedTopics();
+        };
+        const listeningForFocus = recoverOnFocus && typeof window !== "undefined";
+        if (listeningForFocus) {
+            window.addEventListener("online", recoverDroppedTopics);
+            document.addEventListener("visibilitychange", handleVisibilityChange);
+        }
         void authenticateAndJoin(subscribedTopics);
         return () => {
             cancelled = true;
             unsubscribeAuth();
+            if (listeningForFocus) {
+                window.removeEventListener("online", recoverDroppedTopics);
+                document.removeEventListener("visibilitychange", handleVisibilityChange);
+            }
             retryTimers.forEach((timer) => clearTimeout(timer));
             retryTimers.clear();
             channels.forEach((channel) => {
@@ -134,6 +198,7 @@ export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, r
         backoffInitialMs,
         backoffMaxMs,
         backoffMaxAttempts,
+        recoverOnFocus,
     ]);
     return [latestUpdate, clearLatestUpdate];
 }

package/dist/hooks/useScoutRefresh.js

@@ -100,7 +100,7 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
         const isCurrent = () => refreshIdRef.current === refreshId;
         const startTime = Date.now();
         const isOffline = typeof navigator === "undefined" || !navigator.onLine;
-        let cachedHerdModules = null;
+        let cachedSnapshot = null;
         let cacheReady = false;
         const complete = (loadingState) => {
             if (!isCurrent())
@@ -114,7 +114,7 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
             if (activeUserIdRef.current &&
                 activeUserIdRef.current !== userId) {
                 resetClientState();
-                cachedHerdModules = null;
+                cachedSnapshot = null;
             }
             activeUserIdRef.current = userId;
         };
@@ -141,7 +141,7 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
                 if (cacheResult.data === null) {
                     return;
                 }
-                cachedHerdModules = cacheResult.data;
+                cachedSnapshot = cacheResult.data;
                 dispatch(setDataSource(EnumDataSource.CACHE));
                 dispatch(setDataSourceInfo({
                     source: EnumDataSource.CACHE,
@@ -149,7 +149,10 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
                     cacheAge: cacheResult.age,
                     isStale: cacheResult.isStale,
                 }));
-                dispatchInTransition(dispatch, setHerdModules({ modules: cachedHerdModules }));
+                dispatchInTransition(dispatch, setHerdModules({
+                    modules: cachedSnapshot.herd_modules,
+                    productCatalog: cachedSnapshot.product_catalog,
+                }));
                 dispatch(setHerdModulesLoadingState(EnumHerdModulesLoadingState.SUCCESSFULLY_LOADED));
             }
             catch (cacheError) {
@@ -188,14 +191,14 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
                     dispatch(setUserApiDuration(sessionDuration));
                     dispatchInTransition(dispatch, setUser(sessionUser));
                 }
-                if (cachedHerdModules === null) {
+                if (cachedSnapshot === null) {
                     dispatch(setDataSource(EnumDataSource.UNKNOWN));
                     dispatch(setDataSourceInfo({
                         source: EnumDataSource.UNKNOWN,
                         timestamp: Date.now(),
                     }));
                 }
-                complete(cachedHerdModules !== null
+                complete(cachedSnapshot !== null
                     ? EnumHerdModulesLoadingState.SUCCESSFULLY_LOADED
                     : EnumHerdModulesLoadingState.UNSUCCESSFULLY_LOADED);
                 return;
@@ -226,16 +229,19 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
                 !Array.isArray(herdModulesResponse.data)) {
                 throw new Error("Invalid herd modules response");
             }
-            const freshHerdModules = herdModulesResponse.data;
+            const freshSnapshot = {
+                herd_modules: herdModulesResponse.data,
+                product_catalog: herdModulesResponse.product_catalog,
+            };
             const freshContentHash = herdModulesResponse.content_hash;
             if (cacheReady) {
                 try {
-                    await scoutCache.setHerdModules(freshHerdModules, cacheTtlMs, freshContentHash, userId);
+                    await scoutCache.setHerdModules(freshSnapshot, cacheTtlMs, freshContentHash, userId);
                 }
                 catch (cacheError) {
                     console.warn("[useScoutRefresh] Cache save failed:", cacheError);
                     await recoverScoutCache(cacheError, "cache save", userId, async () => {
-                        await scoutCache.setHerdModules(freshHerdModules, cacheTtlMs, freshContentHash, userId);
+                        await scoutCache.setHerdModules(freshSnapshot, cacheTtlMs, freshContentHash, userId);
                     });
                 }
             }
@@ -248,7 +254,8 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
                 timestamp: Date.now(),
             }));
             dispatchInTransition(dispatch, setHerdModules({
-                modules: freshHerdModules,
+                modules: freshSnapshot.herd_modules,
+                productCatalog: freshSnapshot.product_catalog,
                 contentHash: freshContentHash,
             }));
             const dataProcessingDuration = Date.now() - dataProcessingStartTime;
@@ -259,7 +266,7 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
             if (!isCurrent())
                 return;
             console.error("Error refreshing scout data:", error);
-            if (cachedHerdModules !== null) {
+            if (cachedSnapshot !== null) {
                 dispatch(setDataSource(EnumDataSource.CACHE));
                 complete(EnumHerdModulesLoadingState.SUCCESSFULLY_LOADED);
             }

package/dist/server/index.d.ts

@@ -6,9 +6,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";
@@ -28,6 +31,8 @@ export { server_create_document_template as create_document_template, server_get
 export { server_search_embeddings_vertex_multimodal_001 as search_embeddings_vertex_multimodal_001 } from "../helpers/embeddings";
 export { server_delete_event as delete_event, server_get_event_by_id as get_event_by_id, server_get_total_events_by_herd as get_total_events_by_herd, server_insert_event as insert_event, server_match_events_by_vertex_embedding as match_events_by_vertex_embedding, server_update_event as update_event, } from "../helpers/events";
 export { server_create_battery_cycle_count as create_battery_cycle_count, server_delete_battery_cycle_count as delete_battery_cycle_count, server_get_battery_cycle_counts_by_battery_id as get_battery_cycle_counts_by_battery_id, server_update_battery_cycle_count as update_battery_cycle_count, } from "../helpers/battery_cycle_counts";
+export { server_get_gallery_items_by_ids as get_gallery_items_by_ids } from "../helpers/gallery";
+export type { IGalleryItemsByIdsArgs } from "../helpers/gallery.queries";
 export { server_get_health_metrics as get_health_metrics, server_get_health_metrics_summary as get_health_metrics_summary, } from "../helpers/health_metrics";
 export { server_get_herd_media_usage as get_herd_media_usage, server_get_latest_herd_media_usage as get_latest_herd_media_usage, } from "../helpers/herd_media_usage";
 export { server_check_device_online_status as check_device_online_status, server_get_heartbeats_by_device as get_heartbeats_by_device, server_get_last_heartbeat_by_device as get_last_heartbeat_by_device, } from "../helpers/heartbeats";

package/dist/server/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";
@@ -28,6 +31,7 @@ export { server_create_document_template as create_document_template, server_get
 export { server_search_embeddings_vertex_multimodal_001 as search_embeddings_vertex_multimodal_001 } from "../helpers/embeddings";
 export { server_delete_event as delete_event, server_get_event_by_id as get_event_by_id, server_get_total_events_by_herd as get_total_events_by_herd, server_insert_event as insert_event, server_match_events_by_vertex_embedding as match_events_by_vertex_embedding, server_update_event as update_event, } from "../helpers/events";
 export { server_create_battery_cycle_count as create_battery_cycle_count, server_delete_battery_cycle_count as delete_battery_cycle_count, server_get_battery_cycle_counts_by_battery_id as get_battery_cycle_counts_by_battery_id, server_update_battery_cycle_count as update_battery_cycle_count, } from "../helpers/battery_cycle_counts";
+export { server_get_gallery_items_by_ids as get_gallery_items_by_ids } from "../helpers/gallery";
 export { server_get_health_metrics as get_health_metrics, server_get_health_metrics_summary as get_health_metrics_summary, } from "../helpers/health_metrics";
 export { server_get_herd_media_usage as get_herd_media_usage, server_get_latest_herd_media_usage as get_latest_herd_media_usage, } from "../helpers/herd_media_usage";
 export { server_check_device_online_status as check_device_online_status, server_get_heartbeats_by_device as get_heartbeats_by_device, server_get_last_heartbeat_by_device as get_last_heartbeat_by_device, } from "../helpers/heartbeats";