@notionhq/custom-blocks-host 0.1.23 → 0.1.25

package/README.md

@@ -127,14 +127,19 @@ and record access.
 
 ### Query requests
 
-The `queryDataSource` handler receives raw data source and property IDs. Its optional `filter` and
-`sorts` fields have already been resolved by the SDK. The host validates that sorts contain at most
-10 unique property IDs, checks property IDs and currently supported property types against the bound
-collection schema when available, and applies valid sorts in the order provided by the array.
-
-When a data source binding includes `collectionSchema`, the runtime validates select, multi-select,
-and status option names before invoking `queryDataSource`. Bindings without a collection schema
-cannot perform this check, so their query handlers remain responsible for validating option names.
+The `queryDataSource` handler receives raw data source and property IDs. The SDK resolves semantic
+keys before it sends a request. The runtime requires every filter and sort property ID to exist in
+`collectionSchema.propertiesById`. This map must contain only actual database properties. The SDK
+adds synthetic metadata to its separate read map, `propertySchemasById`.
+
+For SDKs using protocol 3 or 4, the runtime adds synthetic metadata schemas to outgoing
+`collectionSchema` payloads during initialization and binding updates. Query validation still uses
+the actual database schema supplied by the host. Protocol 5 SDKs receive that schema directly and
+add the metadata read schemas themselves.
+
+The runtime validates option names, supported sort types, and the limit of ten unique sort
+properties before it invokes the handler. Sorts retain their array order. Extra fields and mixed
+filter types fail protocol validation.
 
 `initialState.dataSources` may also be a function of the successful `connect` message. This lets a
 host derive bindings from the sandbox-provided manifest.

package/dist/createCustomBlockHost.d.ts

