backend-manager 5.0.86 → 5.0.87

package/src/manager/events/firestore/payments-webhooks/transitions/index.js

@@ -0,0 +1,148 @@
+/**
+ * Payment transition detection and dispatch
+ *
+ * Compares subscription state before and after a webhook to detect meaningful
+ * transitions (e.g., new subscription, payment failed, cancellation).
+ * Dispatches to individual handler files for each transition type.
+ */
+const path = require('path');
+
+/**
+ * Detect what transition occurred based on category and before/after state
+ *
+ * @param {string} category - 'subscription' or 'one-time'
+ * @param {object|null} before - Previous state (null for new users / one-time)
+ * @param {object} after - New unified state about to be written
+ * @param {string} eventType - Original webhook event type (used for one-time detection)
+ * @returns {string|null} Transition name or null if no meaningful change
+ */
+function detectTransition(category, before, after, eventType) {
+  if (category === 'subscription') {
+    return detectSubscriptionTransition(before, after);
+  }
+
+  if (category === 'one-time') {
+    return detectOneTimeTransition(eventType);
+  }
+
+  return null;
+}
+
+/**
+ * Detect subscription state transitions by comparing before and after
+ *
+ * Checks are ordered by specificity — most specific first to avoid misclassification.
+ *
+ * @param {object|null} before - Previous users/{uid}.subscription (null/undefined for new users)
+ * @param {object} after - New unified subscription
+ * @returns {string|null} Transition name
+ */
+function detectSubscriptionTransition(before, after) {
+  if (!after) {
+    return null;
+  }
+
+  const beforeStatus = before?.status;
+  const afterStatus = after.status;
+
+  // 1. new-subscription: basic/null → active paid (handler checks after.trial.claimed for trial info)
+  if (isBasicOrNull(before) && afterStatus === 'active' && isPaid(after)) {
+    return 'new-subscription';
+  }
+
+  // 2. payment-failed: active → suspended
+  if (beforeStatus === 'active' && afterStatus === 'suspended') {
+    return 'payment-failed';
+  }
+
+  // 3. payment-recovered: suspended → active
+  if (beforeStatus === 'suspended' && afterStatus === 'active') {
+    return 'payment-recovered';
+  }
+
+  // 4. cancellation-requested: pending flips from false → true while still active
+  if (afterStatus === 'active' && !before?.cancellation?.pending && after.cancellation?.pending) {
+    return 'cancellation-requested';
+  }
+
+  // 5. subscription-cancelled: any non-cancelled → cancelled
+  if (beforeStatus !== 'cancelled' && afterStatus === 'cancelled') {
+    return 'subscription-cancelled';
+  }
+
+  // 6. plan-changed: both active, both paid, different product
+  if (
+    beforeStatus === 'active'
+    && afterStatus === 'active'
+    && isPaid(before)
+    && isPaid(after)
+    && before.product.id !== after.product.id
+  ) {
+    return 'plan-changed';
+  }
+
+  return null;
+}
+
+/**
+ * Detect one-time payment transitions from event type
+ * Simpler than subscriptions — no before/after comparison needed
+ *
+ * @param {string} eventType - Webhook event type
+ * @returns {string|null} Transition name
+ */
+function detectOneTimeTransition(eventType) {
+  if (eventType === 'checkout.session.completed') {
+    return 'purchase-completed';
+  }
+
+  if (eventType === 'invoice.payment_failed') {
+    return 'purchase-failed';
+  }
+
+  return null;
+}
+
+/**
+ * Dispatch a transition handler (fire-and-forget)
+ *
+ * @param {string} transitionName - e.g., 'new-subscription', 'payment-failed'
+ * @param {string} category - 'subscription' or 'one-time'
+ * @param {object} context - Full context passed to the handler
+ */
+function dispatch(transitionName, category, context) {
+  const { assistant } = context;
+
+  try {
+    const handlerPath = path.join(__dirname, category, `${transitionName}.js`);
+    const handler = require(handlerPath);
+
+    // Fire-and-forget — don't block the main webhook processing
+    Promise.resolve(handler(context)).catch((e) => {
+      assistant.error(`Transition handler [${category}/${transitionName}] failed: ${e.message}`, e);
+    });
+  } catch (e) {
+    // Handler file doesn't exist or can't be loaded — log but don't fail
+    assistant.error(`Transition handler [${category}/${transitionName}] not found: ${e.message}`);
+  }
+}
+
+// ─── Helpers ───
+
+function isBasicOrNull(sub) {
+  return !sub || !sub.product || sub.product.id === 'basic';
+}
+
+function isPaid(sub) {
+  return sub && sub.product && sub.product.id !== 'basic';
+}
+
+module.exports = {
+  detectTransition,
+  detectSubscriptionTransition,
+  detectOneTimeTransition,
+  dispatch,
+  // Exported for testing
+  isBasicOrNull,
+  isPaid,
+};

