@notionhq/custom-blocks-host 0.0.1

package/dist/protocol/dataSources/propertySchema.js

@@ -0,0 +1,165 @@
+import * as v from "valibot";
+/**
+ * Hex-token identifiers for Notion's named colors. Mirrors the public API's
+ * `select.options[].color` enum
+ * (https://developers.notion.com/reference/property-object#select).
+ */
+export const notionPropertyColorSchema = v.picklist([
+    "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",
+]);
+export const notionPropertyOptionSchema = v.object({
+    id: v.string(),
+    name: v.string(),
+    color: v.optional(notionPropertyColorSchema),
+    description: v.optional(v.string()),
+});
+export const notionStatusGroupSchema = v.object({
+    id: v.string(),
+    name: v.string(),
+    color: v.optional(notionPropertyColorSchema),
+    option_ids: v.array(v.string()),
+});
+export const notionDualPropertySchema = v.object({
+    synced_property_id: v.string(),
+    synced_property_name: v.string(),
+});
+const baseProp = v.object({
+    name: v.string(),
+    description: v.optional(v.string()),
+});
+/**
+ * Every Notion property type the bridge speaks, in a single readable list.
+ * Mirrors the Notion public API
+ * [property object](https://developers.notion.com/reference/property-object)
+ * type field. Internal-only types (`button`, `verification`,
+ * `last_visited_time`, `location`) and the four built-ins (`created_time`,
+ * `last_edited_time`, `created_by`, `last_edited_by`) are included under their
+ * bridge-native names.
+ */
+export const NOTION_PROPERTY_TYPES = [
+    "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",
+];
+export const notionPropertyTypeSchema = v.picklist(NOTION_PROPERTY_TYPES);
+/**
+ * Property types currently supported by the custom-block data source sort API.
+ * Keep this list narrower than {@link NOTION_PROPERTY_TYPES} when a property
+ * type is exposed but its sort value is not yet represented by every host.
+ */
+export const CUSTOM_BLOCK_DATA_SOURCE_SORTABLE_PROPERTY_TYPES = [
+    "title",
+    "rich_text",
+    "number",
+    "checkbox",
+    "url",
+    "email",
+    "phone_number",
+    "date",
+    "created_time",
+    "last_edited_time",
+];
+/**
+ * Per-property schema as exposed by the host over the custom-block bridge.
+ * The `type` discriminator must be one of {@link NOTION_PROPERTY_TYPES}.
+ */
+export const notionPropertySchemaSchema = v.variant("type", [
+    v.object({ ...baseProp.entries, type: v.literal("title") }),
+    v.object({ ...baseProp.entries, type: v.literal("rich_text") }),
+    v.object({ ...baseProp.entries, type: v.literal("number") }),
+    v.object({ ...baseProp.entries, type: v.literal("checkbox") }),
+    v.object({ ...baseProp.entries, type: v.literal("url") }),
+    v.object({ ...baseProp.entries, type: v.literal("email") }),
+    v.object({ ...baseProp.entries, type: v.literal("phone_number") }),
+    v.object({
+        ...baseProp.entries,
+        type: v.literal("select"),
+        options: v.array(notionPropertyOptionSchema),
+    }),
+    v.object({
+        ...baseProp.entries,
+        type: v.literal("multi_select"),
+        options: v.array(notionPropertyOptionSchema),
+    }),
+    v.object({
+        ...baseProp.entries,
+        type: v.literal("status"),
+        options: v.array(notionPropertyOptionSchema),
+        groups: v.array(notionStatusGroupSchema),
+    }),
+    v.object({ ...baseProp.entries, type: v.literal("date") }),
+    v.object({ ...baseProp.entries, type: v.literal("people") }),
+    v.object({ ...baseProp.entries, type: v.literal("files") }),
+    v.object({ ...baseProp.entries, type: v.literal("unique_id") }),
+    v.object({
+        ...baseProp.entries,
+        type: v.literal("relation"),
+        data_source_id: v.optional(v.string()),
+        dual_property: v.optional(notionDualPropertySchema),
+    }),
+    v.object({ ...baseProp.entries, type: v.literal("place") }),
+    v.object({ ...baseProp.entries, type: v.literal("formula") }),
+    v.object({ ...baseProp.entries, type: v.literal("rollup") }),
+    // Internal-only types passed through under their bridge-native names.
+    v.object({ ...baseProp.entries, type: v.literal("button") }),
+    v.object({ ...baseProp.entries, type: v.literal("verification") }),
+    v.object({ ...baseProp.entries, type: v.literal("last_visited_time") }),
+    v.object({ ...baseProp.entries, type: v.literal("location") }),
+    // Synthetic built-ins. The host always emits one of each per data source.
+    v.object({ ...baseProp.entries, type: v.literal("created_time") }),
+    v.object({ ...baseProp.entries, type: v.literal("last_edited_time") }),
+    v.object({ ...baseProp.entries, type: v.literal("created_by") }),
+    v.object({ ...baseProp.entries, type: v.literal("last_edited_by") }),
+]);
+/**
+ * The four synthetic built-in property IDs the host always includes in every
+ * data source's `propertySchemasById` and every row's `propertiesById`.
+ */
+export const NOTION_BUILTIN_PROPERTY_IDS = [
+    "created_time",
+    "last_edited_time",
+    "created_by",
+    "last_edited_by",
+];

