From 868670ad57329deb210ca110cd3f7ed898404311 Mon Sep 17 00:00:00 2001
From: Thomas Cederholm <thomas.cederholm@extendaretail.com>
Date: Fri, 26 Jun 2026 15:45:02 +0200
Subject: [PATCH] feat: Add Response.withLocation convenience method

Add a withLocation(String) mutator that sets the Location header
without the caller naming the key, mirroring the existing
withHeader/withStatus/withContentType pattern. Update the created(...)
javadoc to point at the new method.
---
 src/main/java/com/retailsvc/http/Response.java     | 7 ++++++-
 src/test/java/com/retailsvc/http/ResponseTest.java | 8 ++++++++
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/src/main/java/com/retailsvc/http/Response.java b/src/main/java/com/retailsvc/http/Response.java
index f3e35b3d..09ea6221 100644
--- a/src/main/java/com/retailsvc/http/Response.java
+++ b/src/main/java/com/retailsvc/http/Response.java
@@ -57,7 +57,7 @@ public static Response ok(Object body) {
 
   /**
    * {@code 201 Created} with {@code body} serialised as JSON. Add a {@code Location} header for the
-   * new resource via {@link #withHeader(String, String) withHeader("Location", uri)}.
+   * new resource via {@link #withLocation(String)}.
    */
   public static Response created(Object body) {
     return new Response(HTTP_CREATED, body, null, Map.of());
@@ -140,6 +140,11 @@ public Response withHeader(String name, String value) {
     return new Response(status, body, contentType, merged);
   }
 
+  /** Sets the {@code Location} header, typically the URI of a newly {@link #created} resource. */
+  public Response withLocation(String location) {
+    return withHeader("Location", location);
+  }
+
   public Response withHeaders(Map<String, String> additional) {
     LinkedHashMap<String, String> merged = new LinkedHashMap<>(headers);
     merged.putAll(additional);
diff --git a/src/test/java/com/retailsvc/http/ResponseTest.java b/src/test/java/com/retailsvc/http/ResponseTest.java
index 162c00f2..d8fd5bd3 100644
--- a/src/test/java/com/retailsvc/http/ResponseTest.java
+++ b/src/test/java/com/retailsvc/http/ResponseTest.java
@@ -47,6 +47,14 @@ void createdWithLocationViaWithHeader() {
     assertThat(r.headers()).containsEntry("Location", "/things/x-1");
   }
 
+  @Test
+  void createdWithLocationViaWithLocation() {
+    Response r = Response.created(Map.of("id", "x-1")).withLocation("/things/x-1");
+
+    assertThat(r.status()).isEqualTo(HTTP_CREATED);
+    assertThat(r.headers()).containsEntry("Location", "/things/x-1");
+  }
+
   @Test
   void notFoundNoBody() {
     Response r = Response.notFound();