valtech-components 2.0.821 → 2.0.823

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

@@ -0,0 +1,256 @@
+/**
+ * Analytics Service (Firebase GA4)
+ *
+ * Servicio para tracking de eventos, page views y errores con Firebase Analytics.
+ * Integra con el sistema de auth para user properties y respeta consent mode GDPR.
+ */
+import { Injector } from '@angular/core';
+import { ValtechFirebaseConfig } from './types';
+import { AnalyticsDebugEvent, AnalyticsEventName, AnalyticsEventParams, AnalyticsItem, ConsentSettings, ConsentState, UserProperties } from './analytics-types';
+import * as i0 from "@angular/core";
+/**
+ * Servicio de Firebase Analytics (GA4).
+ *
+ * Proporciona tracking de eventos, page views, errores y métricas de performance.
+ * Soporta GDPR Consent Mode y modo debug para desarrollo.
+ *
+ * @example
+ * ```typescript
+ * @Component({...})
+ * export class ProductComponent {
+ *   private analytics = inject(AnalyticsService);
+ *
+ *   onPurchase(product: Product) {
+ *     this.analytics.logEvent('purchase', {
+ *       transaction_id: order.id,
+ *       value: order.total,
+ *       currency: 'EUR'
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class AnalyticsService {
+    private injector;
+    private config;
+    private platformId;
+    private readonly _consentState;
+    private readonly _isDebugMode;
+    private readonly _debugHistory;
+    /** Estado de consentimiento actual (readonly) */
+    readonly consentState: import("@angular/core").Signal<ConsentState>;
+    /** Indica si está en modo debug */
+    readonly isDebugMode: import("@angular/core").Signal<boolean>;
+    /** Indica si analytics está habilitado y funcionando */
+    readonly isEnabled: import("@angular/core").Signal<boolean>;
+    private readonly analyticsConfig;
+    private readonly consentStorageKey;
+    private readonly eventPrefix;
+    private readonly samplingRate;
+    constructor(injector: Injector, config: ValtechFirebaseConfig, platformId: Object);
+    /**
+     * Inicializa el servicio de analytics
+     */
+    private initializeAnalytics;
+    /**
+     * Obtiene la instancia de Analytics de forma perezosa.
+     * Esto evita el error de APP_INITIALIZER de AngularFire.
+     */
+    private getAnalyticsInstance;
+    /**
+     * Verifica si Analytics está soportado
+     */
+    private isAnalyticsSupported;
+    /**
+     * Verifica si debe enviar el evento (sampling)
+     */
+    private shouldSample;
+    /**
+     * Registra un page view.
+     * Normalmente se usa automáticamente via AnalyticsRouterTracker.
+     *
+     * @param pagePath - Ruta de la página (ej: '/products/123')
+     * @param pageTitle - Título de la página (opcional)
+     */
+    logPageView(pagePath: string, pageTitle?: string): void;
+    /**
+     * Registra un screen view (para apps tipo SPA).
+     *
+     * @param screenName - Nombre del screen
+     * @param screenClass - Clase del screen (opcional)
+     */
+    logScreenView(screenName: string, screenClass?: string): void;
+    /**
+     * Registra un evento tipado GA4.
+     *
+     * @param eventName - Nombre del evento (tipado)
+     * @param params - Parámetros del evento (tipados según el nombre)
+     *
+     * @example
+     * ```typescript
+     * // Evento tipado con autocompletado
+     * analytics.logEvent('add_to_cart', {
+     *   item_id: '123',
+     *   item_name: 'Producto',
+     *   value: 99.99,
+     *   currency: 'EUR'
+     * });
+     * ```
+     */
+    logEvent<T extends AnalyticsEventName>(eventName: T, params?: AnalyticsEventParams[T]): void;
+    /**
+     * Registra un evento custom con parámetros libres.
+     * Usar cuando el evento no está en el catálogo tipado.
+     *
+     * @param eventName - Nombre del evento custom
+     * @param params - Parámetros libres
+     */
+    logCustomEvent(eventName: string, params?: Record<string, unknown>): void;
+    /**
+     * Lógica común para enviar eventos
+     */
+    private trackEvent;
+    /**
+     * Registra vista de item
+     */
+    logViewItem(item: AnalyticsItem): void;
+    /**
+     * Registra agregar al carrito
+     */
+    logAddToCart(item: AnalyticsItem, quantity?: number): void;
+    /**
+     * Registra inicio de checkout
+     */
+    logBeginCheckout(items: AnalyticsItem[], value: number, currency?: string): void;
+    /**
+     * Registra compra completada
+     */
+    logPurchase(transactionId: string, items: AnalyticsItem[], value: number, currency?: string): void;
+    /**
+     * Setea el userId para asociar eventos con el usuario.
+     * Llamado automáticamente si enableAuthIntegration=true.
+     *
+     * @param userId - ID del usuario o null para limpiar
+     */
+    setUserId(userId: string | null): void;
+    /**
+     * Setea propiedades del usuario para segmentación.
+     *
+     * @param properties - Propiedades key-value
+     *
+     * @example
+     * ```typescript
+     * analytics.setUserProperties({
+     *   subscription_tier: 'premium',
+     *   preferred_language: 'es'
+     * });
+     * ```
+     */
+    setUserProperties(properties: UserProperties | Record<string, string | number | boolean>): void;
+    /**
+     * Setea la organización activa (multi-tenant).
+     * Llamado automáticamente si enableAuthIntegration=true.
+     *
+     * @param orgId - ID de la organización o null
+     */
+    setActiveOrganization(orgId: string | null): void;
+    /**
+     * Registra un error para tracking.
+     * Integra automáticamente con Angular ErrorHandler si enableErrorTracking=true.
+     *
+     * @param error - Error o mensaje de error
+     * @param context - Contexto adicional
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await riskyOperation();
+     * } catch (error) {
+     *   analytics.logError(error, { context: 'checkout_flow' });
+     * }
+     * ```
+     */
+    logError(error: Error | string, context?: Record<string, string>): void;
+    /**
+     * Registra un error fatal (crash-level).
+     */
+    logFatalError(error: Error, context?: Record<string, string>): void;
+    /**
+     * Actualiza el estado de consentimiento del usuario.
+     * Afecta qué datos se recolectan y envían.
+     *
+     * @param consent - Settings de consentimiento
+     *
+     * @example
+     * ```typescript
+     * // Usuario acepta todo
+     * analytics.updateConsent({ analytics: true, advertising: true });
+     *
+     * // Usuario rechaza publicidad
+     * analytics.updateConsent({ analytics: true, advertising: false });
+     * ```
+     */
+    updateConsent(consent: ConsentSettings): void;
+    /**
+     * Deniega todo consentimiento.
+     */
+    denyAllConsent(): void;
+    /**
+     * Acepta todo consentimiento.
+     */
+    grantAllConsent(): void;
+    /**
+     * Obtiene el estado actual de consentimiento.
+     */
+    getConsentState(): ConsentState;
+    /**
+     * Aplica consent settings a gtag (GA4 Consent Mode v2)
+     */
+    private applyConsentToGtag;
+    /**
+     * Carga consent desde localStorage
+     */
+    private loadConsentFromStorage;
+    /**
+     * Guarda consent en localStorage
+     */
+    private saveConsentToStorage;
+    /**
+     * Registra una métrica de timing/performance.
+     *
+     * @param name - Nombre de la métrica
+     * @param valueMs - Valor en milisegundos
+     * @param params - Parámetros adicionales
+     *
+     * @example
+     * ```typescript
+     * const start = performance.now();
+     * await loadData();
+     * analytics.logTiming('data_load', performance.now() - start, {
+     *   category: 'api',
+     *   endpoint: '/products'
+     * });
+     * ```
+     */
+    logTiming(name: string, valueMs: number, params?: Record<string, string>): void;
+    /**
+     * Habilita/deshabilita modo debug.
+     * En debug: logea eventos a consola además de enviarlos a Firebase.
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Obtiene historial de eventos (solo en debug mode).
+     * Útil para testing y desarrollo.
+     */
+    getDebugHistory(): AnalyticsDebugEvent[];
+    /**
+     * Limpia historial de debug.
+     */
+    clearDebugHistory(): void;
+    /**
+     * Agrega evento al historial de debug
+     */
+    private addToDebugHistory;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AnalyticsService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AnalyticsService>;
+}

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,303 @@
+/**
+ * Firebase Service
+ *
+ * Servicio principal para la autenticación con Firebase usando Custom Tokens.
+ * Permite que usuarios autenticados con tu backend (Cognito, etc.) accedan
+ * a servicios de Firebase (Firestore, Storage, FCM) de manera segura.
+ */
+import { Signal } from '@angular/core';
+import { Auth, UserCredential } from '@angular/fire/auth';
+import { Observable } from 'rxjs';
+import { FirebaseUser, MembershipInfo, OrganizationInfo, 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>;
+    /**
+     * Signal interna que respalda `firebaseAuthReady`.
+     * `true` cuando hay un `firebase.User` activo y por tanto las reglas de
+     * Firestore evaluarán `request.auth != null` correctamente.
+     */
+    private readonly _firebaseAuthReady;
+    /**
+     * Indica si la sesión de **Firebase Auth** está establecida y lista para
+     * leer Firestore.
+     *
+     * IMPORTANTE: esto es distinto del JWT del backend. La sesión de Firebase
+     * Auth es una sesión separada que se establece vía `signInWithCustomToken`
+     * (ver `AuthService.signInWithFirebase`). En cold start de PWA, el JWT del
+     * backend puede estar listo varios cientos de ms antes de que Firebase Auth
+     * confirme su `User` — adjuntar un listener de Firestore en esa ventana
+     * produce `permission-denied`.
+     *
+     * Usar este signal (o `whenFirebaseAuthReady()`) como gate antes de
+     * suscribirse a cualquier query/listener de Firestore.
+     *
+     * @example
+     * ```typescript
+     * if (this.firebase.firebaseAuthReady()) {
+     *   // seguro leer Firestore
+     * }
+     * ```
+     */
+    readonly firebaseAuthReady: Signal<boolean>;
+    /**
+     * Emite `true` una sola vez en cuanto la sesión de Firebase Auth está lista,
+     * y completa. Si ya está lista, emite inmediatamente.
+     *
+     * Pensado como gate compartido para abrir streams Firestore — espera la
+     * ventana de hidratación de Firebase Auth sin necesidad de retries.
+     */
+    readonly firebaseAuthReady$: Observable<boolean>;
+    constructor(auth: Auth, config: ValtechFirebaseConfig);
+    /**
+     * Resuelve en cuanto la sesión de Firebase Auth está lista para leer
+     * Firestore. Si ya está lista, resuelve inmediatamente.
+     *
+     * Útil para gatear la primera suscripción a un listener de Firestore y así
+     * cerrar la ventana de `permission-denied` en cold start.
+     */
+    whenFirebaseAuthReady(): Promise<boolean>;
+    /**
+     * 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.
+     *
+     * @param forceRefresh - Si true, fuerza la renovación del token para obtener claims actualizados
+     * @returns Objeto con los claims o vacío si no hay usuario
+     */
+    getClaims(forceRefresh?: boolean): 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>;
+    /**
+     * Obtiene las memberships (organizaciones) del usuario.
+     * Cada membership contiene el rol y permisos en esa organización.
+     *
+     * @param forceRefresh - Si true, fuerza la renovación del token
+     * @returns Mapa de orgId → MembershipInfo
+     *
+     * @example
+     * ```typescript
+     * const memberships = await firebaseService.getMemberships();
+     * // { 'org_abc': { roleId: 'admin', roleName: 'admin', permissions: ['users:*', ...] } }
+     * ```
+     */
+    getMemberships(forceRefresh?: boolean): Promise<Record<string, MembershipInfo>>;
+    /**
+     * Obtiene la organización activa del usuario.
+     * La organización activa se establece al hacer login o al cambiar de org.
+     *
+     * @param forceRefresh - Si true, fuerza la renovación del token
+     * @returns ID de la organización activa o null si no hay ninguna
+     */
+    getActiveOrg(forceRefresh?: boolean): Promise<string | null>;
+    /**
+     * Obtiene información de todas las organizaciones del usuario.
+     *
+     * @param forceRefresh - Si true, fuerza la renovación del token
+     * @returns Array con información de cada organización
+     */
+    getOrganizations(forceRefresh?: boolean): Promise<OrganizationInfo[]>;
+    /**
+     * Obtiene los IDs de todas las organizaciones del usuario.
+     *
+     * @returns Array de IDs de organizaciones
+     */
+    getOrganizationIds(): Promise<string[]>;
+    /**
+     * Verifica si el usuario pertenece a una organización.
+     *
+     * @param orgId - ID de la organización
+     * @returns true si el usuario es miembro
+     */
+    isMemberOf(orgId: string): Promise<boolean>;
+    /**
+     * Obtiene el rol del usuario en una organización.
+     *
+     * @param orgId - ID de la organización
+     * @returns ID del rol o null si no es miembro
+     */
+    getRoleInOrg(orgId: string): Promise<string | null>;
+    /**
+     * Obtiene los permisos del usuario en una organización.
+     *
+     * @param orgId - ID de la organización
+     * @returns Array de permisos en formato 'resource:action'
+     */
+    getPermissionsInOrg(orgId: string): Promise<string[]>;
+    /**
+     * Verifica si el usuario tiene un permiso específico en una organización.
+     * Soporta wildcards: 'resource:*' y '*:*' (super admin).
+     *
+     * @param orgId - ID de la organización
+     * @param resource - Recurso a verificar (ej: 'users', 'documents')
+     * @param action - Acción a verificar (ej: 'read', 'write', 'create', 'delete')
+     * @returns true si tiene el permiso
+     *
+     * @example
+     * ```typescript
+     * // Verificar permiso específico
+     * const canReadUsers = await firebaseService.hasPermission('org_abc', 'users', 'read');
+     *
+     * // Verificar en la organización activa
+     * const orgId = await firebaseService.getActiveOrg();
+     * const canEdit = await firebaseService.hasPermission(orgId!, 'documents', 'write');
+     * ```
+     */
+    hasPermission(orgId: string, resource: string, action: string): Promise<boolean>;
+    /**
+     * Verifica si el usuario puede leer un recurso en una organización.
+     * Atajo para hasPermission(orgId, resource, 'read').
+     */
+    canRead(orgId: string, resource: string): Promise<boolean>;
+    /**
+     * Verifica si el usuario puede escribir un recurso en una organización.
+     * Atajo para hasPermission(orgId, resource, 'write').
+     */
+    canWrite(orgId: string, resource: string): Promise<boolean>;
+    /**
+     * Verifica si el usuario puede crear un recurso en una organización.
+     * Atajo para hasPermission(orgId, resource, 'create').
+     */
+    canCreate(orgId: string, resource: string): Promise<boolean>;
+    /**
+     * Verifica si el usuario puede eliminar un recurso en una organización.
+     * Atajo para hasPermission(orgId, resource, 'delete').
+     */
+    canDelete(orgId: string, resource: string): Promise<boolean>;
+    /**
+     * Verifica si el usuario puede administrar un recurso en una organización.
+     * Equivale a tener 'resource:*' o '*:*'.
+     */
+    canManage(orgId: string, resource: string): Promise<boolean>;
+    /**
+     * Verifica si el usuario es super admin en una organización.
+     * Super admin tiene el permiso '*:*'.
+     */
+    isSuperAdmin(orgId: string): Promise<boolean>;
+    /**
+     * Verifica si el usuario es admin en una organización.
+     */
+    isAdminInOrg(orgId: 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>;
+}