response: add ResponseEnvelopeInterceptor and standardize error envelope in HttpExceptionFilter

Author: digitalnomad91

src/common/filters/exception.filter.ts

@@ -25,11 +25,16 @@ export class HttpExceptionFilter implements ExceptionFilter {
       // no-op: never block response on logging failures
     }
 
+    const payload = exception.getResponse?.();
     response.status(status).json({
-      statusCode: status,
-      timestamp: new Date().toISOString(),
-      path: request.path,
-      exception: exception.getResponse(),
+      success: false,
+      error: {
+        statusCode: status,
+        message: (payload as any)?.message || exception.message,
+        details: payload,
+        path: request.path,
+        timestamp: new Date().toISOString(),
+      },
     });
   }
 }

src/common/interceptors/response-envelope.interceptor.ts

@@ -0,0 +1,42 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+/**
+ * ResponseEnvelopeInterceptor
+ *
+ * Wraps successful JSON responses in a standard envelope when the handler or its
+ * method metadata indicates it. Envelope shape:
+ * { success: boolean; data?: any; error?: { code: string; message: string; details?: any } }
+ *
+ * Automatically detects if data already matches { success, data } to avoid double wrapping.
+ */
+@Injectable()
+export class ResponseEnvelopeInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const ctx = context.switchToHttp();
+    const request = ctx.getRequest();
+    const response = ctx.getResponse();
+
+    const handler = context.getHandler();
+    const wantsEnvelope = Reflect.getMetadata('cb:envelope', handler);
+
+    if (!wantsEnvelope) {
+      return next.handle();
+    }
+
+    return next.handle().pipe(
+      map((data) => {
+        // Avoid wrapping if already in desired form
+        if (data && typeof data === 'object' && 'success' in data && ('data' in data || 'error' in data)) {
+          return data;
+        }
+
+        return {
+          success: true,
+          data,
+        };
+      })
+    );
+  }
+}

src/main.ts

@@ -49,6 +49,7 @@ import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 import { PrismaClientExceptionFilter } from 'nestjs-prisma';
 import { NestExpressApplication } from '@nestjs/platform-express';
 import { HttpExceptionFilter } from './common/filters/exception.filter'; // Assuming path to your filter
+import { ResponseEnvelopeInterceptor } from './common/interceptors/response-envelope.interceptor';
 
 import helmet from 'helmet';
 import cookieParser from 'cookie-parser';
@@ -133,6 +134,8 @@ async function bootstrap(): Promise<void> {
   // Global filters for exception handling.
   const { httpAdapter } = app.get(HttpAdapterHost);
   app.useGlobalFilters(new HttpExceptionFilter(), new PrismaClientExceptionFilter(httpAdapter));
+  // Global interceptor for standardized response envelopes (only wraps endpoints marked with envelope flag)
+  app.useGlobalInterceptors(new ResponseEnvelopeInterceptor());
 
   // ===================================
   // WebSocket Adapter (Optional)