@@ -12,16 +12,19 @@ export type CustomBlockHostOptions = {
     iframe: HTMLIFrameElement;
     sandboxOrigin: string;
     /**
-     * Minimum sandbox protocol version to accept. Defaults to the host runtime
-     * minimum. Higher values retire older SDKs; lower values cannot enable
-     * protocol versions the runtime no longer supports.
+     * Minimum sandbox protocol version to accept. Defaults to the host runtime minimum. Higher
+     * values retire older SDKs; lower values cannot enable protocol versions the runtime no longer
+     * supports.
      */
     minBridgeProtocolVersion?: number;
     noConnectTimeoutMs?: number;
     noInitResultTimeoutMs?: number;
     initialState: CustomBlockHostInitialState;
     handlers: CustomBlockHostHandlers;
-    /** Called as soon as the `manifest` is available after `connect`, before `onInitialized` and binding validation. */
+    /**
+     * Called as soon as the `manifest` is available after `connect`, before `onInitialized` and
+     * binding validation.
+     */
     onManifest?: (manifest: CustomBlockManifest) => void;
     /** Callback fired when the initialization handshake with the sandbox completed successfully. */
     onInitialized?: (state: {
@@ -31,8 +34,7 @@ export type CustomBlockHostOptions = {
     /** Callback fired when the initialization handshake with the sandbox failed or timed out. */
     onInitializationFailure?: (error: CustomBlockHostInitializationFailure) => void;
     /**
-     * Callback fired when the current host and iframe must restart.
-     * Recreate both to continue.
+     * Callback fired when the current host and iframe must restart. Recreate both to continue.
      */
     onRestartRequired?: () => void;
     onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void;

package/dist/createCustomBlockHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../src/createCustomBlockHost.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,8CAA8C,CAAA;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAA;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AAavF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AAiBtG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAGhF,OAAO,KAAK,EACX,iCAAiC,EACjC,2BAA2B,EAC3B,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,uBAAuB,EACvB,oCAAoC,EACpC,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAU5B,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC,oHAAoH;IACpH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAA;IACpD,gGAAgG;IAChG,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACvB,QAAQ,EAAE,mBAAmB,CAAA;QAC7B,aAAa,CAAC,EAAE,MAAM,CAAA;KACtB,KAAK,IAAI,CAAA;IACV,6FAA6F;IAC7F,uBAAuB,CAAC,EAAE,CACzB,KAAK,EAAE,oCAAoC,KACvC,IAAI,CAAA;IACT;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAA;IAC9B,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC,eAAe,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC3D,SAAS,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,KAAK,IAAI,CAAA;IACjD,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,YAAY,EAAE,kBAAkB,CAAA;KAAE,KAAK,IAAI,CAAA;CAClE,CAAA;AAED,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CAuZvB"}
+{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../src/createCustomBlockHost.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,8CAA8C,CAAA;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAA;AACjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AAavF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AAoBtG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAE9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAIhF,OAAO,KAAK,EACX,iCAAiC,EACjC,2BAA2B,EAC3B,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,uBAAuB,EACvB,oCAAoC,EACpC,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAU5B,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAA;IACpD,gGAAgG;IAChG,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACvB,QAAQ,EAAE,mBAAmB,CAAA;QAC7B,aAAa,CAAC,EAAE,MAAM,CAAA;KACtB,KAAK,IAAI,CAAA;IACV,6FAA6F;IAC7F,uBAAuB,CAAC,EAAE,CACzB,KAAK,EAAE,oCAAoC,KACvC,IAAI,CAAA;IACT;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAA;IAC9B,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IACtC,eAAe,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC3D,SAAS,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,KAAK,IAAI,CAAA;IACjD,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,YAAY,EAAE,kBAAkB,CAAA;KAAE,KAAK,IAAI,CAAA;CAClE,CAAA;AAED,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CAgZvB"}

package/dist/createCustomBlockHost.js

@@ -1,6 +1,8 @@
 import { DEFAULT_CONTRAST_MODE, } from "./protocol/contrast.js";
+import { LATEST_BRIDGE_PROTOCOL_VERSION } from "./protocol/protocolVersion.js";
 import { initErrorForFailureReason } from "./lifecycle/initErrors.js";
 import { createInitializationController } from "./lifecycle/initializationController.js";
+import { normalizeHostToSandboxMessage } from "./lifecycle/normalizeHostToSandboxMessage.js";
 import { createSandboxMessageRouter } from "./messages/sandboxMessageRouter.js";
 import { MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION } from "./protocolVersion.js";
 import { QuerySubscriptions, } from "./queries/querySubscriptions.js";
@@ -8,8 +10,8 @@ import { validateQueryDataSourceFilter } from "./queries/validateQueryDataSource
 import { validateQueryDataSourceSorts } from "./queries/validateQueryDataSourceSorts.js";
 export function createCustomBlockHost(options) {
     const { iframe, initialState, handlers, onManifest, onInitialized, onInitializationFailure, onRestartRequired, onLog, sandboxOrigin, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, noInitResultTimeoutMs, } = options;
-    // Callers can retire older SDKs, but cannot restore support for protocols
-    // the runtime no longer implements. Omission uses the runtime minimum.
+    // Callers can retire older SDKs, but cannot restore support for protocols the runtime no longer
+    // implements. Omission uses the runtime minimum.
     const minBridgeProtocolVersion = Math.max(configuredMinBridgeProtocolVersion ??
         MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION, MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION);
     let theme = initialState.theme;
@@ -18,6 +20,7 @@ export function createCustomBlockHost(options) {
     let page = initialState.page;
     let dataSources = initialState.dataSources;
     let activeDataSources;
+    let sandboxBridgeProtocolVersion = LATEST_BRIDGE_PROTOCOL_VERSION;
     let manifest = initialState.manifest;
     let currentUser = initialState.currentUser;
     let pendingThemeChange = false;
@@ -31,8 +34,9 @@ export function createCustomBlockHost(options) {
         onLog?.(direction, payload);
     }
     function post(message) {
-        emit("out", message);
-        iframe.contentWindow?.postMessage(message, sandboxOrigin);
+        const sandboxMessage = normalizeHostToSandboxMessage(message, sandboxBridgeProtocolVersion);
+        emit("out", sandboxMessage);
+        iframe.contentWindow?.postMessage(sandboxMessage, sandboxOrigin);
     }
     function postQueryDataSourceResult(args) {
         const message = args.response.status === "error"
@@ -53,22 +57,12 @@ export function createCustomBlockHost(options) {
     }
     async function handleQuery(message, token = querySubscriptions.subscribe(message)) {
         const collectionSchema = getCollectionSchema(activeDataSources, message.dataSourceId);
-        const filterError = validateQueryDataSourceFilter(message.filter, collectionSchema);
-        if (filterError !== undefined) {
+        const queryError = getQueryValidationError(message, collectionSchema);
+        if (queryError !== undefined) {
             if (querySubscriptions.isCurrent(message.subscriptionId, token)) {
                 postQueryDataSourceResult({
                     subscriptionId: message.subscriptionId,
-                    response: { status: "error", error: filterError },
-                });
-            }
-            return;
-        }
-        const sortError = validateQueryDataSourceSorts(message.sorts, collectionSchema);
-        if (sortError !== undefined) {
-            if (querySubscriptions.isCurrent(message.subscriptionId, token)) {
-                postQueryDataSourceResult({
-                    subscriptionId: message.subscriptionId,
-                    response: { status: "error", error: sortError },
+                    response: { status: "error", error: queryError },
                 });
             }
             return;
@@ -179,7 +173,10 @@ export function createCustomBlockHost(options) {
         if (pendingDataSourcesChange !== undefined) {
             const nextDataSources = pendingDataSourcesChange;
             pendingDataSourcesChange = undefined;
-            post({ type: "dataSourcesChanged", dataSources: nextDataSources });
+            post({
+                type: "dataSourcesChanged",
+                dataSources: nextDataSources,
+            });
         }
         if (pendingCurrentUserChange) {
             pendingCurrentUserChange = false;
@@ -196,6 +193,7 @@ export function createCustomBlockHost(options) {
             currentUser,
         }),
         prepareInit(connect) {
+            sandboxBridgeProtocolVersion = connect.bridgeProtocolVersion;
             manifest = connect.manifest ?? initialState.manifest;
             if (manifest === undefined) {
                 return {
@@ -382,3 +380,18 @@ function getBindingErrorCode(manifest, dataSources) {
     }
     return undefined;
 }
+function getQueryValidationError(message, collectionSchema) {
+    // The host can omit the database schema. Queries without filters or sorts need no schema validation.
+    if (collectionSchema === undefined) {
+        if (message.filter === undefined && (message.sorts?.length ?? 0) === 0) {
+            return undefined;
+        }
+        return {
+            code: "data_source_schema_unavailable",
+            message: "You cannot query this data source with filters or sorts because its schema is unavailable.",
+            isRetryable: false,
+        };
+    }
+    return (validateQueryDataSourceFilter(message.filter, collectionSchema) ??
+        validateQueryDataSourceSorts(message.sorts, collectionSchema));
+}

package/dist/lifecycle/normalizeHostToSandboxMessage.d.ts

@@ -0,0 +1,6 @@
+import type { HostToSandboxMessage } from "../protocol/messages/hostToSandbox.js";
+/**
+ * Normalizes an outgoing message for the bridge protocol version requested by the sandbox.
+ */
+export declare function normalizeHostToSandboxMessage(message: HostToSandboxMessage, bridgeProtocolVersion: number): HostToSandboxMessage;
+//# sourceMappingURL=normalizeHostToSandboxMessage.d.ts.map

package/dist/lifecycle/normalizeHostToSandboxMessage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeHostToSandboxMessage.d.ts","sourceRoot":"","sources":["../../src/lifecycle/normalizeHostToSandboxMessage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AAEtG;;GAEG;AAGH,wBAAgB,6BAA6B,CAC5C,OAAO,EAAE,oBAAoB,EAC7B,qBAAqB,EAAE,MAAM,GAC3B,oBAAoB,CAkCtB"}

package/dist/lifecycle/normalizeHostToSandboxMessage.js

@@ -0,0 +1,38 @@
+import { NOTION_BUILTIN_PROPERTY_SCHEMAS } from "../protocol/dataSources/propertySchema.js";
+/**
+ * Normalizes an outgoing message for the bridge protocol version requested by the sandbox.
+ */
+// TODO(custom-blocks): Remove this function when MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION
+// reaches 5.
+export function normalizeHostToSandboxMessage(message, bridgeProtocolVersion) {
+    // The latest SDK version does not need any normalization.
+    if (bridgeProtocolVersion >= 5) {
+        return message;
+    }
+    const containsDataSources = (message.type === "init" && message.status === "success") ||
+        message.type === "dataSourcesChanged";
+    if (!containsDataSources) {
+        return message;
+    }
+    // Protocol 5 excludes synthetic IDs such as created_time from collectionSchema.propertiesById.
+    // Older SDKs derive read schemas from that map. Restore those entries in outgoing copies so
+    // host query validation still uses the actual database schema.
+    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/dist/protocol/dataSources/dataSource.d.ts

@@ -7,6 +7,11 @@ declare const collectionPointerValidator: v.ObjectSchema<{
 export type NotionCollectionPointer = v.InferOutput<typeof collectionPointerValidator>;
 export declare const notionCollectionSchemaValidator: v.ObjectSchema<{
     readonly id: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionDataSourceId">]>, undefined>;
+    /**
+     * Describes actual database properties in protocol 5. Protocol 3/4 payloads can also include
+     * synthetic metadata for compatibility. Use this map to resolve property bindings. Use this map
+     * to validate filter and sort references.
+     */
     readonly propertiesById: v.RecordSchema<v.StringSchema<undefined>, v.VariantSchema<"type", [v.ObjectSchema<{
         readonly name: v.StringSchema<undefined>;
         readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
@@ -144,8 +149,8 @@ export declare const notionCollectionSchemaValidator: v.ObjectSchema<{
 }, undefined>;
 export type NotionCollectionSchema = v.InferOutput<typeof notionCollectionSchemaValidator>;
 /**
- * Bridge shape for a single data source: a semantic key bound (optionally) to a collection,
- * its property name → ID mapping, and its column schemas.
+ * Describes a data source, its optional database binding, and its property schemas. The
+ * database schema validates query references. The read schemas describe snapshot values.
  */
 export declare const notionDataSourceSchema: v.ObjectSchema<{
     readonly key: v.StringSchema<undefined>;
@@ -154,8 +159,18 @@ export declare const notionDataSourceSchema: v.ObjectSchema<{
         readonly table: v.StringSchema<undefined>;
         readonly spaceId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionSpaceId">]>, undefined>;
     }, undefined>, undefined>;
+    /**
+     * Describes database properties. Use this schema to resolve property bindings. Use this
+     * schema to validate filter and sort references. Undefined when the host does not provide a
+     * database schema.
+     */
     readonly collectionSchema: v.OptionalSchema<v.ObjectSchema<{
         readonly id: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionDataSourceId">]>, undefined>;
+        /**
+         * Describes actual database properties in protocol 5. Protocol 3/4 payloads can also include
+         * synthetic metadata for compatibility. Use this map to resolve property bindings. Use this map
+         * to validate filter and sort references.
+         */
         readonly propertiesById: v.RecordSchema<v.StringSchema<undefined>, v.VariantSchema<"type", [v.ObjectSchema<{
             readonly name: v.StringSchema<undefined>;
             readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
@@ -292,13 +307,21 @@ export declare const notionDataSourceSchema: v.ObjectSchema<{
         }, undefined>], undefined>, undefined>;
     }, undefined>, undefined>;
     /**
-     * Keyed mapping of user-defined keys to a raw property ID. A key mapped to `undefined`
-     * is a declared-but-unbound slot.
+     * Maps user-defined property keys to database property IDs. Use this map to resolve a key
+     * such as `name` to its database property ID. A value of `undefined` marks a declared
+     * property without a valid binding. Synthetic metadata does not add entries to this map.
      */
     readonly propertyIdsByKey: v.RecordSchema<v.StringSchema<undefined>, v.OptionalSchema<v.StringSchema<undefined>, undefined>, undefined>;
     /**
-     * Keyed mapping of raw property IDs to their schema. Always includes the four built-ins
-     * (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`).
+     * Describes property values in query snapshots. Keys use the same property IDs as a snapshot's
+     * `propertiesById` map.
+     *
+     * Includes four synthetic metadata fields, even when the database schema is unavailable:
+     * `created_time`, `last_edited_time`, `created_by`, and `last_edited_by`. Also includes
+     * database properties when the host provides their schema.
+     *
+     * Use `propertiesById` to read a value. Use this map to read the value's schema. Use
+     * `collectionSchema` to validate filter and sort references.
      */
     readonly propertySchemasById: v.RecordSchema<v.StringSchema<undefined>, v.VariantSchema<"type", [v.ObjectSchema<{
         readonly name: v.StringSchema<undefined>;
@@ -442,8 +465,18 @@ export declare const notionDataSourceBindingSchema: v.ObjectSchema<{
         readonly table: v.StringSchema<undefined>;
         readonly spaceId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionSpaceId">]>, undefined>;
     }, undefined>, undefined>;
+    /**
+     * Describes database properties. Use this schema to resolve property bindings. Use this
+     * schema to validate filter and sort references. Undefined when the host does not provide a
+     * database schema.
+     */
     readonly collectionSchema: v.OptionalSchema<v.ObjectSchema<{
         readonly id: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionDataSourceId">]>, undefined>;
+        /**
+         * Describes actual database properties in protocol 5. Protocol 3/4 payloads can also include
+         * synthetic metadata for compatibility. Use this map to resolve property bindings. Use this map
+         * to validate filter and sort references.
+         */
         readonly propertiesById: v.RecordSchema<v.StringSchema<undefined>, v.VariantSchema<"type", [v.ObjectSchema<{
             readonly name: v.StringSchema<undefined>;
             readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
@@ -579,6 +612,12 @@ export declare const notionDataSourceBindingSchema: v.ObjectSchema<{
             readonly type: v.LiteralSchema<"last_edited_by", undefined>;
         }, undefined>], undefined>, undefined>;
     }, undefined>, undefined>;
+    /**
+     * Maps user-defined property keys to database property IDs. Use this map to resolve a key
+     * such as `name` to its database property ID. A value of `undefined` marks a declared
+     * property without a binding. Omitted when the host does not provide property mappings.
+     * Synthetic metadata does not add entries to this map.
+     */
     readonly propertyIdsByKey: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.OptionalSchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
 }, undefined>;
 export type NotionDataSourceBinding = v.InferOutput<typeof notionDataSourceBindingSchema>;
@@ -588,8 +627,18 @@ export declare const notionDataSourceBindingsSchema: v.RecordSchema<v.StringSche
         readonly table: v.StringSchema<undefined>;
         readonly spaceId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionSpaceId">]>, undefined>;
     }, undefined>, undefined>;
+    /**
+     * Describes database properties. Use this schema to resolve property bindings. Use this
+     * schema to validate filter and sort references. Undefined when the host does not provide a
+     * database schema.
+     */
     readonly collectionSchema: v.OptionalSchema<v.ObjectSchema<{
         readonly id: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionDataSourceId">]>, undefined>;
+        /**
+         * Describes actual database properties in protocol 5. Protocol 3/4 payloads can also include
+         * synthetic metadata for compatibility. Use this map to resolve property bindings. Use this map
+         * to validate filter and sort references.
+         */
         readonly propertiesById: v.RecordSchema<v.StringSchema<undefined>, v.VariantSchema<"type", [v.ObjectSchema<{
             readonly name: v.StringSchema<undefined>;
             readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
@@ -725,6 +774,12 @@ export declare const notionDataSourceBindingsSchema: v.RecordSchema<v.StringSche
             readonly type: v.LiteralSchema<"last_edited_by", undefined>;
         }, undefined>], undefined>, undefined>;
     }, undefined>, undefined>;
+    /**
+     * Maps user-defined property keys to database property IDs. Use this map to resolve a key
+     * such as `name` to its database property ID. A value of `undefined` marks a declared
+     * property without a binding. Omitted when the host does not provide property mappings.
+     * Synthetic metadata does not add entries to this map.
+     */
     readonly propertyIdsByKey: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.OptionalSchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
 }, undefined>, undefined>;
 export type NotionDataSourceBindings = v.InferOutput<typeof notionDataSourceBindingsSchema>;

package/dist/protocol/dataSources/dataSource.js

@@ -8,30 +8,59 @@ const collectionPointerValidator = v.object({
 });
 export const notionCollectionSchemaValidator = v.object({
     id: v.optional(notionDataSourceIdSchema),
+    /**
+     * Describes actual database properties in protocol 5. Protocol 3/4 payloads can also include
+     * synthetic metadata for compatibility. Use this map to resolve property bindings. Use this map
+     * to validate filter and sort references.
+     */
     propertiesById: v.record(v.string(), notionPropertySchemaSchema),
 });
 /**
- * Bridge shape for a single data source: a semantic key bound (optionally) to a collection,
- * its property name → ID mapping, and its column schemas.
+ * Describes a data source, its optional database binding, and its property schemas. The
+ * database schema validates query references. The read schemas describe snapshot values.
  */
 export const notionDataSourceSchema = v.object({
     key: v.string(),
     collectionPointer: v.optional(collectionPointerValidator),
+    /**
+     * Describes database properties. Use this schema to resolve property bindings. Use this
+     * schema to validate filter and sort references. Undefined when the host does not provide a
+     * database schema.
+     */
     collectionSchema: v.optional(notionCollectionSchemaValidator),
     /**
-     * Keyed mapping of user-defined keys to a raw property ID. A key mapped to `undefined`
-     * is a declared-but-unbound slot.
+     * Maps user-defined property keys to database property IDs. Use this map to resolve a key
+     * such as `name` to its database property ID. A value of `undefined` marks a declared
+     * property without a valid binding. Synthetic metadata does not add entries to this map.
      */
     propertyIdsByKey: v.record(v.string(), v.optional(v.string())),
     /**
-     * Keyed mapping of raw property IDs to their schema. Always includes the four built-ins
-     * (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`).
+     * Describes property values in query snapshots. Keys use the same property IDs as a snapshot's
+     * `propertiesById` map.
+     *
+     * Includes four synthetic metadata fields, even when the database schema is unavailable:
+     * `created_time`, `last_edited_time`, `created_by`, and `last_edited_by`. Also includes
+     * database properties when the host provides their schema.
+     *
+     * Use `propertiesById` to read a value. Use this map to read the value's schema. Use
+     * `collectionSchema` to validate filter and sort references.
      */
     propertySchemasById: v.record(v.string(), notionPropertySchemaSchema),
 });
 export const notionDataSourceBindingSchema = v.object({
     collectionPointer: v.optional(collectionPointerValidator),
+    /**
+     * Describes database properties. Use this schema to resolve property bindings. Use this
+     * schema to validate filter and sort references. Undefined when the host does not provide a
+     * database schema.
+     */
     collectionSchema: v.optional(notionCollectionSchemaValidator),
+    /**
+     * Maps user-defined property keys to database property IDs. Use this map to resolve a key
+     * such as `name` to its database property ID. A value of `undefined` marks a declared
+     * property without a binding. Omitted when the host does not provide property mappings.
+     * Synthetic metadata does not add entries to this map.
+     */
     propertyIdsByKey: v.optional(v.record(v.string(), v.optional(v.string()))),
 });
 export const notionDataSourceBindingsSchema = v.record(v.string(), notionDataSourceBindingSchema);

package/dist/protocol/dataSources/propertySchema.d.ts

@@ -195,3 +195,5 @@ export type NotionPropertySchema = v.InferOutput<typeof notionPropertySchemaSche
  */
 export declare const NOTION_BUILTIN_PROPERTY_IDS: readonly ["created_time", "last_edited_time", "created_by", "last_edited_by"];
 export type NotionBuiltinPropertyId = (typeof NOTION_BUILTIN_PROPERTY_IDS)[number];
+/** Schemas for synthetic metadata values in query snapshots. */
+export declare const NOTION_BUILTIN_PROPERTY_SCHEMAS: Record<NotionBuiltinPropertyId, NotionPropertySchema>;

package/dist/protocol/dataSources/propertySchema.js

@@ -163,3 +163,10 @@ export const NOTION_BUILTIN_PROPERTY_IDS = [
     "created_by",
     "last_edited_by",
 ];
+/** Schemas for synthetic metadata values in query snapshots. */
+export const NOTION_BUILTIN_PROPERTY_SCHEMAS = {
+    created_time: { type: "created_time", name: "Created time" },
+    last_edited_time: { type: "last_edited_time", name: "Last edited time" },
+    created_by: { type: "created_by", name: "Created by" },
+    last_edited_by: { type: "last_edited_by", name: "Last edited by" },
+};

package/dist/protocol/messages/createPageResult.d.ts

@@ -1,7 +1,7 @@
 import * as v from "valibot";
 import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
 export declare const customBlockCreatePageErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockCreatePageErrorCode = CustomBlockErrorCode<"create_page_failed" | "invalid_page_parent" | "page_access_failed" | "collection_access_failed" | "unknown_data_source_key" | "unmapped_data_source" | "unmapped_property" | "property_id_mismatch" | "duplicate_property" | "invalid_property_value">;
+export type CustomBlockCreatePageErrorCode = CustomBlockErrorCode<"create_page_failed" | "invalid_page_parent" | "page_unavailable" | "collection_access_failed" | "unknown_data_source_key" | "unmapped_data_source" | "unmapped_property" | "property_id_mismatch" | "duplicate_property" | "invalid_property_value">;
 export type CustomBlockCreatePageErrorInfo = CustomBlockErrorInfo<CustomBlockCreatePageErrorCode>;
 export declare const customBlockCreatePageErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

package/dist/protocol/messages/getPage.d.ts

@@ -1,7 +1,7 @@
 import * as v from "valibot";
 import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
 export declare const customBlockGetPageErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockGetPageErrorCode = CustomBlockErrorCode<"get_page_failed" | "page_access_failed">;
+export type CustomBlockGetPageErrorCode = CustomBlockErrorCode<"get_page_failed" | "page_unavailable">;
 export type CustomBlockGetPageErrorInfo = CustomBlockErrorInfo<CustomBlockGetPageErrorCode>;
 export declare const customBlockGetPageErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

package/dist/protocol/messages/hostToSandbox.d.ts

@@ -27,7 +27,10 @@ export declare const hostToSandboxMessageSchema: v.VariantSchema<"type", [v.Vari
     }, undefined>, v.ObjectSchema<{
         readonly type: v.LiteralSchema<"unavailable", undefined>;
     }, undefined>], undefined>;
-    readonly page: v.ObjectSchema<{
+    readonly page: v.VariantSchema<"type", [v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"unavailable", undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"page", undefined>;
         readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
         readonly parent: v.VariantSchema<"type", [v.ObjectSchema<{
             readonly type: v.LiteralSchema<"page_id", undefined>;
@@ -47,7 +50,7 @@ export declare const hostToSandboxMessageSchema: v.VariantSchema<"type", [v.Vari
         }, undefined>, v.ObjectSchema<{
             readonly type: v.LiteralSchema<"unavailable", undefined>;
         }, undefined>], undefined>;
-    }, undefined>;
+    }, undefined>], undefined>;
     readonly manifest: v.ObjectSchema<{
         readonly version: v.LiteralSchema<1, undefined>;
         readonly dataSources: v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
@@ -261,7 +264,10 @@ export declare const hostToSandboxMessageSchema: v.VariantSchema<"type", [v.Vari
     }, undefined>], undefined>;
 }, undefined>, v.ObjectSchema<{
     readonly type: v.LiteralSchema<"pageChanged", undefined>;
-    readonly page: v.ObjectSchema<{
+    readonly page: v.VariantSchema<"type", [v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"unavailable", undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"page", undefined>;
         readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
         readonly parent: v.VariantSchema<"type", [v.ObjectSchema<{
             readonly type: v.LiteralSchema<"page_id", undefined>;
@@ -281,7 +287,7 @@ export declare const hostToSandboxMessageSchema: v.VariantSchema<"type", [v.Vari
         }, undefined>, v.ObjectSchema<{
             readonly type: v.LiteralSchema<"unavailable", undefined>;
         }, undefined>], undefined>;
-    }, undefined>;
+    }, undefined>], undefined>;
 }, undefined>, v.ObjectSchema<{
     readonly type: v.LiteralSchema<"currentUserChanged", undefined>;
     readonly currentUser: v.ObjectSchema<{

package/dist/protocol/messages/init.d.ts

@@ -53,7 +53,10 @@ export declare const initMessageSchema: v.VariantSchema<"status", [v.ObjectSchem
     }, undefined>, v.ObjectSchema<{
         readonly type: v.LiteralSchema<"unavailable", undefined>;
     }, undefined>], undefined>;
-    readonly page: v.ObjectSchema<{
+    readonly page: v.VariantSchema<"type", [v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"unavailable", undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"page", undefined>;
         readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
         readonly parent: v.VariantSchema<"type", [v.ObjectSchema<{
             readonly type: v.LiteralSchema<"page_id", undefined>;
@@ -73,7 +76,7 @@ export declare const initMessageSchema: v.VariantSchema<"status", [v.ObjectSchem
         }, undefined>, v.ObjectSchema<{
             readonly type: v.LiteralSchema<"unavailable", undefined>;
         }, undefined>], undefined>;
-    }, undefined>;
+    }, undefined>], undefined>;
     readonly manifest: v.ObjectSchema<{
         readonly version: v.LiteralSchema<1, undefined>;
         readonly dataSources: v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{

package/dist/protocol/messages/openPage.d.ts

@@ -3,7 +3,7 @@ import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
 export declare const openPageModeSchema: v.PicklistSchema<["side_peek", "center_peek"], undefined>;
 export type OpenPageMode = v.InferOutput<typeof openPageModeSchema>;
 export declare const customBlockOpenPageErrorCodeSchema: v.StringSchema<undefined>;
-export type CustomBlockOpenPageErrorCode = CustomBlockErrorCode<"open_page_failed" | "page_access_failed" | "navigation_unavailable">;
+export type CustomBlockOpenPageErrorCode = CustomBlockErrorCode<"open_page_failed" | "page_unavailable" | "navigation_unavailable">;
 export type CustomBlockOpenPageErrorInfo = CustomBlockErrorInfo<CustomBlockOpenPageErrorCode>;
 export declare const customBlockOpenPageErrorInfoSchema: v.ObjectSchema<{
     readonly code: v.StringSchema<undefined>;

package/dist/protocol/messages/pageChanged.d.ts

@@ -4,7 +4,10 @@ import * as v from "valibot";
  */
 export declare const pageChangedMessageSchema: v.ObjectSchema<{
     readonly type: v.LiteralSchema<"pageChanged", undefined>;
-    readonly page: v.ObjectSchema<{
+    readonly page: v.VariantSchema<"type", [v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"unavailable", undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"page", undefined>;
         readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
         readonly parent: v.VariantSchema<"type", [v.ObjectSchema<{
             readonly type: v.LiteralSchema<"page_id", undefined>;
@@ -24,6 +27,6 @@ export declare const pageChangedMessageSchema: v.ObjectSchema<{
         }, undefined>, v.ObjectSchema<{
             readonly type: v.LiteralSchema<"unavailable", undefined>;
         }, undefined>], undefined>;
-    }, undefined>;
+    }, undefined>], undefined>;
 }, undefined>;
 export type PageChangedMessage = v.InferOutput<typeof pageChangedMessageSchema>;