test: split custom param-name pagination assertion into its own test

The URL-encoding test also asserted the custom page_token query-param
path, so a single case guarded two independent properties. Split the
param-name assertion into a dedicated test and narrow the encoding test
to the default cursor param. Move the token-style guidance out of the
package-map table cells into surrounding prose in the README and
architecture docs.

Author: OmarAlJarrah

README.md

@@ -255,7 +255,7 @@ See [docs/pipelines.md](docs/pipelines.md) for the step-author walkthrough.
 | `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>` / `SimplePage<T>`. |
 | `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 and `Tristate<T>` (absent / null / present). |
 | `io` | `Source`, `Sink`, `Buffer`, `BufferedSource`, `BufferedSink`, `IoProvider`, `Io`, `TeeSink`. |
@@ -265,6 +265,9 @@ See [docs/pipelines.md](docs/pipelines.md) for the step-author walkthrough.
 | `util` | `Clock`, `Uuids` (non-blocking v4), `DateTimeRfc1123`, `RetryUtils`, `ProxyOptions`, `Futures`. |
 | `generics` | `Builder<T>` — the generic builder interface every SDK builder implements. |
 
+Token-style APIs (`next_page_token`, `pageToken`, …) are served by `CursorPaginationStrategy`:
+construct it with the desired query-param name, e.g. `CursorPaginationStrategy(items, extractor, "page_token")`.
+
 ## Building
 
 ```bash

docs/architecture.md

@@ -346,9 +346,12 @@ Two complementary surfaces for walking multi-page responses.
 |-----------------------------------------------------------------|-----------------------------------------------------------------------|
 | `Paginator<T>`                                                  | Lazily iterates pages by re-issuing requests through an `HttpClient`; carries a `maxPages` safety cap |
 | `PaginationStrategy<T>`                                         | Computes the next-page request (or stops) from the current page       |
-| `CursorPaginationStrategy` / `PageNumberPaginationStrategy` / `LinkHeaderPaginationStrategy` | The shipped strategies. Token-style APIs use `CursorPaginationStrategy` with the query-param name set (e.g. `"page_token"`). |
+| `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.
+
 ### Serialization
 
 **Package**: `org.dexpace.sdk.core.serde`

sdk-core/src/test/kotlin/org/dexpace/sdk/core/pagination/CursorPaginationTest.kt

@@ -149,15 +149,39 @@ class CursorPaginationTest {
     @Test
     fun `cursor with special characters is URL encoded in next request`() {
         // Opaque cursors may contain `=` `+` `/` characters (base64) — the rebuilder must
-        // URL-encode them so the server sees the original value unmangled. A custom query
-        // param name (e.g. `page_token`) covers token-style APIs that reuse this strategy.
+        // URL-encode them so the server sees the original value unmangled.
         val rawCursor = "a+b/c="
         val encoded = "a%2Bb%2Fc%3D"
         val client = StubHttpClient()
         client.on("https://api.example.com/items") { req ->
             textResponse(req, "items=one\ncursor=$rawCursor")
         }
-        client.on("https://api.example.com/items?page_token=$encoded") { req ->
+        client.on("https://api.example.com/items?cursor=$encoded") { req ->
+            textResponse(req, "items=two\ncursor=")
+        }
+
+        val (items, cursor) = buildCachedExtractors()
+        val strategy = CursorPaginationStrategy(items, cursor)
+        val paginator = Paginator(client, initialRequest(), strategy)
+        assertEquals(listOf("one", "two"), paginator.iterateAll().toList())
+        assertEquals(
+            listOf(
+                "https://api.example.com/items",
+                "https://api.example.com/items?cursor=$encoded",
+            ),
+            client.receivedUrls,
+        )
+    }
+
+    @Test
+    fun `custom query-param name is used for the next-page cursor`() {
+        // Token-style APIs (next_page_token, pageToken, …) are served by setting
+        // cursorQueryParam; the next request must carry the cursor under that name.
+        val client = StubHttpClient()
+        client.on("https://api.example.com/items") { req ->
+            textResponse(req, "items=one\ncursor=tok1")
+        }
+        client.on("https://api.example.com/items?page_token=tok1") { req ->
             textResponse(req, "items=two\ncursor=")
         }
 
@@ -168,7 +192,7 @@ class CursorPaginationTest {
         assertEquals(
             listOf(
                 "https://api.example.com/items",
-                "https://api.example.com/items?page_token=$encoded",
+                "https://api.example.com/items?page_token=tok1",
             ),
             client.receivedUrls,
         )