backend-manager 5.0.138 → 5.0.140

package/CHANGELOG.md

@@ -14,6 +14,28 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.0.139] - 2026-03-12
+### Fixed
+- Chargebee hosted page checkout failing to resolve UID from webhooks because `subscription[meta_data]` is not supported by Chargebee's hosted page API
+- Webhook pipeline now falls back to resolving UID from hosted page `pass_thru_content` when meta_data is missing
+
+### Added
+- `resolveUidFromHostedPage()` in Chargebee library to search recent hosted pages by subscription ID and extract UID from `pass_thru_content`
+- `setMetaData()` in Chargebee library to backfill meta_data on subscriptions and customers after first UID resolution
+- Automatic meta_data backfill on subscription + customer after resolving UID from pass_thru_content, so future webhooks resolve directly
+
+### Changed
+- Chargebee intent now uses `pass_thru_content` instead of `subscription.meta_data` to carry UID/orderId through checkout
+
+# [5.0.132] - 2026-03-13
+### Fixed
+- Abandoned cart cron crashing with `FAILED_PRECONDITION` due to missing `payments-carts` composite index (status + nextReminderAt)
+- Abandoned cart email subject and template using raw `productId` instead of resolved `productName` and `brandName`
+
+### Changed
+- Index sync (`npx bm setup`) now auto-merges local and live indexes instead of prompting to choose one direction
+- Added `payments-carts` composite index to `required-indexes.js`
+
 # [5.0.131] - 2026-03-11
 ### Changed
 - Analytics config restructured: consolidated `googleAnalytics`, `meta`, and `tiktok` under unified `analytics.providers` namespace with `google`, `meta`, and `tiktok` keys

package/CLAUDE.md

@@ -1044,6 +1044,8 @@ The `test` processor generates Stripe-shaped data and auto-fires webhooks to the
 
 8. **Increment usage before update** - Call `usage.increment()` then `usage.update()`
 
+9. **Add Firestore composite indexes for new compound queries** - Any new Firestore query using multiple `.where()` clauses or `.where()` + `.orderBy()` requires a composite index. Add it to `src/cli/commands/setup-tests/required-indexes.js` (the SSOT). Consumer projects pick these up via `npx bm setup`, which syncs them into `firestore.indexes.json`. Without the index, the query will crash with `FAILED_PRECONDITION` in production.
+
 ## Key Files Reference
 
 | Purpose | File |
@@ -1072,6 +1074,7 @@ The `test` processor generates Stripe-shaped data and auto-fires webhooks to the
 | Stripe library | `src/manager/libraries/payment/processors/stripe.js` |
 | PayPal library | `src/manager/libraries/payment/processors/paypal.js` |
 | Order ID generator | `src/manager/libraries/payment/order-id.js` |
+| Required Firestore indexes (SSOT) | `src/cli/commands/setup-tests/required-indexes.js` |
 | Test accounts | `src/test/test-accounts.js` |
 
 ## Environment Detection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.138",
+  "version": "5.0.140",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/cli/commands/setup-tests/firestore-indexes-synced.js

@@ -2,7 +2,6 @@ const BaseTest = require('./base-test');
 const jetpack = require('fs-jetpack');
 const chalk = require('chalk');
 const _ = require('lodash');
