backend-manager 5.0.73 → 5.0.74

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

@@ -0,0 +1,94 @@
+const path = require('path');
+const powertools = require('node-powertools');
+
+/**
+ * POST /payments/intent
+ * Creates a payment intent (e.g., Stripe Checkout Session) for subscription purchase
+ * Requires authentication
+ */
+module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
+  const { admin } = libraries;
+
+  // Require authentication
+  if (!user.authenticated) {
+    return assistant.respond('Authentication required', { code: 401 });
+  }
+
+  const uid = user.auth.uid;
+  const processor = settings.processor;
+  const productId = settings.productId;
+  const frequency = settings.frequency;
+  const trial = settings.trial;
+
+  // Check if user already has an active non-basic subscription
+  if (user.subscription?.status === 'active' && user.subscription?.product?.id !== 'basic') {
+    return assistant.respond('User already has an active subscription', { code: 400 });
+  }
+
+  // Check trial eligibility
+  if (trial && user.subscription?.trial?.activated) {
+    return assistant.respond('Trial already used', { code: 400 });
+  }
+
+  // Validate product exists in config
+  const product = (Manager.config.products || []).find(p => p.id === productId);
+  if (!product) {
+    return assistant.respond(`Product '${productId}' not found`, { code: 400 });
+  }
+
+  // Load the provider
+  let provider;
+  try {
+    provider = require(path.resolve(__dirname, `providers/${processor}.js`));
+  } catch (e) {
+    return assistant.respond(`Unknown processor: ${processor}`, { code: 400 });
+  }
+
+  // Initialize the processor SDK
+  const StripeLib = require('../../../libraries/stripe.js');
+  const stripe = StripeLib.init();
+
+  // Create the intent via the provider
+  let result;
+  try {
+    result = await provider.createIntent({
+      uid,
+      productId,
+      frequency,
+      trial,
+      config: Manager.config,
+      stripe,
+    });
+  } catch (e) {
+    return assistant.respond(`Failed to create intent: ${e.message}`, { code: 500, sentry: true });
+  }
+
+  // Build timestamps
+  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,
+    processor: processor,
+    uid: uid,
+    status: 'pending',
+    productId: productId,
+    frequency: frequency,
+    trial: trial,
+    raw: result.raw,
+    metadata: {
+      created: {
+        timestamp: now,
+        timestampUNIX: nowUNIX,
+      },
+    },
+  });
+
+  assistant.log(`Intent ${result.id} created for user ${uid} (product=${productId}, frequency=${frequency}, trial=${trial})`);
+
+  return assistant.respond({
+    id: result.id,
+    url: result.url,
+  });
+};

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

@@ -0,0 +1,66 @@
+/**
+ * Stripe intent provider
+ * Creates Stripe Checkout Sessions for subscription purchases
+ */
+module.exports = {
+  /**
+   * Create a Stripe Checkout Session for a subscription
+   *
+   * @param {object} options
+   * @param {string} options.uid - User's UID
+   * @param {string} options.productId - Product ID from config (e.g., 'premium')
+   * @param {string} options.frequency - 'monthly' or 'annually'
+   * @param {boolean} options.trial - Whether to include a trial period
+   * @param {object} options.config - BEM config (must contain products array)
+   * @param {object} options.stripe - Initialized Stripe SDK instance
+   * @returns {object} { id, url, raw }
+   */
+  async createIntent({ uid, productId, frequency, trial, config, stripe }) {
+    // Find the product in config
+    const product = (config.products || []).find(p => p.id === productId);
+    if (!product) {
+      throw new Error(`Product '${productId}' not found in config`);
+    }
+
+    // Get the Stripe price ID for the requested frequency
+    const priceId = product.prices?.[frequency]?.stripe;
+    if (!priceId) {
+      throw new Error(`No Stripe price found for ${productId}/${frequency}`);
+    }
+
+    // Build session params
+    const sessionParams = {
+      mode: 'subscription',
+      line_items: [{
+        price: priceId,
+        quantity: 1,
+      }],
+      subscription_data: {
+        metadata: {
+          uid: uid,
+        },
+      },
+      success_url: `${config.brand?.url || 'https://example.com'}/account/?payment=success`,
+      cancel_url: `${config.brand?.url || 'https://example.com'}/account/?payment=cancelled`,
+      metadata: {
+        uid: uid,
+        productId: productId,
+        frequency: frequency,
+      },
+    };
+
+    // Add trial period if requested
+    if (trial && product.trial?.days) {
+      sessionParams.subscription_data.trial_period_days = product.trial.days;
+    }
+
+    // Create the checkout session
+    const session = await stripe.checkout.sessions.create(sessionParams);
+
+    return {
+      id: session.id,
+      url: session.url,
+      raw: session,
+    };
+  },
+};

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

