@notionhq/custom-blocks 0.1.32 → 0.1.34

package/docs/data-sources.md

@@ -41,7 +41,10 @@ Use `row.update(...)` whenever you already have a row in hand. For pages you don
 ```ts
 function useDataSource(
   key: string,
-  options?: { limit?: number },
+  options?: {
+    limit?: number;
+    filter?: NotionDataSourceFilter;
+  },
 ): UseDataSourceResult;
 
 type UseDataSourceResult = {
@@ -56,7 +59,36 @@ type UseDataSourceResult = {
 };
 ```
 
-Reads the data source mapped to `key`. `limit` defaults to 20 and is capped at 999. To show more rows, keep the desired limit in your own component state and pass the larger value back into `useDataSource(key, { limit })`. `propertyIdsByKey` maps manifest property keys to raw Notion property IDs; unbound keys map to `undefined`. `propertySchemasByKey` exposes the corresponding schemas and is likewise `undefined` for declared-but-unbound slots.
+Reads the data source mapped to `key`. The SDK uses a default `limit` of 20 and caps it at 999. To request more rows, store the limit in component state and pass it to `useDataSource` again. Each request is bounded. The hook does not provide cursor pagination.
+
+`filter` accepts one property condition or one shallow `and` group. Use `key` for a semantic property key. Use `propertyId` for a raw Notion property ID. The SDK resolves semantic keys before it sends the bridge request. The SDK reports local errors for unknown or unbound keys, property-type mismatches, unsupported filter fields, invalid operators, and invalid values.
+
+```tsx
+const query = useDataSource("tasks", {
+  filter: {
+    and: [
+      { key: "title", title: { contains: "launch" } },
+      { key: "done", checkbox: { equals: false } },
+    ],
+  },
+  limit: 50,
+});
+```
+
+Filters support these property types:
+
+- Text properties: `title`, `rich_text`, `url`, `email`, and `phone_number`. They support `equals`, `does_not_equal`, `contains`, `does_not_contain`, `starts_with`, `ends_with`, `is_empty`, and `is_not_empty`.
+- `number`: `equals`, `does_not_equal`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to`, `is_empty`, and `is_not_empty`.
+- `checkbox`: `equals` and `does_not_equal`.
+- `select` and `status`: `equals`, `does_not_equal`, `is_empty`, and `is_not_empty`.
+- `multi_select`: `contains`, `contains_all`, `does_not_contain`, `is_empty`, and `is_not_empty`.
+- `date`: `equals`, `before`, `after`, `on_or_before`, `on_or_after`, `is_empty`, and `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.
+
+The `and` group can contain up to 25 conditions. An empty group is valid. Nested groups and `or` groups are not supported.
+
+`propertyIdsByKey` maps manifest property keys to raw Notion property IDs; unbound keys map to `undefined`. `propertySchemasByKey` exposes the corresponding schemas and is likewise `undefined` for declared-but-unbound slots.
 
 Query failures follow the SDK's [error-handling contract](./errors.md).
 