package/dist/protocol/dataSources/recordPointer.d.ts

@@ -0,0 +1,9 @@
+import * as v from "valibot";
+/**
+ * A pointer to a record in a database.
+ */
+export declare const notionRecordPointerSchema: v.ObjectSchema<{
+    readonly id: v.StringSchema<undefined>;
+    readonly table: v.StringSchema<undefined>;
+}, undefined>;
+export type NotionRecordPointer = v.InferOutput<typeof notionRecordPointerSchema>;

package/dist/protocol/dataSources/recordPointer.js

@@ -0,0 +1,8 @@
+import * as v from "valibot";
+/**
+ * A pointer to a record in a database.
+ */
+export const notionRecordPointerSchema = v.object({
+    id: v.string(),
+    table: v.string(),
+});

package/dist/protocol/errors.d.ts

@@ -0,0 +1,12 @@
+import * as v from "valibot";
+export type CustomBlockErrorCode<KnownCode extends string> = KnownCode | "unknown_error" | (string & {});
+export type CustomBlockErrorInfo<TCode extends string = string> = {
+    code: TCode;
+    message: string;
+    isRetryable: boolean;
+};
+export declare const customBlockErrorInfoSchema: v.ObjectSchema<{
+    readonly code: v.StringSchema<undefined>;
+    readonly message: v.StringSchema<undefined>;
+    readonly isRetryable: v.BooleanSchema<undefined>;
+}, undefined>;

package/dist/protocol/errors.js

@@ -0,0 +1,6 @@
+import * as v from "valibot";
+export const customBlockErrorInfoSchema = v.object({
+    code: v.string(),
+    message: v.string(),
+    isRetryable: v.boolean(),
+});

package/dist/protocol/ids.d.ts

@@ -0,0 +1,31 @@
+import * as v from "valibot";
+/**
+ * Branded Notion block ID. Host payloads and SDK APIs use plain strings at runtime,
+ * but the brand keeps block IDs from being accidentally mixed with other IDs in TypeScript.
+ */
+export declare const notionBlockIdSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionBlockId">]>;
+export type NotionBlockId = v.InferOutput<typeof notionBlockIdSchema>;
+/**
+ * Branded Notion data source ID. Host payloads and SDK APIs use plain strings at runtime,
+ * but the brand keeps data source IDs from being accidentally mixed with other IDs in TypeScript.
+ */
+export declare const notionDataSourceIdSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionDataSourceId">]>;
+export type NotionDataSourceId = v.InferOutput<typeof notionDataSourceIdSchema>;
+/**
+ * Branded Notion page ID. Host payloads and SDK APIs use plain strings at runtime,
+ * but the brand keeps page IDs from being accidentally mixed with other IDs in TypeScript.
+ */
+export declare const notionPageIdSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionPageId">]>;
+export type NotionPageId = v.InferOutput<typeof notionPageIdSchema>;
+/**
+ * Branded Notion agent ID. Agent parents identify the workflow that owns an
+ * instruction page or one of its blocks.
+ */
+export declare const notionAgentIdSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionAgentId">]>;
+export type NotionAgentId = v.InferOutput<typeof notionAgentIdSchema>;
+/**
+ * Branded Notion workspace/space ID. Host payloads and SDK APIs use plain strings at runtime,
+ * but the brand keeps space IDs from being accidentally mixed with other IDs in TypeScript.
+ */
+export declare const notionSpaceIdSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.BrandAction<string, "NotionSpaceId">]>;
+export type NotionSpaceId = v.InferOutput<typeof notionSpaceIdSchema>;

package/dist/protocol/ids.js

