backend-manager 5.0.86 → 5.0.87

package/CLAUDE.md

@@ -621,6 +621,57 @@ user.subscription.cancellation.pending === true
 user.subscription.status === 'suspended'
 ```
 
+## Payment Transition Handlers
+
+### Overview
+
+When a webhook changes a subscription or processes a one-time payment, BEM detects the state transition and dispatches to a handler file. Handlers are fire-and-forget (non-blocking) — they run after the transition is detected but before or during the Firestore writes. Handler failures never block webhook processing.
+
+Handlers are skipped during tests unless `TEST_EXTENDED_MODE` is set.
+
+### Transition Detection
+
+The `transitions/index.js` module compares the **before** state (current `users/{uid}.subscription`) with the **after** state (new unified subscription) to detect what changed.
+
+### Subscription Transitions
+
+| Transition | Before → After | File |
+|---|---|---|
+| `new-subscription` | basic/null → active paid | `transitions/subscription/new-subscription.js` |
+| `trial-started` | basic/null → active paid with trial | `transitions/subscription/trial-started.js` |
+| `payment-failed` | active → suspended | `transitions/subscription/payment-failed.js` |
+| `payment-recovered` | suspended → active | `transitions/subscription/payment-recovered.js` |
+| `cancellation-requested` | pending=false → pending=true | `transitions/subscription/cancellation-requested.js` |
+| `subscription-cancelled` | non-cancelled → cancelled | `transitions/subscription/subscription-cancelled.js` |
+| `plan-changed` | active product A → active product B | `transitions/subscription/plan-changed.js` |
+
+### One-Time Transitions
+
+| Transition | Event Type | File |
+|---|---|---|
+| `purchase-completed` | `checkout.session.completed` | `transitions/one-time/purchase-completed.js` |
+| `purchase-failed` | `invoice.payment_failed` | `transitions/one-time/purchase-failed.js` |
+
+### Handler Interface
+
+All handlers are in `src/manager/events/firestore/payments-webhooks/transitions/` and export a single async function:
+
+```javascript
+module.exports = async function ({ before, after, uid, userDoc, admin, assistant, Manager, eventType, eventId }) {
+  // before: previous subscription state (null for new/one-time)
+  // after: new unified state (subscription or one-time)
+  // userDoc: full user document data
+  // eventType: original webhook event type (e.g., 'customer.subscription.updated')
+  // eventId: webhook event ID
+};
+```
+
+### Creating a New Transition Handler
+
+1. Add detection logic in `transitions/index.js` (in priority order)
+2. Create handler file in `transitions/{category}/{name}.js`
+3. Handler receives full context — use `assistant.log()` for logging, `Manager.project.apiUrl` for API calls
+
 ## Common Mistakes to Avoid
 
 1. **Don't modify Manager internals directly** - Use factory methods and public APIs
@@ -654,7 +705,8 @@ user.subscription.status === 'suspended'
 | Config template | `templates/backend-manager-config.json` |
 | CLI entry | `src/cli/index.js` |
 | Stripe webhook forwarding | `src/cli/commands/stripe.js` |
-| Stripe shared library | `src/manager/libraries/stripe.js` |
+| Payment processor libraries | `src/manager/libraries/payment-processors/` |
+| Payment transition handlers | `src/manager/events/firestore/payments-webhooks/transitions/` |
 
 ## Environment Detection
 

package/package.json

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

package/src/cli/commands/base-command.js

@@ -167,6 +167,10 @@ class BaseCommand {
     const projectDir = this.main.firebaseProjectPath;
     const functionsDir = path.join(projectDir, 'functions');
 
+    // Quit early here because its not supported yet
+    this.log(chalk.gray('  (Stripe webhook forwarding is currently disabled - coming soon!)\n'));
+    return null;
+
     // Load .env so STRIPE_SECRET_KEY and BACKEND_MANAGER_KEY are available
     const envPath = path.join(functionsDir, '.env');
     if (jetpack.exists(envPath)) {
@@ -247,4 +251,4 @@ class BaseCommand {
   }
 }
 
-module.exports = BaseCommand;
+module.exports = BaseCommand;

package/src/cli/commands/serve.js

@@ -12,8 +12,7 @@ class ServeCommand extends BaseCommand {
     watcher.startBackground();
 
     // Start Stripe webhook forwarding in background
-    // Ignored because we cant really fully process them unless the emulator is running
-    // this.startStripeWebhookForwarding();
+    this.startStripeWebhookForwarding();
 
     // Execute
     await powertools.execute(`firebase serve --port ${port}`, { log: true });

package/src/manager/cron/daily/ghostii-auto-publisher.js

@@ -4,7 +4,7 @@ const moment = require('moment');
 const JSON5 = require('json5');
 
 const PROMPT = `
