fix(billing): address review feedback on requireQuota middleware

- Rename billing.quota.middleware.js → billing.requireQuota.js for naming
  consistency with billing.requirePlan.js
- Add JSDoc to inner middleware function per repository coding guidelines
- Document bypass cases (null/undefined limit, Infinity) in outer JSDoc
- Use responses.error envelope for 429 quota response instead of raw JSON
- Update test assertions to match standardized response envelope

Author: PierreBrisorgueil

…/middlewares/billing.quota.middleware.js …ling/middlewares/billing.requireQuota.jsmodules/billing/middlewares/billing.quota.middleware.js renamed to modules/billing/middlewares/billing.requireQuota.js modules/billing/middlewares/billing.quota.middleware.js renamed to modules/billing/middlewares/billing.requireQuota.js

@@ -12,13 +12,25 @@ import responses from '../../../lib/helpers/responses.js';
  * Reads limits from `config.billing.quotas[plan][resource][action]` and
  * compares against the current month's usage via BillingUsageService.
  *
+ * When no quota is configured for the plan/resource/action combination
+ * (limit is `null` or `undefined`), the request is allowed through.
+ * When the limit is `Infinity`, the request is also allowed without
+ * checking usage (unlimited plan).
+ *
  * Expects `req.organization` to be set by resolveOrganization upstream.
  *
  * @param {string} resource - The quota resource name (e.g. 'scraps').
  * @param {string} action - The quota action name (e.g. 'create', 'execute').
  * @returns {Function} Express middleware function.
  */
 function requireQuota(resource, action) {
+  /**
+   * Enforce quota for a resource/action and block requests when limit is reached.
+   * @param {import('express').Request} req - Express request object.
+   * @param {import('express').Response} res - Express response object.
+   * @param {import('express').NextFunction} next - Express next callback.
+   * @returns {Promise<void>} Resolves when middleware handling completes.
+   */
   return async function requireQuotaMiddleware(req, res, next) {
     if (!req.organization) {
       return responses.error(res, 403, 'Forbidden', 'Organization context is required to check quota')();
@@ -45,7 +57,7 @@ function requireQuota(resource, action) {
       const current = usage.counters[counterKey] || 0;
 
       if (current >= limit) {
-        return res.status(429).json({
+        return responses.error(res, 429, 'Quota exceeded', 'You have reached the usage limit for this resource')({
           type: 'QUOTA_EXCEEDED',
           resource,
           action,

modules/billing/tests/billing.quota.unit.tests.js

@@ -48,7 +48,7 @@ describe('requireQuota middleware:', () => {
       default: mockConfig,
     }));
 
-    const mod = await import('../middlewares/billing.quota.middleware.js');
+    const mod = await import('../middlewares/billing.requireQuota.js');
     requireQuota = mod.default;
 
     req = {
@@ -86,11 +86,10 @@ describe('requireQuota middleware:', () => {
     expect(next).not.toHaveBeenCalled();
     expect(res.status).toHaveBeenCalledWith(429);
     expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
-      type: 'QUOTA_EXCEEDED',
-      resource: 'scraps',
-      action: 'create',
-      limit: 3,
-      current: 3,
+      type: 'error',
+      message: 'Quota exceeded',
+      code: 429,
+      status: 429,
     }));
   });
 
@@ -113,7 +112,8 @@ describe('requireQuota middleware:', () => {
     expect(next).not.toHaveBeenCalled();
     expect(res.status).toHaveBeenCalledWith(429);
     expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
-      limit: 3,
+      type: 'error',
+      code: 429,
     }));
   });
 
@@ -126,7 +126,8 @@ describe('requireQuota middleware:', () => {
     expect(next).not.toHaveBeenCalled();
     expect(res.status).toHaveBeenCalledWith(429);
     expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
-      limit: 3,
+      type: 'error',
+      code: 429,
     }));
   });
 
@@ -146,14 +147,13 @@ describe('requireQuota middleware:', () => {
     await requireQuota('scraps', 'execute')(req, res, next);
 
     expect(res.status).toHaveBeenCalledWith(429);
-    expect(res.json).toHaveBeenCalledWith({
-      type: 'QUOTA_EXCEEDED',
-      resource: 'scraps',
-      action: 'execute',
-      limit: 100,
-      current: 100,
-      upgradeUrl: '/billing/plans',
-    });
+    expect(res.json).toHaveBeenCalledWith(expect.objectContaining({
+      type: 'error',
+      message: 'Quota exceeded',
+      code: 429,
+      status: 429,
+      description: 'You have reached the usage limit for this resource',
+    }));
   });
 
   test('should return 403 when organization context is missing', async () => {