@opensourcekd/ng-common-libs 1.2.6 → 1.2.8

package/README.md

@@ -27,6 +27,70 @@ npm install @opensourcekd/ng-common-libs
 
 ## 🔧 Usage
 
+### ⚠️ IMPORTANT: Setup for Module Federation / MicroFrontends
+
+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):**
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { 
+  AuthService, 
+  EventBusService, 
+  getAuthService, 
+  getEventBusService,
+  configureAuth0 
+} 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,
+});
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // REQUIRED: Use factory functions for singleton behavior across 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.
+
+**For NgModule-based apps:**
+```typescript
+import { NgModule } from '@angular/core';
+import { 
+  AuthService, 
+  EventBusService, 
+  getAuthService, 
+  getEventBusService 
+} from '@opensourcekd/ng-common-libs';
+
+@NgModule({
+  providers: [
+    { provide: EventBusService, useFactory: getEventBusService },
+    { provide: AuthService, useFactory: getAuthService }
+  ]
+})
+export class AppModule { }
+```
+
+Then use normally in components with `inject()`:
+```typescript
+export class MyComponent {
+  private authService = inject(AuthService);
+  private eventBus = inject(EventBusService);
+}
+```
+
 ### Configuration (Framework-Agnostic)
 
 The library provides a framework-agnostic configuration utility with **statically configured values** from GitHub repository variables:
@@ -49,19 +113,13 @@ console.log(APP_CONFIG.auth0ClientId);  // Configured during build from GitHub v
 
 ### Auth0 Authentication
 
-Complete Auth0 integration with automatic token management and event emission:
+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, configureAuth0 } from '@opensourcekd/ng-common-libs';
-import { APP_CONFIG } from '@opensourcekd/ng-common-libs/core';
-
-// Use pre-configured values from APP_CONFIG
-configureAuth0({
-  domain: APP_CONFIG.auth0Domain,
-  clientId: APP_CONFIG.auth0ClientId,
-  audience: APP_CONFIG.apiUrl,
-});
+import { AuthService } from '@opensourcekd/ng-common-libs';
 
 @Component({
   selector: 'app-login',
@@ -89,7 +147,9 @@ See the [Auth0 Service Usage Guide](./docs/AUTH_SERVICE_USAGE.md) for complete i
 
 ### EventBusService
 
-Cross-application event communication for MicroFrontend architectures:
+Cross-application event communication for MicroFrontend architectures.
+
+**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, OnInit, inject } from '@angular/core';
@@ -217,14 +277,16 @@ export default {
 
 ### AuthService
 
-- `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
+- `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