backend-manager 5.0.107 → 5.0.109

package/CLAUDE.md

@@ -447,6 +447,8 @@ When `npx bm test` starts its own emulator, logs go to `emulator.log` (since it
 
 These files are overwritten on each run and are gitignored (`*.log`). Use them to search for errors, debug webhook pipelines, or review full function output after a test run.
 
+- **`logs.log`** — Cloud Function logs from `npx bm logs:read` or `npx bm logs:tail` (raw JSON for `read`, streaming text for `tail`)
+
 ### Filtering Tests
 ```bash
 npx bm test rules/             # Run rules tests (both BEM and project)
@@ -587,6 +589,29 @@ npx bm auth:delete <uid-or-email>                    # Delete user (prompts for
 npx bm auth:set-claims <uid-or-email> '<json>'       # Set custom claims
 ```
 
+### Logs Commands
+
+Fetch or stream Cloud Function logs from Google Cloud Logging. Requires `gcloud` CLI installed and authenticated. Auto-resolves the project ID from `service-account.json`, `.firebaserc`, or `GCLOUD_PROJECT`.
+
+```bash
+npx bm logs:read                                     # Read last 1h of logs (default: 50 entries)
+npx bm logs:read --fn bm_api                         # Filter by function name
+npx bm logs:read --fn bm_api --severity ERROR        # Filter by severity (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+npx bm logs:read --since 2d --limit 100              # Custom time range and limit
+npx bm logs:tail                                     # Stream live logs
+npx bm logs:tail --fn bm_paymentsWebhookOnWrite      # Stream filtered live logs
+```
+
+Both commands save output to `logs.log` in the project directory (overwritten on each run). `logs:read` saves raw JSON; `logs:tail` streams text.
+
+| Flag | Description | Default | Commands |
+|------|-------------|---------|----------|
+| `--fn <name>` | Filter by Cloud Function name | all | both |
+| `--severity <level>` | Minimum severity level | all | both |
+| `--since <duration>` | Time range (`30m`, `1h`, `2d`, `1w`) | `1h` | read only |
+| `--limit <n>` | Max entries | `50` | read only |
+| `--raw` | Output raw JSON | false | both |
+
 ### Shared Flags
 
 | Flag | Description |
@@ -985,6 +1010,7 @@ The `test` processor generates Stripe-shaped data and auto-fires webhooks to the
 | Firebase init helper (CLI) | `src/cli/commands/firebase-init.js` |
 | Firestore CLI commands | `src/cli/commands/firestore.js` |
 | Auth CLI commands | `src/cli/commands/auth.js` |
+| Logs CLI commands | `src/cli/commands/logs.js` |
 | Intent creation | `src/manager/routes/payments/intent/post.js` |
 | Webhook ingestion | `src/manager/routes/payments/webhook/post.js` |
 | Webhook processing (on-write) | `src/manager/events/firestore/payments-webhooks/on-write.js` |

package/README.md

@@ -749,9 +749,13 @@ npx backend-manager <command>
 | `bem auth:list` | List Auth users |
 | `bem auth:delete <uid-or-email>` | Delete an Auth user |
 | `bem auth:set-claims <uid-or-email> '<json>'` | Set custom claims on an Auth user |
+| `bem logs:read` | Fetch Cloud Function logs from Google Cloud Logging |
+| `bem logs:tail` | Stream live Cloud Function logs |
 
 All Firestore and Auth commands support `--emulator` to target the local emulator, `--force` to skip confirmation, and `--raw` for compact JSON output.
 
+Logs commands support `--fn <name>` (function name filter), `--severity <level>`, `--since <duration>` (read only), `--limit <n>` (read only), and `--raw`. Requires `gcloud` CLI installed and authenticated.
+
 ## Environment Variables
 
 Set these in your `functions/.env` file:
@@ -795,9 +799,10 @@ npx bm test user/ admin/       # Multiple paths
 
 ### Log Files
 
-Both `npx bm emulator` and `npx bm test` automatically save all output to log files in the project directory:
-- **`emulator.log`** — Full emulator + Cloud Functions output
-- **`test.log`** — Test runner output (when running against an existing emulator)
+BEM CLI commands automatically save output to log files in the project directory:
+- **`emulator.log`** — Full emulator + Cloud Functions output (`npx bm emulator`)
+- **`test.log`** — Test runner output (`npx bm test`, when running against an existing emulator)
+- **`logs.log`** — Cloud Function logs (`npx bm logs:read` or `npx bm logs:tail`)
 
 Logs are overwritten on each run. Use them to debug failing tests or review function output.
 

package/package.json

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

package/src/cli/commands/firebase-init.js

@@ -118,4 +118,4 @@ function resolveProjectId(projectDir, functionsDir) {
   return process.env.GCLOUD_PROJECT || 'demo-project';
 }
 
-module.exports = { initFirebase };
+module.exports = { initFirebase, resolveProjectId };

package/src/cli/commands/logs.js

@@ -0,0 +1,344 @@
+const BaseCommand = require('./base-command');
+const chalk = require('chalk');
+const fs = require('fs');
+const { execSync, spawn } = require('child_process');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const { resolveProjectId } = require('./firebase-init');
+
+const SEVERITY_COLORS = {
+  DEFAULT: 'gray',
+  DEBUG: 'gray',
+  INFO: 'cyan',
+  NOTICE: 'blue',
+  WARNING: 'yellow',
+  ERROR: 'red',
+  CRITICAL: 'redBright',
+  ALERT: 'redBright',
+  EMERGENCY: 'redBright',
+};
+
+class LogsCommand extends BaseCommand {
+  async execute() {
+    const argv = this.main.argv;
+    const args = argv._ || [];
+    const subcommand = args[0]; // e.g., 'logs:read'
+    const action = subcommand.split(':')[1];
+
+    // Check gcloud is installed
+    if (!this.isGcloudInstalled()) {
+      this.logError('gcloud CLI is not installed or not in PATH.');
+      this.log(chalk.gray('  Install it: https://cloud.google.com/sdk/docs/install'));
+      return;
+    }
+
+    // Resolve project ID
+    const projectId = this.resolveProject();
+    if (!projectId) {
+      this.logError('Could not resolve project ID.');
+      this.log(chalk.gray('  Ensure functions/service-account.json, .firebaserc, or GCLOUD_PROJECT exists.'));
+      return;
+    }
+
+    this.log(chalk.gray(`  Project: ${projectId}\n`));
+
+    switch (action) {
+      case 'read':
+        return await this.read(projectId, argv);
+      case 'tail':
+      case 'stream':
+        return await this.tail(projectId, argv);
+      default:
+        this.logError(`Unknown logs subcommand: ${action}`);
+        this.log(chalk.gray('  Available: logs:read, logs:tail, logs:stream'));
+    }
+  }
+
+  /**
+   * Fetch historical logs.
+   * Usage: npx bm logs:read [--fn bm_api] [--severity ERROR] [--since 1h] [--limit 50]
+   */
+  async read(projectId, argv) {
+    const filter = this.buildFilter(argv);
+    const limit = parseInt(argv.limit, 10) || 50;
+
+    const cmd = [
+      'gcloud', 'logging', 'read',
+      filter ? `'${filter}'` : '',
+      `--project=${projectId}`,
+      `--limit=${limit}`,
+      '--format=json',
+      '--order=asc',
+    ].filter(Boolean).join(' ');
+
+    // Set up log file in the project directory
+    const projectDir = this.main.firebaseProjectPath;
+    const logPath = path.join(projectDir, 'logs.log');
+
+    this.log(chalk.gray(`  Filter: ${filter || '(none)'}`));
+    this.log(chalk.gray(`  Limit: ${limit}`));
+    this.log(chalk.gray(`  Logs saving to: ${logPath}\n`));
+
+    try {
+      const output = execSync(cmd, {
+        encoding: 'utf8',
+        maxBuffer: 10 * 1024 * 1024, // 10MB
+        timeout: 30000,
+      });
+
+      const entries = JSON.parse(output || '[]');
+
+      // Save raw JSON to log file for Claude/tooling to read
+      jetpack.write(logPath, JSON.stringify(entries, null, 2));
+
+      if (entries.length === 0) {
+        this.logWarning('No log entries found.');
+        return;
+      }
+
+      if (argv.raw) {
+        this.log(JSON.stringify(entries, null, 2));
+        return;
+      }
+
+      this.log(chalk.gray(`  Found ${entries.length} entries\n`));
+      for (const entry of entries) {
+        this.formatEntry(entry);
+      }
+    } catch (error) {
+      if (error.status) {
+        this.logError(`gcloud command failed (exit code ${error.status}):`);
+        this.log(chalk.gray(error.stderr || error.message));
+      } else {
+        this.logError(`Failed to read logs: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Poll for live logs by repeatedly running gcloud logging read.
+   * Usage: npx bm logs:tail [--fn bm_api] [--severity ERROR] [--interval 5]
+   */
+  async tail(projectId, argv) {
+    const interval = (parseInt(argv.interval, 10) || 5) * 1000;
+    let lastTimestamp = new Date(Date.now() - 60000).toISOString(); // Start 1 min ago
+    const seenIds = new Set();
+    let stopped = false;
+
+    // Set up log file in the project directory
+    const projectDir = this.main.firebaseProjectPath;
+    const logPath = path.join(projectDir, 'logs.log');
+    const logStream = fs.createWriteStream(logPath, { flags: 'w' });
+
+    const filter = this.buildFilter(argv, { excludeTimestamp: true });
+    this.log(chalk.gray(`  Filter: ${filter || '(none)'}`));
+    this.log(chalk.gray(`  Polling every ${interval / 1000}s`));
+    this.log(chalk.gray(`  Logs saving to: ${logPath}`));
+    this.log(chalk.gray('  Tailing logs (Ctrl+C to stop)...\n'));
+
+    // Handle Ctrl+C gracefully
+    process.on('SIGINT', () => {
+      stopped = true;
+    });
+
+    while (!stopped) {
+      try {
+        const timestampFilter = `timestamp>="${lastTimestamp}"`;
+        const fullFilter = filter
+          ? `${filter} AND ${timestampFilter}`
+          : `${timestampFilter}`;
+
+        const cmd = [
+          'gcloud', 'logging', 'read',
+          `'${fullFilter}'`,
+          `--project=${projectId}`,
+          '--limit=100',
+          '--format=json',
+          '--order=asc',
+        ].join(' ');
+
+        const output = execSync(cmd, {
+          encoding: 'utf8',
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: 15000,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+
+        const entries = JSON.parse(output || '[]');
+
+        for (const entry of entries) {
+          // Deduplicate using insertId
+          const entryId = entry.insertId || `${entry.timestamp}-${entry.textPayload || ''}`;
+          if (seenIds.has(entryId)) {
+            continue;
+          }
+          seenIds.add(entryId);
+
+          // Write to log file
+          logStream.write(JSON.stringify(entry) + '\n');
+
+          // Display
+          if (argv.raw) {
+            this.log(JSON.stringify(entry));
+          } else {
+            this.formatEntry(entry);
+          }
+
+          // Advance timestamp watermark
+          if (entry.timestamp && entry.timestamp > lastTimestamp) {
+            lastTimestamp = entry.timestamp;
+          }
+        }
+
+        // Cap seenIds to prevent memory leak
+        if (seenIds.size > 5000) {
+          const arr = [...seenIds];
+          arr.splice(0, arr.length - 2500);
+          seenIds.clear();
+          arr.forEach(id => seenIds.add(id));
+        }
+      } catch (error) {
+        // Silently skip transient errors during polling
+        if (error.status) {
+          this.log(chalk.gray(`  (poll error: ${(error.stderr || error.message).trim().split('\n')[0]})`));
+        }
+      }
+
+      // Wait before next poll
+      if (!stopped) {
+        await new Promise(resolve => setTimeout(resolve, interval));
+      }
+    }
+
+    logStream.end();
+    this.log(chalk.gray('\n  Tail stopped.'));
+  }
+
+  /**
+   * Build a gcloud logging filter string from CLI flags.
+   */
+  buildFilter(argv, options = {}) {
+    const parts = [];
+
+    // Always scope to Cloud Functions
+    parts.push('resource.type="cloud_function"');
+
+    // Function name filter
+    if (argv.fn) {
+      parts.push(`resource.labels.function_name="${argv.fn}"`);
+    }
+
+    // Severity filter
+    if (argv.severity) {
+      parts.push(`severity>=${argv.severity.toUpperCase()}`);
+    }
+
+    // Timestamp filter (read only, not tail)
+    if (!options.excludeTimestamp) {
+      const since = argv.since || '1h';
+      const timestamp = this.parseSince(since);
+      if (timestamp) {
+        parts.push(`timestamp>="${timestamp}"`);
+      }
+    }
+
+    return parts.join(' AND ');
+  }
+
+  /**
+   * Parse a human-friendly duration (e.g., '1h', '2d', '30m') into an ISO timestamp.
+   */
+  parseSince(since) {
+    const match = since.match(/^(\d+)([mhdw])$/);
+    if (!match) {
+      this.logWarning(`Invalid --since format: "${since}". Use e.g., 30m, 1h, 2d, 1w`);
+      return null;
+    }
+
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    const now = new Date();
+
+    switch (unit) {
+      case 'm': now.setMinutes(now.getMinutes() - value); break;
+      case 'h': now.setHours(now.getHours() - value); break;
+      case 'd': now.setDate(now.getDate() - value); break;
+      case 'w': now.setDate(now.getDate() - (value * 7)); break;
+    }
+
+    return now.toISOString();
+  }
+
+  /**
+   * Pretty-print a single log entry.
+   */
+  formatEntry(entry) {
+    const severity = entry.severity || 'DEFAULT';
+    const colorFn = chalk[SEVERITY_COLORS[severity] || 'white'];
+    const timestamp = entry.timestamp || entry.receiveTimestamp || '';
+    const fnName = entry.resource?.labels?.function_name || '';
+
+    // Extract the actual message
+    let message = '';
+    if (entry.textPayload) {
+      message = entry.textPayload;
+    } else if (entry.jsonPayload) {
+      message = typeof entry.jsonPayload.message === 'string'
+        ? entry.jsonPayload.message
+        : JSON.stringify(entry.jsonPayload, null, 2);
+    } else if (entry.protoPayload) {
+      message = JSON.stringify(entry.protoPayload, null, 2);
+    }
+
+    // Format timestamp to local time
+    let timeStr = '';
+    if (timestamp) {
+      const date = new Date(timestamp);
+      timeStr = date.toLocaleTimeString();
+    }
+
+    const severityTag = colorFn(`[${severity.padEnd(8)}]`);
+    const fnTag = fnName ? chalk.blue(`[${fnName}]`) : '';
+    const timeTag = chalk.gray(timeStr);
+
+    this.log(`${timeTag} ${severityTag} ${fnTag} ${message}`);
+  }
+
+  /**
+   * Resolve the project ID without initializing firebase-admin.
+   */
+  resolveProject() {
+    const projectDir = this.firebaseProjectPath;
+    const functionsDir = path.join(projectDir, 'functions');
+
+    // Try service-account.json first (most reliable for production)
+    const serviceAccountPath = path.join(functionsDir, 'service-account.json');
+    if (jetpack.exists(serviceAccountPath)) {
+      try {
+        const sa = JSON.parse(jetpack.read(serviceAccountPath));
+        if (sa.project_id) {
+          return sa.project_id;
+        }
+      } catch (e) {
+        // Fall through
+      }
+    }
+
+    // Fall back to shared resolver
+    return resolveProjectId(projectDir, functionsDir);
+  }
+
+  /**
+   * Check if gcloud CLI is available.
+   */
+  isGcloudInstalled() {
+    try {
+      execSync('gcloud --version', { encoding: 'utf8', stdio: 'pipe' });
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+}
+
+module.exports = LogsCommand;

package/src/cli/index.js

@@ -28,6 +28,7 @@ const WatchCommand = require('./commands/watch');
 const StripeCommand = require('./commands/stripe');
 const FirestoreCommand = require('./commands/firestore');
 const AuthCommand = require('./commands/auth');
+const LogsCommand = require('./commands/logs');
 
 function Main() {}
 
@@ -145,6 +146,12 @@ Main.prototype.process = async function (args) {
     const cmd = new AuthCommand(self);
     return await cmd.execute();
   }
+
+  // Logs utility commands
+  if (self.options['logs:read'] || self.options['logs:tail'] || self.options['logs:stream']) {
+    const cmd = new LogsCommand(self);
+    return await cmd.execute();
+  }
 };
 
 // Test method for setup command

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

@@ -31,6 +31,9 @@ module.exports = async ({ assistant, change, context }) => {
   // Set status to processing
   await webhookRef.set({ status: 'processing' }, { merge: true });
 
+  // Hoisted so orderId is available in catch block for audit trail
+  let orderId = null;
+
   try {
     const processor = dataAfter.processor;
     const uid = dataAfter.owner;
@@ -73,7 +76,7 @@ module.exports = async ({ assistant, change, context }) => {
     const webhookReceivedUNIX = dataAfter.metadata?.received?.timestampUNIX || nowUNIX;
 
     // Extract orderId from resource (processor-agnostic)
-    const orderId = library.getOrderId(resource);
+    orderId = library.getOrderId(resource);
 
     // Process the payment event (subscription or one-time)
     if (category !== 'subscription' && category !== 'one-time') {
@@ -100,11 +103,28 @@ module.exports = async ({ assistant, change, context }) => {
   } catch (e) {
     assistant.error(`Webhook ${eventId} failed: ${e.message}`, e);
 
+    const now = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(now, { output: 'unix' });
+
     // Mark as failed with error message
     await webhookRef.set({
       status: 'failed',
       error: e.message || String(e),
     }, { merge: true });
+
+    // Mark intent as failed if we resolved the orderId before the error
+    if (orderId) {
+      await admin.firestore().doc(`payments-intents/${orderId}`).set({
+        status: 'failed',
+        error: e.message || String(e),
+        metadata: {
+          completed: {
+            timestamp: now,
+            timestampUNIX: nowUNIX,
+          },
+        },
+      }, { merge: true });
+    }
   }
 };
 
@@ -220,6 +240,20 @@ async function processPaymentEvent({ category, library, resource, resourceType,
     assistant.log(`Updated payments-orders/${orderId}: type=${category}, uid=${uid}, eventType=${eventType}`);
   }
 
+  // Update payments-intents/{orderId} status to match webhook outcome
+  if (orderId) {
+    await admin.firestore().doc(`payments-intents/${orderId}`).set({
+      status: 'completed',
+      metadata: {
+        completed: {
+          timestamp: now,
+          timestampUNIX: nowUNIX,
+        },
+      },
+    }, { merge: true });
+    assistant.log(`Updated payments-intents/${orderId}: status=completed`);
+  }
+
   return transitionName;
 }
 

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

@@ -1,22 +1,35 @@
 /**
  * Stripe cancel processor
- * Sets a subscription to cancel at the end of the current billing period
+ * Cancels a subscription — immediately if trialing, at period end otherwise.
  */
 module.exports = {
   /**
-   * Cancel a Stripe subscription at period end
+   * Cancel a Stripe subscription
+   *
+   * If the subscription is currently trialing, cancel immediately to avoid
+   * giving free premium access for the remainder of the trial.
+   * Otherwise, cancel at the end of the current billing period.
    *
    * @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 current subscription object
    * @param {object} options.assistant - Assistant instance for logging
    */
-  async cancelAtPeriodEnd({ resourceId, uid, assistant }) {
+  async cancelAtPeriodEnd({ resourceId, uid, subscription, assistant }) {
     const StripeLib = require('../../../../libraries/payment/processors/stripe.js');
     const stripe = StripeLib.init();
 
-    await stripe.subscriptions.update(resourceId, { cancel_at_period_end: true });
+    const isTrialing = subscription?.trial?.claimed
+      && subscription?.status === 'active'
+      && subscription?.trial?.expires?.timestampUNIX === subscription?.expires?.timestampUNIX;
 
-    assistant.log(`Stripe cancel at period end: sub=${resourceId}, uid=${uid}`);
+    if (isTrialing) {
+      await stripe.subscriptions.cancel(resourceId);
+      assistant.log(`Stripe cancel immediate (trialing): sub=${resourceId}, uid=${uid}`);
+    } else {
+      await stripe.subscriptions.update(resourceId, { cancel_at_period_end: true });
+      assistant.log(`Stripe cancel at period end: sub=${resourceId}, uid=${uid}`);
+    }
   },
 };

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

@@ -2,9 +2,13 @@ const powertools = require('node-powertools');
 
 /**
  * Test cancel processor
- * Simulates the Stripe webhook that results from cancel_at_period_end=true
+ * Simulates the Stripe webhook that results from cancellation
  * by writing directly to payments-webhooks/{eventId} with status=pending.
  * The on-write trigger picks it up and runs the full pipeline.
+ *
+ * If the user is trialing, simulates immediate cancellation (customer.subscription.deleted).
+ * Otherwise, simulates cancel at period end (customer.subscription.updated with cancel_at_period_end=true).
+ *
  * Only available in non-production environments.
  */
 module.exports = {
@@ -16,7 +20,6 @@ module.exports = {
     const admin = assistant.Manager.libraries.admin;
 
     const timestamp = Date.now();
-    const eventId = `_test-evt-cancel-${timestamp}`;
     const now = Math.floor(timestamp / 1000);
     const periodEnd = now + (30 * 86400);
 
@@ -35,21 +38,31 @@ module.exports = {
       }
     }
 
-    // Build a Stripe-shaped customer.subscription.updated payload
-    // with cancel_at_period_end=true — mirrors what Stripe sends after cancellation
+    // Detect if user is on a trial
+    const isTrialing = subscription?.trial?.claimed
+      && subscription?.status === 'active'
+      && subscription?.trial?.expires?.timestampUNIX === subscription?.expires?.timestampUNIX;
+
+    // Trialing: immediate cancel (customer.subscription.deleted)
+    // Non-trialing: cancel at period end (customer.subscription.updated)
+    const eventType = isTrialing
+      ? 'customer.subscription.deleted'
+      : 'customer.subscription.updated';
+    const eventId = `_test-evt-cancel-${timestamp}`;
+
     const subscriptionObj = {
       id: resourceId,
       object: 'subscription',
-      status: 'active',
+      status: isTrialing ? 'canceled' : 'active',
       metadata: { uid, orderId },
-      cancel_at_period_end: true,
-      cancel_at: periodEnd,
-      canceled_at: null,
-      current_period_end: periodEnd,
+      cancel_at_period_end: !isTrialing,
+      cancel_at: isTrialing ? now : periodEnd,
+      canceled_at: isTrialing ? now : null,
+      current_period_end: isTrialing ? now : periodEnd,
       current_period_start: now - (30 * 86400),
       start_date: now - (30 * 86400),
-      trial_start: null,
-      trial_end: null,
+      trial_start: isTrialing ? (now - 86400) : null,
+      trial_end: isTrialing ? now : null,
       plan: { product: stripeProductId, interval: 'month' },
     };
 
@@ -64,11 +77,11 @@ module.exports = {
       owner: uid,
       raw: {
         id: eventId,
-        type: 'customer.subscription.updated',
+        type: eventType,
         data: { object: subscriptionObj },
       },
       event: {
-        type: 'customer.subscription.updated',
+        type: eventType,
         category: 'subscription',
         resourceType: 'subscription',
         resourceId: resourceId,
@@ -86,6 +99,6 @@ module.exports = {
       },
     });
 
-    assistant.log(`Test cancel processor: wrote payments-webhooks/${eventId} for sub=${resourceId}, uid=${uid}`);
+    assistant.log(`Test cancel processor: wrote payments-webhooks/${eventId} (${eventType}) for sub=${resourceId}, uid=${uid}, trialing=${isTrialing}`);
   },
 };

package/src/test/test-accounts.js

@@ -166,6 +166,15 @@ const JOURNEY_ACCOUNTS = {
       subscription: { product: { id: 'basic' }, status: 'active' }, // Starts as basic, upgraded via trial webhook
     },
   },
+  'journey-payments-trial-cancel': {
+    id: 'journey-payments-trial-cancel',
+    uid: '_test-journey-payments-trial-cancel',
+    email: '_test.journey-payments-trial-cancel@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' }, // Starts as basic, trial then immediate cancel
+    },
+  },
   'journey-payments-failure': {
     id: 'journey-payments-failure',
     uid: '_test-journey-payments-failure',

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

@@ -112,7 +112,7 @@ module.exports = {
     },
 
     {
-      name: 'intent-doc-created',
+      name: 'intent-doc-completed',
       async run({ firestore, assert, state }) {
         const intentDoc = await firestore.get(`payments-intents/${state.orderId}`);
 
@@ -121,7 +121,9 @@ module.exports = {
         assert.equal(intentDoc.intentId, state.intentId, 'Intent ID should match processor session ID');
         assert.equal(intentDoc.owner, state.uid, 'Owner should match');
         assert.equal(intentDoc.processor, 'test', 'Processor should be test');
+        assert.equal(intentDoc.status, 'completed', 'Intent status should be completed after webhook processing');
         assert.equal(intentDoc.productId, state.productId, `Product should be ${state.productId}`);
+        assert.ok(intentDoc.metadata?.completed?.timestampUNIX > 0, 'Completed timestamp should be set');
       },
     },
   ],

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

@@ -0,0 +1,109 @@
+/**
+ * Test: Payment Journey - Trial Cancel
+ * Simulates: basic user → trial activation → cancel during trial → immediate cancellation
+ *
+ * When a user cancels during a free trial, the subscription should be cancelled immediately
+ * (not scheduled for period end) to avoid giving free premium access for the remainder of the trial.
+ *
+ * Uses the test processor for initial trial, then cancel endpoint for cancellation.
+ * Product-agnostic: resolves the first paid product from config.payment.products
+ */
+module.exports = {
+  description: 'Payment journey: trial → cancel during trial → immediate cancellation',
+  type: 'suite',
+  timeout: 30000,
+
+  tests: [
+    {
+      name: 'verify-starts-as-basic',
+      async run({ accounts, firestore, assert, state, config }) {
+        const uid = accounts['journey-payments-trial-cancel'].uid;
+        const userDoc = await firestore.get(`users/${uid}`);
+
+        assert.ok(userDoc, 'User doc should exist');
+        assert.equal(userDoc.subscription?.product?.id, 'basic', 'Should start as basic');
+        assert.equal(userDoc.subscription?.trial?.claimed, false, 'Trial should not be claimed');
+
+        // Resolve first paid product with trial from config
+        const trialProduct = config.payment.products.find(p => p.id !== 'basic' && p.prices && p.trial?.days);
+        assert.ok(trialProduct, 'Config should have at least one paid product with trial');
+
+        state.uid = uid;
+        state.paidProductId = trialProduct.id;
+        state.paidProductName = trialProduct.name;
+      },
+    },
+
+    {
+      name: 'create-trial-intent',
+      async run({ http, assert, state }) {
+        const response = await http.as('journey-payments-trial-cancel').post('payments/intent', {
+          processor: 'test',
+          productId: state.paidProductId,
+          frequency: 'monthly',
+          trial: true,
+        });
+
+        assert.isSuccess(response, 'Intent should succeed');
+        assert.ok(response.data.id, 'Should return intent ID');
+        assert.ok(response.data.orderId, 'Should return orderId');
+
+        state.intentId = response.data.id;
+        state.orderId = response.data.orderId;
+        state.eventId = response.data.id.replace('_test-cs-', '_test-evt-');
+      },
+    },
+
+    {
+      name: 'trial-activated',
+      async run({ firestore, assert, state, waitFor }) {
+        await waitFor(async () => {
+          const userDoc = await firestore.get(`users/${state.uid}`);
+          return userDoc?.subscription?.trial?.claimed === true;
+        }, 15000, 500);
+
+        const userDoc = await firestore.get(`users/${state.uid}`);
+
+        assert.equal(userDoc.subscription.product.id, state.paidProductId, `Product should be ${state.paidProductId}`);
+        assert.equal(userDoc.subscription.status, 'active', 'Status should be active');
+        assert.equal(userDoc.subscription.trial.claimed, true, 'Trial should be claimed');
+        assert.equal(userDoc.subscription.trial.expires.timestampUNIX, userDoc.subscription.expires.timestampUNIX, 'Trial expires should match subscription expires (still in trial period)');
+
+        state.subscriptionId = userDoc.subscription.payment.resourceId;
+      },
+    },
+
+    {
+      name: 'cancel-during-trial',
+      async run({ http, assert }) {
+        // Cancel via endpoint — test processor should detect trial and simulate immediate cancel
+        const response = await http.as('journey-payments-trial-cancel').post('payments/cancel', {
+          confirmed: true,
+          reason: 'Changed my mind during trial',
+          feedback: 'Testing trial cancellation',
+        });
+
+        assert.isSuccess(response, 'Cancel endpoint should succeed');
+        assert.equal(response.data.success, true, 'Should return { success: true }');
+      },
+    },
+
+    {
+      name: 'verify-immediate-cancellation',
+      async run({ firestore, assert, state, waitFor }) {
+        // Poll until subscription is cancelled (NOT just pending)
+        await waitFor(async () => {
+          const userDoc = await firestore.get(`users/${state.uid}`);
+          return userDoc?.subscription?.status === 'cancelled';
+        }, 15000, 500);
+
+        const userDoc = await firestore.get(`users/${state.uid}`);
+
+        // During trial cancel: subscription should be immediately cancelled, not pending
+        assert.equal(userDoc.subscription.status, 'cancelled', 'Status should be cancelled (not active with pending)');
+        assert.equal(userDoc.subscription.cancellation.pending, false, 'Should NOT be pending — should be fully cancelled');
+        assert.equal(userDoc.subscription.product.id, state.paidProductId, `Product should still be ${state.paidProductId}`);
+      },
+    },
+  ],
+};

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

@@ -79,6 +79,18 @@ module.exports = {
       },
     },
 
+    {
+      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');
+      },
+    },
+
     {
       name: 'send-trial-to-active-webhook',
       async run({ http, assert, state, config }) {

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

@@ -109,7 +109,7 @@ module.exports = {
     },
 
     {
-      name: 'intent-doc-created',
+      name: 'intent-doc-completed',
       async run({ firestore, assert, state }) {
         const intentDoc = await firestore.get(`payments-intents/${state.orderId}`);
 
@@ -118,8 +118,9 @@ module.exports = {
         assert.equal(intentDoc.intentId, state.intentId, 'Intent ID should match processor session ID');
         assert.equal(intentDoc.owner, state.uid, 'Owner should match');
         assert.equal(intentDoc.processor, 'test', 'Processor should be test');
-        assert.equal(intentDoc.status, 'pending', 'Intent status should be pending');
+        assert.equal(intentDoc.status, 'completed', 'Intent status should be completed after webhook processing');
         assert.equal(intentDoc.productId, state.paidProductId, `Product should be ${state.paidProductId}`);
+        assert.ok(intentDoc.metadata?.completed?.timestampUNIX > 0, 'Completed timestamp should be set');
       },
     },
   ],