backend-manager 5.0.88 → 5.0.91

package/CLAUDE.md

@@ -51,13 +51,19 @@ src/
     index.js                          # Main Manager class
     helpers/                          # Helper classes
       assistant.js                    # Request/response handling
-      user.js                         # User property structure
+      user.js                         # User property structure + schema
       analytics.js                    # GA4 integration
       usage.js                        # Rate limiting
       middleware.js                   # Request pipeline
       settings.js                     # Schema validation
       utilities.js                    # Batch operations
       metadata.js                     # Timestamps/tags
+    libraries/
+      payment-processors/             # Shared payment processor utilities
+        stripe.js                     # Stripe SDK init, fetchResource, toUnified*
+        test.js                       # Test processor (delegates to Stripe shapes)
+        order-id.js                   # Order ID generation (XXXX-XXXX-XXXX)
+        resolve-price-id.js           # Shared price ID resolver from config
     functions/core/                   # Built-in functions
       actions/
         api.js                        # Main bm_api handler
@@ -65,14 +71,35 @@ src/
       events/
         auth/                         # Auth event handlers
         firestore/                    # Firestore triggers
+          payments-webhooks/          # Webhook processing pipeline
+            on-write.js               # Orchestrator: fetch→transform→transition→write
+            analytics.js              # Payment analytics tracking (GA4, Meta, TikTok)
+            transitions/              # State transition detection + handlers
+              index.js                # Transition detection logic
+              send-email.js           # Shared email helper for handlers
+              subscription/           # Subscription transition handlers
+              one-time/               # One-time payment transition handlers
       cron/
         daily.js                      # Daily cron runner
         daily/{job}.js                # Individual cron jobs
     routes/                           # Built-in routes
+      payments/
+        intent/                       # POST /payments/intent
+          post.js                     # Intent creation orchestrator
+          processors/                 # Per-processor intent creators
+            stripe.js                 # Stripe Checkout Session creation
+            test.js                   # Test processor (auto-fires webhooks)
+        webhook/                      # POST /payments/webhook
+          post.js                     # Webhook ingestion + Firestore write
+          processors/                 # Per-processor webhook parsers
+            stripe.js                 # Stripe event parsing + categorization
+            test.js                   # Test processor (delegates to Stripe)
     schemas/                          # Built-in schemas
   cli/
     index.js                          # CLI entry point
     commands/                         # CLI commands
+  test/
+    test-accounts.js                  # Test account definitions (static + journey)
 templates/
   backend-manager-config.json         # Config template
 ```
@@ -594,8 +621,10 @@ subscription: {
   },
   payment: {
     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'
+    price: 0,                      // resolved from config (number, e.g., 4.99)
     startDate: { timestamp, timestampUNIX },
     updatedBy: {
       event: { name: null, id: null },
@@ -638,13 +667,14 @@ The `transitions/index.js` module compares the **before** state (current `users/
 | Transition | Before → After | File |
 |---|---|---|
 | `new-subscription` | basic/null → active paid | `transitions/subscription/new-subscription.js` |
-| `trial-started` | basic/null → active paid with trial | `transitions/subscription/trial-started.js` |
 | `payment-failed` | active → suspended | `transitions/subscription/payment-failed.js` |
 | `payment-recovered` | suspended → active | `transitions/subscription/payment-recovered.js` |
 | `cancellation-requested` | pending=false → pending=true | `transitions/subscription/cancellation-requested.js` |
 | `subscription-cancelled` | non-cancelled → cancelled | `transitions/subscription/subscription-cancelled.js` |
 | `plan-changed` | active product A → active product B | `transitions/subscription/plan-changed.js` |
 
+Note: Trials are NOT a separate transition. The `new-subscription` handler checks `after.trial.claimed` to determine if the subscription started with a trial.
+
 ### One-Time Transitions
 
 | Transition | Event Type | File |
