@chemmangat/msal-next 3.1.6 → 3.1.8

package/CHANGELOG.md

@@ -2,57 +2,54 @@
 
 All notable changes to this project will be documented in this file.
 
-## [3.1.5] - 2026-03-05
+## [3.1.7] - 2026-03-05
 
-### 🔄 Breaking Change - Redirect Flow by Default
+### 🔄 Breaking Change - Redirect-Only Flow
 
-**MicrosoftSignInButton now uses redirect flow by default** instead of popup flow.
+**Removed all popup authentication support** - Package now only supports redirect flow for cleaner, simpler authentication.
 
 **Why this change?**
-- Popup flow requires additional setup (blank.html page)
-- Popup flow causes the full app to load in popup window
-- Redirect flow is simpler and works out of the box
-- Most users prefer redirect flow for better UX
+- Popup flow had persistent issues (full app loading in popup, logout popups, etc.)
+- Redirect flow is simpler, more reliable, and works out of the box
+- No need for blank.html or special Azure AD configuration
+- Better user experience with full-page redirects
+
+**What was removed:**
+- `loginPopup()` method
+- `logoutPopup()` method  
+- `acquireTokenPopup()` method
+- `useRedirect` prop from MicrosoftSignInButton
+- `useRedirect` prop from SignOutButton
+- `popupRedirectUri` configuration option
+- `getPopupRedirectUri()` utility
+- All popup-related code and configuration
 
 **Migration:**
 
-If you were using the default popup behavior:
 ```tsx
-// Before (v3.1.4 and earlier) - used popup by default
-<MicrosoftSignInButton />
-
-// After (v3.1.5) - uses redirect by default
-<MicrosoftSignInButton />  // Now redirects full page
+// Before (v3.1.4 and earlier)
+const { loginPopup, logoutPopup } = useMsalAuth();
+await loginPopup();
+await logoutPopup();
 
-// To keep popup behavior:
 <MicrosoftSignInButton useRedirect={false} />
-```
-
-**New Default Behavior:**
-- Button redirects the entire browser window to Microsoft login
-- After authentication, redirects back to your app
-- No popup windows, no blank.html needed
-- Works with your existing Azure AD redirect URI
+<SignOutButton useRedirect={false} />
 
-### ✨ Optional Popup Support
+// After (v3.1.5) - redirect only
+const { loginRedirect, logoutRedirect } = useMsalAuth();
+await loginRedirect();
+await logoutRedirect();
 
-**Added optional `popupRedirectUri` prop** - Only use if you prefer popup flow.
-
-**For Popup Flow (Optional):**
-1. Create `public/blank.html`
-2. Add `/blank.html` to Azure AD redirect URIs
-3. Use:
-```tsx
-<MSALProvider popupRedirectUri="/blank.html">
-  <MicrosoftSignInButton useRedirect={false} />
-</MSALProvider>
+<MicrosoftSignInButton />
+<SignOutButton />
 ```
 
 **Benefits:**
-- Simpler default experience (no setup required)
-- Redirect flow works out of the box
-- Popup flow still available for those who need it
-- Backward compatible (just set `useRedirect={false}`)
+- Simpler API - no popup vs redirect decisions
+- No popup-related bugs or issues
+- Works perfectly out of the box
+- Cleaner codebase and smaller bundle size
+- Better user experience
 
 ## [3.1.4] - 2026-03-05
 

package/README.md

