valtech-components 2.0.795 → 2.0.796

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

@@ -0,0 +1,315 @@
+/**
+ * Messaging Service (FCM)
+ *
+ * Servicio para Firebase Cloud Messaging (Push Notifications).
+ * Permite solicitar permisos, obtener tokens, escuchar mensajes y manejar
+ * navegación (deep linking) cuando el usuario toca una notificación.
+ */
+import { Injector, NgZone } from '@angular/core';
+import { Observable } from 'rxjs';
+import { NotificationAction, NotificationClickEvent, NotificationPayload, NotificationPermission, ValtechFirebaseConfig } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Estado interno del servicio de messaging
+ */
+interface MessagingState {
+    token: string | null;
+    permission: NotificationPermission;
+    isSupported: boolean;
+}
+/**
+ * Servicio para Firebase Cloud Messaging (FCM).
+ *
+ * Permite recibir notificaciones push en la aplicación web.
+ * Requiere VAPID key configurada en ValtechFirebaseConfig.
+ *
+ * @example
+ * ```typescript
+ * @Component({...})
+ * export class NotificationComponent {
+ *   private messaging = inject(MessagingService);
+ *
+ *   token = signal<string | null>(null);
+ *
+ *   async enableNotifications() {
+ *     // Solicitar permiso y obtener token
+ *     const token = await this.messaging.requestPermission();
+ *
+ *     if (token) {
+ *       this.token.set(token);
+ *       // Enviar token a tu backend para almacenarlo
+ *       await this.backend.registerDeviceToken(token);
+ *     }
+ *   }
+ *
+ *   // Escuchar mensajes en foreground
+ *   messages$ = this.messaging.onMessage();
+ * }
+ * ```
+ */
+export declare class MessagingService {
+    private injector;
+    private config;
+    private platformId;
+    private ngZone;
+    private messageSubject;
+    private notificationClickSubject;
+    private stateSubject;
+    private unsubscribeOnMessage?;
+    /** Flag para persistir mensajes FCM en localStorage (debugging) */
+    private readonly debugPersistence;
+    /** Key para localStorage de mensajes FCM (debugging) */
+    private readonly DEBUG_STORAGE_KEY;
+    constructor(injector: Injector, config: ValtechFirebaseConfig, platformId: Object, ngZone: NgZone);
+    /**
+     * Obtiene la instancia de Messaging via Firebase SDK directo (NO AngularFire DI).
+     *
+     * **Por qué no usamos `injector.get(Messaging)`:**
+     * AngularFire `provideMessaging` registra un APP_INITIALIZER que internamente
+     * resuelve `await isSupported()`. Si `injector.get(Messaging)` se llama antes
+     * que ese APP_INITIALIZER termine (ej. otros APP_INITIALIZER del cliente
+     * construyen AuthService → MessagingService → toca Messaging temprano),
+     * AngularFire lanza el error "APP_INITIALIZER ... has not resolved". Angular
+     * DI **cachea errores de factory** — una vez que falló, todos los
+     * `injector.get` siguientes retornan el mismo error cacheado. Retry loops
+     * no funcionan.
+     *
+     * **Workaround:** bypass AngularFire entirely y usar Firebase SDK directo
+     * (`firebase/messaging.getMessaging(getApp())`). AngularFire es un wrapper
+     * sobre el mismo SDK — la instancia que obtenemos es funcionalmente idéntica.
+     * `getApp()` retorna la default Firebase app inicializada por
+     * `provideFirebaseApp(() => initializeApp(config.firebase))`. Si por alguna
+     * razón no está inicializada aún, hacemos initializeApp idempotente.
+     */
+    private fcmSupportPromise?;
+    private getMessagingInstance;
+    /**
+     * Inicializa el servicio de messaging
+     */
+    private initializeMessaging;
+    /**
+     * Configura listener para mensajes del Service Worker.
+     * Recibe eventos cuando el usuario hace click en una notificación background.
+     */
+    private setupServiceWorkerListener;
+    /**
+     * Verifica si FCM está soportado en el navegador actual
+     */
+    private checkSupport;
+    /**
+     * Solicita permiso de notificaciones y obtiene el token FCM.
+     *
+     * @returns Token FCM si se otorgó permiso, null si se denegó
+     *
+     * @example
+     * ```typescript
+     * const token = await messaging.requestPermission();
+     * if (token) {
+     *   console.log('Token FCM:', token);
+     *   // Enviar a backend
+     * } else {
+     *   console.log('Permiso denegado o no soportado');
+     * }
+     * ```
+     */
+    requestPermission(): Promise<string | null>;
+    /**
+     * Obtiene el token FCM actual (sin solicitar permiso).
+     *
+     * @returns Token FCM si está disponible, null si no
+     *
+     * @example
+     * ```typescript
+     * const token = await messaging.getToken();
+     * ```
+     */
+    getToken(): Promise<string | null>;
+    /**
+     * Elimina el token FCM actual (unsubscribe de notificaciones).
+     *
+     * @example
+     * ```typescript
+     * await messaging.deleteToken();
+     * console.log('Token eliminado, no recibirá más notificaciones');
+     * ```
+     */
+    deleteToken(): Promise<void>;
+    /**
+     * Observable de mensajes recibidos en foreground.
+     *
+     * IMPORTANTE: Los mensajes en background son manejados por el Service Worker.
+     *
+     * @returns Observable que emite cuando llega un mensaje en foreground
+     *
+     * @example
+     * ```typescript
+     * messaging.onMessage().subscribe(payload => {
+     *   console.log('Mensaje recibido:', payload);
+     *   // Mostrar notificación custom o actualizar UI
+     * });
+     * ```
+     */
+    onMessage(): Observable<NotificationPayload>;
+    /**
+     * Configura el listener de mensajes en foreground
+     */
+    private setupMessageListener;
+    /**
+     * Persiste un mensaje FCM en localStorage para debugging.
+     * Solo se usa cuando debugMessagePersistence está habilitado.
+     * Mantiene los últimos 50 mensajes.
+     */
+    private persistMessageForDebug;
+    /**
+     * Obtiene el estado actual del permiso de notificaciones.
+     *
+     * @returns 'granted' | 'denied' | 'default'
+     *
+     * @example
+     * ```typescript
+     * const permission = messaging.getPermissionState();
+     * if (permission === 'granted') {
+     *   // Ya tiene permiso
+     * } else if (permission === 'default') {
+     *   // Puede solicitar permiso
+     * } else {
+     *   // Denegado, debe habilitar manualmente
+     * }
+     * ```
+     */
+    getPermissionState(): NotificationPermission;
+    /**
+     * Verifica si FCM está soportado en el navegador actual.
+     * Usa lógica inteligente para evitar falsos negativos por timing del Injector.
+     *
+     * @returns true si FCM está soportado
+     *
+     * @example
+     * ```typescript
+     * if (await messaging.isSupported()) {
+     *   // Puede usar notificaciones push
+     * } else {
+     *   // Navegador no soporta o no tiene Service Worker
+     * }
+     * ```
+     */
+    isSupported(): Promise<boolean>;
+    /**
+     * iOS sin estar instalado como PWA standalone — push web no disponible.
+     * Aplica a Safari y a Edge/Chrome/Firefox en iOS (todos WebKit por mandato Apple).
+     */
+    private isIOSWithoutStandalone;
+    /**
+     * Obtiene el token actual sin hacer request.
+     *
+     * @returns Token almacenado o null
+     */
+    get currentToken(): string | null;
+    /**
+     * Observable del estado completo del servicio de messaging.
+     */
+    get state$(): Observable<MessagingState>;
+    /**
+     * Verifica si el usuario ya otorgó permiso de notificaciones.
+     */
+    get hasPermission(): boolean;
+    /**
+     * Hidrata el estado del token desde un valor externo (ej: localStorage).
+     * Útil cuando el token ya existe pero el MessagingService no lo tiene en memoria.
+     *
+     * @param token Token FCM a setear
+     *
+     * @example
+     * ```typescript
+     * const storedToken = localStorage.getItem('fcm_token');
+     * if (storedToken) {
+     *   messaging.setTokenFromStorage(storedToken);
+     * }
+     * ```
+     */
+    setTokenFromStorage(token: string): void;
+    /**
+     * Observable de clicks en notificaciones.
+     *
+     * Emite cuando el usuario hace click en una notificación (foreground o background).
+     * Usa este observable para navegar a la página correspondiente.
+     *
+     * @returns Observable que emite NotificationClickEvent
+     *
+     * @example
+     * ```typescript
+     * @Component({...})
+     * export class AppComponent {
+     *   private messaging = inject(MessagingService);
+     *   private router = inject(Router);
+     *
+     *   constructor() {
+     *     this.messaging.onNotificationClick().subscribe(event => {
+     *       if (event.action.route) {
+     *         this.router.navigate([event.action.route], {
+     *           queryParams: event.action.queryParams
+     *         });
+     *       }
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    onNotificationClick(): Observable<NotificationClickEvent>;
+    /**
+     * Extrae la acción de navegación de los datos de una notificación.
+     *
+     * Busca campos específicos en el payload de datos:
+     * - `route`: Ruta interna de la app (ej: '/orders/123')
+     * - `url`: URL externa (ej: 'https://example.com')
+     * - `action_type`: Tipo de acción personalizada
+     * - Campos con prefijo `action_`: Datos adicionales
+     *
+     * @param data - Datos del payload de la notificación
+     * @returns Acción de navegación extraída
+     *
+     * @example
+     * ```typescript
+     * // Payload desde el backend:
+     * // { route: '/orders/123', action_type: 'view_order', action_orderId: '123' }
+     *
+     * const action = messaging.extractActionFromData(notification.data);
+     * // { route: '/orders/123', actionType: 'view_order', actionData: { orderId: '123' } }
+     * ```
+     */
+    extractActionFromData(data?: Record<string, string>): NotificationAction;
+    /**
+     * Emite manualmente un evento de click en notificación.
+     *
+     * Útil para manejar clicks en notificaciones foreground donde
+     * la app decide mostrar un banner custom.
+     *
+     * @param notification - Payload de la notificación
+     *
+     * @example
+     * ```typescript
+     * messaging.onMessage().subscribe(notification => {
+     *   // Mostrar banner custom
+     *   this.showBanner(notification, () => {
+     *     // Usuario hizo click en el banner
+     *     messaging.handleNotificationClick(notification);
+     *   });
+     * });
+     * ```
+     */
+    handleNotificationClick(notification: NotificationPayload): void;
+    /**
+     * Verifica si una notificación tiene acción de navegación.
+     *
+     * @param data - Datos del payload
+     * @returns true si tiene route o url
+     */
+    hasNavigationAction(data?: Record<string, string>): boolean;
+    /**
+     * Parsea un query string en un objeto.
+     */
+    private parseQueryString;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MessagingService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<MessagingService>;
+}
+export {};

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

