@notionhq/custom-blocks-host 0.0.1

package/dist/protocol/messages/hostToSandbox.js

@@ -0,0 +1,34 @@
+import * as v from "valibot";
+import { contrastModeChangedMessageSchema } from "./contrastModeChanged.js";
+import { createPageResultMessageSchema } from "./createPageResult.js";
+import { currentUserChangedMessageSchema } from "./currentUserChanged.js";
+import { dataSourcesChangedMessageSchema } from "./dataSourcesChanged.js";
+import { getPageResultMessageSchema } from "./getPage.js";
+import { getUserResultMessageSchema } from "./getUser.js";
+import { initMessageSchema } from "./init.js";
+import { invalidSandboxMessageSchema } from "./invalidSandboxMessage.js";
+import { listUsersResultMessageSchema } from "./listUsers.js";
+import { pageChangedMessageSchema } from "./pageChanged.js";
+import { parentChangedMessageSchema } from "./parentChanged.js";
+import { 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", [
+    initMessageSchema,
+    themeChangedMessageSchema,
+    contrastModeChangedMessageSchema,
+    parentChangedMessageSchema,
+    pageChangedMessageSchema,
+    currentUserChangedMessageSchema,
+    dataSourcesChangedMessageSchema,
+    queryDataSourceResultMessageSchema,
+    createPageResultMessageSchema,
+    getPageResultMessageSchema,
+    getUserResultMessageSchema,
+    listUsersResultMessageSchema,
+    updatePageResultMessageSchema,
+    invalidSandboxMessageSchema,
+]);

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

