backend-manager 5.0.73 → 5.0.75

package/CLAUDE.md

@@ -490,6 +490,76 @@ assert.fail(message)                           // Explicit fail
 | `src/test/utils/http-client.js` | HTTP client |
 | `src/test/test-accounts.js` | Test account definitions |
 
+## Subscription System
+
+### Subscription Statuses
+
+| Status | Meaning | User can delete account? |
+|--------|---------|--------------------------|
+| `active` | Subscription is current and valid (includes trialing) | No (unless `product.id === 'basic'`) |
+| `suspended` | Payment failed (Stripe: `past_due`, `unpaid`) | No |
+| `cancelled` | Subscription terminated (Stripe: `canceled`, `incomplete`, `incomplete_expired`) | Yes |
+
+### Stripe Status Mapping
+
+| Stripe Status | `subscription.status` | Notes |
+|---|---|---|
+| `active` | `active` | Normal active subscription |
+| `trialing` | `active` | `trial.activated = true` |
+| `past_due` | `suspended` | Payment failed, retrying |
+| `unpaid` | `suspended` | Payment failed |
+| `canceled` | `cancelled` | Subscription terminated |
+| `incomplete` | `cancelled` | Never completed initial payment |
+| `incomplete_expired` | `cancelled` | Expired before completion |
+| `active` + `cancel_at_period_end` | `active` | `cancellation.pending = true` |
+
+### Unified Subscription Object (`users/{uid}.subscription`)
+
+```javascript
+subscription: {
+  product: {
+    id: 'basic',                   // product ID from config ('basic', 'premium', etc.)
+    name: 'Basic',                 // display name from config
+  },
+  status: 'active',                // 'active' | 'suspended' | 'cancelled'
+  expires: { timestamp, timestampUNIX },
+  trial: {
+    activated: false,              // has user EVER used a trial
+    expires: { timestamp, timestampUNIX },
+  },
+  cancellation: {
+    pending: false,                // true = cancel at period end
+    date: { timestamp, timestampUNIX },
+  },
+  payment: {
+    processor: null,               // 'stripe' | 'paypal' | etc.
+    resourceId: null,              // provider subscription ID (e.g., 'sub_xxx')
+    frequency: null,               // 'monthly' | 'annually'
+    startDate: { timestamp, timestampUNIX },
+    updatedBy: {
+      event: { name: null, id: null },
+      date: { timestamp, timestampUNIX },
+    },
+  },
+}
+```
+
+### Access Check Patterns
+
+```javascript
+// Is premium (paid)?
+user.subscription.status === 'active' && user.subscription.product.id !== 'basic'
+
+// Is on trial?
+user.subscription.trial.activated && user.subscription.status === 'active'
+
+// Has pending cancellation?
+user.subscription.cancellation.pending === true
+
+// Payment failed?
+user.subscription.status === 'suspended'
+```
+
 ## Common Mistakes to Avoid
 
 1. **Don't modify Manager internals directly** - Use factory methods and public APIs

package/README.md

