valtech-components 2.0.821 → 2.0.824

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

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

@@ -0,0 +1,374 @@
+/**
+ * Firebase Types
+ *
+ * Tipos e interfaces para la integración de Firebase en valtech-components.
+ * Todos los modelos de Firestore deben extender FirestoreDocument.
+ */
+import type { AnalyticsConfig } from './analytics-types';
+/**
+ * Configuración de Firebase (valores de firebaseConfig)
+ */
+export interface FirebaseConfig {
+    apiKey: string;
+    authDomain: string;
+    projectId: string;
+    storageBucket: string;
+    messagingSenderId: string;
+    appId: string;
+    measurementId?: string;
+    /** Habilitar Firebase Cloud Messaging (default: false) */
+    enableMessaging?: boolean;
+    /** VAPID key para Firebase Cloud Messaging */
+    messagingVapidKey?: 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 por defecto de emuladores.
+ * Puertos estándar usados en todos los proyectos frontend.
+ *
+ * @see https://firebase.google.com/docs/emulator-suite
+ */
+export declare const DEFAULT_EMULATOR_CONFIG: EmulatorConfig;
+/**
+ * Identificador de aplicación para namespacing automático en Firestore y Storage.
+ * Permite aislar datos de diferentes apps dentro del mismo proyecto Firebase.
+ *
+ * Cada app consumidora define sus propios valores de AppId en su configuración local.
+ */
+export type AppId = string;
+/**
+ * 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;
+    /**
+     * ID de la aplicación para namespacing automático.
+     * Si se proporciona:
+     * - Firestore: prefija colecciones con `apps/{appId}/`
+     * - Storage: prefija paths con `{appId}/`
+     * Si no se proporciona, los paths quedan sin modificar (backward compatible).
+     */
+    appId?: AppId;
+    /**
+     * Persiste mensajes FCM en localStorage para debugging.
+     * Solo para desarrollo, permite ver mensajes en DevTools.
+     * Default: false
+     */
+    debugMessagePersistence?: boolean;
+    /**
+     * Habilitar Firebase Analytics / GA4 (default: false).
+     * Requiere measurementId en firebase config.
+     */
+    enableAnalytics?: boolean;
+    /**
+     * Configuración detallada de Analytics.
+     * Solo aplica si enableAnalytics es true.
+     */
+    analyticsConfig?: AnalyticsConfig;
+}
+/**
+ * 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;
+    /**
+     * Skip the appId prefix for shared paths.
+     * Use this for cross-app paths like user avatars: `users/{userId}/avatar.jpg`
+     * @default false
+     */
+    skipPrefix?: boolean;
+}
+/**
+ * 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 de membership en una organización.
+ * Representa el rol y permisos que tiene un usuario en una org específica.
+ */
+export interface MembershipInfo {
+    /** ID del rol (ej: 'admin', 'editor', 'viewer') */
+    roleId: string;
+    /** Nombre del rol para display */
+    roleName: string;
+    /** Lista de permisos en formato 'resource:action' */
+    permissions: string[];
+}
+/**
+ * Estructura completa de claims con RBAC.
+ * Estos claims están disponibles en request.auth.token en Firestore Rules.
+ */
+export interface RBACClaims {
+    /** Email del usuario */
+    email: string;
+    /** Nombre completo del usuario */
+    name: string;
+    /** Si el email está verificado */
+    verified: boolean;
+    /**
+     * Mapa de organizaciones donde el usuario tiene roles.
+     * Key = orgId, Value = información del rol y permisos en esa org.
+     */
+    memberships: Record<string, MembershipInfo>;
+    /** ID de la organización actualmente seleccionada */
+    activeOrg: string;
+}
+/**
+ * Información de una organización para display
+ */
+export interface OrganizationInfo {
+    /** ID único de la organización */
+    id: string;
+    /** Rol del usuario en esta organización */
+    roleId: string;
+    /** Nombre del rol para display */
+    roleName: string;
+    /** Permisos del usuario en esta organización */
+    permissions: 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;
+}