@notionhq/custom-blocks-host 0.4.2 → 0.5.0

package/src/context/initialState.ts

@@ -0,0 +1,56 @@
+import { customBlockPageSchema } from "@notionhq/custom-blocks-protocol/context/containingPage.js"
+import { notionContrastModeSchema } from "@notionhq/custom-blocks-protocol/context/contrast.js"
+import { notionParentSchema } from "@notionhq/custom-blocks-protocol/context/parent.js"
+import { notionThemeSchema } from "@notionhq/custom-blocks-protocol/context/theme.js"
+import { bridgeDataSourceBindingsSchema } from "@notionhq/custom-blocks-protocol/dataSources/bridgeDataSourceBindings.js"
+import { customBlockInitErrorInfoSchema } from "@notionhq/custom-blocks-protocol/handshake/init.js"
+import type { BridgeCustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest/manifest.js"
+import { manifestSchema } from "@notionhq/custom-blocks-protocol/manifest/manifest.js"
+import { bridgeUserSchema } from "@notionhq/custom-blocks-protocol/users/bridgeUser.js"
+import { notionBlockIdSchema } from "@notionhq/custom-blocks-protocol/utils/ids.js"
+import * as v from "valibot"
+import type { CustomBlockHostResult } from "../messages/result.js"
+
+export const customBlockHostInitialStateSchema = v.object({
+	theme: notionThemeSchema,
+	/**
+	 * Defaults to standard for existing host integrations.
+	 * TODO(custom-blocks): Make this required when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION increases to 4.
+	 */
+	contrastMode: v.optional(notionContrastModeSchema),
+	blockId: notionBlockIdSchema,
+	parent: notionParentSchema,
+	page: customBlockPageSchema,
+	manifest: manifestSchema,
+	dataSources: v.object({ bindings: bridgeDataSourceBindingsSchema }),
+	currentUser: bridgeUserSchema,
+})
+
+export type CustomBlockHostInitialState = v.InferInput<
+	typeof customBlockHostInitialStateSchema
+>
+
+export type CustomBlockHostInitialStateResult = CustomBlockHostResult<{
+	initialState: CustomBlockHostInitialState
+}>
+
+export const customBlockHostPreparedStateResultSchema = v.variant("status", [
+	v.object({
+		status: v.literal("success"),
+		initialState: v.omit(customBlockHostInitialStateSchema, ["manifest"]),
+	}),
+	v.object({
+		status: v.literal("error"),
+		error: customBlockInitErrorInfoSchema,
+	}),
+])
+
+/** Adapter-owned state or an explicit preparation error. The host adds the manifest to init. */
+export type CustomBlockHostPreparedStateResult = CustomBlockHostResult<{
+	initialState: Omit<CustomBlockHostInitialState, "manifest">
+}>
+
+export type CustomBlockHostPrepareInitialState = (args: {
+	manifest: BridgeCustomBlockManifest
+	signal: AbortSignal
+}) => Promise<CustomBlockHostPreparedStateResult>

package/src/context/resize.ts

@@ -0,0 +1,4 @@
+import type { resizeMessageSchema } from "@notionhq/custom-blocks-protocol/context/messages/resize.js"
+import type { InferInput } from "valibot"
+
+export type ResizeMessageInput = InferInput<typeof resizeMessageSchema>

package/src/createCustomBlockHost.ts

@@ -1,80 +1,80 @@
-import type { notionContrastModeSchema } from "@notionhq/custom-blocks-protocol/contrast.js"
-import type { NotionCollectionSchema } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
-import { notionDataSourceBindingsSchema } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
-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 {
-	type HostToSandboxMessage,
-	hostToSandboxMessageSchema,
-} from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
+import type { customBlockPageSchema } from "@notionhq/custom-blocks-protocol/context/containingPage.js"
+import type { NotionContrastMode } from "@notionhq/custom-blocks-protocol/context/contrast.js"
+import type { notionParentSchema } from "@notionhq/custom-blocks-protocol/context/parent.js"
+import type { NotionTheme } from "@notionhq/custom-blocks-protocol/context/theme.js"
+import { bridgeDataSourceBindingsSchema } from "@notionhq/custom-blocks-protocol/dataSources/bridgeDataSourceBindings.js"
+import type { NotionCollectionSchema } from "@notionhq/custom-blocks-protocol/dataSources/collectionSchema.js"
+import type {
+	CustomBlockQueryDataSourceErrorInfo,
+	QueryDataSourceMessage,
+	queryDataSourceResultMessageSchema,
+} from "@notionhq/custom-blocks-protocol/dataSources/messages/queryDataSource.js"
+import { resolveDataSourceBinding } from "@notionhq/custom-blocks-protocol/dataSources/resolveDataSourceBinding.js"
+import type { CustomBlockInitErrorInfo } from "@notionhq/custom-blocks-protocol/handshake/init.js"
 import {
-	type CustomBlockInitErrorInfo,
 	CustomBlockInitializationError,
 	initMessageSchema,
-} from "@notionhq/custom-blocks-protocol/messages/init.js"
+} from "@notionhq/custom-blocks-protocol/handshake/init.js"
+import type { BridgeCustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest/manifest.js"
+import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
+import { hostToSandboxMessageSchema } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
 import type { InvalidSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/invalidSandboxMessage.js"
+import type { SandboxToHostMessage } from "@notionhq/custom-blocks-protocol/messages/sandboxToHost.js"
 import type {
 	OpenExternalUrlMessage,
 	OpenExternalUrlResultMessage,
-} from "@notionhq/custom-blocks-protocol/messages/openExternalUrl.js"
-import type { QueryDataSourceMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
-import type {
-	CustomBlockQueryDataSourceErrorInfo,
-	queryDataSourceResultMessageSchema,
-} from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
-import type { SandboxToHostMessage } from "@notionhq/custom-blocks-protocol/messages/sandboxToHost.js"
-import type { customBlockPageSchema } from "@notionhq/custom-blocks-protocol/pages/page.js"
-import type { notionParentSchema } from "@notionhq/custom-blocks-protocol/parent.js"
-import { LATEST_BRIDGE_PROTOCOL_VERSION } from "@notionhq/custom-blocks-protocol/protocolVersion.js"
-import type { notionThemeSchema } from "@notionhq/custom-blocks-protocol/theme.js"
-import type { notionUserSchema } from "@notionhq/custom-blocks-protocol/users/user.js"
+} from "@notionhq/custom-blocks-protocol/navigation/openExternalUrl.js"
+import type { BridgeUser } from "@notionhq/custom-blocks-protocol/users/bridgeUser.js"
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/utils/ids.js"
+import { notionDataSourceIdSchema } from "@notionhq/custom-blocks-protocol/utils/ids.js"
+import { LATEST_BRIDGE_PROTOCOL_VERSION } from "@notionhq/custom-blocks-protocol/utils/protocolVersion.js"
 import type { InferInput } from "valibot"
 import * as v from "valibot"
 import { normalizeHostToSandboxMessage } from "./compatibility/normalizeHostToSandboxMessage.js"
-import { isAllowedLocalPreviewUrl } from "./isAllowedLocalPreviewUrl.js"
-import {
-	contextUnavailableError,
-	invalidLocalPreviewUrlError,
-	invalidPropertyBindingError,
-	missingDataSourceBindingError,
-	missingPropertyBindingError,
-	unknownInitializationError,
-} from "./lifecycle/initErrors.js"
-import { createInitializationController } from "./lifecycle/initializationController.js"
-import { resolveManifest } from "./lifecycle/resolveManifest.js"
 import type {
-	CustomBlockHostDataSourcesPayload,
 	CustomBlockHostInitialState,
 	CustomBlockHostInitialStateResult,
-	CustomBlockHostManifestResult,
-	CustomBlockHostNormalizedDataSourcesPayload,
-	CustomBlockHostNormalizedManifestResult,
 	CustomBlockHostPrepareInitialState,
-	CustomBlockHostStatus,
-	CustomBlockManifestSource,
-} from "./lifecycle/types.js"
+} from "./context/initialState.js"
 import {
 	customBlockHostInitialStateSchema,
-	customBlockHostManifestResultSchema,
 	customBlockHostPreparedStateResultSchema,
-} from "./lifecycle/types.js"
-import { parseExternalUrl } from "./messages/parseExternalUrl.js"
-import { createSandboxMessageRouter } from "./messages/sandboxMessageRouter.js"
+} from "./context/initialState.js"
+import type { QuerySubscriptionToken } from "./dataSources/queries/querySubscriptions.js"
+import { QuerySubscriptions } from "./dataSources/queries/querySubscriptions.js"
+import type {
+	CustomBlockHostDataSourcesPayload,
+	CustomBlockHostNormalizedDataSourcesPayload,
+	CustomBlockHostQueryDataSourceResult,
+} from "./dataSources/types.js"
+import { validateQueryDataSourceFilter } from "./dataSources/validation/validateQueryDataSourceFilter.js"
+import { validateQueryDataSourceSorts } from "./dataSources/validation/validateQueryDataSourceSorts.js"
+import { createInitializationController } from "./lifecycle/createInitializationController.js"
+import { contextUnavailableError } from "./lifecycle/errors/contextUnavailableError.js"
+import { invalidLocalPreviewUrlError } from "./lifecycle/errors/invalidLocalPreviewUrlError.js"
+import { invalidPropertyBindingError } from "./lifecycle/errors/invalidPropertyBindingError.js"
+import { missingDataSourceBindingError } from "./lifecycle/errors/missingDataSourceBindingError.js"
+import { missingPropertyBindingError } from "./lifecycle/errors/missingPropertyBindingError.js"
+import { unknownInitializationError } from "./lifecycle/errors/unknownInitializationError.js"
+import { isAllowedLocalPreviewUrl } from "./lifecycle/isAllowedLocalPreviewUrl.js"
 import type {
 	CustomBlockHostFailure,
-	CustomBlockHostHandlers,
-	CustomBlockHostLogDirection,
-} from "./messages/types.js"
-import { MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION } from "./protocolVersion.js"
-import {
-	QuerySubscriptions,
-	type QuerySubscriptionToken,
-} from "./queries/querySubscriptions.js"
-import type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js"
-import { validateQueryDataSourceFilter } from "./queries/validateQueryDataSourceFilter.js"
-import { validateQueryDataSourceSorts } from "./queries/validateQueryDataSourceSorts.js"
-import { unreachable } from "./utils.js"
+	CustomBlockHostStatus,
+} from "./lifecycle/types.js"
+import { resolveManifest } from "./manifest/resolveManifest.js"
+import type {
+	CustomBlockHostManifestResult,
+	CustomBlockHostNormalizedManifestResult,
+	CustomBlockManifestSource,
+} from "./manifest/types.js"
+import { customBlockHostManifestResultSchema } from "./manifest/types.js"
+import { createSandboxMessageRouter } from "./messages/createSandboxMessageRouter.js"
+import type { CustomBlockHostHandlers } from "./messages/handlers.js"
+import type { CustomBlockHostLogDirection } from "./messages/logging.js"
+import { parseExternalUrl } from "./navigation/parseExternalUrl.js"
+import { MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION } from "./utils/protocolVersion.js"
+import { unreachable } from "./utils/unreachable.js"
 
 // Bridge protocol version that introduced page: { type: "unavailable" }.
 // Earlier SDKs cannot represent this context, so the host reports context_unavailable.
