docs(client): document per-verb *_with_response siblings

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lesnik512

architecture/client.md

@@ -12,6 +12,12 @@ The sync and async surfaces are kept at parity. Shared state is thread-safe wher
 
 The async middleware surface uses the `Async*`/`async_*` prefix, aligning with httpx2's convention.
 
+## `send_with_response` and per-verb siblings
+
+`send_with_response(request, *, response_model)` returns `(httpx2.Response, T)` atomically — the decoded body and the raw response together. This is the building block for cases where response metadata (headers, status) is needed alongside the typed body, such as Link-header pagination.
+
+The per-verb `*_with_response` siblings — `get_with_response`, `post_with_response`, `put_with_response`, `patch_with_response`, `delete_with_response`, and `request_with_response` — are the one-call ergonomic form: `response_model` is required, they return `tuple[httpx2.Response, T]`, and they accept the same keyword arguments as their non-`_with_response` counterparts; there is no `head_with_response` or `options_with_response` — use `request_with_response` for those methods.
+
 ## Streaming
 
 Both `Client.stream()` (sync) and `AsyncClient.stream()` (async) provide a context-manager API for chunked response bodies. Both bypass the middleware chain by design.

docs/recipes/link-header-pagination.md

@@ -30,10 +30,26 @@ async def main() -> None:
 
 `process` and `next_link` are caller-defined. Pick a Link-header parser that fits your project — there are several on PyPI, and the format is small enough to hand-roll.
 
+## Shorthand: per-verb `*_with_response`
+
+When you do not need a pre-built `Request` object, the per-verb siblings collapse the `build_request` + `send_with_response` two-step into a single call:
+
+```python
+# two-step (pre-built request, required when you need full Request control)
+request = client.build_request("GET", url, params=params)
+response, tags = await client.send_with_response(request, response_model=list[Tag])
+
+# one-call shorthand (equivalent for the simple case)
+response, tags = await client.get_with_response(url, params=params, response_model=list[Tag])
+```
+
+The full set of siblings is `get_with_response`, `post_with_response`, `put_with_response`, `patch_with_response`, `delete_with_response`, and `request_with_response`. There is no `head_with_response` or `options_with_response` — use `request_with_response` for those methods.
+
 ## When to use which API
 
 - **Body only, high-level verb:** `client.get(..., response_model=...)`
 - **Body only, custom `Request`:** `client.send(request, response_model=...)`
-- **Body + response metadata:** `client.send_with_response(request, response_model=...)`
+- **Body + response metadata, simple URL:** `client.get_with_response(url, response_model=...)`
+- **Body + response metadata, pre-built `Request`:** `client.send_with_response(request, response_model=...)`
 
-`send_with_response` is not for streaming responses — use [`stream()`](../index.md#streaming-responses) for those.
+`send_with_response` and the `*_with_response` siblings are not for streaming responses — use [`stream()`](../index.md#streaming-responses) for those.

tests/test_client_typing.py

@@ -1,9 +1,13 @@
 """Static-typing tests for AsyncClient and Client overloads.
 
-These assert overload selection at runtime via isinstance checks. ty/mypy
-catches the static-typing variant during `just lint`.
+Assertions come in two forms:
+- Runtime ``isinstance`` checks that verify the overload selected at call
+  time (send / send_with_response with and without response_model).
+- Static ``typing.assert_type`` calls that let ty/mypy verify the inferred
+  return type during ``just lint``.
 """
 
+import typing
 from http import HTTPStatus
 
 import httpx2
@@ -92,3 +96,32 @@ def test_sync_send_with_response_model_returns_typed() -> None:
     client = Client(httpx2_client=httpx2.Client(transport=transport))
     result = client.send(httpx2.Request("GET", "https://example.test/x"), response_model=_User)
     assert isinstance(result, _User)
+
+
+# ---------------------------------------------------------------------------
+# *_with_response static-type assertions — validates tuple[Response, T] destructuring
+# ---------------------------------------------------------------------------
+
+
+async def test_get_with_response_return_type() -> None:
+    transport = httpx2.MockTransport(
+        lambda req: httpx2.Response(HTTPStatus.OK, request=req, json={"id": 1, "name": "a"})
+    )
+    client = AsyncClient(httpx2_client=httpx2.AsyncClient(transport=transport))
+    response, user = await client.get_with_response("https://example.test/x", response_model=_User)
+    typing.assert_type(response, httpx2.Response)
+    typing.assert_type(user, _User)
+    assert isinstance(response, httpx2.Response)
+    assert isinstance(user, _User)
+
+
+def test_sync_get_with_response_return_type() -> None:
+    transport = httpx2.MockTransport(
+        lambda req: httpx2.Response(HTTPStatus.OK, request=req, json={"id": 1, "name": "a"})
+    )
+    client = Client(httpx2_client=httpx2.Client(transport=transport))
+    response, user = client.get_with_response("https://example.test/x", response_model=_User)
+    typing.assert_type(response, httpx2.Response)
+    typing.assert_type(user, _User)
+    assert isinstance(response, httpx2.Response)
+    assert isinstance(user, _User)