@notionhq/custom-blocks 0.0.58

package/src/bridge/messages/init.ts

@@ -0,0 +1,81 @@
+import * as v from "valibot"
+import { notionDataSourceBindingsSchema } from "../dataSources/dataSource.js"
+import type { CustomBlockErrorInfo } from "../errors.js"
+import { notionBlockIdSchema } from "../ids.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 type CustomBlockInitErrorCode =
+	| "no_ready"
+	| "invalid_ready"
+	| "manifest_unavailable"
+	| "manifest_invalid"
+	| "invalid_protocol_version"
+	| "unsupported_protocol_version"
+	| "context_unavailable"
+	| "current_user_unavailable"
+	| "missing_data_source_binding"
+	| "data_source_unavailable"
+	| "missing_property_binding"
+	| "invalid_property_binding"
+	| "not_in_iframe"
+	| "init_timeout"
+	| "unknown_error"
+	| (string & {})
+
+export type CustomBlockInitErrorInfo =
+	CustomBlockErrorInfo<CustomBlockInitErrorCode>
+
+export const customBlockInitErrorInfoSchema = v.object({
+	code: customBlockInitErrorCodeSchema,
+	message: v.string(),
+	isRetryable: v.boolean(),
+})
+
+export class CustomBlockInitError
+	extends Error
+	implements CustomBlockErrorInfo
+{
+	constructor(error: CustomBlockInitErrorInfo) {
+		super(error.message)
+		this.name = "CustomBlockInitError"
+		this.code = error.code
+		this.isRetryable = error.isRetryable
+	}
+
+	code: CustomBlockInitErrorCode
+	isRetryable: boolean
+}
+
+/**
+ * Initialization message sent by the host to the sandbox exactly once, in response to the
+ * sandbox's `ready` message. After init, live updates flow through narrower messages
+ * (`themeChanged`, `parentChanged`, `pageChanged`, `dataSourcesChanged`).
+ */
+export const initMessageSchema = v.variant("status", [
+	v.object({
+		type: v.literal("init"),
+		status: v.literal("success"),
+		theme: notionThemeSchema,
+		blockId: notionBlockIdSchema,
+		parent: notionParentSchema,
+		page: customBlockPageSchema,
+		dataSources: v.object({
+			bindings: notionDataSourceBindingsSchema,
+		}),
+		currentUser: notionUserSchema,
+	}),
+	v.object({
+		type: v.literal("init"),
+		status: v.literal("error"),
+		error: customBlockInitErrorInfoSchema,
+	}),
+])
+
+export type InitMessage = v.InferOutput<typeof initMessageSchema>

package/src/bridge/messages/invalidHostMessage.ts

@@ -0,0 +1,16 @@
+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(),
+})
+
+export type InvalidHostMessage = v.InferOutput<typeof invalidHostMessageSchema>

package/src/bridge/messages/invalidSandboxMessage.ts

@@ -0,0 +1,18 @@
+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(),
+})
+
+export type InvalidSandboxMessage = v.InferOutput<
+	typeof invalidSandboxMessageSchema
+>

package/src/bridge/messages/listUsers.ts

@@ -0,0 +1,49 @@
+import * as v from "valibot"
+import type { CustomBlockErrorInfo } from "../errors.js"
+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 type CustomBlockListUsersErrorCode = "list_users_failed" | (string & {})
+
+export type CustomBlockListUsersErrorInfo =
+	CustomBlockErrorInfo<CustomBlockListUsersErrorCode>
+
+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 type ListUsersMessage = v.InferOutput<typeof listUsersMessageSchema>
+
+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,
+	}),
+])
+
+export type ListUsersResultMessage = v.InferOutput<
+	typeof listUsersResultMessageSchema
+>

package/src/bridge/messages/pageChanged.ts

@@ -0,0 +1,12 @@
+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,
+})
+
+export type PageChangedMessage = v.InferOutput<typeof pageChangedMessageSchema>

package/src/bridge/messages/parentChanged.ts

@@ -0,0 +1,14 @@
+import * as v from "valibot"
+import { notionParentSchema } from "../parent.js"
+
+/**
+ * Message sent by the host whenever the custom block's parent changes.
+ */
+export const parentChangedMessageSchema = v.object({
+	type: v.literal("parentChanged"),
+	parent: notionParentSchema,
+})
+
+export type ParentChangedMessage = v.InferOutput<
+	typeof parentChangedMessageSchema
+>