@@ -0,0 +1,26 @@
+import * as v from "valibot";
+/**
+ * Branded Notion block ID. Host payloads and SDK APIs use plain strings at runtime,
+ * but the brand keeps block IDs from being accidentally mixed with other IDs in TypeScript.
+ */
+export const notionBlockIdSchema = v.pipe(v.string(), v.brand("NotionBlockId"));
+/**
+ * Branded Notion data source ID. Host payloads and SDK APIs use plain strings at runtime,
+ * but the brand keeps data source IDs from being accidentally mixed with other IDs in TypeScript.
+ */
+export const notionDataSourceIdSchema = v.pipe(v.string(), v.brand("NotionDataSourceId"));
+/**
+ * Branded Notion page ID. Host payloads and SDK APIs use plain strings at runtime,
+ * but the brand keeps page IDs from being accidentally mixed with other IDs in TypeScript.
+ */
+export const notionPageIdSchema = v.pipe(v.string(), v.brand("NotionPageId"));
+/**
+ * Branded Notion agent ID. Agent parents identify the workflow that owns an
+ * instruction page or one of its blocks.
+ */
+export const notionAgentIdSchema = v.pipe(v.string(), v.brand("NotionAgentId"));
+/**
+ * Branded Notion workspace/space ID. Host payloads and SDK APIs use plain strings at runtime,
+ * but the brand keeps space IDs from being accidentally mixed with other IDs in TypeScript.
+ */
+export const notionSpaceIdSchema = v.pipe(v.string(), v.brand("NotionSpaceId"));

package/dist/protocol/incomingType.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reads the `type` field off an inbound bridge message, if any.
+ *
+ * Used by both sides of the bridge after the canonical message schema rejects a payload. We still
+ * want to know what type the sender claimed to be sending so we can (a) avoid NACK loops on
+ * `invalidHostMessage` / `invalidSandboxMessage` and (b) include the type in the failure reason
+ * for debugging.
+ */
+export declare function readIncomingType(data: unknown): string | undefined;

package/dist/protocol/incomingType.js

@@ -0,0 +1,17 @@
+/**
+ * Reads the `type` field off an inbound bridge message, if any.
+ *
+ * Used by both sides of the bridge after the canonical message schema rejects a payload. We still
+ * want to know what type the sender claimed to be sending so we can (a) avoid NACK loops on
+ * `invalidHostMessage` / `invalidSandboxMessage` and (b) include the type in the failure reason
+ * for debugging.
+ */
+export function readIncomingType(data) {
+    if (typeof data === "object" &&
+        data !== null &&
+        "type" in data &&
+        typeof data.type === "string") {
+        return data.type;
+    }
+    return undefined;
+}

package/dist/protocol/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared wire contract for custom block sandboxes and hosts.
+ *
+ * This package contains only protocol data: message schemas, wire types, IDs,
+ * errors, manifests, and protocol-version constants. Runtime behavior belongs
+ * in either the author SDK or the host package.
+ */
+export * from "./contrast.js";
+export * from "./dataSources/dataSource.js";
+export * from "./dataSources/dataSourcePage.js";
+export * from "./dataSources/dataSourceValue.js";
+export * from "./dataSources/dateValue.js";
+export * from "./dataSources/errors.js";
+export * from "./dataSources/propertySchema.js";
+export * from "./dataSources/recordPointer.js";
+export * from "./errors.js";
+export * from "./ids.js";
+export * from "./incomingType.js";
+export * from "./manifest.js";
+export * from "./messagePayload.js";
+export * from "./messages/connect.js";
+export * from "./messages/contrastModeChanged.js";
+export * from "./messages/createPage.js";
+export * from "./messages/createPageResult.js";
+export * from "./messages/currentUserChanged.js";
+export * from "./messages/dataSourcesChanged.js";
+export * from "./messages/getPage.js";
+export * from "./messages/getUser.js";
+export * from "./messages/hostToSandbox.js";
+export * from "./messages/init.js";
+export * from "./messages/initResult.js";
+export * from "./messages/invalidHostMessage.js";
+export * from "./messages/invalidSandboxMessage.js";
+export * from "./messages/listUsers.js";
+export * from "./messages/pageChanged.js";
+export * from "./messages/parentChanged.js";
+export * from "./messages/queryDataSource.js";
+export * from "./messages/queryDataSourceResult.js";
+export * from "./messages/resize.js";
+export * from "./messages/sandboxToHost.js";
+export * from "./messages/themeChanged.js";
+export * from "./messages/updatePage.js";
+export * from "./messages/updatePageResult.js";
+export * from "./pages/page.js";
+export * from "./parent.js";
+export * from "./protocolVersion.js";
+export * from "./theme.js";
+export * from "./users/user.js";

