@notionhq/custom-blocks-host 0.0.1

package/src/lifecycle/initErrors.ts

@@ -0,0 +1,165 @@
+import type {
+	CustomBlockInitErrorCode,
+	CustomBlockInitErrorInfo,
+} from "@notionhq/custom-blocks-protocol/messages/init.js"
+
+const UNKNOWN_ERROR_MESSAGE =
+	"Unexpected error while initializing custom block."
+
+/**
+ * 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
+ * `connect` message. `isRetryable` means a fresh iframe / `init` attempt could plausibly succeed
+ * without changing block code or host configuration.
+ */
+export function initErrorForFailureReason(
+	reason: CustomBlockInitErrorCode,
+	data: {
+		minBridgeProtocolVersion?: number
+		currentBridgeProtocolVersion?: number
+	} = {},
+): CustomBlockInitErrorInfo {
+	switch (reason) {
+		case "no_connect":
+			return {
+				code: reason,
+				message: "Sandbox did not send a connect message.",
+				isRetryable: true,
+			}
+		case "invalid_connect_payload":
+			return {
+				code: reason,
+				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: "The custom block manifest is unavailable.",
+				isRetryable: true,
+			}
+		case "manifest_invalid":
+			return {
+				code: reason,
+				message: "Sandbox sent an invalid manifest.",
+				// The sandbox must be updated to a valid manifest.
+				isRetryable: false,
+			}
+		case "invalid_protocol_version": {
+			const versionText = data.currentBridgeProtocolVersion
+				? `: ${data.currentBridgeProtocolVersion}`
+				: "."
+			return {
+				code: reason,
+				message: `Sandbox reported an invalid bridge protocol version ${versionText}`,
+				// The sandbox must be updated to a supported protocol version.
+				isRetryable: false,
+			}
+		}
+		case "unsupported_protocol_version": {
+			const currentVersionText = data.currentBridgeProtocolVersion
+				? `${data.currentBridgeProtocolVersion} `
+				: ""
+			const minVersionText = data.minBridgeProtocolVersion
+				? ` Minimum supported version is ${data.minBridgeProtocolVersion}.`
+				: ""
+			return {
+				code: reason,
+				message: `Sandbox bridge protocol version ${currentVersionText}is not supported.${minVersionText}`,
+				// The sandbox must be updated to a supported protocol version.
+				isRetryable: false,
+			}
+		}
+		case "context_unavailable":
+			return {
+				code: reason,
+				message: "Host page context is unavailable.",
+				isRetryable: true,
+			}
+		case "current_user_unavailable":
+			return {
+				code: reason,
+				message: "Current user is unavailable.",
+				isRetryable: true,
+			}
+		case "missing_data_source_binding":
+			return {
+				code: reason,
+				message: "A required data source is not mapped.",
+				// Host configuration must be changed before this block can initialize.
+				isRetryable: false,
+			}
+		case "data_source_unavailable":
+			return {
+				code: reason,
+				message: "A mapped data source is unavailable.",
+				// This error combines some retryable errors (e.g. data source failed to load) with
+				// some non-retryable errors (e.g. data source does not exist or user does not have
+				// access). Fallback to assuming the error is retryable.
+				isRetryable: true,
+			}
+		case "missing_property_binding":
+			return {
+				code: reason,
+				message: "A required data source property is not mapped.",
+				// Host configuration must be changed before this block can initialize.
+				isRetryable: false,
+			}
+		case "invalid_property_binding":
+			return {
+				code: reason,
+				message: "A mapped data source property is missing or incompatible.",
+				// The bound property's schema must be updated or the binding must be updated to
+				// 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_payload":
+			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,
+				message: "<NotionCustomBlock> only works inside an iframe.",
+				// The block must be embedded in an iframe.
+				isRetryable: false,
+			}
+		case "init_timeout":
+			return {
+				code: reason,
+				message: "Host did not respond to init before the timeout.",
+				isRetryable: true,
+			}
+		case "unknown_error":
+			return {
+				code: reason,
+				message: UNKNOWN_ERROR_MESSAGE,
+				// Treat unknown errors as non-retryable.
+				isRetryable: false,
+			}
+		default:
+			console.warn(`Unexpected custom block init error: ${reason}`)
+			return {
+				code: reason,
+				message: UNKNOWN_ERROR_MESSAGE,
+				// Treat unknown error codes as non-retryable.
+				isRetryable: false,
+			}
+	}
+}

