feat: add comprehensive pagination helpers with Flow support

Implement Flow-based pagination utilities for all paginated API endpoints:
- Add generic PaginatedResponse interface for type-safe pagination
- Implement three pagination methods: asFlow(), collectAll(), asPagesFlow()
- Add Flow helpers to all 6 APIs (DataSources, Blocks, Comments, Users, Search, Pages)
- Create comprehensive pagination documentation guide
- Add unit tests (9 tests) and integration tests (5 tests)

Benefits:
- Memory-efficient processing of large result sets
- Reactive processing patterns with Kotlin Flow
- Reduces boilerplate for manual pagination loops
- Type-safe cursor handling

Breaking changes: None - additive only

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Jonas Saabel

docs/README.md

@@ -16,6 +16,7 @@
 - **[Comments](comments.md)** - Add and retrieve comments
 
 ### Features
+- **[Pagination](pagination.md)** - Handle paginated results efficiently
 - **[Rich Text DSL](rich-text-dsl.md)** - Format text with mentions, links, and more
 - **[File Uploads](file-uploads.md)** - Upload and manage files and images
 - **[Error Handling](error-handling.md)** - Handle API errors gracefully

docs/blocks.md

@@ -368,14 +368,50 @@ notion.blocks.appendChildren(pageId) {
 
 ### Pagination Handling
 
-`retrieveChildren()` automatically handles pagination:
+Retrieving block children supports multiple pagination approaches:
+
+#### 1. Automatic Collection (Simple)
+
+`retrieveChildren()` automatically fetches all children:
 
 ```kotlin
 // Retrieves ALL children, handling pagination internally
 val allBlocks = notion.blocks.retrieveChildren(pageId)
 println("Total blocks: ${allBlocks.size}")
 ```
 
+**Use when**: You need all children and the count is reasonable (< 1000 blocks).
+
+#### 2. Flow-Based Streaming
+
+For pages with many blocks, use Flow for efficient processing:
+
+```kotlin
+// Memory-efficient - processes blocks as they're fetched
+notion.blocks.retrieveChildrenAsFlow(pageId).collect { block ->
+    println("Processing ${block.type}: ${block.id}")
+    // Process each block individually
+}
+```
+
+**Use when**: Working with pages that have many blocks (1000+) or memory efficiency matters.
+
+#### 3. Page-Level Flow
+
+Access pagination metadata while processing:
+
+```kotlin
+// Get complete responses with pagination info
+notion.blocks.retrieveChildrenPagedFlow(pageId).collect { response ->
+    println("Fetched ${response.results.size} blocks (has more: ${response.hasMore})")
+    response.results.forEach { block ->
+        // Process blocks in this batch
+    }
+}
+```
+
+See **[Pagination](pagination.md)** for comprehensive guide and best practices.
+
 ### Error Handling
 
 Handle common block API errors:

docs/data-sources.md

@@ -194,7 +194,11 @@ val existingDb = notion.databases.retrieve("database-id")
 val dataSourceId = existingDb.dataSources?.firstOrNull()?.id
 ```
 
-### Automatic Pagination
+### Working with Pagination
+
+Data source queries can return large result sets. The library provides three ways to handle pagination:
+
+#### 1. Automatic Collection (Simple)
 
 The `query()` method automatically fetches all matching pages:
 
@@ -209,7 +213,45 @@ val allPages = notion.dataSources.query("data-source-id") {
 println("Total matching pages: ${allPages.size}")
 ```
 
-The library handles pagination transparently, fetching up to 100,000 records (1,000 pages × 100 records/page safety limit).
+**Use when**: Result sets are reasonably sized (< 1000 items) and you need all results.
+
+#### 2. Flow-Based Streaming (Recommended for Large Sets)
+
+For large result sets, use Flow to process items as they arrive:
+
+```kotlin
+// Memory-efficient - processes pages as they're fetched
+notion.dataSources.queryAsFlow("data-source-id") {
+    filter {
+        select("Status").equals("To Do")
+    }
+}.collect { page ->
+    println("Processing: ${page.id}")
+    // Process each page individually
+}
+```
+
+**Use when**: Working with 1000+ items or when memory efficiency matters.
+
+#### 3. Page-Level Flow (Batch Processing)
+
+Access pagination metadata while processing:
+
+```kotlin
+// Get complete responses with pagination info
+notion.dataSources.queryPagedFlow("data-source-id") {
+    filter { /* ... */ }
+}.collect { response ->
+    println("Fetched ${response.results.size} pages (has more: ${response.hasMore})")
+    response.results.forEach { page ->
+        // Process pages in this batch
+    }
+}
+```
+
+**Use when**: You need pagination metadata or want to process pages in batches.
+
+See **[Pagination](pagination.md)** for comprehensive guide and best practices.
 
 ### Complex Filters