backend-manager 5.0.122 → 5.0.124

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

@@ -1,171 +1,295 @@
+const fetch = require('wonderful-fetch');
+
 /**
  * Payment analytics tracking
- * Fires server-side events for GA4, Meta Conversions API, and TikTok Events API
+ * Fires server-side events independently to GA4, Meta Conversions API, and TikTok Events API
+ *
+ * Two independent concerns:
+ *   1. Transition events (mutually exclusive, one per webhook):
+ *      new-subscription (no trial) → purchase
+ *      new-subscription (trial)    → start_trial
+ *      payment-recovered           → purchase (recurring)
+ *      purchase-completed          → purchase (one-time)
  *
- * 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
+ *   2. Payment events (fire whenever money changes hands, including renewals):
+ *      subscription renewal        → purchase (recurring)
  */
 
 /**
  * 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)
+ * Fires GA4, Meta, and TikTok independently with per-platform payloads
  */
-function trackPayment({ category, transitionName, unified, uid, processor, assistant }) {
+function trackPayment({ category, transitionName, eventType, unified, uid, processor, assistant }) {
   const Manager = assistant.Manager;
+  const config = Manager.config;
 
   try {
-    // Resolve the analytics event to fire based on transition
-    const event = resolvePaymentEvent(category, transitionName, unified, Manager.config);
+    // Resolve what kind of payment event this is
+    const resolved = resolvePaymentEvent(category, transitionName, eventType, unified);
 
-    if (!event) {
+    if (!resolved) {
+      assistant.log(`trackPayment: skipped — no trackable event (category=${category}, transition=${transitionName || 'null'}, eventType=${eventType})`);
       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,
-    });
+    const currency = config.payment?.currency || 'USD';
 
-    // TODO: Meta Conversions API
-    // Event name: event.meta (e.g., 'Purchase', 'StartTrial', 'Subscribe')
-    // https://developers.facebook.com/docs/marketing-api/conversions-api
+    assistant.log(`trackPayment: reason=${resolved.reason}, value=${resolved.value}, currency=${currency}, product=${resolved.productId}, uid=${uid}, processor=${processor}`);
 
-    // TODO: TikTok Events API
-    // Event name: event.tiktok (e.g., 'CompletePayment', 'Subscribe')
-    // https://business-api.tiktok.com/portal/docs?id=1771100865818625
+    // Fire each platform independently (non-blocking, errors isolated)
+    fireGA4({ resolved, currency, uid, processor, assistant, Manager });
+    fireMeta({ resolved, currency, uid, processor, assistant, config });
+    fireTikTok({ resolved, currency, uid, processor, assistant, config });
   } catch (e) {
     assistant.error(`trackPayment failed: ${e.message}`, e);
   }
 }
 
+// ---------------------------------------------------------------------------
+// Event resolution
+// ---------------------------------------------------------------------------
+
 /**
- * Resolve which analytics event to fire based on transition + unified data
- * Returns null if the transition doesn't warrant an analytics event
+ * Determine what kind of payment event occurred and extract common fields
+ * Returns null if nothing should be tracked
  */
-function resolvePaymentEvent(category, transitionName, unified, config) {
+function resolvePaymentEvent(category, transitionName, eventType, unified) {
+  const productId = unified.product?.id;
+  const productName = unified.product?.name;
+  const frequency = unified.payment?.frequency || null;
+  const isTrial = unified.trial?.claimed === true;
+  const resourceId = unified.payment?.resourceId;
+  const price = unified.payment?.price || 0;
+
+  const base = { productId, productName, frequency, resourceId, isTrial };
+
+  // --- Subscription transitions ---
   if (category === 'subscription') {
-    return resolveSubscriptionEvent(transitionName, unified, config);
+    if (transitionName === 'new-subscription' && isTrial) {
+      return { ...base, reason: 'trial-started', value: 0, isRecurring: false };
+    }
+
+    if (transitionName === 'new-subscription') {
+      return { ...base, reason: 'first-purchase', value: price, isRecurring: false };
+    }
+
+    if (transitionName === 'payment-recovered') {
+      return { ...base, reason: 'payment-recovered', value: price, isRecurring: true };
+    }
+
+    // No transition but a payment event fired (renewal)
+    if (!transitionName && isPaymentEvent(eventType) && price > 0) {
+      return { ...base, reason: 'renewal', value: price, isRecurring: true };
+    }
+
+    return null;
   }
 
+  // --- One-time transitions ---
   if (category === 'one-time') {
-    return resolveOneTimeEvent(transitionName, unified, config);
+    if (transitionName === 'purchase-completed') {
+      return { ...base, reason: 'one-time-purchase', value: price, isRecurring: false, productId: productId || 'unknown', productName: productName || 'Unknown' };
+    }
+
+    return null;
   }
 
   return null;
 }
 
 /**
- * Map subscription transitions to analytics events
+ * Check if a webhook event type represents a payment being made
  */
-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,
-    };
+function isPaymentEvent(eventType) {
+  if (!eventType) {
+    return false;
   }
 
-  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,
-    };
+  return [
+    // PayPal
+    'PAYMENT.SALE.COMPLETED',
+    // Stripe
+    'invoice.payment_succeeded',
+    'invoice.paid',
+  ].includes(eventType);
+}
+
+// ---------------------------------------------------------------------------
+// GA4 — Measurement Protocol
+// ---------------------------------------------------------------------------
+
+/**
+ * Fire GA4 event via Manager.Analytics (Measurement Protocol)
+ * https://developers.google.com/analytics/devguides/collection/protocol/ga4
+ */
+function fireGA4({ resolved, currency, uid, processor, assistant, Manager }) {
+  try {
+    // Map reason → GA4 event name
+    const eventName = resolved.reason === 'trial-started' ? 'start_trial' : 'purchase';
+
+    Manager.Analytics({ assistant, uuid: uid }).event(eventName, {
+      transaction_id: resolved.resourceId,
+      value: resolved.value,
+      currency: currency,
+      items: [{
+        item_id: resolved.productId,
+        item_name: resolved.productName,
+        price: resolved.value,
+        quantity: 1,
+      }],
+      payment_processor: processor,
+      payment_frequency: resolved.frequency,
+      is_trial: resolved.isTrial,
+      is_recurring: resolved.isRecurring,
+    });
+
+    assistant.log(`trackPayment [GA4]: event=${eventName}, value=${resolved.value}, product=${resolved.productId}, uid=${uid}`);
+  } catch (e) {
+    assistant.error(`trackPayment [GA4] failed: ${e.message}`, e);
   }
+}
+
+// ---------------------------------------------------------------------------
+// Meta — Conversions API
+// ---------------------------------------------------------------------------
+
+// Meta event name mapping
+const META_EVENTS = {
+  'trial-started': 'StartTrial',
+  'first-purchase': 'Purchase',
+  'payment-recovered': 'Subscribe',
+  'renewal': 'Subscribe',
+  'one-time-purchase': 'Purchase',
+};
+
+/**
+ * Fire Meta Conversions API event
+ * https://developers.facebook.com/docs/marketing-api/conversions-api
+ */
+function fireMeta({ resolved, currency, uid, processor, assistant, config }) {
+  try {
+    const pixelId = config.meta?.pixelId;
+    const accessToken = process.env.META_ACCESS_TOKEN;
 
-  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,
+    if (!pixelId || !accessToken) {
+      return;
+    }
+
+    const eventName = META_EVENTS[resolved.reason];
+
+    if (!eventName) {
+      return;
+    }
+
+    const payload = {
+      data: [{
+        event_name: eventName,
+        event_time: Math.floor(Date.now() / 1000),
+        action_source: 'website',
+        user_data: {
+          external_id: uid,
+        },
+        custom_data: {
+          value: resolved.value,
+          currency: currency,
+          content_ids: [resolved.productId],
+          content_name: resolved.productName,
+          content_type: 'product',
+          payment_processor: processor,
+          is_recurring: resolved.isRecurring,
+        },
+      }],
     };
-  }
 
-  return null;
+    fetch(`https://graph.facebook.com/v21.0/${pixelId}/events?access_token=${accessToken}`, {
+      method: 'post',
+      response: 'json',
+      body: payload,
+      timeout: 30000,
+      tries: 2,
+    })
+    .then(() => {
+      assistant.log(`trackPayment [Meta]: event=${eventName}, value=${resolved.value}, product=${resolved.productId}, uid=${uid}`);
+    })
+    .catch((e) => {
+      assistant.error(`trackPayment [Meta] failed: ${e.message}`, e);
+    });
+  } catch (e) {
+    assistant.error(`trackPayment [Meta] failed: ${e.message}`, e);
+  }
 }
 
