backend-manager 5.0.103 → 5.0.105

package/src/manager/routes/payments/refund/processors/paypal.js

@@ -0,0 +1,117 @@
+/**
+ * PayPal refund processor
+ * Refunds the most recent payment on a PayPal subscription and cancels it.
+ *
+ * PayPal refunds are issued against individual sale/capture transactions,
+ * not against the subscription itself. We find the most recent completed
+ * transaction and refund it.
+ */
+const FULL_REFUND_DAYS = 7;
+
+module.exports = {
+  /**
+   * Process a refund for a PayPal subscription
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - PayPal subscription ID (e.g., 'I-xxx')
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.assistant - Assistant instance for logging
+   * @returns {{ amount: number, currency: string, full: boolean }}
+   */
+  async processRefund({ resourceId, uid, assistant }) {
+    const PayPalLib = require('../../../../libraries/payment/processors/paypal.js');
+
+    // 1. Get subscription transactions to find the latest payment
+    const now = new Date();
+    const oneYearAgo = new Date(now);
+    oneYearAgo.setFullYear(oneYearAgo.getFullYear() - 1);
+
+    const transactions = await PayPalLib.request(
+      `/v1/billing/subscriptions/${resourceId}/transactions?start_time=${oneYearAgo.toISOString()}&end_time=${now.toISOString()}`
+    );
+
+    const completedTransactions = (transactions.transactions || [])
+      .filter(t => t.status === 'COMPLETED')
+      .sort((a, b) => new Date(b.time) - new Date(a.time));
+
+    if (completedTransactions.length === 0) {
+      throw new Error('No completed transactions found for this subscription');
+    }
+
+    const latestTransaction = completedTransactions[0];
+    const saleId = latestTransaction.id;
+    const transactionAmount = parseFloat(latestTransaction.amount_with_breakdown?.gross_amount?.value || '0');
+    const currency = latestTransaction.amount_with_breakdown?.gross_amount?.currency_code || 'USD';
+
+    if (transactionAmount <= 0) {
+      throw new Error('No refundable amount on the latest transaction');
+    }
+
+    // 2. Calculate refund amount
+    const transactionDate = new Date(latestTransaction.time);
+    const daysSincePayment = (now - transactionDate) / (1000 * 60 * 60 * 24);
+
+    let refundAmount;
+    let isFullRefund;
+
+    if (daysSincePayment <= FULL_REFUND_DAYS) {
+      refundAmount = transactionAmount;
+      isFullRefund = true;
+    } else {
+      // Prorated refund — estimate based on billing cycle
+      // PayPal doesn't expose period start/end per transaction like Stripe
+      // Approximate: 30 days for monthly, 365 for yearly
+      const sub = await PayPalLib.request(`/v1/billing/subscriptions/${resourceId}`);
+      const nextBilling = sub.billing_info?.next_billing_time
+        ? new Date(sub.billing_info.next_billing_time)
+        : null;
+
+      if (nextBilling) {
+        const totalDays = (nextBilling - transactionDate) / (1000 * 60 * 60 * 24);
+        const daysRemaining = Math.max(0, (nextBilling - now) / (1000 * 60 * 60 * 24));
+        refundAmount = Math.round((daysRemaining / totalDays) * transactionAmount * 100) / 100;
+      } else {
+        // Fallback: half refund
+        refundAmount = Math.round(transactionAmount * 50) / 100;
+      }
+
+      isFullRefund = false;
+    }
+
+    if (refundAmount <= 0) {
+      throw new Error('No refundable amount remaining');
+    }
+
+    // 3. Issue the refund against the sale/capture
+    await PayPalLib.request(`/v2/payments/captures/${saleId}/refund`, {
+      method: 'POST',
+      body: JSON.stringify({
+        amount: {
+          value: refundAmount.toFixed(2),
+          currency_code: currency,
+        },
+        note_to_payer: 'Subscription refund',
+      }),
+    });
+
+    assistant.log(`PayPal refund issued: saleId=${saleId}, amount=${refundAmount}, full=${isFullRefund}, uid=${uid}`);
+
+    // 4. Cancel the subscription
+    try {
+      await PayPalLib.request(`/v1/billing/subscriptions/${resourceId}/cancel`, {
+        method: 'POST',
+        body: JSON.stringify({ reason: 'Refund requested' }),
+      });
+      assistant.log(`PayPal subscription cancelled after refund: sub=${resourceId}, uid=${uid}`);
+    } catch (e) {
+      // Already cancelled — that's fine
+      assistant.log(`PayPal subscription cancel after refund failed (may already be cancelled): ${e.message}`);
+    }
+
+    return {
+      amount: refundAmount,
+      currency: currency.toLowerCase(),
+      full: isFullRefund,
+    };
+  },
+};

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