@@ -113,19 +113,33 @@ export type CustomBlockHostOptions = {
 	initialStateTimeoutMs?: number
 }
 
+/** Reports local acceptance, not sandbox delivery or initialization success. */
+export type CustomBlockHostSetDataSourcesResult =
+	| { status: "success" }
+	| {
+			status: "error"
+			error: CustomBlockErrorInfo<
+				| "missing_data_source_binding"
+				| "missing_property_binding"
+				| "invalid_property_binding"
+			>
+	  }
+
 export type CustomBlockHostHandle = {
 	stop: () => void
-	setTheme: (theme: InferInput<typeof notionThemeSchema>) => void
-	setContrastMode: (
-		contrastMode: InferInput<typeof notionContrastModeSchema>,
-	) => void
+	setTheme: (theme: NotionTheme) => void
+	setContrastMode: (contrastMode: NotionContrastMode) => void
 	setParent: (parent: InferInput<typeof notionParentSchema>) => void
 	setPage: (page: InferInput<typeof customBlockPageSchema>) => void
-	setDataSources: (dataSources: CustomBlockHostDataSourcesPayload) => void
-	setCurrentUser: (currentUser: InferInput<typeof notionUserSchema>) => void
-	refreshQuery: (args: {
-		dataSourceId: InferInput<typeof notionDataSourceIdSchema>
-	}) => void
+	/**
+	 * Reports synchronous local acceptance, not sandbox delivery or initialization success.
+	 * Malformed bindings can throw during schema parsing.
+	 */
+	setDataSources: (
+		dataSources: CustomBlockHostDataSourcesPayload,
+	) => CustomBlockHostSetDataSourcesResult
+	setCurrentUser: (currentUser: BridgeUser) => void
+	refreshQuery: (args: { dataSourceId: string }) => void
 }
 
 /**
@@ -168,7 +182,7 @@ export function createCustomBlockHost(
 	let pendingState: HostStateUpdates = {}
 	let hasPreparedInitialState = false
 	const preparationController = new AbortController()
-	let manifest: CustomBlockManifest | undefined
+	let manifest: BridgeCustomBlockManifest | undefined
 	let activeDataSources: CustomBlockHostNormalizedDataSourcesPayload | undefined
 	let sandboxBridgeProtocolVersion = LATEST_BRIDGE_PROTOCOL_VERSION
 	const querySubscriptions = new QuerySubscriptions(subscriptionId => {
@@ -545,7 +559,7 @@ export function createCustomBlockHost(
 	}
 
 	async function prepare(
-		connectManifest: CustomBlockManifest | undefined,
+		connectManifest: BridgeCustomBlockManifest | undefined,
 	): Promise<CustomBlockHostInitialStateResult> {
 		preparationController.signal.throwIfAborted()
 		const manifestResult = await resolveManifest({
@@ -669,23 +683,27 @@ export function createCustomBlockHost(
 			const normalizedDataSources: CustomBlockHostNormalizedDataSourcesPayload =
 				{
 					bindings: v.parse(
-						notionDataSourceBindingsSchema,
+						bridgeDataSourceBindingsSchema,
 						dataSources.bindings,
 					),
 				}
-			if (
-				initializationController.hasConnectedSandbox &&
-				manifest !== undefined &&
-				getBindingError(manifest, normalizedDataSources) !== undefined
-			) {
+			const bindingError =
+				initializationController.hasConnectedSandbox && manifest !== undefined
+					? getBindingError(manifest, normalizedDataSources)
+					: undefined
+			if (bindingError !== undefined) {
 				emit("warn", {
 					message: "Ignored invalid data source bindings update",
 					payload: normalizedDataSources,
 				})
-				return
+				return {
+					status: "error",
+					error: bindingError,
+				}
 			}
 			activeDataSources = normalizedDataSources
 			updateHostState({ dataSources: normalizedDataSources })
+			return { status: "success" }
 		},
 		refreshQuery({ dataSourceId }) {
 			if (initializationController.status !== "initialized") {
@@ -742,30 +760,32 @@ function getCollectionSchema(
 }
 
 function getBindingError(
-	manifest: CustomBlockManifest,
+	manifest: BridgeCustomBlockManifest,
 	dataSources: CustomBlockHostDataSourcesPayload,
-): CustomBlockInitErrorInfo | undefined {
+) {
 	for (const [dataSourceKey, manifestDataSource] of Object.entries(
 		manifest.dataSources,
 	)) {
 		const binding = dataSources.bindings[dataSourceKey]
+		if (binding?.inaccessible === true) {
+			continue
+		}
+		const resolvedBinding = resolveDataSourceBinding({
+			manifestDataSource,
+			collectionSchema: binding?.collectionSchema,
+			propertyIdsByKey: binding?.propertyIdsByKey,
+		})
 		if (
 			binding?.collectionPointer === undefined ||
-			binding.collectionSchema === undefined
+			resolvedBinding.status === "missing_schema"
 		) {
 			return missingDataSourceBindingError()
 		}
-		for (const [propertyKey, manifestProperty] of Object.entries(
-			manifestDataSource.properties ?? {},
-		)) {
-			const propertyId = binding.propertyIdsByKey?.[propertyKey]
-			if (propertyId === undefined) {
+		for (const property of resolvedBinding.properties) {
+			if (property.status === "missing") {
 				return missingPropertyBindingError()
 			}
-			if (
-				binding.collectionSchema.propertiesById[propertyId]?.type !==
-				manifestProperty.type
-			) {
+			if (property.status !== "mapped") {
 				return invalidPropertyBindingError()
 			}
 		}

package/src/{autoBindProperties.ts → dataSources/bindings/getAutoBoundPropertyIdsByKey.ts}

@@ -1,4 +1,4 @@
-import type { NotionPropertyType } from "@notionhq/custom-blocks-protocol/dataSources/propertySchema.js"
+import type { NotionPropertyType } from "@notionhq/custom-blocks-protocol/dataSources/properties/propertySchema.js"
 
 export type AutoBindableProperty = {
 	name: string

package/src/{dateValue.ts → dataSources/properties/toNotionDateValue.ts}

@@ -3,8 +3,8 @@ import type {
 	NotionDateRange,
 	NotionDateTime,
 	NotionDateTimeRange,
-} from "@notionhq/custom-blocks-protocol/dataSources/dateValue.js"
-import type { NotionDateInput } from "@notionhq/custom-blocks-protocol/pages/page.js"
+} from "@notionhq/custom-blocks-protocol/dataSources/properties/dateValue.js"
+import type { NotionDateInput } from "@notionhq/custom-blocks-protocol/pages/properties/dateInput.js"
 
 export type CustomBlockDateValue =
 	| NotionDate

package/src/{queries → dataSources/queries}/querySubscriptions.ts

@@ -1,5 +1,5 @@
-import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/ids.js"
-import type { QueryDataSourceMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
+import type { QueryDataSourceMessage } from "@notionhq/custom-blocks-protocol/dataSources/messages/queryDataSource.js"
+import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/utils/ids.js"
 
 export type QueryRefresh = {
 	message: QueryDataSourceMessage

package/src/dataSources/types.ts

@@ -0,0 +1,23 @@
+import type { bridgeDataSourceBindingsSchema } from "@notionhq/custom-blocks-protocol/dataSources/bridgeDataSourceBindings.js"
+import type { queryDataSourceMessageSchema } from "@notionhq/custom-blocks-protocol/dataSources/messages/queryDataSource.js"
+import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
+import type * as v from "valibot"
+import type { InferInput } from "valibot"
+import type { CustomBlockHostResult } from "../messages/result.js"
+
+export type QueryDataSourceMessageInput = InferInput<
+	typeof queryDataSourceMessageSchema
+>
+
+export type CustomBlockHostDataSourcesPayload = {
+	bindings: v.InferInput<typeof bridgeDataSourceBindingsSchema>
+}
+
+export type CustomBlockHostNormalizedDataSourcesPayload = {
+	bindings: v.InferOutput<typeof bridgeDataSourceBindingsSchema>
+}
+
+export type CustomBlockHostQueryDataSourceResult = CustomBlockHostResult<{
+	items: BridgePage[]
+	hasMore: boolean
+}>

package/src/{queries → dataSources/validation}/validateQueryDataSourceFilter.ts

@@ -1,21 +1,19 @@
-import type { NotionCollectionSchema } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
-import type {
-	CustomBlockContainsFilterOperator,
-	CustomBlockOptionFilterOperator,
-	ResolvedCustomBlockDataSourceFilter,
-	ResolvedCustomBlockDataSourcePropertyFilter,
-} from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
-import { customBlockRelationFilterOperatorSchema } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
-import type { CustomBlockQueryDataSourceErrorInfo } from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
+import type { NotionCollectionSchema } from "@notionhq/custom-blocks-protocol/dataSources/collectionSchema.js"
+import type { BridgeDataSourceFilter } from "@notionhq/custom-blocks-protocol/dataSources/filters/bridgeDataSourceFilter.js"
+import type { BridgeDataSourceFilterCondition } from "@notionhq/custom-blocks-protocol/dataSources/filters/bridgeDataSourceFilterCondition.js"
+import type { CustomBlockContainsFilterOperator } from "@notionhq/custom-blocks-protocol/dataSources/filters/containsFilterOperator.js"
+import type { CustomBlockOptionFilterOperator } from "@notionhq/custom-blocks-protocol/dataSources/filters/optionFilterOperator.js"
+import { customBlockRelationFilterOperatorSchema } from "@notionhq/custom-blocks-protocol/dataSources/filters/relationFilterOperator.js"
+import type { CustomBlockQueryDataSourceErrorInfo } from "@notionhq/custom-blocks-protocol/dataSources/messages/queryDataSource.js"
 import { is } from "valibot"
-import { unreachable } from "../utils.js"
+import { unreachable } from "../../utils/unreachable.js"
 
 type OptionFilterOperator =
 	| CustomBlockOptionFilterOperator
 	| CustomBlockContainsFilterOperator
 
 export function validateQueryDataSourceFilter(
-	filter: ResolvedCustomBlockDataSourceFilter | undefined,
+	filter: BridgeDataSourceFilter | undefined,
 	collectionSchema: NotionCollectionSchema,
 ): CustomBlockQueryDataSourceErrorInfo | undefined {
 	if (filter === undefined) {
@@ -33,7 +31,7 @@ export function validateQueryDataSourceFilter(
 }
 
 function validatePropertyFilter(
-	filter: ResolvedCustomBlockDataSourcePropertyFilter,
+	filter: BridgeDataSourceFilterCondition,
 	collectionSchema: NotionCollectionSchema,
 ): CustomBlockQueryDataSourceErrorInfo | undefined {
 	if (!Object.hasOwn(collectionSchema.propertiesById, filter.propertyId)) {
@@ -109,7 +107,7 @@ function validatePropertyFilter(
 	}
 }
 
-function getOptionFilter(filter: ResolvedCustomBlockDataSourcePropertyFilter):
+function getOptionFilter(filter: BridgeDataSourceFilterCondition):
 	| {
 			propertyType: "select" | "multi_select" | "status"
 			operator: OptionFilterOperator

package/src/{queries → dataSources/validation}/validateQueryDataSourceSorts.ts

@@ -1,10 +1,8 @@
-import type { NotionCollectionSchema } from "@notionhq/custom-blocks-protocol/dataSources/dataSource.js"
-import { CUSTOM_BLOCK_DATA_SOURCE_SORTABLE_PROPERTY_TYPES } from "@notionhq/custom-blocks-protocol/dataSources/propertySchema.js"
-import {
-	CUSTOM_BLOCK_DATA_SOURCE_QUERY_MAX_SORTS,
-	type ResolvedCustomBlockDataSourceSort,
-} from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
-import type { CustomBlockQueryDataSourceErrorInfo } from "@notionhq/custom-blocks-protocol/messages/queryDataSourceResult.js"
+import type { NotionCollectionSchema } from "@notionhq/custom-blocks-protocol/dataSources/collectionSchema.js"
+import type { BridgeDataSourceSort } from "@notionhq/custom-blocks-protocol/dataSources/filters/bridgeDataSourceSort.js"
+import { CUSTOM_BLOCK_DATA_SOURCE_QUERY_MAX_SORTS } from "@notionhq/custom-blocks-protocol/dataSources/filters/bridgeDataSourceSort.js"
+import type { CustomBlockQueryDataSourceErrorInfo } from "@notionhq/custom-blocks-protocol/dataSources/messages/queryDataSource.js"
+import { CUSTOM_BLOCK_DATA_SOURCE_SORTABLE_PROPERTY_TYPES } from "@notionhq/custom-blocks-protocol/dataSources/properties/propertySchema.js"
 
 const supportedDataSourceSortPropertyTypes = new Set<string>(
 	CUSTOM_BLOCK_DATA_SOURCE_SORTABLE_PROPERTY_TYPES,
@@ -14,7 +12,7 @@ const supportedDataSourceSortPropertyTypes = new Set<string>(
  * Ensures the sorts of a data source query are valid.
  */
 export function validateQueryDataSourceSorts(
-	sorts: ResolvedCustomBlockDataSourceSort[] | undefined,
+	sorts: BridgeDataSourceSort[] | undefined,
 	collectionSchema: NotionCollectionSchema,
 ): CustomBlockQueryDataSourceErrorInfo | undefined {
 	if (sorts === undefined) {

package/src/index.ts

@@ -1,49 +1,58 @@
-export {
-	type AutoBindableProperty,
-	getAutoBoundPropertyIdsByKey,
-} from "./autoBindProperties.js"
+export type {
+	CustomBlockHostInitialState,
+	CustomBlockHostInitialStateResult,
+	CustomBlockHostPreparedStateResult,
+	CustomBlockHostPrepareInitialState,
+} from "./context/initialState.js"
+export type { ResizeMessageInput } from "./context/resize.js"
 export {
 	type CustomBlockHostHandle,
 	type CustomBlockHostOptions,
+	type CustomBlockHostSetDataSourcesResult,
 	createCustomBlockHost,
 } from "./createCustomBlockHost.js"
+export {
+	type AutoBindableProperty,
+	getAutoBoundPropertyIdsByKey,
+} from "./dataSources/bindings/getAutoBoundPropertyIdsByKey.js"
 export {
 	type CustomBlockDateValue,
 	InvalidNotionDateError,
 	toNotionDateValue,
-} from "./dateValue.js"
-export { toNotionPageId } from "./ids.js"
-export { isAllowedLocalPreviewUrl } from "./isAllowedLocalPreviewUrl.js"
+} from "./dataSources/properties/toNotionDateValue.js"
 export type {
 	CustomBlockHostDataSourcesPayload,
-	CustomBlockHostInitialState,
-	CustomBlockHostInitialStateResult,
-	CustomBlockHostManifestResult,
-	CustomBlockHostPreparedStateResult,
-	CustomBlockHostPrepareInitialState,
+	CustomBlockHostQueryDataSourceResult,
+	QueryDataSourceMessageInput,
+} from "./dataSources/types.js"
+export { isAllowedLocalPreviewUrl } from "./lifecycle/isAllowedLocalPreviewUrl.js"
+export type {
+	CustomBlockHostFailure,
 	CustomBlockHostStatus,
-	CustomBlockManifestSource,
 } from "./lifecycle/types.js"
 export type {
-	CreatePageMessageInput,
-	CustomBlockHostCreatePageResult,
-	CustomBlockHostFailure,
-	CustomBlockHostGetPageResult,
-	CustomBlockHostGetUserResult,
-	CustomBlockHostHandlers,
-	CustomBlockHostListUsersResult,
-	CustomBlockHostLogDirection,
+	CustomBlockHostManifestResult,
+	CustomBlockManifestSource,
+} from "./manifest/types.js"
+export type { CustomBlockHostHandlers } from "./messages/handlers.js"
+export type { CustomBlockHostLogDirection } from "./messages/logging.js"
+export type { CustomBlockHostResult } from "./messages/result.js"
+export type {
 	CustomBlockHostNavigationContext,
-	CustomBlockHostOpenExternalUrlResult,
+	OpenExternalUrlMessageInput,
+} from "./navigation/types.js"
+export type {
+	CreatePageMessageInput,
 	CustomBlockHostOpenPageResult,
-	CustomBlockHostUpdatePageResult,
+	CustomBlockHostPageResult,
 	GetPageMessageInput,
-	GetUserMessageInput,
-	ListUsersMessageInput,
-	OpenExternalUrlMessageInput,
 	OpenPageMessageInput,
-	QueryDataSourceMessageInput,
-	ResizeMessageInput,
 	UpdatePageMessageInput,
-} from "./messages/types.js"
-export type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js"
+} from "./pages/types.js"
+export type {
+	CustomBlockHostUserListResult,
+	CustomBlockHostUserResult,
+	GetUserMessageInput,
+	ListUsersMessageInput,
+} from "./users/types.js"
+export { toNotionPageId } from "./utils/toNotionPageId.js"

