valtech-components 2.0.452 → 2.0.453

package/lib/services/auth/types.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Tipos e interfaces para el servicio de autenticación de Valtech.
+ * Alineados con el backend AuthV2.
+ */
+/**
+ * Configuración para el servicio de autenticación.
+ */
+export interface ValtechAuthConfig {
+    /** URL base de la API (ej: 'https://api.myvaltech.com') */
+    apiUrl: string;
+    /** Prefijo para endpoints de auth (default: '/v2/auth') */
+    authPrefix?: string;
+    /** Prefijo para las claves de localStorage (default: 'valtech_auth_') */
+    storagePrefix?: string;
+    /** Tiempo antes de expiración para refrescar token en segundos (default: 60) */
+    refreshBeforeExpiry?: number;
+    /** Habilitar sincronización entre pestañas (default: true) */
+    enableTabSync?: boolean;
+    /** Ruta de redirección cuando no autenticado (default: '/login') */
+    loginRoute?: string;
+    /** Ruta de redirección cuando ya autenticado (default: '/') */
+    homeRoute?: string;
+    /** Ruta para acceso denegado (default: '/unauthorized') */
+    unauthorizedRoute?: string;
+    /** Habilitar integración con FirebaseService (default: false) */
+    enableFirebaseIntegration?: boolean;
+}
+/**
+ * Estado completo de autenticación.
+ */
+export interface AuthState {
+    /** Usuario está autenticado */
+    isAuthenticated: boolean;
+    /** Estado de carga inicial */
+    isLoading: boolean;
+    /** Token de acceso actual */
+    accessToken: string | null;
+    /** Token de refresco actual */
+    refreshToken: string | null;
+    /** ID del usuario */
+    userId: string | null;
+    /** Email del usuario */
+    email: string | null;
+    /** Roles del usuario */
+    roles: string[];
+    /** Permisos del usuario (formato 'resource:action') */
+    permissions: string[];
+    /** Usuario es super admin */
+    isSuperAdmin: boolean;
+    /** Timestamp de expiración del accessToken (ms) */
+    expiresAt: number | null;
+    /** Error de autenticación (si existe) */
+    error: AuthError | null;
+}
+/**
+ * Información del usuario autenticado.
+ */
+export interface AuthUser {
+    userId: string;
+    email: string;
+    name?: string;
+    roles: string[];
+    permissions: string[];
+    isSuperAdmin: boolean;
+}
+/**
+ * Error de autenticación.
+ */
+export interface AuthError {
+    code: string;
+    message: string;
+}
+/**
+ * Estado inicial de autenticación.
+ */
+export declare const INITIAL_AUTH_STATE: AuthState;
+/** Métodos de MFA soportados */
+export type MFAMethod = 'EMAIL' | 'SMS';
+/**
+ * Estado de MFA pendiente.
+ */
+export interface MFAPendingState {
+    required: boolean;
+    mfaToken: string | null;
+    method: MFAMethod | null;
+}
+/**
+ * Estado inicial de MFA.
+ */
+export declare const INITIAL_MFA_STATE: MFAPendingState;
+/**
+ * Resultado de setup de MFA.
+ */
+export interface MFASetupResult {
+    codeSent: boolean;
+    message: string;
+}
+/**
+ * Estado de MFA del usuario.
+ */
+export interface MFAStatus {
+    enabled: boolean;
+    method: MFAMethod | null;
+}
+/**
+ * Request para signup (registro).
+ */
+export interface SignupRequest {
+    email: string;
+    password: string;
+    name: string;
+    phone?: string;
+}
+/**
+ * Response de signup (registro).
+ */
+export interface SignupResponse {
+    operationId: string;
+    userId: string;
+    message: string;
+}
+/**
+ * Request para verificar email.
+ */
+export interface VerifyEmailRequest {
+    email: string;
+    code: string;
+}
+/**
+ * Response de verificación de email.
+ * Si es exitoso, incluye tokens para auto-login.
+ */
+export interface VerifyEmailResponse {
+    operationId: string;
+    verified: boolean;
+    accessToken?: string;
+    refreshToken?: string;
+    firebaseToken?: string;
+    expiresIn?: number;
+    tokenType?: string;
+}
+/**
+ * Request para reenviar código de verificación.
+ */
+export interface ResendCodeRequest {
+    email: string;
+    type: 'EMAIL_VERIFY' | 'PASSWORD_RESET';
+}
+/**
+ * Response de reenvío de código.
+ */
+export interface ResendCodeResponse {
+    operationId: string;
+    sent: boolean;
+}
+/**
+ * Request para signin.
+ */
+export interface SigninRequest {
+    email: string;
+    password: string;
+}
+/**
+ * Response de signin.
+ */
+export interface SigninResponse {
+    operationId: string;
+    accessToken?: string;
+    refreshToken?: string;
+    firebaseToken?: string;
+    expiresIn?: number;
+    tokenType?: string;
+    mfaRequired?: boolean;
+    mfaToken?: string;
+    mfaMethod?: MFAMethod;
+    roles?: string[];
+    permissions?: string[];
+}
+/**
+ * Request para verificar MFA.
+ */
+export interface MFAVerifyRequest {
+    mfaToken: string;
+    code: string;
+}
+/**
+ * Response de verificar MFA.
+ */
+export interface MFAVerifyResponse {
+    operationId: string;
+    accessToken: string;
+    refreshToken: string;
+    firebaseToken?: string;
+    expiresIn: number;
+    tokenType: string;
+    roles?: string[];
+    permissions?: string[];
+}
+/**
+ * Request para refrescar token.
+ */
+export interface RefreshRequest {
+    refreshToken: string;
+}
+/**
+ * Response de refrescar token.
+ */
+export interface RefreshResponse {
+    operationId: string;
+    accessToken: string;
+    expiresIn: number;
+}
+/**
+ * Request para logout.
+ */
+export interface LogoutRequest {
+    refreshToken: string;
+}
+/**
+ * Response de logout.
+ */
+export interface LogoutResponse {
+    operationId: string;
+    success: boolean;
+}
+/**
+ * Response de obtener permisos.
+ */
+export interface GetPermissionsResponse {
+    operationId: string;
+    roles: string[];
+    permissions: string[];
+    isSuperAdmin: boolean;
+}
+/**
+ * Request para setup de MFA.
+ */
+export interface MFASetupRequest {
+    method: MFAMethod;
+    phone?: string;
+}
+/**
+ * Response de setup de MFA.
+ */
+export interface MFASetupResponse {
+    operationId: string;
+    codeSent: boolean;
+    message: string;
+}
+/**
+ * Request para confirmar MFA.
+ */
+export interface MFAConfirmRequest {
+    code: string;
+}
+/**
+ * Response de confirmar MFA.
+ */
+export interface MFAConfirmResponse {
+    operationId: string;
+    mfaEnabled: boolean;
+    method: MFAMethod;
+}
+/**
+ * Request para deshabilitar MFA.
+ */
+export interface MFADisableRequest {
+    password: string;
+}
+/**
+ * Response de deshabilitar MFA.
+ */
+export interface MFADisableResponse {
+    operationId: string;
+    mfaDisabled: boolean;
+}
+/** Tipos de eventos de sincronización entre pestañas */
+export type AuthSyncEventType = 'LOGIN' | 'LOGOUT' | 'TOKEN_REFRESH' | 'PERMISSIONS_UPDATE';
+/**
+ * Evento de sincronización entre pestañas.
+ */
+export interface AuthSyncEvent {
+    type: AuthSyncEventType;
+    timestamp: number;
+    payload?: {
+        accessToken?: string;
+        expiresAt?: number;
+    };
+}
+/**
+ * Claims del JWT de acceso.
+ */
+export interface JWTClaims {
+    /** User ID */
+    uid: string;
+    /** Email */
+    email: string;
+    /** Session ID */
+    sid?: string;
+    /** Issued at */
+    iat: number;
+    /** Expiration */
+    exp: number;
+}
+/**
+ * Datos persistidos en storage.
+ */
+export interface StoredAuthState {
+    accessToken: string;
+    refreshToken: string;
+    roles: string[];
+    permissions: string[];
+    isSuperAdmin: boolean;
+    expiresAt?: number;
+}

