feat(billing): refund packId + attachUsageHeader + admin endpoints (PR-N7) (#3556)

* feat(billing): refund packId + attachUsageHeader + admin endpoints (PR-N7)

P1.4 + P1.5 + P1.6 — round out the billing surface required for safe meter mode.

- P1.4: refund correlation now uses packId from charge.metadata when present
        (no more ambiguous_pack_match silently failing). Legacy fallback to
        meterUnits heuristic preserved for topups created before the change.
        createExtrasCheckout already stamped packId in both session.metadata
        and payment_intent_data.metadata, so no session-side change needed.
- P1.5: new billing.attachUsageHeader config flag (default false). When true
        and meterMode also true, billing routes mount attachUsageContext
        middleware → emits X-Meter-Remaining header.
- P1.6: new admin endpoints, gated by existing CASL platform-admin grant:
        - POST /api/admin/billing/refund      → BillingRefundService.refundCharge
        - POST /api/admin/billing/plans/bump  → BillingPlanService.bumpVersion
        Zod-validated bodies (invalid → 422 per existing model.isValid).

* fix(billing): address review — guard order, reason enum, amountCents optional, bumpVersionWithRetry

- billing.routes.js: move attachUsageContext after policy.isAllowed to avoid
  unnecessary DB reads on unauthorized requests
- billing.subscription.schema.js: constrain AdminRefundRequest.reason to Stripe
  enum ['duplicate','fraudulent','requested_by_customer']; make amountCents
  optional to support full refunds; require meterQuota in AdminBumpPlanRequest
  (mirrors Mongoose schema required:true + BillingPlanBump Zod schema)
- billing.admin.controller.js: use bumpVersionWithRetry (retry on E11000 race);
  return 502 Bad Gateway for unexpected errors instead of 422
- billing.extra.service.js: update refundPartial @returns JSDoc to include
  optional reason field in early-exit paths
- tests: mock bumpVersionWithRetry, add tests for reason enum validation,
  full refund without amountCents, and bump without meterQuota (422)

* test(billing): add error-path coverage for admin controller (502 + 422)

Cover the upstream error (502 Bad Gateway) and invalid-argument error (422)
branches in both adminRefundCharge and adminBumpPlanVersion to restore
codecov/project coverage to pre-PR baseline.

Author: PierreBrisorgueil

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

@@ -40,6 +40,12 @@ const config = {
      * Used by middleware error responses (METER_EXHAUSTED, QUOTA_EXCEEDED).
      */
     upgradeUrl: '/billing/plans',
+    /**
+     * When true, mounts attachUsageContext on protected /api/billing/* routes.
+     * Emits X-Meter-Remaining on billing responses. Off by default to avoid
+     * extra DB reads on routes that do not need the header.
+     */
+    attachUsageHeader: false,
     /**
      * Plan definitions — DOWNSTREAM-OVERRIDE-REQUIRED for meter mode.
      * Used by BillingPlanService.ensureSeeded() at boot to upsert BillingPlan docs.

modules/billing/controllers/billing.admin.controller.js

@@ -0,0 +1,47 @@
+/**
+ * Module dependencies
+ */
+import responses from '../../../lib/helpers/responses.js';
+import BillingRefundService from '../services/billing.refund.service.js';
+import BillingPlanService from '../services/billing.plan.service.js';
+
+/**
+ * @desc Admin endpoint to trigger a Stripe refund for a charge
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @returns {Promise<void>}
+ */
+const adminRefundCharge = async (req, res) => {
+  try {
+    const { chargeId, amountCents, reason } = req.body;
+    const refund = await BillingRefundService.refundCharge(chargeId, amountCents, { reason });
+    responses.success(res, 'billing refund created')(refund);
+  } catch (err) {
+    const status = err.message?.startsWith('invalid argument') ? 422 : 502;
+    const title = status === 422 ? 'Unprocessable Entity' : 'Bad Gateway';
+    responses.error(res, status, title, 'Failed to refund charge')(err);
+  }
+};
+
+/**
+ * @desc Admin endpoint to create a new plan version
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @returns {Promise<void>}
+ */
+const adminBumpPlanVersion = async (req, res) => {
+  try {
+    const { planId, meterQuota, ratios } = req.body;
+    const nextPlan = await BillingPlanService.bumpVersionWithRetry(planId, { meterQuota, ratios });
+    responses.success(res, 'billing plan version bumped')(nextPlan);
+  } catch (err) {
+    const status = err.message?.startsWith('invalid argument') ? 422 : 502;
+    const title = status === 422 ? 'Unprocessable Entity' : 'Bad Gateway';
+    responses.error(res, status, title, 'Failed to bump billing plan version')(err);
+  }
+};
+
+export default {
+  adminRefundCharge,
+  adminBumpPlanVersion,
+};

modules/billing/models/billing.subscription.schema.js

@@ -76,10 +76,34 @@ const ExtrasCheckoutRequest = z
   })
   .strict();
 