package/dist/protocol/index.js

@@ -0,0 +1,48 @@
+/**
+ * Shared wire contract for custom block sandboxes and hosts.
+ *
+ * This package contains only protocol data: message schemas, wire types, IDs,
+ * errors, manifests, and protocol-version constants. Runtime behavior belongs
+ * in either the author SDK or the host package.
+ */
+export * from "./contrast.js";
+export * from "./dataSources/dataSource.js";
+export * from "./dataSources/dataSourcePage.js";
+export * from "./dataSources/dataSourceValue.js";
+export * from "./dataSources/dateValue.js";
+export * from "./dataSources/errors.js";
+export * from "./dataSources/propertySchema.js";
+export * from "./dataSources/recordPointer.js";
+export * from "./errors.js";
+export * from "./ids.js";
+export * from "./incomingType.js";
+export * from "./manifest.js";
+export * from "./messagePayload.js";
+export * from "./messages/connect.js";
+export * from "./messages/contrastModeChanged.js";
+export * from "./messages/createPage.js";
+export * from "./messages/createPageResult.js";
+export * from "./messages/currentUserChanged.js";
+export * from "./messages/dataSourcesChanged.js";
+export * from "./messages/getPage.js";
+export * from "./messages/getUser.js";
+export * from "./messages/hostToSandbox.js";
+export * from "./messages/init.js";
+export * from "./messages/initResult.js";
+export * from "./messages/invalidHostMessage.js";
+export * from "./messages/invalidSandboxMessage.js";
+export * from "./messages/listUsers.js";
+export * from "./messages/pageChanged.js";
+export * from "./messages/parentChanged.js";
+export * from "./messages/queryDataSource.js";
+export * from "./messages/queryDataSourceResult.js";
+export * from "./messages/resize.js";
+export * from "./messages/sandboxToHost.js";
+export * from "./messages/themeChanged.js";
+export * from "./messages/updatePage.js";
+export * from "./messages/updatePageResult.js";
+export * from "./pages/page.js";
+export * from "./parent.js";
+export * from "./protocolVersion.js";
+export * from "./theme.js";
+export * from "./users/user.js";

package/dist/protocol/manifest.d.ts

@@ -0,0 +1,60 @@
+import * as v from "valibot";
+/**
+ * Decorative icon attached to a manifest data source. Mirrors the
+ * `emoji` / `external` icon variants the public Notion API uses, so the host
+ * can render a recognizable affordance next to the slot in setup UI.
+ */
+export declare const manifestIconSchema: 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>;
+export type ManifestIcon = v.InferOutput<typeof manifestIconSchema>;
+export declare const manifestPropertySchema: 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>;
+export type ManifestProperty = v.InferOutput<typeof manifestPropertySchema>;
+export declare const manifestDataSourceSchema: 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>;
+export type ManifestDataSource = v.InferOutput<typeof manifestDataSourceSchema>;
+export declare const manifestSchema: 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>;
+/**
+ * Manifest declaring the data sources required by a custom block.
+ */
+export type CustomBlockManifest = v.InferOutput<typeof manifestSchema>;

package/dist/protocol/manifest.js

@@ -0,0 +1,32 @@
+import * as v from "valibot";
+import { notionPropertyTypeSchema } from "./dataSources/propertySchema.js";
+/**
+ * Decorative icon attached to a manifest data source. Mirrors the
+ * `emoji` / `external` icon variants the public Notion API uses, so the host
+ * can render a recognizable affordance next to the slot in setup UI.
+ */
+export const manifestIconSchema = v.variant("type", [
+    v.object({
+        type: v.literal("emoji"),
+        emoji: v.string(),
+    }),
+    v.object({
+        type: v.literal("external"),
+        url: v.string(),
+    }),
+]);
+export const manifestPropertySchema = v.object({
+    name: v.string(),
+    description: v.optional(v.string()),
+    type: notionPropertyTypeSchema,
+});
+export const manifestDataSourceSchema = v.object({
+    name: v.string(),
+    description: v.optional(v.string()),
+    icon: v.optional(manifestIconSchema),
+    properties: v.optional(v.record(v.string(), manifestPropertySchema), {}),
+});
+export const manifestSchema = v.object({
+    version: v.literal(1),
+    dataSources: v.record(v.string(), manifestDataSourceSchema),
+});

package/dist/protocol/messagePayload.d.ts