package/lib/services/firebase/config.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Firebase Configuration
+ *
+ * Configuración e inicialización de Firebase para aplicaciones Angular.
+ * Usa provideValtechFirebase() en el bootstrap de tu aplicación.
+ */
+import { EnvironmentProviders, InjectionToken } from '@angular/core';
+import { ValtechFirebaseConfig } from './types';
+/**
+ * Token de inyección para la configuración de Firebase.
+ * Usado internamente por los servicios de Firebase.
+ */
+export declare const VALTECH_FIREBASE_CONFIG: InjectionToken<ValtechFirebaseConfig>;
+/**
+ * Provee Firebase a la aplicación Angular.
+ *
+ * @param config - Configuración de Firebase
+ * @returns EnvironmentProviders para usar en bootstrapApplication
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * import { bootstrapApplication } from '@angular/platform-browser';
+ * import { provideValtechFirebase } from 'valtech-components';
+ * import { environment } from './environments/environment';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideValtechFirebase({
+ *       firebase: environment.firebase,
+ *       persistence: true,
+ *       emulator: environment.useEmulators ? {
+ *         firestore: { host: 'localhost', port: 8080 },
+ *         auth: { host: 'localhost', port: 9099 },
+ *         storage: { host: 'localhost', port: 9199 },
+ *       } : undefined,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export declare function provideValtechFirebase(config: ValtechFirebaseConfig): EnvironmentProviders;
+/**
+ * Verifica si los emuladores están configurados.
+ *
+ * @param config - Configuración de Firebase
+ * @returns true si hay al menos un emulador configurado
+ */
+export declare function hasEmulators(config: ValtechFirebaseConfig): boolean;

