valtech-components 2.0.687 → 2.0.689

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

@@ -0,0 +1,187 @@
+/**
+ * Ads Types
+ *
+ * Tipos e interfaces para el servicio de Google AdSense.
+ * Simplificado para usar AdSense en lugar de GPT (Ad Manager).
+ */
+
+// ============================================================================
+// CONFIGURACION
+// ============================================================================
+
+/**
+ * Configuracion del servicio de Ads.
+ * Pasada a provideValtechAds() en el bootstrap de la aplicacion.
+ */
+export interface ValtechAdsConfig {
+  /** Publisher ID de AdSense (formato: ca-pub-XXXXXXXXXXXXXXXX) */
+  adClient: string;
+
+  /** Habilitar modo debug (muestra info de ads en consola) */
+  debugMode?: boolean;
+
+  /** Test mode - usa ads de prueba durante desarrollo */
+  testMode?: boolean;
+
+  /** Habilitar Auto Ads (Google decide ubicacion automaticamente) */
+  autoAds?: boolean;
+
+  /** Callback cuando se carga un ad */
+  onAdLoaded?: (slotId: string, isEmpty: boolean) => void;
+
+  /** Callback cuando falla un ad */
+  onAdError?: (slotId: string, error: Error) => void;
+
+  /** Rutas donde NO mostrar ads (regex patterns) */
+  excludeRoutes?: string[];
+}
+
+// ============================================================================
+// AD SLOTS
+// ============================================================================
+
+/**
+ * Formato de ad para AdSense.
+ */
+export type AdFormat = 'auto' | 'fluid' | 'rectangle' | 'horizontal' | 'vertical';
+
+/**
+ * Configuracion de un ad slot individual.
+ */
+export interface AdSlotConfig {
+  /** ID unico del slot (usado para el div container) */
+  slotId: string;
+
+  /** Ad Slot ID de AdSense (numero de unidad de anuncio) */
+  adSlot?: string;
+
+  /** Formato del ad */
+  format?: AdFormat;
+
+  /** Responsive - ocupa todo el ancho disponible */
+  fullWidth?: boolean;
+
+  /** CSS class adicional */
+  cssClass?: string;
+
+  /** Altura minima mientras carga */
+  minHeight?: string;
+
+  /** Mostrar skeleton mientras carga */
+  showSkeleton?: boolean;
+}
+
+// ============================================================================
+// ESTADO
+// ============================================================================
+
+/**
+ * Estado de un ad slot.
+ */
+export type AdSlotState =
+  | 'idle' // No cargado
+  | 'loading' // Script/ad cargando
+  | 'rendered' // Ad visible
+  | 'empty' // Sin ad disponible
+  | 'hidden' // Usuario premium o sin consent
+  | 'error'; // Error de carga
+
+/**
+ * Evento emitido por el servicio de ads.
+ */
+export interface AdEvent {
+  type: 'loaded' | 'empty' | 'error' | 'viewable' | 'clicked';
+  slotId: string;
+  timestamp: Date;
+  isEmpty?: boolean;
+  error?: Error;
+}
+
+// ============================================================================
+// CONSENT
+// ============================================================================
+
+/**
+ * Estado de consent para ads (mapeado desde AnalyticsService).
+ */
+export interface AdsConsentState {
+  /** Permite almacenamiento de ads */
+  adStorage: boolean;
+
+  /** Permite personalizacion de ads */
+  adPersonalization: boolean;
+
+  /** Permite datos de usuario para ads */
+  adUserData: boolean;
+}
+
+// ============================================================================
+// ADSENSE (Google AdSense) Types
+// ============================================================================
+
+/** AdSense global array */
+export type AdSenseCommand = Record<string, unknown>;
+
+// Extend Window interface for adsbygoogle and googletag (GPT)
+declare global {
+  interface Window {
+    adsbygoogle?: AdSenseCommand[];
+    googletag?: GoogleTag;
+  }
+}
+
+/** Google Publisher Tags (GPT) interface */
+export interface GoogleTag {
+  cmd: Array<() => void>;
+  pubads(): GoogleTagPubAds;
+}
+
+/** GPT PubAds service */
+export interface GoogleTagPubAds {
+  setRequestNonPersonalizedAds(value: 0 | 1): void;
+}
+
+// ============================================================================
+// LEGACY TYPES (mantenidos para compatibilidad)
+// ============================================================================
+
+/**
+ * @deprecated Use AdFormat instead
+ */
+export type AdSlotSize =
+  | 'leaderboard'
+  | 'billboard'
+  | 'medium-rectangle'
+  | 'large-rectangle'
+  | 'half-page'
+  | 'skyscraper'
+  | 'mobile-banner'
+  | 'mobile-leaderboard'
+  | 'fluid'
+  | 'native'
+  | 'custom';
+
+/**
+ * @deprecated AdSense handles sizes automatically
+ */
+export const AD_SIZE_MAP: Record<AdSlotSize, [number, number] | 'fluid'> = {
+  leaderboard: [728, 90],
+  billboard: [970, 250],
+  'medium-rectangle': [300, 250],
+  'large-rectangle': [336, 280],
+  'half-page': [300, 600],
+  skyscraper: [160, 600],
+  'mobile-banner': [320, 50],
+  'mobile-leaderboard': [320, 100],
+  fluid: 'fluid',
+  native: 'fluid',
+  custom: 'fluid',
+};
+
+/**
+ * @deprecated Not used with AdSense
+ */
+export interface SizeMapping {
+  viewportWidth: number;
+  sizes: ([number, number] | 'fluid')[];
+}

