mesauth-angular 1.0.1 → 1.1.1

package/README.md

@@ -4,6 +4,15 @@ Angular helper library to connect to a backend API and SignalR hub to surface th
 
 ## Changelog
 
+### v1.1.0 (2026-01-21) - **Major Update**
+- 🚀 **New `provideMesAuth()` Function**: Simplified setup with a single function call
+- ✨ **Functional Interceptor**: New `mesAuthInterceptor` for better compatibility with standalone apps
+- 📦 **Automatic Initialization**: `provideMesAuth()` handles service initialization via `APP_INITIALIZER`
+- 🔧 **Simplified API**: Just pass `apiBaseUrl` and `userBaseUrl` - no manual DI required
+
+### v1.0.1 (2026-01-21)
+- 🔧 Internal refactoring for better module compatibility
+
 ### v0.2.28 (2026-01-19)
 - ✨ **Enhanced Avatar Support**: Direct `avatarPath` usage from user data for instant display without backend calls
 - 🔄 **Improved Avatar Refresh**: Timestamp-based cache busting prevents request cancellation issues
@@ -20,7 +29,70 @@ Angular helper library to connect to a backend API and SignalR hub to surface th
 - 🎨 **Dark/Light Theme**: Automatic theme detection and support
 - 🖼️ **Avatar Support**: Direct API-based avatar loading
 - 🍞 **Toast Notifications**: In-app notification toasts
