fix(billing): mega hardening v3 — atomicity + DRY + config (#3583)

* fix(billing): mega hardening v3 — atomicity + DRY + config knobs

Bundles 3 logical groupings on overlapping surfaces to avoid rebase hell:

ATOMICITY (🔴 + 4× 🟠 + 2× 🟡 + 🔵 + ⚪)
- markFailedAttempt: single atomic op via aggregation pipeline (close TOCTOU
  on concurrent crons that double-emit billing.extras_debit.exhausted)
- incrementMeterWithOutbox: try/catch outbox create, E11000 fetch existing
- zero-cost attribute(): writes idempotency key (close double-charge replay)
- forceRotateForPlanChange: planChangeResetTriggered set BEFORE try (close
  double-rotate via fallback resetWeek)
- E11000 retry: legacy consumedHistoryIds filter symmetric (close mid-migration
  double-charge)
- unitsFromCosts: hard-fail null ratioVersion + non-null costs in meterMode
- BillingMeterOutbox: timestamps:true (drop manual createdAt)
- billing.policy.js: drop stale ESLint disable

DRY + lib EXTRACTION (3× 🟠 + 5× 🟡 + 3× 🔵)
- webhook.controller: responses.error() canonical envelope (3 sites)
- billing.controller: route via BillingExtraService.getOrgBalanceContext()
- _ensureStripeCustomer private: dedup find-or-create between checkout flows
- billing.processedStripeEvent.schema.js: NEW Zod schema parity
- lib/billing.isoWeek.js: NEW currentWeekKey + isoWeekKey single source
- findAllDueForReset deprecated: removed
- lib/billing.cron-utils.js: NEW applyJitter helper, applied to all 3 crons
- billing.plans.controller: unit tests added
- lib/billing.errors.js: NEW isDuplicateKeyError single source
- lib/billing.constants.js: NEW shared types/constants — kills dynamic imports

CONFIG KNOBS SURFACING (NEW)
- config.billing.{meter,outbox,crons,planChange,alerts,events}.* knobs
- All magic numbers (METER_RUN_BASE, retry limits, jitter window, threshold
  percentages, fallback plan id, event names) now config-driven with safe
  defaults. README documents each with downstream override examples.

* fix(billing): warn on unsupported threshold percentages + test coverage

* fix(billing): named constant for ms-per-day + readme example uses supported threshold values

Author: PierreBrisorgueil

modules/billing/README.md

@@ -99,10 +99,73 @@ Consumers wanting clean-break behavior on downgrade should pass `{ preserveUsage
 
 ## Extras debit reliability
 
-`attribute()` returns optimistically after usage increment + outbox row insert. Extras debit happens out of band; if it fails, cron `retry-pending-extras-debit` reconciles within 5min. After 5 failed attempts, the outbox row is marked `failed` and event `billing.extras_debit.exhausted` is emitted for alerting.
+`attribute()` returns optimistically after usage increment + outbox row insert. Extras debit happens out of band; if it fails, cron `retry-pending-extras-debit` reconciles on the configured retry interval. After the configured failed-attempt limit, the outbox row is marked `failed` and the configured exhausted event is emitted for alerting.
 
 Consumers should NOT retry on `applied: true` — the outbox handles eventual consistency.
 
+## Meter hardening configuration
+
+Defaults live in `modules/billing/config/billing.development.config.js` and can be overridden by downstream project config:
+
+```js
+billing: {
+  meter: {
+    runBase: 1,
+    maxUnitsPerOperation: 10000,
+    fallbackPlanId: null,
+  },
+  outbox: {
+    maxRetryAttempts: 5,
+    retryIntervalSec: 300,
+  },
+  crons: {
+    jitterMaxMs: 60_000,
+  },
+  planChange: {
+    preserveUsageDefault: true,
+  },
+  alerts: {
+    thresholdPercents: [80, 100],  // only 80 and 100 are supported schema fields; other values warn and are skipped
+  },
+  events: {
+    extrasExhausted: 'billing.extras_debit.exhausted',
+  },
+}
+```
+
+Example override:
+
+```js
+// config/defaults/production.config.js
+export default {
+  billing: {
+    meter: {
+      runBase: 2,
+      maxUnitsPerOperation: 25000,
+      fallbackPlanId: 'starter',
+    },
+    outbox: {
+      maxRetryAttempts: 8,
+      retryIntervalSec: 120,
+    },
+    crons: {
+      jitterMaxMs: 30_000,
+    },
+    planChange: {
+      preserveUsageDefault: false,
+    },
+    alerts: {
+      thresholdPercents: [80, 100],
+    },
+    events: {
+      extrasExhausted: 'billing.extras_debit.exhausted',
+    },
+  },
+};
+```
+
+`meter.runBaseUnits` is still accepted as a backward-compatible alias for `meter.runBase`.
+
 ## Stripe — `automatic_tax` flag
 
 ```js

modules/billing/billing.init.js

@@ -6,6 +6,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';
+import BillingUsageRepository from './repositories/billing.usage.repository.js';
 
 /**
  * Billing module initialisation.
@@ -29,7 +30,9 @@ export default async (app) => {
   billingEvents.on('plan.changed', ({ organizationId, newPlan }) => {
     try {
       AnalyticsService.groupIdentify('company', String(organizationId), { plan: newPlan });
-    } catch (_) { /* analytics must not break billing flow */ }
+    } catch (err) {
+      console.warn('[billing] analytics groupIdentify failed (non-fatal):', err?.message ?? err);
+    }
   });
 
   try {
@@ -49,6 +52,13 @@ export default async (app) => {
   // Runs after ensureSeeded so the plan catalog is up to date.
   // Never crashes boot — wrapped in try/catch.
   if (config?.billing?.meterMode) {
+    const legacyUsageCount = await BillingUsageRepository.countLegacyConsumedHistoryIds();
+    if (legacyUsageCount > 0) {
+      throw new Error(
+        `[billing] legacy consumedHistoryIds field still present on ${legacyUsageCount} usage document(s); run migration 20260502100000-rename-consumed-history-ids-to-attribution-keys before enabling meterMode`,
+      );
+    }
+
     try {
       const Subscription = mongoose.model('Subscription');
       const knownPlans = new Set(config.billing.plans ?? []);
@@ -58,8 +68,8 @@ export default async (app) => {
           console.warn(`[billing] Subscription.plan value "${plan}" not in planDefinitions — orphaned plan, may resolve quota=0`);
         }
       }
-    } catch (_err) {
-      // Validator failure must NOT crash boot (e.g. model not yet registered at early init)
+    } catch (err) {
+      console.warn('[billing] Subscription.plan boot validator failed (non-fatal):', err?.message ?? err);
     }
   }
 };

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

