backend-manager 5.0.175 → 5.0.177

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

@@ -1,16 +1,15 @@
-const moment = require('moment');
+const path = require('path');
 const powertools = require('node-powertools');
 
 /**
  * Firestore trigger: payments-disputes/{alertId} onWrite
  *
  * Processes pending dispute alerts:
- * 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
+ * 1. Loads the processor module for the alert's payment processor
+ * 2. Searches for the matching charge via processor.searchAndMatch()
+ * 3. Issues refund + cancels subscription via processor.processDispute()
+ * 4. Sends email alert to brand contact
+ * 5. Updates dispute document with results
  */
 module.exports = async ({ assistant, change, context }) => {
   const Manager = assistant.Manager;
@@ -35,13 +34,16 @@ module.exports = async ({ assistant, change, context }) => {
 
     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.`);
+    // Load the processor module
+    let processorModule;
+    try {
+      processorModule = require(path.resolve(__dirname, `processors/${processor}.js`));
+    } catch (e) {
+      throw new Error(`Unsupported dispute processor: ${processor}`);
     }
 
     // Search for the matching charge
-    const match = await searchAndMatch({ alert, assistant });
+    const match = await processorModule.searchAndMatch(alert, assistant);
 
     // Build timestamps
     const now = powertools.timestamp(new Date(), { output: 'string' });
@@ -80,13 +82,12 @@ module.exports = async ({ assistant, change, context }) => {
     }
 
     // Process refund and cancel
-    const result = await processDispute({ match, alert, assistant });
+    const result = await processorModule.processDispute(match, alert, assistant);
 
     // Update dispute document with results
     await disputeRef.set({
       status: 'resolved',
       match: {
-        method: match.method,
         invoiceId: match.invoiceId || null,
         subscriptionId: match.subscriptionId || null,
         customerId: match.customerId,
@@ -131,253 +132,6 @@ module.exports = async ({ assistant, change, context }) => {
   }
 };
 
-/**
- * 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
- * @param {object} options.assistant - Assistant instance
- * @returns {object|null} Match details or null
- */
-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);
-
-  if (!alertDate.isValid()) {
-    throw new Error(`Invalid transactionDate: ${alert.transactionDate}`);
-  }
-
-  const start = alertDate.clone().subtract(2, 'days').unix();
-  const end = alertDate.clone().add(2, 'days').unix();
-
-  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({
-    limit: 100,
-    query: `created>${start} AND created<${end} AND total:${amountCents}`,
-    expand: ['data.payment_intent.payment_method'],
-  });
-
-  if (!invoices.data.length) {
-    assistant.log(`No invoices found for amount=${amountCents} in date range`);
-    return null;
-  }
-
-  if (invoices.data.length >= 100) {
-    assistant.log(`Warning: 100+ invoices found, results may be truncated`);
-  }
-
-  assistant.log(`Found ${invoices.data.length} invoice(s), matching card last4=${alert.card.last4}`);
-
-  // Loop through invoices and match card last4
-  for (const invoice of invoices.data) {
-    const invoiceLast4 = invoice?.payment_intent?.payment_method?.card?.last4;
-
-    assistant.log(`Checking invoice ${invoice.id}: card last4=${invoiceLast4 || 'unknown'}`);
-
-    if (!invoiceLast4 || invoiceLast4 !== alert.card.last4) {
-      continue;
-    }
-
-    assistant.log(`Matched invoice ${invoice.id}: card last4=${invoiceLast4}`);
-
-    // 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,
-    };
-  }
-
-  assistant.log(`No invoice matched card last4=${alert.card.last4}`);
-  return null;
-}
-
-/**
- * Process refund + cancellation for a matched dispute
- *
- * @param {object} options
- * @param {object} options.match - Match details from searchAndMatch
- * @param {object} options.alert - Normalized alert data
- * @param {object} options.assistant - Assistant instance
- * @returns {object} Result with statuses
- */
-async function processDispute({ match, alert, assistant }) {
-  const StripeLib = require('../../../libraries/payment/processors/stripe.js');
-  const stripe = StripeLib.init();
-
-  const amountCents = Math.round(alert.amount * 100);
-  const result = {
-    refundId: null,
-    amountRefunded: null,
-    currency: null,
-    refundStatus: 'skipped',
-    cancelStatus: 'skipped',
-    errors: [],
-  };
-
-  // Issue full refund
-  if (match.chargeId) {
-    try {
-      const refund = await stripe.refunds.create({
-        charge: match.chargeId,
-        amount: amountCents,
-      });
-
-      result.refundId = refund.id;
-      result.amountRefunded = amountCents;
-      result.currency = refund.currency;
-      result.refundStatus = 'success';
-
-      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 charge ${match.chargeId}: ${e.message}`);
-    }
-  }
-
-  // Cancel subscription immediately
-  // Stripe fires customer.subscription.deleted webhook → existing pipeline handles user doc update
-  if (match.subscriptionId) {
-    try {
-      await stripe.subscriptions.cancel(match.subscriptionId);
-      result.cancelStatus = 'success';
-
-      assistant.log(`Subscription cancelled: sub=${match.subscriptionId}`);
-    } catch (e) {
-      result.cancelStatus = 'failed';
-      result.errors.push(`Cancel failed: ${e.message}`);
-      assistant.error(`Cancel failed for sub ${match.subscriptionId}: ${e.message}`);
-    }
-  }
-
-  return result;
-}
-
 /**
  * Send dispute alert email to brand contact (fire-and-forget)
  *

package/src/manager/events/firestore/payments-disputes/processors/stripe.js

@@ -0,0 +1,213 @@
+const moment = require('moment');
+
+const StripeLib = require('../../../../libraries/payment/processors/stripe.js');
+
+/**
+ * Stripe dispute processor
+ *
+ * Implements the dispute processor interface for Stripe:
+ *   - searchAndMatch(alert, assistant) → match | null
+ *   - processDispute(match, alert, assistant) → result
+ *
+ * Match strategy: search charges by amount + date range, then confirm card last4.
+ * If alert.chargeId is provided (alert.updated events), verify it directly — otherwise
+ * fall back to the charge search. Both paths go through the same resolveMatchFromCharge()
+ * so the returned match shape is always identical.
+ *
+ * We use charges.search() rather than invoices.search() because Stripe invoices can have
+ * a null charge field even when paid (payment applied via credit/balance), making invoice
+ * search unreliable. Charges always have payment_method_details.card.last4.
+ */
+
+/**
+ * Find the Stripe charge matching this dispute alert.
+ *
+ * If alert.chargeId is present (Chargeblast alert.updated), verify it directly.
+ * Otherwise search charges by amount + ±2 day window and match card last4.
+ *
+ * @param {object} alert - Normalized alert data
+ * @param {object} assistant - Assistant instance
+ * @returns {object|null} Match details or null
+ */
+async function searchAndMatch(alert, assistant) {
+  const stripe = StripeLib.init();
+
+  // If Chargeblast already gave us the charge ID, verify it directly
+  if (alert.chargeId && alert.chargeId.startsWith('ch_')) {
+    assistant.log(`Direct charge lookup: ${alert.chargeId}`);
+
+    try {
+      const charge = await stripe.charges.retrieve(alert.chargeId, {
+        expand: ['invoice', 'invoice.subscription', 'customer'],
+      });
+      return resolveMatchFromCharge({ charge, stripe, assistant });
+    } catch (e) {
+      assistant.log(`Direct charge lookup failed for ${alert.chargeId}: ${e.message}`);
+    }
+  }
+
+  // Search charges by amount + date range, match card last4
+  const amountCents = Math.round(alert.amount * 100);
+  const alertDate = moment(alert.transactionDate);
+
+  if (!alertDate.isValid()) {
+    throw new Error(`Invalid transactionDate: ${alert.transactionDate}`);
+  }
+
+  const start = alertDate.clone().subtract(2, 'days').unix();
+  const end = alertDate.clone().add(2, 'days').unix();
+
+  assistant.log(`Searching charges: amount=${amountCents} cents, range=${moment.unix(start).format('YYYY-MM-DD')} to ${moment.unix(end).format('YYYY-MM-DD')}, last4=${alert.card.last4}`);
+
+  const charges = await stripe.charges.search({
+    limit: 100,
+    query: `amount:${amountCents} AND created>${start} AND created<${end}`,
+  });
+
+  if (!charges.data.length) {
+    assistant.log(`No charges found for amount=${amountCents} in date range`);
+    return null;
+  }
+
+  if (charges.data.length >= 100) {
+    assistant.log(`Warning: 100+ charges found, results may be truncated`);
+  }
+
+  assistant.log(`Found ${charges.data.length} charge(s), matching last4=${alert.card.last4}`);
+
+  for (const charge of charges.data) {
+    const chargeLast4 = charge.payment_method_details?.card?.last4;
+
+    if (!chargeLast4 || chargeLast4 !== alert.card.last4) {
+      continue;
+    }
+
+    // Fetch full charge with invoice + subscription expanded
+    try {
+      const fullCharge = await stripe.charges.retrieve(charge.id, {
+        expand: ['invoice', 'invoice.subscription', 'customer'],
+      });
+      return resolveMatchFromCharge({ charge: fullCharge, stripe, assistant });
+    } catch (e) {
+      assistant.log(`Failed to expand charge ${charge.id}: ${e.message}`);
+    }
+  }
+
+  assistant.log(`No charge matched last4=${alert.card.last4}`);
+  return null;
+}
+
+/**
+ * Issue a refund and cancel the subscription for a matched dispute.
+ *
+ * @param {object} match - Match details from searchAndMatch
+ * @param {object} alert - Normalized alert data
+ * @param {object} assistant - Assistant instance
+ * @returns {object} Result with statuses
+ */
+async function processDispute(match, alert, assistant) {
+  const stripe = StripeLib.init();
+
+  const amountCents = Math.round(alert.amount * 100);
+  const result = {
+    refundId: null,
+    amountRefunded: null,
+    currency: null,
+    refundStatus: 'skipped',
+    cancelStatus: 'skipped',
+    errors: [],
+  };
+
+  // Issue full refund
+  if (match.chargeId) {
+    try {
+      const refund = await stripe.refunds.create({
+        charge: match.chargeId,
+        amount: amountCents,
+      });
+
+      result.refundId = refund.id;
+      result.amountRefunded = amountCents;
+      result.currency = refund.currency;
+      result.refundStatus = 'success';
+
+      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 charge ${match.chargeId}: ${e.message}`);
+    }
+  }
+
+  // Cancel subscription immediately
+  // Stripe fires customer.subscription.deleted webhook → existing pipeline handles user doc update
+  if (match.subscriptionId) {
+    try {
+      await stripe.subscriptions.cancel(match.subscriptionId);
+      result.cancelStatus = 'success';
+
+      assistant.log(`Subscription cancelled: sub=${match.subscriptionId}`);
+    } catch (e) {
+      result.cancelStatus = 'failed';
+      result.errors.push(`Cancel failed: ${e.message}`);
+      assistant.error(`Cancel failed for sub ${match.subscriptionId}: ${e.message}`);
+    }
+  }
+
+  return result;
+}
+
+module.exports = { searchAndMatch, processDispute };
+
+// ---
+
+/**
+ * Build a match object from a Stripe charge (with invoice + subscription already expanded).
+ *
+ * @param {object} options.charge - Stripe charge with invoice + customer expanded
+ * @param {object} options.stripe - Stripe SDK instance
+ * @param {object} options.assistant - Assistant instance
+ * @returns {object|null}
+ */
+async function resolveMatchFromCharge({ charge, stripe, assistant }) {
+  if (!charge || charge.status !== 'succeeded') {
+    assistant.log(`Charge ${charge?.id} status=${charge?.status}, skipping`);
+    return null;
+  }
+
+  // Resolve UID + email from customer
+  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 from expanded invoice
+  const invoice = typeof charge.invoice === 'object' ? charge.invoice : null;
+  const invoiceId = invoice?.id || (typeof charge.invoice === 'string' ? charge.invoice : null);
+  const subscriptionId = invoice?.subscription
+    ? (typeof invoice.subscription === 'object' ? invoice.subscription.id : invoice.subscription)
+    : null;
+
+  assistant.log(`Matched charge=${charge.id}, customer=${customerId}, uid=${uid}, invoice=${invoiceId}, subscription=${subscriptionId}`);
+
+  return {
+    chargeId: charge.id,
+    invoiceId: invoiceId,
+    subscriptionId: subscriptionId,
+    customerId: customerId,
+    uid: uid,
+    email: email,
+  };
+}

package/src/manager/events/firestore/payments-webhooks/transitions/send-email.js

@@ -15,22 +15,27 @@ const moment = require('moment');
  * @param {object} options.userDoc - User document data (passed as `to` — email.js extracts email/name and user template data)
  * @param {object} options.assistant - Assistant instance
  */
-function sendOrderEmail({ template, subject, categories, data, userDoc, assistant, copy, sender = 'orders' }) {
+function sendOrderEmail({ template, subject, categories, data, userDoc, assistant, copy, internalOnly, sender = 'orders' }) {
   const email = assistant.Manager.Email(assistant);
   const uid = userDoc?.auth?.uid;
 
-  if (!userDoc?.auth?.email) {
+  if (!internalOnly && !userDoc?.auth?.email) {
     assistant.error(`sendOrderEmail(): No email found for uid=${uid}, skipping`);
     return;
   }
 
+  const brandContact = assistant.Manager.config?.brand?.contact;
+  const to = internalOnly
+    ? { email: brandContact?.email, name: brandContact?.name || assistant.Manager.config?.brand?.name }
+    : userDoc;
+
   email.send({
     sender,
-    to: userDoc,
+    to,
     subject,
     template,
     categories,
-    copy: copy !== false,
+    copy: internalOnly ? false : copy !== false,
     data,
   })
     .then((result) => {

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

@@ -11,6 +11,7 @@ module.exports = async function ({ before, after, order, uid, userDoc, assistant
     template: 'main/order/payment-recovered',
     subject: `Payment received for order #${order?.id || ''}`,
     categories: ['order/payment-recovered'],
+    internalOnly: true,
     userDoc,
     assistant,
     data: {

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

@@ -14,7 +14,7 @@ module.exports = {
    * @returns {object} Normalized dispute alert
    */
   normalize(body) {
-    if (!body.id) {
+    if (!body.id && !body.alertId) {
       throw new Error('Missing required field: id');
     }
     if (!body.card) {
@@ -30,7 +30,7 @@ module.exports = {
     const cardStr = String(body.card);
 
     return {
-      id: String(body.id),
+      id: String(body.id || body.alertId),
       card: {
         last4: cardStr.slice(-4),
         brand: body.cardBrand ? String(body.cardBrand).toLowerCase() : null,