docs: update property access patterns and add file uploads notebook

- Update notebooks 02 and 03 to use recommended extension function pattern
  for property access (getTitleAsPlainText, getSelectPropertyName, etc.)
- Add comprehensive file uploads notebook (07-file-uploads.ipynb) with
  examples for uploading files, external imports, and media blocks
- Update docs/pages.md with all three property access patterns and
  recommendations
- Update docs/data-sources.md and docs/pagination.md to show extension
  functions
- Update README.md to reference new notebook 07 and increase example count
  to 55+

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

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

Author: Jonas Saabel

README.md

@@ -128,7 +128,7 @@ See [docs/databases.md](docs/databases.md) and [docs/data-sources.md](docs/data-
 | **Search** | ✅ Complete | [docs/search.md](docs/search.md) |
 | **Users** | ✅ Complete | [docs/users.md](docs/users.md) |
 | **Comments** | ✅ Complete | [docs/comments.md](docs/comments.md) |
-| **File Uploads** | ✅ Complete | Integrated with blocks/pages |
+| **File Uploads** | ✅ Complete | [docs/file-uploads.md](docs/file-uploads.md) |
 
 ### Feature Highlights
 
@@ -144,7 +144,7 @@ See [docs/databases.md](docs/databases.md) and [docs/data-sources.md](docs/data-
 ## Documentation
 
 - **[Quick Start Guide](QUICKSTART.md)** - Get up and running in 5 minutes
-- **[Kotlin Notebooks](notebooks/)** - Interactive Jupyter notebooks with 50+ examples (recommended for learning)
+- **[Kotlin Notebooks](notebooks/)** - Interactive Jupyter notebooks with 55+ examples (recommended for learning)
 - **[API Documentation](docs/)** - Detailed guides for each API category
 - **[Rich Text DSL](docs/rich-text-dsl.md)** - Working with formatted text
 - **[Error Handling](docs/error-handling.md)** - Understanding and handling errors
@@ -159,6 +159,7 @@ The **[Kotlin Notebooks](notebooks/)** are the best way to learn the library:
 4. [Working with Blocks](notebooks/04-working-with-blocks.ipynb) - All block types and operations
 5. [Rich Text DSL](notebooks/05-rich-text-dsl.ipynb) - Formatting, colors, links, dates, equations
 6. [Advanced Queries](notebooks/06-advanced-queries.ipynb) - Complex filtering, AND/OR logic, pagination
+7. [File Uploads](notebooks/07-file-uploads.ipynb) - Uploading files, external imports, media blocks
 
 All notebooks use live Notion API and can be run in IntelliJ IDEA or Jupyter.
 

docs/data-sources.md

@@ -271,13 +271,24 @@ val results = notion.dataSources.query("data-source-id") {
 
 ### Working with Properties
 
-After querying, access page properties:
+After querying, access page properties using extension functions (recommended):
 
 ```kotlin
 val pages = notion.dataSources.query("data-source-id") {}
 
 pages.forEach { page ->
-    // Access different property types
+    // Use extension functions for clean access
+    val title = page.getTitleAsPlainText("Task Name")
+    val status = page.getSelectPropertyName("Status")
+
+    println("$title - $status")
+}
+```
+
+Alternatively, use type-safe casting for more control:
+
+```kotlin
+pages.forEach { page ->
     val titleProp = page.properties["Task Name"] as? PageProperty.Title
     val title = titleProp?.plainText
 
@@ -288,6 +299,8 @@ pages.forEach { page ->
 }
 ```
 
+See [Pages API - Working with Properties](pages.md#working-with-page-properties) for all access patterns.
+
 ### Best Practices
 
 1. **Use filters** - Don't query all pages if you only need some

docs/pages.md

@@ -259,10 +259,45 @@ notion.pages.create {
 
 ### Accessing Properties from Retrieved Pages
 
+The library provides three patterns for accessing page properties:
+
+#### Pattern 1: Extension Functions
+
+The cleanest and most convenient approach - use extension functions for direct access to property values:
+
+```kotlin
+val page = notion.pages.retrieve("page-id")
+
+// Simple value access
+val title = page.getTitleAsPlainText("Name") ?: "Untitled"
+val status = page.getSelectPropertyName("Status") ?: "No status"
+val priority = page.getNumberProperty("Priority") ?: 0.0
+val dueDate = page.getDateProperty("Due Date")?.start
+val assignees = page.getPeopleProperty("Assignee")
+
+// Rich text access (preserves formatting)
+val descriptionRichText = page.getRichTextProperty("Description")
+val descriptionPlainText = page.getRichTextAsPlainText("Description")
+
+// Other convenience methods
+val checkboxValue = page.getCheckboxProperty("Is Complete")
+val url = page.getUrlProperty("Link")
+val email = page.getEmailProperty("Contact")
+val phoneNumber = page.getPhoneNumberProperty("Phone")
+val multiSelectNames = page.getMultiSelectPropertyNames("Tags")
+val relatedPages = page.getRelationProperty("Related Items")
+```
+
+**Use when:** You want clean, concise code and only need the property value (recommended for most cases).
+
+#### Pattern 2: Type-Safe Casting (Full Control)
+
+Cast to the specific property type for explicit control:
+
 ```kotlin
 val page = notion.pages.retrieve("page-id")
 
-// Type-safe property access
+// Access specific property types
 val titleProp = page.properties["Name"] as? PageProperty.Title
 val title = titleProp?.plainText ?: "Untitled"
 
@@ -279,6 +314,25 @@ val peopleProp = page.properties["Assignee"] as? PageProperty.People
 val assignees = peopleProp?.people ?: emptyList()
 ```
 
+**Use when:** You need full control over the property object or want to access multiple fields from the same property.
+
+#### Pattern 3: Generic Plain Text Extractor
+
+For cases where you just need a string representation of any property:
+
+```kotlin
+val page = notion.pages.retrieve("page-id")
+
+// Works with any property type
+val title = page.getPlainTextForProperty("Name")           // "My Page"
+val status = page.getPlainTextForProperty("Status")        // "In Progress"
+val priority = page.getPlainTextForProperty("Priority")    // "8.0"
+val tags = page.getPlainTextForProperty("Tags")            // "urgent, bug"
+val relations = page.getPlainTextForProperty("Related")    // "3 relation(s)"
+```
+
+**Use when:** Writing tests, debugging, or when you need a quick string representation without caring about the specific type.
+
 ### Property Type Reference
 
 Common property types you can set when creating/updating pages:

docs/pagination.md

@@ -240,13 +240,10 @@ notion.dataSources.queryAsFlow("data-source-id") {
 ### Early Termination
 
 ```kotlin
-// Stop after finding what you need
+// Stop after finding what you need (using extension functions)
 val targetPage = notion.dataSources.queryAsFlow("data-source-id") {}
     .firstOrNull { page ->
-        // Find first page matching condition
-        page.properties["Name"]?.let {
-            (it as? PageProperty.Title)?.plainText == "Target Page"
-        } ?: false
+        page.getTitleAsPlainText("Name") == "Target Page"
     }
 ```
 
@@ -257,14 +254,13 @@ val targetPage = notion.dataSources.queryAsFlow("data-source-id") {}
 notion.dataSources.queryAsFlow("data-source-id") {}
     .filter { page ->
         // Only process pages with status "Active"
-        val status = page.properties["Status"] as? PageProperty.Select
-        status?.select?.name == "Active"
+        page.getSelectPropertyName("Status") == "Active"
     }
     .map { page ->
         // Transform to simpler representation
         PageSummary(
             id = page.id,
-            name = (page.properties["Name"] as? PageProperty.Title)?.plainText ?: ""
+            name = page.getTitleAsPlainText("Name") ?: ""
         )
     }
     .take(10) // Limit to first 10 matching items