antaeus.keycloak.react 2.6.2 → 2.6.4

package/README.md

@@ -30,6 +30,7 @@ That's it! You now have full authentication with automatic token refresh.
 - Zero-config setup
 - Automatic token lifecycle management
 - Token refresh on app startup
+- Token refresh when suspended mobile/PWA sessions resume
 - Silent token renewal
 - Session monitoring UI
 - Protected routes
@@ -152,6 +153,8 @@ const { isEnabled, isConfigured, reason } = useKeycloakStatus();
 - **on-demand**: Only when API returns 401
 - **both** (recommended): Startup + 401 retry
 
+For mobile browsers and installed PWAs, token freshness is also checked when the app resumes from the background by default. Set `silentRenew.refreshOnResume` to `false` to disable this behavior.
+
 ## React Hooks
 
 ### useAuth()

package/dist/index.d.mts

@@ -121,6 +121,12 @@ interface SilentRenewConfig {
      * @default true
      */
     useRefreshToken?: boolean;
+    /**
+     * Re-check token freshness when a suspended tab/PWA resumes.
+     * Useful for mobile browsers and installed PWAs where timers pause in the background.
+     * @default true
+     */
+    refreshOnResume?: boolean;
 }
 /**
  * Event callbacks for authentication lifecycle

package/dist/index.d.ts

@@ -121,6 +121,12 @@ interface SilentRenewConfig {
      * @default true
      */
     useRefreshToken?: boolean;
+    /**
+     * Re-check token freshness when a suspended tab/PWA resumes.
+     * Useful for mobile browsers and installed PWAs where timers pause in the background.
+     * @default true
+     */
+    refreshOnResume?: boolean;
 }
 /**
  * Event callbacks for authentication lifecycle

package/dist/index.js

@@ -36,7 +36,8 @@ var defaultConfig = {
     // 30 days in seconds
     showLoadingIndicator: false,
     loadingMessage: "Refreshing session...",
-    useRefreshToken: true
+    useRefreshToken: true,
+    refreshOnResume: true
   },
   advanced: {
     responseType: "code",
@@ -191,6 +192,7 @@ function useTokenLifecycle(options) {
   const auth = useAuth();
   const [isRefreshing, setIsRefreshing] = react.useState(false);
   const [isRefreshTokenExpired, setIsRefreshTokenExpired] = react.useState(false);
+  const isRefreshingRef = react.useRef(false);
   const hasCheckedOnStartup = react.useRef(false);
   const supportsRefreshTokens = config.silentRenew?.useRefreshToken !== false;
   const [pendingRetry, setPendingRetry] = react.useState(null);
@@ -243,10 +245,11 @@ function useTokenLifecycle(options) {
     return elapsedSeconds >= maxLifetime;
   }, [config.silentRenew?.maxRefreshTokenLifetime, getStorageKey, log, storeFirstLoginTime]);
   const refreshToken = react.useCallback(async () => {
-    if (isRefreshing) {
+    if (isRefreshingRef.current) {
       log("Refresh already in progress, skipping");
       return;
     }
+    isRefreshingRef.current = true;
     setIsRefreshing(true);
     deferredRefreshReasonRef.current = null;
     try {
@@ -302,10 +305,10 @@ function useTokenLifecycle(options) {
       onRefreshError?.(err);
       throw err;
     } finally {
+      isRefreshingRef.current = false;
       setIsRefreshing(false);
     }
   }, [
-    isRefreshing,
     auth,
     checkRefreshTokenLifetime,
     onRefreshStart,
@@ -316,6 +319,38 @@ function useTokenLifecycle(options) {
     getStorageKey,
     log
   ]);
+  const shouldRefreshOnResume = react.useCallback((reason) => {
+    const silentRenewEnabled = config.silentRenew?.enabled !== false;
+    const refreshOnResume = config.silentRenew?.refreshOnResume !== false;
+    const strategy = config.silentRenew?.refreshStrategy || "both";
+    const strategyAllowsResume = strategy === "startup" || strategy === "both";
+    const hasRefreshToken = Boolean(auth.user?.refresh_token);
+    if (!silentRenewEnabled || !refreshOnResume || !strategyAllowsResume) {
+      return false;
+    }
+    if (auth.isLoading) {
+      return false;
+    }
+    if (!auth.user) {
+      return false;
+    }
+    if (supportsRefreshTokens && !hasRefreshToken) {
+      log("Skipping resume token check because no refresh token is available:", reason);
+      return false;
+    }
+    if (reason !== "online" && typeof document !== "undefined" && document.visibilityState === "hidden") {
+      return false;
+    }
+    return true;
+  }, [
+    auth.isLoading,
+    auth.user,
+    config.silentRenew?.enabled,
+    config.silentRenew?.refreshOnResume,
+    config.silentRenew?.refreshStrategy,
+    supportsRefreshTokens,
+    log
+  ]);
   const checkAndRefreshTokens = react.useCallback(async () => {
     if (!auth.user) {
       log("No user session, skipping token check");
@@ -463,6 +498,38 @@ function useTokenLifecycle(options) {
     checkAndRefreshTokens,
     log
   ]);
+  react.useEffect(() => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return;
+    }
+    const runResumeCheck = (reason) => {
+      if (!shouldRefreshOnResume(reason)) {
+        return;
+      }
+      log("Running resume token check after:", reason);
+      checkAndRefreshTokens().catch((error) => {
+        log("Resume token check failed:", error);
+      });
+    };
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === "visible") {
+        runResumeCheck("visibilitychange");
+      }
+    };
+    const handlePageShow = () => runResumeCheck("pageshow");
+    const handleFocus = () => runResumeCheck("focus");
+    const handleOnline = () => runResumeCheck("online");
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    window.addEventListener("pageshow", handlePageShow);
+    window.addEventListener("focus", handleFocus);
+    window.addEventListener("online", handleOnline);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      window.removeEventListener("pageshow", handlePageShow);
+      window.removeEventListener("focus", handleFocus);
+      window.removeEventListener("online", handleOnline);
+    };
+  }, [checkAndRefreshTokens, log, shouldRefreshOnResume]);
   react.useEffect(() => {
     if (hasCheckedOnStartup.current) {
       const hasUser = Boolean(auth.user);
@@ -885,7 +952,8 @@ var CONFIG_PRESETS = {
       maxRefreshTokenLifetime: 2592e3,
       // 30 days
       showLoadingIndicator: false,
-      loadingMessage: "Refreshing session..."
+      loadingMessage: "Refreshing session...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",
@@ -921,7 +989,8 @@ var CONFIG_PRESETS = {
       // 30 days
       showLoadingIndicator: true,
       // Show loading for better UX
-      loadingMessage: "Restoring your session..."
+      loadingMessage: "Restoring your session...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",
@@ -958,7 +1027,8 @@ var CONFIG_PRESETS = {
       // 24 hours only
       showLoadingIndicator: false,
       // Silent for security
-      loadingMessage: "Validating session..."
+      loadingMessage: "Validating session...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",
@@ -992,7 +1062,8 @@ var CONFIG_PRESETS = {
       maxRefreshTokenLifetime: 604800,
       // 7 days
       showLoadingIndicator: false,
-      loadingMessage: "Refreshing session..."
+      loadingMessage: "Refreshing session...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",
@@ -1029,7 +1100,8 @@ var CONFIG_PRESETS = {
       // No limit (for convenience)
       showLoadingIndicator: true,
       // Show for debugging
-      loadingMessage: "[DEV] Refreshing tokens..."
+      loadingMessage: "[DEV] Refreshing tokens...",
+      refreshOnResume: true
     },
     advanced: {
       responseType: "code",