@chemmangat/msal-next 3.1.7 → 3.1.8

package/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file.
 
-## [3.1.6] - 2026-03-05
+## [3.1.7] - 2026-03-05
 
 ### 🔄 Breaking Change - Redirect-Only Flow
 

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.6** - Redirect-only authentication (popup support removed). [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.
 

package/dist/index.d.mts

@@ -5,96 +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;
     /**
      * 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;
 }
 

package/dist/index.d.ts

@@ -5,96 +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;
     /**
      * 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;
 }