@@ -0,0 +1,103 @@
+/**
+ * Stripe refund processor
+ * Issues a refund for the latest invoice and cancels the subscription immediately.
+ *
+ * Refund amount:
+ * - Full refund if the last payment was ≤7 days ago
+ * - Prorated refund (based on days remaining in billing period) if >7 days ago
+ *
+ * After refunding, if the subscription is still active, it is cancelled immediately.
+ * Stripe then sends a customer.subscription.deleted webhook which the existing
+ * pipeline processes to update Firestore.
+ */
+const FULL_REFUND_DAYS = 7;
+
+module.exports = {
+  /**
+   * Process a refund for a Stripe subscription
+   *
+   * @param {object} options
+   * @param {string} options.resourceId - Stripe subscription ID (e.g., 'sub_xxx')
+   * @param {string} options.uid - User's UID (for logging)
+   * @param {object} options.subscription - User's subscription object from Firestore
+   * @param {object} options.assistant - Assistant instance for logging
+   * @returns {{ amount: number, currency: string, full: boolean }}
+   */
+  async processRefund({ resourceId, uid, assistant }) {
+    const StripeLib = require('../../../../libraries/payment/processors/stripe.js');
+    const stripe = StripeLib.init();
+
+    // 1. Retrieve subscription to get latest_invoice
+    const sub = await stripe.subscriptions.retrieve(resourceId);
+
+    if (!sub.latest_invoice) {
+      throw new Error('No invoice found for this subscription');
+    }
+
+    // 2. Retrieve the latest invoice to get payment_intent + timing
+    const invoiceId = typeof sub.latest_invoice === 'string'
+      ? sub.latest_invoice
+      : sub.latest_invoice.id;
+    const invoice = await stripe.invoices.retrieve(invoiceId);
+
+    if (!invoice.payment_intent) {
+      throw new Error('No payment found for the latest invoice');
+    }
+
+    // 3. Calculate refund amount
+    const invoicePaidAt = invoice.status_transitions?.paid_at || invoice.created;
+    const daysSincePayment = (Date.now() / 1000 - invoicePaidAt) / 86400;
+    const invoiceAmount = invoice.amount_paid; // in cents
+
+    if (invoiceAmount <= 0) {
+      throw new Error('No refundable amount on the latest invoice');
+    }
+
+    let refundAmount;
+    let isFullRefund;
+
+    if (daysSincePayment <= FULL_REFUND_DAYS) {
+      refundAmount = invoiceAmount;
+      isFullRefund = true;
+    } else {
+      // Prorated: remaining days / total days * amount
+      const periodStart = sub.current_period_start || invoice.period_start;
+      const periodEnd = sub.current_period_end || invoice.period_end;
+      const totalDays = (periodEnd - periodStart) / 86400;
+      const daysRemaining = Math.max(0, (periodEnd - Date.now() / 1000) / 86400);
+
+      refundAmount = Math.round((daysRemaining / totalDays) * invoiceAmount);
+      isFullRefund = false;
+    }
+
+    if (refundAmount <= 0) {
+      throw new Error('No refundable amount remaining');
+    }
+
+    // 4. Issue the refund
+    const paymentIntentId = typeof invoice.payment_intent === 'string'
+      ? invoice.payment_intent
+      : invoice.payment_intent.id;
+
+    const refund = await stripe.refunds.create({
+      payment_intent: paymentIntentId,
+      amount: refundAmount,
+      reason: 'requested_by_customer',
+    });
+
+    assistant.log(`Stripe refund created: refundId=${refund.id}, amount=${refundAmount}, full=${isFullRefund}, uid=${uid}`);
+
+    // 5. Cancel subscription immediately (if not already canceled)
+    //    This triggers customer.subscription.deleted webhook → existing pipeline
+    if (sub.status !== 'canceled') {
+      await stripe.subscriptions.cancel(resourceId);
+      assistant.log(`Stripe subscription cancelled immediately: sub=${resourceId}, uid=${uid}`);
+    }
+
+    return {
+      amount: refundAmount / 100, // convert cents to dollars for response
+      currency: refund.currency,
+      full: isFullRefund,
+    };
+  },
+};

