@opensourcekd/ng-common-libs 1.1.8

package/dist/angular/index.d.ts

@@ -0,0 +1,691 @@
+import { Observable } from 'rxjs';
+import { CanActivateFn } from '@angular/router';
+import { HttpInterceptorFn, HttpErrorResponse } from '@angular/common/http';
+
+/**
+ * Event payload interface
+ */
+interface EventPayload<T = any> {
+    type: string;
+    data: T;
+    timestamp?: number;
+}
+/**
+ * EventBus - A centralized event bus for application-wide communication
+ * Framework-agnostic implementation using only RxJS
+ *
+ * @example
+ * ```typescript
+ * // Create an instance
+ * const eventBus = new EventBus();
+ *
+ * // Emit an event
+ * eventBus.emit('user:login', { userId: '123', username: 'john' });
+ *
+ * // Subscribe to an event
+ * eventBus.on('user:login').subscribe(data => {
+ *   console.log('User logged in:', data);
+ * });
+ * ```
+ */
+declare class EventBus {
+    private eventSubject;
+    /**
+     * Emit an event with optional data
+     * @param eventType - The type/name of the event
+     * @param data - Optional data to send with the event
+     */
+    emit<T = any>(eventType: string, data?: T): void;
+    /**
+     * Subscribe to a specific event type
+     * @param eventType - The type/name of the event to listen for
+     * @returns Observable that emits the event data
+     */
+    on<T = any>(eventType: string): Observable<T>;
+    /**
+     * Subscribe to multiple event types
+     * @param eventTypes - Array of event types to listen for
+     * @returns Observable that emits the full event payload
+     */
+    onMultiple(eventTypes: string[]): Observable<EventPayload>;
+    /**
+     * Subscribe to all events
+     * @returns Observable that emits all event payloads
+     */
+    onAll(): Observable<EventPayload>;
+}
+
+/**
+ * NgEventEmitter - Angular service wrapper for EventBus
+ * Provides Angular dependency injection support for the framework-agnostic EventBus
+ *
+ * @example
+ * ```typescript
+ * import { Component, inject } from '@angular/core';
+ * import { NgEventEmitter } from 'common-libs';
+ *
+ * @Component({
+ *   selector: 'app-example',
+ *   template: '...'
+ * })
+ * export class ExampleComponent {
+ *   private eventEmitter = inject(NgEventEmitter);
+ *
+ *   ngOnInit() {
+ *     this.eventEmitter.on('user:login').subscribe(data => {
+ *       console.log('User logged in:', data);
+ *     });
+ *   }
+ *
+ *   login() {
+ *     this.eventEmitter.emit('user:login', { userId: '123' });
+ *   }
+ * }
+ * ```
+ */
+declare class NgEventEmitter extends EventBus {
+    constructor();
+}
+
+/**
+ * Token configuration interface
+ */
+interface TokenConfig {
+    tokenKey?: string;
+    refreshTokenKey?: string;
+    useSessionStorage?: boolean;
+}
+/**
+ * TokenManager - Manages authentication tokens
+ * Framework-agnostic implementation using browser storage APIs
+ * Handles storage, retrieval, and validation of JWT tokens
+ *
+ * @example
+ * ```typescript
+ * const tokenManager = new TokenManager();
+ *
+ * // Store a token
+ * tokenManager.setToken('your-jwt-token');
+ *
+ * // Check if authenticated
+ * if (tokenManager.isAuthenticated()) {
+ *   const userData = tokenManager.getUserFromToken();
+ * }
+ * ```
+ */
+declare class TokenManager {
+    private TOKEN_KEY;
+    private REFRESH_TOKEN_KEY;
+    private useSessionStorage;
+    /**
+     * Configure token manager
+     */
+    configure(config: TokenConfig): void;
+    /**
+     * Get the storage mechanism based on configuration
+     */
+    private getStorage;
+    /**
+     * Set authentication token
+     */
+    setToken(token: string): void;
+    /**
+     * Get authentication token
+     */
+    getToken(): string | null;
+    /**
+     * Remove authentication token
+     */
+    removeToken(): void;
+    /**
+     * Set refresh token
+     */
+    setRefreshToken(token: string): void;
+    /**
+     * Get refresh token
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Remove refresh token
+     */
+    removeRefreshToken(): void;
+    /**
+     * Clear all tokens
+     */
+    clearTokens(): void;
+    /**
+     * Check if token exists
+     */
+    hasToken(): boolean;
+    /**
+     * Decode JWT token (without verification)
+     * @param token - JWT token to decode
+     * @returns Decoded token payload or null if invalid
+     */
+    decodeToken(token?: string): any;
+    /**
+     * Check if token is expired
+     * @param token - Optional token to check (defaults to stored token)
+     * @returns true if token is expired or invalid
+     */
+    isTokenExpired(token?: string): boolean;
+    /**
+     * Check if user is authenticated (has valid, non-expired token)
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get token expiration date
+     */
+    getTokenExpirationDate(token?: string): Date | null;
+    /**
+     * Get user data from token
+     */
+    getUserFromToken(token?: string): any;
+}
+
+/**
+ * TokenService - Angular service wrapper for TokenManager
+ * Provides Angular dependency injection support for the framework-agnostic TokenManager
+ *
+ * @example
+ * ```typescript
+ * import { Component, inject } from '@angular/core';
+ * import { TokenService } from 'common-libs';
+ *
+ * export class AuthService {
+ *   private tokenService = inject(TokenService);
+ *
+ *   login(token: string) {
+ *     this.tokenService.setToken(token);
+ *   }
+ *
+ *   isAuthenticated(): boolean {
+ *     return this.tokenService.isAuthenticated();
+ *   }
+ * }
+ * ```
+ */
+declare class TokenService extends TokenManager {
+    constructor();
+}
+
+/**
+ * StorageManager - Type-safe wrapper for browser storage
+ * Framework-agnostic implementation using browser storage APIs
+ * Provides JSON serialization/deserialization and error handling
+ *
+ * @example
+ * ```typescript
+ * const storage = new StorageManager();
+ *
+ * // Store data
+ * storage.setLocal('user-prefs', { theme: 'dark', lang: 'en' });
+ *
+ * // Retrieve data
+ * const prefs = storage.getLocal('user-prefs');
+ *
+ * // With expiration
+ * storage.setWithExpiration('temp-data', someData, 3600000); // 1 hour
+ * ```
+ */
+declare class StorageManager {
+    /**
+     * Set item in localStorage with JSON serialization
+     */
+    setLocal<T>(key: string, value: T): boolean;
+    /**
+     * Get item from localStorage with JSON deserialization
+     */
+    getLocal<T>(key: string, defaultValue?: T): T | null;
+    /**
+     * Remove item from localStorage
+     */
+    removeLocal(key: string): void;
+    /**
+     * Clear all localStorage items
+     */
+    clearLocal(): void;
+    /**
+     * Check if key exists in localStorage
+     */
+    hasLocal(key: string): boolean;
+    /**
+     * Get all localStorage keys
+     */
+    getLocalKeys(): string[];
+    /**
+     * Set item in sessionStorage with JSON serialization
+     */
+    setSession<T>(key: string, value: T): boolean;
+    /**
+     * Get item from sessionStorage with JSON deserialization
+     */
+    getSession<T>(key: string, defaultValue?: T): T | null;
+    /**
+     * Remove item from sessionStorage
+     */
+    removeSession(key: string): void;
+    /**
+     * Clear all sessionStorage items
+     */
+    clearSession(): void;
+    /**
+     * Check if key exists in sessionStorage
+     */
+    hasSession(key: string): boolean;
+    /**
+     * Get all sessionStorage keys
+     */
+    getSessionKeys(): string[];
+    /**
+     * Set item with expiration time
+     * @param key - Storage key
+     * @param value - Value to store
+     * @param expirationMs - Expiration time in milliseconds
+     * @param useSession - Use sessionStorage instead of localStorage
+     */
+    setWithExpiration<T>(key: string, value: T, expirationMs: number, useSession?: boolean): boolean;
+    /**
+     * Get item with expiration check
+     * Returns null if item is expired
+     */
+    getWithExpiration<T>(key: string, useSession?: boolean): T | null;
+}
+
+/**
+ * StorageService - Angular service wrapper for StorageManager
+ * Provides Angular dependency injection support for the framework-agnostic StorageManager
+ *
+ * @example
+ * ```typescript
+ * import { Component, inject } from '@angular/core';
+ * import { StorageService } from 'common-libs';
+ *
+ * export class UserPreferencesService {
+ *   private storage = inject(StorageService);
+ *
+ *   savePreferences(prefs: any) {
+ *     this.storage.setLocal('user-prefs', prefs);
+ *   }
+ *
+ *   getPreferences() {
+ *     return this.storage.getLocal('user-prefs');
+ *   }
+ * }
+ * ```
+ */
+declare class StorageService extends StorageManager {
+    constructor();
+}
+
+/**
+ * Log level enum
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+/**
+ * Logger configuration
+ */
+interface LoggerConfig {
+    level?: LogLevel;
+    enableTimestamp?: boolean;
+    enableStackTrace?: boolean;
+    prefix?: string;
+}
+/**
+ * Logger - Centralized logging utility
+ * Framework-agnostic implementation using browser console APIs
+ * Supports different log levels and can be configured globally
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger();
+ *
+ * // Configure
+ * logger.configure({
+ *   level: LogLevel.DEBUG,
+ *   enableTimestamp: true,
+ *   prefix: 'MyApp'
+ * });
+ *
+ * // Use
+ * logger.info('User logged in', { userId: '123' });
+ * logger.error('Failed to load data', error);
+ * ```
+ */
+declare class Logger {
+    private config;
+    /**
+     * Configure the logger
+     */
+    configure(config: LoggerConfig): void;
+    /**
+     * Set log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get current log level
+     */
+    getLevel(): LogLevel;
+    /**
+     * Format log message with timestamp and prefix
+     */
+    private formatMessage;
+    /**
+     * Check if log level should be logged
+     */
+    private shouldLog;
+    /**
+     * Log debug message
+     */
+    debug(message: string, ...args: any[]): void;
+    /**
+     * Log info message
+     */
+    info(message: string, ...args: any[]): void;
+    /**
+     * Log warning message
+     */
+    warn(message: string, ...args: any[]): void;
+    /**
+     * Log error message
+     */
+    error(message: string, error?: any, ...args: any[]): void;
+    /**
+     * Log a group of messages
+     */
+    group(label: string, callback: () => void): void;
+    /**
+     * Log a collapsed group of messages
+     */
+    groupCollapsed(label: string, callback: () => void): void;
+    /**
+     * Log a table (useful for arrays of objects)
+     */
+    table(data: any, columns?: string[]): void;
+    /**
+     * Log execution time of a function
+     */
+    time<T>(label: string, fn: () => Promise<T> | T): Promise<T>;
+}
+
+/**
+ * LoggerService - Angular service wrapper for Logger
+ * Provides Angular dependency injection support for the framework-agnostic Logger
+ *
+ * @example
+ * ```typescript
+ * import { Component, inject } from '@angular/core';
+ * import { LoggerService, LogLevel } from 'common-libs';
+ *
+ * export class MyService {
+ *   private logger = inject(LoggerService);
+ *
+ *   constructor() {
+ *     this.logger.configure({
+ *       level: LogLevel.DEBUG,
+ *       prefix: 'MyApp'
+ *     });
+ *   }
+ *
+ *   doSomething() {
+ *     this.logger.info('Doing something');
+ *   }
+ * }
+ * ```
+ */
+declare class LoggerService extends Logger {
+    constructor();
+}
+
+/**
+ * PermissionService - Manages user permissions and roles
+ */
+declare class PermissionService {
+    private tokenService;
+    /**
+     * Check if user has a specific permission
+     */
+    hasPermission(permission: string): boolean;
+    /**
+     * Check if user has any of the specified permissions
+     */
+    hasAnyPermission(permissions: string[]): boolean;
+    /**
+     * Check if user has all of the specified permissions
+     */
+    hasAllPermissions(permissions: string[]): boolean;
+    /**
+     * Check if user has a specific role
+     */
+    hasRole(role: string): boolean;
+    /**
+     * Check if user has any of the specified roles
+     */
+    hasAnyRole(roles: string[]): boolean;
+    /**
+     * Check if user has all of the specified roles
+     */
+    hasAllRoles(roles: string[]): boolean;
+    /**
+     * Get all user permissions
+     */
+    getPermissions(): string[];
+    /**
+     * Get all user roles
+     */
+    getRoles(): string[];
+    /**
+     * Get user ID from token
+     */
+    getUserId(): string | null;
+    /**
+     * Get username from token
+     */
+    getUsername(): string | null;
+    /**
+     * Get user email from token
+     */
+    getUserEmail(): string | null;
+}
+
+/**
+ * Auth guard configuration
+ */
+interface AuthGuardConfig {
+    redirectUrl?: string;
+    checkExpiration?: boolean;
+}
+/**
+ * Factory function to create an auth guard with configuration
+ *
+ * @example
+ * ```typescript
+ * // In routes
+ * {
+ *   path: 'dashboard',
+ *   component: DashboardComponent,
+ *   canActivate: [createAuthGuard({ redirectUrl: '/login' })]
+ * }
+ * ```
+ */
+declare function createAuthGuard(config?: AuthGuardConfig): CanActivateFn;
+/**
+ * Default auth guard - redirects to '/login' if not authenticated
+ */
+declare const authGuard: CanActivateFn;
+/**
+ * Permission-based guard factory
+ * Checks if user has required permissions from token
+ *
+ * @example
+ * ```typescript
+ * {
+ *   path: 'admin',
+ *   component: AdminComponent,
+ *   canActivate: [createPermissionGuard(['admin', 'editor'])]
+ * }
+ * ```
+ */
+declare function createPermissionGuard(requiredPermissions: string[], config?: AuthGuardConfig): CanActivateFn;
+/**
+ * Role-based guard factory
+ * Checks if user has required role from token
+ *
+ * @example
+ * ```typescript
+ * {
+ *   path: 'admin',
+ *   component: AdminComponent,
+ *   canActivate: [createRoleGuard(['admin'])]
+ * }
+ * ```
+ */
+declare function createRoleGuard(requiredRoles: string[], config?: AuthGuardConfig): CanActivateFn;
+
+/**
+ * Auth interceptor configuration
+ */
+interface AuthInterceptorConfig {
+    headerName?: string;
+    tokenPrefix?: string;
+    excludedUrls?: string[];
+}
+/**
+ * Configure the auth interceptor
+ */
+declare function configureAuthInterceptor(config: AuthInterceptorConfig): void;
+/**
+ * Auth Interceptor - Automatically adds authentication token to HTTP requests
+ *
+ * @example
+ * ```typescript
+ * // In app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHttpClient(
+ *       withInterceptors([authInterceptor])
+ *     )
+ *   ]
+ * };
+ * ```
+ */
+declare const authInterceptor: HttpInterceptorFn;
+
+/**
+ * Error handling configuration
+ */
+interface ErrorHandlingConfig {
+    enableLogging?: boolean;
+    retryAttempts?: number;
+    retryDelay?: number;
+    retryStatusCodes?: number[];
+    excludedUrls?: string[];
+}
+/**
+ * Configure the error handling interceptor
+ */
+declare function configureErrorHandling(config: ErrorHandlingConfig): void;
+/**
+ * Error handling interceptor - Handles HTTP errors and retries
+ *
+ * @example
+ * ```typescript
+ * // In app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHttpClient(
+ *       withInterceptors([errorHandlingInterceptor])
+ *     )
+ *   ]
+ * };
+ *
+ * // Configure retry behavior
+ * configureErrorHandling({
+ *   retryAttempts: 3,
+ *   retryDelay: 2000,
+ *   retryStatusCodes: [500, 502, 503]
+ * });
+ * ```
+ */
+declare const errorHandlingInterceptor: HttpInterceptorFn;
+/**
+ * HTTP Error class with additional context
+ */
+declare class HttpError extends Error {
+    status: number;
+    statusText: string;
+    url: string;
+    originalError: HttpErrorResponse;
+    constructor(status: number, statusText: string, url: string, originalError: HttpErrorResponse);
+}
+/**
+ * Parse HTTP error and return user-friendly message
+ */
+declare function parseHttpError(error: HttpErrorResponse): string;
+/**
+ * Check if error is a network error
+ */
+declare function isNetworkError(error: HttpErrorResponse): boolean;
+/**
+ * Check if error is a server error (5xx)
+ */
+declare function isServerError(error: HttpErrorResponse): boolean;
+/**
+ * Check if error is a client error (4xx)
+ */
+declare function isClientError(error: HttpErrorResponse): boolean;
+
+/**
+ * Cache configuration
+ */
+interface CacheConfig {
+    enabled?: boolean;
+    maxAge?: number;
+    excludedUrls?: string[];
+    cacheableUrls?: string[];
+    cacheMethods?: string[];
+}
+/**
+ * Configure the caching interceptor
+ */
+declare function configureCaching(config: CacheConfig): void;
+/**
+ * Clear all cached entries
+ */
+declare function clearCache(): void;
+/**
+ * Clear cache entry for specific URL
+ */
+declare function clearCacheEntry(url: string): void;
+/**
+ * Caching interceptor - Caches HTTP GET requests
+ *
+ * @example
+ * ```typescript
+ * // In app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHttpClient(
+ *       withInterceptors([cachingInterceptor])
+ *     )
+ *   ]
+ * };
+ *
+ * // Configure caching
+ * configureCaching({
+ *   enabled: true,
+ *   maxAge: 300000, // 5 minutes
+ *   cacheableUrls: ['/api/users', '/api/products']
+ * });
+ * ```
+ */
+declare const cachingInterceptor: HttpInterceptorFn;
+
+export { HttpError, LogLevel, LoggerService, NgEventEmitter, PermissionService, StorageService, TokenService, authGuard, authInterceptor, cachingInterceptor, clearCache, clearCacheEntry, configureAuthInterceptor, configureCaching, configureErrorHandling, createAuthGuard, createPermissionGuard, createRoleGuard, errorHandlingInterceptor, isClientError, isNetworkError, isServerError, parseHttpError };
+export type { AuthGuardConfig, AuthInterceptorConfig, CacheConfig, ErrorHandlingConfig, LoggerConfig, TokenConfig };