@@ -64,11 +64,14 @@ const config = {
      * Meter unit parameters — downstream projects must override with their
      * actual unit economics before enabling meterMode in production.
      *
-     * runBaseUnits: flat units charged per run (before per-feature ratios).
+     * runBase: flat units charged per run when no cost data is available.
+     * runBaseUnits: deprecated alias kept for downstream backward compatibility.
      * maxUnitsPerOperation: safety cap per single operation run.
      */
     meter: {
+      runBase: 1,
       runBaseUnits: 1,
+      fallbackPlanId: null,
       /**
        * Canonical version string emitted by billing.meter.service attribute() when writing
        * history.planVersion. Downstream projects MUST override this value and keep it
@@ -98,6 +101,22 @@ const config = {
       dollarsToUnitRatio: 1000,
       maxUnitsPerOperation: 10000,
     },
+    outbox: {
+      maxRetryAttempts: 5,
+      retryIntervalSec: 300,
+    },
+    crons: {
+      jitterMaxMs: 60_000,
+    },
+    planChange: {
+      preserveUsageDefault: true,
+    },
+    alerts: {
+      thresholdPercents: [80, 100],
+    },
+    events: {
+      extrasExhausted: 'billing.extras_debit.exhausted',
+    },
     /**
      * Extra meter packs — downstream projects override with actual packs.
      * Example: [{ packId: 'pack_500k', meterUnits: 500000, stripePriceId: 'price_xxx' }]

modules/billing/controllers/billing.controller.js

@@ -7,10 +7,6 @@ import responses from '../../../lib/helpers/responses.js';
 import BillingService from '../services/billing.service.js';
 import BillingUsageService from '../services/billing.usage.service.js';
 import BillingExtraService from '../services/billing.extra.service.js';
-import BillingExtraBalanceRepository from '../repositories/billing.extraBalance.repository.js';
-
-// NOTE: BillingExtraBalance uses field name 'organization', BillingUsage uses 'organizationId' — both are Schema.ObjectId refs to Organization.
-// Only the field name differs (historical reasons) — keep queries consistent with each model's own convention.
 
 /**
  * @desc Endpoint to create a Stripe Checkout session
@@ -81,7 +77,7 @@ const getUsage = async (req, res) => {
     if (config.billing?.meterMode) {
       // Meter mode — return compute fields
       const meter = await BillingUsageService.getMeter(req.organization._id.toString());
-      const extrasRemaining = await BillingExtraBalanceRepository.getBalance(req.organization._id.toString());
+      const extrasRemaining = await BillingExtraService.getOrgBalanceContext(req.organization._id.toString());
       const packsAvailable = config.billing?.packs ?? [];
 
       return responses.success(res, 'billing usage')({
@@ -153,7 +149,7 @@ const extrasCheckout = async (req, res) => {
 // biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js controller, not Qwik
 const extrasBalance = async (req, res) => {
   try {
-    const balance = await BillingExtraBalanceRepository.getBalance(req.organization._id.toString());
+    const balance = await BillingExtraService.getOrgBalanceContext(req.organization._id.toString());
     const packsAvailable = config.billing?.packs ?? [];
     responses.success(res, 'extras balance')({ balance, packsAvailable });
   } catch (err) {

modules/billing/controllers/billing.webhook.controller.js

@@ -3,6 +3,7 @@
  */
 import config from '../../../config/index.js';
 import logger from '../../../lib/services/logger.js';
+import responses from '../../../lib/helpers/responses.js';
 import getStripe from '../lib/stripe.js';
 import BillingWebhookService from '../services/billing.webhook.service.js';
 
@@ -15,7 +16,9 @@ import BillingWebhookService from '../services/billing.webhook.service.js';
 // biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js controller, not Qwik
 const handleWebhook = async (req, res) => {
   const stripe = getStripe();
-  if (!stripe) return res.status(400).json({ error: 'Stripe is not configured' });
+  if (!stripe) {
+    return responses.error(res, 400, 'Bad Request', 'Stripe is not configured')(new Error('Stripe is not configured'));
+  }
 
   const sig = req.headers['stripe-signature'];
   const { webhookSecret } = config.stripe;
@@ -24,7 +27,7 @@ const handleWebhook = async (req, res) => {
   try {
     event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);
   } catch (err) {
-    return res.status(400).json({ error: 'Webhook signature verification failed' });
+    return responses.error(res, 400, 'Bad Request', 'Webhook signature verification failed')(err);
   }
 
   try {
@@ -65,7 +68,7 @@ const handleWebhook = async (req, res) => {
     return res.status(200).json({ received: true });
   } catch (err) {
     logger.error('Stripe webhook handler error:', err);
-    return res.status(500).json({ error: 'Webhook handler failed' });
+    return responses.error(res, 500, 'Internal Server Error', 'Webhook handler failed')(err);
   }
 };
 

modules/billing/crons/README.md

@@ -59,19 +59,21 @@ Repeat the manifest for `billing.extrasExpiration.js` and `billing.dunningSweep.
 
 Devkit-shipped crons run on identical UTC schedules across all consumer deployments. To avoid thundering-herd against a shared DB or external API:
 
-### Recommended pattern — startup jitter
+### Built-in startup jitter
 
-These scripts are invoked once per CronJob execution and exit immediately after. Add a random delay at the top of your entrypoint to spread load across deployments:
+`billing.extrasExpiration.js`, `billing.dunningSweep.js`, and `retry-pending-extras-debit.cron.js` call `applyJitter(config.billing.crons.jitterMaxMs ?? 60000)` before doing work. Override the window per project:
 
 ```js
-// Wrap in an async IIFE — cron entrypoints are CommonJS, so top-level await is not available.
-// Jitter is re-randomized on each CronJob invocation — this is intentional for K8s CronJobs.
-// For a stable per-pod offset, derive from process.env.HOSTNAME instead (see note below).
-(async () => {
-  const jitterMs = Math.floor(Math.random() * 60_000); // 0–60s window
-  await new Promise(r => setTimeout(r, jitterMs));
-  await BillingResetService.resetAllDue();
-})();
+export default {
+  billing: {
+    crons: {
+      jitterMaxMs: 30_000,
+    },
+    outbox: {
+      retryIntervalSec: 120,
+    },
+  },
+};
 ```
 
 > **Stable per-pod jitter (optional):** If you want the same pod to always fire at the same offset within the window, derive jitter from the pod hostname instead of `Math.random()`. Use a distinct variable name to avoid shadowing if both snippets appear in the same file:

modules/billing/crons/billing.dunningSweep.js

@@ -17,9 +17,16 @@
 
 process.env.NODE_ENV = process.env.NODE_ENV || 'development';
 
-const [{ default: config }, { default: mongooseService }] = await Promise.all([
+const [
+  { default: config },
+  { default: mongooseService },
+  { applyJitter },
+  { getCronJitterMaxMs },
+] = await Promise.all([
   import('../../../config/index.js'),
   import('../../../lib/services/mongoose.js'),
+  import('../lib/billing.cron-utils.js'),
+  import('../lib/billing.constants.js'),
 ]);
 
 if (!config?.billing?.meterMode) {
@@ -28,6 +35,7 @@ if (!config?.billing?.meterMode) {
 }
 
 try {
+  await applyJitter(getCronJitterMaxMs());
   await mongooseService.connect();
 
   const [{ default: BillingSubscriptionRepository }, { default: OrganizationRepository }] = await Promise.all([

modules/billing/crons/billing.extrasExpiration.js

@@ -14,9 +14,16 @@
 
 process.env.NODE_ENV = process.env.NODE_ENV || 'development';
 
-const [{ default: config }, { default: mongooseService }] = await Promise.all([
+const [
+  { default: config },
+  { default: mongooseService },
+  { applyJitter },
+  { getCronJitterMaxMs },
+] = await Promise.all([
   import('../../../config/index.js'),
   import('../../../lib/services/mongoose.js'),
+  import('../lib/billing.cron-utils.js'),
+  import('../lib/billing.constants.js'),
 ]);
 
 if (!config?.billing?.meterMode) {
@@ -25,6 +32,7 @@ if (!config?.billing?.meterMode) {
 }
 
 try {
+  await applyJitter(getCronJitterMaxMs());
   await mongooseService.connect();
 
   const [{ default: BillingExtraService }, { default: BillingExtraBalanceRepository }] =

modules/billing/crons/retry-pending-extras-debit.cron.js

@@ -10,26 +10,31 @@
 
 process.env.NODE_ENV = process.env.NODE_ENV || 'development';
 
-const [{ default: config }, { default: mongooseService }] = await Promise.all([
+const [
+  { default: config },
+  { default: mongooseService },
+  { applyJitter },
+  { getCronJitterMaxMs, getOutboxRetryIntervalMs },
+] = await Promise.all([
   import('../../../config/index.js'),
   import('../../../lib/services/mongoose.js'),
+  import('../lib/billing.cron-utils.js'),
+  import('../lib/billing.constants.js'),
 ]);
 
 if (!config?.billing?.meterMode) {
   console.log('[billing.retryPendingExtrasDebit] meterMode disabled — skipping.');
   process.exit(0);
 }
 
-const { randomInt } = await import('node:crypto');
-const jitterMs = randomInt(0, 60_000);
-await new Promise((resolve) => setTimeout(resolve, jitterMs));
+await applyJitter(getCronJitterMaxMs());
 
 try {
   await mongooseService.loadModels();
   await mongooseService.connect();
 
   const { default: BillingMeterOutboxService } = await import('../services/billing.meter.outbox.service.js');
-  const result = await BillingMeterOutboxService.retryPendingExtrasDebits(5 * 60 * 1000, 100);
+  const result = await BillingMeterOutboxService.retryPendingExtrasDebits(getOutboxRetryIntervalMs(), 100);
 
   console.log(
     `[billing.retryPendingExtrasDebit] done — scanned: ${result.scanned}, committed: ${result.committed}, failedAttempts: ${result.failedAttempts}, exhausted: ${result.exhausted}`,