@notionhq/custom-blocks 0.1.41 → 0.1.43

package/README.md

@@ -5,7 +5,12 @@
 
 SDK for building Notion custom blocks.
 
-A custom block runs as a sandboxed `<iframe>` inside the Notion app that has no direct access to the internet. The only channel between your block and Notion is a local `postMessage` bridge. This library implements the sandbox side of the bridge protocol and wraps it in a framework-neutral TypeScript API (`@notionhq/custom-blocks`) and typed React hooks (`@notionhq/custom-blocks/react`).
+A custom block runs in a sandboxed `<iframe>` inside Notion. It has no direct
+access to the internet. A local `postMessage` bridge connects the block to
+Notion.
+
+This package provides the sandbox side of the bridge. It exports a
+framework-neutral TypeScript API and typed React hooks.
 
 ## Bundle tooling
 
@@ -14,17 +19,18 @@ Node build tools can import `build` and `upload` from
 
 ## Install
 
-Create a worker project with `ntn workers new --template custom` and use the dependencies and
-entrypoint it generates. In this repository, fixtures depend on the SDK through
-the workspace. React is optional unless the block imports
-`@notionhq/custom-blocks/react`. React blocks need `react` and `react-dom`.
+Create a worker project with `ntn workers new --template custom`. Use the
+dependencies and entrypoint that the Notion CLI generates.
+
+React is optional. Blocks that import `@notionhq/custom-blocks/react` need
+`react` and `react-dom`. This repository's fixtures use the workspace SDK.
 
