valtech-components 2.0.691 → 2.0.692

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

@@ -0,0 +1,126 @@
+/**
+ * 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) */
+    data?: Record<string, string>;
+    /** Tipo de notificación */
+    type?: 'fcm' | 'system' | 'reminder' | string;
+    /** Si la notificación fue leída */
+    isRead: boolean;
+}
+/**
+ * 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 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 todas las notificaciones ordenadas por fecha descendente.
+     * Real-time: se actualiza automáticamente cuando cambian los datos.
+     */
+    getAll(): Observable<NotificationDocument[]>;
+    /**
+     * Obtiene todas las notificaciones (one-time fetch sin listener).
+     * Útil para cargas iniciales sin necesidad de updates en tiempo real.
+     */
+    getAllOnce(): Promise<NotificationDocument[]>;
+    /**
+     * Obtiene solo notificaciones no leídas.
+     */
+    getUnread(): Observable<NotificationDocument[]>;
+    /**
+     * Cuenta notificaciones no leídas.
+     * Útil 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 como leídas.
+     */
+    markAllAsRead(): Promise<void>;
+    /**
+     * Elimina una notificación.
+     */
+    delete(notificationId: string): Promise<void>;
+    /**
+     * Elimina todas las notificaciones del usuario.
+     */
+    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,118 @@
+/**
+ * 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 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;
+    };
+};
+/**
+ * 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 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 {
+    /**
+     * 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;

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

@@ -0,0 +1,238 @@
+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;
+    private config;
+    constructor(storage: Storage);
+    /**
+     * Prefija el path de storage con el appId si está configurado.
+     * Si no hay appId o skipPrefix es true, retorna el path sin modificar.
+     *
+     * @param path - Ruta original
+     * @param skipPrefix - Si es true, no aplica el prefix (útil para paths compartidos como avatares)
+     * @internal
+     */
+    private prefixStoragePath;
+    /**
+     * 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;
+    /**
+     * Construye la URL de avatar de un usuario.
+     *
+     * Los avatares se almacenan en paths predecibles: `users/{userId}/avatar.jpg`
+     * Esto permite que cualquier app pueda mostrar avatares sin pedir la URL al backend,
+     * solo necesita el userId.
+     *
+     * @param userId - ID del usuario (ULID)
+     * @param type - 'avatar' para imagen completa, 'thumb' para thumbnail
+     * @returns URL directa de Firebase Storage
+     *
+     * @example
+     * ```typescript
+     * // Mostrar avatar de cualquier usuario
+     * const avatarUrl = storage.getUserAvatarUrl('01ABCD...');
+     * const thumbUrl = storage.getUserAvatarUrl('01ABCD...', 'thumb');
+     *
+     * // Con cache-busting
+     * const freshUrl = storage.getUserAvatarUrl(userId) + `&t=${Date.now()}`;
+     * ```
+     */
+    getUserAvatarUrl(userId: string, type?: 'avatar' | 'thumb'): string;
+    /**
+     * 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>;
+}