backend-manager 5.0.143 → 5.0.145

package/CHANGELOG.md

@@ -14,6 +14,15 @@ 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.
 
+# [5.0.144] - 2026-03-13
+### Added
+- `User.resolveSubscription()` static method that derives calculated subscription fields (plan, active, trialing, cancelling) from raw user data
+
+# [5.0.143] - 2026-03-13
+### Changed
+- `sendOrderEmail()` now accepts a `copy` parameter to control whether admin receives a copy (defaults to `true` for backward compat)
+- Abandoned cart reminder emails no longer send admin copies (`copy: false`) to reduce inbox noise
+
 # [5.0.140] - 2026-03-12
 ### Fixed
 - Chargebee meta_data backfill not including `orderId`, causing `getOrderId()` to fail on future webhooks

package/CLAUDE.md

@@ -809,6 +809,38 @@ user.subscription.cancellation.pending === true
 user.subscription.status === 'suspended'
 ```
 
+### resolveSubscription(account)
+
+`User.resolveSubscription(account)` is a static method on the User helper that derives calculated subscription fields from raw account data. It returns only fields that require derivation logic — raw data (product.id, status, trial, cancellation) lives on the account object directly.
+
+```javascript
+const User = require('backend-manager/src/manager/helpers/user');
+
+const resolved = User.resolveSubscription(account);
+// Returns: { plan, active, trialing, cancelling }
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `plan` | `string` | Effective plan ID the user has access to RIGHT NOW (`'basic'` if cancelled/suspended) |
+| `active` | `boolean` | User has active access (active, trialing, or cancelling) |
+| `trialing` | `boolean` | In an active trial (status `'active'` + `trial.claimed` + unexpired `trial.expires`) |
+| `cancelling` | `boolean` | Cancellation pending (status `'active'` + `cancellation.pending` + NOT trialing) |
+
+Accepts either a raw Firestore account object or a resolved `User` instance (checks both `account.subscription` and `account.properties.subscription`).
+
+**Unified with web-manager**: The same function exists as `auth.resolveSubscription(account)` in web-manager (`modules/auth.js`) with identical logic and return shape.
+
+**Use this instead of manual access checks** — it centralizes all the derivation logic in one place:
+```javascript
+// ✅ PREFERRED — use resolveSubscription
+const resolved = User.resolveSubscription(user);
+if (resolved.active) { /* has access */ }
+
+// ❌ AVOID — manual checks that duplicate logic
+if (user.subscription.status === 'active' && user.subscription.product.id !== 'basic') { /* ... */ }
+```
+
 ## Payment Transition Handlers
 
 ### Overview

package/README.md

@@ -471,7 +471,8 @@ const userProps = Manager.User(existingData, { defaults: true }).properties;
   },
   roles: { admin, betaTester, developer },
   affiliate: { code, referrals, referrer },
-  activity: { lastActivity, created, geolocation, client },
+  metadata: { created, updated },
+  activity: { geolocation, client },
   api: { clientId, privateKey },
   usage: { requests: { monthly, daily, total, last } },
   personal: { birthday, gender, location, name, company, telephone },
@@ -608,7 +609,7 @@ const results = await utilities.iterateCollection(
     batchSize: 1000,
     maxBatches: 10,
     where: [{ field: 'subscription.product.id', operator: '==', value: 'premium' }],
-    orderBy: { field: 'activity.created.timestamp', direction: 'desc' },
+    orderBy: { field: 'metadata.created.timestamp', direction: 'desc' },
     startAfter: 'lastDocId',
     log: true,
   }
@@ -994,6 +995,26 @@ user.subscription.cancellation.pending === true
 user.subscription.status === 'suspended'
 ```
 
+### resolveSubscription(account)
+
+Static method on the `User` helper that derives calculated subscription fields. Returns only fields that require derivation logic — raw data lives on the account object directly.
+
+```javascript
+const User = require('backend-manager/src/manager/helpers/user');
+
+const resolved = User.resolveSubscription(account);
+// Returns: { plan, active, trialing, cancelling }
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `plan` | `string` | Effective plan ID right now (`'basic'` if cancelled/suspended) |
+| `active` | `boolean` | Has paid access (product is not `'basic'` and status is `'active'`) |
+| `trialing` | `boolean` | In active trial (status `'active'` + claimed + unexpired) |
+| `cancelling` | `boolean` | Cancellation pending (status `'active'` + `cancellation.pending`) |
+
+The same function exists as `auth.resolveSubscription(account)` in [web-manager](https://github.com/itw-creative-works/web-manager) with identical logic and return shape.
+
 ## Final Words
 
 If you are still having difficulty, we would love for you to post a question to [the Backend Manager issues page](https://github.com/itw-creative-works/backend-manager/issues). It is much easier to answer questions that include your code and relevant files! So if you can provide them, we'd be extremely grateful (and more likely to help you find the answer!)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.143",
+  "version": "5.0.145",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/manager/events/auth/on-create.js

@@ -50,8 +50,9 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
     },
   }).properties;
 
