@notionhq/custom-blocks-host 0.0.1

package/src/createCustomBlockHost.ts

@@ -0,0 +1,605 @@
+import {
+	DEFAULT_CONTRAST_MODE,
+	type NotionContrastMode,
+} from "@notionhq/custom-blocks-protocol/contrast.js"
+import type { NotionDataSourceId } 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 { ContrastModeChangedMessage } from "@notionhq/custom-blocks-protocol/messages/contrastModeChanged.js"
+import type { CreatePageMessage } from "@notionhq/custom-blocks-protocol/messages/createPage.js"
+import type { CreatePageResultMessage } from "@notionhq/custom-blocks-protocol/messages/createPageResult.js"
+import type { DataSourcesChangedMessage } from "@notionhq/custom-blocks-protocol/messages/dataSourcesChanged.js"
+import type {
+	GetPageMessage,
+	GetPageResultMessage,
+} from "@notionhq/custom-blocks-protocol/messages/getPage.js"
+import type {
+	GetUserMessage,
+	GetUserResultMessage,
+} from "@notionhq/custom-blocks-protocol/messages/getUser.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 { InitResultMessage } from "@notionhq/custom-blocks-protocol/messages/initResult.js"
+import type {
+	ListUsersMessage,
+	ListUsersResultMessage,
+} from "@notionhq/custom-blocks-protocol/messages/listUsers.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 { QueryDataSourceResultMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
+import { sandboxToHostMessageSchema } from "@notionhq/custom-blocks-protocol/messages/sandboxToHost.js"
+import type { ThemeChangedMessage } from "@notionhq/custom-blocks-protocol/messages/themeChanged.js"
+import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/messages/updatePage.js"
+import type { UpdatePageResultMessage } from "@notionhq/custom-blocks-protocol/messages/updatePageResult.js"
+import type { CustomBlockPage } from "@notionhq/custom-blocks-protocol/pages/page.js"
+import type { NotionParent } from "@notionhq/custom-blocks-protocol/parent.js"
+import { CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION } from "@notionhq/custom-blocks-protocol/protocolVersion.js"
+import type { NotionTheme } from "@notionhq/custom-blocks-protocol/theme.js"
+import type { NotionUser } from "@notionhq/custom-blocks-protocol/users/user.js"
+import * as v from "valibot"
+import { initErrorForFailureReason } from "./lifecycle/initErrors.js"
+import { createInitializationController } from "./lifecycle/initializationController.js"
+import type {
+	ConnectSuccessMessage,
+	CustomBlockHostDataSourcesPayload,
+	CustomBlockHostInitialState,
+} from "./lifecycle/types.js"
+import { getInvalidSandboxMessageResponse } from "./messages/invalidSandboxMessage.js"
+import type {
+	CustomBlockHostHandlers,
+	CustomBlockHostLogDirection,
+} from "./messages/types.js"
+import {
+	QuerySubscriptions,
+	type QuerySubscriptionToken,
+} from "./queries/querySubscriptions.js"
+import type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js"
+import { validateQueryDataSourceFilter } from "./queries/validateQueryDataSourceFilter.js"
+import { validateQueryDataSourceSorts } from "./queries/validateQueryDataSourceSorts.js"
+import { unreachable } from "./utils.js"
+
+export type CustomBlockHostOptions = {
+	iframe: HTMLIFrameElement
+	sandboxOrigin: string
+	minBridgeProtocolVersion: number
+	noConnectTimeoutMs?: number
+	noInitResultTimeoutMs?: number
+	initialState: CustomBlockHostInitialState
+	handlers: CustomBlockHostHandlers
+	onConnect?: (message: ConnectSuccessMessage) => void
+	onInitResult?: (message: InitResultMessage) => void
+	/**
+	 * A `connect` arrived after this host's initialization settled — the
+	 * document was replaced, or its first `connect` came after the host
+	 * stopped waiting. Either way the host cannot serve it: the embedder
+	 * should recreate host and iframe together so the document can run a
+	 * fresh handshake.
+	 */
+	onIgnoredConnect?: (message: ConnectMessage) => void
+	onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void
+}
+
+export type CustomBlockHostHandle = {
+	stop: () => void
+	post: (message: HostToSandboxMessage) => void
+	setTheme: (theme: NotionTheme) => void
+	setContrastMode: (contrastMode: NotionContrastMode) => void
+	setParent: (parent: NotionParent) => void
+	setPage: (page: CustomBlockPage) => void
+	setDataSources: (dataSources: CustomBlockHostDataSourcesPayload) => void
+	setCurrentUser: (currentUser: NotionUser) => void
+	refreshQuery: (args: { dataSourceId: NotionDataSourceId }) => void
+}
+
+const initializationIdentitySchema = v.object({
+	initializationId: v.string(),
+})
+
+export function createCustomBlockHost(
+	options: CustomBlockHostOptions,
+): CustomBlockHostHandle {
+	const {
+		iframe,
+		initialState,
+		handlers,
+		onConnect,
+		onInitResult,
+		onIgnoredConnect,
+		onLog,
+		sandboxOrigin,
+		minBridgeProtocolVersion: configuredMinBridgeProtocolVersion,
+		noConnectTimeoutMs,
+		noInitResultTimeoutMs,
+	} = options
+	const minBridgeProtocolVersion = Math.max(
+		configuredMinBridgeProtocolVersion ?? CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION,
+		CUSTOM_BLOCK_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
+	let activeDataSources: CustomBlockHostDataSourcesPayload | undefined
+	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) {
+		emit("out", message)
+		iframe.contentWindow?.postMessage(message, sandboxOrigin)
+	}
+
+	function postQueryDataSourceResult(args: {
+		subscriptionId: string
+		response: CustomBlockHostQueryDataSourceResult
+	}) {
+		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)
+	}
+
+	async function handleQuery(
+		message: QueryDataSourceMessage,
+		token: QuerySubscriptionToken = querySubscriptions.track(message),
+	) {
+		const collectionSchema = getCollectionSchema(
+			activeDataSources,
+			message.dataSourceId,
+		)
+		const filterError = validateQueryDataSourceFilter(
+			message.filter,
+			collectionSchema,
+		)
+		if (filterError !== undefined) {
+			if (querySubscriptions.isCurrent(message.subscriptionId, token)) {
+				postQueryDataSourceResult({
+					subscriptionId: message.subscriptionId,
+					response: { status: "error", error: filterError },
+				})
+			}
+			return
+		}
+		const sortError = validateQueryDataSourceSorts(
+			message.sorts,
+			collectionSchema,
+		)
+		if (sortError !== undefined) {
+			if (querySubscriptions.isCurrent(message.subscriptionId, token)) {
+				postQueryDataSourceResult({
+					subscriptionId: message.subscriptionId,
+					response: { status: "error", error: sortError },
+				})
+			}
+			return
+		}
+		const response = await handlers.queryDataSource(message)
+		if (!querySubscriptions.isCurrent(message.subscriptionId, token)) {
+			return
+		}
+		postQueryDataSourceResult({
+			subscriptionId: message.subscriptionId,
+			response,
+		})
+	}
+
+	async function handleCreatePage(message: CreatePageMessage) {
+		if (handlers.createPage === undefined) {
+			return
+		}
+		const response = await handlers.createPage(message)
+		const result: CreatePageResultMessage = {
+			type: "createPageResult",
+			requestId: message.requestId,
+			...response,
+		}
+		post(result)
+	}
+
+	async function handleGetPage(message: GetPageMessage) {
+		if (handlers.getPage === undefined) {
+			return
+		}
+		const response = await handlers.getPage(message)
+		const result: GetPageResultMessage = {
+			type: "getPageResult",
+			requestId: message.requestId,
+			...response,
+		}
+		post(result)
+	}
+
+	async function handleGetUser(message: GetUserMessage) {
+		if (handlers.getUser === undefined) {
+			return
+		}
+		const response = await handlers.getUser(message)
+		const result: GetUserResultMessage = {
+			type: "getUserResult",
+			requestId: message.requestId,
+			...response,
+		}
+		post(result)
+	}
+
+	async function handleListUsers(message: ListUsersMessage) {
+		if (handlers.listUsers === undefined) {
+			return
+		}
+		const response = await handlers.listUsers(message)
+		const result: ListUsersResultMessage = {
+			type: "listUsersResult",
+			requestId: message.requestId,
+			...response,
+		}
+		post(result)
+	}
+
+	async function handleUpdatePage(message: UpdatePageMessage) {
+		if (handlers.updatePage === undefined) {
+			return
+		}
+		const response = await handlers.updatePage(message)
+		const result: UpdatePageResultMessage = {
+			type: "updatePageResult",
+			requestId: message.requestId,
+			...response,
+		}
+		post(result)
+	}
+
+	/**
+	 * 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 (pendingContrastModeChange) {
+			pendingContrastModeChange = false
+			post({ type: "contrastModeChanged", contrastMode })
+		}
+		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 })
+		}
+	}
+
+	const initializationController = createInitializationController({
+		blockId: initialState.blockId,
+		getState: () => ({
+			theme,
+			contrastMode,
+			parent,
+			page,
+			currentUser,
+		}),
+		prepareInit(connect) {
+			manifest = connect.manifest ?? initialState.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,
+			}
+		},
+		post,
+		warn: payload => emit("warn", payload),
+		flushPendingHostStateChanges,
+		minBridgeProtocolVersion,
+		noConnectTimeoutMs,
+		noInitResultTimeoutMs,
+		onConnect,
+		onInitResult,
+		onIgnoredConnect,
+	})
+
+	function onInvalidSandboxMessage(
+		data: unknown,
+		issues: readonly v.BaseIssue<unknown>[],
+	) {
+		emit("warn", {
+			message: "Ignored unsupported sandbox message",
+			payload: data,
+			issues,
+		})
+		const response = getInvalidSandboxMessageResponse(data)
+
+		const parsedIdentity = v.safeParse(initializationIdentitySchema, data)
+		const initializationId = parsedIdentity.success
+			? parsedIdentity.output.initializationId
+			: undefined
+		if (
+			response.incomingType === "connect" &&
+			initializationId !== undefined &&
+			initializationController.handleInvalidConnect(initializationId)
+		) {
+			return
+		}
+		if (
+			response.incomingType === "initResult" &&
+			initializationController.handleInvalidInitResult()
+		) {
+			if (response.nack !== undefined) {
+				post(response.nack)
+			}
+			return
+		}
+		if (response.nack !== undefined) {
+			post(response.nack)
+		}
+	}
+
+	function onMessage(event: MessageEvent) {
+		// Ignore messages from windows other than this host's iframe.
+		if (event.source !== iframe.contentWindow) {
+			return
+		}
+
+		// Ignore messages that do not come from the configured sandbox origin.
+		if (event.origin !== sandboxOrigin) {
+			return
+		}
+
+		const parsed = v.safeParse(sandboxToHostMessageSchema, event.data)
+		if (!parsed.success) {
+			onInvalidSandboxMessage(event.data, parsed.issues)
+			return
+		}
+
+		const message = parsed.output
+		emit("in", message)
+
+		if (
+			message.type !== "connect" &&
+			message.type !== "initResult" &&
+			initializationController.status !== "success"
+		) {
+			// The SDK reports resize as soon as it renders, before the
+			// handshake completes, so an early resize is routine.
+			if (message.type !== "resize") {
+				emit("warn", {
+					message: `Ignored ${message.type} before initialization completed`,
+					payload: message,
+				})
+			}
+			return
+		}
+
+		switch (message.type) {
+			case "connect":
+				initializationController.handleConnect(message)
+				return
+			case "initResult":
+				initializationController.handleInitResult(message)
+				return
+			case "queryDataSource":
+				void handleQuery(message)
+				return
+			case "createPage":
+				void handleCreatePage(message)
+				return
+			case "getPage":
+				void handleGetPage(message)
+				return
+			case "getUser":
+				void handleGetUser(message)
+				return
+			case "listUsers":
+				void handleListUsers(message)
+				return
+			case "updatePage":
+				void handleUpdatePage(message)
+				return
+			case "resize":
+				handlers.resize?.(message)
+				return
+			case "invalidHostMessage":
+				return
+			default:
+				unreachable(message)
+		}
+	}
+
+	window.addEventListener("message", onMessage)
+	iframe.addEventListener("load", initializationController.onIframeLoad)
+
+	return {
+		stop() {
+			window.removeEventListener("message", onMessage)
+			iframe.removeEventListener("load", initializationController.onIframeLoad)
+			initializationController.stop()
+			querySubscriptions.clear()
+		},
+		post,
+		setTheme(nextTheme) {
+			theme = nextTheme
+			if (initializationController.status !== "success") {
+				if (initializationController.status === "waitingForInitResult") {
+					pendingThemeChange = true
+				}
+				return
+			}
+			const message: ThemeChangedMessage = { type: "themeChanged", theme }
+			post(message)
+		},
+		setContrastMode(nextContrastMode) {
+			contrastMode = nextContrastMode
+			if (initializationController.status !== "success") {
+				if (initializationController.status === "waitingForInitResult") {
+					pendingContrastModeChange = true
+				}
+				return
+			}
+			const message: ContrastModeChangedMessage = {
+				type: "contrastModeChanged",
+				contrastMode,
+			}
+			post(message)
+		},
+		setParent(nextParent) {
+			parent = nextParent
+			if (initializationController.status !== "success") {
+				if (initializationController.status === "waitingForInitResult") {
+					pendingParentChange = true
+				}
+				return
+			}
+			const message: ParentChangedMessage = { type: "parentChanged", parent }
+			post(message)
+		},
+		setPage(nextPage) {
+			page = nextPage
+			if (initializationController.status !== "success") {
+				if (initializationController.status === "waitingForInitResult") {
+					pendingPageChange = true
+				}
+				return
+			}
+			const message: PageChangedMessage = { type: "pageChanged", page }
+			post(message)
+		},
+		setDataSources(nextDataSources) {
+			if (
+				initializationController.hasConnectedSandbox &&
+				getBindingErrorCode(manifest, nextDataSources) !== undefined
+			) {
+				emit("warn", {
+					message: "Ignored invalid data source bindings update",
+					payload: nextDataSources,
+				})
+				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 })
+		},
+		refreshQuery({ dataSourceId }) {
+			if (initializationController.status !== "success") {
+				return
+			}
+			const refreshes = querySubscriptions.refresh(dataSourceId)
+			if (refreshes.length === 0) {
+				emit("warn", `No active query exists for data source "${dataSourceId}"`)
+				return
+			}
+			for (const refresh of refreshes) {
+				void handleQuery(refresh.message, refresh.token)
+			}
+		},
+	}
+}
+
+function getCollectionSchema(
+	dataSources: CustomBlockHostDataSourcesPayload | undefined,
+	dataSourceId: NotionDataSourceId,
+) {
+	return Object.values(dataSources?.bindings ?? {}).find(
+		binding => binding.collectionPointer?.id === dataSourceId,
+	)?.collectionSchema
+}
+
+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/index.ts

@@ -0,0 +1,25 @@
+export {
+	type AutoBindableProperty,
+	getAutoBoundPropertyIdsByKey,
+} from "./autoBindProperties.js"
+export {
+	type CustomBlockHostHandle,
+	type CustomBlockHostOptions,
+	createCustomBlockHost,
+} from "./createCustomBlockHost.js"
+export type {
+	ConnectSuccessMessage,
+	CustomBlockHostDataSourcesPayload,
+	CustomBlockHostInitialDataSources,
+	CustomBlockHostInitialState,
+} from "./lifecycle/types.js"
+export type {
+	CustomBlockHostCreatePageResult,
+	CustomBlockHostGetPageResult,
+	CustomBlockHostGetUserResult,
+	CustomBlockHostHandlers,
+	CustomBlockHostListUsersResult,
+	CustomBlockHostLogDirection,
+	CustomBlockHostUpdatePageResult,
+} from "./messages/types.js"
+export type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js"