backend-manager 5.0.105 → 5.0.107

package/CHANGELOG.md

@@ -14,6 +14,14 @@ 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.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`).
+
+### Fixed
+- Payment frequency mapping now supports `daily` and `weekly` in addition to `monthly` and `annually` across Stripe (`resolvePriceId`), PayPal (`resolvePlanId`), and test processor (`createSubscriptionIntent`). Previously, these frequencies silently fell back to `monthly`.
+- Updated docs (CLAUDE.md, README.md) to list all four supported frequency values.
+
 # [5.0.104] - 2026-03-02
 ### Added
 - `POST /payments/cancel`: cancels subscription at period end via processor abstraction (Stripe sets `cancel_at_period_end=true`; test processor writes webhook directly into the Firestore pipeline).

package/CLAUDE.md

@@ -89,7 +89,7 @@ src/
           post.js                     # Intent creation orchestrator
           processors/                 # Per-processor intent creators
             stripe.js                 # Stripe Checkout Session creation
-            paypal.js                 # PayPal subscription creation
+            paypal.js                 # PayPal subscription + one-time order creation
             test.js                   # Test processor (auto-fires webhooks)
         webhook/                      # POST /payments/webhook
           post.js                     # Webhook ingestion + Firestore write
@@ -705,7 +705,7 @@ subscription: {
     processor: null,               // 'stripe' | 'paypal' | etc.
     orderId: null,                 // BEM order ID (e.g., '1234-5678-9012')
     resourceId: null,              // provider subscription ID (e.g., 'sub_xxx')
-    frequency: null,               // 'monthly' | 'annually'
+    frequency: null,               // 'monthly' | 'annually' | 'weekly' | 'daily'
     price: 0,                      // resolved from config (number, e.g., 4.99)
     startDate: { timestamp, timestampUNIX },
     updatedBy: {
@@ -804,7 +804,7 @@ The payment system is cleanly separated into three independent layers:
 
 | Layer | Purpose | Tests |
 |-------|---------|-------|
-| **Processor input** (Stripe, PayPal, Test) | Parse raw webhooks + transform to unified shape | Helper tests per processor (`stripe-to-unified.js`, `paypal-to-unified.js`, etc.) |
+| **Processor input** (Stripe, PayPal, Test) | Parse raw webhooks + transform to unified shape | Helper tests per processor (`payment/stripe/to-unified-subscription.js`, `payment/paypal/to-unified-one-time.js`, etc.) |
 | **Unified pipeline** (processor-agnostic) | Transition detection, Firestore writes, analytics | Journey tests (`journey-payments-*.js`) |
 | **Transition handlers** (fire-and-forget) | Emails, notifications, side effects | Skipped during tests unless `TEST_EXTENDED_MODE` |
 
@@ -864,6 +864,7 @@ module.exports = {
 module.exports = {
   init() { /* return SDK instance */ },
   async fetchResource(resourceType, resourceId, rawFallback, context) { /* return resource */ },
+  getOrderId(resource) { /* return orderId string or null */ },
   toUnifiedSubscription(rawSubscription, options) { /* return unified object */ },
   toUnifiedOneTime(rawResource, options) { /* return unified object */ },
 };
@@ -910,7 +911,7 @@ payment: {
       type: 'subscription',
       limits: { requests: 1000 },
       trial: { days: 14 },
-      prices: { monthly: 4.99, annually: 49.99 },       // Flat numbers only
+      prices: { monthly: 4.99, annually: 49.99 },       // Flat numbers; also supports 'weekly' and 'daily'
       stripe: { productId: 'prod_xxx', legacyProductIds: ['prod_OLD'] },
       paypal: { productId: 'PROD-abc123' },
     },

package/README.md

@@ -879,7 +879,7 @@ See `CLAUDE.md` for complete test API documentation.
 
 ## Subscription System
 
-BEM includes a built-in payment/subscription system with Stripe integration (extensible to other providers).
+BEM includes a built-in payment/subscription system with Stripe and PayPal integration.
 
 ### Subscription Statuses
 
@@ -902,6 +902,39 @@ BEM includes a built-in payment/subscription system with Stripe integration (ext
 | `incomplete_expired` | `cancelled` | Expired before completion |
 | `active` + `cancel_at_period_end` | `active` | `cancellation.pending = true` |
 
+### PayPal Status Mapping
+
+| PayPal Status | `subscription.status` | Notes |
+|---|---|---|
+| `ACTIVE` | `active` | Normal active subscription |
+| `SUSPENDED` | `suspended` | Payment failed or manually suspended |
+| `CANCELLED` | `cancelled` | Subscription terminated |
+| `EXPIRED` | `cancelled` | Billing cycles completed |
+
+### Product Configuration
+
+Products are defined in `config.payment.products` with flat prices and per-processor IDs:
+
+```javascript
+payment: {
+  products: [
+    { id: 'basic', name: 'Basic', type: 'subscription', limits: { requests: 10 } },
+    {
+      id: 'plus', name: 'Plus', type: 'subscription',
+      limits: { requests: 100 }, trial: { days: 14 },
+      prices: { monthly: 28, annually: 276 },  // also supports 'weekly' and 'daily'
+      stripe: { productId: 'prod_xxx' },
+      paypal: { productId: 'PROD-abc123' },
+    },
+    {
+      id: 'boost', name: 'Boost Pack', type: 'one-time',
+      prices: { once: 9.99 },
+      stripe: { productId: 'prod_yyy' },
+    },
+  ],
+}
+```
+
 ### Unified Subscription Object
 
 The same subscription shape is stored in `users/{uid}.subscription` and `payments-orders/{orderId}.subscription`:
@@ -925,7 +958,7 @@ subscription: {
   payment: {
     processor: null,               // 'stripe' | 'paypal' | etc.
     resourceId: null,              // provider subscription ID (e.g., 'sub_xxx')
-    frequency: null,               // 'monthly' | 'annually'
+    frequency: null,               // 'monthly' | 'annually' | 'weekly' | 'daily'
     startDate: { timestamp, timestampUNIX },
     updatedBy: {
       event: { name: null, id: null },

package/package.json

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

package/src/manager/index.js

@@ -1,6 +1,6 @@
 // Libraries
 const path = require('path');
-const { merge } = require('lodash');
+const { mergeWith, isArray } = require('lodash');
 const jetpack = require('fs-jetpack');
 const JSON5 = require('json5');
 const EventEmitter = require('events');
@@ -129,10 +129,13 @@ Manager.prototype.init = function (exporter, options) {
   }
 
   // Load config
-  self.config = merge(
+  // Use mergeWith to replace arrays instead of merging by index
+  // (lodash merge merges arrays positionally, causing template defaults to bleed into project values)
+  self.config = mergeWith(
     {},
     requireJSON5(BEM_CONFIG_TEMPLATE_PATH, true),
     requireJSON5(self.project.backendManagerConfigPath, true),
+    (_objValue, srcValue) => isArray(srcValue) ? srcValue : undefined,
   );
 
   // Resolve legacy paths

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

@@ -6,6 +6,7 @@ const EPOCH_ZERO_UNIX = powertools.timestamp(EPOCH_ZERO, { output: 'unix' });
 
 // PayPal interval → unified frequency map
 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';
@@ -271,7 +272,7 @@ const PayPal = {
     const plans = response.plans || [];
 
     // Map frequency to PayPal interval unit
-    const intervalUnit = frequency === 'annually' ? 'YEAR' : 'MONTH';
+    const intervalUnit = FREQUENCY_TO_INTERVAL[frequency] || 'MONTH';
 
     // Find matching active plan by interval + amount
     for (const plan of plans) {

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

@@ -9,6 +9,7 @@ const EPOCH_ZERO_UNIX = powertools.timestamp(EPOCH_ZERO, { output: 'unix' });
 
 // Stripe interval → unified frequency map
 const INTERVAL_TO_FREQUENCY = { year: 'annually', month: 'monthly', week: 'weekly', day: 'daily' };
+const FREQUENCY_TO_INTERVAL = { annually: 'year', monthly: 'month', weekly: 'week', daily: 'day' };
 
 /**
  * Stripe shared library
@@ -228,7 +229,7 @@ const Stripe = {
 
     // Match by interval + amount
     if (productType === 'subscription') {
-      const interval = frequency === 'annually' ? 'year' : 'month';
+      const interval = FREQUENCY_TO_INTERVAL[frequency] || 'month';
       const match = prices.find(p =>
         p.recurring?.interval === interval
         && p.unit_amount === amountCents

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

@@ -14,7 +14,7 @@ module.exports = {
    * @param {string} options.uid - User's UID
    * @param {object} options.product - Full product object from config
    * @param {string} options.productId - Product ID from config
-   * @param {string} options.frequency - 'monthly' or 'annually' (subscriptions only)
+   * @param {string} options.frequency - 'monthly', 'annually', 'weekly', or 'daily' (subscriptions only)
    * @param {boolean} options.trial - Whether to include a trial period (subscriptions only)
    * @param {string} options.confirmationUrl - Success redirect URL
    * @param {string} options.cancelUrl - Cancel redirect URL
@@ -49,13 +49,13 @@ async function createSubscriptionIntent({ uid, orderId, product, frequency, tria
   const eventId = `_test-evt-${timestamp}`;
 
   // Map frequency to Stripe interval
-  const interval = frequency === 'annually' ? 'year' : 'month';
+  const FREQUENCY_TO_INTERVAL = { annually: 'year', monthly: 'month', weekly: 'week', daily: 'day' };
+  const FREQUENCY_TO_PERIOD = { annually: 365 * 86400, monthly: 30 * 86400, weekly: 7 * 86400, daily: 1 * 86400 };
+  const interval = FREQUENCY_TO_INTERVAL[frequency] || 'month';
 
   // Build timestamps
   const now = Math.floor(timestamp / 1000);
-  const periodEnd = frequency === 'annually'
-    ? now + (365 * 86400)
-    : now + (30 * 86400);
+  const periodEnd = now + (FREQUENCY_TO_PERIOD[frequency] || 30 * 86400);
 
   // Build Stripe-shaped subscription object
   // Uses product's Stripe product ID so resolveProduct() can match it

package/src/manager/routes/payments/trial-eligibility/get.js

@@ -0,0 +1,29 @@
+/**
+ * GET /payments/trial-eligibility
+ * Returns whether the authenticated user is eligible for a free trial
+ * Eligible = no previous subscription orders in payments-orders
+ */
+module.exports = async ({ assistant, user, libraries }) => {
+  const { admin } = libraries;
+
+  // Require authentication
+  if (!user.authenticated) {
+    return assistant.respond('Authentication required', { code: 401 });
+  }
+
+  const uid = user.auth.uid;
+
+  // Check for any previous subscription orders
+  const historySnapshot = await admin.firestore()
+    .collection('payments-orders')
+    .where('owner', '==', uid)
+    .where('type', '==', 'subscription')
+    .limit(1)
+    .get();
+
+  const eligible = historySnapshot.empty;
+
+  assistant.log(`Trial eligibility for ${uid}: ${eligible}`);
+
+  return assistant.respond({ eligible });
+};

package/src/manager/schemas/payments/trial-eligibility/get.js

@@ -0,0 +1,5 @@
+/**
+ * Schema: GET /payments/trial-eligibility
+ * No parameters required — uses authenticated user's UID
+ */
+module.exports = () => ({});

package/templates/firestore.rules

@@ -40,11 +40,9 @@ service cloud.firestore {
     }
 
     function getRoles() {
-      // return get(/databases/$(database)/documents/users/$(request.auth.token.email)).data.roles;
       return get(/databases/$(database)/documents/users/$(request.auth.uid)).data.roles;
     }
     function getVerifications() {
-      // return get(/databases/$(database)/documents/users/$(request.auth.token.email)).data.roles;
       return get(/databases/$(database)/documents/users/$(request.auth.uid)).data.verifications;
     }
     function isAdmin() {

package/test/routes/payments/trial-eligibility.js

@@ -0,0 +1,71 @@
+/**
+ * Test: GET /payments/trial-eligibility
+ * Tests trial eligibility check based on subscription order history
+ */
+module.exports = {
+  description: 'Trial eligibility check',
+  type: 'group',
+  timeout: 15000,
+
+  tests: [
+    {
+      name: 'rejects-unauthenticated',
+      async run({ http, assert }) {
+        const response = await http.as('none').get('payments/trial-eligibility');
+
+        assert.isError(response, 401, 'Should reject unauthenticated request');
+      },
+    },
+
+    {
+      name: 'eligible-when-no-orders',
+      async run({ http, assert }) {
+        // Basic user with no subscription history should be eligible
+        const response = await http.as('basic').get('payments/trial-eligibility');
+
+        assert.isSuccess(response, 'Should succeed for authenticated user');
+        assert.equal(response.data.eligible, true, 'Should be eligible with no order history');
+      },
+    },
+
+    {
+      name: 'ineligible-when-has-subscription-history',
+      async run({ http, assert, accounts, firestore }) {
+        const uid = accounts['basic'].uid;
+        const orderDocPath = `payments-orders/_test-trial-eligibility-${uid}`;
+
+        // Create fake subscription order history
+        await firestore.set(orderDocPath, { owner: uid, type: 'subscription', processor: 'test', status: 'cancelled' });
+
+        try {
+          const response = await http.as('basic').get('payments/trial-eligibility');
+
+          assert.isSuccess(response, 'Should succeed for authenticated user');
+          assert.equal(response.data.eligible, false, 'Should be ineligible with subscription history');
+        } finally {
+          await firestore.delete(orderDocPath);
+        }
+      },
+    },
+
+    {
+      name: 'eligible-when-only-non-subscription-orders',
+      async run({ http, assert, accounts, firestore }) {
+        const uid = accounts['basic'].uid;
+        const orderDocPath = `payments-orders/_test-trial-eligibility-onetime-${uid}`;
+
+        // Create a non-subscription order (one-time purchase)
+        await firestore.set(orderDocPath, { owner: uid, type: 'one-time', processor: 'test', status: 'completed' });
+
+        try {
+          const response = await http.as('basic').get('payments/trial-eligibility');
+
+          assert.isSuccess(response, 'Should succeed for authenticated user');
+          assert.equal(response.data.eligible, true, 'Should be eligible — only non-subscription orders');
+        } finally {
+          await firestore.delete(orderDocPath);
+        }
+      },
+    },
+  ],
+};