package/src/lib/services/app-config/app-config.service.ts

@@ -0,0 +1,228 @@
+/**
+ * AppConfigService
+ *
+ * Servicio para gestionar configuración remota de la aplicación desde Firestore.
+ * Soporta feature flags, variables dinámicas, y detección de actualizaciones.
+ */
+
+import { computed, inject, Injectable, signal } from '@angular/core';
+import { Subscription } from 'rxjs';
+
+import { FirestoreService } from '../firebase/firestore.service';
+import { VALTECH_APP_CONFIG } from './config';
+import { AppConfig, AppConfigServiceConfig } from './types';
+
+/**
+ * Servicio de configuración remota de la aplicación.
+ *
+ * Lee la configuración desde Firestore (apps/{appId}/config/app) y provee:
+ * - Feature flags reactivos
+ * - Variables dinámicas de configuración
+ * - Detección de nuevas versiones
+ * - Modo mantenimiento
+ *
+ * @example
+ * ```typescript
+ * @Component({...})
+ * export class MyComponent {
+ *   private appConfig = inject(AppConfigService);
+ *
+ *   // Verificar feature flag
+ *   showNewFeature = computed(() =>
+ *     this.appConfig.isFeatureEnabled('newDashboard')
+ *   );
+ *
+ *   // Obtener variable
+ *   maxSize = this.appConfig.getVariable('maxUploadSize', 5242880);
+ * }
+ * ```
+ */
+@Injectable({ providedIn: 'root' })
+export class AppConfigService {
+  private firestore = inject(FirestoreService);
+  private serviceConfig = inject(VALTECH_APP_CONFIG, { optional: true });
+
+  private subscription: Subscription | null = null;
+
+  // =========================================================================
+  // SIGNALS REACTIVOS
+  // =========================================================================
+
+  /**
+   * Configuración actual de la aplicación.
+   * null si no se ha cargado o no está configurado.
+   */
+  readonly appConfig = signal<AppConfig | null>(null);
+
+  /**
+   * Indica si la configuración está cargando.
+   */
+  readonly loading = signal(true);
+
+  /**
+   * Error de carga, si existe.
+   */
+  readonly error = signal<string | null>(null);
+
+  /**
+   * Indica si hay una nueva versión disponible.
+   */
+  readonly hasUpdate = computed(() => {
+    const config = this.appConfig();
+    const currentVersion = this.serviceConfig?.currentVersion;
+
+    if (!config || !currentVersion) return false;
+
+    return this.isNewerVersion(config.version, currentVersion);
+  });
+
+  /**
+   * Indica si la aplicación está en modo mantenimiento.
+   */
+  readonly isMaintenanceMode = computed(
+    () => this.appConfig()?.maintenance ?? false
+  );
+
+  /**
+   * Versión remota de la aplicación.
+   */
+  readonly remoteVersion = computed(() => this.appConfig()?.version ?? null);
+
+  /**
+   * Versión actual de la aplicación (local).
+   */
+  readonly currentVersion = computed(
+    () => this.serviceConfig?.currentVersion ?? '0.0.0'
+  );
+
+  // =========================================================================
+  // MÉTODOS PÚBLICOS
+  // =========================================================================
+
+  /**
+   * Inicializa el servicio y comienza a escuchar cambios en la configuración.
+   * Se llama automáticamente via APP_INITIALIZER si se usa provideValtechAppConfig().
+   */
+  initialize(): Promise<void> {
+    if (!this.serviceConfig) {
+      console.warn(
+        '[AppConfigService] No configuration provided. Use provideValtechAppConfig() in main.ts'
+      );
+      this.loading.set(false);
+      return Promise.resolve();
+    }
+
+    return new Promise((resolve) => {
+      this.subscription = this.firestore
+        .docChanges<AppConfig>('config', 'app')
+        .subscribe({
+          next: (config) => {
+            this.appConfig.set(config);
+            this.loading.set(false);
+            this.error.set(null);
+            resolve();
+          },
+          error: (err) => {
+            console.error('[AppConfigService] Error loading config:', err);
+            this.error.set(err.message || 'Error al cargar configuración');
+            this.loading.set(false);
+            resolve(); // Resolve anyway to not block app startup
+          },
+        });
+    });
+  }
+
+  /**
+   * Verifica si un feature flag está habilitado.
+   *
+   * @param feature - Nombre del feature flag
+   * @param defaultValue - Valor por defecto si no existe (default: false)
+   * @returns true si el feature está habilitado
+   *
+   * @example
+   * ```typescript
+   * if (appConfig.isFeatureEnabled('darkMode')) {
+   *   // Mostrar toggle de dark mode
+   * }
+   * ```
+   */
+  isFeatureEnabled(feature: string, defaultValue = false): boolean {
+    const config = this.appConfig();
+    if (!config?.features) return defaultValue;
+    return config.features[feature] ?? defaultValue;
+  }
+
+  /**
+   * Obtiene una variable de configuración.
+   *
+   * @param key - Clave de la variable
+   * @param defaultValue - Valor por defecto si no existe
+   * @returns Valor de la variable o el valor por defecto
+   *
+   * @example
+   * ```typescript
+   * const maxSize = appConfig.getVariable('maxUploadSize', 5242880);
+   * const supportEmail = appConfig.getVariable('supportEmail', 'support@example.com');
+   * ```
+   */
+  getVariable<T>(key: string, defaultValue: T): T {
+    const config = this.appConfig();
+    if (!config?.variables) return defaultValue;
+    return (config.variables[key] as T) ?? defaultValue;
+  }
+
+  /**
+   * Recarga la configuración manualmente (one-time read).
+   * Útil si necesitas forzar una actualización.
+   */
+  async refresh(): Promise<void> {
+    this.loading.set(true);
+
+    try {
+      const config = await this.firestore.getDoc<AppConfig>('config', 'app');
+      this.appConfig.set(config);
+      this.error.set(null);
+    } catch (err) {
+      const error = err as Error;
+      console.error('[AppConfigService] Error refreshing config:', error);
+      this.error.set(error.message || 'Error al refrescar configuración');
+    } finally {
+      this.loading.set(false);
+    }
+  }
+
+  /**
+   * Desuscribe del listener de Firestore.
+   * Se llama automáticamente cuando el servicio se destruye.
+   */
+  destroy(): void {
+    this.subscription?.unsubscribe();
+    this.subscription = null;
+  }
+
+  // =========================================================================
+  // MÉTODOS PRIVADOS
+  // =========================================================================
+
+  /**
+   * Compara dos versiones semver y retorna true si remote > current.
+   *
+   * @param remote - Versión remota (ej: "1.2.3")
+   * @param current - Versión actual (ej: "1.2.0")
+   * @returns true si remote es mayor que current
+   */
+  private isNewerVersion(remote: string, current: string): boolean {
+    const remoteParts = remote.split('.').map(Number);
+    const currentParts = current.split('.').map(Number);
+
+    for (let i = 0; i < Math.max(remoteParts.length, currentParts.length); i++) {
+      const remotePart = remoteParts[i] || 0;
+      const currentPart = currentParts[i] || 0;
+
+      if (remotePart > currentPart) return true;
+      if (remotePart < currentPart) return false;
+    }
+
+    return false;
+  }
+}

