backend-manager 5.0.84 → 5.0.86

package/CHANGELOG.md

@@ -14,6 +14,40 @@ 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.84] - 2026-02-19
+### BREAKING
+- Moved `config.products` to `config.payment.products`. All product lookups now use `config.payment.products`.
+- Renamed `subscription.trial.activated` to `subscription.trial.claimed` across the entire subscription schema, API responses, analytics properties, and tests.
+- Renamed analytics user property `plan_id` to `subscription_id` and `plan_trial_activated` to `subscription_trial_claimed`.
+- Removed `Manager.getApp()` method (previously fetched from ITW Creative Works endpoint).
+- Removed `Manager.SubscriptionResolver()` factory method.
+- Removed deprecated `RUNTIME_CONFIG` .env loading from config merge.
+- Test accounts now use `subscription.*` instead of `plan.*`.
+
+### Added
+- Stripe payment integration with shared library (`src/manager/libraries/stripe.js`) and `toUnified()` transformer that maps Stripe subscription states to the unified subscription schema.
+- Test payment processor library that delegates to Stripe's transformer with `processor: 'test'`.
+- Payment webhook route (`POST /payments/webhook`) with processor-specific handlers for Stripe (with signature verification) and test, including idempotent event storage in `payments-webhooks` Firestore collection.
+- Payment intent route (`POST /payments/intent`) for creating checkout sessions with processor-specific handlers.
+- Firestore trigger (`bm_paymentsWebhookOnWrite`) that processes stored webhook events and updates user subscription documents.
+- Payment schemas for webhook and intent validation.
+- `payment.processors` config section for Stripe, PayPal, Chargebee, and Coinbase configuration.
+- `npx bm stripe` CLI command for standalone Stripe webhook forwarding.
+- Auto-start Stripe CLI webhook forwarding with `npx bm emulators` (gracefully skips when prerequisites are missing).
+- `Manager.version` property exposing the BEM package version.
+- Journey test accounts for payment lifecycle testing (upgrade, cancel, suspend, trial).
+- Stripe fixture data for subscription states (active, trialing, canceled).
+- Tests for `stripe-to-unified` transformer, payment webhook route, and payment intent route.
+- Test cleanup for payment-related Firestore collections (`payments-subscriptions`, `payments-webhooks`, `payments-intents`).
+
+### Changed
+- Cron schedule from `every 24 hours` to `0 0 * * *` (explicit midnight UTC).
+- Test runner now passes full config object (with convenience aliases) for payment processor access.
+- Unauthenticated usage tests now use relative assertions instead of absolute values.
+
+### Removed
+- Removed `PAYPAL_CLIENT_ID` and `CHARGEBEE_SITE` from `.env` template (now configured via `payment.processors` in config).
+
 # [5.0.39] - 2025-01-12
 ### Added
 - New test infrastructure with Firebase emulator support for reliable, isolated testing.

package/CLAUDE.md

@@ -490,6 +490,67 @@ assert.fail(message)                           // Explicit fail
 | `src/test/utils/http-client.js` | HTTP client |
 | `src/test/test-accounts.js` | Test account definitions |
 
