@notionhq/custom-blocks-host 0.3.8 → 0.4.0

package/src/compatibility/addMetadataReadSchemasForProtocol3To4.ts

@@ -0,0 +1,36 @@
+import { NOTION_BUILTIN_PROPERTY_SCHEMAS } from "@notionhq/custom-blocks-protocol/dataSources/propertySchema.js"
+import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
+
+/**
+ * Protocols 3–4 derive metadata read schemas from host bindings. Restore those
+ * schemas only in outgoing copies so host query validation keeps the actual schema.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 5.
+ */
+export function addMetadataReadSchemasForProtocol3To4(
+	message: Extract<
+		HostToSandboxMessage,
+		{ type: "init"; status: "success" } | { type: "dataSourcesChanged" }
+	>,
+) {
+	return {
+		...message,
+		dataSources: {
+			bindings: Object.fromEntries(
+				Object.entries(message.dataSources.bindings).map(([key, binding]) => [
+					key,
+					{
+						...binding,
+						collectionSchema: {
+							...binding.collectionSchema,
+							propertiesById: {
+								...binding.collectionSchema?.propertiesById,
+								...NOTION_BUILTIN_PROPERTY_SCHEMAS,
+							},
+						},
+					},
+				]),
+			),
+		},
+	}
+}

package/src/compatibility/normalizeHostToSandboxMessage.ts

@@ -0,0 +1,54 @@
+import type {
+	HostToSandboxMessage,
+	HostToSandboxMessageWithProtocol3To5Compatibility,
+} from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
+import {
+	TEXT_FALLBACK_PROPERTY_PROTOCOL_VERSION,
+	UNIFIED_PAGE_PROTOCOL_VERSION,
+} from "@notionhq/custom-blocks-protocol/protocolVersion.js"
+import { addMetadataReadSchemasForProtocol3To4 } from "./addMetadataReadSchemasForProtocol3To4.js"
+import { normalizePageResultsForProtocol3To5 } from "./normalizePageResultsForProtocol3To5.js"
+import { normalizePageResultsForProtocol6 } from "./normalizePageResultsForProtocol6.js"
+
+/**
+ * Encodes current host messages for the sandbox's declared protocol. Handlers use
+ * current shapes. Each target adapter starts from that shape to avoid data loss.
+ * Unchanged messages and error results retain their original payloads.
+ */
+export function normalizeHostToSandboxMessage(
+	message: HostToSandboxMessage,
+	bridgeProtocolVersion: number,
+): HostToSandboxMessageWithProtocol3To5Compatibility {
+	// Accepted compatibility gap (2026-10-31): leave unavailable containing-page
+	// context in init/pageChanged unchanged for early protocol 5 SDKs. Protocol 5
+	// shipped in SDK 0.2.16 on 2026-09-30. SDK 0.2.17 added unavailable context on
+	// 2026-10-02 without a protocol bump. SDK 0.2.16 cannot decode that context.
+	// Preserve normal contexts and later protocol 5 support. Affected blocks must
+	// upgrade their SDK rather than adding SDK-version-based translation here.
+	if (
+		(message.type === "init" && message.status === "success") ||
+		message.type === "dataSourcesChanged"
+	) {
+		return bridgeProtocolVersion < 5
+			? addMetadataReadSchemasForProtocol3To4(message)
+			: message
+	}
+	if (
+		message.type !== "queryDataSourceResult" &&
+		message.type !== "getPageResult" &&
+		message.type !== "createPageResult" &&
+		message.type !== "updatePageResult"
+	) {
+		return message
+	}
+	if (message.status === "error") {
+		return message
+	}
+	if (bridgeProtocolVersion < UNIFIED_PAGE_PROTOCOL_VERSION) {
+		return normalizePageResultsForProtocol3To5(message)
+	}
+	if (bridgeProtocolVersion < TEXT_FALLBACK_PROPERTY_PROTOCOL_VERSION) {
+		return normalizePageResultsForProtocol6(message)
+	}
+	return message
+}

package/src/compatibility/normalizePageResultsForProtocol3To5.ts

