@chemmangat/msal-next 4.0.1 → 4.1.0

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;
 
@@ -748,24 +793,116 @@ interface UseGraphApiReturn {
  */
 declare function useGraphApi(): UseGraphApiReturn;
 
+/**
+ * Complete Microsoft Graph User Profile Types
+ * Based on Microsoft Graph /me endpoint
+ *
+ * @see https://learn.microsoft.com/en-us/graph/api/user-get
+ */
+/**
+ * Complete user profile from Microsoft Graph /me endpoint
+ *
+ * @remarks
+ * This interface includes all common fields returned by the Microsoft Graph /me endpoint.
+ * You can extend this interface with custom fields specific to your organization.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * const { profile } = useUserProfile();
+ * console.log(profile?.department); // Now type-safe!
+ *
+ * // With custom fields
+ * interface MyUserProfile extends UserProfile {
+ *   customField: string;
+ * }
+ *
+ * const { profile } = useUserProfile<MyUserProfile>();
+ * console.log(profile?.customField);
+ * ```
+ */
 interface UserProfile {
+    /** Unique identifier for the user */
     id: string;
+    /** User's display name */
     displayName: string;
+    /** User's first name */
     givenName: string;
+    /** User's last name */
     surname: string;
+    /** User principal name (UPN) - typically the email used for login */
     userPrincipalName: string;
+    /** Primary email address */
     mail: string;
+    /** Job title */
     jobTitle?: string;
+    /** Department name */
+    department?: string;
+    /** Company name */
+    companyName?: string;
+    /** Office location */
     officeLocation?: string;
+    /** Mobile phone number */
     mobilePhone?: string;
+    /** Business phone numbers */
     businessPhones?: string[];
+    /** Preferred language (e.g., "en-US") */
+    preferredLanguage?: string;
+    /** Employee ID */
+    employeeId?: string;
+    /** Employee hire date */
+    employeeHireDate?: string;
+    /** Employee type (e.g., "Employee", "Contractor") */
+    employeeType?: string;
+    /** Country/region */
+    country?: string;
+    /** City */
+    city?: string;
+    /** State or province */
+    state?: string;
+    /** Street address */
+    streetAddress?: string;
+    /** Postal code */
+    postalCode?: string;
+    /** Usage location (ISO 3166 country code) */
+    usageLocation?: string;
+    /** Manager's user ID */
+    manager?: string;
+    /** About me / bio */
+    aboutMe?: string;
+    /** Birthday */
+    birthday?: string;
+    /** Interests */
+    interests?: string[];
+    /** Skills */
+    skills?: string[];
+    /** Schools attended */
+    schools?: string[];
+    /** Past projects */
+    pastProjects?: string[];
+    /** Responsibilities */
+    responsibilities?: string[];
+    /** My site URL */
+    mySite?: string;
+    /** Fax number */
+    faxNumber?: string;
+    /** Account enabled status */
+    accountEnabled?: boolean;
+    /** Age group (e.g., "Adult", "Minor") */
+    ageGroup?: string;
+    /** User type (e.g., "Member", "Guest") */
+    userType?: string;
+    /** Profile photo URL (blob URL created by the library) */
     photo?: string;
 }
-interface UseUserProfileReturn {
+/**
+ * Return type for useUserProfile hook
+ */
+interface UseUserProfileReturn<T extends UserProfile = UserProfile> {
     /**
      * User profile data
      */
-    profile: UserProfile | null;
+    profile: T | null;
     /**
      * Whether profile is loading
      */
@@ -783,15 +920,27 @@ interface UseUserProfileReturn {
      */
     clearCache: () => void;
 }
+
 /**
  * Hook for fetching and caching user profile from MS Graph
  *
+ * @remarks
+ * Supports generic type parameter for custom profile fields.
+ *
  * @example
  * ```tsx
+ * // Basic usage
  * const { profile, loading } = useUserProfile();
+ * console.log(profile?.department); // Now available!
+ *
+ * // With custom fields
+ * interface MyProfile extends UserProfile {
+ *   customField: string;
+ * }
+ * const { profile } = useUserProfile<MyProfile>();
  * ```
  */
-declare function useUserProfile(): UseUserProfileReturn;
+declare function useUserProfile<T extends UserProfile = UserProfile>(): UseUserProfileReturn<T>;
 
 interface UseRolesReturn {
     /**
@@ -844,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'> {
@@ -1114,6 +1337,107 @@ declare function isValidScope(scope: string): boolean;
  */
 declare function validateScopes(scopes: string[]): boolean;
 
+/**
+ * Development-mode configuration validator
+ * Helps developers catch common configuration mistakes early
+ */
+
+interface ValidationResult {
+    valid: boolean;
+    warnings: ValidationWarning[];
+    errors: ValidationError[];
+}
+interface ValidationWarning {
+    field: string;
+    message: string;
+    fix: string;
+}
+interface ValidationError {
+    field: string;
+    message: string;
+    fix: string;
+}
+/**
+ * Validate MSAL configuration in development mode
+ *
+ * @remarks
+ * This function only runs in development mode and caches results.
+ * It checks for common configuration mistakes and provides helpful warnings.
+ *
+ * @example
+ * ```tsx
+ * const result = validateConfig({
+ *   clientId: process.env.NEXT_PUBLIC_AZURE_AD_CLIENT_ID!,
+ *   tenantId: process.env.NEXT_PUBLIC_AZURE_AD_TENANT_ID,
+ * });
+ *
+ * if (!result.valid) {
+ *   console.warn('Configuration issues detected');
+ * }
+ * ```
+ */
+declare function validateConfig(config: MsalAuthConfig): ValidationResult;
+/**
+ * Display validation results in console with colors and emojis
+ */
+declare function displayValidationResults(result: ValidationResult): void;
+
+/**
+ * Enhanced MSAL error class with actionable messages
+ */
+declare class MsalError extends Error {
+    /** Original error code from MSAL */
+    readonly code?: string;
+    /** Actionable fix instructions */
+    readonly fix?: string;
+    /** Documentation link */
+    readonly docs?: string;
+    /** Original error object */
+    readonly originalError?: unknown;
+    constructor(error: unknown);
+    /**
+     * Parse error and extract actionable information
+     */
+    private static parseError;
+    /**
+     * Format error for console logging with colors (development only)
+     */
+    toConsoleString(): string;
+    /**
+     * Check if error is a user cancellation (not a real error)
+     */
+    isUserCancellation(): boolean;
+    /**
+     * Check if error requires user interaction
+     */
+    requiresInteraction(): boolean;
+}
+/**
+ * Wrap MSAL errors with enhanced error information
+ *
+ * @example
+ * ```tsx
+ * try {
+ *   await loginRedirect();
+ * } catch (error) {
+ *   const msalError = wrapMsalError(error);
+ *
+ *   if (msalError.isUserCancellation()) {
+ *     // User cancelled, ignore
+ *     return;
+ *   }
+ *
+ *   console.error(msalError.toConsoleString());
+ *   throw msalError;
+ * }
+ * ```
+ */
+declare function wrapMsalError(error: unknown): MsalError;
+/**
+ * Create error for missing environment variable
+ */
+declare function createMissingEnvVarError(varName: string): MsalError;
+
 interface ProtectedPageProps {
     children: ReactNode;
     config: PageAuthConfig;
@@ -1224,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, 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 WithAuthOptions, createAuthMiddleware, createMsalConfig, createRetryWrapper, createScopedLogger, getDebugLogger, getMsalInstance, isValidAccountData, isValidRedirectUri, isValidScope, retryWithBackoff, safeJsonParse, sanitizeError, useGraphApi, useMsalAuth, useRoles, useUserProfile, validateScopes, withAuth, withPageAuth };
+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 };