@notionhq/custom-blocks-host 0.1.30 → 0.2.0

package/src/createCustomBlockHost.ts

@@ -1,24 +1,20 @@
-import {
-	DEFAULT_CONTRAST_MODE,
-	type NotionContrastMode,
-} from "@notionhq/custom-blocks-protocol/contrast.js"
+import type { NotionContrastMode } from "@notionhq/custom-blocks-protocol/contrast.js"
 import type { NotionCollectionSchema } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
 import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/ids.js"
 import type { CustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest.js"
-import type { ContrastModeChangedMessage } from "@notionhq/custom-blocks-protocol/messages/contrastModeChanged.js"
-import type { DataSourcesChangedMessage } from "@notionhq/custom-blocks-protocol/messages/dataSourcesChanged.js"
 import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
-import type { CustomBlockInitErrorCode } from "@notionhq/custom-blocks-protocol/messages/init.js"
+import type {
+	CustomBlockInitErrorCode,
+	InitMessage,
+} from "@notionhq/custom-blocks-protocol/messages/init.js"
+import type { InvalidSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/invalidSandboxMessage.js"
 import type { BridgeMessagePayload } from "@notionhq/custom-blocks-protocol/messages/messagePayload.js"
-import type { PageChangedMessage } from "@notionhq/custom-blocks-protocol/messages/pageChanged.js"
-import type { ParentChangedMessage } from "@notionhq/custom-blocks-protocol/messages/parentChanged.js"
 import type { QueryDataSourceMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
 import type {
 	CustomBlockQueryDataSourceErrorInfo,
 	QueryDataSourceResultMessage,
 } from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
 import type { SandboxToHostMessage } from "@notionhq/custom-blocks-protocol/messages/sandboxToHost.js"
-import type { ThemeChangedMessage } from "@notionhq/custom-blocks-protocol/messages/themeChanged.js"
 import type { CustomBlockPage } from "@notionhq/custom-blocks-protocol/pages/page.js"
 import type { NotionParent } from "@notionhq/custom-blocks-protocol/parent.js"
 import { LATEST_BRIDGE_PROTOCOL_VERSION } from "@notionhq/custom-blocks-protocol/protocolVersion.js"
@@ -29,7 +25,9 @@ import { createInitializationController } from "./lifecycle/initializationContro
 import { normalizeHostToSandboxMessage } from "./lifecycle/normalizeHostToSandboxMessage.js"
 import type {
 	CustomBlockHostDataSourcesPayload,
+	CustomBlockHostGetInitialState,
 	CustomBlockHostInitialState,
+	CustomBlockHostInitialStateResult,
 } from "./lifecycle/types.js"
 import { createSandboxMessageRouter } from "./messages/sandboxMessageRouter.js"
 import type {
@@ -45,6 +43,7 @@ import {
 import type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js"
 import { validateQueryDataSourceFilter } from "./queries/validateQueryDataSourceFilter.js"
 import { validateQueryDataSourceSorts } from "./queries/validateQueryDataSourceSorts.js"
+import { unreachable } from "./utils.js"
 
 // Bridge protocol version that introduced page: { type: "unavailable" }.
 // Earlier SDKs cannot represent this context, so the host reports context_unavailable.
@@ -54,19 +53,15 @@ export type CustomBlockHostOptions = {
 	iframe: HTMLIFrameElement
 	sandboxOrigin: string
 	/**
-	 * Minimum sandbox protocol version to accept. Defaults to the host runtime minimum. Higher
-	 * values retire older SDKs; lower values cannot enable protocol versions the runtime no longer
-	 * supports.
+	 * Minimum sandbox protocol version to accept. Defaults to the host runtime
+	 * minimum. Higher values retire older SDKs; lower values cannot enable
+	 * protocol versions the runtime no longer supports.
 	 */
 	minBridgeProtocolVersion?: number
 	noConnectTimeoutMs?: number
 	noInitResultTimeoutMs?: number
-	initialState: CustomBlockHostInitialState
 	handlers: CustomBlockHostHandlers
-	/**
-	 * Called as soon as the `manifest` is available after `connect`, before `onInitialized` and
-	 * binding validation.
-	 */
+	/** Called as soon as the `manifest` is available after `connect`, before `onInitialized` and binding validation. */
 	onManifest?: (manifest: CustomBlockManifest) => void
 	/** Callback fired when the initialization handshake with the sandbox completed successfully. */
 	onInitialized?: (state: {
@@ -81,11 +76,12 @@ export type CustomBlockHostOptions = {
 	 */
 	onFailure?: (error: CustomBlockHostFailure) => void
 	onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void
+	getInitialState: CustomBlockHostGetInitialState
+	initialStateTimeoutMs?: number
 }
 
 export type CustomBlockHostHandle = {
 	stop: () => void
-	post: (message: HostToSandboxMessage) => void
 	setTheme: (theme: NotionTheme) => void
 	setContrastMode: (contrastMode: NotionContrastMode) => void
 	setParent: (parent: NotionParent) => void
@@ -123,7 +119,7 @@ export function createCustomBlockHost(
 ): CustomBlockHostHandle {
 	const {
 		iframe,
-		initialState,
+		getInitialState,
 		handlers,
 		onManifest,
 		onInitialized,
@@ -132,41 +128,46 @@ export function createCustomBlockHost(
 		sandboxOrigin,
 		minBridgeProtocolVersion: configuredMinBridgeProtocolVersion,
 		noConnectTimeoutMs,
+		initialStateTimeoutMs,
 		noInitResultTimeoutMs,
 	} = options
-	// Callers can retire older SDKs, but cannot restore support for protocols the runtime no longer
-	// implements. Omission uses the runtime minimum.
+	// Callers can retire older SDKs, but cannot restore support for protocols
+	// the runtime no longer implements. Omission uses the runtime minimum.
 	const minBridgeProtocolVersion = Math.max(
 		configuredMinBridgeProtocolVersion ??
 			MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION,
 		MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION,
 	)
 
-	let theme = initialState.theme
-	let contrastMode = initialState.contrastMode ?? DEFAULT_CONTRAST_MODE
-	let parent = initialState.parent
-	let page = initialState.page
-	let dataSources = initialState.dataSources
+	type HostStateUpdates = Partial<
+		Omit<CustomBlockHostInitialState, "blockId" | "manifest">
+	>
+	let pendingState: HostStateUpdates = {}
+	let hasPreparedInitialState = false
+	let manifest: CustomBlockManifest | undefined
 	let activeDataSources: CustomBlockHostDataSourcesPayload | undefined
 	let sandboxBridgeProtocolVersion = LATEST_BRIDGE_PROTOCOL_VERSION
-	let manifest = initialState.manifest
-	let currentUser = initialState.currentUser
-	let pendingThemeChange = false
-	let pendingContrastModeChange = false
-	let pendingParentChange = false
-	let pendingPageChange = false
-	let pendingDataSourcesChange: CustomBlockHostDataSourcesPayload | undefined
-	let pendingCurrentUserChange = false
 	const querySubscriptions = new QuerySubscriptions()
 
 	function emit(direction: CustomBlockHostLogDirection, payload: unknown) {
 		onLog?.(direction, payload)
 	}
 
-	function post(message: HostToSandboxMessage) {
-		if (initializationController.status === "stopped") {
-			// The parent page can stop this host. Do not send messages after the host stops.
-			return
+	function postToSandbox(message: HostToSandboxMessage) {
+		const status = initializationController.status
+		switch (status) {
+			case "waitingForConnect":
+			case "preparingInit":
+			case "waitingForInitResult":
+			case "initialized":
+			case "error":
+				break
+			// A stopped host must not send messages, including pending responses.
+			// Return from the function to skip delivery below.
+			case "stopped":
+				return
+			default:
+				return unreachable(status)
 		}
 		const sandboxMessage = normalizeHostToSandboxMessage(
 			message,
@@ -176,6 +177,37 @@ export function createCustomBlockHost(
 		iframe.contentWindow?.postMessage(sandboxMessage, sandboxOrigin)
 	}
 
+	function sendInitMessage(message: InitMessage) {
+		postToSandbox(message)
+	}
+
+	function sendNack(message: InvalidSandboxMessage) {
+		postToSandbox(message)
+	}
+
+	function sendInitializedMessage(
+		message: Exclude<
+			HostToSandboxMessage,
+			{ type: "init" | "invalidSandboxMessage" }
+		>,
+	) {
+		const status = initializationController.status
+		switch (status) {
+			case "initialized":
+				postToSandbox(message)
+				return
+			// Send state updates and handler results only after initialization succeeds.
+			case "waitingForConnect":
+			case "preparingInit":
+			case "waitingForInitResult":
+			case "error":
+			case "stopped":
+				return
+			default:
+				unreachable(status)
+		}
+	}
+
 	/**
 	 * Invokes a one-shot handler and posts its result with the request's ID.
 	 * Each result type is named `<request type>Result` by the bridge protocol.
@@ -192,8 +224,8 @@ export function createCustomBlockHost(
 			type: `${message.type}Result` as const,
 			requestId: message.requestId,
 			...response,
-		} as HostToSandboxMessage
-		post(result)
+		} as ResultForRequest<OneShotRequest>
+		sendInitializedMessage(result)
 	}
 
 	function postQueryDataSourceResult(args: {
@@ -215,7 +247,7 @@ export function createCustomBlockHost(
 						items: args.response.items,
 						hasMore: args.response.hasMore,
 					}
-		post(message)
+		sendInitializedMessage(message)
 	}
 
 	async function handleQuery(
@@ -246,95 +278,69 @@ export function createCustomBlockHost(
 		})
 	}
 
-	/**
-	 * 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 updateHostState(update: HostStateUpdates) {
+		if (
+			initializationController.status === "stopped" ||
+			initializationController.status === "error"
+		) {
+			return
+		}
+		Object.assign(pendingState, update)
+		flushPendingHostStateChanges()
+	}
+
 	function flushPendingHostStateChanges() {
-		if (pendingThemeChange) {
-			pendingThemeChange = false
-			post({ type: "themeChanged", theme })
+		// Keep updates queued until the sandbox acknowledges initialization.
+		// Updates received before init is sent are included in its payload instead.
+		if (initializationController.status !== "initialized") {
+			return
 		}
-		if (pendingContrastModeChange) {
-			pendingContrastModeChange = false
-			post({ type: "contrastModeChanged", contrastMode })
+		const changes = pendingState
+		pendingState = {}
+		if (changes.theme !== undefined) {
+			sendInitializedMessage({ type: "themeChanged", theme: changes.theme })
 		}
-		if (pendingParentChange) {
-			pendingParentChange = false
-			post({ type: "parentChanged", parent })
+		if (changes.contrastMode !== undefined) {
+			sendInitializedMessage({
+				type: "contrastModeChanged",
+				contrastMode: changes.contrastMode,
+			})
+		}
+		if (changes.parent !== undefined) {
+			sendInitializedMessage({ type: "parentChanged", parent: changes.parent })
 		}
-		if (pendingPageChange) {
-			pendingPageChange = false
-			post({ type: "pageChanged", page })
+		if (changes.page !== undefined) {
+			sendInitializedMessage({ type: "pageChanged", page: changes.page })
 		}
-		if (pendingDataSourcesChange !== undefined) {
-			const nextDataSources = pendingDataSourcesChange
-			pendingDataSourcesChange = undefined
-			post({
+		if (changes.dataSources !== undefined) {
+			sendInitializedMessage({
 				type: "dataSourcesChanged",
-				dataSources: nextDataSources,
+				dataSources: changes.dataSources,
 			})
 		}
-		if (pendingCurrentUserChange) {
-			pendingCurrentUserChange = false
-			post({ type: "currentUserChanged", currentUser })
+		if (changes.currentUser !== undefined) {
+			sendInitializedMessage({
+				type: "currentUserChanged",
+				currentUser: changes.currentUser,
+			})
 		}
 	}
 
 	const initializationController = createInitializationController({
-		blockId: initialState.blockId,
-		getState: () => ({
-			theme,
-			contrastMode,
-			parent,
-			page,
-			currentUser,
-		}),
-		prepareInit(connect) {
+		async prepareInit(connect) {
 			sandboxBridgeProtocolVersion = connect.bridgeProtocolVersion
-			if (
-				sandboxBridgeProtocolVersion <
-					BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE &&
-				page.type === "unavailable"
-			) {
-				return {
-					status: "error",
-					error: initErrorForFailureReason("context_unavailable"),
-				}
-			}
-			manifest = connect.manifest ?? initialState.manifest
-			if (manifest === undefined) {
-				return {
-					status: "error",
-					error: initErrorForFailureReason("manifest_unavailable"),
-				}
-			}
-			onManifest?.(manifest)
-			const resolvedDataSources =
-				typeof dataSources === "function" ? dataSources(connect) : dataSources
-			const bindingErrorCode = getBindingErrorCode(
-				manifest,
-				resolvedDataSources,
-			)
-			if (bindingErrorCode !== undefined) {
-				return {
-					status: "error",
-					error: initErrorForFailureReason(bindingErrorCode),
-				}
-			}
-			activeDataSources = resolvedDataSources
-			return {
-				status: "success",
-				manifest,
-				dataSources: resolvedDataSources,
+			const result = await getInitialState(connect)
+			if (initializationController.status !== "preparingInit") {
+				return result
 			}
+			return prepareInitialState(result)
 		},
-		post,
+		sendInitMessage,
 		warn: payload => emit("warn", payload),
 		flushPendingHostStateChanges,
 		minBridgeProtocolVersion,
 		noConnectTimeoutMs,
+		initialStateTimeoutMs,
 		noInitResultTimeoutMs,
 		stopHostWithFailure: stopWithFailure,
 		onInitResult(message) {
@@ -345,12 +351,47 @@ export function createCustomBlockHost(
 		onFailure,
 	})
 
+	function prepareInitialState(
+		result: CustomBlockHostInitialStateResult,
+	): CustomBlockHostInitialStateResult {
+		if (result.status === "error") {
+			return result
+		}
+		manifest = result.initialState.manifest
+		onManifest?.(manifest)
+		const initialState = { ...result.initialState, ...pendingState }
+		pendingState = {}
+		if (
+			sandboxBridgeProtocolVersion <
+				BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE &&
+			initialState.page.type === "unavailable"
+		) {
+			return {
+				status: "error",
+				error: initErrorForFailureReason("context_unavailable"),
+			}
+		}
+		const bindingErrorCode = getBindingErrorCode(
+			initialState.manifest,
+			initialState.dataSources,
+		)
+		if (bindingErrorCode !== undefined) {
+			return {
+				status: "error",
+				error: initErrorForFailureReason(bindingErrorCode),
+			}
+		}
+		activeDataSources = initialState.dataSources
+		hasPreparedInitialState = true
+		return { status: "success", initialState }
+	}
+
 	const onMessage = createSandboxMessageRouter({
 		iframe,
 		sandboxOrigin,
 		getInitStatus: () => initializationController.status,
 		emit,
-		post,
+		sendNack,
 		onInvalidConnect: initializationController.handleInvalidConnect,
 		onInvalidInitResult: initializationController.handleInvalidInitResult,
 		onConnect: initializationController.handleConnect,
@@ -385,102 +426,50 @@ export function createCustomBlockHost(
 
 	return {
 		stop,
-		post,
-		setTheme(nextTheme) {
-			theme = nextTheme
-			if (initializationController.status !== "success") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingThemeChange = true
-				}
-				return
-			}
-			const message: ThemeChangedMessage = { type: "themeChanged", theme }
-			post(message)
+		setTheme(theme) {
+			updateHostState({ theme })
 		},
-		setContrastMode(nextContrastMode) {
-			contrastMode = nextContrastMode
-			if (initializationController.status !== "success") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingContrastModeChange = true
-				}
-				return
-			}
-			const message: ContrastModeChangedMessage = {
-				type: "contrastModeChanged",
-				contrastMode,
-			}
-			post(message)
+		setContrastMode(contrastMode) {
+			updateHostState({ contrastMode })
 		},
-		setParent(nextParent) {
-			parent = nextParent
-			if (initializationController.status !== "success") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingParentChange = true
-				}
-				return
-			}
-			const message: ParentChangedMessage = { type: "parentChanged", parent }
-			post(message)
+		setParent(parent) {
+			updateHostState({ parent })
 		},
-		setPage(nextPage) {
-			page = nextPage
+		setPage(page) {
 			if (
-				nextPage.type === "unavailable" &&
+				page.type === "unavailable" &&
 				sandboxBridgeProtocolVersion <
 					BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE &&
-				(initializationController.status === "waitingForInitResult" ||
-					initializationController.status === "success")
+				((initializationController.status === "preparingInit" &&
+					hasPreparedInitialState) ||
+					initializationController.status === "waitingForInitResult" ||
+					initializationController.status === "initialized")
 			) {
 				stopWithFailure(initErrorForFailureReason("context_unavailable"))
 				return
 			}
-			if (initializationController.status !== "success") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingPageChange = true
-				}
-				return
-			}
-			const message: PageChangedMessage = { type: "pageChanged", page }
-			post(message)
+			updateHostState({ page })
 		},
-		setDataSources(nextDataSources) {
+		setCurrentUser(currentUser) {
+			updateHostState({ currentUser })
+		},
+		setDataSources(dataSources) {
 			if (
 				initializationController.hasConnectedSandbox &&
 				manifest !== undefined &&
-				getBindingErrorCode(manifest, nextDataSources) !== undefined
+				getBindingErrorCode(manifest, dataSources) !== undefined
 			) {
 				emit("warn", {
 					message: "Ignored invalid data source bindings update",
-					payload: nextDataSources,
+					payload: dataSources,
 				})
 				return
 			}
-			dataSources = nextDataSources
-			activeDataSources = nextDataSources
-			if (initializationController.status !== "success") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingDataSourcesChange = nextDataSources
-				}
-				return
-			}
-			const message: DataSourcesChangedMessage = {
-				type: "dataSourcesChanged",
-				dataSources: nextDataSources,
-			}
-			post(message)
-		},
-		setCurrentUser(nextCurrentUser) {
-			currentUser = nextCurrentUser
-			if (initializationController.status !== "success") {
-				if (initializationController.status === "waitingForInitResult") {
-					pendingCurrentUserChange = true
-				}
-				return
-			}
-			post({ type: "currentUserChanged", currentUser })
+			activeDataSources = dataSources
+			updateHostState({ dataSources })
 		},
 		refreshQuery({ dataSourceId }) {
-			if (initializationController.status !== "success") {
+			if (initializationController.status !== "initialized") {
 				return
 			}
 			const refreshes = querySubscriptions.refresh(dataSourceId)

package/src/index.ts

@@ -23,8 +23,9 @@ export {
 export type {
 	ConnectSuccessMessage,
 	CustomBlockHostDataSourcesPayload,
-	CustomBlockHostInitialDataSources,
+	CustomBlockHostGetInitialState,
 	CustomBlockHostInitialState,
+	CustomBlockHostInitialStateResult,
 } from "./lifecycle/types.js"
 export type {
 	CreatePageMessageInput,

package/src/lifecycle/initErrors.ts

@@ -90,6 +90,12 @@ export function initErrorForFailureReason(
 				message: "Current user is unavailable.",
 				isRetryable: true,
 			}
+		case "initial_state_timeout":
+			return {
+				code: reason,
+				message: "Host did not prepare initial state before the timeout.",
+				isRetryable: true,
+			}
 		case "missing_data_source_binding":
 			return {
 				code: reason,