valtech-components 2.0.804 → 2.0.806

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,106 @@
+/**
+ * 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;
+    /**
+     * Timeout (ms) del gate de Firebase Auth. Si la sesión de Firebase Auth no
+     * se establece en este tiempo, el stream procede igual (la factory correrá
+     * y, si no hay permiso, terminará en estado `error` — NUNCA en skeleton
+     * infinito). Muy por encima de cualquier handshake real. Default: 20000.
+     */
+    authGateTimeoutMs?: number;
+    /**
+     * 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.804";
+export declare const VERSION = "2.0.806";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valtech-components",
-  "version": "2.0.804",
+  "version": "2.0.806",
   "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';