@notionhq/custom-blocks 0.0.77 → 0.0.79

package/src/init.ts

@@ -1,19 +1,16 @@
 import type { NotionDataSource } from "./bridge/dataSources/dataSource.js"
 import type { NotionBlockId } from "./bridge/ids.js"
 import { loadManifest } from "./bridge/loadManifest.js"
-import {
-	CustomBlockInitError,
-	type CustomBlockInitErrorCode,
-	type InitMessage,
-} from "./bridge/messages/init.js"
+import { CustomBlockInitializationError } from "./bridge/messages/init.js"
 import type { CustomBlockPage } from "./bridge/pages/page.js"
 import type { NotionParent } from "./bridge/parent.js"
 import { customBlockHost } from "./bridge/sandboxClient.js"
 import type { NotionTheme } from "./bridge/theme.js"
 import type { NotionUser } from "./bridge/users/user.js"
+import { unreachable } from "./utils.js"
 
 /**
- * The payload sent by the host in the `init` message in response to the sandbox's `ready` message.
+ * The payload sent by the host in the `init` message in response to the sandbox's `connect` message.
  */
 export type CustomBlockInitPayload = {
 	theme: NotionTheme
@@ -30,16 +27,17 @@ export type CustomBlockInitPayload = {
  * `<NotionCustomBlock>` catches this specifically and falls back to a standalone preview with a
  * warning banner. Direct callers can `instanceof` it to apply their own policy.
  */
-export class NotInIframeError extends Error {
+export class NotInIframeError extends CustomBlockInitializationError {
 	constructor(message: string = NOT_IN_IFRAME_MESSAGE) {
-		super(message)
+		super({
+			code: "not_in_iframe",
+			message,
+			isRetryable: false,
+		})
 		this.name = "NotInIframeError"
-		this.code = "not_in_iframe"
-		this.isRetryable = false
 	}
 
-	code: CustomBlockInitErrorCode
-	isRetryable: boolean
+	declare code: "not_in_iframe"
 }
 
 /**
@@ -64,9 +62,10 @@ let initPromise: Promise<CustomBlockInitPayload> | undefined
 
 /**
  * Performs the SDK <-> host handshake: loads `custom_blocks.json`, posts
- * `ready`, then awaits the host's `init` message. Resolves with that payload.
+ * `connect`, then awaits the host's `init` message. Resolves after the sandbox
+ * applies the payload and returns `initResult.success`.
  *
- * Rejects with a `CustomBlockInitError` if the host doesn't respond inside `timeoutMs`.
+ * Rejects with a `CustomBlockInitializationError` if initialization fails.
  *
  * Idempotent: subsequent calls return the same promise as the first and ignore any new options.
  * Mount your React tree (or call any SDK hook / `customBlock.subscribe`) only after the
@@ -76,61 +75,75 @@ export function initCustomBlock(
 	opts: InitCustomBlockOptions = {},
 ): Promise<CustomBlockInitPayload> {
 	if (initPromise === undefined) {
-		initPromise = (async () => {
-			// Fail fast with a typed error when rendered as a standalone tab and not in a parent frame.
-			// Otherwise, it would eventually hit the timeout, since `postMessage` to `window.parent`
-			// would just hit the same window and never arrive.
-			if (typeof window !== "undefined" && window.parent === window) {
-				throw new NotInIframeError()
-			}
+		initPromise = initializeCustomBlock(opts)
+	}
+	return initPromise
+}
 
-			// Load the manifest and send it to the host.
-			const manifestResult = await loadManifest()
-			customBlockHost.sendReady(manifestResult)
+async function initializeCustomBlock(
+	opts: InitCustomBlockOptions,
+): Promise<CustomBlockInitPayload> {
+	try {
+		// Fail fast with a typed error when rendered as a standalone tab and not in a parent frame.
+		// Otherwise, it would eventually hit the timeout, since `postMessage` to `window.parent`
+		// would just hit the same window and never arrive.
+		if (typeof window !== "undefined" && window.parent === window) {
+			throw new NotInIframeError()
+		}
 
-			const timeoutMs = opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS
-			let message: InitMessage
-			try {
-				message = await customBlockHost.awaitInit(
-					AbortSignal.timeout(timeoutMs),
-				)
-			} catch (error) {
-				if (isTimeoutError(error)) {
-					throw new CustomBlockInitError({
-						code: "init_timeout",
-						message: "Host did not respond to init before the timeout.",
-						isRetryable: true,
-					})
-				}
-				throw error
-			}
-			if (message.status === "error") {
-				console.error(
-					`[custom-blocks-sdk] host reported init error (${message.error.code}): ${message.error.message}`,
-				)
-				throw new CustomBlockInitError(message.error)
-			}
+		// Load the manifest and send it to the host.
+		const manifestResult = await loadManifest()
+		customBlockHost.sendConnect(manifestResult)
 
-			const hostState = customBlockHost.getState()
-			if (hostState.status !== "initialized") {
-				throw new CustomBlockInitError({
+		const timeoutMs = opts.timeoutMs ?? DEFAULT_INIT_TIMEOUT_MS
+		await awaitHostInitWithTimeout(timeoutMs)
+
+		const hostState = customBlockHost.getState()
+		switch (hostState.status) {
+			case "initialized":
+				return {
+					theme: hostState.theme,
+					blockId: hostState.blockId,
+					parent: hostState.parent,
+					page: hostState.page,
+					currentUser: hostState.currentUser,
+					dataSources: hostState.dataSources,
+				}
+			case "uninitialized":
+				throw new CustomBlockInitializationError({
 					code: "context_unavailable",
 					message: "Host block payload is unavailable.",
 					isRetryable: true,
 				})
-			}
+			default:
+				return unreachable(hostState)
+		}
+	} catch (error) {
+		if (error instanceof CustomBlockInitializationError) {
+			throw error
+		}
+		const message = error instanceof Error ? error.message : String(error)
+		throw new CustomBlockInitializationError({
+			code: "unknown_error",
+			message,
+			isRetryable: false,
+		})
+	}
+}
 
-			return {
-				theme: message.theme,
-				blockId: hostState.blockId,
-				parent: hostState.parent,
-				page: hostState.page,
-				currentUser: message.currentUser,
-				dataSources: hostState.dataSources,
-			}
-		})()
+async function awaitHostInitWithTimeout(timeoutMs: number): Promise<void> {
+	try {
+		await customBlockHost.awaitInit(AbortSignal.timeout(timeoutMs))
+	} catch (error) {
+		if (isTimeoutError(error)) {
+			throw new CustomBlockInitializationError({
+				code: "init_timeout",
+				message: "Host did not respond to init before the timeout.",
+				isRetryable: true,
+			})
+		}
+		throw error
 	}
-	return initPromise
 }
 
 function isTimeoutError(error: unknown): boolean {

package/src/react/index.ts

@@ -13,7 +13,6 @@ export {
 } from "./NotionCustomBlock.js"
 export { useCustomBlockAutoResize } from "./useCustomBlockAutoResize.js"
 export {
-	type CustomBlockInitFailure,
 	type UseCustomBlockInitResult,
 	useCustomBlockInit,
 } from "./useCustomBlockInit.js"

package/src/react/standalonePreview.ts

@@ -8,11 +8,13 @@ const previewPageId = v.parse(notionPageIdSchema, "")
 export function seedStandalonePreviewState() {
 	customBlockHost.setMockState({
 		type: "init",
+		initializationId: "standalone-preview",
 		status: "success",
 		theme: "light",
 		blockId: previewBlockId,
 		parent: { type: "page_id", page_id: previewPageId },
 		page: { id: previewPageId, parent: { type: "workspace", workspace: true } },
+		manifest: { version: 1, dataSources: {} },
 		dataSources: { bindings: {} },
 		currentUser: {
 			object: "user",

package/src/react/useCustomBlockInit.ts

@@ -1,27 +1,24 @@
 import { useEffect, useState } from "react"
-import { CustomBlockInitError } from "../bridge/messages/init.js"
+import type { CustomBlockInitializationError } from "../bridge/messages/init.js"
 import {
 	type CustomBlockInitPayload,
 	type InitCustomBlockOptions,
 	initCustomBlock,
-	NotInIframeError,
 } from "../init.js"
 
-export type CustomBlockInitFailure = CustomBlockInitError | NotInIframeError
-
 /**
  * Discriminated state returned by {@link useCustomBlockInit}.
  *
  * Branch on `isLoaded`/`error`:
  * - `{ isLoaded: false, error: undefined }` — handshake in progress.
- * - `{ isLoaded: false, error: CustomBlockInitFailure }` — handshake failed (most commonly a
- *   `CustomBlockInitError` with code `init_timeout` because the host never sent `init`).
+ * - `{ isLoaded: false, error: CustomBlockInitializationError }` — handshake failed (most commonly a
+ *   `CustomBlockInitializationError` with code `init_timeout` because the host never sent `init`).
  * - `{ isLoaded: true, initial }` — handshake complete; safe to render
  *   children that call `useTheme`, `useBlockId`, etc.
  */
 export type UseCustomBlockInitResult =
 	| { isLoaded: false; error: undefined }
-	| { isLoaded: false; error: CustomBlockInitFailure }
+	| { isLoaded: false; error: CustomBlockInitializationError }
 	| { isLoaded: true; error: undefined; initial: CustomBlockInitPayload }
 
 /**
@@ -56,12 +53,9 @@ export function useCustomBlockInit(
 					setState({ isLoaded: true, error: undefined, initial })
 				}
 			},
-			err => {
+			error => {
 				if (!cancelled) {
-					setState({
-						isLoaded: false,
-						error: normalizeInitError(err),
-					})
+					setState({ isLoaded: false, error })
 				}
 			},
 		)
@@ -74,18 +68,3 @@ export function useCustomBlockInit(
 	}, [])
 	return state
 }
-
-function normalizeInitError(error: unknown): CustomBlockInitFailure {
-	if (
-		error instanceof CustomBlockInitError ||
-		error instanceof NotInIframeError
-	) {
-		return error
-	}
-	const message = error instanceof Error ? error.message : String(error)
-	return new CustomBlockInitError({
-		code: "unknown_error",
-		message,
-		isRetryable: false,
-	})
-}

package/src/react/useRuntimeState.ts

@@ -72,14 +72,15 @@ export function useCurrentUser(): NotionUser {
 }
 
 /**
- * Returns the author-declared manifest loaded from `custom_blocks.json` — the semantic
+ * Returns the authoritative manifest received from the host — the semantic
  * data-source keys plus their declared `name`, `description`, and property declarations.
- * `null` when the block ships no manifest.
+ *
+ * Throws if called before `initCustomBlock` has resolved.
  *
  * This is the configuration the block declared, not host-resolved bindings: use
  * `useDataSource(key)` for rows and resolved schema. Handy for enumerating the declared
  * data-source keys (e.g. picking a default key, or rendering a key switcher).
  */
-export function useManifest(): CustomBlockManifest | null {
+export function useManifest(): CustomBlockManifest {
 	return useSyncExternalStore(customBlock.subscribe, customBlock.getManifest)
 }

package/dist/bridge/messages/ready.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ready.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/bridge/messages/ready.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AA0B5B;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;IAG7B;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BASH,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA"}

package/dist/bridge/messages/ready.js

@@ -1,43 +0,0 @@
-import * as v from "valibot";
-import { manifestSchema } from "../manifest.js";
-const readyMessageCommonEntries = {
-    type: v.literal("ready"),
-    /**
-     * Used to ensure that the host and client are using the same version of the bridge protocol. A
-     * single host needs to support multiple custom blocks built with different versions of the bridge
-     * protocol. Increment this number any time a breaking change is made to the bridge protocol.
-     */
-    bridgeProtocolVersion: v.number(),
-    /**
-     * Semver version of the SDK package that sent this ready message. Should only be used for
-     * analytics purposes. Business logic should compare against `bridgeProtocolVersion` instead.
-     */
-    sdkVersion: v.string(),
-};
-// TODO(custom-blocks): Replace with `customBlockErrorInfoSchema` which makes `isRetryable` required
-// once min supported bridge protocol version is bumped to 3.
-const readyErrorSchema = v.object({
-    code: v.string(),
-    message: v.string(),
-    isRetryable: v.optional(v.boolean(), false),
-});
-/**
- * First message the sandbox sends after mount, kicking off the bridge handshake. The host replies
- * with `init`.
- */
-export const readyMessageSchema = v.union([
-    v.object({
-        status: v.literal("success"),
-        /**
-         * The data sources and settings the custom block expects, or null when the
-         * block has no manifest and no declared data requirements.
-         */
-        manifest: v.union([manifestSchema, v.null_()]),
-        ...readyMessageCommonEntries,
-    }),
-    v.object({
-        status: v.literal("error"),
-        error: readyErrorSchema,
-        ...readyMessageCommonEntries,
-    }),
-]);

package/dist/host/lifecycle/ready.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ready.d.ts","sourceRoot":"","sources":["../../../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/host/lifecycle/ready.ts"],"names":[],"mappings":"AAAA,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE"}

package/src/bridge/messages/ready.ts

@@ -1,48 +0,0 @@
-import * as v from "valibot"
-import { manifestSchema } from "../manifest.js"
-
-const readyMessageCommonEntries = {
-	type: v.literal("ready"),
-	/**
-	 * Used to ensure that the host and client are using the same version of the bridge protocol. A
-	 * single host needs to support multiple custom blocks built with different versions of the bridge
-	 * protocol. Increment this number any time a breaking change is made to the bridge protocol.
-	 */
-	bridgeProtocolVersion: v.number(),
-	/**
-	 * Semver version of the SDK package that sent this ready message. Should only be used for
-	 * analytics purposes. Business logic should compare against `bridgeProtocolVersion` instead.
-	 */
-	sdkVersion: v.string(),
-}
-
-// TODO(custom-blocks): Replace with `customBlockErrorInfoSchema` which makes `isRetryable` required
-// once min supported bridge protocol version is bumped to 3.
-const readyErrorSchema = v.object({
-	code: v.string(),
-	message: v.string(),
-	isRetryable: v.optional(v.boolean(), false),
-})
-
-/**
- * First message the sandbox sends after mount, kicking off the bridge handshake. The host replies
- * with `init`.
- */
-export const readyMessageSchema = v.union([
-	v.object({
-		status: v.literal("success"),
-		/**
-		 * The data sources and settings the custom block expects, or null when the
-		 * block has no manifest and no declared data requirements.
-		 */
-		manifest: v.union([manifestSchema, v.null_()]),
-		...readyMessageCommonEntries,
-	}),
-	v.object({
-		status: v.literal("error"),
-		error: readyErrorSchema,
-		...readyMessageCommonEntries,
-	}),
-])
-
-export type ReadyMessage = v.InferOutput<typeof readyMessageSchema>