antaeus.keycloak.react 1.0.6 → 2.0.0

package/dist/index.d.mts

@@ -86,6 +86,33 @@ interface SilentRenewConfig {
      * @default 300 (5 minutes)
      */
     thresholdSeconds?: number;
+    /**
+     * When to check and refresh tokens
+     * - 'startup': Check immediately on app startup (proactive)
+     * - 'on-demand': Only refresh when API calls fail with 401 (reactive)
+     * - 'both': Check on startup AND retry on 401 (recommended)
+     * @default 'both'
+     */
+    refreshStrategy?: 'startup' | 'on-demand' | 'both';
+    /**
+     * Maximum lifetime for refresh token in seconds
+     * After this duration, user must re-authenticate
+     * Set to 0 or undefined for no limit
+     * @default 2592000 (30 days)
+     * @example 86400 (24 hours), 604800 (7 days)
+     */
+    maxRefreshTokenLifetime?: number;
+    /**
+     * Show loading indicator during automatic token refresh
+     * @default false
+     */
+    showLoadingIndicator?: boolean;
+    /**
+     * Custom loading message to display during refresh
+     * Only used if showLoadingIndicator is true
+     * @default 'Refreshing session...'
+     */
+    loadingMessage?: string;
 }
 /**
  * Event callbacks for authentication lifecycle
@@ -138,9 +165,89 @@ interface AdvancedOidcOptions {
     automaticSilentSignIn?: boolean;
 }
 
-interface KeycloakProviderProps {
+/**
+ * Configuration preset types
+ */
+type ConfigPreset = 'default' | 'mobile' | 'high-security' | 'long-running' | 'development';
+/**
+ * Configuration presets for common use cases
+ *
+ * These presets provide optimized configurations for different application types
+ * and security requirements. All presets can be further customized by overriding
+ * specific properties.
+ */
+declare const CONFIG_PRESETS: Record<ConfigPreset, Partial<KeycloakConfig>>;
+/**
+ * Get a configuration preset by name
+ *
+ * @param preset - The preset name
+ * @returns Partial Keycloak configuration for the preset
+ *
+ * @example
+ * ```typescript
+ * const config = getConfigPreset('mobile');
+ * ```
+ */
+declare function getConfigPreset(preset: ConfigPreset): Partial<KeycloakConfig>;
+/**
+ * Merge a preset with custom configuration
+ *
+ * Custom configuration takes precedence over preset values.
+ * Use this to start with a preset and override specific properties.
+ *
+ * @param preset - The preset name
+ * @param customConfig - Custom configuration to merge
+ * @returns Merged configuration
+ *
+ * @example
+ * ```typescript
+ * const config = mergeWithPreset('mobile', {
+ *   silentRenew: {
+ *     maxRefreshTokenLifetime: 604800, // Override to 7 days
+ *   }
+ * });
+ * ```
+ */
+declare function mergeWithPreset(preset: ConfigPreset, customConfig: Partial<KeycloakConfig>): Partial<KeycloakConfig>;
+
+/**
+ * Props for zero-config mode (simplified setup)
+ */
+interface KeycloakProviderZeroConfigProps {
     /**
-     * Keycloak configuration
+     * Keycloak realm authority URL (e.g., https://sso.example.com/realms/myrealm)
+     */
+    authority: string;
+    /**
+     * Client ID registered in Keycloak
+     */
+    clientId: string;
+    /**
+     * Configuration preset to use
+     * @default 'default'
+     */
+    preset?: ConfigPreset;
+    /**
+     * Child components to render
+     */
+    children: React.ReactNode;
+    /**
+     * Enable debug logging to console
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Override specific configuration properties
+     * Use this to customize preset or zero-config defaults
+     */
+    config?: Partial<Omit<KeycloakConfig, 'authority' | 'clientId'>>;
+}
+/**
+ * Props for full-config mode (advanced setup)
+ */
+interface KeycloakProviderFullConfigProps {
+    /**
+     * Full Keycloak configuration object
      */
     config: KeycloakConfig;
     /**
@@ -153,30 +260,110 @@ interface KeycloakProviderProps {
      */
     debug?: boolean;
 }
