@notionhq/custom-blocks-host 0.2.21 → 0.3.0

package/src/createCustomBlockHost.ts

@@ -4,7 +4,6 @@ import { notionDataSourceBindingsSchema } from "@notionhq/custom-blocks-protocol
 import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/ids.js"
 import { notionDataSourceIdSchema } from "@notionhq/custom-blocks-protocol/ids.js"
 import type { CustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest.js"
-import { manifestSchema } from "@notionhq/custom-blocks-protocol/manifest.js"
 import {
 	type HostToSandboxMessage,
 	hostToSandboxMessageSchema,
@@ -32,15 +31,18 @@ import {
 	invalidPropertyBindingError,
 	missingDataSourceBindingError,
 	missingPropertyBindingError,
+	unknownInitializationError,
 } from "./lifecycle/initErrors.js"
 import { createInitializationController } from "./lifecycle/initializationController.js"
+import { loadCustomBlockManifest } from "./lifecycle/loadCustomBlockManifest.js"
+import type { CustomBlockHostManifestOptions } from "./lifecycle/manifestOptions.js"
 import { normalizeHostToSandboxMessage } from "./lifecycle/normalizeHostToSandboxMessage.js"
 import type {
 	CustomBlockHostDataSourcesPayload,
-	CustomBlockHostGetInitialState,
 	CustomBlockHostInitialState,
 	CustomBlockHostInitialStateResult,
 	CustomBlockHostNormalizedDataSourcesPayload,
+	CustomBlockHostPrepareInitialState,
 } from "./lifecycle/types.js"
 import { customBlockHostInitialStateSchema } from "./lifecycle/types.js"
 import { createSandboxMessageRouter } from "./messages/sandboxMessageRouter.js"
@@ -63,7 +65,7 @@ import { unreachable } from "./utils.js"
 // Earlier SDKs cannot represent this context, so the host reports context_unavailable.
 const BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE = 5
 
-export type CustomBlockHostOptions = {
+export type CustomBlockHostOptions = CustomBlockHostManifestOptions & {
 	iframe: HTMLIFrameElement
 	sandboxOrigin: string
 	/**
@@ -75,8 +77,6 @@ export type CustomBlockHostOptions = {
 	noConnectTimeoutMs?: number
 	noInitResultTimeoutMs?: number
 	handlers: CustomBlockHostHandlers
-	/** Called as soon as the `manifest` is available after `connect`, before `onInitialized` and binding validation. */
-	onManifest?: (manifest: CustomBlockManifest) => void
 	/** Callback fired when the initialization handshake with the sandbox completed successfully. */
 	onInitialized?: (state: {
 		manifest: CustomBlockManifest
@@ -92,7 +92,8 @@ export type CustomBlockHostOptions = {
 	/** Releases adapter resources when a query ends, including replacement and terminal errors. */
 	onQueryUnsubscribed: ((subscriptionId: string) => void) | undefined
 	onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void
-	getInitialState: CustomBlockHostGetInitialState
+	/** Runs once, as soon as the manifest is validated, independently of connect. */
+	prepareInitialState: CustomBlockHostPrepareInitialState
 	initialStateTimeoutMs?: number
 }
 
@@ -122,9 +123,8 @@ export function createCustomBlockHost(
 ): CustomBlockHostHandle {
 	const {
 		iframe,
-		getInitialState,
+		prepareInitialState: prepareAdapterState,
 		handlers,
-		onManifest,
 		onInitialized,
 		onConnectionFailure,
 		onLog,
@@ -148,6 +148,7 @@ export function createCustomBlockHost(
 	>
 	let pendingState: HostStateUpdates = {}
 	let hasPreparedInitialState = false
+	const preparationController = new AbortController()
 	let manifest: CustomBlockManifest | undefined
 	let activeDataSources: CustomBlockHostNormalizedDataSourcesPayload | undefined
 	let sandboxBridgeProtocolVersion = LATEST_BRIDGE_PROTOCOL_VERSION
@@ -343,11 +344,11 @@ export function createCustomBlockHost(
 	const initializationController = createInitializationController({
 		async prepareInit(connect) {
 			sandboxBridgeProtocolVersion = connect.bridgeProtocolVersion
-			const result = await getInitialState(connect)
+			const result = await preparation
 			if (initializationController.status !== "preparingInit") {
 				return result
 			}
-			return prepareInitialState(result)
+			return finalizeInitialState(result)
 		},
 		sendInitMessage,
 		warn: payload => emit("warn", payload),
@@ -362,29 +363,25 @@ export function createCustomBlockHost(
 				onInitialized?.({ manifest, initialHeight: message.initialHeight })
 			}
 		},
-		onConnectionFailure,
+		onConnectionFailure: failure => {
+			preparationController.abort()
+			onConnectionFailure?.(failure)
+		},
 	})
 
-	function prepareInitialState(
+	function finalizeInitialState(
 		result: CustomBlockHostInitialStateResult,
 	): CustomBlockHostInitialStateResult {
 		if (result.status === "error") {
 			return result
 		}
-		manifest = v.parse(manifestSchema, result.initialState.manifest)
-		onManifest?.(manifest)
-		const initialStateInput = {
+		const initialState = v.parse(customBlockHostInitialStateSchema, {
 			...result.initialState,
 			...pendingState,
-		}
+		})
+		manifest = initialState.manifest
 		pendingState = {}
-		const initialState = {
-			...v.parse(
-				v.omit(customBlockHostInitialStateSchema, ["manifest"]),
-				initialStateInput,
-			),
-			manifest,
-		}
+
 		if (
 			sandboxBridgeProtocolVersion <
 				BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE &&
@@ -410,6 +407,49 @@ export function createCustomBlockHost(
 		return { status: "success", initialState }
 	}
 
+	// Attach rejection handling immediately: preparation may finish before connect.
+	const preparation = prepare().catch(
+		(error: unknown): CustomBlockHostInitialStateResult => {
+			if (!preparationController.signal.aborted) {
+				emit("warn", {
+					message: "Failed to prepare custom block initialization",
+					error,
+				})
+			}
+			return { status: "error", error: unknownInitializationError() }
+		},
+	)
+
+	async function prepare(): Promise<CustomBlockHostInitialStateResult> {
+		const loaded = await loadCustomBlockManifest({
+			...options,
+			sandboxOrigin,
+			signal: preparationController.signal,
+			onError: error => {
+				emit("warn", {
+					message: "Failed to load custom block manifest",
+					error,
+				})
+			},
+		})
+		if (loaded.status === "error") {
+			return loaded
+		}
+		if (preparationController.signal.aborted) {
+			return { status: "error", error: unknownInitializationError() }
+		}
+		const result = await prepareAdapterState({
+			manifest: loaded.manifest,
+			signal: preparationController.signal,
+		})
+		return result.status === "error"
+			? result
+			: {
+					status: "success",
+					initialState: { ...result.initialState, manifest: loaded.manifest },
+				}
+	}
+
 	const onMessage = createSandboxMessageRouter({
 		iframe,
 		sandboxOrigin,
@@ -436,6 +476,7 @@ export function createCustomBlockHost(
 	iframe.addEventListener("load", initializationController.onIframeLoad)
 
 	function stop() {
+		preparationController.abort()
 		window.removeEventListener("message", onMessage)
 		iframe.removeEventListener("load", initializationController.onIframeLoad)
 		initializationController.stop()

package/src/index.ts

@@ -5,6 +5,7 @@ export type {
 export type { NotionPropertySchemasById } from "@notionhq/custom-blocks-protocol/dataSources/propertySchema.js"
 export type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/errors.js"
 export type { NotionPageId } from "@notionhq/custom-blocks-protocol/ids.js"
+export type { CustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest.js"
 export type { CreatePageMessage } from "@notionhq/custom-blocks-protocol/messages/createPage.js"
 export type { GetPageMessage } from "@notionhq/custom-blocks-protocol/messages/getPage.js"
 export type { GetUserMessage } from "@notionhq/custom-blocks-protocol/messages/getUser.js"
@@ -53,12 +54,14 @@ export {
 	createCustomBlockHost,
 } from "./createCustomBlockHost.js"
 export { toNotionPageId } from "./ids.js"
+export type { CustomBlockHostManifestOptions } from "./lifecycle/manifestOptions.js"
 export type {
 	ConnectSuccessMessage,
 	CustomBlockHostDataSourcesPayload,
-	CustomBlockHostGetInitialState,
 	CustomBlockHostInitialState,
 	CustomBlockHostInitialStateResult,
+	CustomBlockHostPreparedStateResult,
+	CustomBlockHostPrepareInitialState,
 } from "./lifecycle/types.js"
 export { isLocalCustomBlockUrl } from "./localBlockUrl.js"
 export type {

package/src/lifecycle/loadCustomBlockManifest.ts

@@ -0,0 +1,89 @@
+import {
+	type CustomBlockManifest,
+	manifestSchema,
+} from "@notionhq/custom-blocks-protocol/manifest.js"
+import type { CustomBlockInitErrorInfo } from "@notionhq/custom-blocks-protocol/messages/init.js"
+import * as v from "valibot"
+import { isLocalCustomBlockUrl } from "../localBlockUrl.js"
+import type { CustomBlockHostManifestOptions } from "./manifestOptions.js"
+
+/** Internal to the host: preview requests never carry credentials or follow redirects. */
+export async function loadCustomBlockManifest(
+	args: CustomBlockHostManifestOptions & {
+		sandboxOrigin: string
+		signal: AbortSignal
+		onError: (error: unknown) => void
+	},
+): Promise<
+	| { status: "success"; manifest: CustomBlockManifest }
+	| { status: "error"; error: CustomBlockInitErrorInfo }
+> {
+	const controller = new AbortController()
+	const abort = () => controller.abort()
+	args.signal.addEventListener("abort", abort, { once: true })
+	const cancelled = new Promise<never>((_resolve, reject) => {
+		controller.signal.addEventListener(
+			"abort",
+			() => reject(controller.signal.reason),
+			{ once: true },
+		)
+	})
+	if (args.signal.aborted) {
+		controller.abort()
+	}
+	const timeout =
+		args.manifestSource === "local"
+			? window.setTimeout(() => {
+					controller.abort(
+						new Error("Manifest loading timed out after 5000 ms."),
+					)
+				}, 5_000)
+			: undefined
+	try {
+		const input = await Promise.race([
+			args.manifestSource === "local"
+				? fetchLocalCustomBlockManifest(args.sandboxOrigin, controller.signal)
+				: args.getPersistedManifest({ signal: controller.signal }),
+			cancelled,
+		])
+		if (controller.signal.aborted) {
+			throw new Error("Manifest loading was cancelled.")
+		}
+		return { status: "success", manifest: v.parse(manifestSchema, input) }
+	} catch (error) {
+		if (!args.signal.aborted) {
+			args.onError(error)
+		}
+		return {
+			status: "error",
+			error: {
+				code: "manifest_unavailable",
+				message: "The custom block manifest is unavailable.",
+				isRetryable: true,
+			},
+		}
+	} finally {
+		window.clearTimeout(timeout)
+		args.signal.removeEventListener("abort", abort)
+	}
+}
+
+async function fetchLocalCustomBlockManifest(
+	origin: string,
+	signal: AbortSignal,
+): Promise<unknown> {
+	const url = new URL(origin)
+	if (!isLocalCustomBlockUrl(url) || url.origin === window.location.origin) {
+		throw new Error("Preview requires a separate loopback origin.")
+	}
+	const response = await fetch(new URL("/manifest", url), {
+		credentials: "omit",
+		redirect: "error",
+		cache: "no-store",
+		signal,
+	})
+	if (!response.ok) {
+		throw new Error(`Manifest request failed: HTTP ${response.status}.`)
+	}
+	return response.json()
+}

package/src/lifecycle/manifestOptions.ts

@@ -0,0 +1,19 @@
+import type { manifestSchema } from "@notionhq/custom-blocks-protocol/manifest.js"
+import type { InferInput } from "valibot"
+
+/** Selects the manifest source used during host initialization. */
+export type CustomBlockHostManifestOptions =
+	| {
+			/** Calls getPersistedManifest for a saved definition or worker registry manifest. */
+			manifestSource: "persisted"
+			getPersistedManifest: (args: {
+				signal: AbortSignal
+			}) => Promise<InferInput<typeof manifestSchema> | undefined>
+	  }
+	| {
+			/**
+			 * Fetches /manifest from the loopback sandboxOrigin. No persisted fallback.
+			 * Local refers to the manifest server, not the host's environment.
+			 */
+			manifestSource: "local"
+	  }

package/src/lifecycle/types.ts

@@ -1,7 +1,10 @@
 import { notionContrastModeSchema } from "@notionhq/custom-blocks-protocol/contrast.js"
 import { notionDataSourceBindingsSchema } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
 import { notionBlockIdSchema } from "@notionhq/custom-blocks-protocol/ids.js"
-import { manifestSchema } from "@notionhq/custom-blocks-protocol/manifest.js"
+import {
+	type CustomBlockManifest,
+	manifestSchema,
+} from "@notionhq/custom-blocks-protocol/manifest.js"
 import type { ConnectMessage } from "@notionhq/custom-blocks-protocol/messages/connect.js"
 import type { CustomBlockInitErrorInfo } from "@notionhq/custom-blocks-protocol/messages/init.js"
 import { customBlockPageSchema } from "@notionhq/custom-blocks-protocol/pages/page.js"
@@ -19,7 +22,7 @@ export type ConnectSuccessMessage = Extract<
 export type InitStatus =
 	/** The host is waiting for the sandbox's first `connect` message. */
 	| "waitingForConnect"
-	/** The host is waiting for `getInitialState` to prepare `init`. */
+	/** The host is waiting for host state preparation to complete `init`. */
 	| "preparingInit"
 	/** The host is waiting for a matching `initResult` after it sends `init`. */
 	| "waitingForInitResult"
@@ -67,6 +70,15 @@ export type CustomBlockHostInitialStateResult =
 			error: CustomBlockInitErrorInfo
 	  }
 
-export type CustomBlockHostGetInitialState = (
-	connect: ConnectSuccessMessage,
-) => Promise<CustomBlockHostInitialStateResult>
+/** Adapter-owned state; the runtime adds its selected manifest to init. */
+export type CustomBlockHostPreparedStateResult =
+	| {
+			status: "success"
+			initialState: Omit<CustomBlockHostInitialState, "manifest">
+	  }
+	| { status: "error"; error: CustomBlockInitErrorInfo }
+
+export type CustomBlockHostPrepareInitialState = (args: {
+	manifest: CustomBlockManifest
+	signal: AbortSignal
+}) => Promise<CustomBlockHostPreparedStateResult>