@opensourcekd/ng-common-libs 2.0.10 → 2.1.0

package/README.md

@@ -24,6 +24,8 @@ import {
 - **AuthService**: Complete Auth0 authentication with token management (Pure TypeScript - no Angular dependency)
 - **EventBus**: Framework-agnostic event bus using RxJS
 - **Logger**: OpenTelemetry-compliant structured logging with observable log streams
+- **BearerTokenInterceptor**: Singleton fetch interceptor that attaches bearer tokens to API requests
+- **CSS Tokens**: Shared design tokens (colors, typography, spacing, shadows, and more) as CSS custom properties
 - **Works with any framework**: Angular, React, Vue, Svelte, vanilla JS
 - **Module Federation Support**: Singleton pattern works across shell + MFEs
 - **Zero Framework Lock-in**: Core services are pure TypeScript classes
@@ -92,6 +94,53 @@ All documentation is in the `/docs` folder:
 - **[MICROAPP_SETUP_REQUIRED.md](./docs/MICROAPP_SETUP_REQUIRED.md)** - Microapp setup
 - **[COPILOT_EFFICIENCY.md](./docs/COPILOT_EFFICIENCY.md)** - ⚡ How to use GitHub Copilot efficiently
 
+## 🎨 CSS Design Tokens
+
+Shared CSS custom properties for consistent styling across all micro-frontends.
+
+### Usage
+
+In your global stylesheet (`styles.css` / `styles.scss`):
+
+```css
+@import '@opensourcekd/ng-common-libs/styles/tokens.css';
+```
+
+### Available Token Categories
+
+| Category | Example Tokens |
+|---|---|
+| **Colors** | `--color-primary-500`, `--color-success-600`, `--color-error-500` |
+| **Semantic Colors** | `--color-brand`, `--color-text-primary`, `--color-bg-surface` |
+| **Typography** | `--font-size-md`, `--font-weight-bold`, `--line-height-normal` |
+| **Spacing** | `--space-4` (16px), `--space-8` (32px), `--space-16` (64px) |
+| **Border Radius** | `--radius-sm`, `--radius-lg`, `--radius-full` |
+| **Shadows** | `--shadow-sm`, `--shadow-md`, `--shadow-xl`, `--shadow-focus` |
+| **Z-index** | `--z-index-modal`, `--z-index-toast`, `--z-index-tooltip` |
+| **Transitions** | `--transition-fast`, `--transition-normal`, `--duration-fast` |
+| **Opacity** | `--opacity-50`, `--opacity-75`, `--opacity-100` |
+| **Breakpoints** | `--breakpoint-sm` (640px), `--breakpoint-lg` (1024px) |
+
+### Example
+
+```css
+.my-button {
+  background-color: var(--color-brand);
+  color: var(--color-text-on-brand);
+  padding: var(--space-2) var(--space-4);
+  border-radius: var(--radius-md);
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-semibold);
+  box-shadow: var(--shadow-sm);
+  transition: var(--transition-normal);
+}
+
+.my-button:hover {
+  background-color: var(--color-brand-hover);
+  box-shadow: var(--shadow-md);
+}
+```
+
 ## 📝 What's Exported
 
 Everything you need from one import:
@@ -102,6 +151,7 @@ import {
   AuthService,
   EventBus,
   Logger,
+  BearerTokenInterceptor,
   
   // Helper Functions
   configureAuth0,
@@ -134,6 +184,7 @@ import {
   LogAttributes,
   LogSeverity,
   LoggerOptions,
+  BearerTokenInterceptorConfig,
 } from '@opensourcekd/ng-common-libs';
 ```
 

package/dist/index.cjs

@@ -448,6 +448,7 @@ function e(e,t){var n={};for(var o in e)Object.prototype.hasOwnProperty.call(e,o
 class AuthService {
     auth0Client = null;
     initializationPromise = null;
+    /** Remains false if callback processing fails, allowing the callback to be retried. */
     callbackHandled = false;
     callbackPromise = null;
     userSubject;
@@ -482,6 +483,14 @@ class AuthService {
         const existingUserInfo = this.getUserInfoFromStorage();
         this.userSubject = new rxjs.BehaviorSubject(existingUserInfo);
         this.user$ = this.userSubject.asObservable();
+        // Eagerly begin Auth0 client initialization so logs are visible immediately.
+        // The .catch() only suppresses an unhandled-rejection warning; the rejected
+        // promise is stored in initializationPromise and re-throws when awaited by
+        // ensureInitialized() or ensureAuth0Client(), surfacing the error to callers.
+        this.initializationPromise = this.initializeAuth0();
+        this.initializationPromise.catch(error => {
+            console.error('[AuthService] Failed to initialize Auth0 client:', error);
+        });
     }
     /**
      * Get the identifier of this AuthService instance
@@ -521,6 +530,25 @@ class AuthService {
         console.log('[AuthService] Auth0 client initialized successfully');
         this.emitAuthEvent('init', null);
     }
+    /**
+     * 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
+     */
+    async ensureAuth0Client() {
+        if (this.auth0Client)
+            return;
+        if (this.initializationPromise) {
+            await this.initializationPromise;
+            return;
+        }
+        this.initializationPromise = this.initializeAuth0();
+        await this.initializationPromise;
+        if (!this.auth0Client) {
+            throw new Error('[AuthService] Auth0 client failed to initialize');
+        }
+    }
     /**
      * Ensure the Auth0 client is initialized before use
      * Lazy-initializes on the first call and auto-handles OAuth callbacks when detected
@@ -549,6 +577,10 @@ 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.
      */
     async checkAndHandleCallback() {
         if (this.callbackHandled || typeof window === 'undefined')
@@ -558,15 +590,22 @@ class AuthService {
             return;
         }
         const urlParams = new URLSearchParams(window.location.search);
-        if (urlParams.has('code') && urlParams.has('state')) {
-            console.log('[AuthService] Auth0 callback detected in URL, processing...');
-            this.emitAuthEvent('callback_detected', null);
-            this.callbackPromise = this.handleCallback()
-                .then(() => { this.callbackHandled = true; })
-                .catch(error => { throw error; })
-                .finally(() => { this.callbackPromise = null; });
+        if (!urlParams.has('code') || !urlParams.has('state'))
+            return;
+        console.log('[AuthService] Auth0 callback detected in URL, processing...');
+        this.emitAuthEvent('callback_detected', null);
+        // Store the promise before the first await so concurrent callers see it
+        // and deduplicate by awaiting the same in-flight promise.
+        this.callbackPromise = (async () => {
+            await this.handleCallback();
+            this.callbackHandled = true;
+        })();
+        try {
             await this.callbackPromise;
         }
+        finally {
+            this.callbackPromise = null;
+        }
     }
     /**
      * Redirect the user to Auth0 Universal Login
@@ -603,11 +642,15 @@ 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`
      */
     async handleCallback() {
         try {
-            await this.ensureInitialized();
+            await this.ensureAuth0Client();
             console.log('[AuthService] Processing Auth0 redirect callback...');
             const result = await this.auth0Client.handleRedirectCallback();
             const user = await this.auth0Client.getUser();
@@ -631,6 +674,11 @@ class AuthService {
     }
     /**
      * 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.
      */
     async logout() {
         console.log('[AuthService] User logging out...');
@@ -640,7 +688,7 @@ class AuthService {
         this.userSubject.next(null);
         this.emitAuthEvent('logout', null);
         try {
-            await this.ensureInitialized();
+            await this.ensureAuth0Client();
             await this.auth0Client.logout({
                 logoutParams: { returnTo: this.config.logoutUri }
             });
@@ -1025,9 +1073,321 @@ class Logger {
     }
 }
 
+/**
+ * BearerTokenInterceptor — HTTP interceptor for bearer token injection.
+ * Patches both `window.fetch` and `XMLHttpRequest` (for Angular's default
+ * HttpClient backend), pure TypeScript, framework-agnostic, truly singleton
+ * per identifier.
+ */
+/**
+ * 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
+ * ```
+ */
+class BearerTokenInterceptor {
+    static instances = new Map();
+    static originalFetch = null;
+    static originalXhrOpen = null;
+    static originalXhrSend = null;
+    id;
+    apiUrl;
+    tokenFn;
+    active = false;
+    constructor(id, config) {
+        this.id = id;
+        this.apiUrl = config.apiUrl ?? APP_CONFIG.apiUrl;
+        this.tokenFn = config.getToken;
+    }
+    /**
+     * 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, config) {
+        if (BearerTokenInterceptor.instances.has(id)) {
+            return BearerTokenInterceptor.instances.get(id);
+        }
+        const instance = new BearerTokenInterceptor(id, config);
+        BearerTokenInterceptor.instances.set(id, instance);
+        return instance;
+    }
+    /**
+     * Get the identifier of this interceptor instance.
+     * @returns The `id` string supplied when the instance was created
+     */
+    getId() {
+        return this.id;
+    }
+    /**
+     * Get the API base URL that this interceptor matches against.
+     * @returns The configured API URL string
+     */
+    getApiUrl() {
+        return this.apiUrl;
+    }
+    /**
+     * Check whether this interceptor is currently active.
+     * @returns `true` if the interceptor has been activated and not yet deactivated
+     */
+    isActive() {
+        return this.active;
+    }
+    /**
+     * 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() {
+        if (this.active || typeof window === 'undefined')
+            return;
+        this.active = true;
+        BearerTokenInterceptor.patchFetch();
+        BearerTokenInterceptor.patchXhr();
+    }
+    /**
+     * 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() {
+        if (!this.active)
+            return;
+        this.active = false;
+        if (typeof window !== 'undefined') {
+            BearerTokenInterceptor.maybeRestoreFetch();
+            BearerTokenInterceptor.maybeRestoreXhr();
+        }
+    }
+    /**
+     * 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`
+     */
+    getEffectiveToken(url) {
+        if (!this.active || !url.startsWith(this.apiUrl))
+            return null;
+        return this.tokenFn();
+    }
+    /**
+     * 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
+     */
+    static extractHeaders(init) {
+        if (!init?.headers)
+            return {};
+        if (init.headers instanceof Headers) {
+            const h = {};
+            init.headers.forEach((v, k) => { h[k] = v; });
+            return h;
+        }
+        if (Array.isArray(init.headers)) {
+            return Object.fromEntries(init.headers);
+        }
+        return { ...init.headers };
+    }
+    /**
+     * 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`
+     */
+    static findToken(url) {
+        return ([...BearerTokenInterceptor.instances.values()]
+            .map((i) => i.getEffectiveToken(url))
+            .find((t) => t !== null) ?? null);
+    }
+    /**
+     * 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
+     */
+    static applyBearerToken(url, init) {
+        const headers = BearerTokenInterceptor.extractHeaders(init);
+        const token = BearerTokenInterceptor.findToken(url);
+        if (token) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
+        return { ...init, headers };
+    }
+    /**
+     * 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.
+     */
+    static patchFetch() {
+        if (BearerTokenInterceptor.originalFetch !== null || typeof window === 'undefined')
+            return;
+        // Store without bind so the original reference is preserved for identity checks on restore.
+        BearerTokenInterceptor.originalFetch = window.fetch;
+        window.fetch = (input, init) => {
+            // Extract the URL string from all three possible input types:
+            //   • Request-like objects (e.g. the Fetch API Request) have a `.url` string property.
+            //   • URL objects do NOT have `.url`; String(urlObj) yields the full href (e.g. "https://…").
+            //   • Plain strings pass through String() unchanged.
+            const hasUrl = typeof input.url === 'string';
+            const url = hasUrl ? input.url : String(input);
+            return BearerTokenInterceptor.originalFetch(input, BearerTokenInterceptor.applyBearerToken(url, init));
+        };
+    }
+    /**
+     * 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.
+     */
+    static maybeRestoreFetch() {
+        if (BearerTokenInterceptor.originalFetch === null)
+            return;
+        const anyActive = [...BearerTokenInterceptor.instances.values()].some((i) => i.active);
+        if (anyActive)
+            return;
+        window.fetch = BearerTokenInterceptor.originalFetch;
+        BearerTokenInterceptor.originalFetch = null;
+    }
+    /**
+     * 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.
+     */
+    static patchXhr() {
+        if (BearerTokenInterceptor.originalXhrOpen !== null ||
+            typeof window === 'undefined' ||
+            typeof XMLHttpRequest === 'undefined')
+            return;
+        const originalOpen = XMLHttpRequest.prototype.open;
+        const originalSend = XMLHttpRequest.prototype.send;
+        BearerTokenInterceptor.originalXhrOpen = originalOpen;
+        BearerTokenInterceptor.originalXhrSend = originalSend;
+        // Capture the request URL so send() can match it against registered interceptors.
+        // The `async` parameter is made optional to faithfully match both XHR `open()` overloads.
+        XMLHttpRequest.prototype.open = function (method, url, async, username, password) {
+            const urlStr = url instanceof URL ? url.href : url;
+            try {
+                this._interceptorUrl = new URL(urlStr, window.location.href).href;
+            }
+            catch {
+                this._interceptorUrl = urlStr;
+            }
+            // `async` defaults to true per the XHR spec when not supplied by the caller.
+            originalOpen.call(this, method, url, async ?? true, username, password);
+        };
+        // Inject the Authorization header before dispatching the request.
+        XMLHttpRequest.prototype.send = function (body) {
+            const url = this._interceptorUrl;
+            if (url) {
+                const token = BearerTokenInterceptor.findToken(url);
+                if (token) {
+                    this.setRequestHeader('Authorization', `Bearer ${token}`);
+                }
+            }
+            originalSend.call(this, body);
+        };
+    }
+    /**
+     * 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.
+     */
+    static maybeRestoreXhr() {
+        if (BearerTokenInterceptor.originalXhrOpen === null)
+            return;
+        const anyActive = [...BearerTokenInterceptor.instances.values()].some((i) => i.active);
+        if (anyActive)
+            return;
+        XMLHttpRequest.prototype.open = BearerTokenInterceptor.originalXhrOpen;
+        XMLHttpRequest.prototype.send = BearerTokenInterceptor.originalXhrSend;
+        BearerTokenInterceptor.originalXhrOpen = null;
+        BearerTokenInterceptor.originalXhrSend = null;
+    }
+    /**
+     * 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() {
+        if (typeof window !== 'undefined') {
+            if (BearerTokenInterceptor.originalFetch !== null) {
+                window.fetch = BearerTokenInterceptor.originalFetch;
+            }
+            if (BearerTokenInterceptor.originalXhrOpen !== null && typeof XMLHttpRequest !== 'undefined') {
+                XMLHttpRequest.prototype.open = BearerTokenInterceptor.originalXhrOpen;
+                XMLHttpRequest.prototype.send = BearerTokenInterceptor.originalXhrSend;
+            }
+        }
+        BearerTokenInterceptor.originalFetch = null;
+        BearerTokenInterceptor.originalXhrOpen = null;
+        BearerTokenInterceptor.originalXhrSend = null;
+        BearerTokenInterceptor.instances.clear();
+    }
+}
+
 exports.APP_CONFIG = APP_CONFIG;
 exports.AUTH0_CONFIG = AUTH0_CONFIG;
 exports.AuthService = AuthService;
+exports.BearerTokenInterceptor = BearerTokenInterceptor;
 exports.EventBus = EventBus;
 exports.Logger = Logger;
 exports.STANDARD_JWT_CLAIMS = STANDARD_JWT_CLAIMS;