@notionhq/custom-blocks-host 0.3.11 → 0.4.1

package/docs/lifecycle.md

@@ -0,0 +1,117 @@
+# Host initialization and lifecycle
+
+The host prepares a block's manifest and context, completes initialization, and manages the
+connection until the iframe is removed. This reference covers state preparation, timeouts,
+callbacks, live state, and cleanup. Start with the [embed example](../README.md#create-a-host).
+
+## Manifest and initial state
+
+Pass the full block URL as `sandboxUrl`. The host derives the origin used to authenticate incoming
+messages and target outgoing messages. `CustomBlockManifestSource` selects the manifest:
+
+| `manifestSource` | Manifest source                                                                                            |
+| ---------------- | ---------------------------------------------------------------------------------------------------------- |
+| `"host"`         | The manifest returned by `getPersistedManifest({ signal })`                                                |
+| `"sandbox"`      | The local declaration supplied in `connect.manifest`, subject to the [local URL policy](#local-block-urls) |
+
+`getPersistedManifest` is required in both modes and starts when the host is created. It returns
+`CustomBlockHostManifestResult`: either `{ status: "success", manifest }` or
+`{ status: "error", error }`. It must not resolve to `null` or `undefined`. A definition that is
+still loading keeps the promise pending; a failed load returns an error result. The host validates
+the result and normalizes the manifest before calling `prepareInitialState`. Omitted `dataSources`
+and each source's omitted `properties` default to `{}`.
+
+The sandbox loads independently and sends `connect`. In sandbox mode, the SDK reads the manifest
+from JSON metadata injected into the local block HTML by dev tooling. The host validates the
+declaration in `connect`. The two sources do not wait for each other; only the selected result
+determines initialization. Sandbox mode has no persisted fallback. The
+[wire reference](bridge/protocol.md#initialization) describes the declaration and its
+validation errors.
+
+Once the selected manifest is ready, the host calls `prepareInitialState({ manifest, signal })`
+once. Return `{ status: "success", initialState }` with context and data-source bindings, or
+`{ status: "error", error }`. This callback also must not resolve to `null` or `undefined`. The host
+validates its result. The prepared state omits the manifest; the host adds the selected manifest to
+`init`. Host-mode preparation runs concurrently with connection setup. Sandbox-mode preparation
+starts after `connect` supplies the declaration. The host sends `init` after preparation and a valid
+connection succeed. A preparation failure is retained until the sandbox connects.
+
+Errors from the selected manifest source retain their `code`, `message`, and `isRetryable`. A
+missing sandbox declaration produces `manifest_unavailable`. A sandbox `manifest_invalid` error is
+ignored in host mode because that mode uses the persisted manifest; other connect errors remain
+fatal. Unexpected exceptions or invalid results from either callback produce `unknown_error`.
+Diagnostics go to `onLog("warn", payload)`. Stopping aborts preparation and suppresses late results
+without a cancellation warning.
+
+## Timeouts
+
+| Option                  | Waits for                             | Default   | Failure code            |
+| ----------------------- | ------------------------------------- | --------- | ----------------------- |
+| `noConnectTimeoutMs`    | `connect` after the first iframe load | 5 seconds | `no_connect`            |
+| `initialStateTimeoutMs` | State preparation after `connect`     | 5 seconds | `initial_state_timeout` |
+| `noInitResultTimeoutMs` | `initResult` after `init`             | 5 seconds | `no_init_result`        |
+
+The SDK waits for `init` without its own timeout. Handshake failures abort preparation and suppress
+late results. Manifest and state preparation providers must respect their `signal`.
+
+## Live state
+
+`setTheme()`, `setContrastMode()`, `setParent()`, `setPage()`, `setDataSources()`, and
+`setCurrentUser()` hold updates during initialization and send them after `initResult.success`. For
+data-source query refreshes, see [Handlers and data](handlers.md#refresh-active-queries).
+
+## Callbacks
+
+The required `onStatusChange(state)` callback receives the `CustomBlockHostStatus` union:
+
+| Status                 | Behavior                                                       | Payload                                                |
+| ---------------------- | -------------------------------------------------------------- | ------------------------------------------------------ |
+| `waitingForConnect`    | The host is listening; reported synchronously during creation  | None                                                   |
+| `preparingInit`        | The host accepted a connection and is preparing initialization | `localManifest`, `sdkVersion`, `bridgeProtocolVersion` |
+| `waitingForInitResult` | Successful `init` was sent; acknowledgment is pending          | None                                                   |
+| `initialized`          | The sandbox accepted initialization                            | `resolvedManifest`, optional `initialHeight`           |
+| `failed`               | Initialization or runtime failed                               | `error`                                                |
+| `stopped`              | The application explicitly disposed of the host                | None                                                   |
+
+`localManifest` is optional and comes only from a permitted local sandbox. It is available before
+initialization completes, so an adapter can use its requirements to prepare bindings.
+`resolvedManifest` is the selected declaration sent in `init`. Rejected connections can skip
+intermediate statuses. Both `failed` and `stopped` are terminal; stopping a failed host releases
+resources without replacing its failure status.
+
+Connection failures contain `{ phase, source, code, message, isRetryable }`. The phase is `connect`,
+`init`, `initResult`, or `runtime`. The source identifies who reported the failure. Failures can
+occur after initialization succeeds.
+
+At `initialized`, apply a supplied `initialHeight` in CSS pixels before revealing the iframe. If the
+height is absent, use your application's default size. The `resize` handler applies later height
+changes. Reveal, sizing, and failure UI belong to the embedding application.
+
+| Other callback                        | Behavior                                                                                     |
+| ------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `onQueryUnsubscribed(subscriptionId)` | Runs once when a subscription ends through unsubscribe, replacement, terminal error, or stop |
+| `onLog(direction, payload)`           | Receives bridge messages and warnings                                                        |
+
+## Iframe lifetime
+
+Each host handles one handshake. Create a new host and iframe to retry or replace the block URL. The
+[wire reference](bridge/protocol.md#initialization) defines handshake and
+malformed-message behavior.
+
+The first observed iframe `load` is allowed. A second load stops the host and reports retryable
+`iframe_reloaded`. Load-event cleanup does not isolate documents before that event. A replacement
+document at the same origin can receive messages and invoke handlers until the host stops.
+
+`stop()` removes listeners, cancels preparation, clears timers, ends subscriptions, and suppresses
+pending responses. Call it when removing the iframe.
+
+## Local block URLs
+
+`isAllowedLocalPreviewUrl({ url, hostOrigin })` accepts HTTP or HTTPS URLs on `localhost`,
+`*.localhost`, or `127.0.0.1` without credentials. It rejects the embedding page's origin.
+`hostOrigin` must be nonempty. Pass the embedding page's serialized origin.
+
+The protocol helper `isLocalBlockServerUrl(url)` checks the server URL without requiring origin
+isolation. The host adds the embedding-origin restriction. `manifestSource: "sandbox"` enforces this
+policy before the host starts. An invalid sandbox-mode URL throws `CustomBlockInitializationError`
+with code `invalid_local_preview_url`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notionhq/custom-blocks-host",
-  "version": "0.3.11",
+  "version": "0.4.1",
   "description": "Reusable host runtime for Notion custom blocks.",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,11 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js",
+      "default": "./dist/protocol.js"
     }
   },
   "dependencies": {
@@ -22,6 +27,9 @@
   "files": [
     "src",
     "dist",
-    "README.md"
+    "docs",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_LICENSES.md"
   ]
 }

package/src/autoBindProperties.ts

@@ -6,8 +6,8 @@ export type AutoBindableProperty = {
 }
 
 /**
- * Finds property IDs for a manifest's properties without changing the
- * manifest's semantic keys.
+ * Returns a map from manifest property keys to database property IDs.
+ * Unmapped keys are omitted.
  *
  * For each manifest property:
  * 1. Consider only schema properties of the same type.
@@ -15,6 +15,9 @@ export type AutoBindableProperty = {
  *    (exact string: no trim, no case folding) or its display name equals
  *    the manifest display name after `trim()` and lowercasing.
  * 3. Bind when there is exactly one candidate. Otherwise leave it unmapped.
+ *
+ * An ID match has no priority over a display name match. If they identify two
+ * different properties of the same type, the manifest property stays unmapped.
  */
 export function getAutoBoundPropertyIdsByKey(args: {
 	manifestProperties: Readonly<Record<string, AutoBindableProperty>>

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)
+				}
+			}),
+		),
+	}
+}