web-manager 4.1.9 → 4.1.11

package/CHANGELOG.md

@@ -14,6 +14,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+---
+## [4.1.10] - 2026-02-17
+### Changed
+- Refactored auth to use promise-based settler pattern (`_authReady`) for reliable auth state detection, eliminating race conditions with late-registered listeners.
+- Split `listen()` into two clear paths: `once` (waits for settler, fires once) and persistent (subscribes to all changes, catches up if already settled).
+- Renamed `onAuthStateChanged` to `_subscribe` (internal-only).
+- Removed unused `_readyCallbacks`.
+
 ---
 ## [4.1.1] - 2025-12-17
 ### Added

package/CLAUDE.md

@@ -150,6 +150,14 @@ document.body.addEventListener('click', (e) => {
 - **Key Methods**: `listen(options, callback)`, `isAuthenticated()`, `getUser()`, `signInWithEmailAndPassword()`, `signOut()`, `getIdToken()`
 - **Bindings**: Updates `auth.user` and `auth.account` context
 
+#### Auth Settler Pattern
+Auth uses a promise-based settler (`_authReady`) that resolves once Firebase's first `onAuthStateChanged` fires — the moment auth state is guaranteed (authenticated user OR null). This eliminates race conditions.
+
+- **`once` listeners** (`listen({ once: true }, cb)`): Wait for `_authReady`, fire once, done. No cleanup needed.
+- **Persistent listeners** (`listen({}, cb)`): Subscribe to `_authStateCallbacks`. If auth already settled when registered, catch up via `_authReady.then()`. Otherwise, `_handleAuthStateChange` handles the initial call naturally.
+- **`_hasProcessedStateChange`**: Ensures bindings/storage updates run only once per auth state change across all listeners.
+- **Manager owns the promise**: `_authReady` and `_authReadyResolve` live on the Manager instance. The `onAuthStateChanged` callback in `index.js` resolves it on first fire and sets `_firebaseAuthInitialized = true`.
+
 ### Bindings (`bindings.js`)
 - **Class**: `Bindings`
 - **Key Methods**: `update(data)`, `getContext()`, `clear()`

package/README.md

@@ -296,20 +296,24 @@ storage.session.clear();
 
 ### Authentication
 
-Firebase Authentication wrapper with automatic account data fetching:
+Firebase Authentication wrapper with a promise-based auth settler:
 
 ```javascript
 const auth = Manager.auth();
 
-// Listen for auth state changes
-const unsubscribe = auth.listen({ account: true }, (result) => {
-  console.log('User:', result.user);     // Firebase user or null
-  console.log('Account:', result.account); // Firestore account data or null
+// Listen once — waits for auth to settle, fires exactly once
+auth.listen({ once: true }, (state) => {
+  if (state.user) {
+    console.log('Logged in:', state.user.email);
+    console.log('Account:', state.account);
+  } else {
+    console.log('Not logged in');
+  }
 });
 
-// Listen once (useful for initial state)
-auth.listen({ once: true }, (result) => {
-  console.log('Initial state:', result);
+// Persistent listener — fires on initial settle + every future auth change
+const unsubscribe = auth.listen({}, (state) => {
+  console.log('Auth changed:', state.user?.email || 'signed out');
 });
 
 // Check authentication status
@@ -319,11 +323,7 @@ if (auth.isAuthenticated()) {
 }
 
 // Sign in
-try {
-  const user = await auth.signInWithEmailAndPassword('user@example.com', 'password');
-} catch (error) {
-  console.error('Sign in failed:', error.message);
-}
+await auth.signInWithEmailAndPassword('user@example.com', 'password');
 
 // Sign in with custom token (from backend)
 await auth.signInWithCustomToken('custom-jwt-token');
@@ -335,10 +335,17 @@ const freshToken = await auth.getIdToken(true); // Force refresh
 // Sign out
 await auth.signOut();
 
-// Stop listening
+// Stop persistent listener
 unsubscribe();
 ```
 
+**Auth Settler Design**:
+
+On page load, Firebase Auth takes time to restore the user session. The auth settler (`Manager._authReady`) is a promise that resolves once Firebase determines the auth state (user or null). All `listen()` callbacks wait for this settler before firing — consumers never see an intermediate/unknown state.
+
+- `{ once: true }` — Waits for the settler promise, calls the callback once, done. No cleanup needed.
+- `{}` (persistent) — Gets the initial settled state via `_handleAuthStateChange`, then fires again on every future sign-in/sign-out.
+
 **getUser() returns enhanced user object**:
 ```javascript
 {
@@ -351,38 +358,24 @@ unsubscribe();
 ```
 
 **HTML Auth Classes**:
-Add these classes to elements for automatic auth functionality:
 - `.auth-signout-btn` - Sign out button (shows confirmation dialog)
 
 **⚠️ Auth State Timing**:
 
-On fresh page loads, Firebase Auth needs time to restore the user session from IndexedDB/localStorage. Methods like `auth.isAuthenticated()`, `auth.getUser()`, and `auth.getIdToken()` may return `null`/`false` if called before auth state is determined.
+Methods like `auth.isAuthenticated()`, `auth.getUser()`, and `auth.getIdToken()` read the current state directly — they may return `null` before auth settles.
 
-**Problem:**
 ```javascript
 // ❌ May fail on page load - auth state not yet determined
-await Manager.dom().ready();
-const token = await auth.getIdToken(); // Could throw if currentUser is null
-```
+const token = await auth.getIdToken();
 
-**Solution:** Use `auth.listen({ once: true })` to wait for auth state:
-```javascript
-// ✅ Wait for auth state to be determined first
-auth.listen({ once: true }, async (result) => {
-  if (result.user) {
-    const token = await auth.getIdToken(); // Safe - user is authenticated
+// ✅ Wait for auth to settle first
+auth.listen({ once: true }, async (state) => {
+  if (state.user) {
+    const token = await auth.getIdToken(); // Safe
   }
 });
 ```
 
-**When this matters:**
-- Pages making authenticated API calls immediately on load
-- OAuth callback pages
-- Deep links requiring authentication
-
-**When NOT needed:**
-- User-triggered actions (button clicks) - auth state is always determined by then
-
 ### Data Binding System
 
 Reactive DOM updates with `data-wm-bind` attributes:

package/TODO.md

@@ -7,6 +7,9 @@ Do we need to use polyfill? the project that consumes this  is using webpack and
 - async
 
 
+Eventually update auth.js to have an intelligent schema for user object
+
+
 UTM management
 
 LOCALSTORAGE

package/dist/index.js

@@ -20,8 +20,12 @@ class Manager {
       serviceWorker: null
     };
 
-    // Track Firebase auth initialization
+    // Auth settler: resolves when Firebase auth first determines user state
     this._firebaseAuthInitialized = false;
+    this._authReadyResolve = null;
+    this._authReady = new Promise((resolve) => {
+      this._authReadyResolve = resolve;
+    });
 
     // Initialize modules
     this._storage = new Storage();
@@ -419,8 +423,11 @@ class Manager {
 
     // Setup auth state listener
     onAuthStateChanged(this._firebaseAuth, (user) => {
-      // Mark auth as initialized after first callback
-      this._firebaseAuthInitialized = true;
+      // Mark auth as initialized and resolve the settler promise on first callback
+      if (!this._firebaseAuthInitialized) {
+        this._firebaseAuthInitialized = true;
+        this._authReadyResolve();
+      }
 
       // Let auth module handle everything including DOM updates
       this._auth._handleAuthStateChange(user);

package/dist/modules/auth.js

@@ -27,6 +27,10 @@ const DEFAULT_ACCOUNT = {
   usage: { requests: { total: 0, period: 0 } },
   personal: { name: { first: null, last: null } },
   oauth2: {},
+  attribution: {
+    affiliate: { code: null, timestamp: null, url: null, page: null },
+    utm: { tags: {}, timestamp: null, url: null, page: null },
+  },
 };
 
 function resolveAccount(rawData, firebaseUser) {
@@ -62,7 +66,6 @@ class Auth {
   constructor(manager) {
     this.manager = manager;
     this._authStateCallbacks = [];
-    this._readyCallbacks = [];
     this._hasProcessedStateChange = false;
   }
 
@@ -128,89 +131,66 @@ class Auth {
 
     // If Firebase is not enabled, call callback immediately with null
     if (!this.manager.config.firebase?.app?.enabled) {
-      // Call callback with null user and empty account
       callback({
         user: null,
-        account: resolveAccount({}, {})
+        account: resolveAccount({}, {}),
       });
 
-      // Return empty unsubscribe function
       return () => {};
     }
 
-    // Function to get current state and call callback
-    const getStateAndCallback = async (user) => {
-      // Start with the user which will return null if not authenticated
+    // Build auth state and call the provided callback
+    const run = async (user) => {
       const state = { user: this.getUser() };
 
-      // Then, add account data if requested and user exists
-      // if (options.account && user && this.manager.firebaseFirestore) {
-      // Fetch account if the user is logged in AND Firestore is available
+      // Fetch account data if the user is logged in and Firestore is available
       if (user && this.manager.firebaseFirestore) {
         try {
           state.account = await this._getAccountData(user.uid);
         } catch (error) {
-          // Pass error to Sentry
           this.manager.sentry().captureException(new Error('Failed to get account data', { cause: error }));
         }
       }
 
-      // Always ensure account is at least a default resolved object
+      // Ensure account is always a resolved object
       state.account = state.account || resolveAccount({}, { uid: user?.uid });
 
-      // Process state change (update bindings and storage) only once across all callbacks
-      // Now ONLY the first listener will process the state change until the next auth state change
+      // Update bindings and storage once per auth state change
       if (!this._hasProcessedStateChange) {
-        // Run update - nest state under 'auth' key for consistent access
         this.manager.bindings().update({ auth: state });
-
-        // Save to storage
-        const storage = this.manager.storage();
-        storage.set('auth', state);
-
-        // Mark that we've processed this state change
+        this.manager.storage().set('auth', state);
         this._hasProcessedStateChange = true;
       }
 
-      // Call the provided callback with the state
       callback(state);
     };
 
-    let hasCalledback = false;
-    let unsubscribe = null;
-
-    // Set up listener for auth state changes
-    unsubscribe = this.onAuthStateChanged((user) => {
-      // Wait for settled state before first callback
-      if (!hasCalledback && !this.manager._firebaseAuthInitialized) {
-        return; // Auth state not yet determined
-      }
+    // Once listeners: wait for auth to settle, fire once, done
+    if (options.once) {
+      this.manager._authReady.then(() => {
+        run(this.manager.firebaseAuth?.currentUser || null);
+      });
 
-      // Mark that we've called back at least once
-      hasCalledback = true;
+      return () => {};
+    }
 
-      // Get current state and call the callback
-      getStateAndCallback(user);
+    // Persistent listeners: subscribe to all auth state changes (initial + future)
+    // If auth already settled, fire the first callback via the promise to catch up
+    const unsubscribe = this._subscribe(run);
 
-      // If once option is set, unsubscribe AFTER calling the callback
-      if (options.once && unsubscribe) {
-        unsubscribe();
-      }
-    });
+    if (this.manager._firebaseAuthInitialized) {
+      this.manager._authReady.then(() => {
+        run(this.manager.firebaseAuth?.currentUser || null);
+      });
+    }
 
     return unsubscribe;
   }
 
-  // Listen for auth state changes
-  onAuthStateChanged(callback) {
+  // Subscribe to ongoing auth state changes (sign-in, sign-out after initial settle)
+  _subscribe(callback) {
     this._authStateCallbacks.push(callback);
 
-    // If auth is already initialized, call the callback immediately
-    if (this.manager._firebaseAuthInitialized) {
-      callback(this.manager.firebaseAuth?.currentUser || null);
-    }
-
-    // Return unsubscribe function
     return () => {
       const index = this._authStateCallbacks.indexOf(callback);
       if (index > -1) {
@@ -219,12 +199,12 @@ class Auth {
     };
   }
 
-  // Internal method to handle auth state changes
+  // Called by Manager when Firebase auth state changes
   _handleAuthStateChange(user) {
     // Reset state processing flag for new auth state
     this._hasProcessedStateChange = false;
 
-    // Call all registered callbacks
+    // Call all persistent listener callbacks
     this._authStateCallbacks.forEach(callback => {
       try {
         callback(user);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-manager",
-  "version": "4.1.9",
+  "version": "4.1.11",
   "description": "Easily access important variables such as the query string, current domain, and current page in a single object.",
   "main": "dist/index.js",
   "module": "src/index.js",
@@ -42,7 +42,7 @@
     "@sentry/browser": "Resolved by using OVERRIDES in web-manager (lighthouse is the issue"
   },
   "dependencies": {
-    "@sentry/browser": "^10.38.0",
+    "@sentry/browser": "^10.39.0",
     "firebase": "^12.9.0",
     "itwcw-package-analytics": "^1.0.8",
     "lodash": "^4.17.23"