@opensourcekd/ng-common-libs 1.2.8 → 2.0.1

package/README.md

@@ -2,18 +2,33 @@
 
 Angular 18 library with Auth0 authentication service and MicroFrontend event bus.
 
-## 🎯 Dual-Layer Architecture
+## 🎯 Simple Architecture
 
-This library features a **dual-layer architecture**:
+**One import path. Everything you need.**
 
-- **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.
+All services, utilities, and types are exported from a single package:
+
+```typescript
+import { 
+  AuthService, 
+  EventBusService, 
+  getAuthService,
+  getEventBusService,
+  getApiUrl,
+  UserInfo,
+  EventBus
+} from '@opensourcekd/ng-common-libs';
+```
+
+> 📖 **Complete Guide**: See [CONSUMPTION_GUIDE.md](./CONSUMPTION_GUIDE.md) for detailed usage instructions.
 
 ## 🚀 Features
 
-- **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
+- **AuthService**: Complete Auth0 authentication with token management
+- **EventBusService**: MicroFrontend-ready event bus with replay buffer
+- **Module Federation Support**: Singleton pattern works across shell + MFEs
+- **AOT-Safe**: No JIT compiler required, works in production builds
+- **Framework-Agnostic Core**: EventBus can be used in React, Vue, or vanilla JS
 
 ## 📦 Installation
 
@@ -21,17 +36,13 @@ 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.
+> **Note:** `mitt` and `@auth0/auth0-spa-js` are bundled. No separate installation needed.
 
-## 🔧 Usage
+## 🔧 Quick Start
 
-### ⚠️ IMPORTANT: Setup for Module Federation / MicroFrontends
+### For Module Federation (Shell + MFEs)
 
-If you're using **Module Federation** with multiple Angular applications (shell + MFEs), you **MUST** configure the services as singletons using factory functions. This ensures ONE instance is shared across all applications.
-
-**In your shell app AND each MFE's `app.config.ts` (standalone) or `app.module.ts` (NgModule):**
+**In your shell app AND each MFE's `app.config.ts`:**
 
 ```typescript
 import { ApplicationConfig } from '@angular/core';
@@ -39,267 +50,86 @@ import {
   AuthService, 
   EventBusService, 
   getAuthService, 
-  getEventBusService,
-  configureAuth0 
+  getEventBusService
 } from '@opensourcekd/ng-common-libs';
-import { APP_CONFIG } from '@opensourcekd/ng-common-libs/core';
 
-// Configure Auth0 (do this once in shell or each MFE)
-configureAuth0({
-  domain: APP_CONFIG.auth0Domain,
-  clientId: APP_CONFIG.auth0ClientId,
-  audience: APP_CONFIG.apiUrl,
-});
+// No configuration needed - API URL is baked into the library during build
 
 export const appConfig: ApplicationConfig = {
   providers: [
-    // REQUIRED: Use factory functions for singleton behavior across MFEs
+    // Factory functions ensure singleton across all MFEs
     { provide: EventBusService, useFactory: getEventBusService },
     { provide: AuthService, useFactory: getAuthService },
-    // ... your other providers
   ]
 };
 ```
 
-**Why is this needed?**  
-Angular's `providedIn: 'root'` creates one instance per Angular application. In Module Federation, each MFE is a separate Angular app, so you'd get multiple instances. Factory functions create a **JavaScript module-level singleton** that's shared across ALL applications.
+**Why factory functions?**  
+They create a **JavaScript module-level singleton** shared across ALL applications (shell + MFEs). Module Federation ensures the module loads once, so all apps get the same instance.
 
-**For NgModule-based apps:**
-```typescript
-import { NgModule } from '@angular/core';
-import { 
-  AuthService, 
-  EventBusService, 
-  getAuthService, 
-  getEventBusService 
-} from '@opensourcekd/ng-common-libs';
+### For Standalone Components
 
-@NgModule({
-  providers: [
-    { provide: EventBusService, useFactory: getEventBusService },
-    { provide: AuthService, useFactory: getAuthService }
-  ]
-})
-export class AppModule { }
-```
-
-Then use normally in components with `inject()`:
+Then use normally with `inject()`:
 ```typescript
+import { Component, inject } from '@angular/core';
+import { AuthService, EventBusService } from '@opensourcekd/ng-common-libs';
+
 export class MyComponent {
   private authService = inject(AuthService);
   private eventBus = inject(EventBusService);
+  
+  login() { this.authService.login(); }
 }
 ```
 
-### Configuration (Framework-Agnostic)
-
-The library provides a framework-agnostic configuration utility with **statically configured values** from GitHub repository variables:
-
-```typescript
-// Import from /core for framework-agnostic usage
-import { APP_CONFIG } from '@opensourcekd/ng-common-libs/core';
-
-// 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
-```
-
-**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
-
-Complete Auth0 integration with automatic token management and event emission.
-
-**Note:** Make sure you've configured the providers as shown in the [Module Federation setup](#️-important-setup-for-module-federation--microfrontends) above first!
-
-```typescript
-import { Component, inject } from '@angular/core';
-import { AuthService } from '@opensourcekd/ng-common-libs';
-
-@Component({
-  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 LoginComponent {
-  private authService = inject(AuthService);
-  user = this.authService.getUser();
-
-  async login() {
-    await this.authService.login();
-  }
-
-  async logout() {
-    await this.authService.logout();
-  }
-}
-```
-
-See the [Auth0 Service Usage Guide](./docs/AUTH_SERVICE_USAGE.md) for complete integration instructions.
-
-### EventBusService
-
-Cross-application event communication for MicroFrontend architectures.
+### API URL Access
 