package/src/manager/events/firestore/payments-webhooks/transitions/one-time/purchase-completed.js

@@ -0,0 +1,16 @@
+/**
+ * Transition: purchase-completed
+ * Triggered when a one-time payment checkout completes (checkout.session.completed with mode=payment)
+ *
+ * Use cases:
+ * - Send purchase receipt/confirmation email
+ * - Deliver digital goods or credits
+ * - Fire analytics event for purchase
+ */
+module.exports = async function ({ before, after, uid, userDoc, admin, assistant, Manager, eventType, eventId }) {
+  assistant.log(`Transition [one-time/purchase-completed]: uid=${uid}, resourceId=${after.id}`);
+
+  // TODO: Send purchase confirmation email
+  // TODO: Deliver digital goods
+  // TODO: Fire analytics event
+};

package/src/manager/events/firestore/payments-webhooks/transitions/one-time/purchase-failed.js

@@ -0,0 +1,15 @@
+/**
+ * Transition: purchase-failed
+ * Triggered when a one-time payment fails (invoice.payment_failed with billing_reason=manual)
+ *
+ * Use cases:
+ * - Send payment failure notification
+ * - Include retry link or alternative payment method
+ * - Fire analytics event
+ */
+module.exports = async function ({ before, after, uid, userDoc, admin, assistant, Manager, eventType, eventId }) {
+  assistant.log(`Transition [one-time/purchase-failed]: uid=${uid}, resourceId=${after.id}`);
+
+  // TODO: Send payment failure email with retry link
+  // TODO: Fire analytics event
+};

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/cancellation-requested.js

@@ -0,0 +1,15 @@
+/**
+ * Transition: cancellation-requested
+ * Triggered when a user requests cancellation at period end (cancellation.pending flips to true)
+ *
+ * Use cases:
+ * - Send cancellation confirmation email with period end date
+ * - Include win-back offer or feedback survey link
+ * - Fire analytics event for churn intent
+ */
+module.exports = async function ({ before, after, uid, userDoc, admin, assistant, Manager, eventType, eventId }) {
+  assistant.log(`Transition [subscription/cancellation-requested]: uid=${uid}, product=${after.product.id}, cancelDate=${after.cancellation.date.timestamp}`);
+
+  // TODO: Send cancellation confirmation email with end date
+  // TODO: Fire analytics event
+};

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/new-subscription.js

@@ -0,0 +1,18 @@
+/**
+ * Transition: new-subscription
+ * Triggered when a user subscribes for the first time (basic/null → active paid)
+ * Check after.trial.claimed to determine if this is a trial subscription
+ *
+ * Use cases:
+ * - Send order confirmation email with plan details (include trial info if applicable)
+ * - Fire analytics event for new subscriber
+ * - Update marketing lists
+ */
+module.exports = async function ({ before, after, uid, userDoc, admin, assistant, Manager, eventType, eventId }) {
+  const isTrial = after.trial?.claimed === true;
+
+  assistant.log(`Transition [subscription/new-subscription]: uid=${uid}, product=${after.product.id}, frequency=${after.payment.frequency}, trial=${isTrial}`);
+
+  // TODO: Send order confirmation email (modify content if isTrial)
+  // TODO: Fire analytics event
+};

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/payment-failed.js

@@ -0,0 +1,15 @@
+/**
+ * Transition: payment-failed
+ * Triggered when a subscription payment fails (active → suspended)
+ *
+ * Use cases:
+ * - Send payment failure notification email
+ * - Include link to update payment method
+ * - Fire analytics event for churn risk
+ */
+module.exports = async function ({ before, after, uid, userDoc, admin, assistant, Manager, eventType, eventId }) {
+  assistant.log(`Transition [subscription/payment-failed]: uid=${uid}, product=${after.product.id}, previousStatus=${before?.status}`);
+
+  // TODO: Send payment failure email with update-payment link
+  // TODO: Fire analytics event
+};

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/payment-recovered.js

