From 1fd959c58452815e15edb9416a9be8dc1f404684 Mon Sep 17 00:00:00 2001
From: Pasindu Owa Gamage <pasinduogdev@gmail.com>
Date: Fri, 27 Feb 2026 20:56:07 +0530
Subject: [PATCH 1/5] Added error methods to ApiResponse

---
 .../io/github/og4dev/dto/ApiResponse.java     | 80 ++++++++++++++++---
 .../io/github/og4dev/dto/package-info.java    | 17 ++--
 2 files changed, 76 insertions(+), 21 deletions(-)

diff --git a/src/main/java/io/github/og4dev/dto/ApiResponse.java b/src/main/java/io/github/og4dev/dto/ApiResponse.java
index 3f127a4..36d202f 100644
--- a/src/main/java/io/github/og4dev/dto/ApiResponse.java
+++ b/src/main/java/io/github/og4dev/dto/ApiResponse.java
@@ -17,10 +17,10 @@
  * The response structure follows a standardized format:
  * </p>
  * <ul>
- *   <li><b>status</b> - HTTP status code (200, 201, 404, etc.)</li>
- *   <li><b>message</b> - Human-readable description of the response</li>
- *   <li><b>content</b> - The response payload (generic type T, optional)</li>
- *   <li><b>timestamp</b> - RFC 3339 UTC timestamp (auto-generated)</li>
+ * <li><b>status</b> - HTTP status code (200, 201, 404, etc.)</li>
+ * <li><b>message</b> - Human-readable description of the response</li>
+ * <li><b>content</b> - The response payload (generic type T, optional)</li>
+ * <li><b>timestamp</b> - RFC 3339 UTC timestamp (auto-generated)</li>
  * </ul>
  * <p>
  * <b>Thread Safety:</b> This class is immutable and thread-safe. All fields are final and set during
@@ -129,10 +129,25 @@ public Instant getTimestamp() {
         return timestamp;
     }
 