@@ -5,7 +5,7 @@ Production-grade MSAL authentication library for Next.js App Router with minimal
 [![npm version](https://badge.fury.io/js/@chemmangat%2Fmsal-next.svg)](https://www.npmjs.com/package/@chemmangat/msal-next)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **📦 Current Version: 3.1.5** - Separate popup redirect URI support. [See changelog](./CHANGELOG.md)
+> **📦 Current Version: 3.1.7** - Redirect-only authentication (popup support removed). [See changelog](./CHANGELOG.md)
 
 > **⚠️ Important:** If you're on v3.0.6 or v3.0.7, please update immediately - those versions have a critical popup authentication bug.
 
@@ -134,59 +134,7 @@ export default function Home() {
 
 That's it! 🎉
 
-The button uses redirect flow by default (full page redirect to Microsoft login, then back to your app). No popups, no blank.html needed.
-
-## Optional: Fix Popup Window Issue
-
-**Important:** When using popup authentication, the popup window MUST navigate to your redirect URI to complete the OAuth flow. This is how OAuth works and cannot be avoided.
-
-By default, this means your full Next.js app will briefly load in the popup before it closes. The package detects this and renders minimal content, but you may still see a flash of your app.
-
-### Solution: Use a Blank Page (Recommended for Popup Flow)
-
-For the cleanest popup experience, create a blank HTML page:
-
-### 1. Create blank.html
-
-Create `public/blank.html`:
-
-```html
-<!DOCTYPE html>
-<html>
-<head><title>Auth</title></head>
-<body></body>
-</html>
-```
-
-### 2. Add to Azure AD
-
-Add to Azure AD redirect URIs:
-- `http://localhost:3000/blank.html`
-- `https://yourdomain.com/blank.html`
-
-### 3. Configure MSALProvider
-
-```tsx
-<MSALProvider 
-  clientId={process.env.NEXT_PUBLIC_AZURE_AD_CLIENT_ID!}
-  tenantId={process.env.NEXT_PUBLIC_AZURE_AD_TENANT_ID!}
-  popupRedirectUri="/blank.html"  // Add this line
->
-  {children}
-</MSALProvider>
-```
-
-This ensures the popup shows only a blank page and closes immediately.
-
-### Alternative: Use Redirect Flow
-
-If you don't want to set up blank.html, use redirect flow instead:
-
-```tsx
-<MicrosoftSignInButton useRedirect={true} />
-```
-
-Redirect flow navigates the entire browser window (no popup), so there's no "app in popup" issue.
+The button uses redirect flow (full page redirect to Microsoft login, then back to your app). Simple and clean.
 
 ## Components
 
@@ -240,18 +188,14 @@ export function MyProviders({ children }) {
 
 ### MicrosoftSignInButton
 
-Pre-styled sign-in button with Microsoft branding. Uses redirect flow by default (no popups).
+Pre-styled sign-in button with Microsoft branding. Uses redirect flow (full page redirect to Microsoft login).
 
 ```tsx
 <MicrosoftSignInButton
   variant="dark" // or "light"
   size="medium" // "small", "medium", "large"
-  useRedirect={true} // Default: true (full page redirect)
   onSuccess={() => console.log('Signed in!')}
 />
-
-// If you prefer popup (requires blank.html setup):
-<MicrosoftSignInButton useRedirect={false} />
 ```
 
 ### SignOutButton
@@ -332,21 +276,19 @@ const {
   account,
   isAuthenticated,
   inProgress,
-  loginPopup,
   loginRedirect,
-  logoutPopup,
   logoutRedirect,
   acquireToken,
 } = useMsalAuth();
 
-// Login
-await loginPopup(['User.Read']);
+// Login (redirects to Microsoft)
+await loginRedirect(['User.Read']);
 
 // Get token
 const token = await acquireToken(['User.Read']);
 
-// Logout
-await logoutPopup();
+// Logout (redirects to Microsoft)
+await logoutRedirect();
 ```
 
 ### useGraphApi

package/dist/index.d.mts

@@ -5,103 +5,276 @@ import { ReactNode, CSSProperties, Component, ErrorInfo, ComponentType } from 'r
 import { NextRequest, NextResponse } from 'next/server';
 export { useAccount, useIsAuthenticated, useMsal } from '@azure/msal-react';
 
+/**
+ * Type definitions for @chemmangat/msal-next
+ *
+ * @packageDocumentation
+ */
+
 /**
  * Custom token claims interface for TypeScript generics
- * Extend this interface to add your custom claims
+ *
+ * @remarks
+ * Extend this interface to add type-safe custom claims from your Azure AD tokens.
+ * This is useful when you have custom claims configured in your Azure AD app registration.
  *
  * @example
  * ```tsx
+ * // Define your custom claims
  * interface MyCustomClaims extends CustomTokenClaims {
  *   roles: string[];
  *   department: string;
+ *   employeeId: string;
  * }
  *
- * const claims = account.idTokenClaims as MyCustomClaims;
+ * // Use with type safety
+ * const { account } = useMsalAuth();
+ * const claims = account?.idTokenClaims as MyCustomClaims;
+ *
+ * console.log(claims.roles); // Type-safe!
+ * console.log(claims.department); // Type-safe!
  * ```
  */
 interface CustomTokenClaims {
     [key: string]: any;
 }
+/**
+ * Configuration options for MSAL authentication
+ *
+ * @remarks
+ * This interface defines all available configuration options for the MSAL provider.
+ * Most options have sensible defaults and only clientId is required.
+ */
 interface MsalAuthConfig {
     /**
      * Azure AD Application (client) ID
+     *
+     * @remarks
+     * Required. Get this from your Azure AD app registration.
+     *
+     * @example
+     * ```tsx
+     * clientId: "12345678-1234-1234-1234-123456789012"
+     * ```
      */
     clientId: string;
     /**
-     * Azure AD Directory (tenant) ID (optional for multi-tenant)
+     * Azure AD Directory (tenant) ID
+     *
+     * @remarks
+     * Optional. Required for single-tenant apps.
+     * Omit for multi-tenant apps (use authorityType: 'common' instead).
+     *
+     * @example
+     * ```tsx
+     * tenantId: "87654321-4321-4321-4321-210987654321"
+     * ```
      */
     tenantId?: string;
     /**
-     * Authority type: 'common' for multi-tenant, 'organizations', 'consumers', or 'tenant' for single-tenant
-     * @default 'common'
+     * Authority type for authentication
+     *
+     * @remarks
+     * - 'common': Multi-tenant (any Azure AD tenant)
+     * - 'organizations': Any organizational Azure AD tenant
+     * - 'consumers': Microsoft personal accounts only
+     * - 'tenant': Single-tenant (requires tenantId)
+     *
+     * @defaultValue 'common'
+     *
+     * @example
+     * ```tsx
+     * // Multi-tenant SaaS app
+     * authorityType: 'common'
+     *
+     * // Single-tenant enterprise app
+     * authorityType: 'tenant'
+     * tenantId: "your-tenant-id"
+     * ```
      */
     authorityType?: 'common' | 'organizations' | 'consumers' | 'tenant';
     /**
      * Redirect URI after authentication
-     * @default window.location.origin
+     *
+     * @remarks
+     * Must match a redirect URI configured in your Azure AD app registration.
+     *
+     * @defaultValue window.location.origin
+     *
+     * @example
+     * ```tsx
+     * redirectUri: "https://myapp.com/auth/callback"
+     * ```
      */
     redirectUri?: string;
-    /**
-     * Redirect URI for popup authentication (optional)
-     * If not specified, uses the same redirectUri as redirect flow
-     * Only set this if you want a different URI for popup (e.g., /blank.html)
-     * @default redirectUri
-     */
-    popupRedirectUri?: string;
     /**
      * Post logout redirect URI
-     * @default redirectUri
+     *
+     * @remarks
+     * Where to redirect after logout. Defaults to redirectUri if not specified.
+     *
+     * @defaultValue redirectUri
+     *
+     * @example
+     * ```tsx
+     * postLogoutRedirectUri: "https://myapp.com"
+     * ```
      */
     postLogoutRedirectUri?: string;
     /**
      * Default scopes for authentication
-     * @default ['User.Read']
+     *
+     * @remarks
+     * Scopes define what permissions your app requests.
+     * Common scopes: 'User.Read', 'Mail.Read', 'Calendars.Read'
+     *
+     * @defaultValue ['User.Read']
+     *
+     * @example
+     * ```tsx
+     * scopes: ['User.Read', 'Mail.Read', 'Calendars.Read']
+     * ```
      */
     scopes?: string[];
     /**
-     * Cache location: 'sessionStorage', 'localStorage', or 'memoryStorage'
-     * @default 'sessionStorage'
+     * Cache location for tokens
+     *
+     * @remarks
+     * - 'sessionStorage': Tokens cleared when browser tab closes (more secure)
+     * - 'localStorage': Tokens persist across browser sessions
+     * - 'memoryStorage': Tokens only in memory (most secure, but lost on refresh)
+     *
+     * @defaultValue 'sessionStorage'
+     *
+     * @example
+     * ```tsx
+     * cacheLocation: 'sessionStorage'
+     * ```
      */
     cacheLocation?: 'sessionStorage' | 'localStorage' | 'memoryStorage';
     /**
-     * Store auth state in cookie (for IE11/Edge legacy)
-     * @default false
+     * Store auth state in cookie
+     *
+     * @remarks
+     * Enable for IE11/Edge legacy support. Not needed for modern browsers.
+     *
+     * @defaultValue false
      */
     storeAuthStateInCookie?: boolean;
     /**
      * Navigate to login request URL after authentication
-     * @default true
+     *
+     * @remarks
+     * If true, redirects to the page that initiated login after successful auth.
+     *
+     * @defaultValue true
      */
     navigateToLoginRequestUrl?: boolean;
     /**
-     * Custom MSAL configuration (overrides all other options)
+     * Custom MSAL configuration
+     *
+     * @remarks
+     * Advanced: Provide a complete MSAL configuration object.
+     * This overrides all other configuration options.
+     *
+     * @example
+     * ```tsx
+     * msalConfig: {
+     *   auth: {
+     *     clientId: "your-client-id",
+     *     authority: "https://login.microsoftonline.com/your-tenant-id",
+     *   },
+     *   cache: {
+     *     cacheLocation: "sessionStorage",
+     *   },
+     * }
+     * ```
      */
     msalConfig?: Configuration;
     /**
      * Enable debug logging
-     * @default false
+     *
+     * @remarks
+     * Logs authentication events to the console. Useful for troubleshooting.
+     *
+     * @defaultValue false
+     *
+     * @example
+     * ```tsx
+     * enableLogging: true
+     * ```
      */
     enableLogging?: boolean;
     /**
      * Custom logger callback
+     *
+     * @remarks
+     * Advanced: Provide a custom function to handle MSAL logs.
+     *
+     * @example
+     * ```tsx
+     * loggerCallback: (level, message, containsPii) => {
+     *   if (level === LogLevel.Error) {
+     *     console.error('MSAL Error:', message);
+     *   }
+     * }
+     * ```
      */
     loggerCallback?: (level: LogLevel, message: string, containsPii: boolean) => void;
     /**
-     * Allowed redirect URIs for validation (optional but recommended)
-     * Helps prevent open redirect vulnerabilities
-     * @example ['https://myapp.com', 'http://localhost:3000']
+     * Allowed redirect URIs for validation
+     *
+     * @remarks
+     * Security: Whitelist of allowed redirect URIs to prevent open redirect vulnerabilities.
+     * Recommended for production apps.
+     *
+     * @example
+     * ```tsx
+     * allowedRedirectUris: [
+     *   'https://myapp.com',
+     *   'https://staging.myapp.com',
+     *   'http://localhost:3000'
+     * ]
+     * ```
      */
     allowedRedirectUris?: string[];
     /**
      * Loading component to show while MSAL initializes
+     *
+     * @remarks
+     * Custom React component to display during MSAL initialization.
+     *
+     * @example
+     * ```tsx
+     * loadingComponent: <div className="spinner">Loading...</div>
+     * ```
      */
     loadingComponent?: ReactNode;
     /**
-     * Callback invoked after MSAL initialization completes successfully
+     * Callback invoked after MSAL initialization completes
+     *
+     * @remarks
+     * Use this to perform actions after MSAL is ready, such as logging or analytics.
+     *
+     * @example
+     * ```tsx
+     * onInitialized: (instance) => {
+     *   console.log('MSAL initialized with', instance.getAllAccounts().length, 'accounts');
+     * }
+     * ```
      */
     onInitialized?: (instance: IPublicClientApplication) => void;
 }
+/**
+ * Props for MsalAuthProvider component
+ *
+ * @remarks
+ * Extends MsalAuthConfig with React children prop
+ */
 interface MsalAuthProviderProps extends MsalAuthConfig {
+    /**
+     * Child components to wrap with authentication context
+     */
     children: ReactNode;
 }
 
@@ -156,11 +329,6 @@ interface MicrosoftSignInButtonProps {
      * @default 'medium'
      */
     size?: 'small' | 'medium' | 'large';
-    /**
-     * Use redirect flow instead of popup
-     * @default true
-     */
-    useRedirect?: boolean;
     /**
      * Scopes to request
      */
@@ -182,7 +350,7 @@ interface MicrosoftSignInButtonProps {
      */
     onError?: (error: Error) => void;
 }
-declare function MicrosoftSignInButton({ text, variant, size, useRedirect, scopes, className, style, onSuccess, onError, }: MicrosoftSignInButtonProps): react_jsx_runtime.JSX.Element;
+declare function MicrosoftSignInButton({ text, variant, size, scopes, className, style, onSuccess, onError, }: MicrosoftSignInButtonProps): react_jsx_runtime.JSX.Element;
 
 interface SignOutButtonProps {
     /**
@@ -200,11 +368,6 @@ interface SignOutButtonProps {
      * @default 'medium'
      */
     size?: 'small' | 'medium' | 'large';
-    /**
-     * Use redirect flow instead of popup
-     * @default false
-     */
-    useRedirect?: boolean;
     /**
      * Custom className
      */
@@ -224,13 +387,14 @@ interface SignOutButtonProps {
 }
 /**
  * SignOutButton component with Microsoft branding
+ * Uses redirect flow (full page redirect)
  *
  * @example
  * ```tsx
  * <SignOutButton variant="light" />
  * ```
  */
-declare function SignOutButton({ text, variant, size, useRedirect, className, style, onSuccess, onError, }: SignOutButtonProps): react_jsx_runtime.JSX.Element;
+declare function SignOutButton({ text, variant, size, className, style, onSuccess, onError, }: SignOutButtonProps): react_jsx_runtime.JSX.Element;
 
 interface UserAvatarProps {
     /**
@@ -316,11 +480,6 @@ interface AuthGuardProps {
      * Component to show when not authenticated (before redirect)
      */
     fallbackComponent?: ReactNode;
-    /**
-     * Use redirect flow instead of popup
-     * @default true
-     */
-    useRedirect?: boolean;
     /**
      * Scopes to request during authentication
      */
@@ -340,7 +499,7 @@ interface AuthGuardProps {
  * </AuthGuard>
  * ```
  */
-declare function AuthGuard({ children, loadingComponent, fallbackComponent, useRedirect, scopes, onAuthRequired, }: AuthGuardProps): react_jsx_runtime.JSX.Element;
+declare function AuthGuard({ children, loadingComponent, fallbackComponent, scopes, onAuthRequired, }: AuthGuardProps): react_jsx_runtime.JSX.Element;
 
 interface ErrorBoundaryProps {
     /**
@@ -402,34 +561,22 @@ interface UseMsalAuthReturn {
      * Whether MSAL is currently performing an interaction
      */
     inProgress: boolean;
-    /**
-     * Login using popup
-     */
-    loginPopup: (scopes?: string[]) => Promise<void>;
     /**
      * Login using redirect
      */
     loginRedirect: (scopes?: string[]) => Promise<void>;
-    /**
-     * Logout using popup
-     */
-    logoutPopup: () => Promise<void>;
     /**
      * Logout using redirect
      */
     logoutRedirect: () => Promise<void>;
     /**
-     * Acquire access token silently (with fallback to popup)
+     * Acquire access token silently
      */
     acquireToken: (scopes: string[]) => Promise<string>;
     /**
      * Acquire access token silently only (no fallback)
      */
     acquireTokenSilent: (scopes: string[]) => Promise<string>;
-    /**
-     * Acquire access token using popup
-     */
-    acquireTokenPopup: (scopes: string[]) => Promise<string>;
     /**
      * Acquire access token using redirect
      */
@@ -591,7 +738,6 @@ interface UseRolesReturn {
  */
 declare function useRoles(): UseRolesReturn;
 
-declare function getPopupRedirectUri(): string | undefined;
 declare function createMsalConfig(config: MsalAuthConfig): Configuration;
 
 interface WithAuthOptions extends Omit<AuthGuardProps, 'children'> {
@@ -939,4 +1085,4 @@ interface ServerSession {
     accessToken?: string;
 }
 
-export { AuthGuard, type AuthGuardProps, type AuthMiddlewareConfig, AuthStatus, type AuthStatusProps, type CustomTokenClaims, type DebugLoggerConfig, ErrorBoundary, type ErrorBoundaryProps, type GraphApiOptions, MSALProvider, MicrosoftSignInButton, type MicrosoftSignInButtonProps, type MsalAuthConfig, MsalAuthProvider, type MsalAuthProviderProps, 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, getPopupRedirectUri, isValidAccountData, isValidRedirectUri, isValidScope, retryWithBackoff, safeJsonParse, sanitizeError, useGraphApi, useMsalAuth, useRoles, useUserProfile, validateScopes, withAuth };
+export { AuthGuard, type AuthGuardProps, type AuthMiddlewareConfig, AuthStatus, type AuthStatusProps, type CustomTokenClaims, type DebugLoggerConfig, ErrorBoundary, type ErrorBoundaryProps, type GraphApiOptions, MSALProvider, MicrosoftSignInButton, type MicrosoftSignInButtonProps, type MsalAuthConfig, MsalAuthProvider, type MsalAuthProviderProps, 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 };