@chemmangat/msal-next 4.1.1 → 4.2.0

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/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 };

package/dist/index.d.ts

@@ -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 };