@notionhq/custom-blocks 0.0.63 → 0.0.65

package/dist/react/NotionCustomBlock.css

@@ -1,27 +1,27 @@
-.ncblock-standalone-banner {
-	--ncblock-standalone-banner-background: #fff8e1;
-	--ncblock-standalone-banner-border: #f0d77b;
-	--ncblock-standalone-banner-text: #5d4200;
+.custom-blocks-standalone-banner {
+	--custom-blocks-standalone-banner-background: #fff8e1;
+	--custom-blocks-standalone-banner-border: #f0d77b;
+	--custom-blocks-standalone-banner-text: #5d4200;
 
 	padding: 8px 12px;
-	background: var(--ncblock-standalone-banner-background);
-	color: var(--ncblock-standalone-banner-text);
-	border-bottom: 1px solid var(--ncblock-standalone-banner-border);
+	background: var(--custom-blocks-standalone-banner-background);
+	color: var(--custom-blocks-standalone-banner-text);
+	border-bottom: 1px solid var(--custom-blocks-standalone-banner-border);
 	font-size: 13px;
 	font-family: system-ui, sans-serif;
 	line-height: 1.4;
 }
 
-.ncblock-default-init-error {
-	--ncblock-init-error-background: #f7f7f5;
-	--ncblock-init-error-card-background: #ffffff;
-	--ncblock-init-error-border: #e5e5e1;
-	--ncblock-init-error-text: #1f1f1d;
-	--ncblock-init-error-muted-text: #5f5e5b;
-	--ncblock-init-error-eyebrow-text: #787774;
-	--ncblock-init-error-pre-background: #f1f1ef;
-	--ncblock-init-error-pre-text: #37352f;
-	--ncblock-init-error-shadow: rgba(0, 0, 0, 0.08);
+.custom-blocks-default-init-error {
+	--custom-blocks-init-error-background: #f7f7f5;
+	--custom-blocks-init-error-card-background: #ffffff;
+	--custom-blocks-init-error-border: #e5e5e1;
+	--custom-blocks-init-error-text: #1f1f1d;
+	--custom-blocks-init-error-muted-text: #5f5e5b;
+	--custom-blocks-init-error-eyebrow-text: #787774;
+	--custom-blocks-init-error-pre-background: #f1f1ef;
+	--custom-blocks-init-error-pre-text: #37352f;
+	--custom-blocks-init-error-shadow: rgba(0, 0, 0, 0.08);
 
 	box-sizing: border-box;
 	min-height: 240px;
@@ -29,81 +29,81 @@
 	align-items: center;
 	justify-content: center;
 	padding: 24px;
-	background: var(--ncblock-init-error-background);
-	color: var(--ncblock-init-error-text);
+	background: var(--custom-blocks-init-error-background);
+	color: var(--custom-blocks-init-error-text);
 	font-family: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
 	color-scheme: light;
 }
 
-.ncblock-default-init-error__card {
+.custom-blocks-default-init-error__card {
 	box-sizing: border-box;
 	width: 100%;
 	max-width: 420px;
 	padding: 20px;
-	border: 1px solid var(--ncblock-init-error-border);
+	border: 1px solid var(--custom-blocks-init-error-border);
 	border-radius: 12px;
-	background: var(--ncblock-init-error-card-background);
-	box-shadow: 0 8px 24px var(--ncblock-init-error-shadow);
+	background: var(--custom-blocks-init-error-card-background);
+	box-shadow: 0 8px 24px var(--custom-blocks-init-error-shadow);
 }
 
-.ncblock-default-init-error__eyebrow {
+.custom-blocks-default-init-error__eyebrow {
 	margin-bottom: 8px;
 	font-size: 11px;
 	font-weight: 600;
 	letter-spacing: 0.08em;
 	text-transform: uppercase;
-	color: var(--ncblock-init-error-eyebrow-text);
+	color: var(--custom-blocks-init-error-eyebrow-text);
 }
 
-.ncblock-default-init-error__title {
+.custom-blocks-default-init-error__title {
 	margin: 0;
 	font-size: 18px;
 	line-height: 1.3;
 	font-weight: 650;
 }
 
-.ncblock-default-init-error__body {
+.custom-blocks-default-init-error__body {
 	margin: 8px 0 0;
 	font-size: 14px;
 	line-height: 1.5;
-	color: var(--ncblock-init-error-muted-text);
+	color: var(--custom-blocks-init-error-muted-text);
 }
 
-.ncblock-default-init-error__details {
+.custom-blocks-default-init-error__details {
 	margin-top: 14px;
 	font-size: 12px;
-	color: var(--ncblock-init-error-muted-text);
+	color: var(--custom-blocks-init-error-muted-text);
 }
 
-.ncblock-default-init-error__pre {
+.custom-blocks-default-init-error__pre {
 	margin: 8px 0 0;
 	padding: 10px;
 	overflow: auto;
 	border-radius: 8px;
-	background: var(--ncblock-init-error-pre-background);
-	color: var(--ncblock-init-error-pre-text);
+	background: var(--custom-blocks-init-error-pre-background);
+	color: var(--custom-blocks-init-error-pre-text);
 	font-size: 12px;
 	line-height: 1.4;
 	white-space: pre-wrap;
 }
 
 @media (prefers-color-scheme: dark) {
-	.ncblock-standalone-banner {
-		--ncblock-standalone-banner-background: #3b2f0b;
-		--ncblock-standalone-banner-border: #6f5713;
-		--ncblock-standalone-banner-text: #f5d36c;
+	.custom-blocks-standalone-banner {
+		--custom-blocks-standalone-banner-background: #3b2f0b;
+		--custom-blocks-standalone-banner-border: #6f5713;
+		--custom-blocks-standalone-banner-text: #f5d36c;
 	}
 
-	.ncblock-default-init-error {
-		--ncblock-init-error-background: #191918;
-		--ncblock-init-error-card-background: #20201f;
-		--ncblock-init-error-border: #373633;
-		--ncblock-init-error-text: #f1f1ef;
-		--ncblock-init-error-muted-text: #b9b8b3;
-		--ncblock-init-error-eyebrow-text: #9b9a97;
-		--ncblock-init-error-pre-background: #2a2a28;
-		--ncblock-init-error-pre-text: #e8e8e4;
-		--ncblock-init-error-shadow: rgba(0, 0, 0, 0.35);
+	.custom-blocks-default-init-error {
+		--custom-blocks-init-error-background: #191918;
+		--custom-blocks-init-error-card-background: #20201f;
+		--custom-blocks-init-error-border: #373633;
+		--custom-blocks-init-error-text: #f1f1ef;
+		--custom-blocks-init-error-muted-text: #b9b8b3;
+		--custom-blocks-init-error-eyebrow-text: #9b9a97;
+		--custom-blocks-init-error-pre-background: #2a2a28;
+		--custom-blocks-init-error-pre-text: #e8e8e4;
+		--custom-blocks-init-error-shadow: rgba(0, 0, 0, 0.35);
 
 		color-scheme: dark;
 	}

package/dist/react/NotionCustomBlock.js

@@ -45,7 +45,7 @@ export function NotionCustomBlock({ children, timeoutMs, fallback = null, errorF
         if (!isStandalone) {
             return;
         }
-        console.warn(`[notion-custom-sdk] ${init.error?.message}`);
+        console.warn(`[custom-blocks-sdk] ${init.error?.message}`);
         seedStandalonePreviewState();
     }, [isStandalone, init.error]);
     if (debugOpen) {
@@ -65,7 +65,7 @@ export function NotionCustomBlock({ children, timeoutMs, fallback = null, errorF
         if (host.status !== "initialized") {
             return _jsx(_Fragment, { children: fallback });
         }
-        return (_jsxs(_Fragment, { children: [_jsx("div", { role: "status", className: "ncblock-standalone-banner", children: "Notion host not detected \u2014 running in standalone preview. SDK hooks return placeholder values until embedded in Notion." }), children] }));
+        return (_jsxs(_Fragment, { children: [_jsx("div", { role: "status", className: "custom-blocks-standalone-banner", children: "Notion host not detected \u2014 running in standalone preview. SDK hooks return placeholder values until embedded in Notion." }), children] }));
     }
     if (!init.isLoaded) {
         return _jsx(_Fragment, { children: fallback });
@@ -75,7 +75,7 @@ export function NotionCustomBlock({ children, timeoutMs, fallback = null, errorF
 // TODO(custom-blocks): Align the styling of this with the host-side error states.
 function DefaultInitErrorFallback({ error }) {
     useEffect(() => {
-        console.warn(`[notion-custom-sdk] Custom block init failed: ${error.message}`);
+        console.warn(`[custom-blocks-sdk] Custom block init failed: ${error.message}`);
     }, [error]);
-    return (_jsx("div", { role: "alert", className: "ncblock-default-init-error", children: _jsxs("div", { className: "ncblock-default-init-error__card", children: [_jsx("div", { className: "ncblock-default-init-error__eyebrow", children: "Custom block" }), _jsx("h2", { className: "ncblock-default-init-error__title", children: "Couldn't connect to Notion" }), _jsx("p", { className: "ncblock-default-init-error__body", children: "This custom block loaded, but the setup handshake didn't finish. Try again from Notion. If this keeps happening, check the browser console for SDK details." }), _jsxs("details", { className: "ncblock-default-init-error__details", children: [_jsx("summary", { children: "Developer details" }), _jsx("pre", { className: "ncblock-default-init-error__pre", children: error.message })] })] }) }));
+    return (_jsx("div", { role: "alert", className: "custom-blocks-default-init-error", children: _jsxs("div", { className: "custom-blocks-default-init-error__card", children: [_jsx("div", { className: "custom-blocks-default-init-error__eyebrow", children: "Custom block" }), _jsx("h2", { className: "custom-blocks-default-init-error__title", children: "Couldn't connect to Notion" }), _jsx("p", { className: "custom-blocks-default-init-error__body", children: "This custom block loaded, but the setup handshake didn't finish. Try again from Notion. If this keeps happening, check the browser console for SDK details." }), _jsxs("details", { className: "custom-blocks-default-init-error__details", children: [_jsx("summary", { children: "Developer details" }), _jsx("pre", { className: "custom-blocks-default-init-error__pre", children: error.message })] })] }) }));
 }

package/dist/utils.js

@@ -6,5 +6,5 @@
  * are covered when using discriminated unions.
  */
 export function unreachable(value) {
-    throw new Error(`[notion-custom-sdk] Unexpected value encountered: ${JSON.stringify(value)}`);
+    throw new Error(`[custom-blocks-sdk] Unexpected value encountered: ${JSON.stringify(value)}`);
 }

package/dist/version.d.ts

@@ -5,5 +5,5 @@
  * This checked-in value intentionally stays generic for local development. The SDK publish build
  * overwrites the compiled runtime module with package.json's semver before publishing.
  */
-export declare const NCBLOCK_SDK_VERSION: string;
+export declare const CUSTOM_BLOCKS_SDK_VERSION: string;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAgB,CAAA"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../home/runner/work/custom-blocks/custom-blocks/sdk/src/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAgB,CAAA"}

package/dist/version.js

@@ -4,4 +4,4 @@
  *
  * WARNING: Generated during SDK publish. Do not edit in the published package.
  */
-export const NCBLOCK_SDK_VERSION = "0.0.63"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.0.65"

package/docs/block-location.md

@@ -46,7 +46,7 @@ For non-React renderers, use `customBlock.getParent()` after `initCustomBlock()`
 To identify custom blocks in agent-owned instruction content:
 
 ```tsx
-import { useParent } from "ncblock"
+import { useParent } from "@notionhq/custom-blocks"
 
 export function AgentInstructionBadge() {
   const parent = useParent()

package/docs/manifest.md

@@ -1,6 +1,6 @@
 # Manifest
 
-A custom view declares its required data sources in `custom_blocks.json` at the project root. Notion uses the manifest to know what semantic keys the block expects, what shape each property should be, and what to show when an admin is configuring the block.
+A custom block declares its required data sources in `custom_blocks.json` at the project root. Notion uses the manifest to know what semantic keys the block expects, what shape each property should be, and what to show when an admin is configuring the block.
 
 ```json
 {
@@ -18,7 +18,7 @@ A custom view declares its required data sources in `custom_blocks.json` at the
 }
 ```
 
-`initCustomBlock()` fetches `custom_blocks.json` and forwards it with `ready`. The `notionCustomBlock()` Vite plugin from `@notionhq/custom-blocks/vite` serves it in dev and emits it into `dist/` on build. If the file is missing, the SDK sends `ready` with `status: "success"` and `manifest: null`, which means the block has no declared data requirements. If the file is unavailable for another reason or invalid, the SDK sends `ready` with `status: "error"` and an `error` payload, and hosts should reject init by echoing the sandbox-reported error code back.
+`initCustomBlock()` fetches the manifest and forwards it with `ready`. The `notionCustomBlock()` Vite plugin from `@notionhq/custom-blocks/vite` serves it in dev and emits it into `dist/` on build. If the file is missing, the SDK sends `ready` with `status: "success"` and `manifest: null`, which means the block has no declared data requirements. If the file is unavailable for another reason or invalid, the SDK sends `ready` with `status: "error"` and an `error` payload. Hosts should reject `init` by forwarding that full error payload unchanged.
 
 ## Vite plugin
 

package/docs/pages.md

@@ -53,7 +53,7 @@ type CreatePageParent =
   | { type: "data_source_key"; key: string };
 ```
 
-`type: "data_source_key"` is the recommended form inside a custom view. Pass the semantic key you declared in `custom_blocks.json` (e.g. `"tasks"`) and the SDK looks up the corresponding data source for you. The other two variants exist for the rarer case where you already have a raw Notion ID in hand.
+`type: "data_source_key"` is the recommended form inside a custom block. Pass the semantic key you declared in `custom_blocks.json` (e.g. `"tasks"`) and the SDK looks up the corresponding data source for you. The other two variants exist for the rarer case where you already have a raw Notion ID in hand.
 
 ### Property keys
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.0.63",
+	"version": "0.0.65",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {

package/src/bridge/SandboxBridge.ts

@@ -13,7 +13,7 @@ import type {
 	UseDataSourceOptions,
 } from "../types.js"
 import { unreachable } from "../utils.js"
-import { NCBLOCK_SDK_VERSION } from "../version.js"
+import { CUSTOM_BLOCKS_SDK_VERSION } from "../version.js"
 import type {
 	NotionDataSource,
 	NotionDataSourceBindings,
@@ -167,7 +167,7 @@ export class SandboxBridge {
 			return
 		}
 		if (this.hasSentReady) {
-			console.warn("[notion-custom-sdk] ignoring duplicate ready message")
+			console.warn("[custom-blocks-sdk] ignoring duplicate ready message")
 			return
 		}
 		const { manifest, error } = manifestResult
@@ -179,21 +179,21 @@ export class SandboxBridge {
 						type: "ready",
 						status: "error",
 						bridgeProtocolVersion: CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION,
-						sdkVersion: NCBLOCK_SDK_VERSION,
+						sdkVersion: CUSTOM_BLOCKS_SDK_VERSION,
 						error,
 					}
 				: {
 						type: "ready",
 						status: "success",
 						bridgeProtocolVersion: CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION,
-						sdkVersion: NCBLOCK_SDK_VERSION,
+						sdkVersion: CUSTOM_BLOCKS_SDK_VERSION,
 						manifest,
 					}
 		this.postToHost(readyMessage)
 	}
 
 	private postToHost(message: unknown) {
-		console.debug("[notion-custom-sdk] outbound postMessage", message)
+		console.debug("[custom-blocks-sdk] outbound postMessage", message)
 		this.logMessage("sent", message)
 		window.parent.postMessage(message, "*")
 	}
@@ -205,7 +205,7 @@ export class SandboxBridge {
 	}
 
 	private handleMessage = (event: MessageEvent) => {
-		console.debug("[notion-custom-sdk] incoming postMessage", {
+		console.debug("[custom-blocks-sdk] incoming postMessage", {
 			data: event.data,
 			fromParent: event.source === window.parent,
 		})
@@ -217,7 +217,7 @@ export class SandboxBridge {
 		const parsed = v.safeParse(hostToSandboxMessageSchema, event.data)
 		if (!parsed.success) {
 			console.warn(
-				"[notion-custom-sdk] ignoring malformed host message",
+				"[custom-blocks-sdk] ignoring malformed host message",
 				parsed.issues,
 			)
 			const incomingType = readIncomingType(event.data)
@@ -245,7 +245,7 @@ export class SandboxBridge {
 		// failure on its own.
 		if (message.type === "invalidSandboxMessage") {
 			console.warn(
-				"[notion-custom-sdk] host reported invalid sandbox message:",
+				"[custom-blocks-sdk] host reported invalid sandbox message:",
 				message.reason,
 			)
 			return
@@ -263,7 +263,7 @@ export class SandboxBridge {
 		const hostState = this.hostState
 
 		if (hostState.status !== "initialized") {
-			console.warn(`[notion-custom-sdk] ignoring ${message.type} before init`)
+			console.warn(`[custom-blocks-sdk] ignoring ${message.type} before init`)
 			return
 		}
 
@@ -340,7 +340,7 @@ export class SandboxBridge {
 						: { status: "error", error: message.error }
 				if (!this.pendingCreatePage.resolve(message.requestId, result)) {
 					console.warn(
-						`[notion-custom-sdk] createPageResult for unknown requestId ${message.requestId}`,
+						`[custom-blocks-sdk] createPageResult for unknown requestId ${message.requestId}`,
 					)
 				}
 				return
@@ -353,7 +353,7 @@ export class SandboxBridge {
 						: { status: "error", error: message.error }
 				if (!this.pendingGetPage.resolve(message.requestId, result)) {
 					console.warn(
-						`[notion-custom-sdk] getPageResult for unknown requestId ${message.requestId}`,
+						`[custom-blocks-sdk] getPageResult for unknown requestId ${message.requestId}`,
 					)
 				}
 				return
@@ -366,7 +366,7 @@ export class SandboxBridge {
 						: { status: "error", error: message.error }
 				if (!this.pendingGetUser.resolve(message.requestId, result)) {
 					console.warn(
-						`[notion-custom-sdk] getUserResult for unknown requestId ${message.requestId}`,
+						`[custom-blocks-sdk] getUserResult for unknown requestId ${message.requestId}`,
 					)
 				}
 				return
@@ -379,7 +379,7 @@ export class SandboxBridge {
 						: { status: "error", error: message.error }
 				if (!this.pendingListUsers.resolve(message.requestId, result)) {
 					console.warn(
-						`[notion-custom-sdk] listUsersResult for unknown requestId ${message.requestId}`,
+						`[custom-blocks-sdk] listUsersResult for unknown requestId ${message.requestId}`,
 					)
 				}
 				return
@@ -392,7 +392,7 @@ export class SandboxBridge {
 						: { status: "error", error: message.error }
 				if (!this.pendingUpdatePage.resolve(message.requestId, result)) {
 					console.warn(
-						`[notion-custom-sdk] updatePageResult for unknown requestId ${message.requestId}`,
+						`[custom-blocks-sdk] updatePageResult for unknown requestId ${message.requestId}`,
 					)
 				}
 				return
@@ -492,7 +492,7 @@ export class SandboxBridge {
 			// the browser console either way. We deliberately don't NACK the host or post anything
 			// back over the bridge since the host has already given up.
 			console.error(
-				`[notion-custom-sdk] host reported init error (${message.error.code}): ${message.error.message}`,
+				`[custom-blocks-sdk] host reported init error (${message.error.code}): ${message.error.message}`,
 			)
 			if (this.rejectInit) {
 				this.rejectInit(new CustomBlockInitError(message.error))
@@ -900,13 +900,13 @@ function resolveDataSourceQueryLimit(limit: number | undefined): number {
 	}
 	if (!Number.isFinite(limit) || !Number.isInteger(limit) || limit < 1) {
 		console.warn(
-			`[notion-custom-sdk] useDataSource limit must be a positive integer; using ${DEFAULT_DATA_SOURCE_QUERY_LIMIT}.`,
+			`[custom-blocks-sdk] useDataSource limit must be a positive integer; using ${DEFAULT_DATA_SOURCE_QUERY_LIMIT}.`,
 		)
 		return DEFAULT_DATA_SOURCE_QUERY_LIMIT
 	}
 	if (limit > MAX_DATA_SOURCE_QUERY_LIMIT) {
 		console.warn(
-			`[notion-custom-sdk] useDataSource limit is capped at ${MAX_DATA_SOURCE_QUERY_LIMIT}.`,
+			`[custom-blocks-sdk] useDataSource limit is capped at ${MAX_DATA_SOURCE_QUERY_LIMIT}.`,
 		)
 		return MAX_DATA_SOURCE_QUERY_LIMIT
 	}

package/src/bridge/loadManifest.ts

@@ -1,25 +1,16 @@
 import * as v from "valibot"
+import type { CustomBlockErrorInfo } from "./errors.js"
 import { type CustomBlockManifest, manifestSchema } from "./manifest.js"
 
 const MANIFEST_URL = "custom_blocks.json"
 
-// The schema accepts any string code. The type lists known codes for
-// autocomplete, with an open string fallback for newer senders.
-export const customBlockReadyErrorCodeSchema = v.string()
-
 export type CustomBlockReadyErrorCode =
 	| "manifest_unavailable"
 	| "manifest_invalid"
 	| (string & {})
 
-export const customBlockReadyErrorSchema = v.object({
-	code: customBlockReadyErrorCodeSchema,
-	message: v.string(),
-})
-
-export type CustomBlockReadyError = v.InferOutput<
-	typeof customBlockReadyErrorSchema
->
+export type CustomBlockReadyError =
+	CustomBlockErrorInfo<CustomBlockReadyErrorCode>
 
 export type ManifestLoadResult =
 	| {
@@ -41,10 +32,10 @@ export type ManifestLoadResult =
 export async function loadManifest(): Promise<ManifestLoadResult> {
 	if (typeof fetch !== "function") {
 		const message = `No fetch API available; cannot load ${MANIFEST_URL}.`
-		console.warn(`[notion-custom-sdk] ${message}`)
+		console.warn(`[custom-blocks-sdk] ${message}`)
 		return {
 			manifest: null,
-			error: { code: "manifest_unavailable", message },
+			error: { code: "manifest_unavailable", message, isRetryable: true },
 		}
 	}
 	let response: Response
@@ -52,38 +43,68 @@ export async function loadManifest(): Promise<ManifestLoadResult> {
 		response = await fetch(MANIFEST_URL, { credentials: "omit" })
 	} catch (error) {
 		const message = `Could not fetch ${MANIFEST_URL}.`
-		console.warn(`[notion-custom-sdk] ${message}`, error)
+		console.warn(`[custom-blocks-sdk] ${message}`, error)
 		return {
 			manifest: null,
-			error: { code: "manifest_unavailable", message },
+			// Consider this retryable because it may have just been a network issue. Because `init`
+			// errors are considered terminal, the host should "retry" by reloading the iframe and
+			// sending another `ready` message.
+			error: { code: "manifest_unavailable", message, isRetryable: true },
 		}
 	}
 	if (response.status === 404) {
 		const message = `No manifest found at ${MANIFEST_URL} (status ${response.status}).`
-		console.warn(`[notion-custom-sdk] ${message}`)
+		console.warn(`[custom-blocks-sdk] ${message}`)
 		return { manifest: null }
 	}
 	if (!response.ok) {
 		const message = `Could not fetch ${MANIFEST_URL} (status ${response.status}).`
-		console.warn(`[notion-custom-sdk] ${message}`)
+		console.warn(`[custom-blocks-sdk] ${message}`)
 		return {
 			manifest: null,
-			error: { code: "manifest_unavailable", message },
+			error: {
+				code: "manifest_unavailable",
+				message,
+				isRetryable: isRetryableManifestHttpStatus(response.status),
+			},
 		}
 	}
+
 	let json: unknown
 	try {
 		json = await response.json()
 	} catch (error) {
 		const message = `Manifest at ${MANIFEST_URL} was not valid JSON.`
-		console.warn(`[notion-custom-sdk] ${message}`, error)
-		return { manifest: null, error: { code: "manifest_invalid", message } }
+		console.warn(`[custom-blocks-sdk] ${message}`, error)
+		return {
+			manifest: null,
+			// Consider invalid manifests as unrecoverable errors.
+			error: { code: "manifest_invalid", message, isRetryable: false },
+		}
 	}
+
 	const parsed = v.safeParse(manifestSchema, json)
 	if (!parsed.success) {
 		const message = `Manifest at ${MANIFEST_URL} did not match schema.`
-		console.warn(`[notion-custom-sdk] ${message}`, parsed.issues)
-		return { manifest: null, error: { code: "manifest_invalid", message } }
+		console.warn(`[custom-blocks-sdk] ${message}`, parsed.issues)
+		return {
+			manifest: null,
+			// Consider invalid manifests as unrecoverable errors.
+			error: { code: "manifest_invalid", message, isRetryable: false },
+		}
 	}
+
 	return { manifest: parsed.output }
 }
+
+function isRetryableManifestHttpStatus(status: number): boolean {
+	// Consider these statuses retryable because they may reflect transient failures.
+	return (
+		status === 408 || // Request Timeout
+		status === 425 || // Too Early
+		status === 500 || // Internal Server Error
+		status === 502 || // Bad Gateway
+		status === 503 || // Service Unavailable
+		status === 504 // Gateway Timeout
+	)
+}

package/src/bridge/messages/ready.ts

@@ -1,5 +1,4 @@
 import * as v from "valibot"
-import { customBlockReadyErrorSchema } from "../loadManifest.js"
 import { manifestSchema } from "../manifest.js"
 
 const readyMessageCommonEntries = {
@@ -17,6 +16,14 @@ const readyMessageCommonEntries = {
 	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`.
@@ -33,7 +40,7 @@ export const readyMessageSchema = v.union([
 	}),
 	v.object({
 		status: v.literal("error"),
-		error: customBlockReadyErrorSchema,
+		error: readyErrorSchema,
 		...readyMessageCommonEntries,
 	}),
 ])

package/src/host/createCustomBlockHost.ts

@@ -13,7 +13,7 @@ import type {
 } from "../bridge/messages/getUser.js"
 import type { HostToSandboxMessage } from "../bridge/messages/hostToSandbox.js"
 import type {
-	CustomBlockInitErrorCode,
+	CustomBlockInitErrorInfo,
 	InitMessage,
 } from "../bridge/messages/init.js"
 import type {
@@ -35,7 +35,7 @@ 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 { isValidBridgeProtocolVersion } from "./lifecycle/ready.js"
 import type {
 	CustomBlockHostDataSourcesPayload,
 	CustomBlockHostInitialState,
@@ -161,27 +161,24 @@ export function createCustomBlockHost(
 		return true
 	}
 
-	function sendInitError(code: CustomBlockInitErrorCode, message?: string) {
+	function sendInitError(error: CustomBlockInitErrorInfo) {
 		if (initStatus !== "pending") {
 			return
 		}
 		initStatus = "error"
 		clearNoReadyTimeout()
-		const error = initErrorForFailureReason(code)
 		post({
 			type: "init",
 			status: "error",
-			error: {
-				...error,
-				message: message ?? error.message,
-			},
+			error,
 		})
 	}
 
 	function onIframeLoad() {
 		clearNoReadyTimeout()
 		noReadyTimeoutId = window.setTimeout(() => {
-			sendInitError("no_ready")
+			const initError = initErrorForFailureReason("no_ready")
+			sendInitError(initError)
 		}, noReadyTimeoutMs)
 	}
 
@@ -261,14 +258,32 @@ export function createCustomBlockHost(
 	}
 
 	function handleReady(message: ReadyMessage) {
-		const failure = getReadyInitFailure(message, minBridgeProtocolVersion)
-		if (failure !== undefined) {
-			sendInitError(failure.code, failure.message)
+		// Verify the bridge protocol version is valid.
+		if (!isValidBridgeProtocolVersion(message.bridgeProtocolVersion)) {
+			const initError = initErrorForFailureReason("invalid_protocol_version", {
+				currentBridgeProtocolVersion: message.bridgeProtocolVersion,
+			})
+			sendInitError(initError)
 			return
 		}
-		if (message.status !== "success") {
+		if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
+			const initError = initErrorForFailureReason(
+				"unsupported_protocol_version",
+				{
+					currentBridgeProtocolVersion: message.bridgeProtocolVersion,
+					minBridgeProtocolVersion,
+				},
+			)
+			sendInitError(initError)
 			return
 		}
+
+		// If the sandbox reported an error during `ready`, return it as an `init` error.
+		if (message.status === "error") {
+			sendInitError(message.error)
+			return
+		}
+
 		if (sendInit(message)) {
 			onReady?.(message)
 		}
@@ -286,7 +301,8 @@ export function createCustomBlockHost(
 		const response = getInvalidSandboxMessageResponse(data)
 
 		if (initStatus === "pending" && response.incomingType === "ready") {
-			sendInitError("invalid_ready")
+			const initError = initErrorForFailureReason("invalid_ready")
+			sendInitError(initError)
 		} else if (response.nack !== undefined) {
 			post(response.nack)
 		}