@notionhq/custom-blocks 0.1.43 → 0.1.45

package/README.md

@@ -124,9 +124,9 @@ Each page covers one API category. Import framework-neutral APIs from
 `@notionhq/custom-blocks`. Import React hooks and components from
 `@notionhq/custom-blocks/react`.
 
-- [`docs/lifecycle.md`](./docs/lifecycle.md) — `<NotionCustomBlock>`, `useCustomBlockInit`, `initCustomBlock`, `NotInIframeError`, `useCustomBlockAutoResize`. The handshake, the React wrapper, sizing.
+- [`docs/lifecycle.md`](./docs/lifecycle.md) — `<NotionCustomBlock>`, `useCustomBlockInit`, `initCustomBlock`, `NotInIframeError`. The handshake, the React wrapper, sizing.
 - [`docs/block-location.md`](./docs/block-location.md) — `useBlockId`, `useParent`, `usePage`, `useTheme`, `useContrastMode`, `NotionTokenScope`, and `NotionTokenScopeProps`. Where the block sits and how to read the host's appearance.
-- [`docs/data-sources.md`](./docs/data-sources.md) — `useDataSource`, `useManifest`, `customBlock.getManifest`, the row, property, and date-value types, plus a worked example.
+- [`docs/data-sources.md`](./docs/data-sources.md) — `customBlock.subscribeToDataSource`, `useDataSource`, `useManifest`, `customBlock.getManifest`, the row, property, and date-value types, plus a worked example.
 - [`docs/pages.md`](./docs/pages.md) — `pages.create / get / update / archive / unarchive`, parent variants (including the recommended `data_source_key`), property input shapes.
 - [`docs/users.md`](./docs/users.md) — `users.list / get`, the `NotionUser` shape, paging.
 - [`docs/errors.md`](./docs/errors.md) — request results, error format, error codes, retries, and initialization failures.

package/dist/bridge/SandboxBridge.d.ts

@@ -1,7 +1,7 @@
 import type { NotionDataSource } from "../protocol/dataSources/dataSource.js";
 import type { NotionPageId } from "../protocol/ids.js";
 import { type InitMessage } from "../protocol/messages/init.js";