package/src/manager/routes/payments/refund/processors/test.js

@@ -0,0 +1,98 @@
+const powertools = require('node-powertools');
+
+/**
+ * Test refund processor
+ * Simulates a Stripe refund + immediate cancellation by writing directly to
+ * payments-webhooks/{eventId} with status=pending.
+ * The on-write trigger picks it up and runs the full pipeline,
+ * resulting in a subscription-cancelled transition.
+ * Only available in non-production environments.
+ */
+module.exports = {
+  async processRefund({ resourceId, uid, subscription, assistant }) {
+    if (assistant.isProduction()) {
+      throw new Error('Test processor is not available in production');
+    }
+
+    const admin = assistant.Manager.libraries.admin;
+
+    const timestamp = Date.now();
+    const eventId = `_test-evt-refund-${timestamp}`;
+    const now = Math.floor(timestamp / 1000);
+
+    // Look up the Stripe product ID from the existing order so resolveProduct() can match
+    const orderId = subscription?.payment?.orderId;
+    let stripeProductId = null;
+
+    if (orderId) {
+      const orderDoc = await admin.firestore().doc(`payments-orders/${orderId}`).get();
+      if (orderDoc.exists) {
+        const orderData = orderDoc.data();
+        const productId = orderData.unified?.product?.id;
+        const products = assistant.Manager.config.payment?.products || [];
+        const product = products.find(p => p.id === productId);
+        stripeProductId = product?.stripe?.productId || null;
+      }
+    }
+
+    // Build a Stripe-shaped customer.subscription.deleted payload
+    // Mirrors what Stripe sends after an immediate cancellation (refund + cancel)
+    const subscriptionObj = {
+      id: resourceId,
+      object: 'subscription',
+      status: 'canceled',
+      metadata: { uid, orderId },
+      cancel_at_period_end: false,
+      cancel_at: null,
+      canceled_at: now,
+      current_period_end: now,
+      current_period_start: now - (30 * 86400),
+      start_date: now - (30 * 86400),
+      trial_start: null,
+      trial_end: null,
+      plan: { product: stripeProductId, interval: 'month' },
+    };
+
+    const nowTs = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(nowTs, { output: 'unix' });
+
+    // Write directly to payments-webhooks — on-write trigger handles the rest
+    await admin.firestore().doc(`payments-webhooks/${eventId}`).set({
+      id: eventId,
+      processor: 'test',
+      status: 'pending',
+      owner: uid,
+      raw: {
+        id: eventId,
+        type: 'customer.subscription.deleted',
+        data: { object: subscriptionObj },
+      },
+      event: {
+        type: 'customer.subscription.deleted',
+        category: 'subscription',
+        resourceType: 'subscription',
+        resourceId: resourceId,
+      },
+      error: null,
+      metadata: {
+        received: {
+          timestamp: nowTs,
+          timestampUNIX: nowUNIX,
+        },
+        processed: {
+          timestamp: null,
+          timestampUNIX: null,
+        },
+      },
+    });
+
+    assistant.log(`Test refund processor: wrote payments-webhooks/${eventId} for sub=${resourceId}, uid=${uid}`);
+
+    // Return mock refund result
+    return {
+      amount: subscription?.payment?.price || 0,
+      currency: 'usd',
+      full: true,
+    };
+  },
+};

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

