@opensourcekd/ng-common-libs 1.2.2 → 1.2.4

package/dist/angular/index.d.ts

@@ -1,6 +1,7 @@
-import { Observable } from 'rxjs';
+import { Observable, ReplaySubject } from 'rxjs';
+import { HttpClient, HttpInterceptorFn, HttpErrorResponse } from '@angular/common/http';
+import { EventType } from 'mitt';
 import { CanActivateFn } from '@angular/router';
-import { HttpInterceptorFn, HttpErrorResponse } from '@angular/common/http';
 
 /**
  * Event payload interface
@@ -494,6 +495,273 @@ declare class PermissionService {
     getUserEmail(): string | null;
 }
 
+/**
+ * EventBusService - Angular service for cross-application event communication
+ * Uses mitt library for efficient event handling and RxJS ReplaySubject for observable stream
+ *
+ * This service is designed for MicroFrontend architectures where different apps need to communicate
+ * The ReplaySubject keeps last 100 events in memory for late subscribers
+ *
+ * @example
+ * ```typescript
+ * import { Component, inject, OnInit } from '@angular/core';
+ * import { EventBusService } from '@opensourcekd/ng-common-libs';
+ *
+ * @Component({
+ *   selector: 'app-example',
+ *   template: '...'
+ * })
+ * export class ExampleComponent implements OnInit {
+ *   private eventBus = inject(EventBusService);
+ *
+ *   ngOnInit() {
+ *     // Subscribe to all events
+ *     this.eventBus.onePlusNEvents.subscribe(event => {
+ *       console.log('Event received:', event);
+ *     });
+ *   }
+ *
+ *   sendCustomEvent() {
+ *     // Send a custom event
+ *     this.eventBus.sendEvent('user:action');
+ *
+ *     // Or send structured event with data
+ *     this.eventBus.sendEvent(JSON.stringify({
+ *       type: 'user:login',
+ *       payload: { userId: '123' },
+ *       timestamp: new Date().toISOString()
+ *     }));
+ *   }
+ * }
+ * ```
+ */
+declare class EventBusService {
+    /**
+     * ReplaySubject that buffers the last 100 events for late subscribers
+     * Subscribe to this observable to receive all events
+     */
+    onePlusNEvents: ReplaySubject<EventType>;
+    /**
+     * mitt event emitter instance
+     * Lightweight event emitter library
+     */
+    private emitter;
+    constructor();
+    /**
+     * Send an event through the event bus
+     * The event will be forwarded to all subscribers via the ReplaySubject
+     *
+     * @param s - Event string, can be a simple event name or JSON stringified structured data
+     *
+     * @example
+     * ```typescript
+     * // Simple event
+     * eventBus.sendEvent('user:logout');
+     *
+     * // Structured event
+     * eventBus.sendEvent(JSON.stringify({
+     *   type: 'auth:token_updated',
+     *   payload: { token: 'abc123' },
+     *   timestamp: new Date().toISOString()
+     * }));
+     * ```
+     */
+    sendEvent(s: string): void;
+}
+
+/**
+ * User information from ID token
+ * Standard OIDC claims compatible with Auth0
+ */
+interface UserInfo {
+    sub: string;
+    name?: string;
+    email?: string;
+    email_verified?: boolean;
+    preferred_username?: string;
+    given_name?: string;
+    family_name?: string;
+    nickname?: string;
+    locale?: string;
+    picture?: string;
+    phone?: string;
+    phone_verified?: boolean;
+    updated_at?: string;
+    role?: string;
+    org?: string;
+    organization?: string;
+    [key: string]: any;
+}
+/**
+ * Simplified user data extracted from token
+ */
+interface UserData {
+    id: string;
+    name: string;
+    email: string;
+    role: string;
+    org: string;
+}
+/**
+ * Authentication service for Auth0 integration
+ * Handles login, logout, token management, and user session
+ * Uses sessionStorage for sensitive data and emits authentication events for MicroApps
+ *
+ * Configuration is centralized in config/auth.config.ts for easy management
+ *
+ * NOTE: All navigation logic using setTimeout is commented out as per requirements.
+ * To enable navigation after auth operations, uncomment the marked sections in consuming components.
+ */
+declare class AuthService {
+    private http;
+    private eventBus;
+    id: string;
+    private readonly STANDARD_JWT_CLAIMS;
+    private auth0Client;
+    private initializationPromise;
+    private userSubject;
+    user$: Observable<UserInfo | null>;
+    constructor(http: HttpClient, eventBus: EventBusService);
+    /**
+     * Initialize Auth0 client
+     */
+    private initializeAuth0;
+    /**
+     * Ensure Auth0 client is initialized before use
+     */
+    private ensureInitialized;
+    /**
+     * Login with Auth0
+     * Redirects to Auth0 Universal Login
+     * Preserves current URL parameters (like invitation tokens) through the auth flow
+     *
+     * @param user - Optional user identifier for logging
+     * @param options - Optional login options including invitation and organization parameters
+     */
+    login(user?: string, options?: {
+        invitation?: string;
+        organization?: string;
+    }): Promise<void>;
+    /**
+     * Handle OAuth2 callback after successful authorization
+     * Processes the callback and retrieves user info
+     *
+     * NOTE: Navigation after successful/failed authentication should be handled in the calling component
+     * using setTimeout. See commented examples in app.component.ts
+     *
+     * @returns Promise<{ success: boolean, appState?: any }> - Success status and preserved appState
+     */
+    handleCallback(): Promise<{
+        success: boolean;
+        appState?: any;
+    }>;
+    /**
+     * Log all user claims for debugging
+     * @param user - User info from Auth0
+     */
+    private logUserClaims;
+    /**
+     * Log standard OIDC claims
+     * @param user - User info from Auth0
+     */
+    private logStandardClaims;
+    /**
+     * Log claims with consistent formatting
+     * @param header - Section header to display
+     * @param claims - Array of claim keys to log
+     * @param user - User info object
+     */
+    private logClaims;
+    /**
+     * Get custom namespaced claims from user info
+     * @param user - User info object
+     * @returns Array of custom claim keys
+     */
+    private getCustomClaims;
+    /**
+     * Get additional non-namespaced claims from user info
+     * @param user - User info object
+     * @returns Array of additional claim keys
+     */
+    private getAdditionalClaims;
+    /**
+     * Check if a claim key is namespaced
+     * @param key - Claim key to check
+     * @returns True if the key starts with http:// or https://
+     */
+    private isNamespacedClaim;
+    /**
+     * Logout user and clear authentication state
+     * Redirects to Auth0 logout endpoint and clears local state
+     */
+    logout(): Promise<void>;
+    /**
+     * Get current access token from storage or Auth0 client
+     * @returns string | null - Access token or null if not authenticated
+     */
+    getToken(): Promise<string | null>;
+    /**
+     * Get current access token synchronously from storage only
+     * Use this for synchronous operations like interceptors
+     * @returns string | null - Access token or null if not authenticated
+     */
+    getTokenSync(): string | null;
+    /**
+     * Set access token in storage and emit event for MicroApps
+     * @param token - Access token to store
+     */
+    private setToken;
+    /**
+     * Check if user is authenticated
+     * @returns boolean - True if user has valid token
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Check if user is authenticated synchronously
+     * Only checks storage, doesn't verify with Auth0
+     * @returns boolean - True if user has token in storage
+     */
+    isAuthenticatedSync(): boolean;
+    /**
+     * Get current user information
+     * @returns UserInfo | null - Current user or null if not authenticated
+     */
+    getUser(): UserInfo | null;
+    /**
+     * Get simplified user data from token
+     * Extracts user details, role, and organization from ID token claims
+     * Checks both top-level claims and namespaced custom claims
+     * @returns UserData | null - Simplified user data or null if not authenticated
+     */
+    getUserData(): UserData | null;
+    /**
+     * Extract claim value from user info, checking both direct properties and namespaced custom claims
+     * @param userInfo - User info object
+     * @param claimNames - Single claim name or array of claim names to search for
+     * @param defaultValue - Default value if claim is not found
+     * @returns Extracted claim value or default value
+     */
+    private extractClaimValue;
+    /**
+     * Get user information from storage
+     * @returns UserInfo | null - Stored user info or null
+     */
+    private getUserInfoFromStorage;
+    /**
+     * Set user information in storage, update observable and emit event for MicroApps
+     * Logs all Auth0 claims for debugging
+     * @param userInfo - User information to store
+     */
+    private setUserInfo;
+    /**
+     * Emit authentication event for MicroApps to consume
+     * Events are emitted via EventBus for cross-MFE communication
+     * @param eventType - Type of authentication event
+     * @param payload - Event payload
+     */
+    private emitAuthEvent;
+}
+
 /**
  * Auth guard configuration
  */
