@notionhq/custom-blocks-host 0.2.10 → 0.2.12

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

@@ -1 +1 @@
-{"version":3,"file":"initializationController.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initializationController.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EACX,wBAAwB,EACxB,iBAAiB,EACjB,MAAM,mDAAmD,CAAA;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAIlE,OAAO,KAAK,EACX,qBAAqB,EACrB,iCAAiC,EACjC,UAAU,EACV,MAAM,YAAY,CAAA;AAMnB,MAAM,MAAM,+BAA+B,GAAG;IAC7C,WAAW,EAAE,CACZ,OAAO,EAAE,qBAAqB,KAC1B,OAAO,CAAC,iCAAiC,CAAC,CAAA;IAC/C,eAAe,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,KAAK,IAAI,CAAA;IACxE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAChC,4BAA4B,EAAE,MAAM,IAAI,CAAA;IACxC,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,mBAAmB,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAA;IAC5D,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACnD,mBAAmB,EAAE,CAAC,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACtC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAA;IACrC,aAAa,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IAChD,gBAAgB,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACtD,oBAAoB,EAAE,CAAC,IAAI,EAAE;QAC5B,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;QACpC,KAAK,EAAE,wBAAwB,CAAA;QAC/B,qBAAqB,EAAE,MAAM,GAAG,SAAS,CAAA;KACzC,KAAK,SAAS,GAAG,MAAM,CAAA;IACxB,uBAAuB,EAAE,CAAC,IAAI,EAAE;QAC/B,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;QACpC,KAAK,EAAE,wBAAwB,CAAA;KAC/B,KAAK,IAAI,CAAA;IACV,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,IAAI,EAAE,MAAM,IAAI,CAAA;CAChB,CAAA;AAED,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,+BAA+B,GACtC,wBAAwB,CAiU1B"}
+{"version":3,"file":"initializationController.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initializationController.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EACX,wBAAwB,EACxB,iBAAiB,EACjB,MAAM,mDAAmD,CAAA;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAWlE,OAAO,KAAK,EACX,qBAAqB,EACrB,iCAAiC,EACjC,UAAU,EACV,MAAM,YAAY,CAAA;AAMnB,MAAM,MAAM,+BAA+B,GAAG;IAC7C,WAAW,EAAE,CACZ,OAAO,EAAE,qBAAqB,KAC1B,OAAO,CAAC,iCAAiC,CAAC,CAAA;IAC/C,eAAe,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,KAAK,IAAI,CAAA;IACxE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAChC,4BAA4B,EAAE,MAAM,IAAI,CAAA;IACxC,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,mBAAmB,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAA;IAC5D,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACnD,mBAAmB,EAAE,CAAC,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;CAC1E,CAAA;AAED,MAAM,MAAM,wBAAwB,GAAG;IACtC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAA;IACrC,aAAa,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IAChD,gBAAgB,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACtD,oBAAoB,EAAE,CAAC,IAAI,EAAE;QAC5B,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;QACpC,KAAK,EAAE,wBAAwB,CAAA;QAC/B,qBAAqB,EAAE,MAAM,GAAG,SAAS,CAAA;KACzC,KAAK,SAAS,GAAG,MAAM,CAAA;IACxB,uBAAuB,EAAE,CAAC,IAAI,EAAE;QAC/B,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;QACpC,KAAK,EAAE,wBAAwB,CAAA;KAC/B,KAAK,IAAI,CAAA;IACV,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,IAAI,EAAE,MAAM,IAAI,CAAA;CAChB,CAAA;AAED,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,+BAA+B,GACtC,wBAAwB,CAgU1B"}

package/dist/lifecycle/initializationController.js

@@ -1,6 +1,6 @@
 import { DEFAULT_CONTRAST_MODE } from "../protocol/contrast.js";
 import { unreachable } from "../utils.js";
-import { initErrorForFailureReason } from "./initErrors.js";
+import { initialStateTimeoutError, invalidProtocolVersionError, noConnectError, noInitResultError, unknownInitializationError, unsupportedProtocolVersionError, } from "./initErrors.js";
 import { isValidBridgeProtocolVersion } from "./protocolVersion.js";
 const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5_000;
 const DEFAULT_INITIAL_STATE_TIMEOUT_MS = 5_000;
