@chemmangat/msal-next 4.0.0 → 4.0.2

package/dist/index.d.mts

@@ -748,24 +748,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 +875,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 {
     /**
@@ -1114,6 +1218,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 +1429,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 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, useUserProfile, validateConfig, validateScopes, withAuth, withPageAuth, wrapMsalError };

package/dist/index.d.ts

@@ -748,24 +748,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 +875,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 {
     /**
@@ -1114,6 +1218,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 +1429,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 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, useUserProfile, validateConfig, validateScopes, withAuth, withPageAuth, wrapMsalError };