backend-manager 5.0.89 → 5.0.92

package/src/cli/index.js

@@ -1,6 +1,17 @@
+const os = require('os');
+const path = require('path');
 const argv = require('yargs').argv;
 const _ = require('lodash');
 
+// Abort if running from ~/node_modules (accidental home directory install)
+const _homeDir = os.homedir();
+if (__dirname.startsWith(path.join(_homeDir, 'node_modules'))) {
+  console.error(`\nERROR: BEM is running from ~/node_modules (home directory install).`);
+  console.error(`This shadows the local project copy. Fix:`);
+  console.error(`  rm -rf ~/node_modules ~/package.json ~/package-lock.json\n`);
+  process.exit(1);
+}
+
 // Import commands
 const VersionCommand = require('./commands/version');
 const ClearCommand = require('./commands/clear');
@@ -10,7 +21,7 @@ const InstallCommand = require('./commands/install');
 const ServeCommand = require('./commands/serve');
 const DeployCommand = require('./commands/deploy');
 const TestCommand = require('./commands/test');
-const EmulatorsCommand = require('./commands/emulators');
+const EmulatorCommand = require('./commands/emulator');
 const CleanCommand = require('./commands/clean');
 const IndexesCommand = require('./commands/indexes');
 const WatchCommand = require('./commands/watch');
@@ -95,9 +106,9 @@ Main.prototype.process = async function (args) {
     return await cmd.execute();
   }
 
-  // Emulators (keep-alive mode)
-  if (self.options['emulators'] || self.options['emulator']) {
-    const cmd = new EmulatorsCommand(self);
+  // Emulator (keep-alive mode)
+  if (self.options['emulator'] || self.options['emulators']) {
+    const cmd = new EmulatorCommand(self);
     return await cmd.execute();
   }
 

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

@@ -1,5 +1,3 @@
-const fetch = require('wonderful-fetch');
-const moment = require('moment');
 const { FieldValue } = require('firebase-admin/firestore');
 
 const MAX_RETRIES = 3;
@@ -15,7 +13,9 @@ const RETRY_DELAY_MS = 1000;
  * - Checks if user doc already exists (auth.uid) → skips if exists (handles test accounts, provider linking)
  * - Batch writes user doc + increment count atomically
  * - Retries up to 3 times with exponential backoff on failure
- * - Sends analytics event (non-critical, no retry)
+ *
+ * Non-critical work (name inference, welcome emails, marketing contact) is handled
+ * by the user/signup endpoint, which the frontend calls after account creation.
  */
 module.exports = async ({ Manager, assistant, user, context, libraries }) => {
   const startTime = Date.now();
@@ -71,42 +71,13 @@ module.exports = async ({ Manager, assistant, user, context, libraries }) => {
       await batch.commit();
     }, MAX_RETRIES, RETRY_DELAY_MS);
 
-    assistant.log(`onCreate: Successfully created user doc for ${user.uid}`);
+    assistant.log(`onCreate: Successfully created user doc for ${user.uid} (${Date.now() - startTime}ms)`);
   } catch (error) {
     assistant.error(`onCreate: Failed to create user doc after ${MAX_RETRIES} retries:`, error);
 
     // Don't reject - the user was already created in Auth
-    // The user:sign-up endpoint will handle creating the doc if it's missing
-    return;
-  }
-
-  // Send emails in dev/production, or in test mode if TEST_EXTENDED_MODE=true
-  // Note: Must be passed to the emulator
-  const shouldSendEmails = !assistant.isTesting() || process.env.TEST_EXTENDED_MODE;
-
-  if (!shouldSendEmails) {
-    assistant.log(`onCreate: Skipping emails/SendGrid (BEM_TESTING=true, TEST_EXTENDED_MODE not set)`);
-  } else {
-    assistant.log(`onCreate: Sending emails/adding to SendGrid for ${user.uid}`);
-
-    // Add to marketing lists (SendGrid + Beehiiv) via centralized endpoint
-    fetch(`${Manager.project.apiUrl}/backend-manager/marketing/contact`, {
-      method: 'POST',
-      response: 'json',
-      body: {
-        backendManagerKey: process.env.BACKEND_MANAGER_KEY,
-        email: user.email,
-        source: 'auth:on-create',
-      },
-    }).catch(e => assistant.error('onCreate: add-marketing-contact failed:', e));
-
-    // Send welcome emails (non-blocking, don't fail on error)
-    sendWelcomeEmail(Manager, assistant, user).catch(e => assistant.error('onCreate: sendWelcomeEmail failed:', e));
-    sendCheckupEmail(Manager, assistant, user).catch(e => assistant.error('onCreate: sendCheckupEmail failed:', e));
-    sendFeedbackEmail(Manager, assistant, user).catch(e => assistant.error('onCreate: sendFeedbackEmail failed:', e));
+    // The user/signup endpoint will handle creating the doc if it's missing
   }