@@ -0,0 +1,137 @@
+/**
+ * PayPal webhook processor
+ * Extracts, validates, and categorizes webhook event data from PayPal
+ *
+ * PayPal webhook events: https://developer.paypal.com/api/rest/webhooks/event-names/
+ */
+
+// Events we process, mapped to their category
+const SUPPORTED_EVENTS = new Set([
+  // Subscription lifecycle
+  'BILLING.SUBSCRIPTION.ACTIVATED',
+  'BILLING.SUBSCRIPTION.UPDATED',
+  'BILLING.SUBSCRIPTION.CANCELLED',
+  'BILLING.SUBSCRIPTION.SUSPENDED',
+  'BILLING.SUBSCRIPTION.EXPIRED',
+  'BILLING.SUBSCRIPTION.RE-ACTIVATED',
+
+  // Payment events (subscription billing)
+  'PAYMENT.SALE.COMPLETED',
+  'PAYMENT.SALE.DENIED',
+  'PAYMENT.SALE.REFUNDED',
+
+  // One-time order events
+  'CHECKOUT.ORDER.APPROVED',
+]);
+
+module.exports = {
+  /**
+   * Returns true if this event type should be saved and processed
+   */
+  isSupported(eventType) {
+    return SUPPORTED_EVENTS.has(eventType);
+  },
+
+  /**
+   * Parse a PayPal webhook request
+   * Extracts event data and determines category, resource type, resource ID, and UID
+   *
+   * @param {object} req - The raw HTTP request
+   * @returns {object} { eventId, eventType, category, resourceType, resourceId, raw, uid }
+   */
+  parseWebhook(req) {
+    const event = req.body;
+
+    // Validate event structure
+    if (!event || !event.id || !event.event_type) {
+      throw new Error('Invalid PayPal webhook payload');
+    }
+
+    const resource = event.resource || {};
+    const eventType = event.event_type;
+
+    let category = null;
+    let resourceType = null;
+    let resourceId = null;
+    let uid = null;
+
+    if (eventType.startsWith('BILLING.SUBSCRIPTION.')) {
+      // Subscription lifecycle events
+      category = 'subscription';
+      resourceType = 'subscription';
+      resourceId = resource.id; // PayPal subscription ID (I-xxx)
+
+      // Parse uid from custom_id
+      uid = parseUidFromCustomId(resource.custom_id);
+
+    } else if (eventType === 'PAYMENT.SALE.COMPLETED' || eventType === 'PAYMENT.SALE.DENIED') {
+      // Payment sale — determine if it's for a subscription
+      const billingAgreementId = resource.billing_agreement_id;
+
+      if (billingAgreementId) {
+        // Subscription payment
+        category = 'subscription';
+        resourceType = 'subscription';
+        resourceId = billingAgreementId; // This is the subscription ID
+
+        uid = parseUidFromCustomId(resource.custom_id);
+      } else {
+        // One-time payment — skip for now (not yet supported)
+        category = null;
+      }
+
+    } else if (eventType === 'CHECKOUT.ORDER.APPROVED') {
+      // One-time order approved by buyer — will be captured in fetchResource
+      category = 'one-time';
+      resourceType = 'order';
+      resourceId = resource.id; // PayPal order ID
+
+      // Parse uid from purchase_units custom_id
+      uid = parseUidFromCustomId(resource.purchase_units?.[0]?.custom_id);
+
+    } else if (eventType === 'PAYMENT.SALE.REFUNDED') {
+      // Refund — linked to a subscription via billing_agreement_id
+      const billingAgreementId = resource.billing_agreement_id;
+
+      if (billingAgreementId) {
+        category = 'subscription';
+        resourceType = 'subscription';
+        resourceId = billingAgreementId;
+        uid = parseUidFromCustomId(resource.custom_id);
+      } else {
+        category = null;
+      }
+    }
+
+    return {
+      eventId: event.id,
+      eventType: eventType,
+      category: category,
+      resourceType: resourceType,
+      resourceId: resourceId,
+      raw: event,
+      uid: uid,
+    };
+  },
+};
+
+/**
+ * Parse uid from PayPal custom_id format: uid:{uid},orderId:{orderId}
+ * @param {string} customId
+ * @returns {string|null}
+ */
+function parseUidFromCustomId(customId) {
+  if (!customId) {
+    return null;
+  }
+
+  for (const part of customId.split(',')) {
+    const [key, ...valueParts] = part.split(':');
+
+    if (key === 'uid') {
+      return valueParts.join(':') || null;
+    }
+  }
+
+  return null;
+}

