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

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,26 @@ 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 } },
+    },
     /**
      * 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.plan.ensureSeeded.unit.tests.js

@@ -0,0 +1,159 @@
+/**
+ * Module dependencies.
+ */
+import { jest, describe, test, beforeEach, afterEach, expect } from '@jest/globals';
+
+/**
+ * Unit tests for BillingPlanService.ensureSeeded
+ */
+describe('BillingPlanService.ensureSeeded unit tests:', () => {
+  let BillingPlanService;
+  let mockBillingPlanRepository;
+  let mockConfig;
+
+  beforeEach(async () => {
+    jest.resetModules();
+
+    mockConfig = {
+      billing: {
+        meterMode: true,
+        planDefinitions: {},
+      },
+    };
+
+    mockBillingPlanRepository = {
+      findActive: jest.fn(),
+      findByVersion: jest.fn(),
+      deactivateAll: jest.fn(),
+      count: jest.fn(),
+      create: jest.fn(),
+    };
+
+    jest.unstable_mockModule('../../../config/index.js', () => ({
+      default: mockConfig,
+    }));
+
+    jest.unstable_mockModule('../repositories/billing.plan.repository.js', () => ({
+      default: mockBillingPlanRepository,
+    }));
+
+    const mod = await import('../services/billing.plan.service.js');
+    BillingPlanService = mod.default;
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('meterMode=false returns zeroes and never touches the repository', async () => {
+    mockConfig.billing.meterMode = false;
+
+    const result = await BillingPlanService.ensureSeeded();
+
+    expect(result).toEqual({ seeded: 0, skipped: 0 });
+    expect(mockBillingPlanRepository.findActive).not.toHaveBeenCalled();
+    expect(mockBillingPlanRepository.create).not.toHaveBeenCalled();
+  });
+
+  test('meterMode=true with empty planDefinitions returns zeroes', async () => {
+    const result = await BillingPlanService.ensureSeeded();
+
+    expect(result).toEqual({ seeded: 0, skipped: 0 });
+    expect(mockBillingPlanRepository.findActive).not.toHaveBeenCalled();
+    expect(mockBillingPlanRepository.create).not.toHaveBeenCalled();
+  });
+
+  test('meterMode=true with 3 planDefinitions and none existing seeds 3 plans', async () => {
+    mockConfig.billing.planDefinitions = {
+      free: { meterQuota: 0, ratios: { default: 1 } },
+      starter: { meterQuota: 50000, ratios: { default: 1 } },
+      pro: { meterQuota: 500000, ratios: { default: 2 } },
+    };
+    mockBillingPlanRepository.findActive.mockResolvedValue(null);
+    // count=0 → version 'v1' for each plan
+    mockBillingPlanRepository.count.mockResolvedValue(0);
+    mockBillingPlanRepository.create.mockResolvedValue({});
+
+    const result = await BillingPlanService.ensureSeeded();
+
+    expect(result).toEqual({ seeded: 3, skipped: 0 });
+    expect(mockBillingPlanRepository.findActive).toHaveBeenCalledTimes(3);
+    expect(mockBillingPlanRepository.count).toHaveBeenCalledTimes(3);
+    expect(mockBillingPlanRepository.create).toHaveBeenCalledTimes(3);
+    expect(mockBillingPlanRepository.create).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ planId: 'free', version: 'v1', meterQuota: 0, ratios: { default: 1 }, active: true }),
+    );
+  });
+
+  test('meterMode=true with 3 planDefinitions and 1 existing seeds 2 and skips 1', async () => {
+    mockConfig.billing.planDefinitions = {
+      free: { meterQuota: 0, ratios: { default: 1 } },
+      starter: { meterQuota: 50000, ratios: { default: 1 } },
+      pro: { meterQuota: 500000, ratios: { default: 1 } },
+    };
+    mockBillingPlanRepository.findActive
+      .mockResolvedValueOnce({ planId: 'free', version: 'v1' })
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce(null);
+    mockBillingPlanRepository.count.mockResolvedValue(0);
+    mockBillingPlanRepository.create.mockResolvedValue({});
+
+    const result = await BillingPlanService.ensureSeeded();
+
+    expect(result).toEqual({ seeded: 2, skipped: 1 });
+    expect(mockBillingPlanRepository.create).toHaveBeenCalledTimes(2);
+    expect(mockBillingPlanRepository.create).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ planId: 'starter', version: 'v1' }),
+    );
+    expect(mockBillingPlanRepository.create).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ planId: 'pro', version: 'v1' }),
+    );
+  });
+
+  test('count > 0 yields next version string correctly', async () => {
+    mockConfig.billing.planDefinitions = {
+      pro: { meterQuota: 500000, ratios: { default: 1 } },
+    };
+    mockBillingPlanRepository.findActive.mockResolvedValue(null);
+    // Existing inactive v1 is present (total count = 1)
+    mockBillingPlanRepository.count.mockResolvedValue(1);
+    mockBillingPlanRepository.create.mockResolvedValue({});
+
+    const result = await BillingPlanService.ensureSeeded();
+
+    expect(result).toEqual({ seeded: 1, skipped: 0 });
+    expect(mockBillingPlanRepository.create).toHaveBeenCalledWith(
+      expect.objectContaining({ planId: 'pro', version: 'v2' }),
+    );
+  });
+
+  test('E11000 on create is absorbed as a skip (concurrent pod race)', async () => {
+    mockConfig.billing.planDefinitions = {
+      free: { meterQuota: 0, ratios: { default: 1 } },
+      pro: { meterQuota: 500000, ratios: { default: 1 } },
+    };
+    mockBillingPlanRepository.findActive.mockResolvedValue(null);
+    mockBillingPlanRepository.count.mockResolvedValue(0);
+    // First create throws E11000; second succeeds
+    const e11000 = Object.assign(new Error('E11000 duplicate key error'), { code: 11000 });
+    mockBillingPlanRepository.create.mockRejectedValueOnce(e11000).mockResolvedValueOnce({});
+
+    const result = await BillingPlanService.ensureSeeded();
+
+    expect(result).toEqual({ seeded: 1, skipped: 1 });
+  });
+
+  test('non-E11000 error on create propagates and aborts', async () => {
+    mockConfig.billing.planDefinitions = {
+      pro: { meterQuota: 500000, ratios: { default: 1 } },
+    };
+    mockBillingPlanRepository.findActive.mockResolvedValue(null);
+    mockBillingPlanRepository.count.mockResolvedValue(0);
+    mockBillingPlanRepository.create.mockRejectedValue(new Error('DB connection lost'));
+
+    await expect(BillingPlanService.ensureSeeded()).rejects.toThrow('DB connection lost');
+  });
+});