-
-  assistant.log(`onCreate: Completed for ${user.uid} (${Date.now() - startTime}ms)`);
 };
 
 /**
@@ -133,127 +104,3 @@ async function retryBatchWrite(assistant, fn, maxRetries, delayMs) {
 
   throw lastError; // All retries failed
 }
-
-/**
- * Send welcome email (immediate)
- */
-function sendWelcomeEmail(Manager, assistant, user) {
-  return fetch(`${Manager.project.apiUrl}/backend-manager/admin/email`, {
-    method: 'POST',
-    response: 'json',
-    body: {
-      backendManagerKey: process.env.BACKEND_MANAGER_KEY,
-      to: [{ email: user.email }],
-      categories: ['account/welcome'],
-      subject: `Welcome to ${Manager.config.brand.name}!`,
-      template: 'd-b7f8da3c98ad49a2ad1e187f3a67b546',
-      group: 25928,
-      copy: false,
-      ensureUnique: true,
-      data: {
-        email: {
-          preview: `Welcome aboard! I'm Ian, the CEO and founder of ${Manager.config.brand.name}. I'm here to ensure your journey with us gets off to a great start.`,
-        },
-        body: {
-          title: `Welcome to ${Manager.config.brand.name}!`,
-          message: `
-            Welcome aboard!
-            <br><br>
-            I'm Ian, the founder and CEO of <strong>${Manager.config.brand.name}</strong>, and I'm thrilled to have you with us.
-            Your journey begins today, and we are committed to supporting you every step of the way.
-            <br><br>
-            We are dedicated to ensuring your experience is exceptional.
-            Feel free to reply directly to this email with any questions you may have.
-            <br><br>
-            Thank you for choosing <strong>${Manager.config.brand.name}</strong>. Here's to new beginnings!
-          `,
-        },
-        signoff: {
-          type: 'personal',
-          name: 'Ian Wiedenman, CEO',
-          url: `https://ianwiedenman.com?utm_source=welcome-email&utm_medium=email&utm_campaign=${Manager.config.app.id}`,
-          urlText: '@ianwieds',
-        },
-      },
-    },
-  })
-  .then((json) => {
-    assistant.log('sendWelcomeEmail(): Success', json);
-    return json;
-  });
-}
-
-/**
- * Send checkup email (7 days after signup)
- */
-function sendCheckupEmail(Manager, assistant, user) {
-  return fetch(`${Manager.project.apiUrl}/backend-manager/admin/email`, {
-    method: 'POST',
-    response: 'json',
-    body: {
-      backendManagerKey: process.env.BACKEND_MANAGER_KEY,
-      to: [{ email: user.email }],
-      categories: ['account/checkup'],
-      subject: `How's your experience with ${Manager.config.brand.name}?`,
-      template: 'd-b7f8da3c98ad49a2ad1e187f3a67b546',
-      group: 25928,
-      copy: false,
-      ensureUnique: true,
-      sendAt: moment().add(7, 'days').unix(),
-      data: {
-        email: {
-          preview: `Checking in from ${Manager.config.brand.name} to see how things are going. Let us know if you have any questions or feedback!`,
-        },
-        body: {
-          title: `How's everything going?`,
-          message: `
-            Hi there,
-            <br><br>
-            It's Ian again from <strong>${Manager.config.brand.name}</strong>. Just checking in to see how things are going for you.
-            <br><br>
-            Have you had a chance to explore all our features? Any questions or feedback for us?
-            <br><br>
-            We're always here to help, so don't hesitate to reach out. Just reply to this email and we'll get back to you as soon as possible.
-            <br><br>
-            Thank you for choosing <strong>${Manager.config.brand.name}</strong>. Here's to new beginnings!
-          `,
-        },
-        signoff: {
-          type: 'personal',
-          name: 'Ian Wiedenman, CEO',
-          url: `https://ianwiedenman.com?utm_source=checkup-email&utm_medium=email&utm_campaign=${Manager.config.app.id}`,
-          urlText: '@ianwieds',
-        },
-      },
-    },
-  })
-  .then((json) => {
-    assistant.log('sendCheckupEmail(): Success', json);
-    return json;
-  });
-}
-
-/**
- * Send feedback email (14 days after signup)
- */
-function sendFeedbackEmail(Manager, assistant, user) {
-  return fetch(`${Manager.project.apiUrl}/backend-manager/admin/email`, {
-    method: 'POST',
-    response: 'json',
-    body: {
-      backendManagerKey: process.env.BACKEND_MANAGER_KEY,
-      to: [{ email: user.email }],
-      categories: ['engagement/feedback'],
-      subject: `Want to share your feedback about ${Manager.config.brand.name}?`,
-      template: 'd-c1522214c67b47058669acc5a81ed663',
-      group: 25928,
-      copy: false,
-      ensureUnique: true,
-      sendAt: moment().add(14, 'days').unix(),
-    },
-  })
-  .then((json) => {
-    assistant.log('sendFeedbackEmail(): Success', json);
-    return json;
-  });
-}

package/src/manager/events/firestore/payments-webhooks/analytics.js

@@ -0,0 +1,171 @@
+/**
+ * Payment analytics tracking
+ * 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
+ */
+
+/**
+ * Track payment events across analytics platforms (non-blocking)
+ *
+ * @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 (Manager derived via assistant.Manager)
+ */
+function trackPayment({ category, transitionName, unified, uid, processor, assistant }) {
+  const Manager = 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;
+  const price = unified.payment?.price || 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.product?.id;
+  const productName = unified.product?.name;
+  const price = unified.payment?.price || 0;
+  const resourceId = unified.payment?.resourceId;
+
+  return {
+    ga4: 'purchase',
+    meta: 'Purchase',
+    tiktok: 'CompletePayment',
+    value: price,
+    currency: config.payment?.currency || 'USD',
+    productId: productId || 'unknown',
+    productName: productName || 'Unknown',
+    frequency: null,
+    isTrial: false,
+    isRecurring: false,
+    transactionId: resourceId,
+  };
+}
+
+module.exports = { trackPayment };