package/src/manager/schemas/payments/refund/post.js

@@ -0,0 +1,18 @@
+/**
+ * Schema: POST /payments/refund
+ * Validates subscription refund parameters
+ */
+module.exports = () => ({
+  reason: {
+    types: ['string'],
+    required: true,
+  },
+  feedback: {
+    types: ['string'],
+    default: null,
+  },
+  confirmed: {
+    types: ['boolean'],
+    required: true,
+  },
+});

package/src/test/test-accounts.js

@@ -285,6 +285,52 @@ const JOURNEY_ACCOUNTS = {
       subscription: { product: { id: 'premium', name: 'Premium' }, status: 'active', expires: getFutureExpires(), payment: { processor: 'unknown-processor', resourceId: 'sub_test_fake' } },
     },
   },
+  // Dedicated accounts for refund validation tests
+  'refund-active-no-cancel': {
+    id: 'refund-active-no-cancel',
+    uid: '_test-refund-active-no-cancel',
+    email: '_test.refund-active-no-cancel@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'premium', name: 'Premium' }, status: 'active', expires: getFutureExpires(), cancellation: { pending: false }, payment: { processor: 'test', resourceId: 'sub_test_fake' } },
+    },
+  },
+  'refund-no-processor': {
+    id: 'refund-no-processor',
+    uid: '_test-refund-no-processor',
+    email: '_test.refund-no-processor@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'premium', name: 'Premium' }, status: 'cancelled', expires: getPastExpires(), cancellation: { pending: false }, payment: { processor: null, resourceId: null } },
+    },
+  },
+  'refund-unknown-processor': {
+    id: 'refund-unknown-processor',
+    uid: '_test-refund-unknown-processor',
+    email: '_test.refund-unknown-processor@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'premium', name: 'Premium' }, status: 'cancelled', expires: getPastExpires(), cancellation: { pending: false }, payment: { processor: 'unknown-processor', resourceId: 'sub_test_fake' } },
+    },
+  },
+  'refund-expired-payment': {
+    id: 'refund-expired-payment',
+    uid: '_test-refund-expired-payment',
+    email: '_test.refund-expired-payment@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'premium', name: 'Premium' }, status: 'cancelled', expires: getPastExpires(), cancellation: { pending: false }, payment: { processor: 'test', resourceId: 'sub_test_fake', startDate: getPastExpires() } },
+    },
+  },
+  'route-refund-success': {
+    id: 'route-refund-success',
+    uid: '_test-route-refund-success',
+    email: '_test.route-refund-success@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' },
+    },
+  },
 };
 
 /**

package/templates/backend-manager-config.json

@@ -60,16 +60,14 @@
           days: 14,
         },
         prices: {
-          monthly: {
-            amount: 4.99,
-            stripe: null,
-            paypal: null,
-          },
-          annually: {
-            amount: 49.99,
-            stripe: null,
-            paypal: null,
-          },
+          monthly: 4.99,
+          annually: 49.99,
+        },
+        stripe: {
+          productId: null,
+        },
+        paypal: {
+          productId: null,
         },
       },
       {
@@ -80,16 +78,14 @@
           requests: 10000,
         },
         prices: {
-          monthly: {
-            amount: 19.99,
-            stripe: null,
-            paypal: null,
-          },
-          annually: {
-            amount: 199.99,
-            stripe: null,
-            paypal: null,
-          },
+          monthly: 19.99,
+          annually: 199.99,
+        },
+        stripe: {
+          productId: null,
+        },
+        paypal: {
+          productId: null,
         },
       },
       {
@@ -97,10 +93,10 @@
         name: '100 Credits',
         type: 'one-time',
         prices: {
-          once: {
-            amount: 9.99,
-            stripe: null,
-          },
+          once: 9.99,
+        },
+        stripe: {
+          productId: null,
         },
       },
       // Add more products/tiers here

package/test/events/payments/journey-payments-cancel.js

@@ -23,7 +23,7 @@ module.exports = {
         state.uid = uid;
         state.paidProductId = paidProduct.id;
         state.paidProductName = paidProduct.name;
-        state.paidPriceId = paidProduct.prices.monthly.stripe;
+        state.paidStripeProductId = paidProduct.stripe?.productId;
 
         // Create subscription via test intent
         const response = await http.as('journey-payments-cancel').post('payments/intent', {
@@ -74,7 +74,7 @@ module.exports = {
               start_date: Math.floor(Date.now() / 1000) - 86400 * 30,
               trial_start: null,
               trial_end: null,
-              plan: { id: state.paidPriceId, interval: 'month' },
+              plan: { product: state.paidStripeProductId, interval: 'month' },
             },
           },
         });
@@ -122,7 +122,7 @@ module.exports = {
               start_date: Math.floor(Date.now() / 1000) - 86400 * 60,
               trial_start: null,
               trial_end: null,
-              plan: { id: state.paidPriceId, interval: 'month' },
+              plan: { product: state.paidStripeProductId, interval: 'month' },
             },
           },
         });

package/test/events/payments/journey-payments-failure.js

@@ -26,7 +26,7 @@ module.exports = {
         state.uid = uid;
         state.paidProductId = paidProduct.id;
         state.paidProductName = paidProduct.name;
-        state.paidPriceId = paidProduct.prices.monthly.stripe;
+        state.paidStripeProductId = paidProduct.stripe?.productId;
 
         // Create subscription via test intent
         const response = await http.as('journey-payments-failure').post('payments/intent', {

package/test/events/payments/journey-payments-one-time.js

@@ -29,7 +29,7 @@ module.exports = {
         state.uid = uid;
         state.productId = oneTimeProduct.id;
         state.productName = oneTimeProduct.name;
-        state.price = oneTimeProduct.prices.once.amount;
+        state.price = oneTimeProduct.prices.once;
 
         // Snapshot subscription before purchase — should remain unchanged after
         state.subscriptionBefore = userDoc.subscription || null;

package/test/events/payments/journey-payments-plan-change.js

@@ -24,8 +24,8 @@ module.exports = {
         const productB = paidProducts[1];
 
         state.uid = uid;
-        state.productA = { id: productA.id, name: productA.name, priceId: productA.prices.monthly.stripe };
-        state.productB = { id: productB.id, name: productB.name, priceId: productB.prices.monthly.stripe };
+        state.productA = { id: productA.id, name: productA.name, stripeProductId: productA.stripe?.productId };
+        state.productB = { id: productB.id, name: productB.name, stripeProductId: productB.stripe?.productId };
 
         // Create subscription via test intent (product A)
         const response = await http.as('journey-payments-plan-change').post('payments/intent', {
@@ -58,7 +58,7 @@ module.exports = {
 
         state.eventId = `_test-evt-journey-plan-change-${Date.now()}`;
 
-        // Send subscription.updated with a different product's price ID
+        // Send subscription.updated with a different product's Stripe product ID
         const response = await http.as('none').post(`payments/webhook?processor=test&key=${config.backendManagerKey}`, {
           id: state.eventId,
           type: 'customer.subscription.updated',
@@ -75,7 +75,7 @@ module.exports = {
               start_date: Math.floor(Date.now() / 1000) - 86400 * 30,
               trial_start: null,
               trial_end: null,
-              plan: { id: state.productB.priceId, interval: 'month' },
+              plan: { product: state.productB.stripeProductId, interval: 'month' },
             },
           },
         });