+/**
+ * Combined props type
+ */
+type KeycloakProviderProps = KeycloakProviderZeroConfigProps | KeycloakProviderFullConfigProps;
 /**
  * Main Keycloak authentication provider component
  *
- * Wraps your application to provide authentication context using Keycloak.
- * This component handles all OIDC flows including login, logout, token refresh,
- * and silent renewal.
+ * This component wraps your application to provide authentication context using Keycloak.
+ * It supports both zero-config mode (for simplicity) and full-config mode (for advanced use cases).
  *
- * @example
+ * ## Zero-Config Mode (Recommended)
+ *
+ * Minimal setup with sensible defaults and automatic feature enablement.
+ *
+ * @example Zero-config (simplest)
  * ```tsx
  * import { KeycloakProvider } from 'antaeus.keycloak.react';
  *
  * function App() {
  *   return (
  *     <KeycloakProvider
- *       config={{
- *         authority: 'https://sso.example.com/realms/myrealm',
- *         clientId: 'my-app',
- *       }}
+ *       authority="https://sso.example.com/realms/myrealm"
+ *       clientId="my-app"
  *     >
  *       <YourApp />
  *     </KeycloakProvider>
  *   );
  * }
  * ```
+ *
+ * @example Zero-config with preset
+ * ```tsx
+ * <KeycloakProvider
+ *   authority="https://sso.example.com/realms/myrealm"
+ *   clientId="my-app"
+ *   preset="mobile"  // or 'high-security', 'long-running', 'development'
+ * >
+ *   <YourApp />
+ * </KeycloakProvider>
+ * ```
+ *
+ * @example Zero-config with overrides
+ * ```tsx
+ * <KeycloakProvider
+ *   authority="https://sso.example.com/realms/myrealm"
+ *   clientId="my-app"
+ *   preset="default"
+ *   config={{
+ *     silentRenew: {
+ *       maxRefreshTokenLifetime: 604800, // Override: 7 days instead of 30
+ *       showLoadingIndicator: true,
+ *     }
+ *   }}
+ *   debug={true}
+ * >
+ *   <YourApp />
+ * </KeycloakProvider>
+ * ```
+ *
+ * ## Full-Config Mode (Advanced)
+ *
+ * Complete control over all configuration options.
+ *
+ * @example Full configuration
+ * ```tsx
+ * <KeycloakProvider
+ *   config={{
+ *     authority: 'https://sso.example.com/realms/myrealm',
+ *     clientId: 'my-app',
+ *     redirectUri: window.location.origin,
+ *     scope: 'openid profile email offline_access',
+ *     features: {
+ *       autoRefresh: true,
+ *       sessionMonitor: true,
+ *     },
+ *     silentRenew: {
+ *       enabled: true,
+ *       refreshStrategy: 'both',
+ *       maxRefreshTokenLifetime: 2592000,
+ *     },
+ *     events: {
+ *       onLogin: (user) => console.log('User logged in', user),
+ *       onError: (error) => sendToSentry(error),
+ *     }
+ *   }}
+ *   debug={true}
+ * >
+ *   <YourApp />
+ * </KeycloakProvider>
+ * ```
+ *
+ * ## Features Automatically Enabled
+ *
+ * When using zero-config or presets, the following features are automatically enabled:
+ * - ✅ Automatic token refresh (before expiration)
+ * - ✅ Token lifecycle management (refresh on app startup)
+ * - ✅ Session monitoring UI (countdown timer)
+ * - ✅ Silent renew (background token refresh)
+ * - ✅ Error notifications (user-friendly messages)
+ * - ✅ 401 retry logic (automatic token refresh on API errors)
+ * - ✅ Maximum refresh token lifetime (security control)
+ * - ✅ PKCE (for secure public clients)
+ *
+ * All features can be disabled or customized via configuration overrides.
  */
 declare const KeycloakProvider: React.FC<KeycloakProviderProps>;
 
