@notionhq/custom-blocks-host 0.4.2 → 0.4.3

package/src/createCustomBlockHost.ts

@@ -1,80 +1,79 @@
-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 { notionContrastModeSchema } from "@notionhq/custom-blocks-protocol/context/contrast.js"
+import type { notionParentSchema } from "@notionhq/custom-blocks-protocol/context/parent.js"
+import type { notionThemeSchema } 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 { bridgeUserSchema } from "@notionhq/custom-blocks-protocol/users/bridgeUser.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.
@@ -122,7 +121,7 @@ export type CustomBlockHostHandle = {
 	setParent: (parent: InferInput<typeof notionParentSchema>) => void
 	setPage: (page: InferInput<typeof customBlockPageSchema>) => void
 	setDataSources: (dataSources: CustomBlockHostDataSourcesPayload) => void
-	setCurrentUser: (currentUser: InferInput<typeof notionUserSchema>) => void
+	setCurrentUser: (currentUser: InferInput<typeof bridgeUserSchema>) => void
 	refreshQuery: (args: {
 		dataSourceId: InferInput<typeof notionDataSourceIdSchema>
 	}) => void
@@ -168,7 +167,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 +544,7 @@ export function createCustomBlockHost(
 	}
 
 	async function prepare(
-		connectManifest: CustomBlockManifest | undefined,
+		connectManifest: BridgeCustomBlockManifest | undefined,
 	): Promise<CustomBlockHostInitialStateResult> {
 		preparationController.signal.throwIfAborted()
 		const manifestResult = await resolveManifest({
@@ -669,7 +668,7 @@ export function createCustomBlockHost(
 			const normalizedDataSources: CustomBlockHostNormalizedDataSourcesPayload =
 				{
 					bindings: v.parse(
-						notionDataSourceBindingsSchema,
+						bridgeDataSourceBindingsSchema,
 						dataSources.bindings,
 					),
 				}
@@ -742,30 +741,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,26 @@
+import type { bridgeDataSourceBindingsSchema } from "@notionhq/custom-blocks-protocol/dataSources/bridgeDataSourceBindings.js"
+import type {
+	CustomBlockQueryDataSourceErrorInfo,
+	queryDataSourceMessageSchema,
+	queryDataSourceResultMessageSchema,
+} from "@notionhq/custom-blocks-protocol/dataSources/messages/queryDataSource.js"
+import type { BridgeMessagePayload } from "@notionhq/custom-blocks-protocol/messages/messagePayload.js"
+import type * as v from "valibot"
+import type { InferInput } from "valibot"
+
+export type QueryDataSourceMessageInput = InferInput<
+	typeof queryDataSourceMessageSchema
+>
+
+export type CustomBlockHostQueryDataSourceResult = BridgeMessagePayload<
+	InferInput<typeof queryDataSourceResultMessageSchema>,
+	CustomBlockQueryDataSourceErrorInfo
+>
+
+export type CustomBlockHostDataSourcesPayload = {
+	bindings: v.InferInput<typeof bridgeDataSourceBindingsSchema>
+}
+
+export type CustomBlockHostNormalizedDataSourcesPayload = {
+	bindings: v.InferOutput<typeof bridgeDataSourceBindingsSchema>
+}

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,59 @@
-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,
 	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 {
+	CustomBlockHostManifestResult,
+	CustomBlockManifestSource,
+} from "./manifest/types.js"
+export type { CustomBlockHostHandlers } from "./messages/handlers.js"
+export type { CustomBlockHostLogDirection } from "./messages/logging.js"
+export type {
+	CustomBlockHostNavigationContext,
+	CustomBlockHostOpenExternalUrlResult,
+	OpenExternalUrlMessageInput,
+} from "./navigation/types.js"
 export type {
 	CreatePageMessageInput,
 	CustomBlockHostCreatePageResult,
-	CustomBlockHostFailure,
 	CustomBlockHostGetPageResult,
-	CustomBlockHostGetUserResult,
-	CustomBlockHostHandlers,
-	CustomBlockHostListUsersResult,
-	CustomBlockHostLogDirection,
-	CustomBlockHostNavigationContext,
-	CustomBlockHostOpenExternalUrlResult,
 	CustomBlockHostOpenPageResult,
 	CustomBlockHostUpdatePageResult,
 	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 {
+	CustomBlockHostGetUserResult,
+	CustomBlockHostListUsersResult,
+	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,
+	}
+}

package/src/lifecycle/errors/invalidInitResultPayloadError.ts

@@ -0,0 +1,10 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+export function invalidInitResultPayloadError(): CustomBlockErrorInfo<"invalid_init_result_payload"> {
+	return {
+		code: "invalid_init_result_payload",
+		message: "Sandbox sent an invalid initialization result.",
+		// The sandbox must be updated to send a valid initialization result.
+		isRetryable: false,
+	}
+}

package/src/lifecycle/errors/invalidLocalPreviewUrlError.ts

@@ -0,0 +1,10 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+export function invalidLocalPreviewUrlError(): CustomBlockErrorInfo<"invalid_local_preview_url"> {
+	return {
+		code: "invalid_local_preview_url",
+		message:
+			"Local custom blocks require an HTTP(S) URL on localhost, a .localhost subdomain, or 127.0.0.1, without credentials and on a different origin from the host.",
+		isRetryable: false,
+	}
+}

package/src/lifecycle/errors/invalidPropertyBindingError.ts

@@ -0,0 +1,11 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+export function invalidPropertyBindingError(): CustomBlockErrorInfo<"invalid_property_binding"> {
+	return {
+		code: "invalid_property_binding",
+		message: "A mapped data source property is missing or incompatible.",
+		// The bound property's schema must be updated or the binding must be updated to
+		// a property with a compatible schema.
+		isRetryable: false,
+	}
+}

package/src/lifecycle/errors/invalidProtocolVersionError.ts

@@ -0,0 +1,13 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+export function invalidProtocolVersionError(args: {
+	currentBridgeProtocolVersion: number | undefined
+}): CustomBlockErrorInfo<"invalid_protocol_version"> {
+	const { currentBridgeProtocolVersion } = args
+	return {
+		code: "invalid_protocol_version",
+		message: `Sandbox reported an invalid bridge protocol version: ${currentBridgeProtocolVersion}`,
+		// The sandbox must be updated to a supported protocol version.
+		isRetryable: false,
+	}
+}

package/src/lifecycle/errors/missingDataSourceBindingError.ts

@@ -0,0 +1,10 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+export function missingDataSourceBindingError(): CustomBlockErrorInfo<"missing_data_source_binding"> {
+	return {
+		code: "missing_data_source_binding",
+		message: "A required data source is not mapped.",
+		// Host configuration must be changed before this block can initialize.
+		isRetryable: false,
+	}
+}

package/src/lifecycle/errors/missingPropertyBindingError.ts

@@ -0,0 +1,10 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+export function missingPropertyBindingError(): CustomBlockErrorInfo<"missing_property_binding"> {
+	return {
+		code: "missing_property_binding",
+		message: "A required data source property is not mapped.",
+		// Host configuration must be changed before this block can initialize.
+		isRetryable: false,
+	}
+}

package/src/lifecycle/errors/noConnectError.ts

@@ -0,0 +1,15 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+/**
+ * Initialization handshakes are one-shot: after an error, this host instance will not answer
+ * another `connect` message. `isRetryable` means a fresh host and iframe could plausibly
+ * initialize without changing block code or host configuration.
+ */
+export function noConnectError(): CustomBlockErrorInfo<"no_connect"> {
+	return {
+		code: "no_connect",
+		message: "Sandbox did not send a connect message.",
+		// A fresh iframe may finish loading and send connect before the timeout.
+		isRetryable: true,
+	}
+}

package/src/lifecycle/errors/noInitResultError.ts

@@ -0,0 +1,10 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+export function noInitResultError(): CustomBlockErrorInfo<"no_init_result"> {
+	return {
+		code: "no_init_result",
+		message: "Sandbox did not acknowledge initialization.",
+		// A fresh iframe may process init and acknowledge it before the timeout.
+		isRetryable: true,
+	}
+}

package/src/lifecycle/errors/unknownInitializationError.ts

@@ -0,0 +1,10 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+export function unknownInitializationError(): CustomBlockErrorInfo<"unknown_error"> {
+	return {
+		code: "unknown_error",
+		message: "Unexpected error while initializing custom block.",
+		// Without a known transient cause, conservatively treat unknown errors as non-retryable.
+		isRetryable: false,
+	}
+}