@omega.js/backend 0.1.0

package/dist/manager/events/firestore/notifications/on-write.js

@@ -0,0 +1,123 @@
+const { FieldValue } = require('firebase-admin/firestore');
+const { deliverConversion } = require('../../../libraries/analytics/conversions.js');
+const { buildAttributionContext, buildIdentity } = require('../../../libraries/analytics/match-data.js');
+
+/**
+ * Notification subscription write handler
+ *
+ * Handles create, update, and delete events for notification subscriptions.
+ * Updates stats counters and sends analytics events.
+ */
+module.exports = async ({ Manager, ctx, change, context, libraries }) => {
+  const { admin } = libraries;
+
+  // Shortcuts
+  const dataBefore = change.before.data();
+  const dataAfter = change.after.data();
+
+  // Determine event type
+  let eventType;
+  if (dataAfter === undefined) {
+    eventType = 'delete';
+  } else if (dataBefore && dataAfter) {
+    eventType = 'update';
+  } else if (!dataBefore && dataAfter) {
+    eventType = 'create';
+  }
+
+  // Log
+  ctx.log('Notification subscription write:', {
+    after: dataAfter,
+    before: dataBefore,
+    eventType: eventType,
+    resource: context.resource,
+    params: context.params,
+  });
+
+  // Delete event
+  if (eventType === 'delete') {
+    await admin.firestore().doc('meta/stats')
+      .set({
+        notifications: { total: FieldValue.increment(-1) },
+      }, { merge: true });
+
+    trackNotification({
+      Manager: Manager,
+      ctx: ctx,
+      event: 'notification_unsubscribe',
+      token: context.params.token,
+      data: dataBefore,
+    });
+
+    ctx.log('Notification subscription deleted:', dataBefore);
+
+    return dataBefore;
+  }
+
+  // Update event
+  if (eventType === 'update') {
+    return;
+  }
+
+  // Create event
+  if (eventType === 'create') {
+    await admin.firestore().doc('meta/stats')
+      .set({
+        notifications: { total: FieldValue.increment(1) },
+      }, { merge: true });
+
+    trackNotification({
+      Manager: Manager,
+      ctx: ctx,
+      event: 'notification_subscribe',
+      token: context.params.token,
+      data: dataAfter,
+    });
+
+    ctx.log('Notification subscription created:', dataAfter);
+
+    return dataAfter;
+  }
+};
+
+/**
+ * Fire the canonical subscribe/unsubscribe conversion (non-blocking).
+ *
+ * The handler used to call `Manager.Analytics(...).event()` with hyphenated
+ * names of its own — `notification-subscribe` / `notification-unsubscribe` —
+ * which appear in no catalog, so no other surface could ever say the same
+ * thing. Going through `deliverConversion` buys the three things that raw call
+ * had none of: the catalog's name, the consent gate, and the per-provider walk
+ * (GA4 only here — no ad platform maps a push subscription, and the catalog
+ * says so rather than the caller inventing one).
+ *
+ * THE DEDUPE ID IS `<event>.<token>`. The doc id IS the push token, and it is
+ * the only stable key this doc has: `owner` is null on an anonymous subscribe,
+ * so a uid-derived id would collapse every anonymous device onto one id.
+ *
+ * Fire-and-forget, like every other call site: a subscription is already
+ * written when this runs, and an ad platform must never fail a doc write.
+ *
+ * @param {object} options
+ * @param {object} options.Manager - The backend Manager.
+ * @param {object} options.ctx - The event context.
+ * @param {string} options.event - The canonical event name.
+ * @param {string} options.token - The doc id, which is the push token.
+ * @param {object} [options.data] - The subscription doc this is about.
+ * @returns {void}
+ */
+function trackNotification({ Manager, ctx, event, token, data }) {
+  try {
+    deliverConversion({
+      event: event,
+      attribution: buildAttributionContext(data?.attribution),
+      identity: buildIdentity({ uid: data?.owner }),
+      trackingConsent: data?.trackingConsent,
+      eventId: `${event}.${token}`,
+      ctx: ctx,
+      Manager: Manager,
+    });
+  } catch (e) {
+    ctx.error(`Notification ${event} tracking failed for ${token}:`, e);
+  }
+}

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

