web-manager 4.1.23 → 4.1.25

package/CHANGELOG.md

@@ -14,6 +14,16 @@ 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
+- Added `resolveSubscription()` method to Auth module that derives calculated subscription fields (plan, active, trialing, cancelling) from raw backend data.
+
 ---
 ## [4.1.22] - 2026-03-11
 ### Changed

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 });
@@ -218,6 +221,37 @@ class Auth {
     });
   }
 
+  // Resolves calculated subscription fields that require derivation logic
+  // Raw data (product.id, status, trial, cancellation) is on account.subscription directly
+  // Returns: { plan, active, trialing, cancelling }
+  // - plan: the plan ID the user effectively has access to RIGHT NOW ('basic' if cancelled/suspended)
+  // - active: user has active access (active, trialing, or cancelling)
+  // - trialing: user is in an active trial (backend status is 'active' but trial hasn't expired)
+  // - cancelling: cancellation is pending (backend status is 'active' but cancellation.pending is true)
+  resolveSubscription(account) {
+    const subscription = (account || this.manager.storage().get('auth', {})?.account)?.subscription || {};
+    const productId = subscription.product?.id || 'basic';
+
+    // Derive trial and cancelling states from raw backend data
+    let trialing = false;
+    let cancelling = false;
+
+    if (productId !== 'basic' && subscription.status === 'active') {
+      trialing = !!(subscription.trial?.claimed
+        && subscription.trial?.expires?.timestampUNIX > Math.floor(Date.now() / 1000));
+      cancelling = !trialing && !!subscription.cancellation?.pending;
+    }
+
+    const active = (productId !== 'basic' && subscription.status === 'active');
+
+    return {
+      plan: active ? productId : 'basic',
+      active,
+      trialing,
+      cancelling,
+    };
+  }
+
   // Get ID token for the current user
   async getIdToken(forceRefresh = false) {
     try {

package/package.json

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