-const inquirer = require('inquirer');
 const powertools = require('node-powertools');
 
 class FirestoreIndexesSyncedTest extends BaseTest {
@@ -87,45 +86,101 @@ class FirestoreIndexesSyncedTest extends BaseTest {
 
   async fix() {
     const self = this.self;
+    const filePath = `${self.firebaseProjectPath}/firestore.indexes.json`;
 
-    const answer = await inquirer.prompt([
-      {
-        type: 'list',
-        name: 'direction',
-        message: 'Firestore indexes are out of sync. Which direction?',
-        choices: [
-          {
-            name: `Local → Live   (replace ${chalk.bold('live')} indexes with ${chalk.bold('local')})`,
-            value: 'local-to-live',
-          },
-          {
-            name: `Live → Local   (replace ${chalk.bold('local')} indexes with ${chalk.bold('live')})`,
-            value: 'live-to-local',
-          },
-          {
-            name: 'Skip',
-            value: 'skip',
-          },
-        ],
-      },
-    ]);
-
-    if (answer.direction === 'live-to-local') {
-      const commands = require('../index');
-      const IndexesCommand = commands.IndexesCommand;
-      const indexesCmd = new IndexesCommand(self);
-
-      await indexesCmd.get(undefined, true);
-    } else if (answer.direction === 'local-to-live') {
-      console.log(chalk.yellow(`  Deploying local indexes to live...`));
-
-      await powertools.execute('firebase deploy --only firestore:indexes', {
-        log: true,
-        cwd: self.firebaseProjectPath,
-      });
-
-      console.log(chalk.green(`  ✓ Live indexes updated from local`));
+    // Fetch live indexes
+    const commands = require('../index');
+    const IndexesCommand = commands.IndexesCommand;
+    const indexesCmd = new IndexesCommand(self);
+    const tempPath = '_firestore.indexes.json';
+    const liveIndexes = await indexesCmd.get(tempPath, false);
+    jetpack.remove(`${self.firebaseProjectPath}/${tempPath}`);
+
+    // Read local indexes
+    let localIndexes = { indexes: [], fieldOverrides: [] };
+    if (jetpack.exists(filePath)) {
+      localIndexes = JSON.parse(jetpack.read(filePath));
+    }
+
+    // Merge: start with local, add any live indexes that don't already exist locally
+    const merged = [...(localIndexes.indexes || [])];
+    const liveList = (liveIndexes?.indexes || []);
+
+    for (const liveIdx of liveList) {
+      const alreadyExists = merged.some(localIdx => this._normalizedMatch(localIdx, liveIdx));
+
+      if (!alreadyExists) {
+        merged.push(this._stripImplicitFields(liveIdx));
+      }
+    }
+
+    // Merge fieldOverrides the same way
+    const mergedOverrides = [...(localIndexes.fieldOverrides || [])];
+    for (const liveOverride of (liveIndexes?.fieldOverrides || [])) {
+      const alreadyExists = mergedOverrides.some(lo => _.isEqual(lo, liveOverride));
+
+      if (!alreadyExists) {
+        mergedOverrides.push(liveOverride);
+      }
+    }
+
+    // Write merged result locally
+    const result = { indexes: merged, fieldOverrides: mergedOverrides };
+    jetpack.write(filePath, JSON.stringify(result, null, 2));
+
+    const addedCount = merged.length - (localIndexes.indexes || []).length;
+    console.log(chalk.green(`  ✓ Merged indexes (${merged.length} total, ${addedCount} added from live)`));
+
+    // Deploy merged indexes to live
+    console.log(chalk.yellow(`  Deploying merged indexes to live...`));
+    await powertools.execute('firebase deploy --only firestore:indexes', {
+      log: true,
+      cwd: self.firebaseProjectPath,
+    });
+
+    console.log(chalk.green(`  ✓ Live indexes synced`));
+  }
+
+  /**
+   * Check if two indexes match (ignoring implicit __name__ fields and density)
+   */
+  _normalizedMatch(a, b) {
+    if (!a || !b) {
+      return false;
+    }
+
+    if (a.collectionGroup !== b.collectionGroup) {
+      return false;
     }
+
+    if ((a.queryScope || 'COLLECTION') !== (b.queryScope || 'COLLECTION')) {
+      return false;
+    }
+
+    const aFields = (a.fields || []).filter(f => f.fieldPath !== '__name__');
+    const bFields = (b.fields || []).filter(f => f.fieldPath !== '__name__');
+
+    if (aFields.length !== bFields.length) {
+      return false;
+    }
+
+    return aFields.every((af, i) => {
+      const bf = bFields[i];
+      return af.fieldPath === bf.fieldPath
+        && (af.order || null) === (bf.order || null)
+        && (af.arrayConfig || null) === (bf.arrayConfig || null);
+    });
+  }
+
+  /**
+   * Strip implicit fields Firebase adds to live indexes (density, __name__)
+   */
+  _stripImplicitFields(idx) {
+    const { density, ...rest } = idx;
+    return {
+      ...rest,
+      fields: (rest.fields || []).filter(f => f.fieldPath !== '__name__'),
+    };
   }
 }
 

package/src/cli/commands/setup-tests/required-indexes.js

@@ -35,4 +35,15 @@ module.exports = [
       { fieldPath: 'owner', order: 'ASCENDING' },
     ],
   },
+
+  // Abandoned cart cron — find pending carts due for reminders
+  // Query: .where('status', '==', 'pending').where('nextReminderAt', '<=', nowUNIX)
+  {
+    collectionGroup: 'payments-carts',
+    queryScope: 'COLLECTION',
+    fields: [
+      { fieldPath: 'status', order: 'ASCENDING' },
+      { fieldPath: 'nextReminderAt', order: 'ASCENDING' },
+    ],
+  },
 ];

