@notionhq/custom-blocks-host 0.4.2 → 0.5.0

package/dist/protocol/users/makeBridgeUser.d.ts

@@ -0,0 +1,6 @@
+import * as v from "valibot";
+import type { BridgeUser } from "./bridgeUser.js";
+import { bridgeUserSchema } from "./bridgeUser.js";
+export type MakeBridgeUserArgs = Pick<v.InferInput<typeof bridgeUserSchema>, "id" | "person"> & Partial<Omit<v.InferInput<typeof bridgeUserSchema>, "object" | "type" | "id" | "person">>;
+/** Builds the shared person-user payload; callers supply identity and profile data. */
+export declare function makeBridgeUser(args: MakeBridgeUserArgs): BridgeUser;

package/dist/protocol/users/makeBridgeUser.js

@@ -0,0 +1,11 @@
+import * as v from "valibot";
+import { bridgeUserSchema } from "./bridgeUser.js";
+/** Builds the shared person-user payload; callers supply identity and profile data. */
+export function makeBridgeUser(args) {
+    return v.parse(bridgeUserSchema, {
+        ...args,
+        object: "user",
+        type: "person",
+        avatar_url: args.avatar_url ?? null,
+    });
+}

package/dist/protocol/{messages → users/messages}/currentUserChanged.js

@@ -1,9 +1,9 @@
 import * as v from "valibot";
-import { notionUserSchema } from "../users/user.js";
+import { bridgeUserSchema } from "../bridgeUser.js";
 /**
  * Sent by the host when the viewing user's profile changes while the block is mounted.
  */
 export const currentUserChangedMessageSchema = v.object({
     type: v.literal("currentUserChanged"),
-    currentUser: notionUserSchema,
+    currentUser: bridgeUserSchema,
 });

package/dist/protocol/{messages → users/messages}/getUser.d.ts

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
+import type { CustomBlockCapabilityErrorCode, CustomBlockErrorCode, CustomBlockErrorInfo } from "../../utils/errors.js";
 export declare const customBlockGetUserErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockGetUserErrorCode = CustomBlockErrorCode<"get_user_failed">;
+export type CustomBlockGetUserErrorCode = CustomBlockErrorCode<"get_user_failed" | CustomBlockCapabilityErrorCode>;
 export type CustomBlockGetUserErrorInfo = CustomBlockErrorInfo<CustomBlockGetUserErrorCode>;
 export declare const customBlockGetUserErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

package/dist/protocol/{messages → users/messages}/getUser.js

@@ -1,5 +1,6 @@
 import * as v from "valibot";
