@notionhq/custom-blocks-host 0.0.1 → 0.1.0

package/README.md

@@ -78,6 +78,9 @@ const host = createCustomBlockHost({
   onIgnoredConnect: () => {
     remountHostAndIframe();
   },
+  onInitializationFailure: (error) => {
+    showInitializationError(error);
+  },
   onLog: (direction, payload) => {
     console.log(direction, payload);
   },
@@ -90,6 +93,9 @@ replaced, or the document's first `connect` came after the no-connect timeout.
 Recreate the host and the iframe together so the document runs a fresh
 handshake against current host state.
 
+`onInitializationFailure` receives structured errors from failed `init`
+messages, failed `initResult` messages, and initialization timeouts.
+
 `queryDataSource` is required. Other request handlers are optional. Every
 request handler may return its result synchronously or as a promise. Results
 use a `status` discriminator: successful results carry their response payload,

package/dist/createCustomBlockHost.d.ts

@@ -8,7 +8,7 @@ import type { NotionParent } from "./protocol/parent.js";
 import type { NotionTheme } from "./protocol/theme.js";
 import type { NotionUser } from "./protocol/users/user.js";
 import type { ConnectSuccessMessage, CustomBlockHostDataSourcesPayload, CustomBlockHostInitialState } from "./lifecycle/types.js";
-import type { CustomBlockHostHandlers, CustomBlockHostLogDirection } from "./messages/types.js";
+import type { CustomBlockHostHandlers, CustomBlockHostInitializationFailure, CustomBlockHostLogDirection } from "./messages/types.js";
 export type CustomBlockHostOptions = {
     iframe: HTMLIFrameElement;
     sandboxOrigin: string;
@@ -19,6 +19,7 @@ export type CustomBlockHostOptions = {
     handlers: CustomBlockHostHandlers;
     onConnect?: (message: ConnectSuccessMessage) => void;
     onInitResult?: (message: InitResultMessage) => void;
+    onInitializationFailure?: (error: CustomBlockHostInitializationFailure) => void;
     /**
      * A `connect` arrived after this host's initialization settled — the
      * document was replaced, or its first `connect` came after the host

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;AAEjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAa1F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AAEtG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAahG,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,qBAAqB,EACrB,iCAAiC,EACjC,2BAA2B,EAC3B,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EACX,uBAAuB,EACvB,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAU5B,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACpD,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACnD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IACpD,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;AAMD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CA+cvB"}
+{"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;AAEjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAa1F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AAEtG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAahG,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,qBAAqB,EACrB,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,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE,2BAA2B,CAAA;IACzC,QAAQ,EAAE,uBAAuB,CAAA;IACjC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACpD,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACnD,uBAAuB,CAAC,EAAE,CACzB,KAAK,EAAE,oCAAoC,KACvC,IAAI,CAAA;IACT;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IACpD,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;AAMD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CAidvB"}

package/dist/createCustomBlockHost.js

@@ -13,7 +13,7 @@ const initializationIdentitySchema = v.object({
     initializationId: v.string(),
 });
 export function createCustomBlockHost(options) {
-    const { iframe, initialState, handlers, onConnect, onInitResult, onIgnoredConnect, onLog, sandboxOrigin, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, noInitResultTimeoutMs, } = options;
+    const { iframe, initialState, handlers, onConnect, onInitResult, onInitializationFailure, onIgnoredConnect, onLog, sandboxOrigin, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, noInitResultTimeoutMs, } = options;
     const minBridgeProtocolVersion = Math.max(configuredMinBridgeProtocolVersion ?? CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION, CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION);
     let theme = initialState.theme;
     let contrastMode = initialState.contrastMode ?? DEFAULT_CONTRAST_MODE;
@@ -212,6 +212,7 @@ export function createCustomBlockHost(options) {
         onConnect,
         onInitResult,
         onIgnoredConnect,
+        onInitializationFailure,
     });
     function onInvalidSandboxMessage(data, issues) {
         emit("warn", {
@@ -224,10 +225,13 @@ export function createCustomBlockHost(options) {
         const initializationId = parsedIdentity.success
             ? parsedIdentity.output.initializationId
             : undefined;
-        if (response.incomingType === "connect" &&
-            initializationId !== undefined &&
-            initializationController.handleInvalidConnect(initializationId)) {
-            return;
+        if (response.incomingType === "connect") {
+            if (initializationController.handleInvalidConnect(initializationId)) {
+                if (initializationId === undefined && response.nack !== undefined) {
+                    post(response.nack);
+                }
+                return;
+            }
         }
         if (response.incomingType === "initResult" &&
             initializationController.handleInvalidInitResult()) {
@@ -259,8 +263,7 @@ export function createCustomBlockHost(options) {
         if (message.type !== "connect" &&
             message.type !== "initResult" &&
             initializationController.status !== "success") {
-            // The SDK reports resize as soon as it renders, before the
-            // handshake completes, so an early resize is routine.
+            // Ignore all non-handshake messages until initialization succeeds.
             if (message.type !== "resize") {
                 emit("warn", {
                     message: `Ignored ${message.type} before initialization completed`,

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { type AutoBindableProperty, getAutoBoundPropertyIdsByKey, } from "./autoBindProperties.js";
 export { type CustomBlockHostHandle, type CustomBlockHostOptions, createCustomBlockHost, } from "./createCustomBlockHost.js";
 export type { ConnectSuccessMessage, CustomBlockHostDataSourcesPayload, CustomBlockHostInitialDataSources, CustomBlockHostInitialState, } from "./lifecycle/types.js";
-export type { CustomBlockHostCreatePageResult, CustomBlockHostGetPageResult, CustomBlockHostGetUserResult, CustomBlockHostHandlers, CustomBlockHostListUsersResult, CustomBlockHostLogDirection, CustomBlockHostUpdatePageResult, } from "./messages/types.js";
+export type { CustomBlockHostCreatePageResult, CustomBlockHostGetPageResult, CustomBlockHostGetUserResult, CustomBlockHostHandlers, CustomBlockHostInitializationFailure, CustomBlockHostListUsersResult, CustomBlockHostLogDirection, CustomBlockHostUpdatePageResult, } from "./messages/types.js";
 export type { CustomBlockHostQueryDataSourceResult } from "./queries/types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,oBAAoB,EACzB,4BAA4B,GAC5B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,qBAAqB,GACrB,MAAM,4BAA4B,CAAA;AACnC,YAAY,EACX,qBAAqB,EACrB,iCAAiC,EACjC,iCAAiC,EACjC,2BAA2B,GAC3B,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACX,+BAA+B,EAC/B,4BAA4B,EAC5B,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,2BAA2B,EAC3B,+BAA+B,GAC/B,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,oCAAoC,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,oBAAoB,EACzB,4BAA4B,GAC5B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,qBAAqB,GACrB,MAAM,4BAA4B,CAAA;AACnC,YAAY,EACX,qBAAqB,EACrB,iCAAiC,EACjC,iCAAiC,EACjC,2BAA2B,GAC3B,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACX,+BAA+B,EAC/B,4BAA4B,EAC5B,4BAA4B,EAC5B,uBAAuB,EACvB,oCAAoC,EACpC,8BAA8B,EAC9B,2BAA2B,EAC3B,+BAA+B,GAC/B,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,oCAAoC,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/lifecycle/initializationController.d.ts

@@ -9,6 +9,7 @@ import type { CustomBlockPage } from "../protocol/pages/page.js";
 import type { NotionParent } from "../protocol/parent.js";
 import type { NotionTheme } from "../protocol/theme.js";
 import type { NotionUser } from "../protocol/users/user.js";
+import type { CustomBlockHostInitializationFailure } from "../messages/types.js";
 import type { ConnectSuccessMessage, CustomBlockHostDataSourcesPayload, InitStatus } from "./types.js";
 type InitializationState = {
     theme: NotionTheme;
@@ -38,13 +39,14 @@ export type InitializationControllerOptions = {
     onConnect?: (message: ConnectSuccessMessage) => void;
     onInitResult?: (message: InitResultMessage) => void;
     onIgnoredConnect?: (message: ConnectMessage) => void;
+    onInitializationFailure?: (error: CustomBlockHostInitializationFailure) => void;
 };
 export type InitializationController = {
     readonly status: InitStatus;
     readonly hasConnectedSandbox: boolean;
     handleConnect: (message: ConnectMessage) => void;
     handleInitResult: (message: InitResultMessage) => void;
-    handleInvalidConnect: (initializationId: string) => boolean;
+    handleInvalidConnect: (initializationId?: string) => boolean;
     handleInvalidInitResult: () => boolean;
     onIframeLoad: () => void;
     stop: () => void;

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

@@ -1 +1 @@
-{"version":3,"file":"initializationController.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initializationController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4DAA4D,CAAA;AACtG,OAAO,KAAK,EACX,wBAAwB,EAExB,MAAM,mDAAmD,CAAA;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,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,qBAAqB,EACrB,iCAAiC,EACjC,UAAU,EACV,MAAM,YAAY,CAAA;AAKnB,KAAK,mBAAmB,GAAG;IAC1B,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,EAAE,kBAAkB,CAAA;IAChC,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,eAAe,CAAA;IACrB,WAAW,EAAE,UAAU,CAAA;CACvB,CAAA;AAED,KAAK,yBAAyB,GAC3B;IACA,MAAM,EAAE,SAAS,CAAA;IACjB,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,WAAW,EAAE,iCAAiC,CAAA;CAC7C,GACD;IACA,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,wBAAwB,CAAA;CAC9B,CAAA;AAEJ,MAAM,MAAM,+BAA+B,GAAG;IAC7C,OAAO,EAAE,aAAa,CAAA;IACtB,QAAQ,EAAE,MAAM,mBAAmB,CAAA;IACnC,WAAW,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,yBAAyB,CAAA;IAC1E,IAAI,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAC7C,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,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACpD,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACnD,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;CACpD,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,gBAAgB,EAAE,MAAM,KAAK,OAAO,CAAA;IAC3D,uBAAuB,EAAE,MAAM,OAAO,CAAA;IACtC,YAAY,EAAE,MAAM,IAAI,CAAA;IACxB,IAAI,EAAE,MAAM,IAAI,CAAA;CAChB,CAAA;AAED,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,+BAA+B,GACtC,wBAAwB,CAyN1B"}
+{"version":3,"file":"initializationController.d.ts","sourceRoot":"","sources":["../../src/lifecycle/initializationController.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/initializationController.js

@@ -3,7 +3,7 @@ import { isValidBridgeProtocolVersion } from "./protocolVersion.js";
 const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5000;
 const DEFAULT_NO_INIT_RESULT_TIMEOUT_MS = 5000;
 export function createInitializationController(options) {
-    const { blockId, getState, prepareInit, post, warn, flushPendingHostStateChanges, minBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, onConnect, onInitResult, onIgnoredConnect, } = options;
+    const { blockId, getState, prepareInit, post, warn, flushPendingHostStateChanges, minBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, onConnect, onInitResult, onIgnoredConnect, onInitializationFailure, } = options;
     let initStatus = "waitingForConnect";
     let noConnectTimeoutId;
     let noInitResultTimeoutId;
@@ -34,6 +34,7 @@ export function createInitializationController(options) {
             status: "error",
             error,
         });
+        onInitializationFailure?.(error);
     }
     function sendInit(connect) {
         if (initStatus !== "waitingForConnect") {
@@ -68,10 +69,12 @@ export function createInitializationController(options) {
                 return;
             }
             initStatus = "error";
+            const error = initErrorForFailureReason("no_init_result");
             warn({
                 message: "Sandbox did not send initResult",
                 initializationId: connect.initializationId,
             });
+            onInitializationFailure?.(error);
         }, noInitResultTimeoutMs);
         return true;
     }
@@ -118,7 +121,16 @@ export function createInitializationController(options) {
         if (initStatus !== "waitingForConnect") {
             return false;
         }
-        sendInitError(initializationId, initErrorForFailureReason("invalid_connect_payload"));
+        const error = initErrorForFailureReason("invalid_connect_payload");
+        if (initializationId === undefined) {
+            initStatus = "error";
+            clearNoConnectTimeout();
+            warn(error);
+            onInitializationFailure?.(error);
+        }
+        else {
+            sendInitError(initializationId, error);
+        }
         return true;
     }
     function handleInvalidInitResult() {
@@ -127,7 +139,9 @@ export function createInitializationController(options) {
         }
         clearNoInitResultTimeout();
         initStatus = "error";
-        warn(initErrorForFailureReason("invalid_init_result_payload"));
+        const error = initErrorForFailureReason("invalid_init_result_payload");
+        warn(error);
+        onInitializationFailure?.(error);
         return true;
     }
     function onIframeLoad() {
@@ -142,7 +156,9 @@ export function createInitializationController(options) {
                 return;
             }
             initStatus = "error";
-            warn(initErrorForFailureReason("no_connect"));
+            const error = initErrorForFailureReason("no_connect");
+            warn(error);
+            onInitializationFailure?.(error);
         }, noConnectTimeoutMs);
     }
     function handleInitResult(message) {
@@ -155,10 +171,14 @@ export function createInitializationController(options) {
             return;
         }
         clearNoInitResultTimeout();
-        initStatus = message.status === "success" ? "success" : "error";
-        if (initStatus === "success") {
+        if (message.status === "success") {
+            initStatus = "success";
             flushPendingHostStateChanges();
         }
+        else {
+            initStatus = "error";
+            onInitializationFailure?.(message.error);
+        }
         onInitResult?.(message);
     }
     function stop() {

package/dist/messages/types.d.ts

@@ -3,6 +3,8 @@ import type { CreatePageMessage } from "../protocol/messages/createPage.js";
 import type { CreatePageResultMessage, CustomBlockCreatePageErrorInfo } from "../protocol/messages/createPageResult.js";
 import type { CustomBlockGetPageErrorInfo, GetPageMessage, GetPageResultMessage } from "../protocol/messages/getPage.js";
 import type { CustomBlockGetUserErrorInfo, GetUserMessage, GetUserResultMessage } from "../protocol/messages/getUser.js";
+import type { CustomBlockInitErrorInfo } from "../protocol/messages/init.js";
+import type { CustomBlockInitResultErrorInfo } from "../protocol/messages/initResult.js";
 import type { CustomBlockListUsersErrorInfo, ListUsersMessage, ListUsersResultMessage } from "../protocol/messages/listUsers.js";
 import type { QueryDataSourceMessage } from "../protocol/messages/queryDataSource.js";
 import type { ResizeMessage } from "../protocol/messages/resize.js";
@@ -24,6 +26,7 @@ export type CustomBlockHostHandlers = {
     updatePage?: (message: UpdatePageMessage) => MaybePromise<CustomBlockHostUpdatePageResult>;
     resize?: (message: ResizeMessage) => void;
 };
+export type CustomBlockHostInitializationFailure = CustomBlockInitErrorInfo | CustomBlockInitResultErrorInfo;
 export type CustomBlockHostLogDirection = "in" | "out" | "warn";
 export {};
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/messages/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAA;AAC9F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,uBAAuB,EACvB,8BAA8B,EAC9B,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,6BAA6B,EAC7B,gBAAgB,EAChB,sBAAsB,EACtB,MAAM,wDAAwD,CAAA;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,8BAA8B,EAC9B,uBAAuB,EACvB,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,qBAAqB,CAAA;AAE/E,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAErC,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,CACjE,uBAAuB,EACvB,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC9D,oBAAoB,EACpB,2BAA2B,CAC3B,CAAA;AAED,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,CACjE,uBAAuB,EACvB,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC9D,oBAAoB,EACpB,2BAA2B,CAC3B,CAAA;AAED,MAAM,MAAM,8BAA8B,GAAG,oBAAoB,CAChE,sBAAsB,EACtB,6BAA6B,CAC7B,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG;IACrC,eAAe,EAAE,CAChB,OAAO,EAAE,sBAAsB,KAC3B,YAAY,CAAC,oCAAoC,CAAC,CAAA;IACvD,UAAU,CAAC,EAAE,CACZ,OAAO,EAAE,iBAAiB,KACtB,YAAY,CAAC,+BAA+B,CAAC,CAAA;IAClD,OAAO,CAAC,EAAE,CACT,OAAO,EAAE,cAAc,KACnB,YAAY,CAAC,4BAA4B,CAAC,CAAA;IAC/C,OAAO,CAAC,EAAE,CACT,OAAO,EAAE,cAAc,KACnB,YAAY,CAAC,4BAA4B,CAAC,CAAA;IAC/C,SAAS,CAAC,EAAE,CACX,OAAO,EAAE,gBAAgB,KACrB,YAAY,CAAC,8BAA8B,CAAC,CAAA;IACjD,UAAU,CAAC,EAAE,CACZ,OAAO,EAAE,iBAAiB,KACtB,YAAY,CAAC,+BAA+B,CAAC,CAAA;IAClD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CACzC,CAAA;AAED,MAAM,MAAM,2BAA2B,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/messages/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAA;AAC9F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,uBAAuB,EACvB,8BAA8B,EAC9B,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mDAAmD,CAAA;AACjG,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,yDAAyD,CAAA;AAC7G,OAAO,KAAK,EACX,6BAA6B,EAC7B,gBAAgB,EAChB,sBAAsB,EACtB,MAAM,wDAAwD,CAAA;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,8BAA8B,EAC9B,uBAAuB,EACvB,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,qBAAqB,CAAA;AAE/E,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAErC,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,CACjE,uBAAuB,EACvB,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC9D,oBAAoB,EACpB,2BAA2B,CAC3B,CAAA;AAED,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,CACjE,uBAAuB,EACvB,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC9D,oBAAoB,EACpB,2BAA2B,CAC3B,CAAA;AAED,MAAM,MAAM,8BAA8B,GAAG,oBAAoB,CAChE,sBAAsB,EACtB,6BAA6B,CAC7B,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG;IACrC,eAAe,EAAE,CAChB,OAAO,EAAE,sBAAsB,KAC3B,YAAY,CAAC,oCAAoC,CAAC,CAAA;IACvD,UAAU,CAAC,EAAE,CACZ,OAAO,EAAE,iBAAiB,KACtB,YAAY,CAAC,+BAA+B,CAAC,CAAA;IAClD,OAAO,CAAC,EAAE,CACT,OAAO,EAAE,cAAc,KACnB,YAAY,CAAC,4BAA4B,CAAC,CAAA;IAC/C,OAAO,CAAC,EAAE,CACT,OAAO,EAAE,cAAc,KACnB,YAAY,CAAC,4BAA4B,CAAC,CAAA;IAC/C,SAAS,CAAC,EAAE,CACX,OAAO,EAAE,gBAAgB,KACrB,YAAY,CAAC,8BAA8B,CAAC,CAAA;IACjD,UAAU,CAAC,EAAE,CACZ,OAAO,EAAE,iBAAiB,KACtB,YAAY,CAAC,+BAA+B,CAAC,CAAA;IAClD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CACzC,CAAA;AAED,MAAM,MAAM,oCAAoC,GAC7C,wBAAwB,GACxB,8BAA8B,CAAA;AAEjC,MAAM,MAAM,2BAA2B,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAA"}

package/package.json

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

package/src/createCustomBlockHost.ts

@@ -48,6 +48,7 @@ import type {
 import { getInvalidSandboxMessageResponse } from "./messages/invalidSandboxMessage.js"
 import type {
 	CustomBlockHostHandlers,
+	CustomBlockHostInitializationFailure,
 	CustomBlockHostLogDirection,
 } from "./messages/types.js"
 import {
@@ -69,6 +70,9 @@ export type CustomBlockHostOptions = {
 	handlers: CustomBlockHostHandlers
 	onConnect?: (message: ConnectSuccessMessage) => void
 	onInitResult?: (message: InitResultMessage) => void
+	onInitializationFailure?: (
+		error: CustomBlockHostInitializationFailure,
+	) => void
 	/**
 	 * A `connect` arrived after this host's initialization settled — the
 	 * document was replaced, or its first `connect` came after the host
@@ -105,6 +109,7 @@ export function createCustomBlockHost(
 		handlers,
 		onConnect,
 		onInitResult,
+		onInitializationFailure,
 		onIgnoredConnect,
 		onLog,
 		sandboxOrigin,
@@ -345,6 +350,7 @@ export function createCustomBlockHost(
 		onConnect,
 		onInitResult,
 		onIgnoredConnect,
+		onInitializationFailure,
 	})
 
 	function onInvalidSandboxMessage(
@@ -362,12 +368,13 @@ export function createCustomBlockHost(
 		const initializationId = parsedIdentity.success
 			? parsedIdentity.output.initializationId
 			: undefined
-		if (
-			response.incomingType === "connect" &&
-			initializationId !== undefined &&
-			initializationController.handleInvalidConnect(initializationId)
-		) {
-			return
+		if (response.incomingType === "connect") {
+			if (initializationController.handleInvalidConnect(initializationId)) {
+				if (initializationId === undefined && response.nack !== undefined) {
+					post(response.nack)
+				}
+				return
+			}
 		}
 		if (
 			response.incomingType === "initResult" &&
@@ -408,8 +415,7 @@ export function createCustomBlockHost(
 			message.type !== "initResult" &&
 			initializationController.status !== "success"
 		) {
-			// The SDK reports resize as soon as it renders, before the
-			// handshake completes, so an early resize is routine.
+			// Ignore all non-handshake messages until initialization succeeds.
 			if (message.type !== "resize") {
 				emit("warn", {
 					message: `Ignored ${message.type} before initialization completed`,

package/src/index.ts

@@ -18,6 +18,7 @@ export type {
 	CustomBlockHostGetPageResult,
 	CustomBlockHostGetUserResult,
 	CustomBlockHostHandlers,
+	CustomBlockHostInitializationFailure,
 	CustomBlockHostListUsersResult,
 	CustomBlockHostLogDirection,
 	CustomBlockHostUpdatePageResult,

package/src/lifecycle/initializationController.ts

@@ -12,6 +12,7 @@ import type { CustomBlockPage } from "@notionhq/custom-blocks-protocol/pages/pag
 import type { NotionParent } from "@notionhq/custom-blocks-protocol/parent.js"
 import type { NotionTheme } from "@notionhq/custom-blocks-protocol/theme.js"
 import type { NotionUser } from "@notionhq/custom-blocks-protocol/users/user.js"
+import type { CustomBlockHostInitializationFailure } from "../messages/types.js"
 import { initErrorForFailureReason } from "./initErrors.js"
 import { isValidBridgeProtocolVersion } from "./protocolVersion.js"
 import type {
@@ -55,6 +56,9 @@ export type InitializationControllerOptions = {
 	onConnect?: (message: ConnectSuccessMessage) => void
 	onInitResult?: (message: InitResultMessage) => void
 	onIgnoredConnect?: (message: ConnectMessage) => void
+	onInitializationFailure?: (
+		error: CustomBlockHostInitializationFailure,
+	) => void
 }
 
 export type InitializationController = {
@@ -62,7 +66,7 @@ export type InitializationController = {
 	readonly hasConnectedSandbox: boolean
 	handleConnect: (message: ConnectMessage) => void
 	handleInitResult: (message: InitResultMessage) => void
-	handleInvalidConnect: (initializationId: string) => boolean
+	handleInvalidConnect: (initializationId?: string) => boolean
 	handleInvalidInitResult: () => boolean
 	onIframeLoad: () => void
 	stop: () => void
@@ -84,6 +88,7 @@ export function createInitializationController(
 		onConnect,
 		onInitResult,
 		onIgnoredConnect,
+		onInitializationFailure,
 	} = options
 
 	let initStatus: InitStatus = "waitingForConnect"
@@ -122,6 +127,7 @@ export function createInitializationController(
 			status: "error",
 			error,
 		})
+		onInitializationFailure?.(error)
 	}
 
 	function sendInit(connect: ConnectSuccessMessage): boolean {
@@ -157,10 +163,12 @@ export function createInitializationController(
 				return
 			}
 			initStatus = "error"
+			const error = initErrorForFailureReason("no_init_result")
 			warn({
 				message: "Sandbox did not send initResult",
 				initializationId: connect.initializationId,
 			})
+			onInitializationFailure?.(error)
 		}, noInitResultTimeoutMs)
 		return true
 	}
@@ -212,14 +220,19 @@ export function createInitializationController(
 		}
 	}
 
-	function handleInvalidConnect(initializationId: string): boolean {
+	function handleInvalidConnect(initializationId?: string): boolean {
 		if (initStatus !== "waitingForConnect") {
 			return false
 		}
-		sendInitError(
-			initializationId,
-			initErrorForFailureReason("invalid_connect_payload"),
-		)
+		const error = initErrorForFailureReason("invalid_connect_payload")
+		if (initializationId === undefined) {
+			initStatus = "error"
+			clearNoConnectTimeout()
+			warn(error)
+			onInitializationFailure?.(error)
+		} else {
+			sendInitError(initializationId, error)
+		}
 		return true
 	}
 
@@ -229,7 +242,9 @@ export function createInitializationController(
 		}
 		clearNoInitResultTimeout()
 		initStatus = "error"
-		warn(initErrorForFailureReason("invalid_init_result_payload"))
+		const error = initErrorForFailureReason("invalid_init_result_payload")
+		warn(error)
+		onInitializationFailure?.(error)
 		return true
 	}
 
@@ -245,7 +260,9 @@ export function createInitializationController(
 				return
 			}
 			initStatus = "error"
-			warn(initErrorForFailureReason("no_connect"))
+			const error = initErrorForFailureReason("no_connect")
+			warn(error)
+			onInitializationFailure?.(error)
 		}, noConnectTimeoutMs)
 	}
 
@@ -261,9 +278,12 @@ export function createInitializationController(
 			return
 		}
 		clearNoInitResultTimeout()
-		initStatus = message.status === "success" ? "success" : "error"
-		if (initStatus === "success") {
+		if (message.status === "success") {
+			initStatus = "success"
 			flushPendingHostStateChanges()
+		} else {
+			initStatus = "error"
+			onInitializationFailure?.(message.error)
 		}
 		onInitResult?.(message)
 	}

package/src/messages/types.ts

@@ -14,6 +14,8 @@ import type {
 	GetUserMessage,
 	GetUserResultMessage,
 } from "@notionhq/custom-blocks-protocol/messages/getUser.js"
+import type { CustomBlockInitErrorInfo } from "@notionhq/custom-blocks-protocol/messages/init.js"
+import type { CustomBlockInitResultErrorInfo } from "@notionhq/custom-blocks-protocol/messages/initResult.js"
 import type {
 	CustomBlockListUsersErrorInfo,
 	ListUsersMessage,
@@ -77,4 +79,8 @@ export type CustomBlockHostHandlers = {
 	resize?: (message: ResizeMessage) => void
 }
 
+export type CustomBlockHostInitializationFailure =
+	| CustomBlockInitErrorInfo
+	| CustomBlockInitResultErrorInfo
+
 export type CustomBlockHostLogDirection = "in" | "out" | "warn"