valtech-components 2.0.451 → 2.0.453

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

@@ -0,0 +1,263 @@
+/**
+ * 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 { NgZone } from '@angular/core';
+import { Messaging } from '@angular/fire/messaging';
+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 messaging;
+    private config;
+    private platformId;
+    private ngZone;
+    private messageSubject;
+    private notificationClickSubject;
+    private stateSubject;
+    private unsubscribeOnMessage?;
+    constructor(messaging: Messaging | null, config: ValtechFirebaseConfig, platformId: Object, ngZone: NgZone);
+    /**
+     * 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;
+    /**
+     * 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.
+     *
+     * @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>;
+    /**
+     * 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;
+    /**
+     * 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, [{ optional: true; }, null, null, null]>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<MessagingService>;
+}
+export {};

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

@@ -0,0 +1,126 @@
+/**
+ * Firebase Shared Configuration
+ *
+ * Configuración base de Firebase compartida entre todas las apps del monorepo.
+ * Los secrets (apiKey, appId) se inyectan en build time via environment.
+ */
+import { EmulatorConfig, FirebaseConfig, ValtechFirebaseConfig } from './types';
+/**
+ * Identificadores de las apps del monorepo.
+ * Usados para namespacing de colecciones Firestore y paths de Storage.
+ */
+export type AppId = 'demo' | 'showcase' | 'admin-portal' | 'app';
+export declare const APP_IDS: {
+    readonly DEMO: AppId;
+    readonly SHOWCASE: AppId;
+    readonly ADMIN_PORTAL: AppId;
+    readonly APP: AppId;
+};
+/**
+ * IDs de los proyectos Firebase por ambiente.
+ * Deben coincidir con los proyectos creados en Firebase Console.
+ */
+export declare const FIREBASE_PROJECTS: {
+    readonly development: "myvaltech-dev";
+    readonly production: "myvaltech-prod";
+};
+/**
+ * Configuración de emuladores compartida.
+ * Todos los puertos deben coincidir con frontend/firebase/firebase.json
+ */
+export declare const SHARED_EMULATOR_CONFIG: EmulatorConfig;
+/**
+ * Genera paths de Storage con namespace por app.
+ *
+ * @example
+ * // Path específico de la app
+ * storagePaths.forApp('showcase', 'uploads', 'image.jpg')
+ * // => 'showcase/uploads/image.jpg'
+ *
+ * // Path compartido
+ * storagePaths.shared.profilePhoto('user123', 'avatar.jpg')
+ * // => 'profile-photos/user123/avatar.jpg'
+ */
+export declare const storagePaths: {
+    /** Carpeta específica de la app: {appId}/{...paths} */
+    forApp: (appId: AppId, ...paths: string[]) => string;
+    /** Carpetas compartidas (sin namespace) */
+    shared: {
+        /** Foto de perfil de usuario */
+        profilePhoto: (userId: string, fileName: string) => string;
+        /** Archivos públicos accesibles sin autenticación */
+        public: (...paths: string[]) => string;
+    };
+    /** Carpetas de desarrollo (acceso libre en emuladores) */
+    demo: (...paths: string[]) => string;
+};
+/**
+ * Genera paths de colecciones con namespace por app.
+ *
+ * IMPORTANTE: La estructura es /apps/{appId}/{collection}/{docId}
+ * Firestore requiere número impar de segmentos para paths de colección.
+ *
+ * @example
+ * // Colección específica de la app
+ * collections.forApp('showcase', 'items')
+ * // => 'apps/showcase/items'
+ *
+ * // Colección de desarrollo
+ * collections.forApp('demo', 'items')
+ * // => 'apps/demo/items'
+ *
+ * // Colección compartida
+ * collections.shared.users
+ * // => 'users'
+ */
+export declare const collections: {
+    /** Colección específica de la app: apps/{appId}/{collection} */
+    forApp: (appId: AppId, collectionName: string) => string;
+    /** Colecciones compartidas (sin namespace, nivel raíz) */
+    shared: {
+        /** Usuarios del sistema */
+        users: string;
+        /** Perfiles públicos */
+        profiles: string;
+        /** Notificaciones de usuarios */
+        notifications: string;
+    };
+};
+/**
+ * Opciones para crear la configuración de Firebase
+ */
+export interface CreateFirebaseConfigOptions {
+    /** Usar emuladores locales (para desarrollo) */
+    useEmulators?: boolean;
+    /** Habilitar persistencia offline de Firestore */
+    persistence?: boolean;
+    /** Habilitar Firebase Cloud Messaging */
+    enableMessaging?: boolean;
+    /** VAPID key para FCM (requerido si enableMessaging es true) */
+    messagingVapidKey?: string;
+}
+/**
+ * Crea la configuración completa de Firebase desde variables de entorno.
+ * Usa esto en el environment.ts de cada app.
+ *
+ * @example
+ * // environment.ts
+ * export const environment = {
+ *   firebase: createFirebaseConfig(
+ *     {
+ *       apiKey: 'AIza...',
+ *       authDomain: 'myvaltech-dev.firebaseapp.com',
+ *       projectId: 'myvaltech-dev',
+ *       storageBucket: 'myvaltech-dev.appspot.com',
+ *       messagingSenderId: '123456789',
+ *       appId: '1:123456789:web:abc123',
+ *     },
+ *     { useEmulators: true, persistence: true }
+ *   ),
+ * };
+ */
+export declare function createFirebaseConfig(envConfig: FirebaseConfig, options?: CreateFirebaseConfigOptions): ValtechFirebaseConfig;
+/**
+ * Verifica si la configuración tiene emuladores habilitados
+ */
+export declare function isEmulatorMode(config: ValtechFirebaseConfig): boolean;

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

