nestjs-api-forge 1.0.3 → 1.0.4

package/README.md

@@ -1,6 +1,6 @@
 # nestjs-api-forge
 
-[![Build & Publish](https://github.com/mirzasaikatahmmed/nestjs-api-forge/actions/workflows/publish.yml/badge.svg)](https://github.com/mirzasaikatahmmed/nestjs-api-forge/actions/workflows/publish.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/mirzasaikatahmmed/nestjs-api-forge/publish.yml?label=build)](https://github.com/mirzasaikatahmmed/nestjs-api-forge/actions/workflows/publish.yml)
 [![npm version](https://img.shields.io/npm/v/nestjs-api-forge.svg)](https://www.npmjs.com/package/nestjs-api-forge)
 [![npm downloads](https://img.shields.io/npm/dm/nestjs-api-forge.svg)](https://www.npmjs.com/package/nestjs-api-forge)
 [![license](https://img.shields.io/npm/l/nestjs-api-forge.svg)](https://github.com/mirzasaikatahmmed/nestjs-api-forge/blob/main/LICENSE)
@@ -18,10 +18,15 @@ Plug-and-play response envelope, exception filter, and error formatting for [Nes
 - **Built-in typed exceptions** — drop-in replacements for NestJS built-ins with structured error codes
 - **`@ForgeMessage`** — override per-route success message
 - **`@ForgeRawResponse`** — opt a route out of envelope wrapping
+- **`@ForgeMeta`** — merge custom fields into `meta` per route or controller
+- **`@ForgeDeprecated`** — mark a route as deprecated (adds `meta.deprecated` + `Deprecation` header)
 - **`@ApiForge`** — apply filter + interceptor to a single controller without going global
+- **`ForgeValidationPipe`** — drop-in `ValidationPipe` that throws structured `ValidationException` with typed field details
 - **`ApiForgeModule.forRoot()`** — one-line global registration
 - **`ApiForgeModule.forRootAsync()`** — config-service-driven async options
-- **Request ID tracing** — optional UUID `requestId` in every response `meta`
+- **Correlation ID passthrough** — read `X-Request-ID` / `X-Correlation-ID` from requests, echo on responses
+- **Response time** — optional `meta.responseTime` for every response
+- **Request ID tracing** — optional auto-generated UUID `requestId` in every response `meta`
 
 ---
 
@@ -49,29 +54,23 @@ import { ApiForgeModule } from 'nestjs-api-forge';
       includePath: true,
       includeTimestamp: true,
       includeRequestId: true,
+      includeResponseTime: true,
+      correlationIdHeader: 'x-request-id',
     }),
   ],
 })
 export class AppModule {}
 ```
 
-Every route in your application now returns a standardized response automatically.
-
-### 2. Add `ValidationPipe` in `main.ts`
+### 2. Use `ForgeValidationPipe` in `main.ts`
 
 ```typescript
-import { ValidationPipe } from '@nestjs/common';
+import { ForgeValidationPipe } from 'nestjs-api-forge';
 
-app.useGlobalPipes(
-  new ValidationPipe({
-    whitelist: true,
-    forbidNonWhitelisted: true,
-    transform: true,
-  }),
-);
+app.useGlobalPipes(new ForgeValidationPipe());
 ```
 
-The exception filter automatically parses `ValidationPipe` errors and formats them into `error.details`.
+`ForgeValidationPipe` extends NestJS `ValidationPipe` and throws a structured `ValidationException` with typed field-level details — no string parsing required.
 
 ---
 
@@ -89,7 +88,8 @@ The exception filter automatically parses `ValidationPipe` errors and formats th
     "timestamp": "2026-05-15T10:00:00.000Z",
     "path": "/api/users/1",
     "version": "1.0.0",
-    "requestId": "a3f2c1d0-84e5-4b6a-9123-abc123def456"
+    "requestId": "a3f2c1d0-84e5-4b6a-9123-abc123def456",
+    "responseTime": "4ms"
   }
 }
 ```
@@ -101,19 +101,18 @@ The exception filter automatically parses `ValidationPipe` errors and formats th
   "success": false,
   "statusCode": 404,
   "message": "User not found",
-  "error": {
-    "code": "NOT_FOUND"
-  },
+  "error": { "code": "NOT_FOUND" },
   "meta": {
     "timestamp": "2026-05-15T10:00:00.000Z",
     "path": "/api/users/99",
     "version": "1.0.0",
-    "requestId": "b1e2f3a4-0000-4b5c-8d9e-fedcba987654"
+    "requestId": "b1e2f3a4-0000-4b5c-8d9e-fedcba987654",
+    "responseTime": "2ms"
   }
 }
 ```
 
-### Validation Error (from `ValidationPipe`)
+### Validation Error
 
 ```json
 {
@@ -124,24 +123,21 @@ The exception filter automatically parses `ValidationPipe` errors and formats th
     "code": "VALIDATION_ERROR",
     "details": [
       { "field": "email", "message": "must be an email" },
-      { "field": "age", "message": "must be an integer number" }
+      { "field": "address.zip", "message": "must be a string" }
     ]
   },
-  "meta": {
-    "timestamp": "2026-05-15T10:00:00.000Z",
-    "path": "/api/users"
-  }
+  "meta": { "timestamp": "2026-05-15T10:00:00.000Z", "path": "/api/users" }
 }
 ```
 
-### Paginated (`ApiResponseDto.paginated()`)
+### Paginated
 
 ```json
 {
   "success": true,
   "statusCode": 200,
   "message": "Users fetched successfully",
-  "data": [ { "id": 1, "name": "Alice Johnson" } ],
+  "data": [{ "id": 1, "name": "Alice Johnson" }],
   "pagination": {
     "total": 42,
     "page": 2,
@@ -152,7 +148,24 @@ The exception filter automatically parses `ValidationPipe` errors and formats th
   },
   "meta": {
     "timestamp": "2026-05-15T10:00:00.000Z",
-    "path": "/api/users?page=2&limit=10"
+    "path": "/api/users?page=2&limit=10",
+    "responseTime": "8ms"
+  }
+}
+```
+
+### Deprecated route
+
+```json
+{
+  "success": true,
+  "statusCode": 200,
+  "message": "OK",
+  "data": { },
+  "meta": {
+    "timestamp": "2026-05-15T10:00:00.000Z",
+    "deprecated": true,
+    "deprecationNotice": "Use /v2/users instead"
   }
 }
 ```
@@ -167,7 +180,9 @@ The exception filter automatically parses `ValidationPipe` errors and formats th
 |---|---|---|---|
 | `includePath` | `boolean` | `true` | Include request path in `meta` |
 | `includeTimestamp` | `boolean` | `true` | Include ISO timestamp in `meta` |
-| `includeRequestId` | `boolean` | `false` | Attach a generated UUID to `meta.requestId` |
+| `includeRequestId` | `boolean` | `false` | Auto-generate UUID `requestId` in `meta` if no correlation header found |
+| `correlationIdHeader` | `string \| string[]` | `['x-request-id', 'x-correlation-id']` | Header(s) to read request ID from; echoed back on the response |
+| `includeResponseTime` | `boolean` | `false` | Include handler duration as `meta.responseTime` (e.g. `"12ms"`) |
 | `version` | `string` | `undefined` | API version string added to `meta` |
 | `defaultSuccessMessage` | `string` | `'Request successful'` | Fallback success message |
 
@@ -179,8 +194,9 @@ ApiForgeModule.forRootAsync({
   inject: [ConfigService],
   useFactory: (config: ConfigService) => ({
     version: config.get('API_VERSION'),
-    defaultSuccessMessage: config.get('DEFAULT_SUCCESS_MSG'),
     includeRequestId: true,
+    includeResponseTime: true,
+    correlationIdHeader: config.get('CORRELATION_HEADER'),
   }),
 })
 ```
@@ -192,31 +208,40 @@ ApiForgeModule.forRootAsync({
 | `@ApiForge(options?)` | Controller / Method | Apply filter + interceptor without going global |
 | `@ForgeMessage(msg)` | Controller / Method | Override the success message for that route |
 | `@ForgeRawResponse()` | Controller / Method | Skip envelope wrapping; return raw handler value |
+| `@ForgeMeta(extra)` | Controller / Method | Merge extra key-value pairs into `meta` |
+| `@ForgeDeprecated(notice?)` | Controller / Method | Mark route deprecated — adds `meta.deprecated`, optional `meta.deprecationNotice`, and `Deprecation: true` header |
+
+### `ForgeValidationPipe`
+
+Drop-in replacement for NestJS `ValidationPipe`. Throws `ValidationException` with structured `details` instead of a string-message array. Supports nested objects (dot-notation fields).
+
+```typescript
+// main.ts
+app.useGlobalPipes(new ForgeValidationPipe());
+
+// Override defaults
+app.useGlobalPipes(new ForgeValidationPipe({
+  whitelist: false,
+  forbidNonWhitelisted: false,
+}));
+```
 
 ### `ApiResponseDto` — manual usage
 
 ```typescript
 import { ApiResponseDto } from 'nestjs-api-forge';
 
-// Success
-ApiResponseDto.success(data, 'User fetched', 200, { path: '/users/1' });
-
-// Created (201)
+ApiResponseDto.success(data, 'OK', 200, { path: '/users/1' });
 ApiResponseDto.created(data, 'User created');
-
-// No content (204)
-ApiResponseDto.noContent('Deleted');
-
-// Paginated
+ApiResponseDto.accepted(jobRef, 'Export queued');   // 202
+ApiResponseDto.noContent('Deleted');                // 204
 ApiResponseDto.paginated(data, total, page, limit, 'Users fetched');
-
-// Error
 ApiResponseDto.error('Not found', 404, { code: 'NOT_FOUND' });
 ```
 
 ### Built-in Exceptions
 
-All exceptions extend `ApiException` → `HttpException` and produce a structured error body.
+All extend `ApiException` → `HttpException`.
 
 | Class | Status | Code |
 |---|---|---|
@@ -242,12 +267,10 @@ All exceptions extend `ApiException` → `HttpException` and produce a structure
 
 ```typescript
 import { Controller, Get, Post, Delete, Param, Body, HttpCode, HttpStatus } from '@nestjs/common';
-import { ForgeMessage, ForgeRawResponse, NotFoundException } from 'nestjs-api-forge';
+import { ForgeMessage, ForgeRawResponse, ForgeDeprecated, NotFoundException } from 'nestjs-api-forge';
 
 @Controller('users')
 export class UsersController {
-  constructor(private readonly usersService: UsersService) {}
-
   @Get(':id')
   @ForgeMessage('User fetched successfully')
   findOne(@Param('id') id: number) {
@@ -264,11 +287,31 @@ export class UsersController {
 }
 ```
 
-### Paginated list (skip envelope, build manually)
+### Deprecated route
 
 ```typescript
-import { ApiResponseDto, ForgeRawResponse } from 'nestjs-api-forge';
+@Get('export')
+@ForgeDeprecated('Use POST /v2/users/export instead')
+@ForgeMessage('Export started')
+startExport() {
+  const job = this.usersService.queueExport();
+  return ApiResponseDto.accepted({ jobId: job.id }, 'Export queued');
+}
+```
 
+### Custom meta per route
+
+```typescript
+@Get()
+@ForgeMeta({ region: 'us-east-1', cache: 'miss' })
+findAll() {
+  return this.usersService.findAll();
+}
+```
+
+### Paginated list (raw response)
+
+```typescript
 @Get()
 @ForgeRawResponse()
 findAll(@Query('page') page = '1', @Query('limit') limit = '10') {
@@ -282,17 +325,9 @@ findAll(@Query('page') page = '1', @Query('limit') limit = '10') {
 ### Per-controller scope (no global module)
 
 ```typescript
-import { ApiForge, ForgeMessage } from 'nestjs-api-forge';
-
 @Controller('products')
-@ApiForge({ version: '2.0' })
-export class ProductsController {
-  @Get()
-  @ForgeMessage('Products fetched successfully')
-  findAll() {
-    return this.productsService.findAll();
-  }
-}
+@ApiForge({ version: '2.0', includeResponseTime: true })
+export class ProductsController { ... }
 ```
 
 ### Raw response (health check)
@@ -305,17 +340,25 @@ health() {
 }
 ```
 
-### Custom exception with field details
+### Correlation ID tracing
+
+Send `X-Request-ID: abc-123` in the request — the same ID appears in `meta.requestId` and is echoed in the `X-Request-ID` response header. Useful for distributed tracing across microservices.
 
 ```typescript
-import { BadRequestException, ValidationException } from 'nestjs-api-forge';
+ApiForgeModule.forRoot({
+  correlationIdHeader: 'x-request-id',  // or an array of headers
+  includeRequestId: true,               // generate UUID if header is absent
+})
+```
 
-// With field-level details
+### Custom exception with field details
+
+```typescript
 throw new BadRequestException('Invalid input', [
   { field: 'price', message: 'Must be a positive number', value: -5 },
 ]);
 
-// From class-validator constraints map
+// From class-validator constraint map
 throw ValidationException.fromConstraints({
   email: { isEmail: 'must be an email' },
   age: { min: 'must be at least 1' },
@@ -335,6 +378,20 @@ rxjs            ^7
 
 ---
 
+## Changelog
+
+### 1.1.0
+- `ForgeValidationPipe` — structured validation errors with nested field support
+- `@ForgeMeta(extra)` decorator — merge custom fields into response meta
+- `@ForgeDeprecated(notice?)` decorator — deprecation flag in meta + response header
+- `ApiResponseDto.accepted()` — 202 helper
+- Correlation ID passthrough (`correlationIdHeader` option)
+- Response time measurement (`includeResponseTime` option)
+- `forRootAsync` fix — options factory now runs once instead of twice
+- 3 new exceptions: `MethodNotAllowedException`, `PaymentRequiredException`, `GatewayTimeoutException`
+
+---
+
 ## License
 
 MIT

package/dist/decorators/api-response.decorator.d.ts

@@ -1,6 +1,10 @@
 import { ForgeOptions } from '../interfaces/api-response.interface';
 export declare const FORGE_MESSAGE_KEY = "forge:response_message";
 export declare const FORGE_RAW_RESPONSE_KEY = "forge:raw_response";
+export declare const FORGE_META_KEY = "forge:extra_meta";
+export declare const FORGE_DEPRECATED_KEY = "forge:deprecated";
 export declare const ForgeMessage: (message: string) => import("@nestjs/common").CustomDecorator<string>;
 export declare const ForgeRawResponse: () => import("@nestjs/common").CustomDecorator<string>;
+export declare const ForgeMeta: (extra: Record<string, unknown>) => import("@nestjs/common").CustomDecorator<string>;
+export declare const ForgeDeprecated: (notice?: string) => import("@nestjs/common").CustomDecorator<string>;
 export declare function ApiForge(options?: ForgeOptions): <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/dist/decorators/api-response.decorator.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ForgeRawResponse = exports.ForgeMessage = exports.FORGE_RAW_RESPONSE_KEY = exports.FORGE_MESSAGE_KEY = void 0;
+exports.ForgeDeprecated = exports.ForgeMeta = exports.ForgeRawResponse = exports.ForgeMessage = exports.FORGE_DEPRECATED_KEY = exports.FORGE_META_KEY = exports.FORGE_RAW_RESPONSE_KEY = exports.FORGE_MESSAGE_KEY = void 0;
 exports.ApiForge = ApiForge;
 const common_1 = require("@nestjs/common");
 const core_1 = require("@nestjs/core");
@@ -8,10 +8,16 @@ const response_interceptor_1 = require("../interceptors/response.interceptor");
 const global_exception_filter_1 = require("../filters/global-exception.filter");
 exports.FORGE_MESSAGE_KEY = 'forge:response_message';
 exports.FORGE_RAW_RESPONSE_KEY = 'forge:raw_response';
+exports.FORGE_META_KEY = 'forge:extra_meta';
+exports.FORGE_DEPRECATED_KEY = 'forge:deprecated';
 const ForgeMessage = (message) => (0, common_1.SetMetadata)(exports.FORGE_MESSAGE_KEY, message);
 exports.ForgeMessage = ForgeMessage;
 const ForgeRawResponse = () => (0, common_1.SetMetadata)(exports.FORGE_RAW_RESPONSE_KEY, true);
 exports.ForgeRawResponse = ForgeRawResponse;
+const ForgeMeta = (extra) => (0, common_1.SetMetadata)(exports.FORGE_META_KEY, extra);
+exports.ForgeMeta = ForgeMeta;
+const ForgeDeprecated = (notice) => (0, common_1.SetMetadata)(exports.FORGE_DEPRECATED_KEY, notice ?? true);
+exports.ForgeDeprecated = ForgeDeprecated;
 function ApiForge(options = {}) {
     const reflector = new core_1.Reflector();
     return (0, common_1.applyDecorators)((0, common_1.UseInterceptors)(new response_interceptor_1.ForgeResponseInterceptor(reflector, options)), (0, common_1.UseFilters)(new global_exception_filter_1.ForgeExceptionFilter(options)));

package/dist/decorators/api-response.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-response.decorator.js","sourceRoot":"","sources":["../../src/decorators/api-response.decorator.ts"],"names":[],"mappings":";;;AAoBA,4BAMC;AA1BD,2CAA2F;AAC3F,uCAAyC;AACzC,+EAAgF;AAChF,gFAA0E;AAG7D,QAAA,iBAAiB,GAAG,wBAAwB,CAAC;AAC7C,QAAA,sBAAsB,GAAG,oBAAoB,CAAC;AAGpD,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,EAAE,CAC9C,IAAA,oBAAW,EAAC,yBAAiB,EAAE,OAAO,CAAC,CAAC;AAD7B,QAAA,YAAY,gBACiB;AAGnC,MAAM,gBAAgB,GAAG,GAAG,EAAE,CAAC,IAAA,oBAAW,EAAC,8BAAsB,EAAE,IAAI,CAAC,CAAC;AAAnE,QAAA,gBAAgB,oBAAmD;AAMhF,SAAgB,QAAQ,CAAC,UAAwB,EAAE;IACjD,MAAM,SAAS,GAAG,IAAI,gBAAS,EAAE,CAAC;IAClC,OAAO,IAAA,wBAAe,EACpB,IAAA,wBAAe,EAAC,IAAI,+CAAwB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,EACjE,IAAA,mBAAU,EAAC,IAAI,8CAAoB,CAAC,OAAO,CAAC,CAAC,CAC9C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"api-response.decorator.js","sourceRoot":"","sources":["../../src/decorators/api-response.decorator.ts"],"names":[],"mappings":";;;AA0CA,4BAMC;AAhDD,2CAA2F;AAC3F,uCAAyC;AACzC,+EAAgF;AAChF,gFAA0E;AAG7D,QAAA,iBAAiB,GAAG,wBAAwB,CAAC;AAC7C,QAAA,sBAAsB,GAAG,oBAAoB,CAAC;AAC9C,QAAA,cAAc,GAAG,kBAAkB,CAAC;AACpC,QAAA,oBAAoB,GAAG,kBAAkB,CAAC;AAGhD,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,EAAE,CAC9C,IAAA,oBAAW,EAAC,yBAAiB,EAAE,OAAO,CAAC,CAAC;AAD7B,QAAA,YAAY,gBACiB;AAGnC,MAAM,gBAAgB,GAAG,GAAG,EAAE,CAAC,IAAA,oBAAW,EAAC,8BAAsB,EAAE,IAAI,CAAC,CAAC;AAAnE,QAAA,gBAAgB,oBAAmD;AAQzE,MAAM,SAAS,GAAG,CAAC,KAA8B,EAAE,EAAE,CAC1D,IAAA,oBAAW,EAAC,sBAAc,EAAE,KAAK,CAAC,CAAC;AADxB,QAAA,SAAS,aACe;AAU9B,MAAM,eAAe,GAAG,CAAC,MAAe,EAAE,EAAE,CACjD,IAAA,oBAAW,EAAC,4BAAoB,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;AADvC,QAAA,eAAe,mBACwB;AAMpD,SAAgB,QAAQ,CAAC,UAAwB,EAAE;IACjD,MAAM,SAAS,GAAG,IAAI,gBAAS,EAAE,CAAC;IAClC,OAAO,IAAA,wBAAe,EACpB,IAAA,wBAAe,EAAC,IAAI,+CAAwB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,EACjE,IAAA,mBAAU,EAAC,IAAI,8CAAoB,CAAC,OAAO,CAAC,CAAC,CAC9C,CAAC;AACJ,CAAC"}

package/dist/dto/api-response.dto.d.ts

@@ -2,6 +2,7 @@ import { ApiErrorPayload, ApiMeta, ApiSuccessResponse, ApiErrorResponse, ApiPagi
 export declare class ApiResponseDto {
     static success<T>(data: T, message?: string, statusCode?: number, meta?: Partial<ApiMeta>): ApiSuccessResponse<T>;
     static created<T>(data: T, message?: string, meta?: Partial<ApiMeta>): ApiSuccessResponse<T>;
+    static accepted<T>(data: T, message?: string, meta?: Partial<ApiMeta>): ApiSuccessResponse<T>;
     static noContent(message?: string, meta?: Partial<ApiMeta>): ApiSuccessResponse<null>;
     static paginated<T>(data: T[], total: number, page: number, limit: number, message?: string, meta?: Partial<ApiMeta>): ApiPaginatedResponse<T>;
     static error(message: string, statusCode: number, error: ApiErrorPayload, meta?: Partial<ApiMeta>): ApiErrorResponse;

package/dist/dto/api-response.dto.js

@@ -17,6 +17,9 @@ class ApiResponseDto {
     static created(data, message = 'Resource created successfully', meta = {}) {
         return ApiResponseDto.success(data, message, 201, meta);
     }
+    static accepted(data, message = 'Request accepted for processing', meta = {}) {
+        return ApiResponseDto.success(data, message, 202, meta);
+    }
     static noContent(message = 'No content', meta = {}) {
         return ApiResponseDto.success(null, message, 204, meta);
     }

package/dist/dto/api-response.dto.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-response.dto.js","sourceRoot":"","sources":["../../src/dto/api-response.dto.ts"],"names":[],"mappings":";;;AASA,MAAa,cAAc;IACzB,MAAM,CAAC,OAAO,CACZ,IAAO,EACP,OAAO,GAAG,oBAAoB,EAC9B,UAAU,GAAG,GAAG,EAChB,OAAyB,EAAE;QAE3B,OAAO;YACL,OAAO,EAAE,IAAI;YACb,UAAU;YACV,OAAO;YACP,IAAI;YACJ,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,GAAG,IAAI;aACR;SACF,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,OAAO,CACZ,IAAO,EACP,OAAO,GAAG,+BAA+B,EACzC,OAAyB,EAAE;QAE3B,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CAAC,SAAS,CACd,OAAO,GAAG,YAAY,EACtB,OAAyB,EAAE;QAE3B,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CAAC,SAAS,CACd,IAAS,EACT,KAAa,EACb,IAAY,EACZ,KAAa,EACb,OAAO,GAAG,2BAA2B,EACrC,OAAyB,EAAE;QAE3B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;QAC5C,MAAM,UAAU,GAAmB;YACjC,KAAK;YACL,IAAI;YACJ,KAAK;YACL,UAAU;YACV,WAAW,EAAE,IAAI,GAAG,UAAU;YAC9B,WAAW,EAAE,IAAI,GAAG,CAAC;SACtB,CAAC;QAEF,OAAO;YACL,OAAO,EAAE,IAAI;YACb,UAAU,EAAE,GAAG;YACf,OAAO;YACP,IAAI;YACJ,UAAU;YACV,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,GAAG,IAAI;aACR;SACF,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,KAAK,CACV,OAAe,EACf,UAAkB,EAClB,KAAsB,EACtB,OAAyB,EAAE;QAE3B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,UAAU;YACV,OAAO;YACP,KAAK;YACL,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,GAAG,IAAI;aACR;SACF,CAAC;IACJ,CAAC;CACF;AAlFD,wCAkFC"}
+{"version":3,"file":"api-response.dto.js","sourceRoot":"","sources":["../../src/dto/api-response.dto.ts"],"names":[],"mappings":";;;AASA,MAAa,cAAc;IACzB,MAAM,CAAC,OAAO,CACZ,IAAO,EACP,OAAO,GAAG,oBAAoB,EAC9B,UAAU,GAAG,GAAG,EAChB,OAAyB,EAAE;QAE3B,OAAO;YACL,OAAO,EAAE,IAAI;YACb,UAAU;YACV,OAAO;YACP,IAAI;YACJ,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,GAAG,IAAI;aACR;SACF,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,OAAO,CACZ,IAAO,EACP,OAAO,GAAG,+BAA+B,EACzC,OAAyB,EAAE;QAE3B,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CAAC,QAAQ,CACb,IAAO,EACP,OAAO,GAAG,iCAAiC,EAC3C,OAAyB,EAAE;QAE3B,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CAAC,SAAS,CACd,OAAO,GAAG,YAAY,EACtB,OAAyB,EAAE;QAE3B,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CAAC,SAAS,CACd,IAAS,EACT,KAAa,EACb,IAAY,EACZ,KAAa,EACb,OAAO,GAAG,2BAA2B,EACrC,OAAyB,EAAE;QAE3B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;QAC5C,MAAM,UAAU,GAAmB;YACjC,KAAK;YACL,IAAI;YACJ,KAAK;YACL,UAAU;YACV,WAAW,EAAE,IAAI,GAAG,UAAU;YAC9B,WAAW,EAAE,IAAI,GAAG,CAAC;SACtB,CAAC;QAEF,OAAO;YACL,OAAO,EAAE,IAAI;YACb,UAAU,EAAE,GAAG;YACf,OAAO;YACP,IAAI;YACJ,UAAU;YACV,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,GAAG,IAAI;aACR;SACF,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,KAAK,CACV,OAAe,EACf,UAAkB,EAClB,KAAsB,EACtB,OAAyB,EAAE;QAE3B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,UAAU;YACV,OAAO;YACP,KAAK;YACL,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,GAAG,IAAI;aACR;SACF,CAAC;IACJ,CAAC;CACF;AA1FD,wCA0FC"}

package/dist/filters/global-exception.filter.d.ts

@@ -5,6 +5,7 @@ export declare class ForgeExceptionFilter implements ExceptionFilter {
     private readonly logger;
     constructor(options?: ForgeOptions);
     catch(exception: unknown, host: ArgumentsHost): void;
+    private resolveRequestId;
     private buildMeta;
     private buildErrorResponse;
     private extractHttpExceptionMessage;

package/dist/filters/global-exception.filter.js

@@ -25,7 +25,10 @@ let ForgeExceptionFilter = ForgeExceptionFilter_1 = class ForgeExceptionFilter {
         const ctx = host.switchToHttp();
         const response = ctx.getResponse();
         const request = ctx.getRequest();
-        const meta = this.buildMeta(request);
+        const requestId = this.resolveRequestId(request);
+        if (requestId)
+            response.setHeader('x-request-id', requestId);
+        const meta = this.buildMeta(request, requestId);
         const errorResponse = this.buildErrorResponse(exception, meta);
         if (errorResponse.statusCode >= 500) {
             this.logger.error(`${request.method} ${request.url} → ${errorResponse.statusCode}`, exception instanceof Error ? exception.stack : String(exception));
@@ -35,13 +38,29 @@ let ForgeExceptionFilter = ForgeExceptionFilter_1 = class ForgeExceptionFilter {
         }
         response.status(errorResponse.statusCode).json(errorResponse);
     }
-    buildMeta(request) {
-        const { includePath = true, includeTimestamp = true, includeRequestId = false, version, } = this.options;
+    resolveRequestId(request) {
+        const { includeRequestId = false, correlationIdHeader } = this.options;
+        if (!includeRequestId && !correlationIdHeader)
+            return undefined;
+        const headers = typeof correlationIdHeader === 'string'
+            ? [correlationIdHeader]
+            : Array.isArray(correlationIdHeader)
+                ? correlationIdHeader
+                : ['x-request-id', 'x-correlation-id'];
+        for (const h of headers) {
+            const val = request.headers[h.toLowerCase()];
+            if (typeof val === 'string' && val)
+                return val;
+        }
+        return includeRequestId ? (0, crypto_1.randomUUID)() : undefined;
+    }
+    buildMeta(request, requestId) {
+        const { includePath = true, includeTimestamp = true, version } = this.options;
         return {
             ...(includeTimestamp && { timestamp: new Date().toISOString() }),
             ...(includePath && { path: request.url }),
             ...(version && { version }),
-            ...(includeRequestId && { requestId: (0, crypto_1.randomUUID)() }),
+            ...(requestId && { requestId }),
         };
     }
     buildErrorResponse(exception, meta) {

package/dist/filters/global-exception.filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"global-exception.filter.js","sourceRoot":"","sources":["../../src/filters/global-exception.filter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"global-exception.filter.js","sourceRoot":"","sources":["../../src/filters/global-exception.filter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -5,4 +5,5 @@ export * from './exceptions';
 export * from './filters';
 export * from './interceptors';
 export * from './interfaces';
+export * from './pipes';
 export * from './utils';

package/dist/index.js

@@ -21,5 +21,6 @@ __exportStar(require("./exceptions"), exports);
 __exportStar(require("./filters"), exports);
 __exportStar(require("./interceptors"), exports);
 __exportStar(require("./interfaces"), exports);
+__exportStar(require("./pipes"), exports);
 __exportStar(require("./utils"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,+CAA6B;AAC7B,wCAAsB;AACtB,+CAA6B;AAC7B,4CAA0B;AAC1B,iDAA+B;AAC/B,+CAA6B;AAC7B,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,+CAA6B;AAC7B,wCAAsB;AACtB,+CAA6B;AAC7B,4CAA0B;AAC1B,iDAA+B;AAC/B,+CAA6B;AAC7B,0CAAwB;AACxB,0CAAwB"}

package/dist/interceptors/response.interceptor.d.ts

@@ -7,5 +7,6 @@ export declare class ForgeResponseInterceptor implements NestInterceptor {
     private readonly options;
     constructor(reflector: Reflector, options?: ForgeOptions);
     intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+    private resolveRequestId;
     private buildMeta;
 }

package/dist/interceptors/response.interceptor.js

@@ -25,24 +25,64 @@ let ForgeResponseInterceptor = class ForgeResponseInterceptor {
         const isRaw = this.reflector.getAllAndOverride(api_response_decorator_1.FORGE_RAW_RESPONSE_KEY, [context.getHandler(), context.getClass()]);
         if (isRaw)
             return next.handle();
+        const start = Date.now();
         const customMessage = this.reflector.getAllAndOverride(api_response_decorator_1.FORGE_MESSAGE_KEY, [context.getHandler(), context.getClass()]);
+        const extraMeta = this.reflector.getAllAndOverride(api_response_decorator_1.FORGE_META_KEY, [context.getHandler(), context.getClass()]) ?? {};
+        const deprecatedValue = this.reflector.getAllAndOverride(api_response_decorator_1.FORGE_DEPRECATED_KEY, [context.getHandler(), context.getClass()]);
         const request = context.switchToHttp().getRequest();
-        const statusCode = context.switchToHttp().getResponse().statusCode;
-        const meta = this.buildMeta(request);
+        const response = context.switchToHttp().getResponse();
+        const statusCode = response.statusCode;
+        const requestId = this.resolveRequestId(request);
+        if (requestId)
+            response.setHeader('x-request-id', requestId);
+        if (deprecatedValue)
+            response.setHeader('Deprecation', 'true');
         return next.handle().pipe((0, operators_1.map)((data) => {
             const message = customMessage ??
                 this.options.defaultSuccessMessage ??
                 'Request successful';
+            const deprecationMeta = deprecatedValue
+                ? {
+                    deprecated: true,
+                    ...(typeof deprecatedValue === 'string' && {
+                        deprecationNotice: deprecatedValue,
+                    }),
+                }
+                : {};
+            const meta = {
+                ...this.buildMeta(request, requestId),
+                ...(this.options.includeResponseTime && {
+                    responseTime: `${Date.now() - start}ms`,
+                }),
+                ...deprecationMeta,
+                ...extraMeta,
+            };
             return api_response_dto_1.ApiResponseDto.success(data, message, statusCode, meta);
         }));
     }
-    buildMeta(request) {
-        const { includePath = true, includeTimestamp = true, includeRequestId = false, version, } = this.options;
+    resolveRequestId(request) {
+        const { includeRequestId = false, correlationIdHeader } = this.options;
+        if (!includeRequestId && !correlationIdHeader)
+            return undefined;
+        const headers = typeof correlationIdHeader === 'string'
+            ? [correlationIdHeader]
+            : Array.isArray(correlationIdHeader)
+                ? correlationIdHeader
+                : ['x-request-id', 'x-correlation-id'];
+        for (const h of headers) {
+            const val = request.headers[h.toLowerCase()];
+            if (typeof val === 'string' && val)
+                return val;
+        }
+        return includeRequestId ? (0, crypto_1.randomUUID)() : undefined;
+    }
+    buildMeta(request, requestId) {
+        const { includePath = true, includeTimestamp = true, version } = this.options;
         return {
             ...(includeTimestamp && { timestamp: new Date().toISOString() }),
             ...(includePath && { path: request.url }),
             ...(version && { version }),
-            ...(includeRequestId && { requestId: (0, crypto_1.randomUUID)() }),
+            ...(requestId && { requestId }),
         };
     }
 };

package/dist/interceptors/response.interceptor.js.map

@@ -1 +1 @@
-{"version":3,"file":"response.interceptor.js","sourceRoot":"","sources":["../../src/interceptors/response.interceptor.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAKwB;AACxB,uCAAyC;AACzC,mCAAoC;AAEpC,8CAAqC;AAErC,8DAAyD;AAEzD,iFAG8C;AAGvC,IAAM,wBAAwB,GAA9B,MAAM,wBAAwB;IACnC,YACmB,SAAoB,EACpB,UAAwB,EAAE;QAD1B,cAAS,GAAT,SAAS,CAAW;QACpB,YAAO,GAAP,OAAO,CAAmB;IAC1C,CAAC;IAEJ,SAAS,CAAC,OAAyB,EAAE,IAAiB;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAC5C,+CAAsB,EACtB,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAC3C,CAAC;QAEF,IAAI,KAAK;YAAE,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;QAEhC,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC,iBAAiB,CACpD,0CAAiB,EACjB,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAC3C,CAAC;QAEF,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,UAAU,EAAW,CAAC;QAC7D,MAAM,UAAU,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC;QAEnE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAErC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CACvB,IAAA,eAAG,EAAC,CAAC,IAAI,EAAE,EAAE;YACX,MAAM,OAAO,GACX,aAAa;gBACb,IAAI,CAAC,OAAO,CAAC,qBAAqB;gBAClC,oBAAoB,CAAC;YAEvB,OAAO,iCAAc,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;QACjE,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;IAEO,SAAS,CAAC,OAAgB;QAChC,MAAM,EACJ,WAAW,GAAG,IAAI,EAClB,gBAAgB,GAAG,IAAI,EACvB,gBAAgB,GAAG,KAAK,EACxB,OAAO,GACR,GAAG,IAAI,CAAC,OAAO,CAAC;QACjB,OAAO;YACL,GAAG,CAAC,gBAAgB,IAAI,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;YAChE,GAAG,CAAC,WAAW,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;YACzC,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;YAC3B,GAAG,CAAC,gBAAgB,IAAI,EAAE,SAAS,EAAE,IAAA,mBAAU,GAAE,EAAE,CAAC;SACrD,CAAC;IACJ,CAAC;CACF,CAAA;AAlDY,4DAAwB;mCAAxB,wBAAwB;IADpC,IAAA,mBAAU,GAAE;qCAGmB,gBAAS;GAF5B,wBAAwB,CAkDpC"}
+{"version":3,"file":"response.interceptor.js","sourceRoot":"","sources":["../../src/interceptors/response.interceptor.ts"],"names":[],"mappings":"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"}

package/dist/interfaces/api-response.interface.d.ts

@@ -3,6 +3,10 @@ export interface ApiMeta {
     path?: string;
     version?: string;
     requestId?: string;
+    responseTime?: string;
+    deprecated?: true;
+    deprecationNotice?: string;
+    [key: string]: unknown;
 }
 export interface ApiSuccessResponse<T = unknown> {
     success: true;
@@ -48,6 +52,8 @@ export interface ForgeOptions {
     includePath?: boolean;
     includeTimestamp?: boolean;
     includeRequestId?: boolean;
+    correlationIdHeader?: string | string[];
+    includeResponseTime?: boolean;
     version?: string;
     defaultSuccessMessage?: string;
 }

package/dist/pipes/forge-validation.pipe.d.ts

@@ -0,0 +1,4 @@
+import { ValidationPipe, ValidationPipeOptions } from '@nestjs/common';
+export declare class ForgeValidationPipe extends ValidationPipe {
+    constructor(options?: ValidationPipeOptions);
+}