fix(billing): log + surface root cause when checkout 502s (#3660)

* fix(billing): log + surface root cause when checkout 502s

Add logger.error in the checkout and extrasCheckout controller catch
blocks (502 path only) and wrap stripe.customers.create /
stripe.checkout.sessions.create / stripe.checkout.sessions.create
(extras) with explicit try/catch + logger.error so the underlying
Stripe error message appears in pod logs before being re-thrown.

Without this, production 502s from the billing checkout flow had no
stack trace in pod logs — root cause was invisible.

Regression tests: billing.checkout.unit.tests.js — three new tests
covering stripe.customers.create reject, stripe.checkout.sessions.create
reject (subscription), and stripe.checkout.sessions.create reject
(extras pack), each asserting logger.error is called with the correct
marker + re-thrown. Also adds logger mock to billing.extras.controller
and billing.checkout test suites to prevent config-read crash on minimal
config objects.

* fix(billing): serialize error as message+stack in 502 log payloads

Winston format.json() does not serialize Error non-enumerable properties,
so logging `error: err` produces `{}` in JSON mode. Switch to
`error: err?.message ?? String(err), stack: err?.stack` to match the
existing convention in billing.webhook.service.js. Update regression test
assertions to verify the extracted message string.

* test(billing): mock logger in routes integration test to avoid fileLogger init crash

* test(billing): cover main checkout controller 502 path + invalid priceId

Author: PierreBrisorgueil

modules/billing/controllers/billing.controller.js

@@ -4,6 +4,7 @@
 import { activeStatuses } from '../lib/constants.js';
 import config from '../../../config/index.js';
 import responses from '../../../lib/helpers/responses.js';
+import logger from '../../../lib/services/logger.js';
 import BillingService from '../services/billing.service.js';
 import BillingUsageService from '../services/billing.usage.service.js';
 import BillingExtraService from '../services/billing.extra.service.js';
@@ -24,6 +25,15 @@ const checkout = async (req, res) => {
       return res.status(409).json({ type: 'error', message: err.message, code: 'subscription_already_active', portalUrl: err.portalUrl });
     }
     const status = err.message?.startsWith('Invalid') || err.message?.includes('not found') ? 422 : 502;
+    if (status === 502) {
+      logger.error('[billing.checkout] createCheckout failed', {
+        error: err?.message ?? String(err),
+        stack: err?.stack,
+        organizationId: req.organization?._id,
+        priceId: req.body?.priceId,
+        source: 'web',
+      });
+    }
     const title = status === 422 ? 'Unprocessable Entity' : 'Bad Gateway';
     responses.error(res, status, title, 'Failed to create checkout session')(err);
   }
@@ -138,6 +148,15 @@ const extrasCheckout = async (req, res) => {
     responses.success(res, 'extras checkout session created')(result);
   } catch (err) {
     const status = err.message?.startsWith('Invalid') || err.message?.includes('not found') ? 422 : 502;
+    if (status === 502) {
+      logger.error('[billing.checkout] createExtrasCheckout failed', {
+        error: err?.message ?? String(err),
+        stack: err?.stack,
+        organizationId: req.organization?._id,
+        packId: req.body?.packId,
+        source: 'web',
+      });
+    }
     const title = status === 422 ? 'Unprocessable Entity' : 'Bad Gateway';
     responses.error(res, status, title, 'Failed to create extras checkout session')(err);
   }

modules/billing/services/billing.service.js

@@ -2,6 +2,7 @@
  * Module dependencies
  */
 import config from '../../../config/index.js';
+import logger from '../../../lib/services/logger.js';
 import getStripe from '../lib/stripe.js';
 import BillingPlansService from './billing.plans.service.js';
 import SubscriptionRepository from '../repositories/billing.subscription.repository.js';
