backend-manager 5.0.144 → 5.0.146

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.144",
+  "version": "5.0.146",
   "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/events/firestore/payments-webhooks/transitions/subscription/new-subscription.js

@@ -10,7 +10,12 @@ module.exports = async function ({ before, after, order, uid, userDoc, assistant
   const brandName = assistant.Manager.config.brand?.name || '';
   const planName = after.product?.name || '';
 
-  assistant.log(`Transition [subscription/new-subscription]: uid=${uid}, product=${after.product?.id}, frequency=${after.payment?.frequency}, trial=${isTrial}`);
+  // Pre-compute discount values for the email template
+  const price = parseFloat(order.unified?.payment?.price || 0);
+  const discount = order.discount;
+  const hasPromoDiscount = discount?.valid === true && discount?.percent > 0;
+
+  assistant.log(`Transition [subscription/new-subscription]: uid=${uid}, product=${after.product?.id}, frequency=${after.payment?.frequency}, trial=${isTrial}, discount=${hasPromoDiscount ? discount.code : 'none'}`);
 
   sendOrderEmail({
     template: 'main/order/confirmation',
@@ -26,6 +31,16 @@ module.exports = async function ({ before, after, order, uid, userDoc, assistant
           ...(isTrial && after.trial?.expires?.timestamp && {
             trialExpires: formatDate(after.trial.expires.timestamp),
           }),
+          ...(hasPromoDiscount && {
+            promoCode: discount.code,
+            promoPercent: discount.percent,
+            promoSavings: (price * discount.percent / 100).toFixed(2),
+          }),
+          totalToday: isTrial
+            ? '0.00'
+            : hasPromoDiscount
+              ? (price - (price * discount.percent / 100)).toFixed(2)
+              : price.toFixed(2),
         },
       },
     },

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/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');
       },
     },