valtech-components 2.0.417 → 2.0.418

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

@@ -1,140 +0,0 @@
-import { UserCredential } from '@angular/fire/auth';
-import { Observable } from 'rxjs';
-import { FirebaseUser, SessionState, ValtechFirebaseConfig } from './types';
-import * as i0 from "@angular/core";
-/**
- * Servicio de autenticación de Firebase.
- *
- * Este servicio NO maneja el login de usuarios directamente.
- * En su lugar, trabaja con Custom Tokens generados por tu backend.
- *
- * @example
- * ```typescript
- * // Después de autenticarte con tu backend (ej: Cognito)
- * @Component({...})
- * export class LoginComponent {
- *   private authService = inject(AuthService);     // Tu servicio de auth
- *   private firebase = inject(FirebaseService);    // Este servicio
- *
- *   async login(email: string, password: string) {
- *     // 1. Autenticar con tu backend
- *     const response = await this.authService.login(email, password);
- *
- *     // 2. El backend devuelve un Firebase Custom Token
- *     if (response.firebaseToken) {
- *       await this.firebase.signInWithCustomToken(response.firebaseToken);
- *     }
- *
- *     // Ahora el usuario puede acceder a Firestore, Storage, etc.
- *   }
- *
- *   async logout() {
- *     await this.authService.logout();
- *     await this.firebase.signOut();
- *   }
- * }
- * ```
- */
-export declare class FirebaseService {
-    private auth;
-    private config;
-    /** Estado interno de la sesión */
-    private sessionState;
-    /** Estado actual de la sesión como Observable */
-    readonly state$: Observable<SessionState>;
-    /** Usuario actual de Firebase como Observable */
-    readonly user$: Observable<FirebaseUser | null>;
-    /** Indica si el usuario está autenticado en Firebase */
-    readonly isAuthenticated$: Observable<boolean>;
-    constructor();
-    /**
-     * Autentica al usuario con un Custom Token generado por el backend.
-     *
-     * @param token - Firebase Custom Token generado por tu backend
-     * @returns UserCredential con la información del usuario
-     * @throws Error si el token es inválido o expiró
-     *
-     * @example
-     * ```typescript
-     * // Después de login exitoso con tu backend
-     * const { firebaseToken } = await backendAuth.login(email, password);
-     * await firebaseService.signInWithCustomToken(firebaseToken);
-     * ```
-     */
-    signInWithCustomToken(token: string): Promise<UserCredential>;
-    /**
-     * Cierra la sesión de Firebase.
-     * Llamar junto con el logout de tu sistema de autenticación principal.
-     *
-     * @example
-     * ```typescript
-     * async logout() {
-     *   await this.backendAuth.logout();    // Tu auth
-     *   await this.firebase.signOut();       // Firebase
-     * }
-     * ```
-     */
-    signOut(): Promise<void>;
-    /**
-     * Obtiene el usuario actual de Firebase (síncrono).
-     * Retorna null si no hay usuario autenticado.
-     */
-    get currentUser(): FirebaseUser | null;
-    /**
-     * Obtiene el UID del usuario actual.
-     * Retorna null si no hay usuario autenticado.
-     */
-    get uid(): string | null;
-    /**
-     * Indica si hay un usuario autenticado actualmente.
-     */
-    get isAuthenticated(): boolean;
-    /**
-     * Obtiene el ID Token de Firebase para el usuario actual.
-     * Útil para validar el usuario en tu backend.
-     *
-     * @param forceRefresh - Si true, fuerza la renovación del token
-     * @returns ID Token o null si no hay usuario
-     */
-    getIdToken(forceRefresh?: boolean): Promise<string | null>;
-    /**
-     * Obtiene los claims personalizados del token del usuario.
-     * Los claims son establecidos por tu backend al crear el Custom Token.
-     *
-     * @returns Objeto con los claims o vacío si no hay usuario
-     */
-    getClaims(): Promise<Record<string, unknown>>;
-    /**
-     * Verifica si el usuario tiene un rol específico.
-     * El rol debe estar definido en los claims del Custom Token.
-     *
-     * @param role - Nombre del rol a verificar
-     * @returns true si el usuario tiene el rol
-     */
-    hasRole(role: string): Promise<boolean>;
-    /**
-     * Espera a que el estado de autenticación esté determinado.
-     * Útil en guards o al inicializar la app.
-     *
-     * @returns Usuario actual o null
-     */
-    waitForAuth(): Promise<FirebaseUser | null>;
-    /**
-     * Obtiene la configuración actual de Firebase.
-     */
-    getConfig(): ValtechFirebaseConfig;
-    /**
-     * Indica si los emuladores están habilitados.
-     */
-    isUsingEmulators(): boolean;
-    /**
-     * Mapea un User de Firebase a nuestra interface FirebaseUser
-     */
-    private mapUser;
-    /**
-     * Convierte errores de Firebase a mensajes en español
-     */
-    private getErrorMessage;
-    static ɵfac: i0.ɵɵFactoryDeclaration<FirebaseService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<FirebaseService>;
-}

