# Changelog for notion-client
## 0.7.0.2 (2026-06-27)
### Bug Fixes
* Relation property schemas with `single_property` now serialize the required empty `single_property` object, so creating one-directional and self-referential relation columns no longer fails Notion validation with "is not a valid property schema"
## 0.7.0.1 (2026-04-16)
### Bug Fixes
* Fix `FromJSON`/`ToJSON` for native icons to use the nested `{"type":"icon","icon":{"name":..., "color":...}}` shape returned by GET endpoints — previously crashed with `key "name" not found` on pages/databases carrying built-in pictogram icons
## 0.7.0.0 (2026-04-16)
### Breaking Changes
* `BlockContent` gains new constructors: `Heading4`, `Tab`, `MeetingNotes`, `Template` — pattern matches on `BlockContent` must handle these variants
* `MentionContent` gains new constructors: `TemplateMentionDate`, `TemplateMentionUser` — pattern matches must be updated
* `RollupFunction` gains new constructors: `CountPerGroup`, `PercentPerGroup`, `Unique`
* `DateCondition` gains new constructors: `DateThisMonth`, `DateThisYear`
* `PageObject` gains new fields: `isLocked`, `isArchived`
* `DataSourceParent` gains `parentDatabaseId` field
* `ColumnBlock` gains `widthRatio` field
* `BotUser` gains `workspaceId`, `workspaceLimits` fields (new `WorkspaceLimits` type)
* `CreateComment` gains `attachments` and `displayName` fields
* `UpdatePage` gains `isLocked` and `isArchived` fields
* `CommentAttachment` restructured: all fields now `Maybe`, new `category` field, hand-rolled FromJSON/ToJSON to support both read and write shapes
* `CommentDisplayName` gains `resolvedName` field
### New Features
* Add `retrievePageFiltered` method with `filter_properties` query parameter for `GET /v1/pages/{page_id}` (`retrievePage` remains backward-compatible)
* Smart constructor `headingBlock` now supports level 4
* `CommentAttachment` and `CommentDisplayName` now have `ToJSON` instances
### Bug Fixes
* Strip read-only `list_start_index` and `list_format` fields from `BlockUpdate` serialization — the Notion API rejects PATCH requests containing these fields on `numbered_list_item` blocks
* Fix parsing of `List Comments` responses: `CommentAttachment` now correctly decodes the `{"category":..., "file":...}` read shape, and `CommentDisplayName` preserves the `resolved_name` field
## 0.6.1.0 (2026-03-31)
### New Features
* **File Upload API**: New `Notion.V1.FileUploads` module with complete file upload support — create, send (multipart form-data), complete, retrieve, and list endpoints
* Smart constructors for single-part, multi-part, and external URL upload modes
* Add `file_upload` variant to `FileValue`, `Icon`, and `Cover` types
### Other Changes
* Update seihou scaffolding (exec-plan 0.1.2 → 0.1.3)
## 0.6.0.0 (2026-03-30)
### Breaking Changes
* Replace untyped `Value` block content with typed `BlockContent` sum type in `Notion.V1.BlockContent` module
* `AppendBlockChildren` and `CreatePage` now use `[BlockContent]` instead of `[Value]` for children
* Block types are now statically typed variants (e.g., `Paragraph`, `Heading1`, `BulletedListItem`, `Code`, `Toggle`, `Callout`, etc.) instead of free-form JSON
### New Features
* **Typed Block Content**: New `Notion.V1.BlockContent` module with `BlockContent` sum type for creating blocks with compile-time safety and smart constructors
* **Nested Block Children**: `BlockContent` supports recursive `children` for creating nested block hierarchies in a single API call (e.g., toggles containing paragraphs, bulleted lists with sub-items)
## 0.5.0.0 (2026-03-29)
### Breaking Changes
* Replace untyped `PropertyValue`/`PropertyItem`/`PropertyValueType` with a proper `PropertyValue` sum type (23 variants) in new `Notion.V1.PropertyValue` module
* Remove `SelectOption` from `Notion.V1.Pages` — use `SelectOptionValue` from `Notion.V1.PropertyValue` instead
* `PageObject.properties` is now `Map Text PropertyValue` instead of `Map Text PropertyItem`
* `CreatePage.properties` and `UpdatePage.properties` are now `Map Text PropertyValue`
* `UpdateDataSource.properties` changes from `Maybe (Map Text PropertySchema)` to `Maybe (Map Text (Maybe PropertySchema))` to support property deletion via `null`
* `QueryDatabase` and `QueryDataSource` gain a `filterProperties` field
* `UpdateDatabase` gains an `isLocked` field
* `CreateDataSource` gains `description` and `cover` fields
### New Features
* **Typed Property Values**: New `Notion.V1.PropertyValue` module with `PropertyValue` sum type for reading page properties via pattern matching, and smart constructors (`titleValue`, `selectValue`, `numberValue`, `checkboxValue`, `dateValue`, `statusValue`, `relationValue`, `peopleValue`, `filesValue`, etc.) for writes
* **Page Property Item Endpoint**: Add `retrievePageProperty` method (`GET /v1/pages/{page_id}/properties/{property_id}`) with `PropertyItemResponse` type handling both single and paginated results
* **Typed Error Handling**: `NotionError` now has an `Exception` instance. The client automatically parses Notion API errors into typed `NotionError` exceptions. Add `parseNotionError` helper and `ToJSON` instance
* **Property Schema Deletion**: Set properties to `Nothing` in `UpdateDataSource` to delete them from the schema (emits `null` in JSON)
* **Auto-Pagination**: New `paginateAll` and `paginateCollect` functions in `Notion.V1.Pagination` that follow cursors automatically
* Add `publicUrl :: Maybe Text` to `PageObject`
* Mark `queryDatabase` as deprecated in favor of `queryDataSource`
## 0.4.0.0 (2026-03-29)
### Breaking Changes
* Replace `properties :: Maybe Value` in `DatabaseObject` with `Maybe (Map Text PropertySchema)`
* Replace `properties :: Value` in `DataSourceObject` with `Map Text PropertySchema`
* Replace `properties :: Value` / `Maybe Value` in `CreateDataSource`, `UpdateDataSource`, `InitialDataSource` with typed `PropertySchema`
* Replace `filter :: Maybe Value` in `QueryDatabase` and `QueryDataSource` with `Maybe Filter`
* Replace `sorts :: Maybe [Value]` in `QueryDatabase` and `QueryDataSource` with `Maybe [Sort]`
### New Features
* **Typed Property Schemas**: New `Notion.V1.Properties` module with `PropertySchema` sum type (23 property types), `SelectColor` enum (10 colors), `NumberFormat` enum (39 formats), `RollupFunction` enum (25 functions), `RelationType`, `SelectOption`, `StatusGroup`
* **Typed Query Filters**: New `Notion.V1.Filter` module with `Filter` DSL — compound `And`/`Or` filters, `PropertyFilter` with 22 condition variants (text, number, checkbox, select, multi-select, date, people, files, relation, status, unique ID, verification, formula, rollup), and `TimestampFilter`
* **Typed Query Sorts**: `Sort` type with `PropertySort` and `TimestampSort`, `SortDirection` enum
## 0.3.1.0 (2026-03-29)
### New Features
* **Markdown Content API**: Add `updatePageMarkdown` method for editing page content via markdown with search-and-replace (`UpdateContent`), full replacement (`ReplaceContent`), and legacy insert/replace commands
* **Create pages with markdown**: Add `markdown` field to `CreatePage` as alternative to `children`
* **Move Page API**: Add `movePage` method (`POST /v1/pages/{page_id}/move`) to relocate pages between parents
* **Template support**: Add `Template` type and `template`/`eraseContent` fields to `CreatePage` and `UpdatePage`
* **List data source templates**: Add `listDataSourceTemplates` method (`GET /v1/data_sources/{id}/templates`)
* **Views API**: New `Notion.V1.Views` module with full CRUD + list + query endpoints for database views (table, board, list, calendar, timeline, gallery, form, chart, map, dashboard)
* **Custom Emojis API**: New `Notion.V1.CustomEmojis` module with `listCustomEmojis` method
* **Native icons**: Add `NativeIcon` variant to `Icon` type (name + color)
* **Custom emoji icons**: Add `CustomEmojiIcon` variant to `Icon` type
* **View webhook events**: Add `ViewCreated`, `ViewUpdated`, `ViewDeleted` event types and `ViewEntity` entity type
* **View object type**: Add `View` constructor to `ObjectType` enum
* Add `position` field to `CreatePage` for controlling page placement within parent
### Non-Breaking Changes
* Add `markdown` field to `CreatePage` (defaults to `Nothing` via `mkCreatePage`)
* Add `template`, `position` fields to `CreatePage` (defaults to `Nothing` via `mkCreatePage`)
* Add `template`, `eraseContent` fields to `UpdatePage` (defaults to `Nothing` via `mkUpdatePage`)
## 0.3.0.0 (2026-03-29)
### Breaking Changes
* Remove `archived` field from `BlockObject` — use `inTrash` instead (renamed to match API 2026-03-11)
* Remove `archived` field from `PageObject` — use existing `inTrash` field
* Remove `archived` field from `DatabaseObject` — use existing `inTrash` field
* Remove `archived` field from `DataSourceObject` — use existing `inTrash` field
* Rename `archived` to `inTrash` in `UpdatePage` request type
* Remove `archived` from `UpdateDatabase` request type — use existing `inTrash` field
* Remove `archived` from `UpdateDataSource` request type — use existing `inTrash` field
* Remove `archived` from `QueryDataSource` request type — use existing `inTrash` field
* Change `AppendBlockChildren` from `newtype` to `data` with new optional `position` field
### New Features
* Add `Position` type (`AfterBlock`, `Start`, `End`) for specifying block insertion position
* The `transcription` block type is renamed to `meeting_notes` by the API (no library code change needed since block types are `Text`)
### Bug Fixes
* Fix backward-compatible `FromJSON` fallback: `.:?` with `<|>` was silently broken (always returned `Nothing`), now correctly falls back through `in_trash` → `is_archived` → `archived`
## 0.2.0.0 (2026-03-29)
### Breaking Changes
* Bump Notion API version from `2025-09-03` to `2026-03-11`
* Change `DataSourceObject.archived` from `Bool` to `Maybe Bool` (field no longer guaranteed in API responses)
### New Features
* Add `PageMarkdown` type and `retrievePageMarkdown` method for `GET /v1/pages/{page_id}/markdown`
* Support optional `include_transcript` query parameter for markdown retrieval
### Bug Fixes
* Handle API rename of `archived` to `is_archived` in responses for `PageObject`, `BlockObject`, `DatabaseObject`, and `DataSourceObject`
## 0.1.0.1 (2026-03-29)
### Bug Fixes
* Export `UUID` constructor from `Notion.V1.Common` for pattern matching
* Fix `PropertyItem` parsing for rollup, formula, and relation property types
* Fix license field in README from BSD-3-Clause to MIT
### Other Changes
* Add `ToJSON` instances for `UserObject`, `BlockObject`, `PageObject`, and related types
## 0.1.0.0 (2026-02-28)
* Initial release
* Support for core Notion API endpoints:
* Databases
* Data Sources
* Pages
* Blocks
* Users
* Search
* Comments
* Webhooks (event types and signature verification)
* Type-safe client with Servant-based implementation
* Targets Notion API version 2025-09-03