@@ -0,0 +1,256 @@
+const path = require('path');
+const loadProvider = require('../../../libraries/load-provider.js');
+const powertools = require('node-powertools');
+const { escapeHtml, safeUrl } = require('../../../libraries/email/constants.js');
+
+/**
+ * Firestore trigger: payments-disputes/{alertId} onWrite
+ *
+ * Processes pending dispute alerts:
+ * 1. Loads the provider module for the alert's payment provider
+ * 2. Searches for the matching charge via provider.searchAndMatch()
+ * 3. Issues refund + cancels subscription via provider.processDispute()
+ * 4. Sends email alert to brand contact
+ * 5. Updates dispute document with results
+ */
+module.exports = async ({ ctx, change, context }) => {
+  const Manager = ctx.Manager;
+  const admin = Manager.libraries.admin;
+
+  const dataAfter = change.after.data();
+
+  // Short-circuit: deleted doc or non-pending status
+  if (!dataAfter || dataAfter.status !== 'pending') {
+    return;
+  }
+
+  const alertId = context.params.alertId;
+  const disputeRef = admin.firestore().doc(`payments-disputes/${alertId}`);
+
+  // Set status to processing
+  await disputeRef.set({ status: 'processing' }, { merge: true });
+
+  try {
+    const alert = dataAfter.alert;
+    const provider = alert.provider || 'stripe';
+
+    ctx.log(`Processing dispute ${alertId}: provider=${provider}, amount=${alert.amount}, card=****${alert.card.last4}, date=${alert.transactionDate}, chargeId=${alert.chargeId || 'none'}, paymentIntentId=${alert.paymentIntentId || 'none'}`);
+
+    // Load the provider module
+    let providerModule;
+    try {
+      providerModule = loadProvider(path.join(__dirname, 'providers'), provider);
+    } catch (e) {
+      throw new Error(`Unsupported dispute provider: ${provider}`);
+    }
+
+    // Search for the matching charge
+    const match = await providerModule.searchAndMatch(alert, ctx);
+
+    // Build timestamps
+    const now = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+    if (!match) {
+      // No matching charge found
+      await disputeRef.set({
+        status: 'no-match',
+        match: null,
+        actions: {
+          refund: 'skipped',
+          cancel: 'skipped',
+          email: 'pending',
+        },
+        metadata: {
+          completed: {
+            timestamp: now,
+            timestampUNIX: nowUNIX,
+          },
+        },
+      }, { merge: true });
+
+      ctx.log(`Dispute ${alertId}: no matching charge found`);
+
+      // Still send email to alert brand about unmatched dispute. No testing-mode
+      // gate — the mailer's own seam captures a testing send instead of delivering
+      // it ([#774](https://github.com/Omega-JS-Stack/omega/issues/774)).
+      const emailStatus = await sendDisputeEmail({ alert, match: null, result: null, alertId, ctx });
+      await disputeRef.set({ actions: { email: emailStatus } }, { merge: true });
+
+      return;
+    }
+
+    // Process refund and cancel
+    const result = await providerModule.processDispute(match, alert, ctx);
+
+    // Update dispute document with results
+    await disputeRef.set({
+      status: 'resolved',
+      match: {
+        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,
+        currency: result.currency || null,
+      },
+      actions: {
+        refund: result.refundStatus,
+        cancel: result.cancelStatus,
+        email: 'pending',
+      },
+      errors: result.errors,
+      metadata: {
+        completed: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+      },
+    }, { merge: true });
+
+    // Send email alert — awaited, because the dispute doc records its outcome. No
+    // testing-mode gate — the mailer's own seam captures a testing send instead of
+    // delivering it ([#774](https://github.com/Omega-JS-Stack/omega/issues/774)).
+    const emailStatus = await sendDisputeEmail({ alert, match, result, alertId, ctx });
+    await disputeRef.set({ actions: { email: emailStatus } }, { merge: true });
+
+    ctx.log(`Dispute ${alertId} resolved: refund=${result.refundStatus}, cancel=${result.cancelStatus}`);
+  } catch (e) {
+    ctx.error(`Dispute ${alertId} failed: ${e.message}`, e);
+
+    await disputeRef.set({
+      status: 'failed',
+      error: e.message || String(e),
+    }, { merge: true });
+  }
+};
+
+/**
+ * Send dispute alert email to brand contact
+ *
+ * Returns the outcome the dispute doc records — the caller must never claim a send
+ * that did not happen, so this resolves rather than throws.
+ *
+ * @param {object} options
+ * @param {object} options.alert - Normalized alert data
+ * @param {object|null} options.match - Match details (null if no match)
+ * @param {object} [options.result] - Processing result (refund/cancel statuses)
+ * @param {string} options.alertId - Dispute alert ID
+ * @param {object} options.ctx - Assistant instance
+ * @returns {Promise<'success'|'failed'|'skipped'>}
+ */
+function sendDisputeEmail({ alert, match, result, alertId, ctx }) {
+  const Manager = ctx.Manager;
+  const email = Manager.Email(ctx);
+  const brandEmail = Manager.config.brand?.contact?.email;
+
+  if (!brandEmail) {
+    ctx.error(`sendDisputeEmail(): No brand.contact.email configured, skipping`);
+    return Promise.resolve('skipped');
+  }
+
+  const matched = match ? 'Matched' : 'Unmatched';
+  const subject = `Dispute Alert: ${matched} — $${alert.amount} on ****${alert.card.last4} [${alertId}]`;
+
+  // The alert body is hand-built markup (trustedContent below), so every value that
+  // came off the dispute webhook or the provider match gets escaped on the way in.
+  const messageLines = [];
+
+  // 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> ${escapeHtml(alertId)}</li>`);
+  messageLines.push(`<li><strong>Type:</strong> ${escapeHtml(alert.alertType || 'N/A')}</li>`);
+  messageLines.push(`<li><strong>Card:</strong> ****${escapeHtml(alert.card.last4)} (${escapeHtml(alert.card.brand || 'unknown')})</li>`);
+  messageLines.push(`<li><strong>Amount:</strong> $${escapeHtml(alert.amount)}</li>`);
+  messageLines.push(`<li><strong>Transaction Date:</strong> ${escapeHtml(alert.transactionDate)}</li>`);
+  messageLines.push(`<li><strong>Provider:</strong> ${escapeHtml(alert.provider)}</li>`);
+  messageLines.push(`<li><strong>Reason:</strong> ${escapeHtml(alert.reasonCode || 'N/A')}</li>`);
+  messageLines.push(`<li><strong>Network:</strong> ${escapeHtml(alert.subprovider || 'N/A')}</li>`);
+  messageLines.push(`<li><strong>Customer Email:</strong> ${escapeHtml(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> ${escapeHtml(match.method)}</li>`);
+    messageLines.push(`<li><strong>Charge:</strong> ${escapeHtml(match.chargeId || 'N/A')}</li>`);
+    messageLines.push(`<li><strong>Invoice:</strong> ${escapeHtml(match.invoiceId || 'N/A')}</li>`);
+    messageLines.push(`<li><strong>Subscription:</strong> ${escapeHtml(match.subscriptionId || 'N/A')}</li>`);
+    messageLines.push(`<li><strong>Customer:</strong> ${escapeHtml(match.customerId || 'N/A')}</li>`);
+    messageLines.push(`<li><strong>Customer Email:</strong> ${escapeHtml(match.email || 'N/A')}</li>`);
+    messageLines.push(`<li><strong>UID:</strong> ${escapeHtml(match.uid || 'unknown')}</li>`);
+    messageLines.push('</ul>');
+
+    if (result) {
+      messageLines.push('<strong>Actions Taken:</strong>');
+      messageLines.push('<ul>');
+      messageLines.push(`<li><strong>Refund:</strong> ${escapeHtml(result.refundStatus)}${result.refundId ? ` (${escapeHtml(result.refundId)})` : ''}${result.amountRefunded ? ` — $${(result.amountRefunded / 100).toFixed(2)} ${escapeHtml(result.currency || '')}` : ''}</li>`);
+      messageLines.push(`<li><strong>Cancel Subscription:</strong> ${escapeHtml(result.cancelStatus)}</li>`);
+      messageLines.push('</ul>');
+    }
+  }
+
+  // Stripe link
+  if (alert.stripeUrl) {
+    messageLines.push(`<br><a href="${safeUrl(alert.stripeUrl)}">View in Stripe Dashboard</a>`);
+  }
+
+  // Errors
+  if (result?.errors?.length) {
+    messageLines.push('');
+    messageLines.push('<strong>Errors:</strong>');
+    messageLines.push('<ul>');
+    result.errors.forEach((err) => {
+      messageLines.push(`<li>${escapeHtml(err)}</li>`);
+    });
+    messageLines.push('</ul>');
+  }
+
+  return email.send({
+    sender: 'internal',
+    to: brandEmail,
+    subject: subject,
+    template: 'card',
+    categories: ['order/dispute-alert'],
+    copy: true,
+    // Body is first-party markup built above; its third-party values are escaped.
+    trustedContent: true,
+    data: {
+      email: {
+        preview: `Dispute Alert: ${matched} — $${alert.amount} on ****${alert.card.last4}`,
+      },
+      content: {
+        title: `Dispute Alert: ${matched}`,
+        message: messageLines.join('\n'),
+      },
+    },
+  })
+    .then((r) => {
+      ctx.log(`sendDisputeEmail(): Success alertId=${alertId}`);
+      return 'success';
+    })
+    .catch((e) => {
+      ctx.error(`sendDisputeEmail(): Failed alertId=${alertId}: ${e.message}`);
+      return 'failed';
+    });
+}
+
+// Exported for testing
+module.exports.sendDisputeEmail = sendDisputeEmail;