+const AdminRefundRequest = z
+  .object({
+    chargeId: z.string().trim().min(1, 'chargeId is required'),
+    amountCents: z.number().int().positive().optional(),
+    // Stripe refund reason: https://stripe.com/docs/api/refunds/create#create_refund-reason
+    reason: z.enum(['duplicate', 'fraudulent', 'requested_by_customer']).optional(),
+  })
+  .strict();
+
+const AdminBumpPlanRequest = z
+  .object({
+    planId: z.string().trim().min(1, 'planId is required'),
+    meterQuota: z.number().int().nonnegative(),
+    ratios: z.record(z.string(), z.number().nonnegative()).optional(),
+  })
+  .strict();
+
+export {
+  AdminRefundRequest,
+  AdminBumpPlanRequest,
+};
+
 export default {
   Subscription,
   SubscriptionUpdate,
   CheckoutRequest,
   PortalRequest,
   ExtrasCheckoutRequest,
+  AdminRefundRequest,
+  AdminBumpPlanRequest,
 };

modules/billing/policies/billing.policy.js

@@ -19,6 +19,8 @@ export function billingSubjectRegistration({ registerPathSubject }) {
   registerPathSubject('/api/billing/extras/checkout', 'BillingExtrasCheckout');
   registerPathSubject('/api/billing/extras/balance', 'BillingExtrasBalance');
   registerPathSubject('/api/billing/extras/ledger', 'BillingExtrasLedger');
+  registerPathSubject('/api/admin/billing/refund', 'BillingAdminRefund');
+  registerPathSubject('/api/admin/billing/plans/bump', 'BillingAdminPlanBump');
   // Webhook is mounted in billing.preroute.js before body parsing and auth middleware,
   // so it bypasses policy.isAllowed entirely. Registered here for documentation completeness.
   registerPathSubject('/api/billing/webhook', 'BillingWebhook');

modules/billing/routes/billing.admin.routes.js

@@ -0,0 +1,29 @@
+/**
+ * Module dependencies
+ */
+import passport from 'passport';
+
+import policy from '../../../lib/middlewares/policy.js';
+import model from '../../../lib/middlewares/model.js';
+import billingAdmin from '../controllers/billing.admin.controller.js';
+import {
+  AdminRefundRequest,
+  AdminBumpPlanRequest,
+} from '../models/billing.subscription.schema.js';
+
+/**
+ * Routes
+ * @param {Object} app - Express application instance
+ * @returns {void}
+ */
+export default (app) => {
+  app
+    .route('/api/admin/billing/refund')
+    .all(passport.authenticate('jwt', { session: false }), policy.isAllowed)
+    .post(model.isValid(AdminRefundRequest), billingAdmin.adminRefundCharge);
+
+  app
+    .route('/api/admin/billing/plans/bump')
+    .all(passport.authenticate('jwt', { session: false }), policy.isAllowed)
+    .post(model.isValid(AdminBumpPlanRequest), billingAdmin.adminBumpPlanVersion);
+};

modules/billing/routes/billing.routes.js

@@ -1,6 +1,7 @@
 /**
  * Module dependencies
  */
+import config from '../../../config/index.js';
 import passport from 'passport';
 
 import model from '../../../lib/middlewares/model.js';
@@ -9,55 +10,65 @@ import organization from '../../organizations/middlewares/organizations.middlewa
 import billingSchema from '../models/billing.subscription.schema.js';
 import billingPlans from '../controllers/billing.plans.controller.js';
 import billing from '../controllers/billing.controller.js';
+import attachUsageContext from '../middlewares/billing.attachUsageContext.js';
 
 /**
  * @desc Register billing routes
  * @param {Object} app - Express application instance
  * @returns {void}
  */
 export default (app) => {
+  const billingGuards = [
+    passport.authenticate('jwt', { session: false }),
+    organization.resolveOrganization,
+    policy.isAllowed,
+    ...(config.billing?.meterMode === true && config.billing?.attachUsageHeader === true
+      ? [attachUsageContext]
+      : []),
+  ];
+
   // plans (public)
   app.route('/api/billing/plans').get(billingPlans.getPlans);
 
   // checkout
   app
     .route('/api/billing/checkout')
-    .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
+    .all(...billingGuards)
     .post(model.isValid(billingSchema.CheckoutRequest), billing.checkout);
 
   // portal
   app
     .route('/api/billing/portal')
-    .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
+    .all(...billingGuards)
     .post(model.isValid(billingSchema.PortalRequest), billing.portal);
 
   // subscription
   app
     .route('/api/billing/subscription')
-    .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
+    .all(...billingGuards)
     .get(billing.getSubscription);
 
   // usage
   app
     .route('/api/billing/usage')
-    .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
+    .all(...billingGuards)
     .get(billing.getUsage);
 
   // extras checkout (one-time pack purchase)
   app
     .route('/api/billing/extras/checkout')
-    .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
+    .all(...billingGuards)
     .post(model.isValid(billingSchema.ExtrasCheckoutRequest), billing.extrasCheckout);
 
   // extras balance
   app
     .route('/api/billing/extras/balance')
-    .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
+    .all(...billingGuards)
     .get(billing.extrasBalance);
 
   // extras ledger (paginated: ?page=1&limit=20)
   app
     .route('/api/billing/extras/ledger')
-    .all(passport.authenticate('jwt', { session: false }), organization.resolveOrganization, policy.isAllowed)
+    .all(...billingGuards)
     .get(billing.extrasLedger);
 };

modules/billing/services/billing.extra.service.js

@@ -71,10 +71,17 @@ const expireOldEntries = (orgId) =>
  * @param {string} orgId - The organization ObjectId (string).
  * @param {string} stripeSessionId - Stripe session ID of the original purchase (to find the pack).
  * @param {number} amountRefundedCents - Amount refunded in cents (integer).
- * @returns {Promise<{doc: Object, applied: boolean, refundUnits: number}>}
+ * @param {string|undefined} [packId] - Optional pack identifier from Stripe metadata for exact correlation.
+ * @returns {Promise<{doc: Object|null, applied: boolean, refundUnits: number, reason?: string}>}
+ *          `reason` is present only when `applied === false`: 'meter_mode_disabled' | 'invalid_org' |
+ *          'pack_not_found' | 'ambiguous_pack_match'.
  */
 // biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js service, not Qwik
-const refundPartial = async (orgId, stripeSessionId, amountRefundedCents) => {
+const refundPartial = async (orgId, stripeSessionId, amountRefundedCents, packId) => {
+  if (!config?.billing?.meterMode) {
+    return { doc: null, applied: false, reason: 'meter_mode_disabled', refundUnits: 0 };
+  }
+
   // Find the topup ledger entry for this session to identify the pack
   const doc = await BillingExtraBalanceRepository.getOrCreate(orgId);
   if (!doc) return { doc: null, applied: false, reason: 'invalid_org', refundUnits: 0 };
@@ -87,23 +94,27 @@ const refundPartial = async (orgId, stripeSessionId, amountRefundedCents) => {
     return { doc, applied: false, refundUnits: 0 };
   }
 
-  // Find the pack config to compute proportion using the topup entry's meterUnits.
-  // Ambiguity guard: if 0 or >1 packs share the same meterUnits, fall back to
-  // applied=false rather than using a wrong priceUsd.
-  // NOTE: packId is not passed to refundPartial — charge.refunded carries it in
-  // charge.metadata but the webhook call-site only passes (orgId, stripeSessionId, amountCents).
-  // This heuristic is therefore intentionally retained; the ambiguity guard is the safety net.
   const packs = config?.billing?.packs ?? [];
-  const matchingPacks = packs.filter(
-    (p) => (p.meterUnits ?? p.computeUnits) === topupEntry.amount,
-  );
+  let matchingPack;
+
+  if (packId) {
+    matchingPack = packs.find((p) => p.packId === packId);
+    if (!matchingPack) {
+      return { doc, applied: false, reason: 'pack_not_found', refundUnits: 0 };
+    }
+  } else {
+    const matchingPacks = packs.filter(
+      (p) => (p.meterUnits ?? p.computeUnits) === topupEntry.amount,
+    );
+
+    if (matchingPacks.length !== 1) {
+      // Ambiguous or unknown pack — cannot compute proportional refund safely.
+      return { doc, applied: false, reason: 'ambiguous_pack_match', refundUnits: 0 };
+    }
 
-  if (matchingPacks.length !== 1) {
-    // Ambiguous or unknown pack — cannot compute proportional refund safely.
-    return { doc, applied: false, reason: 'ambiguous_pack_match', refundUnits: 0 };
+    matchingPack = matchingPacks[0];
   }
 
-  const matchingPack = matchingPacks[0];
   let refundUnits;
   if (matchingPack.priceUsd && matchingPack.priceUsd > 0) {
     const packUnits = matchingPack.meterUnits ?? matchingPack.computeUnits;

modules/billing/services/billing.refund.service.js

@@ -13,10 +13,12 @@ import getStripe from '../lib/stripe.js';
  *
  * @param {string} stripeChargeId - Stripe charge ID (ch_xxx). Must be non-empty.
  * @param {number|undefined} [amountCents] - Amount to refund in cents. Omit for full refund. Must be > 0 if provided.
+ * @param {Object} [options={}] - Optional Stripe refund options.
+ * @param {string} [options.reason] - Optional Stripe refund reason.
  * @returns {Promise<Object>} The Stripe refund object.
  */
 // biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js service, not Qwik
-const refundCharge = async (stripeChargeId, amountCents) => {
+const refundCharge = async (stripeChargeId, amountCents, { reason } = {}) => {
   if (typeof stripeChargeId !== 'string' || stripeChargeId.trim() === '') {
     throw new Error('invalid argument: stripeChargeId must be a non-empty string');
   }
@@ -33,7 +35,7 @@ const refundCharge = async (stripeChargeId, amountCents) => {
 
   const params = {
     charge: stripeChargeId,
-    reason: 'requested_by_customer',
+    reason: reason || 'requested_by_customer',
   };
   if (amountCents !== undefined) {
     params.amount = amountCents;

modules/billing/services/billing.webhook.service.js

@@ -339,12 +339,12 @@ const handleInvoicePaymentSucceeded = async (invoice) => {
 
 /**
  * @description Handle charge.refunded event — debit ledger proportionally.
- *       Reads charge.metadata.{organizationId, stripeSessionId} which must be propagated
+ *       Reads charge.metadata.{organizationId, stripeSessionId, packId} which must be propagated
  *       via the upstream session creation pattern:
  *         stripe.checkout.sessions.create({
  *           ...,
- *           metadata: { organizationId, stripeSessionId, ... },
- *           payment_intent_data: { metadata: { organizationId, stripeSessionId, ... } },
+ *           metadata: { organizationId, stripeSessionId, packId, ... },
+ *           payment_intent_data: { metadata: { organizationId, stripeSessionId, packId, ... } },
  *         })
  *       Without payment_intent_data.metadata, charge.metadata will be empty and refunds
  *       silently skip. Downstream (trawl_node) is responsible for setting these at session creation.
@@ -363,7 +363,7 @@ const handleChargeRefunded = async (charge) => {
   // The session ID and organizationId must have been stamped on charge metadata
   // via payment_intent_data.metadata at session creation (not automatic — caller must set both
   // session.metadata and payment_intent_data.metadata explicitly).
-  const { organizationId, stripeSessionId } = metadata ?? {};
+  const { organizationId, stripeSessionId, packId } = metadata ?? {};
 
   if (!organizationId || !mongoose.Types.ObjectId.isValid(organizationId)) return;
   if (!stripeSessionId) return;
@@ -374,7 +374,7 @@ const handleChargeRefunded = async (charge) => {
   if (!thisRefundAmount || thisRefundAmount <= 0) return;
 
   // Service layer computes proportional refundUnits from config.billing.packs.
-  await BillingExtraService.refundPartial(organizationId, stripeSessionId, thisRefundAmount);
+  await BillingExtraService.refundPartial(organizationId, stripeSessionId, thisRefundAmount, packId);
 };
 
 export default {