@myko.pk/response 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 MYKO Pakistan
+
+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,256 @@
+<p align="center">
+  <h1 align="center">@myko.pk/response</h1>
+  <p align="center"><strong>Consistent responses. Clear errors.</strong></p>
+  <p align="center">Shared response utilities, builders, and exception filters for MYKO services. Provides a unified API response envelope, configurable NestJS exception filters, a response interceptor for automatic wrapping, request context tracking, Swagger integration, and reusable pagination DTOs.</p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/@myko.pk/response"><img src="https://img.shields.io/npm/v/@myko.pk/response?style=for-the-badge&logo=npm&logoColor=white" alt="npm version"></a>
+    <a href="https://www.npmjs.com/package/@myko.pk/response"><img src="https://img.shields.io/npm/dm/@myko.pk/response?style=for-the-badge&logo=npm&logoColor=white" alt="npm downloads"></a>
+    <a href="https://github.com/mykopk/response/actions"><img src="https://img.shields.io/github/actions/workflow/status/mykopk/response/ci.yml?style=for-the-badge&logo=githubactions&logoColor=white&label=CI" alt="build"></a>
+    <a href="https://github.com/mykopk/response"><img src="https://img.shields.io/github/stars/mykopk/response?style=for-the-badge&logo=github" alt="stars"></a>
+    <a href="https://github.com/mykopk/response"><img src="https://img.shields.io/github/forks/mykopk/response?style=for-the-badge&logo=github" alt="forks"></a>
+    <a href="https://github.com/mykopk/response"><img src="https://img.shields.io/github/issues/mykopk/response?style=for-the-badge&logo=github" alt="issues"></a>
+    <a href="https://github.com/mykopk/response"><img src="https://img.shields.io/github/last-commit/mykopk/response?style=for-the-badge&logo=github" alt="last commit"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="license"></a>
+  </p>
+</p>
+
+## 📑 Table of Contents
+
+- [Description](#description)
+- [Key Features](#key-features)
+- [Use Cases](#use-cases)
+- [Tech Stack](#tech-stack)
+- [Quick Start](#quick-start)
+- [Available Scripts](#available-scripts)
+- [Project Structure](#project-structure)
+- [Contributors](#contributors)
+- [Contributing](#contributing)
+- [License](#license)
+
+## 📝 Description
+
+@myko.pk/response provides a standardised response envelope (`ApiResponse<T>`) and a set of reusable NestJS exception filters for every MYKO service. The `ResponseBuilder` class offers a fluent API for constructing success, error, paginated, cursor-paginated, and specialised responses. Built-in exception filters handle `HttpException`, validation errors, database errors, and auth failures — all rendered into a consistent `ApiResponse` shape.
+
+The package also includes a request context system (AsyncLocalStorage-based requestId tracking across the request lifecycle), decorators for fine-grained control over response wrapping, reusable pagination DTOs, a Swagger decorator to document the `ApiResponse` envelope, and a validation error formatter utility.
+
+## ✨ Key Features
+
+- **📦 Unified Response Envelope** — Every response follows the `ApiResponse<T>` shape: `success`, `statusCode`, `message`, `data`, `error`, `timestamp`, `requestId`.
+- **🏗️ Fluent Response Builder** — `ResponseBuilder.success()`, `ResponseBuilder.error()`, `ResponseBuilder.paginated()`, `ResponseBuilder.cursorPaginated()`, `ResponseBuilder.ok()`, and specialised methods for bulk, import/export, redirect, file download, and partial success.
+- **🛡️ Configurable Exception Filters** — 5 NestJS exception filters covering global, validation, HTTP, database, and auth exceptions. Register all or pick specific ones via `ResponseModule.forRoot()`.
+- **🔄 Response Interceptor** — Automatically wraps controller returns into `ApiResponse`. Respects `@SkipResponseWrapper()` and `@ResponseMessage()` decorators.
+- **🔗 Request Context** — `RequestContextInterceptor` captures or generates a `requestId` (via `x-request-id` header or `crypto.randomUUID()`) and stores it in AsyncLocalStorage. Access it anywhere with `responseContext.getStore()`.
+- **📐 Reusable DTOs** — `PaginatedQueryDto` and `CursorPaginatedQueryDto` with `class-validator` decorators for consistent pagination parameters.
+- **📘 Swagger Integration** — `@ApiResponseEnvelope(YourDto)` decorator documents the full `ApiResponse<T>` wrapper shape in your OpenAPI spec.
+- **🔍 Validation Formatter** — `formatValidationErrors()` flattens NestJS `ValidationError[]` into a structured `{ field, constraints, children? }[]` shape.
+- **📘 Fully Typed** — Full TypeScript support with strict mode, typed response envelopes, and filter options.
+
+## 🎯 Use Cases
+
+- Standardising API response format across all MYKO NestJS microservices.
+- Replacing ad-hoc error handling with consistent, typed exception filters.
+- Automatically wrapping all controller responses in a uniform envelope.
+- Tracking request IDs across the entire request lifecycle without manual parameter passing.
+- Handling validation errors with structured field-level error messages.
+- Documenting the `ApiResponse` envelope in Swagger/OpenAPI without manual schema definitions.
+- Building paginated endpoints with reusable, validated query DTOs.
+- Rendering user-friendly error pages for browser-facing requests.
+
+## 🛠️ Tech Stack
+
+- 📘 **TypeScript** (strict mode)
+- 🪺 **NestJS** (optional: `@nestjs/swagger` for OpenAPI decorator)
+- 🚂 **Express**
+
+## ⚡ Quick Start
+
+### Installation
+
+```bash
+npm install @myko.pk/response
+
+# Optional — for paginated DTOs
+npm install class-validator class-transformer
+
+# Optional — for Swagger decorator
+npm install @nestjs/swagger
+```
+
+### Response Builder
+
+```ts
+import { ResponseBuilder } from '@myko.pk/response';
+
+// Success response
+ResponseBuilder.success(data, 'User fetched', 200, requestId);
+ResponseBuilder.created(newUser);                    // 201
+ResponseBuilder.ok('Operation completed');            // 200, no data
+ResponseBuilder.noContent('Item deleted');            // 204
+
+// Error response
+ResponseBuilder.error('User not found', 'USER_NOT_FOUND', 404, 'User ID: 123', requestId);
+
+// Offset pagination
+ResponseBuilder.paginated(items, total, page, limit);
+
+// Cursor pagination (infinite scroll / load more)
+ResponseBuilder.cursorPaginated(items, total, nextCursor, hasNextPage, limit);
+```
+
+### Module Registration
+
+```ts
+import { Module } from '@nestjs/common';
+import { ResponseModule } from '@myko.pk/response';
+
+@Module({
+  imports: [
+    ResponseModule.forRoot({
+      filters: ['GLOBAL', 'VALIDATION', 'HTTP', 'DATABASE', 'AUTH'],
+      enableResponseWrapper: true,     // auto-wrap controller returns
+      enableRequestContext: true,       // auto-track requestId via AsyncLocalStorage
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Decorators
+
+```ts
+import { SkipResponseWrapper, ResponseMessage } from '@myko.pk/response';
+
+@SkipResponseWrapper()              // skip auto-wrapping for this route
+@ResponseMessage('Users fetched')   // override default "Success" message
+@Get('/users')
+getUsers() { ... }
+```
+
+### Swagger
+
+```ts
+import { ApiResponseEnvelope } from '@myko.pk/response';
+import { UserDto } from './user.dto';
+
+@Get('/users')
+@ApiResponseEnvelope(UserDto)       // documents ApiResponse<UserDto> in OpenAPI
+getUsers() { ... }
+```
+
+### Paginated DTOs
+
+```ts
+import { PaginatedQueryDto, CursorPaginatedQueryDto } from '@myko.pk/response';
+
+@Get('/users')
+async getUsers(@Query() query: PaginatedQueryDto) {
+  // query.page  -> number (default 1)
+  // query.limit -> number (default 20, max 100)
+}
+```
+
+### Request Context (AsyncLocalStorage)
+
+```ts
+import { responseContext } from '@myko.pk/response';
+
+// Inside any service (after RequestContextInterceptor has run)
+const ctx = responseContext.getStore();
+console.log(ctx?.requestId);   // "abc-123"
+console.log(ctx?.path);        // "/api/users"
+console.log(ctx?.method);      // "GET"
+```
+
+## 🚀 Available Scripts
+
+- **build** — `npm run build` (tsup → CJS + ESM + DTS, copies views/)
+- **dev** — `npm run dev` (tsup --watch)
+- **typecheck** — `npm run typecheck` (tsc --noEmit)
+
+## 📁 Project Structure
+
+```
+.
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── SECURITY.md
+├── package.json
+├── docs/
+│   ├── README.md
+│   └── QUICK-START.md
+├── src
+│   ├── builders
+│   │   └── response.builder.ts
+│   ├── decorators
+│   │   ├── skip-response-wrapper.decorator.ts
+│   │   └── response-message.decorator.ts
+│   ├── dto
+│   │   └── paginated-query.dto.ts
+│   ├── filters
+│   │   ├── auth.filter.ts
+│   │   ├── database.filter.ts
+│   │   ├── global-exception.filter.ts
+│   │   ├── http-exception.filter.ts
+│   │   └── validation.filter.ts
+│   ├── interceptors
+│   │   ├── response.interceptor.ts
+│   ├── request-context
+│   │   ├── request-context.interceptor.ts
+│   ├── swagger
+│   │   └── api-response-envelope.decorator.ts
+│   ├── validation
+│   │   └── validation-formatter.ts
+│   ├── index.ts
+│   ├── response.constants.ts
+│   ├── response.context.ts
+│   ├── response.module.ts
+│   ├── types.ts
+│   └── views-path.ts
+├── tsconfig.json
+├── tsup.config.mjs
+└── views
+    └── error.hbs
+```
+
+## 🛠️ Development Setup
+
+1. Install Node.js (v18+ recommended)
+2. Install dependencies: `npm install`
+3. Build: `npm run build`
+
+> **Note:** This package does not currently have tests. Tests will be added in a future release.
+
+## 👥 Contributors
+
+<p align="left">
+<a href="https://github.com/arsalanwahab" title="arsalanwahab"><img src="https://avatars.githubusercontent.com/u/178069156?v=4&s=64" width="64" height="64" alt="arsalanwahab" style="border-radius:50%" /></a>
+</p>
+
+[See the full list of contributors →](https://github.com/mykopk/response/graphs/contributors)
+
+## 👥 Contributing
+
+Contributions are welcome! Here's the standard flow:
+
+1. **Fork** the repository
+2. **Clone** your fork: `git clone https://github.com/mykopk/response.git`
+3. **Branch**: `git checkout -b feature/your-feature`
+4. **Commit**: `git commit -m 'feat: add some feature'`
+5. **Push**: `git push origin feature/your-feature`
+6. **Open** a pull request
+
+Please follow the existing code style and include tests for new behavior where applicable.
+
+## 📜 License
+
+This project is licensed under the **MIT** License.
+
+
+MYKO Pakistan
+
+Detail	Information
+Website	myko.pk
+Email	support@myko.pk
+About	Building digital infrastructure and super-app experiences for millions of users across Pakistan.
+Built with ❤️ in Pakistan 🇵🇰

package/dist/builders/response.builder.cjs

@@ -0,0 +1,315 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/response.constants.ts
+var HTTP_STATUS = {
+  OK: 200,
+  CREATED: 201,
+  ACCEPTED: 202,
+  NO_CONTENT: 204,
+  MULTI_STATUS: 207,
+  FOUND: 302,
+  BAD_REQUEST: 400
+};
+var RESPONSE_MESSAGES = {
+  SUCCESS: "Success",
+  CREATED: "Created successfully",
+  ACCEPTED: "Request accepted",
+  NO_CONTENT: "No content",
+  UPDATED: "Updated successfully",
+  DELETED: "Deleted successfully",
+  PARTIAL_SUCCESS: "Partially successful",
+  REDIRECTING: "Redirecting",
+  FILE_READY: "File ready for download"
+};
+
+// src/builders/response.builder.ts
+var ResponseBuilder = class {
+  static {
+    __name(this, "ResponseBuilder");
+  }
+  /**
+   * Build a success response
+   * @template T - Type of response data
+   * @param data - Response data
+   * @param message - Success message
+   * @param statusCode - HTTP status code
+   * @param requestId - Request tracking ID for correlation
+   * @returns ApiResponse with success data
+   */
+  static success(data, message = RESPONSE_MESSAGES.SUCCESS, statusCode = HTTP_STATUS.OK, requestId) {
+    return {
+      success: true,
+      statusCode,
+      message,
+      data,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+  /**
+   * Shorthand success response with no data payload (e.g. status-only endpoints)
+   * @param message - Success message
+   * @param statusCode - HTTP status code
+   * @param requestId - Request tracking ID for correlation
+   * @returns ApiResponse with no data field
+   */
+  static ok(message = RESPONSE_MESSAGES.SUCCESS, statusCode = HTTP_STATUS.OK, requestId) {
+    return {
+      success: true,
+      statusCode,
+      message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+  /**
+   * Build an error response
+   * @param message - Error message
+   * @param code - Error code for categorization
+   * @param statusCode - HTTP status code
+   * @param details - Additional error details
+   * @param requestId - Request tracking ID for correlation
+   * @returns ApiResponse with error information
+   */
+  static error(message, code, statusCode = HTTP_STATUS.BAD_REQUEST, details, requestId) {
+    return {
+      success: false,
+      statusCode,
+      message,
+      error: {
+        code,
+        details
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+  /**
+   * Build a paginated response
+   * @template T - Type of array items
+   * @param data - Array of items
+   * @param total - Total number of items available
+   * @param page - Current page number
+   * @param limit - Items per page
+   * @param message - Success message
+   * @param statusCode - HTTP status code
+   * @param requestId - Request tracking ID for correlation
+   * @returns PaginatedResponse with pagination metadata
+   */
+  static paginated(data, total, page, limit, message = RESPONSE_MESSAGES.SUCCESS, statusCode = HTTP_STATUS.OK, requestId) {
+    const pages = Math.ceil(total / limit);
+    return {
+      success: true,
+      statusCode,
+      message,
+      data,
+      pagination: {
+        total,
+        page,
+        limit,
+        pages
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+  /**
+   * Build a cursor-based paginated response for infinite-scroll / "load more" patterns
+   * @template T - Type of array items
+   * @param data - Array of items for the current page
+   * @param total - Total number of items available
+   * @param nextCursor - Cursor string for the next page
+   * @param hasNextPage - Whether more items exist after this page
+   * @param limit - Items per page
+   * @param message - Success message
+   * @param statusCode - HTTP status code
+   * @param requestId - Request tracking ID for correlation
+   * @returns CursorPaginatedResponse with cursor metadata
+   */
+  static cursorPaginated(data, total, nextCursor, hasNextPage, limit, previousCursor, hasPreviousPage, message = RESPONSE_MESSAGES.SUCCESS, statusCode = HTTP_STATUS.OK, requestId) {
+    return {
+      success: true,
+      statusCode,
+      message,
+      data,
+      pagination: {
+        total,
+        nextCursor,
+        previousCursor,
+        hasNextPage,
+        hasPreviousPage: hasPreviousPage ?? false,
+        limit
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+  /**
+   * Build a created (201) response
+   * @template T - Type of response data
+   * @param data - Created resource data
+   * @param message - Success message
+   * @param requestId - Request tracking ID for correlation
+   * @returns ApiResponse with 201 status code
+   */
+  static created(data, message = RESPONSE_MESSAGES.CREATED, requestId) {
+    return this.success(data, message, HTTP_STATUS.CREATED, requestId);
+  }
+  /**
+   * Build an accepted (202) response for async operations
+   * @template T - Type of response data
+   * @param data - Response data (optional)
+   * @param message - Success message
+   * @param requestId - Request tracking ID for correlation
+   * @returns ApiResponse with 202 status code
+   */
+  static accepted(data, message = RESPONSE_MESSAGES.ACCEPTED, requestId) {
+    return this.success(data, message, HTTP_STATUS.ACCEPTED, requestId);
+  }
+  /**
+   * Build a no content (204) response
+   * @param message - Success message
+   * @param requestId - Request tracking ID for correlation
+   * @returns ApiResponse with 204 status code
+   */
+  static noContent(message = RESPONSE_MESSAGES.NO_CONTENT, requestId) {
+    return {
+      success: true,
+      statusCode: HTTP_STATUS.NO_CONTENT,
+      message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+  /**
+   * Response for successful update operations
+   * @param data - Updated resource data
+   * @param message - Success message
+   * @param requestId - Request tracking ID
+   */
+  static updated(data, message = RESPONSE_MESSAGES.UPDATED, requestId) {
+    return this.success(data, message, HTTP_STATUS.OK, requestId);
+  }
+  /**
+   * Response for successful delete operations
+   * @param message - Success message
+   * @param requestId - Request tracking ID
+   */
+  static deleted(message = RESPONSE_MESSAGES.DELETED, requestId) {
+    return {
+      success: true,
+      statusCode: HTTP_STATUS.OK,
+      message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+  /**
+   * Response for bulk operations (create, update, delete multiple)
+   * @param succeeded - Number of successful operations
+   * @param failed - Number of failed operations
+   * @param total - Total operations attempted
+   * @param requestId - Request tracking ID
+   */
+  static bulkOperation(succeeded, failed, total, requestId) {
+    const message = failed === 0 ? `All ${total} operations completed successfully` : `${succeeded} succeeded, ${failed} failed out of ${total} operations`;
+    return {
+      success: failed === 0,
+      statusCode: failed === 0 ? HTTP_STATUS.OK : HTTP_STATUS.MULTI_STATUS,
+      message,
+      data: {
+        succeeded,
+        failed,
+        total
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+  /**
+   * Response for partial success scenarios
+   * @param data - Partial data that was processed
+   * @param message - Message describing the partial success
+   * @param requestId - Request tracking ID
+   */
+  static partialSuccess(data, message = RESPONSE_MESSAGES.PARTIAL_SUCCESS, requestId) {
+    return {
+      success: true,
+      statusCode: HTTP_STATUS.MULTI_STATUS,
+      message,
+      data,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+  /**
+   * Response for redirect operations
+   * @param url - Redirect URL
+   * @param statusCode - HTTP status code (301, 302, 307, 308)
+   * @param message - Redirect message
+   * @param requestId - Request tracking ID
+   */
+  static redirect(url, statusCode = HTTP_STATUS.FOUND, message = RESPONSE_MESSAGES.REDIRECTING, requestId) {
+    return {
+      success: true,
+      statusCode,
+      message,
+      data: { url },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+  /**
+   * Response for file download operations
+   * @param filename - Name of the file being downloaded
+   * @param size - File size in bytes
+   * @param mimeType - MIME type of the file
+   * @param requestId - Request tracking ID
+   */
+  static fileDownload(filename, size, mimeType, requestId) {
+    return {
+      success: true,
+      statusCode: HTTP_STATUS.OK,
+      message: RESPONSE_MESSAGES.FILE_READY,
+      data: {
+        filename,
+        size,
+        mimeType
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+  /**
+   * Response for import/export operations
+   * @param processed - Number of records processed
+   * @param imported - Number of records imported
+   * @param skipped - Number of records skipped
+   * @param errors - Array of error messages
+   * @param requestId - Request tracking ID
+   */
+  static importExport(processed, imported, skipped, errors = [], requestId) {
+    const hasErrors = errors.length > 0;
+    const message = hasErrors ? `Imported ${imported} records with ${errors.length} errors` : `Successfully imported ${imported} records`;
+    return {
+      success: !hasErrors,
+      statusCode: hasErrors ? HTTP_STATUS.MULTI_STATUS : HTTP_STATUS.OK,
+      message,
+      data: {
+        processed,
+        imported,
+        skipped,
+        errors: hasErrors ? errors : void 0
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      requestId
+    };
+  }
+};
+
+exports.ResponseBuilder = ResponseBuilder;
+//# sourceMappingURL=response.builder.cjs.map
+//# sourceMappingURL=response.builder.cjs.map

package/dist/builders/response.builder.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/response.constants.ts","../../src/builders/response.builder.ts"],"names":[],"mappings":"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","file":"response.builder.cjs","sourcesContent":["export const RESPONSE_FILTERS = {\n  GLOBAL: 'global',\n  VALIDATION: 'validation',\n  HTTP: 'http',\n  DATABASE: 'database',\n  AUTH: 'auth',\n} as const;\n\nexport const HTTP_STATUS = {\n  OK: 200,\n  CREATED: 201,\n  ACCEPTED: 202,\n  NO_CONTENT: 204,\n  MULTI_STATUS: 207,\n  FOUND: 302,\n  BAD_REQUEST: 400,\n} as const;\n\nexport const RESPONSE_MESSAGES = {\n  SUCCESS: 'Success',\n  CREATED: 'Created successfully',\n  ACCEPTED: 'Request accepted',\n  NO_CONTENT: 'No content',\n  UPDATED: 'Updated successfully',\n  DELETED: 'Deleted successfully',\n  PARTIAL_SUCCESS: 'Partially successful',\n  REDIRECTING: 'Redirecting',\n  FILE_READY: 'File ready for download',\n} as const;\n","import { ApiResponse, PaginatedResponse, CursorPaginatedResponse } from '../types';\nimport { HTTP_STATUS, RESPONSE_MESSAGES } from '../response.constants';\nimport { responseContext } from '../response.context';\n\nexport class ResponseBuilder {\n  /**\n   * Build a success response\n   * @template T - Type of response data\n   * @param data - Response data\n   * @param message - Success message\n   * @param statusCode - HTTP status code\n   * @param requestId - Request tracking ID for correlation\n   * @returns ApiResponse with success data\n   */\n  static success<T = any>(\n    data: T,\n    message: string = RESPONSE_MESSAGES.SUCCESS,\n    statusCode: number = HTTP_STATUS.OK,\n    requestId?: string\n  ): ApiResponse<T> {\n    return {\n      success: true,\n      statusCode,\n      message,\n      data,\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n\n  /**\n   * Shorthand success response with no data payload (e.g. status-only endpoints)\n   * @param message - Success message\n   * @param statusCode - HTTP status code\n   * @param requestId - Request tracking ID for correlation\n   * @returns ApiResponse with no data field\n   */\n  static ok(\n    message: string = RESPONSE_MESSAGES.SUCCESS,\n    statusCode: number = HTTP_STATUS.OK,\n    requestId?: string\n  ): ApiResponse {\n    return {\n      success: true,\n      statusCode,\n      message,\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n\n  /**\n   * Build an error response\n   * @param message - Error message\n   * @param code - Error code for categorization\n   * @param statusCode - HTTP status code\n   * @param details - Additional error details\n   * @param requestId - Request tracking ID for correlation\n   * @returns ApiResponse with error information\n   */\n  static error(\n    message: string,\n    code: string,\n    statusCode: number = HTTP_STATUS.BAD_REQUEST,\n    details?: string,\n    requestId?: string\n  ): ApiResponse {\n    return {\n      success: false,\n      statusCode,\n      message,\n      error: {\n        code,\n        details,\n      },\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n\n  /**\n   * Build a paginated response\n   * @template T - Type of array items\n   * @param data - Array of items\n   * @param total - Total number of items available\n   * @param page - Current page number\n   * @param limit - Items per page\n   * @param message - Success message\n   * @param statusCode - HTTP status code\n   * @param requestId - Request tracking ID for correlation\n   * @returns PaginatedResponse with pagination metadata\n   */\n  static paginated<T = any>(\n    data: T[],\n    total: number,\n    page: number,\n    limit: number,\n    message: string = RESPONSE_MESSAGES.SUCCESS,\n    statusCode: number = HTTP_STATUS.OK,\n    requestId?: string\n  ): PaginatedResponse<T> {\n    const pages = Math.ceil(total / limit);\n    return {\n      success: true,\n      statusCode,\n      message,\n      data,\n      pagination: {\n        total,\n        page,\n        limit,\n        pages,\n      },\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n\n  /**\n   * Build a cursor-based paginated response for infinite-scroll / \"load more\" patterns\n   * @template T - Type of array items\n   * @param data - Array of items for the current page\n   * @param total - Total number of items available\n   * @param nextCursor - Cursor string for the next page\n   * @param hasNextPage - Whether more items exist after this page\n   * @param limit - Items per page\n   * @param message - Success message\n   * @param statusCode - HTTP status code\n   * @param requestId - Request tracking ID for correlation\n   * @returns CursorPaginatedResponse with cursor metadata\n   */\n  static cursorPaginated<T = any>(\n    data: T[],\n    total: number,\n    nextCursor: string | undefined,\n    hasNextPage: boolean,\n    limit: number,\n    previousCursor?: string,\n    hasPreviousPage?: boolean,\n    message: string = RESPONSE_MESSAGES.SUCCESS,\n    statusCode: number = HTTP_STATUS.OK,\n    requestId?: string\n  ): CursorPaginatedResponse<T> {\n    return {\n      success: true,\n      statusCode,\n      message,\n      data,\n      pagination: {\n        total,\n        nextCursor,\n        previousCursor,\n        hasNextPage,\n        hasPreviousPage: hasPreviousPage ?? false,\n        limit,\n      },\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n\n  /**\n   * Build a created (201) response\n   * @template T - Type of response data\n   * @param data - Created resource data\n   * @param message - Success message\n   * @param requestId - Request tracking ID for correlation\n   * @returns ApiResponse with 201 status code\n   */\n  static created<T = any>(\n    data: T,\n    message: string = RESPONSE_MESSAGES.CREATED,\n    requestId?: string\n  ): ApiResponse<T> {\n    return this.success(data, message, HTTP_STATUS.CREATED, requestId);\n  }\n\n  /**\n   * Build an accepted (202) response for async operations\n   * @template T - Type of response data\n   * @param data - Response data (optional)\n   * @param message - Success message\n   * @param requestId - Request tracking ID for correlation\n   * @returns ApiResponse with 202 status code\n   */\n  static accepted<T = any>(\n    data: T,\n    message: string = RESPONSE_MESSAGES.ACCEPTED,\n    requestId?: string\n  ): ApiResponse<T> {\n    return this.success(data, message, HTTP_STATUS.ACCEPTED, requestId);\n  }\n\n  /**\n   * Build a no content (204) response\n   * @param message - Success message\n   * @param requestId - Request tracking ID for correlation\n   * @returns ApiResponse with 204 status code\n   */\n  static noContent(\n    message: string = RESPONSE_MESSAGES.NO_CONTENT,\n    requestId?: string\n  ): ApiResponse {\n    return {\n      success: true,\n      statusCode: HTTP_STATUS.NO_CONTENT,\n      message,\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n\n  /**\n   * Response for successful update operations\n   * @param data - Updated resource data\n   * @param message - Success message\n   * @param requestId - Request tracking ID\n   */\n  static updated<T = any>(\n    data: T,\n    message: string = RESPONSE_MESSAGES.UPDATED,\n    requestId?: string\n  ): ApiResponse<T> {\n    return this.success(data, message, HTTP_STATUS.OK, requestId);\n  }\n\n  /**\n   * Response for successful delete operations\n   * @param message - Success message\n   * @param requestId - Request tracking ID\n   */\n  static deleted(\n    message: string = RESPONSE_MESSAGES.DELETED,\n    requestId?: string\n  ): ApiResponse {\n    return {\n      success: true,\n      statusCode: HTTP_STATUS.OK,\n      message,\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n\n  /**\n   * Response for bulk operations (create, update, delete multiple)\n   * @param succeeded - Number of successful operations\n   * @param failed - Number of failed operations\n   * @param total - Total operations attempted\n   * @param requestId - Request tracking ID\n   */\n  static bulkOperation(\n    succeeded: number,\n    failed: number,\n    total: number,\n    requestId?: string\n  ): ApiResponse {\n    const message = failed === 0\n      ? `All ${total} operations completed successfully`\n      : `${succeeded} succeeded, ${failed} failed out of ${total} operations`;\n\n    return {\n      success: failed === 0,\n      statusCode: failed === 0 ? HTTP_STATUS.OK : HTTP_STATUS.MULTI_STATUS,\n      message,\n      data: {\n        succeeded,\n        failed,\n        total,\n      },\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n\n  /**\n   * Response for partial success scenarios\n   * @param data - Partial data that was processed\n   * @param message - Message describing the partial success\n   * @param requestId - Request tracking ID\n   */\n  static partialSuccess<T = any>(\n    data: T,\n    message: string = RESPONSE_MESSAGES.PARTIAL_SUCCESS,\n    requestId?: string\n  ): ApiResponse<T> {\n    return {\n      success: true,\n      statusCode: HTTP_STATUS.MULTI_STATUS,\n      message,\n      data,\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n\n  /**\n   * Response for redirect operations\n   * @param url - Redirect URL\n   * @param statusCode - HTTP status code (301, 302, 307, 308)\n   * @param message - Redirect message\n   * @param requestId - Request tracking ID\n   */\n  static redirect(\n    url: string,\n    statusCode: number = HTTP_STATUS.FOUND,\n    message: string = RESPONSE_MESSAGES.REDIRECTING,\n    requestId?: string\n  ): ApiResponse {\n    return {\n      success: true,\n      statusCode,\n      message,\n      data: { url },\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n\n  /**\n   * Response for file download operations\n   * @param filename - Name of the file being downloaded\n   * @param size - File size in bytes\n   * @param mimeType - MIME type of the file\n   * @param requestId - Request tracking ID\n   */\n  static fileDownload(\n    filename: string,\n    size: number,\n    mimeType: string,\n    requestId?: string\n  ): ApiResponse {\n    return {\n      success: true,\n      statusCode: HTTP_STATUS.OK,\n      message: RESPONSE_MESSAGES.FILE_READY,\n      data: {\n        filename,\n        size,\n        mimeType,\n      },\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n\n  /**\n   * Response for import/export operations\n   * @param processed - Number of records processed\n   * @param imported - Number of records imported\n   * @param skipped - Number of records skipped\n   * @param errors - Array of error messages\n   * @param requestId - Request tracking ID\n   */\n  static importExport(\n    processed: number,\n    imported: number,\n    skipped: number,\n    errors: string[] = [],\n    requestId?: string\n  ): ApiResponse {\n    const hasErrors = errors.length > 0;\n    const message = hasErrors\n      ? `Imported ${imported} records with ${errors.length} errors`\n      : `Successfully imported ${imported} records`;\n\n    return {\n      success: !hasErrors,\n      statusCode: hasErrors ? HTTP_STATUS.MULTI_STATUS : HTTP_STATUS.OK,\n      message,\n      data: {\n        processed,\n        imported,\n        skipped,\n        errors: hasErrors ? errors : undefined,\n      },\n      timestamp: new Date().toISOString(),\n      requestId,\n    };\n  }\n}\n"]}

package/dist/builders/response.builder.d.cts

@@ -0,0 +1 @@
+export { R as ResponseBuilder } from '../response.builder-BX9d7Taz.cjs';

package/dist/builders/response.builder.d.ts

@@ -0,0 +1 @@
+export { R as ResponseBuilder } from '../response.builder-BX9d7Taz.js';