@@ -161,7 +193,11 @@ export function ScoreList() {
 - `NotionDataSourcePageUpdateArgs` / `UpdatePageResult` — arguments and result for the per-page `update` helper.
 - `NotionDataSourcePageUpdateInput` — deprecated alias for `NotionDataSourcePageUpdateArgs`.
 - `NotionDataSourcePageUpdateResult` — deprecated alias for `UpdatePageResult`.
-- `UseDataSourceOptions` — options accepted by `useDataSource`, currently `{ limit?: number }`.
+- `UseDataSourceOptions` — options accepted by `useDataSource`: `limit?: number` and `filter?: NotionDataSourceFilter`.
+- `NotionDataSourceFilter` — one property condition or one shallow `and` group.
+- `NotionDataSourcePropertyFilter` — one property address combined with a type-specific operator.
+- `NotionDataSourcePropertyAddress` — either a semantic property `key` or a raw `propertyId`.
+- `NotionDataSourceTextFilterOperator`, `NotionDataSourceNumberFilterOperator`, `NotionDataSourceCheckboxFilterOperator`, `NotionDataSourceOptionFilterOperator`, `NotionDataSourceContainsFilterOperator`, and `NotionDataSourceDateFilterOperator` — the operators accepted for each property type.
 
 ### Property schemas
 

package/docs/errors.md

@@ -39,6 +39,22 @@ Unlike request helpers, `initCustomBlock` rejects with `CustomBlockInitializatio
 
 `CustomBlockInitializationErrorInfo` is the matching `{ code, message, isRetryable }` object type.
 
+Initialization errors have direction-specific meanings:
+
+- `invalid_connect_payload` means that the host could not parse the SDK's
+  `connect` message. The host sends this code in `init.error` when it can read
+  the `initializationId`.
+- `invalid_init_payload` means that the SDK could not parse the host's `init`
+  message. The SDK sends this code in `initResult.error` when it can read the
+  expected `initializationId`.
+- `invalid_init_bindings` means that the SDK could not apply the data source
+  bindings in the host's valid `init` message. The SDK sends this code in
+  `initResult.error`.
+- `invalid_init_result_payload` means that the host could not parse the SDK's
+  `initResult`. This is a host-local error. The SDK does not send this code.
+- `no_init_result` means that the host did not receive a valid `initResult`
+  before its timeout.
+
 See [Lifecycle and initialization](./lifecycle.md) for initialization-specific error codes.
 
 ## Handling errors

package/docs/lifecycle.md

@@ -1,27 +1,65 @@
 # Lifecycle
 
-The SDK ↔ host handshake, the React wrapper that runs it, and the auto-resize hook that keeps the iframe in sync with your content.
-
-## Handshake
-
-`initCustomBlock()` handles three messages:
-
-1. The SDK sends `connect` with a new initialization ID and version information.
-2. The host sends `init`. It includes the same ID, the manifest, block context, current user, and data source bindings.
-3. The SDK sends `initResult` with the ID and the initial block height.
-
-The promise resolves when the SDK applies the host state. Await it before React renders so hooks read initialized state. The SDK sends `initResult` after the initial render.
-
-- Rejects with `CustomBlockInitializationError` code `init_timeout` if the host doesn't respond.
-- In a top-level browser tab (no parent frame), rejects with `NotInIframeError` code `not_in_iframe`. `<NotionCustomBlock>` catches this, seeds placeholders, and renders `children` behind a warning banner so dev-time previews still work.
-- After init, compatible hosts use `*Changed` events (e.g. `themeChanged`, `contrastModeChanged`, `parentChanged`, `dataSourcesChanged`) to push updates and re-render the relevant hooks.
-- `initCustomBlock` is idempotent; subsequent calls return the same promise.
+The SDK and host use a three-message `postMessage` handshake to initialize
+a custom block.
+
+This handshake can be completed with one of these APIs:
+
+- `<NotionCustomBlock>` for most React blocks. It starts initialization and
+  renders `children` after the host state is ready.
+- `useCustomBlockInit()` for React blocks that need to control loading and
+  error states.
+- `initCustomBlock()` for framework-neutral code or code that must await
+  initialization before it renders.
+
+Custom bridge integrations can also handle the `postMessage` wire messages
+directly. This is advanced usage for host or integration authors.
+
+## Initialization protocol message
+
+The full `postMessage` handshake is:
+
+1. The SDK sends `connect` with a new `initializationId` and version
+   information.
+2. The host sends `init` with the same `initializationId`, the manifest, data source bindings,
+   and additional block and app context.
+3. The SDK validates and applies `init`, renders the initial content, and sends
+   `initResult` with the same `initializationId` and the initial block height.
+
+Both sides must check that the `initializationId` matches. The SDK ignores an
+`init` with a different ID. It sends `initResult` only after it applies a
+matching `init`.
+
+The initialization promise resolves after the SDK applies the host state.
+Await it before rendering code that reads initialized state. The SDK sends
+`initResult` after the initial render.
+
+- The promise rejects with `CustomBlockInitializationError` code
+  `init_timeout` if the host does not send a usable `init`.
+- If a matching `init` is malformed, the SDK sends `initResult.error` with code
+  `invalid_init_payload` and rejects with the same structured error.
+- If the host sends incomplete or invalid data source bindings, the SDK sends
+  `initResult.error` with code `invalid_init_bindings` and rejects with the same
+  structured error.
+- If the SDK cannot correlate a malformed `init` to the handshake, it sends
+  `invalidHostMessage` when safe.
+- After initialization, compatible hosts use `*Changed` messages to push live
+  updates.
+- `initCustomBlock()` is idempotent. Later calls return the same promise.
+
+## Rendering inside a host
+
+The SDK expects the custom block to run inside an iframe. In a top-level
+browser tab, initialization rejects with `NotInIframeError` code
+`not_in_iframe`.
+
+`<NotionCustomBlock>` catches this error and renders a standalone preview with
+a warning. This supports local development when no host is available.
 
 ## Sizing
 
-All blocks resize to fit their content. The Notion app limits block height to 10,000 pixels.
-
-To set a shorter height, set `max-height` and `overflow-y` on `#root`:
+Custom blocks resize to fit their content by default. To set a shorter height, set
+`max-height` and `overflow-y` on `#root`:
 
 ```css
 #root {
@@ -30,9 +68,25 @@ To set a shorter height, set `max-height` and `overflow-y` on `#root`:
 }
 ```
 
+The Notion app enforces a maximum custom block height of 10,000 pixels.
+
+The SDK measures the `#root` element and sends its initial height in
+`initResult.success`. It sends later height changes in `resize` messages. The
+host uses these messages to keep the iframe height in sync.
+
+Using `<NotionCustomBlock>` enables this behavior automatically. Use
+`customBlock.autoResize()` for a custom, framework-neutral initialization wrapper.
+
 ## API
 
