@chemmangat/msal-next 4.0.2 → 4.1.1

package/dist/index.d.mts

@@ -264,6 +264,41 @@ interface MsalAuthConfig {
      * ```
      */
     onInitialized?: (instance: IPublicClientApplication) => void;
+    /**
+     * Enable automatic token refresh
+     *
+     * @remarks
+     * Automatically refreshes access tokens before they expire to prevent
+     * session interruptions. Tokens are refreshed silently in the background.
+     *
+     * @defaultValue false
+     *
+     * @example
+     * ```tsx
+     * <MSALProvider
+     *   clientId="..."
+     *   autoRefreshToken={true}
+     *   refreshBeforeExpiry={300} // Refresh 5 min before expiry
+     * >
+     *   {children}
+     * </MSALProvider>
+     * ```
+     */
+    autoRefreshToken?: boolean;
+    /**
+     * Refresh token this many seconds before expiry
+     *
+     * @remarks
+     * Only used when autoRefreshToken is enabled.
+     *
+     * @defaultValue 300 (5 minutes)
+     *
+     * @example
+     * ```tsx
+     * refreshBeforeExpiry={600} // Refresh 10 minutes before expiry
+     * ```
+     */
+    refreshBeforeExpiry?: number;
 }
 /**
  * Props for MsalAuthProvider component
@@ -283,7 +318,7 @@ interface MsalAuthProviderProps extends MsalAuthConfig {
  * @returns The MSAL instance or null if not initialized
  */
 declare function getMsalInstance(): PublicClientApplication | null;
-declare function MsalAuthProvider({ children, loadingComponent, onInitialized, ...config }: MsalAuthProviderProps): react_jsx_runtime.JSX.Element;
+declare function MsalAuthProvider({ children, loadingComponent, onInitialized, autoRefreshToken, refreshBeforeExpiry, ...config }: MsalAuthProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Zero-Config Protected Routes - Type Definitions
@@ -393,12 +428,15 @@ interface MSALProviderProps extends MsalAuthProviderProps {
 }
 /**
  * Pre-configured MSALProvider component for Next.js App Router layouts.
- * This component is already marked as 'use client', so you can use it directly
- * in your server-side layout.tsx without needing to create a separate client component.
+ *
+ * @remarks
+ * This component is already marked as 'use client' internally, so you can import
+ * and use it directly in your server-side layout.tsx without adding 'use client'
+ * to your layout file.
  *
  * @example
  * ```tsx
- * // app/layout.tsx
+ * // app/layout.tsx (Server Component - no 'use client' needed!)
  * import { MSALProvider } from '@chemmangat/msal-next'
  *
  * export default function RootLayout({ children }) {
@@ -416,6 +454,13 @@ interface MSALProviderProps extends MsalAuthProviderProps {
  *   )
  * }
  * ```
+ *
+ * @security
+ * - All authentication happens client-side (browser)
+ * - Tokens are never sent to your Next.js server
+ * - Uses Microsoft's official MSAL library
+ * - Supports secure token storage (sessionStorage/localStorage)
+ * - No server-side token handling required
  */
 declare function MSALProvider({ children, protection, ...props }: MSALProviderProps): react_jsx_runtime.JSX.Element;
 
@@ -948,6 +993,80 @@ interface UseRolesReturn {
  */
 declare function useRoles(): UseRolesReturn;
 
+/**
+ * Automatic token refresh hook
+ * Refreshes tokens before they expire to prevent session interruptions
+ */
+interface UseTokenRefreshOptions {
+    /**
+     * Enable automatic token refresh
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Refresh token this many seconds before expiry
+     * @default 300 (5 minutes)
+     */
+    refreshBeforeExpiry?: number;
+    /**
+     * Scopes to refresh
+     * @default ['User.Read']
+     */
+    scopes?: string[];
+    /**
+     * Callback when token is refreshed
+     */
+    onRefresh?: (expiresIn: number) => void;
+    /**
+     * Callback when refresh fails
+     */
+    onError?: (error: Error) => void;
+}
+interface UseTokenRefreshReturn {
+    /**
+     * Seconds until token expires
+     */
+    expiresIn: number | null;
+    /**
+     * Whether token is expiring soon
+     */
+    isExpiringSoon: boolean;
+    /**
+     * Manually trigger token refresh
+     */
+    refresh: () => Promise<void>;
+    /**
+     * Last refresh timestamp
+     */
+    lastRefresh: Date | null;
+}
+/**
+ * Hook for automatic token refresh
+ *
+ * @remarks
+ * Automatically refreshes access tokens before they expire to prevent
+ * session interruptions. Runs in the background without user interaction.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - automatic refresh
+ * useTokenRefresh();
+ *
+ * // With options
+ * const { expiresIn, isExpiringSoon } = useTokenRefresh({
+ *   refreshBeforeExpiry: 600, // 10 minutes
+ *   scopes: ['User.Read', 'Mail.Read'],
+ *   onRefresh: (expiresIn) => console.log(`Token refreshed, expires in ${expiresIn}s`),
+ * });
+ *
+ * // Show warning when expiring soon
+ * if (isExpiringSoon) {
+ *   return <div>Your session will expire soon</div>;
+ * }
+ * ```
+ */
+declare function useTokenRefresh(options?: UseTokenRefreshOptions): UseTokenRefreshReturn;
+
 declare function createMsalConfig(config: MsalAuthConfig): Configuration;
 
 interface WithAuthOptions extends Omit<AuthGuardProps, 'children'> {
@@ -1429,4 +1548,4 @@ interface ServerSession {
     accessToken?: string;
 }
 
-export { AuthGuard, type AuthGuardProps, type AuthMiddlewareConfig, type AuthProtectionConfig, AuthStatus, type AuthStatusProps, type CustomTokenClaims, type DebugLoggerConfig, ErrorBoundary, type ErrorBoundaryProps, type GraphApiOptions, MSALProvider, MicrosoftSignInButton, type MicrosoftSignInButtonProps, type MsalAuthConfig, MsalAuthProvider, type MsalAuthProviderProps, MsalError, type PageAuthConfig, ProtectedPage, type RetryConfig, type ServerSession, SignOutButton, type SignOutButtonProps, type UseGraphApiReturn, type UseMsalAuthReturn, type UseRolesReturn, type UseUserProfileReturn, UserAvatar, type UserAvatarProps, type UserProfile, type ValidatedAccountData, type ValidationError, type ValidationResult, type ValidationWarning, type WithAuthOptions, createAuthMiddleware, createMissingEnvVarError, createMsalConfig, createRetryWrapper, createScopedLogger, displayValidationResults, getDebugLogger, getMsalInstance, isValidAccountData, isValidRedirectUri, isValidScope, retryWithBackoff, safeJsonParse, sanitizeError, useGraphApi, useMsalAuth, useRoles, useUserProfile, validateConfig, validateScopes, withAuth, withPageAuth, wrapMsalError };
+export { AuthGuard, type AuthGuardProps, type AuthMiddlewareConfig, type AuthProtectionConfig, AuthStatus, type AuthStatusProps, type CustomTokenClaims, type DebugLoggerConfig, ErrorBoundary, type ErrorBoundaryProps, type GraphApiOptions, MSALProvider, MicrosoftSignInButton, type MicrosoftSignInButtonProps, type MsalAuthConfig, MsalAuthProvider, type MsalAuthProviderProps, MsalError, type PageAuthConfig, ProtectedPage, type RetryConfig, type ServerSession, SignOutButton, type SignOutButtonProps, type UseGraphApiReturn, type UseMsalAuthReturn, type UseRolesReturn, type UseTokenRefreshOptions, type UseTokenRefreshReturn, type UseUserProfileReturn, UserAvatar, type UserAvatarProps, type UserProfile, type ValidatedAccountData, type ValidationError, type ValidationResult, type ValidationWarning, type WithAuthOptions, createAuthMiddleware, createMissingEnvVarError, createMsalConfig, createRetryWrapper, createScopedLogger, displayValidationResults, getDebugLogger, getMsalInstance, isValidAccountData, isValidRedirectUri, isValidScope, retryWithBackoff, safeJsonParse, sanitizeError, useGraphApi, useMsalAuth, useRoles, useTokenRefresh, useUserProfile, validateConfig, validateScopes, withAuth, withPageAuth, wrapMsalError };

package/dist/index.d.ts

@@ -264,6 +264,41 @@ interface MsalAuthConfig {
      * ```
      */
     onInitialized?: (instance: IPublicClientApplication) => void;
+    /**
+     * Enable automatic token refresh
+     *
+     * @remarks
+     * Automatically refreshes access tokens before they expire to prevent
+     * session interruptions. Tokens are refreshed silently in the background.
+     *
+     * @defaultValue false
+     *
+     * @example
+     * ```tsx
+     * <MSALProvider
+     *   clientId="..."
+     *   autoRefreshToken={true}
+     *   refreshBeforeExpiry={300} // Refresh 5 min before expiry
+     * >
+     *   {children}
+     * </MSALProvider>
+     * ```
+     */
+    autoRefreshToken?: boolean;
+    /**
+     * Refresh token this many seconds before expiry
+     *
+     * @remarks
+     * Only used when autoRefreshToken is enabled.
+     *
+     * @defaultValue 300 (5 minutes)
+     *
+     * @example
+     * ```tsx
+     * refreshBeforeExpiry={600} // Refresh 10 minutes before expiry
+     * ```
+     */
+    refreshBeforeExpiry?: number;
 }
 /**
  * Props for MsalAuthProvider component
@@ -283,7 +318,7 @@ interface MsalAuthProviderProps extends MsalAuthConfig {
  * @returns The MSAL instance or null if not initialized
  */
 declare function getMsalInstance(): PublicClientApplication | null;
-declare function MsalAuthProvider({ children, loadingComponent, onInitialized, ...config }: MsalAuthProviderProps): react_jsx_runtime.JSX.Element;
+declare function MsalAuthProvider({ children, loadingComponent, onInitialized, autoRefreshToken, refreshBeforeExpiry, ...config }: MsalAuthProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Zero-Config Protected Routes - Type Definitions
@@ -393,12 +428,15 @@ interface MSALProviderProps extends MsalAuthProviderProps {
 }
 /**
  * Pre-configured MSALProvider component for Next.js App Router layouts.
- * This component is already marked as 'use client', so you can use it directly
- * in your server-side layout.tsx without needing to create a separate client component.
+ *
+ * @remarks
+ * This component is already marked as 'use client' internally, so you can import
+ * and use it directly in your server-side layout.tsx without adding 'use client'
+ * to your layout file.
  *
  * @example
  * ```tsx
- * // app/layout.tsx
+ * // app/layout.tsx (Server Component - no 'use client' needed!)
  * import { MSALProvider } from '@chemmangat/msal-next'
  *
  * export default function RootLayout({ children }) {
@@ -416,6 +454,13 @@ interface MSALProviderProps extends MsalAuthProviderProps {
  *   )
  * }
  * ```
+ *
+ * @security
+ * - All authentication happens client-side (browser)
+ * - Tokens are never sent to your Next.js server
+ * - Uses Microsoft's official MSAL library
+ * - Supports secure token storage (sessionStorage/localStorage)
+ * - No server-side token handling required
  */
 declare function MSALProvider({ children, protection, ...props }: MSALProviderProps): react_jsx_runtime.JSX.Element;
 
@@ -948,6 +993,80 @@ interface UseRolesReturn {
  */
 declare function useRoles(): UseRolesReturn;
 
+/**
+ * Automatic token refresh hook
+ * Refreshes tokens before they expire to prevent session interruptions
+ */
+interface UseTokenRefreshOptions {
+    /**
+     * Enable automatic token refresh
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Refresh token this many seconds before expiry
+     * @default 300 (5 minutes)
+     */
+    refreshBeforeExpiry?: number;
+    /**
+     * Scopes to refresh
+     * @default ['User.Read']
+     */
+    scopes?: string[];
+    /**
+     * Callback when token is refreshed
+     */
+    onRefresh?: (expiresIn: number) => void;
+    /**
+     * Callback when refresh fails
+     */
+    onError?: (error: Error) => void;
+}
+interface UseTokenRefreshReturn {
+    /**
+     * Seconds until token expires
+     */
+    expiresIn: number | null;
+    /**
+     * Whether token is expiring soon
+     */
+    isExpiringSoon: boolean;
+    /**
+     * Manually trigger token refresh
+     */
+    refresh: () => Promise<void>;
+    /**
+     * Last refresh timestamp
+     */
+    lastRefresh: Date | null;
+}
+/**
+ * Hook for automatic token refresh
+ *
+ * @remarks
+ * Automatically refreshes access tokens before they expire to prevent
+ * session interruptions. Runs in the background without user interaction.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - automatic refresh
+ * useTokenRefresh();
+ *
+ * // With options
+ * const { expiresIn, isExpiringSoon } = useTokenRefresh({
+ *   refreshBeforeExpiry: 600, // 10 minutes
+ *   scopes: ['User.Read', 'Mail.Read'],
+ *   onRefresh: (expiresIn) => console.log(`Token refreshed, expires in ${expiresIn}s`),
+ * });
+ *
+ * // Show warning when expiring soon
+ * if (isExpiringSoon) {
+ *   return <div>Your session will expire soon</div>;
+ * }
+ * ```
+ */
+declare function useTokenRefresh(options?: UseTokenRefreshOptions): UseTokenRefreshReturn;
+
 declare function createMsalConfig(config: MsalAuthConfig): Configuration;
 
 interface WithAuthOptions extends Omit<AuthGuardProps, 'children'> {
@@ -1429,4 +1548,4 @@ interface ServerSession {
     accessToken?: string;
 }
 
-export { AuthGuard, type AuthGuardProps, type AuthMiddlewareConfig, type AuthProtectionConfig, AuthStatus, type AuthStatusProps, type CustomTokenClaims, type DebugLoggerConfig, ErrorBoundary, type ErrorBoundaryProps, type GraphApiOptions, MSALProvider, MicrosoftSignInButton, type MicrosoftSignInButtonProps, type MsalAuthConfig, MsalAuthProvider, type MsalAuthProviderProps, MsalError, type PageAuthConfig, ProtectedPage, type RetryConfig, type ServerSession, SignOutButton, type SignOutButtonProps, type UseGraphApiReturn, type UseMsalAuthReturn, type UseRolesReturn, type UseUserProfileReturn, UserAvatar, type UserAvatarProps, type UserProfile, type ValidatedAccountData, type ValidationError, type ValidationResult, type ValidationWarning, type WithAuthOptions, createAuthMiddleware, createMissingEnvVarError, createMsalConfig, createRetryWrapper, createScopedLogger, displayValidationResults, getDebugLogger, getMsalInstance, isValidAccountData, isValidRedirectUri, isValidScope, retryWithBackoff, safeJsonParse, sanitizeError, useGraphApi, useMsalAuth, useRoles, useUserProfile, validateConfig, validateScopes, withAuth, withPageAuth, wrapMsalError };
+export { AuthGuard, type AuthGuardProps, type AuthMiddlewareConfig, type AuthProtectionConfig, AuthStatus, type AuthStatusProps, type CustomTokenClaims, type DebugLoggerConfig, ErrorBoundary, type ErrorBoundaryProps, type GraphApiOptions, MSALProvider, MicrosoftSignInButton, type MicrosoftSignInButtonProps, type MsalAuthConfig, MsalAuthProvider, type MsalAuthProviderProps, MsalError, type PageAuthConfig, ProtectedPage, type RetryConfig, type ServerSession, SignOutButton, type SignOutButtonProps, type UseGraphApiReturn, type UseMsalAuthReturn, type UseRolesReturn, type UseTokenRefreshOptions, type UseTokenRefreshReturn, type UseUserProfileReturn, UserAvatar, type UserAvatarProps, type UserProfile, type ValidatedAccountData, type ValidationError, type ValidationResult, type ValidationWarning, type WithAuthOptions, createAuthMiddleware, createMissingEnvVarError, createMsalConfig, createRetryWrapper, createScopedLogger, displayValidationResults, getDebugLogger, getMsalInstance, isValidAccountData, isValidRedirectUri, isValidScope, retryWithBackoff, safeJsonParse, sanitizeError, useGraphApi, useMsalAuth, useRoles, useTokenRefresh, useUserProfile, validateConfig, validateScopes, withAuth, withPageAuth, wrapMsalError };