-- 🛡️ **HTTP Interceptor**: Automatic 403 error handling
+- 🛡️ **HTTP Interceptor**: Automatic 401/403 error handling with redirects
+
+## Quick Start (v1.1.0+)
+
+### 1. Install
+
+```bash
+npm install mesauth-angular
+```
+
+### 2. Configure in app.config.ts (Recommended for Angular 14+)
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { provideMesAuth, mesAuthInterceptor } from 'mesauth-angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(
+      withInterceptors([mesAuthInterceptor])  // Handles 401/403 redirects
+    ),
+    provideMesAuth({
+      apiBaseUrl: 'https://mes.kefico.vn/auth',
+      userBaseUrl: 'https://mes.kefico.vn/x'   // For login/403 redirects
+    })
+  ]
+};
+```
+
+That's it! The library handles:
+- Service initialization via `APP_INITIALIZER`
+- `HttpClient` and `Router` injection automatically
+- 401 → redirects to `{userBaseUrl}/login?returnUrl=...`
+- 403 → redirects to `{userBaseUrl}/403?returnUrl=...`
+
+### 3. Use in Components
+
+```ts
+import { MesAuthService } from 'mesauth-angular';
+
+@Component({...})
+export class MyComponent {
+  private auth = inject(MesAuthService);
+
+  // Observable streams
+  currentUser$ = this.auth.currentUser$;
+  notifications$ = this.auth.notifications$;
+
+  logout() {
+    this.auth.logout().subscribe();
+  }
+}
+```
+
+## Configuration Options
+
+```ts
+interface MesAuthConfig {
+  apiBaseUrl: string;      // Required: MesAuth API base URL
+  userBaseUrl?: string;    // Optional: Base URL for login/403 redirects
+  withCredentials?: boolean; // Optional: Send cookies (default: true)
+}
+```
 
 ## Theme Support
 
@@ -75,150 +147,9 @@ Avatar URLs include timestamps to prevent browser caching issues during updates:
 - **UI Avatars**: Generates initials-based avatars if no user data available
 - **Authentication**: Not required for fallback avatars
 
-## Quick Start
-
-1. Install (from local folder during development):
-
-    ```bash
-    cd /path/to/your/angular-app
-    npm install ../path/to/mesauth-angular
-    ```
-
-2. Provide the service and import components:
-   - **For standalone components/apps**: Import `MesAuthModule` in your standalone component or `app.config.ts`.
-     ```ts
-     import { MesAuthModule } from 'mesauth-angular';
-
-     @Component({
-       standalone: true,
-       imports: [MesAuthModule, /* other imports */],
-       // ...
-     })
-     export class MyComponent {}
-     ```
-     Or in `app.config.ts`:
-     ```ts
-     import { MesAuthModule } from 'mesauth-angular';
-
-     export const appConfig: ApplicationConfig = {
-       imports: [MesAuthModule],
-       // ... other config
-     };
-     ```
-   - **For module-based apps**: Import `MesAuthModule` in your `AppModule` or feature module.
-     ```ts
-     import { MesAuthModule } from 'mesauth-angular';
-
-     @NgModule({
-       imports: [MesAuthModule],
-       // ... other config
-     })
-     export class AppModule { }
-     ```
-
-3. (Optional) Provide the HTTP interceptor to handle 403 errors:
-   - The interceptor redirects to `${userBaseUrl}/403?returnUrl=encodedCurrentUrl` using `window.location.href` for external URLs (since `userBaseUrl` may be outside the client app).
-   - **For module-based apps**: Add `MesAuthInterceptor` to providers in `AppModule`.
-     ```ts
-     import { HTTP_INTERCEPTORS } from '@angular/common/http';
-     import { MesAuthInterceptor } from 'mesauth-angular';
-
-     @NgModule({
-       // ... other module config ...
-       providers: [
-         // ... other providers ...
-         { provide: HTTP_INTERCEPTORS, useClass: MesAuthInterceptor, multi: true }
-       ]
-     })
-     export class AppModule { }
-     ```
-   - **For standalone apps**: Add `MesAuthInterceptor` to providers in `app.config.ts`.
-     ```ts
-     import { HTTP_INTERCEPTORS } from '@angular/common/http';
-     import { MesAuthInterceptor } from 'mesauth-angular';
-
-     export const appConfig: ApplicationConfig = {
-       providers: [
-         // ... other providers ...
-         { provide: HTTP_INTERCEPTORS, useClass: MesAuthInterceptor, multi: true }
-       ]
-     };
-     ```
-
-4. Initialize in your app (recommended in `AppComponent` constructor):
-
-    **⚠️ IMPORTANT:** Starting from v0.2.16, `MesAuthService` requires `HttpClient` and optionally `Router` to be passed to the `init()` method. This prevents dependency injection timing issues.
-
-    ```ts
-    // In AppComponent constructor (recommended)
-    import { HttpClient } from '@angular/common/http';
-    import { Router } from '@angular/router';
-    import { inject } from '@angular/core';
-    import { MesAuthService } from 'mesauth-angular';
-
-    export class AppComponent {
-      readonly #mesAuthService = inject(MesAuthService);
-      readonly #router = inject(Router);
-
-      constructor() {
-        // Initialize MesAuth with HttpClient and Router
-        this.#mesAuthService.init(
-          {
-            apiBaseUrl: 'https://api.example.com',
-            withCredentials: true,
-            userBaseUrl: 'https://api.example.com/users'
-          },
-          inject(HttpClient),  // Required: pass HttpClient
-          this.#router         // Optional: pass Router for automatic user refresh on navigation
-        );
-
-        // Subscribe to observables
-        this.#mesAuthService.currentUser$.subscribe(user => console.log('user', user));
-        this.#mesAuthService.notifications$.subscribe(n => console.log('notif', n));
-      }
-    }
-    ```
-
-    **Why this change?**
-    - Previous versions injected `HttpClient` and `Router` directly in the service constructor
-    - This caused `NG0203` injection context errors during route loading and early bootstrap
-    - The new pattern delays dependency access until after the app is fully initialized
-
-    **For Module-based Apps:**
-
-    ```ts
-    // In AppComponent
-    import { HttpClient } from '@angular/common/http';
-    import { Router } from '@angular/router';
-
-    constructor(
-      private mesAuth: MesAuthService,
-      private http: HttpClient,
-      private router: Router
-    ) {
-      this.mesAuth.init(
-        {
-          apiBaseUrl: 'https://api.example.com',
-          withCredentials: true,
-          userBaseUrl: 'https://api.example.com/users'
-        },
-        this.http,    // Required
-        this.router   // Optional
-      );
-    }
-    ```
-
-5. Build the package for publishing:
-
-    ```bash
-    cd /path/to/mesauth-angular
-    npm install
-    npm run build
-    ```
-
 ## Components
 
-**Note:** All components are standalone and can only be imported in standalone components or apps. If your app uses NgModules, use dynamic imports or convert to standalone.
+**Note:** All components are standalone and can be imported directly.
 
 ### ma-user-profile
 
@@ -232,7 +163,7 @@ A reusable Angular component for displaying the current user's profile informati
 - **Usage Example**:
 
     ```html