+## Stripe Webhook Forwarding
+
+BEM auto-starts Stripe CLI webhook forwarding when running `npx bm serve` or `npx bm emulators`. This forwards Stripe test webhooks to the local server so the full payment pipeline works end-to-end during development.
+
+**Requirements:**
+- `STRIPE_SECRET_KEY` set in `functions/.env`
+- `BACKEND_MANAGER_KEY` set in `functions/.env`
+- [Stripe CLI](https://stripe.com/docs/stripe-cli) installed
+
+**Standalone usage:**
+```bash
+npx bm stripe
+```
+
+If any prerequisite is missing, webhook forwarding is silently skipped with an info message.
+
+The forwarding URL is: `http://localhost:{hostingPort}/backend-manager/payments/webhook?processor=stripe&key={BACKEND_MANAGER_KEY}`
+
+## Usage & Rate Limiting
+
+### Overview
+
+Usage is tracked per-metric (e.g., `requests`, `marketing-subscribe`) with two counters:
+- `period`: Current month's count, reset on the 1st of each month
+- `total`: All-time count, never resets
+
+### Product Rate Limit Modes
+
+Products can set a `rateLimit` field to control how limits are enforced:
+
+| Value | Behavior | Default |
+|-------|----------|---------|
+| `'monthly'` | Full monthly limit available at any time | Yes |
+| `'daily'` | Proportional daily cap: `ceil(limit * dayOfMonth / daysInMonth)` | No |
+
+Example config (not in the template — add per-product as needed):
+```json
+{
+  "id": "basic",
+  "limits": { "requests": 100 },
+  "rateLimit": "daily"
+}
+```
+
+With `rateLimit: 'daily'` and 100 requests/month in a 30-day month:
+- Day 1: max 4 requests used so far
+- Day 15: max 50 requests used so far
+- Day 30: max 100 requests (full allocation)
+
+Unused days roll forward — a user who doesn't use the product for 2 weeks can use a burst later.
+
+### Reset Schedule
+
+| Target | Frequency | What happens |
+|--------|-----------|-------------|
+| Local storage | Daily | Cleared entirely |
+| `usage` collection (unauthenticated) | Daily | Deleted entirely |
+| User doc `usage.*.period` (authenticated) | Monthly (1st) | Reset to 0 |
+
+The daily cron runs at midnight UTC (`0 0 * * *`). Authenticated user period resets only execute on the 1st of the month.
+
 ## Subscription System
 
 ### Subscription Statuses
@@ -505,7 +566,7 @@ assert.fail(message)                           // Explicit fail
 | Stripe Status | `subscription.status` | Notes |
 |---|---|---|
 | `active` | `active` | Normal active subscription |
-| `trialing` | `active` | `trial.activated = true` |
+| `trialing` | `active` | `trial.claimed = true` |
 | `past_due` | `suspended` | Payment failed, retrying |
 | `unpaid` | `suspended` | Payment failed |
 | `canceled` | `cancelled` | Subscription terminated |
@@ -524,7 +585,7 @@ subscription: {
   status: 'active',                // 'active' | 'suspended' | 'cancelled'
   expires: { timestamp, timestampUNIX },
   trial: {
-    activated: false,              // has user EVER used a trial
+    claimed: false,                // has user EVER used a trial
     expires: { timestamp, timestampUNIX },
   },
   cancellation: {
@@ -551,7 +612,7 @@ subscription: {
 user.subscription.status === 'active' && user.subscription.product.id !== 'basic'
 
 // Is on trial?
-user.subscription.trial.activated && user.subscription.status === 'active'
+user.subscription.trial.claimed && user.subscription.status === 'active'
 
 // Has pending cancellation?
 user.subscription.cancellation.pending === true
@@ -592,6 +653,8 @@ user.subscription.status === 'suspended'
 | Main API handler | `src/manager/functions/core/actions/api.js` |
 | Config template | `templates/backend-manager-config.json` |
 | CLI entry | `src/cli/index.js` |
+| Stripe webhook forwarding | `src/cli/commands/stripe.js` |
+| Stripe shared library | `src/manager/libraries/stripe.js` |
 
 ## Environment Detection
 

package/README.md

@@ -464,7 +464,7 @@ const userProps = Manager.User(existingData, { defaults: true }).properties;
     product: { id, name },   // product from config ('basic', 'premium', etc.)
     status: 'active',        // active | suspended | cancelled
     expires: { timestamp, timestampUNIX },
-    trial: { activated, expires: {...} },
+    trial: { claimed, expires: {...} },
     cancellation: { pending, date: {...} },
     limits: {},
     payment: { processor, resourceId, frequency, startDate, updatedBy }
@@ -501,7 +501,7 @@ analytics.event('purchase', {
 
 **Auto-tracked User Properties:**
 - `app_version`, `device_category`, `operating_system`, `platform`
-- `authenticated`, `plan_id`, `plan_trial_activated`, `activity_created`
+- `authenticated`, `subscription_id`, `subscription_trial_claimed`, `activity_created`
 - `country`, `city`, `language`, `age`, `gender`
 
 ### Usage
@@ -734,6 +734,7 @@ npx backend-manager <command>
 | `bem deploy` | Deploy functions to Firebase |
 | `bem test [paths...]` | Run integration tests |
 | `bem emulators` | Start Firebase emulators (keep-alive mode) |
+| `bem stripe` | Start Stripe CLI webhook forwarding to local server |
 | `bem version`, `bem v` | Show BEM version |
 | `bem clear` | Clear cache and temp files |
 | `bem install`, `bem i` | Install BEM (local or production) |
@@ -748,6 +749,7 @@ Set these in your `functions/.env` file:
 | Variable | Description |
 |----------|-------------|
 | `BACKEND_MANAGER_KEY` | Admin authentication key |
+| `STRIPE_SECRET_KEY` | Stripe secret key (enables auto webhook forwarding in `serve`/`emulators`) |
 
 ## Response Headers
 
@@ -874,7 +876,7 @@ BEM includes a built-in payment/subscription system with Stripe integration (ext
 | Stripe Status | `subscription.status` | Notes |
 |---|---|---|
 | `active` | `active` | Normal active subscription |
-| `trialing` | `active` | `trial.activated = true` |
+| `trialing` | `active` | `trial.claimed = true` |
 | `past_due` | `suspended` | Payment failed, retrying |
 | `unpaid` | `suspended` | Payment failed |
 | `canceled` | `cancelled` | Subscription terminated |
@@ -895,7 +897,7 @@ subscription: {
   status: 'active',                // 'active' | 'suspended' | 'cancelled'
   expires: { timestamp, timestampUNIX },
   trial: {
-    activated: false,              // has user EVER used a trial
+    claimed: false,                // has user EVER used a trial
     expires: { timestamp, timestampUNIX },
   },
   cancellation: {
@@ -922,7 +924,7 @@ subscription: {
 user.subscription.status === 'active' && user.subscription.product.id !== 'basic'
 
 // Is on trial?
-user.subscription.trial.activated && user.subscription.status === 'active'
+user.subscription.trial.claimed && user.subscription.status === 'active'
 
 // Has pending cancellation?
 user.subscription.cancellation.pending === true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.84",
+  "version": "5.0.86",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {
@@ -44,8 +44,8 @@
   },
   "dependencies": {
     "@firebase/rules-unit-testing": "^5.0.0",
-    "@google-cloud/pubsub": "^5.2.2",
-    "@google-cloud/storage": "^7.18.0",
+    "@google-cloud/pubsub": "^5.3.0",
+    "@google-cloud/storage": "^7.19.0",
     "@octokit/rest": "^19.0.13",
     "@sendgrid/mail": "^7.7.0",
     "@sentry/node": "^6.19.7",
@@ -75,6 +75,7 @@
     "paypal-server-api": "^2.0.14",
     "pushid": "^1.0.0",
     "shortid": "^2.2.17",
+    "stripe": "^20.3.1",
     "uid-generator": "^2.0.0",
     "uuid": "^9.0.1",
     "wonderful-fetch": "^1.3.4",
@@ -89,7 +90,7 @@
     "sinon": "^21.0.1"
   },
   "peerDependencies": {
-    "firebase-admin": "^13.6.0",
+    "firebase-admin": "^13.6.1",
     "firebase-functions": "^7.0.5"
   }
 }

package/src/cli/commands/base-command.js

@@ -156,6 +156,95 @@ class BaseCommand {
   isPortInUse(port) {
     return this.getProcessOnPort(port) !== null;
   }
+
+  /**
+   * Start Stripe CLI webhook forwarding in the background
+   * Forwards Stripe test webhooks to the local server
+   * Gracefully skips if stripe CLI or STRIPE_SECRET_KEY is missing
+   * @returns {object|null} - Child process handle or null if skipped
+   */
+  startStripeWebhookForwarding() {
+    const projectDir = this.main.firebaseProjectPath;
+    const functionsDir = path.join(projectDir, 'functions');
+
+    // Load .env so STRIPE_SECRET_KEY and BACKEND_MANAGER_KEY are available
+    const envPath = path.join(functionsDir, '.env');
+    if (jetpack.exists(envPath)) {
+      require('dotenv').config({ path: envPath });
+    }
+
+    // Check for Stripe secret key
+    if (!process.env.STRIPE_SECRET_KEY) {
+      this.log(chalk.gray('  (Stripe webhook forwarding disabled - STRIPE_SECRET_KEY not set in .env)\n'));
+      return null;
+    }
+
+    // Check for Backend Manager key
+    if (!process.env.BACKEND_MANAGER_KEY) {
+      this.log(chalk.gray('  (Stripe webhook forwarding disabled - BACKEND_MANAGER_KEY not set in .env)\n'));
+      return null;
+    }
+
+    // Check if stripe CLI is installed
+    let stripePath;
+    try {
+      stripePath = execSync('which stripe', { encoding: 'utf8' }).trim();
+    } catch (e) {
+      this.log(chalk.gray('  (Stripe webhook forwarding disabled - install Stripe CLI: https://stripe.com/docs/stripe-cli)\n'));
+      return null;
+    }
+
+    // Resolve hosting port from firebase.json (default 5002)
+    let hostingPort = 5002;
+    const firebaseJsonPath = path.join(projectDir, 'firebase.json');
+    if (jetpack.exists(firebaseJsonPath)) {
+      try {
+        const JSON5 = require('json5');
+        const firebaseConfig = JSON5.parse(jetpack.read(firebaseJsonPath));
+        hostingPort = firebaseConfig.emulators?.hosting?.port || hostingPort;
+      } catch (e) {
+        // Use default
+      }
+    }
+
+    const forwardUrl = `http://localhost:${hostingPort}/backend-manager/payments/webhook?processor=stripe&key=${process.env.BACKEND_MANAGER_KEY}`;
+
+    this.log(chalk.gray(`  Stripe webhook forwarding -> localhost:${hostingPort}\n`));
+
+    const stripeProcess = spawn(stripePath, [
+      'listen',
+      '--forward-to', forwardUrl,
+      '--api-key', process.env.STRIPE_SECRET_KEY,
+    ], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: false,
+    });
+
+    // Prefix output with [Stripe]
+    const prefixStream = (stream) => {
+      stream.on('data', (data) => {
+        const lines = data.toString().split('\n').filter(l => l.trim());
+        for (const line of lines) {
+          console.log(chalk.gray(`  [Stripe] ${line}`));
+        }
+      });
+    };
+
+    prefixStream(stripeProcess.stdout);
+    prefixStream(stripeProcess.stderr);
+
+    stripeProcess.on('error', (error) => {
+      this.log(chalk.yellow(`  [Stripe] Error: ${error.message}`));
+    });
+
+    stripeProcess.on('close', (code) => {
+      if (code !== 0 && code !== null) {
+        this.log(chalk.yellow(`  [Stripe] Exited with code ${code}`));
+      }
+    });
+
+    return stripeProcess;
+  }
 }
 
 module.exports = BaseCommand;

package/src/cli/commands/emulators.js

@@ -23,6 +23,9 @@ class EmulatorsCommand extends BaseCommand {
     const watcher = new WatchCommand(this.main);
     watcher.startBackground();
 
+    // Start Stripe webhook forwarding in background
+    this.startStripeWebhookForwarding();
+
     // Run emulators with keep-alive command (use single quotes since runWithEmulators wraps in double quotes)
     const keepAliveCommand = "echo ''; echo 'Emulators ready. Press Ctrl+C to shut down...'; sleep 86400";
 

package/src/cli/commands/serve.js

@@ -11,9 +11,13 @@ class ServeCommand extends BaseCommand {
     const watcher = new WatchCommand(self);
     watcher.startBackground();
 
+    // Start Stripe webhook forwarding in background
+    // Ignored because we cant really fully process them unless the emulator is running
+    // this.startStripeWebhookForwarding();
+
     // Execute
     await powertools.execute(`firebase serve --port ${port}`, { log: true });
   }
 }
 
-module.exports = ServeCommand;
+module.exports = ServeCommand;

package/src/cli/commands/stripe.js

@@ -0,0 +1,14 @@
+const BaseCommand = require('./base-command');
+
+class StripeCommand extends BaseCommand {
+  async execute() {
+    const stripeProcess = this.startStripeWebhookForwarding();
+
+    if (stripeProcess) {
+      // Keep alive until Ctrl+C
+      await new Promise(() => {});
+    }
+  }
+}
+
+module.exports = StripeCommand;

package/src/cli/commands/test.js

@@ -102,14 +102,10 @@ class TestCommand extends BaseCommand {
       return null;
     }
 
-    // Extract values from expected config structure
+    // Derive convenience values
     const projectId = config.firebaseConfig?.projectId;
     const backendManagerKey = argv.key || process.env.BACKEND_MANAGER_KEY;
     const appId = config.brand?.id;
-    const brandName = config.brand?.name;
-    const githubRepoWebsite = config.github?.repo_website;
-
-    // Extract domain from brand.contact.email (e.g., 'support@example.com' -> 'example.com')
     const contactEmail = config.brand?.contact?.email || '';
     const domain = contactEmail.includes('@') ? contactEmail.split('@')[1] : '';
 
@@ -135,7 +131,16 @@ class TestCommand extends BaseCommand {
       return null;
     }
 
-    return { appId, projectId, backendManagerKey, domain, brandName, githubRepoWebsite };
+    // Pass entire config + convenience aliases used by runner/helpers
+    return {
+      ...config,
+      appId,
+      projectId,
+      backendManagerKey,
+      domain,
+      brandName: config.brand?.name,
+      githubRepoWebsite: config.github?.repo_website,
+    };
   }
 
   /**

package/src/cli/index.js

@@ -14,6 +14,7 @@ const EmulatorsCommand = require('./commands/emulators');
 const CleanCommand = require('./commands/clean');
 const IndexesCommand = require('./commands/indexes');
 const WatchCommand = require('./commands/watch');
+const StripeCommand = require('./commands/stripe');
 
 function Main() {}
 
@@ -111,6 +112,12 @@ Main.prototype.process = async function (args) {
     const cmd = new WatchCommand(self);
     return await cmd.execute();
   }
+
+  // Stripe webhook forwarding (standalone)
+  if (self.options['stripe'] || self.options['stripe:listen']) {
+    const cmd = new StripeCommand(self);
+    return await cmd.execute();
+  }
 };
 
 // Test method for setup command

package/src/manager/cron/daily/reset-usage.js

@@ -1,56 +1,86 @@
 /**
  * Reset usage cron job
  *
- * Resets daily usage counters in both local storage and Firestore.
+ * Runs daily at midnight UTC and handles different reset schedules:
+ * - Local storage: cleared every day
+ * - Unauthenticated usage collection: deleted every day
+ * - Authenticated user period counters: reset on the 1st (or 2nd as grace window) of each month
  */
 module.exports = async ({ Manager, assistant, context, libraries }) => {
   const storage = Manager.storage({ name: 'usage', temporary: true, clear: false, log: false });
 
   assistant.log('Starting...');
 
-  // Clear local
+  // Clear local storage (daily)
   await clearLocal(assistant, storage);
 
-  // Clear firestore
-  await clearFirestore(Manager, assistant, libraries);
+  // Clear unauthenticated usage collection (daily)
+  await clearUnauthenticatedUsage(assistant, libraries);
+
+  // Reset authenticated user periods (monthly - 1st or 2nd of month)
+  await resetAuthenticatedUsage(Manager, assistant, libraries);
 };
 
 async function clearLocal(assistant, storage) {
-  // Log status
   assistant.log('[local]: Starting...');
 
-  // Log storage
   assistant.log('[local]: storage(apps)', storage.get('apps', {}).value());
   assistant.log('[local]: storage(users)', storage.get('users', {}).value());
 
   // Clear storage
   storage.setState({}).write();
 
-  // Log status
   assistant.log('[local]: Completed!');
 }
 
-async function clearFirestore(Manager, assistant, libraries) {
+async function clearUnauthenticatedUsage(assistant, libraries) {
+  const { admin } = libraries;
+
+  assistant.log('[unauthenticated]: Deleting usage collection...');
+
+  await admin.firestore().recursiveDelete(admin.firestore().collection('usage'))
+  .then(() => {
+    assistant.log('[unauthenticated]: Deleted usage collection');
+  })
+  .catch((e) => {
+    assistant.errorify(`Error deleting usage collection: ${e}`, { code: 500, log: true });
+  });
+}
+
+async function resetAuthenticatedUsage(Manager, assistant, libraries) {
   const { admin } = libraries;
+  const dayOfMonth = new Date().getDate();
 
-  // Log status
-  assistant.log('[firestore]: Starting...');
+  // Only reset on the 1st of the month
+  if (dayOfMonth !== 1) {
+    assistant.log('[authenticated]: Skipping period reset (not the 1st of the month)');
+    return;
+  }
+
+  assistant.log('[authenticated]: Monthly reset starting...');
+
+  // Gather all unique metric names from ALL products
+  const products = Manager.config.payment?.products || [];
+  const metrics = {};
+
+  for (const product of products) {
+    const limits = product.limits || {};
+
+    for (const key of Object.keys(limits)) {
+      metrics[key] = true;
+    }
+  }
 
-  // Get metric names from the basic product in config
-  const products = Manager.config.products || [];
-  const basicProduct = products.find(p => p.id === 'basic') || {};
-  const metrics = { ...(basicProduct.limits || {}) };
+  // Ensure requests is always included
+  metrics.requests = true;
 
-  // Ensure requests is always included as a default metric
-  metrics.requests = metrics.requests || 1;
+  const metricNames = Object.keys(metrics);
 
-  // Log status
-  assistant.log('[firestore]: Resetting metrics', metrics);
+  assistant.log('[authenticated]: Resetting metrics', metricNames);
 
-  // Reset all metrics with for loop of metrics
-  // TODO: OPTIMIZATION: Put all of the changes into a single batch
-  for (const metric of Object.keys(metrics)) {
-    assistant.log(`[firestore]: Resetting ${metric} for all users`);
+  // Reset each metric for users who have usage > 0
+  for (const metric of metricNames) {
+    assistant.log(`[authenticated]: Resetting ${metric} for all users`);
 
     await Manager.Utilities().iterateCollection((batch, index) => {
       return new Promise(async (resolve, reject) => {
@@ -64,7 +94,7 @@ async function clearFirestore(Manager, assistant, libraries) {
           data.usage[metric].total = data.usage[metric].total || 0;
           data.usage[metric].last = data.usage[metric].last || {};
 
-          // Yeet if its 0
+          // Skip if already 0
           if (data.usage[metric].period <= 0) {
             continue;
           }
@@ -76,14 +106,13 @@ async function clearFirestore(Manager, assistant, libraries) {
           // Update the doc
           await doc.ref.update({ usage: data.usage })
           .then(r => {
-            assistant.log(`[firestore]: Reset ${metric} for ${doc.id} (${original} -> 0)`);
+            assistant.log(`[authenticated]: Reset ${metric} for ${doc.id} (${original} -> 0)`);
           })
           .catch(e => {
             assistant.errorify(`Error resetting ${metric} for ${doc.id}: ${e}`, { code: 500, log: true });
           });
         }
 
-        // Complete
         return resolve();
       });
     }, {
@@ -95,19 +124,12 @@ async function clearFirestore(Manager, assistant, libraries) {
       log: true,
     })
     .then((r) => {
-      assistant.log(`[firestore]: Reset ${metric} for all users complete!`);
+      assistant.log(`[authenticated]: Reset ${metric} for all users complete!`);
     })
     .catch(e => {
       assistant.errorify(`Error resetting ${metric} for all users: ${e}`, { code: 500, log: true });
     });
   }
 
-  // Clear usage in firestore by deleting the entire collection
-  await admin.firestore().recursiveDelete(admin.firestore().collection('usage'))
-  .then(() => {
-    assistant.log('[firestore]: Deleted usage collection');
-  })
-  .catch((e) => {
-    assistant.errorify(`Error deleting usage collection: ${e}`, { code: 500, log: true });
-  });
+  assistant.log('[authenticated]: Monthly reset completed!');
 }

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

@@ -4,7 +4,7 @@ const powertools = require('node-powertools');
  * Firestore trigger: payments-webhooks/{eventId} onWrite
  *
  * Processes pending webhook events:
- * 1. Transforms raw provider data into unified subscription object
+ * 1. Transforms raw processor data into unified subscription object
  * 2. Updates the user's subscription in users/{uid}
  * 3. Stores the subscription doc in payments-subscriptions/{resourceId}
  * 4. Marks the webhook as completed
@@ -31,12 +31,14 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
     const raw = dataAfter.raw;
     const eventType = dataAfter.event?.type;
 
+    assistant.log(`Processing webhook ${eventId}: processor=${processor}, eventType=${eventType}, uid=${uid || 'null'}`);
+
     // Validate UID
     if (!uid) {
       throw new Error('Webhook event has no UID — cannot process');
     }
 
-    // Load and initialize the shared library for this processor
+    // Load the shared library for this processor (only needs toUnified, not SDK init)
     let library;
     try {
       library = require(`../../../libraries/${processor}.js`);
@@ -44,12 +46,12 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
       throw new Error(`Unknown processor library: ${processor}`);
     }
 
-    library.init();
-
     // Extract the subscription object from the raw event
     // Stripe sends events with event.data.object as the subscription
     const rawSubscription = raw.data?.object || {};
 
+    assistant.log(`Raw subscription: stripeStatus=${rawSubscription.status}, cancelAtPeriodEnd=${rawSubscription.cancel_at_period_end}, trialEnd=${rawSubscription.trial_end || 'none'}, resourceId=${rawSubscription.id}`);
+
     // Transform raw data into unified subscription object
     const unified = library.toUnified(rawSubscription, {
       config: Manager.config,
@@ -57,13 +59,7 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
       eventId: eventId,
     });
 
-    assistant.log(`Processing webhook ${eventId}:`, {
-      processor,
-      uid,
-      eventType,
-      productId: unified.product.id,
-      status: unified.status,
-    });
+    assistant.log(`Unified result: status=${unified.status}, product=${unified.product.id}, frequency=${unified.payment.frequency}, trial.claimed=${unified.trial.claimed}, cancellation.pending=${unified.cancellation.pending}`);
 
     // Build timestamps
     const now = powertools.timestamp(new Date(), { output: 'string' });
@@ -74,6 +70,8 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
       subscription: unified,
     }, { merge: true });
 
+    assistant.log(`Updated users/${uid}.subscription: status=${unified.status}, product=${unified.product.id}`);
+
     // Write to payments-subscriptions/{resourceId}
     const resourceId = unified.payment.resourceId;
     if (resourceId) {
@@ -99,6 +97,10 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
           },
         },
       }, { merge: true });
+
+      assistant.log(`Updated payments-subscriptions/${resourceId}: uid=${uid}, eventType=${eventType}`);
+    } else {
+      assistant.log(`No resourceId in unified result, skipping payments-subscriptions write`);
     }
 
     // Mark webhook as completed
@@ -113,9 +115,9 @@ module.exports = async ({ Manager, assistant, change, context, libraries }) => {
       },
     }, { merge: true });
 
-    assistant.log(`Webhook ${eventId} processed successfully`);
+    assistant.log(`Webhook ${eventId} completed: wrote users/${uid}, payments-subscriptions/${resourceId || 'skipped'}, payments-webhooks/${eventId}=completed`);
   } catch (e) {
-    assistant.error(`Webhook ${eventId} processing failed:`, e);
+    assistant.error(`Webhook ${eventId} failed: ${e.message}`, e);
 
     // Mark as failed with error message
     await webhookRef.set({