@@ -672,6 +702,107 @@ module.exports = async function ({ before, after, uid, userDoc, admin, assistant
 2. Create handler file in `transitions/{category}/{name}.js`
 3. Handler receives full context — use `assistant.log()` for logging, `Manager.project.apiUrl` for API calls
 
+## Payment System Architecture
+
+### Pipeline
+
+The payment system follows a linear pipeline: **Intent → Webhook → On-Write → Transition**.
+
+1. **Intent** (`POST /payments/intent`): Client requests a payment session. BEM validates the product, generates an order ID (`XXXX-XXXX-XXXX`), and delegates to the processor module (e.g., Stripe creates a Checkout Session). Saves to `payments-intents/{orderId}`.
+
+2. **Webhook** (`POST /payments/webhook?processor=X&key=Y`): Processor sends event data. BEM parses and categorizes the event (`subscription` or `one-time`), extracts the UID, and saves to `payments-webhooks/{eventId}` with `status: 'pending'`.
+
+3. **On-Write** (Firestore trigger on `payments-webhooks/{eventId}`): Fetches the latest resource from the processor API (not stale webhook data), transforms it into a unified object, detects state transitions, dispatches handlers, tracks analytics, and writes to `users/{uid}.subscription` (subscriptions) and `payments-orders/{orderId}`.
+
+4. **Transitions** (fire-and-forget): Handler files run asynchronously after detection. Failures never block webhook processing. Skipped during tests unless `TEST_EXTENDED_MODE` is set.
+
+### Processor Interface
+
+Each processor implements two modules:
+
+**Intent processor** (`routes/payments/intent/processors/{processor}.js`):
+```javascript
+module.exports = {
+  async createIntent({ uid, orderId, product, productId, frequency, trial, confirmationUrl, cancelUrl, Manager, assistant }) {
+    return { id, url, raw };
+  },
+};
+```
+
+**Webhook processor** (`routes/payments/webhook/processors/{processor}.js`):
+```javascript
+module.exports = {
+  isSupported(eventType) { return boolean; },
+  parseWebhook(req) { return { eventId, eventType, category, resourceType, resourceId, raw, uid }; },
+};
+```
+
+**Shared library** (`libraries/payment-processors/{processor}.js`):
+```javascript
+module.exports = {
+  init() { /* return SDK instance */ },
+  async fetchResource(resourceType, resourceId, rawFallback, context) { /* return resource */ },
+  toUnifiedSubscription(rawSubscription, options) { /* return unified object */ },
+  toUnifiedOneTime(rawResource, options) { /* return unified object */ },
+};
+```
+
+### Product Configuration
+
+Products are defined in `backend-manager-config.json` under `payment.products`:
+
+```javascript
+payment: {
+  products: [
+    {
+      id: 'basic',           // Free tier (no prices)
+      name: 'Basic',
+      type: 'subscription',
+      limits: { requests: 100 },
+    },
+    {
+      id: 'premium',         // Paid subscription
+      name: 'Premium',
+      type: 'subscription',
+      limits: { requests: 1000 },
+      trial: { days: 14 },   // Optional trial period
+      prices: {
+        monthly:  { amount: 4.99,  stripe: 'price_xxx', paypal: null },
+        annually: { amount: 49.99, stripe: 'price_yyy', paypal: null },
+      },
+    },
+    {
+      id: 'credits-100',     // One-time purchase
+      name: '100 Credits',
+      type: 'one-time',
+      prices: {
+        once: { amount: 9.99, stripe: 'price_zzz' },
+      },
+    },
+  ],
+}
+```
+
+Key rules:
+- `type` is `'subscription'` (default) or `'one-time'`
+- Subscription prices are keyed by frequency: `monthly`, `annually`
+- One-time prices are keyed as `once`
+- Each price object has processor-specific IDs (`stripe`, `paypal`, etc.)
+- `basic` product has no `prices` — it's the free tier
+
+### Firestore Collections
+
+| Collection | Key | Purpose |
+|---|---|---|
+| `payments-intents/{orderId}` | Order ID | Intent metadata (processor, product, status) |
+| `payments-webhooks/{eventId}` | Processor event ID | Webhook processing state + transition result |
+| `payments-orders/{orderId}` | Order ID | Unified order data (single source of truth for orders) |
+| `users/{uid}.subscription` | User UID | Current subscription state (subscriptions only) |
+
+### Test Processor
+
+The `test` processor generates Stripe-shaped data and auto-fires webhooks to the local server. Only available in non-production environments. Use `processor: 'test'` in intent requests during testing. The test webhook processor delegates to Stripe's parser since it generates Stripe-shaped payloads.
+
 ## Common Mistakes to Avoid
 
 1. **Don't modify Manager internals directly** - Use factory methods and public APIs

package/README.md

@@ -886,7 +886,7 @@ BEM includes a built-in payment/subscription system with Stripe integration (ext
 
 ### Unified Subscription Object
 
-The same subscription shape is stored in `users/{uid}.subscription` and `payments-subscriptions/{subId}.subscription`:
+The same subscription shape is stored in `users/{uid}.subscription` and `payments-orders/{orderId}.subscription`:
 
 ```javascript
 subscription: {

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "backend-manager",
-  "version": "5.0.88",
+  "version": "5.0.91",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {
-    "bem": "./bin/bem",
-    "bm": "./bin/bem"
+    "bm": "./bin/backend-manager",
+    "bem": "./bin/backend-manager",
+    "backend-manager": "./bin/backend-manager",
+    "mgr": "./bin/backend-manager"
   },
   "scripts": {
     "start": "node src/manager/index.js",

package/src/cli/index.js

@@ -1,6 +1,17 @@
+const os = require('os');
+const path = require('path');
 const argv = require('yargs').argv;
 const _ = require('lodash');
 
+// Abort if running from ~/node_modules (accidental home directory install)
+const _homeDir = os.homedir();
+if (__dirname.startsWith(path.join(_homeDir, 'node_modules'))) {
+  console.error(`\nERROR: BEM is running from ~/node_modules (home directory install).`);
+  console.error(`This shadows the local project copy. Fix:`);
+  console.error(`  rm -rf ~/node_modules ~/package.json ~/package-lock.json\n`);
+  process.exit(1);
+}
+
 // Import commands
 const VersionCommand = require('./commands/version');
 const ClearCommand = require('./commands/clear');

package/src/manager/events/firestore/payments-webhooks/analytics.js

@@ -0,0 +1,170 @@
+/**
+ * Payment analytics tracking
+ * Fires server-side events for GA4, Meta Conversions API, and TikTok Events API
+ *
+ * Maps transitions to standard platform events:
+ *   new-subscription (no trial) → purchase / Purchase / CompletePayment
+ *   new-subscription (trial)    → start_trial / StartTrial / Subscribe
+ *   payment-recovered           → purchase / Subscribe / Subscribe (recurring)
+ *   purchase-completed          → purchase / Purchase / CompletePayment
+ */
+
+/**
+ * Track payment events across analytics platforms (non-blocking)
+ *
+ * @param {object} options
+ * @param {string} options.category - 'subscription' or 'one-time'
+ * @param {string} options.transitionName - Detected transition (e.g., 'new-subscription', 'purchase-completed')
+ * @param {object} options.unified - Unified subscription or one-time object
+ * @param {string} options.uid - User ID
+ * @param {string} options.processor - Payment processor (e.g., 'stripe', 'paypal')
+ * @param {object} options.assistant - Assistant instance
+ * @param {object} options.Manager - Manager instance
+ */
+function trackPayment({ category, transitionName, unified, uid, processor, assistant, Manager }) {
+  try {
+    // Resolve the analytics event to fire based on transition
+    const event = resolvePaymentEvent(category, transitionName, unified, Manager.config);
+
+    if (!event) {
+      return;
+    }
+
+    assistant.log(`trackPayment: event=${event.ga4}, value=${event.value}, currency=${event.currency}, product=${event.productId}, uid=${uid}`);
+
+    // GA4 via Measurement Protocol
+    Manager.Analytics({ assistant, uuid: uid }).event(event.ga4, {
+      transaction_id: event.transactionId,
+      value: event.value,
+      currency: event.currency,
+      items: [{
+        item_id: event.productId,
+        item_name: event.productName,
+        price: event.value,
+        quantity: 1,
+      }],
+      payment_processor: processor,
+      payment_frequency: event.frequency,
+      is_trial: event.isTrial,
+      is_recurring: event.isRecurring,
+    });
+
+    // TODO: Meta Conversions API
+    // Event name: event.meta (e.g., 'Purchase', 'StartTrial', 'Subscribe')
+    // https://developers.facebook.com/docs/marketing-api/conversions-api
+
+    // TODO: TikTok Events API
+    // Event name: event.tiktok (e.g., 'CompletePayment', 'Subscribe')
+    // https://business-api.tiktok.com/portal/docs?id=1771100865818625
+  } catch (e) {
+    assistant.error(`trackPayment failed: ${e.message}`, e);
+  }
+}
+
+/**
+ * Resolve which analytics event to fire based on transition + unified data
+ * Returns null if the transition doesn't warrant an analytics event
+ */
+function resolvePaymentEvent(category, transitionName, unified, config) {
+  if (category === 'subscription') {
+    return resolveSubscriptionEvent(transitionName, unified, config);
+  }
+
+  if (category === 'one-time') {
+    return resolveOneTimeEvent(transitionName, unified, config);
+  }
+
+  return null;
+}
+
+/**
+ * Map subscription transitions to analytics events
+ */
+function resolveSubscriptionEvent(transitionName, unified, config) {
+  const productId = unified.product?.id;
+  const productName = unified.product?.name;
+  const frequency = unified.payment?.frequency;
+  const isTrial = unified.trial?.claimed === true;
+  const resourceId = unified.payment?.resourceId;
+  const price = unified.payment?.price || 0;
+
+  if (transitionName === 'new-subscription' && isTrial) {
+    return {
+      ga4: 'start_trial',
+      meta: 'StartTrial',
+      tiktok: 'Subscribe',
+      value: 0,
+      currency: config.payment?.currency || 'USD',
+      productId,
+      productName,
+      frequency,
+      isTrial: true,
+      isRecurring: false,
+      transactionId: resourceId,
+    };
+  }
+
+  if (transitionName === 'new-subscription') {
+    return {
+      ga4: 'purchase',
+      meta: 'Purchase',
+      tiktok: 'CompletePayment',
+      value: price,
+      currency: config.payment?.currency || 'USD',
+      productId,
+      productName,
+      frequency,
+      isTrial: false,
+      isRecurring: false,
+      transactionId: resourceId,
+    };
+  }
+
+  if (transitionName === 'payment-recovered') {
+    return {
+      ga4: 'purchase',
+      meta: 'Subscribe',
+      tiktok: 'Subscribe',
+      value: price,
+      currency: config.payment?.currency || 'USD',
+      productId,
+      productName,
+      frequency,
+      isTrial: false,
+      isRecurring: true,
+      transactionId: resourceId,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Map one-time transitions to analytics events
+ */
+function resolveOneTimeEvent(transitionName, unified, config) {
+  if (transitionName !== 'purchase-completed') {
+    return null;
+  }
+
+  const productId = unified.product?.id;
+  const productName = unified.product?.name;
+  const price = unified.payment?.price || 0;
+  const resourceId = unified.payment?.resourceId;
+
+  return {
+    ga4: 'purchase',
+    meta: 'Purchase',
+    tiktok: 'CompletePayment',
+    value: price,
+    currency: config.payment?.currency || 'USD',
+    productId: productId || 'unknown',
+    productName: productName || 'Unknown',
+    frequency: null,
+    isTrial: false,
+    isRecurring: false,
+    transactionId: resourceId,
+  };
+}
+
+module.exports = { trackPayment };