+// ---------------------------------------------------------------------------
+// TikTok — Events API
+// ---------------------------------------------------------------------------
+
+// TikTok event name mapping
+const TIKTOK_EVENTS = {
+  'trial-started': 'Subscribe',
+  'first-purchase': 'CompletePayment',
+  'payment-recovered': 'Subscribe',
+  'renewal': 'Subscribe',
+  'one-time-purchase': 'CompletePayment',
+};
+
 /**
- * Map one-time transitions to analytics events
+ * Fire TikTok Events API event
+ * https://business-api.tiktok.com/portal/docs?id=1771100865818625
  */
-function resolveOneTimeEvent(transitionName, unified, config) {
-  if (transitionName !== 'purchase-completed') {
-    return null;
-  }
+function fireTikTok({ resolved, currency, uid, processor, assistant, config }) {
+  try {
+    const pixelCode = config.tiktok?.pixelCode;
+    const accessToken = process.env.TIKTOK_ACCESS_TOKEN;
 
-  const productId = unified.product?.id;
-  const productName = unified.product?.name;
-  const price = unified.payment?.price || 0;
-  const resourceId = unified.payment?.resourceId;
+    if (!pixelCode || !accessToken) {
+      return;
+    }
+
+    const eventName = TIKTOK_EVENTS[resolved.reason];
+
+    if (!eventName) {
+      return;
+    }
 
-  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,
-  };
+    const payload = {
+      pixel_code: pixelCode,
+      event: eventName,
+      event_id: `${uid}-${Date.now()}`,
+      timestamp: new Date().toISOString(),
+      context: {
+        user: {
+          external_id: uid,
+        },
+      },
+      properties: {
+        value: resolved.value,
+        currency: currency,
+        content_id: resolved.productId,
+        content_name: resolved.productName,
+        content_type: 'product',
+        description: `${resolved.reason} via ${processor}`,
+      },
+    };
+
+    fetch('https://business-api.tiktok.com/open_api/v1.3/event/track/', {
+      method: 'post',
+      response: 'json',
+      headers: {
+        'Access-Token': accessToken,
+      },
+      body: { data: [payload] },
+      timeout: 30000,
+      tries: 2,
+    })
+    .then(() => {
+      assistant.log(`trackPayment [TikTok]: event=${eventName}, value=${resolved.value}, product=${resolved.productId}, uid=${uid}`);
+    })
+    .catch((e) => {
+      assistant.error(`trackPayment [TikTok] failed: ${e.message}`, e);
+    });
+  } catch (e) {
+    assistant.error(`trackPayment [TikTok] failed: ${e.message}`, e);
+  }
 }
 
 module.exports = { trackPayment };

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