-  Company: {app.name}: {app.brand.description}
+  Company: {app.brand.name}: {app.brand.description}
   Date: {date}
   Instructions: {prompt}
 
@@ -63,7 +63,7 @@ module.exports = async ({ Manager, assistant, context, libraries }) => {
     }
 
     // Log
-    assistant.log(`Settings (app=${settings.app.id})`, settings);
+    assistant.log(`Settings (app=${settings.app.brand.id})`, settings);
 
     // Quit if articles are disabled
     if (!settings.articles || !settings.sources.length) {
@@ -90,21 +90,12 @@ module.exports = async ({ Manager, assistant, context, libraries }) => {
 };
 
 /**
- * Build app object from Manager.config (same shape as getApp response)
+ * Build app object from Manager.config (same shape as /app endpoint response)
  */
 function buildAppObject(config) {
-  return {
-    id: config.app?.id,
-    name: config.brand?.name,
-    brand: {
-      description: config.brand?.description || '',
-    },
-    url: config.brand?.url,
-    github: {
-      user: config.github?.user,
-      repo: (config.github?.repo_website || '').split('/').pop(),
-    },
-  };
+  const { buildPublicConfig } = require(require('path').join(__dirname, '..', '..', 'routes', 'app', 'get.js'));
+
+  return buildPublicConfig(config);
 }
 
 /**
@@ -122,7 +113,7 @@ async function harvest(assistant, settings) {
   const date = moment().format('MMMM YYYY');
 
   // Log
-  assistant.log(`harvest(): Starting ${settings.app.id}...`);
+  assistant.log(`harvest(): Starting ${settings.app.brand.id}...`);
 
   // Process the number of sources in the settings
   for (let index = 0; index < settings.articles; index++) {
@@ -218,16 +209,16 @@ function requestGhostii(settings, content) {
       description: content,
       insertLinks: true,
       headerImageUrl: 'unsplash',
-      url: settings.app.url,
+      url: settings.app.brand.url,
       sectionQuantity: powertools.random(3, 6, { mode: 'gaussian' }),
-      feedUrl: `${settings.app.url}/feeds/posts.json`,
+      feedUrl: `${settings.app.brand.url}/feeds/posts.json`,
       links: settings.links,
     },
   });
 }
 
 function uploadPost(assistant, settings, article) {
-  const apiUrl = `https://api.${(settings.app.url || '').replace(/^https?:\/\//, '')}`;
+  const apiUrl = `https://api.${(settings.app.brand.url || '').replace(/^https?:\/\//, '')}`;
   return fetch(`${apiUrl}/backend-manager/admin/post`, {
     method: 'POST',
     timeout: 90000,

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

@@ -1,13 +1,17 @@
 const powertools = require('node-powertools');
+const transitions = require('./transitions/index.js');
 
 /**
  * Firestore trigger: payments-webhooks/{eventId} onWrite
  *
  * Processes pending webhook events:
- * 1. Transforms raw processor 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
+ * 1. Loads the processor library
+ * 2. Fetches the latest resource from the processor API (not the stale webhook payload)
+ * 3. Branches on event.category to transform + write:
+ *    - subscription → toUnifiedSubscription → users/{uid}.subscription + payments-subscriptions/{resourceId}
+ *    - one-time    → toUnifiedOneTime → payments-one-time/{resourceId}
+ * 4. Detects state transitions and dispatches handler files (non-blocking)
+ * 5. Marks the webhook as completed
  */
 module.exports = async ({ Manager, assistant, change, context, libraries }) => {
   const { admin } = libraries;
@@ -30,83 +34,57 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
     const uid = dataAfter.uid;
     const raw = dataAfter.raw;
     const eventType = dataAfter.event?.type;
+    const category = dataAfter.event?.category;
+    const resourceType = dataAfter.event?.resourceType;
+    const resourceId = dataAfter.event?.resourceId;
 
-    assistant.log(`Processing webhook ${eventId}: processor=${processor}, eventType=${eventType}, uid=${uid || 'null'}`);
+    assistant.log(`Processing webhook ${eventId}: processor=${processor}, eventType=${eventType}, category=${category}, resourceType=${resourceType}, resourceId=${resourceId}, uid=${uid || 'null'}`);
 
     // Validate UID
     if (!uid) {
       throw new Error('Webhook event has no UID — cannot process');
     }
 
-    // Load the shared library for this processor (only needs toUnified, not SDK init)
+    // Validate category
+    if (!category) {
+      throw new Error(`Webhook event has no category — cannot process`);
+    }
+
+    // Load the shared library for this processor
     let library;
     try {
-      library = require(`../../../libraries/${processor}.js`);
+      library = require(`../../../libraries/payment-processors/${processor}.js`);
     } catch (e) {
       throw new Error(`Unknown processor library: ${processor}`);
     }
 
-    // Extract the subscription object from the raw event
-    // Stripe sends events with event.data.object as the subscription
-    const rawSubscription = raw.data?.object || {};
+    // Fetch the latest resource from the processor API
+    // This ensures we always work with the most current state, not stale webhook data
+    const rawFallback = raw.data?.object || {};
+    const resource = await library.fetchResource(resourceType, resourceId, rawFallback, { admin, eventType, config: Manager.config });
 
-    assistant.log(`Raw subscription: stripeStatus=${rawSubscription.status}, cancelAtPeriodEnd=${rawSubscription.cancel_at_period_end}, trialEnd=${rawSubscription.trial_end || 'none'}, resourceId=${rawSubscription.id}`);
-
-    // Transform raw data into unified subscription object
-    const unified = library.toUnified(rawSubscription, {
-      config: Manager.config,
-      eventName: eventType,
-      eventId: eventId,
-    });
-
-    assistant.log(`Unified result: status=${unified.status}, product=${unified.product.id}, frequency=${unified.payment.frequency}, trial.claimed=${unified.trial.claimed}, cancellation.pending=${unified.cancellation.pending}`);
+    assistant.log(`Fetched resource: type=${resourceType}, id=${resourceId}, status=${resource.status || 'unknown'}`);
 
     // 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 });
-
-    assistant.log(`Updated users/${uid}.subscription: status=${unified.status}, product=${unified.product.id}`);
-
-    // 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 });
+    // Branch on category
+    let transitionName = null;
 
-      assistant.log(`Updated payments-subscriptions/${resourceId}: uid=${uid}, eventType=${eventType}`);
+    if (category === 'subscription') {
+      transitionName = await processSubscription({ library, resource, uid, processor, eventType, eventId, resourceId, now, nowUNIX, admin, assistant, Manager });
+    } else if (category === 'one-time') {
+      transitionName = await processOneTime({ library, resource, uid, processor, eventType, eventId, resourceId, now, nowUNIX, admin, assistant, Manager });
     } else {
-      assistant.log(`No resourceId in unified result, skipping payments-subscriptions write`);
+      throw new Error(`Unknown event category: ${category}`);
     }
 
-    // Mark webhook as completed
+    // Mark webhook as completed (include transition name for auditing/testing)
     await webhookRef.set({
       status: 'completed',
       uid: uid,
+      transition: transitionName,
       metadata: {
         processed: {
           timestamp: now,
@@ -115,7 +93,7 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
       },
     }, { merge: true });
 
-    assistant.log(`Webhook ${eventId} completed: wrote users/${uid}, payments-subscriptions/${resourceId || 'skipped'}, payments-webhooks/${eventId}=completed`);
+    assistant.log(`Webhook ${eventId} completed`);
   } catch (e) {
     assistant.error(`Webhook ${eventId} failed: ${e.message}`, e);
 
@@ -126,3 +104,320 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
     }, { merge: true });
   }
 };