@@ -46,13 +47,23 @@ const _ensureStripeCustomer = async (stripe, organization) => {
   let subscription = await SubscriptionRepository.findByOrganization(organization._id);
   if (subscription?.stripeCustomerId) return subscription;
 
-  const customer = await stripe.customers.create(
-    {
-      name: organization.name,
-      metadata: { organizationId: String(organization._id) },
-    },
-    { idempotencyKey: `cus_create_${String(organization._id)}` },
-  );
+  let customer;
+  try {
+    customer = await stripe.customers.create(
+      {
+        name: organization.name,
+        metadata: { organizationId: String(organization._id) },
+      },
+      { idempotencyKey: `cus_create_${String(organization._id)}` },
+    );
+  } catch (err) {
+    logger.error('[billing.service] stripe.customers.create failed', {
+      error: err?.message ?? String(err),
+      stack: err?.stack,
+      organizationId: String(organization._id),
+    });
+    throw err;
+  }
 
   if (subscription) {
     subscription = await SubscriptionRepository.update({
@@ -190,7 +201,19 @@ const createCheckout = async (organization, priceId, successUrl, cancelUrl) => {
   // the day yields the same expired session URL, silently killing conversion.
   // Same-tab double-clicks are prevented in this function by the active-
   // subscription guard above (both the DB check and the live Stripe lookup).
-  const session = await stripe.checkout.sessions.create(checkoutParams);
+  let session;
+  try {
+    session = await stripe.checkout.sessions.create(checkoutParams);
+  } catch (err) {
+    logger.error('[billing.service] stripe.checkout.sessions.create failed', {
+      error: err?.message ?? String(err),
+      stack: err?.stack,
+      organizationId: String(organization._id),
+      priceId,
+      plan: matchedPlan.planId,
+    });
+    throw err;
+  }
 
   return session.url;
 };
@@ -270,10 +293,21 @@ const createExtrasCheckout = async (organization, packId, successUrl, cancelUrl,
     extrasCheckoutParams.automatic_tax = { enabled: true };
     extrasCheckoutParams.customer_update = { address: 'auto', name: 'auto' };
   }
-  const session = await stripe.checkout.sessions.create(
-    extrasCheckoutParams,
-    { idempotencyKey },
-  );
+  let session;
+  try {
+    session = await stripe.checkout.sessions.create(
+      extrasCheckoutParams,
+      { idempotencyKey },
+    );
+  } catch (err) {
+    logger.error('[billing.service] stripe.checkout.sessions.create (extras) failed', {
+      error: err?.message ?? String(err),
+      stack: err?.stack,
+      organizationId: orgId,
+      packId,
+    });
+    throw err;
+  }
 
   return { url: session.url };
 };

modules/billing/tests/billing.checkout.unit.tests.js

@@ -63,6 +63,12 @@ describe('Billing service unit tests:', () => {
     jest.unstable_mockModule('../services/billing.plans.service.js', () => ({
       default: mockPlansService,
     }));
+
+    // Mock logger to prevent logger.js from reading config at import time.
+    // Tests in the "error logging" describe override this with a tracked mock.
+    jest.unstable_mockModule('../../../lib/services/logger.js', () => ({
+      default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() },
+    }));
   });
 
   afterEach(() => {
@@ -829,4 +835,113 @@ describe('Billing service unit tests:', () => {
       expect(result.nextRenewalDate).toEqual(new Date(cancelAt * 1000));
     });
   });
+
+  // ── Error logging regression (fix-checkout-502) ──────────────────────────
+  // Ensures that stripe.customers.create and stripe.checkout.sessions.create
+  // errors are logged via logger.error before being re-thrown.
+  // Without this, production 502s have no stack trace in pod logs.
+
+  describe('error logging on Stripe failure', () => {
+    let mockLogger;
+
+    beforeEach(() => {
+      // Re-register logger mock with tracked jest.fn() instances so we can assert on calls.
+      // The parent beforeEach already registers a silent mock; this overrides it with tracked ones.
+      mockLogger = { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() };
+      jest.unstable_mockModule('../../../lib/services/logger.js', () => ({
+        default: mockLogger,
+      }));
+    });
+
+    test('logs error and re-throws when stripe.customers.create rejects', async () => {
+      const stripeError = new Error('Stripe Test: customer creation blocked');
+      jest.unstable_mockModule('../../../config/index.js', () => ({
+        default: { stripe: { secretKey: 'sk_test_log_cus' } },
+      }));
+
+      mockSubscriptionRepository.findByOrganization
+        .mockResolvedValueOnce(null)   // block guard: no active sub
+        .mockResolvedValueOnce(null);  // _ensureStripeCustomer: no existing sub → create
+      mockStripeInstance.customers.create.mockRejectedValue(stripeError);
+
+      const mod = await import('../services/billing.service.js');
+      BillingService = mod.default;
+
+      await expect(
+        BillingService.createCheckout(mockOrganization, 'price_starter_m', 'http://ok', 'http://cancel'),
+      ).rejects.toThrow('Stripe Test: customer creation blocked');
+
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        '[billing.service] stripe.customers.create failed',
+        expect.objectContaining({
+          organizationId: orgId,
+          error: 'Stripe Test: customer creation blocked',
+        }),
+      );
+    });
+
+    test('logs error and re-throws when stripe.checkout.sessions.create rejects', async () => {
+      const stripeError = new Error('Stripe Test: session creation blocked');
+      jest.unstable_mockModule('../../../config/index.js', () => ({
+        default: { stripe: { secretKey: 'sk_test_log_sess' } },
+      }));
+
+      mockSubscriptionRepository.findByOrganization.mockResolvedValue({
+        stripeCustomerId: 'cus_existing',
+      });
+      mockStripeInstance.checkout.sessions.create.mockRejectedValue(stripeError);
+
+      const mod = await import('../services/billing.service.js');
+      BillingService = mod.default;
+
+      await expect(
+        BillingService.createCheckout(mockOrganization, 'price_starter_m', 'http://ok', 'http://cancel'),
+      ).rejects.toThrow('Stripe Test: session creation blocked');
+
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        '[billing.service] stripe.checkout.sessions.create failed',
+        expect.objectContaining({
+          organizationId: orgId,
+          priceId: 'price_starter_m',
+          error: 'Stripe Test: session creation blocked',
+        }),
+      );
+    });
+
+    test('logs error and re-throws when extras stripe.checkout.sessions.create rejects', async () => {
+      const stripeError = new Error('Stripe Test: extras session blocked');
+      jest.unstable_mockModule('../../../config/index.js', () => ({
+        default: {
+          stripe: {
+            secretKey: 'sk_test_log_extras',
+            prices: { packs: { pack_500k: 'price_pack500' } },
+          },
+          billing: {
+            packs: [{ packId: 'pack_500k', meterUnits: 500000 }],
+          },
+        },
+      }));
+
+      mockSubscriptionRepository.findByOrganization.mockResolvedValue({
+        stripeCustomerId: 'cus_existing',
+      });
+      mockStripeInstance.checkout.sessions.create.mockRejectedValue(stripeError);
+
+      const mod = await import('../services/billing.service.js');
+      BillingService = mod.default;
+
+      await expect(
+        BillingService.createExtrasCheckout(mockOrganization, 'pack_500k', 'http://ok', 'http://cancel'),
+      ).rejects.toThrow('Stripe Test: extras session blocked');
+
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        '[billing.service] stripe.checkout.sessions.create (extras) failed',
+        expect.objectContaining({
+          organizationId: orgId,
+          packId: 'pack_500k',
+          error: 'Stripe Test: extras session blocked',
+        }),
+      );
+    });
+  });
 });

