@notionhq/custom-blocks-host 0.5.2 → 0.7.0

package/docs/bridge/protocol.md

@@ -185,9 +185,15 @@ filter: {
 
 ## Capabilities
 
-`manifest.capabilities` lists `{ capability, resource }` declarations. Both fields are open strings,
-so a newer vocabulary never makes an older receiver reject a manifest. An omitted `capabilities`
-marks a block that predates approval.
+`manifest.capabilities` lists `{ capability, resource }` declarations. `capability` is an open
+string and `resource` is an open string or a non-empty array of them, so a newer vocabulary never
+makes an older receiver reject a manifest. An array declares the capability on each element.
+Receivers never split a resource string on commas. An omitted `capabilities` marks a block that
+predates approval.
+
+Page capability resources can name one manifest data source as `data_source:<key>`. The key is the
+semantic key from `manifest.dataSources`; hosts resolve it to the bound data source when they record
+and check grants. Bare `data_source` covers every declared key.
 
 The `capability_not_granted` error code is reserved for a request that the viewer's grants do not
 cover, with `isRetryable: false`. No adapter sends it yet, and no receiver restricts requests by
@@ -220,3 +226,14 @@ or `""` when absent. Hosts do not evaluate formulas or rollups.
 The host converts responses to the sandbox's declared protocol. See
 [versioning and compatibility](versioning.md) for protocol version rules. The host's
 [compatibility reference](../compatibility.md) describes older response formats.
+
+### Native page icon compatibility
+
+Protocol 9 and later use native icon objects. Protocols 3–8 receive external SVG URLs in page
+operation results. Unified query results in protocols 6–8 also use external SVG URLs; flat query
+results in protocols 3–5 omit icon fields. Native colors accept any string in responses and write
+inputs, so newer host colors do not require an SDK update.
+
+`createPage` accepts native icons, emoji, custom emoji, and URL-backed icons and covers. The
+application adapter checks submitted image URLs against the block's network permissions before
+creating a page.

package/docs/bridge/versioning.md

@@ -17,6 +17,7 @@ conversions.
 
 `connect.bridgeProtocolVersion` selects the wire contract. `sdkVersion` is analytics metadata.
 `LATEST_BRIDGE_PROTOCOL_VERSION` identifies the latest contract defined by the package.
+`NATIVE_ICON_PROTOCOL_VERSION` is 9, the first protocol with native icon responses and writes.
 
 ## Protocol export names
 

package/docs/compatibility.md

@@ -16,7 +16,7 @@ does not guarantee that future features work.
 
 `sdkVersion` is analytics metadata. Compatibility behavior depends on the protocol version.
 
-The current SDK declares protocol 8. The shared runtime minimum is 3. The dev shell uses the Worker
+The current SDK declares protocol 10. The shared runtime minimum is 3. The dev shell uses the Worker
 manifest in host mode and accepts the shared runtime's supported protocol versions. Protocols 7 and
 8 use the same page and query response formats. Protocol 8's local manifest declaration is selected
 only in sandbox mode; host mode uses the persisted manifest. See the
@@ -35,12 +35,13 @@ through.
 
 ## Current compatibility behavior
 
-| Target | Query results                                                               | Page operation results                                        | Binding schemas                                                          |
-| ------ | --------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| 3–4    | Flat ID-keyed values, including synthetic metadata entries                  | ID-keyed properties with unsupported property objects omitted | Synthetic metadata read schemas restored in outgoing copies              |
-| 5      | Same query values as protocols 3–4                                          | Same page format as protocols 3–4                             | Actual database schemas. The SDK supplies synthetic read schemas locally |
-| 6      | Unified name-keyed properties. Text fallback property objects become `null` | Same unified page format                                      | Actual database schemas                                                  |
-| 7+     | Unified pages with typed text fallback properties                           | Same unified page format                                      | Actual database schemas                                                  |
+| Target | Query results                                                               | Page operation results                                        | Binding schemas                                                          | Native icons                                                                |
+| ------ | --------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| 3–4    | Flat ID-keyed values, including synthetic metadata entries                  | ID-keyed properties with unsupported property objects omitted | Synthetic metadata read schemas restored in outgoing copies              | External SVG URLs in page operations; icons omitted from flat query results |
+| 5      | Same query values as protocols 3–4                                          | Same page format as protocols 3–4                             | Actual database schemas. The SDK supplies synthetic read schemas locally | Same as protocols 3–4                                                       |
+| 6      | Unified name-keyed properties. Text fallback property objects become `null` | Same unified page format                                      | Actual database schemas                                                  | External SVG URLs                                                           |
+| 7–8    | Unified pages with typed text fallback properties                           | Same unified page format                                      | Actual database schemas                                                  | External SVG URLs                                                           |
+| 9+     | Unified pages with typed text fallback properties                           | Same unified page format                                      | Actual database schemas                                                  | Native icon objects                                                         |
 
 The synthetic metadata IDs are `created_time`, `last_edited_time`, `created_by`, and
 `last_edited_by`. They retain metadata meaning if an actual property uses the same raw ID. This
@@ -52,6 +53,13 @@ Release-specific compatibility limits are documented in the changelog entries fo
 and
 [protocol 6 text fallback properties](bridge/changelog.md#protocol-6-richer-fallback-properties).
 
+### Native page icons
+
+Protocol 9 and later receive native icon objects. Protocols 3–8 receive external SVG URLs in page
+operation results, and protocols 6–8 also receive them in query results. Protocols 3–5 use flat
+query results without page appearance fields. Omitted native colors default to gray when producing
+SVG URLs.
+
 ### Unavailable containing-page context
 
 Protocols 3–4 receive `context_unavailable` during initialization or stop when containing-page

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notionhq/custom-blocks-host",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Reusable host runtime for Notion custom blocks.",
   "license": "MIT",
   "type": "module",

package/src/compatibility/normalizeHostToSandboxMessage.ts

@@ -3,12 +3,14 @@ import type {
 	HostToSandboxMessageWithProtocol3To5Compatibility,
 } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
 import {
+	NATIVE_ICON_PROTOCOL_VERSION,
 	TEXT_FALLBACK_PROPERTY_PROTOCOL_VERSION,
 	UNIFIED_PAGE_PROTOCOL_VERSION,
 } from "@notionhq/custom-blocks-protocol/utils/protocolVersion.js"
 import { addMetadataReadSchemasForProtocol3To4 } from "./protocol3To4/addMetadataReadSchemasForProtocol3To4.js"
 import { normalizePageResultsForProtocol3To5 } from "./protocol3To5/normalizePageResultsForProtocol3To5.js"
 import { normalizePageResultsForProtocol6 } from "./protocol6/normalizePageResultsForProtocol6.js"
+import { normalizePageResultsForProtocol7To8 } from "./protocol7To8/normalizePageResultsForProtocol7To8.js"
 
 /**
  * Encodes current host messages for the sandbox's declared protocol. Handlers use
@@ -50,5 +52,8 @@ export function normalizeHostToSandboxMessage(
 	if (bridgeProtocolVersion < TEXT_FALLBACK_PROPERTY_PROTOCOL_VERSION) {
 		return normalizePageResultsForProtocol6(message)
 	}
+	if (bridgeProtocolVersion < NATIVE_ICON_PROTOCOL_VERSION) {
+		return normalizePageResultsForProtocol7To8(message)
+	}
 	return message
 }

package/src/compatibility/pages/toIconForProtocol3To8.ts

@@ -0,0 +1,17 @@
+import type { NotionPageIcon } from "@notionhq/custom-blocks-protocol/pages/pageAppearance.js"
+
+/** Converts native icons for legacy receivers. Delete when the runtime minimum reaches 9. */
+export function toIconForProtocol3To8(
+	icon: NotionPageIcon | null,
+): NotionPageIcon | null {
+	if (icon?.type !== "icon") {
+		return icon
+	}
+	const { name, color } = icon.icon
+	return {
+		type: "external",
+		external: {
+			url: `https://www.notion.so/icons/${name}_${color ?? "gray"}.svg`,
+		},
+	}
+}

package/src/compatibility/pages/toPageWithNullTextFallbackProperties.ts

@@ -41,7 +41,6 @@ export function toPageWithNullTextFallbackProperties(
 					case "last_edited_time":
 					case "created_by":
 					case "last_edited_by":
-					case "last_visited_time":
 					case undefined:
 						return [name, property]
 					default:

package/src/compatibility/protocol3To5/toPageForProtocol3To5.ts

@@ -1,5 +1,6 @@
 import type { BridgePageForProtocol3To5 } from "@notionhq/custom-blocks-protocol/compatibility/protocol3To5/bridgePage.js"
 import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
+import { toIconForProtocol3To8 } from "../pages/toIconForProtocol3To8.js"
 
 /**
  * Converts current page data to the page-operation format used by protocols 3–5.
@@ -19,7 +20,7 @@ export function toPageForProtocol3To5(
 				property ? [[property.id, property]] : [],
 			),
 		),
-		icon: page.icon ?? undefined,
+		icon: toIconForProtocol3To8(page.icon) ?? undefined,
 		cover: page.cover ?? undefined,
 		created_time: page.created_time ?? undefined,
 		last_edited_time: page.last_edited_time ?? undefined,

package/src/compatibility/protocol3To5/toPropertyValueForProtocol3To5.ts

@@ -68,8 +68,6 @@ export function toPropertyValueForProtocol3To5(
 			return toDateTimeValueForProtocol3To5(property.created_time)
 		case "last_edited_time":
 			return toDateTimeValueForProtocol3To5(property.last_edited_time)
-		case "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/protocol6/normalizePageResultsForProtocol6.ts

@@ -1,5 +1,7 @@
 import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
+import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
 import type { SuccessfulPageResult } from "../pages/pageResult.js"
+import { toIconForProtocol3To8 } from "../pages/toIconForProtocol3To8.js"
 import { toPageWithNullTextFallbackProperties } from "../pages/toPageWithNullTextFallbackProperties.js"
 
 /**
@@ -13,11 +15,18 @@ export function normalizePageResultsForProtocol6(
 	if (message.type === "queryDataSourceResult") {
 		return {
 			...message,
-			items: message.items.map(toPageWithNullTextFallbackProperties),
+			items: message.items.map(toPageForProtocol6),
 		}
 	}
 	return {
 		...message,
-		page: toPageWithNullTextFallbackProperties(message.page),
+		page: toPageForProtocol6(message.page),
+	}
+}
+
+function toPageForProtocol6(page: BridgePage): BridgePage {
+	return {
+		...toPageWithNullTextFallbackProperties(page),
+		icon: toIconForProtocol3To8(page.icon),
 	}
 }

package/src/compatibility/protocol7To8/normalizePageResultsForProtocol7To8.ts

@@ -0,0 +1,22 @@
+import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
+import type { SuccessfulPageResult } from "../pages/pageResult.js"
+import { toIconForProtocol3To8 } from "../pages/toIconForProtocol3To8.js"
+
+/** Encodes icons for protocols 7–8. Delete when the runtime minimum reaches 9. */
+export function normalizePageResultsForProtocol7To8(
+	message: SuccessfulPageResult,
+): SuccessfulPageResult {
+	if (message.type === "queryDataSourceResult") {
+		if (!message.items.some(page => page.icon?.type === "icon")) {
+			return message
+		}
+		return { ...message, items: message.items.map(toPageWithoutNativeIcon) }
+	}
+	const page = toPageWithoutNativeIcon(message.page)
+	return page === message.page ? message : { ...message, page }
+}
+
+function toPageWithoutNativeIcon(page: BridgePage): BridgePage {
+	const icon = toIconForProtocol3To8(page.icon)
+	return icon === page.icon ? page : { ...page, icon }
+}

package/src/createCustomBlockHost.ts

@@ -603,6 +603,7 @@ export function createCustomBlockHost(
 		getInitStatus: () => initializationController.status,
 		emit,
 		sendNack,
+		sendPageMutationError: postToSandbox,
 		onInvalidConnect: initializationController.handleInvalidConnect,
 		onInvalidInitResult: initializationController.handleInvalidInitResult,
 		onConnect: initializationController.handleConnect,

package/src/index.ts

@@ -44,6 +44,7 @@ export type {
 export type {
 	CreatePageMessageInput,
 	CustomBlockHostOpenPageResult,
+	CustomBlockHostPageIcon,
 	CustomBlockHostPageResult,
 	GetPageMessageInput,
 	OpenPageMessageInput,

package/src/messages/createSandboxMessageRouter.ts

@@ -6,10 +6,16 @@ import type { InitResultMessage } from "@notionhq/custom-blocks-protocol/handsha
 import { isInitHandshakeMessage } from "@notionhq/custom-blocks-protocol/handshake/isInitHandshakeMessage.js"
 import type { InvalidSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/invalidSandboxMessage.js"
 import type { OpenExternalUrlMessage } from "@notionhq/custom-blocks-protocol/navigation/openExternalUrl.js"
-import type { CreatePageMessage } from "@notionhq/custom-blocks-protocol/pages/messages/createPage.js"
+import type {
+	CreatePageMessage,
+	CreatePageResultMessage,
+} from "@notionhq/custom-blocks-protocol/pages/messages/createPage.js"
 import type { GetPageMessage } from "@notionhq/custom-blocks-protocol/pages/messages/getPage.js"
 import type { OpenPageMessage } from "@notionhq/custom-blocks-protocol/pages/messages/openPage.js"
-import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/pages/messages/updatePage.js"
+import type {
+	UpdatePageMessage,
+	UpdatePageResultMessage,
+} from "@notionhq/custom-blocks-protocol/pages/messages/updatePage.js"
 import type { GetUserMessage } from "@notionhq/custom-blocks-protocol/users/messages/getUser.js"
 import type { ListUsersMessage } from "@notionhq/custom-blocks-protocol/users/messages/listUsers.js"
 import * as v from "valibot"
@@ -20,6 +26,7 @@ import { invalidInitResultPayloadError } from "../lifecycle/errors/invalidInitRe
 import type { InitStatus } from "../lifecycle/types.js"
 import { unreachable } from "../utils/unreachable.js"
 import { getInvalidSandboxMessageResponse } from "./getInvalidSandboxMessageResponse.js"
+import { getInvalidNativeIconColorResponse } from "./invalidNativeIconColor.js"
 import type { CustomBlockHostLogDirection } from "./logging.js"
 
 const initializationIdentitySchema = v.object({
@@ -38,6 +45,9 @@ export type SandboxMessageRouterOptions = {
 	getInitStatus: () => InitStatus
 	emit: (direction: CustomBlockHostLogDirection, payload: unknown) => void
 	sendNack: (message: InvalidSandboxMessage) => void
+	sendPageMutationError: (
+		message: UpdatePageResultMessage | CreatePageResultMessage,
+	) => void
 	onInvalidConnect: InitializationController["handleInvalidConnect"]
 	onInvalidInitResult: InitializationController["handleInvalidInitResult"]
 	onConnect: (message: ConnectMessage) => void
@@ -65,6 +75,7 @@ export function createSandboxMessageRouter(
 		getInitStatus,
 		emit,
 		sendNack,
+		sendPageMutationError,
 		onInvalidConnect,
 		onInvalidInitResult,
 		onConnect,
@@ -85,6 +96,11 @@ export function createSandboxMessageRouter(
 		data: unknown,
 		issues: readonly v.BaseIssue<unknown>[],
 	) {
+		const iconError = getInvalidNativeIconColorResponse(data)
+		if (iconError !== undefined && getInitStatus() === "initialized") {
+			sendPageMutationError(iconError)
+			return
+		}
 		emit("warn", {
 			message: "Ignored unsupported sandbox message",
 			payload: redactExternalUrl(data),

package/src/messages/invalidNativeIconColor.ts

@@ -0,0 +1,43 @@
+import { notionIconColorSchema } from "@notionhq/custom-blocks-protocol/icons.js"
+import type { CreatePageResultMessage } from "@notionhq/custom-blocks-protocol/pages/messages/createPage.js"
+import type { UpdatePageResultMessage } from "@notionhq/custom-blocks-protocol/pages/messages/updatePage.js"
+import * as v from "valibot"
+
+const nativeIconMutationSchema = v.object({
+	type: v.picklist(["updatePage", "createPage"]),
+	requestId: v.string(),
+	icon: v.object({
+		type: v.literal("icon"),
+		icon: v.object({ color: v.unknown() }),
+	}),
+})
+
+/** Reject malformed colors with a correlated result before invoking a page mutation handler. */
+export function getInvalidNativeIconColorResponse(
+	data: unknown,
+): UpdatePageResultMessage | CreatePageResultMessage | undefined {
+	const parsed = v.safeParse(nativeIconMutationSchema, data)
+	if (!parsed.success) {
+		return
+	}
+	const color = parsed.output.icon.icon.color
+	if (
+		color === undefined ||
+		v.safeParse(notionIconColorSchema, color).success
+	) {
+		return
+	}
+	return {
+		type:
+			parsed.output.type === "createPage"
+				? "createPageResult"
+				: "updatePageResult",
+		requestId: parsed.output.requestId,
+		status: "error",
+		error: {
+			code: "invalid_icon_color",
+			message: "Use a supported Notion icon color.",
+			isRetryable: false,
+		},
+	}
+}

package/src/pages/types.ts

@@ -3,6 +3,7 @@ import type { createPageMessageSchema } from "@notionhq/custom-blocks-protocol/p
 import type { getPageMessageSchema } from "@notionhq/custom-blocks-protocol/pages/messages/getPage.js"
 import type { openPageMessageSchema } from "@notionhq/custom-blocks-protocol/pages/messages/openPage.js"
 import type { updatePageMessageSchema } from "@notionhq/custom-blocks-protocol/pages/messages/updatePage.js"
+import type { notionPageIconSchema } from "@notionhq/custom-blocks-protocol/pages/pageAppearance.js"
 import type { InferInput } from "valibot"
 import type { CustomBlockHostResult } from "../messages/result.js"
 
@@ -20,3 +21,5 @@ export type CustomBlockHostPageResult = CustomBlockHostResult<{
 export type CustomBlockHostOpenPageResult = CustomBlockHostResult<{
 	pageId: string
 }>
+
+export type CustomBlockHostPageIcon = InferInput<typeof notionPageIconSchema>