@opensourcekd/ng-common-libs 1.2.3 → 1.2.5

package/README.md

@@ -1,22 +1,18 @@
 # ng-common-libs
 
-Angular 18 shareable utility library with framework-agnostic core and Angular wrappers for event handling, authorization, storage management, logging, and HTTP operations.
+Angular 18 library with Auth0 authentication service and MicroFrontend event bus.
 
 ## 🎯 Dual-Layer Architecture
 
 This library features a **dual-layer architecture**:
 
-- **Core Layer** (`@opensourcekd/ng-common-libs/core`): Framework-agnostic utilities using only RxJS and browser APIs. Use these in React, Vue, Svelte, or vanilla JavaScript projects.
-- **Angular Layer** (`@opensourcekd/ng-common-libs` or `/angular`): Angular-specific wrappers with dependency injection, plus guards and interceptors that require Angular.
+- **Core Layer** (`@opensourcekd/ng-common-libs/core`): Framework-agnostic event bus using only RxJS. Use in React, Vue, Svelte, or vanilla JavaScript projects.
+- **Angular Layer** (`@opensourcekd/ng-common-libs` or `/angular`): Angular-specific services with dependency injection.
 
 ## 🚀 Features
 
-- **Event Bus**: Centralized event communication (framework-agnostic)
-- **Token Manager**: JWT token management and validation (framework-agnostic)
-- **Storage Manager**: Type-safe localStorage/sessionStorage wrapper (framework-agnostic)
-- **Logger**: Configurable logging with multiple levels (framework-agnostic)
-- **Authorization**: Angular guards, interceptors, and permission handling
-- **HTTP Utilities**: Error handling, caching, and retry logic for Angular HTTP requests
+- **EventBusService**: MicroFrontend-ready event bus with replay buffer for cross-app communication
+- **Auth0 Integration**: Complete Auth0 authentication service with token management
 
 ## 📦 Installation
 
@@ -24,263 +20,93 @@ This library features a **dual-layer architecture**:
 npm install @opensourcekd/ng-common-libs
 ```
 
+> **Note:** `mitt` and `@auth0/auth0-spa-js` are bundled with the library. You don't need to install them separately.
+> 
+> **Module Federation**: Just configure `@opensourcekd/ng-common-libs` as shared in your webpack config. The bundled dependencies (`mitt`, `@auth0/auth0-spa-js`) will be included automatically, ensuring they're loaded only once across all micro-frontends.
+
 ## 🔧 Usage
 
-### For Angular Projects
+### Auth0 Authentication
 
-Use the Angular-specific imports that provide dependency injection:
+Complete Auth0 integration with automatic token management and event emission:
 
 ```typescript
-import { Component, OnInit, inject } from '@angular/core';
-import { NgEventEmitter } from '@opensourcekd/ng-common-libs';
+import { Component, inject } from '@angular/core';
+import { AuthService, configureAuth0 } from '@opensourcekd/ng-common-libs';
+
+// Configure Auth0 in your app.config.ts
+configureAuth0({
+  domain: 'your-domain.auth0.com',
+  clientId: 'your-client-id',
+  audience: 'https://your-api.com',
+});
 
 @Component({
-  selector: 'app-example',
-  template: `...`
+  selector: 'app-login',
+  template: `
+    <button (click)="login()">Login with Auth0</button>
+    <button (click)="logout()" *ngIf="user">Logout</button>
+    <div *ngIf="user">Welcome, {{ user.name }}!</div>
+  `
 })
