nestjs-api-forge 1.0.3 → 1.0.5

package/README.md

@@ -1,39 +1,74 @@
-# nestjs-api-forge
+<div align="center">
 
-[![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)
-[![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)
+# ⚡ NestJS API Forge
 
-Plug-and-play response envelope, exception filter, and error formatting for [NestJS](https://nestjs.com/) REST APIs — zero boilerplate, fully typed.
+**Plug-and-play response envelope, exception filter, and error formatting for NestJS REST APIs — zero boilerplate, fully typed.**
+
+[![npm version](https://img.shields.io/npm/v/nestjs-api-forge?color=blue&label=npm)](https://www.npmjs.com/package/nestjs-api-forge)
+[![npm downloads](https://img.shields.io/npm/dm/nestjs-api-forge?color=green)](https://www.npmjs.com/package/nestjs-api-forge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![NestJS](https://img.shields.io/badge/NestJS-%3E%3D9-red)](https://nestjs.com)
+[![Built with TypeScript](https://img.shields.io/badge/Built%20with-TypeScript-3178c6)](https://www.typescriptlang.org)
+[![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)
+[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?logo=github-sponsors)](https://github.com/sponsors/mirzasaikatahmmed)
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-☕-yellow?logo=buy-me-a-coffee)](https://buymeacoffee.com/saikat)
+
+<br/>
+
+> One import to standardize every response, every error, and every validation in your NestJS API.
+
+</div>
 
 ---
 
-## Features
+## 🧩 What it does
+
+Register `ApiForgeModule` once and every response from your API is automatically shaped into a consistent envelope. No more manual `{ success, data, message }` wrappers scattered across controllers.
+
+| Layer | What Forge provides |
+|-------|-------------------|
+| 📦 | **Response envelope** — every handler wrapped with `success`, `statusCode`, `message`, `data`, and `meta` |
+| 🛡️ | **Global exception filter** — handles `HttpException`, validation errors, and unexpected crashes uniformly |
+| ✅ | **Structured validation** — `ForgeValidationPipe` replaces `ValidationPipe` with typed field-level error details |
+| 📄 | **Paginated responses** — `ApiResponseDto.paginated()` with full pagination meta in one call |
+| 🏷️ | **Per-route decorators** — override messages, skip wrapping, add custom meta, or mark routes deprecated |
+| 🔍 | **Request tracing** — correlation ID passthrough, auto UUID generation, and response time measurement |
+| 💥 | **Typed exceptions** — drop-in replacements for every NestJS `HttpException` with structured error codes |
+
+### Decorators at a glance
 
-- **Uniform success envelope** — every handler response wrapped with `success`, `statusCode`, `message`, `data`, and `meta`
-- **Structured error responses** — consistent `code`, `message`, and optional `details` array for all errors
-- **Global exception filter** — handles `HttpException`, `ValidationPipe` errors, and unexpected exceptions
-- **Paginated response helper** — `ApiResponseDto.paginated()` with full pagination meta
-- **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
-- **`@ApiForge`** — apply filter + interceptor to a single controller without going global
-- **`ApiForgeModule.forRoot()`** — one-line global registration
-- **`ApiForgeModule.forRootAsync()`** — config-service-driven async options
-- **Request ID tracing** — optional UUID `requestId` in every response `meta`
+| Decorator | Scope | Description |
+|-----------|-------|-------------|
+| `@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` + `Deprecation` header |
 
 ---
 
-## Installation
+## 📦 Installation
+
+### Requirements
+
+- **Node.js** v18 or higher
+- **NestJS** v9, v10, or v11
+
+### Install
 
 ```bash
 npm install nestjs-api-forge
 ```
 
+Verify the install:
+
+```bash
+node -e "require('nestjs-api-forge'); console.log('nestjs-api-forge installed')"
+```
+
 ---
 
-## Quick Start
+## 🚀 Quick Start
 
 ### 1. Register globally in `app.module.ts`
 
@@ -49,33 +84,34 @@ 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. Add `ForgeValidationPipe` in `main.ts`
 
 ```typescript
-import { ValidationPipe } from '@nestjs/common';
-
-app.useGlobalPipes(
-  new ValidationPipe({
-    whitelist: true,
-    forbidNonWhitelisted: true,
-    transform: true,
-  }),
-);
+import { NestFactory } from '@nestjs/core';
+import { ForgeValidationPipe } from 'nestjs-api-forge';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.useGlobalPipes(new ForgeValidationPipe());
+  await app.listen(3000);
+}
+bootstrap();
 ```
 
-The exception filter automatically parses `ValidationPipe` errors and formats them into `error.details`.
+That's it. Every response is now wrapped, every error is structured, and every validation failure returns typed field details.
 
 ---
 
-## Response Shapes
+## 📐 Response Shapes
 
 ### Success (`2xx`)
 
@@ -86,10 +122,11 @@ The exception filter automatically parses `ValidationPipe` errors and formats th
   "message": "User fetched successfully",
   "data": { "id": 1, "name": "Alice Johnson", "email": "alice@example.com" },
   "meta": {
-    "timestamp": "2026-05-15T10:00:00.000Z",
+    "timestamp": "2025-01-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 +138,17 @@ 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",
+    "timestamp": "2025-01-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 +159,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": "2025-01-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,
@@ -151,75 +183,96 @@ The exception filter automatically parses `ValidationPipe` errors and formats th
     "hasPrevPage": true
   },
   "meta": {
-    "timestamp": "2026-05-15T10:00:00.000Z",
-    "path": "/api/users?page=2&limit=10"
+    "timestamp": "2025-01-15T10:00:00.000Z",
+    "path": "/api/users?page=2&limit=10",
+    "responseTime": "8ms"
+  }
+}
+```
+
+### Deprecated Route
+
+```json
+{
+  "success": true,
+  "statusCode": 200,
+  "message": "OK",
+  "data": {},
+  "meta": {
+    "timestamp": "2025-01-15T10:00:00.000Z",
+    "deprecated": true,
+    "deprecationNotice": "Use /v2/users instead"
   }
 }
 ```
 
 ---
 
-## API Reference
+## 📖 API Reference
 
 ### `ApiForgeModule.forRoot(options?)`
 
 | Option | Type | Default | Description |
-|---|---|---|---|
+|--------|------|---------|-------------|
 | `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 |
 
 ### `ApiForgeModule.forRootAsync(asyncOptions)`
 
+Use when options depend on a config service:
+
 ```typescript
 ApiForgeModule.forRootAsync({
   imports: [ConfigModule],
   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'),
   }),
 })
 ```
 
-### Decorators
+### `ForgeValidationPipe`
 
-| Decorator | Scope | Description |
-|---|---|---|
-| `@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 |
+Drop-in replacement for NestJS `ValidationPipe`. Throws `ValidationException` with structured `details` instead of a string-message array. Supports nested objects using dot-notation field paths.
 
-### `ApiResponseDto` — manual usage
+```typescript
+// Use defaults
+app.useGlobalPipes(new ForgeValidationPipe());
+
+// Override defaults
+app.useGlobalPipes(new ForgeValidationPipe({
+  whitelist: false,
+  forbidNonWhitelisted: false,
+}));
+```
+
+### `ApiResponseDto` — manual builders
 
 ```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`. Pass an optional message and `details` array to any of them.
 
 | Class | Status | Code |
-|---|---|---|
+|-------|--------|------|
 | `BadRequestException` | 400 | `BAD_REQUEST` |
 | `UnauthorizedException` | 401 | `UNAUTHORIZED` |
 | `PaymentRequiredException` | 402 | `PAYMENT_REQUIRED` |
@@ -236,23 +289,21 @@ All exceptions extend `ApiException` → `HttpException` and produce a structure
 
 ---
 
-## Usage Examples
+## 💡 Usage Examples
 
 ### Standard CRUD controller
 
 ```typescript
-import { Controller, Get, Post, Delete, Param, Body, HttpCode, HttpStatus } from '@nestjs/common';
-import { ForgeMessage, ForgeRawResponse, NotFoundException } from 'nestjs-api-forge';
+import { Controller, Get, Delete, Param, HttpCode, HttpStatus } from '@nestjs/common';
+import { ForgeMessage, 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) {
     const user = this.usersService.findById(id);
-    if (!user) throw new NotFoundException('User');
+    if (!user) throw new NotFoundException('User not found');
     return user;
   }
 
@@ -264,11 +315,9 @@ export class UsersController {
 }
 ```
 
-### Paginated list (skip envelope, build manually)
+### Paginated list
 
 ```typescript
-import { ApiResponseDto, ForgeRawResponse } from 'nestjs-api-forge';
-
 @Get()
 @ForgeRawResponse()
 findAll(@Query('page') page = '1', @Query('limit') limit = '10') {
@@ -279,22 +328,36 @@ findAll(@Query('page') page = '1', @Query('limit') limit = '10') {
 }
 ```
 
-### Per-controller scope (no global module)
+### Deprecated route
 
 ```typescript
-import { ApiForge, ForgeMessage } 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');
+}
+```
 
-@Controller('products')
-@ApiForge({ version: '2.0' })
-export class ProductsController {
-  @Get()
-  @ForgeMessage('Products fetched successfully')
-  findAll() {
-    return this.productsService.findAll();
-  }
+### Custom meta per route
+
+```typescript
+@Get()
+@ForgeMeta({ region: 'us-east-1', cache: 'miss' })
+findAll() {
+  return this.usersService.findAll();
 }
 ```
 
+### Per-controller scope (no global module)
+
+```typescript
+@Controller('products')
+@ApiForge({ version: '2.0', includeResponseTime: true })
+export class ProductsController { ... }
+```
+
 ### Raw response (health check)
 
 ```typescript
@@ -305,17 +368,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 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' },
@@ -324,17 +395,131 @@ throw ValidationException.fromConstraints({
 
 ---
 
-## Peer Dependencies
+## 📁 Project Structure
 
 ```
-@nestjs/common  ^9 | ^10 | ^11
-@nestjs/core    ^9 | ^10 | ^11
+nestjs-api-forge/
+├── src/
+│   ├── api-forge.module.ts         # forRoot / forRootAsync registration
+│   ├── index.ts                    # Public exports
+│   ├── decorators/
+│   │   └── api-response.decorator.ts  # @ApiForge, @ForgeMessage, @ForgeRawResponse, @ForgeMeta, @ForgeDeprecated
+│   ├── dto/
+│   │   └── api-response.dto.ts        # ApiResponseDto static builders
+│   ├── exceptions/
+│   │   ├── api.exception.ts           # Base ApiException class
+│   │   └── validation.exception.ts    # ValidationException with field details
+│   ├── filters/
+│   │   └── global-exception.filter.ts # ForgeExceptionFilter
+│   ├── interceptors/
+│   │   └── response.interceptor.ts    # ForgeResponseInterceptor
+│   ├── interfaces/
+│   │   └── api-response.interface.ts  # TypeScript interfaces and ForgeOptions
+│   ├── pipes/
+│   │   └── forge-validation.pipe.ts   # ForgeValidationPipe
+│   └── utils/
+│       └── error-code.util.ts
+├── app/                            # Example NestJS app demonstrating the library
+│   └── src/
+│       ├── users/                  # Full CRUD example with pagination
+│       └── products/               # Per-controller @ApiForge example
+├── .github/
+│   ├── ISSUE_TEMPLATE/            # Bug report & feature request templates
+│   └── workflows/
+│       ├── publish.yml            # npm publish on tag push
+│       └── malware-scan.yml       # Security scan on every push
+├── CONTRIBUTING.md
+├── CODE_OF_CONDUCT.md
+└── package.json
+```
+
+---
+
+## 🛠️ Development
+
+```bash
+# Clone the repo
+git clone https://github.com/mirzasaikatahmmed/nestjs-api-forge.git
+cd nestjs-api-forge
+
+# Install dependencies
+npm install
+
+# Build the library
+npm run build
+
+# Watch mode
+npm run build:watch
+
+# Format code
+npm run format
+
+# Run the example app
+cd app && npm install && npm run start:dev
+```
+
+---
+
+## 📦 Peer Dependencies
+
+```
+@nestjs/common   ^9 | ^10 | ^11
+@nestjs/core     ^9 | ^10 | ^11
 reflect-metadata ^0.1 | ^0.2
-rxjs            ^7
+rxjs             ^7
 ```
 
 ---
 
-## License
+## 📋 Changelog
+
+### v1.1.0
+- `ForgeValidationPipe` — structured validation errors with nested field support (dot-notation)
+- `@ForgeMeta(extra)` — merge custom fields into response `meta` per route or controller
+- `@ForgeDeprecated(notice?)` — deprecation flag in `meta` + `Deprecation: true` response header
+- `ApiResponseDto.accepted()` — 202 Accepted 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`
+
+### v1.0.4
+- Decorators: `@ForgeMessage`, `@ForgeRawResponse`, `@ForgeMeta`, `@ForgeDeprecated`, `@ApiForge`
+- `ForgeValidationPipe` with structured field-level errors
+- Response metadata support (`includePath`, `includeTimestamp`, `includeRequestId`, `includeResponseTime`)
+
+### v1.0.3
+- Bump version, update repository URL
+
+### v1.0.0
+- Initial release — `ApiForgeModule.forRoot()`, `ForgeExceptionFilter`, `ForgeResponseInterceptor`, `ApiResponseDto`, and 10 typed exceptions
+
+---
+
+## 🤝 Contributing
+
+Pull requests are welcome! For major changes, please open an issue first to discuss your approach.
+
+1. Fork the repository
+2. Create your branch: `git checkout -b feat/your-feature`
+3. Make your changes and run `npm run format`
+4. Push and open a PR against `main`
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before participating. All contributors are listed in [CONTRIBUTORS.md](CONTRIBUTORS.md).
+
+---
+
+## 💛 Support
+
+If NestJS API Forge saves you boilerplate, consider supporting the project:
+
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor%20on%20GitHub-%E2%9D%A4-ea4aaa?logo=github-sponsors&style=for-the-badge)](https://github.com/sponsors/mirzasaikatahmmed)
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-☕-yellow?logo=buy-me-a-coffee&style=for-the-badge)](https://buymeacoffee.com/saikat)
+
+---
+
+<div align="center">
+
+Made with ❤️ by [Mirza Saikat Ahmmed](https://github.com/mirzasaikatahmmed)
 
-MIT
+</div>

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"}