backend-manager 5.0.170 → 5.0.173

package/package.json

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

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

@@ -58,6 +58,17 @@ module.exports = [
     ],
   },
 
+  // Admin dashboard — active paid subscriber count
+  // Serves: .where('subscription.status', '==', 'active').where('subscription.product.id', '!=', 'basic')
+  {
+    collectionGroup: 'users',
+    queryScope: 'COLLECTION',
+    fields: [
+      { fieldPath: 'subscription.status', order: 'ASCENDING' },
+      { fieldPath: 'subscription.product.id', order: 'ASCENDING' },
+    ],
+  },
+
   // GET /marketing/campaign — list by type + sendAt range
   // Query: .where('type', '==', type).where('sendAt', '>=', start).where('sendAt', '<=', end)
   {

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

@@ -5,9 +5,9 @@ const powertools = require('node-powertools');
  * Firestore trigger: payments-disputes/{alertId} onWrite
  *
  * Processes pending dispute alerts:
- * 1. Searches Stripe invoices by date range + amount
- * 2. Matches card last4 digits
- * 3. Issues full refund on matched invoice
+ * 1. Tries direct match via charge ID or payment intent (from Chargeblast alert.updated)
+ * 2. Falls back to searching Stripe invoices by date range + amount + card last4
+ * 3. Issues full refund on matched charge
  * 4. Cancels subscription immediately (Stripe fires webhook → existing pipeline handles user doc)
  * 5. Sends email alert to brand contact
  * 6. Updates dispute document with results
@@ -33,14 +33,14 @@ module.exports = async ({ assistant, change, context }) => {
     const alert = dataAfter.alert;
     const processor = alert.processor || 'stripe';
 
-    assistant.log(`Processing dispute ${alertId}: processor=${processor}, amount=${alert.amount}, card=****${alert.card.last4}, date=${alert.transactionDate}`);
+    assistant.log(`Processing dispute ${alertId}: processor=${processor}, amount=${alert.amount}, card=****${alert.card.last4}, date=${alert.transactionDate}, chargeId=${alert.chargeId || 'none'}, paymentIntentId=${alert.paymentIntentId || 'none'}`);
 
     // Only Stripe is supported for now
     if (processor !== 'stripe') {
       throw new Error(`Unsupported processor: ${processor}. Only 'stripe' is currently supported.`);
     }
 
-    // Search for the matching invoice and process
+    // Search for the matching charge
     const match = await searchAndMatch({ alert, assistant });
 
     // Build timestamps
@@ -48,9 +48,10 @@ module.exports = async ({ assistant, change, context }) => {
     const nowUNIX = powertools.timestamp(now, { output: 'unix' });
 
     if (!match) {
-      // No matching invoice found
+      // No matching charge found
       await disputeRef.set({
         status: 'no-match',
+        match: null,
         actions: {
           refund: 'skipped',
           cancel: 'skipped',
@@ -64,11 +65,11 @@ module.exports = async ({ assistant, change, context }) => {
         },
       }, { merge: true });
 
-      assistant.log(`Dispute ${alertId}: no matching invoice found`);
+      assistant.log(`Dispute ${alertId}: no matching charge found`);
 
       // Still send email to alert brand about unmatched dispute
       if (!assistant.isTesting() || process.env.TEST_EXTENDED_MODE) {
-        sendDisputeEmail({ alert, match: null, alertId, assistant });
+        sendDisputeEmail({ alert, match: null, result: null, alertId, assistant });
         await disputeRef.set({ actions: { email: 'success' } }, { merge: true });
       } else {
         assistant.log(`Dispute ${alertId}: skipping email (testing mode)`);
@@ -85,10 +86,12 @@ module.exports = async ({ assistant, change, context }) => {
     await disputeRef.set({
       status: 'resolved',
       match: {
-        invoiceId: match.invoiceId,
+        method: match.method,
+        invoiceId: match.invoiceId || null,
         subscriptionId: match.subscriptionId || null,
         customerId: match.customerId,
         uid: match.uid || null,
+        email: match.email || null,
         chargeId: match.chargeId,
         refundId: result.refundId || null,
         amountRefunded: result.amountRefunded || null,
@@ -129,7 +132,12 @@ module.exports = async ({ assistant, change, context }) => {
 };
 
 /**
- * Search Stripe invoices by date range + amount and match card last4
+ * Try to match the dispute alert to a Stripe charge.
+ *
+ * Strategy (in order):
+ * 1. Direct lookup via charge ID (externalOrder from Chargeblast)
+ * 2. Direct lookup via payment intent ID (metadata from Chargeblast)
+ * 3. Fallback: search invoices by date range + amount + card last4
  *
  * @param {object} options
  * @param {object} options.alert - Normalized alert data
@@ -140,6 +148,103 @@ async function searchAndMatch({ alert, assistant }) {
   const StripeLib = require('../../../libraries/payment/processors/stripe.js');
   const stripe = StripeLib.init();
 
+  // Strategy 1: Direct charge lookup
+  if (alert.chargeId && alert.chargeId.startsWith('ch_')) {
+    assistant.log(`Trying direct charge lookup: ${alert.chargeId}`);
+
+    try {
+      const charge = await stripe.charges.retrieve(alert.chargeId, {
+        expand: ['invoice', 'customer'],
+      });
+
+      const match = await resolveMatchFromCharge({ charge, stripe, assistant, method: 'charge-id' });
+
+      if (match) {
+        return match;
+      }
+    } catch (e) {
+      assistant.log(`Direct charge lookup failed for ${alert.chargeId}: ${e.message}`);
+    }
+  }
+
+  // Strategy 2: Direct payment intent lookup
+  if (alert.paymentIntentId && alert.paymentIntentId.startsWith('pi_')) {
+    assistant.log(`Trying direct payment intent lookup: ${alert.paymentIntentId}`);
+
+    try {
+      const pi = await stripe.paymentIntents.retrieve(alert.paymentIntentId, {
+        expand: ['latest_charge', 'latest_charge.invoice', 'latest_charge.customer'],
+      });
+
+      const charge = pi.latest_charge;
+      if (charge) {
+        const match = await resolveMatchFromCharge({ charge, stripe, assistant, method: 'payment-intent' });
+
+        if (match) {
+          return match;
+        }
+      }
+    } catch (e) {
+      assistant.log(`Direct payment intent lookup failed for ${alert.paymentIntentId}: ${e.message}`);
+    }
+  }
+
+  // Strategy 3: Fallback — search invoices by date range + amount + card last4
+  return searchInvoicesFallback({ alert, stripe, assistant });
+}
+
+/**
+ * Build a match object from a Stripe charge
+ */
+async function resolveMatchFromCharge({ charge, stripe, assistant, method }) {
+  if (!charge || charge.status !== 'succeeded') {
+    assistant.log(`Charge ${charge?.id} status=${charge?.status}, skipping`);
+    return null;
+  }
+
+  // Resolve UID from customer metadata
+  let uid = null;
+  let email = null;
+  const customerId = typeof charge.customer === 'string' ? charge.customer : charge.customer?.id;
+
+  if (charge.customer && typeof charge.customer === 'object') {
+    uid = charge.customer.metadata?.uid || null;
+    email = charge.customer.email || null;
+  } else if (customerId) {
+    try {
+      const customer = await stripe.customers.retrieve(customerId);
+      uid = customer.metadata?.uid || null;
+      email = customer.email || null;
+    } catch (e) {
+      assistant.error(`Failed to retrieve customer ${customerId}: ${e.message}`);
+    }
+  }
+
+  // Resolve invoice/subscription
+  const invoiceId = typeof charge.invoice === 'string'
+    ? charge.invoice
+    : charge.invoice?.id || null;
+  const subscriptionId = typeof charge.invoice === 'object'
+    ? charge.invoice?.subscription || null
+    : null;
+
+  assistant.log(`Matched via ${method}: charge=${charge.id}, customer=${customerId}, uid=${uid}, invoice=${invoiceId}`);
+
+  return {
+    method: method,
+    invoiceId: invoiceId,
+    subscriptionId: subscriptionId,
+    customerId: customerId,
+    uid: uid,
+    email: email,
+    chargeId: charge.id,
+  };
+}
+
+/**
+ * Fallback: search Stripe invoices by date range + amount and match card last4
+ */
+async function searchInvoicesFallback({ alert, stripe, assistant }) {
   const amountCents = Math.round(alert.amount * 100);
   const alertDate = moment(alert.transactionDate);
 
@@ -150,7 +255,7 @@ async function searchAndMatch({ alert, assistant }) {
   const start = alertDate.clone().subtract(2, 'days').unix();
   const end = alertDate.clone().add(2, 'days').unix();
 
-  assistant.log(`Searching Stripe invoices: amount=${amountCents} cents, range=${moment.unix(start).format('YYYY-MM-DD')} to ${moment.unix(end).format('YYYY-MM-DD')}`);
+  assistant.log(`Fallback: searching Stripe invoices: amount=${amountCents} cents, range=${moment.unix(start).format('YYYY-MM-DD')} to ${moment.unix(end).format('YYYY-MM-DD')}`);
 
   // Search invoices by date range and amount
   const invoices = await stripe.invoices.search({
@@ -184,21 +289,25 @@ async function searchAndMatch({ alert, assistant }) {
 
     // Resolve UID from customer metadata
     let uid = null;
+    let email = null;
     const customerId = invoice.customer;
     if (customerId) {
       try {
         const customer = await stripe.customers.retrieve(customerId);
         uid = customer.metadata?.uid || null;
+        email = customer.email || null;
       } catch (e) {
         assistant.error(`Failed to retrieve customer ${customerId}: ${e.message}`);
       }
     }
 
     return {
+      method: 'invoice-search',
       invoiceId: invoice.id,
       subscriptionId: invoice.subscription || null,
       customerId: customerId,
       uid: uid,
+      email: email,
       chargeId: invoice.charge || null,
     };
   }
@@ -243,11 +352,11 @@ async function processDispute({ match, alert, assistant }) {
       result.currency = refund.currency;
       result.refundStatus = 'success';
 
-      assistant.log(`Refund success: refundId=${refund.id}, amount=${amountCents}, invoice=${match.invoiceId}`);
+      assistant.log(`Refund success: refundId=${refund.id}, amount=${amountCents}, charge=${match.chargeId}`);
     } catch (e) {
       result.refundStatus = 'failed';
       result.errors.push(`Refund failed: ${e.message}`);
-      assistant.error(`Refund failed for invoice ${match.invoiceId}: ${e.message}`);
+      assistant.error(`Refund failed for charge ${match.chargeId}: ${e.message}`);
     }
   }
 
@@ -290,47 +399,72 @@ function sendDisputeEmail({ alert, match, result, alertId, assistant }) {
   }
 
   const matched = match ? 'Matched' : 'Unmatched';
-  const subject = `Dispute alert: ${matched} [${alertId}]`;
-
-  const disputeDetails = {
-    id: alertId,
-    card: `****${alert.card.last4} (${alert.card.brand || 'unknown'})`,
-    amount: `$${alert.amount}`,
-    date: alert.transactionDate,
-    processor: alert.processor,
-  };
+  const subject = `Dispute Alert: ${matched} — $${alert.amount} on ****${alert.card.last4} [${alertId}]`;
 
-  const matchDetails = match
-    ? {
-        invoiceId: match.invoiceId,
-        subscriptionId: match.subscriptionId || 'N/A',
-        uid: match.uid || 'unknown',
-        refund: result?.refundStatus || 'N/A',
-        cancel: result?.cancelStatus || 'N/A',
-      }
-    : null;
+  const messageLines = [];
 
-  const messageLines = [
-    `A dispute alert has been received and ${match ? 'automatically processed' : 'could not be matched to an invoice'}.`,
-    '',
-    '<strong>Dispute Details:</strong>',
-    `<pre><code>${JSON.stringify(disputeDetails, null, 2)}</code></pre>`,
-  ];
-
-  if (matchDetails) {
-    messageLines.push(
-      '',
-      '<strong>Match & Actions:</strong>',
-      `<pre><code>${JSON.stringify(matchDetails, null, 2)}</code></pre>`,
-    );
+  // Status banner
+  if (match && result) {
+    const hasErrors = result.errors?.length > 0;
+    const banner = hasErrors ? 'Partially processed (see errors below)' : 'Automatically processed';
+    messageLines.push(`<strong>${banner}</strong>`);
+  } else {
+    messageLines.push('<strong>Could not be matched to a charge — manual review required.</strong>');
   }
 
+  messageLines.push('');
+
+  // Alert details
+  messageLines.push('<strong>Alert Details:</strong>');
+  messageLines.push('<ul>');
+  messageLines.push(`<li><strong>Alert ID:</strong> ${alertId}</li>`);
+  messageLines.push(`<li><strong>Type:</strong> ${alert.alertType || 'N/A'}</li>`);
+  messageLines.push(`<li><strong>Card:</strong> ****${alert.card.last4} (${alert.card.brand || 'unknown'})</li>`);
+  messageLines.push(`<li><strong>Amount:</strong> $${alert.amount}</li>`);
+  messageLines.push(`<li><strong>Transaction Date:</strong> ${alert.transactionDate}</li>`);
+  messageLines.push(`<li><strong>Processor:</strong> ${alert.processor}</li>`);
+  messageLines.push(`<li><strong>Reason:</strong> ${alert.reasonCode || 'N/A'}</li>`);
+  messageLines.push(`<li><strong>Network:</strong> ${alert.subprovider || 'N/A'}</li>`);
+  messageLines.push(`<li><strong>Customer Email:</strong> ${alert.customerEmail || 'N/A'}</li>`);
+  messageLines.push(`<li><strong>Already Refunded:</strong> ${alert.isRefunded ? 'Yes' : 'No'}</li>`);
+  messageLines.push('</ul>');
+
+  // Match & action details
+  if (match) {
+    messageLines.push('<strong>Match Details:</strong>');
+    messageLines.push('<ul>');
+    messageLines.push(`<li><strong>Method:</strong> ${match.method}</li>`);
+    messageLines.push(`<li><strong>Charge:</strong> ${match.chargeId || 'N/A'}</li>`);
+    messageLines.push(`<li><strong>Invoice:</strong> ${match.invoiceId || 'N/A'}</li>`);
+    messageLines.push(`<li><strong>Subscription:</strong> ${match.subscriptionId || 'N/A'}</li>`);
+    messageLines.push(`<li><strong>Customer:</strong> ${match.customerId || 'N/A'}</li>`);
+    messageLines.push(`<li><strong>Customer Email:</strong> ${match.email || 'N/A'}</li>`);
+    messageLines.push(`<li><strong>UID:</strong> ${match.uid || 'unknown'}</li>`);
+    messageLines.push('</ul>');
+
+    if (result) {
+      messageLines.push('<strong>Actions Taken:</strong>');
+      messageLines.push('<ul>');
+      messageLines.push(`<li><strong>Refund:</strong> ${result.refundStatus}${result.refundId ? ` (${result.refundId})` : ''}${result.amountRefunded ? ` — $${(result.amountRefunded / 100).toFixed(2)} ${result.currency || ''}` : ''}</li>`);
+      messageLines.push(`<li><strong>Cancel Subscription:</strong> ${result.cancelStatus}</li>`);
+      messageLines.push('</ul>');
+    }
+  }
+
+  // Stripe link
+  if (alert.stripeUrl) {
+    messageLines.push(`<br><a href="${alert.stripeUrl}">View in Stripe Dashboard</a>`);
+  }
+
+  // Errors
   if (result?.errors?.length) {
-    messageLines.push(
-      '',
-      '<strong>Errors:</strong>',
-      `<pre><code>${JSON.stringify(result.errors, null, 2)}</code></pre>`,
-    );
+    messageLines.push('');
+    messageLines.push('<strong>Errors:</strong>');
+    messageLines.push('<ul>');
+    result.errors.forEach((err) => {
+      messageLines.push(`<li>${err}</li>`);
+    });
+    messageLines.push('</ul>');
   }
 
   email.send({
@@ -342,11 +476,11 @@ function sendDisputeEmail({ alert, match, result, alertId, assistant }) {
     copy: true,
     data: {
       email: {
-        preview: `Dispute alert: ${matched} — $${alert.amount} on ****${alert.card.last4}`,
+        preview: `Dispute Alert: ${matched} — $${alert.amount} on ****${alert.card.last4}`,
       },
       body: {
-        title: subject,
-        message: messageLines.join('<br>'),
+        title: `Dispute Alert: ${matched}`,
+        message: messageLines.join('\n'),
       },
     },
   })

package/src/manager/helpers/user.js

@@ -108,7 +108,6 @@ const SCHEMA = {
         timestampUNIX: { type: 'number', default: 0 },
       },
     },
-    requests: '$template',
   },
   personal: {
     birthday: '$timestamp',

package/src/manager/routes/payments/dispute-alert/processors/chargeblast.js

@@ -2,9 +2,9 @@
  * Chargeblast dispute alert processor
  * Normalizes Chargeblast webhook payloads into a standard dispute alert shape
  *
- * Chargeblast sends:
- *   id, card (full number or last4), cardBrand, amount (dollars),
- *   transactionDate ("YYYY-MM-DD HH:MM:SS"), app, processor, alerts
+ * Chargeblast sends two event types:
+ *   alert.created: id, card, cardBrand, amount, transactionDate, processor, etc.
+ *   alert.updated: same + externalOrder (charge ID), metadata (payment intent), customerEmail, etc.
  */
 module.exports = {
   /**
@@ -38,6 +38,15 @@ module.exports = {
       amount: parseFloat(body.amount),
       transactionDate: String(body.transactionDate).split(' ')[0], // date only, no time
       processor: body.processor ? String(body.processor).toLowerCase() : 'stripe',
+      alertType: body.alertType || null,
+      customerEmail: body.customerEmail || null,
+      // Stripe-specific IDs provided by Chargeblast on alert.updated events
+      chargeId: body.externalOrder || null,
+      paymentIntentId: body.metadata || null,
+      stripeUrl: body.externalUrl || null,
+      reasonCode: body.reasonCode || null,
+      subprovider: body.subprovider || null,
+      isRefunded: body.isRefunded || false,
     };
   },
 };