backend-manager 5.0.88 → 5.0.91

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

@@ -1,15 +1,26 @@
 /**
  * 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 }) {
+const { sendOrderEmail, formatDate } = require('../send-email.js');
+
+module.exports = async function ({ before, after, order, uid, assistant, Manager }) {
   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
+  sendOrderEmail({
+    template: 'd-e56af0ac62364bfb9e50af02854e2cd3',
+    subject: 'Your payment failed',
+    categories: ['order/payment-failed'],
+    uid,
+    assistant,
+    Manager,
+    data: {
+      order: {
+        ...order,
+        _computed: {
+          date: formatDate(new Date().toISOString()),
+        },
+      },
+    },
+  });
 };

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

@@ -38,8 +38,10 @@ const SCHEMA = {
     },
     payment: {
       processor: { type: 'string', default: null, nullable: true },
+      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/order-id.js

@@ -0,0 +1,18 @@
+const crypto = require('crypto');
+
+/**
+ * Generate a unique order ID in the format XXXX-XXXX-XXXX
+ * 12 random digits, grouped in 3 segments of 4
+ *
+ * @returns {string} e.g. '4637-8821-0473'
+ */
+function generate() {
+  const bytes = crypto.randomBytes(6);
+  const digits = Array.from(bytes)
+    .map(b => (b % 100).toString().padStart(2, '0'))
+    .join('');
+
+  return `${digits.slice(0, 4)}-${digits.slice(4, 8)}-${digits.slice(8, 12)}`;
+}
+
+module.exports = { generate };

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' });
@@ -115,8 +122,10 @@ const Stripe = {
       cancellation: cancellation,
       payment: {
         processor: 'stripe',
+        orderId: rawSubscription.metadata?.orderId || null,
         resourceId: rawSubscription.id || null,
         frequency: frequency,
+        price: price,
         startDate: startDate,
         updatedBy: {
           event: {
@@ -134,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
@@ -142,19 +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',
+      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,
+          },
         },
       },
     };
@@ -194,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;
@@ -230,8 +250,8 @@ function resolveCancellation(raw) {
   return {
     pending: false,
     date: {
-      timestamp: oldDate,
-      timestampUNIX: oldDateUNIX,
+      timestamp: EPOCH_ZERO,
+      timestampUNIX: EPOCH_ZERO_UNIX,
     },
   };
 }
@@ -240,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 = {
@@ -272,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;
 }
 
 /**
@@ -322,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
@@ -333,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

@@ -26,18 +26,21 @@ const Test = {
       return rawFallback;
     }
 
-    // Fallback doesn't match — try to look up the resource from Firestore
+    // Fallback doesn't match — try to look up the resource from payments-orders
     const admin = context?.admin;
     if (admin && resourceId) {
-      const collection = resourceType === 'subscription' ? 'payments-subscriptions' : 'payments-one-time';
-      const doc = await admin.firestore().doc(`${collection}/${resourceId}`).get();
-
-      if (doc.exists) {
-        const data = doc.data();
-        // payments-subscriptions stores the unified subscription inside .subscription
+      const snapshot = await admin.firestore()
+        .collection('payments-orders')
+        .where('resourceId', '==', resourceId)
+        .limit(1)
+        .get();
+
+      if (!snapshot.empty) {
+        const data = snapshot.docs[0].data();
+        // 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);
         }
       }
     }
@@ -62,7 +65,7 @@ const Test = {
    */
   toUnifiedOneTime(rawResource, options) {
     const unified = Stripe.toUnifiedOneTime(rawResource, options);
-    unified.processor = 'test';
+    unified.payment.processor = 'test';
     return unified;
   },
 };
@@ -110,7 +113,7 @@ function buildStripeSubscriptionFromUnified(unified, resourceId, eventType, conf
     id: resourceId,
     object: 'subscription',
     status: status,
-    metadata: {},
+    metadata: { orderId: unified.payment?.orderId || null },
     plan: {
       id: priceId,
       interval: INTERVAL_MAP[frequency] || 'month',

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

@@ -1,5 +1,6 @@
 const path = require('path');
 const powertools = require('node-powertools');
+const OrderId = require('../../../libraries/payment-processors/order-id.js');
 
 /**
  * POST /payments/intent
@@ -49,8 +50,9 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
     // Resolve trial eligibility: if requested but user has subscription history, silently downgrade
     if (trial) {
       const historySnapshot = await admin.firestore()
-        .collection('payments-subscriptions')
-        .where('uid', '==', uid)
+        .collection('payments-orders')
+        .where('owner', '==', uid)
+        .where('type', '==', 'subscription')
         .limit(1)
         .get();
 
@@ -64,6 +66,15 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
     trial = false;
   }
 
+  // Generate order ID
+  const orderId = OrderId.generate();
+
+  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 {
@@ -77,10 +88,13 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
   try {
     result = await processorModule.createIntent({
       uid,
+      orderId,
       product,
       productId,
       frequency,
       trial,
+      confirmationUrl,
+      cancelUrl,
       config: Manager.config,
       Manager,
       assistant,
@@ -96,11 +110,12 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
   const now = powertools.timestamp(new Date(), { output: 'string' });
   const nowUNIX = powertools.timestamp(now, { output: 'unix' });
 
-  // Save to payments-intents collection
-  await admin.firestore().doc(`payments-intents/${result.id}`).set({
-    id: result.id,
+  // Save to payments-intents collection (keyed by orderId for consistent lookup with payments-orders)
+  await admin.firestore().doc(`payments-intents/${orderId}`).set({
+    id: orderId,
+    intentId: result.id,
     processor: processor,
-    uid: uid,
+    owner: uid,
     status: 'pending',
     productId: productId,
     productType: productType,
@@ -115,10 +130,49 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
     },
   });
 
-  assistant.log(`Saved payments-intents/${result.id}: uid=${uid}, product=${productId}, type=${productType}, frequency=${frequency}, trial=${trial}`);
+  assistant.log(`Saved payments-intents/${orderId}: uid=${uid}, product=${productId}, type=${productType}, frequency=${frequency}, trial=${trial}`);
 
   return assistant.respond({
     id: result.id,
+    orderId: orderId,
     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();
+}