-Import framework-neutral APIs from `@notionhq/custom-blocks`; import React hooks and components from `@notionhq/custom-blocks/react`. The runtime APIs below assume `initCustomBlock()` has resolved — initialized-only hooks and `customBlock` getters throw if called before that. Inside `<NotionCustomBlock>` (or past the `isLoaded` gate of `useCustomBlockInit`), single-value hooks return non-nullable values.
+Import framework-neutral APIs from `@notionhq/custom-blocks`. Import React
+hooks and components from `@notionhq/custom-blocks/react`.
+
+The APIs below require successful initialization unless stated otherwise.
+Initialized-only hooks and `customBlock` getters throw before
+`initCustomBlock()` resolves. Inside `<NotionCustomBlock>`, or after the
+`isLoaded` gate of `useCustomBlockInit`, single-value hooks return non-nullable
+values.
 
 ### `<NotionCustomBlock>`
 

package/package.json

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

package/src/bridge/SandboxBridge.ts

@@ -52,6 +52,7 @@ import {
 	NOTION_DARK_BACKGROUND_BASE,
 	NOTION_LIGHT_BACKGROUND_BASE,
 } from "./appearance.js"
+import { resolveDataSourceQuery } from "./dataSources/query.js"
 import { resolveDataSources } from "./dataSources/resolve.js"
 import { resolvePropertyWriteMapForDataSource } from "./dataSources/resolveProperty.js"
 import {
@@ -258,6 +259,16 @@ export class SandboxBridge {
 				parsed.issues,
 			)
 			const incomingType = readIncomingType(event.data)
+			if (
+				!this.hasReceivedInit &&
+				incomingType === "init" &&
+				this.initializationId !== undefined &&
+				readInitializationId(event.data) === this.initializationId
+			) {
+				this.hasReceivedInit = true
+				this.sendInitResultError(invalidInitPayloadError(parsed.issues))
+				return
+			}
 			// Loop guard: never NACK a NACK. Excludes both directions —
 			// `invalidSandboxMessage` is what the host normally sends, but
 			// a buggy host that echoes our own `invalidHostMessage` back
@@ -383,12 +394,14 @@ export class SandboxBridge {
 					nextBindings,
 				})
 				this.latestDataSourceBindings = nextBindings
-				// Drop cached query state for keys that no longer exist in the mapping.
+				// Drop cached query state for subscriptions whose key no longer exists.
 				const nextKeys = new Set(dataSources.map(s => s.key))
 				const prunedState: Record<string, DataSourceQueryState> = {}
