antaeus.keycloak.react 1.0.6

package/dist/index.d.mts

@@ -0,0 +1,1193 @@
+import React from 'react';
+import { User, UserManagerSettings } from 'oidc-client-ts';
+export { User } from 'oidc-client-ts';
+import { useLocation } from 'react-router-dom';
+import * as react_oidc_context from 'react-oidc-context';
+export { AuthContextProps as UseAuthReturn } from 'react-oidc-context';
+
+/**
+ * Main configuration interface for Keycloak integration
+ */
+interface KeycloakConfig {
+    /**
+     * Keycloak realm authority URL (e.g., https://sso.example.com/realms/myrealm)
+     */
+    authority: string;
+    /**
+     * Client ID registered in Keycloak
+     */
+    clientId: string;
+    /**
+     * Redirect URI after login (defaults to current origin)
+     */
+    redirectUri?: string;
+    /**
+     * Redirect URI after logout (defaults to current origin)
+     */
+    postLogoutRedirectUri?: string;
+    /**
+     * OAuth2 scopes to request
+     * @default 'openid profile email offline_access'
+     */
+    scope?: string;
+    /**
+     * Feature flags to enable/disable functionality
+     */
+    features?: FeatureFlags;
+    /**
+     * Silent token renewal configuration
+     */
+    silentRenew?: SilentRenewConfig;
+    /**
+     * Event callbacks
+     */
+    events?: EventCallbacks;
+    /**
+     * Advanced OIDC options
+     */
+    advanced?: AdvancedOidcOptions;
+}
+/**
+ * Feature flags for optional Keycloak functionality
+ */
+interface FeatureFlags {
+    /**
+     * Enable device flow authentication
+     * @default false
+     */
+    deviceFlow?: boolean;
+    /**
+     * Enable session monitoring UI
+     * @default false
+     */
+    sessionMonitor?: boolean;
+    /**
+     * Enable automatic token refresh
+     * @default true
+     */
+    autoRefresh?: boolean;
+}
+/**
+ * Silent token renewal configuration
+ */
+interface SilentRenewConfig {
+    /**
+     * Enable silent token renewal
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Path to silent renew HTML file
+     * @default '/silent-renew.html'
+     */
+    silentRedirectUri?: string;
+    /**
+     * Threshold in seconds before expiry to trigger renewal
+     * @default 300 (5 minutes)
+     */
+    thresholdSeconds?: number;
+}
+/**
+ * Event callbacks for authentication lifecycle
+ */
+interface EventCallbacks {
+    /**
+     * Called after successful login
+     */
+    onLogin?: (user: User) => void;
+    /**
+     * Called after logout
+     */
+    onLogout?: () => void;
+    /**
+     * Called when token expires
+     */
+    onTokenExpired?: () => void;
+    /**
+     * Called on authentication errors
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Called on silent renew error
+     */
+    onSilentRenewError?: (error: Error) => void;
+}
+/**
+ * Advanced OIDC configuration options
+ */
+interface AdvancedOidcOptions {
+    /**
+     * Response type
+     * @default 'code'
+     */
+    responseType?: string;
+    /**
+     * PKCE code challenge method
+     * @default 'S256'
+     */
+    codeChallengeMethod?: string;
+    /**
+     * Load user info from userinfo endpoint
+     * @default true
+     */
+    loadUserInfo?: boolean;
+    /**
+     * Automatically sign in if session exists
+     * @default false
+     */
+    automaticSilentSignIn?: boolean;
+}
+
+interface KeycloakProviderProps {
+    /**
+     * Keycloak configuration
+     */
+    config: KeycloakConfig;
+    /**
+     * Child components to render
+     */
+    children: React.ReactNode;
+    /**
+     * Enable debug logging to console
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * import { KeycloakProvider } from 'antaeus.keycloak.react';
+ *
+ * function App() {
+ *   return (
+ *     <KeycloakProvider
+ *       config={{
+ *         authority: 'https://sso.example.com/realms/myrealm',
+ *         clientId: 'my-app',
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </KeycloakProvider>
+ *   );
+ * }
+ * ```
+ */
+declare const KeycloakProvider: React.FC<KeycloakProviderProps>;
+
+/**
+ * Context object passed to custom policy function
+ */
+interface PolicyContext {
+    /**
+     * Current location from react-router
+     */
+    location: ReturnType<typeof useLocation>;
+    /**
+     * Any additional context you want to pass
+     */
+    [key: string]: any;
+}
+/**
+ * Custom policy function for fine-grained access control
+ */
+type PolicyFunction = (user: User, context: PolicyContext) => boolean;
+interface ProtectedRouteProps {
+    /**
+     * Child components to render when user is authorized
+     */
+    children: React.ReactNode;
+    /**
+     * Required realm roles (OR logic - user needs at least one)
+     */
+    requiredRoles?: string[];
+    /**
+     * Require all roles instead of any (AND logic)
+     * @default false
+     */
+    requireAllRoles?: boolean;
+    /**
+     * Required OAuth 2.0 scopes (OR logic - user needs at least one)
+     */
+    requiredScopes?: string[];
+    /**
+     * Require all scopes instead of any (AND logic)
+     * @default false
+     */
+    requireAllScopes?: boolean;
+    /**
+     * Custom policy function for advanced authorization logic
+     * If provided, this takes precedence over role and scope checks
+     */
+    policy?: PolicyFunction;
+    /**
+     * Custom loading component to display while checking authentication
+     */
+    loadingComponent?: React.ReactNode;
+    /**
+     * Custom unauthorized component to display when user lacks required permissions
+     */
+    unauthorizedComponent?: React.ReactNode;
+    /**
+     * Path to redirect to if not authenticated
+     * @default '/login'
+     */
+    redirectTo?: string;
+    /**
+     * Callback when user is unauthorized
+     * @param reason - Reason for unauthorized access
+     */
+    onUnauthorized?: (reason: 'not-authenticated' | 'insufficient-roles' | 'insufficient-scopes' | 'policy-denied') => void;
+}
+/**
+ * Component for protecting routes with authentication, role-based, scope-based, or policy-based authorization
+ *
+ * This component provides comprehensive route protection with multiple authorization strategies:
+ * - Authentication check (always required)
+ * - Role-based authorization (realm roles)
+ * - Scope-based authorization (OAuth 2.0 scopes)
+ * - Custom policy functions (advanced logic)
+ *
+ * @example Basic authentication required
+ * ```tsx
+ * import { ProtectedRoute } from 'antaeus.keycloak.react';
+ *
+ * <Route
+ *   path="/dashboard"
+ *   element={
+ *     <ProtectedRoute>
+ *       <Dashboard />
+ *     </ProtectedRoute>
+ *   }
+ * />
+ * ```
+ *
+ * @example Require specific role
+ * ```tsx
+ * <Route
+ *   path="/admin"
+ *   element={
+ *     <ProtectedRoute requiredRoles={['admin']}>
+ *       <AdminPanel />
+ *     </ProtectedRoute>
+ *   }
+ * />
+ * ```
+ *
+ * @example Require any of multiple roles
+ * ```tsx
+ * <ProtectedRoute requiredRoles={['editor', 'moderator', 'admin']}>
+ *   <EditPage />
+ * </ProtectedRoute>
+ * ```
+ *
+ * @example Require all roles (AND logic)
+ * ```tsx
+ * <ProtectedRoute
+ *   requiredRoles={['verified', 'premium']}
+ *   requireAllRoles={true}
+ * >
+ *   <PremiumContent />
+ * </ProtectedRoute>
+ * ```
+ *
+ * @example Require specific scopes
+ * ```tsx
+ * <ProtectedRoute requiredScopes={['read:users', 'write:users']}>
+ *   <UserManagement />
+ * </ProtectedRoute>
+ * ```
+ *
+ * @example Require all scopes (AND logic)
+ * ```tsx
+ * <ProtectedRoute
+ *   requiredScopes={['read:data', 'write:data', 'delete:data']}
+ *   requireAllScopes={true}
+ * >
+ *   <DataAdmin />
+ * </ProtectedRoute>
+ * ```
+ *
+ * @example Combine roles and scopes
+ * ```tsx
+ * <ProtectedRoute
+ *   requiredRoles={['admin']}
+ *   requiredScopes={['manage:users']}
+ * >
+ *   <UserAdmin />
+ * </ProtectedRoute>
+ * ```
+ *
+ * @example Custom policy function
+ * ```tsx
+ * <ProtectedRoute
+ *   policy={(user, context) => {
+ *     // Custom authorization logic
+ *     const isEmailVerified = user.profile.email_verified === true;
+ *     const isAdult = (user.profile.age || 0) >= 18;
+ *     return isEmailVerified && isAdult;
+ *   }}
+ *   onUnauthorized={(reason) => {
+ *     console.log('Access denied:', reason);
+ *   }}
+ * >
+ *   <AdultContent />
+ * </ProtectedRoute>
+ * ```
+ *
+ * @example Advanced policy with location context
+ * ```tsx
+ * <ProtectedRoute
+ *   policy={(user, context) => {
+ *     // Check if user is accessing during business hours
+ *     const hour = new Date().getHours();
+ *     const isBusinessHours = hour >= 9 && hour < 17;
+ *
+ *     // Or check based on route
+ *     const isAdminRoute = context.location.pathname.startsWith('/admin');
+ *     const hasAdminRole = user.profile.realm_access?.roles?.includes('admin');
+ *
+ *     return isBusinessHours && (!isAdminRoute || hasAdminRole);
+ *   }}
+ * >
+ *   <TimeSensitiveContent />
+ * </ProtectedRoute>
+ * ```
+ */
+declare const ProtectedRoute: React.FC<ProtectedRouteProps>;
+
+interface LoginButtonProps {
+    /**
+     * Button text
+     * @default 'Login'
+     */
+    children?: React.ReactNode;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+    /**
+     * Button variant
+     * @default 'primary'
+     */
+    variant?: 'primary' | 'secondary' | 'outline';
+    /**
+     * Button size
+     * @default 'medium'
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Show login icon
+     * @default true
+     */
+    showIcon?: boolean;
+    /**
+     * Callback before login starts
+     */
+    onLoginStart?: () => void;
+    /**
+     * Custom inline styles
+     */
+    style?: React.CSSProperties;
+    /**
+     * Disable the button
+     */
+    disabled?: boolean;
+}
+/**
+ * Pre-built login button component
+ *
+ * Triggers the Keycloak login flow when clicked. The button automatically
+ * hides when the user is already authenticated.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { LoginButton } from 'antaeus.keycloak.react';
+ *
+ * function Header() {
+ *   return <LoginButton />;
+ * }
+ * ```
+ *
+ * @example Customized
+ * ```tsx
+ * <LoginButton
+ *   variant="outline"
+ *   size="large"
+ *   onLoginStart={() => console.log('Starting login...')}
+ * >
+ *   Sign In
+ * </LoginButton>
+ * ```
+ *
+ * @example With custom styling
+ * ```tsx
+ * <LoginButton
+ *   className="my-custom-class"
+ *   style={{ backgroundColor: '#007bff' }}
+ * />
+ * ```
+ */
+declare const LoginButton: React.FC<LoginButtonProps>;
+
+interface LogoutButtonProps {
+    /**
+     * Button text
+     * @default 'Logout'
+     */
+    children?: React.ReactNode;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+    /**
+     * Button variant
+     * @default 'secondary'
+     */
+    variant?: 'primary' | 'secondary' | 'outline';
+    /**
+     * Button size
+     * @default 'medium'
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Show logout icon
+     * @default true
+     */
+    showIcon?: boolean;
+    /**
+     * Callback before logout starts
+     */
+    onLogoutStart?: () => void;
+    /**
+     * Custom inline styles
+     */
+    style?: React.CSSProperties;
+    /**
+     * Disable the button
+     */
+    disabled?: boolean;
+}
+/**
+ * Pre-built logout button component
+ *
+ * Triggers the Keycloak logout flow when clicked. The button automatically
+ * hides when the user is not authenticated.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { LogoutButton } from 'antaeus.keycloak.react';
+ *
+ * function Header() {
+ *   return <LogoutButton />;
+ * }
+ * ```
+ *
+ * @example Customized
+ * ```tsx
+ * <LogoutButton
+ *   variant="outline"
+ *   size="small"
+ *   onLogoutStart={() => {
+ *     // Clean up app state
+ *     localStorage.clear();
+ *   }}
+ * >
+ *   Sign Out
+ * </LogoutButton>
+ * ```
+ *
+ * @example With custom styling
+ * ```tsx
+ * <LogoutButton
+ *   className="my-logout-btn"
+ *   style={{ backgroundColor: '#dc3545' }}
+ * />
+ * ```
+ */
+declare const LogoutButton: React.FC<LogoutButtonProps>;
+
+interface UserProfileProps {
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+    /**
+     * Show user avatar/icon
+     * @default true
+     */
+    showAvatar?: boolean;
+    /**
+     * Show user email
+     * @default true
+     */
+    showEmail?: boolean;
+    /**
+     * Show user roles
+     * @default false
+     */
+    showRoles?: boolean;
+    /**
+     * Avatar size in pixels
+     * @default 40
+     */
+    avatarSize?: number;
+    /**
+     * Custom inline styles
+     */
+    style?: React.CSSProperties;
+    /**
+     * Callback when profile is clicked
+     */
+    onClick?: () => void;
+}
+/**
+ * Pre-built user profile display component
+ *
+ * Displays the current user's information including name, email, and optionally roles.
+ * Automatically hides when user is not authenticated.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { UserProfile } from 'antaeus.keycloak.react';
+ *
+ * function Header() {
+ *   return <UserProfile />;
+ * }
+ * ```
+ *
+ * @example With roles
+ * ```tsx
+ * <UserProfile showRoles={true} />
+ * ```
+ *
+ * @example Clickable profile
+ * ```tsx
+ * <UserProfile
+ *   onClick={() => navigate('/profile')}
+ *   style={{ cursor: 'pointer' }}
+ * />
+ * ```
+ *
+ * @example Customized
+ * ```tsx
+ * <UserProfile
+ *   showEmail={false}
+ *   showRoles={true}
+ *   avatarSize={50}
+ *   className="my-profile"
+ * />
+ * ```
+ */
+declare const UserProfile: React.FC<UserProfileProps>;
+
+interface SessionMonitorProps {
+    /**
+     * Position on screen
+     * @default 'top-right'
+     */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /**
+     * Warning threshold in seconds (yellow state)
+     * @default 300 (5 minutes)
+     */
+    warningThreshold?: number;
+    /**
+     * Critical threshold in seconds (red state)
+     * @default 60 (1 minute)
+     */
+    criticalThreshold?: number;
+    /**
+     * Show progress bar
+     * @default true
+     */
+    showProgressBar?: boolean;
+    /**
+     * Allow minimize/expand
+     * @default true
+     */
+    minimizable?: boolean;
+    /**
+     * Start minimized
+     * @default false
+     */
+    startMinimized?: boolean;
+    /**
+     * Custom CSS class names
+     */
+    className?: string;
+    /**
+     * Callback when warning threshold is reached
+     */
+    onWarning?: (secondsRemaining: number) => void;
+    /**
+     * Callback when critical threshold is reached
+     */
+    onCritical?: (secondsRemaining: number) => void;
+    /**
+     * Callback when session expires
+     */
+    onExpired?: () => void;
+    /**
+     * Custom inline styles
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * Session monitoring component with countdown timer
+ *
+ * Displays the time remaining until the user's session expires. Shows visual
+ * warnings when the session is about to expire and triggers callbacks for
+ * custom handling.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { SessionMonitor } from 'antaeus.keycloak.react';
+ *
+ * function App() {
+ *   return (
+ *     <>
+ *       <SessionMonitor />
+ *       <YourApp />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom thresholds
+ * ```tsx
+ * <SessionMonitor
+ *   warningThreshold={600}  // 10 minutes
+ *   criticalThreshold={120} // 2 minutes
+ *   onWarning={(seconds) => {
+ *     console.log(`Session expiring in ${seconds} seconds`);
+ *   }}
+ * />
+ * ```
+ *
+ * @example Custom position and style
+ * ```tsx
+ * <SessionMonitor
+ *   position="bottom-left"
+ *   showProgressBar={false}
+ *   minimizable={false}
+ * />
+ * ```
+ */
+declare const SessionMonitor: React.FC<SessionMonitorProps>;
+
+interface DeviceLoginProps {
+    /**
+     * API base URL for device flow endpoints
+     * @example 'http://localhost:5000'
+     */
+    apiBaseUrl: string;
+    /**
+     * QR code size in pixels
+     * @default 256
+     */
+    qrCodeSize?: number;
+    /**
+     * Polling interval in seconds
+     * @default 5
+     */
+    pollingInterval?: number;
+    /**
+     * Custom CSS class
+     */
+    className?: string;
+    /**
+     * Callback on successful login
+     */
+    onSuccess?: (user: User) => void;
+    /**
+     * Callback on error
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Custom inline styles
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * Device flow login component
+ *
+ * Displays QR code and user code for device authentication. Automatically polls
+ * for authorization and completes the login flow.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { DeviceLogin } from 'antaeus.keycloak.react';
+ *
+ * function TVLoginPage() {
+ *   return (
+ *     <DeviceLogin
+ *       apiBaseUrl="http://localhost:5000"
+ *       onSuccess={(user) => {
+ *         console.log('Logged in:', user.profile.name);
+ *         navigate('/home');
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom settings
+ * ```tsx
+ * <DeviceLogin
+ *   apiBaseUrl="http://localhost:5000"
+ *   qrCodeSize={300}
+ *   pollingInterval={3}
+ *   onError={(error) => console.error('Login failed:', error)}
+ * />
+ * ```
+ */
+declare const DeviceLogin: React.FC<DeviceLoginProps>;
+
+/**
+ * Main authentication hook for accessing Keycloak authentication state and methods
+ *
+ * This hook provides access to the current user, authentication state, and methods
+ * for signing in and out. It must be used within a KeycloakProvider component.
+ *
+ * @returns Authentication state and methods
+ *
+ * @example
+ * ```tsx
+ * import { useAuth } from 'antaeus.keycloak.react';
+ *
+ * function MyComponent() {
+ *   const auth = useAuth();
+ *
+ *   if (auth.isLoading) {
+ *     return <div>Loading...</div>;
+ *   }
+ *
+ *   if (!auth.isAuthenticated) {
+ *     return <button onClick={() => auth.signinRedirect()}>Login</button>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <p>Welcome, {auth.user?.profile?.name}</p>
+ *       <button onClick={() => auth.signoutRedirect()}>Logout</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Role checking
+ * ```tsx
+ * function AdminPanel() {
+ *   const auth = useAuth();
+ *   const roles = auth.user?.profile?.realm_access?.roles || [];
+ *
+ *   if (!roles.includes('admin')) {
+ *     return <div>Access denied</div>;
+ *   }
+ *
+ *   return <div>Admin panel content</div>;
+ * }
+ * ```
+ */
+declare const useAuth: () => react_oidc_context.AuthContextProps;
+
+interface UseRolesReturn {
+    /**
+     * Array of realm roles assigned to the current user
+     */
+    roles: string[];
+    /**
+     * Checks if user has a specific realm role
+     * @param role - Role name to check
+     * @returns True if user has the role
+     */
+    hasRole: (role: string) => boolean;
+    /**
+     * Checks if user has any of the specified roles (OR logic)
+     * @param roles - Array of role names
+     * @returns True if user has at least one of the roles
+     */
+    hasAnyRole: (roles: string[]) => boolean;
+    /**
+     * Checks if user has all of the specified roles (AND logic)
+     * @param roles - Array of role names
+     * @returns True if user has all the roles
+     */
+    hasAllRoles: (roles: string[]) => boolean;
+    /**
+     * Gets client-specific roles
+     * @param clientId - Client ID to get roles for
+     * @returns Array of client roles
+     */
+    getClientRoles: (clientId: string) => string[];
+}
+/**
+ * Hook for working with Keycloak roles
+ *
+ * Provides convenient methods for checking user roles, both realm-level and client-level.
+ * Must be used within a KeycloakProvider component.
+ *
+ * @returns Role utilities and methods
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useRoles } from 'antaeus.keycloak.react';
+ *
+ * function MyComponent() {
+ *   const { roles, hasRole, hasAnyRole } = useRoles();
+ *
+ *   return (
+ *     <div>
+ *       <p>Your roles: {roles.join(', ')}</p>
+ *       {hasRole('admin') && <AdminPanel />}
+ *       {hasAnyRole(['editor', 'moderator']) && <EditButton />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Client roles
+ * ```tsx
+ * function ClientRoleExample() {
+ *   const { getClientRoles } = useRoles();
+ *   const apiRoles = getClientRoles('my-api');
+ *
+ *   return <div>API roles: {apiRoles.join(', ')}</div>;
+ * }
+ * ```
+ */
+declare function useRoles(): UseRolesReturn;
+
+/**
+ * Return type for useScopes hook
+ */
+interface UseScopesReturn {
+    /**
+     * Array of granted scopes
+     */
+    scopes: string[];
+    /**
+     * Check if user has a specific scope
+     */
+    hasScope: (scope: string) => boolean;
+    /**
+     * Check if user has any of the specified scopes
+     */
+    hasAnyScope: (scopes: string[]) => boolean;
+    /**
+     * Check if user has all of the specified scopes
+     */
+    hasAllScopes: (scopes: string[]) => boolean;
+}
+/**
+ * Hook for checking OAuth 2.0 scopes
+ *
+ * Provides utilities for scope-based authorization. Scopes are typically space-separated
+ * in the token (e.g., "openid profile email read:users write:users").
+ *
+ * @returns Scope checking utilities
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useScopes } from 'antaeus.keycloak.react';
+ *
+ * function MyComponent() {
+ *   const { scopes, hasScope, hasAnyScope } = useScopes();
+ *
+ *   return (
+ *     <div>
+ *       <p>Your scopes: {scopes.join(', ')}</p>
+ *
+ *       {hasScope('read:users') && <UserList />}
+ *
+ *       {hasAnyScope(['write:users', 'admin']) && <CreateUserButton />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Conditional rendering
+ * ```tsx
+ * function DataActions() {
+ *   const { hasScope, hasAllScopes } = useScopes();
+ *
+ *   return (
+ *     <div>
+ *       {hasScope('read:data') && <ViewButton />}
+ *       {hasScope('write:data') && <EditButton />}
+ *       {hasScope('delete:data') && <DeleteButton />}
+ *       {hasAllScopes(['read:data', 'write:data']) && <ExportButton />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useScopes(): UseScopesReturn;
+
+interface UseProtectedFetchOptions {
+    /**
+     * Base URL for API requests
+     * @example 'http://localhost:5000'
+     */
+    baseUrl?: string;
+    /**
+     * Callback when request is unauthorized (401)
+     */
+    onUnauthorized?: () => void;
+    /**
+     * Retry request on 401 error after token refresh
+     * @default true
+     */
+    retryOn401?: boolean;
+    /**
+     * Additional headers to include in all requests
+     */
+    headers?: Record<string, string>;
+}
+interface UseProtectedFetchReturn {
+    /**
+     * Fetch with automatic token injection and JSON parsing
+     *
+     * @param url - URL or path to fetch
+     * @param init - Fetch init options
+     * @returns Parsed JSON response
+     */
+    fetchJson: <T = any>(url: string, init?: RequestInit) => Promise<T>;
+    /**
+     * Raw fetch with automatic token injection
+     *
+     * @param url - URL or path to fetch
+     * @param init - Fetch init options
+     * @returns Fetch response
+     */
+    fetch: (url: string, init?: RequestInit) => Promise<Response>;
+    /**
+     * Check if request is in progress
+     */
+    isLoading: boolean;
+}
+/**
+ * Hook for making authenticated API requests
+ *
+ * Automatically injects the current user's access token into all requests.
+ * Handles 401 errors and provides convenient methods for JSON APIs.
+ *
+ * @param options - Configuration options
+ * @returns Protected fetch methods
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useProtectedFetch } from 'antaeus.keycloak.react';
+ *
+ * function MyComponent() {
+ *   const { fetchJson } = useProtectedFetch({
+ *     baseUrl: 'http://localhost:5000'
+ *   });
+ *
+ *   const loadData = async () => {
+ *     // Token is automatically added
+ *     const data = await fetchJson('/api/data');
+ *     console.log(data);
+ *   };
+ *
+ *   return <button onClick={loadData}>Load Data</button>;
+ * }
+ * ```
+ *
+ * @example With custom headers
+ * ```tsx
+ * const { fetchJson } = useProtectedFetch({
+ *   baseUrl: 'http://localhost:5000',
+ *   headers: {
+ *     'X-Custom-Header': 'value'
+ *   }
+ * });
+ * ```
+ *
+ * @example POST request
+ * ```tsx
+ * const { fetchJson } = useProtectedFetch({
+ *   baseUrl: 'http://localhost:5000'
+ * });
+ *
+ * const createUser = async (userData: User) => {
+ *   const result = await fetchJson<User>('/api/users', {
+ *     method: 'POST',
+ *     body: JSON.stringify(userData),
+ *     headers: {
+ *       'Content-Type': 'application/json'
+ *     }
+ *   });
+ *   return result;
+ * };
+ * ```
+ *
+ * @example Handle unauthorized
+ * ```tsx
+ * const { fetchJson } = useProtectedFetch({
+ *   baseUrl: 'http://localhost:5000',
+ *   onUnauthorized: () => {
+ *     console.log('Unauthorized! Redirecting to login...');
+ *   }
+ * });
+ * ```
+ */
+declare function useProtectedFetch(options?: UseProtectedFetchOptions): UseProtectedFetchReturn;
+
+/**
+ * Default configuration values for Keycloak integration
+ */
+declare const defaultConfig: Partial<KeycloakConfig>;
+
+/**
+ * Configuration builder for Keycloak integration
+ */
+declare class KeycloakConfigBuilder {
+    /**
+     * Builds OIDC client configuration from Keycloak config
+     *
+     * @param userConfig - User-provided Keycloak configuration
+     * @returns OIDC client settings ready for react-oidc-context
+     * @throws Error if required fields are missing or invalid
+     */
+    static build(userConfig: KeycloakConfig): UserManagerSettings;
+    /**
+     * Validates required configuration fields
+     *
+     * @param config - Configuration to validate
+     * @throws Error if validation fails
+     */
+    private static validate;
+    /**
+     * Merges user configuration with defaults
+     *
+     * @param config - User configuration
+     * @returns Merged configuration with all defaults applied
+     */
+    private static mergeWithDefaults;
+}
+/**
+ * Helper function to get configuration from environment variables
+ *
+ * @returns Partial Keycloak configuration from environment
+ */
+declare function getConfigFromEnv(): Partial<KeycloakConfig>;
+
+/**
+ * Device authorization response from Keycloak
+ */
+interface DeviceAuthorizationResponse {
+    /** Device code used for polling */
+    device_code: string;
+    /** User code to display to user */
+    user_code: string;
+    /** Verification URI (plain) */
+    verification_uri: string;
+    /** Complete verification URI with user code (for QR codes) */
+    verification_uri_complete: string;
+    /** Expiration time in seconds */
+    expires_in: number;
+    /** Recommended polling interval in seconds */
+    interval: number;
+}
+/**
+ * Token response from Keycloak
+ */
+interface TokenResponse {
+    /** Access token */
+    access_token: string;
+    /** Token type (usually 'Bearer') */
+    token_type: string;
+    /** Expiration time in seconds */
+    expires_in: number;
+    /** Refresh token (if offline_access scope was requested) */
+    refresh_token?: string;
+    /** ID token */
+    id_token?: string;
+    /** Granted scopes */
+    scope?: string;
+}
+/**
+ * Error response from token polling
+ */
+interface DeviceFlowError {
+    /** Error code */
+    error: string;
+    /** Error description */
+    error_description?: string;
+}
+/**
+ * Request device authorization code from the backend API
+ *
+ * This function calls your backend API which proxies the request to Keycloak.
+ * This avoids CORS issues.
+ *
+ * @param apiBaseUrl - Base URL of your backend API (e.g., 'http://localhost:5000')
+ * @returns Device authorization response
+ * @throws Error if request fails
+ *
+ * @example
+ * ```ts
+ * const response = await requestDeviceCode('http://localhost:5000');
+ * console.log('User code:', response.user_code);
+ * console.log('Verification URL:', response.verification_uri_complete);
+ * ```
+ */
+declare function requestDeviceCode(apiBaseUrl: string): Promise<DeviceAuthorizationResponse>;
+/**
+ * Poll for token using device code
+ *
+ * This function should be called repeatedly until the user authorizes the device
+ * or the device code expires. The backend handles the actual token exchange with Keycloak.
+ *
+ * @param apiBaseUrl - Base URL of your backend API
+ * @param deviceCode - Device code from requestDeviceCode()
+ * @returns Token response if authorized, null if still pending
+ * @throws Error if request fails or authorization is denied
+ *
+ * @example
+ * ```ts
+ * const deviceCode = 'ABC123';
+ * const interval = setInterval(async () => {
+ *   try {
+ *     const token = await pollForToken('http://localhost:5000', deviceCode);
+ *     if (token) {
+ *       clearInterval(interval);
+ *       console.log('Authorized! Token:', token.access_token);
+ *     }
+ *   } catch (error) {
+ *     if (error.message.includes('authorization_pending')) {
+ *       // Still waiting, continue polling
+ *     } else {
+ *       // Real error, stop polling
+ *       clearInterval(interval);
+ *       console.error('Authorization failed:', error);
+ *     }
+ *   }
+ * }, 5000);
+ * ```
+ */
+declare function pollForToken(apiBaseUrl: string, deviceCode: string): Promise<TokenResponse | null>;
+/**
+ * Fetch user information using access token
+ *
+ * @param apiBaseUrl - Base URL of your backend API
+ * @param accessToken - Access token from token response
+ * @returns User information
+ * @throws Error if request fails
+ *
+ * @example
+ * ```ts
+ * const userInfo = await fetchUserInfo('http://localhost:5000', token.access_token);
+ * console.log('User:', userInfo.preferred_username);
+ * ```
+ */
+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 };