package/src/lib/services/app-config/config.ts

@@ -0,0 +1,62 @@
+import {
+  APP_INITIALIZER,
+  EnvironmentProviders,
+  InjectionToken,
+  makeEnvironmentProviders,
+} from '@angular/core';
+import {
+  AppConfigServiceConfig,
+  DEFAULT_APP_CONFIG_SERVICE_CONFIG,
+} from './types';
+import { AppConfigService } from './app-config.service';
+
+/**
+ * Token de inyección para la configuración de AppConfig.
+ */
+export const VALTECH_APP_CONFIG = new InjectionToken<AppConfigServiceConfig>(
+  'ValtechAppConfig'
+);
+
+/**
+ * Provee el servicio de configuración remota a la aplicación Angular.
+ *
+ * @param config - Configuración del servicio
+ * @returns EnvironmentProviders para usar en bootstrapApplication
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * import { bootstrapApplication } from '@angular/platform-browser';
+ * import { provideValtechAppConfig } from 'valtech-components';
+ * import { version } from '../package.json';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideValtechFirebase(environment.valtechFirebase),
+ *     provideValtechAppConfig({
+ *       currentVersion: version,
+ *       showUpdateBanner: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export function provideValtechAppConfig(
+  config: AppConfigServiceConfig
+): EnvironmentProviders {
+  const mergedConfig: AppConfigServiceConfig = {
+    ...DEFAULT_APP_CONFIG_SERVICE_CONFIG,
+    ...config,
+  };
+
+  return makeEnvironmentProviders([
+    { provide: VALTECH_APP_CONFIG, useValue: mergedConfig },
+    {
+      provide: APP_INITIALIZER,
+      useFactory: (appConfigService: AppConfigService) => () =>
+        appConfigService.initialize(),
+      deps: [AppConfigService],
+      multi: true,
+    },
+  ]);
+}

package/src/lib/services/app-config/index.ts

@@ -0,0 +1,48 @@
+/**
+ * AppConfig Service Module
+ *
+ * Servicio de configuración remota para aplicaciones Angular.
+ * Lee configuración desde Firestore y provee feature flags, variables dinámicas,
+ * y detección de actualizaciones.
+ *
+ * Soporta detección de versión cross-platform (web y mobile con Capacitor).
+ *
+ * @example
+ * ```typescript
+ * // main.ts - Con soporte cross-platform
+ * import { provideValtechAppConfig, getAppVersion } from 'valtech-components';
+ * import { version } from '../package.json';
+ *
+ * async function bootstrap() {
+ *   const appVersion = await getAppVersion(version);
+ *
+ *   bootstrapApplication(AppComponent, {
+ *     providers: [
+ *       provideValtechFirebase(environment.valtechFirebase),
+ *       provideValtechAppConfig({
+ *         currentVersion: appVersion,
+ *         showUpdateBanner: true,
+ *       }),
+ *     ],
+ *   });
+ * }
+ * bootstrap();
+ *
+ * // component.ts
+ * import { AppConfigService } from 'valtech-components';
+ *
+ * @Component({...})
+ * export class MyComponent {
+ *   private appConfig = inject(AppConfigService);
+ *
+ *   showFeature = computed(() =>
+ *     this.appConfig.isFeatureEnabled('newDashboard')
+ *   );
+ * }
+ * ```
+ */
+
+export * from './types';
+export { VALTECH_APP_CONFIG, provideValtechAppConfig } from './config';
+export { AppConfigService } from './app-config.service';
+export { getAppVersion, getAppInfo, type AppVersionInfo } from './version';