-import { notionUserIdSchema, notionUserSchema } from "../users/user.js";
+import { bridgeUserSchema } from "../bridgeUser.js";
+import { notionUserIdSchema } from "../userId.js";
 // The schema accepts any string code. The type lists known codes for
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockGetUserErrorCodeSchema = v.string();
@@ -21,7 +22,7 @@ export const getUserResultMessageSchema = v.variant("status", [
         type: v.literal("getUserResult"),
         requestId: v.string(),
         status: v.literal("success"),
-        user: notionUserSchema,
+        user: bridgeUserSchema,
     }),
     v.object({
         type: v.literal("getUserResult"),

package/dist/protocol/{messages → users/messages}/listUsers.d.ts

@@ -1,7 +1,7 @@
 import * as v from "valibot";
-import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
+import type { CustomBlockCapabilityErrorCode, CustomBlockErrorCode, CustomBlockErrorInfo } from "../../utils/errors.js";
 export declare const customBlockListUsersErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockListUsersErrorCode = CustomBlockErrorCode<"list_users_failed">;
+export type CustomBlockListUsersErrorCode = CustomBlockErrorCode<"list_users_failed" | CustomBlockCapabilityErrorCode>;
 export type CustomBlockListUsersErrorInfo = CustomBlockErrorInfo<CustomBlockListUsersErrorCode>;
 export declare const customBlockListUsersErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

package/dist/protocol/{messages → users/messages}/listUsers.js

@@ -1,5 +1,5 @@
 import * as v from "valibot";
-import { notionUserListSchema } from "../users/user.js";
+import { bridgeUserListSchema } from "../bridgeUserList.js";
 // The schema accepts any string code. The type lists known codes for
 // autocomplete, with an open string fallback for newer senders.
 export const customBlockListUsersErrorCodeSchema = v.string();
@@ -22,7 +22,7 @@ export const listUsersResultMessageSchema = v.variant("status", [
         type: v.literal("listUsersResult"),
         requestId: v.string(),
         status: v.literal("success"),
-        list: notionUserListSchema,
+        list: bridgeUserListSchema,
     }),
     v.object({
         type: v.literal("listUsersResult"),

package/dist/protocol/users/userId.d.ts

@@ -0,0 +1,3 @@
+import * as v from "valibot";
+export declare const notionUserIdSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionUserId">]>;
+export type NotionUserId = v.InferOutput<typeof notionUserIdSchema>;

package/dist/protocol/users/userId.js

@@ -0,0 +1,2 @@
+import * as v from "valibot";
+export const notionUserIdSchema = v.pipe(v.string(), v.brand("NotionUserId"));

package/dist/protocol/{errors.d.ts → utils/errors.d.ts}

@@ -1,5 +1,11 @@
 import * as v from "valibot";
 export type CustomBlockErrorCode<KnownCode extends string> = KnownCode | "unknown_error" | (string & {});
+/**
+ * Reserved for a request that needs a capability the block did not declare or
+ * the viewer did not grant. No host sends it yet.
+ */
+export declare const CAPABILITY_NOT_GRANTED_ERROR_CODE = "capability_not_granted";
+export type CustomBlockCapabilityErrorCode = typeof CAPABILITY_NOT_GRANTED_ERROR_CODE;
 export type CustomBlockErrorInfo<TCode extends string = string> = {
     code: TCode;
     message: string;

package/dist/protocol/utils/errors.js

@@ -0,0 +1,11 @@
+import * as v from "valibot";
+/**
+ * Reserved for a request that needs a capability the block did not declare or
+ * the viewer did not grant. No host sends it yet.
+ */
+export const CAPABILITY_NOT_GRANTED_ERROR_CODE = "capability_not_granted";
+export const customBlockErrorInfoSchema = v.object({
+    code: v.string(),
+    message: v.string(),
+    isRetryable: v.boolean(),
+});

package/dist/protocol/utils/nullableStringSchema.d.ts

@@ -0,0 +1,2 @@
+import * as v from "valibot";
+export declare const nullableStringSchema: v.NullableSchema<v.StringSchema<undefined>, undefined>;

package/dist/protocol/utils/nullableStringSchema.js

@@ -0,0 +1,2 @@
+import * as v from "valibot";
+export const nullableStringSchema = v.nullable(v.string());

package/dist/users/types.d.ts

@@ -0,0 +1,15 @@
+import type { BridgeUser } from "../protocol/users/bridgeUser.js";
+import type { BridgeUserList } from "../protocol/users/bridgeUserList.js";
+import type { getUserMessageSchema } from "../protocol/users/messages/getUser.js";
+import type { listUsersMessageSchema } from "../protocol/users/messages/listUsers.js";
+import type { InferInput } from "valibot";
+import type { CustomBlockHostResult } from "../messages/result.js";
+export type GetUserMessageInput = InferInput<typeof getUserMessageSchema>;
+export type ListUsersMessageInput = InferInput<typeof listUsersMessageSchema>;
+export type CustomBlockHostUserResult = CustomBlockHostResult<{
+    user: BridgeUser;
+}>;
+export type CustomBlockHostUserListResult = CustomBlockHostResult<{
+    list: BridgeUserList;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/users/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/users/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAA;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0DAA0D,CAAA;AAC9F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AACtG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAC1G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAElE,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEzE,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE7E,MAAM,MAAM,yBAAyB,GAAG,qBAAqB,CAAC;IAC7D,IAAI,EAAE,UAAU,CAAA;CAChB,CAAC,CAAA;AACF,MAAM,MAAM,6BAA6B,GAAG,qBAAqB,CAAC;IACjE,IAAI,EAAE,cAAc,CAAA;CACpB,CAAC,CAAA"}

package/dist/users/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/maybePromise.d.ts

@@ -0,0 +1,2 @@
+export type MaybePromise<T> = T | Promise<T>;
+//# sourceMappingURL=maybePromise.d.ts.map

package/dist/utils/maybePromise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maybePromise.d.ts","sourceRoot":"","sources":["../../src/utils/maybePromise.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA"}

package/dist/utils/maybePromise.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/protocolVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocolVersion.d.ts","sourceRoot":"","sources":["../../src/utils/protocolVersion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,0CAA0C,IAAI,CAAA"}

package/dist/utils/toNotionPageId.d.ts

@@ -0,0 +1,3 @@
+import type { NotionPageId } from "../protocol/utils/ids.js";
+export declare function toNotionPageId(id: string): NotionPageId;
+//# sourceMappingURL=toNotionPageId.d.ts.map

package/dist/utils/toNotionPageId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toNotionPageId.d.ts","sourceRoot":"","sources":["../../src/utils/toNotionPageId.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+CAA+C,CAAA;AAIjF,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAEvD"}

package/dist/{ids.js → utils/toNotionPageId.js}

@@ -1,4 +1,4 @@
-import { notionPageIdSchema, } from "./protocol/ids.js";
+import { notionPageIdSchema } from "../protocol/utils/ids.js";
 import * as v from "valibot";
 export function toNotionPageId(id) {
     return v.parse(notionPageIdSchema, id);

package/dist/{utils.d.ts → utils/unreachable.d.ts}

@@ -2,4 +2,4 @@
  * Throws when a discriminated union has an unexpected member.
  */
 export declare function unreachable(value: never): never;
-//# sourceMappingURL=utils.d.ts.map
+//# sourceMappingURL=unreachable.d.ts.map

package/dist/utils/unreachable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.d.ts","sourceRoot":"","sources":["../../src/utils/unreachable.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAI/C"}

package/docs/bridge/protocol.md

@@ -107,13 +107,18 @@ for `code`, including unknown codes. TypeScript aliases list known codes for aut
 
 ### Bindings and IDs
 
-Hosts send `NotionDataSourceBindings` as `dataSources: { bindings }`, keyed by the semantic data
+Hosts send `BridgeDataSourceBindings` as `dataSources: { bindings }`, keyed by the semantic data
 source key declared in the manifest. `collectionSchema` contains only actual database properties.
 
 Sandbox-to-host object references are raw IDs. The SDK resolves semantic data-source and property
 keys before sending query or page-operation requests. Get and update requests can carry an optional
 resolved `dataSourceId`.
 
+A binding with `inaccessible: true` marks a bound data source that the viewer can't read. The host
+omits its pointer, schema, and property mappings. The SDK and host still initialize the block. The
+SDK fails queries and page creation that use the data source with `data_source_inaccessible`,
+without sending a message.
+
 ### Query requests
 
 `queryDataSource` may include a resolved `filter` and an ordered `sorts` list. Each sort contains a
@@ -160,6 +165,16 @@ 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.
+
+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
+capability. The SDK's capabilities guide documents the vocabulary.
+
 ## Page context
 
 Containing-page context uses `CustomBlockPage`. The `init.page` and `pageChanged.page` fields

package/docs/bridge/versioning.md

@@ -21,8 +21,8 @@ conversions.
 ## Protocol export names
 
 The `@notionhq/custom-blocks-host/protocol` entrypoint exports wire definitions. Page formats used
-by protocols 3–5 are named `NotionPageForProtocol3To5` and `NotionDataSourcePageForProtocol3To5`,
-with matching `notionPageForProtocol3To5Schema` and `notionDataSourcePageForProtocol3To5Schema`
+by protocols 3–5 are named `BridgePageForProtocol3To5` and `NotionDataSourcePageForProtocol3To5`,
+with matching `bridgePageForProtocol3To5Schema` and `notionDataSourcePageForProtocol3To5Schema`
 validators. Message types and schemas containing `WithProtocol3To5Compatibility` accept both current
 page formats and protocol 3–5 page formats. `UNIFIED_PAGE_PROTOCOL_VERSION` is 6, the minimum
 protocol version that uses unified pages.

package/docs/handlers.md

@@ -15,9 +15,14 @@ hosts must provide their own permissions, data access, and persistence.
 sends no response to that request. A handler returns a result synchronously or as a promise. Errors
 carry `{ code, message, isRetryable }`, with open string codes.
 
-Handler requests are validated messages with branded IDs. Initial state, setters, handler results,
-and `*MessageInput` types accept plain string IDs. The runtime validates these inputs and applies
-schema defaults. ID brands do not check record existence or access.
+### Return bridge data
+
+Handlers return data in the bridge's shared types. Use bridge builders to construct complete objects
+from application records.
+
+The host validates result shapes, matches responses to requests, and converts responses for the
+block's protocol version. Your application checks that records exist and that the viewer may perform
+the requested operation.
 
 Query filters and sorts are validated against the actual bound database schema before
 `queryDataSource` runs. See the [wire reference](bridge/protocol.md#data-sources) for
@@ -42,11 +47,15 @@ import type {
   CustomBlockHostDataSourcesPayload,
   CustomBlockHostHandlers,
 } from "@notionhq/custom-blocks-host"
-import type { CustomBlockManifest, BridgePage } from "@notionhq/custom-blocks-host/protocol"
+import {
+  makeBridgePage,
+  type BridgeCustomBlockManifest,
+  type BridgePage,
+} from "@notionhq/custom-blocks-host/protocol"
 
 const tasksId = "44444444-4444-4444-8444-444444444444"
 
-const manifest: CustomBlockManifest = {
+const manifest: BridgeCustomBlockManifest = {
   version: 1,
   dataSources: {
     tasks: {
@@ -110,8 +119,7 @@ const handlers: CustomBlockHostHandlers = {
     }
 
     const items: BridgePage[] = [
-      {
-        object: "page",
+      makeBridgePage({
         id: "55555555-5555-4555-8555-555555555555",
         parent: { type: "data_source_id", data_source_id: tasksId },
         is_archived: false,
@@ -119,7 +127,7 @@ const handlers: CustomBlockHostHandlers = {
         properties: {
           Estimate: { id: "estimate-id", type: "number", number: estimate },
         },
-      },
+      }),
     ]
 
     return {

package/docs/lifecycle.md

@@ -60,6 +60,20 @@ late results. Manifest and state preparation providers must respect their `signa
 `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).
 
+`setDataSources()` returns a synchronous `CustomBlockHostSetDataSourcesResult`. Success means local
+acceptance only; it does not guarantee sandbox delivery or successful initialization. Existing
+callers can ignore the return value. Malformed bindings can throw during schema parsing.
+
+- `{ status: "success" }`: accepts the bindings into local state.
+- `{ status: "error", error: { code, message, isRetryable } }`: logs a warning, keeps the last
+  accepted bindings and pending update, and sends no update. Codes are
+  `missing_data_source_binding`, `missing_property_binding`, and `invalid_property_binding`. All
+  have `isRetryable: false`; correct the bindings before resubmitting.
+
+Pre-connect updates are checked against the selected manifest during initialization. Later updates
+are validated once that manifest is available. Accepted updates wait for `initResult.success` before
+sending; after failed initialization, they only change local state and do not restart it.
+
 ## Callbacks
 
 The required `onStatusChange(state)` callback receives the `CustomBlockHostStatus` union:

package/package.json

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

package/src/compatibility/normalizeHostToSandboxMessage.ts

@@ -5,10 +5,10 @@ import type {
 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"
+} 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"
 
 /**
  * Encodes current host messages for the sandbox's declared protocol. Handlers use

package/src/compatibility/{pageWithNullTextFallbackProperties.ts → pages/toPageWithNullTextFallbackProperties.ts}

@@ -1,6 +1,6 @@
-import type { bridgePageSchema } from "@notionhq/custom-blocks-protocol/pages/page.js"
+import type { bridgePageSchema } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
 import type { InferOutput } from "valibot"
-import { unreachable } from "../utils.js"
+import { unreachable } from "../../utils/unreachable.js"
 
 /**
  * Shared field conversion for receivers that cannot decode text fallback objects.

package/src/compatibility/{addMetadataReadSchemasForProtocol3To4.ts → protocol3To4/addMetadataReadSchemasForProtocol3To4.ts}

@@ -1,4 +1,4 @@
-import { NOTION_BUILTIN_PROPERTY_SCHEMAS } from "@notionhq/custom-blocks-protocol/dataSources/propertySchema.js"
+import { NOTION_BUILTIN_PROPERTY_SCHEMAS } from "@notionhq/custom-blocks-protocol/dataSources/properties/propertySchema.js"
 import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
 
 /**

package/src/compatibility/{normalizePageResultsForProtocol3To5.ts → protocol3To5/normalizePageResultsForProtocol3To5.ts}

@@ -1,10 +1,8 @@
 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"
+import type { SuccessfulPageResult } from "../pages/pageResult.js"
+import { toPageWithNullTextFallbackProperties } from "../pages/toPageWithNullTextFallbackProperties.js"
+import { toPageForProtocol3To5 } from "./toPageForProtocol3To5.js"
+import { toQueryPageForProtocol3To5 } from "./toQueryPageForProtocol3To5.js"
 
 /**
  * Encodes current pages for protocols 3–5. Query values are flat and ID-keyed.

package/src/compatibility/protocol3To5/toDateTimeValueForProtocol3To5.ts

@@ -0,0 +1,25 @@
+import type { NotionDataSourceValue } from "@notionhq/custom-blocks-protocol/compatibility/protocol3To5/dataSourceValue.js"
+
+/**
+ * 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.
+ */
+export function toDateTimeValueForProtocol3To5(
+	value: string | number | null | undefined,
+): NotionDataSourceValue | undefined {
+	if (value === undefined || value === null || value === "") {
+		return undefined
+	}
+	const date = new Date(value)
+	if (!Number.isFinite(date.getTime())) {
+		return undefined
+	}
+	return {
+		type: "datetime",
+		start_date: date.toISOString().slice(0, 10),
+		start_time: date.toISOString().slice(11, 16),
+		time_zone: "UTC",
+	}
+}

package/src/compatibility/protocol3To5/toPageForProtocol3To5.ts

@@ -0,0 +1,29 @@
+import type { BridgePageForProtocol3To5 } from "@notionhq/custom-blocks-protocol/compatibility/protocol3To5/bridgePage.js"
+import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
+
+/**
+ * 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: BridgePage,
+): BridgePageForProtocol3To5 {
+	return {
+		...page,
+		properties: Object.fromEntries(
+			Object.values(page.properties).flatMap(property =>
+				property ? [[property.id, property]] : [],
+			),
+		),
+		icon: page.icon ?? undefined,
+		cover: page.cover ?? undefined,
+		created_time: page.created_time ?? undefined,
+		last_edited_time: page.last_edited_time ?? undefined,
+		url: page.url ?? undefined,
+		public_url: page.public_url ?? undefined,
+	}
+}

package/src/compatibility/protocol3To5/toPropertyValueForProtocol3To5.ts

@@ -0,0 +1,102 @@
+import type { NotionDataSourceValue } from "@notionhq/custom-blocks-protocol/compatibility/protocol3To5/dataSourceValue.js"
+import type { BridgePagePropertyValue } from "@notionhq/custom-blocks-protocol/pages/properties/bridgePagePropertyValue.js"
+import { toNotionDateValue } from "../../dataSources/properties/toNotionDateValue.js"
+import { unreachable } from "../../utils/unreachable.js"
+import { toDateTimeValueForProtocol3To5 } from "./toDateTimeValueForProtocol3To5.js"
+
+/**
+ * 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.
+ */
+export function toPropertyValueForProtocol3To5(
+	property: BridgePagePropertyValue,
+): NotionDataSourceValue | undefined {
+	switch (property.type) {
+		case "title":
+			return plainText(property.title)
+		case "rich_text":
+			return plainText(property.rich_text)
+		case "number":
+			return property.number ?? undefined
+		case "checkbox":
+			return property.checkbox
+		case "url":
+			return property.url ?? ""
+		case "email":
+			return property.email ?? ""
+		case "phone_number":
+			return property.phone_number ?? ""
+		case "select":
+			return property.select?.name
+		case "status":
+			return property.status?.name
+		case "multi_select":
+			return property.multi_select.flatMap(option => option.name ?? [])
+		case "date":
+			return property.date ? toNotionDateValue(property.date) : undefined
+		case "people":
+			return property.people.map(person =>
+				person.object === "group"
+					? {
+							id: person.id,
+							table: "space_permission_group",
+							spaceId: person.id.split("|")[1],
+						}
+					: { id: person.id, table: "notion_user" },
+			)
+		case "relation":
+			return property.relation.map(page => ({ id: page.id, table: "block" }))
+		case "files":
+			return property.files.map(file => file.name).join(",")
+		case "unique_id":
+			return property.unique_id
+		case "button":
+			return property.button
+		case "formula":
+			return property.formula
+		case "location":
+			return property.location
+		case "rollup":
+			return property.rollup
+		case "verification":
+			return property.verification
+		case "place":
+			return ""
+		case "created_time":
+			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":
+			return property.last_edited_by ? [property.last_edited_by] : undefined
+		default:
+			return unreachable(property)
+	}
+}
+
+/**
+ * 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 => {
+			if (typeof item.plain_text === "string") {
+				return item.plain_text
+			}
+			const text = item.text
+			return text &&
+				typeof text === "object" &&
+				"content" in text &&
+				typeof text.content === "string"
+				? text.content
+				: ""
+		})
+		.join("")
+}

package/src/compatibility/protocol3To5/toQueryPageForProtocol3To5.ts

@@ -0,0 +1,35 @@
+import type { NotionDataSourceValue } from "@notionhq/custom-blocks-protocol/compatibility/protocol3To5/dataSourceValue.js"
+import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
+import { toDateTimeValueForProtocol3To5 } from "./toDateTimeValueForProtocol3To5.js"
+import { toPropertyValueForProtocol3To5 } from "./toPropertyValueForProtocol3To5.js"
+
+/**
+ * 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: BridgePage) {
+	const propertiesById: Record<string, NotionDataSourceValue | undefined> = {}
+	for (const property of Object.values(page.properties)) {
+		if (property) {
+			propertiesById[property.id] = toPropertyValueForProtocol3To5(property)
+		}
+	}
+	return {
+		id: page.id,
+		is_archived: page.is_archived,
+		in_trash: page.in_trash,
+		// 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,
+		},
+	}
+}

package/src/compatibility/{normalizePageResultsForProtocol6.ts → protocol6/normalizePageResultsForProtocol6.ts}

@@ -1,6 +1,6 @@
 import type { HostToSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
-import type { SuccessfulPageResult } from "./pageResult.js"
-import { toPageWithNullTextFallbackProperties } from "./pageWithNullTextFallbackProperties.js"
+import type { SuccessfulPageResult } from "../pages/pageResult.js"
+import { toPageWithNullTextFallbackProperties } from "../pages/toPageWithNullTextFallbackProperties.js"
 
 /**
  * Encodes protocol 6 pages, whose receivers require null for text fallback properties.