@@ -0,0 +1,206 @@
+import { Storage } from '@angular/fire/storage';
+import { Observable } from 'rxjs';
+import { StorageListResult, StorageMetadata, UploadProgress, UploadResult } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Servicio para Firebase Storage.
+ *
+ * @example
+ * ```typescript
+ * @Component({...})
+ * export class FileUploadComponent {
+ *   private storage = inject(StorageService);
+ *
+ *   uploadProgress = signal<number>(0);
+ *   downloadUrl = signal<string | null>(null);
+ *
+ *   async onFileSelected(event: Event) {
+ *     const file = (event.target as HTMLInputElement).files?.[0];
+ *     if (!file) return;
+ *
+ *     // Upload con progreso
+ *     this.storage.upload(`uploads/${file.name}`, file).subscribe({
+ *       next: (progress) => this.uploadProgress.set(progress.percentage),
+ *       complete: async () => {
+ *         const url = await this.storage.getDownloadUrl(`uploads/${file.name}`);
+ *         this.downloadUrl.set(url);
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare class StorageService {
+    private storage;
+    constructor(storage: Storage);
+    /**
+     * Sube un archivo con tracking de progreso.
+     *
+     * @param path - Ruta en Storage donde guardar el archivo
+     * @param file - Archivo a subir (File o Blob)
+     * @param metadata - Metadata opcional (contentType, customMetadata)
+     * @returns Observable que emite el progreso y completa cuando termina
+     *
+     * @example
+     * ```typescript
+     * // Upload básico
+     * storage.upload('images/photo.jpg', file).subscribe({
+     *   next: (progress) => console.log(`${progress.percentage}%`),
+     *   complete: () => console.log('Upload completado')
+     * });
+     *
+     * // Con metadata
+     * storage.upload('docs/report.pdf', file, {
+     *   contentType: 'application/pdf',
+     *   customMetadata: { uploadedBy: 'user123' }
+     * }).subscribe(...);
+     * ```
+     */
+    upload(path: string, file: File | Blob, metadata?: StorageMetadata): Observable<UploadProgress>;
+    /**
+     * Sube un archivo y retorna la URL de descarga al completar.
+     *
+     * @param path - Ruta en Storage
+     * @param file - Archivo a subir
+     * @param metadata - Metadata opcional
+     * @returns Resultado del upload con URL de descarga
+     *
+     * @example
+     * ```typescript
+     * const result = await storage.uploadAndGetUrl('avatars/user123.jpg', file);
+     * console.log('URL:', result.downloadUrl);
+     * ```
+     */
+    uploadAndGetUrl(path: string, file: File | Blob, metadata?: StorageMetadata): Promise<UploadResult>;
+    /**
+     * Sube un archivo desde una Data URL (base64).
+     *
+     * @param path - Ruta en Storage
+     * @param dataUrl - Data URL (ej: 'data:image/png;base64,...')
+     * @param metadata - Metadata opcional
+     * @returns Resultado del upload
+     *
+     * @example
+     * ```typescript
+     * // Desde canvas
+     * const dataUrl = canvas.toDataURL('image/png');
+     * const result = await storage.uploadFromDataUrl('images/drawing.png', dataUrl);
+     * ```
+     */
+    uploadFromDataUrl(path: string, dataUrl: string, metadata?: StorageMetadata): Promise<UploadResult>;
+    /**
+     * Obtiene la URL de descarga de un archivo.
+     *
+     * @param path - Ruta del archivo en Storage
+     * @returns URL de descarga
+     *
+     * @example
+     * ```typescript
+     * const url = await storage.getDownloadUrl('images/photo.jpg');
+     * // Usar en <img [src]="url">
+     * ```
+     */
+    getDownloadUrl(path: string): Promise<string>;
+    /**
+     * Obtiene la metadata de un archivo.
+     *
+     * @param path - Ruta del archivo
+     * @returns Metadata del archivo
+     */
+    getMetadata(path: string): Promise<StorageMetadata & {
+        size: number;
+        name: string;
+    }>;
+    /**
+     * Elimina un archivo.
+     *
+     * @param path - Ruta del archivo a eliminar
+     *
+     * @example
+     * ```typescript
+     * await storage.delete('images/old-photo.jpg');
+     * ```
+     */
+    delete(path: string): Promise<void>;
+    /**
+     * Elimina múltiples archivos.
+     *
+     * @param paths - Array de rutas a eliminar
+     *
+     * @example
+     * ```typescript
+     * await storage.deleteMultiple([
+     *   'images/photo1.jpg',
+     *   'images/photo2.jpg'
+     * ]);
+     * ```
+     */
+    deleteMultiple(paths: string[]): Promise<void>;
+    /**
+     * Lista archivos en un directorio.
+     *
+     * @param path - Ruta del directorio
+     * @returns Lista de rutas de archivos
+     *
+     * @example
+     * ```typescript
+     * const result = await storage.list('images/');
+     * console.log(result.items); // ['images/photo1.jpg', 'images/photo2.jpg']
+     * ```
+     */
+    list(path: string): Promise<StorageListResult>;
+    /**
+     * Genera un nombre de archivo único con timestamp.
+     *
+     * @param originalName - Nombre original del archivo
+     * @param prefix - Prefijo opcional
+     * @returns Nombre único
+     *
+     * @example
+     * ```typescript
+     * const uniqueName = storage.generateFileName('photo.jpg', 'user123');
+     * // => 'user123_1703091234567_photo.jpg'
+     * ```
+     */
+    generateFileName(originalName: string, prefix?: string): string;
+    /**
+     * Genera una ruta única para un archivo.
+     *
+     * @param directory - Directorio base
+     * @param originalName - Nombre original
+     * @param prefix - Prefijo opcional
+     * @returns Ruta completa única
+     *
+     * @example
+     * ```typescript
+     * const path = storage.generatePath('uploads', 'photo.jpg', 'user123');
+     * // => 'uploads/user123_1703091234567_photo.jpg'
+     * ```
+     */
+    generatePath(directory: string, originalName: string, prefix?: string): string;
+    /**
+     * Obtiene la extensión de un archivo.
+     *
+     * @param filename - Nombre del archivo
+     * @returns Extensión (sin el punto)
+     */
+    getExtension(filename: string): string;
+    /**
+     * Verifica si un archivo es una imagen basándose en su extensión.
+     */
+    isImage(filename: string): boolean;
+    /**
+     * Verifica si un archivo es un documento.
+     */
+    isDocument(filename: string): boolean;
+    /**
+     * Mapea el estado de la tarea de upload
+     */
+    private mapTaskState;
+    /**
+     * Convierte errores de Storage a mensajes en español
+     */
+    private getErrorMessage;
+    static ɵfac: i0.ɵɵFactoryDeclaration<StorageService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<StorageService>;
+}