fix(billing): warn on getUsage meterQuota fallback when live plan config missing

Addresses review: getUsage silently fell back to the DB snapshot/0 when
getActivePlan returned null, masking plan/config mismatches. getUsage is a
read-only display endpoint (not a gate — billing.requireQuota already fails
safe with 503 on the work path), so it degrades gracefully but now emits a
warn log for ops visibility. Comment updated to document the fallback.

Author: PierreBrisorgueil

modules/billing/controllers/billing.controller.js

@@ -94,9 +94,21 @@ const getUsage = async (req, res) => {
       const extrasRemaining = await BillingExtraService.getOrgBalanceContext(req.organization._id.toString());
       const packsAvailable = config.billing?.packs ?? [];
 
-      // Derive meterQuota from the live plan config — DB snapshot is stale after a plan upgrade
-      // (free → growth) until the next incrementMeter call. Live config is authoritative.
+      // Derive meterQuota from the live plan config — the DB snapshot is stale after a
+      // plan upgrade (free → growth) until the next incrementMeter call, so live config
+      // is authoritative when present. When it is absent (legacy plan dropped from config,
+      // or seeding / version bump in progress) this is a read-only display endpoint, not a
+      // gate: billing.requireQuota already fails safe with 503 on the work path, so here we
+      // degrade gracefully to the DB snapshot (or 0) and warn for ops visibility rather than
+      // failing the usage page.
       const livePlan = BillingPlanService.getActivePlan(plan);
+      if (!livePlan) {
+        logger.warn('[billing.getUsage] no live plan definition for planId — falling back to DB snapshot quota', {
+          planId: plan,
+          organizationId: req.organization._id.toString(),
+          snapshotQuota: meter?.meterQuota ?? null,
+        });
+      }
       const liveQuota = livePlan?.meterQuota ?? meter?.meterQuota ?? 0;
 
       return responses.success(res, 'billing usage')({

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

@@ -240,6 +240,7 @@ describe('Billing usage endpoint unit tests:', () => {
   describe('meterMode — meterQuota live override', () => {
     let mockBillingPlanService;
     let mockMeterUsageService;
+    let mockLogger;
 
     beforeEach(async () => {
       jest.resetModules();
@@ -274,8 +275,9 @@ describe('Billing usage endpoint unit tests:', () => {
         default: mockBillingPlanService,
       }));
 
+      mockLogger = { info: jest.fn(), error: jest.fn(), warn: jest.fn() };
       jest.unstable_mockModule('../../../lib/services/logger.js', () => ({
-        default: { info: jest.fn(), error: jest.fn(), warn: jest.fn() },
+        default: mockLogger,
       }));
       jest.unstable_mockModule('../lib/events.js', () => ({
         default: { emit: jest.fn() },
@@ -321,6 +323,7 @@ describe('Billing usage endpoint unit tests:', () => {
       expect(payload.meterQuota).toBe(1600); // live plan config, not stale DB snapshot
       expect(payload.meterUsed).toBe(46);
       expect(payload.plan).toBe('growth');
+      expect(mockLogger.warn).not.toHaveBeenCalled(); // live plan present — no fallback warn
     });
 
     test('falls back to DB snapshot quota when live plan config returns null (unknown plan)', async () => {
@@ -341,6 +344,11 @@ describe('Billing usage endpoint unit tests:', () => {
       expect(res.status).toHaveBeenCalledWith(200);
       const payload = res.json.mock.calls[0][0].data;
       expect(payload.meterQuota).toBe(50); // falls back to DB snapshot
+      // Fallback path masks a plan/config mismatch — warn for ops visibility.
+      expect(mockLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('no live plan definition'),
+        expect.objectContaining({ planId: 'legacy', snapshotQuota: 50 }),
+      );
     });
 
     test('returns 0 meterQuota when no DB snapshot and no live config plan', async () => {