package/dist/manager/events/firestore/payments-disputes/providers/stripe.js

@@ -0,0 +1,218 @@
+const moment = require('moment');
+
+const StripeLib = require('../../../../libraries/payment/providers/stripe.js');
+
+/**
+ * Stripe dispute provider
+ *
+ * Implements the dispute provider interface for Stripe:
+ *   - searchAndMatch(alert, ctx) → match | null
+ *   - processDispute(match, alert, ctx) → 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} ctx - Assistant instance
+ * @returns {object|null} Match details or null
+ */
+async function searchAndMatch(alert, ctx) {
+  const stripe = StripeLib.init();
+
+  // If Chargeblast already gave us the charge ID, verify it directly
+  if (alert.chargeId && alert.chargeId.startsWith('ch_')) {
+    ctx.log(`Direct charge lookup: ${alert.chargeId}`);
+
+    try {
+      const charge = await stripe.charges.retrieve(alert.chargeId, {
+        expand: ['invoice', 'invoice.subscription', 'customer'],
+      });
+      return resolveMatchFromCharge({ charge, stripe, ctx });
+    } catch (e) {
+      ctx.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();
+
+  ctx.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) {
+    ctx.log(`No charges found for amount=${amountCents} in date range`);
+    return null;
+  }
+
+  if (charges.data.length >= 100) {
+    ctx.log(`Warning: 100+ charges found, results may be truncated`);
+  }
+
+  ctx.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, ctx });
+    } catch (e) {
+      ctx.log(`Failed to expand charge ${charge.id}: ${e.message}`);
+    }
+  }
+
+  ctx.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} ctx - Assistant instance
+ * @returns {object} Result with statuses
+ */
+async function processDispute(match, alert, ctx) {
+  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 {
+      // Idempotency key scoped to the charge prevents double-refund when the
+      // Firestore trigger fires more than once (retries, re-delivered webhooks,
+      // etc.). Stripe caches the response for 24 hours.
+      const refund = await stripe.refunds.create({
+        charge: match.chargeId,
+        amount: amountCents,
+      }, {
+        idempotencyKey: `omega-dispute-refund-${match.chargeId}`,
+      });
+
+      result.refundId = refund.id;
+      result.amountRefunded = amountCents;
+      result.currency = refund.currency;
+      result.refundStatus = 'success';
+
+      ctx.log(`Refund success: refundId=${refund.id}, amount=${amountCents}, charge=${match.chargeId}`);
+    } catch (e) {
+      result.refundStatus = 'failed';
+      result.errors.push(`Refund failed: ${e.message}`);
+      ctx.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';
+
+      ctx.log(`Subscription cancelled: sub=${match.subscriptionId}`);
+    } catch (e) {
+      result.cancelStatus = 'failed';
+      result.errors.push(`Cancel failed: ${e.message}`);
+      ctx.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.ctx - Assistant instance
+ * @returns {object|null}
+ */
+async function resolveMatchFromCharge({ charge, stripe, ctx }) {
+  if (!charge || charge.status !== 'succeeded') {
+    ctx.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) {
+      ctx.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;
+
+  ctx.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,
+  };
+}