valtech-components 2.0.452 → 2.0.453

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>;
+}

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

@@ -0,0 +1,281 @@
+/**
+ * Firebase Types
+ *
+ * Tipos e interfaces para la integración de Firebase en valtech-components.
+ * Todos los modelos de Firestore deben extender FirestoreDocument.
+ */
+/**
+ * Configuración de Firebase (valores de firebaseConfig)
+ */
+export interface FirebaseConfig {
+    apiKey: string;
+    authDomain: string;
+    projectId: string;
+    storageBucket: string;
+    messagingSenderId: string;
+    appId: string;
+    measurementId?: string;
+}
+/**
+ * Configuración de emuladores para desarrollo local
+ */
+export interface EmulatorConfig {
+    firestore?: {
+        host: string;
+        port: number;
+    };
+    auth?: {
+        host: string;
+        port: number;
+    };
+    storage?: {
+        host: string;
+        port: number;
+    };
+}
+/**
+ * Configuración completa de Valtech Firebase
+ */
+export interface ValtechFirebaseConfig {
+    /** Configuración de Firebase */
+    firebase: FirebaseConfig;
+    /** Configuración de emuladores (opcional, para desarrollo) */
+    emulator?: EmulatorConfig;
+    /** Habilitar persistencia offline de Firestore (default: false) */
+    persistence?: boolean;
+    /** Habilitar Firebase Cloud Messaging (default: false) - requiere Service Worker */
+    enableMessaging?: boolean;
+    /** VAPID key para Firebase Cloud Messaging */
+    messagingVapidKey?: string;
+}
+/**
+ * Interface base para todos los documentos de Firestore.
+ * Todos los modelos deben extender esta interface.
+ *
+ * @example
+ * interface User extends FirestoreDocument {
+ *   name: string;
+ *   email: string;
+ * }
+ */
+export interface FirestoreDocument {
+    /** ID del documento (asignado por Firestore) */
+    id?: string;
+    /** Fecha de creación (manejada automáticamente) */
+    createdAt?: Date;
+    /** Fecha de última actualización (manejada automáticamente) */
+    updatedAt?: Date;
+}
+/**
+ * Operadores disponibles para cláusulas where
+ */
+export type WhereOperator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'array-contains' | 'array-contains-any' | 'in' | 'not-in';
+/**
+ * Cláusula where para filtrar documentos
+ */
+export interface WhereClause {
+    /** Campo a filtrar */
+    field: string;
+    /** Operador de comparación */
+    operator: WhereOperator;
+    /** Valor a comparar */
+    value: unknown;
+}
+/**
+ * Dirección de ordenamiento
+ */
+export type OrderDirection = 'asc' | 'desc';
+/**
+ * Cláusula orderBy para ordenar resultados
+ */
+export interface OrderByClause {
+    /** Campo por el cual ordenar */
+    field: string;
+    /** Dirección del ordenamiento */
+    direction: OrderDirection;
+}
+/**
+ * Opciones para queries de Firestore
+ */
+export interface QueryOptions {
+    /** Filtros where (AND entre todos) */
+    where?: WhereClause[];
+    /** Ordenamiento de resultados */
+    orderBy?: OrderByClause[];
+    /** Límite de documentos a retornar */
+    limit?: number;
+    /** Cursor para paginación: empezar después de este documento */
+    startAfter?: unknown;
+    /** Cursor para paginación: empezar en este documento */
+    startAt?: unknown;
+    /** Cursor para paginación: terminar antes de este documento */
+    endBefore?: unknown;
+    /** Cursor para paginación: terminar en este documento */
+    endAt?: unknown;
+}
+/**
+ * Opciones adicionales para subscripciones real-time
+ */
+export interface SubscriptionOptions extends QueryOptions {
+    /** Incluir cambios de metadata (ej: pendingWrites) */
+    includeMetadataChanges?: boolean;
+}
+/**
+ * Resultado de una query paginada
+ */
+export interface PaginatedResult<T> {
+    /** Documentos de la página actual */
+    data: T[];
+    /** Indica si hay más páginas disponibles */
+    hasMore: boolean;
+    /** Cursor para la siguiente página (pasar a startAfter) */
+    lastDoc: unknown;
+    /** Total de documentos (opcional, requiere query adicional) */
+    total?: number;
+}
+/**
+ * Estado de una operación de upload
+ */
+export type UploadState = 'running' | 'paused' | 'success' | 'canceled' | 'error';
+/**
+ * Progreso de upload de archivo
+ */
+export interface UploadProgress {
+    /** Bytes transferidos hasta ahora */
+    bytesTransferred: number;
+    /** Total de bytes a transferir */
+    totalBytes: number;
+    /** Porcentaje completado (0-100) */
+    percentage: number;
+    /** Estado actual del upload */
+    state: UploadState;
+}
+/**
+ * Resultado de un upload completado
+ */
+export interface UploadResult {
+    /** URL de descarga del archivo */
+    downloadUrl: string;
+    /** Ruta completa en Storage */
+    fullPath: string;
+    /** Nombre del archivo */
+    name: string;
+    /** Tamaño en bytes */
+    size: number;
+    /** Tipo MIME del archivo */
+    contentType: string;
+    /** Metadata personalizada */
+    metadata: Record<string, string>;
+}
+/**
+ * Metadata para archivos en Storage
+ */
+export interface StorageMetadata {
+    /** Tipo MIME del archivo */
+    contentType?: string;
+    /** Metadata personalizada (key-value) */
+    customMetadata?: Record<string, string>;
+    /** Control de caché HTTP */
+    cacheControl?: string;
+}
+/**
+ * Resultado de listar archivos en Storage
+ */
+export interface StorageListResult {
+    /** Rutas de los archivos encontrados */
+    items: string[];
+    /** Token para la siguiente página (si hay más) */
+    nextPageToken?: string;
+}
+/**
+ * Información del usuario de Firebase (simplificada)
+ */
+export interface FirebaseUser {
+    /** UID único del usuario */
+    uid: string;
+    /** Email del usuario */
+    email: string | null;
+    /** Nombre para mostrar */
+    displayName: string | null;
+    /** URL de foto de perfil */
+    photoURL: string | null;
+    /** Email verificado */
+    emailVerified: boolean;
+    /** Usuario anónimo */
+    isAnonymous: boolean;
+    /** Proveedor de autenticación */
+    providerId: string;
+}
+/**
+ * Estado de la sesión de Firebase
+ */
+export interface SessionState {
+    /** Usuario actual (null si no autenticado) */
+    user: FirebaseUser | null;
+    /** Indica si el usuario está autenticado */
+    isAuthenticated: boolean;
+    /** Indica si se está cargando el estado de auth */
+    isLoading: boolean;
+    /** Error de autenticación (si lo hay) */
+    error: Error | null;
+}
+/**
+ * Estado del permiso de notificaciones
+ */
+export type NotificationPermission = 'granted' | 'denied' | 'default';
+/**
+ * Payload de una notificación push
+ */
+export interface NotificationPayload {
+    /** Título de la notificación */
+    title?: string;
+    /** Cuerpo del mensaje */
+    body?: string;
+    /** URL de imagen */
+    image?: string;
+    /** Datos personalizados */
+    data?: Record<string, string>;
+    /** ID del mensaje de FCM */
+    messageId?: string;
+}
+/**
+ * Acción de navegación desde una notificación
+ */
+export interface NotificationAction {
+    /** Ruta interna de la app (ej: '/orders/123') */
+    route?: string;
+    /** URL externa (ej: 'https://example.com') */
+    url?: string;
+    /** Parámetros de query string */
+    queryParams?: Record<string, string>;
+    /** Tipo de acción personalizada */
+    actionType?: string;
+    /** Datos adicionales para la acción */
+    actionData?: Record<string, unknown>;
+}
+/**
+ * Evento de click en una notificación
+ */
+export interface NotificationClickEvent {
+    /** Payload original de la notificación */
+    notification: NotificationPayload;
+    /** Acción de navegación extraída */
+    action: NotificationAction;
+    /** Timestamp del click */
+    timestamp: Date;
+}
+/**
+ * Códigos de error de Firebase
+ */
+export type FirebaseErrorCode = 'permission-denied' | 'not-found' | 'already-exists' | 'resource-exhausted' | 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'unauthenticated';
+/**
+ * Error de Firebase tipado
+ */
+export interface FirebaseError {
+    /** Código del error */
+    code: FirebaseErrorCode;
+    /** Mensaje de error (en español) */
+    message: string;
+    /** Error original de Firebase */
+    originalError?: unknown;
+}