@adventurelabs/scout-core 2.0.8 → 2.0.10

package/README.md

@@ -35,6 +35,8 @@ barrel.
 `ScoutRefreshProvider` accepts an existing browser Supabase client and otherwise
 creates one stable client. Its automatic refresh uses a fresh IndexedDB cache
 without another request; manual and reconnect refreshes still query the API.
+Returning to a visible tab revalidates herd data and refreshes JWT mints that
+are near expiry, covering browsers that suspend background timers.
 Offline PWAs can pass a persisted `offlineUserId` to restore that user's herd
 modules and JWT mints before online authentication is revalidated. Cached mints
 remain available when expired; pass `false` as the fourth argument to

package/dist/hooks/useScoutRefresh.js

@@ -60,6 +60,7 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
     const { validatedUserId, onUserValidated } = identityOptions;
     const dispatch = useAppDispatch();
     const refreshIdRef = useRef(0);
+    const refreshInProgressIdRef = useRef(null);
     const activeUserIdRef = useRef(null);
     const validatedUserIdRef = useRef(null);
     const providedValidatedUserIdRef = useRef(validatedUserId);
@@ -91,7 +92,10 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
     }, [dispatch]);
     const cacheIdentityRef = useRef({ supabase, offlineUserId });
     const handleRefresh = useCallback(async ({ force = true } = {}) => {
+        if (refreshInProgressIdRef.current !== null && !force)
+            return;
         const refreshId = ++refreshIdRef.current;
+        refreshInProgressIdRef.current = refreshId;
         const isCurrent = () => refreshIdRef.current === refreshId;
         const startTime = Date.now();
         const isOffline = typeof navigator === "undefined" || !navigator.onLine;
@@ -268,6 +272,9 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
             }
         }
         finally {
+            if (refreshInProgressIdRef.current === refreshId) {
+                refreshInProgressIdRef.current = null;
+            }
             if (isCurrent()) {
                 lastQueryAtRef.current = Date.now();
             }
@@ -355,14 +362,25 @@ export function useScoutRefresh(options = {}, identityOptions = {}) {
     useEffect(() => {
         if (!autoRefresh || typeof window === "undefined")
             return;
-        const handleOnline = () => {
+        const revalidate = () => {
+            if (!navigator.onLine)
+                return;
             const now = Date.now();
             if (now - lastQueryAtRef.current >= onlineRefetchMinIntervalMs) {
                 void handleRefresh({ force: true });
             }
         };
-        window.addEventListener("online", handleOnline);
-        return () => window.removeEventListener("online", handleOnline);
+        const handleVisibilityChange = () => {
+            if (document.visibilityState === "visible") {
+                revalidate();
+            }
+        };
+        window.addEventListener("online", revalidate);
+        document.addEventListener("visibilitychange", handleVisibilityChange);
+        return () => {
+            window.removeEventListener("online", revalidate);
+            document.removeEventListener("visibilitychange", handleVisibilityChange);
+        };
     }, [autoRefresh, handleRefresh, onlineRefetchMinIntervalMs]);
     const clearCache = useCallback(async () => {
         try {

package/dist/providers/ScoutRefreshProvider.js

@@ -82,7 +82,9 @@ function useJwtMintLifecycle({ enabled, supabase, identity, cacheKey, ttlSec, re
     const [mint, setMint] = useState(null);
     const [inFlight, setInFlight] = useState(false);
     const [error, setError] = useState(null);
+    const [offline, setOffline] = useState(isBrowserOffline);
     const refreshIdRef = useRef(0);
+    const refreshInProgressRef = useRef(false);
     const authUserIdRef = useRef(null);
     const cacheHydrationIdRef = useRef(0);
     const signedOutRef = useRef(false);
@@ -101,15 +103,16 @@ function useJwtMintLifecycle({ enabled, supabase, identity, cacheKey, ttlSec, re
             console.error("[ScoutRefreshProvider] User validation callback failed:", validationError);
         }
     }, [onUserValidated]);
-    const status = useMemo(() => derive_jwt_mint_status(enabled, mint, inFlight, error), [enabled, mint, inFlight, error]);
+    const status = useMemo(() => derive_jwt_mint_status(enabled, mint, inFlight, error, offline), [enabled, mint, inFlight, error, offline]);
     const refreshMint = useCallback(async (force = true) => {
         if (!enabled || isBrowserOffline())
             return;
+        if (refreshInProgressRef.current && !force)
+            return;
+        refreshInProgressRef.current = true;
         cacheHydrationIdRef.current++;
         const refreshId = ++refreshIdRef.current;
         const isCurrent = () => refreshIdRef.current === refreshId;
-        setInFlight(true);
-        setError(null);
         try {
             const { data, error: authError } = await supabase.auth.getUser();
             if (authError) {
@@ -142,6 +145,8 @@ function useJwtMintLifecycle({ enabled, supabase, identity, cacheKey, ttlSec, re
                 !shouldRefreshMint(currentMint, ttlSec, refreshBeforeExpirySec)) {
                 return;
             }
+            setInFlight(true);
+            setError(null);
             const mintResponse = await mintToken(supabase);
             if (!isCurrent() || authUserIdRef.current !== userId)
                 return;
@@ -176,6 +181,7 @@ function useJwtMintLifecycle({ enabled, supabase, identity, cacheKey, ttlSec, re
         }
         finally {
             if (isCurrent()) {
+                refreshInProgressRef.current = false;
                 setInFlight(false);
             }
         }
@@ -201,10 +207,12 @@ function useJwtMintLifecycle({ enabled, supabase, identity, cacheKey, ttlSec, re
             authUserIdRef.current = null;
             cacheHydrationIdRef.current++;
             refreshIdRef.current++;
+            refreshInProgressRef.current = false;
             updateMint(null);
             setInFlight(false);
         }
         if (!enabled) {
+            refreshInProgressRef.current = false;
             updateMint(null);
             setError(null);
             setInFlight(false);
@@ -219,6 +227,7 @@ function useJwtMintLifecycle({ enabled, supabase, identity, cacheKey, ttlSec, re
             authUserIdRef.current = null;
             cacheHydrationIdRef.current++;
             refreshIdRef.current++;
+            refreshInProgressRef.current = false;
             updateMint(null);
             setError(null);
             setInFlight(false);
@@ -287,40 +296,78 @@ function useJwtMintLifecycle({ enabled, supabase, identity, cacheKey, ttlSec, re
             }
         };
         void initializeMint();
+        const refreshCurrentMintIfDue = () => {
+            const currentMint = mintRef.current;
+            if (!currentMint ||
+                shouldRefreshMint(currentMint, ttlSec, refreshBeforeExpirySec)) {
+                void refreshMint(false);
+            }
+        };
         const unsubscribeAuth = subscribeToSupabaseAuth(supabase, (event, session) => {
             if (event === "SIGNED_OUT") {
                 signedOutRef.current = true;
                 authUserIdRef.current = null;
                 cacheHydrationIdRef.current++;
                 refreshIdRef.current++;
+                refreshInProgressRef.current = false;
                 updateMint(null);
                 setError(null);
                 setInFlight(false);
                 return;
             }
             if (event === "SIGNED_IN" || event === "TOKEN_REFRESHED") {
+                const wasSignedOut = signedOutRef.current;
                 signedOutRef.current = false;
-                refreshIdRef.current++;
-                setInFlight(false);
                 const userId = session?.user?.id;
-                if (userId) {
+                if (!userId) {
+                    refreshCurrentMintIfDue();
+                    return;
+                }
+                const knownUserId = authUserIdRef.current;
+                const userChanged = wasSignedOut ||
+                    (knownUserId !== null && knownUserId !== userId);
+                if (userChanged) {
+                    cacheHydrationIdRef.current++;
+                    refreshIdRef.current++;
+                    refreshInProgressRef.current = false;
                     void initializeMint(userId, true);
                 }
+                else if (knownUserId === null || !mintRef.current) {
+                    void initializeMint(userId);
+                }
                 else {
-                    void refreshMint();
+                    refreshCurrentMintIfDue();
                 }
             }
         });
         const handleOnline = () => {
+            setOffline(false);
             void refreshMint(false);
         };
+        const handleOffline = () => {
+            setOffline(true);
+        };
+        const handleVisibilityChange = () => {
+            if (document.visibilityState !== "visible")
+                return;
+            const currentlyOffline = isBrowserOffline();
+            setOffline(currentlyOffline);
+            if (currentlyOffline)
+                return;
+            refreshCurrentMintIfDue();
+        };
         window.addEventListener("online", handleOnline);
+        window.addEventListener("offline", handleOffline);
+        document.addEventListener("visibilitychange", handleVisibilityChange);
         return () => {
             cancelled = true;
             cacheHydrationIdRef.current++;
             refreshIdRef.current++;
+            refreshInProgressRef.current = false;
             unsubscribeAuth();
             window.removeEventListener("online", handleOnline);
+            window.removeEventListener("offline", handleOffline);
+            document.removeEventListener("visibilitychange", handleVisibilityChange);
         };
     }, [
         enabled,
@@ -328,6 +375,8 @@ function useJwtMintLifecycle({ enabled, supabase, identity, cacheKey, ttlSec, re
         offlineUserId,
         validatedUserId,
         cacheKey,
+        ttlSec,
+        refreshBeforeExpirySec,
         refreshMint,
         updateMint,
     ]);
@@ -340,7 +389,7 @@ function useJwtMintLifecycle({ enabled, supabase, identity, cacheKey, ttlSec, re
         const refreshAtSec = Math.max(expSec - refreshBeforeExpirySec, mint.iat + 1);
         const delayMs = Math.max((refreshAtSec - nowSec) * 1000, 1000);
         const timer = setTimeout(() => {
-            void refreshMint();
+            void refreshMint(false);
         }, delayMs);
         return () => clearTimeout(timer);
     }, [enabled, mint, ttlSec, refreshBeforeExpirySec, refreshMint]);

package/dist/types/jwt_mint.d.ts

@@ -7,4 +7,5 @@ export declare enum EnumJwtMintStatus {
 }
 export declare function derive_jwt_mint_status(enabled: boolean, mint: {
     token: string;
-} | null | undefined, inFlight: boolean, error: string | null): EnumJwtMintStatus;
+    exp?: number;
+} | null | undefined, inFlight: boolean, error: string | null, allowExpired?: boolean): EnumJwtMintStatus;

package/dist/types/jwt_mint.js

@@ -6,17 +6,18 @@ export var EnumJwtMintStatus;
     EnumJwtMintStatus["READY"] = "ready";
     EnumJwtMintStatus["ERROR"] = "error";
 })(EnumJwtMintStatus || (EnumJwtMintStatus = {}));
-export function derive_jwt_mint_status(enabled, mint, inFlight, error) {
+export function derive_jwt_mint_status(enabled, mint, inFlight, error, allowExpired = false) {
     if (!enabled) {
         return EnumJwtMintStatus.IDLE;
     }
-    if (inFlight && !mint?.token) {
-        return EnumJwtMintStatus.LOADING;
+    const expired = mint?.exp != null && mint.exp <= Math.floor(Date.now() / 1000);
+    const hasUsableMint = Boolean(mint?.token) && (allowExpired || !expired);
+    if (inFlight) {
+        return hasUsableMint
+            ? EnumJwtMintStatus.REFRESHING
+            : EnumJwtMintStatus.LOADING;
     }
-    if (inFlight && mint?.token) {
-        return EnumJwtMintStatus.REFRESHING;
-    }
-    if (mint?.token) {
+    if (hasUsableMint) {
         return EnumJwtMintStatus.READY;
     }
     if (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adventurelabs/scout-core",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "description": "Core utilities and helpers for Adventure Labs Scout applications",
   "exports": {
     "./client": {