antaeus.keycloak.react 2.2.3 → 2.4.0

package/README.md

@@ -115,6 +115,28 @@ function MyComponent() {
 </KeycloakProvider>
 ```
 
+### 5. Optional / Disabled Mode
+
+Wrap legacy paths or feature flags without tearing out the provider:
+
+```tsx
+<KeycloakProvider
+  authority={import.meta.env.VITE_KEYCLOAK_AUTHORITY ?? ''}
+  clientId={import.meta.env.VITE_KEYCLOAK_CLIENT_ID ?? ''}
+  enabled={Boolean(import.meta.env.VITE_KEYCLOAK_AUTHORITY)}
+>
+  <App />
+</KeycloakProvider>
+```
+
+When disabled (or missing authority/clientId), the provider exposes a safe stub context—`useAuth()` still works, but no network calls are made. Inspect the state anywhere via:
+
+```tsx
+import { useKeycloakStatus } from 'antaeus.keycloak.react';
+
+const { isEnabled, isConfigured, reason } = useKeycloakStatus();
+```
+
 ## Configuration Presets
 
 | Preset | Session Lifetime | Best For |
@@ -144,6 +166,61 @@ auth.signinRedirect()
 auth.signoutRedirect()
 ```
 
+## Token Bridge (Non-React Consumers)
+
+Expose tokens to plain TypeScript modules (SignalR, fetch helpers, etc.):
+
+```tsx
+import {
+  KeycloakProvider,
+  TokenBridgeSync,
+  createTokenBridge,
+} from 'antaeus.keycloak.react';
+
+export const tokenBridge = createTokenBridge();
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <KeycloakProvider authority="..." clientId="..." tokenBridge={tokenBridge}>
+    <TokenBridgeSync bridge={tokenBridge} />
+    <App />
+  </KeycloakProvider>
+);
+```
+
+Then outside React:
+
+```ts
+import { tokenBridge } from './main';
+
+tokenBridge.subscribe((token) => {
+  console.log('Token changed:', token);
+});
+```
+
+Prefer a shared singleton? Use the default bridge:
+
+```tsx
+import {
+  KeycloakProvider,
+  TokenBridgeSync,
+  defaultTokenBridge,
+} from 'antaeus.keycloak.react';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <KeycloakProvider authority="..." clientId="..." tokenBridge={defaultTokenBridge}>
+    <TokenBridgeSync />
+    <App />
+  </KeycloakProvider>
+);
+```
+
+```ts
+// signalr.ts
+import { defaultTokenBridge } from 'antaeus.keycloak.react';
+
+const bearer = defaultTokenBridge.getToken();
+```
+
 ### useProtectedFetch()
 
 ```tsx
@@ -325,6 +402,24 @@ If your refresh token expires (exceeds `maxRefreshTokenLifetime`):
 />
 ```
 
+### Refresh Tokens After Restart
+
+When a refresh token is available the provider now reuses it on startup, ensuring long-lived sessions survive browser reloads or app restarts. The refresh token grant is attempted automatically before falling back to iframe-based silent renew.
+
+If you need to disable this behavior and revert to iframe-only silent renew, set:
+
+```tsx
+<KeycloakProvider
+  authority="..."
+  clientId="my-app"
+  config={{
+    silentRenew: {
+      useRefreshToken: false,
+    },
+  }}
+/>
+```
+
 ### Startup Token Refresh
 
 When your app loads with an existing session:
@@ -446,4 +541,3 @@ const { fetchJson } = useProtectedFetch({
 ## License
 
 MIT � Saeed Aghdam
-

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import React from 'react';
+import * as React$1 from 'react';
+import React__default from 'react';
 import { User, UserManagerSettings } from 'oidc-client-ts';
 export { User } from 'oidc-client-ts';
 import { useLocation } from 'react-router-dom';
@@ -113,6 +114,12 @@ interface SilentRenewConfig {
      * @default 'Refreshing session...'
      */
     loadingMessage?: string;
+    /**
+     * Enable using the refresh token grant instead of iframe silent renew when available.
+     * Keeps long-lived sessions alive even after the app is closed.
+     * @default true
+     */
+    useRefreshToken?: boolean;
 }
 /**
  * Event callbacks for authentication lifecycle
@@ -217,6 +224,40 @@ declare function getConfigPreset(preset: ConfigPreset): Partial<KeycloakConfig>;
  */
 declare function mergeWithPreset(preset: ConfigPreset, customConfig: Partial<KeycloakConfig>): Partial<KeycloakConfig>;
 
+type TokenListener = (token: string | null) => void;
+/**
+ * Minimal bridge to expose the current Keycloak access token outside React.
+ * Consumers can subscribe to token changes or fetch the latest value on demand.
+ */
+declare class TokenBridge {
+    private currentToken;
+    private listeners;
+    /**
+     * Update the tracked token and notify subscribers when it changes.
+     */
+    setToken(token: string | null): void;
+    /**
+     * Read the most recent token value.
+     */
+    getToken(): string | null;
+    /**
+     * Convenience helper for async callers.
+     */
+    getTokenAsync(): Promise<string | null>;
+    /**
+     * Subscribe to token changes. Returns an unsubscribe callback.
+     */
+    subscribe(listener: TokenListener): () => void;
+}
+/**
+ * Factory helper to create an isolated token bridge.
+ */
+declare const createTokenBridge: () => TokenBridge;
+/**
+ * Default shared bridge for simple scenarios.
+ */
+declare const defaultTokenBridge: TokenBridge;
+
 /**
  * Props for zero-config mode (simplified setup)
  */
@@ -234,10 +275,16 @@ interface KeycloakProviderZeroConfigProps {
      * @default 'default'
      */
     preset?: ConfigPreset;
+    /**
+     * Toggle to disable Keycloak integration entirely.
+     * When false, children render with a stub auth context.
+     * @default true
+     */
+    enabled?: boolean;
     /**
      * Child components to render
      */
-    children: React.ReactNode;
+    children: React__default.ReactNode;
     /**
      * Enable debug logging to console
      * @default false
@@ -248,6 +295,10 @@ interface KeycloakProviderZeroConfigProps {
      * Use this to customize preset or zero-config defaults
      */
     config?: Partial<Omit<KeycloakConfig, 'authority' | 'clientId'>>;
+    /**
+     * Optional token bridge instance for exposing tokens outside React.
+     */
+    tokenBridge?: TokenBridge;
 }
 /**
  * Props for full-config mode (advanced setup)
@@ -257,15 +308,25 @@ interface KeycloakProviderFullConfigProps {
      * Full Keycloak configuration object
      */
     config: KeycloakConfig;
+    /**
+     * Toggle to disable Keycloak integration entirely.
+     * When false, children render with a stub auth context.
+     * @default true
+     */
+    enabled?: boolean;
     /**
      * Child components to render
      */
-    children: React.ReactNode;
+    children: React__default.ReactNode;
     /**
      * Enable debug logging to console
      * @default false
      */
     debug?: boolean;
+    /**
+     * Optional token bridge instance for exposing tokens outside React.
+     */
+    tokenBridge?: TokenBridge;
 }
 /**
  * Combined props type
@@ -318,6 +379,7 @@ type KeycloakProviderProps = KeycloakProviderZeroConfigProps | KeycloakProviderF
  *     silentRenew: {
  *       maxRefreshTokenLifetime: 604800, // Override: 7 days instead of 30
  *       showLoadingIndicator: true,
+ *       useRefreshToken: true, // Explicitly ensure refresh tokens are used when available
  *     }
  *   }}
  *   debug={true}
@@ -361,6 +423,7 @@ type KeycloakProviderProps = KeycloakProviderZeroConfigProps | KeycloakProviderF
  *       enabled: true,
  *       refreshStrategy: 'both',
  *       maxRefreshTokenLifetime: 2592000,
+ *       useRefreshToken: true,
  *     },
  *     events: {
  *       onLogin: (user) => console.log('User logged in', user),
@@ -380,6 +443,7 @@ type KeycloakProviderProps = KeycloakProviderZeroConfigProps | KeycloakProviderF
  * - ✅ Token lifecycle management (refresh on app startup)
  * - ✅ Session monitoring UI (countdown timer)
  * - ✅ Silent renew (background token refresh)
+ * - ✅ Refresh token grant fallback on app restart
  * - ✅ Error notifications (user-friendly messages)
  * - ✅ 401 retry logic (automatic token refresh on API errors)
  * - ✅ Maximum refresh token lifetime (security control)
@@ -387,7 +451,7 @@ type KeycloakProviderProps = KeycloakProviderZeroConfigProps | KeycloakProviderF
  *
  * All features can be disabled or customized via configuration overrides.
  */
-declare const KeycloakProvider: React.FC<KeycloakProviderProps>;
+declare const KeycloakProvider: React__default.FC<KeycloakProviderProps>;
 
 /**
  * Context object passed to custom policy function
@@ -410,7 +474,7 @@ interface ProtectedRouteProps {
     /**
      * Child components to render when user is authorized
      */
-    children: React.ReactNode;
+    children: React__default.ReactNode;
     /**
      * Required realm roles (OR logic - user needs at least one)
      */
@@ -437,11 +501,11 @@ interface ProtectedRouteProps {
     /**
      * Custom loading component to display while checking authentication
      */
-    loadingComponent?: React.ReactNode;
+    loadingComponent?: React__default.ReactNode;
     /**
      * Custom unauthorized component to display when user lacks required permissions
      */
-    unauthorizedComponent?: React.ReactNode;
+    unauthorizedComponent?: React__default.ReactNode;
     /**
      * Path to redirect to if not authenticated
      * @default '/login'
@@ -568,14 +632,14 @@ interface ProtectedRouteProps {
  * </ProtectedRoute>
  * ```
  */
-declare const ProtectedRoute: React.FC<ProtectedRouteProps>;
+declare const ProtectedRoute: React__default.FC<ProtectedRouteProps>;
 
 interface LoginButtonProps {
     /**
      * Button text
      * @default 'Login'
      */
-    children?: React.ReactNode;
+    children?: React__default.ReactNode;
     /**
      * Additional CSS class names
      */
@@ -602,7 +666,7 @@ interface LoginButtonProps {
     /**
      * Custom inline styles
      */
-    style?: React.CSSProperties;
+    style?: React__default.CSSProperties;
     /**
      * Disable the button
      */
@@ -642,14 +706,14 @@ interface LoginButtonProps {
  * />
  * ```
  */
-declare const LoginButton: React.FC<LoginButtonProps>;
+declare const LoginButton: React__default.FC<LoginButtonProps>;
 
 interface LogoutButtonProps {
     /**
      * Button text
      * @default 'Logout'
      */
-    children?: React.ReactNode;
+    children?: React__default.ReactNode;
     /**
      * Additional CSS class names
      */
@@ -676,7 +740,7 @@ interface LogoutButtonProps {
     /**
      * Custom inline styles
      */
-    style?: React.CSSProperties;
+    style?: React__default.CSSProperties;
     /**
      * Disable the button
      */
@@ -719,7 +783,7 @@ interface LogoutButtonProps {
  * />
  * ```
  */
-declare const LogoutButton: React.FC<LogoutButtonProps>;
+declare const LogoutButton: React__default.FC<LogoutButtonProps>;
 
 interface UserProfileProps {
     /**
@@ -749,7 +813,7 @@ interface UserProfileProps {
     /**
      * Custom inline styles
      */
-    style?: React.CSSProperties;
+    style?: React__default.CSSProperties;
     /**
      * Callback when profile is clicked
      */
@@ -793,7 +857,7 @@ interface UserProfileProps {
  * />
  * ```
  */
-declare const UserProfile: React.FC<UserProfileProps>;
+declare const UserProfile: React__default.FC<UserProfileProps>;
 
 interface SessionMonitorProps {
     /**
@@ -845,7 +909,7 @@ interface SessionMonitorProps {
     /**
      * Custom inline styles
      */
-    style?: React.CSSProperties;
+    style?: React__default.CSSProperties;
 }
 /**
  * Session monitoring component with countdown timer
@@ -888,7 +952,7 @@ interface SessionMonitorProps {
  * />
  * ```
  */
-declare const SessionMonitor: React.FC<SessionMonitorProps>;
+declare const SessionMonitor: React__default.FC<SessionMonitorProps>;
 
 interface DeviceLoginProps {
     /**
@@ -921,7 +985,7 @@ interface DeviceLoginProps {
     /**
      * Custom inline styles
      */
-    style?: React.CSSProperties;
+    style?: React__default.CSSProperties;
 }
 /**
  * Device flow login component
@@ -956,7 +1020,7 @@ interface DeviceLoginProps {
  * />
  * ```
  */
-declare const DeviceLogin: React.FC<DeviceLoginProps>;
+declare const DeviceLogin: React__default.FC<DeviceLoginProps>;
 
 interface TokenLifecycleManagerProps {
     /**
@@ -966,7 +1030,7 @@ interface TokenLifecycleManagerProps {
     /**
      * Child components to render
      */
-    children: React.ReactNode;
+    children: React__default.ReactNode;
     /**
      * Enable debug logging
      * @default false
@@ -988,7 +1052,19 @@ interface TokenLifecycleManagerProps {
  * </TokenLifecycleManager>
  * ```
  */
-declare const TokenLifecycleManager: React.FC<TokenLifecycleManagerProps>;
+declare const TokenLifecycleManager: React__default.FC<TokenLifecycleManagerProps>;
+
+interface TokenBridgeProps {
+    /**
+     * Optional custom bridge instance. Defaults to the shared global bridge.
+     */
+    bridge?: TokenBridge;
+}
+/**
+ * Synchronises the current Keycloak access token into an imperative TokenBridge.
+ * Place this component inside your application tree (after KeycloakProvider).
+ */
+declare const TokenBridgeSync: React.FC<TokenBridgeProps>;
 
 /**
  * Main authentication hook for accessing Keycloak authentication state and methods
@@ -1397,6 +1473,24 @@ declare class KeycloakConfigBuilder {
  */
 declare function getConfigFromEnv(): Partial<KeycloakConfig>;
 
+type KeycloakDisabledReason = 'disabled' | 'missing-config';
+interface KeycloakStatus {
+    /**
+     * Whether the Keycloak integration is enabled by configuration.
+     */
+    isEnabled: boolean;
+    /**
+     * Whether the minimum configuration (authority + clientId) is present.
+     */
+    isConfigured: boolean;
+    /**
+     * Provides additional context when integration is disabled.
+     */
+    reason?: KeycloakDisabledReason;
+}
+declare const KeycloakStatusProvider: React$1.Provider<KeycloakStatus>;
+declare const useKeycloakStatus: () => KeycloakStatus;
+
 /**
  * Device authorization response from Keycloak
  */
@@ -1508,4 +1602,4 @@ declare function pollForToken(apiBaseUrl: string, deviceCode: string): Promise<T
  */
 declare function fetchUserInfo(apiBaseUrl: string, accessToken: string): Promise<any>;
 
-export { type AdvancedOidcOptions, CONFIG_PRESETS, type ConfigPreset, type DeviceAuthorizationResponse, type DeviceFlowError, DeviceLogin, type DeviceLoginProps, type EventCallbacks, type FeatureFlags, type KeycloakConfig, KeycloakConfigBuilder, KeycloakProvider, type KeycloakProviderFullConfigProps, type KeycloakProviderProps, type KeycloakProviderZeroConfigProps, LoginButton, type LoginButtonProps, LogoutButton, type LogoutButtonProps, type PolicyContext, type PolicyFunction, ProtectedRoute, type ProtectedRouteProps, SessionMonitor, type SessionMonitorProps, type SilentRenewConfig, TokenLifecycleManager, type TokenLifecycleManagerProps, type TokenResponse, type UseProtectedFetchOptions, type UseProtectedFetchReturn, type UseRolesReturn, type UseScopesReturn, type UseTokenLifecycleOptions, type UseTokenLifecycleReturn, UserProfile, type UserProfileProps, defaultConfig, fetchUserInfo, getConfigFromEnv, getConfigPreset, mergeWithPreset, pollForToken, requestDeviceCode, useAuth, useProtectedFetch, useRoles, useScopes, useTokenLifecycle };
+export { type AdvancedOidcOptions, CONFIG_PRESETS, type ConfigPreset, type DeviceAuthorizationResponse, type DeviceFlowError, DeviceLogin, type DeviceLoginProps, type EventCallbacks, type FeatureFlags, type KeycloakConfig, KeycloakConfigBuilder, type KeycloakDisabledReason, KeycloakProvider, type KeycloakProviderFullConfigProps, type KeycloakProviderProps, type KeycloakProviderZeroConfigProps, type KeycloakStatus, KeycloakStatusProvider, LoginButton, type LoginButtonProps, LogoutButton, type LogoutButtonProps, type PolicyContext, type PolicyFunction, ProtectedRoute, type ProtectedRouteProps, SessionMonitor, type SessionMonitorProps, type SilentRenewConfig, TokenBridge, type TokenBridgeProps, TokenBridgeSync, TokenLifecycleManager, type TokenLifecycleManagerProps, type TokenListener, type TokenResponse, type UseProtectedFetchOptions, type UseProtectedFetchReturn, type UseRolesReturn, type UseScopesReturn, type UseTokenLifecycleOptions, type UseTokenLifecycleReturn, UserProfile, type UserProfileProps, createTokenBridge, defaultConfig, defaultTokenBridge, fetchUserInfo, getConfigFromEnv, getConfigPreset, mergeWithPreset, pollForToken, requestDeviceCode, useAuth, useKeycloakStatus, useProtectedFetch, useRoles, useScopes, useTokenLifecycle };