@@ -0,0 +1,14 @@
+/**
+ * Transition: payment-recovered
+ * Triggered when a suspended subscription is recovered (suspended → active)
+ *
+ * Use cases:
+ * - Send payment recovered confirmation email
+ * - Fire analytics event for recovered subscriber
+ */
+module.exports = async function ({ before, after, uid, userDoc, admin, assistant, Manager, eventType, eventId }) {
+  assistant.log(`Transition [subscription/payment-recovered]: uid=${uid}, product=${after.product.id}`);
+
+  // TODO: Send payment recovered email
+  // TODO: Fire analytics event
+};

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/plan-changed.js

@@ -0,0 +1,16 @@
+/**
+ * Transition: plan-changed
+ * Triggered when a user upgrades or downgrades their plan (product A → product B, both active + paid)
+ *
+ * Use cases:
+ * - Send plan change confirmation email
+ * - Include new plan details and what changed
+ * - Fire analytics event for upgrade/downgrade
+ */
+module.exports = async function ({ before, after, uid, userDoc, admin, assistant, Manager, eventType, eventId }) {
+  const direction = after.product.id > before.product.id ? 'upgrade' : 'downgrade';
+  assistant.log(`Transition [subscription/plan-changed]: uid=${uid}, ${before.product.id} → ${after.product.id} (${direction})`);
+
+  // TODO: Send plan change email with new plan details
+  // TODO: Fire analytics event
+};

package/src/manager/events/firestore/payments-webhooks/transitions/subscription/subscription-cancelled.js

@@ -0,0 +1,16 @@
+/**
+ * Transition: subscription-cancelled
+ * Triggered when a subscription is fully cancelled (any non-cancelled → cancelled)
+ *
+ * Use cases:
+ * - Send final cancellation email
+ * - Include reactivation link or win-back offer
+ * - Fire analytics event for churned subscriber
+ * - Clean up any subscription-specific resources
+ */
+module.exports = async function ({ before, after, uid, userDoc, admin, assistant, Manager, eventType, eventId }) {
+  assistant.log(`Transition [subscription/subscription-cancelled]: uid=${uid}, previousProduct=${before?.product?.id}, previousStatus=${before?.status}`);
+
+  // TODO: Send cancellation email with reactivation link
+  // TODO: Fire analytics event
+};

package/src/manager/index.js

