@notionhq/custom-blocks 0.1.32 → 0.1.34

package/src/bridge/dataSources/query.ts

@@ -0,0 +1,470 @@
+import type { NotionDataSource } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
+import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/ids.js"
+import {
+	customBlockCheckboxFilterOperatorSchema,
+	customBlockContainsFilterOperatorSchema,
+	customBlockDateFilterOperatorSchema,
+	customBlockNumberFilterOperatorSchema,
+	customBlockOptionFilterOperatorSchema,
+	customBlockTextFilterOperatorSchema,
+	type ResolvedCustomBlockDataSourceFilter,
+	type ResolvedCustomBlockDataSourcePropertyFilter,
+} from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
+import * as v from "valibot"
+import type { UseDataSourceOptions } from "../../types.js"
+
+const DEFAULT_DATA_SOURCE_QUERY_LIMIT = 20
+const MAX_DATA_SOURCE_QUERY_LIMIT = 999
+const MAX_DATA_SOURCE_QUERY_FILTER_CHILDREN = 25
+
+export type ResolvedDataSourceQuery = {
+	dataSourceId: NotionDataSourceId
+	limit: number
+	filter?: ResolvedCustomBlockDataSourceFilter
+	identity: string
+}
+
+export type ResolveDataSourceQueryResult =
+	| { status: "error"; error: string }
+	| {
+			status: "ok"
+			dataSource: NotionDataSource
+			query: ResolvedDataSourceQuery
+	  }
+
+export function resolveDataSourceQuery(args: {
+	dataSources: NotionDataSource[]
+	key: string
+	options?: unknown
+	warn?: (message: string) => void
+}): ResolveDataSourceQueryResult {
+	const { dataSources, key, options, warn } = args
+	if (options !== undefined && !isPlainRecord(options)) {
+		return {
+			status: "error",
+			error: "Data source query options must be an object.",
+		}
+	}
+	if (
+		options !== undefined &&
+		Object.keys(options).some(key => !["limit", "filter"].includes(key))
+	) {
+		return {
+			status: "error",
+			error: "Data source query options contain unsupported fields.",
+		}
+	}
+	const dataSource = dataSources.find(entry => entry.key === key)
+	if (dataSource === undefined) {
+		return {
+			status: "error",
+			error: `Unknown data source key "${key}". Known keys: [${dataSources.map(entry => entry.key).join(", ")}].`,
+		}
+	}
+	if (dataSource.collectionPointer === undefined) {
+		return {
+			status: "error",
+			error: `Data source "${key}" has not been mapped to a database yet.`,
+		}
+	}
+
+	const limit = resolveDataSourceQueryLimit(options?.limit, warn)
+	if (limit.status === "error") {
+		return limit
+	}
+	const filter = resolveFilter(options?.filter, dataSource)
+	if (filter.status === "error") {
+		return filter
+	}
+
+	const identity = stableJsonStringify({
+		dataSourceId: dataSource.collectionPointer.id,
+		limit: limit.limit,
+		filter: filter.filter ?? null,
+	})
+	return {
+		status: "ok",
+		dataSource,
+		query: {
+			dataSourceId: dataSource.collectionPointer.id,
+			limit: limit.limit,
+			filter: filter.filter,
+			identity,
+		},
+	}
+}
+
+function resolveDataSourceQueryLimit(
+	limit: unknown,
+	warn: ((message: string) => void) | undefined = console.warn,
+): { status: "ok"; limit: number } | { status: "error"; error: string } {
+	if (limit === undefined) {
+		return { status: "ok", limit: DEFAULT_DATA_SOURCE_QUERY_LIMIT }
+	}
+	if (
+		typeof limit !== "number" ||
+		!Number.isFinite(limit) ||
+		!Number.isInteger(limit) ||
+		limit < 1
+	) {
+		return {
+			status: "error",
+			error: `Data source query limit must be a positive integer between 1 and ${MAX_DATA_SOURCE_QUERY_LIMIT}.`,
+		}
+	}
+	if (limit > MAX_DATA_SOURCE_QUERY_LIMIT) {
+		warn?.(
+			`Data source query limit ${limit} exceeds the maximum of ${MAX_DATA_SOURCE_QUERY_LIMIT}; clamping to ${MAX_DATA_SOURCE_QUERY_LIMIT}.`,
+		)
+		return { status: "ok", limit: MAX_DATA_SOURCE_QUERY_LIMIT }
+	}
+	return { status: "ok", limit }
+}
+
+export function getDataSourceQueryOptionsIdentity(
+	options: UseDataSourceOptions | undefined,
+): string {
+	try {
+		return stableJsonStringify(options ?? {})
+	} catch {
+		return "invalid-data-source-query-options"
+	}
+}
+
+function stableJsonStringify(value: unknown): string {
+	return JSON.stringify(normalizeJsonValue(value))
+}
+
+function resolveFilter(
+	filter: unknown,
+	dataSource: NotionDataSource,
+):
+	| { status: "ok"; filter?: ResolvedCustomBlockDataSourceFilter }
+	| { status: "error"; error: string } {
+	if (filter === undefined) {
+		return { status: "ok" }
+	}
+	if (!isPlainRecord(filter)) {
+		return {
+			status: "error",
+			error: "Data source query filter must be an object.",
+		}
+	}
+	if ("and" in filter) {
+		if (Object.keys(filter).length !== 1 || !Array.isArray(filter.and)) {
+			return {
+				status: "error",
+				error: 'Data source query filter "and" must be an array.',
+			}
+		}
+		if (filter.and.length > MAX_DATA_SOURCE_QUERY_FILTER_CHILDREN) {
+			return {
+				status: "error",
+				error: `Data source query filter "and" may contain at most ${MAX_DATA_SOURCE_QUERY_FILTER_CHILDREN} children.`,
+			}
+		}
+		const and: ResolvedCustomBlockDataSourcePropertyFilter[] = []
+		for (const child of filter.and) {
+			const resolved = resolvePropertyFilter(child, dataSource)
+			if (resolved.status === "error") {
+				return resolved
+			}
+			and.push(resolved.filter)
+		}
+		return { status: "ok", filter: { and } }
+	}
+	return resolvePropertyFilter(filter, dataSource)
+}
+
+function resolvePropertyFilter(
+	filter: unknown,
+	dataSource: NotionDataSource,
+):
+	| { status: "ok"; filter: ResolvedCustomBlockDataSourcePropertyFilter }
+	| { status: "error"; error: string } {
+	if (!isPlainRecord(filter)) {
+		return {
+			status: "error",
+			error: "Data source query property filter must be an object.",
+		}
+	}
+	const property = resolvePropertyAddress(filter, dataSource)
+	if (property.status === "error") {
+		return property
+	}
+	const branchKeys = Object.keys(filter).filter(
+		key => key !== "key" && key !== "propertyId",
+	)
+	if (branchKeys.length !== 1) {
+		return {
+			status: "error",
+			error:
+				"Data source query property filter must contain exactly one property branch.",
+		}
+	}
+	const branch = branchKeys[0]
+	const value = filter[branch]
+	if (!isPlainRecord(value) || Object.keys(value).length !== 1) {
+		return invalidOperator(branch)
+	}
+	if (property.propertyType !== branch) {
+		return {
+			status: "error",
+			error: `Data source query filter branch "${branch}" does not match property type "${property.propertyType}".`,
+		}
+	}
+
+	switch (branch) {
+		case "title": {
+			const parsed = v.safeParse(customBlockTextFilterOperatorSchema, value)
+			return parsed.success
+				? {
+						status: "ok",
+						filter: { propertyId: property.propertyId, title: parsed.output },
+					}
+				: invalidOperator(branch)
+		}
+		case "rich_text": {
+			const parsed = v.safeParse(customBlockTextFilterOperatorSchema, value)
+			return parsed.success
+				? {
+						status: "ok",
+						filter: {
+							propertyId: property.propertyId,
+							rich_text: parsed.output,
+						},
+					}
+				: invalidOperator(branch)
+		}
+		case "url":
+		case "email":
+		case "phone_number": {
+			const parsed = v.safeParse(customBlockTextFilterOperatorSchema, value)
+			if (!parsed.success) {
+				return invalidOperator(branch)
+			}
+			if (branch === "url") {
+				return {
+					status: "ok",
+					filter: { propertyId: property.propertyId, url: parsed.output },
+				}
+			}
+			if (branch === "email") {
+				return {
+					status: "ok",
+					filter: { propertyId: property.propertyId, email: parsed.output },
+				}
+			}
+			return {
+				status: "ok",
+				filter: {
+					propertyId: property.propertyId,
+					phone_number: parsed.output,
+				},
+			}
+		}
+		case "number": {
+			const parsed = v.safeParse(customBlockNumberFilterOperatorSchema, value)
+			if (
+				parsed.success &&
+				Object.values(parsed.output).every(
+					entry => typeof entry !== "number" || Number.isFinite(entry),
+				)
+			) {
+				return {
+					status: "ok",
+					filter: { propertyId: property.propertyId, number: parsed.output },
+				}
+			}
+			return invalidOperator(branch)
+		}
+		case "checkbox": {
+			const parsed = v.safeParse(customBlockCheckboxFilterOperatorSchema, value)
+			return parsed.success
+				? {
+						status: "ok",
+						filter: {
+							propertyId: property.propertyId,
+							checkbox: parsed.output,
+						},
+					}
+				: invalidOperator(branch)
+		}
+		case "select": {
+			const parsed = v.safeParse(customBlockOptionFilterOperatorSchema, value)
+			return parsed.success
+				? {
+						status: "ok",
+						filter: { propertyId: property.propertyId, select: parsed.output },
+					}
+				: invalidOperator(branch)
+		}
+		case "multi_select": {
+			const parsed = v.safeParse(customBlockContainsFilterOperatorSchema, value)
+			return parsed.success
+				? {
+						status: "ok",
+						filter: {
+							propertyId: property.propertyId,
+							multi_select: parsed.output,
+						},
+					}
+				: invalidOperator(branch)
+		}
+		case "status": {
+			const parsed = v.safeParse(customBlockOptionFilterOperatorSchema, value)
+			return parsed.success
+				? {
+						status: "ok",
+						filter: { propertyId: property.propertyId, status: parsed.output },
+					}
+				: invalidOperator(branch)
+		}
+		case "date": {
+			const parsed = v.safeParse(customBlockDateFilterOperatorSchema, value)
+			if (
+				parsed.success &&
+				Object.values(parsed.output).every(
+					entry => entry === true || isValidIsoDate(entry),
+				)
+			) {
+				return {
+					status: "ok",
+					filter: { propertyId: property.propertyId, date: parsed.output },
+				}
+			}
+			return invalidOperator(branch)
+		}
+		default:
+			return {
+				status: "error",
+				error: `Data source query filter branch "${branch}" is not supported.`,
+			}
+	}
+}
+
+function resolvePropertyAddress(
+	value: Record<string, unknown>,
+	dataSource: NotionDataSource,
+):
+	| { status: "ok"; propertyId: string; propertyType: string }
+	| { status: "error"; error: string } {
+	const hasKey = "key" in value
+	const hasPropertyId = "propertyId" in value
+	if (hasKey === hasPropertyId) {
+		return {
+			status: "error",
+			error:
+				"Data source query filters must use exactly one of key or propertyId.",
+		}
+	}
+	let propertyId: string
+	if (hasKey) {
+		if (typeof value.key !== "string") {
+			return {
+				status: "error",
+				error: "Data source query property key must be a string.",
+			}
+		}
+		if (!(value.key in dataSource.propertyIdsByKey)) {
+			return {
+				status: "error",
+				error: `Unknown property key "${value.key}" for data source "${dataSource.key}".`,
+			}
+		}
+		const resolvedPropertyId = dataSource.propertyIdsByKey[value.key]
+		if (resolvedPropertyId === undefined) {
+			return {
+				status: "error",
+				error: `Property key "${value.key}" for data source "${dataSource.key}" is not bound.`,
+			}
+		}
+		propertyId = resolvedPropertyId
+	} else {
+		if (typeof value.propertyId !== "string") {
+			return {
+				status: "error",
+				error: "Data source query propertyId must be a string.",
+			}
+		}
+		propertyId = value.propertyId
+	}
+	const propertySchema = dataSource.propertySchemasById[propertyId]
+	if (propertySchema === undefined) {
+		return {
+			status: "error",
+			error: `Unknown property ID "${propertyId}" for data source "${dataSource.key}".`,
+		}
+	}
+	return {
+		status: "ok",
+		propertyId,
+		propertyType: propertySchema.type,
+	}
+}
+
+function invalidOperator(branch: string): { status: "error"; error: string } {
+	return {
+		status: "error",
+		error: `Data source query filter branch "${branch}" has an invalid operator or value.`,
+	}
+}
+
+function normalizeJsonValue(value: unknown): unknown {
+	if (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "boolean"
+	) {
+		return value
+	}
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) {
+			throw new Error("Data source query values must be finite JSON numbers.")
+		}
+		return value
+	}
+	if (Array.isArray(value)) {
+		return value.map(entry => normalizeJsonValue(entry))
+	}
+	if (isPlainRecord(value)) {
+		const normalized: Record<string, unknown> = {}
+		for (const key of Object.keys(value).sort()) {
+			const child = value[key]
+			if (child !== undefined) {
+				normalized[key] = normalizeJsonValue(child)
+			}
+		}
+		return normalized
+	}
+	throw new Error("Data source query values must be JSON-compatible.")
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		!Array.isArray(value) &&
+		(Object.getPrototypeOf(value) === Object.prototype ||
+			Object.getPrototypeOf(value) === null)
+	)
+}
+
+function isValidIsoDate(value: unknown): boolean {
+	if (typeof value !== "string") {
+		return false
+	}
+	const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value)
+	if (dateOnly !== null) {
+		const [, year, month, day] = dateOnly
+		const date = new Date(
+			Date.UTC(Number(year), Number(month) - 1, Number(day)),
+		)
+		return date.toISOString().slice(0, 10) === value
+	}
+	return (
+		/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+			value,
+		) && Number.isFinite(Date.parse(value))
+	)
+}

