valtech-components 2.0.691 → 2.0.693

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

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

@@ -0,0 +1,132 @@
+/**
+ * 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 declare function buildPath(template: string, params: Record<string, string>): string;
+/**
+ * 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 declare function extractPathParams(template: string): string[];
+/**
+ * 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 declare function isValidPath(path: string): boolean;
+/**
+ * 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 declare function getCollectionPath(documentPath: string): string;
+/**
+ * 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 declare function getDocumentId(documentPath: string): string;
+/**
+ * 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 declare function isDocumentPath(path: string): boolean;
+/**
+ * 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 declare function isCollectionPath(path: string): boolean;
+/**
+ * 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 declare function joinPath(...segments: string[]): string;

package/lib/services/firebase/utils/query-builder.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Query Builder
+ *
+ * Builder fluido para construir queries de Firestore de manera legible.
+ * Alternativa más expresiva a pasar objetos QueryOptions directamente.
+ */
+import { OrderDirection, QueryOptions, WhereOperator } from '../types';
+/**
+ * Builder fluido para queries de Firestore.
+ *
+ * @example
+ * ```typescript
+ * // Construir query con builder
+ * const options = new QueryBuilder()
+ *   .where('status', '==', 'active')
+ *   .where('age', '>=', 18)
+ *   .orderBy('createdAt', 'desc')
+ *   .limit(10)
+ *   .build();
+ *
+ * // Usar con FirestoreService
+ * const users = await firestoreService.getDocs<User>('users', options);
+ *
+ * // O con método estático
+ * const options2 = QueryBuilder.create()
+ *   .where('category', '==', 'electronics')
+ *   .orderBy('price', 'asc')
+ *   .build();
+ * ```
+ */
+export declare class QueryBuilder {
+    private whereConditions;
+    private orderByConditions;
+    private limitValue?;
+    private startAfterValue?;
+    private startAtValue?;
+    private endBeforeValue?;
+    private endAtValue?;
+    /**
+     * Crea una nueva instancia del builder (método estático alternativo).
+     */
+    static create(): QueryBuilder;
+    /**
+     * Agrega una condición where.
+     *
+     * @param field - Campo a filtrar
+     * @param operator - Operador de comparación
+     * @param value - Valor a comparar
+     *
+     * @example
+     * ```typescript
+     * builder.where('status', '==', 'active')
+     * builder.where('price', '>=', 100)
+     * builder.where('tags', 'array-contains', 'featured')
+     * builder.where('category', 'in', ['electronics', 'books'])
+     * ```
+     */
+    where(field: string, operator: WhereOperator, value: unknown): QueryBuilder;
+    /**
+     * Shortcut para where con operador '=='.
+     *
+     * @example
+     * ```typescript
+     * builder.whereEquals('status', 'active')
+     * // equivalente a: builder.where('status', '==', 'active')
+     * ```
+     */
+    whereEquals(field: string, value: unknown): QueryBuilder;
+    /**
+     * Shortcut para where con operador '!='.
+     */
+    whereNotEquals(field: string, value: unknown): QueryBuilder;
+    /**
+     * Shortcut para where con operador '>'.
+     */
+    whereGreaterThan(field: string, value: unknown): QueryBuilder;
+    /**
+     * Shortcut para where con operador '>='.
+     */
+    whereGreaterOrEqual(field: string, value: unknown): QueryBuilder;
+    /**
+     * Shortcut para where con operador '<'.
+     */
+    whereLessThan(field: string, value: unknown): QueryBuilder;
+    /**
+     * Shortcut para where con operador '<='.
+     */
+    whereLessOrEqual(field: string, value: unknown): QueryBuilder;
+    /**
+     * Shortcut para where con operador 'array-contains'.
+     *
+     * @example
+     * ```typescript
+     * builder.whereArrayContains('tags', 'featured')
+     * ```
+     */
+    whereArrayContains(field: string, value: unknown): QueryBuilder;
+    /**
+     * Shortcut para where con operador 'array-contains-any'.
+     *
+     * @example
+     * ```typescript
+     * builder.whereArrayContainsAny('tags', ['featured', 'new'])
+     * ```
+     */
+    whereArrayContainsAny(field: string, values: unknown[]): QueryBuilder;
+    /**
+     * Shortcut para where con operador 'in'.
+     *
+     * @example
+     * ```typescript
+     * builder.whereIn('status', ['active', 'pending'])
+     * ```
+     */
+    whereIn(field: string, values: unknown[]): QueryBuilder;
+    /**
+     * Shortcut para where con operador 'not-in'.
+     */
+    whereNotIn(field: string, values: unknown[]): QueryBuilder;
+    /**
+     * Agrega ordenamiento por un campo.
+     *
+     * @param field - Campo por el cual ordenar
+     * @param direction - Dirección: 'asc' o 'desc' (default: 'asc')
+     *
+     * @example
+     * ```typescript
+     * builder.orderBy('createdAt', 'desc')
+     * builder.orderBy('name') // asc por defecto
+     * ```
+     */
+    orderBy(field: string, direction?: OrderDirection): QueryBuilder;
+    /**
+     * Shortcut para orderBy descendente.
+     */
+    orderByDesc(field: string): QueryBuilder;
+    /**
+     * Shortcut para orderBy ascendente.
+     */
+    orderByAsc(field: string): QueryBuilder;
+    /**
+     * Limita el número de resultados.
+     *
+     * @param count - Número máximo de documentos
+     *
+     * @example
+     * ```typescript
+     * builder.limit(10)
+     * ```
+     */
+    limit(count: number): QueryBuilder;
+    /**
+     * Cursor para paginación: empezar después de un documento.
+     *
+     * @param cursor - Documento o snapshot desde donde continuar
+     *
+     * @example
+     * ```typescript
+     * // Primera página
+     * const page1 = await service.getPaginated('users', builder.limit(10).build());
+     *
+     * // Siguiente página
+     * const page2 = await service.getPaginated('users',
+     *   builder.startAfter(page1.lastDoc).limit(10).build()
+     * );
+     * ```
+     */
+    startAfter(cursor: unknown): QueryBuilder;
+    /**
+     * Cursor para paginación: empezar en un documento.
+     */
+    startAt(cursor: unknown): QueryBuilder;
+    /**
+     * Cursor para paginación: terminar antes de un documento.
+     */
+    endBefore(cursor: unknown): QueryBuilder;
+    /**
+     * Cursor para paginación: terminar en un documento.
+     */
+    endAt(cursor: unknown): QueryBuilder;
+    /**
+     * Construye el objeto QueryOptions.
+     *
+     * @returns QueryOptions para usar con FirestoreService
+     */
+    build(): QueryOptions;
+    /**
+     * Resetea el builder para reutilización.
+     */
+    reset(): QueryBuilder;
+    /**
+     * Clona el builder actual.
+     */
+    clone(): QueryBuilder;
+}
+/**
+ * Función helper para crear un QueryBuilder.
+ *
+ * @example
+ * ```typescript
+ * import { query } from 'valtech-components';
+ *
+ * const options = query()
+ *   .where('status', '==', 'active')
+ *   .orderBy('createdAt', 'desc')
+ *   .limit(10)
+ *   .build();
+ * ```
+ */
+export declare function query(): QueryBuilder;