+
+/**
+ * Process a subscription event
+ * 1. Read current user subscription (before state)
+ * 2. Transform raw resource → unified subscription (after state)
+ * 3. Detect and dispatch transition handlers (non-blocking)
+ * 4. Write to user doc + payments-subscriptions
+ */
+async function processSubscription({ library, resource, uid, processor, eventType, eventId, resourceId, now, nowUNIX, admin, assistant, Manager }) {
+  // Read current user doc BEFORE writing (for transition detection)
+  const userDoc = await admin.firestore().doc(`users/${uid}`).get();
+  const userData = userDoc.exists ? userDoc.data() : {};
+  const before = userData.subscription || null;
+
+  // Transform to unified subscription (the "after" state)
+  const unified = library.toUnifiedSubscription(resource, {
+    config: Manager.config,
+    eventName: eventType,
+    eventId: eventId,
+  });
+
+  assistant.log(`Unified subscription: status=${unified.status}, product=${unified.product.id}, frequency=${unified.payment.frequency}, trial.claimed=${unified.trial.claimed}, cancellation.pending=${unified.cancellation.pending}`, unified);
+
+  // Detect and dispatch transition (non-blocking)
+  const shouldRunHandlers = !assistant.isTesting() || process.env.TEST_EXTENDED_MODE;
+  const transitionName = transitions.detectTransition('subscription', before, unified, eventType);
+
+  if (transitionName) {
+    assistant.log(`Transition detected: subscription/${transitionName} (before.status=${before?.status || 'null'}, after.status=${unified.status})`);
+
+    if (shouldRunHandlers) {
+      transitions.dispatch(transitionName, 'subscription', {
+        before, after: unified, uid, userDoc: userData, admin, assistant, Manager, eventType, eventId,
+      });
+    } else {
+      assistant.log(`Transition handler skipped (testing mode): subscription/${transitionName}`);
+    }
+  }
+
+  // Track payment analytics (non-blocking)
+  if (transitionName && shouldRunHandlers) {
+    trackPayment({ category: 'subscription', transitionName, unified, uid, processor, assistant, Manager });
+  }
+
+  // Write unified subscription to user doc
+  await admin.firestore().doc(`users/${uid}`).set({
+    subscription: unified,
+  }, { merge: true });
+
+  assistant.log(`Updated users/${uid}.subscription: status=${unified.status}, product=${unified.product.id}`);
+
+  // Write to payments-subscriptions/{resourceId}
+  if (resourceId) {
+    await admin.firestore().doc(`payments-subscriptions/${resourceId}`).set({
+      uid: uid,
+      processor: processor,
+      subscription: unified,
+      metadata: {
+        created: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+        updated: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+        updatedBy: {
+          event: {
+            name: eventType,
+            id: eventId,
+          },
+        },
+      },
+    }, { merge: true });
+
+    assistant.log(`Updated payments-subscriptions/${resourceId}: uid=${uid}, eventType=${eventType}`);
+  }
+
+  return transitionName;
+}
+
+/**
+ * Process a one-time payment event
+ * 1. Transform raw resource → unified one-time
+ * 2. Detect and dispatch transition handlers (non-blocking)
+ * 3. Write to payments-one-time
+ */
+async function processOneTime({ library, resource, uid, processor, eventType, eventId, resourceId, now, nowUNIX, admin, assistant, Manager }) {
+  const unified = library.toUnifiedOneTime(resource, {
+    config: Manager.config,
+    eventName: eventType,
+    eventId: eventId,
+  });
+
+  assistant.log(`Unified one-time: id=${unified.id}, status=${unified.status}`, unified);
+
+  // Detect and dispatch transition (non-blocking)
+  const shouldRunHandlers = !assistant.isTesting() || process.env.TEST_EXTENDED_MODE;
+  const transitionName = transitions.detectTransition('one-time', null, unified, eventType);
+
+  if (transitionName) {
+    assistant.log(`Transition detected: one-time/${transitionName}`);
+
+    if (shouldRunHandlers) {
+      // Read user doc for handler context
+      const userDoc = await admin.firestore().doc(`users/${uid}`).get();
+      const userData = userDoc.exists ? userDoc.data() : {};
+
+      transitions.dispatch(transitionName, 'one-time', {
+        before: null, after: unified, uid, userDoc: userData, admin, assistant, Manager, eventType, eventId,
+      });
+    } else {
+      assistant.log(`Transition handler skipped (testing mode): one-time/${transitionName}`);
+    }
+  }
+
+  // Track payment analytics (non-blocking)
+  if (transitionName && shouldRunHandlers) {
+    trackPayment({ category: 'one-time', transitionName, unified, uid, processor, assistant, Manager });
+  }
+
+  // Write to payments-one-time/{resourceId}
+  if (resourceId) {
+    await admin.firestore().doc(`payments-one-time/${resourceId}`).set({
+      uid: uid,
+      processor: processor,
+      payment: unified,
+      metadata: {
+        created: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+        updated: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+        updatedBy: {
+          event: {
+            name: eventType,
+            id: eventId,
+          },
+        },
+      },
+    }, { merge: true });
+
+    assistant.log(`Updated payments-one-time/${resourceId}: uid=${uid}, eventType=${eventType}`);
+  }
+
+  return transitionName;
+}
+
+/**
+ * Track payment events across analytics platforms (non-blocking)
+ * Fires server-side events for GA4, Meta Conversions API, and TikTok Events API
+ *
+ * Maps transitions to standard platform events:
+ *   new-subscription (no trial) → purchase / Purchase / CompletePayment
+ *   new-subscription (trial)    → start_trial / StartTrial / Subscribe
+ *   payment-recovered           → purchase / Subscribe / Subscribe (recurring)
+ *   purchase-completed          → purchase / Purchase / CompletePayment
+ *
+ * @param {object} options
+ * @param {string} options.category - 'subscription' or 'one-time'
+ * @param {string} options.transitionName - Detected transition (e.g., 'new-subscription', 'purchase-completed')
+ * @param {object} options.unified - Unified subscription or one-time object
+ * @param {string} options.uid - User ID
+ * @param {string} options.processor - Payment processor (e.g., 'stripe', 'paypal')
+ * @param {object} options.assistant - Assistant instance
+ * @param {object} options.Manager - Manager instance
+ */
+function trackPayment({ category, transitionName, unified, uid, processor, assistant, Manager }) {
+  try {
+    // Resolve the analytics event to fire based on transition
+    const event = resolvePaymentEvent(category, transitionName, unified, Manager.config);
+
+    if (!event) {
+      return;
+    }
+
+    assistant.log(`trackPayment: event=${event.ga4}, value=${event.value}, currency=${event.currency}, product=${event.productId}, uid=${uid}`);
+
+    // GA4 via Measurement Protocol
+    Manager.Analytics({ assistant, uuid: uid }).event(event.ga4, {
+      transaction_id: event.transactionId,
+      value: event.value,
+      currency: event.currency,
+      items: [{
+        item_id: event.productId,
+        item_name: event.productName,
+        price: event.value,
+        quantity: 1,
+      }],
+      payment_processor: processor,
+      payment_frequency: event.frequency,
+      is_trial: event.isTrial,
+      is_recurring: event.isRecurring,
+    });
+
+    // TODO: Meta Conversions API
+    // Event name: event.meta (e.g., 'Purchase', 'StartTrial', 'Subscribe')
+    // https://developers.facebook.com/docs/marketing-api/conversions-api
+
+    // TODO: TikTok Events API
+    // Event name: event.tiktok (e.g., 'CompletePayment', 'Subscribe')
+    // https://business-api.tiktok.com/portal/docs?id=1771100865818625
+  } catch (e) {
+    assistant.error(`trackPayment failed: ${e.message}`, e);
+  }
+}
+
+/**
+ * Resolve which analytics event to fire based on transition + unified data
+ * Returns null if the transition doesn't warrant an analytics event
+ */
+function resolvePaymentEvent(category, transitionName, unified, config) {
+  if (category === 'subscription') {
+    return resolveSubscriptionEvent(transitionName, unified, config);
+  }
+
+  if (category === 'one-time') {
+    return resolveOneTimeEvent(transitionName, unified, config);
+  }
+
+  return null;
+}
+
+/**
+ * Map subscription transitions to analytics events
+ */
+function resolveSubscriptionEvent(transitionName, unified, config) {
+  const productId = unified.product?.id;
+  const productName = unified.product?.name;
+  const frequency = unified.payment?.frequency;
+  const isTrial = unified.trial?.claimed === true;
+  const resourceId = unified.payment?.resourceId;
+
+  // Resolve price from config
+  const product = config.payment?.products?.find(p => p.id === productId);
+  const price = product?.prices?.[frequency]?.amount || 0;
+
+  if (transitionName === 'new-subscription' && isTrial) {
+    return {
+      ga4: 'start_trial',
+      meta: 'StartTrial',
+      tiktok: 'Subscribe',
+      value: 0,
+      currency: config.payment?.currency || 'USD',
+      productId,
+      productName,
+      frequency,
+      isTrial: true,
+      isRecurring: false,
+      transactionId: resourceId,
+    };
+  }
+
+  if (transitionName === 'new-subscription') {
+    return {
+      ga4: 'purchase',
+      meta: 'Purchase',
+      tiktok: 'CompletePayment',
+      value: price,
+      currency: config.payment?.currency || 'USD',
+      productId,
+      productName,
+      frequency,
+      isTrial: false,
+      isRecurring: false,
+      transactionId: resourceId,
+    };
+  }
+
+  if (transitionName === 'payment-recovered') {
+    return {
+      ga4: 'purchase',
+      meta: 'Subscribe',
+      tiktok: 'Subscribe',
+      value: price,
+      currency: config.payment?.currency || 'USD',
+      productId,
+      productName,
+      frequency,
+      isTrial: false,
+      isRecurring: true,
+      transactionId: resourceId,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Map one-time transitions to analytics events
+ */
+function resolveOneTimeEvent(transitionName, unified, config) {
+  if (transitionName !== 'purchase-completed') {
+    return null;
+  }
+
+  const productId = unified.metadata?.productId || unified.raw?.metadata?.productId;
+  const product = config.payment?.products?.find(p => p.id === productId);
+  const price = product?.prices?.once?.amount || 0;
+
+  return {
+    ga4: 'purchase',
+    meta: 'Purchase',
+    tiktok: 'CompletePayment',
+    value: price,
+    currency: config.payment?.currency || 'USD',
+    productId: productId || 'unknown',
+    productName: product?.name || 'Unknown',
+    frequency: null,
+    isTrial: false,
+    isRecurring: false,
+    transactionId: unified.id,
+  };
+}