package/src/lib/services/app-config/types.ts

@@ -0,0 +1,62 @@
+/**
+ * AppConfig Types
+ *
+ * Tipos para el servicio de configuración remota de la aplicación.
+ */
+
+import { FirestoreDocument } from '../firebase/types';
+
+/**
+ * Configuración de la aplicación almacenada en Firestore.
+ *
+ * @property version - Versión más reciente de la app
+ * @property minVersion - Versión mínima soportada (opcional)
+ * @property maintenance - Modo mantenimiento global
+ * @property features - Feature flags (key-value boolean)
+ * @property variables - Variables dinámicas de configuración
+ * @property announcements - Anuncios opcionales para mostrar
+ */
+export interface AppConfig extends FirestoreDocument {
+  version: string;
+  minVersion?: string;
+  maintenance?: boolean;
+  features: Record<string, boolean>;
+  variables: Record<string, unknown>;
+  announcements?: Announcement[];
+}
+
+/**
+ * Anuncio para mostrar en la aplicación.
+ *
+ * @property id - Identificador único del anuncio
+ * @property type - Tipo de anuncio (info, warning, promo)
+ * @property message - Mensaje en múltiples idiomas
+ * @property active - Si el anuncio está activo
+ * @property link - URL opcional para redirección
+ */
+export interface Announcement {
+  id: string;
+  type: 'info' | 'warning' | 'promo';
+  message: Record<string, string>;
+  active: boolean;
+  link?: string;
+}
+
+/**
+ * Configuración para el proveedor de AppConfigService.
+ *
+ * @property currentVersion - Versión actual de la aplicación
+ * @property showUpdateBanner - Mostrar banner de actualización automáticamente
+ */
+export interface AppConfigServiceConfig {
+  currentVersion: string;
+  showUpdateBanner?: boolean;
+}
+
+/**
+ * Configuración por defecto del servicio.
+ */
+export const DEFAULT_APP_CONFIG_SERVICE_CONFIG: AppConfigServiceConfig = {
+  currentVersion: '0.0.0',
+  showUpdateBanner: true,
+};

