feat(billing): add checkout, portal, and subscription endpoints

Add authenticated billing endpoints behind JWT + organization middleware:
- POST /api/billing/checkout — creates Stripe Checkout session
- POST /api/billing/portal — creates Stripe Customer Portal session
- GET /api/billing/subscription — returns org subscription

Includes CASL policy, service layer with lazy Stripe init, and
deriveSubjectType mappings for billing routes.

Closes #3245

Author: PierreBrisorgueil

lib/middlewares/policy.js

@@ -189,6 +189,10 @@ const USER_ROUTE_SUBJECTS = {
  * @returns {string|null} CASL subject type or null if not mappable
  */
 const deriveSubjectType = (routePath) => {
+  if (routePath === '/api/billing/checkout') return 'BillingCheckout';
+  if (routePath === '/api/billing/portal') return 'BillingPortal';
+  if (routePath === '/api/billing/subscription') return 'BillingSubscription';
+  if (routePath === '/api/billing/plans') return 'BillingPlans';
   if (routePath.startsWith('/api/tasks')) return 'Task';
   if (routePath.startsWith('/api/uploads')) return 'Upload';
   if (routePath.startsWith('/api/home')) return 'Home';

modules/billing/controllers/billing.controller.js

@@ -0,0 +1,57 @@
+/**
+ * Module dependencies
+ */
+import responses from '../../../lib/helpers/responses.js';
+import BillingService from '../services/billing.service.js';
+
+/**
+ * @desc Endpoint to create a Stripe Checkout session
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @returns {Promise<void>}
+ */
+const checkout = async (req, res) => {
+  try {
+    const { priceId, successUrl, cancelUrl } = req.body;
+    const url = await BillingService.createCheckout(req.organization, priceId, successUrl, cancelUrl);
+    responses.success(res, 'checkout session created')({ url });
+  } catch (err) {
+    responses.error(res, 422, 'Unprocessable Entity', 'Failed to create checkout session')(err);
+  }
+};
+
+/**
+ * @desc Endpoint to create a Stripe Customer Portal session
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @returns {Promise<void>}
+ */
+const portal = async (req, res) => {
+  try {
+    const url = await BillingService.createPortalSession(req.organization);
+    responses.success(res, 'portal session created')({ url });
+  } catch (err) {
+    responses.error(res, 422, 'Unprocessable Entity', 'Failed to create portal session')(err);
+  }
+};
+
+/**
+ * @desc Endpoint to get the subscription for the current organization
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @returns {Promise<void>}
+ */
+const getSubscription = async (req, res) => {
+  try {
+    const subscription = await BillingService.getSubscription(req.organization._id);
+    responses.success(res, 'subscription')(subscription);
+  } catch (err) {
+    responses.error(res, 500, 'Internal Server Error', 'Failed to retrieve subscription')(err);
+  }
+};
+
+export default {
+  checkout,
+  portal,
+  getSubscription,
+};

modules/billing/policies/.gitkeep

@@ -0,0 +1,36 @@
+/**
+ * Billing ability definitions for CASL document-level authorization.
+ */
+
+/**
+ * Define billing-related abilities for an authenticated user.
+ * Any authenticated user with an organization membership can manage billing.
+ * @param {Object} user - The authenticated user
+ * @param {Object|null} membership - Optional organization membership
+ * @param {Object} builder - CASL AbilityBuilder helpers
+ * @param {Function} builder.can - Grant an ability
+ * @param {Function} builder.cannot - Deny an ability
+ */
+// eslint-disable-next-line no-unused-vars
+export function billingAbilities(user, membership, { can, cannot }) {
+  if (Array.isArray(user?.roles) && user.roles.includes('admin')) {
+    can('manage', 'all');
+    return;
+  }
+
+  if (!membership) return;
+
+  can('create', 'BillingCheckout');
+  can('create', 'BillingPortal');
+  can('read', 'BillingSubscription');
+}
+
+/**
+ * Define billing-related abilities for guest (unauthenticated) users.
+ * Guests can read billing plans (public route).
+ * @param {Object} builder - CASL AbilityBuilder helpers
+ * @param {Function} builder.can - Grant an ability
+ */
+export function billingGuestAbilities({ can }) {
+  can('read', 'BillingPlans');
+}

modules/billing/policies/billing.policy.js

@@ -1,7 +1,12 @@
 /**
  * Module dependencies
  */
-import billing from '../controllers/billing.plans.controller.js';
+import passport from 'passport';
+
+import policy from '../../../lib/middlewares/policy.js';
+import organization from '../../organizations/middleware/organizations.middleware.js';
+import billingPlans from '../controllers/billing.plans.controller.js';
+import billing from '../controllers/billing.controller.js';
 
 /**
  * @desc Register billing routes
@@ -10,5 +15,23 @@ import billing from '../controllers/billing.plans.controller.js';
  */
 export default (app) => {
   // plans (public)
-  app.route('/api/billing/plans').get(billing.getPlans);
+  app.route('/api/billing/plans').get(billingPlans.getPlans);
+
+  // checkout
+  app
+    .route('/api/billing/checkout')
+    .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
+    .post(billing.checkout);
+
+  // portal
+  app
+    .route('/api/billing/portal')
+    .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
+    .post(billing.portal);
+
+  // subscription
+  app
+    .route('/api/billing/subscription')
+    .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
+    .get(billing.getSubscription);
 };

modules/billing/routes/billing.routes.js

@@ -0,0 +1,100 @@
+/**
+ * Module dependencies
+ */
+import Stripe from 'stripe';
+
+import config from '../../../config/index.js';
+import SubscriptionRepository from '../repositories/billing.subscription.repository.js';
+
+/**
+ * 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 Create a Stripe Checkout Session for the given organization
+ * @param {Object} organization - The organization document
+ * @param {String} priceId - Stripe price ID
+ * @param {String} successUrl - URL to redirect on success
+ * @param {String} cancelUrl - URL to redirect on cancel
+ * @returns {Promise<String>} Checkout session URL
+ */
+const createCheckout = async (organization, priceId, successUrl, cancelUrl) => {
+  const stripe = getStripe();
+  if (!stripe) throw new Error('Stripe is not configured');
+
+  // Find or create subscription record with Stripe customer
+  let subscription = await SubscriptionRepository.findByOrganization(organization._id);
+
+  if (!subscription?.stripeCustomerId) {
+    const customer = await stripe.customers.create({
+      name: organization.name,
+      metadata: { organizationId: String(organization._id) },
+    });
+
+    if (subscription) {
+      subscription = await SubscriptionRepository.update({
+        ...subscription.toObject(),
+        stripeCustomerId: customer.id,
+      });
+    } else {
+      subscription = await SubscriptionRepository.create({
+        organization: organization._id,
+        stripeCustomerId: customer.id,
+      });
+    }
+  }
+
+  const session = await stripe.checkout.sessions.create({
+    customer: subscription.stripeCustomerId,
+    mode: 'subscription',
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: successUrl,
+    cancel_url: cancelUrl,
+  });
+
+  return session.url;
+};
+
+/**
+ * @desc Create a Stripe Customer Portal session for the given organization
+ * @param {Object} organization - The organization document
+ * @returns {Promise<String>} Portal session URL
+ */
+const createPortalSession = async (organization) => {
+  const stripe = getStripe();
+  if (!stripe) throw new Error('Stripe is not configured');
+
+  const subscription = await SubscriptionRepository.findByOrganization(organization._id);
+  if (!subscription?.stripeCustomerId) throw new Error('No Stripe customer found for this organization');
+
+  const session = await stripe.billingPortal.sessions.create({
+    customer: subscription.stripeCustomerId,
+  });
+
+  return session.url;
+};
+
+/**
+ * @desc Get subscription for the given organization
+ * @param {String} organizationId - The organization ID
+ * @returns {Promise<Object|null>} The subscription document or null
+ */
+const getSubscription = async (organizationId) => SubscriptionRepository.findByOrganization(organizationId);
+
+export default {
+  createCheckout,
+  createPortalSession,
+  getSubscription,
+};