@odx/auth 15.0.0 → 15.0.1

package/fesm2022/odx-auth.mjs

@@ -1,7 +1,7 @@
 import * as i1 from '@angular/common';
 import { CommonModule, AsyncPipe, NgIf } from '@angular/common';
 import * as i0 from '@angular/core';
-import { inject, EnvironmentInjector, Component, ChangeDetectionStrategy, ViewEncapsulation, Input, DestroyRef, InjectionToken, ENVIRONMENT_INITIALIZER, makeEnvironmentProviders, APP_INITIALIZER, Injectable, Directive, EventEmitter, Output, HostListener, input, NgModule } from '@angular/core';
+import { inject, EnvironmentInjector, runInInjectionContext, Component, ChangeDetectionStrategy, ViewEncapsulation, Input, DestroyRef, InjectionToken, ENVIRONMENT_INITIALIZER, makeEnvironmentProviders, APP_INITIALIZER, Injectable, Directive, EventEmitter, Output, HostListener, input, NgModule } from '@angular/core';
 import * as i2$1 from '@odx/angular/components/area-header';
 import { AreaHeaderModule } from '@odx/angular/components/area-header';
 import * as i7 from '@odx/angular/components/dropdown';
@@ -27,17 +27,45 @@ import * as i3 from '@odx/angular/components/icon';
 import { IconComponent } from '@odx/angular/components/icon';
 import { trigger, transition, useAnimation } from '@angular/animations';
 import { fadeOut } from '@odx/angular/animations';
-import * as i5 from '@odx/angular/components/button';
-import { ButtonComponent } from '@odx/angular/components/button';
 import { CircularProgressComponent } from '@odx/angular/components/circular-progress';
 import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import * as i3$1 from '@odx/angular/components/avatar';
 import * as i4 from '@odx/angular/components/action-group';
+import * as i5 from '@odx/angular/components/button';
 
+/**
+ * Creates an authentication host URL based on the provided environment and URL segments.
+ *
+ * @param {AuthEnvironment} environment - The authentication environment (e.g., 'development', 'production').
+ * @param {string[]} segments - Additional URL segments to append to the base URL.
+ * @returns {string} The constructed authentication host URL.
+ *
+ * @example
+ * ```ts
+ * createAuthHostUrl('dev', 'api', 'v1', 'users'); // returns 'https://dev-auth.odx.com/api/v1/users'
+ * ```
+ */
 function createAuthHostUrl(environment, ...segments) {
     return buildUrl(ODX_AUTH_HOSTS[environment], ...segments);
 }
 
+/**
+ * Creates initials from a given string.
+ *
+ * This function takes a string input, removes any text within parentheses,
+ * trims any leading or trailing whitespace, and then splits the string into
+ * parts based on spaces. It then constructs initials using the first letter
+ * of the first and last parts of the string, converting them to uppercase.
+ *
+ * @param {string | null} value - The input string from which to create initials. It can be
+ *                undefined or null, in which case an empty string is returned.
+ * @returns {string} - A string containing the initials derived from the input string.
+ *
+ * @example
+ * ```ts
+ * createInitials('John Smith'); // returns 'JS'
+ * ```
+ */
 function createInitials(value) {
     if (!value)
         return '';
@@ -53,10 +81,20 @@ function createInitials(value) {
     }, '');
 }
 