@@ -0,0 +1,28 @@
+import type { HostToSandboxMessageWithProtocol3To5Compatibility } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
+import {
+	toPageForProtocol3To5,
+	toQueryPageForProtocol3To5,
+} from "./pageForProtocol3To5.js"
+import type { SuccessfulPageResult } from "./pageResult.js"
+import { toPageWithNullTextFallbackProperties } from "./pageWithNullTextFallbackProperties.js"
+
+/**
+ * Encodes current pages for protocols 3–5. Query values are flat and ID-keyed.
+ * Page operations omit unsupported property objects and use ID-keyed properties.
+ * Convert directly from current pages so query text fallbacks remain available.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 6.
+ */
+export function normalizePageResultsForProtocol3To5(
+	message: SuccessfulPageResult,
+): HostToSandboxMessageWithProtocol3To5Compatibility {
+	if (message.type === "queryDataSourceResult") {
+		return { ...message, items: message.items.map(toQueryPageForProtocol3To5) }
+	}
+	return {
+		...message,
+		page: toPageForProtocol3To5(
+			toPageWithNullTextFallbackProperties(message.page),
+		),
+	}
+}

package/src/compatibility/normalizePageResultsForProtocol6.ts

@@ -0,0 +1,23 @@
+import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
+import type { SuccessfulPageResult } from "./pageResult.js"
+import { toPageWithNullTextFallbackProperties } from "./pageWithNullTextFallbackProperties.js"
+
+/**
+ * Encodes protocol 6 pages, whose receivers require null for text fallback properties.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 7.
+ */
+export function normalizePageResultsForProtocol6(
+	message: SuccessfulPageResult,
+): HostToSandboxMessage {
+	if (message.type === "queryDataSourceResult") {
+		return {
+			...message,
+			items: message.items.map(toPageWithNullTextFallbackProperties),
+		}
+	}
+	return {
+		...message,
+		page: toPageWithNullTextFallbackProperties(message.page),
+	}
+}

package/src/compatibility/normalizeSandboxToHostMessage.ts

@@ -0,0 +1,10 @@
+import { sandboxToHostMessageSchema } from "@notionhq/custom-blocks-protocol/messages/sandboxToHost.js"
+import * as v from "valibot"
+
+/**
+ * Validates sandbox wire messages before handler dispatch. Supported requests
+ * currently share one schema, so parsing produces the current handler shape.
+ */
+export function normalizeSandboxToHostMessage(payload: unknown) {
+	return v.safeParse(sandboxToHostMessageSchema, payload)
+}

package/src/{lifecycle/legacyPage.ts → compatibility/pageForProtocol3To5.ts}

@@ -1,6 +1,6 @@
 import type { NotionDataSourceValue } from "@notionhq/custom-blocks-protocol/dataSources/dataSourceValue.js"
 import type {
-	LegacyNotionPage,
+	NotionPageForProtocol3To5,
 	NotionPagePropertyValue,
 	notionPageDataSchema,
 } from "@notionhq/custom-blocks-protocol/pages/page.js"
@@ -8,9 +8,17 @@ import type { InferOutput } from "valibot"
 import { toNotionDateValue } from "../dateValue.js"
 import { unreachable } from "../utils.js"
 