@@ -687,5 +955,81 @@ declare function clearCacheEntry(url: string): void;
  */
 declare const cachingInterceptor: HttpInterceptorFn;
 
-export { HttpError, LogLevel, LoggerService, NgEventEmitter, PermissionService, StorageService, TokenService, authGuard, authInterceptor, cachingInterceptor, clearCache, clearCacheEntry, configureAuthInterceptor, configureCaching, configureErrorHandling, createAuthGuard, createPermissionGuard, createRoleGuard, errorHandlingInterceptor, isClientError, isNetworkError, isServerError, parseHttpError };
-export type { AuthGuardConfig, AuthInterceptorConfig, CacheConfig, ErrorHandlingConfig, LoggerConfig, TokenConfig };
+/**
+ * Auth0 Configuration
+ * Centralized configuration for Auth0 integration
+ *
+ * Environment variables are typically set in consuming applications
+ * Default values are provided for development/testing
+ */
+/**
+ * Auth0 client configuration
+ * Override these values in your consuming application by setting them before importing AuthService
+ */
+declare const AUTH0_CONFIG: {
+    domain: string;
+    clientId: string;
+    redirectUri: string;
+    logoutUri: string;
+    audience: string;
+    scope: string;
+    connection: string | undefined;
+};
+/**
+ * Storage configuration
+ * Controls where sensitive data is stored
+ */
+declare const STORAGE_CONFIG: {
+    TOKEN_STORAGE: "localStorage" | "sessionStorage";
+    USER_INFO_STORAGE: "localStorage" | "sessionStorage";
+};
+/**
+ * Storage keys for auth data
+ */
+declare const STORAGE_KEYS: {
+    ACCESS_TOKEN: string;
+    USER_INFO: string;
+};
+/**
+ * Helper functions for storage operations
+ * These work with both localStorage and sessionStorage
+ */
+/**
+ * Get item from storage
+ * @param key - Storage key
+ * @param storageType - Type of storage to use
+ * @returns Stored value or null
+ */
+declare function getStorageItem(key: string, storageType?: 'localStorage' | 'sessionStorage'): string | null;
+/**
+ * Set item in storage
+ * @param key - Storage key
+ * @param value - Value to store
+ * @param storageType - Type of storage to use
+ */
+declare function setStorageItem(key: string, value: string, storageType?: 'localStorage' | 'sessionStorage'): void;
+/**
+ * Remove item from storage
+ * @param key - Storage key
+ * @param storageType - Type of storage to use
+ */
+declare function removeStorageItem(key: string, storageType?: 'localStorage' | 'sessionStorage'): void;
+/**
+ * Configure Auth0 settings
+ * Call this function in your consuming application before using AuthService
+ *
+ * @example
+ * ```typescript
+ * import { configureAuth0 } from '@opensourcekd/ng-common-libs';
+ *
+ * configureAuth0({
+ *   domain: 'your-domain.auth0.com',
+ *   clientId: 'your-client-id',
+ *   audience: 'https://your-api.com'
+ * });
+ * ```
+ */
+declare function configureAuth0(config: Partial<typeof AUTH0_CONFIG>): void;
+
+export { AUTH0_CONFIG, AuthService, EventBusService, HttpError, LogLevel, LoggerService, NgEventEmitter, PermissionService, STORAGE_CONFIG, STORAGE_KEYS, StorageService, TokenService, authGuard, authInterceptor, cachingInterceptor, clearCache, clearCacheEntry, configureAuth0, configureAuthInterceptor, configureCaching, configureErrorHandling, createAuthGuard, createPermissionGuard, createRoleGuard, errorHandlingInterceptor, getStorageItem, isClientError, isNetworkError, isServerError, parseHttpError, removeStorageItem, setStorageItem };
+export type { AuthGuardConfig, AuthInterceptorConfig, CacheConfig, ErrorHandlingConfig, LoggerConfig, TokenConfig, UserData, UserInfo };