backend-manager 5.0.89 → 5.0.91

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

@@ -1,14 +1,26 @@
 /**
  * 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 }) {
+const { sendOrderEmail, formatDate } = require('../send-email.js');
+
+module.exports = async function ({ before, after, order, uid, assistant, Manager }) {
   assistant.log(`Transition [subscription/payment-recovered]: uid=${uid}, product=${after.product.id}`);
 
-  // TODO: Send payment recovered email
-  // TODO: Fire analytics event
+  sendOrderEmail({
+    template: 'd-d6dbd17a260a4755b34a852ba09c2454',
+    subject: 'Your payment was successful',
+    categories: ['order/payment-recovered'],
+    uid,
+    assistant,
+    Manager,
+    data: {
+      order: {
+        ...order,
+        _computed: {
+          date: formatDate(new Date().toISOString()),
+        },
+      },
+    },
+  });
 };

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

@@ -1,16 +1,35 @@
 /**
  * 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 { sendOrderEmail, formatDate } = require('../send-email.js');
+
+module.exports = async function ({ before, after, order, uid, assistant, Manager }) {
   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
+  sendOrderEmail({
+    template: 'd-399086311bbb48b4b77bc90b20fb9d0a',
+    subject: 'Your subscription plan has been updated',
+    categories: ['order/plan-changed'],
+    uid,
+    assistant,
+    Manager,
+    data: {
+      order: {
+        ...order,
+        // Inject previous plan info into the unified object for the template
+        unified: {
+          ...order.unified,
+          previous: {
+            product: before.product,
+            price: before.payment?.price || 0,
+          },
+        },
+        _computed: {
+          date: formatDate(new Date().toISOString()),
+        },
+      },
+    },
+  });
 };

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

@@ -1,16 +1,32 @@
 /**
  * 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 }) {
+const { sendOrderEmail, formatDate } = require('../send-email.js');
+
+module.exports = async function ({ before, after, order, uid, assistant, Manager }) {
   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
+  // Check if subscription has a future expiry (e.g., cancelled at period end)
+  const hasFutureExpiry = after.expires?.timestamp && new Date(after.expires.timestamp) > new Date();
+
+  sendOrderEmail({
+    template: 'd-39041132e6b24e5ebf0e95bce2d94dba',
+    subject: 'Your subscription has been cancelled',
+    categories: ['order/cancelled'],
+    uid,
+    assistant,
+    Manager,
+    data: {
+      order: {
+        ...order,
+        _computed: {
+          date: formatDate(new Date().toISOString()),
+          ...(hasFutureExpiry && {
+            expiresDate: formatDate(after.expires.timestamp),
+          }),
+        },
+      },
+    },
+  });
 };

package/src/manager/helpers/user.js

@@ -41,6 +41,7 @@ const SCHEMA = {
       orderId: { type: 'string', default: null, nullable: true },
       resourceId: { type: 'string', default: null, nullable: true },
       frequency: { type: 'string', default: null, nullable: true },
+      price: { type: 'number', default: 0 },
       startDate: '$timestamp',
       updatedBy: {
         event: {

package/src/manager/libraries/payment-processors/resolve-price-id.js

@@ -0,0 +1,19 @@
+/**
+ * Resolve the Stripe price ID from a product config object
+ *
+ * @param {object} product - Product object from config (must have .prices)
+ * @param {string} productType - 'subscription' or 'one-time'
+ * @param {string} frequency - 'monthly', 'annually', etc. (subscriptions) — ignored for one-time
+ * @returns {string} Stripe price ID
+ * @throws {Error} If no price ID found
+ */
+module.exports = function resolvePriceId(product, productType, frequency) {
+  const key = productType === 'subscription' ? frequency : 'once';
+  const priceId = product.prices?.[key]?.stripe;
+
+  if (!priceId) {
+    throw new Error(`No Stripe price found for ${product.id}/${key}`);
+  }
+
+  return priceId;
+};

package/src/manager/libraries/payment-processors/stripe.js

@@ -3,6 +3,13 @@ const powertools = require('node-powertools');
 // Lazy singleton Stripe SDK instance
 let stripeInstance = null;
 
