docs: address final-review polish for pagination unification

Author: OmarAlJarrah

docs/implementation-plan.md

@@ -372,6 +372,8 @@ defaults (per Square: `FAIL_ON_UNKNOWN_PROPERTIES=false`, `WRITE_DATES_AS_TIMEST
 
 ### WU-9: Pagination primitives
 
+> Superseded by #30 (pagination unification): `Page` is now an immutable value type, strategies return `PageInfo` (`nextRequest == null` = end of stream), and `SimplePage` was removed.
+
 **Status: shipped.** `Page`, `Paginator`, `PaginationStrategy`, and the three strategies
 (`Cursor` / `PageNumber` / `LinkHeader`) are in `sdk-core/.../pagination`, alongside
 helper types `SimplePage` and `RequestRebuilder`. `Paginator` gained a `maxPages` safety cap

sdk-core/src/main/kotlin/org/dexpace/sdk/core/pagination/AsyncPaginator.kt

@@ -371,8 +371,9 @@ public class AsyncPaginator<T>
             }
 
             /**
-             * Emits a page's items to the consumer, then schedules the next request. Returns
-             * `true` to continue driving, `false` if the consumer threw (walk aborted).
+             * Delivers a parsed page to the page sink (which may emit the page's items or the
+             * whole page), then schedules the next request read from the [ParsedPage]. Returns
+             * `true` to continue driving, `false` if the sink threw (walk aborted).
              */
             private fun drainPage(page: ParsedPage<T>): Boolean {
                 try {
@@ -386,9 +387,10 @@ public class AsyncPaginator<T>
             }
 
             /**
-             * Executes [request], parses the response into a [Page], and closes the response —
-             * mirroring [Paginator]'s per-page lifecycle. The returned future completes with the
-             * parsed page or exceptionally if the transport or strategy fails.
+             * Executes [request], parses the response into a [PageInfo], snapshots a [Page], and
+             * closes the response — mirroring [Paginator]'s per-page lifecycle. The returned future
+             * completes with the resulting [ParsedPage] or exceptionally if the transport or
+             * strategy fails.
              */
             private fun fetchPage(request: Request): CompletableFuture<ParsedPage<T>> {
                 pagesFetched++

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

@@ -14,8 +14,6 @@ import org.dexpace.sdk.core.http.request.Request
 import org.dexpace.sdk.core.http.response.Response
 import org.dexpace.sdk.core.http.response.ResponseBody
 import org.dexpace.sdk.core.http.response.Status
-import org.dexpace.sdk.core.io.Io
-import org.dexpace.sdk.io.OkioIoProvider
 import java.io.IOException
 import java.net.URL
 import java.util.concurrent.atomic.AtomicInteger
@@ -28,7 +26,7 @@ import kotlin.test.assertSame
 import kotlin.test.assertTrue
 
 class PagedIterableTest {
-    @BeforeTest fun setup() = Io.installProvider(OkioIoProvider)
+    @BeforeTest fun setup() = installIoProvider()
 
     private fun request(): Request =
         Request.builder().url(URL("https://api.example.com/items")).method(Method.GET).build()
@@ -169,6 +167,44 @@ class PagedIterableTest {
         assertEquals(0, nextPageCalls.get(), "nextPage must not be called for an empty continuationToken")
     }
 
+    // -------------------------------------------------------------------------
+    // Behavior 2b: continuationToken drives the next fetch when nextLink is null
+    // -------------------------------------------------------------------------
+
+    @Test
+    fun `continuationToken is used when nextLink is null and the next page is followed`() {
+        val observedToken = arrayOfNulls<String>(1)
+        val iterable =
+            PagedIterable<Int>(
+                firstPage = { page(listOf(1), nextLink = null, continuationToken = "tok") },
+                nextPage = { _, token ->
+                    observedToken[0] = token
+                    page(listOf(2))
+                },
+            )
+        assertEquals(listOf(1, 2), iterable.toList())
+        assertEquals("tok", observedToken[0], "continuationToken must drive nextPage when nextLink is null")
+    }
+
+    // -------------------------------------------------------------------------
+    // Behavior 2c: a null return from nextPage terminates iteration
+    // -------------------------------------------------------------------------
+
+    @Test
+    fun `null return from nextPage terminates iteration after first page`() {
+        val nextPageCalls = AtomicInteger(0)
+        val iterable =
+            PagedIterable<Int>(
+                firstPage = { page(listOf(1, 2), nextLink = "p2") },
+                nextPage = { _, _ ->
+                    nextPageCalls.incrementAndGet()
+                    null
+                },
+            )
+        assertEquals(listOf(1, 2), iterable.toList())
+        assertEquals(1, nextPageCalls.get(), "nextPage must be called exactly once before its null ends the stream")
+    }
+
     // -------------------------------------------------------------------------
     // Behavior 3: null first-page return yields nothing
     // -------------------------------------------------------------------------