@opensourcekd/ng-common-libs 2.0.10 → 2.1.0

package/dist/index.d.ts

@@ -413,6 +413,7 @@ declare function buildUserData(userInfo: UserInfo): UserData;
 declare class AuthService {
     private auth0Client;
     private initializationPromise;
+    /** Remains false if callback processing fails, allowing the callback to be retried. */
     private callbackHandled;
     private callbackPromise;
     private userSubject;
@@ -447,6 +448,13 @@ declare class AuthService {
      * @throws {Error} When required config fields (domain, clientId) are missing
      */
     private initializeAuth0;
+    /**
+     * Ensure the Auth0 client instance is created, without triggering callback detection.
+     * Used internally by {@link handleCallback} to avoid a circular async dependency:
+     * `ensureInitialized` → `checkAndHandleCallback` → `handleCallback` → `ensureInitialized`.
+     * @throws {Error} When the Auth0 client fails to initialize
+     */
+    private ensureAuth0Client;
     /**
      * Ensure the Auth0 client is initialized before use
      * Lazy-initializes on the first call and auto-handles OAuth callbacks when detected
@@ -459,6 +467,10 @@ declare class AuthService {
      * The Auth0 SDK's `handleRedirectCallback` validates the `state` parameter
      * to prevent CSRF attacks. This method only detects presence of callback
      * params before delegating securely to the SDK.
+     *
+     * Uses an async IIFE to store the in-flight promise for concurrency deduplication
+     * (concurrent callers await the same promise) while still using async/await
+     * internally instead of `.then()/.catch()` chains.
      */
     private checkAndHandleCallback;
     /**
@@ -474,11 +486,20 @@ declare class AuthService {
     /**
      * Handle the OAuth2 redirect callback after successful authorization
      * Stores the user info and access token, then cleans up the callback URL
+     *
+     * Uses {@link ensureAuth0Client} (not {@link ensureInitialized}) to avoid a circular
+     * async dependency: `ensureInitialized` → `checkAndHandleCallback` → `handleCallback`
+     * → `ensureInitialized`. Only the Auth0 client instance is needed here.
      * @returns {@link CallbackResult} with `success` flag and optional `appState`
      */
     handleCallback(): Promise<CallbackResult>;
     /**
      * Log the user out, clear all stored auth data, and redirect to the logout URI
+     *
+     * Uses {@link ensureAuth0Client} (not {@link ensureInitialized}) to avoid triggering
+     * callback detection during logout. Calling `ensureInitialized` here would invoke
+     * `checkAndHandleCallback`, which re-authenticates the user if callback URL params
+     * are present, causing them to be sent back to Auth0 instead of the logout URI.
      */
     logout(): Promise<void>;
     /**
@@ -773,5 +794,197 @@ declare class Logger {
     }): void;
 }
 
-export { APP_CONFIG, AUTH0_CONFIG, AuthService, EventBus, LogSeverity, Logger, STANDARD_JWT_CLAIMS, STORAGE_CONFIG, STORAGE_KEYS, buildUserData, configureAuth0, createAuthService, decodeAndStoreToken, extractClaimValue, getCustomClaims, getDecodedToken, getStorageItem, isNamespacedClaim, removeStorageItem, resetAuth0Config, setStorageItem };
-export type { AppState, Auth0Config, Auth0ConfigOptions, AuthServiceOptions, AuthorizationParams, CallbackResult, EventBusOptions, EventPayload, LogAttributes, LogRecord, LoggerOptions, StorageConfig, StorageKeys, TokenPayload, UserData, UserInfo };
+/**
+ * Configuration for a {@link BearerTokenInterceptor} instance.
+ *
+ * @example
+ * ```typescript
+ * const config: BearerTokenInterceptorConfig = {
+ *   apiUrl: 'https://api.example.com',
+ *   getToken: () => authService.getTokenSync(),
+ * };
+ * ```
+ */
+interface BearerTokenInterceptorConfig {
+    /**
+     * API base URL to match against — only requests whose URL begins with this
+     * string will receive the `Authorization` header.
+     * Defaults to {@link APP_CONFIG}.apiUrl when not provided.
+     */
+    apiUrl?: string;
+    /**
+     * Synchronous function that returns the current bearer token string,
+     * or `null` when no token is available (e.g. before login).
+     */
+    getToken: () => string | null;
+}
+/**
+ * BearerTokenInterceptor
+ *
+ * A per-identifier singleton that patches the global `window.fetch` to
+ * automatically attach an `Authorization: Bearer <token>` header to every
+ * request whose URL begins with the configured API base URL.
+ *
+ * **Singleton behaviour**: the first call to {@link BearerTokenInterceptor.getInstance}
+ * for a given `id` creates the instance; subsequent calls with the same `id`
+ * return the previously created instance, regardless of the `config` argument.
+ *
+ * Designed for Module Federation micro-frontend environments where both the
+ * fetch wrapper and the XHR prototype must be shared across the shell and all
+ * remote applications.
+ *
+ * @example
+ * ```typescript
+ * import { BearerTokenInterceptor, APP_CONFIG } from '@opensourcekd/ng-common-libs';
+ *
+ * // In the shell app — creates the instance
+ * const interceptor = BearerTokenInterceptor.getInstance('shell', {
+ *   apiUrl: APP_CONFIG.apiUrl,
+ *   getToken: () => authService.getTokenSync(),
+ * });
+ * interceptor.activate();
+ *
+ * // In any MFE — same instance is returned
+ * const same = BearerTokenInterceptor.getInstance('shell', { getToken: () => null });
+ * console.log(same === interceptor); // true
+ * ```
+ */
+declare class BearerTokenInterceptor {
+    private static readonly instances;
+    private static originalFetch;
+    private static originalXhrOpen;
+    private static originalXhrSend;
+    private readonly id;
+    private readonly apiUrl;
+    private readonly tokenFn;
+    private active;
+    private constructor();
+    /**
+     * Get or create the singleton interceptor for the given identifier.
+     *
+     * The first invocation with a given `id` creates the instance using the
+     * supplied `config`. Subsequent calls with the same `id` return the existing
+     * instance — the `config` argument is ignored on subsequent calls.
+     *
+     * @param id - Unique identifier for this interceptor (e.g. `'shell'`, `'mfe-orders'`)
+     * @param config - Configuration used only when creating a new instance
+     * @returns The singleton {@link BearerTokenInterceptor} for the given `id`
+     *
+     * @example
+     * ```typescript
+     * const interceptor = BearerTokenInterceptor.getInstance('shell', {
+     *   apiUrl: 'https://api.example.com',
+     *   getToken: () => authService.getTokenSync(),
+     * });
+     * ```
+     */
+    static getInstance(id: string, config: BearerTokenInterceptorConfig): BearerTokenInterceptor;
+    /**
+     * Get the identifier of this interceptor instance.
+     * @returns The `id` string supplied when the instance was created
+     */
+    getId(): string;
+    /**
+     * Get the API base URL that this interceptor matches against.
+     * @returns The configured API URL string
+     */
+    getApiUrl(): string;
+    /**
+     * Check whether this interceptor is currently active.
+     * @returns `true` if the interceptor has been activated and not yet deactivated
+     */
+    isActive(): boolean;
+    /**
+     * Activate the interceptor.
+     *
+     * Patches `window.fetch` and `XMLHttpRequest` once (on the first active
+     * interceptor) so that matching requests receive the bearer token.
+     * Subsequent calls are no-ops. No-op in non-browser environments.
+     */
+    activate(): void;
+    /**
+     * Deactivate the interceptor.
+     *
+     * Stops attaching the bearer token for this interceptor's URL pattern.
+     * Both the global fetch wrapper and the XHR prototype patches are removed
+     * automatically once all registered interceptors have been deactivated.
+     * No-op when already inactive.
+     */
+    deactivate(): void;
+    /**
+     * Return the effective bearer token for a given request URL, or `null` if
+     * this interceptor should not modify the request.
+     *
+     * Returns `null` when the interceptor is inactive, the URL does not begin
+     * with the configured API base URL, or the token getter returns `null`.
+     *
+     * @param url - The absolute URL of the outgoing request
+     * @returns Bearer token string or `null`
+     */
+    private getEffectiveToken;
+    /**
+     * Extract headers from a `RequestInit` object into a plain key-value map.
+     * Handles `Headers` instances, `[key, value]` arrays, and plain objects.
+     *
+     * @param init - Optional `RequestInit` whose headers to extract
+     * @returns A plain `Record<string, string>` copy of the headers
+     */
+    private static extractHeaders;
+    /**
+     * Find the bearer token for a given URL by consulting all active interceptors.
+     * Uses first-match semantics to avoid ambiguity when multiple interceptors
+     * share the same API URL prefix.
+     *
+     * @param url - Absolute URL of the outgoing request
+     * @returns The first matching bearer token string, or `null`
+     */
+    private static findToken;
+    /**
+     * Apply the `Authorization: Bearer` header from the first active interceptor
+     * that matches the given URL. Uses first-match semantics to avoid ambiguity
+     * when multiple interceptors share the same API URL prefix.
+     *
+     * @param url - Absolute URL of the outgoing fetch request
+     * @param init - Original `RequestInit` options
+     * @returns Modified `RequestInit` with the `Authorization` header added when applicable
+     */
+    private static applyBearerToken;
+    /**
+     * Install the global fetch wrapper exactly once.
+     * The wrapper delegates to {@link applyBearerToken} for every outgoing request.
+     * No-op when already patched or in a non-browser environment.
+     */
+    private static patchFetch;
+    /**
+     * Restore the original `window.fetch` if no interceptors remain active.
+     * No-op when the fetch has not been patched or some interceptors are still active.
+     */
+    private static maybeRestoreFetch;
+    /**
+     * Install a global `XMLHttpRequest` prototype patch exactly once.
+     *
+     * Overrides `XMLHttpRequest.prototype.open` to capture the request URL on
+     * the XHR instance, and `XMLHttpRequest.prototype.send` to inject the
+     * `Authorization: Bearer` header (via `setRequestHeader`) before dispatching
+     * the request. Supports Angular's default XHR-based `HttpClient` backend.
+     *
+     * No-op when already patched or in a non-browser environment.
+     */
+    private static patchXhr;
+    /**
+     * Restore `XMLHttpRequest.prototype.open` and `.send` to their original
+     * values if no interceptors remain active.
+     * No-op when XHR has not been patched or some interceptors are still active.
+     */
+    private static maybeRestoreXhr;
+    /**
+     * Remove all registered instances and restore `window.fetch` and
+     * `XMLHttpRequest` prototype methods to their original values.
+     * Intended for use in test teardown only.
+     * @internal
+     */
+    static _reset(): void;
+}
+
+export { APP_CONFIG, AUTH0_CONFIG, AuthService, BearerTokenInterceptor, EventBus, LogSeverity, Logger, STANDARD_JWT_CLAIMS, STORAGE_CONFIG, STORAGE_KEYS, buildUserData, configureAuth0, createAuthService, decodeAndStoreToken, extractClaimValue, getCustomClaims, getDecodedToken, getStorageItem, isNamespacedClaim, removeStorageItem, resetAuth0Config, setStorageItem };
+export type { AppState, Auth0Config, Auth0ConfigOptions, AuthServiceOptions, AuthorizationParams, BearerTokenInterceptorConfig, CallbackResult, EventBusOptions, EventPayload, LogAttributes, LogRecord, LoggerOptions, StorageConfig, StorageKeys, TokenPayload, UserData, UserInfo };