valtech-components 2.0.687 → 2.0.689

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

@@ -0,0 +1,461 @@
+/**
+ * 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
+// ============================================================================
+
+/**
+ * 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 const DEFAULT_EMULATOR_CONFIG: EmulatorConfig = {
+  firestore: { host: 'localhost', port: 9080 },
+  storage: { host: 'localhost', port: 9199 },
+  auth: { host: 'localhost', port: 9099 },
+};
+
+/**
+ * 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;
+}
+
+// ============================================================================
+// FIRESTORE - DOCUMENTOS
+// ============================================================================
+
+/**
+ * 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;
+}
+
+// ============================================================================
+// FIRESTORE - QUERIES
+// ============================================================================
+
+/**
+ * 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;
+}
+
+// ============================================================================
+// STORAGE
+// ============================================================================
+
+/**
+ * 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;
+}
+
+// ============================================================================
+// RBAC - PERMISOS Y ORGANIZACIONES
+// ============================================================================
+
+/**
+ * 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[];
+}
+
+// ============================================================================
+// AUTH / SESSION
+// ============================================================================
+
+/**
+ * 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;
+}
+
+// ============================================================================
+// MESSAGING (FCM)
+// ============================================================================
+
+/**
+ * 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;
+}
+
+// ============================================================================
+// ERRORES
+// ============================================================================
+
+/**
+ * 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;
+}

package/src/lib/services/firebase/utils/path-builder.ts

@@ -0,0 +1,210 @@
+/**
+ * Path Builder
+ *
+ * Utilidades para construir rutas de Firestore con templates.
+ * Soporta rutas multi-nivel y anidadas.
+ */
+
+/**
+ * Construye una ruta de Firestore reemplazando placeholders.
+ *
+ * @param template - Template con placeholders en formato {param}
+ * @param params - Objeto con los valores a reemplazar
+ * @returns Ruta construida
+ * @throws Error si faltan parámetros requeridos
+ *
+ * @example
+ * ```typescript
+ * // Ruta simple
+ * buildPath('users/{userId}', { userId: 'abc123' });
+ * // => 'users/abc123'
+ *
+ * // Ruta anidada
+ * buildPath('users/{userId}/documents/{docId}', {
+ *   userId: 'abc123',
+ *   docId: 'doc456'
+ * });
+ * // => 'users/abc123/documents/doc456'
+ *
+ * // Múltiples niveles
+ * buildPath('orgs/{orgId}/teams/{teamId}/members/{memberId}', {
+ *   orgId: 'org1',
+ *   teamId: 'team2',
+ *   memberId: 'member3'
+ * });
+ * // => 'orgs/org1/teams/team2/members/member3'
+ * ```
+ */
+export function buildPath(template: string, params: Record<string, string>): string {
+  let result = template;
+
+  // Encontrar todos los placeholders
+  const placeholders = template.match(/\{([^}]+)\}/g);
+
+  if (!placeholders) {
+    return template;
+  }
+
+  for (const placeholder of placeholders) {
+    const key = placeholder.slice(1, -1); // Remover { y }
+    const value = params[key];
+
+    if (value === undefined || value === null) {
+      throw new Error(`Parámetro requerido '${key}' no proporcionado para la ruta: ${template}`);
+    }
+
+    if (typeof value !== 'string' || value.trim() === '') {
+      throw new Error(`El parámetro '${key}' debe ser un string no vacío`);
+    }
+
+    // Validar que no contenga caracteres inválidos para Firestore
+    if (value.includes('/')) {
+      throw new Error(`El parámetro '${key}' no puede contener '/'`);
+    }
+
+    result = result.replace(placeholder, value);
+  }
+
+  return result;
+}
+
+/**
+ * Extrae los nombres de los parámetros de un template de ruta.
+ *
+ * @param template - Template de ruta
+ * @returns Array con los nombres de los parámetros
+ *
+ * @example
+ * ```typescript
+ * extractParams('users/{userId}/documents/{docId}');
+ * // => ['userId', 'docId']
+ * ```
+ */
+export function extractPathParams(template: string): string[] {
+  const matches = template.match(/\{([^}]+)\}/g);
+  if (!matches) return [];
+  return matches.map((m) => m.slice(1, -1));
+}
+
+/**
+ * Valida que una ruta de Firestore sea válida.
+ *
+ * @param path - Ruta a validar
+ * @returns true si la ruta es válida
+ *
+ * @example
+ * ```typescript
+ * isValidPath('users/abc123');           // true
+ * isValidPath('users/abc123/documents'); // true
+ * isValidPath('users//documents');       // false (segmento vacío)
+ * isValidPath('');                       // false (vacío)
+ * ```
+ */
+export function isValidPath(path: string): boolean {
+  if (!path || path.trim() === '') return false;
+
+  const segments = path.split('/');
+
+  // No puede tener segmentos vacíos
+  if (segments.some((s) => s.trim() === '')) return false;
+
+  // No puede empezar o terminar con /
+  if (path.startsWith('/') || path.endsWith('/')) return false;
+
+  return true;
+}
+
+/**
+ * Obtiene la ruta de la colección padre de un documento.
+ *
+ * @param documentPath - Ruta completa del documento
+ * @returns Ruta de la colección padre
+ *
+ * @example
+ * ```typescript
+ * getCollectionPath('users/abc123');
+ * // => 'users'
+ *
+ * getCollectionPath('users/abc123/documents/doc456');
+ * // => 'users/abc123/documents'
+ * ```
+ */
+export function getCollectionPath(documentPath: string): string {
+  const segments = documentPath.split('/');
+  if (segments.length < 2) {
+    throw new Error(`Ruta de documento inválida: ${documentPath}`);
+  }
+  return segments.slice(0, -1).join('/');
+}
+
+/**
+ * Obtiene el ID del documento de una ruta.
+ *
+ * @param documentPath - Ruta completa del documento
+ * @returns ID del documento
+ *
+ * @example
+ * ```typescript
+ * getDocumentId('users/abc123');
+ * // => 'abc123'
+ *
+ * getDocumentId('users/abc123/documents/doc456');
+ * // => 'doc456'
+ * ```
+ */
+export function getDocumentId(documentPath: string): string {
+  const segments = documentPath.split('/');
+  if (segments.length < 2 || segments.length % 2 !== 0) {
+    throw new Error(`Ruta de documento inválida: ${documentPath}`);
+  }
+  return segments[segments.length - 1];
+}
+
+/**
+ * Verifica si una ruta apunta a un documento (número par de segmentos).
+ *
+ * @param path - Ruta a verificar
+ * @returns true si es una ruta de documento
+ *
+ * @example
+ * ```typescript
+ * isDocumentPath('users/abc123');           // true
+ * isDocumentPath('users');                  // false (colección)
+ * isDocumentPath('users/abc123/documents'); // false (colección)
+ * ```
+ */
+export function isDocumentPath(path: string): boolean {
+  const segments = path.split('/').filter((s) => s.trim() !== '');
+  return segments.length > 0 && segments.length % 2 === 0;
+}
+
+/**
+ * Verifica si una ruta apunta a una colección (número impar de segmentos).
+ *
+ * @param path - Ruta a verificar
+ * @returns true si es una ruta de colección
+ */
+export function isCollectionPath(path: string): boolean {
+  const segments = path.split('/').filter((s) => s.trim() !== '');
+  return segments.length > 0 && segments.length % 2 !== 0;
+}
+
+/**
+ * Combina una ruta base con segmentos adicionales.
+ *
+ * @param basePath - Ruta base
+ * @param segments - Segmentos adicionales
+ * @returns Ruta combinada
+ *
+ * @example
+ * ```typescript
+ * joinPath('users', 'abc123', 'documents');
+ * // => 'users/abc123/documents'
+ * ```
+ */
+export function joinPath(...segments: string[]): string {
+  return segments
+    .filter((s) => s && s.trim() !== '')
+    .map((s) => s.replace(/^\/+|\/+$/g, '')) // Remover / al inicio y final
+    .join('/');
+}