valtech-components 2.0.803 → 2.0.805

package/lib/services/donation/config.d.ts

@@ -0,0 +1,33 @@
+import { EnvironmentProviders, InjectionToken } from '@angular/core';
+import { ValtechDonationConfig } from './types';
+/**
+ * Token de inyección para la configuración de Donation/Support.
+ */
+export declare const VALTECH_DONATION_CONFIG: InjectionToken<ValtechDonationConfig>;
+/** Configuración por defecto — sin métodos habilitados. */
+export declare const DEFAULT_DONATION_CONFIG: Partial<ValtechDonationConfig>;
+/**
+ * Provee el feature de aportes (Support) a la aplicación Angular.
+ *
+ * Cada app del factory declara qué métodos habilita. La vista de Support
+ * (heredada o local) renderiza solo los métodos configurados.
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * provideValtechDonations({
+ *   appId: 'showcase',
+ *   methods: ['coffee', 'bank', 'ads'],
+ *   coffee: { provider: 'buymeacoffee', url: 'https://buymeacoffee.com/valtech' },
+ *   bank: {
+ *     accounts: [{
+ *       country: 'CL', bank: 'Banco X', accountType: 'Cuenta Corriente',
+ *       number: '000000000', taxId: '11.111.111-1', holder: 'Valtech SpA',
+ *       email: 'aportes@valtech.com', currency: 'CLP',
+ *     }],
+ *   },
+ *   ads: { provider: 'admob', rewardedUnitId: 'ca-app-pub-xxx' },
+ * }),
+ * ```
+ */
+export declare function provideValtechDonations(config: ValtechDonationConfig): EnvironmentProviders;

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

