feat(billing): add GET /api/billing/plans public endpoint

Fetches active products and prices from Stripe, maps them to a
normalized plan format, and caches results in-memory for 1 hour.
Returns a default free plan when Stripe is not configured.

Closes #3244

Author: PierreBrisorgueil

modules/billing/controllers/.gitkeep

@@ -0,0 +1,24 @@
+/**
+ * Module dependencies
+ */
+import errors from '../../../lib/helpers/errors.js';
+import responses from '../../../lib/helpers/responses.js';
+import BillingPlansService from '../services/billing.plans.service.js';
+
+/**
+ * @desc Endpoint to get billing plans
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ */
+const getPlans = async (req, res) => {
+  try {
+    const plans = await BillingPlansService.getPlans();
+    responses.success(res, 'billing plans')(plans);
+  } catch (err) {
+    responses.error(res, 422, 'Unprocessable Entity', errors.getMessage(err))(err);
+  }
+};
+
+export default {
+  getPlans,
+};

modules/billing/controllers/billing.plans.controller.js

@@ -0,0 +1,12 @@
+/**
+ * Module dependencies
+ */
+import billing from '../controllers/billing.plans.controller.js';
+
+/**
+ * Routes
+ */
+export default (app) => {
+  // plans (public)
+  app.route('/api/billing/plans').get(billing.getPlans);
+};

modules/billing/routes/.gitkeep

@@ -0,0 +1,108 @@
+/**
+ * Module dependencies
+ */
+import Stripe from 'stripe';
+
+import config from '../../../config/index.js';
+
+/**
+ * In-memory cache for plans
+ */
+let cachedPlans = null;
+let cacheTimestamp = 0;
+const CACHE_TTL = 60 * 60 * 1000; // 1 hour
+
+/**
+ * Default free plan returned when Stripe is not configured
+ */
+const DEFAULT_FREE_PLAN = {
+  planId: 'free',
+  name: 'Free',
+  monthlyPrice: 0,
+  annualPrice: 0,
+  stripePriceMonthly: null,
+  stripePriceAnnual: null,
+};
+
+/**
+ * Lazily instantiated Stripe client
+ */
+let stripeClient = null;
+
+/**
+ * @desc Get or create the Stripe client instance
+ * @returns {Object|null} Stripe client or null if not configured
+ */
+const getStripe = () => {
+  if (stripeClient) return stripeClient;
+  if (!config.stripe?.secretKey) return null;
+  stripeClient = new Stripe(config.stripe.secretKey);
+  return stripeClient;
+};
+
+/**
+ * @desc Fetch plans from Stripe and map to normalized format
+ * @returns {Promise<Array>} sorted array of plan objects
+ */
+const fetchPlansFromStripe = async (stripe) => {
+  const products = await stripe.products.list({
+    active: true,
+    expand: ['data.default_price'],
+  });
+
+  const plans = await Promise.all(
+    products.data.map(async (product) => {
+      const prices = await stripe.prices.list({
+        product: product.id,
+        active: true,
+      });
+
+      let monthlyPrice = 0;
+      let annualPrice = 0;
+      let stripePriceMonthly = null;
+      let stripePriceAnnual = null;
+
+      for (const price of prices.data) {
+        if (price.recurring?.interval === 'month') {
+          monthlyPrice = price.unit_amount / 100;
+          stripePriceMonthly = price.id;
+        } else if (price.recurring?.interval === 'year') {
+          annualPrice = price.unit_amount / 100;
+          stripePriceAnnual = price.id;
+        }
+      }
+
+      return {
+        planId: product.metadata?.planId || product.id,
+        name: product.name,
+        monthlyPrice,
+        annualPrice,
+        stripePriceMonthly,
+        stripePriceAnnual,
+      };
+    }),
+  );
+
+  return plans.sort((a, b) => a.monthlyPrice - b.monthlyPrice);
+};
+
+/**
+ * @desc Get billing plans with in-memory caching
+ * @returns {Promise<Array>} array of plan objects sorted by monthlyPrice ascending
+ */
+const getPlans = async () => {
+  const stripe = getStripe();
+  if (!stripe) return [DEFAULT_FREE_PLAN];
+
+  const now = Date.now();
+  if (cachedPlans && now - cacheTimestamp < CACHE_TTL) return cachedPlans;
+
+  const plans = await fetchPlansFromStripe(stripe);
+  cachedPlans = plans;
+  cacheTimestamp = Date.now();
+  return plans;
+};
+
+export default {
+  getPlans,
+};