@chemmangat/msal-next 4.1.1 → 4.2.1

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 All notable changes to this project will be documented in this file.
 
+## [4.2.0] - 2026-03-08
+
+### 🎉 Major Feature Release - Multi-Account Management
+
+This release introduces the most requested feature: Multi-Account Management. Users can now sign in with multiple Microsoft accounts simultaneously and switch between them seamlessly.
+
+### ✨ New Features
+
+#### 1. Multi-Account Management 🔥
+Sign in with multiple Microsoft accounts and switch between them without signing out.
+
+**New Hook: `useMultiAccount`**
+```tsx
+const {
+  accounts,              // All signed-in accounts
+  activeAccount,         // Current active account
+  hasMultipleAccounts,   // Boolean: more than one account
+  switchAccount,         // Switch to different account
+  addAccount,            // Sign in with another account
+  removeAccount,         // Remove account from cache
+  signOutAccount,        // Sign out specific account
+  signOutAll,            // Sign out all accounts
+} = useMultiAccount();
+```
+
+**New Component: `AccountSwitcher`**
+Pre-built dropdown UI for switching accounts with three variants (default, compact, minimal).
+
+```tsx
+<AccountSwitcher
+  showAvatars={true}
+  maxAccounts={5}
+  variant="default"
+  onSwitch={(account) => console.log('Switched to', account.name)}
+/>
+```
+
+**New Component: `AccountList`**
+Display all accounts in a list format with vertical or horizontal layouts.
+
+```tsx
+<AccountList
+  showAvatars={true}
+  showDetails={true}
+  clickToSwitch={true}
+  orientation="vertical"
+/>
+```
+
+**Use Cases:**
+- Work + personal accounts
+- Multiple work accounts (IT admins, consultants)
+- Multi-tenant SaaS applications
+- Testing different roles/permissions
+
+**Complete Examples:**
+- 5 real-world examples in `examples/multi-account-example.tsx`
+- Header with account switcher
+- Account management page
+- Programmatic account switching
+
+### 🐛 Bug Fixes
+
+- Fixed type error in `clearCache` API call
+- Removed unused variable in `AccountList` component
+- Improved error handling for account operations
+
+### 📚 Documentation
+
+- Added multi-account section to README
+- Created comprehensive examples file with 5 scenarios
+- Updated API reference with new exports
+- Added TypeScript type exports for all new components
+
+### 🔄 Migration
+
+No breaking changes! Simply update to v4.2.0:
+```bash
+npm install @chemmangat/msal-next@4.2.0
+```
+
+All existing code continues to work. Multi-account features are opt-in.
+
+---
+
 ## [4.1.0] - 2026-03-07
 
 ### 🎉 Major Release - Documentation Overhaul + Production Features

package/README.md

