@notionhq/custom-blocks 0.0.76 → 0.0.78

package/src/host/createCustomBlockHost.ts

@@ -1,5 +1,7 @@
 import * as v from "valibot"
 import type { NotionDataSourceId } from "../bridge/ids.js"
+import type { CustomBlockManifest } from "../bridge/manifest.js"
+import type { ConnectMessage } from "../bridge/messages/connect.js"
 import type { CreatePageMessage } from "../bridge/messages/createPage.js"
 import type { CreatePageResultMessage } from "../bridge/messages/createPageResult.js"
 import type { DataSourcesChangedMessage } from "../bridge/messages/dataSourcesChanged.js"
@@ -13,9 +15,11 @@ import type {
 } from "../bridge/messages/getUser.js"
 import type { HostToSandboxMessage } from "../bridge/messages/hostToSandbox.js"
 import type {
+	CustomBlockInitErrorCode,
 	CustomBlockInitErrorInfo,
 	InitMessage,
 } from "../bridge/messages/init.js"
+import type { InitResultMessage } from "../bridge/messages/initResult.js"
 import type {
 	ListUsersMessage,
 	ListUsersResultMessage,
@@ -24,7 +28,6 @@ import type { PageChangedMessage } from "../bridge/messages/pageChanged.js"
 import type { ParentChangedMessage } from "../bridge/messages/parentChanged.js"
 import type { QueryDataSourceMessage } from "../bridge/messages/queryDataSource.js"
 import type { QueryDataSourceResultMessage } from "../bridge/messages/queryDataSourceResult.js"
-import type { ReadyMessage } from "../bridge/messages/ready.js"
 import { sandboxToHostMessageSchema } from "../bridge/messages/sandboxToHost.js"
 import type { ThemeChangedMessage } from "../bridge/messages/themeChanged.js"
 import type { UpdatePageMessage } from "../bridge/messages/updatePage.js"
@@ -37,10 +40,10 @@ import { unreachable } from "../utils.js"
 import { initErrorForFailureReason } from "./lifecycle/initErrors.js"
 import { isValidBridgeProtocolVersion } from "./lifecycle/ready.js"
 import type {
+	ConnectSuccessMessage,
 	CustomBlockHostDataSourcesPayload,
 	CustomBlockHostInitialState,
 	InitStatus,
-	ReadySuccessMessage,
 } from "./lifecycle/types.js"
 import { getInvalidSandboxMessageResponse } from "./messages/invalidSandboxMessage.js"
 import type {
@@ -54,10 +57,12 @@ export type CustomBlockHostOptions = {
 	iframe: HTMLIFrameElement
 	targetOrigin?: string
 	minBridgeProtocolVersion?: number
-	noReadyTimeoutMs?: number
+	noConnectTimeoutMs?: number
+	noInitResultTimeoutMs?: number
 	initialState: CustomBlockHostInitialState
 	handlers: CustomBlockHostHandlers
-	onReady?: (message: ReadySuccessMessage) => void
+	onConnect?: (message: ConnectSuccessMessage) => void
+	onInitResult?: (message: InitResultMessage) => void
 	onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void
 }
 
@@ -75,7 +80,8 @@ export type CustomBlockHostHandle = {
 	}) => void
 }
 
