web-manager 4.1.24 → 4.1.26

package/CHANGELOG.md

@@ -14,6 +14,11 @@ 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.25] - 2026-03-13
+### Added
+- Automatically attach resolved subscription state (`state.resolved`) to auth state during processing, making `plan`, `active`, `trialing`, and `cancelling` available to bindings and consumers without manual calls.
+
 ---
 ## [4.1.24] - 2026-03-13
 ### Added

package/CLAUDE.md

@@ -147,9 +147,23 @@ document.body.addEventListener('click', (e) => {
 
 ### Auth (`auth.js`)
 - **Class**: `Auth`
-- **Key Methods**: `listen(options, callback)`, `isAuthenticated()`, `getUser()`, `signInWithEmailAndPassword()`, `signOut()`, `getIdToken()`
+- **Key Methods**: `listen(options, callback)`, `isAuthenticated()`, `getUser()`, `signInWithEmailAndPassword()`, `signOut()`, `getIdToken()`, `resolveSubscription(account?)`
 - **Bindings**: Updates `auth.user` and `auth.account` context
 
+#### resolveSubscription(account?)
+Derives calculated subscription fields from raw account data. Returns only fields that require derivation logic — raw data (product.id, status, trial, cancellation) lives on `account.subscription` directly.
+
+```javascript
+const resolved = auth.resolveSubscription(account);
+// Returns: { plan, active, trialing, cancelling }
+```
+- `plan`: Effective plan ID the user has access to RIGHT NOW (`'basic'` if cancelled/suspended)
+- `active`: User has active access (active, trialing, or cancelling — all mean the user can use the product)
+- `trialing`: In an active trial (status `'active'` + `trial.claimed` + unexpired `trial.expires`)
+- `cancelling`: Cancellation pending (status `'active'` + `cancellation.pending` + NOT trialing)
+
+**Unified with BEM**: The same function exists on `User.resolveSubscription(account)` in backend-manager (`helpers/user.js`) with identical logic and return shape.
+
 #### 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.
 

package/README.md

@@ -360,6 +360,50 @@ On page load, Firebase Auth takes time to restore the user session. The auth set
 **HTML Auth Classes**:
 - `.auth-signout-btn` - Sign out button (shows confirmation dialog)
 
+**Resolve Subscription State**:
+
+Derives calculated subscription fields from raw account data. Returns only fields that require logic — raw data is on `account.subscription` directly.
+
+```javascript
+const resolved = auth.resolveSubscription(account);
+// Or without an argument (falls back to stored auth state):
+const resolved = auth.resolveSubscription();
+```
+
+When called without an argument, reads the account from `localStorage` (the last auth state saved by `listen()`). Pass an explicit account when you have one to avoid stale data.
+
+Returns:
+```javascript
+{
+  plan: 'basic',       // Effective plan ID right now ('basic' if cancelled/suspended)
+  active: true,        // Has active access (active, trialing, or cancelling)
+  trialing: false,     // In an active trial (status 'active' + unexpired trial)
+  cancelling: false,   // Cancellation pending (status 'active' + cancellation.pending)
+}
+```
+
+Usage:
+```javascript
+auth.listen({ once: true }, (state) => {
+  const resolved = auth.resolveSubscription(state.account);
+
+  if (!resolved.active) {
+    // User is on free plan or subscription ended
+  }
+
+  if (resolved.trialing) {
+    // Show trial banner
+  }
+
+  if (resolved.cancelling) {
+    // Show "your plan will cancel at end of period" notice
+  }
+
+  // Use resolved.plan for effective plan ID
+  const product = products.find(p => p.id === resolved.plan);
+});
+```
+
 **⚠️ Auth State Timing**:
 
 Methods like `auth.isAuthenticated()`, `auth.getUser()`, and `auth.getIdToken()` read the current state directly — they may return `null` before auth settles.

package/dist/modules/auth.js

@@ -159,6 +159,9 @@ class Auth {
       // Ensure account is always a resolved object
       state.account = state.account || resolveAccount({}, { uid: user?.uid });
 
+      // Derive resolved subscription state for bindings and consumers
+      state.resolved = this.resolveSubscription(state.account);
+
       // Update bindings and storage once per auth state change
       if (!this._hasProcessedStateChange) {
         this.manager.bindings().update({ auth: state });

package/dist/modules/firestore.js

@@ -26,7 +26,7 @@ class Firestore {
       }
 
       // Dynamically import Firestore
-      const { getFirestore, doc: firestoreDoc, collection: firestoreCollection, getDoc, setDoc, updateDoc, deleteDoc, getDocs, query, where, orderBy, limit, startAt, endAt } = await import('firebase/firestore');
+      const { getFirestore, doc: firestoreDoc, collection: firestoreCollection, getDoc, setDoc, updateDoc, deleteDoc, getDocs, query, where, orderBy, limit, startAt, endAt, onSnapshot } = await import('firebase/firestore');
 
       // Store references for later use
       this._firestoreMethods = {
@@ -43,7 +43,8 @@ class Firestore {
         orderBy,
         limit,
         startAt,
-        endAt
+        endAt,
+        onSnapshot,
       };
 
       // Initialize Firestore
@@ -112,6 +113,25 @@ class Firestore {
         await self._ensureInitialized();
         const docRef = self._firestoreMethods.doc(self._db, docPath);
         return await self._firestoreMethods.deleteDoc(docRef);
+      },
+
+      onSnapshot(callback, errorCallback) {
+        let unsubscribe = function () {};
+
+        self._ensureInitialized().then(function () {
+          const docRef = self._firestoreMethods.doc(self._db, docPath);
+
+          unsubscribe = self._firestoreMethods.onSnapshot(docRef, function (docSnap) {
+            callback({
+              exists: () => docSnap.exists(),
+              data: () => docSnap.data(),
+              id: docSnap.id,
+              ref: docRef,
+            });
+          }, errorCallback);
+        });
+
+        return function () { unsubscribe(); };
       }
     };
   }
@@ -192,51 +212,87 @@ class Firestore {
       },
 
       async get() {
-        await self._ensureInitialized();
-        const collRef = self._firestoreMethods.collection(self._db, collectionPath);
-
-        // Build query constraints
-        const queryConstraints = [];
-        for (const constraint of constraints) {
-          switch (constraint.type) {
-            case 'where':
-              queryConstraints.push(self._firestoreMethods.where(constraint.field, constraint.operator, constraint.value));
-              break;
-            case 'orderBy':
-              queryConstraints.push(self._firestoreMethods.orderBy(constraint.field, constraint.direction));
-              break;
-            case 'limit':
-              queryConstraints.push(self._firestoreMethods.limit(constraint.count));
-              break;
-            case 'startAt':
-              queryConstraints.push(self._firestoreMethods.startAt(...constraint.values));
-              break;
-            case 'endAt':
-              queryConstraints.push(self._firestoreMethods.endAt(...constraint.values));
-              break;
-          }
-        }
-
-        const q = self._firestoreMethods.query(collRef, ...queryConstraints);
-        const querySnapshot = await self._firestoreMethods.getDocs(q);
+        return self._executeQuery(collectionPath, constraints);
+      },
 
-        return {
-          docs: querySnapshot.docs.map(doc => ({
-            id: doc.id,
-            data: () => doc.data(),
-            exists: () => doc.exists(),
-            ref: doc.ref
-          })),
-          size: querySnapshot.size,
-          empty: querySnapshot.empty,
-          forEach: (callback) => querySnapshot.forEach(callback)
-        };
+      onSnapshot(callback, errorCallback) {
+        let unsubscribe = function () {};
+
+        self._ensureInitialized().then(function () {
+          const collRef = self._firestoreMethods.collection(self._db, collectionPath);
+          const queryConstraints = self._buildConstraints(constraints);
+          const q = self._firestoreMethods.query(collRef, ...queryConstraints);
+
+          unsubscribe = self._firestoreMethods.onSnapshot(q, function (querySnapshot) {
+            callback({
+              docs: querySnapshot.docs.map(doc => ({
+                id: doc.id,
+                data: () => doc.data(),
+                exists: () => doc.exists(),
+                ref: doc.ref,
+              })),
+              size: querySnapshot.size,
+              empty: querySnapshot.empty,
+              forEach: (cb) => querySnapshot.forEach(cb),
+            });
+          }, errorCallback);
+        });
+
+        return function () { unsubscribe(); };
       }
     };
 
     return queryBuilder;
   }
 
+  // Build query constraint objects from constraint descriptors
+  _buildConstraints(constraints) {
+    const queryConstraints = [];
+
+    for (const constraint of constraints) {
+      switch (constraint.type) {
+        case 'where':
+          queryConstraints.push(this._firestoreMethods.where(constraint.field, constraint.operator, constraint.value));
+          break;
+        case 'orderBy':
+          queryConstraints.push(this._firestoreMethods.orderBy(constraint.field, constraint.direction));
+          break;
+        case 'limit':
+          queryConstraints.push(this._firestoreMethods.limit(constraint.count));
+          break;
+        case 'startAt':
+          queryConstraints.push(this._firestoreMethods.startAt(...constraint.values));
+          break;
+        case 'endAt':
+          queryConstraints.push(this._firestoreMethods.endAt(...constraint.values));
+          break;
+      }
+    }
+
+    return queryConstraints;
+  }
+
+  // Execute a query and return formatted results
+  async _executeQuery(collectionPath, constraints) {
+    await this._ensureInitialized();
+    const collRef = this._firestoreMethods.collection(this._db, collectionPath);
+    const queryConstraints = this._buildConstraints(constraints);
+    const q = this._firestoreMethods.query(collRef, ...queryConstraints);
+    const querySnapshot = await this._firestoreMethods.getDocs(q);
+
+    return {
+      docs: querySnapshot.docs.map(doc => ({
+        id: doc.id,
+        data: () => doc.data(),
+        exists: () => doc.exists(),
+        ref: doc.ref,
+      })),
+      size: querySnapshot.size,
+      empty: querySnapshot.empty,
+      forEach: (callback) => querySnapshot.forEach(callback),
+    };
+  }
+
   // Helper to generate document IDs (similar to Firebase auto-generated IDs)
   _generateId() {
     const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-manager",
-  "version": "4.1.24",
+  "version": "4.1.26",
   "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",