@nest-toolbox/response-envelope 1.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 bogdanlupu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# @nest-toolbox/response-envelope
+
+Standard API response envelope with interceptor, exception filter, and helpers for NestJS.
+
+[![npm version](https://badge.fury.io/js/%40nest-toolbox%2Fresponse-envelope.svg)](https://www.npmjs.com/package/@nest-toolbox/response-envelope)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🚀 **Zero-config** — import the module and every route gets a consistent envelope
+- 🎯 **Decorator-first** — `@SkipEnvelope()` and `@ApiMessage()` for per-route control
+- 🛡️ **Consistent error formatting** — class-validator errors auto-parsed into structured field errors
+- 🔄 **Idempotent** — already-wrapped responses pass through untouched
+- ⚙️ **Configurable** — `forRoot()` / `forRootAsync()` for custom defaults
+- 📦 **Manual helpers** — `success()`, `error()`, `paginated()` for WebSockets, queues, etc.
+
+## Installation
+
+```bash
+npm install @nest-toolbox/response-envelope
+```
+
+## Quick Start
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { ResponseEnvelopeModule } from '@nest-toolbox/response-envelope';
+
+@Module({
+  imports: [ResponseEnvelopeModule.forRoot()],
+})
+export class AppModule {}
+```
+
+That's it! Every route now returns a consistent envelope. No interceptors to register, no filters to bind.
+
+## Response Format
+
+### Success
+
+```json
+{
+  "success": true,
+  "data": { "id": 1, "name": "Alice" },
+  "message": "OK",
+  "meta": {
+    "timestamp": "2025-02-05T07:32:00.000Z",
+    "path": "/api/users/1",
+    "statusCode": 200
+  }
+}
+```
+
+### Paginated Success
+
+```json
+{
+  "success": true,
+  "data": [{ "id": 1 }, { "id": 2 }],
+  "message": "OK",
+  "meta": {
+    "timestamp": "2025-02-05T07:32:00.000Z",
+    "path": "/api/users",
+    "statusCode": 200,
+    "pagination": {
+      "page": 1,
+      "limit": 20,
+      "total": 100,
+      "totalPages": 5
+    }
+  }
+}
+```
+
+### Error
+
+```json
+{
+  "success": false,
+  "data": null,
+  "message": "Validation failed",
+  "errors": [
+    { "field": "email", "message": "must be a valid email" },
+    { "field": "name", "message": "should not be empty" }
+  ],
+  "meta": {
+    "timestamp": "2025-02-05T07:32:00.000Z",
+    "path": "/api/users",
+    "statusCode": 400
+  }
+}
+```
+
+## API Reference
+
+### `ResponseEnvelopeModule.forRoot(options?)`
+
+Register the module globally with static options.
+
+```typescript
+ResponseEnvelopeModule.forRoot({
+  defaultMessage: 'Success',
+  includePath: true,
+  includeTimestamp: true,
+});
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultMessage` | `string` | `'OK'` | Default success message when `@ApiMessage()` is not used |
+| `includePath` | `boolean` | `true` | Include the request path in response meta |
+| `includeTimestamp` | `boolean` | `true` | Include the ISO timestamp in response meta |
+
+### `ResponseEnvelopeModule.forRootAsync(options)`
+
+Register the module with async factory injection.
+
+```typescript
+ResponseEnvelopeModule.forRootAsync({
+  imports: [ConfigModule],
+  useFactory: (config: ConfigService) => ({
+    defaultMessage: config.get('API_DEFAULT_MESSAGE', 'OK'),
+    includePath: config.get('API_INCLUDE_PATH') !== 'false',
+  }),
+  inject: [ConfigService],
+});
+```
+
+### `@SkipEnvelope()`
+
+Skip the envelope for a specific route handler. The raw return value is sent as-is.
+
+```typescript
+import { SkipEnvelope } from '@nest-toolbox/response-envelope';
+
+@Controller()
+export class AppController {
+  @Get('health')
+  @SkipEnvelope()
+  health() {
+    return { status: 'ok' }; // sent as-is, no envelope
+  }
+}
+```
+
+### `@ApiMessage(message)`
+
+Set a custom success message for a route handler.
+
+```typescript
+import { ApiMessage } from '@nest-toolbox/response-envelope';
+
+@Controller('users')
+export class UsersController {
+  @Post()
+  @ApiMessage('User created successfully')
+  create(@Body() dto: CreateUserDto) {
+    return this.usersService.create(dto);
+  }
+  // → { success: true, data: { ... }, message: "User created successfully", meta: { ... } }
+}
+```
+
+### `success(data, options?)`
+
+Manually create a success envelope. Useful outside the HTTP interceptor (WebSocket gateways, message queues, etc.).
+
+```typescript
+import { success } from '@nest-toolbox/response-envelope';
+
+const response = success(user, {
+  message: 'User found',
+  path: '/api/users/1',
+  statusCode: 200,
+});
+```
+
+**Options:** `message?: string`, `path?: string`, `statusCode?: number`, `pagination?: PaginationMeta`
+
+### `error(message, options?)`
+
+Manually create an error envelope.
+
+```typescript
+import { error } from '@nest-toolbox/response-envelope';
+
+const response = error('Validation failed', {
+  statusCode: 400,
+  errors: [{ field: 'email', message: 'must be a valid email' }],
+  path: '/api/users',
+});
+```
+
+**Options:** `errors?: FieldError[]`, `path?: string`, `statusCode?: number`
+
+### `paginated(data, pagination, options?)`
+
+Create a paginated success envelope with pagination metadata.
+
+```typescript
+import { paginated } from '@nest-toolbox/response-envelope';
+
+const response = paginated(users, { page: 1, limit: 20, total: 100 }, {
+  message: 'Users retrieved',
+  path: '/api/users',
+});
+// → meta.pagination = { page: 1, limit: 20, total: 100, totalPages: 5 }
+```
+
+**Pagination:** `page: number`, `limit: number`, `total: number`
+**Options:** `message?: string`, `path?: string`, `statusCode?: number`
+
+## Types
+
+All types are exported from the package. See [`src/types.ts`](./src/types.ts) for full definitions.
+
+| Type | Description |
+|------|-------------|
+| `ApiResponse<T>` | Standard success response envelope |
+| `ApiErrorResponse` | Standard error response envelope |
+| `ResponseMeta` | Metadata attached to every response (timestamp, path, statusCode) |
+| `PaginationMeta` | Pagination info (page, limit, total, totalPages) |
+| `FieldError` | Structured field-level error (`{ field, message }`) |
+| `ResponseEnvelopeOptions` | Static configuration options for `forRoot()` |
+| `ResponseEnvelopeAsyncOptions` | Async configuration options for `forRootAsync()` |
+
+## Integration with Other Toolbox Packages
+
+### @nest-toolbox/typeorm-paginate
+
+The `paginated()` helper pairs naturally with [`@nest-toolbox/typeorm-paginate`](../typeorm-paginate):
+
+```typescript
+import { paginate } from '@nest-toolbox/typeorm-paginate';
+import { paginated } from '@nest-toolbox/response-envelope';
+
+@Get()
+async findAll(@Query() query: PaginationDto) {
+  const result = await paginate(this.userRepository, {
+    page: query.page,
+    limit: query.limit,
+  });
+
+  return paginated(result.items, {
+    page: result.meta.currentPage,
+    limit: result.meta.itemsPerPage,
+    total: result.meta.totalItems,
+  });
+}
+```
+
+## License
+
+MIT © [Bogdan Lupu](https://github.com/lupu60)

package/dist/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Constants for @nest-toolbox/response-envelope
+ */
+/** Metadata key for @SkipEnvelope() decorator */
+export declare const SKIP_ENVELOPE_KEY = "response-envelope:skip";
+/** Metadata key for @ApiMessage() decorator */
+export declare const API_MESSAGE_KEY = "response-envelope:message";
+/** Injection token for module options */
+export declare const RESPONSE_ENVELOPE_OPTIONS = "RESPONSE_ENVELOPE_OPTIONS";
+/** Default success message */
+export declare const DEFAULT_MESSAGE = "OK";

package/dist/constants.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Constants for @nest-toolbox/response-envelope
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MESSAGE = exports.RESPONSE_ENVELOPE_OPTIONS = exports.API_MESSAGE_KEY = exports.SKIP_ENVELOPE_KEY = void 0;
+/** Metadata key for @SkipEnvelope() decorator */
+exports.SKIP_ENVELOPE_KEY = 'response-envelope:skip';
+/** Metadata key for @ApiMessage() decorator */
+exports.API_MESSAGE_KEY = 'response-envelope:message';
+/** Injection token for module options */
+exports.RESPONSE_ENVELOPE_OPTIONS = 'RESPONSE_ENVELOPE_OPTIONS';
+/** Default success message */
+exports.DEFAULT_MESSAGE = 'OK';
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,iDAAiD;AACpC,QAAA,iBAAiB,GAAG,wBAAwB,CAAC;AAE1D,+CAA+C;AAClC,QAAA,eAAe,GAAG,2BAA2B,CAAC;AAE3D,yCAAyC;AAC5B,QAAA,yBAAyB,GAAG,2BAA2B,CAAC;AAErE,8BAA8B;AACjB,QAAA,eAAe,GAAG,IAAI,CAAC"}

package/dist/decorators.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Decorators for @nest-toolbox/response-envelope
+ */
+/**
+ * Skip the response envelope for a specific route handler.
+ * The raw controller return value will be sent as-is.
+ *
+ * @example
+ * ```typescript
+ * @Get('health')
+ * @SkipEnvelope()
+ * health() {
+ *   return { status: 'ok' };
+ * }
+ * ```
+ */
+export declare const SkipEnvelope: () => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * Set a custom success message for a route handler's response envelope.
+ *
+ * @param message - The message to include in the response envelope
+ *
+ * @example
+ * ```typescript
+ * @Post()
+ * @ApiMessage('User created successfully')
+ * create(@Body() dto: CreateUserDto) {
+ *   return this.usersService.create(dto);
+ * }
+ * ```
+ */
+export declare const ApiMessage: (message: string) => import("@nestjs/common").CustomDecorator<string>;

package/dist/decorators.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Decorators for @nest-toolbox/response-envelope
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiMessage = exports.SkipEnvelope = void 0;
+const common_1 = require("@nestjs/common");
+const constants_1 = require("./constants");
+/**
+ * Skip the response envelope for a specific route handler.
+ * The raw controller return value will be sent as-is.
+ *
+ * @example
+ * ```typescript
+ * @Get('health')
+ * @SkipEnvelope()
+ * health() {
+ *   return { status: 'ok' };
+ * }
+ * ```
+ */
+const SkipEnvelope = () => (0, common_1.SetMetadata)(constants_1.SKIP_ENVELOPE_KEY, true);
+exports.SkipEnvelope = SkipEnvelope;
+/**
+ * Set a custom success message for a route handler's response envelope.
+ *
+ * @param message - The message to include in the response envelope
+ *
+ * @example
+ * ```typescript
+ * @Post()
+ * @ApiMessage('User created successfully')
+ * create(@Body() dto: CreateUserDto) {
+ *   return this.usersService.create(dto);
+ * }
+ * ```
+ */
+const ApiMessage = (message) => (0, common_1.SetMetadata)(constants_1.API_MESSAGE_KEY, message);
+exports.ApiMessage = ApiMessage;
+//# sourceMappingURL=decorators.js.map

package/dist/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,2CAA6C;AAC7C,2CAAiE;AAEjE;;;;;;;;;;;;GAYG;AACI,MAAM,YAAY,GAAG,GAAG,EAAE,CAAC,IAAA,oBAAW,EAAC,6BAAiB,EAAE,IAAI,CAAC,CAAC;AAA1D,QAAA,YAAY,gBAA8C;AAEvE;;;;;;;;;;;;;GAaG;AACI,MAAM,UAAU,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,IAAA,oBAAW,EAAC,2BAAe,EAAE,OAAO,CAAC,CAAC;AAAxE,QAAA,UAAU,cAA8D"}

package/dist/envelope-exception.filter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Exception filter that formats errors in the standard envelope shape.
+ *
+ * Handles HttpException (and subclasses like BadRequestException, NotFoundException)
+ * as well as unknown errors, formatting them into a consistent ApiErrorResponse.
+ */
+import { type ArgumentsHost, type ExceptionFilter } from '@nestjs/common';
+import type { ResponseEnvelopeOptions } from './types';
+export declare class EnvelopeExceptionFilter implements ExceptionFilter {
+    private readonly options?;
+    constructor(options?: ResponseEnvelopeOptions | undefined);
+    catch(exception: unknown, host: ArgumentsHost): void;
+}

package/dist/envelope-exception.filter.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Exception filter that formats errors in the standard envelope shape.
+ *
+ * Handles HttpException (and subclasses like BadRequestException, NotFoundException)
+ * as well as unknown errors, formatting them into a consistent ApiErrorResponse.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvelopeExceptionFilter = void 0;
+const common_1 = require("@nestjs/common");
+const constants_1 = require("./constants");
+let EnvelopeExceptionFilter = class EnvelopeExceptionFilter {
+    constructor(options) {
+        this.options = options;
+    }
+    catch(exception, host) {
+        var _a, _b, _c, _d, _e;
+        const ctx = host.switchToHttp();
+        const response = ctx.getResponse();
+        const request = ctx.getRequest();
+        const statusCode = exception instanceof common_1.HttpException ? exception.getStatus() : common_1.HttpStatus.INTERNAL_SERVER_ERROR;
+        const message = extractMessage(exception);
+        const errors = extractFieldErrors(exception);
+        const includePath = (_b = (_a = this.options) === null || _a === void 0 ? void 0 : _a.includePath) !== null && _b !== void 0 ? _b : true;
+        const includeTimestamp = (_d = (_c = this.options) === null || _c === void 0 ? void 0 : _c.includeTimestamp) !== null && _d !== void 0 ? _d : true;
+        const body = {
+            success: false,
+            data: null,
+            message,
+            errors,
+            meta: {
+                timestamp: includeTimestamp ? new Date().toISOString() : '',
+                path: includePath ? ((_e = request.url) !== null && _e !== void 0 ? _e : '') : '',
+                statusCode,
+            },
+        };
+        response.status(statusCode).json(body);
+    }
+};
+exports.EnvelopeExceptionFilter = EnvelopeExceptionFilter;
+exports.EnvelopeExceptionFilter = EnvelopeExceptionFilter = __decorate([
+    (0, common_1.Catch)(),
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(constants_1.RESPONSE_ENVELOPE_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], EnvelopeExceptionFilter);
+/**
+ * Extract a human-readable message from the exception.
+ */
+function extractMessage(exception) {
+    if (exception instanceof common_1.HttpException) {
+        const response = exception.getResponse();
+        if (typeof response === 'string') {
+            return response;
+        }
+        if (typeof response === 'object' && response !== null) {
+            const obj = response;
+            if (typeof obj.message === 'string') {
+                return obj.message;
+            }
+            // class-validator returns message as an array
+            if (Array.isArray(obj.message) && obj.message.length > 0) {
+                return 'Validation failed';
+            }
+        }
+    }
+    if (exception instanceof Error) {
+        return exception.message;
+    }
+    return 'Internal server error';
+}
+/**
+ * Extract structured field errors from class-validator ValidationPipe responses.
+ */
+function extractFieldErrors(exception) {
+    if (!(exception instanceof common_1.HttpException)) {
+        return [];
+    }
+    const response = exception.getResponse();
+    if (typeof response !== 'object' || response === null) {
+        return [];
+    }
+    const obj = response;
+    // class-validator via ValidationPipe returns { message: string[] }
+    if (Array.isArray(obj.message)) {
+        return obj.message.filter((msg) => typeof msg === 'string').map(parseValidationMessage);
+    }
+    return [];
+}
+/**
+ * Parse a class-validator message like "email must be a valid email" into a FieldError.
+ * The first word is typically the field name.
+ */
+function parseValidationMessage(message) {
+    const spaceIndex = message.indexOf(' ');
+    if (spaceIndex === -1) {
+        return { field: 'unknown', message };
+    }
+    return {
+        field: message.substring(0, spaceIndex),
+        message: message.substring(spaceIndex + 1),
+    };
+}
+//# sourceMappingURL=envelope-exception.filter.js.map

package/dist/envelope-exception.filter.js.map

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

package/dist/helpers.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Helper functions for manually creating envelope responses.
+ *
+ * Use these when you need to construct responses outside of the interceptor,
+ * for example in WebSocket gateways or message queues.
+ */
+import type { ApiErrorResponse, ApiResponse, FieldError, PaginationMeta } from './types';
+/**
+ * Create a success envelope.
+ *
+ * @param data - The response payload
+ * @param options - Optional message, path, statusCode, and pagination
+ * @returns A typed ApiResponse envelope
+ *
+ * @example
+ * ```typescript
+ * return success(user, { message: 'User found', path: '/api/users/1' });
+ * ```
+ */
+export declare function success<T>(data: T, options?: {
+    message?: string;
+    path?: string;
+    statusCode?: number;
+    pagination?: PaginationMeta;
+}): ApiResponse<T>;
+/**
+ * Create an error envelope.
+ *
+ * @param message - The error message
+ * @param options - Optional errors array, path, and statusCode
+ * @returns A typed ApiErrorResponse envelope
+ *
+ * @example
+ * ```typescript
+ * return error('Validation failed', {
+ *   statusCode: 400,
+ *   errors: [{ field: 'email', message: 'must be a valid email' }],
+ * });
+ * ```
+ */
+export declare function error(message: string, options?: {
+    errors?: FieldError[];
+    path?: string;
+    statusCode?: number;
+}): ApiErrorResponse;
+/**
+ * Create a paginated success envelope.
+ *
+ * @param data - The array of items for the current page
+ * @param pagination - Pagination metadata (page, limit, total)
+ * @param options - Optional message, path, and statusCode
+ * @returns A typed ApiResponse envelope with pagination meta
+ *
+ * @example
+ * ```typescript
+ * return paginated(users, { page: 1, limit: 20, total: 100 }, {
+ *   path: '/api/users',
+ * });
+ * ```
+ */
+export declare function paginated<T>(data: T[], pagination: {
+    page: number;
+    limit: number;
+    total: number;
+}, options?: {
+    message?: string;
+    path?: string;
+    statusCode?: number;
+}): ApiResponse<T[]>;

package/dist/helpers.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Helper functions for manually creating envelope responses.
+ *
+ * Use these when you need to construct responses outside of the interceptor,
+ * for example in WebSocket gateways or message queues.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.success = success;
+exports.error = error;
+exports.paginated = paginated;
+const constants_1 = require("./constants");
+/**
+ * Create a success envelope.
+ *
+ * @param data - The response payload
+ * @param options - Optional message, path, statusCode, and pagination
+ * @returns A typed ApiResponse envelope
+ *
+ * @example
+ * ```typescript
+ * return success(user, { message: 'User found', path: '/api/users/1' });
+ * ```
+ */
+function success(data, options = {}) {
+    var _a, _b, _c;
+    const meta = {
+        timestamp: new Date().toISOString(),
+        path: (_a = options.path) !== null && _a !== void 0 ? _a : '',
+        statusCode: (_b = options.statusCode) !== null && _b !== void 0 ? _b : 200,
+    };
+    if (options.pagination) {
+        meta.pagination = options.pagination;
+    }
+    return {
+        success: true,
+        data,
+        message: (_c = options.message) !== null && _c !== void 0 ? _c : constants_1.DEFAULT_MESSAGE,
+        meta,
+    };
+}
+/**
+ * Create an error envelope.
+ *
+ * @param message - The error message
+ * @param options - Optional errors array, path, and statusCode
+ * @returns A typed ApiErrorResponse envelope
+ *
+ * @example
+ * ```typescript
+ * return error('Validation failed', {
+ *   statusCode: 400,
+ *   errors: [{ field: 'email', message: 'must be a valid email' }],
+ * });
+ * ```
+ */
+function error(message, options = {}) {
+    var _a, _b, _c;
+    return {
+        success: false,
+        data: null,
+        message,
+        errors: (_a = options.errors) !== null && _a !== void 0 ? _a : [],
+        meta: {
+            timestamp: new Date().toISOString(),
+            path: (_b = options.path) !== null && _b !== void 0 ? _b : '',
+            statusCode: (_c = options.statusCode) !== null && _c !== void 0 ? _c : 500,
+        },
+    };
+}
+/**
+ * Create a paginated success envelope.
+ *
+ * @param data - The array of items for the current page
+ * @param pagination - Pagination metadata (page, limit, total)
+ * @param options - Optional message, path, and statusCode
+ * @returns A typed ApiResponse envelope with pagination meta
+ *
+ * @example
+ * ```typescript
+ * return paginated(users, { page: 1, limit: 20, total: 100 }, {
+ *   path: '/api/users',
+ * });
+ * ```
+ */
+function paginated(data, pagination, options = {}) {
+    const totalPages = pagination.limit > 0 ? Math.ceil(pagination.total / pagination.limit) : 0;
+    return success(data, Object.assign(Object.assign({}, options), { pagination: {
+            page: pagination.page,
+            limit: pagination.limit,
+            total: pagination.total,
+            totalPages,
+        } }));
+}
+//# sourceMappingURL=helpers.js.map