@notionhq/custom-blocks 0.0.76 → 0.0.78

package/src/bridge/messages/{ready.ts → connect.ts}

@@ -1,8 +1,9 @@
 import * as v from "valibot"
 import { manifestSchema } from "../manifest.js"
 
-const readyMessageCommonEntries = {
-	type: v.literal("ready"),
+const connectMessageCommonEntries = {
+	type: v.literal("connect"),
+	initializationId: v.string(),
 	/**
 	 * 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
@@ -10,7 +11,7 @@ const readyMessageCommonEntries = {
 	 */
 	bridgeProtocolVersion: v.number(),
 	/**
-	 * Semver version of the SDK package that sent this ready message. Should only be used for
+	 * Semver version of the SDK package that sent this connect message. Should only be used for
 	 * analytics purposes. Business logic should compare against `bridgeProtocolVersion` instead.
 	 */
 	sdkVersion: v.string(),
@@ -18,31 +19,31 @@ const readyMessageCommonEntries = {
 
 // TODO(custom-blocks): Replace with `customBlockErrorInfoSchema` which makes `isRetryable` required
 // once min supported bridge protocol version is bumped to 3.
-const readyErrorSchema = v.object({
+const connectErrorSchema = 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`.
+ * First message the sandbox sends after mount. It identifies the sandbox and starts the bridge
+ * initialization exchange. The host echoes `initializationId` in its `init` response.
  */
-export const readyMessageSchema = v.union([
+export const connectMessageSchema = v.variant("status", [
 	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.
+		 * The data sources and settings the custom block expects. Hosts may omit
+		 * this when they already have an authoritative manifest.
 		 */
-		manifest: v.union([manifestSchema, v.null_()]),
-		...readyMessageCommonEntries,
+		manifest: v.optional(manifestSchema),
+		...connectMessageCommonEntries,
 	}),
 	v.object({
 		status: v.literal("error"),
-		error: readyErrorSchema,
-		...readyMessageCommonEntries,
+		error: connectErrorSchema,
+		...connectMessageCommonEntries,
 	}),
 ])
 
-export type ReadyMessage = v.InferOutput<typeof readyMessageSchema>
+export type ConnectMessage = v.InferOutput<typeof connectMessageSchema>

package/src/bridge/messages/hostToSandbox.ts

@@ -9,10 +9,7 @@ import { invalidSandboxMessageSchema } from "./invalidSandboxMessage.js"
 import { listUsersResultMessageSchema } from "./listUsers.js"
 import { pageChangedMessageSchema } from "./pageChanged.js"
 import { parentChangedMessageSchema } from "./parentChanged.js"
-import {
-	legacyQueryDataSourceResultMessageSchema,
-	statusQueryDataSourceResultMessageSchema,
-} from "./queryDataSourceResult.js"
+import { queryDataSourceResultMessageSchema } from "./queryDataSourceResult.js"
 import { themeChangedMessageSchema } from "./themeChanged.js"
 import { updatePageResultMessageSchema } from "./updatePageResult.js"
 
@@ -26,8 +23,7 @@ export const hostToSandboxMessageSchema = v.variant("type", [
 	pageChangedMessageSchema,
 	currentUserChangedMessageSchema,
 	dataSourcesChangedMessageSchema,
-	statusQueryDataSourceResultMessageSchema,
-	legacyQueryDataSourceResultMessageSchema,
+	queryDataSourceResultMessageSchema,
 	createPageResultMessageSchema,
 	getPageResultMessageSchema,
 	getUserResultMessageSchema,

package/src/bridge/messages/init.ts

@@ -2,18 +2,18 @@ import * as v from "valibot"
 import { notionDataSourceBindingsSchema } from "../dataSources/dataSource.js"
 import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
 import { notionBlockIdSchema } from "../ids.js"
+import { manifestSchema } from "../manifest.js"
 import { customBlockPageSchema } from "../pages/page.js"
 import { notionParentSchema } from "../parent.js"
 import { notionThemeSchema } from "../theme.js"
 import { notionUserSchema } from "../users/user.js"
+import type { CustomBlockInitResultErrorCode } from "./initResult.js"
 
 // The schema accepts any string code. The type lists known codes for
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockInitErrorCodeSchema = v.string()
 
 export type CustomBlockInitErrorCode = CustomBlockErrorCode<
-	| "no_ready"
-	| "invalid_ready"
 	| "manifest_unavailable"
 	| "manifest_invalid"
 	| "invalid_protocol_version"
@@ -24,47 +24,60 @@ export type CustomBlockInitErrorCode = CustomBlockErrorCode<
 	| "data_source_unavailable"
 	| "missing_property_binding"
 	| "invalid_property_binding"
-	| "not_in_iframe"
-	| "init_timeout"
 >
 
 export type CustomBlockInitErrorInfo =
 	CustomBlockErrorInfo<CustomBlockInitErrorCode>
 
+/**
+ * Every initialization failure visible to block code. This combines errors
+ * received in `init`, errors the sandbox reports in `initResult`, and failures
+ * detected locally while running `initCustomBlock()`.
+ */
+export type CustomBlockInitializationErrorCode =
+	| CustomBlockInitErrorCode
+	| CustomBlockInitResultErrorCode
+	| CustomBlockErrorCode<"not_in_iframe" | "init_timeout">
+
+export type CustomBlockInitializationErrorInfo =
+	CustomBlockErrorInfo<CustomBlockInitializationErrorCode>
+
 export const customBlockInitErrorInfoSchema = v.object({
 	code: customBlockInitErrorCodeSchema,
 	message: v.string(),
 	isRetryable: v.boolean(),
 })
 
-export class CustomBlockInitError
+export class CustomBlockInitializationError
 	extends Error
 	implements CustomBlockErrorInfo
 {
-	constructor(error: CustomBlockInitErrorInfo) {
+	constructor(error: CustomBlockInitializationErrorInfo) {
 		super(error.message)
-		this.name = "CustomBlockInitError"
+		this.name = "CustomBlockInitializationError"
 		this.code = error.code
 		this.isRetryable = error.isRetryable
 	}
 
-	code: CustomBlockInitErrorCode
+	code: CustomBlockInitializationErrorCode
 	isRetryable: boolean
 }
 
 /**
  * Initialization message sent by the host to the sandbox exactly once, in response to the
- * sandbox's `ready` message. After init, live updates flow through narrower messages
- * (`themeChanged`, `parentChanged`, `pageChanged`, `dataSourcesChanged`).
+ * sandbox's `connect` message. The sandbox echoes `initializationId` in `initResult`. After
+ * successful initialization, live updates flow through narrower messages.
  */
 export const initMessageSchema = v.variant("status", [
 	v.object({
 		type: v.literal("init"),
+		initializationId: v.string(),
 		status: v.literal("success"),
 		theme: notionThemeSchema,
 		blockId: notionBlockIdSchema,
 		parent: notionParentSchema,
 		page: customBlockPageSchema,
+		manifest: manifestSchema,
 		dataSources: v.object({
 			bindings: notionDataSourceBindingsSchema,
 		}),
@@ -72,6 +85,7 @@ export const initMessageSchema = v.variant("status", [
 	}),
 	v.object({
 		type: v.literal("init"),
+		initializationId: v.string(),
 		status: v.literal("error"),
 		error: customBlockInitErrorInfoSchema,
 	}),

package/src/bridge/messages/initResult.ts

@@ -0,0 +1,37 @@
+import * as v from "valibot"
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
+
+// The schema accepts any string code. The type lists known codes for
+// autocomplete, with an open string fallback for newer senders.
+export const customBlockInitResultErrorCodeSchema = v.string()
+
+export type CustomBlockInitResultErrorCode =
+	CustomBlockErrorCode<"invalid_init_bindings">
+
+export type CustomBlockInitResultErrorInfo =
+	CustomBlockErrorInfo<CustomBlockInitResultErrorCode>
+
+export const customBlockInitResultErrorInfoSchema = v.object({
+	code: customBlockInitResultErrorCodeSchema,
+	message: v.string(),
+	isRetryable: v.boolean(),
+})
+
+/**
+ * Acknowledges whether the sandbox successfully applied the host's `init` response.
+ */
+export const initResultMessageSchema = v.variant("status", [
+	v.object({
+		type: v.literal("initResult"),
+		initializationId: v.string(),
+		status: v.literal("success"),
+	}),
+	v.object({
+		type: v.literal("initResult"),
+		initializationId: v.string(),
+		status: v.literal("error"),
+		error: customBlockInitResultErrorInfoSchema,
+	}),
+])
+
+export type InitResultMessage = v.InferOutput<typeof initResultMessageSchema>

package/src/bridge/messages/queryDataSource.ts

@@ -7,15 +7,11 @@ import { notionDataSourceIdSchema } from "../ids.js"
  */
 export const queryDataSourceMessageSchema = v.object({
 	type: v.literal("queryDataSource"),
-	requestId: v.string(),
-	/**
-	 * The stable snapshot ID that identifies the SDK result slot to update. This is stable for the
-	 * lifetime of the subscription.
-	 */
-	snapshotId: v.string(),
+	/** Stable for the lifetime of this query subscription. */
+	subscriptionId: v.string(),
 	/** The raw Notion data source ID to read from. */
 	dataSourceId: notionDataSourceIdSchema,
-	/** The number of items to return in the snapshot. */
+	/** The number of items to return in each subscription update. */
 	limit: v.number(),
 })
 

package/src/bridge/messages/queryDataSourceResult.ts

@@ -22,44 +22,24 @@ export const customBlockQueryDataSourceErrorInfoSchema = v.object({
 })
 
 /**
- * Message sent by the host to the sandbox in response to a `queryDataSource` request.
+ * Message sent by the host to update a `queryDataSource` subscription.
  */
-export const legacyQueryDataSourceResultMessageSchema = v.object({
-	type: v.literal("queryDataSourceResult"),
-	requestId: v.string(),
-	snapshotId: v.string(),
-	items: v.array(notionDataSourcePageBridgeSchema),
-	hasMore: v.boolean(),
-	error: v.optional(customBlockQueryDataSourceErrorInfoSchema),
-})
-
-export const statusQueryDataSourceResultMessageSchema = v.variant("status", [
+export const queryDataSourceResultMessageSchema = v.variant("status", [
 	v.object({
 		type: v.literal("queryDataSourceResult"),
-		requestId: v.string(),
-		snapshotId: v.string(),
+		subscriptionId: v.string(),
 		status: v.literal("success"),
 		items: v.array(notionDataSourcePageBridgeSchema),
 		hasMore: v.boolean(),
 	}),
 	v.object({
 		type: v.literal("queryDataSourceResult"),
-		requestId: v.string(),
-		snapshotId: v.string(),
+		subscriptionId: v.string(),
 		status: v.literal("error"),
 		error: customBlockQueryDataSourceErrorInfoSchema,
 	}),
 ])
 
-/**
- * TODO(custom-blocks): Update when bumping bridge protocol version to 3.
- * Protocol version 2 hosts and sandboxes use the legacy optional-error shape.
- */
-export const queryDataSourceResultMessageSchema = v.union([
-	legacyQueryDataSourceResultMessageSchema,
-	statusQueryDataSourceResultMessageSchema,
-])
-
 export type QueryDataSourceResultMessage = v.InferOutput<
 	typeof queryDataSourceResultMessageSchema
 >

package/src/bridge/messages/sandboxToHost.ts

@@ -1,11 +1,12 @@
 import * as v from "valibot"
+import { connectMessageSchema } from "./connect.js"
 import { createPageMessageSchema } from "./createPage.js"
 import { getPageMessageSchema } from "./getPage.js"
 import { getUserMessageSchema } from "./getUser.js"
+import { initResultMessageSchema } from "./initResult.js"
 import { invalidHostMessageSchema } from "./invalidHostMessage.js"
 import { listUsersMessageSchema } from "./listUsers.js"
 import { queryDataSourceMessageSchema } from "./queryDataSource.js"
-import { readyMessageSchema } from "./ready.js"
 import { resizeMessageSchema } from "./resize.js"
 import { updatePageMessageSchema } from "./updatePage.js"
 
@@ -14,7 +15,8 @@ import { updatePageMessageSchema } from "./updatePage.js"
  * inbound traffic from sandboxes without re-implementing validation logic.
  */
 export const sandboxToHostMessageSchema = v.union([
-	readyMessageSchema,
+	connectMessageSchema,
+	initResultMessageSchema,
 	queryDataSourceMessageSchema,
 	createPageMessageSchema,
 	getPageMessageSchema,

package/src/bridge/sandboxClient.ts

@@ -17,7 +17,6 @@ import {
 	getDataSourceQueryView as getDataSourceQueryViewWithBridge,
 } from "./hostState.js"
 import type { ManifestLoadResult } from "./loadManifest.js"
-import type { CustomBlockManifest } from "./manifest.js"
 import type { InitMessage } from "./messages/init.js"
 import { type MessageLogEntry, SandboxBridge } from "./SandboxBridge.js"
 
@@ -26,11 +25,11 @@ export type { MessageLogEntry }
 const bridge = new SandboxBridge()
 
 export const customBlockHost = {
-	sendReady: (manifestResult: ManifestLoadResult) => {
-		bridge.sendReady(manifestResult)
+	sendConnect: (manifestResult: ManifestLoadResult) => {
+		bridge.sendConnect(manifestResult)
 	},
 
-	awaitInit: (signal?: AbortSignal): Promise<InitMessage> => {
+	awaitInit: (signal?: AbortSignal): Promise<void> => {
 		return bridge.awaitInit(signal)
 	},
 
@@ -42,10 +41,6 @@ export const customBlockHost = {
 		return bridge.getHostState()
 	},
 
-	getManifest: (): CustomBlockManifest | null => {
-		return bridge.getManifest()
-	},
-
 	/**
 	 * Apply an `init` payload directly, bypassing the postMessage handshake for
 	 * standalone preview state.

package/src/customBlock.ts

@@ -57,8 +57,8 @@ export const customBlock = {
 		return getInitializedHostState("getPage").page
 	},
 
-	getManifest(): CustomBlockManifest | null {
-		return customBlockHost.getManifest()
+	getManifest(): CustomBlockManifest {
+		return getInitializedHostState("getManifest").manifest
 	},
 
 	autoResize,