@@ -0,0 +1,259 @@
+import * as v from "valibot";
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
+import type { CustomBlockInitResultErrorCode } from "./initResult.js";
+export declare const customBlockInitErrorCodeSchema: v.StringSchema<undefined>;
+export type CustomBlockInitErrorCode = CustomBlockErrorCode<"manifest_unavailable" | "manifest_invalid" | "invalid_connect_payload" | "invalid_protocol_version" | "unsupported_protocol_version" | "context_unavailable" | "current_user_unavailable" | "missing_data_source_binding" | "data_source_unavailable" | "missing_property_binding" | "invalid_property_binding">;
+export type CustomBlockInitErrorInfo = CustomBlockErrorInfo<CustomBlockInitErrorCode>;
+/**
+ * Every initialization failure visible to block code. This combines errors
+ * received in `init`, errors the sandbox reports in `initResult`, and failures
+ * detected locally while running `initCustomBlock()`.
+ */
+export type CustomBlockInitializationErrorCode = CustomBlockInitErrorCode | CustomBlockInitResultErrorCode | CustomBlockErrorCode<"not_in_iframe" | "init_timeout">;
+export type CustomBlockInitializationErrorInfo = CustomBlockErrorInfo<CustomBlockInitializationErrorCode>;
+export declare const customBlockInitErrorInfoSchema: v.ObjectSchema<{
+    readonly code: v.StringSchema<undefined>;
+    readonly message: v.StringSchema<undefined>;
+    readonly isRetryable: v.BooleanSchema<undefined>;
+}, undefined>;
+export declare class CustomBlockInitializationError extends Error implements CustomBlockErrorInfo {
+    constructor(error: CustomBlockInitializationErrorInfo);
+    code: CustomBlockInitializationErrorCode;
+    isRetryable: boolean;
+}
+/**
+ * Initialization message sent by the host to the sandbox exactly once, in response to the
+ * sandbox's `connect` message. The sandbox echoes `initializationId` in `initResult`. After
+ * successful initialization, live updates flow through narrower messages
+ * (`themeChanged`, `contrastModeChanged`, `parentChanged`, `pageChanged`,
+ * `dataSourcesChanged`).
+ */
+export declare const initMessageSchema: v.VariantSchema<"status", [v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"init", undefined>;
+    readonly initializationId: v.StringSchema<undefined>;
+    readonly status: v.LiteralSchema<"success", undefined>;
+    readonly theme: v.PicklistSchema<["light", "dark"], undefined>;
+    readonly contrastMode: v.OptionalSchema<v.PicklistSchema<["standard", "high"], undefined>, "standard" | "high">;
+    readonly blockId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionBlockId">]>;
+    readonly parent: v.VariantSchema<"type", [v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"page_id", undefined>;
+        readonly page_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"data_source_id", undefined>;
+        readonly data_source_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionDataSourceId">]>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"workspace", undefined>;
+        readonly workspace: v.LiteralSchema<true, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"block_id", undefined>;
+        readonly block_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionBlockId">]>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"agent_id", undefined>;
+        readonly agent_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionAgentId">]>;
+    }, undefined>], undefined>;
+    readonly page: v.ObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
+        readonly parent: v.VariantSchema<"type", [v.ObjectSchema<{
+            readonly type: v.LiteralSchema<"page_id", undefined>;
+            readonly page_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
+        }, undefined>, v.ObjectSchema<{
+            readonly type: v.LiteralSchema<"data_source_id", undefined>;
+            readonly data_source_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionDataSourceId">]>;
+        }, undefined>, v.ObjectSchema<{
+            readonly type: v.LiteralSchema<"workspace", undefined>;
+            readonly workspace: v.LiteralSchema<true, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly type: v.LiteralSchema<"block_id", undefined>;
+            readonly block_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionBlockId">]>;
+        }, undefined>, v.ObjectSchema<{
+            readonly type: v.LiteralSchema<"agent_id", undefined>;
+            readonly agent_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionAgentId">]>;
+        }, undefined>], undefined>;
+    }, undefined>;
+    readonly manifest: v.ObjectSchema<{
+        readonly version: v.LiteralSchema<1, undefined>;
+        readonly dataSources: v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+            readonly name: v.StringSchema<undefined>;
+            readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly icon: v.OptionalSchema<v.VariantSchema<"type", [v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"emoji", undefined>;
+                readonly emoji: v.StringSchema<undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly type: v.LiteralSchema<"external", undefined>;
+                readonly url: v.StringSchema<undefined>;
+            }, undefined>], undefined>, undefined>;
+            readonly properties: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+                readonly name: v.StringSchema<undefined>;
+                readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly type: v.PicklistSchema<readonly ["title", "rich_text", "number", "checkbox", "url", "email", "phone_number", "select", "multi_select", "status", "date", "people", "files", "unique_id", "relation", "place", "formula", "rollup", "button", "verification", "last_visited_time", "location", "created_time", "last_edited_time", "created_by", "last_edited_by"], undefined>;
+            }, undefined>, undefined>, {}>;
+        }, undefined>, undefined>;
+    }, undefined>;
+    readonly dataSources: v.ObjectSchema<{
+        readonly bindings: v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+            readonly collectionPointer: v.OptionalSchema<v.ObjectSchema<{
+                readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionDataSourceId">]>;
+                readonly table: v.StringSchema<undefined>;
+                readonly spaceId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionSpaceId">]>, undefined>;
+            }, undefined>, undefined>;
+            readonly collectionSchema: v.OptionalSchema<v.ObjectSchema<{
+                readonly id: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionDataSourceId">]>, undefined>;
+                readonly propertiesById: v.RecordSchema<v.StringSchema<undefined>, v.VariantSchema<"type", [v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"title", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"rich_text", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"number", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"checkbox", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"url", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"email", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"phone_number", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"select", undefined>;
+                    readonly options: v.ArraySchema<v.ObjectSchema<{
+                        readonly id: v.StringSchema<undefined>;
+                        readonly name: v.StringSchema<undefined>;
+                        readonly color: v.OptionalSchema<v.PicklistSchema<["default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background", "default_background"], undefined>, undefined>;
+                        readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    }, undefined>, undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"multi_select", undefined>;
+                    readonly options: v.ArraySchema<v.ObjectSchema<{
+                        readonly id: v.StringSchema<undefined>;
+                        readonly name: v.StringSchema<undefined>;
+                        readonly color: v.OptionalSchema<v.PicklistSchema<["default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background", "default_background"], undefined>, undefined>;
+                        readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    }, undefined>, undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"status", undefined>;
+                    readonly options: v.ArraySchema<v.ObjectSchema<{
+                        readonly id: v.StringSchema<undefined>;
+                        readonly name: v.StringSchema<undefined>;
+                        readonly color: v.OptionalSchema<v.PicklistSchema<["default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background", "default_background"], undefined>, undefined>;
+                        readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    }, undefined>, undefined>;
+                    readonly groups: v.ArraySchema<v.ObjectSchema<{
+                        readonly id: v.StringSchema<undefined>;
+                        readonly name: v.StringSchema<undefined>;
+                        readonly color: v.OptionalSchema<v.PicklistSchema<["default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red", "gray_background", "brown_background", "orange_background", "yellow_background", "green_background", "blue_background", "purple_background", "pink_background", "red_background", "default_background"], undefined>, undefined>;
+                        readonly option_ids: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+                    }, undefined>, undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"date", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"people", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"files", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"unique_id", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"relation", undefined>;
+                    readonly data_source_id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                    readonly dual_property: v.OptionalSchema<v.ObjectSchema<{
+                        readonly synced_property_id: v.StringSchema<undefined>;
+                        readonly synced_property_name: v.StringSchema<undefined>;
+                    }, undefined>, undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"place", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"formula", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"rollup", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"button", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"verification", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"last_visited_time", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"location", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"created_time", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"last_edited_time", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"created_by", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>, v.ObjectSchema<{
+                    readonly type: v.LiteralSchema<"last_edited_by", undefined>;
+                    readonly name: v.StringSchema<undefined>;
+                    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                }, undefined>], undefined>, undefined>;
+            }, undefined>, undefined>;
+            readonly propertyIdsByKey: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.OptionalSchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+        }, undefined>, undefined>;
+    }, undefined>;
+    readonly currentUser: v.ObjectSchema<{
+        readonly object: v.LiteralSchema<"user", undefined>;
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionUserId">]>;
+        readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly avatar_url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly type: v.LiteralSchema<"person", undefined>;
+        readonly person: v.ObjectSchema<{
+            readonly email: v.StringSchema<undefined>;
+        }, undefined>;
+    }, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"init", undefined>;
+    readonly initializationId: 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 InitMessage = v.InferOutput<typeof initMessageSchema>;