-const DEFAULT_NO_READY_TIMEOUT_MS = 5_000
+const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5_000
+const DEFAULT_NO_INIT_RESULT_TIMEOUT_MS = 5_000
 const DEFAULT_MIN_BRIDGE_PROTOCOL_VERSION = 2
 
 export function createCustomBlockHost(
@@ -85,20 +91,31 @@ export function createCustomBlockHost(
 		iframe,
 		initialState,
 		handlers,
-		onReady,
+		onConnect,
+		onInitResult,
 		onLog,
 		targetOrigin = "*",
 		minBridgeProtocolVersion = DEFAULT_MIN_BRIDGE_PROTOCOL_VERSION,
-		noReadyTimeoutMs = DEFAULT_NO_READY_TIMEOUT_MS,
+		noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS,
+		noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS,
 	} = options
 
 	let theme = initialState.theme
 	let parent = initialState.parent
 	let page = initialState.page
 	let dataSources = initialState.dataSources
+	let manifest = initialState.manifest
 	let currentUser = initialState.currentUser
-	let initStatus: InitStatus = "pending"
-	let noReadyTimeoutId: number | undefined
+	let initStatus: InitStatus = "waitingForConnect"
+	let noConnectTimeoutId: number | undefined
+	let noInitResultTimeoutId: number | undefined
+	let activeInitializationId: string | undefined
+	let connectedSandbox: ConnectSuccessMessage | undefined
+	let pendingThemeChange = false
+	let pendingParentChange = false
+	let pendingPageChange = false
+	let pendingDataSourcesChange: CustomBlockHostDataSourcesPayload | undefined
+	let pendingCurrentUserChange = false
 	const querySubscriptions = new QuerySubscriptions()
 
 	function emit(direction: CustomBlockHostLogDirection, payload: unknown) {
@@ -111,83 +128,135 @@ export function createCustomBlockHost(
 	}
 
 	function postQueryDataSourceResult(args: {
-		requestId: string
-		snapshotId: string
+		subscriptionId: string
 		response: CustomBlockHostQueryDataSourceResult
 	}) {
-		// TODO(custom-blocks): Update when bumping bridge protocol version to 3.
-		// Protocol v2 sandboxes require the legacy optional-error result shape.
-		const message: QueryDataSourceResultMessage = {
-			type: "queryDataSourceResult",
-			requestId: args.requestId,
-			snapshotId: args.snapshotId,
-			items: args.response.items,
-			hasMore: args.response.hasMore ?? false,
-			error: args.response.error,
-		}
+		const message: QueryDataSourceResultMessage =
+			args.response.status === "error"
+				? {
+						type: "queryDataSourceResult",
+						subscriptionId: args.subscriptionId,
+						status: "error",
+						error: args.response.error,
+					}
+				: {
+						type: "queryDataSourceResult",
+						subscriptionId: args.subscriptionId,
+						status: "success",
+						items: args.response.items,
+						hasMore: args.response.hasMore,
+					}
 		post(message)
 	}
 
-	function clearNoReadyTimeout() {
-		if (noReadyTimeoutId !== undefined) {
-			window.clearTimeout(noReadyTimeoutId)
-			noReadyTimeoutId = undefined
+	function clearNoConnectTimeout() {
+		if (noConnectTimeoutId !== undefined) {
+			window.clearTimeout(noConnectTimeoutId)
+			noConnectTimeoutId = undefined
+		}
+	}
+
+	function clearNoInitResultTimeout() {
+		if (noInitResultTimeoutId !== undefined) {
+			window.clearTimeout(noInitResultTimeoutId)
+			noInitResultTimeoutId = undefined
 		}
 	}
 
 	function resolveDataSourcesPayload(
-		ready: ReadySuccessMessage,
+		connect: ConnectSuccessMessage,
 	): CustomBlockHostDataSourcesPayload {
-		return typeof dataSources === "function" ? dataSources(ready) : dataSources
+		return typeof dataSources === "function"
+			? dataSources(connect)
+			: dataSources
 	}
 
-	function sendInit(ready: ReadySuccessMessage): boolean {
-		if (initStatus !== "pending") {
+	function sendInit(connect: ConnectSuccessMessage): boolean {
+		if (initStatus !== "waitingForConnect") {
 			return false
 		}
-		initStatus = "success"
-		clearNoReadyTimeout()
+		onConnect?.(connect)
+		manifest = connect.manifest ?? initialState.manifest
+		const resolvedDataSources = resolveDataSourcesPayload(connect)
+		const bindingErrorCode = getBindingErrorCode(manifest, resolvedDataSources)
+		if (bindingErrorCode !== undefined) {
+			sendInitError(
+				connect.initializationId,
+				initErrorForFailureReason(bindingErrorCode),
+			)
+			return false
+		}
+		initStatus = "waitingForInitResult"
+		activeInitializationId = connect.initializationId
+		clearNoConnectTimeout()
 		const message: InitMessage = {
 			type: "init",
+			initializationId: connect.initializationId,
 			status: "success",
 			theme,
 			blockId: initialState.blockId,
 			parent,
 			page,
-			dataSources: resolveDataSourcesPayload(ready),
+			manifest,
+			dataSources: resolvedDataSources,
 			currentUser,
 		}
 		post(message)
+		noInitResultTimeoutId = window.setTimeout(() => {
+			if (initStatus !== "waitingForInitResult") {
+				return
+			}
+			initStatus = "error"
+			emit("warn", {
+				message: "Sandbox did not send initResult",
+				initializationId: connect.initializationId,
+			})
+		}, noInitResultTimeoutMs)
 		return true
 	}
 
-	function sendInitError(error: CustomBlockInitErrorInfo) {
-		if (initStatus !== "pending") {
+	function sendInitError(
+		initializationId: string,
+		error: CustomBlockInitErrorInfo,
+	) {
+		if (initStatus !== "waitingForConnect") {
 			return
 		}
 		initStatus = "error"
-		clearNoReadyTimeout()
+		activeInitializationId = initializationId
+		clearNoConnectTimeout()
 		post({
 			type: "init",
+			initializationId,
 			status: "error",
 			error,
 		})
 	}
 
 	function onIframeLoad() {
-		clearNoReadyTimeout()
-		noReadyTimeoutId = window.setTimeout(() => {
-			const initError = initErrorForFailureReason("no_ready")
-			sendInitError(initError)
-		}, noReadyTimeoutMs)
+		clearNoConnectTimeout()
+		if (initStatus !== "waitingForConnect") {
+			// Only set the timeout if the iframe loaded before the `connect` message was sent.
+			return
+		}
+		noConnectTimeoutId = window.setTimeout(() => {
+			if (initStatus !== "waitingForConnect") {
+				// Only do anything if the iframe loaded before the `connect` message was sent.
+				return
+			}
+			initStatus = "error"
+			emit("warn", initErrorForFailureReason("no_connect"))
+		}, noConnectTimeoutMs)
 	}
 
 	async function handleQuery(message: QueryDataSourceMessage) {
-		querySubscriptions.track(message)
+		const token = querySubscriptions.track(message)
 		const response = await handlers.queryDataSource(message)
+		if (!querySubscriptions.isCurrent(message.subscriptionId, token)) {
+			return
+		}
 		postQueryDataSourceResult({
-			requestId: message.requestId,
-			snapshotId: message.snapshotId,
+			subscriptionId: message.subscriptionId,
 			response,
 		})
 	}
@@ -257,13 +326,13 @@ export function createCustomBlockHost(
 		post(result)
 	}
 
-	function handleReady(message: ReadyMessage) {
+	function handleConnect(message: ConnectMessage) {
 		// Verify the bridge protocol version is valid.
 		if (!isValidBridgeProtocolVersion(message.bridgeProtocolVersion)) {
 			const initError = initErrorForFailureReason("invalid_protocol_version", {
 				currentBridgeProtocolVersion: message.bridgeProtocolVersion,
 			})
-			sendInitError(initError)
+			sendInitError(message.initializationId, initError)
 			return
 		}
 		if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
@@ -274,19 +343,68 @@ export function createCustomBlockHost(
 					minBridgeProtocolVersion,
 				},
 			)
-			sendInitError(initError)
+			sendInitError(message.initializationId, initError)
 			return
 		}
 
-		// If the sandbox reported an error during `ready`, return it as an `init` error.
+		// If the sandbox reported an error during `connect`, return it as an `init` error.
 		if (message.status === "error") {
-			sendInitError(message.error)
+			sendInitError(message.initializationId, message.error)
 			return
 		}
 
-		if (sendInit(message)) {
-			onReady?.(message)
+		if (!sendInit(message)) {
+			return
 		}
+		connectedSandbox = message
+	}
+
+	/**
+	 * Sends any pending host state changes to the sandbox. It is possible for these to change
+	 * between when the host sends `init` and when the sandbox responds with `initResult`. The host
+	 * does send any pending state changes until hearing back from the sandbox.
+	 */
+	function flushPendingHostStateChanges() {
+		if (pendingThemeChange) {
+			pendingThemeChange = false
+			post({ type: "themeChanged", theme })
+		}
+		if (pendingParentChange) {
+			pendingParentChange = false
+			post({ type: "parentChanged", parent })
+		}
+		if (pendingPageChange) {
+			pendingPageChange = false
+			post({ type: "pageChanged", page })
+		}
+		if (pendingDataSourcesChange !== undefined) {
+			const nextDataSources = pendingDataSourcesChange
+			pendingDataSourcesChange = undefined
+			post({ type: "dataSourcesChanged", dataSources: nextDataSources })
+		}
+		if (pendingCurrentUserChange) {
+			pendingCurrentUserChange = false
+			post({ type: "currentUserChanged", currentUser })
+		}
+	}
+
+	function handleInitResult(message: InitResultMessage) {
+		if (
+			initStatus !== "waitingForInitResult" ||
+			message.initializationId !== activeInitializationId
+		) {
+			emit("warn", {
+				message: "Ignored stale or unexpected initResult",
+				payload: message,
+			})
+			return
+		}
+		clearNoInitResultTimeout()
+		initStatus = message.status === "success" ? "success" : "error"
+		if (initStatus === "success") {
+			flushPendingHostStateChanges()
+		}
+		onInitResult?.(message)
 	}
 
 	function onInvalidSandboxMessage(
@@ -300,10 +418,7 @@ export function createCustomBlockHost(
 		})
 		const response = getInvalidSandboxMessageResponse(data)
 
-		if (initStatus === "pending" && response.incomingType === "ready") {
-			const initError = initErrorForFailureReason("invalid_ready")
-			sendInitError(initError)
-		} else if (response.nack !== undefined) {
+		if (response.nack !== undefined) {
 			post(response.nack)
 		}
 	}
@@ -322,9 +437,24 @@ export function createCustomBlockHost(
 		const message = parsed.output
 		emit("in", message)
 
+		if (
+			message.type !== "connect" &&
+			message.type !== "initResult" &&
+			initStatus !== "success"
+		) {
+			emit("warn", {
+				message: `Ignored ${message.type} before initialization completed`,
+				payload: message,
+			})
+			return
+		}
+
 		switch (message.type) {
-			case "ready":
-				handleReady(message)
+			case "connect":
+				handleConnect(message)
+				return
+			case "initResult":
+				handleInitResult(message)
 				return
 			case "queryDataSource":
 				void handleQuery(message)
@@ -361,26 +491,62 @@ export function createCustomBlockHost(
 		stop() {
 			window.removeEventListener("message", onMessage)
 			iframe.removeEventListener("load", onIframeLoad)
-			clearNoReadyTimeout()
+			clearNoConnectTimeout()
+			clearNoInitResultTimeout()
+			querySubscriptions.clear()
 		},
 		post,
 		setTheme(nextTheme) {
 			theme = nextTheme
+			if (initStatus !== "success") {
+				if (initStatus === "waitingForInitResult") {
+					pendingThemeChange = true
+				}
+				return
+			}
 			const message: ThemeChangedMessage = { type: "themeChanged", theme }
 			post(message)
 		},
 		setParent(nextParent) {
 			parent = nextParent
+			if (initStatus !== "success") {
+				if (initStatus === "waitingForInitResult") {
+					pendingParentChange = true
+				}
+				return
+			}
 			const message: ParentChangedMessage = { type: "parentChanged", parent }
 			post(message)
 		},
 		setPage(nextPage) {
 			page = nextPage
+			if (initStatus !== "success") {
+				if (initStatus === "waitingForInitResult") {
+					pendingPageChange = true
+				}
+				return
+			}
 			const message: PageChangedMessage = { type: "pageChanged", page }
 			post(message)
 		},
 		setDataSources(nextDataSources) {
+			if (
+				connectedSandbox !== undefined &&
+				getBindingErrorCode(manifest, nextDataSources) !== undefined
+			) {
+				emit("warn", {
+					message: "Ignored invalid data source bindings update",
+					payload: nextDataSources,
+				})
+				return
+			}
 			dataSources = nextDataSources
+			if (initStatus !== "success") {
+				if (initStatus === "waitingForInitResult") {
+					pendingDataSourcesChange = nextDataSources
+				}
+				return
+			}
 			const message: DataSourcesChangedMessage = {
 				type: "dataSourcesChanged",
 				dataSources: nextDataSources,
@@ -389,22 +555,61 @@ export function createCustomBlockHost(
 		},
 		setCurrentUser(nextCurrentUser) {
 			currentUser = nextCurrentUser
+			if (initStatus !== "success") {
+				if (initStatus === "waitingForInitResult") {
+					pendingCurrentUserChange = true
+				}
+				return
+			}
 			post({ type: "currentUserChanged", currentUser })
 		},
 		refreshQuery({ dataSourceId, response }) {
-			const refresh = querySubscriptions.resolveRefresh({
+			if (initStatus !== "success") {
+				return
+			}
+			const refreshes = querySubscriptions.resolveRefreshes({
 				dataSourceId,
 				response,
 			})
-			if (refresh.status === "missing") {
+			if (refreshes.length === 0) {
 				emit("warn", `No active query exists for data source "${dataSourceId}"`)
 				return
 			}
-			postQueryDataSourceResult({
-				requestId: refresh.requestId,
-				snapshotId: refresh.snapshotId,
-				response: refresh.response,
-			})
+			for (const refresh of refreshes) {
+				postQueryDataSourceResult(refresh)
+			}
 		},
 	}
 }
+
+function getBindingErrorCode(
+	manifest: CustomBlockManifest,
+	dataSources: CustomBlockHostDataSourcesPayload,
+): CustomBlockInitErrorCode | undefined {
+	for (const [dataSourceKey, manifestDataSource] of Object.entries(
+		manifest.dataSources,
+	)) {
+		const binding = dataSources.bindings[dataSourceKey]
+		if (
+			binding?.collectionPointer === undefined ||
+			binding.collectionSchema === undefined
+		) {
+			return "missing_data_source_binding"
+		}
+		for (const [propertyKey, manifestProperty] of Object.entries(
+			manifestDataSource.properties ?? {},
+		)) {
+			const propertyId = binding.propertyIdsByKey?.[propertyKey]
+			if (propertyId === undefined) {
+				return "missing_property_binding"
+			}
+			if (
+				binding.collectionSchema.propertiesById[propertyId]?.type !==
+				manifestProperty.type
+			) {
+				return "invalid_property_binding"
+			}
+		}
+	}
+	return undefined
+}

package/src/host/lifecycle/initErrors.ts

@@ -10,7 +10,7 @@ const UNKNOWN_ERROR_MESSAGE =
  * Returns the error info for a given `init` failure code.
  *
  * `init` handshakes are one-shot: after an `init` error, this host instance will not answer another
- * `ready` message. `isRetryable` means a fresh iframe / `init` attempt could plausibly succeed
+ * `connect` message. `isRetryable` means a fresh iframe / `init` attempt could plausibly succeed
  * without changing block code or host configuration.
  */
 export function initErrorForFailureReason(
@@ -21,23 +21,23 @@ export function initErrorForFailureReason(
 	} = {},
 ): CustomBlockInitErrorInfo {
 	switch (reason) {
-		case "no_ready":
+		case "no_connect":
 			return {
 				code: reason,
-				message: "Sandbox did not send a ready message.",
+				message: "Sandbox did not send a connect message.",
 				isRetryable: true,
 			}
-		case "invalid_ready":
+		case "invalid_connect":
 			return {
 				code: reason,
-				message: "Sandbox sent an invalid ready message.",
-				// The sandbox must be updated to send a valid ready message.
+				message: "Sandbox sent an invalid connect message.",
+				// The sandbox must be updated to send a valid connect message.
 				isRetryable: false,
 			}
 		case "manifest_unavailable":
 			return {
 				code: reason,
-				message: "Sandbox could not load its manifest.",
+				message: "The custom block manifest is unavailable.",
 				isRetryable: true,
 			}
 		case "manifest_invalid":
@@ -115,6 +115,24 @@ export function initErrorForFailureReason(
 				// a property with a compatible schema.
 				isRetryable: false,
 			}
+		case "no_init_result":
+			return {
+				code: reason,
+				message: "Sandbox did not acknowledge initialization.",
+				isRetryable: true,
+			}
+		case "invalid_init_result":
+			return {
+				code: reason,
+				message: "Sandbox sent an invalid initialization result.",
+				isRetryable: false,
+			}
+		case "invalid_init_bindings":
+			return {
+				code: reason,
+				message: "Sandbox rejected the host-provided data source bindings.",
+				isRetryable: false,
+			}
 		case "not_in_iframe":
 			return {
 				code: reason,

package/src/host/lifecycle/types.ts

@@ -1,14 +1,22 @@
 import type { NotionDataSourceBindings } from "../../bridge/dataSources/dataSource.js"
 import type { NotionBlockId } from "../../bridge/ids.js"
-import type { ReadyMessage } from "../../bridge/messages/ready.js"
+import type { CustomBlockManifest } from "../../bridge/manifest.js"
+import type { ConnectMessage } from "../../bridge/messages/connect.js"
 import type { CustomBlockPage } from "../../bridge/pages/page.js"
 import type { NotionParent } from "../../bridge/parent.js"
 import type { NotionTheme } from "../../bridge/theme.js"
 import type { NotionUser } from "../../bridge/users/user.js"
 
-export type ReadySuccessMessage = Extract<ReadyMessage, { status: "success" }>
+export type ConnectSuccessMessage = Extract<
+	ConnectMessage,
+	{ status: "success" }
+>
 
-export type InitStatus = "pending" | "success" | "error"
+export type InitStatus =
+	| "waitingForConnect"
+	| "waitingForInitResult"
+	| "success"
+	| "error"
 
 export type CustomBlockHostDataSourcesPayload = {
 	bindings: NotionDataSourceBindings
@@ -16,13 +24,14 @@ export type CustomBlockHostDataSourcesPayload = {
 
 export type CustomBlockHostInitialDataSources =
 	| CustomBlockHostDataSourcesPayload
-	| ((ready: ReadySuccessMessage) => CustomBlockHostDataSourcesPayload)
+	| ((connect: ConnectSuccessMessage) => CustomBlockHostDataSourcesPayload)
 
 export type CustomBlockHostInitialState = {
 	theme: NotionTheme
 	blockId: NotionBlockId
 	parent: NotionParent
 	page: CustomBlockPage
+	manifest: CustomBlockManifest
 	dataSources: CustomBlockHostInitialDataSources
 	currentUser: NotionUser
 }

package/src/host/messages/invalidSandboxMessage.ts

@@ -28,9 +28,6 @@ export function getInvalidSandboxMessageResponse(
 function nackReasonForInvalidSandboxMessage(
 	incomingType: string | undefined,
 ): string {
-	if (incomingType === "ready") {
-		return "Invalid manifest"
-	}
 	if (incomingType !== undefined) {
 		return `Unsupported sandbox message of type "${incomingType}"`
 	}