@@ -0,0 +1,141 @@
+/**
+ * Notifications Service
+ *
+ * Servicio para leer notificaciones desde Firestore.
+ * El backend escribe las notificaciones, el frontend solo las lee y actualiza estado.
+ *
+ * Se auto-inicializa cuando AuthService tiene un usuario autenticado.
+ * También puede inicializarse manualmente con `initialize(userId)`.
+ */
+import { Injector } from '@angular/core';
+import { Observable } from 'rxjs';
+import { FirestoreCollectionFactory } from './firestore-collection';
+import { FirestoreDocument } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Documento de notificación en Firestore.
+ * Estructura escrita por el backend.
+ */
+export interface NotificationDocument extends FirestoreDocument {
+    /** Título de la notificación */
+    title?: string;
+    /** Cuerpo del mensaje */
+    body?: string;
+    /** URL de imagen */
+    image?: string;
+    /** Datos personalizados (ej: route, actionType). Legacy — preferir actionRoute + payload */
+    data?: Record<string, string>;
+    /** Tipo de notificación */
+    type?: 'fcm' | 'system' | 'reminder' | string;
+    /** Si la notificación fue leída */
+    isRead: boolean;
+    /** AppID origen (ej: 'showcase', 'sigify'). Permite cross-app routing */
+    appId?: string;
+    /** OrgID asociado (si la notif es org-scoped). Habilita switch-org al abrir */
+    orgId?: string;
+    /** Route destino al click (ej: '/app/docs/123') */
+    actionRoute?: string;
+    /** Payload estructurado para acciones (reemplazo tipado de `data`) */
+    payload?: Record<string, unknown>;
+}
+/**
+ * Servicio para leer notificaciones desde Firestore.
+ *
+ * Se auto-inicializa cuando AuthService tiene un usuario autenticado.
+ * No requiere llamar a `initialize()` manualmente si AuthService está configurado.
+ *
+ * @example
+ * ```typescript
+ * // Con AuthService configurado: auto-inicialización
+ * // Solo inyectar y usar directamente
+ * private notifications = inject(NotificationsService);
+ *
+ * notifications$ = this.notifications.getAll();
+ * unreadCount$ = this.notifications.getUnreadCount();
+ *
+ * // Sin AuthService: inicialización manual
+ * this.notifications.initialize(userId);
+ * ```
+ */
+export declare class NotificationsService {
+    private injector;
+    private collectionFactory;
+    private collection;
+    private currentUserId;
+    private collectionReady$;
+    private authService;
+    constructor(injector: Injector, collectionFactory: FirestoreCollectionFactory);
+    /**
+     * Configura auto-inicialización observando el estado de AuthService.
+     * Se ejecuta en el contexto del injector para poder usar effect().
+     */
+    private setupAutoInitialization;
+    /**
+     * Inicializa el servicio para un usuario específico.
+     *
+     * NOTA: Se llama automáticamente si AuthService está configurado.
+     * Solo usar manualmente si AuthService no está disponible o se necesita
+     * un userId diferente al del usuario autenticado.
+     */
+    initialize(userId: string): void;
+    /**
+     * Verifica si el servicio está inicializado.
+     */
+    get isReady(): boolean;
+    /**
+     * Obtiene el ID del usuario actual.
+     */
+    get userId(): string | null;
+    /**
+     * Obtiene notificaciones ordenadas por fecha descendente (real-time).
+     * Se actualiza automáticamente cuando cambian los datos.
+     *
+     * @param limit - Máximo de notificaciones a cargar (default: 50)
+     */
+    getAll(limit?: number): Observable<NotificationDocument[]>;
+    /**
+     * Obtiene notificaciones (one-time fetch sin listener).
+     * Útil para cargas iniciales sin necesidad de updates en tiempo real.
+     *
+     * @param limit - Máximo de notificaciones a cargar (default: 50)
+     */
+    getAllOnce(limit?: number): Promise<NotificationDocument[]>;
+    /**
+     * Obtiene solo notificaciones no leídas (real-time, filtrado server-side).
+     *
+     * @param limit - Máximo de notificaciones (default: 50)
+     */
+    getUnread(limit?: number): Observable<NotificationDocument[]>;
+    /**
+     * Cuenta notificaciones no leídas usando server-side aggregation query.
+     * No descarga documentos — eficiente para badges en UI.
+     */
+    getUnreadCount(): Observable<number>;
+    /**
+     * Obtiene una notificación por ID.
+     */
+    getById(notificationId: string): Promise<NotificationDocument | null>;
+    /**
+     * Marca una notificación como leída.
+     */
+    markAsRead(notificationId: string): Promise<void>;
+    /**
+     * Marca todas las notificaciones no leídas como leídas (batch write).
+     */
+    markAllAsRead(): Promise<void>;
+    /**
+     * Elimina una notificación.
+     */
+    delete(notificationId: string): Promise<void>;
+    /**
+     * Elimina todas las notificaciones del usuario (batch delete).
+     */
+    deleteAll(): Promise<void>;
+    /**
+     * Limpia el estado del servicio.
+     * Útil para logout.
+     */
+    reset(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NotificationsService, [null, { optional: true; }]>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NotificationsService>;
+}

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

@@ -0,0 +1,151 @@
+/**
+ * Firebase Shared Configuration
+ *
+ * Utilidades genéricas para configuración de Firebase.
+ * Las constantes específicas del proyecto (APP_IDS, FIREBASE_PROJECTS, EMULATOR_CONFIG)
+ * deben definirse en cada app consumidora.
+ */
+import { AppId, EmulatorConfig, FirebaseConfig, ValtechFirebaseConfig } from './types';
+import type { AnalyticsConfig } from './analytics-types';
+export type { AppId } from './types';
+/**
+ * Genera paths de Storage alineados con storage.rules.
+ *
+ * Convenciones (ver frontend/firebase/storage.rules):
+ * - Avatar global del user (cross-app): /users/{uid}/avatar.jpg
+ * - Files privados del user (cross-app): /users/{uid}/files/{path}
+ * - Avatar per-app del user: /apps/{appId}/users/{uid}/avatar.jpg
+ * - Files per-app del user: /apps/{appId}/users/{uid}/files/{path}
+ * - Public per-app: /apps/{appId}/public/{path}
+ * - Shared per-app (auth-only): /apps/{appId}/shared/{path}
+ * - Public global: /public/{path}
+ *
+ * @example
+ * storagePaths.forApp('showcase', 'public', 'banner.jpg')
+ * // => 'apps/showcase/public/banner.jpg'
+ *
+ * storagePaths.userAvatar('user123')
+ * // => 'users/user123/avatar.jpg'
+ *
+ * storagePaths.appUserFile('showcase', 'user123', 'doc.pdf')
+ * // => 'apps/showcase/users/user123/files/doc.pdf'
+ */
+export declare const storagePaths: {
+    /** Path per-app: apps/{appId}/{...paths} */
+    forApp: (appId: AppId, ...paths: string[]) => string;
+    /** Avatar global del user (cross-app) */
+    userAvatar: (userId: string) => string;
+    /** Thumbnail global del user (cross-app) */
+    userThumb: (userId: string) => string;
+    /** File privado global del user (cross-app) */
+    userFile: (userId: string, ...paths: string[]) => string;
+    /** Avatar per-app del user */
+    appUserAvatar: (appId: AppId, userId: string) => string;
+    /** File per-app del user */
+    appUserFile: (appId: AppId, userId: string, ...paths: string[]) => string;
+    /** Public global (acceso sin auth, write admin-only) */
+    public: (...paths: string[]) => string;
+};
+/**
+ * Genera paths de colecciones alineados con firestore.rules.
+ *
+ * Convenciones (ver frontend/firebase/firestore.rules):
+ * - Cross-app shared:
+ *   /users/{uid} (privado), /profiles/{uid} (público global),
+ *   /users/{uid}/notifications (INBOX GLOBAL cross-app cross-org)
+ * - Per-app:
+ *   /apps/{appId}/{collection}, /apps/{appId}/profiles/{uid}
+ * - Per-app per-user (notifications NO viven aquí):
+ *   /apps/{appId}/users/{uid}/{collection}
+ * - Per-app per-org:
+ *   /apps/{appId}/orgs/{orgId}/{collection}
+ *
+ * @example
+ * collections.forApp('showcase', 'items')
+ * // => 'apps/showcase/items'
+ *
+ * collections.appUser('showcase', 'user123', 'drafts')
+ * // => 'apps/showcase/users/user123/drafts'
+ *
+ * collections.appOrg('showcase', 'org_abc', 'posts')
+ * // => 'apps/showcase/orgs/org_abc/posts'
+ *
+ * collections.userNotifications('user123')
+ * // => 'users/user123/notifications'
+ */
+export declare const collections: {
+    /** Per-app cross-user: apps/{appId}/{collection} */
+    forApp: (appId: AppId, collectionName: string) => string;
+    /** Per-app per-user: apps/{appId}/users/{uid}/{collection} */
+    appUser: (appId: AppId, userId: string, collectionName: string) => string;
+    /** Per-app per-org: apps/{appId}/orgs/{orgId}/{collection} */
+    appOrg: (appId: AppId, orgId: string, collectionName: string) => string;
+    /** Per-app perfil público del user: apps/{appId}/profiles/{uid} */
+    appProfile: (appId: AppId, userId: string) => string;
+    /** Inbox global del user (cross-app cross-org) */
+    userNotifications: (userId: string) => string;
+    /** Cross-app shared (sin namespace, nivel raíz) */
+    shared: {
+        /** Doc privado del user — /users/{uid} */
+        users: string;
+        /** Perfiles públicos globales — /profiles/{uid} */
+        profiles: string;
+    };
+};
+/**
+ * Opciones para crear la configuración de Firebase
+ */
+export interface CreateFirebaseConfigOptions {
+    /**
+     * Configuración de emuladores (para desarrollo local).
+     * Pasa tu propia configuración con hosts y puertos.
+     */
+    emulator?: EmulatorConfig;
+    /** Habilitar persistencia offline de Firestore */
+    persistence?: boolean;
+    /**
+     * ID de la aplicación para namespacing automático.
+     * Cuando se configura, FirestoreService y StorageService prefijan automáticamente los paths.
+     */
+    appId?: string;
+    /**
+     * Habilitar Firebase Analytics / GA4.
+     * Requiere measurementId en firebase config.
+     */
+    enableAnalytics?: boolean;
+    /**
+     * Configuración detallada de Analytics.
+     * Solo aplica si enableAnalytics es true.
+     */
+    analyticsConfig?: AnalyticsConfig;
+}
+/**
+ * Crea la configuración completa de Firebase desde variables de entorno.
+ * Usa esto en el environment.ts de cada app.
+ *
+ * @example
+ * // environment.ts
+ * import { createFirebaseConfig } from 'valtech-components';
+ * import { APP_IDS, EMULATOR_CONFIG, USE_EMULATORS } from '../config/app-config';
+ * import firebaseConfig from '../config/firebase.config.json';
+ *
+ * export const environment = {
+ *   valtechFirebase: createFirebaseConfig(
+ *     {
+ *       ...firebaseConfig,
+ *       enableMessaging: true,
+ *       messagingVapidKey: 'BHLx...',
+ *     },
+ *     {
+ *       emulator: USE_EMULATORS ? EMULATOR_CONFIG : undefined,
+ *       persistence: true,
+ *       appId: APP_IDS.MY_APP,
+ *     }
+ *   ),
+ * };
+ */
+export declare function createFirebaseConfig(config: FirebaseConfig, options?: CreateFirebaseConfigOptions): ValtechFirebaseConfig;
+/**
+ * Verifica si la configuración tiene emuladores habilitados
+ */
+export declare function isEmulatorMode(config: ValtechFirebaseConfig): boolean;