feat(billing): plan source-of-truth + plan seed + meterExempt Zod (PR-N6) (#3555)

* feat(billing): plan source-of-truth + plan seed + meterExempt Zod (PR-N6)

P0 + P1.7 unblockers for activating meterMode in prod.

- P0.1: read planId from Subscription.plan of org instead of config.billing.plans[0]
        (which always returned 'free'). Fallback now configurable via billing.defaultPlan.
- P0.2: BillingPlanService.ensureSeeded() upserts BillingPlan docs from
        config.billing.planDefinitions at boot. Idempotent. No-op when meterMode=false.
- P0.3: add meterExempt to organizations Zod schema (was on Mongoose only,
        silently dropped on PUT/PATCH).
- P1.7: declare billing.upgradeUrl + billing.defaultPlan in default config
        (already used by middleware with hardcoded fallback).

* fix(billing): lean subscription lookup + E11000-safe ensureSeeded + fail-fast on seed error

Review fixes for PR-N6 (Codacy/Copilot threads):

- billing.subscription.repository: add findPlan() — lean projection {plan:1}, no populate,
  for hot-path meter attribution and weekly reset (avoids org join cost on every incrementMeter).
- billing.usage.service + billing.reset.service: switch from findByOrganization to findPlan.
- billing.plan.service.ensureSeeded: derive version from count() instead of hardcoding 'v1'
  (avoids E11000 when an inactive v1 record exists). Wrap create in try-catch: E11000
  from concurrent pod startup races is absorbed as a skip, not fatal.
- billing.init: re-throw ensureSeeded failure when meterMode=true — prevents deploy from
  succeeding in a broken state where all quota resolutions return 0.
- Tests: add coverage for count>0 version derivation, E11000 race skip, non-E11000 propagation.
  Update billing.usage.service, billing.reset.service and cron weeklyReset tests to mock
  findPlan instead of findByOrganization.

* test(billing): add coverage for billing.init fail-fast + findPlan guard

- Add billing.init.unit.tests.js: 4 tests covering ensureSeeded integration
  (called at init, swallowed when meterMode=false, re-throws when meterMode=true,
  logs info on seeded>0)
- Add findPlan describe block to billing.subscription.repository.unit.tests.js:
  3 tests covering valid ID, invalid ID guard (no DB call), and null on no match

Closes codecov/project regression introduced by 9e71c74.

* fix(billing): add enterprise to planDefinitions

CodeRabbit flagged that billing.plans enum includes 'enterprise' but
planDefinitions did not — bootstrap seeding would skip enterprise and
downstream resolution would fall back to meterQuota=0 for enterprise orgs.

Author: PierreBrisorgueil

modules/billing/billing.init.js

@@ -4,6 +4,7 @@
 import config from '../../config/index.js';
 import AnalyticsService from '../../lib/services/analytics.js';
 import billingEvents from './lib/events.js';
+import BillingPlanService from './services/billing.plan.service.js';
 
 /**
  * Billing module initialisation.
@@ -29,4 +30,17 @@ export default async (app) => {
       AnalyticsService.groupIdentify('company', String(organizationId), { plan: newPlan });
     } catch (_) { /* analytics must not break billing flow */ }
   });
+
+  try {
+    const { seeded, skipped } = await BillingPlanService.ensureSeeded();
+    if (seeded > 0) {
+      console.info(`[billing] seeded ${seeded} plan(s) from config.billing.planDefinitions (skipped ${skipped} already active)`);
+    }
+  } catch (err) {
+    console.error('[billing] ensureSeeded failed:', err);
+    // Fail fast when meterMode is enabled: a seeding failure means quota resolution
+    // will return 0 for all plans, silently gating all metered operations.
+    // Surfacing the crash here prevents a deploy from succeeding in a broken state.
+    if (config?.billing?.meterMode) throw err;
+  }
 };

modules/billing/config/billing.development.config.js