@@ -0,0 +1,87 @@
+const path = require('path');
+const powertools = require('node-powertools');
+
+/**
+ * POST /payments/webhook?processor=stripe&key=XXX
+ * Receives payment provider webhooks, validates them, and saves to Firestore
+ * The Firestore onWrite trigger handles async processing
+ */
+module.exports = async ({ assistant, Manager, libraries }) => {
+  const { admin } = libraries;
+  const data = assistant.request.data;
+  const query = assistant.request.query;
+
+  // Get processor and key from query params
+  const processor = query.processor;
+  const key = query.key;
+
+  // Validate processor
+  if (!processor) {
+    return assistant.respond('Missing processor parameter', { code: 400 });
+  }
+
+  // Validate key against BACKEND_MANAGER_KEY
+  if (!key || key !== process.env.BACKEND_MANAGER_KEY) {
+    return assistant.respond('Invalid key', { code: 401 });
+  }
+
+  // Load the provider
+  let provider;
+  try {
+    provider = require(path.resolve(__dirname, `providers/${processor}.js`));
+  } catch (e) {
+    return assistant.respond(`Unknown processor: ${processor}`, { code: 400 });
+  }
+
+  // Parse the webhook using the provider
+  let parsed;
+  try {
+    parsed = provider.parseWebhook(assistant.ref.req);
+  } catch (e) {
+    return assistant.respond(`Failed to parse webhook: ${e.message}`, { code: 400 });
+  }
+
+  const { eventId, eventType, raw, uid } = parsed;
+
+  // Check for duplicate (skip if already processing/completed)
+  const existingDoc = await admin.firestore().doc(`payments-webhooks/${eventId}`).get();
+  if (existingDoc.exists) {
+    const existingStatus = existingDoc.data()?.status;
+    if (existingStatus !== 'failed') {
+      assistant.log(`Webhook ${eventId} already exists with status=${existingStatus}, skipping`);
+      return assistant.respond({ received: true, duplicate: true });
+    }
+  }
+
+  // Build timestamps
+  const now = powertools.timestamp(new Date(), { output: 'string' });
+  const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+  // Save to Firestore with status=pending (trigger handles the rest)
+  await admin.firestore().doc(`payments-webhooks/${eventId}`).set({
+    id: eventId,
+    processor: processor,
+    status: 'pending',
+    raw: raw,
+    uid: uid,
+    event: {
+      type: eventType,
+    },
+    error: null,
+    metadata: {
+      received: {
+        timestamp: now,
+        timestampUNIX: nowUNIX,
+      },
+      processed: {
+        timestamp: null,
+        timestampUNIX: null,
+      },
+    },
+  });
+
+  assistant.log(`Webhook ${eventId} saved (type=${eventType}, processor=${processor}, uid=${uid})`);
+
+  // Return 200 immediately
+  return assistant.respond({ received: true });
+};

package/src/manager/routes/payments/webhook/providers/stripe.js

