valtech-components 2.0.687 → 2.0.689

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

@@ -0,0 +1,519 @@
+/**
+ * Storage Service
+ *
+ * Servicio para operaciones de Firebase Storage.
+ * Soporta upload con tracking de progreso, download y gestión de archivos.
+ */
+
+import { inject, Injectable } from '@angular/core';
+import {
+  deleteObject,
+  getDownloadURL,
+  getMetadata,
+  listAll,
+  ref,
+  Storage,
+  uploadBytesResumable,
+  UploadMetadata,
+  UploadTaskSnapshot,
+} from '@angular/fire/storage';
+import { BehaviorSubject, Observable } from 'rxjs';
+
+import { VALTECH_FIREBASE_CONFIG } from './config';
+import { StorageListResult, StorageMetadata, UploadProgress, UploadResult, UploadState } from './types';
+
+/**
+ * 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);
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
+@Injectable({ providedIn: 'root' })
+export class StorageService {
+  private config = inject(VALTECH_FIREBASE_CONFIG, { optional: true });
+
+  constructor(private 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(path: string, skipPrefix = false): string {
+    if (skipPrefix || !this.config?.appId) return path;
+    return `${this.config.appId}/${path}`;
+  }
+
+  // ===========================================================================
+  // UPLOAD
+  // ===========================================================================
+
+  /**
+   * 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> {
+    const prefixedPath = this.prefixStoragePath(path, metadata?.skipPrefix);
+    const storageRef = ref(this.storage, prefixedPath);
+    const uploadMetadata: UploadMetadata = {
+      contentType: metadata?.contentType || (file instanceof File ? file.type : undefined),
+      customMetadata: metadata?.customMetadata,
+      cacheControl: metadata?.cacheControl,
+    };
+
+    const task = uploadBytesResumable(storageRef, file, uploadMetadata);
+    const progress$ = new BehaviorSubject<UploadProgress>({
+      bytesTransferred: 0,
+      totalBytes: file.size,
+      percentage: 0,
+      state: 'running',
+    });
+
+    task.on(
+      'state_changed',
+      (snapshot: UploadTaskSnapshot) => {
+        progress$.next({
+          bytesTransferred: snapshot.bytesTransferred,
+          totalBytes: snapshot.totalBytes,
+          percentage: Math.round((snapshot.bytesTransferred / snapshot.totalBytes) * 100),
+          state: this.mapTaskState(snapshot.state),
+        });
+      },
+      (error) => {
+        progress$.next({
+          bytesTransferred: 0,
+          totalBytes: file.size,
+          percentage: 0,
+          state: 'error',
+        });
+        progress$.error(this.getErrorMessage(error));
+      },
+      () => {
+        progress$.next({
+          bytesTransferred: file.size,
+          totalBytes: file.size,
+          percentage: 100,
+          state: 'success',
+        });
+        progress$.complete();
+      }
+    );
+
+    return progress$.asObservable();
+  }
+
+  /**
+   * 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);
+   * ```
+   */
+  async uploadAndGetUrl(
+    path: string,
+    file: File | Blob,
+    metadata?: StorageMetadata
+  ): Promise<UploadResult> {
+    const prefixedPath = this.prefixStoragePath(path, metadata?.skipPrefix);
+    return new Promise((resolve, reject) => {
+      this.upload(path, file, metadata).subscribe({
+        complete: async () => {
+          try {
+            const storageRef = ref(this.storage, prefixedPath);
+            const downloadUrl = await getDownloadURL(storageRef);
+            const storedMetadata = await getMetadata(storageRef);
+
+            resolve({
+              downloadUrl,
+              fullPath: storedMetadata.fullPath,
+              name: storedMetadata.name,
+              size: storedMetadata.size,
+              contentType: storedMetadata.contentType || 'application/octet-stream',
+              metadata: storedMetadata.customMetadata || {},
+            });
+          } catch (error) {
+            reject(this.getErrorMessage(error));
+          }
+        },
+        error: (error) => reject(error),
+      });
+    });
+  }
+
+  /**
+   * 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);
+   * ```
+   */
+  async uploadFromDataUrl(
+    path: string,
+    dataUrl: string,
+    metadata?: StorageMetadata
+  ): Promise<UploadResult> {
+    // Extraer content type y datos base64
+    const matches = dataUrl.match(/^data:([^;]+);base64,(.+)$/);
+    if (!matches) {
+      throw new Error('Data URL inválida');
+    }
+
+    const contentType = matches[1];
+    const base64Data = matches[2];
+
+    // Convertir base64 a Blob
+    const byteCharacters = atob(base64Data);
+    const byteNumbers = new Array(byteCharacters.length);
+    for (let i = 0; i < byteCharacters.length; i++) {
+      byteNumbers[i] = byteCharacters.charCodeAt(i);
+    }
+    const byteArray = new Uint8Array(byteNumbers);
+    const blob = new Blob([byteArray], { type: contentType });
+
+    return this.uploadAndGetUrl(path, blob, {
+      contentType,
+      ...metadata,
+    });
+  }
+
+  // ===========================================================================
+  // DOWNLOAD
+  // ===========================================================================
+
+  /**
+   * 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">
+   * ```
+   */
+  async getDownloadUrl(path: string): Promise<string> {
+    try {
+      const prefixedPath = this.prefixStoragePath(path);
+      const storageRef = ref(this.storage, prefixedPath);
+      return await getDownloadURL(storageRef);
+    } catch (error) {
+      throw new Error(this.getErrorMessage(error));
+    }
+  }
+
+  /**
+   * Obtiene la metadata de un archivo.
+   *
+   * @param path - Ruta del archivo
+   * @returns Metadata del archivo
+   */
+  async getMetadata(path: string): Promise<StorageMetadata & { size: number; name: string }> {
+    try {
+      const prefixedPath = this.prefixStoragePath(path);
+      const storageRef = ref(this.storage, prefixedPath);
+      const metadata = await getMetadata(storageRef);
+      return {
+        contentType: metadata.contentType,
+        customMetadata: metadata.customMetadata,
+        cacheControl: metadata.cacheControl,
+        size: metadata.size,
+        name: metadata.name,
+      };
+    } catch (error) {
+      throw new Error(this.getErrorMessage(error));
+    }
+  }
+
+  // ===========================================================================
+  // DELETE
+  // ===========================================================================
+
+  /**
+   * Elimina un archivo.
+   *
+   * @param path - Ruta del archivo a eliminar
+   *
+   * @example
+   * ```typescript
+   * await storage.delete('images/old-photo.jpg');
+   * ```
+   */
+  async delete(path: string): Promise<void> {
+    try {
+      const prefixedPath = this.prefixStoragePath(path);
+      const storageRef = ref(this.storage, prefixedPath);
+      await deleteObject(storageRef);
+    } catch (error) {
+      throw new Error(this.getErrorMessage(error));
+    }
+  }
+
+  /**
+   * Elimina múltiples archivos.
+   *
+   * @param paths - Array de rutas a eliminar
+   *
+   * @example
+   * ```typescript
+   * await storage.deleteMultiple([
+   *   'images/photo1.jpg',
+   *   'images/photo2.jpg'
+   * ]);
+   * ```
+   */
+  async deleteMultiple(paths: string[]): Promise<void> {
+    await Promise.all(paths.map((path) => this.delete(path)));
+  }
+
+  // ===========================================================================
+  // LIST
+  // ===========================================================================
+
+  /**
+   * 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']
+   * ```
+   */
+  async list(path: string): Promise<StorageListResult> {
+    try {
+      const prefixedPath = this.prefixStoragePath(path);
+      const storageRef = ref(this.storage, prefixedPath);
+      const result = await listAll(storageRef);
+
+      return {
+        items: result.items.map((item) => item.fullPath),
+        nextPageToken: undefined, // listAll no soporta paginación
+      };
+    } catch (error) {
+      throw new Error(this.getErrorMessage(error));
+    }
+  }
+
+  // ===========================================================================
+  // UTILIDADES
+  // ===========================================================================
+
+  /**
+   * 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 {
+    const timestamp = Date.now();
+    const sanitizedName = originalName.replace(/[^a-zA-Z0-9.-]/g, '_');
+
+    if (prefix) {
+      return `${prefix}_${timestamp}_${sanitizedName}`;
+    }
+    return `${timestamp}_${sanitizedName}`;
+  }
+
+  /**
+   * 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 {
+    const fileName = this.generateFileName(originalName, prefix);
+    const cleanDir = directory.replace(/\/+$/, ''); // Remover / final
+    return `${cleanDir}/${fileName}`;
+  }
+
+  /**
+   * Obtiene la extensión de un archivo.
+   *
+   * @param filename - Nombre del archivo
+   * @returns Extensión (sin el punto)
+   */
+  getExtension(filename: string): string {
+    const parts = filename.split('.');
+    return parts.length > 1 ? parts.pop()!.toLowerCase() : '';
+  }
+
+  /**
+   * Verifica si un archivo es una imagen basándose en su extensión.
+   */
+  isImage(filename: string): boolean {
+    const ext = this.getExtension(filename);
+    return ['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg', 'bmp'].includes(ext);
+  }
+
+  /**
+   * Verifica si un archivo es un documento.
+   */
+  isDocument(filename: string): boolean {
+    const ext = this.getExtension(filename);
+    return ['pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'txt'].includes(ext);
+  }
+
+  // ===========================================================================
+  // USER AVATAR HELPERS
+  // ===========================================================================
+
+  /**
+   * 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' = 'avatar'): string {
+    const bucket = this.config?.firebase?.storageBucket || 'myvaltech-dev.firebasestorage.app';
+    const path = `users/${userId}/${type}.jpg`;
+    return `https://firebasestorage.googleapis.com/v0/b/${bucket}/o/${encodeURIComponent(path)}?alt=media`;
+  }
+
+  // ===========================================================================
+  // MÉTODOS PRIVADOS
+  // ===========================================================================
+
+  /**
+   * Mapea el estado de la tarea de upload
+   */
+  private mapTaskState(state: string): UploadState {
+    switch (state) {
+      case 'running':
+        return 'running';
+      case 'paused':
+        return 'paused';
+      case 'success':
+        return 'success';
+      case 'canceled':
+        return 'canceled';
+      case 'error':
+        return 'error';
+      default:
+        return 'running';
+    }
+  }
+
+  /**
+   * Convierte errores de Storage a mensajes en español
+   */
+  private getErrorMessage(error: unknown): string {
+    if (error instanceof Error) {
+      const code = (error as { code?: string }).code;
+
+      switch (code) {
+        case 'storage/object-not-found':
+          return 'El archivo no existe';
+        case 'storage/unauthorized':
+          return 'No tienes permiso para acceder a este archivo';
+        case 'storage/canceled':
+          return 'La operación fue cancelada';
+        case 'storage/quota-exceeded':
+          return 'Se ha excedido la cuota de almacenamiento';
+        case 'storage/invalid-checksum':
+          return 'El archivo está corrupto';
+        case 'storage/retry-limit-exceeded':
+          return 'Error de conexión. Intenta de nuevo';
+        case 'storage/invalid-url':
+          return 'URL de archivo inválida';
+        case 'storage/invalid-argument':
+          return 'Argumento inválido';
+        default:
+          return error.message || 'Error de almacenamiento desconocido';
+      }
+    }
+
+    return 'Error de almacenamiento desconocido';
+  }
+}