@notionhq/custom-blocks-host 0.2.9 → 0.2.11

package/src/lifecycle/initErrors.ts

@@ -1,171 +1,125 @@
-import type {
-	CustomBlockInitErrorCode,
-	CustomBlockInitErrorInfo,
-} from "@notionhq/custom-blocks-protocol/messages/init.js"
-
-const UNKNOWN_ERROR_MESSAGE =
-	"Unexpected error while initializing custom block."
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/errors.js"
 
 /**
- * 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.
+ * Initialization handshakes are one-shot: after an error, this host instance will not answer
+ * another `connect` message. `isRetryable` means a fresh host and iframe could plausibly
+ * initialize 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 "init_timeout":
-			return {
-				code: reason,
-				message: "Host dependencies did not finish loading before the timeout.",
-				isRetryable: true,
-			}
-		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 "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,
-				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 "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,
-			}
+export function noConnectError(): CustomBlockErrorInfo<"no_connect"> {
+	return {
+		code: "no_connect",
+		message: "Sandbox did not send a connect message.",
+		// A fresh iframe may finish loading and send connect before the timeout.
+		isRetryable: true,
+	}
+}
+
+export function invalidConnectPayloadError(): CustomBlockErrorInfo<"invalid_connect_payload"> {
+	return {
+		code: "invalid_connect_payload",
+		message: "Sandbox sent an invalid connect message.",
+		// The sandbox must be updated to send a valid connect message.
+		isRetryable: false,
+	}
+}
+
+export function invalidProtocolVersionError(args: {
+	currentBridgeProtocolVersion: number | undefined
+}): CustomBlockErrorInfo<"invalid_protocol_version"> {
+	const { currentBridgeProtocolVersion } = args
+	const versionText = currentBridgeProtocolVersion
+		? `: ${currentBridgeProtocolVersion}`
+		: "."
+	return {
+		code: "invalid_protocol_version",
+		message: `Sandbox reported an invalid bridge protocol version ${versionText}`,
+		// The sandbox must be updated to a supported protocol version.
+		isRetryable: false,
+	}
+}
+
+export function unsupportedProtocolVersionError(args: {
+	currentBridgeProtocolVersion: number
+	minBridgeProtocolVersion: number
+}): CustomBlockErrorInfo<"unsupported_protocol_version"> {
+	const { currentBridgeProtocolVersion, minBridgeProtocolVersion } = args
+	return {
+		code: "unsupported_protocol_version",
+		message: `Sandbox bridge protocol version ${currentBridgeProtocolVersion} is not supported. Minimum supported version is ${minBridgeProtocolVersion}.`,
+		// The sandbox must be updated to a supported protocol version.
+		isRetryable: false,
+	}
+}
+
+export function contextUnavailableError(): CustomBlockErrorInfo<"context_unavailable"> {
+	return {
+		code: "context_unavailable",
+		message: "Host page context is unavailable.",
+		// Page context may become available before a fresh initialization attempt.
+		isRetryable: true,
+	}
+}
+
+export function initialStateTimeoutError(): CustomBlockErrorInfo<"initial_state_timeout"> {
+	return {
+		code: "initial_state_timeout",
+		message: "Host did not prepare initial state before the timeout.",
+		// A fresh attempt may finish loading host dependencies before the timeout.
+		isRetryable: true,
+	}
+}
+
+export function missingDataSourceBindingError(): CustomBlockErrorInfo<"missing_data_source_binding"> {
+	return {
+		code: "missing_data_source_binding",
+		message: "A required data source is not mapped.",
+		// Host configuration must be changed before this block can initialize.
+		isRetryable: false,
+	}
+}
+
+export function missingPropertyBindingError(): CustomBlockErrorInfo<"missing_property_binding"> {
+	return {
+		code: "missing_property_binding",
+		message: "A required data source property is not mapped.",
+		// Host configuration must be changed before this block can initialize.
+		isRetryable: false,
+	}
+}
+
+export function invalidPropertyBindingError(): CustomBlockErrorInfo<"invalid_property_binding"> {
+	return {
+		code: "invalid_property_binding",
+		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,
+	}
+}
+
+export function noInitResultError(): CustomBlockErrorInfo<"no_init_result"> {
+	return {
+		code: "no_init_result",
+		message: "Sandbox did not acknowledge initialization.",
+		// A fresh iframe may process init and acknowledge it before the timeout.
+		isRetryable: true,
+	}
+}
+
+export function invalidInitResultPayloadError(): CustomBlockErrorInfo<"invalid_init_result_payload"> {
+	return {
+		code: "invalid_init_result_payload",
+		message: "Sandbox sent an invalid initialization result.",
+		// The sandbox must be updated to send a valid initialization result.
+		isRetryable: false,
+	}
+}
+
+export function unknownInitializationError(): CustomBlockErrorInfo<"unknown_error"> {
+	return {
+		code: "unknown_error",
+		message: "Unexpected error while initializing custom block.",
+		// Without a known transient cause, conservatively treat unknown errors as non-retryable.
+		isRetryable: false,
 	}
 }

package/src/lifecycle/initializationController.ts

@@ -8,7 +8,14 @@ import type { InitResultMessage } from "@notionhq/custom-blocks-protocol/message
 import type { InferInput } from "valibot"
 import type { CustomBlockHostFailure } from "../messages/types.js"
 import { unreachable } from "../utils.js"
-import { initErrorForFailureReason } from "./initErrors.js"
+import {
+	initialStateTimeoutError,
+	invalidProtocolVersionError,
+	noConnectError,
+	noInitResultError,
+	unknownInitializationError,
+	unsupportedProtocolVersionError,
+} from "./initErrors.js"
 import { isValidBridgeProtocolVersion } from "./protocolVersion.js"
 import type {
 	ConnectSuccessMessage,
@@ -141,7 +148,7 @@ export function createInitializationController(
 			if (initStatus !== "preparingInit") {
 				return
 			}
-			const error = initErrorForFailureReason("initial_state_timeout")
+			const error = initialStateTimeoutError()
 			warn({
 				...error,
 				initializationId: connect.initializationId,
@@ -183,7 +190,7 @@ export function createInitializationController(
 					return
 				}
 				initStatus = "error"
-				const error = initErrorForFailureReason("no_init_result")
+				const error = noInitResultError()
 				onConnectionFailure?.(error)
 				warn({
 					...error,
@@ -200,7 +207,7 @@ export function createInitializationController(
 			})
 			sendInitError({
 				initializationId: connect.initializationId,
-				error: initErrorForFailureReason("unknown_error"),
+				error: unknownInitializationError(),
 			})
 		}
 	}
@@ -215,7 +222,7 @@ export function createInitializationController(
 
 		// Verify the bridge protocol version is valid.
 		if (!isValidBridgeProtocolVersion(message.bridgeProtocolVersion)) {
-			const initError = initErrorForFailureReason("invalid_protocol_version", {
+			const initError = invalidProtocolVersionError({
 				currentBridgeProtocolVersion: message.bridgeProtocolVersion,
 			})
 			sendInitError({
@@ -225,13 +232,10 @@ export function createInitializationController(
 			return
 		}
 		if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
-			const initError = initErrorForFailureReason(
-				"unsupported_protocol_version",
-				{
-					currentBridgeProtocolVersion: message.bridgeProtocolVersion,
-					minBridgeProtocolVersion,
-				},
-			)
+			const initError = unsupportedProtocolVersionError({
+				currentBridgeProtocolVersion: message.bridgeProtocolVersion,
+				minBridgeProtocolVersion,
+			})
 			sendInitError({
 				initializationId: message.initializationId,
 				error: initError,
@@ -273,9 +277,11 @@ export function createInitializationController(
 		// when the malformed message includes a numeric version.
 		if (bridgeProtocolVersion !== undefined) {
 			if (!isValidBridgeProtocolVersion(bridgeProtocolVersion)) {
-				error = initErrorForFailureReason("invalid_protocol_version")
+				error = invalidProtocolVersionError({
+					currentBridgeProtocolVersion: undefined,
+				})
 			} else if (bridgeProtocolVersion < minBridgeProtocolVersion) {
-				error = initErrorForFailureReason("unsupported_protocol_version", {
+				error = unsupportedProtocolVersionError({
 					currentBridgeProtocolVersion: bridgeProtocolVersion,
 					minBridgeProtocolVersion,
 				})
@@ -329,7 +335,7 @@ export function createInitializationController(
 				return
 			}
 			initStatus = "error"
-			const error = initErrorForFailureReason("no_connect")
+			const error = noConnectError()
 			warn(error)
 			onConnectionFailure?.(error)
 		}, noConnectTimeoutMs)

package/src/messages/sandboxMessageRouter.ts

@@ -13,7 +13,10 @@ import { sandboxToHostMessageSchema } from "@notionhq/custom-blocks-protocol/mes
 import type { UnsubscribeDataSourceQueryMessage } from "@notionhq/custom-blocks-protocol/messages/unsubscribeDataSourceQuery.js"
 import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/messages/updatePage.js"
 import * as v from "valibot"
-import { initErrorForFailureReason } from "../lifecycle/initErrors.js"
+import {
+	invalidConnectPayloadError,
+	invalidInitResultPayloadError,
+} from "../lifecycle/initErrors.js"
 import type { InitializationController } from "../lifecycle/initializationController.js"
 import type { InitStatus } from "../lifecycle/types.js"
 import { unreachable } from "../utils.js"
@@ -95,7 +98,7 @@ export function createSandboxMessageRouter(
 				initializationId: parsedIdentity.success
 					? parsedIdentity.output.initializationId
 					: undefined,
-				error: initErrorForFailureReason("invalid_connect_payload"),
+				error: invalidConnectPayloadError(),
 				bridgeProtocolVersion: parsedVersion.success
 					? parsedVersion.output.bridgeProtocolVersion
 					: undefined,
@@ -112,7 +115,7 @@ export function createSandboxMessageRouter(
 				initializationId: parsedIdentity.success
 					? parsedIdentity.output.initializationId
 					: undefined,
-				error: initErrorForFailureReason("invalid_init_result_payload"),
+				error: invalidInitResultPayloadError(),
 			})
 		}