package/dist/protocol/messages/init.js

@@ -0,0 +1,56 @@
+import * as v from "valibot";
+import { DEFAULT_CONTRAST_MODE, notionContrastModeSchema } from "../contrast.js";
+import { notionDataSourceBindingsSchema } from "../dataSources/dataSource.js";
+import { notionBlockIdSchema } from "../ids.js";
+import { manifestSchema } from "../manifest.js";
+import { customBlockPageSchema } from "../pages/page.js";
+import { notionParentSchema } from "../parent.js";
+import { notionThemeSchema } from "../theme.js";
+import { notionUserSchema } from "../users/user.js";
+// The schema accepts any string code. The type lists known codes for
+// autocomplete, with an open string fallback for newer senders.
+export const customBlockInitErrorCodeSchema = v.string();
+export const customBlockInitErrorInfoSchema = v.object({
+    code: customBlockInitErrorCodeSchema,
+    message: v.string(),
+    isRetryable: v.boolean(),
+});
+export class CustomBlockInitializationError extends Error {
+    constructor(error) {
+        super(error.message);
+        this.name = "CustomBlockInitializationError";
+        this.code = error.code;
+        this.isRetryable = error.isRetryable;
+    }
+}
+/**
+ * Initialization message sent by the host to the sandbox exactly once, in response to the
+ * sandbox's `connect` message. The sandbox echoes `initializationId` in `initResult`. After
+ * successful initialization, live updates flow through narrower messages
+ * (`themeChanged`, `contrastModeChanged`, `parentChanged`, `pageChanged`,
+ * `dataSourcesChanged`).
+ */
+export const initMessageSchema = v.variant("status", [
+    v.object({
+        type: v.literal("init"),
+        initializationId: v.string(),
+        status: v.literal("success"),
+        theme: notionThemeSchema,
+        // TODO(custom-blocks): Make this required when bumping bridge protocol version 4.
+        contrastMode: v.optional(notionContrastModeSchema, DEFAULT_CONTRAST_MODE),
+        blockId: notionBlockIdSchema,
+        parent: notionParentSchema,
+        page: customBlockPageSchema,
+        manifest: manifestSchema,
+        dataSources: v.object({
+            bindings: notionDataSourceBindingsSchema,
+        }),
+        currentUser: notionUserSchema,
+    }),
+    v.object({
+        type: v.literal("init"),
+        initializationId: v.string(),
+        status: v.literal("error"),
+        error: customBlockInitErrorInfoSchema,
+    }),
+]);

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

