backend-manager 5.0.113 → 5.0.114

package/package.json

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

package/src/manager/cron/daily/expire-paypal-cancellations.js

@@ -0,0 +1,104 @@
+const powertools = require('node-powertools');
+
+/**
+ * Expire PayPal pending cancellations
+ *
+ * PayPal has no cancel_at_period_end like Stripe — cancellation is immediate on PayPal's side.
+ * BEM keeps users active with cancellation.pending=true until the billing period ends.
+ * Since PayPal does NOT fire a webhook at period end, this cron job transitions those
+ * users to 'cancelled' status once their paid period has expired.
+ *
+ * Flow:
+ * 1. Query users with PayPal subscriptions where cancellation.pending=true
+ * 2. Check if subscription.expires.timestampUNIX < now
+ * 3. Update status to 'cancelled' and cancellation.pending to false
+ * 4. Dispatch 'subscription-cancelled' transition (sends email)
+ */
+module.exports = async ({ Manager, assistant, context, libraries }) => {
+  const { admin } = libraries;
+  const transitions = require('../../events/firestore/payments-webhooks/transitions/index.js');
+
+  const now = new Date();
+  const nowStr = powertools.timestamp(now, { output: 'string' });
+  const nowUNIX = powertools.timestamp(nowStr, { output: 'unix' });
+
+  assistant.log('Checking for expired PayPal pending cancellations...');
+
+  let processed = 0;
+  let skipped = 0;
+
+  await Manager.Utilities().iterateCollection(async (batch, index) => {
+    for (const doc of batch.docs) {
+      const data = doc.data();
+      const sub = data.subscription;
+      const uid = doc.id;
+
+      // Double-check: skip if expires is in the future
+      if (!sub?.expires?.timestampUNIX || sub.expires.timestampUNIX > nowUNIX) {
+        assistant.log(`[skip] ${uid}: expires=${sub?.expires?.timestamp || 'null'} is still in the future (now=${nowStr})`);
+        skipped++;
+        continue;
+      }
+
+      assistant.log(`[expire] ${uid}: expires=${sub.expires.timestamp}, product=${sub.product?.id}, processor=${sub.payment?.processor}, orderId=${sub.payment?.orderId || 'null'}`);
+
+      // Snapshot the before state for transition detection
+      const before = { ...sub };
+
+      // Build the after state — transition to cancelled
+      const after = {
+        ...sub,
+        status: 'cancelled',
+        cancellation: {
+          ...sub.cancellation,
+          pending: false,
+        },
+      };
+
+      // Write to Firestore
+      await doc.ref.set({ subscription: after }, { merge: true });
+
+      assistant.log(`[expire] ${uid}: Updated status=cancelled, cancellation.pending=false`);
+
+      // Detect and dispatch transition (should fire 'subscription-cancelled')
+      const transitionName = transitions.detectTransition('subscription', before, after, null);
+
+      if (transitionName) {
+        assistant.log(`[expire] ${uid}: Transition detected: subscription/${transitionName}`);
+
+        // Build minimal order context for the handler
+        const order = {
+          id: sub.payment?.orderId || null,
+          type: 'subscription',
+          owner: uid,
+          processor: 'paypal',
+          resourceId: sub.payment?.resourceId || null,
+          unified: after,
+        };
+
+        transitions.dispatch(transitionName, 'subscription', {
+          before,
+          after,
+          order,
+          uid,
+          userDoc: data,
+          assistant,
+        });
+      } else {
+        assistant.log(`[expire] ${uid}: No transition detected (before.status=${before.status}, after.status=${after.status})`);
+      }
+
+      processed++;
+    }
+  }, {
+    collection: 'users',
+    where: [
+      { field: 'subscription.payment.processor', operator: '==', value: 'paypal' },
+      { field: 'subscription.cancellation.pending', operator: '==', value: true },
+    ],
+    batchSize: 5000,
+    log: true,
+  });
+
+  assistant.log(`Completed! Processed=${processed}, Skipped=${skipped}`);
+};

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