package/lib/services/firebase/firebase.service.d.ts

@@ -0,0 +1,140 @@
+import { Auth, UserCredential } from '@angular/fire/auth';
+import { Observable } from 'rxjs';
+import { FirebaseUser, SessionState, ValtechFirebaseConfig } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Servicio de autenticación de Firebase.
+ *
+ * Este servicio NO maneja el login de usuarios directamente.
+ * En su lugar, trabaja con Custom Tokens generados por tu backend.
+ *
+ * @example
+ * ```typescript
+ * // Después de autenticarte con tu backend (ej: Cognito)
+ * @Component({...})
+ * export class LoginComponent {
+ *   private authService = inject(AuthService);     // Tu servicio de auth
+ *   private firebase = inject(FirebaseService);    // Este servicio
+ *
+ *   async login(email: string, password: string) {
+ *     // 1. Autenticar con tu backend
+ *     const response = await this.authService.login(email, password);
+ *
+ *     // 2. El backend devuelve un Firebase Custom Token
+ *     if (response.firebaseToken) {
+ *       await this.firebase.signInWithCustomToken(response.firebaseToken);
+ *     }
+ *
+ *     // Ahora el usuario puede acceder a Firestore, Storage, etc.
+ *   }
+ *
+ *   async logout() {
+ *     await this.authService.logout();
+ *     await this.firebase.signOut();
+ *   }
+ * }
+ * ```
+ */
+export declare class FirebaseService {
+    private auth;
+    private config;
+    /** Estado interno de la sesión */
+    private sessionState;
+    /** Estado actual de la sesión como Observable */
+    readonly state$: Observable<SessionState>;
+    /** Usuario actual de Firebase como Observable */
+    readonly user$: Observable<FirebaseUser | null>;
+    /** Indica si el usuario está autenticado en Firebase */
+    readonly isAuthenticated$: Observable<boolean>;
+    constructor(auth: Auth, config: ValtechFirebaseConfig);
+    /**
+     * Autentica al usuario con un Custom Token generado por el backend.
+     *
+     * @param token - Firebase Custom Token generado por tu backend
+     * @returns UserCredential con la información del usuario
+     * @throws Error si el token es inválido o expiró
+     *
+     * @example
+     * ```typescript
+     * // Después de login exitoso con tu backend
+     * const { firebaseToken } = await backendAuth.login(email, password);
+     * await firebaseService.signInWithCustomToken(firebaseToken);
+     * ```
+     */
+    signInWithCustomToken(token: string): Promise<UserCredential>;
+    /**
+     * Cierra la sesión de Firebase.
+     * Llamar junto con el logout de tu sistema de autenticación principal.
+     *
+     * @example
+     * ```typescript
+     * async logout() {
+     *   await this.backendAuth.logout();    // Tu auth
+     *   await this.firebase.signOut();       // Firebase
+     * }
+     * ```
+     */
+    signOut(): Promise<void>;
+    /**
+     * Obtiene el usuario actual de Firebase (síncrono).
+     * Retorna null si no hay usuario autenticado.
+     */
+    get currentUser(): FirebaseUser | null;
+    /**
+     * Obtiene el UID del usuario actual.
+     * Retorna null si no hay usuario autenticado.
+     */
+    get uid(): string | null;
+    /**
+     * Indica si hay un usuario autenticado actualmente.
+     */
+    get isAuthenticated(): boolean;
+    /**
+     * Obtiene el ID Token de Firebase para el usuario actual.
+     * Útil para validar el usuario en tu backend.
+     *
+     * @param forceRefresh - Si true, fuerza la renovación del token
+     * @returns ID Token o null si no hay usuario
+     */
+    getIdToken(forceRefresh?: boolean): Promise<string | null>;
+    /**
+     * Obtiene los claims personalizados del token del usuario.
+     * Los claims son establecidos por tu backend al crear el Custom Token.
+     *
+     * @returns Objeto con los claims o vacío si no hay usuario
+     */
+    getClaims(): Promise<Record<string, unknown>>;
+    /**
+     * Verifica si el usuario tiene un rol específico.
+     * El rol debe estar definido en los claims del Custom Token.
+     *
+     * @param role - Nombre del rol a verificar
+     * @returns true si el usuario tiene el rol
+     */
+    hasRole(role: string): Promise<boolean>;
+    /**
+     * Espera a que el estado de autenticación esté determinado.
+     * Útil en guards o al inicializar la app.
+     *
+     * @returns Usuario actual o null
+     */
+    waitForAuth(): Promise<FirebaseUser | null>;
+    /**
+     * Obtiene la configuración actual de Firebase.
+     */
+    getConfig(): ValtechFirebaseConfig;
+    /**
+     * Indica si los emuladores están habilitados.
+     */
+    isUsingEmulators(): boolean;
+    /**
+     * Mapea un User de Firebase a nuestra interface FirebaseUser
+     */
+    private mapUser;
+    /**
+     * Convierte errores de Firebase a mensajes en español
+     */
+    private getErrorMessage;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FirebaseService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FirebaseService>;
+}