@@ -194,6 +194,13 @@ async function processPaymentEvent({ category, library, resource, resourceType,
 
   assistant.log(`Unified ${category}: product=${unified.product.id}, status=${unified.status}`, unified);
 
+  // Read checkout context from payments-intents (attribution, discount, supplemental)
+  let intentData = {};
+  if (orderId) {
+    const intentDoc = await admin.firestore().doc(`payments-intents/${orderId}`).get();
+    intentData = intentDoc.exists ? intentDoc.data() : {};
+  }
+
   // Build the order object (single source of truth for handlers + Firestore)
   const order = {
     id: orderId,
@@ -203,6 +210,9 @@ async function processPaymentEvent({ category, library, resource, resourceType,
     processor: processor,
     resourceId: resourceId,
     unified: unified,
+    attribution: intentData.attribution || {},
+    discount: intentData.discount || null,
+    supplemental: intentData.supplemental || {},
     metadata: {
       created: {
         timestamp: now,
@@ -243,8 +253,9 @@ async function processPaymentEvent({ category, library, resource, resourceType,
   }
 
   // Track payment analytics (non-blocking)
-  if (transitionName && shouldRunHandlers) {
-    trackPayment({ category, transitionName, unified, uid, processor, assistant });
+  // Fires independently of transitions — renewals have no transition but still need tracking
+  if (shouldRunHandlers) {
+    trackPayment({ category, transitionName, eventType, unified, uid, processor, assistant });
   }
 
   // Write unified subscription to user doc (subscriptions only)
@@ -284,6 +295,25 @@ async function processPaymentEvent({ category, library, resource, resourceType,
     assistant.log(`Updated payments-intents/${orderId}: status=completed`);
   }
 
+  // Mark abandoned cart as completed (non-blocking, fire-and-forget)
+  const { COLLECTION } = require('../../../libraries/abandoned-cart-config.js');
+  admin.firestore().doc(`${COLLECTION}/${uid}`).set({
+    status: 'completed',
+    metadata: {
+      updated: {
+        timestamp: now,
+        timestampUNIX: nowUNIX,
+      },
+    },
+  }, { merge: true })
+    .then(() => assistant.log(`Updated ${COLLECTION}/${uid}: status=completed`))
+    .catch((e) => {
+      // Ignore not-found — cart may not exist for this user
+      if (e.code !== 5) {
+        assistant.error(`Failed to update ${COLLECTION}/${uid}: ${e.message}`);
+      }
+    });
+
   return transitionName;
 }
 

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

@@ -1,6 +1,7 @@
 const fetch = require('wonderful-fetch');
 const path = require('path');
 const dns = require('dns').promises;
+const recaptcha = require(path.join(__dirname, '..', '..', '..', '..', '..', 'libraries', 'recaptcha.js'));
 
 // Load disposable domains list
 const DISPOSABLE_DOMAINS = require(path.join(__dirname, '..', '..', '..', '..', '..', 'libraries', 'disposable-domains.json'));
@@ -49,15 +50,17 @@ Module.prototype.main = function () {
 
     // Public access protection
     if (!isAdmin) {
-      // Verify reCAPTCHA
-      const recaptchaToken = requestPayload['g-recaptcha-response'];
-      if (!recaptchaToken) {
-        return reject(assistant.errorify('reCAPTCHA token required', { code: 400 }));
-      }
+      // Verify reCAPTCHA (skip during automated tests)
+      if (!assistant.isTesting()) {
+        const recaptchaToken = requestPayload['g-recaptcha-response'];
+        if (!recaptchaToken) {
+          return reject(assistant.errorify('Request could not be verified', { code: 403 }));
+        }
 
-      const recaptchaValid = await verifyRecaptcha(recaptchaToken);
-      if (!recaptchaValid) {
-        return reject(assistant.errorify('reCAPTCHA verification failed', { code: 400 }));
+        const recaptchaValid = await recaptcha.verify(recaptchaToken);
+        if (!recaptchaValid) {
+          return reject(assistant.errorify('Request could not be verified', { code: 403 }));
+        }
       }
 
       // Check rate limit via Usage API
@@ -174,32 +177,6 @@ Module.prototype.main = function () {
   });
 };
 
-/**
- * Verify Google reCAPTCHA (invisible) token
- */
-async function verifyRecaptcha(token) {
-  if (!process.env.RECAPTCHA_SECRET_KEY) {
-    // Skip verification if no secret configured
-    return true;
-  }
-
-  try {
-    // reCAPTCHA requires form-urlencoded, not JSON
-    const data = await fetch('https://www.google.com/recaptcha/api/siteverify', {
-      method: 'post',
-      response: 'json',
-      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-      body: `secret=${process.env.RECAPTCHA_SECRET_KEY}&response=${token}`,
-    });
-
-    // For v3 invisible reCAPTCHA, check score (0.5+ is typically human)
-    return data.success && (data.score === undefined || data.score >= 0.5);
-  } catch (e) {
-    console.error('reCAPTCHA verification error:', e);
-    return false;
-  }
-}
-
 /**
  * Validate email with ZeroBounce API
  */

package/src/manager/helpers/analytics.js

@@ -161,8 +161,8 @@ function Analytics(Manager, options) {
   };
 
   // Set id and secret
-  self.analyticsId = self?.Manager?.config?.google_analytics?.id;
-  self.analyticsSecret = self?.Manager?.config?.google_analytics?.secret;
+  self.analyticsId = self?.Manager?.config?.googleAnalytics?.id;
+  self.analyticsSecret = self?.Manager?.config?.googleAnalytics?.secret;
 
   // Check if we have the required properties
   if (!self.analyticsId) {