@@ -0,0 +1,37 @@
+import * as v from "valibot";
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
+export declare const customBlockInitResultErrorCodeSchema: v.StringSchema<undefined>;
+export type CustomBlockInitResultErrorCode = CustomBlockErrorCode<
+/**
+ * The host-provided bindings defined in `init.dataSources` were rejected by the sandbox because
+ * they did not completely match the expected manifest keys.
+ */
+"invalid_init_bindings"
+/** The host-provided `init` payload failed to parse. */
+ | "invalid_init_payload">;
+export type CustomBlockInitResultErrorInfo = CustomBlockErrorInfo<CustomBlockInitResultErrorCode>;
+export declare const customBlockInitResultErrorInfoSchema: v.ObjectSchema<{
+    readonly code: v.StringSchema<undefined>;
+    readonly message: v.StringSchema<undefined>;
+    readonly isRetryable: v.BooleanSchema<undefined>;
+}, undefined>;
+/**
+ * Acknowledges whether the sandbox successfully applied the host's `init` response.
+ */
+export declare const initResultMessageSchema: v.VariantSchema<"status", [v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"initResult", undefined>;
+    readonly initializationId: v.StringSchema<undefined>;
+    readonly status: v.LiteralSchema<"success", undefined>;
+    /** Height of the initial rendered custom-block content, in CSS pixels. */
+    readonly initialHeight: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.FiniteAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"initResult", undefined>;
+    readonly initializationId: 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 InitResultMessage = v.InferOutput<typeof initResultMessageSchema>;

package/dist/protocol/messages/initResult.js

@@ -0,0 +1,28 @@
+import * as v from "valibot";
+// The schema accepts any string code. The type lists known codes for
+// autocomplete, with an open string fallback for newer senders.
+export const customBlockInitResultErrorCodeSchema = v.string();
+export const customBlockInitResultErrorInfoSchema = v.object({
+    code: customBlockInitResultErrorCodeSchema,
+    message: v.string(),
+    isRetryable: v.boolean(),
+});
+/**
+ * Acknowledges whether the sandbox successfully applied the host's `init` response.
+ */
+export const initResultMessageSchema = v.variant("status", [
+    v.object({
+        type: v.literal("initResult"),
+        initializationId: v.string(),
+        status: v.literal("success"),
+        /** Height of the initial rendered custom-block content, in CSS pixels. */
+        // TODO(custom-blocks): Make this required when bumping bridge protocol version 4.
+        initialHeight: v.optional(v.pipe(v.number(), v.finite(), v.minValue(0))),
+    }),
+    v.object({
+        type: v.literal("initResult"),
+        initializationId: v.string(),
+        status: v.literal("error"),
+        error: customBlockInitResultErrorInfoSchema,
+    }),
+]);

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

@@ -0,0 +1,14 @@
+import * as v from "valibot";
+/**
+ * Sent by the sandbox back to the host when an inbound host-to-sandbox message could not be parsed
+ * (unknown `type`, schema mismatch, etc.). The host should never reply to an `invalidHostMessage`
+ * with another bridge error message.
+ */
+export declare const invalidHostMessageSchema: v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"invalidHostMessage", undefined>;
+    /**
+     * A human-readable string intended for sandbox-side logging. It has no structured contract.
+     */
+    readonly reason: v.StringSchema<undefined>;
+}, undefined>;
+export type InvalidHostMessage = v.InferOutput<typeof invalidHostMessageSchema>;

package/dist/protocol/messages/invalidHostMessage.js

@@ -0,0 +1,13 @@
+import * as v from "valibot";
+/**
+ * Sent by the sandbox back to the host when an inbound host-to-sandbox message could not be parsed
+ * (unknown `type`, schema mismatch, etc.). The host should never reply to an `invalidHostMessage`
+ * with another bridge error message.
+ */
+export const invalidHostMessageSchema = v.object({
+    type: v.literal("invalidHostMessage"),
+    /**
+     * A human-readable string intended for sandbox-side logging. It has no structured contract.
+     */
+    reason: v.string(),
+});

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

@@ -0,0 +1,14 @@
+import * as v from "valibot";
+/**
+ * Sent by the host back to the sandbox when an inbound sandbox-to-host message could not be parsed
+ * (unknown `type`, schema mismatch, etc.). The sandbox should never reply to an
+ * `invalidSandboxMessage` with another bridge error message.
+ */
+export declare const invalidSandboxMessageSchema: v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"invalidSandboxMessage", undefined>;
+    /**
+     * A human-readable string intended for sandbox-side logging. It has no structured contract.
+     */
+    readonly reason: v.StringSchema<undefined>;
+}, undefined>;
+export type InvalidSandboxMessage = v.InferOutput<typeof invalidSandboxMessageSchema>;

package/dist/protocol/messages/invalidSandboxMessage.js

@@ -0,0 +1,13 @@
+import * as v from "valibot";
+/**
+ * Sent by the host back to the sandbox when an inbound sandbox-to-host message could not be parsed
+ * (unknown `type`, schema mismatch, etc.). The sandbox should never reply to an
+ * `invalidSandboxMessage` with another bridge error message.
+ */
+export const invalidSandboxMessageSchema = v.object({
+    type: v.literal("invalidSandboxMessage"),
+    /**
+     * A human-readable string intended for sandbox-side logging. It has no structured contract.
+     */
+    reason: v.string(),
+});

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