-  // Add metadata
-  userRecord.metadata = Manager.Metadata().set({ tag: 'auth:on-create' });
+  // Add metadata tag (merge into existing metadata to preserve metadata.created from User schema)
+  const meta = Manager.Metadata().set({ tag: 'auth:on-create' });
+  userRecord.metadata = { ...userRecord.metadata, ...meta };
 
   assistant.log(`onCreate: Creating user doc for ${user.uid}`, userRecord);
 

package/src/manager/helpers/analytics.js

@@ -117,8 +117,8 @@ function Analytics(Manager, options) {
       value: authUser?.subscription?.trial?.claimed || false,
     },
     activity_created: {
-      value: moment(authUser?.activity?.created?.timestampUNIX
-        ? authUser?.activity?.created?.timestamp
+      value: moment(authUser?.metadata?.created?.timestampUNIX
+        ? authUser?.metadata?.created?.timestamp
         : self.assistant.meta.startTime.timestamp).format('YYYY-MM-DD'),
     },
 

package/src/manager/helpers/user.js

@@ -345,4 +345,34 @@ function User(Manager, settings) {
   return self;
 }
 
+// Resolves calculated subscription fields that require derivation logic
+// Raw data (product.id, status, trial, cancellation) is on the user object 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 (status is 'active' but trial hasn't expired)
+// - cancelling: cancellation is pending (status is 'active' but cancellation.pending is true)
+User.resolveSubscription = function resolveSubscription(account) {
+  const subscription = (account?.subscription || account?.properties?.subscription) || {};
+  const productId = subscription.product?.id || 'basic';
+
+  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,
+  };
+};
+
 module.exports = User;

package/src/manager/libraries/payment/processors/chargebee.js

@@ -91,7 +91,9 @@ const Chargebee = {
 
     if (!response.ok) {
       const msg = data.message || data.error_description || JSON.stringify(data);
-      throw new Error(`Chargebee API ${response.status}: ${msg}`);
+      const err = new Error(`Chargebee API ${response.status}: ${msg}`);
+      err.statusCode = response.status;
+      throw err;
     }
 
     return data;

package/test/_init/accounts-validation.js

@@ -44,9 +44,9 @@ module.exports = {
       // Validate affiliate code (generated by on-create via User helper)
       assert.hasProperty(userDoc, 'affiliate.code', `Account '${accountId}' should have affiliate.code`);
 
-      // Validate activity.created (set by on-create)
-      assert.hasProperty(userDoc, 'activity.created.timestamp', `Account '${accountId}' should have activity.created.timestamp`);
-      assert.hasProperty(userDoc, 'activity.created.timestampUNIX', `Account '${accountId}' should have activity.created.timestampUNIX`);
+      // Validate metadata.created (set by on-create via User helper)
+      assert.hasProperty(userDoc, 'metadata.created.timestamp', `Account '${accountId}' should have metadata.created.timestamp`);
+      assert.hasProperty(userDoc, 'metadata.created.timestampUNIX', `Account '${accountId}' should have metadata.created.timestampUNIX`);
 
       // Validate subscription fields (merged from test account properties)
       assert.hasProperty(userDoc, 'subscription.product.id', `Account '${accountId}' should have subscription.product.id`);

package/test/helpers/user.js

@@ -58,9 +58,9 @@ module.exports = {
         assert.ok(user.affiliate.code.length > 0, 'affiliate.code should not be empty');
         assert.ok(Array.isArray(user.affiliate.referrals), 'affiliate.referrals should be array');
 
-        // Activity
-        assert.ok(user.activity.lastActivity.timestamp, 'activity.lastActivity.timestamp should exist');
-        assert.ok(user.activity.created.timestamp, 'activity.created.timestamp should exist');
+        // Metadata
+        assert.ok(user.metadata.updated.timestamp, 'metadata.updated.timestamp should exist');
+        assert.ok(user.metadata.created.timestamp, 'metadata.created.timestamp should exist');
         assert.equal(user.activity.geolocation.latitude, 0, 'geolocation.latitude should be 0');
         assert.equal(user.activity.geolocation.longitude, 0, 'geolocation.longitude should be 0');
         assert.equal(user.activity.client.mobile, false, 'client.mobile should be false');
@@ -379,8 +379,8 @@ module.exports = {
         assert.equal(user.activity.geolocation.country, 'US', 'provided country preserved');
         assert.equal(user.activity.geolocation.ip, null, 'missing ip defaults to null');
         assert.equal(user.activity.geolocation.latitude, 0, 'missing latitude defaults to 0');
-        assert.ok(user.activity.lastActivity.timestamp, 'missing lastActivity gets default');
-        assert.ok(user.activity.created.timestamp, 'missing created gets default');
+        assert.ok(user.metadata.updated.timestamp, 'missing updated gets default');
+        assert.ok(user.metadata.created.timestamp, 'missing created gets default');
       },
     },