@notionhq/custom-blocks 0.1.48 → 0.1.49

package/dist/version.js

@@ -4,4 +4,4 @@
  *
  * WARNING: Generated during SDK publish. Do not edit in the published package.
  */
-export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.48"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.49"

package/docs/data-sources.md

@@ -145,16 +145,19 @@ The SDK reports invalid keys, types, operators, and values through the snapshot'
 <details>
 <summary>Filter operators and values</summary>
 
-| Property types | Filter operators |
-| --- | --- |
-| `title`, `rich_text`, `url`, `email`, `phone_number` | `equals`, `does_not_equal`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty` |
-| `number` | `equals`, `does_not_equal`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to`, `is_empty`, `is_not_empty` |
-| `checkbox` | `equals`, `does_not_equal` |
-| `select`, `status` | `equals`, `does_not_equal`, `is_empty`, `is_not_empty` |
-| `multi_select` | `contains`, `contains_all`, `does_not_contain`, `is_empty`, `is_not_empty` |
-| `date` | `equals`, `before`, `after`, `on_or_before`, `on_or_after`, `is_empty`, `is_not_empty` |
-
-Select, multi-select, and status values can be one option name or an array of option names. For multi-select properties, `contains` matches any supplied option and `contains_all` requires every supplied option. Empty checks use `{ is_empty: true }` or `{ is_not_empty: true }`. Date comparisons accept ISO dates or ISO timestamps.
+| Property types                                       | Filter operators                                                                                                                         |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`, `rich_text`, `url`, `email`, `phone_number` | `equals`, `does_not_equal`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`                       |
+| `number`                                             | `equals`, `does_not_equal`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to`, `is_empty`, `is_not_empty` |
+| `checkbox`                                           | `equals`, `does_not_equal`                                                                                                               |
+| `select`, `status`                                   | `equals`, `does_not_equal`, `is_empty`, `is_not_empty`                                                                                   |
+| `multi_select`                                       | `contains`, `contains_all`, `does_not_contain`, `is_empty`, `is_not_empty`                                                               |
+| `date`                                               | `equals`, `before`, `after`, `on_or_before`, `on_or_after`, `is_empty`, `is_not_empty`                                                   |
+
+- Select, multi-select, and status filters accept one option name or an array of option names.
+- For multi-select filters, `contains` matches **any** supplied option. `contains_all` requires **every** supplied option.
+- Empty checks use `{ is_empty: true }` or `{ is_not_empty: true }`.
+- Date comparisons accept ISO date strings or timestamps. Notion evaluates timestamps at minute precision.
 
 </details>
 
@@ -168,13 +171,13 @@ This example sorts tasks by due date, with the earliest first. Tasks with the sa
 const query = useDataSource("tasks", {
   sorts: [
     { key: "due", direction: "ascending" },
-    { propertyId: "created_time", direction: "descending" },
+    { key: "createdAt", direction: "descending" },
   ],
   limit: 50,
 });
 ```
 
-Here, `due` is a declared date property key and `created_time` is a built-in property ID. Sorts apply in array order, with the first property taking priority. Empty values sort last in both directions.
+Here, `due` is a declared date property key and `createdAt` is a declared key bound to a created-time property in the data source schema. Sorts apply in array order, with the first property taking priority. Empty values sort last in both directions.
 
 You can sort by up to 10 unique properties. Both APIs accept the same sort shape, and you can combine `sorts` with `filter`.
 