+    /**
+     * Creates a CREATED (201) response with a message.
+     *
+     * @param <T>     the type of the response content
+     * @param message the response message
+     * @return a ResponseEntity with CREATED status
+     */
+    public static <T> ResponseEntity<ApiResponse<T>> created(String message) {
+        return ResponseEntity.status(HttpStatus.CREATED)
+                .body(new ApiResponseBuilder<T>()
+                        .status(HttpStatus.CREATED.value())
+                        .message(message)
+                        .build());
+    }
+
     /**
      * Creates a CREATED (201) response with a message and content.
      *
-     * @param <T> the type of the response content
+     * @param <T>     the type of the response content
      * @param message the response message
      * @param content the response content
      * @return a ResponseEntity with CREATED status
@@ -163,7 +178,7 @@ public static ResponseEntity<ApiResponse<Void>> success(String message) {
     /**
      * Creates a SUCCESS (200) response with a message and content.
      *
-     * @param <T> the type of the response content
+     * @param <T>     the type of the response content
      * @param message the response message
      * @param content the response content
      * @return a ResponseEntity with OK status
@@ -181,7 +196,7 @@ public static <T> ResponseEntity<ApiResponse<T>> success(String message, T conte
      * Creates a response with a custom HTTP status and message only.
      *
      * @param message the response message
-     * @param status the HTTP status
+     * @param status  the HTTP status
      * @return a ResponseEntity with the specified status
      */
     public static ResponseEntity<ApiResponse<Void>> status(String message, HttpStatus status) {
@@ -195,10 +210,10 @@ public static ResponseEntity<ApiResponse<Void>> status(String message, HttpStatu
     /**
      * Creates a response with a custom HTTP status, message, and content.
      *
-     * @param <T> the type of the response content
+     * @param <T>     the type of the response content
      * @param message the response message
      * @param content the response content
-     * @param status the HTTP status
+     * @param status  the HTTP status
      * @return a ResponseEntity with the specified status
      */
     public static <T> ResponseEntity<ApiResponse<T>> status(String message, T content, HttpStatus status) {
@@ -211,22 +226,63 @@ public static <T> ResponseEntity<ApiResponse<T>> status(String message, T conten
     }
 
     /**
-     * Builder class for constructing ApiResponse instances.
+     * Creates a response with a custom HTTP status and error message only.
+     *
+     * @param message the error response message
+     * @param status  the HTTP status
+     * @return a ResponseEntity with the specified status
+     */
+    public static ResponseEntity<ApiResponse<Void>> error(String message, HttpStatus status) {
+        return ResponseEntity.status(status)
+                .body(new ApiResponseBuilder<Void>()
+                        .status(status.value())
+                        .message(message)
+                        .build());
+    }
+
+    /**
+     * Creates a response with a custom HTTP status, error message, and content.
+     *
+     * @param <T>     the type of the response content
+     * @param message the error response message
+     * @param content the response content
+     * @param status  the HTTP status
+     * @return a ResponseEntity with the specified status
+     */
+    public static <T> ResponseEntity<ApiResponse<T>> error(String message, T content, HttpStatus status) {
+        return ResponseEntity.status(status)
+                .body(new ApiResponseBuilder<T>()
+                        .status(status.value())
+                        .message(message)
+                        .content(content)
+                        .build());
+    }
+
+    /**
+     * Builder class for constructing {@link ApiResponse} instances.
      *
      * @param <T> the type of the response content
      */
     public static class ApiResponseBuilder<T> {
+
         private Integer status;
         private String message;
         private T content;
 
+        /**
+         * Default constructor for creating an empty builder.
+         */
+        public ApiResponseBuilder() {
+            // Default constructor
+        }
+
         /**
          * Sets the HTTP status code.
          *
          * @param status the status code
          * @return this builder instance
          */
-        private ApiResponseBuilder<T> status(Integer status) {
+        public ApiResponseBuilder<T> status(Integer status) {
             this.status = status;
             return this;
         }
@@ -254,7 +310,7 @@ public ApiResponseBuilder<T> content(T content) {
         }
 
         /**
-         * Builds the ApiResponse instance.
+         * Builds the {@link ApiResponse} instance.
          *
          * @return a new ApiResponse instance
          */
diff --git a/src/main/java/io/github/og4dev/dto/package-info.java b/src/main/java/io/github/og4dev/dto/package-info.java
index 026b729..a733fe1 100644
--- a/src/main/java/io/github/og4dev/dto/package-info.java
+++ b/src/main/java/io/github/og4dev/dto/package-info.java
@@ -1,24 +1,23 @@
 /**
- * Data Transfer Object (DTO) classes for standardized API responses.
+ * Provides Data Transfer Object (DTO) classes for standardized API responses.
  * <p>
  * This package contains classes for structuring API responses in a consistent, type-safe format.
  * The main class {@link io.github.og4dev.dto.ApiResponse} provides a generic wrapper that includes:
  * </p>
  * <ul>
- *   <li>HTTP status code</li>
- *   <li>Human-readable message</li>
- *   <li>Response content (generic type T)</li>
- *   <li>Automatic UTC timestamp generation</li>
+ * <li>HTTP status code</li>
+ * <li>Human-readable message</li>
+ * <li>Response content (generic type {@code T})</li>
+ * <li>Automatic UTC timestamp generation</li>
  * </ul>
  * <p>
  * All response objects are immutable and thread-safe, using a builder pattern for flexible construction.
- * Factory methods like {@code success()}, {@code created()}, and {@code status()} provide convenient
- * ways to create responses without manual building.
+ * Factory methods like {@code success()}, {@code created()}, {@code status()}, and {@code error()}
+ * provide convenient ways to create responses without manual building.
  * </p>
  *
  * @author Pasindu OG
  * @version 1.3.0
  * @since 1.0.0
  */
-package io.github.og4dev.dto;
-
+package io.github.og4dev.dto;
\ No newline at end of file

From 5d428f0a83f6a505b5476c343a72f3e174469bf2 Mon Sep 17 00:00:00 2001
From: Pasindu Owa Gamage <pasinduogdev@gmail.com>
Date: Fri, 27 Feb 2026 23:49:01 +0530
Subject: [PATCH 2/5] Created AutoResponse annotation and GlobalResponseWrapper
 for autoconfiguring API response sending

---
 .../og4dev/advice/GlobalResponseWrapper.java  | 107 ++++++++++++++++++
 .../og4dev/annotation/AutoResponse.java       |   9 ++
 2 files changed, 116 insertions(+)
 create mode 100644 src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java
 create mode 100644 src/main/java/io/github/og4dev/annotation/AutoResponse.java

diff --git a/src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java b/src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java
new file mode 100644
index 0000000..ed8deb0
--- /dev/null
+++ b/src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java
@@ -0,0 +1,107 @@
+package io.github.og4dev.advice;
+
+import io.github.og4dev.annotation.AutoResponse;
+import io.github.og4dev.dto.ApiResponse;
+import org.jspecify.annotations.Nullable;
+import org.springframework.core.MethodParameter;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ProblemDetail;
+import org.springframework.http.ResponseEntity;
+import org.springframework.http.converter.HttpMessageConverter;
+import org.springframework.http.server.ServerHttpRequest;
+import org.springframework.http.server.ServerHttpResponse;
+import org.springframework.http.server.ServletServerHttpResponse;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;
+
+/**
+ * Global response interceptor that automatically wraps REST controller outputs into the
+ * standardized {@link ApiResponse} format.
+ * <p>
+ * This wrapper is conditionally activated <b>only</b> for controllers or specific methods
+ * annotated with the {@link AutoResponse @AutoResponse} annotation. It provides a seamless
+ * developer experience by eliminating the need to manually return {@code ResponseEntity<ApiResponse<T>>}
+ * from every controller method.
+ * </p>
+ * <h2>Core Functionalities:</h2>
+ * <ul>
+ * <li><b>Automatic Encapsulation:</b> Intercepts raw DTOs, Lists, or primitive responses and packages
+ * them into the {@code content} field of an {@code ApiResponse}.</li>
+ * <li><b>Status Code Preservation:</b> Dynamically reads the current HTTP status of the response
+ * (e.g., set via {@code @ResponseStatus(HttpStatus.CREATED)}) and ensures it is accurately
+ * reflected in the final {@code ApiResponse}.</li>
+ * <li><b>Safety Mechanisms:</b> Intelligently skips wrapping if the response is already formatted
+ * to prevent double-wrapping errors or interference with standard error handling protocols.</li>
+ * </ul>
+ *
+ * @author Pasindu OG
+ * @version 1.4.0
+ * @see AutoResponse
+ * @see ApiResponse
+ * @see ResponseBodyAdvice
+ * @since 1.4.0
+ */
+@RestControllerAdvice(annotations = AutoResponse.class)
+@SuppressWarnings("unused")
+public class GlobalResponseWrapper implements ResponseBodyAdvice<Object> {
+
+    /**
+     * Determines whether the current response should be intercepted and wrapped.
+     * <p>
+     * To guarantee application stability and adherence to standard HTTP protocols, this method
+     * specifically <b>excludes</b> the following return types from being wrapped:
+     * </p>
+     * <ul>
+     * <li>{@link ApiResponse} - Prevents recursive double-wrapping (e.g., {@code ApiResponse<ApiResponse<T>>}).</li>
+     * <li>{@link ResponseEntity} - Skips manual responses to respect developer's explicit configurations.</li>
+     * <li>{@link ProblemDetail} - Excludes RFC 9457 error responses generated by exception handlers.</li>
+     * <li>{@link String} - Bypasses raw strings to prevent {@code ClassCastException} when Spring utilizes
+     * the {@code StringHttpMessageConverter}.</li>
+     * </ul>
+     *
+     * @param returnType    The return type of the controller method.
+     * @param converterType The selected HTTP message converter.
+     * @return {@code true} if the body should be wrapped; {@code false} if it should be skipped.
+     */
+    @Override
+    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
+        Class<?> type = returnType.getParameterType();
+        return !ApiResponse.class.isAssignableFrom(type) &&
+                !ResponseEntity.class.isAssignableFrom(type) &&
+                !ProblemDetail.class.isAssignableFrom(type) &&
+                !String.class.isAssignableFrom(type);
+    }
+
+    /**
+     * Intercepts the response body before it is written to the output stream and encapsulates it
+     * within an {@link ApiResponse}.
+     * <p>
+     * This method extracts the actual HTTP status code set on the current response (defaulting to 200 OK).
+     * Based on whether the status code represents a success (2xx) or another state, it dynamically
+     * assigns an appropriate message ("Success" or "Processed") to the API response.
+     * </p>
+     *
+     * @param body                  The raw object returned by the controller method.
+     * @param returnType            The return type of the controller method.
+     * @param selectedContentType   The selected content type for the response.
+     * @param selectedConverterType The selected HTTP message converter.
+     * @param request               The current server HTTP request.
+     * @param response              The current server HTTP response.
+     * @return The newly wrapped {@code ApiResponse} object ready to be serialized.
+     */
+    @Override
+    public @Nullable Object beforeBodyWrite(@Nullable Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
+        int statusCode = HttpStatus.OK.value();
+
+        // Extract the dynamically set HTTP status code (e.g., from @ResponseStatus)
+        if (response instanceof ServletServerHttpResponse serverHttpResponse) {
+            statusCode = serverHttpResponse.getServletResponse().getStatus();
+        }
+
+        HttpStatus httpStatus = HttpStatus.valueOf(statusCode);
+
+        // Wrap the payload and generate the final format
+        return ApiResponse.status(httpStatus.is2xxSuccessful() ? "Success" : "Processed", body, httpStatus).getBody();
+    }
+}
\ No newline at end of file
diff --git a/src/main/java/io/github/og4dev/annotation/AutoResponse.java b/src/main/java/io/github/og4dev/annotation/AutoResponse.java
new file mode 100644
index 0000000..d22eb84
--- /dev/null
+++ b/src/main/java/io/github/og4dev/annotation/AutoResponse.java
@@ -0,0 +1,9 @@
+package io.github.og4dev.annotation;
+
+import java.lang.annotation.*;
+
+@Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface AutoResponse {
+}

From 5fdbc0c9158077e3f1051d947094a366b68411bd Mon Sep 17 00:00:00 2001
From: Pasindu Owa Gamage <pasinduogdev@gmail.com>
Date: Sat, 28 Feb 2026 00:16:03 +0530
Subject: [PATCH 3/5] feat: introduce @AutoResponse for zero-boilerplate
 response wrapping

- Add `@AutoResponse` annotation for opt-in controller response wrapping
- Implement `GlobalResponseWrapper` to intercept and wrap raw DTOs into `ApiResponse`
- Preserve custom HTTP status codes set via `@ResponseStatus`
- Safely bypass `ResponseEntity`, `ApiResponse`, `ProblemDetail`, and `String` to prevent double-wrapping
- Update `ApiResponseAutoConfiguration` to register the new wrapper automatically
- Add comprehensive Javadocs and `package-info.java` for the new `advice` package
- Update README.md with v1.4.0 features, examples, and version bumps
---
 README.md                                     | 3695 ++---------------
 pom.xml                                       |    2 +-
 .../og4dev/advice/GlobalResponseWrapper.java  |    5 +-
 .../io/github/og4dev/advice/package-info.java |   30 +
 .../og4dev/annotation/AutoResponse.java       |   50 +-
 .../io/github/og4dev/annotation/AutoTrim.java |    2 +-
 .../io/github/og4dev/annotation/XssCheck.java |    2 +-
 .../og4dev/annotation/package-info.java       |    2 +-
 .../config/ApiResponseAutoConfiguration.java  |  122 +-
 .../io/github/og4dev/config/package-info.java |    7 +-
 .../io/github/og4dev/dto/ApiResponse.java     |    2 +-
 .../io/github/og4dev/dto/package-info.java    |    2 +-
 .../github/og4dev/exception/ApiException.java |    2 +-
 .../exception/GlobalExceptionHandler.java     |    2 +-
 .../github/og4dev/exception/package-info.java |    2 +-
 .../github/og4dev/filter/TraceIdFilter.java   |    2 +-
 .../io/github/og4dev/filter/package-info.java |    2 +-
 .../java/io/github/og4dev/package-info.java   |    4 +-
 18 files changed, 413 insertions(+), 3522 deletions(-)
 create mode 100644 src/main/java/io/github/og4dev/advice/package-info.java

diff --git a/README.md b/README.md
index 2cfb457..5b19353 100644
--- a/README.md
+++ b/README.md
@@ -3,186 +3,175 @@
 # OG4Dev Spring API Response
 
 <p align="center">
-  <img src="https://skillicons.dev/icons?i=java,spring,maven,git,github,idea" alt="Tech Stack" />
+<img src="https://skillicons.dev/icons?i=java,spring,maven,git,github,idea" alt="Tech Stack" />
 </p>
 
 <p align="center">
-  <em>A lightweight, zero-configuration REST API Response wrapper for Spring Boot applications</em>
+<em>A lightweight, zero-configuration REST API Response wrapper for Spring Boot applications</em>
 </p>
 
 <p align="center">
-  <a href="https://central.sonatype.com/artifact/io.github.og4dev/og4dev-spring-response">
-    <img src="https://img.shields.io/maven-central/v/io.github.og4dev/og4dev-spring-response.svg" alt="Maven Central">
-  </a>
-  <a href="https://opensource.org/licenses/Apache-2.0">
-    <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License">
-  </a>
-  <a href="https://www.oracle.com/java/">
-    <img src="https://img.shields.io/badge/Java-17+-orange.svg" alt="Java">
-  </a>
-  <a href="https://spring.io/projects/spring-boot">
-    <img src="https://img.shields.io/badge/Spring%20Boot-4.0.3-brightgreen.svg" alt="Spring Boot">
-  </a>
-  <a href="https://github.com/OG4Dev/og4dev-spring-response">
-    <img src="https://img.shields.io/badge/Version-1.3.0-brightgreen.svg" alt="Version">
-  </a>
+<a href="https://central.sonatype.com/artifact/io.github.og4dev/og4dev-spring-response">
+<img src="https://img.shields.io/maven-central/v/io.github.og4dev/og4dev-spring-response.svg" alt="Maven Central">
+</a>
+<a href="https://opensource.org/licenses/Apache-2.0">
+<img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License">
+</a>
+<a href="https://www.oracle.com/java/">
+<img src="https://img.shields.io/badge/Java-17+-orange.svg" alt="Java">
+</a>
+<a href="https://spring.io/projects/spring-boot">
+<img src="https://img.shields.io/badge/Spring%20Boot-4.0.3-brightgreen.svg" alt="Spring Boot">
+</a>
+<a href="https://github.com/OG4Dev/og4dev-spring-response">
+<img src="https://img.shields.io/badge/Version-1.4.0-brightgreen.svg" alt="Version">
+</a>
 </p>
 
 <p align="center">
-A lightweight, type-safe API Response wrapper for Spring Boot applications. Standardize your REST API responses with consistent structure, automatic timestamps, distributed tracing support, and clean factory methods. Features zero-configuration Spring Boot auto-configuration and production-ready exception handling with comprehensive RFC 9457 ProblemDetail support covering 10 common error scenarios. No external dependencies required - uses pure Java with a custom builder pattern.
+A lightweight, type-safe API Response wrapper for Spring Boot applications. Standardize your REST API responses with consistent structure, automatic timestamps, distributed tracing support, and clean factory methods. Features zero-configuration Spring Boot auto-configuration, opt-in automatic response wrapping (@AutoResponse), and production-ready exception handling with comprehensive RFC 9457 ProblemDetail support covering 10 common error scenarios. No external dependencies required - uses pure Java with a custom builder pattern.
 </p>
 
 </div>
 
-
 ## 🔗 Quick Links
 
-- 📦 [Maven Central Repository](https://central.sonatype.com/artifact/io.github.og4dev/og4dev-spring-response)
-- 📚 [JavaDoc Documentation](https://javadoc.io/doc/io.github.og4dev/og4dev-spring-response)
-- 🐛 [Report Issues](https://github.com/OG4Dev/og4dev-spring-response/issues)
-- 💡 [Feature Requests](https://github.com/OG4Dev/og4dev-spring-response/issues/new)
-- 🤝 [Contributing Guide](#-contributing)
+* 📦 [Maven Central Repository](https://central.sonatype.com/artifact/io.github.og4dev/og4dev-spring-response)
+* 📚 [JavaDoc Documentation](https://javadoc.io/doc/io.github.og4dev/og4dev-spring-response)
+* 🐛 [Report Issues](https://github.com/OG4Dev/og4dev-spring-response/issues)
+* 💡 [Feature Requests](https://github.com/OG4Dev/og4dev-spring-response/issues/new)
+* 🤝 [Contributing Guide](#-contributing)
 
 ## 📑 Table of Contents
 
-- [Quick Links](#-quick-links)
-- [Key Highlights](#-key-highlights)
-- [Features](#-features)
-- [Requirements](#-requirements)
-- [What Makes This Different?](#-what-makes-this-different)
-- [Installation](#-installation)
-- [Project Structure](#-project-structure)
-- [Quick Start](#-quick-start)
-- [Auto-Configuration](#️-auto-configuration)
-- [Built-in Security Features](#-built-in-security-features)
-- [Built-in Exception Handling](#️-built-in-exception-handling)
-- [Usage](#-usage)
-- [Real-World Examples](#-real-world-examples)
-- [API Reference](#-api-reference)
-- [Response Structure](#-response-structure)
-- [Best Practices](#-best-practices)
-- [Testing](#-testing)
-- [Architecture & Design](#️-architecture--design-principles)
-- [OpenAPI/Swagger Integration](#-openapiswagger-integration)
-- [Compatibility Matrix](#-compatibility-matrix)
-- [Troubleshooting](#-troubleshooting)
-- [FAQ](#-faq)
-- [Performance & Best Practices](#-performance--best-practices)
-- [Migration Guide](#-migration-guide)
-- [Security Considerations](#-security-considerations)
-- [Contributing](#-contributing)
-- [License](#-license)
-- [Contact](#-contact)
-- [Acknowledgments](#-acknowledgments)
-- [Version History](#-version-history)
+* [Quick Links](#-quick-links)
+* [Key Highlights](#-key-highlights)
+* [Features](#-features)
+* [Requirements](#-requirements)
+* [What Makes This Different?](#-what-makes-this-different)
+* [Installation](#-installation)
+* [Project Structure](#-project-structure)
+* [Quick Start](#-quick-start)
+* [Auto-Configuration](#%EF%B8%8F-auto-configuration)
+* [Opt-in Automatic Wrapping (@AutoResponse)](#-opt-in-automatic-wrapping-autoresponse)
+* [Built-in Security Features](#-built-in-security-features)
+* [Built-in Exception Handling](#%EF%B8%8F-built-in-exception-handling)
+* [Usage](#-usage)
+* [Real-World Examples](#-real-world-examples)
+* [API Reference](#-api-reference)
+* [Response Structure](#-response-structure)
+* [Best Practices](#-best-practices)
+* [Testing](#-testing)
+* [Architecture & Design](#%EF%B8%8F-architecture--design-principles)
+* [OpenAPI/Swagger Integration](#-openapiswagger-integration)
+* [Compatibility Matrix](#-compatibility-matrix)
+* [Troubleshooting](#-troubleshooting)
+* [FAQ](#-faq)
+* [Performance & Best Practices](#-performance--best-practices)
+* [Migration Guide](#-migration-guide)
+* [Security Considerations](#-security-considerations)
+* [Contributing](#-contributing)
+* [License](#-license)
+* [Contact](#-contact)
+* [Acknowledgments](#-acknowledgments)
+* [Version History](#-version-history)
 
 ## 🎯 Key Highlights
 
-- 🚀 **Truly Zero Configuration** - Spring Boot 3.x/4.x auto-configuration with META-INF imports
-- 🎯 **Production-Ready** - Built-in RFC 9457 ProblemDetail with 10 comprehensive exception handlers
-- 🛡️ **Complete Error Coverage** - Handles validation, JSON parsing, 404s, method mismatches, media types, and more
-- 🔍 **Trace IDs in Errors** - Error responses include traceId for debugging
-- 🔒 **Type-Safe & Immutable** - Thread-safe design with generic type support
-- 📦 **Ultra-Lightweight** - Only ~10KB JAR size with provided dependencies
-- 🔍 **Microservices-Ready** - Built-in trace IDs for distributed tracing
-- ✅ **Battle-Tested** - Used in production Spring Boot applications
-- 📋 **Professional-Grade Javadoc** - 100% coverage with comprehensive method documentation
-- 🔐 **Opt-in Security Features** - Fine-grained control with field-level annotations
-- 🚫 **Zero External Dependencies** - Pure Java, no Lombok required
+* 🚀 **Truly Zero Configuration** - Spring Boot 3.x/4.x auto-configuration with META-INF imports
+* 🎁 **Zero Boilerplate** - Opt-in `@AutoResponse` to automatically wrap raw return types
+* 🎯 **Production-Ready** - Built-in RFC 9457 ProblemDetail with 10 comprehensive exception handlers
+* 🛡️ **Complete Error Coverage** - Handles validation, JSON parsing, 404s, method mismatches, media types, and more
+* 🔍 **Trace IDs in Errors** - Error responses include traceId for debugging
+* 🔒 **Type-Safe & Immutable** - Thread-safe design with generic type support
+* 📦 **Ultra-Lightweight** - Only ~10KB JAR size with provided dependencies
+* 🔍 **Microservices-Ready** - Built-in trace IDs for distributed tracing
+* ✅ **Battle-Tested** - Used in production Spring Boot applications
+* 📋 **Professional-Grade Javadoc** - 100% coverage with comprehensive method documentation
+* 🔐 **Opt-in Security Features** - Fine-grained control with field-level annotations
+* 🚫 **Zero External Dependencies** - Pure Java, no Lombok required
 
 ## ✨ Features
 
-- 🎯 **Consistent Structure** - All responses follow the same format: `status`, `message`, `content`, `timestamp`
-- 🔒 **Type-Safe** - Full generic type support with compile-time type checking
-- 🔍 **Distributed Tracing** - Trace IDs in error responses with MDC integration for request tracking
-- ⏰ **Auto Timestamps** - Automatic RFC 3339 UTC formatted timestamps on every response
-- 🏭 **Factory Methods** - Clean static methods: `success()`, `created()`, `status()`
-- 🚀 **Zero Config** - Spring Boot Auto-Configuration for instant setup
-- 🪶 **Lightweight** - Only ~10KB JAR with single provided dependency (Spring Web)
-- 📦 **Immutable** - Thread-safe with final fields
-- 🔌 **Spring Native** - Built on `ResponseEntity` and `HttpStatus`
-- 📋 **RFC 9457 Compliance** - Standard ProblemDetail format (supersedes RFC 7807)
-- 📚 **Complete JavaDoc** - Every class and method fully documented with comprehensive examples
-- 🔐 **Opt-in Security Features** - Fine-grained JSON request protection via field annotations
-  - ✅ **Strict JSON Validation** - Rejects unknown properties to prevent mass assignment attacks (automatic)
-  - ✅ **XSS Prevention** - HTML tag detection and rejection via `@XssCheck` annotation (opt-in)
-  - ✅ **Smart String Trimming** - Whitespace trimming via `@AutoTrim` annotation (opt-in)
-  - ✅ **Case-Insensitive Enums** - Flexible enum handling for better API usability (automatic)
-- 🛡️ **Comprehensive Exception Handling** - 10 built-in handlers covering all common scenarios
-  - ✅ Validation errors (`@Valid` annotations)
-  - ✅ Type mismatches (wrong parameter types)
-  - ✅ Malformed JSON (invalid request bodies)
-  - ✅ Missing parameters (required `@RequestParam`)
-  - ✅ 404 Not Found (missing endpoints/resources)
-  - ✅ 405 Method Not Allowed (wrong HTTP method)
-  - ✅ 415 Unsupported Media Type (invalid Content-Type)
-  - ✅ Null pointer exceptions
-  - ✅ Custom business exceptions (`ApiException`)
-  - ✅ General unexpected errors
-- 🎭 **Custom Business Exceptions** - Abstract `ApiException` class for domain-specific errors
-- ✅ **Validation Support** - Automatic `@Valid` annotation error handling
+* 🎯 **Consistent Structure** - All responses follow the same format: `status`, `message`, `content`, `timestamp`
+* 🎁 **@AutoResponse Wrapping** - Return plain DTOs; let the library wrap them automatically (Opt-in)
+* 🔒 **Type-Safe** - Full generic type support with compile-time type checking
+* 🔍 **Distributed Tracing** - Trace IDs in error responses with MDC integration for request tracking
+* ⏰ **Auto Timestamps** - Automatic RFC 3339 UTC formatted timestamps on every response
+* 🏭 **Factory Methods** - Clean static methods: `success()`, `created()`, `status()`
+* 🚀 **Zero Config** - Spring Boot Auto-Configuration for instant setup
+* 🪶 **Lightweight** - Only ~10KB JAR with single provided dependency (Spring Web)
+* 📦 **Immutable** - Thread-safe with final fields
+* 🔌 **Spring Native** - Built on `ResponseEntity` and `HttpStatus`
+* 📋 **RFC 9457 Compliance** - Standard ProblemDetail format (supersedes RFC 7807)
+* 📚 **Complete JavaDoc** - Every class and method fully documented with comprehensive examples
+* 🔐 **Opt-in Security Features** - Fine-grained JSON request protection via field annotations
+* ✅ **Strict JSON Validation** - Rejects unknown properties to prevent mass assignment attacks (automatic)
+* ✅ **XSS Prevention** - HTML tag detection and rejection via `@XssCheck` annotation (opt-in)
+* ✅ **Smart String Trimming** - Whitespace trimming via `@AutoTrim` annotation (opt-in)
+* ✅ **Case-Insensitive Enums** - Flexible enum handling for better API usability (automatic)
+* 🛡️ **Comprehensive Exception Handling** - 10 built-in handlers covering all common scenarios
 
 ## 📦 Requirements
 
-- Java 17 or higher
-- Spring Boot 3.2.0 or higher (tested up to 4.0.3)
-- No additional dependencies required (pure Java implementation)
+* Java 17 or higher
+* Spring Boot 3.2.0 or higher (tested up to 4.0.3)
+* No additional dependencies required (pure Java implementation)
 
 ## 🌟 What Makes This Different?
 
 Unlike other response wrapper libraries, this one offers:
 
-- ✅ **Native Spring Boot 3.x/4.x Auto-Configuration** - No manual setup required
-- ✅ **RFC 9457 ProblemDetail Support** - Industry-standard error responses (latest RFC)
-- ✅ **Opt-in Security Features** - Fine-grained control via field-level annotations
-  - `@XssCheck` - HTML tag detection and rejection (fail-fast approach)
-  - `@AutoTrim` - Whitespace trimming for specific fields
-  - Regex-based validation: `(?s).*<\s*[a-zA-Z/!].*`
-  - Default: Fields are NOT modified unless explicitly annotated
-- ✅ **Zero External Dependencies** - Pure Java implementation, won't conflict with your application
-- ✅ **Extensible Exception Handling** - Create custom business exceptions easily
-- ✅ **Trace ID Support** - Built-in distributed tracing capabilities
-- ✅ **Professional-Grade Documentation** - 100% Javadoc coverage with comprehensive method documentation including:
-  - Detailed security feature explanations
-  - Code examples for all major features
-  - Complete @param, @return, @see, and @since tags
-  - Method-level documentation explaining design decisions
-  - Zero Javadoc warnings on build
-- ✅ **Production-Grade Quality** - Clean builds, proper documentation, and battle-tested code
+* ✅ **Native Spring Boot 3.x/4.x Auto-Configuration** - No manual setup required
+* ✅ **Zero-Boilerplate @AutoResponse** - Return raw objects, let the library wrap them automatically while preserving
+  your HTTP Status codes.
+* ✅ **RFC 9457 ProblemDetail Support** - Industry-standard error responses (latest RFC)
+* ✅ **Opt-in Security Features** - Fine-grained control via field-level annotations (`@XssCheck`, `@AutoTrim`)
+* ✅ **Zero External Dependencies** - Pure Java implementation, won't conflict with your application
+* ✅ **Extensible Exception Handling** - Create custom business exceptions easily
+* ✅ **Trace ID Support** - Built-in distributed tracing capabilities
+* ✅ **Professional-Grade Documentation** - 100% Javadoc coverage
+
 ## 🚀 Installation
 
-### Maven (Latest - v1.3.0)
+### Maven (Latest - v1.4.0)
 
 ```xml
+
 <dependency>
     <groupId>io.github.og4dev</groupId>
     <artifactId>og4dev-spring-response</artifactId>
-    <version>1.3.0</version>
+    <version>1.4.0</version>
 </dependency>
+
 ```
 
-### Gradle (Latest - v1.3.0)
+### Gradle (Latest - v1.4.0)
 
 ```gradle
-implementation 'io.github.og4dev:og4dev-spring-response:1.3.0'
+implementation 'io.github.og4dev:og4dev-spring-response:1.4.0'
+
 ```
 
-### Gradle Kotlin DSL (Latest - v1.3.0)
+### Gradle Kotlin DSL (Latest - v1.4.0)
 
 ```kotlin
-implementation("io.github.og4dev:og4dev-spring-response:1.3.0")
+implementation("io.github.og4dev:og4dev-spring-response:1.4.0")
+
 ```
 
 ---
 
-
 ## 📁 Project Structure
 
-The library is organized into five main packages:
+The library is organized into six main packages:
 
 ```
 io.github.og4dev
+├── advice/
+│   └── GlobalResponseWrapper.java           # Automatic response wrapper interceptor
 ├── annotation/
+│   ├── AutoResponse.java                    # Opt-in annotation for automatic wrapping
 │   ├── AutoTrim.java                        # Opt-in annotation for string trimming
 │   └── XssCheck.java                        # Opt-in annotation for XSS validation
 ├── config/
@@ -194,498 +183,151 @@ io.github.og4dev
 │   └── GlobalExceptionHandler.java          # RFC 9457 exception handler
 └── filter/
     └── TraceIdFilter.java                   # Request trace ID generation
-```
 
-### Package Overview
-
-| Package | Description |
-|---------|-------------|
-| `annotation` | Field-level annotations for opt-in security and data processing features |
-| `config` | Spring Boot auto-configuration classes for zero-config setup |
-| `dto` | Data Transfer Objects - main `ApiResponse<T>` wrapper class |
-| `exception` | Exception handling infrastructure with ProblemDetail support |
-| `filter` | Servlet filters for trace ID generation and MDC management |
+```
 
-### Key Components
+## 🎯 Quick Start
 
-- **ApiResponse<T>** - Type-safe response wrapper with factory methods
-- **ApiResponseAutoConfiguration** - Automatic Spring Boot integration
-- **GlobalExceptionHandler** - Centralized exception handling with RFC 9457
-- **ApiException** - Base class for domain-specific exceptions
-- **@AutoTrim** - Annotation to opt-in to automatic string trimming for specific fields
-- **@XssCheck** - Annotation to opt-in to XSS validation for specific fields
-- **TraceIdFilter** - Automatic trace ID generation for distributed tracing
+You can use the library in two ways: **Explicit Factory Methods** or **Automatic Wrapping**.
 
-## 🎯 Quick Start
+### Method 1: Explicit Factory Methods
 
 ```java
-import io.github.og4dev.dto.ApiResponse;
-import org.springframework.http.ResponseEntity;
-import org.springframework.web.bind.annotation.*;
 
 @RestController
 @RequestMapping("/api/users")
 public class UserController {
-
     @GetMapping("/{id}")
     public ResponseEntity<ApiResponse<User>> getUser(@PathVariable Long id) {
         User user = userService.findById(id);
         return ApiResponse.success("User retrieved successfully", user);
     }
 }
-```
 
-**Response:**
-```json
-{
-  "status": 200,
-  "message": "User retrieved successfully",
-  "content": {
-    "id": 1,
-    "name": "John Doe",
-    "email": "john@example.com"
-  },
-  "timestamp": "2026-02-06T10:30:45.123Z"
-}
 ```
 
-## ⚙️ Auto-Configuration 
-
-The library now features **Spring Boot Auto-Configuration** for truly zero-config setup! Simply add the dependency and everything works automatically.
-
-### What Gets Auto-Configured
-
-When you include this library in your Spring Boot application, the following components are automatically registered:
+### Method 2: Automatic Wrapping (New in v1.4.0) 🎁
 
-✅ **GlobalExceptionHandler** - Automatic exception handling with RFC 7807 ProblemDetail format  
-✅ **Component Scanning** - All library components are automatically discovered  
-✅ **Bean Registration** - No manual @ComponentScan or @Import required  
+Tired of typing `ResponseEntity<ApiResponse<T>>`? Use `@AutoResponse`!
 
-### How It Works
-
-The library includes `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` which Spring Boot 3.x automatically detects and loads the `ApiResponseAutoConfiguration` class.
-
-**No configuration needed!** Just add the dependency:
-
-```xml
-<dependency>
-    <groupId>io.github.og4dev</groupId>
-    <artifactId>og4dev-spring-response</artifactId>
-    <version>1.1.1</version>
-</dependency>
-```
+```java
 
-### Disabling Auto-Configuration (Optional)
+@RestController
+@RequestMapping("/api/users")
+@AutoResponse // Applies to all methods in this controller
+public class UserController {
 
-If you need to customize or disable the auto-configuration:
+    @GetMapping("/{id}")
+    public User getUser(@PathVariable Long id) {
+        // Just return the raw object!
+        return userService.findById(id);
+    }
 
-```java
-@SpringBootApplication(exclude = ApiResponseAutoConfiguration.class)
-public class Application {
-    public static void main(String[] args) {
-        SpringApplication.run(Application.class, args);
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED) // Preserves custom status codes!
+    public User createUser(@RequestBody UserDto dto) {
+        return userService.create(dto);
     }
 }
-```
 
-Or in `application.properties`:
-```properties
-spring.autoconfigure.exclude=io.github.og4dev.config.ApiResponseAutoConfiguration
 ```
 
-## 🔐 Built-in Security Features
-
-The library provides fine-grained security and data processing features through field-level annotations. By default, **fields are NOT modified** unless explicitly annotated, giving you complete control over which fields receive special treatment.
-
-### Security Philosophy: Opt-in by Default
-
-**Version 1.3.0** introduces an opt-in approach:
-- ✅ **Default Behavior**: String fields are preserved as-is (no trimming, no XSS validation)
-- ✅ **Explicit Control**: Use `@AutoTrim` and `@XssCheck` annotations to enable features per field
-- ✅ **No Surprises**: Your data is not modified unless you explicitly request it
-- ✅ **Production-Ready**: Enable security only where needed
-
-### 1. Strict Property Validation 🛡️ (Automatic)
-
-**Prevents mass assignment vulnerabilities and data injection attacks**
-
-Automatically rejects JSON payloads containing unexpected fields:
-
-```java
-// Your DTO
-public class UserDto {
-    private String name;
-    private String email;
-    // getters and setters
-}
-
-// ✅ Valid request
-{
-  "name": "John Doe",
-  "email": "john@example.com"
-}
+**Both methods produce the exact same JSON:**
 
-// ❌ Rejected with 400 Bad Request
+```json
 {
-  "name": "John Doe",
-  "email": "john@example.com",
-  "isAdmin": true  // Unknown field - potential mass assignment attack
+  "status": 200,
+  // or 201 for POST
+  "message": "Success",
+  "content": {
+    "id": 1,
+    "name": "John Doe"
+  },
+  "timestamp": "2026-02-28T10:30:45.123Z"
 }
-```
-
-**Benefits:**
-- Prevents privilege escalation attempts
-- Catches client-side typos early
-- Enforces strict API contracts
-- Improves API security posture
-
-### 2. Opt-in XSS Prevention with @XssCheck 🔒
-
-**Fail-fast HTML tag detection and rejection (opt-in per field)**
 
-Use the `@XssCheck` annotation to enable XSS validation on specific string fields:
-
-```java
-import io.github.og4dev.annotation.XssCheck;
-
-public class CommentDTO {
-    @XssCheck
-    private String content;        // XSS validated
-    
-    @XssCheck
-    private String authorName;     // XSS validated
-    
-    private String commentId;      // NOT validated (no annotation)
-}
 ```
 
-**What happens:**
+## ⚙️ Auto-Configuration
 
-```java
-// ✅ Valid requests (accepted for @XssCheck fields)
-{
-  "content": "Hello World",              // Plain text
-  "authorName": "John Doe",              // Plain text
-  "commentId": "<id-123>"                // No validation (no @XssCheck)
-}
+The library features **Spring Boot Auto-Configuration** for truly zero-config setup!
 
-{
-  "content": "Price: $100 < $200",       // Comparison operators OK
-  "authorName": "User@2024"              // Special characters OK
-}
+✅ **GlobalExceptionHandler** - Automatic exception handling
 
-// ❌ Invalid requests (rejected with 400 Bad Request for @XssCheck fields)
-{
-  "content": "<script>alert('XSS')</script>",  // Script injection
-  "authorName": "<b>John</b>",                 // HTML tags
-  "commentId": "<script>test</script>"         // NOT rejected (no @XssCheck)
-}
-```
+✅ **GlobalResponseWrapper** - Automatic payload wrapping via `@AutoResponse`
 
-**Error Response:**
-```json
-{
-  "type": "about:blank",
-  "title": "Bad Request",
-  "status": 400,
-  "detail": "Security Error: HTML tags or XSS payloads are not allowed in the request.",
-  "traceId": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2026-02-21T10:30:45.123Z"
-}
-```
+✅ **Security Customizers** - Jackson configuration for `@AutoTrim` and `@XssCheck`
 
-**Features:**
-- ✅ Detects HTML tags using regex: `(?s).*<\s*[a-zA-Z/!].*`
-- ✅ Rejects requests entirely (fail-fast approach)
-- ✅ Works only on annotated fields
-- ✅ Preserves null values (doesn't convert to empty strings)
-- ✅ Supports multiline content (DOTALL mode)
+**No configuration needed!** Just add the dependency.
 
-**Security Advantage:**  
-Unlike HTML escaping (which transforms `<` to `&lt;`), this fail-fast approach **rejects the request entirely**. This prevents:
-- Stored XSS attacks
-- DOM-based XSS attacks
-- Second-order injection vulnerabilities
-- Encoding bypass attempts
+## 🎁 Opt-in Automatic Wrapping (@AutoResponse)
 
-### 3. Opt-in String Trimming with @AutoTrim ✂️
+Introduced in **v1.4.0**, you can eliminate boilerplate code by letting the library wrap your controller responses
+automatically.
 
-**Whitespace removal for specific fields (opt-in per field)**
+### How to use it:
 
-Use the `@AutoTrim` annotation to enable automatic whitespace trimming on specific string fields:
+Add the `@AutoResponse` annotation to your controller class (applies to all methods) or to specific methods.
 
 ```java
-import io.github.og4dev.annotation.AutoTrim;
-
-public class UserRegistrationDTO {
-    @AutoTrim
-    private String username;       // Trimmed: "  john_doe  " → "john_doe"
-    
-    @AutoTrim
-    private String email;          // Trimmed: " user@example.com " → "user@example.com"
-    
-    private String password;       // NOT trimmed: "  pass123  " → "  pass123  "
-    private String bio;            // NOT trimmed: preserves formatting
-}
-```
 
-**What happens:**
-
-```java
-// Input JSON
-{
-  "username": "  john_doe  ",
-  "email": " user@example.com ",
-  "password": "  myPass123  ",
-  "bio": "  Software Developer  "
+@RestController
+@AutoResponse
+public class ProductController {
+    // ...
 }
 
-// After Deserialization
-username = "john_doe"              // ✓ Trimmed (has @AutoTrim)
-email    = "user@example.com"      // ✓ Trimmed (has @AutoTrim)
-password = "  myPass123  "         // ✗ NOT trimmed (no annotation)
-bio      = "  Software Developer  " // ✗ NOT trimmed (no annotation)
 ```
 
-**Use Cases for @AutoTrim:**
-- User input fields: names, emails, addresses where whitespace is unwanted
-- Search queries: remove accidental spaces from user inputs
-- Usernames: ensure consistent formatting without extra spaces
-- Reference numbers: IDs, codes that should not have whitespace
-- Categories/Tags: taxonomy values that need consistent formatting
-
-**When NOT to use @AutoTrim:**
-- Password fields where whitespace may be intentional
-- Code snippets or formatted text requiring exact spacing
-- Base64-encoded data that should not be modified
-- Poetry, ASCII art, or pre-formatted documents
-- API keys/tokens that must be processed exactly as provided
-
-### 4. Combining Annotations for Maximum Security
+### Key Capabilities:
 
-You can use both `@AutoTrim` and `@XssCheck` together for fields that need both behaviors:
-
-```java
-import io.github.og4dev.annotation.AutoTrim;
-import io.github.og4dev.annotation.XssCheck;
-
-public class SecureInputDTO {
-    @AutoTrim
-    @XssCheck
-    private String username;  // First trimmed, then XSS-validated
-    
-    @XssCheck
-    private String comment;   // Only XSS-validated (not trimmed)
-    
-    @AutoTrim
-    private String email;     // Only trimmed (not XSS-validated)
-    
-    private String bio;       // Neither (preserved as-is)
-}
-```
+* ✅ **Status Code Preservation:** Intelligently reads custom HTTP status codes set via `@ResponseStatus` (e.g., 201
+  Created) and reflects them in the `ApiResponse`.
+* ✅ **Double-Wrap Prevention:** Safely skips wrapping if you explicitly return an `ApiResponse` or `ResponseEntity`.
+* ✅ **Error Compatibility:** Bypasses `ProblemDetail` responses, ensuring standard error handling is never broken.
+* ✅ **String Safety:** Skips raw `String` returns to prevent `ClassCastException` with Spring's internal string message
+  converters.
 
-**Processing order:**
-1. String is trimmed (if `@AutoTrim` is present)
-2. Trimmed string is checked for HTML tags (if `@XssCheck` is present)
-3. If HTML tags found, `IllegalArgumentException` is thrown
+## 🔐 Built-in Security Features
 
-**Example:**
+The library provides fine-grained security and data processing features through field-level annotations. By default, **fields are NOT modified** unless explicitly annotated.
 
-```java
-// These will be rejected (after trimming):
-{"username": "  <script>alert(1)</script>  "}  // ✗ XSS attempt blocked
-{"username": "  <img src=x>  "}               // ✗ HTML tag blocked
-
-// These are accepted:
-{"username": "  john_doe  "}  // ✓ Trimmed to "john_doe"
-{"comment": "<comparison> 5 < 10"}  // ✗ Rejected (has HTML tag)
-{"email": "  user@example.com  "}  // ✓ Trimmed to "user@example.com"
-{"bio": "  <emphasis on quality>  "}  // ✓ Preserved as-is (no annotations)
-```
+### 1. Strict Property Validation 🛡️ (Automatic)
 
-### 5. Case-Insensitive Enum Handling 🎯 (Automatic)
+Rejects JSON payloads containing unexpected fields to prevent mass assignment attacks.
 
-**Better API usability without compromising type safety**
+### 2. Opt-in XSS Prevention with @XssCheck 🔒
 
-Allows flexible enum value formats from clients:
+Fail-fast HTML tag detection and rejection using regex pattern `(?s).*<\s*[a-zA-Z/!].*`.
 
 ```java
-public enum Status {
-    ACTIVE, INACTIVE, PENDING
-}
-
-// All of these work ✅
-{ "status": "ACTIVE" }
-{ "status": "active" }
-{ "status": "Active" }
-{ "status": "AcTiVe" }
-```
 
-### How It Works
+@XssCheck
+private String comment; // Rejects "<script>alert(1)</script>"
 
-These features are automatically configured via the `strictJsonCustomizer()` method in `ApiResponseAutoConfiguration`:
-
-```java
-@Bean
-public JsonMapperBuilderCustomizer strictJsonCustomizer() {
-    return builder -> {
-        // 1. Reject unknown properties (automatic)
-        builder.enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
-        
-        // 2. Allow case-insensitive enums (automatic)
-        builder.enable(MapperFeature.ACCEPT_CASE_INSENSITIVE_ENUMS);
-        
-        
-        // 3. Register AdvancedStringDeserializer for opt-in features
-        SimpleModule stringModule = new SimpleModule();
-        
-        class AdvancedStringDeserializer extends StdScalarDeserializer<String> {
-            private final boolean shouldTrim;
-            private final boolean shouldXssCheck;
-            
-            public AdvancedStringDeserializer() {
-                super(String.class);
-                this.shouldTrim = false;      // Default: NO trimming
-                this.shouldXssCheck = false;  // Default: NO XSS checking
-            }
-            
-            public AdvancedStringDeserializer(boolean shouldTrim, boolean shouldXssCheck) {
-                super(String.class);
-                this.shouldTrim = shouldTrim;
-                this.shouldXssCheck = shouldXssCheck;
-            }
-            
-            @Override
-            public String deserialize(JsonParser p, DeserializationContext ctxt) {
-                String value = p.getValueAsString();
-                if (value == null) return null;
-                
-                // Apply trimming only if @AutoTrim is present
-                String processedValue = shouldTrim ? value.trim() : value;
-                
-                // Validate for HTML tags only if @XssCheck is present
-                if (shouldXssCheck && processedValue.matches("(?s).*<\\s*[a-zA-Z/!].*")) {
-                    throw new IllegalArgumentException(
-                        "Security Error: HTML tags or XSS payloads are not allowed in the request."
-                    );
-                }
-                
-                return processedValue;
-            }
-            
-            @Override
-            public ValueDeserializer<?> createContextual(
-                    DeserializationContext ct, BeanProperty property) {
-                // Check for @AutoTrim and @XssCheck annotations on field
-                if (property != null) {
-                    boolean trim = property.getAnnotation(AutoTrim.class) != null;
-                    boolean xss = property.getAnnotation(XssCheck.class) != null;
-                    return new AdvancedStringDeserializer(trim, xss);
-                }
-                return this;
-            }
-        }
-        
-        stringModule.addDeserializer(String.class, new AdvancedStringDeserializer());
-        builder.addModules(stringModule);
-    };
-}
 ```
 
-**Key Features:**
-- **Opt-in by Default:** Fields are NOT modified unless explicitly annotated
-- **Fine-grained Control:** Each field can have different behavior via annotations
-- **Context-Aware:** Uses `createContextual()` to detect field annotations
-- **Four Modes:**
-  - No annotations: String preserved as-is
-  - `@AutoTrim` only: String is trimmed
-  - `@XssCheck` only: String is XSS-validated
-  - Both annotations: String is trimmed then XSS-validated
-- **Performance:** Deserializer created once per field at initialization, not per request
-
-### Disabling Security Features (Not Recommended)
+### 3. Opt-in String Trimming with @AutoTrim ✂️
 
-If you need to disable these features for specific use cases:
+Automatic whitespace removal for specific fields.
 
 ```java
-@Configuration
-public class CustomJacksonConfig {
-    
-    @Bean
-    @Primary  // Takes precedence over library's bean
-    public JsonMapperBuilderCustomizer myCustomizer() {
-        return builder -> {
-            // Your custom configuration
-            builder.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
-        };
-    }
-}
-```
 
-Or disable the entire auto-configuration:
+@AutoTrim
+private String username; // "  john_doe  " -> "john_doe"
 
-```properties
-spring.autoconfigure.exclude=io.github.og4dev.config.ApiResponseAutoConfiguration
 ```
 
-### Documentation
-
-For complete technical details, see the comprehensive Javadoc documentation:
-- 📚 [ApiResponseAutoConfiguration.strictJsonCustomizer()](https://javadoc.io/doc/io.github.og4dev/og4dev-spring-response/latest/io/github/og4dev/config/ApiResponseAutoConfiguration.html#strictJsonCustomizer())
+*(See full Security details in the Javadocs and examples above).*
 
 ## 🛡️ Built-in Exception Handling
 
-The library includes a **production-ready `GlobalExceptionHandler`** that automatically handles common exceptions using Spring Boot's **ProblemDetail (RFC 9457)** standard.
-
-### What's Included
-
-✅ **General Exception Handler** - Catches all unhandled exceptions (HTTP 500)  
-✅ **Validation Error Handler** - Automatically processes `@Valid` annotation failures (HTTP 400)  
-✅ **Type Mismatch Handler** - Handles method argument type conversion errors (HTTP 400)  
-✅ **Malformed JSON Handler** - Handles invalid JSON request bodies (HTTP 400)  
-✅ **Missing Parameter Handler** - Detects missing required request parameters (HTTP 400)  
-✅ **404 Not Found Handler** - Handles missing endpoints and resources (HTTP 404)  
-✅ **Method Not Allowed Handler** - Handles unsupported HTTP methods (HTTP 405)  
-✅ **Unsupported Media Type Handler** - Handles invalid Content-Type headers (HTTP 415)  
-✅ **Null Pointer Handler** - Specific handling for NullPointerException (HTTP 500)  
-✅ **Custom ApiException Handler** - Handles custom business exceptions extending `ApiException`  
-✅ **Automatic Logging** - SLF4J integration for all errors with consistent trace IDs  
-✅ **Trace ID Consistency** - Logs and responses always have matching trace IDs  
-✅ **Timestamp Support** - All error responses include RFC 3339 timestamps  
-✅ **RFC 9457 Compliance** - Standard ProblemDetail format (supersedes RFC 7807)
-
-### Trace ID Consistency 
-
-All exception handlers now ensure **consistent trace IDs** between logs and error responses:
-
-- **With TraceIdFilter**: Uses the trace ID from SLF4J MDC
-- **Without Filter**: Generates a UUID and stores it in MDC for consistent logging
-- **Guaranteed**: Logs and responses always have matching trace IDs
-
-**Example Log Output:**
-```
-2026-02-07 10:30:45.123 [550e8400-e29b-41d4-a716-446655440000] ERROR GlobalExceptionHandler - Error in SQLExceptionTranslator:112
-```
-
-**Matching Error Response:**
-```json
-{
-  "type": "about:blank",
-  "title": "Internal Server Error",
-  "status": 500,
-  "detail": "Internal Server Error. Please contact technical support",
-  "traceId": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2026-02-07T10:30:45.123Z"
-}
-```
-
-✅ **No more "N/A" trace IDs** - Every error has a real, correlatable trace ID  
-✅ **Easy debugging** - Copy trace ID from response and find all related logs  
-✅ **Thread-safe** - Proper MDC management ensures no cross-thread contamination  
-
-### Custom Business Exceptions 
+The library includes a **production-ready `GlobalExceptionHandler**` that automatically handles 10 common exceptions
+using Spring Boot's **ProblemDetail (RFC 9457)** standard.
 
-Instead of throwing generic exceptions, you can now extend the **abstract `ApiException` class** to create domain-specific exceptions with automatic exception handling:
+* **Automatic Logging:** SLF4J integration for all errors.
+* **Trace ID Consistency:** Logs and responses always have matching trace IDs.
+* **Custom Business Exceptions:** Extend the abstract `ApiException` class to create domain-specific exceptions.
 
 ```java
 public class ResourceNotFoundException extends ApiException {
@@ -694,2955 +336,106 @@ public class ResourceNotFoundException extends ApiException {
     }
 }
 
-public class UnauthorizedAccessException extends ApiException {
-    public UnauthorizedAccessException(String message) {
-        super(message, HttpStatus.UNAUTHORIZED);
-    }
-}
-
-public class BusinessRuleViolationException extends ApiException {
-    public BusinessRuleViolationException(String message) {
-        super(message, HttpStatus.CONFLICT);
-    }
-}
-```
-
-**Usage in Controllers:**
-
-```java
-@GetMapping("/{id}")
-public ResponseEntity<ApiResponse<User>> getUser(@PathVariable Long id) {
-    User user = userService.findById(id)
-        .orElseThrow(() -> new ResourceNotFoundException("User", id));
-    return ApiResponse.success("User retrieved successfully", user);
-}
-```
-
-**Automatic Error Response (RFC 9457):**
-```json
-{
-  "type": "about:blank",
-  "title": "Not Found",
-  "status": 404,
-  "detail": "User not found with ID: 123",
-  "traceId": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2026-02-02T10:30:45.123Z"
-}
-```
-
-The `GlobalExceptionHandler` automatically:
-- Extracts the HTTP status from your custom exception
-- Formats it as a ProblemDetail response
-- Logs the error with appropriate severity
-- Includes timestamps for traceability
-
-### Example: Validation Errors
-
-Add validation to your DTOs:
-
-```java
-public class UserDto {
-    @NotBlank(message = "Name is required")
-    private String name;
-    
-    @Email(message = "Email must be valid")
-    @NotBlank(message = "Email is required")
-    private String email;
-    
-    @Min(value = 18, message = "Age must be at least 18")
-    private Integer age;
-}
-```
-
-Use `@Valid` in your controller:
-
-```java
-@PostMapping
-public ResponseEntity<ApiResponse<User>> createUser(@Valid @RequestBody UserDto dto) {
-    User newUser = userService.create(dto);
-    return ApiResponse.created("User created successfully", newUser);
-}
-```
-
-**Automatic Error Response:**
-```json
-{
-  "type": "about:blank",
-  "title": "Bad Request",
-  "status": 400,
-  "detail": "Validation Failed",
-  "errors": {
-    "email": "Email must be valid",
-    "name": "Name is required",
-    "age": "Age must be at least 18"
-  },
-  "traceId": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2026-02-02T10:30:45.123Z"
-}
-```
-
-### Example: Malformed JSON Errors **
-
-When a client sends invalid JSON (missing quotes, commas, etc.):
-
-```bash
-# Request with malformed JSON
-POST /api/users
-Content-Type: application/json
-
-{
-  "name": "John Doe"
-  "email": "invalid"  # Missing comma
-}
 ```
 
-**Automatic Error Response:**
-```json
-{
-  "type": "about:blank",
-  "title": "Bad Request",
-  "status": 400,
-  "detail": "Malformed JSON request. Please check your request body format.",
-  "traceId": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2026-02-02T10:30:45.123Z"
-}
-```
-
-### Example: Missing Required Parameters **
+## 🌍 Real-World Examples
 
-When a required `@RequestParam` is missing:
+### Example 1: Clean CRUD Controller (Using @AutoResponse)
 
 ```java
-@GetMapping("/search")
-public ResponseEntity<ApiResponse<List<User>>> search(
-    @RequestParam(required = true) String query) {
-    // ...
-}
-```
-
-**Automatic Error Response:**
-```json
-{
-  "type": "about:blank",
-  "title": "Bad Request",
-  "status": 400,
-  "detail": "Required request parameter 'query' (type: String) is missing.",
-  "traceId": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2026-02-02T10:30:45.123Z"
-}
-```
-
-### Example: 404 Not Found **
-
-When accessing a non-existent endpoint or resource:
-
-```bash
-GET /api/nonexistent
-```
-
-**Automatic Error Response:**
-```json
-{
-  "type": "about:blank",
-  "title": "Not Found",
-  "status": 404,
-  "detail": "The requested resource '/api/nonexistent' was not found.",
-  "traceId": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2026-02-02T10:30:45.123Z"
-}
-```
-
-### Example: Method Not Allowed **
 
-When using an unsupported HTTP method:
-
-```bash
-# POST to an endpoint that only supports GET
-POST /api/users/123
-```
-
-**Automatic Error Response:**
-```json
-{
-  "type": "about:blank",
-  "title": "Method Not Allowed",
-  "status": 405,
-  "detail": "Method 'POST' is not supported for this endpoint. Supported methods are: [GET, PUT, DELETE]",
-  "traceId": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2026-02-02T10:30:45.123Z"
-}
-```
+@RestController
+@RequestMapping("/api/products")
+@RequiredArgsConstructor
+@AutoResponse // ✨ Zero boilerplate for the whole controller!
+public class ProductController {
 
-### Example: Unsupported Media Type **
+    private final ProductService productService;
 
-When sending an unsupported Content-Type:
+    @GetMapping
+    public Page<Product> getAllProducts(Pageable pageable) {
+        return productService.findAll(pageable);
+    }
 
-```bash
-POST /api/users
-Content-Type: application/xml
+    @GetMapping("/{id}")
+    public Product getProduct(@PathVariable Long id) {
+        return productService.findById(id)
+                .orElseThrow(() -> new ResourceNotFoundException("Product", id));
+    }
 
-<user><name>John</name></user>
-```
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED) // ✨ 201 Created preserved automatically
+    public Product createProduct(@Valid @RequestBody ProductDto dto) {
+        return productService.create(dto);
+    }
 
-**Automatic Error Response:**
-```json
-{
-  "type": "about:blank",
-  "title": "Unsupported Media Type",
-  "status": 415,
-  "detail": "Content type 'application/xml' is not supported. Supported content types: [application/json]",
-  "traceId": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2026-02-02T10:30:45.123Z"
+    @DeleteMapping("/{id}")
+    public void deleteProduct(@PathVariable Long id) {
+        productService.delete(id);
+        // Returns empty content with 200 OK automatically
+    }
 }
-```
-
-### Logging
-
-All exceptions are automatically logged with appropriate severity levels:
-- **ERROR level** - General exceptions and null pointer exceptions
-- **WARN level** - Validation errors, type mismatches, malformed JSON, missing parameters, 404 errors, method not allowed, unsupported media types, and business logic exceptions
 
 ```
-2026-02-02 10:30:45.123 WARN  i.g.p.e.GlobalExceptionHandler - Validation error: {email=Email must be valid, name=Name is required}
-2026-02-02 10:30:45.456 ERROR i.g.p.e.GlobalExceptionHandler - An unexpected error occurred:
-java.lang.RuntimeException: Database connection failed
-    at com.example.service.UserService.findById(UserService.java:42)
-2026-02-02 10:31:12.789 WARN  i.g.p.e.GlobalExceptionHandler - Malformed JSON request: JSON parse error: Unexpected character...
-2026-02-02 10:31:45.234 WARN  i.g.p.e.GlobalExceptionHandler - Missing parameter: Required request parameter 'query' (type: String) is missing.
-2026-02-02 10:32:15.567 WARN  i.g.p.e.GlobalExceptionHandler - 404 Not Found: The requested resource '/api/invalid' was not found.
-2026-02-02 10:32:45.890 WARN  i.g.p.e.GlobalExceptionHandler - Method not allowed: Method 'POST' is not supported for this endpoint.
-2026-02-02 10:33:15.123 WARN  i.g.p.e.GlobalExceptionHandler - Unsupported media type: Content type 'application/xml' is not supported.
-```
-```
-
-## 🔍 Distributed Tracing 
-
-The library provides **production-ready distributed tracing** with automatic trace ID generation and MDC (Mapped Diagnostic Context) integration for seamless log correlation across your microservices architecture.
 
-### Key Features
-
-✅ **Automatic Trace ID Generation** - Every response includes a unique UUID for request tracking  
-✅ **MDC Integration** - Trace IDs automatically available in all log statements via SLF4J MDC  
-✅ **TraceIdFilter** - Optional servlet filter for consistent trace ID management **  
-✅ **Flexible Priority** - Supports explicit trace IDs, MDC context, or auto-generation  
-✅ **Thread-Safe** - Proper MDC cleanup prevents memory leaks  
-✅ **Zero Configuration** - Works out of the box with sensible defaults  
-✅ **UUID Format** - Standard 128-bit globally unique identifiers  
-
-### Industry Standards Compatibility
-
-The trace ID implementation uses **UUID format** (128-bit), which is:
-- ✅ Widely supported across distributed systems
-- ✅ Compatible with most logging and APM tools
-- ✅ Globally unique without coordination
+## 📚 API Reference
 
-**For enhanced interoperability**, consider implementing header propagation to support:
-- `X-Trace-Id` / `X-Request-ID` (Common custom headers)
-- `X-B3-TraceId` (Zipkin/B3 format)
-- `traceparent` (W3C Trace Context standard)
+*(Refer to Javadoc for full details)*
 
-See the [Enhanced TraceIdFilter](#enhanced-traceidfilter-with-header-propagation) section below for implementation details.
+## 📈 Version History
 
-### How It Works
+### 1.4.0 (February 2026) - Current Release
 
-#### Default Behavior (Without Filter)
+✨ **New Features:**
 
-By default, `ApiResponse` automatically generates a trace ID for each response:
+* **@AutoResponse Annotation & GlobalResponseWrapper**
+* Opt-in automatic response wrapping to eliminate boilerplate code.
+* Returns raw DTOs from controllers and automatically wraps them in `ApiResponse<T>`.
+* Preserves HTTP status codes from `@ResponseStatus`.
+* Intelligently skips `ResponseEntity`, `ApiResponse`, `ProblemDetail`, and `String` to prevent double-wrapping and
+  casting errors.
 
-```java
-@GetMapping("/{id}")
-public ResponseEntity<ApiResponse<User>> getUser(@PathVariable Long id) {
-    User user = userService.findById(id);
-    return ApiResponse.success("User found", user);
-}
-```
 
-**Response:**
-```json
-{
-  "status": 200,
-  "message": "User found",
-  "content": { "id": 1, "name": "John" },
-  "timestamp": "2026-02-06T10:30:45.123Z"
-}
-```
+* **package-info.java documentation** added for the new `advice` package.
 
-**Note:** Success responses (ApiResponse) do NOT include `traceId`. Trace IDs are only included in error responses (ProblemDetail format) for debugging purposes.
-```
+### 1.3.0 (February 2026)
 
-#### Enhanced Tracing with TraceIdFilter
+* **Security Philosophy Change:** Complete redesign from automatic to opt-in approach for JSON sanitization.
+* Added **@AutoTrim** annotation for explicit string trimming.
+* Added **@XssCheck** annotation for explicit fail-fast XSS validation.
+* Extensive Javadoc and README updates regarding the new security model.
 
-For comprehensive distributed tracing, register the `TraceIdFilter` to automatically manage trace IDs across your entire request lifecycle:
+### 1.2.0 (February 2026)
 
-**Step 1: Register the Filter**
+* Added `@NoTrim` annotation (Legacy - removed in 1.3.0 in favor of opt-in model).
+* Enhanced Advanced String Deserializer.
 
-```java
-@Configuration
-public class FilterConfig {
-
-    @Bean
-    public FilterRegistrationBean<TraceIdFilter> traceIdFilter() {
-        FilterRegistrationBean<TraceIdFilter> registration = new FilterRegistrationBean<>();
-        registration.setFilter(new TraceIdFilter());
-        registration.addUrlPatterns("/*");
-        registration.setOrder(Ordered.HIGHEST_PRECEDENCE);
-        return registration;
-    }
-}
-```
+### 1.1.0 & 1.1.1 (February 2026)
 
-**Step 2: Automatic Benefits**
+* Added `GlobalExceptionHandler` and RFC 9457 Support.
+* Added `TraceIdFilter` and MDC Integration.
+* Verified Spring Boot 4.0.3 Compatibility.
 
-Once registered, the filter:
-1. Generates a unique UUID for each incoming request
-2. Stores it in SLF4J MDC (available for logging)
-3. Makes it available to `ApiResponse` automatically
-4. Cleans up MDC after request completion
+### 1.0.0 (February 2026)
 
-**Step 3: Trace ID in Logs**
+* Initial Release. Core `ApiResponse` wrapper.
 
-All your log statements automatically include the trace ID:
+---
 
-```java
-@Service
-@Slf4j
-public class UserService {
-    
-    public User findById(Long id) {
-        log.info("Finding user by ID: {}", id);  // Trace ID automatically included
-        // ... business logic
-        log.debug("User retrieved from database");
-        return user;
-    }
-}
-```
+## 🤝 Contributing
 
-**Log Output (with Logback configuration):**
-```
-2026-02-06 10:30:45.123 [a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d] INFO  c.e.s.UserService - Finding user by ID: 123
-2026-02-06 10:30:45.234 [a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d] DEBUG c.e.s.UserService - User retrieved from database
-```
+We welcome contributions! Please see the Contributing section above for details on our Apache 2.0 license terms and PR
+process.
 
-**Logback Configuration (logback-spring.xml):**
-```xml
-<configuration>
-    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
-        <encoder>
-            <pattern>%d{yyyy-MM-DD HH:mm:ss.SSS} [%X{traceId}] %-5level %logger{36} - %msg%n</pattern>
-        </encoder>
-    </appender>
-    
-    <root level="INFO">
-        <appender-ref ref="CONSOLE"/>
-    </root>
-</configuration>
-```
+## 📄 License
 
-### Trace ID Priority
+Licensed under the Apache License 2.0.
 
-The trace ID is resolved with the following priority:
+## 📧 Contact
 
-1. **Explicit Parameter** - If you explicitly set a trace ID via builder
-2. **MDC Context** - If `TraceIdFilter` has set a trace ID in MDC
-3. **Auto-Generated** - Falls back to a random UUID
-
-```java
-// Priority 1: Explicit trace ID
-UUID customId = UUID.randomUUID();
-ApiResponse.<User>builder()
-    .traceId(customId)  // This takes highest priority
-    .status(200)
-    .message("User found")
-    .content(user)
-    .build();
-
-// Priority 2: From MDC (when TraceIdFilter is active)
-// Automatically uses the filter-generated trace ID
-
-// Priority 3: Auto-generated (when no filter and no explicit ID)
-// Falls back to random UUID
-```
-
-### End-to-End Tracing Example
-
-**Scenario:** Client → API Gateway → User Service → Database
-
-```java
-// API Gateway receives request with trace ID
-@RestController
-@RequestMapping("/api/users")
-public class UserController {
-    
-    @GetMapping("/{id}")
-    public ResponseEntity<ApiResponse<User>> getUser(@PathVariable Long id) {
-        // TraceIdFilter already set MDC with trace ID
-        log.info("Received request for user: {}", id);
-        
-        User user = userService.findById(id);
-        
-        // Response automatically includes the same trace ID
-        return ApiResponse.success("User found", user);
-    }
-}
-
-@Service
-@Slf4j
-public class UserService {
-    
-    public User findById(Long id) {
-        // All logs automatically include trace ID from MDC
-        log.info("Finding user in database: {}", id);
-        
-        User user = userRepository.findById(id)
-            .orElseThrow(() -> {
-                log.warn("User not found: {}", id);
-                return new ResourceNotFoundException("User", id);
-            });
-            
-        log.info("User found: {}", user.getEmail());
-        return user;
-    }
-}
-```
-
-**Complete Request Flow:**
-```
-1. Request arrives → TraceIdFilter generates UUID: a1b2c3d4-...
-2. MDC.put("traceId", "a1b2c3d4-...")
-3. Controller logs: [a1b2c3d4-...] INFO - Received request for user: 123
-4. Service logs:    [a1b2c3d4-...] INFO - Finding user in database: 123
-5. Service logs:    [a1b2c3d4-...] INFO - User found: john@example.com
-6. Response includes: "traceId": "a1b2c3d4-..."
-7. MDC.clear() in finally block
-```
-
-### Propagating Trace IDs to Downstream Services
-
-For microservices architectures, propagate the trace ID to downstream services:
-
-```java
-@Service
-@RequiredArgsConstructor
-public class OrderService {
-    
-    private final RestTemplate restTemplate;
-    
-    public Order createOrder(OrderDto dto) {
-        // Get trace ID from MDC
-        String traceId = MDC.get("traceId");
-        
-        // Create headers with trace ID
-        HttpHeaders headers = new HttpHeaders();
-        headers.set("X-Trace-Id", traceId);
-        headers.setContentType(MediaType.APPLICATION_JSON);
-        
-        // Call downstream service
-        HttpEntity<OrderDto> request = new HttpEntity<>(dto, headers);
-        ResponseEntity<ApiResponse<Order>> response = restTemplate.exchange(
-            "http://payment-service/api/payments",
-            HttpMethod.POST,
-            request,
-            new ParameterizedTypeReference<ApiResponse<Order>>() {}
-        );
-        
-        return response.getBody().getContent();
-    }
-}
-```
-
-**Downstream Service (Payment Service):**
-```java
-@RestController
-@RequestMapping("/api/payments")
-public class PaymentController {
-    
-    @PostMapping
-    public ResponseEntity<ApiResponse<Payment>> processPayment(
-            @RequestHeader(value = "X-Trace-Id", required = false) String incomingTraceId,
-            @RequestBody PaymentDto dto) {
-        
-        // Use incoming trace ID if provided
-        if (incomingTraceId != null) {
-            MDC.put("traceId", incomingTraceId);
-        }
-        
-        Payment payment = paymentService.process(dto);
-        return ApiResponse.created("Payment processed", payment);
-    }
-}
-```
-
-### Testing with Trace IDs
-
-**Unit Tests:**
-```java
-@Test
-void testTraceIdInResponse() {
-    // Set trace ID in MDC (simulating TraceIdFilter)
-    String expectedTraceId = UUID.randomUUID().toString();
-    MDC.put("traceId", expectedTraceId);
-    
-    try {
-        ApiResponse<User> response = ApiResponse.<User>builder()
-            .status(200)
-            .message("Success")
-            .content(user)
-            .build();
-        
-        assertEquals(UUID.fromString(expectedTraceId), response.getTraceId());
-    } finally {
-        MDC.clear();
-    }
-}
-```
-
-**Integration Tests:**
-```java
-@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
-class UserControllerIntegrationTest {
-    
-    @Autowired
-    private TestRestTemplate restTemplate;
-    
-    @Test
-    void testTraceIdInApiResponse() {
-        ResponseEntity<ApiResponse<User>> response = restTemplate.exchange(
-            "/api/users/1",
-            HttpMethod.GET,
-            null,
-            new ParameterizedTypeReference<ApiResponse<User>>() {}
-        );
-        
-        assertNotNull(response.getBody().getTraceId());
-        // Trace ID should be in response
-    }
-}
-```
-
-### Benefits
-
-1. **Simplified Debugging** - Track requests across multiple services with a single ID
-2. **Log Correlation** - All logs for a request share the same trace ID
-3. **Performance Monitoring** - Identify slow requests by trace ID
-4. **Error Investigation** - Quickly find all logs related to a failed request
-5. **Distributed Systems** - Essential for microservices architecture
-6. **Production Ready** - No memory leaks with automatic MDC cleanup
-
-### Enhanced TraceIdFilter with Header Propagation
-
-For better interoperability with industry-standard distributed tracing systems, you can extend `TraceIdFilter` to support incoming trace ID headers and add trace IDs to response headers:
-
-```java
-package io.github.og4dev.filter;
-
-import jakarta.servlet.FilterChain;
-import jakarta.servlet.ServletException;
-import jakarta.servlet.http.HttpServletRequest;
-import jakarta.servlet.http.HttpServletResponse;
-import org.slf4j.MDC;
-import org.springframework.web.filter.OncePerRequestFilter;
-
-import java.io.IOException;
-import java.util.UUID;
-
-/**
- * Enhanced TraceIdFilter with industry-standard header support.
- * Supports incoming trace IDs from common headers and propagates to response.
- */
-public class EnhancedTraceIdFilter extends OncePerRequestFilter {
-
-    @Override
-    protected void doFilterInternal(HttpServletRequest request,
-                                    HttpServletResponse response,
-                                    FilterChain filterChain) throws ServletException, IOException {
-        UUID traceId = extractOrGenerateTraceId(request);
-
-        try {
-            request.setAttribute("traceId", traceId);
-            MDC.put("traceId", traceId.toString());
-
-            // Add trace ID to response header for downstream services
-            response.setHeader("X-Trace-Id", traceId.toString());
-
-            filterChain.doFilter(request, response);
-        } finally {
-            MDC.clear();
-        }
-    }
-
-    /**
-     * Extracts trace ID from standard headers or generates a new one.
-     * Checks headers in order of priority:
-     * 1. X-Trace-Id (custom)
-     * 2. X-Request-ID (common)
-     * 3. X-B3-TraceId (Zipkin)
-     * 4. traceparent (W3C Trace Context)
-     */
-    private UUID extractOrGenerateTraceId(HttpServletRequest request) {
-        // Check X-Trace-Id header
-        String traceId = request.getHeader("X-Trace-Id");
-
-        // Check X-Request-ID header
-        if (traceId == null) {
-            traceId = request.getHeader("X-Request-ID");
-        }
-
-        // Check X-B3-TraceId header (Zipkin format)
-        if (traceId == null) {
-            traceId = request.getHeader("X-B3-TraceId");
-        }
-
-        // Check W3C traceparent header
-        if (traceId == null) {
-            String traceparent = request.getHeader("traceparent");
-            if (traceparent != null) {
-                // Format: 00-{trace-id}-{span-id}-{flags}
-                String[] parts = traceparent.split("-");
-                if (parts.length >= 2) {
-                    traceId = parts[1]; // Extract trace-id
-                }
-            }
-        }
-
-        // Try to parse as UUID, or generate new one
-        if (traceId != null) {
-            try {
-                return UUID.fromString(traceId);
-            } catch (IllegalArgumentException e) {
-                // Invalid UUID format, generate new one
-            }
-        }
-
-        return UUID.randomUUID();
-    }
-}
-```
-
-**Register the Enhanced Filter:**
-
-```java
-@Configuration
-public class FilterConfig {
-
-    @Bean
-    public FilterRegistrationBean<EnhancedTraceIdFilter> traceIdFilter() {
-        FilterRegistrationBean<EnhancedTraceIdFilter> registration = new FilterRegistrationBean<>();
-        registration.setFilter(new EnhancedTraceIdFilter());
-        registration.addUrlPatterns("/*");
-        registration.setOrder(Ordered.HIGHEST_PRECEDENCE);
-        return registration;
-    }
-}
-```
-
-**Benefits of Enhanced Filter:**
-- ✅ Accepts trace IDs from upstream services (API Gateway, Load Balancer)
-- ✅ Supports multiple industry-standard header formats
-- ✅ Adds trace ID to response headers for downstream services
-- ✅ Maintains compatibility with W3C, Zipkin, and custom formats
-- ✅ Graceful fallback to UUID generation
-
-**Testing with cURL:**
-```bash
-# Send request with trace ID in header
-curl -H "X-Trace-Id: 12345678-1234-1234-1234-123456789012" \
-     http://localhost:8080/api/users/1
-
-# Check response header - trace ID is propagated
-HTTP/1.1 200 OK
-X-Trace-Id: 12345678-1234-1234-1234-123456789012
-
-# Success response body (no traceId field in ApiResponse)
-{
-  "status": 200,
-  "message": "User found",
-  "content": {...},
-  "timestamp": "2026-02-06T10:30:45.123Z"
-}
-
-# Error responses include traceId in body (ProblemDetail format)
-# For errors, the traceId appears in the response JSON:
-{
-  "type": "about:blank",
-  "title": "Not Found",
-  "status": 404,
-  "detail": "User not found",
-  "traceId": "12345678-1234-1234-1234-123456789012",
-  "timestamp": "2026-02-06T10:30:45.123Z"
-}
-```
-
-**Note:** 
-- Success responses (ApiResponse) do NOT have `traceId` in the response body
-- Error responses (ProblemDetail) DO include `traceId` for debugging
-- Both success and error responses can have `X-Trace-Id` header if TraceIdFilter is configured
-
-## 📖 Usage
-
-### Success Responses (HTTP 200)
-
-**With data:**
-```java
-@GetMapping
-public ResponseEntity<ApiResponse<List<User>>> getAllUsers() {
-    List<User> users = userService.findAll();
-    return ApiResponse.success("Users retrieved successfully", users);
-}
-```
-
-**Without data:**
-```java
-@DeleteMapping("/{id}")
-public ResponseEntity<ApiResponse<Void>> deleteUser(@PathVariable Long id) {
-    userService.delete(id);
-    return ApiResponse.success("User deleted successfully");
-}
-```
-
-### Created Responses (HTTP 201)
-
-```java
-@PostMapping
-public ResponseEntity<ApiResponse<User>> createUser(@RequestBody UserDto dto) {
-    User newUser = userService.create(dto);
-    return ApiResponse.created("User created successfully", newUser);
-}
-```
-
-### Custom Status Responses
-
-**Without data:**
-```java
-@GetMapping("/health")
-public ResponseEntity<ApiResponse<Void>> healthCheck() {
-    if (!service.isHealthy()) {
-        return ApiResponse.status("Service unavailable", HttpStatus.SERVICE_UNAVAILABLE);
-    }
-    return ApiResponse.success("Service is healthy");
-}
-```
-
-**With data:**
-```java
-@PutMapping("/{id}")
-public ResponseEntity<ApiResponse<User>> updateUser(
-        @PathVariable Long id, 
-        @RequestBody UserDto dto) {
-    User updated = userService.update(id, dto);
-    return ApiResponse.status("User updated", updated, HttpStatus.OK);
-}
-```
-
-## 🌍 Real-World Examples
-
-### Example 1: Complete CRUD Controller
-
-```java
-@RestController
-@RequestMapping("/api/products")
-@RequiredArgsConstructor
-@Slf4j
-public class ProductController {
-
-    private final ProductService productService;
-
-    @GetMapping
-    public ResponseEntity<ApiResponse<Page<Product>>> getAllProducts(
-            @PageableDefault(size = 20, sort = "createdAt", direction = Sort.Direction.DESC) Pageable pageable) {
-        Page<Product> products = productService.findAll(pageable);
-        return ApiResponse.success("Products retrieved successfully", products);
-    }
-
-    @GetMapping("/{id}")
-    public ResponseEntity<ApiResponse<Product>> getProduct(@PathVariable Long id) {
-        Product product = productService.findById(id)
-                .orElseThrow(() -> new ResourceNotFoundException("Product", id));
-        return ApiResponse.success("Product found", product);
-    }
-
-    @PostMapping
-    public ResponseEntity<ApiResponse<Product>> createProduct(
-            @Valid @RequestBody ProductDto dto) {
-        Product product = productService.create(dto);
-        log.info("Product created with ID: {}", product.getId());
-        return ApiResponse.created("Product created successfully", product);
-    }
-
-    @PutMapping("/{id}")
-    public ResponseEntity<ApiResponse<Product>> updateProduct(
-            @PathVariable Long id,
-            @Valid @RequestBody ProductDto dto) {
-        Product product = productService.update(id, dto);
-        return ApiResponse.success("Product updated successfully", product);
-    }
-
-    @DeleteMapping("/{id}")
-    public ResponseEntity<ApiResponse<Void>> deleteProduct(@PathVariable Long id) {
-        productService.delete(id);
-        return ApiResponse.success("Product deleted successfully");
-    }
-
-    @PatchMapping("/{id}/status")
-    public ResponseEntity<ApiResponse<Product>> updateStatus(
-            @PathVariable Long id,
-            @RequestParam ProductStatus status) {
-        Product product = productService.updateStatus(id, status);
-        return ApiResponse.success("Product status updated", product);
-    }
-}
-```
-
-### Example 2: File Upload with Progress
-
-```java
-@RestController
-@RequestMapping("/api/files")
-@RequiredArgsConstructor
-public class FileUploadController {
-
-    private final FileStorageService fileService;
-
-    @PostMapping("/upload")
-    public ResponseEntity<ApiResponse<FileMetadata>> uploadFile(
-            @RequestParam("file") MultipartFile file) {
-        
-        if (file.isEmpty()) {
-            throw new InvalidFileException("File cannot be empty");
-        }
-
-        if (file.getSize() > 10 * 1024 * 1024) { // 10MB limit
-            throw new FileTooLargeException("File size exceeds 10MB limit");
-        }
-
-        FileMetadata metadata = fileService.store(file);
-        return ApiResponse.created("File uploaded successfully", metadata);
-    }
-
-    @GetMapping("/{id}/download")
-    public ResponseEntity<Resource> downloadFile(@PathVariable String id) {
-        FileData fileData = fileService.load(id);
-        
-        return ResponseEntity.ok()
-                .contentType(MediaType.parseMediaType(fileData.getContentType()))
-                .header(HttpHeaders.CONTENT_DISPOSITION, 
-                        "attachment; filename=\"" + fileData.getFilename() + "\"")
-                .body(fileData.getResource());
-    }
-}
-
-// Custom exceptions
-public class InvalidFileException extends ApiException {
-    public InvalidFileException(String message) {
-        super(message, HttpStatus.BAD_REQUEST);
-    }
-}
-
-public class FileTooLargeException extends ApiException {
-    public FileTooLargeException(String message) {
-        super(message, HttpStatus.PAYLOAD_TOO_LARGE);
-    }
-}
-```
-
-### Example 3: Async Processing with Callbacks
-
-```java
-@RestController
-@RequestMapping("/api/reports")
-@RequiredArgsConstructor
-public class ReportController {
-
-    private final ReportService reportService;
-
-    @PostMapping("/generate")
-    public ResponseEntity<ApiResponse<ReportJob>> generateReport(
-            @Valid @RequestBody ReportRequest request) {
-        
-        ReportJob job = reportService.submitJob(request);
-        
-        return ApiResponse.status(
-                "Report generation started. Check status at /api/reports/" + job.getId(),
-                job,
-                HttpStatus.ACCEPTED
-        );
-    }
-
-    @GetMapping("/{jobId}/status")
-    public ResponseEntity<ApiResponse<ReportJobStatus>> getStatus(@PathVariable String jobId) {
-        ReportJobStatus status = reportService.getJobStatus(jobId);
-        
-        return switch (status.getState()) {
-            case COMPLETED -> ApiResponse.success("Report is ready", status);
-            case FAILED -> ApiResponse.status("Report generation failed", status, HttpStatus.INTERNAL_SERVER_ERROR);
-            case PROCESSING -> ApiResponse.status("Report is being generated", status, HttpStatus.ACCEPTED);
-            default -> ApiResponse.status("Report is queued", status, HttpStatus.ACCEPTED);
-        };
-    }
-}
-```
-
-### Example 4: Search with Filters
-
-```java
-@RestController
-@RequestMapping("/api/search")
-@RequiredArgsConstructor
-public class SearchController {
-
-    private final SearchService searchService;
-
-    @GetMapping("/products")
-    public ResponseEntity<ApiResponse<SearchResults<Product>>> searchProducts(
-            @RequestParam(required = false) String query,
-            @RequestParam(required = false) BigDecimal minPrice,
-            @RequestParam(required = false) BigDecimal maxPrice,
-            @RequestParam(required = false) List<String> categories,
-            @RequestParam(required = false) Boolean inStock,
-            Pageable pageable) {
-
-        SearchCriteria criteria = SearchCriteria.builder()
-                .query(query)
-                .minPrice(minPrice)
-                .maxPrice(maxPrice)
-                .categories(categories)
-                .inStock(inStock)
-                .build();
-
-        SearchResults<Product> results = searchService.search(criteria, pageable);
-        
-        String message = String.format("Found %d results", results.getTotalElements());
-        return ApiResponse.success(message, results);
-    }
-}
-```
-
-### Example 5: Batch Operations
-
-```java
-@RestController
-@RequestMapping("/api/batch")
-@RequiredArgsConstructor
-public class BatchOperationController {
-
-    private final BatchService batchService;
-
-    @PostMapping("/users/import")
-    public ResponseEntity<ApiResponse<BatchResult>> importUsers(
-            @RequestBody List<@Valid UserImportDto> users) {
-        
-        if (users.isEmpty()) {
-            throw new InvalidRequestException("User list cannot be empty");
-        }
-
-        if (users.size() > 1000) {
-            throw new BatchTooLargeException("Maximum 1000 users per batch");
-        }
-
-        BatchResult result = batchService.importUsers(users);
-        
-        String message = String.format(
-                "Batch completed: %d successful, %d failed",
-                result.getSuccessCount(),
-                result.getFailureCount()
-        );
-        
-        return ApiResponse.success(message, result);
-    }
-
-    @DeleteMapping("/users")
-    public ResponseEntity<ApiResponse<BatchDeleteResult>> deleteUsers(
-            @RequestBody List<Long> userIds) {
-        
-        BatchDeleteResult result = batchService.deleteUsers(userIds);
-        
-        return ApiResponse.success(
-                String.format("Deleted %d users", result.getDeletedCount()),
-                result
-        );
-    }
-}
-```
-
-### Example 6: Health Check & Monitoring
-
-```java
-@RestController
-@RequestMapping("/api")
-@RequiredArgsConstructor
-public class HealthController {
-
-    private final DatabaseHealthChecker dbHealthChecker;
-    private final CacheHealthChecker cacheHealthChecker;
-    private final ExternalApiHealthChecker apiHealthChecker;
-
-    @GetMapping("/health")
-    public ResponseEntity<ApiResponse<HealthStatus>> health() {
-        HealthStatus status = HealthStatus.builder()
-                .database(dbHealthChecker.check())
-                .cache(cacheHealthChecker.check())
-                .externalApi(apiHealthChecker.check())
-                .timestamp(Instant.now())
-                .build();
-
-        HttpStatus httpStatus = status.isHealthy() ? HttpStatus.OK : HttpStatus.SERVICE_UNAVAILABLE;
-        String message = status.isHealthy() ? "All systems operational" : "Some systems are down";
-        
-        return ApiResponse.status(message, status, httpStatus);
-    }
-
-    @GetMapping("/metrics")
-    public ResponseEntity<ApiResponse<SystemMetrics>> metrics() {
-        SystemMetrics metrics = SystemMetrics.builder()
-                .uptime(ManagementFactory.getRuntimeMXBean().getUptime())
-                .memoryUsage(Runtime.getRuntime().totalMemory() - Runtime.getRuntime().freeMemory())
-                .activeThreads(Thread.activeCount())
-                .timestamp(Instant.now())
-                .build();
-        
-        return ApiResponse.success("System metrics retrieved", metrics);
-    }
-}
-```
-
-### Error Handling with GlobalExceptionHandler
-
-**Version 2.0.0 includes a comprehensive `GlobalExceptionHandler`** with 10 built-in exception handlers using Spring Boot's `ProblemDetail` (RFC 9457) for standardized error responses:
-
-**Handled Exception Types:**
-1. ✅ **General Exceptions** (HTTP 500)
-2. ✅ **Validation Errors** (HTTP 400) - `@Valid` annotation failures
-3. ✅ **Type Mismatches** (HTTP 400) - Wrong parameter types
-4. ✅ **Malformed JSON** (HTTP 400) - Invalid request body **
-5. ✅ **Missing Parameters** (HTTP 400) - Required `@RequestParam` missing **
-6. ✅ **404 Not Found** (HTTP 404) - Missing endpoints/resources **
-7. ✅ **405 Method Not Allowed** (HTTP 405) - Wrong HTTP method **
-8. ✅ **415 Unsupported Media Type** (HTTP 415) - Invalid Content-Type **
-9. ✅ **Null Pointer Exceptions** (HTTP 500)
-10. ✅ **Custom ApiExceptions** - Domain-specific business logic errors
-
-```java
-package io.github.og4dev.exception;
-
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-import org.springframework.http.HttpStatus;
-import org.springframework.http.ProblemDetail;
-import org.springframework.http.converter.HttpMessageNotReadableException;
-import org.springframework.validation.FieldError;
-import org.springframework.web.HttpMediaTypeNotSupportedException;
-import org.springframework.web.HttpRequestMethodNotSupportedException;
-import org.springframework.web.bind.MethodArgumentNotValidException;
-import org.springframework.web.bind.MissingServletRequestParameterException;
-import org.springframework.web.bind.annotation.ExceptionHandler;
-import org.springframework.web.bind.annotation.RestControllerAdvice;
-import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
-import org.springframework.web.servlet.resource.NoResourceFoundException;
-
-import java.time.Instant;
-import java.util.HashMap;
-import java.util.Map;
-
-@RestControllerAdvice
-public class GlobalExceptionHandler {
-    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
-
-    // 10 comprehensive exception handlers included
-    // See full implementation in the source code
-
-    private String getOrGenerateTraceId() {
-        String traceId = MDC.get("traceId");
-        if (traceId == null) {
-            traceId = UUID.randomUUID().toString();
-            MDC.put("traceId", traceId);
-        }
-        return traceId;
-    }
-
-    @ExceptionHandler(Exception.class)
-    public ProblemDetail handleAllExceptions(Exception ex) {
-        String traceId = getOrGenerateTraceId();
-        log.error("[TraceID: {}] An unexpected error occurred: ", traceId, ex);
-        ProblemDetail problemDetail = ProblemDetail.forStatusAndDetail(
-                HttpStatus.INTERNAL_SERVER_ERROR,
-                "Internal Server Error. Please contact technical support"
-        );
-        problemDetail.setProperty("traceId", traceId);
-        problemDetail.setProperty("timestamp", Instant.now());
-        return problemDetail;
-    }
-
-    @ExceptionHandler(MethodArgumentNotValidException.class)
-    public ProblemDetail handleValidationExceptions(MethodArgumentNotValidException ex) {
-        String traceId = getOrGenerateTraceId();
-        Map<String, String> errorMessage = new HashMap<>();
-        for (FieldError fieldError : ex.getBindingResult().getFieldErrors()) {
-            errorMessage.merge(fieldError.getField(), fieldError.getDefaultMessage(),
-                    (msg1, msg2) -> msg1 + "; " + msg2);
-        }
-        log.warn("[TraceID: {}] Validation error: {}", traceId, errorMessage);
-        ProblemDetail problemDetail = ProblemDetail.forStatusAndDetail(
-                HttpStatus.BAD_REQUEST,
-                "Validation Failed"
-        );
-        problemDetail.setProperty("errors", errorMessage);
-        problemDetail.setProperty("traceId", traceId);
-        problemDetail.setProperty("timestamp", Instant.now());
-        return problemDetail;
-    }
-
-    @ExceptionHandler(NullPointerException.class)
-    public ProblemDetail handleNullPointerExceptions(NullPointerException ex) {
-        String traceId = getOrGenerateTraceId();
-        log.error("[TraceID: {}] Null pointer exception occurred: ", traceId, ex);
-        ProblemDetail problemDetail = ProblemDetail.forStatusAndDetail(
-                HttpStatus.INTERNAL_SERVER_ERROR,
-                "A null pointer exception occurred."
-        );
-        problemDetail.setProperty("traceId", traceId);
-        problemDetail.setProperty("timestamp", Instant.now());
-        return problemDetail;
-    }
-}
-```
-
-**The GlobalExceptionHandler provides:**
-- 🛡️ **ProblemDetail RFC 9457** - Latest standard error format (supersedes RFC 7807)
-- ✅ **Validation Error Handling** - Automatic `@Valid` annotation support
-- 📝 **Comprehensive Logging** - SLF4J integration with trace IDs
-- ⏰ **Automatic Timestamps** - On all error responses
-- 🔍 **Trace ID Generation** - Automatic UUID generation for all errors
-- 🔍 **Null Pointer Protection** - Dedicated NullPointerException handling
-- 📊 **10 Exception Handlers** - Covers all common error scenarios
-
-**Example Validation Error Response:**
-```json
-{
-  "type": "about:blank",
-  "title": "Bad Request",
-  "status": 400,
-  "detail": "Validation Failed",
-  "errors": {
-    "email": "must be a well-formed email address",
-    "name": "must not be blank"
-  },
-  "timestamp": "2026-02-02T10:30:45.123Z"
-}
-```
-
-You can also create custom exception handlers using ApiResponse:
-
-```java
-@ControllerAdvice
-public class CustomExceptionHandler {
-
-    @ExceptionHandler(ResourceNotFoundException.class)
-    public ResponseEntity<ApiResponse<Void>> handleNotFound(ResourceNotFoundException ex) {
-        return ApiResponse.status(ex.getMessage(), HttpStatus.NOT_FOUND);
-    }
-
-    @ExceptionHandler(IllegalArgumentException.class)
-    public ResponseEntity<ApiResponse<Void>> handleBadRequest(IllegalArgumentException ex) {
-        return ApiResponse.status("Invalid request: " + ex.getMessage(), HttpStatus.BAD_REQUEST);
-    }
-}
-```
-
-## 📚 API Reference
-
-### Static Factory Methods
-
-| Method | Parameters | Return Type | HTTP Status | Description |
-|--------|-----------|-------------|-------------|-------------|
-| `success(String message)` | message | `ResponseEntity<ApiResponse<Void>>` | 200 OK | Success without data |
-| `success(String message, T data)` | message, data | `ResponseEntity<ApiResponse<T>>` | 200 OK | Success with data |
-| `created(String message, T data)` | message, data | `ResponseEntity<ApiResponse<T>>` | 201 CREATED | Resource creation |
-| `status(String message, HttpStatus status)` | message, status | `ResponseEntity<ApiResponse<Void>>` | Custom | Custom status without data |
-| `status(String message, T data, HttpStatus status)` | message, data, status | `ResponseEntity<ApiResponse<T>>` | Custom | Custom status with data |
-
-### Response Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `status` | `Integer` | HTTP status code (e.g., 200, 201, 404) |
-| `message` | `String` | Human-readable message describing the response |
-| `content` | `T` (Generic) | Response payload (can be any type or null) |
-| `timestamp` | `Instant` | ISO-8601 formatted UTC timestamp (auto-generated) |
-
-## 🔍 Response Structure
-
-All **success responses** follow this consistent structure:
-
-```json
-{
-  "status": 200,
-  "message": "string",
-  "content": {},
-  "timestamp": "2026-02-06T10:30:45.123456Z"
-}
-```
-
-**Note:** `traceId` is NOT included in success responses. Trace IDs are only added to **error responses** (ProblemDetail format) by the GlobalExceptionHandler for debugging purposes.
-
-### Examples
-
-**Single Object:**
-```json
-{
-  "status": 200,
-  "message": "Product found",
-  "content": {
-    "id": 1,
-    "name": "Laptop",
-    "price": 999.99
-  },
-  "timestamp": "2026-02-01T10:30:45.123Z"
-}
-```
-
-**Array/List:**
-```json
-{
-  "status": 200,
-  "message": "Products retrieved",
-  "content": [
-    {"id": 1, "name": "Laptop"},
-    {"id": 2, "name": "Mouse"}
-  ],
-  "timestamp": "2026-02-01T10:30:45.123Z"
-}
-```
-
-**No Content (Void):**
-```json
-{
-  "status": 200,
-  "message": "Product deleted successfully",
-  "timestamp": "2026-02-01T10:30:45.123Z"
-}
-```
-
-**Error Response (ProblemDetail format with traceId):**
-```json
-{
-  "type": "about:blank",
-  "title": "Not Found",
-  "status": 404,
-  "detail": "Product not found with ID: 123",
-  "traceId": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2026-02-01T10:30:45.123Z"
-}
-```
-
-## 💡 Best Practices
-
-### 1. Use Appropriate Methods
-
-```java
-// ✅ Use success() for standard operations
-return ApiResponse.success("Retrieved", data);
-
-// ✅ Use created() for resource creation
-return ApiResponse.created("Created", newResource);
-
-// ✅ Use status() for custom status codes
-return ApiResponse.status("Accepted", HttpStatus.ACCEPTED);
-```
-
-### 2. Write Clear Messages
-
-```java
-// ✅ Good - Descriptive and specific
-return ApiResponse.success("User profile updated successfully", user);
-
-// ❌ Avoid - Too generic
-return ApiResponse.success("Success", user);
-```
-
-### 3. Leverage Generics
-
-```java
-// Specific types
-ResponseEntity<ApiResponse<User>> getUser();
-ResponseEntity<ApiResponse<List<Product>>> getProducts();
-ResponseEntity<ApiResponse<Map<String, Object>>> getMetadata();
-ResponseEntity<ApiResponse<Void>> deleteResource();
-```
-
-### 4. Custom Business Exceptions 
-
-**Version 1.3.0 includes an abstract `ApiException` class** for creating domain-specific exceptions. The built-in `GlobalExceptionHandler` automatically handles them with the correct HTTP status:
-
-```java
-// Define custom exceptions
-public class ResourceNotFoundException extends ApiException {
-    public ResourceNotFoundException(String resource, Long id) {
-        super(String.format("%s not found with ID: %d", resource, id), HttpStatus.NOT_FOUND);
-    }
-}
-
-public class InsufficientBalanceException extends ApiException {
-    public InsufficientBalanceException(String accountId) {
-        super("Insufficient balance in account: " + accountId, HttpStatus.PAYMENT_REQUIRED);
-    }
-}
-
-// Use them in your service/controller
-@GetMapping("/{id}")
-public ResponseEntity<ApiResponse<User>> getUser(@PathVariable Long id) {
-    User user = userRepository.findById(id)
-        .orElseThrow(() -> new ResourceNotFoundException("User", id));
-    return ApiResponse.success("User found", user);
-}
-```
-
-**Benefits:**
-- ✅ No need to manually create `@ExceptionHandler` methods
-- ✅ Automatic RFC 9457 ProblemDetail formatting
-- ✅ Type-safe with compile-time checking
-- ✅ Clean, readable code
-
-You can still create additional custom exception handlers if needed:
-
-```java
-@ControllerAdvice
-public class CustomExceptionHandler {
-    
-    @ExceptionHandler(ThirdPartyApiException.class)
-    public ProblemDetail handleThirdPartyError(ThirdPartyApiException ex) {
-        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
-            HttpStatus.BAD_GATEWAY, ex.getMessage()
-        );
-        problem.setProperty("timestamp", Instant.now());
-        return problem;
-    }
-}
-```
-
-### 5. RESTful Conventions
-
-```java
-@RestController
-@RequestMapping("/api/products")
-public class ProductController {
-
-    @GetMapping("/{id}")  // 200 OK
-    public ResponseEntity<ApiResponse<Product>> get(@PathVariable Long id) {
-        return ApiResponse.success("Product found", productService.findById(id));
-    }
-
-    @PostMapping  // 201 CREATED
-    public ResponseEntity<ApiResponse<Product>> create(@RequestBody ProductDto dto) {
-        return ApiResponse.created("Product created", productService.create(dto));
-    }
-
-    @PutMapping("/{id}")  // 200 OK
-    public ResponseEntity<ApiResponse<Product>> update(
-            @PathVariable Long id, @RequestBody ProductDto dto) {
-        return ApiResponse.success("Product updated", productService.update(id, dto));
-    }
-
-    @DeleteMapping("/{id}")  // 200 OK
-    public ResponseEntity<ApiResponse<Void>> delete(@PathVariable Long id) {
-        productService.delete(id);
-        return ApiResponse.success("Product deleted");
-    }
-}
-```
-
-## 🧪 Testing
-
-### Unit Testing with MockMvc
-
-```java
-@WebMvcTest(UserController.class)
-class UserControllerTest {
-
-    @Autowired
-    private MockMvc mockMvc;
-
-    @MockBean
-    private UserService userService;
-
-    @Test
-    void shouldReturnUserSuccessfully() throws Exception {
-        User user = new User(1L, "John Doe", "john@example.com");
-        when(userService.findById(1L)).thenReturn(user);
-
-        mockMvc.perform(get("/api/users/1"))
-                .andExpect(status().isOk())
-                .andExpect(jsonPath("$.status").value(200))
-                .andExpect(jsonPath("$.message").value("User retrieved successfully"))
-                .andExpect(jsonPath("$.data.id").value(1))
-                .andExpect(jsonPath("$.data.name").value("John Doe"))
-                .andExpect(jsonPath("$.traceId").exists())
-                .andExpect(jsonPath("$.timestamp").exists());
-    }
-
-    @Test
-    void shouldReturnCreatedStatus() throws Exception {
-        User newUser = new User(1L, "Jane Doe", "jane@example.com");
-        when(userService.create(any())).thenReturn(newUser);
-
-        mockMvc.perform(post("/api/users")
-                .contentType(MediaType.APPLICATION_JSON)
-                .content("{\"name\":\"Jane Doe\",\"email\":\"jane@example.com\"}"))
-                .andExpect(status().isCreated())
-                .andExpect(jsonPath("$.status").value(201))
-                .andExpect(jsonPath("$.message").value("User created successfully"))
-                .andExpect(jsonPath("$.data.id").value(1))
-                .andExpect(jsonPath("$.traceId").exists());
-    }
-    
-    @Test
-    void shouldReturnValidationErrors() throws Exception {
-        mockMvc.perform(post("/api/users")
-                .contentType(MediaType.APPLICATION_JSON)
-                .content("{\"name\":\"\",\"email\":\"invalid\"}"))
-                .andExpect(status().isBadRequest())
-                .andExpect(jsonPath("$.status").value(400))
-                .andExpect(jsonPath("$.detail").value("Validation Failed"))
-                .andExpect(jsonPath("$.errors.name").exists())
-                .andExpect(jsonPath("$.errors.email").exists())
-                .andExpect(jsonPath("$.timestamp").exists());
-    }
-    
-    @Test
-    void shouldHandleCustomException() throws Exception {
-        when(userService.findById(999L))
-                .thenThrow(new ResourceNotFoundException("User", 999L));
-
-        mockMvc.perform(get("/api/users/999"))
-                .andExpect(status().isNotFound())
-                .andExpect(jsonPath("$.status").value(404))
-                .andExpect(jsonPath("$.detail").value("User not found with ID: 999"))
-                .andExpect(jsonPath("$.timestamp").exists());
-    }
-}
-```
-
-### Integration Testing with TestRestTemplate
-
-```java
-@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
-class UserControllerIntegrationTest {
-
-    @Autowired
-    private TestRestTemplate restTemplate;
-
-    @Test
-    void shouldGetUser() {
-        ResponseEntity<ApiResponse> response = restTemplate.getForEntity(
-                "/api/users/1", ApiResponse.class);
-
-        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
-        assertThat(response.getBody().getStatus()).isEqualTo(200);
-        assertThat(response.getBody().getMessage()).contains("User");
-        assertThat(response.getBody().getTraceId()).isNotNull();
-        assertThat(response.getBody().getTimestamp()).isNotNull();
-    }
-
-    @Test
-    void shouldCreateUser() {
-        UserDto newUser = new UserDto("Jane Doe", "jane@example.com");
-        
-        ResponseEntity<ApiResponse> response = restTemplate.postForEntity(
-                "/api/users", newUser, ApiResponse.class);
-
-        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
-        assertThat(response.getBody().getStatus()).isEqualTo(201);
-    }
-}
-```
-
-### Testing Custom Exceptions
-
-```java
-@ExtendWith(MockitoExtension.class)
-class CustomExceptionTest {
-
-    @Test
-    void shouldThrowResourceNotFoundException() {
-        ResourceNotFoundException exception = 
-            new ResourceNotFoundException("User", 123L);
-
-        assertThat(exception.getMessage()).isEqualTo("User not found with ID: 123");
-        assertThat(exception.getStatus()).isEqualTo(HttpStatus.NOT_FOUND);
-    }
-}
-```
-
-### Testing with WebTestClient (WebFlux)
-
-If you adapt the library for reactive applications:
-
-```java
-@WebFluxTest(UserController.class)
-class UserControllerWebFluxTest {
-
-    @Autowired
-    private WebTestClient webTestClient;
-
-    @MockBean
-    private UserService userService;
-
-    @Test
-    void shouldReturnUser() {
-        User user = new User(1L, "John Doe", "john@example.com");
-        when(userService.findById(1L)).thenReturn(Mono.just(user));
-
-        webTestClient.get()
-                .uri("/api/users/1")
-                .exchange()
-                .expectStatus().isOk()
-                .expectBody()
-                .jsonPath("$.status").isEqualTo(200)
-                .jsonPath("$.data.name").isEqualTo("John Doe")
-                .jsonPath("$.traceId").exists();
-    }
-}
-```
-        User newUser = new User(1L, "Jane Doe", "jane@example.com");
-        when(userService.create(any())).thenReturn(newUser);
-
-        mockMvc.perform(post("/api/users")
-                .contentType(MediaType.APPLICATION_JSON)
-                .content("{\"name\":\"Jane Doe\",\"email\":\"jane@example.com\"}"))
-                .andExpect(status().isCreated())
-                .andExpect(jsonPath("$.status").value(201))
-                .andExpect(jsonPath("$.message").value("User created successfully"))
-                .andExpect(jsonPath("$.data.id").value(1))
-                .andExpect(jsonPath("$.traceId").exists());
-    }
-}
-```
-
-## 🏗️ Architecture & Design Principles
-
-### Thread Safety & Immutability
-
-The `ApiResponse<T>` class is designed with **immutability** at its core:
-
-- All fields are declared as `final`
-- No setter methods exist (only getters)
-- Uses a custom inner Builder class for object construction
-- Thread-safe by design - can be safely shared across threads
-
-```java
-// Once created, the response cannot be modified
-ApiResponse<User> response = new ApiResponse.ApiResponseBuilder<User>()
-    .message("Success")
-    .content(user)
-    .build();
-
-// This is thread-safe and can be safely cached or shared
-```
-
-### Dependency Management
-
-The library uses **provided scope** for Spring Boot:
-
-```xml
-<dependency>
-    <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-starter-web</artifactId>
-    <scope>provided</scope>  <!-- Will not bloat your application -->
-</dependency>
-```
-
-**Benefits:**
-- ✅ **No Dependency Conflicts** - Uses your application's existing Spring Boot version
-- ✅ **Zero External Dependencies** - Pure Java implementation, no Lombok or other libraries required
-- ✅ **Zero Bloat** - Adds only ~10KB to your application
-- ✅ **Version Flexibility** - Compatible with Spring Boot 3.2.0 - 4.0.3 and Java 17+
-
-### Auto-Configuration Architecture
-
-```
-┌─────────────────────────────────────────────────────┐
-│  Spring Boot Application Starts                     │
-└─────────────┬───────────────────────────────────────┘
-              │
-              ▼
-┌─────────────────────────────────────────────────────┐
-│  Reads META-INF/spring/                             │
-│  org.springframework.boot.autoconfigure             │
-│  .AutoConfiguration.imports                         │
-└─────────────┬───────────────────────────────────────┘
-              │
-              ▼
-┌─────────────────────────────────────────────────────┐
-│  Loads ApiResponseAutoConfiguration                 │
-└─────────────┬───────────────────────────────────────┘
-              │
-              ▼
-┌─────────────────────────────────────────────────────┐
-│  Registers GlobalExceptionHandler Bean              │
-│  (as @RestControllerAdvice)                         │
-└─────────────┬───────────────────────────────────────┘
-              │
-              ▼
-┌─────────────────────────────────────────────────────┐
-│  Ready to Handle Exceptions Automatically           │
-└─────────────────────────────────────────────────────┘
-```
-
-### Design Patterns Used
-
-- **Factory Pattern** - Static factory methods (`success()`, `created()`, `status()`)
-- **Builder Pattern** - Custom inner Builder class for flexible object construction
-- **Template Method Pattern** - `ApiException` abstract class for custom exceptions
-- **Advisor Pattern** - `GlobalExceptionHandler` with `@RestControllerAdvice`
-
-## 🔌 OpenAPI/Swagger Integration
-
-Works seamlessly with SpringDoc OpenAPI:
-
-```java
-@Operation(summary = "Get user by ID", description = "Returns a single user")
-@ApiResponses(value = {
-    @ApiResponse(responseCode = "200", description = "User found"),
-    @ApiResponse(responseCode = "404", description = "User not found")
-})
-@GetMapping("/{id}")
-public ResponseEntity<ApiResponse<User>> getUser(@PathVariable Long id) {
-    User user = userService.findById(id);
-    return ApiResponse.success("User retrieved successfully", user);
-}
-```
-
-**Add SpringDoc dependency:**
-```xml
-<dependency>
-    <groupId>org.springdoc</groupId>
-    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
-    <version>2.3.0</version>
-</dependency>
-```
-
-## 🔄 Compatibility Matrix
-
-### Tested Compatibility
-
-| Library Version | Java Version | Spring Boot Version | Status |
-|----------------|--------------|---------------------|--------|
-| 1.3.0 | 17, 21+ | 3.2.0 - 4.0.3 | ✅ Tested |
-| 1.2.0 | 17, 21+ | 3.2.0 - 4.0.3 | ✅ Tested |
-| 1.1.1 | 17, 21+ | 3.2.0 - 4.0.3 | ✅ Tested |
-| 1.1.0 | 17, 21+ | 3.2.0 - 4.0.2 | ✅ Tested |
-| 1.0.0 | 17, 21+ | 3.2.0+ | ✅ Tested |
-
-### Version Requirements
-
-**Minimum Requirements:**
-- **Java:** 17 or higher
-- **Spring Boot:** 3.2.0 or higher (tested up to 4.0.3)
-- **Dependencies:** None (pure Java implementation)
-
-**Recommended:**
-- **Java:** 21 (LTS)
-- **Spring Boot:** 3.4.x or 4.0.x (fully compatible with Spring Boot 4)
-
-### Spring Boot 4.x Support
-
-✅ **Full Spring Boot 4.0.3 Compatibility**
-- The library has been tested and verified to work with Spring Boot 4.0.3
-- All features including auto-configuration work seamlessly
-- No breaking changes when upgrading from Spring Boot 3.x to 4.x
-- Uses provided scope dependencies to avoid version conflicts
-
-### Framework Compatibility
-
-| Framework | Supported | Notes |
-|-----------|-----------|-------|
-| Spring Boot 4.x | ✅ Yes | Full support with version 4.0.3 |
-| Spring Boot 3.x | ✅ Yes | Full support with auto-configuration |
-| Spring Boot 2.x | ❌ No | Use Spring Boot 3.x+ |
-| Spring WebFlux | ⚠️ Partial | Manual adaptation required |
-| Micronaut | ❌ No | Spring-specific features used |
-| Quarkus | ❌ No | Spring-specific features used |
-
-### Build Tools
-
-| Build Tool | Supported | Configuration |
-|------------|-----------|---------------|
-| Maven | ✅ Yes | Native support |
-| Gradle | ✅ Yes | Groovy & Kotlin DSL |
-| Gradle (Groovy) | ✅ Yes | `implementation 'io.github.og4dev:og4dev-spring-response:1.0.0'` |
-| Gradle (Kotlin) | ✅ Yes | `implementation("io.github.og4dev:og4dev-spring-response:1.0.0")` |
-
-## 🔧 Troubleshooting
-
-### Common Issues & Solutions
-
-#### 1. GlobalExceptionHandler Not Working
-
-**Problem:** Exceptions are not being caught by the GlobalExceptionHandler.
-
-**Solution:**
-- Check that auto-configuration is not excluded
-- Verify Spring Boot version is 3.2.0+
-
-```java
-// Verify auto-configuration is active
-@SpringBootApplication
-// Do NOT exclude ApiResponseAutoConfiguration
-public class Application {
-    public static void main(String[] args) {
-        SpringApplication.run(Application.class, args);
-    }
-}
-```
-
-#### 2. Response Fields Not Serializing
-
-**Problem:** Some fields like `status`, `message`, or `content` are missing in JSON responses.
-
-**Solution:**
-- The library uses `@JsonInclude(JsonInclude.Include.NON_NULL)` to exclude null fields
-- This is intentional behavior - only non-null fields are included in the response
-- To include all fields, you would need to customize Jackson's configuration in your application
-
-#### 3. Auto-Configuration Not Working
-
-**Problem:** GlobalExceptionHandler is not being picked up automatically.
-
-**Solution:**
-- Ensure you're using Spring Boot 3.2.0 or higher
-- Check that the library JAR is on the classpath
-- Verify `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` exists in the JAR
-- Check application logs for auto-configuration reports
-
-#### 4. Version Conflicts with Spring Boot
-    .status(200)
-    .traceId(UUID.randomUUID())  // Must set manually
-    .message("Success")
-    .content(data)
-    .build());
-```
-
-- For **error responses**, trace IDs are **automatically generated** by GlobalExceptionHandler
-- All error logs and responses have matching trace IDs for easy correlation
-
-#### 4. Dependency Conflicts
-
-**Problem:** Version conflicts with Spring Boot.
-
-**Solution:**
-- The library uses `provided` scope for Spring Boot - it won't conflict
-- Ensure your application has Spring Boot Web dependency:
-
-```xml
-<dependency>
-    <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-starter-web</artifactId>
-</dependency>
-```
-
-#### 5. Custom Exception Not Being Caught
-
-**Problem:** Custom `ApiException` subclass not returning ProblemDetail.
-
-**Solution:**
-- Ensure your exception extends `ApiException`
-- Verify the exception is actually being thrown
-- Check GlobalExceptionHandler is registered
-
-```java
-// ✅ Correct
-public class MyException extends ApiException {
-    public MyException(String message) {
-        super(message, HttpStatus.BAD_REQUEST);
-    }
-}
-
-// ❌ Wrong - must extend ApiException
-public class MyException extends RuntimeException {
-    // ...
-}
-```
-
-#### 6. Timestamp Format Issues
-
-**Problem:** Timestamp format not as expected.
-
-**Solution:**
-- The library uses `Instant` (UTC) by default
-- Configure Jackson if you need different format:
-
-```java
-@Configuration
-public class JacksonConfig {
-    @Bean
-    public ObjectMapper objectMapper() {
-        ObjectMapper mapper = new ObjectMapper();
-        mapper.registerModule(new JavaTimeModule());
-        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
-        return mapper;
-    }
-}
-```
-
-#### 7. Auto-Configuration Not Loading
-
-**Problem:** Auto-configuration doesn't work.
-
-**Solution:**
-- Verify you're using Spring Boot 3.x (not 2.x)
-- Check the JAR includes `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`
-- Clear Maven/Gradle cache and rebuild:
-
-```bash
-# Maven
-mvn clean install
-
-# Gradle
-./gradlew clean build --refresh-dependencies
-```
-
-#### 8. Jackson Serialization Issues
-
-**Problem:** Fields are not serializing as expected or timestamp format is wrong.
-
-**Solution:**
-- The library uses Jackson's `@JsonInclude(NON_NULL)` by default
-- Ensure you have `jackson-datatype-jsr310` for Java 8+ date/time support (included in Spring Boot)
-- Configure Jackson if needed:
-
-```java
-@Configuration
-public class JacksonConfig {
-    @Bean
-    public ObjectMapper objectMapper() {
-        ObjectMapper mapper = new ObjectMapper();
-        mapper.registerModule(new JavaTimeModule());
-        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
-        mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
-        return mapper;
-    }
-}
-```
-
-#### 9. UUID Not Serializing Properly
-
-**Problem:** TraceId appears as an object instead of string.
-
-**Solution:**
-- This shouldn't happen with standard Jackson configuration
-- Verify Jackson version is compatible with Spring Boot
-- UUID is serialized as string by default in Jackson
-
-```json
-// ✅ Correct
-"traceId": "550e8400-e29b-41d4-a716-446655440000"
-
-// ❌ Wrong (shouldn't happen)
-"traceId": {"mostSigBits": 123, "leastSigBits": 456}
-```
-
-### Getting Help
-
-If you encounter issues not covered here:
-
-1. **Check the Issues:** [GitHub Issues](https://github.com/OG4Dev/og4dev-spring-response/issues)
-2. **Review JavaDocs:** All classes are fully documented
-3. **Enable Debug Logging:**
-   ```properties
-   logging.level.io.github.og4dev=DEBUG
-   ```
-4. **Open an Issue:** Provide minimal reproducible example
-
-## ❓ FAQ
-
-### How do I use trace IDs for debugging? **
-
-**Error responses** automatically include a `traceId` (UUID) in the ProblemDetail format for request tracking and debugging. Success responses (ApiResponse) do NOT include traceId in the response body, but you can add trace IDs via headers using the TraceIdFilter.
-
-**Key Points:**
-- ✅ **Error responses** - traceId is automatically included in ProblemDetail JSON
-- ❌ **Success responses** - traceId is NOT in ApiResponse JSON (use headers instead)
-- 🔍 **Logging** - All exceptions are logged with [TraceID: xxx] for correlation
-
-For comprehensive distributed tracing with MDC integration and header propagation, see the **Distributed Tracing** section above.
-
-**Quick Example with TraceIdFilter:**
-
-```java
-// 1. Register TraceIdFilter for header propagation
-@Configuration
-public class FilterConfig {
-    @Bean
-    public FilterRegistrationBean<TraceIdFilter> traceIdFilter() {
-        FilterRegistrationBean<TraceIdFilter> registration = new FilterRegistrationBean<>();
-        registration.setFilter(new TraceIdFilter());
-        registration.addUrlPatterns("/*");
-        registration.setOrder(Ordered.HIGHEST_PRECEDENCE);
-        return registration;
-    }
-}
-
-// 2. Use in your service (trace ID automatically in logs)
-@Service
-@Slf4j
-public class UserService {
-    public User createUser(UserDto dto) {
-        log.info("Creating user with email: {}", dto.getEmail());  // [traceId] in logs
-        // ... business logic
-        return user;
-    }
-}
-```
-
-**For industry-standard header propagation** (accepting trace IDs from upstream services), use the **[Enhanced TraceIdFilter](#enhanced-traceidfilter-with-header-propagation)** which supports:
-- `X-Trace-Id` and `X-Request-ID` headers
-- `X-B3-TraceId` (Zipkin format)
-- `traceparent` (W3C Trace Context)
-- Automatic response header injection
-}
-```
-
-**Response:**
-```json
-{
-  "status": 200,
-  "message": "User created",
-  "content": {...},
-  "timestamp": "2026-02-06T10:30:45.123Z"
-}
-```
-
-**Note:** The traceId is in the MDC for logging and can be added to response headers, but is NOT in the ApiResponse JSON body.
-
-**Logs (with traceId from MDC):**
-```
-2026-02-06 10:30:45.123 [550e8400-e29b-41d4-a716-446655440000] INFO c.e.s.UserService - Creating user with email: john@example.com
-```
-```
-
-For more details on MDC integration, propagating trace IDs to downstream services, and end-to-end tracing examples, see the **[Distributed Tracing](#-distributed-tracing-enhanced-in-v200)** section.
-```
-
-### How do I create custom business exceptions?
-
-Extend the abstract `ApiException` class to create domain-specific exceptions:
-
-```java
-public class ResourceNotFoundException extends ApiException {
-    public ResourceNotFoundException(String resource, Long id) {
-        super(String.format("%s not found with ID: %d", resource, id), HttpStatus.NOT_FOUND);
-    }
-}
-
-public class DuplicateResourceException extends ApiException {
-    public DuplicateResourceException(String message) {
-        super(message, HttpStatus.CONFLICT);
-    }
-}
-```
-
-Then throw them in your code - the `GlobalExceptionHandler` will automatically convert them to RFC 9457 ProblemDetail responses:
-
-```java
-@GetMapping("/{id}")
-public ResponseEntity<ApiResponse<User>> getUser(@PathVariable Long id) {
-    User user = userRepository.findById(id)
-        .orElseThrow(() -> new ResourceNotFoundException("User", id));
-    return ApiResponse.success("User found", user);
-}
-```
-
-### How do I use the built-in GlobalExceptionHandler?
-
-The `GlobalExceptionHandler` is **automatically configured** via Spring Boot Auto-Configuration. No manual setup is required!
-
-Simply add the library dependency, and the exception handler will be active immediately. The auto-configuration mechanism automatically registers the handler when the library is detected on the classpath.
-
-### Can I customize or extend the GlobalExceptionHandler?
-
-Yes! You can add your own `@ControllerAdvice` handlers alongside the built-in one:
-
-```java
-@ControllerAdvice
-public class CustomExceptionHandler {
-    
-    @ExceptionHandler(ResourceNotFoundException.class)
-    public ResponseEntity<ApiResponse<Void>> handleNotFound(ResourceNotFoundException ex) {
-        return ApiResponse.status(ex.getMessage(), HttpStatus.NOT_FOUND);
-    }
-    
-    @ExceptionHandler(UnauthorizedException.class)
-    public ProblemDetail handleUnauthorized(UnauthorizedException ex) {
-        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
-            HttpStatus.UNAUTHORIZED, ex.getMessage()
-        );
-        problem.setProperty("timestamp", Instant.now());
-        return problem;
-    }
-}
-```
-
-### How do I disable the GlobalExceptionHandler?
-
-You can disable it by excluding the auto-configuration:
-
-```java
-@SpringBootApplication(exclude = ApiResponseAutoConfiguration.class)
-public class Application {
-    public static void main(String[] args) {
-        SpringApplication.run(Application.class, args);
-    }
-}
-```
-
-Or in `application.properties`:
-```properties
-spring.autoconfigure.exclude=io.github.og4dev.config.ApiResponseAutoConfiguration
-```
-
-### How do I customize the timestamp format?
-
-Configure Jackson's ObjectMapper:
-
-```java
-@Configuration
-public class JacksonConfig {
-    @Bean
-    public ObjectMapper objectMapper() {
-        ObjectMapper mapper = new ObjectMapper();
-        mapper.registerModule(new JavaTimeModule());
-        mapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);
-        return mapper;
-    }
-}
-```
-
-### Can I add custom fields?
-
-The library provides a standard structure. To add custom fields, wrap the response:
-
-```java
-public class ExtendedResponse<T> {
-    private ApiResponse<T> response;
-    private String requestId;
-    private Map<String, String> metadata;
-    // getters and setters
-}
-```
-
-### Does this work with Spring WebFlux?
-
-Currently designed for Spring MVC. For WebFlux, you'd need to adapt it to work with `Mono<ResponseEntity<ApiResponse<T>>>`.
-
-### How do I handle paginated responses?
-
-Use Spring's `Page` as the data type:
-
-```java
-@GetMapping
-public ResponseEntity<ApiResponse<Page<User>>> getUsers(Pageable pageable) {
-    Page<User> users = userService.findAll(pageable);
-    return ApiResponse.success("Users retrieved", users);
-}
-```
-
-### Why use this over plain ResponseEntity?
-
-| Plain ResponseEntity | ApiResponse |
-|---------------------|-------------|
-| Inconsistent structure | ✅ Standardized everywhere |
-| Manual timestamps | ✅ Automatic |
-| No trace IDs | ✅ Built-in UUID trace IDs |
-| No status in body | ✅ Status code included in response |
-| Manual exception handling | ✅ Custom ApiException support |
-| More boilerplate | ✅ Concise factory methods |
-| No message field | ✅ Always includes message |
-
-## 🚀 Performance & Best Practices
-
-### Performance Characteristics
-
-- **Response Creation:** < 1ms (simple object instantiation with builder pattern)
-- **Memory Footprint:** ~200 bytes per response object (excluding data payload)
-- **Thread Safety:** 100% thread-safe (immutable design with final fields)
-- **GC Impact:** Minimal (uses immutable objects, eligible for quick collection)
-- **JSON Serialization:** Optimized with `@JsonInclude(NON_NULL)` to reduce payload size
-- **UUID Generation:** Negligible overhead (~0.1ms per UUID using `UUID.randomUUID()`)
-- **Timestamp Generation:** Negligible overhead (~0.01ms using `Instant.now()`)
-
-### Benchmark Results (Approximate)
-
-| Operation | Time | Notes |
-|-----------|------|-------|
-| `ApiResponse.success()` | ~0.5ms | Including UUID and timestamp generation |
-| `ApiResponse.created()` | ~0.5ms | Same as success() |
-| `ApiResponse.builder().build()` | ~0.3ms | Manual builder without factory methods |
-| JSON Serialization (small DTO) | ~1-2ms | Standard Jackson performance |
-| GlobalExceptionHandler catch | ~0.1ms | Minimal overhead for exception transformation |
-
-### Best Practices
-
-#### 1. Prefer Factory Methods Over Builder
-
-```java
-// ✅ RECOMMENDED - Auto-generates trace ID and timestamp
-return ApiResponse.success("User found", user);
-
-// ⚠️ AVOID - More verbose, manual field management
-return ResponseEntity.ok(ApiResponse.<User>builder()
-    .status(200)
-    .traceId(UUID.randomUUID())
-    .message("User found")
-    .data(user)
-    .timestamp(Instant.now())
-    .build());
-```
-
-#### 2. Use Appropriate HTTP Status Codes
-
-```java
-// ✅ POST - Use created() for 201
-@PostMapping
-public ResponseEntity<ApiResponse<User>> create(@RequestBody UserDto dto) {
-    return ApiResponse.created("User created", userService.create(dto));
-}
-
-// ✅ DELETE - Use success() with no data
-@DeleteMapping("/{id}")
-public ResponseEntity<ApiResponse<Void>> delete(@PathVariable Long id) {
-    userService.delete(id);
-    return ApiResponse.success("User deleted");
-}
-
-// ✅ Custom status - Use status() method
-@GetMapping("/health")
-public ResponseEntity<ApiResponse<Void>> health() {
-    return ApiResponse.status("Service degraded", HttpStatus.SERVICE_UNAVAILABLE);
-}
-```
-
-#### 3. Write Descriptive Messages
-
-```java
-// ✅ GOOD - Clear and actionable
-return ApiResponse.success("User profile updated successfully", updatedUser);
-
-// ❌ BAD - Too generic
-return ApiResponse.success("Success", updatedUser);
-
-// ❌ BAD - Technical jargon
-return ApiResponse.success("User entity persisted to database", updatedUser);
-```
-
-#### 4. Handle Exceptions Properly
-
-```java
-// ✅ GOOD - Use custom ApiException
-public class InsufficientFundsException extends ApiException {
-    public InsufficientFundsException(String accountId) {
-        super("Insufficient funds in account: " + accountId, HttpStatus.PAYMENT_REQUIRED);
-    }
-}
-
-// In your service
-if (account.getBalance() < amount) {
-    throw new InsufficientFundsException(account.getId());
-}
-
-// ❌ AVOID - Generic exceptions
-throw new RuntimeException("Not enough money");
-```
-
-#### 5. Leverage Trace IDs for Debugging
-
-```java
-// Log the trace ID from incoming requests
-@PostMapping
-public ResponseEntity<ApiResponse<User>> createUser(@RequestBody UserDto dto) {
-    UUID traceId = UUID.randomUUID();
-    log.info("Processing user creation request, traceId: {}", traceId);
-    
-    User user = userService.create(dto);
-    
-    // Create response with same trace ID
-    ApiResponse<User> response = ApiResponse.<User>builder()
-        .status(HttpStatus.CREATED.value())
-        .traceId(traceId)
-        .message("User created successfully")
-        .data(user)
-        .build();
-    
-    return ResponseEntity.status(HttpStatus.CREATED).body(response);
-}
-```
-
-#### 6. Caching Considerations
-
-```java
-// ⚠️ CAUTION - Response includes timestamp, making caching difficult
-// Consider extracting just the data for caching:
-
-@Cacheable("users")
-public User getUserData(Long id) {
-    return userRepository.findById(id).orElseThrow();
-}
-
-@GetMapping("/{id}")
-public ResponseEntity<ApiResponse<User>> getUser(@PathVariable Long id) {
-    // Fresh response wrapper, cached data
-    return ApiResponse.success("User found", getUserData(id));
-}
-```
-
-## 📋 Migration Guide
-
-### From v1.0.0 to v1.1.0
-
-This is a minor release with **new security features** and documentation fixes:
-
-#### ✨ New Features:
-- ✅ **Strict JSON Validation** - New `strictJsonCustomizer()` method that adds:
-  - `FAIL_ON_UNKNOWN_PROPERTIES` - Rejects JSON with unexpected fields (prevents mass assignment attacks)
-  - `ACCEPT_CASE_INSENSITIVE_ENUMS` - Flexible enum handling (e.g., "ACTIVE", "active", "Active")
-  - **Automatic XSS Prevention** - Detects and rejects HTML tags in string inputs
-  - **Automatic String Trimming** - Removes leading/trailing whitespace
-  - Throws `IllegalArgumentException` with message: "Security Error: HTML tags or XSS payloads are not allowed in the request."
-
-#### 📝 Documentation Fixes:
-- ✅ Fixed incorrect package name references in README (`io.github.pasinduog` → `io.github.og4dev`)
-
-#### 🔄 Migration Steps:
-**No code changes required!** The new security features are automatically applied.
-
-If you need to disable strict validation (e.g., to accept HTML content):
-```java
-@Configuration
-public class CustomConfig {
-    @Bean
-    @Primary  // Override the default
-    public JsonMapperBuilderCustomizer myCustomizer() {
-        return builder -> {
-            // Your custom configuration
-        };
-    }
-}
-```
-
-### Getting Started (New Users)
-
-Simply add the dependency to your project:
-
-```xml
-<dependency>
-    <groupId>io.github.og4dev</groupId>
-    <artifactId>og4dev-spring-response</artifactId>
-    <version>1.3.0</version>
-</dependency>
-```
-
-All features are automatically enabled through Spring Boot auto-configuration. No manual configuration needed!
-
-## 🔒 Security Considerations
-
-### 🛡️ Built-in Security Features (Automatic)
-
-The library includes **three automatic security protections** that are enabled by default:
-
-#### 1. ✅ Strict JSON Property Validation (Mass Assignment Prevention)
-
-**Automatically enabled** - Rejects unknown properties to prevent mass assignment attacks:
-
-```java
-// Your DTO
-public class UserUpdateDto {
-    private String name;
-    private String email;
-}
-
-// ✅ Valid request
-{"name": "John", "email": "john@example.com"}
-
-// ❌ Automatically rejected with 400 Bad Request
-{"name": "John", "email": "john@example.com", "isAdmin": true}
-```
-
-**What it prevents:**
-- Privilege escalation attempts
-- Data injection attacks
-- Unauthorized field modifications
-
-#### 2. ✅ Automatic XSS Prevention (HTML Tag Rejection)
-
-**Automatically enabled** - All string inputs are validated for HTML tags, and requests with HTML content are rejected:
-
-```java
-// ✅ Valid input - Clean text
-{"comment": "This is a safe comment"}
-
-// ❌ Rejected with 400 Bad Request
-{"comment": "<script>alert('XSS')</script>"}
-
-// Error response:
-{
-  "status": 400,
-  "detail": "Security Error: HTML tags or XSS payloads are not allowed in the request.",
-  "traceId": "550e8400-e29b-41d4-a716-446655440000",
-  "timestamp": "2026-02-16T10:30:45.123Z"
-}
-```
-
-**What it prevents:**
-- Cross-Site Scripting (XSS) attacks
-- HTML injection
-- JavaScript injection
-- XML/XHTML injection attempts
-
-**Note:** Fail-fast approach - malicious content never enters your system.
-
-#### 3. ✅ Automatic String Sanitization
-
-**Automatically enabled** - Trims whitespace and preserves null values:
-
-```java
-// Input
-{"name": "  John Doe  ", "middleName": null}
-
-// Automatically processed to
-{"name": "John Doe", "middleName": null}
-```
-
-**See also:** [Built-in Security Features](#-built-in-security-features) for detailed documentation.
-
----
-
-### 1. Exception Message Sanitization
-
-The library's `GlobalExceptionHandler` provides safe defaults, but be mindful:
-
-```java
-// ✅ SAFE - No sensitive data
-throw new ApiException("User not found", HttpStatus.NOT_FOUND);
-
-// ⚠️ CAUTION - May leak sensitive information
-throw new ApiException("Database connection failed: " + sqlException.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
-
-// ✅ BETTER - Generic message
-throw new ApiException("An internal error occurred", HttpStatus.INTERNAL_SERVER_ERROR);
-```
-
-### 2. Trace ID Privacy
-
-Trace IDs are UUIDs and don't contain sensitive information. However:
-
-- **Don't log sensitive data** alongside trace IDs
-- **Consider rate limiting** to prevent trace ID enumeration
-- **Rotate logs** regularly to limit exposure
-
-```java
-// ✅ SAFE
-log.info("User created successfully, traceId: {}", traceId);
-
-// ❌ UNSAFE - Logs password
-log.info("User created, traceId: {}, password: {}", traceId, password);
-```
-
-### 3. Stack Trace Exposure
-
-The `GlobalExceptionHandler` **never exposes stack traces** to clients. Stack traces are:
-- ✅ Logged server-side for debugging
-- ❌ Never sent in API responses
-- ✅ Replaced with generic messages
-
-### 4. Validation Error Details
-
-Validation errors include field names and constraints:
-
-```json
-{
-  "status": 400,
-  "detail": "Validation Failed",
-  "errors": {
-    "email": "must be a well-formed email address",
-    "password": "must not be blank"
-  }
-}
-```
-
-**Security Tips:**
-- ✅ Don't include sensitive field values in error messages
-- ✅ Use generic constraint messages for sensitive fields
-- ✅ Consider custom validators for sensitive data
-
-```java
-public class SensitiveDto {
-    @NotBlank(message = "Required field is missing")  // Generic message
-    private String creditCardNumber;
-    
-    @Pattern(regexp = "...", message = "Invalid format")  // No details
-    private String ssn;
-}
-```
-
-### 5. CORS & Security Headers
-
-The library doesn't interfere with Spring Security or CORS configuration:
-
-```java
-@Configuration
-public class SecurityConfig {
-    @Bean
-    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
-        http
-            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
-            .csrf(csrf -> csrf.disable())
-            // ... other configurations
-        return http.build();
-    }
-}
-```
-
-### 6. Dependency Security
-
-The library uses **provided scope** dependencies:
-- ✅ No transitive dependency vulnerabilities
-- ✅ Uses your application's Spring Boot version
-- ✅ No additional security surface area
-
-**Verify with:**
-```bash
-mvn dependency:tree -Dincludes=io.github.og4dev:og4dev-spring-response
-```
-
-### 7. ProblemDetail Information Disclosure
-
-RFC 9457 ProblemDetail responses (supersedes RFC 7807) include:
-- `type` - URI reference (defaults to "about:blank")
-- `title` - Short, human-readable summary
-- `status` - HTTP status code
-- `detail` - Human-readable explanation
-- `instance` - URI reference (not used by default)
-
-**Best Practice:** Don't include internal system details in error messages.
-
-## 🤝 Contributing
-
-**We welcome and encourage contributions from everyone!** 🎉
-
-This project is licensed under the **Apache License 2.0**, which means:
-- ✅ **Anyone can contribute** - The project is open to all developers
-- ✅ **Your contributions are protected** - No one can claim exclusive ownership of your work
-- ✅ **You retain copyright** - You keep rights to your work while granting usage rights to the project
-- ✅ **Fair and equal terms** - All contributions are made under the same Apache 2.0 terms
-
-### 🔐 Contributor License Agreement
-
-By contributing to this project, you agree that:
-
-1. **Your contributions** will be licensed under the Apache License 2.0
-2. **You grant** the project maintainers and users a perpetual, worldwide license to use your contributions
-3. **You retain** copyright to your contributions
-4. **You confirm** that you have the right to submit the contribution and grant these rights
-5. **Your work is protected** - No one (including the project maintainer) can claim exclusive ownership of your contributions or publish them elsewhere as their own
-
-### 📜 What Apache 2.0 Means for Contributors
-
-✅ **Your Rights:**
-- You keep copyright to your contributions
-- Your name is attributed in the project
-- You can use your contributions elsewhere
-- You're protected from patent claims
-
-🛡️ **Project Protection:**
-- **Prevents anyone from copyrighting the project** - No one can claim exclusive ownership
-- Ensures the project remains open source
-- Protects all contributors equally
-- Maintains free usage for everyone
-- **Cannot be published elsewhere as proprietary** - Derivative works must maintain the Apache 2.0 License
-
-### How to Contribute
-
-1. **Fork the repository** on GitHub
-   - Navigate to https://github.com/OG4Dev/og4dev-spring-response
-   - Click the "Fork" button in the top-right corner
-
-2. **Clone your fork** locally
-   ```bash
-   git clone https://github.com/YOUR_USERNAME/api-response.git
-   cd api-response
-   ```
-
-3. **Create a feature branch**
-   ```bash
-   git checkout -b feature/amazing-feature
-   ```
-
-4. **Make your changes**
-   - Follow the existing code style and conventions
-   - Add JavaDoc comments for all public methods and classes
-   - Ensure all existing tests pass (when tests are added)
-   - Keep changes focused and atomic
-
-5. **Commit your changes** (follow conventional commit format)
-   ```bash
-   git commit -m 'feat: add amazing feature'
-   ```
-
-6. **Push to your fork**
-   ```bash
-   git push origin feature/amazing-feature
-   ```
-
-7. **Open a Pull Request** on the main repository
-   - Go to the original repository on GitHub
-   - Click "New Pull Request"
-   - Select your branch and describe your changes in detail
-   - Reference any related issues
-
-### Contribution Guidelines
-
-#### Code Quality Standards
-- ✅ Follow existing code style and conventions
-- ✅ Add comprehensive JavaDoc comments for all public methods and classes
-- ✅ Include explicit constructor documentation for all constructors
-- ✅ Ensure all existing tests pass
-- ✅ Keep changes focused and atomic
-- ✅ Update README.md if adding new features or changing behavior
-- ✅ Verify zero Javadoc warnings (`mvn javadoc:javadoc` should run cleanly)
-
-#### Commit Message Format
-Follow [Conventional Commits](https://www.conventionalcommits.org/) specification:
-
-```bash
-# Format: <type>(<scope>): <subject>
-
-# Types:
-feat: add new response wrapper method
-fix: correct trace ID generation
-docs: update installation instructions
-refactor: improve exception handling
-test: add unit tests for ApiResponse
-style: format code and fix whitespace
-chore: update dependencies
-perf: optimize response creation
-```
-
-**Examples:**
-```bash
-feat(dto): add pagination support to ApiResponse
-fix(exception): resolve NPE in GlobalExceptionHandler
-docs(readme): add contributing guidelines
-test(response): add unit tests for success factory methods
-```
-
-#### Pull Request Process
-1. **Update documentation** - Modify README.md if adding features or changing behavior
-2. **Add JavaDoc** - Document all new public methods and classes with zero warnings
-3. **Write clear PR description**:
-   - What problem does this solve?
-   - What changes were made?
-   - How was it tested?
-   - Any breaking changes?
-4. **Reference issues** - Link related issues using `#issue-number` or `Fixes #issue-number`
-5. **Wait for review** - Maintainer will review and provide feedback
-6. **Address feedback** - Make requested changes and push updates
-7. **Squash commits** - Clean up commit history if needed before merge
-
-### Development Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/OG4Dev/og4dev-spring-response.git
-cd og4dev-spring-response
-
-# Build the project
-mvn clean install
-
-# Generate JavaDoc (builds with zero warnings)
-mvn javadoc:javadoc
-
-# Generate JavaDoc JAR (clean build with comprehensive documentation)
-mvn javadoc:jar
-
-# Package for Maven Central (requires GPG key)
-mvn clean deploy -P release
-```
-
-**Note:** The project includes explicit constructor documentation for all classes, ensuring zero Javadoc warnings during the build process. All constructors (including Spring bean constructors) are properly documented.
-
-### Project Structure for Contributors
-
-```
-og4dev-spring-response/
-├── src/
-│   ├── main/
-│   │   ├── java/io/github/og4dev/
-│   │   │   ├── config/           # Auto-configuration classes
-│   │   │   ├── dto/              # Response wrapper classes
-│   │   │   └── exception/        # Exception handling
-│   │   └── resources/
-│   │       └── META-INF/spring/  # Auto-configuration metadata
-│   └── test/java/                # Unit tests (to be added)
-├── pom.xml                       # Maven configuration
-└── README.md                     # Documentation
-```
-
-### What We're Looking For
-
-- 🐛 Bug fixes
-- 📝 Documentation improvements
-- ✨ New features (discuss in issue first)
-- 🧪 Test coverage improvements
-- 🎨 Code quality enhancements
-- 🌐 Internationalization support
-
-### Code of Conduct
-
-- Be respectful and inclusive
-- Provide constructive feedback
-
-## 📄 License
-
-This project is licensed under the **Apache License 2.0** - see the [LICENSE](LICENSE) file for full details.
-
-### What This Means
-
-The Apache 2.0 License is a permissive open-source license that:
-
-#### ✅ **Allows You To:**
-- ✅ Use this library in personal, commercial, or proprietary projects
-- ✅ Modify and distribute the source code
-- ✅ Sublicense the code
-- ✅ Use the software for any purpose (private, commercial, etc.)
-- ✅ Patent protection - contributors grant you patent rights
-
-#### 🛡️ **Protects The Project:**
-- 🛡️ **No one can claim ownership** - Others cannot copyright this work as their own
-- 🛡️ **Attribution required** - Anyone using or modifying this code must give credit
-- 🛡️ **License propagation** - Modified versions must include the Apache 2.0 License
-- 🛡️ **Trademark protection** - Project name and trademarks remain protected
-- 🛡️ **No liability** - Software is provided "as-is" without warranty
-
-#### 🤝 **For Contributors:**
-- 🤝 **Open contribution** - Anyone can contribute under the same terms
-- 🤝 **Grant of rights** - By contributing, you grant Apache 2.0 rights to your contributions
-- 🤝 **Your work is protected** - Contributions are attributed and cannot be claimed by others
-- 🤝 **Patent peace** - Contributors cannot sue users for patent infringement related to their contributions
-
-### Key License Terms
-
-```
-Copyright 2026 Pasindu OG
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-```
-
-### Summary for Users
-
-✅ **You CAN:**
-- Use in commercial products
-- Modify the code
-- Distribute copies
-- Grant sublicenses
-- Use privately
-
-❌ **You CANNOT:**
-- Hold the author liable
-- Use contributor names for endorsement
-- Remove copyright notices
-- Claim ownership of the original work
-
-📋 **You MUST:**
-- Include the Apache 2.0 License
-- Include copyright notice
-- State significant changes made
-- Include the NOTICE file (if applicable)
-
-For the complete license text, see [LICENSE](LICENSE) or visit [Apache.org](http://www.apache.org/licenses/LICENSE-2.0).
-
-## 📧 Contact
-
-**Pasindu OG**
-- 📧 Email: pasinduogdev@gmail.com
-- 🐙 GitHub: [@pasinduog](https://github.com/pasinduog)
-- 💻 Repository: [github.com/OG4Dev/og4dev-spring-response](https://github.com/OG4Dev/og4dev-spring-response)
-
-## 💖 Sponsorship
-
-**Love this project? Consider sponsoring!** ☕
-
-This library is developed and maintained in my free time with passion for the Spring Boot community. Your sponsorship helps keep this project alive and growing!
-
-### 🌟 Why Sponsor?
-
-Your support enables:
-- 🔧 **Continuous Maintenance** - Regular updates, bug fixes, and security patches
-- ✨ **New Features** - Pagination, WebFlux support, internationalization, and more
-- 📚 **Better Documentation** - More examples, tutorials, and comprehensive guides
-- 🧪 **Higher Quality** - More tests, better coverage, and reliability improvements
-- ⚡ **Faster Support** - Priority response to your issues and feature requests
-
-### 💝 How to Support
-
-Choose your preferred platform:
-
-- **GitHub Sponsors** - [Sponsor @pasinduog](https://github.com/sponsors/pasinduog)
-- **Buy Me a Coffee** - [buymeacoffee.com/pasinduog](https://buymeacoffee.com/pasinduog)
-- **PayPal** - [paypal.me/pasinduog](https://paypal.me/pasinduog)
-
-### 🎁 Sponsor Perks
-
-Monthly sponsors receive:
-- 🏆 Recognition in README with name/company logo
-- 🎯 Priority support for issues and features
-- 📢 Early access to new releases
-- 💬 Direct communication channel
-- 🗺️ Influence on project roadmap
-
-### 🙏 Current Sponsors
-
-*Your name could be here! Become the first sponsor of OG4Dev Spring API Response.*
-
-<!-- Sponsor badges will appear here -->
-
-**Every dollar helps!** Even small contributions make a big difference. Thank you for your support! ❤️
-
-## 🙏 Acknowledgments
-
-- Spring Boot team for the excellent framework
-- The open-source community for inspiration and support
-
-## 📈 Version History
-
-### 1.3.0 (February 2026) - Current Release
-
-✨ **Major Breaking Change: Opt-in Security Model**
-- **Security Philosophy Change** - Complete redesign from automatic to opt-in approach
-  - **Before (v1.2.0):** All strings automatically trimmed and XSS-validated
-  - **After (v1.3.0):** Fields preserved as-is by default; features enabled via annotations
-  - **Reason:** Gives developers full control over which fields need processing
-  - **Migration:** Add `@AutoTrim` and/or `@XssCheck` to fields that need them
-
-✨ **New Features:**
-- **@AutoTrim Annotation** - Opt-in automatic string trimming
-  - Replaces default trimming behavior from v1.2.0
-  - Apply to individual fields that should have whitespace removed
-  - Examples: usernames, emails, search queries, reference numbers
-  - Comprehensive Javadoc with 100+ lines of documentation
-  - Null-safe processing with proper empty string handling
-- **@XssCheck Annotation** - Opt-in XSS validation
-  - Replaces automatic XSS validation from v1.2.0
-  - Apply to individual fields that should reject HTML tags
-  - Examples: comments, user-generated content, profile fields
-  - Fail-fast regex pattern: `(?s).*<\s*[a-zA-Z/!].*`
-  - Comprehensive Javadoc with 150+ lines of documentation
-- **Fine-Grained Control** - Four processing modes per field
-  - No annotations: String preserved as-is (default)
-  - `@AutoTrim` only: String is trimmed
-  - `@XssCheck` only: String is XSS-validated
-  - Both annotations: String is trimmed then XSS-validated
-
-📚 **Documentation Overhaul:**
-- **Complete README Rewrite** - Entirely new documentation structure
-  - Updated all code examples to show annotation-based approach
-  - Added "Security Philosophy: Opt-in by Default" section
-  - Expanded annotation usage examples with 20+ code samples
-  - Clear migration guide from v1.2.0
-  - Updated "How It Works" section with new implementation
-- **Comprehensive JavaDoc Updates**
-  - `@AutoTrim`: 100+ lines of detailed documentation
-  - `@XssCheck`: 150+ lines of detailed documentation
-  - Updated `ApiResponseAutoConfiguration` to reflect opt-in model
-  - All examples updated to show annotation usage
-  - Zero Javadoc warnings
-
-🔧 **Technical Updates:**
-- Spring Boot 4.0.3 compatibility maintained
-- Jackson 3.x with tools.jackson packages
-- Enhanced `AdvancedStringDeserializer` with four-mode operation
-- Context-aware deserialization via `createContextual()`
-- Performance optimized: deserializer created once per field at initialization
-- Removed `@NoTrim` annotation (no longer needed with opt-in approach)
-
-🔄 **Breaking Changes:**
-- **⚠️ IMPORTANT:** Default behavior changed from v1.2.0
-  - **v1.2.0:** All strings automatically trimmed and XSS-validated
-  - **v1.3.0:** Strings preserved as-is unless annotated
-  - **Migration Required:** Add `@AutoTrim` and/or `@XssCheck` to fields that need processing
-  - **Example Migration:**
-    ```java
-    // v1.2.0 (automatic processing)
-    public class UserDTO {
-        private String username;  // Was automatically trimmed
-        private String comment;   // Was automatically XSS-validated
-    }
-    
-    // v1.3.0 (opt-in with annotations)
-    public class UserDTO {
-        @AutoTrim
-        private String username;  // Now explicitly trimmed
-        
-        @XssCheck
-        private String comment;   // Now explicitly XSS-validated
-    }
-    ```
-
-### 1.2.0 (February 2026) - Previous Release
-
-✨ **New Features:**
-- **@NoTrim Annotation** - Fine-grained control over string trimming behavior
-  - Opt-out of automatic whitespace trimming for specific fields
-  - Preserves whitespace for passwords, code snippets, Base64 data, API tokens
-  - XSS validation still applies even with `@NoTrim` for security
-  - Context-aware deserialization using `createContextual()` method
-- **Enhanced Security Model** - Improved XSS prevention approach
-  - Changed from HTML escaping to fail-fast tag rejection
-  - Regex pattern: `(?s).*<\s*[a-zA-Z/!].*` with DOTALL mode support
-  - Prevents stored XSS, DOM-based XSS, and second-order injections
-- **Advanced String Deserializer** - Context-aware string processing
-  - Two-mode operation: Default Mode (trim enabled) and NoTrim Mode (preserve whitespace)
-  - Field-level annotation detection via `createContextual()`
-  - Performance optimized: deserializer created once at initialization
-
-📚 **Documentation Enhancements:**
-- Comprehensive JavaDoc improvements
-- Updated `strictJsonCustomizer()` with ~280 lines of detailed documentation
-- Added `@NoTrim` annotation documentation with complete examples
-- Complete README refresh with corrected XSS prevention descriptions
-
-🔧 **Technical Updates:**
-- Spring Boot 4.0.3 compatibility (tested and verified)
-- Jackson 3.x with tools.jackson packages
-- Added annotation package: `io.github.og4dev.annotation`
-- Enhanced StdScalarDeserializer implementation
-
-🔄 **Breaking Changes:**
-- None - Fully backward compatible with v1.1.0 and v1.1.1
-
-### 1.1.1 (February 2026)
-
-🔧 **Maintenance Release:**
-- **Spring Boot 4.0.3 Support** - Updated compatibility to Spring Boot 4.0.3
-  - Tested and verified with Spring Boot 4.0.3
-  - All features continue to work flawlessly
-  - Seamless upgrade from Spring Boot 4.0.2
-- **Enhanced Stability** - Benefits from Spring Boot 4.0.3 bug fixes and improvements
-
-*Note: Version 1.1.1 was a Spring Boot patch compatibility update. New features were added in v1.2.0.*
-
-### 1.1.0 (February 2026)
-
-✅ **New Features:**
-- **Built-in Security Features** - Added `strictJsonCustomizer()` method with comprehensive JSON security
-  - ✅ **Strict Property Validation** - Rejects unknown properties to prevent mass assignment attacks
-  - ✅ **XSS Prevention** - Automatic HTML tag detection and rejection using regex pattern `.*<\s*[a-zA-Z/!].*`
-  - ✅ **String Sanitization** - Automatic whitespace trimming on deserialization
-  - ✅ **Case-Insensitive Enums** - Flexible enum handling for better API usability
-- **Comprehensive Exception Handling** - GlobalExceptionHandler with 10 built-in exception handlers
-  - General exceptions (HTTP 500)
-  - Validation errors with field-level details (HTTP 400)
-  - Type mismatch errors (HTTP 400)
-  - Malformed JSON requests (HTTP 400)
-  - Missing required parameters (HTTP 400)
-  - 404 Not Found errors
-  - 405 Method Not Allowed
-  - 415 Unsupported Media Type
-  - Null pointer exceptions (HTTP 500)
-  - Custom ApiException instances (custom status codes)
-- **Distributed Tracing Support** - Trace IDs in error responses for debugging
-- **RFC 9457 Compliance** - Standard ProblemDetail format for error responses
-- **Spring Boot Auto-Configuration** - Zero-configuration setup via META-INF imports
-- **TraceIdFilter** - Optional servlet filter for trace ID generation and MDC integration
-- **Custom Business Exceptions** - Abstract ApiException class for domain-specific errors
-
-🔧 **Improvements:**
-- **Complete Javadoc Coverage** - 100% documentation with zero warnings
-  - Comprehensive documentation for all classes and methods
-  - Detailed security feature explanations
-  - Code examples for all major features
-  - Complete @param, @return, @see, and @since tags
-- **Enhanced Security** - Fail-fast approach with HTML tag rejection instead of escaping
-- **Better Error Messages** - Clear, actionable error messages for all scenarios
-- **Improved Logging** - Consistent trace IDs between logs and error responses
-- **Production-Ready Quality** - Clean Maven builds, proper documentation, battle-tested code
-
-📚 **Documentation:**
-- Added dedicated "Built-in Security Features" section in README
-- Enhanced JavaDoc for `strictJsonCustomizer()` method with detailed examples
-- Added comprehensive exception handling documentation
-- Added distributed tracing examples and best practices
-- Complete package-info.java files for all packages
-
-🔧 **Technical Updates:**
-- Java 17+ support (Java 21 LTS recommended)
-- Spring Boot 3.2.0 - 4.0.3 compatibility (tested with 4.0.3)
-- Jackson 3.x compatibility (tools.jackson packages)
-- Pure Java implementation - No Lombok dependency
-- Zero external runtime dependencies
-- Ultra-lightweight: ~10KB JAR size
-
-### 1.0.0 (February 2026) - Initial Release
-
-✅ **Core Features:**
-- Standard API Response wrapper with generic type support
-- Factory methods: `success()`, `created()`, `status()`
-- Automatic RFC 3339 UTC timestamp generation
-- Thread-safe & immutable design
-- Full Spring Boot 3.2.0+ integration
-- Comprehensive JavaDoc documentation
-
-🎯 **Roadmap:**
-- Spring WebFlux support (reactive)
-- Pagination metadata support
-- OpenAPI schema generation
-- Internationalization (i18n) support
-- Response compression support
-- Custom serialization options
-- Metrics and monitoring integration
-
----
-
-## 📋 Summary
-
-The **OG4Dev Spring API Response** library is a production-ready, zero-configuration solution for standardizing REST API responses in Spring Boot applications.
-
-### 🎯 Why Choose This Library?
-
-✅ **Instant Setup** - Add dependency, start using. No configuration needed.  
-✅ **Battle-Tested** - Production-ready code with comprehensive testing  
-✅ **Modern Standards** - RFC 9457 ProblemDetail, Spring Boot 4.x support  
-✅ **Developer Friendly** - Comprehensive docs, clear examples, active maintenance  
-✅ **Lightweight** - Only ~10KB, zero runtime dependencies  
-✅ **Type Safe** - Full generic support with compile-time checking  
-✅ **Pure Java** - No Lombok or external dependencies required  
-
-### 📊 Quick Stats
-
-| Metric | Value |
-|--------|-------|
-| JAR Size | ~10KB |
-| Response Time | < 1ms |
-| Memory per Response | ~200 bytes |
-| Thread Safety | 100% |
-| Spring Boot Support | 3.2.0 - 4.0.3 |
-| Java Version | 17+ |
-
-### 🔗 Quick Access
-
-- 📦 **[Maven Central](https://central.sonatype.com/artifact/io.github.og4dev/og4dev-spring-response)** - Download & integration
-- 📚 **[JavaDoc](https://javadoc.io/doc/io.github.og4dev/og4dev-spring-response)** - Complete API documentation  
-- 🐛 **[Issues](https://github.com/OG4Dev/og4dev-spring-response/issues)** - Report bugs or request features
-- 💬 **[Discussions](https://github.com/OG4Dev/og4dev-spring-response/discussions)** - Ask questions & share ideas
+**Pasindu OG** | [pasinduogdev@gmail.com](mailto:pasinduogdev@gmail.com) |
+GitHub: [@pasinduog](https://github.com/pasinduog)
 
 ---
 
-**⭐ If you find this library helpful, please give it a star on GitHub!**
-
-Made with ❤️ by [Pasindu OG](https://github.com/pasinduog)
+**⭐ If you find this library helpful, please give it a star on GitHub!**
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index e5fdb00..8d66f6c 100644
--- a/pom.xml
+++ b/pom.xml
@@ -5,7 +5,7 @@
 
     <groupId>io.github.og4dev</groupId>
     <artifactId>og4dev-spring-response</artifactId>
-    <version>1.3.0</version>
+    <version>1.4.0</version>
 
     <name>OG4Dev Spring API Response</name>
     <description>A lightweight, zero-configuration REST API Response wrapper and Global Exception Handler (RFC 9457) for Spring Boot applications, maintained by OG4Dev.</description>
diff --git a/src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java b/src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java
index ed8deb0..fb694e3 100644
--- a/src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java
+++ b/src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java
@@ -2,6 +2,7 @@
 
 import io.github.og4dev.annotation.AutoResponse;
 import io.github.og4dev.dto.ApiResponse;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 import org.springframework.core.MethodParameter;
 import org.springframework.http.HttpStatus;
@@ -44,7 +45,7 @@
  */
 @RestControllerAdvice(annotations = AutoResponse.class)
 @SuppressWarnings("unused")
-public class GlobalResponseWrapper implements ResponseBodyAdvice<Object> {
+public @NullMarked class GlobalResponseWrapper implements ResponseBodyAdvice<Object> {
 
     /**
      * Determines whether the current response should be intercepted and wrapped.
@@ -65,7 +66,7 @@ public class GlobalResponseWrapper implements ResponseBodyAdvice<Object> {
      * @return {@code true} if the body should be wrapped; {@code false} if it should be skipped.
      */
     @Override
-    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
+    public @NullMarked boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
         Class<?> type = returnType.getParameterType();
         return !ApiResponse.class.isAssignableFrom(type) &&
                 !ResponseEntity.class.isAssignableFrom(type) &&
diff --git a/src/main/java/io/github/og4dev/advice/package-info.java b/src/main/java/io/github/og4dev/advice/package-info.java
new file mode 100644
index 0000000..793e9b3
--- /dev/null
+++ b/src/main/java/io/github/og4dev/advice/package-info.java
@@ -0,0 +1,30 @@
+/**
+ * Provides global advisory components for the OG4Dev Spring API Response Library.
+ * <p>
+ * This package contains Spring {@link org.springframework.web.bind.annotation.RestControllerAdvice}
+ * implementations that intercept and modify HTTP responses and requests globally across the application.
+ * </p>
+ * <p>
+ * The primary component within this package is the {@link io.github.og4dev.advice.GlobalResponseWrapper}.
+ * It facilitates the seamless, opt-in encapsulation of standard controller return values into the
+ * standardized {@link io.github.og4dev.dto.ApiResponse} format, significantly reducing boilerplate code.
+ * </p>
+ * <h2>Integration &amp; Usage</h2>
+ * <p>
+ * Components in this package are automatically registered via Spring Boot's auto-configuration
+ * mechanism ({@code ApiResponseAutoConfiguration}). Developers do not need to manually scan, import,
+ * or configure this package.
+ * </p>
+ * <p>
+ * To activate the response wrapping capabilities provided by this package, simply annotate
+ * target REST controllers or specific methods with the {@link io.github.og4dev.annotation.AutoResponse @AutoResponse}
+ * annotation.
+ * </p>
+ *
+ * @author Pasindu OG
+ * @version 1.4.0
+ * @see io.github.og4dev.advice.GlobalResponseWrapper
+ * @see io.github.og4dev.annotation.AutoResponse
+ * @since 1.4.0
+ */
+package io.github.og4dev.advice;
\ No newline at end of file
diff --git a/src/main/java/io/github/og4dev/annotation/AutoResponse.java b/src/main/java/io/github/og4dev/annotation/AutoResponse.java
index d22eb84..3360904 100644
--- a/src/main/java/io/github/og4dev/annotation/AutoResponse.java
+++ b/src/main/java/io/github/og4dev/annotation/AutoResponse.java
@@ -2,8 +2,56 @@
 
 import java.lang.annotation.*;
 
+/**
+ * Opt-in annotation to enable automatic API response wrapping for Spring REST controllers.
+ * <p>
+ * When this annotation is applied to a {@link org.springframework.web.bind.annotation.RestController}
+ * class or a specific request mapping method, the {@link io.github.og4dev.advice.GlobalResponseWrapper}
+ * intercepts the returned object and automatically encapsulates it within the standardized
+ * {@link io.github.og4dev.dto.ApiResponse} format.
+ * </p>
+ * <h2>Usage:</h2>
+ * <ul>
+ * <li><b>Class Level ({@link ElementType#TYPE}):</b> Applies the wrapping behavior to <i>all</i> endpoint methods within the controller.</li>
+ * <li><b>Method Level ({@link ElementType#METHOD}):</b> Applies the wrapping behavior <i>only</i> to the specific annotated method.</li>
+ * </ul>
+ * <h2>Example:</h2>
+ * <pre>{@code
+ * @RestController
+ * @RequestMapping("/api/users")
+ * @AutoResponse // All methods in this controller will be automatically wrapped
+ * public class UserController {
+ * * @GetMapping("/{id}")
+ * public UserDto getUser(@PathVariable Long id) {
+ * // Returns: { "status": "Success", "content": { "id": 1, ... }, "timestamp": "..." }
+ * return userService.findById(id);
+ * }
+ * * @PostMapping
+ * @ResponseStatus(HttpStatus.CREATED)
+ * // @AutoResponse can also be placed here for method-level granularity instead of class-level
+ * public UserDto createUser(@RequestBody UserDto dto) {
+ * return userService.create(dto);
+ * }
+ * }
+ * }</pre>
+ * <h2>Exclusions:</h2>
+ * <p>
+ * To prevent errors and double-wrapping, the interceptor will safely ignore methods that return:
+ * </p>
+ * <ul>
+ * <li>{@code ApiResponse} or {@code ResponseEntity} (Assumes the developer has explicitly formatted the response)</li>
+ * <li>{@code ProblemDetail} (RFC 9457 error responses managed by the global exception handler)</li>
+ * <li>{@code String} (Bypassed to avoid {@code ClassCastException} with Spring's internal string message converters)</li>
+ * </ul>
+ *
+ * @author Pasindu OG
+ * @version 1.4.0
+ * @see io.github.og4dev.advice.GlobalResponseWrapper
+ * @see io.github.og4dev.dto.ApiResponse
+ * @since 1.4.0
+ */
 @Target({ElementType.TYPE, ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 @Documented
 public @interface AutoResponse {
-}
+}
\ No newline at end of file
diff --git a/src/main/java/io/github/og4dev/annotation/AutoTrim.java b/src/main/java/io/github/og4dev/annotation/AutoTrim.java
index 05ae376..cb70fce 100644
--- a/src/main/java/io/github/og4dev/annotation/AutoTrim.java
+++ b/src/main/java/io/github/og4dev/annotation/AutoTrim.java
@@ -110,7 +110,7 @@
  * </p>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @see io.github.og4dev.config.ApiResponseAutoConfiguration#strictJsonCustomizer()
  * @see io.github.og4dev.annotation.XssCheck
  * @see tools.jackson.databind.ValueDeserializer#createContextual
diff --git a/src/main/java/io/github/og4dev/annotation/XssCheck.java b/src/main/java/io/github/og4dev/annotation/XssCheck.java
index 9ded2d5..f009a8e 100644
--- a/src/main/java/io/github/og4dev/annotation/XssCheck.java
+++ b/src/main/java/io/github/og4dev/annotation/XssCheck.java
@@ -201,7 +201,7 @@
  * </table>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @see io.github.og4dev.config.ApiResponseAutoConfiguration#strictJsonCustomizer()
  * @see io.github.og4dev.annotation.AutoTrim
  * @see tools.jackson.databind.ValueDeserializer#createContextual
diff --git a/src/main/java/io/github/og4dev/annotation/package-info.java b/src/main/java/io/github/og4dev/annotation/package-info.java
index b9c8ae7..cbc9df8 100644
--- a/src/main/java/io/github/og4dev/annotation/package-info.java
+++ b/src/main/java/io/github/og4dev/annotation/package-info.java
@@ -152,7 +152,7 @@
  * </p>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @see io.github.og4dev.annotation.AutoTrim
  * @see io.github.og4dev.annotation.XssCheck
  * @see io.github.og4dev.config.ApiResponseAutoConfiguration
diff --git a/src/main/java/io/github/og4dev/config/ApiResponseAutoConfiguration.java b/src/main/java/io/github/og4dev/config/ApiResponseAutoConfiguration.java
index aa4abe6..240b0e1 100644
--- a/src/main/java/io/github/og4dev/config/ApiResponseAutoConfiguration.java
+++ b/src/main/java/io/github/og4dev/config/ApiResponseAutoConfiguration.java
@@ -1,8 +1,11 @@
 package io.github.og4dev.config;
 
+import io.github.og4dev.advice.GlobalResponseWrapper;
+import io.github.og4dev.annotation.AutoResponse;
 import io.github.og4dev.annotation.AutoTrim;
 import io.github.og4dev.annotation.XssCheck;
 import io.github.og4dev.exception.GlobalExceptionHandler;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
 import org.springframework.boot.jackson.autoconfigure.JsonMapperBuilderCustomizer;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -17,7 +20,8 @@
  * <p>
  * This configuration is automatically loaded by Spring Boot's autoconfiguration mechanism
  * when the library is present on the classpath. It registers essential beans required for
- * the library to function properly, including the comprehensive global exception handler.
+ * the library to function properly, including the comprehensive global exception handler
+ * and the automatic response wrapper.
  * </p>
  * <p>
  * <b>Zero Configuration Required:</b> Simply adding the library dependency enables all features
@@ -25,14 +29,15 @@
  * </p>
  * <h2>What Gets Auto-Configured:</h2>
  * <ul>
- *   <li>{@link GlobalExceptionHandler} - Comprehensive exception handling with RFC 9457 ProblemDetail format
- *       <ul>
- *         <li>10 built-in exception handlers covering all common error scenarios</li>
- *         <li>Automatic trace ID generation and logging</li>
- *         <li>Validation error aggregation and formatting</li>
- *         <li>Production-ready error messages</li>
- *       </ul>
- *   </li>
+ * <li>{@link GlobalExceptionHandler} - Comprehensive exception handling with RFC 9457 ProblemDetail format
+ * <ul>
+ * <li>10 built-in exception handlers covering all common error scenarios</li>
+ * <li>Automatic trace ID generation and logging</li>
+ * <li>Validation error aggregation and formatting</li>
+ * <li>Production-ready error messages</li>
+ * </ul>
+ * </li>
+ * <li>{@link GlobalResponseWrapper} - Automatic wrapping of controller responses (Opt-in via {@code @AutoResponse})</li>
  * </ul>
  * <h2>How It Works:</h2>
  * <p>
@@ -46,9 +51,9 @@
  * <pre>{@code
  * @SpringBootApplication(exclude = ApiResponseAutoConfiguration.class)
  * public class Application {
- *     public static void main(String[] args) {
- *         SpringApplication.run(Application.class, args);
- *     }
+ * public static void main(String[] args) {
+ * SpringApplication.run(Application.class, args);
+ * }
  * }
  * }</pre>
  * <p>
@@ -57,16 +62,11 @@
  * <pre>
  * spring.autoconfigure.exclude=io.github.og4dev.config.ApiResponseAutoConfiguration
  * </pre>
- * <p>
- * Alternatively, disable the exception handler while keeping other library features:
- * </p>
- * <pre>
- * api-response.enabled=false
- * </pre>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @see GlobalExceptionHandler
+ * @see GlobalResponseWrapper
  * @see org.springframework.boot.autoconfigure.AutoConfiguration
  * @since 1.0.0
  */
@@ -76,10 +76,6 @@ public class ApiResponseAutoConfiguration {
 
     /**
      * Default constructor for ApiResponseAutoConfiguration.
-     * <p>
-     * This constructor is automatically invoked by Spring's dependency injection
-     * container during application startup when autoconfiguration is enabled.
-     * </p>
      */
     public ApiResponseAutoConfiguration() {
         // Default constructor for Spring autoconfiguration
@@ -87,42 +83,66 @@ public ApiResponseAutoConfiguration() {
 
     /**
      * Registers the {@link GlobalExceptionHandler} as a Spring bean for automatic exception handling.
+     * * // ... (පරණ JavaDoc එකමයි, වෙනස් වෙන්නේ නෑ) ...
+     * * @return A new instance of {@link GlobalExceptionHandler} registered as a Spring bean.
+     */
+    @Bean
+    public GlobalExceptionHandler apiResponseAdvisor() {
+        return new GlobalExceptionHandler();
+    }
+
+    /**
+     * Registers the {@link GlobalResponseWrapper} as a Spring bean for automatic API response wrapping.
      * <p>
-     * The handler provides comprehensive centralized exception management using Spring's
-     * {@link org.springframework.web.bind.annotation.RestControllerAdvice} mechanism,
-     * automatically converting 10 different types of exceptions to RFC 9457 ProblemDetail responses.
-     * </p>
-     * <p>
-     * <b>Exception Coverage:</b>
+     * This bean enables the opt-in {@link AutoResponse @AutoResponse} feature. When a REST controller
+     * or method is annotated with {@code @AutoResponse}, this wrapper automatically intercepts the
+     * outgoing payload and encapsulates it within the standardized {@code ApiResponse<T>} structure
+     * before it is written to the HTTP response body.
      * </p>
+     * <h2>Key Capabilities:</h2>
      * <ul>
-     *   <li>General exceptions (500 Internal Server Error)</li>
-     *   <li>Validation errors with field-level details (400 Bad Request)</li>
-     *   <li>Type mismatch errors (400 Bad Request)</li>
-     *   <li>Malformed JSON requests (400 Bad Request)</li>
-     *   <li>Missing required parameters (400 Bad Request)</li>
-     *   <li>404 Not Found errors</li>
-     *   <li>405 Method Not Allowed</li>
-     *   <li>415 Unsupported Media Type</li>
-     *   <li>Null pointer exceptions (500 Internal Server Error)</li>
-     *   <li>Custom ApiException instances (custom status codes)</li>
+     * <li><b>Zero Boilerplate:</b> Eliminates the need to manually return {@code ResponseEntity<ApiResponse<T>>}
+     * from every controller method.</li>
+     * <li><b>Status Code Preservation:</b> Intelligently reads and preserves custom HTTP status codes
+     * set via {@code @ResponseStatus} (e.g., 201 Created).</li>
+     * <li><b>Double-Wrap Prevention:</b> Safely skips wrapping if the controller already returns
+     * an {@code ApiResponse} or {@code ResponseEntity}.</li>
+     * <li><b>Error Compatibility:</b> Bypasses {@code ProblemDetail} and exception responses to maintain
+     * RFC 9457 compliance managed by {@link GlobalExceptionHandler}.</li>
      * </ul>
+     * <h2>Example Usage:</h2>
+     * <pre>{@code
+     * @RestController
+     * @RequestMapping("/api/users")
+     * @AutoResponse // Enables automatic wrapping for all methods in this controller
+     * public class UserController {
+     * * @GetMapping("/{id}")
+     * public UserDto getUser(@PathVariable Long id) {
+     * // Simply return the DTO. It will be sent to the client as:
+     * // { "status": "Success", "content": { "id": 1, "name": "..." }, "timestamp": "..." }
+     * return userService.findById(id);
+     * }
+     * * @PostMapping
+     * @ResponseStatus(HttpStatus.CREATED)
+     * public UserDto createUser(@RequestBody UserDto dto) {
+     * // The 201 Created status will be preserved in the final ApiResponse
+     * return userService.create(dto);
+     * }
+     * }
+     * }</pre>
      * <p>
-     * <b>Features:</b>
+     * <b>Note:</b> This bean is conditionally loaded using {@code @ConditionalOnMissingBean}, allowing developers
+     * to easily override the default wrapping behavior by defining their own {@code GlobalResponseWrapper} bean.
      * </p>
-     * <ul>
-     *   <li>Automatic trace ID generation for all errors</li>
-     *   <li>Consistent trace IDs between logs and responses</li>
-     *   <li>RFC 9457 compliant error format</li>
-     *   <li>Comprehensive SLF4J logging with appropriate severity levels</li>
-     *   <li>Automatic timestamp inclusion in all error responses</li>
-     * </ul>
-     *
-     * @return A new instance of {@link GlobalExceptionHandler} registered as a Spring bean.
+     * * @return A new instance of {@link GlobalResponseWrapper} registered as a Spring bean.
+     * @see AutoResponse
+     * @see io.github.og4dev.dto.ApiResponse
+     * @since 1.4.0
      */
     @Bean
-    public GlobalExceptionHandler apiResponseAdvisor() {
-        return new GlobalExceptionHandler();
+    @ConditionalOnMissingBean // මේක දැම්මොත් අනිත් අයට මේක override කරන්න පුළුවන්
+    public GlobalResponseWrapper globalResponseWrapper() {
+        return new GlobalResponseWrapper();
     }
 
     /**
diff --git a/src/main/java/io/github/og4dev/config/package-info.java b/src/main/java/io/github/og4dev/config/package-info.java
index 4cd5972..3aedd22 100644
--- a/src/main/java/io/github/og4dev/config/package-info.java
+++ b/src/main/java/io/github/og4dev/config/package-info.java
@@ -1,7 +1,7 @@
 /**
  * Configuration classes for the OG4Dev Spring API Response Library.
  * <p>
- * This package contains Spring Boot auto-configuration classes that automatically
+ * This package contains Spring Boot autoconfiguration classes that automatically
  * register required beans when the library is added to the classpath. Zero manual
  * configuration is required - simply add the dependency and all features are enabled.
  * </p>
@@ -12,8 +12,7 @@
  * </p>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @since 1.0.0
  */
-package io.github.og4dev.config;
-
+package io.github.og4dev.config;
\ No newline at end of file
diff --git a/src/main/java/io/github/og4dev/dto/ApiResponse.java b/src/main/java/io/github/og4dev/dto/ApiResponse.java
index 36d202f..0c81a03 100644
--- a/src/main/java/io/github/og4dev/dto/ApiResponse.java
+++ b/src/main/java/io/github/og4dev/dto/ApiResponse.java
@@ -49,7 +49,7 @@
  *
  * @param <T> the type of the response content (can be any Java type or Void for no content)
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @since 1.0.0
  * @see org.springframework.http.ResponseEntity
  * @see org.springframework.http.HttpStatus
diff --git a/src/main/java/io/github/og4dev/dto/package-info.java b/src/main/java/io/github/og4dev/dto/package-info.java
index a733fe1..6c20b78 100644
--- a/src/main/java/io/github/og4dev/dto/package-info.java
+++ b/src/main/java/io/github/og4dev/dto/package-info.java
@@ -17,7 +17,7 @@
  * </p>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @since 1.0.0
  */
 package io.github.og4dev.dto;
\ No newline at end of file
diff --git a/src/main/java/io/github/og4dev/exception/ApiException.java b/src/main/java/io/github/og4dev/exception/ApiException.java
index 7f74a10..77cf7f4 100644
--- a/src/main/java/io/github/og4dev/exception/ApiException.java
+++ b/src/main/java/io/github/og4dev/exception/ApiException.java
@@ -38,7 +38,7 @@
  * </ul>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @since 1.0.0
  * @see io.github.og4dev.exception.GlobalExceptionHandler
  * @see org.springframework.http.HttpStatus
diff --git a/src/main/java/io/github/og4dev/exception/GlobalExceptionHandler.java b/src/main/java/io/github/og4dev/exception/GlobalExceptionHandler.java
index 5341b06..e2a3499 100644
--- a/src/main/java/io/github/og4dev/exception/GlobalExceptionHandler.java
+++ b/src/main/java/io/github/og4dev/exception/GlobalExceptionHandler.java
@@ -75,7 +75,7 @@
  * </ul>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @since 1.0.0
  * @see org.springframework.web.bind.annotation.RestControllerAdvice
  * @see org.springframework.http.ProblemDetail
diff --git a/src/main/java/io/github/og4dev/exception/package-info.java b/src/main/java/io/github/og4dev/exception/package-info.java
index 376efcf..6e81223 100644
--- a/src/main/java/io/github/og4dev/exception/package-info.java
+++ b/src/main/java/io/github/og4dev/exception/package-info.java
@@ -26,7 +26,7 @@
  * </ul>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @since 1.0.0
  */
 package io.github.og4dev.exception;
diff --git a/src/main/java/io/github/og4dev/filter/TraceIdFilter.java b/src/main/java/io/github/og4dev/filter/TraceIdFilter.java
index 3c1b261..658d146 100644
--- a/src/main/java/io/github/og4dev/filter/TraceIdFilter.java
+++ b/src/main/java/io/github/og4dev/filter/TraceIdFilter.java
@@ -57,7 +57,7 @@
  * </p>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @since 1.0.0
  * @see org.springframework.web.filter.OncePerRequestFilter
  * @see org.slf4j.MDC
diff --git a/src/main/java/io/github/og4dev/filter/package-info.java b/src/main/java/io/github/og4dev/filter/package-info.java
index 5ed5ef8..dcff3f0 100644
--- a/src/main/java/io/github/og4dev/filter/package-info.java
+++ b/src/main/java/io/github/og4dev/filter/package-info.java
@@ -21,7 +21,7 @@
  * </p>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @since 1.0.0
  */
 package io.github.og4dev.filter;
diff --git a/src/main/java/io/github/og4dev/package-info.java b/src/main/java/io/github/og4dev/package-info.java
index 543a2fc..a471b48 100644
--- a/src/main/java/io/github/og4dev/package-info.java
+++ b/src/main/java/io/github/og4dev/package-info.java
@@ -6,11 +6,11 @@
  * </p>
  * <p>
  * Simply add the dependency to your project, and all features are automatically enabled through
- * Spring Boot auto-configuration.
+ * Spring Boot autoconfiguration.
  * </p>
  *
  * @author Pasindu OG
- * @version 1.3.0
+ * @version 1.4.0
  * @since 1.0.0
  */
 package io.github.og4dev;

From 15bf282d073a5dd24ae7dafbe123d1d2815599e2 Mon Sep 17 00:00:00 2001
From: Pasindu Owa Gamage <pasinduogdev@gmail.com>
Date: Sun, 1 Mar 2026 03:05:10 +0530
Subject: [PATCH 4/5] fix: enable @AutoResponse annotation at the method level

Updated the `supports` method in `GlobalResponseWrapper` to evaluate the presence of the `@AutoResponse` annotation on both the declaring class and the specific handler method. Previously, method-level annotations were ignored. Also updated the corresponding Javadoc to reflect the new evaluation criteria.
---
 README.md                                     |  52 +++-
 .../og4dev/advice/GlobalResponseWrapper.java  |  68 ++++-
 .../io/github/og4dev/annotation/AutoTrim.java |  71 ++---
 .../io/github/og4dev/annotation/XssCheck.java | 180 ++++++------
 .../config/ApiResponseAutoConfiguration.java  | 275 ++++--------------
 5 files changed, 282 insertions(+), 364 deletions(-)

diff --git a/README.md b/README.md
index 5b19353..58ba55a 100644
--- a/README.md
+++ b/README.md
@@ -105,7 +105,7 @@ A lightweight, type-safe API Response wrapper for Spring Boot applications. Stan
 * 🔌 **Spring Native** - Built on `ResponseEntity` and `HttpStatus`
 * 📋 **RFC 9457 Compliance** - Standard ProblemDetail format (supersedes RFC 7807)
 * 📚 **Complete JavaDoc** - Every class and method fully documented with comprehensive examples
-* 🔐 **Opt-in Security Features** - Fine-grained JSON request protection via field annotations
+* 🔐 **Opt-in Security Features** - Fine-grained JSON request protection via field and class-level annotations
 * ✅ **Strict JSON Validation** - Rejects unknown properties to prevent mass assignment attacks (automatic)
 * ✅ **XSS Prevention** - HTML tag detection and rejection via `@XssCheck` annotation (opt-in)
 * ✅ **Smart String Trimming** - Whitespace trimming via `@AutoTrim` annotation (opt-in)
@@ -125,8 +125,9 @@ Unlike other response wrapper libraries, this one offers:
 * ✅ **Native Spring Boot 3.x/4.x Auto-Configuration** - No manual setup required
 * ✅ **Zero-Boilerplate @AutoResponse** - Return raw objects, let the library wrap them automatically while preserving
   your HTTP Status codes.
+* ✅ **Intelligent String Handling** - Safely wraps raw `String` returns into JSON without throwing `ClassCastException`.
 * ✅ **RFC 9457 ProblemDetail Support** - Industry-standard error responses (latest RFC)
-* ✅ **Opt-in Security Features** - Fine-grained control via field-level annotations (`@XssCheck`, `@AutoTrim`)
+* ✅ **Opt-in Security Features** - Fine-grained control via field and **class-level** annotations (`@XssCheck`, `@AutoTrim`)
 * ✅ **Zero External Dependencies** - Pure Java implementation, won't conflict with your application
 * ✅ **Extensible Exception Handling** - Create custom business exceptions easily
 * ✅ **Trace ID Support** - Built-in distributed tracing capabilities
@@ -144,6 +145,7 @@ Unlike other response wrapper libraries, this one offers:
     <version>1.4.0</version>
 </dependency>
 
+
 ```
 
 ### Gradle (Latest - v1.4.0)
@@ -151,6 +153,7 @@ Unlike other response wrapper libraries, this one offers:
 ```gradle
 implementation 'io.github.og4dev:og4dev-spring-response:1.4.0'
 
+
 ```
 
 ### Gradle Kotlin DSL (Latest - v1.4.0)
@@ -158,6 +161,7 @@ implementation 'io.github.og4dev:og4dev-spring-response:1.4.0'
 ```kotlin
 implementation("io.github.og4dev:og4dev-spring-response:1.4.0")
 
+
 ```
 
 ---
@@ -184,6 +188,7 @@ io.github.og4dev
 └── filter/
     └── TraceIdFilter.java                   # Request trace ID generation
 
+
 ```
 
 ## 🎯 Quick Start
@@ -204,6 +209,7 @@ public class UserController {
     }
 }
 
+
 ```
 
 ### Method 2: Automatic Wrapping (New in v1.4.0) 🎁
@@ -228,8 +234,15 @@ public class UserController {
     public User createUser(@RequestBody UserDto dto) {
         return userService.create(dto);
     }
+
+    @GetMapping("/greeting")
+    public String greeting() {
+        // Raw strings are safely converted to JSON ApiResponse too!
+        return "Hello World"; 
+    }
 }
 
+
 ```
 
 **Both methods produce the exact same JSON:**
@@ -246,6 +259,7 @@ public class UserController {
   "timestamp": "2026-02-28T10:30:45.123Z"
 }
 
+
 ```
 
 ## ⚙️ Auto-Configuration
@@ -277,6 +291,7 @@ public class ProductController {
     // ...
 }
 
+
 ```
 
 ### Key Capabilities:
@@ -285,13 +300,14 @@ public class ProductController {
   Created) and reflects them in the `ApiResponse`.
 * ✅ **Double-Wrap Prevention:** Safely skips wrapping if you explicitly return an `ApiResponse` or `ResponseEntity`.
 * ✅ **Error Compatibility:** Bypasses `ProblemDetail` responses, ensuring standard error handling is never broken.
-* ✅ **String Safety:** Skips raw `String` returns to prevent `ClassCastException` with Spring's internal string message
-  converters.
+* ✅ **Intelligent String Handling:** Uses the injected `ObjectMapper` to serialize raw `String` returns into JSON format safely, preventing `ClassCastException` conflicts with Spring's native `StringHttpMessageConverter`.
 
 ## 🔐 Built-in Security Features
 
 The library provides fine-grained security and data processing features through field-level annotations. By default, **fields are NOT modified** unless explicitly annotated.
 
+*New in v1.4.0:* You can now apply `@AutoTrim` and `@XssCheck` to **entire classes** to protect all string fields at once!
+
 ### 1. Strict Property Validation 🛡️ (Automatic)
 
 Rejects JSON payloads containing unexpected fields to prevent mass assignment attacks.
@@ -305,6 +321,7 @@ Fail-fast HTML tag detection and rejection using regex pattern `(?s).*<\s*[a-zA-
 @XssCheck
 private String comment; // Rejects "<script>alert(1)</script>"
 
+
 ```
 
 ### 3. Opt-in String Trimming with @AutoTrim ✂️
@@ -316,6 +333,23 @@ Automatic whitespace removal for specific fields.
 @AutoTrim
 private String username; // "  john_doe  " -> "john_doe"
 
+
+```
+
+### 4. Class-Level Protection (New in v1.4.0) 🛡️
+
+Apply annotations to the class level to automatically protect **ALL** string fields within that class!
+
+```java
+@AutoTrim
+@XssCheck
+public class SecureRegistrationDTO {
+    // Both of these fields will be automatically trimmed and XSS-validated!
+    private String username;
+    private String email;
+    private String bio;
+}
+
 ```
 
 *(See full Security details in the Javadocs and examples above).*
@@ -336,6 +370,7 @@ public class ResourceNotFoundException extends ApiException {
     }
 }
 
+
 ```
 
 ## 🌍 Real-World Examples
@@ -376,6 +411,7 @@ public class ProductController {
     }
 }
 
+
 ```
 
 ## 📚 API Reference
@@ -392,8 +428,12 @@ public class ProductController {
 * Opt-in automatic response wrapping to eliminate boilerplate code.
 * Returns raw DTOs from controllers and automatically wraps them in `ApiResponse<T>`.
 * Preserves HTTP status codes from `@ResponseStatus`.
-* Intelligently skips `ResponseEntity`, `ApiResponse`, `ProblemDetail`, and `String` to prevent double-wrapping and
-  casting errors.
+* Intelligently skips `ResponseEntity`, `ApiResponse`, and `ProblemDetail` to prevent double-wrapping.
+* **Intelligent String Handling:** Uses Spring's `ObjectMapper` to safely serialize raw `String` returns to JSON, avoiding `ClassCastException` with native converters.
+
+
+* **Class-Level Security Annotations**
+* `@AutoTrim` and `@XssCheck` can now be applied at the Class level (`ElementType.TYPE`) to automatically protect all String fields within the DTO at once.
 
 
 * **package-info.java documentation** added for the new `advice` package.
diff --git a/src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java b/src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java
index fb694e3..8d4a2f9 100644
--- a/src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java
+++ b/src/main/java/io/github/og4dev/advice/GlobalResponseWrapper.java
@@ -15,6 +15,8 @@
 import org.springframework.http.server.ServletServerHttpResponse;
 import org.springframework.web.bind.annotation.RestControllerAdvice;
 import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.ObjectMapper;
 
 /**
  * Global response interceptor that automatically wraps REST controller outputs into the
@@ -32,6 +34,8 @@
  * <li><b>Status Code Preservation:</b> Dynamically reads the current HTTP status of the response
  * (e.g., set via {@code @ResponseStatus(HttpStatus.CREATED)}) and ensures it is accurately
  * reflected in the final {@code ApiResponse}.</li>
+ * <li><b>String Payload Compatibility:</b> Safely intercepts raw {@code String} returns and manually
+ * serializes them to prevent {@code ClassCastException} when Spring utilizes the {@code StringHttpMessageConverter}.</li>
  * <li><b>Safety Mechanisms:</b> Intelligently skips wrapping if the response is already formatted
  * to prevent double-wrapping errors or interference with standard error handling protocols.</li>
  * </ul>
@@ -43,13 +47,32 @@
  * @see ResponseBodyAdvice
  * @since 1.4.0
  */
-@RestControllerAdvice(annotations = AutoResponse.class)
+@RestControllerAdvice
 @SuppressWarnings("unused")
 public @NullMarked class GlobalResponseWrapper implements ResponseBodyAdvice<Object> {
 
+    private final ObjectMapper objectMapper;
+
+    /**
+     * Constructs a new {@code GlobalResponseWrapper} with the provided {@link ObjectMapper}.
+     *
+     * @param objectMapper The Jackson object mapper used for explicit string serialization.
+     */
+    public GlobalResponseWrapper(ObjectMapper objectMapper) {
+        this.objectMapper = objectMapper;
+    }
+
     /**
      * Determines whether the current response should be intercepted and wrapped.
      * <p>
+     * This method evaluates two main conditions before allowing the response to be wrapped:
+     * </p>
+     * <ol>
+     * <li><b>Annotation Presence:</b> The target controller class or the specific handler method
+     * must be annotated with {@link AutoResponse}.</li>
+     * <li><b>Type Exclusion:</b> The return type must <b>not</b> be one of the explicitly excluded types.</li>
+     * </ol>
+     * <p>
      * To guarantee application stability and adherence to standard HTTP protocols, this method
      * specifically <b>excludes</b> the following return types from being wrapped:
      * </p>
@@ -57,21 +80,26 @@
      * <li>{@link ApiResponse} - Prevents recursive double-wrapping (e.g., {@code ApiResponse<ApiResponse<T>>}).</li>
      * <li>{@link ResponseEntity} - Skips manual responses to respect developer's explicit configurations.</li>
      * <li>{@link ProblemDetail} - Excludes RFC 9457 error responses generated by exception handlers.</li>
-     * <li>{@link String} - Bypasses raw strings to prevent {@code ClassCastException} when Spring utilizes
-     * the {@code StringHttpMessageConverter}.</li>
      * </ul>
+     * <p>
+     * Note: Unlike standard wrappers, raw {@link String} payloads are <b>supported</b> and handled
+     * appropriately during the write phase.
+     * </p>
      *
      * @param returnType    The return type of the controller method.
      * @param converterType The selected HTTP message converter.
-     * @return {@code true} if the body should be wrapped; {@code false} if it should be skipped.
+     * @return {@code true} if annotated with {@code @AutoResponse} and not an excluded type; {@code false} otherwise.
      */
     @Override
     public @NullMarked boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
         Class<?> type = returnType.getParameterType();
-        return !ApiResponse.class.isAssignableFrom(type) &&
-                !ResponseEntity.class.isAssignableFrom(type) &&
-                !ProblemDetail.class.isAssignableFrom(type) &&
-                !String.class.isAssignableFrom(type);
+        boolean isExcludedType = ApiResponse.class.isAssignableFrom(type) ||
+                ResponseEntity.class.isAssignableFrom(type) ||
+                ProblemDetail.class.isAssignableFrom(type);
+        if (isExcludedType) return false;
+        boolean hasClassAnnotation = returnType.getDeclaringClass().isAnnotationPresent(AutoResponse.class);
+        boolean hasMethodAnnotation = returnType.hasMethodAnnotation(AutoResponse.class);
+        return hasClassAnnotation || hasMethodAnnotation;
     }
 
     /**
@@ -82,6 +110,12 @@
      * Based on whether the status code represents a success (2xx) or another state, it dynamically
      * assigns an appropriate message ("Success" or "Processed") to the API response.
      * </p>
+     * <p>
+     * <b>Special String Handling:</b> If the intercepted payload is a raw {@code String}, it is
+     * explicitly serialized to a JSON string using the configured {@link ObjectMapper}, and the
+     * response {@code Content-Type} is strictly set to {@code application/json}. This prevents
+     * standard message converter conflicts.
+     * </p>
      *
      * @param body                  The raw object returned by the controller method.
      * @param returnType            The return type of the controller method.
@@ -89,20 +123,28 @@
      * @param selectedConverterType The selected HTTP message converter.
      * @param request               The current server HTTP request.
      * @param response              The current server HTTP response.
-     * @return The newly wrapped {@code ApiResponse} object ready to be serialized.
+     * @return The newly wrapped {@code ApiResponse} object ready to be serialized, or a pre-serialized
+     * JSON {@code String} if the original payload was a raw string.
      */
     @Override
     public @Nullable Object beforeBodyWrite(@Nullable Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {
         int statusCode = HttpStatus.OK.value();
 
-        // Extract the dynamically set HTTP status code (e.g., from @ResponseStatus)
         if (response instanceof ServletServerHttpResponse serverHttpResponse) {
             statusCode = serverHttpResponse.getServletResponse().getStatus();
         }
-
         HttpStatus httpStatus = HttpStatus.valueOf(statusCode);
+        ApiResponse<Object> apiResponse = ApiResponse.status(httpStatus.is2xxSuccessful() ? "Success" : "Processed", body, httpStatus).getBody();
 
-        // Wrap the payload and generate the final format
-        return ApiResponse.status(httpStatus.is2xxSuccessful() ? "Success" : "Processed", body, httpStatus).getBody();
+        if (body instanceof String) {
+            try {
+                response.getHeaders().setContentType(MediaType.APPLICATION_JSON);
+                assert apiResponse != null;
+                return objectMapper.writeValueAsString(apiResponse);
+            } catch (JacksonException e) {
+                return body;
+            }
+        }
+        return apiResponse;
     }
 }
\ No newline at end of file
diff --git a/src/main/java/io/github/og4dev/annotation/AutoTrim.java b/src/main/java/io/github/og4dev/annotation/AutoTrim.java
index cb70fce..768079e 100644
--- a/src/main/java/io/github/og4dev/annotation/AutoTrim.java
+++ b/src/main/java/io/github/og4dev/annotation/AutoTrim.java
@@ -9,57 +9,57 @@
  * Annotation to explicitly enable automatic string trimming during JSON deserialization.
  * <p>
  * By default, the OG4Dev Spring API Response library does NOT automatically trim strings.
- * This annotation allows you to opt-in to automatic trimming for specific fields where
- * removing leading and trailing whitespace is desired for data quality and consistency.
+ * This annotation allows you to opt-in to automatic trimming for specific fields or entire
+ * classes where removing leading and trailing whitespace is desired for data quality and consistency.
  * </p>
  * <p>
  * <b>Important:</b> When {@code @AutoTrim} is applied, XSS validation (HTML tag detection)
  * is still performed on the trimmed value to maintain security.
  * </p>
  *
- * <h2>Use Cases</h2>
+ * <h2>Target Scopes</h2>
  * <ul>
- *   <li><b>User input fields:</b> Names, emails, addresses where whitespace is typically unwanted</li>
- *   <li><b>Search queries:</b> Remove accidental spaces from user search inputs</li>
- *   <li><b>Usernames:</b> Ensure consistent username formatting without leading/trailing spaces</li>
- *   <li><b>Reference numbers:</b> IDs, codes, or identifiers that should not have extra whitespace</li>
- *   <li><b>Categories/Tags:</b> Taxonomy values that need consistent formatting</li>
+ * <li><b>Field Level ({@link ElementType#FIELD}):</b> Applies trimming <i>only</i> to the specific annotated String field.</li>
+ * <li><b>Class Level ({@link ElementType#TYPE}):</b> Applies trimming to <i>all</i> String fields within the annotated class globally.</li>
  * </ul>
  *
- * <h2>Example Usage</h2>
+ * <h2>Example Usage: Field Level</h2>
  * <pre>{@code
  * public class UserRegistrationDTO {
- *     @AutoTrim
- *     private String username;       // Trimmed: "  john_doe  " → "john_doe"
+ * @AutoTrim
+ * private String username;       // Trimmed: "  john_doe  " → "john_doe"
  *
- *     @AutoTrim
- *     private String email;          // Trimmed: " user@example.com " → "user@example.com"
+ * @AutoTrim
+ * private String email;          // Trimmed: " user@example.com " → "user@example.com"
  *
- *     @AutoTrim
- *     private String firstName;      // Trimmed: "  John  " → "John"
+ * private String password;       // NOT trimmed (no annotation)
+ * private String bio;            // NOT trimmed (no annotation)
+ * }
+ * }</pre>
  *
- *     private String password;       // NOT trimmed (no annotation)
- *     private String bio;            // NOT trimmed (no annotation)
+ * <h2>Example Usage: Class Level</h2>
+ * <pre>{@code
+ * @AutoTrim // Automatically applies to ALL String fields in this class!
+ * public class GlobalTrimDTO {
+ * private String firstName;      // Trimmed: "  John  " → "John"
+ * private String lastName;       // Trimmed: " Doe  " → "Doe"
+ * private String address;        // Trimmed: " 123 Main St " → "123 Main St"
  * }
  * }</pre>
  *
- * <h2>Input/Output Examples</h2>
+ * <h2>Input/Output Examples (Class Level)</h2>
  * <pre>{@code
- * // Request JSON
+ * // Request JSON for GlobalTrimDTO
  * {
- *   "username": "  john_doe  ",
- *   "email": " john@example.com ",
- *   "firstName": "\t\nJohn\t\n",
- *   "password": "  myPass123  ",
- *   "bio": "  Software Developer  "
+ * "firstName": "\t\nJohn\t\n",
+ * "lastName": "  Doe  ",
+ * "address": " 123 Main St "
  * }
  *
  * // After Deserialization
- * username  = "john_doe"              // ✓ Trimmed (has @AutoTrim)
- * email     = "john@example.com"      // ✓ Trimmed (has @AutoTrim)
- * firstName = "John"                  // ✓ Trimmed (has @AutoTrim)
- * password  = "  myPass123  "         // ✗ NOT trimmed (no annotation)
- * bio       = "  Software Developer  " // ✗ NOT trimmed (no annotation)
+ * firstName = "John"                  // ✓ Trimmed (due to class-level @AutoTrim)
+ * lastName  = "Doe"                   // ✓ Trimmed (due to class-level @AutoTrim)
+ * address   = "123 Main St"           // ✓ Trimmed (due to class-level @AutoTrim)
  * }</pre>
  *
  * <h2>XSS Validation Still Active</h2>
@@ -77,10 +77,10 @@
  * You can combine {@code @AutoTrim} with {@link XssCheck @XssCheck} for both behaviors:
  * </p>
  * <pre>{@code
+ * @AutoTrim // Trims all fields
  * public class SecureDTO {
- *     @AutoTrim
- *     @XssCheck
- *     private String cleanInput;  // Both trimmed and XSS-validated
+ * @XssCheck
+ * private String cleanInput;  // Both trimmed (from class scope) and XSS-validated
  * }
  * }</pre>
  *
@@ -89,7 +89,8 @@
  * This annotation is processed by the {@code AdvancedStringDeserializer} in
  * {@link io.github.og4dev.config.ApiResponseAutoConfiguration#strictJsonCustomizer()}.
  * The deserializer uses {@link tools.jackson.databind.ValueDeserializer#createContextual}
- * to detect the annotation and create a specialized instance that enables trimming.
+ * to detect the annotation on either the field itself or its declaring class, creating a
+ * specialized instance that enables trimming.
  * </p>
  *
  * <h2>Null Value Handling</h2>
@@ -116,8 +117,8 @@
  * @see tools.jackson.databind.ValueDeserializer#createContextual
  * @since 1.3.0
  */
-@Target(ElementType.FIELD)
+@Target({ElementType.TYPE, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 @SuppressWarnings("unused")
 public @interface AutoTrim {
-}
+}
\ No newline at end of file
diff --git a/src/main/java/io/github/og4dev/annotation/XssCheck.java b/src/main/java/io/github/og4dev/annotation/XssCheck.java
index f009a8e..aadffea 100644
--- a/src/main/java/io/github/og4dev/annotation/XssCheck.java
+++ b/src/main/java/io/github/og4dev/annotation/XssCheck.java
@@ -10,34 +10,41 @@
  * <p>
  * By default, the OG4Dev Spring API Response library does NOT perform XSS validation on strings.
  * This annotation allows you to opt-in to automatic HTML/XML tag detection and rejection for specific fields
- * where preventing malicious content injection is critical for security.
+ * or <b>entire classes</b> where preventing malicious content injection is critical for security.
  * </p>
  * <p>
  * <b>Security Approach:</b> This annotation implements a <b>fail-fast rejection strategy</b> - requests
- * containing HTML tags are rejected entirely with a 400 Bad Request error. This is more secure than
+ * containing HTML tags are rejected entirely with a 400 Bad Request error.  This is more secure than
  * HTML escaping, as it prevents stored XSS, DOM-based XSS, and second-order injection vulnerabilities.
  * </p>
  *
- * <h2>Use Cases</h2>
+ * <h2>Target Scopes</h2>
  * <ul>
- *   <li><b>User-generated content:</b> Comments, reviews, forum posts, chat messages</li>
- *   <li><b>Profile information:</b> Usernames, display names, bio fields</li>
- *   <li><b>Search queries:</b> User input that will be displayed or processed</li>
- *   <li><b>Form inputs:</b> Any field that accepts free-form text from users</li>
- *   <li><b>API parameters:</b> String parameters that should not contain markup</li>
+ * <li><b>Field Level ({@link ElementType#FIELD}):</b> Applies XSS validation <i>only</i> to the specific annotated String field.</li>
+ * <li><b>Class Level ({@link ElementType#TYPE}):</b> Applies XSS validation to <i>all</i> String fields within the annotated class globally.</li>
  * </ul>
  *
- * <h2>Example Usage</h2>
+ * <h2>Example Usage: Field Level</h2>
  * <pre>{@code
  * public class CommentDTO {
- *     @XssCheck
- *     private String content;        // XSS validated - rejects HTML tags
+ * @XssCheck
+ * private String content;        // XSS validated - rejects HTML tags
  *
- *     @XssCheck
- *     private String authorName;     // XSS validated - rejects HTML tags
+ * @XssCheck
+ * private String authorName;     // XSS validated - rejects HTML tags
  *
- *     private String commentId;      // NOT validated (no annotation)
- *     private Instant timestamp;     // NOT validated (not a string)
+ * private String commentId;      // NOT validated (no annotation)
+ * private Instant timestamp;     // NOT validated (not a string)
+ * }
+ * }</pre>
+ *
+ * <h2>Example Usage: Class Level</h2>
+ * <pre>{@code
+ * @XssCheck // Automatically protects ALL String fields in this class!
+ * public class SecureUserProfileDTO {
+ * private String bio;            // XSS validated automatically
+ * private String displayName;    // XSS validated automatically
+ * private String websiteUrl;     // XSS validated automatically
  * }
  * }</pre>
  *
@@ -53,7 +60,7 @@
  * {"content": "<script>alert('XSS')</script>"}   // Script injection
  * {"content": "<img src=x onerror=alert(1)>"}    // Image XSS attack
  * {"content": "Hello<br>World"}                  // HTML break tag
- * {"content": "<!--comment-->"}                  // HTML comment
+ * {"content": ""}                  // HTML comment
  * {"content": "<!DOCTYPE html>"}                 // DOCTYPE declaration
  * {"content": "</div>"}                          // Closing tag
  * {"content": "<b>Bold text</b>"}                // HTML formatting
@@ -65,12 +72,12 @@
  * </p>
  * <pre>{@code
  * {
- *   "type": "about:blank",
- *   "title": "Bad Request",
- *   "status": 400,
- *   "detail": "Security Error: HTML tags or XSS payloads are not allowed in the request.",
- *   "traceId": "550e8400-e29b-41d4-a716-446655440000",
- *   "timestamp": "2026-02-21T10:30:45.123Z"
+ * "type": "about:blank",
+ * "title": "Bad Request",
+ * "status": 400,
+ * "detail": "Security Error: HTML tags or XSS payloads are not allowed in the request.",
+ * "traceId": "550e8400-e29b-41d4-a716-446655440000",
+ * "timestamp": "2026-02-21T10:30:45.123Z"
  * }
  * }</pre>
  *
@@ -82,20 +89,20 @@
  * This pattern detects:
  * </p>
  * <ul>
- *   <li><b>Opening tags:</b> {@code <script>}, {@code <img>}, {@code <div>}, {@code <iframe>}</li>
- *   <li><b>Closing tags:</b> {@code </div>}, {@code </script>}, {@code </body>}</li>
- *   <li><b>Self-closing tags:</b> {@code <br/>}, {@code <input/>}</li>
- *   <li><b>Special tags:</b> {@code <!DOCTYPE>}, {@code <!--comment-->}, {@code <![CDATA[]]>}</li>
- *   <li><b>Tags with attributes:</b> {@code <div class="test">}, {@code <img src="x">}</li>
- *   <li><b>Multiline tags:</b> Tags spanning multiple lines (DOTALL mode enabled)</li>
+ * <li><b>Opening tags:</b> {@code <script>}, {@code <img>}, {@code <div>}, {@code <iframe>}</li>
+ * <li><b>Closing tags:</b> {@code </div>}, {@code </script>}, {@code </body>}</li>
+ * <li><b>Self-closing tags:</b> {@code <br/>}, {@code <input/>}</li>
+ * <li><b>Special tags:</b> {@code <!DOCTYPE>}, {@code }, {@code <![CDATA[]]>}</li>
+ * <li><b>Tags with attributes:</b> {@code <div class="test">}, {@code <img src="x">}</li>
+ * <li><b>Multiline tags:</b> Tags spanning multiple lines (DOTALL mode enabled)</li>
  * </ul>
  * <p>
  * <b>What is NOT detected (safe to use):</b>
  * </p>
  * <ul>
- *   <li>Mathematical comparisons: {@code 5 < 10}, {@code x > y}</li>
- *   <li>Arrows and symbols: {@code -> <-}, {@code <=>}</li>
- *   <li>Quoted examples: {@code "less than symbol: <"} (if properly escaped in JSON)</li>
+ * <li>Mathematical comparisons: {@code 5 < 10}, {@code x > y}</li>
+ * <li>Arrows and symbols: {@code -> <-}, {@code <=>}</li>
+ * <li>Quoted examples: {@code "less than symbol: <"} (if properly escaped in JSON)</li>
  * </ul>
  *
  * <h2>Why Rejection Instead of Escaping?</h2>
@@ -104,11 +111,11 @@
  * This is more secure because:
  * </p>
  * <ul>
- *   <li><b>Prevents stored XSS:</b> Malicious content never enters your database</li>
- *   <li><b>Prevents DOM-based XSS:</b> No chance of client-side re-interpretation</li>
- *   <li><b>Prevents second-order attacks:</b> Escaped content cannot be un-escaped later</li>
- *   <li><b>Prevents encoding bypasses:</b> No risk of double-encoding vulnerabilities</li>
- *   <li><b>Clear security policy:</b> Users know HTML is not allowed</li>
+ * <li><b>Prevents stored XSS:</b> Malicious content never enters your database</li>
+ * <li><b>Prevents DOM-based XSS:</b> No chance of client-side re-interpretation</li>
+ * <li><b>Prevents second-order attacks:</b> Escaped content cannot be un-escaped later</li>
+ * <li><b>Prevents encoding bypasses:</b> No risk of double-encoding vulnerabilities</li>
+ * <li><b>Clear security policy:</b> Users know HTML is not allowed</li>
  * </ul>
  *
  * <h2>Combining with @AutoTrim</h2>
@@ -116,19 +123,11 @@
  * You can combine {@code @XssCheck} with {@link AutoTrim @AutoTrim} for both behaviors:
  * </p>
  * <pre>{@code
+ * @XssCheck // Protects all fields
  * public class SecureInputDTO {
- *     @AutoTrim
- *     @XssCheck
- *     private String username;  // First trimmed, then XSS-validated
- *
- *     @XssCheck
- *     private String comment;   // Only XSS-validated (not trimmed)
+ * @AutoTrim // Trims only this field
+ * private String username;
  * }
- *
- * // Processing order:
- * // 1. String is trimmed (if @AutoTrim is present)
- * // 2. Trimmed string is checked for HTML tags (if @XssCheck is present)
- * // 3. If HTML tags found, IllegalArgumentException is thrown
  * }</pre>
  *
  * <h2>How It Works</h2>
@@ -136,7 +135,8 @@
  * This annotation is processed by the {@code AdvancedStringDeserializer} in
  * {@link io.github.og4dev.config.ApiResponseAutoConfiguration#strictJsonCustomizer()}.
  * The deserializer uses {@link tools.jackson.databind.ValueDeserializer#createContextual}
- * to detect the annotation and create a specialized instance that enables XSS validation.
+ * to detect the annotation on either the field itself or its declaring class, creating a
+ * specialized instance that enables XSS validation.
  * </p>
  *
  * <h2>Null Value Handling</h2>
@@ -158,46 +158,46 @@
  *
  * <h2>When to Use This Annotation</h2>
  * <table border="1" cellpadding="5">
- *   <tr>
- *     <th>Field Type</th>
- *     <th>Use @XssCheck?</th>
- *     <th>Reason</th>
- *   </tr>
- *   <tr>
- *     <td>User comments</td>
- *     <td>✅ Yes</td>
- *     <td>User-generated content that will be displayed</td>
- *   </tr>
- *   <tr>
- *     <td>Profile bio</td>
- *     <td>✅ Yes</td>
- *     <td>Free-form text that could contain malicious content</td>
- *   </tr>
- *   <tr>
- *     <td>Search queries</td>
- *     <td>✅ Yes</td>
- *     <td>User input that might be echoed back</td>
- *   </tr>
- *   <tr>
- *     <td>Email address</td>
- *     <td>⚠️ Optional</td>
- *     <td>Use if email will be displayed; skip if only stored</td>
- *   </tr>
- *   <tr>
- *     <td>IDs/UUIDs</td>
- *     <td>❌ No</td>
- *     <td>Structured format, not free-form text</td>
- *   </tr>
- *   <tr>
- *     <td>Timestamps</td>
- *     <td>❌ No</td>
- *     <td>Not a string field</td>
- *   </tr>
- *   <tr>
- *     <td>Rich text (HTML editor)</td>
- *     <td>❌ No</td>
- *     <td>Intentionally contains HTML; use server-side sanitization instead</td>
- *   </tr>
+ * <tr>
+ * <th>Field Type</th>
+ * <th>Use @XssCheck?</th>
+ * <th>Reason</th>
+ * </tr>
+ * <tr>
+ * <td>User comments</td>
+ * <td>✅ Yes</td>
+ * <td>User-generated content that will be displayed</td>
+ * </tr>
+ * <tr>
+ * <td>Profile bio</td>
+ * <td>✅ Yes</td>
+ * <td>Free-form text that could contain malicious content</td>
+ * </tr>
+ * <tr>
+ * <td>Search queries</td>
+ * <td>✅ Yes</td>
+ * <td>User input that might be echoed back</td>
+ * </tr>
+ * <tr>
+ * <td>Email address</td>
+ * <td>⚠️ Optional</td>
+ * <td>Use if email will be displayed; skip if only stored</td>
+ * </tr>
+ * <tr>
+ * <td>IDs/UUIDs</td>
+ * <td>❌ No</td>
+ * <td>Structured format, not free-form text</td>
+ * </tr>
+ * <tr>
+ * <td>Timestamps</td>
+ * <td>❌ No</td>
+ * <td>Not a string field</td>
+ * </tr>
+ * <tr>
+ * <td>Rich text (HTML editor)</td>
+ * <td>❌ No</td>
+ * <td>Intentionally contains HTML; use server-side sanitization instead</td>
+ * </tr>
  * </table>
  *
  * @author Pasindu OG
@@ -207,8 +207,8 @@
  * @see tools.jackson.databind.ValueDeserializer#createContextual
  * @since 1.3.0
  */
-@Target(ElementType.FIELD)
+@Target({ElementType.TYPE, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 @SuppressWarnings("unused")
 public @interface XssCheck {
-}
+}
\ No newline at end of file
diff --git a/src/main/java/io/github/og4dev/config/ApiResponseAutoConfiguration.java b/src/main/java/io/github/og4dev/config/ApiResponseAutoConfiguration.java
index 240b0e1..f5df5a7 100644
--- a/src/main/java/io/github/og4dev/config/ApiResponseAutoConfiguration.java
+++ b/src/main/java/io/github/og4dev/config/ApiResponseAutoConfiguration.java
@@ -83,7 +83,11 @@ public ApiResponseAutoConfiguration() {
 
     /**
      * Registers the {@link GlobalExceptionHandler} as a Spring bean for automatic exception handling.
-     * * // ... (පරණ JavaDoc එකමයි, වෙනස් වෙන්නේ නෑ) ...
+     * <p>
+     * The handler provides comprehensive centralized exception management using Spring's
+     * {@link org.springframework.web.bind.annotation.RestControllerAdvice} mechanism,
+     * automatically converting various exceptions to RFC 9457 ProblemDetail responses.
+     * </p>
      * * @return A new instance of {@link GlobalExceptionHandler} registered as a Spring bean.
      */
     @Bean
@@ -107,6 +111,9 @@ public GlobalExceptionHandler apiResponseAdvisor() {
      * set via {@code @ResponseStatus} (e.g., 201 Created).</li>
      * <li><b>Double-Wrap Prevention:</b> Safely skips wrapping if the controller already returns
      * an {@code ApiResponse} or {@code ResponseEntity}.</li>
+     * <li><b>String Payload Support:</b> Safely intercepts and serializes raw {@code String} returns
+     * using the injected {@link ObjectMapper} to prevent {@code ClassCastException} with Spring's
+     * native message converters.</li>
      * <li><b>Error Compatibility:</b> Bypasses {@code ProblemDetail} and exception responses to maintain
      * RFC 9457 compliance managed by {@link GlobalExceptionHandler}.</li>
      * </ul>
@@ -134,24 +141,26 @@ public GlobalExceptionHandler apiResponseAdvisor() {
      * <b>Note:</b> This bean is conditionally loaded using {@code @ConditionalOnMissingBean}, allowing developers
      * to easily override the default wrapping behavior by defining their own {@code GlobalResponseWrapper} bean.
      * </p>
-     * * @return A new instance of {@link GlobalResponseWrapper} registered as a Spring bean.
+     *
+     * @param objectMapper The Jackson object mapper injected by Spring, used by the wrapper for explicit string serialization.
+     * @return A new instance of {@link GlobalResponseWrapper} registered as a Spring bean.
      * @see AutoResponse
      * @see io.github.og4dev.dto.ApiResponse
      * @since 1.4.0
      */
     @Bean
-    @ConditionalOnMissingBean // මේක දැම්මොත් අනිත් අයට මේක override කරන්න පුළුවන්
-    public GlobalResponseWrapper globalResponseWrapper() {
-        return new GlobalResponseWrapper();
+    @ConditionalOnMissingBean
+    public GlobalResponseWrapper globalResponseWrapper(ObjectMapper objectMapper) {
+        return new GlobalResponseWrapper(objectMapper);
     }
 
     /**
-     * Configures strict JSON deserialization with opt-in security features via field-level annotations.
+     * Configures strict JSON deserialization with opt-in security features via field-level and class-level annotations.
      * <p>
      * This bean customizer enhances Jackson's JSON processing with production-ready security and data quality
-     * features that can be selectively applied to specific fields using the {@link AutoTrim @AutoTrim} and
-     * {@link XssCheck @XssCheck} annotations. By default, fields are NOT trimmed or XSS-validated unless
-     * explicitly annotated.
+     * features that can be selectively applied to specific fields or entire classes using the
+     * {@link AutoTrim @AutoTrim} and {@link XssCheck @XssCheck} annotations. By default, fields are NOT
+     * trimmed or XSS-validated unless explicitly annotated.
      * </p>
      *
      * <h2>Overview of Features</h2>
@@ -159,10 +168,10 @@ public GlobalResponseWrapper globalResponseWrapper() {
      * This configuration provides four critical layers of protection and data processing:
      * </p>
      * <ol>
-     *   <li><b>Strict Property Validation</b> - Prevents mass assignment attacks (automatic)</li>
-     *   <li><b>Case-Insensitive Enum Handling</b> - Improves API usability (automatic)</li>
-     *   <li><b>Opt-in XSS Prevention</b> - Blocks HTML/XML injection attacks (requires {@code @XssCheck})</li>
-     *   <li><b>Opt-in String Trimming</b> - Removes whitespace (requires {@code @AutoTrim})</li>
+     * <li><b>Strict Property Validation</b> - Prevents mass assignment attacks (automatic)</li>
+     * <li><b>Case-Insensitive Enum Handling</b> - Improves API usability (automatic)</li>
+     * <li><b>Opt-in XSS Prevention</b> - Blocks HTML/XML injection attacks (requires {@code @XssCheck} on field or class)</li>
+     * <li><b>Opt-in String Trimming</b> - Removes whitespace (requires {@code @AutoTrim} on field or class)</li>
      * </ol>
      *
      * <h2>Feature 1: Strict Property Validation</h2>
@@ -171,26 +180,10 @@ public GlobalResponseWrapper globalResponseWrapper() {
      * payloads containing unexpected fields. This prevents three critical security issues:
      * </p>
      * <ul>
-     *   <li><b>Mass Assignment Vulnerabilities:</b> Attackers cannot inject fields like {@code isAdmin: true}</li>
-     *   <li><b>Data Injection Attacks:</b> Prevents modification of unintended database fields</li>
-     *   <li><b>Client Errors:</b> Detects typos early, preventing silent data loss</li>
+     * <li><b>Mass Assignment Vulnerabilities:</b> Attackers cannot inject fields like {@code isAdmin: true}</li>
+     * <li><b>Data Injection Attacks:</b> Prevents modification of unintended database fields</li>
+     * <li><b>Client Errors:</b> Detects typos early, preventing silent data loss</li>
      * </ul>
-     * <p>
-     * <b>Example:</b>
-     * </p>
-     * <pre>{@code
-     * // DTO Definition
-     * public class UserDTO {
-     *     private String name;
-     *     private String email;
-     * }
-     *
-     * // Valid Request
-     * {"name": "John", "email": "john@example.com"}  // ✓ Success
-     *
-     * // Invalid Request (will be rejected with 400 Bad Request)
-     * {"name": "John", "email": "john@example.com", "isAdmin": true}  // ✗ Unknown field
-     * }</pre>
      *
      * <h2>Feature 2: Case-Insensitive Enum Handling</h2>
      * <p>
@@ -198,221 +191,57 @@ public GlobalResponseWrapper globalResponseWrapper() {
      * deserialization. Clients can send enum values in any case format, improving API
      * usability without compromising type safety or security.
      * </p>
-     * <p>
-     * <b>Example:</b>
-     * </p>
-     * <pre>{@code
-     * public enum Status { ACTIVE, INACTIVE, PENDING }
-     *
-     * // All these are accepted and map to Status.ACTIVE:
-     * {"status": "ACTIVE"}   // ✓ Original
-     * {"status": "active"}   // ✓ Lowercase
-     * {"status": "Active"}   // ✓ Title case
-     * {"status": "AcTiVe"}   // ✓ Mixed case
-     * }</pre>
      *
      * <h2>Feature 3: Opt-in XSS Prevention with @XssCheck</h2>
      * <p>
      * Registers a custom {@link StdScalarDeserializer} ({@code AdvancedStringDeserializer})
      * that performs automatic HTML/XML tag detection and rejection at the deserialization layer
-     * for fields annotated with {@link XssCheck @XssCheck}. This provides fail-fast security
+     * for fields or classes annotated with {@link XssCheck @XssCheck}. This provides fail-fast security
      * that prevents malicious content from ever entering your system.
      * </p>
-     * <p>
-     * <b>Default Behavior (No Annotation):</b> Fields are NOT validated for HTML tags
-     * </p>
-     * <p>
-     * <b>With @XssCheck Annotation:</b> HTML tags are detected and rejected
-     * </p>
-     * <p>
-     * <b>Detection Mechanism:</b>
-     * </p>
-     * <ul>
-     *   <li>Uses regex pattern: {@code (?s).*<\s*[a-zA-Z/!].*}</li>
-     *   <li>Detects opening tags: {@code <script>}, {@code <img>}, {@code <div>}</li>
-     *   <li>Detects closing tags: {@code </div>}, {@code </script>}</li>
-     *   <li>Detects special tags: {@code <!DOCTYPE>}, {@code <!--comment-->}</li>
-     *   <li>Works across multiple lines (DOTALL mode enabled)</li>
-     * </ul>
-     * <p>
-     * <b>Security Advantage:</b> Unlike HTML escaping (which transforms {@code <} to {@code &lt;}),
-     * this approach rejects the request entirely. This prevents:
-     * </p>
-     * <ul>
-     *   <li>Stored XSS attacks</li>
-     *   <li>DOM-based XSS attacks</li>
-     *   <li>Second-order injection vulnerabilities</li>
-     *   <li>Encoding bypass attempts</li>
-     * </ul>
-     * <p>
-     * <b>Example:</b>
-     * </p>
-     * <pre>{@code
-     * public class CommentDTO {
-     *     @XssCheck
-     *     private String content;        // XSS validated
-     *
-     *     private String commentId;      // NOT validated (no annotation)
-     * }
-     *
-     * // Valid Requests (for content field with @XssCheck)
-     * {"content": "Hello World"}                     // ✓ Plain text
-     * {"content": "Price: $100 < $200"}              // ✓ Comparison operators (no tag)
-     * {"content": "2 + 2 = 4"}                       // ✓ Math expressions
-     *
-     * // Invalid Requests (throws IllegalArgumentException)
-     * {"content": "<script>alert('XSS')</script>"}   // ✗ Script injection
-     * {"content": "<img src=x onerror=alert(1)>"}    // ✗ Image XSS
-     * {"content": "Hello<br>World"}                  // ✗ HTML tags
-     * {"content": "<!--comment-->"}                  // ✗ HTML comments
-     * {"content": "<!DOCTYPE html>"}                 // ✗ DOCTYPE declaration
-     * }</pre>
      *
      * <h2>Feature 4: Opt-in String Trimming with @AutoTrim</h2>
      * <p>
-     * Automatically removes leading and trailing whitespace from string fields annotated with
+     * Automatically removes leading and trailing whitespace from string fields or entire classes annotated with
      * {@link AutoTrim @AutoTrim}, improving data quality and preventing common user input errors.
-     * Fields without the annotation preserve their original whitespace.
-     * </p>
-     *
-     * <h3>Default Behavior (No Annotation)</h3>
-     * <p>
-     * By default, string fields preserve all whitespace:
      * </p>
-     * <pre>{@code
-     * public class UserDTO {
-     *     private String username;  // NOT trimmed (no annotation)
-     *     private String email;     // NOT trimmed (no annotation)
-     * }
-     *
-     * // Input                            → Output
-     * {"username": "  john  "}            → {"username": "  john  "}
-     * {"email": " test@example.com   "}   → {"email": " test@example.com   "}
-     * }</pre>
      *
-     * <h3>Opt-in with @AutoTrim Annotation</h3>
+     * <h3>Combining Features (Class and Field Level)</h3>
      * <p>
-     * The {@code AdvancedStringDeserializer} implements context-aware deserialization using
-     * {@link ValueDeserializer#createContextual(DeserializationContext, BeanProperty)}.
-     * When it detects the {@code @AutoTrim} annotation on a field, it creates a specialized
-     * deserializer instance with trimming enabled.
-     * </p>
-     * <p>
-     * <b>Use Cases for @AutoTrim:</b>
-     * </p>
-     * <ul>
-     *   <li><b>User Input Fields:</b> Names, emails, addresses where whitespace is unwanted</li>
-     *   <li><b>Search Queries:</b> Remove accidental spaces from user inputs</li>
-     *   <li><b>Usernames:</b> Ensure consistent formatting without extra spaces</li>
-     *   <li><b>Reference Numbers:</b> IDs, codes that should not have whitespace</li>
-     * </ul>
-     * <p>
-     * <b>Example:</b>
-     * </p>
-     * <pre>{@code
-     * public class LoginDTO {
-     *     @AutoTrim
-     *     private String username;       // Trimmed: "  admin  " → "admin"
-     *
-     *     private String password;       // NOT trimmed: "  pass123  " → "  pass123  "
-     * }
-     *
-     * public class ProductDTO {
-     *     @AutoTrim
-     *     private String name;           // Trimmed
-     *
-     *     private String description;    // NOT trimmed: preserves formatting
-     * }
-     * }</pre>
-     *
-     * <h3>Combining Both Annotations</h3>
-     * <p>
-     * You can use both annotations together for fields that need both trimming and XSS validation:
+     * You can combine these annotations at both the class and field levels. Class-level annotations
+     * apply to all string fields within the class automatically:
      * </p>
      * <pre>{@code
+     * @AutoTrim // Automatically trims ALL strings in this class
      * public class SecureDTO {
-     *     @AutoTrim
-     *     @XssCheck
-     *     private String cleanInput;  // First trimmed, then XSS-validated
+     * @XssCheck
+     * private String cleanInput;  // Both trimmed (from class scope) and XSS-validated
+     * * private String email;       // Only trimmed (from class scope)
      * }
-     *
-     * // These will be rejected (after trimming):
-     * {"cleanInput": "  <script>alert(1)</script>  "}  // ✗ XSS attempt blocked
-     * {"cleanInput": "  <img src=x>  "}               // ✗ HTML tag blocked
      * }</pre>
      *
      * <h2>Implementation Details</h2>
      * <p>
      * This method registers an inner class {@code AdvancedStringDeserializer} that extends
      * {@link StdScalarDeserializer}{@code <String>}. The deserializer operates in different modes
-     * based on field annotations:
+     * based on annotations:
      * </p>
      * <ul>
-     *   <li><b>Default Mode:</b> No processing (preserves original value)</li>
-     *   <li><b>Trim Mode:</b> {@code shouldTrim = true} when {@code @AutoTrim} is present</li>
-     *   <li><b>XSS Mode:</b> {@code shouldXssCheck = true} when {@code @XssCheck} is present</li>
-     *   <li><b>Combined Mode:</b> Both trimming and validation when both annotations present</li>
+     * <li><b>Default Mode:</b> No processing (preserves original value)</li>
+     * <li><b>Trim Mode:</b> {@code shouldTrim = true} when {@code @AutoTrim} is present on the field or class</li>
+     * <li><b>XSS Mode:</b> {@code shouldXssCheck = true} when {@code @XssCheck} is present on the field or class</li>
+     * <li><b>Combined Mode:</b> Both trimming and validation when both annotations are present</li>
      * </ul>
      * <p>
-     * The {@code createContextual()} method inspects each field's annotations during
-     * deserialization context creation and returns an appropriately configured deserializer instance.
+     * The {@code createContextual()} method inspects each field's annotations, as well as its
+     * declaring class's annotations, during deserialization context creation and returns an
+     * appropriately configured deserializer instance.
      * </p>
      *
-     * <h2>Global Application Scope</h2>
-     * <p>
-     * As a {@link JsonMapperBuilderCustomizer} bean, these settings are automatically applied
-     * to Spring Boot's default {@link tools.jackson.databind.ObjectMapper}, affecting:
-     * </p>
-     * <ul>
-     *   <li>All {@code @RequestBody} deserialization in REST controllers</li>
-     *   <li>All {@code @ResponseBody} serialization</li>
-     *   <li>WebSocket message handling</li>
-     *   <li>Spring Data REST endpoints</li>
-     *   <li>Spring Cloud Feign clients</li>
-     *   <li>Any component using the autoconfigured ObjectMapper</li>
-     * </ul>
-     *
      * <h2>Null Value Handling</h2>
      * <p>
-     * Null values are preserved and never converted to empty strings:
-     * </p>
-     * <pre>{@code
-     * {"name": null}      → name = null (not "")
-     * {"name": ""}        → name = ""
-     * {"name": "  "}      → name = "  " (unchanged unless @AutoTrim is used)
-     * }</pre>
-     *
-     * <h2>Disabling These Features</h2>
-     * <p>
-     * If you need to disable any of these features, you have three options:
+     * Null values are preserved and never converted to empty strings.
      * </p>
-     * <ol>
-     *   <li><b>Exclude Auto-Configuration:</b>
-     *     <pre>{@code
-     * @SpringBootApplication(exclude = ApiResponseAutoConfiguration.class)
-     * public class Application { }
-     *     }</pre>
-     *   </li>
-     *   <li><b>Override with @Primary Bean:</b>
-     *     <pre>{@code
-     * @Configuration
-     * public class CustomConfig {
-     *     @Bean
-     *     @Primary
-     *     public JsonMapperBuilderCustomizer myCustomizer() {
-     *         return builder -> {
-     *             // Your custom configuration
-     *         };
-     *     }
-     * }
-     *     }</pre>
-     *   </li>
-     *   <li><b>Use Application Properties:</b>
-     *     <pre>
-     * spring.autoconfigure.exclude=io.github.og4dev.config.ApiResponseAutoConfiguration
-     *     </pre>
-     *   </li>
-     * </ol>
      *
      * <h2>Performance Considerations</h2>
      * <p>
@@ -422,8 +251,8 @@ public GlobalResponseWrapper globalResponseWrapper() {
      * </p>
      *
      * @return A {@link JsonMapperBuilderCustomizer} that configures strict JSON processing
-     *         with opt-in string validation via {@code @XssCheck}, opt-in trimming via {@code @AutoTrim},
-     *         unknown property rejection, and case-insensitive enum handling.
+     * with opt-in string validation via {@code @XssCheck}, opt-in trimming via {@code @AutoTrim},
+     * unknown property rejection, and case-insensitive enum handling.
      * @see DeserializationFeature#FAIL_ON_UNKNOWN_PROPERTIES
      * @see MapperFeature#ACCEPT_CASE_INSENSITIVE_ENUMS
      * @see io.github.og4dev.annotation.AutoTrim
@@ -461,9 +290,7 @@ public String deserialize(JsonParser p, DeserializationContext ctxt) throws Jack
                     String value = p.getValueAsString();
                     if (value == null) return null;
                     String processedValue = shouldTrim ? value.trim() : value;
-                    if (shouldXssCheck && processedValue.matches("(?s).*<\\s*[a-zA-Z/!].*")) {
-                        throw new IllegalArgumentException("Security Error: HTML tags or XSS payloads are not allowed in the request.");
-                    }
+                    if (shouldXssCheck && processedValue.matches("(?s).*<\\s*[a-zA-Z/!].*")) throw new IllegalArgumentException("Security Error: HTML tags or XSS payloads are not allowed in the request.");
                     return processedValue;
                 }
 
@@ -472,6 +299,14 @@ public ValueDeserializer<?> createContextual(DeserializationContext ct, BeanProp
                     if (property != null) {
                         boolean trim = property.getAnnotation(AutoTrim.class) != null;
                         boolean xss = property.getAnnotation(XssCheck.class) != null;
+
+                        if ((!trim || !xss) && property.getMember() != null) {
+                            Class<?> declaringClass = property.getMember().getDeclaringClass();
+                            if (declaringClass != null) {
+                                if (!trim) trim = declaringClass.getAnnotation(AutoTrim.class) != null;
+                                if (!xss) xss = declaringClass.getAnnotation(XssCheck.class) != null;
+                            }
+                        }
                         return new AdvancedStringDeserializer(trim, xss);
                     }
                     return this;
@@ -481,4 +316,4 @@ public ValueDeserializer<?> createContextual(DeserializationContext ct, BeanProp
             builder.addModules(stringTrimModule);
         };
     }
-}
+}
\ No newline at end of file

From 75a7f6a374424a5f5b1329bf826707161b6ac2cd Mon Sep 17 00:00:00 2001
From: Pasindu Owa Gamage <pasinduogdev@gmail.com>
Date: Sun, 1 Mar 2026 03:08:55 +0530
Subject: [PATCH 5/5] Update README

---
 README.md | 74 +++++++++++++++++--------------------------------------
 1 file changed, 23 insertions(+), 51 deletions(-)

diff --git a/README.md b/README.md
index 58ba55a..e5730cf 100644
--- a/README.md
+++ b/README.md
@@ -79,7 +79,7 @@ A lightweight, type-safe API Response wrapper for Spring Boot applications. Stan
 ## 🎯 Key Highlights
 
 * 🚀 **Truly Zero Configuration** - Spring Boot 3.x/4.x auto-configuration with META-INF imports
-* 🎁 **Zero Boilerplate** - Opt-in `@AutoResponse` to automatically wrap raw return types
+* 🎁 **Zero Boilerplate** - Opt-in `@AutoResponse` to automatically wrap raw return types (Class or Method level)
 * 🎯 **Production-Ready** - Built-in RFC 9457 ProblemDetail with 10 comprehensive exception handlers
 * 🛡️ **Complete Error Coverage** - Handles validation, JSON parsing, 404s, method mismatches, media types, and more
 * 🔍 **Trace IDs in Errors** - Error responses include traceId for debugging
@@ -88,7 +88,7 @@ A lightweight, type-safe API Response wrapper for Spring Boot applications. Stan
 * 🔍 **Microservices-Ready** - Built-in trace IDs for distributed tracing
 * ✅ **Battle-Tested** - Used in production Spring Boot applications
 * 📋 **Professional-Grade Javadoc** - 100% coverage with comprehensive method documentation
-* 🔐 **Opt-in Security Features** - Fine-grained control with field-level annotations
+* 🔐 **Opt-in Security Features** - Fine-grained control with field and class-level annotations
 * 🚫 **Zero External Dependencies** - Pure Java, no Lombok required
 
 ## ✨ Features
@@ -123,8 +123,7 @@ A lightweight, type-safe API Response wrapper for Spring Boot applications. Stan
 Unlike other response wrapper libraries, this one offers:
 
 * ✅ **Native Spring Boot 3.x/4.x Auto-Configuration** - No manual setup required
-* ✅ **Zero-Boilerplate @AutoResponse** - Return raw objects, let the library wrap them automatically while preserving
-  your HTTP Status codes.
+* ✅ **Zero-Boilerplate @AutoResponse** - Return raw objects, let the library wrap them automatically while preserving your HTTP Status codes. **Supports both Class-level and Method-level granularity.**
 * ✅ **Intelligent String Handling** - Safely wraps raw `String` returns into JSON without throwing `ClassCastException`.
 * ✅ **RFC 9457 ProblemDetail Support** - Industry-standard error responses (latest RFC)
 * ✅ **Opt-in Security Features** - Fine-grained control via field and **class-level** annotations (`@XssCheck`, `@AutoTrim`)
@@ -138,14 +137,12 @@ Unlike other response wrapper libraries, this one offers:
 ### Maven (Latest - v1.4.0)
 
 ```xml
-
 <dependency>
     <groupId>io.github.og4dev</groupId>
     <artifactId>og4dev-spring-response</artifactId>
     <version>1.4.0</version>
 </dependency>
 
-
 ```
 
 ### Gradle (Latest - v1.4.0)
@@ -153,7 +150,6 @@ Unlike other response wrapper libraries, this one offers:
 ```gradle
 implementation 'io.github.og4dev:og4dev-spring-response:1.4.0'
 
-
 ```
 
 ### Gradle Kotlin DSL (Latest - v1.4.0)
@@ -161,7 +157,6 @@ implementation 'io.github.og4dev:og4dev-spring-response:1.4.0'
 ```kotlin
 implementation("io.github.og4dev:og4dev-spring-response:1.4.0")
 
-
 ```
 
 ---
@@ -188,7 +183,6 @@ io.github.og4dev
 └── filter/
     └── TraceIdFilter.java                   # Request trace ID generation
 
-
 ```
 
 ## 🎯 Quick Start
@@ -198,7 +192,6 @@ You can use the library in two ways: **Explicit Factory Methods** or **Automatic
 ### Method 1: Explicit Factory Methods
 
 ```java
-
 @RestController
 @RequestMapping("/api/users")
 public class UserController {
@@ -209,32 +202,33 @@ public class UserController {
     }
 }
 
-
 ```
 
 ### Method 2: Automatic Wrapping (New in v1.4.0) 🎁
 
-Tired of typing `ResponseEntity<ApiResponse<T>>`? Use `@AutoResponse`!
+Tired of typing `ResponseEntity<ApiResponse<T>>`? Use `@AutoResponse`! You can apply it to the whole class, or just specific methods.
 
 ```java
-
 @RestController
 @RequestMapping("/api/users")
-@AutoResponse // Applies to all methods in this controller
+// @AutoResponse // Uncomment this to apply to ALL methods in the controller
 public class UserController {
 
+    @AutoResponse // Applied ONLY to this specific method
     @GetMapping("/{id}")
     public User getUser(@PathVariable Long id) {
         // Just return the raw object!
         return userService.findById(id);
     }
 
+    @AutoResponse
     @PostMapping
     @ResponseStatus(HttpStatus.CREATED) // Preserves custom status codes!
     public User createUser(@RequestBody UserDto dto) {
         return userService.create(dto);
     }
 
+    @AutoResponse
     @GetMapping("/greeting")
     public String greeting() {
         // Raw strings are safely converted to JSON ApiResponse too!
@@ -242,7 +236,6 @@ public class UserController {
     }
 }
 
-
 ```
 
 **Both methods produce the exact same JSON:**
@@ -259,7 +252,6 @@ public class UserController {
   "timestamp": "2026-02-28T10:30:45.123Z"
 }
 
-
 ```
 
 ## ⚙️ Auto-Configuration
@@ -267,37 +259,23 @@ public class UserController {
 The library features **Spring Boot Auto-Configuration** for truly zero-config setup!
 
 ✅ **GlobalExceptionHandler** - Automatic exception handling
-
 ✅ **GlobalResponseWrapper** - Automatic payload wrapping via `@AutoResponse`
-
 ✅ **Security Customizers** - Jackson configuration for `@AutoTrim` and `@XssCheck`
 
 **No configuration needed!** Just add the dependency.
 
 ## 🎁 Opt-in Automatic Wrapping (@AutoResponse)
 
-Introduced in **v1.4.0**, you can eliminate boilerplate code by letting the library wrap your controller responses
-automatically.
-
-### How to use it:
-
-Add the `@AutoResponse` annotation to your controller class (applies to all methods) or to specific methods.
-
-```java
-
-@RestController
-@AutoResponse
-public class ProductController {
-    // ...
-}
+Introduced in **v1.4.0**, you can eliminate boilerplate code by letting the library wrap your controller responses automatically.
 
+### Flexible Granularity:
 
-```
+* **Class Level (`@Target(ElementType.TYPE)`):** Apply `@AutoResponse` to your controller class to automatically wrap *all* endpoint responses within it.
+* **Method Level (`@Target(ElementType.METHOD)`):** Apply `@AutoResponse` to specific request mapping methods for fine-grained, opt-in control over exactly which endpoints get wrapped.
 
 ### Key Capabilities:
 
-* ✅ **Status Code Preservation:** Intelligently reads custom HTTP status codes set via `@ResponseStatus` (e.g., 201
-  Created) and reflects them in the `ApiResponse`.
+* ✅ **Status Code Preservation:** Intelligently reads custom HTTP status codes set via `@ResponseStatus` (e.g., 201 Created) and reflects them in the `ApiResponse`.
 * ✅ **Double-Wrap Prevention:** Safely skips wrapping if you explicitly return an `ApiResponse` or `ResponseEntity`.
 * ✅ **Error Compatibility:** Bypasses `ProblemDetail` responses, ensuring standard error handling is never broken.
 * ✅ **Intelligent String Handling:** Uses the injected `ObjectMapper` to serialize raw `String` returns into JSON format safely, preventing `ClassCastException` conflicts with Spring's native `StringHttpMessageConverter`.
@@ -317,11 +295,9 @@ Rejects JSON payloads containing unexpected fields to prevent mass assignment at
 Fail-fast HTML tag detection and rejection using regex pattern `(?s).*<\s*[a-zA-Z/!].*`.
 
 ```java
-
 @XssCheck
 private String comment; // Rejects "<script>alert(1)</script>"
 
-
 ```
 
 ### 3. Opt-in String Trimming with @AutoTrim ✂️
@@ -329,11 +305,9 @@ private String comment; // Rejects "<script>alert(1)</script>"
 Automatic whitespace removal for specific fields.
 
 ```java
-
 @AutoTrim
 private String username; // "  john_doe  " -> "john_doe"
 
-
 ```
 
 ### 4. Class-Level Protection (New in v1.4.0) 🛡️
@@ -356,8 +330,7 @@ public class SecureRegistrationDTO {
 
 ## 🛡️ Built-in Exception Handling
 
-The library includes a **production-ready `GlobalExceptionHandler**` that automatically handles 10 common exceptions
-using Spring Boot's **ProblemDetail (RFC 9457)** standard.
+The library includes a **production-ready `GlobalExceptionHandler**` that automatically handles 10 common exceptions using Spring Boot's **ProblemDetail (RFC 9457)** standard.
 
 * **Automatic Logging:** SLF4J integration for all errors.
 * **Trace ID Consistency:** Logs and responses always have matching trace IDs.
@@ -370,15 +343,13 @@ public class ResourceNotFoundException extends ApiException {
     }
 }
 
-
 ```
 
 ## 🌍 Real-World Examples
 
-### Example 1: Clean CRUD Controller (Using @AutoResponse)
+### Example 1: Clean CRUD Controller (Using Class-Level @AutoResponse)
 
 ```java
-
 @RestController
 @RequestMapping("/api/products")
 @RequiredArgsConstructor
@@ -411,7 +382,6 @@ public class ProductController {
     }
 }
 
-
 ```
 
 ## 📚 API Reference
@@ -422,10 +392,11 @@ public class ProductController {
 
 ### 1.4.0 (February 2026) - Current Release
 
-✨ **New Features:**
+✨ **New Features & Improvements:**
 
 * **@AutoResponse Annotation & GlobalResponseWrapper**
 * Opt-in automatic response wrapping to eliminate boilerplate code.
+* **Improved Granularity:** Fully supports both Class-level (`ElementType.TYPE`) and Method-level (`ElementType.METHOD`) placement for precision control over which endpoints are wrapped.
 * Returns raw DTOs from controllers and automatically wraps them in `ApiResponse<T>`.
 * Preserves HTTP status codes from `@ResponseStatus`.
 * Intelligently skips `ResponseEntity`, `ApiResponse`, and `ProblemDetail` to prevent double-wrapping.
@@ -436,7 +407,10 @@ public class ProductController {
 * `@AutoTrim` and `@XssCheck` can now be applied at the Class level (`ElementType.TYPE`) to automatically protect all String fields within the DTO at once.
 
 
-* **package-info.java documentation** added for the new `advice` package.
+* **Documentation**
+* `package-info.java` documentation added for the new `advice` package.
+
+
 
 ### 1.3.0 (February 2026)
 
@@ -464,8 +438,7 @@ public class ProductController {
 
 ## 🤝 Contributing
 
-We welcome contributions! Please see the Contributing section above for details on our Apache 2.0 license terms and PR
-process.
+We welcome contributions! Please see the Contributing section above for details on our Apache 2.0 license terms and PR process.
 
 ## 📄 License
 
@@ -473,8 +446,7 @@ Licensed under the Apache License 2.0.
 
 ## 📧 Contact
 
-**Pasindu OG** | [pasinduogdev@gmail.com](mailto:pasinduogdev@gmail.com) |
-GitHub: [@pasinduog](https://github.com/pasinduog)
+**Pasindu OG** | [pasinduogdev@gmail.com](mailto:pasinduogdev@gmail.com) | GitHub: [@pasinduog](https://github.com/pasinduog)
 
 ---