@@ -749,6 +936,38 @@ interface DeviceLoginProps {
  */
 declare const DeviceLogin: React.FC<DeviceLoginProps>;
 
+interface TokenLifecycleManagerProps {
+    /**
+     * Keycloak configuration
+     */
+    config: KeycloakConfig;
+    /**
+     * Child components to render
+     */
+    children: React.ReactNode;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Component that manages token lifecycle including startup refresh and max lifetime tracking
+ *
+ * This component wraps your app and automatically:
+ * - Checks tokens on app startup and refreshes if needed
+ * - Tracks refresh token max lifetime
+ * - Shows optional loading indicator during refresh
+ *
+ * @example
+ * ```tsx
+ * <TokenLifecycleManager config={config} debug={true}>
+ *   <YourApp />
+ * </TokenLifecycleManager>
+ * ```
+ */
+declare const TokenLifecycleManager: React.FC<TokenLifecycleManagerProps>;
+
 /**
  * Main authentication hook for accessing Keycloak authentication state and methods
  *
@@ -1040,6 +1259,83 @@ interface UseProtectedFetchReturn {
  */
 declare function useProtectedFetch(options?: UseProtectedFetchOptions): UseProtectedFetchReturn;
 
+interface UseTokenLifecycleOptions {
+    /**
+     * Keycloak configuration for token lifecycle settings
+     */
+    config: KeycloakConfig;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Callback when token refresh starts
+     */
+    onRefreshStart?: () => void;
+    /**
+     * Callback when token refresh succeeds
+     */
+    onRefreshSuccess?: () => void;
+    /**
+     * Callback when token refresh fails
+     */
+    onRefreshError?: (error: Error) => void;
+    /**
+     * Callback when refresh token lifetime expires
+     */
+    onRefreshTokenExpired?: () => void;
+}
+interface UseTokenLifecycleReturn {
+    /**
+     * Whether token is being refreshed
+     */
+    isRefreshing: boolean;
+    /**
+     * Whether refresh token has exceeded max lifetime
+     */
+    isRefreshTokenExpired: boolean;
+    /**
+     * Manually trigger token refresh
+     */
+    refreshToken: () => Promise<void>;
+    /**
+     * Check if tokens need refresh and do it if needed
+     */
+    checkAndRefreshTokens: () => Promise<boolean>;
+}
+/**
+ * Hook to manage token lifecycle including startup refresh and max lifetime tracking
+ *
+ * This hook provides proactive token management:
+ * - Checks tokens on app startup and refreshes if needed
+ * - Tracks refresh token max lifetime
+ * - Provides manual refresh capabilities
+ *
+ * @param options - Configuration options
+ * @returns Token lifecycle methods and state
+ *
+ * @example
+ * ```tsx
+ * import { useTokenLifecycle } from 'antaeus.keycloak.react';
+ *
+ * function App() {
+ *   const { isRefreshing, isRefreshTokenExpired } = useTokenLifecycle({
+ *     config: myConfig,
+ *     onRefreshStart: () => console.log('Refreshing...'),
+ *     onRefreshSuccess: () => console.log('Refreshed!'),
+ *     onRefreshError: (error) => console.error('Failed:', error),
+ *   });
+ *
+ *   if (isRefreshing) return <div>Loading...</div>;
+ *   if (isRefreshTokenExpired) return <div>Please sign in again</div>;
+ *
+ *   return <YourApp />;
+ * }
+ * ```
+ */
+declare function useTokenLifecycle(options: UseTokenLifecycleOptions): UseTokenLifecycleReturn;
+
 /**
  * Default configuration values for Keycloak integration
  */
@@ -1190,4 +1486,4 @@ declare function pollForToken(apiBaseUrl: string, deviceCode: string): Promise<T
  */
 declare function fetchUserInfo(apiBaseUrl: string, accessToken: string): Promise<any>;
 
-export { type AdvancedOidcOptions, type DeviceAuthorizationResponse, type DeviceFlowError, DeviceLogin, type DeviceLoginProps, type EventCallbacks, type FeatureFlags, type KeycloakConfig, KeycloakConfigBuilder, KeycloakProvider, type KeycloakProviderProps, LoginButton, type LoginButtonProps, LogoutButton, type LogoutButtonProps, type PolicyContext, type PolicyFunction, ProtectedRoute, type ProtectedRouteProps, SessionMonitor, type SessionMonitorProps, type SilentRenewConfig, type TokenResponse, type UseProtectedFetchOptions, type UseProtectedFetchReturn, type UseRolesReturn, type UseScopesReturn, UserProfile, type UserProfileProps, defaultConfig, fetchUserInfo, getConfigFromEnv, pollForToken, requestDeviceCode, useAuth, useProtectedFetch, useRoles, useScopes };
+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 };