@@ -0,0 +1,52 @@
+import * as v from "valibot";
+import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js";
+export declare const customBlockListUsersErrorCodeSchema: v.StringSchema<undefined>;
+export type CustomBlockListUsersErrorCode = CustomBlockErrorCode<"list_users_failed">;
+export type CustomBlockListUsersErrorInfo = CustomBlockErrorInfo<CustomBlockListUsersErrorCode>;
+export declare const customBlockListUsersErrorInfoSchema: v.ObjectSchema<{
+    readonly code: v.StringSchema<undefined>;
+    readonly message: v.StringSchema<undefined>;
+    readonly isRetryable: v.BooleanSchema<undefined>;
+}, undefined>;
+/**
+ * Sandbox -> host: list users visible in the custom block's workspace.
+ */
+export declare const listUsersMessageSchema: v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"listUsers", undefined>;
+    readonly requestId: v.StringSchema<undefined>;
+    readonly startCursor: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly pageSize: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+}, undefined>;
+export type ListUsersMessage = v.InferOutput<typeof listUsersMessageSchema>;
+export declare const listUsersResultMessageSchema: v.VariantSchema<"status", [v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"listUsersResult", undefined>;
+    readonly requestId: v.StringSchema<undefined>;
+    readonly status: v.LiteralSchema<"success", undefined>;
+    readonly list: v.ObjectSchema<{
+        readonly object: v.LiteralSchema<"list", undefined>;
+        readonly results: v.ArraySchema<v.ObjectSchema<{
+            readonly object: v.LiteralSchema<"user", undefined>;
+            readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionUserId">]>;
+            readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly avatar_url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly type: v.LiteralSchema<"person", undefined>;
+            readonly person: v.ObjectSchema<{
+                readonly email: v.StringSchema<undefined>;
+            }, undefined>;
+        }, undefined>, undefined>;
+        readonly next_cursor: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly has_more: v.BooleanSchema<undefined>;
+        readonly type: v.LiteralSchema<"user", undefined>;
+        readonly user: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>;
+    }, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"listUsersResult", 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 ListUsersResultMessage = v.InferOutput<typeof listUsersResultMessageSchema>;

package/dist/protocol/messages/listUsers.js

@@ -0,0 +1,33 @@
+import * as v from "valibot";
+import { notionUserListSchema } from "../users/user.js";
+// The schema accepts any string code. The type lists known codes for
+// autocomplete, with an open string fallback for newer senders.
+export const customBlockListUsersErrorCodeSchema = v.string();
+export const customBlockListUsersErrorInfoSchema = v.object({
+    code: customBlockListUsersErrorCodeSchema,
+    message: v.string(),
+    isRetryable: v.boolean(),
+});
+/**
+ * Sandbox -> host: list users visible in the custom block's workspace.
+ */
+export const listUsersMessageSchema = v.object({
+    type: v.literal("listUsers"),
+    requestId: v.string(),
+    startCursor: v.optional(v.string()),
+    pageSize: v.optional(v.number()),
+});
+export const listUsersResultMessageSchema = v.variant("status", [
+    v.object({
+        type: v.literal("listUsersResult"),
+        requestId: v.string(),
+        status: v.literal("success"),
+        list: notionUserListSchema,
+    }),
+    v.object({
+        type: v.literal("listUsersResult"),
+        requestId: v.string(),
+        status: v.literal("error"),
+        error: customBlockListUsersErrorInfoSchema,
+    }),
+]);

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

@@ -0,0 +1,27 @@
+import * as v from "valibot";
+/**
+ * Message sent by the host whenever the custom block's nearest page ancestor changes.
+ */
+export declare const pageChangedMessageSchema: v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"pageChanged", undefined>;
+    readonly page: v.ObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
+        readonly parent: v.VariantSchema<"type", [v.ObjectSchema<{
+            readonly type: v.LiteralSchema<"page_id", undefined>;
+            readonly page_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
+        }, undefined>, v.ObjectSchema<{
+            readonly type: v.LiteralSchema<"data_source_id", undefined>;
+            readonly data_source_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionDataSourceId">]>;
+        }, undefined>, v.ObjectSchema<{
+            readonly type: v.LiteralSchema<"workspace", undefined>;
+            readonly workspace: v.LiteralSchema<true, undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly type: v.LiteralSchema<"block_id", undefined>;
+            readonly block_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionBlockId">]>;
+        }, undefined>, v.ObjectSchema<{
+            readonly type: v.LiteralSchema<"agent_id", undefined>;
+            readonly agent_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionAgentId">]>;
+        }, undefined>], undefined>;
+    }, undefined>;
+}, undefined>;
+export type PageChangedMessage = v.InferOutput<typeof pageChangedMessageSchema>;

package/dist/protocol/messages/pageChanged.js

@@ -0,0 +1,9 @@
+import * as v from "valibot";
+import { customBlockPageSchema } from "../pages/page.js";
+/**
+ * Message sent by the host whenever the custom block's nearest page ancestor changes.
+ */
+export const pageChangedMessageSchema = v.object({
+    type: v.literal("pageChanged"),
+    page: customBlockPageSchema,
+});

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

@@ -0,0 +1,24 @@
+import * as v from "valibot";
+/**
+ * Message sent by the host whenever the custom block's parent changes.
+ */
+export declare const parentChangedMessageSchema: v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"parentChanged", undefined>;
+    readonly parent: v.VariantSchema<"type", [v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"page_id", undefined>;
+        readonly page_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"data_source_id", undefined>;
+        readonly data_source_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionDataSourceId">]>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"workspace", undefined>;
+        readonly workspace: v.LiteralSchema<true, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"block_id", undefined>;
+        readonly block_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionBlockId">]>;
+    }, undefined>, v.ObjectSchema<{
+        readonly type: v.LiteralSchema<"agent_id", undefined>;
+        readonly agent_id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionAgentId">]>;
+    }, undefined>], undefined>;
+}, undefined>;
+export type ParentChangedMessage = v.InferOutput<typeof parentChangedMessageSchema>;