-    <ma-user-profile 
+    <ma-user-profile
       (onNavigate)="handleNavigation($event)"
       (onLogout)="handleLogout()">
     </ma-user-profile>
@@ -273,166 +204,62 @@ A standalone component for displaying a slide-out notification panel with real-t
     notificationPanel.open();
     ```
 
-## Changelog
-
-### v0.2.27 (Latest)
-- 👤 **Enhanced Profile**: Added comprehensive HR information display support in user profiles
-- 🖼️ **Avatar Upload**: Implemented avatar cropping with drag and zoom functionality
-- 🔒 **Privacy Compliance**: Removed sensitive HR fields (Position/Job Title) from profile display
-- 🎨 **UI Improvements**: Better profile layout with HR information grid
-
-### v0.2.18
-- 🔗 **Interceptor Improvement**: `MesAuthInterceptor` now uses `router.url` instead of `window.location.href` for cleaner returnUrl parameters
-- 📍 **Shorter URLs**: Return URLs are now relative paths (`/dashboard`) instead of full URLs (`https://domain.com/dashboard`)
-- 🔄 **Better Fallback**: Falls back to `window.location.pathname + search` if router URL is unavailable
-
-### v0.2.17
-- 🐛 **ViewChild Fix**: Fixed `MaUserComponent` ViewChild query error by adding `AfterViewInit` lifecycle and `{ static: false }` option
-- ✅ **Error Handling**: Added graceful error handling for 401/403 responses on auth endpoints (silent handling when user not logged in)
-- 🧹 **Clean Console**: Auth errors no longer pollute the console - expected authentication failures are handled silently
-- 🛡️ **Null Safety**: Added null check in `onNotificationRead()` to prevent errors when userProfile is not yet initialized
-
-### v0.2.16
-- 🔧 **Breaking Change**: `init()` method now requires `HttpClient` and optionally `Router` as parameters
-- 🚫 **Injection Fix**: Removed `HttpClient` and `Router` from service constructor to prevent `NG0203` injection context errors
-- ⚡ **Improved Initialization**: Dependencies are now passed explicitly to `init()` method, resolving timing issues during route loading
-- 📝 **API Change**: `init(config: MesAuthConfig, httpClient: HttpClient, router?: Router)`
-- 🎯 **Why**: Fixes dependency injection errors that occurred during lazy route loading and early bootstrap phases
-
-### v0.2.13
-- 🎨 **Notification Format**: Cleaned up notification title format by removing redundant `[sourceAppName]` prefix
-- 📱 **Improved Layout**: Source app name now displayed separately in metadata row for better organization
-- 🔔 **Consistent Toasts**: Toast notifications also updated to use clean title format without app name prefix
-
-### v0.2.12
-- 📝 **HTML Message Support**: Added priority support for `messageHtml` over `message` in notifications
-- 🎨 **Rich Text Display**: Notifications now render HTML content when available, with fallback to plain text
-- 🔔 **Enhanced Toasts**: Toast notifications also support HTML content with proper rendering
-
-### v0.2.9
-- 🔐 **Credentials Fix**: Added `withCredentials: true` to all HTTP requests to properly send authentication cookies
-- 🐛 **403 Forbidden Fix**: Resolved authentication issues where API calls were failing due to missing credentials
-- 🔧 **Consistent Auth**: All API endpoints now properly include credentials for authenticated requests
-
-### v0.2.8
-- 🔄 **Route Change Optimization**: Improved route change detection with debouncing and selective refreshing
-- 🛡️ **Protected Route Handling**: Only refresh user data on protected routes, avoiding auth flow interference
-- 🔧 **Smart URL Construction**: Fixed double `/auth` path issue for auth endpoints when apiBaseUrl includes `/auth`
-- ⏱️ **Timing Improvements**: Added delays and better timing for authentication state management
-
-### v0.2.7
-- 🔄 **Route Change Detection**: Added automatic user data refresh when routes change in single-page applications
-- 🎯 **SPA Support**: Handles login scenarios where page doesn't reload but route changes occur
-- 🛡️ **Optional Dependency**: Router integration is optional - service works with or without Router injection
-
-### v0.2.6
-- 🗑️ **Delete Button**: Added delete button for read notifications in the read tab
-- 🎯 **Contextual Actions**: Unread notifications show "mark as read" button, read notifications show "delete" button
-- 🎨 **Visual Feedback**: Delete button uses error color on hover for clear destructive action indication
-
-### v0.2.5
-- 🗂️ **Notification Tabs**: Added tabs to separate unread and read notifications with unread tab as default
-- 📊 **Tab Counters**: Display notification counts for each tab (Unread/Read)
-- 🎯 **Improved UX**: Better organization of notifications with tab-based navigation
-- 🔄 **Enhanced Filtering**: Load both read and unread notifications for seamless tab switching
-
-### v0.2.4
-- 🔔 **Notification UX**: Changed notification delete button to mark-as-read with checkmark icon
-- 🔄 **Badge Updates**: Added automatic badge counter refresh when notifications are marked as read
-- 🎯 **Event System**: Implemented event-driven communication between notification panel and badge components
-
-### v0.2.3
-- 🧹 **Code Cleanup**: Removed all console.log and console.error statements for production readiness
-- 📚 **Documentation**: Updated README with comprehensive changelog, theme support guide, and API documentation
-- 🏷️ **Package Metadata**: Updated package description to reflect theme support
-
-### v0.2.2
-- ✨ **Theme Support**: Added automatic dark/light theme detection and real-time theme switching
-- 🖼️ **Avatar API**: Changed avatar loading to use API endpoint (`/auth/{userId}/avatar`) instead of external service
-- 🎨 **UI Improvements**: Better toast styling with proper borders and sizing
-
-### v0.2.1
-- 🔄 **Dynamic Themes**: Added real-time theme change detection using MutationObserver
-- 🐛 **Toast Fixes**: Improved toast background and sizing for dark themes
-
-### v0.2.0
-- 🎨 **Initial Theme Support**: Basic dark/light theme implementation
-- 🖼️ **Avatar Updates**: Changed to API-based avatar loading
-
-### v0.1.20
-- 🐛 **Bug fixes and improvements**
-
-## Notes
-- The service expects an endpoint `GET {apiBaseUrl}/auth/me` that returns the current user.
-- Avatar endpoint: `GET {apiBaseUrl}/auth/{userId}/avatar`
-- SignalR events used: `ReceiveNotification` (adjust to your backend).
-
 ## Migration Guide
 
