@notionhq/custom-blocks 0.1.42 → 0.1.44

package/README.md

@@ -124,10 +124,10 @@ 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/pages.md`](./docs/pages.md) — `pages.create / get / update / delete`, parent variants (including the recommended `data_source_key`), property input shapes.
+- [`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.
 - [`docs/deployment.md`](./docs/deployment.md) — worker-backed deploys, localhost self-hosted fallback, where the manifest comes from.

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

@@ -12,6 +12,7 @@ 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";
 const RESPONSE_TYPE_BY_REQUEST = new Map([
     ["getPage", "getPageResult"],
@@ -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") {
@@ -725,17 +740,20 @@ export class SandboxBridge {
         });
     }
     updatePage(args) {
+        // Prefer is_archived over the deprecated archived argument.
+        // TODO(custom-blocks): Remove the archived fallback when upgrading to bridge protocol v4.
+        const isArchived = args.is_archived ?? args.archived;
         return new Promise(resolve => {
             if ((args.properties === undefined ||
                 Object.keys(args.properties).length === 0) &&
                 args.icon === undefined &&
                 args.cover === undefined &&
-                args.archived === undefined) {
+                isArchived === undefined) {
                 resolve({
                     status: "error",
                     error: {
                         code: "invalid_page_update",
-                        message: "updatePage requires at least one of: properties, icon, cover, archived.",
+                        message: "updatePage requires at least one property.",
                         isRetryable: false,
                     },
                 });
@@ -756,8 +774,8 @@ export class SandboxBridge {
             if (args.cover !== undefined) {
                 outbound.cover = args.cover;
             }
-            if (args.archived !== undefined) {
-                outbound.archived = args.archived;
+            if (isArchived !== undefined) {
+                outbound.archived = isArchived;
             }
             this.postToHost(outbound);
         });
@@ -784,7 +802,7 @@ export class SandboxBridge {
             properties: resolvedProperties?.properties,
             icon: pageUpdateArgs.icon,
             cover: pageUpdateArgs.cover,
-            archived: pageUpdateArgs.archived,
+            is_archived: pageUpdateArgs.is_archived ?? pageUpdateArgs.archived,
         });
     }
     /**

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/hostState.d.ts.map

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

package/dist/bridge/hostState.js

@@ -43,17 +43,20 @@ export function getDataSourceQueryView(hostState, key, subscriptionId, updateDat
             propertiesByKey[key] =
                 propertyId === undefined ? undefined : entry.propertiesById[propertyId];
         }
+        const update = (args) => updateDataSourcePage({
+            dataSource,
+            pageId: entry.id,
+            pageUpdateArgs: args,
+        });
         return {
             id: entry.id,
             is_archived: entry.is_archived,
             in_trash: entry.in_trash,
             propertiesById: entry.propertiesById,
             propertiesByKey,
-            update: args => updateDataSourcePage({
-                dataSource,
-                pageId: entry.id,
-                pageUpdateArgs: args,
-            }),
+            update,
+            archive: () => update({ is_archived: true }),
+            unarchive: () => update({ is_archived: false }),
         };
     });
     const propertySchemasByKey = {};

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/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;
 };
@@ -45,7 +45,16 @@ export declare const pages: {
      */
     update: (input: UpdatePageArgs) => Promise<UpdatePageResult>;
     /**
-     * Soft-delete a page by archiving it.
+     * Archives a page.
+     */
+    archive: (pageId: NotionPageId) => Promise<UpdatePageResult>;
+    /**
+     * Unarchives a page.
+     */
+    unarchive: (pageId: NotionPageId) => Promise<UpdatePageResult>;
+    /**
+     * @deprecated This method archives the page. It does not move the page to Trash.
+     * Use `pages.archive(pageId)` instead.
      */
     delete: (pageId: NotionPageId) => Promise<UpdatePageResult>;
 };

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;AAWxE,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,MAAM,WAAW,YAAY,KAAG,OAAO,CAAC,gBAAgB,CAAC;CAGzD,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,6 +1,7 @@
 import { getDataSourceQueryView as getDataSourceQueryViewWithBridge, } from "./hostState.js";
-import { SandboxBridge } from "./SandboxBridge.js";
+import { SandboxBridge, } from "./SandboxBridge.js";
 let bridge;
+let didWarnAboutPagesDelete = false;
 function getBridge() {
     if (!bridge) {
         bridge = new SandboxBridge();
@@ -41,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);
@@ -82,10 +83,27 @@ export const pages = {
         return getBridge().updatePage(input);
     },
     /**
-     * Soft-delete a page by archiving it.
+     * Archives a page.
+     */
+    archive: (pageId) => {
+        return getBridge().updatePage({ pageId, is_archived: true });
+    },
+    /**
+     * Unarchives a page.
+     */
+    unarchive: (pageId) => {
+        return getBridge().updatePage({ pageId, is_archived: false });
+    },
+    /**
+     * @deprecated This method archives the page. It does not move the page to Trash.
+     * Use `pages.archive(pageId)` instead.
      */
     delete: (pageId) => {
-        return getBridge().updatePage({ pageId, archived: true });
+        if (!didWarnAboutPagesDelete) {
+            didWarnAboutPagesDelete = true;
+            console.warn("[Notion Custom Blocks] DEPRECATED: pages.delete() archives the page. It does not move the page to Trash. Use pages.archive() instead.");
+        }
+        return getBridge().updatePage({ pageId, is_archived: true });
     },
 };
 /**

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;
 }