@@ -0,0 +1,19 @@
+import type { CustomBlockErrorInfo } from "./errors.js";
+type WithTypedErrorInfo<T, TErrorInfo extends CustomBlockErrorInfo | undefined> = TErrorInfo extends CustomBlockErrorInfo ? T extends {
+    error: CustomBlockErrorInfo;
+} ? Omit<T, "error"> & {
+    error: TErrorInfo;
+} : T : T;
+/**
+ * Removes bridge envelope fields from every member of a message union.
+ *
+ * The conditional type makes the operation distributive, preserving
+ * success/error-specific fields such as `page` and `error`.
+ *
+ * Pass an API-specific error-info type to preserve its known error-code
+ * literals while still accepting unknown string codes at runtime.
+ */
+export type BridgeMessagePayload<T extends {
+    type: string;
+}, TErrorInfo extends CustomBlockErrorInfo | undefined = undefined> = T extends unknown ? WithTypedErrorInfo<Omit<T, "type" | "requestId" | "subscriptionId">, TErrorInfo> : never;
+export {};

package/dist/protocol/messagePayload.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,47 @@
+import * as v from "valibot";
+/**
+ * First message the sandbox sends after mount. It identifies the sandbox and starts the bridge
+ * initialization exchange. The host echoes `initializationId` in its `init` response.
+ */
+export declare const connectMessageSchema: v.VariantSchema<"status", [v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"connect", undefined>;
+    readonly initializationId: v.StringSchema<undefined>;
+    readonly bridgeProtocolVersion: v.NumberSchema<undefined>;
+    readonly sdkVersion: v.StringSchema<undefined>;
+    readonly status: v.LiteralSchema<"success", undefined>;
+    /**
+     * The data sources and settings the custom block expects. Hosts may omit
+     * this when they already have an authoritative manifest.
+     */
+    readonly manifest: v.OptionalSchema<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>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"connect", undefined>;
+    readonly initializationId: v.StringSchema<undefined>;
+    readonly bridgeProtocolVersion: v.NumberSchema<undefined>;
+    readonly sdkVersion: 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 ConnectMessage = v.InferOutput<typeof connectMessageSchema>;

package/dist/protocol/messages/connect.js

@@ -0,0 +1,38 @@
+import * as v from "valibot";
+import { customBlockErrorInfoSchema } from "../errors.js";
+import { manifestSchema } from "../manifest.js";
+const connectMessageCommonEntries = {
+    type: v.literal("connect"),
+    initializationId: v.string(),
+    /**
+     * Used to ensure that the host and client are using the same version of the bridge protocol. A
+     * single host needs to support multiple custom blocks built with different versions of the bridge
+     * protocol. Increment this number any time a breaking change is made to the bridge protocol.
+     */
+    bridgeProtocolVersion: v.number(),
+    /**
+     * Semver version of the SDK package that sent this connect message. Should only be used for
+     * analytics purposes. Business logic should compare against `bridgeProtocolVersion` instead.
+     */
+    sdkVersion: v.string(),
+};
+/**
+ * First message the sandbox sends after mount. It identifies the sandbox and starts the bridge
+ * initialization exchange. The host echoes `initializationId` in its `init` response.
+ */
+export const connectMessageSchema = v.variant("status", [
+    v.object({
+        status: v.literal("success"),
+        /**
+         * The data sources and settings the custom block expects. Hosts may omit
+         * this when they already have an authoritative manifest.
+         */
+        manifest: v.optional(manifestSchema),
+        ...connectMessageCommonEntries,
+    }),
+    v.object({
+        status: v.literal("error"),
+        error: customBlockErrorInfoSchema,
+        ...connectMessageCommonEntries,
+    }),
+]);

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

@@ -0,0 +1,7 @@
+import * as v from "valibot";
+/** Message sent by the host when contrast changes after initialization. */
+export declare const contrastModeChangedMessageSchema: v.ObjectSchema<{
+    readonly type: v.LiteralSchema<"contrastModeChanged", undefined>;
+    readonly contrastMode: v.PicklistSchema<["standard", "high"], undefined>;
+}, undefined>;
+export type ContrastModeChangedMessage = v.InferOutput<typeof contrastModeChangedMessageSchema>;

package/dist/protocol/messages/contrastModeChanged.js

@@ -0,0 +1,7 @@
+import * as v from "valibot";
+import { notionContrastModeSchema } from "../contrast.js";
+/** Message sent by the host when contrast changes after initialization. */
+export const contrastModeChangedMessageSchema = v.object({
+    type: v.literal("contrastModeChanged"),
+    contrastMode: notionContrastModeSchema,
+});