@notionhq/custom-blocks-host 0.2.6 → 0.2.7

package/README.md

@@ -81,9 +81,10 @@ const host = createCustomBlockHost({
   onInitialized: state => {
     console.log("Initialized manifest", state.manifest)
   },
-  onFailure: error => {
+  onConnectionFailure: error => {
     showHostError(error)
   },
+  onQueryUnsubscribed: undefined,
   onLog: (direction, payload) => {
     console.log(direction, payload)
   },
@@ -101,8 +102,8 @@ Each host handles one initialization handshake with one sandbox iframe:
   malformed ones. A connection after an initialization timeout does not restart it.
 - The first observed iframe `load` is allowed, including when initialization completes before it.
 - A second observed `load` stops the host and reports retryable `iframe_reloaded` through
-  `onFailure`. A reload or navigation can replace the sandbox document, so the host ends the
-  connection instead of continuing to serve the replacement.
+  `onConnectionFailure`. A reload or navigation can replace the sandbox document, so the host ends
+  the connection instead of continuing to serve the replacement.
 - Stopping removes message and load listeners, clears initialization timers, ends query
   subscriptions, and prevents further outbound messages, including pending responses.
 - To retry or apply a deployment or configuration change, the embedder creates a new host and
@@ -142,8 +143,12 @@ iframe reload.
 
 - `onInitialized` reports success after the sandbox accepts initialization. It provides the selected
   `manifest` and the sandbox's optional `initialHeight`.
-- `onFailure` reports a handshake failure, timeout, unavailable page context, or iframe reload. It
-  can run after initialization succeeds.
+- `onConnectionFailure` reports a handshake failure, timeout, unavailable page context, or iframe
+  reload. It can run after initialization succeeds.
+
+- `onQueryUnsubscribed` reports when a query subscription ends. Use it to release per-query
+  resources, such as listeners or timers. The host removes the subscription itself. A query failure
+  can end one subscription while the connection remains active.
 
 `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
@@ -256,6 +261,15 @@ removes a subscription when it receives `unsubscribeDataSourceQuery`. Repeated u
 are safe. The runtime also ignores results from a query that was unsubscribed while its handler was
 running.
 
+A non-retryable query error ends the subscription and discards any queued refresh. This includes
+validation errors before the query handler runs. Retryable errors retain the subscription.
+
+Use `onQueryUnsubscribed(subscriptionId)` to release adapter resources such as collection listeners.
+The callback runs when a subscription ends through an explicit unsubscribe, replacement, terminal
+error, or host stop. Repeated removal of the same subscription does not repeat the callback. A late
+result from a replaced query cannot remove its replacement. The sandbox still receives the terminal
+error result.
+
 Call `stop()` when the iframe is removed. It detaches listeners, clears timeouts, and discards
 active query subscriptions.
 

package/dist/createCustomBlockHost.d.ts

@@ -33,7 +33,9 @@ export type CustomBlockHostOptions = {
      * before this callback runs.
      * This callback can run after initialization succeeds.
      */
-    onFailure?: (error: CustomBlockHostFailure) => void;
+    onConnectionFailure: ((error: CustomBlockHostFailure) => void) | undefined;
+    /** Releases adapter resources when a query ends, including replacement and terminal errors. */
+    onQueryUnsubscribed: ((subscriptionId: string) => void) | undefined;
     onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void;
     getInitialState: CustomBlockHostGetInitialState;
     initialStateTimeoutMs?: number;

package/dist/createCustomBlockHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../src/createCustomBlockHost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8CAA8C,CAAA;AAI5F,OAAO,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAA;AAClF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AAiBvF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAA;AAC3F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4CAA4C,CAAA;AAEpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAA;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAA;AACtF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAKzC,OAAO,KAAK,EACX,iCAAiC,EACjC,8BAA8B,EAI9B,MAAM,sBAAsB,CAAA;AAG7B,OAAO,KAAK,EACX,sBAAsB,EACtB,uBAAuB,EACvB,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAe5B,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,EAAE,uBAAuB,CAAA;IACjC,oHAAoH;IACpH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAA;IACpD,gGAAgG;IAChG,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACvB,QAAQ,EAAE,mBAAmB,CAAA;QAC7B,aAAa,CAAC,EAAE,MAAM,CAAA;KACtB,KAAK,IAAI,CAAA;IACV;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAA;IACnD,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAC1E,eAAe,EAAE,8BAA8B,CAAA;IAC/C,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,KAAK,IAAI,CAAA;IAC/D,eAAe,EAAE,CAChB,YAAY,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,KACrD,IAAI,CAAA;IACT,SAAS,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,KAAK,IAAI,CAAA;IAClE,OAAO,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC,KAAK,IAAI,CAAA;IACjE,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,KAAK,IAAI,CAAA;IAC1E,YAAY,EAAE,CAAC,IAAI,EAAE;QACpB,YAAY,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAA;KACzD,KAAK,IAAI,CAAA;CACV,CAAA;AAQD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CAuYvB"}
+{"version":3,"file":"createCustomBlockHost.d.ts","sourceRoot":"","sources":["../src/createCustomBlockHost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8CAA8C,CAAA;AAI5F,OAAO,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAA;AAClF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AAiBvF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAA;AAC3F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4CAA4C,CAAA;AAEpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAA;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAA;AACtF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAKzC,OAAO,KAAK,EACX,iCAAiC,EACjC,8BAA8B,EAI9B,MAAM,sBAAsB,CAAA;AAG7B,OAAO,KAAK,EACX,sBAAsB,EACtB,uBAAuB,EACvB,2BAA2B,EAC3B,MAAM,qBAAqB,CAAA;AAe5B,MAAM,MAAM,sBAAsB,GAAG;IACpC,MAAM,EAAE,iBAAiB,CAAA;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,EAAE,uBAAuB,CAAA;IACjC,oHAAoH;IACpH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAA;IACpD,gGAAgG;IAChG,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE;QACvB,QAAQ,EAAE,mBAAmB,CAAA;QAC7B,aAAa,CAAC,EAAE,MAAM,CAAA;KACtB,KAAK,IAAI,CAAA;IACV;;;;;OAKG;IACH,mBAAmB,EAAE,CAAC,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;IAC1E,+FAA+F;IAC/F,mBAAmB,EAAE,CAAC,CAAC,cAAc,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;IACnE,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,2BAA2B,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAC1E,eAAe,EAAE,8BAA8B,CAAA;IAC/C,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,KAAK,IAAI,CAAA;IAC/D,eAAe,EAAE,CAChB,YAAY,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,KACrD,IAAI,CAAA;IACT,SAAS,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,KAAK,IAAI,CAAA;IAClE,OAAO,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC,KAAK,IAAI,CAAA;IACjE,cAAc,EAAE,CAAC,WAAW,EAAE,iCAAiC,KAAK,IAAI,CAAA;IACxE,cAAc,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,KAAK,IAAI,CAAA;IAC1E,YAAY,EAAE,CAAC,IAAI,EAAE;QACpB,YAAY,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAA;KACzD,KAAK,IAAI,CAAA;CACV,CAAA;AAQD,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,sBAAsB,GAC7B,qBAAqB,CA8YvB"}

package/dist/createCustomBlockHost.js

@@ -19,7 +19,7 @@ import { unreachable } from "./utils.js";
 // Earlier SDKs cannot represent this context, so the host reports context_unavailable.
 const BRIDGE_PROTOCOL_VERSION_INTRODUCING_UNAVAILABLE_PAGE = 5;
 export function createCustomBlockHost(options) {
-    const { iframe, getInitialState, handlers, onManifest, onInitialized, onFailure, onLog, sandboxOrigin, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, initialStateTimeoutMs, noInitResultTimeoutMs, } = options;
+    const { iframe, getInitialState, handlers, onManifest, onInitialized, onConnectionFailure, onLog, onQueryUnsubscribed, sandboxOrigin, minBridgeProtocolVersion: configuredMinBridgeProtocolVersion, noConnectTimeoutMs, initialStateTimeoutMs, noInitResultTimeoutMs, } = options;
     // Callers can retire older SDKs, but cannot restore support for protocols
     // the runtime no longer implements. Omission uses the runtime minimum.
     const minBridgeProtocolVersion = Math.max(configuredMinBridgeProtocolVersion ??
@@ -29,7 +29,9 @@ export function createCustomBlockHost(options) {
     let manifest;
     let activeDataSources;
     let sandboxBridgeProtocolVersion = LATEST_BRIDGE_PROTOCOL_VERSION;
-    const querySubscriptions = new QuerySubscriptions();
+    const querySubscriptions = new QuerySubscriptions(subscriptionId => {
+        onQueryUnsubscribed?.(subscriptionId);
+    });
     function emit(direction, payload) {
         onLog?.(direction, payload);
     }
@@ -114,6 +116,7 @@ export function createCustomBlockHost(options) {
             const queryError = getQueryValidationError(message, collectionSchema);
             if (queryError !== undefined) {
                 if (querySubscriptions.isCurrent(message.subscriptionId, token)) {
+                    querySubscriptions.unsubscribe(message.subscriptionId);
                     postQueryDataSourceResult({
                         subscriptionId: message.subscriptionId,
                         response: { status: "error", error: queryError },
@@ -125,6 +128,9 @@ export function createCustomBlockHost(options) {
             if (!querySubscriptions.isCurrent(message.subscriptionId, token)) {
                 return;
             }
+            if (response.status === "error" && !response.error.isRetryable) {
+                querySubscriptions.unsubscribe(message.subscriptionId);
+            }
             postQueryDataSourceResult({
                 subscriptionId: message.subscriptionId,
                 response,
@@ -203,7 +209,7 @@ export function createCustomBlockHost(options) {
                 onInitialized?.({ manifest, initialHeight: message.initialHeight });
             }
         },
-        onFailure,
+        onConnectionFailure,
     });
     function prepareInitialState(result) {
         if (result.status === "error") {
@@ -270,7 +276,7 @@ export function createCustomBlockHost(options) {
     function stopWithFailure(error) {
         stop();
         emit("warn", error);
-        onFailure?.(error);
+        onConnectionFailure?.(error);
     }
     return {
         stop,

package/dist/lifecycle/initializationController.d.ts

@@ -15,7 +15,7 @@ export type InitializationControllerOptions = {
     noInitResultTimeoutMs?: number;
     stopHostWithFailure: (error: CustomBlockHostFailure) => void;
     onInitResult?: (message: InitResultMessage) => void;
-    onFailure?: (error: CustomBlockHostFailure) => void;
+    onConnectionFailure: ((error: CustomBlockHostFailure) => void) | undefined;
 };
 export type InitializationController = {
     readonly status: InitStatus;

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,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAA;CACnD,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;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"}

package/dist/lifecycle/initializationController.js

@@ -6,7 +6,7 @@ const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5_000;
 const DEFAULT_INITIAL_STATE_TIMEOUT_MS = 5_000;
 const DEFAULT_NO_INIT_RESULT_TIMEOUT_MS = 5_000;
 export function createInitializationController(options) {
-    const { prepareInit, sendInitMessage, warn, flushPendingHostStateChanges, minBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, initialStateTimeoutMs = DEFAULT_INITIAL_STATE_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, stopHostWithFailure, onInitResult, onFailure, } = options;
+    const { prepareInit, sendInitMessage, warn, flushPendingHostStateChanges, minBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, initialStateTimeoutMs = DEFAULT_INITIAL_STATE_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, stopHostWithFailure, onInitResult, onConnectionFailure, } = options;
     let initStatus = "waitingForConnect";
     let noConnectTimeoutId;
     let initialStateTimeoutId;
@@ -56,7 +56,7 @@ export function createInitializationController(options) {
             status: "error",
             error,
         });
-        onFailure?.(error);
+        onConnectionFailure?.(error);
     }
     async function prepareAndSendInit(connect) {
         if (initStatus !== "waitingForConnect") {
@@ -110,7 +110,7 @@ export function createInitializationController(options) {
                 }
                 initStatus = "error";
                 const error = initErrorForFailureReason("no_init_result");
-                onFailure?.(error);
+                onConnectionFailure?.(error);
                 warn({
                     ...error,
                     initializationId: connect.initializationId,
@@ -210,7 +210,7 @@ export function createInitializationController(options) {
         clearNoInitResultTimeout();
         initStatus = "error";
         warn(error);
-        onFailure?.(error);
+        onConnectionFailure?.(error);
     }
     function onIframeLoad() {
         if (initStatus === "stopped") {
@@ -238,7 +238,7 @@ export function createInitializationController(options) {
             initStatus = "error";
             const error = initErrorForFailureReason("no_connect");
             warn(error);
-            onFailure?.(error);
+            onConnectionFailure?.(error);
         }, noConnectTimeoutMs);
     }
     function handleInitResult(message) {
@@ -256,7 +256,7 @@ export function createInitializationController(options) {
             flushPendingHostStateChanges();
         }
         else {
-            onFailure?.(message.error);
+            onConnectionFailure?.(message.error);
         }
         onInitResult?.(message);
     }

package/dist/queries/querySubscriptions.d.ts

@@ -8,7 +8,9 @@ export type QuerySubscriptionToken = {
     readonly _tag: "QuerySubscriptionToken";
 };
 export declare class QuerySubscriptions {
+    private readonly onUnsubscribe;
     private readonly bySubscriptionId;
+    constructor(onUnsubscribe: (subscriptionId: string) => void);
     subscribe(message: QueryDataSourceMessage): QuerySubscriptionToken;
     isCurrent(subscriptionId: string, token: QuerySubscriptionToken): boolean;
     unsubscribe(subscriptionId: string): void;

package/dist/queries/querySubscriptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"querySubscriptions.d.ts","sourceRoot":"","sources":["../../src/queries/querySubscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAA;AACjF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAE1G,MAAM,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,sBAAsB,CAAA;IAC/B,KAAK,EAAE,sBAAsB,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG;IACpC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAA;CACvC,CAAA;AASD,qBAAa,kBAAkB;IAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA4C;IAE7E,SAAS,CAAC,OAAO,EAAE,sBAAsB,GAAG,sBAAsB,CAWjE;IAED,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAExE;IAED,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAExC;IAED,OAAO,CAAC,YAAY,EAAE,kBAAkB,GAAG,YAAY,EAAE,GAAG,SAAS,CAmBpE;IAED,MAAM,CACL,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,sBAAsB,GAC3B,YAAY,GAAG,SAAS,CAY1B;IAED,cAAc,SAEb;CACD"}
+{"version":3,"file":"querySubscriptions.d.ts","sourceRoot":"","sources":["../../src/queries/querySubscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAA;AACjF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAE1G,MAAM,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,sBAAsB,CAAA;IAC/B,KAAK,EAAE,sBAAsB,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG;IACpC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAA;CACvC,CAAA;AASD,qBAAa,kBAAkB;IAI7B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAH/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA4C;IAE7E,YACkB,aAAa,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,IAAI,EAC7D;IAEJ,SAAS,CAAC,OAAO,EAAE,sBAAsB,GAAG,sBAAsB,CAYjE;IAED,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAExE;IAED,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAIxC;IAED,OAAO,CAAC,YAAY,EAAE,kBAAkB,GAAG,YAAY,EAAE,GAAG,SAAS,CAmBpE;IAED,MAAM,CACL,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,sBAAsB,GAC3B,YAAY,GAAG,SAAS,CAY1B;IAED,cAAc,SAIb;CACD"}

package/dist/queries/querySubscriptions.js

@@ -1,6 +1,11 @@
 export class QuerySubscriptions {
+    onUnsubscribe;
     bySubscriptionId = new Map();
+    constructor(onUnsubscribe) {
+        this.onUnsubscribe = onUnsubscribe;
+    }
     subscribe(message) {
+        this.unsubscribe(message.subscriptionId);
         const token = {
             _tag: "QuerySubscriptionToken",
         };
@@ -16,7 +21,9 @@ export class QuerySubscriptions {
         return this.bySubscriptionId.get(subscriptionId)?.token === token;
     }
     unsubscribe(subscriptionId) {
-        this.bySubscriptionId.delete(subscriptionId);
+        if (this.bySubscriptionId.delete(subscriptionId)) {
+            this.onUnsubscribe(subscriptionId);
+        }
     }
     refresh(dataSourceId) {
         const refreshes = [];
@@ -52,6 +59,8 @@ export class QuerySubscriptions {
         return { message: state.message, token: state.token };
     }
     unsubscribeAll() {
-        this.bySubscriptionId.clear();
+        for (const subscriptionId of this.bySubscriptionId.keys()) {
+            this.unsubscribe(subscriptionId);
+        }
     }
 }

package/package.json

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

package/src/createCustomBlockHost.ts

@@ -83,7 +83,9 @@ export type CustomBlockHostOptions = {
 	 * before this callback runs.
 	 * This callback can run after initialization succeeds.
 	 */
-	onFailure?: (error: CustomBlockHostFailure) => void
+	onConnectionFailure: ((error: CustomBlockHostFailure) => void) | undefined
+	/** Releases adapter resources when a query ends, including replacement and terminal errors. */
+	onQueryUnsubscribed: ((subscriptionId: string) => void) | undefined
 	onLog?: (direction: CustomBlockHostLogDirection, payload: unknown) => void
 	getInitialState: CustomBlockHostGetInitialState
 	initialStateTimeoutMs?: number
@@ -119,8 +121,9 @@ export function createCustomBlockHost(
 		handlers,
 		onManifest,
 		onInitialized,
-		onFailure,
+		onConnectionFailure,
 		onLog,
+		onQueryUnsubscribed,
 		sandboxOrigin,
 		minBridgeProtocolVersion: configuredMinBridgeProtocolVersion,
 		noConnectTimeoutMs,
@@ -143,7 +146,9 @@ export function createCustomBlockHost(
 	let manifest: CustomBlockManifest | undefined
 	let activeDataSources: CustomBlockHostNormalizedDataSourcesPayload | undefined
 	let sandboxBridgeProtocolVersion = LATEST_BRIDGE_PROTOCOL_VERSION
-	const querySubscriptions = new QuerySubscriptions()
+	const querySubscriptions = new QuerySubscriptions(subscriptionId => {
+		onQueryUnsubscribed?.(subscriptionId)
+	})
 
 	function emit(direction: CustomBlockHostLogDirection, payload: unknown) {
 		onLog?.(direction, payload)
@@ -255,6 +260,7 @@ export function createCustomBlockHost(
 			const queryError = getQueryValidationError(message, collectionSchema)
 			if (queryError !== undefined) {
 				if (querySubscriptions.isCurrent(message.subscriptionId, token)) {
+					querySubscriptions.unsubscribe(message.subscriptionId)
 					postQueryDataSourceResult({
 						subscriptionId: message.subscriptionId,
 						response: { status: "error", error: queryError },
@@ -266,6 +272,9 @@ export function createCustomBlockHost(
 			if (!querySubscriptions.isCurrent(message.subscriptionId, token)) {
 				return
 			}
+			if (response.status === "error" && !response.error.isRetryable) {
+				querySubscriptions.unsubscribe(message.subscriptionId)
+			}
 			postQueryDataSourceResult({
 				subscriptionId: message.subscriptionId,
 				response,
@@ -348,7 +357,7 @@ export function createCustomBlockHost(
 				onInitialized?.({ manifest, initialHeight: message.initialHeight })
 			}
 		},
-		onFailure,
+		onConnectionFailure,
 	})
 
 	function prepareInitialState(
@@ -431,7 +440,7 @@ export function createCustomBlockHost(
 	function stopWithFailure(error: CustomBlockHostFailure) {
 		stop()
 		emit("warn", error)
-		onFailure?.(error)
+		onConnectionFailure?.(error)
 	}
 
 	return {

package/src/lifecycle/initializationController.ts

@@ -33,7 +33,7 @@ export type InitializationControllerOptions = {
 	noInitResultTimeoutMs?: number
 	stopHostWithFailure: (error: CustomBlockHostFailure) => void
 	onInitResult?: (message: InitResultMessage) => void
-	onFailure?: (error: CustomBlockHostFailure) => void
+	onConnectionFailure: ((error: CustomBlockHostFailure) => void) | undefined
 }
 
 export type InitializationController = {
@@ -68,7 +68,7 @@ export function createInitializationController(
 		noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS,
 		stopHostWithFailure,
 		onInitResult,
-		onFailure,
+		onConnectionFailure,
 	} = options
 
 	let initStatus: InitStatus = "waitingForConnect"
@@ -127,7 +127,7 @@ export function createInitializationController(
 			status: "error",
 			error,
 		})
-		onFailure?.(error)
+		onConnectionFailure?.(error)
 	}
 
 	async function prepareAndSendInit(connect: ConnectSuccessMessage) {
@@ -184,7 +184,7 @@ export function createInitializationController(
 				}
 				initStatus = "error"
 				const error = initErrorForFailureReason("no_init_result")
-				onFailure?.(error)
+				onConnectionFailure?.(error)
 				warn({
 					...error,
 					initializationId: connect.initializationId,
@@ -301,7 +301,7 @@ export function createInitializationController(
 		clearNoInitResultTimeout()
 		initStatus = "error"
 		warn(error)
-		onFailure?.(error)
+		onConnectionFailure?.(error)
 	}
 
 	function onIframeLoad() {
@@ -331,7 +331,7 @@ export function createInitializationController(
 			initStatus = "error"
 			const error = initErrorForFailureReason("no_connect")
 			warn(error)
-			onFailure?.(error)
+			onConnectionFailure?.(error)
 		}, noConnectTimeoutMs)
 	}
 
@@ -351,7 +351,7 @@ export function createInitializationController(
 		if (message.status === "success") {
 			flushPendingHostStateChanges()
 		} else {
-			onFailure?.(message.error)
+			onConnectionFailure?.(message.error)
 		}
 		onInitResult?.(message)
 	}

package/src/queries/querySubscriptions.ts

@@ -20,7 +20,12 @@ type QuerySubscriptionState = {
 export class QuerySubscriptions {
 	private readonly bySubscriptionId = new Map<string, QuerySubscriptionState>()
 
+	constructor(
+		private readonly onUnsubscribe: (subscriptionId: string) => void,
+	) {}
+
 	subscribe(message: QueryDataSourceMessage): QuerySubscriptionToken {
+		this.unsubscribe(message.subscriptionId)
 		const token: QuerySubscriptionToken = {
 			_tag: "QuerySubscriptionToken",
 		}
@@ -38,7 +43,9 @@ export class QuerySubscriptions {
 	}
 
 	unsubscribe(subscriptionId: string): void {
-		this.bySubscriptionId.delete(subscriptionId)
+		if (this.bySubscriptionId.delete(subscriptionId)) {
+			this.onUnsubscribe(subscriptionId)
+		}
 	}
 
 	refresh(dataSourceId: NotionDataSourceId): QueryRefresh[] | undefined {
@@ -80,6 +87,8 @@ export class QuerySubscriptions {
 	}
 
 	unsubscribeAll() {
-		this.bySubscriptionId.clear()
+		for (const subscriptionId of this.bySubscriptionId.keys()) {
+			this.unsubscribe(subscriptionId)
+		}
 	}
 }