@notionhq/custom-blocks 0.0.58

package/src/host/createCustomBlockHost.ts

@@ -0,0 +1,392 @@
+import * as v from "valibot"
+import type { NotionDataSourceId } from "../bridge/ids.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"
+import type {
+	GetPageMessage,
+	GetPageResultMessage,
+} from "../bridge/messages/getPage.js"
+import type {
+	GetUserMessage,
+	GetUserResultMessage,
+} from "../bridge/messages/getUser.js"
+import type { HostToSandboxMessage } from "../bridge/messages/hostToSandbox.js"
+import type {
+	CustomBlockInitErrorCode,
+	InitMessage,
+} from "../bridge/messages/init.js"
+import type {
+	ListUsersMessage,
+	ListUsersResultMessage,
+} from "../bridge/messages/listUsers.js"
+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"
+import type { UpdatePageResultMessage } from "../bridge/messages/updatePageResult.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"
+import { unreachable } from "../utils.js"
+import { initErrorForFailureReason } from "./lifecycle/initErrors.js"
+import { getReadyInitFailure } from "./lifecycle/ready.js"
+import type {
+	CustomBlockHostDataSourcesPayload,
+	CustomBlockHostInitialState,
+	InitStatus,
+	ReadySuccessMessage,
+} from "./lifecycle/types.js"
+import { getInvalidSandboxMessageResponse } from "./messages/invalidSandboxMessage.js"
+import type {
+	CustomBlockHostHandlers,
+	CustomBlockHostLogDirection,
+} from "./messages/types.js"
+import { QuerySubscriptions } from "./queries/querySubscriptions.js"
+import type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js"
+
+export type CustomBlockHostOptions = {
+	iframe: HTMLIFrameElement
+	targetOrigin?: string
+	minBridgeProtocolVersion?: number
+	noReadyTimeoutMs?: number
+	initialState: CustomBlockHostInitialState
+	handlers: CustomBlockHostHandlers
+	onReady?: (message: ReadySuccessMessage) => void
+	onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void
+}
+
+export type CustomBlockHostHandle = {
+	stop: () => void
+	post: (message: HostToSandboxMessage) => void
+	setTheme: (theme: NotionTheme) => void
+	setParent: (parent: NotionParent) => void
+	setPage: (page: CustomBlockPage) => void
+	setDataSources: (dataSources: CustomBlockHostDataSourcesPayload) => void
+	setCurrentUser: (currentUser: NotionUser) => void
+	refreshQuery: (args: {
+		dataSourceId: NotionDataSourceId
+		response: CustomBlockHostQueryDataSourceResult
+	}) => void
+}
+
+const DEFAULT_NO_READY_TIMEOUT_MS = 5_000
+const DEFAULT_MIN_BRIDGE_PROTOCOL_VERSION = 2
+
+export function createCustomBlockHost(
+	options: CustomBlockHostOptions,
+): CustomBlockHostHandle {
+	const {
+		iframe,
+		initialState,
+		handlers,
+		onReady,
+		onLog,
+		targetOrigin = "*",
+		minBridgeProtocolVersion = DEFAULT_MIN_BRIDGE_PROTOCOL_VERSION,
+		noReadyTimeoutMs = DEFAULT_NO_READY_TIMEOUT_MS,
+	} = options
+
+	let theme = initialState.theme
+	let parent = initialState.parent
+	let page = initialState.page
+	let dataSources = initialState.dataSources
+	let currentUser = initialState.currentUser
+	let initStatus: InitStatus = "pending"
+	let noReadyTimeoutId: number | undefined
+	const querySubscriptions = new QuerySubscriptions()
+
+	function emit(direction: CustomBlockHostLogDirection, payload: unknown) {
+		onLog?.(direction, payload)
+	}
+
+	function post(message: HostToSandboxMessage) {
+		emit("out", message)
+		iframe.contentWindow?.postMessage(message, targetOrigin)
+	}
+
+	function postQueryDataSourceResult(args: {
+		requestId: string
+		snapshotId: string
+		response: CustomBlockHostQueryDataSourceResult
+	}) {
+		const message: QueryDataSourceResultMessage = {
+			type: "queryDataSourceResult",
+			requestId: args.requestId,
+			snapshotId: args.snapshotId,
+			items: args.response.items,
+			hasMore: args.response.hasMore ?? false,
+			error: args.response.error,
+		}
+		post(message)
+	}
+
+	function clearNoReadyTimeout() {
+		if (noReadyTimeoutId !== undefined) {
+			window.clearTimeout(noReadyTimeoutId)
+			noReadyTimeoutId = undefined
+		}
+	}
+
+	function resolveDataSourcesPayload(
+		ready: ReadySuccessMessage,
+	): CustomBlockHostDataSourcesPayload {
+		return typeof dataSources === "function" ? dataSources(ready) : dataSources
+	}
+
+	function sendInit(ready: ReadySuccessMessage): boolean {
+		if (initStatus !== "pending") {
+			return false
+		}
+		initStatus = "success"
+		clearNoReadyTimeout()
+		const message: InitMessage = {
+			type: "init",
+			status: "success",
+			theme,
+			blockId: initialState.blockId,
+			parent,
+			page,
+			dataSources: resolveDataSourcesPayload(ready),
+			currentUser,
+		}
+		post(message)
+		return true
+	}
+
+	function sendInitError(code: CustomBlockInitErrorCode, message?: string) {
+		if (initStatus !== "pending") {
+			return
+		}
+		initStatus = "error"
+		clearNoReadyTimeout()
+		const error = initErrorForFailureReason(code)
+		post({
+			type: "init",
+			status: "error",
+			error: {
+				...error,
+				message: message ?? error.message,
+			},
+		})
+	}
+
+	function onIframeLoad() {
+		clearNoReadyTimeout()
+		noReadyTimeoutId = window.setTimeout(() => {
+			sendInitError("no_ready")
+		}, noReadyTimeoutMs)
+	}
+
+	async function handleQuery(message: QueryDataSourceMessage) {
+		querySubscriptions.track(message)
+		const response = await handlers.queryDataSource(message)
+		postQueryDataSourceResult({
+			requestId: message.requestId,
+			snapshotId: message.snapshotId,
+			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)
+	}
+
+	function handleReady(message: ReadyMessage) {
+		const failure = getReadyInitFailure(message, minBridgeProtocolVersion)
+		if (failure !== undefined) {
+			sendInitError(failure.code, failure.message)
+			return
+		}
+		if (message.status !== "success") {
+			return
+		}
+		if (sendInit(message)) {
+			onReady?.(message)
+		}
+	}
+
+	function onInvalidSandboxMessage(
+		data: unknown,
+		issues: readonly v.BaseIssue<unknown>[],
+	) {
+		emit("warn", {
+			message: "Ignored unsupported sandbox message",
+			payload: data,
+			issues,
+		})
+		const response = getInvalidSandboxMessageResponse(data)
+
+		if (initStatus === "pending" && response.incomingType === "ready") {
+			sendInitError("invalid_ready")
+		} else if (response.nack !== undefined) {
+			post(response.nack)
+		}
+	}
+
+	function onMessage(event: MessageEvent) {
+		if (event.source !== iframe.contentWindow) {
+			return
+		}
+
+		const parsed = v.safeParse(sandboxToHostMessageSchema, event.data)
+		if (!parsed.success) {
+			onInvalidSandboxMessage(event.data, parsed.issues)
+			return
+		}
+
+		const message = parsed.output
+		emit("in", message)
+
+		switch (message.type) {
+			case "ready":
+				handleReady(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", onIframeLoad)
+
+	return {
+		stop() {
+			window.removeEventListener("message", onMessage)
+			iframe.removeEventListener("load", onIframeLoad)
+			clearNoReadyTimeout()
+		},
+		post,
+		setTheme(nextTheme) {
+			theme = nextTheme
+			const message: ThemeChangedMessage = { type: "themeChanged", theme }
+			post(message)
+		},
+		setParent(nextParent) {
+			parent = nextParent
+			const message: ParentChangedMessage = { type: "parentChanged", parent }
+			post(message)
+		},
+		setPage(nextPage) {
+			page = nextPage
+			const message: PageChangedMessage = { type: "pageChanged", page }
+			post(message)
+		},
+		setDataSources(nextDataSources) {
+			dataSources = nextDataSources
+			const message: DataSourcesChangedMessage = {
+				type: "dataSourcesChanged",
+				dataSources: nextDataSources,
+			}
+			post(message)
+		},
+		setCurrentUser(nextCurrentUser) {
+			currentUser = nextCurrentUser
+			post({ type: "currentUserChanged", currentUser })
+		},
+		refreshQuery({ dataSourceId, response }) {
+			const refresh = querySubscriptions.resolveRefresh({
+				dataSourceId,
+				response,
+			})
+			if (refresh.status === "missing") {
+				emit("warn", `No active query exists for data source "${dataSourceId}"`)
+				return
+			}
+			postQueryDataSourceResult({
+				requestId: refresh.requestId,
+				snapshotId: refresh.snapshotId,
+				response: refresh.response,
+			})
+		},
+	}
+}

package/src/host/lifecycle/initErrors.ts

@@ -0,0 +1,132 @@
+import type {
+	CustomBlockInitErrorCode,
+	CustomBlockInitErrorInfo,
+} from "../../bridge/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
+ * `ready` message. `isRetryable` means a fresh iframe / `init` attempt could plausibly succeed
+ * without changing block code or host configuration.
+ */
+export function initErrorForFailureReason(
+	reason: CustomBlockInitErrorCode,
+): CustomBlockInitErrorInfo {
+	switch (reason) {
+		case "no_ready":
+			return {
+				code: reason,
+				message: "Sandbox did not send a ready message.",
+				isRetryable: true,
+			}
+		case "invalid_ready":
+			return {
+				code: reason,
+				message: "Sandbox sent an invalid ready message.",
+				// The sandbox must be updated to send a valid ready message.
+				isRetryable: false,
+			}
+		case "manifest_unavailable":
+			return {
+				code: reason,
+				message: "Sandbox could not load its manifest.",
+				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":
+			return {
+				code: reason,
+				message: "Sandbox reported an invalid bridge protocol version.",
+				// The sandbox must be updated to a supported protocol version.
+				isRetryable: false,
+			}
+		case "unsupported_protocol_version":
+			return {
+				code: reason,
+				message: "Sandbox bridge protocol version is not supported.",
+				// 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 "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/host/lifecycle/ready.ts

@@ -0,0 +1,36 @@
+import type { CustomBlockInitErrorCode } from "../../bridge/messages/init.js"
+import type { ReadyMessage } from "../../bridge/messages/ready.js"
+
+export type ReadyInitFailure = {
+	code: CustomBlockInitErrorCode
+	message?: string
+}
+
+export function getReadyInitFailure(
+	message: ReadyMessage,
+	minBridgeProtocolVersion: number,
+): ReadyInitFailure | undefined {
+	if (!isValidBridgeProtocolVersion(message.bridgeProtocolVersion)) {
+		return {
+			code: "invalid_protocol_version",
+			message: `Sandbox reported invalid bridge protocol version ${message.bridgeProtocolVersion}.`,
+		}
+	}
+	if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
+		return {
+			code: "unsupported_protocol_version",
+			message: `Sandbox bridge protocol version ${message.bridgeProtocolVersion} is below the host minimum ${minBridgeProtocolVersion}.`,
+		}
+	}
+	if (message.status === "error") {
+		return {
+			code: message.error.code,
+			message: message.error.message,
+		}
+	}
+	return undefined
+}
+
+function isValidBridgeProtocolVersion(version: number): boolean {
+	return Number.isFinite(version) && Number.isInteger(version) && version >= 1
+}

package/src/host/lifecycle/types.ts

@@ -0,0 +1,28 @@
+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 { 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 InitStatus = "pending" | "success" | "error"
+
+export type CustomBlockHostDataSourcesPayload = {
+	bindings: NotionDataSourceBindings
+}
+
+export type CustomBlockHostInitialDataSources =
+	| CustomBlockHostDataSourcesPayload
+	| ((ready: ReadySuccessMessage) => CustomBlockHostDataSourcesPayload)
+
+export type CustomBlockHostInitialState = {
+	theme: NotionTheme
+	blockId: NotionBlockId
+	parent: NotionParent
+	page: CustomBlockPage
+	dataSources: CustomBlockHostInitialDataSources
+	currentUser: NotionUser
+}

package/src/host/messages/invalidSandboxMessage.ts

@@ -0,0 +1,38 @@
+import { readIncomingType } from "../../bridge/incomingType.js"
+import type { InvalidSandboxMessage } from "../../bridge/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 === "ready") {
+		return "Invalid manifest"
+	}
+	if (incomingType !== undefined) {
+		return `Unsupported sandbox message of type "${incomingType}"`
+	}
+	return "Unsupported sandbox message (no `type` field or non-object payload)"
+}

package/src/host/messages/types.ts

@@ -0,0 +1,67 @@
+import type { CreatePageMessage } from "../../bridge/messages/createPage.js"
+import type { CustomBlockCreatePageErrorInfo } from "../../bridge/messages/createPageResult.js"
+import type {
+	CustomBlockGetPageErrorInfo,
+	GetPageMessage,
+} from "../../bridge/messages/getPage.js"
+import type {
+	CustomBlockGetUserErrorInfo,
+	GetUserMessage,
+} from "../../bridge/messages/getUser.js"
+import type {
+	CustomBlockListUsersErrorInfo,
+	ListUsersMessage,
+} from "../../bridge/messages/listUsers.js"
+import type { QueryDataSourceMessage } from "../../bridge/messages/queryDataSource.js"
+import type { ResizeMessage } from "../../bridge/messages/resize.js"
+import type { UpdatePageMessage } from "../../bridge/messages/updatePage.js"
+import type { CustomBlockUpdatePageErrorInfo } from "../../bridge/messages/updatePageResult.js"
+import type { NotionPage } from "../../bridge/pages/page.js"
+import type { NotionUser, NotionUserList } from "../../bridge/users/user.js"
+import type { CustomBlockHostQueryDataSourceResult } from "../queries/types.js"
+
+type MaybePromise<T> = T | Promise<T>
+
+export type CustomBlockHostCreatePageResult =
+	| { status: "success"; page: NotionPage }
+	| { status: "error"; error: CustomBlockCreatePageErrorInfo }
+
+export type CustomBlockHostGetPageResult =
+	| { status: "success"; page: NotionPage }
+	| { status: "error"; error: CustomBlockGetPageErrorInfo }
+
+export type CustomBlockHostUpdatePageResult =
+	| { status: "success"; page: NotionPage }
+	| { status: "error"; error: CustomBlockUpdatePageErrorInfo }
+
+export type CustomBlockHostGetUserResult =
+	| { status: "success"; user: NotionUser }
+	| { status: "error"; error: CustomBlockGetUserErrorInfo }
+
+export type CustomBlockHostListUsersResult =
+	| { status: "success"; list: NotionUserList }
+	| { status: "error"; error: 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"