-### Upgrading from v0.2.15 or earlier to v0.2.16+
+### Upgrading from v0.x to v1.1.0+
 
-The initialization pattern has changed to fix dependency injection timing issues. Follow these steps:
+The setup has been greatly simplified. Here's how to migrate:
 
-**Before (v0.2.15 and earlier):**
+**Before (v0.x):**
 ```ts
-constructor(private mesAuth: MesAuthService) {
-  this.mesAuth.init({
-    apiBaseUrl: 'https://api.example.com',
-    withCredentials: true,
-    userBaseUrl: 'https://api.example.com/users'
-  });
-}
-```
-
-**After (v0.2.16+):**
-```ts
-import { HttpClient } from '@angular/common/http';
-import { Router } from '@angular/router';
-import { inject } from '@angular/core';
-
+// app.config.ts - OLD WAY
+import { MesAuthModule, MesAuthService } from 'mesauth-angular';
+import { HTTP_INTERCEPTORS } from '@angular/common/http';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    importProvidersFrom(MesAuthModule),
+    { provide: HTTP_INTERCEPTORS, useClass: MesAuthInterceptor, multi: true }
+  ]
+};
+
+// app.component.ts - OLD WAY
 export class AppComponent {
-  readonly #mesAuthService = inject(MesAuthService);
-  readonly #router = inject(Router);
-
   constructor() {
-    // Pass HttpClient and Router to init()
-    this.#mesAuthService.init(
-      {
-        apiBaseUrl: 'https://api.example.com',
-        withCredentials: true,
-        userBaseUrl: 'https://api.example.com/users'
-      },
-      inject(HttpClient),  // Required: add this parameter
-      this.#router         // Optional: add this parameter for auto user refresh
-    );
+    this.mesAuthService.init({
+      apiBaseUrl: '...',
+      userBaseUrl: '...'
+    }, inject(HttpClient), inject(Router));
   }
 }
 ```
 
