valtech-components 2.0.821 → 2.0.824

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

@@ -0,0 +1,134 @@
+import { Observable } from 'rxjs';
+import { CreateFeedbackResponse, GetFeedbackResponse, CheckFeedbackResponse, DeviceContext, FeedbackType, ContentRef, EntityRef, ReactionValue } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Servicio para gestionar feedback de usuarios.
+ *
+ * @example
+ * ```typescript
+ * @Component({...})
+ * export class MyComponent {
+ *   private feedbackService = inject(FeedbackService);
+ *
+ *   async submitFeedback() {
+ *     const response = await this.feedbackService.createAsync(
+ *       'feedback',
+ *       'Mi comentario',
+ *       'Descripción detallada...'
+ *     );
+ *     console.log('Feedback enviado:', response.feedbackId);
+ *   }
+ * }
+ * ```
+ */
+export declare class FeedbackService {
+    private config;
+    private http;
+    private firestore;
+    private auth;
+    /**
+     * URL base para endpoints de feedback.
+     */
+    private get baseUrl();
+    /**
+     * Captura el contexto del dispositivo automáticamente.
+     */
+    captureDeviceContext(): DeviceContext;
+    /**
+     * Crea un nuevo feedback.
+     *
+     * @param type - Tipo de feedback
+     * @param title - Título del feedback
+     * @param description - Descripción detallada
+     * @param attachments - URLs de archivos adjuntos (opcional)
+     * @param contentRef - Referencia a contenido específico (opcional)
+     * @returns Observable con la respuesta
+     */
+    create(type: FeedbackType, title: string, description: string, attachments?: string[], contentRef?: ContentRef): Observable<CreateFeedbackResponse>;
+    /**
+     * Crea un nuevo feedback (versión async/await).
+     */
+    createAsync(type: FeedbackType, title: string, description: string, attachments?: string[], contentRef?: ContentRef): Promise<CreateFeedbackResponse>;
+    /**
+     * Obtiene un feedback por ID (solo el propietario).
+     *
+     * @param feedbackId - ID del feedback
+     * @returns Observable con la respuesta
+     */
+    getById(feedbackId: string): Observable<GetFeedbackResponse>;
+    /**
+     * Obtiene un feedback por ID (versión async/await).
+     */
+    getByIdAsync(feedbackId: string): Promise<GetFeedbackResponse>;
+    /**
+     * Valida si un archivo cumple con las restricciones.
+     */
+    validateFile(file: File): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * Obtiene la configuración actual del servicio.
+     */
+    getConfig(): Readonly<typeof this.config>;
+    /**
+     * Verifica si el usuario ya dio feedback para una entidad específica.
+     *
+     * Primero intenta leer de Firebase (rápido, sin latencia de red al backend).
+     * Si Firebase no está disponible o falla, hace fallback a la API.
+     *
+     * @param entityType - Tipo de entidad (article, docs, feature, etc.)
+     * @param entityId - ID de la entidad
+     * @returns Promise con la respuesta de verificación
+     *
+     * @example
+     * ```typescript
+     * const check = await this.feedbackService.checkFeedback('article', 'art-123');
+     * if (check.hasFeedback) {
+     *   console.log('Ya dio feedback:', check.reactionValue);
+     * }
+     * ```
+     */
+    checkFeedback(entityType: string, entityId: string): Promise<CheckFeedbackResponse>;
+    /**
+     * Crea o actualiza una reacción (feedback con emoji).
+     *
+     * @param entityRef - Referencia a la entidad
+     * @param value - Valor de la reacción (negative, neutral, positive)
+     * @param comment - Comentario opcional (máx 500 caracteres)
+     * @returns Promise con la respuesta
+     *
+     * @example
+     * ```typescript
+     * const response = await this.feedbackService.createReaction(
+     *   { entityType: 'article', entityId: 'art-123' },
+     *   'positive',
+     *   'Muy útil!'
+     * );
+     * ```
+     */
+    createReaction(entityRef: EntityRef, value: ReactionValue, comment?: string): Promise<CreateFeedbackResponse>;
+    /**
+     * Crea feedback anónimo (sin autenticación requerida).
+     * Usado para blogs, FAQs y contenido público.
+     *
+     * @param entityRef - Referencia a la entidad
+     * @param value - Valor de la reacción (negative, neutral, positive)
+     * @param comment - Comentario opcional (máx 500 caracteres)
+     * @returns Promise con la respuesta
+     *
+     * @example
+     * ```typescript
+     * // En un blog público
+     * const response = await this.feedbackService.createAnonymousReaction(
+     *   { entityType: 'blog', entityId: 'my-post-slug' },
+     *   'positive'
+     * );
+     * ```
+     */
+    createAnonymousReaction(entityRef: EntityRef, value: ReactionValue, comment?: string): Promise<CreateFeedbackResponse>;
+    private detectBrowser;
+    private detectOS;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FeedbackService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FeedbackService>;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Valtech Feedback Service
+ *
+ * Servicio para gestionar feedback de usuarios a nivel de plataforma.
+ *
+ * @example
+ * ```typescript
+ * // main.ts - Configuración
+ * import { provideValtechFeedback } from 'valtech-components';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideValtechAuth({ apiUrl: environment.apiUrl }),
+ *     provideValtechFeedback({
+ *       apiUrl: environment.apiUrl,
+ *       appId: 'my-app-name',
+ *     }),
+ *   ],
+ * });
+ *
+ * // component.ts - Uso
+ * import { FeedbackService } from 'valtech-components';
+ *
+ * @Component({...})
+ * export class MyComponent {
+ *   private feedbackService = inject(FeedbackService);
+ *
+ *   async submitFeedback() {
+ *     const response = await this.feedbackService.createAsync(
+ *       'feedback',
+ *       'Título',
+ *       'Descripción...'
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export { VALTECH_FEEDBACK_CONFIG, provideValtechFeedback, DEFAULT_FEEDBACK_CONFIG } from './config';
+export { FeedbackService } from './feedback.service';
+export { ValtechFeedbackConfig, FeedbackType, FeedbackStatus, ContentType, ContentRef, DeviceContext, Feedback, CreateFeedbackRequest, CreateFeedbackResponse, GetFeedbackResponse, FeedbackTypeOption, DEFAULT_FEEDBACK_TYPE_OPTIONS, } from './types';

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

@@ -0,0 +1,173 @@
+/**
+ * Configuración del servicio de Feedback.
+ */
+export interface ValtechFeedbackConfig {
+    /** URL base de la API */
+    apiUrl: string;
+    /** ID de la aplicación (ej: 'my-valtech-app') */
+    appId: string;
+    /** Prefijo para endpoints (default: '/v1/feedback') */
+    feedbackPrefix?: string;
+    /** Número máximo de adjuntos (default: 5) */
+    maxAttachments?: number;
+    /** Tamaño máximo por archivo en bytes (default: 10MB) */
+    maxFileSize?: number;
+    /** Tipos de archivo permitidos (default: ['image/*', 'video/*', 'application/pdf']) */
+    allowedFileTypes?: string[];
+    /** Ruta en Firebase Storage para adjuntos (default: 'feedback') */
+    storagePath?: string;
+}
+/**
+ * Tipos de feedback disponibles.
+ */
+export type FeedbackType = 'issue' | 'poor-content' | 'feedback' | 'suggestion' | 'reaction';
+/**
+ * Valor de reacción (para feedback tipo emoji).
+ */
+export type ReactionValue = 'negative' | 'neutral' | 'positive';
+/**
+ * Estado de un feedback.
+ */
+export type FeedbackStatus = 'new' | 'reviewed' | 'resolved';
+/**
+ * Tipos de contenido para referencia.
+ */
+export type ContentType = 'article' | 'faq' | 'news' | 'page' | 'product' | 'event' | 'other';
+/**
+ * Referencia a contenido específico.
+ */
+export interface ContentRef {
+    contentId: string;
+    contentType: ContentType;
+}
+/**
+ * Referencia a entidad (para reactions y feedback de contenido).
+ */
+export interface EntityRef {
+    /** Tipo de entidad: 'article', 'docs', 'feature', 'bug', etc. */
+    entityType: string;
+    /** ID de la entidad */
+    entityId: string;
+}
+/**
+ * Contexto del dispositivo del usuario.
+ */
+export interface DeviceContext {
+    browser: string;
+    os: string;
+    viewport: string;
+    language: string;
+    userAgent: string;
+    pageUrl: string;
+}
+/**
+ * Entrada de feedback completa.
+ */
+export interface Feedback {
+    feedbackId: string;
+    appId: string;
+    userId: string;
+    type: FeedbackType;
+    title: string;
+    description: string;
+    attachments: string[];
+    contentRef?: ContentRef;
+    entityRef?: EntityRef;
+    reactionValue?: ReactionValue;
+    deviceContext: DeviceContext;
+    status: FeedbackStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Request para crear feedback.
+ */
+export interface CreateFeedbackRequest {
+    type: FeedbackType;
+    title?: string;
+    description?: string;
+    attachments?: string[];
+    contentRef?: ContentRef;
+    entityRef?: EntityRef;
+    reactionValue?: ReactionValue;
+    deviceContext: DeviceContext;
+    appId: string;
+}
+/**
+ * Response al crear feedback.
+ */
+export interface CreateFeedbackResponse {
+    operationId: string;
+    feedbackId: string;
+    status: FeedbackStatus;
+    createdAt: string;
+}
+/**
+ * Response al obtener feedback.
+ */
+export interface GetFeedbackResponse {
+    operationId: string;
+    feedback: Feedback;
+}
+/**
+ * Opciones de tipo de feedback para UI.
+ */
+export interface FeedbackTypeOption {
+    value: FeedbackType;
+    label: string;
+    description?: string;
+    icon?: string;
+}
+/**
+ * Configuración por defecto de tipos de feedback.
+ */
+export declare const DEFAULT_FEEDBACK_TYPE_OPTIONS: FeedbackTypeOption[];
+/**
+ * Response al verificar si existe feedback para una entidad.
+ */
+export interface CheckFeedbackResponse {
+    operationId: string;
+    hasFeedback: boolean;
+    feedbackId?: string;
+    type?: FeedbackType;
+    reactionValue?: ReactionValue;
+    createdAt?: string;
+}
+/**
+ * Request para listar feedback (admin).
+ */
+export interface ListFeedbackRequest {
+    appId?: string;
+    type?: FeedbackType;
+    status?: FeedbackStatus;
+    entityType?: string;
+    entityId?: string;
+    userId?: string;
+    dateFrom?: string;
+    dateTo?: string;
+    limit?: number;
+    nextToken?: string;
+}
+/**
+ * Response al listar feedback.
+ */
+export interface ListFeedbackResponse {
+    operationId: string;
+    feedbacks: Feedback[];
+    nextToken?: string;
+    count: number;
+}
+/**
+ * Documento de feedback en Firestore.
+ * Usado para lectura rápida del estado de feedback del usuario.
+ *
+ * Path: apps/{appId}/feedback/{entityType}/{entityId}/{userId}
+ */
+export interface FeedbackFirestoreDoc {
+    id?: string;
+    feedbackId: string;
+    type: string;
+    reactionValue: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}

package/lib/services/firebase/analytics-error-handler.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Analytics Error Handler
+ *
+ * ErrorHandler personalizado que envía errores no capturados a Firebase Analytics.
+ * Se activa si enableErrorTracking=true en analyticsConfig.
+ */
+import { ErrorHandler } from '@angular/core';
+import * as i0 from "@angular/core";
+/**
+ * ErrorHandler que trackea errores en Firebase Analytics.
+ *
+ * Captura errores no manejados de la aplicación y los envía a GA4
+ * como eventos 'error_occurred'. También delega al ErrorHandler
+ * default para mantener el comportamiento de console.error.
+ *
+ * @example
+ * ```typescript
+ * // Se activa automáticamente si enableErrorTracking=true
+ * provideValtechFirebase({
+ *   firebase: environment.firebase,
+ *   enableAnalytics: true,
+ *   analyticsConfig: {
+ *     enableErrorTracking: true,
+ *   },
+ * });
+ * ```
+ */
+export declare class AnalyticsErrorHandler implements ErrorHandler {
+    private readonly analytics;
+    private readonly defaultHandler;
+    /**
+     * Maneja un error no capturado.
+     * Envía el error a Analytics y luego al handler default.
+     */
+    handleError(error: unknown): void;
+    /**
+     * Trackea el error en Analytics
+     */
+    private trackError;
+    /**
+     * Extrae información útil del error
+     */
+    private extractErrorInfo;
+    /**
+     * Verifica si es un PromiseRejectionEvent
+     */
+    private isPromiseRejection;
+    /**
+     * Obtiene la URL actual de forma segura
+     */
+    private getCurrentUrl;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AnalyticsErrorHandler, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AnalyticsErrorHandler>;
+}

package/lib/services/firebase/analytics-router-tracker.d.ts

@@ -0,0 +1,51 @@
+import { ValtechFirebaseConfig } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Tracker automático de page views via Router.
+ *
+ * Este servicio escucha eventos de navegación del Router y registra
+ * page views automáticamente en Firebase Analytics.
+ *
+ * Se excluyen rutas configuradas en `analyticsConfig.excludeRoutes`.
+ *
+ * @example
+ * ```typescript
+ * // Se activa automáticamente si enablePageViewTracking=true
+ * provideValtechFirebase({
+ *   firebase: environment.firebase,
+ *   enableAnalytics: true,
+ *   analyticsConfig: {
+ *     enablePageViewTracking: true,
+ *     excludeRoutes: ['/admin/*', '/debug/*'],
+ *   },
+ * });
+ * ```
+ */
+export declare class AnalyticsRouterTracker {
+    private config;
+    private readonly analytics;
+    private readonly router;
+    private readonly destroyRef;
+    private readonly excludePatterns;
+    private readonly enabled;
+    constructor(config: ValtechFirebaseConfig);
+    /**
+     * Inicia el tracking de navegación
+     */
+    private startTracking;
+    /**
+     * Compila patrones de exclusión a RegExp
+     */
+    private compileExcludePatterns;
+    /**
+     * Verifica si una URL debe ser excluida del tracking
+     */
+    private isExcluded;
+    /**
+     * Registra un page view manualmente.
+     * Útil para casos donde necesitas trackear manualmente.
+     */
+    trackPageView(path: string, title?: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AnalyticsRouterTracker, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AnalyticsRouterTracker>;
+}

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

@@ -0,0 +1,221 @@
+/**
+ * Analytics Types
+ *
+ * Tipos e interfaces para el servicio de Firebase Analytics (GA4).
+ */
+/**
+ * Configuración de Analytics para ValtechFirebaseConfig
+ */
+export interface AnalyticsConfig {
+    /** Habilitar tracking automático de page views via Router (default: true) */
+    enablePageViewTracking?: boolean;
+    /** Habilitar tracking automático de errores via ErrorHandler (default: false) */
+    enableErrorTracking?: boolean;
+    /** Habilitar integración con auth para userId y userProperties (default: true) */
+    enableAuthIntegration?: boolean;
+    /** Modo debug: logea a consola además de enviar a Firebase (default: false) */
+    debugMode?: boolean;
+    /** Auto-grant consent para desarrollo/testing (default: false) */
+    defaultConsentGranted?: boolean;
+    /** Rutas a excluir del page view tracking (regex patterns) */
+    excludeRoutes?: string[];
+    /** Consent mode inicial (GDPR) */
+    defaultConsent?: ConsentSettings;
+    /** Clave de localStorage para persistir consent (default: 'analytics_consent') */
+    consentStorageKey?: string;
+    /** Propiedades de usuario por defecto */
+    defaultUserProperties?: Record<string, string>;
+    /** Prefijo para eventos custom (ej: 'myapp_') */
+    eventPrefix?: string;
+    /** Sampling rate (0.0 - 1.0) para reducir volumen (default: 1.0) */
+    samplingRate?: number;
+}
+/**
+ * Settings de consentimiento GDPR
+ */
+export interface ConsentSettings {
+    /** Permite recolección de analytics */
+    analytics?: boolean;
+    /** Permite personalización de ads */
+    advertising?: boolean;
+    /** Permite funcionalidad */
+    functionality?: boolean;
+    /** Permite seguridad */
+    security?: boolean;
+}
+/**
+ * Estado completo de consentimiento
+ */
+export interface ConsentState {
+    /** Settings actuales */
+    settings: ConsentSettings;
+    /** Timestamp de la última actualización */
+    updatedAt: Date | null;
+    /** Si el usuario ha tomado una decisión explícita */
+    hasDecided: boolean;
+}
+/**
+ * Nombres de eventos GA4 recomendados + customs
+ */
+export type AnalyticsEventName = 'add_payment_info' | 'add_shipping_info' | 'add_to_cart' | 'add_to_wishlist' | 'begin_checkout' | 'purchase' | 'refund' | 'remove_from_cart' | 'view_cart' | 'view_item' | 'view_item_list' | 'generate_lead' | 'login' | 'page_view' | 'screen_view' | 'search' | 'select_content' | 'select_item' | 'select_promotion' | 'share' | 'sign_up' | 'view_promotion' | 'feature_used' | 'preference_changed' | 'onboarding_step' | 'error_occurred' | 'performance_metric' | string;
+/**
+ * Parámetros tipados por evento
+ */
+export interface AnalyticsEventParams {
+    add_to_cart: {
+        item_id: string;
+        item_name?: string;
+        value?: number;
+        currency?: string;
+        quantity?: number;
+    };
+    purchase: {
+        transaction_id: string;
+        value: number;
+        currency?: string;
+        items?: AnalyticsItem[];
+        tax?: number;
+        shipping?: number;
+    };
+    begin_checkout: {
+        value?: number;
+        currency?: string;
+        items?: AnalyticsItem[];
+    };
+    view_item: {
+        item_id: string;
+        item_name?: string;
+        value?: number;
+        currency?: string;
+    };
+    remove_from_cart: {
+        item_id: string;
+        item_name?: string;
+        value?: number;
+    };
+    login: {
+        method?: string;
+    };
+    sign_up: {
+        method?: string;
+    };
+    search: {
+        search_term: string;
+    };
+    share: {
+        content_type?: string;
+        item_id?: string;
+        method?: string;
+    };
+    select_content: {
+        content_type: string;
+        item_id?: string;
+    };
+    page_view: {
+        page_path?: string;
+        page_title?: string;
+        page_location?: string;
+    };
+    screen_view: {
+        screen_name: string;
+        screen_class?: string;
+    };
+    feature_used: {
+        feature_name: string;
+        feature_category?: string;
+    };
+    preference_changed: {
+        preference_name: string;
+        old_value?: string;
+        new_value?: string;
+    };
+    onboarding_step: {
+        step_number: number;
+        step_name?: string;
+    };
+    error_occurred: {
+        error_type: string;
+        error_message?: string;
+        error_stack?: string;
+        context?: string;
+    };
+    performance_metric: {
+        metric_name: string;
+        value: number;
+        unit?: string;
+    };
+    [key: string]: Record<string, unknown> | undefined;
+}
+/**
+ * Item para eventos de ecommerce
+ */
+export interface AnalyticsItem {
+    /** ID único del item */
+    item_id: string;
+    /** Nombre del item */
+    item_name: string;
+    /** Categoría principal */
+    item_category?: string;
+    /** Subcategorías */
+    item_category2?: string;
+    item_category3?: string;
+    /** Marca */
+    item_brand?: string;
+    /** Variante (ej: color, talla) */
+    item_variant?: string;
+    /** Precio unitario */
+    price?: number;
+    /** Cantidad */
+    quantity?: number;
+    /** Moneda ISO 4217 */
+    currency?: string;
+    /** Posición en lista */
+    index?: number;
+    /** Cupón aplicado */
+    coupon?: string;
+}
+/**
+ * Tipo de evento de debug
+ */
+export type DebugEventType = 'event' | 'page_view' | 'screen_view' | 'user_property' | 'error' | 'consent' | 'timing';
+/**
+ * Evento de debug (solo en debug mode)
+ */
+export interface AnalyticsDebugEvent {
+    /** Timestamp del evento */
+    timestamp: Date;
+    /** Tipo de evento */
+    type: DebugEventType;
+    /** Nombre del evento */
+    name: string;
+    /** Parámetros del evento */
+    params?: Record<string, unknown>;
+    /** Si fue enviado a Firebase (false en debug mode) */
+    sent: boolean;
+}
+/**
+ * Métrica de timing/performance
+ */
+export interface TimingMetric {
+    /** Nombre de la métrica */
+    name: string;
+    /** Valor en milisegundos */
+    valueMs: number;
+    /** Categoría (ej: 'api', 'render', 'load') */
+    category?: string;
+    /** Parámetros adicionales */
+    params?: Record<string, string>;
+}
+/**
+ * Propiedades de usuario para segmentación
+ */
+export interface UserProperties {
+    /** Idioma preferido */
+    preferred_language?: string;
+    /** Nivel de suscripción */
+    subscription_tier?: string;
+    /** Organización activa (multi-tenant) */
+    active_organization?: string;
+    /** Propiedades custom */
+    [key: string]: string | number | boolean | undefined;
+}