@opensourcekd/ng-common-libs 1.2.8 → 2.0.0

package/dist/angular/index.d.ts

@@ -1,443 +0,0 @@
-import { ReplaySubject, Observable } from 'rxjs';
-import { EventType } from 'mitt';
-
-/**
- * EventBusService - Angular service for cross-application event communication
- * Uses mitt library for efficient event handling and RxJS ReplaySubject for observable stream
- *
- * This service is designed for MicroFrontend architectures where different apps need to communicate
- * The ReplaySubject keeps last 100 events in memory for late subscribers
- *
- * **IMPORTANT for Module Federation / MicroFrontends:**
- * This service uses a module-level singleton to ensure ONE instance across all MFEs and shell.
- * Before using `inject(EventBusService)` in components, you must provide it at application level:
- *
- * @example
- * ```typescript
- * // In app.config.ts (standalone) or app.module.ts (NgModule)
- * import { EventBusService, getEventBusService } from '@opensourcekd/ng-common-libs';
- *
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     { provide: EventBusService, useFactory: getEventBusService }
- *   ]
- * };
- * ```
- *
- * Then use in components:
- * ```typescript
- * import { Component, inject, OnInit } from '@angular/core';
- * import { EventBusService } from '@opensourcekd/ng-common-libs';
- *
- * @Component({
- *   selector: 'app-example',
- *   template: '...'
- * })
- * export class ExampleComponent implements OnInit {
- *   private eventBus = inject(EventBusService);
- *
- *   ngOnInit() {
- *     // Subscribe to all events
- *     this.eventBus.onePlusNEvents.subscribe(event => {
- *       console.log('Event received:', event);
- *     });
- *   }
- *
- *   sendCustomEvent() {
- *     // Send a custom event
- *     this.eventBus.sendEvent('user:action');
- *
- *     // Or send structured event with data
- *     this.eventBus.sendEvent(JSON.stringify({
- *       type: 'user:login',
- *       payload: { userId: '123' },
- *       timestamp: new Date().toISOString()
- *     }));
- *   }
- * }
- * ```
- */
-declare class EventBusService {
-    /**
-     * ReplaySubject that buffers the last 100 events for late subscribers
-     * Subscribe to this observable to receive all events
-     */
-    onePlusNEvents: ReplaySubject<EventType>;
-    /**
-     * mitt event emitter instance
-     * Lightweight event emitter library
-     */
-    private emitter;
-    constructor();
-    /**
-     * Send an event through the event bus
-     * The event will be forwarded to all subscribers via the ReplaySubject
-     *
-     * @param s - Event string, can be a simple event name or JSON stringified structured data
-     *
-     * @example
-     * ```typescript
-     * // Simple event
-     * eventBus.sendEvent('user:logout');
-     *
-     * // Structured event
-     * eventBus.sendEvent(JSON.stringify({
-     *   type: 'auth:token_updated',
-     *   payload: { token: 'abc123' },
-     *   timestamp: new Date().toISOString()
-     * }));
-     * ```
-     */
-    sendEvent(s: string): void;
-}
-/**
- * Factory function to get the singleton EventBusService instance
- * Use this in your application providers to ensure singleton behavior across MFEs
- *
- * @example
- * ```typescript
- * // In app.config.ts or app.module.ts
- * import { EventBusService, getEventBusService } from '@opensourcekd/ng-common-libs';
- *
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     { provide: EventBusService, useFactory: getEventBusService }
- *   ]
- * };
- * ```
- *
- * @returns The singleton EventBusService instance
- */
-declare function getEventBusService(): EventBusService;
-
-/**
- * User information from ID token
- * Standard OIDC claims compatible with Auth0
- */
-interface UserInfo {
-    sub: string;
-    name?: string;
-    email?: string;
-    email_verified?: boolean;
-    preferred_username?: string;
-    given_name?: string;
-    family_name?: string;
-    nickname?: string;
-    locale?: string;
-    picture?: string;
-    phone?: string;
-    phone_verified?: boolean;
-    updated_at?: string;
-    role?: string;
-    org?: string;
-    organization?: string;
-    [key: string]: any;
-}
-/**
- * Simplified user data extracted from token
- */
-interface UserData {
-    id: string;
-    name: string;
-    email: string;
-    role: string;
-    org: string;
-}
-/**
- * Authentication service for Auth0 integration
- * Handles login, logout, token management, and user session
- * Uses sessionStorage for sensitive data and emits authentication events for MicroApps
- *
- * Configuration is centralized in config/auth.config.ts for easy management
- *
- * **IMPORTANT for Module Federation / MicroFrontends:**
- * This service uses a module-level singleton to ensure ONE instance across all MFEs and shell.
- * Before using `inject(AuthService)` in components, you must provide it at application level:
- *
- * @example
- * ```typescript
- * // In app.config.ts (standalone) or app.module.ts (NgModule)
- * import { AuthService, getAuthService, EventBusService, getEventBusService } from '@opensourcekd/ng-common-libs';
- *
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     { provide: EventBusService, useFactory: getEventBusService },
- *     { provide: AuthService, useFactory: getAuthService }
- *   ]
- * };
- * ```
- *
- * NOTE: All navigation logic using setTimeout is commented out as per requirements.
- * To enable navigation after auth operations, uncomment the marked sections in consuming components.
- */
-declare class AuthService {
-    private eventBus;
-    private readonly STANDARD_JWT_CLAIMS;
-    private auth0Client;
-    private initializationPromise;
-    private userSubject;
-    user$: Observable<UserInfo | null>;
-    constructor(eventBus: EventBusService);
-    /**
-     * Initialize Auth0 client
-     */
-    private initializeAuth0;
-    /**
-     * Ensure Auth0 client is initialized before use
-     */
-    private ensureInitialized;
-    /**
-     * Login with Auth0
-     * Redirects to Auth0 Universal Login
-     * Preserves current URL parameters (like invitation tokens) through the auth flow
-     *
-     * @param user - Optional user identifier for logging
-     * @param options - Optional login options including invitation and organization parameters
-     */
-    login(user?: string, options?: {
-        invitation?: string;
-        organization?: string;
-    }): Promise<void>;
-    /**
-     * Handle OAuth2 callback after successful authorization
-     * Processes the callback and retrieves user info
-     *
-     * NOTE: Navigation after successful/failed authentication should be handled in the calling component
-     * using setTimeout. See commented examples in app.component.ts
-     *
-     * @returns Promise<{ success: boolean, appState?: any }> - Success status and preserved appState
-     */
-    handleCallback(): Promise<{
-        success: boolean;
-        appState?: any;
-    }>;
-    /**
-     * Decode and log the access token to console
-     * NOTE: This logs sensitive token information to console for debugging purposes.
-     * In production environments, consider disabling this or filtering console logs.
-     * @param token - The JWT access token
-     */
-    private decodeAndLogToken;
-    /**
-     * Log all user claims for debugging
-     * @param user - User info from Auth0
-     */
-    private logUserClaims;
-    /**
-     * Log standard OIDC claims
-     * @param user - User info from Auth0
-     */
-    private logStandardClaims;
-    /**
-     * Log claims with consistent formatting
-     * @param header - Section header to display
-     * @param claims - Array of claim keys to log
-     * @param user - User info object
-     */
-    private logClaims;
-    /**
-     * Get custom namespaced claims from user info
-     * @param user - User info object
-     * @returns Array of custom claim keys
-     */
-    private getCustomClaims;
-    /**
-     * Get additional non-namespaced claims from user info
-     * @param user - User info object
-     * @returns Array of additional claim keys
-     */
-    private getAdditionalClaims;
-    /**
-     * Check if a claim key is namespaced
-     * @param key - Claim key to check
-     * @returns True if the key starts with http:// or https://
-     */
-    private isNamespacedClaim;
-    /**
-     * Logout user and clear authentication state
-     * Redirects to Auth0 logout endpoint and clears local state
-     */
-    logout(): Promise<void>;
-    /**
-     * Get current access token from storage or Auth0 client
-     * @returns string | null - Access token or null if not authenticated
-     */
-    getToken(): Promise<string | null>;
-    /**
-     * Get current access token synchronously from storage only
-     * Use this for synchronous operations like interceptors
-     * @returns string | null - Access token or null if not authenticated
-     */
-    getTokenSync(): string | null;
-    /**
-     * Set access token in storage and emit event for MicroApps
-     * @param token - Access token to store
-     */
-    private setToken;
-    /**
-     * Check if user is authenticated
-     * @returns boolean - True if user has valid token
-     */
-    isAuthenticated(): Promise<boolean>;
-    /**
-     * Check if user is authenticated synchronously
-     * Only checks storage, doesn't verify with Auth0
-     * @returns boolean - True if user has token in storage
-     */
-    isAuthenticatedSync(): boolean;
-    /**
-     * Get current user information
-     * @returns UserInfo | null - Current user or null if not authenticated
-     */
-    getUser(): UserInfo | null;
-    /**
-     * Get simplified user data from token
-     * Extracts user details, role, and organization from ID token claims
-     * Checks both top-level claims and namespaced custom claims
-     * @returns UserData | null - Simplified user data or null if not authenticated
-     */
-    getUserData(): UserData | null;
-    /**
-     * Extract claim value from user info, checking both direct properties and namespaced custom claims
-     * @param userInfo - User info object
-     * @param claimNames - Single claim name or array of claim names to search for
-     * @param defaultValue - Default value if claim is not found
-     * @returns Extracted claim value or default value
-     */
-    private extractClaimValue;
-    /**
-     * Get user information from storage
-     * @returns UserInfo | null - Stored user info or null
-     */
-    private getUserInfoFromStorage;
-    /**
-     * Set user information in storage, update observable and emit event for MicroApps
-     * Logs all Auth0 claims for debugging
-     * @param userInfo - User information to store
-     */
-    private setUserInfo;
-    /**
-     * Emit authentication event for MicroApps to consume
-     * Events are emitted via EventBus for cross-MFE communication
-     * @param eventType - Type of authentication event
-     * @param payload - Event payload
-     */
-    private emitAuthEvent;
-}
-/**
- * Factory function to get the singleton AuthService instance
- * Use this in your application providers to ensure singleton behavior across MFEs
- *
- * Lazy initialization ensures Auth0 can be configured before service creation
- *
- * @example
- * ```typescript
- * // In app.config.ts or app.module.ts
- * import { AuthService, getAuthService, EventBusService, getEventBusService } from '@opensourcekd/ng-common-libs';
- *
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     { provide: EventBusService, useFactory: getEventBusService },
- *     { provide: AuthService, useFactory: getAuthService }
- *   ]
- * };
- * ```
- *
- * @returns The singleton AuthService instance
- */
-declare function getAuthService(): AuthService;
-
-/**
- * Auth0 Configuration
- * Centralized configuration for Auth0 integration
- *
- * Environment variables are typically set in consuming applications
- * Default values are provided for development/testing
- */
-/**
- * Auth0 client configuration
- * Override these values in your consuming application by setting them before importing AuthService
- *
- * Note: redirectUri defaults to window.location.origin (base URL without path).
- * Auth0 will redirect back to this URL after authentication.
- * You can override this to a specific callback URL (e.g., '/auth-callback') using configureAuth0().
- */
-declare const AUTH0_CONFIG: {
-    domain: string;
-    clientId: string;
-    redirectUri: string;
-    logoutUri: string;
-    audience: string;
-    scope: string;
-    connection: string | undefined;
-};
-/**
- * Storage configuration
- * Controls where sensitive data is stored
- */
-declare const STORAGE_CONFIG: {
-    TOKEN_STORAGE: "localStorage" | "sessionStorage";
-    USER_INFO_STORAGE: "localStorage" | "sessionStorage";
-};
-/**
- * Storage keys for auth data
- */
-declare const STORAGE_KEYS: {
-    ACCESS_TOKEN: string;
-    USER_INFO: string;
-};
-/**
- * Helper functions for storage operations
- * These work with both localStorage and sessionStorage
- */
-/**
- * Get item from storage
- * @param key - Storage key
- * @param storageType - Type of storage to use
- * @returns Stored value or null
- */
-declare function getStorageItem(key: string, storageType?: 'localStorage' | 'sessionStorage'): string | null;
-/**
- * Set item in storage
- * @param key - Storage key
- * @param value - Value to store
- * @param storageType - Type of storage to use
- */
-declare function setStorageItem(key: string, value: string, storageType?: 'localStorage' | 'sessionStorage'): void;
-/**
- * Remove item from storage
- * @param key - Storage key
- * @param storageType - Type of storage to use
- */
-declare function removeStorageItem(key: string, storageType?: 'localStorage' | 'sessionStorage'): void;
-/**
- * Configure Auth0 settings (OPTIONAL)
- * Call this function in your consuming application to override default Auth0 configuration.
- * Only the values you provide will be overridden; all other defaults remain unchanged.
- *
- * Note: This function is optional. If not called, default values will be used.
- *
- * @param config - Partial Auth0 configuration object with values to override
- *
- * @example
- * ```typescript
- * import { configureAuth0 } from '@opensourcekd/ng-common-libs';
- *
- * // Only override specific values - others keep their defaults
- * configureAuth0({
- *   domain: 'your-domain.auth0.com',
- *   clientId: 'your-client-id',
- *   audience: 'https://your-api.com'
- *   // redirectUri, logoutUri, scope, etc. will use defaults
- * });
- *
- * // Or override just redirectUri to use a specific callback page
- * configureAuth0({
- *   redirectUri: window.location.origin + '/auth-callback'
- * });
- * ```
- */
-declare function configureAuth0(config: Partial<typeof AUTH0_CONFIG>): void;
-
-export { AUTH0_CONFIG, AuthService, EventBusService, STORAGE_CONFIG, STORAGE_KEYS, configureAuth0, getAuthService, getEventBusService, getStorageItem, removeStorageItem, setStorageItem };
-export type { UserData, UserInfo };