valtech-components 2.0.417 → 2.0.418

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

@@ -1,281 +0,0 @@
-/**
- * Firebase Types
- *
- * Tipos e interfaces para la integración de Firebase en valtech-components.
- * Todos los modelos de Firestore deben extender FirestoreDocument.
- */
-/**
- * Configuración de Firebase (valores de firebaseConfig)
- */
-export interface FirebaseConfig {
-    apiKey: string;
-    authDomain: string;
-    projectId: string;
-    storageBucket: string;
-    messagingSenderId: string;
-    appId: string;
-    measurementId?: 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 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;
-}
-/**
- * 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;
-}
-/**
- * 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 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

@@ -1,132 +0,0 @@
-/**
- * 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

@@ -1,210 +0,0 @@
-/**
- * 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;