-import type { CreatePageArgs, CreatePageResult, GetPageResult, GetUserResult, ListUsersArgs, ListUsersResult, NotionDataSourcePageUpdateArgs, NotionUserId, UpdatePageArgs, UpdatePageResult, UseDataSourceOptions } from "../types.js";
+import type { CreatePageArgs, CreatePageResult, DataSourceQueryOptions, GetPageResult, GetUserResult, ListUsersArgs, ListUsersResult, NotionDataSourcePageUpdateArgs, NotionUserId, UpdatePageArgs, UpdatePageResult } from "../types.js";
 import { type CustomBlockHostState } from "./hostState.js";
 import type { ManifestLoadResult } from "./loadManifest.js";
 /**
@@ -13,6 +13,13 @@ export type MessageLogEntry = {
     direction: "sent" | "received";
     data: unknown;
 };
+export type QueryDataSourceArgs = {
+    subscriptionId: string;
+    key: string;
+    options?: DataSourceQueryOptions;
+    /** Send the query even if an identical query is already loading. */
+    forceRequery?: boolean;
+};
 export declare class SandboxBridge {
     private hostState;
     private listeners;
@@ -67,7 +74,7 @@ export declare class SandboxBridge {
      */
     private scheduleInitResult;
     createDataSourceSubscriptionId(): string;
-    queryDataSource(subscriptionId: string, key: string, options?: UseDataSourceOptions): void;
+    queryDataSource({ subscriptionId, key, options, forceRequery, }: QueryDataSourceArgs): void;
     private setDataSourceQueryError;
     releaseDataSourceSubscription(subscriptionId: string): void;
     postResize(height: number): void;

package/dist/bridge/SandboxBridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SandboxBridge.d.ts","sourceRoot":"","sources":["../../src/bridge/SandboxBridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SandboxBridge.d.ts","sourceRoot":"","sources":["../../src/bridge/SandboxBridge.ts"],"names":[],"mappings":"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"}

package/dist/bridge/SandboxBridge.js

@@ -4,7 +4,6 @@ import { hostToSandboxMessageSchema, } from "../protocol/messages/hostToSandbox.
 import { CustomBlockInitializationError, initMessageSchema, } from "../protocol/messages/init.js";
 import { CUSTOM_BLOCK_BRIDGE_PROTOCOL_VERSION } from "../protocol/protocolVersion.js";
 import * as v from "valibot";
-import { globalPrimedResponsesCache } from "../testing.js";
 import { unreachable } from "../utils.js";
 import { CUSTOM_BLOCKS_SDK_VERSION } from "../version.js";
 import { NOTION_DARK_BACKGROUND_BASE, NOTION_LIGHT_BACKGROUND_BASE, } from "./appearance.js";
@@ -12,7 +11,9 @@ import { resolveDataSourceQuery } from "./dataSources/query.js";
 import { resolveDataSources } from "./dataSources/resolve.js";
 import { resolvePropertyWriteMapForDataSource } from "./dataSources/resolveProperty.js";
 import { createEmptyDataSourceQueryState, } from "./hostState.js";
+import { notifyListener } from "./notifyListener.js";
 import { PendingRequests } from "./pendingRequests.js";
+import { globalPrimedResponsesCache } from "./primedResponses.js";
 const RESPONSE_TYPE_BY_REQUEST = new Map([
     ["getPage", "getPageResult"],
     ["createPage", "createPageResult"],
@@ -181,7 +182,7 @@ export class SandboxBridge {
     }
     notify = () => {
         for (const listener of this.listeners) {
-            listener();
+            notifyListener(listener);
         }
     };
     handleMessage = (event) => {
@@ -312,13 +313,21 @@ export class SandboxBridge {
                     nextBindings,
                 });
                 this.latestDataSourceBindings = nextBindings;
-                // Drop cached query state for subscriptions whose key no longer exists.
-                const nextKeys = new Set(dataSources.map(s => s.key));
+                // Preserve rows only while the key still refers to the same backing data source.
+                const previousSourcesByKey = new Map(hostState.dataSources.map(source => [source.key, source]));
+                const nextSourcesByKey = new Map(dataSources.map(source => [source.key, source]));
                 const prunedState = {};
                 for (const [subscriptionId, state] of Object.entries(hostState.dataSourceState)) {
-                    if (nextKeys.has(state.dataSourceKey)) {
-                        prunedState[subscriptionId] = state;
+                    const nextSource = nextSourcesByKey.get(state.dataSourceKey);
+                    if (nextSource === undefined) {
+                        continue;
                     }
+                    const previousSource = previousSourcesByKey.get(state.dataSourceKey);
+                    prunedState[subscriptionId] =
+                        previousSource?.collectionPointer?.id ===
+                            nextSource.collectionPointer?.id
+                            ? state
+                            : createEmptyDataSourceQueryState(state.dataSourceKey);
                 }
                 this.hostState = {
                     ...hostState,
@@ -552,7 +561,7 @@ export class SandboxBridge {
     createDataSourceSubscriptionId() {
         return `data-source:${globalThis.crypto.randomUUID()}`;
     }
-    queryDataSource(subscriptionId, key, options = {}) {
+    queryDataSource({ subscriptionId, key, options = {}, forceRequery = false, }) {
         if (this.hostState.status !== "initialized") {
             return;
         }
@@ -591,7 +600,8 @@ export class SandboxBridge {
             return;
         }
         const query = resolvedQuery.query;
-        if (currentState.isLoading &&
+        if (!forceRequery &&
+            currentState.isLoading &&
             currentState.latestQueryIdentity === query.identity) {
             return;
         }
@@ -609,7 +619,6 @@ export class SandboxBridge {
                 },
             },
         };
-        this.notify();
         const outbound = {
             type: "queryDataSource",
             subscriptionId,
@@ -619,6 +628,7 @@ export class SandboxBridge {
             ...(query.sorts !== undefined ? { sorts: query.sorts } : {}),
         };
         this.postToHost(outbound);
+        this.notify();
     }
     setDataSourceQueryError(subscriptionId, currentState, error) {
         if (this.hostState.status !== "initialized") {
@@ -649,6 +659,11 @@ export class SandboxBridge {
             ...this.hostState,
             dataSourceState,
         };
+        const outbound = {
+            type: "unsubscribeDataSourceQuery",
+            subscriptionId,
+        };
+        this.postToHost(outbound);
     }
     postResize(height) {
         if (typeof window === "undefined") {

package/dist/bridge/dataSources/subscribe.d.ts

@@ -0,0 +1,3 @@
+import type { SubscribeToDataSourceArgs } from "../../types.js";
+export declare function subscribeToDataSource({ key, onSnapshot, options: providedOptions, }: SubscribeToDataSourceArgs): () => void;
+//# sourceMappingURL=subscribe.d.ts.map

package/dist/bridge/dataSources/subscribe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe.d.ts","sourceRoot":"","sources":["../../../src/bridge/dataSources/subscribe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAA;AAQ/D,wBAAgB,qBAAqB,CAAC,EACrC,GAAG,EACH,UAAU,EACV,OAAO,EAAE,eAAoB,GAC7B,EAAE,yBAAyB,GAAG,MAAM,IAAI,CAoFxC"}

package/dist/bridge/dataSources/subscribe.js

@@ -0,0 +1,63 @@
+import { notifyListener } from "../notifyListener.js";
+import { customBlockDataSources, customBlockHost } from "../sandboxClient.js";
+export function subscribeToDataSource({ key, onSnapshot, options: providedOptions = {}, }) {
+    const options = structuredClone(providedOptions);
+    const subscriptionId = customBlockDataSources.createSubscriptionId();
+    let active = true;
+    let lastSnapshotInputs;
+    let lastMatchingSignature;
+    const deliverSnapshotIfChanged = (hostState, dataSource, queryState) => {
+        if (lastSnapshotInputs !== undefined &&
+            lastSnapshotInputs.status === hostState.status &&
+            lastSnapshotInputs.dataSource === dataSource &&
+            lastSnapshotInputs.queryState === queryState) {
+            return;
+        }
+        const snapshot = customBlockDataSources.getView(hostState, key, subscriptionId);
+        // Record inputs before calling consumer code, which can trigger another notification.
+        lastSnapshotInputs = { status: hostState.status, dataSource, queryState };
+        notifyListener(() => onSnapshot(snapshot));
+    };
+    const handleHostChange = () => {
+        if (!active) {
+            return;
+        }
+        const hostState = customBlockHost.getState();
+        if (hostState.status !== "initialized") {
+            deliverSnapshotIfChanged(hostState, undefined, undefined);
+            return;
+        }
+        const dataSource = hostState.dataSources.find(source => source.key === key);
+        const signature = dataSource === undefined ? null : JSON.stringify(dataSource);
+        if (signature !== lastMatchingSignature) {
+            const forceRequery = lastMatchingSignature !== undefined;
+            lastMatchingSignature = signature;
+            // Querying updates SDK state and calls this listener again.
+            customBlockDataSources.query({
+                subscriptionId,
+                key,
+                options,
+                forceRequery,
+            });
+            return;
+        }
+        deliverSnapshotIfChanged(hostState, dataSource, hostState.dataSourceState[subscriptionId]);
+    };
+    const unsubscribeHost = customBlockHost.subscribe(handleHostChange);
+    try {
+        handleHostChange();
+    }
+    catch (error) {
+        unsubscribeHost();
+        customBlockDataSources.release(subscriptionId);
+        throw error;
+    }
+    return () => {
+        if (!active) {
+            return;
+        }
+        active = false;
+        unsubscribeHost();
+        customBlockDataSources.release(subscriptionId);
+    };
+}

package/dist/bridge/notifyListener.d.ts

@@ -0,0 +1,3 @@
+/** Report consumer errors without interrupting bridge operations or other listeners. */
+export declare function notifyListener(listener: () => void): void;
+//# sourceMappingURL=notifyListener.d.ts.map

package/dist/bridge/notifyListener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifyListener.d.ts","sourceRoot":"","sources":["../../src/bridge/notifyListener.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAYzD"}

package/dist/bridge/notifyListener.js

@@ -0,0 +1,16 @@
+/** Report consumer errors without interrupting bridge operations or other listeners. */
+export function notifyListener(listener) {
+    try {
+        listener();
+    }
+    catch (error) {
+        if (typeof globalThis.reportError === "function") {
+            globalThis.reportError(error);
+        }
+        else {
+            setTimeout(() => {
+                throw error;
+            }, 0);
+        }
+    }
+}

package/dist/bridge/primedResponses.d.ts

@@ -0,0 +1,8 @@
+import type { BridgeMessagePayload } from "../protocol/index.js";
+import type { PrimeableHostToSandboxMessage } from "../protocol/messages/hostToSandbox.js";
+/**
+ * Shared across sandbox bridge instances. Each result type holds one response;
+ * consuming it removes it, and priming it again replaces the previous response.
+ */
+export declare const globalPrimedResponsesCache: Map<"createPageResult" | "getPageResult" | "getUserResult" | "listUsersResult" | "queryDataSourceResult" | "updatePageResult", BridgeMessagePayload<PrimeableHostToSandboxMessage>>;
+//# sourceMappingURL=primedResponses.d.ts.map

package/dist/bridge/primedResponses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primedResponses.d.ts","sourceRoot":"","sources":["../../src/bridge/primedResponses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAC5E,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,4DAA4D,CAAA;AAE/G;;;GAGG;AACH,eAAO,MAAM,0BAA0B,qLAGpC,CAAA"}

package/dist/bridge/primedResponses.js

@@ -0,0 +1,5 @@
+/**
+ * Shared across sandbox bridge instances. Each result type holds one response;
+ * consuming it removes it, and priming it again replaces the previous response.
+ */
+export const globalPrimedResponsesCache = new Map();

package/dist/bridge/sandboxClient.d.ts

@@ -1,9 +1,9 @@
 import type { NotionPageId } from "../protocol/ids.js";
 import type { InitMessage } from "../protocol/messages/init.js";
-import type { CreatePageArgs, CreatePageResult, GetPageResult, GetUserResult, ListUsersArgs, ListUsersResult, NotionUserId, UpdatePageArgs, UpdatePageResult, UseDataSourceOptions } from "../types.js";
+import type { CreatePageArgs, CreatePageResult, GetPageResult, GetUserResult, ListUsersArgs, ListUsersResult, NotionUserId, UpdatePageArgs, UpdatePageResult } from "../types.js";
 import { type CustomBlockHostState, type DataSourceQueryView } from "./hostState.js";
 import type { ManifestLoadResult } from "./loadManifest.js";
-import { type MessageLogEntry } from "./SandboxBridge.js";
+import { type MessageLogEntry, type QueryDataSourceArgs } from "./SandboxBridge.js";
 export declare const customBlockHost: {
     start: () => void;
     sendConnect: (manifestResult: ManifestLoadResult) => void;
@@ -20,7 +20,7 @@ export declare const customBlockHost: {
 };
 export declare const customBlockDataSources: {
     createSubscriptionId: () => string;
-    query: (subscriptionId: string, key: string, options?: UseDataSourceOptions) => void;
+    query: (args: QueryDataSourceArgs) => void;
     release: (subscriptionId: string) => void;
     getView: (hostState: CustomBlockHostState, key: string, subscriptionId: string) => DataSourceQueryView;
 };

package/dist/bridge/sandboxClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandboxClient.d.ts","sourceRoot":"","sources":["../../src/bridge/sandboxClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAA;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mDAAmD,CAAA;AACpF,OAAO,KAAK,EACX,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,MAAM,aAAa,CAAA;AACpB,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAExB,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,oBAAoB,CAAA;AAYxE,eAAO,MAAM,eAAe;IAC3B,KAAK;IAIL,WAAW,mBAAmB,kBAAkB;IAIhD,SAAS,YAAY,WAAW,KAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,SAAS,aAAa,MAAM,IAAI;IAIhC,QAAQ,QAAM,oBAAoB;IAIlC;;;OAGG;IACH,YAAY,YAAY,WAAW;IAInC,sBAAsB;IAItB,UAAU,WAAW,MAAM;CAG3B,CAAA;AAED,eAAO,MAAM,sBAAsB;IAClC,oBAAoB;IAIpB,KAAK,mBACY,MAAM,OACjB,MAAM,YACD,oBAAoB;IAK/B,OAAO,mBAAmB,MAAM;IAIhC,OAAO,cACK,oBAAoB,OAC1B,MAAM,kBACK,MAAM,KACpB,mBAAmB;CAQtB,CAAA;AAED,eAAO,MAAM,UAAU;IACtB,WAAW,QAAM,SAAS,eAAe,EAAE;IAI3C,SAAS,aAAa,MAAM,IAAI;CAGhC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,KAAK;IACjB;;OAEG;IACH,MAAM,UAAU,cAAc,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D;;OAEG;IACH,GAAG,WAAW,YAAY,KAAG,OAAO,CAAC,aAAa,CAAC;IAInD;;OAEG;IACH,MAAM,UAAU,cAAc,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D;;OAEG;IACH,OAAO,WAAW,YAAY,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D;;OAEG;IACH,SAAS,WAAW,YAAY,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI5D;;;OAGG;IACH,MAAM,WAAW,YAAY,KAAG,OAAO,CAAC,gBAAgB,CAAC;CASzD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,KAAK;IACjB;;OAEG;IACH,IAAI,WAAW,aAAa,KAAG,OAAO,CAAC,eAAe,CAAC;IAIvD;;OAEG;IACH,GAAG,WAAW,YAAY,KAAG,OAAO,CAAC,aAAa,CAAC;CAGnD,CAAA"}
+{"version":3,"file":"sandboxClient.d.ts","sourceRoot":"","sources":["../../src/bridge/sandboxClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAA;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mDAAmD,CAAA;AACpF,OAAO,KAAK,EACX,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,MAAM,aAAa,CAAA;AACpB,OAAO,EACN,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAExB,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,mBAAmB,EAExB,MAAM,oBAAoB,CAAA;AAY3B,eAAO,MAAM,eAAe;IAC3B,KAAK;IAIL,WAAW,mBAAmB,kBAAkB;IAIhD,SAAS,YAAY,WAAW,KAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,SAAS,aAAa,MAAM,IAAI;IAIhC,QAAQ,QAAM,oBAAoB;IAIlC;;;OAGG;IACH,YAAY,YAAY,WAAW;IAInC,sBAAsB;IAItB,UAAU,WAAW,MAAM;CAG3B,CAAA;AAED,eAAO,MAAM,sBAAsB;IAClC,oBAAoB;IAIpB,KAAK,SAAS,mBAAmB;IAIjC,OAAO,mBAAmB,MAAM;IAIhC,OAAO,cACK,oBAAoB,OAC1B,MAAM,kBACK,MAAM,KACpB,mBAAmB;CAQtB,CAAA;AAED,eAAO,MAAM,UAAU;IACtB,WAAW,QAAM,SAAS,eAAe,EAAE;IAI3C,SAAS,aAAa,MAAM,IAAI;CAGhC,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,KAAK;IACjB;;OAEG;IACH,MAAM,UAAU,cAAc,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D;;OAEG;IACH,GAAG,WAAW,YAAY,KAAG,OAAO,CAAC,aAAa,CAAC;IAInD;;OAEG;IACH,MAAM,UAAU,cAAc,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D;;OAEG;IACH,OAAO,WAAW,YAAY,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI1D;;OAEG;IACH,SAAS,WAAW,YAAY,KAAG,OAAO,CAAC,gBAAgB,CAAC;IAI5D;;;OAGG;IACH,MAAM,WAAW,YAAY,KAAG,OAAO,CAAC,gBAAgB,CAAC;CASzD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,KAAK;IACjB;;OAEG;IACH,IAAI,WAAW,aAAa,KAAG,OAAO,CAAC,eAAe,CAAC;IAIvD;;OAEG;IACH,GAAG,WAAW,YAAY,KAAG,OAAO,CAAC,aAAa,CAAC;CAGnD,CAAA"}

package/dist/bridge/sandboxClient.js

@@ -1,5 +1,5 @@
 import { getDataSourceQueryView as getDataSourceQueryViewWithBridge, } from "./hostState.js";
-import { SandboxBridge } from "./SandboxBridge.js";
+import { SandboxBridge, } from "./SandboxBridge.js";
 let bridge;
 let didWarnAboutPagesDelete = false;
 function getBridge() {
@@ -42,8 +42,8 @@ export const customBlockDataSources = {
     createSubscriptionId: () => {
         return getBridge().createDataSourceSubscriptionId();
     },
-    query: (subscriptionId, key, options) => {
-        getBridge().queryDataSource(subscriptionId, key, options);
+    query: (args) => {
+        getBridge().queryDataSource(args);
     },
     release: (subscriptionId) => {
         getBridge().releaseDataSourceSubscription(subscriptionId);

package/dist/customBlock.d.ts

@@ -7,6 +7,7 @@ import type { NotionParent } from "./protocol/parent.js";
 import type { NotionTheme } from "./protocol/theme.js";
 import type { NotionUser } from "./protocol/users/user.js";
 import { autoResize } from "./autoResize.js";
+import { subscribeToDataSource } from "./bridge/dataSources/subscribe.js";
 export type CustomBlockState = {
     status: "uninitialized";
     theme: NotionTheme;
@@ -36,5 +37,10 @@ export declare const customBlock: {
     getPage(): CustomBlockPage;
     getManifest(): CustomBlockManifest;
     autoResize: typeof autoResize;
+    /**
+     * Registers a listener that receives the current query snapshot and later updates.
+     * Returns a function that removes this listener. Other listeners remain subscribed.
+     */
+    subscribeToDataSource: typeof subscribeToDataSource;
 };
 //# sourceMappingURL=customBlock.d.ts.map

package/dist/customBlock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"customBlock.d.ts","sourceRoot":"","sources":["../src/customBlock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4DAA4D,CAAA;AAClG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,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;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAO5C,MAAM,MAAM,gBAAgB,GACzB;IACA,MAAM,EAAE,eAAe,CAAA;IACvB,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,EAAE,kBAAkB,CAAA;CAC/B,GACD;IACA,MAAM,EAAE,aAAa,CAAA;IACrB,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,EAAE,kBAAkB,CAAA;IAChC,OAAO,EAAE,aAAa,CAAA;IACtB,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,eAAe,CAAA;IACrB,WAAW,EAAE,UAAU,CAAA;IACvB,WAAW,EAAE,gBAAgB,EAAE,CAAA;CAC9B,CAAA;AAEJ;;;GAGG;AACH,eAAO,MAAM,WAAW;wBACH,MAAM,IAAI,GAAG,MAAM,IAAI;gBAI/B,gBAAgB;sBAIV,UAAU;gBAIhB,WAAW;uBAIJ,kBAAkB;kBAIvB,aAAa;iBAId,YAAY;eAId,eAAe;mBAIX,mBAAmB;;CAKlC,CAAA"}
+{"version":3,"file":"customBlock.d.ts","sourceRoot":"","sources":["../src/customBlock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4DAA4D,CAAA;AAClG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,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;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AAOzE,MAAM,MAAM,gBAAgB,GACzB;IACA,MAAM,EAAE,eAAe,CAAA;IACvB,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,EAAE,kBAAkB,CAAA;CAC/B,GACD;IACA,MAAM,EAAE,aAAa,CAAA;IACrB,KAAK,EAAE,WAAW,CAAA;IAClB,YAAY,EAAE,kBAAkB,CAAA;IAChC,OAAO,EAAE,aAAa,CAAA;IACtB,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,eAAe,CAAA;IACrB,WAAW,EAAE,UAAU,CAAA;IACvB,WAAW,EAAE,gBAAgB,EAAE,CAAA;CAC9B,CAAA;AAEJ;;;GAGG;AACH,eAAO,MAAM,WAAW;wBACH,MAAM,IAAI,GAAG,MAAM,IAAI;gBAI/B,gBAAgB;sBAIV,UAAU;gBAIhB,WAAW;uBAIJ,kBAAkB;kBAIvB,aAAa;iBAId,YAAY;eAId,eAAe;mBAIX,mBAAmB;;IAMlC;;;OAGG;;CAEH,CAAA"}

package/dist/customBlock.js

@@ -1,4 +1,5 @@
 import { autoResize } from "./autoResize.js";
+import { subscribeToDataSource } from "./bridge/dataSources/subscribe.js";
 import { customBlockHost } from "./bridge/sandboxClient.js";
 /**
  * Framework-neutral runtime state APIs for a custom block. Call `initCustomBlock`
@@ -33,6 +34,11 @@ export const customBlock = {
         return getInitializedHostState("getManifest").manifest;
     },
     autoResize,
+    /**
+     * Registers a listener that receives the current query snapshot and later updates.
+     * Returns a function that removes this listener. Other listeners remain subscribed.
+     */
+    subscribeToDataSource,
 };
 let lastHostState;
 let lastPublicState;

package/dist/protocol/index.d.ts

@@ -39,6 +39,7 @@ export * from "./messages/queryDataSourceResult.js";
 export * from "./messages/resize.js";
 export * from "./messages/sandboxToHost.js";
 export * from "./messages/themeChanged.js";
+export * from "./messages/unsubscribeDataSourceQuery.js";
 export * from "./messages/updatePage.js";
 export * from "./messages/updatePageResult.js";
 export * from "./pages/page.js";

package/dist/protocol/index.js

@@ -39,6 +39,7 @@ export * from "./messages/queryDataSourceResult.js";
 export * from "./messages/resize.js";
 export * from "./messages/sandboxToHost.js";
 export * from "./messages/themeChanged.js";
+export * from "./messages/unsubscribeDataSourceQuery.js";
 export * from "./messages/updatePage.js";
 export * from "./messages/updatePageResult.js";
 export * from "./pages/page.js";

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

@@ -411,6 +411,9 @@ export declare const sandboxToHostMessageSchema: v.VariantSchema<"type", [v.Vari
         readonly propertyId: v.StringSchema<undefined>;
         readonly direction: v.PicklistSchema<["ascending", "descending"], undefined>;
     }, undefined>, undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"unsubscribeDataSourceQuery", undefined>;
+    readonly subscriptionId: v.StringSchema<undefined>;
 }, undefined>, v.ObjectSchema<{
     readonly type: v.LiteralSchema<"createPage", undefined>;
     readonly requestId: v.StringSchema<undefined>;

package/dist/protocol/messages/sandboxToHost.js

@@ -8,6 +8,7 @@ import { invalidHostMessageSchema } from "./invalidHostMessage.js";
 import { listUsersMessageSchema } from "./listUsers.js";
 import { queryDataSourceMessageSchema } from "./queryDataSource.js";
 import { resizeMessageSchema } from "./resize.js";
+import { unsubscribeDataSourceQueryMessageSchema } from "./unsubscribeDataSourceQuery.js";
 import { updatePageMessageSchema } from "./updatePage.js";
 /**
  * Discriminated union of every message the sandbox is allowed to send the host. Useful for hosts
@@ -17,6 +18,7 @@ export const sandboxToHostMessageSchema = v.variant("type", [
     connectMessageSchema,
     initResultMessageSchema,
     queryDataSourceMessageSchema,
+    unsubscribeDataSourceQueryMessageSchema,
     createPageMessageSchema,
     getPageMessageSchema,
     getUserMessageSchema,

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

@@ -0,0 +1,10 @@
+import * as v from "valibot";
+/**
+ * Tells the host to stop an active data source query subscription.
+ */
+export declare const unsubscribeDataSourceQueryMessageSchema: v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"unsubscribeDataSourceQuery", undefined>;
+    /** The subscription to remove from the host. */
+    readonly subscriptionId: v.StringSchema<undefined>;
+}, undefined>;
+export type UnsubscribeDataSourceQueryMessage = v.InferOutput<typeof unsubscribeDataSourceQueryMessageSchema>;

package/dist/protocol/messages/unsubscribeDataSourceQuery.js

@@ -0,0 +1,9 @@
+import * as v from "valibot";
+/**
+ * Tells the host to stop an active data source query subscription.
+ */
+export const unsubscribeDataSourceQueryMessageSchema = v.object({
+    type: v.literal("unsubscribeDataSourceQuery"),
+    /** The subscription to remove from the host. */
+    subscriptionId: v.string(),
+});

package/dist/react/useDataSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDataSource.d.ts","sourceRoot":"","sources":["../../src/react/useDataSource.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAG5E;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,oBAAoB,GAC5B,mBAAmB,CA0CrB"}
+{"version":3,"file":"useDataSource.d.ts","sourceRoot":"","sources":["../../src/react/useDataSource.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAiB5E;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,oBAAoB,GAC5B,mBAAmB,CAqBrB"}

package/dist/react/useDataSource.js

@@ -1,7 +1,14 @@
 import { useEffect, useState } from "react";
 import { getDataSourceQueryOptionsIdentity } from "../bridge/dataSources/query.js";
-import { customBlockDataSources } from "../bridge/sandboxClient.js";
-import { useCustomBlockHost } from "./useHostState.js";
+import { customBlock } from "../customBlock.js";
+const EMPTY_DATA_SOURCE_RESULT = {
+    items: [],
+    propertySchemasById: {},
+    propertyIdsByKey: {},
+    propertySchemasByKey: {},
+    isLoading: false,
+    hasMore: false,
+};
 /**
  * Reads from the data source mapped to the given semantic `key`.
  *
@@ -13,34 +20,24 @@ import { useCustomBlockHost } from "./useHostState.js";
  * const { items, isLoading, hasMore, error } = useDataSource("default", { limit: 25 })
  */
 export function useDataSource(key, options) {
-    const host = useCustomBlockHost();
-    const [subscriptionId] = useState(() => customBlockDataSources.createSubscriptionId());
     const optionsIdentity = getDataSourceQueryOptionsIdentity(options);
-    const matchingDataSource = host.status === "initialized"
-        ? host.dataSources.find(dataSource => dataSource.key === key)
-        : undefined;
-    const isInitialized = host.status === "initialized";
+    const [state, setState] = useState(() => ({
+        key,
+        optionsIdentity,
+        snapshot: EMPTY_DATA_SOURCE_RESULT,
+    }));
     // biome-ignore lint/correctness/useExhaustiveDependencies(options): Compare options by value through optionsIdentity. Object identity alone must not trigger queries.
-    // biome-ignore lint/correctness/useExhaustiveDependencies(optionsIdentity): Changes to the serialized options must trigger a query even though the callback reads options.
-    // biome-ignore lint/correctness/useExhaustiveDependencies(matchingDataSource): Requery when the matching data source changes, even when the key and options are unchanged.
     useEffect(() => {
-        if (!isInitialized) {
-            return;
-        }
-        customBlockDataSources.query(subscriptionId, key, options);
-    }, [matchingDataSource, isInitialized, key, optionsIdentity, subscriptionId]);
-    useEffect(() => () => {
-        customBlockDataSources.release(subscriptionId);
-    }, [subscriptionId]);
-    const view = customBlockDataSources.getView(host, key, subscriptionId);
-    return {
-        items: view.items,
-        collectionSchema: view.collectionSchema,
-        propertySchemasById: view.propertySchemasById,
-        propertyIdsByKey: view.propertyIdsByKey,
-        propertySchemasByKey: view.propertySchemasByKey,
-        isLoading: view.isLoading,
-        hasMore: view.hasMore,
-        error: view.error,
-    };
+        return customBlock.subscribeToDataSource({
+            key,
+            onSnapshot: snapshot => {
+                setState({ key, optionsIdentity, snapshot });
+            },
+            options,
+        });
+    }, [key, optionsIdentity]);
+    if (state.key !== key || state.optionsIdentity !== optionsIdentity) {
+        return EMPTY_DATA_SOURCE_RESULT;
+    }
+    return state.snapshot;
 }

package/dist/testing.d.ts

@@ -1,10 +1,5 @@
 import type { BridgeMessagePayload } from "./protocol/index.js";
 import type { PrimeableHostToSandboxMessage } from "./protocol/messages/hostToSandbox.js";
-/**
- * Shared across sandbox bridge instances. Each result type holds one response;
- * consuming it removes it, and priming it again replaces the previous response.
- */
-export declare const globalPrimedResponsesCache: Map<"createPageResult" | "getPageResult" | "getUserResult" | "listUsersResult" | "queryDataSourceResult" | "updatePageResult", BridgeMessagePayload<PrimeableHostToSandboxMessage>>;
 /**
  * Injects a one-use response for SDK tests and verification fixtures. The next
  * matching request receives it locally without reaching the host; later requests

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAC5E,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,4DAA4D,CAAA;AAE/G;;;GAGG;AACH,eAAO,MAAM,0BAA0B,qLAGpC,CAAA;AAEH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,6BAA6B,EAAE,EAC1E,YAAY,EACZ,QAAQ,GACR,EAAE;IACF,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,CAAA;IACvB,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAA;CACjC,QAEA"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAC5E,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,4DAA4D,CAAA;AAI/G;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,6BAA6B,EAAE,EAC1E,YAAY,EACZ,QAAQ,GACR,EAAE;IACF,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,CAAA;IACvB,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAA;CACjC,QAEA"}

package/dist/testing.js

@@ -1,8 +1,4 @@
-/**
- * Shared across sandbox bridge instances. Each result type holds one response;
- * consuming it removes it, and priming it again replaces the previous response.
- */
-export const globalPrimedResponsesCache = new Map();
+import { globalPrimedResponsesCache } from "./bridge/primedResponses.js";
 /**
  * Injects a one-use response for SDK tests and verification fixtures. The next
  * matching request receives it locally without reaching the host; later requests

package/dist/types.d.ts

@@ -31,7 +31,7 @@ export type NotionPagePropertyInputMap = {
     [propertyIdOrKey: string]: NotionPagePropertyInputValue;
 };
 /**
- * Consumer-facing page shape returned from `useDataSource`. Derived from the bridge payload
+ * Consumer-facing page shape returned from a data source snapshot. Derived from the bridge payload
  * plus the data source's `propertyIdsByKey`.
  */
 export type NotionDataSourcePage = {
@@ -129,14 +129,14 @@ export type NotionDataSourceFilter = NotionDataSourcePropertyFilter | {
     and: NotionDataSourcePropertyFilter[];
 };
 /**
- * Return shape of `useDataSource`.
+ * Latest live snapshot of a data source query.
  *
  * - `items` — the rows the host has returned so far. Empty until the first response arrives.
  * - `isLoading` — `true` while a query is in flight.
- * - `hasMore` — `true` if the host indicated more rows are available beyond the current page.
+ * - `hasMore` — `true` if the host indicated more rows are available beyond the requested prefix.
  * - `error` — structured error information if the most recent query failed.
  */
-export type UseDataSourceResult = {
+export type DataSourceSnapshot = {
     items: NotionDataSourcePage[];
     /**
      * Collection/data source schema for the bound Notion data source, including raw property
@@ -169,21 +169,21 @@ export type UseDataSourceResult = {
     hasMore: boolean;
     error?: CustomBlockQueryDataSourceErrorInfo;
 };
-export type UseDataSourceOptions = {
-    /**
-     * Maximum number of rows to request from the host. Defaults to 20.
-     */
+export type DataSourceQueryOptions = {
+    /** Maximum number of rows to request from the host. Defaults to 20. */
     limit?: number;
-    /**
-     * Optional property filter. The SDK resolves semantic property keys before
-     * it sends the query to the host.
-     */
+    /** Optional property filter. The SDK resolves semantic keys before it sends the query. */
     filter?: NotionDataSourceFilter;
-    /**
-     * Optional property sorts. The host applies them in array order.
-     */
+    /** Optional property sorts. The host applies them in array order. */
     sorts?: NotionDataSourceSort[];
 };
+export type SubscribeToDataSourceArgs = {
+    key: string;
+    onSnapshot: (snapshot: DataSourceSnapshot) => void;
+    options?: DataSourceQueryOptions;
+};
+export type UseDataSourceResult = DataSourceSnapshot;
+export type UseDataSourceOptions = DataSourceQueryOptions;
 /**
  * Parent reference accepted by `sdk.pages.create`. Mirrors Notion's public `POST /v1/pages`
  * parent shape; see https://developers.notion.com/reference/data-source.