package/src/lib/services/app-config/version.ts

@@ -0,0 +1,104 @@
+/**
+ * Cross-Platform Version Helpers
+ *
+ * Funciones para obtener la versión de la aplicación de forma
+ * cross-platform (web y mobile con Capacitor).
+ */
+
+import { Capacitor } from '@capacitor/core';
+
+/**
+ * Info completa de la app en plataformas nativas.
+ */
+export interface AppVersionInfo {
+  /** Versión semver (ej: "1.2.3") */
+  version: string;
+  /** Número de build (ej: "123") */
+  build: string;
+  /** Nombre de la app */
+  name: string;
+  /** Bundle ID / Package name */
+  id: string;
+}
+
+/**
+ * Obtiene la versión de la aplicación de forma cross-platform.
+ *
+ * - En web: retorna la versión de package.json (pasada como parámetro)
+ * - En mobile: usa @capacitor/app para obtener la versión nativa
+ *
+ * @param webVersion - Versión de package.json para fallback en web
+ * @returns Promise<string> - La versión actual de la app
+ *
+ * @example
+ * ```typescript
+ * import { getAppVersion } from 'valtech-components';
+ * import { version } from '../package.json';
+ *
+ * const appVersion = await getAppVersion(version);
+ *
+ * // Uso en main.ts
+ * async function bootstrap() {
+ *   const appVersion = await getAppVersion(version);
+ *   bootstrapApplication(AppComponent, {
+ *     providers: [
+ *       provideValtechAppConfig({ currentVersion: appVersion }),
+ *     ],
+ *   });
+ * }
+ * bootstrap();
+ * ```
+ */
+export async function getAppVersion(webVersion: string): Promise<string> {
+  // En web, siempre usar la versión de package.json
+  if (!Capacitor.isNativePlatform()) {
+    return webVersion;
+  }
+
+  // En native (iOS/Android), obtener versión del binario
+  try {
+    const { App } = await import('@capacitor/app');
+    const info = await App.getInfo();
+    return info.version;
+  } catch (error) {
+    console.warn(
+      '[getAppVersion] Failed to get native version, using fallback:',
+      error
+    );
+    return webVersion;
+  }
+}
+
+/**
+ * Obtiene información completa de la app (solo en nativo).
+ * En web retorna null.
+ *
+ * @returns Promise<AppVersionInfo | null> - Info completa o null en web
+ *
+ * @example
+ * ```typescript
+ * const info = await getAppInfo();
+ * if (info) {
+ *   console.log(`App: ${info.name} v${info.version} (build ${info.build})`);
+ *   console.log(`Bundle ID: ${info.id}`);
+ * }
+ * ```
+ */
+export async function getAppInfo(): Promise<AppVersionInfo | null> {
+  if (!Capacitor.isNativePlatform()) {
+    return null;
+  }
+
+  try {
+    const { App } = await import('@capacitor/app');
+    const info = await App.getInfo();
+    return {
+      version: info.version,
+      build: info.build,
+      name: info.name,
+      id: info.id,
+    };
+  } catch {
+    return null;
+  }
+}