backend-manager 5.0.109 → 5.0.111

package/CHANGELOG.md

@@ -14,6 +14,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.0.109] - 2026-03-04
+### Added
+- Immediate trial cancellation: cancelling during a free trial now terminates the subscription instantly instead of scheduling cancel at period end, preventing free premium access for the remainder of the trial.
+- Intent status tracking: `payments-intents/{orderId}` is now updated with `status: completed/failed` and completion timestamp after webhook processing.
+- `journey-payments-trial-cancel` test suite covering the full trial → cancel → immediate cancellation flow.
+
+### Changed
+- Stripe and test cancel processors now detect trialing state and dispatch immediate cancel (`customer.subscription.deleted`) vs period-end cancel (`customer.subscription.updated`).
+
 # [5.0.106] - 2026-03-04
 ### Added
 - `GET /payments/trial-eligibility`: returns whether the authenticated user is eligible for a free trial (checks for any previous subscription orders in `payments-orders`).

package/package.json

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

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

@@ -236,7 +236,18 @@ async function processPaymentEvent({ category, library, resource, resourceType,
 
   // Write to payments-orders/{orderId}
   if (orderId) {
-    await admin.firestore().doc(`payments-orders/${orderId}`).set(order, { merge: true });
+    const orderRef = admin.firestore().doc(`payments-orders/${orderId}`);
+    const orderSnap = await orderRef.get();
+
+    // Initialize requests on first creation only (avoid overwriting cancel/refund data set by endpoints)
+    if (!orderSnap.exists) {
+      order.requests = {
+        cancellation: null,
+        refund: null,
+      };
+    }
+
+    await orderRef.set(order, { merge: true });
     assistant.log(`Updated payments-orders/${orderId}: type=${category}, uid=${uid}, eventType=${eventType}`);
   }
 

package/src/manager/index.js

@@ -138,6 +138,9 @@ Manager.prototype.init = function (exporter, options) {
     (_objValue, srcValue) => isArray(srcValue) ? srcValue : undefined,
   );
 
+  // Set PAYPAL_CLIENT_ID from config (clientId is public, not a secret — lives in config, not .env)
+  process.env.PAYPAL_CLIENT_ID = process.env.PAYPAL_CLIENT_ID || self.config?.payment?.processors?.paypal?.clientId || '';
+
   // Resolve legacy paths
   // TODO: Remove this in future versions (after we migrate to removing app.id from config)
   self.config.app = self.config.app || {};

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

@@ -8,12 +8,41 @@ const EPOCH_ZERO_UNIX = powertools.timestamp(EPOCH_ZERO, { output: 'unix' });
 const INTERVAL_TO_FREQUENCY = { YEAR: 'annually', MONTH: 'monthly', WEEK: 'weekly', DAY: 'daily' };
 const FREQUENCY_TO_INTERVAL = { annually: 'YEAR', monthly: 'MONTH', weekly: 'WEEK', daily: 'DAY' };
 
-// PayPal API base URL
-const PAYPAL_API_BASE = 'https://api-m.paypal.com';
+// PayPal API base URLs
+const LIVE_URL = 'https://api-m.paypal.com';
+const SANDBOX_URL = 'https://api-m.sandbox.paypal.com';
 
-// Cached access token + expiry
+// Cached access token, expiry, and resolved base URL
 let cachedToken = null;
 let tokenExpiresAt = 0;
+let resolvedBaseUrl = null;
+
+/**
+ * Try to authenticate against a specific PayPal endpoint
+ * @param {string} auth - Base64-encoded client_id:secret
+ * @param {string} baseUrl - PayPal API base URL
+ * @returns {Promise<object|null>} Token data or null if auth failed
+ */
+async function tryAuth(auth, baseUrl) {
+  try {
+    const response = await fetch(`${baseUrl}/v1/oauth2/token`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Basic ${auth}`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: 'grant_type=client_credentials',
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    return await response.json();
+  } catch (e) {
+    return null;
+  }
+}
 
 /**
  * PayPal shared library
@@ -22,7 +51,7 @@ let tokenExpiresAt = 0;
 const PayPal = {
   /**
    * Initialize or return a PayPal access token
-   * Uses client credentials grant (client_id + secret)
+   * Tries both live and sandbox endpoints in parallel on first auth
    * @returns {Promise<string>} Access token
    */
   async init() {
@@ -40,22 +69,39 @@ const PayPal = {
 
     const auth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
 
-    const response = await fetch(`${PAYPAL_API_BASE}/v1/oauth2/token`, {
-      method: 'POST',
-      headers: {
-        'Authorization': `Basic ${auth}`,
-        'Content-Type': 'application/x-www-form-urlencoded',
-      },
-      body: 'grant_type=client_credentials',
-    });
+    // First auth — try both endpoints in parallel to detect environment
+    if (!resolvedBaseUrl) {
+      const [liveResult, sandboxResult] = await Promise.all([
+        tryAuth(auth, LIVE_URL),
+        tryAuth(auth, SANDBOX_URL),
+      ]);
+
+      if (liveResult) {
+        resolvedBaseUrl = LIVE_URL;
+        cachedToken = liveResult.access_token;
+        tokenExpiresAt = Date.now() + (liveResult.expires_in * 1000);
+        return cachedToken;
+      }
 
-    if (!response.ok) {
-      throw new Error(`PayPal auth failed: ${response.status} ${response.statusText}`);
+      if (sandboxResult) {
+        resolvedBaseUrl = SANDBOX_URL;
+        cachedToken = sandboxResult.access_token;
+        tokenExpiresAt = Date.now() + (sandboxResult.expires_in * 1000);
+        return cachedToken;
+      }
+
+      throw new Error('PayPal auth failed on both live and sandbox — check your client ID and secret');
     }
 
-    const data = await response.json();
-    cachedToken = data.access_token;
-    tokenExpiresAt = Date.now() + (data.expires_in * 1000);
+    // Subsequent auths — use the resolved endpoint
+    const result = await tryAuth(auth, resolvedBaseUrl);
+
+    if (!result) {
+      throw new Error(`PayPal auth failed (${resolvedBaseUrl})`);
+    }
+
+    cachedToken = result.access_token;
+    tokenExpiresAt = Date.now() + (result.expires_in * 1000);
 
     return cachedToken;
   },
@@ -69,7 +115,7 @@ const PayPal = {
   async request(endpoint, options = {}) {
     const token = await this.init();
 
-    const response = await fetch(`${PAYPAL_API_BASE}${endpoint}`, {
+    const response = await fetch(`${resolvedBaseUrl}${endpoint}`, {
       ...options,
       headers: {
         'Authorization': `Bearer ${token}`,

package/src/manager/routes/payments/cancel/post.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const powertools = require('node-powertools');
 
 /**
  * POST /payments/cancel
@@ -6,6 +7,7 @@ const path = require('path');
  * Delegates to the processor (e.g., Stripe) to set cancel_at_period_end=true.
  * The resulting webhook triggers the Firestore pipeline which updates subscription state
  * and fires the cancellation-requested transition handler.
+ * Stores the cancellation reason/feedback on payments-orders/{orderId}.requests.cancellation.
  * Requires authentication.
  */
 module.exports = async ({ assistant, user, settings }) => {
@@ -60,7 +62,31 @@ module.exports = async ({ assistant, user, settings }) => {
     return assistant.respond(`Failed to cancel subscription: ${e.message}`, { code: 500, sentry: true });
   }
 
-  assistant.log(`Cancel at period end scheduled: uid=${uid}, processor=${processor}, sub=${resourceId}, reason=${settings.reason}`);
+  // Store cancellation reason/feedback on the order doc
+  const orderId = subscription.payment?.orderId;
+
+  if (orderId) {
+    const admin = assistant.Manager.libraries.admin;
+    const now = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+    await admin.firestore().doc(`payments-orders/${orderId}`).set({
+      requests: {
+        cancellation: {
+          reason: settings.reason || null,
+          feedback: settings.feedback || null,
+          date: {
+            timestamp: now,
+            timestampUNIX: nowUNIX,
+          },
+        },
+      },
+    }, { merge: true });
+
+    assistant.log(`Stored cancellation request on payments-orders/${orderId}: reason=${settings.reason}`);
+  }
+
+  assistant.log(`Cancel scheduled: uid=${uid}, processor=${processor}, sub=${resourceId}, reason=${settings.reason}`);
 
   return assistant.respond({ success: true });
 };

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

@@ -1,4 +1,5 @@
 const path = require('path');
+const powertools = require('node-powertools');
 
 /**
  * POST /payments/refund
@@ -8,6 +9,7 @@ const path = require('path');
  * Delegates to the processor (e.g., Stripe) to issue the refund and cancel.
  * The resulting webhook triggers the Firestore pipeline which updates subscription state
  * and fires the subscription-cancelled transition handler.
+ * Stores the refund reason/feedback on payments-orders/{orderId}.requests.refund.
  * Requires authentication.
  */
 module.exports = async ({ assistant, user, settings }) => {
@@ -79,6 +81,32 @@ module.exports = async ({ assistant, user, settings }) => {
     return assistant.respond(`Failed to process refund: ${e.message}`, { code: 500, sentry: true });
   }
 
+  // Store refund reason/feedback on the order doc
+  const orderId = subscription.payment?.orderId;
+
+  if (orderId) {
+    const admin = assistant.Manager.libraries.admin;
+    const now = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
+    await admin.firestore().doc(`payments-orders/${orderId}`).set({
+      requests: {
+        refund: {
+          reason: settings.reason || null,
+          feedback: settings.feedback || null,
+          amount: refund.amount,
+          full: refund.full,
+          date: {
+            timestamp: now,
+            timestampUNIX: nowUNIX,
+          },
+        },
+      },
+    }, { merge: true });
+
+    assistant.log(`Stored refund request on payments-orders/${orderId}: reason=${settings.reason}, amount=${refund.amount}`);
+  }
+
   assistant.log(`Refund processed: uid=${uid}, processor=${processor}, sub=${resourceId}, amount=${refund.amount}, full=${refund.full}, reason=${settings.reason}`);
 
   return assistant.respond({ success: true, refund });

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

@@ -75,5 +75,20 @@ module.exports = {
         assert.ok(userDoc.subscription.cancellation.date.timestampUNIX > 0, 'Cancellation date should be set');
       },
     },
+
+    {
+      name: 'cancellation-request-stored',
+      async run({ firestore, assert, state }) {
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.ok(orderDoc, 'Order doc should exist');
+        assert.ok(orderDoc.requests, 'requests field should exist');
+        assert.ok(orderDoc.requests.cancellation, 'requests.cancellation should be populated');
+        assert.equal(orderDoc.requests.cancellation.reason, 'Too expensive', 'Cancellation reason should match');
+        assert.equal(orderDoc.requests.cancellation.feedback, 'Would return at a lower price', 'Cancellation feedback should match');
+        assert.ok(orderDoc.requests.cancellation.date.timestampUNIX > 0, 'Cancellation date should be set');
+        assert.equal(orderDoc.requests.refund, null, 'requests.refund should still be null');
+      },
+    },
   ],
 };

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

@@ -148,5 +148,31 @@ module.exports = {
         assert.equal(userDoc.subscription.cancellation.pending, false, 'Cancellation should not be pending');
       },
     },
+
+    {
+      name: 'order-doc-verified',
+      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');
+        assert.ok(orderDoc.requests !== undefined, 'requests field should exist');
+        assert.equal(orderDoc.requests.cancellation, null, 'requests.cancellation should be null (cancel was via webhook, not endpoint)');
+        assert.equal(orderDoc.requests.refund, null, 'requests.refund should be null');
+      },
+    },
+
+    {
+      name: 'intent-doc-completed',
+      async run({ firestore, assert, state }) {
+        const intentDoc = await firestore.get(`payments-intents/${state.orderId}`);
+
+        assert.ok(intentDoc, 'Intent doc should exist');
+        assert.equal(intentDoc.id, state.orderId, 'ID should match orderId');
+        assert.equal(intentDoc.status, 'completed', 'Intent status should be completed after webhook processing');
+        assert.ok(intentDoc.metadata?.completed?.timestampUNIX > 0, 'Completed timestamp should be set');
+      },
+    },
   ],
 };

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

@@ -112,5 +112,31 @@ module.exports = {
         assert.equal(userDoc.subscription.product.id, state.paidProductId, `Product should still be ${state.paidProductId}`);
       },
     },
+
+    {
+      name: 'order-doc-verified',
+      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');
+        assert.ok(orderDoc.requests !== undefined, 'requests field should exist');
+        assert.equal(orderDoc.requests.cancellation, null, 'requests.cancellation should be null');
+        assert.equal(orderDoc.requests.refund, null, 'requests.refund should be null');
+      },
+    },
+
+    {
+      name: 'intent-doc-completed',
+      async run({ firestore, assert, state }) {
+        const intentDoc = await firestore.get(`payments-intents/${state.orderId}`);
+
+        assert.ok(intentDoc, 'Intent doc should exist');
+        assert.equal(intentDoc.id, state.orderId, 'ID should match orderId');
+        assert.equal(intentDoc.status, 'completed', 'Intent status should be completed after initial webhook processing');
+        assert.ok(intentDoc.metadata?.completed?.timestampUNIX > 0, 'Completed timestamp should be set');
+      },
+    },
   ],
 };

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

@@ -85,6 +85,9 @@ module.exports = {
         assert.equal(orderDoc.type, 'one-time', 'Type should be one-time');
         assert.equal(orderDoc.owner, state.uid, 'Owner should match');
         assert.equal(orderDoc.processor, 'test', 'Processor should be test');
+        assert.ok(orderDoc.requests !== undefined, 'requests field should exist');
+        assert.equal(orderDoc.requests.cancellation, null, 'requests.cancellation should be null');
+        assert.equal(orderDoc.requests.refund, null, 'requests.refund should be null');
       },
     },
 

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

@@ -88,6 +88,9 @@ module.exports = {
         assert.equal(orderDoc.unified.product.id, state.productId, `Product should be ${state.productId}`);
         assert.equal(orderDoc.unified.payment.processor, 'test', 'Unified processor should be test');
         assert.equal(orderDoc.unified.payment.orderId, state.orderId, 'Unified orderId should match');
+        assert.ok(orderDoc.requests !== undefined, 'requests field should exist');
+        assert.equal(orderDoc.requests.cancellation, null, 'requests.cancellation should be null');
+        assert.equal(orderDoc.requests.refund, null, 'requests.refund should be null');
       },
     },
 

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

@@ -120,6 +120,21 @@ module.exports = {
         assert.ok(orderDoc, 'Order doc should exist');
         assert.equal(orderDoc.unified.product.id, state.productB.id, `Order product should be ${state.productB.id}`);
         assert.equal(orderDoc.unified.status, 'active', 'Order status should be active');
+        assert.ok(orderDoc.requests !== undefined, 'requests field should exist');
+        assert.equal(orderDoc.requests.cancellation, null, 'requests.cancellation should be null');
+        assert.equal(orderDoc.requests.refund, null, 'requests.refund should be null');
+      },
+    },
+
+    {
+      name: 'intent-doc-completed',
+      async run({ firestore, assert, state }) {
+        const intentDoc = await firestore.get(`payments-intents/${state.orderId}`);
+
+        assert.ok(intentDoc, 'Intent doc should exist');
+        assert.equal(intentDoc.id, state.orderId, 'ID should match orderId');
+        assert.equal(intentDoc.status, 'completed', 'Intent status should be completed after webhook processing');
+        assert.ok(intentDoc.metadata?.completed?.timestampUNIX > 0, 'Completed timestamp should be set');
       },
     },
   ],

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

@@ -147,5 +147,31 @@ module.exports = {
         assert.equal(userDoc.subscription.product.id, state.paidProductId, `Product should still be ${state.paidProductId}`);
       },
     },
+
+    {
+      name: 'order-doc-verified',
+      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');
+        assert.ok(orderDoc.requests !== undefined, 'requests field should exist');
+        assert.equal(orderDoc.requests.cancellation, null, 'requests.cancellation should be null');
+        assert.equal(orderDoc.requests.refund, null, 'requests.refund should be null');
+      },
+    },
+
+    {
+      name: 'intent-doc-completed',
+      async run({ firestore, assert, state }) {
+        const intentDoc = await firestore.get(`payments-intents/${state.orderId}`);
+
+        assert.ok(intentDoc, 'Intent doc should exist');
+        assert.equal(intentDoc.id, state.orderId, 'ID should match orderId');
+        assert.equal(intentDoc.status, 'completed', 'Intent status should be completed after webhook processing');
+        assert.ok(intentDoc.metadata?.completed?.timestampUNIX > 0, 'Completed timestamp should be set');
+      },
+    },
   ],
 };

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

@@ -105,5 +105,20 @@ module.exports = {
         assert.equal(userDoc.subscription.product.id, state.paidProductId, `Product should still be ${state.paidProductId}`);
       },
     },
+
+    {
+      name: 'cancellation-request-stored',
+      async run({ firestore, assert, state }) {
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.ok(orderDoc, 'Order doc should exist');
+        assert.ok(orderDoc.requests, 'requests field should exist');
+        assert.ok(orderDoc.requests.cancellation, 'requests.cancellation should be populated');
+        assert.equal(orderDoc.requests.cancellation.reason, 'Changed my mind during trial', 'Cancellation reason should match');
+        assert.equal(orderDoc.requests.cancellation.feedback, 'Testing trial cancellation', 'Cancellation feedback should match');
+        assert.ok(orderDoc.requests.cancellation.date.timestampUNIX > 0, 'Cancellation date should be set');
+        assert.equal(orderDoc.requests.refund, null, 'requests.refund should still be null');
+      },
+    },
   ],
 };

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

@@ -91,6 +91,23 @@ module.exports = {
       },
     },
 
+    {
+      name: 'order-doc-created',
+      async run({ firestore, assert, state }) {
+        const orderDoc = await firestore.get(`payments-orders/${state.orderId}`);
+
+        assert.ok(orderDoc, 'Order doc should exist');
+        assert.equal(orderDoc.id, state.orderId, 'ID should match orderId');
+        assert.equal(orderDoc.type, 'subscription', 'Type should be subscription');
+        assert.equal(orderDoc.owner, state.uid, 'Owner should match');
+        assert.equal(orderDoc.unified.product.id, state.paidProductId, `Product should be ${state.paidProductId}`);
+        assert.equal(orderDoc.unified.trial.claimed, true, 'Trial should be claimed');
+        assert.ok(orderDoc.requests !== undefined, 'requests field should exist');
+        assert.equal(orderDoc.requests.cancellation, null, 'requests.cancellation should be null');
+        assert.equal(orderDoc.requests.refund, null, 'requests.refund should be null');
+      },
+    },
+
     {
       name: 'send-trial-to-active-webhook',
       async run({ http, assert, state, config }) {

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

@@ -90,6 +90,9 @@ module.exports = {
         assert.equal(orderDoc.resourceId, state.subscriptionId, 'Resource ID should match');
         assert.equal(orderDoc.unified.product.id, state.paidProductId, `Product should be ${state.paidProductId}`);
         assert.equal(orderDoc.unified.status, 'active', 'Status should be active');
+        assert.ok(orderDoc.requests !== undefined, 'requests field should exist');
+        assert.equal(orderDoc.requests.cancellation, null, 'requests.cancellation should be null initially');
+        assert.equal(orderDoc.requests.refund, null, 'requests.refund should be null initially');
       },
     },