package/src/bridge/messages/queryDataSource.ts

@@ -0,0 +1,24 @@
+import * as v from "valibot"
+import { notionDataSourceIdSchema } from "../ids.js"
+
+/**
+ * Message sent by the sandbox to ask the host for the current rows in a resolved
+ * Notion data source.
+ */
+export const queryDataSourceMessageSchema = v.object({
+	type: v.literal("queryDataSource"),
+	requestId: v.string(),
+	/**
+	 * The stable snapshot ID that identifies the SDK result slot to update. This is stable for the
+	 * lifetime of the subscription.
+	 */
+	snapshotId: v.string(),
+	/** The raw Notion data source ID to read from. */
+	dataSourceId: notionDataSourceIdSchema,
+	/** The number of items to return in the snapshot. */
+	limit: v.number(),
+})
+
+export type QueryDataSourceMessage = v.InferOutput<
+	typeof queryDataSourceMessageSchema
+>

package/src/bridge/messages/queryDataSourceResult.ts

@@ -0,0 +1,38 @@
+import * as v from "valibot"
+import { notionDataSourcePageBridgeSchema } from "../dataSources/dataSourcePage.js"
+import type { CustomBlockErrorInfo } from "../errors.js"
+
+// The schema accepts any string code. The type lists known codes for
+// autocomplete, with an open string fallback for newer senders.
+export const customBlockQueryDataSourceErrorCodeSchema = v.string()
+
+export type CustomBlockQueryDataSourceErrorCode =
+	| "query_data_source_failed"
+	| "unknown_data_source_key"
+	| "unmapped_data_source"
+	| (string & {})
+
+export type CustomBlockQueryDataSourceErrorInfo =
+	CustomBlockErrorInfo<CustomBlockQueryDataSourceErrorCode>
+
+export const customBlockQueryDataSourceErrorInfoSchema = v.object({
+	code: customBlockQueryDataSourceErrorCodeSchema,
+	message: v.string(),
+	isRetryable: v.boolean(),
+})
+
+/**
+ * Message sent by the host to the sandbox in response to a `queryDataSource` request.
+ */
+export const queryDataSourceResultMessageSchema = v.object({
+	type: v.literal("queryDataSourceResult"),
+	requestId: v.string(),
+	snapshotId: v.string(),
+	items: v.array(notionDataSourcePageBridgeSchema),
+	hasMore: v.boolean(),
+	error: v.optional(customBlockQueryDataSourceErrorInfoSchema),
+})
+
+export type QueryDataSourceResultMessage = v.InferOutput<
+	typeof queryDataSourceResultMessageSchema
+>

package/src/bridge/messages/ready.ts