@@ -69,7 +69,7 @@ export function createInitializationController(options) {
             if (initStatus !== "preparingInit") {
                 return;
             }
-            const error = initErrorForFailureReason("initial_state_timeout");
+            const error = initialStateTimeoutError();
             warn({
                 ...error,
                 initializationId: connect.initializationId,
@@ -109,7 +109,7 @@ export function createInitializationController(options) {
                     return;
                 }
                 initStatus = "error";
-                const error = initErrorForFailureReason("no_init_result");
+                const error = noInitResultError();
                 onConnectionFailure?.(error);
                 warn({
                     ...error,
@@ -127,7 +127,7 @@ export function createInitializationController(options) {
             });
             sendInitError({
                 initializationId: connect.initializationId,
-                error: initErrorForFailureReason("unknown_error"),
+                error: unknownInitializationError(),
             });
         }
     }
@@ -140,7 +140,7 @@ export function createInitializationController(options) {
         }
         // Verify the bridge protocol version is valid.
         if (!isValidBridgeProtocolVersion(message.bridgeProtocolVersion)) {
-            const initError = initErrorForFailureReason("invalid_protocol_version", {
+            const initError = invalidProtocolVersionError({
                 currentBridgeProtocolVersion: message.bridgeProtocolVersion,
             });
             sendInitError({
@@ -150,7 +150,7 @@ export function createInitializationController(options) {
             return;
         }
         if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
-            const initError = initErrorForFailureReason("unsupported_protocol_version", {
+            const initError = unsupportedProtocolVersionError({
                 currentBridgeProtocolVersion: message.bridgeProtocolVersion,
                 minBridgeProtocolVersion,
             });
@@ -187,10 +187,12 @@ export function createInitializationController(options) {
         // when the malformed message includes a numeric version.
         if (bridgeProtocolVersion !== undefined) {
             if (!isValidBridgeProtocolVersion(bridgeProtocolVersion)) {
-                error = initErrorForFailureReason("invalid_protocol_version");
+                error = invalidProtocolVersionError({
+                    currentBridgeProtocolVersion: undefined,
+                });
             }
             else if (bridgeProtocolVersion < minBridgeProtocolVersion) {
-                error = initErrorForFailureReason("unsupported_protocol_version", {
+                error = unsupportedProtocolVersionError({
                     currentBridgeProtocolVersion: bridgeProtocolVersion,
                     minBridgeProtocolVersion,
                 });
@@ -236,7 +238,7 @@ export function createInitializationController(options) {
                 return;
             }
             initStatus = "error";
-            const error = initErrorForFailureReason("no_connect");
+            const error = noConnectError();
             warn(error);
             onConnectionFailure?.(error);
         }, noConnectTimeoutMs);

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

@@ -1 +1 @@
-{"version":3,"file":"sandboxMessageRouter.d.ts","sourceRoot":"","sources":["../../src/messages/sandboxMessageRouter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oEAAoE,CAAA;AAE/G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wDAAwD,CAAA;AAC9F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uDAAuD,CAAA;AAC5F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AAExF,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,yEAAyE,CAAA;AAChI,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAGhG,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAA;AACxF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAGvD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAA;AAY7D,MAAM,MAAM,2BAA2B,GAAG;IACzC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,UAAU,CAAA;IAC/B,IAAI,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IACxE,QAAQ,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IAClD,gBAAgB,EAAE,wBAAwB,CAAC,sBAAsB,CAAC,CAAA;IAClE,mBAAmB,EAAE,wBAAwB,CAAC,yBAAyB,CAAC,CAAA;IACxE,SAAS,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IAC5C,YAAY,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IAClD,iBAAiB,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5E,4BAA4B,EAAE,CAC7B,OAAO,EAAE,iCAAiC,KACtC,IAAI,CAAA;IACT,YAAY,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClE,UAAU,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9D,SAAS,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,SAAS,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,WAAW,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChE,YAAY,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClE,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CAC1C,CAAA;AAED,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,2BAA2B,GAClC,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAsI/B"}
+{"version":3,"file":"sandboxMessageRouter.d.ts","sourceRoot":"","sources":["../../src/messages/sandboxMessageRouter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oEAAoE,CAAA;AAE/G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wDAAwD,CAAA;AAC9F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uDAAuD,CAAA;AAC5F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AAExF,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,yEAAyE,CAAA;AAChI,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAMhG,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAA;AACxF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAGvD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAA;AAY7D,MAAM,MAAM,2BAA2B,GAAG;IACzC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,UAAU,CAAA;IAC/B,IAAI,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IACxE,QAAQ,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IAClD,gBAAgB,EAAE,wBAAwB,CAAC,sBAAsB,CAAC,CAAA;IAClE,mBAAmB,EAAE,wBAAwB,CAAC,yBAAyB,CAAC,CAAA;IACxE,SAAS,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IAC5C,YAAY,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IAClD,iBAAiB,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5E,4BAA4B,EAAE,CAC7B,OAAO,EAAE,iCAAiC,KACtC,IAAI,CAAA;IACT,YAAY,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClE,UAAU,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9D,SAAS,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,SAAS,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,WAAW,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChE,YAAY,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClE,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CAC1C,CAAA;AAED,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,2BAA2B,GAClC,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAsI/B"}

package/dist/messages/sandboxMessageRouter.js

@@ -1,7 +1,7 @@
 import { isInitHandshakeMessage } from "../protocol/messages/isInitHandshakeMessage.js";
 import { sandboxToHostMessageSchema } from "../protocol/messages/sandboxToHost.js";
 import * as v from "valibot";
-import { initErrorForFailureReason } from "../lifecycle/initErrors.js";
+import { invalidConnectPayloadError, invalidInitResultPayloadError, } from "../lifecycle/initErrors.js";
 import { unreachable } from "../utils.js";
 import { getInvalidSandboxMessageResponse } from "./invalidSandboxMessage.js";
 const initializationIdentitySchema = v.object({
@@ -28,7 +28,7 @@ export function createSandboxMessageRouter(options) {
                 initializationId: parsedIdentity.success
                     ? parsedIdentity.output.initializationId
                     : undefined,
-                error: initErrorForFailureReason("invalid_connect_payload"),
+                error: invalidConnectPayloadError(),
                 bridgeProtocolVersion: parsedVersion.success
                     ? parsedVersion.output.bridgeProtocolVersion
                     : undefined,
@@ -44,7 +44,7 @@ export function createSandboxMessageRouter(options) {
                 initializationId: parsedIdentity.success
                     ? parsedIdentity.output.initializationId
                     : undefined,
-                error: initErrorForFailureReason("invalid_init_result_payload"),
+                error: invalidInitResultPayloadError(),
             });
         }
         // Other messages get NACKed indicating they were invalid and skipped.

package/package.json

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

package/src/createCustomBlockHost.ts

@@ -10,7 +10,7 @@ import {
 	hostToSandboxMessageSchema,
 } from "@notionhq/custom-blocks-protocol/messages/hostToSandbox.js"
 import {
-	type CustomBlockInitErrorCode,
+	type CustomBlockInitErrorInfo,
 	initMessageSchema,
 } from "@notionhq/custom-blocks-protocol/messages/init.js"
 import type { InvalidSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/invalidSandboxMessage.js"
@@ -27,7 +27,12 @@ import type { notionThemeSchema } from "@notionhq/custom-blocks-protocol/theme.j
 import type { notionUserSchema } from "@notionhq/custom-blocks-protocol/users/user.js"
 import type { InferInput } from "valibot"
 import * as v from "valibot"
-import { initErrorForFailureReason } from "./lifecycle/initErrors.js"
+import {
+	contextUnavailableError,
+	invalidPropertyBindingError,
+	missingDataSourceBindingError,
+	missingPropertyBindingError,
+} from "./lifecycle/initErrors.js"
 import { createInitializationController } from "./lifecycle/initializationController.js"
 import { normalizeHostToSandboxMessage } from "./lifecycle/normalizeHostToSandboxMessage.js"
 import type {
@@ -387,17 +392,17 @@ export function createCustomBlockHost(
 		) {
 			return {
 				status: "error",
-				error: initErrorForFailureReason("context_unavailable"),
+				error: contextUnavailableError(),
 			}
 		}
-		const bindingErrorCode = getBindingErrorCode(
+		const bindingError = getBindingError(
 			initialState.manifest,
 			initialState.dataSources,
 		)
-		if (bindingErrorCode !== undefined) {
+		if (bindingError !== undefined) {
 			return {
 				status: "error",
-				error: initErrorForFailureReason(bindingErrorCode),
+				error: bindingError,
 			}
 		}
 		activeDataSources = initialState.dataSources
@@ -464,7 +469,7 @@ export function createCustomBlockHost(
 					initializationController.status === "waitingForInitResult" ||
 					initializationController.status === "initialized")
 			) {
-				stopWithFailure(initErrorForFailureReason("context_unavailable"))
+				stopWithFailure(contextUnavailableError())
 				return
 			}
 			updateHostState({ page })
@@ -483,7 +488,7 @@ export function createCustomBlockHost(
 			if (
 				initializationController.hasConnectedSandbox &&
 				manifest !== undefined &&
-				getBindingErrorCode(manifest, normalizedDataSources) !== undefined
+				getBindingError(manifest, normalizedDataSources) !== undefined
 			) {
 				emit("warn", {
 					message: "Ignored invalid data source bindings update",
@@ -523,10 +528,10 @@ function getCollectionSchema(
 	)?.collectionSchema
 }
 
-function getBindingErrorCode(
+function getBindingError(
 	manifest: InferInput<typeof manifestSchema>,
 	dataSources: CustomBlockHostDataSourcesPayload,
-): CustomBlockInitErrorCode | undefined {
+): CustomBlockInitErrorInfo | undefined {
 	for (const [dataSourceKey, manifestDataSource] of Object.entries(
 		manifest.dataSources,
 	)) {
@@ -535,20 +540,20 @@ function getBindingErrorCode(
 			binding?.collectionPointer === undefined ||
 			binding.collectionSchema === undefined
 		) {
-			return "missing_data_source_binding"
+			return missingDataSourceBindingError()
 		}
 		for (const [propertyKey, manifestProperty] of Object.entries(
 			manifestDataSource.properties ?? {},
 		)) {
 			const propertyId = binding.propertyIdsByKey?.[propertyKey]
 			if (propertyId === undefined) {
-				return "missing_property_binding"
+				return missingPropertyBindingError()
 			}
 			if (
 				binding.collectionSchema.propertiesById[propertyId]?.type !==
 				manifestProperty.type
 			) {
-				return "invalid_property_binding"
+				return invalidPropertyBindingError()
 			}
 		}
 	}

package/src/lifecycle/initErrors.ts

@@ -1,171 +1,125 @@
-import type {
-	CustomBlockInitErrorCode,
-	CustomBlockInitErrorInfo,
-} from "@notionhq/custom-blocks-protocol/messages/init.js"
-
-const UNKNOWN_ERROR_MESSAGE =
-	"Unexpected error while initializing custom block."
+import type { CustomBlockErrorInfo } from "@notionhq/custom-blocks-protocol/errors.js"
 
 /**
- * Returns the error info for a given `init` failure code.
- *
- * `init` handshakes are one-shot: after an `init` error, this host instance will not answer another
- * `connect` message. `isRetryable` means a fresh iframe / `init` attempt could plausibly succeed
- * without changing block code or host configuration.
+ * Initialization handshakes are one-shot: after an error, this host instance will not answer
+ * another `connect` message. `isRetryable` means a fresh host and iframe could plausibly
+ * initialize without changing block code or host configuration.
  */
-export function initErrorForFailureReason(
-	reason: CustomBlockInitErrorCode,
-	data: {
-		minBridgeProtocolVersion?: number
-		currentBridgeProtocolVersion?: number
-	} = {},
-): CustomBlockInitErrorInfo {
-	switch (reason) {
-		case "no_connect":
-			return {
-				code: reason,
-				message: "Sandbox did not send a connect message.",
-				isRetryable: true,
-			}
-		case "invalid_connect_payload":
-			return {
-				code: reason,
-				message: "Sandbox sent an invalid connect message.",
-				// The sandbox must be updated to send a valid connect message.
-				isRetryable: false,
-			}
-		case "manifest_unavailable":
-			return {
-				code: reason,
-				message: "The custom block manifest is unavailable.",
-				isRetryable: true,
-			}
-		case "manifest_invalid":
-			return {
-				code: reason,
-				message: "Sandbox sent an invalid manifest.",
-				// The sandbox must be updated to a valid manifest.
-				isRetryable: false,
-			}
-		case "invalid_protocol_version": {
-			const versionText = data.currentBridgeProtocolVersion
-				? `: ${data.currentBridgeProtocolVersion}`
-				: "."
-			return {
-				code: reason,
-				message: `Sandbox reported an invalid bridge protocol version ${versionText}`,
-				// The sandbox must be updated to a supported protocol version.
-				isRetryable: false,
-			}
-		}
-		case "unsupported_protocol_version": {
-			const currentVersionText = data.currentBridgeProtocolVersion
-				? `${data.currentBridgeProtocolVersion} `
-				: ""
-			const minVersionText = data.minBridgeProtocolVersion
-				? ` Minimum supported version is ${data.minBridgeProtocolVersion}.`
-				: ""
-			return {
-				code: reason,
-				message: `Sandbox bridge protocol version ${currentVersionText}is not supported.${minVersionText}`,
-				// The sandbox must be updated to a supported protocol version.
-				isRetryable: false,
-			}
-		}
-		case "init_timeout":
-			return {
-				code: reason,
-				message: "Host dependencies did not finish loading before the timeout.",
-				isRetryable: true,
-			}
-		case "context_unavailable":
-			return {
-				code: reason,
-				message: "Host page context is unavailable.",
-				isRetryable: true,
-			}
-		case "current_user_unavailable":
-			return {
-				code: reason,
-				message: "Current user is unavailable.",
-				isRetryable: true,
-			}
-		case "initial_state_timeout":
-			return {
-				code: reason,
-				message: "Host did not prepare initial state before the timeout.",
-				isRetryable: true,
-			}
-		case "missing_data_source_binding":
-			return {
-				code: reason,
-				message: "A required data source is not mapped.",
-				// Host configuration must be changed before this block can initialize.
-				isRetryable: false,
-			}
-		case "data_source_unavailable":
-			return {
-				code: reason,
-				message: "A mapped data source is unavailable.",
-				// This error combines some retryable errors (e.g. data source failed to load) with
-				// some non-retryable errors (e.g. data source does not exist or user does not have
-				// access). Fallback to assuming the error is retryable.
-				isRetryable: true,
-			}
-		case "missing_property_binding":
-			return {
-				code: reason,
-				message: "A required data source property is not mapped.",
-				// Host configuration must be changed before this block can initialize.
-				isRetryable: false,
-			}
-		case "invalid_property_binding":
-			return {
-				code: reason,
-				message: "A mapped data source property is missing or incompatible.",
-				// The bound property's schema must be updated or the binding must be updated to
-				// a property with a compatible schema.
-				isRetryable: false,
-			}
-		case "no_init_result":
-			return {
-				code: reason,
-				message: "Sandbox did not acknowledge initialization.",
-				isRetryable: true,
-			}
-		case "invalid_init_result_payload":
-			return {
-				code: reason,
-				message: "Sandbox sent an invalid initialization result.",
-				isRetryable: false,
-			}
-		case "invalid_init_bindings":
-			return {
-				code: reason,
-				message: "Sandbox rejected the host-provided data source bindings.",
-				isRetryable: false,
-			}
-		case "not_in_iframe":
-			return {
-				code: reason,
-				message: "<NotionCustomBlock> only works inside an iframe.",
-				// The block must be embedded in an iframe.
-				isRetryable: false,
-			}
-		case "unknown_error":
-			return {
-				code: reason,
-				message: UNKNOWN_ERROR_MESSAGE,
-				// Treat unknown errors as non-retryable.
-				isRetryable: false,
-			}
-		default:
-			console.warn(`Unexpected custom block init error: ${reason}`)
-			return {
-				code: reason,
-				message: UNKNOWN_ERROR_MESSAGE,
-				// Treat unknown error codes as non-retryable.
-				isRetryable: false,
-			}
+export function noConnectError(): CustomBlockErrorInfo<"no_connect"> {
+	return {
+		code: "no_connect",
+		message: "Sandbox did not send a connect message.",
+		// A fresh iframe may finish loading and send connect before the timeout.
+		isRetryable: true,
+	}
+}
+
+export function invalidConnectPayloadError(): CustomBlockErrorInfo<"invalid_connect_payload"> {
+	return {
+		code: "invalid_connect_payload",
+		message: "Sandbox sent an invalid connect message.",
+		// The sandbox must be updated to send a valid connect message.
+		isRetryable: false,
+	}
+}
+
+export function invalidProtocolVersionError(args: {
+	currentBridgeProtocolVersion: number | undefined
+}): CustomBlockErrorInfo<"invalid_protocol_version"> {
+	const { currentBridgeProtocolVersion } = args
+	const versionText = currentBridgeProtocolVersion
+		? `: ${currentBridgeProtocolVersion}`
+		: "."
+	return {
+		code: "invalid_protocol_version",
+		message: `Sandbox reported an invalid bridge protocol version ${versionText}`,
+		// The sandbox must be updated to a supported protocol version.
+		isRetryable: false,
+	}
+}
+
+export function unsupportedProtocolVersionError(args: {
+	currentBridgeProtocolVersion: number
+	minBridgeProtocolVersion: number
+}): CustomBlockErrorInfo<"unsupported_protocol_version"> {
+	const { currentBridgeProtocolVersion, minBridgeProtocolVersion } = args
+	return {
+		code: "unsupported_protocol_version",
+		message: `Sandbox bridge protocol version ${currentBridgeProtocolVersion} is not supported. Minimum supported version is ${minBridgeProtocolVersion}.`,
+		// The sandbox must be updated to a supported protocol version.
+		isRetryable: false,
+	}
+}
+
+export function contextUnavailableError(): CustomBlockErrorInfo<"context_unavailable"> {
+	return {
+		code: "context_unavailable",
+		message: "Host page context is unavailable.",
+		// Page context may become available before a fresh initialization attempt.
+		isRetryable: true,
+	}
+}
+
+export function initialStateTimeoutError(): CustomBlockErrorInfo<"initial_state_timeout"> {
+	return {
+		code: "initial_state_timeout",
+		message: "Host did not prepare initial state before the timeout.",
+		// A fresh attempt may finish loading host dependencies before the timeout.
+		isRetryable: true,
+	}
+}
+
+export function missingDataSourceBindingError(): CustomBlockErrorInfo<"missing_data_source_binding"> {
+	return {
+		code: "missing_data_source_binding",
+		message: "A required data source is not mapped.",
+		// Host configuration must be changed before this block can initialize.
+		isRetryable: false,
+	}
+}
+
+export function missingPropertyBindingError(): CustomBlockErrorInfo<"missing_property_binding"> {
+	return {
+		code: "missing_property_binding",
+		message: "A required data source property is not mapped.",
+		// Host configuration must be changed before this block can initialize.
+		isRetryable: false,
+	}
+}
+
+export function invalidPropertyBindingError(): CustomBlockErrorInfo<"invalid_property_binding"> {
+	return {
+		code: "invalid_property_binding",
+		message: "A mapped data source property is missing or incompatible.",
+		// The bound property's schema must be updated or the binding must be updated to
+		// a property with a compatible schema.
+		isRetryable: false,
+	}
+}
+
+export function noInitResultError(): CustomBlockErrorInfo<"no_init_result"> {
+	return {
+		code: "no_init_result",
+		message: "Sandbox did not acknowledge initialization.",
+		// A fresh iframe may process init and acknowledge it before the timeout.
+		isRetryable: true,
+	}
+}
+
+export function invalidInitResultPayloadError(): CustomBlockErrorInfo<"invalid_init_result_payload"> {
+	return {
+		code: "invalid_init_result_payload",
+		message: "Sandbox sent an invalid initialization result.",
+		// The sandbox must be updated to send a valid initialization result.
+		isRetryable: false,
+	}
+}
+
+export function unknownInitializationError(): CustomBlockErrorInfo<"unknown_error"> {
+	return {
+		code: "unknown_error",
+		message: "Unexpected error while initializing custom block.",
+		// Without a known transient cause, conservatively treat unknown errors as non-retryable.
+		isRetryable: false,
 	}
 }

package/src/lifecycle/initializationController.ts

@@ -8,7 +8,14 @@ import type { InitResultMessage } from "@notionhq/custom-blocks-protocol/message
 import type { InferInput } from "valibot"
 import type { CustomBlockHostFailure } from "../messages/types.js"
 import { unreachable } from "../utils.js"
-import { initErrorForFailureReason } from "./initErrors.js"
+import {
+	initialStateTimeoutError,
+	invalidProtocolVersionError,
+	noConnectError,
+	noInitResultError,
+	unknownInitializationError,
+	unsupportedProtocolVersionError,
+} from "./initErrors.js"
 import { isValidBridgeProtocolVersion } from "./protocolVersion.js"
 import type {
 	ConnectSuccessMessage,
@@ -141,7 +148,7 @@ export function createInitializationController(
 			if (initStatus !== "preparingInit") {
 				return
 			}
-			const error = initErrorForFailureReason("initial_state_timeout")
+			const error = initialStateTimeoutError()
 			warn({
 				...error,
 				initializationId: connect.initializationId,
@@ -183,7 +190,7 @@ export function createInitializationController(
 					return
 				}
 				initStatus = "error"
-				const error = initErrorForFailureReason("no_init_result")
+				const error = noInitResultError()
 				onConnectionFailure?.(error)
 				warn({
 					...error,
@@ -200,7 +207,7 @@ export function createInitializationController(
 			})
 			sendInitError({
 				initializationId: connect.initializationId,
-				error: initErrorForFailureReason("unknown_error"),
+				error: unknownInitializationError(),
 			})
 		}
 	}
@@ -215,7 +222,7 @@ export function createInitializationController(
 
 		// Verify the bridge protocol version is valid.
 		if (!isValidBridgeProtocolVersion(message.bridgeProtocolVersion)) {
-			const initError = initErrorForFailureReason("invalid_protocol_version", {
+			const initError = invalidProtocolVersionError({
 				currentBridgeProtocolVersion: message.bridgeProtocolVersion,
 			})
 			sendInitError({
@@ -225,13 +232,10 @@ export function createInitializationController(
 			return
 		}
 		if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
-			const initError = initErrorForFailureReason(
-				"unsupported_protocol_version",
-				{
-					currentBridgeProtocolVersion: message.bridgeProtocolVersion,
-					minBridgeProtocolVersion,
-				},
-			)
+			const initError = unsupportedProtocolVersionError({
+				currentBridgeProtocolVersion: message.bridgeProtocolVersion,
+				minBridgeProtocolVersion,
+			})
 			sendInitError({
 				initializationId: message.initializationId,
 				error: initError,
@@ -273,9 +277,11 @@ export function createInitializationController(
 		// when the malformed message includes a numeric version.
 		if (bridgeProtocolVersion !== undefined) {
 			if (!isValidBridgeProtocolVersion(bridgeProtocolVersion)) {
-				error = initErrorForFailureReason("invalid_protocol_version")
+				error = invalidProtocolVersionError({
+					currentBridgeProtocolVersion: undefined,
+				})
 			} else if (bridgeProtocolVersion < minBridgeProtocolVersion) {
-				error = initErrorForFailureReason("unsupported_protocol_version", {
+				error = unsupportedProtocolVersionError({
 					currentBridgeProtocolVersion: bridgeProtocolVersion,
 					minBridgeProtocolVersion,
 				})
@@ -329,7 +335,7 @@ export function createInitializationController(
 				return
 			}
 			initStatus = "error"
-			const error = initErrorForFailureReason("no_connect")
+			const error = noConnectError()
 			warn(error)
 			onConnectionFailure?.(error)
 		}, noConnectTimeoutMs)

package/src/messages/sandboxMessageRouter.ts

@@ -13,7 +13,10 @@ import { sandboxToHostMessageSchema } from "@notionhq/custom-blocks-protocol/mes
 import type { UnsubscribeDataSourceQueryMessage } from "@notionhq/custom-blocks-protocol/messages/unsubscribeDataSourceQuery.js"
 import type { UpdatePageMessage } from "@notionhq/custom-blocks-protocol/messages/updatePage.js"
 import * as v from "valibot"
-import { initErrorForFailureReason } from "../lifecycle/initErrors.js"
+import {
+	invalidConnectPayloadError,
+	invalidInitResultPayloadError,
+} from "../lifecycle/initErrors.js"
 import type { InitializationController } from "../lifecycle/initializationController.js"
 import type { InitStatus } from "../lifecycle/types.js"
 import { unreachable } from "../utils.js"
@@ -95,7 +98,7 @@ export function createSandboxMessageRouter(
 				initializationId: parsedIdentity.success
 					? parsedIdentity.output.initializationId
 					: undefined,
-				error: initErrorForFailureReason("invalid_connect_payload"),
+				error: invalidConnectPayloadError(),
 				bridgeProtocolVersion: parsedVersion.success
 					? parsedVersion.output.bridgeProtocolVersion
 					: undefined,
@@ -112,7 +115,7 @@ export function createSandboxMessageRouter(
 				initializationId: parsedIdentity.success
 					? parsedIdentity.output.initializationId
 					: undefined,
-				error: initErrorForFailureReason("invalid_init_result_payload"),
+				error: invalidInitResultPayloadError(),
 			})
 		}