@@ -6,7 +6,7 @@ Production-grade MSAL authentication library for Next.js App Router with minimal
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Security](https://img.shields.io/badge/Security-A+-green.svg)](./SECURITY.md)
 
-> **📦 Current Version: 4.1.1** - Production-ready with automatic token refresh and enhanced security
+> **📦 Current Version: 4.2.1** - Production-ready with automatic token refresh and enhanced security
 
 ---
 
@@ -466,6 +466,7 @@ Pre-styled sign-in button with Microsoft branding.
   variant="dark" // or "light"
   size="medium"  // "small", "medium", "large"
   onSuccess={() => console.log('Signed in!')}
+  onError={(error) => console.error(error)}
 />
 ```
 
@@ -477,6 +478,7 @@ Pre-styled sign-out button.
   variant="light"
   size="medium"
   onSuccess={() => console.log('Signed out!')}
+  onError={(error) => console.error(error)}
 />
 ```
 
@@ -510,13 +512,16 @@ Main authentication hook.
 
 ```tsx
 const {
-  account,           // Current user account
-  accounts,          // All cached accounts
-  isAuthenticated,   // Boolean: is user signed in?
-  inProgress,        // Boolean: is auth in progress?
-  loginRedirect,     // Function: sign in
-  logoutRedirect,    // Function: sign out
-  acquireToken,      // Function: get access token
+  account,                // Current user account
+  accounts,               // All cached accounts
+  isAuthenticated,        // Boolean: is user signed in?
+  inProgress,             // Boolean: is auth in progress?
+  loginRedirect,          // Function: sign in (redirect flow)
+  logoutRedirect,         // Function: sign out (redirect flow)
+  acquireToken,           // Function: get access token (silent with redirect fallback)
+  acquireTokenSilent,     // Function: get access token (silent only, no fallback)
+  acquireTokenRedirect,   // Function: get access token via redirect
+  clearSession,           // Function: clear MSAL session without Microsoft logout
 } = useMsalAuth();
 ```
 
@@ -553,18 +558,30 @@ const message = await graph.post('/me/messages', {
   subject: 'Hello',
   body: { content: 'World' }
 });
+
+// PUT, PATCH, DELETE
+await graph.put('/me/photo/$value', photoBlob);
+await graph.patch('/me', { displayName: 'New Name' });
+await graph.delete('/me/messages/{id}');
+
+// Custom request with options
+const data = await graph.request('/me', { version: 'beta', scopes: ['User.Read'] });
 ```
 
 #### useRoles()
-Access user's Azure AD roles.
+Access user's Azure AD roles and groups.
 
 ```tsx
 const {
   roles,        // Array of role names
   groups,       // Array of group IDs
+  loading,      // Boolean: is loading?
+  error,        // Error object if failed
   hasRole,      // Function: check single role
-  hasAnyRole,   // Function: check multiple roles
-  hasAllRoles,  // Function: check all roles
+  hasGroup,     // Function: check single group by ID
+  hasAnyRole,   // Function: check if user has any of the given roles
+  hasAllRoles,  // Function: check if user has all of the given roles
+  refetch,      // Function: refetch roles and groups
 } = useRoles();
 
 if (hasRole('Admin')) {
@@ -572,9 +589,109 @@ if (hasRole('Admin')) {
 }
 ```
 
+#### useTokenRefresh()
+Monitor and control token refresh state.
+
+```tsx
+const {
+  expiresIn,      // Seconds until token expires (null if unknown)
+  isExpiringSoon, // Boolean: token expiring within threshold
+  refresh,        // Function: manually trigger token refresh
+  lastRefresh,    // Date: when token was last refreshed
+} = useTokenRefresh({
+  refreshBeforeExpiry: 300, // seconds before expiry to refresh
+  scopes: ['User.Read'],
+  onRefresh: (expiresIn) => console.log(`Refreshed, expires in ${expiresIn}s`),
+  onError: (error) => console.error(error),
+});
+```
+
+#### useMultiAccount()
+Manage multiple signed-in Microsoft accounts.
+
+```tsx
+const {
+  accounts,             // All signed-in accounts
+  activeAccount,        // Currently active account
+  hasMultipleAccounts,  // Boolean: more than one account signed in
+  accountCount,         // Number of signed-in accounts
+  inProgress,           // Boolean: interaction in progress
+  switchAccount,        // Function: switch active account
+  addAccount,           // Function: sign in with another account
+  removeAccount,        // Function: remove account from cache
+  signOutAccount,       // Function: sign out a specific account
+  signOutAll,           // Function: sign out all accounts
+  getAccountByUsername, // Function: find account by username
+  getAccountById,       // Function: find account by homeAccountId
+  isActiveAccount,      // Function: check if account is active
+} = useMultiAccount();
+```
+
 ---
 
-## 🎓 Advanced Usage
+### Additional Components
+
+#### AccountSwitcher
+Pre-built UI for switching between multiple signed-in accounts.
+
+```tsx
+<AccountSwitcher
+  showAvatars={true}
+  maxAccounts={5}
+  variant="default" // "default", "compact", "minimal"
+  showAddButton={true}
+  showRemoveButton={true}
+  onSwitch={(account) => console.log('Switched to', account.name)}
+  onAdd={() => console.log('Adding account')}
+  onRemove={(account) => console.log('Removed', account.name)}
+/>
+```
+
+#### AccountList
+Display all signed-in accounts in a list.
+
+```tsx
+<AccountList
+  showAvatars={true}
+  showDetails={true}
+  showActiveIndicator={true}
+  clickToSwitch={true}
+  orientation="vertical" // or "horizontal"
+  onAccountClick={(account) => console.log('Clicked', account.name)}
+/>
+```
+
+---
+
+### Higher-Order Components
+
+#### withAuth
+Protect a component by wrapping it with `AuthGuard`.
+
+```tsx
+const ProtectedPage = withAuth(MyPage);
+
+// With options
+const ProtectedPage = withAuth(MyPage, {
+  loadingComponent: <Spinner />,
+  fallbackComponent: <div>Please sign in</div>,
+  scopes: ['User.Read'],
+});
+```
+
+#### withPageAuth
+Add page-level auth protection with role support.
+
+```tsx
+const ProtectedDashboard = withPageAuth(Dashboard, {
+  required: true,
+  roles: ['Admin', 'Editor'],
+  redirectTo: '/login',
+});
+export default ProtectedDashboard;
+```
+
+---
 
 ### Automatic Token Refresh (NEW in v4.1.0)
 
@@ -598,12 +715,13 @@ Prevent unexpected logouts by automatically refreshing tokens before they expire
 import { useTokenRefresh } from '@chemmangat/msal-next';
 
 export default function SessionWarning() {
-  const { expiresIn, isExpiringSoon } = useTokenRefresh();
+  const { expiresIn, isExpiringSoon, refresh, lastRefresh } = useTokenRefresh();
 
   if (isExpiringSoon) {
     return (
       <div className="warning">
-        ⚠️ Your session will expire in {Math.floor(expiresIn / 60)} minutes
+        ⚠️ Your session will expire in {Math.floor((expiresIn ?? 0) / 60)} minutes
+        <button onClick={refresh}>Refresh now</button>
       </div>
     );
   }
@@ -752,9 +870,14 @@ export default function ProfilePage() {
 | `tenantId` | `string` | No | - | Azure AD Directory (tenant) ID (for single-tenant) |
 | `authorityType` | `'common' \| 'organizations' \| 'consumers' \| 'tenant'` | No | `'common'` | Authority type |
 | `redirectUri` | `string` | No | `window.location.origin` | Redirect URI after authentication |
+| `postLogoutRedirectUri` | `string` | No | `redirectUri` | Redirect URI after logout |
 | `scopes` | `string[]` | No | `['User.Read']` | Default scopes |
 | `cacheLocation` | `'sessionStorage' \| 'localStorage' \| 'memoryStorage'` | No | `'sessionStorage'` | Token cache location |
 | `enableLogging` | `boolean` | No | `false` | Enable debug logging |
+| `autoRefreshToken` | `boolean` | No | `false` | Automatically refresh tokens before expiry |
+| `refreshBeforeExpiry` | `number` | No | `300` | Seconds before expiry to refresh token |
+| `allowedRedirectUris` | `string[]` | No | - | Whitelist of allowed redirect URIs |
+| `protection` | `AuthProtectionConfig` | No | - | Zero-config protected routes configuration |
 
 ### Authority Types
 

package/dist/index.d.mts

@@ -695,6 +695,151 @@ declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryS
     render(): ReactNode;
 }
 
+interface AccountSwitcherProps {
+    /**
+     * Show user avatars (requires Microsoft Graph API access)
+     * @defaultValue true
+     */
+    showAvatars?: boolean;
+    /**
+     * Maximum number of accounts to allow
+     * @defaultValue 5
+     */
+    maxAccounts?: number;
+    /**
+     * Callback when account is switched
+     */
+    onSwitch?: (account: AccountInfo) => void;
+    /**
+     * Callback when account is added
+     */
+    onAdd?: () => void;
+    /**
+     * Callback when account is removed
+     */
+    onRemove?: (account: AccountInfo) => void;
+    /**
+     * Custom CSS class name
+     */
+    className?: string;
+    /**
+     * Custom inline styles
+     */
+    style?: CSSProperties;
+    /**
+     * Variant style
+     * @defaultValue 'default'
+     */
+    variant?: 'default' | 'compact' | 'minimal';
+    /**
+     * Show "Add Account" button
+     * @defaultValue true
+     */
+    showAddButton?: boolean;
+    /**
+     * Show "Remove Account" button for each account
+     * @defaultValue true
+     */
+    showRemoveButton?: boolean;
+}
+/**
+ * Account Switcher Component
+ *
+ * @remarks
+ * Pre-built UI component for switching between multiple Microsoft accounts.
+ * Displays all signed-in accounts with avatars and allows users to switch or add accounts.
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ *
+ * import { AccountSwitcher } from '@chemmangat/msal-next';
+ *
+ * export default function Header() {
+ *   return (
+ *     <div>
+ *       <h1>My App</h1>
+ *       <AccountSwitcher
+ *         showAvatars={true}
+ *         maxAccounts={5}
+ *         onSwitch={(account) => console.log('Switched to', account.name)}
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function AccountSwitcher({ showAvatars, maxAccounts, onSwitch, onAdd, onRemove, className, style, variant, showAddButton, showRemoveButton, }: AccountSwitcherProps): react_jsx_runtime.JSX.Element | null;
+
+interface AccountListProps {
+    /**
+     * Show user avatars
+     * @defaultValue true
+     */
+    showAvatars?: boolean;
+    /**
+     * Show account details (email, tenant)
+     * @defaultValue true
+     */
+    showDetails?: boolean;
+    /**
+     * Show active account indicator
+     * @defaultValue true
+     */
+    showActiveIndicator?: boolean;
+    /**
+     * Allow clicking to switch accounts
+     * @defaultValue true
+     */
+    clickToSwitch?: boolean;
+    /**
+     * Callback when account is clicked
+     */
+    onAccountClick?: (account: AccountInfo) => void;
+    /**
+     * Custom CSS class name
+     */
+    className?: string;
+    /**
+     * Custom inline styles
+     */
+    style?: CSSProperties;
+    /**
+     * Layout orientation
+     * @defaultValue 'vertical'
+     */
+    orientation?: 'vertical' | 'horizontal';
+}
+/**
+ * Account List Component
+ *
+ * @remarks
+ * Display all signed-in Microsoft accounts in a list format.
+ * Useful for account management pages or settings screens.
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ *
+ * import { AccountList } from '@chemmangat/msal-next';
+ *
+ * export default function AccountsPage() {
+ *   return (
+ *     <div>
+ *       <h1>Your Accounts</h1>
+ *       <AccountList
+ *         showAvatars={true}
+ *         showDetails={true}
+ *         clickToSwitch={true}
+ *         onAccountClick={(account) => console.log('Clicked', account.name)}
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function AccountList({ showAvatars, showDetails, showActiveIndicator, clickToSwitch, onAccountClick, className, style, orientation, }: AccountListProps): react_jsx_runtime.JSX.Element;
+
 interface UseMsalAuthReturn {
     /**
      * Current authenticated account
@@ -1067,6 +1212,118 @@ interface UseTokenRefreshReturn {
  */
 declare function useTokenRefresh(options?: UseTokenRefreshOptions): UseTokenRefreshReturn;
 
+interface UseMultiAccountReturn {
+    /**
+     * All signed-in accounts
+     */
+    accounts: AccountInfo[];
+    /**
+     * Currently active account
+     */
+    activeAccount: AccountInfo | null;
+    /**
+     * Whether user has multiple accounts signed in
+     */
+    hasMultipleAccounts: boolean;
+    /**
+     * Number of signed-in accounts
+     */
+    accountCount: number;
+    /**
+     * Whether MSAL is currently performing an interaction
+     */
+    inProgress: boolean;
+    /**
+     * Switch to a different account
+     * @param account - The account to switch to
+     */
+    switchAccount: (account: AccountInfo) => void;
+    /**
+     * Add a new account (sign in with another account)
+     * @param scopes - Optional scopes for the new account
+     */
+    addAccount: (scopes?: string[]) => Promise<void>;
+    /**
+     * Remove an account from the cache
+     * @param account - The account to remove
+     */
+    removeAccount: (account: AccountInfo) => Promise<void>;
+    /**
+     * Sign out from a specific account
+     * @param account - The account to sign out from
+     */
+    signOutAccount: (account: AccountInfo) => Promise<void>;
+    /**
+     * Sign out from all accounts
+     */
+    signOutAll: () => Promise<void>;
+    /**
+     * Get account by username
+     * @param username - The username to search for
+     */
+    getAccountByUsername: (username: string) => AccountInfo | undefined;
+    /**
+     * Get account by home account ID
+     * @param homeAccountId - The home account ID to search for
+     */
+    getAccountById: (homeAccountId: string) => AccountInfo | undefined;
+    /**
+     * Check if a specific account is active
+     * @param account - The account to check
+     */
+    isActiveAccount: (account: AccountInfo) => boolean;
+}
+/**
+ * Hook for managing multiple Microsoft accounts
+ *
+ * @remarks
+ * Allows users to sign in with multiple Microsoft accounts and switch between them seamlessly.
+ * Perfect for users who need to access both work and personal accounts, or multiple work accounts.
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ *
+ * import { useMultiAccount } from '@chemmangat/msal-next';
+ *
+ * export default function AccountManager() {
+ *   const {
+ *     accounts,
+ *     activeAccount,
+ *     switchAccount,
+ *     addAccount,
+ *     removeAccount,
+ *     hasMultipleAccounts
+ *   } = useMultiAccount();
+ *
+ *   return (
+ *     <div>
+ *       <h2>Active: {activeAccount?.name}</h2>
+ *
+ *       {hasMultipleAccounts && (
+ *         <div>
+ *           <h3>Switch Account:</h3>
+ *           {accounts.map(account => (
+ *             <button
+ *               key={account.homeAccountId}
+ *               onClick={() => switchAccount(account)}
+ *             >
+ *               {account.name}
+ *             </button>
+ *           ))}
+ *         </div>
+ *       )}
+ *
+ *       <button onClick={() => addAccount()}>
+ *         Add Another Account
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useMultiAccount(defaultScopes?: string[]): UseMultiAccountReturn;
+
 declare function createMsalConfig(config: MsalAuthConfig): Configuration;
 
 interface WithAuthOptions extends Omit<AuthGuardProps, 'children'> {
@@ -1548,4 +1805,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 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 };
+export { AccountList, type AccountListProps, AccountSwitcher, type AccountSwitcherProps, 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 UseMultiAccountReturn, 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, useMultiAccount, useRoles, useTokenRefresh, useUserProfile, validateConfig, validateScopes, withAuth, withPageAuth, wrapMsalError };