@@ -36,7 +36,7 @@ module.exports = async ({ assistant, change, context }) => {
 
   try {
     const processor = dataAfter.processor;
-    const uid = dataAfter.owner;
+    let uid = dataAfter.owner;
     const raw = dataAfter.raw;
     const eventType = dataAfter.event?.type;
     const category = dataAfter.event?.category;
@@ -45,11 +45,6 @@ module.exports = async ({ assistant, change, context }) => {
 
     assistant.log(`Processing webhook ${eventId}: processor=${processor}, eventType=${eventType}, category=${category}, resourceType=${resourceType}, resourceId=${resourceId}, uid=${uid || 'null'}`);
 
-    // Validate UID
-    if (!uid) {
-      throw new Error('Webhook event has no UID — cannot process');
-    }
-
     // Validate category
     if (!category) {
       throw new Error(`Webhook event has no category — cannot process`);
@@ -70,6 +65,24 @@ module.exports = async ({ assistant, change, context }) => {
 
     assistant.log(`Fetched resource: type=${resourceType}, id=${resourceId}, status=${resource.status || 'unknown'}`);
 
+    // Resolve UID from the fetched resource if not available from webhook parse
+    // This handles events like PAYMENT.SALE where the Sale object doesn't carry custom_id
+    // but the parent subscription (fetched via fetchResource) does
+    if (!uid && library.getUid) {
+      uid = library.getUid(resource);
+      assistant.log(`UID resolved from fetched resource: uid=${uid || 'null'}, processor=${processor}, resourceType=${resourceType}`);
+
+      // Update the webhook doc with the resolved UID so it's persisted for debugging
+      if (uid) {
+        await webhookRef.set({ owner: uid }, { merge: true });
+      }
+    }
+
+    // Validate UID — must have one by now (either from webhook parse or fetched resource)
+    if (!uid) {
+      throw new Error(`Webhook event has no UID — could not extract from webhook parse or fetched ${resourceType} resource`);
+    }
+
     // Build timestamps
     const now = powertools.timestamp(new Date(), { output: 'string' });
     const nowUNIX = powertools.timestamp(now, { output: 'unix' });
@@ -83,7 +96,7 @@ module.exports = async ({ assistant, change, context }) => {
       throw new Error(`Unknown event category: ${category}`);
     }
 
-    const transitionName = await processPaymentEvent({ category, library, resource, resourceType, uid, processor, eventType, eventId, resourceId, orderId, now, nowUNIX, webhookReceivedUNIX, assistant });
+    const transitionName = await processPaymentEvent({ category, library, resource, resourceType, uid, processor, eventType, eventId, resourceId, orderId, now, nowUNIX, webhookReceivedUNIX, assistant, raw });
 
     // Mark webhook as completed (include transition name for auditing/testing)
     await webhookRef.set({
@@ -138,7 +151,7 @@ module.exports = async ({ assistant, change, context }) => {
  * 6. Track analytics (non-blocking)
  * 7. Write to Firestore (user doc for subscriptions + payments-orders)
  */
-async function processPaymentEvent({ category, library, resource, resourceType, uid, processor, eventType, eventId, resourceId, orderId, now, nowUNIX, webhookReceivedUNIX, assistant }) {
+async function processPaymentEvent({ category, library, resource, resourceType, uid, processor, eventType, eventId, resourceId, orderId, now, nowUNIX, webhookReceivedUNIX, assistant, raw }) {
   const Manager = assistant.Manager;
   const admin = Manager.libraries.admin;
   const isSubscription = category === 'subscription';
@@ -215,8 +228,13 @@ async function processPaymentEvent({ category, library, resource, resourceType,
     assistant.log(`Transition detected: ${category}/${transitionName} (before.status=${before?.status || 'null'}, after.status=${unified.status})`);
 
     if (shouldRunHandlers) {
+      // Extract unified refund details from the processor library (keeps handlers processor-agnostic)
+      const refundDetails = (transitionName === 'payment-refunded' && library.getRefundDetails)
+        ? library.getRefundDetails(raw)
+        : null;
+
       transitions.dispatch(transitionName, category, {
-        before, after: unified, order, uid, userDoc: userData, assistant,
+        before, after: unified, order, uid, userDoc: userData, assistant, refundDetails,
       });
     } else {
       assistant.log(`Transition handler skipped (testing mode): ${category}/${transitionName}`);

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

@@ -18,7 +18,7 @@ const path = require('path');
  */
 function detectTransition(category, before, after, eventType) {
   if (category === 'subscription') {
-    return detectSubscriptionTransition(before, after);
+    return detectSubscriptionTransition(before, after, eventType);
   }
 
   if (category === 'one-time') {
@@ -37,11 +37,18 @@ function detectTransition(category, before, after, eventType) {
  * @param {object} after - New unified subscription
  * @returns {string|null} Transition name
  */
-function detectSubscriptionTransition(before, after) {
+function detectSubscriptionTransition(before, after, eventType) {
   if (!after) {
     return null;
   }
 
+  // Refund events take priority — detected by webhook event type rather than state diff
+  // because the subscription state may not change meaningfully during a refund
+  const refundEvents = ['PAYMENT.SALE.REFUNDED', 'charge.refunded'];
+  if (refundEvents.includes(eventType)) {
+    return 'payment-refunded';
+  }
+
   const beforeStatus = before?.status;
   const afterStatus = after.status;
 

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

@@ -0,0 +1,34 @@
+/**
+ * Transition: payment-refunded
+ * Triggered when a payment refund webhook is received.
+ *
+ * Processor-agnostic — refund details are extracted by the processor library's
+ * getRefundDetails() method and passed as a unified { amount, currency, reason } object.
+ *
+ * This is webhook-driven so it fires regardless of how the refund originated
+ * (admin dashboard, user self-service, or direct processor action).
+ */
+const { sendOrderEmail, formatDate } = require('../send-email.js');
+
+module.exports = async function ({ before, after, order, uid, userDoc, assistant, refundDetails }) {
+  assistant.log(`Transition [subscription/payment-refunded]: uid=${uid}, product=${after?.product?.id}, amount=${refundDetails?.amount} ${refundDetails?.currency}, reason=${refundDetails?.reason || 'none'}`);
+
+  sendOrderEmail({
+    template: 'main/order/refunded',
+    subject: `Your payment has been refunded #${order?.id || ''}`,
+    categories: ['order/refunded'],
+    userDoc,
+    assistant,
+    data: {
+      order: {
+        ...order,
+        _computed: {
+          date: formatDate(new Date().toISOString()),
+          refundAmount: refundDetails?.amount || null,
+          refundCurrency: refundDetails?.currency || 'USD',
+          refundReason: refundDetails?.reason || null,
+        },
+      },
+    },
+  });
+};

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

@@ -358,6 +358,35 @@ const PayPal = {
     return customData.orderId || null;
   },
 
+  /**
+   * Extract the UID from a PayPal resource's custom_id
+   * Used to resolve UID after fetchResource() for events like PAYMENT.SALE
+   * where the initial webhook payload doesn't carry custom_id
+   *
+   * @param {object} resource - Raw PayPal resource (subscription or order)
+   * @returns {string|null}
+   */
+  getUid(resource) {
+    const purchaseCustomId = resource.purchase_units?.[0]?.custom_id;
+    const customData = parseCustomId(purchaseCustomId || resource.custom_id);
+    return customData?.uid || null;
+  },
+
+  /**
+   * Extract refund details from a PayPal PAYMENT.SALE.REFUNDED webhook payload
+   * Returns a unified shape so transition handlers stay processor-agnostic
+   *
+   * @param {object} raw - Raw PayPal webhook payload
+   * @returns {{ amount: string|null, currency: string, reason: string|null }}
+   */
+  getRefundDetails(raw) {
+    return {
+      amount: raw?.resource?.amount?.total || raw?.resource?.total_refunded_amount?.value || null,
+      currency: raw?.resource?.amount?.currency || 'USD',
+      reason: raw?.resource?.reason_code || null,
+    };
+  },
+
   /**
    * Build the custom_id string for PayPal subscriptions and orders
    * Format: uid:{uid},orderId:{orderId} or uid:{uid},orderId:{orderId},productId:{productId}
@@ -408,6 +437,44 @@ function parseCustomId(customId) {
   return result;
 }
 
+/**
+ * Calculate when the current billing period ends based on last payment + interval
+ * Used for cancelled subs to determine remaining access time
+ *
+ * @param {object} raw - Raw PayPal subscription (with _plan attached)
+ * @returns {Date|null} Period end date, or null if cannot be calculated
+ */
+function calculatePeriodEnd(raw) {
+  const lastPayment = raw.billing_info?.last_payment?.time;
+
+  if (!lastPayment) {
+    return null;
+  }
+
+  const plan = raw._plan;
+  const regularCycle = plan?.billing_cycles?.find(c => c.tenure_type === 'REGULAR');
+
+  if (!regularCycle) {
+    return null;
+  }
+
+  const unit = regularCycle.frequency.interval_unit;
+  const count = regularCycle.frequency.interval_count || 1;
+  const lastDate = new Date(lastPayment);
+
+  if (unit === 'YEAR') {
+    lastDate.setFullYear(lastDate.getFullYear() + count);
+  } else if (unit === 'MONTH') {
+    lastDate.setMonth(lastDate.getMonth() + count);
+  } else if (unit === 'WEEK') {
+    lastDate.setDate(lastDate.getDate() + (count * 7));
+  } else if (unit === 'DAY') {
+    lastDate.setDate(lastDate.getDate() + count);
+  }
+
+  return lastDate;
+}
+
 /**
  * Map PayPal subscription status to unified status
  *
@@ -415,7 +482,8 @@ function parseCustomId(customId) {
  * |------------------|----------------|
  * | ACTIVE           | active         |
  * | SUSPENDED        | suspended      |
- * | CANCELLED        | cancelled      |
+ * | CANCELLED (period remaining) | active (with cancellation.pending) |
+ * | CANCELLED (period ended)     | cancelled      |
  * | EXPIRED          | cancelled      |
  * | APPROVAL_PENDING | cancelled      |
  * | APPROVED         | active         |
@@ -431,17 +499,47 @@ function resolveStatus(raw) {
     return 'suspended';
   }
 
-  // CANCELLED, EXPIRED, APPROVAL_PENDING, or anything else
+  // CANCELLED — check if user still has paid time remaining
+  if (status === 'CANCELLED') {
+    const periodEnd = calculatePeriodEnd(raw);
+
+    if (periodEnd && periodEnd > new Date()) {
+      // User still has access until period end — treat as active with pending cancellation
+      return 'active';
+    }
+
+    return 'cancelled';
+  }
+
+  // EXPIRED, APPROVAL_PENDING, or anything else
   return 'cancelled';
 }
 
 /**
  * Resolve cancellation state from PayPal subscription
+ *
+ * PayPal has no cancel_at_period_end like Stripe. When cancelled:
+ * - If billing period hasn't ended: pending=true, date=period end (user keeps access)
+ * - If billing period has ended: pending=false, date=cancellation time (fully cancelled)
  */
 function resolveCancellation(raw) {
   if (raw.status === 'CANCELLED') {
-    // PayPal doesn't give a specific cancellation date on the sub itself
-    // Use status_update_time if available
+    const periodEnd = calculatePeriodEnd(raw);
+
+    // Period still active — pending cancellation (user keeps access until period end)
+    if (periodEnd && periodEnd > new Date()) {
+      const periodEndStr = powertools.timestamp(periodEnd, { output: 'string' });
+
+      return {
+        pending: true,
+        date: {
+          timestamp: periodEndStr,
+          timestampUNIX: powertools.timestamp(periodEndStr, { output: 'unix' }),
+        },
+      };
+    }
+
+    // Period has ended — fully cancelled
     const cancelDate = raw.status_update_time
       ? powertools.timestamp(new Date(raw.status_update_time), { output: 'string' })
       : EPOCH_ZERO;
@@ -542,6 +640,7 @@ function resolveFrequency(raw) {
 /**
  * Resolve product by matching the PayPal product ID against config products
  * Uses: sub._plan.product_id → match config product.paypal.productId
+ * Also checks paypal.legacyProductIds[] for migrated products
  */
 function resolveProduct(raw, config) {
   // Get PayPal product ID from the plan (attached during fetchResource)
@@ -552,9 +651,15 @@ function resolveProduct(raw, config) {
   }
 
   for (const product of config.payment.products) {
+    // Check current product ID
     if (product.paypal?.productId === paypalProductId) {
       return { id: product.id, name: product.name || product.id };
     }
+
+    // Check legacy product IDs (for migrated products)
+    if (product.paypal?.legacyProductIds?.includes(paypalProductId)) {
+      return { id: product.id, name: product.name || product.id };
+    }
   }
 
   return { id: 'basic', name: 'Basic' };
@@ -579,9 +684,26 @@ function resolveProductOneTime(productId, config) {
 
 /**
  * Resolve subscription expiration from PayPal data
+ *
+ * For cancelled subs with remaining time, uses calculated period end.
+ * For active subs, uses next_billing_time.
  */
 function resolveExpires(raw) {
-  // PayPal's billing_info.next_billing_time is the closest to "period end"
+  // Cancelled subs with remaining time — use calculated period end
+  if (raw.status === 'CANCELLED') {
+    const periodEnd = calculatePeriodEnd(raw);
+
+    if (periodEnd && periodEnd > new Date()) {
+      const expiresStr = powertools.timestamp(periodEnd, { output: 'string' });
+
+      return {
+        timestamp: expiresStr,
+        timestampUNIX: powertools.timestamp(expiresStr, { output: 'unix' }),
+      };
+    }
+  }
+
+  // Active subs: PayPal's billing_info.next_billing_time is the closest to "period end"
   const nextBilling = raw.billing_info?.next_billing_time;
 
   if (!nextBilling) {

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

@@ -82,6 +82,36 @@ const Stripe = {
     return resource.metadata?.orderId || null;
   },
 
+  /**
+   * Extract the UID from a Stripe resource's metadata
+   * Used to resolve UID after fetchResource() for parity with PayPal
+   *
+   * @param {object} resource - Raw Stripe resource (subscription, session, invoice)
+   * @returns {string|null}
+   */
+  getUid(resource) {
+    return resource.metadata?.uid || null;
+  },
+
+  /**
+   * Extract refund details from a Stripe charge.refunded webhook payload
+   * Returns a unified shape so transition handlers stay processor-agnostic
+   *
+   * @param {object} raw - Raw Stripe webhook payload
+   * @returns {{ amount: string|null, currency: string, reason: string|null }}
+   */
+  getRefundDetails(raw) {
+    const charge = raw?.data?.object;
+    const amountCents = charge?.amount_refunded;
+    const latestRefund = charge?.refunds?.data?.[0];
+
+    return {
+      amount: amountCents ? (amountCents / 100).toFixed(2) : null,
+      currency: charge?.currency?.toUpperCase() || 'USD',
+      reason: latestRefund?.reason || null,
+    };
+  },
+
   /**
    * Transform a raw Stripe subscription object into the unified subscription shape
    * This produces the exact same object stored in users/{uid}.subscription

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

@@ -21,12 +21,17 @@ const Test = {
    * from Firestore instead of returning mismatched data.
    */
   async fetchResource(resourceType, resourceId, rawFallback, context) {
-    // If the fallback matches the requested type, return it directly
-    if (rawFallback?.object === resourceType) {
+    // If the fallback matches the requested type AND has a UID, return it directly
+    // When UID is missing (e.g., PAYMENT.SALE events), fall through to Firestore lookup
+    // so we can reconstruct a resource with the UID from the order's owner field
+    const fallbackHasUid = rawFallback?.metadata?.uid;
+    if (rawFallback?.object === resourceType && fallbackHasUid) {
       return rawFallback;
     }
 
-    // Fallback doesn't match — try to look up the resource from payments-orders
+    // Look up the existing resource from payments-orders in Firestore
+    // This simulates what a real API call (Stripe/PayPal) would return — a resource
+    // with the full metadata including UID
     const admin = context?.admin;
     if (admin && resourceId) {
       const snapshot = await admin.firestore()
@@ -40,7 +45,15 @@ const Test = {
         // payments-orders stores the unified subscription inside .unified
         // Reconstruct a Stripe-shaped object from the unified data for toUnifiedSubscription()
         if (resourceType === 'subscription' && data.unified) {
-          return buildStripeSubscriptionFromUnified(data.unified, resourceId, context?.eventType, context?.config);
+          const reconstructed = buildStripeSubscriptionFromUnified(data.unified, resourceId, context?.eventType, context?.config, data.owner);
+
+          // If the fallback matched the type but lacked UID, overlay the webhook's new state
+          // onto the reconstructed resource, but keep the reconstructed metadata (has uid)
+          if (rawFallback?.object === resourceType) {
+            return { ...rawFallback, metadata: { ...rawFallback.metadata, ...reconstructed.metadata } };
+          }
+
+          return reconstructed;
         }
       }
     }
@@ -56,6 +69,20 @@ const Test = {
     return Stripe.getOrderId(resource);
   },
 
+  /**
+   * Extract UID — delegates to Stripe (test processor uses Stripe-shaped data)
+   */
+  getUid(resource) {
+    return Stripe.getUid(resource);
+  },
+
+  /**
+   * Extract refund details — delegates to Stripe (test processor uses Stripe-shaped data)
+   */
+  getRefundDetails(raw) {
+    return Stripe.getRefundDetails(raw);
+  },
+
   /**
    * Transform raw subscription into unified shape
    * Delegates to Stripe's toUnifiedSubscription (same data shape), stamps processor as 'test'
@@ -87,7 +114,7 @@ module.exports = Test;
  * The unified → Stripe mapping must produce data that toUnifiedSubscription() can process correctly.
  * For payment failure events, we override the status to past_due so it maps to 'suspended'.
  */
-function buildStripeSubscriptionFromUnified(unified, resourceId, eventType, config) {
+function buildStripeSubscriptionFromUnified(unified, resourceId, eventType, config, ownerUid) {
   // Map unified status back to a Stripe status
   const STATUS_MAP = {
     active: 'active',
@@ -120,7 +147,7 @@ function buildStripeSubscriptionFromUnified(unified, resourceId, eventType, conf
     id: resourceId,
     object: 'subscription',
     status: status,
-    metadata: { orderId: unified.payment?.orderId || null },
+    metadata: { orderId: unified.payment?.orderId || null, uid: ownerUid || null },
     plan: {
       product: stripeProductId,
       interval: INTERVAL_MAP[frequency] || 'month',

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

@@ -20,6 +20,9 @@ const SUPPORTED_EVENTS = new Set([
 
   // Checkout completion (could be subscription or one-time)
   'checkout.session.completed',
+
+  // Refunds
+  'charge.refunded',
 ]);
 
 module.exports = {
@@ -101,6 +104,30 @@ module.exports = {
         resourceId = dataObject.id;
         uid = dataObject.metadata?.uid || null;
       }
+
+    } else if (eventType === 'charge.refunded') {
+      // Refund event — the charge object contains an invoice ID which links to a subscription
+      const invoiceId = dataObject.invoice;
+      const subscriptionId = dataObject.subscription
+        || dataObject.metadata?.subscriptionId
+        || null;
+
+      if (subscriptionId) {
+        // Subscription-related refund
+        category = 'subscription';
+        resourceType = 'subscription';
+        resourceId = subscriptionId;
+      } else if (invoiceId) {
+        // Has invoice — likely subscription-related, will resolve via fetchResource
+        category = 'subscription';
+        resourceType = 'invoice';
+        resourceId = invoiceId;
+      } else {
+        // One-time payment refund — skip for now (no subscription to update)
+        category = null;
+      }
+
+      uid = dataObject.metadata?.uid || null;
     }
 
     return {

package/src/test/test-accounts.js

@@ -340,6 +340,36 @@ const JOURNEY_ACCOUNTS = {
       subscription: { product: { id: 'basic' }, status: 'active' },
     },
   },
+  // Journey: refund webhook transition (charge.refunded fires payment-refunded transition)
+  'journey-payments-refund-webhook': {
+    id: 'journey-payments-refund-webhook',
+    uid: '_test-journey-payments-refund-webhook',
+    email: '_test.journey-payments-refund-webhook@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' },
+    },
+  },
+  // Journey: UID resolution fallback (webhook without uid in metadata, resolved from fetched resource)
+  'journey-payments-uid-resolution': {
+    id: 'journey-payments-uid-resolution',
+    uid: '_test-journey-payments-uid-resolution',
+    email: '_test.journey-payments-uid-resolution@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' },
+    },
+  },
+  // Journey: legacy product ID resolution (webhook with legacy product ID maps to correct product)
+  'journey-payments-legacy-product': {
+    id: 'journey-payments-legacy-product',
+    uid: '_test-journey-payments-legacy-product',
+    email: '_test.journey-payments-legacy-product@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' },
+    },
+  },
 };
 
 /**

package/test/events/payments/journey-payments-legacy-product.js

@@ -0,0 +1,149 @@
+/**
+ * Test: Payment Journey - Legacy Product ID Resolution
+ * Simulates: webhook with a legacy Stripe product ID → resolves to the correct product
+ *
+ * Verifies Fix 4: when an existing subscriber's webhook carries a legacy product ID
+ * (from before product migration), resolveProduct() checks stripe.legacyProductIds[]
+ * and maps it to the correct current product.
+ *
+ * Flow:
+ * 1. Find a config product that has stripe.legacyProductIds (skip if none)
+ * 2. Send a customer.subscription.created webhook with the legacy product ID in plan.product
+ * 3. Verify: subscription.product.id resolves to the correct (current) product ID
+ *
+ * This test is config-dependent — it requires at least one product with legacyProductIds.
+ * If no such product exists, the test skips gracefully.
+ */
+module.exports = {
+  description: 'Payment journey: webhook with legacy product ID → correct product resolution',
+  type: 'suite',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'find-product-with-legacy-ids',
+      async run({ accounts, assert, state, config }) {
+        const uid = accounts['journey-payments-legacy-product'].uid;
+        state.uid = uid;
+
+        // Find a paid product that has legacy Stripe product IDs configured
+        const productWithLegacy = config.payment?.products?.find(
+          p => p.id !== 'basic'
+            && p.prices?.monthly
+            && p.stripe?.legacyProductIds?.length > 0,
+        );
+
+        if (!productWithLegacy) {
+          state.skip = true;
+          console.log('No product with stripe.legacyProductIds found in config — skipping legacy product ID test');
+          return;
+        }
+
+        state.skip = false;
+        state.productId = productWithLegacy.id;
+        state.productName = productWithLegacy.name;
+        state.currentStripeProductId = productWithLegacy.stripe.productId;
+        state.legacyStripeProductId = productWithLegacy.stripe.legacyProductIds[0];
+
+        assert.ok(state.legacyStripeProductId, 'Legacy product ID should exist');
+        assert.notEqual(state.legacyStripeProductId, state.currentStripeProductId, 'Legacy ID should differ from current ID');
+      },
+    },
+
+    {
+      name: 'send-webhook-with-legacy-product-id',
+      async run({ http, assert, state, config }) {
+        if (state.skip) {
+          return;
+        }
+
+        const futureDate = new Date();
+        futureDate.setMonth(futureDate.getMonth() + 1);
+
+        state.legacyEventId = `_test-evt-journey-legacy-prod-${Date.now()}`;
+        state.subscriptionId = `sub_test_legacy_${Date.now()}`;
+
+        // Send a subscription created webhook with the LEGACY product ID
+        // This simulates an existing subscriber whose Stripe subscription still
+        // references the old product ID from before migration
+        const response = await http.as('none').post(`payments/webhook?processor=test&key=${config.backendManagerKey}`, {
+          id: state.legacyEventId,
+          type: 'customer.subscription.created',
+          data: {
+            object: {
+              id: state.subscriptionId,
+              object: 'subscription',
+              status: 'active',
+              metadata: { uid: state.uid },
+              cancel_at_period_end: false,
+              canceled_at: null,
+              current_period_end: Math.floor(futureDate.getTime() / 1000),
+              current_period_start: Math.floor(Date.now() / 1000),
+              start_date: Math.floor(Date.now() / 1000),
+              trial_start: null,
+              trial_end: null,
+              // KEY: use the LEGACY product ID, not the current one
+              plan: { product: state.legacyStripeProductId, interval: 'month' },
+            },
+          },
+        });
+
+        assert.isSuccess(response, 'Webhook with legacy product ID should be accepted');
+      },
+    },
+
+    {
+      name: 'legacy-product-resolved-correctly',
+      async run({ firestore, assert, state, waitFor }) {
+        if (state.skip) {
+          return;
+        }
+
+        // Wait for webhook to complete
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.legacyEventId}`);
+          return doc?.status === 'completed' || doc?.status === 'failed';
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.legacyEventId}`);
+        assert.equal(webhookDoc.status, 'completed', 'Webhook should complete successfully');
+        assert.equal(webhookDoc.transition, 'new-subscription', 'Transition should be new-subscription');
+
+        // Core assertion: the legacy product ID resolved to the correct current product
+        const userDoc = await firestore.get(`users/${state.uid}`);
+        assert.equal(
+          userDoc.subscription.product.id,
+          state.productId,
+          `Legacy product ID "${state.legacyStripeProductId}" should resolve to "${state.productId}" (not "basic")`,
+        );
+        assert.equal(userDoc.subscription.status, 'active', 'Status should be active');
+        assert.equal(userDoc.subscription.payment.processor, 'test', 'Processor should be test');
+      },
+    },
+
+    {
+      name: 'order-doc-has-correct-product',
+      async run({ firestore, assert, state }) {
+        if (state.skip) {
+          return;
+        }
+
+        // Find the order doc — legacy webhook may not have an orderId from metadata,
+        // so look it up by resourceId
+        const orderQuery = await firestore.query('payments-orders', {
+          where: [{ field: 'resourceId', op: '==', value: state.subscriptionId }],
+          limit: 1,
+        });
+
+        if (orderQuery && orderQuery.length > 0) {
+          const orderDoc = orderQuery[0];
+          assert.equal(
+            orderDoc.unified?.product?.id,
+            state.productId,
+            `Order unified product should be "${state.productId}"`,
+          );
+        }
+      },
+    },
+  ],
+};

package/test/events/payments/journey-payments-refund-webhook.js

@@ -0,0 +1,177 @@
+/**
+ * Test: Payment Journey - Refund Webhook
+ * Simulates: basic → paid active → pending cancel → charge.refunded webhook → payment-refunded transition
+ *
+ * Verifies that refund webhook events:
+ * 1. Flow through the pipeline correctly
+ * 2. Trigger the payment-refunded transition (not subscription-cancelled)
+ * 3. Extract refundDetails via the processor library's getRefundDetails()
+ * 4. Record the transition name on the webhook doc for auditing
+ *
+ * Product-agnostic: resolves the first paid product from config.payment.products
+ */
+module.exports = {
+  description: 'Payment journey: paid → refund webhook → payment-refunded transition',
+  type: 'suite',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'setup-paid-subscription',
+      async run({ accounts, firestore, assert, state, config, http, waitFor }) {
+        const uid = accounts['journey-payments-refund-webhook'].uid;
+
+        const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices?.monthly);
+        assert.ok(paidProduct, 'Config should have at least one paid product with monthly price');
+
+        state.uid = uid;
+        state.paidProductId = paidProduct.id;
+        state.paidStripeProductId = paidProduct.stripe?.productId;
+
+        // Create subscription via test intent
+        const response = await http.as('journey-payments-refund-webhook').post('payments/intent', {
+          processor: 'test',
+          productId: paidProduct.id,
+          frequency: 'monthly',
+        });
+        assert.isSuccess(response, 'Intent should succeed');
+        state.orderId = response.data.orderId;
+
+        // Wait for subscription to activate
+        await waitFor(async () => {
+          const userDoc = await firestore.get(`users/${uid}`);
+          return userDoc?.subscription?.product?.id === paidProduct.id
+            && userDoc?.subscription?.status === 'active';
+        }, 15000, 500);
+
+        const userDoc = await firestore.get(`users/${uid}`);
+        assert.equal(userDoc.subscription?.product?.id, paidProduct.id, `Should be ${paidProduct.id}`);
+        assert.equal(userDoc.subscription?.status, 'active', 'Should be active');
+
+        state.subscriptionId = userDoc.subscription.payment.resourceId;
+      },
+    },
+
+    {
+      name: 'send-pending-cancel-webhook',
+      async run({ http, assert, state, config }) {
+        const futureDate = new Date();
+        futureDate.setMonth(futureDate.getMonth() + 1);
+
+        state.cancelEventId = `_test-evt-journey-refund-cancel-${Date.now()}`;
+
+        const response = await http.as('none').post(`payments/webhook?processor=test&key=${config.backendManagerKey}`, {
+          id: state.cancelEventId,
+          type: 'customer.subscription.updated',
+          data: {
+            object: {
+              id: state.subscriptionId,
+              object: 'subscription',
+              status: 'active',
+              metadata: { uid: state.uid },
+              cancel_at_period_end: true,
+              cancel_at: Math.floor(futureDate.getTime() / 1000),
+              canceled_at: null,
+              current_period_end: Math.floor(futureDate.getTime() / 1000),
+              current_period_start: Math.floor(Date.now() / 1000),
+              start_date: Math.floor(Date.now() / 1000) - 86400 * 30,
+              trial_start: null,
+              trial_end: null,
+              plan: { product: state.paidStripeProductId, interval: 'month' },
+            },
+          },
+        });
+
+        assert.isSuccess(response, 'Cancel webhook should be accepted');
+      },
+    },
+
+    {
+      name: 'cancellation-pending-confirmed',
+      async run({ firestore, assert, state, waitFor }) {
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.cancelEventId}`);
+          return doc?.status === 'completed';
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.cancelEventId}`);
+        assert.equal(webhookDoc.transition, 'cancellation-requested', 'Should detect cancellation-requested');
+
+        const userDoc = await firestore.get(`users/${state.uid}`);
+        assert.equal(userDoc.subscription.status, 'active', 'Status should still be active');
+        assert.equal(userDoc.subscription.cancellation.pending, true, 'Cancellation should be pending');
+      },
+    },
+
+    {
+      name: 'send-charge-refunded-webhook',
+      async run({ http, assert, state, config }) {
+        // Simulate a charge.refunded event (Stripe-shaped, used by test processor)
+        // This carries refund amount data that getRefundDetails() extracts
+        state.refundEventId = `_test-evt-journey-refund-charge-${Date.now()}`;
+        state.refundAmountCents = 2800; // $28.00
+
+        const response = await http.as('none').post(`payments/webhook?processor=test&key=${config.backendManagerKey}`, {
+          id: state.refundEventId,
+          type: 'charge.refunded',
+          data: {
+            object: {
+              id: `ch_test_${Date.now()}`,
+              object: 'charge',
+              amount: state.refundAmountCents,
+              amount_refunded: state.refundAmountCents,
+              currency: 'usd',
+              subscription: state.subscriptionId,
+              metadata: { uid: state.uid },
+              refunds: {
+                data: [
+                  {
+                    id: `re_test_${Date.now()}`,
+                    amount: state.refundAmountCents,
+                    currency: 'usd',
+                    reason: 'requested_by_customer',
+                  },
+                ],
+              },
+            },
+          },
+        });
+
+        assert.isSuccess(response, 'Refund webhook should be accepted');
+      },
+    },
+
+    {
+      name: 'payment-refunded-transition-detected',
+      async run({ firestore, assert, state, waitFor }) {
+        // Wait for the refund webhook to be processed
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.refundEventId}`);
+          return doc?.status === 'completed';
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.refundEventId}`);
+
+        // Core assertion: refund events trigger payment-refunded, not subscription-cancelled
+        assert.equal(webhookDoc.status, 'completed', 'Webhook should complete successfully');
+        assert.equal(webhookDoc.transition, 'payment-refunded', 'Transition should be payment-refunded (not subscription-cancelled)');
+        assert.equal(webhookDoc.owner, state.uid, 'Owner should match');
+        assert.equal(webhookDoc.orderId, state.orderId, 'Order ID should match');
+      },
+    },
+
+    {
+      name: 'order-doc-updated',
+      async run({ firestore, assert, state }) {
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.ok(orderDoc, 'Order doc should exist');
+        assert.equal(orderDoc.type, 'subscription', 'Type should be subscription');
+        assert.equal(orderDoc.owner, state.uid, 'Owner should match');
+
+        // The order was last updated by the refund webhook event
+        assert.equal(orderDoc.metadata?.updatedBy?.event?.name, 'charge.refunded', 'Last event should be charge.refunded');
+      },
+    },
+  ],
+};

package/test/events/payments/journey-payments-uid-resolution.js

@@ -0,0 +1,129 @@
+/**
+ * Test: Payment Journey - UID Resolution Fallback
+ * Simulates: paid active subscription → webhook with uid OMITTED from metadata
+ *
+ * Verifies Fix 1: when a webhook event doesn't carry uid in metadata (like PayPal's
+ * PAYMENT.SALE events), the pipeline resolves uid from the fetched resource using
+ * library.getUid() and persists it on the webhook doc.
+ *
+ * Flow:
+ * 1. Set up paid subscription via test intent (establishes payments-orders doc with resourceId)
+ * 2. Send customer.subscription.updated webhook WITHOUT uid in metadata
+ * 3. Verify: webhook completes (not fails), uid resolved, subscription updated
+ *
+ * Product-agnostic: resolves the first paid product from config.payment.products
+ */
+module.exports = {
+  description: 'Payment journey: webhook without uid → UID resolved from fetched resource',
+  type: 'suite',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'setup-paid-subscription',
+      async run({ accounts, firestore, assert, state, config, http, waitFor }) {
+        const uid = accounts['journey-payments-uid-resolution'].uid;
+
+        const paidProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices?.monthly);
+        assert.ok(paidProduct, 'Config should have at least one paid product with monthly price');
+
+        state.uid = uid;
+        state.paidProductId = paidProduct.id;
+        state.paidStripeProductId = paidProduct.stripe?.productId;
+
+        // Create subscription via test intent
+        const response = await http.as('journey-payments-uid-resolution').post('payments/intent', {
+          processor: 'test',
+          productId: paidProduct.id,
+          frequency: 'monthly',
+        });
+        assert.isSuccess(response, 'Intent should succeed');
+        state.orderId = response.data.orderId;
+
+        // Wait for subscription to activate
+        await waitFor(async () => {
+          const userDoc = await firestore.get(`users/${uid}`);
+          return userDoc?.subscription?.product?.id === paidProduct.id
+            && userDoc?.subscription?.status === 'active';
+        }, 15000, 500);
+
+        const userDoc = await firestore.get(`users/${uid}`);
+        state.subscriptionId = userDoc.subscription.payment.resourceId;
+
+        assert.ok(state.subscriptionId, 'Subscription resource ID should exist');
+      },
+    },
+
+    {
+      name: 'send-webhook-without-uid',
+      async run({ http, assert, state, config }) {
+        // Send a subscription update webhook WITHOUT uid in metadata
+        // The test processor's fetchResource() will look up payments-orders by resourceId
+        // and reconstruct a Stripe-shaped subscription that includes metadata.uid
+        // Then library.getUid() extracts uid from the fetched resource
+        const futureDate = new Date();
+        futureDate.setMonth(futureDate.getMonth() + 1);
+
+        state.noUidEventId = `_test-evt-journey-uid-resolve-${Date.now()}`;
+
+        const response = await http.as('none').post(`payments/webhook?processor=test&key=${config.backendManagerKey}`, {
+          id: state.noUidEventId,
+          type: 'customer.subscription.updated',
+          data: {
+            object: {
+              id: state.subscriptionId,
+              object: 'subscription',
+              status: 'active',
+              // NO metadata.uid — this is the key part of the test
+              metadata: {},
+              cancel_at_period_end: true,
+              cancel_at: Math.floor(futureDate.getTime() / 1000),
+              canceled_at: null,
+              current_period_end: Math.floor(futureDate.getTime() / 1000),
+              current_period_start: Math.floor(Date.now() / 1000),
+              start_date: Math.floor(Date.now() / 1000) - 86400 * 30,
+              trial_start: null,
+              trial_end: null,
+              plan: { product: state.paidStripeProductId, interval: 'month' },
+            },
+          },
+        });
+
+        assert.isSuccess(response, 'Webhook should be accepted (even without uid)');
+      },
+    },
+
+    {
+      name: 'uid-resolved-and-webhook-completed',
+      async run({ firestore, assert, state, waitFor }) {
+        // Wait for the webhook to be processed
+        await waitFor(async () => {
+          const doc = await firestore.get(`payments-webhooks/${state.noUidEventId}`);
+          return doc?.status === 'completed' || doc?.status === 'failed';
+        }, 15000, 500);
+
+        const webhookDoc = await firestore.get(`payments-webhooks/${state.noUidEventId}`);
+
+        // Core assertions: UID was resolved from the fetched resource
+        assert.equal(webhookDoc.status, 'completed', 'Webhook should complete (not fail due to missing UID)');
+        assert.equal(webhookDoc.owner, state.uid, 'Owner should be resolved to the correct UID');
+        assert.equal(webhookDoc.orderId, state.orderId, 'Order ID should match');
+
+        // Transition should be cancellation-requested (we sent cancel_at_period_end: true)
+        assert.equal(webhookDoc.transition, 'cancellation-requested', 'Transition should be cancellation-requested');
+      },
+    },
+
+    {
+      name: 'subscription-updated-correctly',
+      async run({ firestore, assert, state }) {
+        const userDoc = await firestore.get(`users/${state.uid}`);
+
+        // The webhook should have updated the user doc even though uid wasn't in the webhook metadata
+        assert.equal(userDoc.subscription.status, 'active', 'Status should still be active');
+        assert.equal(userDoc.subscription.cancellation.pending, true, 'Cancellation should be pending');
+        assert.equal(userDoc.subscription.product.id, state.paidProductId, `Product should be ${state.paidProductId}`);
+      },
+    },
+  ],
+};