chore(release): bump version to 0.2.0

Update version from 0.1.0 to 0.2.0 across all project files including
documentation and Kotlin notebooks.

Changes:
- Update gradle.properties version to 0.2.0
- Update installation examples in README.md and QUICKSTART.md
- Add comprehensive CHANGELOG entry for 0.2.0 release
- Update all 7 Kotlin notebook dependencies
- Add lightweight documentation mentions for new features

New features in 0.2.0:
- Five new query filter types (relation, people, status, unique_id, files)
- Place property type support with convenience accessors
- Enhanced unique_id property with convenience accessors
- Graceful handling of unknown property types
- Updated dependencies to latest versions

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

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

Author: Jonas Saabel

CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-11-04
+
+### ✨ Added
+
+**Query Filters** - New property type filters for advanced querying:
+- **Relation filter**: Filter by related pages with `relation("Property").contains(pageId)`, `doesNotContain()`, `isEmpty()`, `isNotEmpty()`
+- **People filter**: Filter by users/assignees with `people("Property").contains(userId)`, `doesNotContain()`, `isEmpty()`, `isNotEmpty()`
+- **Status filter**: Filter by workflow status with `status("Property").equals("Status")`, `doesNotEqual()`, `isEmpty()`, `isNotEmpty()`
+- **Unique ID filter**: Filter by auto-incrementing IDs with numeric comparisons (`equals()`, `greaterThan()`, `lessThan()`, etc.)
+- **Files filter**: Filter by attachment presence with `files("Property").isEmpty()`, `isNotEmpty()`
+
+**Property Types**:
+- **Place property**: Full support for location data with `PageProperty.Place` including:
+  - Structured access to latitude/longitude coordinates
+  - Name and address fields
+  - Convenience accessors: `getPlaceProperty()`, `getPlaceAsString()`, `formattedLocation`
+- **Unique ID property**: Enhanced with convenience accessors (`getUniqueIdProperty()`, properly integrated with `getPlainTextForProperty()`)
+
+### 🐛 Fixed
+
+- **Unknown property types**: Library now gracefully handles property types it doesn't recognize, returning `PageProperty.Unsupported` instead of failing deserialization
+
+### 🔧 Changed
+
+- **Dependencies**: Updated to latest versions of Kotlin, Ktor, and other dependencies
+- **Gradle**: Updated Gradle wrapper to latest version
+
+### 📊 Statistics
+
+- **Test coverage**: 514+ unit tests (up from 481)
+- **New test suites**: Integration tests for all new filter types
+
 ## [0.1.0] - 2025-10-10
 
 ### 🎉 Initial Release
@@ -82,4 +114,5 @@ This is the first public release of the Kotlin Notion Client library.
 
 **Note**: This is an early release (0.1.0). While comprehensive testing has been performed, users should expect potential issues and are encouraged to report them via GitHub Issues.
 
+[0.2.0]: https://github.com/jsaabel/kotlin-notion-client/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/jsaabel/kotlin-notion-client/releases/tag/v0.1.0

QUICKSTART.md

@@ -15,7 +15,7 @@ Add the dependency to your `build.gradle.kts`:
 
 ```kotlin
 dependencies {
-    implementation("it.saabel:kotlin-notion-client:0.1.0")
+    implementation("it.saabel:kotlin-notion-client:0.2.0")
 }
 ```
 

README.md

@@ -25,7 +25,7 @@ A modern, type-safe Kotlin client for the Notion API with comprehensive DSL supp
 ```kotlin
 // Gradle (Kotlin DSL)
 dependencies {
-    implementation("it.saabel:kotlin-notion-client:0.1.0")
+    implementation("it.saabel:kotlin-notion-client:0.2.0")
 }
 ```
 