@@ -0,0 +1,35 @@
+/**
+ * Stripe webhook provider
+ * Extracts and validates webhook event data from Stripe
+ */
+module.exports = {
+  /**
+   * Parse a Stripe webhook request
+   * Extracts the event data, event type, and resolves the UID from metadata
+   *
+   * @param {object} req - The raw HTTP request
+   * @returns {object} { eventId, eventType, raw, uid }
+   */
+  parseWebhook(req) {
+    const event = req.body;
+
+    // Validate event structure
+    if (!event || !event.id || !event.type) {
+      throw new Error('Invalid Stripe webhook payload');
+    }
+
+    // The subscription object is typically in event.data.object
+    const dataObject = event.data?.object || {};
+
+    // Resolve UID from subscription metadata
+    // When creating checkout sessions, we set metadata.uid on the subscription
+    const uid = dataObject.metadata?.uid || null;
+
+    return {
+      eventId: event.id,
+      eventType: event.type,
+      raw: event,
+      uid: uid,
+    };
+  },
+};

package/src/manager/routes/test/schema/post.js

@@ -3,10 +3,10 @@
  * Returns the resolved settings for testing purposes
  */
 module.exports = async ({ assistant, user, settings }) => {
-  assistant.log('test/schema: User plan info', {
-    planId: user.plan?.id,
-    planStatus: user.plan?.status,
-    fullPlan: user.plan,
+  assistant.log('test/schema: User subscription info', {
+    subscriptionId: user.subscription?.product?.id,
+    subscriptionStatus: user.subscription?.status,
+    fullSubscription: user.subscription,
   });
 
   return assistant.respond({
@@ -14,7 +14,7 @@ module.exports = async ({ assistant, user, settings }) => {
     user: {
       authenticated: user.authenticated,
       uid: user.auth?.uid || null,
-      plan: user.plan?.id || 'basic',
+      subscription: user.subscription?.product?.id || 'basic',
     },
   });
 };

package/src/manager/routes/user/delete.js

@@ -29,10 +29,12 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
 
   const userData = userDoc.data();
 
-  // Disallow deleting users with active subscriptions
+  // Disallow deleting users with active or suspended paid subscriptions
+  const subStatus = userData?.subscription?.status;
+  const subId = userData?.subscription?.product?.id;
   if (
-    (userData?.plan?.status && userData?.plan?.status !== 'cancelled')
-    || userData?.plan?.payment?.active
+    (subStatus === 'active' || subStatus === 'suspended')
+    && subId !== 'basic'
   ) {
     return assistant.respond(
       'This account cannot be deleted because it has a paid subscription attached to it. In order to delete the account, you must first cancel the paid subscription.',

package/src/manager/routes/user/settings/validate/post.js

@@ -5,7 +5,7 @@ const path = require('path');
 
 /**
  * POST /user/settings/validate - Validate user settings against defaults
- * Merges user settings with plan-specific defaults from defaults.js
+ * Merges user settings with subscription-specific defaults from defaults.js
  */
 module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
   const { admin } = libraries;
@@ -23,7 +23,7 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
     return assistant.respond('Admin required', { code: 403 });
   }
 
-  // Get user data for plan
+  // Get user data for subscription
   let userData = user;
 
   if (uid !== user.auth.uid) {
@@ -50,7 +50,7 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
   // Load and process defaults
   try {
     const defaults = _.get(require(resolvedPath)(), settings.defaultsPath);
-    const combined = combineDefaults(defaults.all, defaults[userData.plan?.id] || {});
+    const combined = combineDefaults(defaults.all, defaults[userData.subscription?.product?.id] || {});
 
     assistant.log('Combined settings', combined);
 

package/src/manager/routes/user/subscription/get.js

@@ -2,7 +2,7 @@ const powertools = require('node-powertools');
 
 /**
  * GET /user/subscription - Get user subscription info
- * Returns plan, expiry, trial, and payment status
+ * Returns subscription, expiry, trial, and payment status
  */
 module.exports = async ({ assistant, user, settings, libraries }) => {
   const { admin } = libraries;
@@ -38,21 +38,37 @@ module.exports = async ({ assistant, user, settings, libraries }) => {
   const oldDateUNIX = powertools.timestamp(oldDate, { output: 'unix' });
 
   const result = {
-    plan: {
-      id: userData?.plan?.id || 'unknown',
+    subscription: {
+      product: {
+        id: userData?.subscription?.product?.id || 'basic',
+        name: userData?.subscription?.product?.name || 'Basic',
+      },
+      status: userData?.subscription?.status || 'active',
       expires: {
-        timestamp: userData?.plan?.expires?.timestamp || oldDate,
-        timestampUNIX: userData?.plan?.expires?.timestampUNIX || oldDateUNIX,
+        timestamp: userData?.subscription?.expires?.timestamp || oldDate,
+        timestampUNIX: userData?.subscription?.expires?.timestampUNIX || oldDateUNIX,
       },
       trial: {
-        activated: userData?.plan?.trial?.activated ?? false,
+        activated: userData?.subscription?.trial?.activated ?? false,
+        expires: {
+          timestamp: userData?.subscription?.trial?.expires?.timestamp || oldDate,
+          timestampUNIX: userData?.subscription?.trial?.expires?.timestampUNIX || oldDateUNIX,
+        },
+      },
+      cancellation: {
+        pending: userData?.subscription?.cancellation?.pending ?? false,
         date: {
-          timestamp: userData?.plan?.trial?.date?.timestamp || oldDate,
-          timestampUNIX: userData?.plan?.trial?.date?.timestampUNIX || oldDateUNIX,
+          timestamp: userData?.subscription?.cancellation?.date?.timestamp || oldDate,
+          timestampUNIX: userData?.subscription?.cancellation?.date?.timestampUNIX || oldDateUNIX,
         },
       },
       payment: {
-        active: userData?.plan?.payment?.active ?? false,
+        processor: userData?.subscription?.payment?.processor || null,
+        frequency: userData?.subscription?.payment?.frequency || null,
+        startDate: {
+          timestamp: userData?.subscription?.payment?.startDate?.timestamp || oldDate,
+          timestampUNIX: userData?.subscription?.payment?.startDate?.timestampUNIX || oldDateUNIX,
+        },
       },
     },
   };

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

@@ -0,0 +1,22 @@
+/**
+ * Schema: POST /payments/intent
+ * Validates intent creation parameters
+ */
+module.exports = () => ({
+  processor: {
+    types: ['string'],
+    required: true,
+  },
+  productId: {
+    types: ['string'],
+    required: true,
+  },
+  frequency: {
+    types: ['string'],
+    required: true,
+  },
+  trial: {
+    types: ['boolean'],
+    default: false,
+  },
+});

package/src/manager/schemas/payments/webhook/post.js

@@ -0,0 +1,6 @@
+/**
+ * Schema: POST /payments/webhook
+ * Minimal schema - webhook payloads are validated by the provider, not the schema
+ * The processor and key come from query params, not the body
+ */
+module.exports = () => ({});

package/src/manager/schemas/test/schema/post.js

@@ -3,7 +3,7 @@
  * Tests: types, default (static + function), value, min, max, required, clean
  */
 module.exports = ({ user }) => {
-  const planId = user?.plan?.id || 'basic';
+  const planId = user?.subscription?.product?.id || 'basic';
   const isPremium = planId !== 'basic';
 
   const schema = {

package/src/test/test-accounts.js

@@ -1,9 +1,9 @@
 const uuid = require('uuid');
 
 /**
- * Helper to create a future expiration date for premium plans
- * resolve-account checks plan.expires to determine if plan is active
- * If expires is in the past (or default 1970), plan gets downgraded to basic
+ * Helper to create a future expiration date for premium subscriptions
+ * resolve-account checks subscription.expires to determine if subscription is active
+ * If expires is in the past (or default 1970), subscription gets downgraded to basic
  */
 function getFutureExpires(years = 10) {
   const futureDate = new Date();
@@ -15,7 +15,7 @@ function getFutureExpires(years = 10) {
 }
 
 /**
- * Helper to create a past expiration date for expired plans
+ * Helper to create a past expiration date for expired subscriptions
  */
 function getPastExpires(years = 1) {
   const pastDate = new Date();
@@ -37,7 +37,7 @@ function getPastExpires(years = 1) {
  * - email: Email with {domain} placeholder (resolved at runtime)
  * - properties: Object to merge into user doc after auth:on-create
  *
- * IMPORTANT: Premium accounts MUST have plan.expires set to a future date
+ * IMPORTANT: Premium accounts MUST have subscription.expires set to a future date
  * or resolve-account will downgrade them to basic
  */
 const STATIC_ACCOUNTS = {
@@ -47,7 +47,7 @@ const STATIC_ACCOUNTS = {
     email: '_test.admin@{domain}',
     properties: {
       roles: { admin: true },
-      plan: { id: 'basic', status: 'active' },
+      subscription: { product: { id: 'basic' }, status: 'active' },
     },
   },
   basic: {
@@ -56,7 +56,7 @@ const STATIC_ACCOUNTS = {
     email: '_test.basic@{domain}',
     properties: {
       roles: {},
-      plan: { id: 'basic', status: 'active' },
+      subscription: { product: { id: 'basic' }, status: 'active' },
     },
   },
   'premium-active': {
@@ -65,7 +65,7 @@ const STATIC_ACCOUNTS = {
     email: '_test.premium-active@{domain}',
     properties: {
       roles: {},
-      plan: { id: 'premium', status: 'active', expires: getFutureExpires() },
+      subscription: { product: { id: 'premium' }, status: 'active', expires: getFutureExpires() },
     },
   },
   'premium-expired': {
@@ -74,7 +74,7 @@ const STATIC_ACCOUNTS = {
     email: '_test.premium-expired@{domain}',
     properties: {
       roles: {},
-      plan: { id: 'premium', status: 'cancelled', expires: getPastExpires() },
+      subscription: { product: { id: 'premium' }, status: 'cancelled', expires: getPastExpires() },
     },
   },
   delete: {
@@ -83,7 +83,7 @@ const STATIC_ACCOUNTS = {
     email: '_test.delete@{domain}',
     properties: {
       roles: {},
-      plan: { id: 'premium', status: 'active', expires: getFutureExpires() }, // Active subscription - deletion should be blocked initially
+      subscription: { product: { id: 'premium' }, status: 'active', expires: getFutureExpires() }, // Active subscription - deletion should be blocked initially
     },
   },
   'delete-by-admin': {
@@ -92,7 +92,7 @@ const STATIC_ACCOUNTS = {
     email: '_test.delete-by-admin@{domain}',
     properties: {
       roles: {},
-      // No plan - can be deleted immediately by admin
+      // No subscription - can be deleted immediately by admin
     },
   },
   referrer: {
@@ -101,7 +101,7 @@ const STATIC_ACCOUNTS = {
     email: '_test.referrer@{domain}',
     properties: {
       roles: {},
-      plan: { id: 'basic', status: 'active' },
+      subscription: { product: { id: 'basic' }, status: 'active' },
       affiliate: { code: 'TESTREF', referrals: [] },
     },
   },
@@ -111,7 +111,7 @@ const STATIC_ACCOUNTS = {
     email: '_test.referred@{domain}',
     properties: {
       roles: {},
-      plan: { id: 'basic', status: 'active' },
+      subscription: { product: { id: 'basic' }, status: 'active' },
     },
   },
   'referred-invalid': {
@@ -120,7 +120,7 @@ const STATIC_ACCOUNTS = {
     email: '_test.referred-invalid@{domain}',
     properties: {
       roles: {},
-      plan: { id: 'basic', status: 'active' },
+      subscription: { product: { id: 'basic' }, status: 'active' },
     },
   },
 };
@@ -130,22 +130,40 @@ const STATIC_ACCOUNTS = {
  * These accounts transition through states via webhook tests
  */
 const JOURNEY_ACCOUNTS = {
-  'journey-upgrade': {
-    id: 'journey-upgrade',
-    uid: '_test-journey-upgrade',
-    email: '_test.journey-upgrade@{domain}',
+  'journey-payment-upgrade': {
+    id: 'journey-payment-upgrade',
+    uid: '_test-journey-payment-upgrade',
+    email: '_test.journey-payment-upgrade@{domain}',
     properties: {
       roles: {},
-      plan: { id: 'basic', status: 'active' }, // Starts as basic, upgraded via Stripe webhook
+      subscription: { product: { id: 'basic' }, status: 'active' }, // Starts as basic, upgraded via Stripe webhook
     },
   },
-  'journey-cancel': {
-    id: 'journey-cancel',
-    uid: '_test-journey-cancel',
-    email: '_test.journey-cancel@{domain}',
+  'journey-payment-cancel': {
+    id: 'journey-payment-cancel',
+    uid: '_test-journey-payment-cancel',
+    email: '_test.journey-payment-cancel@{domain}',
     properties: {
       roles: {},
-      plan: { id: 'premium', status: 'active', expires: getFutureExpires() }, // Starts as premium, cancelled via Stripe webhook
+      subscription: { product: { id: 'premium' }, status: 'active', expires: getFutureExpires() }, // Starts as premium, cancelled via Stripe webhook
+    },
+  },
+  'journey-payment-suspend': {
+    id: 'journey-payment-suspend',
+    uid: '_test-journey-payment-suspend',
+    email: '_test.journey-payment-suspend@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'premium' }, status: 'active', expires: getFutureExpires() }, // Starts as premium, suspended via failed payment webhook
+    },
+  },
+  'journey-payment-trial': {
+    id: 'journey-payment-trial',
+    uid: '_test-journey-payment-trial',
+    email: '_test.journey-payment-trial@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' }, // Starts as basic, upgraded via trial webhook
     },
   },
 };
@@ -275,7 +293,7 @@ async function createAccount(admin, account) {
     waited += pollInterval;
   }
 
-  // Merge test-specific properties (roles, plan, etc.)
+  // Merge test-specific properties (roles, subscription, etc.)
   await userRef.set(account.properties, { merge: true });
 
   return { uid: account.uid, email: account.email };
@@ -334,6 +352,26 @@ async function deleteTestUsers(admin) {
     })
   );
 
+  // Clean up payment-related collections for test accounts
+  const testUids = Object.values(TEST_ACCOUNTS).map(a => a.uid);
+  const paymentCollections = ['payments-subscriptions', 'payments-webhooks', 'payments-intents'];
+
+  await Promise.all(
+    paymentCollections.map(async (collection) => {
+      try {
+        const snapshot = await admin.firestore().collection(collection)
+          .where('uid', 'in', testUids)
+          .get();
+
+        await Promise.all(
+          snapshot.docs.map(doc => doc.ref.delete())
+        );
+      } catch (e) {
+        // Collection may not exist yet — ignore
+      }
+    })
+  );
+
   return {
     success: results.failed.length === 0,
     deleted: results.deleted.length,

package/src/test/utils/firestore-rules-client.js

@@ -162,7 +162,7 @@ async function seedTestAccounts(accounts) {
     throw new Error('Test environment not initialized. Call initRulesTestEnv() first.');
   }
 
-  // Get static account definitions for roles/plan data
+  // Get static account definitions for roles/subscription data
   const { TEST_ACCOUNTS } = require('../test-accounts.js');
 
   // Use withSecurityRulesDisabled to write test data
@@ -174,7 +174,7 @@ async function seedTestAccounts(accounts) {
         continue;
       }
 
-      // Get the static definition for this account type (has roles, plan)
+      // Get the static definition for this account type (has roles, subscription)
       const staticDef = TEST_ACCOUNTS[accountType];
 
       // Build user document with roles for isAdmin() check
@@ -186,9 +186,9 @@ async function seedTestAccounts(accounts) {
         roles: staticDef?.properties?.roles || {},
       };
 
-      // Add plan if present in static definition
-      if (staticDef?.properties?.plan) {
-        userData.plan = staticDef.properties.plan;
+      // Add subscription if present in static definition
+      if (staticDef?.properties?.subscription) {
+        userData.subscription = staticDef.properties.subscription;
       }
 
       await db.doc(`users/${account.uid}`).set(userData, { merge: true });