refactor: unify pagination onto a single Page-based surface

README.md

@@ -271,8 +271,7 @@ See [docs/pipelines.md](docs/pipelines.md) for the step-author walkthrough.
 | `http.pipeline.steps` | Concrete steps: `RetryStep`, `RedirectStep`, `AuthStep`, `KeyCredentialAuthStep`, `BearerTokenAuthStep`, `InstrumentationStep`, `SetDateStep`, and their `*Options` / `*Condition` types. |
 | `http.auth` | `Credential` sealed hierarchy (`KeyCredential`, `NamedKeyCredential`, `BearerToken`), `BearerTokenProvider`, `AuthScheme`, `AuthMetadata`, RFC 7235 challenge parser, `BasicChallengeHandler`, `DigestChallengeHandler`, `CompositeChallengeHandler`. |
 | `http.sse` | `ServerSentEventReader` (WHATWG spec), `ServerSentEvent`, `ServerSentEventListener`, `BufferedSource.readServerSentEvents()`. |
-| `http.paging` | `PagedIterable<T>`, `PagedResponse<T>`, `PagingOptions` with `byPage()` and `stream()` accessors. |
-| `pagination` | `Paginator<T>` (with a `maxPages` safety cap) over cursor / page-number / link-header `PaginationStrategy` implementations, plus `Page<T>` / `SimplePage<T>`. Token-style APIs use `CursorPaginationStrategy` with the query-param name set (e.g. `"page_token"`). |
+| `pagination` | `Paginator<T>` (with a `maxPages` safety cap) over cursor / page-number / link-header `PaginationStrategy` implementations, plus `Page<T>` — each page carries its items and optional response metadata (`statusCode`, `headers`) and HATEOAS links / continuation token (`nextLink`, `previousLink`, `firstLink`, `lastLink`, `continuationToken`). `iterateAll()` flattens items, `streamAll()` exposes a Java 8 `Stream<T>`, and the paginator closes each response after the strategy parses it. Token-style APIs use `CursorPaginationStrategy` with the query-param name set (e.g. `"page_token"`). |
 | `pipeline` | Recovery-aware primitives: `RequestPipeline`, `ResponsePipeline`, `ExecutionPipeline` over a sealed `ResponseOutcome`, with steps (`pipeline.step`, `pipeline.step.retry`) like `RetryStep`, `ResponseRecoveryStep`, `IdempotencyKeyStep`, `ClientIdentityStep`. |
 | `serde` | `Serde`, `Serializer`, `Deserializer` abstractions, `Tristate<T>` (absent / null / present), and `SerdeException` (the unchecked failure adapters translate codec errors into). |
 | `io` | `Source`, `Sink`, `Buffer`, `BufferedSource`, `BufferedSink`, `IoProvider`, `Io`, `TeeSink`. |

docs/architecture.md

@@ -79,7 +79,6 @@ java-sdk/
         http/common/                  Headers, MediaType, Protocol, CommonMediaTypes, ETag, HttpRange, conditions
         http/auth/                    Credentials, RFC 7235 challenge parsing, Basic/Digest/Composite handlers
         http/context/                 Call/dispatch/request/exchange contexts + ContextStore
-        http/paging/                  PagedIterable, PagedResponse, PagingOptions
         http/pipeline/                Stage-based sync/async pipeline runtime (+ .steps)
         http/sse/                     WHATWG Server-Sent Events reader/listener/events
         pipeline/                     Recovery-aware Request/Response/Execution pipeline primitives (+ .step, .step.retry)
@@ -343,16 +342,16 @@ for usage examples.
 
 ### Pagination
 
-**Packages**: `org.dexpace.sdk.core.pagination`, `org.dexpace.sdk.core.http.paging`
+**Package**: `org.dexpace.sdk.core.pagination`
 
-Two complementary surfaces for walking multi-page responses.
+A single surface for walking multi-page responses.
 
 | Type                                                            | Role                                                                  |
 |-----------------------------------------------------------------|-----------------------------------------------------------------------|