-**Note:** Make sure you've configured the providers as shown in the [Module Federation setup](#️-important-setup-for-module-federation--microfrontends) above first!
+**No configuration needed** - API URL is automatically available:
 
 ```typescript
-import { Component, OnInit, inject } from '@angular/core';
-import { EventBusService } from '@opensourcekd/ng-common-libs';
-
-@Component({
-  selector: 'app-event-example',
-  template: `<button (click)="sendEvent()">Send Event</button>`
-})
-export class EventExampleComponent implements OnInit {
-  private eventBus = inject(EventBusService);
+import { getApiUrl } from '@opensourcekd/ng-common-libs';
 
-  ngOnInit() {
-    // Subscribe to all events
-    this.eventBus.onePlusNEvents.subscribe(event => {
-      console.log('Event received:', event);
-    });
-  }
-
-  sendEvent() {
-    // Send structured event
-    this.eventBus.sendEvent(JSON.stringify({
-      type: 'user:action',
-      payload: { userId: '123' },
-      timestamp: new Date().toISOString()
-    }));
-  }
-}
-```
-
-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 event bus:
-
-```typescript
-// Import from /core
-import { EventBus } from '@opensourcekd/ng-common-libs/core';
-
-// Event Bus
-const eventBus = new EventBus();
-eventBus.emit('user:login', { userId: '123' });
-eventBus.on('user:login').subscribe(data => {
-  console.log('User logged in:', data);
-});
+// API URL is baked into the library during build from GitHub repository variables
+const apiUrl = getApiUrl();
+const endpoint = `${apiUrl}/users`;
 ```
 
-#### React Example
+> ℹ️ **Note**: The API URL is configured in GitHub repository variables (API_URL) and baked into the library during the CI/CD build process. No runtime configuration is needed in consuming applications.
 
-```typescript
-import { useEffect } from 'react';
-import { EventBus } from '@opensourcekd/ng-common-libs/core';
-
-const eventBus = new EventBus();
-
-function MyComponent() {
-  useEffect(() => {
-    const subscription = eventBus.on('user:login').subscribe(data => {
-      console.log('User logged in:', data);
-    });
-    return () => subscription.unsubscribe();
-  }, []);
+## 📚 Documentation
 
-  const handleLogin = () => {
-    eventBus.emit('user:login', { userId: '123' });
-  };
+- **[CONSUMPTION_GUIDE.md](./CONSUMPTION_GUIDE.md)** - Complete setup guide and API reference
+- **[Auth0 Service Usage](./docs/AUTH_SERVICE_USAGE.md)** - Detailed Auth0 integration
+- **[EventBus Service Usage](./docs/EVENT_BUS_USAGE.md)** - Cross-application event patterns
+- **[Module Federation Guide](./docs/MODULE_FEDERATION.md)** - Runtime sharing configuration
 
-  return <button onClick={handleLogin}>Login</button>;
-}
-```
+## 📝 What's Exported
 
-#### Vue Example
+Everything you need from one import:
 
 ```typescript
-import { onMounted, onUnmounted } from 'vue';
-import { EventBus } from '@opensourcekd/ng-common-libs/core';
-
-const eventBus = new EventBus();
-
-export default {
-  setup() {
-    let subscription;
-
-    onMounted(() => {
-      subscription = eventBus.on('user:login').subscribe(data => {
-        console.log('User logged in:', data);
-      });
-    });
-
-    onUnmounted(() => {
-      subscription?.unsubscribe();
-    });
-
-    const handleLogin = () => {
-      eventBus.emit('user:login', { userId: '123' });
-    };
-
-    return { handleLogin };
-  }
-};
+import { 
+  // Services
+  AuthService,
+  EventBusService,
+  
+  // Factory Functions
+  getAuthService,
+  getEventBusService,
+  
+  // API Access
+  getApiUrl,
+  
+  // Core Utilities
+  EventBus,
+  
+  // Types & Interfaces
+  UserInfo,
+  UserData,
+  EventPayload,
+} from '@opensourcekd/ng-common-libs';
 ```
 
-## 📚 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
-
-## 📝 API Documentation
-
-### Core Configuration (Framework-Agnostic)
-
-- `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
-
-- `configureAuth0(config: Partial<AUTH0_CONFIG>): void` - Configure Auth0 settings (domain, clientId, etc.)
-- `AUTH0_CONFIG` - Auth0 configuration object (domain, clientId, redirectUri, etc.)
-
-### AuthService
-
-- `login(user?: string, options?: { invitation?: string; organization?: string }): Promise<void>` - Initiate Auth0 login with optional user identifier and organization invitation parameters
-- `logout(): Promise<void>` - Logout and clear session
-- `handleCallback(): Promise<{ success: boolean, appState?: any }>` - Handle Auth0 callback and return success status with preserved appState
-- `getToken(): Promise<string | null>` - Get access token asynchronously (checks storage first, then Auth0)
-- `getTokenSync(): string | null` - Get cached access token synchronously (storage only)
-- `getUser(): UserInfo | null` - Get current user information
-- `getUserData(): UserData | null` - Get simplified user data with role and organization extraction
-- `isAuthenticated(): Promise<boolean>` - Check authentication status asynchronously (verifies with Auth0)
-- `isAuthenticatedSync(): boolean` - Check authentication status synchronously (storage only)
-- `user$: Observable<UserInfo | null>` - Observable stream of user changes
-
-### EventBusService
-
-- `sendEvent(event: string): void` - Send event to all subscribers
-- `onePlusNEvents: Observable<string>` - Subscribe to all events with replay buffer
-
-### 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
 
 ```bash