@notionhq/custom-blocks 0.1.42 → 0.1.44

package/src/bridge/SandboxBridge.ts

@@ -32,6 +32,7 @@ import type { ListUsersMessage } from "@notionhq/custom-blocks-protocol/messages
 import type { QueryDataSourceMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
 import type { CustomBlockQueryDataSourceErrorInfo } from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
 import type { ResizeMessage } from "@notionhq/custom-blocks-protocol/messages/resize.js"
+import type { UnsubscribeDataSourceQueryMessage } from "@notionhq/custom-blocks-protocol/messages/unsubscribeDataSourceQuery.js"
 import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/messages/updatePage.js"
 import { CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION } from "@notionhq/custom-blocks-protocol/protocolVersion.js"
 import type { NotionTheme } from "@notionhq/custom-blocks-protocol/theme.js"
@@ -40,6 +41,7 @@ import { globalPrimedResponsesCache } from "../testing.js"
 import type {
 	CreatePageArgs,
 	CreatePageResult,
+	DataSourceQueryOptions,
 	GetPageResult,
 	GetUserResult,
 	ListUsersArgs,
@@ -48,7 +50,6 @@ import type {
 	NotionUserId,
 	UpdatePageArgs,
 	UpdatePageResult,
-	UseDataSourceOptions,
 } from "../types.js"
 import { unreachable } from "../utils.js"
 import { CUSTOM_BLOCKS_SDK_VERSION } from "../version.js"
@@ -65,6 +66,7 @@ import {
 	type DataSourceQueryState,
 } from "./hostState.js"
 import type { ManifestLoadResult } from "./loadManifest.js"
+import { notifyListener } from "./notifyListener.js"
 import { PendingRequests } from "./pendingRequests.js"
 
 /**
@@ -88,6 +90,14 @@ const RESPONSE_TYPE_BY_REQUEST = new Map([
 
 const INIT_RESULT_TIMER_FALLBACK_MS = 100
 
+export type QueryDataSourceArgs = {
+	subscriptionId: string
+	key: string
+	options?: DataSourceQueryOptions
+	/** Send the query even if an identical query is already loading. */
+	forceRequery?: boolean
+}
+
 export class SandboxBridge {
 	private hostState: CustomBlockHostState = {
 		status: "uninitialized",
@@ -281,7 +291,7 @@ export class SandboxBridge {
 
 	private notify = () => {
 		for (const listener of this.listeners) {
-			listener()
+			notifyListener(listener)
 		}
 	}
 
@@ -437,15 +447,27 @@ export class SandboxBridge {
 					nextBindings,
 				})
 				this.latestDataSourceBindings = nextBindings
-				// Drop cached query state for subscriptions whose key no longer exists.
-				const nextKeys = new Set(dataSources.map(s => s.key))
+				// Preserve rows only while the key still refers to the same backing data source.
+				const previousSourcesByKey = new Map(
+					hostState.dataSources.map(source => [source.key, source]),
+				)
+				const nextSourcesByKey = new Map(
+					dataSources.map(source => [source.key, source]),
+				)
 				const prunedState: Record<string, DataSourceQueryState> = {}
 				for (const [subscriptionId, state] of Object.entries(
 					hostState.dataSourceState,
 				)) {
-					if (nextKeys.has(state.dataSourceKey)) {
-						prunedState[subscriptionId] = state
+					const nextSource = nextSourcesByKey.get(state.dataSourceKey)
+					if (nextSource === undefined) {
+						continue
 					}
+					const previousSource = previousSourcesByKey.get(state.dataSourceKey)
+					prunedState[subscriptionId] =
+						previousSource?.collectionPointer?.id ===
+						nextSource.collectionPointer?.id
+							? state
+							: createEmptyDataSourceQueryState(state.dataSourceKey)
 				}
 				this.hostState = {
 					...hostState,
@@ -720,11 +742,12 @@ export class SandboxBridge {
 		return `data-source:${globalThis.crypto.randomUUID()}`
 	}
 
-	queryDataSource(
-		subscriptionId: string,
-		key: string,
-		options: UseDataSourceOptions = {},
-	) {
+	queryDataSource({
+		subscriptionId,
+		key,
+		options = {},
+		forceRequery = false,
+	}: QueryDataSourceArgs) {
 		if (this.hostState.status !== "initialized") {
 			return
 		}
@@ -770,6 +793,7 @@ export class SandboxBridge {
 		const query = resolvedQuery.query
 
 		if (
+			!forceRequery &&
 			currentState.isLoading &&
 			currentState.latestQueryIdentity === query.identity
 		) {
@@ -790,8 +814,6 @@ export class SandboxBridge {
 				},
 			},
 		}
-		this.notify()
-
 		const outbound: QueryDataSourceMessage = {
 			type: "queryDataSource",
 			subscriptionId,
@@ -801,6 +823,7 @@ export class SandboxBridge {
 			...(query.sorts !== undefined ? { sorts: query.sorts } : {}),
 		}
 		this.postToHost(outbound)
+		this.notify()
 	}
 
 	private setDataSourceQueryError(
@@ -840,6 +863,11 @@ export class SandboxBridge {
 			...this.hostState,
 			dataSourceState,
 		}
+		const outbound: UnsubscribeDataSourceQueryMessage = {
+			type: "unsubscribeDataSourceQuery",
+			subscriptionId,
+		}
+		this.postToHost(outbound)
 	}
 
 	postResize(height: number) {
@@ -923,20 +951,22 @@ export class SandboxBridge {
 	}
 
 	updatePage(args: UpdatePageArgs): Promise<UpdatePageResult> {
+		// Prefer is_archived over the deprecated archived argument.
+		// TODO(custom-blocks): Remove the archived fallback when upgrading to bridge protocol v4.
+		const isArchived = args.is_archived ?? args.archived
 		return new Promise(resolve => {
 			if (
 				(args.properties === undefined ||
 					Object.keys(args.properties).length === 0) &&
 				args.icon === undefined &&
 				args.cover === undefined &&
-				args.archived === undefined
+				isArchived === undefined
 			) {
 				resolve({
 					status: "error",
 					error: {
 						code: "invalid_page_update",
-						message:
-							"updatePage requires at least one of: properties, icon, cover, archived.",
+						message: "updatePage requires at least one property.",
 						isRetryable: false,
 					},
 				})
@@ -958,8 +988,8 @@ export class SandboxBridge {
 			if (args.cover !== undefined) {
 				outbound.cover = args.cover
 			}
-			if (args.archived !== undefined) {
-				outbound.archived = args.archived
+			if (isArchived !== undefined) {
+				outbound.archived = isArchived
 			}
 			this.postToHost(outbound)
 		})
@@ -993,7 +1023,7 @@ export class SandboxBridge {
 			properties: resolvedProperties?.properties,
 			icon: pageUpdateArgs.icon,
 			cover: pageUpdateArgs.cover,
-			archived: pageUpdateArgs.archived,
+			is_archived: pageUpdateArgs.is_archived ?? pageUpdateArgs.archived,
 		})
 	}
 

package/src/bridge/dataSources/subscribe.ts

@@ -0,0 +1,97 @@
+import type { SubscribeToDataSourceArgs } from "../../types.js"
+import type {
+	CustomBlockHostState,
+	InitializedHostState,
+} from "../hostState.js"
+import { notifyListener } from "../notifyListener.js"
+import { customBlockDataSources, customBlockHost } from "../sandboxClient.js"
+
+export function subscribeToDataSource({
+	key,
+	onSnapshot,
+	options: providedOptions = {},
+}: SubscribeToDataSourceArgs): () => void {
+	const options = structuredClone(providedOptions)
+	const subscriptionId = customBlockDataSources.createSubscriptionId()
+	let active = true
+	let lastSnapshotInputs:
+		| {
+				status: CustomBlockHostState["status"]
+				dataSource: InitializedHostState["dataSources"][number] | undefined
+				queryState: InitializedHostState["dataSourceState"][string] | undefined
+		  }
+		| undefined
+	let lastMatchingSignature: string | null | undefined
+
+	const deliverSnapshotIfChanged = (
+		hostState: CustomBlockHostState,
+		dataSource: InitializedHostState["dataSources"][number] | undefined,
+		queryState: InitializedHostState["dataSourceState"][string] | undefined,
+	) => {
+		if (
+			lastSnapshotInputs !== undefined &&
+			lastSnapshotInputs.status === hostState.status &&
+			lastSnapshotInputs.dataSource === dataSource &&
+			lastSnapshotInputs.queryState === queryState
+		) {
+			return
+		}
+		const snapshot = customBlockDataSources.getView(
+			hostState,
+			key,
+			subscriptionId,
+		)
+		// Record inputs before calling consumer code, which can trigger another notification.
+		lastSnapshotInputs = { status: hostState.status, dataSource, queryState }
+		notifyListener(() => onSnapshot(snapshot))
+	}
+
+	const handleHostChange = () => {
+		if (!active) {
+			return
+		}
+		const hostState = customBlockHost.getState()
+		if (hostState.status !== "initialized") {
+			deliverSnapshotIfChanged(hostState, undefined, undefined)
+			return
+		}
+
+		const dataSource = hostState.dataSources.find(source => source.key === key)
+		const signature =
+			dataSource === undefined ? null : JSON.stringify(dataSource)
+		if (signature !== lastMatchingSignature) {
+			const forceRequery = lastMatchingSignature !== undefined
+			lastMatchingSignature = signature
+			// Querying updates SDK state and calls this listener again.
+			customBlockDataSources.query({
+				subscriptionId,
+				key,
+				options,
+				forceRequery,
+			})
+			return
+		}
+		deliverSnapshotIfChanged(
+			hostState,
+			dataSource,
+			hostState.dataSourceState[subscriptionId],
+		)
+	}
+
+	const unsubscribeHost = customBlockHost.subscribe(handleHostChange)
+	try {
+		handleHostChange()
+	} catch (error) {
+		unsubscribeHost()
+		customBlockDataSources.release(subscriptionId)
+		throw error
+	}
+	return () => {
+		if (!active) {
+			return
+		}
+		active = false
+		unsubscribeHost()
+		customBlockDataSources.release(subscriptionId)
+	}
+}

package/src/bridge/hostState.ts

@@ -139,18 +139,21 @@ export function getDataSourceQueryView(
 			propertiesByKey[key] =
 				propertyId === undefined ? undefined : entry.propertiesById[propertyId]
 		}
+		const update = (args: NotionDataSourcePageUpdateArgs) =>
+			updateDataSourcePage({
+				dataSource,
+				pageId: entry.id,
+				pageUpdateArgs: args,
+			})
 		return {
 			id: entry.id,
 			is_archived: entry.is_archived,
 			in_trash: entry.in_trash,
 			propertiesById: entry.propertiesById,
 			propertiesByKey,
-			update: args =>
-				updateDataSourcePage({
-					dataSource,
-					pageId: entry.id,
-					pageUpdateArgs: args,
-				}),
+			update,
+			archive: () => update({ is_archived: true }),
+			unarchive: () => update({ is_archived: false }),
 		}
 	})
 

package/src/bridge/notifyListener.ts

@@ -0,0 +1,14 @@
+/** Report consumer errors without interrupting bridge operations or other listeners. */
+export function notifyListener(listener: () => void): void {
+	try {
+		listener()
+	} catch (error) {
+		if (typeof globalThis.reportError === "function") {
+			globalThis.reportError(error)
+		} else {
+			setTimeout(() => {
+				throw error
+			}, 0)
+		}
+	}
+}

package/src/bridge/sandboxClient.ts

@@ -10,7 +10,6 @@ import type {
 	NotionUserId,
 	UpdatePageArgs,
 	UpdatePageResult,
-	UseDataSourceOptions,
 } from "../types.js"
 import {
 	type CustomBlockHostState,
@@ -18,9 +17,14 @@ import {
 	getDataSourceQueryView as getDataSourceQueryViewWithBridge,
 } from "./hostState.js"
 import type { ManifestLoadResult } from "./loadManifest.js"
-import { type MessageLogEntry, SandboxBridge } from "./SandboxBridge.js"
+import {
+	type MessageLogEntry,
+	type QueryDataSourceArgs,
+	SandboxBridge,
+} from "./SandboxBridge.js"
 
 let bridge: SandboxBridge | undefined
+let didWarnAboutPagesDelete = false
 
 function getBridge(): SandboxBridge {
 	if (!bridge) {
@@ -72,12 +76,8 @@ export const customBlockDataSources = {
 		return getBridge().createDataSourceSubscriptionId()
 	},
 
-	query: (
-		subscriptionId: string,
-		key: string,
-		options?: UseDataSourceOptions,
-	) => {
-		getBridge().queryDataSource(subscriptionId, key, options)
+	query: (args: QueryDataSourceArgs) => {
+		getBridge().queryDataSource(args)
 	},
 
 	release: (subscriptionId: string) => {
@@ -134,10 +134,31 @@ export const pages = {
 	},
 
 	/**
-	 * Soft-delete a page by archiving it.
+	 * Archives a page.
+	 */
+	archive: (pageId: NotionPageId): Promise<UpdatePageResult> => {
+		return getBridge().updatePage({ pageId, is_archived: true })
+	},
+
+	/**
+	 * Unarchives a page.
+	 */
+	unarchive: (pageId: NotionPageId): Promise<UpdatePageResult> => {
+		return getBridge().updatePage({ pageId, is_archived: false })
+	},
+
+	/**
+	 * @deprecated This method archives the page. It does not move the page to Trash.
+	 * Use `pages.archive(pageId)` instead.
 	 */
 	delete: (pageId: NotionPageId): Promise<UpdatePageResult> => {
-		return getBridge().updatePage({ pageId, archived: true })
+		if (!didWarnAboutPagesDelete) {
+			didWarnAboutPagesDelete = true
+			console.warn(
+				"[Notion Custom Blocks] DEPRECATED: pages.delete() archives the page. It does not move the page to Trash. Use pages.archive() instead.",
+			)
+		}
+		return getBridge().updatePage({ pageId, is_archived: true })
 	},
 }
 

package/src/customBlock.ts

@@ -7,6 +7,7 @@ import type { NotionParent } from "@notionhq/custom-blocks-protocol/parent.js"
 import type { NotionTheme } from "@notionhq/custom-blocks-protocol/theme.js"
 import type { NotionUser } from "@notionhq/custom-blocks-protocol/users/user.js"
 import { autoResize } from "./autoResize.js"
+import { subscribeToDataSource } from "./bridge/dataSources/subscribe.js"
 import type {
 	CustomBlockHostState,
 	InitializedHostState,
@@ -72,6 +73,12 @@ export const customBlock = {
 	},
 
 	autoResize,
+
+	/**
+	 * Registers a listener that receives the current query snapshot and later updates.
+	 * Returns a function that removes this listener. Other listeners remain subscribed.
+	 */
+	subscribeToDataSource,
 }
 
 let lastHostState: CustomBlockHostState | undefined

package/src/react/useDataSource.ts

@@ -1,8 +1,22 @@
 import { useEffect, useState } from "react"
 import { getDataSourceQueryOptionsIdentity } from "../bridge/dataSources/query.js"
-import { customBlockDataSources } from "../bridge/sandboxClient.js"
+import { customBlock } from "../customBlock.js"
 import type { UseDataSourceOptions, UseDataSourceResult } from "../types.js"
-import { useCustomBlockHost } from "./useHostState.js"
+
+const EMPTY_DATA_SOURCE_RESULT: UseDataSourceResult = {
+	items: [],
+	propertySchemasById: {},
+	propertyIdsByKey: {},
+	propertySchemasByKey: {},
+	isLoading: false,
+	hasMore: false,
+}
+
+type DataSourceHookState = {
+	key: string
+	optionsIdentity: string
+	snapshot: UseDataSourceResult
+}
 
 /**
  * Reads from the data source mapped to the given semantic `key`.
@@ -18,45 +32,24 @@ export function useDataSource(
 	key: string,
 	options?: UseDataSourceOptions,
 ): UseDataSourceResult {
-	const host = useCustomBlockHost()
-	const [subscriptionId] = useState(() =>
-		customBlockDataSources.createSubscriptionId(),
-	)
 	const optionsIdentity = getDataSourceQueryOptionsIdentity(options)
-	const matchingDataSource =
-		host.status === "initialized"
-			? host.dataSources.find(dataSource => dataSource.key === key)
-			: undefined
-
-	const isInitialized = host.status === "initialized"
+	const [state, setState] = useState<DataSourceHookState>(() => ({
+		key,
+		optionsIdentity,
+		snapshot: EMPTY_DATA_SOURCE_RESULT,
+	}))
 	// biome-ignore lint/correctness/useExhaustiveDependencies(options): Compare options by value through optionsIdentity. Object identity alone must not trigger queries.
-	// biome-ignore lint/correctness/useExhaustiveDependencies(optionsIdentity): Changes to the serialized options must trigger a query even though the callback reads options.
-	// biome-ignore lint/correctness/useExhaustiveDependencies(matchingDataSource): Requery when the matching data source changes, even when the key and options are unchanged.
 	useEffect(() => {
-		if (!isInitialized) {
-			return
-		}
-
-		customBlockDataSources.query(subscriptionId, key, options)
-	}, [matchingDataSource, isInitialized, key, optionsIdentity, subscriptionId])
-
-	useEffect(
-		() => () => {
-			customBlockDataSources.release(subscriptionId)
-		},
-		[subscriptionId],
-	)
-
-	const view = customBlockDataSources.getView(host, key, subscriptionId)
-
-	return {
-		items: view.items,
-		collectionSchema: view.collectionSchema,
-		propertySchemasById: view.propertySchemasById,
-		propertyIdsByKey: view.propertyIdsByKey,
-		propertySchemasByKey: view.propertySchemasByKey,
-		isLoading: view.isLoading,
-		hasMore: view.hasMore,
-		error: view.error,
+		return customBlock.subscribeToDataSource({
+			key,
+			onSnapshot: snapshot => {
+				setState({ key, optionsIdentity, snapshot })
+			},
+			options,
+		})
+	}, [key, optionsIdentity])
+	if (state.key !== key || state.optionsIdentity !== optionsIdentity) {
+		return EMPTY_DATA_SOURCE_RESULT
 	}
+	return state.snapshot
 }

package/src/types.ts

@@ -80,7 +80,7 @@ export type NotionPagePropertyInputMap = {
 }
 
 /**
- * Consumer-facing page shape returned from `useDataSource`. Derived from the bridge payload
+ * Consumer-facing page shape returned from a data source snapshot. Derived from the bridge payload
  * plus the data source's `propertyIdsByKey`.
  */
 export type NotionDataSourcePage = {
@@ -106,12 +106,20 @@ export type NotionDataSourcePage = {
 	 * keys to raw property IDs before sending the bridge message to the host.
 	 */
 	update: (args: NotionDataSourcePageUpdateArgs) => Promise<UpdatePageResult>
+	/** Archives this page. Shorthand for update({ is_archived: true }). */
+	archive: () => Promise<UpdatePageResult>
+	/** Unarchives this page. Shorthand for update({ is_archived: false }). */
+	unarchive: () => Promise<UpdatePageResult>
 }
 
 export type NotionDataSourcePageUpdateArgs = {
 	properties?: NotionPagePropertyInputMap
 	icon?: NotionPageIcon
 	cover?: NotionPageCover
+	/** Whether to archive this page. Takes precedence over archived. */
+	is_archived?: boolean
+	/** @deprecated Use is_archived instead. */
+	// TODO(custom-blocks): Remove archived when upgrading to bridge protocol v4.
 	archived?: boolean
 }
 
@@ -168,14 +176,14 @@ export type NotionDataSourceFilter =
 	| { and: NotionDataSourcePropertyFilter[] }
 
 /**
- * Return shape of `useDataSource`.
+ * Latest live snapshot of a data source query.
  *
  * - `items` — the rows the host has returned so far. Empty until the first response arrives.
  * - `isLoading` — `true` while a query is in flight.
- * - `hasMore` — `true` if the host indicated more rows are available beyond the current page.
+ * - `hasMore` — `true` if the host indicated more rows are available beyond the requested prefix.
  * - `error` — structured error information if the most recent query failed.
  */
-export type UseDataSourceResult = {
+export type DataSourceSnapshot = {
 	items: NotionDataSourcePage[]
 	/**
 	 * Collection/data source schema for the bound Notion data source, including raw property
@@ -203,22 +211,25 @@ export type UseDataSourceResult = {
 	error?: CustomBlockQueryDataSourceErrorInfo
 }
 
-export type UseDataSourceOptions = {
-	/**
-	 * Maximum number of rows to request from the host. Defaults to 20.
-	 */
+export type DataSourceQueryOptions = {
+	/** 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.
-	 */
+	/** Optional property filter. The SDK resolves semantic keys before it sends the query. */
 	filter?: NotionDataSourceFilter
-	/**
-	 * Optional property sorts. The host applies them in array order.
-	 */
+	/** Optional property sorts. The host applies them in array order. */
 	sorts?: NotionDataSourceSort[]
 }
 
+export type SubscribeToDataSourceArgs = {
+	key: string
+	onSnapshot: (snapshot: DataSourceSnapshot) => void
+	options?: DataSourceQueryOptions
+}
+
+export type UseDataSourceResult = DataSourceSnapshot
+
+export type UseDataSourceOptions = DataSourceQueryOptions
+
 /**
  * Parent reference accepted by `sdk.pages.create`. Mirrors Notion's public `POST /v1/pages`
  * parent shape; see https://developers.notion.com/reference/data-source.
@@ -260,7 +271,16 @@ export type CreatePageResult = BridgeMessagePayload<
 	CustomBlockCreatePageErrorInfo
 >
 
-export type UpdatePageArgs = Omit<UpdatePageMessage, "type" | "requestId">
+export type UpdatePageArgs = Omit<
+	UpdatePageMessage,
+	"type" | "requestId" | "archived"
+> & {
+	/** Whether to archive this page. Takes precedence over archived. */
+	is_archived?: boolean
+	/** @deprecated Use is_archived instead. */
+	// TODO(custom-blocks): Remove archived when upgrading to bridge protocol v4.
+	archived?: boolean
+}
 
 /**
  * @deprecated Use `UpdatePageArgs` instead.
@@ -278,7 +298,7 @@ export type GetPageResult = BridgeMessagePayload<
 >
 
 /**
- * Result of `sdk.pages.update` / `sdk.pages.delete`.
+ * Result of `sdk.pages.update`, `sdk.pages.archive`, and `sdk.pages.unarchive`.
  */
 export type UpdatePageResult = BridgeMessagePayload<
 	UpdatePageResultMessage,