@adventurelabs/scout-core 2.0.8 → 2.0.9

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

@@ -355,14 +355,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,6 +82,7 @@ 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 authUserIdRef = useRef(null);
     const cacheHydrationIdRef = useRef(0);
@@ -101,7 +102,7 @@ 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;
@@ -312,15 +313,36 @@ function useJwtMintLifecycle({ enabled, supabase, identity, cacheKey, ttlSec, re
             }
         });
         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;
+            const currentMint = mintRef.current;
+            if (!currentMint ||
+                shouldRefreshMint(currentMint, ttlSec, refreshBeforeExpirySec)) {
+                void refreshMint(false);
+            }
+        };
         window.addEventListener("online", handleOnline);
+        window.addEventListener("offline", handleOffline);
+        document.addEventListener("visibilitychange", handleVisibilityChange);
         return () => {
             cancelled = true;
             cacheHydrationIdRef.current++;
             refreshIdRef.current++;
             unsubscribeAuth();
             window.removeEventListener("online", handleOnline);
+            window.removeEventListener("offline", handleOffline);
+            document.removeEventListener("visibilitychange", handleVisibilityChange);
         };
     }, [
         enabled,
@@ -328,6 +350,8 @@ function useJwtMintLifecycle({ enabled, supabase, identity, cacheKey, ttlSec, re
         offlineUserId,
         validatedUserId,
         cacheKey,
+        ttlSec,
+        refreshBeforeExpirySec,
         refreshMint,
         updateMint,
     ]);

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.9",
   "description": "Core utilities and helpers for Adventure Labs Scout applications",
   "exports": {
     "./client": {