http-response-kit 1.0.0 → 1.1.0

package/README.md

@@ -37,17 +37,22 @@ throw HttpError.unauthorized('Token expired');
 throw new HttpError(404, { message: 'User not found' });
 throw new HttpError(429, { message: 'Slow down!', retryAfter: 60 });
 
-// Format success responses
-const response = HttpResponse.success({
+// Format success responses using Generics for typesafety
+interface User {
+  id: number;
+  name: string;
+}
+
+const response = HttpResponse.success<User>({
   data: { id: 1, name: 'John' },
   message: 'User retrieved successfully'
 });
-// { success: true, status_code: 200, data: {...}, message: '...' }
+// { success: true, status_code: 200, data: User, message: '...' }
 
 // Format error responses
 const error = HttpError.notFound('User not found');
 const errorResponse = HttpResponse.error(error);
-// { success: false, status_code: 404, error: { type: 'not_found', ... } }
+// { success: false, status_code: 404, error: { type: 'not_found', message: '...', details: '...', ... } }
 ```
 
 ## Usage with Express
@@ -87,7 +92,7 @@ app.use((err, req, res, next) => {
 
 ## API Reference
 
-### HttpSuccessCode (1xx Informational)
+### HttpInfoCode (1xx Informational)
 
 | Enum | Code | Description |
 |------|------|-------------|
@@ -180,6 +185,10 @@ app.use((err, req, res, next) => {
 #### Utility Methods
 
 ```typescript
+// Create error from status code (semantic alias for new HttpError(code))
+const error = HttpError.fromStatus(503);
+const errorWithMsg = HttpError.fromStatus(404, { message: 'Not here' });
+
 // Convert any error to HttpError
 const httpError = HttpError.fromError(unknownError);
 
@@ -199,16 +208,16 @@ throw HttpError.badRequest('Validation failed', {
 ### HttpResponse
 
 ```typescript
-// Success responses
-HttpResponse.success({ data, message, statusCode, metadata });
-HttpResponse.ok(data, message);
-HttpResponse.created(data, message);
-HttpResponse.accepted(data, message);
+// Success responses using Generics for Type Safety
+HttpResponse.success<User>({ data, message, statusCode, metadata });
+HttpResponse.ok<User>(data, message);
+HttpResponse.created<User>(data, message);
+HttpResponse.accepted<User>(data, message);
 HttpResponse.noContent();
 
 // Error responses
-HttpResponse.error(httpError);
-HttpResponse.fromError(anyError);
+HttpResponse.error(httpError, { includeStack: true });
+HttpResponse.fromError(anyError, { fallbackCode: 503 });
 
 // Paginated responses
 HttpResponse.paginated(items, {
@@ -224,7 +233,7 @@ HttpResponse.paginated(items, {
 import { configure } from 'http-response-kit';
 
 configure({
-  // Enable stack traces in error responses
+  // Enable stack traces in error responses (auto-detects from NODE_ENV if omitted)
   isDevelopment: true,
   
   // Include timestamps in all responses
@@ -234,7 +243,7 @@ configure({
   customMessages: {
     404: 'Oops! This page went on vacation 🏝️',
     500: 'Well, this is embarrassing... 🤖'
-  },
+  },  // Note: multiple configure() calls are incrementally merged
   
   // Custom response transformer
   responseTransformer: (response) => ({

package/dist/index.d.mts

@@ -44,9 +44,9 @@ interface HttpSuccessInfo {
 /**
  * Configuration for success responses
  */
-interface SuccessResponseConfig {
+interface SuccessResponseConfig<T = unknown> {
     /** Response data payload */
-    data?: unknown;
+    data?: T;
     /** Custom success message */
     message?: string;
     /** HTTP status code (default: 200) */
@@ -62,6 +62,8 @@ interface ErrorResponseConfig {
     includeStack?: boolean;
     /** Additional fields to include */
     additionalFields?: Record<string, unknown>;
+    /** Fallback status code for unknown errors */
+    fallbackCode?: number;
 }
 /**
  * Global library configuration
@@ -77,33 +79,63 @@ interface LibraryConfig {
     responseTransformer?: (response: Record<string, unknown>) => Record<string, unknown>;
 }
 /**
- * Standard success response structure
+ * Standard success response structure.
+ * The index signature `[key: string]: unknown` allows additional fields via
+ * `additionalFields`, but extra properties will be typed as `unknown` at compile time.
  */
-interface SuccessResponse {
+interface SuccessResponse<T = unknown> {
     success: true;
     status_code: number;
     timestamp?: string;
-    data?: unknown;
+    data?: T;
     message?: string;
     metadata?: Record<string, unknown>;
     [key: string]: unknown;
 }
 /**
- * Standard error response structure
+ * Standard error response structure.
+ * The index signature `[key: string]: unknown` allows additional fields via
+ * `additionalFields`, but extra properties will be typed as `unknown` at compile time.
  */
 interface ErrorResponse {
     success: false;
     status_code: number;
     timestamp?: string;
+    retry_after?: number;
     error: {
         type: string;
         title: string;
         message: string;
         details?: string;
+        stack?: string;
     };
     metadata?: Record<string, unknown>;
     [key: string]: unknown;
 }
+/**
+ * Input parameters for paginated responses
+ */
+interface PaginationInput {
+    /** Current page number */
+    page: number;
+    /** Items per page */
+    limit: number;
+    /** Total number of items */
+    total: number;
+    /** Optional pre-computed total pages (overrides auto-calculation) */
+    totalPages?: number;
+}
+/**
+ * Pagination metadata included in paginated responses
+ */
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    total_pages: number;
+    has_next: boolean;
+    has_prev: boolean;
+}
 
 /**
  * HTTP Response Kit - Status Code Enums
@@ -318,6 +350,8 @@ declare class HttpError extends Error {
     readonly type: string;
     /** Human-readable error title */
     readonly title: string;
+    /** Default error description from definition */
+    readonly details: string;
     /** Additional error metadata */
     readonly metadata?: Record<string, unknown>;
     /** Original error cause */
@@ -330,7 +364,7 @@ declare class HttpError extends Error {
      * @param code - HTTP status code (e.g., 404, 500)
      * @param options - Optional configuration
      */
-    constructor(code: number, options?: HttpErrorOptions);
+    constructor(code: HttpClientErrorCode | HttpServerErrorCode | number, options?: HttpErrorOptions);
     /**
      * Convert error to plain object for JSON serialization
      */
@@ -417,6 +451,11 @@ declare class HttpError extends Error {
     static notExtended(message?: string, metadata?: Record<string, unknown>): HttpError;
     /** 511 Network Authentication Required */
     static networkAuthenticationRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /**
+     * Create an HttpError from a status code with default definition values.
+     * Semantic alias for `new HttpError(code)`.
+     */
+    static fromStatus(code: HttpClientErrorCode | HttpServerErrorCode | number, options?: HttpErrorOptions): HttpError;
     /**
      * Create an HttpError from an unknown error
      */
@@ -477,7 +516,7 @@ declare class HttpResponse {
      * @param config - Success response configuration
      * @returns Formatted success response object
      */
-    static success(config?: SuccessResponseConfig): SuccessResponse;
+    static success<T = unknown>(config?: SuccessResponseConfig<T>): SuccessResponse<T>;
     /**
      * Format an error response
      *
@@ -495,17 +534,17 @@ declare class HttpResponse {
      */
     static fromError(error: unknown, config?: ErrorResponseConfig): ErrorResponse;
     /** 200 OK */
-    static ok(data?: unknown, message?: string): SuccessResponse;
+    static ok<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
     /** 201 Created */
-    static created(data?: unknown, message?: string): SuccessResponse;
+    static created<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
     /** 202 Accepted */
-    static accepted(data?: unknown, message?: string): SuccessResponse;
+    static accepted<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
     /** 204 No Content */
-    static noContent(): SuccessResponse;
+    static noContent(): SuccessResponse<never>;
     /** 206 Partial Content */
-    static partialContent(data?: unknown, message?: string): SuccessResponse;
-    /** 304 Not Modified */
-    static notModified(): SuccessResponse;
+    static partialContent<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
+    /** 304 Not Modified — Note: 304 is a 3xx redirect code, included here as a convenience method */
+    static notModified(): SuccessResponse<never>;
     /**
      * Check if a response is a success response
      */
@@ -517,12 +556,7 @@ declare class HttpResponse {
     /**
      * Create a paginated success response
      */
-    static paginated(data: unknown[], pagination: {
-        page: number;
-        limit: number;
-        total: number;
-        totalPages?: number;
-    }, message?: string): SuccessResponse;
+    static paginated<T = unknown>(data: T[], pagination: PaginationInput, message?: string): SuccessResponse<T[]>;
 }
 
 /**
@@ -551,7 +585,7 @@ declare function configure(config: Partial<LibraryConfig>): void;
 /**
  * Get the current library configuration
  */
-declare function getConfig(): LibraryConfig;
+declare function getConfig(): Readonly<LibraryConfig>;
 /**
  * Reset configuration to defaults
  */
@@ -561,4 +595,4 @@ declare function resetConfig(): void;
  */
 declare function isDevelopment(): boolean;
 
-export { type ErrorResponse, type ErrorResponseConfig, HttpClientErrorCode, HttpError, HttpErrorCode, HttpErrorDefinitions, type HttpErrorInfo, type HttpErrorOptions, HttpInfoCode, HttpInfoDefinitions, HttpRedirectCode, HttpRedirectDefinitions, HttpResponse, HttpServerErrorCode, HttpSuccessCode, HttpSuccessDefinitions, type HttpSuccessInfo, type LibraryConfig, type SuccessResponse, type SuccessResponseConfig, configure, getConfig, getErrorDefinition, getSuccessDefinition, isDevelopment, resetConfig };
+export { type ErrorResponse, type ErrorResponseConfig, HttpClientErrorCode, HttpError, HttpErrorCode, HttpErrorDefinitions, type HttpErrorInfo, type HttpErrorOptions, HttpInfoCode, HttpInfoDefinitions, HttpRedirectCode, HttpRedirectDefinitions, HttpResponse, HttpServerErrorCode, HttpSuccessCode, HttpSuccessDefinitions, type HttpSuccessInfo, type LibraryConfig, type PaginationInput, type PaginationMeta, type SuccessResponse, type SuccessResponseConfig, configure, getConfig, getErrorDefinition, getSuccessDefinition, isDevelopment, resetConfig };

package/dist/index.d.ts

@@ -44,9 +44,9 @@ interface HttpSuccessInfo {
 /**
  * Configuration for success responses
  */
-interface SuccessResponseConfig {
+interface SuccessResponseConfig<T = unknown> {
     /** Response data payload */
-    data?: unknown;
+    data?: T;
     /** Custom success message */
     message?: string;
     /** HTTP status code (default: 200) */
@@ -62,6 +62,8 @@ interface ErrorResponseConfig {
     includeStack?: boolean;
     /** Additional fields to include */
     additionalFields?: Record<string, unknown>;
+    /** Fallback status code for unknown errors */
+    fallbackCode?: number;
 }
 /**
  * Global library configuration
@@ -77,33 +79,63 @@ interface LibraryConfig {
     responseTransformer?: (response: Record<string, unknown>) => Record<string, unknown>;
 }
 /**
- * Standard success response structure
+ * Standard success response structure.
+ * The index signature `[key: string]: unknown` allows additional fields via
+ * `additionalFields`, but extra properties will be typed as `unknown` at compile time.
  */
-interface SuccessResponse {
+interface SuccessResponse<T = unknown> {
     success: true;
     status_code: number;
     timestamp?: string;
-    data?: unknown;
+    data?: T;
     message?: string;
     metadata?: Record<string, unknown>;
     [key: string]: unknown;
 }
 /**
- * Standard error response structure
+ * Standard error response structure.
+ * The index signature `[key: string]: unknown` allows additional fields via
+ * `additionalFields`, but extra properties will be typed as `unknown` at compile time.
  */
 interface ErrorResponse {
     success: false;
     status_code: number;
     timestamp?: string;
+    retry_after?: number;
     error: {
         type: string;
         title: string;
         message: string;
         details?: string;
+        stack?: string;
     };
     metadata?: Record<string, unknown>;
     [key: string]: unknown;
 }
+/**
+ * Input parameters for paginated responses
+ */
+interface PaginationInput {
+    /** Current page number */
+    page: number;
+    /** Items per page */
+    limit: number;
+    /** Total number of items */
+    total: number;
+    /** Optional pre-computed total pages (overrides auto-calculation) */
+    totalPages?: number;
+}
+/**
+ * Pagination metadata included in paginated responses
+ */
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    total_pages: number;
+    has_next: boolean;
+    has_prev: boolean;
+}
 
 /**
  * HTTP Response Kit - Status Code Enums
@@ -318,6 +350,8 @@ declare class HttpError extends Error {
     readonly type: string;
     /** Human-readable error title */
     readonly title: string;
+    /** Default error description from definition */
+    readonly details: string;
     /** Additional error metadata */
     readonly metadata?: Record<string, unknown>;
     /** Original error cause */
@@ -330,7 +364,7 @@ declare class HttpError extends Error {
      * @param code - HTTP status code (e.g., 404, 500)
      * @param options - Optional configuration
      */
-    constructor(code: number, options?: HttpErrorOptions);
+    constructor(code: HttpClientErrorCode | HttpServerErrorCode | number, options?: HttpErrorOptions);
     /**
      * Convert error to plain object for JSON serialization
      */
@@ -417,6 +451,11 @@ declare class HttpError extends Error {
     static notExtended(message?: string, metadata?: Record<string, unknown>): HttpError;
     /** 511 Network Authentication Required */
     static networkAuthenticationRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /**
+     * Create an HttpError from a status code with default definition values.
+     * Semantic alias for `new HttpError(code)`.
+     */
+    static fromStatus(code: HttpClientErrorCode | HttpServerErrorCode | number, options?: HttpErrorOptions): HttpError;
     /**
      * Create an HttpError from an unknown error
      */
@@ -477,7 +516,7 @@ declare class HttpResponse {
      * @param config - Success response configuration
      * @returns Formatted success response object
      */
-    static success(config?: SuccessResponseConfig): SuccessResponse;
+    static success<T = unknown>(config?: SuccessResponseConfig<T>): SuccessResponse<T>;
     /**
      * Format an error response
      *
@@ -495,17 +534,17 @@ declare class HttpResponse {
      */
     static fromError(error: unknown, config?: ErrorResponseConfig): ErrorResponse;
     /** 200 OK */
-    static ok(data?: unknown, message?: string): SuccessResponse;
+    static ok<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
     /** 201 Created */
-    static created(data?: unknown, message?: string): SuccessResponse;
+    static created<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
     /** 202 Accepted */
-    static accepted(data?: unknown, message?: string): SuccessResponse;
+    static accepted<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
     /** 204 No Content */
-    static noContent(): SuccessResponse;
+    static noContent(): SuccessResponse<never>;
     /** 206 Partial Content */
-    static partialContent(data?: unknown, message?: string): SuccessResponse;
-    /** 304 Not Modified */
-    static notModified(): SuccessResponse;
+    static partialContent<T = unknown>(data?: T, message?: string): SuccessResponse<T>;
+    /** 304 Not Modified — Note: 304 is a 3xx redirect code, included here as a convenience method */
+    static notModified(): SuccessResponse<never>;
     /**
      * Check if a response is a success response
      */
@@ -517,12 +556,7 @@ declare class HttpResponse {
     /**
      * Create a paginated success response
      */
-    static paginated(data: unknown[], pagination: {
-        page: number;
-        limit: number;
-        total: number;
-        totalPages?: number;
-    }, message?: string): SuccessResponse;
+    static paginated<T = unknown>(data: T[], pagination: PaginationInput, message?: string): SuccessResponse<T[]>;
 }
 
 /**
@@ -551,7 +585,7 @@ declare function configure(config: Partial<LibraryConfig>): void;
 /**
  * Get the current library configuration
  */
-declare function getConfig(): LibraryConfig;
+declare function getConfig(): Readonly<LibraryConfig>;
 /**
  * Reset configuration to defaults
  */
@@ -561,4 +595,4 @@ declare function resetConfig(): void;
  */
 declare function isDevelopment(): boolean;
 
-export { type ErrorResponse, type ErrorResponseConfig, HttpClientErrorCode, HttpError, HttpErrorCode, HttpErrorDefinitions, type HttpErrorInfo, type HttpErrorOptions, HttpInfoCode, HttpInfoDefinitions, HttpRedirectCode, HttpRedirectDefinitions, HttpResponse, HttpServerErrorCode, HttpSuccessCode, HttpSuccessDefinitions, type HttpSuccessInfo, type LibraryConfig, type SuccessResponse, type SuccessResponseConfig, configure, getConfig, getErrorDefinition, getSuccessDefinition, isDevelopment, resetConfig };
+export { type ErrorResponse, type ErrorResponseConfig, HttpClientErrorCode, HttpError, HttpErrorCode, HttpErrorDefinitions, type HttpErrorInfo, type HttpErrorOptions, HttpInfoCode, HttpInfoDefinitions, HttpRedirectCode, HttpRedirectDefinitions, HttpResponse, HttpServerErrorCode, HttpSuccessCode, HttpSuccessDefinitions, type HttpSuccessInfo, type LibraryConfig, type PaginationInput, type PaginationMeta, type SuccessResponse, type SuccessResponseConfig, configure, getConfig, getErrorDefinition, getSuccessDefinition, isDevelopment, resetConfig };

package/dist/index.js

@@ -383,8 +383,23 @@ var HttpErrorDefinitions = {
     details: "The client needs to authenticate to gain network access."
   }
 };
+Object.freeze(HttpErrorDefinitions);
 function getErrorDefinition(code) {
-  return HttpErrorDefinitions[code] || HttpErrorDefinitions[500];
+  if (code < 400 || code > 599) {
+    throw new RangeError(
+      `Invalid HTTP error code: ${code}. Must be between 400 and 599.`
+    );
+  }
+  if (HttpErrorDefinitions[code]) {
+    return HttpErrorDefinitions[code];
+  }
+  const isClientError = code >= 400 && code < 500;
+  return {
+    type: isClientError ? "unknown_client_error" : "unknown_server_error",
+    title: isClientError ? "Unknown Client Error" : "Unknown Server Error",
+    code,
+    details: isClientError ? "An unknown client error occurred." : "An unknown server error occurred."
+  };
 }
 
 // src/constants/success-definitions.ts
@@ -430,6 +445,7 @@ var HttpSuccessDefinitions = {
     description: "The server has fulfilled a GET request and the response is a representation of the result of one or more instance-manipulations."
   }
 };
+Object.freeze(HttpSuccessDefinitions);
 var HttpRedirectDefinitions = {
   [300 /* MULTIPLE_CHOICES */]: {
     code: 300,
@@ -464,6 +480,7 @@ var HttpRedirectDefinitions = {
     description: "The request and all future requests should be repeated using another URI."
   }
 };
+Object.freeze(HttpRedirectDefinitions);
 var HttpInfoDefinitions = {
   [100 /* CONTINUE */]: {
     code: 100,
@@ -482,29 +499,41 @@ var HttpInfoDefinitions = {
     description: "The server is sending some response headers before the final response."
   }
 };
+Object.freeze(HttpInfoDefinitions);
 function getSuccessDefinition(code) {
-  return HttpSuccessDefinitions[code] || HttpRedirectDefinitions[code] || HttpInfoDefinitions[code] || HttpSuccessDefinitions[200];
+  const definedInfo = HttpSuccessDefinitions[code] || HttpRedirectDefinitions[code] || HttpInfoDefinitions[code];
+  if (definedInfo) {
+    return definedInfo;
+  }
+  return {
+    code,
+    description: "The request was processed with a non-standard status code."
+  };
 }
 
 // src/config/index.ts
 var defaultConfig = {
-  isDevelopment: process.env.NODE_ENV === "development",
+  isDevelopment: void 0,
   includeTimestamp: true,
   customMessages: {},
   responseTransformer: void 0
 };
 var currentConfig = { ...defaultConfig };
 function configure(config) {
-  currentConfig = { ...currentConfig, ...config };
+  currentConfig = {
+    ...currentConfig,
+    ...config,
+    customMessages: { ...currentConfig.customMessages, ...config.customMessages }
+  };
 }
 function getConfig() {
   return { ...currentConfig };
 }
 function resetConfig() {
-  currentConfig = { ...defaultConfig };
+  currentConfig = { ...defaultConfig, customMessages: {} };
 }
 function isDevelopment() {
-  return currentConfig.isDevelopment ?? false;
+  return currentConfig.isDevelopment ?? process.env.NODE_ENV === "development";
 }
 function shouldIncludeTimestamp() {
   return currentConfig.includeTimestamp ?? true;
@@ -533,6 +562,7 @@ var HttpError = class _HttpError extends Error {
     this.code = errorInfo.code;
     this.type = errorInfo.type;
     this.title = errorInfo.title;
+    this.details = errorInfo.details;
     this.metadata = options.metadata;
     this.cause = options.cause;
     this.retryAfter = options.retryAfter ?? errorInfo.retryAfter;
@@ -550,6 +580,7 @@ var HttpError = class _HttpError extends Error {
       type: this.type,
       title: this.title,
       message: this.message,
+      details: this.details,
       metadata: this.metadata,
       retryAfter: this.retryAfter
     };
@@ -727,6 +758,13 @@ var HttpError = class _HttpError extends Error {
   // ========================================================================
   // Utility Methods
   // ========================================================================
+  /**
+   * Create an HttpError from a status code with default definition values.
+   * Semantic alias for `new HttpError(code)`.
+   */
+  static fromStatus(code, options) {
+    return new _HttpError(code, options);
+  }
   /**
    * Create an HttpError from an unknown error
    */
@@ -734,6 +772,11 @@ var HttpError = class _HttpError extends Error {
     if (error instanceof _HttpError) {
       return error;
     }
+    if (fallbackCode < 400 || fallbackCode > 599) {
+      throw new RangeError(
+        `fallbackCode must be between 400 and 599, got ${fallbackCode}`
+      );
+    }
     if (error instanceof Error) {
       return new _HttpError(fallbackCode, {
         message: error.message,
@@ -774,7 +817,7 @@ var HttpResponse = class _HttpResponse {
    */
   static success(config = {}) {
     const {
-      data = null,
+      data,
       message,
       statusCode = 200 /* OK */,
       metadata = {}
@@ -787,7 +830,7 @@ var HttpResponse = class _HttpResponse {
     if (shouldIncludeTimestamp()) {
       response.timestamp = (/* @__PURE__ */ new Date()).toISOString();
     }
-    if (statusCode !== 204 /* NO_CONTENT */ && statusCode !== 205 /* RESET_CONTENT */) {
+    if (statusCode !== 204 /* NO_CONTENT */ && statusCode !== 205 /* RESET_CONTENT */ && statusCode !== 304 /* NOT_MODIFIED */) {
       if (data !== null && data !== void 0) {
         response.data = data;
       }
@@ -825,8 +868,11 @@ var HttpResponse = class _HttpResponse {
     if (shouldIncludeTimestamp()) {
       response.timestamp = (/* @__PURE__ */ new Date()).toISOString();
     }
+    if (error.details) {
+      response.error.details = error.details;
+    }
     if (includeStack ?? isDevelopment()) {
-      response.error.details = error.stack;
+      response.error.stack = error.stack;
     }
     if (error.retryAfter) {
       response.retry_after = error.retryAfter;
@@ -835,7 +881,8 @@ var HttpResponse = class _HttpResponse {
       response.metadata = error.metadata;
     }
     if (additionalFields) {
-      Object.assign(response, additionalFields);
+      const { success, status_code, error: _error, timestamp, metadata, retry_after, ...safeFields } = additionalFields;
+      Object.assign(response, safeFields);
     }
     const transformer = getResponseTransformer();
     if (transformer) {
@@ -851,7 +898,7 @@ var HttpResponse = class _HttpResponse {
    * @returns Formatted error response object
    */
   static fromError(error, config = {}) {
-    const httpError = HttpError.fromError(error);
+    const httpError = HttpError.fromError(error, config.fallbackCode);
     return _HttpResponse.error(httpError, config);
   }
   // ========================================================================
@@ -877,7 +924,7 @@ var HttpResponse = class _HttpResponse {
   static partialContent(data, message) {
     return _HttpResponse.success({ data, message, statusCode: 206 /* PARTIAL_CONTENT */ });
   }
-  /** 304 Not Modified */
+  /** 304 Not Modified — Note: 304 is a 3xx redirect code, included here as a convenience method */
   static notModified() {
     return _HttpResponse.success({ statusCode: 304 /* NOT_MODIFIED */ });
   }
@@ -900,16 +947,17 @@ var HttpResponse = class _HttpResponse {
    * Create a paginated success response
    */
   static paginated(data, pagination, message) {
+    const effectiveLimit = pagination.limit > 0 ? pagination.limit : 1;
     return _HttpResponse.success({
       data,
       message,
       metadata: {
         pagination: {
           page: pagination.page,
-          limit: pagination.limit,
+          limit: effectiveLimit,
           total: pagination.total,
-          total_pages: pagination.totalPages ?? Math.ceil(pagination.total / pagination.limit),
-          has_next: pagination.page < (pagination.totalPages ?? Math.ceil(pagination.total / pagination.limit)),
+          total_pages: pagination.totalPages ?? Math.ceil(pagination.total / effectiveLimit),
+          has_next: pagination.page < (pagination.totalPages ?? Math.ceil(pagination.total / effectiveLimit)),
           has_prev: pagination.page > 1
         }
       }

package/dist/index.mjs

@@ -340,8 +340,23 @@ var HttpErrorDefinitions = {
     details: "The client needs to authenticate to gain network access."
   }
 };
+Object.freeze(HttpErrorDefinitions);
 function getErrorDefinition(code) {
-  return HttpErrorDefinitions[code] || HttpErrorDefinitions[500];
+  if (code < 400 || code > 599) {
+    throw new RangeError(
+      `Invalid HTTP error code: ${code}. Must be between 400 and 599.`
+    );
+  }
+  if (HttpErrorDefinitions[code]) {
+    return HttpErrorDefinitions[code];
+  }
+  const isClientError = code >= 400 && code < 500;
+  return {
+    type: isClientError ? "unknown_client_error" : "unknown_server_error",
+    title: isClientError ? "Unknown Client Error" : "Unknown Server Error",
+    code,
+    details: isClientError ? "An unknown client error occurred." : "An unknown server error occurred."
+  };
 }
 
 // src/constants/success-definitions.ts
@@ -387,6 +402,7 @@ var HttpSuccessDefinitions = {
     description: "The server has fulfilled a GET request and the response is a representation of the result of one or more instance-manipulations."
   }
 };
+Object.freeze(HttpSuccessDefinitions);
 var HttpRedirectDefinitions = {
   [300 /* MULTIPLE_CHOICES */]: {
     code: 300,
@@ -421,6 +437,7 @@ var HttpRedirectDefinitions = {
     description: "The request and all future requests should be repeated using another URI."
   }
 };
+Object.freeze(HttpRedirectDefinitions);
 var HttpInfoDefinitions = {
   [100 /* CONTINUE */]: {
     code: 100,
@@ -439,29 +456,41 @@ var HttpInfoDefinitions = {
     description: "The server is sending some response headers before the final response."
   }
 };
+Object.freeze(HttpInfoDefinitions);
 function getSuccessDefinition(code) {
-  return HttpSuccessDefinitions[code] || HttpRedirectDefinitions[code] || HttpInfoDefinitions[code] || HttpSuccessDefinitions[200];
+  const definedInfo = HttpSuccessDefinitions[code] || HttpRedirectDefinitions[code] || HttpInfoDefinitions[code];
+  if (definedInfo) {
+    return definedInfo;
+  }
+  return {
+    code,
+    description: "The request was processed with a non-standard status code."
+  };
 }
 
 // src/config/index.ts
 var defaultConfig = {
-  isDevelopment: process.env.NODE_ENV === "development",
+  isDevelopment: void 0,
   includeTimestamp: true,
   customMessages: {},
   responseTransformer: void 0
 };
 var currentConfig = { ...defaultConfig };
 function configure(config) {
-  currentConfig = { ...currentConfig, ...config };
+  currentConfig = {
+    ...currentConfig,
+    ...config,
+    customMessages: { ...currentConfig.customMessages, ...config.customMessages }
+  };
 }
 function getConfig() {
   return { ...currentConfig };
 }
 function resetConfig() {
-  currentConfig = { ...defaultConfig };
+  currentConfig = { ...defaultConfig, customMessages: {} };
 }
 function isDevelopment() {
-  return currentConfig.isDevelopment ?? false;
+  return currentConfig.isDevelopment ?? process.env.NODE_ENV === "development";
 }
 function shouldIncludeTimestamp() {
   return currentConfig.includeTimestamp ?? true;
@@ -490,6 +519,7 @@ var HttpError = class _HttpError extends Error {
     this.code = errorInfo.code;
     this.type = errorInfo.type;
     this.title = errorInfo.title;
+    this.details = errorInfo.details;
     this.metadata = options.metadata;
     this.cause = options.cause;
     this.retryAfter = options.retryAfter ?? errorInfo.retryAfter;
@@ -507,6 +537,7 @@ var HttpError = class _HttpError extends Error {
       type: this.type,
       title: this.title,
       message: this.message,
+      details: this.details,
       metadata: this.metadata,
       retryAfter: this.retryAfter
     };
@@ -684,6 +715,13 @@ var HttpError = class _HttpError extends Error {
   // ========================================================================
   // Utility Methods
   // ========================================================================
+  /**
+   * Create an HttpError from a status code with default definition values.
+   * Semantic alias for `new HttpError(code)`.
+   */
+  static fromStatus(code, options) {
+    return new _HttpError(code, options);
+  }
   /**
    * Create an HttpError from an unknown error
    */
@@ -691,6 +729,11 @@ var HttpError = class _HttpError extends Error {
     if (error instanceof _HttpError) {
       return error;
     }
+    if (fallbackCode < 400 || fallbackCode > 599) {
+      throw new RangeError(
+        `fallbackCode must be between 400 and 599, got ${fallbackCode}`
+      );
+    }
     if (error instanceof Error) {
       return new _HttpError(fallbackCode, {
         message: error.message,
@@ -731,7 +774,7 @@ var HttpResponse = class _HttpResponse {
    */
   static success(config = {}) {
     const {
-      data = null,
+      data,
       message,
       statusCode = 200 /* OK */,
       metadata = {}
@@ -744,7 +787,7 @@ var HttpResponse = class _HttpResponse {
     if (shouldIncludeTimestamp()) {
       response.timestamp = (/* @__PURE__ */ new Date()).toISOString();
     }
-    if (statusCode !== 204 /* NO_CONTENT */ && statusCode !== 205 /* RESET_CONTENT */) {
+    if (statusCode !== 204 /* NO_CONTENT */ && statusCode !== 205 /* RESET_CONTENT */ && statusCode !== 304 /* NOT_MODIFIED */) {
       if (data !== null && data !== void 0) {
         response.data = data;
       }
@@ -782,8 +825,11 @@ var HttpResponse = class _HttpResponse {
     if (shouldIncludeTimestamp()) {
       response.timestamp = (/* @__PURE__ */ new Date()).toISOString();
     }
+    if (error.details) {
+      response.error.details = error.details;
+    }
     if (includeStack ?? isDevelopment()) {
-      response.error.details = error.stack;
+      response.error.stack = error.stack;
     }
     if (error.retryAfter) {
       response.retry_after = error.retryAfter;
@@ -792,7 +838,8 @@ var HttpResponse = class _HttpResponse {
       response.metadata = error.metadata;
     }
     if (additionalFields) {
-      Object.assign(response, additionalFields);
+      const { success, status_code, error: _error, timestamp, metadata, retry_after, ...safeFields } = additionalFields;
+      Object.assign(response, safeFields);
     }
     const transformer = getResponseTransformer();
     if (transformer) {
@@ -808,7 +855,7 @@ var HttpResponse = class _HttpResponse {
    * @returns Formatted error response object
    */
   static fromError(error, config = {}) {
-    const httpError = HttpError.fromError(error);
+    const httpError = HttpError.fromError(error, config.fallbackCode);
     return _HttpResponse.error(httpError, config);
   }
   // ========================================================================
@@ -834,7 +881,7 @@ var HttpResponse = class _HttpResponse {
   static partialContent(data, message) {
     return _HttpResponse.success({ data, message, statusCode: 206 /* PARTIAL_CONTENT */ });
   }
-  /** 304 Not Modified */
+  /** 304 Not Modified — Note: 304 is a 3xx redirect code, included here as a convenience method */
   static notModified() {
     return _HttpResponse.success({ statusCode: 304 /* NOT_MODIFIED */ });
   }
@@ -857,16 +904,17 @@ var HttpResponse = class _HttpResponse {
    * Create a paginated success response
    */
   static paginated(data, pagination, message) {
+    const effectiveLimit = pagination.limit > 0 ? pagination.limit : 1;
     return _HttpResponse.success({
       data,
       message,
       metadata: {
         pagination: {
           page: pagination.page,
-          limit: pagination.limit,
+          limit: effectiveLimit,
           total: pagination.total,
-          total_pages: pagination.totalPages ?? Math.ceil(pagination.total / pagination.limit),
-          has_next: pagination.page < (pagination.totalPages ?? Math.ceil(pagination.total / pagination.limit)),
+          total_pages: pagination.totalPages ?? Math.ceil(pagination.total / effectiveLimit),
+          has_next: pagination.page < (pagination.totalPages ?? Math.ceil(pagination.total / effectiveLimit)),
           has_prev: pagination.page > 1
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "http-response-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A professional HTTP error and response formatting library for Node.js",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -19,6 +19,8 @@
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -35,9 +37,11 @@
   "author": "Matteo Teodori",
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^25.2.1",
-    "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "@types/node": "^25.3.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=16.0.0"
@@ -46,4 +50,4 @@
     "type": "git",
     "url": "https://github.com/matteo-teodori/http-response-kit"
   }
-}
+}