@@ -265,9 +268,7 @@ export function ScoreList() {
 
   const displayItems = items.filter(isComplete);
   if (displayItems.length === 0) {
-    return (
-      <div>No rows have both a text name and a finite score.</div>
-    );
+    return <div>No rows have both a text name and a finite score.</div>;
   }
 
   return (
@@ -297,46 +298,93 @@ export function ScoreList() {
 ## Known limitations
 
 - **Row limits and pagination:** `limit` defaults to 20 and is capped at 999. Queries have no cursor or offset. Increasing the limit repeats the query from the start and replaces the snapshot. `hasMore` can remain true at the cap, so use filters to narrow larger data sources.
-- **Filter and sort rules:** Use one property condition or one `and` group with up to 25 conditions. Nested groups and `or` are unsupported. Sort by up to 10 unique properties. Empty values sort last in both directions. See the table below for property support and [Filters](#filters) for operators.
+- **Filter and sort rules:** Use one property condition or one `and` group with up to 25 conditions. Nested groups and `or` are unsupported. You can sort by up to 10 unique properties. Empty values sort last in both directions. See the table below for property support and [Filters](#filters) for operators.
 - **Changing a query:** TypeScript subscriptions copy their options when they start. To change them, unsubscribe and create a new subscription. React replaces the subscription when the key or options change. Previous rows are cleared while the new query loads.
 - **Updates:** Callbacks receive complete snapshots, not individual row changes. A new result can trigger a callback even when its row values are unchanged.
 
-### Property support
-
-The table shows the values returned by the Notion host and whether each property type supports filtering and sorting. ✅ means supported. ❌ means unsupported. ⚠️ marks a text fallback that does not preserve the property's structured value. Missing values can be `undefined`.
-
-| Property type | Query result | Filter | Sort |
-| --- | --- | :---: | :---: |
-| `title` | Plain text | ✅ | ✅ |
-| `rich_text` | Plain text | ✅ | ✅ |
-| `number` | Number | ✅ | ✅ |
-| `checkbox` | Boolean | ✅ | ✅ |
-| `url` | String | ✅ | ✅ |
-| `email` | String | ✅ | ✅ |
-| `phone_number` | String | ✅ | ✅ |
-| `select` | Option name | ✅ | ❌ |
-| `multi_select` | Array of option names | ✅ | ❌ |
-| `status` | Option name | ✅ | ❌ |
-| `date` | `NotionDateValue` | ✅ | ✅ |
-| `people` | Array of record pointers | ❌ | ❌ |
-| `files` | ⚠️ Text fallback | ❌ | ❌ |
-| `unique_id` | ⚠️ Text fallback | ❌ | ❌ |
-| `relation` | Array of record pointers | ❌ | ❌ |
-| `place` | ⚠️ Text fallback | ❌ | ❌ |
-| `formula` | ⚠️ Text fallback | ❌ | ❌ |
-| `rollup` | ⚠️ Text fallback | ❌ | ❌ |
-| `button` | ⚠️ Text fallback | ❌ | ❌ |
-| `verification` | ⚠️ Text fallback | ❌ | ❌ |
-| `last_visited_time` | ⚠️ Text fallback | ❌ | ❌ |
-| `location` | ⚠️ Text fallback | ❌ | ❌ |
-| `created_time` | `NotionDateTime` in UTC | ❌ | ✅ |
-| `last_edited_time` | `NotionDateTime` in UTC | ❌ | ✅ |
-| `created_by` | Array of record pointers | ❌ | ❌ |
-| `last_edited_by` | Array of record pointers | ❌ | ❌ |
-
-Text values omit formatting, mention tokens, and annotations. Record pointers contain a table name and a record ID.
-
-Use `propertyId: "created_time"` or `propertyId: "last_edited_time"` to sort by these built-in timestamps.
+## Property support
+
+This table shows property support for custom blocks running in Notion.
+
+- **Query result** shows values in `propertiesById` and `propertiesByKey` from `useDataSource` and `customBlock.subscribeToDataSource`. Missing values can be `undefined`.
+- **Update row** covers writes through `item.update({ properties: ... })`.
+- **Filter** and **Sort** cover query options.
+
+- 🟢 **Supported:** The SDK supports this operation in Notion.
+- 🟡 **Limited:** The SDK supports this operation with the restrictions shown in the cell.
+- 🔴 **Unavailable:** The SDK does not expose this operation.
+- ⚫ **Not supported in Notion:** Notion itself does not support this operation in the stated case.
+
+| Property type | Query result | Update row | Filter | Sort |
+| --- | --- | --- | --- | --- |
+| `title` | 🟢 Plain text | 🟡 Plain text only | 🟢 Supported | 🟢 Supported |
+| `rich_text` | 🟢 Plain text | 🟡 Plain text only | 🟢 Supported | 🟢 Supported |
+| `number` | 🟢 Number | 🟢 Supported | 🟢 Supported | 🟢 Supported |
+| `checkbox` | 🟢 Boolean | 🟢 Supported | 🟢 Supported | 🟢 Supported |
+| `url` | 🟢 String | 🟢 Supported | 🟢 Supported | 🟢 Supported |
+| `email` | 🟢 String | 🟢 Supported | 🟢 Supported | 🟢 Supported |
+| `phone_number` | 🟢 String | 🟢 Supported | 🟢 Supported | 🟢 Supported |
+| `select` | 🟢 Option name | 🟡 Set value only | 🟢 Supported | 🔴 Unavailable |
+| `multi_select` | 🟢 Array of option names | 🟡 Set values only | 🟢 Supported | 🔴 Unavailable |
+| `status` | 🟢 Option name | 🟡 Set value only | 🟡 Option names or empty checks, without groups | 🔴 Unavailable |
+| `date` | 🟢 `NotionDateValue` | 🟡 Minute precision | 🟡 Fixed start-date comparisons or empty checks, at minute precision | 🟢 Supported |
+| `people` | 🟢 Array of record pointers | 🟢 Supported | 🔴 Unavailable | 🔴 Unavailable |
+| `files` | 🟡 Text fallback | 🟡 File URLs only | 🔴 Unavailable | 🔴 Unavailable |
+| `unique_id` | 🟡 Text fallback | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `relation` | 🟢 Array of record pointers | 🟡 Replaces value. Rejects `has_more: true`. | 🔴 Unavailable | 🔴 Unavailable for standard relations. ⚫ Notion cannot sort XLDB targets. |
+| `place` | 🟡 Text fallback | 🟢 Supported | 🔴 Unavailable | 🔴 Unavailable |
+| `formula` | 🟡 Text fallback | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `rollup` | 🟡 Text fallback | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable for numeric targets or numeric aggregations. ⚫ Notion cannot sort other rollups. |
+| `button` | 🟡 Text fallback | 🔴 Unavailable | ⚫ Not supported in Notion | ⚫ Not supported in Notion |
+| `verification` | 🟡 Text fallback | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `last_visited_time` | 🟡 Text fallback | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `location` | 🟡 Text fallback | 🔴 Unavailable | 🔴 Unavailable elsewhere. ⚫ Notion disables filters in My Meetings and Library system collections. | 🔴 Unavailable elsewhere. ⚫ Notion disables sorts in Library system collections. |
+| `created_time` | 🟢 `NotionDateTime` in UTC | 🔴 Unavailable | 🔴 Unavailable | 🟡 Schema property only |
+| `last_edited_time` | 🟢 `NotionDateTime` in UTC | 🔴 Unavailable | 🔴 Unavailable | 🟡 Schema property only |
+| `created_by` | 🟢 Array of record pointers | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `last_edited_by` | 🟢 Array of record pointers | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+
+### Notes
+
+- Text values omit formatting, mention tokens, and annotations. A text fallback can be empty and does not preserve the property's structured value. It does not provide structured formula or rollup results.
+- Record pointers contain a table name and a record ID.
+- Every row includes four built-in properties in `propertiesById`: `created_time`, `last_edited_time`, `created_by`, and `last_edited_by`. The data source does not need matching schema properties. These values are read-only. Timestamps use `NotionDateTime` in UTC. Creator and editor values use arrays of record pointers.
+- The SDK accepts timestamp sorts, but the current Notion host requires a property ID in the data source's actual schema. Sort using a configured created-time or last-edited-time property. The synthetic IDs `created_time` and `last_edited_time` alone are not sufficient.
+- You can sort by up to 10 unique properties.
+- Date-time filter values may include seconds or milliseconds, but the Notion host currently evaluates them at minute precision. Date filters do not expose relative dates or end-date targeting.
+- Status filters accept option names and empty checks, but not status groups.
+- Filters accept one condition or an `and` group of up to 25 conditions. The SDK does not support `or` or nested groups.
+- Select, multi-select, and status query values contain option names. Their schemas provide option IDs and colors separately. Writes set the selected values. They do not edit option definitions or colors.
+
+### Writing values
+
+The value you read has a different shape from the value you write. For example, a query returns a status as a string:
+
+```ts
+item.propertiesByKey.status // "Done"
+```
+
+To update it, wrap the string in a property object. Here, `status` is a declared property key:
+
+```ts
+const result = await item.update({
+  properties: {
+    status: { type: "status", status: { name: "Done" } },
+  },
+});
+
+if (result.status === "error") {
+  console.error(result.error.message);
+}
+```
+
+Other write restrictions:
+
+- **Text:** Title and rich text writes preserve plain text, but not formatting or mentions.
+- **Files:** Supply external or existing hosted file URLs. The host stores them as links and does not support upload references.
+- **Relations:** Supply the complete replacement list of related pages. The host rejects `has_more: true`, which indicates an incomplete list.
+
+See [Pages property support](./pages.md#property-support) for the page-property read shapes.
 
 ## Types
 

package/docs/pages.md

@@ -149,6 +149,61 @@ File-upload references aren't enabled for custom blocks yet. When updating icons
 
 Do **not** send `{ type: "file_upload", file_upload: { id } }`; the host will reject it.
 
+## Property support
+
+This table shows property support for custom blocks running in Notion.
+
+- **Read value** shows `page.properties` in responses from `pages.get`, `pages.create`, and `pages.update`. The table identifies top-level fields separately. Unavailable values are absent from `page.properties`.
+- **Create** covers property writes through `pages.create`.
+- **Update** covers property writes through `pages.update`.
+
+Pages outside a data source support only `title`. Other property writes require a data source row and a property in its schema.
+
+- 🟢 **Supported:** The SDK supports this operation in Notion.
+- 🟡 **Limited:** The SDK supports this operation with the restrictions shown in the cell.
+- 🔴 **Unavailable:** The SDK does not expose this operation.
+- ⚫ **Not supported in Notion:** Notion itself does not support this operation in the stated case.
+
+| Property type | Read value (`pages.get`) | Create (`pages.create`) | Update (`pages.update`) |
+| --- | --- | --- | --- |
+| `title` | 🟡 Text array with plain text only | 🟡 Plain text only | 🟡 Plain text only |
+| `rich_text` | 🟡 Text array with plain text only | 🟡 Plain text only | 🟡 Plain text only |
+| `number` | 🟢 Number or `null` | 🟢 Supported | 🟢 Supported |
+| `checkbox` | 🟢 Boolean | 🟢 Supported | 🟢 Supported |
+| `url` | 🟢 String or `null` | 🟢 Supported | 🟢 Supported |
+| `email` | 🟢 String or `null` | 🟢 Supported | 🟢 Supported |
+| `phone_number` | 🟢 String or `null` | 🟢 Supported | 🟢 Supported |
+| `select` | 🟡 Option ID/name object or `null` | 🟡 Set value only | 🟡 Set value only |
+| `multi_select` | 🟡 Array of option ID/name objects | 🟡 Set value only | 🟡 Set value only |
+| `status` | 🟡 Option ID/name object or `null` | 🟡 Set value only | 🟡 Set value only |
+| `date` | 🟢 `start` and optional `end` strings, or `null` | 🟡 Minute precision | 🟡 Minute precision |
+| `people` | 🟢 Array of user/group ID objects | 🟢 Supported | 🟢 Supported |
+| `files` | 🟡 External file links only | 🟡 File URLs only | 🟡 File URLs only |
+| `unique_id` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `relation` | 🟢 Array of page ID objects | 🟡 Replaces value. Rejects `has_more: true`. | 🟡 Replaces value. Rejects `has_more: true`. |
+| `place` | 🟢 Coordinates and optional place details, or `null` | 🟢 Supported | 🟢 Supported |
+| `formula` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `rollup` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `button` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `verification` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `last_visited_time` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `location` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `created_time` | 🟡 Top-level ISO timestamp only | 🔴 Unavailable | 🔴 Unavailable |
+| `last_edited_time` | 🟡 Top-level ISO timestamp only | 🔴 Unavailable | 🔴 Unavailable |
+| `created_by` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+| `last_edited_by` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
+
+### Notes
+
+- Select, multi-select, and status reads return option names. They also return IDs when the options match the schema, but they omit colors. Writes accept an existing option ID or a name and set the selected value. They do not edit option definitions or colors. If you supply both an ID and a name, the host uses the ID. The host rejects unknown IDs.
+- Date-time writes preserve hours and minutes but discard seconds and milliseconds.
+- Title and rich text use text arrays, but reads and writes preserve only plain text. Reads and writes do not preserve formatting, links, mentions, or equations as structured rich text.
+- File reads include link items only. File writes accept `external` URLs and existing `file` URLs and store them as links. Upload references (`file_upload`) are unsupported.
+- Relation writes replace the value and reject `has_more: true`.
+- `created_time` and `last_edited_time` are read-only top-level fields on `page`, when available. The host omits them from `page.properties`. The host does not return `created_by` or `last_edited_by`, even as top-level fields. The host does not return structured page values for formula, rollup, unique ID, or the other omitted types.
+
+For flattened query values, filters, and sorts, see [Data source property support](./data-sources.md#property-support).
+
 ## Types
 
 - `NotionPage` — the page record returned by every successful call.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.1.48",
+	"version": "0.1.49",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {