@notionhq/custom-blocks-host 0.4.3 → 0.5.1

package/dist/messages/result.d.ts

@@ -0,0 +1,12 @@
+import type { CustomBlockErrorInfo } from "../protocol/utils/errors.js";
+/**
+ * The outcome of a handler operation: success with its data, or failure with an error.
+ * The host turns the result into a response message.
+ */
+export type CustomBlockHostResult<Payload extends object = Record<never, never>> = ({
+    status: "success";
+} & Payload) | {
+    status: "error";
+    error: CustomBlockErrorInfo;
+};
+//# sourceMappingURL=result.d.ts.map

package/dist/messages/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/messages/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kDAAkD,CAAA;AAE5F;;;GAGG;AACH,MAAM,MAAM,qBAAqB,CAChC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAE3C,CAAC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GAAG,OAAO,CAAC,GACjC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,oBAAoB,CAAA;CAAE,CAAA"}

package/dist/messages/result.js

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

package/dist/navigation/types.d.ts

@@ -1,7 +1,5 @@
-import type { BridgeMessagePayload } from "../protocol/messages/messagePayload.js";
-import type { CustomBlockOpenExternalUrlErrorInfo, OpenExternalUrlResultMessage, openExternalUrlMessageSchema } from "../protocol/navigation/openExternalUrl.js";
+import type { openExternalUrlMessageSchema } from "../protocol/navigation/openExternalUrl.js";
 import type { InferInput } from "valibot";
