feat(billing): add GET /api/billing/usage endpoint (#3277)

* feat(billing): add GET /api/billing/usage endpoint

* fix(billing): address review feedback on usage endpoint

- Move subscription lookup behind BillingService (service-layer rule)
- Remove SubscriptionRepository import from controller
- Use usage.month for period instead of recomputing (avoid drift)
- Normalize Infinity quotas to null for JSON-safe serialization
- Update tests to match new service boundary and null limits

* fix(billing): use status allowlist for plan resolution in usage endpoint

- Replace past_due-only check with active/trialing allowlist
- All other statuses (canceled, unpaid, incomplete, etc.) now map to free
- Add test.each for all non-active statuses + trialing test

Author: PierreBrisorgueil

lib/middlewares/policy.js

@@ -195,6 +195,7 @@ 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/usage') return 'BillingUsage';
   if (routePath === '/api/billing/plans') return 'BillingPlans';
   if (routePath.startsWith('/api/tasks')) return 'Task';
   if (routePath.startsWith('/api/uploads')) return 'Upload';

modules/billing/controllers/billing.controller.js

@@ -1,8 +1,10 @@
 /**
  * Module dependencies
  */
+import config from '../../../config/index.js';
 import responses from '../../../lib/helpers/responses.js';
 import BillingService from '../services/billing.service.js';
+import BillingUsageService from '../services/billing.usage.service.js';
 
 /**
  * @desc Endpoint to create a Stripe Checkout session
@@ -55,8 +57,50 @@ const getSubscription = async (req, res) => {
   }
 };
 
+/**
+ * @desc Endpoint to get billing usage for the current organization
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @returns {Promise<void>}
+ */
+const getUsage = async (req, res) => {
+  try {
+    // Determine current plan via service layer
+    const subscription = await BillingService.getSubscription(req.organization._id);
+    const activeStatuses = ['active', 'trialing'];
+    const plan = (!subscription || !activeStatuses.includes(subscription.status)) ? 'free' : (subscription.plan || 'free');
+
+    // Get usage counters (includes month field)
+    const usage = await BillingUsageService.get(req.organization._id.toString());
+
+    // Flatten quotas config into { "resource.action": limit } format
+    // Normalize Infinity to null for JSON-safe serialization
+    const quotas = config.billing?.quotas;
+    let limits = {};
+    if (quotas?.[plan]) {
+      const planQuotas = quotas[plan];
+      for (const resource of Object.keys(planQuotas)) {
+        for (const action of Object.keys(planQuotas[resource])) {
+          const rawLimit = planQuotas[resource][action];
+          limits[`${resource}.${action}`] = Number.isFinite(rawLimit) ? rawLimit : null;
+        }
+      }
+    }
+
+    responses.success(res, 'billing usage')({
+      plan,
+      period: usage.month,
+      usage: usage.counters || {},
+      limits,
+    });
+  } catch (err) {
+    responses.error(res, 500, 'Internal Server Error', 'Failed to retrieve billing usage')(err);
+  }
+};
+
 export default {
   checkout,
   portal,
   getSubscription,
+  getUsage,
 };

modules/billing/policies/billing.policy.js

@@ -24,6 +24,7 @@ export function billingAbilities(user, membership, { can, cannot }) {
   can('create', 'BillingCheckout');
   can('create', 'BillingPortal');
   can('read', 'BillingSubscription');
+  can('read', 'BillingUsage');
 }
 
 /**

modules/billing/routes/billing.routes.js

@@ -36,4 +36,10 @@ export default (app) => {
     .route('/api/billing/subscription')
     .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
     .get(billing.getSubscription);
+
+  // usage
+  app
+    .route('/api/billing/usage')
+    .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
+    .get(billing.getUsage);
 };

modules/billing/tests/billing.usage.endpoint.unit.tests.js

@@ -0,0 +1,210 @@
+/**
+ * Module dependencies.
+ */
+import { jest, beforeEach, afterEach } from '@jest/globals';
+
+/**
+ * Unit tests for billing usage endpoint (getUsage controller)
+ */
+describe('Billing usage endpoint unit tests:', () => {
+  let billingController;
+  let mockBillingService;
+  let mockBillingUsageService;
+  let mockConfig;
+  let res;
+
+  const orgId = '507f1f77bcf86cd799439011';
+
+  beforeEach(async () => {
+    jest.resetModules();
+
+    mockBillingService = {
+      getSubscription: jest.fn(),
+    };
+
+    mockBillingUsageService = {
+      get: jest.fn(),
+    };
+
+    mockConfig = {
+      billing: {
+        quotas: {
+          free: { documents: { create: 5 }, requests: { execute: 100 } },
+          starter: { documents: { create: 20 }, requests: { execute: 2000 } },
+          pro: { documents: { create: Infinity }, requests: { execute: Infinity } },
+        },
+      },
+    };
+
+    jest.unstable_mockModule('../services/billing.service.js', () => ({
+      default: mockBillingService,
+    }));
+
+    jest.unstable_mockModule('../services/billing.usage.service.js', () => ({
+      default: mockBillingUsageService,
+    }));
+
+    jest.unstable_mockModule('../../../config/index.js', () => ({
+      default: mockConfig,
+    }));
+
+    const mod = await import('../controllers/billing.controller.js');
+    billingController = mod.default;
+
+    res = {
+      status: jest.fn().mockReturnThis(),
+      json: jest.fn().mockReturnThis(),
+    };
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('should return usage and limits for active subscription', async () => {
+    mockBillingService.getSubscription.mockResolvedValue({ plan: 'starter', status: 'active' });
+    mockBillingUsageService.get.mockResolvedValue({ month: '2026-03', counters: { 'documents.create': 5, 'requests.execute': 42 } });
+
+    const req = { organization: { _id: orgId } };
+    await billingController.getUsage(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      type: 'success',
+      message: 'billing usage',
+      data: expect.objectContaining({
+        plan: 'starter',
+        usage: { 'documents.create': 5, 'requests.execute': 42 },
+        limits: { 'documents.create': 20, 'requests.execute': 2000 },
+      }),
+    }));
+  });
+
+  test('should return free plan when no subscription', async () => {
+    mockBillingService.getSubscription.mockResolvedValue(null);
+    mockBillingUsageService.get.mockResolvedValue({ month: '2026-03', counters: {} });
+
+    const req = { organization: { _id: orgId } };
+    await billingController.getUsage(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      type: 'success',
+      data: expect.objectContaining({
+        plan: 'free',
+        limits: { 'documents.create': 5, 'requests.execute': 100 },
+      }),
+    }));
+  });
+
+  test.each([
+    'past_due',
+    'canceled',
+    'unpaid',
+    'incomplete',
+    'incomplete_expired',
+    'paused',
+  ])('should return free plan when subscription status is %s', async (status) => {
+    mockBillingService.getSubscription.mockResolvedValue({ plan: 'starter', status });
+    mockBillingUsageService.get.mockResolvedValue({ month: '2026-03', counters: { 'documents.create': 2 } });
+
+    const req = { organization: { _id: orgId } };
+    await billingController.getUsage(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      data: expect.objectContaining({
+        plan: 'free',
+        limits: { 'documents.create': 5, 'requests.execute': 100 },
+      }),
+    }));
+  });
+
+  test('should return paid plan when subscription status is trialing', async () => {
+    mockBillingService.getSubscription.mockResolvedValue({ plan: 'starter', status: 'trialing' });
+    mockBillingUsageService.get.mockResolvedValue({ month: '2026-03', counters: {} });
+
+    const req = { organization: { _id: orgId } };
+    await billingController.getUsage(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      data: expect.objectContaining({
+        plan: 'starter',
+        limits: { 'documents.create': 20, 'requests.execute': 2000 },
+      }),
+    }));
+  });
+
+  test('should return empty limits when plan has no quota config', async () => {
+    mockBillingService.getSubscription.mockResolvedValue({ plan: 'enterprise', status: 'active' });
+    mockBillingUsageService.get.mockResolvedValue({ month: '2026-03', counters: {} });
+
+    const req = { organization: { _id: orgId } };
+    await billingController.getUsage(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      data: expect.objectContaining({
+        plan: 'enterprise',
+        limits: {},
+      }),
+    }));
+  });
+
+  test('should return correct flattened limits format', async () => {
+    mockBillingService.getSubscription.mockResolvedValue({ plan: 'pro', status: 'active' });
+    mockBillingUsageService.get.mockResolvedValue({ month: '2026-03', counters: {} });
+
+    const req = { organization: { _id: orgId } };
+    await billingController.getUsage(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      data: expect.objectContaining({
+        plan: 'pro',
+        limits: { 'documents.create': null, 'requests.execute': null },
+      }),
+    }));
+  });
+
+  test('should return empty counters for new org (no usage yet)', async () => {
+    mockBillingService.getSubscription.mockResolvedValue({ plan: 'starter', status: 'active' });
+    mockBillingUsageService.get.mockResolvedValue({ month: '2026-03', counters: {} });
+
+    const req = { organization: { _id: orgId } };
+    await billingController.getUsage(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      data: expect.objectContaining({
+        usage: {},
+      }),
+    }));
+  });
+
+  test('should return period from usage month field', async () => {
+    mockBillingService.getSubscription.mockResolvedValue({ plan: 'free', status: 'active' });
+    mockBillingUsageService.get.mockResolvedValue({ month: '2026-03', counters: {} });
+
+    const req = { organization: { _id: orgId } };
+    await billingController.getUsage(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    const { data } = res.json.mock.calls[0][0];
+    expect(data.period).toBe('2026-03');
+  });
+
+  test('should return 500 when an error occurs', async () => {
+    mockBillingService.getSubscription.mockRejectedValue(new Error('DB error'));
+
+    const req = { organization: { _id: orgId } };
+    await billingController.getUsage(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(500);
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      type: 'error',
+      message: 'Internal Server Error',
+    }));
+  });
+});