-**For module-based apps:**
+**After (v1.1.0+):**
 ```ts
-constructor(
-  private mesAuth: MesAuthService,
-  private http: HttpClient,    // Add this
-  private router: Router       // Add this (optional)
-) {
-  this.mesAuth.init(
-    {
-      apiBaseUrl: 'https://api.example.com',
-      withCredentials: true,
-      userBaseUrl: 'https://api.example.com/users'
-    },
-    this.http,    // Add this parameter
-    this.router   // Add this parameter (optional)
-  );
+// app.config.ts - NEW WAY (everything in one place!)
+import { provideMesAuth, mesAuthInterceptor } from 'mesauth-angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(withInterceptors([mesAuthInterceptor])),
+    provideMesAuth({
+      apiBaseUrl: 'https://mes.kefico.vn/auth',
+      userBaseUrl: 'https://mes.kefico.vn/x'
+    })
+  ]
+};
+
+// app.component.ts - No init() needed!
+export class AppComponent {
+  // Just inject and use - no manual initialization required
 }
 ```
 
-**What changed and why:**
-- `HttpClient` is now required as the 2nd parameter to `init()`
-- `Router` is optional as the 3rd parameter (recommended for SPA user refresh)
-- This fixes `NG0203` injection errors that occurred during route lazy-loading
-- The service constructor is now empty - all dependencies are passed to `init()`
+**Key Changes:**
+- `provideMesAuth()` replaces `MesAuthModule` + manual `init()` call
+- `mesAuthInterceptor` (functional) replaces `MesAuthInterceptor` (class-based)
+- No need to inject `HttpClient` or `Router` manually
+- Configuration moved from `AppComponent` to `app.config.ts`
 
 ## Troubleshooting
 
@@ -440,7 +267,6 @@ constructor(
 If you encounter an error like "The injectable 'MesAuthService' needs to be compiled using the JIT compiler, but '@angular/compiler' is not available," this typically occurs because:
 - The package is being imported directly from source code (e.g., during development) without building it first.
 - The client app is running in AOT (Ahead-of-Time) compilation mode, which requires pre-compiled libraries.
-- **Why JIT is required:** Originally, `MesAuthService` used `@Injectable({ providedIn: 'root' })`, making it a library-provided service. Angular libraries must be built with tools like ng-packagr to generate AOT-compatible code. If not, or if imported from source, the service requires JIT compilation in the client's app. This change (removing `providedIn: 'root'` and requiring manual provision) allows the service to be compiled in your app's context, supporting both JIT and AOT modes.
 
 **Solutions:**
 1. **Build the package for production/AOT compatibility:**
@@ -449,37 +275,17 @@ If you encounter an error like "The injectable 'MesAuthService' needs to be comp
 
 2. **For development (if you must link to source):**
    - Switch your Angular app to JIT mode by bootstrapping with `@angular/platform-browser-dynamic` instead of `@angular/platform-browser`.
-   - Example in `main.ts`:
-     ```ts
-     import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
-     import { AppModule } from './app/app.module';
-
-     platformBrowserDynamic().bootstrapModule(AppModule);
-     ```
-   - Note: JIT is not recommended for production; use AOT for better performance.
 
 3. **Verify imports:**
    - Ensure you're importing from the built package (e.g., `import { MesAuthService } from 'mesauth-angular';`) and not from the `src` folder.
-   - If using standalone components, confirm the service is available in the injection context.
-
-If issues persist, check your Angular version compatibility and ensure the package's `package.json` includes the correct entry points for AOT.
 
 ### Components Appear Empty
 If components like `ma-user` or `ma-user-profile` render as empty:
-- Ensure `MesAuthService` is provided in your app (see Quick Start step 2).
-- Check browser console for logs from components (e.g., "UserProfileComponent: currentUser").
-- If `currentUser` is null, the component shows a login button—verify the service is initialized and the API returns user data.
-- For standalone apps, confirm `APP_INITIALIZER` or manual init is used.
-
----
+- Ensure `provideMesAuth()` is called in your `app.config.ts`.
+- Check browser console for logs from components.
+- If `currentUser` is null, the component shows a login button—verify the API returns user data.
 
-# Dynamic import in a module-based component
-import { Component } from '@angular/core';
-
-@Component({...})
-export class DefaultHeaderComponent {
-  async ngOnInit() {
-    const { MaUserComponent } = await import('mesauth-angular');
-    // Use it dynamically
-  }
-}
+## Notes
+- The service expects an endpoint `GET {apiBaseUrl}/auth/me` that returns the current user.
+- Avatar endpoint: `GET {apiBaseUrl}/auth/{userId}/avatar`
+- SignalR events used: `ReceiveNotification` (adjust to your backend).