@@ -34,7 +34,7 @@ dependencies {
 <dependency>
     <groupId>it.saabel</groupId>
     <artifactId>kotlin-notion-client</artifactId>
-    <version>0.1.0</version>
+    <version>0.2.0</version>
 </dependency>
 ```
 

docs/data-sources.md

@@ -269,6 +269,8 @@ val results = notion.dataSources.query("data-source-id") {
 }
 ```
 
+**Additional Filter Types** (v0.2.0+): The query DSL also supports filters for `relation` (related pages), `people` (users/assignees), `status` (workflow status), `unique_id` (auto-incrementing IDs), and `files` (attachment presence). All follow the same DSL pattern as shown above.
+
 ### Working with Properties
 
 After querying, access page properties using extension functions (recommended):

docs/notebooks.md

@@ -43,7 +43,7 @@ Our integration tests provide excellent, verified examples:
 
 ```kotlin
 // Load dependencies
-@file:DependsOn("it.saabel:kotlin-notion-client:0.1.0")
+@file:DependsOn("it.saabel:kotlin-notion-client:0.2.0")
 
 // Imports
 import it.saabel.kotlinnotionclient.NotionClient

docs/pages.md

@@ -352,6 +352,8 @@ Common property types you can set when creating/updating pages:
 | Phone | `phoneNumber(name, phoneString)` | `phoneNumber("Phone", "+1-555-0123")` |
 | Files | `files(name, ...)` | (See file upload documentation) |
 | Relation | `relation(name, pageIds)` | `relation("Related", "page-1", "page-2")` |
+| Place (v0.2.0+) | Read location data | Access with `getPlaceProperty()` |
+| Unique ID | Read auto-incrementing ID | Access with `getUniqueIdProperty()` |
 
 **Read-only properties** (cannot be set via create/update):
 - Formula
@@ -360,6 +362,8 @@ Common property types you can set when creating/updating pages:
 - Last edited time
 - Created by
 - Last edited by
+- Place (read-only in API)
+- Unique ID (auto-generated)
 
 ## Common Patterns
 

gradle.properties

@@ -3,7 +3,7 @@ org.gradle.configuration-cache=false
 org.jetbrains.dokka.experimental.gradle.pluginMode=V2EnabledWithHelpers
 
 # Project version
-version=0.1.0
+version=0.2.0
 group=it.saabel
 
 # Maven Central Publishing (Vanniktech Maven Publish Plugin)

notebooks/01-getting-started.ipynb

@@ -35,35 +35,9 @@
      "start_time": "2025-10-16T21:01:48.197016Z"
     }
    },
-   "source": [
-    "// Load the Kotlin Notion Client library from Maven Central\n",
-    "@file:DependsOn(\"it.saabel:kotlin-notion-client:0.1.0\")\n",
-    "\n",
-    "// Import necessary classes\n",
-    "import it.saabel.kotlinnotionclient.NotionClient\n",
-    "import it.saabel.kotlinnotionclient.exceptions.NotionException\n",
-    "import kotlinx.coroutines.runBlocking\n",
-    "\n",
-    "// Initialize the client with your API token\n",
-    "val apiToken = System.getenv(\"NOTION_API_TOKEN\")\n",
-    "    ?: error(\"❌ NOTION_API_TOKEN environment variable not set\")\n",
-    "\n",
-    "val notion = NotionClient(apiToken)\n",
-    "\n",
-    "println(\"✅ NotionClient initialized successfully!\")\n",
-    "println(\"   Token: ${apiToken.take(10)}...\")"
-   ],
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "✅ NotionClient initialized successfully!\n",
-      "   Token: ntn_532171...\n"
-     ]
-    }
-   ],
-   "execution_count": 1
+   "source": "// Load the Kotlin Notion Client library from Maven Central\n@file:DependsOn(\"it.saabel:kotlin-notion-client:0.2.0\")\n\n// Import necessary classes\nimport it.saabel.kotlinnotionclient.NotionClient\nimport it.saabel.kotlinnotionclient.exceptions.NotionException\nimport kotlinx.coroutines.runBlocking\n\n// Initialize the client with your API token\nval apiToken = System.getenv(\"NOTION_API_TOKEN\")\n    ?: error(\"❌ NOTION_API_TOKEN environment variable not set\")\n\nval notion = NotionClient(apiToken)\n\nprintln(\"✅ NotionClient initialized successfully!\")\nprintln(\"   Token: ${apiToken.take(10)}...\")",
+   "outputs": [],
+   "execution_count": null
   },
   {
    "cell_type": "markdown",
@@ -381,4 +355,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}

notebooks/02-reading-databases.ipynb

@@ -20,17 +20,9 @@
      "start_time": "2025-10-23T08:11:40.748488Z"
     }
    },
-   "source": "// Load the Kotlin Notion Client library from Maven Central\n@file:DependsOn(\"it.saabel:kotlin-notion-client:0.1.0\")\n\n// Import necessary classes\nimport it.saabel.kotlinnotionclient.NotionClient\nimport it.saabel.kotlinnotionclient.models.base.SelectOptionColor\nimport it.saabel.kotlinnotionclient.models.datasources.SortDirection\nimport it.saabel.kotlinnotionclient.models.pages.PageProperty\nimport kotlinx.coroutines.runBlocking\nimport kotlinx.coroutines.async\nimport kotlinx.coroutines.awaitAll\n\n// Initialize the client\nval apiToken = System.getenv(\"NOTION_API_TOKEN\")\n    ?: error(\"❌ NOTION_API_TOKEN environment variable not set\")\n\nval parentPageId = System.getenv(\"NOTION_TEST_PAGE_ID\")\n    ?: error(\"❌ NOTION_TEST_PAGE_ID environment variable not set\")\n\nval notion = NotionClient(apiToken)\n\nprintln(\"✅ NotionClient initialized successfully!\")",
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "✅ NotionClient initialized successfully!\n"
-     ]
-    }
-   ],
-   "execution_count": 1
+   "source": "// Load the Kotlin Notion Client library from Maven Central\n@file:DependsOn(\"it.saabel:kotlin-notion-client:0.2.0\")\n\n// Import necessary classes\nimport it.saabel.kotlinnotionclient.NotionClient\nimport it.saabel.kotlinnotionclient.models.base.SelectOptionColor\nimport it.saabel.kotlinnotionclient.models.datasources.SortDirection\nimport it.saabel.kotlinnotionclient.models.pages.PageProperty\nimport kotlinx.coroutines.runBlocking\nimport kotlinx.coroutines.async\nimport kotlinx.coroutines.awaitAll\n\n// Initialize the client\nval apiToken = System.getenv(\"NOTION_API_TOKEN\")\n    ?: error(\"❌ NOTION_API_TOKEN environment variable not set\")\n\nval parentPageId = System.getenv(\"NOTION_TEST_PAGE_ID\")\n    ?: error(\"❌ NOTION_TEST_PAGE_ID environment variable not set\")\n\nval notion = NotionClient(apiToken)\n\nprintln(\"✅ NotionClient initialized successfully!\")",
+   "outputs": [],
+   "execution_count": null
   },
   {
    "cell_type": "markdown",
@@ -432,4 +424,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}

notebooks/03-creating-pages.ipynb

@@ -20,17 +20,9 @@
      "start_time": "2025-10-23T08:16:03.587615Z"
     }
    },
-   "source": "// Load the Kotlin Notion Client library from Maven Central\n@file:DependsOn(\"it.saabel:kotlin-notion-client:0.1.0\")\n\n// Import necessary classes\nimport it.saabel.kotlinnotionclient.NotionClient\nimport it.saabel.kotlinnotionclient.models.base.SelectOptionColor\nimport it.saabel.kotlinnotionclient.models.datasources.SortDirection\nimport it.saabel.kotlinnotionclient.models.pages.PageProperty\nimport kotlinx.coroutines.runBlocking\nimport kotlinx.coroutines.async\nimport kotlinx.coroutines.awaitAll\n\n// Initialize the client\nval apiToken = System.getenv(\"NOTION_API_TOKEN\")\n    ?: error(\"❌ NOTION_API_TOKEN environment variable not set\")\n\nval parentPageId = System.getenv(\"NOTION_TEST_PAGE_ID\")\n    ?: error(\"❌ NOTION_TEST_PAGE_ID environment variable not set\")\n\nval notion = NotionClient(apiToken)\n\nprintln(\"✅ NotionClient initialized successfully!\")",
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "✅ NotionClient initialized successfully!\n"
-     ]
-    }
-   ],
-   "execution_count": 1
+   "source": "// Load the Kotlin Notion Client library from Maven Central\n@file:DependsOn(\"it.saabel:kotlin-notion-client:0.2.0\")\n\n// Import necessary classes\nimport it.saabel.kotlinnotionclient.NotionClient\nimport it.saabel.kotlinnotionclient.models.base.SelectOptionColor\nimport it.saabel.kotlinnotionclient.models.datasources.SortDirection\nimport it.saabel.kotlinnotionclient.models.pages.PageProperty\nimport kotlinx.coroutines.runBlocking\nimport kotlinx.coroutines.async\nimport kotlinx.coroutines.awaitAll\n\n// Initialize the client\nval apiToken = System.getenv(\"NOTION_API_TOKEN\")\n    ?: error(\"❌ NOTION_API_TOKEN environment variable not set\")\n\nval parentPageId = System.getenv(\"NOTION_TEST_PAGE_ID\")\n    ?: error(\"❌ NOTION_TEST_PAGE_ID environment variable not set\")\n\nval notion = NotionClient(apiToken)\n\nprintln(\"✅ NotionClient initialized successfully!\")",
+   "outputs": [],
+   "execution_count": null
   },
   {
    "cell_type": "markdown",
@@ -410,4 +402,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}