-				for (const [key, state] of Object.entries(hostState.dataSourceState)) {
-					if (nextKeys.has(key)) {
-						prunedState[key] = state
+				for (const [subscriptionId, state] of Object.entries(
+					hostState.dataSourceState,
+				)) {
+					if (nextKeys.has(state.dataSourceKey)) {
+						prunedState[subscriptionId] = state
 					}
 				}
 				this.hostState = {
@@ -466,13 +479,10 @@ export class SandboxBridge {
 			}
 
 			case "queryDataSourceResult": {
-				const queryEntry = Object.entries(hostState.dataSourceState).find(
-					([, state]) => state.subscriptionId === message.subscriptionId,
-				)
-				if (queryEntry === undefined) {
+				const currentState = hostState.dataSourceState[message.subscriptionId]
+				if (currentState === undefined) {
 					return
 				}
-				const [key, currentState] = queryEntry
 				const queryResult =
 					message.status === "error"
 						? {
@@ -489,13 +499,14 @@ export class SandboxBridge {
 					...hostState,
 					dataSourceState: {
 						...hostState.dataSourceState,
-						[key]: {
+						[message.subscriptionId]: {
+							dataSourceKey: currentState.dataSourceKey,
 							items: queryResult.items,
 							isLoading: false,
 							hasMore: queryResult.hasMore,
 							error: queryResult.error,
-							subscriptionId: message.subscriptionId,
 							latestLimit: currentState.latestLimit,
+							latestQueryIdentity: currentState.latestQueryIdentity,
 						},
 					},
 				}
@@ -548,6 +559,25 @@ export class SandboxBridge {
 		this.flushPendingOutboundMessages()
 	}
 
+	private sendInitResultError(error: CustomBlockInitResultErrorInfo) {
+		if (this.hasSentInitResult || this.initializationId === undefined) {
+			return
+		}
+		const result: InitResultMessage = {
+			type: "initResult",
+			initializationId: this.initializationId,
+			status: "error",
+			error,
+		}
+		this.hasSentInitResult = true
+		this.postToHost(result)
+		if (this.rejectInit) {
+			this.rejectInit(new CustomBlockInitializationError(error))
+			this.resolveInit = undefined
+			this.rejectInit = undefined
+		}
+	}
+
 	private applyInit(message: InitMessage, postResult: boolean) {
 		if (postResult) {
 			this.isMockState = false
@@ -581,18 +611,7 @@ export class SandboxBridge {
 			: resolveMockDataSources(this.latestDataSourceBindings)
 		const bindingError = getInitBindingError(message.manifest, dataSources)
 		if (postResult && bindingError !== undefined) {
-			const result: InitResultMessage = {
-				type: "initResult",
-				initializationId: message.initializationId,
-				status: "error",
-				error: bindingError,
-			}
-			this.postToHost(result)
-			if (this.rejectInit) {
-				this.rejectInit(new CustomBlockInitializationError(bindingError))
-				this.resolveInit = undefined
-				this.rejectInit = undefined
-			}
+			this.sendInitResultError(bindingError)
 			return
 		}
 		this.hostState = {
@@ -654,7 +673,15 @@ export class SandboxBridge {
 		}
 	}
 
-	queryDataSource(key: string, options: UseDataSourceOptions = {}) {
+	createDataSourceSubscriptionId(): string {
+		return `data-source:${globalThis.crypto.randomUUID()}`
+	}
+
+	queryDataSource(
+		subscriptionId: string,
+		key: string,
+		options: UseDataSourceOptions = {},
+	) {
 		if (this.hostState.status !== "initialized") {
 			return
 		}
@@ -662,10 +689,13 @@ export class SandboxBridge {
 		const dataSource = this.hostState.dataSources.find(
 			entry => entry.key === key,
 		)
+		const subscriptionState = this.hostState.dataSourceState[subscriptionId]
 		const currentState =
-			this.hostState.dataSourceState[key] ?? createEmptyDataSourceQueryState()
+			subscriptionState?.dataSourceKey === key
+				? subscriptionState
+				: createEmptyDataSourceQueryState(key)
 		if (dataSource === undefined) {
-			this.setDataSourceQueryError(key, currentState, {
+			this.setDataSourceQueryError(subscriptionId, currentState, {
 				code: "unknown_data_source_key",
 				message: `Unknown data source key "${key}". Known keys: [${this.hostState.dataSources.map(entry => entry.key).join(", ")}].`,
 				isRetryable: false,
@@ -673,7 +703,7 @@ export class SandboxBridge {
 			return
 		}
 		if (dataSource.collectionPointer === undefined) {
-			this.setDataSourceQueryError(key, currentState, {
+			this.setDataSourceQueryError(subscriptionId, currentState, {
 				code: "unmapped_data_source",
 				message: `Data source "${key}" has not been mapped to a database yet.`,
 				isRetryable: false,
@@ -681,15 +711,24 @@ export class SandboxBridge {
 			return
 		}
 
-		const limit = resolveDataSourceQueryLimit(options.limit)
-		const subscriptionId = makeDataSourceSubscriptionId({
+		const resolvedQuery = resolveDataSourceQuery({
+			dataSources: this.hostState.dataSources,
 			key,
+			options,
 		})
+		if (resolvedQuery.status === "error") {
+			this.setDataSourceQueryError(subscriptionId, currentState, {
+				code: "invalid_data_source_query",
+				message: resolvedQuery.error,
+				isRetryable: false,
+			})
+			return
+		}
+		const query = resolvedQuery.query
 
 		if (
 			currentState.isLoading &&
-			currentState.subscriptionId === subscriptionId &&
-			currentState.latestLimit === limit
+			currentState.latestQueryIdentity === query.identity
 		) {
 			return
 		}
@@ -698,12 +737,13 @@ export class SandboxBridge {
 			...this.hostState,
 			dataSourceState: {
 				...this.hostState.dataSourceState,
-				[key]: {
+				[subscriptionId]: {
 					...currentState,
+					dataSourceKey: key,
 					isLoading: true,
 					error: undefined,
-					subscriptionId,
-					latestLimit: limit,
+					latestLimit: query.limit,
+					latestQueryIdentity: query.identity,
 				},
 			},
 		}
@@ -712,14 +752,15 @@ export class SandboxBridge {
 		const outbound: QueryDataSourceMessage = {
 			type: "queryDataSource",
 			subscriptionId,
-			dataSourceId: dataSource.collectionPointer.id,
-			limit,
+			dataSourceId: query.dataSourceId,
+			limit: query.limit,
+			...(query.filter !== undefined ? { filter: query.filter } : {}),
 		}
 		this.postToHost(outbound)
 	}
 
 	private setDataSourceQueryError(
-		key: string,
+		subscriptionId: string,
 		currentState: DataSourceQueryState,
 		error: CustomBlockQueryDataSourceErrorInfo,
 	) {
@@ -730,18 +771,33 @@ export class SandboxBridge {
 			...this.hostState,
 			dataSourceState: {
 				...this.hostState.dataSourceState,
-				[key]: {
+				[subscriptionId]: {
 					...currentState,
 					isLoading: false,
 					error,
-					subscriptionId: undefined,
 					latestLimit: undefined,
+					latestQueryIdentity: undefined,
 				},
 			},
 		}
 		this.notify()
 	}
 
+	releaseDataSourceSubscription(subscriptionId: string) {
+		if (
+			this.hostState.status !== "initialized" ||
+			this.hostState.dataSourceState[subscriptionId] === undefined
+		) {
+			return
+		}
+		const { [subscriptionId]: _, ...dataSourceState } =
+			this.hostState.dataSourceState
+		this.hostState = {
+			...this.hostState,
+			dataSourceState,
+		}
+	}
+
 	postResize(height: number) {
 		if (typeof window === "undefined") {
 			return
@@ -1036,34 +1092,26 @@ function reuseDataSourcesForUnchangedBindings(args: {
 	})
 }
 
-// The default number of items to return in a live snapshot response if no limit is provided.
-const DEFAULT_DATA_SOURCE_QUERY_LIMIT = 20
-
-// The maximum number of items to return in a single live snapshot response.
-const MAX_DATA_SOURCE_QUERY_LIMIT = 999
-
-function resolveDataSourceQueryLimit(limit: number | undefined): number {
-	if (limit === undefined) {
-		return DEFAULT_DATA_SOURCE_QUERY_LIMIT
-	}
-	if (!Number.isFinite(limit) || !Number.isInteger(limit) || limit < 1) {
-		console.warn(
-			`[custom-blocks-sdk] useDataSource limit must be a positive integer; using ${DEFAULT_DATA_SOURCE_QUERY_LIMIT}.`,
-		)
-		return DEFAULT_DATA_SOURCE_QUERY_LIMIT
-	}
-	if (limit > MAX_DATA_SOURCE_QUERY_LIMIT) {
-		console.warn(
-			`[custom-blocks-sdk] useDataSource limit is capped at ${MAX_DATA_SOURCE_QUERY_LIMIT}.`,
-		)
-		return MAX_DATA_SOURCE_QUERY_LIMIT
+function invalidInitPayloadError(
+	issues: readonly v.BaseIssue<unknown>[],
+): CustomBlockInitResultErrorInfo {
+	return {
+		code: "invalid_init_payload",
+		message: formatInvalidHostReason("init", issues),
+		isRetryable: false,
 	}
-	return limit
 }
 
-function makeDataSourceSubscriptionId(args: { key: string }): string {
-	const { key } = args
-	return `data-source:${encodeURIComponent(key)}`
+function readInitializationId(data: unknown): string | undefined {
+	if (
+		typeof data === "object" &&
+		data !== null &&
+		"initializationId" in data &&
+		typeof data.initializationId === "string"
+	) {
+		return data.initializationId
+	}
+	return undefined
 }
 
 function getInitBindingError(