@notionhq/custom-blocks-host 0.3.3 → 0.3.5

package/dist/protocol/messages/hostToSandbox.js

@@ -8,16 +8,14 @@ import { getUserResultMessageSchema } from "./getUser.js";
 import { initMessageSchema } from "./init.js";
 import { invalidSandboxMessageSchema } from "./invalidSandboxMessage.js";
 import { listUsersResultMessageSchema } from "./listUsers.js";
+import { openExternalUrlResultMessageSchema } from "./openExternalUrl.js";
 import { openPageResultMessageSchema } from "./openPage.js";
 import { pageChangedMessageSchema } from "./pageChanged.js";
 import { parentChangedMessageSchema } from "./parentChanged.js";
-import { queryDataSourceResultMessageSchema } from "./queryDataSourceResult.js";
+import { queryDataSourceResultMessageLegacySchema, queryDataSourceResultMessageSchema, } from "./queryDataSourceResult.js";
 import { themeChangedMessageSchema } from "./themeChanged.js";
 import { updatePageResultMessageSchema } from "./updatePageResult.js";
-/**
- * Discriminated union of every message the host is allowed to send the sandbox.
- */
-export const hostToSandboxMessageSchema = v.variant("type", [
+const baseHostToSandboxMessageSchema = v.variant("type", [
     initMessageSchema,
     themeChangedMessageSchema,
     contrastModeChangedMessageSchema,
@@ -25,12 +23,23 @@ export const hostToSandboxMessageSchema = v.variant("type", [
     pageChangedMessageSchema,
     currentUserChangedMessageSchema,
     dataSourcesChangedMessageSchema,
-    queryDataSourceResultMessageSchema,
     createPageResultMessageSchema,
     getPageResultMessageSchema,
     getUserResultMessageSchema,
     listUsersResultMessageSchema,
     openPageResultMessageSchema,
+    openExternalUrlResultMessageSchema,
     updatePageResultMessageSchema,
     invalidSandboxMessageSchema,
 ]);
+export const hostToSandboxMessageSchema = v.variant("type", [
+    ...baseHostToSandboxMessageSchema.options,
+    queryDataSourceResultMessageSchema,
+]);
+/**
+ * Discriminated union of every message the host is allowed to send the sandbox.
+ */
+export const hostToSandboxMessageLegacySchema = v.variant("type", [
+    ...baseHostToSandboxMessageSchema.options,
+    queryDataSourceResultMessageLegacySchema,
+]);

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

@@ -0,0 +1,32 @@
+import * as v from "valibot";
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
+export declare const customBlockOpenExternalUrlErrorCodeSchema: v.StringSchema<undefined>;
+export type CustomBlockOpenExternalUrlErrorCode = CustomBlockErrorCode<"user_decline" | "pending_navigation" | "invalid_url">;
+export type CustomBlockOpenExternalUrlErrorInfo = CustomBlockErrorInfo<CustomBlockOpenExternalUrlErrorCode>;
+export declare const customBlockOpenExternalUrlErrorInfoSchema: v.ObjectSchema<{
+    readonly code: v.StringSchema<undefined>;
+    readonly message: v.StringSchema<undefined>;
+    readonly isRetryable: v.BooleanSchema<undefined>;
+}, undefined>;
+/** Sandbox -> host: request approval to open an external URL. */
+export declare const openExternalUrlMessageSchema: v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"openExternalUrl", undefined>;
+    readonly requestId: v.StringSchema<undefined>;
+    readonly url: v.StringSchema<undefined>;
+}, undefined>;
+export type OpenExternalUrlMessage = v.InferOutput<typeof openExternalUrlMessageSchema>;
+export declare const openExternalUrlResultMessageSchema: v.VariantSchema<"status", [v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"openExternalUrlResult", undefined>;
+    readonly requestId: v.StringSchema<undefined>;
+    readonly status: v.LiteralSchema<"success", undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"openExternalUrlResult", undefined>;
+    readonly requestId: v.StringSchema<undefined>;
+    readonly status: v.LiteralSchema<"error", undefined>;
+    readonly error: v.ObjectSchema<{
+        readonly code: v.StringSchema<undefined>;
+        readonly message: v.StringSchema<undefined>;
+        readonly isRetryable: v.BooleanSchema<undefined>;
+    }, undefined>;
+}, undefined>], undefined>;
+export type OpenExternalUrlResultMessage = v.InferOutput<typeof openExternalUrlResultMessageSchema>;

package/dist/protocol/messages/openExternalUrl.js

@@ -0,0 +1,26 @@
+import * as v from "valibot";
+export const customBlockOpenExternalUrlErrorCodeSchema = v.string();
+export const customBlockOpenExternalUrlErrorInfoSchema = v.object({
+    code: customBlockOpenExternalUrlErrorCodeSchema,
+    message: v.string(),
+    isRetryable: v.boolean(),
+});
+/** Sandbox -> host: request approval to open an external URL. */
+export const openExternalUrlMessageSchema = v.object({
+    type: v.literal("openExternalUrl"),
+    requestId: v.string(),
+    url: v.string(),
+});
+export const openExternalUrlResultMessageSchema = v.variant("status", [
+    v.object({
+        type: v.literal("openExternalUrlResult"),
+        requestId: v.string(),
+        status: v.literal("success"),
+    }),
+    v.object({
+        type: v.literal("openExternalUrlResult"),
+        requestId: v.string(),
+        status: v.literal("error"),
+        error: customBlockOpenExternalUrlErrorInfoSchema,
+    }),
+]);

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

@@ -12,6 +12,179 @@ export declare const customBlockQueryDataSourceErrorInfoSchema: v.ObjectSchema<{
  * Message sent by the host to update a `queryDataSource` subscription.
  */
 export declare const queryDataSourceResultMessageSchema: v.VariantSchema<"status", [v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"queryDataSourceResult", undefined>;
+    readonly subscriptionId: v.StringSchema<undefined>;
+    readonly status: v.LiteralSchema<"success", undefined>;
+    readonly items: v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
+        readonly is_archived: v.BooleanSchema<undefined>;
+        readonly in_trash: v.BooleanSchema<undefined>;
+        readonly properties: v.RecordSchema<v.StringSchema<undefined>, v.OptionalSchema<v.VariantSchema<"type", [v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"title", undefined>;
+            readonly title: v.ArraySchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"rich_text", undefined>;
+            readonly rich_text: v.ArraySchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"number", undefined>;
+            readonly number: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"url", undefined>;
+            readonly url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"email", undefined>;
+            readonly email: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"phone_number", undefined>;
+            readonly phone_number: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"checkbox", undefined>;
+            readonly checkbox: v.BooleanSchema<undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"select", undefined>;
+            readonly select: v.NullableSchema<v.UnionSchema<[v.ObjectSchema<{
+                readonly id: v.StringSchema<undefined>;
+                readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly color: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly description: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly name: v.StringSchema<undefined>;
+                readonly id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly color: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly description: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            }, undefined>], undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"status", undefined>;
+            readonly status: v.NullableSchema<v.UnionSchema<[v.ObjectSchema<{
+                readonly id: v.StringSchema<undefined>;
+                readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly color: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly description: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly name: v.StringSchema<undefined>;
+                readonly id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly color: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly description: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            }, undefined>], undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"multi_select", undefined>;
+            readonly multi_select: v.ArraySchema<v.UnionSchema<[v.ObjectSchema<{
+                readonly id: v.StringSchema<undefined>;
+                readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly color: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly description: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly name: v.StringSchema<undefined>;
+                readonly id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly color: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly description: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            }, undefined>], undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"date", undefined>;
+            readonly date: v.NullableSchema<v.ObjectSchema<{
+                readonly start: v.StringSchema<undefined>;
+                readonly end: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+                readonly time_zone: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            }, undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"people", undefined>;
+            readonly people: v.ArraySchema<v.UnionSchema<[v.ObjectSchema<{
+                readonly object: v.OptionalSchema<v.LiteralSchema<"user", undefined>, undefined>;
+                readonly id: v.StringSchema<undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly object: v.LiteralSchema<"group", undefined>;
+                readonly id: v.StringSchema<undefined>;
+                readonly name: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            }, undefined>], undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"relation", undefined>;
+            readonly has_more: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly relation: v.ArraySchema<v.ObjectSchema<{
+                readonly id: v.StringSchema<undefined>;
+            }, undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"files", undefined>;
+            readonly files: v.ArraySchema<v.UnionSchema<[v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"external", undefined>;
+                readonly name: v.StringSchema<undefined>;
+                readonly external: v.ObjectSchema<{
+                    readonly url: v.StringSchema<undefined>;
+                }, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"file", undefined>;
+                readonly name: v.StringSchema<undefined>;
+                readonly file: v.ObjectSchema<{
+                    readonly url: v.StringSchema<undefined>;
+                    readonly expiry_time: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>;
+            }, undefined>], undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"place", undefined>;
+            readonly place: v.NullableSchema<v.ObjectSchema<{
+                readonly lat: v.NumberSchema<undefined>;
+                readonly lon: v.NumberSchema<undefined>;
+                readonly name: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+                readonly address: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+                readonly aws_place_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+                readonly google_place_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            }, undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"created_time", undefined>;
+            readonly created_time: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"last_edited_time", undefined>;
+            readonly last_edited_time: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"created_by", undefined>;
+            readonly created_by: v.NullableSchema<v.ObjectSchema<{
+                readonly id: v.StringSchema<undefined>;
+                readonly table: v.PicklistSchema<["notion_user", "bot", "organization_bot"], undefined>;
+                readonly spaceId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"last_edited_by", undefined>;
+            readonly last_edited_by: v.NullableSchema<v.ObjectSchema<{
+                readonly id: v.StringSchema<undefined>;
+                readonly table: v.PicklistSchema<["notion_user", "bot", "organization_bot"], undefined>;
+                readonly spaceId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly type: v.LiteralSchema<"last_visited_time", undefined>;
+            readonly last_visited_time: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>], undefined>, undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly hasMore: v.BooleanSchema<undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"queryDataSourceResult", undefined>;
+    readonly subscriptionId: v.StringSchema<undefined>;
+    readonly status: v.LiteralSchema<"error", undefined>;
+    readonly error: v.ObjectSchema<{
+        readonly code: v.StringSchema<undefined>;
+        readonly message: v.StringSchema<undefined>;
+        readonly isRetryable: v.BooleanSchema<undefined>;
+    }, undefined>;
+}, undefined>], undefined>;
+export declare const queryDataSourceResultMessageLegacySchema: v.VariantSchema<"status", [v.ObjectSchema<{
     readonly type: v.LiteralSchema<"queryDataSourceResult", undefined>;
     readonly subscriptionId: v.StringSchema<undefined>;
     readonly status: v.LiteralSchema<"success", undefined>;
@@ -250,3 +423,4 @@ export declare const queryDataSourceResultMessageSchema: v.VariantSchema<"status
     }, undefined>;
 }, undefined>], undefined>;
 export type QueryDataSourceResultMessage = v.InferOutput<typeof queryDataSourceResultMessageSchema>;
+export type QueryDataSourceResultMessageLegacy = v.InferOutput<typeof queryDataSourceResultMessageLegacySchema>;

package/dist/protocol/messages/queryDataSourceResult.js

@@ -12,6 +12,21 @@ export const customBlockQueryDataSourceErrorInfoSchema = v.object({
  * Message sent by the host to update a `queryDataSource` subscription.
  */
 export const queryDataSourceResultMessageSchema = v.variant("status", [
+    v.object({
+        type: v.literal("queryDataSourceResult"),
+        subscriptionId: v.string(),
+        status: v.literal("success"),
+        items: v.array(notionDataSourcePageBridgeSchema),
+        hasMore: v.boolean(),
+    }),
+    v.object({
+        type: v.literal("queryDataSourceResult"),
+        subscriptionId: v.string(),
+        status: v.literal("error"),
+        error: customBlockQueryDataSourceErrorInfoSchema,
+    }),
+]);
+export const queryDataSourceResultMessageLegacySchema = v.variant("status", [
     v.object({
         type: v.literal("queryDataSourceResult"),
         subscriptionId: v.string(),

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

@@ -759,6 +759,10 @@ export declare const sandboxToHostMessageSchema: v.VariantSchema<"type", [v.Vari
     readonly requestId: v.StringSchema<undefined>;
     readonly pageId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
     readonly mode: v.PicklistSchema<["side_peek", "center_peek"], undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"openExternalUrl", undefined>;
+    readonly requestId: v.StringSchema<undefined>;
+    readonly url: v.StringSchema<undefined>;
 }, undefined>, v.ObjectSchema<{
     readonly type: v.LiteralSchema<"updatePage", undefined>;
     readonly requestId: v.StringSchema<undefined>;

package/dist/protocol/messages/sandboxToHost.js

@@ -6,6 +6,7 @@ import { getUserMessageSchema } from "./getUser.js";
 import { initResultMessageSchema } from "./initResult.js";
 import { invalidHostMessageSchema } from "./invalidHostMessage.js";
 import { listUsersMessageSchema } from "./listUsers.js";
+import { openExternalUrlMessageSchema } from "./openExternalUrl.js";
 import { openPageMessageSchema } from "./openPage.js";
 import { queryDataSourceMessageSchema } from "./queryDataSource.js";
 import { resizeMessageSchema } from "./resize.js";
@@ -25,6 +26,7 @@ export const sandboxToHostMessageSchema = v.variant("type", [
     getUserMessageSchema,
     listUsersMessageSchema,
     openPageMessageSchema,
+    openExternalUrlMessageSchema,
     updatePageMessageSchema,
     resizeMessageSchema,
     invalidHostMessageSchema,

package/package.json

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

package/src/createCustomBlockHost.ts

@@ -13,6 +13,10 @@ import {
 	initMessageSchema,
 } from "@notionhq/custom-blocks-protocol/messages/init.js"
 import type { InvalidSandboxMessage } from "@notionhq/custom-blocks-protocol/messages/invalidSandboxMessage.js"
+import type {
+	OpenExternalUrlMessage,
+	OpenExternalUrlResultMessage,
+} from "@notionhq/custom-blocks-protocol/messages/openExternalUrl.js"
 import type { QueryDataSourceMessage } from "@notionhq/custom-blocks-protocol/messages/queryDataSource.js"
 import type {
 	CustomBlockQueryDataSourceErrorInfo,
@@ -45,6 +49,7 @@ import type {
 	CustomBlockHostPrepareInitialState,
 } from "./lifecycle/types.js"
 import { customBlockHostInitialStateSchema } from "./lifecycle/types.js"
+import { parseExternalUrl } from "./messages/parseExternalUrl.js"
 import { createSandboxMessageRouter } from "./messages/sandboxMessageRouter.js"
 import type {
 	CustomBlockHostFailure,
@@ -143,6 +148,9 @@ export function createCustomBlockHost(
 		MIN_HOST_SUPPORTED_BRIDGE_PROTOCOL_VERSION,
 	)
 
+	const navigationAbortController = new AbortController()
+	let pendingOpenExternalUrlRequestId: string | undefined
+
 	type HostStateUpdates = Partial<
 		Omit<CustomBlockHostInitialState, "blockId" | "manifest">
 	>
@@ -304,6 +312,75 @@ export function createCustomBlockHost(
 		flushPendingHostStateChanges()
 	}
 
+	async function handleOpenExternalUrl(message: OpenExternalUrlMessage) {
+		if (
+			handlers.openExternalUrl === undefined ||
+			navigationAbortController.signal.aborted
+		) {
+			return
+		}
+		if (pendingOpenExternalUrlRequestId === message.requestId) {
+			return
+		}
+		if (pendingOpenExternalUrlRequestId !== undefined) {
+			const pendingResult: OpenExternalUrlResultMessage = {
+				type: "openExternalUrlResult",
+				requestId: message.requestId,
+				status: "error",
+				error: {
+					code: "pending_navigation",
+					message: "Another external navigation request is pending.",
+					isRetryable: true,
+				},
+			}
+			sendInitializedMessage(pendingResult)
+			return
+		}
+		const url = parseExternalUrl(message.url)
+		if (url === undefined) {
+			const invalidResult: OpenExternalUrlResultMessage = {
+				type: "openExternalUrlResult",
+				requestId: message.requestId,
+				status: "error",
+				error: {
+					code: "invalid_url",
+					message:
+						"Only valid HTTP or HTTPS URLs without credentials, up to 2,048 characters, can be opened.",
+					isRetryable: false,
+				},
+			}
+			sendInitializedMessage(invalidResult)
+			return
+		}
+
+		pendingOpenExternalUrlRequestId = message.requestId
+		try {
+			const response = await handlers.openExternalUrl(
+				{ ...message, url },
+				{
+					signal: navigationAbortController.signal,
+				},
+			)
+			if (navigationAbortController.signal.aborted) {
+				return
+			}
+			const result: OpenExternalUrlResultMessage = {
+				type: "openExternalUrlResult",
+				requestId: message.requestId,
+				...response,
+			}
+			sendInitializedMessage(result)
+		} catch (error) {
+			if (!navigationAbortController.signal.aborted) {
+				throw error
+			}
+		} finally {
+			if (pendingOpenExternalUrlRequestId === message.requestId) {
+				pendingOpenExternalUrlRequestId = undefined
+			}
+		}
+	}
+
 	function flushPendingHostStateChanges() {
 		// Keep updates queued until the sandbox acknowledges initialization.
 		// Updates received before init is sent are included in its payload instead.
@@ -463,6 +540,7 @@ export function createCustomBlockHost(
 		onQueryDataSource: handleQuery,
 		onUnsubscribeDataSourceQuery: message =>
 			querySubscriptions.unsubscribe(message.subscriptionId),
+		onOpenExternalUrl: handleOpenExternalUrl,
 		onCreatePage: message => respondToRequest(message, handlers.createPage),
 		onGetPage: message => respondToRequest(message, handlers.getPage),
 		onOpenPage: message => respondToRequest(message, handlers.openPage),
@@ -474,8 +552,8 @@ export function createCustomBlockHost(
 
 	window.addEventListener("message", onMessage)
 	iframe.addEventListener("load", initializationController.onIframeLoad)
-
 	function stop() {
+		navigationAbortController.abort()
 		preparationController.abort()
 		window.removeEventListener("message", onMessage)
 		iframe.removeEventListener("load", initializationController.onIframeLoad)

package/src/index.ts

@@ -10,6 +10,7 @@ export type { CreatePageMessage } from "@notionhq/custom-blocks-protocol/message
 export type { GetPageMessage } from "@notionhq/custom-blocks-protocol/messages/getPage.js"
 export type { GetUserMessage } from "@notionhq/custom-blocks-protocol/messages/getUser.js"
 export type { ListUsersMessage } from "@notionhq/custom-blocks-protocol/messages/listUsers.js"
+export type { OpenExternalUrlMessage } from "@notionhq/custom-blocks-protocol/messages/openExternalUrl.js"
 export type { OpenPageMessage } from "@notionhq/custom-blocks-protocol/messages/openPage.js"
 export type {
 	CustomBlockCheckboxFilterOperator,
@@ -76,11 +77,14 @@ export type {
 	CustomBlockHostHandlers,
 	CustomBlockHostListUsersResult,
 	CustomBlockHostLogDirection,
+	CustomBlockHostNavigationContext,
+	CustomBlockHostOpenExternalUrlResult,
 	CustomBlockHostOpenPageResult,
 	CustomBlockHostUpdatePageResult,
 	GetPageMessageInput,
 	GetUserMessageInput,
 	ListUsersMessageInput,
+	OpenExternalUrlMessageInput,
 	OpenPageMessageInput,
 	QueryDataSourceMessageInput,
 	ResizeMessageInput,