@@ -709,6 +709,14 @@ Manager.prototype.debug = function () {
 // Setup functions
 Manager.prototype.setupFunctions = function (exporter, options) {
   const self = this;
+  const resourceZone = options.resourceZone;
+
+  // Helper to create a function builder with region + runtime options
+  function fn(runtimeOptions) {
+    return self.libraries.functions
+      .runWith(runtimeOptions)
+      .region(resourceZone);
+  }
 
   // Log
   if (options.log) {
@@ -717,8 +725,7 @@ Manager.prototype.setupFunctions = function (exporter, options) {
 
   // Setup functions
   exporter.bm_api =
-  self.libraries.functions
-  .runWith({memory: '256MB', timeoutSeconds: 60 * 5})
+  fn({memory: '256MB', timeoutSeconds: 60 * 5})
   .https.onRequest(async (req, res) => {
     const route = self.BemRouter(req, res).resolve();
 
@@ -734,8 +741,7 @@ Manager.prototype.setupFunctions = function (exporter, options) {
   // Setup legacy functions
   if (options.setupFunctionsLegacy) {
     exporter.bm_signUpHandler =
-    self.libraries.functions
-    .runWith({memory: '256MB', timeoutSeconds: 60})
+    fn({memory: '256MB', timeoutSeconds: 60})
     .https.onRequest(async (req, res) => {
       const Module = require(`${_legacy}/actions/sign-up-handler.js`);
       Module.init(self, { req: req, res: res, });
@@ -750,8 +756,7 @@ Manager.prototype.setupFunctions = function (exporter, options) {
 
     // Admin
     exporter.bm_createPost =
-    self.libraries.functions
-    .runWith({memory: '256MB', timeoutSeconds: 60})
+    fn({memory: '256MB', timeoutSeconds: 60})
     .https.onRequest(async (req, res) => {
       const Module = require(`${_legacy}/admin/create-post.js`);
       Module.init(self, { req: req, res: res, });
@@ -765,8 +770,7 @@ Manager.prototype.setupFunctions = function (exporter, options) {
     });
 
     exporter.bm_firestoreWrite =
-    self.libraries.functions
-    .runWith({memory: '256MB', timeoutSeconds: 60})
+    fn({memory: '256MB', timeoutSeconds: 60})
     .https.onRequest(async (req, res) => {
       const Module = require(`${_legacy}/admin/firestore-write.js`);
       Module.init(self, { req: req, res: res, });
@@ -780,8 +784,7 @@ Manager.prototype.setupFunctions = function (exporter, options) {
     });
 
     exporter.bm_getStats =
-    self.libraries.functions
-    .runWith({memory: '256MB', timeoutSeconds: 420})
+    fn({memory: '256MB', timeoutSeconds: 420})
     .https.onRequest(async (req, res) => {
       const Module = require(`${_legacy}/admin/get-stats.js`);
       Module.init(self, { req: req, res: res, });
@@ -795,8 +798,7 @@ Manager.prototype.setupFunctions = function (exporter, options) {
     });
 
     exporter.bm_sendNotification =
-    self.libraries.functions
-    .runWith({memory: '1GB', timeoutSeconds: 420})
+    fn({memory: '1GB', timeoutSeconds: 420})
     .https.onRequest(async (req, res) => {
       const Module = require(`${_legacy}/admin/send-notification.js`);
       Module.init(self, { req: req, res: res, });
@@ -810,8 +812,7 @@ Manager.prototype.setupFunctions = function (exporter, options) {
     });
 
     exporter.bm_query =
-    self.libraries.functions
-    .runWith({memory: '256MB', timeoutSeconds: 60})
+    fn({memory: '256MB', timeoutSeconds: 60})
     .https.onRequest(async (req, res) => {
       const Module = require(`${_legacy}/admin/query.js`);
       Module.init(self, { req: req, res: res, });
@@ -825,8 +826,7 @@ Manager.prototype.setupFunctions = function (exporter, options) {
     });
 
     exporter.bm_createPostHandler =
-    self.libraries.functions
-    .runWith({memory: '256MB', timeoutSeconds: 60})
+    fn({memory: '256MB', timeoutSeconds: 60})
     .https.onRequest(async (req, res) => {
       const Module = require(`${_legacy}/actions/create-post-handler.js`);
       Module.init(self, { req: req, res: res, });
@@ -840,8 +840,7 @@ Manager.prototype.setupFunctions = function (exporter, options) {
     });
 
     exporter.bm_generateUuid =
-    self.libraries.functions
-    .runWith({memory: '256MB', timeoutSeconds: 60})
+    fn({memory: '256MB', timeoutSeconds: 60})
     .https.onRequest(async (req, res) => {
       const Module = require(`${_legacy}/actions/generate-uuid.js`);
       Module.init(self, { req: req, res: res, });
@@ -856,8 +855,7 @@ Manager.prototype.setupFunctions = function (exporter, options) {
 
     // Test
     exporter.bm_test_authenticate =
-    self.libraries.functions
-    .runWith({memory: '256MB', timeoutSeconds: 60})
+    fn({memory: '256MB', timeoutSeconds: 60})
     .https.onRequest(async (req, res) => {
       const Module = require(`${_legacy}/test/authenticate.js`);
       Module.init(self, { req: req, res: res, });
@@ -871,8 +869,7 @@ Manager.prototype.setupFunctions = function (exporter, options) {
     });
 
     exporter.bm_test_webhook =
-    self.libraries.functions
-    .runWith({memory: '256MB', timeoutSeconds: 60})
+    fn({memory: '256MB', timeoutSeconds: 60})
     .https.onRequest(async (req, res) => {
       const Module = require(`${_legacy}/test/webhook.js`);
       Module.init(self, { req: req, res: res, });
@@ -889,47 +886,40 @@ Manager.prototype.setupFunctions = function (exporter, options) {
   // Setup identity functions
   if (options.setupFunctionsIdentity) {
     exporter.bm_authBeforeCreate =
-    self.libraries.functions
-    .runWith({memory: '256MB', timeoutSeconds: 60})
+    fn({memory: '256MB', timeoutSeconds: 60})
     .auth.user()
     .beforeCreate((user, context) => self.EventMiddleware({ user, context }).run(`${events}/auth/before-create.js`));
 
     exporter.bm_authBeforeSignIn =
-    self.libraries.functions
-    .runWith({memory: '256MB', timeoutSeconds: 60})
+    fn({memory: '256MB', timeoutSeconds: 60})
     .auth.user()
     .beforeSignIn((user, context) => self.EventMiddleware({ user, context }).run(`${events}/auth/before-signin.js`));
   }
 
   // Setup events
   exporter.bm_authOnCreate =
-  self.libraries.functions
-  .runWith({memory: '256MB', timeoutSeconds: 60})
+  fn({memory: '256MB', timeoutSeconds: 60})
   .auth.user()
   .onCreate((user, context) => self.EventMiddleware({ user, context }).run(`${events}/auth/on-create.js`));
 
   exporter.bm_authOnDelete =
-  self.libraries.functions
-  .runWith({memory: '256MB', timeoutSeconds: 60})
+  fn({memory: '256MB', timeoutSeconds: 60})
   .auth.user()
   .onDelete((user, context) => self.EventMiddleware({ user, context }).run(`${events}/auth/on-delete.js`));
 
   exporter.bm_notificationsOnWrite =
-  self.libraries.functions
-  .runWith({memory: '256MB', timeoutSeconds: 60})
+  fn({memory: '256MB', timeoutSeconds: 60})
   .firestore.document('notifications/{token}')
   .onWrite((change, context) => self.EventMiddleware({ change, context }).run(`${events}/firestore/notifications/on-write.js`));
 
   exporter.bm_paymentsWebhookOnWrite =
-  self.libraries.functions
-  .runWith({memory: '256MB', timeoutSeconds: 60})
+  fn({memory: '256MB', timeoutSeconds: 60})
   .firestore.document('payments-webhooks/{eventId}')
   .onWrite((change, context) => self.EventMiddleware({ change, context }).run(`${events}/firestore/payments-webhooks/on-write.js`));
 
   // Setup cron jobs
   exporter.bm_cronDaily =
-  self.libraries.functions
-  .runWith({ memory: '256MB', timeoutSeconds: 60 * 5})
+  fn({memory: '256MB', timeoutSeconds: 60 * 5})
   .pubsub.schedule('0 0 * * *')
   .onRun((context) => self.EventMiddleware({ context }).run(`${cron}/daily.js`));
 };

package/src/manager/libraries/{stripe.js → payment-processors/stripe.js}

@@ -5,7 +5,7 @@ let stripeInstance = null;
 
 /**
  * Stripe shared library
- * Provides SDK initialization and unified subscription transformation
+ * Provides SDK initialization, resource fetching, and unified transformations
  */
 const Stripe = {
   /**
@@ -27,6 +27,33 @@ const Stripe = {
     return stripeInstance;
   },
 
+  /**
+   * Fetch the latest resource from Stripe's API
+   *
+   * @param {string} resourceType - 'subscription' | 'invoice' | 'session'
+   * @param {string} resourceId - Stripe resource ID
+   * @param {object} rawFallback - Fallback data from webhook payload (unused for Stripe — fetches live)
+   * @param {object} context - Additional context (e.g., { admin }) — unused for Stripe
+   * @returns {object} Full Stripe resource object
+   */
+  async fetchResource(resourceType, resourceId, rawFallback, context) {
+    const stripe = this.init();
+
+    if (resourceType === 'subscription') {
+      return stripe.subscriptions.retrieve(resourceId);
+    }
+
+    if (resourceType === 'invoice') {
+      return stripe.invoices.retrieve(resourceId);
+    }
+
+    if (resourceType === 'session') {
+      return stripe.checkout.sessions.retrieve(resourceId);
+    }
+
+    throw new Error(`Unknown resource type: ${resourceType}`);
+  },
+
   /**
    * Transform a raw Stripe subscription object into the unified subscription shape
    * This produces the exact same object stored in users/{uid}.subscription
@@ -38,7 +65,7 @@ const Stripe = {
    * @param {string} options.eventId - ID of the webhook event (e.g., 'evt_xxx')
    * @returns {object} Unified subscription object
    */
-  toUnified(rawSubscription, options) {
+  toUnifiedSubscription(rawSubscription, options) {
     options = options || {};
     const config = options.config || {};
 
@@ -94,6 +121,34 @@ const Stripe = {
       },
     };
   },
+
+  /**
+   * Transform a raw Stripe one-time payment resource into a unified shape
+   * Stub for now — will be fully implemented when one-time purchases are built out
+   *
+   * @param {object} rawResource - Raw Stripe resource (session, invoice, etc.)
+   * @param {object} options
+   * @returns {object} Unified one-time payment object
+   */
+  toUnifiedOneTime(rawResource, options) {
+    options = options || {};
+
+    const now = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+    return {
+      id: rawResource.id || null,
+      processor: 'stripe',
+      status: rawResource.status || 'unknown',
+      raw: rawResource,
+      metadata: {
+        created: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+      },
+    };
+  },
 };
 
 /**