package/src/bridge/hostState.ts

@@ -41,17 +41,21 @@ export type InitializedHostState = {
 }
 
 export type DataSourceQueryState = {
+	dataSourceKey: string
 	/** Latest pages from the host as parsed from the bridge. `propertiesByKey` is derived lazily. */
 	items: NotionDataSourcePageBridge[]
 	isLoading: boolean
 	hasMore: boolean
 	error?: CustomBlockQueryDataSourceErrorInfo
-	subscriptionId?: string
 	latestLimit?: number
+	latestQueryIdentity?: string
 }
 
-export function createEmptyDataSourceQueryState(): DataSourceQueryState {
+export function createEmptyDataSourceQueryState(
+	dataSourceKey: string,
+): DataSourceQueryState {
 	return {
+		dataSourceKey,
 		items: [],
 		isLoading: false,
 		hasMore: false,
@@ -97,6 +101,7 @@ export type UpdateDataSourcePageFn = (args: {
 export function getDataSourceQueryView(
 	hostState: CustomBlockHostState,
 	key: string,
+	subscriptionId: string,
 	updateDataSourcePage: UpdateDataSourcePageFn,
 ): DataSourceQueryView {
 	if (hostState.status !== "initialized") {
@@ -104,8 +109,11 @@ export function getDataSourceQueryView(
 	}
 
 	const dataSource = hostState.dataSources.find(entry => entry.key === key)
+	const subscriptionState = hostState.dataSourceState[subscriptionId]
 	const queryState =
-		hostState.dataSourceState[key] ?? createEmptyDataSourceQueryState()
+		subscriptionState?.dataSourceKey === key
+			? subscriptionState
+			: createEmptyDataSourceQueryState(key)
 
 	if (dataSource === undefined) {
 		return {

package/src/bridge/sandboxClient.ts

@@ -68,16 +68,32 @@ export const customBlockHost = {
 }
 
 export const customBlockDataSources = {
-	query: (key: string, options?: UseDataSourceOptions) => {
-		getBridge().queryDataSource(key, options)
+	createSubscriptionId: () => {
+		return getBridge().createDataSourceSubscriptionId()
+	},
+
+	query: (
+		subscriptionId: string,
+		key: string,
+		options?: UseDataSourceOptions,
+	) => {
+		getBridge().queryDataSource(subscriptionId, key, options)
+	},
+
+	release: (subscriptionId: string) => {
+		getBridge().releaseDataSourceSubscription(subscriptionId)
 	},
 
 	getView: (
 		hostState: CustomBlockHostState,
 		key: string,
+		subscriptionId: string,
 	): DataSourceQueryView => {
-		return getDataSourceQueryViewWithBridge(hostState, key, args =>
-			getBridge().updateDataSourcePage(args),
+		return getDataSourceQueryViewWithBridge(
+			hostState,
+			key,
+			subscriptionId,
+			args => getBridge().updateDataSourcePage(args),
 		)
 	},
 }

package/src/react/useDataSource.ts

@@ -1,4 +1,5 @@
-import { useEffect } from "react"
+import { useEffect, useState } from "react"
+import { getDataSourceQueryOptionsIdentity } from "../bridge/dataSources/query.js"
 import { customBlockDataSources } from "../bridge/sandboxClient.js"
 import type { UseDataSourceOptions, UseDataSourceResult } from "../types.js"
 import { useCustomBlockHost } from "./useHostState.js"
@@ -18,7 +19,10 @@ export function useDataSource(
 	options?: UseDataSourceOptions,
 ): UseDataSourceResult {
 	const host = useCustomBlockHost()
-	const limit = options?.limit
+	const [subscriptionId] = useState(() =>
+		customBlockDataSources.createSubscriptionId(),
+	)
+	const optionsIdentity = getDataSourceQueryOptionsIdentity(options)
 	const matchingDataSource =
 		host.status === "initialized"
 			? host.dataSources.find(dataSource => dataSource.key === key)
@@ -30,10 +34,17 @@ export function useDataSource(
 			return
 		}
 
-		customBlockDataSources.query(key, { limit })
-	}, [matchingDataSource, isInitialized, key, limit])
+		customBlockDataSources.query(subscriptionId, key, options)
+	}, [matchingDataSource, isInitialized, key, optionsIdentity, subscriptionId])
 
-	const view = customBlockDataSources.getView(host, key)
+	useEffect(
+		() => () => {
+			customBlockDataSources.release(subscriptionId)
+		},
+		[subscriptionId],
+	)
+
+	const view = customBlockDataSources.getView(host, key, subscriptionId)
 
 	return {
 		items: view.items,

package/src/types.ts

@@ -24,6 +24,14 @@ import type {
 	ListUsersMessage,
 	ListUsersResultMessage,
 } from "@notionhq/custom-blocks-protocol/messages/listUsers.js"
+import type {
+	CustomBlockCheckboxFilterOperator,
+	CustomBlockContainsFilterOperator,
+	CustomBlockDateFilterOperator,
+	CustomBlockNumberFilterOperator,
+	CustomBlockOptionFilterOperator,
+	CustomBlockTextFilterOperator,
+} from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
 import type { CustomBlockQueryDataSourceErrorInfo } from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
 import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/messages/updatePage.js"
 import type {
@@ -116,6 +124,40 @@ export type NotionDataSourcePageUpdateInput = NotionDataSourcePageUpdateArgs
  */
 export type NotionDataSourcePageUpdateResult = UpdatePageResult
 
+export type NotionDataSourceTextFilterOperator = CustomBlockTextFilterOperator
+export type NotionDataSourceNumberFilterOperator =
+	CustomBlockNumberFilterOperator
+export type NotionDataSourceCheckboxFilterOperator =
+	CustomBlockCheckboxFilterOperator
+export type NotionDataSourceOptionFilterOperator =
+	CustomBlockOptionFilterOperator
+export type NotionDataSourceContainsFilterOperator =
+	CustomBlockContainsFilterOperator
+export type NotionDataSourceDateFilterOperator = CustomBlockDateFilterOperator
+
+export type NotionDataSourcePropertyAddress =
+	| { key: string; propertyId?: never }
+	| { propertyId: string; key?: never }
+
+export type NotionDataSourcePropertyFilter = NotionDataSourcePropertyAddress &
+	(
+		| { title: NotionDataSourceTextFilterOperator }
+		| { rich_text: NotionDataSourceTextFilterOperator }
+		| { url: NotionDataSourceTextFilterOperator }
+		| { email: NotionDataSourceTextFilterOperator }
+		| { phone_number: NotionDataSourceTextFilterOperator }
+		| { number: NotionDataSourceNumberFilterOperator }
+		| { checkbox: NotionDataSourceCheckboxFilterOperator }
+		| { select: NotionDataSourceOptionFilterOperator }
+		| { multi_select: NotionDataSourceContainsFilterOperator }
+		| { status: NotionDataSourceOptionFilterOperator }
+		| { date: NotionDataSourceDateFilterOperator }
+	)
+
+export type NotionDataSourceFilter =
+	| NotionDataSourcePropertyFilter
+	| { and: NotionDataSourcePropertyFilter[] }
+
 /**
  * Return shape of `useDataSource`.
  *
@@ -157,6 +199,11 @@ export type UseDataSourceOptions = {
 	 * Maximum number of rows to request from the host. Defaults to 20.
 	 */
 	limit?: number
+	/**
+	 * Optional property filter. The SDK resolves semantic property keys before
+	 * it sends the query to the host.
+	 */
+	filter?: NotionDataSourceFilter
 }
 
 /**