-export function toLegacyPage(
+/**
+ * Converts current page data to the page-operation format used by protocols 3–5.
+ * Keys property objects by raw ID and omits null properties. Optional icons,
+ * covers, timestamps, and URLs use undefined instead of null in this format.
+ * Call after clearing property objects unsupported by these protocols.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 6.
+ */
+export function toPageForProtocol3To5(
 	page: InferOutput<typeof notionPageDataSchema>,
-): LegacyNotionPage {
+): NotionPageForProtocol3To5 {
 	return {
 		...page,
 		properties: Object.fromEntries(
@@ -27,23 +35,44 @@ export function toLegacyPage(
 	}
 }
 
-export function toLegacyQueryPage(
+/**
+ * Converts a current page to a protocol 3–5 query row, keeping its ID and archive
+ * flags while flattening typed property objects into raw-ID-keyed values.
+ * Copies page creation and edit metadata into the reserved property IDs that
+ * these query readers expect.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 6.
+ */
+export function toQueryPageForProtocol3To5(
 	page: InferOutput<typeof notionPageDataSchema>,
 ) {
 	const propertiesById: Record<string, NotionDataSourceValue | undefined> = {}
 	for (const property of Object.values(page.properties)) {
 		if (property) {
-			propertiesById[property.id] = toLegacyProperty(property)
+			propertiesById[property.id] = toPropertyValueForProtocol3To5(property)
 		}
 	}
 	return {
 		id: page.id,
 		is_archived: page.is_archived,
 		in_trash: page.in_trash,
-		propertiesById,
+		// Reserved metadata IDs retain their historical meaning even if an actual
+		// property uses the same ID. Binding schemas use the same precedence.
+		propertiesById: {
+			...propertiesById,
+			created_time: toDateTimeValueForProtocol3To5(page.created_time),
+			last_edited_time: toDateTimeValueForProtocol3To5(page.last_edited_time),
+			created_by: page.created_by ? [page.created_by] : undefined,
+			last_edited_by: page.last_edited_by ? [page.last_edited_by] : undefined,
+		},
 	}
 }
 
+/**
+ * Flattens rich-text items to the string used by protocol 3–5 query values.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 6.
+ */
 function plainText(items: Record<string, unknown>[]): string {
 	return items
 		.map(item => {
@@ -61,7 +90,13 @@ function plainText(items: Record<string, unknown>[]): string {
 		.join("")
 }
 
-function timestamp(
+/**
+ * Converts a timestamp to the UTC date/time object used by protocol 3–5 queries.
+ * Missing or invalid timestamps produce undefined; time is stored to the minute.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 6.
+ */
+function toDateTimeValueForProtocol3To5(
 	value: string | number | null | undefined,
 ): NotionDataSourceValue | undefined {
 	if (value === undefined || value === null || value === "") {
@@ -79,7 +114,13 @@ function timestamp(
 	}
 }
 
-function toLegacyProperty(
+/**
+ * Converts a typed page property to the scalar, list, record-reference, or
+ * date/time value used by protocol 3–5 query results.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 6.
+ */
+function toPropertyValueForProtocol3To5(
 	property: NotionPagePropertyValue,
 ): NotionDataSourceValue | undefined {
 	switch (property.type) {
@@ -134,11 +175,11 @@ function toLegacyProperty(
 		case "place":
 			return ""
 		case "created_time":
-			return timestamp(property.created_time)
+			return toDateTimeValueForProtocol3To5(property.created_time)
 		case "last_edited_time":
-			return timestamp(property.last_edited_time)
+			return toDateTimeValueForProtocol3To5(property.last_edited_time)
 		case "last_visited_time":
-			return timestamp(property.last_visited_time)
+			return toDateTimeValueForProtocol3To5(property.last_visited_time)
 		case "created_by":
 			return property.created_by ? [property.created_by] : undefined
 		case "last_edited_by":

package/src/compatibility/pageResult.ts

@@ -0,0 +1,18 @@
+import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
+
+/**
+ * Page-bearing responses accepted by the target-protocol adapters. The dispatcher
+ * passes errors and unrelated messages through unchanged before calling them.
+ * Sharing this subset keeps both adapters limited to successful page conversions.
+ */
+export type SuccessfulPageResult = Extract<
+	HostToSandboxMessage,
+	{
+		type:
+			| "queryDataSourceResult"
+			| "getPageResult"
+			| "createPageResult"
+			| "updatePageResult"
+		status: "success"
+	}
+>

package/src/compatibility/pageWithNullTextFallbackProperties.ts

@@ -0,0 +1,53 @@
+import type { notionPageDataSchema } from "@notionhq/custom-blocks-protocol/pages/page.js"
+import type { InferOutput } from "valibot"
+import { unreachable } from "../utils.js"
+
+/**
+ * Shared field conversion for receivers that cannot decode text fallback objects.
+ *
+ * Delete when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION >= 7.
+ */
+export function toPageWithNullTextFallbackProperties(
+	page: InferOutput<typeof notionPageDataSchema>,
+): InferOutput<typeof notionPageDataSchema> {
+	return {
+		...page,
+		properties: Object.fromEntries(
+			Object.entries(page.properties).map(([name, property]) => {
+				switch (property?.type) {
+					case "unique_id":
+					case "button":
+					case "formula":
+					case "location":
+					case "rollup":
+					case "verification":
+						return [name, null]
+					case "title":
+					case "rich_text":
+					case "number":
+					case "url":
+					case "email":
+					case "phone_number":
+					case "checkbox":
+					case "select":
+					case "status":
+					case "multi_select":
+					case "date":
+					case "people":
+					case "relation":
+					case "files":
+					case "place":
+					case "created_time":
+					case "last_edited_time":
+					case "created_by":
+					case "last_edited_by":
+					case "last_visited_time":
+					case undefined:
+						return [name, property]
+					default:
+						return unreachable(property)
+				}
+			}),
+		),
+	}
+}