-export class ExampleComponent implements OnInit {
-  private eventEmitter = inject(NgEventEmitter);
+export class LoginComponent {
+  private authService = inject(AuthService);
+  user = this.authService.getUser();
 
-  ngOnInit() {
-    // Subscribe to events
-    this.eventEmitter.on('user:login').subscribe(data => {
-      console.log('User logged in:', data);
-    });
+  async login() {
+    await this.authService.login();
   }
 
-  login() {
-    // Emit events
-    this.eventEmitter.emit('user:login', { 
-      userId: '123', 
-      username: 'john' 
-    });
+  async logout() {
+    await this.authService.logout();
   }
 }
 ```
 
-### Authorization
+See the [Auth0 Service Usage Guide](./docs/AUTH_SERVICE_USAGE.md) for complete integration instructions.
 
-#### Token Service
+### EventBusService
 
-Manage authentication tokens with ease:
+Cross-application event communication for MicroFrontend architectures:
 
 ```typescript
-import { inject } from '@angular/core';
-import { TokenService } from '@opensourcekd/ng-common-libs';
-
-export class AuthService {
-  private tokenService = inject(TokenService);
-
-  login(token: string) {
-    this.tokenService.setToken(token);
-  }
-
-  logout() {
-    this.tokenService.clearTokens();
-  }
-
-  isAuthenticated(): boolean {
-    return this.tokenService.isAuthenticated();
-  }
-
-  getUserData() {
-    return this.tokenService.getUserFromToken();
-  }
-}
-```
-
-#### Auth Guard
-
-Protect routes with authentication guards:
-
-```typescript
-import { Routes } from '@angular/router';
-import { authGuard, createRoleGuard } from '@opensourcekd/ng-common-libs';
-
-export const routes: Routes = [
-  {
-    path: 'dashboard',
-    component: DashboardComponent,
-    canActivate: [authGuard]
-  },
-  {
-    path: 'admin',
-    component: AdminComponent,
-    canActivate: [createRoleGuard(['admin'], { redirectUrl: '/unauthorized' })]
-  }
-];
-```
-
-#### Auth Interceptor
-
-Automatically add authentication tokens to HTTP requests:
-
-```typescript
-import { ApplicationConfig } from '@angular/core';
-import { provideHttpClient, withInterceptors } from '@angular/common/http';
-import { authInterceptor, configureAuthInterceptor } from '@opensourcekd/ng-common-libs';
-
-// Configure the interceptor (optional)
-configureAuthInterceptor({
-  headerName: 'Authorization',
-  tokenPrefix: 'Bearer',
-  excludedUrls: ['/auth/login', '/auth/register']
-});
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideHttpClient(
-      withInterceptors([authInterceptor])
-    )
-  ]
-};
-```
-
-#### Permission Service
-
-Check user permissions and roles:
-
-```typescript
-import { inject } from '@angular/core';
-import { PermissionService } from '@opensourcekd/ng-common-libs';
-
-export class MyComponent {
-  private permissionService = inject(PermissionService);
-
-  canEditPost(): boolean {
-    return this.permissionService.hasPermission('posts:edit');
-  }
-
-  isAdmin(): boolean {
-    return this.permissionService.hasRole('admin');
-  }
-}
-```
-
-### Storage Service
-
-Type-safe storage operations with JSON serialization:
-
-```typescript
-import { inject } from '@angular/core';
-import { StorageService } from '@opensourcekd/ng-common-libs';
-
-export class UserPreferencesService {
-  private storage = inject(StorageService);
-
-  savePreferences(prefs: UserPreferences) {
-    this.storage.setLocal('user-prefs', prefs);
-  }
-
-  getPreferences(): UserPreferences | null {
-    return this.storage.getLocal<UserPreferences>('user-prefs');
-  }
-
-  // With expiration (1 hour)
-  saveTempData(data: any) {
-    this.storage.setWithExpiration('temp-data', data, 3600000);
-  }
-
-  getTempData() {
-    return this.storage.getWithExpiration('temp-data');
-  }
-}
-```
-
-### Logger Service
+import { Component, OnInit, inject } from '@angular/core';
+import { EventBusService } from '@opensourcekd/ng-common-libs';
 
-Centralized logging with configurable levels:
+@Component({
+  selector: 'app-event-example',
+  template: `<button (click)="sendEvent()">Send Event</button>`
+})
+export class EventExampleComponent implements OnInit {
+  private eventBus = inject(EventBusService);
 
-```typescript
-import { inject } from '@angular/core';
-import { LoggerService, LogLevel } from '@opensourcekd/ng-common-libs';
-
-export class MyService {
-  private logger = inject(LoggerService);
-
-  constructor() {
-    // Configure logger
-    this.logger.configure({
-      level: LogLevel.DEBUG,
-      enableTimestamp: true,
-      prefix: 'MyApp'
+  ngOnInit() {
+    // Subscribe to all events
+    this.eventBus.onePlusNEvents.subscribe(event => {
+      console.log('Event received:', event);
     });
   }
 
-  doSomething() {
-    this.logger.debug('Debug message');
-    this.logger.info('Info message');
-    this.logger.warn('Warning message');
-    this.logger.error('Error message', new Error('Something went wrong'));
-
-    // Measure execution time
-    this.logger.time('fetchData', async () => {
-      return await this.fetchData();
-    });
+  sendEvent() {
+    // Send structured event
+    this.eventBus.sendEvent(JSON.stringify({
+      type: 'user:action',
+      payload: { userId: '123' },
+      timestamp: new Date().toISOString()
+    }));
   }
 }
 ```
 
-### HTTP Utilities
-
-#### Error Handling Interceptor
-
-Handle HTTP errors with automatic retry:
-
-```typescript
-import { ApplicationConfig } from '@angular/core';
-import { provideHttpClient, withInterceptors } from '@angular/common/http';
-import { errorHandlingInterceptor, configureErrorHandling } from '@opensourcekd/ng-common-libs';
-
-// Configure error handling
-configureErrorHandling({
-  enableLogging: true,
-  retryAttempts: 3,
-  retryDelay: 1000,
-  retryStatusCodes: [500, 502, 503, 504]
-});
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideHttpClient(
-      withInterceptors([errorHandlingInterceptor])
-    )
-  ]
-};
-```
-
-#### Caching Interceptor
-
-Cache HTTP responses:
-
-```typescript
-import { ApplicationConfig } from '@angular/core';
-import { provideHttpClient, withInterceptors } from '@angular/common/http';
-import { cachingInterceptor, configureCaching } from '@opensourcekd/ng-common-libs';
-
-// Configure caching
-configureCaching({
-  enabled: true,
-  maxAge: 300000, // 5 minutes
-  cacheableUrls: ['/api/users', '/api/products']
-});
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideHttpClient(
-      withInterceptors([cachingInterceptor])
-    )
-  ]
-};
-```
+See the [EventBus Service Usage Guide](./docs/EVENT_BUS_USAGE.md) for advanced patterns and MicroFrontend examples.
 
 ### For Non-Angular Projects (React, Vue, Svelte, Vanilla JS)
 
-Use the framework-agnostic core utilities:
+Use the framework-agnostic core event bus:
 
 ```typescript
 // Import from /core
-import { EventBus, TokenManager, StorageManager, Logger, LogLevel } from '@opensourcekd/ng-common-libs/core';
+import { EventBus } from '@opensourcekd/ng-common-libs/core';
 
 // Event Bus
 const eventBus = new EventBus();
@@ -288,23 +114,6 @@ eventBus.emit('user:login', { userId: '123' });
 eventBus.on('user:login').subscribe(data => {
   console.log('User logged in:', data);
 });
-
-// Token Manager
-const tokenManager = new TokenManager();
-tokenManager.setToken('your-jwt-token');
-if (tokenManager.isAuthenticated()) {
-  const user = tokenManager.getUserFromToken();
-}
-
-// Storage Manager
-const storage = new StorageManager();
-storage.setLocal('preferences', { theme: 'dark' });
-const prefs = storage.getLocal('preferences');
-
-// Logger
-const logger = new Logger();
-logger.configure({ level: LogLevel.DEBUG, prefix: 'MyApp' });
-logger.info('Application started');
 ```
 
 #### React Example
@@ -364,49 +173,36 @@ export default {
 
 ## 📚 Documentation
 
-- **[Usage Guide](./docs/USAGE.md)** - Complete usage examples for all utilities
-- **[API Reference](./docs/API.md)** - Detailed API documentation
+- **[Auth0 Service Usage](./docs/AUTH_SERVICE_USAGE.md)** - Complete Auth0 authentication integration guide
+- **[EventBus Service Usage](./docs/EVENT_BUS_USAGE.md)** - Cross-application event communication guide
 - **[Deployment Guide](./docs/DEPLOYMENT.md)** - Publishing, versioning, and consumption
 - **[Microapp Triggering Guide](./docs/MICROAPP_TRIGGERING.md)** - Automatic build triggering for consuming microapps
 - **[Module Federation Guide](./docs/MODULE_FEDERATION.md)** - Runtime sharing with Module Federation
-- **[Architecture Decisions](./ARCHITECTURE_DECISIONS.md)** - Detailed architecture and design decisions
 
 ## 📝 API Documentation
 
-### NgEventEmitter
-
-- `emit<T>(eventType: string, data?: T): void` - Emit an event
-- `on<T>(eventType: string): Observable<T>` - Subscribe to an event
-- `onMultiple(eventTypes: string[]): Observable<EventPayload>` - Subscribe to multiple events
-- `onAll(): Observable<EventPayload>` - Subscribe to all events
-
-### TokenService
+### AuthService
 
-- `setToken(token: string): void` - Store authentication token
-- `getToken(): string | null` - Retrieve authentication token
-- `removeToken(): void` - Remove authentication token
-- `clearTokens(): void` - Clear all tokens
-- `isAuthenticated(): boolean` - Check if user is authenticated
-- `isTokenExpired(token?: string): boolean` - Check if token is expired
-- `getUserFromToken(token?: string): any` - Extract user data from token
+- `login(options?: RedirectLoginOptions): Promise<void>` - Initiate Auth0 login
+- `logout(options?: LogoutOptions): Promise<void>` - Logout and clear session
+- `handleCallback(): Promise<{ success: boolean, appState?: any }>` - Handle Auth0 callback
+- `getToken(): Promise<string | null>` - Get access token asynchronously
+- `getTokenSync(): string | null` - Get cached access token synchronously
+- `getUser(): Signal<UserInfo | null>` - Get user information as signal
+- `isAuthenticated(): Signal<boolean>` - Check authentication status
+- `isLoading(): Signal<boolean>` - Check if authentication is loading
 
-### StorageService
+### EventBusService
 
-- `setLocal<T>(key: string, value: T): boolean` - Set item in localStorage
-- `getLocal<T>(key: string, defaultValue?: T): T | null` - Get item from localStorage
-- `removeLocal(key: string): void` - Remove item from localStorage
-- `setSession<T>(key: string, value: T): boolean` - Set item in sessionStorage
-- `getSession<T>(key: string, defaultValue?: T): T | null` - Get item from sessionStorage
-- `setWithExpiration<T>(key, value, expirationMs, useSession?): boolean` - Set item with expiration
-- `getWithExpiration<T>(key, useSession?): T | null` - Get item with expiration check
+- `sendEvent(event: string): void` - Send event to all subscribers
+- `onePlusNEvents: Observable<string>` - Subscribe to all events with replay buffer
 
-### LoggerService
+### EventBus (Core)
 
-- `debug(message: string, ...args: any[]): void` - Log debug message
-- `info(message: string, ...args: any[]): void` - Log info message
-- `warn(message: string, ...args: any[]): void` - Log warning message
-- `error(message: string, error?: any, ...args: any[]): void` - Log error message
-- `time<T>(label: string, fn: () => Promise<T> | T): Promise<T>` - Measure execution time
+- `emit<T>(eventType: string, data?: T): void` - Emit an event
+- `on<T>(eventType: string): Observable<T>` - Subscribe to an event
+- `onMultiple(eventTypes: string[]): Observable<EventPayload>` - Subscribe to multiple events
+- `onAll(): Observable<EventPayload>` - Subscribe to all events
 
 ## 🛠️ Development
 
@@ -436,4 +232,3 @@ Contributions, issues, and feature requests are welcome!
 ## ⭐ Show your support
 
 Give a ⭐️ if this project helped you!
-