package/lib/services/firebase/firestore-collection.d.ts

@@ -1,195 +0,0 @@
-/**
- * Firestore Collection
- *
- * Clase base abstracta para crear servicios de colección tipados.
- * Extiende esta clase para tener un servicio dedicado por entidad.
- */
-import { Observable } from 'rxjs';
-import { FirestoreService } from './firestore.service';
-import { FirestoreDocument, PaginatedResult, QueryOptions } from './types';
-/**
- * Opciones de configuración para una colección.
- */
-export interface CollectionOptions {
-    /**
-     * Si true, usa soft delete (marca deletedAt en lugar de eliminar).
-     * Default: false
-     */
-    softDelete?: boolean;
-    /**
-     * Si true, maneja automáticamente createdAt/updatedAt.
-     * Default: true
-     */
-    timestamps?: boolean;
-}
-/**
- * Referencia a una sub-colección tipada.
- */
-export interface SubCollectionRef<T extends FirestoreDocument> {
-    getById(id: string): Promise<T | null>;
-    getAll(options?: QueryOptions): Promise<T[]>;
-    watch(id: string): Observable<T | null>;
-    watchAll(options?: QueryOptions): Observable<T[]>;
-    create(data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
-    update(id: string, data: Partial<T>): Promise<void>;
-    delete(id: string): Promise<void>;
-}
-/**
- * Clase base para servicios de colección tipados.
- *
- * Extiende esta clase para crear un servicio dedicado para cada entidad,
- * con métodos personalizados y tipado fuerte.
- *
- * @example
- * ```typescript
- * // Definir el modelo
- * interface User extends FirestoreDocument {
- *   name: string;
- *   email: string;
- *   role: 'admin' | 'user';
- *   active: boolean;
- * }
- *
- * // Crear el servicio
- * @Injectable({ providedIn: 'root' })
- * export class UsersCollection extends FirestoreCollection<User> {
- *   constructor() {
- *     super('users');
- *   }
- *
- *   // Métodos personalizados
- *   async getActiveUsers(): Promise<User[]> {
- *     return this.query({
- *       where: [{ field: 'active', operator: '==', value: true }]
- *     });
- *   }
- *
- *   async getAdmins(): Promise<User[]> {
- *     return this.query({
- *       where: [{ field: 'role', operator: '==', value: 'admin' }]
- *     });
- *   }
- *
- *   watchOnlineUsers(): Observable<User[]> {
- *     return this.watchQuery({
- *       where: [{ field: 'status', operator: '==', value: 'online' }]
- *     });
- *   }
- * }
- *
- * // Usar en componentes
- * @Component({...})
- * export class UsersComponent {
- *   private users = inject(UsersCollection);
- *
- *   admins$ = this.users.getAdmins();
- *   onlineUsers$ = this.users.watchOnlineUsers();
- *
- *   async createUser(data: Omit<User, 'id'>) {
- *     const user = await this.users.create(data);
- *   }
- * }
- * ```
- */
-export declare abstract class FirestoreCollection<T extends FirestoreDocument> {
-    protected firestore: FirestoreService;
-    protected readonly collectionPath: string;
-    protected readonly options: CollectionOptions;
-    /**
-     * @param collectionPath - Ruta de la colección en Firestore
-     * @param options - Opciones de configuración
-     */
-    constructor(collectionPath: string, options?: CollectionOptions);
-    /**
-     * Obtiene un documento por ID.
-     */
-    getById(id: string): Promise<T | null>;
-    /**
-     * Obtiene todos los documentos de la colección.
-     */
-    getAll(options?: QueryOptions): Promise<T[]>;
-    /**
-     * Ejecuta una query personalizada.
-     */
-    query(options: QueryOptions): Promise<T[]>;
-    /**
-     * Obtiene documentos con paginación.
-     */
-    paginate(options: QueryOptions & {
-        limit: number;
-    }): Promise<PaginatedResult<T>>;
-    /**
-     * Obtiene el primer documento que coincida con la query.
-     */
-    getFirst(options?: QueryOptions): Promise<T | null>;
-    /**
-     * Cuenta los documentos que coinciden con la query.
-     * Nota: Esto carga todos los documentos, usar con cuidado en colecciones grandes.
-     */
-    count(options?: QueryOptions): Promise<number>;
-    /**
-     * Verifica si un documento existe.
-     */
-    exists(id: string): Promise<boolean>;
-    /**
-     * Suscribe a cambios de un documento.
-     */
-    watch(id: string): Observable<T | null>;
-    /**
-     * Suscribe a cambios de la colección.
-     */
-    watchAll(options?: QueryOptions): Observable<T[]>;
-    /**
-     * Suscribe a una query personalizada.
-     */
-    watchQuery(options: QueryOptions): Observable<T[]>;
-    /**
-     * Crea un nuevo documento con ID auto-generado.
-     */
-    create(data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
-    /**
-     * Crea un documento con ID específico.
-     */
-    createWithId(id: string, data: Omit<T, 'id'>): Promise<void>;
-    /**
-     * Actualiza campos de un documento.
-     */
-    update(id: string, data: Partial<Omit<T, 'id' | 'createdAt'>>): Promise<void>;
-    /**
-     * Elimina un documento.
-     * Si softDelete está habilitado, marca como eliminado en lugar de borrar.
-     */
-    delete(id: string): Promise<void>;
-    /**
-     * Restaura un documento soft-deleted.
-     */
-    restore(id: string): Promise<void>;
-    /**
-     * Obtiene una referencia a una sub-colección.
-     *
-     * @example
-     * ```typescript
-     * // En UsersCollection
-     * getUserDocuments(userId: string) {
-     *   return this.subcollection<Document>(userId, 'documents');
-     * }
-     *
-     * // Uso
-     * const docs = await users.getUserDocuments('user123').getAll();
-     * ```
-     */
-    subcollection<S extends FirestoreDocument>(parentId: string, subcollectionName: string): SubCollectionRef<S>;
-    /**
-     * Aplica filtros por defecto a las queries.
-     * Override este método para agregar filtros globales (ej: excluir soft-deleted).
-     */
-    protected applyDefaultFilters(options?: QueryOptions): QueryOptions;
-    /**
-     * Genera un nuevo ID sin crear el documento.
-     */
-    generateId(): string;
-    /**
-     * Obtiene la ruta de la colección.
-     */
-    getPath(): string;
-}

package/lib/services/firebase/firestore.service.d.ts

@@ -1,303 +0,0 @@
-import { FieldValue } from '@angular/fire/firestore';
-import { Observable } from 'rxjs';
-import { FirestoreDocument, PaginatedResult, QueryOptions } from './types';
-import * as i0 from "@angular/core";
-/**
- * Servicio para operaciones CRUD en Firestore.
- *
- * @example
- * ```typescript
- * interface User extends FirestoreDocument {
- *   name: string;
- *   email: string;
- *   role: 'admin' | 'user';
- * }
- *
- * @Component({...})
- * export class UsersComponent {
- *   private firestore = inject(FirestoreService);
- *
- *   // Lectura one-time
- *   async loadUser(id: string) {
- *     const user = await this.firestore.getDoc<User>('users', id);
- *   }
- *
- *   // Subscripción real-time
- *   users$ = this.firestore.collectionChanges<User>('users', {
- *     where: [{ field: 'role', operator: '==', value: 'admin' }],
- *     orderBy: [{ field: 'name', direction: 'asc' }]
- *   });
- *
- *   // Crear documento
- *   async createUser(data: Omit<User, 'id'>) {
- *     const user = await this.firestore.addDoc<User>('users', data);
- *   }
- * }
- * ```
- */
-export declare class FirestoreService {
-    private firestore;
-    /**
-     * Obtiene un documento por ID (lectura única).
-     *
-     * @param collectionPath - Ruta de la colección
-     * @param docId - ID del documento
-     * @returns Documento o null si no existe
-     *
-     * @example
-     * ```typescript
-     * const user = await firestoreService.getDoc<User>('users', 'abc123');
-     * if (user) {
-     *   console.log(user.name);
-     * }
-     * ```
-     */
-    getDoc<T extends FirestoreDocument>(collectionPath: string, docId: string): Promise<T | null>;
-    /**
-     * Obtiene múltiples documentos con opciones de query.
-     *
-     * @param collectionPath - Ruta de la colección
-     * @param options - Opciones de query (where, orderBy, limit)
-     * @returns Array de documentos
-     *
-     * @example
-     * ```typescript
-     * // Todos los usuarios activos ordenados por nombre
-     * const users = await firestoreService.getDocs<User>('users', {
-     *   where: [{ field: 'active', operator: '==', value: true }],
-     *   orderBy: [{ field: 'name', direction: 'asc' }],
-     *   limit: 50
-     * });
-     * ```
-     */
-    getDocs<T extends FirestoreDocument>(collectionPath: string, options?: QueryOptions): Promise<T[]>;
-    /**
-     * Obtiene documentos con paginación basada en cursores.
-     *
-     * @param collectionPath - Ruta de la colección
-     * @param options - Opciones de query (debe incluir limit)
-     * @returns Resultado paginado con cursor para la siguiente página
-     *
-     * @example
-     * ```typescript
-     * // Primera página
-     * const page1 = await firestoreService.getPaginated<User>('users', {
-     *   orderBy: [{ field: 'createdAt', direction: 'desc' }],
-     *   limit: 10
-     * });
-     *
-     * // Siguiente página
-     * if (page1.hasMore) {
-     *   const page2 = await firestoreService.getPaginated<User>('users', {
-     *     orderBy: [{ field: 'createdAt', direction: 'desc' }],
-     *     limit: 10,
-     *     startAfter: page1.lastDoc
-     *   });
-     * }
-     * ```
-     */
-    getPaginated<T extends FirestoreDocument>(collectionPath: string, options: QueryOptions & {
-        limit: number;
-    }): Promise<PaginatedResult<T>>;
-    /**
-     * Verifica si un documento existe.
-     *
-     * @param collectionPath - Ruta de la colección
-     * @param docId - ID del documento
-     * @returns true si el documento existe
-     */
-    exists(collectionPath: string, docId: string): Promise<boolean>;
-    /**
-     * Suscribe a cambios de un documento (real-time).
-     *
-     * @param collectionPath - Ruta de la colección
-     * @param docId - ID del documento
-     * @returns Observable que emite cuando el documento cambia
-     *
-     * @example
-     * ```typescript
-     * // En el componente
-     * user$ = this.firestoreService.docChanges<User>('users', this.userId);
-     *
-     * // En el template
-     * @if (user$ | async; as user) {
-     *   <p>{{ user.name }}</p>
-     * }
-     * ```
-     */
-    docChanges<T extends FirestoreDocument>(collectionPath: string, docId: string): Observable<T | null>;
-    /**
-     * Suscribe a cambios de una colección (real-time).
-     *
-     * @param collectionPath - Ruta de la colección
-     * @param options - Opciones de query
-     * @returns Observable que emite cuando la colección cambia
-     *
-     * @example
-     * ```typescript
-     * // Usuarios activos en tiempo real
-     * activeUsers$ = this.firestoreService.collectionChanges<User>('users', {
-     *   where: [{ field: 'status', operator: '==', value: 'online' }]
-     * });
-     * ```
-     */
-    collectionChanges<T extends FirestoreDocument>(collectionPath: string, options?: QueryOptions): Observable<T[]>;
-    /**
-     * Agrega un documento con ID auto-generado.
-     *
-     * @param collectionPath - Ruta de la colección
-     * @param data - Datos del documento (sin id, createdAt, updatedAt)
-     * @returns Documento creado con su ID
-     *
-     * @example
-     * ```typescript
-     * const newUser = await firestoreService.addDoc<User>('users', {
-     *   name: 'John Doe',
-     *   email: 'john@example.com',
-     *   role: 'user'
-     * });
-     * console.log('Created user with ID:', newUser.id);
-     * ```
-     */
-    addDoc<T extends FirestoreDocument>(collectionPath: string, data: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
-    /**
-     * Crea o sobrescribe un documento con ID específico.
-     *
-     * @param collectionPath - Ruta de la colección
-     * @param docId - ID del documento
-     * @param data - Datos del documento
-     * @param options - Opciones (merge: true para merge en lugar de sobrescribir)
-     *
-     * @example
-     * ```typescript
-     * // Sobrescribir completamente
-     * await firestoreService.setDoc<User>('users', 'user123', userData);
-     *
-     * // Merge con datos existentes
-     * await firestoreService.setDoc<User>('users', 'user123', { name: 'New Name' }, { merge: true });
-     * ```
-     */
-    setDoc<T extends FirestoreDocument>(collectionPath: string, docId: string, data: Omit<T, 'id'>, options?: {
-        merge?: boolean;
-    }): Promise<void>;
-    /**
-     * Actualiza campos específicos de un documento.
-     *
-     * @param collectionPath - Ruta de la colección
-     * @param docId - ID del documento
-     * @param data - Campos a actualizar
-     *
-     * @example
-     * ```typescript
-     * await firestoreService.updateDoc<User>('users', 'user123', {
-     *   name: 'Updated Name',
-     *   lastLogin: new Date()
-     * });
-     * ```
-     */
-    updateDoc<T extends FirestoreDocument>(collectionPath: string, docId: string, data: Partial<Omit<T, 'id' | 'createdAt'>>): Promise<void>;
-    /**
-     * Elimina un documento.
-     *
-     * @param collectionPath - Ruta de la colección
-     * @param docId - ID del documento
-     *
-     * @example
-     * ```typescript
-     * await firestoreService.deleteDoc('users', 'user123');
-     * ```
-     */
-    deleteDoc(collectionPath: string, docId: string): Promise<void>;
-    /**
-     * Ejecuta múltiples operaciones de escritura de forma atómica.
-     *
-     * @param operations - Función que recibe el batch y agrega operaciones
-     *
-     * @example
-     * ```typescript
-     * await firestoreService.batch((batch) => {
-     *   batch.set('users/user1', { name: 'User 1' });
-     *   batch.update('users/user2', { status: 'inactive' });
-     *   batch.delete('users/user3');
-     * });
-     * ```
-     */
-    batch(operations: (batch: {
-        set: <T>(path: string, data: T) => void;
-        update: <T>(path: string, data: Partial<T>) => void;
-        delete: (path: string) => void;
-    }) => void): Promise<void>;
-    /**
-     * Construye una ruta a partir de un template.
-     *
-     * @param template - Template con placeholders {param}
-     * @param params - Valores para los placeholders
-     * @returns Ruta construida
-     *
-     * @example
-     * ```typescript
-     * const path = firestoreService.buildPath('users/{userId}/documents/{docId}', {
-     *   userId: 'user123',
-     *   docId: 'doc456'
-     * });
-     * // => 'users/user123/documents/doc456'
-     * ```
-     */
-    buildPath(template: string, params: Record<string, string>): string;
-    /**
-     * Genera un ID único para un documento (sin crearlo).
-     *
-     * @param collectionPath - Ruta de la colección
-     * @returns ID único generado por Firestore
-     */
-    generateId(collectionPath: string): string;
-    /**
-     * Retorna un valor de timestamp del servidor.
-     * Usar en campos de fecha para que Firestore asigne el timestamp.
-     */
-    serverTimestamp(): FieldValue;
-    /**
-     * Retorna un valor para agregar elementos a un array.
-     *
-     * @example
-     * ```typescript
-     * await firestoreService.updateDoc('users', 'user123', {
-     *   tags: firestoreService.arrayUnion('new-tag')
-     * });
-     * ```
-     */
-    arrayUnion(...elements: unknown[]): FieldValue;
-    /**
-     * Retorna un valor para remover elementos de un array.
-     */
-    arrayRemove(...elements: unknown[]): FieldValue;
-    /**
-     * Retorna un valor para incrementar un campo numérico.
-     *
-     * @example
-     * ```typescript
-     * await firestoreService.updateDoc('users', 'user123', {
-     *   loginCount: firestoreService.increment(1)
-     * });
-     * ```
-     */
-    increment(n: number): FieldValue;
-    /**
-     * Construye los QueryConstraints a partir de QueryOptions
-     */
-    private buildQueryConstraints;
-    /**
-     * Mapea un DocumentSnapshot a nuestro tipo
-     */
-    private mapDocument;
-    /**
-     * Convierte Timestamps de Firestore a Date de JavaScript
-     */
-    private convertTimestamps;
-    /**
-     * Divide una ruta de documento en colección e ID
-     */
-    private splitPath;
-    static ɵfac: i0.ɵɵFactoryDeclaration<FirestoreService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<FirestoreService>;
-}

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

@@ -1,38 +0,0 @@
-/**
- * Firebase Services
- *
- * Servicios reutilizables para integración con Firebase.
- *
- * @example
- * ```typescript
- * // En main.ts
- * import { provideValtechFirebase } from 'valtech-components';
- *
- * bootstrapApplication(AppComponent, {
- *   providers: [
- *     provideValtechFirebase({
- *       firebase: environment.firebase,
- *       persistence: true,
- *     }),
- *   ],
- * });
- *
- * // En componentes
- * import { FirebaseService, FirestoreService } from 'valtech-components';
- *
- * @Component({...})
- * export class MyComponent {
- *   private firebase = inject(FirebaseService);
- *   private firestore = inject(FirestoreService);
- * }
- * ```
- */
-export * from './types';
-export { VALTECH_FIREBASE_CONFIG, hasEmulators, provideValtechFirebase } from './config';
-export { FirebaseService } from './firebase.service';
-export { FirestoreService } from './firestore.service';
-export { CollectionOptions, FirestoreCollection, SubCollectionRef } from './firestore-collection';
-export { QueryBuilder, query } from './utils/query-builder';
-export { buildPath, extractPathParams, getCollectionPath, getDocumentId, isCollectionPath, isDocumentPath, isValidPath, joinPath, } from './utils/path-builder';
-export { StorageService } from './storage.service';
-export { MessagingService } from './messaging.service';