@notionhq/custom-blocks 0.0.58

package/src/bridge/pages/page.ts

@@ -0,0 +1,281 @@
+/**
+ * Notion page shapes exchanged over the custom block bridge.
+ *
+ * These mirror a narrow subset of Notion's public `POST /v1/pages` API, since that's the bridge
+ * shape the host delivers for messages like `createPageResult`.
+ */
+
+import * as v from "valibot"
+import { notionDataSourceIdSchema, notionPageIdSchema } from "../ids.js"
+import { notionParentSchema } from "../parent.js"
+
+export type { NotionPageId } from "../ids.js"
+
+export const customBlockPageSchema = v.object({
+	id: notionPageIdSchema,
+})
+
+export type CustomBlockPage = v.InferOutput<typeof customBlockPageSchema>
+
+/**
+ * Parent reference accepted by `pages.create` / `pages.update` inputs.
+ *
+ * Mirrors the parent shape Notion's public `POST /v1/pages` API accepts: `page_id` for a
+ * page-parented child, `data_source_id` for a database row. `data_source_id` is the internal
+ * collection ID.
+ */
+export const notionPageParentInputSchema = v.variant("type", [
+	v.object({ type: v.literal("page_id"), page_id: notionPageIdSchema }),
+	v.object({
+		type: v.literal("data_source_id"),
+		data_source_id: notionDataSourceIdSchema,
+	}),
+])
+export type NotionPageParentInput = v.InferOutput<
+	typeof notionPageParentInputSchema
+>
+
+export const notionEmojiIconSchema = v.object({
+	type: v.literal("emoji"),
+	emoji: v.string(),
+})
+export const notionCustomEmojiIconSchema = v.object({
+	type: v.literal("custom_emoji"),
+	custom_emoji: v.object({
+		id: v.string(),
+		name: v.optional(v.string()),
+		url: v.optional(v.string()),
+	}),
+})
+export const notionExternalFileSchema = v.object({
+	type: v.literal("external"),
+	external: v.object({ url: v.string() }),
+})
+export const notionHostedFileSchema = v.object({
+	type: v.literal("file"),
+	file: v.object({
+		url: v.string(),
+		expiry_time: v.optional(v.string()),
+	}),
+})
+
+// TODO(custom-blocks): Add file upload support.
+export const notionPageIconSchema = v.variant("type", [
+	notionEmojiIconSchema,
+	notionCustomEmojiIconSchema,
+	notionExternalFileSchema,
+	notionHostedFileSchema,
+])
+export type NotionPageIcon = v.InferOutput<typeof notionPageIconSchema>
+
+export const notionPageCoverSchema = v.variant("type", [
+	notionExternalFileSchema,
+	notionHostedFileSchema,
+])
+export type NotionPageCover = v.InferOutput<typeof notionPageCoverSchema>
+
+const nullableStringSchema = v.nullable(v.string())
+
+const notionRichTextItemSchema = v.record(v.string(), v.unknown())
+export type NotionRichTextItem = v.InferOutput<typeof notionRichTextItemSchema>
+
+const notionSelectOptionInputSchema = v.union([
+	v.object({
+		id: v.string(),
+		name: v.optional(v.string()),
+		color: v.optional(v.string()),
+		description: v.optional(nullableStringSchema),
+	}),
+	v.object({
+		name: v.string(),
+		id: v.optional(v.string()),
+		color: v.optional(v.string()),
+		description: v.optional(nullableStringSchema),
+	}),
+])
+export type NotionSelectOptionInput = v.InferOutput<
+	typeof notionSelectOptionInputSchema
+>
+
+const notionDateInputSchema = v.object({
+	start: v.string(),
+	end: v.optional(nullableStringSchema),
+	time_zone: v.optional(nullableStringSchema),
+})
+export type NotionDateInput = v.InferOutput<typeof notionDateInputSchema>
+
+const notionUserInputSchema = v.union([
+	v.object({
+		object: v.optional(v.literal("user")),
+		id: v.string(),
+	}),
+	v.object({
+		object: v.literal("group"),
+		id: v.string(),
+		name: v.optional(nullableStringSchema),
+	}),
+])
+export type NotionUserInput = v.InferOutput<typeof notionUserInputSchema>
+
+const notionRelationInputSchema = v.object({ id: v.string() })
+export type NotionRelationInput = v.InferOutput<
+	typeof notionRelationInputSchema
+>
+
+const notionFileInputSchema = v.union([
+	v.object({
+		type: v.literal("external"),
+		name: v.string(),
+		external: v.object({ url: v.string() }),
+	}),
+	v.object({
+		type: v.literal("file"),
+		name: v.string(),
+		file: v.object({
+			url: v.string(),
+			expiry_time: v.optional(v.string()),
+		}),
+	}),
+])
+export type NotionFileInput = v.InferOutput<typeof notionFileInputSchema>
+
+const notionPlaceInputSchema = v.object({
+	lat: v.number(),
+	lon: v.number(),
+	name: v.optional(nullableStringSchema),
+	address: v.optional(nullableStringSchema),
+	aws_place_id: v.optional(nullableStringSchema),
+	google_place_id: v.optional(nullableStringSchema),
+})
+export type NotionPlaceInput = v.InferOutput<typeof notionPlaceInputSchema>
+
+const pagePropertyBaseSchema = {
+	id: v.string(),
+}
+
+/**
+ * A page property value.
+ */
+export const notionPagePropertyValueSchema = v.variant("type", [
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("title"),
+		title: v.array(notionRichTextItemSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("rich_text"),
+		rich_text: v.array(notionRichTextItemSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("number"),
+		number: v.nullable(v.number()),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("url"),
+		url: nullableStringSchema,
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("email"),
+		email: nullableStringSchema,
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("phone_number"),
+		phone_number: nullableStringSchema,
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("checkbox"),
+		checkbox: v.boolean(),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("select"),
+		select: v.nullable(notionSelectOptionInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("status"),
+		status: v.nullable(notionSelectOptionInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("multi_select"),
+		multi_select: v.array(notionSelectOptionInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("date"),
+		date: v.nullable(notionDateInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("people"),
+		people: v.array(notionUserInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("relation"),
+		has_more: v.optional(v.boolean()),
+		relation: v.array(notionRelationInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("files"),
+		files: v.array(notionFileInputSchema),
+	}),
+	v.object({
+		...pagePropertyBaseSchema,
+		type: v.literal("place"),
+		place: v.nullable(notionPlaceInputSchema),
+	}),
+])
+export type NotionPagePropertyValue = v.InferOutput<
+	typeof notionPagePropertyValueSchema
+>
+
+type WithOptionalPropertyId<T> = T extends { id: string }
+	? Omit<T, "id"> & { id?: string }
+	: never
+
+/**
+ * Public SDK page property write input. Keys may be raw property IDs or data-source
+ * property keys. `id` is optional because the SDK resolves the final raw property ID
+ * from the map key before sending the bridge message.
+ */
+export type NotionPagePropertyInputValue =
+	WithOptionalPropertyId<NotionPagePropertyValue>
+
+export type NotionPagePropertyInputMap = {
+	[propertyIdOrKey: string]: NotionPagePropertyInputValue
+}
+
+export const notionPagePropertyWriteMapSchema = v.record(
+	v.string(),
+	notionPagePropertyValueSchema,
+)
+export type NotionPagePropertyWriteMap = v.InferOutput<
+	typeof notionPagePropertyWriteMapSchema
+>
+
+/**
+ * The `Page` object returned in `createPageResult` messages.
+ */
+export const notionPageSchema = v.object({
+	object: v.literal("page"),
+	id: notionPageIdSchema,
+	parent: notionParentSchema,
+	properties: notionPagePropertyWriteMapSchema,
+	created_time: v.optional(v.string()),
+	last_edited_time: v.optional(v.string()),
+	icon: v.optional(notionPageIconSchema),
+	cover: v.optional(notionPageCoverSchema),
+	url: v.optional(v.string()),
+	public_url: v.optional(v.string()),
+	in_trash: v.optional(v.boolean()),
+})
+export type NotionPage = v.InferOutput<typeof notionPageSchema>

package/src/bridge/parent.ts

@@ -0,0 +1,27 @@
+import * as v from "valibot"
+import {
+	notionBlockIdSchema,
+	notionDataSourceIdSchema,
+	notionPageIdSchema,
+} from "./ids.js"
+
+export const notionParentSchema = v.variant("type", [
+	v.object({ type: v.literal("page_id"), page_id: notionPageIdSchema }),
+	v.object({
+		type: v.literal("data_source_id"),
+		data_source_id: notionDataSourceIdSchema,
+	}),
+	v.object({ type: v.literal("workspace"), workspace: v.literal(true) }),
+	v.object({ type: v.literal("block_id"), block_id: notionBlockIdSchema }),
+])
+
+/**
+ * A record's parent reference.
+ *
+ * Mirrors Notion's public API:
+ * - `page_id` — parented directly under a page.
+ * - `block_id` — parented under a non-page container block (toggle, column, callout, ...).
+ * - `data_source_id` — parented under a collection (data source).
+ * - `workspace` — top-level / team-rooted.
+ */
+export type NotionParent = v.InferOutput<typeof notionParentSchema>

package/src/bridge/pendingRequests.ts

@@ -0,0 +1,28 @@
+/**
+ * Tracks one-shot request/response pairs over the `postMessage` bridge. Each `allocate` reserves a
+ * unique `requestId` and stores its resolver. `resolve` finds the pending resolver by `requestId`
+ * and calls it, then removes the entry so the same `requestId` cannot be resolved twice.
+ */
+export class PendingRequests<T> {
+	private nextId = 1
+	private readonly entries = new Map<string, (value: T) => void>()
+
+	constructor(private readonly prefix: string) {}
+
+	allocate(resolver: (value: T) => void): string {
+		const requestId = `${this.prefix}-${this.nextId}`
+		this.nextId += 1
+		this.entries.set(requestId, resolver)
+		return requestId
+	}
+
+	resolve(requestId: string, value: T): boolean {
+		const resolver = this.entries.get(requestId)
+		if (resolver === undefined) {
+			return false
+		}
+		this.entries.delete(requestId)
+		resolver(value)
+		return true
+	}
+}

package/src/bridge/sandboxClient.ts

@@ -0,0 +1,137 @@
+import type {
+	CreatePageInput,
+	CreatePageResult,
+	GetPageResult,
+	GetUserResult,
+	ListUsersInput,
+	ListUsersResult,
+	NotionPageId,
+	NotionUserId,
+	UpdatePageInput,
+	UpdatePageResult,
+	UseDataSourceOptions,
+} from "../types.js"
+import {
+	type CustomBlockHostState,
+	type DataSourceQueryView,
+	getDataSourceQueryView as getDataSourceQueryViewWithBridge,
+} from "./hostState.js"
+import type { ManifestLoadResult } from "./loadManifest.js"
+import type { CustomBlockManifest } from "./manifest.js"
+import type { InitMessage } from "./messages/init.js"
+import { type MessageLogEntry, SandboxBridge } from "./SandboxBridge.js"
+
+export type { MessageLogEntry }
+
+const bridge = new SandboxBridge()
+
+export const customBlockHost = {
+	sendReady: (manifestResult: ManifestLoadResult) => {
+		bridge.sendReady(manifestResult)
+	},
+
+	awaitInit: (signal?: AbortSignal): Promise<InitMessage> => {
+		return bridge.awaitInit(signal)
+	},
+
+	subscribe: (listener: () => void) => {
+		return bridge.subscribe(listener)
+	},
+
+	getState: (): CustomBlockHostState => {
+		return bridge.getHostState()
+	},
+
+	getManifest: (): CustomBlockManifest | null => {
+		return bridge.getManifest()
+	},
+
+	/**
+	 * Apply an `init` payload directly, bypassing the postMessage handshake for
+	 * standalone preview state.
+	 */
+	setMockState: (message: InitMessage) => {
+		bridge.setMockState(message)
+	},
+
+	postResize: (height: number) => {
+		bridge.postResize(height)
+	},
+}
+
+export const customBlockDataSources = {
+	query: (key: string, options?: UseDataSourceOptions) => {
+		bridge.queryDataSource(key, options)
+	},
+
+	getView: (
+		hostState: CustomBlockHostState,
+		key: string,
+	): DataSourceQueryView => {
+		return getDataSourceQueryViewWithBridge(hostState, key, args =>
+			bridge.updateDataSourcePage(args),
+		)
+	},
+}
+
+export const messageLog = {
+	getSnapshot: (): readonly MessageLogEntry[] => {
+		return bridge.getMessageLog()
+	},
+
+	subscribe: (listener: () => void) => {
+		return bridge.subscribeToMessageLog(listener)
+	},
+}
+
+/**
+ * Page-related SDK APIs exposed under `sdk.pages.*`.
+ */
+export const pages = {
+	/**
+	 * Creates a new Notion page.
+	 */
+	create: (input: CreatePageInput): Promise<CreatePageResult> => {
+		return bridge.createPage(input)
+	},
+
+	/**
+	 * Fetches a page by id.
+	 */
+	get: (pageId: NotionPageId): Promise<GetPageResult> => {
+		return bridge.getPage(pageId)
+	},
+
+	/**
+	 * Updates an existing page.
+	 */
+	update: (input: UpdatePageInput): Promise<UpdatePageResult> => {
+		return bridge.updatePage(input)
+	},
+
+	/**
+	 * Soft-delete a page by archiving it.
+	 */
+	delete: (pageId: NotionPageId): Promise<UpdatePageResult> => {
+		return bridge.updatePage({ pageId, archived: true })
+	},
+}
+
+/**
+ * User-related SDK APIs exposed under `sdk.users.*`.
+ */
+export const users = {
+	/**
+	 * Lists users visible in the current custom block workspace.
+	 */
+	list: (input?: ListUsersInput): Promise<ListUsersResult> => {
+		return bridge.listUsers(input)
+	},
+
+	/**
+	 * Fetches a user by id.
+	 */
+	get: (userId: NotionUserId): Promise<GetUserResult> => {
+		return bridge.getUser(userId)
+	},
+}

package/src/bridge/theme.ts

@@ -0,0 +1,5 @@
+import * as v from "valibot"
+
+export const notionThemeSchema = v.picklist(["light", "dark"])
+
+export type NotionTheme = v.InferOutput<typeof notionThemeSchema>

package/src/bridge/users/user.ts

@@ -0,0 +1,31 @@
+import * as v from "valibot"
+
+declare const notionUserIdBrand: unique symbol
+
+export type NotionUserId = string & {
+	readonly [notionUserIdBrand]: "NotionUserId"
+}
+
+export const notionUserSchema = v.object({
+	object: v.literal("user"),
+	id: v.string(),
+	name: v.optional(v.string()),
+	avatar_url: v.nullable(v.string()),
+	type: v.literal("person"),
+	person: v.object({
+		email: v.string(),
+	}),
+})
+
+export type NotionUser = v.InferOutput<typeof notionUserSchema>
+
+export const notionUserListSchema = v.object({
+	object: v.literal("list"),
+	results: v.array(notionUserSchema),
+	next_cursor: v.nullable(v.string()),
+	has_more: v.boolean(),
+	type: v.literal("user"),
+	user: v.record(v.string(), v.unknown()),
+})
+
+export type NotionUserList = v.InferOutput<typeof notionUserListSchema>

package/src/css.d.ts

@@ -0,0 +1 @@
+declare module "*.css"

package/src/customBlock.ts

@@ -0,0 +1,102 @@
+import { autoResize } from "./autoResize.js"
+import type { NotionDataSource } from "./bridge/dataSources/dataSource.js"
+import type {
+	CustomBlockHostState,
+	InitializedHostState,
+} from "./bridge/hostState.js"
+import type { NotionBlockId } from "./bridge/ids.js"
+import type { CustomBlockManifest } from "./bridge/manifest.js"
+import type { CustomBlockPage } from "./bridge/pages/page.js"
+import type { NotionParent } from "./bridge/parent.js"
+import { customBlockHost } from "./bridge/sandboxClient.js"
+import type { NotionTheme } from "./bridge/theme.js"
+import type { NotionUser } from "./bridge/users/user.js"
+
+export type CustomBlockState =
+	| { status: "uninitialized"; theme: NotionTheme }
+	| {
+			status: "initialized"
+			theme: NotionTheme
+			blockId: NotionBlockId
+			parent: NotionParent
+			page: CustomBlockPage
+			currentUser: NotionUser
+			dataSources: NotionDataSource[]
+	  }
+
+/**
+ * Framework-neutral runtime state APIs for a custom block. Call `initCustomBlock`
+ * before reading initialized values, and use `subscribe` to react to host pushes.
+ */
+export const customBlock = {
+	subscribe(listener: () => void): () => void {
+		return customBlockHost.subscribe(listener)
+	},
+
+	getState(): CustomBlockState {
+		return toPublicState(customBlockHost.getState())
+	},
+
+	getCurrentUser(): NotionUser {
+		return getInitializedHostState("getCurrentUser").currentUser
+	},
+
+	getTheme(): NotionTheme {
+		return getInitializedHostState("getTheme").theme
+	},
+
+	getBlockId(): NotionBlockId {
+		return getInitializedHostState("getBlockId").blockId
+	},
+
+	getParent(): NotionParent {
+		return getInitializedHostState("getParent").parent
+	},
+
+	getPage(): CustomBlockPage {
+		return getInitializedHostState("getPage").page
+	},
+
+	getManifest(): CustomBlockManifest | null {
+		return customBlockHost.getManifest()
+	},
+
+	autoResize,
+}
+
+let lastHostState: CustomBlockHostState | undefined
+let lastPublicState: CustomBlockState | undefined
+
+function toPublicState(hostState: CustomBlockHostState): CustomBlockState {
+	if (hostState === lastHostState && lastPublicState !== undefined) {
+		return lastPublicState
+	}
+	lastHostState = hostState
+	if (hostState.status === "uninitialized") {
+		lastPublicState = {
+			status: "uninitialized",
+			theme: hostState.theme,
+		}
+		return lastPublicState
+	}
+	lastPublicState = {
+		status: "initialized",
+		theme: hostState.theme,
+		blockId: hostState.blockId,
+		parent: hostState.parent,
+		page: hostState.page,
+		currentUser: hostState.currentUser,
+		dataSources: hostState.dataSources,
+	}
+	return lastPublicState
+}
+
+function getInitializedHostState(methodName: string): InitializedHostState {
+	const hostState = customBlockHost.getState()
+	if (hostState.status !== "initialized") {
+		throw new Error(
+			`customBlock.${methodName} called before \`initCustomBlock\` resolved. Await it before reading runtime state.`,
+		)
+	}
+	return hostState
+}