modules/billing/tests/billing.extras.controller.unit.tests.js

@@ -31,6 +31,7 @@ describe('Billing extras controller unit tests:', () => {
     jest.resetModules();
 
     mockBillingService = {
+      createCheckout: jest.fn(),
       createExtrasCheckout: jest.fn(),
       getLocalSubscription: jest.fn(),
       getSubscription: jest.fn(),
@@ -77,6 +78,12 @@ describe('Billing extras controller unit tests:', () => {
       activeStatuses: ['active', 'trialing'],
     }));
 
+    // Mock logger: billing.controller.js imports logger, which reads config at module init.
+    // Without this mock, tests that supply a minimal config object cause logger.js to throw.
+    jest.unstable_mockModule('../../../lib/services/logger.js', () => ({
+      default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() },
+    }));
+
     const mod = await import('../controllers/billing.controller.js');
     BillingController = mod.default;
 
@@ -141,6 +148,28 @@ describe('Billing extras controller unit tests:', () => {
     });
   });
 
+  // ── checkout (main subscription) ───────────────────────────────────────────
+
+  describe('checkout', () => {
+    test('should return 502 and log the error when Stripe call fails with generic error', async () => {
+      req.body = { priceId: 'price_growth_m', successUrl: 'http://ok', cancelUrl: 'http://cancel' };
+      mockBillingService.createCheckout.mockRejectedValue(new Error('Network error'));
+
+      await BillingController.checkout(req, res);
+
+      expect(res.status).toHaveBeenCalledWith(502);
+    });
+
+    test('should return 422 when priceId is invalid (no logger.error on 422 path)', async () => {
+      req.body = { priceId: 'price_unknown', successUrl: 'http://ok', cancelUrl: 'http://cancel' };
+      mockBillingService.createCheckout.mockRejectedValue(new Error('Invalid priceId: price not found'));
+
+      await BillingController.checkout(req, res);
+
+      expect(res.status).toHaveBeenCalledWith(422);
+    });
+  });
+
   // ── extrasBalance ──────────────────────────────────────────────────────────
 
   describe('extrasBalance', () => {

modules/billing/tests/billing.routes.integration.tests.js

@@ -71,6 +71,15 @@ describe('Billing extras routes integration tests:', () => {
       activeStatuses: ['active', 'trialing'],
     }));
 
+    jest.unstable_mockModule('../../../lib/services/logger.js', () => ({
+      default: {
+        error: jest.fn(),
+        warn: jest.fn(),
+        info: jest.fn(),
+        debug: jest.fn(),
+      },
+    }));
+
     const mod = await import('../controllers/billing.controller.js');
     BillingController = mod.default;