@opensourcekd/ng-common-libs 2.0.11 → 2.2.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

@@ -1073,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;