@notionhq/custom-blocks 0.1.48 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -3
- package/dist/bridge/SandboxBridge.d.ts.map +1 -1
- package/dist/bridge/SandboxBridge.js +2 -4
- package/dist/bridge/sandboxClient.d.ts +0 -5
- package/dist/bridge/sandboxClient.d.ts.map +1 -1
- package/dist/bridge/sandboxClient.js +0 -12
- package/dist/customBlock.d.ts +0 -22
- package/dist/customBlock.d.ts.map +1 -1
- package/dist/customBlock.js +0 -37
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/protocol/dataSources/dataSourcePage.d.ts +2 -2
- package/dist/protocol/dataSources/dataSourcePage.js +2 -3
- package/dist/protocol/messages/createPageResult.d.ts +2 -2
- package/dist/protocol/messages/getPage.d.ts +2 -2
- package/dist/protocol/messages/hostToSandbox.d.ts +9 -9
- package/dist/protocol/messages/init.d.ts +1 -1
- package/dist/protocol/messages/init.js +2 -3
- package/dist/protocol/messages/queryDataSourceResult.d.ts +2 -2
- package/dist/protocol/messages/updatePageResult.d.ts +2 -2
- package/dist/protocol/pages/page.d.ts +2 -2
- package/dist/protocol/pages/page.js +2 -3
- package/dist/protocol/protocolVersion.d.ts +1 -1
- package/dist/protocol/protocolVersion.js +1 -1
- package/dist/react/NotionCustomBlock.d.ts +1 -9
- package/dist/react/NotionCustomBlock.d.ts.map +1 -1
- package/dist/react/NotionCustomBlock.js +9 -3
- package/dist/react/index.d.ts +0 -1
- package/dist/react/index.d.ts.map +1 -1
- package/dist/react/index.js +0 -1
- package/dist/types.d.ts +4 -38
- package/dist/types.d.ts.map +1 -1
- package/dist/version.js +1 -1
- package/docs/data-sources.md +100 -52
- package/docs/lifecycle.md +1 -14
- package/docs/pages.md +55 -0
- package/docs/users.md +97 -26
- package/package.json +1 -6
- package/src/bridge/SandboxBridge.ts +2 -4
- package/src/bridge/sandboxClient.ts +0 -15
- package/src/customBlock.ts +1 -65
- package/src/index.ts +1 -1
- package/src/react/NotionCustomBlock.tsx +9 -11
- package/src/react/index.ts +0 -1
- package/src/types.ts +4 -46
- package/dist/react/useCustomBlockAutoResize.d.ts +0 -26
- package/dist/react/useCustomBlockAutoResize.d.ts.map +0 -1
- package/dist/react/useCustomBlockAutoResize.js +0 -31
- package/src/react/useCustomBlockAutoResize.ts +0 -42
- package/vite-plugin/index.d.ts +0 -12
- package/vite-plugin/index.js +0 -11
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4DAA4D,CAAA;AACxG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iEAAiE,CAAA;AAC5G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gEAAgE,CAAA;AAC1G,OAAO,KAAK,EACX,kBAAkB,EAClB,YAAY,EACZ,MAAM,yCAAyC,CAAA;AAChD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yDAAyD,CAAA;AACvG,OAAO,KAAK,EACX,uBAAuB,EACvB,8BAA8B,EAC9B,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EACX,2BAA2B,EAC3B,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,2BAA2B,EAC3B,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,6BAA6B,EAC7B,gBAAgB,EAChB,sBAAsB,EACtB,MAAM,wDAAwD,CAAA;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAA;AACvG,OAAO,KAAK,EACX,iCAAiC,EACjC,iCAAiC,EACjC,6BAA6B,EAC7B,+BAA+B,EAC/B,+BAA+B,EAC/B,6BAA6B,EAC7B,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,oEAAoE,CAAA;AAC7H,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,8BAA8B,EAC9B,uBAAuB,EACvB,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EACX,eAAe,EACf,cAAc,EACd,uBAAuB,EACvB,MAAM,gDAAgD,CAAA;AAEvD,YAAY,EAAE,oBAAoB,EAAE,MAAM,4CAA4C,CAAA;AACtF,YAAY,EACX,kBAAkB,EAClB,aAAa,GACb,MAAM,yCAAyC,CAAA;AAChD,YAAY,EACX,UAAU,EACV,YAAY,EACZ,cAAc,GACd,MAAM,gDAAgD,CAAA;AACvD,YAAY,EACX,8BAA8B,EAC9B,2BAA2B,EAC3B,2BAA2B,EAC3B,6BAA6B,EAC7B,mCAAmC,EACnC,8BAA8B,GAC9B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,4BAA4B,GACvC,uBAAuB,SAAS,MAAM,aAAa,GAChD,aAAa,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GACnC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,KAAK,GACN,KAAK,CAAA;AAET,MAAM,MAAM,0BAA0B,GAAG;IACxC,CAAC,eAAe,EAAE,MAAM,GAAG,4BAA4B,CAAA;CACvD,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,EAAE,EAAE,YAAY,CAAA;
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
package/dist/version.js
CHANGED
package/docs/data-sources.md
CHANGED
|
@@ -145,16 +145,19 @@ The SDK reports invalid keys, types, operators, and values through the snapshot'
|
|
|
145
145
|
<details>
|
|
146
146
|
<summary>Filter operators and values</summary>
|
|
147
147
|
|
|
148
|
-
| Property types
|
|
149
|
-
|
|
|
150
|
-
| `title`, `rich_text`, `url`, `email`, `phone_number` | `equals`, `does_not_equal`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty`
|
|
151
|
-
| `number`
|
|
152
|
-
| `checkbox`
|
|
153
|
-
| `select`, `status`
|
|
154
|
-
| `multi_select`
|
|
155
|
-
| `date`
|
|
156
|
-
|
|
157
|
-
Select, multi-select, and status
|
|
148
|
+
| Property types | Filter operators |
|
|
149
|
+
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
|
150
|
+
| `title`, `rich_text`, `url`, `email`, `phone_number` | `equals`, `does_not_equal`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, `is_not_empty` |
|
|
151
|
+
| `number` | `equals`, `does_not_equal`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to`, `is_empty`, `is_not_empty` |
|
|
152
|
+
| `checkbox` | `equals`, `does_not_equal` |
|
|
153
|
+
| `select`, `status` | `equals`, `does_not_equal`, `is_empty`, `is_not_empty` |
|
|
154
|
+
| `multi_select` | `contains`, `contains_all`, `does_not_contain`, `is_empty`, `is_not_empty` |
|
|
155
|
+
| `date` | `equals`, `before`, `after`, `on_or_before`, `on_or_after`, `is_empty`, `is_not_empty` |
|
|
156
|
+
|
|
157
|
+
- Select, multi-select, and status filters accept one option name or an array of option names.
|
|
158
|
+
- For multi-select filters, `contains` matches **any** supplied option. `contains_all` requires **every** supplied option.
|
|
159
|
+
- Empty checks use `{ is_empty: true }` or `{ is_not_empty: true }`.
|
|
160
|
+
- Date comparisons accept ISO date strings or timestamps. Notion evaluates timestamps at minute precision.
|
|
158
161
|
|
|
159
162
|
</details>
|
|
160
163
|
|
|
@@ -168,13 +171,13 @@ This example sorts tasks by due date, with the earliest first. Tasks with the sa
|
|
|
168
171
|
const query = useDataSource("tasks", {
|
|
169
172
|
sorts: [
|
|
170
173
|
{ key: "due", direction: "ascending" },
|
|
171
|
-
{
|
|
174
|
+
{ key: "createdAt", direction: "descending" },
|
|
172
175
|
],
|
|
173
176
|
limit: 50,
|
|
174
177
|
});
|
|
175
178
|
```
|
|
176
179
|
|
|
177
|
-
Here, `due` is a declared date property key and `
|
|
180
|
+
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.
|
|
178
181
|
|
|
179
182
|
You can sort by up to 10 unique properties. Both APIs accept the same sort shape, and you can combine `sorts` with `filter`.
|
|
180
183
|
|
|
@@ -265,9 +268,7 @@ export function ScoreList() {
|
|
|
265
268
|
|
|
266
269
|
const displayItems = items.filter(isComplete);
|
|
267
270
|
if (displayItems.length === 0) {
|
|
268
|
-
return
|
|
269
|
-
<div>No rows have both a text name and a finite score.</div>
|
|
270
|
-
);
|
|
271
|
+
return <div>No rows have both a text name and a finite score.</div>;
|
|
271
272
|
}
|
|
272
273
|
|
|
273
274
|
return (
|
|
@@ -297,46 +298,93 @@ export function ScoreList() {
|
|
|
297
298
|
## Known limitations
|
|
298
299
|
|
|
299
300
|
- **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.
|
|
300
|
-
- **Filter and sort rules:** Use one property condition or one `and` group with up to 25 conditions. Nested groups and `or` are unsupported.
|
|
301
|
+
- **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.
|
|
301
302
|
- **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.
|
|
302
303
|
- **Updates:** Callbacks receive complete snapshots, not individual row changes. A new result can trigger a callback even when its row values are unchanged.
|
|
303
304
|
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
|
318
|
-
|
|
|
319
|
-
| `
|
|
320
|
-
| `
|
|
321
|
-
| `
|
|
322
|
-
| `
|
|
323
|
-
| `
|
|
324
|
-
| `
|
|
325
|
-
| `
|
|
326
|
-
| `
|
|
327
|
-
| `
|
|
328
|
-
| `
|
|
329
|
-
| `
|
|
330
|
-
| `
|
|
331
|
-
| `
|
|
332
|
-
| `
|
|
333
|
-
| `
|
|
334
|
-
| `
|
|
335
|
-
| `
|
|
336
|
-
|
|
337
|
-
Text
|
|
338
|
-
|
|
339
|
-
|
|
305
|
+
## Property support
|
|
306
|
+
|
|
307
|
+
This table shows property support for custom blocks running in Notion.
|
|
308
|
+
|
|
309
|
+
- **Query result** shows values in `propertiesById` and `propertiesByKey` from `useDataSource` and `customBlock.subscribeToDataSource`. Missing values can be `undefined`.
|
|
310
|
+
- **Update row** covers writes through `item.update({ properties: ... })`.
|
|
311
|
+
- **Filter** and **Sort** cover query options.
|
|
312
|
+
|
|
313
|
+
- 🟢 **Supported:** The SDK supports this operation in Notion.
|
|
314
|
+
- 🟡 **Limited:** The SDK supports this operation with the restrictions shown in the cell.
|
|
315
|
+
- 🔴 **Unavailable:** The SDK does not expose this operation.
|
|
316
|
+
- ⚫ **Not supported in Notion:** Notion itself does not support this operation in the stated case.
|
|
317
|
+
|
|
318
|
+
| Property type | Query result | Update row | Filter | Sort |
|
|
319
|
+
| --- | --- | --- | --- | --- |
|
|
320
|
+
| `title` | 🟢 Plain text | 🟡 Plain text only | 🟢 Supported | 🟢 Supported |
|
|
321
|
+
| `rich_text` | 🟢 Plain text | 🟡 Plain text only | 🟢 Supported | 🟢 Supported |
|
|
322
|
+
| `number` | 🟢 Number | 🟢 Supported | 🟢 Supported | 🟢 Supported |
|
|
323
|
+
| `checkbox` | 🟢 Boolean | 🟢 Supported | 🟢 Supported | 🟢 Supported |
|
|
324
|
+
| `url` | 🟢 String | 🟢 Supported | 🟢 Supported | 🟢 Supported |
|
|
325
|
+
| `email` | 🟢 String | 🟢 Supported | 🟢 Supported | 🟢 Supported |
|
|
326
|
+
| `phone_number` | 🟢 String | 🟢 Supported | 🟢 Supported | 🟢 Supported |
|
|
327
|
+
| `select` | 🟢 Option name | 🟡 Set value only | 🟢 Supported | 🔴 Unavailable |
|
|
328
|
+
| `multi_select` | 🟢 Array of option names | 🟡 Set values only | 🟢 Supported | 🔴 Unavailable |
|
|
329
|
+
| `status` | 🟢 Option name | 🟡 Set value only | 🟡 Option names or empty checks, without groups | 🔴 Unavailable |
|
|
330
|
+
| `date` | 🟢 `NotionDateValue` | 🟡 Minute precision | 🟡 Fixed start-date comparisons or empty checks, at minute precision | 🟢 Supported |
|
|
331
|
+
| `people` | 🟢 Array of record pointers | 🟢 Supported | 🔴 Unavailable | 🔴 Unavailable |
|
|
332
|
+
| `files` | 🟡 Text fallback | 🟡 File URLs only | 🔴 Unavailable | 🔴 Unavailable |
|
|
333
|
+
| `unique_id` | 🟡 Text fallback | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
334
|
+
| `relation` | 🟢 Array of record pointers | 🟡 Replaces value. Rejects `has_more: true`. | 🔴 Unavailable | 🔴 Unavailable for standard relations. ⚫ Notion cannot sort XLDB targets. |
|
|
335
|
+
| `place` | 🟡 Text fallback | 🟢 Supported | 🔴 Unavailable | 🔴 Unavailable |
|
|
336
|
+
| `formula` | 🟡 Text fallback | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
337
|
+
| `rollup` | 🟡 Text fallback | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable for numeric targets or numeric aggregations. ⚫ Notion cannot sort other rollups. |
|
|
338
|
+
| `button` | 🟡 Text fallback | 🔴 Unavailable | ⚫ Not supported in Notion | ⚫ Not supported in Notion |
|
|
339
|
+
| `verification` | 🟡 Text fallback | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
340
|
+
| `last_visited_time` | 🟡 Text fallback | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
341
|
+
| `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. |
|
|
342
|
+
| `created_time` | 🟢 `NotionDateTime` in UTC | 🔴 Unavailable | 🔴 Unavailable | 🟡 Schema property only |
|
|
343
|
+
| `last_edited_time` | 🟢 `NotionDateTime` in UTC | 🔴 Unavailable | 🔴 Unavailable | 🟡 Schema property only |
|
|
344
|
+
| `created_by` | 🟢 Array of record pointers | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
345
|
+
| `last_edited_by` | 🟢 Array of record pointers | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
346
|
+
|
|
347
|
+
### Notes
|
|
348
|
+
|
|
349
|
+
- 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.
|
|
350
|
+
- Record pointers contain a table name and a record ID.
|
|
351
|
+
- 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.
|
|
352
|
+
- 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.
|
|
353
|
+
- You can sort by up to 10 unique properties.
|
|
354
|
+
- 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.
|
|
355
|
+
- Status filters accept option names and empty checks, but not status groups.
|
|
356
|
+
- Filters accept one condition or an `and` group of up to 25 conditions. The SDK does not support `or` or nested groups.
|
|
357
|
+
- 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.
|
|
358
|
+
|
|
359
|
+
### Writing values
|
|
360
|
+
|
|
361
|
+
The value you read has a different shape from the value you write. For example, a query returns a status as a string:
|
|
362
|
+
|
|
363
|
+
```ts
|
|
364
|
+
item.propertiesByKey.status // "Done"
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
To update it, wrap the string in a property object. Here, `status` is a declared property key:
|
|
368
|
+
|
|
369
|
+
```ts
|
|
370
|
+
const result = await item.update({
|
|
371
|
+
properties: {
|
|
372
|
+
status: { type: "status", status: { name: "Done" } },
|
|
373
|
+
},
|
|
374
|
+
});
|
|
375
|
+
|
|
376
|
+
if (result.status === "error") {
|
|
377
|
+
console.error(result.error.message);
|
|
378
|
+
}
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
Other write restrictions:
|
|
382
|
+
|
|
383
|
+
- **Text:** Title and rich text writes preserve plain text, but not formatting or mentions.
|
|
384
|
+
- **Files:** Supply external or existing hosted file URLs. The host stores them as links and does not support upload references.
|
|
385
|
+
- **Relations:** Supply the complete replacement list of related pages. The host rejects `has_more: true`, which indicates an incomplete list.
|
|
386
|
+
|
|
387
|
+
See [Pages property support](./pages.md#property-support) for the page-property read shapes.
|
|
340
388
|
|
|
341
389
|
## Types
|
|
342
390
|
|
package/docs/lifecycle.md
CHANGED
|
@@ -75,8 +75,7 @@ The SDK measures the `#root` element and sends its initial height in
|
|
|
75
75
|
`initResult.success`. It sends later height changes in `resize` messages. The
|
|
76
76
|
host uses these messages to keep the iframe height in sync.
|
|
77
77
|
|
|
78
|
-
Using `<NotionCustomBlock>` enables this behavior automatically.
|
|
79
|
-
`customBlock.autoResize()` for a custom, framework-neutral initialization wrapper.
|
|
78
|
+
Using `<NotionCustomBlock>` enables this behavior automatically.
|
|
80
79
|
|
|
81
80
|
## API
|
|
82
81
|
|
|
@@ -196,18 +195,6 @@ function ThemeLabel() {
|
|
|
196
195
|
|
|
197
196
|
See [Block location and appearance](./block-location.md#reading-values-and-following-changes) for the available getters, subscriptions, and React hooks.
|
|
198
197
|
|
|
199
|
-
### `customBlock.autoResize()`
|
|
200
|
-
|
|
201
|
-
For non-React auto-resize, pass the element whose content height should drive the host iframe. The helper posts one initial measurement, observes later size changes when `ResizeObserver` is available, dedupes unchanged heights, and returns a cleanup function:
|
|
202
|
-
|
|
203
|
-
```ts
|
|
204
|
-
const stopAutoResize = customBlock.autoResize({
|
|
205
|
-
target: document.getElementById("root"),
|
|
206
|
-
});
|
|
207
|
-
|
|
208
|
-
// Call stopAutoResize() when your renderer is removed.
|
|
209
|
-
```
|
|
210
|
-
|
|
211
198
|
### `NotInIframeError`
|
|
212
199
|
|
|
213
200
|
Thrown when `initCustomBlock` is called in a top-level tab (no parent frame). It extends `CustomBlockInitializationError`, has `code: "not_in_iframe"` and `isRetryable: false`, and can be detected specifically with `instanceof NotInIframeError`. `<NotionCustomBlock>` catches it and falls back to a standalone preview with a warning banner.
|
package/docs/pages.md
CHANGED
|
@@ -149,6 +149,61 @@ File-upload references aren't enabled for custom blocks yet. When updating icons
|
|
|
149
149
|
|
|
150
150
|
Do **not** send `{ type: "file_upload", file_upload: { id } }`; the host will reject it.
|
|
151
151
|
|
|
152
|
+
## Property support
|
|
153
|
+
|
|
154
|
+
This table shows property support for custom blocks running in Notion.
|
|
155
|
+
|
|
156
|
+
- **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`.
|
|
157
|
+
- **Create** covers property writes through `pages.create`.
|
|
158
|
+
- **Update** covers property writes through `pages.update`.
|
|
159
|
+
|
|
160
|
+
Pages outside a data source support only `title`. Other property writes require a data source row and a property in its schema.
|
|
161
|
+
|
|
162
|
+
- 🟢 **Supported:** The SDK supports this operation in Notion.
|
|
163
|
+
- 🟡 **Limited:** The SDK supports this operation with the restrictions shown in the cell.
|
|
164
|
+
- 🔴 **Unavailable:** The SDK does not expose this operation.
|
|
165
|
+
- ⚫ **Not supported in Notion:** Notion itself does not support this operation in the stated case.
|
|
166
|
+
|
|
167
|
+
| Property type | Read value (`pages.get`) | Create (`pages.create`) | Update (`pages.update`) |
|
|
168
|
+
| --- | --- | --- | --- |
|
|
169
|
+
| `title` | 🟡 Text array with plain text only | 🟡 Plain text only | 🟡 Plain text only |
|
|
170
|
+
| `rich_text` | 🟡 Text array with plain text only | 🟡 Plain text only | 🟡 Plain text only |
|
|
171
|
+
| `number` | 🟢 Number or `null` | 🟢 Supported | 🟢 Supported |
|
|
172
|
+
| `checkbox` | 🟢 Boolean | 🟢 Supported | 🟢 Supported |
|
|
173
|
+
| `url` | 🟢 String or `null` | 🟢 Supported | 🟢 Supported |
|
|
174
|
+
| `email` | 🟢 String or `null` | 🟢 Supported | 🟢 Supported |
|
|
175
|
+
| `phone_number` | 🟢 String or `null` | 🟢 Supported | 🟢 Supported |
|
|
176
|
+
| `select` | 🟡 Option ID/name object or `null` | 🟡 Set value only | 🟡 Set value only |
|
|
177
|
+
| `multi_select` | 🟡 Array of option ID/name objects | 🟡 Set value only | 🟡 Set value only |
|
|
178
|
+
| `status` | 🟡 Option ID/name object or `null` | 🟡 Set value only | 🟡 Set value only |
|
|
179
|
+
| `date` | 🟢 `start` and optional `end` strings, or `null` | 🟡 Minute precision | 🟡 Minute precision |
|
|
180
|
+
| `people` | 🟢 Array of user/group ID objects | 🟢 Supported | 🟢 Supported |
|
|
181
|
+
| `files` | 🟡 External file links only | 🟡 File URLs only | 🟡 File URLs only |
|
|
182
|
+
| `unique_id` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
183
|
+
| `relation` | 🟢 Array of page ID objects | 🟡 Replaces value. Rejects `has_more: true`. | 🟡 Replaces value. Rejects `has_more: true`. |
|
|
184
|
+
| `place` | 🟢 Coordinates and optional place details, or `null` | 🟢 Supported | 🟢 Supported |
|
|
185
|
+
| `formula` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
186
|
+
| `rollup` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
187
|
+
| `button` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
188
|
+
| `verification` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
189
|
+
| `last_visited_time` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
190
|
+
| `location` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
191
|
+
| `created_time` | 🟡 Top-level ISO timestamp only | 🔴 Unavailable | 🔴 Unavailable |
|
|
192
|
+
| `last_edited_time` | 🟡 Top-level ISO timestamp only | 🔴 Unavailable | 🔴 Unavailable |
|
|
193
|
+
| `created_by` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
194
|
+
| `last_edited_by` | 🔴 Unavailable | 🔴 Unavailable | 🔴 Unavailable |
|
|
195
|
+
|
|
196
|
+
### Notes
|
|
197
|
+
|
|
198
|
+
- 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.
|
|
199
|
+
- Date-time writes preserve hours and minutes but discard seconds and milliseconds.
|
|
200
|
+
- 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.
|
|
201
|
+
- 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.
|
|
202
|
+
- Relation writes replace the value and reject `has_more: true`.
|
|
203
|
+
- `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.
|
|
204
|
+
|
|
205
|
+
For flattened query values, filters, and sorts, see [Data source property support](./data-sources.md#property-support).
|
|
206
|
+
|
|
152
207
|
## Types
|
|
153
208
|
|
|
154
209
|
- `NotionPage` — the page record returned by every successful call.
|
package/docs/users.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# `users` API
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Read the current user, fetch a user by ID, or list workspace users from inside a custom block.
|
|
4
4
|
|
|
5
5
|
```ts
|
|
6
6
|
import {
|
|
@@ -12,52 +12,113 @@ import {
|
|
|
12
12
|
import { useCurrentUser } from "@notionhq/custom-blocks/react";
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
`users.get()` and `users.list()` follow the SDK's [error-handling contract](./errors.md). Check `result.status` before reading `result.user` or `result.list`.
|
|
16
16
|
|
|
17
17
|
## Reading the current user
|
|
18
18
|
|
|
19
|
-
`useCurrentUser()`
|
|
19
|
+
`customBlock.getCurrentUser()` and `useCurrentUser()` return the user viewing the custom block. Both read the user from the block’s state without a separate request.
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
const me = useCurrentUser();
|
|
23
|
-
// me.id, me.name, me.person.email
|
|
24
|
-
```
|
|
21
|
+
Wait for `initCustomBlock()` to resolve before calling the getter or mounting components that use the hook. See [initialization](./lifecycle.md).
|
|
25
22
|
|
|
26
|
-
|
|
23
|
+
### TypeScript API
|
|
27
24
|
|
|
28
|
-
|
|
25
|
+
Use `customBlock.getCurrentUser()` to read the current user in any framework. Subscribe to context changes to keep your UI updated:
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
import { customBlock, initCustomBlock } from "@notionhq/custom-blocks"
|
|
29
29
|
|
|
30
|
-
```ts
|
|
31
30
|
await initCustomBlock()
|
|
31
|
+
const user = customBlock.getCurrentUser()
|
|
32
|
+
console.log(user.name)
|
|
32
33
|
|
|
33
|
-
const unsubscribe = customBlock.subscribeToCurrentUser(
|
|
34
|
-
|
|
34
|
+
const unsubscribe = customBlock.subscribeToCurrentUser(nextUser => {
|
|
35
|
+
console.log(nextUser.name)
|
|
35
36
|
})
|
|
36
37
|
```
|
|
37
38
|
|
|
38
|
-
Call `unsubscribe()` when
|
|
39
|
+
Call `unsubscribe()` when you no longer need updates. The callback receives the initial profile and later changes.
|
|
39
40
|
See [context subscriptions](./block-location.md#reading-values-and-following-changes) for initialization and equality rules.
|
|
40
41
|
|
|
42
|
+
### React hook
|
|
43
|
+
|
|
44
|
+
In React, use `useCurrentUser()` to re-render when the current user changes:
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
import { useCurrentUser } from "@notionhq/custom-blocks/react"
|
|
48
|
+
|
|
49
|
+
function Greeting() {
|
|
50
|
+
const user = useCurrentUser()
|
|
51
|
+
return <p>Hello, {user.name ?? "there"}</p>
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Both approaches return the same `NotionUser` shape.
|
|
56
|
+
|
|
57
|
+
## User object
|
|
58
|
+
|
|
59
|
+
`NotionUser` is based on the [public API User object](https://developers.notion.com/reference/user). `users.get()` and the current-user APIs return a `NotionUser`. `users.list()` returns a page of these objects. Custom blocks return only people, not bots or integrations.
|
|
60
|
+
|
|
61
|
+
All fields except `name` are always present. `name` may be omitted. `avatar_url` is present but can be `null`.
|
|
62
|
+
|
|
63
|
+
| Property | Type | Description |
|
|
64
|
+
| --- | --- | --- |
|
|
65
|
+
| `object` | `"user"` | Identifies a user object. |
|
|
66
|
+
| `id` | `string` (UUID) | The user's ID. Typed as `NotionUserId` in the SDK. |
|
|
67
|
+
| `name` | `string` (optional) | The user's name, if available. |
|
|
68
|
+
| `avatar_url` | `string` (nullable) | The user's avatar URL, or `null` if no avatar is available. |
|
|
69
|
+
| `type` | `"person"` | Custom blocks return people. |
|
|
70
|
+
| `person` | `object` | The user's person details. |
|
|
71
|
+
| `person.email` | `string` | The user's email address. |
|
|
72
|
+
|
|
41
73
|
## Listing users
|
|
42
74
|
|
|
43
|
-
`users.list(
|
|
75
|
+
Each `users.list()` call returns one page of workspace users visible to the viewing user. The SDK does not fetch the remaining pages automatically.
|
|
44
76
|
|
|
45
77
|
```ts
|
|
46
78
|
const result = await users.list({ pageSize: 50 });
|
|
47
|
-
if (result.status === "
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
79
|
+
if (result.status === "success") {
|
|
80
|
+
for (const user of result.list.results) {
|
|
81
|
+
console.log(user.id, user.name, user.person.email);
|
|
82
|
+
}
|
|
83
|
+
} else {
|
|
84
|
+
console.error(result.error);
|
|
51
85
|
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`ListUsersArgs` accepts the following options:
|
|
89
|
+
|
|
90
|
+
| Option | Description |
|
|
91
|
+
| --- | --- |
|
|
92
|
+
| `pageSize` | Maximum users per response. Optional integer from 1 to 100. Defaults to 100. |
|
|
93
|
+
| `startCursor` | Optional cursor from the previous response's `next_cursor`. Omit it for the first page. |
|
|
94
|
+
|
|
95
|
+
`users.list()` returns a promise that resolves to a `ListUsersResult`: either `{ status: "success", list }` or `{ status: "error", error }`.
|
|
96
|
+
|
|
97
|
+
On success, `list` is a `NotionUserList` with `results`, `next_cursor`, and `has_more`.
|
|
98
|
+
|
|
99
|
+
Pass `next_cursor` as `startCursor` to request the next page. Use the cursor exactly as returned. Do not parse it or create your own. Stop when `has_more` is false.
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
import { users, type ListUsersArgs } from "@notionhq/custom-blocks";
|
|
103
|
+
|
|
104
|
+
const args: ListUsersArgs = { pageSize: 50 };
|
|
52
105
|
|
|
53
|
-
|
|
54
|
-
const
|
|
55
|
-
|
|
106
|
+
while (true) {
|
|
107
|
+
const result = await users.list(args);
|
|
108
|
+
if (result.status === "error") {
|
|
109
|
+
console.error(result.error);
|
|
110
|
+
break;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
for (const user of result.list.results) {
|
|
114
|
+
console.log(user.id, user.name);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
if (!result.list.has_more || result.list.next_cursor === null) break;
|
|
118
|
+
args.startCursor = result.list.next_cursor;
|
|
56
119
|
}
|
|
57
120
|
```
|
|
58
121
|
|
|
59
|
-
`ListUsersArgs` accepts `pageSize` and `startCursor`; both are optional. `ListUsersResult` resolves to either `{ status: "success", list }` or `{ status: "error", error }`, where `list` is a `NotionUserList` (with `results`, `next_cursor`, `has_more`).
|
|
60
|
-
|
|
61
122
|
## Reading a single user
|
|
62
123
|
|
|
63
124
|
`users.get(userId)` fetches one `NotionUser` by `NotionUserId`:
|
|
@@ -69,14 +130,24 @@ if (result.status === "success") {
|
|
|
69
130
|
}
|
|
70
131
|
```
|
|
71
132
|
|
|
72
|
-
`
|
|
133
|
+
`users.get()` returns a promise that resolves to a `GetUserResult`: either `{ status: "success", user }` or `{ status: "error", error }`.
|
|
134
|
+
|
|
135
|
+
A `people` property can contain both users and groups (`object: "group"`). `users.get()` and `users.list()` only support people. You cannot use these APIs to resolve a group or list its members.
|
|
136
|
+
|
|
137
|
+
Skip group entries when you need a person’s name and avatar. Match the person’s ID against results from `users.list()`. Reuse those results if your UI already lists workspace users. IDs in a `people` property are plain strings. `users.get()` requires a `NotionUserId`, such as an ID from the user APIs.
|
|
138
|
+
|
|
139
|
+
## Permissions
|
|
140
|
+
|
|
141
|
+
A user returned by `users.list()` does not necessarily have access to the current page or data source. Do not use this list to check page or data source permissions.
|
|
142
|
+
|
|
143
|
+
If a request returns `status: "error"`, handle the error before reading `result.user` or `result.list`. See [error handling](./errors.md).
|
|
73
144
|
|
|
74
145
|
## Types
|
|
75
146
|
|
|
76
147
|
- `NotionUser` — the user record returned by `users.get` and inside `NotionUserList.results`.
|
|
77
148
|
- `NotionUserId` — branded string ID for a user.
|
|
78
149
|
- `NotionUserList` — paginated list shape returned by `users.list`.
|
|
79
|
-
- `useCurrentUser()` — hook that returns the
|
|
80
|
-
- `customBlock.getCurrentUser()` — framework-neutral getter for the
|
|
150
|
+
- `useCurrentUser()` — hook that returns the current user's `NotionUser`.
|
|
151
|
+
- `customBlock.getCurrentUser()` — framework-neutral getter for the current user's `NotionUser`.
|
|
81
152
|
- `ListUsersArgs` / `ListUsersResult`.
|
|
82
153
|
- `GetUserResult`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@notionhq/custom-blocks",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"publishConfig": {
|
|
@@ -22,10 +22,6 @@
|
|
|
22
22
|
"import": "./dist/testing.js",
|
|
23
23
|
"types": "./dist/testing.d.ts"
|
|
24
24
|
},
|
|
25
|
-
"./vite": {
|
|
26
|
-
"import": "./vite-plugin/index.js",
|
|
27
|
-
"types": "./vite-plugin/index.d.ts"
|
|
28
|
-
},
|
|
29
25
|
"./bundle": {
|
|
30
26
|
"types": "./bin/notion-custom-blocks/bundle.d.ts",
|
|
31
27
|
"import": "./bin/notion-custom-blocks/bundle.js"
|
|
@@ -43,7 +39,6 @@
|
|
|
43
39
|
"src",
|
|
44
40
|
"bin",
|
|
45
41
|
"docs",
|
|
46
|
-
"vite-plugin",
|
|
47
42
|
"dist"
|
|
48
43
|
],
|
|
49
44
|
"peerDependencies": {
|
|
@@ -931,9 +931,7 @@ export class SandboxBridge {
|
|
|
931
931
|
}
|
|
932
932
|
|
|
933
933
|
updatePage(args: UpdatePageArgs): Promise<UpdatePageResult> {
|
|
934
|
-
|
|
935
|
-
// TODO(custom-blocks): Remove the archived fallback when upgrading to bridge protocol v4.
|
|
936
|
-
const isArchived = args.is_archived ?? args.archived
|
|
934
|
+
const isArchived = args.is_archived
|
|
937
935
|
return new Promise(resolve => {
|
|
938
936
|
if (
|
|
939
937
|
(args.properties === undefined ||
|
|
@@ -1003,7 +1001,7 @@ export class SandboxBridge {
|
|
|
1003
1001
|
properties: resolvedProperties?.properties,
|
|
1004
1002
|
icon: pageUpdateArgs.icon,
|
|
1005
1003
|
cover: pageUpdateArgs.cover,
|
|
1006
|
-
is_archived: pageUpdateArgs.is_archived
|
|
1004
|
+
is_archived: pageUpdateArgs.is_archived,
|
|
1007
1005
|
})
|
|
1008
1006
|
}
|
|
1009
1007
|
|
|
@@ -24,7 +24,6 @@ import {
|
|
|
24
24
|
} from "./SandboxBridge.js"
|
|
25
25
|
|
|
26
26
|
let bridge: SandboxBridge | undefined
|
|
27
|
-
let didWarnAboutPagesDelete = false
|
|
28
27
|
|
|
29
28
|
function getBridge(): SandboxBridge {
|
|
30
29
|
if (!bridge) {
|
|
@@ -146,20 +145,6 @@ export const pages = {
|
|
|
146
145
|
unarchive: (pageId: NotionPageId): Promise<UpdatePageResult> => {
|
|
147
146
|
return getBridge().updatePage({ pageId, is_archived: false })
|
|
148
147
|
},
|
|
149
|
-
|
|
150
|
-
/**
|
|
151
|
-
* @deprecated This method archives the page. It does not move the page to Trash.
|
|
152
|
-
* Use `pages.archive(pageId)` instead.
|
|
153
|
-
*/
|
|
154
|
-
delete: (pageId: NotionPageId): Promise<UpdatePageResult> => {
|
|
155
|
-
if (!didWarnAboutPagesDelete) {
|
|
156
|
-
didWarnAboutPagesDelete = true
|
|
157
|
-
console.warn(
|
|
158
|
-
"[Notion Custom Blocks] DEPRECATED: pages.delete() archives the page. It does not move the page to Trash. Use pages.archive() instead.",
|
|
159
|
-
)
|
|
160
|
-
}
|
|
161
|
-
return getBridge().updatePage({ pageId, is_archived: true })
|
|
162
|
-
},
|
|
163
148
|
}
|
|
164
149
|
|
|
165
150
|
/**
|