-| `Paginator<T>`                                                  | Lazily iterates pages by re-issuing requests through an `HttpClient`; carries a `maxPages` safety cap |
+| `Paginator<T>`                                                  | Lazily iterates pages by re-issuing requests through an `HttpClient`; carries a `maxPages` safety cap; closes each response after the strategy parses it |
 | `PaginationStrategy<T>`                                         | Computes the next-page request (or stops) from the current page       |
+| `Page<T>`                                                       | One parsed page: items plus optional response metadata (`statusCode`, `headers`) and HATEOAS links / continuation token (`nextLink`, `previousLink`, `firstLink`, `lastLink`, `continuationToken`) |
 | `CursorPaginationStrategy` / `PageNumberPaginationStrategy` / `LinkHeaderPaginationStrategy` | The shipped strategies |
-| `PagedIterable<T>`                                              | First/next-page fetcher abstraction over `PagedResponse`, with its own `maxPages` cap |
 
 Token-style APIs (`next_page_token`, `pageToken`, …) are handled by `CursorPaginationStrategy`
 constructed with the query-param name set (e.g. `"page_token"`), so no separate token strategy is needed.
@@ -718,7 +717,6 @@ they should construct a fresh one.
 | `http.common`        | Headers, MediaType, CommonMediaTypes, Protocol, ETag, HttpRange, RequestConditions             |
 | `http.auth`          | Credential, KeyCredential, BearerToken, ChallengeHandler, Basic/Digest/CompositeChallengeHandler, AuthChallengeParser |
 | `http.context`       | CallContext, DispatchContext, RequestContext, ExchangeContext, ContextStore                     |
-| `http.paging`        | PagedIterable, PagedResponse, PagingOptions                                                      |
 | `http.pipeline`      | HttpPipeline, HttpPipelineBuilder, HttpStep, Stage, AsyncHttpPipeline (+ `.steps`)              |
 | `http.sse`           | ServerSentEvent, ServerSentEventReader, ServerSentEventListener                                 |
 | `pipeline`           | RequestPipeline, ResponsePipeline, ExecutionPipeline, ResponseOutcome                           |

docs/refs-comparison.md

@@ -230,8 +230,8 @@ below records where each scheme's design was sourced from:
 ### Pagination
 
 `Paginator<T>` + `Page<T>` ship in `sdk-core`, driven by a `PaginationStrategy` (cursor,
-page-number, token, link-header), and `http.paging.PagedIterable` wraps the result. Reference
-designs we drew on:
+page-number, token, link-header). `Page<T>` carries the items plus the response envelope
+(`statusCode`, `headers`) and HATEOAS links / continuation token. Reference designs we drew on:
 
 - **Square**: `SyncPagingIterable<T>` (`Iterable<T>` lazy iterator), `SyncPage<T>` (per-page holder), `BiDirectionalPage<T>` (forward + backward cursors), `CustomPager<T>` (user-implementation stub for HATEOAS).
 - **gax**: `PagedListResponse<RequestT, ResponseT, ResourceT>` driven by `PagedListDescriptor` (`injectToken`, `extractNextToken`, `extractResources`). `iterateAll()` returns lazy `Iterable<ResourceT>`. `FixedSizeCollection` repaginates to consumer-chosen page sizes.
@@ -333,7 +333,7 @@ adapters where noted):
 - **Idempotency-key step.** Auto-injects `Idempotency-Key: UUID.randomUUID()` for `POST`/`PUT`/`PATCH`; caller-set header wins; pluggable key strategy. [`pipeline/step/IdempotencyKeyStep.kt`]
 - **Auth.** `Credential` family + RFC 7235 challenge parsing + Basic/Digest/Composite `ChallengeHandler`s + `AuthStep` pillar. [`http/auth/`, `http/pipeline/steps/`]
 - **`sdk-serde-jackson` adapter.** Kotlin + JSR-310 + Jdk8 modules; `FAIL_ON_UNKNOWN_PROPERTIES` and `WRITE_DATES_AS_TIMESTAMPS` disabled; `Tristate<T>` via `TristateModule`.