@@ -0,0 +1,41 @@
+import * as v from "valibot"
+import { customBlockReadyErrorSchema } from "../loadManifest.js"
+import { manifestSchema } from "../manifest.js"
+
+const readyMessageCommonEntries = {
+	type: v.literal("ready"),
+	/**
+	 * 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 ready 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, kicking off the bridge handshake. The host replies
+ * with `init`.
+ */
+export const readyMessageSchema = v.union([
+	v.object({
+		status: v.literal("success"),
+		/**
+		 * The data sources and settings the custom block expects, or null when the
+		 * block has no manifest and no declared data requirements.
+		 */
+		manifest: v.union([manifestSchema, v.null_()]),
+		...readyMessageCommonEntries,
+	}),
+	v.object({
+		status: v.literal("error"),
+		error: customBlockReadyErrorSchema,
+		...readyMessageCommonEntries,
+	}),
+])
+
+export type ReadyMessage = v.InferOutput<typeof readyMessageSchema>

package/src/bridge/messages/resize.ts

@@ -0,0 +1,13 @@
+import * as v from "valibot"
+
+/**
+ * Message sent by the sandbox whenever its measured content height changes, so the host can resize
+ * the surrounding iframe to match. The host is free to clamp the value or ignore it. The sandbox
+ * always reports the most recent measurement.
+ */
+export const resizeMessageSchema = v.object({
+	type: v.literal("resize"),
+	height: v.pipe(v.number(), v.finite(), v.minValue(0)),
+})
+
+export type ResizeMessage = v.InferOutput<typeof resizeMessageSchema>

package/src/bridge/messages/sandboxToHost.ts

@@ -0,0 +1,30 @@
+import * as v from "valibot"
+import { createPageMessageSchema } from "./createPage.js"
+import { getPageMessageSchema } from "./getPage.js"
+import { getUserMessageSchema } from "./getUser.js"
+import { invalidHostMessageSchema } from "./invalidHostMessage.js"
+import { listUsersMessageSchema } from "./listUsers.js"
+import { queryDataSourceMessageSchema } from "./queryDataSource.js"
+import { readyMessageSchema } from "./ready.js"
+import { resizeMessageSchema } from "./resize.js"
+import { updatePageMessageSchema } from "./updatePage.js"
+
+/**
+ * Union of every message the sandbox is allowed to send the host. Useful for hosts to validate
+ * inbound traffic from sandboxes without re-implementing validation logic.
+ */
+export const sandboxToHostMessageSchema = v.union([
+	readyMessageSchema,
+	queryDataSourceMessageSchema,
+	createPageMessageSchema,
+	getPageMessageSchema,
+	getUserMessageSchema,
+	listUsersMessageSchema,
+	updatePageMessageSchema,
+	resizeMessageSchema,
+	invalidHostMessageSchema,
+])
+
+export type SandboxToHostMessage = v.InferOutput<
+	typeof sandboxToHostMessageSchema
+>

package/src/bridge/messages/themeChanged.ts

@@ -0,0 +1,15 @@
+import * as v from "valibot"
+import { notionThemeSchema } from "../theme.js"
+
+/**
+ * Message sent by the host every time the theme changes after the initial
+ * `init` handshake.
+ */
+export const themeChangedMessageSchema = v.object({
+	type: v.literal("themeChanged"),
+	theme: notionThemeSchema,
+})
+
+export type ThemeChangedMessage = v.InferOutput<
+	typeof themeChangedMessageSchema
+>

package/src/bridge/messages/updatePage.ts

@@ -0,0 +1,22 @@
+import * as v from "valibot"
+import { notionPageIdSchema } from "../ids.js"
+import {
+	notionPageCoverSchema,
+	notionPageIconSchema,
+	notionPagePropertyWriteMapSchema,
+} from "../pages/page.js"
+
+/**
+ * Sandbox -> host: patch an existing page.
+ */
+export const updatePageMessageSchema = v.object({
+	type: v.literal("updatePage"),
+	requestId: v.string(),
+	pageId: notionPageIdSchema,
+	properties: v.optional(notionPagePropertyWriteMapSchema),
+	icon: v.optional(notionPageIconSchema),
+	cover: v.optional(notionPageCoverSchema),
+	archived: v.optional(v.boolean()),
+})
+
+export type UpdatePageMessage = v.InferOutput<typeof updatePageMessageSchema>

package/src/bridge/messages/updatePageResult.ts

@@ -0,0 +1,49 @@
+import * as v from "valibot"
+import type { CustomBlockErrorInfo } from "../errors.js"
+import { notionPageSchema } from "../pages/page.js"
+
+// The schema accepts any string code. The type lists known codes for
+// autocomplete, with an open string fallback for newer senders.
+export const customBlockUpdatePageErrorCodeSchema = v.string()
+
+export type CustomBlockUpdatePageErrorCode =
+	| "update_page_failed"
+	| "invalid_page_update"
+	| "page_access_failed"
+	| "collection_access_failed"
+	| "unmapped_property"
+	| "property_id_mismatch"
+	| "duplicate_property"
+	| "invalid_property_value"
+	| (string & {})
+
+export type CustomBlockUpdatePageErrorInfo =
+	CustomBlockErrorInfo<CustomBlockUpdatePageErrorCode>
+
+export const customBlockUpdatePageErrorInfoSchema = v.object({
+	code: customBlockUpdatePageErrorCodeSchema,
+	message: v.string(),
+	isRetryable: v.boolean(),
+})
+
+/**
+ * Host -> sandbox: result for a page update request.
+ */
+export const updatePageResultMessageSchema = v.variant("status", [
+	v.object({
+		type: v.literal("updatePageResult"),
+		requestId: v.string(),
+		status: v.literal("success"),
+		page: notionPageSchema,
+	}),
+	v.object({
+		type: v.literal("updatePageResult"),
+		requestId: v.string(),
+		status: v.literal("error"),
+		error: customBlockUpdatePageErrorInfoSchema,
+	}),
+])
+
+export type UpdatePageResultMessage = v.InferOutput<
+	typeof updatePageResultMessageSchema
+>