+// Epoch zero timestamps (used as default/empty dates)
+const EPOCH_ZERO = powertools.timestamp(new Date(0), { output: 'string' });
+const EPOCH_ZERO_UNIX = powertools.timestamp(EPOCH_ZERO, { output: 'unix' });
+
+// Stripe interval → unified frequency map
+const INTERVAL_TO_FREQUENCY = { year: 'annually', month: 'monthly', week: 'weekly', day: 'daily' };
+
 /**
  * Stripe shared library
  * Provides SDK initialization, resource fetching, and unified transformations
@@ -79,9 +86,6 @@ const Stripe = {
     options = options || {};
     const config = options.config || {};
 
-    const oldDate = powertools.timestamp(new Date(0), { output: 'string' });
-    const oldDateUNIX = powertools.timestamp(oldDate, { output: 'unix' });
-
     // Resolve status
     const status = resolveStatus(rawSubscription);
 
@@ -98,10 +102,13 @@ const Stripe = {
     const product = resolveProduct(rawSubscription, config);
 
     // Resolve expiration
-    const expires = resolveExpires(rawSubscription, oldDate, oldDateUNIX);
+    const expires = resolveExpires(rawSubscription);
 
     // Resolve start date
-    const startDate = resolveStartDate(rawSubscription, oldDate, oldDateUNIX);
+    const startDate = resolveStartDate(rawSubscription);
+
+    // Resolve price from config
+    const price = resolvePrice(product.id, frequency, config);
 
     // Build the unified subscription object
     const now = powertools.timestamp(new Date(), { output: 'string' });
@@ -118,6 +125,7 @@ const Stripe = {
         orderId: rawSubscription.metadata?.orderId || null,
         resourceId: rawSubscription.id || null,
         frequency: frequency,
+        price: price,
         startDate: startDate,
         updatedBy: {
           event: {
@@ -135,7 +143,7 @@ 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
+   * Mirrors subscription structure: { product, status, payment: { ... } }
    *
    * @param {object} rawResource - Raw Stripe resource (session, invoice, etc.)
    * @param {object} options
@@ -143,20 +151,33 @@ const Stripe = {
    */
   toUnifiedOneTime(rawResource, options) {
     options = options || {};
+    const config = options.config || {};
 
     const now = powertools.timestamp(new Date(), { output: 'string' });
     const nowUNIX = powertools.timestamp(now, { output: 'unix' });
 
+    // Resolve product + price from config
+    const productId = rawResource.metadata?.productId;
+    const product = resolveProductOneTime(productId, config);
+    const price = resolvePrice(productId, 'once', config);
+
     return {
-      id: rawResource.id || null,
-      processor: 'stripe',
-      orderId: rawResource.metadata?.orderId || null,
+      product: product,
       status: rawResource.status || 'unknown',
-      raw: rawResource,
-      metadata: {
-        created: {
-          timestamp: now,
-          timestampUNIX: nowUNIX,
+      payment: {
+        processor: 'stripe',
+        orderId: rawResource.metadata?.orderId || null,
+        resourceId: rawResource.id || null,
+        price: price,
+        updatedBy: {
+          event: {
+            name: options.eventName || null,
+            id: options.eventId || null,
+          },
+          date: {
+            timestamp: now,
+            timestampUNIX: nowUNIX,
+          },
         },
       },
     };
@@ -196,9 +217,6 @@ function resolveStatus(raw) {
  * Handles cancel_at_period_end for pending cancellations
  */
 function resolveCancellation(raw) {
-  const oldDate = powertools.timestamp(new Date(0), { output: 'string' });
-  const oldDateUNIX = powertools.timestamp(oldDate, { output: 'unix' });
-
   // Pending cancellation: active but set to cancel at period end
   if (raw.cancel_at_period_end) {
     const periodEnd = raw.current_period_end || raw.items?.data?.[0]?.current_period_end || 0;
@@ -232,8 +250,8 @@ function resolveCancellation(raw) {
   return {
     pending: false,
     date: {
-      timestamp: oldDate,
-      timestampUNIX: oldDateUNIX,
+      timestamp: EPOCH_ZERO,
+      timestampUNIX: EPOCH_ZERO_UNIX,
     },
   };
 }
@@ -242,15 +260,12 @@ function resolveCancellation(raw) {
  * Resolve trial state from Stripe subscription
  */
 function resolveTrial(raw) {
-  const oldDate = powertools.timestamp(new Date(0), { output: 'string' });
-  const oldDateUNIX = powertools.timestamp(oldDate, { output: 'unix' });
-
   const trialStart = raw.trial_start ? raw.trial_start * 1000 : 0;
   const trialEnd = raw.trial_end ? raw.trial_end * 1000 : 0;
   const activated = !!(trialStart && trialEnd);
 
   // Build trial expiration
-  let trialExpires = { timestamp: oldDate, timestampUNIX: oldDateUNIX };
+  let trialExpires = { timestamp: EPOCH_ZERO, timestampUNIX: EPOCH_ZERO_UNIX };
   if (trialEnd) {
     const trialEndDate = powertools.timestamp(new Date(trialEnd), { output: 'string' });
     trialExpires = {
@@ -274,23 +289,7 @@ function resolveFrequency(raw) {
     || raw.items?.data?.[0]?.price?.recurring?.interval
     || null;
 
-  if (interval === 'year') {
-    return 'annually';
-  }
-
-  if (interval === 'month') {
-    return 'monthly';
-  }
-
-  if (interval === 'week') {
-    return 'weekly';
-  }
-
-  if (interval === 'day') {
-    return 'daily';
-  }
-
-  return null;
+  return INTERVAL_TO_FREQUENCY[interval] || null;
 }
 
 /**
@@ -324,10 +323,28 @@ function resolveProduct(raw, config) {
   return { id: 'basic', name: 'Basic' };
 }
 
+/**
+ * Resolve product for one-time payments by matching productId from metadata
+ * Returns { id, name } — falls back to 'unknown' if no match is found
+ */
+function resolveProductOneTime(productId, config) {
+  if (!productId || !config.payment?.products) {
+    return { id: productId || 'unknown', name: 'Unknown' };
+  }
+
+  const product = config.payment.products.find(p => p.id === productId);
+
+  if (!product) {
+    return { id: productId, name: productId };
+  }
+
+  return { id: product.id, name: product.name || product.id };
+}
+
 /**
  * Resolve subscription expiration from Stripe data
  */
-function resolveExpires(raw, oldDate, oldDateUNIX) {
+function resolveExpires(raw) {
   // Stripe API 2025+ moves period dates to items.data[0]
   const periodEndRaw = raw.current_period_end
     || raw.items?.data?.[0]?.current_period_end
@@ -335,30 +352,52 @@ function resolveExpires(raw, oldDate, oldDateUNIX) {
 
   const periodEnd = periodEndRaw
     ? powertools.timestamp(new Date(periodEndRaw * 1000), { output: 'string' })
-    : oldDate;
+    : EPOCH_ZERO;
 
   return {
     timestamp: periodEnd,
-    timestampUNIX: periodEnd !== oldDate
+    timestampUNIX: periodEnd !== EPOCH_ZERO
       ? powertools.timestamp(periodEnd, { output: 'unix' })
-      : oldDateUNIX,
+      : EPOCH_ZERO_UNIX,
   };
 }
 
 /**
  * Resolve subscription start date from Stripe data
  */
-function resolveStartDate(raw, oldDate, oldDateUNIX) {
+function resolveStartDate(raw) {
   const startDate = raw.start_date
     ? powertools.timestamp(new Date(raw.start_date * 1000), { output: 'string' })
-    : oldDate;
+    : EPOCH_ZERO;
 
   return {
     timestamp: startDate,
-    timestampUNIX: startDate !== oldDate
+    timestampUNIX: startDate !== EPOCH_ZERO
       ? powertools.timestamp(startDate, { output: 'unix' })
-      : oldDateUNIX,
+      : EPOCH_ZERO_UNIX,
   };
 }
 
+/**
+ * Resolve the display price for a product/frequency from config
+ *
+ * @param {string} productId - Product ID (e.g., 'premium')
+ * @param {string} frequency - 'monthly', 'annually', or 'once'
+ * @param {object} config - App config
+ * @returns {number} Price amount (e.g., 4.99) or 0
+ */
+function resolvePrice(productId, frequency, config) {
+  const product = config.payment?.products?.find(p => p.id === productId);
+
+  if (!product) {
+    return 0;
+  }
+
+  if (frequency === 'once') {
+    return product.prices?.once?.amount || 0;
+  }
+
+  return product.prices?.[frequency]?.amount || 0;
+}
+
 module.exports = Stripe;

package/src/manager/libraries/payment-processors/test.js

@@ -37,10 +37,10 @@ const Test = {
 
       if (!snapshot.empty) {
         const data = snapshot.docs[0].data();
-        // payments-orders stores the unified subscription inside .subscription
+        // payments-orders stores the unified subscription inside .unified
         // Reconstruct a Stripe-shaped object from the unified data for toUnifiedSubscription()
-        if (resourceType === 'subscription' && data.subscription) {
-          return buildStripeSubscriptionFromUnified(data.subscription, resourceId, context?.eventType, context?.config);
+        if (resourceType === 'subscription' && data.unified) {
+          return buildStripeSubscriptionFromUnified(data.unified, resourceId, context?.eventType, context?.config);
         }
       }
     }
@@ -65,7 +65,7 @@ const Test = {
    */
   toUnifiedOneTime(rawResource, options) {
     const unified = Stripe.toUnifiedOneTime(rawResource, options);
-    unified.processor = 'test';
+    unified.payment.processor = 'test';
     return unified;
   },
 };

package/src/manager/routes/payments/intent/post.js

@@ -71,6 +71,10 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
 
   assistant.log(`Generated orderId=${orderId}`);
 
+  // Build redirect URLs
+  const confirmationUrl = buildConfirmationUrl(Manager.project.websiteUrl, { product, productId, productType, frequency, processor, trial, orderId });
+  const cancelUrl = buildCancelUrl(Manager.project.websiteUrl, { productId, frequency });
+
   // Load the processor module
   let processorModule;
   try {
@@ -89,6 +93,8 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
       productId,
       frequency,
       trial,
+      confirmationUrl,
+      cancelUrl,
       config: Manager.config,
       Manager,
       assistant,
@@ -132,3 +138,41 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
     url: result.url,
   });
 };
+
+/**
+ * Build the confirmation/success redirect URL
+ */
+function buildConfirmationUrl(baseUrl, { product, productId, productType, frequency, processor, trial, orderId }) {
+  const amount = productType === 'subscription'
+    ? (product.prices?.[frequency]?.amount || 0)
+    : (product.prices?.once?.amount || 0);
+
+  const url = new URL('/payment/confirmation', baseUrl);
+  url.searchParams.set('productId', productId);
+  url.searchParams.set('productName', product.name || productId);
+  url.searchParams.set('amount', trial && product.trial?.days ? '0' : String(amount));
+  url.searchParams.set('currency', 'USD');
+  url.searchParams.set('frequency', frequency || 'once');
+  url.searchParams.set('paymentMethod', processor);
+  url.searchParams.set('trial', String(!!trial && !!product.trial?.days));
+  url.searchParams.set('orderId', orderId);
+  url.searchParams.set('track', 'true');
+
+  return url.toString();
+}
+
+/**
+ * Build the cancel/back redirect URL
+ */
+function buildCancelUrl(baseUrl, { productId, frequency }) {
+  const url = new URL('/payment/checkout', baseUrl);
+  url.searchParams.set('product', productId);
+
+  if (frequency) {
+    url.searchParams.set('frequency', frequency);
+  }
+
+  url.searchParams.set('payment', 'cancelled');
+
+  return url.toString();
+}

package/src/manager/routes/payments/intent/processors/stripe.js

@@ -1,3 +1,5 @@
+const resolvePriceId = require('../../../../libraries/payment-processors/resolve-price-id.js');
+
 /**
  * Stripe intent processor
  * Creates Stripe Checkout Sessions for subscription and one-time purchases
@@ -12,11 +14,11 @@ module.exports = {
    * @param {string} options.productId - Product ID from config (e.g., 'premium')
    * @param {string} options.frequency - 'monthly' or 'annually' (subscriptions only)
    * @param {boolean} options.trial - Whether to include a trial period (subscriptions only)
-   * @param {object} options.config - BEM config
-   * @param {object} options.Manager - Manager instance
+   * @param {string} options.confirmationUrl - Success redirect URL
+   * @param {string} options.cancelUrl - Cancel redirect URL
    * @returns {object} { id, url, raw }
    */
-  async createIntent({ uid, orderId, product, productId, frequency, trial, config, Manager, assistant }) {
+  async createIntent({ uid, orderId, product, productId, frequency, trial, confirmationUrl, cancelUrl, assistant }) {
     // Initialize Stripe SDK
     const StripeLib = require('../../../../libraries/payment-processors/stripe.js');
     const stripe = StripeLib.init();
@@ -24,50 +26,13 @@ module.exports = {
     const productType = product.type || 'subscription';
 
     // Resolve the Stripe price ID based on product type
-    let priceId;
-    if (productType === 'subscription') {
-      priceId = product.prices?.[frequency]?.stripe;
-      if (!priceId) {
-        throw new Error(`No Stripe price found for ${productId}/${frequency}`);
-      }
-    } else {
-      priceId = product.prices?.once?.stripe;
-      if (!priceId) {
-        throw new Error(`No Stripe price found for ${productId}/once`);
-      }
-    }
+    const priceId = resolvePriceId(product, productType, frequency);
 
     // Resolve or create Stripe customer (keyed by uid in metadata)
     const email = assistant?.getUser()?.auth?.email || null;
     const customer = await resolveCustomer(stripe, uid, email, assistant);
 
-    assistant?.log(`Stripe checkout: type=${productType}, priceId=${priceId}, uid=${uid}, customerId=${customer.id}, trial=${trial}, trialDays=${product.trial?.days || 'none'}`);
-
-    // Build confirmation redirect URL
-    const baseUrl = Manager.project.websiteUrl;
-    const amount = productType === 'subscription'
-      ? (product.prices?.[frequency]?.amount || 0)
-      : (product.prices?.once?.amount || 0);
-
-    let confirmationUrl = new URL('/payment/confirmation', baseUrl);
-    confirmationUrl.searchParams.set('productId', productId);
-    confirmationUrl.searchParams.set('productName', product.name || productId);
-    confirmationUrl.searchParams.set('amount', trial && product.trial?.days ? '0' : String(amount));
-    confirmationUrl.searchParams.set('currency', 'USD');
-    confirmationUrl.searchParams.set('frequency', frequency || 'once');
-    confirmationUrl.searchParams.set('paymentMethod', 'stripe');
-    confirmationUrl.searchParams.set('trial', String(!!trial && !!product.trial?.days));
-    confirmationUrl.searchParams.set('orderId', orderId);
-    confirmationUrl.searchParams.set('track', 'true');
-    confirmationUrl = confirmationUrl.toString();
-
-    let cancelUrl = new URL('/payment/checkout', baseUrl);
-    cancelUrl.searchParams.set('product', productId);
-    if (frequency) {
-      cancelUrl.searchParams.set('frequency', frequency);
-    }
-    cancelUrl.searchParams.set('payment', 'cancelled');
-    cancelUrl = cancelUrl.toString();
+    assistant.log(`Stripe checkout: type=${productType}, priceId=${priceId}, uid=${uid}, customerId=${customer.id}, trial=${trial}, trialDays=${product.trial?.days || 'none'}`);
 
     // Build session params based on product type
     let sessionParams;
@@ -81,7 +46,7 @@ module.exports = {
     // Create the checkout session
     const session = await stripe.checkout.sessions.create(sessionParams);
 
-    assistant?.log(`Stripe session created: sessionId=${session.id}, mode=${sessionParams.mode}, url=${session.url}`);
+    assistant.log(`Stripe session created: sessionId=${session.id}, mode=${sessionParams.mode}, url=${session.url}`);
 
     return {
       id: session.id,
@@ -165,7 +130,7 @@ async function resolveCustomer(stripe, uid, email, assistant) {
 
   if (search.data.length > 0) {
     const existing = search.data[0];
-    assistant?.log(`Found existing Stripe customer: ${existing.id}`);
+    assistant.log(`Found existing Stripe customer: ${existing.id}`);
     return existing;
   }
 
@@ -179,6 +144,6 @@ async function resolveCustomer(stripe, uid, email, assistant) {
   }
 
   const customer = await stripe.customers.create(params);
-  assistant?.log(`Created new Stripe customer: ${customer.id}`);
+  assistant.log(`Created new Stripe customer: ${customer.id}`);
   return customer;
 }