package/src/lifecycle/{initializationController.ts → createInitializationController.ts}

@@ -1,27 +1,22 @@
-import { DEFAULT_CONTRAST_MODE } from "@notionhq/custom-blocks-protocol/contrast.js"
-import type { ConnectMessage } from "@notionhq/custom-blocks-protocol/messages/connect.js"
+import { DEFAULT_CONTRAST_MODE } from "@notionhq/custom-blocks-protocol/context/contrast.js"
+import type { ConnectMessage } from "@notionhq/custom-blocks-protocol/handshake/connect.js"
 import type {
 	CustomBlockInitErrorInfo,
 	initMessageSchema,
-} from "@notionhq/custom-blocks-protocol/messages/init.js"
-import type { InitResultMessage } from "@notionhq/custom-blocks-protocol/messages/initResult.js"
+} from "@notionhq/custom-blocks-protocol/handshake/init.js"
+import type { InitResultMessage } from "@notionhq/custom-blocks-protocol/handshake/initResult.js"
 import type { InferInput } from "valibot"
-import type { CustomBlockHostFailure } from "../messages/types.js"
-import { unreachable } from "../utils.js"
-import {
-	initialStateTimeoutError,
-	invalidProtocolVersionError,
-	noConnectError,
-	noInitResultError,
-	unknownInitializationError,
-	unsupportedProtocolVersionError,
-} from "./initErrors.js"
-import { isValidBridgeProtocolVersion } from "./protocolVersion.js"
-import type {
-	CustomBlockHostInitialStateResult,
-	CustomBlockManifestSource,
-	InitStatus,
-} from "./types.js"
+import type { CustomBlockHostInitialStateResult } from "../context/initialState.js"
+import type { CustomBlockManifestSource } from "../manifest/types.js"
+import { unreachable } from "../utils/unreachable.js"
+import { initialStateTimeoutError } from "./errors/initialStateTimeoutError.js"
+import { invalidProtocolVersionError } from "./errors/invalidProtocolVersionError.js"
+import { noConnectError } from "./errors/noConnectError.js"
+import { noInitResultError } from "./errors/noInitResultError.js"
+import { unknownInitializationError } from "./errors/unknownInitializationError.js"
+import { unsupportedProtocolVersionError } from "./errors/unsupportedProtocolVersionError.js"
+import { isValidBridgeProtocolVersion } from "./isValidBridgeProtocolVersion.js"
+import type { CustomBlockHostFailure, InitStatus } from "./types.js"
 
 const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5_000
 const DEFAULT_INITIAL_STATE_TIMEOUT_MS = 5_000

package/src/lifecycle/errors/contextUnavailableError.ts

@@ -0,0 +1,10 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+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,
+	}
+}

package/src/lifecycle/errors/initialStateTimeoutError.ts

@@ -0,0 +1,10 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+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,
+	}
+}

package/src/lifecycle/errors/invalidConnectPayloadError.ts

@@ -0,0 +1,10 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+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,
+	}
+}