package/src/manager/cron/frequent/abandoned-carts.js

@@ -60,18 +60,25 @@ module.exports = async ({ Manager, assistant, context, libraries }) => {
       // Build checkout URL from cart data
       const checkoutUrl = buildCheckoutUrl(Manager.project.websiteUrl, data);
 
+      // Resolve product name from config
+      const product = (Manager.config.payment?.products || []).find(p => p.id === data.productId);
+      const productName = product?.name || data.productId;
+      const brandName = Manager.config.brand?.name || '';
+
       // Send reminder email
       assistant.log(`Sending abandoned cart reminder #${reminderIndex + 1} to uid=${uid}, product=${data.productId}`);
 
       sendOrderEmail({
         template: 'main/order/abandoned-cart',
-        subject: `Complete your ${data.productId} checkout`,
+        subject: `Complete your ${brandName} ${productName} checkout`,
         categories: ['order/abandoned-cart', `order/abandoned-cart/reminder-${reminderIndex + 1}`],
         userDoc,
         assistant,
         data: {
           abandonedCart: {
             productId: data.productId,
+            productName: productName,
+            brandName: brandName,
             type: data.type,
             frequency: data.frequency,
             reminderNumber: reminderIndex + 1,

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

@@ -78,9 +78,34 @@ module.exports = async ({ assistant, change, context }) => {
       }
     }
 
-    // Validate UID — must have one by now (either from webhook parse or fetched resource)
+    // Fallback: resolve UID from the hosted page's pass_thru_content
+    // Chargebee hosted page checkouts don't forward subscription[meta_data] to the subscription,
+    // but pass_thru_content is stored on the hosted page and contains our UID + orderId
+    let resolvedFromPassThru = false;
+    let passThruOrderId = null;
+    if (!uid && library.resolveUidFromHostedPage) {
+      const passThruResult = await library.resolveUidFromHostedPage(resourceId, assistant);
+      if (passThruResult) {
+        uid = passThruResult.uid;
+        passThruOrderId = passThruResult.orderId || null;
+        resolvedFromPassThru = true;
+        assistant.log(`UID resolved from hosted page pass_thru_content: uid=${uid}, orderId=${passThruOrderId}, resourceId=${resourceId}`);
+
+        await webhookRef.set({ owner: uid }, { merge: true });
+      }
+    }
+
+    // Validate UID — must have one by now
     if (!uid) {
-      throw new Error(`Webhook event has no UID — could not extract from webhook parse or fetched ${resourceType} resource`);
+      throw new Error(`Webhook event has no UID — could not extract from webhook parse, fetched ${resourceType} resource, or hosted page pass_thru_content`);
+    }
+
+    // Backfill: if UID was resolved from pass_thru_content, set meta_data on the subscription
+    // so future webhooks (renewals, cancellations) can resolve the UID directly
+    if (resolvedFromPassThru && resourceType === 'subscription' && library.setMetaData) {
+      library.setMetaData(resource, { uid, orderId: passThruOrderId })
+        .then(() => assistant.log(`Backfilled meta_data on subscription ${resourceId} + customer: uid=${uid}, orderId=${passThruOrderId}`))
+        .catch((e) => assistant.error(`Failed to backfill meta_data on ${resourceType} ${resourceId}: ${e.message}`));
     }
 
     // Build timestamps
@@ -89,7 +114,8 @@ module.exports = async ({ assistant, change, context }) => {
     const webhookReceivedUNIX = dataAfter.metadata?.created?.timestampUNIX || nowUNIX;
 
     // Extract orderId from resource (processor-agnostic)
-    orderId = library.getOrderId(resource);
+    // Falls back to pass_thru_content orderId when meta_data wasn't available on the resource
+    orderId = library.getOrderId(resource) || passThruOrderId;
 
     // Process the payment event (subscription or one-time)
     if (category !== 'subscription' && category !== 'one-time') {

package/src/manager/libraries/payment/processors/chargebee.js

@@ -130,6 +130,79 @@ const Chargebee = {
     }
   },
 
+  /**
+   * Resolve UID from a Chargebee hosted page's pass_thru_content
+   * Searches recent hosted pages for one whose subscription matches the given resourceId
+   *
+   * @param {string} resourceId - Chargebee subscription ID to match
+   * @param {object} assistant - Assistant instance for logging
+   * @returns {Promise<{ uid: string, orderId: string }|null>}
+   */
+  async resolveUidFromHostedPage(resourceId, assistant) {
+    try {
+      this.init();
+      const result = await this.request('/hosted_pages?limit=25&sort_by[desc]=created_at');
+      const pages = result?.list || [];
+
+      for (const entry of pages) {
+        const hp = entry.hosted_page;
+
+        // Match by subscription ID in the hosted page content
+        if (hp.content?.subscription?.id !== resourceId) {
+          continue;
+        }
+
+        if (!hp.pass_thru_content) {
+          continue;
+        }
+
+        try {
+          const parsed = typeof hp.pass_thru_content === 'string'
+            ? JSON.parse(hp.pass_thru_content)
+            : hp.pass_thru_content;
+
+          if (parsed.uid) {
+            return { uid: parsed.uid, orderId: parsed.orderId || null };
+          }
+        } catch (e) {
+          // Invalid JSON in pass_thru_content — skip
+        }
+      }
+
+      return null;
+    } catch (e) {
+      assistant.log(`resolveUidFromHostedPage failed: ${e.message}`);
+      return null;
+    }
+  },
+
+  /**
+   * Set meta_data on a Chargebee subscription and its customer via direct API calls
+   * Used to backfill meta_data after resolving UID from pass_thru_content,
+   * so future webhooks (renewals, cancellations) can resolve UID directly
+   *
+   * @param {object} resource - Fetched subscription resource (has .id and .customer_id)
+   * @param {object} meta - { uid, orderId } to backfill on the subscription + customer
+   */
+  async setMetaData(resource, meta = {}) {
+    this.init();
+    const metaBody = { meta_data: meta };
+
+    // Backfill subscription
+    await this.request(`/subscriptions/${resource.id}`, {
+      method: 'POST',
+      body: metaBody,
+    });
+
+    // Backfill customer
+    if (resource.customer_id) {
+      await this.request(`/customers/${resource.customer_id}`, {
+        method: 'POST',
+        body: metaBody,
+      });
+    }
+  },
+
   /**
    * Extract the internal orderId from a Chargebee resource
    * Checks meta_data JSON first (new), then cf_clientorderid (legacy)

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

@@ -62,14 +62,14 @@ async function createSubscriptionCheckout({ ChargebeeLib, uid, orderId, product,
   // Deterministic item price ID: {itemId}-{frequency}
   const itemPriceId = `${chargebeeItemId}-${frequency}`;
 
+  // NOTE: subscription[meta_data] is NOT supported by Chargebee's hosted page checkout.
+  // We use pass_thru_content to carry our UID/orderId through the checkout flow,
+  // then backfill meta_data on the subscription after the webhook resolves the UID.
   const params = {
     subscription_items: {
       item_price_id: [itemPriceId],
       quantity: [1],
     },
-    subscription: {
-      meta_data: metaData,
-    },
     redirect_url: confirmationUrl,
     cancel_url: cancelUrl,
     pass_thru_content: metaData,
@@ -79,7 +79,7 @@ async function createSubscriptionCheckout({ ChargebeeLib, uid, orderId, product,
   // set trial_end explicitly. Otherwise let the item price's trial config handle it.
   if (trial === false && product.trial?.days) {
     // Explicitly skip trial by setting trial_end to 0
-    params.subscription.trial_end = 0;
+    params.subscription = { trial_end: 0 };
   }
 
   // Apply discount coupon (first payment only)