package/src/lifecycle/initializationController.ts

@@ -0,0 +1,290 @@
+import type { NotionContrastMode } from "@notionhq/custom-blocks-protocol/contrast.js"
+import type { NotionBlockId } from "@notionhq/custom-blocks-protocol/ids.js"
+import type { CustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest.js"
+import type { ConnectMessage } from "@notionhq/custom-blocks-protocol/messages/connect.js"
+import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
+import type {
+	CustomBlockInitErrorInfo,
+	InitMessage,
+} from "@notionhq/custom-blocks-protocol/messages/init.js"
+import type { InitResultMessage } from "@notionhq/custom-blocks-protocol/messages/initResult.js"
+import type { CustomBlockPage } from "@notionhq/custom-blocks-protocol/pages/page.js"
+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 { initErrorForFailureReason } from "./initErrors.js"
+import { isValidBridgeProtocolVersion } from "./protocolVersion.js"
+import type {
+	ConnectSuccessMessage,
+	CustomBlockHostDataSourcesPayload,
+	InitStatus,
+} from "./types.js"
+
+const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5_000
+const DEFAULT_NO_INIT_RESULT_TIMEOUT_MS = 5_000
+
+type InitializationState = {
+	theme: NotionTheme
+	contrastMode: NotionContrastMode
+	parent: NotionParent
+	page: CustomBlockPage
+	currentUser: NotionUser
+}
+
+type InitializationPreparation =
+	| {
+			status: "success"
+			manifest: CustomBlockManifest
+			dataSources: CustomBlockHostDataSourcesPayload
+	  }
+	| {
+			status: "error"
+			error: CustomBlockInitErrorInfo
+	  }
+
+export type InitializationControllerOptions = {
+	blockId: NotionBlockId
+	getState: () => InitializationState
+	prepareInit: (connect: ConnectSuccessMessage) => InitializationPreparation
+	post: (message: HostToSandboxMessage) => void
+	warn: (payload: unknown) => void
+	flushPendingHostStateChanges: () => void
+	minBridgeProtocolVersion: number
+	noConnectTimeoutMs?: number
+	noInitResultTimeoutMs?: number
+	onConnect?: (message: ConnectSuccessMessage) => void
+	onInitResult?: (message: InitResultMessage) => void
+	onIgnoredConnect?: (message: ConnectMessage) => void
+}
+
+export type InitializationController = {
+	readonly status: InitStatus
+	readonly hasConnectedSandbox: boolean
+	handleConnect: (message: ConnectMessage) => void
+	handleInitResult: (message: InitResultMessage) => void
+	handleInvalidConnect: (initializationId: string) => boolean
+	handleInvalidInitResult: () => boolean
+	onIframeLoad: () => void
+	stop: () => void
+}
+
+export function createInitializationController(
+	options: InitializationControllerOptions,
+): InitializationController {
+	const {
+		blockId,
+		getState,
+		prepareInit,
+		post,
+		warn,
+		flushPendingHostStateChanges,
+		minBridgeProtocolVersion,
+		noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS,
+		noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS,
+		onConnect,
+		onInitResult,
+		onIgnoredConnect,
+	} = options
+
+	let initStatus: InitStatus = "waitingForConnect"
+	let noConnectTimeoutId: number | undefined
+	let noInitResultTimeoutId: number | undefined
+	let activeInitializationId: string | undefined
+	let hasConnectedSandbox = false
+
+	function clearNoConnectTimeout() {
+		if (noConnectTimeoutId !== undefined) {
+			window.clearTimeout(noConnectTimeoutId)
+			noConnectTimeoutId = undefined
+		}
+	}
+
+	function clearNoInitResultTimeout() {
+		if (noInitResultTimeoutId !== undefined) {
+			window.clearTimeout(noInitResultTimeoutId)
+			noInitResultTimeoutId = undefined
+		}
+	}
+
+	function sendInitError(
+		initializationId: string,
+		error: CustomBlockInitErrorInfo,
+	) {
+		if (initStatus !== "waitingForConnect") {
+			return
+		}
+		initStatus = "error"
+		activeInitializationId = initializationId
+		clearNoConnectTimeout()
+		post({
+			type: "init",
+			initializationId,
+			status: "error",
+			error,
+		})
+	}
+
+	function sendInit(connect: ConnectSuccessMessage): boolean {
+		if (initStatus !== "waitingForConnect") {
+			return false
+		}
+		onConnect?.(connect)
+		const preparation = prepareInit(connect)
+		if (preparation.status === "error") {
+			sendInitError(connect.initializationId, preparation.error)
+			return false
+		}
+		initStatus = "waitingForInitResult"
+		activeInitializationId = connect.initializationId
+		clearNoConnectTimeout()
+		const state = getState()
+		const message: InitMessage = {
+			type: "init",
+			initializationId: connect.initializationId,
+			status: "success",
+			theme: state.theme,
+			contrastMode: state.contrastMode,
+			blockId,
+			parent: state.parent,
+			page: state.page,
+			manifest: preparation.manifest,
+			dataSources: preparation.dataSources,
+			currentUser: state.currentUser,
+		}
+		post(message)
+		noInitResultTimeoutId = window.setTimeout(() => {
+			if (initStatus !== "waitingForInitResult") {
+				return
+			}
+			initStatus = "error"
+			warn({
+				message: "Sandbox did not send initResult",
+				initializationId: connect.initializationId,
+			})
+		}, noInitResultTimeoutMs)
+		return true
+	}
+
+	function handleConnect(message: ConnectMessage) {
+		if (initStatus !== "waitingForConnect") {
+			// A sandbox document sends `connect` exactly once, so this connect
+			// belongs to a replacement document — or arrived after this host
+			// already gave up waiting. The host is single-initialization; the
+			// embedder must recreate it together with the iframe for the new
+			// document to initialize.
+			warn({
+				message:
+					"Ignored connect after initialization settled; recreate the host and iframe to re-initialize",
+				initializationId: message.initializationId,
+			})
+			onIgnoredConnect?.(message)
+			return
+		}
+
+		// Verify the bridge protocol version is valid.
+		if (!isValidBridgeProtocolVersion(message.bridgeProtocolVersion)) {
+			const initError = initErrorForFailureReason("invalid_protocol_version", {
+				currentBridgeProtocolVersion: message.bridgeProtocolVersion,
+			})
+			sendInitError(message.initializationId, initError)
+			return
+		}
+		if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
+			const initError = initErrorForFailureReason(
+				"unsupported_protocol_version",
+				{
+					currentBridgeProtocolVersion: message.bridgeProtocolVersion,
+					minBridgeProtocolVersion,
+				},
+			)
+			sendInitError(message.initializationId, initError)
+			return
+		}
+
+		// If the sandbox reported an error during `connect`, return it as an `init` error.
+		if (message.status === "error") {
+			sendInitError(message.initializationId, message.error)
+			return
+		}
+
+		if (sendInit(message)) {
+			hasConnectedSandbox = true
+		}
+	}
+
+	function handleInvalidConnect(initializationId: string): boolean {
+		if (initStatus !== "waitingForConnect") {
+			return false
+		}
+		sendInitError(
+			initializationId,
+			initErrorForFailureReason("invalid_connect_payload"),
+		)
+		return true
+	}
+
+	function handleInvalidInitResult(): boolean {
+		if (initStatus !== "waitingForInitResult") {
+			return false
+		}
+		clearNoInitResultTimeout()
+		initStatus = "error"
+		warn(initErrorForFailureReason("invalid_init_result_payload"))
+		return true
+	}
+
+	function onIframeLoad() {
+		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"
+			warn(initErrorForFailureReason("no_connect"))
+		}, noConnectTimeoutMs)
+	}
+
+	function handleInitResult(message: InitResultMessage) {
+		if (
+			initStatus !== "waitingForInitResult" ||
+			message.initializationId !== activeInitializationId
+		) {
+			warn({
+				message: "Ignored stale or unexpected initResult",
+				payload: message,
+			})
+			return
+		}
+		clearNoInitResultTimeout()
+		initStatus = message.status === "success" ? "success" : "error"
+		if (initStatus === "success") {
+			flushPendingHostStateChanges()
+		}
+		onInitResult?.(message)
+	}
+
+	function stop() {
+		clearNoConnectTimeout()
+		clearNoInitResultTimeout()
+	}
+
+	return {
+		get status() {
+			return initStatus
+		},
+		get hasConnectedSandbox() {
+			return hasConnectedSandbox
+		},
+		handleConnect,
+		handleInitResult,
+		handleInvalidConnect,
+		handleInvalidInitResult,
+		onIframeLoad,
+		stop,
+	}
+}