+/**
+ * Handles authentication errors by executing a series of error handler functions.
+ *
+ * @param {AuthErrorHandlerFn[]} handlers - An array of functions that handle authentication errors.
+ * Each function is expected to take an `OAuthErrorEvent` as an argument.
+ *
+ * @returns A function that takes an `OAuthErrorEvent` and processes it using the provided handlers.
+ * The function will stop processing once a handler successfully handles the error without throwing.
+ * If a handler throws an error that is not an instance of `OAuthErrorEvent`, the original error is re-thrown.
+ */
 function handleAuthError(handlers) {
     const injector = inject(EnvironmentInjector);
     return (error) => {
-        injector.runInContext(() => {
+        runInInjectionContext(injector, () => {
             for (const handler of handlers) {
                 try {
                     handler(error);
@@ -72,10 +110,38 @@ function handleAuthError(handlers) {
     };
 }
 
+/**
+ * Handles OAuth events of a specific type by applying a provided handler function.
+ *
+ * @template {T} - The type of OAuth event.
+ * @param {T['type']} type - The type of the OAuth event to handle.
+ * @param {(event: T) => Promise<void>} handler - A function that takes an event of type T and returns a Promise that resolves to void.
+ * @returns {OperatorFunction<T, void>} - An OperatorFunction that filters events of the specified type and applies the handler function.
+ */
 function handleOAuthEvent(type, handler) {
     return (source$) => source$.pipe(filter((event) => event.type === type), switchMap((event) => handler(event)));
 }
 
+/**
+ * Resolves the email address from the given identity claims.
+ *
+ * This function attempts to extract an email address from the provided
+ * `OdxAuth.RawIdentityClaims` object by checking the following properties
+ * in order:
+ * 1. `email` - if it is a string, it is returned.
+ * 2. `email_address` - if it is a string, it is returned.
+ * 3. `emails` - if it is an array and the first element is a string, the first element is returned.
+ *
+ * If none of these properties contain a valid string email address, an empty string is returned.
+ *
+ * @param {OdxAuth.RawIdentityClaims} claims - The identity claims object from which to resolve the email address.
+ * @returns {string} - The resolved email address as a string, or an empty string if no valid email address is found.
+ *
+ * @example
+ * ```ts
+ * resolveEmail({ email_address: 'email.address@mdn.com' }) // returns 'email.address@mdn.com';
+ * ```
+ */
 function resolveEmail(claims) {
     if (isString(claims['email'])) {
         return claims['email'];
@@ -89,6 +155,27 @@ function resolveEmail(claims) {
     return '';
 }
 
+/**
+ * Resolves the username from the provided identity claims.
+ *
+ * The function attempts to construct a username from the claims in the following order:
+ * 1. If both 'firstname' and 'lastname' are strings, it returns them concatenated with a space.
+ * 2. If both 'given_name' and 'family_name' are strings, it returns them concatenated with a space.
+ * 3. If 'name' is a string, it returns the 'name'.
+ * 4. If 'displayname' is a string, it returns the 'displayname'.
+ * 5. If none of the above conditions are met, it returns an empty string.
+ *
+ * @param {OdxAuth.RawIdentityClaims} claims - The raw identity claims from which to resolve the username.
+ * @returns {string} - The resolved username as a string.
+ *
+ * @example
+ * ```ts
+ * resolveUsername({ firstname: 'John', lastname: 'Doe' }) // returns 'John Doe';
+ * resolveUsername({ given_name: 'John', family_name: 'Doe' }) // returns 'John Doe';
+ * resolveUsername({ name: 'John Doe' }) // returns 'John Doe';
+ * resolveUsername({ displayname: 'John Doe' }) // returns 'John Doe';
+ * ```
+ */
 function resolveUsername(claims) {
     if (isString(claims['firstname']) && isString(claims['lastname'])) {
         return `${claims['firstname']} ${claims['lastname']}`;
@@ -105,6 +192,15 @@ function resolveUsername(claims) {
     return '';
 }
 
+/**
+ * Sets the HTTP Authorization header for a given request.
+ *
+ * @template R - The type of the request, which extends HttpRequest<T> or Request.
+ * @template T - The type of the request body.
+ * @param {R} req - The HTTP request to which the Authorization header will be added.
+ * @param {string | null} [token] - The token to be used in the Authorization header. If no token is provided, the request is returned unchanged.
+ * @returns {R} - The modified HTTP request with the Authorization header set, or the original request if no token is provided.
+ */
 function setHttpAuthHeader(req, token) {
     if (!token)
         return req;
@@ -119,6 +215,13 @@ function setHttpAuthHeader(req, token) {
 const AuthEnvironment = Environment;
 
 const requireAuthentication = new HttpContextToken(() => false);
+/**
+ * Interceptor to handle authentication for HTTP requests.
+ *
+ * This interceptor checks if the request URL is allowed or if the request requires authentication.
+ * If the URL is not allowed and the request does not require authentication, it simply forwards the request.
+ * Otherwise, it prepares the authentication request using the AuthService.
+ */
 const authInterceptor = (req, next) => {
     const { allowedUrls, requireSignInForRequests } = injectAuthConfig();
     const isUrlAllowed = allowedUrls.some((allowedUrl) => matchUrl(req.url, allowedUrl));
@@ -130,9 +233,18 @@ const authInterceptor = (req, next) => {
 
 var logger = new Logger('@odx/auth');
 
+/**
+ * Displays authentication actions.
+ */
 let AuthActionsComponent = class AuthActionsComponent {
     constructor() {
         this.element = injectElement();
+        /**
+         * The identity claims.
+         *
+         * @type {OdxAuth.IdentiyClaims | null}
+         * @default null
+         */
         this.claims = null;
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "18.2.12", ngImport: i0, type: AuthActionsComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
@@ -148,12 +260,25 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.12", ngImpo
                 type: Input
             }] } });
 
+/**
+ * Authentication loading screen.
+ *
+ * This component displays a loading screen with animations and dynamic content
+ * based on the authentication state.
+ */
 class AuthLoadingScreenComponent {
     constructor() {
         this.authConfig = injectAuthConfig();
         this.icon$ = inject(AuthService).isRedirecting$.pipe(map((isRedirecting) => (isRedirecting ? 'link-external' : 'user')));
     }
     static { this.instance = null; }
+    /**
+     * Initializes the authentication loading screen.
+     *
+     * @param {AuthService} authService - The authentication service.
+     * @param {DynamicViewService} dynamicViewService - The dynamic view service used to create the loading screen.
+     * @static
+     */
     static initialize(authService, dynamicViewService) {
         authService.isLoading$.subscribe((isLoading) => {
             if (isLoading) {
@@ -170,11 +295,20 @@ class AuthLoadingScreenComponent {
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.12", ngImport: i0, type: AuthLoadingScreenComponent, decorators: [{
             type: Component,
-            args: [{ standalone: true, selector: 'div.odx-auth-loading-screen', imports: [CommonModule, ButtonComponent, IconComponent, LogoDirective, CircularProgressComponent, DynamicViewDirective], changeDetection: ChangeDetectionStrategy.OnPush, encapsulation: ViewEncapsulation.None, host: {
+            args: [{ standalone: true, selector: 'div.odx-auth-loading-screen', imports: [CommonModule, IconComponent, LogoDirective, CircularProgressComponent, DynamicViewDirective], changeDetection: ChangeDetectionStrategy.OnPush, encapsulation: ViewEncapsulation.None, host: {
                         '[@hostAnimation]': 'true',
                     }, animations: [trigger('hostAnimation', [transition(':leave', useAnimation(fadeOut()))])], template: "<div class=\"odx-auth-loading-screen__content\" odxLayout=\"grid 12 horizontal-center vertical-center gap-small\">\n  <odx-logo size=\"large\" />\n  <odx-circular-progress class=\"odx-auth-loading-screen__spinner\" value=\"-1\" size=\"medium\" stroke=\"3\">\n    <odx-icon [name]=\"icon$ | async\" iconSet=\"core\" />\n  </odx-circular-progress>\n  @if (authConfig.loadingScreenMessage; as content) {\n    <p class=\"odx-auth-loading-screen__message\">\n      <ng-template [odxDynamicView]=\"content\" />\n    </p>\n  }\n</div>\n", styles: ["@keyframes odx-auth-loading-screen-animation{0%{opacity:0;transform:translate(-50%,-50%) scale(.9)}to{opacity:1;transform:translate(-50%,-50%)}}.odx-auth-loading-screen{--odx-c-highlight: var(--odx-c-primary);background-color:var(--odx-c-background-content);inset:0;position:fixed;z-index:var(--odx-v-layer-6)}.odx-auth-loading-screen__content{animation:odx-auth-loading-screen-animation .75s ease;left:50%;position:absolute;top:50%;transform:translate(-50%,-50%)}.odx-auth-loading-screen__message{text-align:center}.odx-auth-loading-screen__spinner{position:relative}.odx-auth-loading-screen__spinner .odx-icon{left:50%;position:absolute;top:50%;transform:translate(-50%,-50%)}\n"] }]
         }] });
 
+/**
+ * A factory function that creates a core debug plugin for the authentication service.
+ * This plugin logs detailed information about the user's identity claims and tokens.
+ *
+ * @remarks
+ * This plugin is intended for debugging purposes only and should not be used in production environments.
+ *
+ * @returns {AuthPluginFactory} A function that takes an authentication service and sets up logging for identity claims and tokens.
+ */
 const coreDebugPlugin = () => {
     logger.warn('DEBUG MODE ENABLED - DO NOT USE IN PRODUCTION!');
     const destroyRef = inject(DestroyRef);
@@ -191,6 +325,13 @@ const coreDebugPlugin = () => {
     };
 };
 
+/**
+ * Core identity plugin for authentication.
+ *
+ * This plugin extracts and processes identity claims from the authentication service.
+ *
+ * @returns {AuthPluginFactory} A factory function that returns an observable with the processed identity claims.
+ */
 const coreIdentityPlugin = () => {
     const { resolveEmail, resolveUsername, createInitials } = injectAuthConfig();
     return (authService) => {
@@ -202,6 +343,15 @@ const coreIdentityPlugin = () => {
     };
 };
 
+/**
+ * A plugin factory that generates a user profile URL plugin.
+ *
+ * This plugin retrieves the user profile URL from the authentication configuration.
+ * If the user profile URL is not specified in the configuration, it falls back to
+ * using the default URL for the current environment from `ODX_AUTH_USER_PROFILE_HOSTS`.
+ *
+ * @returns A function that returns an observable emitting an object containing the user profile URL.
+ */
 const userProfileUrlPlugin = () => {
     const { environment, userProfileUrl } = injectAuthConfig();
     return () => {
@@ -239,6 +389,11 @@ const ODX_AUTH_PLUGINS = new InjectionToken('@odx/auth::Plugins', {
         return [...corePlugins, ...plugins].map((pluginFactory) => pluginFactory());
     },
 });
+/**
+ * Provides a logger for the authentication module.
+ *
+ * @returns {Provider} - The provider for the logger.
+ */
 function provideAuthLogger() {
     return {
         provide: ENVIRONMENT_INITIALIZER,
@@ -251,11 +406,19 @@ function provideAuthLogger() {
         multi: true,
     };
 }
+/**
+ * Initializes the authentication error handlers.
+ */
 function initializeAuthErrorHandlers() {
     const authService = inject(AuthService);
     const handler = handleAuthError(inject(ODX_AUTH_ERROR_HANDLERS));
     authService.errors$.pipe(tap((error) => handler(error))).subscribe();
 }
+/**
+ * Initializes the authentication configuration.
+ *
+ * @returns {() => Promise<void>} - A function that returns a promise resolving when the configuration is initialized.
+ */
 function initalizeAuthConfig() {
     const { clientId, scopes, redirectPath, environment, postLogoutRedirectUrl, issuer, timeoutFactor, discoveryUrl, enableLoadingScreen } = injectAuthConfig();
     const authService = inject(AuthService);
@@ -278,6 +441,27 @@ function initalizeAuthConfig() {
         waitForTokenInMsec: 1000,
     });
 }
+/**
+ * Provides the authentication configuration and dependencies.
+ *
+ * @param {ConfigProvider<Partial<AuthConfig>, D>} config - The configuration provider.
+ * @returns {EnvironmentProviders} The environment providers for authentication.
+ * @template D
+ *
+ * @example Provide the authentication configuration and dependencies
+ * ```ts
+ * providers: [
+ *  provideAuth({
+ *   useFactory: ({ environment, auth: { clientId, loadUserProfile } }: ApplicationEnvironment) => ({
+ *     environment,
+ *     clientId,
+ *     loadUserProfile,
+ *   }),
+ *   deps: [APPLICATION_ENVIRONMENT],
+ *  }),
+ * ],
+ * ```
+ */
 function provideAuth(config) {
     return makeEnvironmentProviders([
         provideAuthConfig(config),
@@ -345,7 +529,40 @@ const offlineAuthErrorHandler = (error) => {
     throw error;
 };
 
+/**
+ * The `AuthService` class provides authentication functionality for an Angular application.
+ * It handles OAuth2/OIDC authentication, token management, and user identity claims.
+ *
+ * Key responsibilities include:
+ * - Initializing authentication with a provided configuration.
+ * - Managing tokens (access, refresh, and ID tokens).
+ * - Checking and emitting authentication and authorization states.
+ * - Handling user login and logout flows.
+ * - Supporting silent refresh and offline authentication scenarios.
+ * - Integrating authentication plugins via `AuthPluginManager`.
+ *
+ * @example
+ * ```typescript
+ * // Injecting the AuthService
+ * constructor(private authService: AuthService) {}
+ *
+ * // Using the AuthService to initialize authentication
+ * async ngOnInit() {
+ *   const config: AuthConfig = { clientId: 'your-client-id', discoveryUrl: 'https://example.com/.well-known/openid-configuration' };
+ *   await this.authService.initialize(config);
+ * }
+ * ```
+ */
 class AuthService {
+    /**
+     * Emits whenever the `access_token` in local storage is updated or cleared.
+     * Provides an observable for tracking token updates.
+     *
+     * @type {Observable<StorageEvent | null>}
+     */
+    get accessTokenUpdate$() {
+        return this.onAccessTokenUpdate$;
+    }
     constructor() {
         this.authConfig = injectAuthConfig();
         this.authPluginManager = inject(AuthPluginManager);
@@ -357,16 +574,62 @@ class AuthService {
         this.onAccessTokenUpdate$ = fromEvent(this.windowRef.nativeWindow, 'storage').pipe(filter(({ key }) => key === 'access_token' || key === null), startWith(null), share());
         this.silentRefreshHandler$ = this.isInitialized$$.pipe(filter(Boolean), switchMap(() => this.windowRef.isOnline$), tap((isOnline) => this.updateSilentRefresh(isOnline)));
         this.onAuthStateChange$ = combineLatest([this.oauthService.events.pipe(startWith(null)), this.windowRef.isOnline$, this.onAccessTokenUpdate$]);
+        /**
+         * Emits `true` when the service has completed initialization.
+         * Emits `false` until the initialization is complete.
+         *
+         * @type {Observable<boolean>}
+         */
         this.isInitialized$ = this.isInitialized$$.pipe(filter(Boolean), distinctUntilChanged());
+        /**
+         * Emits `true` when the user is being redirected to the login page.
+         * Emits `false` when there is no redirection in progress.
+         *
+         * @type {Observable<boolean>}
+         */
         this.isRedirecting$ = this.isRedirecting$$.pipe(distinctUntilChanged(), shareReplay({ bufferSize: 1, refCount: true }));
+        /**
+         * Emits `true` when the application is in a loading state (e.g., during redirection or plugin initialization).
+         * Emits `false` when there is no ongoing loading activity.
+         *
+         * @type {Observable<boolean>}
+         */
         this.isLoading$ = merge(this.isRedirecting$, this.authPluginManager.pluginsLoading$).pipe(distinctUntilChanged());
+        /**
+         * Emits `true` when the user is authenticated.
+         * Emits `false` when the user is not authenticated.
+         *
+         * @type {Observable<boolean>}
+         */
         this.isAuthenticated$ = this.isInitialized$.pipe(switchMap(() => this.authPluginManager.pluginsReady$), switchMap(() => this.onAuthStateChange$), map(() => this.isAuthenticated()), distinctUntilChanged(), shareReplay({ bufferSize: 1, refCount: true }));
+        /**
+         * Emits the identity claims of the authenticated user.
+         * If the user is not authenticated, emits `null`.
+         *
+         * @type {Observable<OdxAuth.IdentityClaims | null>}
+         */
         this.identityClaims$ = this.isAuthenticated$.pipe(map(() => this.getIdentityClaims()), shareReplay({ bufferSize: 1, refCount: true }));
+        /**
+         * Emits OAuth error events.
+         *
+         * @type {Observable<OAuthErrorEvent>}
+         */
         this.errors$ = this.oauthService.events.pipe(filter((event) => event instanceof OAuthErrorEvent), share());
+        /**
+         * Emits events when an OAuth token is successfully received.
+         *
+         * @type {Observable<Event>}
+         */
         this.onTokenReceived$ = this.oauthService.events.pipe(filter((event) => event.type === 'token_received'), share());
         this.runPlugins();
         this.silentRefreshHandler$.subscribe();
     }
+    /**
+     * Initializes the authentication service with the provided configuration.
+     *
+     * @param {AuthConfig} config - The authentication configuration object.
+     * @returns {Promise<void>} Resolves when initialization is complete.
+     */
     async initialize(config) {
         this.assertAudience(config.clientId);
         this.oauthService.configure({ ...config, openUri: this.redirectToLogin.bind(this) });
@@ -393,57 +656,136 @@ class AuthService {
         await this.tryLoadUserProfile();
         await this.routeToRequestedUrl();
     }
+    /**
+     * Runs all authentication plugins registered in the `AuthPluginManager`.
+     */
     runPlugins() {
         this.authPluginManager.runPlugins(this).subscribe();
     }
+    /**
+     * Returns the issuer URL for the OAuth server.
+     *
+     * @returns {URL} The issuer URL.
+     */
     getIssuer() {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         return new URL(this.oauthService.issuer);
     }
+    /**
+     * Initiates the login flow for the user. Redirects to the login page.
+     *
+     * @param {string} [url] - The URL to redirect back to after login.
+     */
     signIn(url) {
         this.oauthService.initLoginFlow(url);
     }
+    /**
+     * Logs the user out and clears their tokens.
+     *
+     * @param {boolean} [noRedirect] - If `true`, no redirection occurs after logout.
+     */
     signOut(noRedirect) {
         this.oauthService.logOut(noRedirect || !this.getAccessToken());
     }
+    /**
+     * Attempts to refresh the user's tokens.
+     *
+     * @returns {Promise<TokenResponse>} Resolves with the new token response.
+     */
     async refreshTokens() {
         return this.oauthService.refreshToken();
     }
+    /**
+     * Retrieves the current access token, if available.
+     *
+     * @returns {string | null} The access token, or `null` if not available.
+     */
     getAccessToken() {
         return this.oauthService.getAccessToken() ?? null;
     }
+    /**
+     * Retrieves the current refresh token, if available.
+     *
+     * @returns {string | null} The refresh token, or `null` if not available.
+     */
     getRefreshToken() {
         return this.oauthService.getRefreshToken() ?? null;
     }
+    /**
+     * Retrieves the current ID token, if available.
+     *
+     * @returns {string | null} The ID token, or `null` if not available.
+     */
     getIdToken() {
         return this.oauthService.getIdToken() ?? null;
     }
+    /**
+     * Retrieves the identity claims of the authenticated user.
+     *
+     * @returns {OdxAuth.IdentityClaims | null} The identity claims, or `null` if not available.
+     */
     getIdentityClaims() {
         if (!this.getIdToken())
             return null;
         return deepmerge(this.oauthService.getIdentityClaims(), this.authPluginManager.getResult());
     }
+    /**
+     * Retrieves the raw identity claims of the authenticated user.
+     *
+     * @returns {OdxAuth.RawIdentityClaims | null} The raw identity claims, or `null` if not available.
+     */
     getRawIdentityClaims() {
         if (!this.getIdToken())
             return null;
         return this.oauthService.getIdentityClaims();
     }
+    /**
+     * Checks if the user is currently authenticated.
+     *
+     * @returns {boolean} `true` if authenticated, otherwise `false`.
+     */
     isAuthenticated() {
         if (this.windowRef.isOnline()) {
             return this.oauthService.hasValidAccessToken() && this.oauthService.hasValidIdToken();
         }
         return this.hasValidOfflineToken();
     }
+    /**
+     * Checks if the user is authorized based on the provided handler.
+     *
+     * @param {AuthorizedHandler | null} [authorizedHandler] - A handler to determine authorization.
+     * @returns {boolean} `true` if authorized, otherwise `false`.
+     */
     isAuthorized(authorizedHandler) {
         const handler = authorizedHandler ?? this.authConfig.defaultAuthorizedHandler;
         return this.isAuthenticated() && (handler?.(this.getIdentityClaims(), this, this.router) ?? true);
     }
+    /**
+     * Emits whether the user is authorized based on the provided handler.
+     *
+     * @param {AuthorizedHandler | null} [authorizedHandler] - A handler to determine authorization.
+     * @returns {Observable<boolean>} An observable emitting the authorization status.
+     */
     isAuthorized$(authorizedHandler) {
         return this.isAuthenticated$.pipe(map(() => this.isAuthorized(authorizedHandler)));
     }
+    /**
+     * Prepares an HTTP request by adding the access token to its headers.
+     *
+     * @param {HttpRequest<T> | Request} req - The HTTP request to prepare.
+     * @param {boolean} requireSignIn - Whether to require the user to sign in if no token is available.
+     * @returns {Observable<R>} An observable emitting the prepared request.
+     * @template R, T
+     */
     prepareAuthRequest$(req, requireSignIn = false) {
         return this.waitForAccessToken$(requireSignIn).pipe(map((token) => setHttpAuthHeader(req, token)));
     }
+    /**
+     * Waits for a valid access token to become available.
+     *
+     * @param {boolean} requireSignIn - Whether to require the user to sign in if no token is available.
+     * @returns {Observable<string | null>} An observable emitting the access token.
+     */
     waitForAccessToken$(requireSignIn) {
         const accessToken$ = of(this.getAccessToken()).pipe(filter((token) => !!token && this.isAuthenticated()));
         const waitForAccessToken$ = this.onTokenReceived$.pipe(timeout(this.authConfig.waitForTokenInMs ?? 0), catchError(async () => this.tryRefreshToken().catch(() => null)));
@@ -494,6 +836,13 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.12", ngImpo
             args: [{ providedIn: 'root' }]
         }], ctorParameters: () => [] });
 
+/**
+ * A function that creates a language loader function for user authentication.
+ *
+ * @param {LanguageSelector} languageSelector - A function that takes optional identity claims and returns a language string, null, or undefined.
+ *                           Defaults to a function that returns the preferred language from the claims.
+ * @returns {LanguageLoaderFn} - A function that retrieves the user's preferred language from the identity claims.
+ */
 function userLanguageLoader(languageSelector = (claims) => claims?.preferredLanguage) {
     return () => {
         return inject(AuthService).identityClaims$.pipe(map(languageSelector), map((value) => (isNonEmptyString(value) ? value : undefined)));
@@ -512,6 +861,43 @@ const ODX_AUTH_USER_PROFILE_HOSTS = {
     stage: 'https://purple-cliff-0e61c5703.3.azurestaticapps.net',
     prod: 'https://id.draeger.com',
 };
+/**
+ * Tools for injecting and providing the auth configuration with default configuration for the authentication.
+ *
+ * @example
+ * // Providing custom authentication configuration.
+ * ```ts
+ *   import { createInitials, resolveEmail, resolveUsername } from './helpers';
+ *
+ *   providers: [provideAuthConfig({
+ *        environment: 'dev',
+ *        redirectPath: 'login/callback',
+ *        allowedUrls: [],
+ *        timeoutFactor: 0.75,
+ *        maxOfflineTime: 60 * 60, // 1 hour
+ *        loadUserProfile: false,
+ *        errorHandler: (error) => {
+ *          throw error;
+ *        },
+ *        createInitials,
+ *        resolveEmail,
+ *        resolveUsername,
+ *        plugins: [],
+ *        defaultAuthorizedHandler: null,
+ *        enableLoadingScreen: true,
+ *        loadingScreenMessage: 'Loading...',
+ *        waitForTokenInMs: 500,
+ *
+ *    })],
+ *
+ * // Injecting the datepicker configuration.
+ * ```ts
+ * @Component({})
+ * export class MyComponent {
+ *  constructor(@Inject(injectAuthConfig()) private readonly authConfig: AuthConfig) {}
+ * }
+ * ```
+ */
 const { AuthDefaultConfig, AuthConfig, injectAuthConfig, provideAuthConfig } = createConfigTokens('Auth', '@odx/auth', {
     environment: 'prod',
     redirectPath: 'login/callback',
@@ -545,6 +931,12 @@ var translations = {
     },
 };
 
+/**
+ * An abstract directive that integrates with the `LoadingSpinnerDirective` and `AuthService` to manage loading states based on authentication redirection.
+ *
+ * This directive automatically sets the `autoColor` property of the `LoadingSpinnerDirective` to `true` and subscribes to the `isRedirecting$` observable from the `AuthService`.
+ * When `isRedirecting$` emits a value, it updates the `isLoading` property of the `LoadingSpinnerDirective`.
+ */
 class AuthActionDirective {
     constructor() {
         this.takeUntilDestroyed = untilDestroyed();
@@ -564,9 +956,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.12", ngImpo
             type: Directive
         }] });
 
+/**
+ * A directive that handles the sign-in action for a button element.
+ *
+ * This directive extends the `AuthActionDirective` and uses the `LoadingSpinnerDirective`
+ * to show a loading spinner during the sign-in process.
+ *
+ * @see {AuthActionDirective}
+ * @see {LoadingSpinnerDirective}
+ *
+ * @example
+ * ```html
+ * <button odxButton odxAuthSignIn (odxAuthSignIn)="onSignIn()">Sign In</button>
+ * ```
+ */
 class SignInDirective extends AuthActionDirective {
     constructor() {
         super(...arguments);
+        /**
+         * Emits an event after the sign-in action is completed.
+         *
+         * @type {EventEmitter<void>}
+         */
         // eslint-disable-next-line @angular-eslint/no-output-rename
         this.afterSignIn = new EventEmitter();
     }
@@ -592,9 +1003,28 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.12", ngImpo
                 args: ['click']
             }] } });
 
+/**
+ * A directive that handles the sign-out action for a button element.
+ *
+ * This directive extends the `AuthActionDirective` and uses the `LoadingSpinnerDirective`
+ * to show a loading spinner during the sign-out process.
+ *
+ * @see {AuthActionDirective}
+ * @see {LoadingSpinnerDirective}
+ *
+ * @example
+ * ```html
+ * <button odxButton odxAuthSignOut (odxAuthSignOut)="onSignOut()">Sign Out</button>
+ * ```
+ */
 class SignOutDirective extends AuthActionDirective {
     constructor() {
         super(...arguments);
+        /**
+         * Emits an event after the sign-out action is completed.
+         *
+         * @type {EventEmitter<void>}
+         */
         // eslint-disable-next-line @angular-eslint/no-output-rename
         this.afterSignOut = new EventEmitter();
     }
@@ -633,6 +1063,11 @@ class AuthComponent {
             idClaims: this.authService.identityClaims$,
             isAuthenticated: this.authService.isAuthenticated$,
         });
+        /**
+         * Whether to hide the institution information.
+         *
+         * @type {InputSignal<boolean>}
+         */
         this.hideInstitution = input(false);
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "18.2.12", ngImport: i0, type: AuthComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
@@ -659,8 +1094,18 @@ class AuthDirective {
         this.authService = inject(AuthService);
         this.ngIfDirective = inject(NgIf, { host: true });
         this.takeUntilDestroyed = untilDestroyed();
+        /**
+         * The authorization handler or a string representing the handler.
+         *
+         * @type {AuthorizedHandler | null | string}
+         */
         this.authorizationHandler = null;
     }
+    /**
+     * Sets the template to be displayed when the authorization check fails.
+     *
+     * @param {TemplateRef<NgIfContext<unknown>>} value - The template reference.
+     */
     // eslint-disable-next-line @angular-eslint/no-input-rename
     set elseTemplate(value) {
         this.ngIfDirective.ngIfElse = value;
@@ -689,6 +1134,14 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.12", ngImpo
                 args: ['odxAuthElse']
             }] } });
 
+/**
+ * Guard function to protect routes from unauthorized access.
+ *
+ * @param {AuthorizedHandler} [authorizedHandler] - Optional handler to check if the user is authorized.
+ * @param {string | any[]} [redirectTo] - Optional URL or route to redirect unauthorized users to. Can be a string or an array of strings.
+ * @param {boolean} [isExternal=false] - Optional flag to indicate if the redirection should be external. Defaults to false.
+ * @returns {CanActivateFn} A function that implements the CanActivateFn interface.
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function authGuard(authorizedHandler, redirectTo, isExternal = false) {
     return (_, state) => {
@@ -733,6 +1186,14 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.12", ngImpo
                 }]
         }] });
 
+/**
+ * Guard function to prevent unauthorized access to routes.
+ *
+ * @param {AuthorizedHandler} authorizedHandler - Optional handler to check if the user is authorized.
+ * @param {any[] | string} redirectTo - Optional URL or route to redirect unauthorized users to. Can be a string or an array of strings.
+ * @param {boolean} isExternal - Optional flag to indicate if the redirection should be external. Defaults to false.
+ * @returns {CanActivateFn} - A function that implements the CanActivateFn interface.
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function unauthGuard(authorizedHandler, redirectTo, isExternal = false) {
     return (_) => {