@notionhq/custom-blocks 0.1.33 → 0.1.35

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/types.ts"],"names":[],"mappings":"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"}

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.33"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.35"

package/docs/data-sources.md

@@ -41,7 +41,11 @@ 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;
+    sorts?: NotionDataSourceSort[];
+  },
 ): UseDataSourceResult;
 
 type UseDataSourceResult = {
@@ -56,7 +60,46 @@ 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 } },
+    ],
+  },
+  sorts: [{ key: "due", direction: "ascending" }],
+  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.
+
+`sorts` accepts a list of property addresses and directions. Use `key` for a
+semantic property key or `propertyId` for a raw Notion property ID. The SDK
+resolves semantic keys before it sends the bridge request. The host applies
+sorts in array order. The first sort has the highest priority. The list can
+contain up to ten unique properties. Empty values sort last in either
+direction. Sorts currently support title, rich text, number, checkbox, URL,
+email, phone number, date, created time, and last edited time properties.
+Other property types are rejected until their sort values are 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 +204,12 @@ 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`, `filter?: NotionDataSourceFilter`, and `sorts?: NotionDataSourceSort[]`.
+- `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`.
+- `NotionDataSourceSort` — a property address with an `ascending` or `descending` direction.
+- `NotionDataSourceTextFilterOperator`, `NotionDataSourceNumberFilterOperator`, `NotionDataSourceCheckboxFilterOperator`, `NotionDataSourceOptionFilterOperator`, `NotionDataSourceContainsFilterOperator`, and `NotionDataSourceDateFilterOperator` — the operators accepted for each property type.
 
 ### Property schemas
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.1.33",
+	"version": "0.1.35",
 	"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 {
@@ -393,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 = {
@@ -476,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"
 						? {
@@ -499,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,
 						},
 					},
 				}
@@ -672,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
 		}
@@ -680,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,
@@ -691,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,
@@ -699,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
 		}
@@ -716,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,
 				},
 			},
 		}
@@ -730,14 +752,16 @@ 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 } : {}),
+			...(query.sorts !== undefined ? { sorts: query.sorts } : {}),
 		}
 		this.postToHost(outbound)
 	}
 
 	private setDataSourceQueryError(
-		key: string,
+		subscriptionId: string,
 		currentState: DataSourceQueryState,
 		error: CustomBlockQueryDataSourceErrorInfo,
 	) {
@@ -748,18 +772,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
@@ -1054,36 +1093,6 @@ 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
-	}
-	return limit
-}
-
-function makeDataSourceSubscriptionId(args: { key: string }): string {
-	const { key } = args
-	return `data-source:${encodeURIComponent(key)}`
-}
-
 function invalidInitPayloadError(
 	issues: readonly v.BaseIssue<unknown>[],
 ): CustomBlockInitResultErrorInfo {