@opensourcekd/ng-common-libs 1.2.4 → 1.2.6

package/README.md

@@ -1,24 +1,19 @@
 # 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)
+- **APP_CONFIG**: Framework-agnostic configuration utility for all environment variables (Auth0, API URLs)
 - **EventBusService**: MicroFrontend-ready event bus with replay buffer for cross-app communication
 - **Auth0 Integration**: Complete Auth0 authentication service with token management
-- **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
 
 ## 📦 Installation
 
@@ -32,68 +27,25 @@ npm install @opensourcekd/ng-common-libs
 
 ## 🔧 Usage
 
-### For Angular Projects
+### Configuration (Framework-Agnostic)
 
-Use the Angular-specific imports that provide dependency injection:
+The library provides a framework-agnostic configuration utility with **statically configured values** from GitHub repository variables:
 
 ```typescript
-import { Component, OnInit, inject } from '@angular/core';
-import { NgEventEmitter } from '@opensourcekd/ng-common-libs';
-
-@Component({
-  selector: 'app-example',
-  template: `...`
-})
-export class ExampleComponent implements OnInit {
-  private eventEmitter = inject(NgEventEmitter);
+// Import from /core for framework-agnostic usage
+import { APP_CONFIG } from '@opensourcekd/ng-common-libs/core';
 
-  ngOnInit() {
-    // Subscribe to events
-    this.eventEmitter.on('user:login').subscribe(data => {
-      console.log('User logged in:', data);
-    });
-  }
-
-  login() {
-    // Emit events
-    this.eventEmitter.emit('user:login', { 
-      userId: '123', 
-      username: 'john' 
-    });
-  }
-}
+// Access pre-configured values anywhere in your app
+console.log(APP_CONFIG.apiUrl);        // Configured during build from GitHub vars
+console.log(APP_CONFIG.auth0Domain);    // Configured during build from GitHub vars
+console.log(APP_CONFIG.auth0ClientId);  // Configured during build from GitHub vars
 ```
 
-### Authorization
-
-#### Token Service
-
-Manage authentication tokens with ease:
-
-```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();
-  }
-}
-```
+**Key Features:**
+- Values are **statically baked** into the library during build time from GitHub repository variables
+- No runtime configuration needed - values are available immediately
+- Can be used across any framework: Angular, React, Vue, Svelte, vanilla JS
+- Perfect for MicroFrontends (MFEs) and shell applications
 
 ### Auth0 Authentication
 
@@ -102,12 +54,13 @@ Complete Auth0 integration with automatic token management and event emission:
 ```typescript
 import { Component, inject } from '@angular/core';
 import { AuthService, configureAuth0 } from '@opensourcekd/ng-common-libs';
+import { APP_CONFIG } from '@opensourcekd/ng-common-libs/core';
 
-// Configure Auth0 in your app.config.ts
+// Use pre-configured values from APP_CONFIG
 configureAuth0({
-  domain: 'your-domain.auth0.com',
-  clientId: 'your-client-id',
-  audience: 'https://your-api.com',
+  domain: APP_CONFIG.auth0Domain,
+  clientId: APP_CONFIG.auth0ClientId,
+  audience: APP_CONFIG.apiUrl,
 });
 
 @Component({
@@ -169,198 +122,13 @@ export class EventExampleComponent implements OnInit {
 
 See the [EventBus Service Usage Guide](./docs/EVENT_BUS_USAGE.md) for advanced patterns and MicroFrontend examples.
 
-#### 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
-
-Centralized logging with configurable levels:
-
-```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'
-    });
-  }
-
-  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();
-    });
-  }
-}
-```
-
-### 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])
-    )
-  ]
-};
-```
-
 ### 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();
@@ -368,23 +136,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
@@ -444,51 +195,48 @@ 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
+### Core Configuration (Framework-Agnostic)
 
-- `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
+- `APP_CONFIG` - Read-only application configuration object with values statically configured during build time:
+  - `auth0Domain: string` - Auth0 tenant domain (from GitHub var `AUTH0_DOMAIN`)
+  - `auth0ClientId: string` - Auth0 client ID (from GitHub var `AUTH0_CLIENT_ID`)
+  - `apiUrl: string` - API base URL (from GitHub var `API_URL`)
+
+### Angular Configuration
 
-### TokenService
+- `configureAuth0(config: Partial<AUTH0_CONFIG>): void` - Configure Auth0 settings (domain, clientId, etc.)
+- `AUTH0_CONFIG` - Auth0 configuration object (domain, clientId, redirectUri, etc.)
 
-- `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
+### AuthService
 
-### StorageService
+- `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
 
-- `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
+### EventBusService
 
-### LoggerService
+- `sendEvent(event: string): void` - Send event to all subscribers
+- `onePlusNEvents: Observable<string>` - Subscribe to all events with replay buffer
 
-- `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
+### EventBus (Core)
+
+- `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
 
@@ -518,4 +266,3 @@ Contributions, issues, and feature requests are welcome!
 ## ⭐ Show your support
 
 Give a ⭐️ if this project helped you!
-