-export type CustomBlockHostOpenExternalUrlResult = BridgeMessagePayload<OpenExternalUrlResultMessage, CustomBlockOpenExternalUrlErrorInfo>;
 export type CustomBlockHostNavigationContext = {
     signal: AbortSignal;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/navigation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAA;AACvG,OAAO,KAAK,EACX,mCAAmC,EACnC,4BAA4B,EAC5B,4BAA4B,EAC5B,MAAM,gEAAgE,CAAA;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,MAAM,MAAM,oCAAoC,GAAG,oBAAoB,CACtE,4BAA4B,EAC5B,mCAAmC,CACnC,CAAA;AAED,MAAM,MAAM,gCAAgC,GAAG;IAC9C,MAAM,EAAE,WAAW,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,2BAA2B,GAAG,UAAU,CACnD,OAAO,4BAA4B,CACnC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/navigation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,gEAAgE,CAAA;AAClH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,MAAM,MAAM,gCAAgC,GAAG;IAC9C,MAAM,EAAE,WAAW,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,2BAA2B,GAAG,UAAU,CACnD,OAAO,4BAA4B,CACnC,CAAA"}

package/dist/pages/types.d.ts

@@ -1,20 +1,18 @@
-import type { BridgeMessagePayload } from "../protocol/messages/messagePayload.js";
-import type { CustomBlockCreatePageErrorInfo, createPageMessageSchema, createPageResultMessageSchema } from "../protocol/pages/messages/createPage.js";
-import type { CustomBlockGetPageErrorInfo, getPageMessageSchema, getPageResultMessageSchema } from "../protocol/pages/messages/getPage.js";
-import type { CustomBlockOpenPageErrorInfo, openPageMessageSchema, openPageResultMessageSchema } from "../protocol/pages/messages/openPage.js";
-import type { CustomBlockUpdatePageErrorInfo, updatePageMessageSchema, updatePageResultMessageSchema } from "../protocol/pages/messages/updatePage.js";
+import type { BridgePage } from "../protocol/pages/bridgePage.js";
+import type { createPageMessageSchema } from "../protocol/pages/messages/createPage.js";
+import type { getPageMessageSchema } from "../protocol/pages/messages/getPage.js";
+import type { openPageMessageSchema } from "../protocol/pages/messages/openPage.js";
+import type { updatePageMessageSchema } from "../protocol/pages/messages/updatePage.js";
 import type { InferInput } from "valibot";
-/**
- * Host results use InferInput so adapters can return plain string IDs.
- * The runtime validates results before sending them and assigns protocol ID brands.
- * Handler requests use parsed protocol types, whose IDs are already branded.
- */
-export type CustomBlockHostCreatePageResult = BridgeMessagePayload<InferInput<typeof createPageResultMessageSchema>, CustomBlockCreatePageErrorInfo>;
-export type CustomBlockHostGetPageResult = BridgeMessagePayload<InferInput<typeof getPageResultMessageSchema>, CustomBlockGetPageErrorInfo>;
-export type CustomBlockHostUpdatePageResult = BridgeMessagePayload<InferInput<typeof updatePageResultMessageSchema>, CustomBlockUpdatePageErrorInfo>;
-export type CustomBlockHostOpenPageResult = BridgeMessagePayload<InferInput<typeof openPageResultMessageSchema>, CustomBlockOpenPageErrorInfo>;
+import type { CustomBlockHostResult } from "../messages/result.js";
 export type CreatePageMessageInput = InferInput<typeof createPageMessageSchema>;
 export type GetPageMessageInput = InferInput<typeof getPageMessageSchema>;
 export type OpenPageMessageInput = InferInput<typeof openPageMessageSchema>;
 export type UpdatePageMessageInput = InferInput<typeof updatePageMessageSchema>;
+export type CustomBlockHostPageResult = CustomBlockHostResult<{
+    page: BridgePage;
+}>;
+export type CustomBlockHostOpenPageResult = CustomBlockHostResult<{
+    pageId: string;
+}>;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pages/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAA;AACvG,OAAO,KAAK,EACX,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EACX,2BAA2B,EAC3B,oBAAoB,EACpB,0BAA0B,EAC1B,MAAM,4DAA4D,CAAA;AACnE,OAAO,KAAK,EACX,4BAA4B,EAC5B,qBAAqB,EACrB,2BAA2B,EAC3B,MAAM,6DAA6D,CAAA;AACpE,OAAO,KAAK,EACX,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC;;;;GAIG;AACH,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,CACjE,UAAU,CAAC,OAAO,6BAA6B,CAAC,EAChD,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC9D,UAAU,CAAC,OAAO,0BAA0B,CAAC,EAC7C,2BAA2B,CAC3B,CAAA;AAED,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,CACjE,UAAU,CAAC,OAAO,6BAA6B,CAAC,EAChD,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,6BAA6B,GAAG,oBAAoB,CAC/D,UAAU,CAAC,OAAO,2BAA2B,CAAC,EAC9C,4BAA4B,CAC5B,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE/E,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEzE,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAE3E,MAAM,MAAM,sBAAsB,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pages/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sDAAsD,CAAA;AACtF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+DAA+D,CAAA;AAC5G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AACtG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6DAA6D,CAAA;AACxG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+DAA+D,CAAA;AAC5G,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAElE,MAAM,MAAM,sBAAsB,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE/E,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEzE,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAE3E,MAAM,MAAM,sBAAsB,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE/E,MAAM,MAAM,yBAAyB,GAAG,qBAAqB,CAAC;IAC7D,IAAI,EAAE,UAAU,CAAA;CAChB,CAAC,CAAA;AACF,MAAM,MAAM,6BAA6B,GAAG,qBAAqB,CAAC;IACjE,MAAM,EAAE,MAAM,CAAA;CACd,CAAC,CAAA"}

package/dist/protocol/context/parent.d.ts

@@ -40,3 +40,5 @@ export declare const notionParentSchema: v.VariantSchema<"type", [v.ObjectSchema
  *   is exposed, including when a readable child identifies the parent as a data source.
  */
 export type NotionParent = v.InferOutput<typeof notionParentSchema>;
+/** A parent reference constructed from application records with plain string IDs. */
+export type BridgeParent = v.InferInput<typeof notionParentSchema>;

package/dist/protocol/index.d.ts

@@ -19,7 +19,7 @@ export type { ResizeMessage } from "./context/messages/resize.js";
 export { resizeMessageSchema } from "./context/messages/resize.js";
 export type { ThemeChangedMessage } from "./context/messages/themeChanged.js";
 export { themeChangedMessageSchema } from "./context/messages/themeChanged.js";
-export type { DataSourceParent, NotionParent, PageParent, } from "./context/parent.js";
+export type { BridgeParent, DataSourceParent, NotionParent, PageParent, } from "./context/parent.js";
 export { dataSourceParentSchema, notionParentSchema, pageParentSchema, } from "./context/parent.js";
 export type { NotionTheme } from "./context/theme.js";
 export { notionThemeSchema } from "./context/theme.js";

package/dist/protocol/pages/makeBridgePage.d.ts

@@ -1,4 +1,6 @@
+import * as v from "valibot";
 import type { BridgePage } from "./bridgePage.js";
-export type MakeBridgePageArgs = Pick<BridgePage, "id" | "parent"> & Partial<Omit<BridgePage, "object" | "id" | "parent">>;
+import { bridgePageSchema } from "./bridgePage.js";
+export type MakeBridgePageArgs = Pick<v.InferInput<typeof bridgePageSchema>, "id" | "parent"> & Partial<Omit<v.InferInput<typeof bridgePageSchema>, "object" | "id" | "parent">>;
 /** Builds a complete bridge page without inventing identity or Notion data. */
 export declare function makeBridgePage(args: MakeBridgePageArgs): BridgePage;

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

@@ -1,4 +1,6 @@
+import * as v from "valibot";
 import type { BridgeUser } from "./bridgeUser.js";
-export type MakeBridgeUserArgs = Pick<BridgeUser, "id" | "person"> & Partial<Omit<BridgeUser, "object" | "type" | "id" | "person">>;
+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/users/types.d.ts

@@ -1,9 +1,15 @@
-import type { BridgeMessagePayload } from "../protocol/messages/messagePayload.js";
-import type { CustomBlockGetUserErrorInfo, getUserMessageSchema, getUserResultMessageSchema } from "../protocol/users/messages/getUser.js";
-import type { CustomBlockListUsersErrorInfo, listUsersMessageSchema, listUsersResultMessageSchema } from "../protocol/users/messages/listUsers.js";
+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";
-export type CustomBlockHostGetUserResult = BridgeMessagePayload<InferInput<typeof getUserResultMessageSchema>, CustomBlockGetUserErrorInfo>;
-export type CustomBlockHostListUsersResult = BridgeMessagePayload<InferInput<typeof listUsersResultMessageSchema>, CustomBlockListUsersErrorInfo>;
+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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/users/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAA;AACvG,OAAO,KAAK,EACX,2BAA2B,EAC3B,oBAAoB,EACpB,0BAA0B,EAC1B,MAAM,4DAA4D,CAAA;AACnE,OAAO,KAAK,EACX,6BAA6B,EAC7B,sBAAsB,EACtB,4BAA4B,EAC5B,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC9D,UAAU,CAAC,OAAO,0BAA0B,CAAC,EAC7C,2BAA2B,CAC3B,CAAA;AAED,MAAM,MAAM,8BAA8B,GAAG,oBAAoB,CAChE,UAAU,CAAC,OAAO,4BAA4B,CAAC,EAC/C,6BAA6B,CAC7B,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEzE,MAAM,MAAM,qBAAqB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAA"}
+{"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/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,7 +47,11 @@ import type {
   CustomBlockHostDataSourcesPayload,
   CustomBlockHostHandlers,
 } from "@notionhq/custom-blocks-host"
-import type { BridgeCustomBlockManifest, 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"
 
@@ -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.3",
+  "version": "0.5.1",
   "description": "Reusable host runtime for Notion custom blocks.",
   "license": "MIT",
   "type": "module",

package/src/context/initialState.ts

@@ -3,13 +3,13 @@ import { notionContrastModeSchema } from "@notionhq/custom-blocks-protocol/conte
 import { notionParentSchema } from "@notionhq/custom-blocks-protocol/context/parent.js"
 import { notionThemeSchema } from "@notionhq/custom-blocks-protocol/context/theme.js"
 import { bridgeDataSourceBindingsSchema } from "@notionhq/custom-blocks-protocol/dataSources/bridgeDataSourceBindings.js"
-import type { CustomBlockInitErrorInfo } from "@notionhq/custom-blocks-protocol/handshake/init.js"
 import { customBlockInitErrorInfoSchema } from "@notionhq/custom-blocks-protocol/handshake/init.js"
 import type { BridgeCustomBlockManifest } from "@notionhq/custom-blocks-protocol/manifest/manifest.js"
 import { manifestSchema } from "@notionhq/custom-blocks-protocol/manifest/manifest.js"
 import { bridgeUserSchema } from "@notionhq/custom-blocks-protocol/users/bridgeUser.js"
 import { notionBlockIdSchema } from "@notionhq/custom-blocks-protocol/utils/ids.js"
 import * as v from "valibot"
+import type { CustomBlockHostResult } from "../messages/result.js"
 
 export const customBlockHostInitialStateSchema = v.object({
 	theme: notionThemeSchema,
@@ -30,15 +30,9 @@ export type CustomBlockHostInitialState = v.InferInput<
 	typeof customBlockHostInitialStateSchema
 >
 
-export type CustomBlockHostInitialStateResult =
-	| {
-			status: "success"
-			initialState: CustomBlockHostInitialState
-	  }
-	| {
-			status: "error"
-			error: CustomBlockInitErrorInfo
-	  }
+export type CustomBlockHostInitialStateResult = CustomBlockHostResult<{
+	initialState: CustomBlockHostInitialState
+}>
 
 export const customBlockHostPreparedStateResultSchema = v.variant("status", [
 	v.object({
@@ -52,12 +46,9 @@ export const customBlockHostPreparedStateResultSchema = v.variant("status", [
 ])
 
 /** Adapter-owned state or an explicit preparation error. The host adds the manifest to init. */
-export type CustomBlockHostPreparedStateResult =
-	| {
-			status: "success"
-			initialState: Omit<CustomBlockHostInitialState, "manifest">
-	  }
-	| { status: "error"; error: CustomBlockInitErrorInfo }
+export type CustomBlockHostPreparedStateResult = CustomBlockHostResult<{
+	initialState: Omit<CustomBlockHostInitialState, "manifest">
+}>
 
 export type CustomBlockHostPrepareInitialState = (args: {
 	manifest: BridgeCustomBlockManifest

package/src/createCustomBlockHost.ts

@@ -1,7 +1,7 @@
 import type { customBlockPageSchema } from "@notionhq/custom-blocks-protocol/context/containingPage.js"
-import type { notionContrastModeSchema } from "@notionhq/custom-blocks-protocol/context/contrast.js"
-import type { notionParentSchema } from "@notionhq/custom-blocks-protocol/context/parent.js"
-import type { notionThemeSchema } from "@notionhq/custom-blocks-protocol/context/theme.js"
+import type { NotionContrastMode } from "@notionhq/custom-blocks-protocol/context/contrast.js"
+import type { BridgeParent } from "@notionhq/custom-blocks-protocol/context/parent.js"
+import type { NotionTheme } from "@notionhq/custom-blocks-protocol/context/theme.js"
 import { bridgeDataSourceBindingsSchema } from "@notionhq/custom-blocks-protocol/dataSources/bridgeDataSourceBindings.js"
 import type { NotionCollectionSchema } from "@notionhq/custom-blocks-protocol/dataSources/collectionSchema.js"
 import type {
@@ -24,7 +24,8 @@ import type {
 	OpenExternalUrlMessage,
 	OpenExternalUrlResultMessage,
 } from "@notionhq/custom-blocks-protocol/navigation/openExternalUrl.js"
-import type { bridgeUserSchema } from "@notionhq/custom-blocks-protocol/users/bridgeUser.js"
+import type { BridgeUser } from "@notionhq/custom-blocks-protocol/users/bridgeUser.js"
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
 import type { NotionDataSourceId } from "@notionhq/custom-blocks-protocol/utils/ids.js"
 import { notionDataSourceIdSchema } from "@notionhq/custom-blocks-protocol/utils/ids.js"
 import { LATEST_BRIDGE_PROTOCOL_VERSION } from "@notionhq/custom-blocks-protocol/utils/protocolVersion.js"
@@ -112,19 +113,33 @@ export type CustomBlockHostOptions = {
 	initialStateTimeoutMs?: number
 }
 
+/** Reports local acceptance, not sandbox delivery or initialization success. */
+export type CustomBlockHostSetDataSourcesResult =
+	| { status: "success" }
+	| {
+			status: "error"
+			error: CustomBlockErrorInfo<
+				| "missing_data_source_binding"
+				| "missing_property_binding"
+				| "invalid_property_binding"
+			>
+	  }
+
 export type CustomBlockHostHandle = {
 	stop: () => void
-	setTheme: (theme: InferInput<typeof notionThemeSchema>) => void
-	setContrastMode: (
-		contrastMode: InferInput<typeof notionContrastModeSchema>,
-	) => void
-	setParent: (parent: InferInput<typeof notionParentSchema>) => void
+	setTheme: (theme: NotionTheme) => void
+	setContrastMode: (contrastMode: NotionContrastMode) => void
+	setParent: (parent: BridgeParent) => void
 	setPage: (page: InferInput<typeof customBlockPageSchema>) => void
-	setDataSources: (dataSources: CustomBlockHostDataSourcesPayload) => void
-	setCurrentUser: (currentUser: InferInput<typeof bridgeUserSchema>) => void
-	refreshQuery: (args: {
-		dataSourceId: InferInput<typeof notionDataSourceIdSchema>
-	}) => void
+	/**
+	 * Reports synchronous local acceptance, not sandbox delivery or initialization success.
+	 * Malformed bindings can throw during schema parsing.
+	 */
+	setDataSources: (
+		dataSources: CustomBlockHostDataSourcesPayload,
+	) => CustomBlockHostSetDataSourcesResult
+	setCurrentUser: (currentUser: BridgeUser) => void
+	refreshQuery: (args: { dataSourceId: string }) => void
 }
 
 /**
@@ -672,19 +687,23 @@ export function createCustomBlockHost(
 						dataSources.bindings,
 					),
 				}
-			if (
-				initializationController.hasConnectedSandbox &&
-				manifest !== undefined &&
-				getBindingError(manifest, normalizedDataSources) !== undefined
-			) {
+			const bindingError =
+				initializationController.hasConnectedSandbox && manifest !== undefined
+					? getBindingError(manifest, normalizedDataSources)
+					: undefined
+			if (bindingError !== undefined) {
 				emit("warn", {
 					message: "Ignored invalid data source bindings update",
 					payload: normalizedDataSources,
 				})
-				return
+				return {
+					status: "error",
+					error: bindingError,
+				}
 			}
 			activeDataSources = normalizedDataSources
 			updateHostState({ dataSources: normalizedDataSources })
+			return { status: "success" }
 		},
 		refreshQuery({ dataSourceId }) {
 			if (initializationController.status !== "initialized") {
@@ -743,7 +762,7 @@ function getCollectionSchema(
 function getBindingError(
 	manifest: BridgeCustomBlockManifest,
 	dataSources: CustomBlockHostDataSourcesPayload,
-): CustomBlockInitErrorInfo | undefined {
+) {
 	for (const [dataSourceKey, manifestDataSource] of Object.entries(
 		manifest.dataSources,
 	)) {

package/src/dataSources/types.ts

@@ -1,22 +1,14 @@
 import type { bridgeDataSourceBindingsSchema } from "@notionhq/custom-blocks-protocol/dataSources/bridgeDataSourceBindings.js"
-import type {
-	CustomBlockQueryDataSourceErrorInfo,
-	queryDataSourceMessageSchema,
-	queryDataSourceResultMessageSchema,
-} from "@notionhq/custom-blocks-protocol/dataSources/messages/queryDataSource.js"
-import type { BridgeMessagePayload } from "@notionhq/custom-blocks-protocol/messages/messagePayload.js"
+import type { queryDataSourceMessageSchema } from "@notionhq/custom-blocks-protocol/dataSources/messages/queryDataSource.js"
+import type { BridgePage } from "@notionhq/custom-blocks-protocol/pages/bridgePage.js"
 import type * as v from "valibot"
 import type { InferInput } from "valibot"
+import type { CustomBlockHostResult } from "../messages/result.js"
 
 export type QueryDataSourceMessageInput = InferInput<
 	typeof queryDataSourceMessageSchema
 >
 
-export type CustomBlockHostQueryDataSourceResult = BridgeMessagePayload<
-	InferInput<typeof queryDataSourceResultMessageSchema>,
-	CustomBlockQueryDataSourceErrorInfo
->
-
 export type CustomBlockHostDataSourcesPayload = {
 	bindings: v.InferInput<typeof bridgeDataSourceBindingsSchema>
 }
@@ -24,3 +16,8 @@ export type CustomBlockHostDataSourcesPayload = {
 export type CustomBlockHostNormalizedDataSourcesPayload = {
 	bindings: v.InferOutput<typeof bridgeDataSourceBindingsSchema>
 }
+
+export type CustomBlockHostQueryDataSourceResult = CustomBlockHostResult<{
+	items: BridgePage[]
+	hasMore: boolean
+}>

package/src/index.ts

@@ -8,6 +8,7 @@ export type { ResizeMessageInput } from "./context/resize.js"
 export {
 	type CustomBlockHostHandle,
 	type CustomBlockHostOptions,
+	type CustomBlockHostSetDataSourcesResult,
 	createCustomBlockHost,
 } from "./createCustomBlockHost.js"
 export {
@@ -35,24 +36,22 @@ export type {
 } from "./manifest/types.js"
 export type { CustomBlockHostHandlers } from "./messages/handlers.js"
 export type { CustomBlockHostLogDirection } from "./messages/logging.js"
+export type { CustomBlockHostResult } from "./messages/result.js"
 export type {
 	CustomBlockHostNavigationContext,
-	CustomBlockHostOpenExternalUrlResult,
 	OpenExternalUrlMessageInput,
 } from "./navigation/types.js"
 export type {
 	CreatePageMessageInput,
-	CustomBlockHostCreatePageResult,
-	CustomBlockHostGetPageResult,
 	CustomBlockHostOpenPageResult,
-	CustomBlockHostUpdatePageResult,
+	CustomBlockHostPageResult,
 	GetPageMessageInput,
 	OpenPageMessageInput,
 	UpdatePageMessageInput,
 } from "./pages/types.js"
 export type {
-	CustomBlockHostGetUserResult,
-	CustomBlockHostListUsersResult,
+	CustomBlockHostUserListResult,
+	CustomBlockHostUserResult,
 	GetUserMessageInput,
 	ListUsersMessageInput,
 } from "./users/types.js"

package/src/manifest/types.ts

@@ -1,7 +1,7 @@
-import type { CustomBlockInitErrorInfo } from "@notionhq/custom-blocks-protocol/handshake/init.js"
 import { customBlockInitErrorInfoSchema } from "@notionhq/custom-blocks-protocol/handshake/init.js"
 import { manifestSchema } from "@notionhq/custom-blocks-protocol/manifest/manifest.js"
 import * as v from "valibot"
+import type { CustomBlockHostResult } from "../messages/result.js"
 
 /** Selects the manifest used to initialize a custom block. Both sources load independently. */
 export type CustomBlockManifestSource =
@@ -19,9 +19,9 @@ export const customBlockHostManifestResultSchema = v.variant("status", [
 ])
 
 /** A persisted manifest or an explicit loading error. The host validates and normalizes it. */
-export type CustomBlockHostManifestResult =
-	| { status: "success"; manifest: v.InferInput<typeof manifestSchema> }
-	| { status: "error"; error: CustomBlockInitErrorInfo }
+export type CustomBlockHostManifestResult = CustomBlockHostResult<{
+	manifest: v.InferInput<typeof manifestSchema>
+}>
 
 export type CustomBlockHostNormalizedManifestResult = v.InferOutput<
 	typeof customBlockHostManifestResultSchema

package/src/messages/handlers.ts

@@ -8,21 +8,17 @@ import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/pages/m
 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 type { CustomBlockHostQueryDataSourceResult } from "../dataSources/types.js"
+import type { CustomBlockHostNavigationContext } from "../navigation/types.js"
 import type {
-	CustomBlockHostNavigationContext,
-	CustomBlockHostOpenExternalUrlResult,
-} from "../navigation/types.js"
-import type {
-	CustomBlockHostCreatePageResult,
-	CustomBlockHostGetPageResult,
 	CustomBlockHostOpenPageResult,
-	CustomBlockHostUpdatePageResult,
+	CustomBlockHostPageResult,
 } from "../pages/types.js"
 import type {
-	CustomBlockHostGetUserResult,
-	CustomBlockHostListUsersResult,
+	CustomBlockHostUserListResult,
+	CustomBlockHostUserResult,
 } from "../users/types.js"
 import type { MaybePromise } from "../utils/maybePromise.js"
+import type { CustomBlockHostResult } from "./result.js"
 
 export type CustomBlockHostHandlers = {
 	queryDataSource: (
@@ -30,25 +26,21 @@ export type CustomBlockHostHandlers = {
 	) => MaybePromise<CustomBlockHostQueryDataSourceResult>
 	createPage?: (
 		message: CreatePageMessage,
-	) => MaybePromise<CustomBlockHostCreatePageResult>
-	getPage?: (
-		message: GetPageMessage,
-	) => MaybePromise<CustomBlockHostGetPageResult>
-	getUser?: (
-		message: GetUserMessage,
-	) => MaybePromise<CustomBlockHostGetUserResult>
+	) => MaybePromise<CustomBlockHostPageResult>
+	getPage?: (message: GetPageMessage) => MaybePromise<CustomBlockHostPageResult>
+	getUser?: (message: GetUserMessage) => MaybePromise<CustomBlockHostUserResult>
 	listUsers?: (
 		message: ListUsersMessage,
-	) => MaybePromise<CustomBlockHostListUsersResult>
+	) => MaybePromise<CustomBlockHostUserListResult>
 	openPage?: (
 		message: OpenPageMessage,
 	) => MaybePromise<CustomBlockHostOpenPageResult>
 	openExternalUrl?: (
 		message: OpenExternalUrlMessage,
 		context: CustomBlockHostNavigationContext,
-	) => MaybePromise<CustomBlockHostOpenExternalUrlResult>
+	) => MaybePromise<CustomBlockHostResult>
 	updatePage?: (
 		message: UpdatePageMessage,
-	) => MaybePromise<CustomBlockHostUpdatePageResult>
+	) => MaybePromise<CustomBlockHostPageResult>
 	resize?: (message: ResizeMessage) => void
 }

package/src/messages/result.ts

@@ -0,0 +1,11 @@
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/utils/errors.js"
+
+/**
+ * The outcome of a handler operation: success with its data, or failure with an error.
+ * The host turns the result into a response message.
+ */
+export type CustomBlockHostResult<
+	Payload extends object = Record<never, never>,
+> =
+	| ({ status: "success" } & Payload)
+	| { status: "error"; error: CustomBlockErrorInfo }

package/src/navigation/types.ts

@@ -1,16 +1,6 @@
-import type { BridgeMessagePayload } from "@notionhq/custom-blocks-protocol/messages/messagePayload.js"
-import type {
-	CustomBlockOpenExternalUrlErrorInfo,
-	OpenExternalUrlResultMessage,
-	openExternalUrlMessageSchema,
-} from "@notionhq/custom-blocks-protocol/navigation/openExternalUrl.js"
+import type { openExternalUrlMessageSchema } from "@notionhq/custom-blocks-protocol/navigation/openExternalUrl.js"
 import type { InferInput } from "valibot"
 
-export type CustomBlockHostOpenExternalUrlResult = BridgeMessagePayload<
-	OpenExternalUrlResultMessage,
-	CustomBlockOpenExternalUrlErrorInfo
->
-
 export type CustomBlockHostNavigationContext = {
 	signal: AbortSignal
 }