@adventurelabs/scout-core 1.5.4 → 2.0.0

package/dist/hooks/useScoutRealtimeBroadcast.js

@@ -1,6 +1,7 @@
 "use client";
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { EnumRealtimeOperation } from "../types/realtime";
+import { refreshRealtimeAuth, subscribeToSupabaseAuth, } from "../helpers/supabase_auth";
 import { useAuthorizedRealtimeTopics } from "./useAuthorizedRealtimeTopics";
 const OPERATIONS = {
     INSERT: EnumRealtimeOperation.INSERT,
@@ -19,6 +20,8 @@ function backoffDelayMs(attempt, initialMs, maxMs) {
 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 [latestUpdate, setLatestUpdate] = useState(null);
+    const rowFilterRef = useRef(rowFilter);
+    rowFilterRef.current = rowFilter;
     const subscribedTopics = useAuthorizedRealtimeTopics(topics);
     const clearLatestUpdate = useCallback(() => setLatestUpdate(null), []);
     useEffect(() => {
@@ -63,7 +66,7 @@ export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, r
                 const row = change.record ?? change.old_record;
                 if (operation === undefined || !row)
                     return;
-                if (rowFilter && !rowFilter(row))
+                if (rowFilterRef.current && !rowFilterRef.current(row))
                     return;
                 setLatestUpdate({ data: row, operation, table: change.table });
             });
@@ -86,7 +89,7 @@ export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, r
         };
         async function authenticateAndJoin(topicsToJoin) {
             try {
-                await scoutSupabase.realtime.setAuth();
+                await refreshRealtimeAuth(scoutSupabase);
             }
             catch (error) {
                 console.warn("[scout-core realtime] failed to refresh auth", error);
@@ -106,7 +109,7 @@ export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, r
             if (topicsToRetry.length > 0)
                 void authenticateAndJoin(topicsToRetry);
         };
-        const { data: { subscription: authSubscription }, } = scoutSupabase.auth.onAuthStateChange((event) => {
+        const unsubscribeAuth = subscribeToSupabaseAuth(scoutSupabase, (event) => {
             if (event === "INITIAL_SESSION" ||
                 event === "SIGNED_IN" ||
                 event === "TOKEN_REFRESHED") {
@@ -116,7 +119,7 @@ export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, r
         void authenticateAndJoin(subscribedTopics);
         return () => {
             cancelled = true;
-            authSubscription.unsubscribe();
+            unsubscribeAuth();
             retryTimers.forEach((timer) => clearTimeout(timer));
             retryTimers.clear();
             channels.forEach((channel) => {
@@ -131,7 +134,6 @@ export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, r
         backoffInitialMs,
         backoffMaxMs,
         backoffMaxAttempts,
-        rowFilter,
     ]);
     return [latestUpdate, clearLatestUpdate];
 }

package/dist/hooks/useScoutRealtimeDocuments.js

@@ -13,12 +13,13 @@ const ALL_DOCUMENT_CHANNELS = [
 export function useScoutRealtimeDocuments(scoutSupabase, channels = ALL_DOCUMENT_CHANNELS, options) {
     const activeHerdId = useSelector((state) => state.scout.active_herd_id);
     const userId = useSelector((state) => state.scout.user?.id ?? null);
-    const topics = useMemo(() => channels.flatMap((channel) => {
+    const channelsKey = channels.join("|");
+    const topics = useMemo(() => channelsKey.split("|").flatMap((channel) => {
         if (channel === "product")
             return ["product_documents_changes"];
         if (channel === "own")
             return userId ? [`user_${userId}-documents`] : [];
         return activeHerdId ? [`${activeHerdId}-${channel}_documents`] : [];
-    }), [channels, activeHerdId, userId]);
+    }), [channelsKey, activeHerdId, userId]);
     return useScoutRealtimeBroadcast(scoutSupabase, topics, options);
 }

package/dist/hooks/useScoutRefresh.d.ts

@@ -1,5 +1,5 @@
-import { SupabaseClient } from "@supabase/supabase-js";
-import { Database } from "../types/supabase";
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { Database } from "../types/supabase";
 export interface UseScoutRefreshOptions {
     supabase?: SupabaseClient<Database>;
     autoRefresh?: boolean;
@@ -8,32 +8,16 @@ export interface UseScoutRefreshOptions {
     cacheTtlMs?: number;
     onlineRefetchMinIntervalMs?: number;
 }
+export interface ScoutRefreshRequest {
+    force?: boolean;
+}
 /**
- * Hook for refreshing scout data with detailed timing measurements and cache-first loading
- *
- * @param options - Configuration options for the refresh behavior
- * @param options.autoRefresh - Whether to automatically refresh on mount (default: true)
- * @param options.onRefreshComplete - Callback function called when refresh completes
- * @param options.cacheFirst - Whether to load from cache first, then refresh (default: true)
- * @param options.cacheTtlMs - Cache time-to-live in milliseconds (default: 24 hours)
- * @param options.onlineRefetchMinIntervalMs - Min ms since last refresh before refetch on "online" (default: 15s)
- * @param options.supabase - Optional shared browser client; when omitted, the hook creates its own via `createBrowserClient`
- *
- * @returns Object containing:
- * - handleRefresh: Function to manually trigger a refresh
- * - clearCache: Function to clear the cache
- *
- * @example
- * ```tsx
- * const { handleRefresh, clearCache } = useScoutRefresh({
- *   cacheFirst: true,
- *   cacheTtlMs: 10 * 60 * 1000 // 10 minutes
- * });
+ * Refreshes Scout state from cache and the API.
  *
- * // Timing stats are available in Redux store via selectors
- * ```
+ * Manual refreshes force an API request by default. Automatic mount refreshes
+ * finish from a fresh cache without requesting the API.
  */
 export declare function useScoutRefresh(options?: UseScoutRefreshOptions): {
-    handleRefresh: () => Promise<void>;
+    handleRefresh: ({ force }?: ScoutRefreshRequest) => Promise<void>;
     clearCache: () => Promise<void>;
 };

package/dist/hooks/useScoutRefresh.js

@@ -1,93 +1,60 @@
-import { useEffect, useCallback, useRef, useMemo, startTransition } from "react";
+"use client";
+import { useEffect, useCallback, useRef, useMemo, startTransition, } from "react";
 import { useAppDispatch } from "../store/hooks";
 import { EnumScoutStateStatus, setHerdModules, setStatus, setHerdModulesLoadingState, setHerdModulesLoadedInMs, setHerdModulesApiServerProcessingDuration, setHerdModulesApiTotalRequestDuration, setUserApiDuration, setDataProcessingDuration, setCacheLoadDuration, setUser, setDataSource, setDataSourceInfo, } from "../store/scout";
-import { EnumHerdModulesLoadingState } from "../types/herd_module";
-import { server_load_herd_modules } from "../helpers/herds";
+import { EnumHerdModulesLoadingState, } from "../types/herd_module";
+import { load_herd_modules_query } from "../helpers/herd_modules.queries";
 import { scoutCache } from "../helpers/cache";
 import { EnumDataSource } from "../types/data_source";
 import { EnumWebResponse } from "../types/requests";
-import { createBrowserClient } from "@supabase/ssr";
+import { createScoutBrowserClient } from "../supabase/client";
 function dispatchInTransition(dispatch, action) {
     startTransition(() => {
         dispatch(action);
     });
 }
 /**
- * Hook for refreshing scout data with detailed timing measurements and cache-first loading
+ * Refreshes Scout state from cache and the API.
  *
- * @param options - Configuration options for the refresh behavior
- * @param options.autoRefresh - Whether to automatically refresh on mount (default: true)
- * @param options.onRefreshComplete - Callback function called when refresh completes
- * @param options.cacheFirst - Whether to load from cache first, then refresh (default: true)
- * @param options.cacheTtlMs - Cache time-to-live in milliseconds (default: 24 hours)
- * @param options.onlineRefetchMinIntervalMs - Min ms since last refresh before refetch on "online" (default: 15s)
- * @param options.supabase - Optional shared browser client; when omitted, the hook creates its own via `createBrowserClient`
- *
- * @returns Object containing:
- * - handleRefresh: Function to manually trigger a refresh
- * - clearCache: Function to clear the cache
- *
- * @example
- * ```tsx
- * const { handleRefresh, clearCache } = useScoutRefresh({
- *   cacheFirst: true,
- *   cacheTtlMs: 10 * 60 * 1000 // 10 minutes
- * });
- *
- * // Timing stats are available in Redux store via selectors
- * ```
+ * Manual refreshes force an API request by default. Automatic mount refreshes
+ * finish from a fresh cache without requesting the API.
  */
 export function useScoutRefresh(options = {}) {
-    const { supabase: supabaseOption, autoRefresh = true, onRefreshComplete, cacheFirst = true, cacheTtlMs = 24 * 60 * 60 * 1000, // 24 hours default (1 day)
-    onlineRefetchMinIntervalMs = 15 * 1000, // 15 seconds
-     } = options;
+    const { supabase: supabaseOption, autoRefresh = true, onRefreshComplete, cacheFirst = true, cacheTtlMs = 24 * 60 * 60 * 1000, onlineRefetchMinIntervalMs = 15 * 1000, } = options;
     const dispatch = useAppDispatch();
     const refreshInProgressRef = useRef(false);
     const lastQueryAtRef = useRef(0);
+    const onRefreshCompleteRef = useRef(onRefreshComplete);
+    useEffect(() => {
+        onRefreshCompleteRef.current = onRefreshComplete;
+    }, [onRefreshComplete]);
     const supabase = useMemo(() => {
         if (supabaseOption) {
             return supabaseOption;
         }
-        return createBrowserClient(process.env.NEXT_PUBLIC_SUPABASE_URL || "", process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY || "");
+        return createScoutBrowserClient();
     }, [supabaseOption]);
-    // Refs to store timing measurements
-    const timingRefs = useRef({
-        startTime: 0,
-        herdModulesDuration: 0,
-        userApiDuration: 0,
-        dataProcessingDuration: 0,
-        cacheLoadDuration: 0,
-        cacheSaveDuration: 0,
-    });
-    // Helper function for deep comparison of objects
-    // Helper function to handle IndexedDB errors - memoized for stability
     const handleIndexedDbError = useCallback(async (error, operation, retryFn) => {
         if (error instanceof Error &&
             (error.message.includes("object store") ||
                 error.message.includes("NotFoundError"))) {
-            console.log(`[useScoutRefresh] Attempting database reset due to ${operation} error...`);
             try {
                 await scoutCache.resetDatabase();
-                console.log("[useScoutRefresh] Database reset successful");
                 if (retryFn) {
                     await retryFn();
-                    console.log(`[useScoutRefresh] ${operation} successful after database reset`);
                 }
             }
             catch (resetError) {
-                console.error(`[useScoutRefresh] Database reset and retry failed:`, resetError);
+                console.error(`[useScoutRefresh] ${operation} reset and retry failed:`, resetError);
             }
         }
     }, []);
-    const handleRefresh = useCallback(async () => {
-        // Prevent concurrent refresh calls
+    const handleRefresh = useCallback(async ({ force = true } = {}) => {
         if (refreshInProgressRef.current) {
-            console.warn("[useScoutRefresh] Refresh already in progress, skipping");
             return;
         }
         refreshInProgressRef.current = true;
         const startTime = Date.now();
-        timingRefs.current.startTime = startTime;
         const isOffline = typeof navigator === "undefined" || !navigator.onLine;
         const fetchUserWithOneRetry = async () => {
             const startTotal = Date.now();
@@ -99,7 +66,6 @@ export function useScoutRefresh(options = {}) {
                         throw new Error("Invalid user response");
                     }
                     const totalMs = Date.now() - startTotal;
-                    timingRefs.current.userApiDuration = totalMs;
                     dispatch(setUserApiDuration(totalMs));
                     dispatchInTransition(dispatch, setUser(data.user));
                     return data.user;
@@ -110,47 +76,20 @@ export function useScoutRefresh(options = {}) {
             }
             throw lastError;
         };
-        const fetchUserWithOneRetryBackground = async () => {
-            const startTotal = Date.now();
-            for (let attempt = 0; attempt < 2; attempt++) {
-                try {
-                    const { data } = await supabase.auth.getUser();
-                    if (data.user) {
-                        const totalMs = Date.now() - startTotal;
-                        timingRefs.current.userApiDuration = totalMs;
-                        dispatch(setUserApiDuration(totalMs));
-                        dispatchInTransition(dispatch, setUser(data.user));
-                        return data.user;
-                    }
-                }
-                catch {
-                    // retry once
-                }
-            }
-            const totalMs = Date.now() - startTotal;
-            timingRefs.current.userApiDuration = totalMs;
-            dispatch(setUserApiDuration(totalMs));
-            return null;
-        };
         try {
             dispatch(setStatus(EnumScoutStateStatus.LOADING));
             dispatch(setHerdModulesLoadingState(EnumHerdModulesLoadingState.LOADING));
             let cachedHerdModules = null;
             let cachedContentHash;
-            let cacheLoadDuration = 0;
-            // Step 1: Load from cache first if enabled
             if (cacheFirst) {
                 const cacheStartTime = Date.now();
                 try {
                     const cacheResult = await scoutCache.getHerdModules();
-                    cacheLoadDuration = Date.now() - cacheStartTime;
-                    timingRefs.current.cacheLoadDuration = cacheLoadDuration;
+                    const cacheLoadDuration = Date.now() - cacheStartTime;
                     dispatch(setCacheLoadDuration(cacheLoadDuration));
                     if (cacheResult.data && cacheResult.data.length > 0) {
                         cachedHerdModules = cacheResult.data;
                         cachedContentHash = cacheResult.metadata?.etag;
-                        console.log(`[useScoutRefresh] Loaded ${cachedHerdModules.length} herd modules from cache in ${cacheLoadDuration}ms (age: ${Math.round(cacheResult.age / 1000)}s, stale: ${cacheResult.isStale})`);
-                        // Set data source to CACHE initially
                         dispatch(setDataSource(EnumDataSource.CACHE));
                         dispatch(setDataSourceInfo({
                             source: EnumDataSource.CACHE,
@@ -158,98 +97,25 @@ export function useScoutRefresh(options = {}) {
                             cacheAge: cacheResult.age,
                             isStale: cacheResult.isStale,
                         }));
-                        // Update the store with cached data
-                        console.log(`[useScoutRefresh] Updating store with cached herd modules`);
                         dispatchInTransition(dispatch, setHerdModules({
                             modules: cachedHerdModules,
                             contentHash: cachedContentHash,
                         }));
                         dispatch(setHerdModulesLoadingState(EnumHerdModulesLoadingState.SUCCESSFULLY_LOADED));
-                        // If cache is fresh, we still background fetch but don't wait (only when online)
-                        if (!cacheResult.isStale) {
-                            if (!isOffline) {
-                                // Background fetch fresh data without blocking
-                                (async () => {
-                                    try {
-                                        const userPromise = fetchUserWithOneRetryBackground();
-                                        let backgroundHerdModulesResult;
-                                        try {
-                                            const start = Date.now();
-                                            const result = await server_load_herd_modules();
-                                            const totalDuration = Date.now() - start;
-                                            const serverDuration = result.server_processing_time_ms || totalDuration;
-                                            const clientOverhead = totalDuration - serverDuration;
-                                            console.log(`[useScoutRefresh] Background API timing breakdown:`);
-                                            console.log(`  - Server processing: ${serverDuration}ms`);
-                                            console.log(`  - Client overhead: ${clientOverhead}ms`);
-                                            console.log(`  - Total request: ${totalDuration}ms`);
-                                            timingRefs.current.herdModulesDuration = serverDuration;
-                                            dispatch(setHerdModulesApiServerProcessingDuration(serverDuration));
-                                            dispatch(setHerdModulesApiTotalRequestDuration(totalDuration));
-                                            backgroundHerdModulesResult = result;
-                                        }
-                                        catch (e) {
-                                            await userPromise.catch(() => { });
-                                            throw e;
-                                        }
-                                        const backgroundUserResult = await userPromise;
-                                        // Validate background responses
-                                        if (backgroundHerdModulesResult.status ===
-                                            EnumWebResponse.SUCCESS &&
-                                            Array.isArray(backgroundHerdModulesResult.data) &&
-                                            backgroundUserResult) {
-                                            const backgroundContentHash = backgroundHerdModulesResult.content_hash;
-                                            // Update cache with fresh data
-                                            try {
-                                                await scoutCache.setHerdModules(backgroundHerdModulesResult.data, cacheTtlMs, backgroundContentHash);
-                                            }
-                                            catch (cacheError) {
-                                                console.warn("[useScoutRefresh] Background cache save failed:", cacheError);
-                                                await handleIndexedDbError(cacheError, "background cache save", async () => {
-                                                    if (backgroundHerdModulesResult.data) {
-                                                        await scoutCache.setHerdModules(backgroundHerdModulesResult.data, cacheTtlMs, backgroundContentHash);
-                                                    }
-                                                });
-                                            }
-                                            // Update store with fresh data from background request
-                                            console.log(`[useScoutRefresh] Updating store with background herd modules`);
-                                            dispatchInTransition(dispatch, setHerdModules({
-                                                modules: backgroundHerdModulesResult.data,
-                                                contentHash: backgroundContentHash,
-                                            }));
-                                            // Update data source to DATABASE
-                                            dispatch(setDataSource(EnumDataSource.DATABASE));
-                                            dispatch(setDataSourceInfo({
-                                                source: EnumDataSource.DATABASE,
-                                                timestamp: Date.now(),
-                                            }));
-                                        }
-                                        else {
-                                            console.warn("[useScoutRefresh] Background fetch returned invalid data");
-                                        }
-                                    }
-                                    catch (backgroundError) {
-                                        console.warn("[useScoutRefresh] Background fetch failed:", backgroundError);
-                                    }
-                                })();
-                            }
+                        if (!cacheResult.isStale && !force) {
                             const totalDuration = Date.now() - startTime;
                             dispatch(setHerdModulesLoadedInMs(totalDuration));
                             dispatch(setStatus(EnumScoutStateStatus.DONE_LOADING));
-                            onRefreshComplete?.();
+                            onRefreshCompleteRef.current?.();
                             return;
                         }
                     }
-                    else {
-                    }
                 }
                 catch (cacheError) {
                     console.warn("[useScoutRefresh] Cache load failed:", cacheError);
                     await handleIndexedDbError(cacheError, "cache load");
-                    // Continue with API call
                 }
             }
-            // When offline, skip network/auth; use cache if available
             if (isOffline) {
                 if (cachedHerdModules && cachedHerdModules.length > 0) {
                     dispatch(setDataSource(EnumDataSource.CACHE));
@@ -273,22 +139,18 @@ export function useScoutRefresh(options = {}) {
                 }
                 dispatch(setHerdModulesLoadedInMs(Date.now() - startTime));
                 dispatch(setStatus(EnumScoutStateStatus.DONE_LOADING));
-                onRefreshComplete?.();
-                refreshInProgressRef.current = false;
-                lastQueryAtRef.current = Date.now();
+                onRefreshCompleteRef.current?.();
                 return;
             }
-            // Step 2: Load fresh data from API (user resolves independently; Redux gets user as soon as getUser returns)
-            const parallelStartTime = Date.now();
             const userPromise = fetchUserWithOneRetry();
             let herdModulesResult;
             try {
                 herdModulesResult = await (async () => {
                     const start = Date.now();
-                    const result = await server_load_herd_modules();
+                    const result = await load_herd_modules_query(supabase);
                     const totalDuration = Date.now() - start;
                     const serverDuration = result.server_processing_time_ms || totalDuration;
-                    return { result, totalDuration, serverDuration, start };
+                    return { result, totalDuration, serverDuration };
                 })();
             }
             catch (e) {
@@ -296,121 +158,79 @@ export function useScoutRefresh(options = {}) {
                 throw e;
             }
             await userPromise;
-            const parallelDuration = Date.now() - parallelStartTime;
-            console.log(`[useScoutRefresh] API requests completed in ${parallelDuration}ms`);
-            // Extract results and timing
             const herdModulesResponse = herdModulesResult.result;
             const herdModulesServerDuration = herdModulesResult.serverDuration;
             const herdModulesTotalDuration = herdModulesResult.totalDuration;
-            const clientOverhead = herdModulesTotalDuration - herdModulesServerDuration;
-            console.log(`[useScoutRefresh] Fresh API timing breakdown:`);
-            console.log(`  - Server processing: ${herdModulesServerDuration}ms`);
-            console.log(`  - Client overhead: ${clientOverhead}ms`);
-            console.log(`  - Total request: ${herdModulesTotalDuration}ms`);
-            // Store timing values
-            timingRefs.current.herdModulesDuration = herdModulesServerDuration;
-            // Dispatch timing actions
             dispatch(setHerdModulesApiServerProcessingDuration(herdModulesServerDuration));
             dispatch(setHerdModulesApiTotalRequestDuration(herdModulesTotalDuration));
-            // Validate API responses 
-            const validationStartTime = Date.now();
             if (herdModulesResponse.status !== EnumWebResponse.SUCCESS ||
                 !Array.isArray(herdModulesResponse.data)) {
                 throw new Error("Invalid herd modules response");
             }
-            const validationDuration = Date.now() - validationStartTime;
-            console.log(`[useScoutRefresh] Data validation took: ${validationDuration}ms`);
-            // Use the validated data
-            const compatible_new_herd_modules = herdModulesResponse.data;
+            const freshHerdModules = herdModulesResponse.data;
             const freshContentHash = herdModulesResponse.content_hash;
-            // Set data source to DATABASE
             dispatch(setDataSource(EnumDataSource.DATABASE));
             dispatch(setDataSourceInfo({
                 source: EnumDataSource.DATABASE,
                 timestamp: Date.now(),
             }));
-            // Step 3: Update cache with fresh data
-            const cacheSaveStartTime = Date.now();
             try {
-                await scoutCache.setHerdModules(compatible_new_herd_modules, cacheTtlMs, freshContentHash);
-                const cacheSaveDuration = Date.now() - cacheSaveStartTime;
-                timingRefs.current.cacheSaveDuration = cacheSaveDuration;
-                console.log(`[useScoutRefresh] Cache updated in ${cacheSaveDuration}ms with TTL: ${Math.round(cacheTtlMs / 1000)}s`);
+                await scoutCache.setHerdModules(freshHerdModules, cacheTtlMs, freshContentHash);
             }
             catch (cacheError) {
                 console.warn("[useScoutRefresh] Cache save failed:", cacheError);
                 await handleIndexedDbError(cacheError, "cache save", async () => {
-                    await scoutCache.setHerdModules(compatible_new_herd_modules, cacheTtlMs, freshContentHash);
+                    await scoutCache.setHerdModules(freshHerdModules, cacheTtlMs, freshContentHash);
                 });
             }
-            // Step 4: Update store with fresh data (reducer skips no-op updates)
             const dataProcessingStartTime = Date.now();
-            // Update store with new data
-            console.log(`[useScoutRefresh] Updating store with fresh herd modules`);
             dispatchInTransition(dispatch, setHerdModules({
-                modules: compatible_new_herd_modules,
+                modules: freshHerdModules,
                 contentHash: freshContentHash,
             }));
             dispatch(setHerdModulesLoadingState(EnumHerdModulesLoadingState.SUCCESSFULLY_LOADED));
             const dataProcessingDuration = Date.now() - dataProcessingStartTime;
-            timingRefs.current.dataProcessingDuration = dataProcessingDuration;
             dispatch(setDataProcessingDuration(dataProcessingDuration));
             const loadingDuration = Date.now() - startTime;
             dispatch(setHerdModulesLoadedInMs(loadingDuration));
             dispatch(setStatus(EnumScoutStateStatus.DONE_LOADING));
-            // Log concise completion summary
-            console.log(`[useScoutRefresh] Refresh completed in ${loadingDuration}ms (Server: ${herdModulesServerDuration}ms, Total API: ${herdModulesTotalDuration}ms)`);
-            onRefreshComplete?.();
+            onRefreshCompleteRef.current?.();
         }
         catch (error) {
             const loadingDuration = Date.now() - startTime;
             console.error("Error refreshing scout data:", error);
-            // Set data source to UNKNOWN on error
             dispatch(setDataSource(EnumDataSource.UNKNOWN));
             dispatch(setDataSourceInfo({
                 source: EnumDataSource.UNKNOWN,
                 timestamp: Date.now(),
             }));
-            // Ensure consistent state updates on error
             dispatch(setHerdModulesLoadingState(EnumHerdModulesLoadingState.UNSUCCESSFULLY_LOADED));
             dispatch(setHerdModulesLoadedInMs(loadingDuration));
             dispatch(setStatus(EnumScoutStateStatus.DONE_LOADING));
-            // Log essential error metrics
-            console.log(`[useScoutRefresh] Refresh failed after ${loadingDuration}ms`);
-            // Call completion callback even on error for consistency
-            onRefreshComplete?.();
+            onRefreshCompleteRef.current?.();
         }
         finally {
             refreshInProgressRef.current = false;
             lastQueryAtRef.current = Date.now();
         }
-    }, [
-        dispatch,
-        supabase,
-        onRefreshComplete,
-        cacheFirst,
-        cacheTtlMs,
-        handleIndexedDbError,
-    ]);
+    }, [dispatch, supabase, cacheFirst, cacheTtlMs, handleIndexedDbError]);
     useEffect(() => {
         if (autoRefresh) {
-            handleRefresh();
+            void handleRefresh({ force: false });
         }
     }, [autoRefresh, handleRefresh]);
-    // Full refetch when nav goes online, only if min interval since last query has passed
     useEffect(() => {
-        if (typeof window === "undefined")
+        if (!autoRefresh || typeof window === "undefined")
             return;
         const handleOnline = () => {
             const now = Date.now();
             if (now - lastQueryAtRef.current >= onlineRefetchMinIntervalMs) {
-                handleRefresh();
+                void handleRefresh({ force: true });
             }
         };
         window.addEventListener("online", handleOnline);
         return () => window.removeEventListener("online", handleOnline);
-    }, [handleRefresh, onlineRefetchMinIntervalMs]);
-    // Utility function to clear cache
+    }, [autoRefresh, handleRefresh, onlineRefetchMinIntervalMs]);
     const clearCache = useCallback(async () => {
         try {
             await scoutCache.clearHerdModules();

package/dist/providers/ScoutRefreshProvider.d.ts

@@ -33,4 +33,4 @@ export interface ScoutRefreshProviderProps extends UseScoutRefreshOptions {
     children: ReactNode;
     abilityParams?: ScoutRefreshAbilityParams;
 }
-export declare function ScoutRefreshProvider({ children, abilityParams, ...refreshOptions }: ScoutRefreshProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ScoutRefreshProvider({ children, abilityParams, supabase: supabaseOption, ...refreshOptions }: ScoutRefreshProviderProps): import("react/jsx-runtime").JSX.Element;