@@ -0,0 +1,54 @@
+import { BankAccount, DonationActionResult, DonationMethod } from './types';
+import * as i0 from "@angular/core";
+/**
+ * `DonationService`
+ *
+ * Servicio cross-app para el feature de aportes voluntarios (Support).
+ * Patrón factory: cada app llama `provideValtechDonations(...)` y este
+ * servicio expone solo los métodos habilitados.
+ *
+ * **Fase 0 (placeholder)** — abre links externos + expone datos de config.
+ * Sin backend. Fases futuras: rewarded ads reales, webhook de café,
+ * registro de intents para una página de transparencia.
+ *
+ * @example
+ * ```typescript
+ * private donations = inject(DonationService);
+ *
+ * methods = this.donations.enabledMethods();  // ['coffee', 'bank']
+ * onCoffee() { this.donations.openCoffee(); }
+ * accounts = this.donations.bankAccounts();
+ * ```
+ */
+export declare class DonationService {
+    private readonly config;
+    /** Último intent registrado — útil para tests / debugging / UI feedback. */
+    private readonly _lastIntent;
+    readonly lastIntent: import("@angular/core").Signal<DonationMethod>;
+    /** Métodos habilitados por la app, en orden de config. */
+    readonly enabledMethods: import("@angular/core").Signal<DonationMethod[]>;
+    /** `true` si el método está habilitado en la config de la app. */
+    isEnabled(method: DonationMethod): boolean;
+    /** Cuentas bancarias configuradas (vacío si `bank` no está habilitado). */
+    bankAccounts(): BankAccount[];
+    /** Cuentas filtradas por país ISO — para apps multi-mercado. */
+    bankAccountsByCountry(country: string): BankAccount[];
+    /**
+     * Abre el checkout de "café" (Buy Me a Coffee / Ko-fi) en una pestaña nueva.
+     * El proveedor es el merchant of record — Valtech no procesa el pago.
+     */
+    openCoffee(): DonationActionResult;
+    /**
+     * Muestra un anuncio rewarded (opt-in). **Fase 0: no implementado** —
+     * placeholder hasta integrar el plugin de ads (AdMob/AdSense) + la
+     * categoría de consentimiento. Retorna `not-supported`.
+     */
+    showRewardedAd(): Promise<DonationActionResult>;
+    /**
+     * Registra la intención de aporte. **Fase 0: solo estado local.**
+     * Fase 4 — POST a un endpoint para una página de transparencia.
+     */
+    recordIntent(method: DonationMethod): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DonationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DonationService>;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Valtech Donation / Support Service
+ *
+ * Feature cross-app de aportes voluntarios. Patrón factory: cada app llama
+ * `provideValtechDonations(...)` y habilita los métodos que quiera
+ * (`ads` · `coffee` · `bank`).
+ *
+ * Importante (legal): el dinero recibido por una entidad con fines de lucro
+ * es ingreso afecto a impuesto, NO una donación deducible. La UI debe usar
+ * lenguaje de "aporte voluntario / apoyo", nunca "donación".
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * provideValtechDonations({
+ *   appId: 'showcase',
+ *   methods: ['coffee', 'bank'],
+ *   coffee: { provider: 'buymeacoffee', url: 'https://buymeacoffee.com/valtech' },
+ *   bank: { accounts: [ ... ] },
+ * }),
+ * ```
+ */
+export { VALTECH_DONATION_CONFIG, provideValtechDonations, DEFAULT_DONATION_CONFIG, } from './config';
+export { DonationService } from './donation.service';
+export { DonationMethod, CoffeeProvider, AdsProvider, BankAccount, CoffeeConfig, AdsConfig, ValtechDonationConfig, DonationActionResult, } from './types';

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

@@ -0,0 +1,85 @@
+/**
+ * Valtech Donation / Support — tipos.
+ *
+ * Nota legal importante: el dinero recibido por una entidad con fines de lucro
+ * NO es una "donación" deducible de impuestos — es ingreso afecto. Por eso la
+ * UI debe usar lenguaje de "aporte voluntario / apoyo", nunca "donación" en su
+ * sentido jurídico. Ver `docs/` (pendiente) y la vista Support del consumer.
+ */
+/**
+ * Métodos de aporte soportados.
+ * - `ads`    — el usuario ve publicidad rewarded (opt-in) para apoyar.
+ * - `coffee` — pago único vía proveedor externo (Buy Me a Coffee / Ko-fi).
+ * - `bank`   — transferencia bancaria directa (se muestran los datos).
+ */
+export type DonationMethod = 'ads' | 'coffee' | 'bank';
+/** Proveedor del método "café". El merchant of record es el proveedor. */
+export type CoffeeProvider = 'buymeacoffee' | 'kofi' | 'custom';
+/** Proveedor de publicidad rewarded. */
+export type AdsProvider = 'admob' | 'adsense' | 'custom';
+/**
+ * Datos de una cuenta bancaria para transferencia. Pensado para ser
+ * por-país (el modelo factory es 1 producto = 1 dominio, con datos
+ * fiscales/bancarios distintos por mercado).
+ */
+export interface BankAccount {
+    /** ISO country code — ej. 'CL', 'AR', 'MX'. */
+    country: string;
+    /** Nombre del banco. */
+    bank: string;
+    /** Tipo de cuenta — ej. 'Cuenta Corriente', 'Vista', 'Checking'. */
+    accountType: string;
+    /** Número de cuenta / IBAN / CBU. */
+    number: string;
+    /** Identificador fiscal del titular — RUT, CUIT, RFC, etc. */
+    taxId: string;
+    /** Nombre del titular de la cuenta. */
+    holder: string;
+    /** Email para enviar comprobante de transferencia. */
+    email?: string;
+    /** Moneda — ej. 'CLP', 'USD'. */
+    currency?: string;
+}
+/** Config del método "café". */
+export interface CoffeeConfig {
+    provider: CoffeeProvider;
+    /** URL pública del perfil (BMC/Ko-fi) o checkout custom. */
+    url: string;
+}
+/** Config del método "ads" (rewarded, opt-in). */
+export interface AdsConfig {
+    provider: AdsProvider;
+    /** ID de la unidad de anuncio rewarded. */
+    rewardedUnitId?: string;
+}
+/**
+ * Configuración del feature Donation/Support.
+ *
+ * Cada app del factory declara qué métodos habilita. Una vista heredada
+ * (`val-*` page) renderiza solo los métodos en `methods`.
+ */
+export interface ValtechDonationConfig {
+    /** AppID — para tracking de intents (ej. analytics). */
+    appId?: string;
+    /** Métodos habilitados, en orden de aparición en la UI. */
+    methods: DonationMethod[];
+    /** Config del método café — requerido si `methods` incluye `'coffee'`. */
+    coffee?: CoffeeConfig;
+    /** Cuentas bancarias — requerido si `methods` incluye `'bank'`. */
+    bank?: {
+        accounts: BankAccount[];
+    };
+    /** Config de ads — requerido si `methods` incluye `'ads'`. */
+    ads?: AdsConfig;
+}
+/**
+ * Resultado de un intento de aporte. Devuelto por los métodos del servicio
+ * de forma descriptiva (no se lanzan excepciones para flujos esperables).
+ */
+export interface DonationActionResult {
+    method: DonationMethod;
+    /** `true` si la acción se inició correctamente. */
+    ok: boolean;
+    /** Motivo cuando `ok` es `false` — ej. 'not-configured', 'not-supported'. */
+    reason?: string;
+}

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

@@ -1,3 +1,11 @@
+/**
+ * Firebase Service
+ *
+ * Servicio principal para la autenticación con Firebase usando Custom Tokens.
+ * Permite que usuarios autenticados con tu backend (Cognito, etc.) accedan
+ * a servicios de Firebase (Firestore, Storage, FCM) de manera segura.
+ */
+import { Signal } from '@angular/core';
 import { Auth, UserCredential } from '@angular/fire/auth';
 import { Observable } from 'rxjs';
 import { FirebaseUser, MembershipInfo, OrganizationInfo, SessionState, ValtechFirebaseConfig } from './types';
@@ -46,7 +54,51 @@ export declare class FirebaseService {
     readonly user$: Observable<FirebaseUser | null>;
     /** Indica si el usuario está autenticado en Firebase */
     readonly isAuthenticated$: Observable<boolean>;
+    /**
+     * Signal interna que respalda `firebaseAuthReady`.
+     * `true` cuando hay un `firebase.User` activo y por tanto las reglas de
+     * Firestore evaluarán `request.auth != null` correctamente.
+     */
+    private readonly _firebaseAuthReady;
+    /**
+     * Indica si la sesión de **Firebase Auth** está establecida y lista para
+     * leer Firestore.
+     *
+     * IMPORTANTE: esto es distinto del JWT del backend. La sesión de Firebase
+     * Auth es una sesión separada que se establece vía `signInWithCustomToken`
+     * (ver `AuthService.signInWithFirebase`). En cold start de PWA, el JWT del
+     * backend puede estar listo varios cientos de ms antes de que Firebase Auth
+     * confirme su `User` — adjuntar un listener de Firestore en esa ventana
+     * produce `permission-denied`.
+     *
+     * Usar este signal (o `whenFirebaseAuthReady()`) como gate antes de
+     * suscribirse a cualquier query/listener de Firestore.
+     *
+     * @example
+     * ```typescript
+     * if (this.firebase.firebaseAuthReady()) {
+     *   // seguro leer Firestore
+     * }
+     * ```
+     */
+    readonly firebaseAuthReady: Signal<boolean>;
+    /**
+     * Emite `true` una sola vez en cuanto la sesión de Firebase Auth está lista,
+     * y completa. Si ya está lista, emite inmediatamente.
+     *
+     * Pensado como gate compartido para abrir streams Firestore — espera la
+     * ventana de hidratación de Firebase Auth sin necesidad de retries.
+     */
+    readonly firebaseAuthReady$: Observable<boolean>;
     constructor(auth: Auth, config: ValtechFirebaseConfig);
+    /**
+     * Resuelve en cuanto la sesión de Firebase Auth está lista para leer
+     * Firestore. Si ya está lista, resuelve inmediatamente.
+     *
+     * Útil para gatear la primera suscripción a un listener de Firestore y así
+     * cerrar la ventana de `permission-denied` en cold start.
+     */
+    whenFirebaseAuthReady(): Promise<boolean>;
     /**
      * Autentica al usuario con un Custom Token generado por el backend.
      *

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

@@ -64,7 +64,16 @@ export declare class NotificationsService {
     private currentUserId;
     private collectionReady$;
     private authService;
+    private firebaseService;
     constructor(injector: Injector, collectionFactory: FirestoreCollectionFactory);
+    /**
+     * Gate de Firebase Auth: emite la colección lista SOLO cuando la sesión de
+     * Firebase Auth está confirmada. Sin FirebaseService disponible, no gatea
+     * (degrada al comportamiento previo). Espera a que `firebaseAuthReady$`
+     * emita antes de propagar la colección — así el listener Firestore nunca se
+     * adjunta antes de que `request.auth` esté disponible.
+     */
+    private collectionWhenAuthReady$;
     /**
      * Configura auto-inicialización observando el estado de AuthService.
      * Se ejecuta en el contexto del injector para poder usar effect().
@@ -90,6 +99,11 @@ export declare class NotificationsService {
      * Obtiene notificaciones ordenadas por fecha descendente (real-time).
      * Se actualiza automáticamente cuando cambian los datos.
      *
+     * El listener Firestore NO se adjunta hasta que la sesión de Firebase Auth
+     * esté confirmada (`FirebaseService.firebaseAuthReady`). Esto cierra la
+     * ventana de `permission-denied` en cold start de PWA, donde el JWT del
+     * backend puede estar listo antes que la sesión de Firebase Auth.
+     *
      * @param limit - Máximo de notificaciones a cargar (default: 50)
      */
     getAll(limit?: number): Observable<NotificationDocument[]>;
@@ -109,6 +123,9 @@ export declare class NotificationsService {
     /**
      * Cuenta notificaciones no leídas usando server-side aggregation query.
      * No descarga documentos — eficiente para badges en UI.
+     *
+     * Gateado por `firebaseAuthReady` — la aggregation query no se ejecuta hasta
+     * que la sesión de Firebase Auth esté lista.
      */
     getUnreadCount(): Observable<number>;
     /**

package/lib/services/refreshable-stream/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Refreshable Stream
+ *
+ * Helper `createRefreshableStream` para vistas con datos Firestore.
+ * Soporta modo one-shot y real-time, con gate de `firebaseAuthReady`.
+ */
+export { createRefreshableStream, type RefreshableStream, type RefreshableStreamOptions, } from './refreshable-stream';

package/lib/services/refreshable-stream/refreshable-stream.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Refreshable Stream
+ *
+ * Helper estándar para vistas que consumen datos de Firestore. Soporta DOS
+ * modos — el caller decide cuál vía la `factory`:
+ *
+ *  - **one-shot** (recomendado por defecto): `() => from(svc.getAllOnce())`.
+ *    Carga una vez y completa. Más barato — sin listener vivo.
+ *  - **real-time**: `() => svc.getAll()`. Listener Firestore que auto-actualiza.
+ *    Solo donde importa (inbox de notificaciones, badges).
+ *
+ * En ambos modos la primera suscripción se gatea por `firebaseAuthReady`
+ * (sesión de Firebase Auth lista) — así el listener/lectura nunca se adjunta
+ * antes de que `request.auth` esté disponible en las reglas de Firestore, lo
+ * que cierra la ventana de `permission-denied` en cold start de PWA.
+ *
+ * El `retry` con backoff corto es solo red de seguridad para reconexiones
+ * transitorias (no para cubrir cold start — eso lo cubre el gate de auth).
+ */
+import { Injector, Signal } from '@angular/core';
+import { Observable } from 'rxjs';
+/** Opciones de configuración para `createRefreshableStream`. */
+export interface RefreshableStreamOptions<T> {
+    /**
+     * Valor emitido cuando la factory falla tras agotar los reintentos.
+     * Default: `null`.
+     */
+    fallback?: T;
+    /**
+     * Número máximo de reintentos ante un error de la factory.
+     * Backoff corto — NO cubre cold start (eso lo hace el gate de auth), solo
+     * reconexiones transitorias. Default: 4.
+     */
+    retryCount?: number;
+    /**
+     * Delay base del backoff (ms). El delay efectivo crece exponencialmente
+     * acotado: 500ms → 1s → 2s ... Default: 500.
+     */
+    retryBaseDelayMs?: number;
+    /**
+     * Si `false`, NO espera a `firebaseAuthReady` antes de la primera
+     * suscripción. Útil para streams que no leen Firestore. Default: `true`.
+     */
+    gateOnFirebaseAuth?: boolean;
+    /**
+     * Injector explícito. Solo necesario si `createRefreshableStream` se llama
+     * fuera de un injection context (raro). Por defecto usa `inject(Injector)`.
+     */
+    injector?: Injector;
+}
+/**
+ * Resultado de `createRefreshableStream`.
+ */
+export interface RefreshableStream<T> {
+    /** Datos actuales. `null` mientras la primera emisión no ha llegado. */
+    readonly data: Signal<T | null>;
+    /** `true` mientras se espera la primera emisión de la suscripción actual. */
+    readonly loading: Signal<boolean>;
+    /** `true` si la factory falló tras agotar los reintentos. */
+    readonly error: Signal<boolean>;
+    /**
+     * Re-suscribe la factory desde cero (nuevo listener / nueva lectura).
+     * Es lo que registra el `PageRefreshService` como handler de pull-to-refresh,
+     * y también el "reconectar manual" si un listener murió.
+     */
+    reload: () => void;
+}
+/**
+ * Crea un stream refrescable a partir de una factory de Observable.
+ *
+ * DEBE llamarse en un injection context (field initializer o constructor) —
+ * usa `toSignal`/`toObservable`/`inject` internamente.
+ *
+ * @param factory - Función que produce el Observable a consumir. El caller
+ *   decide el modo: `() => from(svc.getAllOnce())` (one-shot) o
+ *   `() => svc.getAll()` (real-time).
+ * @param options - Configuración opcional (fallback, retry, gate).
+ *
+ * @example
+ * ```typescript
+ * // one-shot (recomendado por defecto)
+ * private readonly stream = createRefreshableStream(
+ *   () => from(this.svc.getAllOnce()),
+ * );
+ *
+ * // real-time (inbox)
+ * private readonly stream = createRefreshableStream(
+ *   () => this.notifs.getAll(50),
+ * );
+ *
+ * readonly items = this.stream.data;
+ * readonly loading = this.stream.loading;
+ *
+ * ionViewWillEnter() {
+ *   this.pageRefresh.register(() => this.stream.reload());
+ * }
+ * ```
+ */
+export declare function createRefreshableStream<T>(factory: () => Observable<T>, options?: RefreshableStreamOptions<T>): RefreshableStream<T>;

package/lib/version.d.ts

@@ -2,4 +2,4 @@
  * Current version of valtech-components.
  * This is automatically updated during the publish process.
  */
-export declare const VERSION = "2.0.803";
+export declare const VERSION = "2.0.805";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valtech-components",
-  "version": "2.0.803",
+  "version": "2.0.805",
   "private": false,
   "bin": {
     "valtech-firebase-config": "./src/lib/services/firebase/scripts/generate-sw-config.js"

package/public-api.d.ts

@@ -263,6 +263,7 @@ export * from './lib/services/auth';
 export * from './lib/services/i18n';
 export * from './lib/services/preferences';
 export * from './lib/services/page-refresh/page-refresh.service';
+export * from './lib/services/refreshable-stream';
 export * from './lib/services/app-config';
 export * from './lib/services/presets';
 export * from './lib/services/skeleton';
@@ -272,6 +273,7 @@ export * from './lib/services/ads';
 export * from './lib/components/molecules/ad-slot/ad-slot.component';
 export * from './lib/services/content';
 export * from './lib/services/feedback';
+export * from './lib/services/donation';
 export * from './lib/components/molecules/feedback-form/feedback-form.component';
 export * from './lib/components/molecules/feedback-form/types';
 export * from './lib/components/molecules/content-reaction/content-reaction.component';