package/src/lifecycle/protocolVersion.ts

@@ -0,0 +1,3 @@
+export function isValidBridgeProtocolVersion(version: number): boolean {
+	return Number.isFinite(version) && Number.isInteger(version) && version >= 1
+}

package/src/lifecycle/types.ts

@@ -0,0 +1,40 @@
+import type { NotionContrastMode } from "@notionhq/custom-blocks-protocol/contrast.js"
+import type { NotionDataSourceBindings } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
+import type { NotionBlockId } from "@notionhq/custom-blocks-protocol/ids.js"
+import type { CustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest.js"
+import type { ConnectMessage } from "@notionhq/custom-blocks-protocol/messages/connect.js"
+import type { CustomBlockPage } from "@notionhq/custom-blocks-protocol/pages/page.js"
+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"
+
+export type ConnectSuccessMessage = Extract<
+	ConnectMessage,
+	{ status: "success" }
+>
+
+export type InitStatus =
+	| "waitingForConnect"
+	| "waitingForInitResult"
+	| "success"
+	| "error"
+
+export type CustomBlockHostDataSourcesPayload = {
+	bindings: NotionDataSourceBindings
+}
+
+export type CustomBlockHostInitialDataSources =
+	| CustomBlockHostDataSourcesPayload
+	| ((connect: ConnectSuccessMessage) => CustomBlockHostDataSourcesPayload)
+
+export type CustomBlockHostInitialState = {
+	theme: NotionTheme
+	// TODO(custom-blocks): Make this required when bumping bridge protocol version 4.
+	contrastMode?: NotionContrastMode
+	blockId: NotionBlockId
+	parent: NotionParent
+	page: CustomBlockPage
+	manifest: CustomBlockManifest
+	dataSources: CustomBlockHostInitialDataSources
+	currentUser: NotionUser
+}

package/src/messages/invalidSandboxMessage.ts

@@ -0,0 +1,35 @@
+import { readIncomingType } from "@notionhq/custom-blocks-protocol/incomingType.js"
+import type { InvalidSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/invalidSandboxMessage.js"
+
+export type InvalidSandboxMessageResponse = {
+	incomingType: string | undefined
+	nack?: InvalidSandboxMessage
+}
+
+export function getInvalidSandboxMessageResponse(
+	data: unknown,
+): InvalidSandboxMessageResponse {
+	const incomingType = readIncomingType(data)
+	if (
+		incomingType === "invalidHostMessage" ||
+		incomingType === "invalidSandboxMessage"
+	) {
+		return { incomingType }
+	}
+	return {
+		incomingType,
+		nack: {
+			type: "invalidSandboxMessage",
+			reason: nackReasonForInvalidSandboxMessage(incomingType),
+		},
+	}
+}
+
+function nackReasonForInvalidSandboxMessage(
+	incomingType: string | undefined,
+): string {
+	if (incomingType !== undefined) {
+		return `Unsupported sandbox message of type "${incomingType}"`
+	}
+	return "Unsupported sandbox message (no `type` field or non-object payload)"
+}

package/src/messages/types.ts

@@ -0,0 +1,80 @@
+import type { BridgeMessagePayload } from "@notionhq/custom-blocks-protocol/messagePayload.js"
+import type { CreatePageMessage } from "@notionhq/custom-blocks-protocol/messages/createPage.js"
+import type {
+	CreatePageResultMessage,
+	CustomBlockCreatePageErrorInfo,
+} from "@notionhq/custom-blocks-protocol/messages/createPageResult.js"
+import type {
+	CustomBlockGetPageErrorInfo,
+	GetPageMessage,
+	GetPageResultMessage,
+} from "@notionhq/custom-blocks-protocol/messages/getPage.js"
+import type {
+	CustomBlockGetUserErrorInfo,
+	GetUserMessage,
+	GetUserResultMessage,
+} from "@notionhq/custom-blocks-protocol/messages/getUser.js"
+import type {
+	CustomBlockListUsersErrorInfo,
+	ListUsersMessage,
+	ListUsersResultMessage,
+} from "@notionhq/custom-blocks-protocol/messages/listUsers.js"
+import type { QueryDataSourceMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
+import type { ResizeMessage } from "@notionhq/custom-blocks-protocol/messages/resize.js"
+import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/messages/updatePage.js"
+import type {
+	CustomBlockUpdatePageErrorInfo,
+	UpdatePageResultMessage,
+} from "@notionhq/custom-blocks-protocol/messages/updatePageResult.js"
+import type { CustomBlockHostQueryDataSourceResult } from "../queries/types.js"
+
+type MaybePromise<T> = T | Promise<T>
+
+export type CustomBlockHostCreatePageResult = BridgeMessagePayload<
+	CreatePageResultMessage,
+	CustomBlockCreatePageErrorInfo
+>
+
+export type CustomBlockHostGetPageResult = BridgeMessagePayload<
+	GetPageResultMessage,
+	CustomBlockGetPageErrorInfo
+>
+
+export type CustomBlockHostUpdatePageResult = BridgeMessagePayload<
+	UpdatePageResultMessage,
+	CustomBlockUpdatePageErrorInfo
+>
+
+export type CustomBlockHostGetUserResult = BridgeMessagePayload<
+	GetUserResultMessage,
+	CustomBlockGetUserErrorInfo
+>
+
+export type CustomBlockHostListUsersResult = BridgeMessagePayload<
+	ListUsersResultMessage,
+	CustomBlockListUsersErrorInfo
+>
+
+export type CustomBlockHostHandlers = {
+	queryDataSource: (
+		message: QueryDataSourceMessage,
+	) => MaybePromise<CustomBlockHostQueryDataSourceResult>
+	createPage?: (
+		message: CreatePageMessage,
+	) => MaybePromise<CustomBlockHostCreatePageResult>
+	getPage?: (
+		message: GetPageMessage,
+	) => MaybePromise<CustomBlockHostGetPageResult>
+	getUser?: (
+		message: GetUserMessage,
+	) => MaybePromise<CustomBlockHostGetUserResult>
+	listUsers?: (
+		message: ListUsersMessage,
+	) => MaybePromise<CustomBlockHostListUsersResult>
+	updatePage?: (
+		message: UpdatePageMessage,
+	) => MaybePromise<CustomBlockHostUpdatePageResult>
+	resize?: (message: ResizeMessage) => void
+}
+
+export type CustomBlockHostLogDirection = "in" | "out" | "warn"

package/src/queries/querySubscriptions.ts

@@ -0,0 +1,57 @@
+import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/ids.js"
+import type { QueryDataSourceMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
+
+export type QueryRefresh = {
+	message: QueryDataSourceMessage
+	token: QuerySubscriptionToken
+}
+
+export type QuerySubscriptionToken = {
+	readonly _tag: "QuerySubscriptionToken"
+}
+
+type QuerySubscriptionState = {
+	message: QueryDataSourceMessage
+	token: QuerySubscriptionToken
+}
+
+export class QuerySubscriptions {
+	private readonly bySubscriptionId = new Map<string, QuerySubscriptionState>()
+
+	track(message: QueryDataSourceMessage): QuerySubscriptionToken {
+		const token: QuerySubscriptionToken = {
+			_tag: "QuerySubscriptionToken",
+		}
+		this.bySubscriptionId.set(message.subscriptionId, {
+			message,
+			token,
+		})
+		return token
+	}
+
+	isCurrent(subscriptionId: string, token: QuerySubscriptionToken): boolean {
+		return this.bySubscriptionId.get(subscriptionId)?.token === token
+	}
+
+	refresh(dataSourceId: NotionDataSourceId): QueryRefresh[] {
+		const refreshes: QueryRefresh[] = []
+		for (const queryState of this.bySubscriptionId.values()) {
+			if (queryState.message.dataSourceId !== dataSourceId) {
+				continue
+			}
+			const token: QuerySubscriptionToken = {
+				_tag: "QuerySubscriptionToken",
+			}
+			queryState.token = token
+			refreshes.push({
+				message: queryState.message,
+				token,
+			})
+		}
+		return refreshes
+	}
+
+	clear() {
+		this.bySubscriptionId.clear()
+	}
+}

package/src/queries/types.ts

@@ -0,0 +1,10 @@
+import type { BridgeMessagePayload } from "@notionhq/custom-blocks-protocol/messagePayload.js"
+import type {
+	CustomBlockQueryDataSourceErrorInfo,
+	QueryDataSourceResultMessage,
+} from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
+
+export type CustomBlockHostQueryDataSourceResult = BridgeMessagePayload<
+	QueryDataSourceResultMessage,
+	CustomBlockQueryDataSourceErrorInfo
+>