-For local preview, run `ntn customblocks dev` from the worker project, then
-open `http://localhost:9873`. Install
+For local preview, run `ntn workers customblocks dev` from the worker project.
+Then open `http://localhost:9873`. Install
 [`@notionhq/custom-blocks-dev-shell`](https://www.npmjs.com/package/@notionhq/custom-blocks-dev-shell)
 as a devDependency to pin the shell and get its reference docs in
-`node_modules`; see [`docs/deployment.md`](./docs/deployment.md) for how local
-serving works.
+`node_modules`. See [`docs/deployment.md`](./docs/deployment.md) for local
+serving details.
 
 ## Quick start
 
@@ -43,7 +49,7 @@ worker.customBlock("hello", {
 });
 ```
 
-In the block's entry point defined above, wrap your React code in `<NotionCustomBlock>` so the SDK connects with Notion before anything renders:
+Wrap your React app in `<NotionCustomBlock>` at the block's entry point:
 
 ```tsx
 // blocks/hello/src/index.tsx
@@ -52,10 +58,14 @@ import {
   NotionCustomBlock,
   NotionTokenScope,
 } from "@notionhq/custom-blocks/react";
-import ReactDOM from "react-dom/client";
+import { createRoot } from "react-dom/client";
 import { App } from "./App";
+import "./style.css";
 
-ReactDOM.createRoot(document.getElementById("root")!).render(
+const root = document.getElementById("root");
+if (!root) throw new Error("The root element is missing.");
+
+createRoot(root).render(
   <NotionCustomBlock>
     <NotionTokenScope>
       <App />
@@ -76,6 +86,8 @@ export function App() {
 }
 ```
 
+Save these styles in `blocks/hello/src/style.css`:
+
 ```css
 .app {
   color: var(--content-primary);
@@ -86,26 +98,36 @@ export function App() {
 }
 ```
 
-`<NotionCustomBlock>` runs the SDK ↔ host handshake (`connect` → `init` → `initResult`) and only mounts `children` once the host state is available. It measures the initial content before sending `initResult`, so the host can reveal the iframe at its correct height. Inside the wrapper, every hook returns non-nullable values — there's no separate gating component to write. It continues observing content height changes automatically.
+`<NotionCustomBlock>` connects the SDK to the host and waits for host state before rendering its children.
+It reports the initial content height so the host can size the iframe before displaying it.
+It also reports later height changes automatically.
 
 ## Notion design tokens
 
-The optional `@notionhq/custom-blocks/nds.css` stylesheet provides the colors, spacing, typography, borders, and other design tokens used by Notion. Import it once, then put token-consuming UI inside `<NotionTokenScope>` as shown above.
+The optional `@notionhq/custom-blocks/nds.css` stylesheet provides Notion CSS variables for matching Notion's UI.
+These variables cover colors, spacing, typography, and borders.
+Import the stylesheet once. Place components that use the variables inside `<NotionTokenScope>`, as shown above.
 
-`<NotionTokenScope>` applies the display and contrast modes selected by the host, so variables such as `--content-primary` and `--bg-base` stay in sync with Notion automatically. Hosts that do not provide a contrast mode use standard contrast.
+`<NotionTokenScope>` applies the host's display and contrast modes to these variables.
+Hosts that omit a contrast mode use standard contrast.
 
 `NotionTokenScopeProps` has one required `children` prop.
 
-The stylesheet is scoped rather than installed globally. Render portals inside `<NotionTokenScope>`, or wrap the portal container in another scope. Framework-neutral renderers can read the current appearance with `customBlock.getTheme()` and `customBlock.getContrastMode()`; see [Block Location & Appearance](./docs/block-location.md).
+The CSS variables apply within the scope, not globally.
+Place portal containers inside `<NotionTokenScope>`, or wrap the portal content in another `<NotionTokenScope>`.
+Framework-neutral renderers can read the current appearance with `customBlock.getTheme()` and `customBlock.getContrastMode()`.
+See [Block location and appearance](./docs/block-location.md).
 
 ## Reference
 
-API surface, one page per category. Import framework-neutral APIs from `@notionhq/custom-blocks`; import React hooks and components from `@notionhq/custom-blocks/react`. Hover docs in your editor cover the per-field detail; these pages cover usage shape and the gotchas.
+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/block-location.md`](./docs/block-location.md) — `useBlockId`, `useParent`, `usePage`, `useTheme`, and `useContrastMode`. Where the block sits and how to read the host's appearance.
+- [`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/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.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

@@ -725,17 +725,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 +759,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 +787,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/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/sandboxClient.d.ts

@@ -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,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"}

package/dist/bridge/sandboxClient.js

@@ -1,6 +1,7 @@
 import { getDataSourceQueryView as getDataSourceQueryViewWithBridge, } from "./hostState.js";
 import { SandboxBridge } from "./SandboxBridge.js";
 let bridge;
+let didWarnAboutPagesDelete = false;
 function getBridge() {
     if (!bridge) {
         bridge = new SandboxBridge();
@@ -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/react/NotionCustomBlock.js

@@ -75,7 +75,7 @@ export function NotionCustomBlock({ children, timeoutMs, fallback = null, errorF
         if (host.status !== "initialized") {
             return _jsx(_Fragment, { children: fallback });
         }
-        return (_jsxs(_Fragment, { children: [_jsx("div", { role: "status", className: "custom-blocks-standalone-banner", children: "Host not detected \u2014 running in standalone preview. Try `ntn customblocks dev` to run the block in a local development environment." }), children] }));
+        return (_jsxs(_Fragment, { children: [_jsx("div", { role: "status", className: "custom-blocks-standalone-banner", children: "Host not detected \u2014 running in standalone preview. Try `ntn workers customblocks dev` to run the block in a local development environment." }), children] }));
     }
     if (!init.isLoaded) {
         return _jsx(_Fragment, { children: fallback });

package/dist/types.d.ts

@@ -60,11 +60,18 @@ export type NotionDataSourcePage = {
      * keys to raw property IDs before sending the bridge message to the host.
      */
     update: (args: NotionDataSourcePageUpdateArgs) => Promise<UpdatePageResult>;
+    /** Archives this page. Shorthand for update({ is_archived: true }). */
+    archive: () => Promise<UpdatePageResult>;
+    /** Unarchives this page. Shorthand for update({ is_archived: false }). */
+    unarchive: () => Promise<UpdatePageResult>;
 };
 export type NotionDataSourcePageUpdateArgs = {
     properties?: NotionPagePropertyInputMap;
     icon?: NotionPageIcon;
     cover?: NotionPageCover;
+    /** Whether to archive this page. Takes precedence over archived. */
+    is_archived?: boolean;
+    /** @deprecated Use is_archived instead. */
     archived?: boolean;
 };
 /**
@@ -217,7 +224,12 @@ export type CreatePageInput = CreatePageArgs;
  * The result of a `sdk.pages.create` API call.
  */
 export type CreatePageResult = BridgeMessagePayload<CreatePageResultMessage, CustomBlockCreatePageErrorInfo>;
-export type UpdatePageArgs = Omit<UpdatePageMessage, "type" | "requestId">;
+export type UpdatePageArgs = Omit<UpdatePageMessage, "type" | "requestId" | "archived"> & {
+    /** Whether to archive this page. Takes precedence over archived. */
+    is_archived?: boolean;
+    /** @deprecated Use is_archived instead. */
+    archived?: boolean;
+};
 /**
  * @deprecated Use `UpdatePageArgs` instead.
  *
@@ -229,7 +241,7 @@ export type UpdatePageInput = UpdatePageArgs;
  */
 export type GetPageResult = BridgeMessagePayload<GetPageResultMessage, CustomBlockGetPageErrorInfo>;
 /**
- * Result of `sdk.pages.update` / `sdk.pages.delete`.
+ * Result of `sdk.pages.update`, `sdk.pages.archive`, and `sdk.pages.unarchive`.
  */
 export type UpdatePageResult = BridgeMessagePayload<UpdatePageResultMessage, CustomBlockUpdatePageErrorInfo>;
 export type ListUsersArgs = Omit<ListUsersMessage, "type" | "requestId">;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4DAA4D,CAAA;AACxG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iEAAiE,CAAA;AAC5G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gEAAgE,CAAA;AAC1G,OAAO,KAAK,EACX,kBAAkB,EAClB,YAAY,EACZ,MAAM,yCAAyC,CAAA;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAA;AAC9F,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yDAAyD,CAAA;AACvG,OAAO,KAAK,EACX,uBAAuB,EACvB,8BAA8B,EAC9B,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EACX,2BAA2B,EAC3B,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,2BAA2B,EAC3B,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,6BAA6B,EAC7B,gBAAgB,EAChB,sBAAsB,EACtB,MAAM,wDAAwD,CAAA;AAC/D,OAAO,KAAK,EACX,iCAAiC,EACjC,iCAAiC,EACjC,6BAA6B,EAC7B,+BAA+B,EAC/B,+BAA+B,EAC/B,6BAA6B,EAC7B,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,oEAAoE,CAAA;AAC7H,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,8BAA8B,EAC9B,uBAAuB,EACvB,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EACX,eAAe,EACf,cAAc,EACd,uBAAuB,EACvB,MAAM,gDAAgD,CAAA;AAEvD,YAAY,EAAE,oBAAoB,EAAE,MAAM,4CAA4C,CAAA;AACtF,YAAY,EACX,kBAAkB,EAClB,aAAa,GACb,MAAM,yCAAyC,CAAA;AAChD,YAAY,EACX,UAAU,EACV,YAAY,EACZ,cAAc,GACd,MAAM,gDAAgD,CAAA;AACvD,YAAY,EACX,8BAA8B,EAC9B,2BAA2B,EAC3B,2BAA2B,EAC3B,6BAA6B,EAC7B,mCAAmC,EACnC,8BAA8B,GAC9B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,4BAA4B,GACvC,uBAAuB,SAAS,MAAM,aAAa,GAChD,aAAa,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GACnC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,KAAK,GACN,KAAK,CAAA;AAET,MAAM,MAAM,0BAA0B,GAAG;IACxC,CAAC,eAAe,EAAE,MAAM,GAAG,4BAA4B,CAAA;CACvD,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,EAAE,EAAE,YAAY,CAAA;IAEhB,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,cAAc,EAAE;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAA;KAAE,CAAA;IAC3E;;;OAGG;IACH,eAAe,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAA;KAAE,CAAA;IACrE;;;OAGG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,8BAA8B,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAA;CAC3E,CAAA;AAED,MAAM,MAAM,8BAA8B,GAAG;IAC5C,UAAU,CAAC,EAAE,0BAA0B,CAAA;IACvC,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,+BAA+B,GAAG,8BAA8B,CAAA;AAE5E;;;;GAIG;AACH,MAAM,MAAM,gCAAgC,GAAG,gBAAgB,CAAA;AAE/D,MAAM,MAAM,kCAAkC,GAAG,6BAA6B,CAAA;AAC9E,MAAM,MAAM,oCAAoC,GAC/C,+BAA+B,CAAA;AAChC,MAAM,MAAM,sCAAsC,GACjD,iCAAiC,CAAA;AAClC,MAAM,MAAM,oCAAoC,GAC/C,+BAA+B,CAAA;AAChC,MAAM,MAAM,sCAAsC,GACjD,iCAAiC,CAAA;AAClC,MAAM,MAAM,kCAAkC,GAAG,6BAA6B,CAAA;AAE9E,MAAM,MAAM,+BAA+B,GACxC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GACnC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,KAAK,CAAA;CAAE,CAAA;AAEtC,MAAM,MAAM,8BAA8B,GAAG,+BAA+B,GAC3E,CACG;IAAE,KAAK,EAAE,kCAAkC,CAAA;CAAE,GAC7C;IAAE,SAAS,EAAE,kCAAkC,CAAA;CAAE,GACjD;IAAE,GAAG,EAAE,kCAAkC,CAAA;CAAE,GAC3C;IAAE,KAAK,EAAE,kCAAkC,CAAA;CAAE,GAC7C;IAAE,YAAY,EAAE,kCAAkC,CAAA;CAAE,GACpD;IAAE,MAAM,EAAE,oCAAoC,CAAA;CAAE,GAChD;IAAE,QAAQ,EAAE,sCAAsC,CAAA;CAAE,GACpD;IAAE,MAAM,EAAE,oCAAoC,CAAA;CAAE,GAChD;IAAE,YAAY,EAAE,sCAAsC,CAAA;CAAE,GACxD;IAAE,MAAM,EAAE,oCAAoC,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,kCAAkC,CAAA;CAAE,CAC9C,CAAA;AAEF,MAAM,MAAM,oBAAoB,GAAG,+BAA+B,GAAG;IACpE,SAAS,EAAE,WAAW,GAAG,YAAY,CAAA;CACrC,CAAA;AAED,MAAM,MAAM,sBAAsB,GAC/B,8BAA8B,GAC9B;IAAE,GAAG,EAAE,8BAA8B,EAAE,CAAA;CAAE,CAAA;AAE5C;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG;IACjC,KAAK,EAAE,oBAAoB,EAAE,CAAA;IAC7B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAA;IACzC;;;OAGG;IACH,mBAAmB,EAAE;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,oBAAoB,CAAA;KAAE,CAAA;IACnE;;;OAGG;IACH,gBAAgB,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAA;IACvD;;;;OAIG;IACH,oBAAoB,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAAA;KAAE,CAAA;IACzE,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,mCAAmC,CAAA;CAC3C,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IAClC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,sBAAsB,CAAA;IAC/B;;OAEG;IACH,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAA;CAC9B,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,gBAAgB,GACzB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,cAAc,EAAE,kBAAkB,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3C;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE,gBAAgB,CAAA;IACxB,UAAU,EAAE,0BAA0B,CAAA;IACtC,QAAQ,CAAC,EAAE,wBAAwB,CAAA;CACnC,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,CAAA;AAE5C;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,CAClD,uBAAuB,EACvB,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,WAAW,CAAC,CAAA;AAE1E;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,CAAA;AAE5C;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,oBAAoB,CAC/C,oBAAoB,EACpB,2BAA2B,CAC3B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,CAClD,uBAAuB,EACvB,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,WAAW,CAAC,CAAA;AAExE;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,CAAA;AAE1C,MAAM,MAAM,eAAe,GAAG,oBAAoB,CACjD,sBAAsB,EACtB,6BAA6B,CAC7B,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,oBAAoB,CAC/C,oBAAoB,EACpB,2BAA2B,CAC3B,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/version.js

@@ -4,4 +4,4 @@
  *
  * WARNING: Generated during SDK publish. Do not edit in the published package.
  */
-export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.41"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.43"

package/docs/block-location.md

@@ -118,7 +118,7 @@ const theme = customBlock.getTheme();
 ```
 
 ```tsx
-import { usePage, useTheme } from "@notionhq/custom-blocks";
+import { usePage, useTheme } from "@notionhq/custom-blocks/react";
 
 export function Header() {
   const page = usePage();
@@ -137,4 +137,4 @@ function useContrastMode(): NotionContrastMode; // "standard" | "high"
 
 For non-React renderers, use `customBlock.getContrastMode()` after `initCustomBlock()` resolves.
 
-For React apps, `<NotionTokenScope>` applies both appearance values to the bundled Notion design tokens automatically. Setup and portal guidance live in the [package README](../README.md#notion-design-tokens).
+For React apps, `<NotionTokenScope>` applies both appearance values to the bundled Notion CSS variables automatically.

package/docs/data-sources.md

@@ -10,7 +10,7 @@ At runtime, your code references the semantic key and the SDK handles the lookup
 
 ## Pages within a data source
 
-Each row returned by `useDataSource` is a `NotionDataSourcePage` — `{ id, propertiesById, propertiesByKey, update }`. Read property values through either of the two views:
+Each row returned by `useDataSource` is a `NotionDataSourcePage` — `{ id, propertiesById, propertiesByKey, update, archive, unarchive }`. Read property values through either of the two views:
 
 - `propertiesByKey[key]` — keyed by the semantic property keys you declared in the manifest.
 - `propertiesById[propertyId]` — keyed by the raw Notion property ID.
@@ -32,7 +32,14 @@ await row.update({
 
 Property values can be keyed by **either** semantic keys or raw IDs. The SDK resolves semantic keys to IDs before sending the request.
 
-Use `row.update(...)` whenever you already have a row in hand. For pages you don't have a row for (e.g. you only have a `pageId`), drop down to the top-level [`pages` API](./pages.md) — it covers create / get / update / delete and accepts raw property IDs only.
+Use `row.update(...)` whenever you already have a row in hand. For pages you don't have a row for (e.g. you only have a `pageId`), drop down to the top-level [`pages` API](./pages.md) — it covers create / get / update / archive / unarchive and accepts raw property IDs only.
+
+### Archiving and unarchiving a row
+
+`row.archive()` is shorthand for calling `row.update({ is_archived: true })`.
+`row.unarchive()` is shorthand for calling `row.update({ is_archived: false })`.
+Both methods return an `UpdatePageResult`.
+Use `row.update` to change archive status and other fields in one request.
 
 ## API
 
@@ -137,9 +144,10 @@ renderManifest(customBlock.getManifest());
 
 ## Example: querying a data source
 
-A typical data-driven view picks a key, calls `useDataSource`, schema-checks the rows, and surfaces a setup hint when the mapped collection is missing the expected fields:
+This example calls `useDataSource` with a declared key. It validates each row’s values before rendering:
 
 ```tsx
+import { useState } from "react";
 import type { NotionDataSourcePage } from "@notionhq/custom-blocks";
 import { useDataSource } from "@notionhq/custom-blocks/react";
 
@@ -163,10 +171,7 @@ export function ScoreList() {
   const displayItems = items.filter(isComplete);
   if (displayItems.length === 0) {
     return (
-      <div>
-        Map a data source with key <code>{KEY}</code> exposing <code>name</code>{" "}
-        (text) and <code>score</code> (number).
-      </div>
+      <div>No rows have both a text name and a finite score.</div>
     );
   }
 
@@ -198,9 +203,9 @@ export function ScoreList() {
 
 ### Rows & values
 
-- `NotionDataSource` — a resolved data source: semantic key, `collectionSchema`, `propertyIdsByKey`, `propertySchemasById`.
-- `NotionDataSourcePage` — a single row exposed to app code: `{ id, propertiesById, propertiesByKey, update }`.
-- `NotionDataSourceValue` — the discriminated union of values that can appear inside `propertiesById[propertyId]`. Date values branch into the `NotionDateValue` union below.
+- `NotionDataSource` — a resolved data source: semantic key, optional `collectionSchema`, `propertyIdsByKey`, and `propertySchemasById`.
+- `NotionDataSourcePage` — a single row exposed to app code: `{ id, propertiesById, propertiesByKey, update, archive, unarchive }`.
+- `NotionDataSourceValue` — the value union for `propertiesById` and `propertiesByKey`.
 - `NotionDataSourcePageUpdateArgs` / `UpdatePageResult` — arguments and result for the per-page `update` helper.
 - `NotionDataSourcePageUpdateInput` — deprecated alias for `NotionDataSourcePageUpdateArgs`.
 - `NotionDataSourcePageUpdateResult` — deprecated alias for `UpdatePageResult`.

package/docs/deployment.md

@@ -7,9 +7,11 @@ A custom block manifest describes the data sources a block requires, including t
 - **Deployed** — deploying persists the manifest on the block's definition record in Notion. The host reads it from there and sends it to the SDK during initialization.
 - **Local development** — the dev shell extracts the same worker declaration at runtime and serves the selected block's manifest dynamically at `/manifest`.
 
+Notion reconciles custom block definitions by their Worker capability keys during deployment.
+
 ## Local development
 
-Run `ntn customblocks dev` from a worker. It builds the worker, extracts its custom block declarations, starts one localhost Vite server per block, and renders them in the mock host at http://localhost:9873.
+Run `ntn workers customblocks dev` from a worker. It builds the worker, extracts its custom block declarations, starts one localhost Vite server per block, and renders them in the mock host at http://localhost:9873.
 
 At startup, the SDK fetches the page-relative `manifest` path only when the bundle's hostname is exactly `localhost`, then forwards the response in `connect`. On every other hostname, the SDK skips this fetch and relies on the host-provided manifest from `init`.
 

package/docs/pages.md

@@ -97,7 +97,7 @@ Read `in_trash` on a page or data source row. It is `true` when the page or an a
 
 ## Updating pages
 
-`pages.update` writes back to a page. The optional fields (`properties`, `icon`, `cover`, `archived`) are independent — supply only what you want to change:
+`pages.update` writes back to a page. The optional fields (`properties`, `icon`, `cover`, `is_archived`) are independent — supply only what you want to change:
 
 ```ts
 const result = await pages.update({
@@ -115,17 +115,27 @@ const result = await pages.update({
 
 The `properties` map (a `NotionPagePropertyWriteMap`) is keyed by **raw Notion property ID**, and each value must repeat that ID as its own `id` field — semantic data source keys aren't accepted here. To update a row by configured custom-block key without writing out the raw IDs, use the `update` helper on the row returned from `useDataSource` instead; the SDK handles the key → ID resolution for you.
 
-If you call `pages.update` with no fields to change, it short-circuits and resolves with `{ status: "error", error: { code: "invalid_page_update", message: "updatePage requires at least one of: properties, icon, cover, archived.", isRetryable: false } }` — no request is sent.
+If you call `pages.update` with no fields to change, it short-circuits and resolves with `{ status: "error", error: { code: "invalid_page_update", message: "updatePage requires at least one property.", isRetryable: false } }` — no request is sent.
 
-## Deleting (archiving) pages
+## Archiving and unarchiving pages
 
-`pages.delete(pageId)` archives the page. It does not move the page to Trash.
+`pages.archive(pageId)` archives a page. `pages.unarchive(pageId)` removes its archive state.
 
 ```ts
-await pages.delete(pageId);
+const result = await pages.archive(pageId);
+if (result.status === "error") {
+  console.error(result.error.message);
+}
+
+const restored = await pages.unarchive(pageId);
+if (restored.status === "error") {
+  console.error(restored.error.message);
+}
 ```
 
-To unarchive a page, call `pages.update({ pageId, archived: false })`.
+`pages.archive` is shorthand for calling `pages.update` with `is_archived: true`.
+`pages.unarchive` is shorthand for calling `pages.update` with `is_archived: false`.
+Both methods return an `UpdatePageResult`.
 
 ## Icons, covers, and file uploads
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.1.41",
+	"version": "0.1.43",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {

package/src/bridge/SandboxBridge.ts

@@ -923,20 +923,22 @@ export class SandboxBridge {
 	}
 
 	updatePage(args: UpdatePageArgs): Promise<UpdatePageResult> {
+		// 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,
 					},
 				})
@@ -958,8 +960,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)
 		})
@@ -993,7 +995,7 @@ export class SandboxBridge {
 			properties: resolvedProperties?.properties,
 			icon: pageUpdateArgs.icon,
 			cover: pageUpdateArgs.cover,
-			archived: pageUpdateArgs.archived,
+			is_archived: pageUpdateArgs.is_archived ?? pageUpdateArgs.archived,
 		})
 	}
 

package/src/bridge/hostState.ts

@@ -139,18 +139,21 @@ export function getDataSourceQueryView(
 			propertiesByKey[key] =
 				propertyId === undefined ? undefined : entry.propertiesById[propertyId]
 		}
+		const update = (args: NotionDataSourcePageUpdateArgs) =>
+			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 }),
 		}
 	})
 

package/src/bridge/sandboxClient.ts

@@ -21,6 +21,7 @@ import type { ManifestLoadResult } from "./loadManifest.js"
 import { type MessageLogEntry, SandboxBridge } from "./SandboxBridge.js"
 
 let bridge: SandboxBridge | undefined
+let didWarnAboutPagesDelete = false
 
 function getBridge(): SandboxBridge {
 	if (!bridge) {
@@ -134,10 +135,31 @@ export const pages = {
 	},
 
 	/**
-	 * Soft-delete a page by archiving it.
+	 * Archives a page.
+	 */
+	archive: (pageId: NotionPageId): Promise<UpdatePageResult> => {
+		return getBridge().updatePage({ pageId, is_archived: true })
+	},
+
+	/**
+	 * Unarchives a page.
+	 */
+	unarchive: (pageId: NotionPageId): Promise<UpdatePageResult> => {
+		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: NotionPageId): Promise<UpdatePageResult> => {
-		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/src/react/NotionCustomBlock.tsx

@@ -119,7 +119,7 @@ export function NotionCustomBlock({
 		return (
 			<>
 				<div role="status" className="custom-blocks-standalone-banner">
-					Host not detected — running in standalone preview. Try `ntn
+					Host not detected — running in standalone preview. Try `ntn workers
 					customblocks dev` to run the block in a local development environment.
 				</div>
 				{children}

package/src/types.ts

@@ -106,12 +106,20 @@ export type NotionDataSourcePage = {
 	 * keys to raw property IDs before sending the bridge message to the host.
 	 */
 	update: (args: NotionDataSourcePageUpdateArgs) => Promise<UpdatePageResult>
+	/** Archives this page. Shorthand for update({ is_archived: true }). */
+	archive: () => Promise<UpdatePageResult>
+	/** Unarchives this page. Shorthand for update({ is_archived: false }). */
+	unarchive: () => Promise<UpdatePageResult>
 }
 
 export type NotionDataSourcePageUpdateArgs = {
 	properties?: NotionPagePropertyInputMap
 	icon?: NotionPageIcon
 	cover?: NotionPageCover
+	/** Whether to archive this page. Takes precedence over archived. */
+	is_archived?: boolean
+	/** @deprecated Use is_archived instead. */
+	// TODO(custom-blocks): Remove archived when upgrading to bridge protocol v4.
 	archived?: boolean
 }
 
@@ -260,7 +268,16 @@ export type CreatePageResult = BridgeMessagePayload<
 	CustomBlockCreatePageErrorInfo
 >
 
-export type UpdatePageArgs = Omit<UpdatePageMessage, "type" | "requestId">
+export type UpdatePageArgs = Omit<
+	UpdatePageMessage,
+	"type" | "requestId" | "archived"
+> & {
+	/** Whether to archive this page. Takes precedence over archived. */
+	is_archived?: boolean
+	/** @deprecated Use is_archived instead. */
+	// TODO(custom-blocks): Remove archived when upgrading to bridge protocol v4.
+	archived?: boolean
+}
 
 /**
  * @deprecated Use `UpdatePageArgs` instead.
@@ -278,7 +295,7 @@ export type GetPageResult = BridgeMessagePayload<
 >
 
 /**
- * Result of `sdk.pages.update` / `sdk.pages.delete`.
+ * Result of `sdk.pages.update`, `sdk.pages.archive`, and `sdk.pages.unarchive`.
  */
 export type UpdatePageResult = BridgeMessagePayload<
 	UpdatePageResultMessage,