-- **Pagination primitives.** `Paginator<T>` + `Page<T>` + `PaginationStrategy` (cursor / page-number / token / link-header) with a `maxPages` cap; `PagedIterable` wrapper.
+- **Pagination primitives.** `Paginator<T>` + `Page<T>` + `PaginationStrategy` (cursor / page-number / token / link-header) with a `maxPages` cap; `Page<T>` exposes per-page status / headers / HATEOAS links.
 - **Client identity header.** `ClientIdentityStep` building the `dexpace-sdk/<ver> jvm/<javaver>` token line.
 - **Tracer event vocabulary + metrics seam.** `HttpTracer` with named retry/request/response events; `Meter`/`LongCounter`/`DoubleHistogram` separate from tracing.
 - **SSE streaming.** WHATWG reader in `sdk-core`; backpressured `Flux<ServerSentEvent>` in `sdk-async-reactor`.

sdk-core/api/sdk-core.api

@@ -577,64 +577,6 @@ public final class org/dexpace/sdk/core/http/context/RequestContext : org/dexpac
 	public fun toString ()Ljava/lang/String;
 }
 
-public abstract interface class org/dexpace/sdk/core/http/paging/FirstPageFetcher {
-	public abstract fun fetch (Lorg/dexpace/sdk/core/http/paging/PagingOptions;)Lorg/dexpace/sdk/core/http/paging/PagedResponse;
-}
-
-public abstract interface class org/dexpace/sdk/core/http/paging/NextPageFetcher {
-	public abstract fun fetch (Lorg/dexpace/sdk/core/http/paging/PagingOptions;Ljava/lang/String;)Lorg/dexpace/sdk/core/http/paging/PagedResponse;
-}
-
-public final class org/dexpace/sdk/core/http/paging/PagedIterable : java/lang/Iterable, kotlin/jvm/internal/markers/KMappedMarker {
-	public fun <init> (Lorg/dexpace/sdk/core/http/paging/FirstPageFetcher;)V
-	public fun <init> (Lorg/dexpace/sdk/core/http/paging/FirstPageFetcher;Lorg/dexpace/sdk/core/http/paging/NextPageFetcher;)V
-	public fun <init> (Lorg/dexpace/sdk/core/http/paging/FirstPageFetcher;Lorg/dexpace/sdk/core/http/paging/NextPageFetcher;J)V
-	public synthetic fun <init> (Lorg/dexpace/sdk/core/http/paging/FirstPageFetcher;Lorg/dexpace/sdk/core/http/paging/NextPageFetcher;JILkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public final fun byPage ()Lkotlin/sequences/Sequence;
-	public final fun byPage (Lorg/dexpace/sdk/core/http/paging/PagingOptions;)Lkotlin/sequences/Sequence;
-	public static synthetic fun byPage$default (Lorg/dexpace/sdk/core/http/paging/PagedIterable;Lorg/dexpace/sdk/core/http/paging/PagingOptions;ILjava/lang/Object;)Lkotlin/sequences/Sequence;
-	public fun iterator ()Ljava/util/Iterator;
-	public final fun stream ()Ljava/util/stream/Stream;
-}
-
-public final class org/dexpace/sdk/core/http/paging/PagedResponse : java/io/Closeable {
-	public fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Ljava/util/List;)V
-	public fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Ljava/util/List;Ljava/lang/String;)V
-	public fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Ljava/util/List;Ljava/lang/String;Ljava/lang/String;)V
-	public fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Ljava/util/List;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
-	public fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Ljava/util/List;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
-	public fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Ljava/util/List;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
-	public synthetic fun <init> (Lorg/dexpace/sdk/core/http/response/Response;Ljava/util/List;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public fun close ()V
-	public final fun getContinuationToken ()Ljava/lang/String;
-	public final fun getFirstLink ()Ljava/lang/String;
-	public final fun getHeaders ()Lorg/dexpace/sdk/core/http/common/Headers;
-	public final fun getLastLink ()Ljava/lang/String;
-	public final fun getNextLink ()Ljava/lang/String;
-	public final fun getPreviousLink ()Ljava/lang/String;
-	public final fun getRequest ()Lorg/dexpace/sdk/core/http/request/Request;
-	public final fun getResponse ()Lorg/dexpace/sdk/core/http/response/Response;
-	public final fun getStatusCode ()I
-	public final fun getValue ()Ljava/util/List;
-}
-
-public final class org/dexpace/sdk/core/http/paging/PagingOptions {
-	public fun <init> ()V
-	public fun <init> (Ljava/lang/Long;)V
-	public fun <init> (Ljava/lang/Long;Ljava/lang/Long;)V
-	public fun <init> (Ljava/lang/Long;Ljava/lang/Long;Ljava/lang/Long;)V
-	public fun <init> (Ljava/lang/Long;Ljava/lang/Long;Ljava/lang/Long;Ljava/lang/String;)V
-	public synthetic fun <init> (Ljava/lang/Long;Ljava/lang/Long;Ljava/lang/Long;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public final fun getContinuationToken ()Ljava/lang/String;
-	public final fun getOffset ()Ljava/lang/Long;
-	public final fun getPageIndex ()Ljava/lang/Long;
-	public final fun getPageSize ()Ljava/lang/Long;
-	public final fun setContinuationToken (Ljava/lang/String;)V
-	public final fun setOffset (Ljava/lang/Long;)V
-	public final fun setPageIndex (Ljava/lang/Long;)V
-	public final fun setPageSize (Ljava/lang/Long;)V
-}
-
 public final class org/dexpace/sdk/core/http/pipeline/AsyncHttpPipeline {
 	public static final field Companion Lorg/dexpace/sdk/core/http/pipeline/AsyncHttpPipeline$Companion;
 	public final fun getHttpClient ()Lorg/dexpace/sdk/core/client/AsyncHttpClient;
@@ -2005,11 +1947,28 @@ public final class org/dexpace/sdk/core/pagination/LinkHeaderPaginationStrategy
 }
 
 public abstract interface class org/dexpace/sdk/core/pagination/Page {
+	public fun getContinuationToken ()Ljava/lang/String;
+	public fun getFirstLink ()Ljava/lang/String;
 	public abstract fun getHasNext ()Z
+	public fun getHeaders ()Lorg/dexpace/sdk/core/http/common/Headers;
 	public abstract fun getItems ()Ljava/util/List;
+	public fun getLastLink ()Ljava/lang/String;
+	public fun getNextLink ()Ljava/lang/String;
+	public fun getPreviousLink ()Ljava/lang/String;
+	public fun getStatusCode ()Ljava/lang/Integer;
 	public abstract fun nextPageRequest ()Lorg/dexpace/sdk/core/http/request/Request;
 }
 
+public final class org/dexpace/sdk/core/pagination/Page$DefaultImpls {
+	public static fun getContinuationToken (Lorg/dexpace/sdk/core/pagination/Page;)Ljava/lang/String;
+	public static fun getFirstLink (Lorg/dexpace/sdk/core/pagination/Page;)Ljava/lang/String;
+	public static fun getHeaders (Lorg/dexpace/sdk/core/pagination/Page;)Lorg/dexpace/sdk/core/http/common/Headers;
+	public static fun getLastLink (Lorg/dexpace/sdk/core/pagination/Page;)Ljava/lang/String;
+	public static fun getNextLink (Lorg/dexpace/sdk/core/pagination/Page;)Ljava/lang/String;
+	public static fun getPreviousLink (Lorg/dexpace/sdk/core/pagination/Page;)Ljava/lang/String;
+	public static fun getStatusCode (Lorg/dexpace/sdk/core/pagination/Page;)Ljava/lang/Integer;
+}
+
 public final class org/dexpace/sdk/core/pagination/PageNumberPaginationStrategy : org/dexpace/sdk/core/pagination/PaginationStrategy {
 	public fun <init> (Lkotlin/jvm/functions/Function1;)V
 	public fun <init> (Lkotlin/jvm/functions/Function1;Ljava/lang/String;)V