package/lib/services/firebase/firestore-collection.d.ts

@@ -0,0 +1,175 @@
+import { Observable } from 'rxjs';
+import { FirestoreService } from './firestore.service';
+import { FirestoreDocument, PaginatedResult, QueryOptions } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Opciones de configuración para una colección.
+ */
+export interface CollectionOptions {
+    /**
+     * Si true, usa soft delete (marca deletedAt en lugar de eliminar).
+     * Default: false
+     */
+    softDelete?: boolean;
+    /**
+     * Si true, maneja automáticamente createdAt/updatedAt.
+     * Default: true
+     */
+    timestamps?: boolean;
+}
+/**
+ * Referencia a una sub-colección tipada.
+ */
+export interface SubCollectionRef<T extends FirestoreDocument> {
+    getById(id: string): Promise<T | null>;
+    getAll(options?: QueryOptions): Promise<T[]>;
+    watch(id: string): Observable<T | null>;
+    watchAll(options?: QueryOptions): Observable<T[]>;
+    create(data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
+    update(id: string, data: Partial<T>): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+/**
+ * Factory para crear instancias de colección tipadas.
+ *
+ * @example
+ * ```typescript
+ * @Injectable({ providedIn: 'root' })
+ * export class UsersService {
+ *   private users = inject(FirestoreCollectionFactory).create<User>('users');
+ *
+ *   getAll = () => this.users.getAll();
+ *   getById = (id: string) => this.users.getById(id);
+ *   create = (data: Omit<User, 'id'>) => this.users.create(data);
+ *
+ *   // Métodos personalizados
+ *   async getActiveUsers(): Promise<User[]> {
+ *     return this.users.query({
+ *       where: [{ field: 'active', operator: '==', value: true }]
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class FirestoreCollectionFactory {
+    private firestore;
+    constructor(firestore: FirestoreService);
+    /**
+     * Crea una instancia de colección tipada.
+     *
+     * @param collectionPath - Ruta de la colección en Firestore
+     * @param options - Opciones de configuración
+     * @returns Instancia de TypedCollection
+     */
+    create<T extends FirestoreDocument>(collectionPath: string, options?: CollectionOptions): TypedCollection<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FirestoreCollectionFactory, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FirestoreCollectionFactory>;
+}
+/**
+ * Colección tipada con métodos CRUD.
+ *
+ * NO usa inject() - recibe FirestoreService por constructor.
+ * Esto evita el error NG0203.
+ */
+export declare class TypedCollection<T extends FirestoreDocument> {
+    private firestore;
+    private collectionPath;
+    private readonly options;
+    constructor(firestore: FirestoreService, collectionPath: string, options?: CollectionOptions);
+    /**
+     * Obtiene un documento por ID.
+     */
+    getById(id: string): Promise<T | null>;
+    /**
+     * Obtiene todos los documentos de la colección.
+     */
+    getAll(options?: QueryOptions): Promise<T[]>;
+    /**
+     * Ejecuta una query personalizada.
+     */
+    query(options: QueryOptions): Promise<T[]>;
+    /**
+     * Obtiene documentos con paginación.
+     */
+    paginate(options: QueryOptions & {
+        limit: number;
+    }): Promise<PaginatedResult<T>>;
+    /**
+     * Obtiene el primer documento que coincida con la query.
+     */
+    getFirst(options?: QueryOptions): Promise<T | null>;
+    /**
+     * Cuenta los documentos que coinciden con la query.
+     * Nota: Esto carga todos los documentos, usar con cuidado en colecciones grandes.
+     */
+    count(options?: QueryOptions): Promise<number>;
+    /**
+     * Verifica si un documento existe.
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * Suscribe a cambios de un documento.
+     */
+    watch(id: string): Observable<T | null>;
+    /**
+     * Suscribe a cambios de la colección.
+     */
+    watchAll(options?: QueryOptions): Observable<T[]>;
+    /**
+     * Suscribe a una query personalizada.
+     */
+    watchQuery(options: QueryOptions): Observable<T[]>;
+    /**
+     * Crea un nuevo documento con ID auto-generado.
+     */
+    create(data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
+    /**
+     * Crea un documento con ID específico.
+     */
+    createWithId(id: string, data: Omit<T, 'id'>): Promise<void>;
+    /**
+     * Actualiza campos de un documento.
+     */
+    update(id: string, data: Partial<Omit<T, 'id' | 'createdAt'>>): Promise<void>;
+    /**
+     * Elimina un documento.
+     * Si softDelete está habilitado, marca como eliminado en lugar de borrar.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Restaura un documento soft-deleted.
+     */
+    restore(id: string): Promise<void>;
+    /**
+     * Obtiene una referencia a una sub-colección.
+     *
+     * @example
+     * ```typescript
+     * // En UsersService
+     * getUserDocuments(userId: string) {
+     *   return this.users.subcollection<Document>(userId, 'documents');
+     * }
+     *
+     * // Uso
+     * const docs = await users.getUserDocuments('user123').getAll();
+     * ```
+     */
+    subcollection<S extends FirestoreDocument>(parentId: string, subcollectionName: string): SubCollectionRef<S>;
+    /**
+     * Aplica filtros por defecto a las queries.
+     */
+    private applyDefaultFilters;
+    /**
+     * Genera un nuevo ID sin crear el documento.
+     */
+    generateId(): string;
+    /**
+     * Obtiene la ruta de la colección.
+     */
+    getPath(): string;
+}
+/**
+ * @deprecated Use FirestoreCollectionFactory.create() instead.
+ * Type alias for backwards compatibility.
+ */
+export type FirestoreCollection<T extends FirestoreDocument> = TypedCollection<T>;