@notionhq/custom-blocks-host 0.5.1 → 0.6.0

package/src/createCustomBlockHost.ts

@@ -148,6 +148,8 @@ export type CustomBlockHostHandle = {
  */
 type OneShotRequest = Extract<SandboxToHostMessage, { requestId: string }>
 
+type RequestError = { status: "error"; error: CustomBlockErrorInfo }
+
 export function createCustomBlockHost(
 	options: CustomBlockHostOptions,
 ): CustomBlockHostHandle {
@@ -247,22 +249,39 @@ export function createCustomBlockHost(
 	 * 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.
 	 */
-	async function respondToRequest<
+	async function handleRequest<
 		Request extends OneShotRequest,
 		Response extends object,
 	>(
 		message: Request,
 		handler: ((message: Request) => Response | Promise<Response>) | undefined,
 	) {
-		if (handler === undefined) {
-			return
+		try {
+			const response =
+				handler === undefined
+					? unsupportedOperation(message.type)
+					: await handler(message)
+			sendInitializedMessage({
+				...response,
+				type: `${message.type}Result`,
+				requestId: message.requestId,
+			})
+		} catch (error) {
+			if (initializationController.status !== "initialized") {
+				return
+			}
+			emit("warn", error)
+			sendInitializedMessage({
+				type: `${message.type}Result`,
+				requestId: message.requestId,
+				status: "error",
+				error: {
+					code: "unknown_error",
+					message: `The host could not complete ${message.type}.`,
+					isRetryable: false,
+				},
+			})
 		}
-		const response = await handler(message)
-		sendInitializedMessage({
-			type: `${message.type}Result` as const,
-			requestId: message.requestId,
-			...response,
-		})
 	}
 
 	function postQueryDataSourceResult(args: {
@@ -338,10 +357,12 @@ export function createCustomBlockHost(
 	}
 
 	async function handleOpenExternalUrl(message: OpenExternalUrlMessage) {
-		if (
-			handlers.openExternalUrl === undefined ||
-			navigationAbortController.signal.aborted
-		) {
+		if (navigationAbortController.signal.aborted) {
+			return
+		}
+		const handler = handlers.openExternalUrl
+		if (handler === undefined) {
+			await handleRequest(message, undefined)
 			return
 		}
 		if (pendingOpenExternalUrlRequestId === message.requestId) {
@@ -380,25 +401,12 @@ export function createCustomBlockHost(
 
 		pendingOpenExternalUrlRequestId = message.requestId
 		try {
-			const response = await handlers.openExternalUrl(
-				{ ...message, url },
-				{
-					signal: navigationAbortController.signal,
-				},
+			await handleRequest(message, () =>
+				handler(
+					{ ...message, url },
+					{ signal: navigationAbortController.signal },
+				),
 			)
-			if (navigationAbortController.signal.aborted) {
-				return
-			}
-			const result: OpenExternalUrlResultMessage = {
-				type: "openExternalUrlResult",
-				requestId: message.requestId,
-				...response,
-			}
-			sendInitializedMessage(result)
-		} catch (error) {
-			if (!navigationAbortController.signal.aborted) {
-				throw error
-			}
 		} finally {
 			if (pendingOpenExternalUrlRequestId === message.requestId) {
 				pendingOpenExternalUrlRequestId = undefined
@@ -595,6 +603,7 @@ export function createCustomBlockHost(
 		getInitStatus: () => initializationController.status,
 		emit,
 		sendNack,
+		sendPageMutationError: postToSandbox,
 		onInvalidConnect: initializationController.handleInvalidConnect,
 		onInvalidInitResult: initializationController.handleInvalidInitResult,
 		onConnect: initializationController.handleConnect,
@@ -603,12 +612,12 @@ export function createCustomBlockHost(
 		onUnsubscribeDataSourceQuery: message =>
 			querySubscriptions.unsubscribe(message.subscriptionId),
 		onOpenExternalUrl: handleOpenExternalUrl,
-		onCreatePage: message => respondToRequest(message, handlers.createPage),
-		onGetPage: message => respondToRequest(message, handlers.getPage),
-		onOpenPage: message => respondToRequest(message, handlers.openPage),
-		onGetUser: message => respondToRequest(message, handlers.getUser),
-		onListUsers: message => respondToRequest(message, handlers.listUsers),
-		onUpdatePage: message => respondToRequest(message, handlers.updatePage),
+		onCreatePage: message => handleRequest(message, handlers.createPage),
+		onGetPage: message => handleRequest(message, handlers.getPage),
+		onOpenPage: message => handleRequest(message, handlers.openPage),
+		onGetUser: message => handleRequest(message, handlers.getUser),
+		onListUsers: message => handleRequest(message, handlers.listUsers),
+		onUpdatePage: message => handleRequest(message, handlers.updatePage),
 		onResize: message => handlers.resize?.(message),
 	})
 
@@ -793,6 +802,17 @@ function getBindingError(
 	return undefined
 }
 
+function unsupportedOperation(type: string): RequestError {
+	return {
+		status: "error",
+		error: {
+			code: "unsupported_operation",
+			message: `The host does not support ${type}.`,
+			isRetryable: false,
+		},
+	}
+}
+
 function getQueryValidationError(
 	message: QueryDataSourceMessage,
 	collectionSchema: NotionCollectionSchema | undefined,

package/src/index.ts

@@ -44,6 +44,7 @@ export type {
 export type {
 	CreatePageMessageInput,
 	CustomBlockHostOpenPageResult,
+	CustomBlockHostPageIcon,
 	CustomBlockHostPageResult,
 	GetPageMessageInput,
 	OpenPageMessageInput,

package/src/messages/createSandboxMessageRouter.ts

@@ -6,10 +6,16 @@ import type { InitResultMessage } from "@notionhq/custom-blocks-protocol/handsha
 import { isInitHandshakeMessage } from "@notionhq/custom-blocks-protocol/handshake/isInitHandshakeMessage.js"
 import type { InvalidSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/invalidSandboxMessage.js"
 import type { OpenExternalUrlMessage } from "@notionhq/custom-blocks-protocol/navigation/openExternalUrl.js"
-import type { CreatePageMessage } from "@notionhq/custom-blocks-protocol/pages/messages/createPage.js"
+import type {
+	CreatePageMessage,
+	CreatePageResultMessage,
+} from "@notionhq/custom-blocks-protocol/pages/messages/createPage.js"
 import type { GetPageMessage } from "@notionhq/custom-blocks-protocol/pages/messages/getPage.js"
 import type { OpenPageMessage } from "@notionhq/custom-blocks-protocol/pages/messages/openPage.js"
-import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/pages/messages/updatePage.js"
+import type {
+	UpdatePageMessage,
+	UpdatePageResultMessage,
+} from "@notionhq/custom-blocks-protocol/pages/messages/updatePage.js"
 import type { GetUserMessage } from "@notionhq/custom-blocks-protocol/users/messages/getUser.js"
 import type { ListUsersMessage } from "@notionhq/custom-blocks-protocol/users/messages/listUsers.js"
 import * as v from "valibot"
@@ -20,6 +26,7 @@ import { invalidInitResultPayloadError } from "../lifecycle/errors/invalidInitRe
 import type { InitStatus } from "../lifecycle/types.js"
 import { unreachable } from "../utils/unreachable.js"
 import { getInvalidSandboxMessageResponse } from "./getInvalidSandboxMessageResponse.js"
+import { getInvalidNativeIconColorResponse } from "./invalidNativeIconColor.js"
 import type { CustomBlockHostLogDirection } from "./logging.js"
 
 const initializationIdentitySchema = v.object({
@@ -38,6 +45,9 @@ export type SandboxMessageRouterOptions = {
 	getInitStatus: () => InitStatus
 	emit: (direction: CustomBlockHostLogDirection, payload: unknown) => void
 	sendNack: (message: InvalidSandboxMessage) => void
+	sendPageMutationError: (
+		message: UpdatePageResultMessage | CreatePageResultMessage,
+	) => void
 	onInvalidConnect: InitializationController["handleInvalidConnect"]
 	onInvalidInitResult: InitializationController["handleInvalidInitResult"]
 	onConnect: (message: ConnectMessage) => void
@@ -65,6 +75,7 @@ export function createSandboxMessageRouter(
 		getInitStatus,
 		emit,
 		sendNack,
+		sendPageMutationError,
 		onInvalidConnect,
 		onInvalidInitResult,
 		onConnect,
@@ -85,6 +96,11 @@ export function createSandboxMessageRouter(
 		data: unknown,
 		issues: readonly v.BaseIssue<unknown>[],
 	) {
+		const iconError = getInvalidNativeIconColorResponse(data)
+		if (iconError !== undefined && getInitStatus() === "initialized") {
+			sendPageMutationError(iconError)
+			return
+		}
 		emit("warn", {
 			message: "Ignored unsupported sandbox message",
 			payload: redactExternalUrl(data),

package/src/messages/getInvalidSandboxMessageResponse.ts

@@ -1,5 +1,6 @@
 import { readIncomingType } from "@notionhq/custom-blocks-protocol/messages/incomingType.js"
 import type { InvalidSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/invalidSandboxMessage.js"
+import { readRequestId } from "@notionhq/custom-blocks-protocol/utils/readRequestId.js"
 
 export type InvalidSandboxMessageResponse = {
 	incomingType: string | undefined
@@ -16,10 +17,12 @@ export function getInvalidSandboxMessageResponse(
 	) {
 		return { incomingType }
 	}
+	const requestId = readRequestId(data)
 	return {
 		incomingType,
 		nack: {
 			type: "invalidSandboxMessage",
+			...(requestId !== undefined ? { requestId } : {}),
 			reason: nackReasonForInvalidSandboxMessage(incomingType),
 		},
 	}

package/src/messages/invalidNativeIconColor.ts

@@ -0,0 +1,43 @@
+import { notionIconColorSchema } from "@notionhq/custom-blocks-protocol/icons.js"
+import type { CreatePageResultMessage } from "@notionhq/custom-blocks-protocol/pages/messages/createPage.js"
+import type { UpdatePageResultMessage } from "@notionhq/custom-blocks-protocol/pages/messages/updatePage.js"
+import * as v from "valibot"
+
+const nativeIconMutationSchema = v.object({
+	type: v.picklist(["updatePage", "createPage"]),
+	requestId: v.string(),
+	icon: v.object({
+		type: v.literal("icon"),
+		icon: v.object({ color: v.unknown() }),
+	}),
+})
+
+/** Reject malformed colors with a correlated result before invoking a page mutation handler. */
+export function getInvalidNativeIconColorResponse(
+	data: unknown,
+): UpdatePageResultMessage | CreatePageResultMessage | undefined {
+	const parsed = v.safeParse(nativeIconMutationSchema, data)
+	if (!parsed.success) {
+		return
+	}
+	const color = parsed.output.icon.icon.color
+	if (
+		color === undefined ||
+		v.safeParse(notionIconColorSchema, color).success
+	) {
+		return
+	}
+	return {
+		type:
+			parsed.output.type === "createPage"
+				? "createPageResult"
+				: "updatePageResult",
+		requestId: parsed.output.requestId,
+		status: "error",
+		error: {
+			code: "invalid_icon_color",
+			message: "Use a supported Notion icon color.",
+			isRetryable: false,
+		},
+	}
+}

package/src/pages/types.ts

@@ -3,6 +3,7 @@ import type { createPageMessageSchema } from "@notionhq/custom-blocks-protocol/p
 import type { getPageMessageSchema } from "@notionhq/custom-blocks-protocol/pages/messages/getPage.js"
 import type { openPageMessageSchema } from "@notionhq/custom-blocks-protocol/pages/messages/openPage.js"
 import type { updatePageMessageSchema } from "@notionhq/custom-blocks-protocol/pages/messages/updatePage.js"
+import type { notionPageIconSchema } from "@notionhq/custom-blocks-protocol/pages/pageAppearance.js"
 import type { InferInput } from "valibot"
 import type { CustomBlockHostResult } from "../messages/result.js"
 
@@ -20,3 +21,5 @@ export type CustomBlockHostPageResult = CustomBlockHostResult<{
 export type CustomBlockHostOpenPageResult = CustomBlockHostResult<{
 	pageId: string
 }>
+
+export type CustomBlockHostPageIcon = InferInput<typeof notionPageIconSchema>