@@ -31,6 +31,27 @@ const config = {
      * When false, all meter code paths are no-ops; legacy behavior unchanged.
      */
     meterMode: false,
+    /**
+     * Default plan used when an organization has no subscription. Configurable per project.
+     */
+    defaultPlan: 'free',
+    /**
+     * URL the front-end should redirect users to when quota is exhausted or past_due.
+     * Used by middleware error responses (METER_EXHAUSTED, QUOTA_EXCEEDED).
+     */
+    upgradeUrl: '/billing/plans',
+    /**
+     * Plan definitions — DOWNSTREAM-OVERRIDE-REQUIRED for meter mode.
+     * Used by BillingPlanService.ensureSeeded() at boot to upsert BillingPlan docs.
+     * Each entry: { meterQuota: units/week, ratios: { featureKey: multiplier } }.
+     * Plans listed here must also exist in billing.plans enum.
+     */
+    planDefinitions: {
+      free: { meterQuota: 0, ratios: { default: 1 } },
+      starter: { meterQuota: 50000, ratios: { default: 1 } },
+      pro: { meterQuota: 500000, ratios: { default: 1 } },
+      enterprise: { meterQuota: 2000000, ratios: { default: 1 } },
+    },
     /**
      * Meter unit parameters — downstream projects must override with their
      * actual unit economics before enabling meterMode in production.

modules/billing/repositories/billing.subscription.repository.js

@@ -109,6 +109,20 @@ const findByStripeSubscriptionId = (stripeSubscriptionId) => {
   return Subscription.findOne({ stripeSubscriptionId: normalized }).populate(defaultPopulate).exec();
 };
 
+/**
+ * @function findPlan
+ * @description Lean lookup that returns only the `plan` field for a given organization.
+ *              Used on hot paths (meter attribution, weekly reset) where only the plan
+ *              identifier is needed — avoids the full populate overhead of findByOrganization.
+ * @param {String} organizationId - The organization ID.
+ * @returns {Promise<{plan: string}|null>} A lean plain object with just `plan`, or null.
+ */
+// biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js repository, not Qwik
+const findPlan = (organizationId) => {
+  if (!mongoose.Types.ObjectId.isValid(organizationId)) return null;
+  return Subscription.findOne({ organization: organizationId }, { plan: 1 }).lean().exec();
+};
+
 /**
  * @function findAllDueForReset
  * @description Fetch active/trialing subscriptions whose currentPeriodStart falls
@@ -173,6 +187,7 @@ export default {
   update,
   remove,
   findByOrganization,
+  findPlan,
   findByStripeCustomerId,
   findByStripeSubscriptionId,
   findAllDueForReset,

modules/billing/services/billing.plan.service.js

@@ -1,6 +1,7 @@
 /**
  * Module dependencies
  */
+import config from '../../../config/index.js';
 import BillingPlanRepository from '../repositories/billing.plan.repository.js';
 
 /**
@@ -161,10 +162,70 @@ const bumpVersionWithRetry = async (planId, fields, { maxAttempts = 3 } = {}) =>
   throw lastErr;
 };
 
+/**
+ * @function ensureSeeded
+ * @description Upsert BillingPlan docs from config.billing.planDefinitions.
+ *              For each configured planId, ensures an active plan exists.
+ *              No-op when meter mode is disabled. Idempotent on re-run.
+ *
+ *              Race / E11000 safety: version is derived from the total count of
+ *              existing docs for the planId (same strategy as bumpVersion). A
+ *              try-catch on create absorbs E11000 from concurrent multi-pod
+ *              startup races — the losing pod simply increments skipped.
+ *
+ * @returns {Promise<{seeded: number, skipped: number}>} Seed summary.
+ */
+// biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js service, not Qwik
+const ensureSeeded = async () => {
+  if (!config?.billing?.meterMode) return { seeded: 0, skipped: 0 };
+
+  const definitions = config?.billing?.planDefinitions ?? {};
+  let seeded = 0;
+  let skipped = 0;
+
+  for (const [planId, def] of Object.entries(definitions)) {
+    const existing = await BillingPlanRepository.findActive(planId);
+    if (existing) {
+      skipped += 1;
+      continue;
+    }
+
+    try {
+      // Derive version from total count so that an inactive v1 record does not
+      // collide with the insert (same approach as bumpVersion to avoid hardcoding 'v1').
+      const total = await BillingPlanRepository.count(planId);
+      const version = `v${total + 1}`;
+
+      await BillingPlanRepository.create({
+        planId,
+        version,
+        meterQuota: def.meterQuota ?? 0,
+        ratios: def.ratios ?? { default: 1 },
+        effectiveFrom: new Date(),
+        effectiveUntil: null,
+        active: true,
+      });
+      cache.delete(planId);
+      seeded += 1;
+    } catch (err) {
+      // E11000: concurrent pod beat us to the insert — treat as skip, not fatal.
+      const isE11000 = err.code === 11000 || (err.message && err.message.includes('E11000'));
+      if (isE11000) {
+        skipped += 1;
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  return { seeded, skipped };
+};
+
 export default {
   getActivePlan,
   getPlanByVersion,
   bumpVersion,
   bumpVersionWithRetry,
+  ensureSeeded,
   invalidateCache,
 };

modules/billing/services/billing.reset.service.js

@@ -50,8 +50,9 @@ const resetWeek = async (orgId, periodStart) => {
   // Delegates to repository — no mongoose import in service layer.
   await BillingUsageRepository.archiveOtherWeeks(orgId, newWeekKey, now);
 
-  // Step 2 — Fetch the active plan to snapshot quota/planVersion.
-  const planId = config?.billing?.plans?.[0] ?? 'pro';
+  // Step 2 — Fetch the active plan to snapshot quota/planVersion — lean projection (plan only, no populate).
+  const subscription = await BillingSubscriptionRepository.findPlan(orgId);
+  const planId = subscription?.plan ?? config?.billing?.defaultPlan ?? 'free';
   const activePlan = await BillingPlanService.getActivePlan(planId);
   const meterQuota = activePlan?.meterQuota ?? 0;
   const planVersion = activePlan?.version ?? null;

modules/billing/services/billing.usage.service.js

@@ -3,6 +3,7 @@
  */
 import config from '../../../config/index.js';
 import UsageRepository from '../repositories/billing.usage.repository.js';
+import BillingSubscriptionRepository from '../repositories/billing.subscription.repository.js';
 import BillingPlanService from './billing.plan.service.js';
 
 /**
@@ -104,8 +105,9 @@ const incrementMeter = async (organizationId, units, breakdown, idempotencyKey)
   const weekKey = currentWeekKey();
   const monthKey = currentMonth();
 
-  // Fetch active plan for quota snapshot
-  const planId = config?.billing?.plans?.[0] ?? 'pro';
+  // Fetch active plan for quota snapshot — lean projection (plan field only, no populate)
+  const subscription = await BillingSubscriptionRepository.findPlan(organizationId);
+  const planId = subscription?.plan ?? config?.billing?.defaultPlan ?? 'free';
   const activePlan = await BillingPlanService.getActivePlan(planId);
   const meterQuota = activePlan?.meterQuota ?? 0;
   const planVersion = activePlan?.version ?? null;

modules/billing/tests/billing.init.unit.tests.js

@@ -0,0 +1,84 @@
+/**
+ * Module dependencies.
+ */
+import { jest, describe, test, beforeEach, afterEach, expect } from '@jest/globals';
+
+/**
+ * Unit tests for billing.init ensureSeeded integration.
+ */
+describe('billing.init ensureSeeded unit tests:', () => {
+  let billingInit;
+  let mockBillingPlanService;
+  let mockConfig;
+
+  const mockApp = {};
+
+  beforeEach(async () => {
+    jest.resetModules();
+
+    mockConfig = {
+      billing: {
+        meterMode: false,
+        packs: [],
+      },
+    };
+
+    mockBillingPlanService = {
+      ensureSeeded: jest.fn().mockResolvedValue({ seeded: 0, skipped: 0 }),
+    };
+
+    jest.unstable_mockModule('../../../config/index.js', () => ({
+      default: mockConfig,
+    }));
+
+    jest.unstable_mockModule('../services/billing.plan.service.js', () => ({
+      default: mockBillingPlanService,
+    }));
+
+    // Stub analytics and events to avoid side effects
+    jest.unstable_mockModule('../../../lib/services/analytics.js', () => ({
+      default: { groupIdentify: jest.fn() },
+    }));
+
+    jest.unstable_mockModule('../lib/events.js', () => ({
+      default: { on: jest.fn(), emit: jest.fn() },
+    }));
+
+    const mod = await import('../billing.init.js');
+    billingInit = mod.default;
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('ensureSeeded is called at init when meterMode=false', async () => {
+    await billingInit(mockApp);
+    expect(mockBillingPlanService.ensureSeeded).toHaveBeenCalledTimes(1);
+  });
+
+  test('ensureSeeded failure is swallowed when meterMode=false', async () => {
+    mockBillingPlanService.ensureSeeded.mockRejectedValue(new Error('DB error'));
+
+    // Should not throw — meterMode=false means graceful degradation
+    await expect(billingInit(mockApp)).resolves.toBeUndefined();
+  });
+
+  test('ensureSeeded failure re-throws when meterMode=true (fail-fast)', async () => {
+    mockConfig.billing.meterMode = true;
+    mockBillingPlanService.ensureSeeded.mockRejectedValue(new Error('seed failure'));
+
+    await expect(billingInit(mockApp)).rejects.toThrow('seed failure');
+  });
+
+  test('ensureSeeded success with seeded>0 logs info and resolves', async () => {
+    mockBillingPlanService.ensureSeeded.mockResolvedValue({ seeded: 2, skipped: 1 });
+    const infoSpy = jest.spyOn(console, 'info').mockImplementation(() => {});
+
+    await billingInit(mockApp);
+
+    expect(infoSpy).toHaveBeenCalledWith(
+      expect.stringContaining('seeded 2 plan(s)'),
+    );
+  });
+});