backend-manager 5.0.102 → 5.0.104

package/src/cli/commands/firestore.js

@@ -0,0 +1,261 @@
+const BaseCommand = require('./base-command');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const { initFirebase } = require('./firebase-init');
+
+class FirestoreCommand extends BaseCommand {
+  async execute() {
+    const argv = this.main.argv;
+    const args = argv._ || [];
+    const subcommand = args[0]; // e.g., 'firestore:get'
+    const action = subcommand.split(':')[1];
+
+    // Initialize Firebase
+    const isEmulator = argv.emulator || false;
+    let firebase;
+
+    try {
+      firebase = initFirebase({
+        firebaseProjectPath: this.firebaseProjectPath,
+        emulator: isEmulator,
+      });
+    } catch (error) {
+      this.logError(`Firebase init failed: ${error.message}`);
+      return;
+    }
+
+    const { admin, projectId } = firebase;
+    const target = isEmulator ? 'emulator' : 'production';
+    this.log(chalk.gray(`  Target: ${projectId} (${target})\n`));
+
+    // Dispatch to subcommand handler
+    switch (action) {
+      case 'get':
+        return await this.get(admin, args, argv);
+      case 'set':
+        return await this.set(admin, args, argv);
+      case 'query':
+        return await this.query(admin, args, argv);
+      case 'delete':
+        return await this.del(admin, args, argv, isEmulator);
+      default:
+        this.logError(`Unknown firestore subcommand: ${action}`);
+        this.log(chalk.gray('  Available: firestore:get, firestore:set, firestore:query, firestore:delete'));
+    }
+  }
+
+  /**
+   * Read a document by path.
+   * Usage: npx bm firestore:get users/abc123
+   */
+  async get(admin, args, argv) {
+    const docPath = args[1];
+
+    if (!docPath) {
+      this.logError('Missing document path. Usage: npx bm firestore:get <path>');
+      return;
+    }
+
+    // Validate path is a document (even number of segments), not a collection
+    const segments = docPath.split('/').filter(Boolean);
+    if (segments.length % 2 !== 0) {
+      this.logError(`Path "${docPath}" points to a collection, not a document.`);
+      this.log(chalk.gray('  Use firestore:query to list collection documents.'));
+      return;
+    }
+
+    try {
+      const doc = await admin.firestore().doc(docPath).get();
+
+      if (!doc.exists) {
+        this.logWarning(`Document does not exist: ${docPath}`);
+        return;
+      }
+
+      this.output({ id: doc.id, path: doc.ref.path, data: doc.data() }, argv);
+    } catch (error) {
+      this.logError(`Failed to read document: ${error.message}`);
+    }
+  }
+
+  /**
+   * Write/merge to a document.
+   * Usage: npx bm firestore:set users/abc123 '{"field": "value"}'
+   */
+  async set(admin, args, argv) {
+    const docPath = args[1];
+    const jsonString = args[2];
+
+    if (!docPath || !jsonString) {
+      this.logError('Usage: npx bm firestore:set <path> \'<json>\'');
+      return;
+    }
+
+    let data;
+    try {
+      data = JSON.parse(jsonString);
+    } catch (error) {
+      this.logError(`Invalid JSON: ${error.message}`);
+      return;
+    }
+
+    const merge = argv.merge !== false; // merge by default, --no-merge to overwrite
+
+    try {
+      await admin.firestore().doc(docPath).set(data, { merge });
+      this.logSuccess(`Document written: ${docPath} (merge: ${merge})`);
+      this.output(data, argv);
+    } catch (error) {
+      this.logError(`Failed to write document: ${error.message}`);
+    }
+  }
+
+  /**
+   * Query a collection.
+   * Usage: npx bm firestore:query users --where "plan==premium" --limit 10
+   */
+  async query(admin, args, argv) {
+    const collectionPath = args[1];
+
+    if (!collectionPath) {
+      this.logError('Usage: npx bm firestore:query <collection> [--where "field==value"] [--limit N]');
+      return;
+    }
+
+    try {
+      let query = admin.firestore().collection(collectionPath);
+
+      // Parse --where clauses (can be repeated for AND)
+      const whereClauses = this.parseWhereClauses(argv);
+      for (const { field, operator, value } of whereClauses) {
+        query = query.where(field, operator, value);
+      }
+
+      // Parse --orderBy
+      if (argv.orderBy) {
+        const [field, direction] = argv.orderBy.split(':');
+        query = query.orderBy(field, direction || 'asc');
+      }
+
+      // Parse --limit (default 25)
+      const limit = parseInt(argv.limit, 10) || 25;
+      query = query.limit(limit);
+
+      const snapshot = await query.get();
+
+      if (snapshot.empty) {
+        this.logWarning('No documents found.');
+        return;
+      }
+
+      const results = snapshot.docs.map(doc => ({
+        id: doc.id,
+        path: doc.ref.path,
+        data: doc.data(),
+      }));
+
+      this.log(chalk.gray(`  Found ${results.length} document(s)\n`));
+      this.output(results, argv);
+    } catch (error) {
+      this.logError(`Query failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Delete a document.
+   * Usage: npx bm firestore:delete users/abc123 [--force]
+   */
+  async del(admin, args, argv, isEmulator) {
+    const docPath = args[1];
+
+    if (!docPath) {
+      this.logError('Usage: npx bm firestore:delete <path> [--force]');
+      return;
+    }
+
+    // Require confirmation for production (skip for emulator or --force)
+    if (!isEmulator && !argv.force) {
+      const { confirmed } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'confirmed',
+        message: `Delete document "${docPath}" from PRODUCTION?`,
+        default: false,
+      }]);
+
+      if (!confirmed) {
+        this.log(chalk.gray('  Aborted.'));
+        return;
+      }
+    }
+
+    try {
+      await admin.firestore().doc(docPath).delete();
+      this.logSuccess(`Document deleted: ${docPath}`);
+    } catch (error) {
+      this.logError(`Failed to delete document: ${error.message}`);
+    }
+  }
+
+  /**
+   * Parse --where flag(s) into Firestore query clauses.
+   * Supports: "field==value", "field>value", "field>=value", etc.
+   * Multiple --where flags create AND conditions.
+   */
+  parseWhereClauses(argv) {
+    if (!argv.where) {
+      return [];
+    }
+
+    // yargs: single --where gives string, multiple gives array
+    const rawClauses = Array.isArray(argv.where) ? argv.where : [argv.where];
+    const operators = ['>=', '<=', '!=', '==', '>', '<'];
+
+    return rawClauses.map(clause => {
+      for (const op of operators) {
+        const idx = clause.indexOf(op);
+
+        if (idx === -1) {
+          continue;
+        }
+
+        const field = clause.substring(0, idx).trim();
+        const rawValue = clause.substring(idx + op.length).trim();
+
+        return { field, operator: op, value: this.coerceValue(rawValue) };
+      }
+
+      throw new Error(`Cannot parse --where clause: "${clause}". Use format: "field==value"`);
+    });
+  }
+
+  /**
+   * Coerce a string value to the appropriate JS type.
+   */
+  coerceValue(raw) {
+    if (raw === 'true') return true;
+    if (raw === 'false') return false;
+    if (raw === 'null') return null;
+    if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+
+    // Strip surrounding quotes if present
+    if ((raw.startsWith('"') && raw.endsWith('"'))
+      || (raw.startsWith("'") && raw.endsWith("'"))) {
+      return raw.slice(1, -1);
+    }
+
+    return raw;
+  }
+
+  /**
+   * Output data as JSON.
+   */
+  output(data, argv) {
+    if (argv.raw) {
+      this.log(JSON.stringify(data));
+    } else {
+      this.log(JSON.stringify(data, null, 2));
+    }
+  }
+}
+
+module.exports = FirestoreCommand;

package/src/cli/commands/index.js

@@ -12,4 +12,6 @@ module.exports = {
   CleanCommand: require('./clean'),
   IndexesCommand: require('./indexes'),
   WatchCommand: require('./watch'),
+  FirestoreCommand: require('./firestore'),
+  AuthCommand: require('./auth'),
 };

package/src/cli/index.js

@@ -26,6 +26,8 @@ const CleanCommand = require('./commands/clean');
 const IndexesCommand = require('./commands/indexes');
 const WatchCommand = require('./commands/watch');
 const StripeCommand = require('./commands/stripe');
+const FirestoreCommand = require('./commands/firestore');
+const AuthCommand = require('./commands/auth');
 
 function Main() {}
 
@@ -129,6 +131,20 @@ Main.prototype.process = async function (args) {
     const cmd = new StripeCommand(self);
     return await cmd.execute();
   }
+
+  // Firestore utility commands
+  if (self.options['firestore:get'] || self.options['firestore:set']
+    || self.options['firestore:query'] || self.options['firestore:delete']) {
+    const cmd = new FirestoreCommand(self);
+    return await cmd.execute();
+  }
+
+  // Auth utility commands
+  if (self.options['auth:get'] || self.options['auth:list']
+    || self.options['auth:delete'] || self.options['auth:set-claims']) {
+    const cmd = new AuthCommand(self);
+    return await cmd.execute();
+  }
 };
 
 // Test method for setup command

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

@@ -141,6 +141,43 @@ const Stripe = {
     };
   },
 
+  /**
+   * Find an existing Stripe customer by uid metadata, or create one
+   *
+   * @param {string} uid - User's UID
+   * @param {string|null} email - User's email (used when creating a new customer)
+   * @param {object} assistant - Assistant instance for logging
+   * @returns {object} Stripe customer object
+   */
+  async resolveCustomer(uid, email, assistant) {
+    const stripe = this.init();
+
+    // Search for existing customer with this uid
+    const search = await stripe.customers.search({
+      query: `metadata['uid']:'${uid}'`,
+      limit: 1,
+    });
+
+    if (search.data.length > 0) {
+      const existing = search.data[0];
+      assistant.log(`Found existing Stripe customer: ${existing.id}`);
+      return existing;
+    }
+
+    // Create new customer
+    const params = {
+      metadata: { uid },
+    };
+
+    if (email) {
+      params.email = email;
+    }
+
+    const customer = await stripe.customers.create(params);
+    assistant.log(`Created new Stripe customer: ${customer.id}`);
+    return customer;
+  },
+
   /**
    * Transform a raw Stripe one-time payment resource into a unified shape
    * Mirrors subscription structure: { product, status, payment: { ... } }

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

@@ -0,0 +1,66 @@
+const path = require('path');
+
+/**
+ * POST /payments/cancel
+ * Cancels the authenticated user's subscription at the end of the current billing period.
+ * 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.
+ * Requires authentication.
+ */
+module.exports = async ({ assistant, user, settings }) => {
+  // Require authentication
+  if (!user.authenticated) {
+    return assistant.respond('Authentication required', { code: 401 });
+  }
+
+  const uid = user.auth.uid;
+  const confirmed = settings.confirmed;
+
+  // Require explicit confirmation
+  if (!confirmed) {
+    return assistant.respond('Cancellation must be confirmed', { code: 400 });
+  }
+
+  const subscription = user.subscription;
+
+  // Require an active, paid subscription
+  if (!subscription || subscription.status !== 'active' || subscription.product?.id === 'basic') {
+    assistant.log(`Cancel rejected: uid=${uid}, status=${subscription?.status}, product=${subscription?.product?.id}`);
+    return assistant.respond('No active paid subscription found', { code: 400 });
+  }
+
+  // Guard: already pending cancellation
+  if (subscription.cancellation?.pending === true) {
+    assistant.log(`Cancel rejected: uid=${uid}, cancellation already pending`);
+    return assistant.respond('Subscription is already pending cancellation', { code: 400 });
+  }
+
+  const processor = subscription.payment?.processor;
+  const resourceId = subscription.payment?.resourceId;
+
+  if (!processor || !resourceId) {
+    assistant.log(`Cancel rejected: uid=${uid}, missing processor=${processor} or resourceId=${resourceId}`);
+    return assistant.respond('Subscription payment details not found', { code: 400 });
+  }
+
+  // Load the processor module
+  let processorModule;
+  try {
+    processorModule = require(path.resolve(__dirname, `processors/${processor}.js`));
+  } catch (e) {
+    return assistant.respond(`Unknown processor: ${processor}`, { code: 400 });
+  }
+
+  // Cancel at period end via the processor
+  try {
+    await processorModule.cancelAtPeriodEnd({ resourceId, uid, subscription, assistant });
+  } catch (e) {
+    assistant.log(`Failed to cancel subscription via ${processor}: ${e.message}`);
+    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}`);
+
+  return assistant.respond({ success: true });
+};

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

@@ -0,0 +1,22 @@
+/**
+ * Stripe cancel processor
+ * Sets a subscription to cancel at the end of the current billing period
+ */
+module.exports = {
+  /**
+   * Cancel a Stripe subscription at period end
+   *
+   * @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.assistant - Assistant instance for logging
+   */
+  async cancelAtPeriodEnd({ resourceId, uid, assistant }) {
+    const StripeLib = require('../../../../libraries/payment-processors/stripe.js');
+    const stripe = StripeLib.init();
+
+    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

@@ -0,0 +1,93 @@
+const powertools = require('node-powertools');
+
+/**
+ * Test cancel processor
+ * Simulates the Stripe webhook that results from cancel_at_period_end=true
+ * by writing directly to payments-webhooks/{eventId} with status=pending.
+ * The on-write trigger picks it up and runs the full pipeline.
+ * Only available in non-production environments.
+ */
+module.exports = {
+  async cancelAtPeriodEnd({ resourceId, uid, subscription, assistant }) {
+    if (assistant.isProduction()) {
+      throw new Error('Test processor is not available in production');
+    }
+
+    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);
+
+    // Look up the price ID from the existing order so toUnifiedSubscription can resolve the product
+    const orderId = subscription?.payment?.orderId;
+    let priceId = null;
+
+    if (orderId) {
+      const orderDoc = await admin.firestore().doc(`payments-orders/${orderId}`).get();
+      if (orderDoc.exists) {
+        const orderData = orderDoc.data();
+        // Find the matching price from config using frequency
+        const frequency = orderData.unified?.payment?.frequency;
+        const productId = orderData.unified?.product?.id;
+        const products = assistant.Manager.config.payment?.products || [];
+        const product = products.find(p => p.id === productId);
+        priceId = product?.prices?.[frequency]?.stripe || null;
+      }
+    }
+
+    // Build a Stripe-shaped customer.subscription.updated payload
+    // with cancel_at_period_end=true — mirrors what Stripe sends after cancellation
+    const subscriptionObj = {
+      id: resourceId,
+      object: 'subscription',
+      status: 'active',
+      metadata: { uid, orderId },
+      cancel_at_period_end: true,
+      cancel_at: periodEnd,
+      canceled_at: null,
+      current_period_end: periodEnd,
+      current_period_start: now - (30 * 86400),
+      start_date: now - (30 * 86400),
+      trial_start: null,
+      trial_end: null,
+      plan: { id: priceId, interval: 'month' },
+    };
+
+    const nowTs = powertools.timestamp(new Date(), { output: 'string' });
+    const nowUNIX = powertools.timestamp(nowTs, { output: 'unix' });
+
+    // Write directly to payments-webhooks — on-write trigger handles the rest
+    await admin.firestore().doc(`payments-webhooks/${eventId}`).set({
+      id: eventId,
+      processor: 'test',
+      status: 'pending',
+      owner: uid,
+      raw: {
+        id: eventId,
+        type: 'customer.subscription.updated',
+        data: { object: subscriptionObj },
+      },
+      event: {
+        type: 'customer.subscription.updated',
+        category: 'subscription',
+        resourceType: 'subscription',
+        resourceId: resourceId,
+      },
+      error: null,
+      metadata: {
+        received: {
+          timestamp: nowTs,
+          timestampUNIX: nowUNIX,
+        },
+        processed: {
+          timestamp: null,
+          timestampUNIX: null,
+        },
+      },
+    });
+
+    assistant.log(`Test cancel processor: wrote payments-webhooks/${eventId} for sub=${resourceId}, uid=${uid}`);
+  },
+};

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

@@ -30,7 +30,7 @@ module.exports = {
 
     // Resolve or create Stripe customer (keyed by uid in metadata)
     const email = assistant?.getUser()?.auth?.email || null;
-    const customer = await resolveCustomer(stripe, uid, email, assistant);
+    const customer = await StripeLib.resolveCustomer(uid, email, assistant);
 
     assistant.log(`Stripe checkout: type=${productType}, priceId=${priceId}, uid=${uid}, customerId=${customer.id}, trial=${trial}, trialDays=${product.trial?.days || 'none'}`);
 
@@ -118,32 +118,3 @@ function buildOneTimeSession({ priceId, customer, uid, orderId, productId, produ
   };
 }
 
-/**
- * Find an existing Stripe customer by uid metadata, or create one
- */
-async function resolveCustomer(stripe, uid, email, assistant) {
-  // Search for existing customer with this uid
-  const search = await stripe.customers.search({
-    query: `metadata['uid']:'${uid}'`,
-    limit: 1,
-  });
-
-  if (search.data.length > 0) {
-    const existing = search.data[0];
-    assistant.log(`Found existing Stripe customer: ${existing.id}`);
-    return existing;
-  }
-
-  // Create new customer
-  const params = {
-    metadata: { uid },
-  };
-
-  if (email) {
-    params.email = email;
-  }
-
-  const customer = await stripe.customers.create(params);
-  assistant.log(`Created new Stripe customer: ${customer.id}`);
-  return customer;
-}

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

@@ -0,0 +1,54 @@
+const path = require('path');
+
+/**
+ * POST /payments/portal
+ * Creates a Stripe Billing Portal session for the authenticated user.
+ * The portal allows managing payment methods and viewing invoices,
+ * but does NOT allow cancellation (users must use POST /payments/cancel).
+ * Requires authentication.
+ */
+module.exports = async ({ assistant, user, settings }) => {
+  // Require authentication
+  if (!user.authenticated) {
+    return assistant.respond('Authentication required', { code: 401 });
+  }
+
+  const uid = user.auth.uid;
+  const returnUrl = settings.returnUrl;
+  const subscription = user.subscription;
+
+  // Require a paid subscription (any status — suspended users can still manage billing)
+  if (!subscription || subscription.product?.id === 'basic') {
+    assistant.log(`Portal rejected: uid=${uid}, product=${subscription?.product?.id}`);
+    return assistant.respond('No paid subscription found', { code: 400 });
+  }
+
+  const processor = subscription.payment?.processor;
+
+  if (!processor) {
+    assistant.log(`Portal rejected: uid=${uid}, no processor set`);
+    return assistant.respond('Subscription payment processor not found', { code: 400 });
+  }
+
+  // Load the processor module
+  let processorModule;
+  try {
+    processorModule = require(path.resolve(__dirname, `processors/${processor}.js`));
+  } catch (e) {
+    return assistant.respond(`Unknown processor: ${processor}`, { code: 400 });
+  }
+
+  // Create the portal session via the processor
+  const email = user.auth?.email || null;
+  let result;
+  try {
+    result = await processorModule.createPortalSession({ uid, email, returnUrl, assistant });
+  } catch (e) {
+    assistant.log(`Failed to create ${processor} portal session: ${e.message}`);
+    return assistant.respond(`Failed to create portal session: ${e.message}`, { code: 500, sentry: true });
+  }
+
+  assistant.log(`Portal session created: uid=${uid}, processor=${processor}`);
+
+  return assistant.respond({ url: result.url });
+};

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

@@ -0,0 +1,62 @@
+/**
+ * Stripe portal processor
+ * Creates a Stripe Billing Portal session with cancellation disabled.
+ * The portal config is lazily created and cached per cold start.
+ */
+
+// Cached portal configuration ID (no cancellation allowed)
+let portalConfigId = null;
+
+module.exports = {
+  /**
+   * Create a Stripe Billing Portal session
+   *
+   * @param {object} options
+   * @param {string} options.uid - User's UID
+   * @param {string} options.email - User's email (for customer resolution)
+   * @param {string|null} options.returnUrl - URL to return to after portal session
+   * @param {object} options.assistant - Assistant instance for logging
+   * @returns {object} { url }
+   */
+  async createPortalSession({ uid, email, returnUrl, assistant }) {
+    const StripeLib = require('../../../../libraries/payment-processors/stripe.js');
+    const stripe = StripeLib.init();
+
+    // Resolve the Stripe customer for this user
+    const customer = await StripeLib.resolveCustomer(uid, email, assistant);
+
+    // Lazily create and cache a portal configuration with cancellation disabled
+    if (!portalConfigId) {
+      const config = await stripe.billingPortal.configurations.create({
+        business_profile: {
+          headline: 'Manage your subscription',
+        },
+        features: {
+          subscription_cancel: { enabled: false },
+          subscription_update: { enabled: false },
+          payment_method_update: { enabled: true },
+          invoice_history: { enabled: true },
+        },
+      });
+
+      portalConfigId = config.id;
+      assistant.log(`Created Stripe portal config: ${portalConfigId}`);
+    }
+
+    // Build session params
+    const sessionParams = {
+      customer: customer.id,
+      configuration: portalConfigId,
+    };
+
+    if (returnUrl) {
+      sessionParams.return_url = returnUrl;
+    }
+
+    const session = await stripe.billingPortal.sessions.create(sessionParams);
+
+    assistant.log(`Stripe portal session created: uid=${uid}, customerId=${customer.id}, url=${session.url}`);
+
+    return { url: session.url };
+  },
+};