@@ -460,13 +460,14 @@ const userProps = Manager.User(existingData, { defaults: true }).properties;
 // User structure:
 {
   auth: { uid, email, temporary },
-  plan: {
-    id: 'basic',           // basic | advanced | premium
-    status: 'active',      // active | suspended | cancelled
+  subscription: {
+    product: { id, name },   // product from config ('basic', 'premium', etc.)
+    status: 'active',        // active | suspended | cancelled
     expires: { timestamp, timestampUNIX },
     trial: { activated, expires: {...} },
+    cancellation: { pending, date: {...} },
     limits: {},
-    payment: { processor, orderId, resourceId, frequency, active, startDate, updatedBy }
+    payment: { processor, resourceId, frequency, startDate, updatedBy }
   },
   roles: { admin, betaTester, developer },
   affiliate: { code, referrals, referrer },
@@ -478,7 +479,6 @@ const userProps = Manager.User(existingData, { defaults: true }).properties;
 }
 
 // Methods
-userProps.resolve();           // Check plan expiration
 userProps.merge(otherUser);    // Merge with another user object
 ```
 
@@ -602,7 +602,7 @@ const results = await utilities.iterateCollection(
     collection: 'users',
     batchSize: 1000,
     maxBatches: 10,
-    where: [{ field: 'plan.id', operator: '==', value: 'premium' }],
+    where: [{ field: 'subscription.product.id', operator: '==', value: 'premium' }],
     orderBy: { field: 'activity.created.timestamp', direction: 'desc' },
     startAfter: 'lastDocId',
     log: true,
@@ -710,7 +710,7 @@ const user = await assistant.authenticate();
   authenticated: true,
   auth: { uid: 'abc123', email: 'user@example.com' },
   roles: { admin: false, betaTester: false, developer: false },
-  plan: { id: 'basic', status: 'active', ... },
+  subscription: { product: { id: 'basic', name: 'Basic' }, status: 'active', ... },
   api: { clientId: '...', privateKey: '...' },
   // ... other user properties
 }
@@ -857,6 +857,80 @@ module.exports = {
 
 See `CLAUDE.md` for complete test API documentation.
 
+## Subscription System
+
+BEM includes a built-in payment/subscription system with Stripe integration (extensible to other providers).
+
+### Subscription Statuses
+
+| Status | Meaning | User can delete account? |
+|--------|---------|--------------------------|
+| `active` | Subscription is current and valid (includes trialing) | No (unless `product.id === 'basic'`) |
+| `suspended` | Payment failed (Stripe: `past_due`, `unpaid`) | No |
+| `cancelled` | Subscription terminated (Stripe: `canceled`, `incomplete`, `incomplete_expired`) | Yes |
+
+### Stripe Status Mapping
+
+| Stripe Status | `subscription.status` | Notes |
+|---|---|---|
+| `active` | `active` | Normal active subscription |
+| `trialing` | `active` | `trial.activated = true` |
+| `past_due` | `suspended` | Payment failed, retrying |
+| `unpaid` | `suspended` | Payment failed |
+| `canceled` | `cancelled` | Subscription terminated |
+| `incomplete` | `cancelled` | Never completed initial payment |
+| `incomplete_expired` | `cancelled` | Expired before completion |
+| `active` + `cancel_at_period_end` | `active` | `cancellation.pending = true` |
+
+### Unified Subscription Object
+
+The same subscription shape is stored in `users/{uid}.subscription` and `payments-subscriptions/{subId}.subscription`:
+
+```javascript
+subscription: {
+  product: {
+    id: 'basic',                   // product ID from config ('basic', 'premium', etc.)
+    name: 'Basic',                 // display name from config
+  },
+  status: 'active',                // 'active' | 'suspended' | 'cancelled'
+  expires: { timestamp, timestampUNIX },
+  trial: {
+    activated: false,              // has user EVER used a trial
+    expires: { timestamp, timestampUNIX },
+  },
+  cancellation: {
+    pending: false,                // true = cancel at period end
+    date: { timestamp, timestampUNIX },
+  },
+  payment: {
+    processor: null,               // 'stripe' | 'paypal' | etc.
+    resourceId: null,              // provider subscription ID (e.g., 'sub_xxx')
+    frequency: null,               // 'monthly' | 'annually'
+    startDate: { timestamp, timestampUNIX },
+    updatedBy: {
+      event: { name: null, id: null },
+      date: { timestamp, timestampUNIX },
+    },
+  },
+}
+```
+
+### Access Check Patterns
+
+```javascript
+// Is premium (paid)?
+user.subscription.status === 'active' && user.subscription.product.id !== 'basic'
+
+// Is on trial?
+user.subscription.trial.activated && user.subscription.status === 'active'
+
+// Has pending cancellation?
+user.subscription.cancellation.pending === true
+
+// Payment failed?
+user.subscription.status === 'suspended'
+```
+
 ## 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.73",
+  "version": "5.0.75",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/manager/cron/daily/reset-usage.js

@@ -1,5 +1,3 @@
-const fetch = require('wonderful-fetch');
-
 /**
  * Reset usage cron job
  *
@@ -38,42 +36,17 @@ async function clearFirestore(Manager, assistant, libraries) {
   // Log status
   assistant.log('[firestore]: Starting...');
 
-  // Clear storage
-  const metrics = await fetch('https://us-central1-itw-creative-works.cloudfunctions.net/getApp', {
-    method: 'post',
-    response: 'json',
-    body: {
-      id: Manager.config.app.id,
-    },
-  })
-  .then(response => {
-    response.products = response.products || {};
-
-    for (let product of Object.values(response.products)) {
-      product = product || {};
-      product.planId = product.planId || '';
-
-      if (product.planId.includes('basic')) {
-        return product.limits;
-      }
-    }
-
-    return new Error('No basic product found');
-  })
-  .catch(e => e);
+  // Get metric names from the basic product in config
+  const products = Manager.config.products || [];
+  const basicProduct = products.find(p => p.id === 'basic') || {};
+  const metrics = { ...(basicProduct.limits || {}) };
 
   // Ensure requests is always included as a default metric
-  if (!(metrics instanceof Error)) {
-    metrics.requests = metrics.requests || 1;
-  }
+  metrics.requests = metrics.requests || 1;
 
   // Log status
   assistant.log('[firestore]: Resetting metrics', metrics);
 
-  if (metrics instanceof Error) {
-    throw assistant.errorify(`Failed to check providers: ${metrics}`, { code: 500 });
-  }
-
   // Reset all metrics with for loop of metrics
   // TODO: OPTIMIZATION: Put all of the changes into a single batch
   for (const metric of Object.keys(metrics)) {

package/src/manager/events/firestore/payments-webhooks/on-write.js

@@ -0,0 +1,126 @@
+const powertools = require('node-powertools');
+
+/**
+ * Firestore trigger: payments-webhooks/{eventId} onWrite
+ *
+ * Processes pending webhook events:
+ * 1. Transforms raw provider data into unified subscription object
+ * 2. Updates the user's subscription in users/{uid}
+ * 3. Stores the subscription doc in payments-subscriptions/{resourceId}
+ * 4. Marks the webhook as completed
+ */
+module.exports = async ({ Manager, assistant, change, context, libraries }) => {
+  const { admin } = libraries;
+
+  const dataAfter = change.after.data();
+
+  // Short-circuit: deleted doc or non-pending status
+  if (!dataAfter || dataAfter.status !== 'pending') {
+    return;
+  }
+
+  const eventId = context.params.eventId;
+  const webhookRef = admin.firestore().doc(`payments-webhooks/${eventId}`);
+
+  // Set status to processing
+  await webhookRef.set({ status: 'processing' }, { merge: true });
+
+  try {
+    const processor = dataAfter.processor;
+    const uid = dataAfter.uid;
+    const raw = dataAfter.raw;
+    const eventType = dataAfter.event?.type;
+
+    // Validate UID
+    if (!uid) {
+      throw new Error('Webhook event has no UID — cannot process');
+    }
+
+    // Load and initialize the shared library for this processor
+    let library;
+    try {
+      library = require(`../../../libraries/${processor}.js`);
+    } catch (e) {
+      throw new Error(`Unknown processor library: ${processor}`);
+    }
+
+    library.init();
+
+    // Extract the subscription object from the raw event
+    // Stripe sends events with event.data.object as the subscription
+    const rawSubscription = raw.data?.object || {};
+
+    // Transform raw data into unified subscription object
+    const unified = library.toUnified(rawSubscription, {
+      config: Manager.config,
+      eventName: eventType,
+      eventId: eventId,
+    });
+
+    assistant.log(`Processing webhook ${eventId}:`, {
+      processor,
+      uid,
+      eventType,
+      productId: unified.product.id,
+      status: unified.status,
+    });
+
+    // Build timestamps
+    const now = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+    // Write unified subscription to user doc
+    await admin.firestore().doc(`users/${uid}`).set({
+      subscription: unified,
+    }, { merge: true });
+
+    // Write to payments-subscriptions/{resourceId}
+    const resourceId = unified.payment.resourceId;
+    if (resourceId) {
+      await admin.firestore().doc(`payments-subscriptions/${resourceId}`).set({
+        uid: uid,
+        processor: processor,
+        subscription: unified,
+        raw: rawSubscription,
+        metadata: {
+          created: {
+            timestamp: now,
+            timestampUNIX: nowUNIX,
+          },
+          updated: {
+            timestamp: now,
+            timestampUNIX: nowUNIX,
+          },
+          updatedBy: {
+            event: {
+              name: eventType,
+              id: eventId,
+            },
+          },
+        },
+      }, { merge: true });
+    }
+
+    // Mark webhook as completed
+    await webhookRef.set({
+      status: 'completed',
+      uid: uid,
+      metadata: {
+        processed: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+      },
+    }, { merge: true });
+
+    assistant.log(`Webhook ${eventId} processed successfully`);
+  } catch (e) {
+    assistant.error(`Webhook ${eventId} processing failed:`, e);
+
+    // Mark as failed with error message
+    await webhookRef.set({
+      status: 'failed',
+      error: e.message || String(e),
+    }, { merge: true });
+  }
+};

package/src/manager/functions/core/actions/api/admin/get-stats.js

@@ -265,7 +265,7 @@ Module.prototype.getAllSubscriptions = function () {
 
     // Get subscriptions
     await self.libraries.admin.firestore().collection('users')
-    .where('plan.expires.timestampUNIX', '>=', new Date().getTime() / 1000)
+    .where('subscription.expires.timestampUNIX', '>=', new Date().getTime() / 1000)
     .get()
     .then((snapshot) => {
       const stats = {
@@ -280,8 +280,8 @@ Module.prototype.getAllSubscriptions = function () {
       snapshot
       .forEach((doc, i) => {
         const data = doc.data();
-        const planId = data?.plan?.id || 'basic';
-        const frequency = data?.plan?.payment?.frequency || 'unknown';
+        const planId = data?.subscription?.product?.id || 'basic';
+        const frequency = data?.subscription?.payment?.frequency || 'unknown';
         const isAdmin = data?.roles?.admin || false;
         const isVip = data?.roles?.vip || false;
 

package/src/manager/functions/core/actions/api/general/add-marketing-contact.js

@@ -62,7 +62,7 @@ Module.prototype.main = function () {
 
       // Check rate limit via Usage API
       try {
-        await usage.validate('marketing-subscribe', { throw: true, useCaptchaResponse: false });
+        await usage.validate('marketing-subscribe', { useCaptchaResponse: false });
         usage.increment('marketing-subscribe');
         await usage.update();
       } catch (e) {

package/src/manager/functions/core/actions/api/user/delete.js

@@ -17,10 +17,12 @@ Module.prototype.main = function () {
     .then(async (user) => {
       const uid = user?.auth?.uid;
 
-      // Disallow deleting users with subscriptions in any state other than cancelled or active payments
+      // Disallow deleting users with active or suspended paid subscriptions
+      const subStatus = user?.subscription?.status;
+      const subId = user?.subscription?.product?.id;
       if (
-        (user?.plan?.status && user?.plan?.status !== 'cancelled')
-        || user?.plan?.payment?.active
+        (subStatus === 'active' || subStatus === 'suspended')
+        && subId !== 'basic'
       ) {
         return reject(assistant.errorify(`This account cannot be deleted because it has a paid subscription attached to it. In order to delete the account, you must first cancel the paid subscription.`, {code: 400}));
       }

package/src/manager/functions/core/actions/api/user/get-subscription-info.js

@@ -18,21 +18,37 @@ Module.prototype.main = function () {
     Api.resolveUser({adminRequired: false})
     .then(async (user) => {
       const result = {
-        plan: {
-          id: user?.plan?.id || 'unknown',
+        subscription: {
+          product: {
+            id: user?.subscription?.product?.id || 'basic',
+            name: user?.subscription?.product?.name || 'Basic',
+          },
+          status: user?.subscription?.status || 'active',
           expires: {
-            timestamp: user?.plan?.expires?.timestamp || oldDate,
-            timestampUNIX: user?.plan?.expires?.timestampUNIX || oldDateUNIX,
+            timestamp: user?.subscription?.expires?.timestamp || oldDate,
+            timestampUNIX: user?.subscription?.expires?.timestampUNIX || oldDateUNIX,
           },
           trial: {
-            activated: user?.plan?.trial?.activated ?? false,
+            activated: user?.subscription?.trial?.activated ?? false,
+            expires: {
+              timestamp: user?.subscription?.trial?.expires?.timestamp || oldDate,
+              timestampUNIX: user?.subscription?.trial?.expires?.timestampUNIX || oldDateUNIX,
+            },
+          },
+          cancellation: {
+            pending: user?.subscription?.cancellation?.pending ?? false,
             date: {
-              timestamp: user?.plan?.trial?.date?.timestamp || oldDate,
-              timestampUNIX: user?.plan?.trial?.date?.timestampUNIX || oldDateUNIX,
-            }
+              timestamp: user?.subscription?.cancellation?.date?.timestamp || oldDate,
+              timestampUNIX: user?.subscription?.cancellation?.date?.timestampUNIX || oldDateUNIX,
+            },
           },
           payment: {
-            active: user?.plan?.payment?.active ?? false,
+            processor: user?.subscription?.payment?.processor || null,
+            frequency: user?.subscription?.payment?.frequency || null,
+            startDate: {
+              timestamp: user?.subscription?.payment?.startDate?.timestamp || oldDate,
+              timestampUNIX: user?.subscription?.payment?.startDate?.timestampUNIX || oldDateUNIX,
+            },
           },
         }
       }

package/src/manager/functions/core/actions/api/user/validate-settings.js

@@ -36,7 +36,7 @@ Module.prototype.main = function () {
       // Load the file
       try {
         const defaults = _.get(require(resolvedPath)(), payload.data.payload.defaultsPath);
-        const combined = combine(defaults.all, defaults[user.plan.id] || {})
+        const combined = combine(defaults.all, defaults[user.subscription.product.id] || {})
 
         assistant.log('Combined settings', combined)
 

package/src/manager/helpers/analytics.js

@@ -110,11 +110,11 @@ function Analytics(Manager, options) {
     authenticated: {
       value: authUser?.auth?.uid ? true : false,
     },
-    plan_id: {
-      value: authUser?.plan?.id || 'basic',
+    subscription_id: {
+      value: authUser?.subscription?.product?.id || 'basic',
     },
-    plan_trial_activated: {
-      value: authUser?.plan?.trial?.activated || false,
+    subscription_trial_activated: {
+      value: authUser?.subscription?.trial?.activated || false,
     },
     activity_created: {
       value: moment(authUser?.activity?.created?.timestampUNIX

package/src/manager/helpers/api-manager.js

@@ -1,13 +1,14 @@
 const moment = require('moment');
-const fetch = require('node-fetch');
 const uuidv5 = require('uuid').v5;
 const { get, set, merge } = require('lodash');
 
 let sampleUser = {
   api: {},
   auth: {},
-  plan: {
-    id: '',
+  subscription: {
+    product: {
+      id: '',
+    },
     limits: {
 
     }
@@ -52,40 +53,20 @@ ApiManager.prototype.init = function (options) {
     options.officialAPIKeys = options.officialAPIKeys || [];
     options.whitelistedAPIKeys = options.whitelistedAPIKeys || [];
 
-    await fetch('https://us-central1-itw-creative-works.cloudfunctions.net/getApp', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        id: options.app,
-      }),
-    })
-    .then(res => {
-      res.text()
-      .then(text => {
-        if (res.ok) {
-          const data = JSON.parse(text);
-
-          options.plans = {};
-
-          Object.keys(data.products)
-          .forEach((id, i) => {
-            const product = data.products[id]
-            options.plans[product.planId] = {}
-            options.plans[product.planId].limits = product.limits || {};
-          });
-
-          self.options = options;
-          self.initialized = true;
-
-          return resolve(self);
-        } else {
-          throw new Error(text || res.statusText || 'Unknown error.')
-        }
-      })
-    })
-    .catch(e => {
-      return reject(e)
-    })
+    // Read limits from config products
+    const products = self.Manager.config.products || [];
+    options.plans = {};
+
+    for (const product of products) {
+      options.plans[product.id] = {
+        limits: product.limits || {},
+      };
+    }
+
+    self.options = options;
+    self.initialized = true;
+
+    return resolve(self);
   });
 };
 
@@ -107,8 +88,10 @@ ApiManager.prototype._createNewUser = function (authenticatedUser, planId, persi
   let newUser = {
     api: authenticatedUser?.api || {},
     auth: authenticatedUser?.auth || {},
-    plan: {
-      id: planId,
+    subscription: {
+      product: {
+        id: planId,
+      },
       limits: {
       }
     },
@@ -124,7 +107,7 @@ ApiManager.prototype._createNewUser = function (authenticatedUser, planId, persi
   .forEach((id, i) => {
     // console.log('----id', id);
     // console.log('======currentPlan[id]', currentPlan[id]);
-    newUser.plan.limits[id] = get(authenticatedUser, `plan.limits.${id}`, currentPlan[id])
+    newUser.subscription.limits[id] = get(authenticatedUser, `subscription.limits.${id}`, currentPlan[id])
     // const product = data.products[id]
     // options.plans[product.planId] = {}
     // options.plans[product.planId].limits = product.limits || {};
@@ -185,7 +168,7 @@ ApiManager.prototype.getUser = async function (assistant) {
     // console.log('---doesnt exist so reauthing');
     authenticatedUser = await assistant.authenticate({apiKey: apiKey});
     // console.log('---authenticatedUser', authenticatedUser);
-    const planId = authenticatedUser?.plan?.id || 'basic';
+    const planId = authenticatedUser?.subscription?.product?.id || 'basic';
     let workingUID = !authenticatedUser.authenticated
       ? uuidv5(assistant.request.geolocation.ip, '1b671a64-40d5-491e-99b0-da01ff1f3341')
       : authenticatedUser.auth.uid
@@ -229,7 +212,7 @@ function _getUserStat(self, user, stat, def) {
   // console.log('----isWhitelistedAPIKey', isWhitelistedAPIKey);
   return {
     current: !isWhitelistedAPIKey ? get(user, `_APIManager.stats.${stat}`, typeof def !== 'undefined' ? def : 0) : 0,
-    limit: !isWhitelistedAPIKey ? get(user, `plan.limits.${stat}`, typeof def !== 'undefined' ? def : 0) : Infinity,
+    limit: !isWhitelistedAPIKey ? get(user, `subscription.limits.${stat}`, typeof def !== 'undefined' ? def : 0) : Infinity,
   }
 }
 

package/src/manager/helpers/middleware.js

@@ -126,7 +126,7 @@ Middleware.prototype.run = function (libPath, options) {
 
     // Log working user
     const workingUser = assistant.getUser();
-    assistant.log(`Middleware.process(): User (${workingUser.auth.uid}, ${workingUser.auth.email}, ${workingUser.plan.id}=${workingUser.plan.status}):`, safeStringify(workingUser));
+    assistant.log(`Middleware.process(): User (${workingUser.auth.uid}, ${workingUser.auth.email}, ${workingUser.subscription.product.id}=${workingUser.subscription.status}):`, safeStringify(workingUser));
 
     // Setup analytics
     if (options.setupAnalytics) {