@memberjunction/ng-auth-services 2.129.0 → 2.130.1

package/dist/lib/mjexplorer-auth-base.service.d.ts

@@ -1,14 +1,33 @@
 import { Observable, BehaviorSubject } from 'rxjs';
 import { IAngularAuthProvider, AngularAuthProviderConfig } from './IAuthProvider';
+import { StandardUserInfo, StandardAuthToken, StandardAuthError, TokenRefreshResult } from './auth-types';
 import * as i0 from "@angular/core";
 /**
- * Base class for Angular authentication providers
- * Provides common functionality and enforces the provider interface
+ * Base class for Angular authentication providers - v3.0.0
+ *
+ * Provides common functionality and enforces the provider interface.
+ * All concrete providers (MSAL, Auth0, Okta) should extend this class.
+ *
+ * ## Key Improvements in v3.0:
+ * - Proper abstraction - no more leaky provider-specific logic
+ * - Standardized types - no more `any` types
+ * - Clean token access - no more `__raw || idToken` patterns
+ * - Semantic error handling - no more provider-specific error checks
+ *
+ * ## For Provider Implementers:
+ * Extend this class and implement the abstract methods:
+ * - `extractIdTokenInternal()` - Extract token from provider storage
+ * - `extractTokenInfoInternal()` - Extract full token info
+ * - `extractUserInfoInternal()` - Map claims to StandardUserInfo
+ * - `refreshTokenInternal()` - Implement refresh mechanism
+ * - `classifyErrorInternal()` - Map errors to AuthErrorType
+ *
+ * @version 3.0.0
  */
 export declare abstract class MJAuthBase implements IAngularAuthProvider {
     protected config: AngularAuthProviderConfig;
     protected isAuthenticated$: BehaviorSubject<boolean>;
-    protected userProfile$: BehaviorSubject<any>;
+    protected userInfo$: BehaviorSubject<StandardUserInfo | null>;
     protected userEmail$: BehaviorSubject<string>;
     private _initialPath;
     private _initialSearch;
@@ -20,92 +39,249 @@ export declare abstract class MJAuthBase implements IAngularAuthProvider {
      * Contains the initial search/query string from window.location.search before any work was done by auth services
      */
     get initialSearch(): string | null;
-    abstract type: string;
+    /**
+     * Provider type identifier
+     * Must be implemented by concrete providers
+     */
+    abstract readonly type: string;
     constructor(config: AngularAuthProviderConfig);
     /**
-     * Initialize the authentication provider
-     * Override in subclasses to setup provider-specific initialization
+     * Initialize the provider
+     *
+     * Subclasses should override to set up provider-specific initialization,
+     * handle redirect callbacks, restore sessions, etc.
      */
     abstract initialize(): Promise<void>;
     /**
-     * Login the user - internal implementation
-     * Override to implement provider-specific login flow
+     * Internal login implementation
+     *
+     * Subclasses implement provider-specific login flow.
+     * This is called by the public login() method.
      */
-    protected abstract loginInternal(options?: any): Promise<void>;
+    protected abstract loginInternal(options?: Record<string, unknown>): Promise<void>;
     /**
-     * Login the user - public API that returns Observable for backward compatibility
+     * Logout implementation
+     *
+     * Subclasses implement provider-specific logout flow.
      */
-    login(options?: any): Observable<void>;
+    abstract logout(): Promise<void>;
     /**
-     * Logout the user
-     * Override to implement provider-specific logout flow
+     * Handle OAuth callback
+     *
+     * Subclasses implement provider-specific callback handling.
      */
-    abstract logout(): Promise<void>;
+    abstract handleCallback(): Promise<void>;
     /**
-     * Get the current access token
-     * Override to retrieve token from provider-specific storage
+     * Extract ID token from provider-specific storage
+     *
+     * This is where providers hide their implementation details.
+     * - Auth0: Extracts from claims.__raw
+     * - MSAL: Extracts from response.idToken
+     * - Okta: Extracts from authState.idToken
+     *
+     * @returns Promise resolving to token string or null if not authenticated
      */
-    abstract getToken(): Promise<string | null>;
+    protected abstract extractIdTokenInternal(): Promise<string | null>;
     /**
-     * Handle callback after redirect
-     * Override to process provider-specific callback logic
+     * Extract complete token info from provider-specific storage
+     *
+     * Maps provider-specific token structure to StandardAuthToken.
+     *
+     * @returns Promise resolving to StandardAuthToken or null if not authenticated
      */
-    abstract handleCallback(): Promise<void>;
+    protected abstract extractTokenInfoInternal(): Promise<StandardAuthToken | null>;
     /**
-     * Check if user is authenticated
+     * Extract user info from provider-specific claims
+     *
+     * Maps provider-specific claim structure to StandardUserInfo.
+     * This is where providers translate their claims (sub, email, name, etc.)
+     * into the standard structure.
+     *
+     * @returns Promise resolving to StandardUserInfo or null if not authenticated
      */
-    isAuthenticated(): Observable<boolean>;
+    protected abstract extractUserInfoInternal(): Promise<StandardUserInfo | null>;
     /**
-     * Get user profile information
+     * Refresh token using provider-specific mechanism
+     *
+     * Implements the provider's token refresh logic using whatever mechanism
+     * is appropriate (silent refresh with refresh tokens, iframe-based token
+     * acquisition, etc.).
+     *
+     * Should return success with token if refresh succeeds, or failure with
+     * appropriate error type (TOKEN_EXPIRED, INTERACTION_REQUIRED, etc.) if
+     * refresh fails.
+     *
+     * @returns Promise resolving to TokenRefreshResult indicating success/failure
      */
-    getUserProfile(): Observable<any>;
+    protected abstract refreshTokenInternal(): Promise<TokenRefreshResult>;
     /**
-     * Get user email
+     * Classify provider-specific error into standard error type
+     *
+     * Maps provider-specific errors to semantic AuthErrorType values.
+     * Examines error objects, error codes, and messages to determine the
+     * appropriate category (TOKEN_EXPIRED, INTERACTION_REQUIRED, NETWORK_ERROR, etc.).
+     *
+     * @param error The error to classify
+     * @returns StandardAuthError with categorized type and user-friendly message
      */
-    getUserEmail(): Observable<string>;
+    protected abstract classifyErrorInternal(error: unknown): StandardAuthError;
     /**
-     * Get provider-specific configuration requirements
-     * Override to specify required config fields
+     * Get profile picture URL from auth provider
+     *
+     * Retrieves the user's profile picture using provider-specific mechanisms.
+     * Some providers include the URL in user claims, others require API calls
+     * to fetch the image.
+     *
+     * @returns Promise resolving to image URL or null if not available
      */
-    getRequiredConfig(): string[];
+    protected abstract getProfilePictureUrlInternal(): Promise<string | null>;
     /**
-     * Validate provider configuration
-     * Override to add provider-specific validation
+     * Handle session expiry when silent refresh fails
+     *
+     * Called internally when silent token refresh fails with TOKEN_EXPIRED or
+     * INTERACTION_REQUIRED errors. Providers that support refresh tokens can
+     * implement this as a no-op. Providers that require interactive re-authentication
+     * should initiate the appropriate flow (redirect, popup, etc.).
+     *
+     * Note: If this method redirects the page, it may never return. The app will
+     * reload after authentication completes and re-initialize with a fresh token.
+     *
+     * @returns Promise that resolves if re-auth completed, or never returns if redirected
      */
-    validateConfig(config: any): boolean;
+    protected abstract handleSessionExpiryInternal(): Promise<void>;
     /**
-     * Helper method to update authentication state
+     * Public login method with Observable wrapper for backward compatibility
+     *
+     * Consumers can use either:
+     * - `await this.authBase.login()` (Promise)
+     * - `this.authBase.login().subscribe()` (Observable)
      */
-    protected updateAuthState(isAuthenticated: boolean): void;
+    login(options?: Record<string, unknown>): Observable<void>;
+    /**
+     * Check if user is authenticated (Observable stream)
+     *
+     * Returns a reactive stream that emits authentication state changes.
+     * Consumers can subscribe to react to login/logout events.
+     */
+    isAuthenticated(): Observable<boolean>;
+    /**
+     * Get user info as Observable stream
+     *
+     * Returns standardized user info, hiding provider-specific claim structures.
+     * No more need for consumers to merge claims or check provider-specific fields!
+     */
+    getUserInfo(): Observable<StandardUserInfo | null>;
     /**
-     * Helper method to update user profile
+     * Get user email as Observable stream
      */
-    protected updateUserProfile(profile: any): void;
+    getUserEmail(): Observable<string>;
     /**
-     * Legacy property for authentication state
+     * Get ID token string (primary token method)
+     *
+     * This is the clean abstraction - no provider-specific logic needed!
+     * Replaces the old pattern of: `claims?.__raw || claims?.idToken`
+     *
+     * @example
+     * ```typescript
+     * const token = await this.authBase.getIdToken();
+     * if (token) {
+     *   setupGraphQLClient(token, apiUrl);
+     * }
+     * ```
      */
-    get authenticated(): boolean;
+    getIdToken(): Promise<string | null>;
     /**
-     * Legacy setter for authentication state
-     * Used by MJExplorer for backward compatibility
+     * Get complete token information
+     *
+     * Returns full token details including expiration and scopes.
+     * Use this when you need more than just the token string.
      */
-    set authenticated(value: boolean);
+    getTokenInfo(): Promise<StandardAuthToken | null>;
     /**
-     * Legacy method to get user
+     * Refresh authentication token
+     *
+     * Attempts to obtain a fresh authentication token using the provider's
+     * refresh mechanism. If silent refresh fails due to session expiry, the
+     * provider will handle re-authentication automatically (which may involve
+     * redirecting to the auth provider's login page).
+     *
+     * Returns StandardAuthToken on success, or throws on complete failure.
+     *
+     * IMPORTANT: If the provider requires interactive re-authentication (redirect
+     * or popup), this method may never return. The app will reload after
+     * authentication completes and re-initialize with a fresh token.
+     *
+     * @returns Promise resolving to StandardAuthToken or throws on failure
+     *
+     * @example
+     * ```typescript
+     * const token = await this.authBase.refreshToken();
+     * return token.idToken; // Always succeeds or throws
+     * ```
      */
-    getUser(): Promise<any>;
+    refreshToken(): Promise<StandardAuthToken>;
     /**
-     * Legacy method to get user claims
+     * Classify an error into standard error type
+     *
+     * Converts provider-specific errors into semantic categories.
+     * Eliminates need for consumers to check error.name or error types.
+     *
+     * @example
+     * ```typescript
+     * const authError = this.authBase.classifyError(err);
+     * if (authError.type === AuthErrorType.TOKEN_EXPIRED) {
+     *   this.showMessage(authError.userMessage);
+     * }
+     * ```
      */
-    getUserClaims(): Promise<Observable<any>>;
+    classifyError(error: unknown): StandardAuthError;
     /**
-     * Legacy method to check expired token error
+     * Get profile picture URL from auth provider
+     *
+     * Returns the user's profile picture URL if available from the auth provider.
+     * This abstracts away provider-specific logic:
+     * - Microsoft/MSAL: Fetches from Graph API
+     * - Auth0/Okta: Returns from user claims
+     *
+     * @returns Promise resolving to image URL or null if not available
+     *
+     * @example
+     * ```typescript
+     * const pictureUrl = await this.authBase.getProfilePictureUrl();
+     * if (pictureUrl) {
+     *   this.userAvatar = pictureUrl;
+     * }
+     * ```
      */
-    checkExpiredTokenError(error: string): boolean;
+    getProfilePictureUrl(): Promise<string | null>;
+    /**
+     * Update authentication state
+     *
+     * Subclasses should call this when authentication state changes
+     * (after login, logout, session check, etc.)
+     */
+    protected updateAuthState(isAuthenticated: boolean): void;
     /**
-     * Legacy refresh method
+     * Update user info
+     *
+     * Subclasses should call this when user info is retrieved or updated.
+     * This automatically updates the email stream as well.
+     */
+    protected updateUserInfo(userInfo: StandardUserInfo | null): void;
+    /**
+     * Get required configuration fields
+     *
+     * Default implementation requires clientId.
+     * Subclasses can override to add provider-specific requirements.
+     */
+    getRequiredConfig(): string[];
+    /**
+     * Validate provider configuration
+     *
+     * Checks that all required fields are present and non-empty.
+     * Subclasses can override to add custom validation logic.
      */
-    refresh(): Promise<Observable<any>>;
+    validateConfig(config: Record<string, unknown>): boolean;
     static ɵfac: i0.ɵɵFactoryDeclaration<MJAuthBase, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<MJAuthBase>;
 }

package/dist/lib/mjexplorer-auth-base.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mjexplorer-auth-base.service.d.ts","sourceRoot":"","sources":["../../src/lib/mjexplorer-auth-base.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAQ,MAAM,MAAM,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;;AAElF;;;GAGG;AACH,8BACsB,UAAW,YAAW,oBAAoB;IAC9D,SAAS,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC5C,SAAS,CAAC,gBAAgB,2BAAuC;IACjE,SAAS,CAAC,YAAY,uBAAkC;IACxD,SAAS,CAAC,UAAU,0BAAmC;IAEvD,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,cAAc,CAAuB;IAC7C;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IACD;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,GAAG,IAAI,CAEjC;IAED,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,MAAM,EAAE,yBAAyB;IAM7C;;;OAGG;IACH,QAAQ,CAAC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAEpC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAE9D;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC;IAItC;;;OAGG;IACH,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAE3C;;;OAGG;IACH,QAAQ,CAAC,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAExC;;OAEG;IACH,eAAe,IAAI,UAAU,CAAC,OAAO,CAAC;IAItC;;OAEG;IACH,cAAc,IAAI,UAAU,CAAC,GAAG,CAAC;IAIjC;;OAEG;IACH,YAAY,IAAI,UAAU,CAAC,MAAM,CAAC;IAIlC;;;OAGG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAI7B;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO;IAKpC;;OAEG;IACH,SAAS,CAAC,eAAe,CAAC,eAAe,EAAE,OAAO,GAAG,IAAI;IAIzD;;OAEG;IACH,SAAS,CAAC,iBAAiB,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI;IAS/C;;OAEG;IACH,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED;;;OAGG;IACH,IAAI,aAAa,CAAC,KAAK,EAAE,OAAO,EAE/B;IAED;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC;IAI7B;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAI/C;;OAEG;IACH,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAO9C;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;yCArKrB,UAAU;6CAAV,UAAU;CA0K/B"}
+{"version":3,"file":"mjexplorer-auth-base.service.d.ts","sourceRoot":"","sources":["../../src/lib/mjexplorer-auth-base.service.ts"],"names":[],"mappings":"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"}

package/dist/lib/mjexplorer-auth-base.service.js

@@ -2,13 +2,32 @@ import { Injectable } from '@angular/core';
 import { BehaviorSubject, from } from 'rxjs';
 import * as i0 from "@angular/core";
 /**
- * Base class for Angular authentication providers
- * Provides common functionality and enforces the provider interface
+ * Base class for Angular authentication providers - v3.0.0
+ *
+ * Provides common functionality and enforces the provider interface.
+ * All concrete providers (MSAL, Auth0, Okta) should extend this class.
+ *
+ * ## Key Improvements in v3.0:
+ * - Proper abstraction - no more leaky provider-specific logic
+ * - Standardized types - no more `any` types
+ * - Clean token access - no more `__raw || idToken` patterns
+ * - Semantic error handling - no more provider-specific error checks
+ *
+ * ## For Provider Implementers:
+ * Extend this class and implement the abstract methods:
+ * - `extractIdTokenInternal()` - Extract token from provider storage
+ * - `extractTokenInfoInternal()` - Extract full token info
+ * - `extractUserInfoInternal()` - Map claims to StandardUserInfo
+ * - `refreshTokenInternal()` - Implement refresh mechanism
+ * - `classifyErrorInternal()` - Map errors to AuthErrorType
+ *
+ * @version 3.0.0
  */
 export class MJAuthBase {
     config;
+    // State management with proper types (no more 'any'!)
     isAuthenticated$ = new BehaviorSubject(false);
-    userProfile$ = new BehaviorSubject(null);
+    userInfo$ = new BehaviorSubject(null);
     userEmail$ = new BehaviorSubject('');
     _initialPath = null;
     _initialSearch = null;
@@ -29,102 +48,218 @@ export class MJAuthBase {
         this._initialPath = window.location.pathname;
         this._initialSearch = window.location.search;
     }
+    // ============================================================================
+    // PUBLIC API (Concrete implementations using abstract internals)
+    // ============================================================================
     /**
-     * Login the user - public API that returns Observable for backward compatibility
+     * Public login method with Observable wrapper for backward compatibility
+     *
+     * Consumers can use either:
+     * - `await this.authBase.login()` (Promise)
+     * - `this.authBase.login().subscribe()` (Observable)
      */
     login(options) {
         return from(this.loginInternal(options));
     }
     /**
-     * Check if user is authenticated
+     * Check if user is authenticated (Observable stream)
+     *
+     * Returns a reactive stream that emits authentication state changes.
+     * Consumers can subscribe to react to login/logout events.
      */
     isAuthenticated() {
         return this.isAuthenticated$.asObservable();
     }
     /**
-     * Get user profile information
+     * Get user info as Observable stream
+     *
+     * Returns standardized user info, hiding provider-specific claim structures.
+     * No more need for consumers to merge claims or check provider-specific fields!
      */
-    getUserProfile() {
-        return this.userProfile$.asObservable();
+    getUserInfo() {
+        return this.userInfo$.asObservable();
     }
     /**
-     * Get user email
+     * Get user email as Observable stream
      */
     getUserEmail() {
         return this.userEmail$.asObservable();
     }
     /**
-     * Get provider-specific configuration requirements
-     * Override to specify required config fields
+     * Get ID token string (primary token method)
+     *
+     * This is the clean abstraction - no provider-specific logic needed!
+     * Replaces the old pattern of: `claims?.__raw || claims?.idToken`
+     *
+     * @example
+     * ```typescript
+     * const token = await this.authBase.getIdToken();
+     * if (token) {
+     *   setupGraphQLClient(token, apiUrl);
+     * }
+     * ```
      */
-    getRequiredConfig() {
-        return ['clientId'];
+    async getIdToken() {
+        return this.extractIdTokenInternal();
     }
     /**
-     * Validate provider configuration
-     * Override to add provider-specific validation
+     * Get complete token information
+     *
+     * Returns full token details including expiration and scopes.
+     * Use this when you need more than just the token string.
      */
-    validateConfig(config) {
-        const requiredFields = this.getRequiredConfig();
-        return requiredFields.every(field => config[field] !== undefined && config[field] !== '');
-    }
-    /**
-     * Helper method to update authentication state
-     */
-    updateAuthState(isAuthenticated) {
-        this.isAuthenticated$.next(isAuthenticated);
+    async getTokenInfo() {
+        return this.extractTokenInfoInternal();
     }
     /**
-     * Helper method to update user profile
+     * Refresh authentication token
+     *
+     * Attempts to obtain a fresh authentication token using the provider's
+     * refresh mechanism. If silent refresh fails due to session expiry, the
+     * provider will handle re-authentication automatically (which may involve
+     * redirecting to the auth provider's login page).
+     *
+     * Returns StandardAuthToken on success, or throws on complete failure.
+     *
+     * IMPORTANT: If the provider requires interactive re-authentication (redirect
+     * or popup), this method may never return. The app will reload after
+     * authentication completes and re-initialize with a fresh token.
+     *
+     * @returns Promise resolving to StandardAuthToken or throws on failure
+     *
+     * @example
+     * ```typescript
+     * const token = await this.authBase.refreshToken();
+     * return token.idToken; // Always succeeds or throws
+     * ```
      */
-    updateUserProfile(profile) {
-        this.userProfile$.next(profile);
-        if (profile?.email) {
-            this.userEmail$.next(profile.email);
+    async refreshToken() {
+        // Try silent refresh
+        const result = await this.refreshTokenInternal();
+        if (result.success && result.token) {
+            // Update state if refresh succeeded
+            try {
+                const userInfo = await this.extractUserInfoInternal();
+                if (userInfo) {
+                    this.updateUserInfo(userInfo);
+                }
+            }
+            catch {
+                // User info update failed, but token refresh succeeded
+                // Don't fail the entire refresh for this
+            }
+            return result.token;
         }
+        // Silent refresh failed - check if we can handle session expiry
+        const errorType = result.error?.type;
+        if (errorType === 'TOKEN_EXPIRED' || errorType === 'INTERACTION_REQUIRED') {
+            // Let provider handle session expiry (may redirect and never return)
+            await this.handleSessionExpiryInternal();
+            // If we reach here (didn't redirect), retry refresh once
+            const retryResult = await this.refreshTokenInternal();
+            if (retryResult.success && retryResult.token) {
+                // Update state with new token
+                try {
+                    const userInfo = await this.extractUserInfoInternal();
+                    if (userInfo) {
+                        this.updateUserInfo(userInfo);
+                    }
+                }
+                catch {
+                    // Ignore user info update errors
+                }
+                return retryResult.token;
+            }
+        }
+        // Complete failure - throw error
+        throw new Error(result.error?.userMessage || 'Token refresh failed');
     }
-    // Backward compatibility methods for existing code
     /**
-     * Legacy property for authentication state
+     * Classify an error into standard error type
+     *
+     * Converts provider-specific errors into semantic categories.
+     * Eliminates need for consumers to check error.name or error types.
+     *
+     * @example
+     * ```typescript
+     * const authError = this.authBase.classifyError(err);
+     * if (authError.type === AuthErrorType.TOKEN_EXPIRED) {
+     *   this.showMessage(authError.userMessage);
+     * }
+     * ```
      */
-    get authenticated() {
-        return this.isAuthenticated$.value;
+    classifyError(error) {
+        return this.classifyErrorInternal(error);
     }
     /**
-     * Legacy setter for authentication state
-     * Used by MJExplorer for backward compatibility
+     * Get profile picture URL from auth provider
+     *
+     * Returns the user's profile picture URL if available from the auth provider.
+     * This abstracts away provider-specific logic:
+     * - Microsoft/MSAL: Fetches from Graph API
+     * - Auth0/Okta: Returns from user claims
+     *
+     * @returns Promise resolving to image URL or null if not available
+     *
+     * @example
+     * ```typescript
+     * const pictureUrl = await this.authBase.getProfilePictureUrl();
+     * if (pictureUrl) {
+     *   this.userAvatar = pictureUrl;
+     * }
+     * ```
      */
-    set authenticated(value) {
-        this.updateAuthState(value);
+    async getProfilePictureUrl() {
+        return this.getProfilePictureUrlInternal();
     }
+    // ============================================================================
+    // HELPER METHODS (For subclasses to update state)
+    // ============================================================================
     /**
-     * Legacy method to get user
+     * Update authentication state
+     *
+     * Subclasses should call this when authentication state changes
+     * (after login, logout, session check, etc.)
      */
-    async getUser() {
-        return this.userProfile$.value;
+    updateAuthState(isAuthenticated) {
+        this.isAuthenticated$.next(isAuthenticated);
     }
     /**
-     * Legacy method to get user claims
+     * Update user info
+     *
+     * Subclasses should call this when user info is retrieved or updated.
+     * This automatically updates the email stream as well.
      */
-    async getUserClaims() {
-        return this.userProfile$.asObservable();
+    updateUserInfo(userInfo) {
+        this.userInfo$.next(userInfo);
+        if (userInfo?.email) {
+            this.userEmail$.next(userInfo.email);
+        }
+        else {
+            this.userEmail$.next('');
+        }
     }
+    // ============================================================================
+    // CONFIGURATION & VALIDATION
+    // ============================================================================
     /**
-     * Legacy method to check expired token error
+     * Get required configuration fields
+     *
+     * Default implementation requires clientId.
+     * Subclasses can override to add provider-specific requirements.
      */
-    checkExpiredTokenError(error) {
-        // Check for common token expiration error messages
-        return error?.toLowerCase().includes('expired') ||
-            error?.toLowerCase().includes('invalid token') ||
-            error?.toLowerCase().includes('unauthorized');
+    getRequiredConfig() {
+        return ['clientId'];
     }
     /**
-     * Legacy refresh method
+     * Validate provider configuration
+     *
+     * Checks that all required fields are present and non-empty.
+     * Subclasses can override to add custom validation logic.
      */
-    async refresh() {
-        // Try to get a new token
-        await this.getToken();
-        return this.userProfile$.asObservable();
+    validateConfig(config) {
+        const requiredFields = this.getRequiredConfig();
+        return requiredFields.every(field => config[field] !== undefined && config[field] !== '');
     }
     static ɵfac = function MJAuthBase_Factory(t) { i0.ɵɵinvalidFactory(); };
     static ɵprov = /*@__PURE__*/ i0.ɵɵdefineInjectable({ token: MJAuthBase, factory: MJAuthBase.ɵfac });